----
url: https://docs.docker.com/reference/compose-file/services/
----

# Define services in Docker Compose

***

Table of contents

***

A service is an abstract definition of a computing resource within an application which can be scaled or replaced independently from other components. Services are backed by a set of containers, run by the platform according to replication requirements and placement constraints. As services are backed by containers, they are defined by a Docker image and set of runtime arguments. All containers within a service are identically created with these arguments.

A Compose file must declare a `services` top-level element as a map whose keys are string representations of service names, and whose values are service definitions. A service definition contains the configuration that is applied to each service container.

Each service may also include a `build` section, which defines how to create the Docker image for the service. Compose supports building Docker images using this service definition. If not used, the `build` section is ignored and the Compose file is still considered valid. Build support is an optional aspect of the Compose Specification, and is described in detail in the [Compose Build Specification](https://docs.docker.com/reference/compose-file/build/) documentation.

Each service defines runtime constraints and requirements to run its containers. The `deploy` section groups these constraints and lets the platform adjust the deployment strategy to best match containers' needs with available resources. Deploy support is an optional aspect of the Compose Specification, and is described in detail in the [Compose Deploy Specification](https://docs.docker.com/reference/compose-file/deploy/) documentation. If not implemented the `deploy` section is ignored and the Compose file is still considered valid.

## [Examples](#examples)

### [Simple example](#simple-example)

The following example demonstrates how to define two simple services, set their images, map ports, and configure basic environment variables using Docker Compose.

```yaml
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"

  db:
    image: postgres:18
    environment:
      POSTGRES_USER: example
      POSTGRES_DB: exampledb
```

### [Advanced example](#advanced-example)

In the following example, the `proxy` service uses the Nginx image, mounts a local Nginx configuration file into the container, exposes port `80` and depends on the `backend` service.

The `backend` service builds an image from the Dockerfile located in the `backend` directory that is set to build at stage `builder`.

```yaml
services:
  proxy:
    image: nginx
    volumes:
      - type: bind
        source: ./proxy/nginx.conf
        target: /etc/nginx/conf.d/default.conf
        read_only: true
    ports:
      - 80:80
    depends_on:
      - backend

  backend:
    build:
      context: backend
      target: builder
```

For more example Compose files, explore the [Awesome Compose samples](https://github.com/docker/awesome-compose).

## [Attributes](#attributes)

### [`annotations`](#annotations)

`annotations` defines annotations for the container. `annotations` can use either an array or a map.

```yml
annotations:
  com.example.foo: bar
```

```yml
annotations:
  - com.example.foo=bar
```

### [`attach`](#attach)

Requires: Docker Compose [2.20.0](https://github.com/docker/compose/releases/tag/v2.20.0) and later

When `attach` is defined and set to `false` Compose does not collect service logs, until you explicitly request it to.

The default service configuration is `attach: true`.

### [`build`](#build)

`build` specifies the build configuration for creating a container image from source, as defined in the [Compose Build Specification](https://docs.docker.com/reference/compose-file/build/).

### [`blkio_config`](#blkio_config)

`blkio_config` defines a set of configuration options to set block I/O limits for a service.

```yml
services:
  foo:
    image: busybox
    blkio_config:
       weight: 300
       weight_device:
         - path: /dev/sda
           weight: 400
       device_read_bps:
         - path: /dev/sdb
           rate: '12mb'
       device_read_iops:
         - path: /dev/sdb
           rate: 120
       device_write_bps:
         - path: /dev/sdb
           rate: '1024k'
       device_write_iops:
         - path: /dev/sdb
           rate: 30
```

#### [`device_read_bps`, `device_write_bps`](#device_read_bps-device_write_bps)

Set a limit in bytes per second for read / write operations on a given device. Each item in the list must have two keys:

* `path`: Defines the symbolic path to the affected device.
* `rate`: Either as an integer value representing the number of bytes or as a string expressing a byte value.

#### [`device_read_iops`, `device_write_iops`](#device_read_iops-device_write_iops)

Set a limit in operations per second for read / write operations on a given device. Each item in the list must have two keys:

* `path`: Defines the symbolic path to the affected device.
* `rate`: As an integer value representing the permitted number of operations per second.

#### [`weight`](#weight)

Modify the proportion of bandwidth allocated to a service relative to other services. Takes an integer value between 10 and 1000, with 500 being the default.

#### [`weight_device`](#weight_device)

Fine-tune bandwidth allocation by device. Each item in the list must have two keys:

* `path`: Defines the symbolic path to the affected device.
* `weight`: An integer value between 10 and 1000.

### [`cpu_count`](#cpu_count)

`cpu_count` defines the number of usable CPUs for service container.

### [`cpu_percent`](#cpu_percent)

`cpu_percent` defines the usable percentage of the available CPUs.

### [`cpu_shares`](#cpu_shares)

`cpu_shares` defines, as integer value, a service container's relative CPU weight versus other containers.

### [`cpu_period`](#cpu_period)

`cpu_period` configures CPU CFS (Completely Fair Scheduler) period when a platform is based on Linux kernel.

### [`cpu_quota`](#cpu_quota)

`cpu_quota` configures CPU CFS (Completely Fair Scheduler) quota when a platform is based on Linux kernel.

### [`cpu_rt_runtime`](#cpu_rt_runtime)

`cpu_rt_runtime` configures CPU allocation parameters for platforms with support for real-time scheduler. It can be either an integer value using microseconds as unit or a [duration](https://docs.docker.com/reference/compose-file/extension/#specifying-durations).

```yml
 cpu_rt_runtime: '400ms'
 cpu_rt_runtime: '95000'
```

### [`cpu_rt_period`](#cpu_rt_period)

`cpu_rt_period` configures CPU allocation parameters for platforms with support for real-time scheduler. It can be either an integer value using microseconds as unit or a [duration](https://docs.docker.com/reference/compose-file/extension/#specifying-durations).

```yml
 cpu_rt_period: '1400us'
 cpu_rt_period: '11000'
```

### [`cpus`](#cpus)

`cpus` define the number of (potentially virtual) CPUs to allocate to service containers. This is a fractional number. `0.000` means no limit.

When set, `cpus` must be consistent with the `cpus` attribute in the [Deploy Specification](https://docs.docker.com/reference/compose-file/deploy/#cpus).

### [`cpuset`](#cpuset)

`cpuset` defines the explicit CPUs in which to permit execution. Can be a range `0-3` or a list `0,1`

### [`cap_add`](#cap_add)

`cap_add` specifies additional container [capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) as strings.

```yaml
cap_add:
  - ALL
```

### [`cap_drop`](#cap_drop)

`cap_drop` specifies container [capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) to drop as strings.

```yaml
cap_drop:
  - NET_ADMIN
  - SYS_ADMIN
```

### [`cgroup`](#cgroup)

Requires: Docker Compose [2.15.0](https://github.com/docker/compose/releases/tag/v2.15.0) and later

`cgroup` specifies the cgroup namespace to join. When unset, it is the container runtime's decision to select which cgroup namespace to use, if supported.

* `host`: Runs the container in the Container runtime cgroup namespace.
* `private`: Runs the container in its own private cgroup namespace.

### [`cgroup_parent`](#cgroup_parent)

`cgroup_parent` specifies an optional parent [cgroup](https://man7.org/linux/man-pages/man7/cgroups.7.html) for the container.

```yaml
cgroup_parent: m-executor-abcd
```

### [`command`](#command)

`command` overrides the default command declared by the container image, for example by Dockerfile's `CMD`.

```yaml
command: bundle exec thin -p 3000
```

If the value is `null`, the default command from the image is used.

If the value is `[]` (empty list) or `''` (empty string), the default command declared by the image is ignored, or in other words overridden to be empty.

> Note
>
> Unlike the `CMD` instruction in a Dockerfile, the `command` field doesn't automatically run within the context of the [`SHELL`](https://docs.docker.com/reference/dockerfile/#shell-form) instruction defined in the image. If your `command` relies on shell-specific features, such as environment variable expansion, you need to explicitly run it within a shell. For example:
>
> ```yaml
> command: /bin/sh -c 'echo "hello $$HOSTNAME"'
> ```

The value can also be a list, similar to the [exec-form syntax](https://docs.docker.com/reference/dockerfile/#exec-form) used by the [Dockerfile](https://docs.docker.com/reference/dockerfile/#exec-form).

### [`configs`](#configs)

`configs` let services adapt their behaviour without the need to rebuild a Docker image. Services can only access configs when explicitly granted by the `configs` attribute. Two different syntax variants are supported.

Compose reports an error if `config` doesn't exist on the platform or isn't defined in the [`configs` top-level element](https://docs.docker.com/reference/compose-file/configs/) in the Compose file.

There are two syntaxes defined for configs: a short syntax and a long syntax.

You can grant a service access to multiple configs, and you can mix long and short syntax.

#### [Short syntax](#short-syntax)

The short syntax variant only specifies the config name. This grants the container access to the config and mounts it as files into a service’s container’s filesystem. The location of the mount point within the container defaults to `/<config_name>` in Linux containers, and `C:\<config-name>` in Windows containers.

The following example uses the short syntax to grant the `redis` service access to the `my_config` and `my_other_config` configs. The value of `my_config` is set to the contents of the file `./my_config.txt`, and `my_other_config` is defined as an external resource, which means that it has already been defined in the platform. If the external config does not exist, the deployment fails.

```yml
services:
  redis:
    image: redis:latest
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true
```

#### [Long syntax](#long-syntax)

The long syntax provides more granularity in how the config is created within the service's task containers.

* `source`: The name of the config as it exists in the platform.
* `target`: The path and name of the file to be mounted in the service's task containers. Defaults to `/<source>` if not specified.
* `uid` and `gid`: The numeric uid or gid that owns the mounted config file within the service's task containers.
* `mode`: The [permissions](https://wintelguy.com/permissions-calc.pl) for the file that is mounted within the service's task containers, in octal notation. Default value is world-readable (`0444`). Writable bit must be ignored. The executable bit can be set.

The following example sets the name of `my_config` to `redis_config` within the container, sets the mode to `0440` (group-readable) and sets the user and group to `103`. The `redis` service does not have access to the `my_other_config` config.

```yml
services:
  redis:
    image: redis:latest
    configs:
      - source: my_config
        target: /redis_config
        uid: "103"
        gid: "103"
        mode: 0440
configs:
  my_config:
    external: true
  my_other_config:
    external: true
```

### [`container_name`](#container_name)

`container_name` is a string that specifies a custom container name, rather than a name generated by default.

```yml
container_name: my-web-container
```

Compose does not scale a service beyond one container if the Compose file specifies a `container_name`. Attempting to do so results in an error.

`container_name` follows the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+`

### [`credential_spec`](#credential_spec)

`credential_spec` configures the credential spec for a managed service account.

If you have services that use Windows containers, you can use `file:` and `registry:` protocols for `credential_spec`. Compose also supports additional protocols for custom use-cases.

The `credential_spec` must be in the format `file://<filename>` or `registry://<value-name>`.

```yml
credential_spec:
  file: my-credential-spec.json
```

When using `registry:`, the credential spec is read from the Windows registry on the daemon's host. A registry value with the given name must be located in:

```bash
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs
```

The following example loads the credential spec from a value named `my-credential-spec` in the registry:

```yml
credential_spec:
  registry: my-credential-spec
```

#### [Example gMSA configuration](#example-gmsa-configuration)

When configuring a gMSA credential spec for a service, you only need to specify a credential spec with `config`, as shown in the following example:

```yml
services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json
```

### [`depends_on`](#depends_on)

With the `depends_on` attribute, you can control the order of service startup and shutdown. It is useful if services are closely coupled, and the startup sequence impacts the application's functionality.

#### [Short syntax](#short-syntax-1)

The short syntax variant only specifies service names of the dependencies. Service dependencies cause the following behaviors:

* Compose creates services in dependency order. In the following example, `db` and `redis` are created before `web`.

* Compose removes services in dependency order. In the following example, `web` is removed before `db` and `redis`.

Simple example:

```yml
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres:18
```

Compose guarantees dependency services have been started before starting a dependent service. With short syntax, Compose does not wait for dependency services to be "healthy" before starting a dependent service.

#### [Long syntax](#long-syntax-1)

The long form syntax enables the configuration of additional fields that can't be expressed in the short form.

* `restart`: When set to `true` Compose restarts this service after it updates the dependency service. This applies to an explicit restart controlled by a Compose operation, and excludes automated restart by the container runtime after the container dies. Introduced in Docker Compose version [2.17.0](https://github.com/docker/compose/releases/tag/v2.17.0).

* `condition`: Sets the condition under which dependency is considered satisfied

  * `service_started`: An equivalent of the short syntax described previously
  * `service_healthy`: Specifies that a dependency is expected to be "healthy" (as indicated by [`healthcheck`](#healthcheck)) before starting a dependent service.
  * `service_completed_successfully`: Specifies that a dependency is expected to run to successful completion before starting a dependent service.

* `required`: When set to `false` Compose only warns you when the dependency service isn't started or available. If it's not defined the default value of `required` is `true`. Introduced in Docker Compose version [2.20.0](https://github.com/docker/compose/releases/tag/v2.20.0).

Service dependencies cause the following behaviors:

* Compose creates services in dependency order. In the following example, `db` and `redis` are created before `web`.

* Compose waits for healthchecks to pass on dependencies marked with `service_healthy`. In the following example, `db` is expected to be "healthy" before `web` is created.

* Compose removes services in dependency order. In the following example, `web` is removed before `db` and `redis`.

```yml
services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres:18
```

Compose guarantees dependency services are started before starting a dependent service. Compose guarantees dependency services marked with `service_healthy` are "healthy" before starting a dependent service.

### [`deploy`](#deploy)

`deploy` specifies the configuration for the deployment and lifecycle of services, as defined [in the Compose Deploy Specification](https://docs.docker.com/reference/compose-file/deploy/).

### [`develop`](#develop)

Requires: Docker Compose [2.22.0](https://github.com/docker/compose/releases/tag/v2.22.0) and later

`develop` specifies the development configuration for maintaining a container in sync with source, as defined in the [Development Section](https://docs.docker.com/reference/compose-file/develop/).

### [`device_cgroup_rules`](#device_cgroup_rules)

`device_cgroup_rules` defines a list of device cgroup rules for this container. The format is the same format the Linux kernel specifies in the [Control Groups Device Whitelist Controller](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html).

```yml
device_cgroup_rules:
  - 'c 1:3 mr'
  - 'a 7:* rmw'
```

### [`devices`](#devices)

`devices` defines a list of device mappings for created containers in the form of `HOST_PATH:CONTAINER_PATH[:CGROUP_PERMISSIONS]`.

```yml
devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
  - "/dev/sda:/dev/xvda:rwm"
```

`devices` can also rely on the [CDI](https://github.com/cncf-tags/container-device-interface) syntax to let the container runtime select a device:

```yml
devices:
  - "vendor1.com/device=gpu"
```

### [`dns`](#dns)

`dns` defines custom DNS servers to set on the container network interface configuration. It can be a single value or a list.

```yml
dns: 8.8.8.8
```

```yml
dns:
  - 8.8.8.8
  - 9.9.9.9
```

### [`dns_opt`](#dns_opt)

`dns_opt` list custom DNS options to be passed to the container’s DNS resolver (`/etc/resolv.conf` file on Linux).

```yml
dns_opt:
  - use-vc
  - no-tld-query
```

### [`dns_search`](#dns_search)

`dns_search` defines custom DNS search domains to set on container network interface configuration. It can be a single value or a list.

```yml
dns_search: example.com
```

```yml
dns_search:
  - dc1.example.com
  - dc2.example.com
```

### [`domainname`](#domainname)

`domainname` declares a custom domain name to use for the service container. It must be a valid RFC 1123 hostname.

### [`driver_opts`](#driver_opts)

Requires: Docker Compose [2.27.1](https://github.com/docker/compose/releases/tag/v2.27.1) and later

`driver_opts` specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent.

```yml
services:
  app:
    networks:
      app_net:
        driver_opts:
          com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"
```

Consult the [network drivers documentation](https://docs.docker.com/engine/network/) for more information.

### [`entrypoint`](#entrypoint)

`entrypoint` declares the default entrypoint for the service container. This overrides the `ENTRYPOINT` instruction from the service's Dockerfile.

If `entrypoint` is non-null, Compose ignores any default command from the image, for example the `CMD` instruction in the Dockerfile.

See also [`command`](#command) to set or override the default command to be executed by the entrypoint process.

In its short form, the value can be defined as a string:

```yml
entrypoint: /code/entrypoint.sh
```

Alternatively, the value can also be a list, in a manner similar to the [Dockerfile](https://docs.docker.com/reference/dockerfile/#cmd):

```yml
entrypoint:
  - php
  - -d
  - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
  - -d
  - memory_limit=-1
  - vendor/bin/phpunit
```

If the value is `null`, the default entrypoint from the image is used.

If the value is `[]` (empty list) or `''` (empty string), the default entrypoint declared by the image is ignored, or in other words, overridden to be empty.

### [`env_file`](#env_file)

The `env_file` attribute is used to specify one or more files that contain environment variables to be passed to the containers.

```yml
env_file: .env
```

Relative paths are resolved from the Compose file's parent folder. As absolute paths prevent the Compose file from being portable, Compose warns you when such a path is used to set `env_file`.

Environment variables declared in the [`environment`](#environment) section override these values. This holds true even if those values are empty or undefined.

`env_file` can also be a list. The files in the list are processed from the top down. For the same variable specified in two environment files, the value from the last file in the list stands.

```yml
env_file:
  - ./a.env
  - ./b.env
```

List elements can also be declared as a mapping, which then lets you set additional attributes.

#### [`required`](#required)

Requires: Docker Compose [2.24.0](https://github.com/docker/compose/releases/tag/v2.24.0) and later

The `required` attribute defaults to `true`. When `required` is set to `false` and the `.env` file is missing, Compose silently ignores the entry.

```yml
env_file:
  - path: ./default.env
    required: true # default
  - path: ./override.env
    required: false
```

#### [`format`](#format)

Requires: Docker Compose [2.30.0](https://github.com/docker/compose/releases/tag/v2.30.0) and later

The `format` attribute lets you use an alternative file format for the `env_file`. When not set, `env_file` is parsed according to the Compose rules outlined in [`Env_file` format](#env_file-format).

`raw` format lets you use an `env_file` with key=value items, but without any attempt from Compose to parse the value for interpolation. This let you pass values as-is, including quotes and `$` signs.

```yml
env_file:
  - path: ./default.env
    format: raw
```

#### [`Env_file` format](#env_file-format)

Each line in an `.env` file must be in `VAR[=[VAL]]` format. The following syntax rules apply:

* Lines beginning with `#` are processed as comments and ignored.

* Blank lines are ignored.

* Unquoted and double-quoted (`"`) values have [Interpolation](https://docs.docker.com/reference/compose-file/interpolation/) applied.

`VAL` may be omitted, in such cases the variable value is an empty string. `=VAL` may be omitted, in such cases the variable is unset.

```bash
# Set Rails/Rack environment
RACK_ENV=development
VAR="quoted"
```

### [`environment`](#environment)

The `environment` attribute defines environment variables set in the container. `environment` can use either an array or a map. Any boolean values; true, false, yes, no, should be enclosed in quotes to ensure they are not converted to True or False by the YAML parser.

Environment variables can be declared by a single key (no value to equals sign). In this case Compose relies on you to resolve the value. If the value is not resolved, the variable is unset and is removed from the service container environment.

Map syntax:

```yml
environment:
  RACK_ENV: development
  SHOW: "true"
  USER_INPUT:
```

Array syntax:

```yml
environment:
  - RACK_ENV=development
  - SHOW=true
  - USER_INPUT
```

When both `env_file` and `environment` are set for a service, values set by `environment` have precedence.

### [`expose`](#expose)

`expose` defines the (incoming) port or a range of ports that Compose exposes from the container. These ports must be accessible to linked services and should not be published to the host machine. Only the internal container ports can be specified.

Syntax is `<portnum>/[<proto>]` or `<startport-endport>/[<proto>]` for a port range. When not explicitly set, `tcp` protocol is used.

```yml
expose:
  - "3000"
  - "8000"
  - "8080-8085/tcp"
```

> Note
>
> If the Dockerfile for the image already exposes ports, it is visible to other containers on the network even if `expose` is not set in your Compose file.

### [`extends`](#extends)

`extends` lets you share common configurations among different files, or even different projects entirely. With `extends` you can define a common set of service options in one place and refer to it from anywhere. You can refer to another Compose file and select a service you want to also use in your own application, with the ability to override some attributes for your own needs.

You can use `extends` on any service together with other configuration keys. The `extends` value must be a mapping defined with a required `service` and an optional `file` key.

```yaml
extends:
  file: common.yml
  service: webapp
```

* `service`: Defines the name of the service being referenced as a base, for example `web` or `database`.
* `file`: The location of a Compose configuration file defining that service.

`extends` is not supported when deploying with `docker stack deploy`.

#### [Restrictions](#restrictions)

When a service is referenced using `extends`, it can declare dependencies on other resources. These dependencies may be explicitly defined through attributes like `volumes`, `networks`, `configs`, `secrets`, `links`, `volumes_from`, or `depends_on`. Alternatively, dependencies can reference another service using the `service:{name}` syntax in namespace declarations such as `ipc`, `pid`, or `network_mode`.

Compose does not automatically import these referenced resources into the extended model. It is your responsibility to ensure all required resources are explicitly declared in the model that relies on extends.

Circular references with `extends` are not supported, Compose returns an error when one is detected.

#### [Finding referenced service](#finding-referenced-service)

`file` value can be:

* Not present. This indicates that another service within the same Compose file is being referenced.

* File path, which can be either:

  * Relative path. This path is considered as relative to the location of the main Compose file.
  * Absolute path.

A service denoted by `service` must be present in the identified referenced Compose file. Compose returns an error if:

* The service denoted by `service` is not found.
* The Compose file denoted by `file` is not found.

#### [Merging service definitions](#merging-service-definitions)

Two service definitions, the main one in the current Compose file and the referenced one specified by `extends`, are merged in the following way:

* Mappings: Keys in mappings of the main service definition override keys in mappings of the referenced service definition. Keys that aren't overridden are included as is.
* Sequences: Items are combined together into a new sequence. The order of elements is preserved with the referenced items coming first and main items after.
* Scalars: Keys in the main service definition take precedence over keys in the referenced one.

##### [Mappings](#mappings)

The following keys should be treated as mappings: `annotations`, `build.args`, `build.labels`, `build.extra_hosts`, `deploy.labels`, `deploy.update_config`, `deploy.rollback_config`, `deploy.restart_policy`, `deploy.resources.limits`, `environment`, `healthcheck`, `labels`, `logging.options`, `sysctls`, `storage_opt`, `extra_hosts`, `ulimits`.

One exception that applies to `healthcheck` is that the main mapping cannot specify `disable: true` unless the referenced mapping also specifies `disable: true`. Compose returns an error in this case. For example, the following input:

```yaml
services:
  common:
    image: busybox
    environment:
      TZ: utc
      PORT: 80
  cli:
    extends:
      service: common
    environment:
      PORT: 8080
```

Produces the following configuration for the `cli` service. The same output is produced if array syntax is used.

```yaml
environment:
  PORT: 8080
  TZ: utc
image: busybox
```

Items under `blkio_config.device_read_bps`, `blkio_config.device_read_iops`, `blkio_config.device_write_bps`, `blkio_config.device_write_iops`, `devices` and `volumes` are also treated as mappings where key is the target path inside the container.

For example, the following input:

```yaml
services:
  common:
    image: busybox
    volumes:
      - common-volume:/var/lib/backup/data:rw
  cli:
    extends:
      service: common
    volumes:
      - cli-volume:/var/lib/backup/data:ro
```

Produces the following configuration for the `cli` service. Note that the mounted path now points to the new volume name and `ro` flag was applied.

```yaml
image: busybox
volumes:
- cli-volume:/var/lib/backup/data:ro
```

If the referenced service definition contains `extends` mapping, the items under it are simply copied into the new merged definition. The merging process is then kicked off again until no `extends` keys are remaining.

For example, the following input:

```yaml
services:
  base:
    image: busybox
    user: root
  common:
    image: busybox
    extends:
      service: base
  cli:
    extends:
      service: common
```

Produces the following configuration for the `cli` service. Here, `cli` services gets `user` key from `common` service, which in turn gets this key from `base` service.

```yaml
image: busybox
user: root
```

##### [Sequences](#sequences)

The following keys should be treated as sequences: `cap_add`, `cap_drop`, `configs`, `deploy.placement.constraints`, `deploy.placement.preferences`, `deploy.reservations.generic_resources`, `device_cgroup_rules`, `expose`, `external_links`, `ports`, `secrets`, `security_opt`. Any duplicates resulting from the merge are removed so that the sequence only contains unique elements.

For example, the following input:

```yaml
services:
  common:
    image: busybox
    security_opt:
      - label=role:ROLE
  cli:
    extends:
      service: common
    security_opt:
      - label=user:USER
```

Produces the following configuration for the `cli` service.

```yaml
image: busybox
security_opt:
- label=role:ROLE
- label=user:USER
```

In case list syntax is used, the following keys should also be treated as sequences: `dns`, `dns_search`, `env_file`, `tmpfs`. Unlike sequence fields mentioned previously, duplicates resulting from the merge are not removed.

##### [Scalars](#scalars)

Any other allowed keys in the service definition should be treated as scalars.

### [`external_links`](#external_links)

`external_links` link service containers to services managed outside of your Compose application. `external_links` define the name of an existing service to retrieve using the platform lookup mechanism. An alias of the form `SERVICE:ALIAS` can be specified.

```yml
external_links:
  - redis
  - database:mysql
  - database:postgresql
```

### [`extra_hosts`](#extra_hosts)

`extra_hosts` adds hostname mappings to the container network interface configuration (`/etc/hosts` for Linux).

#### [Short syntax](#short-syntax-2)

Short syntax uses plain strings in a list. Values must set hostname and IP address for additional hosts in the form of `HOSTNAME=IP`.

```yml
extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"
```

IPv6 addresses can be enclosed in square brackets, for example:

```yml
extra_hosts:
  - "myhostv6=[::1]"
```

The separator `=` is preferred, but `:` can also be used. Introduced in Docker Compose version [2.24.1](https://github.com/docker/compose/releases/tag/v2.24.1). For example:

```yml
extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"
```

#### [Long syntax](#long-syntax-2)

Alternatively, `extra_hosts` can be set as a mapping between hostname(s) and IP(s)

```yml
extra_hosts:
  somehost: "162.242.195.82"
  otherhost: "50.31.209.229"
  myhostv6: "::1"
```

Compose creates a matching entry with the IP address and hostname in the container's network configuration, which means for Linux `/etc/hosts` get extra lines:

```console
162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6
```

### [`gpus`](#gpus)

Requires: Docker Compose [2.30.0](https://github.com/docker/compose/releases/tag/v2.30.0) and later

`gpus` specifies GPU devices to be allocated for container usage. This is equivalent to a [device request](https://docs.docker.com/reference/compose-file/deploy/#devices) with an implicit `gpu` capability.

```yaml
services:
  model:
    gpus:
      - driver: 3dfx
        count: 2
```

`gpus` also can be set as string `all` to allocate all available GPU devices to the container.

```yaml
services:
  model:
    gpus: all
```

### [`group_add`](#group_add)

`group_add` specifies additional groups, by name or number, which the user inside the container must be a member of.

An example of where this is useful is when multiple containers (running as different users) need to all read or write the same file on a shared volume. That file can be owned by a group shared by all the containers, and specified in `group_add`.

```yml
services:
  myservice:
    image: alpine
    group_add:
      - mail
```

Running `id` inside the created container must show that the user belongs to the `mail` group, which would not have been the case if `group_add` were not declared.

### [`healthcheck`](#healthcheck)

The `healthcheck` attribute declares a check that's run to determine whether or not the service containers are "healthy". It works in the same way, and has the same default values, as the HEALTHCHECK Dockerfile instruction set by the service's Docker image. Your Compose file can override the values set in the Dockerfile.

For more information on `HEALTHCHECK`, see the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/#healthcheck).

```yml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s
  start_interval: 5s
```

`interval`, `timeout`, `start_period`, and `start_interval` are [specified as durations](https://docs.docker.com/reference/compose-file/extension/#specifying-durations). Introduced in Docker Compose version [2.20.2](https://github.com/docker/compose/releases/tag/v2.20.2)

`test` defines the command Compose runs to check container health. It can be either a string or a list. If it's a list, the first item must be either `NONE`, `CMD` or `CMD-SHELL`. If it's a string, it's equivalent to specifying `CMD-SHELL` followed by that string.

```yml
# Hit the local web app
test: ["CMD", "curl", "-f", "http://localhost"]
```

Using `CMD-SHELL` runs the command configured as a string using the container's default shell (`/bin/sh` for Linux). Both of the following forms are equivalent:

```yml
test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
```

```yml
test: curl -f https://localhost || exit 1
```

`NONE` disables the healthcheck, and is mostly useful to disable the Healthcheck Dockerfile instruction set by the service's Docker image. Alternatively, the healthcheck set by the image can be disabled by setting `disable: true`:

```yml
healthcheck:
  disable: true
```

### [`hostname`](#hostname)

`hostname` declares a custom host name to use for the service container. It must be a valid RFC 1123 hostname.

### [`image`](#image)

`image` specifies the image to start the container from. `image` must follow the Open Container Specification [addressable image format](https://github.com/opencontainers/org/blob/master/docs/docs/introduction/digests.md), as `[<registry>/][<project>/]<image>[:<tag>|@<digest>]`.

```yml
    image: redis
    image: redis:5
    image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
    image: library/redis
    image: docker.io/library/redis
    image: my_private.registry:5000/redis
```

If the image does not exist on the platform, Compose attempts to pull it based on the `pull_policy`. If you are also using the [Compose Build Specification](https://docs.docker.com/reference/compose-file/build/), there are alternative options for controlling the precedence of pull over building the image from source, however pulling the image is the default behavior.

`image` may be omitted from a Compose file as long as a `build` section is declared. If you are not using the Compose Build Specification, Compose won't work if `image` is missing from the Compose file.

### [`init`](#init)

`init` runs an init process (PID 1) inside the container that forwards signals and reaps processes. Set this option to `true` to enable this feature for the service.

```yml
services:
  web:
    image: alpine:latest
    init: true
```

The init binary that is used is platform specific.

### [`ipc`](#ipc)

`ipc` configures the IPC isolation mode set by the service container.

* `shareable`: Gives the container its own private IPC namespace, with a possibility to share it with other containers.
* `service:{name}`: Makes the container join another container's (`shareable`) IPC namespace.

```yml
    ipc: "shareable"
    ipc: "service:[service name]"
```

### [`isolation`](#isolation)

`isolation` specifies a container’s isolation technology. Supported values are platform specific.

### [`labels`](#labels)

`labels` add metadata to containers. You can use either an array or a map.

It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.

```yml
labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""
```

```yml
labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"
```

Compose creates containers with canonical labels:

* `com.docker.compose.project` set on all resources created by Compose to the user project name
* `com.docker.compose.service` set on service containers with service name as defined in the Compose file

The `com.docker.compose` label prefix is reserved. Specifying labels with this prefix in the Compose file results in a runtime error.

### [`label_file`](#label_file)

Requires: Docker Compose [2.32.2](https://github.com/docker/compose/releases/tag/v2.32.2) and later

The `label_file` attribute lets you load labels for a service from an external file or a list of files. This provides a convenient way to manage multiple labels without cluttering the Compose file.

The file uses a key-value format, similar to `env_file`. You can specify multiple files as a list. When using multiple files, they are processed in the order they appear in the list. If the same label is defined in multiple files, the value from the last file in the list overrides earlier ones.

```yaml
services:
  one:
    label_file: ./app.labels

  two:
    label_file:
      - ./app.labels
      - ./additional.labels
```

If a label is defined in both the `label_file` and the `labels` attribute, the value in [labels](#labels) takes precedence.

### [`links`](#links)

`links` defines a network link to containers in another service. Either specify both the service name and a link alias (`SERVICE:ALIAS`), or just the service name.

```yml
web:
  links:
    - db
    - db:database
    - redis
```

Containers for the linked service are reachable at a hostname identical to the alias, or the service name if no alias is specified.

Links are not required to enable services to communicate. When no specific network configuration is set, any service is able to reach any other service at that service’s name on the `default` network. If services specify the networks they are attached to, `links` does not override the network configuration. Services that are not connected to a shared network are not be able to communicate with each other. Compose doesn't warn you about a configuration mismatch.

Links also express implicit dependency between services in the same way as [`depends_on`](#depends_on), so they determine the order of service startup.

### [`logging`](#logging)

`logging` defines the logging configuration for the service.

```yml
logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"
```

The `driver` name specifies a logging driver for the service's containers. The default and available values are platform specific. Driver specific options can be set with `options` as key-value pairs.

### [`mac_address`](#mac_address)

> Available with Docker Compose version 2.24.0 and later.

`mac_address` sets a Mac address for the service container.

> Note
>
> Container runtimes might reject this value, for example Docker Engine >= v25.0. In that case, you should use [networks.mac\_address](#mac_address) instead.

### [`mem_limit`](#mem_limit)

`mem_limit` configures a limit on the amount of memory a container can allocate, set as a string expressing a [byte value](https://docs.docker.com/reference/compose-file/extension/#specifying-byte-values).

When set, `mem_limit` must be consistent with the `limits.memory` attribute in the [Deploy Specification](https://docs.docker.com/reference/compose-file/deploy/#memory).

### [`mem_reservation`](#mem_reservation)

`mem_reservation` configures a reservation on the amount of memory a container can allocate, set as a string expressing a [byte value](https://docs.docker.com/reference/compose-file/extension/#specifying-byte-values).

When set, `mem_reservation` must be consistent with the `reservations.memory` attribute in the [Deploy Specification](https://docs.docker.com/reference/compose-file/deploy/#memory).

### [`mem_swappiness`](#mem_swappiness)

`mem_swappiness` defines as a percentage, a value between 0 and 100, for the host kernel to swap out anonymous memory pages used by a container.

* `0`: Turns off anonymous page swapping.
* `100`: Sets all anonymous pages as swappable.

The default value is platform specific.

### [`memswap_limit`](#memswap_limit)

`memswap_limit` defines the amount of memory the container is allowed to swap to disk. This is a modifier attribute that only has meaning if [`memory`](https://docs.docker.com/reference/compose-file/deploy/#memory) is also set. Using swap lets the container write excess memory requirements to disk when the container has exhausted all the memory that is available to it. There is a performance penalty for applications that swap memory to disk often.

* If `memswap_limit` is set to a positive integer, then both `memory` and `memswap_limit` must be set. `memswap_limit` represents the total amount of memory and swap that can be used, and `memory` controls the amount used by non-swap memory. So if `memory`="300m" and `memswap_limit`="1g", the container can use 300m of memory and 700m (1g - 300m) swap.
* If `memswap_limit` is set to 0, the setting is ignored, and the value is treated as unset.
* If `memswap_limit` is set to the same value as `memory`, and `memory` is set to a positive integer, the container does not have access to swap.
* If `memswap_limit` is unset, and `memory` is set, the container can use as much swap as the `memory` setting, if the host container has swap memory configured. For instance, if `memory`="300m" and `memswap_limit` is not set, the container can use 600m in total of memory and swap.
* If `memswap_limit` is explicitly set to -1, the container is allowed to use unlimited swap, up to the amount available on the host system.

### [`models`](#models)

Requires: Docker Compose [2.38.0](https://github.com/docker/compose/releases/tag/v2.38.0) and later

`models` defines which AI models the service should use at runtime. Each referenced model must be defined under the [`models` top-level element](https://docs.docker.com/reference/compose-file/models/).

```yaml
services:
  short_syntax:
    image: app
    models:
      - my_model
  long_syntax:
    image: app
    models:
      my_model:
        endpoint_var: MODEL_URL
        model_var: MODEL
```

When a service is linked to a model, Docker Compose injects environment variables to pass connection details and model identifiers to the container. This allows the application to locate and communicate with the model dynamically at runtime, without hard-coding values.

#### [Long syntax](#long-syntax-3)

The long syntax gives you more control over the environment variable names.

* `endpoint_var` sets the name of the environment variable that holds the model runner’s URL.
* `model_var` sets the name of the environment variable that holds the model identifier.

If either is omitted, Compose automatically generates the environment variable names based on the model key using the following rules:

* Convert the model key to uppercase
* Replace any '-' characters with '\_'
* Append `_URL` for the endpoint variable

### [`network_mode`](#network_mode)

`network_mode` sets a service container's network mode.

* `bridge`: Connects the container to Docker's default bridge network instead of a project-specific network. Containers on the default bridge network cannot resolve each other by service name . Instead, use a user-defined network for DNS resolution.
* `none`: Turns off all container networking.
* `host`: Gives the container raw access to the host's network interface.
* `service:{name}`: Gives the container access to the specified container by referring to its service name.
* `container:{name}`: Gives the container access to the specified container by referring to its container ID.

For more information container networks, see the [Docker Engine documentation](https://docs.docker.com/engine/network/#container-networks).

```yml
    network_mode: "bridge"
    network_mode: "host"
    network_mode: "none"
    network_mode: "service:[service name]"
```

When set, the [`networks`](#networks) attribute is not allowed and Compose rejects any Compose file containing both attributes.

### [`networks`](#networks)

The `networks` attribute defines the networks that service containers are attached to, referencing entries under the `networks` top-level element. The `networks` attribute helps manage the networking aspects of containers, providing control over how services are segmented and interact within the Docker environment. This is used to specify which networks the containers for that service should connect to. This is important for defining how containers communicate with each other and externally.

```yml
services:
  some-service:
    networks:
      - some-network
      - other-network
```

For more information about the `networks` top-level element, see [Networks](https://docs.docker.com/reference/compose-file/networks/).

#### [Implicit default network](#implicit-default-network)

If `networks` is empty or absent from the Compose file, Compose considers an implicit definition for the service to be connected to the `default` network:

```yml
services:
  some-service:
    image: foo
```

This example is actually equivalent to:

```yml
services:
  some-service:
    image: foo
    networks:
      default: {}
```

If you want the service to not be connected a network, you must set [`network_mode: none`](#network_mode).

#### [`aliases`](#aliases)

`aliases` declares alternative hostnames for the service on the network. Other containers on the same network can use either the service name or an alias to connect to one of the service's containers.

Since `aliases` are network-scoped, the same service can have different aliases on different networks.

> Note
>
> A network-wide alias can be shared by multiple containers, and even by multiple services. If it is, then exactly which container the name resolves to is not guaranteed.

```yml
services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2
```

In the following example, service `frontend` is able to reach the `backend` service at the hostname `backend` or `database` on the `back-tier` network. The service `monitoring` is able to reach same `backend` service at `backend` or `mysql` on the `admin` network.

```yml
services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

  monitoring:
    image: example/monitoring
    networks:
      - admin

  backend:
    image: example/backend
    networks:
      back-tier:
        aliases:
          - database
      admin:
        aliases:
          - mysql

networks:
  front-tier: {}
  back-tier: {}
  admin: {}
```

#### [`interface_name`](#interface_name)

Requires: Docker Compose [2.36.0](https://github.com/docker/compose/releases/tag/v2.36.0) and later

`interface_name` lets you specify the name of the network interface used to connect a service to a given network. This ensures consistent and predictable interface naming across services and networks.

```yaml
services:
  backend:
    image: alpine
    command: ip link show
    networks:
      back-tier:
        interface_name: eth0
```

Running the example Compose application shows:

```console
backend-1  | 11: eth0@if64: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP
```

#### [`ipv4_address`, `ipv6_address`](#ipv4_address-ipv6_address)

Specify a static IP address for a service container when joining the network.

The corresponding network configuration in the [top-level networks section](https://docs.docker.com/reference/compose-file/networks/) must have an `ipam` attribute with subnet configurations covering each static address.

```yml
services:
  frontend:
    image: example/webapp
    networks:
      front-tier:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  front-tier:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"
```

#### [`link_local_ips`](#link_local_ips)

`link_local_ips` specifies a list of link-local IPs. Link-local IPs are special IPs which belong to a well known subnet and are purely managed by the operator, usually dependent on the architecture where they are deployed.

Example:

```yaml
services:
  app:
    image: busybox
    command: top
    networks:
      app_net:
        link_local_ips:
          - 57.123.22.11
          - 57.123.22.13
networks:
  app_net:
    driver: bridge
```

#### [`mac_address`](#mac_address-1)

Requires: Docker Compose [2.23.2](https://github.com/docker/compose/releases/tag/v2.23.2) and later

`mac_address` sets the Mac address used by the service container when connecting to this particular network.

#### [`driver_opts`](#driver_opts-1)

`driver_opts` specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent. Consult the driver's documentation for more information.

```yml
services:
  app:
    networks:
      app_net:
        driver_opts:
          foo: "bar"
          baz: 1
```

#### [`gw_priority`](#gw_priority)

Requires: Docker Compose [2.33.1](https://github.com/docker/compose/releases/tag/v2.33.1) and later

The network with the highest `gw_priority` is selected as the default gateway for the service container. If unspecified, the default value is 0.

In the following example, `app_net_2` will be selected as the default gateway.

```yaml
services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
      app_net_2:
        gw_priority: 1
      app_net_3:
networks:
  app_net_1:
  app_net_2:
  app_net_3:
```

#### [`priority`](#priority)

`priority` indicates in which order Compose connects the service’s containers to its networks. If unspecified, the default value is 0.

If the container runtime accepts a `mac_address` attribute at service level, it is applied to the network with the highest `priority`. In other cases, use attribute `networks.mac_address`.

`priority` does not affect which network is selected as the default gateway. Use the [`gw_priority`](#gw_priority) attribute instead.

`priority` does not control the order in which networks connections are added to the container, it cannot be used to determine the device name (`eth0` etc.) in the container.

```yaml
services:
  app:
    image: busybox
    command: top
    networks:
      app_net_1:
        priority: 1000
      app_net_2:

      app_net_3:
        priority: 100
networks:
  app_net_1:
  app_net_2:
  app_net_3:
```

### [`oom_kill_disable`](#oom_kill_disable)

If `oom_kill_disable` is set, Compose configures the platform so it won't kill the container in case of memory starvation.

### [`oom_score_adj`](#oom_score_adj)

`oom_score_adj` tunes the preference for containers to be killed by platform in case of memory starvation. Value must be within -1000,1000 range.

### [`pid`](#pid)

`pid` sets the PID mode for container created by Compose. Supported values are platform specific.

### [`pids_limit`](#pids_limit)

`pids_limit` tunes a container’s PIDs limit. Set to -1 for unlimited PIDs.

```yml
pids_limit: 10
```

When set, `pids_limit` must be consistent with the `pids` attribute in the [Deploy Specification](https://docs.docker.com/reference/compose-file/deploy/#pids).

### [`platform`](#platform)

`platform` defines the target platform the containers for the service run on. It uses the `os[/arch[/variant]]` syntax.

The values of `os`, `arch`, and `variant` must conform to the convention used by the [OCI Image Spec](https://github.com/opencontainers/image-spec/blob/v1.0.2/image-index.md).

Compose uses this attribute to determine which version of the image is pulled and/or on which platform the service’s build is performed.

```yml
platform: darwin
platform: windows/amd64
platform: linux/arm64/v8
```

### [`ports`](#ports)

The `ports` is used to define the port mappings between the host machine and the containers. This is crucial for allowing external access to services running inside containers. It can be defined using short syntax for simple port mapping or long syntax, which includes additional options like protocol type and network mode.

> Note
>
> Port mapping must not be used with `network_mode: host`. Doing so causes a runtime error because `network_mode: host` already exposes container ports directly to the host network, so port mapping isn’t needed.

#### [Short syntax](#short-syntax-3)

The short syntax is a colon-separated string to set the host IP, host port, and container port in the form:

`[HOST:]CONTAINER[/PROTOCOL]` where:

* `HOST` is `[IP:](port | range)` (optional). If it is not set, it binds to all network interfaces (`0.0.0.0`).
* `CONTAINER` is `port | range`.
* `PROTOCOL` restricts ports to a specified protocol either `tcp` or `udp`(optional). Default is `tcp`.

> Warning
>
> If you do not specify a host IP (such as `127.0.0.1`), Docker binds to all interfaces (`0.0.0.0`), bypassing host firewall rules. This can expose the container directly to the internet if the host has a public IP address. For more information, see [Port publishing and mapping](https://docs.docker.com/engine/network/port-publishing/).

Ports can be either a single value or a range. `HOST` and `CONTAINER` must use equivalent ranges.

You can either specify both ports (`HOST:CONTAINER`), or just the container port. In the latter case, the container runtime automatically allocates any unassigned port of the host.

`HOST:CONTAINER` should always be specified as a (quoted) string, to avoid conflicts with [YAML base-60 float](https://yaml.org/type/float.html).

IPv6 addresses can be enclosed in square brackets.

Examples:

```yml
ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "8000-9000:80"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "::1:6000:6000"
  - "[::1]:6001:6001"
  - "6060:6060/udp"
```

> Note
>
> If host IP mapping is not supported by a container engine, Compose rejects the Compose file and ignores the specified host IP.

#### [Long syntax](#long-syntax-4)

The long form syntax lets you configure additional fields that can't be expressed in the short form.

* `target`: The container port.
* `published`: The publicly exposed port. It is defined as a string and can be set as a range using syntax `start-end`. It means the actual port is assigned a remaining available port, within the set range.
* `host_ip`: The host IP mapping. If it is not set, it binds to all network interfaces (`0.0.0.0`).
* `protocol`: The port protocol (`tcp` or `udp`). Defaults to `tcp`.
* `app_protocol`: The application protocol (TCP/IP level 4 / OSI level 7) this port is used for. This is optional and can be used as a hint for Compose to offer richer behavior for protocols that it understands. Introduced in Docker Compose version [2.26.0](https://github.com/docker/compose/releases/tag/v2.26.0).
* `mode`: Specifies how the port is published in a Swarm setup. If set to `host`, it publishes the port on every node in Swarm. If set to `ingress`, it allows load balancing across the nodes in Swarm. Defaults to `ingress`.
* `name`: A human-readable name for the port, used to document its usage within the service.

```yml
ports:
  - name: web
    target: 80
    host_ip: 127.0.0.1
    published: "8080"
    protocol: tcp
    app_protocol: http
    mode: host

  - name: web-secured
    target: 443
    host_ip: 127.0.0.1
    published: "8083-9000"
    protocol: tcp
    app_protocol: https
    mode: host
```

### [`post_start`](#post_start)

Requires: Docker Compose [2.30.0](https://github.com/docker/compose/releases/tag/v2.30.0) and later

`post_start` defines a sequence of lifecycle hooks to run after a container has started. The exact timing of when the command is run is not guaranteed.

* `command`: Specifies the command to run once the container starts. This attribute is required, and you can choose to use either the shell form or the exec form.
* `user`: The user to run the command. If not set, the command is run with the same user as the main service command.
* `privileged`: Lets the `post_start` command run with privileged access.
* `working_dir`: The working directory in which to run the command. If not set, it is run in the same working directory as the main service command.
* `environment`: Sets environment variables specifically for the `post_start` command. While the command inherits the environment variables defined for the service’s main command, this section lets you add new variables or override existing ones.

```yaml
services:
  test:
    post_start:
      - command: ./do_something_on_startup.sh
        user: root
        privileged: true
        environment:
          - FOO=BAR
```

For more information, see [Use lifecycle hooks](https://docs.docker.com/compose/how-tos/lifecycle/).

### [`pre_stop`](#pre_stop)

Requires: Docker Compose [2.30.0](https://github.com/docker/compose/releases/tag/v2.30.0) and later

`pre_stop` defines a sequence of lifecycle hooks to run before the container is stopped. These hooks won't run if the container stops by itself or is terminated suddenly.

Configuration is equivalent to [post\_start](#post_start).

### [`privileged`](#privileged)

`privileged` configures the service container to run with elevated privileges. Support and actual impacts are platform specific.

### [`profiles`](#profiles)

`profiles` defines a list of named profiles for the service to be enabled under. If unassigned, the service is always started but if assigned, it is only started if the profile is activated.

If present, `profiles` follow the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+`.

```yaml
services:
  frontend:
    image: frontend
    profiles: ["frontend"]

  phpmyadmin:
    image: phpmyadmin
    depends_on:
      - db
    profiles:
      - debug
```

### [`provider`](#provider)

Requires: Docker Compose [2.36.0](https://github.com/docker/compose/releases/tag/v2.36.0) and later

`provider` can be used to define a service that Compose won't manage directly. Compose delegated the service lifecycle to a dedicated or third-party component.

```yaml
  database:
    provider:
      type: awesomecloud
      options:
        type: mysql
        foo: bar
  app:
    image: myapp
    depends_on:
       - database
```

As Compose runs the application, the `awesomecloud` binary is used to manage the `database` service setup. Dependent service `app` receives additional environment variables prefixed by the service name so it can access the resource.

For illustration, assuming `awesomecloud` execution produced variables `URL` and `API_KEY`, the `app` service runs with environment variables `DATABASE_URL` and `DATABASE_API_KEY`.

As Compose stops the application, the `awesomecloud` binary is used to manage the `database` service tear down.

The mechanism used by Compose to delegate the service lifecycle to an external binary is described in the [Compose extensibility documentation](https://github.com/docker/compose/tree/main/docs/extension.md).

For more information on using the `provider` attribute, see [Use provider services](https://docs.docker.com/compose/how-tos/provider-services/).

#### [`type`](#type)

`type` attribute is required. It defines the external component used by Compose to manage setup and tear down lifecycle events.

#### [`options`](#options)

`options` are specific to the selected provider and not validated by the compose specification

### [`pull_policy`](#pull_policy)

`pull_policy` defines the decisions Compose makes when it starts to pull images. Possible values are:

* `always`: Compose always pulls the image from the registry.
* `never`: Compose doesn't pull the image from a registry and relies on the platform cached image. If there is no cached image, a failure is reported.
* `missing`: Compose pulls the image only if it's not available in the platform cache. This is the default option if you are not also using the [Compose Build Specification](https://docs.docker.com/reference/compose-file/build/). `if_not_present` is considered an alias for this value for backward compatibility. The `latest` tag is always pulled even when the `missing` pull policy is used.
* `build`: Compose builds the image. Compose rebuilds the image if it's already present.
* `daily`: Compose checks the registry for image updates if the last pull took place more than 24 hours ago.
* `weekly`: Compose checks the registry for image updates if the last pull took place more than 7 days ago.
* `every_<duration>`: Compose checks the registry for image updates if the last pull took place before `<duration>`. Duration can be expressed in weeks (`w`), days (`d`), hours (`h`), minutes (`m`), seconds (`s`) or a combination of these.

```yaml
services:
  test:
    image: nginx
    pull_policy: every_12h
```

### [`read_only`](#read_only)

`read_only` configures the service container to be created with a read-only filesystem.

### [`restart`](#restart)

`restart` defines the policy that the platform applies on container termination.

* `no`: The default restart policy. It does not restart the container under any circumstances.
* `always`: The policy always restarts the container until its removal.
* `on-failure[:max-retries]`: The policy restarts the container if the exit code indicates an error. Optionally, limit the number of restart retries the Docker daemon attempts.
* `unless-stopped`: The policy restarts the container irrespective of the exit code but stops restarting when the service is stopped or removed.

```yml
    restart: "no"
    restart: always
    restart: on-failure
    restart: on-failure:3
    restart: unless-stopped
```

You can find more detailed information on restart policies in the [Restart Policies (--restart)](/reference/cli/docker/container/run/#restart) section of the Docker run reference page.

### [`runtime`](#runtime)

`runtime` specifies which runtime to use for the service’s containers.

For example, `runtime` can be the name of [an implementation of OCI Runtime Spec](https://github.com/opencontainers/runtime-spec/blob/master/implementations.md), such as "runc".

```yml
web:
  image: busybox:latest
  command: true
  runtime: runc
```

The default is `runc`. To use a different runtime, see [Alternative runtimes](https://docs.docker.com/engine/daemon/alternative-runtimes/).

### [`scale`](#scale)

`scale` specifies the default number of containers to deploy for this service. When both are set, `scale` must be consistent with the `replicas` attribute in the [Deploy Specification](https://docs.docker.com/reference/compose-file/deploy/#replicas).

### [`secrets`](#secrets)

The `secrets` attribute grants access to sensitive data defined by the secrets top-level element on a per-service basis. Services can be granted access to multiple secrets.

Two different syntax variants are supported; the short syntax and the long syntax. Long and short syntax for secrets may be used in the same Compose file.

Compose reports an error if the secret doesn't exist on the platform or isn't defined in the [`secrets` top-level section](https://docs.docker.com/reference/compose-file/secrets/) of the Compose file.

Defining a secret in the top-level `secrets` must not imply granting any service access to it. Such grant must be explicit within service specification as [secrets](https://docs.docker.com/reference/compose-file/secrets/) service element.

#### [Short syntax](#short-syntax-4)

The short syntax variant only specifies the secret name. This grants the container access to the secret and mounts it as read-only to `/run/secrets/<secret_name>` within the container. The source name and destination mountpoint are both set to the secret name.

The following example uses the short syntax to grant the `frontend` service access to the `server-certificate` secret. The value of `server-certificate` is set to the contents of the file `./server.cert`.

```yml
services:
  frontend:
    image: example/webapp
    secrets:
      - server-certificate
secrets:
  server-certificate:
    file: ./server.cert
```

#### [Long syntax](#long-syntax-5)

The long syntax provides more granularity in how the secret is created within the service's containers.

* `source`: The name of the secret as it exists on the platform.
* `target`: The name of the file to be mounted in `/run/secrets/` in the service's task container, or absolute path of the file if an alternate location is required. Defaults to `source` if not specified.
* `uid` and `gid`: The numeric uid or gid that owns the file within `/run/secrets/` in the service's task containers.
* `mode`: The [permissions](https://wintelguy.com/permissions-calc.pl) for the file to be mounted in `/run/secrets/` in the service's task containers, in octal notation. The default value is world-readable permissions (mode `0444`). The writable bit must be ignored if set. The executable bit may be set.

Note that support for `uid`, `gid`, and `mode` attributes are only implemented in Docker Compose when the source of the secret is [`environment`](https://docs.docker.com/reference/compose-file/secrets/). When the source is a [`file`](https://docs.docker.com/reference/compose-file/secrets/), Compose uses a bind-mount under the hood which doesn't allow `uid` remapping, and these attributes are silently ignored.

The following example sets the name of the `my-token` secret file within the container, sets the mode to `0440` (group-readable), and sets the user and group to `103`. The value of `my-token` is read from the `MY_TOKEN` environment variable.

```yml
services:
  frontend:
    image: example/webapp
    secrets:
      - source: my-token
        uid: "103"
        gid: "103"
        mode: 0o440
secrets:
  my-token:
    environment: "MY_TOKEN"
```

### [`security_opt`](#security_opt)

`security_opt` overrides the default labeling scheme for each container.

Options accept either `option=value` or `option:value` syntax. For boolean options such as `no-new-privileges`, the value may be omitted entirely, in which case the option is treated as enabled. The following syntaxes are all equivalent:

```yml
security_opt:
  - no-new-privileges
  - no-new-privileges=true
  - no-new-privileges:true
```

```yml
security_opt:
  - label=user:USER
  - label=role:ROLE
```

For further default labeling schemes you can override, see [Security configuration](/reference/cli/docker/container/run/#security-opt).

### [`shm_size`](#shm_size)

`shm_size` configures the size of the shared memory (`/dev/shm` partition on Linux) allowed by the service container. It's specified as a [byte value](https://docs.docker.com/reference/compose-file/extension/#specifying-byte-values).

### [`stdin_open`](#stdin_open)

`stdin_open` configures a service's container to run with an allocated stdin. This is the same as running a container with the `-i` flag. For more information, see [Keep stdin open](/reference/cli/docker/container/run/#interactive).

Supported values are `true` or `false`.

### [`stop_grace_period`](#stop_grace_period)

`stop_grace_period` specifies how long Compose must wait when attempting to stop a container if it doesn't handle SIGTERM (or whichever stop signal has been specified with [`stop_signal`](#stop_signal)), before sending SIGKILL. It's specified as a [duration](https://docs.docker.com/reference/compose-file/extension/#specifying-durations).

```yml
    stop_grace_period: 1s
    stop_grace_period: 1m30s
```

Default value is 10 seconds for the container to exit before sending SIGKILL.

### [`stop_signal`](#stop_signal)

`stop_signal` defines the signal that Compose uses to stop the service containers. If unset containers are stopped by Compose by sending `SIGTERM`.

```yml
stop_signal: SIGUSR1
```

### [`storage_opt`](#storage_opt)

`storage_opt` defines storage driver options for a service.

```yml
storage_opt:
  size: '1G'
```

### [`sysctls`](#sysctls)

`sysctls` defines kernel parameters to set in the container. `sysctls` can use either an array or a map.

```yml
sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0
```

```yml
sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0
```

You can only use sysctls that are namespaced in the kernel. Docker does not support changing sysctls inside a container that also modify the host system. For an overview of supported sysctls, refer to [configure namespaced kernel parameters (sysctls) at runtime](/reference/cli/docker/container/run/#sysctl).

### [`tmpfs`](#tmpfs)

`tmpfs` mounts a temporary file system inside the container. It can be a single value or a list.

```yml
tmpfs:
 - <path>
 - <path>:<options>
```

* `path`: The path inside the container where the tmpfs will be mounted.
* `options`: Comma-separated list of options for the tmpfs mount.

Available options:

* `mode`: Sets the file system permissions.
* `uid`: Sets the user ID that owns the mounted tmpfs.
* `gid`: Sets the group ID that owns the mounted tmpfs.

```yml
services:
  app:
    tmpfs:
      - /data:mode=755,uid=1009,gid=1009
      - /run
```

### [`tty`](#tty)

`tty` configures a service's container to run with a TTY. This is the same as running a container with the `-t` or `--tty` flag. For more information, see [Allocate a pseudo-TTY](/reference/cli/docker/container/run/#tty).

Supported values are `true` or `false`.

### [`ulimits`](#ulimits)

`ulimits` overrides the default `ulimits` for a container. It's specified either as an integer for a single limit or as mapping for soft/hard limits.

```yml
ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000
```

### [`use_api_socket`](#use_api_socket)

When `use_api_socket` is set, the container is able to interact with the underlying container engine through the API socket. Your credentials are mounted inside the container so the container acts as a pure delegate for your commands relating to the container engine. Typically, commands ran by container can `pull` and `push` to your registry.

### [`user`](#user)

`user` overrides the user used to run the container process. The default is set by the image, for example Dockerfile `USER`. If it's not set, then `root`.

### [`userns_mode`](#userns_mode)

`userns_mode` sets the user namespace for the service. Supported values are platform specific and may depend on platform configuration.

```yml
userns_mode: "host"
```

### [`uts`](#uts)

Requires: Docker Compose [2.15.1](https://github.com/docker/compose/releases/tag/v2.15.1) and later

`uts` configures the UTS namespace mode set for the service container. When unspecified it is the runtime's decision to assign a UTS namespace, if supported. Available values are:

* `'host'`: Results in the container using the same UTS namespace as the host.

```yml
    uts: "host"
```

### [`volumes`](#volumes)

The `volumes` attribute define mount host paths or named volumes that are accessible by service containers. You can use `volumes` to define multiple types of mounts; `volume`, `bind`, `tmpfs`, or `npipe`.

If the mount is a host path and is only used by a single service, it can be declared as part of the service definition. To reuse a volume across multiple services, a named volume must be declared in the `volumes` top-level element.

The following example shows a named volume (`db-data`) being used by the `backend` service, and a bind mount defined for a single service.

```yml
services:
  backend:
    image: example/backend
    volumes:
      - type: volume
        source: db-data
        target: /data
        volume:
          nocopy: true
          subpath: sub
      - type: bind
        source: /var/run/postgres/postgres.sock
        target: /var/run/postgres/postgres.sock

volumes:
  db-data:
```

For more information about the `volumes` top-level element, see [Volumes](https://docs.docker.com/reference/compose-file/volumes/).

#### [Short syntax](#short-syntax-5)

The short syntax uses a single string with colon-separated values to specify a volume mount (`VOLUME:CONTAINER_PATH`), or an access mode (`VOLUME:CONTAINER_PATH:ACCESS_MODE`).

* `VOLUME`: Can be either a host path on the platform hosting containers (bind mount) or a volume name.

* `CONTAINER_PATH`: The path in the container where the volume is mounted.

* `ACCESS_MODE`: A comma-separated `,` list of options:

  * `rw`: Read and write access. This is the default if none is specified.
  * `ro`: Read-only access.
  * `z`: SELinux option indicating that the bind mount host content is shared among multiple containers.
  * `Z`: SELinux option indicating that the bind mount host content is private and unshared for other containers.

> Note
>
> The SELinux re-labeling bind mount option is ignored on platforms without SELinux.

> Note
>
> Relative host paths are only supported by Compose that deploy to a local container runtime. This is because the relative path is resolved from the Compose file’s parent directory which is only applicable in the local case. When Compose deploys to a non-local platform it rejects Compose files which use relative host paths with an error. To avoid ambiguities with named volumes, relative paths should always begin with `.` or `..`.

> Note
>
> For bind mounts, the short syntax creates a directory at the source path on the host if it doesn't exist. This is for backward compatibility with `docker-compose` legacy. It can be prevented by using long syntax and setting `create_host_path` to `false`.

#### [Long syntax](#long-syntax-6)

The long form syntax lets you configure additional fields that can't be expressed in the short form.

* `type`: The mount type. Either `volume`, `bind`, `tmpfs`, `image`, `npipe`, or `cluster`

* `source`: The source of the mount, a path on the host for a bind mount, a Docker image reference for an image mount, or the name of a volume defined in the [top-level `volumes` key](https://docs.docker.com/reference/compose-file/volumes/). Not applicable for a tmpfs mount.

* `target`: The path in the container where the volume is mounted.

* `read_only`: Flag to set the volume as read-only.

* `bind`: Used to configure additional bind options:

  * `propagation`: The propagation mode used for the bind.
  * `create_host_path`: Creates a directory at the source path on host if there is nothing present. Defaults to `true`.
  * `selinux`: The SELinux re-labeling option `z` (shared) or `Z` (private)

* `volume`: Configures additional volume options:

  * `nocopy`: Flag to disable copying of data from a container when a volume is created.
  * `subpath`: Path inside a volume to mount instead of the volume root.

* `tmpfs`: Configures additional tmpfs options:

  * `size`: The size for the tmpfs mount in bytes (either numeric or as bytes unit).
  * `mode`: The file mode for the tmpfs mount as Unix permission bits as an octal number. Introduced in Docker Compose version [2.14.0](https://github.com/docker/compose/releases/tag/v2.14.0).

* `image`: Configures additional image options:
  * `subpath`: Path inside the source image to mount instead of the image root. Available in [Docker Compose version 2.35.0](https://github.com/docker/compose/releases/tag/v2.35.0)

* `consistency`: The consistency requirements of the mount. Available values are platform specific.

> Tip
>
> Working with large repositories or monorepos, or with virtual file systems that are no longer scaling with your codebase? Compose now takes advantage of [Synchronized file shares](https://docs.docker.com/desktop/features/synchronized-file-sharing/) and automatically creates file shares for bind mounts. Ensure you're signed in to Docker with a paid subscription and have enabled both **Access experimental features** and **Manage Synchronized file shares with Compose** in Docker Desktop's settings.

### [`volumes_from`](#volumes_from)

`volumes_from` mounts all of the volumes from another service or container. You can optionally specify read-only access `ro` or read-write `rw`. If no access level is specified, then read-write access is used.

You can also mount volumes from a container that is not managed by Compose by using the `container:` prefix.

```yaml
volumes_from:
  - service_name
  - service_name:ro
  - container:container_name
  - container:container_name:rw
```

### [`working_dir`](#working_dir)

`working_dir` overrides the container's working directory which is specified by the image, for example Dockerfile's `WORKDIR`.

----
url: https://docs.docker.com/reference/cli/docker/offload/start/
----

# docker offload start

***

| Description | Start a Docker Offload session |
| ----------- | ------------------------------ |
| Usage       | `docker offload start`         |

## [Options](#options)

| Option           | Default | Description                                 |
| ---------------- | ------- | ------------------------------------------- |
| `-a, --account`  |         | The Docker account to use                   |
| `-g, --gpu`      |         | Request an engine with a gpu                |
| `--idle-timeout` |         | How long before the engine idles            |
| `--timeout`      | `10s`   | How long to wait for the engine to be ready |

----
url: https://docs.docker.com/reference/cli/sbx/login/
----

# sbx login

| Description | Sign in to Docker   |
| ----------- | ------------------- |
| Usage       | `sbx login [flags]` |

## [Options](#options)

| Option             | Default | Description                               |
| ------------------ | ------- | ----------------------------------------- |
| `--password-stdin` |         | Read password or access token from stdin  |
| `--username`       |         | Docker username for non-interactive login |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/enterprise/security/roles-and-permissions/custom-roles/
----

# Custom roles

***

Table of contents

***

For: Administrators

Custom roles allow you to create tailored permission sets that match your organization's specific needs. This page covers custom roles and steps to create and manage them.

## [What are custom roles?](#what-are-custom-roles)

Custom roles let you create tailored permission sets for your organization. You can assign custom roles to individual users or teams. Users and teams get either a core role or custom role, but not both.

Use custom roles when Docker's core roles don't fit your needs.

## [Prerequisites](#prerequisites)

To configure custom roles, you need owner permissions in your Docker organization.

## [Create a custom role](#create-a-custom-role)

Before you can assign a custom role to users, you must create one in the Admin Console:

1. Sign in to [Docker Home](https://app.docker.com).

2. Select **Admin Console**.

3. Under **User management**, select **Roles** > **Create role**.

4. Create a name and describe what the role is for:

   * Provide a **Label**
   * Enter a unique **Name** identifier (can't be changed later)
   * Add an optional **Description**

5. Set permissions for the role by expanding permission categories and selecting the checkboxes for permissions. For a full list of available permissions, see the [custom roles permissions reference](#custom-roles-permissions-reference).

6. Select **Review** to review your custom roles configuration and see a summary of selected permissions.

7. Select **Create**.

With a custom role created, you can now [assign custom roles to users](#assign-custom-roles).

## [Edit a custom role](#edit-a-custom-role)

1. Sign in to [Docker Home](https://app.docker.com).

2. Select **Admin Console**.

3. Under **User management**, select **Roles**.

4. Find your custom role from the list, and select the **Actions menu**.

5. Select **Edit**.

6. You can edit the following custom role settings:

   * Label
   * Description
   * Permissions

7. After you have finished editing, select **Save**.

## [Assign custom roles](#assign-custom-roles)

1. Sign in to [Docker Home](https://app.docker.com).
2. Select **Members**.
3. Locate the member you want to assign a custom role to, then select the **Actions menu**.
4. In the drop-down, select **Change role**.
5. In the **Select a role** drop-down, select your custom role.
6. Select **Save**.

1) Sign in to [Docker Home](https://app.docker.com).
2) Select **Members**.
3) Use the checkboxes in the username column to select all users you want to assign a custom role to.
4) Select **Change role**.
5) In the **Select a role** drop-down, select your custom role or a core role.
6) Select **Save**.

1. Sign in to [Docker Home](https://app.docker.com).
2. Select **Teams**.
3. Locate the team you want to assign a custom role to, then select the **Actions menu**.
4. Select **Assign role**.
5. Select your custom role, then select **Assign**.

The role column will update to the newly assigned role.

## [View role assignments](#view-role-assignments)

To see which users and teams are assigned to roles:

1. Sign in to [Docker Home](https://app.docker.com).
2. Select **Admin Console**.
3. Under **User management**, select **Roles**.
4. In the roles list, view the **Users** and **Teams** columns to see assignment counts.
5. Select a specific role to view its permissions and assignments in detail.

## [Reassign custom roles](#reassign-custom-roles)

1. Sign in to [Docker Home](https://app.docker.com).
2. Select **Members**.
3. Locate the member you want to reassign, then select the **Actions menu**.
4. Select **Change role**.
5. In the **Select a role** drop-down, select the new role.
6. Select **Save**.

1) Sign in to [Docker Home](https://app.docker.com).
2) Select **Members**.
3) Use the checkboxes in the username column to select all users you want to reassign.
4) Select **Change role**.
5) In the **Select a role** drop-down, select the new role.
6) Select **Save**.

1. Sign in to [Docker Home](https://app.docker.com).
2. Select **Teams**.
3. Locate the team, then select the **Actions menu**.
4. Select **Change role**.
5. In the pop-up window, select a role from the drop-down menu, then select **Save**.

## [Delete a custom role](#delete-a-custom-role)

Before deleting a custom role, you must reassign all users and teams to different roles.

1. Sign in to [Docker Home](https://app.docker.com).

2. Select **Admin Console**.

3. Under **User management**, select **Roles**.

4. Find your custom role from the list, and select the **Actions menu**.

5. If the role has assigned users or teams:

   * Navigate to the **Members** page and change the role for all users assigned to this custom role
   * Navigate to the **Teams** page and reassign all teams that have this custom role

6. Once no users or teams are assigned, return to **Roles**.

7. Find your custom role and select the **Actions menu**.

8. Select **Delete**.

9. In the confirmation window, select **Delete** to confirm.

## [Custom roles permissions reference](#custom-roles-permissions-reference)

Custom roles are built by selecting specific permissions across different categories. The following tables list all available permissions you can assign to a custom role.

### [Organization management](#organization-management)

| Permission                        | Description                                                                                     |
| --------------------------------- | ----------------------------------------------------------------------------------------------- |
| View teams                        | View teams and team members                                                                     |
| Manage teams                      | Create, update, and delete teams and team members                                               |
| Manage registry access            | Control which registries members can access                                                     |
| Manage image access               | Set policies for which images members can pull and use                                          |
| Update organization information   | Update organization information such as name and location                                       |
| Member management                 | Manage organization members, invites, and roles                                                 |
| View custom roles                 | View existing custom roles and their permissions                                                |
| Manage custom roles               | Full access to custom role management and assignment                                            |
| Manage organization access tokens | Create, update, and delete repositories in this org. Push/pull or registry actions not included |
| View activity logs                | Access organization audit logs and activity history                                             |
| View domains                      | View domains and domain audit settings                                                          |
| Manage domains                    | Manage verified domains and domain audit settings                                               |
| View SSO and SCIM                 | View single sign-on and user provisioning configurations                                        |
| Manage SSO and SCIM               | Full access to SSO and SCIM management                                                          |
| Manage Desktop settings           | Configure Docker Desktop settings policies and view usage reports                               |

### [Docker Hub](#docker-hub)

| Permission          | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| View repositories   | View repository details and contents                       |
| Manage repositories | Create, update, and delete repositories and their contents |

### [Billing](#billing)

| Permission     | Description                                      |
| -------------- | ------------------------------------------------ |
| View billing   | View organization billing information            |
| Manage billing | Complete access to managing organization billing |

----
url: https://docs.docker.com/guides/testcontainers-go-getting-started/create-project/
----

# Create the Go project

***

Table of contents

***

## [Initialize the project](#initialize-the-project)

Start by creating a Go project.

```console
$ mkdir testcontainers-go-demo
$ cd testcontainers-go-demo
$ go mod init github.com/testcontainers/testcontainers-go-demo
```

This guide uses the [jackc/pgx](https://github.com/jackc/pgx) PostgreSQL driver to interact with the Postgres database and the testcontainers-go [Postgres module](https://golang.testcontainers.org/modules/postgres/) to spin up a Postgres Docker instance for testing. It also uses [testify](https://github.com/stretchr/testify) for running multiple tests as a suite and for writing assertions.

Install these dependencies:

```console
$ go get github.com/jackc/pgx/v5
$ go get github.com/testcontainers/testcontainers-go
$ go get github.com/testcontainers/testcontainers-go/modules/postgres
$ go get github.com/stretchr/testify
```

## [Create Customer struct](#create-customer-struct)

Create a `types.go` file in the `customer` package and define the `Customer` struct to model the customer details:

```go
package customer

type Customer struct {
	Id    int
	Name  string
	Email string
}
```

## [Create Repository](#create-repository)

Next, create `customer/repo.go`, define the `Repository` struct, and add methods to create a customer and get a customer by email:

```go
package customer

import (
	"context"
	"fmt"
	"os"

	"github.com/jackc/pgx/v5"
)

type Repository struct {
	conn *pgx.Conn
}

func NewRepository(ctx context.Context, connStr string) (*Repository, error) {
	conn, err := pgx.Connect(ctx, connStr)
	if err != nil {
		_, _ = fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
		return nil, err
	}
	return &Repository{
		conn: conn,
	}, nil
}

func (r Repository) CreateCustomer(ctx context.Context, customer Customer) (Customer, error) {
	err := r.conn.QueryRow(ctx,
		"INSERT INTO customers (name, email) VALUES ($1, $2) RETURNING id",
		customer.Name, customer.Email).Scan(&customer.Id)
	return customer, err
}

func (r Repository) GetCustomerByEmail(ctx context.Context, email string) (Customer, error) {
	var customer Customer
	query := "SELECT id, name, email FROM customers WHERE email = $1"
	err := r.conn.QueryRow(ctx, query, email).
		Scan(&customer.Id, &customer.Name, &customer.Email)
	if err != nil {
		return Customer{}, err
	}
	return customer, nil
}
```

Here's what the code does:

* `Repository` holds a `*pgx.Conn` for performing database operations.
* `NewRepository(connStr)` takes a database connection string and initializes a `Repository`.
* `CreateCustomer()` and `GetCustomerByEmail()` are methods on the `Repository` receiver that insert and query customer records.

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-go-getting-started/write-tests/)

----
url: https://docs.docker.com/engine/storage/
----

# Storage

***

Table of contents

***

Docker storage covers two different concepts:

**Container data persistence** (this page): How to store application data outside containers using volumes, bind mounts, and tmpfs mounts. This data persists independently of container lifecycle.

**Daemon storage backends** ([containerd image store](https://docs.docker.com/engine/storage/containerd/) and [storage drivers](https://docs.docker.com/engine/storage/drivers/)): How the daemon stores image layers and container writable layers on disk.

This page focuses on container data persistence. For information about how Docker stores images and container layers, see [containerd image store](https://docs.docker.com/engine/storage/containerd/) or [Storage drivers](https://docs.docker.com/engine/storage/drivers/).

## [Container layer basics](#container-layer-basics)

By default all files created inside a container are stored on a writable container layer that sits on top of the read-only, immutable image layers.

Data written to the container layer doesn't persist when the container is destroyed. This means that it can be difficult to get the data out of the container if another process needs it.

The writable layer is unique per container. You can't easily extract the data from the writeable layer to the host, or to another container.

## [Storage mount options](#storage-mount-options)

Docker supports the following types of storage mounts for storing data outside of the writable layer of the container:

* [Volume mounts](#volume-mounts)
* [Bind mounts](#bind-mounts)
* [tmpfs mounts](#tmpfs-mounts)
* [Named pipes](#named-pipes)

No matter which type of mount you choose to use, the data looks the same from within the container. It is exposed as either a directory or an individual file in the container's filesystem.

### [Volume mounts](#volume-mounts)

Volumes are persistent storage mechanisms managed by the Docker daemon. They retain data even after the containers using them are removed. Volume data is stored on the filesystem on the host, but in order to interact with the data in the volume, you must mount the volume to a container. Directly accessing or interacting with the volume data is unsupported, undefined behavior, and may result in the volume or its data breaking in unexpected ways.

Volumes are ideal for performance-critical data processing and long-term storage needs. Since the storage location is managed on the daemon host, volumes provide the same raw file performance as accessing the host filesystem directly.

### [Bind mounts](#bind-mounts)

Bind mounts create a direct link between a host system path and a container, allowing access to files or directories stored anywhere on the host. Since they aren't isolated by Docker, both non-Docker processes on the host and container processes can modify the mounted files simultaneously.

Use bind mounts when you need to be able to access files from both the container and the host.

### [tmpfs mounts](#tmpfs-mounts)

A tmpfs mount stores files directly in the host machine's memory, ensuring the data is not written to disk. This storage is ephemeral: the data is lost when the container is stopped or restarted, or when the host is rebooted. tmpfs mounts do not persist data either on the Docker host or within the container's filesystem.

These mounts are suitable for scenarios requiring temporary, in-memory storage, such as caching intermediate data, handling sensitive information like credentials, or reducing disk I/O. Use tmpfs mounts only when the data does not need to persist beyond the current container session.

### [Named pipes](#named-pipes)

[Named pipes](https://docs.microsoft.com/en-us/windows/desktop/ipc/named-pipes) can be used for communication between the Docker host and a container. Common use case is to run a third-party tool inside of a container and connect to the Docker Engine API using a named pipe.

## [Next steps](#next-steps)

Learn more about container data persistence:

* [Volumes](https://docs.docker.com/engine/storage/volumes/)
* [Bind mounts](https://docs.docker.com/engine/storage/bind-mounts/)
* [tmpfs mounts](https://docs.docker.com/engine/storage/tmpfs/)

Learn more about daemon storage backends:

* [containerd image store](https://docs.docker.com/engine/storage/containerd/)
* [Storage drivers](https://docs.docker.com/engine/storage/drivers/)

----
url: https://docs.docker.com/guides/opentelemetry/
----

[Instrumenting a JavaScript App with OpenTelemetry](https://docs.docker.com/guides/opentelemetry/)

Learn how to instrument a JavaScript application using OpenTelemetry in a Dockerized environment.

JavaScript App development Observability

10 minutes

[« Back to all guides](/guides/)

# Instrumenting a JavaScript App with OpenTelemetry

***

Table of contents

***

OpenTelemetry (OTel) is an open-source observability framework that provides a set of APIs, SDKs, and tools for collecting telemetry data, such as metrics, logs, and traces, from applications. With OpenTelemetry, developers can obtain valuable insights into how their services perform in production or during local development.

A key component of OpenTelemetry is the OpenTelemetry Protocol (OTLP) a general-purpose, vendor-agnostic protocol designed to transmit telemetry data efficiently and reliably. OTLP supports multiple data types (traces, metrics, logs) over HTTP or gRPC, making it the default and recommended protocol for communication between instrumented applications, the OpenTelemetry Collector, and backends such as Jaeger or Prometheus.

This guide walks you through how to instrument a simple Node.js application with OpenTelemetry and run both the app and a collector using Docker. This setup is ideal for local development and testing observability before integrating with external observability platforms like Prometheus, Jaeger, or Grafana.

In this guide, you'll learn how to:

* How to set up OpenTelemetry in a Node.js app.
* How to run an OpenTelemetry Collector in Docker.
* How to visualize traces with Jaeger.
* How to use Docker Compose to manage the full observability stack.

## [Using OpenTelemetry with Docker](#using-opentelemetry-with-docker)

The [Docker Official Image for OpenTelemetry](https://hub.docker.com/r/otel/opentelemetry-collector-contrib) provides a convenient way to deploy and manage Dex instances. OpenTelemetry is available for various CPU architectures, including amd64, armv7, and arm64, ensuring compatibility with different devices and platforms. Same for the [Jaeger Docker image](https://hub.docker.com/r/jaegertracing/jaeger).

## [Prerequisites](#prerequisites)

[Docker Compose](/compose/): Recommended for managing multi-container Docker applications.

Basic knowledge of Node.js and Docker.

## [Project structure](#project-structure)

Create the project directory:

```bash
mkdir otel-js-app
cd otel-js-app
```

```bash
otel-js-app/
├── docker-compose.yaml
├── collector-config.yaml
├── app/
│   ├── package.json
│   ├── app.js
│   └── tracer.js
```

## [Create a simple Node.js app](#create-a-simple-nodejs-app)

Initialize a basic Node.js app:

```bash
mkdir app && cd app
npm init -y
npm install express @opentelemetry/api @opentelemetry/sdk-node \
            @opentelemetry/auto-instrumentations-node \
            @opentelemetry/exporter-trace-otlp-http
```

Now, add the application logic:

```js
// app/app.js
const express = require('express');
require('./tracer'); // Initialize OpenTelemetry

const app = express();

app.get('/', (req, res) => {
  res.send('Hello from OpenTelemetry demo app!');
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`App listening at http://localhost:${PORT}`);
});
```

## [Configure OpenTelemetry tracing](#configure-opentelemetry-tracing)

Create the tracer configuration file:

```js
// app/tracer.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: 'http://collector:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();
```

## [Configure the OpenTelemetry Collector](#configure-the-opentelemetry-collector)

Create a collector-config.yaml file at the root:

```yaml
# collector-config.yaml
receivers:
  otlp:
    protocols:
      http:

exporters:
  logging:
    loglevel: debug
  jaeger:
    endpoint: jaeger:14250
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [logging, jaeger]
```

## [Add Docker Compose configuration](#add-docker-compose-configuration)

Create the `docker-compose.yaml` file:

```yaml
version: '3.9'

services:
  app:
    build: ./app
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    depends_on:
      - collector

  collector:
    image: otel/opentelemetry-collector:latest
    volumes:
      - ./collector-config.yaml:/etc/otelcol/config.yaml
    command: ["--config=/etc/otelcol/config.yaml"]
    ports:
      - "4318:4318" # OTLP

  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686" # UI
      - "14250:14250" # Collector gRPC
```

Now, add the `Dockerfile` inside the `app/` folder:

```dockerfile
# app/Dockerfile
FROM node:18

WORKDIR /usr/src/app
COPY . .
RUN npm install

CMD ["node", "app.js"]
```

## [Start the stack](#start-the-stack)

Start all services with Docker Compose:

```bash
docker compose up --build
```

Once the services are running:

Visit your app at <http://localhost:3000>

View traces at <http://localhost:16686> in the Jaeger UI

## [Verify traces in Jaeger](#verify-traces-in-jaeger)

After visiting your app's root endpoint, open Jaeger’s UI, search for the service (default is usually `unknown_service` unless explicitly named), and check the traces.

You should see spans for the HTTP request, middleware, and auto-instrumented libraries.

## [Conclusion](#conclusion)

You now have a fully functional OpenTelemetry setup using Docker Compose. You've instrumented a basic JavaScript app to export traces and visualized them using Jaeger. This architecture is extendable for more complex applications and observability pipelines using Prometheus, Grafana, or cloud-native exporters.

For advanced topics such as custom span creation, metrics, and logs, consult the OpenTelemetry JavaScript docs.

----
url: https://docs.docker.com/guides/php/deploy/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Test your PHP deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Containerize a PHP application](https://docs.docker.com/guides/php/containerize/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your `docker-php-sample` directory, create a file named `docker-php-kubernetes.yaml`. Open the file in an IDE or text editor and add the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the name of the repository that you created in [Configure CI/CD for your PHP application](https://docs.docker.com/guides/php/configure-ci-cd/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-php-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      hello-php: web
  template:
    metadata:
      labels:
        hello-php: web
    spec:
      containers:
        - name: hello-site
          image: DOCKER_USERNAME/REPO_NAME
          imagePullPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: php-entrypoint
  namespace: default
spec:
  type: NodePort
  selector:
    hello-php: web
  ports:
    - port: 80
      targetPort: 80
      nodePort: 30001
```

In this Kubernetes YAML file, there are two objects, separated by the `---`:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your PHP application](https://docs.docker.com/guides/php/configure-ci-cd/).
* A NodePort service, which will route traffic from port 30001 on your host to port 80 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to the `docker-php-sample` directory and deploy your application to Kubernetes.

   ```console
   $ kubectl apply -f docker-php-kubernetes.yaml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```text
   deployment.apps/docker-php-demo created
   service/php-entrypoint created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```text
   NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
   docker-php-demo      1/1     1            1           6s
   ```

   This indicates all of the pods are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```text
   NAME              TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
   kubernetes        ClusterIP   10.96.0.1        <none>        443/TCP          7d22h
   php-entrypoint    NodePort    10.111.101.229   <none>        80:30001/TCP     33s
   ```

   In addition to the default `kubernetes` service, you can see your `php-entrypoint` service. The `php-entrypoint` service is accepting traffic on port 30001/TCP.

3. Open a browser and visit your app at <http://localhost:30001/hello.php>. You should see your application.

4. Run the following command to tear down your application.

   ```console
   $ kubectl delete -f docker-php-kubernetes.yaml
   ```

----
url: https://docs.docker.com/reference/cli/docker/desktop/stop/
----

# docker desktop stop

***

| Description | Stop Docker Desktop             |
| ----------- | ------------------------------- |
| Usage       | `docker desktop stop [OPTIONS]` |

## [Options](#options)

| Option         | Default | Description                                                                                                                               |
| -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `-d, --detach` |         | Do not synchronously wait for the requested operation to complete                                                                         |
| `--force`      |         | Force Docker Desktop to stop                                                                                                              |
| `--timeout`    |         | Terminate the running command after the specified timeout with a non-zero exit code. A value of zero (the default) or -1 means no timeout |

----
url: https://docs.docker.com/reference/samples/java/
----

# Java samples

| Name                                                                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Java Spark / MySQL](https://github.com/docker/awesome-compose/tree/master/sparkjava-mysql)                                       | A sample Java application and a MySQL database.                                                                                                                                                                                                                                                                                                                                                                                                |
| [React / Spring / MySQL](https://github.com/docker/awesome-compose/tree/master/react-java-mysql)                                  | A sample React application with a Spring backend and a MySQL database.                                                                                                                                                                                                                                                                                                                                                                         |
| [Spring / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/spring-postgres)                                      | A sample Java application with Spring framework and a Postgres database.                                                                                                                                                                                                                                                                                                                                                                       |
| [Spark](https://github.com/docker/awesome-compose/tree/master/sparkjava)                                                          | A sample Spark application.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [example-voting-app](https://github.com/dockersamples/example-voting-app)                                                         | A sample Docker Compose app.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [atsea-sample-shop-app](https://github.com/dockersamples/atsea-sample-shop-app)                                                   | A sample app that uses a Java Spring Boot backend connected to a database to display a fictitious art shop with a React front-end.                                                                                                                                                                                                                                                                                                             |
| [wordsmith](https://github.com/dockersamples/wordsmith)                                                                           | A demo app that runs three containers, including PostgreSQL, Java, and Go.                                                                                                                                                                                                                                                                                                                                                                     |
| [Spring AI Brave Search Example - Model Context Protocol (MCP)](https://github.com/docker/compose-for-agents/tree/main/spring-ai) | This example demonstrates how to create a Spring AI Model Context Protocol (MCP) client that communicates with the Brave Search MCP Server. The application shows how to build an MCP client that enables natural language interactions with Brave Search, allowing you to perform internet searches through a conversational interface. This example uses Spring Boot autoconfiguration to set up the MCP client through configuration files. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/
----

# Configure Settings Management with the Admin Console

***

Table of contents

***

Subscription: Business

For: Administrators

Use the Docker Admin Console to create and manage settings policies for Docker Desktop across your organization. Settings policies let you standardize configurations, enforce security requirements, and maintain consistent Docker Desktop environments.

## [Prerequisites](#prerequisites)

Before you begin, make sure you have:

* [Docker Desktop](https://docs.docker.com/desktop/release-notes/) installed
* [A verified domain](/enterprise/security/single-sign-on/connect/#step-1-add-a-domain)
* [Enforced sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) for your organization
* A Docker Business subscription

> Important
>
> You can create settings management policies at any time, but your organization needs to verify a domain before the policies take effect.

## [Create a settings policy](#create-a-settings-policy)

To create a new settings policy:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.

2. Select **Admin Console**, then **Desktop Settings Management**.

3. Select **Create a settings policy**.

4. Provide a name and optional description.

   > Tip
   >
   > You can upload an existing `admin-settings.json` file to pre-fill the form. Admin Console policies override local `admin-settings.json` files.

5. Choose who the policy applies to:

   * All users

   * Specific users

     > Note
     >
     > User-specific policies override global default policies. Test your policy with a small group before applying it organization-wide.

6. Configure each setting using a state:

   | Admin Console state | Description                       | `admin-settings.json` equivalent    |
   | ------------------- | --------------------------------- | ----------------------------------- |
   | **User-defined**    | Users can change the setting      | Omit the setting                    |
   | **Always enabled**  | Setting is on and locked          | `"value": true`, `"locked": true`   |
   | **Enabled**         | Setting is on but can be changed  | `"value": true`, `"locked": false`  |
   | **Always disabled** | Setting is off and locked         | `"value": false`, `"locked": true`  |
   | **Disabled**        | Setting is off but can be changed | `"value": false`, `"locked": false` |

   > Tip
   >
   > For a complete list of configurable settings, supported platforms, and configuration methods, see the [Settings reference](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/settings-reference/).

7. Select **Create** to save your policy.

## [Apply the policy](#apply-the-policy)

Settings policies take effect after Docker Desktop restarts and users sign in.

For new installations:

1. Launch Docker Desktop.
2. Sign in with your Docker account.

For existing installations:

1. Quit Docker Desktop completely.
2. Relaunch Docker Desktop.

> Important
>
> Users must fully quit and reopen Docker Desktop. Restarting from the Docker Desktop menu isn't sufficient.

Docker Desktop checks for policy updates when it launches and every 60 minutes while running.

## [Verify applied settings](#verify-applied-settings)

After you apply policies:

* Docker Desktop displays most settings as greyed out
* Some settings, particularly Enhanced Container Isolation configurations, may not appear in the GUI
* You can verify all applied settings by checking the [`settings-store.json` file](https://docs.docker.com/desktop/settings-and-maintenance/settings/) on your system

## [Manage existing policies](#manage-existing-policies)

From the **Desktop Settings Management** page in the Admin Console, use the **Actions** menu to:

* Edit or delete an existing settings policy
* Export a settings policy as an `admin-settings.json` file
* Promote a user-specific policy to be the new global default

## [Roll back policies](#roll-back-policies)

To roll back a settings policy:

* Complete rollback: Delete the entire policy.
* Partial rollback: Set specific settings to **User-defined**.

When you roll back settings, users regain control over those settings configurations.

----
url: https://docs.docker.com/guides/java/containerize/
----

# Containerize a Java application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop.

- You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Overview](#overview)

This section walks you through containerizing and running a Java application.

## [Get the sample applications](#get-the-sample-applications)

Clone the sample application that you'll be using to your local development machine. Run the following command in a terminal to clone the repository.

```console
$ git clone https://github.com/spring-projects/spring-petclinic.git
```

The sample application is a Spring Boot application built using Maven. For more details, see `readme.md` in the repository.

## [Create Docker assets](#create-docker-assets)

Now that you have an application, you can create the necessary Docker assets to containerize your application.

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

Create a file named `Dockerfile` with the following contents.

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1

# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Dockerfile reference guide at
# https://docs.docker.com/go/dockerfile-reference/

################################################################################

# Create a stage for resolving and downloading dependencies.
FROM eclipse-temurin:21-jdk-jammy as deps

WORKDIR /build

# Copy the mvnw wrapper with executable permissions.
COPY --chmod=0755 mvnw mvnw
COPY .mvn/ .mvn/

# Download dependencies as a separate step to take advantage of Docker's caching.
# Leverage a cache mount to /root/.m2 so that subsequent builds don't have to
# re-download packages.
RUN --mount=type=bind,source=pom.xml,target=pom.xml \
    --mount=type=cache,target=/root/.m2 ./mvnw dependency:go-offline -DskipTests

################################################################################

# Create a stage for building the application based on the stage with downloaded dependencies.
# This Dockerfile is optimized for Java applications that output an uber jar, which includes
# all the dependencies needed to run your app inside a JVM. If your app doesn't output an uber
# jar and instead relies on an application server like Apache Tomcat, you'll need to update this
# stage with the correct filename of your package and update the base image of the "final" stage
# use the relevant app server, e.g., using tomcat (https://hub.docker.com/_/tomcat/) as a base image.
FROM deps as package

WORKDIR /build

COPY ./src src/
RUN --mount=type=bind,source=pom.xml,target=pom.xml \
    --mount=type=cache,target=/root/.m2 \
    ./mvnw package -DskipTests && \
    mv target/$(./mvnw help:evaluate -Dexpression=project.artifactId -q -DforceStdout)-$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout).jar target/app.jar

################################################################################

# Create a stage for extracting the application into separate layers.
# Take advantage of Spring Boot's layer tools and Docker's caching by extracting
# the packaged application into separate layers that can be copied into the final stage.
# See Spring's docs for reference:
# https://docs.spring.io/spring-boot/docs/current/reference/html/container-images.html
FROM package as extract

WORKDIR /build

RUN java -Djarmode=layertools -jar target/app.jar extract --destination target/extracted

################################################################################

# Create a new stage for running the application that contains the minimal
# runtime dependencies for the application. This often uses a different base
# image from the install or build stage where the necessary files are copied
# from the install stage.
#
# The example below uses eclipse-turmin's JRE image as the foundation for running the app.
# By specifying the "17-jre-jammy" tag, it will also use whatever happens to be the
# most recent version of that tag when you build your Dockerfile.
# If reproducibility is important, consider using a specific digest SHA, like
# eclipse-temurin@sha256:99cede493dfd88720b610eb8077c8688d3cca50003d76d1d539b0efc8cca72b4.
FROM eclipse-temurin:21-jre-jammy AS final

# Create a non-privileged user that the app will run under.
# See https://docs.docker.com/go/dockerfile-user-best-practices/
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser
USER appuser

# Copy the executable from the "package" stage.
COPY --from=extract build/target/extracted/dependencies/ ./
COPY --from=extract build/target/extracted/spring-boot-loader/ ./
COPY --from=extract build/target/extracted/snapshot-dependencies/ ./
COPY --from=extract build/target/extracted/application/ ./

EXPOSE 8080

ENTRYPOINT [ "java", "org.springframework.boot.loader.launch.JarLauncher" ]
```

> Note
>
> The sample repository includes a `docker-compose.yml` file. The following instructions use the preferred `compose.yaml` filename — both are supported by Docker Compose.

Create a file named `compose.yaml` with the following contents.

compose.yaml

```yaml
# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Docker Compose reference guide at
# https://docs.docker.com/go/compose-spec-reference/

# Here the instructions define your application as a service called "server".
# This service is built from the Dockerfile in the current directory.
# You can add other services your application may depend on here, such as a
# database or a cache. For examples, see the Awesome Compose repository:
# https://github.com/docker/awesome-compose
services:
  server:
    build:
      context: .
    ports:
      - 8080:8080
# The commented out section below is an example of how to define a PostgreSQL
# database that your application can use. `depends_on` tells Docker Compose to
# start the database before your application. The `db-data` volume persists the
# database data between container restarts. The `db-password` secret is used
# to set the database password. You must create `db/password.txt` and add
# a password of your choosing to it before running `docker compose up`.
#     depends_on:
#       db:
#         condition: service_healthy
#   db:
#     image: postgres:18
#     restart: always
#     user: postgres
#     secrets:
#       - db-password
#     volumes:
#       - db-data:/var/lib/postgresql
#     environment:
#       - POSTGRES_DB=example
#       - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
#     expose:
#       - 5432
#     healthcheck:
#       test: [ "CMD", "pg_isready" ]
#       interval: 10s
#       timeout: 5s
#       retries: 5
# volumes:
#   db-data:
# secrets:
#   db-password:
#     file: db/password.txt
```

Create a file named `.dockerignore` with the following contents.

.dockerignore

```text
# Include any files or directories that you don't want to be copied to your
# container here (e.g., local build artifacts, temporary files, etc.).
#
# For more help, visit the .dockerignore file reference guide at
# https://docs.docker.com/go/build-context-dockerignore/

**/.classpath
**/.dockerignore
**/.env
**/.git
**/.gitignore
**/.project
**/.settings
**/.toolstarget
**/.vs
**/.vscode
**/.next
**/.cache
**/*.*proj.user
**/*.dbmdl
**/*.jfm
**/charts
**/docker-compose*
**/compose.y*ml
**/target
**/Dockerfile*
**/node_modules
**/npm-debug.log
**/obj
**/secrets.dev.yaml
**/values.dev.yaml
**/vendor
LICENSE
README.md
```

You should now have the following three files in your `spring-petclinic` directory.

* [Dockerfile](/reference/dockerfile/)
* [.dockerignore](/reference/dockerfile/#dockerignore-file)
* [compose.yaml](https://docs.docker.com/reference/compose-file/)

## [Run the application](#run-the-application)

Inside the `spring-petclinic` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

The first time you build and run the app, Docker downloads dependencies and builds the app. It may take several minutes depending on your network connection.

Open a browser and view the application at <http://localhost:8080>. You should see a simple app for a pet clinic.

In the terminal, press `ctrl`+`c` to stop the application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `spring-petclinic` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:8080>. You should see a simple app for a pet clinic.

In the terminal, run the following command to stop the application.

```console
$ docker compose down
```

For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

## [Summary](#summary)

In this section, you learned how you can containerize and run a Java application using Docker.

## [Next steps](#next-steps)

In the next section, you'll learn how you can develop your application using Docker containers.

[Use containers for Java development »](https://docs.docker.com/guides/java/develop/)

----
url: https://docs.docker.com/reference/cli/docker/image/save/
----

# docker image save

***

| Description                                                               | Save one or more images to a tar archive (streamed to STDOUT by default) |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Usage                                                                     | `docker image save [OPTIONS] IMAGE [IMAGE...]`                           |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker save`                                                            |

## [Description](#description)

Produces a tarred repository to the standard output stream. Contains all parent layers, and all tags + versions, or specified `repo:tag`, for each argument provided.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                   |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `-o, --output`            |         | Write to a file, instead of STDOUT                                                                                                            |
| [`--platform`](#platform) |         | API 1.48+ Save only the given platform(s). Formatted as a comma-separated list of `os[/arch[/variant]]` (e.g., `linux/amd64,linux/arm64/v8`)  |

## [Examples](#examples)

### [Create a backup that can then be used with `docker load`.](#create-a-backup-that-can-then-be-used-with-docker-load)

```console
$ docker save busybox > busybox.tar

$ ls -sh busybox.tar

2.7M busybox.tar

$ docker save --output busybox.tar busybox

$ ls -sh busybox.tar

2.7M busybox.tar

$ docker save -o fedora-all.tar fedora

$ docker save -o fedora-latest.tar fedora:latest
```

### [Save an image to a tar.gz file using gzip](#save-an-image-to-a-targz-file-using-gzip)

You can use gzip to save the image file and make the backup smaller.

```console
$ docker save myimage:latest | gzip > myimage_latest.tar.gz
```

### [Cherry-pick particular tags](#cherry-pick-particular-tags)

You can even cherry-pick particular tags of an image repository.

```console
$ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy
```

### [Save a specific platform (--platform)](#platform)

The `--platform` option allows you to specify which platform variant of the image to save. By default, `docker save` saves all platform variants that are present in the daemon's image store. Use the `--platform` option to specify which platform variant of the image to save. An error is produced if the given platform is not present in the local image store.

The platform option takes the `os[/arch[/variant]]` format; for example, `linux/amd64` or `linux/arm64/v8`. Architecture and variant are optional, and default to the daemon's native architecture if omitted.

The following example pulls the RISC-V variant of the `alpine:latest` image and saves it to a tar archive.

```console
$ docker pull --platform=linux/riscv64 alpine:latest
latest: Pulling from library/alpine
8c4a05189a5f: Download complete
Digest: sha256:beefdbd8a1da6d2915566fde36db9db0b524eb737fc57cd1367effd16dc0d06d
Status: Downloaded newer image for alpine:latest
docker.io/library/alpine:latest

$ docker image save --platform=linux/riscv64 -o alpine-riscv.tar alpine:latest

$ ls -lh image.tar
-rw-------  1 thajeztah  staff   3.9M Oct  7 11:06 alpine-riscv.tar
```

The following example attempts to save a platform variant of `alpine:latest` that doesn't exist in the local image store, resulting in an error.

```console
$ docker image ls --tree
IMAGE                   ID             DISK USAGE   CONTENT SIZE   IN USE
alpine:latest           beefdbd8a1da       10.6MB         3.37MB
├─ linux/riscv64        80cde017a105       10.6MB         3.37MB
├─ linux/amd64          33735bd63cf8           0B             0B
├─ linux/arm/v6         50f635c8b04d           0B             0B
├─ linux/arm/v7         f2f82d424957           0B             0B
├─ linux/arm64/v8       9cee2b382fe2           0B             0B
├─ linux/386            b3e87f642f5c           0B             0B
├─ linux/ppc64le        c7a6800e3dc5           0B             0B
└─ linux/s390x          2b5b26e09ca2           0B             0B

$ docker image save --platform=linux/s390x -o alpine-s390x.tar alpine:latest
Error response from daemon: no suitable export target found for platform linux/s390x
```

----
url: https://docs.docker.com/reference/cli/docker/sandbox/create/kiro/
----

# docker sandbox create kiro

***

| Description | Create a sandbox for kiro                                   |
| ----------- | ----------------------------------------------------------- |
| Usage       | `docker sandbox create kiro WORKSPACE [EXTRA_WORKSPACE...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Create a sandbox with access to a host workspace for kiro.

The workspace path is required and will be exposed inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use 'docker sandbox run SANDBOX' to start kiro after creation.

## [Examples](#examples)

### [Create a Kiro sandbox in the current directory](#create-a-kiro-sandbox-in-the-current-directory)

```console
$ docker sandbox create kiro .
```

### [Create with an absolute path](#create-with-an-absolute-path)

```console
$ docker sandbox create kiro /home/user/my-project
```

### [Create and then run](#create-and-then-run)

```console
$ docker sandbox create --name my-kiro kiro ~/my-project
$ docker sandbox run my-kiro
```

----
url: https://docs.docker.com/get-started/docker-concepts/building-images/understanding-image-layers/
----

# Understanding the image layers

***

Table of contents

***

## [Explanation](#explanation)

As you learned in [What is an image?](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/), container images are composed of layers. And each of these layers, once created, are immutable. But, what does that actually mean? And how are those layers used to create the filesystem a container can use?

### [Image layers](#image-layers)

Each layer in an image contains a set of filesystem changes - additions, deletions, or modifications. Let’s look at a theoretical image:

1. The first layer adds basic commands and a package manager, such as apt.
2. The second layer installs a Python runtime and pip for dependency management.
3. The third layer copies in an application’s specific requirements.txt file.
4. The fourth layer installs that application’s specific dependencies.
5. The fifth layer copies in the actual source code of the application.

This example might look like:

This is beneficial because it allows layers to be reused between images. For example, imagine you wanted to create another Python application. Due to layering, you can leverage the same Python base. This will make builds faster and reduce the amount of storage and bandwidth required to distribute the images. The image layering might look similar to the following:

Layers let you extend images of others by reusing their base layers, allowing you to add only the data that your application needs.

### [Stacking the layers](#stacking-the-layers)

Layering is made possible by content-addressable storage and union filesystems. While this will get technical, here’s how it works:

1. After each layer is downloaded, it is extracted into its own directory on the host filesystem.
2. When you run a container from an image, a union filesystem is created where layers are stacked on top of each other, creating a new and unified view.
3. When the container starts, its root directory is set to the location of this unified directory, using `chroot`.

When the union filesystem is created, in addition to the image layers, a directory is created specifically for the running container. This allows the container to make filesystem changes while allowing the original image layers to remain untouched. This enables you to run multiple containers from the same underlying image.

## [Try it out](#try-it-out)

In this hands-on guide, you will create new image layers manually using the [`docker container commit`](https://docs.docker.com/reference/cli/docker/container/commit/) command. Note that you’ll rarely create images this way, as you’ll normally [use a Dockerfile](https://docs.docker.com/get-started/docker-concepts/building-images/writing-a-dockerfile/). But, it makes it easier to understand how it’s all working.

### [Create a base image](#create-a-base-image)

In this first step, you will create your own base image that you will then use for the following steps.

1. [Download and install](https://www.docker.com/products/docker-desktop/) Docker Desktop.

2. In a terminal, run the following command to start a new container:

   ```console
   $ docker run --name=base-container -ti ubuntu
   ```

   Once the image has been downloaded and the container has started, you should see a new shell prompt. This is running inside your container. It will look similar to the following (the container ID will vary):

   ```console
   root@d8c5ca119fcd:/#
   ```

3. Inside the container, run the following command to install Node.js:

   ```console
   $ apt update && apt install -y nodejs
   ```

   When this command runs, it downloads and installs Node inside the container. In the context of the union filesystem, these filesystem changes occur within the directory unique to this container.

4. Validate if Node is installed by running the following command:

   ```console
   $ node -e 'console.log("Hello world!")'
   ```

   You should then see a “Hello world!” appear in the console.

5. Now that you have Node installed, you’re ready to save the changes you’ve made as a new image layer, from which you can start new containers or build new images. To do so, you will use the [`docker container commit`](https://docs.docker.com/reference/cli/docker/container/commit/) command. Run the following command in a new terminal:

   ```console
   $ docker container commit -m "Add node" base-container node-base
   ```

6. View the layers of your image using the `docker image history` command:

   ```console
   $ docker image history node-base
   ```

   You will see output similar to the following:

   ```console
   IMAGE          CREATED          CREATED BY                                      SIZE      COMMENT
   9e274734bb25   10 seconds ago   /bin/bash                                       157MB     Add node
   cd1dba651b30   7 days ago       /bin/sh -c #(nop)  CMD ["/bin/bash"]            0B
   <missing>      7 days ago       /bin/sh -c #(nop) ADD file:6089c6bede9eca8ec…   110MB
   <missing>      7 days ago       /bin/sh -c #(nop)  LABEL org.opencontainers.…   0B
   <missing>      7 days ago       /bin/sh -c #(nop)  LABEL org.opencontainers.…   0B
   <missing>      7 days ago       /bin/sh -c #(nop)  ARG LAUNCHPAD_BUILD_ARCH     0B
   <missing>      7 days ago       /bin/sh -c #(nop)  ARG RELEASE                  0B
   ```

   Note the “Add node” comment on the top line. This layer contains the Node.js install you just made.

7. To prove your image has Node installed, you can start a new container using this new image:

   ```console
   $ docker run node-base node -e "console.log('Hello again')"
   ```

   With that, you should get a “Hello again” output in the terminal, showing Node was installed and working.

8. Now that you’re done creating your base image, you can remove that container:

   ```console
   $ docker rm -f base-container
   ```

> **Base image definition**
>
> A base image is a foundation for building other images. It's possible to use any images as a base image. However, some images are intentionally created as building blocks, providing a foundation or starting point for an application.
>
> In this example, you probably won’t deploy this `node-base` image, as it doesn’t actually do anything yet. But it’s a base you can use for other builds.

### [Build an app image](#build-an-app-image)

Now that you have a base image, you can extend that image to build additional images.

1. Start a new container using the newly created node-base image:

   ```console
   $ docker run --name=app-container -ti node-base
   ```

2. Inside of this container, run the following command to create a Node program:

   ```console
   $ echo 'console.log("Hello from an app")' > app.js
   ```

   To run this Node program, you can use the following command and see the message printed on the screen:

   ```console
   $ node app.js
   ```

3. In another terminal, run the following command to save this container’s changes as a new image:

   ```console
   $ docker container commit -c "CMD node app.js" -m "Add app" app-container sample-app
   ```

   This command not only creates a new image named `sample-app`, but also adds additional configuration to the image to set the default command when starting a container. In this case, you are setting it to automatically run `node app.js`.

4. In a terminal outside of the container, run the following command to view the updated layers:

   ```console
   $ docker image history sample-app
   ```

   You’ll then see output that looks like the following. Note the top layer comment has “Add app” and the next layer has “Add node”:

   ```console
   IMAGE          CREATED              CREATED BY                                      SIZE      COMMENT
   c1502e2ec875   About a minute ago   /bin/bash                                       33B       Add app
   5310da79c50a   4 minutes ago        /bin/bash                                       126MB     Add node
   2b7cc08dcdbb   5 weeks ago          /bin/sh -c #(nop)  CMD ["/bin/bash"]            0B
   <missing>      5 weeks ago          /bin/sh -c #(nop) ADD file:07cdbabf782942af0…   69.2MB
   <missing>      5 weeks ago          /bin/sh -c #(nop)  LABEL org.opencontainers.…   0B
   <missing>      5 weeks ago          /bin/sh -c #(nop)  LABEL org.opencontainers.…   0B
   <missing>      5 weeks ago          /bin/sh -c #(nop)  ARG LAUNCHPAD_BUILD_ARCH     0B
   <missing>      5 weeks ago          /bin/sh -c #(nop)  ARG RELEASE                  0B
   ```

5. Finally, start a new container using the brand new image. Since you specified the default command, you can use the following command:

   ```console
   $ docker run sample-app
   ```

   You should see your greeting appear in the terminal, coming from your Node program.

6. Now that you’re done with your containers, you can remove them using the following command:

   ```console
   $ docker rm -f app-container
   ```

## [Additional resources](#additional-resources)

If you’d like to dive deeper into the things you learned, check out the following resources:

* [`docker image history`](/reference/cli/docker/image/history/)
* [`docker container commit`](/reference/cli/docker/container/commit/)

## [Next steps](#next-steps)

As hinted earlier, most image builds don’t use `docker container commit`. Instead, you’ll use a Dockerfile which automates these steps for you.

[Writing a Dockerfile](https://docs.docker.com/get-started/docker-concepts/building-images/writing-a-dockerfile/)

----
url: https://docs.docker.com/guides/testcontainers-java-spring-boot-kafka/write-tests/
----

# Write tests with Testcontainers

***

Table of contents

***

To test the Kafka listener, you need a running Kafka broker and a MySQL database, plus a started Spring context. Testcontainers spins up both services in Docker containers and `@DynamicPropertySource` connects them to Spring.

## [Write the test](#write-the-test)

Create `ProductPriceChangedEventHandlerTest.java`:

```java
package com.testcontainers.demo;

import static java.util.concurrent.TimeUnit.SECONDS;
import static org.assertj.core.api.Assertions.assertThat;
import static org.awaitility.Awaitility.await;

import java.math.BigDecimal;
import java.time.Duration;
import java.util.Optional;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.kafka.core.KafkaTemplate;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.springframework.test.context.TestPropertySource;
import org.testcontainers.kafka.ConfluentKafkaContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@SpringBootTest
@TestPropertySource(
  properties = {
    "spring.kafka.consumer.auto-offset-reset=earliest",
    "spring.datasource.url=jdbc:tc:mysql:8.0.32:///db",
  }
)
@Testcontainers
class ProductPriceChangedEventHandlerTest {

  @Container
  static final ConfluentKafkaContainer kafka =
    new ConfluentKafkaContainer("confluentinc/cp-kafka:7.8.0");

  @DynamicPropertySource
  static void overrideProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.kafka.bootstrap-servers", kafka::getBootstrapServers);
  }

  @Autowired
  private KafkaTemplate<String, Object> kafkaTemplate;

  @Autowired
  private ProductRepository productRepository;

  @BeforeEach
  void setUp() {
    Product product = new Product(null, "P100", "Product One", BigDecimal.TEN);
    productRepository.save(product);
  }

  @Test
  void shouldHandleProductPriceChangedEvent() {
    ProductPriceChangedEvent event = new ProductPriceChangedEvent(
      "P100",
      new BigDecimal("14.50")
    );

    kafkaTemplate.send("product-price-changes", event.productCode(), event);

    await()
      .pollInterval(Duration.ofSeconds(3))
      .atMost(10, SECONDS)
      .untilAsserted(() -> {
        Optional<Product> optionalProduct = productRepository.findByCode(
          "P100"
        );
        assertThat(optionalProduct).isPresent();
        assertThat(optionalProduct.get().getCode()).isEqualTo("P100");
        assertThat(optionalProduct.get().getPrice())
          .isEqualTo(new BigDecimal("14.50"));
      });
  }
}
```

Here's what the test does:

* `@SpringBootTest` starts the full Spring application context.
* The Testcontainers special JDBC URL (`jdbc:tc:mysql:8.0.32:///db`) in `@TestPropertySource` spins up a MySQL container and configures it as the datasource automatically.
* `@Testcontainers` and `@Container` manage the lifecycle of the Kafka container. `@DynamicPropertySource` registers the Kafka bootstrap servers with Spring so that the producer and consumer connect to the test container.
* `@BeforeEach` creates a `Product` record in the database before each test.
* The test sends a `ProductPriceChangedEvent` to the `product-price-changes` topic using `KafkaTemplate`. Spring Boot converts the object to JSON using `JsonSerializer`.
* Because Kafka message processing is asynchronous, the test uses [Awaitility](http://www.awaitility.org/) to poll every 3 seconds (up to a maximum of 10 seconds) until the product price in the database matches the expected value.
* The property `spring.kafka.consumer.auto-offset-reset` is set to `earliest` so that the listener consumes messages even if they're sent to the topic before the listener is ready. This setting is helpful when running tests.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-spring-boot-kafka/run-tests/)

----
url: https://docs.docker.com/reference/cli/docker/desktop/logs/
----

# docker desktop logs

***

| Description | Print log entries for Docker Desktop |
| ----------- | ------------------------------------ |
| Usage       | `docker desktop logs [OPTIONS]`      |

## [Options](#options)

| Option             | Default         | Description                                                                                                                    |
| ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `-b, --boot`       |                 | Show logs from a specified boot. Zero means the current or boot, one the second last boot, and so on                           |
| `-c, --color`      |                 | Enable colored output. Priority levels are highlighted.                                                                        |
| `-m, --color-mode` |                 | Color mode to use. Can be `default` or `priority`                                                                              |
| `-D, --directory`  |                 | Specifies a custom directory to search for log entries                                                                         |
| `-p, --priority`   | `%!s(int64=-1)` | Filter output by log priorities. `-1` is all, `0` is info or above, `1` filters for warnings or above, `2` filters for errors. |
| `-S, --since`      |                 | Start showing entries on or newer than the specified date and time. Uses the systemd.time(7) format.                           |
| `-u, --unit`       |                 | Filter by one or more categories (e.g. `--unit=com.docker.backend.ipc`, `com.docker.backend.apiproxy`)                         |
| `-U, --until`      |                 | Start showing entries on or before the specified date and time. Uses the systemd.time(7) format.                               |

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/list/
----

# docker dhi customization list

***

| Description | List all customizations         |
| ----------- | ------------------------------- |
| Usage       | `docker dhi customization list` |

## [Description](#description)

List all Docker Hardened Images customizations

## [Options](#options)

| Option         | Default | Description                                                          |
| -------------- | ------- | -------------------------------------------------------------------- |
| `--bulk-id`    |         | Filter by bulk customization ID (exact match)                        |
| `-f, --filter` |         | Filter by customization name (case-insensitive substring match)      |
| `--json`       |         | Output in JSON format                                                |
| `-r, --repo`   |         | Filter by destination repository (case-insensitive substring match)  |
| `--source`     |         | Filter by DHI source repository (case-insensitive substring match)   |

----
url: https://docs.docker.com/reference/cli/docker/mcp/secret/
----

# docker mcp secret

***

| Description | Manage secrets in the local OS Keychain |
| ----------- | --------------------------------------- |

## [Description](#description)

Manage secrets in the local OS Keychain

## [Examples](#examples)

### [Pass the secret via STDIN](#pass-the-secret-via-stdin)

> echo my-secret-password > pwd.txt cat pwd.txt | docker mcp secret set POSTGRES\_PASSWORD

## [Subcommands](#subcommands)

| Command                                                                                 | Description                                                                               |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| [`docker mcp secret ls`](https://docs.docker.com/reference/cli/docker/mcp/secret/ls/)   | List all secrets from the local OS Keychain as well as any active Secrets Engine provider |
| [`docker mcp secret rm`](https://docs.docker.com/reference/cli/docker/mcp/secret/rm/)   | Remove secrets from the local OS Keychain                                                 |
| [`docker mcp secret set`](https://docs.docker.com/reference/cli/docker/mcp/secret/set/) | Set a secret in the local OS Keychain                                                     |

----
url: https://docs.docker.com/reference/cli/sbx/secret/set/
----

# sbx secret set

| Description | Create or update a secret                          |
| ----------- | -------------------------------------------------- |
| Usage       | `sbx secret set [-g \| SANDBOX] [SERVICE] [flags]` |

## [Description](#description)

Create or update a secret for a service or registry.

Available services: anthropic, aws, bedrock, cursor, droid, github, google, groq, mistral, nebius, openai, xai

When no arguments are provided, an interactive prompt guides you through scope and service selection.

Use --registry to store pull credentials for a container registry: Without -g: host-only — used for template/kit pulls, not injected into sandboxes. With -g: global — host pulls AND written as \~/.docker/config.json in every new sandbox. With SANDBOX as the first argument: scoped to that specific sandbox only.

## [Options](#options)

| Option             | Default | Description                                                       |
| ------------------ | ------- | ----------------------------------------------------------------- |
| `-f, --force`      |         | Overwrite an existing secret when --token is used                 |
| `-g, --global`     |         | Use global secret scope                                           |
| `--oauth`          |         | Start OAuth flow and store OAuth tokens (openai/global only)      |
| `--password-stdin` |         | Read registry password or token from stdin (use with --registry)  |
| `--registry`       |         | Registry hostname for pull credentials (e.g. ghcr.io)             |
| `-t, --token`      |         | Secret value (less secure: visible in shell history)              |
| `--username`       |         | Registry username (use with --registry; omit for token-only auth) |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Store a GitHub token globally (available to all sandboxes)
sbx secret set -g github

# Store an OpenAI key for a specific sandbox
sbx secret set my-sandbox openai

# Non-interactive via stdin (e.g., from a secret manager or env var)
echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic

# Start OpenAI OAuth flow and store global OAuth tokens
sbx secret set -g openai --oauth

# Registry: host-only (template/kit pulls, not injected into sandboxes)
gh auth token | sbx secret set --registry ghcr.io --password-stdin

# Registry: global (host pulls + injected into every new sandbox)
gh auth token | sbx secret set -g --registry ghcr.io --password-stdin

# Registry: specific sandbox only
gh auth token | sbx secret set my-sandbox --registry ghcr.io --password-stdin
```

----
url: https://docs.docker.com/reference/samples/ms-sql/
----

# MS-SQL samples

| Name                                                                                   | Description                                                    |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [ASP.NET / MS-SQL](https://github.com/docker/awesome-compose/tree/master/aspnet-mssql) | A sample ASP.NET core application with MS SQL server database. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/ai/docker-agent/integrations/
----

# Integrations

***

Table of contents

***

Agents created with Docker Agent can integrate with different environments depending on how you want to use them. Each integration type serves a specific purpose.

## [Integration types](#integration-types)

### [ACP - Editor integration](#acp---editor-integration)

Run agents directly in your editor (Neovim, Zed). The agent sees your editor's file context and can read and modify files through the editor's interface. Use ACP when you want an AI coding assistant embedded in your editor.

See [ACP integration](https://docs.docker.com/ai/docker-agent/integrations/acp/) for setup instructions.

### [MCP - Tool integration](#mcp---tool-integration)

Expose agents as tools in MCP clients like Claude Desktop or Claude Code. Your agents appear in the client's tool list, and the client can call them when needed. Use MCP when you want Claude Desktop (or another MCP client) to have access to your specialized agents.

See [MCP integration](https://docs.docker.com/ai/docker-agent/integrations/mcp/) for setup instructions.

### [A2A - Agent-to-agent communication](#a2a---agent-to-agent-communication)

Run agents as HTTP servers that other agents or systems can call using the Agent-to-Agent protocol. Your agent becomes a service that other systems can discover and invoke over the network. Use A2A when you want to build multi-agent systems or expose your agent as an HTTP service.

See [A2A integration](https://docs.docker.com/ai/docker-agent/integrations/a2a/) for setup instructions.

## [Choosing the right integration](#choosing-the-right-integration)

| Feature       | ACP                | MCP                | A2A                  |
| ------------- | ------------------ | ------------------ | -------------------- |
| Use case      | Editor integration | Agents as tools    | Agent-to-agent calls |
| Transport     | stdio              | stdio/SSE          | HTTP                 |
| Discovery     | Editor plugin      | Server manifest    | Agent card           |
| Best for      | Code editing       | Tool integration   | Multi-agent systems  |
| Communication | Editor calls agent | Client calls tools | Between agents       |

Choose ACP if you want your agent embedded in your editor while you code. Choose MCP if you want Claude Desktop (or another MCP client) to be able to call your specialized agents as tools. Choose A2A if you're building multi-agent systems where agents need to call each other over HTTP.

----
url: https://docs.docker.com/reference/cli/docker/container/run/
----

# docker container run

***

| Description                                                               | Create and run a new container from an image              |
| ------------------------------------------------------------------------- | --------------------------------------------------------- |
| Usage                                                                     | `docker container run [OPTIONS] IMAGE [COMMAND] [ARG...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker run`                                              |

## [Description](#description)

The `docker run` command runs a command in a new container, pulling the image if needed and starting the container.

You can restart a stopped container with all its previous changes intact using `docker start`. Use `docker ps -a` to view a list of all containers, including those that are stopped.

## [Options](#options)

| Option                                        | Default   | Description                                                                                                                                                                                                                                                                               |
| --------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`--add-host`](#add-host)                     |           | Add a custom host-to-IP mapping (host:ip)                                                                                                                                                                                                                                                 |
| `--annotation`                                |           | API 1.43+ Add an annotation to the container (passed through to the OCI runtime)                                                                                                                                                                                                          |
| [`-a, --attach`](#attach)                     |           | Attach to STDIN, STDOUT or STDERR                                                                                                                                                                                                                                                         |
| `--blkio-weight`                              |           | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)                                                                                                                                                                                                              |
| `--blkio-weight-device`                       |           | Block IO weight (relative device weight)                                                                                                                                                                                                                                                  |
| `--cap-add`                                   |           | Add Linux capabilities                                                                                                                                                                                                                                                                    |
| `--cap-drop`                                  |           | Drop Linux capabilities                                                                                                                                                                                                                                                                   |
| [`--cgroup-parent`](#cgroup-parent)           |           | Optional parent cgroup for the container                                                                                                                                                                                                                                                  |
| `--cgroupns`                                  |           | API 1.41+ Cgroup namespace to use (host\|private) 'host': Run the container in the Docker host's cgroup namespace 'private': Run the container in its own private cgroup namespace '': Use the cgroup namespace as configured by the default-cgroupns-mode option on the daemon (default) |
| [`--cidfile`](#cidfile)                       |           | Write the container ID to the file                                                                                                                                                                                                                                                        |
| `--cpu-count`                                 |           | CPU count (Windows only)                                                                                                                                                                                                                                                                  |
| `--cpu-percent`                               |           | CPU percent (Windows only)                                                                                                                                                                                                                                                                |
| `--cpu-period`                                |           | Limit CPU CFS (Completely Fair Scheduler) period                                                                                                                                                                                                                                          |
| `--cpu-quota`                                 |           | Limit CPU CFS (Completely Fair Scheduler) quota                                                                                                                                                                                                                                           |
| `--cpu-rt-period`                             |           | API 1.25+ Limit CPU real-time period in microseconds                                                                                                                                                                                                                                      |
| `--cpu-rt-runtime`                            |           | API 1.25+ Limit CPU real-time runtime in microseconds                                                                                                                                                                                                                                     |
| `-c, --cpu-shares`                            |           | CPU shares (relative weight)                                                                                                                                                                                                                                                              |
| `--cpus`                                      |           | API 1.25+ Number of CPUs                                                                                                                                                                                                                                                                  |
| `--cpuset-cpus`                               |           | CPUs in which to allow execution (0-3, 0,1)                                                                                                                                                                                                                                               |
| `--cpuset-mems`                               |           | MEMs in which to allow execution (0-3, 0,1)                                                                                                                                                                                                                                               |
| [`-d, --detach`](#detach)                     |           | Run container in background and print container ID                                                                                                                                                                                                                                        |
| [`--detach-keys`](#detach-keys)               |           | Override the key sequence for detaching a container                                                                                                                                                                                                                                       |
| [`--device`](#device)                         |           | Add a host device to the container                                                                                                                                                                                                                                                        |
| [`--device-cgroup-rule`](#device-cgroup-rule) |           | Add a rule to the cgroup allowed devices list                                                                                                                                                                                                                                             |
| `--device-read-bps`                           |           | Limit read rate (bytes per second) from a device                                                                                                                                                                                                                                          |
| `--device-read-iops`                          |           | Limit read rate (IO per second) from a device                                                                                                                                                                                                                                             |
| `--device-write-bps`                          |           | Limit write rate (bytes per second) to a device                                                                                                                                                                                                                                           |
| `--device-write-iops`                         |           | Limit write rate (IO per second) to a device                                                                                                                                                                                                                                              |
| `--dns`                                       |           | Set custom DNS servers                                                                                                                                                                                                                                                                    |
| `--dns-option`                                |           | Set DNS options                                                                                                                                                                                                                                                                           |
| `--dns-search`                                |           | Set custom DNS search domains                                                                                                                                                                                                                                                             |
| `--domainname`                                |           | Container NIS domain name                                                                                                                                                                                                                                                                 |
| `--entrypoint`                                |           | Overwrite the default ENTRYPOINT of the image                                                                                                                                                                                                                                             |
| [`-e, --env`](#env)                           |           | Set environment variables                                                                                                                                                                                                                                                                 |
| `--env-file`                                  |           | Read in a file of environment variables                                                                                                                                                                                                                                                   |
| `--expose`                                    |           | Expose a port or a range of ports                                                                                                                                                                                                                                                         |
| [`--gpus`](#gpus)                             |           | API 1.40+ GPU devices to add to the container ('all' to pass all GPUs)                                                                                                                                                                                                                    |
| `--group-add`                                 |           | Add additional groups to join                                                                                                                                                                                                                                                             |
| `--health-cmd`                                |           | Command to run to check health                                                                                                                                                                                                                                                            |
| `--health-interval`                           |           | Time between running the check (ms\|s\|m\|h) (default 0s)                                                                                                                                                                                                                                 |
| `--health-retries`                            |           | Consecutive failures needed to report unhealthy                                                                                                                                                                                                                                           |
| `--health-start-interval`                     |           | API 1.44+ Time between running the check during the start period (ms\|s\|m\|h) (default 0s)                                                                                                                                                                                               |
| `--health-start-period`                       |           | API 1.29+ Start period for the container to initialize before starting health-retries countdown (ms\|s\|m\|h) (default 0s)                                                                                                                                                                |
| `--health-timeout`                            |           | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s)                                                                                                                                                                                                                         |
| `--help`                                      |           | Print usage                                                                                                                                                                                                                                                                               |
| `-h, --hostname`                              |           | Container host name                                                                                                                                                                                                                                                                       |
| [`--init`](#init)                             |           | API 1.25+ Run an init inside the container that forwards signals and reaps processes                                                                                                                                                                                                      |
| [`-i, --interactive`](#interactive)           |           | Keep STDIN open even if not attached                                                                                                                                                                                                                                                      |
| `--io-maxbandwidth`                           |           | Maximum IO bandwidth limit for the system drive (Windows only)                                                                                                                                                                                                                            |
| `--io-maxiops`                                |           | Maximum IOps limit for the system drive (Windows only)                                                                                                                                                                                                                                    |
| `--ip`                                        | ``        | IPv4 address (e.g., 172.30.100.104)                                                                                                                                                                                                                                                       |
| `--ip6`                                       | ``        | IPv6 address (e.g., 2001:db8::33)                                                                                                                                                                                                                                                         |
| [`--ipc`](#ipc)                               |           | IPC mode to use                                                                                                                                                                                                                                                                           |
| [`--isolation`](#isolation)                   |           | Container isolation technology                                                                                                                                                                                                                                                            |
| [`-l, --label`](#label)                       |           | Set meta data on a container                                                                                                                                                                                                                                                              |
| `--label-file`                                |           | Read in a line delimited file of labels                                                                                                                                                                                                                                                   |
| `--link`                                      |           | Add link to another container                                                                                                                                                                                                                                                             |
| `--link-local-ip`                             |           | Container IPv4/IPv6 link-local addresses                                                                                                                                                                                                                                                  |
| [`--log-driver`](#log-driver)                 |           | Logging driver for the container                                                                                                                                                                                                                                                          |
| `--log-opt`                                   |           | Log driver options                                                                                                                                                                                                                                                                        |
| `--mac-address`                               |           | Container MAC address (e.g., 92:d0:c6:0a:29:33)                                                                                                                                                                                                                                           |
| [`-m, --memory`](#memory)                     |           | Memory limit                                                                                                                                                                                                                                                                              |
| `--memory-reservation`                        |           | Memory soft limit                                                                                                                                                                                                                                                                         |
| `--memory-swap`                               |           | Swap limit equal to memory plus swap: '-1' to enable unlimited swap                                                                                                                                                                                                                       |
| `--memory-swappiness`                         | `-1`      | Tune container memory swappiness (0 to 100)                                                                                                                                                                                                                                               |
| [`--mount`](#mount)                           |           | Attach a filesystem mount to the container                                                                                                                                                                                                                                                |
| [`--name`](#name)                             |           | Assign a name to the container                                                                                                                                                                                                                                                            |
| [`--network`](#network)                       |           | Connect a container to a network                                                                                                                                                                                                                                                          |
| `--network-alias`                             |           | Add network-scoped alias for the container                                                                                                                                                                                                                                                |
| `--no-healthcheck`                            |           | Disable any container-specified HEALTHCHECK                                                                                                                                                                                                                                               |
| `--oom-kill-disable`                          |           | Disable OOM Killer                                                                                                                                                                                                                                                                        |
| `--oom-score-adj`                             |           | Tune host's OOM preferences (-1000 to 1000)                                                                                                                                                                                                                                               |
| [`--pid`](#pid)                               |           | PID namespace to use                                                                                                                                                                                                                                                                      |
| `--pids-limit`                                |           | Tune container pids limit (set -1 for unlimited)                                                                                                                                                                                                                                          |
| `--platform`                                  |           | API 1.32+ Set platform if server is multi-platform capable                                                                                                                                                                                                                                |
| [`--privileged`](#privileged)                 |           | Give extended privileges to this container                                                                                                                                                                                                                                                |
| [`-p, --publish`](#publish)                   |           | Publish a container's port(s) to the host                                                                                                                                                                                                                                                 |
| [`-P, --publish-all`](#publish-all)           |           | Publish all exposed ports to random ports                                                                                                                                                                                                                                                 |
| [`--pull`](#pull)                             | `missing` | Pull image before running (`always`, `missing`, `never`)                                                                                                                                                                                                                                  |
| `-q, --quiet`                                 |           | Suppress the pull output                                                                                                                                                                                                                                                                  |
| [`--read-only`](#read-only)                   |           | Mount the container's root filesystem as read only                                                                                                                                                                                                                                        |
| [`--restart`](#restart)                       | `no`      | Restart policy to apply when a container exits                                                                                                                                                                                                                                            |
| [`--rm`](#rm)                                 |           | Automatically remove the container and its associated anonymous volumes when it exits                                                                                                                                                                                                     |
| `--runtime`                                   |           | Runtime to use for this container                                                                                                                                                                                                                                                         |
| [`--security-opt`](#security-opt)             |           | Security Options                                                                                                                                                                                                                                                                          |
| `--shm-size`                                  |           | Size of /dev/shm                                                                                                                                                                                                                                                                          |
| `--sig-proxy`                                 | `true`    | Proxy received signals to the process                                                                                                                                                                                                                                                     |
| [`--stop-signal`](#stop-signal)               |           | Signal to stop the container                                                                                                                                                                                                                                                              |
| [`--stop-timeout`](#stop-timeout)             |           | API 1.25+ Timeout (in seconds) to stop a container                                                                                                                                                                                                                                        |
| [`--storage-opt`](#storage-opt)               |           | Storage driver options for the container                                                                                                                                                                                                                                                  |
| [`--sysctl`](#sysctl)                         |           | Sysctl options                                                                                                                                                                                                                                                                            |
| [`--tmpfs`](#tmpfs)                           |           | Mount a tmpfs directory                                                                                                                                                                                                                                                                   |
| [`-t, --tty`](#tty)                           |           | Allocate a pseudo-TTY                                                                                                                                                                                                                                                                     |
| [`--ulimit`](#ulimit)                         |           | Ulimit options                                                                                                                                                                                                                                                                            |
| `--use-api-socket`                            |           | Bind mount Docker API socket and required auth                                                                                                                                                                                                                                            |
| `-u, --user`                                  |           | Username or UID (format: \<name\|uid>\[:\<group\|gid>])                                                                                                                                                                                                                                   |
| [`--userns`](#userns)                         |           | User namespace to use                                                                                                                                                                                                                                                                     |
| [`--uts`](#uts)                               |           | UTS namespace to use                                                                                                                                                                                                                                                                      |
| [`-v, --volume`](#volume)                     |           | Bind mount a volume                                                                                                                                                                                                                                                                       |
| `--volume-driver`                             |           | Optional volume driver for the container                                                                                                                                                                                                                                                  |
| [`--volumes-from`](#volumes-from)             |           | Mount volumes from the specified container(s)                                                                                                                                                                                                                                             |
| [`-w, --workdir`](#workdir)                   |           | Working directory inside the container                                                                                                                                                                                                                                                    |

## [Examples](#examples)

### [Assign name (--name)](#name)

The `--name` flag lets you specify a custom identifier for a container. The following example runs a container named `test` using the `nginx:alpine` image in [detached mode](#detach).

```console
$ docker run --name test -d nginx:alpine
4bed76d3ad428b889c56c1ecc2bf2ed95cb08256db22dc5ef5863e1d03252a19
$ docker ps
CONTAINER ID   IMAGE          COMMAND                  CREATED        STATUS                  PORTS     NAMES
4bed76d3ad42   nginx:alpine   "/docker-entrypoint.…"   1 second ago   Up Less than a second   80/tcp    test
```

You can reference the container by name with other commands. For example, the following commands stop and remove a container named `test`:

```console
$ docker stop test
test
$ docker rm test
test
```

If you don't specify a custom name using the `--name` flag, the daemon assigns a randomly generated name, such as `vibrant_cannon`, to the container. Using a custom-defined name provides the benefit of having an easy-to-remember ID for a container.

Moreover, if you connect the container to a user-defined bridge network, other containers on the same network can refer to the container by name via DNS.

```console
$ docker network create mynet
cb79f45948d87e389e12013fa4d969689ed2c3316985dd832a43aaec9a0fe394
$ docker run --name test --net mynet -d nginx:alpine
58df6ecfbc2ad7c42d088ed028d367f9e22a5f834d7c74c66c0ab0485626c32a
$ docker run --net mynet busybox:latest ping test
PING test (172.18.0.2): 56 data bytes
64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.073 ms
64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.411 ms
64 bytes from 172.18.0.2: seq=2 ttl=64 time=0.319 ms
64 bytes from 172.18.0.2: seq=3 ttl=64 time=0.383 ms
...
```

### [Capture container ID (--cidfile)](#cidfile)

To help with automation, you can have Docker write the container ID out to a file of your choosing. This is similar to how some programs might write out their process ID to a file (you might've seen them as PID files):

```console
$ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
```

This creates a container and prints `test` to the console. The `cidfile` flag makes Docker attempt to create a new file and write the container ID to it. If the file exists already, Docker returns an error. Docker closes this file when `docker run` exits.

### [PID settings (--pid)](#pid)

```text
--pid=""  : Set the PID (Process) Namespace mode for the container,
             'container:<name|id>': joins another container's PID namespace
             'host': use the host's PID namespace inside the container
```

By default, all containers have the PID namespace enabled.

PID namespace provides separation of processes. The PID Namespace removes the view of the system processes, and allows process ids to be reused including PID 1.

In certain cases you want your container to share the host's process namespace, allowing processes within the container to see all of the processes on the system. For example, you could build a container with debugging tools like `strace` or `gdb`, but want to use these tools when debugging processes within the container.

#### [Example: run htop inside a container](#example-run-htop-inside-a-container)

To run `htop` in a container that shares the process namespac of the host:

1. Run an alpine container with the `--pid=host` option:

   ```console
   $ docker run --rm -it --pid=host alpine
   ```

2. Install `htop` in the container:

   ```console
   / # apk add --quiet htop
   ```

3. Invoke the `htop` command.

   ```console
   / # htop
   ```

#### [Example, join another container's PID namespace](#example-join-another-containers-pid-namespace)

Joining another container's PID namespace can be useful for debugging that container.

1. Start a container running a Redis server:

   ```console
   $ docker run --rm --name my-nginx -d nginx:alpine
   ```

2. Run an Alpine container that attaches the `--pid` namespace to the `my-nginx` container:

   ```console
   $ docker run --rm -it --pid=container:my-nginx \
     --cap-add SYS_PTRACE \
     --security-opt seccomp=unconfined \
     alpine
   ```

3. Install `strace` in the Alpine container:

   ```console
   / # apk add strace
   ```

4. Attach to process 1, the process ID of the `my-nginx` container:

   ```console
   / # strace -p 1
   strace: Process 1 attached
   ```

### [Disable namespace remapping for a container (--userns)](#userns)

If you enable user namespaces on the daemon, all containers are started with user namespaces enabled by default. To disable user namespace remapping for a specific container, you can set the `--userns` flag to `host`.

```console
docker run --userns=host hello-world
```

`host` is the only valid value for the `--userns` flag.

For more information, refer to [Isolate containers with a user namespace](/engine/security/userns-remap/).

### [UTS settings (--uts)](#uts)

```text
--uts=""  : Set the UTS namespace mode for the container
            'host': use the host's UTS namespace inside the container
```

The UTS namespace is for setting the hostname and the domain that's visible to running processes in that namespace. By default, all containers, including those with `--network=host`, have their own UTS namespace. Setting `--uts` to `host` results in the container using the same UTS namespace as the host.

> Note
>
> Docker disallows combining the `--hostname` and `--domainname` flags with `--uts=host`. This is to prevent containers running in the host's UTS namespace from attempting to change the hosts' configuration.

You may wish to share the UTS namespace with the host if you would like the hostname of the container to change as the hostname of the host changes. A more advanced use case would be changing the host's hostname from a container.

### [IPC settings (--ipc)](#ipc)

```text
--ipc="MODE"  : Set the IPC mode for the container
```

The `--ipc` flag accepts the following values:

| Value                      | Description                                                                      |
| -------------------------- | -------------------------------------------------------------------------------- |
| ""                         | Use daemon's default.                                                            |
| "none"                     | Own private IPC namespace, with /dev/shm not mounted.                            |
| "private"                  | Own private IPC namespace.                                                       |
| "shareable"                | Own private IPC namespace, with a possibility to share it with other containers. |
| "container:<*name-or-ID*>" | Join another ("shareable") container's IPC namespace.                            |
| "host"                     | Use the host system's IPC namespace.                                             |

If not specified, daemon default is used, which can either be `"private"` or `"shareable"`, depending on the daemon version and configuration.

[System V interprocess communication (IPC)](https://linux.die.net/man/5/ipc) namespaces provide separation of named shared memory segments, semaphores and message queues.

Shared memory segments are used to accelerate inter-process communication at memory speed, rather than through pipes or through the network stack. Shared memory is commonly used by databases and custom-built (typically C/OpenMPI, C++/using boost libraries) high performance applications for scientific computing and financial services industries. If these types of applications are broken into multiple containers, you might need to share the IPC mechanisms of the containers, using `"shareable"` mode for the main (i.e. "donor") container, and `"container:<donor-name-or-ID>"` for other containers.

### [Escalate container privileges (--privileged)](#privileged)

The `--privileged` flag gives the following capabilities to a container:

* Enables all Linux kernel capabilities
* Disables the default seccomp profile
* Disables the default AppArmor profile
* Disables the SELinux process label
* Grants access to all host devices
* Makes `/sys` read-write
* Makes cgroups mounts read-write

In other words, the container can then do almost everything that the host can do. This flag exists to allow special use-cases, like running Docker within Docker.

> Warning
>
> Use the `--privileged` flag with caution. A container with `--privileged` is not a securely sandboxed process. Containers in this mode can get a root shell on the host and take control over the system.
>
> For most use cases, this flag should not be the preferred solution. If your container requires escalated privileges, you should prefer to explicitly grant the necessary permissions, for example by adding individual kernel capabilities with `--cap-add`.
>
> For more information, see [Runtime privilege and Linux capabilities](/engine/containers/run/#runtime-privilege-and-linux-capabilities)

The following example doesn't work, because by default, Docker drops most potentially dangerous kernel capabilities, including `CAP_SYS_ADMIN `(which is required to mount filesystems).

```console
$ docker run -t -i --rm ubuntu bash
root@bc338942ef20:/# mount -t tmpfs none /mnt
mount: permission denied
```

It works when you add the `--privileged` flag:

```console
$ docker run -t -i --privileged ubuntu bash
root@50e3f57e16e6:/# mount -t tmpfs none /mnt
root@50e3f57e16e6:/# df -h
Filesystem      Size  Used Avail Use% Mounted on
none            1.9G     0  1.9G   0% /mnt
```

### [Set working directory (-w, --workdir)](#workdir)

```console
$ docker run -w /path/to/dir/ ubuntu pwd
```

The `-w` option runs the command executed inside the directory specified, in this example, `/path/to/dir/`. If the path doesn't exist, Docker creates it inside the container.

### [Set storage driver options per container (--storage-opt)](#storage-opt)

```console
$ docker run -it --storage-opt size=120G fedora /bin/bash
```

This (size) constraints the container filesystem size to 120G at creation time. This option is only available for the `btrfs`, `overlay2`, `windowsfilter`, and `zfs` storage drivers.

For the `overlay2` storage driver, the size option is only available if the backing filesystem is `xfs` and mounted with the `pquota` mount option. Under these conditions, you can pass any size less than the backing filesystem size.

For the `windowsfilter`, `btrfs`, and `zfs` storage drivers, you cannot pass a size less than the Default BaseFS Size.

### [Mount tmpfs (--tmpfs)](#tmpfs)

The `--tmpfs` flag lets you create a `tmpfs` mount.

The options that you can pass to `--tmpfs` are identical to the Linux `mount -t tmpfs -o` command. The following example mounts an empty `tmpfs` into the container with the `rw`, `noexec`, `nosuid`, `size=65536k` options.

```console
$ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image
```

For more information, see [tmpfs mounts](/storage/tmpfs/).

### [Mount volume (-v)](#volume)

```console
$ docker  run  -v $(pwd):$(pwd) -w $(pwd) -i -t  ubuntu pwd
```

The example above mounts the current directory into the container at the same path using the `-v` flag, sets it as the working directory, and then runs the `pwd` command inside the container.

As of Docker Engine version 23, you can use relative paths on the host.

```console
$ docker  run  -v ./content:/content -w /content -i -t  ubuntu pwd
```

The example above mounts the `content` directory in the current directory into the container at the `/content` path using the `-v` flag, sets it as the working directory, and then runs the `pwd` command inside the container.

```console
$ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash
```

When the host directory of a bind-mounted volume doesn't exist, Docker automatically creates this directory on the host for you. In the example above, Docker creates the `/doesnt/exist` folder before starting your container.

### [Mount volume read-only (--read-only)](#read-only)

```console
$ docker run --read-only -v /icanwrite busybox touch /icanwrite/here
```

You can use volumes in combination with the `--read-only` flag to control where a container writes files. The `--read-only` flag mounts the container's root filesystem as read only prohibiting writes to locations other than the specified volumes for the container.

```console
$ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh
```

By bind-mounting the Docker Unix socket and statically linked Docker binary (refer to [get the Linux binary](/engine/install/binaries/#install-static-binaries)), you give the container the full access to create and manipulate the host's Docker daemon.

On Windows, you must specify the paths using Windows-style path semantics.

```powershell
PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt
Contents of file

PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt
Contents of file
```

The following examples fails when using Windows-based containers, as the destination of a volume or bind mount inside the container must be one of: a non-existing or empty directory; or a drive other than `C:`. Further, the source of a bind mount must be a local directory, not a file.

```powershell
net use z: \\remotemachine\share
docker run -v z:\foo:c:\dest ...
docker run -v \\uncpath\to\directory:c:\dest ...
docker run -v c:\foo\somefile.txt:c:\dest ...
docker run -v c:\foo:c: ...
docker run -v c:\foo:c:\existing-directory-with-contents ...
```

For in-depth information about volumes, refer to [manage data in containers](/storage/volumes/)

### [Add bind mounts or volumes using the --mount flag](#mount)

The `--mount` flag allows you to mount volumes, host-directories, and `tmpfs` mounts in a container.

The `--mount` flag supports most options supported by the `-v` or the `--volume` flag, but uses a different syntax. For in-depth information on the `--mount` flag, and a comparison between `--volume` and `--mount`, refer to [Bind mounts](/storage/bind-mounts/).

Even though there is no plan to deprecate `--volume`, usage of `--mount` is recommended.

Examples:

```console
$ docker run --read-only --mount type=volume,target=/icanwrite busybox touch /icanwrite/here
```

```console
$ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh
```

### [Publish or expose port (-p, --expose)](#publish)

```console
$ docker run -p 127.0.0.1:80:8080/tcp nginx:alpine
```

This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host. You can also specify `udp` and `sctp` ports. The [Networking overview page](/network/) explains in detail how to publish ports with Docker.

> Note
>
> If you don't specify an IP address (i.e., `-p 80:80` instead of `-p 127.0.0.1:80:80`) when publishing a container's ports, Docker publishes the port on all interfaces (address `0.0.0.0`) by default. These ports are externally accessible. This also applies if you configured UFW to block this specific port, as Docker manages its own iptables rules. [Read more](/network/packet-filtering-firewalls/)

```console
$ docker run --expose 80 nginx:alpine
```

This exposes port `80` of the container without publishing the port to the host system's interfaces.

### [Publish all exposed ports (-P, --publish-all)](#publish-all)

```console
$ docker run -P nginx:alpine
```

The `-P`, or `--publish-all`, flag publishes all the exposed ports to the host. Docker binds each exposed port to a random port on the host.

The `-P` flag only publishes port numbers that are explicitly flagged as exposed, either using the Dockerfile `EXPOSE` instruction or the `--expose` flag for the `docker run` command.

The range of ports are within an *ephemeral port range* defined by `/proc/sys/net/ipv4/ip_local_port_range`. Use the `-p` flag to explicitly map a single port or range of ports.

### [Set the pull policy (--pull)](#pull)

Use the `--pull` flag to set the image pull policy when creating (and running) the container.

The `--pull` flag can take one of these values:

| Value               | Description                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `missing` (default) | Pull the image if it was not found in the image cache, or use the cached image otherwise.                         |
| `never`             | Do not pull the image, even if it's missing, and produce an error if the image does not exist in the image cache. |
| `always`            | Always perform a pull before creating the container.                                                              |

When creating (and running) a container from an image, the daemon checks if the image exists in the local image cache. If the image is missing, an error is returned to the CLI, allowing it to initiate a pull.

The default (`missing`) is to only pull the image if it's not present in the daemon's image cache. This default allows you to run images that only exist locally (for example, images you built from a Dockerfile, but that have not been pushed to a registry), and reduces networking.

The `always` option always initiates a pull before creating the container. This option makes sure the image is up-to-date, and prevents you from using outdated images, but may not be suitable in situations where you want to test a locally built image before pushing (as pulling the image overwrites the existing image in the image cache).

The `never` option disables (implicit) pulling images when creating containers, and only uses images that are available in the image cache. If the specified image is not found, an error is produced, and the container is not created. This option is useful in situations where networking is not available, or to prevent images from being pulled implicitly when creating containers.

The following example shows `docker run` with the `--pull=never` option set, which produces en error as the image is missing in the image-cache:

```console
$ docker run --pull=never hello-world
docker: Error response from daemon: No such image: hello-world:latest.
```

### [Set environment variables (-e, --env, --env-file)](#env)

```console
$ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
```

Use the `-e`, `--env`, and `--env-file` flags to set simple (non-array) environment variables in the container you're running, or overwrite variables defined in the Dockerfile of the image you're running.

You can define the variable and its value when running the container:

```console
$ docker run --env VAR1=value1 --env VAR2=value2 ubuntu env | grep VAR
VAR1=value1
VAR2=value2
```

You can also use variables exported to your local environment:

```console
export VAR1=value1
export VAR2=value2

$ docker run --env VAR1 --env VAR2 ubuntu env | grep VAR
VAR1=value1
VAR2=value2
```

When running the command, the Docker CLI client checks the value the variable has in your local environment and passes it to the container. If no `=` is provided and that variable isn't exported in your local environment, the variable is unset in the container.

You can also load the environment variables from a file. This file should use the syntax `<variable>=value` (which sets the variable to the given value) or `<variable>` (which takes the value from the local environment), and `#` for comments. Lines beginning with `#` are treated as line comments and are ignored, whereas a `#` appearing anywhere else in a line is treated as part of the variable value.

```console
$ cat env.list
# This is a comment
VAR1=value1
VAR2=value2
USER

$ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER'
VAR1=value1
VAR2=value2
USER=jonzeolla
```

### [Set metadata on container (-l, --label, --label-file)](#label)

A label is a `key=value` pair that applies metadata to a container. To label a container with two labels:

```console
$ docker run -l my-label --label com.example.foo=bar ubuntu bash
```

The `my-label` key doesn't specify a value so the label defaults to an empty string (`""`). To add multiple labels, repeat the label flag (`-l` or `--label`).

The `key=value` must be unique to avoid overwriting the label value. If you specify labels with identical keys but different values, each subsequent value overwrites the previous. Docker uses the last `key=value` you supply.

Use the `--label-file` flag to load multiple labels from a file. Delimit each label in the file with an EOL mark. The example below loads labels from a labels file in the current directory:

```console
$ docker run --label-file ./labels ubuntu bash
```

The label-file format is similar to the format for loading environment variables. (Unlike environment variables, labels are not visible to processes running inside a container.) The following example shows a label-file format:

```console
com.example.label1="a label"

# this is a comment
com.example.label2=another\ label
com.example.label3
```

You can load multiple label-files by supplying multiple `--label-file` flags.

For additional information on working with labels, see [Labels](/config/labels-custom-metadata/).

### [Connect a container to a network (--network)](#network)

To start a container and connect it to a network, use the `--network` option.

If you want to add a running container to a network use the `docker network connect` subcommand.

You can connect multiple containers to the same network. Once connected, the containers can communicate using only another container's IP address or name. For `overlay` networks or custom plugins that support multi-host connectivity, containers connected to the same multi-host network but launched from different Engines can also communicate in this way.

> Note
>
> The default bridge network only allows containers to communicate with each other using internal IP addresses. User-created bridge networks provide DNS resolution between containers using container names.

You can disconnect a container from a network using the `docker network disconnect` command.

The following commands create a network named `my-net` and add a `busybox` container to the `my-net` network.

```console
$ docker network create my-net
$ docker run -itd --network=my-net busybox
```

You can also choose the IP addresses for the container with `--ip` and `--ip6` flags when you start the container on a user-defined network. To assign a static IP to containers, you must specify subnet block for the network.

```console
$ docker network create --subnet 192.0.2.0/24 my-net
$ docker run -itd --network=my-net --ip=192.0.2.69 busybox
```

To connect the container to more than one network, repeat the `--network` option.

```console
$ docker network create --subnet 192.0.2.0/24 my-net1
$ docker network create --subnet 192.0.3.0/24 my-net2
$ docker run -itd --network=my-net1 --network=my-net2 busybox
```

To specify options when connecting to more than one network, use the extended syntax for the `--network` flag. Comma-separated options that can be specified in the extended `--network` syntax are:

| Option          | Top-level Equivalent                  | Description                                                                             |
| --------------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
| `name`          |                                       | The name of the network (mandatory)                                                     |
| `alias`         | `--network-alias`                     | Add network-scoped alias for the container                                              |
| `ip`            | `--ip`                                | IPv4 address (e.g., 172.30.100.104)                                                     |
| `ip6`           | `--ip6`                               | IPv6 address (e.g., 2001:db8::33)                                                       |
| `mac-address`   | `--mac-address`                       | Container MAC address (e.g., 92:d0:c6:0a:29:33)                                         |
| `link-local-ip` | `--link-local-ip`                     | Container IPv4/IPv6 link-local addresses                                                |
| `driver-opt`    | `docker network connect --driver-opt` | Network driver options                                                                  |
| `gw-priority`   |                                       | Highest gw-priority provides the default gateway. Accepts positive and negative values. |

```console
$ docker network create --subnet 192.0.2.0/24 my-net1
$ docker network create --subnet 192.0.3.0/24 my-net2
$ docker run -itd --network=name=my-net1,ip=192.0.2.42 --network=name=my-net2,ip=192.0.3.42 busybox
```

`sysctl` settings that start with `net.ipv4.`, `net.ipv6.` or `net.mpls.` can be set per-interface using `driver-opt` label `com.docker.network.endpoint.sysctls`. The interface name must be the string `IFNAME`.

To set more than one `sysctl` for an interface, quote the whole `driver-opt` field, remembering to escape the quotes for the shell if necessary. For example, if the interface to `my-net` is given name `eth0`, the following example sets sysctls `net.ipv4.conf.eth0.log_martians=1` and `net.ipv4.conf.eth0.forwarding=0`, and assigns the IPv4 address `192.0.2.42`.

```console
$ docker network create --subnet 192.0.2.0/24 my-net
$ docker run -itd --network=name=my-net,\"driver-opt=com.docker.network.endpoint.sysctls=net.ipv4.conf.IFNAME.log_martians=1,net.ipv4.conf.IFNAME.forwarding=0\",ip=192.0.2.42 busybox
```

> Note
>
> Network drivers may restrict the sysctl settings that can be modified and, to protect the operation of the network, new restrictions may be added in the future.

For more information on connecting a container to a network when using the `run` command, see the [Docker network overview](/network/).

### [Mount volumes from container (--volumes-from)](#volumes-from)

```console
$ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd
```

The `--volumes-from` flag mounts all the defined volumes from the referenced containers. You can specify more than one container by repetitions of the `--volumes-from` argument. The container ID may be optionally suffixed with `:ro` or `:rw` to mount the volumes in read-only or read-write mode, respectively. By default, Docker mounts the volumes in the same mode (read write or read only) as the reference container.

Labeling systems like SELinux require placing proper labels on volume content mounted into a container. Without a label, the security system might prevent the processes running inside the container from using the content. By default, Docker does not change the labels set by the OS.

To change the label in the container context, you can add either of two suffixes `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file objects on the shared volumes. The `z` option tells Docker that two containers share the volume content. As a result, Docker labels the content with a shared content label. Shared volume labels allow all containers to read/write content. The `Z` option tells Docker to label the content with a private unshared label. Only the current container can use a private volume.

### [Detached mode (-d, --detach)](#detach)

The `--detach` (or `-d`) flag starts a container as a background process that doesn't occupy your terminal window. By design, containers started in detached mode exit when the root process used to run the container exits, unless you also specify the `--rm` option. If you use `-d` with `--rm`, the container is removed when it exits or when the daemon exits, whichever happens first.

Don't pass a `service x start` command to a detached container. For example, this command attempts to start the `nginx` service.

```console
$ docker run -d -p 80:80 my_image service nginx start
```

This succeeds in starting the `nginx` service inside the container. However, it fails the detached container paradigm in that, the root process (`service nginx start`) returns and the detached container stops as designed. As a result, the `nginx` service starts but can't be used. Instead, to start a process such as the `nginx` web server do the following:

```console
$ docker run -d -p 80:80 my_image nginx -g 'daemon off;'
```

To do input/output with a detached container use network connections or shared volumes. These are required because the container is no longer listening to the command line where `docker run` was run.


### [Add host device to container (--device)](#device)

```console
$ docker run -it --rm \
    --device=/dev/sdc:/dev/xvdc \
    --device=/dev/sdd \
    --device=/dev/zero:/dev/foobar \
    ubuntu ls -l /dev/{xvdc,sdd,foobar}

brw-rw---- 1 root disk 8, 2 Feb  9 16:05 /dev/xvdc
brw-rw---- 1 root disk 8, 3 Feb  9 16:05 /dev/sdd
crw-rw-rw- 1 root root 1, 5 Feb  9 16:05 /dev/foobar
```

It's often necessary to directly expose devices to a container. The `--device` option enables that. For example, adding a specific block storage device or loop device or audio device to an otherwise unprivileged container (without the `--privileged` flag) and have the application directly access it.

By default, the container is able to `read`, `write` and `mknod` these devices. This can be overridden using a third `:rwm` set of options to each `--device` flag. If the container is running in privileged mode, then Docker ignores the specified permissions.

```console
$ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk  /dev/xvdc

Command (m for help): q
$ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk  /dev/xvdc
You will not be able to write the partition table.

Command (m for help): q

$ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk  /dev/xvdc

Command (m for help): q

$ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk  /dev/xvdc
fdisk: unable to open /dev/xvdc: Operation not permitted
```

> Note
>
> The `--device` option cannot be safely used with ephemeral devices. You shouldn't add block devices that may be removed to untrusted containers with `--device`.

For Windows, the format of the string passed to the `--device` option is in the form of `--device=<IdType>/<Id>`. Beginning with Windows Server 2019 and Windows 10 October 2018 Update, Windows only supports an IdType of `class` and the Id as a [device interface class GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). Refer to the table defined in the [Windows container docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers) for a list of container-supported device interface class GUIDs.

If you specify this option for a process-isolated Windows container, Docker makes *all* devices that implement the requested device interface class GUID available in the container. For example, the command below makes all COM ports on the host visible in the container.

```powershell
PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.microsoft.com/windows/servercore:ltsc2019
```

> Note
>
> The `--device` option is only supported on process-isolated Windows containers, and produces an error if the container isolation is `hyperv`.

#### [CDI devices](#cdi-devices)

[Container Device Interface (CDI)](https://github.com/cncf-tags/container-device-interface/blob/main/SPEC.md) is a standardized mechanism for container runtimes to create containers which are able to interact with third party devices.

CDI is currently only supported for Linux containers and is enabled by default since Docker Engine 28.3.0.

With CDI, device configurations are declaratively defined using a JSON or YAML file. In addition to enabling the container to interact with the device node, it also lets you specify additional configuration for the device, such as environment variables, host mounts (such as shared objects), and executable hooks.

You can reference a CDI device with the `--device` flag using the fully-qualified name of the device, as shown in the following example:

```console
$ docker run --device=vendor.com/class=device-name --rm -it ubuntu
```

This starts an `ubuntu` container with access to the specified CDI device, `vendor.com/class=device-name`, assuming that:

* A valid CDI specification (JSON or YAML file) for the requested device is available on the system running the daemon, in one of the configured CDI specification directories.
* The CDI feature has been enabled in the daemon; see [Enable CDI devices](/reference/cli/dockerd/#configure-cdi-devices).

### [Attach to STDIN/STDOUT/STDERR (-a, --attach)](#attach)

The `--attach` (or `-a`) flag tells `docker run` to bind to the container's `STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output and input as needed. You can specify to which of the three standard streams (`STDIN`, `STDOUT`, `STDERR`) you'd like to connect instead, as in:

```console
$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash
```

The following example pipes data into a container and prints the container's ID by attaching only to the container's `STDIN`.

```console
$ echo "test" | docker run -i -a stdin ubuntu cat -
```

The following example doesn't print anything to the console unless there's an error because output is only attached to the `STDERR` of the container. The container's logs still store what's written to `STDERR` and `STDOUT`.

```console
$ docker run -a stderr ubuntu echo test
```

The following example shows a way of using `--attach` to pipe a file into a container. The command prints the container's ID after the build completes and you can retrieve the build logs using `docker logs`. This is useful if you need to pipe a file or something else into a container and retrieve the container's ID once the container has finished running.

```console
$ cat somefile | docker run -i -a stdin mybuilder dobuild
```

> Note
>
> A process running as PID 1 inside a container is treated specially by Linux: it ignores any signal with the default action. So, the process doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so.

See also [the `docker cp` command](/reference/cli/docker/container/cp/).

### [Keep STDIN open (-i, --interactive)](#interactive)

The `--interactive` (or `-i`) flag keeps the container's `STDIN` open, and lets you send input to the container through standard input.

```console
$ echo hello | docker run --rm -i busybox cat
hello
```

The `-i` flag is most often used together with the `--tty` flag to bind the I/O streams of the container to a pseudo terminal, creating an interactive terminal session for the container. See [Allocate a pseudo-TTY](#tty) for more examples.

```console
$ docker run -it debian
root@10a3e71492b0:/# factor 90
90: 2 3 3 5
root@10a3e71492b0:/# exit
exit
```

Using the `-i` flag on its own allows for composition, such as piping input to containers:

```console
$ docker run --rm -i busybox echo "foo bar baz" \
  | docker run --rm -i busybox awk '{ print $2 }' \
  | docker run --rm -i busybox rev
rab
```

### [Specify an init process](#init)

You can use the `--init` flag to indicate that an init process should be used as the PID 1 in the container. Specifying an init process ensures the usual responsibilities of an init system, such as reaping zombie processes, are performed inside the created container.

The default init process used is the first `docker-init` executable found in the system path of the Docker daemon process. This `docker-init` binary, included in the default installation, is backed by [tini](https://github.com/krallin/tini).

### [Allocate a pseudo-TTY (-t, --tty)](#tty)

The `--tty` (or `-t`) flag attaches a pseudo-TTY to the container, connecting your terminal to the I/O streams of the container. Allocating a pseudo-TTY to the container means that you get access to input and output feature that TTY devices provide.

For example, the following command runs the `passwd` command in a `debian` container, to set a new password for the `root` user.

```console
$ docker run -i debian passwd root
New password: karjalanpiirakka9
Retype new password: karjalanpiirakka9
passwd: password updated successfully
```

If you run this command with only the `-i` flag (which lets you send text to `STDIN` of the container), the `passwd` prompt displays the password in plain text. However, if you try the same thing but also adding the `-t` flag, the password is hidden:

```console
$ docker run -it debian passwd root
New password:
Retype new password:
passwd: password updated successfully
```

This is because `passwd` can suppress the output of characters to the terminal using the echo-off TTY feature.

You can use the `-t` flag without `-i` flag. This still allocates a pseudo-TTY to the container, but with no way of writing to `STDIN`. The only time this might be useful is if the output of the container requires a TTY environment.

### [Specify custom cgroups](#cgroup-parent)

Using the `--cgroup-parent` flag, you can pass a specific cgroup to run a container in. This allows you to create and manage cgroups on their own. You can define custom resources for those cgroups and put containers under a common parent group.

### [Using dynamically created devices (--device-cgroup-rule)](#device-cgroup-rule)

Docker assigns devices available to a container at creation time. The assigned devices are added to the cgroup.allow file and created into the container when it runs. This poses a problem when you need to add a new device to running container.

One solution is to add a more permissive rule to a container allowing it access to a wider range of devices. For example, supposing the container needs access to a character device with major `42` and any number of minor numbers (added as new devices appear), add the following rule:

```console
$ docker run -d --device-cgroup-rule='c 42:* rmw' --name my-container my-image
```

Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>` the required device when it is added.

> Note
>
> You still need to explicitly add initially present devices to the `docker run` / `docker create` command.

### [Access an NVIDIA GPU](#gpus)

The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to install the [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/).

> Note
>
> You can also specify a GPU as a CDI device with the `--device` flag, see [CDI devices](#cdi-devices).

Read [Specify a container's resources](/config/containers/resource_constraints/) for more information.

To use `--gpus`, specify which GPUs (or all) to use. If you provide no value, Docker uses all available GPUs. The example below exposes all available GPUs.

```console
$ docker run -it --rm --gpus all ubuntu nvidia-smi
```

Use the `device` option to specify GPUs. The example below exposes a specific GPU.

```console
$ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubuntu nvidia-smi
```

The example below exposes the first and third GPUs.

```console
$ docker run -it --rm --gpus '"device=0,2"' ubuntu nvidia-smi
```

### [Restart policies (--restart)](#restart)

Use the `--restart` flag to specify a container's *restart policy*. A restart policy controls whether the Docker daemon restarts a container after exit. Docker supports the following restart policies:

| Flag                       | Description                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `no`                       | Don't automatically restart the container. (Default)                                                                                                                                                                                                                                                                                                                  |
| `on-failure[:max-retries]` | Restart the container if it exits due to an error, which manifests as a non-zero exit code. Optionally, limit the number of times the Docker daemon attempts to restart the container using the `:max-retries` option. The `on-failure` policy only prompts a restart if the container exits with a failure. It doesn't restart the container if the daemon restarts. |
| `always`                   | Always restart the container if it stops. If it's manually stopped, it's restarted only when Docker daemon restarts or the container itself is manually restarted.                                                                                                                                                                                                    |
| `unless-stopped`           | Similar to `always`, except that when the container is stopped (manually or otherwise), it isn't restarted even after Docker daemon restarts.                                                                                                                                                                                                                         |

```console
$ docker run --restart=always redis
```

This runs the `redis` container with a restart policy of **always**. If the container exits, Docker restarts it.

When a restart policy is active on a container, it shows as either `Up` or `Restarting` in [`docker ps`](/reference/cli/docker/container/ls/). It can also be useful to use [`docker events`](/reference/cli/docker/system/events/) to see the restart policy in effect.

An increasing delay (double the previous delay, starting at 100 milliseconds) is added before each restart to prevent flooding the server. This means the daemon waits for 100 ms, then 200 ms, 400, 800, 1600, and so on until either the `on-failure` limit, the maximum delay of 1 minute is hit, or when you `docker stop` or `docker rm -f` the container.

If a container is successfully restarted (the container is started and runs for at least 10 seconds), the delay is reset to its default value of 100 ms.

#### [Specify a limit for restart attempts](#specify-a-limit-for-restart-attempts)

You can specify the maximum amount of times Docker attempts to restart the container when using the **on-failure** policy. By default, Docker never stops attempting to restart the container.

The following example runs the `redis` container with a restart policy of **on-failure** and a maximum restart count of 10.

```console
$ docker run --restart=on-failure:10 redis
```

If the `redis` container exits with a non-zero exit status more than 10 times in a row, Docker stops trying to restart the container. Providing a maximum restart limit is only valid for the **on-failure** policy.

#### [Inspect container restarts](#inspect-container-restarts)

The number of (attempted) restarts for a container can be obtained using the [`docker inspect`](/reference/cli/docker/inspect/) command. For example, to get the number of restarts for container "my-container";

```console
$ docker inspect -f "{{ .RestartCount }}" my-container
2
```

Or, to get the last time the container was (re)started;

```console
$ docker inspect -f "{{ .State.StartedAt }}" my-container
2015-03-04T23:47:07.691840179Z
```

Combining `--restart` (restart policy) with the `--rm` (clean up) flag results in an error. On container restart, attached clients are disconnected.

### [Clean up (--rm)](#rm)

By default, a container's file system persists even after the container exits. This makes debugging a lot easier, since you can inspect the container's final state and you retain all your data.

If you are running short-term **foreground** processes, these container file systems can start to pile up. If you'd like Docker to automatically clean up the container and remove the file system when the container exits, use the `--rm` flag:

```text
--rm: Automatically remove the container and its associated anonymous volumes when it exits
```

> Note
>
> If you set the `--rm` flag, Docker also removes the anonymous volumes associated with the container when the container is removed. This is similar to running `docker rm -v my-container`. Only volumes that are specified without a name are removed. For example, when running the following command, volume `/foo` is removed, but not `/bar`:
>
> ```console
> $ docker run --rm -v /foo -v awesome:/bar busybox top
> ```
>
> Volumes inherited via `--volumes-from` are removed with the same logic: if the original volume was specified with a name it isn't removed.

### [Add entries to container hosts file (--add-host)](#add-host)

You can add other hosts into a container's `/etc/hosts` file by using one or more `--add-host` flags. This example adds a static address for a host named `my-hostname`:

```console
$ docker run --add-host=my-hostname=8.8.8.8 --rm -it alpine

/ # ping my-hostname
PING my-hostname (8.8.8.8): 56 data bytes
64 bytes from 8.8.8.8: seq=0 ttl=37 time=93.052 ms
64 bytes from 8.8.8.8: seq=1 ttl=37 time=92.467 ms
64 bytes from 8.8.8.8: seq=2 ttl=37 time=92.252 ms
^C
--- my-hostname ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max = 92.209/92.495/93.052 ms
```

You can wrap an IPv6 address in square brackets:

```console
$ docker run --add-host my-hostname=[2001:db8::33] --rm -it alpine
```

The `--add-host` flag supports a special `host-gateway` value that resolves to the internal IP address of the host. This is useful when you want containers to connect to services running on the host machine.

It's conventional to use `host.docker.internal` as the hostname referring to `host-gateway`. Docker Desktop automatically resolves this hostname, see [Explore networking how-tos on Docker Desktop](/desktop/features/networking/networking-how-tos/#connect-a-container-to-a-service-on-the-host) and [Configure host gateway IP](/reference/cli/dockerd/#configure-host-gateway-ip).

The following example shows how the special `host-gateway` value works. The example runs an HTTP server that serves a file from host to container over the `host.docker.internal` hostname, which resolves to the host's internal IP.

```console
$ echo "hello from host!" > ./hello
$ python3 -m http.server 8000
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
$ docker run \
  --add-host host.docker.internal=host-gateway \
  curlimages/curl -s host.docker.internal:8000/hello
hello from host!
```

The `--add-host` flag also accepts a `:` separator, for example:

```console
$ docker run --add-host=my-hostname:8.8.8.8 --rm -it alpine
```

### [Logging drivers (--log-driver)](#log-driver)

The container can have a different logging driver than the Docker daemon. Use the `--log-driver=<DRIVER>` with the `docker run` command to configure the container's logging driver.

To learn about the supported logging drivers and how to use them, refer to [Configure logging drivers](/engine/logging/configure/).

To disable logging for a container, set the `--log-driver` flag to `none`:

```console
$ docker run --log-driver=none -d nginx:alpine
5101d3b7fe931c27c2ba0e65fd989654d297393ad65ae238f20b97a020e7295b
$ docker logs 5101d3b
Error response from daemon: configured logging driver does not support reading
```

### [Set ulimits in container (--ulimit)](#ulimit)

Since setting `ulimit` settings in a container requires extra privileges not available in the default container, you can set these using the `--ulimit` flag. Specify `--ulimit` with a soft and hard limit in the format `<type>=<soft limit>[:<hard limit>]`. For example:

```console
$ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
1024
```

> Note
>
> If you don't provide a hard limit value, Docker uses the soft limit value for both values. If you don't provide any values, they are inherited from the default `ulimits` set on the daemon.

> Note
>
> The `as` option is deprecated. In other words, the following script is not supported:
>
> ```console
> $ docker run -it --ulimit as=1024 fedora /bin/bash
> ```

#### [Supported options for `--ulimit`:](#supported-options-for---ulimit)

| Option       | Description                                               |
| ------------ | --------------------------------------------------------- |
| `core`       | Maximum size of core files created (`RLIMIT_CORE`)        |
| `cpu`        | CPU time limit in seconds (`RLIMIT_CPU`)                  |
| `data`       | Maximum data segment size (`RLIMIT_DATA`)                 |
| `fsize`      | Maximum file size (`RLIMIT_FSIZE`)                        |
| `locks`      | Maximum number of file locks (`RLIMIT_LOCKS`)             |
| `memlock`    | Maximum locked-in-memory address space (`RLIMIT_MEMLOCK`) |
| `msgqueue`   | Maximum bytes in POSIX message queues (`RLIMIT_MSGQUEUE`) |
| `nice`       | Maximum nice priority adjustment (`RLIMIT_NICE`)          |
| `nofile`     | Maximum number of open file descriptors (`RLIMIT_NOFILE`) |
| `nproc`      | Maximum number of processes available (`RLIMIT_NPROC`)    |
| `rss`        | Maximum resident set size (`RLIMIT_RSS`)                  |
| `rtprio`     | Maximum real-time scheduling priority (`RLIMIT_RTPRIO`)   |
| `rttime`     | Maximum real-time execution time (`RLIMIT_RTTIME`)        |
| `sigpending` | Maximum number of pending signals (`RLIMIT_SIGPENDING`)   |
| `stack`      | Maximum stack size (`RLIMIT_STACK`)                       |

Docker sends the values to the appropriate OS `syscall` and doesn't perform any byte conversion. Take this into account when setting the values.

#### [For `nproc` usage](#for-nproc-usage)

Be careful setting `nproc` with the `ulimit` flag as Linux uses `nproc` to set the maximum number of processes available to a user, not to a container. For example, start four containers with `daemon` user:

```console
$ docker run -d -u daemon --ulimit nproc=3 busybox top

$ docker run -d -u daemon --ulimit nproc=3 busybox top

$ docker run -d -u daemon --ulimit nproc=3 busybox top

$ docker run -d -u daemon --ulimit nproc=3 busybox top
```

The 4th container fails and reports a "\[8] System error: resource temporarily unavailable" error. This fails because the caller set `nproc=3` resulting in the first three containers using up the three processes quota set for the `daemon` user.

### [Stop container with signal (--stop-signal)](#stop-signal)

The `--stop-signal` flag sends the system call signal to the container to exit. This signal can be a signal name in the format `SIG<NAME>`, for instance `SIGKILL`, or an unsigned number that matches a position in the kernel's syscall table, for instance `9`.

The default value is defined by [`STOPSIGNAL`](/reference/dockerfile/#stopsignal) in the image, or `SIGTERM` if the image has no `STOPSIGNAL` defined.

### [Optional security options (--security-opt)](#security-opt)

| Option                                    | Description                                                                                                                                                                                                      |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--security-opt="label=user:USER"`        | Set the label user for the container                                                                                                                                                                             |
| `--security-opt="label=role:ROLE"`        | Set the label role for the container                                                                                                                                                                             |
| `--security-opt="label=type:TYPE"`        | Set the label type for the container                                                                                                                                                                             |
| `--security-opt="label=level:LEVEL"`      | Set the label level for the container                                                                                                                                                                            |
| `--security-opt="label=disable"`          | Turn off label confinement for the container                                                                                                                                                                     |
| `--security-opt="apparmor=PROFILE"`       | Set the apparmor profile to be applied to the container                                                                                                                                                          |
| `--security-opt="no-new-privileges=true"` | Disable container processes from gaining new privileges                                                                                                                                                          |
| `--security-opt="seccomp=unconfined"`     | Turn off seccomp confinement for the container                                                                                                                                                                   |
| `--security-opt="seccomp=builtin"`        | Use the default (built-in) seccomp profile for the container. This can be used to enable seccomp for a container running on a daemon with a custom default profile set, or with seccomp disabled ("unconfined"). |
| `--security-opt="seccomp=profile.json"`   | White-listed syscalls seccomp Json file to be used as a seccomp filter                                                                                                                                           |
| `--security-opt="systempaths=unconfined"` | Turn off confinement for system paths (masked paths, read-only paths) for the container                                                                                                                          |

The `--security-opt` flag lets you override the default labeling scheme for a container. Specifying the level in the following command allows you to share the same content between containers.

```console
$ docker run --security-opt label=level:s0:c100,c200 -it fedora bash
```

> Note
>
> Automatic translation of MLS labels isn't supported.

To disable the security labeling for a container entirely, you can use `label=disable`:

```console
$ docker run --security-opt label=disable -it ubuntu bash
```

If you want a tighter security policy on the processes within a container, you can specify a custom `type` label. The following example runs a container that's only allowed to listen on Apache ports:

```console
$ docker run --security-opt label=type:svirt_apache_t -it ubuntu bash
```

> Note
>
> You would have to write policy defining a `svirt_apache_t` type.

To prevent your container processes from gaining additional privileges, you can use the following command:

```console
$ docker run --security-opt no-new-privileges -it ubuntu bash
```

This means that commands that raise privileges such as `su` or `sudo` no longer work. It also causes any seccomp filters to be applied later, after privileges have been dropped which may mean you can have a more restrictive set of filters. For more details, see the [kernel documentation](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt).

On Windows, you can use the `--security-opt` flag to specify the `credentialspec` option. The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`.

### [Stop container with timeout (--stop-timeout)](#stop-timeout)

The `--stop-timeout` flag sets the number of seconds to wait for the container to stop after sending the pre-defined (see `--stop-signal`) system call signal. If the container does not exit after the timeout elapses, it's forcibly killed with a `SIGKILL` signal.

If you set `--stop-timeout` to `-1`, no timeout is applied, and the daemon waits indefinitely for the container to exit.

The Daemon determines the default, and is 10 seconds for Linux containers, and 30 seconds for Windows containers.

### [Specify isolation technology for container (--isolation)](#isolation)

This option is useful in situations where you are running Docker containers on Windows. The `--isolation=<value>` option sets a container's isolation technology. On Linux, the only supported is the `default` option which uses Linux namespaces. These two commands are equivalent on Linux:

```console
$ docker run -d busybox top
$ docker run -d --isolation default busybox top
```

On Windows, `--isolation` can take one of these values:

| Value     | Description                                                                                |
| --------- | ------------------------------------------------------------------------------------------ |
| `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). |
| `process` | Shared-kernel namespace isolation.                                                         |
| `hyperv`  | Hyper-V hypervisor partition-based isolation.                                              |

The default isolation on Windows server operating systems is `process`, and `hyperv` on Windows client operating systems, such as Windows 10. Process isolation has better performance, but requires that the image and host use the same kernel version.

On Windows server, assuming the default configuration, these commands are equivalent and result in `process` isolation:

```powershell
PS C:\> docker run -d microsoft/nanoserver powershell echo process
PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo process
PS C:\> docker run -d --isolation process microsoft/nanoserver powershell echo process
```

If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, or are running against a Windows client-based daemon, these commands are equivalent and result in `hyperv` isolation:

```powershell
PS C:\> docker run -d microsoft/nanoserver powershell echo hyperv
PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo hyperv
PS C:\> docker run -d --isolation hyperv microsoft/nanoserver powershell echo hyperv
```

### [Specify hard limits on memory available to containers (-m, --memory)](#memory)

These parameters always set an upper limit on the memory available to the container. Linux sets this on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`.

On Windows, this affects containers differently depending on what type of isolation you use.

* With `process` isolation, Windows reports the full memory of the host system, not the limit to applications running inside the container

  ```powershell
  PS C:\> docker run -it -m 2GB --isolation=process microsoft/nanoserver powershell Get-ComputerInfo *memory*

  CsTotalPhysicalMemory      : 17064509440
  CsPhyicallyInstalledMemory : 16777216
  OsTotalVisibleMemorySize   : 16664560
  OsFreePhysicalMemory       : 14646720
  OsTotalVirtualMemorySize   : 19154928
  OsFreeVirtualMemory        : 17197440
  OsInUseVirtualMemory       : 1957488
  OsMaxProcessMemorySize     : 137438953344
  ```

* With `hyperv` isolation, Windows creates a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory."

  ```powershell
  PS C:\> docker run -it -m 2GB --isolation=hyperv microsoft/nanoserver powershell Get-ComputerInfo *memory*

  CsTotalPhysicalMemory      : 2683355136
  CsPhyicallyInstalledMemory :
  OsTotalVisibleMemorySize   : 2620464
  OsFreePhysicalMemory       : 2306552
  OsTotalVirtualMemorySize   : 2620464
  OsFreeVirtualMemory        : 2356692
  OsInUseVirtualMemory       : 263772
  OsMaxProcessMemorySize     : 137438953344
  ```

### [Configure namespaced kernel parameters (sysctls) at runtime (--sysctl)](#sysctl)

The `--sysctl` sets namespaced kernel parameters (sysctls) in the container. For example, to turn on IP forwarding in the containers network namespace, run this command:

```console
$ docker run --sysctl net.ipv4.ip_forward=1 someimage
```

> Note
>
> Not all sysctls are namespaced. Docker does not support changing sysctls inside of a container that also modify the host system. As the kernel evolves we expect to see more sysctls become namespaced.

#### [Currently supported sysctls](#currently-supported-sysctls)

IPC Namespace:

* `kernel.msgmax`, `kernel.msgmnb`, `kernel.msgmni`, `kernel.sem`, `kernel.shmall`, `kernel.shmmax`, `kernel.shmmni`, `kernel.shm_rmid_forced`.
* Sysctls beginning with `fs.mqueue.*`
* If you use the `--ipc=host` option these sysctls are not allowed.

Network Namespace:

* Sysctls beginning with `net.*`
* If you use the `--network=host` option using these sysctls are not allowed.

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/list/
----

# docker mcp profile list

***

| Description                                                               | List profiles             |
| ------------------------------------------------------------------------- | ------------------------- |
| Usage                                                                     | `docker mcp profile list` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker mcp profile ls`   |

## [Description](#description)

List profiles

## [Options](#options)

| Option     | Default | Description                   |
| ---------- | ------- | ----------------------------- |
| `--format` | `human` | Supported: json, yaml, human. |

----
url: https://docs.docker.com/reference/cli/docker/scout/integration/
----

# docker scout integration

***

| Description | Commands to list, configure, and delete Docker Scout integrations |
| ----------- | ----------------------------------------------------------------- |

## [Description](#description)

Commands to list, configure, and delete Docker Scout integrations

## [Subcommands](#subcommands)

| Command                                                                                                           | Description                                         |
| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [`docker scout integration configure`](https://docs.docker.com/reference/cli/docker/scout/integration/configure/) | Configure or update a new integration configuration |
| [`docker scout integration delete`](https://docs.docker.com/reference/cli/docker/scout/integration/delete/)       | Delete a new integration configuration              |
| [`docker scout integration list`](https://docs.docker.com/reference/cli/docker/scout/integration/list/)           | List integrations which can be installed            |

----
url: https://docs.docker.com/engine/install/debian/
----

# Install Docker Engine on Debian

***

Table of contents

***

To get started with Docker Engine on Debian, make sure you [meet the prerequisites](#prerequisites), and then follow the [installation steps](#installation-methods).

## [Prerequisites](#prerequisites)

### [Firewall limitations](#firewall-limitations)

> Warning
>
> Before you install Docker, make sure you consider the following security implications and firewall incompatibilities.

* If you use ufw or firewalld to manage firewall settings, be aware that when you expose container ports using Docker, these ports bypass your firewall rules. For more information, refer to [Docker and ufw](https://docs.docker.com/engine/network/packet-filtering-firewalls/#docker-and-ufw).
* Docker is only compatible with `iptables-nft` and `iptables-legacy`. Firewall rules created with `nft` are not supported on a system with Docker installed. Make sure that any firewall rulesets you use are created with `iptables` or `ip6tables`, and that you add them to the `DOCKER-USER` chain, see [Packet filtering and firewalls](https://docs.docker.com/engine/network/packet-filtering-firewalls/).

### [OS requirements](#os-requirements)

To install Docker Engine, you need one of these Debian versions:

* Debian Trixie 13 (stable)
* Debian Bookworm 12 (oldstable)
* Debian Bullseye 11 (oldoldstable)

Docker Engine for Debian is compatible with x86\_64 (or amd64), armhf (arm/v7), arm64, and ppc64le (ppc64el) architectures.

```console
$ sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-doc podman-docker containerd runc | cut -f1)
```

   ```bash
   # Add Docker's official GPG key:
   sudo apt update
   sudo apt install ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc

   # Add the repository to Apt sources:
   sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
   Types: deb
   URIs: https://download.docker.com/linux/debian
   Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
   Components: stable
   Architectures: $(dpkg --print-architecture)
   Signed-By: /etc/apt/keyrings/docker.asc
   EOF

   sudo apt update
   ```

   > Note
   >
   > If you use Debian testing or a derivative distribution such as Kali Linux, you may need to substitute the part of this command that's expected to print the version codename:
   >
   > ```console
   > $(. /etc/os-release && echo "$VERSION_CODENAME")
   > ```
   >
   > Replace this part with the codename of the corresponding Debian release, such as `trixie`.

2. Install the Docker packages.

   To install the latest version, run:

   ```console
   $ sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   To install a specific version of Docker Engine, start by listing the available versions in the repository:

   ```console
   $ apt list --all-versions docker-ce

   docker-ce/bookworm 5:29.5.2-1~debian.12~bookworm <arch>
   docker-ce/bookworm 5:29.5.1-1~debian.12~bookworm <arch>
   ...
   ```

   Select the desired version and install:

   ```console
   $ VERSION_STRING=5:29.5.2-1~debian.12~bookworm
   $ sudo apt install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   > Note
   >
   > After installation, verify that Docker is running:
   >
   > ```console
   > $ sudo systemctl status docker
   > ```
   >
   > If Docker is not running, start it manually:
   >
   > ```console
   > $ sudo systemctl start docker
   > ```

3. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

#### [Upgrade Docker Engine](#upgrade-docker-engine)

To upgrade Docker Engine, follow step 2 of the [installation instructions](#install-using-the-repository), choosing the new version you want to install.

### [Install from a package](#install-from-a-package)

If you can't use Docker's `apt` repository to install Docker Engine, you can download the `deb` file for your release and install it manually. You need to download a new file each time you want to upgrade Docker Engine.

1. Go to [`https://download.docker.com/linux/debian/dists/`](https://download.docker.com/linux/debian/dists/).

2. Select your Debian version in the list.

   ```console
   $ sudo dpkg -i ./containerd.io_<version>_<arch>.deb \
     ./docker-ce_<version>_<arch>.deb \
     ./docker-ce-cli_<version>_<arch>.deb \
     ./docker-buildx-plugin_<version>_<arch>.deb \
     ./docker-compose-plugin_<version>_<arch>.deb
   ```

   > Note
   >
   > After installation, verify that Docker is running:
   >
   > ```console
   > $ sudo systemctl status docker
   > ```
   >
   > If Docker is not running, start it manually:
   >
   > ```console
   > $ sudo systemctl start docker
   > ```

6. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

> Tip
>
> Preview script steps before running. You can run the script with the `--dry-run` option to learn what steps the script will run when invoked:
>
> ```console
> $ curl -fsSL https://get.docker.com -o get-docker.sh
> $ sudo sh ./get-docker.sh --dry-run
> ```

This example downloads the script from <https://get.docker.com/> and runs it to install the latest stable release of Docker on Linux:

```console
$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh get-docker.sh
Executing docker install script, commit: 7cae5f8b0decc17d6571f9f52eb840fbc13b2737
<...>
```

You have now successfully installed and started Docker Engine. The `docker` service starts automatically on Debian based distributions. On `RPM` based distributions, such as CentOS, Fedora or RHEL, you need to start it manually using the appropriate `systemctl` or `service` command. As the message indicates, non-root users can't run Docker commands by default.

> **Use Docker as a non-privileged user, or install in rootless mode?**
>
> The installation script requires `root` or `sudo` privileges to install and use Docker. If you want to grant non-root users access to Docker, refer to the [post-installation steps for Linux](/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). You can also install Docker without `root` privileges, or configured to run in rootless mode. For instructions on running Docker in rootless mode, refer to [run the Docker daemon as a non-root user (rootless mode)](/engine/security/rootless/).

#### [Install pre-releases](#install-pre-releases)

Docker also provides a convenience script at <https://test.docker.com/> to install pre-releases of Docker on Linux. This script is equal to the script at `get.docker.com`, but configures your package manager to use the test channel of the Docker package repository. The test channel includes both stable and pre-releases (beta versions, release-candidates) of Docker. Use this script to get early access to new releases, and to evaluate them in a testing environment before they're released as stable.

To install the latest version of Docker on Linux from the test channel, run:

```console
$ curl -fsSL https://test.docker.com -o test-docker.sh
$ sudo sh test-docker.sh
```

#### [Upgrade Docker after using the convenience script](#upgrade-docker-after-using-the-convenience-script)

If you installed Docker using the convenience script, you should upgrade Docker using your package manager directly. There's no advantage to re-running the convenience script. Re-running it can cause issues if it attempts to re-install repositories which already exist on the host machine.

## [Uninstall Docker Engine](#uninstall-docker-engine)

1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages:

   ```console
   $ sudo apt purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
   ```

2. Images, containers, volumes, or custom configuration files on your host aren't automatically removed. To delete all images, containers, and volumes:

   ```console
   $ sudo rm -rf /var/lib/docker
   $ sudo rm -rf /var/lib/containerd
   ```

3. Remove source list and keyrings

   ```console
   $ sudo rm /etc/apt/sources.list.d/docker.sources
   $ sudo rm /etc/apt/keyrings/docker.asc
   ```

----
url: https://docs.docker.com/engine/swarm/swarm-mode/
----

# Run Docker Engine in swarm mode

***

Table of contents

***

When you first install and start working with Docker Engine, Swarm mode is disabled by default. When you enable Swarm mode, you work with the concept of services managed through the `docker service` command.

There are two ways to run the engine in Swarm mode:

* Create a new swarm, covered in this article.
* [Join an existing swarm](https://docs.docker.com/engine/swarm/join-nodes/).

When you run the engine in Swarm mode on your local machine, you can create and test services based upon images you've created or other available images. In your production environment, Swarm mode provides a fault-tolerant platform with cluster management features to keep your services running and available.

These instructions assume you have installed the Docker Engine on a machine to serve as a manager node in your swarm.

If you haven't already, read through the [Swarm mode key concepts](https://docs.docker.com/engine/swarm/key-concepts/) and try the [Swarm mode tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/).

## [Create a swarm](#create-a-swarm)

When you run the command to create a swarm, Docker Engine starts running in Swarm mode.

Run [`docker swarm init`](/reference/cli/docker/swarm/init/) to create a single-node swarm on the current node. The engine sets up the swarm as follows:

* Switches the current node into Swarm mode.
* Creates a swarm named `default`.
* Designates the current node as a leader manager node for the swarm.
* Names the node with the machine hostname.
* Configures the manager to listen on an active network interface on port `2377`.
* Sets the current node to `Active` availability, meaning it can receive tasks from the scheduler.
* Starts an internal distributed data store for Engines participating in the swarm to maintain a consistent view of the swarm and all services running on it.
* By default, generates a self-signed root CA for the swarm.
* By default, generates tokens for worker and manager nodes to join the swarm.
* Creates an overlay network named `ingress` for publishing service ports external to the swarm.
* Creates an overlay default IP addresses and subnet mask for your networks

The output for `docker swarm init` provides the connection command to use when you join new worker nodes to the swarm:

```console
$ docker swarm init
Swarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
    192.168.99.100:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
```

### [Configuring default address pools](#configuring-default-address-pools)

By default Swarm mode uses a default address pool `10.0.0.0/8` for global scope (overlay) networks. Every network that does not have a subnet specified will have a subnet sequentially allocated from this pool. In some circumstances it may be desirable to use a different default IP address pool for networks.

For example, if the default `10.0.0.0/8` range conflicts with already allocated address space in your network, then it is desirable to ensure that networks use a different range without requiring swarm users to specify each subnet with the `--subnet` command.

To configure custom default address pools, you must define pools at swarm initialization using the `--default-addr-pool` command line option. This command line option uses CIDR notation for defining the subnet mask. To create the custom address pool for Swarm, you must define at least one default address pool, and an optional default address pool subnet mask. For example, for the `10.0.0.0/27`, use the value `27`.

Docker allocates subnet addresses from the address ranges specified by the `--default-addr-pool` option. For example, a command line option `--default-addr-pool 10.10.0.0/16` indicates that Docker will allocate subnets from that `/16` address range. If `--default-addr-pool-mask-len` were unspecified or set explicitly to 24, this would result in 256 `/24` networks of the form `10.10.X.0/24`.

The subnet range comes from the `--default-addr-pool`, (such as `10.10.0.0/16`). The size of 16 there represents the number of networks one can create within that `default-addr-pool` range. The `--default-addr-pool` option may occur multiple times with each option providing additional addresses for docker to use for overlay subnets.

The format of the command is:

```console
$ docker swarm init --default-addr-pool <IP range in CIDR> [--default-addr-pool <IP range in CIDR> --default-addr-pool-mask-length <CIDR value>]
```

The command to create a default IP address pool with a /16 (class B) for the `10.20.0.0` network looks like this:

```console
$ docker swarm init --default-addr-pool 10.20.0.0/16
```

The command to create a default IP address pool with a `/16` (class B) for the `10.20.0.0` and `10.30.0.0` networks, and to create a subnet mask of `/26` for each network looks like this:

```console
$ docker swarm init --default-addr-pool 10.20.0.0/16 --default-addr-pool 10.30.0.0/16 --default-addr-pool-mask-length 26
```

In this example, `docker network create -d overlay net1` will result in `10.20.0.0/26` as the allocated subnet for `net1`, and `docker network create -d overlay net2` will result in `10.20.0.64/26` as the allocated subnet for `net2`. This continues until all the subnets are exhausted.

Refer to the following pages for more information:

* [Swarm networking](https://docs.docker.com/engine/swarm/networking/) for more information about the default address pool usage
* `docker swarm init` [CLI reference](/reference/cli/docker/swarm/init/) for more detail on the `--default-addr-pool` flag.

### [Configure the advertise address](#configure-the-advertise-address)

Manager nodes use an advertise address to allow other nodes in the swarm access to the Swarmkit API and overlay networking. The other nodes on the swarm must be able to access the manager node on its advertise address.

If you don't specify an advertise address, Docker checks if the system has a single IP address. If so, Docker uses the IP address with the listening port `2377` by default. If the system has multiple IP addresses, you must specify the correct `--advertise-addr` to enable inter-manager communication and overlay networking:

```console
$ docker swarm init --advertise-addr <MANAGER-IP>
```

You must also specify the `--advertise-addr` if the address where other nodes reach the first manager node is not the same address the manager sees as its own. For instance, in a cloud setup that spans different regions, hosts have both internal addresses for access within the region and external addresses that you use for access from outside that region. In this case, specify the external address with `--advertise-addr` so that the node can propagate that information to other nodes that subsequently connect to it.

Refer to the `docker swarm init` [CLI reference](/reference/cli/docker/swarm/init/) for more detail on the advertise address.

### [View the join command or update a swarm join token](#view-the-join-command-or-update-a-swarm-join-token)

Nodes require a secret token to join the swarm. The token for worker nodes is different from the token for manager nodes. Nodes only use the join-token at the moment they join the swarm. Rotating the join token after a node has already joined a swarm does not affect the node's swarm membership. Token rotation ensures an old token cannot be used by any new nodes attempting to join the swarm.

To retrieve the join command including the join token for worker nodes, run:

```console
$ docker swarm join-token worker

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
    192.168.99.100:2377

This node joined a swarm as a worker.
```

To view the join command and token for manager nodes, run:

```console
$ docker swarm join-token manager

To add a manager to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-59egwe8qangbzbqb3ryawxzk3jn97ifahlsrw01yar60pmkr90-bdjfnkcflhooyafetgjod97sz \
    192.168.99.100:2377
```

Pass the `--quiet` flag to print only the token:

```console
$ docker swarm join-token --quiet worker

SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c
```

Be careful with the join tokens because they are the secrets necessary to join the swarm. In particular, checking a secret into version control is a bad practice because it would allow anyone with access to the application source code to add new nodes to the swarm. Manager tokens are especially sensitive because they allow a new manager node to join and gain control over the whole swarm.

We recommend that you rotate the join tokens in the following circumstances:

* If a token was checked-in by accident into a version control system, group chat or accidentally printed to your logs.
* If you suspect a node has been compromised.
* If you wish to guarantee that no new nodes can join the swarm.

Additionally, it is a best practice to implement a regular rotation schedule for any secret including swarm join tokens. We recommend that you rotate your tokens at least every 6 months.

Run `swarm join-token --rotate` to invalidate the old token and generate a new token. Specify whether you want to rotate the token for `worker` or `manager` nodes:

```console
$ docker swarm join-token  --rotate worker

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-2kscvs0zuymrsc9t0ocyy1rdns9dhaodvpl639j2bqx55uptag-ebmn5u927reawo27s3azntd44 \
    192.168.99.100:2377
```

## [Learn more](#learn-more)

* [Join nodes to a swarm](https://docs.docker.com/engine/swarm/join-nodes/)
* `swarm init` [command line reference](/reference/cli/docker/swarm/init/)
* [Swarm mode tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/)

----
url: https://docs.docker.com/dhi/how-to/scan/
----

# Scan Docker Hardened Images

***

Table of contents

***

Docker Hardened Images (DHIs) are designed to be secure by default, but like any container image, it's important to scan them regularly as part of your vulnerability management process.

## [Scan with OpenVEX-compliant scanners](#scan-with-openvex-compliant-scanners)

To get accurate vulnerability assessments, use scanners that support [VEX](https://docs.docker.com/dhi/core-concepts/vex/) attestations. The following scanners can read and apply the VEX statements included with Docker Hardened Images:

* [Docker Scout](#docker-scout): Automatically applies VEX statements with zero configuration
* [Trivy](#trivy): Supports VEX through VEX Hub or local VEX files
* [Grype](#grype): Supports VEX via the `--vex` flag
* [Wiz](#wiz): Automatically applies VEX statements with zero configuration
* [Mend.io](#mendio): Automatically applies VEX statements with zero configuration
* [Black Duck](#black-duck): Automatically applies VEX statements with zero configuration

For guidance on choosing the right scanner and understanding the differences between VEX-enabled and non-VEX scanners, see [Scanner integrations](https://docs.docker.com/dhi/explore/scanner-integrations/).

## [Docker Scout](#docker-scout)

Docker Scout is integrated into Docker Desktop and the Docker CLI. It provides vulnerability insights, CVE summaries, and direct links to remediation guidance.

### [Scan a DHI using Docker Scout](#scan-a-dhi-using-docker-scout)

To scan a Docker Hardened Image using Docker Scout, run the following command:

```console
$ docker login dhi.io
$ docker scout cves dhi.io/<image>:<tag> --platform <platform>
```

Example output:

```plaintext
    v SBOM obtained from attestation, 101 packages found
    v Provenance obtained from attestation
    v VEX statements obtained from attestation
    v No vulnerable package detected
    ...
```

For more detailed filtering and JSON output, see [Docker Scout CLI reference](/reference/cli/docker/scout/).

### [Build child images with provenance attestations](#build-child-images-with-provenance-attestations)

When you build a custom image that uses a Docker Hardened Image as its base, you must build with `--provenance=mode=max` and `--sbom=true` so that Docker Scout can trace the base image lineage and correctly apply VEX statements.

Without these flags, Docker Scout cannot identify the DHI base image in the provenance chain. As a result, it reports CVEs that are already suppressed by VEX statements in the base image, producing false CVE positives in your scan results.

> Note
>
> **Why provenance attestation is required**
>
> Docker Scout uses max-mode provenance attestations to identify the DHI base image and track its lineage. A cryptographically signed provenance attestation ensures that base image lineage is verified and tamper-resistant, giving Docker Scout the trust anchor it needs to correctly apply VEX statements from the base image.

To build with maximum provenance and SBOM attestations:

```console
$ docker build \
    --provenance=mode=max \
    --sbom=true \
    --push \
    -t docker.io/<namespace>/<image>:<tag> .
```

After building with these flags, Docker Scout reads the full provenance chain, matches the DHI base image, and applies its VEX statements. Scans of your child image then reflect the correct suppressed CVEs, giving you an accurate vulnerability assessment.

### [VEX attestations in child images](#vex-attestations-in-child-images)

If you introduce new layers in your child image and want to suppress CVEs in those layers, you can attach your own VEX attestation to the child image independently, you do not need to duplicate or aggregate the VEX statements from the DHI base image.

When `docker scout cves` runs against your child image, Scout reads VEX attestations from the full provenance chain and applies them cumulatively:

* **Base image VEX** - attached to the DHI, applied to CVEs in base image layers
* **Child image VEX** - attached to your image, applied to CVEs in layers you introduced

For example, if you add a `requests` layer to a DHI Python base image and attach a VEX statement suppressing `CVE-2024-47081`, Scout applies both VEX attestations independently and attributes each to its respective author:

```text
✓ VEX statements obtained from attestation
CVE-2024-47081  VEX: not affected [vulnerable code not present] : <your-namespace>
```

Scout suppresses CVEs from the DHI base VEX and CVEs from your child VEX in the same scan - no aggregate VEX document is required.

To create and attach a VEX attestation to your child image:

```bash
cat > child-vex.json << 'EOF'
{
  "@context": "https://openvex.dev/ns/v0.2.0",
  "@id": "https://<your-namespace>/vex/<image-name>/1",
  "author": "<your-namespace>",
  "timestamp": "<timestamp>",
  "version": 1,
  "statements": [
    {
      "vulnerability": {
        "name": "<CVE-ID>"
      },
      "products": [
        {
          "@id": "pkg:pypi/<package>@<version>"
        }
      ],
      "status": "not_affected",
      "justification": "vulnerable_code_not_present"
    }
  ]
}
EOF

docker scout attestation add \
  --file child-vex.json \
  --predicate-type https://openvex.dev/ns/v0.2.0 \
  docker.io/<your-namespace>/<image>:<tag>
```

> Note
>
> This is only possible because you built with `--provenance=mode=max`. Without the full provenance chain, Scout cannot traverse back to the base image to retrieve its VEX attestations.

### [Automate DHI scanning in CI/CD with Docker Scout](#automate-dhi-scanning-in-cicd-with-docker-scout)

Integrating Docker Scout into your CI/CD pipeline enables you to automatically verify that images built from Docker Hardened Images remain free from known vulnerabilities during the build process. This proactive approach ensures the continued security integrity of your images throughout the development lifecycle.

#### [Example GitHub Actions workflow](#example-github-actions-workflow)

The following is a sample GitHub Actions workflow that builds an image, scans it and pushes to the registry only if the scan passes:

```yaml
name: DHI Vulnerability Scan

on:
  push:
    branches:
      - main
  pull_request:

env:
  REGISTRY: docker.io
  IMAGE_NAME: ${{ github.repository }}
  SHA: ${{ github.event.pull_request.head.sha || github.event.after }}

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      pull-requests: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Set up Docker with containerd image store
        uses: docker/setup-docker-action@v5
        with:
          daemon-config: |
            {
              "features": {
                 "containerd-snapshotter": true
              }
            }

      - name: Log in to Docker Hub
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Build
        uses: docker/build-push-action@v7
        with:
          context: .
          sbom: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.SHA }}
      
      - name: Run Docker Scout CVE scan
        uses: docker/scout-action@v1
        with:
          command: cves
          image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.SHA }}
          only-severities: critical,high
          exit-code: true

      - name: Push image
        if: success()
        run: |
          docker push ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.SHA }}
```

The `exit-code: true` parameter ensures that the workflow fails if any critical or high-severity vulnerabilities are detected, preventing the deployment of insecure images.

> Note
>
> The `--provenance=mode=max` and `--sbom=true` flags are required so that Docker Scout can trace the DHI base image lineage and correctly apply its VEX statements. Enabling the containerd image store via `docker/setup-docker-action` allows BuildKit to store attestations locally without pushing to a registry first. Without the containerd image store, Docker Engine rejects the build with: `Attestation is not supported for the docker driver. Switch to a different driver, or turn on the containerd image store, and try again.` The `Push image` step runs only if the scan passes, using `if: success()` to ensure images are only pushed to the registry when they are free of critical or high-severity vulnerabilities.

For more details on using Docker Scout in CI, see [Integrating Docker Scout with other systems](https://docs.docker.com/scout/integrations/).

## [Grype](#grype)

[Grype](https://github.com/anchore/grype) is an open-source scanner that checks container images against vulnerability databases like the NVD and distro advisories.

### [Scan a DHI using Grype](#scan-a-dhi-using-grype)

To scan a Docker Hardened Image using Grype with VEX filtering, first export the VEX attestation and then scan with the `--vex` flag:

```console
$ docker login dhi.io
$ docker pull dhi.io/<image>:<tag>
$ docker scout vex get dhi.io/<image>:<tag> --output vex.json
$ grype dhi.io/<image>:<tag> --vex vex.json
```

The `--vex` flag applies VEX statements during the scan, filtering out known non-exploitable CVEs for accurate results.

For more information on exporting VEX attestations, see [Export VEX attestations](#export-vex-attestations).

## [Trivy](#trivy)

[Trivy](https://github.com/aquasecurity/trivy) is an open-source vulnerability scanner for containers and other artifacts. It detects vulnerabilities in OS packages and application dependencies.

### [Scan a DHI using Trivy](#scan-a-dhi-using-trivy)

After installing Trivy, you can scan a Docker Hardened Image by pulling the image and running the scan command:

```console
$ docker login dhi.io
$ docker pull dhi.io/<image>:<tag>
$ trivy image --scanners vuln dhi.io/<image>:<tag>
```

To filter vulnerabilities using VEX statements, Trivy supports multiple approaches. Docker recommends using VEX Hub, which provides a seamless workflow for automatically downloading and applying VEX statements from configured repositories.

#### [Using VEX Hub (recommended)](#using-vex-hub-recommended)

Configure Trivy to download the Docker Hardened Images advisories repository from VEX Hub. Run the following commands to set up the VEX repository:

```console
$ trivy vex repo init
$ cat << REPO > ~/.trivy/vex/repository.yaml
repositories:
  - name: default
    url: https://github.com/aquasecurity/vexhub
    enabled: true
    username: ""
    password: ""
    token: ""
  - name: dhi-vex
    url: https://github.com/docker-hardened-images/advisories
    enabled: true
REPO
$ trivy vex repo list
$ trivy vex repo download
```

After setting up VEX Hub, you can scan a Docker Hardened Image with VEX filtering:

```console
$ docker login dhi.io
$ docker pull dhi.io/<image>:<tag>
$ trivy image --scanners vuln --vex repo dhi.io/<image>:<tag>
```

For example, scanning the `dhi.io/python:3.13` image:

```console
$ trivy image --scanners vuln --vex repo dhi.io/python:3.13
```

Example output:

```plaintext
Report Summary

┌─────────────────────────────────────────────────────────────────────────────┬────────────┬─────────────────┐
│                                   Target                                    │    Type    │ Vulnerabilities │
├─────────────────────────────────────────────────────────────────────────────┼────────────┼─────────────────┤
│ dhi.io/python:3.13 (debian 13.2)                                            │   debian   │        0        │
├─────────────────────────────────────────────────────────────────────────────┼────────────┼─────────────────┤
│ opt/python-3.13.11/lib/python3.13/site-packages/pip-25.3.dist-info/METADATA │ python-pkg │        0        │
└─────────────────────────────────────────────────────────────────────────────┴────────────┴─────────────────┘
Legend:
- '-': Not scanned
- '0': Clean (no security findings detected)
```

The `--vex repo` flag applies VEX statements from the configured repository during the scan, which filters out known non-exploitable CVEs.

#### [Using local VEX files](#using-local-vex-files)

In addition to VEX Hub, Trivy also supports the use of local VEX files for vulnerability filtering. You can download the VEX attestation that Docker Hardened Images provide and use it directly with Trivy.

First, download the VEX attestation for your image:

```console
$ docker scout vex get dhi.io/<image>:<tag> --output vex.json
```

Then scan the image with the local VEX file:

```console
$ trivy image --scanners vuln --vex vex.json dhi.io/<image>:<tag>
```

## [Wiz](#wiz)

[Wiz](https://www.wiz.io/) is a cloud security platform that includes container image scanning capabilities with support for DHI VEX attestations. Wiz CLI automatically consumes VEX statements from Docker Hardened Images to provide accurate vulnerability assessments.

### [Scan a DHI using Wiz CLI](#scan-a-dhi-using-wiz-cli)

After acquiring a Wiz subscription and installing the Wiz CLI, you can scan a Docker Hardened Image by pulling the image and running the scan command:

```console
$ docker login dhi.io
$ docker pull dhi.io/<image>:<tag>
$ wizcli scan container-image dhi.io/<image>:<tag>
```

## [Mend.io](#mendio)

[Mend.io](https://www.mend.io/) is an application security platform that includes container image scanning with support for DHI VEX attestations. Mend Container automatically retrieves and applies VEX statements from Docker Hardened Images and combines them with Mend's reachability analysis for comprehensive vulnerability assessment.

### [Scan a DHI using Mend.io](#scan-a-dhi-using-mendio)

After acquiring a Mend.io subscription and configuring [Mend Container](https://docs.mend.io/container/latest/), Mend automatically detects Docker Hardened Images and applies their VEX data without requiring any additional configuration. When you scan a Docker Hardened Image through the Mend AppSec Platform, VEX statements are automatically retrieved and attached as risk factors to each finding.

You can view and filter DHI-specific findings in the Mend AppSec Platform under **Security > Containers > Packages**, where a Docker badge identifies hardened image packages. Use the **Risk Factors** column to filter by VEX statuses such as Not Affected, Fixed, or Under Investigation.

For more information, see the [Mend.io Docker Hardened Images documentation](https://docs.mend.io/platform/latest/docker-hardened-images).

## [Black Duck](#black-duck)

[Black Duck](https://www.blackduck.com/) identifies Docker Hardened Images and applies their VEX statements without additional configuration.

For more information, see the [Black Duck documentation](https://documentation.blackduck.com/bundle/bd-hub/page/Reporting/vexReport_global.html).

## [Export VEX attestations](#export-vex-attestations)

For scanners that need local VEX files (like Grype or Trivy with local files), you can export the VEX attestations from Docker Hardened Images.

> Note
>
> By default, VEX attestations are fetched from `registry.scout.docker.com`. Ensure that you can access this registry if your network has outbound restrictions. You can also mirror the attestations to an alternate registry. For more details, see [Mirror to a third-party registry](https://docs.docker.com/dhi/how-to/mirror/#mirror-to-a-third-party-registry).

Export VEX attestations to a JSON file:

```console
$ docker scout vex get dhi.io/<image>:<tag> --output vex.json
```

> Note
>
> The `docker scout vex get` command requires [Docker Scout CLI](https://github.com/docker/scout-cli/) version 1.18.3 or later.
>
> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://docs/dhi-python:3.13` instead of `docs/dhi-python:3.13`.

----
url: https://docs.docker.com/dhi/migration/examples/python/
----

# Python

***

***

This example shows how to migrate a Python application to Docker Hardened Images.

The following examples show Dockerfiles before and after migration to Docker Hardened Images. Each example includes five variations:

* Before (Ubuntu): A sample Dockerfile using Ubuntu-based images, before migrating to DHI
* Before (Wolfi): A sample Dockerfile using Wolfi distribution images, before migrating to DHI
* Before (DOI): A sample Dockerfile using Docker Official Images, before migrating to DHI
* After (multi-stage): A sample Dockerfile after migrating to DHI with multi-stage builds (recommended for minimal, secure images)
* After (single-stage): A sample Dockerfile after migrating to DHI with single-stage builds (simpler but results in a larger image with a broader attack surface)

> Note
>
> Multi-stage builds are recommended for most use cases. Single-stage builds are supported for simplicity, but come with tradeoffs in size and security.
>
> You must authenticate to `dhi.io` before you can pull Docker Hardened Images. Use your Docker ID credentials (the same username and password you use for Docker Hub). If you don't have a Docker account, [create one](https://docs.docker.com/accounts/create-account/) for free.
>
> Run `docker login dhi.io` to authenticate.

```dockerfile
#syntax=docker/dockerfile:1

FROM ubuntu/python:3.13-24.04_stable AS builder

ENV LANG=C.UTF-8
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

WORKDIR /app

RUN python -m venv /app/venv
COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

FROM ubuntu/python:3.13-24.04_stable

WORKDIR /app

ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

COPY app.py ./
COPY --from=builder /app/venv /app/venv

ENTRYPOINT [ "python", "/app/app.py" ]
```

```dockerfile
#syntax=docker/dockerfile:1

FROM cgr.dev/chainguard/python:latest-dev AS builder

ENV LANG=C.UTF-8
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

WORKDIR /app

RUN python -m venv /app/venv
COPY requirements.txt .

# Install any additional packages if needed using apk
# RUN apk add --no-cache gcc musl-dev

RUN pip install --no-cache-dir -r requirements.txt

FROM cgr.dev/chainguard/python:latest

WORKDIR /app

ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

COPY app.py ./
COPY --from=builder /app/venv /app/venv

ENTRYPOINT [ "python", "/app/app.py" ]
```

```dockerfile
#syntax=docker/dockerfile:1

FROM python:latest AS builder

ENV LANG=C.UTF-8
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

WORKDIR /app

RUN python -m venv /app/venv
COPY requirements.txt .

# Install any additional packages if needed using apt
# RUN apt-get update && apt-get install -y gcc && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir -r requirements.txt

FROM python:latest

WORKDIR /app

ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

COPY app.py ./
COPY --from=builder /app/venv /app/venv

ENTRYPOINT [ "python", "/app/app.py" ]
```

```dockerfile
#syntax=docker/dockerfile:1

# === Build stage: Install dependencies and create virtual environment ===
FROM dhi.io/python:3.13-alpine3.21-dev AS builder

ENV LANG=C.UTF-8
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

WORKDIR /app

RUN python -m venv /app/venv
COPY requirements.txt .

# Install any additional packages if needed using apk
# RUN apk add --no-cache gcc musl-dev

RUN pip install --no-cache-dir -r requirements.txt

# === Final stage: Create minimal runtime image ===
FROM dhi.io/python:3.13-alpine3.21

WORKDIR /app

ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

COPY app.py ./
COPY --from=builder /app/venv /app/venv

ENTRYPOINT [ "python", "/app/app.py" ]
```

```dockerfile
#syntax=docker/dockerfile:1

FROM dhi.io/python:3.13-alpine3.21-dev

ENV LANG=C.UTF-8
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"

WORKDIR /app

RUN python -m venv /app/venv
COPY requirements.txt .

# Install any additional packages if needed using apk
# RUN apk add --no-cache gcc musl-dev

RUN pip install --no-cache-dir -r requirements.txt

COPY app.py ./

ENTRYPOINT [ "python", "/app/app.py" ]
```

----
url: https://docs.docker.com/dhi/how-to/build/
----

# Create and build a Docker Hardened Image

***

Table of contents

***

Docker Hardened Images (DHI) are built from declarative YAML definition files instead of traditional Dockerfiles. A single YAML file describes exactly what goes into an image: packages, users, environment variables, entrypoint, and metadata. The DHI build system produces a signed image containing only the required packages, with a Software Bill of Materials (SBOM) and SLSA Build Level 3 provenance.

This page explains how to write a DHI definition file, build images locally, and use advanced patterns such as build stages, third-party repositories, file paths, and dev variants.

> Important
>
> The DHI build system pulls base images and build tools from `dhi.io`, so you must authenticate to that registry before building a definition file. Use your Docker ID credentials (the same username and password you use for Docker Hub) when signing in.
>
> Run `docker login dhi.io` to authenticate.

## [How DHI builds differ from Dockerfiles](#how-dhi-builds-differ-from-dockerfiles)

A Dockerfile is a sequence of imperative instructions: `RUN`, `COPY`, `FROM`. A DHI definition file is a declarative specification. You describe the desired state of the image, and the build system figures out how to produce it.

Every DHI definition starts with a syntax directive that tells BuildKit which DHI build frontend to use. The frontend is the component that parses and processes YAML definitions instead of the default Dockerfile parser:

```yaml
# syntax=dhi.io/build:2-alpine3.23
```

The frontend version corresponds to the base distribution:

| Distribution         | Syntax directive                     |
| -------------------- | ------------------------------------ |
| Alpine 3.22          | `# syntax=dhi.io/build:2-alpine3.22` |
| Alpine 3.23          | `# syntax=dhi.io/build:2-alpine3.23` |
| Debian 12 (Bookworm) | `# syntax=dhi.io/build:2-debian12`   |
| Debian 13 (Trixie)   | `# syntax=dhi.io/build:2-debian13`   |

The DHI build system reads the YAML, resolves packages from the specified repositories, assembles the filesystem, creates user accounts, sets metadata, and produces a signed OCI image.

## [Explore the catalog for reference](#explore-the-catalog-for-reference)

The [DHI catalog repository](https://github.com/docker-hardened-images/catalog) is open source under Apache 2.0 and contains every official image definition. Studying existing definitions is the best way to learn the YAML patterns for different image types.

The catalog follows this directory structure:

```text
catalog/
├── image/
│   ├── alpine-base/
│   │   ├── alpine-3.23/
│   │   │   ├── 3.23.yaml            # runtime variant
│   │   │   └── 3.23-dev.yaml        # dev variant
│   │   ├── guides.md
│   │   ├── info.yaml
│   │   ├── logo.svg
│   │   └── overview.md
│   ├── nginx/
│   │   ├── alpine-3.22/
│   │   ├── alpine-3.23/
│   │   │   ├── mainline.yaml
│   │   │   ├── mainline-dev.yaml
│   │   │   ├── stable.yaml
│   │   │   └── stable-dev.yaml
│   │   ├── debian-12/
│   │   ├── debian-13/
│   │   ├── bin/
│   │   ├── guides.md
│   │   ├── info.yaml
│   │   ├── logo.svg
│   │   └── overview.md
│   └── redis/
│       ├── debian-13/
│       │   ├── 8.0.yaml              # runtime
│       │   ├── 8.0-dev.yaml          # dev
│       │   ├── 8.0-compat.yaml       # compat runtime
│       │   └── 8.0-compat-dev.yaml   # compat dev
│       ├── guides.md
│       ├── info.yaml
│       ├── logo.svg
│       └── overview.md
├── chart/
└── package/
```

Each image organizes its variants by distribution. Images support multiple variant types:

* A `runtime` variant is minimal and typically runs as a non-root user.
* A `dev` variant adds a shell, package manager, and development tools.
* A compatibility variant adds common shell utilities such as `bash`, `coreutils`, `grep`, and `sed` for use with existing workflows. Compatibility images use the `flavor: compat` field alongside a `runtime` or `dev` variant.
* A compatibility-dev variant combines the compatibility packages with dev tools.

Some images also support additional flavors such as `sfw` (software framework) variants. Refer to the catalog for the full list of available variants for each image.

## [Try it: build a catalog image](#try-it-build-a-catalog-image)

Before writing your own definition, try building an existing catalog image directly from GitHub:

```console
$ docker buildx build \
    https://raw.githubusercontent.com/docker-hardened-images/catalog/refs/heads/main/image/alpine-base/alpine-3.23/3.23.yaml \
    --sbom=generator=dhi.io/scout-sbom-indexer:1 \
    --provenance=1 \
    --tag my-alpine-base:3.23 \
    --load
```

This downloads the definition file directly from GitHub and builds it locally. After the build completes, verify the image:

```console
$ docker images my-alpine-base
```

To modify an image, clone the catalog and edit the YAML files locally:

```console
$ git clone https://github.com/docker-hardened-images/catalog.git
$ cd catalog
```

## [YAML schema reference](#yaml-schema-reference)

The following sections describe the fields available in a DHI definition file.

### [Required fields](#required-fields)

Every definition must include these top-level fields:

| Field       | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `name`      | Human-readable name for the image.                             |
| `image`     | Full registry path, such as `dhi.io/my-image`.                 |
| `variant`   | Image variant type: `runtime` or `dev`.                        |
| `tags`      | List of image tags.                                            |
| `platforms` | Target architectures, such as `linux/amd64` and `linux/arm64`. |
| `contents`  | Package repositories and packages to install.                  |

### [Image metadata](#image-metadata)

These fields add metadata to the image:

| Field         | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `os-release`  | Defines the `/etc/os-release` contents inside the image.          |
| `annotations` | OCI image annotations such as description and license.            |
| `dates`       | Release date and end-of-life date.                                |
| `vars`        | Build-time variables for templating.                              |
| `flavor`      | Image flavor modifier, such as `compat` for compatibility images. |

### [Container configuration](#container-configuration)

These fields control how the container runs:

| Field         | Description                                 |
| ------------- | ------------------------------------------- |
| `accounts`    | Users, groups, and the `run-as` user.       |
| `environment` | Environment variables.                      |
| `entrypoint`  | Container entrypoint command.               |
| `cmd`         | Default command arguments.                  |
| `work-dir`    | Working directory inside the container.     |
| `volumes`     | Volume mount points.                        |
| `ports`       | Exposed network ports.                      |
| `paths`       | Directories, files, and symlinks to create. |

### [Advanced fields](#advanced-fields)

These fields support more complex build patterns:

| Field                | Description                                        |
| -------------------- | -------------------------------------------------- |
| `contents.builds`    | Build stages with shell pipelines.                 |
| `contents.keyring`   | Signing keys for third-party package repositories. |
| `contents.artifacts` | Pre-built OCI artifacts to include.                |
| `contents.mappings`  | Package URL (purl) mappings for SBOM accuracy.     |
| `contents.files`     | Source files fetched from Git URLs with checksums. |

## [Create a minimal image](#create-a-minimal-image)

Start with the simplest possible definition: an Alpine base image with a non-root user.

Create a directory for your project and add a file called `base.yaml`:

```yaml
# syntax=dhi.io/build:2-alpine3.23

name: My Base Image
image: my-registry/my-base
variant: runtime
tags:
  - "1.0.0"
  - "1.0"
platforms:
  - linux/amd64
  - linux/arm64

contents:
  repositories:
    - https://dl-cdn.alpinelinux.org/alpine/v3.23/main
    - https://dl-cdn.alpinelinux.org/alpine/v3.23/community
  packages:
    - alpine-baselayout-data
    - busybox
    - ca-certificates-bundle

accounts:
  run-as: nonroot
  users:
    - name: nonroot
      uid: 65532
      gid: 65532
  groups:
    - name: nonroot
      gid: 65532
      members:
        - nonroot

os-release:
  name: Docker Hardened Images (Alpine)
  id: alpine
  version-id: "3.23"
  pretty-name: My Hardened Image
  home-url: https://docker.com/products/hardened-images/
  bug-report-url: https://docker.com/support/

environment:
  SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt

annotations:
  org.opencontainers.image.description: A minimal Alpine base image

cmd:
  - /bin/sh
```

In this definition:

* `contents.repositories` uses full URLs to Alpine package mirrors.
* `contents.packages` lists exact Alpine package names.
* The `accounts` block creates a `nonroot` user (UID 65532) and sets it as the default user for the container.
* The `os-release` block defines what appears in `/etc/os-release`. Always include `bug-report-url` alongside `home-url`.
* The `annotations` block adds OCI metadata visible in registries and Docker Scout reports.

Build the image:

```console
$ docker buildx build . -f base.yaml \
    --sbom=generator=dhi.io/scout-sbom-indexer:1 \
    --provenance=1 \
    --tag my-base:latest \
    --load
```

> Note
>
> The `tags` field in the spec file defines the image metadata (variant and version labels embedded in the image manifest). The `--tag` flag on the CLI sets the OCI image reference used to push or load the image. These serve different purposes - the spec file tags describe *what the image is*, while the CLI tag determines *where it's stored*.

## [Use a Debian base with third-party repositories](#use-a-debian-base-with-third-party-repositories)

For applications that require Debian packages or third-party APT repositories, use the Debian syntax directive. The following example builds a Redis image from the official Redis APT repository.

Create a file called `redis.yaml`:

```yaml
# syntax=dhi.io/build:2-debian13

name: Redis 8.0.x
image: my-registry/my-redis
variant: runtime
tags:
  - "8.0"
  - "8.0.5"
platforms:
  - linux/amd64
  - linux/arm64

contents:
  repositories:
    - deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb trixie main
  keyring:
    - https://packages.redis.io/gpg
  packages:
    - '!libelogind0'
    - '!mawk'
    - '!original-awk'
    - base-files
    - libpcre2-8-0
    - libssl3t64
    - libstdc++6
    - libsystemd0
    - redis=6:8.0.5-1rl1~trixie1
    - redis-server=6:8.0.5-1rl1~trixie1
    - redis-tools=6:8.0.5-1rl1~trixie1
    - tini
  mappings:
    redis: pkg:deb/redis/redis@6:8.0.5-1rl1~trixie1?os_name=debian&os_version=13
    redis-server: pkg:deb/redis/redis-server@6:8.0.5-1rl1~trixie1?os_name=debian&os_version=13
    redis-tools: pkg:deb/redis/redis-tools@6:8.0.5-1rl1~trixie1?os_name=debian&os_version=13

accounts:
  run-as: nonroot
  users:
    - name: nonroot
      uid: 65532
      gid: 65532
  groups:
    - name: nonroot
      gid: 65532
      members:
        - nonroot

os-release:
  name: Docker Hardened Images (Debian)
  id: debian
  version-id: "13"
  version-codename: trixie
  pretty-name: Docker Hardened Images/Debian GNU/Linux 13 (trixie)
  home-url: https://docker.com/products/hardened-images/
  bug-report-url: https://docker.com/support/

work-dir: /data

environment:
  REDIS_VERSION: 8.0.5

annotations:
  org.opencontainers.image.description: A minimal Redis image
  org.opencontainers.image.licenses: AGPL-3.0-only

entrypoint:
  - /usr/bin/tini
  - --

cmd:
  - redis-server
  - /etc/redis/redis.conf
  - --include
  - /etc/redis/conf.d/*.conf
```

This example introduces several patterns:

* **Third-party repositories**: The `repositories` field uses the Debian `deb [signed-by=...] URL suite component` format for APT sources.
* **Keyring**: The `keyring` field downloads the GPG key used to verify packages from the third-party repository.
* **Package exclusions**: Prefix a package name with `!` to explicitly exclude it. This prevents unwanted dependencies from being installed. In this case, `!libelogind0`, `!mawk`, and `!original-awk` are excluded.
* **Debian version pinning**: Use the full epoch format, `redis-server=6:8.0.5-1rl1~trixie1`, to pin exact package versions.
* **SBOM mappings**: The `mappings` field provides Package URL (purl) metadata so that Docker Scout can accurately identify the software in the SBOM.
* **Init process**: The `entrypoint` uses `tini` as a lightweight init process (PID 1) to handle signal forwarding and zombie process reaping.
* **Config includes**: The `cmd` uses `--include /etc/redis/conf.d/*.conf` so that configuration files created in the `paths` section are loaded at startup.

## [Create paths](#create-paths)

Use the `paths` field to create directories, files with inline content, and symlinks inside the image. The following example extends the Redis definition with the paths required for operation:

```yaml
paths:
  - type: directory
    path: /var/lib/redis
    uid: 65532
    gid: 65532
    mode: "0755"
  - type: directory
    path: /var/log/redis
    uid: 65532
    gid: 65532
    mode: "0755"
  - type: directory
    path: /run/redis/
    uid: 65532
    gid: 65532
    mode: "0755"
  - type: directory
    path: /data
    uid: 65532
    gid: 65532
    mode: "0755"
  - type: file
    path: /etc/redis/conf.d/docker.conf
    content: |
      daemonize no
      bind 0.0.0.0 -::1
      logfile ""
    uid: 0
    gid: 0
    mode: "0555"
  - type: symlink
    path: /usr/bin/redis-sentinel
    uid: 0
    gid: 0
    source: /usr/bin/redis-check-rdb
```

Three path types are available:

| Type        | Required fields                         | Description                         |
| ----------- | --------------------------------------- | ----------------------------------- |
| `directory` | `path`, `uid`, `gid`, `mode`            | Creates an empty directory.         |
| `file`      | `path`, `content`, `uid`, `gid`, `mode` | Creates a file with inline content. |
| `symlink`   | `path`, `source`, `uid`, `gid`          | Creates a symbolic link.            |

The `mode` field uses a string representation of the octal permission bits, such as `"0755"` for read-write-execute by owner or `"0555"` for read-execute by all. Note that the `file` type supports inline `content` using a YAML multi-line string.

## [Add build stages](#add-build-stages)

For images that need to run shell commands during the build, such as configuring files, creating symlinks, or adjusting permissions, use the `contents.builds` field. Each build stage has its own packages, a pipeline of named steps, and output mappings.

The following example configures Nginx during the build to run on an unprivileged port and disable server tokens:

```yaml
# syntax=dhi.io/build:2-alpine3.23

name: Nginx mainline
image: my-registry/my-nginx
variant: runtime
tags:
  - "1.29"
platforms:
  - linux/amd64
  - linux/arm64

contents:
  repositories:
    - https://dl-cdn.alpinelinux.org/alpine/v3.23/main
    - https://dl-cdn.alpinelinux.org/alpine/v3.23/community
    - http://nginx.org/packages/mainline/alpine/v3.23/main
  keyring:
    - https://nginx.org/keys/nginx_signing.rsa.pub
  packages:
    - alpine-baselayout-data
    - busybox
    - musl-utils
    - nginx=1.29.5-r1
  builds:
    - name: nginx
      contents:
        repositories:
          - https://dl-cdn.alpinelinux.org/alpine/v3.23/main
          - https://dl-cdn.alpinelinux.org/alpine/v3.23/community
          - http://nginx.org/packages/mainline/alpine/v3.23/main
        keyring:
          - https://nginx.org/keys/nginx_signing.rsa.pub
        packages:
          - alpine-baselayout-data
          - bash
          - musl-utils
          - nginx=1.29.5-r1
      pipeline:
        - name: install
          runs: |
            set -eux -o pipefail

            ln -sf /dev/stdout /var/log/nginx/access.log
            ln -sf /dev/stderr /var/log/nginx/error.log

            sed -i "s,listen       80;,listen       8080;," /etc/nginx/conf.d/default.conf
            sed -i "/user  nginx;/d" /etc/nginx/nginx.conf
            sed -i "s,pid        /run/nginx.pid;,pid        /var/run/nginx.pid;," /etc/nginx/nginx.conf
            sed -i '/^http {$/a\    server_tokens off;' /etc/nginx/nginx.conf

            chown -R 65532:65532 /var/cache/nginx
            chmod -R g+w /var/cache/nginx
            chown -R 65532:65532 /etc/nginx
            chmod -R g+w /etc/nginx
            chown -R 65532:65532 /run
            chown -R 65532:65532 /run/lock
            chown -R 65532:65532 /var/run
            chown -R 65532:65532 /var/log/nginx
      outputs:
        - source: /
          target: /
          uid: 0
          gid: 0
          diff: true

accounts:
  run-as: nginx
  users:
    - name: nginx
      uid: 65532
      gid: 65532
  groups:
    - name: nginx
      gid: 65532
      members:
        - nginx
    - name: www-data
      gid: 82

os-release:
  name: Docker Hardened Images (Alpine)
  id: alpine
  version-id: "3.23"
  pretty-name: Docker Hardened Images/Alpine Linux v3.23
  home-url: https://docker.com/products/hardened-images/
  bug-report-url: https://docker.com/support/

environment:
  NGINX_VERSION: 1.29.5-r1

annotations:
  org.opencontainers.image.description: A minimal Nginx image
  org.opencontainers.image.licenses: BSD-2-Clause

entrypoint:
  - nginx

cmd:
  - -g
  - daemon off;

ports:
  - 8080/tcp
```

Key patterns in this definition:

| Element      | Description                                                                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contents`   | Each build stage has its own `contents` section. Include packages needed only during the build, such as `bash`.                                   |
| `pipeline`   | Contains named steps that run shell commands. Always start scripts with `set -eux -o pipefail`.                                                   |
| `outputs`    | Copies results from the build stage into the final image. Setting `diff: true` copies only files that changed, keeping the image minimal.         |
| `accounts`   | Nginx uses a dedicated `nginx` user (UID 65532) instead of `nonroot`. The `www-data` group (GID 82) is also created for web server compatibility. |
| `musl-utils` | Required in both the main and build packages for Alpine-based Nginx images.                                                                       |

## [Use OCI artifacts as package sources](#use-oci-artifacts-as-package-sources)

Instead of installing packages from Alpine or Debian repositories, you can pull pre-built binaries from DHI package artifacts. This is how the catalog builds images like Python and Node.js — the runtime is compiled separately and published as an OCI artifact, then referenced by digest in the image definition.

Add the `artifacts` field under `contents`:

```yaml
contents:
  repositories:
    - https://dl-cdn.alpinelinux.org/alpine/v3.23/main
    - https://dl-cdn.alpinelinux.org/alpine/v3.23/community
  packages:
    - alpine-baselayout-data
    - bzip2
    - ca-certificates-bundle
    - expat
    - gdbm
    - libffi
    - mpdecimal
    - musl
    - ncurses
    - openssl
    - readline
    - sqlite-libs
    - tzdata
    - zlib
  artifacts:
    - name: dhi.io/pkg-python:3.13.12-alpine3.23@sha256:052b3b915055006a27c42470eed5c65d7ee92d2c3de47ecaedcc6bbd36077b95
      includes:
        - opt/**
      uid: 0
      gid: 0
```

| Field        | Description                                                                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`       | Full OCI reference with digest pin. Always use `@sha256:` for reproducibility.                                                                         |
| `includes`   | Glob patterns for files to extract from the artifact. Paths are resolved from the filesystem root; `opt/**` includes everything under the `/opt` path. |
| `excludes`   | Glob patterns for files to skip. Useful for removing headers, docs, or unused binaries.                                                                |
| `uid`, `gid` | Ownership for extracted files.                                                                                                                         |

Available DHI packages are in the [`package/`](https://github.com/docker-hardened-images/catalog/tree/main/package) directory of the catalog repository.

## [Create a dev variant](#create-a-dev-variant)

A dev variant of an image adds a shell, package manager, and development tools. This is useful for debugging and for use as a build stage in multi-stage workflows.

To create a dev variant, change the `variant` field and enable root access:

```yaml
# syntax=dhi.io/build:2-alpine3.23

name: Alpine 3.23 Base (dev)
image: my-registry/my-base
variant: dev
tags:
  - "1.0-dev"
platforms:
  - linux/amd64
  - linux/arm64

contents:
  repositories:
    - https://dl-cdn.alpinelinux.org/alpine/v3.23/main
    - https://dl-cdn.alpinelinux.org/alpine/v3.23/community
  packages:
    - alpine-baselayout-data
    - apk-tools
    - busybox
    - ca-certificates-bundle

accounts:
  root: true
  run-as: root
  users:
    - name: nonroot
      uid: 65532
      gid: 65532
  groups:
    - name: nonroot
      gid: 65532
      members:
        - nonroot

os-release:
  name: Docker Hardened Images (Alpine)
  id: alpine
  version-id: "3.23"
  pretty-name: Docker Hardened Images/Alpine Linux v3.23
  home-url: https://docker.com/products/hardened-images/
  bug-report-url: https://docker.com/support/

environment:
  SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt

annotations:
  org.opencontainers.image.description: A minimal Alpine base image

cmd:
  - /bin/sh
```

The key differences from a runtime variant:

* `variant: dev` instead of `variant: runtime`.
* `accounts.root: true` enables the root account.
* `run-as: root` sets root as the default user.
* `apk-tools` is added to packages, giving the image a package manager.
* The `nonroot` user is still defined so that applications can switch to an unprivileged user at runtime.

For Debian-based dev variants, add `apt` instead of `apk-tools` and include the `DEBIAN_FRONTEND: noninteractive` environment variable.

## [Create a compatibility variant](#create-a-compatibility-variant)

A compatibility variant includes common shell utilities for use with scripts and automation tools that expect a standard Linux userland. Compatibility images use the `flavor` field:

```yaml
variant: runtime
flavor: compat
```

A compatibility variant adds packages such as `bash`, `coreutils`, `findutils`, `grep`, `hostname`, `openssl`, `procps`, and `sed` alongside the application packages. A compatibility-dev variant combines both the compatibility packages and the dev tools:

```yaml
variant: dev
flavor: compat
```

Refer to the Redis compatibility images in the catalog for a complete example of the compatibility pattern.

## [Set ports and volumes](#set-ports-and-volumes)

Use the `ports` field to declare which ports the container exposes. Always use unprivileged ports (higher than 1024) when the container runs as a non-root user.

```yaml
ports:
  - 8080/tcp
```

Use the `volumes` field to declare volume mount points:

```yaml
volumes:
  - /data
```

## [Set annotations](#set-annotations)

OCI annotations add machine-readable metadata to the image. Use the `annotations` field:

```yaml
annotations:
  org.opencontainers.image.description: A minimal hardened application image
  org.opencontainers.image.licenses: Apache-2.0
```

These annotations appear in Docker Scout reports and container registry interfaces.

## [Build and verify](#build-and-verify)

### [Build the image](#build-the-image)

Build a single-platform image for local testing:

```console
$ docker buildx build . -f my-image.yaml \
    --sbom=generator=dhi.io/scout-sbom-indexer:1 \
    --provenance=1 \
    --tag my-image:latest \
    --load
```

### [Inspect the SBOM](#inspect-the-sbom)

View the generated Software Bill of Materials:

```console
$ docker scout sbom my-image:latest
```

### [Scan for vulnerabilities](#scan-for-vulnerabilities)

Check the image against known CVE databases:

```console
$ docker scout cves my-image:latest
```

### [Compare with a non-hardened image](#compare-with-a-non-hardened-image)

Measure the security improvement against an equivalent non-hardened image:

```console
$ docker scout compare my-image:latest \
    --to <non-hardened-equivalent>:<tag> \
    --platform linux/amd64
```

Replace `<non-hardened-equivalent>` with the Docker Official Image or community image you're comparing against.

### [Inspect with Docker Debug](#inspect-with-docker-debug)

Verify the os-release and entrypoint configuration:

```console
$ docker debug my-image:latest
```

The output shows the detected distribution name from your `os-release` configuration and runs an entrypoint lint check.

## [Push to a registry](#push-to-a-registry)

Tag and push the image to your container registry:

```console
$ docker tag my-image:latest <your-namespace>/my-image:latest
```

```console
$ docker push <your-namespace>/my-image:latest
```

Replace `<your-namespace>` with your Docker Hub username or organization namespace.

## [Contribute to the catalog](#contribute-to-the-catalog)

Docker Hardened Images is an open source project. You can contribute new image definitions or improve existing ones by submitting a pull request to the [catalog repository](https://github.com/docker-hardened-images/catalog).

To contribute a new image:

1. Fork the catalog repository.
2. Create a directory under `image/` following the naming convention: `image/<image-name>/<distribution>/`.
3. Add your YAML definition files (one per variant).
4. Add an `info.yaml` with display name, description, and categories.
5. Add an `overview.md` describing the image.
6. Add a `logo.svg` for the image icon.
7. Add a `guides.md` with usage documentation.
8. Open a pull request against the `main` branch.

For more details, read the [contributing guide](https://github.com/docker-hardened-images/catalog/blob/main/CONTRIBUTING.md) in the catalog repository.

----
url: https://docs.docker.com/reference/cli/docker/compose/start/
----

# docker compose start

***

| Description | Start services                      |
| ----------- | ----------------------------------- |
| Usage       | `docker compose start [SERVICE...]` |

## [Description](#description)

Starts existing containers for a service

## [Options](#options)

| Option           | Default | Description                                                                 |
| ---------------- | ------- | --------------------------------------------------------------------------- |
| `--wait`         |         | Wait for services to be running\|healthy. Implies detached mode.            |
| `--wait-timeout` |         | Maximum duration in seconds to wait for the project to be running\|healthy  |

----
url: https://docs.docker.com/reference/cli/docker/config/inspect/
----

# docker config inspect

***

| Description | Display detailed information on one or more configs  |
| ----------- | ---------------------------------------------------- |
| Usage       | `docker config inspect [OPTIONS] CONFIG [CONFIG...]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Inspects the specified config.

By default, this renders all results in a JSON array. If a format is specified, the given template will be executed for each result.

Go's [text/template](https://pkg.go.dev/text/template) package describes all the details of the format.

For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).

> Note
>
> This is a cluster management command, and must be executed on a Swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                             |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --format`](#format) |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `--pretty`                |         | Print the information in a human friendly format                                                                                                                                                                                        |

## [Examples](#examples)

### [Inspect a config by name or ID](#inspect-a-config-by-name-or-id)

You can inspect a config, either by its *name*, or *ID*

For example, given the following config:

```console
$ docker config ls

ID                          NAME                CREATED             UPDATED
eo7jnzguqgtpdah3cm5srfb97   my_config           3 minutes ago       3 minutes ago
```

```console
$ docker config inspect config.json
```

The output is in JSON format, for example:

```json
[
  {
    "ID": "eo7jnzguqgtpdah3cm5srfb97",
    "Version": {
      "Index": 17
    },
    "CreatedAt": "2017-03-24T08:15:09.735271783Z",
    "UpdatedAt": "2017-03-24T08:15:09.735271783Z",
    "Spec": {
      "Name": "my_config",
      "Labels": {
        "env": "dev",
        "rev": "20170324"
      },
      "Data": "aGVsbG8K"
    }
  }
]
```

### [Format the output (--format)](#format)

You can use the --format option to obtain specific information about a config. The following example command outputs the creation time of the config.

```console
$ docker config inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97

2017-03-24 08:15:09.735271783 +0000 UTC
```

----
url: https://docs.docker.com/guides/java/
----

# Java language-specific guide

***

This guide demonstrates how to containerize Java applications using Docker.

**Time to complete** 20 minutes

The Java getting started guide teaches you how to create a containerized Spring Boot application using Docker. In this module, you’ll learn how to:

* Containerize and run a Spring Boot application with Maven
* Set up a local development environment to connect a database to the container, configure a debugger, and use Compose Watch for live reload
* Run your unit tests inside a container
* Configure a CI/CD pipeline for your application using GitHub Actions
* Deploy your containerized application locally to Kubernetes to test and debug your deployment

After completing the Java getting started modules, you should be able to containerize your own Java application based on the examples and instructions provided in this guide.

Get started containerizing your first Java app.

## [Modules](#modules)

1. [Containerize your app](https://docs.docker.com/guides/java/containerize/)

   Learn how to containerize a Java application.

2. [Develop your app](https://docs.docker.com/guides/java/develop/)

   Learn how to develop your application locally.

3. [Run your tests](https://docs.docker.com/guides/java/run-tests/)

   How to build and run your Java tests

4. [Configure CI/CD](https://docs.docker.com/guides/java/configure-ci-cd/)

   Learn how to Configure CI/CD for your Java application

5. [Test your deployment](https://docs.docker.com/guides/java/deploy/)

   Learn how to develop locally using Kubernetes

----
url: https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/
----

# Create a swarm

***

***

After you complete the [tutorial setup](https://docs.docker.com/engine/swarm/swarm-tutorial/) steps, you're ready to create a swarm. Make sure the Docker Engine daemon is started on the host machines.

1. Open a terminal and ssh into the machine where you want to run your manager node. This tutorial uses a machine named `manager1`.

2. Run the following command to create a new swarm:

   ```console
   $ docker swarm init --advertise-addr <MANAGER-IP>
   ```

   In the tutorial, the following command creates a swarm on the `manager1` machine:

   ```console
   $ docker swarm init --advertise-addr 192.168.99.100
   Swarm initialized: current node (dxn1zf6l61qsb1josjja83ngz) is now a manager.

   To add a worker to this swarm, run the following command:

       docker swarm join \
       --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
       192.168.99.100:2377

   To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
   ```

   The `--advertise-addr` flag configures the manager node to publish its address as `192.168.99.100`. The other nodes in the swarm must be able to access the manager at the IP address.

   The output includes the commands to join new nodes to the swarm. Nodes will join as managers or workers depending on the value for the `--token` flag.

3. Run `docker info` to view the current state of the swarm:

   ```console
   $ docker info

   Containers: 2
   Running: 0
   Paused: 0
   Stopped: 2
     ...snip...
   Swarm: active
     NodeID: dxn1zf6l61qsb1josjja83ngz
     Is Manager: true
     Managers: 1
     Nodes: 1
     ...snip...
   ```

4. Run the `docker node ls` command to view information about nodes:

   ```console
   $ docker node ls

   ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
   dxn1zf6l61qsb1josjja83ngz *  manager1  Ready   Active        Leader
   ```

   The `*` next to the node ID indicates that you're currently connected on this node.

   Docker Engine Swarm mode automatically names the node with the machine host name. The tutorial covers other columns in later steps.

## [Next steps](#next-steps)

Next, you'll add two more nodes to the cluster.

[Add two more nodes](https://docs.docker.com/engine/swarm/swarm-tutorial/add-nodes/)

----
url: https://docs.docker.com/reference/cli/docker/compose/build/
----

# docker compose build

***

| Description | Build or rebuild services                     |
| ----------- | --------------------------------------------- |
| Usage       | `docker compose build [OPTIONS] [SERVICE...]` |

## [Description](#description)

Services are built once and then tagged, by default as `project-service`.

If the Compose file specifies an [image](https://github.com/compose-spec/compose-spec/blob/main/spec.md#image) name, the image is tagged with that name, substituting any variables beforehand. See [variable interpolation](https://github.com/compose-spec/compose-spec/blob/main/spec.md#interpolation).

If you change a service's `Dockerfile` or the contents of its build directory, run `docker compose build` to rebuild it.

## [Options](#options)

| Option                | Default | Description                                                                                                  |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `--build-arg`         |         | Set build-time variables for services                                                                        |
| `--builder`           |         | Set builder to use                                                                                           |
| `--check`             |         | Check build configuration                                                                                    |
| `-m, --memory`        |         | Set memory limit for the build container. Not supported by BuildKit.                                         |
| `--no-cache`          |         | Do not use cache when building the image                                                                     |
| `--print`             |         | Print equivalent bake file                                                                                   |
| `--provenance`        |         | Add a provenance attestation                                                                                 |
| `--pull`              |         | Always attempt to pull a newer version of the image                                                          |
| `--push`              |         | Push service images                                                                                          |
| `-q, --quiet`         |         | Suppress the build output                                                                                    |
| `--sbom`              |         | Add a SBOM attestation                                                                                       |
| `--ssh`               |         | Set SSH authentications used when building service images. (use 'default' for using your default SSH Agent)  |
| `--with-dependencies` |         | Also build dependencies (transitively)                                                                       |

----
url: https://docs.docker.com/engine/security/trust/trust_automation/
----

# Automation with content trust

***

Table of contents

***

It is very common for Docker Content Trust to be built into existing automation systems. To allow tools to wrap Docker and push trusted content, there are environment variables that can be passed through to the client.

This guide follows the steps as described in [Signing images with Docker Content Trust](https://docs.docker.com/engine/security/trust/#signing-images-with-docker-content-trust). Make sure you understand and follow the prerequisites.

When working directly with the Notary client, it uses its [own set of environment variables](https://github.com/theupdateframework/notary/blob/master/docs/reference/client-config.md#environment-variables-optional).

## [Add a delegation private key](#add-a-delegation-private-key)

To automate importing a delegation private key to the local Docker trust store, we need to pass a passphrase for the new key. This passphrase will be required every time that delegation signs a tag.

```console
$ export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="mypassphrase123"

$ docker trust key load delegation.key --name jeff
Loading key from "delegation.key"...
Successfully imported key from delegation.key
```

## [Add a delegation public key](#add-a-delegation-public-key)

If you initialize a repository at the same time as adding a delegation public key, then you will need to use the local Notary Canonical Root Key's passphrase to create the repositories trust data. If the repository has already been initiated then you only need the repositories passphrase.

```console
# Export the Local Root Key Passphrase if required.
$ export DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE="rootpassphrase123"

# Export the Repository Passphrase
$ export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="repopassphrase123"

# Initialize Repo and Push Delegation
$ docker trust signer add --key delegation.crt jeff registry.example.com/admin/demo
Adding signer "jeff" to registry.example.com/admin/demo...
Initializing signed repository for registry.example.com/admin/demo...
Successfully initialized "registry.example.com/admin/demo"
Successfully added signer: registry.example.com/admin/demo
```

## [Sign an image](#sign-an-image)

Finally when signing an image, we will need to export the passphrase of the signing key. This was created when the key was loaded into the local Docker trust store with `$ docker trust key load`.

```console
$ export DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="mypassphrase123"

$ docker trust sign registry.example.com/admin/demo:1
Signing and pushing trust data for local image registry.example.com/admin/demo:1, may overwrite remote trust data
The push refers to repository [registry.example.com/admin/demo]
428c97da766c: Layer already exists
2: digest: sha256:1a6fd470b9ce10849be79e99529a88371dff60c60aab424c077007f6979b4812 size: 524
Signing and pushing trust metadata
Successfully signed registry.example.com/admin/demo:1
```

## [Build with content trust](#build-with-content-trust)

You can also build with content trust. Before running the `docker build` command, you should set the environment variable `DOCKER_CONTENT_TRUST` either manually or in a scripted fashion. Consider the simple Dockerfile below.

```dockerfile
# syntax=docker/dockerfile:1
FROM docker/trusttest:latest
RUN echo
```

The `FROM` tag is pulling a signed image. You cannot build an image that has a `FROM` that is not either present locally or signed. Given that content trust data exists for the tag `latest`, the following build should succeed:

```console
$  docker build -t docker/trusttest:testing .
Using default tag: latest
latest: Pulling from docker/trusttest

b3dbab3810fc: Pull complete
a9539b34a6ab: Pull complete
Digest: sha256:d149ab53f871
```

If content trust is enabled, building from a Dockerfile that relies on tag without trust data, causes the build command to fail:

```console
$  docker build -t docker/trusttest:testing .
unable to process Dockerfile: No trust data for notrust
```

## [Related information](#related-information)

* [Delegations for content trust](https://docs.docker.com/engine/security/trust/trust_delegation/)
* [Content trust in Docker](https://docs.docker.com/engine/security/trust/)
* [Manage keys for content trust](https://docs.docker.com/engine/security/trust/trust_key_mng/)
* [Play in a content trust sandbox](https://docs.docker.com/engine/security/trust/trust_sandbox/)

----
url: https://docs.docker.com/reference/cli/docker/scout/version/
----

# docker scout version

***

| Description | Show Docker Scout version information |
| ----------- | ------------------------------------- |
| Usage       | `docker scout version`                |

## [Description](#description)

Show Docker Scout version information

## [Examples](#examples)

```console
$ docker scout version

      ⢀⢀⢀             ⣀⣀⡤⣔⢖⣖⢽⢝
   ⡠⡢⡣⡣⡣⡣⡣⡣⡢⡀    ⢀⣠⢴⡲⣫⡺⣜⢞⢮⡳⡵⡹⡅
  ⡜⡜⡜⡜⡜⡜⠜⠈⠈        ⠁⠙⠮⣺⡪⡯⣺⡪⡯⣺
 ⢘⢜⢜⢜⢜⠜               ⠈⠪⡳⡵⣹⡪⠇
 ⠨⡪⡪⡪⠂    ⢀⡤⣖⢽⡹⣝⡝⣖⢤⡀    ⠘⢝⢮⡚       _____                 _
  ⠱⡱⠁    ⡴⡫⣞⢮⡳⣝⢮⡺⣪⡳⣝⢦    ⠘⡵⠁      / ____| Docker        | |
   ⠁    ⣸⢝⣕⢗⡵⣝⢮⡳⣝⢮⡺⣪⡳⣣    ⠁      | (___   ___ ___  _   _| |_
        ⣗⣝⢮⡳⣝⢮⡳⣝⢮⡳⣝⢮⢮⡳            \___ \ / __/ _ \| | | | __|
   ⢀    ⢱⡳⡵⣹⡪⡳⣝⢮⡳⣝⢮⡳⡣⡏    ⡀       ____) | (_| (_) | |_| | |_
  ⢀⢾⠄    ⠫⣞⢮⡺⣝⢮⡳⣝⢮⡳⣝⠝    ⢠⢣⢂     |_____/ \___\___/ \__,_|\__|
  ⡼⣕⢗⡄    ⠈⠓⠝⢮⡳⣝⠮⠳⠙     ⢠⢢⢣⢣
 ⢰⡫⡮⡳⣝⢦⡀              ⢀⢔⢕⢕⢕⢕⠅
 ⡯⣎⢯⡺⣪⡳⣝⢖⣄⣀        ⡀⡠⡢⡣⡣⡣⡣⡣⡃
⢸⢝⢮⡳⣝⢮⡺⣪⡳⠕⠗⠉⠁    ⠘⠜⡜⡜⡜⡜⡜⡜⠜⠈
⡯⡳⠳⠝⠊⠓⠉             ⠈⠈⠈⠈



version: v1.0.9 (go1.21.3 - darwin/arm64)
git commit: 8bf95bf60d084af341f70e8263342f71b0a3cd16
```

----
url: https://docs.docker.com/reference/
----

# Reference documentation

***

***

This section includes the reference documentation for the Docker platform's various APIs, CLIs, drivers and specifications, and file formats.

## [File formats](#file-formats)

### [Dockerfile](/reference/dockerfile/)

[Defines the contents and startup behavior of a single container.](/reference/dockerfile/)

### [Compose file](/reference/compose-file/)

[Defines a multi-container application.](/reference/compose-file/)

## [Command-line interfaces (CLIs)](#command-line-interfaces-clis)

### [Docker CLI](/reference/cli/docker/)

[The main Docker CLI, includes all `docker` commands.](/reference/cli/docker/)

### [Compose CLI](/reference/cli/docker/compose/)

[The CLI for Docker Compose, for building and running multi-container applications.](/reference/cli/docker/compose/)

### [Daemon CLI (dockerd)](/reference/cli/dockerd/)

[Persistent process that manages containers.](/reference/cli/dockerd/)

## [Application programming interfaces (APIs)](#application-programming-interfaces-apis)

### [Engine API](/reference/api/engine/)

[The main API for Docker, provides programmatic access to a daemon.](/reference/api/engine/)

### [Docker Hub API](/reference/api/hub/latest/)

[API to interact with Docker Hub.](/reference/api/hub/latest/)

### [DVP Data API](/reference/api/dvp/latest/)

[API for Docker Verified Publishers to fetch analytics data.](/reference/api/dvp/latest/)

### [Registry API](/reference/api/registry/latest/)

[API for Docker Registry.](/reference/api/registry/latest/)

----
url: https://docs.docker.com/build/building/base-images/
----

# Base images

***

Table of contents

***

All Dockerfiles start from a base image. A base is the image that your image extends. It refers to the contents of the `FROM` instruction in the Dockerfile.

```dockerfile
FROM debian
```

For most cases, you don't need to create your own base image. Docker Hub contains a vast library of Docker images that are suitable for use as a base image in your build. [Docker Official Images](https://docs.docker.com/docker-hub/image-library/trusted-content/#docker-official-images) have clear documentation, promote best practices, and are regularly updated. There are also [Docker Verified Publisher](https://docs.docker.com/docker-hub/image-library/trusted-content/#verified-publisher-images) images, created by trusted publishing partners, verified by Docker.

## [Create a base image](#create-a-base-image)

If you need to completely control the contents of your image, you can create your own base image from a Linux distribution of your choosing, or use the special `FROM scratch` base:

```dockerfile
FROM scratch
```

The `scratch` image is typically used to create minimal images containing only just what an application needs. See [Create a minimal base image using scratch](#create-a-minimal-base-image-using-scratch).

To create a distribution base image, you can use a root filesystem, packaged as a `tar` file, and import it to Docker with `docker import`. The process for creating your own base image depends on the Linux distribution you want to package. See [Create a full image using tar](#create-a-full-image-using-tar).

## [Create a minimal base image using scratch](#create-a-minimal-base-image-using-scratch)

The reserved, minimal `scratch` image serves as a starting point for building containers. Using the `scratch` image signals to the build process that you want the next command in the `Dockerfile` to be the first filesystem layer in your image.

While `scratch` appears in Docker's [repository on Docker Hub](https://hub.docker.com/_/scratch), you can't pull it, run it, or tag any image with the name `scratch`. Instead, you can refer to it in your `Dockerfile`. For example, to create a minimal container using `scratch`:

```dockerfile
# syntax=docker/dockerfile:1
FROM scratch
ADD hello /
CMD ["/hello"]
```

Assuming an executable binary named `hello` exists at the root of the [build context](https://docs.docker.com/build/concepts/context/). You can build this Docker image using the following `docker build` command:

```console
$ docker build --tag hello .
```

To run your new image, use the `docker run` command:

```console
$ docker run --rm hello
```

This example image can only be successfully executed as long as the `hello` binary doesn't have any runtime dependencies. Computer programs tend to depend on certain other programs or resources to exist in the runtime environment. For example:

* Programming language runtimes
* Dynamically linked C libraries
* CA certificates

When building a base image, or any image, this is an important aspect to consider. And this is why creating a base image using `FROM scratch` can be difficult, for anything other than small, simple programs. On the other hand, it's also important to include only the things you need in your image, to reduce the image size and attack surface.

## [Create a full image using tar](#create-a-full-image-using-tar)

In general, start with a working machine that is running the distribution you'd like to package as a base image, though that is not required for some tools like Debian's [Debootstrap](https://wiki.debian.org/Debootstrap), which you can also use to build Ubuntu images.

For example, to create an Ubuntu base image:

```dockerfile
$ sudo debootstrap noble noble > /dev/null
$ sudo tar -C noble -c . | docker import - noble

sha256:81ec9a55a92a5618161f68ae691d092bf14d700129093158297b3d01593f4ee3

$ docker run noble cat /etc/lsb-release

DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=24.04
DISTRIB_CODENAME=noble
DISTRIB_DESCRIPTION="Ubuntu 24.04.2 LTS"
```

There are more example scripts for creating base images in [the Moby GitHub repository](https://github.com/moby/moby/blob/master/contrib).

## [More resources](#more-resources)

For more information about building images and writing Dockerfiles, see:

* [Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
* [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)
* [Docker Official Images](https://docs.docker.com/docker-hub/image-library/trusted-content/#docker-official-images)

----
url: https://docs.docker.com/guides/testcontainers-java-jooq-flyway/
----

# Working with jOOQ and Flyway using Testcontainers

Table of contents

***

Generate typesafe jOOQ code from a real PostgreSQL database managed by Flyway migrations, then test repositories using Testcontainers.

**Time to complete** 25 minutes

In this guide, you will learn how to:

* Create a Spring Boot application with jOOQ support
* Generate jOOQ code using Testcontainers, Flyway, and a Maven plugin
* Implement basic database operations using jOOQ
* Load complex object graphs using jOOQ's MULTISET feature
* Test the jOOQ persistence layer using Testcontainers

## [Prerequisites](#prerequisites)

* Java 17+
* Maven
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-jooq-flyway/create-project/)

   Set up a Spring Boot project with jOOQ, Flyway, PostgreSQL, and Testcontainers code generation.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-jooq-flyway/write-tests/)

   Test jOOQ repositories using Testcontainers with the @JooqTest slice and @SpringBootTest.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-jooq-flyway/run-tests/)

   Run the jOOQ and Flyway integration tests and explore next steps.

----
url: https://docs.docker.com/reference/cli/sbx/completion/powershell/
----

# sbx completion powershell

| Description | Generate the autocompletion script for powershell |
| ----------- | ------------------------------------------------- |
| Usage       | `sbx completion powershell [flags]`               |

## [Description](#description)

Generate the autocompletion script for powershell.

To load completions in your current shell session:

```
sbx completion powershell | Out-String | Invoke-Expression
```

To load completions for every new session, add the output of the above command to your powershell profile.

## [Options](#options)

| Option              | Default | Description                     |
| ------------------- | ------- | ------------------------------- |
| `--no-descriptions` |         | disable completion descriptions |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/build/policies/intro/
----

# Introduction to build policies

***

Table of contents

***

Build policies let you validate the inputs to your Docker builds before they run. This tutorial walks you through creating your first policy, teaching the Rego basics you need along the way.

## [What you'll learn](#what-youll-learn)

By the end of this tutorial, you'll understand:

* How to create and organize policy files
* Basic Rego syntax and patterns
* How to write policies that validate URLs, checksums, and images
* How policies evaluate during builds

## [Prerequisites](#prerequisites)

* Buildx version 0.31 or later
* Basic familiarity with Dockerfiles and building images

## [How policies work](#how-policies-work)

When you build an image, Buildx resolves all the inputs your Dockerfile references: base images from `FROM` instructions, files from `ADD` or `COPY` or build contexts, and Git repositories. Before running the build, Buildx evaluates your policies against these inputs. If any input violates a policy, the build fails before any instructions execute.

Policies are written in Rego, a declarative language designed for expressing rules and constraints. You don't need to know Rego to get started - this tutorial teaches you what you need.

## [Create your first policy](#create-your-first-policy)

Create a new directory for this tutorial and add a Dockerfile:

```console
$ mkdir policy-tutorial
$ cd policy-tutorial
```

Create a `Dockerfile` that downloads a file with `ADD`:

```dockerfile
FROM scratch
ADD https://example.com/index.html /index.html
```

Now create a policy file. Policies use the `.rego` extension and live alongside your Dockerfile. Create `Dockerfile.rego`:

Dockerfile.rego

```rego
package docker

default allow := false

allow if input.local
allow if {
  input.http.host == "example.com"
}

decision := {"allow": allow}
```

Save this file as `Dockerfile.rego` in the same directory as your Dockerfile.

Let's break down what this policy does:

* `package docker` - All build policies must start with this package declaration
* `default allow := false` - This example uses a deny-by-default rule: if inputs do not match an `allow` rule, the policy check fails
* `allow if input.local` - The first rule allows any local files (your build context)
* `allow if { input.http.host == "example.com" }` - The second rule allows HTTP downloads from `example.com`
* `decision := {"allow": allow}` - The final decision object tells Buildx whether to allow or deny the input

This policy says: "Only allow local files and HTTP downloads from `example.com`". Rego evaluates all the policy rules to figure out the return value for the `decision` variable, for each build input. The evaluations happen in parallel and on-demand; the order of the policy rules has no significance.

### [About `input.local`](#about-inputlocal)

You'll see `allow if input.local` in nearly every policy. This rule allows local file access, which includes your build context (typically, the `.` directory) and importantly, the Dockerfile itself. Without this rule, Buildx can't read your Dockerfile to start the build.

Even builds that don't reference any files from the build context often need `input.local` because the Dockerfile is a local file. The policy evaluates before the build starts, and denying local access means denying access to the Dockerfile.

In rare cases, you might want stricter local file policies - for example, in CI builds where the build context uses a Git URL as a context directly. In these cases, you may want to deny local sources to prevent untracked files or changes from making their way into your build.

## [Automatic policy loading](#automatic-policy-loading)

Buildx automatically loads policies that match your Dockerfile name. When you build with `Dockerfile`, Buildx looks for `Dockerfile.rego` in the same directory. For a file named `app.Dockerfile`, it looks for `app.Dockerfile.rego`.

This automatic loading means you don't need any command-line flags in most cases - create the policy file and build.

The policy file must be in the same directory as the Dockerfile. If Buildx can't find a matching policy, the build proceeds without policy evaluation (unless you use `--policy strict=true`).

For more control over policy loading, see the [Usage guide](https://docs.docker.com/build/policies/usage/).

## [Run a build with your policy](#run-a-build-with-your-policy)

Build the image with policy evaluation enabled:

```console
$ docker build .
```

The build succeeds because the URL in your Dockerfile matches the policy. Now try changing the URL in your Dockerfile to something else:

```dockerfile
FROM scratch
ADD https://api.github.com/users/octocat /user.json
```

Build again:

```console
$ docker build .
```

This time the build fails with a policy violation. The `api.github.com` hostname doesn't match the rule in your policy, so Buildx rejects it before running any build steps.

## [Debugging policy failures](#debugging-policy-failures)

If your build fails with a policy violation, use `--progress=plain` to see exactly what went wrong:

```console
$ docker buildx build --progress=plain .
```

This shows all policy checks, the input data for each source, and allow/deny decisions. For complete debugging guidance, see [Debugging](https://docs.docker.com/build/policies/debugging/).

## [Add helpful error messages](#add-helpful-error-messages)

When a policy denies an input, users see a generic error message. You can provide custom messages that explain why the build was denied:

Dockerfile.rego

```rego
package docker

default allow := false

allow if input.local
allow if {
  input.http.host == "example.com"
  input.http.schema == "https"
}

deny_msg contains msg if {
  not allow
  input.http
  msg := "only HTTPS downloads from example.com are allowed"
}

decision := {"allow": allow, "deny_msg": deny_msg}
```

Now when a build is denied, users see your custom message explaining what went wrong:

```console
$ docker buildx build .
Policy: only HTTPS downloads from example.com are allowed
ERROR: failed to build: ... source not allowed by policy
```

The `deny_msg` rule uses `contains` to add messages to a set. You can add multiple deny messages for different failure conditions to help users understand exactly what needs to change.

## [Understand Rego rules](#understand-rego-rules)

Rego policies are built from rules. A rule defines when something is allowed. The basic pattern is:

```rego
allow if {
    condition_one
    condition_two
    condition_three
}
```

All conditions must be true for the rule to match. Think of it as an AND operation - the URL must match AND the checksum must match AND any other conditions you specify.

You can have multiple `allow` rules in one policy. If any rule matches, the input is allowed:

```rego
# Allow downloads from example.com
allow if {
    input.http.host == "example.com"
}

# Also allow downloads from api.github.com
allow if {
    input.http.host == "api.github.com"
}
```

This works like OR - the input can match the first rule OR the second rule.

## [Access input fields](#access-input-fields)

The `input` object gives you access to information about build inputs. The structure depends on the input type:

* `input.http` - Files downloaded with `ADD https://...`
* `input.image` - Container images from `FROM` or `COPY --from`
* `input.git` - Git repositories from `ADD git://...` or build context
* `input.local` - Local file context

Refer to the [Input reference](https://docs.docker.com/build/policies/inputs/) for all available input fields.

For HTTP downloads, you can access:

| Key                 | Description                        | Example                          |
| ------------------- | ---------------------------------- | -------------------------------- |
| `input.http.url`    | The full URL                       | `https://example.com/index.html` |
| `input.http.schema` | The protocol (HTTP/HTTPS)          | `https`                          |
| `input.http.host`   | The hostname                       | `example.com`                    |
| `input.http.path`   | The URL path, including parameters | `/index.html`                    |

Update your policy to require HTTPS:

```rego
package docker

default allow := false

allow if {
    input.http.host == "example.com"
    input.http.schema == "https"
}

decision := {"allow": allow}
```

Now the policy requires both the hostname to be `example.com` and the protocol to be HTTPS. HTTP URLs (without TLS) would fail the policy check.

## [Pattern matching and strings](#pattern-matching-and-strings)

Rego provides [built-in functions](https://www.openpolicyagent.org/docs/policy-language#built-in-functions) for pattern matching. Use `startswith()` to match URL prefixes:

```rego
allow if {
    startswith(input.http.url, "https://example.com/")
}
```

This allows any URL that starts with `https://example.com/`.

Use `regex.match()` for complex patterns:

```rego
allow if {
    regex.match(`^https://example\.com/.+\.json$`, input.http.url)
}
```

This matches URLs that:

* Start with `https://example.com/`
* End with `.json`
* Have at least one character between the domain and extension

## [Policy file location](#policy-file-location)

Policy files live adjacent to the Dockerfile they validate, using the naming pattern `<dockerfile-name>.rego`:

```text
project/
├── Dockerfile           # Main Dockerfile
├── Dockerfile.rego      # Policy for Dockerfile
├── lint.Dockerfile      # Linting Dockerfile
└── lint.Dockerfile.rego # Policy for lint.Dockerfile
```

When you build, Buildx automatically loads the corresponding policy file:

```console
$ docker buildx build -f Dockerfile .        # Loads Dockerfile.rego
$ docker buildx build -f lint.Dockerfile .   # Loads lint.Dockerfile.rego
```

## [Next steps](#next-steps)

You now understand how to write basic build policies for HTTP resources. To continue learning:

* Apply and test policies: [Using build policies](https://docs.docker.com/build/policies/usage/)
* Learn [Image validation](https://docs.docker.com/build/policies/validate-images/) to validate container images from `FROM` instructions
* Learn [Git validation](https://docs.docker.com/build/policies/validate-git/) to validate Git repositories used in builds
* See [Example policies](https://docs.docker.com/build/policies/examples/) for copy-paste-ready policies covering common scenarios
* Write unit tests for your policies: [Test build policies](https://docs.docker.com/build/policies/testing/)
* Debug policy failures: [Debugging](https://docs.docker.com/build/policies/debugging/)
* Read the [Input reference](https://docs.docker.com/build/policies/inputs/) for all available input fields
* Check the [Built-in functions](https://docs.docker.com/build/policies/built-ins/) for signature verification, attestations, and other security checks

----
url: https://docs.docker.com/guides/ruby/deploy/
----

# Test your Ruby on Rails deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Containerize a Ruby on Rails application](https://docs.docker.com/guides/ruby/containerize/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This lets you to test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your `docker-ruby-on-rails` directory, create a file named `docker-ruby-on-rails-kubernetes.yaml`. Open the file in an IDE or text editor and add the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the name of the repository that you created in [Configure CI/CD for your Ruby on Rails application](https://docs.docker.com/guides/ruby/configure-github-actions/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-ruby-on-rails-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: ruby-on-rails
  template:
    metadata:
      labels:
        service: ruby-on-rails
    spec:
      containers:
        - name: ruby-on-rails-container
          image: DOCKER_USERNAME/REPO_NAME
          imagePullPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: docker-ruby-on-rails-demo
  namespace: default
spec:
  type: NodePort
  selector:
    service: ruby-on-rails
  ports:
    - port: 3000
      targetPort: 3000
      nodePort: 30001
```

In this Kubernetes YAML file, there are two objects, separated by the `---`:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your Ruby on Rails application](https://docs.docker.com/guides/ruby/configure-github-actions/).
* A NodePort service, which will route traffic from port 30001 on your host to port 8001 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to `docker-ruby-on-rails` and deploy your application to Kubernetes.

   ```console
   $ kubectl apply -f docker-ruby-on-rails-kubernetes.yaml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```shell
   deployment.apps/docker-ruby-on-rails-demo created
   service/docker-ruby-on-rails-demo created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```shell
   NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
   docker-ruby-on-rails-demo  1/1     1            1           15s
   ```

   This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```shell
   NAME                        TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
   kubernetes                  ClusterIP   10.96.0.1       <none>        443/TCP          23h
   docker-ruby-on-rails-demo   NodePort    10.99.128.230   <none>        3000:30001/TCP   75s
   ```

   In addition to the default `kubernetes` service, you can see your `docker-ruby-on-rails-demo` service, accepting traffic on port 30001/TCP.

3. To create and migrate the database in a Ruby on Rails application running on Kubernetes, you need to follow these steps.

   **Get the Current Pods**: First, you need to identify the pods running in your Kubernetes cluster. Execute the following command to list the current pods in the `default` namespace:

   ```sh
   # Get the current pods in the cluster in the namespace default
   $ kubectl get pods
   ```

   This command will display a list of all pods in the `default` namespace. Look for the pod with the prefix `docker-ruby-on-rails-demo-`. Here is an example output:

   ```console
   NAME                                         READY   STATUS    RESTARTS      AGE
   docker-ruby-on-rails-demo-7cbddb5d6f-qh44l   1/1     Running   2 (22h ago)   9d
   ```

   **Execute the Migration Command**: Once you've identified the correct pod, use the `kubectl exec` command to run the database migration inside the pod.

   ```sh
   $ kubectl exec -it docker-ruby-on-rails-demo-7cbddb5d6f-qh44l -- rails db:migrate RAILS_ENV=development
   ```

   This command opens an interactive terminal session (`-it`) in the specified pod and runs the `rails db:migrate` command with the environment set to development (`RAILS_ENV=development`).

   By following these steps, you ensure that your database is properly migrated within the Ruby on Rails application running in your Kubernetes cluster. This process helps maintain the integrity and consistency of your application's data structure during deployment and updates.

4. Open the browser and go to <http://localhost:30001>, you should see the ruby on rails application working.

5. Run the following command to tear down your application.

   ```console
   $ kubectl delete -f docker-ruby-on-rails-kubernetes.yaml
   ```

----
url: https://docs.docker.com/scout/how-tos/create-exceptions-vex/
----

# Create an exception using the VEX

***

Table of contents

***

Vulnerability Exploitability eXchange (VEX) is a standard format for documenting vulnerabilities in the context of a software package or product. Docker Scout supports VEX documents to create [exceptions](https://docs.docker.com/scout/explore/exceptions/) for vulnerabilities in images.

> Note
>
> You can also create exceptions using the Docker Scout Dashboard or Docker Desktop. The GUI provides a user-friendly interface for creating exceptions, and it's easy to manage exceptions for multiple images. It also lets you create exceptions for multiple images, or your entire organization, all at once. For more information, see [Create an exception using the GUI](https://docs.docker.com/scout/how-tos/create-exceptions-gui/).

## [Prerequisites](#prerequisites)

To create exceptions using OpenVEX documents, you need:

* The latest version of Docker Desktop or the Docker Scout CLI plugin
* The [`vexctl`](https://github.com/openvex/vexctl) command line tool.
* The [containerd image store](https://docs.docker.com/desktop/features/containerd/) must be enabled
* Write permissions to the registry repository where the image is stored

## [Introduction to VEX](#introduction-to-vex)

The VEX standard is defined by a working group by the United States Cybersecurity and Infrastructure Security Agency (CISA). At the core of VEX are exploitability assessments. These assessments describe the status of a given CVE for a product. The possible vulnerability statuses in VEX are:

* Not affected: No remediation is required regarding this vulnerability.
* Affected: Actions are recommended to remediate or address this vulnerability.
* Fixed: These product versions contain a fix for the vulnerability.
* Under investigation: It is not yet known whether these product versions are affected by the vulnerability. An update will be provided in a later release.

There are multiple implementations and formats of VEX. Docker Scout supports the [OpenVex](https://github.com/openvex/spec) implementation. Regardless of the specific implementation, the core idea is the same: to provide a framework for describing the impact of vulnerabilities. Key components of VEX regardless of implementation includes:

* VEX document

  A type of security advisory for storing VEX statements. The format of the document depends on the specific implementation.

* VEX statement

  Describes the status of a vulnerability in a product, whether it's exploitable, and whether there are ways to remediate the issue.

* Justification and impact

  Depending on the vulnerability status, statements include a justification or impact statement describing why a product is or isn't affected.

* Action statements

  Describe how to remediate or mitigate the vulnerability.

## [`vexctl` example](#vexctl-example)

The following example command creates a VEX document stating that:

* The software product described by this VEX document is the Docker image `example/app:v1`
* The image contains the npm package `express@4.17.1`
* The npm package is affected by a known vulnerability: `CVE-2022-24999`
* The image is unaffected by the CVE, because the vulnerable code is never executed in containers that run this image

```console
$ vexctl create \
  --author="author@example.com" \
  --product="pkg:docker/example/app@v1" \
  --subcomponents="pkg:npm/express@4.17.1" \
  --vuln="CVE-2022-24999" \
  --status="not_affected" \
  --justification="vulnerable_code_not_in_execute_path" \
  --file="CVE-2022-24999.vex.json"
```

Here's a description of the options in this example:

* `--author`

  The email of the author of the VEX document.

* `--product`

  Package URL (PURL) of the Docker image. A PURL is an identifier for the image in a standardized format, defined in the PURL [specification](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#docker).

  Docker image PURL strings begin with a `pkg:docker` type prefix, followed by the image repository and version (the image tag or SHA256 digest). Unlike image tags, where the version is specified like `example/app:v1`, in PURL the image repository and version are separated by an `@`.

* `--subcomponents`

  PURL of the vulnerable package in the image. In this example, the vulnerability exists in an npm package, so the `--subcomponents` PURL is the identifier for the npm package name and version (`pkg:npm/express@4.17.1`).

  If the same vulnerability exists in multiple packages, `vexctl` lets you specify the `--subcomponents` flag multiple times for a single `create` command.

  You can also omit `--subcomponents`, in which case the VEX statement applies to the entire image.

* `--vuln`

  ID of the CVE that the VEX statement addresses.

* `--status`

  This is the status label of the vulnerability. This describes the relationship between the software (`--product`) and the CVE (`--vuln`). The possible values for the status label in OpenVEX are:

  * `not_affected`
  * `affected`
  * `fixed`
  * `under_investigation`

  In this example, the VEX statement asserts that the Docker image is `not_affected` by the vulnerability. The `not_affected` status is the only status that results in CVE suppression, where the CVE is filtered out of the analysis results. The other statuses are useful for documentation purposes, but they do not work for creating exceptions. For more information about all the possible status labels, see [Status Labels](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#status-labels) in the OpenVEX specification.

* `--justification`

  Justifies the `not_affected` status label, informing why the product is not affected by the vulnerability. In this case, the justification given is `vulnerable_code_not_in_execute_path`, signalling that the vulnerability can't be executed as used by the product.

  In OpenVEX, status justifications can have one of the five possible values:

  * `component_not_present`
  * `vulnerable_code_not_present`
  * `vulnerable_code_not_in_execute_path`
  * `vulnerable_code_cannot_be_controlled_by_adversary`
  * `inline_mitigations_already_exist`

  For more information about these values and their definitions, see [Status Justifications](https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#status-justifications) in the OpenVEX specification.

* `--file`

  Filename of the VEX document output

## [Example JSON document](#example-json-document)

Here's the OpenVEX JSON generated by this command:

```json
{
  "@context": "https://openvex.dev/ns/v0.2.0",
  "@id": "https://openvex.dev/docs/public/vex-749f79b50f5f2f0f07747c2de9f1239b37c2bda663579f87a35e5f0fdfc13de5",
  "author": "author@example.com",
  "timestamp": "2024-05-27T13:20:22.395824+02:00",
  "version": 1,
  "statements": [
    {
      "vulnerability": {
        "name": "CVE-2022-24999"
      },
      "timestamp": "2024-05-27T13:20:22.395829+02:00",
      "products": [
        {
          "@id": "pkg:docker/example/app@v1",
          "subcomponents": [
            {
              "@id": "pkg:npm/express@4.17.1"
            }
          ]
        }
      ],
      "status": "not_affected",
      "justification": "vulnerable_code_not_in_execute_path"
    }
  ]
}
```

Understanding how VEX documents are supposed to be structured can be a bit of a mouthful. The [OpenVEX specification](https://github.com/openvex/spec) describes the format and all the possible properties of documents and statements. For the full details, refer to the specification to learn more about the available fields and how to create a well-formed OpenVEX document.

To learn more about the available flags and syntax of the `vexctl` CLI tool and how to install it, refer to the [`vexctl` GitHub repository](https://github.com/openvex/vexctl).

## [Verifying VEX documents](#verifying-vex-documents)

To test whether the VEX documents you create are well-formed and produce the expected results, use the `docker scout cves` command with the `--vex-location` flag to apply a VEX document to a local image analysis using the CLI.

The following command invokes a local image analysis that incorporates all VEX documents in the specified location, using the `--vex-location` flag. In this example, the CLI is instructed to look for VEX documents in the current working directory.

```console
$ docker scout cves IMAGE --vex-location .
```

The output of the `docker scout cves` command displays the results with any VEX statements found in under the `--vex-location` location factored into the results. For example, CVEs assigned a status of `not_affected` are filtered out from the results. If the output doesn't seem to take the VEX statements into account, that's an indication that the VEX documents might be invalid in some way.

Things to look out for include:

* The PURL of a Docker image must begin with `pkg:docker/` followed by the image name.
* In a Docker image PURL, the image name and version is separated by `@`. An image named `example/myapp:1.0` has the following PURL: `pkg:docker/example/myapp@1.0`.
* Remember to specify an `author` (it's a mandatory field in OpenVEX)
* The [OpenVEX specification](https://github.com/openvex/spec) describes how and when to use `justification`, `impact_statement`, and other fields in the VEX documents. Specifying these in an incorrect way results in an invalid document. Make sure your VEX documents comply with the OpenVEX specification.

## [Attach VEX documents to images](#attach-vex-documents-to-images)

When you've created a VEX document, you can attach it to your image in the following ways:

* Attach the document as an [attestation](#attestation)
* Embed the document in the [image filesystem](#image-filesystem)

You can't remove a VEX document from an image once it's been added. For documents attached as attestations, you can create a new VEX document and attach it to the image again. Doing so will overwrite the previous VEX document (but it won't remove the attestation). For images where the VEX document has been embedded in the image's filesystem, you need to rebuild the image to change the VEX document.

### [Attestation](#attestation)

To attach VEX documents as an attestation, you can use the `docker scout attestation add` CLI command. Using attestations is the recommended option for attaching exceptions to images when using VEX.

You can attach attestations to images that have already been pushed to a registry. You don't need to build or push the image again. Additionally, having the exceptions attached to the image as attestations means consumers can inspect the exceptions for an image, directly from the registry.

To attach an attestation to an image:

1. Build the image and push it to a registry.

   ```console
   $ docker build --provenance=true --sbom=true --tag IMAGE --push .
   ```

2. Attach the exception to the image as an attestation.

   ```console
   $ docker scout attestation add \
     --file <cve-id>.vex.json \
     --predicate-type https://openvex.dev/ns/v0.2.0 \
     IMAGE
   ```

   The options for this command are:

   * `--file`: the location and filename of the VEX document
   * `--predicate-type`: the in-toto `predicateType` for OpenVEX

### [Image filesystem](#image-filesystem)

Embedding VEX documents directly on the image filesystem is a good option if you know the exceptions ahead of time, before you build the image. And it's relatively easy; just `COPY` the VEX document to the image in your Dockerfile.

The downside with this approach is that you can't change or update the exception later. Image layers are immutable, so anything you put in the image's filesystem is there forever. Attaching the document as an [attestation](#attestation) provides better flexibility.

> Note
>
> VEX documents embedded in the image filesystem are not considered for images that have attestations. If your image has **any** attestations, Docker Scout will only look for exceptions in the attestations, and not in the image filesystem.
>
> If you want to use the VEX document embedded in the image filesystem, you must remove the attestation from the image. Note that provenance attestations may be added automatically for images. To ensure that no attestations are added to the image, you can explicitly disable both SBOM and provenance attestations using the `--provenance=false` and `--sbom=false` flags when building the image.

To embed a VEX document on the image filesystem, `COPY` the file into the image as part of the image build. The following example shows how to copy all VEX documents under `.vex/` in the build context, to `/var/lib/db` in the image.

```dockerfile
# syntax=docker/dockerfile:1

FROM alpine
COPY .vex/* /var/lib/db/
```

The filename of the VEX document must match the `*.vex.json` glob pattern. It doesn't matter where on the image's filesystem you store the file.

Note that the copied files must be part of the filesystem of the final image, For multi-stage builds, the documents must persist in the final stage.

----
url: https://docs.docker.com/guides/kube-deploy/
----

[Deploy to Kubernetes](https://docs.docker.com/guides/kube-deploy/)

Learn how to deploy and orchestrate Docker containers using Kubernetes.

Deployment

10 minutes

[« Back to all guides](/guides/)

# Deploy to Kubernetes

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Download and install Docker Desktop as described in [Get Docker](https://docs.docker.com/get-started/get-docker/).
* Work through containerizing an application in [Part 2](https://docs.docker.com/get-started/workshop/02_our_app/).
* Make sure that Kubernetes is turned on in Docker Desktop: If Kubernetes isn't running, follow the instructions in [Orchestration](https://docs.docker.com/guides/orchestration/) to finish setting it up.

## [Introduction](#introduction)

Now that you've demonstrated that the individual components of your application run as stand-alone containers, it's time to arrange for them to be managed by an orchestrator like Kubernetes. Kubernetes provides many tools for scaling, networking, securing and maintaining your containerized applications, above and beyond the abilities of containers themselves.

In order to validate that your containerized application works well on Kubernetes, you'll use Docker Desktop's built in Kubernetes environment right on your development machine to deploy your application, before handing it off to run on a full Kubernetes cluster in production. The Kubernetes environment created by Docker Desktop is *fully featured*, meaning it has all the Kubernetes features your app will enjoy on a real cluster, accessible from the convenience of your development machine.

## [Describing apps using Kubernetes YAML](#describing-apps-using-kubernetes-yaml)

All containers in Kubernetes are scheduled as pods, which are groups of co-located containers that share some resources. Furthermore, in a realistic application you almost never create individual pods. Instead, most of your workloads are scheduled as deployments, which are scalable groups of pods maintained automatically by Kubernetes. Lastly, all Kubernetes objects can and should be described in manifests called Kubernetes YAML files. These YAML files describe all the components and configurations of your Kubernetes app, and can be used to create and destroy your app in any Kubernetes environment.

You already wrote a basic Kubernetes YAML file in the Orchestration overview part of this tutorial. Now, you can write a slightly more sophisticated YAML file to run and manage your Todo app, the container `getting-started` image created in [Part 2](https://docs.docker.com/get-started/workshop/02_our_app/) of the Quickstart tutorial. Place the following in a file called `bb.yaml`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: bb-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      bb: web
  template:
    metadata:
      labels:
        bb: web
    spec:
      containers:
        - name: bb-site
          image: getting-started
          imagePullPolicy: Never
---
apiVersion: v1
kind: Service
metadata:
  name: bb-entrypoint
  namespace: default
spec:
  type: NodePort
  selector:
    bb: web
  ports:
    - port: 3000
      targetPort: 3000
      nodePort: 30001
```

In this Kubernetes YAML file, there are two objects, separated by the `---`:

* A `Deployment`, describing a scalable group of identical pods. In this case, you'll get just one `replica`, or copy of your pod, and that pod (which is described under the `template:` key) has just one container in it, based off of your `getting-started` image from the previous step in this tutorial.
* A `NodePort` service, which will route traffic from port 30001 on your host to port 3000 inside the pods it routes to, allowing you to reach your Todo app from the network.

Also, notice that while Kubernetes YAML can appear long and complicated at first, it almost always follows the same pattern:

* The `apiVersion`, which indicates the Kubernetes API that parses this object
* The `kind` indicating what sort of object this is
* Some `metadata` applying things like names to your objects
* The `spec` specifying all the parameters and configurations of your object.

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to where you created `bb.yaml` and deploy your application to Kubernetes:

   ```console
   $ kubectl apply -f bb.yaml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully:

   ```shell
   deployment.apps/bb-demo created
   service/bb-entrypoint created
   ```

2. Make sure everything worked by listing your deployments:

   ```console
   $ kubectl get deployments
   ```

   if all is well, your deployment should be listed as follows:

   ```shell
   NAME      READY   UP-TO-DATE   AVAILABLE   AGE
   bb-demo   1/1     1            1           40s
   ```

   This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services:

   ```console
   $ kubectl get services

   NAME            TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
   bb-entrypoint   NodePort    10.106.145.116   <none>        3000:30001/TCP   53s
   kubernetes      ClusterIP   10.96.0.1        <none>        443/TCP          138d
   ```

   In addition to the default `kubernetes` service, we see our `bb-entrypoint` service, accepting traffic on port 30001/TCP.

3. Open a browser and visit your Todo app at `localhost:30001`. You should see your Todo application, the same as when you ran it as a stand-alone container in [Part 2](https://docs.docker.com/get-started/workshop/02_our_app/) of the tutorial.

4. Once satisfied, tear down your application:

   ```console
   $ kubectl delete -f bb.yaml
   ```

## [Conclusion](#conclusion)

At this point, you have successfully used Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. You can now add other components to your app and taking advantage of all the features and power of Kubernetes, right on your own machine.

In addition to deploying to Kubernetes, you have also described your application as a Kubernetes YAML file. This simple text file contains everything you need to create your application in a running state. You can check it in to version control and share it with your colleagues. This let you distribute your applications to other clusters (like the testing and production clusters that probably come after your development environments).

## [Kubernetes references](#kubernetes-references)

Further documentation for all new Kubernetes objects used in this article are available here:

* [Kubernetes Pods](https://kubernetes.io/docs/concepts/workloads/pods/pod/)
* [Kubernetes Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
* [Kubernetes Services](https://kubernetes.io/docs/concepts/services-networking/service/)

----
url: https://docs.docker.com/engine/logging/drivers/splunk/
----

# Splunk logging driver

***

Table of contents

***

The `splunk` logging driver sends container logs to [HTTP Event Collector](https://dev.splunk.com/enterprise/docs/devtools/httpeventcollector/) in Splunk Enterprise and Splunk Cloud.

## [Usage](#usage)

You can configure Docker logging to use the `splunk` driver by default or on a per-container basis.

To use the `splunk` driver as the default logging driver, set the keys `log-driver` and `log-opts` to appropriate values in the `daemon.json` configuration file and restart Docker. For example:

```json
{
  "log-driver": "splunk",
  "log-opts": {
    "splunk-token": "",
    "splunk-url": "",
    ...
  }
}
```

For more about configuring Docker using `daemon.json`, see [daemon.json](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file).

> Note
>
> If you're using Docker Desktop, edit the daemon configuration through the Docker Desktop Dashboard. Open **Settings** and select **Docker Engine**. For details, see [Docker Engine settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine).

> Note
>
> `log-opts` configuration options in the `daemon.json` configuration file must be provided as strings. Boolean and numeric values (such as the value for `splunk-gzip` or `splunk-gzip-level`) must therefore be enclosed in quotes (`"`).

To use the `splunk` driver for a specific container, use the commandline flags `--log-driver` and `log-opt` with `docker run`:

```console
$ docker run --log-driver=splunk --log-opt splunk-token=VALUE --log-opt splunk-url=VALUE ...
```

## [Splunk options](#splunk-options)

The following properties let you configure the Splunk logging driver.

* To configure the `splunk` driver across the Docker environment, edit `daemon.json` with the key, `"log-opts": {"NAME": "VALUE", ...}`.
* To configure the `splunk` driver for an individual container, use `docker run` with the flag, `--log-opt NAME=VALUE ...`.

| Option                      | Required | Description                                                                                                                                                                                                                                                                                                                                |
| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `splunk-token`              | required | Splunk HTTP Event Collector token.                                                                                                                                                                                                                                                                                                         |
| `splunk-url`                | required | Path to your Splunk Enterprise, self-service Splunk Cloud instance, or Splunk Cloud managed cluster (including port and scheme used by HTTP Event Collector) in one of the following formats: `https://your_splunk_instance:8088`, `https://input-prd-p-XXXXXXX.cloud.splunk.com:8088`, or `https://http-inputs-XXXXXXXX.splunkcloud.com`. |
| `splunk-source`             | optional | Event source.                                                                                                                                                                                                                                                                                                                              |
| `splunk-sourcetype`         | optional | Event source type.                                                                                                                                                                                                                                                                                                                         |
| `splunk-index`              | optional | Event index.                                                                                                                                                                                                                                                                                                                               |
| `splunk-capath`             | optional | Path to root certificate.                                                                                                                                                                                                                                                                                                                  |
| `splunk-caname`             | optional | Name to use for validating server certificate; by default the hostname of the `splunk-url` is used.                                                                                                                                                                                                                                        |
| `splunk-insecureskipverify` | optional | Ignore server certificate validation.                                                                                                                                                                                                                                                                                                      |
| `splunk-format`             | optional | Message format. Can be `inline`, `json` or `raw`. Defaults to `inline`.                                                                                                                                                                                                                                                                    |
| `splunk-verify-connection`  | optional | Verify on start, that Docker can connect to Splunk server. Defaults to true.                                                                                                                                                                                                                                                               |
| `splunk-gzip`               | optional | Enable/disable gzip compression to send events to Splunk Enterprise or Splunk Cloud instance. Defaults to false.                                                                                                                                                                                                                           |
| `splunk-gzip-level`         | optional | Set compression level for gzip. Valid values are -1 (default), 0 (no compression), 1 (best speed) ... 9 (best compression). Defaults to [DefaultCompression](https://golang.org/pkg/compress/gzip/#DefaultCompression).                                                                                                                    |
| `tag`                       | optional | Specify tag for message, which interpret some markup. Default value is `{{.ID}}` (12 characters of the container ID). Refer to the [log tag option documentation](https://docs.docker.com/engine/logging/log_tags/) for customizing the log tag format.                                                                                    |
| `labels`                    | optional | Comma-separated list of keys of labels, which should be included in message, if these labels are specified for container.                                                                                                                                                                                                                  |
| `labels-regex`              | optional | Similar to and compatible with `labels`. A regular expression to match logging-related labels. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                                                                                                                                                      |
| `env`                       | optional | Comma-separated list of keys of environment variables, which should be included in message, if these variables are specified for container.                                                                                                                                                                                                |
| `env-regex`                 | optional | Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                                                                                                                                          |

If there is collision between the `label` and `env` keys, the value of the `env` takes precedence. Both options add additional fields to the attributes of a logging message.

Below is an example of the logging options specified for the Splunk Enterprise instance. The instance is installed locally on the same machine on which the Docker daemon is running.

The path to the root certificate and Common Name is specified using an HTTPS scheme. This is used for verification. The `SplunkServerDefaultCert` is automatically generated by Splunk certificates.

```console
$ docker run \
    --log-driver=splunk \
    --log-opt splunk-token=176FCEBF-4CF5-4EDF-91BC-703796522D20 \
    --log-opt splunk-url=https://splunkhost:8088 \
    --log-opt splunk-capath=/path/to/cert/cacert.pem \
    --log-opt splunk-caname=SplunkServerDefaultCert \
    --log-opt tag="{{.Name}}/{{.FullID}}" \
    --log-opt labels=location \
    --log-opt env=TEST \
    --env "TEST=false" \
    --label location=west \
    your/application
```

The `splunk-url` for Splunk instances hosted on Splunk Cloud is in a format like `https://http-inputs-XXXXXXXX.splunkcloud.com` and does not include a port specifier.

### [Message formats](#message-formats)

There are three logging driver messaging formats: `inline` (default), `json`, and `raw`.

The default format is `inline` where each log message is embedded as a string. For example:

```json
{
  "attrs": {
    "env1": "val1",
    "label1": "label1"
  },
  "tag": "MyImage/MyContainer",
  "source": "stdout",
  "line": "my message"
}
```

```json
{
  "attrs": {
    "env1": "val1",
    "label1": "label1"
  },
  "tag": "MyImage/MyContainer",
  "source": "stdout",
  "line": "{\"foo\": \"bar\"}"
}
```

To format messages as `json` objects, set `--log-opt splunk-format=json`. The driver attempts to parse every line as a JSON object and send it as an embedded object. If it can't parse the message, it's sent `inline`. For example:

```json
{
  "attrs": {
    "env1": "val1",
    "label1": "label1"
  },
  "tag": "MyImage/MyContainer",
  "source": "stdout",
  "line": "my message"
}
```

```json
{
  "attrs": {
    "env1": "val1",
    "label1": "label1"
  },
  "tag": "MyImage/MyContainer",
  "source": "stdout",
  "line": {
    "foo": "bar"
  }
}
```

To format messages as `raw`, set `--log-opt splunk-format=raw`. Attributes (environment variables and labels) and tags are prefixed to the message. For example:

```console
MyImage/MyContainer env1=val1 label1=label1 my message
MyImage/MyContainer env1=val1 label1=label1 {"foo": "bar"}
```

## [Advanced options](#advanced-options)

The Splunk logging driver lets you configure a few advanced options by setting environment variables for the Docker daemon.

| Environment variable name                        | Default value | Description                                                                                                                              |
| ------------------------------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `SPLUNK_LOGGING_DRIVER_POST_MESSAGES_FREQUENCY`  | `5s`          | The time to wait for more messages to batch.                                                                                             |
| `SPLUNK_LOGGING_DRIVER_POST_MESSAGES_BATCH_SIZE` | `1000`        | The number of messages that should accumulate before sending them in one batch.                                                          |
| `SPLUNK_LOGGING_DRIVER_BUFFER_MAX`               | `10 * 1000`   | The maximum number of messages held in buffer for retries.                                                                               |
| `SPLUNK_LOGGING_DRIVER_CHANNEL_SIZE`             | `4 * 1000`    | The maximum number of pending messages that can be in the channel used to send messages to background logger worker, which batches them. |

----
url: https://docs.docker.com/reference/cli/docker/scout/environment/
----

# docker scout environment

***

| Description                                                               | Manage environments (experimental)               |
| ------------------------------------------------------------------------- | ------------------------------------------------ |
| Usage                                                                     | `docker scout environment [ENVIRONMENT] [IMAGE]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker scout env`                               |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

The `docker scout environment` command lists the environments. If you pass an image reference, the image is recorded to the specified environment.

Once recorded, environments can be referred to by their name. For example, you can refer to the `production` environment with the `docker scout compare` command as follows:

```console
$ docker scout compare --to-env production
```

## [Options](#options)

| Option         | Default | Description                          |
| -------------- | ------- | ------------------------------------ |
| `--org`        |         | Namespace of the Docker organization |
| `-o, --output` |         | Write the report to a file           |
| `--platform`   |         | Platform of image to record          |

## [Examples](#examples)

### [List existing environments](#list-existing-environments)

```console
$ docker scout environment
prod
staging
```

### [List images of an environment](#list-images-of-an-environment)

```console
$ docker scout environment staging
namespace/repo:tag@sha256:9a4df4fadc9bbd44c345e473e0688c2066a6583d4741679494ba9228cfd93e1b
namespace/other-repo:tag@sha256:0001d6ce124855b0a158569c584162097fe0ca8d72519067c2c8e3ce407c580f
```

### [Record an image to an environment, for a specific platform](#record-an-image-to-an-environment-for-a-specific-platform)

```console
$ docker scout environment staging namespace/repo:stage-latest --platform linux/amd64
✓ Pulled
✓ Successfully recorded namespace/repo:stage-latest in environment staging
```

----
url: https://docs.docker.com/compose/install/standalone/
----

# Install the Docker Compose standalone (Legacy)

***

Table of contents

***

> Warning
>
> This install scenario is not recommended and is only supported for backward compatibility purposes. Use [Docker Desktop](https://docs.docker.com/desktop/) or the [Docker Compose plugin](https://docs.docker.com/compose/install/linux/) instead. Use the standalone binary only if you cannot use either of these options.

This page contains instructions on how to install Docker Compose standalone on Linux or Windows Server, from the command line.

> Warning
>
> The Docker Compose standalone uses the `-compose` syntax instead of the current standard syntax `compose`.\
> For example, you must type `docker-compose up` when using Docker Compose standalone, instead of `docker compose up`. Use it only for backward compatibility.

## [On Linux](#on-linux)

1. To download and install the Docker Compose standalone, run:

   ```console
   $ curl -SL https://github.com/docker/compose/releases/download/v5.1.2/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
   ```

2. Apply executable permissions to the standalone binary in the target path for the installation.

   ```console
   $ chmod +x /usr/local/bin/docker-compose
   ```

3. Test and execute Docker Compose commands using `docker-compose`.

> Tip
>
> If the command `docker-compose` fails after installation, check your path. You can also create a symbolic link to `/usr/bin` or any other directory in your path. For example:
>
> ```console
> $ sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
> ```

## [On Windows Server](#on-windows-server)

Follow these instructions if you are [running the Docker daemon directly on Microsoft Windows Server](https://docs.docker.com/engine/install/binaries/#install-server-and-client-binaries-on-windows) and want to install Docker Compose.

1. Run PowerShell as an administrator. In order to proceed with the installation, select **Yes** when asked if you want this app to make changes to your device.

2. Optional. Ensure TLS1.2 is enabled. GitHub requires TLS1.2 for secure connections. If you’re using an older version of Windows Server, for example 2016, or suspect that TLS1.2 is not enabled, run the following command in PowerShell:

   ```powershell
   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   ```

3. Download the latest release of Docker Compose (v5.1.2). Run the following command:

   ```powershell
    Start-BitsTransfer -Source "https://github.com/docker/compose/releases/download/v5.1.2/docker-compose-windows-x86_64.exe" -Destination $Env:ProgramFiles\Docker\docker-compose.exe
   ```

   To install a different version of Docker Compose, substitute `v5.1.2` with the version of Compose you want to use.

   > Note
   >
   > On Windows Server 2019 you can add the Compose executable to `$Env:ProgramFiles\Docker`. Because this directory is registered in the system `PATH`, you can run the `docker-compose --version` command on the subsequent step with no additional configuration.

4. Test the installation.

   ```console
   $ docker-compose.exe version
   Docker Compose version v5.1.2
   ```

## [What's next?](#whats-next)


----
url: https://docs.docker.com/ai/sandboxes/customize/kits/
----

# Kits

***

Table of contents

***

Availability: Early Access

> Note
>
> Kits are experimental. The kit file format, CLI commands, and experience for creating, loading, and managing kits are subject to change as the feature evolves. Share feedback and bug reports in the [docker/sbx-releases](https://github.com/docker/sbx-releases) repository.

A kit packages a set of capabilities a sandbox can use, such as:

* Tools to install
* Environment variables to set
* Credentials to inject
* Network rules to allow or deny domains
* Files to drop in
* Startup commands to run
* Memory instructions to give the agent

You declare these in a single `spec.yaml` file, point the CLI at the directory (or a ZIP, OCI artifact, or Git URL), and the sandbox applies and enforces them at runtime. Credentials stay on the host and go through a proxy instead of entering the VM, and outbound traffic is restricted to the domains permitted by the kit's network rules.

A kit is either a mixin or an agent:

* Mixin kits (`kind: mixin`) extend an existing agent with extra capabilities. Stack several on the same sandbox.
* Agent kits (`kind: agent`) define a full agent from scratch: its image, entrypoint, network policies, and everything else the agent needs.

## [What kits can do](#what-kits-can-do)

### [Run commands](#run-commands)

A kit can run commands inside the sandbox automatically. **Install commands** run once at creation; **startup commands** run each time the sandbox starts.

Install commands are the place to put anything an agent needs into the image, via `apt`, `pip`, `npm`, `curl | bash`, or whatever fits:

```yaml
commands:
  install:
    - command: "apt-get update && apt-get install -y jq"
```

Startup commands cover things like launching background services, warming caches, or refreshing config on each start. They must be idempotent — see the [`startup`](#startup) spec reference:

```yaml
commands:
  startup:
    - command: ["sh", "-c", "my-daemon &"]
```

### [Inject files](#inject-files)

Kits can inject files into the sandbox in two ways: **static files** bundled with the kit, and **`initFiles`** written at startup with runtime values substituted in.

Static files work well for content that doesn't vary between sandboxes, such as tool configurations, shared linter rules, helper scripts the agent can invoke, or reference material like a style guide or API cheatsheet.

```text
my-kit/
├── spec.yaml
└── files/
    ├── home/
    │   └── .config/my-tool/settings.json
    └── workspace/
        └── .editorconfig
```

`initFiles` cover content that depends on runtime values, such as an absolute workspace path that a tool needs to bake into its config file at startup:

```yaml
commands:
  initFiles:
    - path: /home/agent/.my-tool/config.json
      content: '{"workspace": "${WORKDIR}"}'
      onlyIfMissing: true
```

See [`initFiles`](#initfiles) in the spec reference for all fields.

Sandboxes seed settings files for some built-in agents during setup. For example, the sandbox writes `/home/agent/.claude/settings.json` for the `claude` agent. This happens after the kit's static files and `initFiles`, so kit-injected files at those paths get overwritten. Workspace files (such as `<workspace>/.claude/settings.local.json`) aren't affected, and you can ship them under `files/workspace/` as usual. To override a path the sandbox writes to, use a [`commands.startup`](#startup) script instead. See [Override agent settings](https://docs.docker.com/ai/sandboxes/customize/kit-examples/#override-agent-settings) for an example.

### [Set environment variables](#set-environment-variables)

Environment variables set by the kit are available to the agent at runtime:

```yaml
environment:
  variables:
    MY_TOOL_WORKSPACE: /home/agent/my-tool
```

For credentials, see [Authenticate to external services](#authenticate-to-external-services). Don't put secret values directly in `environment.variables` — they'd be visible inside the sandbox VM.

### [Control network access](#control-network-access)

Network rules define which domains the sandbox can reach or block. Kit network rules apply only to sandboxes that use the kit:

```yaml
network:
  allowedDomains:
    - api.example.com
    - "*.cdn.example.com"
  deniedDomains:
    - telemetry.example.com
```

Use `allowedDomains` for hosts the agent needs, such as package registries, install endpoints, or external APIs. Use `deniedDomains` for hosts the agent should not reach, such as telemetry endpoints. If a domain matches both an allow rule and a deny rule, the deny rule wins.

For authenticated services, see [Authenticate to external services](#authenticate-to-external-services).

### [Authenticate to external services](#authenticate-to-external-services)

A kit can attach credentials to outbound requests through the host-side proxy. The agent inside the VM works with a sentinel value; the proxy reads the real credential on the host and overwrites the auth header before the request leaves the sandbox.

The standard pattern uses four blocks tied to a service identifier you choose (here, `my-service`):

```yaml
network:
  allowedDomains:
    - api.example.com
  serviceDomains:
    api.example.com: my-service # Tag traffic to this domain
  serviceAuth:
    my-service:
      headerName: Authorization # Overwrite this header
      valueFormat: "Bearer %s"

credentials:
  sources:
    my-service:
      env:
        - MY_SERVICE_API_KEY # Host-side credential lookup

environment:
  proxyManaged:
    - MY_SERVICE_API_KEY # Set the in-VM env var to "proxy-managed"
```

The agent boots with `MY_SERVICE_API_KEY=proxy-managed`, sends a request with that value in `Authorization`, and the proxy overwrites the header with the real credential before forwarding. The real secret never enters the VM.

See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for how to provide the credential value on your host, other approaches for cases the example above doesn't fit, and what the proxy does at request time.

### [Inject agent memory](#inject-agent-memory)

A kit can append content to the agent's memory file, such as `CLAUDE.md` or `AGENTS.md`. The agent reads this file at startup. Use it to give the agent project conventions, usage tips for a tool the kit installs, or other guidance that should be in scope when the sandbox runs.

```yaml
memory: |
  Ruff is installed. Run `ruff check` before committing.
  Shared config lives at `/workspace/ruff.toml`.
```

Both mixin and agent kits can declare `memory:`. The content is written only when the active agent kit sets [`agent.aiFilename`](#agent-block), which determines the memory file's name.

When more than one loaded kit declares a `memory:` block, each kit's content is written to its own `<kit-name>.md` file under a sibling `kits-memory/` directory. The main memory file gets a `## Kits` section that points to each kit file:

```text
/Users/you/
├── myproject/         # workspace
├── AGENTS.md          # main memory file with a "## Kits" index
└── kits-memory/
    ├── ruff-lint.md
    ├── vale.md
    └── git-ssh-sign.md
```

See [`memory`](#memory) in the spec reference for the full field schema.

### [Define an agent](#define-an-agent)

Agent kits declare an `agent:` block with the image the agent runs in and the command the user attaches to when they launch the sandbox:

```yaml
agent:
  image: "my-registry/my-agent:latest"
  entrypoint:
    run: [my-agent, "--yolo"]
```

See [Agent kits](#agent-kits) for use cases and an example.

## [Mixin kits](#mixin-kits)

A mixin kit extends an existing agent with extra capabilities. Common use cases:

* Pre-install tools: linters, libraries, or other custom programs
* Grant the agent access to a new authenticated service (a database, a vendor API)
* Inject shared team config (linter rules, editor settings, dotfiles)

### [Example: Python linting kit](#example-python-linting-kit)

This kit installs [Ruff](https://docs.astral.sh/ruff/) and injects a shared configuration file, so every sandbox starts with the same linting setup.

```text
ruff-lint/
├── spec.yaml
└── files/
    └── workspace/
        └── ruff.toml
```

ruff-lint/spec.yaml

```yaml
schemaVersion: "1"
kind: mixin
name: ruff-lint
displayName: Ruff Linter
description: Python linting with shared team config

network:
  allowedDomains:
    - pypi.org
    - files.pythonhosted.org

commands:
  install:
    - command: "uv tool install ruff@latest"
      user: "1000"
      description: Install Ruff
```

ruff-lint/files/workspace/ruff.toml

```toml
line-length = 100

[lint]
select = ["E", "F", "I"]
```

> Tip
>
> The templates for the built-in agents (`claude`, `codex`, etc) already includes `uv`, so this mixin can use it without installing it separately.

To start a new sandbox with this mixin:

```console
$ sbx run claude --kit /path/to/ruff-lint/
```

To apply the mixin to a sandbox that's already running, use [`sbx kit add`](#local) instead. The `--kit` flag only takes effect when a sandbox is created.

## [Agent kits](#agent-kits)

An agent kit defines a full agent from scratch — image, entrypoint, and everything the agent needs. Common use cases:

* Package a custom agent you've built so others can run it
* Ship a team-internal agent with defaults baked in
* Run a fork of an existing agent with your own config
* Prototype a new agent integration

Agent kits declare everything a mixin kit can, plus an [`agent:` block](#agent-block) that tells the sandbox how to launch the agent. For a step-by-step walkthrough, see [Build your own agent kit](https://docs.docker.com/ai/sandboxes/customize/build-an-agent/).

### [Example: the built-in `claude` agent](#example-the-built-in-claude-agent)

The `claude` agent you get from `sbx run claude` is defined as a kit. Here is an abbreviated version of its spec, showing how the agent block combines with network, credentials, environment, and commands:

claude/spec.yaml

```yaml
schemaVersion: "1"
kind: agent
name: claude
agent:
  image: "docker/sandbox-templates:claude-code-docker"
  aiFilename: CLAUDE.md
  persistence: persistent
  entrypoint:
    run: [claude, "--dangerously-skip-permissions"]

network:
  serviceDomains:
    api.anthropic.com: anthropic
    console.anthropic.com: anthropic
  serviceAuth:
    anthropic:
      headerName: x-api-key
      valueFormat: "%s"
  allowedDomains:
    - "claude.com:443"

credentials:
  sources:
    anthropic:
      env:
        - ANTHROPIC_API_KEY

environment:
  variables:
    IS_SANDBOX: "1"

commands:
  install:
    - command: "curl -fsSL https://claude.ai/install.sh | bash"
      user: "1000"
      description: Install Claude Code
```

## [Using kits](#using-kits)

Kits can be loaded from a local path (a directory or ZIP file), a Git repository, or an OCI registry. Pass `--kit` more than once to stack several kits on the same sandbox.

> Important
>
> `--kit` only takes effect when a sandbox is created. Passing it against an existing sandbox name fails with `--kit can only be used when creating a new sandbox`. To extend a running sandbox with a kit, use [`sbx kit add`](#local) instead.

### [Local](#local)

Point `--kit` at a directory or ZIP file on disk:

```console
$ sbx run claude --kit ./my-kit/
$ sbx run claude --kit ./my-kit-1.0.zip
```

While iterating on a kit, apply changes to a running sandbox with `sbx kit add` instead of recreating it:

```console
$ sbx kit add my-sandbox ./my-kit/
```

`kit add` re-runs install commands and re-copies files. Kits can't be removed from a running sandbox — remove and recreate it to start clean.

### [Git repository](#git-repository)

```console
$ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#ref=v0.1.0&dir=code-server"
```

* `#ref=<branch|tag|commit>` pins to a specific revision. Defaults to the repository's default branch.
* `#dir=<path>` loads a kit from a subdirectory.
* `git+ssh://` URLs also work, using your local SSH agent, Git credential helpers, and `.netrc`.
* Quote the URL in shells where `&` starts a background job.

### [OCI registry](#oci-registry)

```console
$ sbx run claude --kit ghcr.io/myorg/my-kit:1.0
```

For Docker Hub, include the full `docker.io` prefix. See [Packaging and distribution](#packaging-and-distribution) for publishing.

> Important
>
> For Docker Hub, `sbx` reuses your `sbx login` session to pull private kits. For other registries, store pull credentials with [`sbx secret set --registry`](https://docs.docker.com/ai/sandboxes/security/credentials/#registry-credentials) before running the sandbox:
>
> ```console
> $ gh auth token | sbx secret set --registry ghcr.io --password-stdin
> ```
>
> Without stored credentials, pulls from non-Docker Hub registries are anonymous and private kits fail to pull.

## [Packaging and distribution](#packaging-and-distribution)

The `sbx kit` subcommands validate, inspect, and publish kits:

* `sbx kit validate <path>` — check that a kit directory or ZIP is well-formed.
* `sbx kit inspect <path>` — display kit details. Add `--json` for machine-readable output.
* `sbx kit pack <path> -o <file.zip>` — package a directory as a ZIP file for sharing.
* `sbx kit push <path> <ref>` — publish to an OCI registry (for example, `ghcr.io/myorg/my-kit:1.0`).
* `sbx kit pull <ref>` — download a kit from a registry as a ZIP file to the working directory.

For Docker Hub, include the full `docker.io` prefix — `sbx` doesn't add it automatically.

`sbx kit pull` prefers credentials stored with [`sbx secret set --registry`](https://docs.docker.com/ai/sandboxes/security/credentials/#registry-credentials), falling back to the Docker credential store. `sbx kit push` only uses the Docker credential store, so pushing to a private registry requires a prior `docker login`.

## [Spec reference](#spec-reference)

A kit directory has a required `spec.yaml` and an optional `files/` tree:

```text
my-kit/
├── spec.yaml       # required
└── files/          # optional — static files to inject
    ├── home/
    └── workspace/
```

### [Top-level fields](#top-level-fields)

```yaml
schemaVersion: "1"
kind: <mixin | agent>
name: <name>
displayName: <name>
description: <text>
```

| Field           | Required | Description                                                              |
| --------------- | -------- | ------------------------------------------------------------------------ |
| `schemaVersion` | Yes      | Spec schema version. Set to `"1"`.                                       |
| `kind`          | Yes      | `mixin` for kits that extend an agent; `agent` for kits that define one. |
| `name`          | Yes      | Unique identifier. Lowercase, alphanumeric, hyphens.                     |
| `displayName`   | No       | Human-readable name.                                                     |
| `description`   | No       | Short description.                                                       |

The sections below apply to both kinds. Agent kits also declare an [`agent:` block](#agent-block).

### [Credentials](#credentials)

```yaml
credentials:
  sources:
    <service-id>:
      env: [<env-var>, ...]
      file:
        path: <path>
        parser: <parser>
      priority: <env-first | file-first>
```

| Field                      | Description                                                   |
| -------------------------- | ------------------------------------------------------------- |
| `sources`                  | Map of service identifier to credential source.               |
| `sources.<id>.env`         | Environment variables to read on the host, in priority order. |
| `sources.<id>.file.path`   | Path on host. `~` expands to home.                            |
| `sources.<id>.file.parser` | How to extract the value (for example, `"json:apiKey"`).      |
| `sources.<id>.priority`    | `env-first` (default) or `file-first`.                        |

Service identifiers link credentials to [network rules](#network).

### [Network](#network)

```yaml
network:
  allowedDomains: [<domain>, ...]
  deniedDomains: [<domain>, ...]
  serviceDomains:
    <domain>: <service-id>
  serviceAuth:
    <service-id>:
      headerName: <header>
      valueFormat: <format>
```

| Field                     | Description                                                      |
| ------------------------- | ---------------------------------------------------------------- |
| `allowedDomains`          | Domains the sandbox can reach. Wildcards supported.              |
| `deniedDomains`           | Domains the sandbox can't reach. Deny rules take precedence.     |
| `serviceDomains`          | Map of domain to service identifier from `credentials.sources`.  |
| `serviceAuth.headerName`  | HTTP header the proxy sets (for example, `Authorization`).       |
| `serviceAuth.valueFormat` | Format string for the header value (for example, `"Bearer %s"`). |

### [Environment](#environment)

```yaml
environment:
  variables:
    NAME: <value>
  proxyManaged: [NAME, ...]
```

| Field          | Description                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `variables`    | Key-value pairs set directly in the container.                                                                      |
| `proxyManaged` | Environment variable names populated by the proxy at request time. Pair with [`credentials.sources`](#credentials). |

Variable names must be valid shell identifiers (`[A-Za-z_][A-Za-z0-9_]*`).

### [Commands](#commands)

```yaml
commands:
  install:
    - command: <shell-string>
      user: <uid>
      description: <text>
  startup:
    - command: [<argv>, ...]
      user: <uid>
      background: <true | false>
      description: <text>
  initFiles:
    - path: <path>
      content: <text>
      mode: <octal>
      onlyIfMissing: <true | false>
      description: <text>
```

#### [`install`](#install)

Runs once during sandbox creation. Shell strings passed to `sh -c`.

| Field         | Default | Description                   |
| ------------- | ------- | ----------------------------- |
| `command`     | —       | Shell command string.         |
| `user`        | `"0"`   | User to run as. `"0"` = root. |
| `description` | —       | Human-readable description.   |

#### [`startup`](#startup)

Runs at every sandbox start. String array, not interpreted by a shell.

| Field         | Default  | Description                         |
| ------------- | -------- | ----------------------------------- |
| `command`     | —        | Command and args as a string array. |
| `user`        | `"1000"` | User to run as. `"1000"` = agent.   |
| `background`  | `false`  | Run in background.                  |
| `description` | —        | Human-readable description.         |

Startup commands are non-interactive. They run before the agent attaches, with no terminal connected, so they can't prompt the user (for example, an interactive `aws login` will hang or fail). They also don't gate the agent's entrypoint: the agent launches once startup commands have been dispatched, regardless of `background`. Use them for non-interactive prep — launching daemons, warming caches, refreshing config — and use `commands.initFiles` for any value that needs to land on disk before the agent runs.

Startup commands must be idempotent. They run on every sandbox start and replay on container restarts, so a command that fails or misbehaves on a second invocation breaks the restart path. Guard work with existence checks, use upserts instead of inserts, and prefer commands that converge to the same end state regardless of how many times they run.

#### [`initFiles`](#initfiles)

Files written at sandbox start, with runtime substitution.

| Field           | Default  | Description                                               |
| --------------- | -------- | --------------------------------------------------------- |
| `path`          | —        | Absolute container path.                                  |
| `content`       | —        | File content. `${WORKDIR}` expands to the workspace path. |
| `mode`          | `"0644"` | File permissions in octal.                                |
| `onlyIfMissing` | `false`  | Skip if the file already exists.                          |

### [Static files](#static-files)

```text
my-kit/files/
├── home/       → /home/agent/
└── workspace/  → primary workspace path
```

| Kit path           | Container destination                   |
| ------------------ | --------------------------------------- |
| `files/home/`      | `/home/agent/` (config files, dotfiles) |
| `files/workspace/` | The primary workspace path              |

Parent directories are created automatically. Existing files are overwritten. Absolute paths and path-traversal sequences (`../../`) are rejected.

### [Memory](#memory)

```yaml
memory: |
  <markdown>
```

Top-level field. Available in both mixin and agent kits. Markdown appended to the agent's memory file at sandbox creation. The agent reads this content at startup. Write it as instructions or notes the agent should follow when working in the sandbox. Applied only when the active agent kit sets [`agent.aiFilename`](#agent-block).

The file is written to the parent of the workspace path inside the sandbox, not to the workspace itself. For a workspace mounted at `/Users/you/myproject`, the memory file lands at `/Users/you/AGENTS.md` (or whatever `aiFilename` is set to). It exists only inside the sandbox. Nothing is written to the host.

When several loaded kits declare `memory:` blocks, the content is split across files instead of being concatenated into the main one:

* Each kit's memory is written to `<kit-name>.md` in a sibling `kits-memory/` directory next to the main memory file.
* The main memory file gets a `## Kits` section listing every kit with a pointer to its file. The section is delimited by `<!-- sbx:kits-section start -->` and `<!-- sbx:kits-section end -->` markers so it can be regenerated when kits are added or removed.

### [Agent block](#agent-block)

Required for `kind: agent`.

```yaml
agent:
  image: <image-ref>
  aiFilename: <filename>
  persistence: <persistent | ephemeral>
  entrypoint:
    run: [<argv>, ...]
    args: [<arg>, ...]
```

| Field                   | Required | Description                                                                                    |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `agent.image`           | Yes      | Docker image reference. See [Base image requirements](#base-image-requirements).               |
| `agent.aiFilename`      | No       | Memory filename (for example, `AGENTS.md`). Appends top-level [`memory`](#memory) at creation. |
| `agent.persistence`     | No       | `persistent` (named volume across restarts) or `ephemeral` (default).                          |
| `agent.entrypoint.run`  | No       | Command and args as a string array. Replaces the image's entrypoint.                           |
| `agent.entrypoint.args` | No       | Args appended to the image's existing entrypoint.                                              |

#### [Base image requirements](#base-image-requirements)

The agent's container image must provide:

* A non-root `agent` user at UID 1000 with passwordless sudo.
* A `/home/agent/` home directory owned by `agent`.
* HTTP proxy environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) preserved across sudo.
* The agent binary (baked in, or installed via [`commands.install`](#commands)).

Build on top of `docker/sandbox-templates:shell-docker` to get these for free.

## [Debugging](#debugging)

When a kit doesn't behave as expected, start with the network policy log and direct inspection inside the sandbox:

* `sbx policy log` shows every outbound request the sandbox proxy saw, the rule it matched, extra context when available, and its `PROXY` value, such as `forward`, `forward-bypass`, `transparent`, or `browser-open`. Use it to diagnose install-time download failures, blocked domains, and unexpected TLS interception. If downloads fail or arrive corrupted after you add `serviceDomains`, check whether the service mapping is too broad. Map only the hosts that need credential injection.
* `sbx exec <sandbox> -- <cmd>` runs an arbitrary command inside an existing sandbox. Useful for inspecting post-install state without recreating: `which mytool`, `ls /home/agent/.local/bin/`, `cat /home/agent/.config/...`, and so on.

Install and startup command output is only emitted during `sbx run` or `sbx create`; `sbx` doesn't retain it for later inspection. To repeat setup with fresh output, remove and recreate the sandbox: `sbx rm <sandbox> && sbx run ...`.

----
url: https://docs.docker.com/engine/
----

# Docker Engine

***

Table of contents

***

Docker Engine is an open source containerization technology for building and containerizing your applications. Docker Engine acts as a client-server application with:

* A server with a long-running daemon process [`dockerd`](/reference/cli/dockerd).
* APIs which specify interfaces that programs can use to talk to and instruct the Docker daemon.
* A command line interface (CLI) client [`docker`](/reference/cli/docker/).

The CLI uses [Docker APIs](https://docs.docker.com/reference/api/engine/) to control or interact with the Docker daemon through scripting or direct CLI commands. Many other Docker applications use the underlying API and CLI. The daemon creates and manages Docker objects, such as images, containers, networks, and volumes.

For more details, see [Docker Architecture](https://docs.docker.com/get-started/docker-overview/#docker-architecture).

### [Install Docker Engine](/engine/install)

[Learn how to install the open source Docker Engine for your distribution.](/engine/install)

### [Storage](/storage)

[Use persistent data with Docker containers.](/storage)

### [Networking](/network)

[Manage network connections between containers.](/network)

### [Container logs](/config/containers/logging/)

[Learn how to view and read container logs.](/config/containers/logging/)

### [Prune](/config/pruning)

[Tidy up unused resources.](/config/pruning)

### [Configure the daemon](/config/daemon)

[Delve into the configuration options of the Docker daemon.](/config/daemon)

### [Rootless mode](/engine/security/rootless)

[Run Docker without root privileges.](/engine/security/rootless)

### [Deprecated features](/engine/deprecated/)

[Find out what features of Docker Engine you should stop using.](/engine/deprecated/)

### [Release notes](/engine/release-notes)

[Read the release notes for the latest version.](/engine/release-notes)

## [Licensing](#licensing)

Commercial use of Docker Engine obtained via Docker Desktop within larger enterprises (exceeding 250 employees OR with annual revenue surpassing $10 million USD), requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsEngine). Apache License, Version 2.0. See [LICENSE](https://github.com/moby/moby/blob/master/LICENSE) for the full license.

----
url: https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/known-issues/
----

# Known issues

***

***

* The Mac Activity Monitor reports that Docker is using twice the amount of memory it's actually using. This is due to a [bug in macOS](https://docs.google.com/document/d/17ZiQC1Tp9iH320K-uqVLyiJmk4DHJ3c4zgQetJiKYQM/edit?usp=sharing).

* **"Docker.app is damaged" dialog**: If you see a "Docker.app is damaged and can't be opened" dialog during installation or updates, this is typically caused by non-atomic copy operations when other applications are using the Docker CLI. See [Fix "Docker.app is damaged" on macOS](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog/) for resolution steps.

* Force-ejecting the `.dmg` after running `Docker.app` from it can cause the whale icon to become unresponsive, Docker tasks to show as not responding in the Activity Monitor, and for some processes to consume a large amount of CPU resources. Reboot and restart Docker to resolve these issues.

* Docker Desktop uses the `HyperKit` hypervisor (<https://github.com/docker/hyperkit>) in macOS 10.10 Yosemite and higher. If you are developing with tools that have conflicts with `HyperKit`, such as [Intel Hardware Accelerated Execution Manager (HAXM)](https://software.intel.com/en-us/android/articles/intel-hardware-accelerated-execution-manager/), the current workaround is not to run them at the same time. You can pause `HyperKit` by quitting Docker Desktop temporarily while you work with HAXM. This allows you to continue work with the other tools and prevent `HyperKit` from interfering.

* If you are working with applications like [Apache Maven](https://maven.apache.org/) that expect settings for `DOCKER_HOST` and `DOCKER_CERT_PATH` environment variables, specify these to connect to Docker instances through Unix sockets. For example:

  ```console
  $ export DOCKER_HOST=unix:///var/run/docker.sock
  ```

- Some command line tools do not work when Rosetta 2 is not installed.

  * The old version 1.x of `docker-compose`. Use Compose V2 instead - type `docker compose`.
  * The `docker-credential-ecr-login` credential helper.

- Some images do not support the ARM64 architecture. You can add `--platform linux/amd64` to run (or build) an Intel image using emulation.

  However, attempts to run Intel-based containers on Apple silicon machines under emulation can crash as QEMU sometimes fails to run the container. In addition, filesystem change notification APIs (`inotify`) do not work under QEMU emulation. Even when the containers do run correctly under emulation, they will be slower and use more memory than the native equivalent.

  In summary, running Intel-based containers on Arm-based machines should be regarded as "best effort" only. We recommend running `arm64` containers on Apple silicon machines whenever possible, and encouraging container authors to produce `arm64`, or multi-arch, versions of their containers. This issue should become less common over time, as more and more images are rebuilt [supporting multiple architectures](https://www.docker.com/blog/multi-arch-build-and-images-the-simple-way/).

- Users may occasionally experience data drop when a TCP stream is half-closed.

----
url: https://docs.docker.com/ai/gordon/use-cases/
----

# Gordon use cases and examples

***

Table of contents

***

Requires: Docker Desktop [4.74.0](https://docs.docker.com/desktop/release-notes/#4740) or later

Gordon handles Docker workflows through natural conversation. In Docker Desktop, Gordon is available from the sidebar for open-ended sessions and from contextual entry points in views like Containers, Images, Builds, and Volumes. Selecting Gordon from one of these views opens a conversation pre-loaded with context about the item you're looking at. You can ask the same questions from the CLI with `docker ai`.

## [Debug a failing container](#debug-a-failing-container)

You're in the Containers view and a container has crashed or behaves unexpectedly. Open Gordon from the container row to ask about that container's state and configuration:

* "Why did this container exit?"
* "What environment variables are set in this container?"
* "How long did this container run?"
* "What security settings are applied to this container?"

From the CLI:

```console
$ docker ai "why is my postgres container crashing on startup?"
```

## [Debug a failed build](#debug-a-failed-build)

You're in the Builds view looking at a build that failed or is slower than expected. Open Gordon from the build to inspect the Dockerfile, build arguments, and cache behavior:

* "Why did this build fail?"
* "How can I improve cache usage for this build?"
* "What Dockerfile instructions were used?"
* "What build arguments were used?"

From the CLI:

```console
$ docker ai "my build is failing at the pip install step, what's wrong?"
```

## [Inspect an image](#inspect-an-image)

You're in the Images view and want to understand what's in an image before running it, or you want to size up a base image:

* "How do I run this image in the CLI?"
* "What environment variables are configured?"
* "What entrypoint is configured?"
* "What's the base architecture of this image?"
* "Is there a lighter version of this image?"

From the CLI:

```console
$ docker ai "compare my python:3.12 image to python:3.12-slim"
```

## [Manage volumes and resources](#manage-volumes-and-resources)

From the Volumes view, ask Gordon about what's stored, which containers use a volume, or how to clean up. From any view, use the Gordon sidebar to inspect your wider environment:

* "Which containers are using this volume?"
* "Show me all my containers and their status"
* "How much disk space is Docker using?"
* "List my images sorted by size"

From the CLI:

```console
$ docker ai "clean up all unused Docker resources"
```

## [Build and containerize](#build-and-containerize)

For new projects, start a conversation in the Gordon sidebar or via `docker ai` from your project directory. Gordon reads your working directory and proposes the right files:

* "Containerize my Node.js app"
* "Create a docker-compose for my stack"
* "Set up a dev environment with Postgres and Redis"

From the CLI:

```console
$ cd ~/my-project
$ docker ai "create a Dockerfile for this application"
```

## [Develop and optimize](#develop-and-optimize)

Ask Gordon to review and improve existing Dockerfiles or service definitions. You can start from the Images view (for an image you've already built) or from the Gordon sidebar with your project context:

* "Optimize this Dockerfile"
* "Add a health check to my service"
* "Make my Dockerfile more secure"

From the CLI:

```console
$ docker ai "rate my Dockerfile and suggest improvements"
```

## [Learn Docker](#learn-docker)

For conceptual questions, use the Gordon sidebar or CLI. Gordon explains concepts grounded in your environment, not generic answers:

* "What is a Docker volume?"
* "Explain multi-stage builds"
* "How does networking work in Docker?"

From the CLI:

```console
$ docker ai "what's the difference between COPY and ADD in a Dockerfile?"
```

## [Writing effective prompts](#writing-effective-prompts)

Be specific:

* Include relevant context: "my postgres container" not "the database"
* State your goal: "make my build faster" not "optimize"
* Include error messages when debugging

Gordon works best when you describe what you want to achieve rather than how to do it. Gordon maintains context across a conversation, so you can follow up with clarifications or ask related questions without repeating yourself.

### [Working directory context](#working-directory-context)

When using `docker ai` in the CLI, Gordon uses your current working directory as the default context for file operations. Change to your project directory before starting Gordon to ensure it has access to the right files:

```console
$ cd ~/my-project
$ docker ai "review my Dockerfile"
```

You can also override the working directory with the `-C` flag. See [Using Gordon via CLI](https://docs.docker.com/ai/gordon/how-to/cli/#working-directory) for details.

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/delete/
----

# docker dhi customization delete

***

| Description | Delete one or more customizations              |
| ----------- | ---------------------------------------------- |
| Usage       | `docker dhi customization delete <id> [id...]` |

## [Description](#description)

Delete one or more Docker Hardened Images customizations by their IDs.

Multiple IDs can be specified as positional arguments.

Examples:

# [Delete a single customization](#delete-a-single-customization)

docker dhi customization delete abc123

# [Delete multiple customizations](#delete-multiple-customizations)

docker dhi customization delete abc123 def456 ghi789

# [Delete without confirmation prompt](#delete-without-confirmation-prompt)

docker dhi customization delete abc123 def456 --force

## [Options](#options)

| Option        | Default | Description                                                   |
| ------------- | ------- | ------------------------------------------------------------- |
| `-f, --force` |         | Skip the confirmation prompt; aborts if any ID does not exist |

----
url: https://docs.docker.com/docker-hub/repos/manage/builds/
----

# Automated builds

***

***

Subscription: Pro Team Business

Availability: Deprecated

> Warning
>
> Docker Hub Automated Builds is a deprecated feature. It will be fully retired on April 1, 2027.

Docker Hub can automatically build images from source code in an external repository and automatically push the built image to your Docker repositories.

When you set up automated builds, also called autobuilds, you create a list of branches and tags that you want to build into Docker images. When you push code to a source-code branch, for example in GitHub, for one of those listed image tags, the push uses a webhook to trigger a new build, which produces a Docker image. The built image is then pushed to Docker Hub.

> Note
>
> You can still use `docker push` to push pre-built images to repositories with automated builds configured.

If you have automated tests configured, these run after building, but before pushing to the registry. You can use these tests to create a continuous integration workflow where a build that fails its tests doesn't push the built image. Automated tests don't push images to the registry on their own. [Learn about automated image testing](https://docs.docker.com/docker-hub/repos/manage/builds/automated-testing/).

Depending on your [subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsHubRepoBuilds), you may get concurrent builds, which means that `N` autobuilds can be run at the same time. `N` is configured according to your subscription. Once `N+1` builds are running, any additional builds go into a queue to be run later.

The maximum number of pending builds in the queue is 30 and Docker Hub discards further requests. The number of concurrent builds for Pro is 5 and for Team and Business is 15. Automated builds can handle images of up to 10 GB in size.

----
url: https://docs.docker.com/desktop/release-notes/
----

# Docker Desktop release notes

***

Table of contents

***

This page contains information about the new features, improvements, known issues, and bug fixes in Docker Desktop releases.

Releases are gradually rolled out to ensure quality control. If the latest version is not yet available to you, allow some time — updates typically become available within a week of the release date.

Docker Desktop versions older than 6 months from the latest release are not available for download. Previous release notes are available in our [documentation repository](https://github.com/docker/docs/tree/main/content/manuals/desktop/previous-versions).

For more frequently asked questions, see the [FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/releases/).

## [4.75.0](#4750)

*2026-05-25*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/227598/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/227598/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/227598/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/227598/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/227598/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/227598/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/227598/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/227598/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/227598/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/227598/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/227598/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/227598/checksums.txt))

### [Updates](#updates)

* [Docker Offload v0.5.92](https://github.com/docker/cloud/releases/tag/v0.5.92)
* [Docker Engine v29.5.2](https://docs.docker.com/engine/release-notes/29/#2952)
* [Docker Buildx v0.34.0](https://github.com/docker/buildx/releases/tag/v0.34.0)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

#### [For all platforms](#for-all-platforms)

* Removed the Docker Scout view and disabled Scout-related OS notifications and notification popups.
* Added support for time namespacing in ECI protected containers.
* Fixed a bug where the `http_proxy` environment variable could prevent kind clusters from pulling local images.
* Fixed a `500 Internal Server Error` that could occur on the first Docker API call right after the VM wakes up from idle shutdown.
* Fixed broken images in Docker Hub image descriptions caused by relative URLs being resolved to invalid `app://` scheme URLs.

#### [For Mac](#for-mac)

* Added a warning dialog that appears at startup when Docker Desktop is running from a staging directory due to a failed update. Also adds a link to download a fresh install.

#### [For Windows](#for-windows)

* WSL integration with the default distribution has been disabled. To change this, visit **Settings**.
* Fixed a bug where `docker compose up` failed with an `EOF` error on Windows with a Hyper-V backend, when accepting a file-sharing consent prompt.
* Fixed Windows installer bugs that could cause incorrect backend mode detection or unexpected directory creation during installation.

## [4.74.0](#4740)

*2026-05-19*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/227015/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/227015/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/227015/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/227015/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/227015/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/227015/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/227015/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/227015/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/227015/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/227015/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/227015/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/227015/checksums.txt))

### [New](#new)

* [Gordon](/ai/gordon) is now generally available. New usage plans are also available. Paid Gordon plans unlock higher usage limits.

### [Updates](#updates-1)

* [Docker Offload v0.5.89](https://github.com/docker/cloud/releases/tag/v0.5.89)
* [Docker Agent v1.57.0](https://github.com/docker/docker-agent/releases/tag/v1.57.0)
* [Credential helpers v0.9.7](https://github.com/docker/docker-credential-helpers/releases/tag/v0.9.7)
* `docker pass` v0.0.26

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

#### [For all platforms](#for-all-platforms-1)

* Fixed a bug where Docker Desktop's own Electron helper processes (GPU, renderer, utility) were incorrectly detected and killed as lingering processes on startup when launching from the Start menu, causing a crash loop.
* Fixed an issue where the **View build logs** toggle in Logs view display settings was reset after restarting Docker Desktop instead of persisting the user's preference.
* Docker Extensions is now disabled by default.

#### [For Mac](#for-mac-1)

* Fixed published ports being inaccessible when a container is also connected to a Swarm overlay network. Fixes [docker/for-mac#7854](https://github.com/docker/for-mac/issues/7854).
* Fixed dashboard TLS failures in some corporate environments.
* Improved GUI security via content hash validation.

#### [For Linux](#for-linux)

* Added support for Ubuntu 26.04.

## [4.73.1](#4731)

*2026-05-13*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/226574/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/226574/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

#### [For Windows](#for-windows-1)

* Fixed a bug where Docker Desktop's own Electron processes were incorrectly killed when launching from the Start menu. Fixes [docker/desktop-feedback#367](https://github.com/docker/desktop-feedback/issues/367).

## [4.73.0](#4730)

*2026-05-11*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/226246/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/226246/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/226246/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/226246/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/226246/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/226246/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/226246/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/226246/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/226246/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/226246/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/226246/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/226246/checksums.txt))

### [Updates](#updates-2)

* [Docker Engine v29.4.3](https://docs.docker.com/engine/release-notes/29/#2943)
* [Docker Agent v1.54.0](https://github.com/docker/docker-agent/releases/tag/v1.54.0)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-3)

#### [For all platforms](#for-all-platforms-2)

* Fixed `Cmd+Q` (Mac) and `Ctrl+Q` (Windows/Linux) not fully quitting Docker Desktop. Fixes [docker/for-mac#7833](https://github.com/docker/for-mac/issues/7833).
* Fixed a bug where canceling `docker load` left a containerd ref lock held, causing subsequent loads of the same image to fail.
* Fixed an issue where Docker Desktop made unnecessary network requests to `mcp.docker.com` on sign-in when MCP Toolkit was disabled, causing unexpected proxy authentication prompts.
* Fixed an issue where the search input in Gordon's session sidebar would not close if it was left empty.
* Improved Docker Desktop handling of transient rename failures caused by antivirus software accessing those files simultaneously.

#### [For Mac](#for-mac-2)

* Fixed excessive memory usage on Apple Silicon Macs by improving the Linux VM's ability to return freed container memory back to the host OS.
* Fixed a bug where containers received connections with a corrupted source IP when another container had an active outbound connection to an IP in the same subnet range. Fixes [docker/for-mac#7824](https://github.com/docker/for-mac/issues/7824).

## [4.72.0](#4720)

*2026-05-06*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/225998/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/225998/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/225998/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/225998/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/225998/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/225998/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/225998/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/225998/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/225998/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/225998/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/225998/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/225998/checksums.txt))

### [New](#new-1)

* The **Logs** view is now generally available.
* New installations of Docker Desktop for Windows have a choice between per-user (Beta) or all-user installs.

### [Updates](#updates-3)

* [Docker Agent v1.50.0](https://github.com/docker/docker-agent/releases/tag/v1.50.0)
* [Docker DHI (`dhictl`) v0.0.3](https://github.com/docker-hardened-images/dhictl/releases/tag/v0.0.3)
* [Docker Model Runner v1.1.37](https://github.com/docker/model-cli/releases/tag/v1.1.37)
* [credential helpers v0.9.6](https://github.com/docker/docker-credential-helpers/releases/tag/v0.9.6)

### [Security](#security)

* The Extensions settings page now includes a security notice that extensions run with host-level privileges and are not audited by Docker.
* [Fixed CVE-2026-31431 ("copy.fail")](https://xint.io/blog/copy-fail-linux-distributions) by backporting an upstream Linux kernel patch that prevents an unprivileged container user from gaining root inside the container via a controlled write into the host VM page cache.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-4)

#### [For all platforms](#for-all-platforms-3)

* Improvements to Docker Offload idle notifications.
* Fixed the **Open Gordon in TUI** button not working due to a missing `run` subcommand in Docker Agent command arguments.
* Fixed an issue where transient network errors or Docker Hub server errors during sign-in would unexpectedly sign users out instead of retrying automatically.
* Improved data refresh for the Containers, Images, and Volumes screens by fetching up-to-date data on demand when navigating to those screens, reducing background polling load.
* Fixed a kernel crash that could occur when changing filesharing technology after significant container file activity.
* Enable the OpenAI Responses API (`/responses`) endpoint in Docker Model Runner.
* Fixed a bug where users were unexpectedly signed out of Docker Desktop mid-flow when signing in via `docker login` using OAuth.

#### [For Windows](#for-windows-2)

* Fixed a bug on Windows where selecting the Docker Desktop taskbar icon multiple times could spawn multiple backend processes. Re-selecting the icon while Docker Desktop is running now brings the dashboard to focus.
* Fixed a race condition on Windows that caused a false-positive "processes still running" dialog to appear when Docker Desktop starts or exits normally.

### [For Linux](#for-linux-1)

* Support for RHEL 8 has been dropped.

## [4.71.0](#4710)

*2026-04-27*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/225177/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/225177/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/225177/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/225177/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/225177/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/225177/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/225177/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/225177/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/225177/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/225177/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/225177/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/225177/checksums.txt))

> Important
>
> Support for RHEL 8 has ended. Installing Docker Desktop will require RHEL 9 or RHEL 10 in the next release.

### [Updates](#updates-4)

* [Docker Model Runner v1.1.36](https://github.com/docker/model-runner/releases/tag/v1.1.36)
* [containerd to v2.2.3](https://github.com/containerd/containerd/releases/tag/v2.2.3)
* [Runc v1.3.5](https://github.com/opencontainers/runc/releases/tag/v1.3.5)
* [Docker Compose v5.1.3](https://github.com/docker/compose/releases/tag/v5.1.3)
* [Docker Agent v1.44.0](https://github.com/docker/docker-agent/releases/tag/v1.44.0)
* [Docker Engine v29.4.1](https://docs.docker.com/engine/release-notes/29/#2941)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-5)

#### [For all platforms](#for-all-platforms-4)

* Docker Model Runner is now disabled by default and must be explicitly enabled in **Settings**. When enabled, TCP host-side support is automatically active.
* Fixed an issue where downloading a Docker Desktop update would fail without a clear error if the disk had insufficient free space.
* Fixed an issue where Docker Scout tag recommendations, when inspecting an image, failed when the base image digest or repository name was empty.
* Added a **Switch to local Docker context** button on the sign-in screen, allowing users in a cloud context to switch back to their local context without signing in.
* Added a dedicated **Stopped** status screen for the cloud engine so users see a clear stopped state instead of an error screen when transitioning away from Docker Offload.

#### [For Mac](#for-mac-3)

* Fixed an issue where error tracking would temporarily continue sending session data directly after a user disabled analytics. Fixes [docker/for-mac#7768](https://github.com/docker/for-mac/issues/7768).

#### [For Windows](#for-windows-3)

* Fixed a critical issue where Docker Desktop Dashboard failed to open with `ERR_FAILED` errors caused by process hardening policies conflicting with Chromium.
* Fixed a bug where Kubernetes could fail to start on WSL 2 when `HTTP_PROXY` environment variables are set in WSL 2 itself.
* Fixed a bug in Enhanced Container Isolation (ECI) that was causing loss of container `rootfs` persistence across Docker Desktop restarts, when using WSL.

### [Security](#security-1)

* Addressed [CVE-2026-5843](https://www.cve.org/cverecord?id=CVE-2026-5843), container-to-host code execution in the Docker Model Runner MLX inference backend via MLX-LM `model_file` importlib loading.

## [4.70.0](#4700)

*2026-04-20*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/224270/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/224270/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/224270/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/224270/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/224270/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/224270/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/224270/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/224270/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/224270/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/224270/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/224270/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/224270/checksums.txt))

### [New](#new-2)

* Added a CLI hint that surfaces the **Logs** view when running `logs`, `compose logs`, `compose attach`, or `compose up` commands, giving you quick access to logs across all running containers. Available with the **Logs** (Beta) feature enabled.

### [Updates](#updates-5)

* [Docker Compose v5.1.2](https://github.com/docker/compose/releases/tag/v5.1.2)
* [Docker Engine v29.4.0](https://docs.docker.com/engine/release-notes/29/#2940)
* [Docker Agent v1.43.0](https://github.com/docker/docker-agent/releases/tag/v1.43.0)
* [Docker Model Runner v1.1.33](https://github.com/docker/model-runner/releases/tag/v1.1.33)
* [Docker Scout CLI v1.20.4](https://github.com/docker/scout-cli/releases/tag/v1.20.4)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-6)

#### [For all platforms](#for-all-platforms-5)

* Fixed a bug where `docker login` could fail silently in CI environments due to slow Docker Hub responses causing credential store update timeouts.
* Fixed an issue where disabling Beta features also disabled Docker Model Runner.
* Fixed `docker desktop start` causing the Docker AI agent API daemon to fail due to an inherited CLI plugin environment variable.

#### [For Mac](#for-mac-4)

* Fixed a crash loop where Docker Desktop repeatedly failed to start with exit status `42` after an update due to a corrupted `DockerAppLaunchPath` setting.
* Fixed an issue where a failed update could leave Docker Desktop in a broken state. The installer now automatically reverts to the previous version and shows a clear error message.
* Fixed a bug where stopping one container could disrupt active Unix socket forwards belonging to other running containers.

#### [For Windows](#for-windows-4)

* Fixed an issue where a failed update could leave Docker Desktop in a broken state. The installer now automatically reverts to the previous version and shows a clear error message.
* Fixed a bug where a failed switch to Windows containers could leave Docker Desktop in a broken state, requiring a restart.
* Fixed an issue where Docker Desktop failed to launch for users with `DEVHOME` set in their environment.
* Temporarily rolled back process hardening that caused Electron crashes on Windows. Fixes [docker/desktop-feedback#245](https://github.com/docker/desktop-feedback/issues/245).

## [4.69.0](#4690)

*2026-04-13*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/224084/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/224084/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/224084/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/224084/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/224084/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/224084/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/224084/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/224084/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/224084/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/224084/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/224084/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/224084/checksums.txt))

### [Updates](#updates-6)

* [Docker Agent v1.42.0](https://github.com/docker/docker-agent/releases/tag/v1.42.0)
* [Docker Model v1.1.29](https://github.com/docker/model-runner/releases/tag/v1.1.29)
* [containerd v2.2.2](https://github.com/containerd/containerd/releases/tag/v2.2.2)
* [Docker Buildx v0.33.0](https://github.com/docker/buildx/releases/tag/v0.33.0)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-7)

#### [For all platforms](#for-all-platforms-6)

* Fixed an issue where `docker logout` from the CLI was ignored by Docker Desktop when OAuth tokens remained in the credential store, leaving the user unexpectedly signed in.
* Fixed an issue where Docker Desktop could unexpectedly sign users out when unrelated credential updates, `docker login`, or transient network errors triggered a sign-out.
* Fixed a data loss issue where backup data could be deleted during a failed restore operation, leaving users with no data.
* Fixed an issue where sign-in credentials (`login-info.json`) could be included in diagnostic bundles, improving privacy and security. Note that this file contains an encoded organisation(s) name, plan name, encoded username, and encoded email only. No passwords or credentials are included.
* Fixed the footer update label incorrectly showing **Downloading** during the prepare/unpack phase of an update. It now correctly displays **Preparing**.
* Fixed an issue where Docker Desktop would not start when the internal storage disk was full.

#### [For Mac](#for-mac-5)

* Fixed an issue where the in-app update button was not disabled when `Docker.app` was installed in a non-user-writable directory, preventing failed update attempts.
* Fixed update failure for users who installed Docker Desktop via Homebrew on Mac.

#### [For Windows](#for-windows-5)

* Fixed an unexpected WSL terminal popup appearing for Windows users using the Hyper-V backend during Docker Desktop installation or uninstallation.
* Fixed an issue on Windows where factory reset deleted CLI plugins from `~/.docker/cli-plugins`, causing `docker build` to fall back to the legacy builder.
* Fixed a bug where Kubernetes failed to start when WSL integration was enabled alongside another distro using cgroup v1 controllers.
* Fixed a race condition that caused Kubernetes to fail to start when a Registry Access Management policy change occurred during startup.
* Prevent Docker Desktop from fatally failing due to transient 'Access is denied' errors during file operations on Windows.

## [4.68.0](#4680)

*2026-04-07*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/223695/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/223695/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/223695/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/223695/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/223695/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/223695/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/223695/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/223695/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/223695/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/223695/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/223695/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/223695/checksums.txt))

### [New](#new-3)

* Gordon now has persistent local memory, allowing it to remember your preferences and context across sessions.

### [Updates](#updates-7)

* [Docker Agent v1.39.0](https://github.com/docker/docker-agent/releases/tag/v1.39.0)
* [Docker Model v1.1.28](https://github.com/docker/model-runner/releases/tag/v1.1.28)
* [Docker Offload v0.5.81](https://github.com/docker/cloud/releases/tag/v0.5.81)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-8)

#### [For all platforms](#for-all-platforms-7)

* Fixed a deadlock in Enhanced Container Isolation that caused containers to hang indefinitely during creation when ECI was enabled.
* Added a warning banner to alert when an MCP server is community-provided and has not been verified by Docker.
* Added a persistent **Show timestamps** toggle to the **Logs** view, allowing timestamps to be hidden in both table and visualiser views across sessions.
* Fixed an issue where Docker Desktop frontend processes were not properly terminated on quit.
* Fixed a deadlock when settings controlled by admins reload that could cause Docker Desktop to become unresponsive during sign in or sign out operations.
* Fixed a bug where Docker Desktop could fail to start due to uncorrectable filesystem errors on the disk image not being repaired.
* Fixed a bug that caused Enhanced Container Isolation (ECI) to inadvertently block startup of Kubernetes clusters.
* Fixed an issue where a failed volume size fetch could make the **Volumes** view inaccessible; container counts on volumes now correctly exclude bind mounts.
* Fixed race conditions in volume backup that could cause containers to be incorrectly restarted, export logs to be corrupted, or runtime panics when scheduling tasks.
* Fixed a crash in the API cache that occurred when containers with no names caused a panic disrupting container listing.
* Fixed a bug where starting a container could fail with `ENOENT` if a bind-mount parent directory was deleted while no container was using it.

#### [For Mac](#for-mac-6)

* Fixed a security vulnerability where tampered user-deployed config profiles could bypass organization sign-in enforcement.
* Fixed a bug where a failed `vmnetd` handshake could dispatch a bogus command on a broken connection, causing unexpected networking errors.
* Fixed a bug where the Docker Desktop Dashboard could be prematurely displayed when restoring to a fullscreen state on launch.
* Fixed nested bind mounts showing empty child mount content on VirtioFS when using Docker Compose with multiple services sharing a volume. Fixes [docker/desktop-feedback#264](https://github.com/docker/desktop-feedback/issues/264).

#### [For Windows](#for-windows-6)

* Fixed an issue where the installer extraction did not update the progress bar and could take around 5 minutes, depending on the machine. Extraction is now \~60% faster and includes proper progress updates.
* Fixed a race condition where container ports would sometimes not be published correctly after container start, affecting ephemeral ports, `--publish-all`, and gateway IP bindings.
* Fixed an issue where a failed WSL distro move could leave the distro unregistered.

### [Security](#security-2)

* Addressed [CVE-2026-5817](https://www.cve.org/cverecord?id=CVE-2026-5817), container-to-host code execution in the Docker Model Runner vllm-metal inference backend via unsandboxed `trust_remote_code` tokenizer loading.

## [4.67.0](#4670)

*2026-03-30*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/222858/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/222858/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/222858/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/222858/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/222858/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/222858/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/222858/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/222858/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/222858/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/222858/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/222858/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/222858/checksums.txt))

### [New](#new-4)

* Docker MCP Toolkit now has MCP profile template cards and an onboarding tour accessible via the **Profiles** tab.

### [Updates](#updates-8)

* [Docker Compose v5.1.1](https://github.com/docker/compose/releases/tag/v5.1.1)
* [Docker Agent v1.34.0](https://github.com/docker/docker-agent/releases/tag/v1.34.0)
* [Docker Scout CLI v1.20.3](https://github.com/docker/scout-cli/releases/tag/v1.20.3)
* [Docker Model v1.1.25](https://github.com/docker/model-runner/releases/tag/v1.1.25)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes)

#### [For all platforms](#for-all-platforms-8)

* Docker Model Runner now supports Qwen3.5.
* With the new **Logs (Beta)** view, you can now filter container logs by Compose stack.
* Improved interaction with **Settings** while the Docker engine or Kubernetes is starting or stopping.
* Fixed a bug where random UDP port bindings reported port `0` instead of the actual assigned port.
* Fixed an issue with the Docker Desktop shortcut not reopening the Dashboard when Docker Desktop was already running.
* Fixed an issue where the **Add to existing profile** dialog showed profiles that already contained all selected MCP servers in the dropdown.

#### [For Mac](#for-mac-7)

* Fixed intermittent `exec format error` when starting amd64 containers on Apple Silicon Macs due to a race condition between Rosetta `binfmt` registration and `virtiofs` device availability.

#### [For Windows](#for-windows-7)

* Fixed Hyper-V being silently re-enabled on every EXE upgrade for WSL 2 users.
* Fixed an MSI installer bug where Docker Desktop processes could be left running after uninstall.
* Fixed an issue on Windows where installations or updates using `--installation-dir` would fail due to the installer archive being extracted into the custom installation directory.
* Improved Docker Desktop startup time on Windows by several seconds when using WSL 2.
* Fixed a bug on the **Models** > **Logs** screen which caused `docker-model` processes to accumulate on Windows each time the screen was visited.

### [Security](#security-3)

* Addressed [CVE-2026-33990](https://www.cve.org/cverecord?id=CVE-2026-33990), SSRF in Docker Model Runner OCI Registry Client

## [4.66.1](#4661)

*2026-03-26*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/222799/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/222799/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/222799/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/222799/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/222799/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/222799/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/222799/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/222799/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/222799/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/222799/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/222799/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/222799/checksums.txt))

### [Updates](#updates-9)

* [Docker Engine v29.3.1](https://docs.docker.com/engine/release-notes/29/#2931)

## [4.66.0](#4660)

*2026-03-23*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/222299/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/222299/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/222299/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/222299/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/222299/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/222299/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/222299/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/222299/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/222299/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/222299/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/222299/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/222299/checksums.txt))

### [Updates](#updates-10)

* [Docker Engine v29.3.0](https://docs.docker.com/engine/release-notes/29/#2930)
* [NVIDIA Container Toolkit v1.19.0](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.19.0)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-1)

#### [For all platforms](#for-all-platforms-9)

* Gordon improvements:

  * Provides pre-filled prompts when deeplinking from command-line failure hints.
  * Prevents Docker Hub rate limiting by authenticating before making requests.

* Fixed a Kubernetes pod discovery hang when the kube context is broken or unreachable.

* Fixed a terminal crash caused by an undefined dimensions error during terminal resize.

* Fixed volume backup export error handling for file, image, and registry export operations.

#### [For Windows](#for-windows-8)

* Fixed high CPU usage in the Windows API proxy caused by unnecessary process enumeration.
* Fixed the Windows MSI installer failing to update Docker Desktop. Versions between 4.56 and 4.65 need to uninstall before reinstalling version 4.66 or later. Note that uninstalling removes all associated data.

## [4.65.0](#4650)

*2026-03-16*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/221669/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/221669/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/221669/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/221669/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/221669/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/221669/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/221669/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/221669/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/221669/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/221669/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/221669/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/221669/checksums.txt))

### [New](#new-5)

* Added a new **Logs** view where you can explore logs from all sources in one unified view. (Beta)
* Gordon hints now appear when `docker build`, `docker run`, or `docker compose` commands fail, offering contextual suggestions.
* Community MCP servers now support OAuth authentication directly in the UI.
* Added the [`docker dhi` CLI plugin](https://github.com/docker-hardened-images/dhictl) for managing Docker Hardened Images.

### [Updates](#updates-11)

* [Docker Scout CLI v1.20.1](https://github.com/docker/scout-cli/releases/tag/v1.20.1)
* [Docker Agent v1.29.0](https://github.com/docker/docker-agent/releases/tag/v1.29.0)
* [Docker Buildx v0.32.1](https://github.com/docker/buildx/releases/tag/v0.32.1)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-2)

#### [For all platforms](#for-all-platforms-10)

* Kubernetes now defaults to kind for new clusters.
* Fixed update progress bar not resuming correctly.

#### [For Windows](#for-windows-9)

* Improved startup time by skipping docker-users group check when using WSL2 backend.

### [Known issues](#known-issues)

* The Windows MSI installer cannot update an existing Docker Desktop installation when the current version is between 4.56 and 4.65. As a workaround, uninstall the existing version before reinstalling the latest version. Note that uninstalling removes all associated data.

## [4.64.0](#4640)

*2026-03-11*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/221278/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/221278/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/221278/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/221278/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/221278/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/221278/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/221278/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/221278/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/221278/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/221278/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/221278/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/221278/checksums.txt))

### [Updates](#updates-12)

* [Docker Compose v5.1.0](https://github.com/docker/compose/releases/tag/v5.1.0)
* [Docker Scout CLI v1.20.0](https://github.com/docker/scout-cli/releases/tag/v1.20.0)
* [Docker Agent v1.27.1](https://github.com/docker/docker-agent/releases/tag/v1.27.1)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-3)

#### [For all platforms](#for-all-platforms-11)

* Fixed a bug in MCP Toolkit where disabling all tools in a profile would enable all tools.
* Fixed the `docker ai` command stopping after a Docker Agent update.
* Fixed Gordon session title flickering when hover buttons appeared.
* Improved Gordon summary rendering and reduced narrative verbosity.
* Fixed a bug where `docker ai` CLI commands did not correctly shell out to Docker Agent.
* Fixed the **OAuth** tab in Docker MCP Toolkit not showing entries from all catalogs.
* Improved MCP Catalog search.
* Fixed the **Build logs** tab not retaining search terms and filters when switching tabs.
* Fixed Kind container startup to be more reliable.

#### [For Mac](#for-mac-8)

* Improved update error reporting with more descriptive diagnostics.
* Improved update reliability by preparing the updated `Docker.app` under `Application Support` instead of `/tmp`.

### [Known issues](#known-issues-1)

* The Windows MSI installer cannot update an existing Docker Desktop installation when the current version is between 4.56 and 4.65. As a workaround, uninstall the existing version before reinstalling the latest version. Note that uninstalling removes all associated data.

## [4.63.0](#4630)

*2026-03-02*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/220185/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/220185/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/220185/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/220185/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/220185/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/220185/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/220185/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/220185/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/220185/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/220185/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/220185/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/220185/checksums.txt))

### [New](#new-6)

* Added SLSA v1 provenance support in the **Builds** view.

### [Updates](#updates-13)

* [Kubernetes v1.34.3](https://github.com/kubernetes/kubernetes/releases/tag/v1.34.3)
* Linux kernel `v6.12.72`

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-4)

#### [For all platforms](#for-all-platforms-12)

* Enhanced the proxy settings UI and added a separate proxy for containers.
* Fixed an issue where community registry MCP catalogs failed to load when a server's config object contained `"required": null`.
* Fixed an issue where `mcp-gateway` would hang when fetching secrets from the Secrets Engine while the Docker Desktop VM was in Resource Saver mode.
* Rebranded "Docker AI" references to "Gordon".

#### [For Windows](#for-windows-10)

* Improved startup time on Windows.

### [Known issues](#known-issues-2)

* The Windows MSI installer cannot update an existing Docker Desktop installation when the current version is between 4.56 and 4.65. As a workaround, uninstall the existing version before reinstalling the latest version. Note that uninstalling removes all associated data.

## [4.62.0](#4620)

*2026-02-23*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/219486/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/219486/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/219486/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/219486/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/219486/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/219486/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/219486/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/219486/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/219486/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/219486/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/219486/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/219486/checksums.txt))

### [New](#new-7)

* With Docker MCP Toolkit, you can now use [profiles](https://docs.docker.com/ai/mcp-catalog-and-toolkit/profiles/) to organize your MCP servers into named collections. You can also create custom catalogs — curated collections of servers for your team or organization.

### [Updates](#updates-14)

* Linux kernel `v6.12.69`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-9)

#### [For all platforms](#for-all-platforms-13)

* Fixed an issue where background update checks did not respect the **Automatically check for updates** setting when disabled. Fixes [docker/for-mac#3908](https://github.com/docker/for-mac/issues/3908).

#### [For Mac](#for-mac-9)

* Added support for vLLM Metal in Docker Model Runner.

#### [For Linux](#for-linux-2)

* Fixed a networking crash on QEMU 10.2.0 and later.

### [Security](#security-4)

* Addressed [CVE-2026-2664](https://www.cve.org/cverecord?id=CVE-2026-2664), out of bounds read in grpcfuse kernel module.
* Addressed [CVE-2026-28400](https://www.cve.org/cverecord?id=CVE-2026-28400), runtime flag injection in Docker Model Runner.

### [Known issues](#known-issues-3)

* The Windows MSI installer cannot update an existing Docker Desktop installation when the current version is between 4.56 and 4.65. As a workaround, uninstall the existing version before reinstalling the latest version. Note that uninstalling removes all associated data.

## [4.61.0](#4610)

*2026-02-18*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/219004/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/219004/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/219004/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/219004/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/219004/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/219004/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/219004/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/219004/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/219004/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/219004/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/219004/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/219004/checksums.txt))

### [New](#new-8)

* You can now customize the left-hand navigation to show only the tabs that matter to you, and hide the ones that don’t.

### [Updates](#updates-15)

* Linux kernel `v6.12.68`
* [Docker Engine v29.2.1](https://docs.docker.com/engine/release-notes/29/#2921)
* Docker Sandbox `v0.12.0`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-10)

#### [For all platforms](#for-all-platforms-14)

* Docker Sandboxes:

  * Added automated image caching to prevent re-downloading images unnecessarily.
  * Added Shell mode for blank coding agent sandboxes.
  * Added support for OpenCode.
  * Added support for mounting multiple workspaces.
  * Added experimental Linux support (single user only, UID 1000).
  * Added support for running in WSL 2.
  * Sandboxes now start in the current working directory if no path is provided.

### [Known issues](#known-issues-4)

* The Windows MSI installer cannot update an existing Docker Desktop installation when the current version is between 4.56 and 4.65. As a workaround, uninstall the existing version before reinstalling the latest version. Note that uninstalling removes all associated data.

## [4.60.1](#4601)

*2026-02-10*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/218372/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/218372/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/218372/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/218372/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/218372/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/218372/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/218372/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/218372/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/218372/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/218372/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/218372/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/218372/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-11)

#### [For all platforms](#for-all-platforms-15)

* Fixed a rare issue that crashed the Docker Desktop Dashboard after sign-in.

## [4.60.0](#4600)

*2026-02-09*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/218231/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/218231/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/218231/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/218231/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/218231/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/218231/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/218231/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/218231/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/218231/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/218231/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/218231/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/218231/checksums.txt))

### [New](#new-9)

* Added a new `docker desktop diagnose` command to gather diagnostics.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-12)

#### [For all platforms](#for-all-platforms-16)

* Fixed `ping6 host.docker.internal`.

* Enabled landlock LSM.

* Docker Sandboxes improvements:

  * Improved agent system prompt with network access documentation
  * Fixed Gemini API key injection
  * Sandboxes now block `console.anthropic.com/claude.ai` in proxy default rules
  * Fix CLI help text for `run <agent> --help`
  * Improved terminal size handling

### [Known issues](#known-issues-5)

* The Windows MSI installer cannot update an existing Docker Desktop installation when the current version is between 4.56 and 4.65. As a workaround, uninstall the existing version before reinstalling the latest version. Note that uninstalling removes all associated data.

## [4.59.1](#4591)

*2026-02-03*

> Download Docker Desktop
>
> * [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/217750/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/217750/checksums.txt))
> * [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/217750/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/217750/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-13)

#### [For Mac](#for-mac-10)

* Fixed an issue where CPU usage could spike at regular intervals. Fixes [docker/for-mac#7839](https://github.com/docker/for-mac/issues/7839).

## [4.59.0](#4590)

*2026-02-02*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/217644/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/217644/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/217644/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/217644/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/217644/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/217644/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/217644/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/217644/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/217644/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/217644/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/217644/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/217644/checksums.txt))

### [Updates](#updates-16)

* Linux kernel `v6.12.67`
* [Docker Compose v5.0.2](https://github.com/docker/compose/releases/tag/v5.0.2)
* Docker Sandbox `v0.10.1`
* [Docker Buildx v0.31.1](https://github.com/docker/buildx/releases/tag/v0.31.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-14)

#### [For all platforms](#for-all-platforms-17)

* Added Neo4j as a known publisher to the Docker MCP Catalog.
* Fixed an issue where the **Models** tab would crash when displaying requests made via the Anthropic Messages API.

#### [For Mac](#for-mac-11)

* Fixed an issue where shared file permissions could be unintentionally modified when using DockerVMM. Fixes [docker/for-mac#7830](https://github.com/docker/for-mac/issues/7830).

#### [For Windows](#for-windows-11)

* Fixed an issue where container secrets injection could fail with `docker-pass`.
* Temporarily disabled VHDX compaction for the WSL data disk to improve stability.

### [Security](#security-5)

* Fixed a security issue in enhanced container isolation where Docker socket mount permissions could be bypassed when using the `--use-api-socket` flag.

## [4.58.1](#4581)

*2026-01-29*

> Download Docker Desktop
>
> * [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/217134/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/217134/checksums.txt))
> * [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/217134/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/217134/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-15)

#### [For Mac](#for-mac-12)

* Fixed an issue where CPU usage could spike at regular intervals. Fixes [docker/for-mac#7839](https://github.com/docker/for-mac/issues/7839).

## [4.58.0](#4580)

*2026-01-26*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/216728/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/216728/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/216728/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/216728/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/216728/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/216728/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/216728/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/216728/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/216728/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/216728/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/216728/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/216728/checksums.txt))

### [New](#new-10)

* A new version of [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) is now available on Docker Desktop. It provides a secure, isolated, microVM-based environment for running coding agents.

### [Updates](#updates-17)

* Linux kernel `v6.12.65`
* [Credential helpers v0.9.5](https://github.com/docker/docker-credential-helpers/releases/tag/v0.9.5)
* [Docker Engine v29.1.5](https://docs.docker.com/engine/release-notes/29/#2915)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-16)

#### [For all platforms](#for-all-platforms-18)

* Docker Model Runner now exposes an [Anthropic-compatible API](https://docs.docker.com/ai/model-runner/api-reference/#anthropic-compatible-api).
* Docker Desktop now supports UTF-8 BOM for `admin-settings.json` and `registry.json`.
* Fixed an issue where admin settings incorrectly changed user proxy settings after a restart.

> Important
>
> Starting with Docker Desktop version 4.59, installing an update from the tray menu will proceed without opening the Docker Desktop Dashboard.

#### [For Mac](#for-mac-13)

* Fixed a bug where shared file permissions could be modified inadvertently while using DockerVMM on macOS. Fixes [docker/for-mac#7830](https://github.com/docker/for-mac/issues/7830).

#### [For Windows](#for-windows-12)

* Fixed an issue where the installer failed because of special ACLs set on `ProgramData`.

### [Security](#security-6)

* Updated Kubernetes images to address CVEs.

  * Kind:

    * `docker/desktop-containerd-registry-mirror:v0.0.3`
    * `docker/desktop-cloud-provider-kind:v0.5.0`

  * Kubeadm:

    * `docker/desktop-vpnkit-controller:v4.0`
    * `docker/desktop-storage-provisioner:v3.0`

* The `kind` dependency image `envoyproxy/envoy` was upgraded from v1.32.6 to v1.36.4. If you mirror `kind` images, ensure your mirrors are updated.

## [4.57.0](#4570)

*2026-01-19*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/215387/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/215387/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/215387/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/215387/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/215387/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/215387/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/215387/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/215387/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/215387/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/215387/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/215387/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/215387/checksums.txt))

### [Security](#security-7)

* Fixed [CVE-2025-14740](https://www.cve.org/cverecord?id=CVE-2025-14740) where the Docker Desktop for Windows installer contained multiple incorrect permission assignment vulnerabilities in the handling of the `C:\ProgramData\DockerDesktop` directory.

### [New](#new-11)

* Docker Desktop now has a new issue tracker for all platforms at <https://github.com/docker/desktop-feedback>. Relevant, actively discussed issues from the previous platform-specific trackers will be migrated.

### [Updates](#updates-18)

* [Docker Compose v5.0.1](https://github.com/docker/compose/releases/tag/v5.0.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-17)

#### [For all platforms](#for-all-platforms-19)

* Improved alignment of the Ask Gordon streaming indicator so it stays in sync with content on large screens.
* Fixed a bug where `docker debug` failed on containers started with environment variables but no '='. For example, `docker run -e NONEXISTENT_ENV_VAR`.

## [4.56.0](#4560)

*2026-01-12*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/214940/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/214940/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/214940/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/214940/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/214940/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/214940/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/214940/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/214940/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/214940/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/214940/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/214940/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/214940/checksums.txt))

### [New](#new-12)

* Docker Desktop now includes Docker Compose v5 which introduces a new official Go SDK. This SDK provides a comprehensive API that lets you integrate Compose functionality directly into your applications, allowing you to load, validate, and manage multi-container environments without relying on the Compose CLI. For more information, see the [Compose SDK docs](https://docs.docker.com/compose/compose-sdk/).

### [Updates](#updates-19)

* [containerd v2.2.1](https://github.com/containerd/containerd/releases/tag/v2.2.1)
* [Docker Compose v5.0.0](https://github.com/docker/compose/releases/tag/v5.0.0)
* [Docker Agent v1.18.6](https://github.com/docker/docker-agent/releases/tag/v1.18.6)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-18)

#### [For all platforms](#for-all-platforms-20)

* Fixed a panic in filesharing tests when containers don't have an IP address immediately after starting.
* Added support for custom DNS entries in the LinuxKit VM with the `ExtraDNSEntries` configuration field.

#### [For Windows](#for-windows-13)

* Fixed a bug on Windows where removing the state directory would fail because log files were still open.

* Fixed installations from the Microsoft Store wrongly advertizing a new update.

* Fixed a crash when running `/sbin/ldconfig` in `ubuntu:22.04` ARM64 containers by upgrading QEMU from 8.1.5 to 10.0.4. This resolves a known issue reported in [docker/for-win#15004](https://github.com/docker/for-win/issues/15004).

  > Note
  >
  > When running under ARM64 emulation, some `amd64` Go binaries built with older Go versions may still segfault. To avoid this, rebuild affected binaries using Go 1.25.4 or later. For details, see [golang/go#69255](https://github.com/golang/go/issues/69255) and the corresponding [Go commit](https://github.com/golang/go/commit/bf95b767394eb5643265f44c7b98bdbb85b897ce).

#### [For Linux](#for-linux-3)

* Fixed Kubernetes `hostPath` volume mounts failing on Linux hosts. Fixes [docker/desktop-linux#12](https://github.com/docker/desktop-linux/issues/12).

## [4.55.0](#4550)

*2025-12-16*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/213807/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/213807/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/213807/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/213807/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/213807/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/213807/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/213807/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/213807/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/213807/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/213807/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/213807/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/213807/checksums.txt))

### [Updates](#updates-20)

* [Docker Engine v29.1.3](https://docs.docker.com/engine/release-notes/29/#2913)
* [Docker Agent v1.15.1](https://github.com/docker/docker-agent/releases/tag/v1.15.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-19)

#### [For all platforms](#for-all-platforms-21)

* Fixed an issue that caused Docker Desktop to get stuck during startup.
* Improved the error message when the `daemon.json` is invalid.
* Fixed performance issues on every keystroke within a long Ask Gordon session.
* Fixed an issue that prevented Kubernetes in kubeadm mode from starting up when an organization has configured Registry Access Management to block Docker Hub.

> Important
>
> Wasm workloads will be deprecated and removed in a future Docker Desktop release.

## [4.54.0](#4540)

*2025-12-04*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/212467/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/212467/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/212467/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/212467/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/212467/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/212467/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/212467/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/212467/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/212467/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/212467/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/212467/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/212467/checksums.txt))

### [New](#new-13)

* Added support for vLLM in Docker Model Runner on Windows with WSL2 and NVIDIA GPUs.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-20)

#### [For Mac](#for-mac-14)

* Fixed a bug where `/dev/shm` did not have enough permission for containers to write into. Fixes [docker/for-mac#7804](https://github.com/docker/for-mac/issues/7804).

### [Upgrades](#upgrades)

* [Docker Buildx v0.30.1](https://github.com/docker/buildx/releases/tag/v0.30.1)
* [Docker Engine v29.1.2](https://docs.docker.com/engine/release-notes/29/#2912)
* [Runc v1.3.4](https://github.com/opencontainers/runc/releases/tag/v1.3.4)
* [Docker Model Runner CLI v1.0.2](https://github.com/docker/model-runner/releases/tag/cmd%2Fcli%2Fv1.0.2)

### [Security](#security-8)

* Added a security patch to address [CVE-2025-13743](https://www.cve.org/cverecord?id=CVE-2025-13743) where Docker Desktop diagnostics bundles were found to include expired Hub PATs in log output due to error object serialization.

## [4.53.0](#4530)

*2025-11-27*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/211793/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/211793/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/211793/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/211793/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/211793/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/211793/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/211793/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/211793/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/211793/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/211793/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/211793/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/211793/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-21)

#### [For all platforms](#for-all-platforms-22)

* Fixed an issue where the Support Diagnostics tooling inadvertently captured expired Docker Hub authorization bearer tokens.

### [Security](#security-9)

* Added security patches to address CVEs [2025-52565](https://github.com/opencontainers/runc/security/advisories/GHSA-9493-h29p-rfm2), [2025-52881](https://github.com/opencontainers/runc/security/advisories/GHSA-cgrx-mc8f-2prm), and [2025-31133](https://github.com/opencontainers/runc/security/advisories/GHSA-qw9x-cqr3-wc7r) when using [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation).

## [4.52.0](#4520)

*2025-11-20*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/210994/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/210994/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/210994/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/210994/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/210994/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/210994/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/210994/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/210994/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/210994/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/210994/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/210994/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/210994/checksums.txt))

### [New](#new-14)

* Added new port binding settings to Docker Desktop. This can also be controlled by administrators via Settings Management using the `admin-settings.json` file.
* Added a new Docker Model Runner command. With `docker model purge` you can remove all your models.

### [Upgrades](#upgrades-1)

* [Docker Engine v29.0.0](https://docs.docker.com/engine/release-notes/29/#2900)
* [Docker Model Runner v1.0.3](https://github.com/docker/model-runner/releases/tag/v1.0.3)
* [Docker Model Runner CLI v1.0.0](https://github.com/docker/model-runner/releases/tag/cmd%2Fcli%2Fv1.0.0)
* Docker MCP plugin `v0.28.0`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-22)

#### [For all platforms](#for-all-platforms-23)

* Docker MCP Toolkit improvements:

  * Amazon Q client support
  * OAuth DCR (Dynamic Client Registration) with Docker Engine
  * Create MCP profiles using the CLI

* Docker Model Runner improvements:

  * You can now skip the `/engines` prefix for [Docker Model Runner's OpenAI API endpoint](https://docs.docker.com/ai/model-runner/api-reference/#rest-api-examples) `curl http://localhost:12434/v1/models`.
  * You can now skip the `ai/` prefix for the models [published on Docker Hub with](https://hub.docker.com/u/ai) `docker model pull`.
  * Downloads are now resumed when they get interrupted.

#### [For Windows](#for-windows-14)

* Fixed an issue with Kerberos/NTLM proxy sign in.

## [4.51.0](#4510)

*2025-11-13*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/210443/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/210443/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/210443/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/210443/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/210443/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/210443/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/210443/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/210443/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/210443/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/210443/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/210443/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/210443/checksums.txt))

### [New](#new-15)

* You can now set up your Kubernetes resources from the **Kubernetes** view. This new view also provides a real-time display of your pods, services, and deployments.

### [Upgrades](#upgrades-2)

* [Docker Engine v28.5.2](https://docs.docker.com/engine/release-notes/28/#2852)
* Linux kernel `v6.12.54`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-23)

#### [For all platforms](#for-all-platforms-24)

* Kind now only pulls required dependency images if they are not available locally.

## [4.50.0](#4500)

*2025-11-06*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/209931/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/209931/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/209931/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/209931/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/209931/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/209931/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/209931/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/209931/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/209931/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/209931/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/209931/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/209931/checksums.txt))

### [New](#new-16)

* [Dynamic MCP](https://docs.docker.com/ai/mcp-catalog-and-toolkit/dynamic-mcp/)(Experimental) is now available in Docker Desktop .
* Introduced a new Welcome Survey to improve onboarding. New users can now provide information to help tailor their Docker Desktop experience.

### [Upgrades](#upgrades-3)

* [Docker Compose v2.40.3](https://github.com/docker/compose/releases/tag/v2.40.3)
* [NVIDIA Container Toolkit v1.18.0](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.18.0)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-24)

#### [For all platforms](#for-all-platforms-25)

* Docker Desktop now detects and attempts to avoid clashes between the "Docker subnet" and physical networks using RFC1918 addresses. For example if the host has a non-default route which overlaps with `192.168.65.0/24` then an alternative network will be chosen automatically. You can still override the choice as before via Docker Desktop settings and admin settings.
* Docker Desktop no longer treats Stargz Snapshotter failures as fatal. If a failure occurs, Docker Desktop continues to run without the Stargz Snapshotter.
* Ask Gordon no longer displays images with user provided URLs.
* Ask Gordon now asks for confirmation before running all built-in and all user added MCP tools.

## [4.49.0](#4490)

*2025-10-23*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/208700/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/208700/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/208700/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/208700/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/208700/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/208700/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/208700/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/208700/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/208700/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/208700/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/208700/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/208700/checksums.txt))

> Important
>
> Support for Windows 10 21H2 (19044) and 11 22H2 (22621) has ended. Installing Docker Desktop will require Windows 10 22H2 (19045) or Windows 11 23H2 (22631) in the next release.

### [Security](#security-10)

* Fixed [CVE-2025-9164](https://www.cve.org/cverecord?id=CVE-2025-9164) where the Docker Desktop for Windows installer was vulnerable to DLL hijacking due to insecure DLL search order. The installer searches for required DLLs in the user's Downloads folder before checking system directories, allowing local privilege escalation through malicious DLL placement.

### [New](#new-17)

* [Docker Agent](https://docs.docker.com/ai/docker-agent/) is now available through Docker Desktop.
* [Docker Debug](/reference/cli/docker/debug/) is now free for all users.

### [Upgrades](#upgrades-4)

* [Docker Engine v28.5.1](https://docs.docker.com/engine/release-notes/28/#2851)
* [Docker Compose v2.40.2](https://github.com/docker/compose/releases/tag/v2.40.2)
* [NVIDIA Container Toolkit v1.17.9](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.17.9)
* Docker Debug `v0.0.45`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-25)

#### [For all platforms](#for-all-platforms-26)

* Fixed an issue where Docker Desktop used an expired proxy password while waiting for the user to enter a new one.
* Fixed a 'chown' error shown on startup with Docker Debug.
* Fixed a bug that caused some forwarded UDP ports to hang.

#### [For Mac](#for-mac-15)

* Fixed Kubernetes startup hanging when another Kubernetes context was active. Fixes <https://github.com/docker/for-mac/issues/7771>.
* If a Rosetta install is cancelled or fails, Rosetta will be disabled in Docker Desktop.
* Minimum OS version to install or update Docker Desktop on macOS is now macOS Sonoma (version 14) or later.

## [4.48.0](#4480)

*2025-10-09*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/207573/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/207573/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/207573/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/207573/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/207573/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/207573/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/207573/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/207573/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/207573/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/207573/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/207573/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/207573/checksums.txt))

> Important
>
> Support for macOS 13 has ended. Installing Docker Desktop will require macOS 14 in the next release.

### [New](#new-18)

* You can now specify PAC files and Embedded PAC scripts with installer flags for [macOS](https://docs.docker.com/desktop/setup/install/mac-install/#proxy-configuration) and [Windows](https://docs.docker.com/desktop/setup/install/windows-install/#proxy-configuration).
* Administrators can set proxy settings via [macOS configuration profiles](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#macos-configuration-profiles-method-recommended).

### [Upgrades](#upgrades-5)

* [Docker Compose v2.40.0](https://github.com/docker/compose/releases/tag/v2.40.0)
* [Docker Buildx v0.29.1](https://github.com/docker/buildx/releases/tag/v0.29.1)
* [Docker Engine v28.5.1](https://docs.docker.com/engine/release-notes/28/#2851)
* Docker MCP plugin `v0.22.0`
* [Docker Model CLI v0.1.42](https://github.com/docker/model-cli/releases/tag/v0.1.42)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-26)

#### [For all platforms](#for-all-platforms-27)

* Fixed an issue where kind cluster state is sometimes reset when Desktop restarts. Fixes [docker/for-mac#77445](https://github.com/docker/for-mac/issues/7745).
* Removed the obsolete `mcp` key to align with the latest VS Code MCP server changes.
* Update credential helpers to [v0.9.4](https://github.com/docker/docker-credential-helpers/releases/tag/v0.9.4).
* Fixed an issue where Docker Desktop used an expired proxy password while waiting for the user to enter a new one.
* Fixed a bug which caused Docker Desktop to regularly create new processes with Docker CLI tools under certain conditions. Fixes [docker/for-win#14944](https://github.com/docker/for-win/issues/14944).
* Fixed a bug which caused models to not be configured for embeddings with Docker Model Runner via Compose. To specify that a model should be configured for embeddings, you must explicitly add the `--embeddings` runtime flag as described in [AI Models in Docker Compose](https://docs.docker.com/ai/compose/models-and-compose/#model-configuration-options). Fixes [docker/model-runner#166](https://github.com/docker/model-runner/issues/166).

#### [For Windows](#for-windows-15)

* Removed the `HKLM\SOFTWARE\Docker Inc.\Docker\1.0` registry key. Look for `docker.exe` in the path to find out where Docker Desktop is installed instead.
* Fixed startup in WSL 2 mode when IPv6 has been disabled.

## [4.47.0](#4470)

*2025-09-25*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/206054/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/206054/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/206054/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/206054/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/206054/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/206054/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/206054/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/206054/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/206054/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/206054/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/206054/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/206054/checksums.txt))

### [Security](#security-11)

* Fixed [CVE-2025-10657](https://www.cve.org/CVERecord?id=CVE-2025-10657) where the Enhanced Container Isolation [Docker Socket command restrictions](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/#command-restrictions) feature was not working properly in Docker Desktop 4.46.0 only (the configuration for it was being ignored).

### [New](#new-19)

* Added dynamic MCP server discovery and support to Docker's MCP catalog.
* With Enhanced Container Isolation, administrators can now block `docker plugin` and `docker login` commands in containers with Docker socket mounts.
* Added a new Docker Model Runner command. With `docker model requests` you can fetch requests and responses.

### [Upgrades](#upgrades-6)

* [Docker Compose v2.39.4](https://github.com/docker/compose/releases/tag/v2.39.4)

* [Kubernetes v1.34.1](https://github.com/kubernetes/kubernetes/releases/tag/v1.34.1)

  * [CNI plugins v1.7.1](https://github.com/containernetworking/plugins/releases/tag/v1.7.1)
  * [cri-tools v1.33.0](https://github.com/kubernetes-sigs/cri-tools/releases/tag/v1.33.0)
  * [cri-dockerd v0.3.20](https://github.com/Mirantis/cri-dockerd/releases/tag/v0.3.20)

* Docker Debug `v0.0.44`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-27)

#### [For all platforms](#for-all-platforms-28)

* You can now search for MCP servers more easily with filters, sorting, and improved search functionality.
* Docker Debug no longer hangs when debugging containers that have environment variables set to an empty value.
* Enhanced Docker Model Runner with rich response rendering in the CLI, conversational context in the Docker Desktop Dashboard, and resumable downloads.

#### [For Mac](#for-mac-16)

* Removed the `com.apple.security.cs.allow-dyld-environment-variables` entitlement which allow a signed, arbitrary dynamic library to be loaded with Docker Desktop via the `DYLD_INSERT_LIBRARIES` environment variable.
* Fixed a regression where config profile sign-in enforcement broke for some customer environments.
* Fixed a bug that sometimes caused the `docker model package` command to hang when writing to the local content store (without the `--push` flag).
* Fixed a bug where containers started with the restart policy `unless-stopped` were never restarted. Fixes [docker/for-mac#7744](https://github.com/docker/for-mac/issues/7744).

#### [For Windows](#for-windows-16)

* Fixed the Goose MCP client connection on Windows for the Docker MCP Toolkit.
* Addressed an issue with the "Skipping integration" of a WSL distro option, after a failed integration attempt.
* Fixed a bug that sometimes caused the `docker model package` command to hang when writing to the local content store (without the `--push` flag).

## [4.46.0](#4460)

*2025-09-11*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/204649/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/204649/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/204649/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/204649/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/204649/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/204649/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/204649/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/204649/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/204649/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/204649/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/204649/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/204649/checksums.txt))

### [New](#new-20)

* Added a new Learning center walkthrough for Docker MCP Toolkit and other onboarding improvements.
* Administrators can now control [PAC configurations with Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/#proxy-settings).
* The update experience has been redesigned to make it easier to understand and manage updates for Docker Desktop and its components.

### [Upgrades](#upgrades-7)

* [Docker Buildx v0.28.0](https://github.com/docker/buildx/releases/tag/v0.28.0)
* [Docker Engine v28.4.0](https://docs.docker.com/engine/release-notes/28/#2840)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-28)

#### [For all platforms](#for-all-platforms-29)

* With the Docker CLI, you can now set the `GODEBUG` environment variable when the key-value pair (`"GODEBUG":"..."`) exists inside the Docker context metadata. This means certificates that have negative serial numbers in the CLI binaries are supported by default.
* Updated the Docker Subscription Service Agreement link to point to the latest version.

#### [For Mac](#for-mac-17)

* Improved the security of Docker Model Runner by enabling sandboxing of the `llama.cpp` inference processes.
* Fixed a bug which caused Docker Desktop to start slowly and appear frozen. Fixes [docker/for-mac#7671](https://github.com/docker/for-mac/issues/7671).

#### [For Windows](#for-windows-17)

* Improved the security of Docker Model Runner by enabling sandboxing of the `llama.cpp` inference processes.

#### [For Linux](#for-linux-4)

* Fixed a path issue in the RHEL post-uninstall sequence.

## [4.45.0](#4450)

*2025-08-28*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/203075/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/203075/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/203075/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/203075/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/203075/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/203075/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/203075/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/203075/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/203075/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/203075/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/203075/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/203075/checksums.txt))

### [New](#new-21)

* [Docker Model Runner](https://docs.docker.com/ai/model-runner/) is now generally available.

### [Upgrades](#upgrades-8)

* [Docker Compose v2.39.2](https://github.com/docker/compose/releases/tag/v2.39.2)
* [Docker Buildx v0.27.0](https://github.com/docker/buildx/releases/tag/v0.27.0)
* [Docker Scout CLI v1.18.3](https://github.com/docker/scout-cli/releases/tag/v1.18.3)
* [Docker Engine v28.3.3](https://docs.docker.com/engine/release-notes/28/#2833)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-29)

#### [For all platforms](#for-all-platforms-30)

* Fixed a bug that caused the `com.docker.diagnose` to crash when uploading a diagnostics bundle behind a proxy that requires authentication.
* The `kind` dependency image `envoyproxy/envoy` was upgraded from v1.32.0 to v1.32.6. If you mirror `kind` images, ensure your mirrors are updated.

#### [For Mac](#for-mac-18)

* Fixed a bug that caused Docker Desktop to crash after the laptop woke from sleep. Fixes [docker/for-mac#7741](https://github.com/docker/for-mac/issues/7741).
* Fixed an issue where the VM would sometimes fail with the error **The virtual machine stopped unexpectedly.**
* Fixed a bug that would break port mappings when a container was connected to or disconnected from a network after it was started. Fixes [docker/for-mac#7693](https://github.com/docker/for-mac/issues/7693).

#### [For Windows](#for-windows-18)

* Fixed a bug that prevented CLI plugins from being deployed to `~/.docker/cli-plugins` by default when users lacked the correct permissions.
* Fixed a bug where relocating the WSL data distribution would fail if the `docker-desktop` distribution was not present.
* Fixed a typo in the WSL install URL in the Docker Desktop Dashboard.
* Fixed an issue where certain WSL distros would fail to integrate. Fixes [docker/for-win#14686](https://github.com/docker/for-win/issues/14686)

## [4.44.3](#4443)

*2025-08-20*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/202357/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/202357/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/202357/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/202357/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/202357/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/202357/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/202357/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/202357/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/202357/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/202357/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/202357/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/202357/checksums.txt))

### [Security](#security-12)

* Fixed [CVE-2025-9074](https://www.cve.org/CVERecord?id=CVE-2025-9074) where a malicious container running on Docker Desktop could access the Docker Engine and launch additional containers without requiring the Docker socket to be mounted. This could allow unauthorized access to user files on the host system. Enhanced Container Isolation (ECI) does not mitigate this vulnerability.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-30)

* Fixed a bug which caused the Docker Offload dialog to block users from accessing the dashboard.

## [4.44.2](#4442)

*2025-08-15*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/202017/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/202017/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/202017/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/202017/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/202017/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/202017/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/202017/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/202017/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/202017/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/202017/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/202017/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/202017/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-31)

* Adds [Docker Offload](https://docs.docker.com/offload/) to the **Beta features** settings tab and includes updates to support [Docker Offload Beta](https://www.docker.com/products/docker-offload/).

## [4.44.1](#4441)

*2025-08-13*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/201842/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/201842/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/201842/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/201842/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/201842/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/201842/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/201842/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/201842/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/201842/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/201842/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/201842/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/201842/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-32)

#### [For all platforms](#for-all-platforms-31)

* Fixed an issue found in version 4.44.0 that caused startup to fail when `vpnkit` CIDR is locked without specifying a value in Desktop Settings Management.

#### [For Windows](#for-windows-19)

* Fixed an issue where volumes and containers were not visible after an upgrade from distributions using the legacy `version-pack-data` directory structure.
* Resolved a rare issue in WSL 2 where the Docker CLI failed with a **Proxy Authentication Required** error.
* Fixed a bug where CLI plugins were not deployed to `~/.docker/cli-plugins` if the user lacked execution permissions on that directory.

## [4.44.0](#4440)

*2025-08-07*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/201307/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/201307/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/201307/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/201307/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/201307/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/201307/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/201307/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/201307/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/201307/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/201307/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/201307/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/201307/checksums.txt))

### [New](#new-22)

* WSL 2 stability improvements.
* You can now inspect requests and responses to help you diagnose model-related issues in Docker Model Runner.
* Added the ability to run multiple models and receive a warning on insufficient resources. This avoids Docker Desktop freezing when using big models.
* Added new MCP clients to the MCP Toolkit: Gemini CLI, Goose.
* Introduced `--gpu` (Windows only) and `--cors` flags for `docker desktop enable model-runner`.
* Added a new `docker desktop kubernetes` command to the Docker Desktop CLI.
* You can now search for specific configuration options within **Settings**.
* Apple Virtualization is now the default VMM for better performance and QEMU Virtualization is removed. See [blog post](https://www.docker.com/blog/docker-desktop-for-mac-qemu-virtualization-option-to-be-deprecated-in-90-days/).
* Performance and stability improvements to the DockerVMM.

### [Upgrades](#upgrades-9)

* [Docker Compose v2.39.1](https://github.com/docker/compose/releases/tag/v2.39.1)
* [Docker Buildx v0.26.1](https://github.com/docker/buildx/releases/tag/v0.26.1)
* [Docker Engine v28.3.2](https://docs.docker.com/engine/release-notes/28/#2832)
* [Docker Scout CLI v1.18.2](https://github.com/docker/scout-cli/releases/tag/v1.18.2)
* [Docker Model CLI v0.1.36](https://github.com/docker/model-cli/releases/tag/v0.1.36)
* [Docker Desktop CLI v0.2.0](https://docs.docker.com/desktop/features/desktop-cli/)

### [Security](#security-13)

We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266), a critical vulnerability affecting the NVIDIA Container Toolkit in CDI mode up to version 1.17.7. Docker Desktop includes version 1.17.8, which is not impacted. However, older versions of Docker Desktop that bundled earlier toolkit versions may be affected if CDI mode was manually enabled. Upgrade to Docker Desktop 4.44 or later to ensure you're using the patched version.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-33)

#### [For all platforms](#for-all-platforms-32)

* Fixed an issue pulling images with zstd differential layers when the containerd image store is enabled.
* Fixed a bug causing containers launching with the `--restart` flag to not restart properly when using Enhanced Container Isolation.
* Improved interaction between [Kubernetes custom registry images](https://docs.docker.com/desktop/use-desktop/kubernetes/#configuring-a-custom-image-registry-for-kubernetes-control-plane-images) and Enhanced Container Isolation (ECI), so the [ECI Docker Socket image list](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/) no longer needs to be manually updated when using a custom registry for Kubernetes control plane images.
* Fixed a bug where a Docker Desktop Kubernetes cluster in kind mode fails to start after restarting Docker Desktop if the user is required to be signed in but is currently signed out.
* Fixed a bug that prevented the mounting of MCP secrets into containers when [Enhanced Container Isolation](/enterprise/security/hardened-desktop/enhanced-container-isolation/) is enabled.
* Fixed a bug preventing the use of `--publish-all` when `--publish` was already specified.
* Fixed a bug causing the **Images** view to scroll infinitely. Fixes [docker/for-mac#7725](https://github.com/docker/for-mac/issues/7725).
* Fixed a bug which caused the **Volumes** tab to be blank while in Resource Saver mode.
* Updated terms of service text on first launch.
* More robustness in parsing newly released GGUF formats.

#### [For Mac](#for-mac-19)

* Fixed disk corruption on DockerVMM when reclaiming disk space.
* Fixed regression since 4.42.0 on DockerVMM by re-introducing performance boost on general usage.
* Removed QEMU hypervisor and switched to Apple Virtualization as the new default. See [blog post](https://www.docker.com/blog/docker-desktop-for-mac-qemu-virtualization-option-to-be-deprecated-in-90-days/).
* Fixed a bug preventing Traefik from autodetecting containers' ports. Fixes [docker/for-mac#7693](https://github.com/docker/for-mac/issues/7693).
* Fixed a bug that caused port mappings to break when a container was connected to or disconnected from a network after it was started. Fixes [docker/for-mac#7693](https://github.com/docker/for-mac/issues/7693#issuecomment-3131427879).
* Removed eBPF which blocked `io_uring`. To enable `io_uring` in a container, use `--security-opt seccomp=unconfined`. Fixes [docker/for-mac#7707](https://github.com/docker/for-mac/issues/7707).
* Docker Model Runner now supports GPT OSS models.

#### [For Windows](#for-windows-20)

* Re-added `docker-users` group to the named pipe security descriptors.
* Fixed an installer crash when the current user has no `SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall` registry key.
* Fixed a bug where Docker Desktop could leak a `com.docker.build` process and fail to start. Fixed [docker/for-win#14840](https://github.com/docker/for-win/issues/14840).
* Fixed a bug that was preventing Docker Desktop Kubernetes in kind mode from starting when using WSL with `cgroups v1` and Enhanced Container Isolation (ECI) is enabled.
* Fixed a typo in the WSL installation URL in the UI.
* Docker Model Runner now supports GPT OSS models

## [4.43.2](#4432)

*2025-07-15*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/199162/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/199162/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/199162/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/199162/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/199162/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/199162/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/199162/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/199162/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/199162/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/199162/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/199162/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/199162/checksums.txt))

### [Upgrades](#upgrades-10)

* [Docker Compose v2.38.2](https://github.com/docker/compose/releases/tag/v2.38.2)
* [Docker Engine v28.3.2](https://docs.docker.com/engine/release-notes/28/#2832)
* Docker Model CLI v0.1.33

## [4.43.1](#4431)

*2025-07-04*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/198352/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/198352/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/198352/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/198352/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/198352/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/198352/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/198352/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/198352/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/198352/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/198352/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/198352/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/198352/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-34)

#### [For all platforms](#for-all-platforms-33)

* Fixed an issue that caused Docker Desktop UI to break when Ask Gordon responses contained HTML tags.
* Fixed an issue that prevented extensions from communicating with their backends.

## [4.43.0](#4430)

*2025-07-03*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/198134/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/198134/checksums.txt))
> * [Windows ARM Early Access](https://desktop.docker.com/win/main/arm64/198134/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/198134/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/198134/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/198134/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/198134/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/198134/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/198134/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/198134/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/198134/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/198134/checksums.txt))

### [New](#new-23)

* [Compose Bridge](https://docs.docker.com/compose/bridge/) is now generally available.

### [Upgrades](#upgrades-11)

* [Docker Buildx v0.25.0](https://github.com/docker/buildx/releases/tag/v0.25.0)
* [Docker Compose v2.38.1](https://github.com/docker/compose/releases/tag/v2.38.1)
* [Docker Engine v28.3.0](https://docs.docker.com/engine/release-notes/28/#2830)
* [NVIDIA Container Toolkit v1.17.8](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.17.8)

### [Security](#security-14)

* Fixed [CVE-2025-6587](https://www.cve.org/CVERecord?id=CVE-2025-6587) where sensitive system environment variables were included in Docker Desktop diagnostic logs, allowing for potential secret exposure.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-35)

#### [For all platforms](#for-all-platforms-34)

* Fixed a bug causing `docker start` to drop the container's port mappings for a container already running.
* Fixed a bug that prevented container ports to be displayed on the GUI when a container was re-started.
* Fixed a bug that caused Docker API `500 Internal Server Error for API route and version` error application start.
* The settings **Apply & restart** button is now labeled **Apply**. The VM is no longer restarted when applying changed settings.
* Fixed a bug where the disk would be corrupted if Docker is shutdown during a `fsck`.
* Fixed a bug causing an incorrect `~/.kube/config` in WSL2 when using a `kind` Kubernetes cluster.
* Return an explicit error to a Docker API / `docker` CLI command if Docker Desktop has been manually paused.
* Fixed an issue where unknown keys in Admin and Cloud settings caused a failure.

#### [For Mac](#for-mac-20)

* Removed `eBPF` which blocked `io_uring`. To enable `io_uring` in a container, use `--security-opt seccomp=unconfined`. Fixes [docker/for-mac#7707](https://github.com/docker/for-mac/issues/7707).

#### [For Windows](#for-windows-21)

* Fixed an issue that caused the Docker Desktop installer to crash when the current user has no `SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall` registry key.
* Fixed a bug where Docker Desktop could leak a `com.docker.build` process and fail to start. Fixes [docker/for-win#14840](https://github.com/docker/for-win/issues/14840)

### [Known issues](#known-issues-6)

#### [For all platforms](#for-all-platforms-35)

* `docker buildx bake` will not build images in Compose files with a top-level models attribute. Use `docker compose build` instead.

* Gordon responses containing HTML can cause Desktop UI to be permanently broken. As a workaround, you can delete `persisted-state.json` file to reset the UI. The file is located in the following directories:

  * Windows: `%APPDATA%\Docker Desktop\persisted-state.json`
  * Linux: `$XDG_CONFIG_HOME/Docker Desktop/persisted-state.json` or `~/.config/Docker Desktop/persisted-state.json`
  * Mac: `~/Library/Application Support/Docker Desktop/persisted-state.json`

#### [For Windows](#for-windows-22)

* Possible incompatibility between the "host networking" feature of Docker Desktop and the most recent WSL 2 Linux kernel. If you encounter such issues, downgrade WSL 2 to 2.5.7.

## [4.42.1](#4421)

*2025-06-18*

### [Upgrades](#upgrades-12)

* [Docker Compose v2.37.1](https://github.com/docker/compose/releases/tag/v2.37.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-36)

#### [For all platforms](#for-all-platforms-36)

* Fixed an issue where Docker domains were not reachable when the proxy configuration is not valid.
* Fixed a possible deadlock when exposing ports.
* Fixed a race condition which can cause `docker run -p` ports to disappear.

#### [For Mac](#for-mac-21)

* Fixed a bug where a container’s port list appeared empty when inspected immediately after it was created, for example, when using a script. [docker/for-mac#7693](https://github.com/docker/for-mac/issues/7693)

#### [For Windows](#for-windows-23)

* Disabled the Resource Saver mode in WSL 2 to prevent `docker` CLI commands hanging in WSL 2 distros. [docker/for-win#14656](https://github.com/docker/for-win/issues/14656#issuecomment-2960285463)

## [4.42.0](#4420)

*2025-06-04*

### [New](#new-24)

* Expanded network compatibility with IPv6 support.
* The Docker MCP Toolkit is now natively integrated into Docker Desktop.
* Docker Model Runner is now available for Windows systems running on Qualcomm/ARM GPUs.
* Added a **Logs** tab to the Models view so you can see the inference engine output in real time.
* Gordon now integrates the MCP Toolkit, providing access to 100+ MCP servers.

### [Upgrades](#upgrades-13)

* [Docker Buildx v0.24.0](https://github.com/docker/buildx/releases/tag/v0.24.0)
* [Docker Engine v28.2.2](https://docs.docker.com/engine/release-notes/28/#2822)
* [Compose Bridge v0.0.20](https://github.com/docker/compose-bridge-binaries/releases/tag/v0.0.20)
* [Docker Compose v2.36.2](https://github.com/docker/compose/releases/tag/v2.36.2)
* [NVIDIA Container Toolkit v1.17.7](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.17.7)
* [Docker Scout CLI v1.18.0](https://github.com/docker/scout-cli/releases/tag/v1.18.0)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-37)

#### [For all platforms](#for-all-platforms-37)

* Docker Desktop now accepts certificates with a negative serial number.
* Re-enable `seccomp` for containers by default. Use `docker run --security-opt seccomp=unconfined` to disable seccomp for a container.
* Fixed a bug that caused Docker Desktop to hang when it ran out of memory.
* Block `io_uring` syscalls in containers.
* Added support for pulling models from Docker Hub directly, simplifying the process of accessing and using models.
* Docker Desktop now sets the disk usage limit to the size of the physical disk on fresh install and reset to defaults on Mac and Linux.
* The maximum disk size in the settings UI now aligns with the full capacity of the host file system.
* The **Models** view now has a **Docker Hub** tab that lists models under the `ai` namespace.
* Improved the sign-in enforcement message when more than 10 organizations are enforced.
* Changed the way ports are mapped by Docker Desktop to fully support IPv6 ports.
* Fixed a bug in the Dashboard container logs screen causing the scrollbar to disappear as the mouse approaches.
* [Enforced sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) fixed for Teams subscription users.
* `llama.cpp` server now supports streaming and tool calling in Model Runner.
* Sign-in Enforcement capability is now available to all subscriptions.

#### [For Mac](#for-mac-22)

* Fixed a bug where the disk would always have a minimum usage limit of 64GB when using Docker VMM.
* Disabled the memory protection keys mechanism in the Docker Desktop Linux VM. This caused VS Code Dev Containers to not work properly. See [docker/for-mac#7667](https://github.com/docker/for-mac/issues/7667).
* Fixed persistent volume claims under Kubernetes. Fixes [docker/for-mac#7625](https://github.com/docker/for-mac/issues/7625).
* Fixed a bug where the VM failed to start using Apple virtualization.framework.
* Minimum version to install or update Docker Desktop on is now macOS Ventura 13.3.

#### [For Windows](#for-windows-24)

* Fixed a bug in Enhanced Container Isolation on Windows WSL, where files with hardlinks inside containers had `nobody:nogroup` ownership.
* Fixed a bug that caused Docker Desktop to crash. Related to [docker/for-win#14782](https://github.com/docker/for-win/issues/14782).
* Fixed a bug that caused `The network name cannot be found` error when starting with WSL 2. Fixes [docker/for-win#14714](https://github.com/docker/for-win/issues/14714).
* Fixed an issue where Docker Desktop would not remove entries in the hosts file when uninstalling.
* Fixed an issue when reading auto-start registry key for some system languages. Fixes [docker/for-win#14731](https://github.com/docker/for-win/issues/14731).
* Fixed a bug where Docker Desktop was adding unrecognised /etc/wsl.conf `crossDistro` option which was causing WSL 2 to log an error. See [microsoft/WSL#4577](https://github.com/microsoft/WSL/issues/4577)
* Fixed a bug where Docker Desktop failed to start on WSL 2.5.7 if another WSL distro is still using Linux cgroups v1. Fixes [docker/for-win#14801](https://github.com/docker/for-win/issues/14801)
* Windows Subsystem for Linux (WSL) version 2.1.5 is now the minimum version required for proper functioning of Docker Desktop application

### [Known issues](#known-issues-7)

#### [For all platforms](#for-all-platforms-38)

* This release contains a regression with `docker port`, resulting in "No host port found for host IP" errors when using testcontainers-node. See [testcontainers/testcontainers-node#818](https://github.com/testcontainers/testcontainers-node/issues/818#issuecomment-2941575369)

#### [For Windows](#for-windows-25)

* Running containers with Wasm will hang sporadically. See [docker/for-mac#7666](https://github.com/docker/for-mac/issues/7666).
* On some machines Resource Saver will cause other WSL 2 distros to freeze. The workaround is to disable Resource Saver. See [docker/for-win#14656](https://github.com/docker/for-win/issues/14656).

## [4.41.2](#4412)

*2025-05-06*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-38)

#### [For all platforms](#for-all-platforms-39)

* Fixed an issue where the `Models` menu was displayed in the GUI even when Docker Model Runner was not supported or not enabled.

## [4.41.1](#4411)

*2025-04-30*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-39)

#### [For all platforms](#for-all-platforms-40)

* Fixed an issue where Docker Desktop failed to start when a proxy configuration was specified in the `admin-settings.json` file.

#### [For Windows](#for-windows-26)

* Fixed possible conflict with 3rd party tools (for example, Ollama) by avoiding placing `llama.cpp` DLLs in a directory included in the system `PATH`.

## [4.41.0](#4410)

*2025-04-28*

### [New](#new-25)

* Docker Model Runner is now available on x86 Windows machines with NVIDIA GPUs.
* You can now [push models](https://docs.docker.com/ai/model-runner/#push-a-model-to-docker-hub) to Docker Hub with Docker Model Runner.
* Added support for Docker Model Runner's model management and chat interface in Docker Desktop for Mac and Windows (on hardware supporting Docker Model Runner). Users can now view, interact with, and manage local AI models through a new dedicated interface.
* [Docker Compose](https://docs.docker.com/ai/compose/models-and-compose/) and Testcontainers [Java](https://java.testcontainers.org/modules/docker_model_runner/) and [Go](https://golang.testcontainers.org/modules/dockermodelrunner/) now support Docker Model Runner.
* Introducing Docker Desktop in the [Microsoft App Store](https://apps.microsoft.com/detail/xp8cbj40xlbwkx?hl=en-GB\&gl=GB).

### [Upgrades](#upgrades-14)

* [Docker Engine v28.1.1](https://docs.docker.com/engine/release-notes/28.1/#2811)
* [Docker Compose v2.35.1](https://github.com/docker/compose/releases/tag/v2.35.1)
* [Docker Buildx v0.23.0](https://github.com/docker/buildx/releases/tag/v0.23.0)
* [Docker Scout CLI v1.17.1](https://github.com/docker/scout-cli/releases/tag/v1.17.1)
* [Compose Bridge v0.0.19](https://github.com/docker/compose-bridge-binaries/releases/tag/v0.0.19)

### [Security](#security-15)

* Fixed [CVE-2025-3224](https://www.cve.org/CVERecord?id=CVE-2025-3224) allowing an attacker with access to a user machine to perform an elevation of privilege when Docker Desktop updates.
* Fixed [CVE-2025-4095](https://www.cve.org/CVERecord?id=CVE-2025-4095) where Registry Access Management (RAM) policies were not enforced when using a MacOS configuration profile, allowing users to pull images from unapproved registries.
* Fixed [CVE-2025-3911](https://www.cve.org/CVERecord?id=CVE-2025-3911) allowing an attacker with read access to a user's machine to obtain sensitive information from Docker Desktop log files, including environment variables configured for running containers.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-40)

#### [For all platforms](#for-all-platforms-41)

* Fixed a bug in DockerVMM that caused an excessive number of open file handles on the host.
* Fixed an issue where Docker Desktop failed to start if the `admin-settings.json` file didn't contain the optional `configurationFileVersion` configuration.
* Fixed a bug that was causing outgoing UDP connections to be eagerly closed.
* Enhanced log reading experience with advanced search capabilities and container-level filtering, enabling quicker debugging and troubleshooting.
* Improved error messages when downloading Registry Access Management configuration.
* If Docker can't bind an ICMPv4 socket, it now logs an error and continues rather than quits.
* Enabled the memory protection keys mechanism in the Docker Desktop Linux VM, allowing containers like Oracle database images to run correctly.
* Fixed a problem with containers accessing `/proc/sys/kernel/shm*` sysctls when [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) is enabled on Mac, Windows Hyper-V, or Linux.
* Added kernel module `nft_fib_inet`, required for running firewalld in a Linux container.
* MacOS QEMU Virtualization option is being deprecated on July 14, 2025.

#### [For Mac](#for-mac-23)

* Fixed a bug that caused high CPU usage. Fixes [docker/for-mac#7643](https://github.com/docker/for-mac/issues/7643).
* Fixed multi-arch build issue with Rosetta on M3 Macs.
* Fixed an issue where absence of `/Library/Application Support/com.docker.docker/` directory can cause failure to apply RAM policy restrictions.

#### [For Windows](#for-windows-27)

* The Windows `.exe` installer now includes improved handling of locked files. Fixes [docker/for-win#14299](https://github.com/docker/for-win/issues/14299) and [docker/for-win#14316](https://github.com/docker/for-win/issues/14316).
* Fixed `Docker Desktop.exe` not showing version information after installation. Fixes [docker/for-win#14703](https://github.com/docker/for-win/issues/14703).

### [Known issues](#known-issues-8)

#### [For all platforms](#for-all-platforms-42)

* If you have enforced sign-in using `desktop.plist` (on macOS) or Registry key (on Windows) and also have a `registry.json`, sign-in will fail if the user belongs to an organization listed in `desktop.plist`/ registry key but not to any organizations specified in `registry.json`. To resolve this, remove the `registry.json` file.

#### [For Windows](#for-windows-28)

* If multiple organizations are specified in the `allowedOrgs` Windows registry key using space-separated format, sign-in will fail and user will be logged out. As a workaround, specify each organization on a separate line in the registry key value.

## [4.40.0](#4400)

*2025-03-31*

### [New](#new-26)

* You can now pull, run, and manage AI models from Docker Hub directly in Docker Desktop with [Docker Model Runner (Beta)](https://docs.docker.com/ai/model-runner/). Currently available for Docker Desktop for Mac with Apple Silicon.

### [Upgrades](#upgrades-15)

* [Docker Buildx v0.22.0](https://github.com/docker/buildx/releases/tag/v0.22.0)
* [Docker Compose v2.34.0](https://github.com/docker/compose/releases/tag/v2.34.0)
* [Docker Engine v28.0.4](https://docs.docker.com/engine/release-notes/28/#2804)
* [Docker Scout CLI v1.17.0](https://github.com/docker/scout-cli/releases/tag/v1.17.0)
* [compose-bridge v0.0.18](https://github.com/docker/compose-bridge-binaries/releases/tag/v0.0.18)
* [NVIDIA Container Toolkit v1.17.5](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.17.5)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-41)

#### [For all platforms](#for-all-platforms-43)

* Fixed a bug that caused `docker-proxy` to stop forwarding UDP datagrams to containers.
* Fixed a bug that caused docker-proxy to close UDP connections to containers eagerly and resulting in the source address to change needlessly
* Fixed a race condition that prevented Docker Desktop Kubernetes from starting in some scenarios.
* Improved the way ECI collects image digest info from a repository in environments where proxies are configured.
* Users can now to specify a timeout when generating a private Extension Marketplace using the new `--timeout` flag.
* Removed unused internal helper tool `com.docker.admin` for Mac and Linux.

#### [For Mac](#for-mac-24)

* Fixed an issue where stale directory cache in Docker VMM that prevented detecting moved or new files.
* Removed Continue/Restart pop up when Time Machine utility is restricted.
* Docker Desktop now allows Unix domain sockets to be shared with containers via `docker run -v /path/to/unix.sock:/unix.sock`. The full socket path must be specified in the bind-mount. See [for-mac/#483](https://github.com/docker/for-mac/issues/483).
* Fixed a bug that caused the `docker-credential-osxkeychain` and `docker-credential-desktop` to return malformed URIs when a token was stored for a server with a port specified.

#### [For Windows](#for-windows-29)

* The Windows MSI and `.exe` installers now disable Windows Containers by default when installing with the GUI.
* Improved port-mapping throughput on WSL2.

### [Known issues](#known-issues-9)

#### [For Windows](#for-windows-30)

* Switching to Windows Containers while the privileged helper error message is displayed could cause inconsistent state. As a workaround, quit Docker Desktop, change `UseWindowsContainers` to `false` in `settings-store.json` and restart Docker Desktop.
* After installation, `Docker Desktop.exe` does not contain the latest version information.

## [4.39.0](#4390)

*2025-03-05*

### [New](#new-27)

* The [Docker Desktop CLI](https://docs.docker.com/desktop/features/desktop-cli/) is now generally available. You can now also print logs with the new `docker desktop logs` command.
* Docker Desktop now supports the `--platform` flag on [`docker load`](/reference/cli/docker/image/load/) and [`docker save`](/reference/cli/docker/image/save/). This helps you import and export a subset of multi-platform images.

### [Upgrades](#upgrades-16)

* [Docker Compose v2.33.1](https://github.com/docker/compose/releases/tag/v2.33.1)
* [Docker Buildx v0.21.1](https://github.com/docker/buildx/releases/tag/v0.21.1)
* [Kubernetes v1.32.2](https://github.com/kubernetes/kubernetes/releases/tag/v1.32.2)
* [Docker Engine v28.0.1](https://docs.docker.com/engine/release-notes/28/#2801)
* [Docker Scout CLI v1.16.3](https://github.com/docker/scout-cli/releases/tag/v1.16.3)

### [Security](#security-16)

* Fixed [CVE-2025-1696](https://www.cve.org/CVERecord?id=CVE-2025-1696) which could disclose proxy authentication credentials in plaintext in log files.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-42)

#### [For all platforms](#for-all-platforms-44)

* Ask Gordon now offers deeper context on Docker images, containers, and volumes, delivers faster support, and enables more user actions via Docker Desktop and the Docker CLI.
* Support multi-platform images via enabling users to pick a specific platform in `docker history`
* Fixed an issue that caused clients other than the CLI and Docker Desktop to see a delay of 3 seconds whenever a container with port-mappings exists. See [docker/for-mac#7575](https://github.com/docker/for-mac/issues/7575)
* Fixed a bug in the ECI Docker socket permissions which caused it to sometimes block Docker socket mounts on containers with allowed images, or images derived from allowed images.
* Fixed a bug that prevented Docker Desktop from entering Resource Saver mode again immediately after an engine restart.
* Fixed an issue that caused Kubernetes clusters to stop working due to expired PKI certificates.

#### [For Mac](#for-mac-25)

* Downgraded Linux kernel to `v6.10.14` to fix a bug in OpenJDK that causes Java containers to terminate due to cgroups controller misidentification. See [docker/for-mac#7573](https://github.com/docker/for-mac/issues/7573).
* Added `/usr/share/misc/usb.ids` in the root mount namespace to fix `usbip`.
* Fixed an issue where the display of the CPU limit was capped at 8 when using Docker VMM.
* Fixed an issue where startup would hang and the `com.docker.backend` process consumed 100% of the CPU. See [docker/for-mac#6951](https://github.com/docker/for-mac/issues/6951).
* Fixed a bug that caused all Java programs running on M4 Macbook Pro to emit a SIGILL error. See [docker/for-mac#7583](https://github.com/docker/for-mac/issues/7583).
* Blocked startup on macOS 15.4 beta 1 since starting VMs will cause the host to crash, see <https://developer.apple.com/documentation/macos-release-notes/macos-15_4-release-notes#Virtual-Machines>.
* Fixed an issue where the myIPAddress PAC file function retrieved the host IP from the wrong interface, causing incorrect proxy selection.

#### [For Windows](#for-windows-31)

* Fixed a bug that prevented `docker compose log` to stream when running apps in WSL.
* Fixed a bug where Paketo buildpacks failed with Enhanced Container Isolation when Docker Desktop uses WSL.
* Fixed a bug where the WSL 2 integration would fail if WSL Version 1 distributions are installed.
* Fixed a bug that caused some CLI plugins update to fail if WSL distributions were enabled.
* Fixed a bug where Docker Desktop sign-in would hang when using a PAC file for proxy configuration, causing a blurred UI and blocking access.

#### [For Linux](#for-linux-5)

* The **Software Updates** page in settings, now points to the latest available version available.

## [4.38.0](#4380)

*2025-01-30*

### [New](#new-28)

* Installing Docker Desktop via the PKG installer is now generally available.
* Enforcing sign-in via configuration profiles is now generally available.
* Docker Compose, Docker Scout, the Docker CLI, and Ask Gordon can now be updated independently of Docker Desktop and without a full restart (Beta).
* The new [`update` command](/reference/cli/docker/desktop/update/) has been added to the Docker Desktop CLI (Mac only).
* [Bake](https://docs.docker.com/build/bake/) is now generally available, with support for entitlements and composable attributes.
* You can now create [multi-node Kubernetes clusters](https://docs.docker.com/desktop/settings-and-maintenance/settings/#kubernetes) in Docker Desktop.
* [Ask Gordon](https://docs.docker.com/ai/gordon/) is more widely available. It is still in Beta.

### [Upgrades](#upgrades-17)

* [containerd v1.7.24](https://github.com/containerd/containerd/releases/tag/v1.7.24)
* [Docker Buildx v0.20.1](https://github.com/docker/buildx/releases/tag/v0.20.1)
* [Docker Compose v2.32.4](https://github.com/docker/compose/releases/tag/v2.32.4)
* [Docker Engine v27.5.1](https://docs.docker.com/engine/release-notes/27/#2751)
* [Docker Scout CLI v1.16.1](https://github.com/docker/scout-cli/releases/tag/v1.16.1)
* [Runc v1.2.2](https://github.com/opencontainers/runc/releases/tag/v1.2.2)
* [NVIDIA Container Toolkit v1.17.4](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.17.4)
* [Kubernetes v1.31.4](https://github.com/kubernetes/kubernetes/releases/tag/v1.31.4)
* Docker Debug `v0.0.38`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-43)

#### [For all platforms](#for-all-platforms-45)

* Fixed a bug where access tokens generated by the `docker login` web flow could not be refreshed by Docker Desktop.

* Fixed a bug where container creation via the Docker API using `curl` failed when [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) was enabled.

* Fixed a bug where the RAM policy was not refreshed after the refresh period had elapsed.

* Fixed a bug in Enhanced Container Isolation when mounting the Docker socket into a container, and then creating Docker containers with bind-mounts from within that container.

* Fixed an issue that caused a discrepancy between the GUI and the CLI, the former forcing the `0.0.0.0` HostIP in port-mappings. This caused default binding IPs configured through Engine's `ip` flag, or through the bridge option `com.docker.network.bridge.host_binding_ipv4`, to not be used.

* Fixed a bug where the `pac` setting was ignored in `admin-settings.json`.

* Build UI:

  * Added a progress status when importing a build.
  * Fixed a bug where users were unable to import builds.
  * Fixed a bug where some builders using SSH endpoints were not skipped.

#### [For Mac](#for-mac-26)

* Fixed a bug in Docker VMM where bind-mounts from non-root volumes would weren't working as expected.
* Fixed an issue that caused startup failures on systems without IPv6. Fixes [docker/for-mac#14298](https://github.com/docker/for-win/issues/14298).
* Fixed a bug that caused Docker Desktop to hang. See [docker/for-mac#7493](https://github.com/docker/for-mac/issues/7493#issuecomment-2568594070).
* Fixed an issue where the uninstaller would fail if the settings file is missing.
* Fixed a bug where config profiles deployed via Workspace One were ignored.

#### [For Windows](#for-windows-32)

* The Docker Desktop installer will now present a UAC prompt when launched.
* Fixed an issue where Docker Desktop would fail to start for data disks created with old WSL versions that shared the same identifier as other WSL distros.
* Docker Desktop now restarts when WSL integration settings are changed. This ensures proper setup of WSL integration when using Enhanced Container Isolation.

#### [For Linux](#for-linux-6)

* Added support for gvisor networking. Users with an incompatible version of qemu (8.x) will stay on qemu networking, and others will be migrated automatically.

### [Deprecation](#deprecation)

#### [For all platforms](#for-all-platforms-46)

* Deprecated `com.docker.diagnose check|check-dot|check-hypervisordetect-host-hypervisor`.

## [4.37.2](#4372)

*2025-01-09*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-44)

#### [For Mac](#for-mac-27)

* Prevents a bug that caused Docker Desktop to not update `com.docker.vmnetd` or `com.docker.socket` to newer versions.

### [Known issues](#known-issues-10)

#### [For Mac](#for-mac-28)

* If you’re seeing a security popup about malware on `com.docker.vmnetd` or `com.docker.socket`, follow the steps documented in [docker/for-mac#7527](https://github.com/docker/for-mac/issues/7527).

## [4.37.1](#4371)

*2024-12-17*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-45)

#### [For all platforms](#for-all-platforms-47)

* Fixed an issue that caused the AI Catalog in Docker Hub to be unavailable in Docker Desktop.
* Fixed an issue that caused Docker Desktop to panic with `index out of range [0] with length 0` when using [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/).

### [Known issues](#known-issues-11)

#### [For Mac](#for-mac-29)

* If you’re seeing a security popup about a malware on `com.docker.vmnetd` or `com.docker.socket`, follow the steps documented in [docker/for-mac#7527](https://github.com/docker/for-mac/issues/7527).

## [4.37.0](#4370)

*2024-12-12*

### [New](#new-29)

* You can now perform key operations such as starting, stopping, restarting, and checking the status of Docker Desktop directly from the [command line](https://docs.docker.com/desktop/features/desktop-cli/) (Beta).
* The AI Catalog in Docker Hub is available directly through Docker Desktop.

### [Upgrades](#upgrades-18)

* [Docker Buildx v0.19.2](https://github.com/docker/buildx/releases/tag/v0.19.2)
* [Docker Compose v2.31.0](https://github.com/docker/compose/releases/tag/v2.31.0)
* [Docker Engine v27.4.0](https://docs.docker.com/engine/release-notes/27/#2740)
* [Docker Scout CLI v1.15.1](https://github.com/docker/scout-cli/releases/tag/v1.15.1)
* [NVIDIA Container Toolkit v1.17.2](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.17.2)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-46)

#### [For all platforms](#for-all-platforms-48)

* The default disk usage limit for Docker Engine in new installations is now 1TB.

* Fixed an issue where containers could not establish loopback `AF_VSOCK` connections.

* Fixed a bug where resetting default settings would also reset the CLI context.

* Fixed a bug where the Docker Desktop Dashboard would get out of sync with the Docker daemon after restarting the engine while in Resource Saver mode (Windows with WSL2 backend only) or after switching engines (macOS).

* Fixed a bug where Resource Saver mode would fail to re-engage after restarting the engine while in Resource Saver mode.

* Build UI:

  * Fixed a bug where the source file could not be found for some builds.
  * Fixed a bug where error logs were not displayed in the **Source** tab.
  * Fixed a bug where users had to scroll to the bottom for error logs in **Source** tab.
  * Fixed a bug where timestamps would be broken in the **Logs** tab.

#### [For Mac](#for-mac-30)

* Fixed a bug that would create certain user directories with root permission when running the uninstaller binary twice with `sudo`.

#### [For Windows](#for-windows-33)

* Added support for Windows on ARM using WSL 2 version 2.3.24 and later to single distribution mode on WSL 2.
* Fixed an issue where Docker Desktop would fail to start. Fixes [docker/for-win#14453](https://github.com/docker/for-win/issues/14453)

### [Known issues](#known-issues-12)

#### [For all platforms](#for-all-platforms-49)

* Kubernetes cluster may not start if **Registry Access Manager** is enabled. As a workaround, add `registry.k8s.io` and `<geo>-docker.pkg.dev` to **Registry Access Management** policies.

#### [For Mac](#for-mac-31)

* If you’re seeing a security popup about a malware on `com.docker.vmnetd` or `com.docker.socket`, follow the steps documented in [docker/for-mac#7527](https://github.com/docker/for-mac/issues/7527).

### [Deprecation](#deprecation-1)

#### [For Mac](#for-mac-32)

* QEMU (Legacy) as a VMM on Apple Silicon will be removed in a future version. It is recommended that you switch to the Apple Virtualization Framework for increased performance and stability. If you encounter an issue, [contact Docker Support](https://www.docker.com/support/) or [file a GitHub issue](https://github.com/docker/for-mac/issues).
* osxfs (Legacy) will be removed in a future version. It is recommended that you switch to VirtioFS for increased performance. If you encounter an issue, [contact Docker Support](https://www.docker.com/support/) or [file a GitHub issue](https://github.com/docker/for-mac/issues).

## [4.36.1](#4361)

*2025-01-09*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-47)

#### [For Mac](#for-mac-33)

* Prevents a bug that caused Docker Desktop to not update `com.docker.vmnetd` or `com.docker.socket` to newer versions.

### [Known issues](#known-issues-13)

#### [For Mac](#for-mac-34)

* If you’re seeing a security popup about malware on `com.docker.vmnetd` or `com.docker.socket`, follow the steps documented in [docker/for-mac#7527](https://github.com/docker/for-mac/issues/7527).

## [4.36.0](#4360)

*2024-11-18*

### [New](#new-30)

* Existing Docker Desktop installations using the WSL2 engine on Windows are now automatically migrated to a unified single-distribution architecture for enhanced consistency and performance.

* Administrators can now:

  * Enforce sign-in with macOS [configuration profiles](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#configuration-profiles-method-mac-only) (Early Access).
  * Enforce sign-in for more than one organization at a time (Early Access).
  * Deploy Docker Desktop for Mac in bulk with the [PKG installer](https://docs.docker.com/enterprise/enterprise-deployment/pkg-install-and-configure/) (Early Access).
  * Use Desktop Settings Management to manage and enforce defaults via admin.docker.com (Early Access).

* Enhance Container Isolation (ECI) has been improved to:

  * Allow admins to [turn off Docker socket mount restrictions](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/#allowing-all-containers-to-mount-the-docker-socket).
  * Support wildcard tags when using the [`allowedDerivedImages` setting](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/#docker-socket-mount-permissions-for-derived-images).

### [Upgrades](#upgrades-19)

* [Docker Buildx v0.18.0](https://github.com/docker/buildx/releases/tag/v0.18.0)
* [Docker Compose v2.30.3](https://github.com/docker/compose/releases/tag/v2.30.3)
* [Kubernetes v1.30.5](https://github.com/kubernetes/kubernetes/releases/tag/v1.30.5)
* [NVIDIA Container Toolkit v1.17.0](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.17.0)
* [Docker Scout CLI v1.15.0](https://github.com/docker/scout-cli/releases/tag/v1.15.0)
* Docker Init v1.4.0
* Linux kernel `v6.10.13`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-48)

#### [For all platforms](#for-all-platforms-50)

* Fixed a bug where the `docker events` command would not terminate after streaming the events.

* Docker Init: Improved Dockerfile caching for PHP applications that don't use Docker Compose.

* Synchronized file shares now respects the `filesharingAllowedDirectories` setting in `admin-settings.json`.

* Fixed an issue where if Docker Desktop is configured to use a proxy, it fails to start due to an internal timeout while fetching authentication tokens.

* Added a recovery banner to retry an update if the download failed.

* Fixed an issue where if the `umask` is set to `577` it would cause `rpmbuild` failure. Fixes [docker/for-mac#6511](https://github.com/docker/for-mac/issues/6511).

* Fixed a bug that restricted containers using `--network=host` to 18 open host ports.

* Fixed bind mount ownership for non-root containers. Fixes [docker/for-mac#6243](https://github.com/docker/for-mac/issues/6243).

* Docker Desktop will not unpause automatically after a manual pause. The system will stay paused until you manually resume the Docker engine. This fixes a bug where other software would accidentally trigger a resume by running a CLI command in the background. Fixes [for-mac/#6908](https://github.com/docker/for-mac/issues/6908)

* Build UI:

  * The **Source** tab now supports multiple source files.
  * Links for image dependencies in the **Info** tab now support other well-known registries such as GitHub, Google, and GitLab.
  * Disabled the **Delete** button if only cloud builds are selected.
  * Fixed an issue where users were unable to delete builds.
  * Fixed malformed Jaeger traces that were missing events and links.
  * Fixed missing export attributes when building with the cloud driver.

#### [For Mac](#for-mac-35)

* Fixed a bug in Docker VMM that prevented MySQL and other databases containers to start. Fixes reports from [docker/for-mac#7464](https://github.com/docker/for-mac/issues/7464).
* The minimum memory requirement is now automatically adjusted for Docker VMM, improving the user experience and addressing reports from [docker/for-mac#7464](https://github.com/docker/for-mac/issues/7464), [docker/for-mac#7482](https://github.com/docker/for-mac/issues/7482).
* Fixed a bug where the advanced option **Allowed privileged port mapping** was not working as expected. Fixes [docker/for-mac#7460](https://github.com/docker/for-mac/issues/7460).
* Docker Desktop can now automatically configure shell completion scripts for zsh, bash and fish inside the install wizard and settings screen.
* Fixed a bug where the in-app update would fail if Docker Desktop was installed by a non-admin user or if the current user was previously an administrator. Fixes [for-mac/#7403](https://github.com/docker/for-mac/issues/7403) and [for-mac/#6920](https://github.com/docker/for-mac/issues/6920)

#### [For Windows](#for-windows-34)

* Fixed a bug preventing UDP port 53 to be bound.
* Fixed a bug where Windows daemon options were overwritten at startup.

## [4.35.2](#4352)

*2025-01-09*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-49)

#### [For Mac](#for-mac-36)

* Prevents a bug that caused Docker Desktop to not update `com.docker.vmnetd` or `com.docker.socket` to newer versions.

### [Known issues](#known-issues-14)

#### [For Mac](#for-mac-37)

* If you’re seeing a security popup about malware on `com.docker.vmnetd` or `com.docker.socket`, follow the steps documented in [docker/for-mac#7527](https://github.com/docker/for-mac/issues/7527).

## [4.35.1](#4351)

*2024-10-30*

#### [For all platforms](#for-all-platforms-51)

* Fixed a bug where Docker Desktop would incorrectly bind to port `8888`. Fixes [docker/for-win#14389](https://github.com/docker/for-win/issues/14389) and [docker/for-mac#7468](https://github.com/docker/for-mac/issues/7468)

## [4.35.0](#4350)

*2024-10-24*

### [New](#new-31)

* Support for [Docker Desktop on Red Hat Enterprise Linux](https://docs.docker.com/desktop/setup/install/linux/rhel/) is now generally available.
* Volume Backup and Share is now generally available and can be found in the **Volumes** view.
* Terminal support within Docker Desktop using system shells is now generally available.
* Beta release of Docker VMM - the more performant alternative to Apple Virtualization Framework on macOS (requires Apple Silicon and macOS 12.5 or later).

### [Upgrades](#upgrades-20)

* [containerd v1.7.21](https://github.com/containerd/containerd/releases/tag/v1.7.21)
* [Docker Buildx v0.17.1](https://github.com/docker/buildx/releases/tag/v0.17.1)
* [Docker Compose v2.29.7](https://github.com/docker/compose/releases/tag/v2.29.7)
* [Docker Engine v27.3.1](https://docs.docker.com/engine/release-notes/27/#2731)
* [Docker Scout CLI v1.14.0](https://github.com/docker/scout-cli/releases/tag/v1.14.0)
* Docker Debug `v0.0.37`
* Linux kernel `v6.10.9`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-50)

#### [For all platforms](#for-all-platforms-52)

* Fixed a bug where proxy settings in `daemon.json` would override proxies set in Docker Desktop settings.

* Fixed a bug where some Docker subnet ranges were not able to be used.

* Removed [docker-index](https://github.com/docker/index-cli-plugin) as it is now deprecated, you can use `docker scout cves fs://<path to binary>` instead.

* Fixed a bug where images couldn't be sorted or filtered by tag. Fixes [docker/for-win#14297](https://github.com/docker/for-win/issues/14297).

* Fixed a bug where the `docker` CLI did not work as expected when the `registry.json` file was malformed.

* Fixed a bug where the **Push to Docker Hub** action in the **Images** view would result in an `invalid tag format` error. Fixes [docker/for-win#14258](https://github.com/docker/for-win/issues/14258).

* Fixed an issue where Docker Desktop startup failed when ICMPv6 setup was not successful.

* Added drivers that allow USB/IP to work.

* Fixed a bug in Enhanced Container Isolation (ECI) [Docker socket mount permissions for derived images](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/) where it was incorrectly denying Docker socket mounts for some images when Docker Desktop uses the containerd image store.

* Enable `NFT_NUMGEN`, `NFT_FIB_IPV4` and `NFT_FIB_IPV6` kernel modules.

* Build UI:

  * Highlight build check warnings in the **Completed builds** list.
  * Improve visualization for the build time charts.
  * Image tags added to **Build results** section under the **Info** tab.

* Improved efficiency of host-side disk utilization for fresh installations on Mac and Linux.

* Fixed a bug that prevented the Sign in enforcement popup to be triggered when token expires.

* Fixed a bug where containers would not be displayed in the GUI immediately after signing in when using [enforced sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).

* `settings.json` has been renamed to `settings-store.json`

* The host networking feature no longer requires users to be signed-in in order to use it.

#### [For Mac](#for-mac-38)

* Fixed a bug where auto-start containers could be misconfigured after changing filesharing type in settings.
* Fixed a bug that would cause `~/.docker/cli-plugins` to not be populated on start-up.
* Fixed a bug that prevented php composer or postgres to start as non root user. Fixes [docker/for-mac#7415](https://github.com/docker/for-mac/issues/7415).
* Fixed a bug that could cause file changed on the host to appear truncated. Fixes [docker/for-mac#7438](https://github.com/docker/for-mac/issues/7438).

#### [For Windows](#for-windows-35)

* New installations of Docker Desktop for Windows now require a Windows version of 19045 or later.
* Fixed an issue that caused a start failure if IPv6 is disabled either in the kernel config or via the kernel command-line in WSL. Fixes [docker/for-win#14240](https://github.com/docker/for-win/issues/14240)
* Fixed the **Clean / Purge data** button on Windows. Fixes [docker/for-win#12650](https://github.com/docker/for-win/issues/14308).
* Disk usage statistics is now displayed in the Dashboard footer installations.
* Improved recovery for WSL distribution issues.

#### [For Linux](#for-linux-7)

* Ubuntu 24.04 is now supported on Docker Desktop.

### [Known issues](#known-issues-15)

#### [For Mac](#for-mac-39)

* Since version 4.34.0, the toggle "Allow privileged port mapping" in the Advanced settings does not work. For more information, see [docker/for-mac#7460](https://github.com/docker/for-mac/issues/7460).

#### [For Windows](#for-windows-36)

* Users with versions 4.14.0 and earlier could encounter issues using the in-app update. To update to the latest version, download and install the latest Docker Desktop from this page.

## [4.34.4](#4344)

*2025-01-09*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-51)

#### [For Mac](#for-mac-40)

* Prevents a bug that caused Docker Desktop to not update `com.docker.vmnetd` or `com.docker.socket` to newer versions.

### [Known issues](#known-issues-16)

#### [For Mac](#for-mac-41)

* If you’re seeing a security popup about malware on `com.docker.vmnetd` or `com.docker.socket`, follow the steps documented in [docker/for-mac#7527](https://github.com/docker/for-mac/issues/7527).

## [4.34.3](#4343)

*2024-10-09*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/170107/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/170107/checksums.txt))
> * [Windows ARM Beta](https://desktop.docker.com/win/main/arm64/170107/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/170107/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/170107/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/170107/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/170107/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/170107/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/170107/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/170107/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/170107/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/170107/checksums.txt))

### [Upgrades](#upgrades-21)

* [NVIDIA Container Toolkit v1.16.2](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.16.2)

### [Security](#security-17)

* Fixed [CVE-2024-9348](https://www.cve.org/cverecord?id=CVE-2024-9348) which allows RCE via image build details source information
* Fixed NVIDIA Container Toolkit [CVE-2024-0132](https://nvidia.custhelp.com/app/answers/detail/a_id/5582)
* Fixed NVIDIA Container Toolkit [CVE-2024-0133](https://nvidia.custhelp.com/app/answers/detail/a_id/5582)

## [4.34.2](#4342)

*2024-09-12*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-52)

#### [For all platforms](#for-all-platforms-53)

* Fixed a bug where `docker compose up` would become unresponsive while in Resource Saver mode.

### [Security](#security-18)

* Fixed [CVE-2024-8695](https://www.cve.org/cverecord?id=CVE-2024-8695) which allows RCE via crafted extension description/changelog which could be abused by a malicious extension.
* Fixed [CVE-2024-8696](https://www.cve.org/cverecord?id=CVE-2024-8696) which allows RCE via crafted extension publisher-url/additional-urls which could be abused by a malicious extension.

## [4.34.1](#4341)

*2024-09-05*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/166053/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/166053/checksums.txt))
> * [Windows ARM Beta](https://desktop.docker.com/win/main/arm64/166053/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/166053/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-53)

#### [For Windows](#for-windows-37)

* Fixed a bug where Docker Desktop failed to start (often on first boot) incorrectly believing another instance of the application is running. ([docker/for-win#14294](https://github.com/docker/for-win/issues/14294) and [docker/for-win#14034](https://github.com/docker/for-win/issues/14034)).

## [4.34.0](#4340)

*2024-08-29*

### [New](#new-32)

* [Host networking](https://docs.docker.com/engine/network/drivers/host/#docker-desktop) support on Docker Desktop is now generally available.
* If you authenticate via the CLI, you can now authenticate through a browser-based flow, removing the need for manual PAT generation.
* Windows now supports automatic reclamation of disk space in Docker Desktop for WSL2 installations [using a managed virtual hard disk](https://docs.docker.com/desktop/features/wsl/best-practices/).
* Deploying Docker Desktop via the [MSI installer](https://docs.docker.com/enterprise/enterprise-deployment/msi-install-and-configure/) is now generally available.
* Two new methods to [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) (windows registry key and `.plist` file) are now generally available.
* Fresh installations of Docker Desktop now use the containerd image store by default.
* [Compose Bridge](https://docs.docker.com/compose/bridge/) (Experimental) is now available from the Compose file viewer. Easily convert and deploy your Compose project to a Kubernetes cluster.

### [Upgrades](#upgrades-22)

* [Docker Engine v27.2.0](https://docs.docker.com/engine/release-notes/27.2/#2720)
* [Docker Compose v2.29.2](https://github.com/docker/compose/releases/tag/v2.29.2)
* [containerd v1.7.20](https://github.com/containerd/containerd/releases/tag/v1.7.20)
* [Docker Scout CLI v1.13.0](https://github.com/docker/scout-cli/releases/tag/v1.13.0)
* [Docker Buildx v0.16.2](https://github.com/docker/buildx/releases/tag/v0.16.2)
* Linux kernel `v6.10.1`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-54)

#### [For all platforms](#for-all-platforms-54)

* Fixed a bug that caused the CLI to become idle when a container was started with AutoRemove (`--rm`) but whose port bindings would be rejected by Docker Desktop at start-up.
* Fixed a bug where diagnostics collection would fail sporadically on the **Support** screen.
* Fixed a bug where folders wouldn't expand in a container's **File** tab. Fixes [docker/for-win#14204](https://github.com/docker/for-win/issues/14204).
* In-app updates now respect the proxy settings.
* Extended the ECI Docker socket mount permissions feature to optionally child images derived from allowed images. This allows ECI to work with buildpacks (e.g., Paketo) that create ephemeral local images that use Docker socket mounts.
* Fixed a bug that caused the **Containers** view to flash when using certain proxy settings. Fixes [docker/for-win#13972](https://github.com/docker/for-win/issues/13972).
* Improved the output of `docker image list` to show multi-platform-related image information.

#### [For Mac](#for-mac-42)

* Fixed a bug where a `Partial repair error` would occasionally appear when triggering the Configuration integrity check feature.
* Configuration integrity check feature now shows information on why the Docker socket is mis-configured.
* Fixed an issue where the Configuration integrity check feature would report the system path instead of the user path if Docker Desktop is installed as `User`.
* Fixed a bug where applications trying to read extended attributes from bind mounted volumes could experience failures. Fixes [docker/for-mac#7377](https://github.com/docker/for-mac/issues/7377).

#### [For Windows](#for-windows-38)

* Fixed a bug where Docker Desktop would reset docker's `credsStore` to `desktop` when the user's intention is to keep it empty. Fixes [docker/for-win#9843](https://github.com/docker/for-win/issues/9843).
* Fixed a bug that would cause Docker Desktop to not start in the WSL2 engine [docker/for-win#14034](https://github.com/docker/for-win/issues/14034).
* Fixed a bug that caused WSL distribution to terminate abruptly. Fixes [docker/for-win/14230](https://github.com/docker/for-win/issues/14230).
* Fixed an issue that caused WSL to update in each startup. Fixes [docker/for-win/13868](https://github.com/docker/for-win/issues/13868), [docker/for-win/13806](https://github.com/docker/for-win/issues/13806).

### [Known issues](#known-issues-17)

* Compose Bridge does not work automatically when you enable it within the **Experimental** settings tab. It takes a few minutes before you are notified that you must 'repair' Docker Desktop which then installs the `compose-bridge` binary.

* The **Convert and Deploy** button in the Compose file viewer might be disabled even when Kubernetes is running and Compose Bridge is enabled. The workaround for this is to disable Compose Bridge in the **Experimental** settings tab, apply the change with **Apply & restart**, then re-enable and select **Apply & restart** again.

* There is a known issue when authenticating against a registry in the Docker CLI (`docker login [registry address]`) where, if the provided registry address includes a repository/image name (such as `docker login index.docker.io/docker/welcome-to-docker`), the repository part (`docker/welcome-to-docker`) is not normalized and results in credentials being stored incorrectly, which causes subsequent pulls from the registry (`docker pull index.docker.io/docker/welcome-to-docker`) to not be authenticated. To prevent this, don't include any extraneous suffix in the registry address when running `docker login`.

  > Note
  >
  > Using `docker login` with an address that includes URL path segments is not a documented use case and is considered unsupported. The recommended usage is to specify only a registry hostname, and optionally a port, as the address for `docker login`.

* When running `docker compose up` and Docker Desktop is in the Resource Saver mode, the command is unresponsive. As a workaround, manually exit the Resource Saving mode and Docker Compose becomes responsive again.

* When [Enhanced Container Isolation (ECI)](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) is enabled, Docker Desktop may not enter Resource Saver mode. This will be fixed in a future Docker Desktop release.

* The new [ECI Docker socket mount permissions for derived images](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/#docker-socket-mount-permissions-for-derived-images) feature does not yet work when Docker Desktop is configured with the **Use containerd for pulling and storing images**. This will be fixed in the next Docker Desktop release.

## [4.33.2](#4332)

*2025-01-09*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-55)

#### [For Mac](#for-mac-43)

* Prevents a bug that caused Docker Desktop to not update `com.docker.vmnetd` or `com.docker.socket` to newer versions.

### [Known issues](#known-issues-18)

#### [For Mac](#for-mac-44)

* If you’re seeing a security popup about malware on `com.docker.vmnetd` or `com.docker.socket`, follow the steps documented in [docker/for-mac#7527](https://github.com/docker/for-mac/issues/7527).

## [4.33.1](#4331)

*2024-07-31*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-56)

#### [For Windows](#for-windows-39)

* Added support for WSL2 2.3.11 and above, which includes loadable kernel modules. Fixes [docker/for-win#14222](https://github.com/docker/for-win/issues/14222)

## [4.33.0](#4330)

*2024-07-25*

> Download Docker Desktop
>
> * [Windows](https://desktop.docker.com/win/main/amd64/160616/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/amd64/160616/checksums.txt))
> * [Windows ARM Beta](https://desktop.docker.com/win/main/arm64/160616/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) ([checksum](https://desktop.docker.com/win/main/arm64/160616/checksums.txt))
>
> - [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/160616/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/160616/checksums.txt))
> - [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/160616/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/160616/checksums.txt))
>
> * [Debian](https://desktop.docker.com/linux/main/amd64/160616/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [RPM](https://desktop.docker.com/linux/main/amd64/160616/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) - [Arch](https://desktop.docker.com/linux/main/amd64/160616/docker-desktop-x86_64.pkg.tar.zst?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64) ([checksum](https://desktop.docker.com/linux/main/amd64/160616/checksums.txt))

### [New](#new-33)

* [Docker Debug](/reference/cli/docker/debug/) is now generally available.
* BuildKit now evaluates Dockerfile rules to inform you of potential issues.
* **Resource Allocation** settings can now be accessed directly from the resource usage data displayed in the Dashboard footer.
* New and improved experience for [troubleshooting](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/).

### [Upgrades](#upgrades-23)

* [Docker Compose v2.29.1](https://github.com/docker/compose/releases/tag/v2.29.1)
* [Docker Engine v27.1.1](https://docs.docker.com/engine/release-notes/27.1/#2711)
* [containerd v1.7.19](https://github.com/containerd/containerd/releases/tag/v1.7.19)
* [NVIDIA Container Toolkit v1.16.0](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.16.0)
* [Docker Scout CLI v1.11.0](https://github.com/docker/scout-cli/releases/tag/v1.11.0)
* [Kubernetes v1.30.2](https://github.com/kubernetes/kubernetes/releases/tag/v1.30.2)
* Linux kernel `v6.10`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-57)

#### [For all platforms](#for-all-platforms-55)

* Fixed an issue that caused containers started with `--net=host` and listening on an IPv6 address to be accessible from the host.

* Improved the UX for enabling the containerd image store in the **Settings** tab.

* Fixed an issue that caused a deadlock seen while using the `grpcfuse` filesharing option under heavy load.

* Fixed a bug where Mac-specific admin settings were impacting other platforms.

* IPv6 address blocks can now be specified in Docker Engine's `default-address-pools`.

* Fixed an issue with the validation of the Docker Engine's `bip`, `fixed-cidr` and `fixed-cidr-v6`. Fixes [docker/for-mac#7104](https://github.com/docker/for-mac/issues/7104).

* Docker Engine's `default-network-opts` parameter is now properly validated.

* VirtioFS performance improvements include increasing directory cache timeout, handling change notifications from the host, removing extra FUSE operations for security.capability attributes, optimizing host event detection, and providing an API to clean caches after container termination.

* Docker Desktop now notifies when there is a port conflict in a host networking container.

* Compose Bridge command line option is now available via Experimental features. When enabled, run `compose-bridge` to convert your Compose configuration to Kubernetes resources.

* Builds view:

  * Added [build checks](https://docs.docker.com/build/checks/) to the build details' **Source** tab.
  * Added build tags to the build details' **Info** tab under the **Source details** section.
  * Newly imported builds are now highlighted.
  * Improved performance of error message handling.
  * Fixed a connection issue to the builder which prevented build records from displaying.
  * Fixed the navigation when opening builds through the CLI.

#### [For Mac](#for-mac-45)

* The Configuration integrity check feature now provides more context around what has changed with your Docker Desktop configuration. For more information, see the [FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/macfaqs/).
* The Configuration integrity check feature shows an error when it fails to repair Docker Desktop.
* Fixed a bug where the IPv6 TCP was set to `host.docker.internal`. Fixes [docker/for-mac#7332](https://github.com/docker/for-mac/issues/7332).
* Fixed an issue where the `docker-compose` symlink pointed to an empty location. Fixes [docker/for-mac#7345](https://github.com/docker/for-mac/issues/7345).

#### [For Linux](#for-linux-8)

* Fixed an issue where some `wincred` values were persisted after uninstall. Reported by Javier Yong [@Javiery3889](https://github.com/Javiery3889).
* Fixed an issue where the notification **Another application changed your Desktop configurations** is incorrectly triggered.

### [Security](#security-19)

#### [For all platforms](#for-all-platforms-56)

* Includes a fix for AuthZ Plugin Bypass Regression in Docker Engine. For more information, see [CVE-2024-41110](https://www.cve.org/cverecord?id=CVE-2024-41110).

#### [For Windows](#for-windows-40)

* Fixed an issue where some `wincred` values were persisted after uninstall. Reported by Javier Yong [@Javiery3889](https://github.com/Javiery3889).

### [Known Issues](#known-issues-19)

#### [For Windows](#for-windows-41)

* Docker Desktop fails to start with WSL pre-releases `v2.3.11.0` and `v2.3.12.0`, which is included in Windows 11 Insider. To fix this ensure WSL `v2.2.4.0` is installed. For more information, see [microsoft/WSL#11794](https://github.com/microsoft/WSL/issues/11794). This affects Docker Desktop 4.33.0 and earlier.

## [4.32.1](#4321)

*2025-01-09*

> Download Docker Desktop
>
> * [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/179691/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) ([checksum](https://desktop.docker.com/mac/main/arm64/179691/checksums.txt))
> * [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/179691/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) ([checksum](https://desktop.docker.com/mac/main/amd64/179691/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-58)

#### [For Mac](#for-mac-46)

* Prevents a bug that caused Docker Desktop to not update `com.docker.vmnetd` or `com.docker.socket` to newer versions.

### [Known issues](#known-issues-20)

#### [For Mac](#for-mac-47)

* If you’re seeing a security popup about malware on `com.docker.vmnetd` or `com.docker.socket`, follow the steps documented in [docker/for-mac#7527](https://github.com/docker/for-mac/issues/7527).

## [4.32.0](#4320)

*2024-07-04*

### [New](#new-34)

* Docker Engine and CLI updated to version 27.0.
* Docker Desktop now supports moving data to a different drive on macOS and Windows with WSL2 backend. See [docker/for-win#13384](https://github.com/docker/for-win/issues/13384).
* You can now [schedule backups for volume exports](https://docs.docker.com/desktop/use-desktop/volumes/) in the **Volumes** tab (Beta).
* Access a terminal shell directly from Docker Desktop (Beta).

### [Upgrades](#upgrades-24)

* [Docker Buildx v0.15.1](https://github.com/docker/buildx/releases/tag/v0.15.1)
* [Docker Compose v2.28.1](https://github.com/docker/compose/releases/tag/v2.28.1)
* [Docker Scout CLI v1.10.0](https://github.com/docker/scout-cli/releases/tag/v1.10.0)
* [Docker Engine v27.0.3](https://docs.docker.com/engine/release-notes/27/#2703)
* Docker Init v1.3.0

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-59)

#### [For all platforms](#for-all-platforms-57)

* Improved instructions for `watch` in the Compose File Viewer

* Added support for Golang projects that don't have dependencies in Docker Init. Addresses [docker/roadmap#611](https://github.com/docker/roadmap/issues/611)

* [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) now lets admins set the default value to `ProxyEnableKerberosNTLM`.

* Removed a temporary compatibility fix for older versions of Visual Studio Code.

* Builds view:

  * Changed icon for imported build record to a "files" icon.
  * Improved the error message when trying to connect to an already connected Docker Build Cloud builder.
  * Fixed an issue where build records would disappear unexpectedly.
  * Fixed an issue that prevented users from being able to re-open an [imported build](https://docs.docker.com/desktop/use-desktop/builds/#import-builds).
  * Fixed an issue where build details were not displayed when a build's state had changed from running to completed.
  * Fixed malformed build source link in build details.
  * Fixed missing build stats for named contexts.
  * Fixed image index/manifest not being displayed anymore in build results.
  * Fixed an issue where build traces exported from the UI would appear as a single, flattened list when imported to Jaeger
  * Fixed truncated digest/sha in build details.
  * Fixed final status animation of active builds.

#### [For Windows](#for-windows-42)

* Fixed an issue on the WSL 2 engine where Docker Desktop would not detect the existence of the `docker-desktop-data` distribution if it had been manually moved by the user.
* The Windows on ARM installer and the [privileged service](https://docs.docker.com/desktop/setup/install/windows-permission-requirements/#privileged-helper) are now built for ARM64.

#### [For Mac](#for-mac-48)

* Re-added `CONFIG_DM_CRYPT` kernel module.
* Re-added `CONFIG_PSI` kernel module.
* Re-added `CONFIG_GTP` kernel module.
* Re-added `CONFIG_NFT_BRIDGE_META` kernel module.
* Fixed a regression where the **Another application changed your Desktop configuration** warning message appeared whenever `/var/run/docker.socket` was pointing to an unexpected path.
* Changed the Configuration Check menu entry and banner to a notification.
* Improved the performance of read and write operations on bind mounts.
* Fixed fatal errors with some `AMD64` Java images. Fixes [docker/for-mac/7286](https://github.com/docker/for-mac/issues/7286) and [docker/for-mac/7006](https://github.com/docker/for-mac/issues/7006).
* Fixed an issue that caused Docker Desktop to remove `Docker.app` when installing from `/Applications`.
* Fixed an issue that caused bind mounts to fail. Fixes [docker/for-mac#7274](https://github.com/docker/for-mac/issues/7274).

### [Known issues](#known-issues-21)

#### [For all platforms](#for-all-platforms-58)

* The **Manage Synchronized File Shares with Compose** setting is automatically enabled for all users who opt into **Access experimental features**. This converts all bind mounts into synchronized file shares. To disable this behavior, deselect **Access experimental features**. Then, manually delete any file shares by going to the **File sharing** tab within **Resources**, navigating to the **Synchronized file shares** section, selecting the file shares you want to remove, and selecting **Delete**.

#### [For Mac](#for-mac-49)

* When running `docker-compose` after an update, it will return `command not found`. As a workaround, you can create the following symlink: `sudo ln -sf /Applications/Docker.app/Contents/Resources/cli-plugins/docker-compose /usr/local/bin/docker-compose`

## [4.31.1](#4311)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-60)

#### [For Windows](#for-windows-43)

* Fixed a bug where containers, images and volumes created before the update were potentially invisible for users. Fixes [docker/for-win#14118](https://github.com/docker/for-win/issues/14118).

## [4.31.0](#4310)

### [New](#new-35)

* [Air-Gapped Containers](https://docs.docker.com/enterprise/security/hardened-desktop/air-gapped-containers/) is now generally available.
* Docker Compose File Viewer shows your Compose YAML with syntax highlighting and contextual links to relevant docs (Beta, progressive rollout).
* New Sidebar user experience.

### [Upgrades](#upgrades-25)

* [Docker Engine and CLI v26.1.4](https://github.com/moby/moby/releases/tag/v26.1.4).
* [Docker Scout CLI v1.9.1](https://github.com/docker/scout-cli/releases/tag/v1.9.1)
* [Docker Compose v2.27.1](https://github.com/docker/compose/releases/tag/v2.27.1)
* [Docker Buildx v0.14.1](https://github.com/docker/buildx/releases/tag/v0.14.1)
* [Containerd v1.6.33](https://github.com/containerd/containerd/releases/tag/v1.6.33)
* [Credential Helpers v0.8.2](https://github.com/docker/docker-credential-helpers/releases/tag/v0.8.2)
* [NVIDIA Container Toolkit v1.15.0](https://github.com/NVIDIA/nvidia-container-toolkit/releases/tag/v1.15.0)
* [Go 1.22.4](https://github.com/golang/go/releases/tag/go1.22.4)
* Linux kernel `v6.6.31`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-61)

#### [For all platforms](#for-all-platforms-59)

* Newer releases are now displayed in the **Software updates** settings tab when an update has already been downloaded.

* Added `proxyEnableKerberosNTLM` config to `settings.json` to enable fallback to basic proxy authentication if Kerberos/NTLM environment is not properly set up.

* Fixed a bug where Docker Debug was not working properly with Enhanced Container Isolation enabled.

* Fixed a bug where UDP responses were not truncated properly.

* Fixed a bug where the **Update** screen was hidden when using [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/).

* Fixed a bug where proxy settings defined in `admin-settings.json` were not applied correctly on startup.

* Fixed a bug where the **Manage Synchronized file shares with Compose** toggle did not correctly reflect the value with the feature.

* Fixed a bug where a bind mounted file modified on host is not updated after the container restarts, when gRPC FUSE file sharing is used on macOS and on Windows with Hyper-V. Fixes [docker/for-mac#7274](https://github.com/docker/for-mac/issues/7274), [docker/for-win#14060](https://github.com/docker/for-win/issues/14060).

* Builds view:

  * New [Import builds](https://docs.docker.com/desktop/use-desktop/builds/#import-builds) feature that lets you import build records for builds by other people, or [builds in a CI environment](https://docs.docker.com/build/ci/github-actions/build-summary/).
  * Fixed missing OpenTelemetry traces in build results for failed builds.
  * Fixed `default-load` appearing as invalid driver-opt for the container driver.
  * Fixed deep link to build details.

#### [For Windows](#for-windows-44)

* Changed the `--allowed-org` installer flag to write a policy registry key instead of to the `registry.json`.

#### [For Mac](#for-mac-50)

* Moved the setting **Automatically check configuration** from **Advanced** settings to **General** settings.
* Improved VirtioFS caching by implementing longer attributes timeout and invalidation.

#### [For Linux](#for-linux-9)

* Added Linux headers to the VM, to ease the compilation of custom kernel modules.

### [Security](#security-20)

#### [For all platforms](#for-all-platforms-60)

* Fixed a security bug in Enhanced Container Isolation (ECI) mode where a user could create Docker volumes sourced from restricted directories inside the Docker Desktop VM and mount them into containers, thereby giving the container access to such restricted VM directories.
* By default, only extensions listed in the marketplace can be installed in Docker Desktop. This can be changed in Docker Desktop's settings. Extension developers will need to change this option in order to test their extensions.

### [For Windows](#for-windows-45)

* Fixed [CVE-2024-5652](https://www.cve.org/cverecord?id=CVE-2024-5652) in which a user in the `docker-users` group can cause a Windows Denial-of-Service through the `exec-path` Docker daemon config option in Windows containers mode. This vulnerability was discovered by Hashim Jawad ([@ihack4falafel](https://github.com/ihack4falafel)) working with Trend Micro Zero Day Initiative.

### [Deprecation](#deprecation-2)

#### [For all platforms](#for-all-platforms-61)

* The CLI binary that used to be shipped as `com.docker.cli` is now shipped simply as `docker`. This release leaves the CLI binary as `com.docker.cli`, but it will be removed next release.

#### [For Windows](#for-windows-46)

* Removed support for legacy version packs from the WSL2 engine.

### [Known Issues](#known-issues-22)

#### [For Windows](#for-windows-47)

* When upgrading to Docker Desktop 4.31.0, existing containers, images and volumes become invisible for users that created those containers and images using Docker Desktop 4.8.0 or lower, on Windows hosts with WSL only. The data is not lost, it just becomes invisible to Docker Desktop 4.31.0. If impacted, downgrade to version 4.30 or earlier. For more information see: [docker/for-win#14118](https://github.com/docker/for-win/issues/14118).

#### [For Linux](#for-linux-10)

* Ubuntu 24.04 LTS is not yet supported, Docker Desktop will fail to start. Due to a change in how the latest Ubuntu release restricts the unprivileged namespaces, `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0` needs to be ran at least once. Refer to the [Ubuntu Blog](https://ubuntu.com/blog/).

## [4.30.0](#4300)

*2024-05-06*

### [New](#new-36)

#### [For all platforms](#for-all-platforms-62)

* Docker Desktop now supports [SOCKS5 proxies](https://docs.docker.com/desktop/features/networking/#socks5-proxy-support). Requires a Business subscription.
* Added a new setting to manage the onboarding survey in [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/).

#### [For Windows](#for-windows-48)

* Added support for [Kerberos and NTLM proxy authentication](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxy-authentication) on Windows. Requires a Business subscription.

### [Upgrades](#upgrades-26)

* [Docker Compose v2.27.0](https://github.com/docker/compose/releases/tag/v2.27.0)

* [Docker Engine v26.1.1](https://docs.docker.com/engine/release-notes/26.1/#2611)

* [Wasm](https://docs.docker.com/desktop/features/wasm/) runtimes:

  * Updated `runwasi` shims to `v0.4.0`
  * Updated `deislabs` shims to `v0.11.1`
  * Updated `spin` shim to `v0.13.1`

* [Docker Scout CLI v1.8.0](https://github.com/docker/scout-cli/releases/tag/v1.8.0)

* Docker Debug `v0.0.29`

* Linux kernel `v6.6.26`

* [Go 1.22.2](https://github.com/golang/go/releases/tag/go1.22.2)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-62)

#### [For all platforms](#for-all-platforms-63)

* Improved Enhanced Container Isolation (ECI) security when running `docker build` commands in rootless containers.

* Fixed a bug where `docker events` exited with `Unexpected EOF` when Docker Desktop entered/exited Resource Saver mode.

* Fixed a bug where `docker stats --no-stream` hung when Docker Desktop was in Resource Saver mode.

* Fixed a bug in the self-diagnose CLI that incorrectly showed the VM had not started. Fixes [docker/for-mac#7241](https://github.com/docker/for-mac/issues/7241).

* Fixed a bug where high-throughput port forward transfers could stall. Fixes [docker/for-mac#7207](https://github.com/docker/for-mac/issues/7207).

* Fixed CLI-plugin symlinks not being removed when CLI apps were removed.

* Fixed a bug in the shared ports drawer to show the right message for local engines.

* Dev Environments is being sunset and has moved to the **Beta** tab in **Features in development**.

* Builds view:

  * Better bulk delete for build records.
  * Added action to open the relevant web page for container images and Git sources in build dependencies.
  * Added action to download Provenance and OpenTelemetry traces in Jaeger or OTLP format.
  * Fixed source details for remote build invocations.
  * Fixed a bug where multi-platform builds would show up as separate records when using a cloud builder.

#### [For Mac](#for-mac-51)

* Fixed a bug where a segmentation fault was triggered with Virtualization Framework, on post-2019 Macs. See [docker/for-mac#6824](https://github.com/docker/for-mac/issues/6824).
* Enabled `CONFIG_SECURITY=y` kernel config, for example for [Tetragon](https://tetragon.io/). Fixes [docker/for-mac#7250](https://github.com/docker/for-mac/issues/7250).
* Re-added support for `SQUASHFS` compression. Fixes [docker/for-mac#7260](https://github.com/docker/for-mac/issues/7260).
* Fixed a bug that caused a new version of Docker Desktop to be marked as damaged.
* Increased network MTU when using qemu on Apple Silicon.
* Fixed a bug preventing Docker Desktop to start if Rosetta was not installed. Fixes [docker/for-mac#7243](https://github.com/docker/for-mac/issues/7243).

#### [For Windows](#for-windows-49)

* Added a simplified provisioning mode for WSL2 that avoids the need for the ancillary `docker-desktop-data` WSL distribution (experimental).
* Fixed bash completions for the Docker CLI in a WSL environment.
* Fixed a regression in Docker Desktop 4.28 that caused host files bind-mounted into containers to not show up properly inside the container, when using Docker-in-Docker (via mounts of `/var/run/docker.sock`) on WSL.
* Fixed a bug that would cause the following error `merging settings: integratedWslDistros type mismatch`.

### [Known issues](#known-issues-23)

#### [For all platforms](#for-all-platforms-64)

* If you have enabled a feature in Docker Desktop that requires you to be signed in, such as **Host networking** you must remain signed in to use Docker Desktop. To continue using Docker Desktop or to modify these settings, ensure you are signed in.
* To enable or disable **Manage Synchronized file shares with Compose**, **Access experimental features** and **Manage Synchronized file shares with Compose** have to be checked or unchecked at the same time.
* The Docker CLI will sometimes hang when running a container with the autoremove option (`--rm`) if the container fails to start (e.g.: `docker run --rm alpine invalidcommand`). In this case, the CLI process may need to be manually killed.

#### [For Windows](#for-windows-50)

* When starting Docker Desktop as a non-admin user, the following error connect `ENOENT \\.\pipe\errorReporter` might be triggered if the user is not a member of the **docker-users** group. This can be resolved by adding the user to the **docker-users** group. Before starting Docker Desktop, make sure to sign out and then sign back in and unregister `docker-desktop` distribution if that was created, using `wsl --unregister docker-desktop`.

#### [For Linux](#for-linux-11)

* Ubuntu 24.04 LTS is not yet supported, Docker Desktop will fail to start. Due to a change in how the latest Ubuntu release restricts the unprivileged namespaces, `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0` needs to be ran at least once. Refer to the [Ubuntu Blog](https://ubuntu.com/blog/ubuntu-23-10-restricted-unprivileged-user-namespaces) for more details.

## [4.29.0](#4290)

*2024-04-08*

### [New](#new-37)

* You can now enforce Rosetta usage via [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/).

* [Docker socket mount restrictions](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/) with ECI is now generally available.

* Docker Engine and CLI updated to [Moby 26.0](https://github.com/moby/moby/releases/tag/v26.0.0). This includes Buildkit 0.13, sub volumes mounts, networking updates, and improvements to the containerd multi-platform image store UX.

* New and improved Docker Desktop error screens: swift troubleshooting, easy diagnostics uploads, and actionable remediation.

* Compose supports [Synchronized file shares (experimental)](https://docs.docker.com/desktop/features/synchronized-file-sharing/).

* New [interactive Compose CLI (experimental)](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_menu).

* Beta release of:

  * Air-Gapped Containers with [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/air-gapped-containers/).
  * [Host networking](https://docs.docker.com/engine/network/drivers/host/#docker-desktop) in Docker Desktop.
  * [Docker Debug](https://docs.docker.com/desktop/use-desktop/container/#integrated-terminal) for running containers.
  * [Volumes Backup & Share extension](https://docs.docker.com/desktop/use-desktop/volumes/) functionality available in the **Volumes** tab.

### [Upgrades](#upgrades-27)

* [Docker Compose v2.26.1](https://github.com/docker/compose/releases/tag/v2.26.1)
* [Docker Scout CLI v1.6.3](https://github.com/docker/scout-cli/releases/tag/v1.6.3)
* [Docker Engine v26.0.0](https://docs.docker.com/engine/release-notes/26.0/#2600)
* [Buildx v0.13.1](https://github.com/docker/buildx/releases/tag/v0.13.1)
* [Kubernetes v1.29.2](https://github.com/kubernetes/kubernetes/releases/tag/v1.29.2)
* [cri-dockerd v0.3.11](https://github.com/Mirantis/cri-dockerd/releases/tag/v0.3.11)
* Docker Debug v0.0.27

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-63)

#### [For all platforms](#for-all-platforms-65)

* Fixed an issue with dropdown menu opening beyond the application window.

* Docker Init:

  * Updated the formatting of CLI output to improve legibility.
  * Fixed an issue with `.dockerignore` to avoid ignoring application files that start with "compose".
  * Improved how Java applications are started based on Spring Boot version. Fixes [docker/for-mac#7171](https://github.com/docker/for-mac/issues/7171).
  * Removed non-official Docker image used for Rust cross-compilation.

* The maximum number of files per [Synchronized file share](https://docs.docker.com/desktop/features/synchronized-file-sharing/) now exceeds 2 million.

* Fixed an issue that caused the warning: "*The value provided to Autocomplete is invalid.*" when selecting the **Export to local image** field.

* **Run Cloud** can now be accessed from the Docker Desktop Dashboard.

* Opting out from sending analytics will now also disable collecting data for bug reports.

* You can now share and unshare a port to the Cloud Engine in the **Containers** view.

* Shared cloud can now be accessed from the footer in the right-hand side of the **Dashboard**.

* Added beta support for host networking on macOS, Windows and Docker Desktop for Linux [docker#238](https://github.com/docker/roadmap/issues/238).

* Added a timestamp to new unread notifications.

* Fixed typo in the virtualization support error message. Fixes [docker/desktop-linux#197](https://github.com/docker/desktop-linux/issues/197).

* Docker Desktop now allows connections to `host.docker.internal` to be blocked by a rule in a PAC file.

* Fixed the placement of the secondary menu in the **Images** and **Containers** lists.

* Fixed a race condition that occurred when starting Docker Desktop with QEMU.

* Improved the error message when an image pull is blocked by Registry Access Management policy.

* Re-add `CONFIG_BONDING=y` in the kernel config.

#### [For Mac](#for-mac-52)

* Fixed Kubernetes not starting successfully. Fixes [docker/for-mac#7136](https://github.com/docker/for-mac/issues/7136) and [docker/for-mac#7031](https://github.com/docker/for-mac/issues/7031).
* Fixed a bug when the browser was not able to send back authentication information to Docker Desktop. Fixes [docker/for-mac/issues#7160](https://github.com/docker/for-mac/issues/7160).

#### [For Windows](#for-windows-51)

* Fixed a bug where `docker run -v` would fail after switching between WSL 2 and Hyper-V.
* Fixed a bug where Docker Desktop was not stopping its WSL distributions (`docker-desktop` and `docker-desktop-data`) when it was shutdown. Fixes [docker/for-win/issues/13443](https://github.com/docker/for-win/issues/13443) and [docker/for-win/issues/13938](https://github.com/docker/for-win/issues/13938).

#### [For Linux](#for-linux-12)

* Fixed an issue that caused the list of available experimental features in the UI to become out-of-sync with the backend data.

#### [Security](#security-21)

* Disabled Electron `runAsNode` fuse to improve security hardening. For more info, see [Electron's documentation.](https://www.electronjs.org/blog/statement-run-as-node-cves).
* Fixed [CVE-2024-6222](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-6222) which allows an attacker who has gained access to the Docker Desktop VM through a container breakout to further escape to the host by passing extensions and dashboard related IPC messages. Reported by Billy Jheng Bing-Jhong, Đỗ Minh Tuấn, Muhammad Alifa Ramdhan working with Trend Micro Zero Day Initiative.

### [Known issues](#known-issues-24)

#### [For Mac](#for-mac-53)

* Docker Desktop on Apple Silicon doesn't start if Rosetta is not installed. This will be fixed in future releases. See [docker/for-mac#7243](https://github.com/docker/for-mac/issues/7243).

## [4.28.0](#4280)

*2024-02-26*

### [New](#new-38)

* [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) now allows admins to set the default file-sharing implementation and specify which paths developer can add file shares to.
* Added support for `socks5://` HTTP and HTTPS proxy URLs when the [`SOCKS` proxy support beta feature](https://docs.docker.com/desktop/features/networking/) is enabled.
* Users can now filter volumes to see which ones are in use in the **Volumes** tab.

### [Upgrades](#upgrades-28)

* [Compose v2.24.6](https://github.com/docker/compose/releases/tag/v2.24.6)

* [Docker Engine v25.0.3](https://docs.docker.com/engine/release-notes/25.0/#2503)

* [Docker Scout CLI v1.5.0](https://github.com/docker/scout-cli/releases/tag/v1.5.0)

* [Qemu 8.1.5](https://wiki.qemu.org/ChangeLog/8.1)

* [Wasm](https://docs.docker.com/desktop/features/wasm/) runtimes:

  * Updated runwasi shims to `v0.4.0`, including:

    * wasmtime `v17.0`, with initial support for WASI preview 2
    * wasmedge `v0.13.5`
    * wasmer `v4.1.2`

  * Updated deislabs shims to `v0.11.1`, including:

    * lunatic `v0.13.2`
    * slight `v0.5.1`
    * spin `v2.2.0`
    * wws `v1.7.0`

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-64)

#### [For all platforms](#for-all-platforms-66)

* Fixed `postgis` with `Qemu`. Fixes [docker/for-mac#7172](https://github.com/docker/for-mac/issues/7172).

* Re added `CONFIG_BLK_DEV_DM` kernel config for `kpartx`. Fixes [docker/for-mac#7197](https://github.com/docker/for-mac/issues/7197).

* Allow `SOCKS` proxies to be set via a proxy autoconfig `pac file`.

* Re added `CONFIG_AUDIT` kernel config.

* Fixed a bug with the Rust build on `virtiofs`. See [rust-lang/docker-rust#161](https://github.com/rust-lang/docker-rust/issues/161).

* Fixed an issue that caused the `missing registry authentication` error when pulling Kubernetes images.

* Fixed an issue that caused Docker Compose commands to hang.

* Fixed a bug in `docker build` that caused Docker Desktop to crash. Fixes [docker/for-win#13885](https://github.com/docker/for-win/issues/13885), [docker/for-win#13896](https://github.com/docker/for-win/issues/13896), [docker/for-win#13899](https://github.com/docker/for-win/issues/13899), [docker/for-mac#7164](https://github.com/docker/for-mac/issues/7164), [docker/for-mac#7169](https://github.com/docker/for-mac/issues/7169)

* Docker Init:

  * Improved how Java applications are started based on Spring Boot version. Fixes [docker/for-mac#7171](https://github.com/docker/for-mac/issues/7171).
  * Removed non-official Docker image used for Rust cross-compilation

* Builds view:

  * Active and completed builds can be found in dedicated tabs.
  * Build details now displays build duration and cache steps.
  * OpenTelemetry traces are now displayed in the build results.
  * Fixed an issue where context builders events were not always triggered.
  * Restyle the empty state view to make the dashboard clearer.

#### [For Mac](#for-mac-54)

* Fix `httpd` issue with Rosetta. [docker/for-mac#7182](https://github.com/docker/for-mac/issues/7182)
* Fixed a bug that caused a crash on the `virtualization.framework`. Fixes [docker/for-mac#7024](https://github.com/docker/for-mac/issues/7024)

#### [For Windows](#for-windows-52)

* Fixed an issue with DNS timeouts on Windows.
* Added support for Enhanced Container Isolation Docker socket mount permission on WSL user distributions.
* Fixed an issue that caused the `failed to get console mode` error when redirecting output from the CLI.
* Fixed an issue with the engine socket permissions when mounted inside containers. Fixes [docker/for-win#13898](https://github.com/docker/for-win/issues/13898)

### [Known Issues](#known-issues-25)

#### [For Windows](#for-windows-53)

* In dark mode, the **Disk image location** in **Resources**>**Advanced** settings is not visible. As a workaround, change to light mode.

## [4.27.2](#4272)

*2024-02-08*

### [Upgrades](#upgrades-29)

* [Compose v2.24.5](https://github.com/docker/compose/releases/tag/v2.24.5)
* [Docker Scout CLI v1.4.1](https://github.com/docker/scout-cli/releases/tag/v1.4.1)
* Docker Debug v0.0.24

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-65)

#### [For all platforms](#for-all-platforms-67)

* Fixed a bug where the diagnostics ID would not print correctly when uploading diagnostics from the terminal.

* Fixed a bug where the default settings values were being reset to default on startup, when using Settings Management.

* Fixed a bug with the dashboard being shown at startup even though the **Open Docker Dashboard when Docker Desktop starts** option was disabled. Fixes [docker/for-win#13887](https://github.com/docker/for-win/issues/13887).

* Fixed a bug in the build backend service that caused Docker Desktop to crash. Fixes [docker/for-win#13885](https://github.com/docker/for-win/issues/13885), [docker/for-win#13896](https://github.com/docker/for-win/issues/13896), [docker/for-win#13899](https://github.com/docker/for-win/issues/13899), [docker/for-mac#7164](https://github.com/docker/for-mac/issues/7164), [docker/for-mac#7169](https://github.com/docker/for-mac/issues/7169).

* Fixed the Docker Engine socket permissions when mounted inside containers. Fixes [docker/for-win#13898](https://github.com/docker/for-win/issues/13898).

* Docker Scout:

  * Updated dependencies to address Leaky Vessels series of CVEs ([CVE-2024-21626](https://github.com/advisories/GHSA-xr7r-f8xq-vfvv), [CVE-2024-24557](https://github.com/advisories/GHSA-xw73-rw38-6vjc))
  * Added initial VEX document to document false positive [CVE-2020-8911](https://github.com/advisories/GHSA-f5pg-7wfw-84q9) and [CVE-2020-8912](https://github.com/advisories/GHSA-7f33-f4f5-xwgw)
  * Added support for cosign SBOM attestations
  * Added support for VEX in-toto attestations

* Docker Debug:

  * Fixed a bug when pulling the image behind resource accesses management
  * Fixed connection issues

#### [For Mac](#for-mac-55)

* Re-added kernel modules needed by `Istio`. Fixes [docker/for-mac#7148](https://github.com/docker/for-mac/issues/7148).
* Node now uses all the cores available under Rosetta.
* Fixed an issue with `php-fpm`. Fixes [docker/for-mac#7037](https://github.com/docker/for-mac/issues/7037).

## [4.27.1](#4271)

*2024-02-01*

### [Upgrades](#upgrades-30)

* [Docker Engine v25.0.2](https://docs.docker.com/engine/release-notes/25.0/#2502) which contains a fix for [CVE-2024-24557](https://scout.docker.com/vulnerabilities/id/CVE-2024-24557), [CVE-2024-23650](https://scout.docker.com/vulnerabilities/id/CVE-2024-23650), [CVE-2024-23651](https://scout.docker.com/vulnerabilities/id/CVE-2024-23651), [CVE-2024-23652](https://scout.docker.com/vulnerabilities/id/CVE-2024-23652) and [CVE-2024-23653](https://scout.docker.com/vulnerabilities/id/CVE-2024-23653)
* [Containerd v1.6.28](https://github.com/containerd/containerd/releases/tag/v1.6.28)
* [Runc v1.1.12](https://github.com/opencontainers/runc/releases/tag/v1.1.12) which contains a fix for [CVE-2024-21626](https://scout.docker.com/vulnerabilities/id/CVE-2024-21626)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-66)

#### [For Mac](#for-mac-56)

* Fixed a bug that caused Docker Desktop to hang when applying an update.

## [4.27.0](#4270)

*2024-01-25*

### [New](#new-39)

* Docker init now supports Java and is generally available to all users.
* [Synchronized File Shares](https://docs.docker.com/desktop/features/synchronized-file-sharing/) provides fast and flexible host-to-VM file sharing within Docker Desktop. Utilizing the technology behind [Docker’s acquisition of Mutagen](https://www.docker.com/blog/mutagen-acquisition/), this feature provides an alternative to virtual bind mounts that uses synchronized filesystem caches, improving performance for developers working with large codebases.
* Organization admins can now [configure Docker socket mount permissions](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/) when ECI is enabled.
* [Containerd Image Store](https://docs.docker.com/desktop/features/containerd/) support is now generally available to all users.
* Get a debug shell into any container or image with the new [`docker debug` command](/reference/cli/docker/debug/) (Beta).
* Organization admins, with a Docker Business subscription, can now configure a custom list of extensions with [Private Extensions Marketplace](https://docs.docker.com/extensions/private-marketplace/) enabled (Beta)

### [Upgrades](#upgrades-31)

* [Amazon ECR Credential Helper v0.7.1](https://github.com/awslabs/amazon-ecr-credential-helper/releases/tag/v0.7.1)
* [Buildx v0.12.1](https://github.com/docker/buildx/releases/tag/v0.12.1)
* [Containerd v1.6.27](https://github.com/containerd/containerd/releases/tag/v1.6.27)
* [Compose v2.24.3](https://github.com/docker/compose/releases/tag/v2.24.3)
* [Docker Credential Helpers v0.8.1](https://github.com/docker/docker-credential-helpers/releases/tag/v0.8.1)
* [Runc v1.1.11](https://github.com/opencontainers/runc/releases/tag/v1.1.11)
* [Docker Engine v25.0.0](https://docs.docker.com/engine/release-notes/25.0/)
* [Kubernetes v1.29.1](https://github.com/kubernetes/kubernetes/releases/tag/v1.29.1)
* [Docker Scout v1.3.0](https://github.com/docker/scout-cli/releases/tag/v1.3.0)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-67)

#### [For all platforms](#for-all-platforms-68)

* The `docker scan` command has been removed. To continue learning about the vulnerabilities of your images, and many other features, use the [`docker scout` command](/reference/cli/docker/scout/).

* Fixed a bug where automatic updates would not download when the **Always download updates** checkbox was selected.

* Fixed typo in the dashboard tooltip. Fixes [docker/for-mac#7132](https://github.com/docker/for-mac/issues/7132)

* Improved signal handling behavior (e.g. when pressing Ctrl-C in the terminal while running a `docker` command).

* Re-added kernel modules required by `minikube start --cni=cilium`.

* Fixed a bug that caused the installation screen to appear again when admin controls are enabled after sign in.

* Fixed a bug where Docker would not start if a shared folder is no longer present.

* Fixed the number of available CPUs displayed in the **Containers** section of the Dashboard.

* Re-added kernel modules for `btrfs`, `xfs`, `vfat`, `exfat`, `ntfs3`, `f2fs`, `squashfs`, `udf`, `9p` and `autofs`.

* Container usage charts have been moved to a vertical **Resource usage** side panel to allow for more space in the containers list. Accessing the usage charts remains the same via the **Show charts** button.

* Fixed a bug where selecting **Close Application** at sign-in was leaving behind a hung backend process.

* Fixed a bug which caused Docker Desktop to become unresponsive when analytics is disabled through Settings Management.

* Docker init:

  * Added support for containerizing a Java server
  * Various fixes on Windows

* Builder settings:

  * You can now refresh storage data for your builder at any point in time.
  * You can now delete the build history for a builder.

* Builds view:

  * An error message is now shown when a build record cannot be removed.
  * Fixed an issue where a cloud builder could not be created in rootless mode on macOS.
  * Inline cache and Git source are now properly handled in the **Build timing** section of the **Info** tab.
  * The Builder used and the author invoking the build is now displayed in past builds on the **History** tab.
  * Several improvements made to better link past builds on the **History** tab.
  * Several improvements to make the build name more accurate.
  * Fixed stuck builds in the **Active builds** list when a builder cannot be reached.
  * Fixed an issue preventing the build record from being deleted in some circumstances.
  * Fixed an issue where build names could be empty.
  * Fixed a general issue with the Builds view when Resource saver mode is enabled.

#### [For Mac](#for-mac-57)

* Enabled `Huge Pages` and fixed PHP segmentation fault with Rosetta. Fixes [docker/for-mac#7117](https://github.com/docker/for-mac/issues/7117).
* Fixed `xvfb` under Rosetta. Fixes [docker/for-mac#7122](https://github.com/docker/for-mac/issues/7122)
* Fixed `ERR_WORKER_INVALID_EXEC_ARGV` error under Rosetta. [docker/for-mac#6998](https://github.com/docker/for-mac/issues/6998).
* Fixed a bug where Docker Desktop could deadlock if `admin-settings.json` was syntactically invalid.

#### [For Windows](#for-windows-54)

* Fixed a bug that prevented UTF-16 strings from being encoded to UTF-8 for some locales. Fixes [docker/for-win#13868](https://github.com/docker/for-win/issues/13868).
* Fixed a bug where the credentials store configuration would reset on app restart with the WSL integration. Fixes [docker/for-win#13529](https://github.com/docker/for-win/issues/13529).
* Fixed an issue that prevented the correct WSL engine errors from propagating to the user.
* Fixed an issue that would cause Docker Desktop to hang when quitting from Windows Containers mode.

### [Security](#security-22)

#### [For Windows](#for-windows-55)

* Mitigated several DLL side-loading vulnerabilities in the Docker Desktop installer on Windows, reported by Suman Kumar Chakraborty ([@Hijack-Everything](https://github.com/Hijack-Everything))

### [Known issues](#known-issues-26)

#### [For all platforms](#for-all-platforms-69)

* When using Setting Management, the settings that are not set in the `admin-settings.json` will be reset to default when Docker Desktop starts.

#### [For Mac](#for-mac-58)

* Updating to 4.27.0 from the **Software updates** sometimes hangs. As a workaround, use the 4.27.0 installer from this page.

## [4.26.1](#4261)

*2023-12-14*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-68)

#### [For all platforms](#for-all-platforms-70)

* Updated feedback links inside Docker Desktop to ensure they continue to work correctly

#### [For Windows](#for-windows-56)

* Switch the CLI binaries to a version compatible with older versions of glibc, such as used in Ubuntu 20.04 fixes [docker/for-win#13824](https://github.com/docker/for-win/issues/13824)

## [4.26.0](#4260)

*2023-12-04*

### [New](#new-40)

* Administrators can now control access to beta and experimental features in the **Features in development** tab with [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/).
* Introduced four new version update states in the footer.
* `docker init` (Beta) now supports PHP with Apache + Composer.
* The [**Builds** view](https://docs.docker.com/desktop/use-desktop/builds/) is now GA. You can now inspect builds, troubleshoot errors, and optimize build speed.

### [Upgrades](#upgrades-32)

* [Compose v2.23.3](https://github.com/docker/compose/releases/tag/v2.23.3)

* [Docker Scout CLI v1.2.0](https://github.com/docker/scout-cli/releases/tag/v1.2.0).

* [Buildx v0.12.0](https://github.com/docker/buildx/releases/tag/v0.12.0)

* [Wasm](https://docs.docker.com/desktop/features/wasm/) runtimes:

  * wasmtime, wasmedge and wasmer `v0.3.1`.
  * lunatic, slight, spin, and wws `v0.10.0`.
  * Wasmtime is now based on wasmtime `v14.0` and supports wasi preview-2 components
  * Wasmedge is now based on WasmEdge `v0.13.5`
  * Spin is now based on Spin `v2.0.1`
  * wws is now based on wws `v1.7.0`

* [Docker Engine v24.0.7](https://docs.docker.com/engine/release-notes/24.0/#2407)

* [Containerd v1.6.25](https://github.com/containerd/containerd/releases/tag/v1.6.25)

* [runc v1.1.10](https://github.com/opencontainers/runc/releases/tag/v1.1.10)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-69)

#### [For all platforms](#for-all-platforms-71)

* You can now provide feedback from the commandline by using `docker feedback`.

* Improved the text and position of the startup options in the **General** settings tab.

* Redesigned the dashboard's header bar, added links to other Docker resources, improved display of account information.

* Fixed a bug where enabling the containerd image store and Wasm simultaneously would not enable Wasm.

* containerd integration:

  * Fixed `docker push/pull` authentication not being sent to non-DockerHub registries in cases where `ServerAddress` is not provided.
  * Fixed `docker history` reporting wrong IDs and tags.
  * Fixed `docker tag` not preserving internal metadata.
  * Fixed `docker commit` when the daemon configured with `--userns-remap`.
  * Fixed `docker image list` to show real image creation date.
  * Added support for `-a` flag to `docker pull` (pull all remote repository tags).
  * Added support for `--group-add` flag to `docker run` (append extra groups).
  * Adjusted some errors reported by `docker push/pull`.

* Docker Init:

  * Improved cross-compilation in Dockerfiles for Golang and Rust.
  * Improved caching in Dockerfile for ASP.NET Core.

* Docker Desktop now gives more detailed information about pending updates in the dashboard footer.

* Fixed a bug in Enhanced Container Isolation mode where `docker run --init` was failing.

* Fixed a bug where a notification prompting the user to download a new version of Docker Desktop remained visible after the user started downloading the new version.

* Added a notification that indicates when Docker Desktop is installing a new version.

* Fixed a bug where the cursor changed to a pointer when the user hovered over a notification that has no call to action.

#### [For Mac](#for-mac-59)

* Fixed an issue where Rosetta would not work with PHP. Fixes [docker/for-mac#6773](https://github.com/docker/for-mac/issues/6773) and [docker/for-mac#7037](https://github.com/docker/for-mac/issues/7037).
* Fixed several issues related to Rosetta not working. Fixed \[[docker/for-mac#6973](https://github.com/docker/for-mac/issues/6973), \[[docker/for-mac#7009](https://github.com/docker/for-mac/issues/7009), \[[docker/for-mac#7068](https://github.com/docker/for-mac/issues/7068) and \[[docker/for-mac#7075](https://github.com/docker/for-mac/issues/7075)
* Improved the performance of NodeJS under Rosetta.
* Fixed the **Unable to open /proc/self/exe** Rosetta errors.
* Fixed a bug were the setting **Start Docker Desktop when you sign in** would not work. Fixes [docker/for-mac#7052](https://github.com/docker/for-mac/issues/7052).
* You can now enable the use of Kernel networking path for UDP through the UI. Fixes [docker/for-mac#7008](https://github.com/docker/for-mac/issues/7008).
* Fixed a regression where the `uninstall` CLI tool was missing.
* Addressed an issue which caused Docker Desktop to become unresponsive when analytics were disabled with Settings Management.

#### [For Windows](#for-windows-57)

* Added support for WSL mirrored mode networking (requires WSL `v2.0.4` and up).
* Added missing signatures on DLL and VBS files.

### [Known issues](#known-issues-27)

#### [For Windows](#for-windows-58)

* Docker CLI doesn’t work when using WSL 2 integration on an older Linux distribution (for example, Ubuntu 20.04) which uses a `glibc` version older than `2.32`. This will be fixed in future releases. See [docker/for-win#13824](https://github.com/docker/for-win/issues/13824).

## [4.25.2](#4252)

*2023-11-21*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-70)

#### [For all platforms](#for-all-platforms-72)

* Fixed a bug where a blank UI would appear after submitting a response in the **Welcome Survey**.

#### [For Windows](#for-windows-59)

* Fixed a bug where Docker Desktop on WSL 2 would shut down dockerd unexpectedly when idle. Fixes [docker/for-win#13789](https://github.com/docker/for-win/issues/13789)

## [4.25.1](#4251)

*2023-11-13*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-71)

#### [For all platforms](#for-all-platforms-73)

* Fixed a regression in 4.25 where Docker would not start if the swap file was corrupt. Corrupt swap files will be re-created on next boot.
* Fixed a bug when swap is disabled. Fixes [docker/for-mac#7045](https://github.com/docker/for-mac/issues/7045), [docker/for-mac#7044](https://github.com/docker/for-mac/issues/7044) and [docker/for-win#13779](https://github.com/docker/for-win/issues/13779).
* The `sysctl vm.max_map_count` is now set to 262144. See [docker/for-mac#7047](https://github.com/docker/for-mac/issues/7047)

#### [For Windows](#for-windows-60)

* Fixed an issue where **Switch to Windows Containers** would not appear on the tray menu for some users. See [docker/for-win#13761](https://github.com/docker/for-win/issues/13761).
* Fixed a bug where the WSL integration would not work for users using a shell other than `sh`. See [docker/for-win#13764](https://github.com/docker/for-win/issues/13764).
* Re-added `DockerCli.exe`.

## [4.25.0](#4250)

*2023-10-26*

### [New](#new-41)

* Rosetta is now Generally Available for all users on macOS 13 or later. It provides faster emulation of Intel-based images on Apple Silicon. To use Rosetta, see [Settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/). Rosetta is enabled by default on macOS 14.1 and later.
* Docker Desktop now detects if a WSL version is out of date. If an out dated version of WSL is detected, you can allow Docker Desktop to automatically update the installation or you can manually update WSL outside of Docker Desktop.
* New installations of Docker Desktop for Windows now require a Windows version of 19044 or later.
* Administrators now have the ability to control Docker Scout image analysis in [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/).

### [Upgrades](#upgrades-33)

* [Compose v2.23.0](https://github.com/docker/compose/releases/tag/v2.23.0)

* [Docker Scout CLI v1.0.9](https://github.com/docker/scout-cli/releases/tag/v1.0.9).

* [Kubernetes v1.28.2](https://github.com/kubernetes/kubernetes/releases/tag/v1.28.2)

  * [cri-dockerd v0.3.4](https://github.com/Mirantis/cri-dockerd/releases/tag/v0.3.4)
  * [CNI plugins v1.3.0](https://github.com/containernetworking/plugins/releases/tag/v1.3.0)
  * [cri-tools v1.28.0](https://github.com/kubernetes-sigs/cri-tools/releases/tag/v1.28.0)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-72)

#### [For all platforms](#for-all-platforms-74)

* Fixed a spacing problem in the `Accept License` pop-up.

* Fixed a bug where the **Notifications drawer** changed size when navigating between **Notifications list** and **Notification details** view.

* containerd integration:

  * `docker push` now supports `Layer already exists` and `Mounted from` progress statuses.
  * `docker save` is now able to export images from all tags of the repository.
  * Hide push upload progress of manifests, configs and indexes (small json blobs) to match the original push behavior.
  * Fixed `docker diff` containing extra differences.
  * Fixed `docker history` not showing intermediate image IDs for images built with the classic builder.
  * Fixed `docker load` not being able to load images from compressed tar archives.
  * Fixed registry mirrors not working.
  * Fixed `docker diff` not working correctly when called multiple times concurrently for the same container.
  * Fixed `docker push` not reusing layers when pushing layers to different repositories on the same registry.

* Docker Init:

  * Fixed outdated links to Docker documentation included in generated files
  * Add support for ASP.NET Core 8 (in addition to 6 and 7)

* Fixed a bug that caused a failure when installing Wasm shims.

* Fixed a bug where Docker Desktop exits the [Resource Saver mode](https://docs.docker.com/desktop/use-desktop/resource-saver/) every 15 minutes, or, if the timer is set above 15 minutes, the resource saver mode never kicks in.

* Promoted the **Enable background SBOM indexing** option to **General settings**.

#### [For Mac](#for-mac-60)

* Minimum OS version to install or update Docker Desktop on macOS is now macOS Monterey (version 12) or later.
* Enhanced error messaging when an update cannot be completed if the user doesn't match the owner of `Docker.app`. Fixes [docker/for-mac#7000](https://github.com/docker/for-mac/issues/7000).
* Fixed a bug where **Re-apply configuration** might not work when `/var/run/docker.sock` is mis-configured.
* Docker Desktop doesn't overwrite `ECRCredentialHelper` if already present in `/usr/local/bin`.

#### [For Windows](#for-windows-61)

* Fixed an issue where **Switch to Windows Containers** would show in the tray menu on Windows Home Editions. Fixes [docker/for-win#13715](https://github.com/docker/for-win/issues/13715)

#### [For Linux](#for-linux-13)

* Fixed a bug in `docker login`. Fixes [docker/docker-credential-helpers#299](https://github.com/docker/docker-credential-helpers/issues/299)

### [Known Issues](#known-issues-28)

#### [For Mac](#for-mac-61)

* Upgrading to MacOS 14 can cause Docker Desktop to also update to a latest version even if the auto update option is disabled.
* Uninstalling Docker Desktop from the command line is not available. As a workaround, you can [uninstall Docker Desktop from the Dashboard](https://docs.docker.com/desktop/uninstall/).

#### [For Windows](#for-windows-62)

* **Switch to Windows containers** option in the tray menu may not show up on Windows. As a workaround, edit the [`settings.json` file](https://docs.docker.com/desktop/settings-and-maintenance/settings/) and set `"displaySwitchWinLinContainers": true`.

#### [For all platforms](#for-all-platforms-75)

* Docker operations, such as pulling images or logging in, fail with 'connection refused' or 'timeout' errors if the Swap file size is set to 0MB. As a workaround, configure the swap file size to a non-zero value in the **Resources** tab in **Settings**.

## [4.24.2](#4242)

*2023-10-12*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-73)

#### [For all platforms](#for-all-platforms-76)

* Fixed a bug where Docker Desktop would send multiple requests to `notify.bugsnag.com`. Fixes [docker/for-win#13722](https://github.com/docker/for-win/issues/13722).
* Fixed a performance regression for PyTorch.

## [4.24.1](#4241)

*2023-10-04*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-74)

#### [For Windows](#for-windows-63)

* Fixed a bug on Docker Desktop for Windows where the Docker Desktop Dashboard wouldn't display container logs correctly. Fixes [docker/for-win#13714](https://github.com/docker/for-win/issues/13714).

## [4.24.0](#4240)

*2023-09-28*

### [New](#new-42)

* The new Notification center is now available to all users so you can be notified of new releases, installation progress updates, and more. Select the bell icon in the bottom-right corner of the Docker Desktop Dashboard to access the notification center.
* Compose Watch is now available to all users. For more information, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).
* Resource Saver is now available to all users and is enabled by default. To configure this feature, navigate to the **Resources** tab in **Settings**. For more information see [Docker Desktop's Resource Saver mode](https://docs.docker.com/desktop/use-desktop/resource-saver/).
* You can now view and manage the Docker Engine state, with pause, stop, and resume, directly from the Docker Desktop Dashboard.

### [Upgrades](#upgrades-34)

* [Compose v2.22.0](https://github.com/docker/compose/releases/tag/v2.22.0)

* [Go 1.21.1](https://github.com/golang/go/releases/tag/go1.21.1)

* [Wasm](https://docs.docker.com/desktop/features/wasm/) runtimes:

  * wasmtime, wasmedge `v0.2.0`.
  * lunatic, slight, spin, and wws`v0.9.1`.
  * Added wasmer wasm shims.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-75)

#### [For all platforms](#for-all-platforms-77)

* Docker Init:

  * Fixed an issue formatting Dockerfile file paths for ASP.NET projects on Windows.
  * Improved performance on language detection for large directories with lots of files.

* Added a timeout to polling for resource usage stats used by the **Containers** view. Fixes [docker/for-mac#6962](https://github.com/docker/for-mac/issues/6962).

* containerd integration:

  * Implemented push/pull/save image events.
  * Implemented pulling legacy schema1 images.
  * Implemented `docker push --all-tags`.
  * Implemented counting containers using a specific image (visible for example in `docker system df -v`).
  * Validated pulled image names are not reserved.
  * Handle `userns-remap` daemon setting.
  * Fixed legacy builder build errors when multiple COPY/ADD instructions are used.
  * Fixed `docker load` causing pool corruption which could some subsequent image related operations.
  * Fixed not being able to reference images via truncated digest with a `sha256:` prefix.
  * Fixed `docker images` (without `--all`) showing intermediate layers (created by the legacy classic builder).
  * Fixed `docker diff` containing extra differences.
  * Changed `docker pull` output to match the output with containerd integration disabled.

* Fixed a grammatical error in Kubernetes status message. See [docker/for-mac#6971](https://github.com/docker/for-mac/issues/6971).

* Docker containers now use all host CPU cores by default.

* Improved inter-process security in dashboard UI.

#### [For Mac](#for-mac-62)

* Fixed a kernel panic on Apple Silicon Macs with macOS version earlier than 12.5. Fixes [docker/for-mac#6975](https://github.com/docker/for-mac/issues/6975).
* Fixed a bug where Docker Desktop failed to start if invalid directories were included in `filesharingDirectories`. Fixes [docker/for-mac#6980](https://github.com/docker/for-mac/issues/6980).
* Fixed a bug where installer is creating root-owned directories. Fixes [docker/for-mac#6984](https://github.com/docker/for-mac/issues/6984).
* Fixed a bug where installer is failing on setting up the docker socket when missing `/Library/LaunchDaemons`. Fixes [docker/for-mac#6967](https://github.com/docker/for-mac/issues/6967).
* Fixed a permission denied error when binding a privileged port to a non-localhost IP on macOS. Fixes [docker/for-mac#697](https://github.com/docker/for-mac/issues/6977).
* Fixed a resource leak introduced in 4.23. Related to [docker/for-mac#6953](https://github.com/docker/for-mac/issues/6953).

#### [For Windows](#for-windows-64)

* Fixed a bug where a "Docker Desktop service not running" popup appeared when service is already running. See [docker/for-win#13679](https://github.com/docker/for-win/issues/13679).
* Fixed a bug that caused Docker Desktop fail to start on Windows hosts. Fixes [docker/for-win#13662](https://github.com/docker/for-win/issues/13662).
* Modified the Docker Desktop resource saver feature to skip reducing kernel memory on WSL when no containers are running, as this was causing timeouts in some cases. Instead, users are encouraged to enable "autoMemoryReclaim" on WSL directly via the .wslconfig file (available since WSL 1.3.10).

### [Known issues](#known-issues-29)

#### [For Mac](#for-mac-63)

* Creating a container with the port 53 fails with the error address `already in use`. As a workaround, deactivate network acceleration by adding `"kernelForUDP": false`, in the `settings.json` file located at `~/Library/Group Containers/group.com.docker/settings.json`.

## [4.23.0](#4230)

*2023-09-11*

### [Upgrades](#upgrades-35)

* [Compose v2.21.0](https://github.com/docker/compose/releases/tag/v2.21.0)

* [Docker Engine v24.0.6](https://docs.docker.com/engine/release-notes/24.0/#2406)

* [Docker Scout CLI v0.24.1](https://github.com/docker/scout-cli/releases/tag/v0.24.1).

* [Wasm](https://docs.docker.com/desktop/features/wasm/) runtimes:

  * wasmtime, wasmedge revision `d0a1a1cd`.
  * slight and spin wasm `v0.9.0`.

### [New](#new-43)

* Added support for new Wasm runtimes: wws and lunatic.
* [`docker init`](/reference/cli/docker/init/) now supports ASP.NET
* Increased performance of exposed ports on macOS, for example with `docker run -p`.

### [Removed](#removed)

* Removed Compose V1 from Docker Desktop as it has stopped receiving updates. Compose V2 has replaced it and is now integrated into all current Docker Desktop versions.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-76)

#### [For all platforms](#for-all-platforms-78)

* With [Docker Scout](https://docs.docker.com/scout/), you can now:

  * Manage temporary and cached files with `docker scout cache`.
  * Manage environments with `docker scout environment`.
  * Configure the default organization with `docker scout config`.
  * List packages of an image with their vulnerabilities with `docker scout cves --format only-packages`.
  * Enroll an organization with Docker scout with `docker scout enroll`.
  * Stop, analyze, and compare local file systems with `docker scout cves --type fs`.

* Fixed a bug where `docker stats` would hang when Docker Desktop was in Resource Saver mode.

* Fixed a bug where turning off experimental features via **Settings** in the Docker Desktop Dashboard would not fully turn off Resource Saver mode.

* Fixed a bug where the **Containers list** action button was clipped.

* containerd image store:

  * Fixed `failed to read config content` error when interacting with some images.
  * Fixed building Dockerfiles with `FROM scratch` instruction when using the legacy classic builder (`DOCKER_BUILDKIT=0`).
  * Fixed `mismatched image rootfs errors` when building images with legacy classic builder (`DOCKER_BUILDKIT=0`).
  * Fixed `ONBUILD` and `MAINTAINER` Dockerfile instruction
  * Fixed healthchecks.

#### [For Mac](#for-mac-64)

* All users on macOS 12.5 or greater now have VirtioFS turned on by default. You can revert this in **Settings** in the **General** tab.
* Improved single-stream TCP throughput.
* Reinstated the health check for macOS that notifies you if there has been a change on your system which might cause problems running Docker binaries.

#### [For Linux](#for-linux-14)

* Fixed a bug where the GUI is killed when opening the Docker Desktop app twice. See [docker/desktop-linux#148](https://github.com/docker/desktop-linux/issues/148).

#### [For Windows](#for-windows-65)

* Fixed a bug where non-admin users would get prompted for credentials when switching to Windows Containers or after disabling WSL and switching to the Hyper-V engine. This issue would occur after an OS restart, or on a cold start of Docker Desktop.

### [Security](#security-23)

#### [For all platforms](#for-all-platforms-79)

* Fixed [CVE-2023-5165](https://www.cve.org/cverecord?id=CVE-2023-5165) which allows Enhanced Container Isolation bypass via debug shell. The affected functionality is available for Docker Business customers only and assumes an environment where users are not granted local root or Administrator privileges.
* Fixed [CVE-2023-5166](https://www.cve.org/cverecord?id=CVE-2023-5166) which allows Access Token theft via a crafted extension icon URL.

### [Known Issues](#known-issues-30)

* Binding a privileged port on Docker Desktop does not work on macOS. As a workaround you can expose the port on all interfaces (using `0.0.0.0`) or using localhost (using `127.0.0.1`).

## [4.22.1](#4221)

*2023-08-24*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-77)

#### [For all platforms](#for-all-platforms-80)

* Mitigated several issues impacting Docker Desktop startup and Resource Saver mode. [docker/for-mac#6933](https://github.com/docker/for-mac/issues/6933)

#### [For Windows](#for-windows-66)

* Fixed `Clean / Purge data` troubleshoot option on Windows. [docker/for-win#13630](https://github.com/docker/for-win/issues/13630)

## [4.22.0](#4220)

*2023-08-03*

### [Upgrades](#upgrades-36)

* [Buildx v0.11.2](https://github.com/docker/buildx/releases/tag/v0.11.2)
* [Compose v2.20.2](https://github.com/docker/compose/releases/tag/v2.20.2)
* [Docker Engine v24.0.5](https://docs.docker.com/engine/release-notes/24.0/#2405)

> Note
>
> In this release, the bundled Docker Compose and Buildx binaries show a different version string. This relates to our efforts to test new features without causing backwards compatibility issues.
>
> For example, `docker buildx version` outputs `buildx v0.11.2-desktop.1`.

### [New](#new-44)

* [Resource Usage](https://docs.docker.com/desktop/use-desktop/container/) has moved from experimental to GA.
* You can now split large Compose projects into multiple sub-projects with [`include`](https://docs.docker.com/compose/how-tos/multiple-compose-files/include/).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-78)

#### [For all platforms](#for-all-platforms-81)

* [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) now lets you turn off Docker Extensions for your organisation.

* Fixed a bug where turning on Kubernetes from the UI failed when the system was paused.

* Fixed a bug where turning on Wasm from the UI failed when the system was paused.

* Bind mounts are now shown when you [inspect a container](https://docs.docker.com/desktop/use-desktop/container/).

* You can now download Wasm runtimes when the containerd image store is enabled.

* With [Quick Search](https://docs.docker.com/desktop/use-desktop/#quick-search), you can now:

  * Find any container or Compose app residing on your local system. In addition, you can access environment variables and perform essential actions such as starting, stopping, or deleting containers.
  * Find public Docker Hub images, local images, or images from remote repositories.
  * Discover more about specific extensions and install them.
  * Navigate through your volumes and gain insights about the associated containers.
  * Search and access Docker's documentation.

#### [For Mac](#for-mac-65)

* Fixed a bug that prevented Docker Desktop from starting. [docker/for-mac#6890](https://github.com/docker/for-mac/issues/6890)
* Resource Saver is now available on Mac. It optimises Docker Desktop's usage of your system resources when no containers are running. To access this feature, make sure you have [turned on access to experimental features](https://docs.docker.com/desktop/settings-and-maintenance/settings/) in settings.

#### [For Windows](#for-windows-67)

* Fixed a bug where the self-diagnose tool showed a false-positive failure when vpnkit is expected to be not running. Fixes [docker/for-win#13479](https://github.com/docker/for-win/issues/13479).
* Fixed a bug where an invalid regular expression in the search bar caused an error. Fixes [docker/for-win#13592](https://github.com/docker/for-win/issues/13592).
* Resource Saver is now available on Windows Hyper-V. It optimises Docker Desktop's usage of your system resources when no containers are running. To access this feature, make sure you have [turned on access to experimental features](https://docs.docker.com/desktop/settings-and-maintenance/settings/) in settings.

## [4.21.1](#4211)

*2023-07-03*

#### [For all platforms](#for-all-platforms-82)

* Fixed connection leak for Docker contexts using SSH ([docker/for-mac#6834](https://github.com/docker/for-mac/issues/6834) and [docker/for-win#13564](https://github.com/docker/for-win/issues/13564))

#### [For Mac](#for-mac-66)

* Removed configuration health check for further investigation and addressing specific setups.

## [4.21.0](#4210)

*2023-06-29*

### [New](#new-45)

* Added support for new Wasm runtimes: slight, spin, and wasmtime. Users can download Wasm runtimes on demand when the containerd image store is enabled.
* Added Rust server support to Docker init.
* Beta release of the [**Builds** view](https://docs.docker.com/desktop/use-desktop/builds/) that lets you inspect builds and manage builders. This can be found in the **Features in Development** tab in **Settings**.

### [Upgrades](#upgrades-37)

* [Buildx v0.11.0](https://github.com/docker/buildx/releases/tag/v0.11.0)
* [Compose v2.19.0](https://github.com/docker/compose/releases/tag/v2.19.0)
* [Kubernetes v1.27.2](https://github.com/kubernetes/kubernetes/releases/tag/v1.27.2)
* [cri-tools v1.27.0](https://github.com/kubernetes-sigs/cri-tools/releases/tag/v1.27.0)
* [cri-dockerd v0.3.2](https://github.com/Mirantis/cri-dockerd/releases/tag/v0.3.2)
* [coredns v1.10.1](https://github.com/coredns/coredns/releases/tag/v1.10.1)
* [cni v1.2.0](https://github.com/containernetworking/plugins/releases/tag/v1.2.0)
* [etcd v3.5.7](https://github.com/etcd-io/etcd/releases/tag/v3.5.7)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-79)

#### [For all platforms](#for-all-platforms-83)

* Docker Desktop now automatically pauses the Docker Engine when it is not in use and wakes up again on demand.
* VirtioFS is now the default file sharing implementation for new installations of Docker Desktop on macOS 12.5 and higher.
* Improved product usage reporting using OpenTelemetry (experimental).
* Fixed Docker socket permissions. Fixes [docker/for-win#13447](https://github.com/docker/for-win/issues/13447) and [docker/for-mac#6823](https://github.com/docker/for-mac/issues/6823).
* Fixed an issue which caused Docker Desktop to hang when quitting the application whilst paused.
* Fixed a bug which caused the **Logs** and **Terminal** tab content in the **Container** view to be covered by a fixed toolbar [docker/for-mac#6814](https://github.com/docker/for-mac/issues/6814).
* Fixed a bug which caused input labels to overlap with input values on the container run dialog. Fixes [docker/for-win#13304](https://github.com/docker/for-win/issues/13304).
* Fixed a bug which meant users couldn't select the Docker Extension menu. Fixes [docker/for-mac#6840](https://github.com/docker/for-mac/issues/6840) and [docker/for-mac#6855](https://github.com/docker/for-mac/issues/6855)

#### [For Mac](#for-mac-67)

* Added a health check for macOS that notifies users if there has been a change on their system which might cause problems running Docker binaries.

#### [For Windows](#for-windows-68)

* Fixed a bug on WSL 2 where if Desktop is paused, killed, and then restarted, the startup hangs unless WSL is shut down first with `wsl --shutdown`.

* Fixed the WSL engine in cases where wsl.exe is not on the PATH [docker/for-win#13547](https://github.com/docker/for-win/issues/13547).

* Fixed the WSL engine's ability to detect cases where one of the Docker Desktop distributions' drive is missing [docker/for-win#13554](https://github.com/docker/for-win/issues/13554).

* A slow or unresponsive WSL integration no longer prevents Docker Desktop from starting. Fixes [docker/for-win#13549](https://github.com/docker/for-win/issues/13549).

* Fixed a bug that caused Docker Desktop to crash on startup [docker/for-win#6890](https://github.com/docker/for-mac/issues/6890).

* Added the following installer flags:

  * `--hyper-v-default-data-root` which specifies the default location for Hyper-V VM disk.
  * `--windows-containers-default-data-root` which specifies the default data root for Windows Containers.
  * `--wsl-default-data-root` which specifies the default location for WSL distribution disks.

## [4.20.1](#4201)

*2023-06-05*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-80)

#### [For all platforms](#for-all-platforms-84)

* containerd image store: Fixed a bug that caused `docker load` to fail when loading an image that contains attestations.
* containerd image store: Fixed the default image exporter during build.

#### [For Windows](#for-windows-69)

* Fixed a bug that made it difficult to parse the WSL version on the host in non-western locales. Fixes [docker/for-win#13518](https://github.com/docker/for-win/issues/13518) and [docker/for-win#13524](https://github.com/docker/for-win/issues/13524).

## [4.20.0](#4200)

*2023-05-30*

### [Upgrades](#upgrades-38)

* [Buildx v0.10.5](https://github.com/docker/buildx/releases/tag/v0.10.5)
* [Compose v2.18.1](https://github.com/docker/compose/releases/tag/v2.18.1)
* [Docker Engine v24.0.2](https://docs.docker.com/engine/release-notes/24.0/#2402)
* [Containerd v1.6.21](https://github.com/containerd/containerd/releases/tag/v1.6.21)
* [runc v1.1.7](https://github.com/opencontainers/runc/releases/tag/v1.1.5)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-81)

#### [For all platforms](#for-all-platforms-85)

* [Docker Scout CLI](https://docs.docker.com/scout/#docker-scout-cli) now finds the most recently built image if it is not provided as an argument.
* Improved the [Docker Scout CLI](https://docs.docker.com/scout/#docker-scout-cli) `compare` command.
* Added a warning about the [retirement of Docker Compose ECS/ACS integrations in November 2023](https://docs.docker.com/go/compose-ecs-eol/). Can be suppressed with `COMPOSE_CLOUD_EOL_SILENT=1`.
* Fixed an HTTP proxy bug where an HTTP 1.0 client could receive an HTTP 1.1 response.
* Enabled Docker Desktop's Enhanced Container Isolation (ECI) feature on WSL-2. This is available with a Docker Business subscription.
* Fixed a bug on the **Containers** table where previously hidden columns were displayed again after a fresh installation of Docker Desktop.

#### [For Mac](#for-mac-68)

* You can now reclaim disk space more quickly when files are deleted in containers. Related to [docker/for-mac#371](https://github.com/docker/for-mac/issues/371).
* Fixed a bug that prevented containers accessing 169.254.0.0/16 IPs. Fixes [docker/for-mac#6825](https://github.com/docker/for-mac/issues/6825).
* Fixed a bug in `com.docker.diagnose check` where it would complain about a missing vpnkit even when vpnkit is not expected to be running. Related to [docker/for-mac#6825](https://github.com/docker/for-mac/issues/6825).

#### [For Windows](#for-windows-70)

* Fixed a bug that meant WSL data could not be moved to a different disk. Fixes [docker/for-win#13269](https://github.com/docker/for-win/issues/13269).
* Fixed a bug where Docker Desktop was not stopping its WSL distributions (docker-desktop and docker-desktop-data) when it was shutdown, consuming host memory unnecessarily.
* Added a new setting that allows the Windows Docker daemon to use Docker Desktop's internal proxy when running Windows containers. See [Windows proxy settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies).

#### [For Linux](#for-linux-15)

* Fixed an issue with the Docker Compose V1/V2 compatibility setting.

## [4.19.0](#4190)

*2023-04-27*

### [New](#new-46)

* Docker Engine and CLI updated to [Moby 23.0](https://github.com/moby/moby/releases/tag/v23.0.0).
* The **Learning Center** now supports in-product walkthroughs.
* Docker init (Beta) now supports Node.js and Python.
* Faster networking between VM and host on macOS.
* You can now inspect and analyze remote images from Docker Desktop without pulling them.
* Usability and performance improvements to the **Artifactory images** view.

### [Removed](#removed-1)

* Removed `docker scan` command. To continue learning about the vulnerabilities of your images, and many other features, use the new `docker scout` command. Run `docker scout --help`, or [read the docs to learn more](/reference/cli/docker/scout/).

### [Upgrades](#upgrades-39)

* [Docker Engine v23.0.5](https://docs.docker.com/engine/release-notes/23.0/#2305)
* [Compose 2.17.3](https://github.com/docker/compose/releases/tag/v2.17.3)
* [Containerd v1.6.20](https://github.com/containerd/containerd/releases/tag/v1.6.20)
* [Kubernetes v1.25.9](https://github.com/kubernetes/kubernetes/releases/tag/v1.25.9)
* [runc v1.1.5](https://github.com/opencontainers/runc/releases/tag/v1.1.5)
* [Go v1.20.3](https://github.com/golang/go/releases/tag/go1.20.3)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-82)

#### [For all platforms](#for-all-platforms-86)

* Improved `docker scout compare` command to compare two images, now also aliased under `docker scout diff`.
* Added more details to dashboard errors when a `docker-compose` action fails ([docker/for-win#13378](https://github.com/docker/for-win/issues/13378)).
* Added support for setting HTTP proxy configuration during installation. This can be done via the `--proxy-http-mode`, `--overrider-proxy-http`, `--override-proxy-https` and `--override-proxy-exclude` installer flags in the case of installation from the CLI on [Mac](https://docs.docker.com/desktop/setup/install/mac-install/#install-from-the-command-line) and [Windows](https://docs.docker.com/desktop/setup/install/windows-install/#install-from-the-command-line), or alternatively by setting the values in the `install-settings.json` file.
* Docker Desktop now stops overriding .docker/config.json `credsStore` keys on application start. Note that if you use a custom credential helper then the CLI `docker login` and `docker logout` does not affect whether the UI is signed in to Docker or not. In general, it is better to sign into Docker via the UI since the UI supports multi-factor authentication.
* Added a warning about the forthcoming removal of Compose V1 from Docker Desktop. Can be suppressed with `COMPOSE_V1_EOL_SILENT=1`.
* In the Compose config, boolean fields in YAML should be either `true` or `false`. Deprecated YAML 1.1 values such as “on” or “no” now produce a warning.
* Improved UI for image table, allowing rows to use more available space.
* Fixed various bugs in port-forwarding.
* Fixed a HTTP proxy bug where an HTTP request without a Server Name Indication record would be rejected with an error.

#### [For Windows](#for-windows-71)

* Reverted to fully patching etc/hosts on Windows (includes `host.docker.internal` and `gateway.docker.internal` again). For WSL, this behavior is controlled by a new setting in the **General** tab. Fixes [docker/for-win#13388](https://github.com/docker/for-win/issues/13388) and [docker/for-win#13398](https://github.com/docker/for-win/issues/13398).
* Fixed a spurious `courgette.log` file appearing on the Desktop when updating Docker Desktop. Fixes [docker/for-win#12468](https://github.com/docker/for-win/issues/12468).
* Fixed the "zoom in" shortcut (ctrl+=). Fixes [docker/for-win#13392](https://github.com/docker/for-win/issues/13392).
* Fixed a bug where the tray menu would not correctly update after second container type switch. Fixes [docker/for-win#13379](https://github.com/docker/for-win/issues/13379).

#### [For Mac](#for-mac-69)

* Increased the performance of VM networking when using the Virtualization framework on macOS Ventura and above. Docker Desktop for Mac now uses gVisor instead of VPNKit. To continue using VPNKit, add `"networkType":"vpnkit"` to your `settings.json` file located at `~/Library/Group Containers/group.com.docker/settings.json`.
* Fixed a bug where an error window is displayed on uninstall.
* Fixed a bug where the setting `deprecatedCgroupv1` was ignored. Fixes [docker/for-mac#6801](https://github.com/docker/for-mac/issues/6801).
* Fixed cases where `docker pull` would return `EOF`.

#### [For Linux](#for-linux-16)

* Fixed a bug where the VM networking crashes after 24h. Fixes [docker/desktop-linux#131](https://github.com/docker/desktop-linux/issues/131).

### [Security](#security-24)

#### [For all platforms](#for-all-platforms-87)

* Fixed a security issue allowing users to bypass Image Access Management (IAM) restrictions configured by their organisation by avoiding `registry.json` enforced login via deleting the `credsStore` key from their Docker CLI configuration file. Only affects Docker Business customers.
* Fixed [CVE-2023-24532](https://github.com/advisories/GHSA-x2w5-7wp4-5qff).
* Fixed [CVE-2023-25809](https://github.com/advisories/GHSA-m8cg-xc2p-r3fc).
* Fixed [CVE-2023-27561](https://github.com/advisories/GHSA-vpvm-3wq2-2wvm).
* Fixed [CVE-2023-28642](https://github.com/advisories/GHSA-g2j6-57v7-gm8c).
* Fixed [CVE-2023-28840](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28840).
* Fixed [CVE-2023-28841](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28841).
* Fixed [CVE-2023-28842](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28842).

## [4.18.0](#4180)

*2023-04-03*

### [New](#new-47)

* Initial beta release of `docker init` as per [the roadmap](https://github.com/docker/roadmap/issues/453).
* Added a new **Learning Center** tab to help users get started with Docker.
* Added an experimental file-watch command to Docker Compose that automatically updates your running Compose services as you edit and save your code.

### [Upgrades](#upgrades-40)

* [Buildx v0.10.4](https://github.com/docker/buildx/releases/tag/v0.10.4)
* [Compose 2.17.2](https://github.com/docker/compose/releases/tag/v2.17.2)
* [Containerd v1.6.18](https://github.com/containerd/containerd/releases/tag/v1.6.18), which includes fixes for [CVE-2023-25153](https://github.com/advisories/GHSA-259w-8hf6-59c2) and [CVE-2023-25173](https://github.com/advisories/GHSA-hmfx-3pcx-653p).
* [Docker Engine v20.10.24](https://docs.docker.com/engine/release-notes/20.10/#201024), which contains fixes for [CVE-2023-28841](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28841), [CVE-2023-28840](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28840), and [CVE-2023-28842](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28842).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-83)

#### [For all platforms](#for-all-platforms-88)

* [Docker Scout CLI](https://docs.docker.com/scout/#docker-scout-cli) can now compare two images and display packages and vulnerabilities differences. This command is in [Early Access](https://docs.docker.com/release-lifecycle/) and might change in the future.
* [Docker Scout CLI](https://docs.docker.com/scout/#docker-scout-cli) now displays base image update and remediation recommendations using `docker scout recommendations`. It also displays a short overview of an image using `docker scout quickview` commands.
* You can now search for extensions direct from the Marketplace, as well as using **Global Search**.
* Fixed a bug where `docker buildx` container builders would lose access to the network after 24hrs.
* Reduced how often users are prompted for feedback on Docker Desktop.
* Removed minimum VM swap size.
* Added support for subdomain match, CIDR match, `.` and `_.` in HTTP proxy exclude lists.
* Fixed a bug in the transparent TLS proxy when the Server Name Indication field is not set.
* Fixed a grammatical error in Docker Desktop engine status message.

### [For Windows](#for-windows-72)

* Fixed a bug where `docker run --gpus=all` hangs. Fixes [docker/for-win#13324](https://github.com/docker/for-win/issues/13324).
* Fixed a bug where Registry Access Management policy updates were not downloaded.
* Docker Desktop now allows Windows containers to work when BitLocker is enabled on `C:`.
* Docker Desktop with the WSL backend no longer requires the `com.docker.service` privileged service to run permanently. For more information see [Permission requirements for Windows](https://docs.docker.com/desktop/windows/permission-requirements/).

### [For Mac](#for-mac-70)

* Fixed a performance issue where attributes stored on the host would not be cached for VirtioFS users.
* The first time Docker Desktop for Mac is launched, the user is presented with an installation window to confirm or adjust the configuration that requires privileged access. For more information see [Permission requirements for Mac](https://docs.docker.com/desktop/mac/permission-requirements/).
* Added the **Advanced** tab in **Settings**, where users can adjust the settings which require privileged access.

### [For Linux](#for-linux-17)

* Fixed a bug where the VM networking crashes after 24h. [docker/for-linux#131](https://github.com/docker/desktop-linux/issues/131)

### [Security](#security-25)

#### [For all platforms](#for-all-platforms-89)

* Fixed [CVE-2023-1802](https://www.cve.org/cverecord?id=CVE-2023-1802) where a security issue with the Artifactory Integration would cause it to fall back to sending registry credentials over plain HTTP if HTTPS check failed. Only users who have `Access experimental features` enabled are affected. Fixes [docker/for-win#13344](https://github.com/docker/for-win/issues/13344).

#### [For Mac](#for-mac-71)

* Removed the `com.apple.security.cs.allow-dyld-environment-variables` and `com.apple.security.cs.disable-library-validation` entitlements which allow an arbitrary dynamic library to be loaded with Docker Desktop via the `DYLD_INSERT_LIBRARIES` environment variable.

### [Known Issues](#known-issues-31)

* Uninstalling Docker Desktop on Mac from the **Troubleshoot** page might trigger an unexpected fatal error popup.

## [4.17.1](#4171)

*2023-03-20*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-84)

#### [For Windows](#for-windows-73)

* Docker Desktop now allows Windows containers to work when BitLocker is enabled on C:
* Fixed a bug where `docker buildx` container builders would lose access to the network after 24hrs.
* Fixed a bug where Registry Access Management policy updates were not downloaded.
* Improved debug information to better characterise failures under WSL 2.

### [Known Issues](#known-issues-32)

* Running containers with `--gpus` on Windows with the WSL 2 backend does not work. This will be fixed in future releases. See [docker/for-win/13324](https://github.com/docker/for-win/issues/13324).

## [4.17.0](#4170)

*2023-02-27*

### [New](#new-48)

* Docker Desktop now ships with Docker Scout. Pull and view analysis for images from Docker Hub and Artifactory repositories, get base image updates and recommended tags and digests, and filter your images on vulnerability information. To learn more, see [Docker Scout](https://docs.docker.com/scout/).
* `docker scan` has been replaced by `docker scout`. See [Docker Scout CLI](https://docs.docker.com/scout/#docker-scout-cli), for more information.
* You can now discover extensions that have been autonomously published in the Extensions Marketplace. For more information on self-published extensions, see [Marketplace Extensions](https://docs.docker.com/extensions/marketplace/).
* **Container File Explorer** is available as an experimental feature. Debug the filesystem within your containers straight from the GUI.
* You can now search for volumes in **Global Search**.

### [Upgrades](#upgrades-41)

* [Containerd v1.6.18](https://github.com/containerd/containerd/releases/tag/v1.6.18), which includes fixes for [CVE-2023-25153](https://github.com/advisories/GHSA-259w-8hf6-59c2) and [CVE-2023-25173](https://github.com/advisories/GHSA-hmfx-3pcx-653p).
* [Docker Engine v20.10.23](https://docs.docker.com/engine/release-notes/20.10/#201023).
* [Go 1.19.5](https://github.com/golang/go/releases/tag/go1.19.5)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-85)

#### [For all platforms](#for-all-platforms-90)

* Fixed a bug where diagnostic gathering could hang waiting for a subprocess to exit.
* Prevented the transparent HTTP proxy from mangling requests too much. Fixes Tailscale extension login, see [tailscale/docker-extension#49](https://github.com/tailscale/docker-extension/issues/49).
* Fixed a bug in the transparent TLS proxy where the Server Name Indication field is not set.
* Added support for subdomain match, CIDR match, `.` and `*.` in HTTP proxy exclude lists.
* Ensured HTTP proxy settings are respected when uploading diagnostics.
* Fixed fatal error when fetching credentials from the credential helper.
* Fixed fatal error related to concurrent logging.
* Improved the UI for Extension actions in the Marketplace.
* Added new filters in the Extensions Marketplace. You can now filter extensions by category and reviewed status.
* Added a way to report a malicious extension to Docker.
* Updated Dev Environments to v0.2.2 with initial set up reliability & security fixes.
* Added a whalecome survey for new users only.
* The confirmation dialogs on the troubleshooting page are now consistent in style with other similar dialogs.
* Fixed fatal error caused by resetting the Kubernetes cluster before it has started.
* Implemented `docker import` for the containerd integration.
* Fixed image tagging with an existing tag with the containerd integration.
* Implemented the dangling filter on images for the containerd integration.
* Fixed `docker ps` failing with containers whose images are no longer present with the containerd integration.

#### [For Mac](#for-mac-72)

* Fixed download of Registry Access Management policy on systems where the privileged helper tool `com.docker.vmnetd` is not installed.
* Fixed a bug where `com.docker.vmnetd` could not be installed if `/Library/PrivilegedHelperTools` does not exist.
* Fixed a bug where the "system" proxy would not handle "autoproxy" / "pac file" configurations.
* Fixed a bug where vmnetd installation fails to read `Info.Plist` on case-sensitive file systems. The actual filename is `Info.plist`. Fixes [docker/for-mac#6677](https://github.com/docker/for-mac/issues/6677).
* Fixed a bug where user is prompted to create the docker socket symlink on every startup. Fixes [docker/for-mac#6634](https://github.com/docker/for-mac/issues/6634).
* Fixed a bug that caused the **Start Docker Desktop when you log in** setting not to work. Fixes [docker/for-mac#6723](https://github.com/docker/for-mac/issues/6723).
* Fixed UDP connection tracking and `host.docker.internal`. Fixes [docker/for-mac#6699](https://github.com/docker/for-mac/issues/6699).
* Improved kubectl symlink logic to respect existing binaries in `/usr/local/bin`. Fixes [docker/for-mac#6328](https://github.com/docker/for-mac/issues/6328).
* Docker Desktop now automatically installs Rosetta when you opt-in to use it but have not already installed it.

### [For Windows](#for-windows-74)

* Added statical linking of WSL integration tools against `musl` so there is no need to install `alpine-pkg-glibc` in user distributions.
* Added support for running under cgroupv2 on WSL 2. This is activated by adding `kernelCommandLine = systemd.unified_cgroup_hierarchy=1 cgroup_no_v1=all` to your `%USERPROFILE%\.wslconfig` file in the `[wsl2]` section.
* Fixed an issue that caused Docker Desktop to get stuck in the "starting" phase when in WSL 2 mode (introduced in 4.16).
* Fixed Docker Desktop failing to start the WSL 2 backend when file system compression or encryption is enabled on `%LOCALAPPDATA%`.
* Fixed Docker Desktop failing to report a missing or outdated (incapable of running WSL version 2 distributions) WSL installation when starting.
* Fixed a bug where opening in Visual Studio Code fails if the target path has a space.
* Fixed a bug that causes `~/.docker/context` corruption and the error message "unexpected end of JSON input". You can also remove `~/.docker/context` to work around this problem.
* Ensured the credential helper used in WSL 2 is properly signed. Related to [docker/for-win#10247](https://github.com/docker/for-win/issues/10247).
* Fixed an issue that caused WSL integration agents to be terminated erroneously. Related to [docker/for-win#13202](https://github.com/docker/for-win/issues/13202).
* Fixed corrupt contexts on start. Fixes [docker/for-win#13180](https://github.com/docker/for-win/issues/13180) and [docker/for-win#12561](https://github.com/docker/for-win/issues/12561).

### [For Linux](#for-linux-18)

* Added Docker Buildx plugin for Docker Desktop for Linux.
* Changed compression algorithm to `xz` for RPM and Arch Linux distribution.
* Fixed a bug that caused leftover files to be left in the root directory of the Debian package. Fixes [docker/for-linux#123](https://github.com/docker/desktop-linux/issues/123).

### [Security](#security-26)

#### [For all platforms](#for-all-platforms-91)

* Fixed [CVE-2023-0628](https://www.cve.org/cverecord?id=CVE-2023-0628), which allows an attacker to execute an arbitrary command inside a Dev Environments container during initialization by tricking a user to open a crafted malicious `docker-desktop://` URL.
* Fixed [CVE-2023-0629](https://www.cve.org/cverecord?id=CVE-2023-0629), which allows an unprivileged user to bypass Enhanced Container Isolation (ECI) restrictions by setting the Docker host to `docker.raw.sock`, or `npipe:////.pipe/docker_engine_linux` on Windows, via the `-H` (`--host`) CLI flag or the `DOCKER_HOST` environment variable and launch containers without the additional hardening features provided by ECI. This does not affect already running containers, nor containers launched through the usual approach (without Docker's raw socket).

## [4.16.3](#4163)

*2023-01-30*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-86)

#### [For Windows](#for-windows-75)

* Fixed Docker Desktop failing to start the WSL 2 backend when file system compression or encryption is enabled on `%LOCALAPPDATA%`. Fixes [docker/for-win#13184](https://github.com/docker/for-win/issues/13184).
* Fixed Docker Desktop failing to report a missing or outdated WSL installation when starting. Fixes [docker/for-win#13184](https://github.com/docker/for-win/issues/13184).

## [4.16.2](#4162)

*2023-01-19*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-87)

#### [For all platforms](#for-all-platforms-92)

* Fixed an issue where `docker build` and `docker tag` commands produced an `image already exists` error if the containerd integration feature is enabled.
* Fixed a regression introduced with Docker Desktop 4.16 breaking networking from containers with target platform linux/386 on amd64 systems. Fixes [docker/for-mac/6689](https://github.com/docker/for-mac/issues/6689).

#### [For Mac](#for-mac-73)

* Fixed the capitalization of `Info.plist` which caused `vmnetd` to break on case-sensitive file systems. Fixes [docker/for-mac/6677](https://github.com/docker/for-mac/issues/6677).

#### [For Windows](#for-windows-76)

* Fixed a regression introduced with Docker Desktop 4.16 causing it to get stuck in the "starting" phase when in WSL2 mode. Fixes [docker/for-win/13165](https://github.com/docker/for-win/issues/13165)

## [4.16.1](#4161)

*2023-01-13*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-88)

#### [For all platforms](#for-all-platforms-93)

* Fixed `sudo` inside a container failing with a security related error for some images. Fixes [docker/for-mac/6675](https://github.com/docker/for-mac/issues/6675) and [docker/for-win/13161](https://github.com/docker/for-win/issues/13161).

## [4.16.0](#4160)

*2023-01-12*

### [New](#new-49)

* Extensions have moved from Beta to GA.
* Quick Search has moved from experimental to GA.
* Extensions are now included in Quick Search.
* Analyzing large images is now up to 4x faster.
* New local images view has moved from experimental to GA.
* New Beta feature for MacOS 13, Rosetta for Linux, has been added for faster emulation of Intel-based images on Apple Silicon.

### [Upgrades](#upgrades-42)

* [Compose v2.15.1](https://github.com/docker/compose/releases/tag/v2.15.1)
* [Containerd v1.6.14](https://github.com/containerd/containerd/releases/tag/v1.6.14)
* [Docker Engine v20.10.22](https://docs.docker.com/engine/release-notes/20.10/#201022)
* [Buildx v0.10.0](https://github.com/docker/buildx/releases/tag/v0.10.0)
* [Docker Scan v0.23.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.23.0)
* [Go 1.19.4](https://github.com/golang/go/releases/tag/go1.19.4)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-89)

#### [For all platforms](#for-all-platforms-94)

* Fixed `docker build --quiet` not outputting the image identifier with the `containerd` integration.
* Fixed image inspect not showing image labels with the `containerd` integration.
* Increased the contrast between running and stopped container icons to make it easier for colorblind people to scan the containers list.
* Fixed a bug where the user is prompted for new HTTP proxy credentials repeatedly until Docker Desktop is restarted.
* Added a diagnostics command `com.docker.diagnose login` to check HTTP proxy configuration.
* Fixed actions on compose stack not working properly. Fixes [docker/for-mac#6566](https://github.com/docker/for-mac/issues/6566).
* Fixed the Docker Desktop Dashboard trying at startup to get disk usage information and display an error banner before the engine was running.
* Added an informational banner with instructions on how to opt-out of experimental feature access next to all experimental features.
* Docker Desktop now supports downloading Kubernetes images via an HTTP proxy.
* Fixed tooltips to not block action buttons. Fixes [docker/for-mac#6516](https://github.com/docker/for-mac/issues/6516).
* Fixed the blank "An error occurred" container list on the **Container** view.

#### [For Mac](#for-mac-74)

* Minimum OS version to install or update Docker Desktop on macOS is now macOS Big Sur (version 11) or later.
* Fixed the Docker engine not starting when Enhanced Container Isolation is enabled if the legacy `osxfs` implementation is used for file sharing.
* Fixed files created on VirtioFS having the executable bit set. Fixes [docker/for-mac#6614](https://github.com/docker/for-mac/issues/6614).
* Added back a way to uninstall Docker Desktop from the command line. Fixes [docker/for-mac#6598](https://github.com/docker/for-mac/issues/6598).
* Fixed hardcoded `/usr/bin/kill`. Fixes [docker/for-mac#6589](https://github.com/docker/for-mac/issues/6589).
* Fixed truncation (for example with the `truncate` command) of very large files (> 38GB) shared on VirtioFS with an incorrect size.
* Changed the disk image size in **Settings** to use the decimal system (base 10) to coincide with how Finder displays disk capacity.
* Fixed Docker crash under network load. Fixes [docker/for-mac#6530](https://github.com/docker/for-mac/issues/6530).
* Fixed an issue causing Docker to prompt the user to install the `/var/run/docker.sock` symlink after every reboot.
* Ensured the Login Item which installs the `/var/run/docker.sock` symlink is signed.
* Fixed bug where `$HOME/.docker` was removed on factory reset.

### [For Windows](#for-windows-77)

* Fixed `docker build` hanging while printing "load metadata for". Fixes [docker/for-win#10247](https://github.com/docker/for-win/issues/10247).
* Fixed typo in diagnose.exe output Fixes [docker/for-win#13107](https://github.com/docker/for-win/issues/13107).
* Added support for running under cgroupv2 on WSL 2. This is activated by adding `kernelCommandLine = systemd.unified_cgroup_hierarchy=1 cgroup_no_v1=all` to your `%USERPROFILE%\.wslconfig` file in the `[wsl2]` section.

### [Known Issues](#known-issues-33)

* Calling `sudo` inside a container fails with a security related error for some images. See [docker/for-mac/6675](https://github.com/docker/for-mac/issues/6675) and [docker/for-win/13161](https://github.com/docker/for-win/issues/13161).

## [4.15.0](#4150)

*2022-12-01*

### [New](#new-50)

* Substantial performance improvements for macOS users with the option of enabling the new VirtioFS file sharing technology. Available for macOS 12.5 and above.
* Docker Desktop for Mac no longer needs to install the privileged helper process `com.docker.vmnetd` on install or on the first run. For more information see [Permission requirements for Mac](https://docs.docker.com/desktop/mac/permission-requirements/).
* Added [WebAssembly capabilities](https://docs.docker.com/desktop/features/wasm/). Use with the [containerd integration](https://docs.docker.com/desktop/features/containerd/).
* Improved the descriptions for beta and experimental settings to clearly explain the differences and how people can access them.
* Available disk space of VM now displays in the footer of Docker Desktop Dashboard for Mac and Linux.
* A disk space warning now displays in the footer if available space is below 3GB.
* Changes to Docker Desktop's interface as we become more ADA accessible and visually unified.
* Added a **Build** tab inside **Extensions** which contains all the necessary resources to build an extension.
* Added the ability to share extensions more easily, either with `docker extension share` CLI or with the share button in the extensions **Manage** tab.
* Extensions in the Marketplace now display the number of installs. You can also sort extensions by the number of installs.
* Dev Environments allow cloning a Git repository to a local bind mount, so you can use any local editor or IDE.
* More Dev Environments improvements: custom names, better private repo support, improved port handling.

### [Upgrades](#upgrades-43)

* [Compose v2.13.0](https://github.com/docker/compose/releases/tag/v2.13.0)
* [Containerd v1.6.10](https://github.com/containerd/containerd/releases/tag/v1.6.10)
* [Docker Hub Tool v0.4.5](https://github.com/docker/hub-tool/releases/tag/v0.4.5)
* [Docker Scan v0.22.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.22.0)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-90)

#### [For all platforms](#for-all-platforms-95)

* Containers are now restored on restart with the containerd integration.
* Fixed listing multi-platform images with the containerd integration.
* Better handling of dangling images with the containerd integration.
* Implement "reference" filter for images with the containerd integration.
* Added support for selecting upstream HTTP/HTTPS proxies automatically via `proxy.pac` in containers, `docker pull` etc.
* Fixed regressions when parsing image references on pull. Fixes [docker/for-win#13053](https://github.com/docker/for-win/issues/13053), [docker/for-mac#6560](https://github.com/docker/for-mac/issues/6560), and [docker/for-mac#6540](https://github.com/docker/for-mac/issues/6540).

#### [For Mac](#for-mac-75)

* Improved the performance of `docker pull`.

#### [For Windows](#for-windows-78)

* Fixed an issue where the system HTTP proxies were not used when Docker starts and the developer logs in.
* When Docker Desktop is using "system" proxies and if the Windows settings change, Docker Desktop now uses the new Windows settings without a restart.

#### [For Linux](#for-linux-19)

* Fixed hot-reload issue on Linux. Fixes [docker/desktop-linux#30](https://github.com/docker/desktop-linux/issues/30).
* Disabled tray icon animations on Linux which fixes crashes for some users.

## [4.14.1](#4141)

*2022-11-17*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-91)

#### [For all platforms](#for-all-platforms-96)

* Fixed container DNS lookups when using Registry Access Management.

#### [For Mac](#for-mac-76)

* Fixed an issue preventing the **Analyze Image** button on the **Images** tab from working.
* Fixed a bug causing symlinks to not be created for the user if `/usr/local/lib` doesn't already exist. Fixes [docker/for-mac#6569](https://github.com/docker/for-mac/issues/6569)

## [4.14.0](#4140)

*2022-11-10*

### [New](#new-51)

* Set Virtualization framework as the default hypervisor for macOS >= 12.5.
* Migrate previous install to Virtualization framework hypervisor for macOS >= 12.5.
* The Enhanced Container Isolation feature, available to Docker Business users, can now be enabled from the General Settings.

### [Updates](#updates-21)

* [Docker Engine v20.10.21](https://docs.docker.com/engine/release-notes/20.10/#201021), which contains mitigations against a Git vulnerability, tracked in [CVE-2022-39253](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-39253), and updates the handling of `image:tag@digest` image references.
* [Docker Compose v2.12.2](https://github.com/docker/compose/releases/tag/v2.12.2)
* [Containerd v1.6.9](https://github.com/containerd/containerd/releases/tag/v1.6.9)
* [Go 1.19.3](https://github.com/golang/go/releases/tag/go1.19.3)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-92)

#### [For all platforms](#for-all-platforms-97)

* Docker Desktop now requires an internal network subnet of size /24. If you were previously using a /28, it is automatically expanded to /24. If you experience networking issues, check to see if you have a clash between the Docker subnet and your infrastructure. Fixes [docker/for-win#13025](https://github.com/docker/for-win/issues/13025).
* Fixed an issue that prevents users from creating Dev Environments when the Git URL has upper-case characters.
* Fix the `vpnkit.exe is not running` error reported in diagnostics.
* Reverted qemu to 6.2.0 to fix errors like `PR_SET_CHILD_SUBREAPER is unavailable` when running emulated amd64 code.
* Enabled [contextIsolation](https://www.electronjs.org/docs/latest/tutorial/context-isolation) and [sandbox](https://www.electronjs.org/docs/latest/tutorial/sandbox) mode inside Extensions. Now Extensions run in a separate context and this limits the harm that malicious code can cause by limiting access to most system resources.
* Included `unpigz` to allow parallel decompression of pulled images.
* Fixed issues related to performing actions on selected containers. [Fixes https://github.com/docker/for-win/issues/13005](https://github.com/docker/for-win/issues/13005)
* Added functionality that allows you to display timestamps for your container or project view.
* Fixed a possible segfault when interrupting `docker pull` with Control+C.
* Increased the default DHCP lease time to avoid the VM's network glitching and dropping connections every two hours.
* Removed the infinite spinner on the containers list. [Fixes https://github.com/docker/for-mac/issues/6486](https://github.com/docker/for-mac/issues/6486)
* Fixed bug which showed incorrect values on used space in **Settings**.
* Fixed a bug that caused Kubernetes not to start with the containerd integration.
* Fixed a bug that caused `kind` not to start with the containerd integration.
* Fixed a bug that caused Dev Environments to not work with the containerd integration.
* Implemented `docker diff` in the containerd integration.
* Implemented `docker run —-platform` in the containerd integration.
* Fixed a bug that caused insecure registries not to work with the containerd integration.

#### [For Mac](#for-mac-77)

* Fixed a startup failure for users of Virtualization framework.
* Re-added the `/var/run/docker.sock` on Mac by default, to increase compatibility with tooling like `tilt` and `docker-py.`
* Fixed an issue that prevented the creation of Dev Environments on new Mac installs (error "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?").

#### [For Windows](#for-windows-79)

* Re-added `DockerCli.exe -SharedDrives`. Fixes [docker/for-win#5625](https://github.com/docker/for-win#5625).
* Docker Desktop now allows Docker to function on machines where PowerShell is disabled.
* Fixed an issue where Compose v2 was not always enabled by default on Windows.
* Docker Desktop now deletes the `C:\Program Files\Docker` folder at uninstall.

### [Known Issues](#known-issues-34)

* For some users on Mac OS there is a known issue with the installer that prevents the installation of a new helper tool needed for the experimental vulnerability and package discovery feature in Docker Desktop. To fix this, a symlink is needed that can be created with the following command: `sudo ln -s /Applications/Docker.app/Contents/Resources/bin/docker-index /usr/local/bin/docker-index`

## [4.13.1](#4131)

*2022-10-31*

### [Updates](#updates-22)

* [Docker Compose v2.12.1](https://github.com/docker/compose/releases/tag/v2.12.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-93)

#### [For all platforms](#for-all-platforms-98)

* Fixed a possible segfault when interrupting `docker pull` with `Control+C` or `CMD+C`.
* Increased the default DHCP lease time to avoid the VM's network glitching and dropping connections every two hours.
* Reverted `Qemu` to `6.2.0` to fix errors like `PR_SET_CHILD_SUBREAPER is unavailable` when running emulated amd64 code.

#### [For Mac](#for-mac-78)

* Added back the `/var/run/docker.sock` symlink on Mac by default, to increase compatibility with tooling like `tilt` and `docker-py`. Fixes [docker/for-mac#6529](https://github.com/docker/for-mac/issues/6529).
* Fixed an issue preventing the creation of Dev Environments on new Mac installs and causing `error "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?")`

#### [For Windows](#for-windows-80)

* Docker Desktop now functions on machines where PowerShell is disabled.

## [4.13.0](#4130)

*2022-10-19*

### [New](#new-52)

* Two new security features have been introduced for Docker Business users, Settings Management and Enhanced Container Isolation. Read more about Docker Desktop’s new [Hardened Docker Desktop security model](https://docs.docker.com/enterprise/security/hardened-desktop/).
* Added the new Dev Environments CLI `docker dev`, so you can create, list, and run Dev Envs via command line. Now it's easier to integrate Dev Envs into custom scripts.
* Docker Desktop can now be installed to any drive and folder using the `--installation-dir`. Partially addresses [docker/roadmap#94](https://github.com/docker/roadmap/issues/94).

### [Updates](#updates-23)

* [Docker Scan v0.21.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.21.0)
* [Go 1.19.2](https://github.com/golang/go/releases/tag/go1.19.2) to address [CVE-2022-2879](https://www.cve.org/CVERecord?id=CVE-2022-2879), [CVE-2022-2880](https://www.cve.org/CVERecord?id=CVE-2022-2880) and [CVE-2022-41715](https://www.cve.org/CVERecord?id=CVE-2022-41715)
* Updated Docker Engine and Docker CLI to [v20.10.20](https://docs.docker.com/engine/release-notes/20.10/#201020), which contain mitigations against a Git vulnerability, tracked in [CVE-2022-39253](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-39253), and updated handling of `image:tag@digest` image references, as well as a fix for [CVE-2022-36109](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-36109).
* [Docker Credential Helpers v0.7.0](https://github.com/docker/docker-credential-helpers/releases/tag/v0.7.0)
* [Docker Compose v2.12.0](https://github.com/docker/compose/releases/tag/v2.12.0)
* [Kubernetes v1.25.2](https://github.com/kubernetes/kubernetes/releases/tag/v1.25.2)
* [Qemu 7.0.0](https://wiki.qemu.org/ChangeLog/7.0) used for cpu emulation, inside the Docker Desktop VM.
* [Linux kernel 5.15.49](https://hub.docker.com/layers/docker/for-desktop-kernel/5.15.49-13422a825f833d125942948cf8a8688cef721ead/images/sha256-ebf1f6f0cb58c70eaa260e9d55df7c43968874d62daced966ef6a5c5cd96b493?context=explore)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-94)

#### [For all platforms](#for-all-platforms-99)

* Docker Desktop now allows the use of TLS when talking to HTTP and HTTPS proxies to encrypt proxy usernames and passwords.
* Docker Desktop now stores HTTP and HTTPS proxy passwords in the OS credential store.
* If Docker Desktop detects that the HTTP or HTTPS proxy password has changed then it will prompt developers for the new password.
* The **Bypass proxy settings for these hosts and domains** setting now handles domain names correctly for HTTPS.
* The **Remote Repositories** view and Tip of the Day now works with HTTP and HTTPS proxies which require authentication
* We’ve introduced dark launch for features that are in early stages of the product development lifecycle. Users that are opted in can opt out at any time in the settings under the “beta features” section.
* Added categories to the Extensions Marketplace.
* Added an indicator in the whale menu and on the **Extension** tab on when extension updates are available.
* Fixed failing uninstalls of extensions with image names that do not have a namespace, as in 'my-extension'.
* Show port mapping explicitly in the **Container** tab.
* Changed the refresh rate for disk usage information for images to happen automatically once a day.
* Made the tab style consistent for the **Container** and **Volume** tabs.
* Fixed Grpcfuse filesharing mode enablement in **Settings**. Fixes [docker/for-mac#6467](https://github.com/docker/for-mac/issues/6467)
* Virtualization Framework and VirtioFS are disabled for users running macOS < 12.5.
* Ports on the **Containers** tab are now clickable.
* The Extensions SDK now allows `ddClient.extension.vm.cli.exec`, `ddClient.extension.host.cli.exec`, `ddClient.docker.cli.exec` to accept a different working directory and pass environment variables through the options parameters.
* Added a small improvement to navigate to the Extensions Marketplace when clicking on **Extensions** in the sidebar.
* Added a badge to identify new extensions in the Marketplace.
* Fixed kubernetes not starting with the containerd integration.
* Fixed `kind` not starting with the containerd integration.
* Fixed dev environments not working with the containerd integration.
* Implemented `docker diff` in the containerd integration.
* Implemented `docker run —-platform` in the containerd integration.
* Fixed insecure registries not working with the containerd integration.
* Fixed a bug that showed incorrect values on used space in **Settings**.
* Docker Desktop now installs credential helpers from Github releases. See [docker/for-win#10247](https://github.com/docker/for-win/issues/10247), [docker/for-win#12995](https://github.com/docker/for-win/issues/12995).
* Fixed an issue where users were logged out of Docker Desktop after 7 days.

#### [For Mac](#for-mac-79)

* Added **Hide**, **Hide others**, **Show all** menu items for Docker Desktop. See [docker/for-mac#6446](https://github.com/docker/for-mac/issues/6446).
* Fixed a bug which caused the application to be deleted when running the install utility from the installed application. Fixes [docker/for-mac#6442](https://github.com/docker/for-mac/issues/6442).
* By default Docker will not create the /var/run/docker.sock symlink on the host and use the docker-desktop CLI context instead.

#### [For Linux](#for-linux-20)

* Fixed a bug that prevented pushing images from the Dashboard

## [4.12.0](#4120)

*2022-09-01*

### [New](#new-53)

* Added the ability to use containerd for pulling and storing images. This is an experimental feature.
* Docker Desktop now runs untagged images. Fixes [docker/for-mac#6425](https://github.com/docker/for-mac/issues/6425).
* Added search capabilities to Docker Extension's Marketplace. Fixes [docker/roadmap#346](https://github.com/docker/roadmap/issues/346).
* Added the ability to zoom in, out or set Docker Desktop to Actual Size. This is done by using keyboard shortcuts ⌘ + / CTRL +, ⌘ - / CTRL -, ⌘ 0 / CTRL 0 on Mac and Windows respectively, or through the View menu on Mac.
* Added compose stop button if any related container is stoppable.
* Individual compose containers are now deletable from the **Container** view.
* Removed the workaround for virtiofsd <-> qemu protocol mismatch on Fedora 35, as it is no longer needed. Fedora 35 users should upgrade the qemu package to the most recent version (qemu-6.1.0-15.fc35 as of the time of writing).
* Implemented an integrated terminal for containers.
* Added a tooltip to display the link address for all external links by default.

### [Updates](#updates-24)

* [Docker Compose v2.10.2](https://github.com/docker/compose/releases/tag/v2.10.2)
* [Docker Scan v0.19.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.19.0)
* [Kubernetes v1.25.0](https://github.com/kubernetes/kubernetes/releases/tag/v1.25.0)
* [Go 1.19](https://github.com/golang/go/releases/tag/go1.19)
* [cri-dockerd v0.2.5](https://github.com/Mirantis/cri-dockerd/releases/tag/v0.2.5)
* [Buildx v0.9.1](https://github.com/docker/buildx/releases/tag/v0.9.1)
* [containerd v1.6.8](https://github.com/containerd/containerd/releases/tag/v1.6.8)
* [containerd v1.6.7](https://github.com/containerd/containerd/releases/tag/v1.6.7)
* [runc v1.1.4](https://github.com/opencontainers/runc/releases/tag/v1.1.4)
* [runc v1.1.3](https://github.com/opencontainers/runc/releases/tag/v1.1.3)

### [Security](#security-27)

#### [For all platforms](#for-all-platforms-100)

* Fixed [CVE-2023-0626](https://www.cve.org/cverecord?id=CVE-2023-0626) which allows RCE via query parameters in the message-box route in the Electron client.
* Fixed [CVE-2023-0625](https://www.cve.org/cverecord?id=CVE-2023-0625) which allows RCE via extension description/changelog which could be abused by a malicious extension.

#### [For Windows](#for-windows-81)

* Fixed [CVE-2023-0627](https://www.cve.org/cverecord?id=CVE-2023-0627) which allows to bypass for the `--no-windows-containers` installation flag which was introduced in version 4.11. This flag allows administrators to disable the use of Windows containers.
* Fixed [CVE-2023-0633](https://www.cve.org/cverecord?id=CVE-2023-0633) in which an argument injection to the Docker Desktop installer which may result in local privilege escalation.

### [Bug fixes and minor enhancements](#bug-fixes-and-minor-enhancements)

#### [For all platforms](#for-all-platforms-101)

* Compose V2 is now enabled after factory reset.
* Compose V2 is now enabled by default on new installations of Docker Desktop.
* Precedence order of environment variables in Compose is more consistent, and clearly [documented](https://docs.docker.com/compose/how-tos/environment-variables/envvars-precedence/).
* Upgraded kernel to 5.10.124.
* Improved overall performance issues caused by calculating disk size. Related to [docker/for-win#9401](https://github.com/docker/for-win/issues/9401).
* Docker Desktop now prevents users on ARM macs without Rosetta installed from switching back to Compose V1, which has only intel binaries.
* Changed the default sort order to descending for volume size and the **Created** column, along with the container's **Started** column.
* Re-organized container row actions by keeping only the start/stop and delete actions visible at all times, while allowing access to the rest via the row menu item.
* The Quickstart guide now runs every command immediately.
* Defined the sort order for container/compose **Status** column to running > some running > paused > some paused > exited > some exited > created.
* Fixed issues with the image list appearing empty in Docker Desktop even though there are images. Related to [docker/for-win#12693](https://github.com/docker/for-win/issues/12693) and [docker/for-mac#6347](https://github.com/docker/for-mac/issues/6347).
* Defined what images are "in use" based on whether or not system containers are displayed. If system containers related to Kubernetes and Extensions are not displayed, the related images are not defined as "in use."
* Fixed a bug that made Docker clients in some languages hang on `docker exec`. Fixes <https://github.com/apocas/dockerode/issues/534>.
* A failed spawned command when building an extension no longer causes Docker Desktop to unexpectedly quit.
* Fixed a bug that caused extensions to be displayed as disabled in the left menu when they are not.
* Fixed `docker login` to private registries when Registry Access Management is enabled and access to Docker Hub is blocked.
* Fixed a bug where Docker Desktop fails to start the Kubernetes cluster if the current cluster metadata is not stored in the `.kube/config` file.
* Updated the tooltips in Docker Desktop and MUI theme package to align with the overall system design.
* Copied terminal contents do not contain non-breaking spaces anymore.

#### [For Mac](#for-mac-80)

* Minimum version to install or update Docker Desktop on macOS is now 10.15. Fixes [docker/for-mac#6007](https://github.com/docker/for-mac/issues/6007).
* Fixed a bug where the Tray menu incorrectly displays "Download will start soon..." after downloading the update. Fixes some issue reported in [for-mac/issues#5677](https://github.com/docker/for-mac/issues/5677)
* Fixed a bug that didn't restart Docker Desktop after applying an update.
* Fixed a bug that caused the connection to Docker to be lost when the computer sleeps if a user is using virtualization.framework and restrictive firewall software.
* Fixed a bug that caused Docker Desktop to run in the background even after a user had quit the application. Fixes [docker/for-mac##6440](https://github.com/docker/for-mac/issues/6440)
* Disabled both Virtualization Framework and VirtioFS for users running macOS < 12.5

#### [For Windows](#for-windows-82)

* Fixed a bug where versions displayed during an update could be incorrect. Fixes [for-win/issues#12822](https://github.com/docker/for-win/issues/12822).

## [4.11.1](#4111)

*2022-08-05*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-95)

#### [For all platforms](#for-all-platforms-102)

* Fixed regression preventing VM system locations (e.g. /var/lib/docker) from being bind mounted [for-mac/issues#6433](https://github.com/docker/for-mac/issues/6433)

#### [For Windows](#for-windows-83)

* Fixed `docker login` to private registries from WSL2 distribution [docker/for-win#12871](https://github.com/docker/for-win/issues/12871)

## [4.11.0](#4110)

*2022-07-28*

### [New](#new-54)

* Docker Desktop is now fully supported for Docker Business customers inside VMware ESXi and Azure VMs. For more information, see [Run Docker Desktop inside a VM or VDI environment](https://docs.docker.com/desktop/setup/vm-vdi/)
* Added two new extensions ([vcluster](https://hub.docker.com/extensions/loftsh/vcluster-dd-extension) and [PGAdmin4](https://hub.docker.com/extensions/mochoa/pgadmin4-docker-extension)) to the Extensions Marketplace.
* The ability to sort extensions has been added to the Extensions Marketplace.
* Fixed a bug that caused some users to be asked for feedback too frequently. You'll now only be asked for feedback twice a year.
* Added custom theme settings for Docker Desktop. This allows you to specify dark or light mode for Docker Desktop independent of your device settings. Fixes [docker/for-win#12747](https://github.com/docker/for-win/issues/12747)
* Added a new flag for Windows installer. `--no-windows-containers` disables the Windows containers integration.
* Added a new flag for Mac install command. `--user <username>` sets up Docker Desktop for a specific user, preventing them from needing an admin password on first run.

### [Updates](#updates-25)

* [Docker Compose v2.7.0](https://github.com/docker/compose/releases/tag/v2.7.0)
* [Docker Compose "Cloud Integrations" v1.0.28](https://github.com/docker/compose-cli/releases/tag/v1.0.28)
* [Kubernetes v1.24.2](https://github.com/kubernetes/kubernetes/releases/tag/v1.24.2)
* [Go 1.18.4](https://github.com/golang/go/releases/tag/go1.18.4)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-96)

#### [For all platforms](#for-all-platforms-103)

* Added the Container / Compose icon as well as the exposed port(s) / exit code to the Containers screen.
* Updated the Docker theme palette colour values to match our design system.
* Improved an error message from `docker login` if Registry Access Management is blocking the Docker engine's access to Docker Hub.
* Increased throughput between the Host and Docker. For example increasing performance of `docker cp`.
* Collecting diagnostics takes less time to complete.
* Selecting or deselecting a compose app on the containers overview now selects/deselects all its containers.
* Tag names on the container overview image column are visible.
* Added search decorations to the terminal's scrollbar so that matches outside the viewport are visible.
* Fixed an issue with search which doesn't work well on containers page [docker/for-win#12828](https://github.com/docker/for-win/issues/12828).
* Fixed an issue which caused infinite loading on the **Volume** screen [docker/for-win#12789](https://github.com/docker/for-win/issues/12789).
* Fixed a problem in the Container UI where resizing or hiding columns didn't work. Fixes [docker/for-mac#6391](https://github.com/docker/for-mac/issues/6391).
* Fixed a bug where the state of installing, updating, or uninstalling multiple extensions at once was lost when leaving the Marketplace screen.
* Fixed an issue where the compose version in the about page would only get updated from v2 to v1 after restarting Docker Desktop.
* Fixed an issue where users cannot see the log view because their underlying hardware didn't support WebGL2 rendering. Fixes [docker/for-win#12825](https://github.com/docker/for-win/issues/12825).
* Fixed a bug where the UI for Containers and Images got out of sync.
* Fixed a startup race when the experimental virtualization framework is enabled.

#### [For Mac](#for-mac-81)

* Fixed an issue executing Compose commands from the UI. Fixes [docker/for-mac#6400](https://github.com/docker/for-mac/issues/6400).

#### [For Windows](#for-windows-84)

* Fixed horizontal resizing issue. Fixes [docker/for-win#12816](https://github.com/docker/for-win/issues/12816).
* If an HTTP/HTTPS proxy is configured in the UI, then it automatically sends traffic from image builds and running containers to the proxy. This avoids the need to separately configure environment variables in each container or build.
* Added the `--backend=windows` installer option to set Windows containers as the default backend.

#### [For Linux](#for-linux-21)

* Fixed bug related to setting up file shares with spaces in their path.

## [4.10.1](#4101)

*2022-07-05*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-97)

#### [For Windows](#for-windows-85)

* Fixed a bug where actions in the UI failed with Compose apps that were created from WSL. Fixes [docker/for-win#12806](https://github.com/docker/for-win/issues/12806).

#### [For Mac](#for-mac-82)

* Fixed a bug where the install command failed because paths were not initialized. Fixes [docker/for-mac#6384](https://github.com/docker/for-mac/issues/6384).

## [4.10.0](#4100)

*2022-06-30*

### [New](#new-55)

* You can now add environment variables before running an image in Docker Desktop.
* Added features to make it easier to work with a container's logs, such as regular expression search and the ability to clear container logs while the container is still running.
* Implemented feedback on the containers table. Added ports and separated container and image names.
* Added two new extensions, Ddosify and Lacework, to the Extensions Marketplace.

### [Removed](#removed-2)

* Removed Homepage while working on a new design. You can provide [feedback here](https://docs.google.com/forms/d/e/1FAIpQLSfYueBkJHdgxqsWcQn4VzBn2swu4u_rMQRIMa8LExYb_72mmQ/viewform?entry.1237514594=4.10).

### [Updates](#updates-26)

* [Docker Engine v20.10.17](https://docs.docker.com/engine/release-notes/20.10/#201017)
* [Docker Compose v2.6.1](https://github.com/docker/compose/releases/tag/v2.6.1)
* [Kubernetes v1.24.1](https://github.com/kubernetes/kubernetes/releases/tag/v1.24.1)
* [cri-dockerd to v0.2.1](https://github.com/Mirantis/cri-dockerd/releases/tag/v0.2.1)
* [CNI plugins to v1.1.1](https://github.com/containernetworking/plugins/releases/tag/v1.1.1)
* [containerd to v1.6.6](https://github.com/containerd/containerd/releases/tag/v1.6.6)
* [runc to v1.1.2](https://github.com/opencontainers/runc/releases/tag/v1.1.2)
* [Go 1.18.3](https://github.com/golang/go/releases/tag/go1.18.3)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-98)

#### [For all platforms](#for-all-platforms-104)

* Added additional bulk actions for starting/pausing/stopping selected containers in the **Containers** tab.
* Added pause and restart actions for compose projects in the **Containers** tab.
* Added icons and exposed ports or exit code information in the **Containers** tab.
* External URLs can now refer to extension details in the Extension Marketplace using links such as `docker-desktop://extensions/marketplace?extensionId=docker/logs-explorer-extension`.
* The expanded or collapsed state of the Compose apps is now persisted.
* `docker extension` CLI commands are available with Docker Desktop by default.
* Increased the size of the screenshots displayed in the Extension marketplace.
* Fixed a bug where a Docker extension fails to load if its backend container(s) are stopped. Fixes [docker/extensions-sdk#16](https://github.com/docker/extensions-sdk/issues/162).
* Fixed a bug where the image search field is cleared without a reason. Fixes [docker/for-win#12738](https://github.com/docker/for-win/issues/12738).
* Fixed a bug where the license agreement does not display and silently blocks Docker Desktop startup.
* Fixed the displayed image and tag for unpublished extensions to actually display the ones from the installed unpublished extension.
* Fixed the duplicate footer on the Support screen.
* Dev Environments can be created from a subdirectory in a GitHub repository.
* Removed the error message if the tips of the day cannot be loaded when using Docker Desktop offline. Fixes [docker/for-mac#6366](https://github.com/docker/for-mac/issues/6366).

#### [For Mac](#for-mac-83)

* Fixed a bug with location of bash completion files on macOS. Fixes [docker/for-mac#6343](https://github.com/docker/for-mac/issues/6343).
* Fixed a bug where Docker Desktop does not start if the username is longer than 25 characters. Fixes [docker/for-mac#6122](https://github.com/docker/for-mac/issues/6122).
* Fixed a bug where Docker Desktop was not starting due to invalid system proxy configuration. Fixes some issues reported in [docker/for-mac#6289](https://github.com/docker/for-mac/issues/6289).
* Fixed a bug where Docker Desktop failed to start when the experimental virtualization framework is enabled.
* Fixed a bug where the tray icon still displayed after uninstalling Docker Desktop.

#### [For Windows](#for-windows-86)

* Fixed a bug which caused high CPU usage on Hyper-V. Fixes [docker/for-win#12780](https://github.com/docker/for-win/issues/12780).
* Fixed a bug where Docker Desktop for Windows would fail to start. Fixes [docker/for-win#12784](https://github.com/docker/for-win/issues/12784).
* Fixed the `--backend=wsl-2` installer flag which did not set the backend to WSL 2. Fixes [docker/for-win#12746](https://github.com/docker/for-win/issues/12746).

#### [For Linux](#for-linux-22)

* Fixed a bug when settings cannot be applied more than once.
* Fixed Compose version displayed in the `About` screen.

### [Known Issues](#known-issues-35)

* Occasionally the Docker engine will restart during a `docker system prune`. This is a [known issue](https://github.com/moby/buildkit/pull/2177) in the version of buildkit used in the current engine and will be fixed in future releases.

## [4.9.1](#491)

*2022-06-16*

> Download Docker Desktop
>
> [Windows](https://desktop.docker.com/win/main/amd64/81317/Docker%20Desktop%20Installer.exe) ([checksum](https://desktop.docker.com/win/main/amd64/81317/checksums.txt)) | [Mac with Apple chip](https://desktop.docker.com/mac/main/arm64/81317/Docker.dmg) ([checksum](https://desktop.docker.com/mac/main/arm64/81317/checksums.txt)) | [Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/81317/Docker.dmg) ([checksum](https://desktop.docker.com/mac/main/amd64/81317/checksums.txt)) | [Debian](https://desktop.docker.com/linux/main/amd64/81317/docker-desktop-4.9.1-amd64.deb) - [RPM](https://desktop.docker.com/linux/main/amd64/81317/docker-desktop-4.9.1-x86_64.rpm) - [Arch](https://desktop.docker.com/linux/main/amd64/81317/docker-desktop-4.9.1-x86_64.pkg.tar.zst) ([checksum](https://desktop.docker.com/linux/main/amd64/81317/checksums.txt))

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-99)

#### [For all platforms](#for-all-platforms-105)

* Fixed blank dashboard screen. Fixes [docker/for-win#12759](https://github.com/docker/for-win/issues/12759).

## [4.9.0](#490)

*2022-06-02*

### [New](#new-56)

* Added additional guides on the homepage for: Elasticsearch, MariaDB, Memcached, MySQL, RabbitMQ and Ubuntu.

* Added a footer to the Docker Desktop Dashboard with general information about the Docker Desktop update status and Docker Engine statistics

* Re-designed the containers table, adding:

  * A button to copy a container ID to the clipboard
  * A pause button for each container
  * Column resizing for the containers table
  * Persistence of sorting and resizing for the containers table
  * Bulk deletion for the containers table

### [Updates](#updates-27)

* [Compose v2.6.0](https://github.com/docker/compose/releases/tag/v2.6.0)
* [Docker Engine v20.10.16](https://docs.docker.com/engine/release-notes/20.10/#201016)
* [containerd v1.6.4](https://github.com/containerd/containerd/releases/tag/v1.6.4)
* [runc v1.1.1](https://github.com/opencontainers/runc/releases/tag/v1.1.1)
* [Go 1.18.2](https://github.com/golang/go/releases/tag/go1.18.2)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-100)

#### [For all platforms](#for-all-platforms-106)

* Fixed an issue which caused Docker Desktop to hang if you quit the app whilst Docker Desktop was paused.
* Fixed the Kubernetes cluster not resetting properly after the PKI expires.
* Fixed an issue where the Extensions Marketplace was not using the defined http proxies.
* Improved the logs search functionality in Docker Desktop Dashboard to allow spaces.
* Middle-button mouse clicks on buttons in the Dashboard now behave as a left-button click instead of opening a blank window.

#### [For Mac](#for-mac-84)

* Fixed an issue to avoid creating `/opt/containerd/bin` and `/opt/containerd/lib` on the host if `/opt` has been added to the file sharing directories list.

#### [For Windows](#for-windows-87)

* Fixed a bug in the WSL 2 integration where if a file or directory is bind-mounted to a container, and the container exits, then the file or directory is replaced with the other type of object with the same name. For example, if a file is replaced with a directory or a directory with a file, any attempts to bind-mount the new object fails.
* Fixed a bug where the Tray icon and Dashboard UI didn't show up and Docker Desktop didn't fully start. Fixes [docker/for-win#12622](https://github.com/docker/for-win/issues/12622).

### [Known issues](#known-issues-36)

#### [For Linux](#for-linux-23)

* Changing ownership rights for files in bind mounts fails. This is due to the way we have implemented file sharing between the host and VM within which the Docker Engine runs. We aim to resolve this issue in the next release.

## [4.8.2](#482)

*2022-05-18*

### [Updates](#updates-28)

* [Compose v2.5.1](https://github.com/docker/compose/releases/tag/v2.5.1)

### [Bug fixes and minor enahancements](#bug-fixes-and-minor-enahancements)

* Fixed an issue with manual proxy settings which caused problems when pulling images. Fixes [docker/for-win#12714](https://github.com/docker/for-win/issues/12714) and [docker/for-mac#6315](https://github.com/docker/for-mac/issues/6315).
* Fixed high CPU usage when extensions are disabled. Fixes [docker/for-mac#6310](https://github.com/docker/for-mac/issues/6310).
* Docker Desktop now redacts HTTP proxy passwords in log files and diagnostics.

### [Known issues](#known-issues-37)

#### [For Linux](#for-linux-24)

* Changing ownership rights for files in bind mounts fails. This is due to the way we have implemented file sharing between the host and VM within which the Docker Engine runs. We aim to resolve this issue in the next release.

## [4.8.1](#481)

*2022-05-09*

### [New](#new-57)

* Released [Docker Desktop for Linux](https://docs.docker.com/desktop/setup/install/linux/).
* Beta release of [Docker Extensions](https://docs.docker.com/extensions/) and Extensions SDK.
* Created a Docker Homepage where you can run popular images and discover how to use them.
* [Compose V2 is now GA](https://www.docker.com/blog/announcing-compose-v2-general-availability/)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-101)

* Fixed a bug that caused the Kubernetes cluster to be deleted when updating Docker Desktop.

### [Known issues](#known-issues-38)

#### [For Linux](#for-linux-25)

* Changing ownership rights for files in bind mounts fails. This is due to the way we have implemented file sharing between the host and VM within which the Docker Engine runs. We aim to resolve this issue in the next release.

## [4.8.0](#480)

*2022-05-06*

### [New](#new-58)

* Released [Docker Desktop for Linux](https://docs.docker.com/desktop/setup/install/linux/).
* Beta release of [Docker Extensions](https://docs.docker.com/extensions/) and Extensions SDK.
* Created a Docker Homepage where you can run popular images and discover how to use them.
* [Compose V2 is now GA](https://www.docker.com/blog/announcing-compose-v2-general-availability/)

### [Updates](#updates-29)

* [Compose v2.5.0](https://github.com/docker/compose/releases/tag/v2.5.0)
* [Go 1.18.1](https://github.com/golang/go/releases/tag/go1.18.1)
* [Kubernetes 1.24](https://github.com/kubernetes/kubernetes/releases/tag/v1.24.0)

### [Bug fixes and minor enhancements](#bug-fixes-and-minor-enhancements-1)

#### [For all platforms](#for-all-platforms-107)

* Introduced reading system proxy. You no longer need to manually configure proxies unless it differs from your OS level proxy.

* Fixed a bug that showed Remote Repositories in the Dashboard when running behind a proxy.

* Fixed vpnkit establishing and blocking the client connection even if the server is gone. See [docker/for-mac#6235](https://github.com/docker/for-mac/issues/6235)

* Made improvements on the Volume tab in Docker Desktop:

  * Volume size is displayed.
  * Columns can be resized, hidden and reordered.
  * A columns sort order and hidden state is persisted, even after Docker Desktop restarts.
  * Row selection is persisted when switching between tabs, even after Docker Desktop restarts.

* Fixed a bug in the Dev Environments tab that did not add a scroll when more items were added to the screen.

* Standardised the header title and action in the Dashboard.

* Added support for downloading Registry Access Management policies through HTTP proxies.

* Fixed an issue related to empty remote repositories when the machine is in sleep mode for an extended period of time.

* Fixed a bug where dangling images were not selected in the cleanup process if their name was not marked as "\<none>" but their tag is.

* Improved the error message when `docker pull` fails because an HTTP proxy is required.

* Added the ability to clear the search bar easily in Docker Desktop.

* Renamed the "Containers / Apps" tab to "Containers".

* Fixed a silent crash in the Docker Desktop installer when `C:\ProgramData\DockerDesktop` is a file or a symlink.

* Fixed a bug where an image with no namespace, for example `docker pull <private registry>/image`, would be erroneously blocked by Registry Access Management unless access to Docker Hub was enabled in settings.

#### [For Mac](#for-mac-85)

* Docker Desktop's icon now matches Big Sur Style guide. See [docker/for-mac#5536](https://github.com/docker/for-mac/issues/5536)
* Fixed a problem with duplicate Dock icons and Dock icon not working as expected. Fixes [docker/for-mac#6189](https://github.com/docker/for-mac/issues/6189).
* Improved support for the `Cmd+Q` shortcut.

#### [For Windows](#for-windows-88)

* Improved support for the `Ctrl+W` shortcut.

### [Known issues](#known-issues-39)

#### [For all platforms](#for-all-platforms-108)

* Currently, if you are running a Kubernetes cluster, it will be deleted when you upgrade to Docker Desktop 4.8.0. We aim to fix this in the next release.

#### [For Linux](#for-linux-26)

* Changing ownership rights for files in bind mounts fails. This is due to the way we have implemented file sharing between the host and VM within which the Docker Engine runs. We aim to resolve this issue in the next release.

## [4.7.1](#471)

*2022-04-19*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-102)

#### [For all platforms](#for-all-platforms-109)

* Fixed a crash on the Quick Start Guide final screen.

#### [For Windows](#for-windows-89)

* Fixed a bug where update was failing with a symlink error. Fixes [docker/for-win#12650](https://github.com/docker/for-win/issues/12650).
* Fixed a bug that prevented using Windows container mode. Fixes [docker/for-win#12652](https://github.com/docker/for-win/issues/12652).

## [4.7.0](#470)

*2022-04-07*

### [New](#new-59)

* IT Administrators can now install Docker Desktop remotely using the command line.
* Add the Docker Software Bill of Materials (SBOM) CLI plugin. The new CLI plugin enables users to generate SBOMs for Docker images.
* Use [cri-dockerd](https://github.com/Mirantis/cri-dockerd) for new Kubernetes clusters instead of `dockershim`. The change is transparent from the user's point of view and Kubernetes containers run on the Docker Engine as before. `cri-dockerd` allows Kubernetes to manage Docker containers using the standard [Container Runtime Interface](https://github.com/kubernetes/cri-api#readme), the same interface used to control other container runtimes. For more information, see [The Future of Dockershim is cri-dockerd](https://www.mirantis.com/blog/the-future-of-dockershim-is-cri-dockerd/).

### [Updates](#updates-30)

* [Docker Engine v20.10.14](https://docs.docker.com/engine/release-notes/20.10/#201014)
* [Compose v2.4.1](https://github.com/docker/compose/releases/tag/v2.4.1)
* [Buildx 0.8.2](https://github.com/docker/buildx/releases/tag/v0.8.2)
* [containerd v1.5.11](https://github.com/containerd/containerd/releases/tag/v1.5.11)
* [Go 1.18](https://golang.org/doc/go1.18)

### [Security](#security-28)

* Update Docker Engine to v20.10.14 to address [CVE-2022-24769](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-24769)
* Update containerd to v1.5.11 to address [CVE-2022-24769](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-24769)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-103)

#### [For all platforms](#for-all-platforms-110)

* Fixed a bug where the Registry Access Management policy was never refreshed after a failure.
* Logs and terminals in the UI now respect your OS theme in light and dark mode.
* Easily clean up many volumes at once via multi-select checkboxes.
* Improved login feedback.

#### [For Mac](#for-mac-86)

* Fixed an issue that sometimes caused Docker Desktop to display a blank white screen. Fixes [docker/for-mac#6134](https://github.com/docker/for-mac/issues/6134).
* Fixed a problem where gettimeofday() performance drops after waking from sleep when using Hyperkit. Fixes [docker/for-mac#3455](https://github.com/docker/for-mac/issues/3455).
* Fixed an issue that caused Docker Desktop to become unresponsive during startup when `osxfs` is used for file sharing.

#### [For Windows](#for-windows-90)

* Fixed volume title. Fixes [docker/for-win#12616](https://github.com/docker/for-win/issues/12616).
* Fixed a bug in the WSL 2 integration that caused Docker commands to stop working after restarting Docker Desktop or after switching to Windows containers.

## [4.6.1](#461)

*2022-03-22*

### [Updates](#updates-31)

* [Buildx 0.8.1](https://github.com/docker/buildx/releases/tag/v0.8.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-104)

* Prevented spinning in vpnkit-forwarder filling the logs with error messages.
* Fixed diagnostics upload when there is no HTTP proxy set. Fixes [docker/for-mac#6234](https://github.com/docker/for-mac/issues/6234).
* Removed a false positive "vm is not running" error from self-diagnose. Fixes [docker/for-mac#6233](https://github.com/docker/for-mac/issues/6233).

## [4.6.0](#460)

*2022-03-14*

### [New](#new-60)

#### [For all platforms](#for-all-platforms-111)

* The Docker Desktop Dashboard Volume Management feature now offers the ability to efficiently clean up volumes using multi-select checkboxes.

#### [For Mac](#for-mac-87)

* Docker Desktop 4.6.0 gives macOS users the option of enabling a new experimental file sharing technology called VirtioFS. During testing VirtioFS has been shown to drastically reduce the time taken to sync changes between the host and VM, leading to substantial performance improvements. For more information, see [VirtioFS](https://docs.docker.com/desktop/settings-and-maintenance/settings/#beta-features).

### [Updates](#updates-32)

#### [For all platforms](#for-all-platforms-112)

* [Docker Engine v20.10.13](https://docs.docker.com/engine/release-notes/20.10/#201013)
* [Compose v2.3.3](https://github.com/docker/compose/releases/tag/v2.3.3)
* [Buildx 0.8.0](https://github.com/docker/buildx/releases/tag/v0.8.0)
* [containerd v1.4.13](https://github.com/containerd/containerd/releases/tag/v1.4.13)
* [runc v1.0.3](https://github.com/opencontainers/runc/releases/tag/v1.0.3)
* [Go 1.17.8](https://golang.org/doc/go1.17)
* [Linux kernel 5.10.104](https://hub.docker.com/layers/docker/for-desktop-kernel/5.10.104-379cadd2e08e8b25f932380e9fdaab97755357b3/images/sha256-7753b60f4544e5c5eed629d12151a49c8a4b48d98b4fb30e4e65cecc20da484d?context=explore)

### [Security](#security-29)

#### [For all platforms](#for-all-platforms-113)

* Fixed [CVE-2022-0847](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-0847), aka “Dirty Pipe”, an issue that could enable attackers to modify files in container images on the host, from inside a container. If using the WSL 2 backend, you must update WSL 2 by running `wsl --update`.

#### [For Windows](#for-windows-91)

* Fixed [CVE-2022-26659](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-26659), which could allow an attacker to overwrite any administrator writable file on the system during the installation or the update of Docker Desktop.

#### [For Mac](#for-mac-88)

* [Qemu 6.2.0](https://wiki.qemu.org/ChangeLog/6.2)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-105)

#### [For all platforms](#for-all-platforms-114)

* Fixed uploading diagnostics when an HTTPS proxy is set.
* Made checking for updates from the systray menu open the Software updates settings section.

#### [For Mac](#for-mac-89)

* Fixed the systray menu not displaying all menu items after starting Docker Desktop. Fixes [docker/for-mac#6192](https://github.com/docker/for-mac/issues/6192).
* Fixed a regression about Docker Desktop not starting in background anymore. Fixes [docker/for-mac#6167](https://github.com/docker/for-mac/issues/6167).
* Fixed missing Docker Desktop Dock icon. Fixes [docker/for-mac#6173](https://github.com/docker/for-mac/issues/6173).
* Used speed up block device access when using the experimental `virtualization.framework`. See [benchmarks](https://github.com/docker/roadmap/issues/7#issuecomment-1050626886).
* Increased default VM memory allocation to half of physical memory (min 2 GB, max 8 GB) for better out-of-the-box performances.

#### [For Windows](#for-windows-92)

* Fixed the UI stuck in `starting` state forever although Docker Desktop is working fine from the command line.
* Fixed missing Docker Desktop systray icon [docker/for-win#12573](https://github.com/docker/for-win/issues/12573)
* Fixed Registry Access Management under WSL 2 with latest 5.10.60.1 kernel.
* Fixed a UI crash when selecting the containers of a Compose application started from a WSL 2 environment. Fixes [docker/for-win#12567](https://github.com/docker/for-win/issues/12567).
* Fixed copying text from terminal in Quick Start Guide. Fixes [docker/for-win#12444](https://github.com/docker/for-win/issues/12444).

### [Known issues](#known-issues-40)

#### [For Mac](#for-mac-90)

* After enabling VirtioFS, containers with processes running with different Unix user IDs may experience caching issues. For example if a process running as `root` queries a file and another process running as user `nginx` tries to access the same file immediately, the `nginx` process will get a "Permission Denied" error.

## [4.5.1](#451)

*2022-02-15*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-106)

#### [For Windows](#for-windows-93)

* Fixed an issue that caused new installations to default to the Hyper-V backend instead of WSL 2.
* Fixed a crash in the Docker Desktop Dashboard which would make the systray menu disappear.

If you are running Docker Desktop on Windows Home, installing 4.5.1 will switch it back to WSL 2 automatically. If you are running another version of Windows, and you want Docker Desktop to use the WSL 2 backend, you must manually switch by enabling the **Use the WSL 2 based engine** option in the **Settings > General** section. Alternatively, you can edit the Docker Desktop settings file located at `%APPDATA%\Docker\settings.json` and manually switch the value of the `wslEngineEnabled` field to `true`.

## [4.5.0](#450)

*2022-02-10*

### [New](#new-61)

* Docker Desktop 4.5.0 introduces a new version of the Docker menu which creates a consistent user experience across all operating systems. For more information, see the blog post [New Docker Menu & Improved Release Highlights with Docker Desktop 4.5](https://www.docker.com/blog/new-docker-menu-improved-release-highlights-with-docker-desktop-4-5/)
* The 'docker version' output now displays the version of Docker Desktop installed on the machine.

### [Updates](#updates-33)

* [Amazon ECR Credential Helper v0.6.0](https://github.com/awslabs/amazon-ecr-credential-helper/releases/tag/v0.6.0)

### [Security](#security-30)

#### [For Mac](#for-mac-91)

* Fixed [CVE-2021-44719](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44719) where Docker Desktop could be used to access any user file on the host from a container, bypassing the allowed list of shared folders.

#### [For Windows](#for-windows-94)

* Fixed [CVE-2022-23774](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-23774) where Docker Desktop allows attackers to move arbitrary files.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-107)

#### [For all platforms](#for-all-platforms-115)

* Fixed an issue where Docker Desktop incorrectly prompted users to sign in after they quit Docker Desktop and start the application.
* Increased the filesystem watch (inotify) limits by setting `fs.inotify.max_user_watches=1048576` and `fs.inotify.max_user_instances=8192` in Linux. Fixes [docker/for-mac#6071](https://github.com/docker/for-mac/issues/6071).

#### [For Mac](#for-mac-92)

* Fixed an issue that caused the VM to become unresponsive during startup when using `osxfs` and when no host directories are shared with the VM.
* Fixed an issue that didn't allow users to stop a Docker Compose application using Docker Desktop Dashboard if the application was started in a different version of Docker Compose. For example, if the user started a Docker Compose application in V1 and then switched to Docker Compose V2, attempts to stop the Docker Compose application would fail.
* Fixed an issue where Docker Desktop incorrectly prompted users to sign in after they quit Docker Desktop and start the application.
* Fixed an issue where the **About Docker Desktop** window wasn't working anymore.
* Limit the number of CPUs to 8 on Mac M1 to fix the startup problem. Fixes [docker/for-mac#6063](https://github.com/docker/for-mac/issues/6063).

#### [For Windows](#for-windows-95)

* Fixed an issue related to compose app started with version 2, but the dashboard only deals with version 1

### [Known issues](#known-issues-41)

#### [For Windows](#for-windows-96)

Installing Docker Desktop 4.5.0 from scratch has a bug which defaults Docker Desktop to use the Hyper-V backend instead of WSL 2. This means, Windows Home users will not be able to start Docker Desktop as WSL 2 is the only supported backend. To work around this issue, you must uninstall 4.5.0 from your machine and then download and install Docker Desktop 4.5.1 or a higher version. Alternatively, you can edit the Docker Desktop settings.json file located at `%APPDATA%\Docker\settings.json` and manually switch the value of the `wslEngineEnabled` field to `true`.

## [4.4.4](#444)

*2022-01-24*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-108)

#### [For Windows](#for-windows-97)

* Fixed logging in from WSL 2. Fixes [docker/for-win#12500](https://github.com/docker/for-win/issues/12500).

### [Known issues](#known-issues-42)

#### [For Windows](#for-windows-98)

* Clicking **Proceed to Desktop** after signing in through the browser, sometimes does not bring the Dashboard to the front.
* After logging in, when the Dashboard receives focus, it sometimes stays in the foreground even when clicking a background window. As a workaround you need to click the Dashboard before clicking another application window.
* The tips of the week show on top of the mandatory login dialog when an organization restriction is enabled via a `registry.json` file.

## [4.4.3](#443)

*2022-01-14*

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-109)

#### [For Windows](#for-windows-99)

* Disabled Dashboard shortcuts to prevent capturing them even when minimized or un-focussed. Fixes [docker/for-win#12495](https://github.com/docker/for-win/issues/12495).

### [Known issues](#known-issues-43)

#### [For Windows](#for-windows-100)

* Clicking **Proceed to Desktop** after signing in through the browser, sometimes does not bring the Dashboard to the front.
* After logging in, when the Dashboard receives focus, it sometimes stays in the foreground even when clicking a background window. As a workaround you need to click the Dashboard before clicking another application window.
* The tips of the week show on top of the mandatory login dialog when an organization restriction is enabled via a `registry.json` file.

## [4.4.2](#442)

*22-01-13*

### [New](#new-62)

* Easy, Secure sign in with Auth0 and Single Sign-on

  * Single Sign-on: Users with a Docker Business subscription can now configure SSO to authenticate using their identity providers (IdPs) to access Docker. For more information, see [Single Sign-on](https://docs.docker.com/enterprise/security/single-sign-on/).
  * Signing in to Docker Desktop now takes you through the browser so that you get all the benefits of auto-filling from password managers.

### [Upgrades](#upgrades-44)

* [Docker Engine v20.10.12](https://docs.docker.com/engine/release-notes/20.10/#201012)
* [Compose v2.2.3](https://github.com/docker/compose/releases/tag/v2.2.3)
* [Kubernetes 1.22.5](https://github.com/kubernetes/kubernetes/releases/tag/v1.22.5)
* [docker scan v0.16.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.16.0)

### [Security](#security-31)

* Fixed [CVE-2021-45449](https://docs.docker.com/security/#cve-2021-45449) that affects users currently on Docker Desktop version 4.3.0 or 4.3.1.

Docker Desktop version 4.3.0 and 4.3.1 has a bug that may log sensitive information (access token or password) on the user's machine during login. This only affects users if they are on Docker Desktop 4.3.0, 4.3.1 and the user has logged in while on 4.3.0, 4.3.1. Gaining access to this data would require having access to the user’s local files.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-110)

#### [For all platforms](#for-all-platforms-116)

* Docker Desktop displays an error if `registry.json` contains more than one organization in the `allowedOrgs` field. If you are using multiple organizations for different groups of developers, you must provision a separate `registry.json` file for each group.
* Fixed a regression in Compose that reverted the container name separator from `-` to `_`. Fixes [docker/compose-switch](https://github.com/docker/compose-switch/issues/24).

#### [For Mac](#for-mac-93)

* Fixed the memory statistics for containers in the Dashboard. Fixes [docker/for-mac/#4774](https://github.com/docker/for-mac/issues/6076).
* Added a deprecated option to `settings.json`: `"deprecatedCgroupv1": true`, which switches the Linux environment back to cgroups v1. If your software requires cgroups v1, you should update it to be compatible with cgroups v2. Although cgroups v1 should continue to work, it is likely that some future features will depend on cgroups v2. It is also possible that some Linux kernel bugs will only be fixed with cgroups v2.
* Fixed an issue where putting the machine to Sleep mode after pausing Docker Desktop results in Docker Desktop not being able to resume from pause after the machine comes out of Sleep mode. Fixes [for-mac#6058](https://github.com/docker/for-mac/issues/6058).

#### [For Windows](#for-windows-101)

* Doing a `Reset to factory defaults` no longer shuts down Docker Desktop.

### [Known issues](#known-issues-44)

#### [For all platforms](#for-all-platforms-117)

* The tips of the week show on top of the mandatory login dialog when an organization restriction is enabled via a `registry.json` file.

#### [For Windows](#for-windows-102)

* Clicking **Proceed to Desktop** after logging in in the browser, sometimes does not bring the Dashboard to the front.
* After logging in, when the Dashboard receives focus, it sometimes stays in the foreground even when clicking a background window. As a workaround you need to click the Dashboard before clicking another application window.
* When the Dashboard is open, even if it does not have focus or is minimized, it will still catch keyboard shortcuts (e.g. ctrl-r for Restart)

## [4.3.2](#432)

*2021-12-21*

### [Security](#security-32)

* Fixed [CVE-2021-45449](https://docs.docker.com/security/#cve-2021-45449) that affects users currently on Docker Desktop version 4.3.0 or 4.3.1.

Docker Desktop version 4.3.0 and 4.3.1 has a bug that may log sensitive information (access token or password) on the user's machine during login. This only affects users if they are on Docker Desktop 4.3.0, 4.3.1 and the user has logged in while on 4.3.0, 4.3.1. Gaining access to this data would require having access to the user’s local files.

### [Upgrades](#upgrades-45)

[docker scan v0.14.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.14.0)

### [Security](#security-33)

**Log4j 2 CVE-2021-44228**: We have updated the `docker scan` CLI plugin. This new version of `docker scan` is able to detect [Log4j 2 CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228) and [Log4j 2 CVE-2021-45046](https://nvd.nist.gov/vuln/detail/CVE-2021-45046)

For more information, read the blog post [Apache Log4j 2 CVE-2021-44228](https://www.docker.com/blog/apache-log4j-2-cve-2021-44228/).

## [4.3.1](#431)

*2021-12-11*

### [Upgrades](#upgrades-46)

[docker scan v0.11.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.11.0)

### [Security](#security-34)

**Log4j 2 CVE-2021-44228**: We have updated the `docker scan` CLI plugin for you. Older versions of `docker scan` in Docker Desktop 4.3.0 and earlier versions are not able to detect [Log4j 2 CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228).

For more information, read the blog post [Apache Log4j 2 CVE-2021-44228](https://www.docker.com/blog/apache-log4j-2-cve-2021-44228/).

## [4.3.0](#430)

*2021-12-02*

### [Upgrades](#upgrades-47)

* [Docker Engine v20.10.11](https://docs.docker.com/engine/release-notes/20.10/#201011)
* [containerd v1.4.12](https://github.com/containerd/containerd/releases/tag/v1.4.12)
* [Buildx 0.7.1](https://github.com/docker/buildx/releases/tag/v0.7.1)
* [Compose v2.2.1](https://github.com/docker/compose/releases/tag/v2.2.1)
* [Kubernetes 1.22.4](https://github.com/kubernetes/kubernetes/releases/tag/v1.22.4)
* [Docker Hub Tool v0.4.4](https://github.com/docker/hub-tool/releases/tag/v0.4.4)
* [Go 1.17.3](https://golang.org/doc/go1.17)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-5)

#### [For all platforms](#for-all-platforms-118)

* Added a self-diagnose warning if the host lacks Internet connectivity.

* Fixed an issue which prevented users from saving files from a volume using the Save As option in the Volumes UI. Fixes [docker/for-win#12407](https://github.com/docker/for-win/issues/12407).

* Docker Desktop now uses cgroupv2. If you need to run `systemd` in a container then:

  * Ensure your version of `systemd` supports cgroupv2. [It must be at least `systemd` 247](https://github.com/systemd/systemd/issues/19760#issuecomment-851565075). Consider upgrading any `centos:7` images to `centos:8`.
  * Containers running `systemd` need the following options: [`--privileged --cgroupns=host -v /sys/fs/cgroup:/sys/fs/cgroup:rw`](https://serverfault.com/questions/1053187/systemd-fails-to-run-in-a-docker-container-when-using-cgroupv2-cgroupns-priva).

#### [For Mac](#for-mac-94)

* Docker Desktop on Apple silicon no longer requires Rosetta 2, with the exception of [three optional command line tools](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/known-issues/).

#### [For Windows](#for-windows-103)

* Fixed an issue that caused Docker Desktop to fail during startup if the home directory path contains a character used in regular expressions. Fixes [docker/for-win#12374](https://github.com/docker/for-win/issues/12374).

### [Known issue](#known-issue)

Docker Desktop Dashboard incorrectly displays the container memory usage as zero on Hyper-V based machines. You can use the [`docker stats`](/reference/cli/docker/container/stats/) command on the command line as a workaround to view the actual memory usage. See [docker/for-mac#6076](https://github.com/docker/for-mac/issues/6076).

### [Deprecation](#deprecation-3)

* The following internal DNS names are deprecated and will be removed from a future release: `docker-for-desktop`, `docker-desktop`, `docker.for.mac.host.internal`, `docker.for.mac.localhost`, `docker.for.mac.gateway.internal`. You must now use `host.docker.internal`, `vm.docker.internal`, and `gateway.docker.internal`.
* Removed: Custom RBAC rules have been removed from Docker Desktop as it gives `cluster-admin` privileges to all Service Accounts. Fixes [docker/for-mac/#4774](https://github.com/docker/for-mac/issues/4774).

## [4.2.0](#420)

*2021-11-09*

### [New](#new-63)

**Pause/Resume**: You can now pause your Docker Desktop session when you are not actively using it and save CPU resources on your machine.

* Ships [Docker Public Roadmap#226](https://github.com/docker/roadmap/issues/226)

**Software Updates**: The option to turn off automatic check for updates is now available for users on all Docker subscriptions, including Docker Personal and Docker Pro. All update-related settings have been moved to the **Software Updates** section.

* Ships [Docker Public Roadmap#228](https://github.com/docker/roadmap/issues/228)

**Window management**: The Docker Desktop Dashboard window size and position persists when you close and reopen Docker Desktop.

### [Upgrades](#upgrades-48)

* [Docker Engine v20.10.10](https://docs.docker.com/engine/release-notes/20.10/#201010)
* [containerd v1.4.11](https://github.com/containerd/containerd/releases/tag/v1.4.11)
* [runc v1.0.2](https://github.com/opencontainers/runc/releases/tag/v1.0.2)
* [Go 1.17.2](https://golang.org/doc/go1.17)
* [Compose v2.1.1](https://github.com/docker/compose/releases/tag/v2.1.1)
* [docker-scan 0.9.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.9.0)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-6)

#### [For all platforms](#for-all-platforms-119)

* Improved: Self-diagnose now also checks for overlap between host IPs and `docker networks`.
* Fixed the position of the indicator that displays the availability of an update on the Docker Desktop Dashboard.

#### [For Mac](#for-mac-95)

* Fixed an issue that caused Docker Desktop to stop responding upon clicking **Exit** on the fatal error dialog.
* Fixed a rare startup failure affecting users having a `docker volume` bind-mounted on top of a directory from the host. If existing, this fix will also remove manually user added `DENY DELETE` ACL entries on the corresponding host directory.
* Fixed a bug where a `Docker.qcow2` file would be ignored on upgrade and a fresh `Docker.raw` used instead, resulting in containers and images disappearing. Note that if a system has both files (due to the previous bug) then the most recently modified file will be used, to avoid recent containers and images disappearing again. To force the use of the old `Docker.qcow2`, delete the newer `Docker.raw` file. Fixes [docker/for-mac#5998](https://github.com/docker/for-mac/issues/5998).
* Fixed a bug where subprocesses could fail unexpectedly during shutdown, triggering an unexpected fatal error popup. Fixes [docker/for-mac#5834](https://github.com/docker/for-mac/issues/5834).

#### [For Windows](#for-windows-104)

* Fixed Docker Desktop sometimes hanging when clicking Exit in the fatal error dialog.
* Fixed an issue that frequently displayed the **Download update** popup when an update has been downloaded but hasn't been applied yet [docker/for-win#12188](https://github.com/docker/for-win/issues/12188).
* Fixed installing a new update killing the application before it has time to shut down.
* Fixed: Installation of Docker Desktop now works even with group policies preventing users to start prerequisite services (e.g. LanmanServer) [docker/for-win#12291](https://github.com/docker/for-win/issues/12291).

## [4.1.1](#411)

*2021-10-12*

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-7)

#### [For Mac](#for-mac-96)

> When upgrading from 4.1.0, the Docker menu does not change to **Update and restart** so you can just wait for the download to complete (icon changes) and then select **Restart**. This bug is fixed in 4.1.1, for future upgrades.

* Fixed a bug where a `Docker.qcow2` file would be ignored on upgrade and a fresh `Docker.raw` used instead, resulting in containers and images disappearing. If a system has both files (due to the previous bug), then the most recently modified file will be used to avoid recent containers and images disappearing again. To force the use of the old `Docker.qcow2`, delete the newer `Docker.raw` file. Fixes [docker/for-mac#5998](https://github.com/docker/for-mac/issues/5998).
* Fixed the update notification overlay sometimes getting out of sync between the **Settings** button and the **Software update** button in the Docker Desktop Dashboard.
* Fixed the menu entry to install a newly downloaded Docker Desktop update. When an update is ready to install, the **Restart** option changes to **Update and restart**.

#### [For Windows](#for-windows-105)

* Fixed a regression in WSL 2 integrations for some distributions (e.g. Arch or Alpine). Fixes [docker/for-win#12229](https://github.com/docker/for-win/issues/12229)
* Fixed update notification overlay sometimes getting out of sync between the Settings button and the Software update button in the Dashboard.

## [4.1.0](#410)

*2021-09-30*

### [New](#new-64)

* **Software Updates**: The Settings tab now includes a new section to help you manage Docker Desktop updates. The **Software Updates** section notifies you whenever there's a new update and allows you to download the update or view information on what's included in the newer version.
* **Compose V2** You can now specify whether to use Docker Compose V2 in the General settings.
* **Volume Management**: Volume management is now available for users on any subscription, including Docker Personal. Ships [Docker Public Roadmap#215](https://github.com/docker/roadmap/issues/215)

### [Upgrades](#upgrades-49)

* [Compose V2](https://github.com/docker/compose/releases/tag/v2.0.0)
* [Buildx 0.6.3](https://github.com/docker/buildx/releases/tag/v0.6.3)
* [Kubernetes 1.21.5](https://github.com/kubernetes/kubernetes/releases/tag/v1.21.5)
* [Go 1.17.1](https://github.com/golang/go/releases/tag/go1.17.1)
* [Alpine 3.14](https://alpinelinux.org/posts/Alpine-3.14.0-released.html)
* [Qemu 6.1.0](https://wiki.qemu.org/ChangeLog/6.1)
* Base distribution to debian:bullseye

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-8)

#### [For Windows](#for-windows-106)

* Fixed a bug related to anti-malware software triggering, self-diagnose avoids calling the `net.exe` utility.
* Fixed filesystem corruption in the WSL 2 Linux VM in self-diagnose. This can be caused by [microsoft/WSL#5895](https://github.com/microsoft/WSL/issues/5895).
* Fixed `SeSecurityPrivilege` requirement issue. See [docker/for-win#12037](https://github.com/docker/for-win/issues/12037).
* Fixed CLI context switch sync with UI. See [docker/for-win#11721](https://github.com/docker/for-win/issues/11721).
* Added the key `vpnKitMaxPortIdleTime` to `settings.json` to allow the idle network connection timeout to be disabled or extended.
* Fixed a crash on exit. See [docker/for-win#12128](https://github.com/docker/for-win/issues/12128).
* Fixed a bug where the CLI tools would not be available in WSL 2 distributions.
* Fixed switching from Linux to Windows containers that was stuck because access rights on panic.log. See [for-win#11899](https://github.com/docker/for-win/issues/11899).

### [Known Issues](#known-issues-45)

#### [For Windows](#for-windows-107)

Docker Desktop may fail to start when upgrading to 4.1.0 on some WSL-based distributions such as ArchWSL. See [docker/for-win#12229](https://github.com/docker/for-win/issues/12229)

## [4.0.1](#401)

*2021-09-13*

### [Upgrades](#upgrades-50)

* [Compose V2 RC3](https://github.com/docker/compose/releases/tag/v2.0.0-rc.3)

  * Compose v2 is now hosted on github.com/docker/compose.
  * Fixed go panic on downscale using `compose up --scale`.
  * Fixed a race condition in `compose run --rm` while capturing exit code.

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-9)

#### [For all platforms](#for-all-platforms-120)

* Fixed a bug where copy-paste was not available in the Docker Desktop Dashboard.

#### [For Windows](#for-windows-108)

* Fixed a bug where Docker Desktop would not start correctly with the Hyper-V engine. See [docker/for-win#11963](https://github.com/docker/for-win/issues/11963)

## [4.0.0](#400)

*2021-08-31*

### [New](#new-65)

Docker has [announced](https://www.docker.com/blog/updating-product-subscriptions/) updates and extensions to the product subscriptions to increase productivity, collaboration, and added security for our developers and businesses.

The updated [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) includes a change to the terms for **Docker Desktop**.

* Docker Desktop **remains free** for small businesses (fewer than 250 employees AND less than $10 million in annual revenue), personal use, education, and non-commercial open source projects.
* It requires a paid subscription (**Pro, Team, or Business**), for as little as $5 a month, for professional use in larger enterprises.
* The effective date of these terms is August 31, 2021. There is a grace period until January 31, 2022 for those that will require a paid subscription to use Docker Desktop.
* The Docker Pro and Docker Team subscriptions now **include commercial use** of Docker Desktop.
* The existing Docker Free subscription has been renamed **Docker Personal**.
* **No changes** to Docker Engine or any other upstream **open source** Docker or Moby project.

To understand how these changes affect you, read the [FAQs](https://www.docker.com/pricing/faq). For more information, see [Docker subscription overview](https://docs.docker.com/subscription/).

### [Upgrades](#upgrades-51)

* [Compose V2 RC2](https://github.com/docker/compose-cli/releases/tag/v2.0.0-rc.2)

  * Fixed project name to be case-insensitive for `compose down`. See [docker/compose-cli#2023](https://github.com/docker/compose-cli/issues/2023)
  * Fixed non-normalized project name.
  * Fixed port merging on partial reference.

* [Kubernetes 1.21.4](https://github.com/kubernetes/kubernetes/releases/tag/v1.21.4)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-10)

#### [For Mac](#for-mac-97)

* Fixed a bug where SSH was not available for builds from git URL. Fixes [for-mac#5902](https://github.com/docker/for-mac/issues/5902)

#### [For Windows](#for-windows-109)

* Fixed a bug where the CLI tools would not be available in WSL 2 distributions.
* Fixed a bug when switching from Linux to Windows containers due to access rights on `panic.log`. [for-win#11899](https://github.com/docker/for-win/issues/11899)

----
url: https://docs.docker.com/scout/release-notes/cli/
----

[Skip to content](#start-of-content)

You signed in with another tab or window. [Reload]() to refresh your session. You signed out in another tab or window. [Reload]() to refresh your session. You switched accounts on another tab or window. [Reload]() to refresh your session. Dismiss alert

[docker ](/docker)/ **[scout-cli](/docker/scout-cli)&#x20;**&#x50;ublic

* [Notifications ](/login?return_to=%2Fdocker%2Fscout-cli)You must be signed in to change notification settings
* [Fork 132](/login?return_to=%2Fdocker%2Fscout-cli)
* [Star 448](/login?return_to=%2Fdocker%2Fscout-cli)

# Releases: docker/scout-cli

Releases · docker/scout-cli

## v1.21.0

19 May 17:16

[docker-scout-ci](/apps/docker-scout-ci)

[v1.21.0](/docker/scout-cli/tree/v1.21.0)

[`0390daf`](/docker/scout-cli/commit/0390daf32edeaee9aca29829ac63aacde4e2ca9b)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v1.21.0](/docker/scout-cli/releases/tag/v1.21.0) [Latest](/docker/scout-cli/releases/latest)

[Latest](/docker/scout-cli/releases/latest)

## What's Changed

* Fix local DHI-derived image handling, including inherited VEX and quickview base-image display
* Improve SBOM package qualifier handling, including DHI distro qualifiers
* Update dependencies and Go toolchain

Assets 9

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## v1.20.4

08 Apr 08:04

[docker-scout-ci](/apps/docker-scout-ci)

[v1.20.4](/docker/scout-cli/tree/v1.20.4)

[`0390daf`](/docker/scout-cli/commit/0390daf32edeaee9aca29829ac63aacde4e2ca9b)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v1.20.4](/docker/scout-cli/releases/tag/v1.20.4)

## What's Changed

* Add JSON output format for docker scout compare [@benja-M-1](https://github.com/benja-M-1)
* Add image config field changes to docker scout compare output [@benja-M-1](https://github.com/benja-M-1)
* Fix Docker Desktop proxy detection in WSL2 environments [@benja-M-1](https://github.com/benja-M-1)
* Update dependencies [@benja-M-1](https://github.com/benja-M-1)

### Contributors

* [](https://github.com/benja-M-1)

benja-M-1

Assets 9

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## v1.20.3

20 Mar 12:06

[docker-scout-ci](/apps/docker-scout-ci)

[v1.20.3](/docker/scout-cli/tree/v1.20.3)

[`48f3372`](/docker/scout-cli/commit/48f3372dc714a91f8ec2635913d9b9ad1c299ada)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v1.20.3](/docker/scout-cli/releases/tag/v1.20.3)

## What's Changed

* Improve retries of temporary and network errors [@chrispatrick](https://github.com/chrispatrick)
* Fix handling of dockerfiles included in provenance attestations [@chrispatrick](https://github.com/chrispatrick)
* Fix handling of cosign sig tags [@chrispatrick](https://github.com/chrispatrick)
* Use Docker Desktop HTTP proxy transport when available [@benja-M-1](https://github.com/benja-M-1)

### Contributors

* [](https://github.com/benja-M-1)
* [](https://github.com/chrispatrick)

benja-M-1 and chrispatrick

Assets 9

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## v1.20.2

09 Mar 17:44

[docker-scout-ci](/apps/docker-scout-ci)

[v1.20.2](/docker/scout-cli/tree/v1.20.2)

[`48f3372`](/docker/scout-cli/commit/48f3372dc714a91f8ec2635913d9b9ad1c299ada)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v1.20.2](/docker/scout-cli/releases/tag/v1.20.2)

## What's Changed

* Minor consistency fixes [@chrispatrick](https://github.com/chrispatrick)

### Contributors

* [](https://github.com/chrispatrick)

chrispatrick

Assets 9

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## v1.20.1

06 Mar 10:41

[chrispatrick](/chrispatrick)

[v1.20.1](/docker/scout-cli/tree/v1.20.1)

[`48f3372`](/docker/scout-cli/commit/48f3372dc714a91f8ec2635913d9b9ad1c299ada)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v1.20.1](/docker/scout-cli/releases/tag/v1.20.1)

## What's Changed

* Fix VCS provenance parsing [@chrispatrick](https://github.com/chrispatrick)

### Contributors

* [](https://github.com/chrispatrick)

chrispatrick

Assets 9

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## v1.20.0

24 Feb 12:24

[chrispatrick](/chrispatrick)

[v1.20.0](/docker/scout-cli/tree/v1.20.0)

[`83df7af`](/docker/scout-cli/commit/83df7afcb6afb06a9c0b13972172b1b63e8355c5)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v1.20.0](/docker/scout-cli/releases/tag/v1.20.0)

## What's Changed

* Documentation updates [@dvdksn](https://github.com/dvdksn)
* Fix vulnerabilities [@jpbriend](https://github.com/jpbriend)
* Fix apk version handling [@cdupuis](https://github.com/cdupuis)
* Support SLSA v1 Provenance [@chrispatrick](https://github.com/chrispatrick)
* Update dependencies [@cdupuis](https://github.com/cdupuis)
* Fix Go purl versioning [@cdupuis](https://github.com/cdupuis)

### Contributors

* [](https://github.com/cdupuis)
* [](https://github.com/jpbriend)
* [](https://github.com/chrispatrick)
* [](https://github.com/dvdksn)

cdupuis, jpbriend, and 2 other contributors

Assets 9

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## v1.19.0

16 Dec 08:37

[chrispatrick](/chrispatrick)

[v1.19.0](/docker/scout-cli/tree/v1.19.0)

[`ae73b6e`](/docker/scout-cli/commit/ae73b6ea46d74261e26f3b9cf8b5375fb5d05951)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v1.19.0](/docker/scout-cli/releases/tag/v1.19.0)

# What's Changed

* CVE fixes [@cdupuis](https://github.com/cdupuis)
* Update dependencies [@cdupuis](https://github.com/cdupuis)
* Documentation updates [@craig-osterhout](https://github.com/craig-osterhout)
* Handle attestation source failures more gracefully [@chrispatrick](https://github.com/chrispatrick)
* Bug fixes including around VEX, versioning and indexing [@cdupuis](https://github.com/cdupuis)

### Contributors

* [](https://github.com/cdupuis)
* [](https://github.com/chrispatrick)
* [](https://github.com/craig-osterhout)

cdupuis, chrispatrick, and craig-osterhout

Assets 9

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## v1.18.4

02 Oct 16:23

[chrispatrick](/chrispatrick)

[v1.18.4](/docker/scout-cli/tree/v1.18.4)

[`fc529c7`](/docker/scout-cli/commit/fc529c7bfb840839af93a4bec124be599e7a4901)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v1.18.4](/docker/scout-cli/releases/tag/v1.18.4)

## What's Changed

* Docs updates [@craig-osterhout](https://github.com/craig-osterhout)
* VEX and SPDX fixes [@cdupuis](https://github.com/cdupuis)

### Contributors

* [](https://github.com/cdupuis)
* [](https://github.com/craig-osterhout)

cdupuis and craig-osterhout

Assets 9

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## v1.18.3

13 Aug 15:12

[cdupuis](/cdupuis)

[v1.18.3](/docker/scout-cli/tree/v1.18.3)

[`ff58efb`](/docker/scout-cli/commit/ff58efb9d2d249bdba20f241a6b25c94665bda97)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v1.18.3](/docker/scout-cli/releases/tag/v1.18.3)

## What's Changed

* Minor fixes for DHI by [@cdupuis](https://github.com/cdupuis)
* Add `docker scout vex get` command to a get merged VEX document from all VEX attestations [@cdupuis](https://github.com/cdupuis)

### Contributors

* [](https://github.com/cdupuis)

cdupuis

Assets 9

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## v1.18.2

21 Jul 14:31

[cdupuis](/cdupuis)

[v1.18.2](/docker/scout-cli/tree/v1.18.2)

[`ff58efb`](/docker/scout-cli/commit/ff58efb9d2d249bdba20f241a6b25c94665bda97)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v1.18.2](/docker/scout-cli/releases/tag/v1.18.2)

## What's Changed

* Minor fixes for DHI by [@cdupuis](https://github.com/cdupuis)
* Add `--skip-tlog` for `docker scout attest get` to skip signature verification against the transparency log by [@cdupuis](https://github.com/cdupuis)
* Do not filter CVEs that are marked with a VEX `under_investigation` statement by [@cdupuis](https://github.com/cdupuis)
* Add predicate type human names for DHI FIPS and STIG attestations by [@cdupuis](https://github.com/cdupuis)

### Contributors

* [](https://github.com/cdupuis)

cdupuis

Assets 9

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

You can’t perform that action at this time.

----
url: https://docs.docker.com/reference/samples/javascript/
----

# JavaScript samples

| Name                                                                                                     | Description                                                                                                                        |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [NGINX / Node.js / Redis](https://github.com/docker/awesome-compose/tree/master/nginx-nodejs-redis)      | A sample Node.js application with Nginx proxy and a Redis database.                                                                |
| [React / Spring / MySQL](https://github.com/docker/awesome-compose/tree/master/react-java-mysql)         | A sample React application with a Spring backend and a MySQL database.                                                             |
| [React / Express / MySQL](https://github.com/docker/awesome-compose/tree/master/react-express-mysql)     | A sample React application with a Node.js backend and a MySQL database.                                                            |
| [React / Express / MongoDB](https://github.com/docker/awesome-compose/tree/master/react-express-mongodb) | A sample React application with a Node.js backend and a Mongo database.                                                            |
| [React / Rust / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/react-rust-postgres)   | A sample React application with a Rust backend and a Postgres database.                                                            |
| [React / NGINX](https://github.com/docker/awesome-compose/tree/master/react-nginx)                       | A sample React application with Nginx.                                                                                             |
| [VueJS](https://github.com/docker/awesome-compose/tree/master/vuejs)                                     | A sample Vue.js application.                                                                                                       |
| [docker-swarm-visualizer](https://github.com/dockersamples/docker-swarm-visualizer)                      | A visualizer for Docker Swarm Mode using the Docker Remote API, Node.JS, and D3.                                                   |
| [atsea-sample-shop-app](https://github.com/dockersamples/atsea-sample-shop-app)                          | A sample app that uses a Java Spring Boot backend connected to a database to display a fictitious art shop with a React front-end. |
| [dotnet-album-viewer](https://github.com/dockersamples/dotnet-album-viewer)                              | West Wind Album Viewer ASP.NET Core and Angular sample.                                                                            |
| [aspnet-monitoring](https://github.com/dockersamples/aspnet-monitoring)                                  | Monitoring ASP.NET Fx applications in Windows Docker containers, using Prometheus.                                                 |
| [slack-clone-docker](https://github.com/dockersamples/slack-clone-docker)                                | A sample Slack Clone app built with the MERN stack.                                                                                |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/engine/security/rootless/
----

# Rootless mode

***

Table of contents

***

Rootless mode lets you run the Docker daemon and containers as a non-root user to mitigate potential vulnerabilities in the daemon and the container runtime.

Rootless mode does not require root privileges even during the installation of the Docker daemon, as long as the [prerequisites](#prerequisites) are met.

## [How it works](#how-it-works)

Rootless mode executes the Docker daemon and containers inside a user namespace. This is similar to [`userns-remap` mode](https://docs.docker.com/engine/security/userns-remap/), except that with `userns-remap` mode, the daemon itself is running with root privileges, whereas in rootless mode, both the daemon and the container are running without root privileges.

Rootless mode does not use binaries with `SETUID` bits or file capabilities, except `newuidmap` and `newgidmap`, which are needed to allow multiple UIDs/GIDs to be used in the user namespace.

## [Prerequisites](#prerequisites)

* You must install `newuidmap` and `newgidmap` on the host. These commands are provided by the `uidmap` package on most distributions.

* `/etc/subuid` and `/etc/subgid` should contain at least 65,536 subordinate UIDs/GIDs for the user. In the following example, the user `testuser` has 65,536 subordinate UIDs/GIDs (231072-296607).

```console
$ id -u
1001
$ whoami
testuser
$ grep ^$(whoami): /etc/subuid
testuser:231072:65536
$ grep ^$(whoami): /etc/subgid
testuser:231072:65536
```

The `dockerd-rootless-setuptool.sh install` script (see following) automatically shows help when the prerequisites are not satisfied.

## [Install](#install)

> Note
>
> If the system-wide Docker daemon is already running, consider disabling it:
>
> ```console
> $ sudo systemctl disable --now docker.service docker.socket
> $ sudo rm /var/run/docker.sock
> ```
>
> Should you choose not to shut down the `docker` service and socket, you will need to use the `--force` parameter in the next section. There are no known issues, but until you shutdown and disable you're still running rootful Docker.

If you installed Docker 20.10 or later with [RPM/DEB packages](/engine/install), you should have `dockerd-rootless-setuptool.sh` in `/usr/bin`.

Run `dockerd-rootless-setuptool.sh install` as a non-root user to set up the daemon:

```console
$ dockerd-rootless-setuptool.sh install
[INFO] Creating /home/testuser/.config/systemd/user/docker.service
...
[INFO] Installed docker.service successfully.
[INFO] To control docker.service, run: `systemctl --user (start|stop|restart) docker.service`
[INFO] To run docker.service on system startup, run: `sudo loginctl enable-linger testuser`

[INFO] Creating CLI context "rootless"
Successfully created context "rootless"
[INFO] Using CLI context "rootless"
Current context is now "rootless"

[INFO] Make sure the following environment variable(s) are set (or add them to ~/.bashrc):
export PATH=/usr/bin:$PATH

[INFO] Some applications may require the following environment variable too:
export DOCKER_HOST=unix:///run/user/1000/docker.sock
```

If `dockerd-rootless-setuptool.sh` is not present, you may need to install the `docker-ce-rootless-extras` package manually, e.g.,

```console
$ sudo apt-get install -y docker-ce-rootless-extras
```

If you do not have permission to run package managers like `apt-get` and `dnf`, consider using the installation script available at <https://get.docker.com/rootless>. Since static packages are not available for `s390x`, hence it is not supported for `s390x`.

```console
$ curl -fsSL https://get.docker.com/rootless | sh
...
[INFO] Creating /home/testuser/.config/systemd/user/docker.service
...
[INFO] Installed docker.service successfully.
[INFO] To control docker.service, run: `systemctl --user (start|stop|restart) docker.service`
[INFO] To run docker.service on system startup, run: `sudo loginctl enable-linger testuser`

[INFO] Creating CLI context "rootless"
Successfully created context "rootless"
[INFO] Using CLI context "rootless"
Current context is now "rootless"

[INFO] Make sure the following environment variable(s) are set (or add them to ~/.bashrc):
export PATH=/home/testuser/bin:$PATH

[INFO] Some applications may require the following environment variable too:
export DOCKER_HOST=unix:///run/user/1000/docker.sock
```

The binaries will be installed at `~/bin`.

Run `docker info` to confirm that the `docker` client is connecting to the Rootless daemon:

```console
$ docker info
Client: Docker Engine - Community
 Version:    28.3.3
 Context:    rootless
...
Server:
...
 Security Options:
  seccomp
   Profile: builtin
  rootless
  cgroupns
...
```

See [Troubleshooting](https://docs.docker.com/engine/security/rootless/troubleshoot/) if you faced an error.

----
url: https://docs.docker.com/reference/cli/docker/compose/pause/
----

# docker compose pause

***

| Description | Pause services                      |
| ----------- | ----------------------------------- |
| Usage       | `docker compose pause [SERVICE...]` |

## [Description](#description)

Pauses running containers of a service. They can be unpaused with `docker compose unpause`.

----
url: https://docs.docker.com/reference/samples/portainer/
----

# Portainer samples

| Name                                                                         | Description               |
| ---------------------------------------------------------------------------- | ------------------------- |
| [Portainer](https://github.com/docker/awesome-compose/tree/master/portainer) | A sample Portainer setup. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/reference/cli/docker/scout/
----

# docker scout

***

| Description | Command line tool for Docker Scout |
| ----------- | ---------------------------------- |
| Usage       | `docker scout [command]`           |

## [Description](#description)

Command line tool for Docker Scout

## [Subcommands](#subcommands)

| Command                                                                                               | Description                                                                                 |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [`docker scout attestation`](https://docs.docker.com/reference/cli/docker/scout/attestation/)         | Manage attestations on images                                                               |
| [`docker scout cache`](https://docs.docker.com/reference/cli/docker/scout/cache/)                     | Manage Docker Scout cache and temporary files                                               |
| [`docker scout compare`](https://docs.docker.com/reference/cli/docker/scout/compare/)                 | Compare two images and display differences (experimental)                                   |
| [`docker scout config`](https://docs.docker.com/reference/cli/docker/scout/config/)                   | Manage Docker Scout configuration                                                           |
| [`docker scout cves`](https://docs.docker.com/reference/cli/docker/scout/cves/)                       | Display CVEs identified in a software artifact                                              |
| [`docker scout enroll`](https://docs.docker.com/reference/cli/docker/scout/enroll/)                   | Enroll an organization with Docker Scout                                                    |
| [`docker scout environment`](https://docs.docker.com/reference/cli/docker/scout/environment/)         | Manage environments (experimental)                                                          |
| [`docker scout help`](https://docs.docker.com/reference/cli/docker/scout/help/)                       | Display information about the available commands                                            |
| [`docker scout integration`](https://docs.docker.com/reference/cli/docker/scout/integration/)         | Commands to list, configure, and delete Docker Scout integrations                           |
| [`docker scout policy`](https://docs.docker.com/reference/cli/docker/scout/policy/)                   | Evaluate policies against an image and display the policy evaluation results (experimental) |
| [`docker scout push`](https://docs.docker.com/reference/cli/docker/scout/push/)                       | Push an image or image index to Docker Scout                                                |
| [`docker scout quickview`](https://docs.docker.com/reference/cli/docker/scout/quickview/)             | Quick overview of an image                                                                  |
| [`docker scout recommendations`](https://docs.docker.com/reference/cli/docker/scout/recommendations/) | Display available base image updates and remediation recommendations                        |
| [`docker scout repo`](https://docs.docker.com/reference/cli/docker/scout/repo/)                       | Commands to list, enable, and disable Docker Scout on repositories                          |
| [`docker scout sbom`](https://docs.docker.com/reference/cli/docker/scout/sbom/)                       | Generate or display SBOM of an image                                                        |
| [`docker scout stream`](https://docs.docker.com/reference/cli/docker/scout/stream/)                   | Manage streams (experimental)                                                               |
| [`docker scout version`](https://docs.docker.com/reference/cli/docker/scout/version/)                 | Show Docker Scout version information                                                       |
| [`docker scout vex`](https://docs.docker.com/reference/cli/docker/scout/vex/)                         | Manage VEX attestations on images                                                           |
| [`docker scout watch`](https://docs.docker.com/reference/cli/docker/scout/watch/)                     | Watch repositories in a registry and push images and indexes to Docker Scout                |

----
url: https://docs.docker.com/reference/cli/docker/stack/
----

# docker stack

***

| Description | Manage Swarm stacks      |
| ----------- | ------------------------ |
| Usage       | `docker stack [OPTIONS]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Manage stacks.

## [Subcommands](#subcommands)

| Command                                                                                 | Description                                                          |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [`docker stack config`](https://docs.docker.com/reference/cli/docker/stack/config/)     | Outputs the final config file, after doing merges and interpolations |
| [`docker stack deploy`](https://docs.docker.com/reference/cli/docker/stack/deploy/)     | Deploy a new stack or update an existing stack                       |
| [`docker stack ls`](https://docs.docker.com/reference/cli/docker/stack/ls/)             | List stacks                                                          |
| [`docker stack ps`](https://docs.docker.com/reference/cli/docker/stack/ps/)             | List the tasks in the stack                                          |
| [`docker stack rm`](https://docs.docker.com/reference/cli/docker/stack/rm/)             | Remove one or more stacks                                            |
| [`docker stack services`](https://docs.docker.com/reference/cli/docker/stack/services/) | List the services in the stack                                       |

----
url: https://docs.docker.com/reference/cli/docker/stack/config/
----

# docker stack config

***

| Description | Outputs the final config file, after doing merges and interpolations |
| ----------- | -------------------------------------------------------------------- |
| Usage       | `docker stack config [OPTIONS]`                                      |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Outputs the final Compose file, after doing the merges and interpolations of the input Compose files.

## [Options](#options)

| Option                 | Default | Description                                       |
| ---------------------- | ------- | ------------------------------------------------- |
| `-c, --compose-file`   |         | Path to a Compose file, or `-` to read from stdin |
| `--skip-interpolation` |         | Skip interpolation and output only merged config  |

## [Examples](#examples)

The following command outputs the result of the merge and interpolation of two Compose files.

```console
$ docker stack config --compose-file docker-compose.yml --compose-file docker-compose.prod.yml
```

The Compose file can also be provided as standard input with `--compose-file -`:

```console
$ cat docker-compose.yml | docker stack config --compose-file -
```

### [Skipping interpolation](#skipping-interpolation)

In some cases, it might be useful to skip interpolation of environment variables. For example, when you want to pipe the output of this command back to `stack deploy`.

If you have a regex for a redirect route in an environment variable for your webserver you would use two `$` signs to prevent `stack deploy` from interpolating `${1}`.

```yaml
  service: webserver
  environment:
    REDIRECT_REGEX=http://host/redirect/$${1}
```

With interpolation, the `stack config` command will replace the environment variable in the Compose file with `REDIRECT_REGEX=http://host/redirect/${1}`, but then when piping it back to the `stack deploy` command it will be interpolated again and result in undefined behavior. That is why, when piping the output back to `stack deploy` one should always prefer the `--skip-interpolation` option.

```console
$ docker stack config --compose-file web.yml --compose-file web.prod.yml --skip-interpolation | docker stack deploy --compose-file -
```

----
url: https://docs.docker.com/reference/cli/docker/buildx/dial-stdio/
----

# docker buildx dial-stdio

***

| Description | Proxy current stdio streams to builder instance |
| ----------- | ----------------------------------------------- |
| Usage       | `docker buildx dial-stdio`                      |

## [Description](#description)

dial-stdio uses the stdin and stdout streams of the command to proxy to the configured builder instance. It is not intended to be used by humans, but rather by other tools that want to interact with the builder instance via BuildKit API.

## [Options](#options)

| Option       | Default | Description                                                                                          |
| ------------ | ------- | ---------------------------------------------------------------------------------------------------- |
| `--platform` |         | Target platform: this is used for node selection                                                     |
| `--progress` | `none`  | Set type of progress output (`auto`, `plain`, `rawjson`, `tty`). Use plain to show container output  |

## [Examples](#examples)

Example go program that uses the dial-stdio command wire up a buildkit client. This is, for example, use only and may not be suitable for production use.

```go
client.New(ctx, "", client.WithContextDialer(func(context.Context, string) (net.Conn, error) {
    c1, c2 := net.Pipe()
    cmd := exec.Command("docker", "buildx", "dial-stdio")
    cmd.Stdin = c1
    cmd.Stdout = c1

    if err := cmd.Start(); err != nil {
        c1.Close()
        c2.Close()
        return nil, err
    }

    go func() {
        cmd.Wait()
        c2.Close()
    }()

    return c2
}))
```

----
url: https://docs.docker.com/reference/api/extensions-sdk/ExecStreamOptions/
----

# Interface: ExecStreamOptions

***

Table of contents

***

**`Since`**

0.2.2

## [Properties](#properties)

### [onOutput](#onoutput)

• `Optional` **onOutput**: (`data`: { `stdout`: `string` ; `stderr?`: `undefined` } | { `stdout?`: `undefined` ; `stderr`: `string` }) => `void`

#### [Type declaration](#type-declaration)

▸ (`data`): `void`

Invoked when receiving output from command execution. By default, the output is split into chunks at arbitrary boundaries. If you prefer the output to be split into complete lines, set `splitOutputLines` to true. The callback is then invoked once for each line.

**`Since`**

0.2.0

##### [Parameters](#parameters)

| Name   | Type                                                                               | Description                                                                        |
| ------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `data` | `{ stdout: string; stderr?: undefined } \| { stdout?: undefined; stderr: string }` | Output content. Can include either stdout string, or stderr string, one at a time. |

##### [Returns](#returns)

`void`

***

### [onError](#onerror)

• `Optional` **onError**: (`error`: `any`) => `void`

#### [Type declaration](#type-declaration-1)

▸ (`error`): `void`

Invoked to report error if the executed command errors.

##### [Parameters](#parameters-1)

| Name    | Type  | Description                                 |
| ------- | ----- | ------------------------------------------- |
| `error` | `any` | The error happening in the executed command |

##### [Returns](#returns-1)

`void`

***

### [onClose](#onclose)

• `Optional` **onClose**: (`exitCode`: `number`) => `void`

#### [Type declaration](#type-declaration-2)

▸ (`exitCode`): `void`

Invoked when process exits.

##### [Parameters](#parameters-2)

| Name       | Type     | Description           |
| ---------- | -------- | --------------------- |
| `exitCode` | `number` | The process exit code |

##### [Returns](#returns-2)

`void`

***

### [splitOutputLines](#splitoutputlines)

• `Optional` `Readonly` **splitOutputLines**: `boolean`

Specifies the behaviour invoking `onOutput(data)`. Raw output by default, splitting output at any position. If set to true, `onOutput` will be invoked once for each line.

----
url: https://docs.docker.com/ai/sandboxes/
----

# Docker Sandboxes

***

Table of contents

***

Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each sandbox gets its own Docker daemon, filesystem, and network — the agent can build containers, install packages, and modify files without touching your host system.

Organization admins can [centrally manage sandbox network and filesystem policies](https://docs.docker.com/ai/sandboxes/security/governance/) from the Docker Admin Console, so the same rules apply uniformly across every developer's machine. Available on a separate paid subscription.

## [Get started](#get-started)

For complete system requirements, see the [get started prerequisites](https://docs.docker.com/ai/sandboxes/get-started/#prerequisites).

Install the `sbx` CLI and sign in:

```console
$ brew install docker/tap/sbx
$ sbx login
```

```powershell
> winget install -h Docker.sbx
> sbx login
```

```console
$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
$ sudo apt-get install docker-sbx
$ sudo usermod -aG kvm $USER
$ newgrp kvm
$ sbx login
```

Then launch an agent in a sandbox:

```console
$ cd ~/my-project
$ sbx run claude
```

See the [get started guide](https://docs.docker.com/ai/sandboxes/get-started/) for a full walkthrough, or jump to the [usage guide](https://docs.docker.com/ai/sandboxes/usage/) for common patterns.

## [Learn more](#learn-more)

* [Agents](https://docs.docker.com/ai/sandboxes/agents/) — supported agents and per-agent configuration
* [Customize](https://docs.docker.com/ai/sandboxes/customize/) — reusable templates and declarative kits for extending or tailoring sandboxes
* [Architecture](https://docs.docker.com/ai/sandboxes/architecture/) — microVM isolation, workspace mounting, networking
* [Security](https://docs.docker.com/ai/sandboxes/security/) — isolation model, credential handling, and network policies
* [CLI reference](/reference/cli/sbx/) — full list of `sbx` commands and options
* [Troubleshooting](https://docs.docker.com/ai/sandboxes/troubleshooting/) — common issues and fixes
* [FAQ](https://docs.docker.com/ai/sandboxes/faq/) — login requirements, telemetry, etc

## [Feedback](#feedback)

Your feedback shapes what gets built next. If you run into a bug, hit a missing feature, or have a suggestion, open an issue at [github.com/docker/sbx-releases/issues](https://github.com/docker/sbx-releases/issues).

----
url: https://docs.docker.com/reference/cli/sbx/kit/pack/
----

# sbx kit pack

| Description | Package a directory as a kit artifact |
| ----------- | ------------------------------------- |
| Usage       | `sbx kit pack DIRECTORY [flags]`      |

## [Description](#description)

Validate and package a kit artifact directory as a ZIP file.

The directory must contain a valid spec.yaml and an optional files/ directory.

## [Options](#options)

| Option         | Default | Description                                 |
| -------------- | ------- | ------------------------------------------- |
| `-o, --output` |         | Output ZIP file path (default: \<name>.zip) |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/image-access-management/
----

# Image Access Management

***

Table of contents

***

Subscription: Business

For: Administrators

Image Access Management lets administrators control which types of images developers can pull from Docker Hub. This prevents developers from accidentally using untrusted community images that could pose security risks to your organization.

With Image Access Management, you can restrict access to:

* Docker Official Images: Curated images maintained by Docker
* Docker Verified Publisher Images: Images from trusted commercial publishers
* Organization images: Your organization's private repositories
* Community images: Public images from individual developers

You can also use a repository allowlist to approve specific repositories that bypass all other access controls.

## [Who should use Image Access Management?](#who-should-use-image-access-management)

Image Access Management helps prevent supply chain attacks by ensuring developers only use trusted container images. For example, a developer building a new application might accidentally use a malicious community image as a component. Image Access Management prevents this by restricting access to only approved image types.

Common security scenarios include:

* Prevent use of unmaintained or malicious community images
* Ensure developers use only vetted, official base images
* Control access to commercial third-party images
* Maintain consistent security standards across development teams

Use the repository allowlist when you need to:

* Grant access to specific vetted community images
* Allow essential third-party tools that don't fall under official categories
* Provide exceptions to general image access policies for specific business requirements

## [Prerequisites](#prerequisites)

Before configuring Image Access Management, you must:

* [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/). Image Access Management only takes effect when users are signed in to Docker Desktop with organization credentials.
* Use [personal access tokens (PATs)](https://docs.docker.com/security/access-tokens/) for authentication (Organization access tokens aren't supported)
* Have a Docker Business subscription

## [Configure image access](#configure-image-access)

> Note
>
> Image Access Management is turned off by default for organization members. Organization owners always have access to all images regardless of policy settings.

To configure Image Access Management:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down.

2. Select **Admin Console**, then **Image access**.

3. Use the **toggle** to enable image access.

4. Select which image types to allow:

   * **Organization images**: Images from your organization (always allowed by default). These can be public or private images created by members within your organization.
   * **Community images**: Images contributed by various users that may pose security risks. This category includes Docker-Sponsored Open Source images and is turned off by default.
   * **Docker Verified Publisher Images**: Images from Docker partners in the Verified Publisher program, qualified for secure supply chains.
   * **Docker Official Images**: Curated Docker repositories that provide OS repositories, best practices for Dockerfiles, drop-in solutions, and timely security updates.
   * **Repository allowlist**: A list of specific repositories that should be allowed. Configure in the next step.

5. If **Repository allowlist** is enabled in the previous step, you can add or remove specific repositories in the allow list:

   * To add repositories, in the **Repository allowlist** section, select **Add repositories to allowlist** and follow the on-screen instructions.
   * To remove a repository, in the **Repository allowlist** section, select the trashcan icon next to it.

   Repositories in the allow list are accessible to all organization members regardless of the image type restrictions configured in the previous steps.

After restrictions are applied, organization members can view the permissions page in read-only format.

## [Verify access restrictions](#verify-access-restrictions)

After configuring Image Access Management, test that restrictions work correctly.

When developers pull allowed image types:

```console
$ docker pull nginx  # Docker Official Image
# Pull succeeds if Docker Official Images are allowed
```

When developers pull blocked image types:

```console
$ docker pull someuser/custom-image  # Community image
Error response from daemon: image access denied: community images not allowed
```

Image access restrictions apply to all Docker Hub operations including pulls, builds using `FROM` instructions, and Docker Compose services.

## [Best practices](#best-practices)

* Start with the most restrictive policy and gradually expand based on legitimate business needs:

  1. Start with Docker Official Images and Organization images
  2. If needed, add Docker Verified Publisher Images for commercial tools
  3. Carefully evaluate community images only for specific, vetted use cases
  4. Use the repository allowlist sparingly. Only add repositories that have been thoroughly vetted and approved through your organization's security review process

* Monitor usage patterns: Review which images developers are attempting to pull, identify legitimate requests for additional image types, regularly audit approved image categories for continued relevance, and use Docker Desktop analytics to monitor usage patterns.

* Regularly review the repository allow list: Periodically audit the repositories in your allowlist to ensure they remain necessary and trustworthy, and remove any that are no longer needed or maintained.

## [Scope and bypass considerations](#scope-and-bypass-considerations)

* Image Access Management only controls access to Docker Hub images. Images from other registries aren't affected by these policies. Use [Registry Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/) to control access to other registries.
* Users can potentially bypass Image Access Management by signing out of Docker Desktop (unless sign-in is enforced), using images from other registries that aren't restricted, or using registry mirrors or proxies. Enforce sign-in and combine with Registry Access Management for comprehensive control.
* Image restrictions apply to Dockerfile `FROM` instructions, Docker Compose services using restricted images will fail, multi-stage builds may be affected if intermediate images are restricted, and CI/CD pipelines using diverse image types may be impacted.

## [Next steps](#next-steps)

* Layer security controls: Image Access Management works best with [Registry Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/) to control which registries developers can access, [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) to secure containers at runtime, and [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) to control Docker Desktop configuration.

----
url: https://docs.docker.com/reference/cli/docker/network/ls/
----

# docker network ls

***

| Description                                                               | List networks                 |
| ------------------------------------------------------------------------- | ----------------------------- |
| Usage                                                                     | `docker network ls [OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker network list`         |

## [Description](#description)

Lists all the networks the Engine `daemon` knows about. This includes the networks that span across multiple hosts in a cluster.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --filter`](#filter) |         | Provide filter values (e.g. `driver=bridge`)                                                                                                                                                                                                                                                                                                                                           |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| [`--no-trunc`](#no-trunc) |         | Do not truncate the output                                                                                                                                                                                                                                                                                                                                                             |
| `-q, --quiet`             |         | Only display network IDs                                                                                                                                                                                                                                                                                                                                                               |

## [Examples](#examples)

### [List all networks](#list-all-networks)

```console
$ docker network ls
NETWORK ID          NAME                DRIVER          SCOPE
7fca4eb8c647        bridge              bridge          local
9f904ee27bf5        none                null            local
cf03ee007fb4        host                host            local
78b03ee04fc4        multi-host          overlay         swarm
```

### [List networks without truncating the ID column (--no-trun)](#no-trunc)

Use the `--no-trunc` option to display the full network id:

```console
$ docker network ls --no-trunc
NETWORK ID                                                         NAME                DRIVER           SCOPE
18a2866682b85619a026c81b98a5e375bd33e1b0936a26cc497c283d27bae9b3   none                null             local
c288470c46f6c8949c5f7e5099b5b7947b07eabe8d9a27d79a9cbf111adcbf47   host                host             local
7b369448dccbf865d397c8d2be0cda7cf7edc6b0945f77d2529912ae917a0185   bridge              bridge           local
95e74588f40db048e86320c6526440c504650a1ff3e9f7d60a497c4d2163e5bd   foo                 bridge           local
63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161   dev                 bridge           local
```

### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). Multiple filter flags are combined as an `OR` filter. For example, `-f type=custom -f type=builtin` returns both `custom` and `builtin` networks.

The currently supported filters are:

* driver
* id (network's id)
* label (`label=<key>` or `label=<key>=<value>`)
* name (network's name)
* scope (`swarm|global|local`)
* type (`custom|builtin`)

#### [Driver](#driver)

The `driver` filter matches networks based on their driver.

The following example matches networks with the `bridge` driver:

```console
$ docker network ls --filter driver=bridge
NETWORK ID          NAME                DRIVER            SCOPE
db9db329f835        test1               bridge            local
f6e212da9dfd        test2               bridge            local
```

#### [ID](#id)

The `id` filter matches on all or part of a network's ID.

The following filter matches all networks with an ID containing the `63d1ff1f77b0...` string.

```console
$ docker network ls --filter id=63d1ff1f77b07ca51070a8c227e962238358bd310bde1529cf62e6c307ade161
NETWORK ID          NAME                DRIVER           SCOPE
63d1ff1f77b0        dev                 bridge           local
```

You can also filter for a substring in an ID as this shows:

```console
$ docker network ls --filter id=95e74588f40d
NETWORK ID          NAME                DRIVER          SCOPE
95e74588f40d        foo                 bridge          local

$ docker network ls --filter id=95e
NETWORK ID          NAME                DRIVER          SCOPE
95e74588f40d        foo                 bridge          local
```

#### [Label](#label)

The `label` filter matches networks based on the presence of a `label` alone or a `label` and a value.

The following filter matches networks with the `usage` label regardless of its value.

```console
$ docker network ls -f "label=usage"
NETWORK ID          NAME                DRIVER         SCOPE
db9db329f835        test1               bridge         local
f6e212da9dfd        test2               bridge         local
```

The following filter matches networks with the `usage` label with the `prod` value.

```console
$ docker network ls -f "label=usage=prod"
NETWORK ID          NAME                DRIVER        SCOPE
f6e212da9dfd        test2               bridge        local
```

#### [Name](#name)

The `name` filter matches on all or part of a network's name.

The following filter matches all networks with a name containing the `foobar` string.

```console
$ docker network ls --filter name=foobar
NETWORK ID          NAME                DRIVER       SCOPE
06e7eef0a170        foobar              bridge       local
```

You can also filter for a substring in a name as this shows:

```console
$ docker network ls --filter name=foo
NETWORK ID          NAME                DRIVER       SCOPE
95e74588f40d        foo                 bridge       local
06e7eef0a170        foobar              bridge       local
```

#### [Scope](#scope)

The `scope` filter matches networks based on their scope.

The following example matches networks with the `swarm` scope:

```console
$ docker network ls --filter scope=swarm
NETWORK ID          NAME                DRIVER              SCOPE
xbtm0v4f1lfh        ingress             overlay             swarm
ic6r88twuu92        swarmnet            overlay             swarm
```

The following example matches networks with the `local` scope:

```console
$ docker network ls --filter scope=local
NETWORK ID          NAME                DRIVER              SCOPE
e85227439ac7        bridge              bridge              local
0ca0e19443ed        host                host                local
ca13cc149a36        localnet            bridge              local
f9e115d2de35        none                null                local
```

#### [Type](#type)

The `type` filter supports two values; `builtin` displays predefined networks (`bridge`, `none`, `host`), whereas `custom` displays user defined networks.

The following filter matches all user defined networks:

```console
$ docker network ls --filter type=custom
NETWORK ID          NAME                DRIVER       SCOPE
95e74588f40d        foo                 bridge       local
63d1ff1f77b0        dev                 bridge       local
```

By having this flag it allows for batch cleanup. For example, use this filter to delete all user defined networks:

```console
$ docker network rm `docker network ls --filter type=custom -q`
```

A warning will be issued when trying to remove a network that has containers attached.

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints networks output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder  | Description                                                                            |
| ------------ | -------------------------------------------------------------------------------------- |
| `.ID`        | Network ID                                                                             |
| `.Name`      | Network name                                                                           |
| `.Driver`    | Network driver                                                                         |
| `.Scope`     | Network scope (local, global)                                                          |
| `.IPv6`      | Whether IPv6 is enabled on the network or not.                                         |
| `.Internal`  | Whether the network is internal or not.                                                |
| `.Labels`    | All labels assigned to the network.                                                    |
| `.Label`     | Value of a specific label for this network. For example `{{.Label "project.version"}}` |
| `.CreatedAt` | Time when the network was created                                                      |

When using the `--format` option, the `network ls` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `ID` and `Driver` entries separated by a colon (`:`) for all networks:

```console
$ docker network ls --format "{{.ID}}: {{.Driver}}"
afaaab448eb2: bridge
d1584f8dc718: host
391df270dc66: null
```

To list all networks in JSON format, use the `json` directive:

```console
$ docker network ls --format json
{"CreatedAt":"2021-03-09 21:41:29.798999529 +0000 UTC","Driver":"bridge","ID":"f33ba176dd8e","IPv6":"false","Internal":"false","Labels":"","Name":"bridge","Scope":"local"}
{"CreatedAt":"2021-03-09 21:41:29.772806592 +0000 UTC","Driver":"host","ID":"caf47bb3ac70","IPv6":"false","Internal":"false","Labels":"","Name":"host","Scope":"local"}
{"CreatedAt":"2021-03-09 21:41:29.752212603 +0000 UTC","Driver":"null","ID":"9d096c122066","IPv6":"false","Internal":"false","Labels":"","Name":"none","Scope":"local"}
```

----
url: https://docs.docker.com/reference/cli/docker/swarm/init/
----

# docker swarm init

***

| Description | Initialize a swarm            |
| ----------- | ----------------------------- |
| Usage       | `docker swarm init [OPTIONS]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Initialize a swarm. The Docker Engine targeted by this command becomes a manager in the newly created single-node swarm.

## [Options](#options)

| Option                                            | Default        | Description                                                                                                                             |
| ------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| [`--advertise-addr`](#advertise-addr)             |                | Advertised address (format: `<ip\|interface>[:port]`)                                                                                   |
| [`--autolock`](#autolock)                         |                | Enable manager autolocking (requiring an unlock key to start a stopped manager)                                                         |
| [`--availability`](#availability)                 | `active`       | Availability of the node (`active`, `pause`, `drain`)                                                                                   |
| `--cert-expiry`                                   | `2160h0m0s`    | Validity period for node certificates (ns\|us\|ms\|s\|m\|h)                                                                             |
| [`--data-path-addr`](#data-path-addr)             |                | API 1.31+ Address or interface to use for data path traffic (format: `<ip\|interface>`)                                                 |
| [`--data-path-port`](#data-path-port)             |                | API 1.40+ Port number to use for data path traffic (1024 - 49151). If no value is set or is set to 0, the default port (4789) is used.  |
| [`--default-addr-pool`](#default-addr-pool)       |                | API 1.39+ default address pool in CIDR format                                                                                           |
| `--default-addr-pool-mask-length`                 | `24`           | API 1.39+ default address pool subnet mask length                                                                                       |
| [`--dispatcher-heartbeat`](#dispatcher-heartbeat) | `5s`           | Dispatcher heartbeat period (ns\|us\|ms\|s\|m\|h)                                                                                       |
| [`--external-ca`](#external-ca)                   |                | Specifications of one or more certificate signing endpoints                                                                             |
| [`--force-new-cluster`](#force-new-cluster)       |                | Force create a new cluster from current state                                                                                           |
| [`--listen-addr`](#listen-addr)                   | `0.0.0.0:2377` | Listen address (format: `<ip\|interface>[:port]`)                                                                                       |
| [`--max-snapshots`](#max-snapshots)               |                | API 1.25+ Number of additional Raft snapshots to retain                                                                                 |
| [`--snapshot-interval`](#snapshot-interval)       | `10000`        | API 1.25+ Number of log entries between Raft snapshots                                                                                  |
| `--task-history-limit`                            | `5`            | Task history retention limit                                                                                                            |

## [Examples](#examples)

```console
$ docker swarm init --advertise-addr 192.168.99.121

Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233... 172.17.0.2:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
```

The `docker swarm init` command generates two random tokens: a worker token and a manager token. When you join a new node to the swarm, the node joins as a worker or manager node based upon the token you pass to [swarm join](/reference/cli/docker/swarm/join/).

After you create the swarm, you can display or rotate the token using [swarm join-token](/reference/cli/docker/swarm/join-token/).

### [Protect manager keys and data (--autolock)](#autolock)

The `--autolock` flag enables automatic locking of managers with an encryption key. The private keys and data stored by all managers are protected by the encryption key printed in the output, and is inaccessible without it. Make sure to store this key securely, in order to reactivate a manager after it restarts. Pass the key to the `docker swarm unlock` command to reactivate the manager. You can disable autolock by running `docker swarm update --autolock=false`. After disabling it, the encryption key is no longer required to start the manager, and it will start up on its own without user intervention.

### [Configure node healthcheck frequency (--dispatcher-heartbeat)](#dispatcher-heartbeat)

The `--dispatcher-heartbeat` flag sets the frequency at which nodes are told to report their health.

### [Use an external certificate authority (--external-ca)](#external-ca)

This flag sets up the swarm to use an external CA to issue node certificates. The value takes the form `protocol=X,url=Y`. The value for `protocol` specifies what protocol should be used to send signing requests to the external CA. Currently, the only supported value is `cfssl`. The URL specifies the endpoint where signing requests should be submitted.

### [Force-restart node as a single-mode manager (--force-new-cluster)](#force-new-cluster)

This flag forces an existing node that was part of a quorum that was lost to restart as a single-node Manager without losing its data.

### [Specify interface for inbound control plane traffic (--listen-addr)](#listen-addr)

The node listens for inbound swarm manager traffic on this address. The default is to listen on `0.0.0.0:2377`. It is also possible to specify a network interface to listen on that interface's address; for example `--listen-addr eth0:2377`.

Specifying a port is optional. If the value is a bare IP address or interface name, the default port 2377 is used.

### [Specify interface for outbound control plane traffic (--advertise-addr)](#advertise-addr)

The `--advertise-addr` flag specifies the address that will be advertised to other members of the swarm for API access and overlay networking. If unspecified, Docker will check if the system has a single IP address, and use that IP address with the listening port (see `--listen-addr`). If the system has multiple IP addresses, `--advertise-addr` must be specified so that the correct address is chosen for inter-manager communication and overlay networking.

It is also possible to specify a network interface to advertise that interface's address; for example `--advertise-addr eth0:2377`.

Specifying a port is optional. If the value is a bare IP address or interface name, the default port 2377 is used.

### [Specify interface for data traffic (--data-path-addr)](#data-path-addr)

The `--data-path-addr` flag specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter you can separate the container's data traffic from the management traffic of the cluster.

If unspecified, the IP address or interface of the advertise address is used.

Setting `--data-path-addr` does not restrict which interfaces or source IP addresses the VXLAN socket is bound to. Similar to `--advertise-addr`, the purpose of this flag is to inform other members of the swarm about which address to use for control plane traffic. To restrict access to the VXLAN port of the node, use firewall rules.

### [Configure port number for data traffic (--data-path-port)](#data-path-port)

The `--data-path-port` flag allows you to configure the UDP port number to use for data path traffic. The provided port number must be within the 1024 - 49151 range. If this flag isn't set, or if it's set to 0, the default port number 4789 is used. The data path port can only be configured when initializing the swarm, and applies to all nodes that join the swarm. The following example initializes a new Swarm, and configures the data path port to UDP port 7777;

```console
$ docker swarm init --data-path-port=7777
```

After the swarm is initialized, use the `docker info` command to verify that the port is configured:

```console
$ docker info
<...>
ClusterID: 9vs5ygs0gguyyec4iqf2314c0
Managers: 1
Nodes: 1
Data Path Port: 7777
<...>
```

### [Specify default subnet pools (--default-addr-pool)](#default-addr-pool)

The `--default-addr-pool` flag specifies default subnet pools for global scope networks. For example, to specify two address pools:

```console
$ docker swarm init \
  --default-addr-pool 30.30.0.0/16 \
  --default-addr-pool 40.40.0.0/16
```

Use the `--default-addr-pool-mask-length` flag to specify the default subnet pools mask length for the subnet pools.

### [Set limit for number of snapshots to keep (--max-snapshots)](#max-snapshots)

This flag sets the number of old Raft snapshots to retain in addition to the current Raft snapshots. By default, no old snapshots are retained. This option may be used for debugging, or to store old snapshots of the swarm state for disaster recovery purposes.

### [Configure Raft snapshot log interval (--snapshot-interval)](#snapshot-interval)

The `--snapshot-interval` flag specifies how many log entries to allow in between Raft snapshots. Setting this to a high number will trigger snapshots less frequently. Snapshots compact the Raft log and allow for more efficient transfer of the state to new managers. However, there is a performance cost to taking snapshots frequently.

### [Configure the availability of a manager (--availability)](#availability)

The `--availability` flag specifies the availability of the node at the time the node joins a master. Possible availability values are `active`, `pause`, or `drain`.

This flag is useful in certain situations. For example, a cluster may want to have dedicated manager nodes that don't serve as worker nodes. You can do this by passing `--availability=drain` to `docker swarm init`.

----
url: https://docs.docker.com/reference/cli/sbx/completion/bash/
----

# sbx completion bash

| Description | Generate the autocompletion script for bash |
| ----------- | ------------------------------------------- |
| Usage       | `sbx completion bash`                       |

## [Description](#description)

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

```
source <(sbx completion bash)
```

To load completions for every new session, execute once:

#### [Linux:](#linux)

```
sbx completion bash > /etc/bash_completion.d/sbx
```

#### [macOS:](#macos)

```
sbx completion bash > $(brew --prefix)/etc/bash_completion.d/sbx
```

You will need to start a new shell for this setup to take effect.

## [Options](#options)

| Option              | Default | Description                     |
| ------------------- | ------- | ------------------------------- |
| `--no-descriptions` |         | disable completion descriptions |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/engine/logging/drivers/gelf/
----

# Graylog Extended Format logging driver

***

Table of contents

***

The `gelf` logging driver is a convenient format that's understood by a number of tools such as [Graylog](https://www.graylog.org/), [Logstash](https://www.elastic.co/products/logstash), and [Fluentd](https://www.fluentd.org). Many tools use this format.

In GELF, every log message is a dict with the following fields:

* Version
* Host (who sent the message in the first place)
* Timestamp
* Short and long version of the message
* Any custom fields you configure yourself

## [Usage](#usage)

To use the `gelf` driver as the default logging driver, set the `log-driver` and `log-opt` keys to appropriate values in the `daemon.json` file. For more about configuring Docker using `daemon.json`, see [daemon.json](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file).

> Note
>
> If you're using Docker Desktop, edit the daemon configuration through the Docker Desktop Dashboard. Open **Settings** and select **Docker Engine**. For details, see [Docker Engine settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine).

The following example sets the log driver to `gelf` and sets the `gelf-address` option.

```json
{
  "log-driver": "gelf",
  "log-opts": {
    "gelf-address": "udp://1.2.3.4:12201"
  }
}
```

Restart Docker for the changes to take effect.

> Note
>
> `log-opts` configuration options in the `daemon.json` configuration file must be provided as strings. Boolean and numeric values (such as the value for `gelf-tcp-max-reconnect`) must therefore be enclosed in quotes (`"`).

You can set the logging driver for a specific container by setting the `--log-driver` flag when using `docker container create` or `docker run`:

```console
$ docker run \
      --log-driver gelf --log-opt gelf-address=udp://1.2.3.4:12201 \
      alpine echo hello world
```

### [GELF options](#gelf-options)

The `gelf` logging driver supports the following options:

| Option                     | Required | Description                                                                                                                                                                                                                                                                                      | Example value                                      |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `gelf-address`             | required | The address of the GELF server. `tcp` and `udp` are the only supported URI specifier and you must specify the port.                                                                                                                                                                              | `--log-opt gelf-address=udp://192.168.0.42:12201`  |
| `gelf-compression-type`    | optional | `UDP Only` The type of compression the GELF driver uses to compress each log message. Allowed values are `gzip`, `zlib` and `none`. The default is `gzip`. Note that enabled compression leads to excessive CPU usage, so it's highly recommended to set this to `none`.                         | `--log-opt gelf-compression-type=gzip`             |
| `gelf-compression-level`   | optional | `UDP Only` The level of compression when `gzip` or `zlib` is the `gelf-compression-type`. An integer in the range of `-1` to `9` (BestCompression). Default value is 1 (BestSpeed). Higher levels provide more compression at lower speed. Either `-1` or `0` disables compression.              | `--log-opt gelf-compression-level=2`               |
| `gelf-tcp-max-reconnect`   | optional | `TCP Only` The maximum number of reconnection attempts when the connection drop. A positive integer. Default value is 3.                                                                                                                                                                         | `--log-opt gelf-tcp-max-reconnect=3`               |
| `gelf-tcp-reconnect-delay` | optional | `TCP Only` The number of seconds to wait between reconnection attempts. A positive integer. Default value is 1.                                                                                                                                                                                  | `--log-opt gelf-tcp-reconnect-delay=1`             |
| `tag`                      | optional | A string that's appended to the `APP-NAME` in the `gelf` message. By default, Docker uses the first 12 characters of the container ID to tag log messages. Refer to the [log tag option documentation](https://docs.docker.com/engine/logging/log_tags/) for customizing the log tag format.     | `--log-opt tag=mailer`                             |
| `labels`                   | optional | Applies when starting the Docker daemon. A comma-separated list of logging-related labels this daemon accepts. Adds additional key on the `extra` fields, prefixed by an underscore (`_`). Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                | `--log-opt labels=production_status,geo`           |
| `labels-regex`             | optional | Similar to and compatible with `labels`. A regular expression to match logging-related labels. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                                                                                                            | `--log-opt labels-regex=^(production_status\|geo)` |
| `env`                      | optional | Applies when starting the Docker daemon. A comma-separated list of logging-related environment variables this daemon accepts. Adds additional key on the `extra` fields, prefixed by an underscore (`_`). Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/). | `--log-opt env=os,customer`                        |
| `env-regex`                | optional | Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                                                                                                | `--log-opt env-regex=^(os\|customer)`              |

> Note
>
> The `gelf` driver doesn't support TLS for TCP connections. Messages sent to TLS-protected inputs can silently fail.

### [Examples](#examples)

This example configures the container to use the GELF server running at `192.168.0.42` on port `12201`.

```console
$ docker run -dit \
    --log-driver=gelf \
    --log-opt gelf-address=udp://192.168.0.42:12201 \
    alpine sh
```

----
url: https://docs.docker.com/security/2fa/
----

# Enable two-factor authentication for your Docker account

***

Table of contents

***

Two-factor authentication (2FA) adds an essential security layer to your Docker account by requiring a unique security code in addition to your password when signing in. This prevents unauthorized access even if your password is compromised.

When you turn on two-factor authentication, Docker provides a unique recovery code specific to your account. Store this code securely as it lets you recover your account if you lose access to your authenticator app.

## [Key benefits](#key-benefits)

Two-factor authentication significantly improves your account security:

* Protection against password breaches: Even if your password is stolen or leaked, attackers can't access your account without your second factor.
* Secure CLI access: Required for Docker CLI authentication when 2FA is turned on, ensuring automated tools use personal access tokens instead of passwords.
* Compliance requirements: Many organizations require 2FA for accessing development and production resources.
* Peace of mind: Know that your Docker repositories, images, and account settings are protected by industry-standard security practices.

## [Prerequisites](#prerequisites)

Before turning on two-factor authentication, you need:

* A smartphone or device with a Time-based One-time password (TOTP) authenticator app installed
* Access to your Docker account password

## [Enable two-factor authentication](#enable-two-factor-authentication)

To turn on 2FA for your Docker account:

1. Sign in to your [Docker account](https://app.docker.com/login).
2. Select your avatar and then from the drop-down menu, select **Account settings**.
3. Select **2FA**.
4. Enter your account password, then select **Confirm**.
5. Save your recovery code and store it somewhere safe. You can use your recovery code to recover your account in the event you lose access to your authenticator app.
6. Use a TOTP mobile app to scan the QR code or enter the text code.
7. Once you've linked your authenticator app, enter the six-digit code in the text-field.
8. Select **Enable 2FA**.

Two-factor authentication is now active on your account. You'll need to enter a security code from your authenticator app each time you sign in.

## [Disable two-factor authentication](#disable-two-factor-authentication)

> Warning
>
> Disabling two-factor authentication results in decreased security for your Docker account.

1. Sign in to your [Docker account](https://app.docker.com/login).
2. Select your avatar and then from the drop-down menu, select **Account settings**.
3. Select **2FA**.
4. Enter your password, then select **Confirm**.
5. Select **Disable 2FA**.

----
url: https://docs.docker.com/reference/cli/docker/compose/commit/
----

# docker compose commit

***

| Description | Create a new image from a service container's changes        |
| ----------- | ------------------------------------------------------------ |
| Usage       | `docker compose commit [OPTIONS] SERVICE [REPOSITORY[:TAG]]` |

## [Description](#description)

Create a new image from a service container's changes

## [Options](#options)

| Option          | Default | Description                                                |
| --------------- | ------- | ---------------------------------------------------------- |
| `-a, --author`  |         | Author (e.g., "John Hannibal Smith <hannibal@a-team.com>") |
| `-c, --change`  |         | Apply Dockerfile instruction to the created image          |
| `--index`       |         | index of the container if service has multiple replicas.   |
| `-m, --message` |         | Commit message                                             |
| `-p, --pause`   | `true`  | Pause container during commit                              |

----
url: https://docs.docker.com/build/buildkit/configure/
----

# Configure BuildKit

***

Table of contents

***

If you create a `docker-container` or `kubernetes` builder with Buildx, you can apply a custom [BuildKit configuration](https://docs.docker.com/build/buildkit/toml-configuration/) by passing the [`--buildkitd-config` flag](/reference/cli/docker/buildx/create/#buildkitd-config) to the `docker buildx create` command.

## [Registry mirror](#registry-mirror)

You can define a registry mirror to use for your builds. Doing so redirects BuildKit to pull images from a different hostname. The following steps exemplify defining a mirror for `docker.io` (Docker Hub) to `mirror.gcr.io`.

1. Create a TOML at `/etc/buildkitd.toml` with the following content:

   ```toml
   debug = true
   [registry."docker.io"]
     mirrors = ["mirror.gcr.io"]
   ```

   > Note
   >
   > `debug = true` turns on debug requests in the BuildKit daemon, which logs a message that shows when a mirror is being used.

2. Create a `docker-container` builder that uses this BuildKit configuration:

   ```console
   $ docker buildx create --use --bootstrap \
     --name mybuilder \
     --driver docker-container \
     --buildkitd-config /etc/buildkitd.toml
   ```

3. Build an image:

   ```bash
   docker buildx build --load . -f - <<EOF
   FROM alpine
   RUN echo "hello world"
   EOF
   ```

The BuildKit logs for this builder now shows that it uses the GCR mirror. You can tell by the fact that the response messages include the `x-goog-*` HTTP headers.

```console
$ docker logs buildx_buildkit_mybuilder0
```

```text
...
time="2022-02-06T17:47:48Z" level=debug msg="do request" request.header.accept="application/vnd.docker.container.image.v1+json, */*" request.header.user-agent=containerd/1.5.8+unknown request.method=GET spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
time="2022-02-06T17:47:48Z" level=debug msg="fetch response received" response.header.accept-ranges=bytes response.header.age=1356 response.header.alt-svc="h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"" response.header.cache-control="public, max-age=3600" response.header.content-length=1469 response.header.content-type=application/octet-stream response.header.date="Sun, 06 Feb 2022 17:25:17 GMT" response.header.etag="\"774380abda8f4eae9a149e5d5d3efc83\"" response.header.expires="Sun, 06 Feb 2022 18:25:17 GMT" response.header.last-modified="Wed, 24 Nov 2021 21:07:57 GMT" response.header.server=UploadServer response.header.x-goog-generation=1637788077652182 response.header.x-goog-hash="crc32c=V3DSrg==" response.header.x-goog-hash.1="md5=d0OAq9qPTq6aFJ5dXT78gw==" response.header.x-goog-metageneration=1 response.header.x-goog-storage-class=STANDARD response.header.x-goog-stored-content-encoding=identity response.header.x-goog-stored-content-length=1469 response.header.x-guploader-uploadid=ADPycduqQipVAXc3tzXmTzKQ2gTT6CV736B2J628smtD1iDytEyiYCgvvdD8zz9BT1J1sASUq9pW_ctUyC4B-v2jvhIxnZTlKg response.status="200 OK" spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
time="2022-02-06T17:47:48Z" level=debug msg="fetch response received" response.header.accept-ranges=bytes response.header.age=760 response.header.alt-svc="h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"" response.header.cache-control="public, max-age=3600" response.header.content-length=1471 response.header.content-type=application/octet-stream response.header.date="Sun, 06 Feb 2022 17:35:13 GMT" response.header.etag="\"35d688bd15327daafcdb4d4395e616a8\"" response.header.expires="Sun, 06 Feb 2022 18:35:13 GMT" response.header.last-modified="Wed, 24 Nov 2021 21:07:12 GMT" response.header.server=UploadServer response.header.x-goog-generation=1637788032100793 response.header.x-goog-hash="crc32c=aWgRjA==" response.header.x-goog-hash.1="md5=NdaIvRUyfar8201DleYWqA==" response.header.x-goog-metageneration=1 response.header.x-goog-storage-class=STANDARD response.header.x-goog-stored-content-encoding=identity response.header.x-goog-stored-content-length=1471 response.header.x-guploader-uploadid=ADPycdtR-gJYwC7yHquIkJWFFG8FovDySvtmRnZBqlO3yVDanBXh_VqKYt400yhuf0XbQ3ZMB9IZV2vlcyHezn_Pu3a1SMMtiw response.status="200 OK" spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
time="2022-02-06T17:47:48Z" level=debug msg=fetch spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
time="2022-02-06T17:47:48Z" level=debug msg=fetch spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
time="2022-02-06T17:47:48Z" level=debug msg=fetch spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
time="2022-02-06T17:47:48Z" level=debug msg=fetch spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
time="2022-02-06T17:47:48Z" level=debug msg="do request" request.header.accept="application/vnd.docker.image.rootfs.diff.tar.gzip, */*" request.header.user-agent=containerd/1.5.8+unknown request.method=GET spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
time="2022-02-06T17:47:48Z" level=debug msg="fetch response received" response.header.accept-ranges=bytes response.header.age=1356 response.header.alt-svc="h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"" response.header.cache-control="public, max-age=3600" response.header.content-length=2818413 response.header.content-type=application/octet-stream response.header.date="Sun, 06 Feb 2022 17:25:17 GMT" response.header.etag="\"1d55e7be5a77c4a908ad11bc33ebea1c\"" response.header.expires="Sun, 06 Feb 2022 18:25:17 GMT" response.header.last-modified="Wed, 24 Nov 2021 21:07:06 GMT" response.header.server=UploadServer response.header.x-goog-generation=1637788026431708 response.header.x-goog-hash="crc32c=ZojF+g==" response.header.x-goog-hash.1="md5=HVXnvlp3xKkIrRG8M+vqHA==" response.header.x-goog-metageneration=1 response.header.x-goog-storage-class=STANDARD response.header.x-goog-stored-content-encoding=identity response.header.x-goog-stored-content-length=2818413 response.header.x-guploader-uploadid=ADPycdsebqxiTBJqZ0bv9zBigjFxgQydD2ESZSkKchpE0ILlN9Ibko3C5r4fJTJ4UR9ddp-UBd-2v_4eRpZ8Yo2llW_j4k8WhQ response.status="200 OK" spanID=9460e5b6e64cec91 traceID=b162d3040ddf86d6614e79c66a01a577
...
```

## [Setting registry certificates](#setting-registry-certificates)

If you specify registry certificates in the BuildKit configuration, the daemon copies the files into the container under `/etc/buildkit/certs`. The following steps show adding a self-signed registry certificate to the BuildKit configuration.

1. Add the following configuration to `/etc/buildkitd.toml`:

   ```toml
   # /etc/buildkitd.toml
   debug = true
   [registry."myregistry.com"]
     ca=["/etc/certs/myregistry.pem"]
     [[registry."myregistry.com".keypair]]
       key="/etc/certs/myregistry_key.pem"
       cert="/etc/certs/myregistry_cert.pem"
   ```

   This tells the builder to push images to the `myregistry.com` registry using the certificates in the specified location (`/etc/certs`).

2. Create a `docker-container` builder that uses this configuration:

   ```console
   $ docker buildx create --use --bootstrap \
     --name mybuilder \
     --driver docker-container \
     --buildkitd-config /etc/buildkitd.toml
   ```

3. Inspect the builder's configuration file (`/etc/buildkit/buildkitd.toml`), it shows that the certificate configuration is now configured in the builder.

   ```console
   $ docker exec -it buildx_buildkit_mybuilder0 cat /etc/buildkit/buildkitd.toml
   ```

   ```toml
   debug = true

   [registry]

     [registry."myregistry.com"]
       ca = ["/etc/buildkit/certs/myregistry.com/myregistry.pem"]

       [[registry."myregistry.com".keypair]]
         cert = "/etc/buildkit/certs/myregistry.com/myregistry_cert.pem"
         key = "/etc/buildkit/certs/myregistry.com/myregistry_key.pem"
   ```

4. Verify that the certificates are inside the container:

   ```console
   $ docker exec -it buildx_buildkit_mybuilder0 ls /etc/buildkit/certs/myregistry.com/
   myregistry.pem    myregistry_cert.pem   myregistry_key.pem
   ```

Now you can push to the registry using this builder, and it will authenticate using the certificates:

```console
$ docker buildx build --push --tag myregistry.com/myimage:latest .
```

## [CNI networking](#cni-networking)

CNI networking for builders can be useful for dealing with network port contention during concurrent builds. CNI is [not yet](https://github.com/moby/buildkit/issues/28) available in the default BuildKit image. But you can create your own image that includes CNI support.

The following Dockerfile example shows a custom BuildKit image with CNI support. It uses the [CNI config for integration tests](https://github.com/moby/buildkit/blob/master//hack/fixtures/cni.json) in BuildKit as an example. Feel free to include your own CNI configuration.

```dockerfile
# syntax=docker/dockerfile:1

ARG BUILDKIT_VERSION=v0.28.0
ARG CNI_VERSION=v1.0.1

FROM --platform=$BUILDPLATFORM alpine AS cni-plugins
RUN apk add --no-cache curl
ARG CNI_VERSION
ARG TARGETOS
ARG TARGETARCH
WORKDIR /opt/cni/bin
RUN curl -Ls https://github.com/containernetworking/plugins/releases/download/$CNI_VERSION/cni-plugins-$TARGETOS-$TARGETARCH-$CNI_VERSION.tgz | tar xzv

FROM moby/buildkit:${BUILDKIT_VERSION}
ARG BUILDKIT_VERSION
RUN apk add --no-cache iptables
COPY --from=cni-plugins /opt/cni/bin /opt/cni/bin
ADD https://raw.githubusercontent.com/moby/buildkit/${BUILDKIT_VERSION}/hack/fixtures/cni.json /etc/buildkit/cni.json
```

Now you can build this image, and create a builder instance from it using [the `--driver-opt image` option](/reference/cli/docker/buildx/create/#driver-opt):

```console
$ docker buildx build --tag buildkit-cni:local --load .
$ docker buildx create --use --bootstrap \
  --name mybuilder \
  --driver docker-container \
  --driver-opt "image=buildkit-cni:local" \
  --buildkitd-flags "--oci-worker-net=cni"
```

## [Resource limiting](#resource-limiting)

### [Max parallelism](#max-parallelism)

You can limit the parallelism of the BuildKit solver, which is particularly useful for low-powered machines, using a [BuildKit configuration](https://docs.docker.com/build/buildkit/toml-configuration/) while creating a builder with the [`--buildkitd-config` flag](/reference/cli/docker/buildx/create/#buildkitd-config).

```toml
# /etc/buildkitd.toml
[worker.oci]
  max-parallelism = 4
```

Now you can [create a `docker-container` builder](https://docs.docker.com/build/builders/drivers/docker-container/) that will use this BuildKit configuration to limit parallelism.

```console
$ docker buildx create --use \
  --name mybuilder \
  --driver docker-container \
  --buildkitd-config /etc/buildkitd.toml
```

### [TCP connection limit](#tcp-connection-limit)

TCP connections are limited to 4 simultaneous connections per registry for pulling and pushing images, plus one additional connection dedicated to metadata requests. This connection limit prevents your build from getting stuck while pulling images. The dedicated metadata connection helps reduce the overall build time.

More information: [moby/buildkit#2259](https://github.com/moby/buildkit/pull/2259)

----
url: https://docs.docker.com/engine/logging/drivers/local/
----

# Local file logging driver

***

Table of contents

***

The `local` logging driver captures output from container's stdout/stderr and writes them to an internal storage that's optimized for performance and disk use.

By default, the `local` driver preserves 100MB of log messages per container and uses automatic compression to reduce the size on disk. The 100MB default value is based on a 20M default size for each file and a default count of 5 for the number of such files (to account for log rotation).

> Warning
>
> The `local` logging driver uses file-based storage. These files are designed to be exclusively accessed by the Docker daemon. Interacting with these files with external tools may interfere with Docker's logging system and result in unexpected behavior, and should be avoided.

## [Usage](#usage)

To use the `local` driver as the default logging driver, set the `log-driver` and `log-opt` keys to appropriate values in the `daemon.json` file. For more about configuring Docker using `daemon.json`, see [daemon.json](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file).

> Note
>
> If you're using Docker Desktop, edit the daemon configuration through the Docker Desktop Dashboard. Open **Settings** and select **Docker Engine**. For details, see [Docker Engine settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine).

The following example sets the log driver to `local` and sets the `max-size` option.

```json
{
  "log-driver": "local",
  "log-opts": {
    "max-size": "10m"
  }
}
```

Restart Docker for the changes to take effect for newly created containers. Existing containers don't use the new logging configuration automatically.

You can set the logging driver for a specific container by using the `--log-driver` flag to `docker container create` or `docker run`:

```console
$ docker run \
      --log-driver local --log-opt max-size=10m \
      alpine echo hello world
```

Note that `local` is a bash reserved keyword, so you may need to quote it in scripts.

### [Options](#options)

The `local` logging driver supports the following logging options:

| Option     | Description                                                                                                                                                   | Example value              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `max-size` | The maximum size of the log before it's rolled. A positive integer plus a modifier representing the unit of measure (`k`, `m`, or `g`). Defaults to 20m.      | `--log-opt max-size=10m`   |
| `max-file` | The maximum number of log files that can be present. If rolling the logs creates excess files, the oldest file is removed. A positive integer. Defaults to 5. | `--log-opt max-file=3`     |
| `compress` | Toggle compression of rotated log files. Enabled by default.                                                                                                  | `--log-opt compress=false` |

### [Examples](#examples)

This example starts an `alpine` container which can have a maximum of 3 log files no larger than 10 megabytes each.

```console
$ docker run -it --log-driver local --log-opt max-size=10m --log-opt max-file=3 alpine ash
```

----
url: https://docs.docker.com/reference/cli/docker/sandbox/
----

# docker sandbox

***

| Description | Docker Sandbox   |
| ----------- | ---------------- |
| Usage       | `docker sandbox` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Local sandbox environments for AI agents, using Docker.

## [Options](#options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Subcommands](#subcommands)

| Command                                                                                   | Description                                           |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [`docker sandbox create`](https://docs.docker.com/reference/cli/docker/sandbox/create/)   | Create a sandbox for an agent                         |
| [`docker sandbox exec`](https://docs.docker.com/reference/cli/docker/sandbox/exec/)       | Execute a command inside a sandbox                    |
| [`docker sandbox inspect`](https://docs.docker.com/reference/cli/docker/sandbox/inspect/) | Display detailed information on one or more sandboxes |
| [`docker sandbox ls`](https://docs.docker.com/reference/cli/docker/sandbox/ls/)           | List VMs                                              |
| [`docker sandbox network`](https://docs.docker.com/reference/cli/docker/sandbox/network/) | Manage sandbox networking                             |
| [`docker sandbox reset`](https://docs.docker.com/reference/cli/docker/sandbox/reset/)     | Reset all VM sandboxes and clean up state             |
| [`docker sandbox rm`](https://docs.docker.com/reference/cli/docker/sandbox/rm/)           | Remove one or more sandboxes                          |
| [`docker sandbox run`](https://docs.docker.com/reference/cli/docker/sandbox/run/)         | Run an agent in a sandbox                             |
| [`docker sandbox save`](https://docs.docker.com/reference/cli/docker/sandbox/save/)       | Save a snapshot of the sandbox as a template          |
| [`docker sandbox stop`](https://docs.docker.com/reference/cli/docker/sandbox/stop/)       | Stop one or more sandboxes without removing them      |
| [`docker sandbox version`](https://docs.docker.com/reference/cli/docker/sandbox/version/) | Show sandbox version information                      |

----
url: https://docs.docker.com/engine/network/links/
----

# Legacy container links

***

Table of contents

***

> Warning
>
> The `--link` flag is a legacy feature of Docker. It may eventually be removed. Unless you absolutely need to continue using it, we recommend that you use user-defined networks to facilitate communication between two containers instead of using `--link`. One feature that user-defined networks do not support that you can do with `--link` is sharing environment variables between containers. However, you can use other mechanisms such as volumes to share environment variables between containers in a more controlled way.
>
> See [Differences between user-defined bridges and the default bridge](https://docs.docker.com/engine/network/drivers/bridge/#differences-between-user-defined-bridges-and-the-default-bridge) for some alternatives to using `--link`.

The information in this section explains legacy container links within the Docker default `bridge` network which is created automatically when you install Docker.

Before the [Docker networks feature](https://docs.docker.com/engine/network/), you could use the Docker link feature to allow containers to discover each other and securely transfer information about one container to another container. With the introduction of the Docker networks feature, you can still create links but they behave differently between default `bridge` network and [user defined networks](https://docs.docker.com/engine/network/drivers/bridge/#differences-between-user-defined-bridges-and-the-default-bridge).

This section briefly discusses connecting via a network port and then goes into detail on container linking in default `bridge` network.

## [Connect using network port mapping](#connect-using-network-port-mapping)

Let's say you used this command to run a simple Python Flask application:

```console
$ docker run -d -P training/webapp python app.py
```

When that container was created, the `-P` flag was used to automatically map any network port inside it to a random high port within an *ephemeral port range* on your Docker host. Next, when `docker ps` was run, you saw that port 5000 in the container was bound to port 49155 on the host.

```console
$ docker ps nostalgic_morse

CONTAINER ID  IMAGE                   COMMAND       CREATED        STATUS        PORTS                    NAMES
bc533791f3f5  training/webapp:latest  python app.py 5 seconds ago  Up 2 seconds  0.0.0.0:49155->5000/tcp  nostalgic_morse
```

You also saw how you can bind a container's ports to a specific port using the `-p` flag. Here port 80 of the host is mapped to port 5000 of the container:

```console
$ docker run -d -p 80:5000 training/webapp python app.py
```

And you saw why this isn't such a great idea because it constrains you to only one container on that specific port.

Instead, you may specify a range of host ports to bind a container port to that is different than the default *ephemeral port range*:

```console
$ docker run -d -p 8000-9000:5000 training/webapp python app.py
```

This would bind port 5000 in the container to a randomly available port between 8000 and 9000 on the host.

There are also a few other ways you can configure the `-p` flag. By default the `-p` flag binds the specified port to all interfaces on the host machine. But you can also specify a binding to a specific interface, for example only to the `localhost`.

```console
$ docker run -d -p 127.0.0.1:80:5000 training/webapp python app.py
```

This would bind port 5000 inside the container to port 80 on the `localhost` or `127.0.0.1` interface on the host machine.

Or, to bind port 5000 of the container to a dynamic port but only on the `localhost`, you could use:

```console
$ docker run -d -p 127.0.0.1::5000 training/webapp python app.py
```

You can also bind UDP and SCTP (typically used by telecom protocols such as SIGTRAN, Diameter, and S1AP/X2AP) ports by adding a trailing `/udp` or `/sctp`. For example:

```console
$ docker run -d -p 127.0.0.1:80:5000/udp training/webapp python app.py
```

You also learned about the useful `docker port` shortcut which showed us the current port bindings. This is also useful for showing you specific port configurations. For example, if you've bound the container port to the `localhost` on the host machine, then the `docker port` output reflects that.

```console
$ docker port nostalgic_morse 5000

127.0.0.1:49155
```

> Note
>
> The `-p` flag can be used multiple times to configure multiple ports.

## [Connect with the linking system](#connect-with-the-linking-system)

> Note
>
> This section covers the legacy link feature in the default `bridge` network. Refer to [differences between user-defined bridges and the default bridge](https://docs.docker.com/engine/network/drivers/bridge/#differences-between-user-defined-bridges-and-the-default-bridge) for more information on links in user-defined networks.

Network port mappings are not the only way Docker containers can connect to one another. Docker also has a linking system that allows you to link multiple containers together and send connection information from one to another. When containers are linked, information about a source container can be sent to a recipient container. This allows the recipient to see selected data describing aspects of the source container.

### [The importance of naming](#the-importance-of-naming)

To establish links, Docker relies on the names of your containers. You've already seen that each container you create has an automatically created name; indeed you've become familiar with our old friend `nostalgic_morse` during this guide. You can also name containers yourself. This naming provides two useful functions:

1. It can be useful to name containers that do specific functions in a way that makes it easier for you to remember them, for example naming a container containing a web application `web`.

2. It provides Docker with a reference point that allows it to refer to other containers, for example, you can specify to link the container `web` to container `db`.

You can name your container by using the `--name` flag, for example:

```console
$ docker run -d -P --name web training/webapp python app.py
```

This launches a new container and uses the `--name` flag to name the container `web`. You can see the container's name using the `docker ps` command.

```console
$ docker ps -l

CONTAINER ID  IMAGE                  COMMAND        CREATED       STATUS       PORTS                    NAMES
aed84ee21bde  training/webapp:latest python app.py  12 hours ago  Up 2 seconds 0.0.0.0:49154->5000/tcp  web
```

You can also use `docker inspect` to return the container's name.

> Note
>
> Container names must be unique. That means you can only call one container `web`. If you want to reuse a container name you must delete the old container (with `docker container rm`) before you can create a new container with the same name. As an alternative you can use the `--rm` flag with the `docker run` command. This deletes the container immediately after it is stopped.

## [Communication across links](#communication-across-links)

Links allow containers to discover each other and securely transfer information about one container to another container. When you set up a link, you create a conduit between a source container and a recipient container. The recipient can then access select data about the source. To create a link, you use the `--link` flag. First, create a new container, this time one containing a database.

```console
$ docker run -d --name db training/postgres
```

This creates a new container called `db` from the `training/postgres` image, which contains a PostgreSQL database.

Now, you need to delete the `web` container you created previously so you can replace it with a linked one:

```console
$ docker container rm -f web
```

Now, create a new `web` container and link it with your `db` container.

```console
$ docker run -d -P --name web --link db:db training/webapp python app.py
```

This links the new `web` container with the `db` container you created earlier. The `--link` flag takes the form:

```
--link <name or id>:alias
```

Where `name` is the name of the container we're linking to and `alias` is an alias for the link name. That alias is used shortly. The `--link` flag also takes the form:

```
--link <name or id>
```

In this case the alias matches the name. You could write the previous example as:

```console
$ docker run -d -P --name web --link db training/webapp python app.py
```

Next, inspect your linked containers with `docker inspect`:

```console
$ docker inspect -f "{{ .HostConfig.Links }}" web

[/db:/web/db]
```

You can see that the `web` container is now linked to the `db` container `web/db`. Which allows it to access information about the `db` container.

So what does linking the containers actually do? You've learned that a link allows a source container to provide information about itself to a recipient container. In our example, the recipient, `web`, can access information about the source `db`. To do this, Docker creates a secure tunnel between the containers that doesn't need to expose any ports externally on the container; when we started the `db` container we did not use either the `-P` or `-p` flags. That's a big benefit of linking: we don't need to expose the source container, here the PostgreSQL database, to the network.

Docker exposes connectivity information for the source container to the recipient container in two ways:

* Environment variables,
* Updating the `/etc/hosts` file.

### [Environment variables](#environment-variables)

Docker creates several environment variables when you link containers. Docker automatically creates environment variables in the target container based on the `--link` parameters. It also exposes all environment variables originating from Docker from the source container. These include variables from:

* the `ENV` commands in the source container's Dockerfile
* the `-e`, `--env`, and `--env-file` options on the `docker run` command when the source container is started

These environment variables enable programmatic discovery from within the target container of information related to the source container.

> Warning
>
> It is important to understand that all environment variables originating from Docker within a container are made available to any container that links to it. This could have serious security implications if sensitive data is stored in them.

Docker sets an `<alias>_NAME` environment variable for each target container listed in the `--link` parameter. For example, if a new container called `web` is linked to a database container called `db` via `--link db:webdb`, then Docker creates a `WEBDB_NAME=/web/webdb` variable in the `web` container.

Docker also defines a set of environment variables for each port exposed by the source container. Each variable has a unique prefix in the form `<name>_PORT_<port>_<protocol>`

The components in this prefix are:

* the alias `<name>` specified in the `--link` parameter (for example, `webdb`)
* the `<port>` number exposed
* a `<protocol>` which is either TCP or UDP

Docker uses this prefix format to define three distinct environment variables:

* The `prefix_ADDR` variable contains the IP Address from the URL, for example `WEBDB_PORT_5432_TCP_ADDR=172.17.0.82`.
* The `prefix_PORT` variable contains just the port number from the URL of example `WEBDB_PORT_5432_TCP_PORT=5432`.
* The `prefix_PROTO` variable contains just the protocol from the URL of example `WEBDB_PORT_5432_TCP_PROTO=tcp`.

If the container exposes multiple ports, an environment variable set is defined for each one. This means, for example, if a container exposes 4 ports that Docker creates 12 environment variables, 3 for each port.

Additionally, Docker creates an environment variable called `<alias>_PORT`. This variable contains the URL of the source container's first exposed port. The 'first' port is defined as the exposed port with the lowest number. For example, consider the `WEBDB_PORT=tcp://172.17.0.82:5432` variable. If that port is used for both tcp and udp, then the tcp one is specified.

Finally, Docker also exposes each Docker originated environment variable from the source container as an environment variable in the target. For each variable Docker creates an `<alias>_ENV_<name>` variable in the target container. The variable's value is set to the value Docker used when it started the source container.

Returning back to our database example, you can run the `env` command to list the specified container's environment variables.

```console
$ docker run --rm --name web2 --link db:db training/webapp env

<...>
DB_NAME=/web2/db
DB_PORT=tcp://172.17.0.5:5432
DB_PORT_5432_TCP=tcp://172.17.0.5:5432
DB_PORT_5432_TCP_PROTO=tcp
DB_PORT_5432_TCP_PORT=5432
DB_PORT_5432_TCP_ADDR=172.17.0.5
<...>
```

You can see that Docker has created a series of environment variables with useful information about the source `db` container. Each variable is prefixed with `DB_`, which is populated from the `alias` you specified above. If the `alias` were `db1`, the variables would be prefixed with `DB1_`. You can use these environment variables to configure your applications to connect to the database on the `db` container. The connection is secure and private; only the linked `web` container can communicate with the `db` container.

### [Important notes on Docker environment variables](#important-notes-on-docker-environment-variables)

Unlike host entries in the [`/etc/hosts` file](#updating-the-etchosts-file), IP addresses stored in the environment variables are not automatically updated if the source container is restarted. We recommend using the host entries in `/etc/hosts` to resolve the IP address of linked containers.

These environment variables are only set for the first process in the container. Some daemons, such as `sshd`, scrub them when spawning shells for connection.

### [Updating the `/etc/hosts` file](#updating-the-etchosts-file)

In addition to the environment variables, Docker adds a host entry for the source container to the `/etc/hosts` file. Here's an entry for the `web` container:

```console
$ docker run -t -i --rm --link db:webdb training/webapp /bin/bash

root@aed84ee21bde:/opt/webapp# cat /etc/hosts
172.17.0.7  aed84ee21bde
<...>
172.17.0.5  webdb 6e5cdeb2d300 db
```

You can see two relevant host entries. The first is an entry for the `web` container that uses the Container ID as a host name. The second entry uses the link alias to reference the IP address of the `db` container. In addition to the alias you provide, the linked container's name, if unique from the alias provided to the `--link` parameter, and the linked container's hostname are also added to `/etc/hosts` for the linked container's IP address. You can ping that host via any of these entries:

```console
root@aed84ee21bde:/opt/webapp# apt-get install -yqq inetutils-ping
root@aed84ee21bde:/opt/webapp# ping webdb

PING webdb (172.17.0.5): 48 data bytes
56 bytes from 172.17.0.5: icmp_seq=0 ttl=64 time=0.267 ms
56 bytes from 172.17.0.5: icmp_seq=1 ttl=64 time=0.250 ms
56 bytes from 172.17.0.5: icmp_seq=2 ttl=64 time=0.256 ms
```

> Note
>
> In the example, you had to install `ping` because it was not included in the container initially.

Here, you used the `ping` command to ping the `db` container using its host entry, which resolves to `172.17.0.5`. You can use this host entry to configure an application to make use of your `db` container.

> Note
>
> You can link multiple recipient containers to a single source. For example, you could have multiple (differently named) web containers attached to your `db` container.

If you restart the source container, the `/etc/hosts` files on the linked containers are automatically updated with the source container's new IP address, allowing linked communication to continue.

```console
$ docker restart db
db

$ docker run -t -i --rm --link db:db training/webapp /bin/bash

root@aed84ee21bde:/opt/webapp# cat /etc/hosts
172.17.0.7  aed84ee21bde
<...>
172.17.0.9  db
```

----
url: https://docs.docker.com/admin/organization/setup/orgs/
----

# Create your organization

***

Table of contents

***

Subscription: Team Business

For: Administrators

There are multiple ways to create an organization. You can either:

* Create a new organization using the **Create Organization** option in the Admin Console or Docker Hub
* Convert an existing user account to an organization

These procedures walk you through creating an organization from the Admin Console.

## [Prerequisites](#prerequisites)

* Before you create an organization, you need a [Docker ID](https://docs.docker.com/accounts/create-account/).
* For prerequisites and detailed instructions on converting an existing user account to an organization, see [Convert an account into an organization](https://docs.docker.com/admin/organization/setup/convert-account/).

> Tip
>
> Need a different plan for your team's needs? Review different [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs\&refAction=DocsAdminOrgs) to choose a subscription for your organization.

## [Create an organization](#create-an-organization)

1. Sign in to [Docker Home](https://app.docker.com/) and navigate to the bottom of the organization list. Select **Create new organization**.

2. Choose a subscription for your organization, a billing cycle, and specify how many seats you need. See [Docker Pricing](https://www.docker.com/pricing?ref=Docs\&refAction=DocsAdminOrgs) for details on the features offered in the Team and Business subscription.

3. Select **Continue to profile**, then **Create an organization** to create a new organization.

4. Enter an **Organization namespace**. This is the official, unique name for your organization in Docker Hub.

   * It's not possible to change the name of the organization after you've created it.
   * Your Docker ID and organization can't share the same name.
   * If you want to use your Docker ID as the organization name, then you must first [convert your account into an organization](https://docs.docker.com/admin/organization/setup/convert-account/).

5. Enter your **Company name**. This is the full name of your company.

   * Docker displays the company name on your organization page and in the details of any public images you publish.
   * You can update the company name anytime by navigating to your organization's **Settings** page.

6. Select **Continue to billing** to continue, then enter your organization's billing information. Select **Continue to payment** to continue to the billing portal.

7. Provide your payment details and select **Purchase**.

You've now created an organization.

## [View an organization](#view-an-organization)

To view an organization in the Admin Console:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization.
2. From the left-hand navigation menu, select **Admin Console**.

The Admin Console contains many options that let you to configure your organization.

## [Merge organizations](#merge-organizations)

> Warning
>
> If you are merging organizations, it is recommended to do so at the *end* of your billing cycle. When you merge an organization and downgrade another, you will lose seats on your downgraded organization. Docker does not offer refunds for downgrades.

If you have multiple organizations that you want to merge into one, complete the following steps:

1. Based on the number of seats from the secondary organization, [purchase additional seats](https://docs.docker.com/subscription/manage-seats/) for the primary organization account that you want to keep.
2. Manually add users to the primary organization and remove existing users from the secondary organization.
3. Manually move over your data, including all repositories.
4. Once you're done moving all of your users and data, [downgrade](https://docs.docker.com/subscription/change/) the secondary account to a free subscription. Note that Docker does not offer refunds for downgrading organizations mid-billing cycle.

If your organization has a Docker Business subscription with a purchase order, contact Support or your Account Manager at Docker.

## [More resources](#more-resources)

* [Video: Docker Hub Organizations](https://www.youtube.com/watch?v=WKlT1O-4Du8)

----
url: https://docs.docker.com/build-cloud/
----

# Docker Build Cloud

***

Table of contents

***

Subscription: Pro Team Business

Docker Build Cloud is a service that lets you build your container images faster, both locally and in CI. Builds run on cloud infrastructure optimally dimensioned for your workloads, no configuration required. The service uses a remote build cache, ensuring fast builds anywhere and for all team members.

## [How Docker Build Cloud works](#how-docker-build-cloud-works)

Using Docker Build Cloud is no different from running a regular build. You invoke a build the same way you normally would, using `docker buildx build`. The difference is in where and how that build gets executed.

By default when you invoke a build command, the build runs on a local instance of BuildKit, bundled with the Docker daemon. With Docker Build Cloud, you send the build request to a BuildKit instance running remotely, in the cloud. All data is encrypted in transit.

The remote builder executes the build steps, and sends the resulting build output to the destination that you specify. For example, back to your local Docker Engine image store, or to an image registry.

Docker Build Cloud provides several benefits over local builds:

* Improved build speed
* Shared build cache
* Native multi-platform builds

And the best part: you don't need to worry about managing builders or infrastructure. Just connect to your builders, and start building. Each cloud builder provisioned to an organization is completely isolated to a single Amazon EC2 instance, with a dedicated EBS volume for build cache, and encryption in transit. That means there are no shared processes or data between cloud builders.

> Note
>
> Docker Build Cloud is only available in the US East region.

## [Get Docker Build Cloud](#get-docker-build-cloud)

To get started with Docker Build Cloud, [create a Docker account](/accounts/create-account/). There are two options to get access to Docker Build Cloud:

* Users with a free Personal account can opt-in to a 7-day free trial, with the option to subscribe for access. To start your free trial, sign in to [Docker Build Cloud Dashboard](https://app.docker.com/build/) and follow the on-screen instructions.
* All users with a paid Docker subscription have access to Docker Build Cloud included with their Docker suite of products. See [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs\&refAction=DocsBuildCloud) for more information.

Once you've signed up and created a builder, continue by [setting up the builder in your local environment](https://docs.docker.com/build-cloud/setup/).

For information about roles and permissions related to Docker Build Cloud, see [Roles and Permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/#docker-build-cloud-permissions).

----
url: https://docs.docker.com/guides/testcontainers-dotnet-aspnet-core/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

Run the tests from the solution root:

```console
$ dotnet test ./RazorPagesProject.sln
```

The first run may take longer because Docker needs to pull the Microsoft SQL Server image. On subsequent runs, the image is cached locally.

You should see xUnit discover and run the tests, including the `MsSqlTests.IndexPageTests` class. Testcontainers starts a SQL Server container, the tests execute against it, and the container is stopped and removed automatically after the tests finish.

## [Summary](#summary)

By replacing SQLite with a Testcontainers-managed Microsoft SQL Server instance, the integration tests run against the same type of database used in production. This approach catches database-specific issues early, such as differences in SQL dialect, transaction behavior, or data type handling between SQLite and SQL Server.

The `MsSqlTests` class uses `IAsyncLifetime` to manage the container lifecycle, and a nested `CustomWebApplicationFactory` wires the container's connection string into the application's service configuration. You can apply this same pattern to any database or service that Testcontainers supports.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testcontainers for .NET documentation](https://dotnet.testcontainers.org/)
* [Testcontainers for .NET modules](https://dotnet.testcontainers.org/modules/)
* [Microsoft SQL Server module](https://www.nuget.org/packages/Testcontainers.MsSql)
* [Integration tests in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests)

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/export/
----

# docker mcp profile export

***

| Description | Export profile to file                                 |
| ----------- | ------------------------------------------------------ |
| Usage       | `docker mcp profile export <profile-id> <output-file>` |

## [Description](#description)

Export profile to file

----
url: https://docs.docker.com/docker-hub/repos/manage/trusted-content/insights-analytics/
----

# Insights and analytics

***

Table of contents

***

Insights and analytics provides usage analytics for [Docker Verified Publisher (DVP)](https://www.docker.com/partners/programs/) and [Docker-Sponsored Open Source (DSOS)](https://www.docker.com/community/open-source/application/#) images on Docker Hub. This includes self-serve access to image and extension usage metrics for a desired time span. You can see the number of image pulls by tag or by digest, geolocation, cloud provider, client, and more.

> Note
>
> The Legacy DVP program applies to existing customers who have not yet renewed to DVP Core. The DVP Legacy program is deprecated and will be retired. Contact your Docker sales representative or [Docker](https://www.docker.com/partners/programs/) for more information.

All members of an organization have access to the analytics data. Members can access analytics data in the [Docker Hub](https://hub.docker.com/) web interface.

## [Available reports](#available-reports)

The following reports may be available for download as CSV files:

* [Summary](#summary-report)
* [Trends](#trends-report)
* [Technographic](#technographic-report)
* [Technographic companies](#technographic-companies-report)
* [Tracked companies](#tracked-companies-report)

The reports available for download may vary based on your organization's subscription. Contact your Docker sales representative or [Docker](https://www.docker.com/partners/programs/) for more information.

## [Configure DVP analytics settings](#configure-dvp-analytics-settings)

Organization owners and editors can configure DVP analytics settings through the Admin Console to control tracked companies and benchmark report allocations for your verified publisher namespaces.

1. Sign in to [Docker Home](https://app.docker.com) and select your organization.

2. Select **Admin Console** > **Verified Publisher**.

3. Configure the settings:

   * **Tracked companies**: Set the number of companies to track for reporting purposes. This setting determines how many company domains appear in your [Tracked companies report](#tracked-companies-report). You can only set this number up to the maximum included in your DVP subscription.
   * **Benchmark report allocations**: If your organization has benchmark reports enabled, enter the number of companies to include in the benchmark report for each namespace listed.

4. Select **Save** to apply your changes.

### [Summary report](#summary-report)

The summary report provides high-level usage metrics aggregated across all your Docker Hub content, organized by namespace and repository. This report gives you a comprehensive overview of your image portfolio performance, helping you understand which repositories, tags, and specific image versions are most popular with your users.

You can use this report to answer questions like:

* Which of my repositories are getting the most usage?
* How do different image tags compare in terms of adoption?
* What's the ratio of actual downloads versus version checks across my portfolio?
* Which specific image digests are being pulled most frequently?
* How has overall usage changed over time for my entire image collection?

To access the report:

1. Sign in to [Docker Hub](https://hub.docker.com/).

2. Select **My Hub** in the top navigation.

3. Select your organization in the left navigation.

4. Select **Analytics** > **Overview** in the left navigation.

5. Download the report by doing one of the following:

   * Select **Download Weekly Summary**.
   * Select the **Download Monthly Summary**.
   * Expand the **Summary reports for the year** drop-down and then select **Download report** for the desired week or month.

The summary report is a CSV file that contains the following data points:

| Field              | Description                                                                                                                                                           |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATE_GRANULARITY` | Weekly or monthly granularity of the data. Indicates whether the data is aggregated by week or month.                                                                 |
| `DATE_REFERENCE`   | The start date of the week or month in YYYY-MM-DD format (e.g., `2025-09-29` for the week starting September 29, 2025).                                               |
| `PUBLISHER_NAME`   | The name of the Docker organization that owns the repository (e.g., `demonstrationorg`).                                                                              |
| `LEVEL`            | The aggregation level of the data - either `repository` (summary for entire repository), `tag` (summary for specific tag), or `digest` (summary for specific digest). |
| `REFERENCE`        | The specific reference being summarized - the repository name, tag name, or digest hash depending on the level.                                                       |
| `DATA_DOWNLOADS`   | The number of actual image downloads.                                                                                                                                 |
| `VERSION_CHECKS`   | The number of version checks performed (HEAD requests to check for updates without downloading the full image).                                                       |
| `EVENT_COUNT`      | The total number of events, calculated as the sum of data downloads and version checks.                                                                               |

### [Trends report](#trends-report)

The trends report helps you understand how adoption of your container images evolves over time. It provides visibility into pull activity across repositories and tags, enabling you to identify adoption patterns, version migration trends, and usage environments (e.g., local development, CI/CD, production).

You can use this report to answer questions like:

* Which versions are gaining or losing traction?
* Is a new release being adopted?
* How does usage vary across cloud providers?

To access the report:

1. Sign in to [Docker Hub](https://hub.docker.com/).
2. Select **My Hub** in the top navigation.
3. Select your organization in the left navigation.
4. Select **Analytics** > **Trends** in the left navigation.
5. Select **DATA BY WEEK** or **DATA BY MONTH** to choose the data granularity.
6. Select **Download report** for the desired week or month.

The trends report is a CSV file that contains the following data points:

| Field                          | Description                                                                                                             |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `DATE_GRANULARITY`             | Weekly or monthly granularity of the data.                                                                              |
| `DATE_REFERENCE`               | The start date of the week or month.                                                                                    |
| `PUBLISHER_NAME`               | The name of the organization that owns the repository.                                                                  |
| `IMAGE_REPOSITORY`             | The full name of the image repository (e.g., `demonstrationorg/scout-demo`).                                            |
| `NAMESPACE`                    | The Docker organization or namespace that owns the repository.                                                          |
| `IP_COUNTRY`                   | The country code (ISO 3166-1 alpha-2) where the pull request originated from (e.g., `US`, `CA`).                        |
| `CLOUD_SERVICE_PROVIDER`       | The cloud service provider used for the pull request (e.g., `gcp`, `aws`, `azure`) or `no csp` for non-cloud providers. |
| `USER_AGENT`                   | The client application or tool used to pull the image (e.g., `docker`, `docker-scout`, `node-fetch`, `regclient`).      |
| `TAG`                          | The specific image tag that was pulled, or `\\N` if no specific tag was used.                                           |
| `DATA_DOWNLOADS`               | The number of data downloads for the specified criteria.                                                                |
| `VERSION_CHECKS`               | The number of version checks (HEAD requests) performed without downloading the full image.                              |
| `PULLS`                        | The total number of pull requests (data downloads + version checks).                                                    |
| `UNIQUE_AUTHENTICATED_USERS`   | The number of unique authenticated users who performed pulls.                                                           |
| `UNIQUE_UNAUTHENTICATED_USERS` | The number of unique unauthenticated users who performed pulls.                                                         |

### [Technographic report](#technographic-report)

The technographic report provides insights into how your Docker Verified Publisher (DVP) images are used alongside other container images in real-world technology stacks. This report helps you understand the technical ecosystem where your images operate and identify co-usage patterns with other images.

You can use this report to answer questions like:

* Which other images are commonly used together with your images?
* What percentage of your user base also uses specific complementary technologies?
* How many companies in your ecosystem use both your image and other popular images?
* What technology stacks are most popular among your users?

To access the report:

1. Sign in to [Docker Hub](https://hub.docker.com/).
2. Select **My Hub** in the top navigation.
3. Select your organization in the left navigation.
4. Select **Analytics** > **Technographic** in the left navigation.
5. Select **DATA BY WEEK** or **DATA BY MONTH** to choose the data granularity.
6. Select **Download report** for the desired week or month.

The technographic report is a CSV file that contains the following data points:

| Field              | Description                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| `DATE_GRANULARITY` | Weekly or monthly granularity of the data.                                                                  |
| `DATE_REFERENCE`   | The start date of the week or month in YYYY-MM-DD format.                                                   |
| `PUBLISHER_ID`     | The unique identifier for the publisher organization.                                                       |
| `PUBLISHER_NAME`   | The name of the organization that owns the DVP repository.                                                  |
| `DVPP_IMAGE`       | Your Docker Verified Publisher image repository name.                                                       |
| `PAIRED_IMAGE`     | The other image repository that is commonly used together with your DVP image.                              |
| `USERS`            | The number of unique users who pulled both your DVP image and the paired image within the time period.      |
| `TOTAL_PULLERS`    | The total number of unique users who pulled your DVP image during the time period.                          |
| `PCT_USERS`        | The percentage of your image's users who also use the paired image (users/total\_pullers).                  |
| `DOMAINS`          | The number of unique company domains that pulled both your DVP image and the paired image.                  |
| `TOTAL_DOMAINS`    | The total number of unique company domains that pulled your DVP image.                                      |
| `PCT_DOMAINS`      | The percentage of company domains using your image that also use the paired image (domains/total\_domains). |

> Note
>
> To protect user privacy and ensure statistical significance, the technographic report only includes image pairings that have at least 10 unique users. Personal, disposable, and university email domains are excluded from the company domain analysis.

### [Technographic companies report](#technographic-companies-report)

The technographic companies report provides a detailed view of which specific companies (identified by their domains) are using your Docker Verified Publisher (DVP) images together with other container images. This report gives you visibility into the actual organizations adopting your technology stack combinations, enabling targeted business development and partnership opportunities.

You can use this report to answer questions like:

* Which companies are using my image alongside specific complementary technologies?
* What technology stacks are adopted by enterprise customers in my target market?
* Which organizations might be good candidates for partnership discussions?
* How can I identify potential customers who are already using related technologies?

To access the report:

1. Sign in to [Docker Hub](https://hub.docker.com/).
2. Select **My Hub** in the top navigation.
3. Select your organization in the left navigation.
4. Select **Analytics** > **Technographic** in the left navigation.
5. Select **DATA BY WEEK** or **DATA BY MONTH** to choose the data granularity.
6. Select **Download report** for the desired week or month.

The technographic companies report is a CSV file that contains the following data points:

| Field              | Description                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| `DATE_GRANULARITY` | Weekly or monthly granularity of the data.                                                     |
| `DATE_REFERENCE`   | The start date of the week or month in YYYY-MM-DD format.                                      |
| `PUBLISHER_NAME`   | The name of the organization that owns the DVP repository.                                     |
| `DOMAIN`           | The company domain that pulled both your DVP image and the paired image (e.g., `example.com`). |
| `DVPP_IMAGE`       | Your Docker Verified Publisher image repository name.                                          |
| `PAIRED_IMAGE`     | The other image repository that was used together with your DVP image by this company.         |

Each row represents a unique combination of a company domain, your DVP image, and another image that were used together during the specified time period.

> Note
>
> To protect privacy and ensure data quality, this report excludes personal email domains, disposable email services, and university domains. Only business and organizational domains are included in the analysis.

### [Tracked companies report](#tracked-companies-report)

The tracked companies report provides detailed insights into how specific companies are using your Docker Verified Publisher (DVP) images. This report helps you understand usage patterns, deployment environments, and adoption trends across your customer base and potential prospects.

You can use this report to answer questions like:

* How are specific companies using my images across different environments?
* What deployment patterns do I see across local development, CI/CD, and production?
* Which companies are heavy users of my images?
* How does usage vary by geography and cloud providers for tracked companies?

To access the report:

1. Sign in to [Docker Hub](https://hub.docker.com/).
2. Select **My Hub** in the top navigation.
3. Select your organization in the left navigation.
4. Select **Analytics** > **Tracked Companies** in the left navigation.
5. Select **DATA BY WEEK** or **DATA BY MONTH** to choose the data granularity.
6. Select **Download report** for the desired week or month.

The tracked companies report is a CSV file that contains the following data points:

| Field                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATE_GRANULARITY`           | Weekly or monthly granularity of the data.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `DATE_REFERENCE`             | The start date of the week or month in YYYY-MM-DD format.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `PUBLISHER_NAME`             | The name of the organization that owns the DVP repository.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `DOMAIN`                     | The company domain (e.g., `docker.com`) associated with the image pulls.                                                                                                                                                                                                                                                                                                                                                                                                |
| `IP_COUNTRY`                 | The country code (ISO 3166-1 alpha-2) where the pull request originated from.                                                                                                                                                                                                                                                                                                                                                                                           |
| `CLOUD_SERVICE_PROVIDER`     | The cloud service provider used for the pull request or `no csp` for non-cloud providers.                                                                                                                                                                                                                                                                                                                                                                               |
| `USER_AGENT`                 | The client application or tool used to pull the image.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `INFERRED_USE_CASE`          | The inferred deployment environment based on user agent and cloud provider analysis. Values include: • `Local Dev`: Local development environment (e.g., Docker Desktop, direct `docker` commands) • `CI/CD`: Continuous integration/deployment pipelines (e.g., containerd, build tools, registry mirroring) • `Prod`: Production environments (e.g., Kubernetes, container orchestration platforms) • `Unknown`: Unable to determine the use case from available data |
| `IMAGE_REPOSITORY`           | The specific DVP image repository that was pulled.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `DATA_DOWNLOADS`             | The number of actual image layer downloads for this combination.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `VERSION_CHECKS`             | The number of version checks (HEAD requests) performed without downloading the full image.                                                                                                                                                                                                                                                                                                                                                                              |
| `PULLS`                      | The total number of pull requests (data downloads + version checks).                                                                                                                                                                                                                                                                                                                                                                                                    |
| `UNIQUE_AUTHENTICATED_USERS` | The number of unique authenticated users from this domain who performed pulls.                                                                                                                                                                                                                                                                                                                                                                                          |

> Note
>
> Use case inference is determined by analyzing user agent patterns and cloud service provider usage. Local development tools used on cloud infrastructure are reclassified as CI/CD, and CI/CD tools used on cloud infrastructure are reclassified as production to better reflect actual deployment patterns.

> Important
>
> The Legacy DVP program applies to existing customers who have not yet renewed to DVP Core. The DVP Legacy program is deprecated and will be retired. Contact your Docker sales representative or [Docker](https://www.docker.com/partners/programs/) for more information.

## [View the image's analytics data](#view-the-images-analytics-data)

You can find analytics data for your repositories on the **Insights and analytics** dashboard at the following URL: `https://hub.docker.com/orgs/{namespace}/insights/images`. The dashboard contains a visualization of the usage data and a table where you can download the data as CSV files.

To view data in the chart:

* Select the data granularity: weekly or monthly
* Select the time interval: 3, 6, or 12 months
* Select one or more repositories in the list

> Tip
>
> Hovering your cursor over the chart displays a tooltip, showing precise data for points in time.

### [Share analytics data](#share-analytics-data)

You can share the visualization with others using the **Share** icon at the top of the chart. This is a convenient way to share statistics with others in your organization.

Selecting the icon generates a link that's copied to your clipboard. The link preserves the display selections you made. When someone follows the link, the **Insights and analytics** page opens and displays the chart with the same configuration as you had set up when creating the link.

## [Extension analytics data](#extension-analytics-data)

If you have published Docker Extensions in the Extension marketplace, you can also get analytics about your extension usage, available as CSV files. You can download extension CSV reports from the **Insights and analytics** dashboard at the following URL: `https://hub.docker.com/orgs/{namespace}/insights/extensions`. If your Docker namespace contains extensions known in the marketplace, you will see an **Extensions** tab listing CSV files for your extension(s).

## [Exporting analytics data](#exporting-analytics-data)

You can export the analytics data either from the web dashboard, or using the [DVP Data API](https://docs.docker.com/reference/api/dvp/latest/). All members of an organization have access to the analytics data.

The data is available as a downloadable CSV file, in a weekly (Monday through Sunday) or monthly format. Monthly data is available from the first day of the following calendar month. You can import this data into your own systems, or you can analyze it manually as a spreadsheet.

### [Export data](#export-data)

Export usage data for your organization's images using the Docker Hub website by following these steps:

1. Sign in to [Docker Hub](https://hub.docker.com/) and select **My Hub**.

2. Choose your organization and select **Analytics**.

3. Set the time span for which you want to export analytics data.

   The downloadable CSV files for summary and raw data appear on the right-hand side.

### [Export data using the API](#export-data-using-the-api)

The HTTP API endpoints are available at: `https://hub.docker.com/api/publisher/analytics/v1`. Learn how to export data using the API in the [DVP Data API documentation](https://docs.docker.com/reference/api/dvp/latest/).

## [Data points](#data-points)

Export data in either raw or summary format. Each format contains different data points and with different structure.

The following sections describe the available data points for each format. The **Date added** column shows when the field was first introduced.

### [Image pulls raw data](#image-pulls-raw-data)

The raw data format contains the following data points. Each row in the CSV file represents an image pull.

| Data point                    | Description                                                                                                                                         | Date added        |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| Action                        | Request type, see [Action classification rules](#image-pulls-action-classification-rules). One of `pull_by_tag`, `pull_by_digest`, `version_check`. | January 1, 2022   |
| Action day                    | The date part of the timestamp: `YYYY-MM-DD`.                                                                                                       | January 1, 2022   |
| Country                       | Request origin country.                                                                                                                             | January 1, 2022   |
| Digest                        | Image digest.                                                                                                                                       | January 1, 2022   |
| HTTP method                   | HTTP method used in the request, see [registry API documentation](/registry/spec/api/) for details.                                                 | January 1, 2022   |
| Host                          | The cloud service provider used in an event.                                                                                                        | January 1, 2022   |
| Namespace                     | Docker [organization](/admin/organization/setup/orgs/) (image namespace).                                                                           | January 1, 2022   |
| Reference                     | Image digest or tag used in the request.                                                                                                            | January 1, 2022   |
| Repository                    | Docker [repository](/docker-hub/repos/) (image name).                                                                                               | January 1, 2022   |
| Tag (included when available) | Tag name that's only available if the request referred to a tag.                                                                                    | January 1, 2022   |
| Timestamp                     | Date and time of the request: `YYYY-MM-DD 00:00:00`.                                                                                                | January 1, 2022   |
| Type                          | The industry from which the event originates. One of `business`, `isp`, `hosting`, `education`, `null`.                                             | January 1, 2022   |
| User agent tool               | The application a user used to pull an image (for example, `docker` or `containerd`).                                                               | January 1, 2022   |
| User agent version            | The version of the application used to pull an image.                                                                                               | January 1, 2022   |
| Domain                        | Request origin domain, see [Privacy](#privacy).                                                                                                     | October 11, 2022  |
| Owner                         | The name of the organization that owns the repository.                                                                                              | December 19, 2022 |

### [Image pulls summary data](#image-pulls-summary-data)

There are two levels of summary data available:

* Repository-level, a summary of every namespace and repository
* Tag- or digest-level, a summary of every namespace, repository, and reference (tag or digest)

The summary data formats contain the following data points for the selected time span:

| Data point        | Description                                             | Date added        |
| ----------------- | ------------------------------------------------------- | ----------------- |
| Unique IP address | Number of unique IP addresses, see [Privacy](#privacy). | January 1, 2022   |
| Pull by tag       | GET request, by digest or by tag.                       | January 1, 2022   |
| Pull by digest    | GET or HEAD request by digest, or HEAD by digest.       | January 1, 2022   |
| Version check     | HEAD by tag, not followed by a GET                      | January 1, 2022   |
| Owner             | The name of the organization that owns the repository.  | December 19, 2022 |

### [Image pulls action classification rules](#image-pulls-action-classification-rules)

An action represents the multiple request events associated with a `docker pull`. Pulls are grouped by category to make the data more meaningful for understanding user behavior and intent. The categories are:

* Version check
* Pull by tag
* Pull by digest

Automated systems frequently check for new versions of your images. Being able to distinguish between "version checks" in CI versus actual image pulls by a user grants you more insight into your users' behavior.

The following table describes the rules applied for determining intent behind pulls. To provide feedback or ask questions about these rules, [fill out the Google Form](https://forms.gle/nb7beTUQz9wzXy1b6).

| Starting event | Reference | Followed by                                                     | Resulting action | Use case(s)                                                                                                    | Notes                                                                                                                                                                                                                                                                                 |
| -------------- | --------- | --------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HEAD           | tag       | N/A                                                             | Version check    | User already has all layers existing on local machine                                                          | This is similar to the use case of a pull by tag when the user already has all the image layers existing locally, however, it differentiates the user intent and classifies accordingly.                                                                                              |
| GET            | tag       | N/A                                                             | Pull by tag      | User already has all layers existing on local machine and/or the image is single-arch                          |                                                                                                                                                                                                                                                                                       |
| GET            | tag       | Get by different digest                                         | Pull by tag      | Image is multi-arch                                                                                            | Second GET by digest must be different from the first.                                                                                                                                                                                                                                |
| HEAD           | tag       | GET by same digest                                              | Pull by tag      | Image is multi-arch but some or all image layers already exist on the local machine                            | The HEAD by tag sends the most current digest, the following GET must be by that same digest. There may occur an additional GET, if the image is multi-arch (see the next row in this table). If the user doesn't want the most recent digest, then the user performs HEAD by digest. |
| HEAD           | tag       | GET by the same digest, then a second GET by a different digest | Pull by tag      | Image is multi-arch                                                                                            | The HEAD by tag sends the most recent digest, the following GET must be by that same digest. Since the image is multi-arch, there is a second GET by a different digest. If the user doesn't want the most recent digest, then the user performs HEAD by digest.                      |
| HEAD           | tag       | GET by same digest, then a second GET by different digest       | Pull by tag      | Image is multi-arch                                                                                            | The HEAD by tag sends the most current digest, the following GET must be by that same digest. Since the image is multi-arch, there is a second GET by a different digest. If the user doesn't want the most recent digest, then the user performs HEAD by digest.                     |
| GET            | digest    | N/A                                                             | Pull by digest   | User already has all layers existing on local machine and/or the image is single-arch                          |                                                                                                                                                                                                                                                                                       |
| HEAD           | digest    | N/A                                                             | Pull by digest   | User already has all layers existing on their local machine                                                    |                                                                                                                                                                                                                                                                                       |
| GET            | digest    | GET by different digest                                         | Pull by digest   | Image is multi-arch                                                                                            | The second GET by digest must be different from the first.                                                                                                                                                                                                                            |
| HEAD           | digest    | GET by same digest                                              | Pull by digest   | Image is single-arch and/or image is multi-arch but some part of the image already exists on the local machine |                                                                                                                                                                                                                                                                                       |
| HEAD           | digest    | GET by same digest, then a second GET by different digest       | Pull by Digest   | Image is multi-arch                                                                                            |                                                                                                                                                                                                                                                                                       |

### [Extension Summary data](#extension-summary-data)

There are two levels of extension summary data available:

* Core summary, with basic extension usage information: number of extension installs, uninstalls, and total install all times

The core-summary-data file contains the following data points for the selected time span:

| Data point      | Description                                      | Date added  |
| --------------- | ------------------------------------------------ | ----------- |
| Installs        | Number of installs for the extension             | Feb 1, 2024 |
| TotalInstalls   | Number of installs for the extension all times   | Feb 1, 2024 |
| Uninstalls      | Number of uninstalls for the extension           | Feb 1, 2024 |
| TotalUninstalls | Number of uninstalls for the extension all times | Feb 1, 2024 |
| Updates         | Number of updates for the extension              | Feb 1, 2024 |

* Premium summary, with advanced extension usage information: installs, uninstalls by unique users, extension opening by unique users.

The core-summary-data file contains the following data points for the selected time span:

| Data point       | Description                                       | Date added  |
| ---------------- | ------------------------------------------------- | ----------- |
| Installs         | Number of installs for the extension              | Feb 1, 2024 |
| UniqueInstalls   | Number of unique users installing the extension   | Feb 1, 2024 |
| Uninstalls       | Number of uninstalls for the extension            | Feb 1, 2024 |
| UniqueUninstalls | Number of unique users uninstalling the extension | Feb 1, 2024 |
| Usage            | Number of openings of the extension tab           | Feb 1, 2024 |
| UniqueUsers      | Number of unique users openings the extension tab | Feb 1, 2024 |

## [Changes in data over time](#changes-in-data-over-time)

The insights and analytics service is continuously improved to increase the value it brings to publishers. Some changes might include adding new data points, or improving existing data to make it more useful.

Changes in the dataset, such as added or removed fields, generally only apply from the date of when the field was first introduced, and going forward.

Refer to the tables in the [Data points](#data-points) section to see from which date a given data point is available.

## [Privacy](#privacy)

This section contains information about privacy-protecting measures that ensures consumers of content on Docker Hub remain completely anonymous.

> Important
>
> Docker never shares any Personally Identifiable Information (PII) as part of analytics data.

The image pulls summary dataset includes unique IP address count. This data point only includes the number of distinct unique IP addresses that request an image. Individual IP addresses are never shared.

The image pulls raw dataset includes user IP domains as a data point. This is the domain name associated with the IP address used to pull an image. If the IP type is `business`, the domain represents the company or organization associated with that IP address (for example, `docker.com`). For any other IP type that's not `business`, the domain represents the internet service provider or hosting provider used to make the request. On average, only about 30% of all pulls classify as the `business` IP type (this varies between publishers and images).

----
url: https://docs.docker.com/reference/cli/docker/service/rollback/
----

# docker service rollback

***

| Description | Revert changes to a service's configuration |
| ----------- | ------------------------------------------- |
| Usage       | `docker service rollback [OPTIONS] SERVICE` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Roll back a specified service to its previous version from the swarm.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option         | Default | Description                                                               |
| -------------- | ------- | ------------------------------------------------------------------------- |
| `-d, --detach` |         | API 1.29+ Exit immediately instead of waiting for the service to converge |
| `-q, --quiet`  |         | Suppress progress output                                                  |

## [Examples](#examples)

### [Roll back to the previous version of a service](#roll-back-to-the-previous-version-of-a-service)

Use the `docker service rollback` command to roll back to the previous version of a service. After executing this command, the service is reverted to the configuration that was in place before the most recent `docker service update` command.

The following example creates a service with a single replica, updates the service to use three replicas, and then rolls back the service to the previous version, having one replica.

Create a service with a single replica:

```console
$ docker service create --name my-service -p 8080:80 nginx:alpine
```

Confirm that the service is running with a single replica:

```console
$ docker service ls

ID                  NAME                MODE                REPLICAS            IMAGE               PORTS
xbw728mf6q0d        my-service          replicated          1/1                 nginx:alpine        *:8080->80/tcp
```

Update the service to use three replicas:

```console
$ docker service update --replicas=3 my-service

$ docker service ls

ID                  NAME                MODE                REPLICAS            IMAGE               PORTS
xbw728mf6q0d        my-service          replicated          3/3                 nginx:alpine        *:8080->80/tcp
```

Now roll back the service to its previous version, and confirm it is running a single replica again:

```console
$ docker service rollback my-service

$ docker service ls

ID                  NAME                MODE                REPLICAS            IMAGE               PORTS
xbw728mf6q0d        my-service          replicated          1/1                 nginx:alpine        *:8080->80/tcp
```

----
url: https://docs.docker.com/guides/testcontainers-java-replace-h2/
----

# Replace H2 with a real database for testing

Table of contents

***

Replace your H2 in-memory test database with a real PostgreSQL instance using the Testcontainers special JDBC URL — a one-line change.

**Time to complete** 15 minutes

In this guide, you will learn how to:

* Understand the drawbacks of using H2 in-memory databases for testing
* Replace H2 with a real PostgreSQL database using the Testcontainers special JDBC URL
* Use the Testcontainers JUnit 5 extension for more control over the container
* Test both Spring Data JPA and JdbcTemplate-based repositories

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [The H2 problem](https://docs.docker.com/guides/testcontainers-java-replace-h2/problem-with-h2/)

   Understand why using H2 in-memory databases for testing gives false confidence.

2. [JDBC URL approach](https://docs.docker.com/guides/testcontainers-java-replace-h2/jdbc-url-approach/)

   Use the Testcontainers special JDBC URL to swap H2 for a real PostgreSQL database.

3. [JUnit 5 extension](https://docs.docker.com/guides/testcontainers-java-replace-h2/junit-extension-approach/)

   Use the Testcontainers JUnit 5 extension for more control over the PostgreSQL container.

----
url: https://docs.docker.com/engine/logging/drivers/journald/
----

# Journald logging driver

***

Table of contents

***

The `journald` logging driver sends container logs to the [`systemd` journal](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html). Log entries can be retrieved using the `journalctl` command, through use of the `journal` API, or using the `docker logs` command.

In addition to the text of the log message itself, the `journald` log driver stores the following metadata in the journal with each message:

| Field                                | Description                                                                                                                                           |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTAINER_ID`                       | The container ID truncated to 12 characters.                                                                                                          |
| `CONTAINER_ID_FULL`                  | The full 64-character container ID.                                                                                                                   |
| `CONTAINER_NAME`                     | The container name at the time it was started. If you use `docker rename` to rename a container, the new name isn't reflected in the journal entries. |
| `CONTAINER_TAG`, `SYSLOG_IDENTIFIER` | The container tag ([log tag option documentation](https://docs.docker.com/engine/logging/log_tags/)).                                                 |
| `CONTAINER_PARTIAL_MESSAGE`          | A field that flags log integrity. Improve logging of long log lines.                                                                                  |
| `IMAGE_NAME`                         | The name of the container image.                                                                                                                      |

## [Usage](#usage)

To use the `journald` driver as the default logging driver, set the `log-driver` and `log-opts` keys to appropriate values in the `daemon.json` file. For more about configuring Docker using `daemon.json`, see [daemon.json](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file).

> Note
>
> If you're using Docker Desktop, edit the daemon configuration through the Docker Desktop Dashboard. Open **Settings** and select **Docker Engine**. For details, see [Docker Engine settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine).

The following example sets the log driver to `journald`:

```json
{
  "log-driver": "journald"
}
```

Restart Docker for the changes to take effect.

To configure the logging driver for a specific container, use the `--log-driver` flag on the `docker run` command.

```console
$ docker run --log-driver=journald ...
```

## [Options](#options)

Use the `--log-opt NAME=VALUE` flag to specify additional `journald` logging driver options.

| Option         | Required | Description                                                                                                                                                                                                        |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tag`          | optional | Specify template to set `CONTAINER_TAG` and `SYSLOG_IDENTIFIER` value in journald logs. Refer to [log tag option documentation](https://docs.docker.com/engine/logging/log_tags/) to customize the log tag format. |
| `labels`       | optional | Comma-separated list of keys of labels, which should be included in message, if these labels are specified for the container.                                                                                      |
| `labels-regex` | optional | Similar to and compatible with labels. A regular expression to match logging-related labels. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                                |
| `env`          | optional | Comma-separated list of keys of environment variables, which should be included in message, if these variables are specified for the container.                                                                    |
| `env-regex`    | optional | Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                  |

If a collision occurs between `label` and `env` options, the value of the `env` takes precedence. Each option adds additional fields to the attributes of a logging message.

The following is an example of the logging options required to log to journald.

```console
$ docker run \
    --log-driver=journald \
    --log-opt labels=location \
    --log-opt env=TEST \
    --env "TEST=false" \
    --label location=west \
    your/application
```

This configuration also directs the driver to include in the payload the label location, and the environment variable `TEST`. If the `--env "TEST=false"` or `--label location=west` arguments were omitted, the corresponding key would not be set in the journald log.

## [Note regarding container names](#note-regarding-container-names)

The value logged in the `CONTAINER_NAME` field is the name of the container that was set at startup. If you use `docker rename` to rename a container, the new name isn't reflected in the journal entries. Journal entries continue to use the original name.

## [Retrieve log messages with `journalctl`](#retrieve-log-messages-with-journalctl)

Use the `journalctl` command to retrieve log messages. You can apply filter expressions to limit the retrieved messages to those associated with a specific container:

```console
$ sudo journalctl CONTAINER_NAME=webserver
```

You can use additional filters to further limit the messages retrieved. The `-b` flag only retrieves messages generated since the last system boot:

```console
$ sudo journalctl -b CONTAINER_NAME=webserver
```

The `-o` flag specifies the format for the retrieved log messages. Use `-o json` to return the log messages in JSON format.

```console
$ sudo journalctl -o json CONTAINER_NAME=webserver
```

### [View logs for a container with a TTY enabled](#view-logs-for-a-container-with-a-tty-enabled)

If TTY is enabled on a container you may see `[10B blob data]` in the output when retrieving log messages. The reason for that is that `\r` is appended to the end of the line and `journalctl` doesn't strip it automatically unless `--all` is set:

```console
$ sudo journalctl -b CONTAINER_NAME=webserver --all
```

## [Retrieve log messages with the `journal` API](#retrieve-log-messages-with-the-journal-api)

This example uses the `systemd` Python module to retrieve container logs:

```python
import systemd.journal

reader = systemd.journal.Reader()
reader.add_match('CONTAINER_NAME=web')

for msg in reader:
    print '{CONTAINER_ID_FULL}: {MESSAGE}'.format(**msg)
```

----
url: https://docs.docker.com/reference/cli/docker/model/status/
----

# docker model status

***

| Description | Check if the Docker Model Runner is running |
| ----------- | ------------------------------------------- |
| Usage       | `docker model status`                       |

## [Description](#description)

Check whether the Docker Model Runner is running and displays the current inference engine.

## [Options](#options)

| Option   | Default | Description           |
| -------- | ------- | --------------------- |
| `--json` |         | Format output in JSON |

----
url: https://docs.docker.com/reference/cli/docker/compose/kill/
----

# docker compose kill

***

| Description | Force stop service containers                |
| ----------- | -------------------------------------------- |
| Usage       | `docker compose kill [OPTIONS] [SERVICE...]` |

## [Description](#description)

Forces running containers to stop by sending a `SIGKILL` signal. Optionally the signal can be passed, for example:

```console
$ docker compose kill -s SIGINT
```

## [Options](#options)

| Option             | Default   | Description                                                    |
| ------------------ | --------- | -------------------------------------------------------------- |
| `--remove-orphans` |           | Remove containers for services not defined in the Compose file |
| `-s, --signal`     | `SIGKILL` | SIGNAL to send to the container                                |

----
url: https://docs.docker.com/build/bake/contexts/
----

# Using Bake with additional contexts

***

Table of contents

***

In addition to the main `context` key that defines the build context, each target can also define additional named contexts with a map defined with key `contexts`. These values map to the `--build-context` flag in the [build command](/reference/cli/docker/buildx/build/#build-context).

Inside the Dockerfile these contexts can be used with the `FROM` instruction or `--from` flag.

Supported context values are:

* Local filesystem directories
* Container images
* Git URLs
* HTTP URLs
* Name of another target in the Bake file

## [Pinning alpine image](#pinning-alpine-image)

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN echo "Hello world"
```

docker-bake.hcl

```hcl
target "app" {
  contexts = {
    alpine = "docker-image://alpine:3.13"
  }
}
```

## [Using a secondary source directory](#using-a-secondary-source-directory)

Dockerfile

```dockerfile
FROM golang
COPY --from=src . .
```

docker-bake.hcl

```hcl
# Running `docker buildx bake app` will result in `src` not pointing
# to some previous build stage but to the client filesystem, not part of the context.
target "app" {
  contexts = {
    src = "../path/to/source"
  }
}
```

## [Using a target as a build context](#using-a-target-as-a-build-context)

To use a result of one target as a build context of another, specify the target name with `target:` prefix.

baseapp.Dockerfile

```dockerfile
FROM scratch
```

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
FROM baseapp
RUN echo "Hello world"
```

docker-bake.hcl

```hcl
target "base" {
  dockerfile = "baseapp.Dockerfile"
}

target "app" {
  contexts = {
    baseapp = "target:base"
  }
}
```

In most cases you should just use a single multi-stage Dockerfile with multiple targets for similar behavior. This case is only recommended when you have multiple Dockerfiles that can't be easily merged into one.

----
url: https://docs.docker.com/dhi/resources/
----

# Docker Hardened Images resources

***

Table of contents

***

This page provides links to additional resources related to Docker Hardened Images (DHI), including blog posts, guides, Docker Hub resources, and GitHub repositories.

For product information and feature comparison, visit the [Docker Hardened Images product page](https://www.docker.com/products/hardened-images/).

## [Blog posts](#blog-posts)

The following blog posts provide insights into Docker Hardened Images, security features, and announcements:

| Date published     | Title                                                                                                                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| May 5, 2026        | [Precision Container Security with Docker and Black Duck](https://www.docker.com/blog/precision-container-security-with-docker-and-black-duck/)                                                                           |
| April 14, 2026     | [Why We Chose the Harder Path: Docker Hardened Images, One Year Later](https://www.docker.com/blog/why-we-chose-the-harder-path-docker-hardened-images-one-year-later/)                                                   |
| April 8, 2026      | [Reclaim Developer Hours through Smarter Vulnerability Prioritization with Docker and Mend.io](https://www.docker.com/blog/reclaim-developer-hours-through-smarter-vulnerability-prioritization-with-docker-and-mend-io/) |
| March 3, 2026      | [Announcing Docker Hardened System Packages](https://www.docker.com/blog/announcing-docker-hardened-system-packages/)                                                                                                     |
| January 25, 2026   | [Making the Most of Your Docker Hardened Images Enterprise Trial - Part 3](https://www.docker.com/blog/making-the-most-of-your-docker-hardened-images-enterprise-trial-part-3/)                                           |
| January 24, 2026   | [Making the Most of Your Docker Hardened Images Enterprise Trial - Part 2](https://www.docker.com/blog/making-the-most-of-your-docker-hardened-images-enterprise-trial-part-2/)                                           |
| December 19, 2025  | [Docker Hardened Images: Security Independently Validated by SRLabs](https://www.docker.com/blog/docker-hardened-images-security-independently-validated-by-srlabs/)                                                      |
| December 17, 2025  | [A Safer Container Ecosystem with Docker: Free Docker Hardened Images](https://www.docker.com/blog/docker-hardened-images-for-every-developer/)                                                                           |
| November 14, 2025  | [Making the Most of Your Docker Hardened Images Enterprise Trial - Part 1](https://www.docker.com/blog/making-the-most-of-your-docker-hardened-images-trial-part-1/)                                                      |
| October 15, 2025   | [Docker Hardened Images: Crafted by Humans, Protected by AI](https://www.docker.com/blog/docker-hardened-images-crafted-by-humans-protected-by-ai/)                                                                       |
| September 29, 2025 | [Expanding Docker Hardened Images: Secure Helm Charts for Deployments](https://www.docker.com/blog/docker-hardened-images-helm-charts-beta/)                                                                              |
| August 6, 2025     | [The Next Evolution of Docker Hardened Images: Customizable, FedRAMP Ready, AI Migration Agent, and Deeper Integrations](https://www.docker.com/blog/the-next-evolution-of-docker-hardened-images/)                       |
| August 6, 2025     | [Accelerating FedRAMP Compliance with Docker Hardened Images](https://www.docker.com/blog/fedramp-compliance-with-hardened-images/)                                                                                       |
| May 19, 2025       | [Introducing Docker Hardened Images: Secure, Minimal, and Ready for Production](https://www.docker.com/blog/introducing-docker-hardened-images/)                                                                          |

## [Guides](#guides)

For guides that demonstrate how to use Docker Hardened Images in various scenarios, see the [guides section filtered by DHI](/guides/?tags=dhi).

## [Docker Hub](#docker-hub)

Docker Hardened Images are available on Docker Hub:

* [Docker Hardened Images Catalog](https://dhi.io): Browse and pull Docker Hardened Images from the official catalog
* [Docker Hub MCP Server](https://hub.docker.com/mcp/server/dockerhub/overview): MCP server to list Docker Hardened Images (DHIs) available in your organizations

## [GitHub repositories and resources](#github-repositories-and-resources)

Docker Hardened Images repositories are available in the [docker-hardened-images](https://github.com/docker-hardened-images) GitHub organization:

* [Catalog](https://github.com/docker-hardened-images/catalog): DHI definition files and catalog metadata
* [Advisories](https://github.com/docker-hardened-images/advisories): CVE advisories for OSS packages distributed with DHIs
  * [Scanner vendor integration guide](https://github.com/docker-hardened-images/advisories/tree/main/integration): Reference for scanner vendors integrating DHI VEX support
* [Keyring](https://github.com/docker-hardened-images/keyring): Public signing keys and verification tools
* [Log](https://github.com/docker-hardened-images/log): Log of references (tag > digest) for Docker Hardened Images
* [dhictl](https://github.com/docker-hardened-images/dhictl): Command-line interface for managing and interacting with Docker Hardened Images
* [Terraform Provider](https://github.com/docker-hardened-images/terraform-provider-dhi): Terraform provider for managing DHI resources ([Terraform Registry](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs))
* [Discussions](https://github.com/orgs/docker-hardened-images/discussions): Community forum and product discussions

## [Additional resources](#additional-resources)

* [Start a free trial](https://hub.docker.com/hardened-images/start-free-trial): Explore DHI Select and Enterprise features including FIPS/STIG variants, customization, and SLA-backed support
* [Support Service Level Agreement](https://docs.docker.com/go/dhi-sla/): Review the SLA commitments for DHI Select and Enterprise subscriptions
* [Request a demo](https://www.docker.com/products/hardened-images/#getstarted): Get a personalized demo and information about DHI Select and Enterprise subscriptions
* [Request an image](https://github.com/docker-hardened-images/catalog/issues): Submit a request for a specific Docker Hardened Image
* [Contact Sales](https://www.docker.com/pricing/contact-sales/): Connect with Docker sales team for enterprise inquiries
* [Docker Support](https://www.docker.com/support/): Access support resources for DHI Select and Enterprise customers

----
url: https://docs.docker.com/dhi/core-concepts/cves/
----

# Common Vulnerabilities and Exposures (CVEs)

***

Table of contents

***

## [What are CVEs?](#what-are-cves)

CVEs are publicly disclosed cybersecurity flaws in software or hardware. Each CVE is assigned a unique identifier (e.g., CVE-2024-12345) and includes a standardized description, allowing organizations to track and address vulnerabilities consistently.

In the context of Docker, CVEs often pertain to issues within base images, or application dependencies. These vulnerabilities can range from minor bugs to critical security risks, such as remote code execution or privilege escalation.

## [Why are CVEs important?](#why-are-cves-important)

Regularly scanning and updating Docker images to mitigate CVEs is crucial for maintaining a secure and compliant environment. Ignoring CVEs can lead to severe security breaches, including:

* Unauthorized access: Exploits can grant attackers unauthorized access to systems.
* Data breaches: Sensitive information can be exposed or stolen.
* Service disruptions: Vulnerabilities can be leveraged to disrupt services or cause downtime.
* Compliance violations: Failure to address known vulnerabilities can lead to non-compliance with industry regulations and standards.

## [How Docker Hardened Images help mitigate CVEs](#how-docker-hardened-images-help-mitigate-cves)

Docker Hardened Images (DHIs) are crafted to minimize the risk of CVEs from the outset. By adopting a security-first approach, DHIs offer several advantages in CVE mitigation:

* Reduced attack surface: DHIs are built using a distroless approach, stripping away unnecessary components and packages. This reduction in image size, up to 95% smaller than traditional images, limits the number of potential vulnerabilities, making it harder for attackers to exploit unneeded software.

* Faster CVE remediation: Maintained by Docker with an [enterprise-grade SLA](https://docs.docker.com/go/dhi-sla/), DHIs are continuously updated to address known vulnerabilities. Critical and high-severity CVEs are patched quickly, ensuring that your containers remain secure without manual intervention.

* Proactive vulnerability management: By utilizing DHIs, organizations can proactively manage vulnerabilities. The images come with CVE and Vulnerability Exposure (VEX) feeds, enabling teams to stay informed about potential threats and take necessary actions promptly.

## [Scan images for CVEs](#scan-images-for-cves)

Regularly scanning Docker images for CVEs is essential for maintaining a secure containerized environment. While Docker Scout is integrated into Docker Desktop and the Docker CLI, tools like Grype and Trivy offer alternative scanning capabilities. The following are instructions for using each tool to scan Docker images for CVEs.

### [Docker Scout](#docker-scout)

Docker Scout is integrated into Docker Desktop and the Docker CLI. It provides vulnerability insights, CVE summaries, and direct links to remediation guidance.

#### [Scan a DHI using Docker Scout](#scan-a-dhi-using-docker-scout)

To scan a Docker Hardened Image using Docker Scout, run the following command:

```console
$ docker scout cves dhi.io/<image>:<tag> --platform <platform>
```

Example output:

```plaintext
    v SBOM obtained from attestation, 101 packages found
    v Provenance obtained from attestation
    v VEX statements obtained from attestation
    v No vulnerable package detected
    ...
```

For more detailed filtering and JSON output, see [Docker Scout CLI reference](/reference/cli/docker/scout/).

### [Grype](#grype)

[Grype](https://github.com/anchore/grype) is an open-source scanner that checks container images against vulnerability databases like the NVD and distro advisories.

#### [Scan a DHI using Grype](#scan-a-dhi-using-grype)

After installing Grype, you can scan a Docker Hardened Image by pulling the image and running the scan command. Grype requires you to export the VEX attestation to a file first:

```console
$ docker pull dhi.io/<image>:<tag>
$ docker scout vex get dhi.io/<image>:<tag> --output vex.json
$ grype dhi.io/<image>:<tag> --vex vex.json
```

Example output:

```plaintext
NAME               INSTALLED              FIXED-IN     TYPE  VULNERABILITY     SEVERITY    EPSS%  RISK
libperl5.36        5.36.0-7+deb12u2       (won't fix)  deb   CVE-2023-31484    High        79.45    1.1
perl               5.36.0-7+deb12u2       (won't fix)  deb   CVE-2023-31484    High        79.45    1.1
perl-base          5.36.0-7+deb12u2       (won't fix)  deb   CVE-2023-31484    High        79.45    1.1
...
```

### [Trivy](#trivy)

[Trivy](https://github.com/aquasecurity/trivy) is an open-source vulnerability scanner for containers and other artifacts. It detects vulnerabilities in OS packages and application dependencies.

#### [Scan a DHI using Trivy](#scan-a-dhi-using-trivy)

After installing Trivy, you can scan a Docker Hardened Image by pulling the image and running the scan command:

```console
$ docker pull dhi.io/<image>:<tag>
$ trivy image --scanners vuln --vex repo dhi.io/<image>:<tag>
```

Example output:

```plaintext
Report Summary

┌──────────────────────────────────────────────────────────────────────────────┬────────────┬─────────────────┬─────────┐
│                                    Target                                    │    Type    │ Vulnerabilities │ Secrets │
├──────────────────────────────────────────────────────────────────────────────┼────────────┼─────────────────┼─────────┤
│ dhi.io/<image>:<tag> (debian 12.11)                                          │   debian   │       66        │    -    │
├──────────────────────────────────────────────────────────────────────────────┼────────────┼─────────────────┼─────────┤
│ opt/python-3.13.4/lib/python3.13/site-packages/pip-25.1.1.dist-info/METADATA │ python-pkg │        0        │    -    │
└──────────────────────────────────────────────────────────────────────────────┴────────────┴─────────────────┴─────────┘
```

## [Use VEX to filter known non-exploitable CVEs](#use-vex-to-filter-known-non-exploitable-cves)

Docker Hardened Images include signed [VEX (Vulnerability Exploitability eXchange)](https://docs.docker.com/dhi/core-concepts/vex/) attestations that identify vulnerabilities not relevant to the image’s runtime behavior.

When using Docker Scout or Trivy, these VEX statements are automatically applied using the previous examples, and no manual configuration needed.

To manually retrieve the VEX attestation for tools that support it:

```console
$ docker scout vex get dhi.io/<image>:<tag> --output vex.json
```

> Note
>
> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://dhi.io/python:3.13` instead of `dhi.io/python:3.13`.

For example:

```console
$ docker scout vex get dhi.io/python:3.13 --output vex.json
```

This creates a `vex.json` file containing the VEX statements for the specified image. You can then use this file with tools that support VEX to filter out known non-exploitable CVEs.

----
url: https://docs.docker.com/guides/genai-leveraging-rag/
----

[Leveraging RAG in GenAI to teach new information](https://docs.docker.com/guides/genai-leveraging-rag/)

This guide explains setting up a GenAI stack with Retrieval-Augmented Generation (RAG) and Neo4j, covering key concepts, deployment steps, and a case study. It also includes troubleshooting tips for optimizing AI performance with real-time data.

AI

35 minutes

[« Back to all guides](/guides/)

# Leveraging RAG in GenAI to teach new information

***

Table of contents

***

## [Introduction](#introduction)

Retrieval-Augmented Generation (RAG) is a powerful framework that enhances large language models (LLMs) by integrating information retrieval from external knowledge sources. This guide focuses on a specialized RAG implementation using graph databases like Neo4j, which excel in managing highly connected, relational data. Unlike traditional RAG setups with vector databases, combining RAG with graph databases offers better context-awareness and relationship-driven insights.

In this guide, you will:

* Explore the advantages of integrating graph databases into a RAG framework.
* Configure a GenAI stack with Docker, incorporating Neo4j and an AI model.
* Analyze a real-world case study that highlights the effectiveness of this approach for handling specialized queries.

## [Understanding RAG](#understanding-rag)

RAG is a hybrid framework that enhances the capabilities of large language models by integrating information retrieval. It combines three core components:

* **Information retrieval** from an external knowledge base
* **Large Language Model (LLM)** for generating responses
* **Vector embeddings** to enable semantic search

In a RAG system, vector embeddings are used to represent the semantic meaning of text in a way that a machine can understand and process. For instance, the words "dog" and "puppy" will have similar embeddings because they share similar meanings. By integrating these embeddings into the RAG framework, the system can combine the generative power of large language models with the ability to pull in highly relevant, contextually-aware data from external sources.

The system operates as follows:

1. Questions get turned into mathematical patterns that capture their meaning
2. These patterns help find matching information in a database
3. The LLM generates responses that blend the model's inherent knowledge with the this extra information.

To hold this vector information in an efficient manner, you need a special type of database.

## [Introduction to Graph databases](#introduction-to-graph-databases)

Graph databases, such as Neo4j, are specifically designed for managing highly connected data. Unlike traditional relational databases, graph databases prioritize both the entities and the relationships between them, making them ideal for tasks where connections are as important as the data itself.

Graph databases stand out for their unique approach to data storage and querying. They use nodes (or vertices) to represent entities and edges to represent the relationships between these entities. This structure allows for efficient handling of highly connected data and complex queries, which are difficult to manage in traditional database systems.

SQL databases and graph databases differ significantly in their data models. SQL databases use a tabular structure with rows and columns, where relationships between entities are established using foreign keys. This approach works well for structured data and predefined relationships. In contrast, graph databases represent data as nodes (entities) and edges (relationships), making the representation of relationships more intuitive and flexible. This structure is particularly advantageous for complex, interconnected data.

Another key difference lies in schema flexibility. SQL databases operate on a rigid schema, meaning any changes to the data structure, such as adding new columns or altering relationships, typically require careful planning and migration processes. Graph databases, however, are schema-optional, allowing for much greater flexibility. New nodes, edges, or properties can be introduced without disrupting existing data, enabling faster adaptation to changing requirements.

## [Practical implementation: testing RAG effectiveness](#practical-implementation-testing-rag-effectiveness)

To illustrate the power of RAG systems in practice, let's examine a real-world implementation using Apache NiFi as our subject matter. This case study demonstrates how RAG can enhance an AI's ability to provide accurate, contextual information about specialized technical topics.

### [Teaching AI about new technologies](#teaching-ai-about-new-technologies)

Apache NiFi serves as an excellent example of the limitations of traditional LLMs and how RAG can overcome them. As a relatively recent technology, many LLMs have limited or outdated knowledge about it, making it a perfect candidate for demonstrating RAG's capabilities.

Without RAG, the LLM may provide broad responses or acknowledge its limited knowledge when asked about information that is beyond its cutoff date. The following example demonstrates this.

```text
Question: What important events happened in 2024?
RAG: Disabled
I'm happy to help! Unfortunately, I'm a large language model, I don't have access to real-time information or events that occurred after my training data cutoff in 2024. Therefore, I cannot provide you with any important events that happened in 2024. My apologize for any inconvenience this may cause. Is there anything else I can help you with?
```

## [Setting up GenAI stack with GPU acceleration on Linux](#setting-up-genai-stack-with-gpu-acceleration-on-linux)

To set up and run the GenAI stack on a Linux host, execute one of the following commands, either for GPU or CPU powered:

### [GPU powered](#gpu-powered)

```bash
git clone https://github.com/docker/genai-stack
docker compose --profile linux-gpu up -d
mv env.example .env
nano .env
```

In the `.env` file, make sure following lines are commented out. Set your own credentials for security

```txt
  NEO4J_URI=neo4j://database:7687
  NEO4J_USERNAME=neo4j
  NEO4J_PASSWORD=password
  OLLAMA_BASE_URL=http://llm-gpu:11434
```

### [CPU powered](#cpu-powered)

```bash
git clone https://github.com/docker/genai-stack
docker compose --profile linux up -d
mv env.example .env
nano .env
```

In the `.env` file, make sure following lines are commented out. Set your own credentials for security

```txt
  NEO4J_URI=neo4j://database:7687
  NEO4J_USERNAME=neo4j
  NEO4J_PASSWORD=password
  OLLAMA_BASE_URL=http://llm:11434
```

### [Setting up on other platforms](#setting-up-on-other-platforms)

For instructions on how to set up the stack on other platforms, refer to [this page](https://github.com/docker/genai-stack).

### [Initial startup](#initial-startup)

The first startup may take some time because the system needs to download a large language model.

### [Monitoring progress](#monitoring-progress)

You can monitor the download and initialization progress by viewing the logs. Run the following command to view the logs:

```bash
docker compose logs
```

Wait for specific lines in the logs indicating that the download is complete and the stack is ready. These lines typically confirm successful setup and initialization.

```text
  pull-model-1 exited with code 0
  database-1    | 2024-12-29 09:35:53.269+0000 INFO  Started.
  pdf_bot-1     |   You can now view your Streamlit app in your browser.
  loader-1      |   You can now view your Streamlit app in your browser.
  bot-1         |   You can now view your Streamlit app in your browser.
```

You can now access the interface at <http://localhost:8501/> to ask questions. For example, you can try the sample question:

When those lines appear in the logs, the web apps are ready to use.

Since the goal is to teach AI about things it does not yet know, begin by asking it a simple question about NiFi at <http://localhost:8501/>.

```text
Question: What is Apache Nifi?
RAG: Disabled
Hello! I'm here to help you with your question about Apache NiFi. Unfortunately, I don't know the answer to that question. I'm just an AI and my knowledge cutoff is December 2022, so I may not be familiar with the latest technologies or software. Can you please provide more context or details about Apache NiFi? Maybe there's something I can help you with related to it.
```

As shown, the AI does not know anything about this subject because it did not exist during the time of its training, also known as the information cutoff point.

Now it's time to teach the AI some new tricks. First, connect to <http://localhost:8502/>. Instead of using the "neo4j" tag, change it to the "apache-nifi" tag, then select the **Import** button.

After the import is successful, you can access Neo4j to verify the data.

After logging in to <http://localhost:7474/> using the credentials from the `.env` file, you can run queries on Neo4j. Using the Neo4j Cypher query language, you can check for the data stored in the database.

To count the data, run the following query:

```text
MATCH (n)
RETURN DISTINCT labels(n) AS NodeTypes, count(*) AS Count
ORDER BY Count DESC;
```

To execute this query, write in the box on the top and select the blue run button.

Results will appear below. The information shown is downloaded from Stack Overflow and saved in the graph database. RAG will utilize this information to enhance its responses.

You can also run the following query to visualize the data:

```text
CALL db.schema.visualization()
```

To check the relationships in the database, run the following query:

```text
CALL db.relationshipTypes()
```

You're ready to enable the LLM to use this information. Go back to <http://localhost:8501/>, enable the **RAG** checkbox, and ask the same question again. The LLM will provide a more detailed answer.

The system delivers comprehensive, accurate information by pulling from current technical documentation.

```text
Question: What is Apache Nifi?
RAG: Enabled

Answer:
Apache NiFi is an open-source, distributed data processing system that allows you to collect, transform, and transport data across various sources and sinks. It provides a graphical user interface for designing and managing data flows, as well as a set of APIs for integrating with other systems.
According to this Stack Overflow question, the free Neo4J JDBC driver doesn't understand SQL, only Cypher, so you would need to use a non-free BI Connector to connect to Neo4j from Apache Drill.
Additionally, this Stack Overflow question suggests that Apache POI does work in a Neo4j User Defined Function. However, there may be an unknown glitch in the standalone UDF mentioned in the initial question.
To export data from Neo4j to Excel using APOC Extended procedures, you can use apoc.export.xls.query which takes a Cypher query and exports the results to an Excel file.

References:
How to connect and query Neo4j Database on Apache Drill?
Is a Neo4j UDF compatible with Apache POI?
```

Keep in mind that new questions will be added to Stack Overflow, and due to the inherent randomness in most AI models, the answers may vary and won't be identical to those in this example.

Feel free to start over with another [Stack Overflow tag](https://stackoverflow.com/tags). To drop all data in Neo4j, you can use the following command in the Neo4j Web UI:

```txt
MATCH (n)
DETACH DELETE n;
```

For optimal results, choose a tag that the LLM is not familiar with.

### [When to leverage RAG for optimal results](#when-to-leverage-rag-for-optimal-results)

Retrieval-Augmented Generation (RAG) is particularly effective in scenarios where standard Large Language Models (LLMs) fall short. The three key areas where RAG excels are knowledge limitations, business requirements, and cost efficiency. The following sections explore these aspects in more detail.

#### [Overcoming knowledge limitations](#overcoming-knowledge-limitations)

LLMs are trained on a fixed dataset up until a certain point in time. This means they lack access to:

* Real-time information: LLMs do not continuously update their knowledge, so they may not be aware of recent events, newly released research, or emerging technologies.
* Specialized knowledge: Many niche subjects, proprietary frameworks, or industry-specific best practices may not be well-documented in the model’s training corpus.
* Accurate contextual understanding: LLMs can struggle with nuances or evolving terminologies that frequently change within dynamic fields like finance, cybersecurity, or medical research.

By incorporating RAG with a graph database such as Neo4j, AI models can access and retrieve the latest, relevant, and highly connected data before generating a response. This ensures that answers are up-to-date and grounded in factual information rather than inferred approximations.

#### [Addressing business and compliance needs](#addressing-business-and-compliance-needs)

Organizations in industries like healthcare, legal services, and financial analysis require their AI-driven solutions to be:

* Accurate: Businesses need AI-generated content that is factual and relevant to their specific domain.
* Compliant: Many industries must adhere to strict regulations regarding data usage and security.
* Traceable: Enterprises often require AI responses to be auditable, meaning they need to reference source material.

By using RAG, AI-generated answers can be sourced from trusted databases, ensuring higher accuracy and compliance with industry standards. This mitigates risks such as misinformation or regulatory violations.

#### [Enhancing cost efficiency and performance](#enhancing-cost-efficiency-and-performance)

Training and fine-tuning large AI models can be computationally expensive and time-consuming. However, integrating RAG provides:

* Reduced fine-tuning needs: Instead of retraining an AI model every time new data emerges, RAG allows the model to fetch and incorporate updated information dynamically.
* Better performance with smaller models: With the right retrieval techniques, even compact AI models can perform well by leveraging external knowledge efficiently.
* Lower operational costs: Instead of investing in expensive infrastructure to support large-scale retraining, businesses can optimize resources by utilizing RAG’s real-time retrieval capabilities.

By following this guide, you now have the foundational knowledge to implement RAG with Neo4j, enabling your AI system to deliver more accurate, relevant, and insightful responses. The next step is experimentation—choose a dataset, configure your stack, and start enhancing your AI with the power of retrieval-augmented generation.

----
url: https://docs.docker.com/guides/testcontainers-java-getting-started/
----

# Getting started with Testcontainers for Java

Table of contents

***

Learn how to create a Java application and test database interactions using Testcontainers for Java with a real PostgreSQL instance.

**Time to complete** 20 minutes

In this guide, you will learn how to:

* Create a Java project with Maven
* Implement a `CustomerService` that manages customer records in PostgreSQL
* Write integration tests using Testcontainers with a real Postgres database
* Run the tests and verify everything works

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-getting-started/create-project/)

   Set up a Java project with Maven and implement a PostgreSQL-backed customer service.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-getting-started/write-tests/)

   Write your first integration test using Testcontainers for Java and PostgreSQL.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-getting-started/run-tests/)

   Run your Testcontainers-based integration tests and explore next steps.

----
url: https://docs.docker.com/guides/bun/configure-ci-cd/
----

# Configure CI/CD for your Bun application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a Bun application](https://docs.docker.com/guides/bun/containerize/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

   ```console
   $ git remote set-url origin https://github.com/your-username/your-repository.git
   ```

7. Run the following commands to stage, commit, and push your local repository to GitHub.

   ```console
   $ git add -A
   $ git commit -m "my commit"
   $ git push -u origin main
   ```

## [Step two: Set up the workflow](#step-two-set-up-the-workflow)

Set up your GitHub Actions workflow for building, testing, and pushing the image to Docker Hub.

1. Go to your repository on GitHub and then select the **Actions** tab.

2. Select **set up a workflow yourself**.

   This takes you to a page for creating a new GitHub actions workflow file in your repository, under `.github/workflows/main.yml` by default.

3. In the editor window, copy and paste the following YAML configuration and commit the changes.

   ```yaml
   name: ci

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Login to Docker Hub
           uses: docker/login-action@v4
           with:
             username: ${{ vars.DOCKER_USERNAME }}
             password: ${{ secrets.DOCKERHUB_TOKEN }}

         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v4

         - name: Build and push
           uses: docker/build-push-action@v7
           with:
             platforms: linux/amd64,linux/arm64
             push: true
             tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
   ```

In this section, you learned how to set up a GitHub Actions workflow for your Bun application.

Related information:

* [Introduction to GitHub Actions](https://docs.docker.com/guides/gha/)
* [Docker Build GitHub Actions](https://docs.docker.com/build/ci/github-actions/)
* [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)

## [Next steps](#next-steps)

Next, learn how you can locally test and debug your workloads on Kubernetes before deploying.

[Test your Bun deployment »](https://docs.docker.com/guides/bun/deploy/)

----
url: https://docs.docker.com/reference/cli/docker/sandbox/create/copilot/
----

# docker sandbox create copilot

***

| Description | Create a sandbox for copilot                                   |
| ----------- | -------------------------------------------------------------- |
| Usage       | `docker sandbox create copilot WORKSPACE [EXTRA_WORKSPACE...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Create a sandbox with access to a host workspace for copilot.

The workspace path is required and will be exposed inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use 'docker sandbox run SANDBOX' to start copilot after creation.

----
url: https://docs.docker.com/billing/payment-method/
----

# Add or update a payment method

***

Table of contents

***

Docker supports different payment methods for your paid personal account or organization. This page describes supported payment types, how to make payments from [Docker Home](https://app.docker.com/), and how to set up pay by invoice.

## [Supported payment types](#supported-payment-types)

You can add a payment method or update your account's existing payment method at any time. All charges are in United States dollars (USD). The following payment methods are supported:

| Category      | Payment type                                                            |
| ------------- | ----------------------------------------------------------------------- |
| Cards         | Visa, MasterCard, American Express, Discover, JCB, Diners, UnionPay     |
| Wallets       | Stripe Link                                                             |
| Bank accounts | Automated Clearing House (ACH) transfer with a verified US bank account |

## [Prerequisites](#prerequisites)

Certain payment methods require additional steps before selecting them as a payment method:

* You must [verify a bank account](https://docs.docker.com/billing/payment-method/#verify-a-bank-account) before choosing a bank account.
* You must have a Docker Business or Docker Team plan to [pay by invoice](https://docs.docker.com/billing/payment-method/#enable-and-disable-pay-by-invoice).
* You must be an existing Stripe Link customer, or fill out the card information form to use Link payments.

## [Manage payment method](#manage-payment-method)

Paid personal accounts and organizations follow the same procedures to add, update, or remove payment methods.

### [Add payment method](#add-payment-method)

1. Sign in to [Docker Home](https://app.docker.com/).

2. Select your account name for personal accounts, or select your organization name for organization accounts.

3. Select **Billing**, then **Payment methods**.

4. Select **Add payment method** and enter your new payment information:

   * For first time setup, fill in your billing information.
   * To purchase as a business, provide your tax ID.

5. Choose to add a card, a US bank account, or a Link payment.

   * To pay with card, fill out the card information form.

   * To pay with a US bank account:

     * Verify your **Email** and **Full name**.
     * If your bank is listed, select your bank's name.
     * If your bank is not listed, select **Search for your bank**.

   * To pay through Link, select an existing payment and choose **Use this card**.

6. Finish adding the payment method by selecting **Add payment method**.

### [Set default payment method](#set-default-payment-method)

After adding one or more payment methods, you can set one as a default method.

1. From **Billing**, go to **Payment methods**.
2. Find the payment method you want to set as default from the **Payment method** table.
3. Select the three dots, then choose **Set as default**.

### [Remove payment method](#remove-payment-method)

To remove a single payment method:

1. From **Billing**, go to **Payment methods**.
2. Find the payment method you want to remove from the **Payment method** table.
3. Select the three dots, then choose **Remove**.

To remove your default payment method, first set a different payment method as default, or [downgrade to a free subscription](https://docs.docker.com/subscription/change/).

## [Enable and disable pay by invoice](#enable-and-disable-pay-by-invoice)

> Tip
>
> Do you need to pay by invoice? [Upgrade to a Docker Business or Docker Team plan](https://www.docker.com/pricing?ref=Docs\&refAction=DocsBillingPaymentMethod) and choose the annual subscription.

Pay by invoice requires you to pay upfront for your first subscription period using a payment card or ACH bank transfer. At renewal time, instead of automatic payment, you'll receive an invoice via email that you must pay manually.

Follow these steps to enable or disable pay by invoice:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Billing**, then **Payment methods**.
3. Select **Pay by invoice**, then select the pay by invoice toggle to enable or disable.
4. Confirm your billing contact details. If you need to change them, select **Change** and enter your new details.

Pay by invoice is not available for subscription upgrades or changes.

## [Verify a bank account](#verify-a-bank-account)

There are two ways to verify a bank account as a payment method:

* Instant verification: Docker supports several major banks for instant verification.
* Manual verification: All other banks must be verified manually.

### [Instant verification](#instant-verification)

To verify your bank account instantly, you must sign in to your bank account from the Docker billing flow:

1. Choose **US bank account** as your payment method.
2. Verify your **Email** and **Full name**.
3. If your bank is listed, select your bank's name or select **Search for your bank**.
4. Sign in to your bank and review the terms and conditions. This agreement allows Docker to debit payments from your connected bank account.
5. Select **Agree and continue**.
6. Select an account to link and verify, and select **Connect account**.

When the account is verified, you will see a success message in the pop-up modal.

### [Manual verification](#manual-verification)

To verify your bank account manually, you must enter the micro-deposit amount from your bank statement:

1. Choose **US bank account** as your payment method.
2. Verify your **Email** and **First and last name**.
3. Select **Enter bank details manually instead**.
4. Enter your bank details: **Routing number** and **Account number**.
5. Select **Submit**.
6. You will receive an email with instructions on how to manually verify.

Manual verification uses micro-deposits. You’ll see a small deposit (such as $0.01) in your bank account within 1–2 business days. Open your manual verification email and enter the amount of this deposit to verify your account.

## [Failed payments](#failed-payments)

If your payment fails, select **Pay now**. This redirects you from Docker Hub so you can manually retry the payment through Stripe.

You have a grace period of 15 days including the due date when your payment fails. Docker retries to collect the payment 3 times using the following schedule:

* 3 days after the due date
* 5 days after the previous attempt
* 7 days after the previous attempt

Docker also sends an email notification `Action Required - Credit Card Payment Failed` with an attached unpaid invoice after each failed payment attempt.

Once the grace period is over and the invoice is still not paid, the subscription downgrades to a free subscription and all paid features are disabled.

----
url: https://docs.docker.com/reference/compose-file/interpolation/
----

# Interpolation

***

***

Values in a Compose file can be set by variables and interpolated at runtime. Compose files use a Bash-like syntax `${VARIABLE}`. Both `$VARIABLE` and `${VARIABLE}` syntax is supported.

Interpolation can also be nested:

* `${VARIABLE:-${FOO}}`
* `${VARIABLE?$FOO}`
* `${VARIABLE:-${FOO:-default}}`

Other extended shell-style features, such as `${VARIABLE/foo/bar}`, are not supported by Compose.

Compose processes any string following a `$` sign as long as it makes it a valid variable definition - either an alphanumeric name (`[_a-zA-Z][_a-zA-Z0-9]*`) or a braced string starting with `${`. In other circumstances, it will be preserved without attempting to interpolate a value.

You can use a `$$` (double-dollar sign) when your configuration needs a literal dollar sign. This also prevents Compose from interpolating a value, so a `$$` allows you to refer to environment variables that you don't want processed by Compose.

```yml
web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"
```

If Compose can't resolve a substituted variable and no default value is defined, it displays a warning and substitutes the variable with an empty string.

As any values in a Compose file can be interpolated with variable substitution, including compact string notation for complex elements, interpolation is applied before a merge on a per-file basis.

Interpolation applies only to YAML values, not to keys. For the few places where keys are actually arbitrary user-defined strings, such as [labels](https://docs.docker.com/reference/compose-file/services/#labels) or [environment](https://docs.docker.com/reference/compose-file/services/#environment), an alternate equal sign syntax must be used for interpolation to apply. For example:

```yml
services:
  foo:
    labels:
      "$VAR_NOT_INTERPOLATED_BY_COMPOSE": "BAR"
```

```yml
services:
  foo:
    labels:
      - "$VAR_INTERPOLATED_BY_COMPOSE=BAR"
```

----
url: https://docs.docker.com/reference/cli/docker/model/show/
----

# docker model show

***

| Description | Show information for a model |
| ----------- | ---------------------------- |
| Usage       | `docker model show MODEL`    |

## [Description](#description)

Display detailed information about a model in a human-readable format.

## [Options](#options)

| Option         | Default | Description                 |
| -------------- | ------- | --------------------------- |
| `-r, --remote` |         | Show info for remote models |

----
url: https://docs.docker.com/engine/extend/plugins_authorization/
----

# Access authorization plugin

***

Table of contents

***

This document describes the Docker Engine plugins available in Docker Engine. To view information on plugins managed by Docker Engine, refer to [Docker Engine plugin system](https://docs.docker.com/engine/extend/).

Docker's out-of-the-box authorization model is all or nothing. Any user with permission to access the Docker daemon can run any Docker client command. The same is true for callers using Docker's Engine API to contact the daemon. If you require greater access control, you can create authorization plugins and add them to your Docker daemon configuration. Using an authorization plugin, a Docker administrator can configure granular access policies for managing access to the Docker daemon.

Anyone with the appropriate skills can develop an authorization plugin. These skills, at their most basic, are knowledge of Docker, understanding of REST, and sound programming knowledge. This document describes the architecture, state, and methods information available to an authorization plugin developer.

## [Basic principles](#basic-principles)

Docker's [plugin infrastructure](https://docs.docker.com/engine/extend/plugin_api/) enables extending Docker by loading, removing and communicating with third-party components using a generic API. The access authorization subsystem was built using this mechanism.

Using this subsystem, you don't need to rebuild the Docker daemon to add an authorization plugin. You can add a plugin to an installed Docker daemon. You do need to restart the Docker daemon to add a new plugin.

An authorization plugin approves or denies requests to the Docker daemon based on both the current authentication context and the command context. The authentication context contains all user details and the authentication method. The command context contains all the relevant request data.

Authorization plugins must follow the rules described in [Docker Plugin API](https://docs.docker.com/engine/extend/plugin_api/). Each plugin must reside within directories described under the [Plugin discovery](https://docs.docker.com/engine/extend/plugin_api/#plugin-discovery) section.

> Note
>
> The abbreviations `AuthZ` and `AuthN` mean authorization and authentication respectively.

## [Default user authorization mechanism](#default-user-authorization-mechanism)

If TLS is enabled in the [Docker daemon](https://docs.docker.com/engine/security/https/), the default user authorization flow extracts the user details from the certificate subject name. That is, the `User` field is set to the client certificate subject common name, and the `AuthenticationMethod` field is set to `TLS`.

## [Basic architecture](#basic-architecture)

You are responsible for registering your plugin as part of the Docker daemon startup. You can install multiple plugins and chain them together. This chain can be ordered. Each request to the daemon passes in order through the chain. Only when all the plugins grant access to the resource, is the access granted.

When an HTTP request is made to the Docker daemon through the CLI or via the Engine API, the authentication subsystem passes the request to the installed authentication plugin(s). The request contains the user (caller) and command context. The plugin is responsible for deciding whether to allow or deny the request.

The sequence diagrams below depict an allow and deny authorization flow:

Each request sent to the plugin includes the authenticated user, the HTTP headers, and the request/response body. Only the user name and the authentication method used are passed to the plugin. Most importantly, no user credentials or tokens are passed. Finally, not all request/response bodies are sent to the authorization plugin. Only request/response bodies where the `Content-Type` is `application/json` are sent to the authorization plugin; bodies of any other `Content-Type` are not visible to the plugin and cannot be used for enforcement, even though the daemon may still act on this data.

For commands that can potentially hijack the HTTP connection (`HTTP Upgrade`), such as `exec`, the authorization plugin is only called for the initial HTTP requests. Once the plugin approves the command, authorization is not applied to the rest of the flow. Specifically, the streaming data is not passed to the authorization plugins. For commands that return chunked HTTP response, such as `logs` and `events`, only the HTTP request is sent to the authorization plugins.

### [Response body size and partial buffering](#response-body-size-and-partial-buffering)

The internal buffer that holds the response body between the daemon's HTTP handler and the plugin's response authorization callback (`responseModifier`, defined in [`pkg/authorization/response.go`](https://github.com/moby/moby/blob/master/pkg/authorization/response.go)) has a fixed capacity of 64 KiB (`maxBufferSize`).

For most non-streaming endpoints the full response is buffered for plugin inspection regardless of total size, because Go's `encoding/json` encoder serializes the complete payload into a single underlying write. The streaming-response exclusion noted above (for example, `logs` and `events`) is the practical effect of this 64 KiB threshold combined with the `io.WriteFlusher` write pattern used by streaming handlers, where each write is immediately drained to the client and is therefore no longer available for plugin inspection by the time the handler returns.

> Note
>
> Plugins that depend on `ResponseBody` inspection for redaction or content-filtering should restrict their policies to endpoints whose response is produced as a single write (typical of REST-style API responses). For commands whose responses are streamed or are likely to exceed the buffer through multiple writes, do not rely on `ResponseBody` for security-relevant decisions; perform the filtering in a separate layer in front of the daemon.

During request/response processing, some authorization flows might need to do additional queries to the Docker daemon. To complete such flows, plugins can call the daemon API similar to a regular user. To enable these additional queries, the plugin must provide the means for an administrator to configure proper authentication and security policies.

## [Docker client flows](#docker-client-flows)

To enable and configure the authorization plugin, the plugin developer must support the Docker client interactions detailed in this section.

### [Setting up Docker daemon](#setting-up-docker-daemon)

Enable the authorization plugin with a dedicated command line flag in the `--authorization-plugin=PLUGIN_ID` format. The flag supplies a `PLUGIN_ID` value. This value can be the plugin’s socket or a path to a specification file. Authorization plugins can be loaded without restarting the daemon. Refer to the [`dockerd` documentation](https://docs.docker.com/reference/cli/dockerd/#configuration-reload-behavior) for more information.

```console
$ dockerd --authorization-plugin=plugin1 --authorization-plugin=plugin2,...
```

Docker's authorization subsystem supports multiple `--authorization-plugin` parameters.

### [Calling authorized command (allow)](#calling-authorized-command-allow)

```console
$ docker pull centos
<...>
f1b10cd84249: Pull complete
<...>
```

### [Calling unauthorized command (deny)](#calling-unauthorized-command-deny)

```console
$ docker pull centos
<...>
docker: Error response from daemon: authorization denied by plugin PLUGIN_NAME: volumes are not allowed.
```

### [Error from plugins](#error-from-plugins)

```console
$ docker pull centos
<...>
docker: Error response from daemon: plugin PLUGIN_NAME failed with error: AuthZPlugin.AuthZReq: Cannot connect to the Docker daemon. Is the docker daemon running on this host?.
```

## [API schema and implementation](#api-schema-and-implementation)

In addition to Docker's standard plugin registration method, each plugin should implement the following two methods:

* `/AuthZPlugin.AuthZReq` This authorize request method is called before the Docker daemon processes the client request.

* `/AuthZPlugin.AuthZRes` This authorize response method is called before the response is returned from Docker daemon to the client.

#### [/AuthZPlugin.AuthZReq](#authzpluginauthzreq)

Request

```json
{
    "User":              "The user identification",
    "UserAuthNMethod":   "The authentication method used",
    "RequestMethod":     "The HTTP method",
    "RequestURI":        "The HTTP request URI",
    "RequestBody":       "Byte array containing the raw HTTP request body",
    "RequestHeader":     "Byte array containing the raw HTTP request header as a map[string][]string "
}
```

Response

```json
{
    "Allow": "Determined whether the user is allowed or not",
    "Msg":   "The authorization message",
    "Err":   "The error message if things go wrong"
}
```

#### [/AuthZPlugin.AuthZRes](#authzpluginauthzres)

Request:

```json
{
    "User":              "The user identification",
    "UserAuthNMethod":   "The authentication method used",
    "RequestMethod":     "The HTTP method",
    "RequestURI":        "The HTTP request URI",
    "RequestBody":       "Byte array containing the raw HTTP request body",
    "RequestHeader":     "Byte array containing the raw HTTP request header as a map[string][]string",
    "ResponseBody":      "Byte array containing the raw HTTP response body",
    "ResponseHeader":    "Byte array containing the raw HTTP response header as a map[string][]string",
    "ResponseStatusCode":"Response status code"
}
```

Response:

```json
{
   "Allow":              "Determined whether the user is allowed or not",
   "Msg":                "The authorization message",
   "Err":                "The error message if things go wrong"
}
```

### [Request authorization](#request-authorization)

Each plugin must support two request authorization messages formats, one from the daemon to the plugin and then from the plugin to the daemon. The tables below detail the content expected in each message.

#### [Daemon -> Plugin](#daemon---plugin)

| Name                  | Type               | Description                                                               |
| --------------------- | ------------------ | ------------------------------------------------------------------------- |
| User                  | string             | The user identification                                                   |
| Authentication method | string             | The authentication method used                                            |
| Request method        | enum               | The HTTP method (GET/DELETE/POST)                                         |
| Request URI           | string             | The HTTP request URI including API version (e.g., v.1.17/containers/json) |
| Request headers       | map\[string]string | Request headers as key value pairs (without the authorization header)     |
| Request body          | \[]byte            | Raw request body                                                          |

#### [Plugin -> Daemon](#plugin---daemon)

| Name  | Type   | Description                                                                                                                                                                        |
| ----- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Allow | bool   | Boolean value indicating whether the request is allowed or denied                                                                                                                  |
| Msg   | string | Authorization message (will be returned to the client in case the access is denied)                                                                                                |
| Err   | string | Error message (will be returned to the client in case the plugin encounter an error. The string value supplied may appear in logs, so should not include confidential information) |

### [Response authorization](#response-authorization)

The plugin must support two authorization messages formats, one from the daemon to the plugin and then from the plugin to the daemon. The tables below detail the content expected in each message.

#### [Daemon -> Plugin](#daemon---plugin-1)

| Name                  | Type               | Description                                                               |
| --------------------- | ------------------ | ------------------------------------------------------------------------- |
| User                  | string             | The user identification                                                   |
| Authentication method | string             | The authentication method used                                            |
| Request method        | string             | The HTTP method (GET/DELETE/POST)                                         |
| Request URI           | string             | The HTTP request URI including API version (e.g., v.1.17/containers/json) |
| Request headers       | map\[string]string | Request headers as key value pairs (without the authorization header)     |
| Request body          | \[]byte            | Raw request body                                                          |
| Response status code  | int                | Status code from the Docker daemon                                        |
| Response headers      | map\[string]string | Response headers as key value pairs                                       |
| Response body         | \[]byte            | Raw Docker daemon response body                                           |

#### [Plugin -> Daemon](#plugin---daemon-1)

| Name  | Type   | Description                                                                                                                                                                        |
| ----- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Allow | bool   | Boolean value indicating whether the response is allowed or denied                                                                                                                 |
| Msg   | string | Authorization message (will be returned to the client in case the access is denied)                                                                                                |
| Err   | string | Error message (will be returned to the client in case the plugin encounter an error. The string value supplied may appear in logs, so should not include confidential information) |

----
url: https://docs.docker.com/guides/angular/develop/
----

# Use containers for Angular development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize Angular application](https://docs.docker.com/guides/angular/containerize/).

***

## [Overview](#overview)

In this section, you'll learn how to set up both production and development environments for your containerized Angular application using Docker Compose. This setup allows you to serve a static production build via Nginx and to develop efficiently inside containers using a live-reloading dev server with Compose Watch.

You’ll learn how to:

* Configure separate containers for production and development
* Enable automatic file syncing using Compose Watch in development
* Debug and live-preview your changes in real-time without manual rebuilds

***

## [Automatically update services (development mode)](#automatically-update-services-development-mode)

Use Compose Watch to automatically sync source file changes into your containerized development environment. This provides a seamless, efficient development experience without restarting or rebuilding containers manually.

## [Step 1: Create a development Dockerfile](#step-1-create-a-development-dockerfile)

Create a file named `Dockerfile.dev` in your project root with the following content:

```dockerfile
# =========================================
# Stage 1: Development - Angular Application
# =========================================

# Define the Node.js version to use (Alpine for a small footprint)
ARG NODE_VERSION=24.12.0-alpine

# Set the base image for development
FROM node:${NODE_VERSION} AS dev

# Set environment variable to indicate development mode
ENV NODE_ENV=development

# Set the working directory inside the container
WORKDIR /app

# Copy only the dependency files first to optimize Docker caching
COPY package.json package-lock.json* ./

# Install dependencies using npm with caching to speed up subsequent builds
RUN --mount=type=cache,target=/root/.npm npm install

# Copy all application source files into the container
COPY . .

# Expose the port Angular uses for the dev server (default is 4200)
EXPOSE 4200

# Start the Angular dev server and bind it to all network interfaces
CMD ["npm", "start", "--", "--host=0.0.0.0"]
```

This file sets up a lightweight development environment for your Angular application using the dev server.

### [Step 2: Update your `compose.yaml` file](#step-2-update-your-composeyaml-file)

Open your `compose.yaml` file and define two services: one for production (`angular-prod`) and one for development (`angular-dev`).

Here’s an example configuration for an Angular application:

```yaml
services:
  angular-prod:
    build:
      context: .
      dockerfile: Dockerfile
    image: docker-angular-sample
    ports:
      - "8080:8080"

  angular-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "4200:4200"
    develop:
      watch:
        - action: sync
          path: .
          target: /app
```

* The `angular-prod` service builds and serves your static production app using Nginx.
* The `angular-dev` service runs your Angular development server with live reload and hot module replacement.
* `watch` triggers file sync with Compose Watch.

> Note
>
> For more details, see the official guide: [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

After completing the previous steps, your project directory should now contain the following files:

```text
├── docker-angular-sample/
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ ├── .dockerignore
│ ├── compose.yaml
│ └── nginx.conf
```

### [Step 4: Start Compose Watch](#step-4-start-compose-watch)

Run the following command from the project root to start the container in watch mode

```console
$ docker compose watch angular-dev
```

### [Step 5: Test Compose Watch with Angular](#step-5-test-compose-watch-with-angular)

To verify that Compose Watch is working correctly:

1. Open the `src/app/app.component.html` file in your text editor.

2. Locate the following line:

   ```html
   <h1>Docker Angular Sample Application</h1>
   ```

3. Change it to:

   ```html
   <h1>Hello from Docker Compose Watch</h1>
   ```

4. Save the file.

5. Open your browser at <http://localhost:4200>.

You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected.

***

## [Summary](#summary)

In this section, you set up a complete development and production workflow for your Angular application using Docker and Docker Compose.

Here’s what you accomplished:

* Created a `Dockerfile.dev` to streamline local development with hot reloading
* Defined separate `angular-dev` and `angular-prod` services in your `compose.yaml` file
* Enabled real-time file syncing using Compose Watch for a smoother development experience
* Verified that live updates work seamlessly by modifying and previewing a component

With this setup, you're now equipped to build, run, and iterate on your Angular app entirely within containers—efficiently and consistently across environments.

***

In the next section, you'll learn how to run unit tests for your Angular application inside Docker containers. This ensures consistent testing across all environments and removes dependencies on local machine setup.

[Run Angular tests in a container »](https://docs.docker.com/guides/angular/run-tests/)

----
url: https://docs.docker.com/docker-hub/troubleshoot/
----

# Troubleshoot Docker Hub

***

Table of contents

***

If you experience issues with Docker Hub, refer to the following solutions.

## [You have reached your pull rate limit (429 response code)](#you-have-reached-your-pull-rate-limit-429-response-code)

### [Error message](#error-message)

When this issue occurs, you receive following error message in the Docker CLI or in the Docker Engine logs:

```text
You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits
```

### [Possible causes](#possible-causes)

* You have reached your pull rate limit as an authenticated Docker Personal user.
* You have reached your pull rate limit as an unauthenticated user based on your IPv4 address or IPv6 /64 subnet.

### [Solution](#solution)

You can use one of the following solutions:

* [Authenticate](https://docs.docker.com/docker-hub/usage/pulls/#authentication) or [upgrade](https://docs.docker.com/subscription/change/#upgrade-your-subscription) your Docker account.
* [View your pull rate limit](https://docs.docker.com/docker-hub/usage/pulls/#view-hourly-pull-rate-and-limit), wait until your pull rate limit decreases, and then try again.

## [Too many requests (429 response code)](#too-many-requests-429-response-code)

### [Error message](#error-message-1)

When this issue occurs, you receive following error message in the Docker CLI or in the Docker Engine logs:

```text
Too Many Requests
```

### [Possible causes](#possible-causes-1)

* You have reached the [Abuse rate limit](https://docs.docker.com/docker-hub/usage/#abuse-rate-limit).

### [Solution](#solution-1)

1. Check for broken CI/CD pipelines accessing Docker Hub and fix them.
2. Implement a retry with back-off solution in your automated scripts to ensure that you're not resending thousands of requests per minute.

## [500 response code](#500-response-code)

### [Error message](#error-message-2)

When this issue occurs, the following error message is common in the Docker CLI or in the Docker Engine logs:

```text
Unexpected status code 500
```

### [Possible causes](#possible-causes-2)

* There is a temporary Docker Hub service issue.

### [Solution](#solution-2)

1. View the [Docker System Status Page](https://www.dockerstatus.com/) and verify that all services are operational.
2. Try accessing Docker Hub again. It may be a temporary issue.
3. [Contact Docker Support](https://www.docker.com/support/) to report the issue.

----
url: https://docs.docker.com/guides/admin-set-up/
----

# Set up your company for success with Docker

Table of contents

***

Get the most out of Docker by streamlining workflows, standardizing development environments, and ensuring smooth deployments across your company.

**Time to complete** 20 minutes

Docker's tools provide a scalable, secure platform that empowers your developers to create, ship, and run applications faster. As an administrator, you can streamline workflows, standardize development environments, and ensure smooth deployments across your organization.

By configuring Docker products to suit your company's needs, you can optimize performance, simplify user management, and maintain control over resources. This guide helps you set up and configure Docker products to maximize productivity and success for your team while meeting compliance and security policies.

## [Who’s this for?](#whos-this-for)

* Administrators responsible for managing Docker environments within their organization
* IT leaders looking to streamline development and deployment workflows
* Teams aiming to standardize application environments across multiple users
* Organizations seeking to optimize their use of Docker products for greater scalability and efficiency
* Organizations with a [Docker Business subscription](https://www.docker.com/pricing?ref=DocsGuides\&refAction=DocsGuidesCTAClicked)

## [What you’ll learn](#what-youll-learn)

* Why signing into your company's Docker organization provides access to usage data and enhanced functionality
* How to standardize Docker Desktop versions and settings to create a consistent baseline for all users, while allowing flexibility for advanced developers
* Strategies for implementing Docker's security configurations to meet company IT and software development security requirements without hindering developer productivity

## [Features covered](#features-covered)

This guide covers the following Docker features:

* [Organizations](https://docs.docker.com/admin/organization/): The core structure for managing your Docker environment, grouping users, teams, and image repositories. Your organization was created with your subscription and is managed by one or more owners. Users signed into the organization are assigned seats based on the purchased subscription.
* [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/): By default, Docker Desktop doesn't require sign-in. You can configure settings to enforce this and ensure your developers sign in to your Docker organization.
* [SSO](https://docs.docker.com/enterprise/security/single-sign-on/): Without SSO, user management in a Docker organization is manual. Setting up an SSO connection between your identity provider and Docker ensures compliance with your security policy and automates user provisioning. Adding SCIM further automates user provisioning and de-provisioning.
* General and security settings: Configuring key settings ensures smooth onboarding and usage of Docker products within your environment. You can also enable security features based on your company's specific security needs.

## [Who needs to be involved](#who-needs-to-be-involved)

* Docker organization owner: Must be involved in the process and is required for several key steps
* DNS team: Needed during the SSO setup to verify the company domain
* MDM team: Responsible for distributing Docker-specific configuration files to developer machines
* Identity Provider team: Required for configuring the identity provider and establishing the SSO connection during setup
* Development lead: A development lead with knowledge of Docker configurations to help establish a baseline for developer settings
* IT team: An IT representative familiar with company desktop policies to assist with aligning Docker configuration to those policies
* Infosec: A security team member with knowledge of company development security policies to help configure security features
* Docker testers: A small group of developers to test the new settings and configurations before full deployment

## [Tools integration](#tools-integration)

This guide covers integration with:

* Okta
* Entra ID SAML 2.0
* Azure Connect (OIDC)
* MDM solutions like Intune

## [Modules](#modules)

1. [Communication and information gathering](https://docs.docker.com/guides/admin-set-up/comms-and-info-gathering/)

   Gather your company's requirements from key stakeholders and communicate to your developers.

2. [Finalize plans and begin setup](https://docs.docker.com/guides/admin-set-up/finalize-plans-and-setup/)

   Collaborate with your MDM team to distribute configurations and set up SSO and Docker product trials.

3. [Testing](https://docs.docker.com/guides/admin-set-up/testing/)

   Test your Docker setup.

4. [Deploy your Docker setup](https://docs.docker.com/guides/admin-set-up/deploy/)

   Deploy your Docker setup across your company.

----
url: https://docs.docker.com/reference/cli/sbx/secret/rm/
----

# sbx secret rm

| Description | Remove a secret                                   |
| ----------- | ------------------------------------------------- |
| Usage       | `sbx secret rm [-g \| SANDBOX] [SERVICE] [flags]` |

## [Options](#options)

| Option         | Default | Description                                      |
| -------------- | ------- | ------------------------------------------------ |
| `-f, --force`  |         | Delete without confirmation prompt               |
| `-g, --global` |         | Use global secret scope                          |
| `--registry`   |         | Registry hostname to remove pull credentials for |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Remove a global secret
sbx secret rm -g github

# Remove a sandbox-scoped secret
sbx secret rm my-sandbox openai

# Remove without confirmation prompt
sbx secret rm -g github -f

# Remove OpenAI or Anthropic credential(s) from global scope (OAuth and/or API key)
sbx secret rm -g openai
sbx secret rm -g anthropic

# Remove registry pull credentials (removes host-only and global entries)
sbx secret rm --registry ghcr.io -f

# Remove only the global (all-sandboxes) registry credential
sbx secret rm -g --registry ghcr.io -f
```

----
url: https://docs.docker.com/reference/api/engine/version/v1.50/
----

# Docker Engine API v1.50 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.50.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.50.yaml)

# Docker Engine API (1.50)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.50.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.50) is used. For example, calling `/info` is the same as calling `/v1.50/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means the server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.50/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.50/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.50/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf",
"Created": "2025-02-17T17:43:39.64001363Z",
"Path": "/bin/sh",
"Args": [
"-c",
"exit 9"
],
"State": {
"Status": "running",
"Running": true,
"Paused": false,
"Restarting": false,
"OOMKilled": false,
"Dead": false,
"Pid": 1234,
"ExitCode": 0,
"Error": "string",
"StartedAt": "2020-01-06T09:06:59.461876391Z",
"FinishedAt": "2020-01-06T09:07:59.461876391Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2020-01-04T10:44:24.496525531Z",
"End": "2020-01-04T10:45:21.364524523Z",
"ExitCode": 0,
"Output": "string"
}
]
}
},
"Image": "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782",
"ResolvConfPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/resolv.conf",
"HostnamePath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hostname",
"HostsPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hosts",
"LogPath": "/var/lib/docker/containers/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59-json.log",
"Name": "/funny_chatelet",
"RestartCount": 0,
"Driver": "overlayfs",
"Platform": "linux",
"ImageManifestDescriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"MountLabel": "",
"ProcessLabel": "",
"AppArmorProfile": "",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"CpuShares": 0,
"Memory": 0,
"CgroupParent": "string",
"BlkioWeight": 1000,
"BlkioWeightDevice": [
{
"Path": "string",
"Weight": 0
}
],
"BlkioDeviceReadBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceReadIOps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteIOps": [
{
"Path": "string",
"Rate": 0
}
],
"CpuPeriod": 0,
"CpuQuota": 0,
"CpuRealtimePeriod": 0,
"CpuRealtimeRuntime": 0,
"CpusetCpus": "0-3",
"CpusetMems": "string",
"Devices": [
{
"PathOnHost": "/dev/deviceName",
"PathInContainer": "/dev/deviceName",
"CgroupPermissions": "mrw"
}
],
"DeviceCgroupRules": [
"c 13:* rwm"
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"KernelMemoryTCP": 0,
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 100,
"NanoCpus": 0,
"OomKillDisable": true,
"Init": true,
"PidsLimit": 0,
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
],
"CpuCount": 0,
"CpuPercent": 0,
"IOMaximumIOps": 0,
"IOMaximumBandwidth": 0,
"Binds": [
"string"
],
"ContainerIDFile": "",
"LogConfig": {
"Type": "local",
"Config": {
"max-file": "5",
"max-size": "10m"
}
},
"NetworkMode": "string",
"PortBindings": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"VolumeDriver": "string",
"VolumesFrom": [
"string"
],
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"ConsoleSize": [
80,
64
],
"Annotations": {
"property1": "string",
"property2": "string"
},
"CapAdd": [
"string"
],
"CapDrop": [
"string"
],
"CgroupnsMode": "private",
"Dns": [
"string"
],
"DnsOptions": [
"string"
],
"DnsSearch": [
"string"
],
"ExtraHosts": [
"string"
],
"GroupAdd": [
"string"
],
"IpcMode": "string",
"Cgroup": "string",
"Links": [
"string"
],
"OomScoreAdj": 500,
"PidMode": "string",
"Privileged": true,
"PublishAllPorts": true,
"ReadonlyRootfs": true,
"SecurityOpt": [
"string"
],
"StorageOpt": {
"property1": "string",
"property2": "string"
},
"Tmpfs": {
"property1": "string",
"property2": "string"
},
"UTSMode": "string",
"UsernsMode": "string",
"ShmSize": 0,
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Runtime": "string",
"Isolation": "default",
"MaskedPaths": [
"/proc/asound",
"/proc/acpi",
"/proc/kcore",
"/proc/keys",
"/proc/latency_stats",
"/proc/timer_list",
"/proc/timer_stats",
"/proc/sched_debug",
"/proc/scsi",
"/sys/firmware",
"/sys/devices/virtual/powercap"
],
"ReadonlyPaths": [
"/proc/bus",
"/proc/fs",
"/proc/irq",
"/proc/sys",
"/proc/sysrq-trigger"
]
},
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"SizeRw": "122880",
"SizeRootFs": "1653948416",
"Mounts": [
{
"Type": "volume",
"Name": "myvolume",
"Source": "/var/lib/docker/volumes/myvolume/_data",
"Destination": "/usr/share/nginx/html/",
"Driver": "local",
"Mode": "z",
"RW": true,
"Propagation": ""
}
],
"Config": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"NetworkSettings": {
"Bridge": "docker0",
"SandboxID": "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": "",
"Ports": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"SandboxKey": "/var/run/docker/netns/8ab54b426c38",
"SecondaryIPAddresses": [
{
"Addr": "string",
"PrefixLen": 0
}
],
"SecondaryIPv6Addresses": [
{
"Addr": "string",
"PrefixLen": 0
}
],
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"MacAddress": "02:42:ac:11:00:04",
"Networks": {
"property1": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
},
"property2": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
}
}
}
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.50/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": {
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
]
},
"Processes": {
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.50/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.50/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.50/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.50/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"name": "boring_wozniak",
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"read": "2025-01-16T13:55:22.165243637Z",
"preread": "2025-01-16T13:55:21.160452595Z",
"pids_stats": {
"current": 5,
"limit": "18446744073709551615"
},
"blkio_stats": {
"io_service_bytes_recursive": [
{
"major": 254,
"minor": 0,
"op": "read",
"value": 7593984
},
{
"major": 254,
"minor": 0,
"op": "write",
"value": 100
}
],
"io_serviced_recursive": null,
"io_queue_recursive": null,
"io_service_time_recursive": null,
"io_wait_time_recursive": null,
"io_merged_recursive": null,
"io_time_recursive": null,
"sectors_recursive": null
},
"num_procs": 16,
"storage_stats": {
"read_count_normalized": 7593984,
"read_size_bytes": 7593984,
"write_count_normalized": 7593984,
"write_size_bytes": 7593984
},
"cpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"memory_stats": {
"usage": 0,
"max_usage": 0,
"stats": {
"active_anon": 1572864,
"active_file": 5115904,
"anon": 1572864,
"anon_thp": 0,
"file": 7626752,
"file_dirty": 0,
"file_mapped": 2723840,
"file_writeback": 0,
"inactive_anon": 0,
"inactive_file": 2510848,
"kernel_stack": 16384,
"pgactivate": 0,
"pgdeactivate": 0,
"pgfault": 2042,
"pglazyfree": 0,
"pglazyfreed": 0,
"pgmajfault": 45,
"pgrefill": 0,
"pgscan": 0,
"pgsteal": 0,
"shmem": 0,
"slab": 1180928,
"slab_reclaimable": 725576,
"slab_unreclaimable": 455352,
"sock": 0,
"thp_collapse_alloc": 0,
"thp_fault_alloc": 1,
"unevictable": 0,
"workingset_activate": 0,
"workingset_nodereclaim": 0,
"workingset_refault": 0
},
"failcnt": 0,
"limit": 8217579520,
"commitbytes": 0,
"commitpeakbytes": 0,
"privateworkingset": 0
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.50/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.50/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.50/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.50/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.50/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime.This field is omitted when empty.                         |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.50/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"Published ports are discarded when using host network mode"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.50/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.50/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.50/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.50/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.50/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.50/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.50/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.50/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.50/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.50/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.50/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |
| manifests   | booleanDefault: falseInclude `Manifests` in the image summary.                                                                                                                                                                                                                                                                                                                                       |

### Responses

/v1.50/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2,
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
}
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.50/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| keep-storage   | integer \<int64>Amount of disk space in bytes to keep for cache> **Deprecated**: This parameter is deprecated and has been renamed to "reserved-space". It is kept for backward compatibility and will be removed in API v1.52.                                                                                                                                                                                                                                          |
| reserved-space | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| max-used-space | integer \<int64>Maximum amount of disk space allowed to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                   |
| min-free-space | integer \<int64>Target amount of free disk space after pruning                                                                                                                                                                                                                                                                                                                                                                                                           |
| all            | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters        | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.50/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. If the name includes a tag or digest, specific behavior applies:- If only `fromImage` includes a tag, that tag is used.
- If both `fromImage` and `tag` are provided, `tag` takes precedence.
- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.
- If neither a tag nor digest is specified, all tags are pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.50/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| manifests | booleanDefault: falseInclude Manifests in the image summary.The `manifests` and `platform` options are mutually exclusive, and an error is produced if both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show inspect. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.The `platform` and `manifests` options are mutually exclusive, and an error is produced if both are set.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.50/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"DockerVersion": "27.0.1",
"Author": "",
"Config": {
"User": "web:web",
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show the history for. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.50/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag      | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed.                                                                                                                                                                                                                                                                                                                   |
| platform | stringJSON-encoded OCI platform to select the platform-variant to push. If not provided, all available variants will attempt to be pushed.If the daemon provides a multi-platform image store, this selects the platform-variant to push to the registry. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.50/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.50/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|           |                                                                                                                                                     |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| force     | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags                                              |
| noprune   | booleanDefault: falseDo not delete untagged parent images                                                                                           |
| platforms | Array of stringsSelect platform-specific content to delete. Multiple values are accepted. Each platform is a OCI platform encoded as a JSON string. |

### Responses

/v1.50/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                   |
| limit        | integerMaximum number of results to return                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.50/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.50/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.50/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.50/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| names    | Array of stringsImage names to filter by                                                                                                                                                                                                                                                 |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.50/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| quiet    | booleanDefault: falseSuppress progress details during load.                                                                                                                                                                                                                              |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be load if the image is multi-platform. If not provided, the full multi-platform image will be loaded.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.50/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.50/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv4": true,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.50/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv4": true,
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.50/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|              |                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired | stringThe network's name.                                                                                                                                                                                                              |
| Driver       | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope        | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal     | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable   | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress      | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly   | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|              | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|              | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv4   | booleanEnable IPv4 on the network.                                                                                                                                                                                                     |
| EnableIPv6   | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|              | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|              | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.50/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv4": true,
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.50/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
},
"MacAddress": "02:42:ac:12:05:02",
"Priority": 100
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.50/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.50/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.50/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.50/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.50/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.50/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.50/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.50/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.50/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.50/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.50/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.50/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.50/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.50/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.50/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.50/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.50/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.50/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.50/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.50/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.50/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.50/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.50/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.50/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.50/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.50/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.50/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.50/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.50/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.50/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.50/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.50/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.50/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.50/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.50/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.50/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.50/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.50/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.50/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.50/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.50/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.50/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.50/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.50/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.50/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.50/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.50/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.50/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.50/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.50/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.50/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.50/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.50/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.50/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.50/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "6.8.0-31-generic",
"OperatingSystem": "Ubuntu 24.04 LTS",
"OSVersion": "24.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "27.0.1",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"FirewallBackend": {
"Driver": "nftables",
"Info": [ [
"ReloadedAt",
"2025-01-01T00:00:00Z"
]
]
},
"DiscoveredDevices": [
{
"Source": "cdi",
"ID": "vendor.com/gpu=0"
}
],
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
],
"Containerd": {
"Address": "/run/containerd/containerd.sock",
"Namespaces": {
"Containers": "moby",
"Plugins": "plugins.moby"
}
}
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.50/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "27.0.1",
"Details": { }
}
],
"Version": "27.0.1",
"ApiVersion": "1.47",
"MinAPIVersion": "1.24",
"GitCommit": "48a66213fe",
"GoVersion": "go1.22.7",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "6.8.0-31-generic",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.50/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.50/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.50/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|      |                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |

### Responses

/v1.50/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parents": [ ],
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parents": [
"ndlpt0hhvkqcdfkputsk4cq9c"
],
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.50/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.50/session

----
url: https://docs.docker.com/get-started/docker-concepts/building-images/multi-stage-builds/
----

# Multi-stage builds

***

Table of contents

***

## [Explanation](#explanation)

In a traditional build, all build instructions are executed in sequence, and in a single build container: downloading dependencies, compiling code, and packaging the application. All those layers end up in your final image. This approach works, but it leads to bulky images carrying unnecessary weight and increasing your security risks. This is where multi-stage builds come in.

Multi-stage builds introduce multiple stages in your Dockerfile, each with a specific purpose. Think of it like the ability to run different parts of a build in multiple different environments, concurrently. By separating the build environment from the final runtime environment, you can significantly reduce the image size and attack surface. This is especially beneficial for applications with large build dependencies.

Multi-stage builds are recommended for all types of applications.

* For interpreted languages, like JavaScript or Ruby or Python, you can build and minify your code in one stage, and copy the production-ready files to a smaller runtime image. This optimizes your image for deployment.
* For compiled languages, like C or Go or Rust, multi-stage builds let you compile in one stage and copy the compiled binaries into a final runtime image. No need to bundle the entire compiler in your final image.

Here's a simplified example of a multi-stage build structure using pseudo-code. Notice there are multiple `FROM` statements and a new `AS <stage-name>`. In addition, the `COPY` statement in the second stage is copying `--from` the previous stage.

```dockerfile
# Stage 1: Build Environment
FROM builder-image AS build-stage 
# Install build tools (e.g., Maven, Gradle)
# Copy source code
# Build commands (e.g., compile, package)

# Stage 2: Runtime environment
FROM runtime-image AS final-stage  
#  Copy application artifacts from the build stage (e.g., JAR file)
COPY --from=build-stage /path/in/build/stage /path/to/place/in/final/stage
# Define runtime configuration (e.g., CMD, ENTRYPOINT) 
```

This Dockerfile uses two stages:

* The build stage uses a base image containing build tools needed to compile your application. It includes commands to install build tools, copy source code, and execute build commands.
* The final stage uses a smaller base image suitable for running your application. It copies the compiled artifacts (a JAR file, for example) from the build stage. Finally, it defines the runtime configuration (using `CMD` or `ENTRYPOINT`) for starting your application.

## [Try it out](#try-it-out)

In this hands-on guide, you'll unlock the power of multi-stage builds to create lean and efficient Docker images for a sample Java application. You'll use a simple “Hello World” Spring Boot-based application built with Maven as your example.

1. [Download and install](https://www.docker.com/products/docker-desktop/) Docker Desktop.

2. Open this [pre-initialized project](https://start.spring.io/#!type=maven-project\&language=java\&platformVersion=4.0.1\&packaging=jar\&configurationFileFormat=properties\&jvmVersion=21\&groupId=com.example\&artifactId=spring-boot-docker\&name=spring-boot-docker\&description=Demo%20project%20for%20Spring%20Boot\&packageName=com.example.spring-boot-docker\&dependencies=web) to generate a ZIP file. Here’s how that looks:

   [Spring Initializr](https://start.spring.io/) is a quickstart generator for Spring projects. It provides an extensible API to generate JVM-based projects with implementations for several common concepts — like basic language generation for Java, Kotlin, Groovy, and Maven.

   Select **Generate** to create and download the zip file for this project.

   For this demonstration, you’ve paired Maven build automation with Java, a Spring Web dependency, and Java 21 for your metadata.

3. Navigate the project directory. Once you unzip the file, you'll see the following project directory structure:

   ```plaintext
   spring-boot-docker
   ├── HELP.md
   ├── mvnw
   ├── mvnw.cmd
   ├── pom.xml
   └── src
       ├── main
       │   ├── java
       │   │   └── com
       │   │       └── example
       │   │           └── spring_boot_docker
       │   │               └── SpringBootDockerApplication.java
       │   └── resources
       │       ├── application.properties
       │       ├── static
       │       └── templates
       └── test
           └── java
               └── com
                   └── example
                       └── spring_boot_docker
                           └── SpringBootDockerApplicationTests.java

   15 directories, 7 files
   ```

   The `src/main/java` directory contains your project's source code, the `src/test/java` directory\
   contains the test source, and the `pom.xml` file is your project’s Project Object Model (POM).

   The `pom.xml` file is the core of a Maven project's configuration. It's a single configuration file that\
   contains most of the information needed to build a customized project. The POM is huge and can seem\
   daunting. Thankfully, you don't yet need to understand every intricacy to use it effectively.

4. Create a RESTful web service that displays "Hello World!".

   Under the `src/main/java/com/example/spring_boot_docker/` directory, you can modify your\
   `SpringBootDockerApplication.java` file with the following content:

   ```java
   package com.example.spring_boot_docker;

   import org.springframework.boot.SpringApplication;
   import org.springframework.boot.autoconfigure.SpringBootApplication;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;


   @RestController
   @SpringBootApplication
   public class SpringBootDockerApplication {

       @RequestMapping("/")
           public String home() {
           return "Hello World";
       }

   	public static void main(String[] args) {
   		SpringApplication.run(SpringBootDockerApplication.class, args);
   	}

   }
   ```

   The `SpringbootDockerApplication.java` file starts by declaring your `com.example.spring_boot_docker` package and importing necessary Spring frameworks. This Java file creates a simple Spring Boot web application that responds with "Hello World" when a user visits its homepage.

### [Create the Dockerfile](#create-the-dockerfile)

Now that you have the project, you’re ready to create the `Dockerfile`.

1. Create a file named `Dockerfile` in the same folder that contains all the other folders and files (like src, pom.xml, etc.).

2. In the `Dockerfile`, define your base image by adding the following line:

   ```dockerfile
   FROM eclipse-temurin:21.0.8_9-jdk-jammy
   ```

3. Now, define the working directory by using the `WORKDIR` instruction. This will specify where future commands will run and the directory files will be copied inside the container image.

   ```dockerfile
   WORKDIR /app
   ```

4. Copy both the Maven wrapper script and your project's `pom.xml` file into the current working directory `/app` within the Docker container.

   ```dockerfile
   COPY .mvn/ .mvn
   COPY mvnw pom.xml ./
   ```

5. Execute a command within the container. It runs the `./mvnw dependency:go-offline` command, which uses the Maven wrapper (`./mvnw`) to download all dependencies for your project without building the final JAR file (useful for faster builds).

   ```dockerfile
   RUN ./mvnw dependency:go-offline
   ```

6. Copy the `src` directory from your project on the host machine to the `/app` directory within the container.

   ```dockerfile
   COPY src ./src
   ```

7. Set the default command to be executed when the container starts. This command instructs the container to run the Maven wrapper (`./mvnw`) with the `spring-boot:run` goal, which will build and execute your Spring Boot application.

   ```dockerfile
   CMD ["./mvnw", "spring-boot:run"]
   ```

   And with that, you should have the following Dockerfile:

   ```dockerfile
   FROM eclipse-temurin:21.0.8_9-jdk-jammy
   WORKDIR /app
   COPY .mvn/ .mvn
   COPY mvnw pom.xml ./
   RUN ./mvnw dependency:go-offline
   COPY src ./src
   CMD ["./mvnw", "spring-boot:run"]
   ```

### [Build the container image](#build-the-container-image)

1. Execute the following command to build the Docker image:

   ```console
   $ docker build -t spring-helloworld .
   ```

2. Check the size of the Docker image by using the `docker images` command:

   ```console
   $ docker images
   ```

   Doing so will produce output like the following:

   ```console
   REPOSITORY          TAG       IMAGE ID       CREATED          SIZE
   spring-helloworld   latest    ff708d5ee194   3 minutes ago    880MB
   ```

   This output shows that your image is 880MB in size. It contains the full JDK, Maven toolchain, and more. In production, you don’t need that in your final image.

### [Run the Spring Boot application](#run-the-spring-boot-application)

1. Now that you have an image built, it's time to run the container.

   ```console
   $ docker run -p 8080:8080 spring-helloworld
   ```

   You'll then see output similar to the following in the container log:

   ```plaintext
   [INFO] --- spring-boot:3.3.4:run (default-cli) @ spring-boot-docker ---
   [INFO] Attaching agents: []

        .   ____          _            __ _ _
       /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
      ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
       \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
        '  |____| .__|_| |_|_| |_\__, | / / / /
       =========|_|==============|___/=/_/_/_/

       :: Spring Boot ::                (v3.3.4)

   2024-09-29T23:54:07.157Z  INFO 159 --- [spring-boot-docker] [           main]
   c.e.s.SpringBootDockerApplication        : Starting SpringBootDockerApplication using Java
   21.0.2 with PID 159 (/app/target/classes started by root in /app)
    ….
   ```

2. Access your “Hello World” page through your web browser at <http://localhost:8080>, or via this curl command:

   ```console
   $ curl localhost:8080
   Hello World
   ```

### [Use multi-stage builds](#use-multi-stage-builds)

1. Consider the following Dockerfile:

   ```dockerfile
   FROM eclipse-temurin:21.0.8_9-jdk-jammy AS builder
   WORKDIR /opt/app
   COPY .mvn/ .mvn
   COPY mvnw pom.xml ./
   RUN ./mvnw dependency:go-offline
   COPY ./src ./src
   RUN ./mvnw clean install

   FROM eclipse-temurin:21.0.8_9-jre-jammy AS final
   WORKDIR /opt/app
   EXPOSE 8080
   COPY --from=builder /opt/app/target/*.jar /opt/app/*.jar
   ENTRYPOINT ["java", "-jar", "/opt/app/*.jar"]
   ```

   Notice that this Dockerfile has been split into two stages.

   * The first stage remains the same as the previous Dockerfile, providing a Java Development Kit (JDK) environment for building the application. This stage is given the name of builder.

   * The second stage is a new stage named `final`. It uses a slimmer `eclipse-temurin:21.0.2_13-jre-jammy` image, containing just the Java Runtime Environment (JRE) needed to run the application. This image provides a Java Runtime Environment (JRE) which is enough for running the compiled application (JAR file).

   > For production use, it's highly recommended that you produce a custom JRE-like runtime using jlink. JRE images are available for all versions of Eclipse Temurin, but `jlink` allows you to create a minimal runtime containing only the necessary Java modules for your application. This can significantly reduce the size and improve the security of your final image. [Refer to this page](https://hub.docker.com/_/eclipse-temurin) for more information.

   With multi-stage builds, a Docker build uses one base image for compilation, packaging, and unit tests and then a separate image for the application runtime. As a result, the final image is smaller in size since it doesn’t contain any development or debugging tools. By separating the build environment from the final runtime environment, you can significantly reduce the image size and increase the security of your final images.

2. Now, rebuild your image and run your ready-to-use production build.

   ```console
   $ docker build -t spring-helloworld-builder .
   ```

   This command builds a Docker image named `spring-helloworld-builder` using the final stage from your `Dockerfile` file located in the current directory.

   > Note
   >
   > In your multi-stage Dockerfile, the final stage (final) is the default target for building. This means that if you don't explicitly specify a target stage using the `--target` flag in the `docker build` command, Docker will automatically build the last stage by default. You could use `docker build -t spring-helloworld-builder --target builder .` to build only the builder stage with the JDK environment.

3. Look at the image size difference by using the `docker images` command:

   ```console
   $ docker images
   ```

   You'll get output similar to the following:

   ```console
   spring-helloworld-builder latest    c5c76cb815c0   24 minutes ago      428MB
   spring-helloworld         latest    ff708d5ee194   About an hour ago   880MB
   ```

   Your final image is just 428 MB, compared to the original build size of 880 MB.

   By optimizing each stage and only including what's necessary, you were able to significantly reduce the overall image size while still achieving the same functionality. This not only improves performance but also makes your Docker images more lightweight, more secure, and easier to manage.

## [Additional resources](#additional-resources)

* [Multi-stage builds](/build/building/multi-stage/)
* [Dockerfile best practices](/develop/develop-images/dockerfile_best-practices/)
* [Base images](/build/building/base-images/)
* [Spring Boot Docker](https://spring.io/guides/topicals/spring-boot-docker)

----
url: https://docs.docker.com/guides/docker-scout/s3c/
----

# Software supply chain security

***

Table of contents

***

The term "software supply chain" refers to the end-to-end process of developing and delivering software, from the development to deployment and maintenance. Software supply chain security, or "S3C" for short, is the practice for protecting the components and processes of the supply chain.

S3C is a fundamental change in how organizations approach software security. Traditionally in the software industry, security and compliance has been mostly an afterthought, left to the software delivery or release phase. With S3C, security is integrated into the entire software development lifecycle, from the inner loop of development and testing, to the outer loop of shipping and monitoring.

Following industry best practices for software supply chain conduct is important because it helps organizations protect their software from security threats, compliance risks, and other vulnerabilities. Implementing a software supply chain security framework improves visibility, collaboration, and traceability of a project across stakeholders. This helps organizations detect, respond to, and remediate threats more effectively.

## [Securing the software supply chain](#securing-the-software-supply-chain)

Building a secure software supply chain involves several key steps, such as:

* Identify the software components and dependencies you use to build and run your applications.
* Automate security testing throughout the software development lifecycle.
* Monitor your software supply chain for security threats.
* Implement security policies that govern how software is built, and the components it contains.

Managing the software supply chain is a complex task, especially in the modern day where software is built using multiple components from different sources. Organizations need to have a clear understanding of the software components they use, and the security risks associated with them.

## [How Docker Scout is different](#how-docker-scout-is-different)

Docker Scout is a platform designed to help organizations secure their software supply chain. It provides tools and services for identifying and managing software assets and policies, and automated remediation of security threats.

Unlike traditional security tools that focus on scheduled, point-in-time scans at specific stages in the software development lifecycle, Docker Scout uses a modern event-driven model that spans the entire software supply chain. This means that when a new vulnerability affecting your images is disclosed, your updated risk assessment is available within seconds, and earlier in the development process.

Docker Scout works by analyzing the composition of your images to create a Software Bill of Materials (SBOM). The SBOM is cross-referenced against the security advisories to identify CVEs that affect your images. Docker Scout integrates with [over 20 different security advisories](https://docs.docker.com/scout/deep-dive/advisory-db-sources/), and updates its vulnerability database in real-time. This ensures that your security posture is represented using the latest available information.

[Software Bill of Materials »](https://docs.docker.com/guides/docker-scout/sbom/)

----
url: https://docs.docker.com/offload/usage/
----

# Docker Offload usage

***

Table of contents

***

Subscription: Docker Offload

Requires: Docker Desktop 4.68 or later

The **Offload activity** page in Docker Home provides visibility into user activity and session metrics for Docker Offload.

To monitor your usage:

1. Sign in to [Docker Home](https://app.docker.com/).
2. If you have access to multiple organizations, select the organization associated with your Docker Offload subscription.
3. Select **Offload** > **Offload activity**.

### [Overview metrics](#overview-metrics)

Key metrics at the top of the page summarize your Docker Offload usage:

* **Total duration**: The total time spent in Offload sessions
* **Average duration**: The average time per Offload session
* **Total sessions**: The total number of Offload sessions
* **Unique images used**: The number of distinct container images used across sessions
* **Unique users**: The number of different users in Docker Offload sessions

### [Filter and export your data](#filter-and-export-your-data)

You can filter the Offload activity data by:

* **Period**: Select a preset time period or choose a custom date range
* **Users**: Organization owners and members with analytics permissions can filter by specific users
* **Additional Filters**: Filter by active sessions and session duration.

Export your session data by selecting the **Download CSV** button. The exported file includes:

* Session ID
* Username
* Image
* Started time
* Ended time
* Duration (in seconds)
* Status
* Container count

The CSV export includes data for your selected date range and user filters, letting you download exactly what you're viewing.

### [Activity cards](#activity-cards)

The following cards provide insights into your Docker Offload usage:

* **Offload usage**: Shows your usage trends over time and cloud resource consumption patterns.
* **Popular images**: Shows the top 4 most frequently used container images in your Docker Offload sessions. Select the card to see more images.
* **Top Offload users**: Shows the top 4 users by session count and duration. Select the card to see more users.

### [Offload sessions](#offload-sessions)

A detailed list of Offload sessions appears following the activity cards. The list:

* Starts with any currently active sessions
* Shows session details including start time, duration, images used, and user information
* Can be filtered using the date and user filters described previously
* Displays **Offload sessions** if you have organization-wide analytics permissions, or **My Offload sessions** if viewing only your own data

Select any session to view more details in a side panel.

----
url: https://docs.docker.com/reference/cli/docker/dhi/attestation/get/
----

# docker dhi attestation get

***

| Description | Get attestation for a Docker Hardened Image   |
| ----------- | --------------------------------------------- |
| Usage       | `docker dhi attestation get <image> <digest>` |

## [Description](#description)

Get an attestation attached to a Docker Hardened Image.

Returns the in-toto statement extracted from the attestation referrer. The referrer digest must be provided to select which attestation to retrieve. Use 'docker dhi attestation list' to discover available attestation digests.

The image can be specified as:

* name:tag (e.g., nginx:1.27)
* namespace/name:tag (e.g., dhi/nginx:1.27)
* name\@sha256:digest (e.g., nginx\@sha256:abc123...)

Examples:

# [Get attestation by referrer digest](#get-attestation-by-referrer-digest)

docker dhi attestation get dhi/nginx:1.27 sha256:abc123...

# [Save attestation to a file](#save-attestation-to-a-file)

docker dhi attestation get dhi/nginx:1.27 sha256:abc123... -o provenance.json

# [Extract only the predicate using jq](#extract-only-the-predicate-using-jq)

docker dhi attestation get dhi/nginx:1.27 sha256:abc123... | jq .predicate

## [Options](#options)

| Option         | Default | Description                            |
| -------------- | ------- | -------------------------------------- |
| `-o, --output` |         | Write output to file instead of stdout |

----
url: https://docs.docker.com/guides/named-entity-recognition/
----

[Build a named entity recognition app](https://docs.docker.com/guides/named-entity-recognition/)

This guide explains how to containerize named entity recognition (NER) models using Docker.

Python AI

20 minutes

[« Back to all guides](/guides/)

# Build a named entity recognition app

***

Table of contents

***

## [Overview](#overview)

This guide walks you through building and running a named entity recognition (NER) application. You'll build the application using Python with spaCy, and then set up the environment and run the application using Docker.

The application processes input text to identify and print named entities, like people, organizations, or locations.

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop.
* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Get the sample application](#get-the-sample-application)

1. Open a terminal, and clone the sample application's repository using the following command.

   ```console
   $ git clone https://github.com/harsh4870/Docker-NLP.git
   ```

2. Verify that you cloned the repository.

   You should see the following files in your `Docker-NLP` directory.

   ```text
   01_sentiment_analysis.py
   02_name_entity_recognition.py
   03_text_classification.py
   04_text_summarization.py
   05_language_translation.py
   entrypoint.sh
   requirements.txt
   Dockerfile
   README.md
   ```

## [Explore the application code](#explore-the-application-code)

The source code for the name recognition application is in the `Docker-NLP/02_name_entity_recognition.py` file. Open `02_name_entity_recognition.py` in a text or code editor to explore its contents in the following steps.

1. Import the required libraries.

   ```python
   import spacy
   ```

   This line imports the `spaCy` library. `spaCy` is a popular library in Python used for natural language processing (NLP).

2. Load the language model.

   ```python
   nlp = spacy.load("en_core_web_sm")
   ```

   Here, the `spacy.load` function loads a language model. The `en_core_web_sm` model is a small English language model. You can use this model for various NLP tasks, including tokenization, part-of-speech tagging, and named entity recognition.

3. Specify the main execution block.

   ```python
   if __name__ == "__main__":
   ```

   This Python idiom ensures that the following code block runs only if this script is the main program. It provides flexibility, allowing the script to function both as a standalone program and as an imported module.

4. Create an infinite loop for continuous input.

   ```python
      while True:
   ```

   This while loop runs indefinitely until it's explicitly broken. It lets the user continuously enter text for entity recognition until they decide to exit.

5. Get user input.

   ```python
   input_text = input("Enter the text for entity recognition (type 'exit' to end): ")
   ```

   This line prompts the user to enter text. The program will then perform entity recognition on this text.

6. Define an exit condition.

   ```python
   if input_text.lower() == 'exit':
      print("Exiting...")
      break
   ```

   If the user types something, the program converts the input to lowercase and compares it to `exit`. If they match, the program prints **Exiting...** and breaks out of the while loop, effectively ending the program.

7. Perform named entity recognition.

   ```python
   doc = nlp(input_text)

   for ent in doc.ents:
      print(f"Entity: {ent.text}, Type: {ent.label_}")
   ```

   * `doc = nlp(input_text)`: Here, the nlp model processes the user-input text. This creates a Doc object which contains various NLP attributes, including identified entities.
   * `for ent in doc.ents:`: This loop iterates over the entities found in the text.
   * `print(f"Entity: {ent.text}, Type: {ent.label_}")`: For each entity, it prints the entity text and its type (like PERSON, ORG, or GPE).

8. Create `requirements.txt`.

   The sample application already contains the `requirements.txt` file to specify the necessary packages that the application imports. Open `requirements.txt` in a code or text editor to explore its contents.

   ```text
   # 02 named_entity_recognition
   spacy==3.7.2

   ...
   ```

   Only the `spacy` package is required for the named recognition application.

## [Explore the application environment](#explore-the-application-environment)

You'll use Docker to run the application in a container. Docker lets you containerize the application, providing a consistent and isolated environment for running it. This means the application will operate as intended within its Docker container, regardless of the underlying system differences.

To run the application in a container, a Dockerfile is required. A Dockerfile is a text document that contains all the commands you would call on the command line to assemble an image. An image is a read-only template with instructions for creating a Docker container.

The sample application already contains a `Dockerfile`. Open the `Dockerfile` in a code or text editor to explore its contents.

The following steps explain each part of the `Dockerfile`. For more details, see the [Dockerfile reference](/reference/dockerfile/).

1. Specify the base image.

   ```dockerfile
   FROM python:3.8-slim
   ```

   This command sets the foundation for the build. `python:3.8-slim` is a lightweight version of the Python 3.8 image, optimized for size and speed. Using this slim image reduces the overall size of your Docker image, leading to quicker downloads and less surface area for security vulnerabilities. This is particularly useful for a Python-based application where you might not need the full standard Python image.

2. Set the working directory.

   ```dockerfile
   WORKDIR /app
   ```

   `WORKDIR` sets the current working directory within the Docker image. By setting it to `/app`, you ensure that all subsequent commands in the Dockerfile (like `COPY` and `RUN`) are executed in this directory. This also helps in organizing your Docker image, as all application-related files are contained in a specific directory.

3. Copy the requirements file into the image.

   ```dockerfile
   COPY requirements.txt /app
   ```

   The `COPY` command transfers the `requirements.txt` file from your local machine into the Docker image. This file lists all Python dependencies required by the application. Copying it into the container lets the next command (`RUN pip install`) install these dependencies inside the image environment.

4. Install the Python dependencies in the image.

   ```dockerfile
   RUN pip install --no-cache-dir -r requirements.txt
   ```

   This line uses `pip`, Python's package installer, to install the packages listed in `requirements.txt`. The `--no-cache-dir` option disables the cache, which reduces the size of the Docker image by not storing the unnecessary cache data.

5. Run additional commands.

   ```dockerfile
   RUN python -m spacy download en_core_web_sm
   ```

   This step is specific to NLP applications that require the spaCy library. It downloads the `en_core_web_sm` model, which is a small English language model for spaCy.

6. Copy the application code into the image.

   ```dockerfile
   COPY *.py /app
   COPY entrypoint.sh /app
   ```

   These commands copy your Python scripts and the `entrypoint.sh` script into the image's `/app` directory. This is crucial because the container needs these scripts to run the application. The `entrypoint.sh` script is particularly important as it dictates how the application starts inside the container.

7. Set permissions for the `entrypoint.sh` script.

   ```dockerfile
   RUN chmod +x /app/entrypoint.sh
   ```

   This command modifies the file permissions of `entrypoint.sh`, making it executable. This step is necessary to ensure that the Docker container can run this script to start the application.

8. Set the entry point.

   ```dockerfile
   ENTRYPOINT ["/app/entrypoint.sh"]
   ```

   The `ENTRYPOINT` instruction configures the container to run `entrypoint.sh` as its default executable. This means that when the container starts, it automatically executes the script.

   You can explore the `entrypoint.sh` script by opening it in a code or text editor. As the sample contains several applications, the script lets you specify which application to run when the container starts.

## [Run the application](#run-the-application)

To run the application using Docker:

1. Build the image.

   In a terminal, run the following command inside the directory of where the `Dockerfile` is located.

   ```console
   $ docker build -t basic-nlp .
   ```

   ```console
   $ docker run -it basic-nlp 02_name_entity_recognition.py
   ```

   The following is a break down of the command:

   * `docker run`: This is the primary command used to run a new container from a Docker image.

   * `-it`: This is a combination of two options:

     * `-i` or `--interactive`: This keeps the standard input (STDIN) open even if not attached. It lets the container remain running in the foreground and be interactive.
     * `-t` or `--tty`: This allocates a pseudo-TTY, essentially simulating a terminal, like a command prompt or a shell. It's what lets you interact with the application inside the container.

   * `basic-nlp`: This specifies the name of the Docker image to use for creating the container. In this case, it's the image named `basic-nlp` that you created with the `docker build` command.

   * `02_name_entity_recognition.py`: This is the script you want to run inside the Docker container. It gets passed to the `entrypoint.sh` script, which runs it when the container starts.

   For more details, see the [docker run CLI reference](/reference/cli/docker/container/run/).

   > Note
   >
   > For Windows users, you may get an error when running the container. Verify that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), then rebuild the image. For more details, see \[Avoid unexpected syntax errors, use Unix style line endings for files in containers]\(/desktop/troubleshoot-and-support/troubleshoot/topics/#Unexpected-syntax-errors-use-Unix-style-line endings-for-files-in-containers).

   You will see the following in your console after the container starts.

   ```console
   Enter the text for entity recognition (type 'exit' to end):
   ```

3. Test the application.

   Enter some information to get the named entity recognition.

   ```console
   Enter the text for entity recognition (type 'exit' to end): Apple Inc. is planning to open a new store in San Francisco. Tim Cook is the CEO of Apple.

   Entity: Apple Inc., Type: ORG
   Entity: San Francisco, Type: GPE
   Entity: Tim Cook, Type: PERSON
   Entity: Apple, Type: ORG
   ```

## [Summary](#summary)

This guide demonstrated how to build and run a named entity recognition application. You learned how to build the application using Python with spaCy, and then set up the environment and run the application using Docker.

Related information:

* [Docker CLI reference](/reference/cli/docker/)
* [Dockerfile reference](/reference/dockerfile/)
* [spaCy](https://spacy.io/)
* [Python documentation](https://docs.python.org/3/)

## [Next steps](#next-steps)

Explore more [natural language processing guides](https://docs.docker.com/guides/).

----
url: https://docs.docker.com/desktop/features/vmm/
----

# Virtual Machine Manager for Docker Desktop on Mac

***

Table of contents

***

Docker Desktop supports multiple Virtual Machine Managers (VMMs) to power the Linux VM that runs containers. You can choose the most suitable option based on your system architecture (Intel or Apple Silicon), performance needs, and feature requirements. This page provides an overview of the available options.

To change the VMM, go to **Settings** > **General** > **Virtual Machine Manager**.

## [Docker VMM](#docker-vmm)

For: Docker Desktop on Mac with Apple Silicon

Docker VMM is a container-optimized hypervisor. By optimizing both the Linux kernel and hypervisor layers, Docker VMM delivers significant performance enhancements across common developer tasks.

Some key performance enhancements provided by Docker VMM include:

* Faster I/O operations: With a cold cache, iterating over a large shared filesystem with `find` is 2x faster than when the Apple Virtualization framework is used.
* Improved caching: With a warm cache, performance can improve by as much as 25x, even surpassing native Mac operations.

These improvements directly impact developers who rely on frequent file access and overall system responsiveness during containerized development. Docker VMM marks a significant leap in speed, enabling smoother workflows and faster iteration cycles.

> Note
>
> Docker VMM requires a minimum of 4GB of memory to be allocated to the Docker Linux VM. The memory needs to be increased before Docker VMM is enabled, and this can be done from the **Resources** tab in **Settings**.

### [Known issues](#known-issues)

As Docker VMM is still in Beta, there are a few known limitations:

* Docker VMM does not currently support Rosetta, so emulation of amd64 architectures is slow. Docker is exploring potential solutions.
* Certain databases, like MongoDB and Cassandra, may fail when using virtiofs with Docker VMM. This issue is expected to be resolved in a future release.

## [Apple Virtualization framework](#apple-virtualization-framework)

The Apple Virtualization framework is a stable and well-established option for managing virtual machines on Mac. It has been a reliable choice for many Mac users over the years. This framework is best suited for developers who prefer a proven solution with solid performance and broad compatibility.

## [QEMU (Legacy) for Apple Silicon](#qemu-legacy-for-apple-silicon)

> Note
>
> QEMU has been deprecated in versions 4.44 and later. For more information, see the [blog announcement](https://www.docker.com/blog/docker-desktop-for-mac-qemu-virtualization-option-to-be-deprecated-in-90-days/)

QEMU is a legacy virtualization option for Apple Silicon Macs, primarily supported for older use cases.

Docker recommends transitioning to newer alternatives, such as Docker VMM or the Apple Virtualization framework, as they offer superior performance and ongoing support. Docker VMM, in particular, offers substantial speed improvements and a more efficient development environment, making it a compelling choice for developers working with Apple Silicon.

Note that this is not related to using QEMU to emulate non-native architectures in [multi-platform builds](https://docs.docker.com/build/building/multi-platform/#qemu).

## [HyperKit (Legacy) for Intel-based Macs](#hyperkit-legacy-for-intel-based-macs)

> Note
>
> HyperKit is deprecated. Docker recommends switching to the Apple Virtualization framework.

HyperKit is a legacy virtualization option for Intel-based Macs. Docker recommends switching to modern alternatives for better performance and to future-proof your setup.

----
url: https://docs.docker.com/engine/containers/runmetrics/
----

# Runtime metrics

***

Table of contents

***

## [Docker stats](#docker-stats)

You can use the `docker stats` command to live stream a container's runtime metrics. The command supports CPU, memory usage, memory limit, and network IO metrics.

The following is a sample output from the `docker stats` command

```console
$ docker stats redis1 redis2

CONTAINER           CPU %               MEM USAGE / LIMIT     MEM %               NET I/O             BLOCK I/O
redis1              0.07%               796 KB / 64 MB        1.21%               788 B / 648 B       3.568 MB / 512 KB
redis2              0.07%               2.746 MB / 64 MB      4.29%               1.266 KB / 648 B    12.4 MB / 0 B
```

The [`docker stats`](/reference/cli/docker/container/stats/) reference page has more details about the `docker stats` command.

## [Control groups](#control-groups)

Linux Containers rely on [control groups](https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt) which not only track groups of processes, but also expose metrics about CPU, memory, and block I/O usage. You can access those metrics and obtain network usage metrics as well. This is relevant for "pure" LXC containers, as well as for Docker containers.

Control groups are exposed through a pseudo-filesystem. In modern distributions, you should find this filesystem under `/sys/fs/cgroup`. Under that directory, you see multiple sub-directories, called `devices`, `freezer`, `blkio`, and so on. Each sub-directory actually corresponds to a different cgroup hierarchy.

On older systems, the control groups might be mounted on `/cgroup`, without distinct hierarchies. In that case, instead of seeing the sub-directories, you see a bunch of files in that directory, and possibly some directories corresponding to existing containers.

To figure out where your control groups are mounted, you can run:

```console
$ grep cgroup /proc/mounts
```

### [Enumerate cgroups](#enumerate-cgroups)

The file layout of cgroups is significantly different between v1 and v2.

If `/sys/fs/cgroup/cgroup.controllers` is present on your system, you are using v2, otherwise you are using v1. Refer to the subsection that corresponds to your cgroup version.

cgroup v2 is used by default on the following distributions:

* Fedora (since 31)
* Debian GNU/Linux (since 11)
* Ubuntu (since 21.10)

#### [cgroup v1](#cgroup-v1)

You can look into `/proc/cgroups` to see the different control group subsystems known to the system, the hierarchy they belong to, and how many groups they contain.

You can also look at `/proc/<pid>/cgroup` to see which control groups a process belongs to. The control group is shown as a path relative to the root of the hierarchy mountpoint. `/` means the process hasn't been assigned to a group, while `/lxc/pumpkin` indicates that the process is a member of a container named `pumpkin`.

#### [cgroup v2](#cgroup-v2)

On cgroup v2 hosts, the content of `/proc/cgroups` isn't meaningful. See `/sys/fs/cgroup/cgroup.controllers` to the available controllers.

### [Changing cgroup version](#changing-cgroup-version)

Changing cgroup version requires rebooting the entire system.

On systemd-based systems, cgroup v2 can be enabled by adding `systemd.unified_cgroup_hierarchy=1` to the kernel command line. To revert the cgroup version to v1, you need to set `systemd.unified_cgroup_hierarchy=0` instead.

If `grubby` command is available on your system (e.g. on Fedora), the command line can be modified as follows:

```console
$ sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=1"
```

If `grubby` command isn't available, edit the `GRUB_CMDLINE_LINUX` line in `/etc/default/grub` and run `sudo update-grub`.

### [Running Docker on cgroup v2](#running-docker-on-cgroup-v2)

Docker supports cgroup v2 since Docker 20.10. Running Docker on cgroup v2 also requires the following conditions to be satisfied:

* containerd: v1.4 or later
* runc: v1.0.0-rc91 or later
* Kernel: v4.15 or later (v5.2 or later is recommended)

Note that the cgroup v2 mode behaves slightly different from the cgroup v1 mode:

* The default cgroup driver (`dockerd --exec-opt native.cgroupdriver`) is `systemd` on v2, `cgroupfs` on v1.
* The default cgroup namespace mode (`docker run --cgroupns`) is `private` on v2, `host` on v1.
* The `docker run` flag `--oom-kill-disable` is discarded on v2.

### [Find the cgroup for a given container](#find-the-cgroup-for-a-given-container)

For each container, one cgroup is created in each hierarchy. On older systems with older versions of the LXC userland tools, the name of the cgroup is the name of the container. With more recent versions of the LXC tools, the cgroup is `lxc/<container_name>.`

For Docker containers using cgroups, the cgroup name is the full ID or long ID of the container. If a container shows up as ae836c95b4c3 in `docker ps`, its long ID might be something like `ae836c95b4c3c9e9179e0e91015512da89fdec91612f63cebae57df9a5444c79`. You can look it up with `docker inspect` or `docker ps --no-trunc`.

Putting everything together to look at the memory metrics for a Docker container, take a look at the following paths:

* `/sys/fs/cgroup/memory/docker/<longid>/` on cgroup v1, `cgroupfs` driver
* `/sys/fs/cgroup/memory/system.slice/docker-<longid>.scope/` on cgroup v1, `systemd` driver
* `/sys/fs/cgroup/docker/<longid>/` on cgroup v2, `cgroupfs` driver
* `/sys/fs/cgroup/system.slice/docker-<longid>.scope/` on cgroup v2, `systemd` driver

### [Metrics from cgroups: memory, CPU, block I/O](#metrics-from-cgroups-memory-cpu-block-io)

> Note
>
> This section isn't yet updated for cgroup v2. For further information about cgroup v2, refer to [the kernel documentation](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html).

For each subsystem (memory, CPU, and block I/O), one or more pseudo-files exist and contain statistics.

#### [Memory metrics: `memory.stat`](#memory-metrics-memorystat)

Memory metrics are found in the `memory` cgroup. The memory control group adds a little overhead, because it does very fine-grained accounting of the memory usage on your host. Therefore, many distributions chose to not enable it by default. Generally, to enable it, all you have to do is to add some kernel command-line parameters: `cgroup_enable=memory swapaccount=1`.

The metrics are in the pseudo-file `memory.stat`. Here is what it looks like:

```
cache 11492564992
rss 1930993664
mapped_file 306728960
pgpgin 406632648
pgpgout 403355412
swap 0
pgfault 728281223
pgmajfault 1724
inactive_anon 46608384
active_anon 1884520448
inactive_file 7003344896
active_file 4489052160
unevictable 32768
hierarchical_memory_limit 9223372036854775807
hierarchical_memsw_limit 9223372036854775807
total_cache 11492564992
total_rss 1930993664
total_mapped_file 306728960
total_pgpgin 406632648
total_pgpgout 403355412
total_swap 0
total_pgfault 728281223
total_pgmajfault 1724
total_inactive_anon 46608384
total_active_anon 1884520448
total_inactive_file 7003344896
total_active_file 4489052160
total_unevictable 32768
```

The first half (without the `total_` prefix) contains statistics relevant to the processes within the cgroup, excluding sub-cgroups. The second half (with the `total_` prefix) includes sub-cgroups as well.

Some metrics are "gauges", or values that can increase or decrease. For instance, `swap` is the amount of swap space used by the members of the cgroup. Some others are "counters", or values that can only go up, because they represent occurrences of a specific event. For instance, `pgfault` indicates the number of page faults since the creation of the cgroup.

* `cache`

  The amount of memory used by the processes of this control group that can be associated precisely with a block on a block device. When you read from and write to files on disk, this amount increases. This is the case if you use "conventional" I/O (`open`, `read`, `write` syscalls) as well as mapped files (with `mmap`). It also accounts for the memory used by `tmpfs` mounts, though the reasons are unclear.

* `rss`

  The amount of memory that doesn't correspond to anything on disk: stacks, heaps, and anonymous memory maps.

* `mapped_file`

  Indicates the amount of memory mapped by the processes in the control group. It doesn't give you information about how much memory is used; it rather tells you how it's used.

* `pgfault`, `pgmajfault`

  Indicate the number of times that a process of the cgroup triggered a "page fault" and a "major fault", respectively. A page fault happens when a process accesses a virtual memory page that is not currently mapped to a physical memory frame. This is a normal part of memory management. For example, a page fault occurs when the process reads from a memory zone that has been swapped out, or that corresponds to a memory-mapped file: in that case, the kernel loads the page from disk and lets the CPU complete the memory access. It also happens when the process writes to a copy-on-write memory zone: the kernel duplicates the memory page and resumes the write operation on the process's own copy of the page. "Major" faults happen when the kernel needs to read data from disk. When it duplicates an existing page, or allocates an empty page, it's a regular (or "minor") fault.

* `swap`

  The amount of swap currently used by the processes in this cgroup.

* `active_anon`, `inactive_anon`

  The amount of anonymous memory that has been identified has respectively *active* and *inactive* by the kernel. "Anonymous" memory is the memory that is *not* linked to disk pages. In other words, that's the equivalent of the rss counter described above. In fact, the very definition of the rss counter is `active_anon` + `inactive_anon` - `tmpfs` (where tmpfs is the amount of memory used up by `tmpfs` filesystems mounted by this control group). Now, what's the difference between "active" and "inactive"? Pages are initially "active"; and at regular intervals, the kernel sweeps over the memory, and tags some pages as "inactive". Whenever they're accessed again, they're immediately re-tagged "active". When the kernel is almost out of memory, and time comes to swap out to disk, the kernel swaps "inactive" pages.

* `active_file`, `inactive_file`

  Cache memory, with *active* and *inactive* similar to the *anon* memory above. The exact formula is `cache` = `active_file` + `inactive_file` + `tmpfs`. The exact rules used by the kernel to move memory pages between active and inactive sets are different from the ones used for anonymous memory, but the general principle is the same. When the kernel needs to reclaim memory, it's cheaper to reclaim a clean (=non modified) page from this pool, since it can be reclaimed immediately (while anonymous pages and dirty/modified pages need to be written to disk first).

* `unevictable`

  The amount of memory that cannot be reclaimed; generally, it accounts for memory that has been "locked" with `mlock`. It's often used by crypto frameworks to make sure that secret keys and other sensitive material never gets swapped out to disk.

* `memory_limit`, `memsw_limit`

  These aren't really metrics, but a reminder of the limits applied to this cgroup. The first one indicates the maximum amount of physical memory that can be used by the processes of this control group; the second one indicates the maximum amount of RAM+swap.

Accounting for memory in the page cache is very complex. If two processes in different control groups both read the same file (ultimately relying on the same blocks on disk), the corresponding memory charge is split between the control groups. It's nice, but it also means that when a cgroup is terminated, it could increase the memory usage of another cgroup, because they're not splitting the cost anymore for those memory pages.

### [CPU metrics: `cpuacct.stat`](#cpu-metrics-cpuacctstat)

Now that we've covered memory metrics, everything else is simple in comparison. CPU metrics are in the `cpuacct` controller.

For each container, a pseudo-file `cpuacct.stat` contains the CPU usage accumulated by the processes of the container, broken down into `user` and `system` time. The distinction is:

* `user` time is the amount of time a process has direct control of the CPU, executing process code.
* `system` time is the time the kernel is executing system calls on behalf of the process.

Those times are expressed in ticks of 1/100th of a second, also called "user jiffies". There are `USER_HZ` *"jiffies"* per second, and on x86 systems, `USER_HZ` is 100. Historically, this mapped exactly to the number of scheduler "ticks" per second, but higher frequency scheduling and [tickless kernels](https://lwn.net/Articles/549580/) have made the number of ticks irrelevant.

#### [Block I/O metrics](#block-io-metrics)

Block I/O is accounted in the `blkio` controller. Different metrics are scattered across different files. While you can find in-depth details in the [blkio-controller](https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt) file in the kernel documentation, here is a short list of the most relevant ones:

* `blkio.sectors`

  Contains the number of 512-bytes sectors read and written by the processes member of the cgroup, device by device. Reads and writes are merged in a single counter.

* `blkio.io_service_bytes`

  Indicates the number of bytes read and written by the cgroup. It has 4 counters per device, because for each device, it differentiates between synchronous vs. asynchronous I/O, and reads vs. writes.

* `blkio.io_serviced`

  The number of I/O operations performed, regardless of their size. It also has 4 counters per device.

* `blkio.io_queued`

  Indicates the number of I/O operations currently queued for this cgroup. In other words, if the cgroup isn't doing any I/O, this is zero. The opposite is not true. In other words, if there is no I/O queued, it doesn't mean that the cgroup is idle (I/O-wise). It could be doing purely synchronous reads on an otherwise quiescent device, which can therefore handle them immediately, without queuing. Also, while it's helpful to figure out which cgroup is putting stress on the I/O subsystem, keep in mind that it's a relative quantity. Even if a process group doesn't perform more I/O, its queue size can increase just because the device load increases because of other devices.

### [Network metrics](#network-metrics)

Network metrics aren't exposed directly by control groups. There is a good explanation for that: network interfaces exist within the context of *network namespaces*. The kernel could probably accumulate metrics about packets and bytes sent and received by a group of processes, but those metrics wouldn't be very useful. You want per-interface metrics (because traffic happening on the local `lo` interface doesn't really count). But since processes in a single cgroup can belong to multiple network namespaces, those metrics would be harder to interpret: multiple network namespaces means multiple `lo` interfaces, potentially multiple `eth0` interfaces, etc.; so this is why there is no easy way to gather network metrics with control groups.

Instead you can gather network metrics from other sources.

#### [iptables](#iptables)

iptables (or rather, the netfilter framework for which iptables is just an interface) can do some serious accounting.

For instance, you can setup a rule to account for the outbound HTTP traffic on a web server:

```console
$ iptables -I OUTPUT -p tcp --sport 80
```

There is no `-j` or `-g` flag, so the rule just counts matched packets and goes to the following rule.

Later, you can check the values of the counters, with:

```console
$ iptables -nxvL OUTPUT
```

Technically, `-n` isn't required, but it prevents iptables from doing DNS reverse lookups, which are probably useless in this scenario.

Counters include packets and bytes. If you want to setup metrics for container traffic like this, you could execute a `for` loop to add two `iptables` rules per container IP address (one in each direction), in the `FORWARD` chain. This only meters traffic going through the NAT layer; you also need to add traffic going through the userland proxy.

Then, you need to check those counters on a regular basis. If you happen to use `collectd`, there is a [nice plugin](https://collectd.org/wiki/index.php/Table_of_Plugins) to automate iptables counters collection.

#### [Interface-level counters](#interface-level-counters)

Since each container has a virtual Ethernet interface, you might want to check directly the TX and RX counters of this interface. Each container is associated to a virtual Ethernet interface in your host, with a name like `vethKk8Zqi`. Figuring out which interface corresponds to which container is, unfortunately, difficult.

But for now, the best way is to check the metrics *from within the containers*. To accomplish this, you can run an executable from the host environment within the network namespace of a container using **ip-netns magic**.

The `ip-netns exec` command allows you to execute any program (present in the host system) within any network namespace visible to the current process. This means that your host can enter the network namespace of your containers, but your containers can't access the host or other peer containers. Containers can interact with their sub-containers, though.

The exact format of the command is:

```console
$ ip netns exec <nsname> <command...>
```

For example:

```console
$ ip netns exec mycontainer netstat -i
```

`ip netns` finds the `mycontainer` container by using namespaces pseudo-files. Each process belongs to one network namespace, one PID namespace, one `mnt` namespace, etc., and those namespaces are materialized under `/proc/<pid>/ns/`. For example, the network namespace of PID 42 is materialized by the pseudo-file `/proc/42/ns/net`.

When you run `ip netns exec mycontainer ...`, it expects `/var/run/netns/mycontainer` to be one of those pseudo-files. (Symlinks are accepted.)

In other words, to execute a command within the network namespace of a container, we need to:

* Find out the PID of any process within the container that we want to investigate;
* Create a symlink from `/var/run/netns/<somename>` to `/proc/<thepid>/ns/net`
* Execute `ip netns exec <somename> ....`

Review [Enumerate Cgroups](#enumerate-cgroups) for how to find the cgroup of an in-container process whose network usage you want to measure. From there, you can examine the pseudo-file named `tasks`, which contains all the PIDs in the cgroup (and thus, in the container). Pick any one of the PIDs.

Putting everything together, if the "short ID" of a container is held in the environment variable `$CID`, then you can do this:

```console
$ TASKS=/sys/fs/cgroup/devices/docker/$CID*/tasks
$ PID=$(head -n 1 $TASKS)
$ mkdir -p /var/run/netns
$ ln -sf /proc/$PID/ns/net /var/run/netns/$CID
$ ip netns exec $CID netstat -i
```

## [Tips for high-performance metric collection](#tips-for-high-performance-metric-collection)

Running a new process each time you want to update metrics is (relatively) expensive. If you want to collect metrics at high resolutions, and/or over a large number of containers (think 1000 containers on a single host), you don't want to fork a new process each time.

Here is how to collect metrics from a single process. You need to write your metric collector in C (or any language that lets you do low-level system calls). You need to use a special system call, `setns()`, which lets the current process enter any arbitrary namespace. It requires, however, an open file descriptor to the namespace pseudo-file (remember: that's the pseudo-file in `/proc/<pid>/ns/net`).

However, there is a catch: you must not keep this file descriptor open. If you do, when the last process of the control group exits, the namespace isn't destroyed, and its network resources (like the virtual interface of the container) stays around forever (or until you close that file descriptor).

The right approach would be to keep track of the first PID of each container, and re-open the namespace pseudo-file each time.

## [Collect metrics when a container exits](#collect-metrics-when-a-container-exits)

Sometimes, you don't care about real time metric collection, but when a container exits, you want to know how much CPU, memory, etc. it has used.

Docker makes this difficult because it relies on `lxc-start`, which carefully cleans up after itself. It is usually easier to collect metrics at regular intervals, and this is the way the `collectd` LXC plugin works.

But, if you'd still like to gather the stats when a container stops, here is how:

For each container, start a collection process, and move it to the control groups that you want to monitor by writing its PID to the tasks file of the cgroup. The collection process should periodically re-read the tasks file to check if it's the last process of the control group. (If you also want to collect network statistics as explained in the previous section, you should also move the process to the appropriate network namespace.)

When the container exits, `lxc-start` attempts to delete the control groups. It fails, since the control group is still in use; but that's fine. Your process should now detect that it is the only one remaining in the group. Now is the right time to collect all the metrics you need!

Finally, your process should move itself back to the root control group, and remove the container control group. To remove a control group, just `rmdir` its directory. It's counter-intuitive to `rmdir` a directory as it still contains files; but remember that this is a pseudo-filesystem, so usual rules don't apply. After the cleanup is done, the collection process can exit safely.

----
url: https://docs.docker.com/ai/docker-agent/reference/config/
----

# Configuration file reference

***

Table of contents

***

This reference documents the YAML configuration file format for agents using Docker Agent. It covers file structure, agent parameters, model configuration, toolset setup, and RAG sources.

For detailed documentation of each toolset's capabilities and specific options, see the [Toolsets reference](https://docs.docker.com/ai/docker-agent/reference/toolsets/).

## [File structure](#file-structure)

A configuration file has four top-level sections:

```yaml
agents: # Required - agent definitions
  root:
    model: anthropic/claude-sonnet-4-5
    description: What this agent does
    instruction: How it should behave

models: # Optional - model configurations
  custom_model:
    provider: openai
    model: gpt-5

rag: # Optional - RAG sources
  docs:
    docs: [./documents]
    strategies: [...]

metadata: # Optional - author, license, readme
  author: Your Name
```

## [Agents](#agents)

| Property               | Type    | Description                                    | Required |
| ---------------------- | ------- | ---------------------------------------------- | -------- |
| `model`                | string  | Model reference or name                        | Yes      |
| `description`          | string  | Brief description of agent's purpose           | No       |
| `instruction`          | string  | Detailed behavior instructions                 | Yes      |
| `sub_agents`           | array   | Agent names for task delegation                | No       |
| `handoffs`             | array   | Agent names for conversation handoff           | No       |
| `toolsets`             | array   | Available tools                                | No       |
| `welcome_message`      | string  | Message displayed on start                     | No       |
| `add_date`             | boolean | Include current date in context                | No       |
| `add_environment_info` | boolean | Include working directory, OS, Git info        | No       |
| `add_prompt_files`     | array   | Prompt file paths to include                   | No       |
| `max_iterations`       | integer | Maximum tool call loops (unlimited if not set) | No       |
| `num_history_items`    | integer | Conversation history limit                     | No       |
| `code_mode_tools`      | boolean | Enable Code Mode for tools                     | No       |
| `commands`             | object  | Named prompts accessible via `/command_name`   | No       |
| `structured_output`    | object  | JSON schema for structured responses           | No       |
| `rag`                  | array   | RAG source names                               | No       |

### [Task delegation versus conversation handoff](#task-delegation-versus-conversation-handoff)

Agents support two different delegation mechanisms. Choose based on whether you need task results or conversation control.

#### [Sub\_agents: Hierarchical task delegation](#sub_agents-hierarchical-task-delegation)

Use `sub_agents` for hierarchical task delegation. The parent agent assigns a specific task to a child agent using the `transfer_task` tool. The child executes in its own context and returns results. The parent maintains control and can delegate to multiple agents in sequence.

This works well for structured workflows where you need to combine results from specialists, or when tasks have clear boundaries. Each delegated task runs independently and reports back to the parent.

**Example:**

```yaml
agents:
  root:
    sub_agents: [researcher, analyst]
    instruction: |
      Delegate research to researcher.
      Delegate analysis to analyst.
      Combine results and present findings.
```

Root calls: `transfer_task(agent="researcher", task="Find pricing data")`. The researcher completes the task and returns results to root.

#### [Handoffs: Conversation transfer](#handoffs-conversation-transfer)

Use `handoffs` to transfer conversation control to a different agent. When an agent uses the `handoff` tool, the new agent takes over completely. The original agent steps back until someone hands back to it.

This works well when different agents should own different parts of an ongoing conversation, or when specialists need to collaborate as peers without a coordinator managing every step.

**Example:**

```yaml
agents:
  generalist:
    handoffs: [database_expert, security_expert]
    instruction: |
      Help with general development questions.
      If the conversation moves to database optimization,
      hand off to database_expert.
      If security concerns arise, hand off to security_expert.

  database_expert:
    handoffs: [generalist, security_expert]
    instruction: Handle database design and optimization.

  security_expert:
    handoffs: [generalist, database_expert]
    instruction: Review code for security vulnerabilities.
```

When the user asks about query performance, generalist executes: `handoff(agent="database_expert")`. The database expert now owns the conversation and can continue working with the user directly, or hand off to security\_expert if the discussion shifts to SQL injection concerns.

### [Commands](#commands)

Named prompts users invoke with `/command_name`. Supports JavaScript template literals with `${env.VARIABLE}` for environment variables:

```yaml
commands:
  greet: "Say hello to ${env.USER}"
  analyze: "Analyze ${env.PROJECT_NAME || 'demo'}"
```

Run with: `docker agent run config.yaml /greet`

### [Structured output](#structured-output)

Constrain responses to a JSON schema (OpenAI and Gemini only):

```yaml
structured_output:
  name: code_analysis
  strict: true
  schema:
    type: object
    properties:
      issues:
        type: array
        items: { ... }
    required: [issues]
```

## [Models](#models)

| Property              | Type    | Description                                    | Required |
| --------------------- | ------- | ---------------------------------------------- | -------- |
| `provider`            | string  | `openai`, `anthropic`, `google`, `dmr`         | Yes      |
| `model`               | string  | Model name                                     | Yes      |
| `temperature`         | float   | Randomness (0.0-2.0)                           | No       |
| `max_tokens`          | integer | Maximum response length                        | No       |
| `top_p`               | float   | Nucleus sampling (0.0-1.0)                     | No       |
| `frequency_penalty`   | float   | Repetition penalty (-2.0 to 2.0, OpenAI only)  | No       |
| `presence_penalty`    | float   | Topic penalty (-2.0 to 2.0, OpenAI only)       | No       |
| `base_url`            | string  | Custom API endpoint                            | No       |
| `parallel_tool_calls` | boolean | Enable parallel tool execution (default: true) | No       |
| `token_key`           | string  | Authentication token key                       | No       |
| `track_usage`         | boolean | Track token usage                              | No       |
| `thinking_budget`     | mixed   | Reasoning effort (provider-specific)           | No       |
| `provider_opts`       | object  | Provider-specific options                      | No       |

### [Alloy models](#alloy-models)

Use multiple models in rotation by separating names with commas:

```yaml
model: anthropic/claude-sonnet-4-5,openai/gpt-5
```

### [Thinking budget](#thinking-budget)

Controls reasoning depth. Configuration varies by provider:

* **OpenAI**: String values - `minimal`, `low`, `medium`, `high`
* **Anthropic**: Integer token budget (1024-32768, must be less than `max_tokens`)
  * Set `provider_opts.interleaved_thinking: true` for tool use during reasoning
* **Gemini**: Integer token budget (0 to disable, -1 for dynamic, max 24576)
  * Gemini 2.5 Pro: 128-32768, cannot disable (minimum 128)

```yaml
# OpenAI
thinking_budget: low

# Anthropic
thinking_budget: 8192
provider_opts:
  interleaved_thinking: true

# Gemini
thinking_budget: 8192    # Fixed
thinking_budget: -1      # Dynamic
thinking_budget: 0       # Disabled
```

### [Docker Model Runner (DMR)](#docker-model-runner-dmr)

Run local models. If `base_url` is omitted, Docker Agent auto-discovers via Docker Model plugin.

```yaml
provider: dmr
model: ai/qwen3
max_tokens: 8192
base_url: http://localhost:12434/engines/llama.cpp/v1 # Optional
```

Pass llama.cpp options via `provider_opts.runtime_flags` (array, string, or multiline):

```yaml
provider_opts:
  runtime_flags: ["--ngl=33", "--threads=8"]
  # or: runtime_flags: "--ngl=33 --threads=8"
```

Model config fields auto-map to runtime flags:

* `temperature` → `--temp`
* `top_p` → `--top-p`
* `max_tokens` → `--context-size`

Explicit `runtime_flags` override auto-mapped flags.

Speculative decoding for faster inference:

```yaml
provider_opts:
  speculative_draft_model: ai/qwen3:0.6B-F16
  speculative_num_tokens: 16
  speculative_acceptance_rate: 0.8
```

## [Tools](#tools)

Configure tools in the `toolsets` array. Three types: built-in, MCP (local/remote), and Docker Gateway.

> Note
>
> documentation of each toolset's capabilities, available tools, and specific configuration options, see the [Toolsets reference](https://docs.docker.com/ai/docker-agent/reference/toolsets/).

All toolsets support common properties like `tools` (whitelist), `defer` (deferred loading), `toon` (output compression), `env` (environment variables), and `instruction` (usage guidance). See the [Toolsets reference](https://docs.docker.com/ai/docker-agent/reference/toolsets/) for details on these properties and what each toolset does.

### [Built-in tools](#built-in-tools)

```yaml
toolsets:
  - type: filesystem
  - type: shell
  - type: think
  - type: todo
    shared: true
  - type: memory
    path: ./memory.db
```

### [MCP tools](#mcp-tools)

Local process:

```yaml
- type: mcp
  command: npx
  args:
    ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
  tools: ["read_file", "write_file"] # Optional: limit to specific tools
  env:
    NODE_OPTIONS: "--max-old-space-size=8192"
```

Remote server:

```yaml
- type: mcp
  remote:
    url: https://mcp-server.example.com
    transport_type: sse
    headers:
      Authorization: Bearer token
```

### [Docker MCP Gateway](#docker-mcp-gateway)

Containerized tools from [Docker MCP Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/):

```yaml
- type: mcp
  ref: docker:duckduckgo
```

## [RAG](#rag)

Retrieval-augmented generation for document knowledge bases. Define sources at the top level, reference in agents.

```yaml
rag:
  docs:
    docs: [./documents, ./README.md]
    strategies:
      - type: chunked-embeddings
        embedding_model: openai/text-embedding-3-small
        vector_dimensions: 1536
        database: ./embeddings.db

agents:
  root:
    rag: [docs]
```

### [Retrieval strategies](#retrieval-strategies)

All strategies support chunking configuration. Chunk size and overlap are measured in characters (Unicode code points), not tokens.

#### [Chunked-embeddings](#chunked-embeddings)

Direct semantic search using vector embeddings. Best for understanding intent, synonyms, and paraphrasing.

| Field                              | Type    | Default |
| ---------------------------------- | ------- | ------- |
| `embedding_model`                  | string  | -       |
| `database`                         | string  | -       |
| `vector_dimensions`                | integer | -       |
| `similarity_metric`                | string  | cosine  |
| `threshold`                        | float   | 0.5     |
| `limit`                            | integer | 5       |
| `chunking.size`                    | integer | 1000    |
| `chunking.overlap`                 | integer | 75      |
| `chunking.respect_word_boundaries` | boolean | true    |
| `chunking.code_aware`              | boolean | false   |

```yaml
- type: chunked-embeddings
  embedding_model: openai/text-embedding-3-small
  vector_dimensions: 1536
  database: ./vector.db
  similarity_metric: cosine_similarity
  threshold: 0.5
  limit: 10
  chunking:
    size: 1000
    overlap: 100
```

#### [Semantic-embeddings](#semantic-embeddings)

LLM-enhanced semantic search. Uses a language model to generate rich semantic summaries of each chunk before embedding, capturing deeper meaning. Best for complex documents where context and relationships between concepts matter.

| Field                              | Type    | Default |
| ---------------------------------- | ------- | ------- |
| `embedding_model`                  | string  | -       |
| `chat_model`                       | string  | -       |
| `database`                         | string  | -       |
| `vector_dimensions`                | integer | -       |
| `similarity_metric`                | string  | cosine  |
| `threshold`                        | float   | 0.5     |
| `limit`                            | integer | 5       |
| `ast_context`                      | boolean | false   |
| `semantic_prompt`                  | string  | -       |
| `chunking.size`                    | integer | 1000    |
| `chunking.overlap`                 | integer | 75      |
| `chunking.respect_word_boundaries` | boolean | true    |
| `chunking.code_aware`              | boolean | false   |

```yaml
- type: semantic-embeddings
  embedding_model: openai/text-embedding-3-small
  vector_dimensions: 1536
  chat_model: openai/gpt-5-mini
  database: ./semantic.db
  threshold: 0.3
  limit: 10
  chunking:
    size: 1000
    overlap: 100
```

#### [BM25](#bm25)

Keyword-based search using BM25 algorithm. Best for exact terms, technical jargon, and code identifiers.

| Field                              | Type    | Default |
| ---------------------------------- | ------- | ------- |
| `database`                         | string  | -       |
| `k1`                               | float   | 1.5     |
| `b`                                | float   | 0.75    |
| `threshold`                        | float   | 0.0     |
| `limit`                            | integer | 5       |
| `chunking.size`                    | integer | 1000    |
| `chunking.overlap`                 | integer | 75      |
| `chunking.respect_word_boundaries` | boolean | true    |
| `chunking.code_aware`              | boolean | false   |

```yaml
- type: bm25
  database: ./bm25.db
  k1: 1.5
  b: 0.75
  threshold: 0.3
  limit: 10
  chunking:
    size: 1000
    overlap: 100
```

### [Hybrid retrieval](#hybrid-retrieval)

Combine multiple strategies with fusion:

```yaml
strategies:
  - type: chunked-embeddings
    embedding_model: openai/text-embedding-3-small
    vector_dimensions: 1536
    database: ./vector.db
    limit: 20
  - type: bm25
    database: ./bm25.db
    limit: 15

results:
  fusion:
    strategy: rrf # Options: rrf, weighted, max
    k: 60 # RRF smoothing parameter
  deduplicate: true
  limit: 5
```

Fusion strategies:

* `rrf`: Reciprocal Rank Fusion (recommended, rank-based, no normalization needed)
* `weighted`: Weighted combination (`fusion.weights: {chunked-embeddings: 0.7, bm25: 0.3}`)
* `max`: Maximum score across strategies

### [Reranking](#reranking)

Re-score results with a specialized model for improved relevance:

```yaml
results:
  reranking:
    model: openai/gpt-5-mini
    top_k: 10 # Only rerank top K (0 = all)
    threshold: 0.3 # Minimum score after reranking
    criteria: | # Optional domain-specific guidance
      Prioritize official docs over blog posts
  limit: 5
```

DMR native reranking:

```yaml
models:
  reranker:
    provider: dmr
    model: hf.co/ggml-org/qwen3-reranker-0.6b-q8_0-gguf

results:
  reranking:
    model: reranker
```

### [Code-aware chunking](#code-aware-chunking)

For source code, use AST-based chunking. With semantic-embeddings, you can include AST metadata in the LLM prompts:

```yaml
- type: semantic-embeddings
  embedding_model: openai/text-embedding-3-small
  vector_dimensions: 1536
  chat_model: openai/gpt-5-mini
  database: ./code.db
  ast_context: true # Include AST metadata in semantic prompts
  chunking:
    size: 2000
    code_aware: true # Enable AST-based chunking
```

### [RAG properties](#rag-properties)

Top-level RAG source:

| Field        | Type      | Description                                                    |
| ------------ | --------- | -------------------------------------------------------------- |
| `docs`       | \[]string | Document paths (supports glob patterns, respects `.gitignore`) |
| `tool`       | object    | Customize RAG tool name/description/instruction                |
| `strategies` | \[]object | Retrieval strategies (see above for strategy-specific fields)  |
| `results`    | object    | Post-processing (fusion, reranking, limits)                    |

Results:

| Field                 | Type    | Default |
| --------------------- | ------- | ------- |
| `limit`               | integer | 15      |
| `deduplicate`         | boolean | true    |
| `include_score`       | boolean | false   |
| `fusion.strategy`     | string  | -       |
| `fusion.k`            | integer | 60      |
| `fusion.weights`      | object  | -       |
| `reranking.model`     | string  | -       |
| `reranking.top_k`     | integer | 0       |
| `reranking.threshold` | float   | 0.5     |
| `reranking.criteria`  | string  | ""      |
| `return_full_content` | boolean | false   |

## [Metadata](#metadata)

Documentation and sharing information:

| Property  | Type   | Description                     |
| --------- | ------ | ------------------------------- |
| `author`  | string | Author name                     |
| `license` | string | License (e.g., MIT, Apache-2.0) |
| `readme`  | string | Usage documentation             |

```yaml
metadata:
  author: Your Name
  license: MIT
  readme: |
    Description and usage instructions
```

## [Example configuration](#example-configuration)

Complete configuration demonstrating key features:

```yaml
agents:
  root:
    model: claude
    description: Technical lead
    instruction: Coordinate development tasks and delegate to specialists
    sub_agents: [developer, reviewer]
    toolsets:
      - type: filesystem
      - type: mcp
        ref: docker:duckduckgo
    rag: [readmes]
    commands:
      status: "Check project status"

  developer:
    model: gpt
    description: Software developer
    instruction: Write clean, maintainable code
    toolsets:
      - type: filesystem
      - type: shell

  reviewer:
    model: claude
    description: Code reviewer
    instruction: Review for quality and security
    toolsets:
      - type: filesystem

models:
  gpt:
    provider: openai
    model: gpt-5

  claude:
    provider: anthropic
    model: claude-sonnet-4-5
    max_tokens: 64000

rag:
  readmes:
    docs: ["**/README.md"]
    strategies:
      - type: chunked-embeddings
        embedding_model: openai/text-embedding-3-small
        vector_dimensions: 1536
        database: ./embeddings.db
        limit: 10
      - type: bm25
        database: ./bm25.db
        limit: 10
    results:
      fusion:
        strategy: rrf
        k: 60
      limit: 5
```

## [What's next](#whats-next)

* Read the [Toolsets reference](https://docs.docker.com/ai/docker-agent/reference/toolsets/) for detailed toolset documentation
* Review the [CLI reference](https://docs.docker.com/ai/docker-agent/reference/cli/) for command-line options
* Browse [example configurations](https://github.com/docker/docker-agent/tree/main/examples)
* Learn about [sharing agents](https://docs.docker.com/ai/docker-agent/sharing-agents/)

----
url: https://docs.docker.com/reference/compose-file/include/
----

# Use include to modularize Compose files

***

Table of contents

***

Requires: Docker Compose [2.20.0](https://github.com/docker/compose/releases/tag/v2.20.0) and later

You can reuse and modularize Docker Compose configurations by including other Compose files. This is useful if:

* You want to reuse other Compose files.
* You need to factor out parts of your application model into separate Compose files so they can be managed separately or shared with others.
* Teams need to maintain a Compose file with only necessary complexity for the limited amount of resources it has to declare for its own sub-domain within a larger deployment.

The `include` top-level section is used to define the dependency on another Compose application, or sub-domain. Each path listed in the `include` section is loaded as an individual Compose application model, with its own project directory, in order to resolve relative paths.

Once the included Compose application is loaded, all resource definitions are copied into the current Compose application model. Compose displays a warning if resource names conflict and doesn't try to merge them. To enforce this, `include` is evaluated after the Compose file(s) selected to define the Compose application model have been parsed and merged, so that conflicts between Compose files are detected.

`include` applies recursively so an included Compose file which declares its own `include` section triggers those other files to be included as well.

Any volumes, networks, or other resources pulled in from the included Compose file can be used by the current Compose application for cross-service references. For example:

```yaml
include:
  - my-compose-include.yaml  #with serviceB declared
services:
  serviceA:
    build: .
    depends_on:
      - serviceB #use serviceB directly as if it was declared in this Compose file
```

Compose also supports the use of interpolated variables with `include`. It's recommended that you [specify mandatory variables](https://docs.docker.com/reference/compose-file/interpolation/). For example:

```text
include:
  -${INCLUDE_PATH:?FOO}/compose.yaml
```

## [Short syntax](#short-syntax)

The short syntax only defines paths to other Compose files. The file is loaded with the parent folder as the project directory, and an optional `.env` file that is loaded to define any variables' default values by interpolation. The local project's environment can override those values.

```yaml
include:
  - ../commons/compose.yaml
  - ../another_domain/compose.yaml

services:
  webapp:
    depends_on:
      - included-service # defined by another_domain
```

In the previous example, both `../commons/compose.yaml` and `../another_domain/compose.yaml` are loaded as individual Compose projects. Relative paths in Compose files being referred by `include` are resolved relative to their own Compose file path, not based on the local project's directory. Variables are interpolated using values set in the optional `.env` file in same folder and are overridden by the local project's environment.

## [Long syntax](#long-syntax)

The long syntax offers more control over the sub-project parsing:

```yaml
include:
   - path: ../commons/compose.yaml
     project_directory: ..
     env_file: ../another/.env
```

### [`path`](#path)

`path` is required and defines the location of the Compose file(s) to be parsed and included into the local Compose model.

`path` can be set as:

* A string: When using a single Compose file.
* A list of strings: When multiple Compose files need to be [merged together](https://docs.docker.com/reference/compose-file/merge/) to define the Compose model for the local application.

```yaml
include:
   - path:
       - ../commons/compose.yaml
       - ./commons-override.yaml
```

### [`project_directory`](#project_directory)

`project_directory` defines a base path to resolve relative paths set in the Compose file. It defaults to the directory of the included Compose file.

### [`env_file`](#env_file)

`env_file` defines an environment file(s) to use to define default values when interpolating variables in the Compose file being parsed. It defaults to `.env` file in the `project_directory` for the Compose file being parsed.

`env_file` can be set to either a string or a list of strings when multiple environment files need to be merged to define a project environment.

```yaml
include:
   - path: ../another/compose.yaml
     env_file:
       - ../another/.env
       - ../another/dev.env
```

The local project's environment has precedence over the values set by the Compose file, so that the local project can override values for customization.

## [Additional resources](#additional-resources)

For more information on using `include`, see [Working with multiple Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/)

----
url: https://docs.docker.com/compose/how-tos/provider-services/
----

# Use provider services

***

Table of contents

***

Requires: Docker Compose [2.36.0](https://github.com/docker/compose/releases/tag/v2.36.0) and later

Docker Compose supports provider services, which allow integration with services whose lifecycles are managed by third-party components rather than by Compose itself.\
This feature enables you to define and utilize platform-specific services without the need for manual setup or direct lifecycle management.

## [What are provider services?](#what-are-provider-services)

Provider services are a special type of service in Compose that represents platform capabilities rather than containers. They allow you to declare dependencies on specific platform features that your application needs.

When you define a provider service in your Compose file, Compose works with the platform to provision and configure the requested capability, making it available to your application services.

## [Using provider services](#using-provider-services)

To use a provider service in your Compose file, you need to:

1. Define a service with the `provider` attribute
2. Specify the `type` of provider you want to use
3. Configure any provider-specific options
4. Declare dependencies from your application services to the provider service

Here's a basic example:

```yaml
services:
  database:
    provider:
      type: awesomecloud
      options:
        type: mysql
        foo: bar  
  app:
    image: myapp 
    depends_on:
       - database
```

Notice the dedicated `provider` attribute in the `database` service. This attribute specifies that the service is managed by a provider and lets you define options specific to that provider type.

The `depends_on` attribute in the `app` service specifies that it depends on the `database` service. This means that the `database` service will be started before the `app` service, allowing the provider information to be injected into the `app` service.

## [How it works](#how-it-works)

During the `docker compose up` command execution, Compose identifies services relying on providers and works with them to provision the requested capabilities. The provider then populates Compose model with information about how to access the provisioned resource.

This information is passed to services that declare a dependency on the provider service, typically through environment variables. The naming convention for these variables is:

```env
<PROVIDER_SERVICE_NAME>_<VARIABLE_NAME>
```

For example, if your provider service is named `database`, your application service might receive environment variables like:

* `DATABASE_URL` with the URL to access the provisioned resource
* `DATABASE_TOKEN` with an authentication token
* Other provider-specific variables

Your application can then use these environment variables to interact with the provisioned resource.

## [Provider types](#provider-types)

The `type` field in a provider service references the name of either:

1. A Docker CLI plugin (e.g., `docker-model`)
2. A binary available in the user's PATH
3. A path to the binary or script to execute

When Compose encounters a provider service, it looks for a plugin or binary with the specified name to handle the provisioning of the requested capability.

For example, if you specify `type: model`, Compose will look for a Docker CLI plugin named `docker-model` or a binary named `model` in the PATH.

```yaml
services:
  ai-runner:
    provider:
      type: model  # Looks for docker-model plugin or model binary
      options:
        model: ai/example-model
```

The plugin or binary is responsible for:

1. Interpreting the options provided in the provider service
2. Provisioning the requested capability
3. Returning information about how to access the provisioned resource

This information is then passed to dependent services as environment variables.

> Tip
>
> If you're working with AI models in Compose, use the [`models` top-level element](https://docs.docker.com/ai/compose/models-and-compose/) instead.

## [Benefits of using provider services](#benefits-of-using-provider-services)

Using provider services in your Compose applications offers several benefits:

1. Simplified configuration: You don't need to manually configure and manage platform capabilities
2. Declarative approach: You can declare all your application's dependencies in one place
3. Consistent workflow: You use the same Compose commands to manage your entire application, including platform capabilities

## [Creating your own provider](#creating-your-own-provider)

If you want to create your own provider to extend Compose with custom capabilities, you can implement a Compose plugin that registers provider types.

For detailed information on how to create and implement your own provider, refer to the [Compose Extensions documentation](https://github.com/docker/compose/blob/main/docs/extension.md).\
This guide explains the extension mechanism that allows you to add new provider types to Compose.

## [Reference](#reference)

* [Docker Model Runner documentation](https://docs.docker.com/ai/model-runner/)
* [Compose Extensions documentation](https://github.com/docker/compose/blob/main/docs/extension.md)

----
url: https://docs.docker.com/extensions/extensions-sdk/extensions/multi-arch/
----

# Build multi-arch extensions

***

Table of contents

***

It is highly recommended that, at a minimum, your extension is supported for the following architectures:

* `linux/amd64`
* `linux/arm64`

Docker Desktop retrieves the extension image according to the user’s system architecture. If the extension does not provide an image that matches the user’s system architecture, Docker Desktop is not able to install the extension. As a result, users can’t run the extension in Docker Desktop.

## [Build and push for multiple architectures](#build-and-push-for-multiple-architectures)

If you created an extension from the `docker extension init` command, the `Makefile` at the root of the directory includes a target with name `push-extension`.

You can run `make push-extension` to build your extension against both `linux/amd64` and `linux/arm64` platforms, and push them to Docker Hub.

For example:

```console
$ make push-extension
```

Alternatively, if you started from an empty directory, use the command below to build your extension for multiple architectures:

```console
$ docker buildx build --push --platform=linux/amd64,linux/arm64 --tag=username/my-extension:0.0.1 .
```

You can then check the image manifest to see if the image is available for both architectures using the [`docker buildx imagetools` command](/reference/cli/docker/buildx/imagetools/):

```console
$ docker buildx imagetools inspect username/my-extension:0.0.1
Name:      docker.io/username/my-extension:0.0.1
MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest:    sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48

Manifests:
  Name:      docker.io/username/my-extension:0.0.1@sha256:71d7ecf3cd12d9a99e73ef448bf63ae12751fe3a436a007cb0969f0dc4184c8c
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/amd64

  Name:      docker.io/username/my-extension:0.0.1@sha256:5ba4ceea65579fdd1181dfa103cc437d8e19d87239683cf5040e633211387ccf
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/arm64
```

> Tip
>
> If you're having trouble pushing the image, make sure you're signed in to Docker Hub. Otherwise, run `docker login` to authenticate.

For more information, see [Multi-platform images](https://docs.docker.com/build/building/multi-platform/) page.

## [Adding multi-arch binaries](#adding-multi-arch-binaries)

If your extension includes some binaries that deploy to the host, it’s important that they also have the right architecture when building the extension against multiple architectures.

Currently, Docker does not provide a way to explicitly specify multiple binaries for every architecture in the `metadata.json` file. However, you can add architecture-specific binaries depending on the `TARGETARCH` in the extension’s `Dockerfile`.

The following example shows an extension that uses a binary as part of its operations. The extension needs to run both in Docker Desktop for Mac and Windows.

In the `Dockerfile`, download the binary depending on the target architecture:

```Dockerfile
#syntax=docker/dockerfile:1.3-labs

FROM alpine AS dl
WORKDIR /tmp
RUN apk add --no-cache curl tar
ARG TARGETARCH
RUN <<EOT ash
    mkdir -p /out/darwin
    curl -fSsLo /out/darwin/kubectl "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/darwin/${TARGETARCH}/kubectl"
    chmod a+x /out/darwin/kubectl
EOT
RUN <<EOT ash
    if [ "amd64" = "$TARGETARCH" ]; then
        mkdir -p /out/windows
        curl -fSsLo /out/windows/kubectl.exe "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/windows/amd64/kubectl.exe"
    fi
EOT

FROM alpine
LABEL org.opencontainers.image.title="example-extension" \
    org.opencontainers.image.description="My Example Extension" \
    org.opencontainers.image.vendor="Docker Inc." \
    com.docker.desktop.extension.api.version=">= 0.3.3"

COPY --from=dl /out /
```

In the `metadata.json` file, specify the path for every binary on every platform:

```json
{
  "icon": "docker.svg",
  "ui": {
    "dashboard-tab": {
      "title": "Example Extension",
      "src": "index.html",
      "root": "ui"
    }
  },
  "host": {
    "binaries": [
      {
        "darwin": [
          {
            "path": "/darwin/kubectl"
          }
        ],
        "windows": [
          {
            "path": "/windows/kubectl.exe"
          }
        ]
      }
    ]
  }
}
```

As a result, when `TARGETARCH` equals:

* `arm64`, the `kubectl` binary fetched corresponds to the `arm64` architecture, and is copied to `/darwin/kubectl` in the final stage.
* `amd64`, two `kubectl` binaries are fetched. One for Darwin and another for Windows. They are copied to `/darwin/kubectl` and `/windows/kubectl.exe` respectively, in the final stage.

> Note
>
> The binary destination path for Darwin is `darwin/kubectl` in both cases. The only change is the architecture-specific binary that is downloaded.

When the extension is installed, the extension framework copies the binaries from the extension image at `/darwin/kubectl` for Darwin, or `/windows/kubectl.exe` for Windows, to a specific location in the user’s host filesystem.

## [Can I develop extensions that run Windows containers?](#can-i-develop-extensions-that-run-windows-containers)

Although Docker Extensions is supported on Docker Desktop for Windows, Mac, and Linux, the extension framework only supports Linux containers. Therefore, you must target `linux` as the OS when you build your extension image.

----
url: https://docs.docker.com/dhi/core-concepts/cis/
----

# CIS Benchmark

***

Table of contents

***

## [What is the CIS Docker Benchmark?](#what-is-the-cis-docker-benchmark)

The [CIS Docker Benchmark](https://www.cisecurity.org/benchmark/docker) is part of the globally recognized CIS Benchmarks, developed by the [Center for Internet Security (CIS)](https://www.cisecurity.org/). It defines recommended secure configurations for all aspects of the Docker container ecosystem, including the container host, Docker daemon, container images, and the container runtime.

## [Why CIS Benchmark compliance matters](#why-cis-benchmark-compliance-matters)

Following the CIS Docker Benchmark helps organizations:

* Reduce security risk with widely recognized hardening guidance.
* Meet regulatory or contractual requirements that reference CIS controls.
* Standardize image and Dockerfile practices across teams.
* Demonstrate audit readiness with configuration decisions grounded in a public standard.

## [How Docker Hardened Images comply with the CIS Benchmark](#how-docker-hardened-images-comply-with-the-cis-benchmark)

Docker Hardened Images (DHIs) are designed with security in mind and are verified to be compliant with the relevant controls from the CIS Docker Benchmark for the scope that applies to container images and Dockerfile configuration.

CIS-compliant DHIs are compliant with all controls in Section 4, with the sole exception of the control requiring Docker Content Trust (DCT), which [Docker officially retired](https://www.docker.com/blog/retiring-docker-content-trust/). Instead, DHIs are [signed](https://docs.docker.com/dhi/core-concepts/signatures/) using Cosign, providing an even higher level of authenticity and integrity. By starting from a CIS-compliant DHI, teams can adopt image-level best practices from the benchmark more quickly and confidently.

> Note
>
> The CIS Docker Benchmark also includes controls for the host, daemon, and runtime. CIS-compliant DHIs address only the image and Dockerfile scope (Section 4). Overall compliance still depends on how you configure and operate the broader environment.

## [Identify CIS-compliant images](#identify-cis-compliant-images)

CIS-compliant images are labeled as **CIS** in the Docker Hardened Images catalog. To find them, [search the catalog](https://docs.docker.com/dhi/how-to/explore/) and look for the **CIS** designation on individual listings.

## [Get the benchmark](#get-the-benchmark)

Download the latest CIS Docker Benchmark directly from CIS: <https://www.cisecurity.org/benchmark/docker>

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/push/
----

# docker mcp catalog push

***

| Description | Push a catalog to an OCI registry         |
| ----------- | ----------------------------------------- |
| Usage       | `docker mcp catalog push <oci-reference>` |

## [Description](#description)

Push a catalog to an OCI registry

----
url: https://docs.docker.com/guides/lab-container-getting-started/
----

[Lab: Getting Started with Docker](https://docs.docker.com/guides/lab-container-getting-started/)

Hands-on lab: Run your first containers, write a Dockerfile, build a custom image from a Node.js app, and optionally push it to Docker Hub.

Labs

30 minutes

Resources:

* [Docker overview](/get-started/docker-overview/)
* [Dockerfile reference](/reference/dockerfile/)
* [Labspace repository](https://github.com/dockersamples/labspace-container-getting-started)

[« Back to all guides](/guides/)

# Lab: Getting Started with Docker

***

Table of contents

***

Start from zero and learn Docker's core building blocks. You'll run pre-built containers, write a `Dockerfile` to package a Node.js app, build your own image, and see container immutability and isolation in action.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-container-getting-started up -d
   ```

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

By the end of this Labspace, you will have completed the following:

* Understand what containers are and how they differ from virtual machines
* Run containers in the background, inspect their logs and filesystem, and manage their lifecycle
* Write a `Dockerfile` to package an application, using layer caching for fast rebuilds
* Build a custom image with `docker build` and run it as a container
* Optionally publish your image to Docker Hub

## [Modules](#modules)

| # | Module                    | Description                                                                    |
| - | ------------------------- | ------------------------------------------------------------------------------ |
| 1 | Welcome to Docker         | Introduction to containers and running your first `hello-world` container      |
| 2 | Running Containers        | Launch Nginx, inspect logs and internals, and manage the container lifecycle   |
| 3 | Building Your First Image | Write a `Dockerfile` and build a custom image from a Node.js app               |
| 4 | Running Your App          | Run your image, explore container isolation, and optionally push to Docker Hub |
| 5 | Wrap-up                   | Summary of key concepts and next steps                                         |

----
url: https://docs.docker.com/guides/testcontainers-java-wiremock/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

```console
$ ./mvnw test
```

Or with Gradle:

```console
$ ./gradlew test
```

You should see the WireMock Docker container start in the console output. It acts as the photo service, serving mock responses based on the configured expectations. All tests should pass.

## [Summary](#summary)

You built a Spring Boot application that integrates with an external REST API, then tested that integration using three different approaches:

* WireMock JUnit 5 extension with inline stubs
* WireMock JUnit 5 extension with JSON mapping files
* Testcontainers WireMock module running WireMock in a Docker container

Testing at the HTTP protocol level instead of mocking Java methods lets you catch serialization issues and simulate realistic failure scenarios.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testcontainers WireMock module](https://testcontainers.com/modules/wiremock/)
* [WireMock documentation](https://wiremock.org/docs/)
* [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/)

----
url: https://docs.docker.com/reference/cli/docker/desktop/engine/ls/
----

# docker desktop engine ls

***

| Description | List available engines (Windows only) |
| ----------- | ------------------------------------- |
| Usage       | `docker desktop engine ls`            |

## [Options](#options)

| Option     | Default  | Description                                          |
| ---------- | -------- | ---------------------------------------------------- |
| `--format` | `pretty` | Format the output. Accepted values are: pretty, json |

----
url: https://docs.docker.com/engine/network/
----

# Networking overview

***

Table of contents

***

Container networking refers to the ability for containers to connect to and communicate with each other, and with non-Docker network services.

Containers have networking enabled by default, and they can make outgoing connections. A container has no information about what kind of network it's attached to, or whether its network peers are also Docker containers. A container only sees a network interface with an IP address, a gateway, a routing table, DNS services, and other networking details.

This page describes networking from the point of view of the container, and the concepts around container networking.

When Docker Engine on Linux starts for the first time, it has a single built-in network called the "default bridge" network. When you run a container without the `--network` option, it is connected to the default bridge.

Containers attached to the default bridge have access to network services outside the Docker host. They use "masquerading" which means, if the Docker host has Internet access, no additional configuration is needed for the container to have Internet access.

For example, to run a container on the default bridge network, and have it ping an Internet host:

```console
$ docker run --rm -ti busybox ping -c1 docker.com
PING docker.com (23.185.0.4): 56 data bytes
64 bytes from 23.185.0.4: seq=0 ttl=62 time=6.564 ms

--- docker.com ping statistics ---
1 packets transmitted, 1 packets received, 0% packet loss
round-trip min/avg/max = 6.564/6.564/6.564 ms
```

## [User-defined networks](#user-defined-networks)

With the default configuration, containers attached to the default bridge network have unrestricted network access to each other using container IP addresses. They cannot refer to each other by name.

It can be useful to separate groups of containers that should have full access to each other, but restricted access to containers in other groups.

You can create custom, user-defined networks, and connect groups of containers to the same network. Once connected to a user-defined network, containers can communicate with each other using container IP addresses or container names.

The following example creates a network using the `bridge` network driver and runs a container in that network:

```console
$ docker network create -d bridge my-net
$ docker run --network=my-net -it busybox
```

### [Drivers](#drivers)

Docker Engine has a number of network drivers, as well as the default "bridge". On Linux, the following built-in network drivers are available:

| Driver                                                             | Description                                                         |
| ------------------------------------------------------------------ | ------------------------------------------------------------------- |
| [bridge](https://docs.docker.com/engine/network/drivers/bridge/)   | The default network driver.                                         |
| [host](https://docs.docker.com/engine/network/drivers/host/)       | Remove network isolation between the container and the Docker host. |
| [none](https://docs.docker.com/engine/network/drivers/none/)       | Completely isolate a container from the host and other containers.  |
| [overlay](https://docs.docker.com/engine/network/drivers/overlay/) | Swarm Overlay networks connect multiple Docker daemons together.    |
| [ipvlan](https://docs.docker.com/engine/network/drivers/ipvlan/)   | Connect containers to external VLANs.                               |
| [macvlan](https://docs.docker.com/engine/network/drivers/macvlan/) | Containers appear as devices on the host's network.                 |

More information can be found in the network driver specific pages, including their configuration options and details about their functionality.

Native Windows containers have a different set of drivers, see [Windows container network drivers](https://learn.microsoft.com/en-us/virtualization/windowscontainers/container-networking/network-drivers-topologies).

### [Connecting to multiple networks](#connecting-to-multiple-networks)

Connecting a container to a network can be compared to connecting an Ethernet cable to a physical host. Just as a host can be connected to multiple Ethernet networks, a container can be connected to multiple Docker networks.

For example, a frontend container may be connected to a bridge network with external access, and a [`--internal`](/reference/cli/docker/network/create/#internal) network to communicate with containers running backend services that do not need external network access.

A container may also be connected to different types of network. For example, an `ipvlan` network to provide internet access, and a `bridge` network for access to local services.

Containers can also share networking stacks, see [Container networks](#container-networks).

When sending packets, if the destination is an address in a directly connected network, packets are sent to that network. Otherwise, packets are sent to a default gateway for routing to their destination. In the example above, the `ipvlan` network's gateway must be the default gateway.

The default gateway is selected by Docker, and may change whenever a container's network connections change. To make Docker choose a specific default gateway when creating the container or connecting a new network, set a gateway priority. See option `gw-priority` for the [`docker run`](/reference/cli/docker/container/run/) and [`docker network connect`](/reference/cli/docker/network/connect/) commands.

The default `gw-priority` is `0` and the gateway in the network with the highest priority is the default gateway. So, when a network should always be the default gateway, it is enough to set its `gw-priority` to `1`.

```console
$ docker run --network name=gwnet,gw-priority=1 --network anet1 --name myctr myimage
$ docker network connect anet2 myctr
```

## [Published ports](#published-ports)

When you create or run a container using `docker create` or `docker run`, all ports of containers on bridge networks are accessible from the Docker host and other containers connected to the same network. Ports are not accessible from outside the host or, with the default configuration, from containers in other networks.

Use the `--publish` or `-p` flag to make a port available outside the host, and to containers in other bridge networks.

For more information about port mapping, including how to disable it and use direct routing to containers, see [port publishing](https://docs.docker.com/engine/network/port-publishing/).

## [IP address and hostname](#ip-address-and-hostname)

When creating a network, IPv4 address allocation is enabled by default, it can be disabled using `--ipv4=false`. IPv6 address allocation can be enabled using `--ipv6`.

```console
$ docker network create --ipv6 --ipv4=false v6net
```

By default, the container gets an IP address for every Docker network it attaches to. A container receives an IP address out of the IP subnet of the network. The Docker daemon performs dynamic subnetting and IP address allocation for containers. Each network also has a default subnet mask and gateway.

You can connect a running container to multiple networks, either by passing the `--network` flag multiple times when creating the container, or using the `docker network connect` command for already running containers. In both cases, you can use the `--ip` or `--ip6` flags to specify the container's IP address on that particular network.

In the same way, a container's hostname defaults to be the container's ID in Docker. You can override the hostname using `--hostname`. When connecting to an existing network using `docker network connect`, you can use the `--alias` flag to specify an additional network alias for the container on that network.

### [Subnet allocation](#subnet-allocation)

Docker networks can use either explicitly configured subnets or automatically allocated ones from default pools.

#### [Explicit subnet configuration](#explicit-subnet-configuration)

You can specify exact subnets when creating a network:

```console
$ docker network create --ipv6 --subnet 192.0.2.0/24 --subnet 2001:db8::/64 mynet
```

#### [Automatic subnet allocation](#automatic-subnet-allocation)

When no `--subnet` option is provided, Docker automatically selects a subnet from predefined "default address pools". These pools can be configured in `/etc/docker/daemon.json`. Docker's built-in default is equivalent to:

```json
{
  "default-address-pools": [
    { "base": "172.17.0.0/16", "size": 16 },
    { "base": "172.18.0.0/16", "size": 16 },
    { "base": "172.19.0.0/16", "size": 16 },
    { "base": "172.20.0.0/14", "size": 16 },
    { "base": "172.24.0.0/14", "size": 16 },
    { "base": "172.28.0.0/14", "size": 16 },
    { "base": "192.168.0.0/16", "size": 20 }
  ]
}
```

* `base`: The subnet that can be allocated from.
* `size`: The prefix length used for each allocated subnet.

When an IPv6 subnet is required and there are no IPv6 addresses in `default-address-pools`, Docker allocates subnets from a Unique Local Address (ULA) prefix. To use specific IPv6 subnets instead, add them to your `default-address-pools`. See [Dynamic IPv6 subnet allocation](https://docs.docker.com/engine/daemon/ipv6/#dynamic-ipv6-subnet-allocation) for more information.

Docker attempts to avoid address prefixes already in use on the host. However, you may need to customize `default-address-pools` to prevent routing conflicts in some network environments.

The default pools use large subnets, which limits the number of networks you can create. You can divide base subnets into smaller pools to support more networks.

For example, this configuration allows Docker to create 256 networks from `172.17.0.0/16`. Docker will allocate subnets `172.17.0.0/24`, `172.17.1.0/24`, and so on, up to `172.17.255.0/24`:

```json
{
  "default-address-pools": [{ "base": "172.17.0.0/16", "size": 24 }]
}
```

You can also request a subnet with a specific prefix length from the default pools by using unspecified addresses in the `--subnet` option:

```console
$ docker network create --ipv6 --subnet ::/56 --subnet 0.0.0.0/24 mynet
6686a6746b17228f5052528113ddad0e6d68e2e3905d648e336b33409f2d3b64
$ docker network inspect mynet -f '{{json .IPAM.Config}}' | jq .
[
  {
    "Subnet": "172.19.0.0/24",
    "Gateway": "172.19.0.1"
  },
  {
    "Subnet": "fdd3:6f80:972c::/56",
    "Gateway": "fdd3:6f80:972c::1"
  }
]
```

> Note
>
> Support for unspecified addresses in `--subnet` was introduced in Docker 29.0.0. If Docker is downgraded to an older version, networks created in this way will become unusable. They can be removed and re-created, or will function again if the daemon is restored to 29.0.0 or later.

## [DNS services](#dns-services)

Containers use the same DNS servers as the host by default, but you can override this with `--dns`.

By default, containers inherit the DNS settings as defined in the `/etc/resolv.conf` configuration file. Containers that attach to the default `bridge` network receive a copy of this file. Containers that attach to a [custom network](https://docs.docker.com/engine/network/drivers/bridge/#use-user-defined-bridge-networks) use Docker's embedded DNS server. The embedded DNS server forwards external DNS lookups to the DNS servers configured on the host. The embedded DNS server address is `127.0.0.11`. There is no IPv6 equivalent; the IPv4 address works even in IPv6-only containers. If an application requires an explicit DNS server address, use `127.0.0.11`.

You can configure DNS resolution on a per-container basis, using flags for the `docker run` or `docker create` command used to start the container. The following table describes the available `docker run` flags related to DNS configuration.

| Flag           | Description                                                                                                                                                                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dns`        | The IP address of a DNS server. To specify multiple DNS servers, use multiple `--dns` flags. DNS requests will be forwarded from the container's network namespace so, for example, `--dns=127.0.0.1` refers to the container's own loopback address. |
| `--dns-search` | A DNS search domain to search non-fully qualified hostnames. To specify multiple DNS search prefixes, use multiple `--dns-search` flags.                                                                                                              |
| `--dns-opt`    | A key-value pair representing a DNS option and its value. See your operating system's documentation for `resolv.conf` for valid options.                                                                                                              |
| `--hostname`   | The hostname a container uses for itself. Defaults to the container's ID if not specified.                                                                                                                                                            |

### [Custom hosts](#custom-hosts)

Your container will have lines in `/etc/hosts` which define the hostname of the container itself, as well as `localhost` and a few other common things. Custom hosts, defined in `/etc/hosts` on the host machine, aren't inherited by containers. To pass additional hosts into a container, refer to [add entries to container hosts file](/reference/cli/docker/container/run/#add-host) in the `docker run` reference documentation.

## [Container networks](#container-networks)

In addition to user-defined networks, you can attach a container to another container's networking stack directly, using the `--network container:<name|id>` flag format.

The following flags aren't supported for containers using the `container:` networking mode:

* `--add-host`
* `--hostname`
* `--dns`
* `--dns-search`
* `--dns-option`
* `--mac-address`
* `--publish`
* `--publish-all`
* `--expose`

The following example runs a Redis container, with Redis binding to 127.0.0.1, then running the `redis-cli` command and connecting to the Redis server over 127.0.0.1.

```console
$ docker run -d --name redis redis --bind 127.0.0.1
$ docker run --rm -it --network container:redis redis redis-cli -h 127.0.0.1
```

----
url: https://docs.docker.com/reference/api/engine/version/v1.44/
----

# Docker Engine API v1.44 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.44.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.44.yaml)

# Docker Engine API (1.44)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.44.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.44) is used. For example, calling `/info` is the same as calling `/v1.44/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.44/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.44/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.44/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"AppArmorProfile": "",
"Args": [
"-c",
"exit 9"
],
"Config": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"/bin/sh",
"-c",
"exit 9"
],
"Domainname": "",
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Healthcheck": {
"Test": [
"CMD-SHELL",
"exit 0"
]
},
"Hostname": "ba033ac44011",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"MacAddress": "",
"NetworkDisabled": false,
"OpenStdin": false,
"StdinOnce": false,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"StopSignal": "SIGTERM",
"StopTimeout": 10
},
"Created": "2015-01-06T15:47:31.485331387Z",
"Driver": "overlay2",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 0,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"ContainerIDFile": "",
"CpusetCpus": "",
"CpusetMems": "",
"CpuPercent": 80,
"CpuShares": 0,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"Devices": [ ],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"IpcMode": "",
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"OomKillDisable": false,
"OomScoreAdj": 500,
"NetworkMode": "bridge",
"PidMode": "",
"PortBindings": { },
"Privileged": false,
"ReadonlyRootfs": false,
"PublishAllPorts": false,
"RestartPolicy": {
"MaximumRetryCount": 2,
"Name": "on-failure"
},
"LogConfig": {
"Type": "json-file"
},
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Ulimits": [
{ }
],
"VolumeDriver": "",
"ShmSize": 67108864
},
"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
"MountLabel": "",
"Name": "/boring_euclid",
"NetworkSettings": {
"Bridge": "",
"SandboxID": "",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": 0,
"SandboxKey": "",
"EndpointID": "",
"Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"MacAddress": "",
"Networks": {
"bridge": {
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
"EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Path": "/bin/sh",
"ProcessLabel": "",
"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
"RestartCount": 1,
"State": {
"Error": "",
"ExitCode": 9,
"FinishedAt": "2015-01-06T15:47:32.080254511Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2019-12-22T10:59:05.6385933Z",
"End": "2019-12-22T10:59:05.8078452Z",
"ExitCode": 0,
"Output": ""
}
]
},
"OOMKilled": false,
"Dead": false,
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z",
"Status": "running"
},
"Mounts": [
{
"Name": "fac362...80535",
"Source": "/data",
"Destination": "/data",
"Driver": "local",
"Mode": "ro,Z",
"RW": false,
"Propagation": ""
}
]
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.44/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
],
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.44/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.44/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.44/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.44/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"read": "2015-01-08T22:57:31.547920715Z",
"pids_stats": {
"current": 3
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"memory_stats": {
"stats": {
"total_pgmajfault": 0,
"cache": 0,
"mapped_file": 0,
"total_inactive_file": 0,
"pgpgout": 414,
"rss": 6537216,
"total_mapped_file": 0,
"writeback": 0,
"unevictable": 0,
"pgpgin": 477,
"total_unevictable": 0,
"pgmajfault": 0,
"total_rss": 6537216,
"total_rss_huge": 6291456,
"total_writeback": 0,
"total_inactive_anon": 0,
"rss_huge": 6291456,
"hierarchical_memory_limit": 67108864,
"total_pgfault": 964,
"total_active_file": 0,
"active_anon": 6537216,
"total_active_anon": 6537216,
"total_pgpgout": 414,
"total_cache": 0,
"inactive_anon": 0,
"active_file": 0,
"pgfault": 964,
"inactive_file": 0,
"total_pgpgin": 477
},
"max_usage": 6651904,
"usage": 6537216,
"failcnt": 0,
"limit": 67108864
},
"blkio_stats": { },
"cpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24472255,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100215355,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 739306590000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24350896,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100093996,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 9492140000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.44/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.44/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.44/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.44/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.44/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime.This field is omitted when empty.                         |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.44/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"string"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.44/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.44/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.44/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.44/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.44/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.44/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.44/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.44/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.44/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.44/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.44/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.44/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.44/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| keep-storage | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| all          | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.44/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.44/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.44/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"Container": "65974bc86f1770ae4bff79f651ebdbce166ae9aada632ee3fa9af3a264911735",
"ContainerConfig": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"DockerVersion": "20.10.7",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "web:web",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": true,
"Image": "",
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.44/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|     |                                                                                                                                                                 |
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed. |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.44/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.44/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|         |                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------ |
| force   | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags |
| noprune | booleanDefault: falseDo not delete untagged parent images                                              |

### Responses

/v1.44/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| limit        | integerMaximum number of results to return                                                                                                                                                                                                                                                                                                                                                                                                                            |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-automated=(true\|false)` (deprecated, see below)
- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars.The `is-automated` filter is deprecated. The `is_automated` field has been deprecated by Docker Hub's search API. Consequently, searching for `is-automated=true` will yield no results. |

### Responses

/v1.44/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.44/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.44/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.44/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                          |
| ----- | ---------------------------------------- |
| names | Array of stringsImage names to filter by |

### Responses

/v1.44/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                                             |
| ----- | ----------------------------------------------------------- |
| quiet | booleanDefault: falseSuppress progress details during load. |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.44/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.44/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.44/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.44/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|                |                                                                                                                                                                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired   | stringThe network's name.                                                                                                                                                                                                              |
| CheckDuplicate | booleanDeprecated: CheckDuplicate is now always enabled.                                                                                                                                                                               |
| Driver         | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope          | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal       | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable     | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress        | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly     | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|                | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|                | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv6     | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|                | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|                | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.44/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"CheckDuplicate": true,
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.44/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
},
"MacAddress": "02:42:ac:12:05:02"
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.44/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.44/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.44/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.44/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.44/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.44/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.44/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.44/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.44/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.44/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.44/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.44/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.44/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.44/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.44/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.44/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.44/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.44/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.44/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.44/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.44/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.44/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.44/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.44/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.44/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.44/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.44/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.44/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.44/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.44/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.44/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.44/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.44/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.44/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.44/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.44/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.44/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.44/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.44/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.44/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.44/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.44/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.44/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.44/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.44/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.44/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.44/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.44/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.44/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.44/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.44/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.44/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.44/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.44/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.44/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"BridgeNfIptables": true,
"BridgeNfIp6tables": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "4.9.38-moby",
"OperatingSystem": "Alpine Linux v3.5",
"OSVersion": "16.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"AllowNondistributableArtifactsCIDRs": [ ],
"AllowNondistributableArtifactsHostnames": [ ],
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "24.0.2",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
]
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.44/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "19.03.12",
"Details": { }
}
],
"Version": "19.03.12",
"ApiVersion": "1.40",
"MinAPIVersion": "1.12",
"GitCommit": "48a66213fe",
"GoVersion": "go1.13.14",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "4.19.76-linuxkit",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.44/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.44/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.44/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|      |                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |

### Responses

/v1.44/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parents": [ ],
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parents": [
"ndlpt0hhvkqcdfkputsk4cq9c"
],
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.44/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 3987495
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.44/session

----
url: https://docs.docker.com/build/ci/github-actions/
----

# Docker Build GitHub Actions

***

Table of contents

***

GitHub Actions is a popular CI/CD platform for automating your build, test, and deployment pipeline. Docker provides a set of official GitHub Actions for you to use in your workflows. These official actions are reusable, easy-to-use components for building, annotating, and pushing images.

The following GitHub Actions are available:

* [Build and push Docker images](https://github.com/marketplace/actions/build-and-push-docker-images): build and push Docker images with BuildKit.
* [Docker Buildx Bake](https://github.com/marketplace/actions/docker-buildx-bake): enables using high-level builds with [Bake](https://docs.docker.com/build/bake/).
* [Docker Login](https://github.com/marketplace/actions/docker-login): sign in to a Docker registry.
* [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx): creates and boots a BuildKit builder.
* [Docker Metadata action](https://github.com/marketplace/actions/docker-metadata-action): extracts metadata from Git reference and GitHub events to generate tags, labels, and annotations.
* [Docker Setup Compose](https://github.com/marketplace/actions/docker-setup-compose): installs and sets up [Compose](https://docs.docker.com/compose/).
* [Docker Setup Docker](https://github.com/marketplace/actions/docker-setup-docker): installs Docker Engine.
* [Docker Setup QEMU](https://github.com/marketplace/actions/docker-setup-qemu): installs [QEMU](https://github.com/qemu/qemu) static binaries for multi-platform builds.
* [Docker Scout](https://github.com/docker/scout-action): analyze Docker images for security vulnerabilities.

Using Docker's actions provides an easy-to-use interface, while still allowing flexibility for customizing build parameters.

## [Examples](#examples)

If you're looking for examples on how to use the Docker GitHub Actions, refer to the following sections:

* [Add image annotations with GitHub Actions](/build/ci/github-actions/annotations/)

* [Add SBOM and provenance attestations with GitHub Actions](/build/ci/github-actions/attestations/)

* [Validating build configuration with GitHub Actions](/build/ci/github-actions/checks/)

* [Using secrets with GitHub Actions](/build/ci/github-actions/secrets/)

* [GitHub Actions build summary](/build/ci/github-actions/build-summary/)

* [Configuring your GitHub Actions builder](/build/ci/github-actions/configure-builder/)

* [Cache management with GitHub Actions](/build/ci/github-actions/cache/)

* [Copy image between registries with GitHub Actions](/build/ci/github-actions/copy-image-registries/)

* [Export to Docker with GitHub Actions](/build/ci/github-actions/export-docker/)

* [Docker GitHub Builder](/build/ci/github-actions/github-builder/)

* [Local registry with GitHub Actions](/build/ci/github-actions/local-registry/)

* [Multi-platform image with GitHub Actions](/build/ci/github-actions/multi-platform/)

* [Named contexts with GitHub Actions](/build/ci/github-actions/named-contexts/)

* [Push to multiple registries with GitHub Actions](/build/ci/github-actions/push-multi-registries/)

* [Reproducible builds with GitHub Actions](/build/ci/github-actions/reproducible-builds/)

* [Share built image between jobs with GitHub Actions](/build/ci/github-actions/share-image-jobs/)

* [Manage tags and labels with GitHub Actions](/build/ci/github-actions/manage-tags-labels/)

* [Test before push with GitHub Actions](/build/ci/github-actions/test-before-push/)

* [Update Docker Hub description with GitHub Actions](/build/ci/github-actions/update-dockerhub-desc/)

## [Get started with GitHub Actions](#get-started-with-github-actions)

The [Introduction to GitHub Actions with Docker](https://docs.docker.com/guides/gha/) guide walks you through the process of setting up and using Docker GitHub Actions for building Docker images, and pushing images to Docker Hub.

----
url: https://docs.docker.com/guides/testcontainers-java-micronaut-wiremock/
----

# Testing REST API integrations in Micronaut apps using WireMock

Table of contents

***

Learn how to create a Micronaut application that integrates with external REST APIs, then test those integrations using WireMock and the Testcontainers WireMock module.

**Time to complete** 20 minutes

In this guide, you'll learn how to:

* Create a Micronaut application that talks to external REST APIs
* Test external API integrations using WireMock
* Use the Testcontainers WireMock module to run WireMock as a Docker container

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-micronaut-wiremock/create-project/)

   Set up a Micronaut project with an external REST API integration using declarative HTTP clients.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-micronaut-wiremock/write-tests/)

   Test external REST API integrations using WireMock and the Testcontainers WireMock module.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-micronaut-wiremock/run-tests/)

   Run your Testcontainers WireMock integration tests and explore next steps.

----
url: https://docs.docker.com/reference/samples/php/
----

# PHP samples

| Name                                                                    | Description               |
| ----------------------------------------------------------------------- | ------------------------- |
| [PHP](https://github.com/docker/awesome-compose/tree/master/apache-php) | A sample PHP application. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/enterprise/enterprise-deployment/
----

# Deploy Docker Desktop

***

***

Docker Desktop supports scalable deployment options tailored for enterprise IT environments. Whether you're rolling out Docker across hundreds of developer workstations or enforcing consistent configuration through MDM solutions like Intune or Jamf, this section provides everything you need to install, configure, and manage Docker Desktop in a secure, repeatable way. Learn how to use MSI and PKG installers, configure default settings, control updates, and ensure compliance with your organization's policies—across Windows, macOS, and Linux systems.

### [MSI installer](/enterprise/enterprise-deployment/msi-install-and-configure/)

[Learn how to install Docker Desktop with the MSI installer.](/enterprise/enterprise-deployment/msi-install-and-configure/)

### [PKG installer](/enterprise/enterprise-deployment/pkg-install-and-configure/)

[Learn how to install Docker Desktop with the PKG installer.](/enterprise/enterprise-deployment/pkg-install-and-configure/)

### [MS Store](/enterprise/enterprise-deployment/ms-store/)

[Learn how to install Docker Desktop through the Microsoft Store.](/enterprise/enterprise-deployment/ms-store/)

### [Deploy with Intune](/enterprise/enterprise-deployment/use-intune/)

[Learn how to deploy Docker Desktop on Windows and macOS devices using Microsoft Intune.](/enterprise/enterprise-deployment/use-intune/)

### [Deploy with Jamf Pro](/enterprise/enterprise-deployment/use-jamf-pro/)

[Learn how to deploy Docker Desktop for Mac using Jamf Pro](/enterprise/enterprise-deployment/use-jamf-pro/)

### [Docker Desktop for Microsoft Dev Box](/enterprise/enterprise-deployment/dev-box/)

[Install Docker Desktop for Microsoft Dev Box via the Microsoft Azure Marketlplace](/enterprise/enterprise-deployment/dev-box/)

### [FAQs](/enterprise/enterprise-deployment/faq/)

[Common questions when deploying Docker Desktop](/enterprise/enterprise-deployment/faq/)

----
url: https://docs.docker.com/reference/cli/sbx/create/droid/
----

# sbx create droid

| Description | Create a sandbox for droid                |
| ----------- | ----------------------------------------- |
| Usage       | `sbx create droid PATH [PATH...] [flags]` |

## [Description](#description)

Create a sandbox with access to a host workspace for droid.

The workspace path is required and will be mounted inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Global options](#global-options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `-D, --debug`    |         | Enable debug logging                                                                                                                                                                                                   |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Examples](#examples)

```console
# Create in the current directory
sbx create droid .

# Create with a specific path
sbx create droid /path/to/project

# Create with additional read-only workspaces
sbx create droid . /path/to/docs:ro
```

----
url: https://docs.docker.com/build/metadata/attestations/
----

# Build attestations

***

Table of contents

***

Build attestations describe how an image was built, and what it contains. The attestations are created at build-time by BuildKit, and become attached to the final image as metadata.

The purpose of attestations is to make it possible to inspect an image and see where it comes from, who created it and how, and what it contains. This enables you to make informed decisions about how an image impacts the supply chain security of your application. It also enables the use of policy engines for validating images based on policy rules you've defined.

Two types of build attestations are available:

* Software Bill of Material (SBOM): list of software artifacts that an image contains, or that were used to build the image.
* Provenance: how an image was built.

## [Purpose of attestations](#purpose-of-attestations)

The use of open source and third-party packages is more widespread than ever before. Developers share and reuse code because it helps increase productivity, allowing teams to create better products, faster.

Importing and using code created elsewhere without vetting it introduces a severe security risk. Even if you do review the software that you consume, new zero-day vulnerabilities are frequently discovered, requiring development teams take action to remediate them.

Build attestations make it easier to see the contents of an image, and where it comes from. Use attestations to analyze and decide whether to use an image, or to see if images you are already using are exposed to vulnerabilities.

## [Creating attestations](#creating-attestations)

BuildKit generates the attestations when building the image. Provenance attestations with the `mode=min` level are added to images by default. The attestation records are wrapped in the in-toto JSON format and attached to the image index in a manifest for the final image.

You can customize attestation behavior using the `--provenance` and `--sbom` flags:

```bash
# Opt in to SBOM attestations:
docker buildx build --sbom=true .
# Opt in to max-level provenance attestations:
docker buildx build --provenance=mode=max .
# Opt out of provenance attestations:
docker buildx build --provenance=false .
```

You can also disable default provenance attestations by setting the [`BUILDX_NO_DEFAULT_ATTESTATIONS`](https://docs.docker.com/build/building/variables/#buildx_no_default_attestations) environment variable. See [Provenance attestation](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) for more details about provenance modes and options.

## [Storage](#storage)

BuildKit produces attestations in the [in-toto format](https://github.com/in-toto/attestation), as defined by the [in-toto framework](https://in-toto.io/), a standard supported by the Linux Foundation.

Attestations attach to images as a manifest in the image index. The data records of the attestations are stored as JSON blobs.

Because attestations attach to images as a manifest, it means that you can inspect the attestations for any image in a registry without having to pull the whole image.

All BuildKit exporters support attestations. The `local` and `tar` can't save the attestations to an image manifest, since it's outputting a directory of files or a tarball, not an image. Instead, these exporters write the attestations to one or more JSON files in the root directory of the export.

## [Example](#example)

The following example shows a truncated in-toto JSON representation of an SBOM attestation.

```json
{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://spdx.dev/Document",
  "subject": [
    {
      "name": "pkg:docker/<registry>/<image>@<tag/digest>?platform=<platform>",
      "digest": {
        "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862"
      }
    }
  ],
  "predicate": {
    "SPDXID": "SPDXRef-DOCUMENT",
    "creationInfo": {
      "created": "2022-12-15T11:47:54.546747383Z",
      "creators": ["Organization: Anchore, Inc", "Tool: syft-v0.60.3"],
      "licenseListVersion": "3.18"
    },
    "dataLicense": "CC0-1.0",
    "documentNamespace": "https://anchore.com/syft/dir/run/src/core-da0f600b-7f0a-4de0-8432-f83703e6bc4f",
    "name": "/run/src/core",
    // list of files that the image contains, e.g.:
    "files": [
      {
        "SPDXID": "SPDXRef-1ac501c94e2f9f81",
        "comment": "layerID: sha256:9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e",
        "fileName": "/bin/busybox",
        "licenseConcluded": "NOASSERTION"
      }
    ],
    // list of packages that were identified for this image:
    "packages": [
      {
        "name": "busybox",
        "originator": "Person: Sören Tempel <soeren+alpine@soeren-tempel.net>",
        "sourceInfo": "acquired package info from APK DB: lib/apk/db/installed",
        "versionInfo": "1.35.0-r17",
        "SPDXID": "SPDXRef-980737451f148c56",
        "description": "Size optimized toolbox of many common UNIX utilities",
        "downloadLocation": "https://busybox.net/",
        "licenseConcluded": "GPL-2.0-only",
        "licenseDeclared": "GPL-2.0-only"
        // ...
      }
    ],
    // files-packages relationship
    "relationships": [
      {
        "relatedSpdxElement": "SPDXRef-1ac501c94e2f9f81",
        "relationshipType": "CONTAINS",
        "spdxElementId": "SPDXRef-980737451f148c56"
      },
      ...
    ],
    "spdxVersion": "SPDX-2.2"
  }
}
```

To deep-dive into the specifics about how attestations are stored, see [Image Attestation Storage (BuildKit)](https://docs.docker.com/build/metadata/attestations/attestation-storage/).

## [Attestation manifest format](#attestation-manifest-format)

Attestations are stored as manifests, referenced by the image's index. Each *attestation manifest* refers to a single *image manifest* (one platform-variant of the image). Attestation manifests contain a single layer, the "value" of the attestation.

The following example shows the structure of an attestation manifest:

```json
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "size": 167,
    "digest": "sha256:916d7437a36dd0e258e64d9c5a373ca5c9618eeb1555e79bd82066e593f9afae"
  },
  "layers": [
    {
      "mediaType": "application/vnd.in-toto+json",
      "size": 1833349,
      "digest": "sha256:3138024b98ed5aa8e3008285a458cd25a987202f2500ce1a9d07d8e1420f5491",
      "annotations": {
        "in-toto.io/predicate-type": "https://spdx.dev/Document"
      }
    }
  ]
}
```

### [Attestations as OCI artifacts](#attestations-as-oci-artifacts)

You can configure the format of the attestation manifest using the [`oci-artifact` option](https://docs.docker.com/build/exporters/image-registry/#synopsis) for the `image` and `registry` exporters. If set to `true`, the structure of the attestation manifest changes as follows:

* An `artifactType` field is added to the attestation manifest, with a value of `application/vnd.docker.attestation.manifest.v1+json`.
* The `config` field is an [empty descriptor](https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidance-for-an-empty-descriptor) instead of a "dummy" config.
* A `subject` field is also added, pointing to the image manifest that the attestation refers to.

The following example shows an attestation with the OCI artifact format:

```json
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.docker.attestation.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.empty.v1+json",
    "size": 2,
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "data": "e30="
  },
  "layers": [
    {
      "mediaType": "application/vnd.in-toto+json",
      "size": 2208,
      "digest": "sha256:6d2f2c714a6bee3cf9e4d3cb9a966b629efea2dd8556ed81f19bd597b3325286",
      "annotations": {
        "in-toto.io/predicate-type": "https://slsa.dev/provenance/v0.2"
      }
    }
  ],
  "subject": {
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 1054,
    "digest": "sha256:bc2046336420a2852ecf915786c20f73c4c1b50d7803aae1fd30c971a7d1cead",
    "platform": {
      "architecture": "amd64",
      "os": "linux"
    }
  }
}
```

## [What's next](#whats-next)

Learn more about the available attestation types and how to use them:

* [Provenance](https://docs.docker.com/build/metadata/attestations/slsa-provenance/)
* [SBOM](https://docs.docker.com/build/metadata/attestations/sbom/)

----
url: https://docs.docker.com/reference/cli/docker/system/events/
----

# docker system events

***

| Description                                                               | Get real time events from the server |
| ------------------------------------------------------------------------- | ------------------------------------ |
| Usage                                                                     | `docker system events [OPTIONS]`     |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker events`                      |

## [Description](#description)

Use `docker events` to get real-time events from the server. These events differ per Docker object type. Different event types have different scopes. Local scoped events are only seen on the node they take place on, and Swarm scoped events are seen on all managers.

Only the last 256 log events are returned. You can use filters to further limit the number of events returned.

### [Object types](#object-types)

#### [Containers](#containers)

Docker containers report the following events:

* `attach`
* `commit`
* `copy`
* `create`
* `destroy`
* `detach`
* `die`
* `exec_create`
* `exec_detach`
* `exec_die`
* `exec_start`
* `export`
* `health_status`
* `kill`
* `oom`
* `pause`
* `rename`
* `resize`
* `restart`
* `start`
* `stop`
* `top`
* `unpause`
* `update`

#### [Images](#images)

Docker images report the following events:

* `delete`
* `import`
* `load`
* `pull`
* `push`
* `save`
* `tag`
* `untag`

#### [Plugins](#plugins)

Docker plugins report the following events:

* `enable`
* `disable`
* `install`
* `remove`

#### [Volumes](#volumes)

Docker volumes report the following events:

* `create`
* `destroy`
* `mount`
* `unmount`

#### [Networks](#networks)

Docker networks report the following events:

* `create`
* `connect`
* `destroy`
* `disconnect`
* `remove`

#### [Daemons](#daemons)

Docker daemons report the following events:

* `reload`

#### [Services](#services)

Docker services report the following events:

* `create`
* `remove`
* `update`

#### [Nodes](#nodes)

Docker nodes report the following events:

* `create`
* `remove`
* `update`

#### [Secrets](#secrets)

Docker secrets report the following events:

* `create`
* `remove`
* `update`

#### [Configs](#configs)

Docker configs report the following events:

* `create`
* `remove`
* `update`

### [Limiting, filtering, and formatting the output](#limiting-filtering-and-formatting-the-output)

#### [Limit events by time (--since, --until)](#since)

The `--since` and `--until` parameters can be Unix timestamps, date formatted timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the client machine’s time. If you do not provide the `--since` option, the command returns only new and/or live events. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local timezone on the client will be used if you do not provide either a `Z` or a `+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds\[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long.

Only the last 256 log events are returned. You can use filters to further limit the number of events returned.

#### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is of "key=value". If you would like to use multiple filters, pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)

Using the same filter multiple times is interpreted as a logical `OR`; for example, `--filter container=588a23dac085 --filter container=a8f7720b8c22` displays events for container `588a23dac085` or container `a8f7720b8c22`.

Using multiple filters is interpreted as a logical `AND`; for example, `--filter container=588a23dac085 --filter event=start` displays events for container `588a23dac085` and where the event type is `start`.

The currently supported filters are:

* config (`config=<name or id>`)
* container (`container=<name or id>`)
* daemon (`daemon=<name or id>`)
* event (`event=<event action>`)
* image (`image=<repository or tag>`)
* label (`label=<key>` or `label=<key>=<value>`)
* network (`network=<name or id>`)
* node (`node=<id>`)
* plugin (`plugin=<name or id>`)
* scope (`scope=<local or swarm>`)
* secret (`secret=<name or id>`)
* service (`service=<name or id>`)
* type (`type=<container or image or volume or network or daemon or plugin or service or node or secret or config>`)
* volume (`volume=<name>`)

#### [Format the output (--format)](#format)

If you specify a format (`--format`), the given template is executed instead of the default format. Go's [text/template](https://pkg.go.dev/text/template) package describes all the details of the format.

If a format is set to `{{json .}}`, events are streamed in the JSON Lines format. For information about JSON Lines, see <https://jsonlines.org/>.

## [Options](#options)

| Option         | Default | Description                                                                                                                                                                                                                             |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --filter` |         | Filter output based on conditions provided                                                                                                                                                                                              |
| `--format`     |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `--since`      |         | Show all events created since timestamp                                                                                                                                                                                                 |
| `--until`      |         | Stream events until this timestamp                                                                                                                                                                                                      |

## [Examples](#examples)

### [Basic example](#basic-example)

You'll need two shells for this example.

**Shell 1: Listening for events:**

```console
$ docker events
```

**Shell 2: Start and Stop containers:**

```console
$ docker create --name test alpine:latest top
$ docker start test
$ docker stop test
```

**Shell 1: (Again .. now showing events):**

```console
2017-01-05T00:35:58.859401177+08:00 container create 0fdb48addc82871eb34eb23a847cfd033dedd1a0a37bef2e6d9eb3870fc7ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1f5ceda09d4300f3a846f0acfaa9a8bb0d89e775eb744c5acecd60e0529e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
```

To exit the `docker events` command, use `CTRL+C`.

### [Filter events by time](#filter-events-by-time)

You can filter the output by an absolute timestamp or relative time on the host machine, using the following different time formats:

```console
$ docker events --since 1483283804
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)

$ docker events --since '2017-01-05'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)

$ docker events --since '2013-09-03T15:49:29'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)

$ docker events --since '10m'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:36:09.830268747+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:36:09.840186338+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:36:09.880113663+08:00 network disconnect e2e...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:09.890214053+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)

$ docker events --since '2017-01-05T00:35:30' --until '2017-01-05T00:36:05'
2017-01-05T00:35:41.241772953+08:00 volume create testVol (driver=local)
2017-01-05T00:35:58.859401177+08:00 container create d9cd...4d70 (image=alpine:latest, name=test)
2017-01-05T00:36:04.703631903+08:00 network connect e2e1...29e2 (container=0fdb...ff37, name=bridge, type=bridge)
2017-01-05T00:36:04.795031609+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
```

### [Filter events by criteria](#filter-events-by-criteria)

The following commands show several different ways to filter the `docker event` output.

```console
$ docker events --filter 'event=stop'

2017-01-05T00:40:22.880175420+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:41:17.888104182+08:00 container stop 2a8f...4e78 (image=alpine, name=kickass_brattain)

$ docker events --filter 'image=alpine'

2017-01-05T00:41:55.784240236+08:00 container create d9cd...4d70 (image=alpine, name=happy_meitner)
2017-01-05T00:41:55.913156783+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
2017-01-05T00:42:01.106875249+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=15)
2017-01-05T00:42:11.111934041+08:00 container kill d9cd...4d70 (image=alpine, name=happy_meitner, signal=9)
2017-01-05T00:42:11.119578204+08:00 container die d9cd...4d70 (exitCode=137, image=alpine, name=happy_meitner)
2017-01-05T00:42:11.173276611+08:00 container stop d9cd...4d70 (image=alpine, name=happy_meitner)

$ docker events --filter 'container=test'

2017-01-05T00:43:00.139719934+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:43:09.259951086+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=15)
2017-01-05T00:43:09.270102715+08:00 container die 0fdb...ff37 (exitCode=143, image=alpine:latest, name=test)
2017-01-05T00:43:09.312556440+08:00 container stop 0fdb...ff37 (image=alpine:latest, name=test)

$ docker events --filter 'container=test' --filter 'container=d9cdb1525ea8'

2017-01-05T00:44:11.517071981+08:00 container start 0fdb...ff37 (image=alpine:latest, name=test)
2017-01-05T00:44:17.685870901+08:00 container start d9cd...4d70 (image=alpine, name=happy_meitner)
2017-01-05T00:44:29.757658470+08:00 container kill 0fdb...ff37 (image=alpine:latest, name=test, signal=9)
2017-01-05T00:44:29.767718510+08:00 container die 0fdb...ff37 (exitCode=137, image=alpine:latest, name=test)
2017-01-05T00:44:29.815798344+08:00 container destroy 0fdb...ff37 (image=alpine:latest, name=test)

$ docker events --filter 'container=test' --filter 'event=stop'

2017-01-05T00:46:13.664099505+08:00 container stop a9d1...e130 (image=alpine, name=test)

$ docker events --filter 'type=volume'

2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562f...5025, destination=/foo, driver=local, propagation=rprivate)
2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562f...5025, driver=local)
2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)

$ docker events --filter 'type=network'

2015-12-23T21:38:24.705709133Z network create 8b11...2c5b (name=test-event-network-local, type=bridge)
2015-12-23T21:38:25.119625123Z network connect 8b11...2c5b (name=test-event-network-local, container=b4be...c54e, type=bridge)

$ docker events --filter 'container=container_1' --filter 'container=container_2'

2014-09-03T15:49:29.999999999Z07:00 container die 4386fb97867d (image=ubuntu:24.04)
2014-05-10T17:42:14.999999999Z07:00 container stop 4386fb97867d (image=ubuntu:24.04)
2014-05-10T17:42:14.999999999Z07:00 container die 7805c1d35632 (imager=redis:7.2)
2014-09-03T15:49:29.999999999Z07:00 container stop 7805c1d35632 (image=redis:7.2)

$ docker events --filter 'type=volume'

2015-12-23T21:05:28.136212689Z volume create test-event-volume-local (driver=local)
2015-12-23T21:05:28.383462717Z volume mount test-event-volume-local (read/write=true, container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, destination=/foo, driver=local, propagation=rprivate)
2015-12-23T21:05:28.650314265Z volume unmount test-event-volume-local (container=562fe10671e9273da25eed36cdce26159085ac7ee6707105fd534866340a5025, driver=local)
2015-12-23T21:05:28.716218405Z volume destroy test-event-volume-local (driver=local)

$ docker events --filter 'type=network'

2015-12-23T21:38:24.705709133Z network create 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, type=bridge)
2015-12-23T21:38:25.119625123Z network connect 8b111217944ba0ba844a65b13efcd57dc494932ee2527577758f939315ba2c5b (name=test-event-network-local, container=b4be644031a3d90b400f88ab3d4bdf4dc23adb250e696b6328b85441abe2c54e, type=bridge)

$ docker events --filter 'type=plugin'

2016-07-25T17:30:14.825557616Z plugin pull ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)
2016-07-25T17:30:14.888127370Z plugin enable ec7b87f2ce84330fe076e666f17dfc049d2d7ae0b8190763de94e1f2d105993f (name=tiborvass/sample-volume-plugin:latest)

$ docker events -f type=service

2017-07-12T06:34:07.999446625Z service create wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)
2017-07-12T06:34:21.405496207Z service remove wj64st89fzgchxnhiqpn8p4oj (name=reverent_albattani)

$ docker events -f type=node

2017-07-12T06:21:51.951586759Z node update 3xyz5ttp1a253q74z1thwywk9 (name=ip-172-31-23-42, state.new=ready, state.old=unknown)

$ docker events -f type=secret

2017-07-12T06:32:13.915704367Z secret create s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)
2017-07-12T06:32:37.052647783Z secret remove s8o6tmlnndrgzbmdilyy5ymju (name=new_secret)

$  docker events -f type=config
2017-07-12T06:44:13.349037127Z config create u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)
2017-07-12T06:44:36.327694184Z config remove u96zlvzdfsyb9sg4mhyxfh3rl (name=abc)

$ docker events --filter 'scope=swarm'

2017-07-10T07:46:50.250024503Z service create m8qcxu8081woyof7w3jaax6gk (name=affectionate_wilson)
2017-07-10T07:47:31.093797134Z secret create 6g5pufzsv438p9tbvl9j94od4 (name=new_secret)
```

### [Format the output](#format-the-output)

```console
$ docker events --filter 'type=container' --format 'Type={{.Type}}  Status={{.Status}}  ID={{.ID}}'

Type=container  Status=create  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container  Status=attach  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container  Status=start  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container  Status=resize  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container  Status=die  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
Type=container  Status=destroy  ID=2ee349dac409e97974ce8d01b70d250b85e0ba8189299c126a87812311951e26
```

#### [Format as JSON](#format-as-json)

To list events in JSON format, use the `json` directive, which is the same `--format '{{ json . }}`.

```console
$ docker events --format json

{"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
{"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
{"Type":"network","Action":"connect","Actor":{"ID":"1b50a5bf755f6021dfa78e..
{"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42..
{"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
```

----
url: https://docs.docker.com/docker-hub/repos/create/
----

# Create a repository

***

***

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

3. Near the top-right corner, select **Create repository**.

4. Select a **Namespace**.

   You can choose to locate it under your own user account, or under any organization where you are an owner or editor.

5. Specify the **Repository Name**.

   The repository name needs to:

   * Be unique
   * Have between 2 and 255 characters
   * Only contain lowercase letters, numbers, hyphens (`-`), and underscores (`_`)

   > Note
   >
   > You can't rename a Docker Hub repository once it's created.

6. Specify the **Short description**.

   The description can be up to 100 characters. It appears in search results.

7. Select the default visibility.

   * **Public**: The repository appears in Docker Hub search results and can be pulled by everyone.
   * **Private**: The repository doesn't appear in Docker Hub search results and is only accessible to you and collaborators. In addition, if you selected an organization's namespace, then the repository is accessible to those with applicable roles or permissions. For more details, see [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/).

   > Note
   >
   > For organizations creating a new repository, if you're unsure which visibility to choose, then Docker recommends that you select **Private**.

8. Select **Create**.

After the repository is created, the **General** page appears. You are now able to manage:

* [Repository information](https://docs.docker.com/docker-hub/repos/manage/information/)
* [Access](https://docs.docker.com/docker-hub/repos/manage/access/)
* [Images](https://docs.docker.com/docker-hub/repos/manage/hub-images/)
* [Automated builds](https://docs.docker.com/docker-hub/repos/manage/builds/)
* [Webhooks](https://docs.docker.com/docker-hub/repos/manage/webhooks/)
* [Image security insights](https://docs.docker.com/docker-hub/repos/manage/vulnerability-scanning/)

----
url: https://docs.docker.com/reference/cli/docker/login/
----

# docker login

***

| Description | Authenticate to a registry        |
| ----------- | --------------------------------- |
| Usage       | `docker login [OPTIONS] [SERVER]` |

## [Description](#description)

Authenticate to a registry.

You can authenticate to any public or private registry for which you have credentials. Authentication may be required for pulling and pushing images. Other commands, such as `docker scout` and `docker build`, may also require authentication to access subscription-only features or data related to your Docker organization.

Authentication credentials are stored in the configured [credential store](#credential-stores). If you use Docker Desktop, credentials are automatically saved to the native keychain of your operating system. If you're not using Docker Desktop, you can configure the credential store in the Docker configuration file, which is located at `$HOME/.docker/config.json` on Linux or `%USERPROFILE%/.docker/config.json` on Windows. If you don't configure a credential store, Docker stores credentials in the `config.json` file in a base64-encoded format. This method is less secure than configuring and using a credential store.

`docker login` also supports [credential helpers](#credential-helpers) to help you handle credentials for specific registries.

### [Authentication methods](#authentication-methods)

You can authenticate to a registry using a username and access token or password. Docker Hub also supports a web-based sign-in flow, which signs you in to your Docker account without entering your password. For Docker Hub, the `docker login` command uses a device code flow by default, unless the `--username` flag is specified. The device code flow is a secure way to sign in. See [Authenticate to Docker Hub using device code](#authenticate-to-docker-hub-with-web-based-login).

### [Credential stores](#credential-stores)

The Docker Engine can keep user credentials in an external credential store, such as the native keychain of the operating system. Using an external store is more secure than storing credentials in the Docker configuration file.

To use a credential store, you need an external helper program to interact with a specific keychain or external store. Docker requires the helper program to be in the client's host `$PATH`.

You can download the helpers from the `docker-credential-helpers` [releases page](https://github.com/docker/docker-credential-helpers/releases). Helpers are available for the following credential stores:

* D-Bus Secret Service
* Apple macOS keychain
* Microsoft Windows Credential Manager
* [pass](https://www.passwordstore.org/)

With Docker Desktop, the credential store is already installed and configured for you. Unless you want to change the credential store used by Docker Desktop, you can skip the following steps.

#### [Configure the credential store](#configure-the-credential-store)

You need to specify the credential store in `$HOME/.docker/config.json` to tell the Docker Engine to use it. The value of the config property should be the suffix of the program to use (i.e. everything after `docker-credential-`). For example, to use `docker-credential-osxkeychain`:

```json
{
  "credsStore": "osxkeychain"
}
```

If you are currently logged in, run `docker logout` to remove the credentials from the file and run `docker login` again.

#### [Default behavior](#default-behavior)

By default, Docker looks for the native binary on each of the platforms, i.e. `osxkeychain` on macOS, `wincred` on Windows, and `pass` on Linux. A special case is that on Linux, Docker will fall back to the `secretservice` binary if it cannot find the `pass` binary. If none of these binaries are present, it stores the base64-encoded credentials in the `config.json` configuration file.

#### [Credential helper protocol](#credential-helper-protocol)

Credential helpers can be any program or script that implements the credential helper protocol. This protocol is inspired by Git, but differs in the information shared.

The helpers always use the first argument in the command to identify the action. There are only three possible values for that argument: `store`, `get`, and `erase`.

The `store` command takes a JSON payload from the standard input. That payload carries the server address, to identify the credential, the username, and either a password or an identity token.

```json
{
  "ServerURL": "https://index.docker.io/v1",
  "Username": "david",
  "Secret": "passw0rd1"
}
```

If the secret being stored is an identity token, the Username should be set to `<token>`.

The `store` command can write error messages to `STDOUT` that the Docker Engine will show if there was an issue.

The `get` command takes a string payload from the standard input. That payload carries the server address that the Docker Engine needs credentials for. This is an example of that payload: `https://index.docker.io/v1`.

The `get` command writes a JSON payload to `STDOUT`. Docker reads the user name and password from this payload:

```json
{
  "Username": "david",
  "Secret": "passw0rd1"
}
```

The `erase` command takes a string payload from `STDIN`. That payload carries the server address that the Docker Engine wants to remove credentials for. This is an example of that payload: `https://index.docker.io/v1`.

The `erase` command can write error messages to `STDOUT` that the Docker Engine will show if there was an issue.

### [Credential helpers](#credential-helpers)

Credential helpers are similar to [credential stores](#credential-stores), but act as the designated programs to handle credentials for specific registries. The default credential store will not be used for operations concerning credentials of the specified registries.

#### [Configure credential helpers](#configure-credential-helpers)

If you are currently logged in, run `docker logout` to remove the credentials from the default store.

Credential helpers are specified in a similar way to `credsStore`, but allow for multiple helpers to be configured at a time. Keys specify the registry domain, and values specify the suffix of the program to use (i.e. everything after `docker-credential-`). For example:

```json
{
  "credHelpers": {
    "myregistry.example.com": "secretservice",
    "docker.internal.example": "pass",
  }
}
```

## [Options](#options)

| Option                                | Default | Description                                                 |
| ------------------------------------- | ------- | ----------------------------------------------------------- |
| `-p, --password`                      |         | Password or Personal Access Token (PAT)                     |
| [`--password-stdin`](#password-stdin) |         | Take the Password or Personal Access Token (PAT) from stdin |
| [`-u, --username`](#username)         |         | Username                                                    |

## [Examples](#examples)

### [Authenticate to Docker Hub with web-based login](#authenticate-to-docker-hub-with-web-based-login)

By default, the `docker login` command authenticates to Docker Hub, using a device code flow. This flow lets you authenticate to Docker Hub without entering your password. Instead, you visit a URL in your web browser, enter a code, and authenticate.

```console
$ docker login

USING WEB-BASED LOGIN
To sign in with credentials on the command line, use 'docker login -u <username>'

Your one-time device confirmation code is: LNFR-PGCJ
Press ENTER to open your browser or submit your device code here: https://login.docker.com/activate

Waiting for authentication in the browser…
```

After entering the code in your browser, you are authenticated to Docker Hub using the account you're currently signed in with on the Docker Hub website or in Docker Desktop. If you aren't signed in, you are prompted to sign in after entering the device code.

### [Authenticate to a self-hosted registry](#authenticate-to-a-self-hosted-registry)

If you want to authenticate to a self-hosted registry you can specify this by adding the server name.

```console
$ docker login registry.example.com
```

By default, the `docker login` command assumes that the registry listens on port 443 or 80. If the registry listens on a different port, you can specify it by adding the port number to the server name.

```console
$ docker login registry.example.com:1337
```

> Note
>
> Registry addresses should not include URL path components, only the hostname and (optionally) the port. Registry addresses with URL path components may result in an error. For example, `docker login registry.example.com/foo/` is incorrect, while `docker login registry.example.com` is correct.
>
> The exception to this rule is the Docker Hub registry, which may use the `/v1/` path component in the address for historical reasons.

### [Authenticate to a registry with a username and password](#username)

To authenticate to a registry with a username and password, you can use the `--username` or `-u` flag. The following example authenticates to Docker Hub with the username `moby`. The password is entered interactively.

```console
$ docker login -u moby
```

### [Provide a password using STDIN (--password-stdin)](#password-stdin)

To run the `docker login` command non-interactively, you can set the `--password-stdin` flag to provide a password through `STDIN`. Using `STDIN` prevents the password from ending up in the shell's history, or log-files.

The following example reads a password from a file, and passes it to the `docker login` command using `STDIN`:

```console
$ cat ~/my_password.txt | docker login --username foo --password-stdin
```

----
url: https://docs.docker.com/build/ci/github-actions/github-builder/architecture/
----

# Docker GitHub Builder architecture

***

Table of contents

***

Docker GitHub Builder separates repository orchestration from build implementation. A consuming repository decides when a build runs, which permissions and secrets are granted, and which inputs are passed. The reusable workflow in [`docker/github-builder` repository](https://github.com/docker/github-builder) owns the build implementation itself. That split keeps repository workflows short while centralizing BuildKit, caching, provenance, SBOM generation, signing, and multi-platform assembly in one Docker-maintained path.

## [Core architecture](#core-architecture)

A caller workflow invokes either [`build.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/build/) or [`bake.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/bake/). [`build.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/build/) is the entrypoint for Dockerfile-oriented builds. [`bake.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/bake/) is the entrypoint for Bake-oriented builds, where the Bake definition remains the source of truth for targets and overrides. In both cases the caller still owns repository policy, including triggers, branch conditions, permissions, secrets, target selection, metadata inputs, and the choice between image output and local output.

Inside the reusable workflow, the first phase prepares the build. It validates the incoming inputs, resolves the runner config, and expands a multi-platform request into one job per platform. The execution model is easiest to picture as a matrix where `linux/amd64` runs on `ubuntu-24.04` and `linux/arm64` runs on `ubuntu-24.04-arm`. Each platform job builds independently, then the workflow finalizes the result into one caller-facing output contract.

```yaml
requested platforms:
  linux/amd64,linux/arm64

conceptual platform jobs:
  linux/amd64 -> ubuntu-24.04
  linux/arm64 -> ubuntu-24.04-arm
```

### [Runner selection](#runner-selection)

The `runner` input accepts either a single GitHub-hosted Linux runner label or a newline-delimited platform mapping.

The default value is a platform mapping that uses GitHub-hosted Ubuntu runners:

```yaml
runner: |
  default=ubuntu-24.04
  linux/arm=ubuntu-24.04-arm
  linux/arm64=ubuntu-24.04-arm
```

In the platform job, the runner label resolves to a single value:

```yaml
runner: ubuntu-24.04
```

A mapping must define a `default` runner. Other keys are platform prefixes, and the most specific matching prefix wins. For example, `linux/arm` matches variants such as `linux/arm/v7`, while `linux/arm64` is a separate prefix:

In the following example, `linux` matches Linux platforms that do not match a longer prefix. The `default` key is still required because it is the fallback when no platform prefix matches.

```yaml
runner: |
  default=ubuntu-24.04
  linux=ubuntu-24.04
  linux/arm=ubuntu-24.04-arm
  linux/arm64=ubuntu-24.04-arm
```

The reusable workflows require GitHub-hosted Linux runners. The legacy `auto`, `amd64`, and `arm64` values are still accepted for compatibility, but emit deprecation warnings. Use an explicit runner label or platform mapping instead.

## [Execution path](#execution-path)

The execution path stays short on purpose. The consuming repository calls the reusable workflow. The reusable workflow prepares the build, runs the per-platform jobs, and finalizes the result. For image output, finalization produces a registry image and multi-platform manifest. For local output, finalization merges the per-platform files and can upload the merged result as a GitHub artifact. The caller does not need to reconstruct how Buildx, BuildKit, caching, or manifest assembly were wired together.

## [The two reusable entrypoints](#the-two-reusable-entrypoints)

[`build.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/build/) is the better fit when the build is already expressed as a Dockerfile-oriented workflow. It lines up naturally with concepts such as `context`, `file`, `target`, `build-args`, `labels`, `annotations`, and `platforms`. This is the entrypoint that feels closest to `docker/build-push-action`, except the workflow implementation is centralized.

[`bake.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/bake/) is the better fit when the repository already uses Bake as the build definition. It preserves the Bake model, including target resolution, `files`, `set`, and `vars`, while still routing execution through the same Docker-maintained build path. One important architectural detail is that the Bake workflow is centered on one target per workflow call, which keeps provenance, digest handling, and final manifest assembly scoped to one build unit at a time.

## [Output model](#output-model)

The reusable workflows expose a stable set of caller-facing outputs so downstream jobs can consume results without understanding the internal job graph. In practice, the main values are `digest`, `meta-json`, `artifact-name`, `output-type`, and `signed`. That contract matters because it keeps promotion, publishing, or follow-on automation decoupled from the mechanics of runner selection and per-platform assembly.

## [Examples](#examples)

### [Dockerfile-oriented image build](#dockerfile-oriented-image-build)

The following example shows the shape of a multi-platform image build driven by [`build.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/build/).

```yaml
name: ci

on:
  push:
    branches:
      - "main"
    tags:
      - "v*"
  pull_request:

permissions:
  contents: read

jobs:
  build:
    uses: docker/github-builder/.github/workflows/build.yml@v1
    permissions:
      contents: read
      id-token: write
    with:
      output: image
      push: ${{ github.event_name != 'pull_request' }}
      platforms: linux/amd64,linux/arm64
      meta-images: name/app
      meta-tags: |
        type=ref,event=branch
        type=ref,event=pr
        type=semver,pattern={{version}}
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
```

This call is small because the reusable workflow absorbs the heavy lifting. The repository decides when the build should run and which inputs it wants, while the shared implementation handles Buildx setup, BuildKit configuration, platform fan-out, metadata generation, provenance, SBOM generation, signing, and final manifest creation.

### [Bake-oriented local output](#bake-oriented-local-output)

The following example shows the shape of a Bake call that exports local output and uploads the merged artifact.

```yaml
name: ci

on:
  pull_request:

permissions:
  contents: read

jobs:
  bake:
    uses: docker/github-builder/.github/workflows/bake.yml@v1
    permissions:
      contents: read
      id-token: write
    with:
      output: local
      target: binaries
      artifact-upload: true
      artifact-name: bake-output
```

This form is useful when the repository already keeps its build definition in Bake and wants to preserve that source of truth. The workflow injects the local output behavior into the Bake run, executes the target per platform when needed, and merges the result into one caller-facing artifact.

## [Why this architecture works](#why-this-architecture-works)

### [Performance](#performance)

The performance story comes from native platform fan-out, shared BuildKit configuration, and centralized cache handling. Multi-platform work can be spread across matching GitHub-hosted runners instead of forcing every architecture through one build machine. That reduces emulation pressure, shortens the critical path for cross-platform builds, and gives every consuming repository the same optimized build baseline.

### [Security](#security)

The security model comes from putting the build implementation in Docker-maintained reusable workflows instead of ad hoc job steps in each consumer repository. The caller still controls permissions and secrets, but the build logic itself is centrally reviewed and versioned. The project also treats provenance, SBOM generation, and signing as first-class concerns, which strengthens the trust boundary between repository orchestration and artifact production.

### [Isolation and reliability](#isolation-and-reliability)

The reliability story comes from separation of concerns. The consuming repository orchestrates the build. The reusable workflow executes the build. That reduces CI drift, removes repeated glue code from repositories, and makes the outcome easier to reason about because the caller sees a stable contract instead of a large custom job definition.

----
url: https://docs.docker.com/reference/cli/docker/checkpoint/
----

# docker checkpoint

***

| Description | Manage checkpoints  |
| ----------- | ------------------- |
| Usage       | `docker checkpoint` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Checkpoint and Restore is an experimental feature that allows you to freeze a running container by specifying a checkpoint, which turns the container state into a collection of files on disk. Later, the container can be restored from the point it was frozen.

This is accomplished using a tool called [CRIU](https://criu.org), which is an external dependency of this feature. A good overview of the history of checkpoint and restore in Docker is available in this [Kubernetes blog post](https://kubernetes.io/blog/2015/07/how-did-quake-demo-from-dockercon-work/).

### [Installing CRIU](#installing-criu)

If you use a Debian system, you can add the CRIU PPA and install with `apt-get` [from the CRIU launchpad](https://launchpad.net/~criu/+archive/ubuntu/ppa).

Alternatively, you can [build CRIU from source](https://criu.org/Installation).

You need at least version 2.0 of CRIU to run checkpoint and restore in Docker.

### [Use cases for checkpoint and restore](#use-cases-for-checkpoint-and-restore)

This feature is currently focused on single-host use cases for checkpoint and restore. Here are a few:

* Restarting the host machine without stopping/starting containers
* Speeding up the start time of slow start applications
* "Rewinding" processes to an earlier point in time
* "Forensic debugging" of running processes

Another primary use case of checkpoint and restore outside of Docker is the live migration of a server from one machine to another. This is possible with the current implementation, but not currently a priority (and so the workflow is not optimized for the task).

### [Using checkpoint and restore](#using-checkpoint-and-restore)

A new top level command `docker checkpoint` is introduced, with three subcommands:

* `docker checkpoint create` (creates a new checkpoint)
* `docker checkpoint ls` (lists existing checkpoints)
* `docker checkpoint rm` (deletes an existing checkpoint)

Additionally, a `--checkpoint` flag is added to the `docker container start` command.

The options for `docker checkpoint create`:

```console
Usage:  docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT

Create a checkpoint from a running container

  --leave-running=false    Leave the container running after checkpoint
  --checkpoint-dir         Use a custom checkpoint storage directory
```

And to restore a container:

```console
Usage:  docker start --checkpoint CHECKPOINT_ID [OTHER OPTIONS] CONTAINER
```

Example of using checkpoint and restore on a container:

```console
$ docker run --security-opt=seccomp:unconfined --name cr -d busybox /bin/sh -c 'i=0; while true; do echo $i; i=$(expr $i + 1); sleep 1; done'
abc0123

$ docker checkpoint create cr checkpoint1

# <later>
$ docker start --checkpoint checkpoint1 cr
abc0123
```

This process just logs an incrementing counter to stdout. If you run `docker logs` in-between running/checkpoint/restoring, you should see that the counter increases while the process is running, stops while it's frozen, and resumes from the point it left off once you restore.

### [Known limitations](#known-limitations)

`seccomp` is only supported by CRIU in very up-to-date kernels.

External terminals (i.e. `docker run -t ..`) aren't supported. If you try to create a checkpoint for a container with an external terminal, it fails:

```console
$ docker checkpoint create cr checkpoint1
Error response from daemon: Cannot checkpoint container c1: rpc error: code = 2 desc = exit status 1: "criu failed: type NOTIFY errno 0\nlog file: /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log\n"

$ cat /var/lib/docker/containers/eb62ebdbf237ce1a8736d2ae3c7d88601fc0a50235b0ba767b559a1f3c5a600b/checkpoints/checkpoint1/criu.work/dump.log
Error (mount.c:740): mnt: 126:./dev/console doesn't have a proper root mount
```

## [Subcommands](#subcommands)

| Command                                                                                       | Description                                  |
| --------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [`docker checkpoint create`](https://docs.docker.com/reference/cli/docker/checkpoint/create/) | Create a checkpoint from a running container |
| [`docker checkpoint ls`](https://docs.docker.com/reference/cli/docker/checkpoint/ls/)         | List checkpoints for a container             |
| [`docker checkpoint rm`](https://docs.docker.com/reference/cli/docker/checkpoint/rm/)         | Remove a checkpoint                          |

----
url: https://docs.docker.com/guides/python/deploy/
----

# Test your Python deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Use containers for Python development](https://docs.docker.com/guides/python/develop/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your `python-docker-dev-example` directory, create a file named `docker-postgres-kubernetes.yaml`. Open the file in an IDE or text editor and add the following contents.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:18
          ports:
            - containerPort: 5432
          env:
            - name: POSTGRES_DB
              value: example
            - name: POSTGRES_USER
              value: postgres
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: postgres-secret
                  key: POSTGRES_PASSWORD
          volumeMounts:
            - name: postgres-data
              mountPath: /var/lib/postgresql
      volumes:
        - name: postgres-data
          persistentVolumeClaim:
            claimName: postgres-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: default
spec:
  ports:
    - port: 5432
  selector:
    app: postgres
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-pvc
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: Secret
metadata:
  name: postgres-secret
  namespace: default
type: Opaque
data:
  POSTGRES_PASSWORD: cG9zdGdyZXNfcGFzc3dvcmQ= # Base64 encoded password (e.g., 'postgres_password')
```

In your `python-docker-dev-example` directory, create a file named `docker-python-kubernetes.yaml`. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the repository name that you created in [Configure CI/CD for your Python application](https://docs.docker.com/guides/python/configure-github-actions/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-python-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: fastapi
  template:
    metadata:
      labels:
        service: fastapi
    spec:
      containers:
        - name: fastapi-service
          image: DOCKER_USERNAME/REPO_NAME
          imagePullPolicy: Always
          env:
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: postgres-secret
                  key: POSTGRES_PASSWORD
            - name: POSTGRES_USER
              value: postgres
            - name: POSTGRES_DB
              value: example
            - name: POSTGRES_SERVER
              value: postgres
            - name: POSTGRES_PORT
              value: "5432"
          ports:
            - containerPort: 8001
---
apiVersion: v1
kind: Service
metadata:
  name: service-entrypoint
  namespace: default
spec:
  type: NodePort
  selector:
    service: fastapi
  ports:
    - port: 8001
      targetPort: 8001
      nodePort: 30001
```

In these Kubernetes YAML file, there are various objects, separated by the `---`:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your Python application](https://docs.docker.com/guides/python/configure-github-actions/).
* A Service, which will define how the ports are mapped in the containers.
* A PersistentVolumeClaim, to define a storage that will be persistent through restarts for the database.
* A Secret, Keeping the database password as an example using secret kubernetes resource.
* A NodePort service, which will route traffic from port 30001 on your host to port 8001 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

> Note
>
> * The `NodePort` service is good for development/testing purposes. For production you should implement an [ingress-controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to `python-docker-dev-example` and deploy your database to Kubernetes.

   ```console
   $ kubectl apply -f docker-postgres-kubernetes.yaml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```console
   deployment.apps/postgres created
   service/postgres created
   persistentvolumeclaim/postgres-pvc created
   secret/postgres-secret created
   ```

   Now, deploy your python application.

   ```console
   kubectl apply -f docker-python-kubernetes.yaml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```console
   deployment.apps/docker-python-demo created
   service/service-entrypoint created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```console
   NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
   docker-python-demo   1/1     1            1           48s
   postgres             1/1     1            1           2m39s
   ```

   This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```console
   NAME                 TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)          AGE
   kubernetes           ClusterIP   10.43.0.1      <none>        443/TCP          13h
   postgres             ClusterIP   10.43.209.25   <none>        5432/TCP         3m10s
   service-entrypoint   NodePort    10.43.67.120   <none>        8001:30001/TCP   79s
   ```

   In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP and the internal `ClusterIP` `postgres` with the port `5432` open to accept connections from you python app.

3. In a terminal, curl the service. Note that a database was not deployed in this example.

   ```console
   $ curl http://localhost:30001/
   Hello, Docker!!!
   ```

4. Run the following commands to tear down your application.

   ```console
   $ kubectl delete -f docker-python-kubernetes.yaml
   $ kubectl delete -f docker-postgres-kubernetes.yaml
   ```

## [Summary](#summary)

In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine.

Related information:

* [Kubernetes documentation](https://kubernetes.io/docs/home/)
* [Deploy on Kubernetes with Docker Desktop](https://docs.docker.com/desktop/use-desktop/kubernetes/)
* [Swarm mode overview](https://docs.docker.com/engine/swarm/)

----
url: https://docs.docker.com/security/2fa/recover-hub-account/
----

# Recover your Docker account

***

Table of contents

***

This page explains how to recover your Docker account and manage recovery codes for two-factor authentication.

## [Generate a new recovery code](#generate-a-new-recovery-code)

If you lost your two-factor authentication recovery code but still have access to your Docker Hub account, you can generate a new recovery code.

1. Sign in to your [Docker account](https://app.docker.com/login) with your username and password.
2. Select your avatar and from the drop-down menu, select **Account settings**.
3. Select **2FA**.
4. Enter your password, then select **Confirm**.
5. Select **Generate new code**.

This generates a new code. Select the visibility icon to view the code. Save your recovery code and store it somewhere safe.

## [Recover your account without access](#recover-your-account-without-access)

If you lost access to both your two-factor authentication application and your recovery code:

1. Sign in to your [Docker account](https://app.docker.com/login) with your username and password.
2. Select **I've lost my authentication device** and **I've lost my recovery code**.
3. Complete the [Contact Support form](https://hub.docker.com/support/contact/?category=2fa-lockout).

You must enter the primary email address associated with your Docker ID in the Contact Support form for recovery instructions.

----
url: https://docs.docker.com/reference/cli/docker/context/use/
----

# docker context use

***

| Description | Set the default docker context |
| ----------- | ------------------------------ |
| Usage       | `docker context use CONTEXT`   |

## [Description](#description)

The `docker context use` command sets the default context for the Docker CLI.

The `docker context use` command sets the Docker CLI’s default context by updating your CLI config (`~/.docker/config.json`). This change is persistent, affecting all shells and sessions that share that config, not just the current terminal.

For one-off commands or per-shell usage, use `--context` or the `DOCKER_CONTEXT` environment variable instead.

## [Examples](#examples)

### [Set the default (sticky) context](#set-the-default-sticky-context)

This updates the CLI configuration and applies to new terminal sessions:

```bash
$ docker context use my-context
my-context

$ docker context show
my-context
```

### [Use a context for a single command](#use-a-context-for-a-single-command)

Use the global `--context` flag to avoid changing the default:

```bash
$ docker --context my-context ps
```

### [Use a context for the current shell session](#use-a-context-for-the-current-shell-session)

Set `DOCKER_CONTEXT` to override the configured default in the current shell:

```bash
$ export DOCKER_CONTEXT=my-context
$ docker context show
my-context
```

To stop overriding:

```bash
$ unset DOCKER_CONTEXT
```

### [Switch back to the default context](#switch-back-to-the-default-context)

```bash
$ docker context use default
default
```

----
url: https://docs.docker.com/scout/integrations/ci/circle-ci/
----

# Integrate Docker Scout with Circle CI

***

***

The following examples runs when triggered in CircleCI. When triggered, it checks out the "docker/scout-demo-service:latest" image and tag and then uses Docker Scout to create a CVE report.

Add the following to a *.circleci/config.yml* file.

First, set up the rest of the workflow. Add the following to the YAML file:

```yaml
version: 2.1

jobs:
  build:
    docker:
      - image: cimg/base:stable
    environment:
      IMAGE_TAG: docker/scout-demo-service:latest
```

This defines the container image the workflow uses and an environment variable for the image.

Add the following to the YAML file to define the steps for the workflow:

```yaml
steps:
  # Checkout the repository files
  - checkout
  
  # Set up a separate Docker environment to run `docker` commands in
  - setup_remote_docker:
      version: 20.10.24

  # Install Docker Scout and login to Docker Hub
  - run:
      name: Install Docker Scout
      command: |
        env
        curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- -b /home/circleci/bin
        echo $DOCKER_HUB_PAT | docker login -u $DOCKER_HUB_USER --password-stdin

  # Build the Docker image
  - run:
      name: Build Docker image
      command: docker build -t $IMAGE_TAG .
  
  # Run Docker Scout          
  - run:
      name: Scan image for CVEs
      command: |
        docker scout cves $IMAGE_TAG --exit-code --only-severity critical,high
```

This checks out the repository files and then sets up a separate Docker environment to run commands in.

It installs Docker Scout, logs into Docker Hub, builds the Docker image, and then runs Docker Scout to generate a CVE report. It only shows critical or high-severity vulnerabilities.

Finally, add a name for the workflow and the workflow's jobs:

```yaml
workflows:
  build-docker-image:
    jobs:
      - build
```

----
url: https://docs.docker.com/ai/model-runner/openwebui-integration/
----

# Open WebUI integration

***

Table of contents

***

[Open WebUI](https://github.com/open-webui/open-webui) is an open-source, self-hosted web interface that provides a ChatGPT-like experience for local AI models. You can connect it to Docker Model Runner to get a polished chat interface for your models.

## [Prerequisites](#prerequisites)

* Docker Model Runner enabled with TCP access
* A model pulled (e.g., `docker model pull ai/llama3.2`)

## [Quick start with Docker Compose](#quick-start-with-docker-compose)

The easiest way to run Open WebUI with Docker Model Runner is using Docker Compose.

Create a `compose.yaml` file:

```yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:12434
      - WEBUI_AUTH=false
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui:/app/backend/data

volumes:
  open-webui:
```

Start the services:

```console
$ docker compose up -d
```

Open your browser to <http://localhost:3000>.

## [Configuration options](#configuration-options)

### [Environment variables](#environment-variables)

| Variable              | Description                       | Default  |
| --------------------- | --------------------------------- | -------- |
| `OLLAMA_BASE_URL`     | URL of Docker Model Runner        | Required |
| `WEBUI_AUTH`          | Enable authentication             | `true`   |
| `OPENAI_API_BASE_URL` | Use OpenAI-compatible API instead | -        |
| `OPENAI_API_KEY`      | API key (use any value for DMR)   | -        |

### [Using OpenAI-compatible API](#using-openai-compatible-api)

If you prefer to use the OpenAI-compatible API instead of the Ollama API:

```yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OPENAI_API_BASE_URL=http://host.docker.internal:12434/engines/v1
      - OPENAI_API_KEY=not-needed
      - WEBUI_AUTH=false
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui:/app/backend/data

volumes:
  open-webui:
```

## [Network configuration](#network-configuration)

### [Docker Desktop](#docker-desktop)

On Docker Desktop, `host.docker.internal` automatically resolves to the host machine. The previous example works without modification.

### [Docker Engine (Linux)](#docker-engine-linux)

On Docker Engine, you may need to configure the network differently:

```yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    network_mode: host
    environment:
      - OLLAMA_BASE_URL=http://localhost:12434
      - WEBUI_AUTH=false
    volumes:
      - open-webui:/app/backend/data

volumes:
  open-webui:
```

Or use the host gateway:

```yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://172.17.0.1:12434
      - WEBUI_AUTH=false
    volumes:
      - open-webui:/app/backend/data

volumes:
  open-webui:
```

## [Using Open WebUI](#using-open-webui)

### [Select a model](#select-a-model)

1. Open <http://localhost:3000>
2. Select the model drop-down in the top-left
3. Select from your pulled models (they appear with `ai/` prefix)

### [Pull models through the UI](#pull-models-through-the-ui)

Open WebUI can pull models directly:

1. Select the model drop-down
2. Enter a model name: `ai/llama3.2`
3. Select the download icon

### [Chat features](#chat-features)

Open WebUI provides:

* Multi-turn conversations with context
* Message editing and regeneration
* Code syntax highlighting
* Markdown rendering
* Conversation history and search
* Export conversations

## [Complete example with multiple models](#complete-example-with-multiple-models)

This example sets up Open WebUI with Docker Model Runner and pre-pulls several models:

```yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:12434
      - WEBUI_AUTH=false
      - DEFAULT_MODELS=ai/llama3.2
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui:/app/backend/data
    depends_on:
      model-setup:
        condition: service_completed_successfully

  model-setup:
    image: docker:cli
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: >
      sh -c "
        docker model pull ai/llama3.2 &&
        docker model pull ai/qwen2.5-coder &&
        docker model pull ai/smollm2
      "

volumes:
  open-webui:
```

## [Enabling authentication](#enabling-authentication)

For multi-user setups or security, enable authentication:

```yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:12434
      - WEBUI_AUTH=true
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui:/app/backend/data

volumes:
  open-webui:
```

On first visit, you'll create an admin account.

## [Troubleshooting](#troubleshooting)

### [Models don't appear in the drop-down](#models-dont-appear-in-the-drop-down)

1. Verify Docker Model Runner is accessible:

   ```console
   $ curl http://localhost:12434/api/tags
   ```

2. Check that models are pulled:

   ```console
   $ docker model list
   ```

3. Verify the `OLLAMA_BASE_URL` is correct and accessible from the container.

### ["Connection refused" errors](#connection-refused-errors)

1. Ensure TCP access is enabled for Docker Model Runner.

2. On Docker Desktop, verify `host.docker.internal` resolves:

   ```console
   $ docker run --rm alpine ping -c 1 host.docker.internal
   ```

3. On Docker Engine, try using `network_mode: host` or the explicit host IP.

### [Slow response times](#slow-response-times)

1. First requests load the model into memory, which takes time.

2. Subsequent requests are much faster.

3. If consistently slow, consider:

   * Using a smaller model
   * Reducing context size
   * Checking GPU acceleration is working

### [CORS errors](#cors-errors)

If running Open WebUI on a different host:

1. In Docker Desktop, go to Settings > AI
2. Add the Open WebUI URL to **CORS Allowed Origins**

## [Customization](#customization)

### [Custom system prompts](#custom-system-prompts)

Open WebUI supports setting system prompts per model. Configure these in the UI under Settings > Models.

### [Model parameters](#model-parameters)

Adjust model parameters in the chat interface:

1. Select the settings icon next to the model name
2. Adjust temperature, top-p, max tokens, etc.

These settings are passed through to Docker Model Runner.

## [Running on a different port](#running-on-a-different-port)

To run Open WebUI on a different port:

```yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "8080:8080"  # Change first port number
    # ... rest of config
```

## [What's next](#whats-next)

* [API reference](https://docs.docker.com/ai/model-runner/api-reference/) - Learn about the APIs Open WebUI uses
* [Configuration options](https://docs.docker.com/ai/model-runner/configuration/) - Tune model behavior
* [IDE integrations](https://docs.docker.com/ai/model-runner/ide-integrations/) - Connect other tools to DMR

----
url: https://docs.docker.com/reference/cli/docker/context/export/
----

# docker context export

***

| Description | Export a context to a tar archive FILE or a tar stream on STDOUT. |
| ----------- | ----------------------------------------------------------------- |
| Usage       | `docker context export [OPTIONS] CONTEXT [FILE\|-]`               |

## [Description](#description)

Exports a context to a file that can then be used with `docker context import`.

The default output filename is `<CONTEXT>.dockercontext`. To export to `STDOUT`, use `-` as filename, for example:

```console
$ docker context export my-context -
```

----
url: https://docs.docker.com/reference/cli/docker/sandbox/create/shell/
----

# docker sandbox create shell

***

| Description | Create a sandbox for shell                                   |
| ----------- | ------------------------------------------------------------ |
| Usage       | `docker sandbox create shell WORKSPACE [EXTRA_WORKSPACE...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Create a sandbox with access to a host workspace for shell.

The workspace path is required and will be exposed inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use 'docker sandbox run SANDBOX' to start shell after creation.

----
url: https://docs.docker.com/reference/cli/docker/sandbox/save/
----

# docker sandbox save

***

| Description | Save a snapshot of the sandbox as a template |
| ----------- | -------------------------------------------- |
| Usage       | `docker sandbox save SANDBOX TAG`            |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Save a snapshot of the sandbox as a template.

By default, the image is loaded into the host's Docker daemon (requires Docker to be running). Use --output to save the image to a tar file instead.

Examples:

# [Load into host Docker (requires host Docker running)](#load-into-host-docker-requires-host-docker-running)

docker sandbox save my-sandbox myimage:v1.0

# [Save to file (works without host Docker)](#save-to-file-works-without-host-docker)

docker sandbox save my-sandbox myimage:v1.0 --output /tmp/myimage.tar

## [Options](#options)

| Option         | Default | Description                                                           |
| -------------- | ------- | --------------------------------------------------------------------- |
| `-o, --output` |         | Save image to specified tar file instead of loading into host Docker  |

----
url: https://docs.docker.com/reference/cli/docker/dhi/
----

# docker dhi

***

| Description | CLI for managing Docker Hardened Images |
| ----------- | --------------------------------------- |

## [Description](#description)

command-line interface for administering Docker Hardened Images. It provides commands to browse the DHI catalog, mirror images into your organisations and manage customizations.

## [Subcommands](#subcommands)

| Command                                                                                       | Description                                        |
| --------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [`docker dhi attestation`](https://docs.docker.com/reference/cli/docker/dhi/attestation/)     | View attestations for Docker Hardened Images       |
| [`docker dhi auth`](https://docs.docker.com/reference/cli/docker/dhi/auth/)                   | Authenticate with Docker Hub                       |
| [`docker dhi catalog`](https://docs.docker.com/reference/cli/docker/dhi/catalog/)             | Browse the Docker Hardened Images catalog          |
| [`docker dhi customization`](https://docs.docker.com/reference/cli/docker/dhi/customization/) | Manage Docker Hardened Images customizations       |
| [`docker dhi mirror`](https://docs.docker.com/reference/cli/docker/dhi/mirror/)               | Mirror Docker Hardened Images to your organization |

----
url: https://docs.docker.com/reference/cli/docker/system/
----

# docker system

***

| Description | Manage Docker   |
| ----------- | --------------- |
| Usage       | `docker system` |

## [Description](#description)

Manage Docker.

## [Subcommands](#subcommands)

| Command                                                                               | Description                          |
| ------------------------------------------------------------------------------------- | ------------------------------------ |
| [`docker system df`](https://docs.docker.com/reference/cli/docker/system/df/)         | Show docker disk usage               |
| [`docker system events`](https://docs.docker.com/reference/cli/docker/system/events/) | Get real time events from the server |
| [`docker system info`](https://docs.docker.com/reference/cli/docker/system/info/)     | Display system-wide information      |
| [`docker system prune`](https://docs.docker.com/reference/cli/docker/system/prune/)   | Remove unused data                   |

----
url: https://docs.docker.com/guides/dhi-backstage/
----

[Secure a Backstage application with Docker Hardened Images](https://docs.docker.com/guides/dhi-backstage/)

Learn how to secure a Backstage developer portal using Docker Hardened Images (DHI), handle native module compilation with better-sqlite3, add Socket Firewall protection during dependency installation, and produce a distroless runtime image using DHI customizations.

Docker Hardened Images

45 minutes

[« Back to all guides](/guides/)

# Secure a Backstage application with Docker Hardened Images

***

Table of contents

***

This guide shows how to secure a Backstage application using Docker Hardened Images (DHI). Backstage is a CNCF open source developer portal used by thousands of organizations to manage their software catalogs, templates, and developer tooling.

By the end of this guide, you'll have a Backstage container image that is distroless, runs as a non-root user by default, and has dramatically fewer CVEs than the standard `node:24-trixie-slim` base image while still supporting the native module compilation that Backstage requires.

## [Prerequisites](#prerequisites)

* Docker Desktop or Docker Engine with BuildKit enabled
* A Docker Hub account authenticated with `docker login` and `docker login dhi.io`
* A Backstage project created with `@backstage/create-app`

## [Why Backstage needs customization](#why-backstage-needs-customization)

The DHI migration examples cover applications where you can swap the base image and everything works. Backstage is different. It uses `better-sqlite3` and other packages that compile native Node.js modules at install time, which means the build stage needs `g++`, `make`, `python3`, and `sqlite-dev` — none of which are in the base `dhi.io/node` image. The runtime image only needs the shared library (`sqlite-libs`) that the compiled native module links against.

This is a common pattern. Any Node.js application that depends on native addons (such as `bcrypt`, `sharp`, `sqlite3`, or `node-canvas`) faces the same challenge. The approach in this guide applies to all of them.

## [Step 1: Examine the original Dockerfile](#step-1-examine-the-original-dockerfile)

The official Backstage documentation recommends a multi-stage Dockerfile using `node:24-trixie-slim` (Debian). A typical setup looks like this:

```dockerfile
# Stage 1 - Create yarn install skeleton layer
FROM node:24-trixie-slim AS packages
WORKDIR /app
COPY backstage.json package.json yarn.lock ./
COPY .yarn ./.yarn
COPY .yarnrc.yml ./
COPY packages packages
COPY plugins plugins
RUN find packages \! -name "package.json" -mindepth 2 -maxdepth 2 \
    -exec rm -rf {} \+

# Stage 2 - Install dependencies and build packages
FROM node:24-trixie-slim AS build
ENV PYTHON=/usr/bin/python3
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
    apt-get install -y --no-install-recommends python3 g++ build-essential && \
    rm -rf /var/lib/apt/lists/*
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
    apt-get install -y --no-install-recommends libsqlite3-dev && \
    rm -rf /var/lib/apt/lists/*
USER node
WORKDIR /app
COPY --from=packages --chown=node:node /app .
RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    yarn install --immutable
COPY --chown=node:node . .
RUN yarn tsc
RUN yarn --cwd packages/backend build
RUN mkdir packages/backend/dist/skeleton packages/backend/dist/bundle \
    && tar xzf packages/backend/dist/skeleton.tar.gz \
       -C packages/backend/dist/skeleton \
    && tar xzf packages/backend/dist/bundle.tar.gz \
       -C packages/backend/dist/bundle

# Stage 3 - Build the actual backend image
FROM node:24-trixie-slim
ENV PYTHON=/usr/bin/python3
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
    apt-get install -y --no-install-recommends python3 g++ build-essential && \
    rm -rf /var/lib/apt/lists/*
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && \
    apt-get install -y --no-install-recommends libsqlite3-dev && \
    rm -rf /var/lib/apt/lists/*
USER node
WORKDIR /app
COPY --from=build --chown=node:node /app/.yarn ./.yarn
COPY --from=build --chown=node:node /app/.yarnrc.yml ./
COPY --from=build --chown=node:node /app/backstage.json ./
COPY --from=build --chown=node:node /app/yarn.lock \
     /app/package.json \
     /app/packages/backend/dist/skeleton/ ./
RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    yarn workspaces focus --all --production
COPY --from=build --chown=node:node /app/packages/backend/dist/bundle/ ./
CMD ["node", "packages/backend", "--config", "app-config.yaml"]
```

Run this image and inspect what's available inside the container:

```console
docker build -t backstage:init .
docker run -d \
    -e APP_CONFIG_backend_database_client='better-sqlite3' \
    -e APP_CONFIG_backend_database_connection=':memory:' \
    -e APP_CONFIG_auth_providers_guest_dangerouslyAllowOutsideDevelopment='true' \
    -p 7007:7007 \
    -u 1000 \
    --cap-drop=ALL \
    --read-only \
    --tmpfs /tmp \
    backstage:init
```

This works, but the runtime container has a shell, a package manager, and yarn. None of these are needed to run Backstage. Run `docker exec` to see what's accessible inside:

```console
docker exec -it <container-id> sh
$ cat /etc/shells
# /etc/shells: valid login shells
/bin/sh
/usr/bin/sh
/bin/bash
/usr/bin/bash
/bin/rbash
/usr/bin/rbash
/usr/bin/dash
$ yarn --version
4.12.0
$ dpkg --version
dpkg version 1.22.11 (arm64).
$ whoami
node
$ id
uid=1000(node) gid=1000(node) groups=1000(node)
```

The `node:24-trixie-slim` image ships with three shells (`dash`, `bash`, and `rbash`), a package manager (`dpkg`), and `yarn`. Each of these tools increases the attack surface. An attacker who gains access to this container could use them for lateral movement across your infrastructure.

## [Step 2: Switch the build stages to DHI](#step-2-switch-the-build-stages-to-dhi)

Replace all three stages with DHI equivalents. DHI Node.js images are available in both Alpine and Debian variants. This guide uses the Alpine variant (`dhi.io/node:24-alpine3.23`) because it produces a smaller image. If you need to stay on Debian for compatibility reasons, use `dhi.io/node:24-bookworm` and keep `apt-get` instead of `apk`.

```dockerfile
# Stage 1: prepare packages
FROM --platform=$BUILDPLATFORM dhi.io/node:24-alpine3.23-dev AS packages
WORKDIR /app
COPY backstage.json package.json yarn.lock ./
COPY .yarn ./.yarn
COPY .yarnrc.yml ./
COPY packages packages
COPY plugins plugins
RUN find packages \! -name "package.json" -mindepth 2 -maxdepth 2 \
    -exec rm -rf {} \+

# Stage 2: build the application
FROM --platform=$BUILDPLATFORM dhi.io/node:24-alpine3.23-dev AS build
ENV PYTHON=/usr/bin/python3
RUN apk add --no-cache g++ make python3 sqlite-dev && \
    rm -rf /var/lib/apk/lists/*
WORKDIR /app
COPY --from=packages --chown=node:node /app .
RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    yarn install --immutable
COPY --chown=node:node . .
RUN yarn tsc
RUN yarn --cwd packages/backend build
RUN mkdir packages/backend/dist/skeleton packages/backend/dist/bundle \
    && tar xzf packages/backend/dist/skeleton.tar.gz \
       -C packages/backend/dist/skeleton \
    && tar xzf packages/backend/dist/bundle.tar.gz \
       -C packages/backend/dist/bundle

# Final Stage: create the runtime image
FROM dhi.io/node:24-alpine3.23-dev
ENV PYTHON=/usr/bin/python3
RUN apk add --no-cache g++ make python3 sqlite-dev && \
    rm -rf /var/lib/apk/lists/*
WORKDIR /app
COPY --from=build --chown=node:node /app/.yarn ./.yarn
COPY --from=build --chown=node:node /app/.yarnrc.yml ./
COPY --from=build --chown=node:node /app/backstage.json ./
COPY --from=build --chown=node:node /app/yarn.lock \
     /app/package.json \
     /app/packages/backend/dist/skeleton/ ./
RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    yarn workspaces focus --all --production \
    && rm -rf "$(yarn cache clean)"
COPY --from=build --chown=node:node /app/packages/backend/dist/bundle/ ./
CMD ["node", "packages/backend", "--config", "app-config.yaml"]
```

Build and tag this version:

```console
docker build -t backstage:dhi-dev .
```

> Note
>
> The `-dev` variant includes a shell and package manager, which is why `apk add` works. Backstage requires `python3` and native build tools in the runtime image because `yarn workspaces focus --all --production` recompiles native modules during the production install. This is specific to Backstage's build process — most Node.js applications can use the standard (non-dev) DHI runtime variant without additional packages.

The DHI images come with attestations that the original `node:24-trixie-slim` images don't have. Check what's attached:

```console
docker scout attest list dhi.io/node:24-alpine3.23
```

DHI images ship with 15 attestations including CycloneDX SBOM, SLSA provenance, OpenVEX, Scout health reports, secret scans, virus/malware reports, and an SLSA verification summary.

## [Step 3: Add Socket Firewall protection](#step-3-add-socket-firewall-protection)

DHI provides `-sfw` (Socket Firewall) variants for Node.js images. Socket Firewall intercepts `npm` and `yarn` commands during the build to detect and block malicious packages before they execute install scripts.

To enable Socket Firewall, change the `-dev` tags to `-sfw-dev` in all three stages. The SFW version of the Dockerfile:

```dockerfile
# Stage 1: prepare packages
FROM --platform=$BUILDPLATFORM dhi.io/node:24-alpine3.23-sfw-dev AS packages
WORKDIR /app
COPY backstage.json package.json yarn.lock ./
COPY .yarn ./.yarn
COPY .yarnrc.yml ./
COPY packages packages
COPY plugins plugins
RUN find packages \! -name "package.json" -mindepth 2 -maxdepth 2 \
    -exec rm -rf {} \+

# Stage 2: build the packages
FROM --platform=$BUILDPLATFORM dhi.io/node:24-alpine3.23-sfw-dev AS build-packages
ENV PYTHON=/usr/bin/python3
RUN apk add --no-cache g++ make python3 sqlite-dev && \
    rm -rf /var/lib/apk/lists/*
WORKDIR /app
COPY --from=packages --chown=node:node /app .
RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    yarn install --immutable
COPY --chown=node:node . .
RUN yarn tsc
RUN yarn --cwd packages/backend build
RUN mkdir packages/backend/dist/skeleton packages/backend/dist/bundle \
    && tar xzf packages/backend/dist/skeleton.tar.gz \
       -C packages/backend/dist/skeleton \
    && tar xzf packages/backend/dist/bundle.tar.gz \
       -C packages/backend/dist/bundle

# Final Stage: create the runtime image
FROM dhi.io/node:24-alpine3.23-sfw-dev
ENV PYTHON=/usr/bin/python3
RUN apk add --no-cache g++ make python3 sqlite-dev && \
    rm -rf /var/lib/apk/lists/*
WORKDIR /app
COPY --from=build-packages --chown=node:node /app/.yarn ./.yarn
COPY --from=build-packages --chown=node:node /app/.yarnrc.yml ./
COPY --from=build-packages --chown=node:node /app/backstage.json ./
COPY --from=build-packages --chown=node:node /app/yarn.lock \
     /app/package.json \
     /app/packages/backend/dist/skeleton/ ./
RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    yarn workspaces focus --all --production \
    && rm -rf "$(yarn cache clean)"
COPY --from=build-packages --chown=node:node /app/packages/backend/dist/bundle/ ./
CMD ["node", "packages/backend", "--config", "app-config.yaml"]
```

Build this version:

```console
docker build -t backstage:dhi-sfw-dev .
```

When you build, you'll see Socket Firewall messages in the build output: `Protected by Socket Firewall` for any `yarn` and `npm` commands executed in the Dockerfile or in the running containers.

> Tip
>
> The `-sfw-dev` variant is larger (1.9 GB versus 1.72 GB) because Socket Firewall adds monitoring tooling. The security benefit during `yarn install` outweighs the size increase.

## [Step 4: Remove the shell and the package manager with DHI customizations](#step-4-remove-the-shell-and-the-package-manager-with-dhi-customizations)

The previous steps still use the `-dev` or `-sfw-dev` variant as the runtime image, which includes a shell and package manager. DHI customizations let you start from the base (non-dev) image — which has no shell and no package manager — and add only the runtime libraries and language runtimes your application needs.

> Important
>
> When creating a customization, only add what your application needs at runtime:
>
> * **System packages** - add shared libraries (such as `sqlite-libs`) and language runtimes from the DHI catalog (such as `python-3.14`). Do not add build tools (such as `g++`, `make`, or `python3` from Alpine).
> * **Build tools** - keep these in the `-dev` build stage only. Never add them to the runtime customization.
>
> Language runtimes installed from the DHI hardened package feed are patched and tracked in the image SBOM, which is why they are acceptable as system packages. Build tools from Alpine or Debian package feeds are not hardened and should never appear in the runtime image.

For Backstage, the runtime image needs:

* **sqlite-libs** - the shared library that the compiled `better-sqlite3` native module links against (added as a system package).
* **Python** - if your Backstage plugins or configuration require Python at runtime. Added as the `python-3.14` system package from the DHI catalog. Unlike `python3` installed via `apk`, this package is patched by Docker and tracked in the image SBOM.

Docker will continuously build with SLSA Level 3 compliance and patch these customized images within the guaranteed SLA for CVE patching.

To create the customization, use one of the following methods.

After you mirror the Node.js DHI repository to your organization's namespace:

1. Open the mirrored Node.js repository in Docker Hub.
2. Select **Customize** and choose the `node:24-alpine3.23` tag.
3. Under **Packages**, add `sqlite-libs` and `python-3.14`.
4. Create the customization.

For more information, see [Customize an image](/dhi/how-to/customize/).

`dhictl` is Docker's command-line tool for managing Docker Hardened Images. It lets you browse the DHI catalog, mirror images, and create customizations directly from your terminal. You can integrate `dhictl` into CI/CD pipelines and infrastructure-as-code workflows. You can install `dhictl` as a standalone binary or as a Docker CLI plugin (`docker dhi`); for installation instructions, see [Use the DHI CLI](/dhi/how-to/cli/).

Rather than writing the customization YAML by hand, use `dhictl` to scaffold a starting point:

```console
dhictl customization prepare --org YOUR_ORG node 24-alpine3.23 \
    --destination YOUR_ORG/dhi-node \
    --name "backstage" \
    --tag-suffix "_backstage" \
    --output node-backstage.yaml
```

Edit the generated file to add the runtime libraries:

```yaml
name: backstage

source: dhi/node
tag_definition_id: node/alpine-3.23/24

destination: YOUR_ORG/dhi-node
tag_suffix: _backstage

platforms:
  - linux/amd64
  - linux/arm64

contents:
  packages:
    - sqlite-libs
    - python-3.14

accounts:
  root: true
  runs-as: node
  users:
    - name: node
      uid: 1000
  groups:
    - name: node
      gid: 1000
```

Then create the customization:

```console
dhictl customization create --org YOUR_ORG node-backstage.yaml
```

Monitor the build progress:

```console
dhictl customization build list --org YOUR_ORG YOUR_ORG/dhi-node "backstage"
```

Docker builds the customized image on its secure infrastructure and publishes it as `YOUR_ORG/dhi-node:24-alpine3.23_backstage`.

> Note
>
> If your Backstage configuration does not require Python at runtime, you can omit the `python-3.14` from the packages list. The `sqlite-libs` package alone is sufficient to run Backstage with `better-sqlite3`.

### [Update the Dockerfile](#update-the-dockerfile)

Update only the final stage of your Dockerfile to use the customized image:

```dockerfile
# Final Stage: create the runtime image
FROM YOUR_ORG/dhi-node:24-alpine3.23_backstage
WORKDIR /app
COPY --from=build --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/packages/backend/dist/bundle/ ./
CMD ["node", "packages/backend", "--config", "app-config.yaml"]
```

Build this version:

```console
docker build -t backstage:dhi .
```

Since the customization includes only runtime libraries and OCI artifacts — no build tools, no package manager, no shell — the resulting image is distroless:

```console
docker run --rm YOUR_ORG/dhi-node:24-alpine3.23_backstage sh -c "echo hello"
docker: Error response from daemon: ... exec: "sh": executable file not found in $PATH
```

With the Enterprise customization:

* The runtime image is distroless — no shell, no package manager.
* Docker automatically rebuilds your customized image when the base Node.js image or any of its packages receive a security patch.
* The full chain of trust is maintained, including SLSA Build Level 3 provenance.
* Both the Node.js and Python runtimes are tracked in the image SBOM.

Confirm the container no longer has shell access:

```console
docker exec -it <container-id> sh
OCI runtime exec failed: exec failed: unable to start container process: ...
```

Use [Docker Debug](/dhi/troubleshoot/#general-debugging) if you need to troubleshoot a running distroless container.

> Note
>
> If your organization requires FIPS/STIG compliant images, that's also an option in DHI Enterprise.

## [Step 5: Verify the results](#step-5-verify-the-results)

Compare the DHI-based image against the original using Docker Scout:

```console
docker scout compare backstage:dhi \
    --to backstage:init \
    --platform linux/amd64 \
    --ignore-unchanged
```

A typical comparison across the approaches shows results similar to the following:

| Metric           | Original | DHI -dev  | DHI -sfw-dev | Enterprise                 |
| ---------------- | -------- | --------- | ------------ | -------------------------- |
| Disk usage       | 1.61 GB  | 1.72 GB   | 1.9 GB       | 1.49 GB                    |
| Content size     | 268 MB   | 288 MB    | 328 MB       | 247 MB                     |
| Shell in runtime | Yes      | Yes       | Yes          | No                         |
| Package manager  | Yes      | Yes       | Yes          | No                         |
| Non-root default | No       | No        | No           | Yes                        |
| Socket Firewall  | No       | No        | Yes (build)  | Yes (build) / No (runtime) |
| SLSA provenance  | No       | Base only | Base only    | Full (Level 3)             |

> Note
>
> The `-sfw-dev` variant is larger because Socket Firewall adds monitoring tooling to the image. The additional size is in the build stages, and the security benefit during `yarn install` outweighs the size increase.

For a more thorough assessment, scan with multiple tools:

```console
trivy image backstage:dhi
grype backstage:dhi
docker scout quickview backstage:dhi
```

Different scanners detect different issues. Running all three gives you the most complete view of your security posture.

## [What's next](#whats-next)

* [Customize an image](/dhi/how-to/customize/) — complete reference on the Enterprise customization UI.
* [Create and build a DHI](/dhi/how-to/build/) — learn how to write a DHI definition file, build images locally.
* [Use the DHI CLI](/dhi/how-to/cli/) — manage DHI images, mirrors, and customizations from the command line.
* [Migrate to DHI](/dhi/migration/) — for applications that work with standard DHI images without additional packages.
* [Compare images](/dhi/how-to/explore/#compare-and-evaluate-images) — evaluate security improvements between your original and hardened images.
* [Docker Debug](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers that have no shell.

----
url: https://docs.docker.com/reference/cli/docker/container/rename/
----

# docker container rename

***

| Description                                                               | Rename a container                           |
| ------------------------------------------------------------------------- | -------------------------------------------- |
| Usage                                                                     | `docker container rename CONTAINER NEW_NAME` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker rename`                              |

## [Description](#description)

The `docker rename` command renames a container.

## [Examples](#examples)

```console
$ docker rename my_container my_new_container
```

----
url: https://docs.docker.com/guides/dotnet/develop/
----

# Use containers for .NET development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a .NET application](https://docs.docker.com/guides/dotnet/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment for your containerized application. This includes:

* Adding a local database and persisting data
* Configuring Compose to automatically update your running Compose services as you edit and save your code
* Creating a development container that contains the .NET Core SDK tools and dependencies

## [Update the application](#update-the-application)

This section uses a different branch of the `docker-dotnet-sample` repository that contains an updated .NET application. The updated application is on the `add-db` branch of the repository you cloned in [Containerize a .NET application](https://docs.docker.com/guides/dotnet/containerize/).

To get the updated code, you need to checkout the `add-db` branch. For the changes you made in [Containerize a .NET application](https://docs.docker.com/guides/dotnet/containerize/), for this section, you can stash them. In a terminal, run the following commands in the `docker-dotnet-sample` directory.

1. Stash any previous changes.

   ```console
   $ git stash -u
   ```

2. Check out the new branch with the updated application.

   ```console
   $ git checkout add-db
   ```

In the `add-db` branch, only the .NET application has been updated. None of the Docker assets have been updated yet.

You should now have the following in your `docker-dotnet-sample` directory.

```text
├── docker-dotnet-sample/
│ ├── .git/
│ ├── src/
│ │ ├── Data/
│ │ ├── Models/
│ │ ├── Pages/
│ │ ├── Properties/
│ │ ├── wwwroot/
│ │ ├── appsettings.Development.json
│ │ ├── appsettings.json
│ │ ├── myWebApp.csproj
│ │ └── Program.cs
│ ├── tests/
│ │ ├── tests.csproj
│ │ ├── UnitTest1.cs
│ │ └── Usings.cs
│ ├── .dockerignore
│ ├── .gitignore
│ ├── compose.yaml
│ ├── Dockerfile
│ └── README.md
```

## [Add a local database and persist data](#add-a-local-database-and-persist-data)

You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data.

Open the `compose.yaml` file in an IDE or text editor. You'll notice it already contains commented-out instructions for a PostgreSQL database and volume.

Open `docker-dotnet-sample/src/appsettings.json` in an IDE or text editor. You'll notice the connection string with all the database information. The `compose.yaml` already contains this information, but it's commented out. Uncomment the database instructions in the `compose.yaml` file.

The following is the updated `compose.yaml` file.

```yaml
services:
  server:
    build:
      context: .
      target: final
    ports:
      - 8080:8080
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:18
    restart: always
    user: postgres
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    expose:
      - 5432
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
```

> Note
>
> To learn more about the instructions in the Compose file, see [Compose file reference](/reference/compose-file/).

Before you run the application using Compose, notice that this Compose file uses `secrets` and specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository.

In the `docker-dotnet-sample` directory, create a new directory named `db` and inside that directory create a file named `password.txt`. Open `password.txt` in an IDE or text editor and add the following password. The password must be on a single line, with no additional lines in the file.

```text
example
```

Save and close the `password.txt` file.

You should now have the following in your `docker-dotnet-sample` directory.

```text
├── docker-dotnet-sample/
│ ├── .git/
│ ├── db/
│ │ └── password.txt
│ ├── src/
│ ├── tests/
│ ├── .dockerignore
│ ├── .gitignore
│ ├── compose.yaml
│ ├── Dockerfile
│ └── README.md
```

Run the following command to start your application.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:8080>. You should see a simple web application with the text `Student name is`.

The application doesn't display a name because the database is empty. For this application, you need to access the database and then add records.

## [Add records to the database](#add-records-to-the-database)

For the sample application, you must access the database directly to create sample records.

You can run commands inside the database container using the `docker exec` command. Before running that command, you must get the ID of the database container. Open a new terminal window and run the following command to list all your running containers.

```console
$ docker container ls
```

You should see output like the following.

```console
CONTAINER ID   IMAGE                         COMMAND                  CREATED              STATUS                        PORTS                    NAMES
cb36e310aa7e   docker-dotnet-sample-server   "dotnet myWebApp.dll"    About a minute ago   Up About a minute             0.0.0.0:8080->8080/tcp   docker-dotnet-sample-server-1
39fdcf0aff7b   postgres:18                   "docker-entrypoint.s…"   About a minute ago   Up About a minute (healthy)   5432/tcp                 docker-dotnet-sample-db-1
```

In the previous example, the container ID is `39fdcf0aff7b`. Run the following command to connect to the postgres database in the container. Replace the container ID with your own container ID.

```console
$ docker exec -it 39fdcf0aff7b psql -d example -U postgres
```

And finally, insert a record into the database.

```console
example=# INSERT INTO "Students" ("ID", "LastName", "FirstMidName", "EnrollmentDate") VALUES (DEFAULT, 'Whale', 'Moby', '2013-03-20');
```

You should see output like the following.

```console
INSERT 0 1
```

Close the database connection and exit the container shell by running `exit`.

```console
example=# exit
```

## [Verify that data persists in the database](#verify-that-data-persists-in-the-database)

Open a browser and view the application at <http://localhost:8080>. You should see a simple web application with the text `Student name is Moby Whale`.

Press `ctrl+c` in the terminal to stop your application.

In the terminal, run `docker compose rm` to remove your containers and then run `docker compose up` to run your application again.

```console
$ docker compose rm
$ docker compose up --build
```

Refresh <http://localhost:8080> in your browser and verify that the student name persisted, even after the containers were removed and ran again.

Press `ctrl+c` in the terminal to stop your application.

## [Automatically update services](#automatically-update-services)

Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

Open your `compose.yaml` file in an IDE or text editor and then add the Compose Watch instructions. The following is the updated `compose.yaml` file.

```yaml
services:
  server:
    build:
      context: .
      target: final
    ports:
      - 8080:8080
    depends_on:
      db:
        condition: service_healthy
    develop:
      watch:
        - action: rebuild
          path: .
  db:
    image: postgres:18
    restart: always
    user: postgres
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    expose:
      - 5432
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
```

Run the following command to run your application with Compose Watch.

```console
$ docker compose watch
```

Open a browser and verify that the application is running at <http://localhost:8080>.

Any changes to the application's source files on your local machine will now be immediately reflected in the running container.

Open `docker-dotnet-sample/src/Pages/Index.cshtml` in an IDE or text editor and update the student name text on line 13 from `Student name is` to `Student name:`.

```diff
-    <p>Student name is @Model.StudentName</p>
+    <p>Student name: @Model.StudentName</p>
```

Save the changes to `Index.cshtml` and then wait a few seconds for the application to rebuild. Refresh <http://localhost:8080> in your browser and verify that the updated text appears.

Press `ctrl+c` in the terminal to stop your application.

## [Create a development container](#create-a-development-container)

At this point, when you run your containerized application, it's using the .NET runtime image. While this small image is good for production, it lacks the SDK tools and dependencies you may need when developing. Also, during development, you may not need to run `dotnet publish`. You can use multi-stage builds to build stages for both development and production in the same Dockerfile. For more details, see [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/).

Add a new development stage to your Dockerfile and update your `compose.yaml` file to use this stage for local development.

The following is the updated Dockerfile.

```Dockerfile
# syntax=docker/dockerfile:1

FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build
ARG TARGETARCH
COPY . /source
WORKDIR /source/src
RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \
    dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app

FROM dhi.io/dotnet:10-sdk AS development
COPY . /source
WORKDIR /source/src
CMD dotnet run --no-launch-profile

FROM dhi.io/aspnetcore:10 AS final
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "myWebApp.dll"]
```

```Dockerfile
# syntax=docker/dockerfile:1

FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build
ARG TARGETARCH
COPY . /source
WORKDIR /source/src
RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \
    dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app

FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS development
COPY . /source
WORKDIR /source/src
CMD dotnet run --no-launch-profile

FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
WORKDIR /app
COPY --from=build /app .
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser
USER appuser
ENTRYPOINT ["dotnet", "myWebApp.dll"]
```

The following is the updated `compose.yaml` file.

```yaml
services:
  server:
    build:
      context: .
      target: development
    ports:
      - 8080:8080
    depends_on:
      db:
        condition: service_healthy
    develop:
      watch:
        - action: rebuild
          path: .
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
  db:
    image: postgres:18
    restart: always
    user: postgres
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    expose:
      - 5432
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
```

Your containerized application will now use the SDK image (either `dhi.io/dotnet:10-sdk` for DHI or `mcr.microsoft.com/dotnet/sdk:10.0-alpine` for official images), which includes development tools like `dotnet test`. Continue to the next section to learn how you can run `dotnet test`.

## [Summary](#summary)

In this section, you took a look at setting up your Compose file to add a local database and persist data. You also learned how to use Compose Watch to automatically rebuild and run your container when you update your code. And finally, you learned how to create a development container that contains the SDK tools and dependencies needed for development.

Related information:

* [Compose file reference](/reference/compose-file/)
* [Compose file watch](https://docs.docker.com/compose/how-tos/file-watch/)
* [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/)

## [Next steps](#next-steps)

In the next section, you'll learn how to run unit tests using Docker.

[Run .NET tests in a container »](https://docs.docker.com/guides/dotnet/run-tests/)

----
url: https://docs.docker.com/ai/gordon/usage-limits/
----

# Gordon usage limits and tiers

***

Table of contents

***

Requires: Docker Desktop [4.74.0](https://docs.docker.com/desktop/release-notes/#4740) or later

Gordon is included with every Docker account at the Base tier. Paid Gordon plans unlock higher usage limits.

## [Tiers](#tiers)

| Tier | Usage allocation                 |
| ---- | -------------------------------- |
| Base | Included with any Docker account |
| Plus | 2× Base                          |
| Max  | 5× Base                          |

For more information about Gordon tiers and how to upgrade, go to [docker.com](https://www.docker.com/products/gordon).

## [Usage limits](#usage-limits)

Gordon usage is measured in questions. The number you can ask depends on complexity: questions that involve more context, files, or Docker operations count more toward your limit.

| Tier | Per 4 hours | Per day | Per month |
| ---- | ----------- | ------- | --------- |
| Base | \~40        | \~100   | \~180     |
| Plus | \~80        | \~200   | \~360     |
| Max  | \~200       | \~500   | \~900     |

These are estimates and vary based on question complexity.

Usage limits reset at fixed UTC times, not on a sliding window. The 4-hour window resets every 4 hours starting at 00:00 UTC, the daily window resets at 00:00 UTC, and the monthly window resets on the first day of each calendar month at 00:00 UTC.

## [View your usage](#view-your-usage)

Docker Desktop shows a usage indicator so you can see how close you are to your limit. To get more usage, upgrade your tier.

----
url: https://docs.docker.com/compose/how-tos/use-secrets/
----

# Manage secrets securely in Docker Compose

***

Table of contents

***

A secret is any piece of data, such as a password, certificate, or API key, that shouldn’t be transmitted over a network or stored unencrypted in a Dockerfile or in your application’s source code.

Docker Compose provides a way for you to use secrets without having to use environment variables to store information. If you’re injecting passwords and API keys as environment variables, you risk unintentional information exposure. Services can only access secrets when explicitly granted by a `secrets` attribute within the `services` top-level element.

Environment variables are often available to all processes, and it can be difficult to track access. They can also be printed in logs when debugging errors without your knowledge. Using secrets mitigates these risks.

## [Use secrets](#use-secrets)

Secrets are mounted as a file in `/run/secrets/<secret_name>` inside the container.

Getting a secret into a container is a two-step process. First, define the secret using the [top-level secrets element in your Compose file](https://docs.docker.com/reference/compose-file/secrets/). Next, update your service definitions to reference the secrets they require with the [secrets attribute](https://docs.docker.com/reference/compose-file/services/#secrets). Compose grants access to secrets on a per-service basis.

Unlike the other methods, this permits granular access control within a service container via standard filesystem permissions.

## [Examples](#examples)

### [Single-service secret injection](#single-service-secret-injection)

In the following example, the frontend service is given access to the `my_secret` secret. In the container, `/run/secrets/my_secret` is set to the contents of the file `./my_secret.txt`.

```yaml
services:
  myapp:
    image: myapp:latest
    secrets:
      - my_secret
secrets:
  my_secret:
    file: ./my_secret.txt
```

### [Multi-service secret sharing and password management](#multi-service-secret-sharing-and-password-management)

```yaml
services:
   db:
     image: mysql:latest
     volumes:
       - db_data:/var/lib/mysql
     environment:
       MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
       MYSQL_DATABASE: wordpress
       MYSQL_USER: wordpress
       MYSQL_PASSWORD_FILE: /run/secrets/db_password
     secrets:
       - db_root_password
       - db_password

   wordpress:
     depends_on:
       - db
     image: wordpress:latest
     ports:
       - "8000:80"
     environment:
       WORDPRESS_DB_HOST: db:3306
       WORDPRESS_DB_USER: wordpress
       WORDPRESS_DB_PASSWORD_FILE: /run/secrets/db_password
     secrets:
       - db_password


secrets:
   db_password:
     file: db_password.txt
   db_root_password:
     file: db_root_password.txt

volumes:
    db_data:
```

In the advanced example above:

* The `secrets` attribute under each service defines the secrets you want to inject into the specific container.
* The top-level `secrets` section defines the variables `db_password` and `db_root_password` and provides the `file` that populates their values.
* The deployment of each container means Docker creates a bind mount under `/run/secrets/<secret_name>` with their specific values.

> Note
>
> The `_FILE` environment variables demonstrated here are a convention used by some images, including Docker Official Images like [mysql](https://hub.docker.com/_/mysql) and [postgres](https://hub.docker.com/_/postgres).

### [Build secrets](#build-secrets)

In the following example, the `npm_token` secret is made available at build time. Its value is taken from the `NPM_TOKEN` environment variable.

```yaml
services:
  myapp:
    build:
      secrets:
        - npm_token
      context: .

secrets:
  npm_token:
    environment: NPM_TOKEN
```

## [Resources](#resources)

* [Familiarize yourself with Compose's trust model](https://docs.docker.com/compose/trust-model/)
* [Secrets top-level element](https://docs.docker.com/reference/compose-file/secrets/)
* [Secrets attribute for services top-level element](https://docs.docker.com/reference/compose-file/services/#secrets)
* [Build secrets](https://docs.docker.com/build/building/secrets/)

----
url: https://docs.docker.com/guides/django/
----

[Containerize a Django application](https://docs.docker.com/guides/django/)

This guide shows how to containerize a Django application using Docker. You'll scaffold the project with uv, create a production-ready Dockerfile using a Docker Hardened Image, then add a development stage and Compose Watch for fast iteration.

Python Docker Hardened Images

25 minutes

[« Back to all guides](/guides/)

# Containerize a Django application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have [uv](https://docs.astral.sh/uv/) installed, or you can use Docker to scaffold the project without a local Python or uv installation.

> Tip
>
> If you're new to Docker, start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide to get familiar with key concepts like images, containers, and Dockerfiles.

***

## [Overview](#overview)

This guide walks you through containerizing a Django application with Docker. By the end, you will:

* Initialize a Django project using uv, either locally or inside a Docker Hardened Image container.
* Create a production-ready Dockerfile using [Docker Hardened Images (DHI)](/dhi/).
* Add a `development` stage to your Dockerfile and configure Compose Watch for automatic code syncing.

***

## [Create the Django project](#create-the-django-project)

You can bootstrap the project with a local uv installation, or entirely inside a container using the same DHI image the Dockerfile uses, with no local Python required.

1. Initialize the project pinned to Python 3.14, then navigate into it:

   ```console
   $ uv init --python 3.14 django-docker
   $ cd django-docker
   ```

2. Add Django and Gunicorn, then scaffold the Django project:

   ```console
   $ uv add django gunicorn
   $ uv run django-admin startproject myapp .
   ```

The DHI dev image already has Python 3.14, so the bootstrapped project will match the Dockerfile exactly.

1. Create the project directory and navigate into it:

   ```console
   $ mkdir django-docker && cd django-docker
   ```

2. Initialize the project, add dependencies, and scaffold. All in one container run:

   ```console
   $ docker run --rm -v $PWD:$PWD -w $PWD \
     -e UV_LINK_MODE=copy \
     dhi.io/python:3.14-alpine3.23-dev \
     sh -c "pip install --quiet --root-user-action=ignore uv && uv init --name django-docker --python 3.14 . && uv add django gunicorn && uv run django-admin startproject myapp ."
   ```

   > Note
   >
   > The previous command uses Mac/Linux shell syntax. On Windows, adjust the path: PowerShell uses `${PWD}`, Command Prompt uses `%cd%`, Git Bash requires `MSYS_NO_PATHCONV=1` with `$(pwd -W)`.

Your directory should now contain the following files:

```text
├── .python-version
├── main.py
├── manage.py
├── myapp/
│ ├── __init__.py
│ ├── asgi.py
│ ├── settings.py
│ ├── urls.py
│ └── wsgi.py
├── pyproject.toml
├── uv.lock
└── README.md
```

***

## [Create a production Dockerfile](#create-a-production-dockerfile)

Docker Hardened Images are production-ready base images maintained by Docker that minimize attack surface. For more details, see [Docker Hardened Images](/dhi/).

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Create a `.dockerignore` file to exclude local artifacts from the build context:

   .dockerignore

   ```text
   .venv/
   __pycache__/
   *.pyc
   .git/
   ```

3. Create a `Dockerfile` with the following contents:

   Dockerfile

   ```dockerfile
   # syntax=docker/dockerfile:1

   # Build stage: the -dev image includes tools needed to install packages.
   FROM dhi.io/python:3.14-alpine3.23-dev AS builder

   # Prevent Python from writing .pyc files to disk.
   ENV PYTHONDONTWRITEBYTECODE=1
   # Prevent Python from buffering stdout/stderr so logs appear immediately.
   ENV PYTHONUNBUFFERED=1

   RUN pip install --quiet --root-user-action=ignore uv
   # Use copy mode since the cache and build filesystem are on different volumes.
   ENV UV_LINK_MODE=copy

   WORKDIR /app

   # Install dependencies into a virtual environment using cache and bind mounts
   # so neither uv nor the lock files need to be copied into the image.
   RUN --mount=type=cache,target=/root/.cache/uv \
       --mount=type=bind,source=uv.lock,target=uv.lock \
       --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
       uv sync --frozen --no-install-project

   # Runtime stage: minimal DHI image with no shell or package manager,
   # already runs as the nonroot user.
   FROM dhi.io/python:3.14-alpine3.23

   # Prevent Python from buffering stdout/stderr so logs appear immediately.
   ENV PYTHONUNBUFFERED=1
   # Activate the virtual environment copied from the build stage.
   ENV PATH="/app/.venv/bin:$PATH"

   WORKDIR /app

   # Copy the pre-built virtual environment and application source code.
   COPY --from=builder /app/.venv /app/.venv
   COPY . .

   EXPOSE 8000

   # Run Gunicorn as the production WSGI server.
   CMD ["gunicorn", "myapp.wsgi:application", "--bind", "0.0.0.0:8000"]
   ```

4. Create a `compose.yaml` file:

   compose.yaml

   ```yaml
   services:
     web:
       build: .
       ports:
         - "8000:8000"
   ```

### [Run the application](#run-the-application)

From the `django-docker` directory, run:

```console
$ docker compose up --build
```

Open a browser and navigate to <http://localhost:8000>. You should see the Django welcome page.

Press `ctrl`+`c` to stop the application.

***

## [Set up a development environment](#set-up-a-development-environment)

The production setup uses Gunicorn and requires a full image rebuild to pick up code changes. For development, you can add a `development` stage to your Dockerfile that uses Django's built-in server, and configure Compose Watch to automatically sync code changes into the running container without a rebuild.

### [Update the Dockerfile](#update-the-dockerfile)

Replace your `Dockerfile` with a multi-stage version that adds a `development` stage alongside `production`:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1

# Build stage: the -dev image includes tools needed to install packages.
FROM dhi.io/python:3.14-alpine3.23-dev AS builder

# Prevent Python from writing .pyc files to disk.
ENV PYTHONDONTWRITEBYTECODE=1
# Prevent Python from buffering stdout/stderr so logs appear immediately.
ENV PYTHONUNBUFFERED=1

RUN pip install --quiet --root-user-action=ignore uv
# Use copy mode since the cache and build filesystem are on different volumes.
ENV UV_LINK_MODE=copy

WORKDIR /app

# Install dependencies into a virtual environment using cache and bind mounts
# so neither uv nor the lock files need to be copied into the image.
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --frozen --no-install-project

# The development stage inherits the -dev image and virtual environment from
# the builder. Django's built-in server reloads when Compose Watch syncs files.
FROM builder AS development

ENV PATH="/app/.venv/bin:$PATH"

COPY . .
EXPOSE 8000
CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

# The production stage uses the minimal runtime image, which has no shell,
# no package manager, and already runs as the nonroot user.
FROM dhi.io/python:3.14-alpine3.23 AS production

# Prevent Python from buffering stdout/stderr so logs appear immediately.
ENV PYTHONUNBUFFERED=1
# Activate the virtual environment copied from the build stage.
ENV PATH="/app/.venv/bin:$PATH"

WORKDIR /app

# Copy only the pre-built virtual environment and application source code.
COPY --from=builder /app/.venv /app/.venv
COPY . .

EXPOSE 8000

# Run Gunicorn as the production WSGI server.
CMD ["gunicorn", "myapp.wsgi:application", "--bind", "0.0.0.0:8000"]
```

### [Update the Compose file](#update-the-compose-file)

Replace your `compose.yaml` with the following. It targets the `development` stage, adds a PostgreSQL database, and configures Compose Watch:

compose.yaml

```yaml
services:
  web:
    build:
      context: .
      # Build the development stage from the multi-stage Dockerfile.
      target: development
    ports:
      - "8000:8000"
    environment:
      # Enable Django's verbose debug error pages (the dev server always auto-reloads).
      - DEBUG=1
      # Database connection settings passed to Django via environment variables.
      - POSTGRES_DB=myapp
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
      - POSTGRES_HOST=db
      - POSTGRES_PORT=5432
    # Wait for the database to pass its healthcheck before starting the web service.
    depends_on:
      db:
        condition: service_healthy
    develop:
      watch:
        # Sync source file changes directly into the container so Django's
        # dev server can reload them without a full image rebuild.
        - action: sync
          path: .
          target: /app
          ignore:
            - __pycache__/
            - "*.pyc"
            - .git/
            - .venv/
        # Rebuild the image when dependencies change.
        - action: rebuild
          path: pyproject.toml
        - action: rebuild
          path: uv.lock
  db:
    image: dhi.io/postgres:18
    restart: always
    volumes:
      # Persist database data across container restarts.
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    # Expose the port only to other services on the Compose network,
    # not to the host machine.
    expose:
      - 5432
    # Only report healthy once PostgreSQL is ready to accept connections,
    # so the web service doesn't start before the database is available.
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
```

The `sync` action pushes file changes directly into the running container so Django's dev server reloads them automatically. A change to `pyproject.toml` or `uv.lock` triggers a full image rebuild instead.

> Note
>
> To learn more about Compose Watch, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

### [Add the PostgreSQL driver](#add-the-postgresql-driver)

Add the `psycopg` adapter to your project:

```console
$ uv add 'psycopg[binary]'
```

```console
$ docker run --rm -v $PWD:$PWD -w $PWD \
  -e UV_LINK_MODE=copy \
  dhi.io/python:3.14-alpine3.23-dev \
  sh -c "pip install --quiet --root-user-action=ignore uv && uv add 'psycopg[binary]'"
```

Then update `myapp/settings.py` to read `DEBUG` and `DATABASES` from environment variables:

myapp/settings.py

```python
import os

DEBUG = os.environ.get('DEBUG', '0') == '1'

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ.get("POSTGRES_DB", "myapp"),
        "USER": os.environ.get("POSTGRES_USER", "postgres"),
        "PASSWORD": os.environ.get("POSTGRES_PASSWORD", "password"),
        "HOST": os.environ.get("POSTGRES_HOST", "localhost"),
        "PORT": os.environ.get("POSTGRES_PORT", "5432"),
    }
}
```

### [Run with Compose Watch](#run-with-compose-watch)

Start the development stack:

```console
$ docker compose watch
```

Open a browser and navigate to <http://localhost:8000>.

Try editing a file, for example add a view to `myapp/views.py`. Compose Watch syncs the change into the container and Django's dev server reloads automatically. If you update `pyproject.toml` or `uv.lock`, Compose Watch triggers a full image rebuild.

Press `ctrl`+`c` to stop.

***

## [Summary](#summary)

In this guide, you:

* Bootstrapped a Django project using uv, with options for both local and containerized setup.
* Created a production-ready Dockerfile using Docker Hardened Images and uv for dependency management.
* Added a `development` stage to the `Dockerfile` and configured Compose Watch for fast iterative development with a PostgreSQL database.

Related information:

* [Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
* [Compose file reference](https://docs.docker.com/reference/compose-file/)
* [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/)
* [Docker Hardened Images](/dhi/)
* [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/)
* [uv documentation](https://docs.astral.sh/uv/)

----
url: https://docs.docker.com/reference/cli/sbx/kit/validate/
----

# sbx kit validate

| Description | Validate a kit artifact              |
| ----------- | ------------------------------------ |
| Usage       | `sbx kit validate REFERENCE [flags]` |

## [Description](#description)

Validate that a directory or ZIP file is a valid kit artifact.

The reference can be a local directory, ZIP file path, or git repository.

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/docker-hub/repos/manage/hub-images/immutable-tags/
----

# Immutable tags on Docker Hub

***

Table of contents

***

Availability: Beta

Immutable tags provide a way to ensure that specific image versions remain unchanged once they are published to Docker Hub. This feature helps maintain consistency and reliability in your container deployments by preventing accidental overwrites of important image versions.

## [What are immutable tags?](#what-are-immutable-tags)

Immutable tags are image tags that, once pushed to Docker Hub, cannot be overwritten or deleted. This ensures that a specific version of an image remains exactly the same throughout its lifecycle, providing:

* Version consistency
* Reproducible builds
* Protection against accidental overwrites
* Better security and compliance

## [Enable immutable tags](#enable-immutable-tags)

To enable immutable tags for your repository:

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

3. Select the repository where you want to enable immutable tags.

4. Go to **Settings** > **General**.

5. Under **Tag mutability settings**, select one of the following options:

   * **All tags are mutable (Default)**:\
     Tags can be changed to reference a different image. This lets you retarget a tag without creating a new one.
   * **All tags are immutable**:\
     Tags cannot be updated to point to a different image after creation. This ensures consistency and prevents accidental changes. This includes the `latest` tag.
   * **Specific tags are immutable**:\
     Define specific tags that cannot be updated after creation using regex values.

6. Select **Save**.

Once enabled, all tags are locked to their specific images, ensuring that each tag always points to the same image version and cannot be modified.

> Note
>
> This implementation of regular expressions follows the [Go regexp package](https://pkg.go.dev/regexp), which is based on the RE2 engine. For more information, visit [RE2 Regular Expression Syntax](https://github.com/google/re2/wiki/Syntax).

## [Working with immutable tags](#working-with-immutable-tags)

When immutable tags are enabled:

* You cannot push a new image with the same tag name
* You must use a new tag name for each new image version

To push an image, create a new tag for your updated image and push it to the repository.

----
url: https://docs.docker.com/compose/intro/compose-application-model/
----

# How Compose works

***

Table of contents

***

With Docker Compose you use a YAML configuration file, known as the [Compose file](#the-compose-file), to configure your application’s services, and then you create and start all the services from your configuration with the [Compose CLI](#cli).

The Compose file, or `compose.yaml` file, follows the rules provided by the [Compose Specification](https://docs.docker.com/reference/compose-file/) in how to define multi-container applications. This is the Docker Compose implementation of the formal [Compose Specification](https://github.com/compose-spec/compose-spec).

Computing components of an application are defined as [services](https://docs.docker.com/reference/compose-file/services/). A service is an abstract concept implemented on platforms by running the same container image, and configuration, one or more times.

Services communicate with each other through [networks](https://docs.docker.com/reference/compose-file/networks/). In the Compose Specification, a network is a platform capability abstraction to establish an IP route between containers within services connected together.

Services store and share persistent data into [volumes](https://docs.docker.com/reference/compose-file/volumes/). The Specification describes such a persistent data as a high-level filesystem mount with global options.

Some services require configuration data that is dependent on the runtime or platform. For this, the Specification defines a dedicated [configs](https://docs.docker.com/reference/compose-file/configs/) concept. From inside the container, configs behave like volumes—they’re mounted as files. However, configs are defined differently at the platform level.

A [secret](https://docs.docker.com/reference/compose-file/secrets/) is a specific flavor of configuration data for sensitive data that should not be exposed without security considerations. Secrets are made available to services as files mounted into their containers, but the platform-specific resources to provide sensitive data are specific enough to deserve a distinct concept and definition within the Compose Specification.

> Note
>
> With volumes, configs and secrets you can have a simple declaration at the top-level and then add more platform-specific information at the service level.

A project is an individual deployment of an application specification on a platform. A project's name, set with the top-level [`name`](https://docs.docker.com/reference/compose-file/version-and-name/) attribute, is used to group resources together and isolate them from other applications or other installation of the same Compose-specified application with distinct parameters. If you are creating resources on a platform, you must prefix resource names by project and set the label `com.docker.compose.project`.

Compose offers a way for you to set a custom project name and override this name, so that the same `compose.yaml` file can be deployed twice on the same infrastructure, without changes, by just passing a distinct name.

## [The Compose file](#the-compose-file)

The default path for a Compose file is `compose.yaml` (preferred) or `compose.yml` that is placed in the working directory. Compose also supports `docker-compose.yaml` and `docker-compose.yml` for backwards compatibility of earlier versions. If both files exist, Compose prefers the canonical `compose.yaml`.

You can use [fragments](https://docs.docker.com/reference/compose-file/fragments/) and [extensions](https://docs.docker.com/reference/compose-file/extension/) to keep your Compose file efficient and easy to maintain.

Multiple Compose files can be [merged](https://docs.docker.com/reference/compose-file/merge/) together to define the application model. The combination of YAML files is implemented by appending or overriding YAML elements based on the Compose file order you set. Simple attributes and maps get overridden by the highest order Compose file, lists get merged by appending. Relative paths are resolved based on the first Compose file's parent folder, whenever complementary files being merged are hosted in other folders. As some Compose file elements can both be expressed as single strings or complex objects, merges apply to the expanded form. For more information, see [Working with multiple Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/).

If you want to reuse other Compose files, or factor out parts of your application model into separate Compose files, you can also use [`include`](https://docs.docker.com/reference/compose-file/include/). This is useful if your Compose application is dependent on another application which is managed by a different team, or needs to be shared with others.

## [CLI](#cli)

The Docker CLI lets you interact with your Docker Compose applications through the `docker compose` command and its subcommands. If you're using Docker Desktop, the Docker Compose CLI is included by default.

Using the CLI, you can manage the lifecycle of your multi-container applications defined in the `compose.yaml` file. The CLI commands enable you to start, stop, and configure your applications effortlessly.

### [Key commands](#key-commands)

To start all the services defined in your `compose.yaml` file:

```console
$ docker compose up
```

To stop and remove the running services:

```console
$ docker compose down 
```

If you want to monitor the output of your running containers and debug issues, you can view the logs with:

```console
$ docker compose logs
```

To list all the services along with their current status:

```console
$ docker compose ps
```

For a full list of all the Compose CLI commands, see the [reference documentation](/reference/cli/docker/compose/).

## [Illustrative example](#illustrative-example)

The following example illustrates the Compose concepts outlined above. The example is non-normative.

Consider an application split into a frontend web application and a backend service.

The frontend is configured at runtime with an HTTP configuration file managed by infrastructure, providing an external domain name, and an HTTPS server certificate injected by the platform's secured secret store.

The backend stores data in a persistent volume.

Both services communicate with each other on an isolated back-tier network, while the frontend is also connected to a front-tier network and exposes port 443 for external usage.

The example application is composed of the following parts:

* Two services, backed by Docker images: `webapp` and `database`
* One secret (HTTPS certificate), injected into the frontend
* One configuration (HTTP), injected into the frontend
* One persistent volume, attached to the backend
* Two networks

```yml
services:
  frontend:
    image: example/webapp
    ports:
      - "443:8043"
    networks:
      - front-tier
      - back-tier
    configs:
      - httpd-config
    secrets:
      - server-certificate

  backend:
    image: example/database
    volumes:
      - db-data:/etc/data
    networks:
      - back-tier

volumes:
  db-data:
    driver: flocker
    driver_opts:
      size: "10GiB"

configs:
  httpd-config:
    external: true

secrets:
  server-certificate:
    external: true

networks:
  # The presence of these objects is sufficient to define them
  front-tier: {}
  back-tier: {}
```

The `docker compose up` command starts the `frontend` and `backend` services, creates the necessary networks and volumes, and injects the configuration and secret into the frontend service.

`docker compose ps` provides a snapshot of the current state of your services, making it easy to see which containers are running, their status, and the ports they are using:

```text
$ docker compose ps

NAME                IMAGE                COMMAND                  SERVICE             CREATED             STATUS              PORTS
example-frontend-1  example/webapp       "nginx -g 'daemon of…"   frontend            2 minutes ago       Up 2 minutes        0.0.0.0:443->8043/tcp
example-backend-1   example/database     "docker-entrypoint.s…"   backend             2 minutes ago       Up 2 minutes
```

## [What's next](#whats-next)

* [Try the Quickstart guide](https://docs.docker.com/compose/gettingstarted/)
* [Explore some sample applications](https://github.com/docker/awesome-compose)
* [Familiarize yourself with the Compose Specification](https://docs.docker.com/reference/compose-file/)

----
url: https://docs.docker.com/engine/network/port-publishing/
----

# Port publishing and mapping

***

Table of contents

***

By default, for both IPv4 and IPv6, the Docker daemon blocks access to ports that have not been published. Published container ports are mapped to host IP addresses. To do this, it uses firewall rules to perform Network Address Translation (NAT), Port Address Translation (PAT), and masquerading.

For example, `docker run -p 8080:80 [...]` creates a mapping between port 8080 on any address on the Docker host, and the container's port 80. Outgoing connections from the container will masquerade, using the Docker host's IP address.

## [Publishing ports](#publishing-ports)

When you create or run a container using `docker create` or `docker run`, all ports of containers on bridge networks are accessible from the Docker host and other containers connected to the same network. Ports are not accessible from outside the host or, with the default configuration, from containers in other networks.

Use the `--publish` or `-p` flag to make a port available outside the host, and to containers in other bridge networks.

This creates a firewall rule in the host, mapping a container port to a port on the Docker host to the outside world. Here are some examples:

| Flag value                      | Description                                                                                                                                             |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p 8080:80`                    | Map port `8080` on the Docker host to TCP port `80` in the container.                                                                                   |
| `-p 192.168.1.100:8080:80`      | Map port `8080` on the Docker host IP `192.168.1.100` to TCP port `80` in the container.                                                                |
| `-p 8080:80/udp`                | Map port `8080` on the Docker host to UDP port `80` in the container.                                                                                   |
| `-p 8080:80/tcp -p 8080:80/udp` | Map TCP port `8080` on the Docker host to TCP port `80` in the container, and map UDP port `8080` on the Docker host to UDP port `80` in the container. |

> Important
>
> Publishing container ports is insecure by default. Meaning, when you publish a container's ports it becomes available not only to the Docker host, but to the outside world as well.
>
> If you include the localhost IP address (`127.0.0.1`, or `::1`) with the publish flag, only the Docker host can access the published container port.
>
> ```console
> $ docker run -p 127.0.0.1:8080:80 -p '[::1]:8080:80' nginx
> ```
>
> > Warning
> >
> > In releases older than 28.0.0, hosts within the same L2 segment (for example, hosts connected to the same network switch) can reach ports published to localhost. For more information, see [moby/moby#45610](https://github.com/moby/moby/issues/45610)

Ports on the host's IPv6 addresses will map to the container's IPv4 address if no host IP is given in a port mapping, the bridge network is IPv4-only, and `--userland-proxy=true` (default).

## [Direct routing](#direct-routing)

Port mapping ensures that published ports are accessible on the host's network addresses, which are likely to be routable for any external clients. No routes are normally set up in the host's network for container addresses that exist within a host.

But, particularly with IPv6 you may prefer to avoid using NAT and instead arrange for external routing to container addresses ("direct routing").

To access containers on a bridge network from outside the Docker host, you must first set up routing to the bridge network via an address on the Docker host. This can be achieved using static routes, Border Gateway Protocol (BGP), or any other means appropriate for your network. For example, within a local layer 2 network, remote hosts can set up static routes to a container network via the Docker daemon host's address on the local network.

### [Direct routing to containers in bridge networks](#direct-routing-to-containers-in-bridge-networks)

By default, remote hosts are not allowed direct access to container IP addresses in Docker's Linux bridge networks. They can only access ports published to host IP addresses.

To allow direct access to any published port, on any container, in any Linux bridge network, use daemon option `"allow-direct-routing": true` in `/etc/docker/daemon.json` or the equivalent `--allow-direct-routing`.

To allow direct routing from anywhere to containers in a specific bridge network, see [Gateway modes](#gateway-modes).

Or, to allow direct routing via specific host interfaces, to a specific bridge network, use the following option when creating the network:

* `com.docker.network.bridge.trusted_host_interfaces`

#### [Example](#example)

Create a network where published ports on container IP addresses can be accessed directly from interfaces `vxlan.1` and `eth3`:

```console
$ docker network create --subnet 192.0.2.0/24 --ip-range 192.0.2.0/29 -o com.docker.network.bridge.trusted_host_interfaces="vxlan.1:eth3" mynet
```

Run a container in that network, publishing its port 80 to port 8080 on the host's loopback interface:

```console
$ docker run -d --ip 192.0.2.100 -p 127.0.0.1:8080:80 nginx
```

The web server running on the container's port 80 can now be accessed from the Docker host at `http://127.0.0.1:8080`, or directly at `http://192.0.2.100:80`. If remote hosts on networks connected to interfaces `vxlan.1` and `eth3` have a route to the `192.0.2.0/24` network inside the Docker host, they can also access the web server via `http://192.0.2.100:80`.

## [Gateway modes](#gateway-modes)

The bridge network driver has the following options:

* `com.docker.network.bridge.gateway_mode_ipv6`
* `com.docker.network.bridge.gateway_mode_ipv4`

Each of these can be set to one of the gateway modes:

* `nat`
* `nat-unprotected`
* `routed`
* `isolated`

The default is `nat`, NAT and masquerading rules are set up for each published container port. Packets leaving the host will use a host address.

With mode `routed`, no NAT or masquerading rules are set up, but firewall rules are still set up so that only published container ports are accessible. Outgoing packets from the container will use the container's address, not a host address.

To access a published port in a `routed` network, remote hosts must have a route to the container network via an external address on the Docker host ("direct routing"). Hosts on the local layer-2 network can set up direct routing without needing any additional network configuration. Hosts outside the local network can only use direct routing to the container if the network's routers are configured to enable it.

In a `nat` mode network, publishing a port to an address on the loopback interface means remote hosts cannot access it. Other published container ports in `routed` and `nat` networks are always accessible from remote hosts using direct routing, unless the Docker host's firewall has additional restrictions.

> Note
>
> When a port is published to a specific host address in `nat` mode, if IP forwarding is enabled on the Docker host, the published port can be accessed via other host interfaces using direct routing to the host address.
>
> For example, a Docker host with IP forwarding enabled has two NICs with addresses `192.168.100.10/24` and `10.0.0.10/24`. When a port is published to `192.168.100.10`, a host in the `10.0.0.0/24` subnet can access that port by routing to `192.168.100.10` via `10.0.0.10`.

In `nat-unprotected` mode, unpublished container ports are also accessible using direct routing, no port filtering rules are set up. This mode is included for compatibility with legacy default behaviour.

The gateway mode also affects communication between containers that are connected to different Docker networks on the same host.

* In `nat` and `nat-unprotected` modes, containers in other bridge networks can only access published ports via the host addresses they are published to. Direct routing from other networks is not allowed.
* In `routed` mode containers in other networks can use direct routing to access ports, without going via a host address.

In `routed` mode, a host port in a `-p` or `--publish` port mapping is not used, and the host address is only used to decide whether to apply the mapping to IPv4 or IPv6. So, when a mapping only applies to `routed` mode, only addresses `0.0.0.0` or `::` should be used, and a host port should not be given. If a specific address or port is given, it will have no effect on the published port and a warning message will be logged.

Mode `isolated` can only be used when the network is also created with CLI flag `--internal`, or equivalent. An address is normally assigned to the bridge device in an `internal` network. So, processes on the Docker host can access the network, and containers in the network can access host services listening on that bridge address (including services listening on "any" host address, `0.0.0.0` or `::`). No address is assigned to the bridge when the network is created with gateway mode `isolated`.

### [Example](#example-1)

Create a network suitable for direct routing for IPv6, with NAT enabled for IPv4:

```console
$ docker network create --ipv6 --subnet 2001:db8::/64 -o com.docker.network.bridge.gateway_mode_ipv6=routed mynet
```

Create a container with a published port:

```console
$ docker run --network=mynet -p 8080:80 myimage
```

Then:

* Only container port 80 will be open, for IPv4 and IPv6.
* For IPv6, using `routed` mode, port 80 will be open on the container's IP address. Port 8080 will not be opened on the host's IP addresses, and outgoing packets will use the container's IP address.
* For IPv4, using the default `nat` mode, the container's port 80 will be accessible via port 8080 on the host's IP addresses, as well as directly from within the Docker host. But, container port 80 cannot be accessed directly from outside the host. Connections originating from the container will masquerade, using the host's IP address.

In `docker inspect`, this port mapping will be shown as follows. Note that there is no `HostPort` for IPv6, because it is using `routed` mode:

```console
$ docker container inspect <id> --format "{{json .NetworkSettings.Ports}}"
{"80/tcp":[{"HostIp":"0.0.0.0","HostPort":"8080"},{"HostIp":"::","HostPort":""}]}
```

Alternatively, to make the mapping IPv6-only, disabling IPv4 access to the container's port 80, use the unspecified IPv6 address `[::]` and do not include a host port number:

```console
$ docker run --network mynet -p '[::]::80'
```

## [Setting the default bind address for containers](#setting-the-default-bind-address-for-containers)

By default, when a container's ports are mapped without any specific host address, the Docker daemon publishes ports to all host addresses (`0.0.0.0` and `[::]`).

For example, the following command publishes port 8080 to all network interfaces on the host, on both IPv4 and IPv6 addresses, potentially making them available to the outside world.

```console
docker run -p 8080:80 nginx
```

You can change the default binding address for published container ports so that they're only accessible to the Docker host by default. To do that, you can configure the daemon to use the loopback address (`127.0.0.1`) instead.

> Warning
>
> In releases older than 28.0.0, hosts within the same L2 segment (for example, hosts connected to the same network switch) can reach ports published to localhost. For more information, see [moby/moby#45610](https://github.com/moby/moby/issues/45610)

To configure this setting for user-defined bridge networks, use the `com.docker.network.bridge.host_binding_ipv4` [driver option](https://docs.docker.com/engine/network/drivers/bridge/#default-host-binding-address) when you create the network. Despite the option name, it is possible to specify an IPv6 address.

```console
$ docker network create mybridge \
  -o "com.docker.network.bridge.host_binding_ipv4=127.0.0.1"
```

Or, to set the default binding address for containers in all user-defined bridge networks, use daemon configuration option `default-network-opts`. For example:

```json
{
  "default-network-opts": {
    "bridge": {
      "com.docker.network.bridge.host_binding_ipv4": "127.0.0.1"
    }
  }
}
```

> Note
>
> Setting the default binding address to `::` means port bindings with no host address specified will work for any IPv6 address on the host. But, `0.0.0.0` means any IPv4 or IPv6 address.
>
> Changing the default bind address doesn't have any effect on Swarm services. Swarm services are always exposed on the `0.0.0.0` network interface.

### [Masquerade or SNAT for outgoing packets](#masquerade-or-snat-for-outgoing-packets)

NAT is enabled by default for bridge networks, meaning outgoing packets from containers are masqueraded. The source address of packets leaving the Docker host is changed to an address on the host interface the packet is sent on.

Masquerading can be disabled for a user-defined bridge network by using the `com.docker.network.bridge.enable_ip_masquerade` driver option when creating the network. For example:

```console
$ docker network create mybridge \
  -o com.docker.network.bridge.enable_ip_masquerade=false ...
```

To use a specific source address for outgoing packets for a user-defined network, instead of letting masquerading select an address, use options `com.docker.network.host_ipv4` and `com.docker.network.host_ipv6` to specify the Source NAT (SNAT) address to use. The `com.docker.network.bridge.enable_ip_masquerade` option must be `true`, the default, for these options to have any effect.

### [Default bridge](#default-bridge)

To set the default binding for the default bridge network, configure the `"ip"` key in the `daemon.json` configuration file:

```json
{
  "ip": "127.0.0.1"
}
```

This changes the default binding address to `127.0.0.1` for published container ports on the default bridge network. Restart the daemon for this change to take effect. Alternatively, you can use the `dockerd --ip` flag when starting the daemon.

----
url: https://docs.docker.com/engine/daemon/logs/
----

# Read the daemon logs

***

Table of contents

***

The daemon logs may help you diagnose problems. The logs may be saved in one of a few locations, depending on the operating system configuration and the logging subsystem used:

| Operating system             | Location                                                                                                                                 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Linux                        | Use the command `journalctl -xu docker.service` (or read `/var/log/syslog` or `/var/log/messages`, depending on your Linux Distribution) |
| macOS (Docker Desktop)       | `~/Library/Containers/com.docker.docker/Data/log/vm/init.log`                                                                            |
| Windows (WSL2)               | `%LOCALAPPDATA%\Docker\log\vm\init.log`                                                                                                  |
| Windows (Windows containers) | Logs are in the Windows Event Log                                                                                                        |

On macOS and Windows (WSL2), Docker Desktop writes daemon logs (`dockerd`, `containerd`, and other VM services) to a single multiplexed `init.log` file in JSON format. Each line contains a `"component"` field identifying the service. To follow the logs, open a terminal and use the `tail` command with the `-f` flag. Logs print until you terminate the command using `CTRL+c`:

```console
$ tail -f ~/Library/Containers/com.docker.docker/Data/log/vm/init.log
{"component":"dockerd","level":"debug","msg":"attach: stdout: begin","time":"2021-07-28T10:21:21.497642089Z"}
{"component":"dockerd","level":"debug","msg":"attach: stderr: begin","time":"2021-07-28T10:21:21.497714291Z"}
...
^C
```

To filter for `dockerd` output only:

```console
$ grep '"component":"dockerd"' ~/Library/Containers/com.docker.docker/Data/log/vm/init.log
```

## [Enable debugging](#enable-debugging)

There are two ways to enable debugging. The recommended approach is to set the `debug` key to `true` in the `daemon.json` file. This method works for every Docker platform.

1. Edit the `daemon.json` file, which is usually located in `/etc/docker/`. You may need to create this file, if it doesn't yet exist. On macOS or Windows, don't edit the file directly. Instead, edit the file through the Docker Desktop settings.

2. If the file is empty, add the following:

   ```json
   {
     "debug": true
   }
   ```

   If the file already contains JSON, just add the key `"debug": true`, being careful to add a comma to the end of the line if it's not the last line before the closing bracket. Also verify that if the `log-level` key is set, it's set to either `info` or `debug`. `info` is the default, and possible values are `debug`, `info`, `warn`, `error`, `fatal`.

3. Send a `HUP` signal to the daemon to cause it to reload its configuration. On Linux hosts, use the following command.

   ```console
   $ sudo kill -SIGHUP $(pidof dockerd)
   ```

   On Windows hosts, restart Docker.

Instead of following this procedure, you can also stop the Docker daemon and restart it manually with the debug flag `-D`. However, this may result in Docker restarting with a different environment than the one the hosts' startup scripts create, and this may make debugging more difficult.

## [Force a stack trace to be logged](#force-a-stack-trace-to-be-logged)

If the daemon is unresponsive, you can force a full stack trace to be logged by sending a `SIGUSR1` signal to the daemon.

* **Linux**:

  ```console
  $ sudo kill -SIGUSR1 $(pidof dockerd)
  ```

* **Windows Server**:

  Download [docker-signal](https://github.com/moby/docker-signal).

  Get the process ID of dockerd `Get-Process dockerd`.

  Run the executable with the flag `--pid=<PID of daemon>`.

This forces a stack trace to be logged but doesn't stop the daemon. Daemon logs show the stack trace or the path to a file containing the stack trace if it was logged to a file.

The daemon continues operating after handling the `SIGUSR1` signal and dumping the stack traces to the log. The stack traces can be used to determine the state of all goroutines and threads within the daemon.

## [View stack traces](#view-stack-traces)

The Docker daemon log can be viewed by using one of the following methods:

* By running `journalctl -u docker.service` on Linux systems using `systemctl`
* `/var/log/messages`, `/var/log/daemon.log`, or `/var/log/docker.log` on older Linux systems

> Note
>
> It isn't possible to manually generate a stack trace on Docker Desktop for Mac or Docker Desktop for Windows. However, you can click the Docker taskbar icon and choose **Troubleshoot** to send information to Docker if you run into issues.

Look in the Docker logs for a message like the following:

```text
...goroutine stacks written to /var/run/docker/goroutine-stacks-2017-06-02T193336z.log
```

The locations where Docker saves these stack traces and dumps depends on your operating system and configuration. You can sometimes get useful diagnostic information straight from the stack traces and dumps. Otherwise, you can provide this information to Docker for help diagnosing the problem.

----
url: https://docs.docker.com/reference/cli/docker/offload/status/
----

# docker offload status

***

| Description | Show the status of the Docker Offload connection |
| ----------- | ------------------------------------------------ |
| Usage       | `docker offload status [OPTIONS]`                |

## [Options](#options)

| Option         | Default  | Description                                              |
| -------------- | -------- | -------------------------------------------------------- |
| `-f, --format` | `pretty` | Format of output (default: pretty, one of: pretty\|json) |
| `-w, --watch`  |          | Watch for status updates                                 |

----
url: https://docs.docker.com/reference/cli/docker/trust/key/
----

# docker trust key

***

| Description | Manage keys for signing Docker images |
| ----------- | ------------------------------------- |
| Usage       | `docker trust key`                    |

## [Description](#description)

Manage keys for signing Docker images

## [Subcommands](#subcommands)

| Command                                                                                         | Description                          |
| ----------------------------------------------------------------------------------------------- | ------------------------------------ |
| [`docker trust key generate`](https://docs.docker.com/reference/cli/docker/trust/key/generate/) | Generate and load a signing key-pair |
| [`docker trust key load`](https://docs.docker.com/reference/cli/docker/trust/key/load/)         | Load a private key file for signing  |

----
url: https://docs.docker.com/reference/api/hub/changelog/
----

# Docker Hub API changelog

***

Table of contents

***

Here you can learn about the latest changes, new features, bug fixes, and known issues for Docker Service APIs.

***

## [2025-11-21](#2025-11-21)

### [Updates](#updates)

* Add missing `expires_at` fields on [PAT management](/reference/api/hub/latest/#tag/access-tokens) endpoints.

## [2025-09-25](#2025-09-25)

### [Updates](#updates-1)

* Fix [Assign repository group](/reference/api/hub/latest/#tag/repositories/operation/CreateRepositoryGroup) endpoints request/response

***

## [2025-09-19](#2025-09-19)

### [New](#new)

* Add [Create repository](/reference/api/hub/latest/#tag/repositories/operation/CreateRepository) endpoints for a given `namespace`.
* Add [Get repository](/reference/api/hub/latest/#tag/repositories/operation/GetRepository) endpoints for a given `namespace`.
* Add [Check repository](/reference/api/hub/latest/#tag/repositories/operation/CheckRepository) endpoints for a given `namespace`.

### [Deprecations](#deprecations)

* [Deprecate POST /v2/repositories](/reference/api/hub/deprecated/#deprecate-legacy-createrepository)
* [Deprecate POST /v2/repositories/{namespace}](/reference/api/hub/deprecated/#deprecate-legacy-createrepository)
* [Deprecate GET /v2/repositories/{namespace}/{repository}](/reference/api/hub/deprecated/#deprecate-legacy-getrepository)
* [Deprecate HEAD /v2/repositories/{namespace}/{repository}](/reference/api/hub/deprecated/#deprecate-legacy-getrepository)

***

## [2025-07-29](#2025-07-29)

### [New](#new-1)

* Add [Update repository immutable tags settings](/reference/api/hub/latest/#tag/repositories/operation/UpdateRepositoryImmutableTags) endpoints for a given `namespace` and `repository`.
* Add [Verify repository immutable tags](/reference/api/hub/latest/#tag/repositories/operation/VerifyRepositoryImmutableTags) endpoints for a given `namespace` and `repository`.

***

## [2025-06-27](#2025-06-27)

### [New](#new-2)

* Add [List repositories](/reference/api/hub/latest/#tag/repositories/operation/listNamespaceRepositories) endpoints for a given `namespace`.

### [Deprecations](#deprecations-1)

* [Deprecate /v2/repositories/{namespace}](/reference/api/hub/deprecated/#deprecate-legacy-listnamespacerepositories)

***

## [2025-03-25](#2025-03-25)

### [New](#new-3)

* Add [APIs](/reference/api/hub/latest/#tag/org-access-tokens) for organization access token (OATs) management.

***

## [2025-03-18](#2025-03-18)

### [New](#new-4)

* Add access to [audit logs](/reference/api/hub/latest/#tag/audit-logs) for org access tokens.

----
url: https://docs.docker.com/desktop/features/wsl/best-practices/
----

# WSL 2 best practices for Docker Desktop on Windows

***

Table of contents

***

This page covers recommendations when running Docker Desktop on Windows using WSL 2, including version requirements and file system performance.

## [Keep WSL up to date](#keep-wsl-up-to-date)

Always use the latest version of WSL.

At a minimum you must use WSL version 2.1.5, otherwise Docker Desktop may not work as expected. Additionally, if you intend to use Enhanced Container Isolation, ensure you’re using WSL version 2.6 or later. This is required because ECI depends on a Linux kernel version of at least 6.3.0, and WSL 2.6+ bundles Linux kernel version 6.6. Testing, development, and documentation is based on the newest kernel versions. Older versions of WSL can cause:

* Docker Desktop to hang periodically or when upgrading
* Deployment via SCCM to fail
* The `vmmem.exe` to consume all memory
* Network filter policies to be applied globally, not to specific objects
* GPU failures with containers

## [Optimise file system performance with bind mounts](#optimise-file-system-performance-with-bind-mounts)

To get the best out of the file system performance when bind-mounting files, store source code and other data that is bind-mounted into Linux containers. For instance, use `docker run -v <host-path>:<container-path>` in the Linux file system, rather than the Windows file system. You can also refer to [Microsoft's recommendation](https://learn.microsoft.com/en-us/windows/wsl/compare-versions).

Linux containers only receive file change events, “inotify events”, if the original files are stored in the Linux filesystem. For example, some web development workflows rely on inotify events for automatic reloading when files have changed.

Performance is much higher when files are bind-mounted from the Linux filesystem, rather than accessed from the Windows host filesystem. Therefore avoid `docker run -v /mnt/c/users:/users` where `/mnt/c` is mounted from Windows.

Instead, from a Linux shell use a command like `docker run -v ~/my-project:/sources <my-image>` where `~` is expanded by the Linux shell to `$HOME`.

## [Limit CPU and memory usage](#limit-cpu-and-memory-usage)

If you have concerns about CPU or memory usage, configure limits on the memory, CPU, and swap size allocated to the [WSL 2 utility VM](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#global-configuration-options-with-wslconfig).

----
url: https://docs.docker.com/reference/cli/sbx/policy/set-default/
----

# sbx policy set-default

| Description | Set the default network policy                                   |
| ----------- | ---------------------------------------------------------------- |
| Usage       | `sbx policy set-default <allow-all\|balanced\|deny-all> [flags]` |

## [Description](#description)

Set the default network policy for all sandboxes.

This must be run before adding custom allow/deny rules or starting a sandbox for the first time. The default policy determines the baseline network access.

Available policies: allow-all All outbound network traffic is allowed balanced Typical development traffic is allowed (AI services, package registries, etc.) deny-all All outbound network traffic is blocked

After setting defaults, use "sbx policy allow/deny" to add custom rules. Use "sbx policy reset" to clear all policies and start over.

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Set balanced defaults (recommended)
sbx policy set-default balanced

# Allow all traffic
sbx policy set-default allow-all

# Block everything, then allow specific sites
sbx policy set-default deny-all
sbx policy allow network -g api.example.com:443
```

----
url: https://docs.docker.com/compose/bridge/use-model-runner/
----

# Use Docker Model Runner with Compose Bridge

***

Table of contents

***

Compose Bridge supports model-aware deployments. It can deploy and configure Docker Model Runner, a lightweight service that hosts and serves machine LLMs.

This reduces manual setup for LLM-enabled services and keeps deployments consistent across Docker Desktop and Kubernetes environments.

If you have a `models` top-level element in your `compose.yaml` file, Compose Bridge:

* Automatically injects environment variables for each model’s endpoint and name.
* Configures model endpoints differently for Docker Desktop vs Kubernetes.
* Optionally deploys Docker Model Runner in Kubernetes when enabled in Helm values

## [Configure model runner settings](#configure-model-runner-settings)

When deploying using generated Helm Charts, you can control the model runner configuration through Helm values.

```yaml
# Model Runner settings
modelRunner:
    # Set to false for Docker Desktop (uses host instance)
    # Set to true for standalone Kubernetes clusters
    enabled: false
    # Endpoint used when enabled=false (Docker Desktop)
    hostEndpoint: "http://host.docker.internal:12434/engines/v1/"
    # Deployment settings when enabled=true
    image: "docker/model-runner:latest"
    imagePullPolicy: "IfNotPresent"
    # GPU support
    gpu:
        enabled: false
        vendor: "nvidia" # nvidia or amd
        count: 1
    # Node scheduling (uncomment and customize as needed)
    # nodeSelector:
    #   accelerator: nvidia-tesla-t4
    # tolerations: []
    # affinity: {}

    # Security context
    securityContext:
        allowPrivilegeEscalation: false
    # Environment variables (uncomment and add as needed)
    # env:
    #   DMR_ORIGINS: "http://localhost:31246"
    resources:
        limits:
            cpu: "1000m"
            memory: "2Gi"
        requests:
            cpu: "100m"
            memory: "256Mi"
    # Storage for models
    storage:
        size: "100Gi"
        storageClass: "" # Empty uses default storage class
    # Models to pre-pull
    models:
        - ai/qwen2.5:latest
        - ai/mxbai-embed-large
```

## [Deploying a model runner](#deploying-a-model-runner)

### [Docker Desktop](#docker-desktop)

When `modelRunner.enabled` is `false`, Compose Bridge configures your workloads to connect to Docker Model Runner running on the host:

```text
http://host.docker.internal:12434/engines/v1/
```

The endpoint is automatically injected into your service containers.

### [Kubernetes](#kubernetes)

When `modelRunner.enabled` is `true`, Compose Bridge uses the generated manifests to deploy Docker Model Runner in your cluster, including:

* Deployment: Runs the `docker-model-runner` container
* Service: Exposes port `80` (maps to container port `12434`)
* `PersistentVolumeClaim`: Stores model files

The `modelRunner.enabled` setting also determines the number of replicas for the `model-runner-deployment`:

* When `true`, the deployment replica count is set to 1, and Docker Model Runner is deployed in the Kubernetes cluster.
* When `false`, the replica count is 0, and no Docker Model Runner resources are deployed.

----
url: https://docs.docker.com/engine/storage/bind-mounts/
----

# Bind mounts

***

Table of contents

***

When you use a bind mount, a file or directory on the host machine is mounted from the host into a container. By contrast, when you use a volume, a new directory is created within Docker's storage directory on the host machine. Docker creates and maintains this storage location, but containers access it directly using standard filesystem operations.

## [When to use bind mounts](#when-to-use-bind-mounts)

Bind mounts are appropriate for the following types of use case:

* Sharing source code or build artifacts between a development environment on the Docker host and a container.

* When you want to create or generate files in a container and persist the files onto the host's filesystem.

* Sharing configuration files from the host machine to containers. This is how Docker provides DNS resolution to containers by default, by mounting `/etc/resolv.conf` from the host machine into each container.

Bind mounts are also available for builds: you can bind mount source code from the host into the build container to test, lint, or compile a project.

## [Bind-mounting over existing data](#bind-mounting-over-existing-data)

If you bind mount file or directory into a directory in the container in which files or directories exist, the pre-existing files are obscured by the mount. This is similar to if you were to save files into `/mnt` on a Linux host, and then mounted a USB drive into `/mnt`. The contents of `/mnt` would be obscured by the contents of the USB drive until the USB drive was unmounted.

With containers, there's no straightforward way of removing a mount to reveal the obscured files again. Your best option is to recreate the container without the mount.

## [Considerations and constraints](#considerations-and-constraints)

* Bind mounts have write access to files on the host by default.

  One side effect of using bind mounts is that you can change the host filesystem via processes running in a container, including creating, modifying, or deleting important system files or directories. This capability can have security implications. For example, it may affect non-Docker processes on the host system.

  You can use the `readonly` or `ro` option to prevent the container from writing to the mount.

* Bind mounts are created to the Docker daemon host, not the client.

  If you're using a remote Docker daemon, you can't create a bind mount to access files on the client machine in a container.

  For Docker Desktop, the daemon runs inside a Linux VM, not directly on the native host. Docker Desktop has built-in mechanisms that transparently handle bind mounts, allowing you to share native host filesystem paths with containers running in the virtual machine.

* Containers with bind mounts are strongly tied to the host.

  Bind mounts rely on the host machine's filesystem having a specific directory structure available. This reliance means that containers with bind mounts may fail if run on a different host without the same directory structure.

## [Syntax](#syntax)

To create a bind mount, you can use either the `--mount` or `--volume` flag.

```console
$ docker run --mount type=bind,src=<host-path>,dst=<container-path>
$ docker run --volume <host-path>:<container-path>
```

In general, `--mount` is preferred. The main difference is that the `--mount` flag is more explicit and supports all the available options.

If you use `--volume` to bind-mount a file or directory that does not yet exist on the Docker host, Docker automatically creates the directory on the host for you. It's always created as a directory.

By default, `--mount` does not automatically create a directory if the specified mount path does not exist on the host. Instead, it produces an error:

```console
$ docker run --mount type=bind,src=/dev/noexist,dst=/mnt/foo alpine
docker: Error response from daemon: invalid mount config for type "bind": bind source path does not exist: /dev/noexist.
```

You can use the `bind-create-src` option to automatically create the source directory on the host if it doesn't exist:

```console
$ docker run --mount type=bind,src=/home/user/mydir,dst=/mnt/foo,bind-create-src alpine
```

### [Options for --mount](#options-for---mount)

The `--mount` flag consists of multiple key-value pairs, separated by commas and each consisting of a `<key>=<value>` tuple. The order of the keys isn't significant.

```console
$ docker run --mount type=bind,src=<host-path>,dst=<container-path>[,<key>=<value>...]
```

Valid options for `--mount type=bind` include:

| Option                         | Description                                                                                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`, `src`                | The location of the file or directory on the host. This can be an absolute or relative path.                                                                        |
| `destination`, `dst`, `target` | The path where the file or directory is mounted in the container. Must be an absolute path.                                                                         |
| `readonly`, `ro`               | If present, causes the bind mount to be [mounted into the container as read-only](#use-a-read-only-bind-mount).                                                     |
| `bind-propagation`             | If present, changes the [bind propagation](#configure-bind-propagation).                                                                                            |
| `bind-create-src`              | Automatically creates the source directory on the host if it doesn't exist. By default, `--mount` produces an error if the source path doesn't exist on the daemon. |

Example

```console
$ docker run --mount type=bind,src=.,dst=/project,ro,bind-propagation=rshared
```

### [Options for --volume](#options-for---volume)

The `--volume` or `-v` flag consists of three fields, separated by colon characters (`:`). The fields must be in the correct order.

```console
$ docker run -v <host-path>:<container-path>[:opts]
```

The first field is the path on the host to bind mount into the container. The second field is the path where the file or directory is mounted in the container.

The third field is optional, and is a comma-separated list of options. Valid options for `--volume` with a bind mount include:

| Option               | Description                                                                                                        |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `readonly`, `ro`     | If present, causes the bind mount to be [mounted into the container as read-only](#use-a-read-only-bind-mount).    |
| `z`, `Z`             | Configures SELinux labeling. See [Configure the SELinux label](#configure-the-selinux-label)                       |
| `rprivate` (default) | Sets bind propagation to `rprivate` for this mount. See [Configure bind propagation](#configure-bind-propagation). |
| `private`            | Sets bind propagation to `private` for this mount. See [Configure bind propagation](#configure-bind-propagation).  |
| `rshared`            | Sets bind propagation to `rshared` for this mount. See [Configure bind propagation](#configure-bind-propagation).  |
| `shared`             | Sets bind propagation to `shared` for this mount. See [Configure bind propagation](#configure-bind-propagation).   |
| `rslave`             | Sets bind propagation to `rslave` for this mount. See [Configure bind propagation](#configure-bind-propagation).   |
| `slave`              | Sets bind propagation to `slave` for this mount. See [Configure bind propagation](#configure-bind-propagation).    |

Example

```console
$ docker run -v .:/project:ro,rshared
```

## [Start a container with a bind mount](#start-a-container-with-a-bind-mount)

Consider a case where you have a directory `source` and that when you build the source code, the artifacts are saved into another directory, `source/target/`. You want the artifacts to be available to the container at `/app/`, and you want the container to get access to a new build each time you build the source on your development host. Use the following command to bind-mount the `target/` directory into your container at `/app/`. Run the command from within the `source` directory. The `$(pwd)` sub-command expands to the current working directory on Linux or macOS hosts. If you're on Windows, see also [Path conversions on Windows](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/).

The following `--mount` and `-v` examples produce the same result. You can't run them both unless you remove the `devtest` container after running the first one.

```console
$ docker run -d \
  -it \
  --name devtest \
  --mount type=bind,source="$(pwd)"/target,target=/app \
  nginx:latest
```

```console
$ docker run -d \
  -it \
  --name devtest \
  -v "$(pwd)"/target:/app \
  nginx:latest
```

Use `docker inspect devtest` to verify that the bind mount was created correctly. Look for the `Mounts` section:

```json
"Mounts": [
    {
        "Type": "bind",
        "Source": "/tmp/source/target",
        "Destination": "/app",
        "Mode": "",
        "RW": true,
        "Propagation": "rprivate"
    }
],
```

This shows that the mount is a `bind` mount, it shows the correct source and destination, it shows that the mount is read-write, and that the propagation is set to `rprivate`.

Stop and remove the container:

```console
$ docker container rm -fv devtest
```

### [Mount into a non-empty directory on the container](#mount-into-a-non-empty-directory-on-the-container)

If you bind-mount a directory into a non-empty directory on the container, the directory's existing contents are obscured by the bind mount. This can be beneficial, such as when you want to test a new version of your application without building a new image. However, it can also be surprising and this behavior differs from that of [volumes](https://docs.docker.com/engine/storage/volumes/).

This example is contrived to be extreme, but replaces the contents of the container's `/usr/` directory with the `/tmp/` directory on the host machine. In most cases, this would result in a non-functioning container.

The `--mount` and `-v` examples have the same end result.

```console
$ docker run -d \
  -it \
  --name broken-container \
  --mount type=bind,source=/tmp,target=/usr \
  nginx:latest

docker: Error response from daemon: oci runtime error: container_linux.go:262:
starting container process caused "exec: \"nginx\": executable file not found in $PATH".
```

```console
$ docker run -d \
  -it \
  --name broken-container \
  -v /tmp:/usr \
  nginx:latest

docker: Error response from daemon: oci runtime error: container_linux.go:262:
starting container process caused "exec: \"nginx\": executable file not found in $PATH".
```

The container is created but does not start. Remove it:

```console
$ docker container rm broken-container
```

## [Use a read-only bind mount](#use-a-read-only-bind-mount)

For some development applications, the container needs to write into the bind mount, so changes are propagated back to the Docker host. At other times, the container only needs read access.

This example modifies the previous one, but mounts the directory as a read-only bind mount, by adding `ro` to the (empty by default) list of options, after the mount point within the container. Where multiple options are present, separate them by commas.

The `--mount` and `-v` examples have the same result.

```console
$ docker run -d \
  -it \
  --name devtest \
  --mount type=bind,source="$(pwd)"/target,target=/app,readonly \
  nginx:latest
```

```console
$ docker run -d \
  -it \
  --name devtest \
  -v "$(pwd)"/target:/app:ro \
  nginx:latest
```

Use `docker inspect devtest` to verify that the bind mount was created correctly. Look for the `Mounts` section:

```json
"Mounts": [
    {
        "Type": "bind",
        "Source": "/tmp/source/target",
        "Destination": "/app",
        "Mode": "ro",
        "RW": false,
        "Propagation": "rprivate"
    }
],
```

Stop and remove the container:

```console
$ docker container rm -fv devtest
```

## [Recursive mounts](#recursive-mounts)

When you bind mount a path that itself contains mounts, those submounts are also included in the bind mount by default. This behavior is configurable, using the `bind-recursive` option for `--mount`. This option is only supported with the `--mount` flag, not with `-v` or `--volume`.

If the bind mount is read-only, the Docker Engine makes a best-effort attempt at making the submounts read-only as well. This is referred to as recursive read-only mounts. Recursive read-only mounts require Linux kernel version 5.12 or later. If you're running an older kernel version, submounts are automatically mounted as read-write by default. Attempting to set submounts to be read-only on a kernel version earlier than 5.12, using the `bind-recursive=readonly` option, results in an error.

Supported values for the `bind-recursive` option are:

| Value               | Description                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `enabled` (default) | Read-only mounts are made recursively read-only if kernel is v5.12 or later. Otherwise, submounts are read-write. |
| `disabled`          | Submounts are ignored (not included in the bind mount).                                                           |
| `writable`          | Submounts are read-write.                                                                                         |
| `readonly`          | Submounts are read-only. Requires kernel v5.12 or later.                                                          |

## [Configure bind propagation](#configure-bind-propagation)

Bind propagation defaults to `rprivate` for both bind mounts and volumes. It is only configurable for bind mounts, and only on Linux host machines. Bind propagation is an advanced topic and many users never need to configure it.

Bind propagation refers to whether or not mounts created within a given bind-mount can be propagated to replicas of that mount. Consider a mount point `/mnt`, which is also mounted on `/tmp`. The propagation settings control whether a mount on `/tmp/a` would also be available on `/mnt/a`. Each propagation setting has a recursive counterpoint. In the case of recursion, consider that `/tmp/a` is also mounted as `/foo`. The propagation settings control whether `/mnt/a` and/or `/tmp/a` would exist.

> Note
>
> Mount propagation doesn't work with Docker Desktop.

| Propagation setting | Description                                                                                                                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shared`            | Sub-mounts of the original mount are exposed to replica mounts, and sub-mounts of replica mounts are also propagated to the original mount.                                                                         |
| `slave`             | similar to a shared mount, but only in one direction. If the original mount exposes a sub-mount, the replica mount can see it. However, if the replica mount exposes a sub-mount, the original mount cannot see it. |
| `private`           | The mount is private. Sub-mounts within it are not exposed to replica mounts, and sub-mounts of replica mounts are not exposed to the original mount.                                                               |
| `rshared`           | The same as shared, but the propagation also extends to and from mount points nested within any of the original or replica mount points.                                                                            |
| `rslave`            | The same as slave, but the propagation also extends to and from mount points nested within any of the original or replica mount points.                                                                             |
| `rprivate`          | The default. The same as private, meaning that no mount points anywhere within the original or replica mount points propagate in either direction.                                                                  |

Before you can set bind propagation on a mount point, the host filesystem needs to already support bind propagation.

For more information about bind propagation, see the [Linux kernel documentation for shared subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt).

The following example mounts the `target/` directory into the container twice, and the second mount sets both the `ro` option and the `rslave` bind propagation option.

The `--mount` and `-v` examples have the same result.

```console
$ docker run -d \
  -it \
  --name devtest \
  --mount type=bind,source="$(pwd)"/target,target=/app \
  --mount type=bind,source="$(pwd)"/target,target=/app2,readonly,bind-propagation=rslave \
  nginx:latest
```

```console
$ docker run -d \
  -it \
  --name devtest \
  -v "$(pwd)"/target:/app \
  -v "$(pwd)"/target:/app2:ro,rslave \
  nginx:latest
```

Now if you create `/app/foo/`, `/app2/foo/` also exists.

## [Configure the SELinux label](#configure-the-selinux-label)

If you use SELinux, you can add the `z` or `Z` options to modify the SELinux label of the host file or directory being mounted into the container. This affects the file or directory on the host machine itself and can have consequences outside of the scope of Docker.

* The `z` option indicates that the bind mount content is shared among multiple containers.
* The `Z` option indicates that the bind mount content is private and unshared.

Use extreme caution with these options. Bind-mounting a system directory such as `/home` or `/usr` with the `Z` option renders your host machine inoperable and you may need to relabel the host machine files by hand.

> Important
>
> When using bind mounts with services, SELinux labels (`:Z` and `:z`), as well as `:ro` are ignored. See [moby/moby #32579](https://github.com/moby/moby/issues/32579) for details.

This example sets the `z` option to specify that multiple containers can share the bind mount's contents:

It is not possible to modify the SELinux label using the `--mount` flag.

```console
$ docker run -d \
  -it \
  --name devtest \
  -v "$(pwd)"/target:/app:z \
  nginx:latest
```

## [Use a bind mount with Docker Compose](#use-a-bind-mount-with-docker-compose)

A single Docker Compose service with a bind mount looks like this:

```yaml
services:
  frontend:
    image: node:lts
    volumes:
      - type: bind
        source: ./static
        target: /opt/app/static
volumes:
  myapp:
```

For more information about using volumes of the `bind` type with Compose, see [Compose reference on the volumes top-level element](https://docs.docker.com/reference/compose-file/volumes/). and [Compose reference on the volume attribute](https://docs.docker.com/reference/compose-file/services/#volumes).

## [Next steps](#next-steps)

* Learn about [volumes](https://docs.docker.com/engine/storage/volumes/).
* Learn about [tmpfs mounts](https://docs.docker.com/engine/storage/tmpfs/).
* Learn about [storage drivers](/engine/storage/drivers/).

----
url: https://docs.docker.com/engine/security/antivirus/
----

# Antivirus software and Docker

***

***

When antivirus software scans files used by Docker, these files may be locked in a way that causes Docker commands to hang.

One way to reduce these problems is to add the Docker data directory (`/var/lib/docker` on Linux, `%ProgramData%\docker` on Windows Server, or `$HOME/Library/Containers/com.docker.docker/` on Mac) to the antivirus's exclusion list. However, this comes with the trade-off that viruses or malware in Docker images, writable layers of containers, or volumes are not detected. If you do choose to exclude Docker's data directory from background virus scanning, you may want to schedule a recurring task that stops Docker, scans the data directory, and restarts Docker.

----
url: https://docs.docker.com/engine/security/protect-access/
----

# Protect the Docker daemon socket

***

Table of contents

***

By default, Docker runs through a non-networked UNIX socket. It can also optionally communicate using SSH or a TLS (HTTPS) socket.

## [Use SSH to protect the Docker daemon socket](#use-ssh-to-protect-the-docker-daemon-socket)

> Note
>
> The given `USERNAME` must have permissions to access the docker socket on the remote machine. Refer to [manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) to learn how to give a non-root user access to the docker socket.

The following example creates a [`docker context`](https://docs.docker.com/engine/manage-resources/contexts/) to connect with a remote `dockerd` daemon on `host1.example.com` using SSH, and as the `docker-user` user on the remote machine:

```console
$ docker context create \
    --docker host=ssh://docker-user@host1.example.com \
    --description="Remote engine" \
    my-remote-engine

my-remote-engine
Successfully created context "my-remote-engine"
```

After creating the context, use `docker context use` to switch the `docker` CLI to use it, and to connect to the remote engine:

```console
$ docker context use my-remote-engine
my-remote-engine
Current context is now "my-remote-engine"

$ docker info
<prints output of the remote engine>
```

Use the `default` context to switch back to the default (local) daemon:

```console
$ docker context use default
default
Current context is now "default"
```

Alternatively, use the `DOCKER_HOST` environment variable to temporarily switch the `docker` CLI to connect to the remote host using SSH. This does not require creating a context, and can be useful to create an ad-hoc connection with a different engine:

```console
$ export DOCKER_HOST=ssh://docker-user@host1.example.com
$ docker info
<prints output of the remote engine>
```

### [SSH Tips](#ssh-tips)

For the best user experience with SSH, configure `~/.ssh/config` as follows to allow reusing a SSH connection for multiple invocations of the `docker` CLI:

```text
ControlMaster     auto
ControlPath       ~/.ssh/control-%C
ControlPersist    yes
```

## [Use TLS (HTTPS) to protect the Docker daemon socket](#use-tls-https-to-protect-the-docker-daemon-socket)

If you need Docker to be reachable through HTTP rather than SSH in a safe manner, you can enable TLS (HTTPS) by specifying the `tlsverify` flag and pointing Docker's `tlscacert` flag to a trusted CA certificate.

In the daemon mode, it only allows connections from clients authenticated by a certificate signed by that CA. In the client mode, it only connects to servers with a certificate signed by that CA.

> Important
>
> Using TLS and managing a CA is an advanced topic. Familiarize yourself with OpenSSL, x509, and TLS before using it in production.

### [Create a CA, server and client keys with OpenSSL](#create-a-ca-server-and-client-keys-with-openssl)

> Note
>
> Replace all instances of `$HOST` in the following example with the DNS name of your Docker daemon's host.

First, on the Docker daemon's host machine, generate CA private and public keys:

```console
$ openssl genrsa -aes256 -out ca-key.pem 4096
Generating RSA private key, 4096 bit long modulus
..............................................................................++
........++
e is 65537 (0x10001)
Enter pass phrase for ca-key.pem:
Verifying - Enter pass phrase for ca-key.pem:

$ openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -out ca.pem
Enter pass phrase for ca-key.pem:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:Queensland
Locality Name (eg, city) []:Brisbane
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Docker Inc
Organizational Unit Name (eg, section) []:Sales
Common Name (e.g. server FQDN or YOUR name) []:$HOST
Email Address []:Sven@home.org.au
```

Now that you have a CA, you can create a server key and certificate signing request (CSR). Make sure that "Common Name" matches the hostname you use to connect to Docker:

> Note
>
> Replace all instances of `$HOST` in the following example with the DNS name of your Docker daemon's host.

```console
$ openssl genrsa -out server-key.pem 4096
Generating RSA private key, 4096 bit long modulus
.....................................................................++
.................................................................................................++
e is 65537 (0x10001)

$ openssl req -subj "/CN=$HOST" -sha256 -new -key server-key.pem -out server.csr
```

Next, we're going to sign the public key with our CA:

Since TLS connections can be made through IP address as well as DNS name, the IP addresses need to be specified when creating the certificate. For example, to allow connections using `10.10.10.20` and `127.0.0.1`:

```console
$ echo subjectAltName = DNS:$HOST,IP:10.10.10.20,IP:127.0.0.1 >> extfile.cnf
```

Set the Docker daemon key's extended usage attributes to be used only for server authentication:

```console
$ echo extendedKeyUsage = serverAuth >> extfile.cnf
```

Now, generate the signed certificate:

```console
$ openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out server-cert.pem -extfile extfile.cnf
Signature ok
subject=/CN=your.host.com
Getting CA Private Key
Enter pass phrase for ca-key.pem:
```

[Authorization plugins](/engine/extend/plugins_authorization/) offer more fine-grained control to supplement authentication from mutual TLS. In addition to other information described in the above document, authorization plugins running on a Docker daemon receive the certificate information for connecting Docker clients.

For client authentication, create a client key and certificate signing request:

> Note
>
> For simplicity of the next couple of steps, you may perform this step on the Docker daemon's host machine as well.

```console
$ openssl genrsa -out key.pem 4096
Generating RSA private key, 4096 bit long modulus
.........................................................++
................++
e is 65537 (0x10001)

$ openssl req -subj '/CN=client' -new -key key.pem -out client.csr
```

To make the key suitable for client authentication, create a new extensions config file:

```console
$ echo extendedKeyUsage = clientAuth > extfile-client.cnf
```

Now, generate the signed certificate:

```console
$ openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out cert.pem -extfile extfile-client.cnf
Signature ok
subject=/CN=client
Getting CA Private Key
Enter pass phrase for ca-key.pem:
```

After generating `cert.pem` and `server-cert.pem` you can safely remove the two certificate signing requests and extensions config files:

```console
$ rm -v client.csr server.csr extfile.cnf extfile-client.cnf
```

With a default `umask` of 022, your secret keys are *world-readable* and writable for you and your group.

To protect your keys from accidental damage, remove their write permissions. To make them only readable by you, change file modes as follows:

```console
$ chmod -v 0400 ca-key.pem key.pem server-key.pem
```

Certificates can be world-readable, but you might want to remove write access to prevent accidental damage:

```console
$ chmod -v 0444 ca.pem server-cert.pem cert.pem
```

Now you can make the Docker daemon only accept connections from clients providing a certificate trusted by your CA:

```console
$ dockerd \
    --tlsverify \
    --tlscacert=ca.pem \
    --tlscert=server-cert.pem \
    --tlskey=server-key.pem \
    -H=0.0.0.0:2376
```

To connect to Docker and validate its certificate, provide your client keys, certificates and trusted CA:

> Tip
>
> This step should be run on your Docker client machine. As such, you need to copy your CA certificate, your server certificate, and your client certificate to that machine.

> Note
>
> Replace all instances of `$HOST` in the following example with the DNS name of your Docker daemon's host.

```console
$ docker --tlsverify \
    --tlscacert=ca.pem \
    --tlscert=cert.pem \
    --tlskey=key.pem \
    -H=$HOST:2376 version
```

> Note
>
> Docker over TLS should run on TCP port 2376.

> Warning
>
> As shown in the example above, you don't need to run the `docker` client with `sudo` or the `docker` group when you use certificate authentication. That means anyone with the keys can give any instructions to your Docker daemon, giving them root access to the machine hosting the daemon. Guard these keys as you would a root password!

### [Secure by default](#secure-by-default)

If you want to secure your Docker client connections by default, you can move the files to the `.docker` directory in your home directory --- and set the `DOCKER_HOST` and `DOCKER_TLS_VERIFY` variables as well (instead of passing `-H=tcp://$HOST:2376` and `--tlsverify` on every call).

```console
$ mkdir -pv ~/.docker
$ cp -v {ca,cert,key}.pem ~/.docker

$ export DOCKER_HOST=tcp://$HOST:2376 DOCKER_TLS_VERIFY=1
```

Docker now connects securely by default:

```
$ docker ps
```

### [Other modes](#other-modes)

If you don't want to have complete two-way authentication, you can run Docker in various other modes by mixing the flags.

#### [Daemon modes](#daemon-modes)

* `tlsverify`, `tlscacert`, `tlscert`, `tlskey` set: Authenticate clients
* `tls`, `tlscert`, `tlskey`: Do not authenticate clients

#### [Client modes](#client-modes)

* `tls`: Authenticate server based on public/default CA pool
* `tlsverify`, `tlscacert`: Authenticate server based on given CA
* `tls`, `tlscert`, `tlskey`: Authenticate with client certificate, do not authenticate server based on given CA
* `tlsverify`, `tlscacert`, `tlscert`, `tlskey`: Authenticate with client certificate and authenticate server based on given CA

If found, the client sends its client certificate, so you just need to drop your keys into `~/.docker/{ca,cert,key}.pem`. Alternatively, if you want to store your keys in another location, you can specify that location using the environment variable `DOCKER_CERT_PATH`.

```console
$ export DOCKER_CERT_PATH=~/.docker/zone1/
$ docker --tlsverify ps
```

#### [Connecting to the secure Docker port using `curl`](#connecting-to-the-secure-docker-port-using-curl)

To use `curl` to make test API requests, you need to use three extra command line flags:

```console
$ curl https://$HOST:2376/images/json \
  --cert ~/.docker/cert.pem \
  --key ~/.docker/key.pem \
  --cacert ~/.docker/ca.pem
```

## [Related information](#related-information)

* [Using certificates for repository client verification](https://docs.docker.com/engine/security/certificates/)
* [Use trusted images](https://docs.docker.com/engine/security/trust/)

----
url: https://docs.docker.com/reference/cli/docker/context/inspect/
----

# docker context inspect

***

| Description | Display detailed information on one or more contexts      |
| ----------- | --------------------------------------------------------- |
| Usage       | `docker context inspect [OPTIONS] [CONTEXT] [CONTEXT...]` |

## [Description](#description)

Inspects one or more contexts.

## [Options](#options)

| Option         | Default | Description                                                                                                                                                                                                                             |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --format` |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |

## [Examples](#examples)

### [Inspect a context by name](#inspect-a-context-by-name)

```console
$ docker context inspect "local+aks"

[
  {
    "Name": "local+aks",
    "Metadata": {
      "Description": "Local Docker Engine",
      "StackOrchestrator": "swarm"
    },
    "Endpoints": {
      "docker": {
        "Host": "npipe:////./pipe/docker_engine",
        "SkipTLSVerify": false
      }
    },
    "TLSMaterial": {},
    "Storage": {
      "MetadataPath": "C:\\Users\\simon\\.docker\\contexts\\meta\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee",
      "TLSPath": "C:\\Users\\simon\\.docker\\contexts\\tls\\cb6d08c0a1bfa5fe6f012e61a442788c00bed93f509141daff05f620fc54ddee"
    }
  }
]
```

----
url: https://docs.docker.com/guides/lab-attestation-basics/
----

[Lab: Container Image Attestations](https://docs.docker.com/guides/lab-attestation-basics/)

Hands-on lab: Add supply chain metadata to a container image. Generate SBOMs and SLSA provenance with BuildKit, sign images with Cosign, and attach OpenVEX statements to declare vulnerability exploitability status.

Labs

45 minutes

Resources:

* [Build attestations](/build/metadata/attestations/)
* [SBOM attestations](/build/metadata/attestations/sbom/)
* [Provenance attestations](/build/metadata/attestations/slsa-provenance/)
* [Labspace repository](https://github.com/dockersamples/labspace-attestation-basics)

[« Back to all guides](/guides/)

# Lab: Container Image Attestations

***

Table of contents

***

Prove where your container images came from and that they haven't been tampered with. This lab walks through generating SBOMs and SLSA build provenance with BuildKit, signing images with Cosign, and writing VEX statements to declare which CVEs affect your image — the techniques used to meet supply chain security requirements like NIST SSDF and EO 14028.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-attestation-basics up -d
   ```

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

By the end of this Labspace, you will have completed the following:

* Generate and inspect an SPDX SBOM attached to a container image with `--sbom=true`
* Generate SLSA build provenance with `--provenance=mode=max` and understand how multi-stage builds are fully recorded
* Install Cosign and use key-based signing to sign and verify a container image
* Write an OpenVEX statement to declare CVE exploitability status and attach it as a signed attestation
* Understand how SBOMs, provenance, signatures, and VEX complement each other in a complete supply chain story

## [Modules](#modules)

| # | Module                            | Description                                                                          |
| - | --------------------------------- | ------------------------------------------------------------------------------------ |
| 1 | Introduction                      | Overview of supply chain attestations and the sample Go app                          |
| 2 | Software Bill of Materials (SBOM) | Build with `--sbom=true`, inspect SPDX contents, and understand scanner integration  |
| 3 | Build Provenance                  | Generate SLSA provenance and explore how multi-stage builds are recorded             |
| 4 | Signing Images with Cosign        | Generate a key pair, sign the image, verify the signature, and learn keyless signing |
| 5 | VEX Statements                    | Scan for CVEs, write an OpenVEX document, and attach it as a signed attestation      |
| 6 | Bringing It All Together          | Run the complete build-sign-attest workflow and see the full supply chain picture    |
| 7 | Recap                             | Summary of skills and next steps for policy enforcement and higher SLSA levels       |

----
url: https://docs.docker.com/guides/dotnet/configure-ci-cd/
----

# Configure CI/CD for your .NET application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a .NET application](https://docs.docker.com/guides/dotnet/containerize/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

   ```console
   $ git remote set-url origin https://github.com/your-username/your-repository.git
   ```

7. In your local repository on your machine, run the following command to rename the branch to main.

   ```console
   $ git branch -M main
   ```

8. Run the following commands to stage, commit, and then push your local repository to GitHub.

   ```console
   $ git add -A
   $ git commit -m "my first commit"
   $ git push -u origin main
   ```

## [Step two: Set up the workflow](#step-two-set-up-the-workflow)

Set up your GitHub Actions workflow for building, testing, and pushing the image to Docker Hub.

1. Go to your repository on GitHub and then select the **Actions** tab.

2. Select **set up a workflow yourself**.

   This takes you to a page for creating a new GitHub actions workflow file in your repository, under `.github/workflows/main.yml` by default.

3. In the editor window, copy and paste the following YAML configuration.

   ```yaml
   name: ci

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Login to Docker Hub
           uses: docker/login-action@v4
           with:
             username: ${{ vars.DOCKER_USERNAME }}
             password: ${{ secrets.DOCKERHUB_TOKEN }}

         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v4

         - name: Build and test
           uses: docker/build-push-action@v7
           with:
             target: build
             load: true

         - name: Build and push
           uses: docker/build-push-action@v7
           with:
             platforms: linux/amd64,linux/arm64
             push: true
             target: final
             tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
   ```

[Test your .NET deployment »](https://docs.docker.com/guides/dotnet/deploy/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/use/
----

# docker buildx use

***

| Description | Set the current builder instance   |
| ----------- | ---------------------------------- |
| Usage       | `docker buildx use [OPTIONS] NAME` |

## [Description](#description)

Switches the current builder instance. Build commands invoked after this command will run on a specified builder. Alternatively, a context name can be used to switch to the default builder of that context.

## [Options](#options)

| Option      | Default | Description                                |
| ----------- | ------- | ------------------------------------------ |
| `--default` |         | Set builder as default for current context |
| `--global`  |         | Builder persists context changes           |

## [Examples](#examples)

### [Override the configured builder instance (--builder)](#builder)

Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

----
url: https://docs.docker.com/engine/release-notes/27/
----

# Docker Engine version 27 release notes

***

Table of contents

***

This page describes the latest changes, additions, known issues, and fixes for Docker Engine version 27.

For more information about:

* Deprecated and removed features, see [Deprecated Engine Features](https://docs.docker.com/engine/deprecated/).
* Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history/).

## [27.5](#275)

Release notes for Docker Engine version 27.5 releases.

### [27.5.1](#2751)

*2025-01-22*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.5.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.5.1)
* [moby/moby, 27.5.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.5.1)

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* Fix an issue that could persistently prevent daemon startup after failure to initialize the default bridge. [moby/moby#49307](https://github.com/moby/moby/pull/49307)
* Add a `DOCKER_IGNORE_BR_NETFILTER_ERROR` environment variable. Setting it to `1` allows running on hosts that cannot load `br_netfilter`. Some things won't work, including disabling inter-container communication in a bridge network. With the userland proxy disabled, it won't be possible to access one container's published ports from another container on the same network. [moby/moby#49306](https://github.com/moby/moby/pull/49306)

#### [Packaging updates](#packaging-updates)

* Update Go runtime to 1.22.11 (fix CVE-2024-45341, CVE-2024-45336). [moby/moby#49312](https://github.com/moby/moby/pull/49312), [docker/docker-ce-packaging#1147](https://github.com/docker/docker-ce-packaging/pull/1147), [docker/cli#5762](https://github.com/docker/cli/pull/5762)
* Update RootlessKit to v2.3.2 to support `passt` >= 2024\_10\_30.ee7d0b6. [moby/moby#49304](https://github.com/moby/moby/pull/49304)
* Update Buildx to [v0.20.0](https://github.com/docker/buildx/releases/tag/v0.20.0). [docker/docker-ce-packaging#1149](https://github.com/docker/docker-ce-packaging/pull/1149)

### [27.5.0](#2750)

*2025-01-13*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.5.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.5.0)
* [moby/moby, 27.5.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.5.0)

#### [Bugfixes and enhancements](#bugfixes-and-enhancements)

* containerd image store: Fix passing a build context via tarball to the `/build` endpoint. [moby/moby#49194](https://github.com/moby/moby/pull/49194)
* Builder garbage collection policies without a `keepStorage` value now inherit the `defaultKeepStorage` limit as intended. [moby/moby#49137](https://github.com/moby/moby/pull/49137)
* Preserve network labels during daemon startup. [moby/moby#49200](https://github.com/moby/moby/pull/49200)
* Fix a potential race condition error when deleting a container. [moby/moby#49239](https://github.com/moby/moby/pull/49239)

#### [Go SDK](#go-sdk)

* `pkg/sysinfo`: deprecate `NumCPU`. This utility has the same behavior as `runtime.NumCPU`. [moby/moby#49247](https://github.com/moby/moby/pull/49247)
* `pkg/fileutils`: deprecate `GetTotalUsedFds`: this function is only used internally and will be removed in the next release. [moby/moby#49209](https://github.com/moby/moby/pull/49209)
* `pkg/ioutils`: deprecate `BytesPipe`, `NewBytesPipe`, `ErrClosed`, `WriteCounter`, `NewWriteCounter`, `NewReaderErrWrapper`, `NopFlusher`, `NopWriter`, `NopWriteCloser`. They were only used internally and will be removed in the next release. [moby/moby#49246](https://github.com/moby/moby/pull/49246), [moby/moby#49255](https://github.com/moby/moby/pull/49255)
* `pkg/reexec`: This package is deprecated and moved to a separate module. Use `github.com/moby/sys/reexec` instead. [moby/moby#49135](https://github.com/moby/moby/pull/49135)

#### [Packaging updates](#packaging-updates-1)

* Update containerd to [v1.7.25](https://github.com/containerd/containerd/releases/tag/v1.7.25) [moby/moby#49253](https://github.com/moby/moby/pull/49253)
* Update `runc` to [v1.2.4](https://github.com/opencontainers/runc/releases/tag/v1.2.4) [moby/moby#49243](https://github.com/moby/moby/pull/49243)
* Update BuildKit to [v0.18.2](https://github.com/moby/buildkit/releases/tag/v0.18.2) [moby/moby#48949](https://github.com/moby/moby/pull/48949)
* Update Compose to [v2.32.2](https://github.com/docker/compose/releases/tag/v2.32.2) [docker/docker-ce-packaging#1140](https://github.com/docker/docker-ce-packaging/pull/1140)

## [27.4](#274)

Release notes for Docker Engine version 27.4 releases.

### [27.4.1](#2741)

*2024-12-18*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.4.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.4.1)
* [moby/moby, 27.4.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.4.1)

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

* Fix excessive memory allocations when OTel is not configured. [moby/moby#49079](https://github.com/moby/moby/pull/49079)
* The `docker info` command and the corresponding `GET /info` API endpoint no longer include warnings when `bridge-nf-call-iptables` or `bridge-nf-call-ip6tables` are disabled at the daemon is started. The `br_netfilter` kernel module is now attempted to be loaded when needed, which made those warnings inaccurate. [moby/moby#49090](https://github.com/moby/moby/pull/49090)
* Attempt to load kernel modules, including `ip6_tables` and `br_netfilter` when required, using a method that is likely to succeed inside a Docker-in-Docker container. [moby/moby#49043](https://github.com/moby/moby/pull/49043)
* Fix a bug that could result in an iptables `DOCKER FILTER` chain not being cleaned up on failure. [moby/moby#49110](https://github.com/moby/moby/pull/49110)

#### [Packaging updates](#packaging-updates-2)

* Update Compose to [v2.32.1](https://github.com/docker/compose/releases/tag/v2.32.1). [docker/docker-ce-packaging#1130](https://github.com/docker/docker-ce-packaging/pull/1130)
* Update Buildx to [v0.19.3](https://github.com/docker/buildx/releases/tag/v0.19.3). [docker/docker-ce-packaging#1132](https://github.com/docker/docker-ce-packaging/pull/1132)
* Update runc (static binaries only) to [v1.2.3](https://github.com/opencontainers/runc/releases/tag/v1.2.3) [moby/moby#49085](https://github.com/moby/moby/pull/49085)

### [27.4.0](#2740)

*2024-12-09*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.4.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.4.0)
* [moby/moby, 27.4.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.4.0)

#### [API](#api)

* `GET /images/json` with the `manifests` option enabled now preserves the original order in which manifests appeared in the manifest-index. [moby/moby#48712](https://github.com/moby/moby/pull/48712)

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

* When reading logs with the `jsonfile` or `local` log drivers, any errors while trying to read or parse underlying log files will cause the rest of the file to be skipped and move to the next log file (if one exists) rather than returning an error to the client and closing the stream. The errors are viewable in the Docker Daemon logs and exported to traces when tracing is configured. [moby/moby#48842](https://github.com/moby/moby/pull/48842)
* When reading log files, compressed log files are now only decompressed when needed rather than decompressing all files before starting the log stream. [moby/moby#48842](https://github.com/moby/moby/pull/48842)
* Fix an issue that meant published ports from one container on a bridge network were not accessible from another container on the same network with `userland-proxy` disabled, if the kernel's `br_netfilter` module was not loaded and enabled. The daemon will now attempt to load the module and enable `bridge-nf-call-iptables` or `bridge-nf-call-ip6tables` when creating a network with the userland proxy disabled. [moby/moby#48685](https://github.com/moby/moby/pull/48685)
* Fix loading of `bridge` and `br_netfilter` kernel modules. [moby/moby#48966](https://github.com/moby/moby/pull/48966)
* containerd image store: Fix Docker daemon failing to fully start with a "context deadline exceeded error" with containerd snapshotter and many builds/images. [moby/moby#48954](https://github.com/moby/moby/pull/48954)
* containerd image store: Fix partially pulled images not being garbage-collected. [moby#48910](https://github.com/moby/moby/pull/48910), [moby/moby#48957](https://github.com/moby/moby/pull/48957)
* containerd image store: Fix `docker image inspect` outputting duplicate references in `RepoDigests`. [moby/moby#48785](https://github.com/moby/moby/pull/48785)
* containerd image store: Fix not being able to connect to some insecure registries in cases where the HTTPS request failed due to a non-TLS related error. [moby/moby#48758](https://github.com/moby/moby/pull/48758)
* containerd image store: Remove a confusing warning log when tagging a non-dangling image. [moby/moby#49010](https://github.com/moby/moby/pull/49010)
* containerd image store: Do not underline names in `docker image ls --tree`. [docker/cli#5519](https://github.com/docker/cli/pull/5519)
* containerd image store: Change name of `USED` column in `docker image ls --tree` to `IN USE`. [docker/cli#5518](https://github.com/docker/cli/pull/5518)
* `dockerd-rootless-setuptool.sh install --force` now ignores RootlessKit errors [moby/moby#48695](https://github.com/moby/moby/pull/48695)
* Disable IPv6 Duplicate Address Detection (DAD) for addresses assigned to the bridges belonging to bridge networks. [moby/moby#48684](https://github.com/moby/moby/pull/48684)
* Remove BuildKit init timeout. [moby/moby#48963](https://github.com/moby/moby/pull/48963)
* Ignore "dataset does not exist" error when removing dataset on ZFS. [moby/moby#48968](https://github.com/moby/moby/pull/48968)
* Client: Prevent idle connections leaking FDs. [moby/moby#48764](https://github.com/moby/moby/pull/48764)
* Fix anonymous volumes being created through the `--mount` option not being marked as anonymous. [moby/moby#48755](https://github.com/moby/moby/pull/48755)
* After a daemon restart with live-restore, ensure an iptables jump to the `DOCKER-USER` chain is placed before other rules. [moby/moby#48714](https://github.com/moby/moby/pull/48714)
* Fix a possible memory leak caused by OTel meters. [moby/moby#48693](https://github.com/moby/moby/pull/48693)
* Create distinct build history db for each image store. [moby/moby#48688](https://github.com/moby/moby/pull/48688)
* Fix an issue that caused excessive memory usage when DNS resolution was made in a tight loop. [moby/moby#48840](https://github.com/moby/moby/pull/48840)
* Fix a bug preventing image pulls from being cancelled during `docker run`. [docker/cli#5654](https://github.com/docker/cli/pull/5654)
* The `docker login` and `docker logout` command no longer update the configuration file if the credentials didn't change. [docker/cli#5569](https://github.com/docker/cli/pull/5569)
* Optimize `docker stats` to reduce flickering issues. [docker/cli#5588](https://github.com/docker/cli/pull/5588), [docker/cli#5635](https://github.com/docker/cli/pull/5635)
* Fix inaccessible plugins paths preventing plugins from being detected. [docker/cli#5652](https://github.com/docker/cli/pull/5652)
* Add support for `events --filter` in cobra generated shell completions. [docker/cli#5614](https://github.com/docker/cli/pull/5614)
* Fix bash completion for `events --filter daemon=`. [docker/cli#5563](https://github.com/docker/cli/pull/5563)
* Improve shell completion of containers for `docker rm`. [docker/cli#5540](https://github.com/docker/cli/pull/5540)
* Add shell completion for `--platform` flags. [docker/cli#5540](https://github.com/docker/cli/pull/5540)
* rootless: Make `/etc/cdi` and `/var/run/cdi` accessible by the Container Device Interface (CDI) integration. [moby/moby#49027](https://github.com/moby/moby/pull/49027)

#### [Removed](#removed)

* Deprecate `Daemon.Exists()` and `Daemon.IsPaused()`. These functions are no longer used and will be removed in the next release. [moby/moby#48719](https://github.com/moby/moby/pull/48719)
* Deprecate `container.ErrNameReserved` and `container.ErrNameNotReserved`. [moby/moby#48697](https://github.com/moby/moby/pull/48697)
* Deprecate `pkg/platform` - this package is only used internally, and will be removed in the next release. [moby/moby#48863](https://github.com/moby/moby/pull/48863)
* Deprecate `RepositoryInfo.Class`. This field is no longer used, and will be removed in the next release. [moby/moby#49013](https://github.com/moby/moby/pull/49013)
* Go SDK: Fix deprecation of `cli/command.ConfigureAuth()`, which was deprecated since v27.2.1. [docker/cli#5552](https://github.com/docker/cli/pull/5552)
* Go SDK: Deprecate `cli.Errors` type in favour of Go's `errors.Join` [docker/cli#5548](https://github.com/docker/cli/pull/5548)

#### [Packaging updates](#packaging-updates-3)

* Update Go runtime to 1.22.10. [moby/moby#49026](https://github.com/moby/moby/pull/49026), [docker/cli#5669](https://github.com/docker/cli/pull/5669), [docker/docker-ce-packaging#1120](https://github.com/docker/docker-ce-packaging/pull/1120).
* Update Compose to [v2.31.0](https://github.com/docker/compose/releases/tag/v2.31.0). [docker/docker-ce-packaging#1100](https://github.com/docker/docker-ce-packaging/pull/1117)
* Update BuildKit to [v0.17.3](https://github.com/moby/buildkit/releases/tag/v0.17.3). [moby/moby#49024](https://github.com/moby/moby/pull/49024)
* Update Buildx to [v0.19.1](https://github.com/docker/buildx/releases/tag/v0.19.1). [docker/docker-ce-packaging#1115](https://github.com/docker/docker-ce-packaging/pull/1115)
* Update containerd to [v1.7.24](https://github.com/containerd/containerd/releases/tag/v1.7.24). [moby/moby#48934](https://github.com/moby/moby/pull/48934)
* Update containerd (static binaries only) to [v1.7.24](https://github.com/containerd/containerd/releases/tag/v1.7.24). [moby/moby#48919](https://github.com/moby/moby/pull/48919)
* Update runc to [v1.2.2](https://github.com/opencontainers/runc/releases/tag/v1.2.2). [moby/moby#48919](https://github.com/moby/moby/pull/48919)

## [27.3](#273)

Release notes for Docker Engine version 27.3 releases.

### [27.3.1](#2731)

*2024-09-20*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.3.1 milestone](https://github.com/docker/cli/issues?q=sort%3Aupdated-desc+is%3Aclosed+milestone%3A27.3.1)
* [moby/moby, 27.3.1 milestone](https://github.com/moby/moby/issues?q=sort%3Aupdated-desc+is%3Aclosed+milestone%3A27.3.1)

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-3)

* CLI: Fix issue with command execution metrics not being exported correctly. [docker/cli#5457](https://github.com/docker/cli/pull/5457)

#### [Packaging updates](#packaging-updates-4)

* Update Compose to [v2.29.7](https://github.com/docker/compose/releases/tag/v2.29.7)

### [27.3.0](#2730)

*2024-09-19*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.3.0 milestone](https://github.com/docker/cli/issues?q=sort%3Aupdated-desc+is%3Aclosed+milestone%3A27.3.0)
* [moby/moby, 27.3.0 milestone](https://github.com/moby/moby/issues?q=sort%3Aupdated-desc+is%3Aclosed+milestone%3A27.3.0)

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-4)

* containerd image store: Fix `docker image prune -a` untagging images used by containers started from images referenced by a digested reference. [moby/moby#48488](https://github.com/moby/moby/pull/48488)
* Add a `--feature` flag to the daemon options. [moby/moby#48487](https://github.com/moby/moby/pull/48487)
* Updated the handling of the `--gpus=0` flag to be consistent with the NVIDIA Container Runtime. [moby/moby#48483](https://github.com/moby/moby/pull/48483)
* Support WSL2 mirrored-mode networking's use of interface `loopback0` for packets from the Windows host. [moby/moby#48514](https://github.com/moby/moby/pull/48514)
* Fix an issue that prevented communication between containers on an IPv4 bridge network when running with `--iptables=false`, `--ip6tables=true` (the default), a firewall with a DROP rule for forwarded packets on hosts where the `br_netfilter` kernel module was not normally loaded. [moby/moby#48511](https://github.com/moby/moby/pull/48511)
* CLI: Fix issue where `docker volume update` command would cause the CLI to panic if no argument/volume was passed. [docker/cli#5426](https://github.com/docker/cli/pull/5426)
* CLI: Properly report metrics when run in WSL environment on Windows. [docker/cli#5432](https://github.com/docker/cli/pull/5432)

#### [Packaging updates](#packaging-updates-5)

* Update containerd (static binaries only) to [v1.7.22](https://github.com/containerd/containerd/releases/tag/v1.7.22) [moby/moby#48468](https://github.com/moby/moby/pull/48468)
* Updated Buildkit to [v0.16.0](https://github.com/moby/buildkit/releases/tag/v0.16.0)
* Update Compose to [v2.29.6](https://github.com/docker/compose/releases/tag/v2.29.6)
* Update Buildx to [v0.17.1](https://github.com/docker/buildx/releases/tag/v0.17.1)

## [27.2](#272)

Release notes for Docker Engine version 27.2 releases.

### [27.2.1](#2721)

*2024-09-09*

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-5)

* containerd image store: Fix non-container images being hidden in the `docker image ls` output. [moby/moby#48402](https://github.com/moby/moby/pull/48402)
* containerd image store: Improve `docker pull` error message when the image platform doesn't match. [moby/moby#48415](https://github.com/moby/moby/pull/48415)
* CLI: Fix issue causing `docker login` to not remove repository names from passed in registry addresses, resulting in credentials being stored under the wrong key. [docker/cli#5385](https://github.com/docker/cli/pull/5385)
* CLI: Fix issue that will sometimes cause the browser-login flow to fail if the CLI process is suspended and then resumed while waiting for the user to authenticate. [docker/cli#5376](https://github.com/docker/cli/pull/5376)
* CLI: `docker login` now returns an error instead of hanging if called non-interactively with `--password` or `--password-stdin` but without `--user`. [docker/cli#5402](https://github.com/docker/cli/pull/5402)

#### [Packaging updates](#packaging-updates-6)

* Update runc to v1.1.14, which contains a fix for [CVE-2024-45310](https://github.com/opencontainers/runc/security/advisories/GHSA-jfvp-7x6p-h2pv). [moby/moby#48426](https://github.com/moby/moby/pull/48426)
* Update Go runtime to 1.22.7. [moby/moby#48433](https://github.com/moby/moby/pull/48433), [docker/cli#5411](https://github.com/docker/cli/pull/5411), [docker/docker-ce-packaging#1068](https://github.com/docker/docker-ce-packaging/pull/1068)

### [27.2.0](#2720)

*2024-08-27*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.2.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.2.0)
* [moby/moby, 27.2.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.2.0)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v27.2.0/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v27.2.0/docs/api/version-history.md).

#### [New](#new)

The new features in this release are:

* [Device code login](#device-code-login)
* [Multi-platform support for `docker image ls`](#multi-platform-support-for-docker-image-ls)

##### [Device code login](#device-code-login)

This release adds support for using device code login when authenticating to Docker Hub.

You can still use the old method of logging in with a username and password or access token, but device code login is more secure and doesn't require you to enter your password in the CLI.

Device code login

To use the old method, use `docker login -u <username>`.

##### [Multi-platform support for `docker image ls`](#multi-platform-support-for-docker-image-ls)

**Experimental**

This is experimental and may change at any time without any backward compatibility.

With the containerd image store enabled, the `docker image ls` command (or `docker images` shorthand) now supports a `--tree` flag that now shows if an image is a multi-platform image.

#### [API](#api-1)

* `GET /images/json` response now includes `Manifests` field, which contains information about the sub-manifests included in the image index. This includes things like platform-specific manifests and build attestations.

  The new field will only be populated if the request also sets the `manifests` query parameter to `true`.

  **Experimental**

  This is experimental and may change at any time without any backward compatibility.

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-6)

* CLI: Fix issue with remote contexts over SSH where the CLI would allocate a pseudo-TTY when connecting to the remote host, which causes issues in rare situations. [docker/cli#5351](https://github.com/docker/cli/pull/5351)
* Fix an issue that prevented network creation with a `--ip-range` ending on a 64-bit boundary. [moby/moby#48326](https://github.com/moby/moby/pull/48326)
* CLI: IPv6 addresses shown by `docker ps` in port bindings are now bracketed. [docker/cli#5365](https://github.com/docker/cli/pull/5365)
* containerd image store: Fix early error exit from `docker load` in cases where unpacking the image would fail. [moby/moby#48376](https://github.com/moby/moby/pull/48376)
* containerd image store: Fix the previous image not being persisted as dangling after `docker pull`. [moby/moby#48380](https://github.com/moby/moby/pull/48380)

#### [Packaging updates](#packaging-updates-7)

* Update BuildKit to [v0.15.2](https://github.com/moby/buildkit/releases/tag/v0.15.2). [moby/moby#48341](https://github.com/moby/moby/pull/48341)
* Update Compose to [v2.29.2](https://github.com/docker/compose/releases/tag/v2.29.2). [docker/docker-ce-packaging#1050](https://github.com/docker/docker-ce-packaging/pull/1050)
* Update containerd to [v1.7.21](https://github.com/containerd/containerd/releases/tag/v1.7.21). [moby/moby#48383](https://github.com/moby/moby/pull/48383), [docker/containerd-packaging#389](https://github.com/docker/containerd-packaging/pull/389)

### [Known Issues](#known-issues)

* There is a known issue when authenticating against a registry in the Docker CLI (`docker login [registry address]`) where, if the provided registry address includes a repository/image name (such as `docker login index.docker.io/docker/welcome-to-docker`), the repository part (`docker/welcome-to-docker`) is not normalized and results in credentials being stored incorrectly, which causes subsequent pulls from the registry (`docker pull index.docker.io/docker/welcome-to-docker`) to not be authenticated. To prevent this, don't include any extraneous suffix in the registry address when running `docker login`.

  > Note
  >
  > Using `docker login` with an address that includes URL path segments is not a documented use case and is considered unsupported. The recommended usage is to specify only a registry hostname, and optionally a port, as the address for `docker login`.

## [27.1](#271)

Release notes for Docker Engine version 27.1 releases.

### [27.1.2](#2712)

*2024-08-13*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.1.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.1.2)
* [moby/moby, 27.1.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.1.2)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v27.1.2/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v27.1.2/docs/api/version-history.md).

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-7)

* Fix a regression that could result in a `ResourceExhausted desc = grpc: received message larger than max` error when building from a large Dockerfile. [moby/moby#48245](https://github.com/moby/moby/pull/48245)
* CLI: Fix `docker attach` printing a spurious `context cancelled` error message. [docker/cli#5296](https://github.com/docker/cli/pull/5296)
* CLI: Fix `docker attach` exiting on `SIGINT` instead of forwarding the signal to the container and waiting for it to exit. [docker/cli#5302](https://github.com/docker/cli/pull/5302)
* CLI: Fix `--device-read-bps` and `--device-write-bps` options not taking effect. [docker/cli#5339](https://github.com/docker/cli/pull/5339)
* CLI: Fix a panic happening in some cases while running a plugin. [docker/cli#5337](https://github.com/docker/cli/pull/5337)

#### [Packaging updates](#packaging-updates-8)

* Update BuildKit to [v0.15.1](https://github.com/moby/buildkit/releases/tag/v0.15.1). [moby/moby#48246](https://github.com/moby/moby/pull/48246)
* Update Buildx to [v0.16.2](https://github.com/docker/buildx/releases/tag/v0.16.2). [docker/docker-ce-packaging#1043](https://github.com/docker/docker-ce-packaging/pull/1043)
* Update Go runtime to 1.21.13. [moby/moby#48301](https://github.com/moby/moby/pull/48301), [docker/cli#5325](https://github.com/docker/cli/pull/5325), [docker/docker-ce-packaging#1046](https://github.com/docker/docker-ce-packaging/pull/1046)
* Remove unused `docker-proxy.exe` binary from Windows packages. [docker/docker-ce-packaging#1045](https://github.com/docker/docker-ce-packaging/pull/1045)

### [27.1.1](#2711)

*2024-07-23*

#### [Security](#security)

This release contains a fix for [CVE-2024-41110](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-41110) / [GHSA-v23v-6jw2-98fq](https://github.com/moby/moby/security/advisories/GHSA-v23v-6jw2-98fq) that impacted setups using [authorization plugins (AuthZ)](https://docs.docker.com/engine/extend/plugins_authorization/) for access control. No other changes are included in this release, and this release is otherwise identical for users not using AuthZ plugins.

#### [Packaging updates](#packaging-updates-9)

* Update Compose to [v2.29.1](https://github.com/docker/compose/releases/tag/v2.29.1). [moby/docker-ce-packaging#1041](https://github.com/docker/docker-ce-packaging/pull/1041)

### [27.1.0](#2710)

*2024-07-22*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.1.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.1.0)
* [moby/moby, 27.1.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.1.0)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v27.1.0/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v27.1.0/docs/api/version-history.md).

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-8)

* rootless: add `Requires=dbus.socket` to prevent errors when starting the daemon on a cgroup v2 host with systemd [moby/moby#48141](https://github.com/moby/moby/pull/48141)
* containerd integration: `image tag` event is now properly emitted when building images with BuildKit [moby/moby#48182](https://github.com/moby/moby/pull/48182)
* CLI: enable shell completion for `docker image rm`, `docker image history`, and `docker image inspect` [moby/moby#5261](https://github.com/moby/moby/pull/5261)
* CLI: add and improve shell completions for various flags [moby/moby#5261](https://github.com/moby/moby/pull/5261)
* CLI: add OOMScoreAdj to `docker service create` and `docker stack` [docker/cli#5274](https://github.com/docker/cli/pull/5274)
* CLI: add support for `DOCKER_CUSTOM_HEADERS` environment variable (experimental) [docker/cli#5271](https://github.com/docker/cli/pull/5271)
* CLI: containerd-integration: Fix `docker push` defaulting the `--platform` flag to a value of `DOCKER_DEFAULT_PLATFORM` environment variable on unsupported API versions [docker/cli#5248](https://github.com/docker/cli/pull/5248)
* CLI: fix: context cancellation on `login` prompt [docker/cli#5260](https://github.com/docker/cli/pull/5260)
* CLI: fix: wait for the container to exit before closing the stream when sending a termination request to the CLI while attached to a container [docker/cli#5250](https://github.com/docker/cli/pull/5250)

#### [Deprecated](#deprecated)

* The `pkg/rootless/specconv` package is deprecated, and will be removed in the next release [moby/moby#48185](https://github.com/moby/moby/pull/48185)
* The `pkg/containerfs` package is deprecated, and will be removed in the next release [moby/moby#48185](https://github.com/moby/moby/pull/48185)
* The `pkg/directory` package is deprecated, and will be removed in the next release [moby/moby#48185](https://github.com/moby/moby/pull/48185)
* `api/types/system`: remove deprecated `Info.ExecutionDriver` [moby/moby#48184](https://github.com/moby/moby/pull/48184)

#### [Packaging updates](#packaging-updates-10)

* Update Buildx to [v0.16.1](https://github.com/docker/buildx/releases/tag/v0.16.1). [moby/docker-ce-packaging#1039](https://github.com/docker/docker-ce-packaging/pull/1039)
* Update Compose to [v2.29.0](https://github.com/docker/compose/releases/tag/v2.29.0). [moby/docker-ce-packaging#1038](https://github.com/docker/docker-ce-packaging/pull/1038)
* Update Containerd (static binaries only) to [v1.7.20](https://github.com/containerd/containerd/releases/tag/v1.7.20). [moby/moby#48191](https://github.com/moby/moby/pull/48191)
* Update BuildKit to [v0.15.0](https://github.com/moby/buildkit/releases/tag/v0.15.0). [moby/moby#48175](https://github.com/moby/moby/pull/48175)
* Update Go runtime to 1.21.12, which contains security fixes for [CVE-2024-24791](https://github.com/advisories/GHSA-hw49-2p59-3mhj) [moby/moby#48120](https://github.com/moby/moby/pull/48120)

## [27.0](#270)

Release notes for Docker Engine 27.0.

### [27.0.3](#2703)

*2024-07-01*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.0.3 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.0.3)
* [moby/moby, 27.0.3 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.0.3)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v27.0.3/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v27.0.3/docs/api/version-history.md).

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-9)

* Fix a regression that incorrectly reported a port mapping from a host IPv6 address to an IPv4-only container as an error. [moby/moby#48090](https://github.com/moby/moby/pull/48090)
* Fix a regression that caused duplicate subnet allocations when creating networks. [moby/moby#48089](https://github.com/moby/moby/pull/48089)
* Fix a regression resulting in `fail to register layer: failed to Lchown` errors when trying to pull an image with rootless enabled on a system that supports native overlay with user-namespaces. [moby/moby#48086](https://github.com/moby/moby/pull/48086)

### [27.0.2](#2702)

*2024-06-27*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.0.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.0.2)
* [moby/moby, 27.0.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.0.2)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v27.0.2/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v27.0.2/docs/api/version-history.md).

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-10)

* Fix a regression that caused port numbers to be ignored when parsing a Docker registry URL. [docker/cli#5197](https://github.com/docker/cli/pull/5197), [docker/cli#5198](https://github.com/docker/cli/pull/5198)

#### [Removed](#removed-1)

* api/types: deprecate `ContainerJSONBase.Node` field and `ContainerNode` type. These definitions were used by the standalone ("classic") Swarm API, but never implemented in the Docker Engine itself. [moby/moby#48055](https://github.com/moby/moby/pull/48055)

### [27.0.1](#2701)

*2024-06-24*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 27.0.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A27.0.0)
* [moby/moby, 27.0.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A27.0.0)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v27.0.1/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v27.0.1/docs/api/version-history.md).

#### [New](#new-1)

* containerd image store: Add `--platform` flag to `docker image push` and improve the default behavior when not all platforms of the multi-platform image are available locally. [docker/cli#4984](https://github.com/docker/cli/pull/4984), [moby/moby#47679](https://github.com/moby/moby/pull/47679)
* Add support to `docker stack deploy` for `driver_opts` in a service's networks. [docker/cli#5125](https://github.com/docker/cli/pull/5125)
* Consider additional `/usr/local/libexec` and `/usr/libexec` paths when looking up the userland proxy binaries by a name with a `docker-` prefix. [moby/moby#47804](https://github.com/moby/moby/pull/47804)

#### [Bug fixes and enhancements](#bug-fixes-and-enhancements-11)

* `*client.Client` instances are now always safe for concurrent use by multiple goroutines. Previously, this could lead to data races when the `WithAPIVersionNegotiation()` option is used. [moby/moby#47961](https://github.com/moby/moby/pull/47961)
* Fix a bug causing the Docker CLI to leak Unix sockets in `$TMPDIR` in some cases. [docker/cli#5146](https://github.com/docker/cli/pull/5146)
* Don't ignore a custom seccomp profile when used in conjunction with `--privileged`. [moby/moby#47500](https://github.com/moby/moby/pull/47500)
* rootless: overlay2: support native overlay diff when using rootless-mode with Linux kernel version 5.11 and later. [moby/moby#47605](https://github.com/moby/moby/pull/47605)
* Fix the `StartInterval` default value of healthcheck to reflect the documented value of 5s. [moby/moby#47799](https://github.com/moby/moby/pull/47799)
* Fix `docker save` and `docker load` not ending on the daemon side when the operation was cancelled by the user, for example with `Ctrl+C`. [moby/moby#47629](https://github.com/moby/moby/pull/47629)
* The `StartedAt` property of containers is now recorded before container startup, guaranteeing that the `StartedAt` is always before `FinishedAt`. [moby/moby#47003](https://github.com/moby/moby/pull/47003)
* The internal DNS resolver used by Windows containers on Windows now forwards requests to external DNS servers by default. This enables `nslookup` to resolve external hostnames. This behaviour can be disabled via `daemon.json`, using `"features": { "windows-dns-proxy": false }`. The configuration option will be removed in a future release. [moby/moby#47826](https://github.com/moby/moby/pull/47826)
* Print a warning when the CLI does not have permissions to read the configuration file. [docker/cli#5077](https://github.com/docker/cli/pull/5077)
* Fix a goroutine and file-descriptor leak on container attach. [moby/moby#45052](https://github.com/moby/moby/pull/45052)
* Clear the networking state of all stopped or dead containers during daemon start-up. [moby/moby#47984](https://github.com/moby/moby/pull/47984)
* Write volume options JSON atomically to avoid "invalid JSON" errors after system crash. [moby/moby#48034](https://github.com/moby/moby/pull/48034)
* Allow multiple macvlan networks with the same parent. [moby/moby#47318](https://github.com/moby/moby/pull/47318)
* Allow BuildKit to be used on Windows daemons that advertise it. [docker/cli#5178](https://github.com/docker/cli/pull/5178)

#### [Networking](#networking)

* Allow sysctls to be set per-interface during container creation and network connection. [moby/moby#47686](https://github.com/moby/moby/pull/47686)
  * In a future release, this will be the only way to set per-interface sysctl options. For example, on the command line in a `docker run` command,`--network mynet --sysctl net.ipv4.conf.eth0.log_martians=1` will be rejected. Instead, you must use `--network name=mynet,driver-opt=com.docker.network.endpoint.sysctls=net.ipv4.conf.IFNAME.log_martians=1`.

##### [IPv6](#ipv6)

* `ip6tables` is no longer experimental. You may remove the `experimental` configuration option and continue to use IPv6, if it is not required by any other features.

* `ip6tables` is now enabled for Linux bridge networks by default. [moby/moby#47747](https://github.com/moby/moby/pull/47747)

  * This makes IPv4 and IPv6 behaviors consistent with each other, and reduces the risk that IPv6-enabled containers are inadvertently exposed to the network.
  * There is no impact if you are running Docker Engine with `ip6tables` enabled (new default).
  * If you are using an IPv6-enabled bridge network without `ip6tables`, this is likely a breaking change. Only published container ports (`-p` or `--publish`) are accessible from outside the Docker bridge network, and outgoing connections masquerade as the host.
  * To restore the behavior of earlier releases, no `ip6tables` at all, set `"ip6tables": false` in `daemon.json`, or use the CLI option `--ip6tables=false`. Alternatively, leave `ip6tables` enabled, publish ports, and enable direct routing.
  * With `ip6tables` enabled, if `ip6tables` is not functional on your host, Docker Engine will start but it will not be possible to create an IPv6-enabled network.

##### [IPv6 network configuration improvements](#ipv6-network-configuration-improvements)

* A Unique Local Address (ULA) base prefix is automatically added to `default-address-pools` if this parameter wasn't manually configured, or if it contains no IPv6 prefixes. [moby/moby#47853](https://github.com/moby/moby/pull/47853)

  * Prior to this release, to create an IPv6-enabled network it was necessary to use the `--subnet` option to specify an IPv6 subnet, or add IPv6 ranges to `default-address-pools` in `daemon.json`.
  * Starting in this release, when a bridge network is created with `--ipv6` and no IPv6 subnet is defined by those options, an IPv6 Unique Local Address (ULA) base prefix is used.
  * The ULA prefix is derived from the Engine host ID such that it's unique across hosts and over time.

* IPv6 address pools of any size can now be added to `default-address-pools`. [moby/moby#47768](https://github.com/moby/moby/pull/47768)

* IPv6 can now be enabled by default on all custom bridge networks using `"default-network-opts": { "bridge": {"com.docker.network.enable_ipv6": "true"}}` in `daemon.json`, or `dockerd --default-network-opt=bridge=com.docker.network.enable_ipv6=true`on the command line. [moby/moby#47867](https://github.com/moby/moby/pull/47867)

* Direct routing for IPv6 networks, with `ip6tables` enabled. [moby/moby#47871](https://github.com/moby/moby/pull/47871)

  * Added bridge driver option `com.docker.network.bridge.gateway_mode_ipv6=<nat|routed>`.
  * The default behavior, `nat`, is unchanged from previous releases running with `ip6tables` enabled. NAT and masquerading rules are set up for each published container port.
  * When set to `routed`, no NAT or masquerading rules are configured for published ports. This enables direct IPv6 access to the container, if the host's network can route packets for the container's address to the host. Published ports will be opened in the container's firewall.
  * When a port mapping only applies to `routed` mode, only addresses `0.0.0.0` or `::` are allowed and a host port must not be given.
  * Note that published container ports, in `nat` or `routed` mode, are accessible from any remote address if routing is set up in the network, unless the Docker host's firewall has additional restrictions. For example: `docker network create --ipv6 -o com.docker.network.bridge.gateway_mode_ipv6=routed mynet`.
  * The option `com.docker.network.bridge.gateway_mode_ipv4=<nat|routed>` is also available, with the same behavior but for IPv4.

* If firewalld is running on the host, Docker creates policy `docker-forwarding` to allow forwarding from any zone to the `docker` zone. This makes it possible to configure a bridge network with a routable IPv6 address, and no NAT or masquerading. [moby/moby#47745](https://github.com/moby/moby/pull/47745)

* When a port is published with no host port specified, or a host port range is given, the same port will be allocated for IPv4 and IPv6. [moby/moby#47871](https://github.com/moby/moby/pull/47871)

  * For example `-p 80` will result in the same ephemeral port being allocated for `0.0.0.0` and `::`, and `-p 8080-8083:80` will pick the same port from the range for both address families.
  * Similarly, ports published to specific addresses will be allocated the same port. For example, `-p 127.0.0.1::80 -p '[::1]::80'`.
  * If no port is available on all required addresses, container creation will fail.

* Environment variable `DOCKER_ALLOW_IPV6_ON_IPV4_INTERFACE`, introduced in release 26.1.1, no longer has any effect. [moby/moby#47963](https://github.com/moby/moby/pull/47963)

  * If IPv6 could not be disabled on an interface because of a read-only `/proc/sys/net`, the environment variable allowed the container to start anyway.
  * In this release, if IPv4 cannot be disabled for an interface, IPv6 can be explicitly enabled for the network simply by using `--ipv6` when creating it. Other workarounds are to configure the OS to disable IPv6 by default on new interfaces, mount `/proc/sys/net` read-write, or use a kernel with no IPv6 support.

* For IPv6-enabled bridge networks, do not attempt to replace the bridge's kernel-assigned link local address with `fe80::1`. [moby/moby#47787](https://github.com/moby/moby/pull/47787)

#### [Removed](#removed-2)

* Deprecate experimental GraphDriver plugins. [moby/moby#48050](https://github.com/moby/moby/pull/48050), [docker/cli#5172](https://github.com/docker/cli/pull/5172)
* pkg/archive: deprecate `NewTempArchive` and `TempArchive`. These types were only used in tests and will be removed in the next release. [moby/moby#48002](https://github.com/moby/moby/pull/48002)
* pkg/archive: deprecate `CanonicalTarNameForPath` [moby/moby#48001](https://github.com/moby/moby/pull/48001)
* Deprecate pkg/dmesg. This package was no longer used, and will be removed in the next release. [moby/moby#47999](https://github.com/moby/moby/pull/47999)
* Deprecate `pkg/stringid.ValidateID` and `pkg/stringid.IsShortID` [moby/moby#47995](https://github.com/moby/moby/pull/47995)
* runconfig: deprecate `SetDefaultNetModeIfBlank` and move `ContainerConfigWrapper` to `api/types/container` [moby/moby#48007](https://github.com/moby/moby/pull/48007)
* runconfig: deprecate `DefaultDaemonNetworkMode` and move to `daemon/network` [moby/moby#48008](https://github.com/moby/moby/pull/48008)
* runconfig: deprecate `opts.ConvertKVStringsToMap`. This utility is no longer used, and will be removed in the next release. [moby/moby#48016](https://github.com/moby/moby/pull/48016)
* runconfig: deprecate `IsPreDefinedNetwork`. [moby/moby#48011](https://github.com/moby/moby/pull/48011)

#### [API](#api-2)

* containerd image store: `POST /images/{name}/push` now supports a `platform` parameter (JSON encoded OCI Platform type) that allows selecting a specific platform-manifest from the multi-platform image. This is experimental and may change in future API versions. [moby/moby#47679](https://github.com/moby/moby/pull/47679)
* `POST /services/create` and `POST /services/{id}/update` now support `OomScoreAdj`. [moby/moby#47950](https://github.com/moby/moby/pull/47950)
* `ContainerList` api returns container annotations. [moby/moby#47866](https://github.com/moby/moby/pull/47866)
* `POST /containers/create` and `POST /services/create` now take `Options` as part of `HostConfig.Mounts.TmpfsOptions` allowing to set options for tmpfs mounts. [moby/moby#46809](https://github.com/moby/moby/pull/46809)
* The `Healthcheck.StartInterval` property is now correctly ignored when updating a Swarm service using API versions less than v1.44. [moby/moby#47991](https://github.com/moby/moby/pull/47991)
* `GET /events` now supports image `create` event that is emitted when a new image is built regardless if it was tagged or not. [moby/moby#47929](https://github.com/moby/moby/pull/47929)
* `GET /info` now includes a `Containerd` field containing information about the location of the containerd API socket and containerd namespaces used by the daemon to run containers and plugins. [moby/moby#47239](https://github.com/moby/moby/pull/47239)
* Deprecate non-standard (config) fields in image inspect output. The `Config` field returned by this endpoint (used for `docker image inspect`) returned additional fields that are not part of the image's configuration and not part of the [Docker Image Spec](https://github.com/moby/docker-image-spec/blob/v1.3.1/specs-go/v1/image.go#L19-L32) and the [OCI Image Spec](https://github.com/opencontainers/image-spec/blob/v1.1.0/specs-go/v1/config.go#L24-L62). These fields are never set (and always return the default value for the type), but are not omitted in the response when left empty. As these fields were not intended to be part of the image configuration response, they are deprecated, and will be removed in the future API versions.
* Deprecate the daemon flag `--api-cors-header` and the corresponding `daemon.json` configuration option. These will be removed in the next major release. [moby/moby#45313](https://github.com/moby/moby/pull/45313)

The following deprecated fields are currently included in the API response, but are not part of the underlying image's `Config`: [moby/moby#47941](https://github.com/moby/moby/pull/47941)

#### [Go SDK changes](#go-sdk-changes)

* Client API callback for the following functions now require a context parameter. [moby/moby#47536](https://github.com/moby/moby/pull/47536)

  * `client.RequestPrivilegeFunc`
  * `client.ImageSearchOptions.AcceptPermissionsFunc`
  * `image.ImportOptions.PrivilegeFunc`

* Remove deprecated aliases for Image types. [moby/moby#47900](https://github.com/moby/moby/pull/47900)

  * `ImageImportOptions`
  * `ImageCreateOptions`
  * `ImagePullOptions`
  * `ImagePushOptions`
  * `ImageListOptions`
  * `ImageRemoveOptions`

* Introduce `Ulimit` type alias for `github.com/docker/go-units.Ulimit`. The `Ulimit` type as used in the API is defined in a Go module that will transition to a new location in future. A type alias is added to reduce the friction that comes with moving the type to a new location. The alias makes sure that existing code continues to work, but its definition may change in future. Users are recommended to use this alias instead of the `units.Ulimit` directly. [moby/moby#48023](https://github.com/moby/moby/pull/48023)

Move and rename types, changing their import paths and exported names. [moby/moby#47936](https://github.com/moby/moby/pull/47936), [moby/moby#47873](https://github.com/moby/moby/pull/47873), [moby/moby#47887](https://github.com/moby/moby/pull/47887), [moby/moby#47882](https://github.com/moby/moby/pull/47882), [moby/moby#47921](https://github.com/moby/moby/pull/47921), [moby/moby#48040](https://github.com/moby/moby/pull/48040)

* Move the following types to `api/types/container`:

  * `BlkioStatEntry`
  * `BlkioStats`
  * `CPUStats`
  * `CPUUsage`
  * `ContainerExecInspect`
  * `ContainerPathStat`
  * `ContainerStats`
  * `ContainersPruneReport`
  * `CopyToContainerOptions`
  * `ExecConfig`
  * `ExecStartCheck`
  * `MemoryStats`
  * `NetworkStats`
  * `PidsStats`
  * `StatsJSON`
  * `Stats`
  * `StorageStats`
  * `ThrottlingData`

* Move the following types to `api/types/image`:

  * `ImagesPruneReport`
  * `ImageImportSource`
  * `ImageLoadResponse`

* Move the `ExecStartOptions` type to `api/types/backend`.

* Move the `VolumesPruneReport` type to `api/types/volume`.

* Move the `EventsOptions` type to `api/types/events`.

* Move the `ImageSearchOptions` type to `api/types/registry`.

* Drop `Network` prefix and move the following types to `api/types/network`:

  * `NetworkCreateResponse`
  * `NetworkConnect`
  * `NetworkDisconnect`
  * `NetworkInspectOptions`
  * `EndpointResource`
  * `NetworkListOptions`
  * `NetworkCreateOptions`
  * `NetworkCreateRequest`
  * `NetworksPruneReport`

* Move `NetworkResource` to `api/types/network`.

#### [Packaging updates](#packaging-updates-11)

* Update Buildx to [v0.15.1](https://github.com/docker/buildx/releases/tag/v0.15.1). [docker/docker-ce-packaging#1029](https://github.com/docker/docker-ce-packaging/pull/1029)
* Update BuildKit to [v0.14.1](https://github.com/moby/buildkit/releases/tag/v0.14.1). [moby/moby#48028](https://github.com/moby/moby/pull/48028)
* Update runc to [v1.1.13](https://github.com/opencontainers/runc/releases/tag/v1.1.13) [moby/moby#47976](https://github.com/moby/moby/pull/47976)
* Update Compose to [v2.28.1](https://github.com/docker/compose/releases/tag/v2.28.1). [moby/docker-ce-packaging#1032](https://github.com/docker/docker-ce-packaging/pull/1032)

### [27.0.0](#2700)

There's no 27.0.0 release due to a mistake during the pre-release of 27.0.0-rc.1 on GitHub which resulted in the v27.0.0 tag being created. Unfortunately the tag was already picked up by the [Go Module Mirror](https://sum.golang.org) so it's not possible to cleanly change the v27.0.0. To workaround this, the 27.0.1 will be the first release of the 27.0.

----
url: https://docs.docker.com/build/bake/reference/
----

# Bake file reference

***

Table of contents

***

The Bake file is a file for defining workflows that you run using `docker buildx bake`.

## [File format](#file-format)

You can define your Bake file in the following file formats:

* HashiCorp Configuration Language (HCL)
* JSON
* YAML (Compose file)

By default, Bake uses the following lookup order to find the configuration file:

You can specify the file location explicitly using the `--file` flag:

```console
$ docker buildx bake --file ../docker/bake.hcl --print
```

If you don't specify a file explicitly, Bake searches for the file in the current working directory. If more than one Bake file is found, all files are merged into a single definition. Files are merged according to the lookup order. That means that if your project contains both a `compose.yaml` file and a `docker-bake.hcl` file, Bake loads the `compose.yaml` file first, and then the `docker-bake.hcl` file.

If merged files contain duplicate attribute definitions, those definitions are either merged or overridden by the last occurrence, depending on the attribute. The following attributes are overridden by the last occurrence:

* `target.cache-to`
* `target.dockerfile-inline`
* `target.dockerfile`
* `target.outputs`
* `target.platforms`
* `target.pull`
* `target.tags`
* `target.target`

For example, if `compose.yaml` and `docker-bake.hcl` both define the `tags` attribute, the `docker-bake.hcl` is used.

```console
$ cat compose.yaml
services:
  webapp:
    build:
      context: .
      tags:
        - bar
$ cat docker-bake.hcl
target "webapp" {
  tags = ["foo"]
}
$ docker buildx bake --print webapp
{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "foo"
      ]
    }
  }
}
```

All other attributes are merged. For example, if `compose.yaml` and `docker-bake.hcl` both define unique entries for the `labels` attribute, all entries are included. Duplicate entries for the same label are overridden.

```console
$ cat compose.yaml
services:
  webapp:
    build:
      context: .
      labels: 
        com.example.foo: "foo"
        com.example.name: "Alice"
$ cat docker-bake.hcl
target "webapp" {
  labels = {
    "com.example.bar" = "bar"
    "com.example.name" = "Bob"
  }
}
$ docker buildx bake --print webapp
{
  "group": {
    "default": {
      "targets": [
        "webapp"
      ]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "labels": {
        "com.example.foo": "foo",
        "com.example.bar": "bar",
        "com.example.name": "Bob"
      }
    }
  }
}
```

## [Syntax](#syntax)

The Bake file supports the following property types:

* `target`: build targets
* `group`: collections of build targets
* `variable`: build arguments and variables
* `function`: custom Bake functions

You define properties as hierarchical blocks in the Bake file. You can assign one or more attributes to a property.

The following snippet shows a JSON representation of a simple Bake file. This Bake file defines three properties: a variable, a group, and a target.

```json
{
  "variable": {
    "TAG": {
      "default": "latest"
    }
  },
  "group": {
    "default": {
      "targets": ["webapp"]
    }
  },
  "target": {
    "webapp": {
      "dockerfile": "Dockerfile",
      "tags": ["docker.io/username/webapp:${TAG}"]
    }
  }
}
```

In the JSON representation of a Bake file, properties are objects, and attributes are values assigned to those objects.

The following example shows the same Bake file in the HCL format:

```hcl
variable "TAG" {
  default = "latest"
}

group "default" {
  targets = ["webapp"]
}

target "webapp" {
  dockerfile = "Dockerfile"
  tags = ["docker.io/username/webapp:${TAG}"]
}
```

HCL is the preferred format for Bake files. Aside from syntactic differences, HCL lets you use features that the JSON and YAML formats don't support.

The examples in this document use the HCL format.

## [Target](#target)

A target reflects a single `docker build` invocation. Consider the following build command:

```console
$ docker build \
  --file=Dockerfile.webapp \
  --tag=docker.io/username/webapp:latest \
  https://github.com/username/webapp
```

You can express this command in a Bake file as follows:

```hcl
target "webapp" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  context = "https://github.com/username/webapp"
}
```

The following table shows the complete list of attributes that you can assign to a target:

| Name                                            | Type    | Description                                                          |
| ----------------------------------------------- | ------- | -------------------------------------------------------------------- |
| [`args`](#targetargs)                           | Map     | Build arguments                                                      |
| [`annotations`](#targetannotations)             | List    | Exporter annotations                                                 |
| [`attest`](#targetattest)                       | List    | Build attestations                                                   |
| [`cache-from`](#targetcache-from)               | List    | External cache sources                                               |
| [`cache-to`](#targetcache-to)                   | List    | External cache destinations                                          |
| [`call`](#targetcall)                           | String  | Specify the frontend method to call for the target.                  |
| [`context`](#targetcontext)                     | String  | Set of files located in the specified path or URL                    |
| [`contexts`](#targetcontexts)                   | Map     | Additional build contexts                                            |
| [`description`](#targetdescription)             | String  | Description of a target                                              |
| [`dockerfile-inline`](#targetdockerfile-inline) | String  | Inline Dockerfile string                                             |
| [`dockerfile`](#targetdockerfile)               | String  | Dockerfile location                                                  |
| [`entitlements`](#targetentitlements)           | List    | Permissions that the build process requires to run                   |
| [`extra-hosts`](#targetextra-hosts)             | List    | Customs host-to-IP mapping                                           |
| [`inherits`](#targetinherits)                   | List    | Inherit attributes from other targets                                |
| [`labels`](#targetlabels)                       | Map     | Metadata for images                                                  |
| [`matrix`](#targetmatrix)                       | Map     | Define a set of variables that forks a target into multiple targets. |
| [`name`](#targetname)                           | String  | Override the target name when using a matrix.                        |
| [`no-cache-filter`](#targetno-cache-filter)     | List    | Disable build cache for specific stages                              |
| [`no-cache`](#targetno-cache)                   | Boolean | Disable build cache completely                                       |
| [`output`](#targetoutput)                       | List    | Output destinations                                                  |
| [`policy`](#targetpolicy)                       | List    | Policies to validate build sources and metadata                      |
| [`platforms`](#targetplatforms)                 | List    | Target platforms                                                     |
| [`pull`](#targetpull)                           | Boolean | Always pull images                                                   |
| [`secret`](#targetsecret)                       | List    | Secrets to expose to the build                                       |
| [`shm-size`](#targetshm-size)                   | List    | Size of `/dev/shm`                                                   |
| [`ssh`](#targetssh)                             | List    | SSH agent sockets or keys to expose to the build                     |
| [`tags`](#targettags)                           | List    | Image names and tags                                                 |
| [`target`](#targettarget)                       | String  | Target build stage                                                   |
| [`ulimits`](#targetulimits)                     | List    | Ulimit options                                                       |

### [`target.args`](#targetargs)

Use the `args` attribute to define build arguments for the target. This has the same effect as passing a [`--build-arg`](https://docs.docker.com/reference/cli/docker/image/build/#build-arg) flag to the build command.

```hcl
target "default" {
  args = {
    VERSION = "0.0.0+unknown"
  }
}
```

You can set `args` attributes to use `null` values. Doing so forces the `target` to use the `ARG` value specified in the Dockerfile.

```hcl
variable "GO_VERSION" {
  default = "1.20.3"
}

target "webapp" {
  dockerfile = "webapp.Dockerfile"
  tags = ["docker.io/username/webapp"]
}

target "db" {
  args = {
    GO_VERSION = null
  }
  dockerfile = "db.Dockerfile"
  tags = ["docker.io/username/db"]
}
```

### [`target.annotations`](#targetannotations)

The `annotations` attribute lets you add annotations to images built with bake. The key takes a list of annotations, in the format of `KEY=VALUE`.

```hcl
target "default" {
  output = [{ type = "image", name = "foo" }]
  annotations = ["org.opencontainers.image.authors=dvdksn"]
}
```

By default, the annotation is added to image manifests. You can configure the level of the annotations by adding a prefix to the annotation, containing a comma-separated list of all the levels that you want to annotate. The following example adds annotations to both the image index and manifests.

```hcl
target "default" {
  output = [
    {
      type = "image"
      name = "foo"
    }
  ]
  annotations = ["index,manifest:org.opencontainers.image.authors=dvdksn"]
}
```

Read about the supported levels in [Specifying annotation levels](https://docs.docker.com/build/building/annotations/#specifying-annotation-levels).

### [`target.attest`](#targetattest)

The `attest` attribute lets you apply [build attestations](https://docs.docker.com/build/attestations/) to the target. This attribute accepts the long-form CSV version of attestation parameters.

```hcl
target "default" {
  attest = [
    {
      type = "provenance"
      mode = "max"
    },
    {
      type = "sbom"
    }
  ]
}
```

### [`target.cache-from`](#targetcache-from)

Build cache sources. The builder imports cache from the locations you specify. It uses the [Buildx cache storage backends](https://docs.docker.com/build/cache/backends/), and it works the same way as the [`--cache-from`](https://docs.docker.com/reference/cli/docker/buildx/build/#cache-from) flag. This takes a list value, so you can specify multiple cache sources.

```hcl
target "app" {
  cache-from = [
    {
      type = "s3"
      region = "eu-west-1"
      bucket = "mybucket"
    },
    {
      type = "registry"
      ref = "user/repo:cache"
    }
  ]
}
```

### [`target.cache-to`](#targetcache-to)

Build cache export destinations. The builder exports its build cache to the locations you specify. It uses the [Buildx cache storage backends](https://docs.docker.com/build/cache/backends/), and it works the same way as the [`--cache-to` flag](https://docs.docker.com/reference/cli/docker/buildx/build/#cache-to). This takes a list value, so you can specify multiple cache export targets.

```hcl
target "app" {
  cache-to = [
    {
      type = "s3"
      region = "eu-west-1"
      bucket = "mybucket"
    },
    {
      type = "inline"
    }
  ]
}
```

### [`target.call`](#targetcall)

Specifies the frontend method to use. Frontend methods let you, for example, execute build checks only, instead of running a build. This is the same as the `--call` flag.

```hcl
target "app" {
  call = "check"
}
```

Supported values are:

* `build` builds the target (default)
* `check`: evaluates [build checks](https://docs.docker.com/build/checks/) for the target
* `outline`: displays the target's build arguments and their default values if available
* `targets`: lists all Bake targets in the loaded definition, along with its [description](#targetdescription).

For more information about frontend methods, refer to the CLI reference for [`docker buildx build --call`](https://docs.docker.com/reference/cli/docker/buildx/build/#call).

### [`target.context`](#targetcontext)

Specifies the location of the build context to use for this target. Accepts a URL or a directory path. This is the same as the [build context](https://docs.docker.com/reference/cli/docker/buildx/build/#build-context) positional argument that you pass to the build command.

```hcl
target "app" {
  context = "./src/www"
}
```

This resolves to the current working directory (`"."`) by default.

```console
$ docker buildx bake --print -f - <<< 'target "default" {}'
[+] Building 0.0s (0/0)
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile"
    }
  }
}
```

### [`target.contexts`](#targetcontexts)

Additional build contexts. This is the same as the [`--build-context` flag](https://docs.docker.com/reference/cli/docker/buildx/build/#build-context). This attribute takes a map, where keys result in named contexts that you can reference in your builds.

You can specify different types of contexts, such local directories, Git URLs, and even other Bake targets. Bake automatically determines the type of a context based on the pattern of the context value.

| Context type    | Example                                   |
| --------------- | ----------------------------------------- |
| Container image | `docker-image://alpine@sha256:0123456789` |
| Git URL         | `https://github.com/user/proj.git`        |
| HTTP URL        | `https://example.com/files`               |
| Local directory | `../path/to/src`                          |
| Bake target     | `target:base`                             |

#### [Pin an image version](#pin-an-image-version)

```hcl
# docker-bake.hcl
target "app" {
  contexts = {
    alpine = "docker-image://alpine:3.13"
  }
}
```

```Dockerfile
# Dockerfile
FROM alpine
RUN echo "Hello world"
```

#### [Use a local directory](#use-a-local-directory)

```hcl
# docker-bake.hcl
target "app" {
  contexts = {
    src = "../path/to/source"
  }
}
```

```Dockerfile
# Dockerfile
FROM scratch AS src
FROM golang
COPY --from=src . .
```

#### [Use another target as base](#use-another-target-as-base)

> Note
>
> You should prefer to use regular multi-stage builds over this option. You can Use this feature when you have multiple Dockerfiles that can't be easily merged into one.

```hcl
# docker-bake.hcl
target "base" {
  dockerfile = "baseapp.Dockerfile"
}

target "app" {
  contexts = {
    baseapp = "target:base"
  }
}
```

```Dockerfile
# Dockerfile
FROM baseapp
RUN echo "Hello world"
```

### [`target.description`](#targetdescription)

Defines a human-readable description for the target, clarifying its purpose or functionality.

```hcl
target "lint" {
  description = "Runs golangci-lint to detect style errors"
  args = {
    GOLANGCI_LINT_VERSION = null
  }
  dockerfile = "lint.Dockerfile"
}
```

This attribute is useful when combined with the `docker buildx bake --list=targets` option, providing a more informative output when listing the available build targets in a Bake file.

### [`target.dockerfile-inline`](#targetdockerfile-inline)

Uses the string value as an inline Dockerfile for the build target.

```hcl
target "default" {
  dockerfile-inline = "FROM alpine\nENTRYPOINT [\"echo\", \"hello\"]"
}
```

The `dockerfile-inline` takes precedence over the `dockerfile` attribute. If you specify both, Bake uses the inline version.

### [`target.dockerfile`](#targetdockerfile)

Name of the Dockerfile to use for the build. This is the same as the [`--file` flag](https://docs.docker.com/reference/cli/docker/image/build/#file) for the `docker build` command.

```hcl
target "default" {
  dockerfile = "./src/www/Dockerfile"
}
```

Resolves to `"Dockerfile"` by default.

```console
$ docker buildx bake --print -f - <<< 'target "default" {}'
[+] Building 0.0s (0/0)
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile"
    }
  }
}
```

### [`target.entitlements`](#targetentitlements)

Entitlements are permissions that the build process requires to run.

Currently supported entitlements are:

* `network.host`: Allows the build to use commands that access the host network. In Dockerfile, use [`RUN --network=host`](https://docs.docker.com/reference/dockerfile/#run---networkhost) to run a command with host network enabled.

* `security.insecure`: Allows the build to run commands in privileged containers that are not limited by the default security sandbox. Such container may potentially access and modify system resources. In Dockerfile, use [`RUN --security=insecure`](https://docs.docker.com/reference/dockerfile/#run---security) to run a command in a privileged container.

```hcl
target "integration-tests" {
  # this target requires privileged containers to run nested containers
  entitlements = ["security.insecure"]
}
```

Entitlements are enabled with a two-step process. First, a target must declare the entitlements it requires. Secondly, when invoking the `bake` command, the user must grant the entitlements by passing the `--allow` flag or confirming the entitlements when prompted in an interactive terminal. This is to ensure that the user is aware of the possibly insecure permissions they are granting to the build process.

### [`target.extra-hosts`](#targetextra-hosts)

Use the `extra-hosts` attribute to define customs host-to-IP mapping for the target. This has the same effect as passing a [`--add-host`](https://docs.docker.com/reference/cli/docker/buildx/build/#add-host) flag to the build command.

```hcl
target "default" {
  extra-hosts = {
    my_hostname = "8.8.8.8"
  }
}
```

### [`target.inherits`](#targetinherits)

A target can inherit attributes from other targets. Use `inherits` to reference from one target to another.

In the following example, the `app-dev` target specifies an image name and tag. The `app-release` target uses `inherits` to reuse the tag name.

```hcl
variable "TAG" {
  default = "latest"
}

target "app-dev" {
  tags = ["docker.io/username/myapp:${TAG}"]
}

target "app-release" {
  inherits = ["app-dev"]
  platforms = ["linux/amd64", "linux/arm64"]
}
```

The `inherits` attribute is a list, meaning you can reuse attributes from multiple other targets. In the following example, the `app-release` target reuses attributes from both the `app-dev` and `_release` targets.

```hcl
target "app-dev" {
  args = {
    GO_VERSION = "1.20"
    BUILDX_EXPERIMENTAL = 1
  }
  tags = ["docker.io/username/myapp"]
  dockerfile = "app.Dockerfile"
  labels = {
    "org.opencontainers.image.source" = "https://github.com/username/myapp"
  }
}

target "_release" {
  args = {
    BUILDKIT_CONTEXT_KEEP_GIT_DIR = 1
    BUILDX_EXPERIMENTAL = 0
  }
}

target "app-release" {
  inherits = ["app-dev", "_release"]
  platforms = ["linux/amd64", "linux/arm64"]
}
```

When inheriting attributes from multiple targets and there's a conflict, the target that appears last in the `inherits` list takes precedence. The previous example defines the `BUILDX_EXPERIMENTAL` argument twice for the `app-release` target. It resolves to `0` because the `_release` target appears last in the inheritance chain:

```console
$ docker buildx bake --print app-release
[+] Building 0.0s (0/0)
{
  "group": {
    "default": {
      "targets": [
        "app-release"
      ]
    }
  },
  "target": {
    "app-release": {
      "context": ".",
      "dockerfile": "app.Dockerfile",
      "args": {
        "BUILDKIT_CONTEXT_KEEP_GIT_DIR": "1",
        "BUILDX_EXPERIMENTAL": "0",
        "GO_VERSION": "1.20"
      },
      "labels": {
        "org.opencontainers.image.source": "https://github.com/username/myapp"
      },
      "tags": [
        "docker.io/username/myapp"
      ],
      "platforms": [
        "linux/amd64",
        "linux/arm64"
      ]
    }
  }
}
```

### [`target.labels`](#targetlabels)

Assigns image labels to the build. This is the same as the `--label` flag for `docker build`.

```hcl
target "default" {
  labels = {
    "org.opencontainers.image.source" = "https://github.com/username/myapp"
    "com.docker.image.source.entrypoint" = "Dockerfile"
  }
}
```

It's possible to use a `null` value for labels. If you do, the builder uses the label value specified in the Dockerfile.

### [`target.matrix`](#targetmatrix)

A matrix strategy lets you fork a single target into multiple different variants, based on parameters that you specify. This works in a similar way to \[Matrix strategies for GitHub Actions]. You can use this to reduce duplication in your bake definition.

The `matrix` attribute is a map of parameter names to lists of values. Bake builds each possible combination of values as a separate target.

Each generated target **must** have a unique name. To specify how target names should resolve, use the `name` attribute.

The following example resolves the `app` target to `app-foo` and `app-bar`. It also uses the matrix value to define the [target build stage](#targettarget).

```hcl
target "app" {
  name = "app-${tgt}"
  matrix = {
    tgt = ["foo", "bar"]
  }
  target = tgt
}
```

```console
$ docker buildx bake --print app
[+] Building 0.0s (0/0)
{
  "group": {
    "app": {
      "targets": [
        "app-foo",
        "app-bar"
      ]
    },
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app-bar": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "target": "bar"
    },
    "app-foo": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "target": "foo"
    }
  }
}
```

#### [Multiple axes](#multiple-axes)

You can specify multiple keys in your matrix to fork a target on multiple axes. When using multiple matrix keys, Bake builds every possible variant.

The following example builds four targets:

* `app-foo-1-0`
* `app-foo-2-0`
* `app-bar-1-0`
* `app-bar-2-0`

```hcl
target "app" {
  name = "app-${tgt}-${replace(version, ".", "-")}"
  matrix = {
    tgt = ["foo", "bar"]
    version = ["1.0", "2.0"]
  }
  target = tgt
  args = {
    VERSION = version
  }
}
```

#### [Multiple values per matrix target](#multiple-values-per-matrix-target)

If you want to differentiate the matrix on more than just a single value, you can use maps as matrix values. Bake creates a target for each map, and you can access the nested values using dot notation.

The following example builds two targets:

* `app-foo-1-0`
* `app-bar-2-0`

```hcl
target "app" {
  name = "app-${item.tgt}-${replace(item.version, ".", "-")}"
  matrix = {
    item = [
      {
        tgt = "foo"
        version = "1.0"
      },
      {
        tgt = "bar"
        version = "2.0"
      }
    ]
  }
  target = item.tgt
  args = {
    VERSION = item.version
  }
}
```

### [`target.name`](#targetname)

Specify name resolution for targets that use a matrix strategy. The following example resolves the `app` target to `app-foo` and `app-bar`.

```hcl
target "app" {
  name = "app-${tgt}"
  matrix = {
    tgt = ["foo", "bar"]
  }
  target = tgt
}
```

### [`target.network`](#targetnetwork)

Specify the network mode for the whole build request. This will override the default network mode for all the `RUN` instructions in the Dockerfile. Accepted values are `default`, `host`, and `none`.

Usually, a better approach to set the network mode for your build steps is to instead use `RUN --network=<value>` in your Dockerfile. This way, you can set the network mode for individual build steps and everyone building the Dockerfile gets consistent behavior without needing to pass additional flags to the build command.

If you set network mode to `host` in your Bake file, you must also grant `network.host` entitlement when invoking the `bake` command. This is because `host` network mode requires elevated privileges and can be a security risk. You can pass `--allow=network.host` to the `docker buildx bake` command to grant the entitlement, or you can confirm the entitlement when prompted if you are using an interactive terminal.

```hcl
target "app" {
  # make sure this build does not access internet
  network = "none"
}
```

### [`target.no-cache-filter`](#targetno-cache-filter)

Don't use build cache for the specified stages. This is the same as the `--no-cache-filter` flag for `docker build`. The following example avoids build cache for the `foo` build stage.

```hcl
target "default" {
  no-cache-filter = ["foo"]
}
```

### [`target.no-cache`](#targetno-cache)

Don't use cache when building the image. This is the same as the `--no-cache` flag for `docker build`.

```hcl
target "default" {
  no-cache = true
}
```

### [`target.output`](#targetoutput)

Configuration for exporting the build output. This is the same as the [`--output` flag](https://docs.docker.com/reference/cli/docker/buildx/build/#output). The following example configures the target to use a cache-only output,

```hcl
target "default" {
  output = [{ type = "cacheonly" }]
}
```

### [`target.policy`](#targetpolicy)

Policies to validate build sources and metadata. Each entry uses the same keys as the `--policy` flag for `docker buildx build` (`filename`, `reset`, `disabled`, `strict`, `log-level`). Bake also automatically loads `Dockerfile.rego` alongside the target Dockerfile when present.

```hcl
target "default" {
  policy = [
    { filename = "extra.rego" },
  ]
}
```

### [`target.platforms`](#targetplatforms)

Set target platforms for the build target. This is the same as the [`--platform` flag](https://docs.docker.com/reference/cli/docker/buildx/build/#platform). The following example creates a multi-platform build for three architectures.

```hcl
target "default" {
  platforms = ["linux/amd64", "linux/arm64", "linux/arm/v7"]
}
```

### [`target.pull`](#targetpull)

Configures whether the builder should attempt to pull images when building the target. This is the same as the `--pull` flag for `docker build`. The following example forces the builder to always pull all images referenced in the build target.

```hcl
target "default" {
  pull = true
}
```

### [`target.secret`](#targetsecret)

Defines secrets to expose to the build target. This is the same as the [`--secret` flag](https://docs.docker.com/reference/cli/docker/buildx/build/#secret).

```hcl
variable "HOME" {
  default = null
}

target "default" {
  secret = [
    {
      type = "env"
      id = "KUBECONFIG"
    },
    {
      type = "file"
      id = "aws"
      src = "${HOME}/.aws/credentials"
    }
  ]
}
```

This lets you [mount the secret](https://docs.docker.com/reference/dockerfile/#run---mounttypesecret) in your Dockerfile.

```dockerfile
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
    aws cloudfront create-invalidation ...
RUN --mount=type=secret,id=KUBECONFIG,env=KUBECONFIG \
    helm upgrade --install
```

### [`target.shm-size`](#targetshm-size)

Sets the size of the shared memory allocated for build containers when using `RUN` instructions.

The format is `<number><unit>`. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes.

This is the same as the `--shm-size` flag for `docker build`.

```hcl
target "default" {
  shm-size = "128m"
}
```

> Note
>
> In most cases, it is recommended to let the builder automatically determine the appropriate configurations. Manual adjustments should only be considered when specific performance tuning is required for complex build scenarios.

### [`target.ssh`](#targetssh)

Defines SSH agent sockets or keys to expose to the build. This is the same as the [`--ssh` flag](https://docs.docker.com/reference/cli/docker/buildx/build/#ssh). This can be useful if you need to access private repositories during a build.

```hcl
target "default" {
  ssh = [{ id = "default" }]
}
```

```dockerfile
FROM alpine
RUN --mount=type=ssh \
    apk add git openssh-client \
    && install -m 0700 -d ~/.ssh \
    && ssh-keyscan github.com >> ~/.ssh/known_hosts \
    && git clone git@github.com:user/my-private-repo.git
```

### [`target.tags`](#targettags)

Image names and tags to use for the build target. This is the same as the [`--tag` flag](https://docs.docker.com/reference/cli/docker/image/build/#tag).

```hcl
target "default" {
  tags = [
    "org/repo:latest",
    "myregistry.azurecr.io/team/image:v1"
  ]
}
```

### [`target.target`](#targettarget)

Set the target build stage to build. This is the same as the [`--target` flag](https://docs.docker.com/reference/cli/docker/image/build/#target).

```hcl
target "default" {
  target = "binaries"
}
```

### [`target.ulimits`](#targetulimits)

Ulimits overrides the default ulimits of build's containers when using `RUN` instructions and are specified with a soft and hard limit as such: `<type>=<soft limit>[:<hard limit>]`, for example:

```hcl
target "app" {
  ulimits = [
    "nofile=1024:1024"
  ]
}
```

> Note
>
> If you do not provide a `hard limit`, the `soft limit` is used for both values. If no `ulimits` are set, they are inherited from the default `ulimits` set on the daemon.

> Note
>
> In most cases, it is recommended to let the builder automatically determine the appropriate configurations. Manual adjustments should only be considered when specific performance tuning is required for complex build scenarios.

## [Group](#group)

Groups allow you to invoke multiple builds (targets) at once.

```hcl
group "default" {
  targets = ["db", "webapp-dev"]
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  tags = ["docker.io/username/db"]
}
```

Groups take precedence over targets, if both exist with the same name. The following bake file builds the `default` group. Bake ignores the `default` target.

```hcl
target "default" {
  dockerfile-inline = "FROM ubuntu"
}

group "default" {
  targets = ["alpine", "debian"]
}
target "alpine" {
  dockerfile-inline = "FROM alpine"
}
target "debian" {
  dockerfile-inline = "FROM debian"
}
```

## [Variable](#variable)

The HCL file format supports variable block definitions. You can use variables as build arguments in your Dockerfile, or interpolate them in attribute values in your Bake file.

```hcl
variable "TAG" {
  type = string
  default = "latest"
  description = "Tag to use for build"
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:${TAG}"]
}
```

You can assign a default value for a variable in the Bake file, or assign a `null` value to it. If you assign a `null` value, Buildx uses the default value from the Dockerfile instead.

You can also add a description of the variable's purpose with the `description` field. This attribute is useful when combined with the `docker buildx bake --list=variables` option, providing a more informative output when listing the available variables in a Bake file.

You can override variable defaults set in the Bake file using environment variables. The following example sets the `TAG` variable to `dev`, overriding the default `latest` value shown in the previous example.

```console
$ TAG=dev docker buildx bake webapp-dev
```

Variables can also be assigned an explicit type. If provided, it will be used to validate the default value (if set), as well as any overrides. This is particularly useful when using complex types which are intended to be overridden. The previous example could be expanded to apply an arbitrary series of tags.

```hcl
variable "TAGS" {
  default = ["latest"]
  type = list(string)
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = [for tag in TAGS: "docker.io/username/webapp:${tag}"]
}
```

This example shows how to generate three tags without changing the file or using custom functions/parsing:

```console
$ TAGS=dev,latest,2 docker buildx bake webapp-dev
```

### [Variable typing](#variable-typing)

The following primitive types are available:

* `string`
* `number`
* `bool`

The type is expressed like a keyword; it must be expressed as a literal:

```hcl
variable "OK" {
  type = string
}

# cannot be an actual string
variable "BAD" {
  type = "string"
}

# cannot be the result of an expression
variable "ALSO_BAD" {
  type = lower("string")
}
```

Specifying primitive types can be valuable to show intent (especially when a default is not provided), but bake will generally behave as expected without explicit typing.

Complex types are expressed with "type constructors"; they are:

* `tuple([<type>,...])`
* `list(<type>)`
* `set(<type>)`
* `map(<type>)`
* `object({<attr>=<type>},...})`

The following are examples of each of those, as well as how the (optional) default value would be expressed:

```hcl
# structured way to express "1.2.3-alpha"
variable "MY_VERSION" {
  type = tuple([number, number, number, string])
  default = [1, 2, 3, "alpha"]
}

# JDK versions used in a matrix build
variable "JDK_VERSIONS" {
  type = list(number)
  default = [11, 17, 21]
}

# better way to express the previous example; this will also
# enforce set semantics and allow use of set-based functions
variable "JDK_VERSIONS" {
  type = set(number)
  default = [11, 17, 21]
}

# with the help of lookup(), translate a 'feature' to a tag
variable "FEATURE_TO_NAME" {
  type = map(string)
  default = {featureA = "slim", featureB = "tiny"}
}

# map a branch name to a registry location
variable "PUSH_DESTINATION" {
  type = object({branch = string, registry = string})
  default = {branch = "main", registry = "prod-registry.invalid.com"}
}

# make the previous example more useful with composition
variable "PUSH_DESTINATIONS" {
  type = list(object({branch = string, registry = string}))
  default = [
    {branch = "develop", registry = "test-registry.invalid.com"},
    {branch = "main", registry = "prod-registry.invalid.com"},
  ]
}
```

Note that in each example, the default value would be valid even if typing was not present. If typing was omitted, the first three would all be considered `tuple`; you would be restricted to functions that operate on `tuple` and, for example, not be able to add elements. Similarly, the third and fourth would both be considered `object`, with the limits and semantics of that type. In short, in the absence of a type, any value delimited with `[]` is a `tuple` and value delimited with `{}` is an `object`. Explicit typing for complex types not only opens up the ability to use functions applicable to that specialized type, but is also a precondition for providing overrides.

> Note
>
> See [HCL Type Expressions](https://github.com/hashicorp/hcl/tree/main/ext/typeexpr) page for more details.

### [Overriding variables](#overriding-variables)

As mentioned in the [intro to variables](#variable), primitive types (`string`, `number`, and `bool`) can be overridden without typing and will generally behave as expected. (When explicit typing is not provided, a variable is assumed to be primitive when the default value lacks `{}` or `[]` delimiters; a variable with neither typing nor a default value is treated as `string`.) Naturally, these same overrides can be used alongside explicit typing too; they may help in edge cases where you want `VAR=true` to be a `string`, where without typing, it may be a `string` or a `bool` depending on how/where it's used. Overriding a variable with a complex type can only be done when the type is provided. This is still done via environment variables, but the values can be provided via CSV or JSON.

#### [CSV overrides](#csv-overrides)

This is considered the canonical method and is well suited to interactive usage. It is assumed that `list` and `set` will be the most common complex type, as well as the most common complex type designed to be overridden. Thus, there is full CSV support for `list` and `set` (and `tuple`; despite being considered a structural type, it is more like a collection type in this regard).

There is limited support for `map` and `object` and no support for composite types; for these advanced cases, an alternative mechanism [using JSON](#json-overrides) is available.

#### [JSON overrides](#json-overrides)

Overrides can also be provided via JSON. This is the only method available for providing some complex types and may be convenient if overrides are already JSON (for example, if they come from a JSON API). It can also be used when dealing with values are difficult or impossible to specify using CSV (e.g., values containing quotes or commas). To use JSON, simply append `_JSON` to the variable name. In this contrived example, CSV cannot handle the second value; despite being a supported CSV type, JSON must be used:

```hcl
variable "VALS" {
  type = list(string)
  default = ["some", "list"]
}
```

```console
$ cat data.json
["hello","with,comma","with\"quote"]
$ VALS_JSON=$(< data.json) docker buildx bake

# CSV equivalent, though the second value cannot be expressed at all 
$ VALS='hello,"with""quote"' docker buildx bake
```

This example illustrates some precedence and usage rules:

```hcl
variable "FOO" {
  type = string
  default = "foo"
}

variable "FOO_JSON" {
  type = string
  default = "foo"
}
```

The variable `FOO` can *only* be overridden using CSV because `FOO_JSON`, which would typically used for a JSON override, is already a defined variable. Since `FOO_JSON` is an actual variable, setting that environment variable would be expected to a CSV value. A JSON override *is* possible for this variable, using environment variable `FOO_JSON_JSON`.

```Console
# These three are all equivalent, setting variable FOO=bar
$ FOO=bar docker buildx bake <...>
$ FOO='bar' docker buildx bake <...>
$ FOO="bar" docker buildx bake <...>

# Sets *only* variable FOO_JSON; FOO is untouched
$ FOO_JSON=bar docker buildx bake <...>

# This also sets FOO_JSON, but will fail due to not being valid JSON
$ FOO_JSON_JSON=bar docker buildx bake <...>

# These are all equivalent
$ cat data.json
"bar"
$ FOO_JSON_JSON=$(< data.json) docker buildx bake <...>
$ FOO_JSON_JSON='"bar"' docker buildx bake <...>
$ FOO_JSON=bar docker buildx bake <...>

# This results in setting two different variables, both specified as CSV (FOO=bar and FOO_JSON="baz")
$ FOO=bar FOO_JSON='"baz"' docker buildx bake <...>

# These refer to the same variable with FOO_JSON_JSON having precedence and read as JSON (FOO_JSON=baz)
$ FOO_JSON=bar FOO_JSON_JSON='"baz"' docker buildx bake <...>
```

### [Built-in variables](#built-in-variables)

The following variables are built-ins that you can use with Bake without having to define them.

| Variable              | Description                                                                         |
| --------------------- | ----------------------------------------------------------------------------------- |
| `BAKE_CMD_CONTEXT`    | Holds the main context when building using a remote Bake file.                      |
| `BAKE_LOCAL_PLATFORM` | Returns the current platform’s default platform specification (e.g. `linux/amd64`). |

### [Use environment variable as default](#use-environment-variable-as-default)

If an environment variable exists with the same name as a declared Bake variable, Bake uses that environment variable value instead of the declared default.

To disable this environment-based variable lookup, set `BUILDX_BAKE_DISABLE_VARS_ENV_LOOKUP=1`.

```hcl
variable "HOME" {
  default = "/root"
}
```

### [Interpolate variables into attributes](#interpolate-variables-into-attributes)

To interpolate a variable into an attribute string value, you must use curly brackets. The following doesn't work:

```hcl
variable "HOME" {
  default = "$HOME"
}

target "default" {
  ssh = ["default=$HOME/.ssh/id_rsa"]
}
```

Wrap the variable in curly brackets where you want to insert it:

```diff
  variable "HOME" {
    default = "$HOME"
  }

  target "default" {
-   ssh = ["default=$HOME/.ssh/id_rsa"]
+   ssh = ["default=${HOME}/.ssh/id_rsa"]
  }
```

Before you can interpolate a variable into an attribute, first you must declare it in the bake file, as demonstrated in the following example.

```console
$ cat docker-bake.hcl
target "default" {
  dockerfile-inline = "FROM ${BASE_IMAGE}"
}
$ docker buildx bake
[+] Building 0.0s (0/0)
docker-bake.hcl:2
--------------------
   1 |     target "default" {
   2 | >>>   dockerfile-inline = "FROM ${BASE_IMAGE}"
   3 |     }
   4 |
--------------------
ERROR: docker-bake.hcl:2,31-41: Unknown variable; There is no variable named "BASE_IMAGE"., and 1 other diagnostic(s)
$ cat >> docker-bake.hcl

variable "BASE_IMAGE" {
  default = "alpine"
}

$ docker buildx bake
[+] Building 0.6s (5/5) FINISHED
```

## [Function](#function)

A [set of general-purpose functions](https://github.com/docker/buildx/blob/master/docs/bake-stdlib.md) provided by [go-cty](https://github.com/zclconf/go-cty/tree/main/cty/function/stdlib) are available for use in HCL files:

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    buildno = "${add(123, 1)}"
  }
}
```

In addition, [user defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc) are also supported:

```hcl
# docker-bake.hcl
function "increment" {
  params = [number]
  result = number + 1
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    buildno = "${increment(123)}"
  }
}
```

> Note
>
> See [User defined HCL functions](https://docs.docker.com/build/bake/hcl-funcs/) page for more details.

----
url: https://docs.docker.com/guides/golang/build-images/
----

# Build your Go image

***

Table of contents

***

## [Overview](#overview)

In this section you're going to build a container image. The image includes everything you need to run your application – the compiled application binary file, the runtime, the libraries, and all other resources required by your application.

## [Required software](#required-software)

To complete this tutorial, you need the following:

* Docker running locally. Follow the [instructions to download and install Docker](https://docs.docker.com/desktop/).
* An IDE or a text editor to edit files. [Visual Studio Code](https://code.visualstudio.com/) is a free and popular choice but you can use anything you feel comfortable with.
* A Git client. This guide uses a command-line based `git` client, but you are free to use whatever works for you.
* A command-line terminal application. The examples shown in this module are from the Linux shell, but they should work in PowerShell, Windows Command Prompt, or OS X Terminal with minimal, if any, modifications.

## [Meet the example application](#meet-the-example-application)

The example application is a caricature of a microservice. It is purposefully trivial to keep focus on learning the basics of containerization for Go applications.

The application offers two HTTP endpoints:

* It responds with a string containing a heart symbol (`<3`) to requests to `/`.
* It responds with `{"Status" : "OK"}` JSON to a request to `/health`.

It responds with HTTP error 404 to any other request.

The application listens on a TCP port defined by the value of environment variable `PORT`. The default value is `8080`.

The application is stateless.

The complete source code for the application is on GitHub: [github.com/docker/docker-gs-ping](https://github.com/docker/docker-gs-ping). You are encouraged to fork it and experiment with it as much as you like.

To continue, clone the application repository to your local machine:

```console
$ git clone https://github.com/docker/docker-gs-ping
```

The application's `main.go` file is straightforward, if you are familiar with Go:

```go
package main

import (
	"net/http"
	"os"

	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
)

func main() {

	e := echo.New()

	e.Use(middleware.Logger())
	e.Use(middleware.Recover())

	e.GET("/", func(c echo.Context) error {
		return c.HTML(http.StatusOK, "Hello, Docker! <3")
	})

	e.GET("/health", func(c echo.Context) error {
		return c.JSON(http.StatusOK, struct{ Status string }{Status: "OK"})
	})

	httpPort := os.Getenv("PORT")
	if httpPort == "" {
		httpPort = "8080"
	}

	e.Logger.Fatal(e.Start(":" + httpPort))
}

// Simple implementation of an integer minimum
// Adapted from: https://gobyexample.com/testing-and-benchmarking
func IntMin(a, b int) int {
	if a < b {
		return a
	}
	return b
}
```

## [Create a Dockerfile for the application](#create-a-dockerfile-for-the-application)

To build a container image with Docker, a `Dockerfile` with build instructions is required.

Begin your `Dockerfile` with the (optional) parser directive line that instructs BuildKit to interpret your file according to the grammar rules for the specified version of the syntax.

You then tell Docker what base image you would like to use for your application:

```dockerfile
# syntax=docker/dockerfile:1

FROM golang:1.19
```

Docker images can be inherited from other images. Therefore, instead of creating your own base image from scratch, you can use the official Go image that already has all necessary tools and libraries to compile and run a Go application.

> Note
>
> If you are curious about creating your own base images, you can check out the following section of this guide: [creating base images](https://docs.docker.com/build/building/base-images/#create-a-base-image). Note, however, that this isn't necessary to continue with your task at hand.

Now that you have defined the base image for your upcoming container image, you can begin building on top of it.

To make things easier when running the rest of your commands, create a directory inside the image that you're building. This also instructs Docker to use this directory as the default destination for all subsequent commands. This way you don't have to type out full file paths in the `Dockerfile`, the relative paths will be based on this directory.

```dockerfile
WORKDIR /app
```

Usually the very first thing you do once you’ve downloaded a project written in Go is to install the modules necessary to compile it. Note, that the base image has the toolchain already, but your source code isn't in it yet.

So before you can run `go mod download` inside your image, you need to get your `go.mod` and `go.sum` files copied into it. Use the `COPY` command to do this.

In its simplest form, the `COPY` command takes two parameters. The first parameter tells Docker what files you want to copy into the image. The last parameter tells Docker where you want that file to be copied to.

Copy the `go.mod` and `go.sum` file into your project directory `/app` which, owing to your use of `WORKDIR`, is the current directory (`./`) inside the image. Unlike some modern shells that appear to be indifferent to the use of trailing slash (`/`), and can figure out what the user meant (most of the time), Docker's `COPY` command is quite sensitive in its interpretation of the trailing slash.

```dockerfile
COPY go.mod go.sum ./
```

> Note
>
> If you'd like to familiarize yourself with the trailing slash treatment by the `COPY` command, see [Dockerfile reference](https://docs.docker.com/reference/dockerfile/#copy). This trailing slash can cause issues in more ways than you can imagine.

Now that you have the module files inside the Docker image that you are building, you can use the `RUN` command to run the command `go mod download` there as well. This works exactly the same as if you were running `go` locally on your machine, but this time these Go modules will be installed into a directory inside the image.

```dockerfile
RUN go mod download
```

At this point, you have a Go toolchain version 1.19.x and all your Go dependencies installed inside the image.

The next thing you need to do is to copy your source code into the image. You’ll use the `COPY` command just like you did with your module files before.

```dockerfile
COPY *.go ./
```

This `COPY` command uses a wildcard to copy all files with `.go` extension located in the current directory on the host (the directory where the `Dockerfile` is located) into the current directory inside the image.

Now, to compile your application, use the familiar `RUN` command:

```dockerfile
RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping
```

This should be familiar. The result of that command will be a static application binary named `docker-gs-ping` and located in the root of the filesystem of the image that you are building. You could have put the binary into any other place you desire inside that image, the root directory has no special meaning in this regard. It's convenient to use it to keep the file paths short for improved readability.

Now, all that is left to do is to tell Docker what command to run when your image is used to start a container.

You do this with the `CMD` command:

```dockerfile
CMD ["/docker-gs-ping"]
```

Here's the complete `Dockerfile`:

```dockerfile
# syntax=docker/dockerfile:1

FROM golang:1.19

# Set destination for COPY
WORKDIR /app

# Download Go modules
COPY go.mod go.sum ./
RUN go mod download

# Copy the source code. Note the slash at the end, as explained in
# https://docs.docker.com/reference/dockerfile/#copy
COPY *.go ./

# Build
RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping

# Optional:
# To bind to a TCP port, runtime parameters must be supplied to the docker command.
# But we can document in the Dockerfile what ports
# the application is going to listen on by default.
# https://docs.docker.com/reference/dockerfile/#expose
EXPOSE 8080

# Run
CMD ["/docker-gs-ping"]
```

The `Dockerfile` may also contain comments. They always begin with a `#` symbol, and must be at the beginning of a line. Comments are there for your convenience to allow documenting your `Dockerfile`.

There is also a concept of Dockerfile directives, such as the `syntax` directive you added. The directives must always be at the very top of the `Dockerfile`, so when adding comments, make sure that the comments follow after any directives that you may have used:

```dockerfile
# syntax=docker/dockerfile:1
# A sample microservice in Go packaged into a container image.

FROM golang:1.19

# ...
```

## [Build the image](#build-the-image)

Now that you've created your `Dockerfile`, build an image from it. The `docker build` command creates Docker images from the `Dockerfile` and a context. A build context is the set of files located in the specified path or URL. The Docker build process can access any of the files located in the context.

The build command optionally takes a `--tag` flag. This flag is used to label the image with a string value, which is easy for humans to read and recognize. If you don't pass a `--tag`, Docker will use `latest` as the default value.

Build your first Docker image.

```console
$ docker build --tag docker-gs-ping .
```

The build process will print some diagnostic messages as it goes through the build steps. The following is an example of what these messages may look like.

```console
[+] Building 2.2s (15/15) FINISHED
 => [internal] load build definition from Dockerfile                                                                                       0.0s
 => => transferring dockerfile: 701B                                                                                                       0.0s
 => [internal] load .dockerignore                                                                                                          0.0s
 => => transferring context: 2B                                                                                                            0.0s
 => resolve image config for docker.io/docker/dockerfile:1                                                                                 1.1s
 => CACHED docker-image://docker.io/docker/dockerfile:1@sha256:39b85bbfa7536a5feceb7372a0817649ecb2724562a38360f4d6a7782a409b14            0.0s
 => [internal] load build definition from Dockerfile                                                                                       0.0s
 => [internal] load .dockerignore                                                                                                          0.0s
 => [internal] load metadata for docker.io/library/golang:1.19                                                                             0.7s
 => [1/6] FROM docker.io/library/golang:1.19@sha256:5d947843dde82ba1df5ac1b2ebb70b203d106f0423bf5183df3dc96f6bc5a705                       0.0s
 => [internal] load build context                                                                                                          0.0s
 => => transferring context: 6.08kB                                                                                                        0.0s
 => CACHED [2/6] WORKDIR /app                                                                                                              0.0s
 => CACHED [3/6] COPY go.mod go.sum ./                                                                                                     0.0s
 => CACHED [4/6] RUN go mod download                                                                                                       0.0s
 => CACHED [5/6] COPY *.go ./                                                                                                              0.0s
 => CACHED [6/6] RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping                                                                  0.0s
 => exporting to image                                                                                                                     0.0s
 => => exporting layers                                                                                                                    0.0s
 => => writing image sha256:ede8ff889a0d9bc33f7a8da0673763c887a258eb53837dd52445cdca7b7df7e3                                               0.0s
 => => naming to docker.io/library/docker-gs-ping                                                                                          0.0s
```

Your exact output will vary, but provided there aren't any errors, you should see the word `FINISHED` in the first line of output. This means Docker has successfully built your image named `docker-gs-ping`.

## [View local images](#view-local-images)

To see the list of images you have on your local machine, you have two options. One is to use the CLI and the other is to use [Docker Desktop](https://docs.docker.com/desktop/). Since you're working in the terminal, take a look at listing images with the CLI.

To list images, run the `docker image ls`command (or the `docker images` shorthand):

```console
$ docker image ls

REPOSITORY                       TAG       IMAGE ID       CREATED         SIZE
docker-gs-ping                   latest    7f153fbcc0a8   2 minutes ago   1.11GB
...
```

Your exact output may vary, but you should see the `docker-gs-ping` image with the `latest` tag. Because you didn't specify a custom tag when you built your image, Docker assumed that the tag would be `latest`, which is a special value.

## [Tag images](#tag-images)

An image name is made up of slash-separated name components. Name components may contain lowercase letters, digits, and separators. A separator is defined as a period, one or two underscores, or one or more dashes. A name component may not start or end with a separator.

An image is made up of a manifest and a list of layers. In simple terms, a tag points to a combination of these artifacts. You can have multiple tags for the image and, in fact, most images have multiple tags. Create a second tag for the image you built and take a look at its layers.

Use the `docker image tag` (or `docker tag` shorthand) command to create a new tag for your image. This command takes two arguments; the first argument is the source image, and the second is the new tag to create. The following command creates a new `docker-gs-ping:v1.0` tag for the `docker-gs-ping:latest` you built:

```console
$ docker image tag docker-gs-ping:latest docker-gs-ping:v1.0
```

The Docker `tag` command creates a new tag for the image. It doesn't create a new image. The tag points to the same image and is another way to reference the image.

Now run the `docker image ls` command again to see the updated list of local images:

```console
$ docker image ls

REPOSITORY                       TAG       IMAGE ID       CREATED         SIZE
docker-gs-ping                   latest    7f153fbcc0a8   6 minutes ago   1.11GB
docker-gs-ping                   v1.0      7f153fbcc0a8   6 minutes ago   1.11GB
...
```

You can see that you have two images that start with `docker-gs-ping`. You know they're the same image because if you look at the `IMAGE ID` column, you can see that the values are the same for the two images. This value is a unique identifier Docker uses internally to identify the image.

Remove the tag that you just created. To do this, you’ll use the `docker image rm` command, or the shorthand `docker rmi` (which stands for "remove image"):

```console
$ docker image rm docker-gs-ping:v1.0
Untagged: docker-gs-ping:v1.0
```

Notice that the response from Docker tells you that the image hasn't been removed but only untagged.

Verify this by running the following command:

```console
$ docker image ls
```

You will see that the tag `v1.0` is no longer in the list of images kept by your Docker instance.

```text
REPOSITORY                       TAG       IMAGE ID       CREATED         SIZE
docker-gs-ping                   latest    7f153fbcc0a8   7 minutes ago   1.11GB
...
```

The tag `v1.0` has been removed but you still have the `docker-gs-ping:latest` tag available on your machine, so the image is there.

## [Multi-stage builds](#multi-stage-builds)

You may have noticed that your `docker-gs-ping` image weighs in at over a gigabyte, which is a lot for a tiny compiled Go application. You may also be wondering what happened to the full suite of Go tools, including the compiler, after you had built your image.

The answer is that the full toolchain is still there, in the container image. Not only this is inconvenient because of the large file size, but it may also present a security risk when the container is deployed.

These two issues can be solved by using [multi-stage builds](https://docs.docker.com/build/building/multi-stage/).

In a nutshell, a multi-stage build can carry over the artifacts from one build stage into another, and every build stage can be instantiated from a different base image.

Thus, in the following example, you are going to use a full-scale official Go image to build your application. Then you'll copy the application binary into another image whose base is very lean and doesn't include the Go toolchain or other optional components.

The `Dockerfile.multistage` in the sample application's repository has the following content:

```dockerfile
# syntax=docker/dockerfile:1

# Build the application from source
FROM golang:1.19 AS build-stage

WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY *.go ./

RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping

# Run the tests in the container
FROM build-stage AS run-test-stage
RUN go test -v ./...

# Deploy the application binary into a lean image
FROM gcr.io/distroless/base-debian11 AS build-release-stage

WORKDIR /

COPY --from=build-stage /docker-gs-ping /docker-gs-ping

EXPOSE 8080

USER nonroot:nonroot

ENTRYPOINT ["/docker-gs-ping"]
```

Since you have two Dockerfiles now, you have to tell Docker what Dockerfile you'd like to use to build the image. Tag the new image with `multistage`. This tag (like any other, apart from `latest`) has no special meaning for Docker, it's something you chose.

```console
$ docker build -t docker-gs-ping:multistage -f Dockerfile.multistage .
```

Comparing the sizes of `docker-gs-ping:multistage` and `docker-gs-ping:latest` you see a few orders-of-magnitude difference.

```console
$ docker image ls
REPOSITORY       TAG          IMAGE ID       CREATED              SIZE
docker-gs-ping   multistage   e3fdde09f172   About a minute ago   28.1MB
docker-gs-ping   latest       336a3f164d0f   About an hour ago    1.11GB
```

This is so because the ["distroless"](https://github.com/GoogleContainerTools/distroless) base image that you have used in the second stage of the build is very barebones and is designed for lean deployments of static binaries.

There's much more to multi-stage builds, including the possibility of multi-architecture builds, so feel free to check out [multi-stage builds](https://docs.docker.com/build/building/multi-stage/). This is, however, not essential for your progress here.

## [Next steps](#next-steps)

In this module, you met your example application and built and container image for it.

In the next module, you’ll take a look at how to run your image as a container.

[Run your Go image as a container »](https://docs.docker.com/guides/golang/run-containers/)

----
url: https://docs.docker.com/accounts/general-faqs/
----

# FAQs on Docker accounts

***

Table of contents

***

### [What is a Docker ID?](#what-is-a-docker-id)

A Docker ID is a username for your Docker account that lets you access Docker products. To create a Docker ID you need one of the following:

* An email address
* A social account
* A GitHub account

Your Docker ID must be between 4 and 30 characters long, and can only contain numbers and lowercase letters. You can't use any special characters or spaces.

For more information, see [Create a Docker ID](https://docs.docker.com/accounts/create-account/).

### [Can I change my Docker ID?](#can-i-change-my-docker-id)

No. You can't change your Docker ID once it's created. If you need a different Docker ID, you must create a new Docker account with a new Docker ID.

Docker IDs can't be reused after deactivation.

### [What if my Docker ID is taken?](#what-if-my-docker-id-is-taken)

All Docker IDs are first-come, first-served except for companies that have a U.S. Trademark on a username.

If you have a trademark for your namespace, [Docker Support](https://hub.docker.com/support/contact/) can retrieve the Docker ID for you.

### [What's an organization name or namespace?](#whats-an-organization-name-or-namespace)

The organization name, sometimes referred to as the organization namespace or the organization ID, is the unique identifier of a Docker organization. The organization name can't be the same as an existing Docker ID.

----
url: https://docs.docker.com/reference/cli/docker/mcp/secret/ls/
----

# docker mcp secret ls

***

| Description | List all secrets from the local OS Keychain as well as any active Secrets Engine provider |
| ----------- | ----------------------------------------------------------------------------------------- |
| Usage       | `docker mcp secret ls`                                                                    |

## [Description](#description)

List all secrets from the local OS Keychain as well as any active Secrets Engine provider

## [Options](#options)

| Option   | Default | Description    |
| -------- | ------- | -------------- |
| `--json` |         | Print as JSON. |

----
url: https://docs.docker.com/reference/cli/docker/pass/set/
----

# docker pass set

***

| Description | Set a secret                         |
| ----------- | ------------------------------------ |
| Usage       | `docker pass set id[=value] [flags]` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Stores a secret in the local OS keychain. The secret value can be provided inline (NAME=VALUE) or piped via STDIN.

## [Options](#options)

| Option       | Default | Description                                   |
| ------------ | ------- | --------------------------------------------- |
| `--metadata` |         | Non-sensitive key=value metadata (repeatable) |

## [Examples](#examples)

### [Set a secret:](#set-a-secret)

docker pass set POSTGRES\_PASSWORD=my-secret-password

### [Or pass the secret via STDIN:](#or-pass-the-secret-via-stdin)

echo my-secret-password > pwd.txt cat pwd.txt | docker pass set POSTGRES\_PASSWORD

### [Set a secret with metadata:](#set-a-secret-with-metadata)

docker pass set POSTGRES\_PASSWORD=my-secret-password --metadata owner=alice --metadata expiry=2027-03-01

### [Or pass a JSON payload with secret and metadata via STDIN:](#or-pass-a-json-payload-with-secret-and-metadata-via-stdin)

echo '{"secret":"my-secret-password","metadata":{"owner":"alice"}}' | docker pass set POSTGRES\_PASSWORD

----
url: https://docs.docker.com/reference/cli/docker/scout/attestation/add/
----

# docker scout attestation add

***

| Description                                                               | Add attestation to image                                |
| ------------------------------------------------------------------------- | ------------------------------------------------------- |
| Usage                                                                     | `docker scout attestation add OPTIONS IMAGE [IMAGE...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker scout attest add`                               |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

The docker scout attestation add command adds attestations to images.

## [Options](#options)

| Option                  | Default                     | Description                                  |
| ----------------------- | --------------------------- | -------------------------------------------- |
| `--file`                |                             | File location of attestations to attach      |
| `--org`                 |                             | Namespace of the Docker organization         |
| `--predicate-type`      |                             | Predicate-type for attestations              |
| `--referrer`            |                             | Use OCI referrer API for pushing attestation |
| `--referrer-repository` | `registry.scout.docker.com` | Repository to push referrer to               |

----
url: https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/
----

# Troubleshoot topics for Docker Desktop

***

Table of contents

***

> Tip
>
> If you do not find a solution in troubleshooting, browse the GitHub repositories or [create a new issue](https://github.com/docker/desktop-feedback).

## [Topics for all platforms](#topics-for-all-platforms)

### [Certificates not set up correctly](#certificates-not-set-up-correctly)

#### [Error message](#error-message)

When attempting to pull from a registry using `docker run`, you may encounter the following error:

```console
Error response from daemon: Get http://192.168.203.139:5858/v2/: malformed HTTP response "\x15\x03\x01\x00\x02\x02"
```

Additionally, logs from the registry may show:

```console
2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52882: tls: client didn't provide a certificate
2017/06/20 18:15:30 http: TLS handshake error from 192.168.203.139:52883: tls: first record does not look like a TLS handshake
```

#### [Possible causes](#possible-causes)

* Docker Desktop ignores certificates listed under insecure registries.
* Client certificates are not sent to insecure registries, causing handshake failures.

#### [Solution](#solution)

* Ensure that your registry is properly configured with valid SSL certificates.
* If your registry is self-signed, configure Docker to trust the certificate by adding it to Docker’s certificates directory (/etc/docker/certs.d/ on Linux).
* If the issue persists, check your Docker daemon configuration and enable TLS authentication.

### [Docker Desktop's UI appears green, distorted, or has visual artifacts](#docker-desktops-ui-appears-green-distorted-or-has-visual-artifacts)

#### [Cause](#cause)

Docker Desktop uses hardware-accelerated graphics by default, which may cause problems for some GPUs.

#### [Solution](#solution-1)

Disable hardware acceleration:

1. Edit Docker Desktop's `settings-store.json` file. You can find this file at:

   * Mac: `~/Library/Group Containers/group.com.docker/settings-store.json`
   * Windows: `C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json`
   * Linux: `~/.docker/desktop/settings-store.json.`

2. Add the following entry:

   ```JSON
   $ "disableHardwareAcceleration": true
   ```

3. Save the file and restart Docker Desktop.

### [Using mounted volumes and getting runtime errors indicating an application file is not found, access to a volume mount is denied, or a service cannot start](#using-mounted-volumes-and-getting-runtime-errors-indicating-an-application-file-is-not-found-access-to-a-volume-mount-is-denied-or-a-service-cannot-start)

#### [Cause](#cause-1)

If your project directory is located outside your home directory (`/home/<user>`), Docker Desktop requires file sharing permissions to access it.

#### [Solution](#solution-2)

Enable file sharing in Docker Desktop for Mac and Linux:

1. Navigate to **Settings**, select **Resources** and then **File sharing**.
2. Add the drive or folder that contains the Dockerfile and volume mount paths.

Enable file sharing in Docker Desktop for Windows:

1. From **Settings**, select **Shared Folders**.
2. Share the folder that contains the Dockerfile and volume mount paths.

### [`port already allocated` errors](#port-already-allocated-errors)

#### [Error message](#error-message-1)

When starting a container, you may see an error like:

```text
Bind for 0.0.0.0:8080 failed: port is already allocated
```

Or

```text
listen tcp:0.0.0.0:8080: bind: address is already in use
```

#### [Cause](#cause-2)

* Another application on your system is already using the specified port.
* A previously running container was not stopped properly and is still bound to the port.

#### [Solution](#solution-3)

To discover the identity of this software, either:

* Use the `resmon.exe` GUI, select **Network** and then **Listening Ports**
* In PowerShell, use `netstat -aon | find /i "listening "` to discover the PID of the process currently using the port (the PID is the number in the rightmost column).

Then, decide whether to shut the other process down, or to use a different port in your Docker app.

## [Topics for Linux and Mac](#topics-for-linux-and-mac)

### [Docker Desktop fails to start on Mac or Linux platforms](#docker-desktop-fails-to-start-on-mac-or-linux-platforms)

#### [Error message](#error-message-2)

Docker fails to start due to Unix domain socket path length limitations:

```console
[vpnkit-bridge][F] listen unix HOME/Library/Containers/com.docker.docker/Data/http-proxy-control.sock: bind: invalid argument
```

```console
[com.docker.backend][E] listen(vsock:4099) failed: listen unix HOME/Library/Containers/com.docker.docker/Data/vms/0/00000002.00001003: bind: invalid argument
```

#### [Cause](#cause-3)

On Mac and Linux, Docker Desktop creates Unix domain sockets used for inter-process communication. These sockets are created under the user's home directory.

Unix domain sockets have a maximum path length:

* 104 characters on Mac
* 108 characters on Linux

If your home directory path is too long, Docker Desktop fails to create necessary sockets.

#### [Solution](#solution-4)

Ensure your username is short enough to keep paths within the allowed limit:

* Mac: Username should be ≤ 33 characters
* Linux: Username should be ≤ 55 characters

## [Topics for Mac](#topics-for-mac)

### [Upgrade requires administrator privileges](#upgrade-requires-administrator-privileges)

#### [Cause](#cause-4)

On macOS, users without administrator privileges cannot perform in-app upgrades from the Docker Desktop Dashboard.

#### [Solution](#solution-5)

> Important
>
> Do not uninstall the current version before upgrading. Doing so deletes all local Docker containers, images, and volumes.

To upgrade Docker Desktop:

* Ask an administrator to install the newer version over the existing one.
* Use the \[]`--user` install flag]\(/manuals/desktop/setup/install/mac-install.md#security-and-access) if appropriate for your setup.

### [Persistent notification telling me an application has changed my Desktop configurations](#persistent-notification-telling-me-an-application-has-changed-my-desktop-configurations)

#### [Cause](#cause-5)

You receive this notification because the Configuration integrity check feature has detected that a third-party application has altered your Docker Desktop configuration. This usually happens due to incorrect or missing symlinks. The notification ensures you are aware of these changes so you can review and repair any potential issues to maintain system reliability.

Opening the notification presents a pop-up window which provides detailed information about the detected integrity issues.

#### [Solution](#solution-6)

If you choose to ignore the notification, it will be shown again only at the next Docker Desktop startup. If you choose to repair your configuration, you won't be prompted again.

If you want to switch off Configuration integrity check notifications, navigate to Docker Desktop's settings and in the **General** tab, clear the **Automatically check configuration** setting.

### [`com.docker.vmnetd` is still running after I quit the app](#comdockervmnetd-is-still-running-after-i-quit-the-app)

The privileged helper process `com.docker.vmnetd` is started by `launchd` and runs in the background. The process does not consume any resources unless `Docker.app` connects to it, so it's safe to ignore.

### [Incompatible CPU detected](#incompatible-cpu-detected)

#### [Cause](#cause-6)

Docker Desktop requires a processor (CPU) that supports virtualization and, more specifically, the [Apple Hypervisor framework](https://developer.apple.com/library/mac/documentation/DriversKernelHardware/Reference/Hypervisor/).

#### [Solution](#solution-7)

Check that:

* You've installed the correct Docker Desktop for your architecture

* Your Mac supports Apple's Hypervisor framework. To check if your Mac supports the Hypervisor framework, run the following command in a terminal window.

  ```console
  $ sysctl kern.hv_support
  ```

  If your Mac supports the Hypervisor Framework, the command prints `kern.hv_support: 1`.

  If not, the command prints `kern.hv_support: 0`.

See also, [Hypervisor Framework Reference](https://developer.apple.com/library/mac/documentation/DriversKernelHardware/Reference/Hypervisor/) in the Apple documentation, and Docker Desktop [Mac system requirements](https://docs.docker.com/desktop/setup/install/mac-install/#system-requirements).

## [Topics for Windows](#topics-for-windows)

### [Docker Desktop fails to start when anti-virus software is installed](#docker-desktop-fails-to-start-when-anti-virus-software-is-installed)

#### [Cause](#cause-7)

Some anti-virus software may be incompatible with Hyper-V and Microsoft Windows builds. The conflict typically occurs after a Windows update and manifests as an error response from the Docker daemon and a Docker Desktop start failure.

#### [Solution](#solution-8)

For a temporary workaround, uninstall the anti-virus software, or add Docker to the exclusions/exceptions in your antivirus software.

### [Permissions errors on data directories for shared volumes](#permissions-errors-on-data-directories-for-shared-volumes)

#### [Cause](#cause-8)

When sharing files from Windows, Docker Desktop sets permissions on [shared volumes](https://docs.docker.com/desktop/settings-and-maintenance/settings/#file-sharing) to a default value of [0777](https://chmodcommand.com/chmod-0777/) (`read`, `write`, `execute` permissions for `user` and for `group`).

The default permissions on shared volumes are not configurable.

#### [Solution](#solution-9)

If you are working with applications that require different permissions, either:

* Use non-host-mounted volumes
* Find a way to make the applications work with the default file permissions

### [Unexpected syntax errors, use Unix style line endings for files in containers](#unexpected-syntax-errors-use-unix-style-line-endings-for-files-in-containers)

#### [Cause](#cause-9)

Docker containers expect Unix-style line `\n` endings, not Windows style: `\r\n`. This includes files referenced at the command line for builds and in RUN commands in Docker files.

Keep this in mind when authoring files such as shell scripts using Windows tools, where the default is likely to be Windows style line endings. These commands ultimately get passed to Unix commands inside a Unix based container (for example, a shell script passed to `/bin/sh`). If Windows style line endings are used, `docker run` fails with syntax errors.

#### [Solution](#solution-10)

* Convert files to Unix-style line endings using:

  ```console
  $ dos2unix script.sh
  ```

* In VS Code, set line endings to `LF` (Unix) instead of `CRLF` (Windows).

### [Path conversion errors on Windows](#path-conversion-errors-on-windows)

#### [Cause](#cause-10)

Unlike Linux, Windows requires explicit path conversion for volume mounting.

On Linux, the system takes care of mounting a path to another path. For example, when you run the following command on Linux:

```console
$ docker run --rm -ti -v /home/user/work:/work alpine
```

It adds a `/work` directory to the target container to mirror the specified path.

#### [Solution](#solution-11)

Update the source path. For example, if you are using the legacy Windows shell (`cmd.exe`), you can use the following command:

```console
$ docker run --rm -ti -v C:\Users\user\work:/work alpine
```

This starts the container and ensures the volume becomes usable. This is possible because Docker Desktop detects the Windows-style path and provides the appropriate conversion to mount the directory.

Docker Desktop also allows you to use Unix-style path to the appropriate format. For example:

```console
$ docker run --rm -ti -v /c/Users/user/work:/work alpine ls /work
```

### [Docker commands failing in Git Bash](#docker-commands-failing-in-git-bash)

#### [Error message](#error-message-3)

```console
$ docker run --rm -ti -v C:\Users\user\work:/work alpine
docker: Error response from daemon: mkdir C:UsersUserwork: Access is denied.
```

```console
$ docker run --rm -ti -v $(pwd):/work alpine
docker: Error response from daemon: OCI runtime create failed: invalid mount {Destination:\Program Files\Git\work Type:bind Source:/run/desktop/mnt/host/c/Users/user/work;C Options:[rbind rprivate]}: mount destination \Program Files\Git\work not absolute: unknown.
```

#### [Cause](#cause-11)

Git Bash (or MSYS) provides a Unix-like environment on Windows. These tools apply their own preprocessing on the command line.

This affects `$(pwd)`, colon-separated paths, and tilde (`~`)

Also, the `\` character has a special meaning in Git Bash.

#### [Solution](#solution-12)

* Disable Git Bash path conversion temporarily. For example, run the command with MSYS path conversion disable:
  ```console
  $ MSYS_NO_PATHCONV=1 docker run --rm -ti -v $(pwd):/work alpine
  ```

* Use proper path formatting:

  * Use double forward and backslashes (`\\` `//`) instead of single (`\` `/`).
  * If referencing `$(pwd)`, add an extra `/`:

Portability of the scripts is not affected as Linux treats multiple `/` as a single entry.

### [Docker Desktop fails due to Virtualization not working](#docker-desktop-fails-due-to-virtualization-not-working)

#### [Error message](#error-message-4)

A typical error message is "Docker Desktop - Unexpected WSL error" mentioning the error code `Wsl/Service/RegisterDistro/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED`. Manually executing `wsl` commands also fails with the same error code.

#### [Cause](#cause-12)

* Virtualization settings are disabled in the BIOS.
* Windows Hyper-V or WSL 2 components are missing.

Note some third-party software such as Android emulators will disable Hyper-V on install.

#### [Solutions](#solutions)

Your machine must have the following features for Docker Desktop to function correctly:

##### [WSL 2 and Windows Home](#wsl-2-and-windows-home)

1. Virtual Machine Platform
2. [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
3. [Virtualization enabled in the BIOS](https://support.microsoft.com/en-gb/windows/enable-virtualization-on-windows-c5578302-6e43-4b4b-a449-8ced115f58e1) Note that many Windows devices already have virtualization enabled, so this may not apply.
4. Hypervisor enabled at Windows startup

It must be possible to run WSL 2 commands without error, for example:

```console
PS C:\users\> wsl -l -v
  NAME              STATE           VERSION
* Ubuntu            Running         2
  docker-desktop    Stopped         2
PS C:\users\> wsl -d docker-desktop echo WSL 2 is working
WSL 2 is working
```

If the features are enabled but the commands are not working, first check [Virtualization is turned on](#virtualization-must-be-turned-on) then [enable the Hypervisor at Windows startup](#hypervisor-enabled-at-windows-startup) if required. If running Docker Desktop in a Virtual Machine, ensure [the hypervisor has nested virtualization enabled](#turn-on-nested-virtualization).

##### [Hyper-V](#hyper-v)

On Windows 10 Pro or Enterprise, you can also use Hyper-V with the following features enabled:

1. [Hyper-V](https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/hyper-v-technology-overview) installed and working
2. [Virtualization enabled in the BIOS](https://support.microsoft.com/en-gb/windows/enable-virtualization-on-windows-c5578302-6e43-4b4b-a449-8ced115f58e1) Note that many Windows devices already have virtualization enabled, so this may not apply.
3. Hypervisor enabled at Windows startup

Docker Desktop requires Hyper-V as well as the Hyper-V Module for Windows PowerShell to be installed and enabled. The Docker Desktop installer enables it for you.

Docker Desktop also needs two CPU hardware features to use Hyper-V: Virtualization and Second Level Address Translation (SLAT), which is also called Rapid Virtualization Indexing (RVI). On some systems, Virtualization must be enabled in the BIOS. The steps required are vendor-specific, but typically the BIOS option is called `Virtualization Technology (VTx)` or something similar. Run the command `systeminfo` to check all required Hyper-V features. See [Pre-requisites for Hyper-V on Windows 10](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/reference/hyper-v-requirements) for more details.

To install Hyper-V manually, see [Install Hyper-V on Windows 10](https://msdn.microsoft.com/en-us/virtualization/hyperv_on_windows/quick_start/walkthrough_install). A reboot is *required* after installation. If you install Hyper-V without rebooting, Docker Desktop does not work correctly.

From the start menu, type **Turn Windows features on or off** and press enter. In the subsequent screen, verify that Hyper-V is enabled.

##### [Virtualization must be turned on](#virtualization-must-be-turned-on)

In addition to [Hyper-V](#hyper-v) or [WSL 2](https://docs.docker.com/desktop/features/wsl/), virtualization must be turned on. Check the Performance tab on the Task Manager. Alternatively, you can type `systeminfo` into your terminal. If you see `Hyper-V Requirements: A hypervisor has been detected. Features required for Hyper-V will not be displayed`, then virtualization is enabled.

If you manually uninstall Hyper-V, WSL 2 or turn off virtualization, Docker Desktop cannot start.

To turn on nested virtualization, see [Run Docker Desktop for Windows in a VM or VDI environment](https://docs.docker.com/desktop/setup/vm-vdi/#turn-on-nested-virtualization).

##### [Hypervisor enabled at Windows startup](#hypervisor-enabled-at-windows-startup)

If you have completed the previous steps and are still experiencing Docker Desktop startup issues, this could be because the Hypervisor is installed, but not launched during Windows startup. Some tools (such as older versions of Virtual Box) and video game installers turn off hypervisor on boot. To turn it back on:

1. Open an administrative console prompt.
2. Run `bcdedit /set hypervisorlaunchtype auto`.
3. Restart Windows.

You can also refer to the [Microsoft TechNet article](https://social.technet.microsoft.com/Forums/en-US/ee5b1d6b-09e2-49f3-a52c-820aafc316f9/hyperv-doesnt-work-after-upgrade-to-windows-10-1809?forum=win10itprovirt) on Code flow guard (CFG) settings.

##### [Turn on nested virtualization](#turn-on-nested-virtualization)

If you are using Hyper-V and you get the following error message when running Docker Desktop in a VDI environment:

```console
The Virtual Machine Management Service failed to start the virtual machine 'DockerDesktopVM' because one of the Hyper-V components is not running
```

Try [enabling nested virtualization](https://docs.docker.com/desktop/setup/vm-vdi/#turn-on-nested-virtualization).

### [Docker Desktop with Windows Containers fails with "The media is write protected""](#docker-desktop-with-windows-containers-fails-with-the-media-is-write-protected)

#### [Error message](#error-message-5)

`FSCTL_EXTEND_VOLUME \\?\Volume{GUID}: The media is write protected`

#### [Cause](#cause-13)

If you're encountering failures when running Docker Desktop with Windows Containers, it might be due to a specific Windows configuration policy: FDVDenyWriteAccess.

This policy, when enabled, causes Windows to mount all fixed drives not encrypted by BitLocker-encrypted as read-only. This also affects virtual machine volumes and as a result, Docker Desktop may not be able to start or run containers correctly because it requires read-write access to these volumes.

FDVDenyWriteAccess is a Windows Group Policy setting that, when enabled, prevents write access to fixed data drives that are not protected by BitLocker. This is often used in security-conscious environments but can interfere with development tools like Docker. In the Windows registry it can be found at `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Policies\Microsoft\FVE\FDVDenyWriteAccess`.

#### [Solutions](#solutions-1)

Docker Desktop does not support running Windows Containers on systems where FDVDenyWriteAccess is enabled. This setting interferes with the ability of Docker to mount volumes correctly, which is critical for container functionality.

To use Docker Desktop with Windows Containers, ensure that FDVDenyWriteAccess is disabled. You can check and change this setting in the registry or through Group Policy Editor (`gpedit.msc`) under:

**Computer Configuration** > **Administrative Templates** > **Windows Components** > **BitLocker Drive Encryption** > **Fixed Data Drives** > **Deny write access to fixed drives not protected by BitLocker**

> Note
>
> Modifying Group Policy settings may require administrator privileges and should comply with your organization's IT policies. If the setting gets reset after some time this usually means that it was overridden by the centralized configuration of your IT department. Talk to them before making any changes.

### [`Docker Desktop Access Denied` error message when starting Docker Desktop](#docker-desktop-access-denied-error-message-when-starting-docker-desktop)

#### [Error message](#error-message-6)

When starting Docker Desktop, the following error appears:

```text
Docker Desktop - Access Denied
```

#### [Cause](#cause-14)

The user is not part of the `docker-users` group, which is required for permissions.

#### [Solution](#solution-13)

If your admin account is different to your user account, add it:

1. Run **Computer Management** as an administrator.
2. Navigate to **Local Users and Groups** > **Groups** > **docker-users**.
3. Right-click to add the user to the group.
4. Sign out and sign back in for the changes to take effect

----
url: https://docs.docker.com/security/faqs/networking-and-vms/
----

# Network and VM FAQs

***

Table of contents

***

## [How can I limit container internet access?](#how-can-i-limit-container-internet-access)

Docker Desktop doesn't have a built-in mechanism for this, but you can use process-level firewalls on the host. Apply rules to the `com.docker.vpnkit` user-space process to control where it can connect (DNS allowlists, packet filters) and which ports/protocols it can use.

For enterprise environments, consider [Air-gapped containers](https://docs.docker.com/enterprise/security/hardened-desktop/air-gapped-containers/) which provide network access controls for containers.

## [Can I apply firewall rules to container network traffic?](#can-i-apply-firewall-rules-to-container-network-traffic)

Yes. Docker Desktop uses a user-space process (`com.docker.vpnkit`) for network connectivity, which inherits constraints like firewall rules, VPN settings, and HTTP proxy properties from the user that launched it.

## [Does Docker Desktop for Windows with Hyper-V allow users to create other VMs?](#does-docker-desktop-for-windows-with-hyper-v-allow-users-to-create-other-vms)

No. The `DockerDesktopVM` name is hard-coded in the service, so you cannot use Docker Desktop to create or manipulate other virtual machines.

## [How does Docker Desktop achieve network isolation with Hyper-V and WSL 2?](#how-does-docker-desktop-achieve-network-isolation-with-hyper-v-and-wsl-2)

Docker Desktop uses the same VM processes for both WSL 2 (in the `docker-desktop` distribution) and Hyper-V (in `DockerDesktopVM`). Host/VM communication uses `AF_VSOCK` hypervisor sockets (shared memory) rather than network switches or interfaces. All host networking is performed using standard TCP/IP sockets from the `com.docker.vpnkit.exe` and `com.docker.backend.exe` processes.

For more information, see [How Docker Desktop networking works under the hood](https://www.docker.com/blog/how-docker-desktop-networking-works-under-the-hood/).

----
url: https://docs.docker.com/security/access-tokens/
----

# Personal access tokens

***

Table of contents

***

Personal access tokens (PATs) provide a secure alternative to passwords for Docker CLI authentication. Use PATs to authenticate automated systems, CI/CD pipelines, and development tools without exposing your Docker Hub password.

## [Key benefits](#key-benefits)

PATs offer significant security advantages over password authentication:

* Enhanced security: Investigate token usage, disable suspicious tokens, and prevent administrative actions that could compromise your account if your system is compromised.
* Better automation: Issue multiple tokens for different integrations, each with specific permissions, and revoke them independently when no longer needed.
* Two-factor authentication compatibility: Required when you have two-factor authentication turned on, providing secure CLI access without bypassing 2FA protection.
* Usage tracking: Monitor when and how tokens are used to identify potential security issues or unused automation.

## [Who should use personal access tokens?](#who-should-use-personal-access-tokens)

Use PATs for these common scenarios:

* Development workflows: Authenticate Docker CLI during local development
* CI/CD pipelines: Automate image builds and deployments in continuous integration systems
* Automation scripts: Push and pull images in automated deployment or backup scripts
* Development tools: Integrate Docker Hub access with IDEs, container management tools, or monitoring systems
* Two-factor authentication: Required for CLI access when 2FA is turned on

> Note
>
> For organization-wide automation, consider [organization access tokens](https://docs.docker.com/enterprise/security/access-tokens/) which aren't tied to individual user accounts.

## [Create a personal access token](#create-a-personal-access-token)

> Important
>
> Treat access tokens like passwords and keep them secure. Store tokens in credential managers and never commit them to source code repositories.

To create a personal access token:

1. Sign in to [Docker Home](https://app.docker.com/).

2. Select your avatar in the top-right corner and from the drop-down menu select **Account settings**.

3. Select **Personal access tokens**.

4. Select **Generate new token**.

5. Configure your token:

   * **Description:** Use a descriptive name that indicates the token's purpose
   * **Expiration date:** Set an expiration date based on your security policies
   * **Access permissions:** **Read**, **Write**, or **Delete**.

6. Select **Generate**. Copy the token that appears on the screen and save it. You won't be able to retrieve the token once you exit the screen.

## [Use personal access tokens](#use-personal-access-tokens)

Sign in to the Docker CLI using your personal access token:

```console
$ docker login --username YOUR_USERNAME
Password: [paste your PAT here]
```

When prompted for a password, enter your personal access token instead of your Docker Hub password.

## [Modify personal access tokens](#modify-personal-access-tokens)

> Note
>
> You can't edit the expiration date on an existing personal access token. You must create a new PAT if you need to set a new expiration date.

You can rename, activate, deactivate, or delete a token as needed. You can manage your tokens in your account settings.

1. Sign in to [Docker Home](https://app.docker.com/login).
2. Select your avatar in the top-right corner and from the drop-down menu select **Account settings**.
3. Select **Personal access tokens**.
   * This page shows an overview of all your tokens, and lists if the token was generated manually or if it was [auto-generated](#auto-generated-tokens). You can also view the scope of the tokens, which tokens are activate and inactive, when they were created, when they were last used, and their expiration date.
4. Select the actions menu on the far right of a token row, then select **Deactivate** or **Activate**, **Edit**, or **Delete** to modify the token.
5. After editing the token, select **Save token**.

## [Auto-generated tokens](#auto-generated-tokens)

Docker Desktop automatically creates authentication tokens when you sign in, with these characteristics:

* Automatic creation: Generated when you sign in to Docker Desktop
* Full permissions: Include Read, Write, and Delete access
* Session-based: Automatically removed when Docker Desktop session expires
* Account limits: Up to 5 auto-generated tokens per account
* Automatic cleanup: Older tokens are deleted when new ones are created

You can manually delete auto-generated tokens if needed, but they'll be recreated when you use Docker Desktop.

## [Fair use policy](#fair-use-policy)

When using personal access tokens, be aware that excessive token creation may result in throttling or additional charges. Docker reserves the right to impose restrictions on accounts with excessive PAT usage to ensure fair resource allocation and maintain service quality.

Best practices for fair use include:

* Reuse tokens across similar use cases instead of creating many single-purpose tokens
* Delete unused tokens regularly
* Use [organization access tokens](https://docs.docker.com/enterprise/security/access-tokens/) for organization-wide automation
* Monitor token usage to identify optimization opportunities

----
url: https://docs.docker.com/reference/cli/docker/container/prune/
----

# docker container prune

***

| Description | Remove all stopped containers      |
| ----------- | ---------------------------------- |
| Usage       | `docker container prune [OPTIONS]` |

## [Description](#description)

Removes all stopped containers.

## [Options](#options)

| Option                | Default | Description                                      |
| --------------------- | ------- | ------------------------------------------------ |
| [`--filter`](#filter) |         | Provide filter values (e.g. `until=<timestamp>`) |
| `-f, --force`         |         | Do not prompt for confirmation                   |

## [Examples](#examples)

### [Prune containers](#prune-containers)

```console
$ docker container prune
WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y
Deleted Containers:
4a7f7eebae0f63178aff7eb0aa39cd3f0627a203ab2df258c1a00b456cf20063
f98f9c2aa1eaf727e4ec9c0283bc7d4aa4762fbdba7f26191f26c97f64090360

Total reclaimed space: 212 B
```

### [Filtering (--filter)](#filter)

The filtering flag (`--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).

When multiple filters are provided, they are combined as follows:

* Multiple filters with **different keys** are combined using AND logic. A container must satisfy all filter conditions to be pruned.
* Multiple filters with the **same key** are combined using OR logic. A container is pruned if it matches any of the values for that key.

For example, `--filter "label=foo" --filter "until=24h"` prunes containers that have the `foo` label **and** were created more than 24 hours ago. Conversely, `--filter "label=foo" --filter "label=bar"` prunes containers that have **either** the `foo` **or** `bar` label.

The currently supported filters are:

* until (`<timestamp>`) - only remove containers created before given timestamp
* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove containers with (or without, in case `label!=...` is used) the specified labels.

The `until` filter can be Unix timestamps, date formatted timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local timezone on the daemon will be used if you do not provide either a `Z` or a `+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds\[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long.

The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`), which removes containers with the specified labels. The other format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes containers without the specified labels.

The following removes containers created more than 5 minutes ago:

```console
$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}'

CONTAINER ID        IMAGE               COMMAND             CREATED AT                      STATUS
61b9efa71024        busybox             "sh"                2017-01-04 13:23:33 -0800 PST   Exited (0) 41 seconds ago
53a9bc23a516        busybox             "sh"                2017-01-04 13:11:59 -0800 PST   Exited (0) 12 minutes ago

$ docker container prune --force --filter "until=5m"

Deleted Containers:
53a9bc23a5168b6caa2bfbefddf1b30f93c7ad57f3dec271fd32707497cb9369

Total reclaimed space: 25 B

$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}'

CONTAINER ID        IMAGE               COMMAND             CREATED AT                      STATUS
61b9efa71024        busybox             "sh"                2017-01-04 13:23:33 -0800 PST   Exited (0) 44 seconds ago
```

The following removes containers created before `2017-01-04T13:10:00`:

```console
$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}'

CONTAINER ID        IMAGE               COMMAND             CREATED AT                      STATUS
53a9bc23a516        busybox             "sh"                2017-01-04 13:11:59 -0800 PST   Exited (0) 7 minutes ago
4a75091a6d61        busybox             "sh"                2017-01-04 13:09:53 -0800 PST   Exited (0) 9 minutes ago

$ docker container prune --force --filter "until=2017-01-04T13:10:00"

Deleted Containers:
4a75091a6d618526fcd8b33ccd6e5928ca2a64415466f768a6180004b0c72c6c

Total reclaimed space: 27 B

$ docker ps -a --format 'table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.CreatedAt}}\t{{.Status}}'

CONTAINER ID        IMAGE               COMMAND             CREATED AT                      STATUS
53a9bc23a516        busybox             "sh"                2017-01-04 13:11:59 -0800 PST   Exited (0) 9 minutes ago
```

----
url: https://docs.docker.com/guides/rust/
----

# Rust language-specific guide

***

This guide covers how to containerize Rust applications using Docker.

**Time to complete** 20 minutes

The Rust language-specific guide teaches you how to create a containerized Rust application using Docker. In this guide, you'll learn how to:

* Containerize a Rust application
* Build an image and run the newly built image as a container
* Set up volumes and networking
* Orchestrate containers using Compose
* Use containers for development
* Configure a CI/CD pipeline for your application using GitHub Actions
* Deploy your containerized Rust application locally to Kubernetes to test and debug your deployment

After completing the Rust modules, you should be able to containerize your own Rust application based on the examples and instructions provided in this guide.

Start with building your first Rust image.

## [Modules](#modules)

1. [Build images](https://docs.docker.com/guides/rust/build-images/)

   Learn how to build your first Rust Docker image

2. [Run containers](https://docs.docker.com/guides/rust/run-containers/)

   Learn how to run your Rust image as a container.

3. [Develop your app](https://docs.docker.com/guides/rust/develop/)

   Learn how to develop your Rust application locally.

4. [Configure CI/CD](https://docs.docker.com/guides/rust/configure-ci-cd/)

   Learn how to Configure CI/CD for your application

5. [Test your deployment](https://docs.docker.com/guides/rust/deploy/)

   Learn how to test your Rust deployment locally using Kubernetes

----
url: https://docs.docker.com/reference/cli/docker/node/ps/
----

# docker node ps

***

| Description | List tasks running on one or more nodes, defaults to current node |
| ----------- | ----------------------------------------------------------------- |
| Usage       | `docker node ps [OPTIONS] [NODE...]`                              |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Lists all the tasks on a Node that Docker knows about. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filter) section for more information about available filter options.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                |
| ------------------------- | ------- | ------------------------------------------ |
| [`-f, --filter`](#filter) |         | Filter output based on conditions provided |
| [`--format`](#format)     |         | Pretty-print tasks using a Go template     |
| `--no-resolve`            |         | Do not map IDs to Names                    |
| `--no-trunc`              |         | Do not truncate output                     |
| `-q, --quiet`             |         | Only display task IDs                      |

## [Examples](#examples)

```console
$ docker node ps swarm-manager1

NAME                                IMAGE        NODE            DESIRED STATE  CURRENT STATE
redis.1.7q92v0nr1hcgts2amcjyqg3pq   redis:7.4.1  swarm-manager1  Running        Running 5 hours
redis.6.b465edgho06e318egmgjbqo4o   redis:7.4.1  swarm-manager1  Running        Running 29 seconds
redis.7.bg8c07zzg87di2mufeq51a2qp   redis:7.4.1  swarm-manager1  Running        Running 5 seconds
redis.9.dkkual96p4bb3s6b10r7coxxt   redis:7.4.1  swarm-manager1  Running        Running 5 seconds
redis.10.0tgctg8h8cech4w0k0gwrmr23  redis:7.4.1  swarm-manager1  Running        Running 5 seconds
```

### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).

The currently supported filters are:

* [name](#name)
* [id](#id)
* [label](#label)
* [desired-state](#desired-state)

#### [name](#name)

The `name` filter matches on all or part of a task's name.

The following filter matches all tasks with a name containing the `redis` string.

```console
$ docker node ps -f name=redis swarm-manager1

NAME                                IMAGE        NODE            DESIRED STATE  CURRENT STATE
redis.1.7q92v0nr1hcgts2amcjyqg3pq   redis:7.4.1  swarm-manager1  Running        Running 5 hours
redis.6.b465edgho06e318egmgjbqo4o   redis:7.4.1  swarm-manager1  Running        Running 29 seconds
redis.7.bg8c07zzg87di2mufeq51a2qp   redis:7.4.1  swarm-manager1  Running        Running 5 seconds
redis.9.dkkual96p4bb3s6b10r7coxxt   redis:7.4.1  swarm-manager1  Running        Running 5 seconds
redis.10.0tgctg8h8cech4w0k0gwrmr23  redis:7.4.1  swarm-manager1  Running        Running 5 seconds
```

#### [id](#id)

The `id` filter matches a task's id.

```console
$ docker node ps -f id=bg8c07zzg87di2mufeq51a2qp swarm-manager1

NAME                                IMAGE        NODE            DESIRED STATE  CURRENT STATE
redis.7.bg8c07zzg87di2mufeq51a2qp   redis:7.4.1  swarm-manager1  Running        Running 5 seconds
```

#### [label](#label)

The `label` filter matches tasks based on the presence of a `label` alone or a `label` and a value.

The following filter matches tasks with the `usage` label regardless of its value.

```console
$ docker node ps -f "label=usage"

NAME                               IMAGE        NODE            DESIRED STATE  CURRENT STATE
redis.6.b465edgho06e318egmgjbqo4o  redis:7.4.1  swarm-manager1  Running        Running 10 minutes
redis.7.bg8c07zzg87di2mufeq51a2qp  redis:7.4.1  swarm-manager1  Running        Running 9 minutes
```

#### [desired-state](#desired-state)

The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`.

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints tasks output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder     | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `.ID`           | Task ID                                                          |
| `.Name`         | Task name                                                        |
| `.Image`        | Task image                                                       |
| `.Node`         | Node ID                                                          |
| `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) |
| `.CurrentState` | Current state of the task                                        |
| `.Error`        | Error                                                            |
| `.Ports`        | Task published ports                                             |

When using the `--format` option, the `node ps` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `Name` and `Image` entries separated by a colon (`:`) for all tasks:

```console
$ docker node ps --format "{{.Name}}: {{.Image}}"

top.1: busybox
top.2: busybox
top.3: busybox
```

----
url: https://docs.docker.com/guides/python/develop/
----

# Use containers for Python development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a Python application](https://docs.docker.com/guides/python/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment for your containerized application. This includes:

* Adding a local database and persisting data
* Configuring Compose to automatically update your running Compose services as you edit and save your code

## [Get the sample application](#get-the-sample-application)

You'll need to clone a new repository to get a sample application that includes logic to connect to the database.

1. Change to a directory where you want to clone the repository and run the following command.

   ```console
   $ git clone https://github.com/estebanx64/python-docker-dev-example
   ```

2. In the cloned repository's directory, create the necessary Docker assets.

   Create the following files in your project directory.

   Create a file named `Dockerfile` with the following contents.

   Dockerfile

   ```dockerfile
   # syntax=docker/dockerfile:1

   # Comments are provided throughout this file to help you get started.
   # If you need more help, visit the Dockerfile reference guide at
   # https://docs.docker.com/go/dockerfile-reference/

   ARG PYTHON_VERSION=3.12
   FROM python:${PYTHON_VERSION}-slim

   # Prevents Python from writing pyc files.
   ENV PYTHONDONTWRITEBYTECODE=1

   # Keeps Python from buffering stdout and stderr to avoid situations where
   # the application crashes without emitting any logs due to buffering.
   ENV PYTHONUNBUFFERED=1

   WORKDIR /app

   # Create a non-privileged user that the app will run under.
   # See https://docs.docker.com/go/dockerfile-user-best-practices/
   ARG UID=10001
   RUN adduser \
       --disabled-password \
       --gecos "" \
       --home "/nonexistent" \
       --shell "/sbin/nologin" \
       --no-create-home \
       --uid "${UID}" \
       appuser

   # Download dependencies as a separate step to take advantage of Docker's    caching.
   # Leverage a cache mount to /root/.cache/pip to speed up subsequent builds.
   # Leverage a bind mount to requirements.txt to avoid having to copy them into
   # into this layer.
   RUN --mount=type=cache,target=/root/.cache/pip \
       --mount=type=bind,source=requirements.txt,target=requirements.txt \
       python -m pip install -r requirements.txt

   # Switch to the non-privileged user to run the application.
   USER appuser

   # Copy the source code into the container.
   COPY . .

   # Expose the port that the application listens on.
   EXPOSE 8001

   # Run the application.
   CMD ["python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8001"]
   ```

   Create a file named `compose.yaml` with the following contents.

   compose.yaml

   ```yaml
   # Comments are provided throughout this file to help you get started.
   # If you need more help, visit the Docker Compose reference guide at
   # https://docs.docker.com/go/compose-spec-reference/

   # Here the instructions define your application as a service called "server".
   # This service is built from the Dockerfile in the current directory.
   # You can add other services your application may depend on here, such as a
   # database or a cache. For examples, see the Awesome Compose repository:
   # https://github.com/docker/awesome-compose
   services:
     server:
       build:
         context: .
       ports:
         - 8001:8001
   # The commented out section below is an example of how to define a PostgreSQL
   # database that your application can use. `depends_on` tells Docker Compose to
   # start the database before your application. The `db-data` volume persists the
   # database data between container restarts. The `db-password` secret is used
   # to set the database password. You must create `db/password.txt` and add
   # a password of your choosing to it before running `docker compose up`.
   #     depends_on:
   #       db:
   #         condition: service_healthy
   #   db:
   #     image: postgres:18
   #     restart: always
   #     user: postgres
   #     secrets:
   #       - db-password
   #     volumes:
   #       - db-data:/var/lib/postgresql
   #     environment:
   #       - POSTGRES_DB=example
   #       - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
   #     expose:
   #       - 5432
   #     healthcheck:
   #       test: [ "CMD", "pg_isready" ]
   #       interval: 10s
   #       timeout: 5s
   #       retries: 5
   # volumes:
   #   db-data:
   # secrets:
   #   db-password:
   #     file: db/password.txt
   ```

   Create a file named `.dockerignore` with the following contents.

   .dockerignore

   ```text
   # Include any files or directories that you don't want to be copied to your
   # container here (e.g., local build artifacts, temporary files, etc.).
   #
   # For more help, visit the .dockerignore file reference guide at
   # https://docs.docker.com/go/build-context-dockerignore/

   **/.DS_Store
   **/__pycache__
   **/.venv
   **/.classpath
   **/.dockerignore
   **/.env
   **/.git
   **/.gitignore
   **/.project
   **/.settings
   **/.toolstarget
   **/.vs
   **/.vscode
   **/*.*proj.user
   **/*.dbmdl
   **/*.jfm
   **/bin
   **/charts
   **/docker-compose*
   **/compose.y*ml
   **/Dockerfile*
   **/node_modules
   **/npm-debug.log
   **/obj
   **/secrets.dev.yaml
   **/values.dev.yaml
   LICENSE
   README.md
   ```

   Create a file named `.gitignore` with the following contents.

   .gitignore

   ```text
   # Byte-compiled / optimized / DLL files
   __pycache__/
   *.py[cod]
   *$py.class

   # C extensions
   *.so

   # Distribution / packaging
   .Python
   build/
   develop-eggs/
   dist/
   downloads/
   eggs/
   .eggs/
   lib/
   lib64/
   parts/
   sdist/
   var/
   wheels/
   share/python-wheels/
   *.egg-info/
   .installed.cfg
   *.egg
   MANIFEST

   # Unit test / coverage reports
   htmlcov/
   .tox/
   .nox/
   .coverage
   .coverage.*
   .cache
   nosetests.xml
   coverage.xml
   *.cover
   *.py,cover
   .hypothesis/
   .pytest_cache/
   cover/

   # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
   __pypackages__/

   # Environments
   .env
   .venv
   env/
   venv/
   ENV/
   env.bak/
   venv.bak/
   ```

## [Add a local database and persist data](#add-a-local-database-and-persist-data)

You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data.

In the cloned repository's directory, open the `compose.yaml` file in an IDE or text editor and update it for your unique application.

In the `compose.yaml` file, you need to uncomment all of the database instructions. In addition, you need to add the database password file as an environment variable to the server service and specify the secret file to use .

The following is the updated `compose.yaml` file.

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 8001:8001
    environment:
      - POSTGRES_SERVER=db
      - POSTGRES_USER=postgres
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    depends_on:
      db:
        condition: service_healthy
    secrets:
      - db-password
  db:
    image: postgres:18
    restart: always
    user: postgres
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    expose:
      - 5432
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
```

> Note
>
> To learn more about the instructions in the Compose file, see [Compose file reference](/reference/compose-file/).

Before you run the application using Compose, notice that this Compose file specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository.

In the cloned repository's directory, create a new directory named `db` and inside that directory create a file named `password.txt` that contains the password for the database. Using your favorite IDE or text editor, add the following contents to the `password.txt` file.

```text
mysecretpassword
```

Save and close the `password.txt` file.

You should now have the following contents in your `python-docker-dev-example` directory.

```text
├── python-docker-dev-example/
│ ├── db/
│ │ └── password.txt
│ ├── app.py
│ ├── config.py
│ ├── requirements.txt
│ ├── .dockerignore
│ ├── .gitignore
│ ├── compose.yaml
│ ├── Dockerfile
│ └── README.md
```

Now, run the following `docker compose up` command to start your application.

```console
$ docker compose up --build
```

Now test your API endpoint. Open a new terminal then make a request to the server using the curl commands:

Let's create an object with a post method

```console
$ curl -X 'POST' \
  'http://localhost:8001/heroes/' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": 1,
  "name": "my hero",
  "secret_name": "austing",
  "age": 12
}'
```

You should receive the following response:

```json
{
  "age": 12,
  "id": 1,
  "name": "my hero",
  "secret_name": "austing"
}
```

Let's make a get request with the next curl command:

```console
curl -X 'GET' \
  'http://localhost:8001/heroes/' \
  -H 'accept: application/json'
```

You should receive the same response as above because it's the only one object we have in database.

```json
{
  "age": 12,
  "id": 1,
  "name": "my hero",
  "secret_name": "austing"
}
```

Press `ctrl+c` in the terminal to stop your application.

## [Automatically update services](#automatically-update-services)

Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

Open your `compose.yaml` file in an IDE or text editor and then add the Compose Watch instructions. The following is the updated `compose.yaml` file.

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 8001:8001
    environment:
      - POSTGRES_SERVER=db
      - POSTGRES_USER=postgres
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    depends_on:
      db:
        condition: service_healthy
    secrets:
      - db-password
    develop:
      watch:
        - action: rebuild
          path: .
  db:
    image: postgres:18
    restart: always
    user: postgres
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    expose:
      - 5432
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
```

Run the following command to run your application with Compose Watch.

```console
$ docker compose watch
```

In a terminal, curl the application to get a response.

```console
$ curl http://localhost:8001
Hello, Docker!
```

Any changes to the application's source files on your local machine will now be immediately reflected in the running container.

Open `python-docker-dev-example/app.py` in an IDE or text editor and update the `Hello, Docker!` string by adding a few more exclamation marks.

```diff
-    return 'Hello, Docker!'
+    return 'Hello, Docker!!!'
```

Save the changes to `app.py` and then wait a few seconds for the application to rebuild. Curl the application again and verify that the updated text appears.

```console
$ curl http://localhost:8001
Hello, Docker!!!
```

In the next section, you'll learn how you can set up linting, formatting and type checking to follow the best practices in python apps.

[Linting, formatting, and type checking for Python »](https://docs.docker.com/guides/python/lint-format-typing/)

----
url: https://docs.docker.com/desktop/setup/allow-list/
----

# Allowlist for Docker Desktop

***

Table of contents

***

For: Administrators

This page contains the domain URLs that you need to add to a firewall allowlist to ensure Docker Desktop works properly within your organization.

## [Domain URLs to allow](#domain-urls-to-allow)

| Domains                                                                                | Description                                  |
| -------------------------------------------------------------------------------------- | -------------------------------------------- |
| <https://notify.bugsnag.com>                                                           | Error reports                                |
| <https://sessions.bugsnag.com>                                                         | Error reports                                |
| <https://auth.docker.io>                                                               | Authentication                               |
| <https://cdn.auth0.com>                                                                | Authentication                               |
| <https://login.docker.com>                                                             | Authentication                               |
| <https://auth.docker.com>                                                              | Authentication                               |
| <https://desktop.docker.com>                                                           | Update                                       |
| <https://hub.docker.com>                                                               | Docker Hub                                   |
| <https://registry-1.docker.io>                                                         | Docker Pull/Push                             |
| <https://production.cloudflare.docker.com>                                             | Docker Pull/Push                             |
| <https://production.cloudfront.docker.com>                                             | Docker Pull/Push                             |
| <https://docker-images-prod.6aa30f8b08e16409b46e0173d6de2f56.r2.cloudflarestorage.com> | Docker Pull/Push (Personal plan / Anonymous) |
| <https://docker-pinata-support.s3.amazonaws.com>                                       | Troubleshooting                              |
| <https://api.dso.docker.com>                                                           | Docker Scout service                         |
| <https://api.docker.com>                                                               | New API                                      |
| <https://dhi.io>                                                                       | Docker Hardened Images                       |
| <https://registry.scout.docker.com>                                                    | Docker Scout registry for DHI attestations   |

----
url: https://docs.docker.com/dhi/explore/what/
----

# What are hardened images and why use them?

***

Table of contents

***

In today’s diverse software environments, container images are often designed for flexibility and broad compatibility. While that makes them ideal for many use cases, it can also result in images that include more components than needed for specific workloads. Docker Hardened Images take a minimal-by-design approach to help reduce image size, limit the attack surface, and streamline security and compliance workflows.

Hardened images solve this by minimizing what's in the container image. Less software means fewer vulnerabilities, faster deployments, and fewer red dashboards to chase down every week.

For platform engineers and security teams, hardened images offer a way out of the CVE triage cycle, letting you focus on delivering secure, compliant infrastructure without constant firefighting.

## [What is a hardened image?](#what-is-a-hardened-image)

A hardened image is a container image that has been deliberately minimized and secured to reduce vulnerabilities and meet stringent security and compliance requirements. Unlike standard images, which may include non-essential components that increase risk, hardened images are streamlined to include only what’s needed to run your application securely.

## [Benefits of hardened images](#benefits-of-hardened-images)

* Reduced attack surface: By removing non-essential components, hardened images limit potential entry points for attackers.
* Improved security posture: Regular updates and vulnerability scans help ensure hardened images remain secure over time.
* Compliance facilitation: Inclusion of signed metadata like SBOMs supports meeting regulatory and organizational compliance standards.
* Operational efficiency: Smaller image sizes lead to faster pulls, lower runtime overhead, and reduced cloud resource costs.

## [What is a Docker Hardened Image?](#what-is-a-docker-hardened-image)

Docker Hardened Images (DHIs) take hardened images even further by combining minimal, secure design with enterprise-grade support and tooling. Built with security at the core, these images are continuously maintained, tested, and validated to meet today’s toughest software supply chain and compliance standards.

Docker Hardened Images are secure by default, minimal by design, and maintained so you don’t have to.

## [How Docker Hardened Images differ from generic hardened images](#how-docker-hardened-images-differ-from-generic-hardened-images)

* SLSA-compliant builds: Docker Hardened Images are built to meet [SLSA Build Level 3](https://docs.docker.com/dhi/core-concepts/slsa/), ensuring a tamper-resistant, verifiable, and auditable build process that protects against supply chain threats.

* Distroless approach: Unlike traditional base images that bundle an entire OS with shells, package managers, and debugging tools, [distroless images](https://docs.docker.com/dhi/core-concepts/distroless/) retain only the minimal OS components required to run your application. By excluding unnecessary tooling and libraries, they reduce the attack surface by up to 95% and can improve performance and image size.

* Continuous maintenance: All DHIs are continuously monitored and updated to maintain near-zero known exploitable [CVEs](https://docs.docker.com/dhi/core-concepts/cves/), helping your teams avoid patch fatigue and surprise alerts.

* Compliance-ready: Each image includes cryptographically signed metadata:

  * [SBOMs](https://docs.docker.com/dhi/core-concepts/sbom/) that show what's in the image
  * [VEX documents](https://docs.docker.com/dhi/core-concepts/vex/) to identify which vulnerabilities are actually exploitable
  * [Build provenance](https://docs.docker.com/dhi/core-concepts/provenance/) that proves how and where the image was built

* Compatibility-focused design: Docker Hardened Images provide a minimal runtime environment while maintaining compatibility with common Linux distributions. They remove non-essential components like shells and package managers to enhance security, yet retain a small base layer built on familiar distribution standards. Images are typically available with musl libc (Alpine-based) and glibc (Debian-based), supporting a broad range of application compatibility needs.

## [Why use Docker Hardened Images?](#why-use-docker-hardened-images)

Docker Hardened Images (DHIs) are secure by default, minimal by design, and maintained so you don't have to. They offer:

* Images built for peace of mind: Ultra-minimal and distroless, DHIs eliminate up to 95% of the traditional container attack surface.
* No more patch panic: With continuous CVE scanning and [SLA-backed remediation](https://docs.docker.com/go/dhi-sla/), Docker helps you stay ahead of threats.
* Audit-ready images: All DHIs include signed SBOMs, VEX, and provenance that support security and compliance workflows.
* Images that work with your stack: Available in Alpine and Debian flavors, DHIs drop into your existing Dockerfiles and pipelines.
* Images backed by enterprise support: Get peace of mind with Docker's support and rapid response to critical vulnerabilities.

----
url: https://docs.docker.com/engine/security/apparmor/
----

# AppArmor security profiles for Docker

***

Table of contents

***

AppArmor (Application Armor) is a Linux security module that protects an operating system and its applications from security threats. To use it, a system administrator associates an AppArmor security profile with each program. Docker expects to find an AppArmor policy loaded and enforced.

Docker automatically generates and loads a default profile for containers named `docker-default`. The Docker binary generates this profile in `tmpfs` and then loads it into the kernel.

> Note
>
> This profile is used on containers, not on the Docker daemon.

A profile for the Docker Engine daemon exists but it is not currently installed with the `deb` packages. If you are interested in the source for the daemon profile, it is located in [contrib/apparmor](https://github.com/moby/moby/tree/master/contrib/apparmor) in the Docker Engine source repository.

## [Understand the policies](#understand-the-policies)

The `docker-default` profile is the default for running containers. It is moderately protective while providing wide application compatibility. The profile is generated from the following [template](https://github.com/moby/profiles/blob/main/apparmor/template.go).

When you run a container, it uses the `docker-default` policy unless you override it with the `security-opt` option. For example, the following explicitly specifies the default policy:

```console
$ docker run --rm -it --security-opt apparmor=docker-default hello-world
```

## [Load and unload profiles](#load-and-unload-profiles)

To load a new profile into AppArmor for use with containers:

```console
$ apparmor_parser -r -W /path/to/your_profile
```

Then, run the custom profile with `--security-opt`:

```console
$ docker run --rm -it --security-opt apparmor=your_profile hello-world
```

To unload a profile from AppArmor:

```console
# unload the profile
$ apparmor_parser -R /path/to/profile
```

### [Resources for writing profiles](#resources-for-writing-profiles)

The syntax for file globbing in AppArmor is a bit different than some other globbing implementations. It is highly suggested you take a look at some of the below resources with regard to AppArmor profile syntax.

* [Quick Profile Language](https://gitlab.com/apparmor/apparmor/wikis/QuickProfileLanguage)
* [Globbing Syntax](https://gitlab.com/apparmor/apparmor/wikis/AppArmor_Core_Policy_Reference#AppArmor_globbing_syntax)

## [Nginx example profile](#nginx-example-profile)

In this example, you create a custom AppArmor profile for Nginx. Below is the custom profile.

```c
#include <tunables/global>


profile docker-nginx flags=(attach_disconnected,mediate_deleted) {
  #include <abstractions/base>

  network inet tcp,
  network inet udp,
  network inet icmp,

  deny network raw,

  deny network packet,

  file,
  umount,

  deny /bin/** wl,
  deny /boot/** wl,
  deny /dev/** wl,
  deny /etc/** wl,
  deny /home/** wl,
  deny /lib/** wl,
  deny /lib64/** wl,
  deny /media/** wl,
  deny /mnt/** wl,
  deny /opt/** wl,
  deny /proc/** wl,
  deny /root/** wl,
  deny /sbin/** wl,
  deny /srv/** wl,
  deny /tmp/** wl,
  deny /sys/** wl,
  deny /usr/** wl,

  audit /** w,

  /var/run/nginx.pid w,

  /usr/sbin/nginx ix,

  deny /bin/dash mrwklx,
  deny /bin/sh mrwklx,
  deny /usr/bin/top mrwklx,


  capability chown,
  capability dac_override,
  capability setuid,
  capability setgid,
  capability net_bind_service,

  deny @{PROC}/* w,   # deny write for all files directly in /proc (not in a subdir)
  # deny write to files not in /proc/<number>/** or /proc/sys/**
  deny @{PROC}/{[^1-9],[^1-9][^0-9],[^1-9s][^0-9y][^0-9s],[^1-9][^0-9][^0-9][^0-9]*}/** w,
  deny @{PROC}/sys/[^k]** w,  # deny /proc/sys except /proc/sys/k* (effectively /proc/sys/kernel)
  deny @{PROC}/sys/kernel/{?,??,[^s][^h][^m]**} w,  # deny everything except shm* in /proc/sys/kernel/
  deny @{PROC}/sysrq-trigger rwklx,
  deny @{PROC}/mem rwklx,
  deny @{PROC}/kmem rwklx,
  deny @{PROC}/kcore rwklx,

  deny mount,

  deny /sys/[^f]*/** wklx,
  deny /sys/f[^s]*/** wklx,
  deny /sys/fs/[^c]*/** wklx,
  deny /sys/fs/c[^g]*/** wklx,
  deny /sys/fs/cg[^r]*/** wklx,
  deny /sys/firmware/** rwklx,
  deny /sys/kernel/security/** rwklx,
}
```

1. Save the custom profile to disk in the `/etc/apparmor.d/containers/docker-nginx` file.

   The file path in this example is not a requirement. In production, you could use another.

2. Load the profile.

   ```console
   $ sudo apparmor_parser -r -W /etc/apparmor.d/containers/docker-nginx
   ```

3. Run a container with the profile.

   To run nginx in detached mode:

   ```console
   $ docker run --security-opt "apparmor=docker-nginx" \
        -p 80:80 -d --name apparmor-nginx nginx
   ```

4. Exec into the running container.

   ```console
   $ docker container exec -it apparmor-nginx bash
   ```

5. Try some operations to test the profile.

   ```console
   root@6da5a2a930b9:~# ping 8.8.8.8
   ping: Lacking privilege for raw socket.

   root@6da5a2a930b9:/# top
   bash: /usr/bin/top: Permission denied

   root@6da5a2a930b9:~# touch ~/thing
   touch: cannot touch 'thing': Permission denied

   root@6da5a2a930b9:/# sh
   bash: /bin/sh: Permission denied

   root@6da5a2a930b9:/# dash
   bash: /bin/dash: Permission denied
   ```

You just deployed a container secured with a custom apparmor profile.

## [Debug AppArmor](#debug-apparmor)

You can use `dmesg` to debug problems and `aa-status` check the loaded profiles.

### [Use dmesg](#use-dmesg)

Here are some helpful tips for debugging any problems you might be facing with regard to AppArmor.

AppArmor sends quite verbose messaging to `dmesg`. Usually an AppArmor line looks like the following:

```text
[ 5442.864673] audit: type=1400 audit(1453830992.845:37): apparmor="ALLOWED" operation="open" profile="/usr/bin/docker" name="/home/jessie/docker/man/man1/docker-attach.1" pid=10923 comm="docker" requested_mask="r" denied_mask="r" fsuid=1000 ouid=0
```

In the above example, you can see `profile=/usr/bin/docker`. This means the user has the `docker-engine` (Docker Engine daemon) profile loaded.

Look at another log line:

```text
[ 3256.689120] type=1400 audit(1405454041.341:73): apparmor="DENIED" operation="ptrace" profile="docker-default" pid=17651 comm="docker" requested_mask="receive" denied_mask="receive"
```

This time the profile is `docker-default`, which is run on containers by default unless in `privileged` mode. This line shows that apparmor has denied `ptrace` in the container. This is exactly as expected.

### [Use aa-status](#use-aa-status)

If you need to check which profiles are loaded, you can use `aa-status`. The output looks like:

```console
$ sudo aa-status
apparmor module is loaded.
14 profiles are loaded.
1 profiles are in enforce mode.
   docker-default
13 profiles are in complain mode.
   /usr/bin/docker
   /usr/bin/docker///bin/cat
   /usr/bin/docker///bin/ps
   /usr/bin/docker///sbin/apparmor_parser
   /usr/bin/docker///sbin/auplink
   /usr/bin/docker///sbin/blkid
   /usr/bin/docker///sbin/iptables
   /usr/bin/docker///sbin/mke2fs
   /usr/bin/docker///sbin/modprobe
   /usr/bin/docker///sbin/tune2fs
   /usr/bin/docker///sbin/xtables-multi
   /usr/bin/docker///sbin/zfs
   /usr/bin/docker///usr/bin/xz
38 processes have profiles defined.
37 processes are in enforce mode.
   docker-default (6044)
   ...
   docker-default (31899)
1 processes are in complain mode.
   /usr/bin/docker (29756)
0 processes are unconfined but have a profile defined.
```

The above output shows that the `docker-default` profile running on various container PIDs is in `enforce` mode. This means AppArmor is actively blocking and auditing in `dmesg` anything outside the bounds of the `docker-default` profile.

The output above also shows the `/usr/bin/docker` (Docker Engine daemon) profile is running in `complain` mode. This means AppArmor only logs to `dmesg` activity outside the bounds of the profile. (Except in the case of Ubuntu Trusty, where some interesting behaviors are enforced.)

## [Contribute to Docker's AppArmor code](#contribute-to-dockers-apparmor-code)

Advanced users and package managers can find a profile for `/usr/bin/docker` (Docker Engine daemon) underneath [contrib/apparmor](https://github.com/moby/moby/tree/master/contrib/apparmor) in the Docker Engine source repository.

The `docker-default` profile for containers lives in [profiles/apparmor](https://github.com/moby/profiles/blob/main/apparmor).

----
url: https://docs.docker.com/reference/cli/docker/scout/stream/
----

# docker scout stream

***

| Description | Manage streams (experimental)          |
| ----------- | -------------------------------------- |
| Usage       | `docker scout stream [STREAM] [IMAGE]` |

> Warning
>
> This command is deprecated
>
> It may be removed in a future Docker version. For more information, see the [Docker roadmap](https://github.com/docker/roadmap/issues/209)

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

The `docker scout stream` command lists the deployment streams and records an image to it.

Once recorded, streams can be referred to by their name, eg. in the `docker scout compare` command using `--to-stream`.

## [Options](#options)

| Option         | Default | Description                          |
| -------------- | ------- | ------------------------------------ |
| `--org`        |         | Namespace of the Docker organization |
| `-o, --output` |         | Write the report to a file           |
| `--platform`   |         | Platform of image to record          |

## [Examples](#examples)

### [List existing streams](#list-existing-streams)

```console
$ %[1]s %[2]s
prod-cluster-123
stage-cluster-234
```

### [List images of a stream](#list-images-of-a-stream)

```console
$ %[1]s %[2]s prod-cluster-123
namespace/repo:tag@sha256:9a4df4fadc9bbd44c345e473e0688c2066a6583d4741679494ba9228cfd93e1b
namespace/other-repo:tag@sha256:0001d6ce124855b0a158569c584162097fe0ca8d72519067c2c8e3ce407c580f
```

### [Record an image to a stream, for a specific platform](#record-an-image-to-a-stream-for-a-specific-platform)

```console
$ %[1]s %[2]s stage-cluster-234 namespace/repo:stage-latest --platform linux/amd64
✓ Pulled
✓ Successfully recorded namespace/repo:stage-latest in stream stage-cluster-234
```

----
url: https://docs.docker.com/guides/postgresql/
----

# PostgreSQL specific guide

***

This guide explains how to containerize PostgreSQL databases using Docker.

**Time to complete** 20 minutes

## [Modules](#modules)

1. [Immediate setup & data persistence](https://docs.docker.com/guides/postgresql/immediate-setup-and-data-persistence/)

   Get PostgreSQL running in Docker in under five minutes. Learn how to configure named volumes and bind mounts to persist your database across container restarts.

2. [Advanced Configuration and Initialization](https://docs.docker.com/guides/postgresql/advanced-configuration-and-initialization/)

   Configure PostgreSQL initialization scripts, tune performance parameters, and set timezone and locale settings for containerized deployments.

3. [Networking and connectivity](https://docs.docker.com/guides/postgresql/networking-and-connectivity/)

   This module shows how to connect to PostgreSQL in Docker in two common ways; from another container (internal network) and from your host machine (external access).

4. [Companions for PostgreSQL](https://docs.docker.com/guides/postgresql/companions-for-postgresql/)

   This module explains how to customize PostgreSQL for real-world use in Docker, covering automated database initialization, performance tuning, and timezone configuration once persistent storage is in place.

----
url: https://docs.docker.com/reference/cli/sbx/template/ls/
----

# sbx template ls

| Description | List template images      |
| ----------- | ------------------------- |
| Usage       | `sbx template ls [flags]` |

## [Description](#description)

List all template images stored in the sandbox runtime's image store.

## [Options](#options)

| Option   | Default | Description           |
| -------- | ------- | --------------------- |
| `--json` |         | Output in JSON format |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# List all template images
sbx template ls

# Output in JSON format
sbx template ls --json
```

----
url: https://docs.docker.com/guides/docker-compose/setup/
----

# Demo: set up and use Docker Compose

***

***

This Docker Compose demo shows how to orchestrate a multi-container application environment, streamlining development and deployment processes.

* Compare Docker Compose to the `docker run` command
* Configure a multi-container web app using a Compose file
* Run a multi-container web app using one command

[Common challenges and questions »](https://docs.docker.com/guides/docker-compose/common-questions/)

----
url: https://docs.docker.com/admin/organization/setup/convert-account/
----

# Convert an account into an organization

***

Table of contents

***

Subscription: Team Business

For: Administrators

Learn how to convert an existing user account into an organization. This is useful if you need multiple users to access your account and the repositories it’s connected to. Converting it to an organization gives you better control over permissions for these users through [teams](https://docs.docker.com/admin/organization/manage/manage-a-team/) and [roles](https://docs.docker.com/enterprise/security/roles-and-permissions/).

When you convert a user account to an organization, the account is migrated to a Docker Team subscription by default.

## [Prerequisites](#prerequisites)

Before you convert a user account to an organization, ensure that you meet the following requirements:

* The user account that you want to convert must not be a member of a company or any teams or organizations. You must remove the account from all teams, organizations, or the company.

  To do this:

  1. Navigate to **My Hub** and then select the organization you need to leave.
  2. Find your username in the **Members** tab.
  3. Select the **More options** menu and then select **Leave organization**.

  If the user account is the sole owner of any organization or company, assign another user the owner role and then remove yourself from the organization or company.

* You must have a separate Docker ID ready to assign as the owner of the organization during conversion.

  If you want to convert your user account into an organization account and you don't have any other user accounts, you need to create a new user account to assign it as the owner of the new organization. With the owner role assigned, this user account has full administrative access to configure and manage the organization. You can assign more users the owner role after the conversion.

## [What happens when you convert your account](#what-happens-when-you-convert-your-account)

The following happens when you convert your account into an organization:

* This process removes the email address for the account. Notifications are instead sent to organization owners. You'll be able to reuse the removed email address for another account after converting.
* The current subscription will automatically cancel and your new subscription will start.
* Repository namespaces and names won't change, but converting your account removes any repository collaborators. Once you convert the account, you'll need to add repository collaborators as team members.
* Existing automated builds appear as if they were set up by the first owner added to the organization.
* The user account that you add as the first owner will have full administrative access to configure and manage the organization.
* To transfer a user's personal access tokens (PATs) to your converted organization, you must designate the user as an organization owner. This will ensure any PATs associated with the user's account are transferred to the organization owner.

## [Convert an account into an organization](#convert-an-account-into-an-organization)

> Important
>
> Converting an account into an organization is permanent. Back up any data or settings you want to retain.

1. Sign in to [Docker Home](https://app.docker.com/).
2. Select your avatar in the top-right corner to open the drop-down.
3. From **Account settings**, select **Convert**.
4. Review the warning displayed about converting a user account. This action cannot be undone and has considerable implications for your assets and the account.
5. Enter a **Username of new owner** to set an organization owner. The new Docker ID you specify becomes the organization’s owner. You cannot use the same Docker ID as the account you are trying to convert. The Docker ID is case-sensitive.
6. Select **Confirm**. The new owner receives a notification email. Use that owner account to sign in and manage the new organization.

----
url: https://docs.docker.com/compose/how-tos/multiple-compose-files/extends/
----

# Extend your Compose file

***

Table of contents

***

Docker Compose's [`extends` attribute](https://docs.docker.com/reference/compose-file/services/#extends) lets you share common configurations among different files, or even different projects entirely.

Extending services is useful if you have several services that reuse a common set of configuration options. With `extends` you can define a common set of service options in one place and refer to it from anywhere. You can refer to another Compose file and select a service you want to also use in your own application, with the ability to override some attributes for your own needs.

> Important
>
> When you use multiple Compose files, you must make sure all paths in the files are relative to the base Compose file (i.e. the Compose file in your main-project folder). This is required because extend files need not be valid Compose files. Extend files can contain small fragments of configuration. Tracking which fragment of a service is relative to which path is difficult and confusing, so to keep paths easier to understand, all paths must be defined relative to the base file.

> Note
>
> `extends` is not supported when deploying with `docker stack deploy`. Running `docker stack config` on a Compose file that uses `extends` returns the error: `Configuration contains forbidden properties`.

## [How the `extends` attribute works](#how-the-extends-attribute-works)

### [Extending services from another file](#extending-services-from-another-file)

Take the following example:

```yaml
services:
  web:
    extends:
      file: common-services.yml
      service: webapp
```

This instructs Compose to reuse only the properties of the `webapp` service defined in the `common-services.yml` file. The `webapp` service itself is not part of the final project.

If `common-services.yml` looks like this:

```yaml
services:
  webapp:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - "/data"
```

You get exactly the same result as if you wrote `compose.yaml` with the same `build`, `ports`, and `volumes` configuration values defined directly under `web`.

To include the service `webapp` in the final project when extending services from another file, you need to explicitly include both services in your current Compose file. For example (this is for illustrative purposes only):

```yaml
services:
  web:
    build: ./alpine
    command: echo
    extends:
      file: common-services.yml
      service: webapp
  webapp:
    extends:
      file: common-services.yml
      service: webapp
```

Alternatively, you can use [include](https://docs.docker.com/compose/how-tos/multiple-compose-files/include/).

### [Extending services within the same file](#extending-services-within-the-same-file)

If you define services in the same Compose file and extend one service from another, both the original service and the extended service will be part of your final configuration. For example:

```yaml
services:
  web:
    build: ./alpine
    extends: webapp
  webapp:
    environment:
      - DEBUG=1
```

### [Extending services within the same file and from another file](#extending-services-within-the-same-file-and-from-another-file)

You can go further and define, or re-define, configuration locally in `compose.yaml`:

```yaml
services:
  web:
    extends:
      file: common-services.yml
      service: webapp
    environment:
      - DEBUG=1
    cpu_shares: 5

  important_web:
    extends: web
    cpu_shares: 10
```

## [Additional example](#additional-example)

Extending an individual service is useful when you have multiple services that have a common configuration. The example below is a Compose app with two services, a web application and a queue worker. Both services use the same codebase and share many configuration options.

The `common.yaml` file defines the common configuration:

```yaml
services:
  app:
    build: .
    environment:
      CONFIG_FILE_PATH: /code/config
      API_KEY: xxxyyy
    cpu_shares: 5
```

The `compose.yaml` defines the concrete services which use the common configuration:

```yaml
services:
  webapp:
    extends:
      file: common.yaml
      service: app
    command: /code/run_web_app
    ports:
      - 8080:8080
    depends_on:
      - queue
      - db

  queue_worker:
    extends:
      file: common.yaml
      service: app
    command: /code/run_worker
    depends_on:
      - queue
```

## [Relative paths](#relative-paths)

When using `extends` with a `file` attribute which points to another folder, relative paths declared by the service being extended are converted so they still point to the same file when used by the extending service. This is illustrated in the following example:

Base Compose file:

```yaml
services:
  webapp:
    image: example
    extends:
      file: ../commons/compose.yaml
      service: base
```

The `commons/compose.yaml` file:

```yaml
services:
  base:
    env_file: ./container.env
```

The resulting service refers to the original `container.env` file within the `commons` directory. This can be confirmed with `docker compose config` which inspects the actual model:

```yaml
services:
  webapp:
    image: example
    env_file: 
      - ../commons/container.env
```

## [Reference information](#reference-information)

* [`extends`](https://docs.docker.com/reference/compose-file/services/#extends)

----
url: https://docs.docker.com/build/bake/expressions/
----

# Expression evaluation in Bake

***

Table of contents

***

Bake files in the HCL format support expression evaluation, which lets you perform arithmetic operations, conditionally set values, and more.

## [Arithmetic operations](#arithmetic-operations)

You can perform arithmetic operations in expressions. The following example shows how to multiply two numbers.

docker-bake.hcl

```hcl
sum = 7*6

target "default" {
  args = {
    answer = sum
  }
}
```

Printing the Bake file with the `--print` flag shows the evaluated value for the `answer` build argument.

```console
$ docker buildx bake --print
```

```json
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "answer": "42"
      }
    }
  }
}
```

## [Ternary operators](#ternary-operators)

You can use ternary operators to conditionally register a value.

The following example adds a tag only when a variable is not empty, using the built-in `notequal` [function](https://docs.docker.com/build/bake/funcs/).

docker-bake.hcl

```hcl
variable "TAG" {}

target "default" {
  context="."
  dockerfile="Dockerfile"
  tags = [
    "my-image:latest",
    notequal("",TAG) ? "my-image:${TAG}": ""
  ]
}
```

In this case, `TAG` is an empty string, so the resulting build configuration only contains the hard-coded `my-image:latest` tag.

```console
$ docker buildx bake --print
```

```json
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": ["my-image:latest"]
    }
  }
}
```

## [Expressions with variables](#expressions-with-variables)

You can use expressions with [variables](https://docs.docker.com/build/bake/variables/) to conditionally set values, or to perform arithmetic operations.

The following example uses expressions to set values based on the value of variables. The `v1` build argument is set to "higher" if the variable `FOO` is greater than 5, otherwise it is set to "lower". The `v2` build argument is set to "yes" if the `IS_FOO` variable is true, otherwise it is set to "no".

docker-bake.hcl

```hcl
variable "FOO" {
  default = 3
}

variable "IS_FOO" {
  default = true
}

target "app" {
  args = {
    v1 = FOO > 5 ? "higher" : "lower"
    v2 = IS_FOO ? "yes" : "no"
  }
}
```

Printing the Bake file with the `--print` flag shows the evaluated values for the `v1` and `v2` build arguments.

```console
$ docker buildx bake --print app
```

```json
{
  "group": {
    "default": {
      "targets": ["app"]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "v1": "lower",
        "v2": "yes"
      }
    }
  }
}
```

----
url: https://docs.docker.com/guides/ros2/develop/
----

# Build and develop a ROS 2 workspace

***

Table of contents

***

## [Overview](#overview)

In this section, you will set up a ROS 2 workspace using Docker and development containers, review the workspace layout, open the workspace in Visual Studio Code, and edit and build ROS 2 projects inside the container.

***

## [Get the sample ROS 2 workspace](#get-the-sample-ros-2-workspace)

A consistent workspace simplifies managing ROS 2 projects and build artifacts across different distributions.

1. Open a terminal and clone the sample workspace repository:

   ```console
   $ git clone https://github.com/shakirth-anisha/docker-ros2-workspace.git
   $ cd docker-ros2-workspace
   ```

   Moving forward, Linux users can use the `ws_linux` folder, and macOS users can use `ws_mac`.

2. Verify the workspace structure:

   ```text
   ws_linux/
   ├── compose.yml
   ├── Dockerfile
   └── src/
       ├── package1/
       └── package2/

   ws_mac/
   ├── compose.yml
   ├── Dockerfile
   └── src/
       ├── package1/
       └── package2/
   ```

3. Explore the workspace layout

* `compose.yml` : Defines how Docker Compose builds and runs the ROS 2 container, including mounts, environment variables, and networking settings.
* `Dockerfile` : Builds the ROS 2 development image. It uses an official ROS 2 base image, creates a non-root development user, and installs required system and ROS 2 dependencies.
* `src` : Contains all ROS 2 packages. This directory is mounted into the container as the active workspace.

## [Open and build the container](#open-and-build-the-container)

1. Execute the following commands to build and start the container:

   For Linux:

   ```console
   $ cd ws_linux
   $ docker compose up -d
   $ docker compose exec ros2 /bin/bash
   ```

   For macOS:

   ```console
   $ cd ws_mac
   $ docker compose up -d
   $ docker compose exec ros2 /bin/bash
   ```

   This command builds the Docker image defined in your `Dockerfile` and starts the container in the background.

   > Note
   >
   > Building the image may take several minutes during the first run as the CLI pulls the base ROS 2 image and installs required dependencies. Subsequent starts will be significantly faster.

2. Once the container is running, execute commands inside it using `exec`:

   ```console
   $ docker compose exec ros2 /bin/bash
   ```

3. Inside the container terminal, verify the environment:

```console
$ echo $ROS_VERSION
$ which colcon
```

All commands should execute successfully inside the container.

## [Switch ROS 2 distributions](#switch-ros-2-distributions)

Update the base image in your `Dockerfile`, changing from `humble` to another distribution like `rolling`, `jazzy`, or `iron`.

## [Summary](#summary)

In this section, you learned how to create a structured workspace, write a Dockerfile with development tools, and configure a Docker Compose setup. Your ROS 2 development environment is now ready with a consistent, reproducible setup across any machine.

## [Next steps](#next-steps)

In the next section, you'll run a complete end-to-end example with Turtlesim.

[Run a complete example with Turtlesim »](https://docs.docker.com/guides/ros2/turtlesim-example/)

----
url: https://docs.docker.com/build/bake/
----

# Bake

***

Table of contents

***

Bake is a feature of Docker Buildx that lets you define your build configuration using a declarative file, as opposed to specifying a complex CLI expression. It also lets you run multiple builds concurrently with a single invocation.

A Bake file can be written in HCL or JSON format. Bake can also build directly from a [Docker Compose file](https://docs.docker.com/build/bake/compose-file/). Here's an example Bake file in HCL format:

docker-bake.hcl

```hcl
group "default" {
  targets = ["frontend", "backend"]
}

target "frontend" {
  context = "./frontend"
  dockerfile = "frontend.Dockerfile"
  args = {
    NODE_VERSION = "22"
  }
  tags = ["myapp/frontend:latest"]
}

target "backend" {
  context = "./backend"
  dockerfile = "backend.Dockerfile"
  args = {
    GO_VERSION = "1.25"
  }
  tags = ["myapp/backend:latest"]
}
```

The `group` block defines a group of targets that can be built concurrently. Each `target` block defines a build target with its own configuration, such as the build context, Dockerfile, and tags.

To invoke a build using the above Bake file, you can run:

```console
$ docker buildx bake
```

This executes the `default` group, which builds the `frontend` and `backend` targets concurrently.

## [Get started](#get-started)

To learn how to get started with Bake, head over to the [Bake introduction](https://docs.docker.com/build/bake/introduction/).

----
url: https://docs.docker.com/engine/network/drivers/macvlan/
----

# Macvlan network driver

***

Table of contents

***

Some applications, especially legacy applications or applications which monitor network traffic, expect to be directly connected to the physical network. In this type of situation, you can use the `macvlan` network driver to assign a MAC address to each container's virtual network interface, making it appear to be a physical network interface directly connected to the physical network. In this case, you need to designate a physical interface on your Docker host to use for the Macvlan, as well as the subnet and gateway of the network. You can even isolate your Macvlan networks using different physical network interfaces.

## [Platform support and requirements](#platform-support-and-requirements)

* The macvlan driver only works on Linux hosts. It is not supported on Docker Desktop for Mac or Windows, or Docker Engine on Windows.
* Most cloud providers block macvlan networking. You may need physical access to your networking equipment.
* Requires at least Linux kernel version 3.9 (version 4.0 or later is recommended).
* The macvlan driver is not supported in rootless mode.

## [Considerations](#considerations)

* You may unintentionally degrade your network due to IP address exhaustion or to "VLAN spread", a situation that occurs when you have an inappropriately large number of unique MAC addresses in your network.

* Your networking equipment needs to be able to handle "promiscuous mode", where one physical interface can be assigned multiple MAC addresses.

* If your application can work using a bridge (on a single Docker host) or overlay (to communicate across multiple Docker hosts), these solutions may be better in the long term.

* Containers attached to a macvlan network cannot communicate with the host directly, this is a restriction in the Linux kernel. If you need communication between the host and the containers, you can connect the containers to a bridge network as well as the macvlan. It is also possible to create a macvlan interface on the host with the same parent interface, and assign it an IP address in the Docker network's subnet.

## [Options](#options)

The following table describes the driver-specific options that you can pass to `--opt` when creating a network using the `macvlan` driver.

| Option         | Default  | Description                                                                   |
| -------------- | -------- | ----------------------------------------------------------------------------- |
| `macvlan_mode` | `bridge` | Sets the Macvlan mode. Can be one of: `bridge`, `vepa`, `passthru`, `private` |
| `parent`       |          | Specifies the parent interface to use.                                        |

## [Create a Macvlan network](#create-a-macvlan-network)

When you create a Macvlan network, it can either be in bridge mode or 802.1Q trunk bridge mode.

* In bridge mode, Macvlan traffic goes through a physical device on the host.

* In 802.1Q trunk bridge mode, traffic goes through an 802.1Q sub-interface which Docker creates on the fly. This allows you to control routing and filtering at a more granular level.

### [Bridge mode](#bridge-mode)

To create a `macvlan` network which bridges with a given physical network interface, use `--driver macvlan` with the `docker network create` command. You also need to specify the `parent`, which is the interface the traffic will physically go through on the Docker host.

```console
$ docker network create -d macvlan \
  --subnet=172.16.86.0/24 \
  --gateway=172.16.86.1 \
  -o parent=eth0 pub_net
```

If you need to exclude IP addresses from being used in the `macvlan` network, such as when a given IP address is already in use, use `--aux-addresses`:

```console
$ docker network create -d macvlan \
  --subnet=192.168.32.0/24 \
  --ip-range=192.168.32.128/25 \
  --gateway=192.168.32.254 \
  --aux-address="my-router=192.168.32.129" \
  -o parent=eth0 macnet32
```

### [802.1Q trunk bridge mode](#8021q-trunk-bridge-mode)

If you specify a `parent` interface name with a dot included, such as `eth0.50`, Docker interprets that as a sub-interface of `eth0` and creates the sub-interface automatically.

```console
$ docker network create -d macvlan \
    --subnet=192.168.50.0/24 \
    --gateway=192.168.50.1 \
    -o parent=eth0.50 macvlan50
```

### [Use an IPvlan instead of Macvlan](#use-an-ipvlan-instead-of-macvlan)

An `ipvlan` network created with option `-o ipvlan_mode=l2` is similar to a macvlan network. The main difference is that the `ipvlan` driver doesn't assign a MAC address to each container, the layer-2 network stack is shared by devices in the ipvlan network. So, containers use the parent interface's MAC address.

The network will see fewer MAC addresses, and the host's MAC address will be associated with the IP address of each container.

The choice of network type depends on your environment and requirements. There are some notes about the trade-offs in the [Linux kernel documentation](https://docs.kernel.org/networking/ipvlan.html#what-to-choose-macvlan-vs-ipvlan).

```console
$ docker network create -d ipvlan \
    --subnet=192.168.210.0/24 \
    --gateway=192.168.210.254 \
     -o ipvlan_mode=l2 -o parent=eth0 ipvlan210
```

## [Use IPv6](#use-ipv6)

If you have [configured the Docker daemon to allow IPv6](https://docs.docker.com/engine/daemon/ipv6/), you can use dual-stack IPv4/IPv6 `macvlan` networks.

```console
$ docker network create -d macvlan \
    --subnet=192.168.216.0/24 --subnet=192.168.218.0/24 \
    --gateway=192.168.216.1 --gateway=192.168.218.1 \
    --subnet=2001:db8:abc8::/64 --gateway=2001:db8:abc8::10 \
     -o parent=eth0.218 \
     -o macvlan_mode=bridge macvlan216
```

## [Usage examples](#usage-examples)

This section provides hands-on examples for working with macvlan networks, including bridge mode and 802.1Q trunk bridge mode.

> Note
>
> These examples assume your ethernet interface is `eth0`. If your device has a different name, use that instead.

### [Bridge mode example](#bridge-mode-example)

In bridge mode, your traffic flows through `eth0` and Docker routes traffic to your container using its MAC address. To network devices on your network, your container appears to be physically attached to the network.

1. Create a macvlan network called `my-macvlan-net`. Modify the `subnet`, `gateway`, and `parent` values to match your environment:

   ```console
   $ docker network create -d macvlan \
     --subnet=172.16.86.0/24 \
     --gateway=172.16.86.1 \
     -o parent=eth0 \
     my-macvlan-net
   ```

   Verify the network was created:

   ```console
   $ docker network ls
   $ docker network inspect my-macvlan-net
   ```

2. Start an `alpine` container and attach it to the `my-macvlan-net` network. The `-dit` flags start the container in the background. The `--rm` flag removes the container when it stops:

   ```console
   $ docker run --rm -dit \
     --network my-macvlan-net \
     --name my-macvlan-alpine \
     alpine:latest \
     ash
   ```

3. Inspect the container and notice the `MacAddress` key within the `Networks` section:

   ```console
   $ docker container inspect my-macvlan-alpine
   ```

   Look for output similar to:

   ```json
   "Networks": {
     "my-macvlan-net": {
       "Gateway": "172.16.86.1",
       "IPAddress": "172.16.86.2",
       "IPPrefixLen": 24,
       "MacAddress": "02:42:ac:10:56:02",
       ...
     }
   }
   ```

4. Check how the container sees its own network interfaces:

   ```console
   $ docker exec my-macvlan-alpine ip addr show eth0

   9: eth0@tunl0: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP
   link/ether 02:42:ac:10:56:02 brd ff:ff:ff:ff:ff:ff
   inet 172.16.86.2/24 brd 172.16.86.255 scope global eth0
      valid_lft forever preferred_lft forever
   ```

   Check the routing table:

   ```console
   $ docker exec my-macvlan-alpine ip route

   default via 172.16.86.1 dev eth0
   172.16.86.0/24 dev eth0 scope link  src 172.16.86.2
   ```

5. Stop the container (Docker removes it automatically) and remove the network:

   ```console
   $ docker container stop my-macvlan-alpine
   $ docker network rm my-macvlan-net
   ```

### [802.1Q trunked bridge mode example](#8021q-trunked-bridge-mode-example)

In 802.1Q trunk bridge mode, your traffic flows through a sub-interface of `eth0` (called `eth0.10`) and Docker routes traffic to your container using its MAC address. To network devices on your network, your container appears to be physically attached to the network.

1. Create a macvlan network called `my-8021q-macvlan-net`. Modify the `subnet`, `gateway`, and `parent` values to match your environment:

   ```console
   $ docker network create -d macvlan \
     --subnet=172.16.86.0/24 \
     --gateway=172.16.86.1 \
     -o parent=eth0.10 \
     my-8021q-macvlan-net
   ```

   Verify the network was created and has parent `eth0.10`. You can use `ip addr show` on the Docker host to verify that the interface `eth0.10` exists:

   ```console
   $ docker network ls
   $ docker network inspect my-8021q-macvlan-net
   ```

2. Start an `alpine` container and attach it to the `my-8021q-macvlan-net` network:

   ```console
   $ docker run --rm -itd \
     --network my-8021q-macvlan-net \
     --name my-second-macvlan-alpine \
     alpine:latest \
     ash
   ```

3. Inspect the container and notice the `MacAddress` key:

   ```console
   $ docker container inspect my-second-macvlan-alpine
   ```

   Look for the `Networks` section with the MAC address.

4. Check how the container sees its own network interfaces:

   ```console
   $ docker exec my-second-macvlan-alpine ip addr show eth0

   11: eth0@if10: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP
   link/ether 02:42:ac:10:56:02 brd ff:ff:ff:ff:ff:ff
   inet 172.16.86.2/24 brd 172.16.86.255 scope global eth0
      valid_lft forever preferred_lft forever
   ```

   Check the routing table:

   ```console
   $ docker exec my-second-macvlan-alpine ip route

   default via 172.16.86.1 dev eth0
   172.16.86.0/24 dev eth0 scope link  src 172.16.86.2
   ```

5. Stop the container and remove the network:

   ```console
   $ docker container stop my-second-macvlan-alpine
   $ docker network rm my-8021q-macvlan-net
   ```

----
url: https://docs.docker.com/reference/cli/docker/image/build/
----

# docker image build

***

| Description                                                               | Build an image from a Dockerfile                |
| ------------------------------------------------------------------------- | ----------------------------------------------- |
| Usage                                                                     | `docker image build [OPTIONS] PATH \| URL \| -` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker build` `docker builder build`           |

## [Description](#description)

> Important
>
> This page refers to the **legacy implementation** of `docker build`, using the legacy (pre-BuildKit) build backend. This configuration is only relevant if you're building Windows containers.
>
> For information about the default `docker build`, using Buildx, see [`docker buildx build`](/reference/cli/docker/buildx/build/).

When building with legacy builder, images are created from a Dockerfile by running a sequence of [commits](/reference/cli/docker/container/commit/). This process is inefficient and slow compared to using BuildKit, which is why this build strategy is deprecated for all use cases except for building Windows containers. It's still useful for building Windows containers because BuildKit doesn't yet have full feature parity for Windows.

Builds invoked with `docker build` use Buildx (and BuildKit) by default, unless:

* You're running Docker Engine in Windows container mode
* You explicitly opt out of using BuildKit by setting the environment variable `DOCKER_BUILDKIT=0`.

The descriptions on this page only covers information that's exclusive to the legacy builder, and cases where behavior in the legacy builder deviates from behavior in BuildKit. For information about features and flags that are common between the legacy builder and BuildKit, such as `--tag` and `--target`, refer to the documentation for [`docker buildx build`](/reference/cli/docker/buildx/build/).

### [Build context with the legacy builder](#build-context-with-the-legacy-builder)

The build context is the positional argument you pass when invoking the build command. In the following example, the context is `.`, meaning current the working directory.

```console
$ docker build .
```

When using the legacy builder, the build context is sent over to the daemon in its entirety. With BuildKit, only the files you use in your builds are transmitted. The legacy builder doesn't calculate which files it needs beforehand. This means that for builds with a large context, context transfer can take a long time, even if you're only using a subset of the files included in the context.

When using the legacy builder, it's therefore extra important that you carefully consider what files you include in the context you specify. Use a [`.dockerignore`](/build/concepts/context/#dockerignore-files) file to exclude files and directories that you don't require in your build from being sent as part of the build context.

#### [Accessing paths outside the build context](#accessing-paths-outside-the-build-context)

The legacy builder will error out if you try to access files outside of the build context using relative paths in your Dockerfile.

```dockerfile
FROM alpine
COPY ../../some-dir .
```

```console
$ docker build .
...
Step 2/2 : COPY ../../some-dir .
COPY failed: forbidden path outside the build context: ../../some-dir ()
```

BuildKit on the other hand strips leading relative paths that traverse outside of the build context. Reusing the previous example, the path `COPY ../../some-dir .` evaluates to `COPY some-dir .` with BuildKit.

## [Options](#options)

| Option                                                                 | Default | Description                                                                       |
| ---------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------- |
| [`--add-host`](/reference/cli/docker/buildx/build/#add-host)           |         | Add a custom host-to-IP mapping (`host:ip`)                                       |
| [`--build-arg`](/reference/cli/docker/buildx/build/#build-arg)         |         | Set build-time variables                                                          |
| `--cache-from`                                                         |         | Images to consider as cache sources                                               |
| [`--cgroup-parent`](/reference/cli/docker/buildx/build/#cgroup-parent) |         | Set the parent cgroup for the `RUN` instructions during build                     |
| `--compress`                                                           |         | Compress the build context using gzip                                             |
| `--cpu-period`                                                         |         | Limit the CPU CFS (Completely Fair Scheduler) period                              |
| `--cpu-quota`                                                          |         | Limit the CPU CFS (Completely Fair Scheduler) quota                               |
| `-c, --cpu-shares`                                                     |         | CPU shares (relative weight)                                                      |
| `--cpuset-cpus`                                                        |         | CPUs in which to allow execution (0-3, 0,1)                                       |
| `--cpuset-mems`                                                        |         | MEMs in which to allow execution (0-3, 0,1)                                       |
| [`-f, --file`](/reference/cli/docker/buildx/build/#file)               |         | Name of the Dockerfile (Default is `PATH/Dockerfile`)                             |
| `--force-rm`                                                           |         | Always remove intermediate containers                                             |
| `--iidfile`                                                            |         | Write the image ID to the file                                                    |
| [`--isolation`](#isolation)                                            |         | Container isolation technology                                                    |
| `--label`                                                              |         | Set metadata for an image                                                         |
| `-m, --memory`                                                         |         | Memory limit                                                                      |
| `--memory-swap`                                                        |         | Swap limit equal to memory plus swap: -1 to enable unlimited swap                 |
| [`--network`](/reference/cli/docker/buildx/build/#network)             |         | API 1.25+ Set the networking mode for the RUN instructions during build           |
| `--no-cache`                                                           |         | Do not use cache when building the image                                          |
| `--platform`                                                           |         | API 1.38+ Set platform if server is multi-platform capable                        |
| `--pull`                                                               |         | Always attempt to pull a newer version of the image                               |
| `-q, --quiet`                                                          |         | Suppress the build output and print image ID on success                           |
| `--rm`                                                                 | `true`  | Remove intermediate containers after a successful build                           |
| [`--security-opt`](#security-opt)                                      |         | Security options                                                                  |
| `--shm-size`                                                           |         | Size of `/dev/shm`                                                                |
| [`--squash`](#squash)                                                  |         | API 1.25+ experimental (daemon) Squash newly built layers into a single new layer |
| [`-t, --tag`](/reference/cli/docker/buildx/build/#tag)                 |         | Name and optionally a tag in the `name:tag` format                                |
| [`--target`](/reference/cli/docker/buildx/build/#target)               |         | Set the target build stage to build.                                              |
| `--ulimit`                                                             |         | Ulimit options                                                                    |

## [Examples](#examples)

### [Specify isolation technology for container (--isolation)](#isolation)

This option is useful in situations where you are running Docker containers on Windows. The `--isolation=<value>` option sets a container's isolation technology. On Linux, the only supported is the `default` option which uses Linux namespaces. On Microsoft Windows, you can specify these values:

| Value     | Description                                                                                                                                                                    |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. |
| `process` | Namespace isolation only.                                                                                                                                                      |
| `hyperv`  | Hyper-V hypervisor partition-based isolation.                                                                                                                                  |

### [Optional security options (--security-opt)](#security-opt)

This flag is only supported on a daemon running on Windows, and only supports the `credentialspec` option. The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`.

### [Squash an image's layers (--squash) (experimental)](#squash)

#### [Overview](#overview)

> Note
>
> The `--squash` option is an experimental feature, and should not be considered stable.

Once the image is built, this flag squashes the new layers into a new image with a single new layer. Squashing doesn't destroy any existing image, rather it creates a new image with the content of the squashed layers. This effectively makes it look like all `Dockerfile` commands were created with a single layer. The `--squash` flag preserves the build cache.

Squashing layers can be beneficial if your Dockerfile produces multiple layers modifying the same files. For example, files created in one step and removed in another step. For other use-cases, squashing images may actually have a negative impact on performance. When pulling an image consisting of multiple layers, the daemon can pull layers in parallel and allows sharing layers between images (saving space).

For most use cases, multi-stage builds are a better alternative, as they give more fine-grained control over your build, and can take advantage of future optimizations in the builder. Refer to the [Multi-stage builds](/build/building/multi-stage/) section for more information.

#### [Known limitations](#known-limitations)

The `--squash` option has a number of known limitations:

* When squashing layers, the resulting image can't take advantage of layer sharing with other images, and may use significantly more space. Sharing the base image is still supported.
* When using this option you may see significantly more space used due to storing two copies of the image, one for the build cache with all the cache layers intact, and one for the squashed version.
* While squashing layers may produce smaller images, it may have a negative impact on performance, as a single layer takes longer to extract, and you can't parallelize downloading a single layer.
* When attempting to squash an image that doesn't make changes to the filesystem (for example, the Dockerfile only contains `ENV` instructions), the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)).

#### [Prerequisites](#prerequisites)

The example on this page is using experimental mode in Docker 23.03.

You can enable experimental mode by using the `--experimental` flag when starting the Docker daemon or setting `experimental: true` in the `daemon.json` configuration file.

By default, experimental mode is disabled. To see the current configuration of the Docker daemon, use the `docker version` command and check the `Experimental` line in the `Engine` section:

```console
Client: Docker Engine - Community
 Version:           28.5.1
 API version:       1.51
 Go version:        go1.24.8
 Git commit:        e180ab8
 Built:             Wed Oct  8 12:16:17 2025
 OS/Arch:           darwin/arm64
 Context:           desktop-linux

Server: Docker Engine - Community
 Engine:
  Version:          28.5.1
  API version:      1.51 (minimum version 1.24)
  Go version:       go1.24.8
  Git commit:       f8215cc
  Built:            Wed Oct  8 12:18:25 2025
  OS/Arch:          linux/arm64
  Experimental:     true
 [...]
```

#### [Build an image with the `--squash` flag](#build-an-image-with-the---squash-flag)

The following is an example of a build with the `--squash` flag. Below is the `Dockerfile`:

```dockerfile
FROM busybox
RUN echo hello > /hello
RUN echo world >> /hello
RUN touch remove_me /remove_me
ENV HELLO=world
RUN rm /remove_me
```

Next, build an image named `test` using the `--squash` flag.

```console
$ docker build --squash -t test .
```

After the build completes, the history looks like the below. The history could show that a layer's name is `<missing>`, and there is a new layer with COMMENT `merge`.

```console
$ docker history test

IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
4e10cb5b4cac        3 seconds ago                                                       12 B                merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb
<missing>           5 minutes ago       /bin/sh -c rm /remove_me                        0 B
<missing>           5 minutes ago       /bin/sh -c #(nop) ENV HELLO=world               0 B
<missing>           5 minutes ago       /bin/sh -c touch remove_me /remove_me           0 B
<missing>           5 minutes ago       /bin/sh -c echo world >> /hello                 0 B
<missing>           6 minutes ago       /bin/sh -c echo hello > /hello                  0 B
<missing>           7 weeks ago         /bin/sh -c #(nop) CMD ["sh"]                    0 B
<missing>           7 weeks ago         /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff   1.113 MB
```

Test the image, check for `/remove_me` being gone, make sure `hello\nworld` is in `/hello`, make sure the `HELLO` environment variable's value is `world`.

----
url: https://docs.docker.com/get-started/introduction/develop-with-containers/
----

# Develop with containers

***

Table of contents

***

## [Explanation](#explanation)

Now that you have Docker Desktop installed, you are ready to do some application development. Specifically, you will do the following:

1. Clone and start a development project
2. Make changes to the backend and frontend
3. See the changes immediately

## [Try it out](#try-it-out)

In this hands-on guide, you'll learn how to develop with containers.

## [Start the project](#start-the-project)

1. To get started, either clone or [download the project as a ZIP file](https://github.com/docker/getting-started-todo-app/archive/refs/heads/main.zip) to your local machine.

   ```console
   $ git clone https://github.com/docker/getting-started-todo-app
   ```

   And after the project is cloned, navigate into the new directory created by the clone:

   ```console
   $ cd getting-started-todo-app
   ```

2. Once you have the project, start the development environment using Docker Compose.

   To start the project using the CLI, run the following command:

   ```console
   $ docker compose watch
   ```

   You will see an output that shows container images being pulled down, containers starting, and more. Don't worry if you don't understand it all at this point. But, within a moment or two, things should stabilize and finish.

3. Open your browser to <http://localhost> to see the application up and running. It may take a few minutes for the app to run. The app is a simple to-do application, so feel free to add an item or two, mark some as done, or even delete an item.

### [What's in the environment?](#whats-in-the-environment)

Now that the environment is up and running, what's actually in it? At a high-level, there are several containers (or processes) that each serve a specific need for the application:

* React frontend - a Node container that's running the React dev server, using [Vite](https://vitejs.dev/).
* Node backend - the backend provides an API that provides the ability to retrieve, create, and delete to-do items.
* MySQL database - a database to store the list of the items.
* phpMyAdmin - a web-based interface to interact with the database that is accessible at <http://db.localhost>.
* Traefik proxy - [Traefik](https://traefik.io/traefik/) is an application proxy that routes requests to the right service. It sends all requests for `localhost/api/*` to the backend, requests for `localhost/*` to the frontend, and then requests for `db.localhost` to phpMyAdmin. This provides the ability to access all applications using port 80 (instead of different ports for each service).

With this environment, you as the developer don’t need to install or configure any services, populate a database schema, configure database credentials, or anything. You only need Docker Desktop. The rest just works.

## [Make changes to the app](#make-changes-to-the-app)

With this environment up and running, you’re ready to make a few changes to the application and see how Docker helps provide a fast feedback loop.

### [Change the greeting](#change-the-greeting)

The greeting at the top of the page is populated by an API call at `/api/greeting`. Currently, it always returns "Hello world!". You’ll now modify it to return one of three randomized messages (that you'll get to choose).

1. Open the `backend/src/routes/getGreeting.js` file in a text editor on your local machine (in the cloned project directory). This file provides the handler for the API endpoint. Your changes will automatically sync to the running container.

2. Modify the variable at the top to an array of greetings. Feel free to use the following modifications or customize it to your own liking. Also, update the endpoint to send a random greeting from this list.

   |                                          |                                                                                                                                                                                                                                               |
   | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | ```
    1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   ``` | ```js
   const GREETINGS = [
     "Whalecome!",
     "All hands on deck!",
     "Charting the course ahead!",
   ];

   module.exports = async (req, res) => {
     res.send({
       greeting: GREETINGS[Math.floor(Math.random() * GREETINGS.length)],
     });
   };
   ``` |

3. If you haven't done so yet, save the file. If you refresh your browser, you should see a new greeting. If you keep refreshing, you should see all of the messages appear.

### [Change the placeholder text](#change-the-placeholder-text)

When you look at the app, you'll see the placeholder text is simply "New Item". You’ll now make that a little more descriptive and fun. You’ll also make a few changes to the styling of the app too.

1. Open the `client/src/components/AddNewItemForm.jsx` file in your local project directory. This provides the component to add a new item to the to-do list.

2. Modify the `placeholder` attribute of the `Form.Control` element to whatever you'd like to display.

   |                              |                                                                                                                                                                           |
   | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | ```
   33
   34
   35
   36
   37
   38
   39
   ``` | ```js
   <Form.Control
     value={newItem}
     onChange={(e) => setNewItem(e.target.value)}
     type="text"
     placeholder="What do you need to do?"
     aria-label="New item"
   />
   ``` |

3. Save the file and go back to your browser. You should see the change already hot-reloaded into your browser. If you don't like it, feel free to tweak it until it looks just right.

### [Change the background color](#change-the-background-color)

Before you consider the application finalized, you need to make the colors better.

1. Open the `client/src/index.scss` file in your local project directory.

2. Adjust the `background-color` attribute to any color you'd like. The provided snippet is a soft blue to go along with Docker's nautical theme.

   If you're using an IDE, you can pick a color using the integrated color pickers. Otherwise, feel free to use an online [Color Picker](https://www.w3schools.com/colors/colors_picker.asp).

   |                   |                                                                                             |
   | ----------------- | ------------------------------------------------------------------------------------------- |
   | ```
   3
   4
   5
   6
   7
   ``` | ```css
   body {
     background-color: #99bbff;
     margin-top: 50px;
     font-family: "Lato";
   }
   ``` |

   Each save should let you see the change immediately in the browser. Keep adjusting it until it's the perfect setup for you.

And with that, you're done. Congrats on updating your website.

## [Recap](#recap)

Before you move on, take a moment and reflect on what happened here. Within a few moments, you were able to:

* Start a complete development project with zero installation effort. The containerized environment provided the development environment, ensuring you have everything you need. You didn't have to install Node, MySQL, or any of the other dependencies directly on your machine. All you needed was Docker Desktop and a code editor.

* Make changes and see them immediately. This was made possible because

  1. the processes running in each container are watching and responding to file changes and 2) the files in your local project directory are shared with the containerized environment, so edits you make locally are automatically synced to the containers.

Docker Desktop enables all of this and so much more. Once you start thinking with containers, you can create almost any environment and easily share it with your team.

## [Next steps](#next-steps)

Now that the application has been updated, you’re ready to learn about packaging it as a container image and pushing it to a registry, specifically Docker Hub.

[Build and push your first image](https://docs.docker.com/get-started/introduction/build-and-push-first-image/)

----
url: https://docs.docker.com/get-started/introduction/whats-next/
----

# What's next

***

***

The following sections provide step-by-step guides to help you understand core Docker concepts, building images, and running containers.

## [The basics](#the-basics)

Get started learning the core concepts of containers, images, registries, and Docker Compose.

### [What is a container?](/get-started/docker-concepts/the-basics/what-is-a-container/)

[Learn how to run your first container.](/get-started/docker-concepts/the-basics/what-is-a-container/)

### [What is an image?](/get-started/docker-concepts/the-basics/what-is-an-image/)

[Learn the basics of image layers.](/get-started/docker-concepts/the-basics/what-is-an-image/)

### [What is a registry?](/get-started/docker-concepts/the-basics/what-is-a-registry/)

[Learn about container registries, explore their interoperability, and interact with registries.](/get-started/docker-concepts/the-basics/what-is-a-registry/)

### [What is Docker Compose?](/get-started/docker-concepts/the-basics/what-is-docker-compose/)

[Gain a better understanding of Docker Compose.](/get-started/docker-concepts/the-basics/what-is-docker-compose/)

## [Building images](#building-images)

Craft optimized container images with Dockerfiles, build cache, and multi-stage builds.

### [Understanding image layers](/get-started/docker-concepts/building-images/understanding-image-layers/)

[Learn about the layers of container images.](/get-started/docker-concepts/building-images/understanding-image-layers/)

### [Writing a Dockerfile](/get-started/docker-concepts/building-images/writing-a-dockerfile/)

[Learn how to create an image using a Dockerfile.](/get-started/docker-concepts/building-images/writing-a-dockerfile/)

### [Build, tag and publish an image](/get-started/docker-concepts/building-images/build-tag-and-publish-an-image/)

[Learn how to build, tag, and publish an image to Docker Hub or any other registry.](/get-started/docker-concepts/building-images/build-tag-and-publish-an-image/)

### [Using the build cache](/get-started/docker-concepts/building-images/using-the-build-cache/)

[Learn about the build cache, what changes invalidate the cache, and how to effectively use the build cache.](/get-started/docker-concepts/building-images/using-the-build-cache/)

### [Multi-stage builds](/get-started/docker-concepts/building-images/multi-stage-builds/)

[Get a better understanding of multi-stage builds and their benefits.](/get-started/docker-concepts/building-images/multi-stage-builds/)

## [Running containers](#running-containers)

Master essential techniques for exposing ports, overriding defaults, persisting data, sharing files, and managing multi-container applications.

### [Publishing ports](/get-started/docker-concepts/running-containers/publishing-ports/)

[Understand the significance of publishing and exposing ports in Docker.](/get-started/docker-concepts/running-containers/publishing-ports/)

### [Overriding container defaults](/get-started/docker-concepts/running-containers/overriding-container-defaults/)

[Learn how to override the container defaults using the `docker run` command.](/get-started/docker-concepts/running-containers/overriding-container-defaults/)

### [Persisting container data](/get-started/docker-concepts/running-containers/persisting-container-data/)

[Learn the significance of data persistence in Docker.](/get-started/docker-concepts/running-containers/persisting-container-data/)

### [Sharing local files with containers](/get-started/docker-concepts/running-containers/sharing-local-files/)

[Explore the various storage options available in Docker and their common usage.](/get-started/docker-concepts/running-containers/sharing-local-files/)

### [Multi-container applications](/get-started/docker-concepts/running-containers/multi-container-applications/)

[Learn the significance of multi-container applications and how they're different from single-container applications.](/get-started/docker-concepts/running-containers/multi-container-applications/)

----
url: https://docs.docker.com/reference/cli/docker/config/
----

# docker config

***

| Description | Manage Swarm configs |
| ----------- | -------------------- |
| Usage       | `docker config`      |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Manage configs.

## [Subcommands](#subcommands)

| Command                                                                                 | Description                                         |
| --------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [`docker config create`](https://docs.docker.com/reference/cli/docker/config/create/)   | Create a config from a file or STDIN                |
| [`docker config inspect`](https://docs.docker.com/reference/cli/docker/config/inspect/) | Display detailed information on one or more configs |
| [`docker config ls`](https://docs.docker.com/reference/cli/docker/config/ls/)           | List configs                                        |
| [`docker config rm`](https://docs.docker.com/reference/cli/docker/config/rm/)           | Remove one or more configs                          |

----
url: https://docs.docker.com/reference/cli/docker/container/update/
----

# docker container update

***

| Description                                                               | Update configuration of one or more containers               |
| ------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Usage                                                                     | `docker container update [OPTIONS] CONTAINER [CONTAINER...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker update`                                              |

## [Description](#description)

The `docker update` command dynamically updates container configuration. You can use this command to prevent containers from consuming too many resources from their Docker host. With a single command, you can place limits on a single container or on many. To specify more than one container, provide space-separated list of container names or IDs.

> Warning
>
> The `docker update` and `docker container update` commands are not supported for Windows containers.

## [Options](#options)

| Option                            | Default | Description                                                                   |
| --------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `--blkio-weight`                  |         | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)  |
| `--cpu-period`                    |         | Limit CPU CFS (Completely Fair Scheduler) period                              |
| `--cpu-quota`                     |         | Limit CPU CFS (Completely Fair Scheduler) quota                               |
| `--cpu-rt-period`                 |         | API 1.25+ Limit the CPU real-time period in microseconds                      |
| `--cpu-rt-runtime`                |         | API 1.25+ Limit the CPU real-time runtime in microseconds                     |
| [`-c, --cpu-shares`](#cpu-shares) |         | CPU shares (relative weight)                                                  |
| `--cpus`                          |         | API 1.29+ Number of CPUs                                                      |
| `--cpuset-cpus`                   |         | CPUs in which to allow execution (0-3, 0,1)                                   |
| `--cpuset-mems`                   |         | MEMs in which to allow execution (0-3, 0,1)                                   |
| [`-m, --memory`](#memory)         |         | Memory limit                                                                  |
| `--memory-reservation`            |         | Memory soft limit                                                             |
| `--memory-swap`                   |         | Swap limit equal to memory plus swap: -1 to enable unlimited swap             |
| `--pids-limit`                    |         | API 1.40+ Tune container pids limit (set -1 for unlimited)                    |
| [`--restart`](#restart)           |         | Restart policy to apply when a container exits                                |

## [Examples](#examples)

The following sections illustrate ways to use this command.

### [Update a container's cpu-shares (--cpu-shares)](#cpu-shares)

To limit a container's cpu-shares to 512, first identify the container name or ID. You can use `docker ps` to find these values. You can also use the ID returned from the `docker run` command. Then, do the following:

```console
$ docker update --cpu-shares 512 abebf7571666
```

### [Update a container with cpu-shares and memory (-m, --memory)](#memory)

To update multiple resource configurations for multiple containers:

```console
$ docker update --cpu-shares 512 -m 300M abebf7571666 hopeful_morse
```

### [Update a container's restart policy (--restart)](#restart)

You can change a container's restart policy on a running container. The new restart policy takes effect instantly after you run `docker update` on a container.

To update restart policy for one or more containers:

```console
$ docker update --restart=on-failure:3 abebf7571666 hopeful_morse
```

Note that if the container is started with `--rm` flag, you cannot update the restart policy for it. The `AutoRemove` and `RestartPolicy` are mutually exclusive for the container.

----
url: https://docs.docker.com/reference/cli/docker/mcp/feature/
----

# docker mcp feature

***

| Description | Manage experimental features |
| ----------- | ---------------------------- |

## [Description](#description)

Manage experimental features for Docker MCP Gateway.

Features are stored in your Docker configuration file (\~/.docker/config.json) and control optional functionality that may change in future versions.

## [Subcommands](#subcommands)

| Command                                                                                           | Description                                  |
| ------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [`docker mcp feature disable`](https://docs.docker.com/reference/cli/docker/mcp/feature/disable/) | Disable an experimental feature              |
| [`docker mcp feature enable`](https://docs.docker.com/reference/cli/docker/mcp/feature/enable/)   | Enable an experimental feature               |
| [`docker mcp feature list`](https://docs.docker.com/reference/cli/docker/mcp/feature/list/)       | List all available features and their status |
| [`docker mcp feature ls`](https://docs.docker.com/reference/cli/docker/mcp/feature/ls/)           | List all available features and their status |

----
url: https://docs.docker.com/reference/cli/docker/plugin/upgrade/
----

# docker plugin upgrade

***

| Description | Upgrade an existing plugin                        |
| ----------- | ------------------------------------------------- |
| Usage       | `docker plugin upgrade [OPTIONS] PLUGIN [REMOTE]` |

## [Description](#description)

Upgrades an existing plugin to the specified remote plugin image. If no remote is specified, Docker will re-pull the current image and use the updated version. All existing references to the plugin will continue to work. The plugin must be disabled before running the upgrade.

## [Options](#options)

| Option                    | Default | Description                                                            |
| ------------------------- | ------- | ---------------------------------------------------------------------- |
| `--grant-all-permissions` |         | Grant all permissions necessary to run the plugin                      |
| `--skip-remote-check`     |         | Do not check if specified remote plugin matches existing plugin image  |

## [Examples](#examples)

The following example installs `vieus/sshfs` plugin, uses it to create and use a volume, then upgrades the plugin.

```console
$ docker plugin install vieux/sshfs DEBUG=1

Plugin "vieux/sshfs:next" is requesting the following privileges:
 - network: [host]
 - device: [/dev/fuse]
 - capabilities: [CAP_SYS_ADMIN]
Do you grant the above permissions? [y/N] y
vieux/sshfs:next

$ docker volume create -d vieux/sshfs:next -o sshcmd=root@1.2.3.4:/tmp/shared -o password=XXX sshvolume

sshvolume

$ docker run -it -v sshvolume:/data alpine sh -c "touch /data/hello"

$ docker plugin disable -f vieux/sshfs:next

viex/sshfs:next

# Here docker volume ls doesn't show 'sshfsvolume', since the plugin is disabled
$ docker volume ls

DRIVER              VOLUME NAME

$ docker plugin upgrade vieux/sshfs:next vieux/sshfs:next

Plugin "vieux/sshfs:next" is requesting the following privileges:
 - network: [host]
 - device: [/dev/fuse]
 - capabilities: [CAP_SYS_ADMIN]
Do you grant the above permissions? [y/N] y
Upgrade plugin vieux/sshfs:next to vieux/sshfs:next

$ docker plugin enable vieux/sshfs:next

viex/sshfs:next

$ docker volume ls

DRIVER              VOLUME NAME
viuex/sshfs:next    sshvolume

$ docker run -it -v sshvolume:/data alpine sh -c "ls /data"

hello
```

----
url: https://docs.docker.com/engine/containers/gpu/
----

# GPU access

***

Table of contents

***

## [Access an NVIDIA GPU](#access-an-nvidia-gpu)

### [Prerequisites](#prerequisites)

Visit the official [NVIDIA drivers page](https://www.nvidia.com/Download/index.aspx) to download and install the proper drivers. Reboot your system once you have done so.

Verify that your GPU is running and accessible.

### [Install NVIDIA Container Toolkit](#install-nvidia-container-toolkit)

Follow the official NVIDIA Container Toolkit [installation instructions](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).

### [Expose GPUs for use](#expose-gpus-for-use)

Include the `--gpus` flag when you start a container to access GPU resources.

To expose all available GPUs:

```console
$ docker run -it --rm --gpus all ubuntu nvidia-smi
```

The output looks like the following:

```text
+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 535.288.01             Driver Version: 535.288.01   CUDA Version: 12.2     |
|-----------------------------------------+----------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|                                         |                      |               MIG M. |
|=========================================+======================+======================|
|   0  NVIDIA L4                      Off | 00000000:31:00.0 Off |                    0 |
| N/A   40C    P0              27W /  72W |      0MiB / 23034MiB |      4%      Default |
|                                         |                      |                  N/A |
+-----------------------------------------+----------------------+----------------------+

+---------------------------------------------------------------------------------------+
| Processes:                                                                            |
|  GPU   GI   CI        PID   Type   Process name                            GPU Memory |
|        ID   ID                                                             Usage      |
|=======================================================================================|
|  No running processes found                                                           |
+---------------------------------------------------------------------------------------+
```

The leftmost column in the GPU table shows the index of each GPU (`0` for the NVIDIA L4 in the previous example). Use these index numbers to target specific GPUs with the `device` option.

To expose a single GPU by index:

```console
$ docker run -it --rm --gpus device=0 ubuntu nvidia-smi
```

To expose a GPU by its UUID, first list UUIDs with `nvidia-smi -L`:

```console
$ nvidia-smi -L
GPU 0: NVIDIA L4 (UUID: GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a)
```

Then pass the UUID to `--gpus`:

```console
$ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubuntu nvidia-smi
```

On systems with multiple GPUs, you can expose several by index. The `device` value must be quoted because it contains a comma:

```console
$ docker run -it --rm --gpus '"device=0,2"' ubuntu nvidia-smi
```

This exposes the GPUs at index `0` and `2` — the first and third GPUs listed in `nvidia-smi` output.

> Note
>
> NVIDIA GPUs can only be accessed by systems running a single engine.

### [Set NVIDIA capabilities](#set-nvidia-capabilities)

You can set capabilities manually. For example, on Ubuntu you can run the following:

```console
$ docker run --gpus 'all,capabilities=utility' --rm ubuntu nvidia-smi
```

This enables the `utility` driver capability which adds the `nvidia-smi` tool to the container.

Capabilities and other configurations can be set in images via environment variables. For valid variables, see the [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html) documentation. These variables can be set in a Dockerfile.

You can also use CUDA images, which set these variables automatically. See the official [CUDA images](https://catalog.ngc.nvidia.com/orgs/nvidia/containers/cuda) NGC catalog page.

----
url: https://docs.docker.com/reference/cli/docker/service/update/
----

# docker service update

***

| Description | Update a service                          |
| ----------- | ----------------------------------------- |
| Usage       | `docker service update [OPTIONS] SERVICE` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Updates a service as described by the specified parameters. The parameters are the same as [`docker service create`](/reference/cli/docker/service/create/). Refer to the description there for further information.

Normally, updating a service will only cause the service's tasks to be replaced with new ones if a change to the service requires recreating the tasks for it to take effect. For example, only changing the `--update-parallelism` setting will not recreate the tasks, because the individual tasks are not affected by this setting. However, the `--force` flag will cause the tasks to be recreated anyway. This can be used to perform a rolling restart without any changes to the service parameters.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                                        | Default | Description                                                                                                    |
| --------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `--args`                                      |         | Service command args                                                                                           |
| `--cap-add`                                   |         | API 1.41+ Add Linux capabilities                                                                               |
| `--cap-drop`                                  |         | API 1.41+ Drop Linux capabilities                                                                              |
| `--config-add`                                |         | API 1.30+ Add or update a config file on a service                                                             |
| `--config-rm`                                 |         | API 1.30+ Remove a configuration file                                                                          |
| `--constraint-add`                            |         | Add or update a placement constraint                                                                           |
| `--constraint-rm`                             |         | Remove a constraint                                                                                            |
| `--container-label-add`                       |         | Add or update a container label                                                                                |
| `--container-label-rm`                        |         | Remove a container label by its key                                                                            |
| `--credential-spec`                           |         | API 1.29+ Credential spec for managed service account (Windows only)                                           |
| `-d, --detach`                                |         | API 1.29+ Exit immediately instead of waiting for the service to converge                                      |
| `--dns-add`                                   |         | API 1.25+ Add or update a custom DNS server                                                                    |
| `--dns-option-add`                            |         | API 1.25+ Add or update a DNS option                                                                           |
| `--dns-option-rm`                             |         | API 1.25+ Remove a DNS option                                                                                  |
| `--dns-rm`                                    |         | API 1.25+ Remove a custom DNS server                                                                           |
| `--dns-search-add`                            |         | API 1.25+ Add or update a custom DNS search domain                                                             |
| `--dns-search-rm`                             |         | API 1.25+ Remove a DNS search domain                                                                           |
| `--endpoint-mode`                             |         | Endpoint mode (vip or dnsrr)                                                                                   |
| `--entrypoint`                                |         | Overwrite the default ENTRYPOINT of the image                                                                  |
| `--env-add`                                   |         | Add or update an environment variable                                                                          |
| `--env-rm`                                    |         | Remove an environment variable                                                                                 |
| `--force`                                     |         | API 1.25+ Force update even if no changes require it                                                           |
| `--generic-resource-add`                      |         | API 1.32+ Add a Generic resource                                                                               |
| `--generic-resource-rm`                       |         | API 1.32+ Remove a Generic resource                                                                            |
| `--group-add`                                 |         | API 1.25+ Add an additional supplementary user group to the container                                          |
| `--group-rm`                                  |         | API 1.25+ Remove a previously added supplementary user group from the container                                |
| `--health-cmd`                                |         | API 1.25+ Command to run to check health                                                                       |
| `--health-interval`                           |         | API 1.25+ Time between running the check (ms\|s\|m\|h)                                                         |
| `--health-retries`                            |         | API 1.25+ Consecutive failures needed to report unhealthy                                                      |
| `--health-start-interval`                     |         | API 1.44+ Time between running the check during the start period (ms\|s\|m\|h)                                 |
| `--health-start-period`                       |         | API 1.29+ Start period for the container to initialize before counting retries towards unstable (ms\|s\|m\|h)  |
| `--health-timeout`                            |         | API 1.25+ Maximum time to allow one check to run (ms\|s\|m\|h)                                                 |
| `--host-add`                                  |         | API 1.25+ Add a custom host-to-IP mapping (`host:ip`)                                                          |
| `--host-rm`                                   |         | API 1.25+ Remove a custom host-to-IP mapping (`host:ip`)                                                       |
| `--hostname`                                  |         | API 1.25+ Container hostname                                                                                   |
| `--image`                                     |         | Service image tag                                                                                              |
| `--init`                                      |         | API 1.37+ Use an init inside each service container to forward signals and reap processes                      |
| [`--isolation`](#isolation)                   |         | API 1.35+ Service container isolation mode                                                                     |
| `--label-add`                                 |         | Add or update a service label                                                                                  |
| `--label-rm`                                  |         | Remove a label by its key                                                                                      |
| `--limit-cpu`                                 |         | Limit CPUs                                                                                                     |
| `--limit-memory`                              |         | Limit Memory                                                                                                   |
| `--limit-pids`                                |         | API 1.41+ Limit maximum number of processes (default 0 = unlimited)                                            |
| `--log-driver`                                |         | Logging driver for service                                                                                     |
| `--log-opt`                                   |         | Logging driver options                                                                                         |
| `--max-concurrent`                            |         | API 1.41+ Number of job tasks to run concurrently (default equal to --replicas)                                |
| `--memory-swap`                               |         | API 1.52+ Swap Bytes (-1 for unlimited)                                                                        |
| `--memory-swappiness`                         | `-1`    | API 1.52+ Tune memory swappiness (0-100), -1 to reset to default                                               |
| [`--mount-add`](#mount-add)                   |         | Add or update a mount on a service                                                                             |
| `--mount-rm`                                  |         | Remove a mount by its target path                                                                              |
| [`--network-add`](#network-add)               |         | API 1.29+ Add a network                                                                                        |
| `--network-rm`                                |         | API 1.29+ Remove a network                                                                                     |
| `--no-healthcheck`                            |         | API 1.25+ Disable any container-specified HEALTHCHECK                                                          |
| `--no-resolve-image`                          |         | API 1.30+ Do not query the registry to resolve image digest and supported platforms                            |
| `--oom-score-adj`                             |         | API 1.46+ Tune host's OOM preferences (-1000 to 1000)                                                          |
| `--placement-pref-add`                        |         | API 1.28+ Add a placement preference                                                                           |
| `--placement-pref-rm`                         |         | API 1.28+ Remove a placement preference                                                                        |
| [`--publish-add`](#publish-add)               |         | Add or update a published port                                                                                 |
| `--publish-rm`                                |         | Remove a published port by its target port                                                                     |
| `-q, --quiet`                                 |         | Suppress progress output                                                                                       |
| `--read-only`                                 |         | API 1.28+ Mount the container's root filesystem as read only                                                   |
| `--replicas`                                  |         | Number of tasks                                                                                                |
| `--replicas-max-per-node`                     |         | API 1.40+ Maximum number of tasks per node (default 0 = unlimited)                                             |
| `--reserve-cpu`                               |         | Reserve CPUs                                                                                                   |
| `--reserve-memory`                            |         | Reserve Memory                                                                                                 |
| `--restart-condition`                         |         | Restart when condition is met (`none`, `on-failure`, `any`)                                                    |
| `--restart-delay`                             |         | Delay between restart attempts (ns\|us\|ms\|s\|m\|h)                                                           |
| `--restart-max-attempts`                      |         | Maximum number of restarts before giving up                                                                    |
| `--restart-window`                            |         | Window used to evaluate the restart policy (ns\|us\|ms\|s\|m\|h)                                               |
| [`--rollback`](#rollback)                     |         | API 1.25+ Rollback to previous specification                                                                   |
| `--rollback-delay`                            |         | API 1.28+ Delay between task rollbacks (ns\|us\|ms\|s\|m\|h)                                                   |
| `--rollback-failure-action`                   |         | API 1.28+ Action on rollback failure (`pause`, `continue`)                                                     |
| `--rollback-max-failure-ratio`                |         | API 1.28+ Failure rate to tolerate during a rollback                                                           |
| `--rollback-monitor`                          |         | API 1.28+ Duration after each task rollback to monitor for failure (ns\|us\|ms\|s\|m\|h)                       |
| `--rollback-order`                            |         | API 1.29+ Rollback order (`start-first`, `stop-first`)                                                         |
| `--rollback-parallelism`                      |         | API 1.28+ Maximum number of tasks rolled back simultaneously (0 to roll back all at once)                      |
| [`--secret-add`](#secret-add)                 |         | API 1.25+ Add or update a secret on a service                                                                  |
| `--secret-rm`                                 |         | API 1.25+ Remove a secret                                                                                      |
| `--stop-grace-period`                         |         | Time to wait before force killing a container (ns\|us\|ms\|s\|m\|h)                                            |
| `--stop-signal`                               |         | API 1.28+ Signal to stop the container                                                                         |
| `--sysctl-add`                                |         | API 1.40+ Add or update a Sysctl option                                                                        |
| `--sysctl-rm`                                 |         | API 1.40+ Remove a Sysctl option                                                                               |
| `-t, --tty`                                   |         | API 1.25+ Allocate a pseudo-TTY                                                                                |
| `--ulimit-add`                                |         | API 1.41+ Add or update a ulimit option                                                                        |
| `--ulimit-rm`                                 |         | API 1.41+ Remove a ulimit option                                                                               |
| `--update-delay`                              |         | Delay between updates (ns\|us\|ms\|s\|m\|h)                                                                    |
| `--update-failure-action`                     |         | Action on update failure (`pause`, `continue`, `rollback`)                                                     |
| `--update-max-failure-ratio`                  |         | API 1.25+ Failure rate to tolerate during an update                                                            |
| `--update-monitor`                            |         | API 1.25+ Duration after each task update to monitor for failure (ns\|us\|ms\|s\|m\|h)                         |
| `--update-order`                              |         | API 1.29+ Update order (`start-first`, `stop-first`)                                                           |
| [`--update-parallelism`](#update-parallelism) |         | Maximum number of tasks updated simultaneously (0 to update all at once)                                       |
| `-u, --user`                                  |         | Username or UID (format: \<name\|uid>\[:\<group\|gid>])                                                        |
| `--with-registry-auth`                        |         | Send registry authentication details to swarm agents                                                           |
| `-w, --workdir`                               |         | Working directory inside the container                                                                         |

## [Examples](#examples)

### [Update a service](#update-a-service)

```console
$ docker service update --limit-cpu 2 redis
```

### [Perform a rolling restart with no parameter changes](#update-parallelism)

```console
$ docker service update --force --update-parallelism 1 --update-delay 30s redis
```

In this example, the `--force` flag causes the service's tasks to be shut down and replaced with new ones even though none of the other parameters would normally cause that to happen. The `--update-parallelism 1` setting ensures that only one task is replaced at a time (this is the default behavior). The `--update-delay 30s` setting introduces a 30 second delay between tasks, so that the rolling restart happens gradually.

### [Add or remove mounts (--mount-add, --mount-rm)](#mount-add)

Use the `--mount-add` or `--mount-rm` options add or remove a service's bind mounts or volumes.

The following example creates a service which mounts the `test-data` volume to `/somewhere`. The next step updates the service to also mount the `other-volume` volume to `/somewhere-else`volume, The last step unmounts the `/somewhere` mount point, effectively removing the `test-data` volume. Each command returns the service name.

* The `--mount-add` flag takes the same parameters as the `--mount` flag on `service create`. Refer to the [volumes and bind mounts](/reference/cli/docker/service/create/#mount) section in the `service create` reference for details.

* The `--mount-rm` flag takes the `target` path of the mount.

```console
$ docker service create \
    --name=myservice \
    --mount type=volume,source=test-data,target=/somewhere \
    nginx:alpine

myservice

$ docker service update \
    --mount-add type=volume,source=other-volume,target=/somewhere-else \
    myservice

myservice

$ docker service update --mount-rm /somewhere myservice

myservice
```

### [Add or remove published service ports (--publish-add, --publish-rm)](#publish-add)

Use the `--publish-add` or `--publish-rm` flags to add or remove a published port for a service. You can use the short or long syntax discussed in the [docker service create](/reference/cli/docker/service/create/#publish) reference.

The following example adds a published service port to an existing service.

```console
$ docker service update \
  --publish-add published=8080,target=80 \
  myservice
```

### [Add or remove network (--network-add, --network-rm)](#network-add)

Use the `--network-add` or `--network-rm` flags to add or remove a network for a service. You can use the short or long syntax discussed in the [docker service create](/reference/cli/docker/service/create/#network) reference.

The following example adds a new alias name to an existing service already connected to network my-network:

```console
$ docker service update \
  --network-rm my-network \
  --network-add name=my-network,alias=web1 \
  myservice
```

### [Roll back to the previous version of a service (--rollback)](#rollback)

Use the `--rollback` option to roll back to the previous version of the service.

This will revert the service to the configuration that was in place before the most recent `docker service update` command.

The following example updates the number of replicas for the service from 4 to 5, and then rolls back to the previous configuration.

```console
$ docker service update --replicas=5 web

web

$ docker service ls

ID            NAME  MODE        REPLICAS  IMAGE
80bvrzp6vxf3  web   replicated  0/5       nginx:alpine
```

The following example rolls back the `web` service:

```console
$ docker service update --rollback web

web

$ docker service ls

ID            NAME  MODE        REPLICAS  IMAGE
80bvrzp6vxf3  web   replicated  0/4       nginx:alpine
```

Other options can be combined with `--rollback` as well, for example, `--update-delay 0s` to execute the rollback without a delay between tasks:

```console
$ docker service update \
  --rollback \
  --update-delay 0s
  web

web
```

Services can also be set up to roll back to the previous version automatically when an update fails. To set up a service for automatic rollback, use `--update-failure-action=rollback`. A rollback will be triggered if the fraction of the tasks which failed to update successfully exceeds the value given with `--update-max-failure-ratio`.

The rate, parallelism, and other parameters of a rollback operation are determined by the values passed with the following flags:

* `--rollback-delay`
* `--rollback-failure-action`
* `--rollback-max-failure-ratio`
* `--rollback-monitor`
* `--rollback-parallelism`

For example, a service set up with `--update-parallelism 1 --rollback-parallelism 3` will update one task at a time during a normal update, but during a rollback, 3 tasks at a time will get rolled back. These rollback parameters are respected both during automatic rollbacks and for rollbacks initiated manually using `--rollback`.

### [Add or remove secrets (--secret-add, --secret-rm)](#secret-add)

Use the `--secret-add` or `--secret-rm` options add or remove a service's secrets.

The following example adds a secret named `ssh-2` and removes `ssh-1`:

```console
$ docker service update \
    --secret-add source=ssh-2,target=ssh-2 \
    --secret-rm ssh-1 \
    myservice
```

### [Update services using templates](#update-services-using-templates)

Some flags of `service update` support the use of templating. See [`service create`](/reference/cli/docker/service/create/#create-services-using-templates) for the reference.

### [Specify isolation mode on Windows (--isolation)](#isolation)

`service update` supports the same `--isolation` flag as `service create` See [`service create`](/reference/cli/docker/service/create/) for the reference.

### [Updating Jobs](#updating-jobs)

When a service is created as a job, by setting its mode to `replicated-job` or to `global-job` when doing `service create`, options for updating it are limited.

Updating a Job immediately stops any Tasks that are in progress. The operation creates a new set of Tasks for the job and effectively resets its completion status. If any Tasks were running before the update, they are stopped, and new Tasks are created.

Jobs cannot be rolled out or rolled back. None of the flags for configuring update or rollback settings are valid with job modes.

To run a job again with the same parameters that it was run previously, it can be force updated with the `--force` flag.

----
url: https://docs.docker.com/desktop/use-desktop/kubernetes/
----

# Explore the Kubernetes view

***

Table of contents

***

Docker Desktop includes a standalone Kubernetes server and client, as well as Docker CLI integration, enabling local Kubernetes development and testing directly on your machine.

The Kubernetes server runs as a single or multi-node cluster, within Docker containers. This lightweight setup helps you explore Kubernetes features, test workloads, and work with container orchestration in parallel with other Docker features.

## [Enable Kubernetes](#enable-kubernetes)

With Docker Desktop version 4.51 and later, you can manage Kubernetes directly from the **Kubernetes** view in the Docker Desktop Dashboard.

1. Open the Docker Desktop Dashboard and select the **Kubernetes** view.

2. Select **Create cluster**.

3. Choose your cluster type:

   * **Kubeadm** creates a single-node cluster and the version is set by Docker Desktop.
   * **kind** creates a multi-node cluster and you can set the version and number of nodes. For more detailed information on each cluster type, see [Cluster provisioning method](#cluster-provisioning-method).

4. Optional: Select **Show system containers (advanced)** to view internal containers when using Docker commands.

5. Select **Create**.

This sets up the images required to run the Kubernetes server as containers, and installs the `kubectl` command-line tool on your system at `/usr/local/bin/kubectl` (Mac) or `C:\Program Files\Docker\Docker\resources\bin\kubectl.exe`(all-user installations) or `%LOCALAPPDATA%\Programs\DockerDesktop\resources\bin\kubectl.exe` (per-user installations) (Windows). If you installed `kubectl` using Homebrew, or by some other method, and experience conflicts, remove `/usr/local/bin/kubectl`.

> Note
>
> Docker Desktop for Linux does not include `kubectl` by default. You can install it separately by following the [Kubernetes installation guide](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/). Ensure the `kubectl` binary is installed at `/usr/local/bin/kubectl`.

The following actions are also triggered in the Docker Desktop backend and VM:

* Generation of certificates and cluster configuration
* Download and installation of Kubernetes internal components
* Cluster boot-up
* Installation of additional controllers for networking and storage

When Kubernetes is enabled, its status is displayed in the Docker Desktop Dashboard footer and the Docker menu.

You can check which version of Kubernetes you're on with:

```console
$ kubectl version
```

### [Cluster provisioning method](#cluster-provisioning-method)

Docker Desktop Kubernetes can be provisioned with either the `kubeadm` or `kind` provisioners.

`kubeadm` is the older provisioner. It supports a single-node cluster, you can't select the kubernetes version, it's slower to provision than `kind`, and it's not supported by [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) (ECI), meaning that if ECI is enabled the cluster works but it's not protected by ECI.

`kind` is the newer provisioner. It supports multi-node clusters (for a more realistic Kubernetes setup), you can choose the Kubernetes version, it's faster to provision than `kubeadm`, and it's supported by ECI - when ECI is enabled, the Kubernetes cluster runs in unprivileged Docker containers, thus making it more secure.

| Feature                           | `kubeadm` | `kind`       |
| --------------------------------- | --------- | ------------ |
| Multi-node cluster support        | No        | Yes          |
| Kubernetes version selector       | No        | Yes          |
| Speed to provision                | \~1 min   | \~30 seconds |
| Supported by ECI                  | No        | Yes          |
| Works with containerd image store | Yes       | Yes          |
| Works with Docker image store     | Yes       | No           |

## [Dashboard view](#dashboard-view)

When a Kubernetes cluster is enabled, the **Kubernetes** view displays a live dashboard view showing:

* A namespace selector at the top
* A real-time list of resources - pods, services, deployments - in the selected namespace
* Automatic updates when resources are created, deleted, or modified

## [Verify installation](#verify-installation)

Confirm that your cluster is running:

```console
$ kubectl get nodes
NAME                 STATUS    ROLES            AGE       VERSION
docker-desktop       Ready     control-plane    3h        v1.29.1
```

If kubectl is pointing to another environment, switch to the Docker Desktop context:

```console
$ kubectl config use-context docker-desktop
```

> Tip
>
> If no contexts appear, try:
>
> * Running the command in the Command Prompt or PowerShell.
> * Setting the `KUBECONFIG` environment variable to point to your `.kube/config` file.

For more information about `kubectl`, see the [`kubectl` documentation](https://kubernetes.io/docs/reference/kubectl/overview/).

## [Edit or stop your cluster](#edit-or-stop-your-cluster)

When Kubernetes is enabled:

* Select **Edit cluster** to modify configuration. For example, switch between **kubeadm** and **kind**, or change the number of nodes.
* Select **Stop** to disable the cluster. Progress is displayed, and the **Kubernetes** view returns to the **Create cluster** screen. This stops and removes Kubernetes containers, and also removes the `/usr/local/bin/kubectl` command.

## [Upgrade your cluster](#upgrade-your-cluster)

Kubernetes clusters are not automatically upgraded with Docker Desktop updates. To upgrade the cluster, you must manually select **Reset cluster** in the **Kubernetes** settings.

## [Configuring a custom image registry for Kubernetes control plane images](#configuring-a-custom-image-registry-for-kubernetes-control-plane-images)

Docker Desktop uses containers to run the Kubernetes control plane. By default, Docker Desktop pulls the associated container images from Docker Hub. The images pulled depend on the [cluster provisioning mode](#cluster-provisioning-method).

For example, in `kind` mode it requires the following images:

```console
docker.io/kindest/node:<tag>
docker.io/envoyproxy/envoy:<tag>
docker.io/docker/desktop-cloud-provider-kind:<tag>
docker.io/docker/desktop-containerd-registry-mirror:<tag>
```

In `kubeadm` mode it requires the following images:

```console
docker.io/docker/desktop-kubernetes:<tag>
docker.io/docker/desktop-storage-provisioner:<tag>
docker.io/docker/desktop-vpnkit-controller:<tag>
docker.io/docker/desktop-kubernetes-etcd:<tag>
docker.io/docker/desktop-kubernetes-coredns:<tag>
docker.io/docker/desktop-kubernetes-pause:<tag>
docker.io/docker/desktop-kubernetes-apiserver:<tag>
docker.io/docker/desktop-kubernetes-controller-manager:<tag>
docker.io/docker/desktop-kubernetes-scheduler:<tag>
docker.io/docker/desktop-kubernetes-proxy:<tag>
```

The image tags are automatically selected by Docker Desktop based on several factors, including the version of Kubernetes being used. The tags vary for each image and may change between Docker Desktop releases. To stay informed, monitor the Docker Desktop release notes.

> Note
>
> In Docker Desktop versions 4.44 or later you can run `docker desktop kubernetes images list` to list Kubernetes images used by the currently installed version of Docker Desktop. For more information, see the [Docker Desktop CLI](/reference/cli/docker/desktop/kubernetes/images).

To accommodate scenarios where access to Docker Hub is not allowed, admins can configure Docker Desktop to pull the above listed images from a different registry (e.g., a mirror) using the [KubernetesImagesRepository](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/#kubernetes) setting as follows.

An image name can be broken into `[registry[:port]/][namespace/]repository[:tag]` components. The `KubernetesImagesRepository` setting allows users to override the `[registry[:port]/][namespace]` portion of the image's name.

For example, if Docker Desktop Kubernetes is configured in `kind` mode and `KubernetesImagesRepository` is set to `my-registry:5000/kind-images`, then Docker Desktop will pull the images from:

```console
my-registry:5000/kind-images/node:<tag>
my-registry:5000/kind-images/envoy:<tag>
my-registry:5000/kind-images/desktop-cloud-provider-kind:<tag>
my-registry:5000/kind-images/desktop-containerd-registry-mirror:<tag>
```

These images should be cloned/mirrored from their respective images in Docker Hub. The tags must also match what Docker Desktop expects.

The recommended approach to set this up is the following:

1. Start Kubernetes using the desired cluster provisioning method: `kubeadm` or `kind`.

2. After Kubernetes has started, use either:

   * (Docker Desktop version 4.44 or later) `docker desktop kubernetes images list` to list the image tags that will be pulled by the current Docker Desktop installation
   * `docker ps` to view the container images used by Docker Desktop for the Kubernetes control plane

3. Clone or mirror those images (with matching tags) to your custom registry.

4. Stop the Kubernetes cluster.

5. Configure the `KubernetesImagesRepository` setting to point to your custom registry.

6. Restart Docker Desktop.

7. Verify that the Kubernetes cluster is using the custom registry images using the `docker ps` command.

> Note
>
> The `KubernetesImagesRepository` setting only applies to control plane images used by Docker Desktop to set up the Kubernetes cluster. It has no effect on other Kubernetes pods.

> Note
>
> In Docker Desktop versions 4.43 or earlier, when using `KubernetesImagesRepository` and [Enhanced Container Isolation (ECI)](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) is enabled, add the following images to the [ECI Docker socket mount image list](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/#enhanced-container-isolation):
>
> `[imagesRepository]/desktop-cloud-provider-kind:` `[imagesRepository]/desktop-containerd-registry-mirror:`
>
> These containers mount the Docker socket, so you must add the images to the ECI images list. If not, ECI will block the mount and Kubernetes won't start.

## [Troubleshooting](#troubleshooting)

* If Kubernetes fails to start, make sure Docker Desktop is running with enough allocated resources. Check **Settings** > **Resources**.
* If the `kubectl` commands return errors, confirm the context is set to `docker-desktop`
  ```console
  $ kubectl config use-context docker-desktop
  ```
  You can then try checking the logs of the Kubernetes system containers if you have enabled that setting.
* If you're experiencing cluster issues after updating, reset your Kubernetes cluster. Resetting a Kubernetes cluster can help resolve issues by essentially reverting the cluster to a clean state, and clearing out misconfigurations, corrupted data, or stuck resources that may be causing problems. If the issue still persists, you may need to clean and purge data, and then restart Docker Desktop.

----
url: https://docs.docker.com/guides/testcontainers-cloud/demo-ci/
----

# Configuring Testcontainers Cloud in the CI Pipeline

***

***

This demo shows how Testcontainers Cloud can be seamlessly integrated into a Continuous Integration (CI) pipeline using GitHub Workflows, providing a powerful solution for running containerized integration tests without overloading local or CI runner resources. By leveraging GitHub Actions, developers can automate the process of spinning up and managing containers for testing in the cloud, ensuring faster and more reliable test execution. With just a few configuration steps, including setting up Testcontainers Cloud authentication and adding it to your workflow, you can offload container orchestration to the cloud. This approach improves the scalability of your pipeline, ensures consistency across tests, and simplifies resource management, making it an ideal solution for modern, containerized development workflows.

* Understand how to set up a GitHub Actions workflow to automate the build and testing of a project.
* Learn how to configure Testcontainers Cloud within GitHub Actions to offload containerized testing to the cloud, improving efficiency and resource management.
* Explore how Testcontainers Cloud integrates with GitHub workflows to run integration tests that require containerized services, such as databases and message brokers.

[Common challenges and questions »](https://docs.docker.com/guides/testcontainers-cloud/common-questions/)

----
url: https://docs.docker.com/get-started/workshop/
----

# Overview of the Docker workshop

***

Table of contents

***

This 45-minute workshop contains step-by-step instructions on how to get started with Docker. This workshop shows you how to:

* Build and run an image as a container.
* Share images using Docker Hub.
* Deploy Docker applications using multiple containers with a database.
* Run applications using Docker Compose.

> Note
>
> For a quick introduction to Docker and the benefits of containerizing your applications, see [Getting started](https://docs.docker.com/get-started/introduction/).

## [What is a container?](#what-is-a-container)

A container is a sandboxed process running on a host machine that is isolated from all other processes running on that host machine. That isolation leverages [kernel namespaces and cgroups](https://medium.com/@saschagrunert/demystifying-containers-part-i-kernel-space-2c53d6979504), features that have been in Linux for a long time. Docker makes these capabilities approachable and easy to use. To summarize, a container:

* Is a runnable instance of an image. You can create, start, stop, move, or delete a container using the Docker API or CLI.
* Can be run on local machines, virtual machines, or deployed to the cloud.
* Is portable (and can be run on any OS).
* Is isolated from other containers and runs its own software, binaries, configurations, etc.

If you're familiar with `chroot`, then think of a container as an extended version of `chroot`. The filesystem comes from the image. However, a container adds additional isolation not available when using chroot.

## [What is an image?](#what-is-an-image)

A running container uses an isolated filesystem. This isolated filesystem is provided by an image, and the image must contain everything needed to run an application - all dependencies, configurations, scripts, binaries, etc. The image also contains other configurations for the container, such as environment variables, a default command to run, and other metadata.

## [Next steps](#next-steps)

In this section, you learned about containers and images.

Next, you'll containerize a simple application and get hands-on with the concepts.

[Containerize an application](https://docs.docker.com/get-started/workshop/02_our_app/)

----
url: https://docs.docker.com/engine/security/certificates/
----

# Verify repository client with certificates

***

Table of contents

***

In [Running Docker with HTTPS](https://docs.docker.com/engine/security/protect-access/), you learned that, by default, Docker runs via a non-networked Unix socket and TLS must be enabled in order to have the Docker client and the daemon communicate securely over HTTPS. TLS ensures authenticity of the registry endpoint and that traffic to/from registry is encrypted.

This article demonstrates how to ensure the traffic between the Docker registry server and the Docker daemon (a client of the registry server) is encrypted and properly authenticated using certificate-based client-server authentication.

We show you how to install a Certificate Authority (CA) root certificate for the registry and how to set the client TLS certificate for verification.

## [Understand the configuration](#understand-the-configuration)

A custom certificate is configured by creating a directory under `/etc/docker/certs.d` using the same name as the registry's hostname, such as `localhost`. All `*.crt` files are added to this directory as CA roots.

> Note
>
> On Linux any root certificates authorities are merged with the system defaults, including the host's root CA set. If you are running Docker on Windows Server, or Docker Desktop for Windows with Windows containers, the system default certificates are only used when no custom root certificates are configured.

The presence of one or more `<filename>.key/cert` pairs indicates to Docker that there are custom certificates required for access to the desired repository.

> Note
>
> If multiple certificates exist, each is tried in alphabetical order. If there is a 4xx-level or 5xx-level authentication error, Docker continues to try with the next certificate.

The following illustrates a configuration with custom certificates:

```text
    /etc/docker/certs.d/        <-- Certificate directory
    └── localhost:5000          <-- Hostname:port
       ├── client.cert          <-- Client certificate
       ├── client.key           <-- Client key
       └── ca.crt               <-- Root CA that signed
                                    the registry certificate, in PEM
```

The preceding example is operating-system specific and is for illustrative purposes only. You should consult your operating system documentation for creating an os-provided bundled certificate chain.

## [Create the client certificates](#create-the-client-certificates)

Use OpenSSL's `genrsa` and `req` commands to first generate an RSA key and then use the key to create the certificate.

```console
$ openssl genrsa -out client.key 4096
$ openssl req -new -x509 -text -key client.key -out client.cert
```

> Note
>
> These TLS commands only generate a working set of certificates on Linux. The version of OpenSSL in macOS is incompatible with the type of certificate Docker requires.

## [Troubleshooting tips](#troubleshooting-tips)

The Docker daemon interprets `.crt` files as CA certificates and `.cert` files as client certificates. If a CA certificate is accidentally given the extension `.cert` instead of the correct `.crt` extension, the Docker daemon logs the following error message:

```text
Missing key KEY_NAME for client certificate CERT_NAME. CA certificates should use the extension .crt.
```

If the Docker registry is accessed without a port number, do not add the port to the directory name. The following shows the configuration for a registry on default port 443 which is accessed with `docker login my-https.registry.example.com`:

```text
    /etc/docker/certs.d/
    └── my-https.registry.example.com          <-- Hostname without port
       ├── client.cert
       ├── client.key
       └── ca.crt
```

## [Related information](#related-information)

* [Use trusted images](https://docs.docker.com/engine/security/trust/)
* [Protect the Docker daemon socket](https://docs.docker.com/engine/security/protect-access/)

----
url: https://docs.docker.com/reference/cli/docker/compose/version/
----

# docker compose version

***

| Description | Show the Docker Compose version information |
| ----------- | ------------------------------------------- |
| Usage       | `docker compose version [OPTIONS]`          |

## [Description](#description)

Show the Docker Compose version information

## [Options](#options)

| Option         | Default | Description                                                     |
| -------------- | ------- | --------------------------------------------------------------- |
| `-f, --format` |         | Format the output. Values: \[pretty \| json]. (Default: pretty) |
| `--short`      |         | Shows only Compose's version number                             |

----
url: https://docs.docker.com/reference/cli/docker/container/stats/
----

# docker container stats

***

| Description                                                               | Display a live stream of container(s) resource usage statistics |
| ------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Usage                                                                     | `docker container stats [OPTIONS] [CONTAINER...]`               |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker stats`                                                  |

## [Description](#description)

The `docker stats` command returns a live data stream for running containers. To limit data to one or more specific containers, specify a list of container names or ids separated by a space. You can specify a stopped container but stopped containers do not return any data.

If you need more detailed information about a container's resource usage, use the `/containers/(id)/stats` API endpoint.

> Note
>
> On Linux, the Docker CLI reports memory usage by subtracting cache usage from the total memory usage. The API does not perform such a calculation but rather provides the total memory usage and the amount from the cache so that clients can use the data as needed. The cache usage is defined as the value of `total_inactive_file` field in the `memory.stat` file on cgroup v1 hosts.
>
> On Docker 19.03 and older, the cache usage was defined as the value of `cache` field. On cgroup v2 hosts, the cache usage is defined as the value of `inactive_file` field.

> Note
>
> The `PIDS` column contains the number of processes and kernel threads created by that container. Threads is the term used by Linux kernel. Other equivalent terms are "lightweight process" or "kernel task", etc. A large number in the `PIDS` column combined with a small number of processes (as reported by `ps` or `top`) may indicate that something in the container is creating many threads.

## [Options](#options)

| Option                | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-a, --all`           |         | Show all containers (default shows just running)                                                                                                                                                                                                                                                                                                                                       |
| [`--format`](#format) |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `--no-stream`         |         | Disable streaming stats and only pull the first result                                                                                                                                                                                                                                                                                                                                 |
| `--no-trunc`          |         | Do not truncate output                                                                                                                                                                                                                                                                                                                                                                 |

## [Examples](#examples)

Running `docker stats` on all running containers against a Linux daemon.

```console
$ docker stats

CONTAINER ID        NAME                                    CPU %               MEM USAGE / LIMIT     MEM %               NET I/O             BLOCK I/O           PIDS
b95a83497c91        awesome_brattain                        0.28%               5.629MiB / 1.952GiB   0.28%               916B / 0B           147kB / 0B          9
67b2525d8ad1        foobar                                  0.00%               1.727MiB / 1.952GiB   0.09%               2.48kB / 0B         4.11MB / 0B         2
e5c383697914        test-1951.1.kay7x1lh1twk9c0oig50sd5tr   0.00%               196KiB / 1.952GiB     0.01%               71.2kB / 0B         770kB / 0B          1
4bda148efbc0        random.1.vnc8on831idyr42slu578u3cr      0.00%               1.672MiB / 1.952GiB   0.08%               110kB / 0B          578kB / 0B          2
```

If you don't [specify a format string using `--format`](#format), the following columns are shown.

| Column name               | Description                                                                                  |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| `CONTAINER ID` and `Name` | the ID and name of the container                                                             |
| `CPU %` and `MEM %`       | the percentage of the host's CPU and memory the container is using                           |
| `MEM USAGE / LIMIT`       | the total memory the container is using, and the total amount of memory it is allowed to use |
| `NET I/O`                 | The amount of data the container has received and sent over its network interface            |
| `BLOCK I/O`               | The amount of data the container has written to and read from block devices on the host      |
| `PIDs`                    | the number of processes or threads the container has created                                 |

Running `docker stats` on multiple containers by name and id against a Linux daemon.

```console
$ docker stats awesome_brattain 67b2525d8ad1

CONTAINER ID        NAME                CPU %               MEM USAGE / LIMIT     MEM %               NET I/O             BLOCK I/O           PIDS
b95a83497c91        awesome_brattain    0.28%               5.629MiB / 1.952GiB   0.28%               916B / 0B           147kB / 0B          9
67b2525d8ad1        foobar              0.00%               1.727MiB / 1.952GiB   0.09%               2.48kB / 0B         4.11MB / 0B         2
```

Running `docker stats` on container with name `nginx` and getting output in `json` format.

```console
$ docker stats nginx --no-stream --format "{{ json . }}"
{"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"}
```

Running `docker stats` with customized format on all (running and stopped) containers.

```console
$ docker stats --all --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}" fervent_panini 5acfcb1b4fd1 humble_visvesvaraya big_heisenberg

CONTAINER                CPU %               MEM USAGE / LIMIT
fervent_panini           0.00%               56KiB / 15.57GiB
5acfcb1b4fd1             0.07%               32.86MiB / 15.57GiB
humble_visvesvaraya      0.00%               0B / 0B
big_heisenberg           0.00%               0B / 0B
```

`humble_visvesvaraya` and `big_heisenberg` are stopped containers in the above example.

Running `docker stats` on all running containers against a Windows daemon.

```powershell
PS E:\> docker stats
CONTAINER ID        CPU %               PRIV WORKING SET    NET I/O             BLOCK I/O
09d3bb5b1604        6.61%               38.21 MiB           17.1 kB / 7.73 kB   10.7 MB / 3.57 MB
9db7aa4d986d        9.19%               38.26 MiB           15.2 kB / 7.65 kB   10.6 MB / 3.3 MB
3f214c61ad1d        0.00%               28.64 MiB           64 kB / 6.84 kB     4.42 MB / 6.93 MB
```

Running `docker stats` on multiple containers by name and id against a Windows daemon.

```powershell
PS E:\> docker ps -a
CONTAINER ID        NAME                IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
3f214c61ad1d        awesome_brattain    nanoserver          "cmd"               2 minutes ago       Up 2 minutes                            big_minsky
9db7aa4d986d        mad_wilson          windowsservercore   "cmd"               2 minutes ago       Up 2 minutes                            mad_wilson
09d3bb5b1604        fervent_panini      windowsservercore   "cmd"               2 minutes ago       Up 2 minutes                            affectionate_easley

PS E:\> docker stats 3f214c61ad1d mad_wilson
CONTAINER ID        NAME                CPU %               PRIV WORKING SET    NET I/O             BLOCK I/O
3f214c61ad1d        awesome_brattain    0.00%               46.25 MiB           76.3 kB / 7.92 kB   10.3 MB / 14.7 MB
9db7aa4d986d        mad_wilson          9.59%               40.09 MiB           27.6 kB / 8.81 kB   17 MB / 20.1 MB
```

### [Format the output (--format)](#format)

The formatting option (`--format`) pretty prints container output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder  | Description                                  |
| ------------ | -------------------------------------------- |
| `.Container` | Container name or ID (user input)            |
| `.Name`      | Container name                               |
| `.ID`        | Container ID                                 |
| `.CPUPerc`   | CPU percentage                               |
| `.MemUsage`  | Memory usage                                 |
| `.NetIO`     | Network IO                                   |
| `.BlockIO`   | Block IO                                     |
| `.MemPerc`   | Memory percentage (Not available on Windows) |
| `.PIDs`      | Number of PIDs (Not available on Windows)    |

When using the `--format` option, the `stats` command either outputs the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `Container` and `CPUPerc` entries separated by a colon (`:`) for all images:

```console
$ docker stats --format "{{.Container}}: {{.CPUPerc}}"

09d3bb5b1604: 6.61%
9db7aa4d986d: 9.19%
3f214c61ad1d: 0.00%
```

To list all containers statistics with their name, CPU percentage and memory usage in a table format you can use:

```console
$ docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"

CONTAINER           CPU %               PRIV WORKING SET
1285939c1fd3        0.07%               796 KiB / 64 MiB
9c76f7834ae2        0.07%               2.746 MiB / 64 MiB
d1ea048f04e4        0.03%               4.583 MiB / 64 MiB
```

The default format is as follows:

On Linux:

```
"table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}"
```

On Windows:

```
"table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}"
```

----
url: https://docs.docker.com/extensions/extensions-sdk/dev/api/dashboard/
----

# Dashboard

***

Table of contents

***

## [User notifications](#user-notifications)

Toasts provide a brief notification to the user. They appear temporarily and shouldn't interrupt the user experience. They also don't require user input to disappear.

### [success](#success)

▸ **success**(`msg`): `void`

Use to display a toast message of type success.

```typescript
ddClient.desktopUI.toast.success("message");
```

### [warning](#warning)

▸ **warning**(`msg`): `void`

Use to display a toast message of type warning.

```typescript
ddClient.desktopUI.toast.warning("message");
```

### [error](#error)

▸ **error**(`msg`): `void`

Use to display a toast message of type error.

```typescript
ddClient.desktopUI.toast.error("message");
```

For more details about method parameters and the return types available, see [Toast API reference](https://docs.docker.com/reference/api/extensions-sdk/Toast/).

> Deprecated user notifications
>
> These methods are deprecated and will be removed in a future version. Use the methods specified above.

```typescript
window.ddClient.toastSuccess("message");
window.ddClient.toastWarning("message");
window.ddClient.toastError("message");
```

## [Open a file selection dialog](#open-a-file-selection-dialog)

This function opens a file selector dialog that asks the user to select a file or folder.

▸ **showOpenDialog**(`dialogProperties`): `Promise`< [`OpenDialogResult`](https://docs.docker.com/reference/api/extensions-sdk/OpenDialogResult/)>:

The `dialogProperties` parameter is a list of flags passed to Electron to customize the dialog's behaviour. For example, you can pass `multiSelections` to allow a user to select multiple files. See [Electron's documentation](https://www.electronjs.org/docs/latest/api/dialog) for a full list.

```typescript
const result = await ddClient.desktopUI.dialog.showOpenDialog({
  properties: ["openDirectory"],
});
if (!result.canceled) {
  console.log(result.paths);
}
```

## [Open a URL](#open-a-url)

This function opens an external URL with the system default browser.

▸ **openExternal**(`url`): `void`

```typescript
ddClient.host.openExternal("https://docker.com");
```

> The URL must have the protocol `http` or `https`.

For more details about method parameters and the return types available, see [Desktop host API reference](https://docs.docker.com/reference/api/extensions-sdk/Host/).

> Deprecated external URL opening
>
> This method is deprecated and will be removed in a future version. Use the methods specified above.

```typescript
window.ddClient.openExternal("https://docker.com");
```

## [Navigation to Dashboard routes](#navigation-to-dashboard-routes)

From your extension, you can also [navigate](https://docs.docker.com/extensions/extensions-sdk/dev/api/dashboard-routes-navigation/) to other parts of the Docker Desktop Dashboard.

----
url: https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/
----

# Publishing and exposing ports

***

Table of contents

***

## [Explanation](#explanation)

If you've been following the guides so far, you understand that containers provide isolated processes for each component of your application. Each component - a React frontend, a Python API, and a Postgres database - runs in its own sandbox environment, completely isolated from everything else on your host machine. This isolation is great for security and managing dependencies, but it also means you can’t access them directly. For example, you can’t access the web app in your browser.

That’s where port publishing comes in.

### [Publishing ports](#publishing-ports)

Publishing a port provides the ability to break through a little bit of networking isolation by setting up a forwarding rule. As an example, you can indicate that requests on your host’s port `8080` should be forwarded to the container’s port `80`. Publishing ports happens during container creation using the `-p` (or `--publish`) flag with `docker run`. The syntax is:

```console
$ docker run -d -p HOST_PORT:CONTAINER_PORT nginx
```

* `HOST_PORT`: The port number on your host machine where you want to receive traffic
* `CONTAINER_PORT`: The port number within the container that's listening for connections

For example, to publish the container's port `80` to host port `8080`:

```console
$ docker run -d -p 8080:80 nginx
```

Now, any traffic sent to port `8080` on your host machine will be forwarded to port `80` within the container.

> Important
>
> When a port is published, it's published to all network interfaces by default. This means any traffic that reaches your machine can access the published application. Be mindful of publishing databases or any sensitive information. [Learn more about published ports here](/engine/network/#published-ports).

### [Publishing to ephemeral ports](#publishing-to-ephemeral-ports)

At times, you may want to simply publish the port but don’t care which host port is used. In these cases, you can let Docker pick the port for you. To do so, simply omit the `HOST_PORT` configuration.

For example, the following command will publish the container’s port `80` onto an ephemeral port on the host:

```console
$ docker run -p 80 nginx
```

Once the container is running, using `docker ps` will show you the port that was chosen:

```console
docker ps
CONTAINER ID   IMAGE         COMMAND                  CREATED          STATUS          PORTS                    NAMES
a527355c9c53   nginx         "/docker-entrypoint.…"   4 seconds ago    Up 3 seconds    0.0.0.0:54772->80/tcp    romantic_williamson
```

In this example, the app is exposed on the host at port `54772`.

### [Publishing all ports](#publishing-all-ports)

When creating a container image, the `EXPOSE` instruction is used to indicate the packaged application will use the specified port. These ports aren't published by default.

With the `-P` or `--publish-all` flag, you can automatically publish all exposed ports to ephemeral ports. This is quite useful when you’re trying to avoid port conflicts in development or testing environments.

For example, the following command will publish all of the exposed ports configured by the image:

```console
$ docker run -P nginx
```

## [Try it out](#try-it-out)

In this hands-on guide, you'll learn how to publish container ports using both the CLI and Docker Compose for deploying a web application.

### [Use the Docker CLI](#use-the-docker-cli)

In this step, you will run a container and publish its port using the Docker CLI.

1. [Download and install](/get-started/get-docker/) Docker Desktop.

2. In a terminal, run the following command to start a new container:

   ```console
   $ docker run -d -p 8080:80 docker/welcome-to-docker
   ```

   The first `8080` refers to the host port. This is the port on your local machine that will be used to access the application running inside the container. The second `80` refers to the container port. This is the port that the application inside the container listens on for incoming connections. Hence, the command binds to port `8080` of the host to port `80` on the container system.

3. Verify the published port by going to the **Containers** view of the Docker Desktop Dashboard.

4. Open the website by either selecting the link in the **Port(s)** column of your container or visiting <http://localhost:8080> in your browser.

### [Use Docker Compose](#use-docker-compose)

This example will launch the same application using Docker Compose:

1. Create a new directory and inside that directory, create a `compose.yaml` file with the following contents:

   ```yaml
   services:
     app:
       image: docker/welcome-to-docker
       ports:
         - 8080:80
   ```

   The `ports` configuration accepts a few different forms of syntax for the port definition. In this case, you’re using the same `HOST_PORT:CONTAINER_PORT` used in the `docker run` command.

2. Open a terminal and navigate to the directory you created in the previous step.

3. Use the `docker compose up` command to start the application.

4. Open your browser to <http://localhost:8080>.

## [Additional resources](#additional-resources)

If you’d like to dive in deeper on this topic, be sure to check out the following resources:

* [`docker container port` CLI reference](/reference/cli/docker/container/port/)
* [Published ports](/engine/network/#published-ports)

## [Next steps](#next-steps)

Now that you understand how to publish and expose ports, you're ready to learn how to override the container defaults using the `docker run` command.

[Overriding container defaults](https://docs.docker.com/get-started/docker-concepts/running-containers/overriding-container-defaults/)

----
url: https://docs.docker.com/guides/testcontainers-java-lifecycle/create-project/
----

# Create the project and business logic

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Java project with Maven and add the required dependencies:

```xml
<dependencies>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>42.7.3</version>
    </dependency>
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.6</version>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.10.2</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-junit-jupiter</artifactId>
        <version>2.0.4</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-postgresql</artifactId>
        <version>2.0.4</version>
        <scope>test</scope>
    </dependency>
</dependencies>
```

## [Create the business logic](#create-the-business-logic)

Create a `Customer` record:

```java
package com.testcontainers.demo;

public record Customer(Long id, String name) {}
```

Create a `CustomerService` class with methods to create, retrieve, and delete customers:

```java
package com.testcontainers.demo;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.ArrayList;
import java.util.List;
import java.util.Optional;

public class CustomerService {

  private final String url;
  private final String username;
  private final String password;

  public CustomerService(String url, String username, String password) {
    this.url = url;
    this.username = username;
    this.password = password;
    createCustomersTableIfNotExists();
  }

  public void createCustomer(Customer customer) {
    try (Connection conn = this.getConnection()) {
      PreparedStatement pstmt = conn.prepareStatement(
        "insert into customers(id,name) values(?,?)"
      );
      pstmt.setLong(1, customer.id());
      pstmt.setString(2, customer.name());
      pstmt.execute();
    } catch (SQLException e) {
      throw new RuntimeException(e);
    }
  }

  public List<Customer> getAllCustomers() {
    List<Customer> customers = new ArrayList<>();
    try (Connection conn = this.getConnection()) {
      PreparedStatement pstmt = conn.prepareStatement(
        "select id,name from customers"
      );
      ResultSet rs = pstmt.executeQuery();
      while (rs.next()) {
        long id = rs.getLong("id");
        String name = rs.getString("name");
        customers.add(new Customer(id, name));
      }
    } catch (SQLException e) {
      throw new RuntimeException(e);
    }
    return customers;
  }

  public Optional<Customer> getCustomer(Long customerId) {
    try (Connection conn = this.getConnection()) {
      PreparedStatement pstmt = conn.prepareStatement(
        "select id,name from customers where id = ?"
      );
      pstmt.setLong(1, customerId);
      ResultSet rs = pstmt.executeQuery();
      if (rs.next()) {
        long id = rs.getLong("id");
        String name = rs.getString("name");
        return Optional.of(new Customer(id, name));
      }
    } catch (SQLException e) {
      throw new RuntimeException(e);
    }
    return Optional.empty();
  }

  public void deleteAllCustomers() {
    try (Connection conn = this.getConnection()) {
      PreparedStatement pstmt = conn.prepareStatement("delete from customers");
      pstmt.execute();
    } catch (SQLException e) {
      throw new RuntimeException(e);
    }
  }

  private void createCustomersTableIfNotExists() {
    try (Connection conn = this.getConnection()) {
      PreparedStatement pstmt = conn.prepareStatement(
        """
        create table if not exists customers (
            id bigint not null,
            name varchar not null,
            primary key (id)
        )
        """
      );
      pstmt.execute();
    } catch (SQLException e) {
      throw new RuntimeException(e);
    }
  }

  private Connection getConnection() {
    try {
      return DriverManager.getConnection(url, username, password);
    } catch (Exception e) {
      throw new RuntimeException(e);
    }
  }
}
```

[JUnit 5 lifecycle callbacks »](https://docs.docker.com/guides/testcontainers-java-lifecycle/lifecycle-callbacks/)

----
url: https://docs.docker.com/dhi/how-to/verify/
----

# Verify a Docker Hardened Image or chart

***

Table of contents

***

Docker Hardened Images (DHI) and charts include signed attestations that verify the build process, contents, and security posture.

Docker's public key for DHI images and charts is published at:

* <https://registry.scout.docker.com/keyring/dhi/latest.pub>
* <https://github.com/docker-hardened-images/keyring>

Docker recommends using [Docker Scout](/scout/), but you can use [`regctl`](https://github.com/regclient/regclient) and [`cosign`](https://docs.sigstore.dev/) to retrieve and verify attestations. Docker Scout offers several key advantages: it understands DHI attestation structures, automatically resolves platforms, provides human-readable summaries, validates in one step with `--verify`, and integrates tightly with Docker's attestation infrastructure.

> Important
>
> You must authenticate to the Docker Hardened Images registry (`dhi.io`) to pull images. Use your Docker ID credentials (the same username and password you use for Docker Hub) when signing in. If you don't have a Docker account, [create one](https://docs.docker.com/accounts/create-account/) for free.
>
> Run `docker login dhi.io` to authenticate.

## [Verify image attestations](#verify-image-attestations)

> Note
>
> Before you run `docker scout attest` commands, ensure any image that you have pulled locally is up to date with the remote image. You can do this by running `docker pull`. If you don't do this, you may see `No attestation found`.

### [List available attestations](#list-available-attestations)

To list attestations for a mirrored DHI image:

> Note
>
> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://dhi.io/python:3.13` instead of `dhi.io/python:3.13`.

```console
$ docker scout attest list dhi.io/<image>:<tag>
```

This command shows all available attestations, including SBOMs, provenance, vulnerability reports, and more.

First, authenticate to both registries. This example authenticates as your Docker organization using an [organization access token (OAT)](https://docs.docker.com/enterprise/security/access-tokens/). The OAT must have at least pull access to the DHI repositories you want to verify. Only repositories in the token's scope are accessible. Alternatively, you can authenticate as a Docker Hub user with a [personal access token (PAT)](https://docs.docker.com/security/access-tokens/) that has `read only` access.

> Warning
>
> The following examples export credentials directly on the command line for demonstration purposes. This exposes sensitive tokens in your shell history and process list. In production environments, use secure methods such as reading from files with restricted permissions, environment files loaded at runtime, or secret management tools.

```console
$ export DOCKER_ORG="YOUR_DOCKER_ORG"
$ export DOCKER_OAT="YOUR_DOCKER_OAT"
$ echo $DOCKER_OAT | regctl registry login -u "$DOCKER_ORG" --pass-stdin docker.io
$ echo $DOCKER_OAT | regctl registry login -u "$DOCKER_ORG" --pass-stdin registry.scout.docker.com
```

Then list attestations using the `--external` flag. DHI repositories store image layers on `dhi.io` (or `docker.io` for mirrored images) and signed attestations in `registry.scout.docker.com`:

```console
$ regctl artifact list docker.io/${DOCKER_ORG}/<image>:<tag> \
  --external registry.scout.docker.com/${DOCKER_ORG}/<image> \
  --platform linux/amd64
```

For example:

```console
$ regctl artifact list docker.io/${DOCKER_ORG}/dhi-node:22 \
  --external registry.scout.docker.com/${DOCKER_ORG}/dhi-node \
  --platform linux/amd64
```

### [Retrieve a specific attestation](#retrieve-a-specific-attestation)

To retrieve a specific attestation, use the `--predicate-type` flag with the full predicate type URI:

```console
$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/<image>:<tag>
```

> Note
>
> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://dhi.io/python:3.13` instead of `dhi.io/python:3.13`.

For example:

```console
$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/python:3.13
```

To retrieve only the predicate body:

```console
$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  --predicate \
  dhi.io/<image>:<tag>
```

Once you've listed attestations, download the full attestation artifact using the digest from the `Name` field:

```console
$ regctl artifact get <attestation-digest> > attestation.json
```

For example, to save a SLSA provenance attestation:

```console
$ regctl artifact get registry.scout.docker.com/${DOCKER_ORG}/dhi-node@sha256:6cbf803796e281e535f2681de7cd33a1012202610322a50ee745d1bb02ac3c18 > slsa_provenance.json
```

### [Validate the attestation](#validate-the-attestation)

To validate the attestation using Docker Scout, you can use the `--verify` flag:

```console
$ docker scout attest get dhi.io/<image>:<tag> \
   --predicate-type https://scout.docker.com/sbom/v0.1 --verify
```

> Note
>
> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://dhi.io/node:20.19-debian12` instead of `dhi.io/node:20.19-debian12`.

For example, to verify the SBOM attestation for the `dhi.io/node:20.19-debian12` image:

```console
$ docker scout attest get dhi.io/node:20.19-debian12 \
   --predicate-type https://scout.docker.com/sbom/v0.1 --verify
```

Once you've listed the attestations and obtained the digest from the `Name` field, verify them using cosign:

```console
$ cosign verify \
  <attestation-digest-from-name-field> \
  --key https://registry.scout.docker.com/keyring/dhi/latest.pub \
  --insecure-ignore-tlog=true
```

For example:

```console
$ cosign verify \
  registry.scout.docker.com/${DOCKER_ORG}/dhi-node@sha256:6cbf803796e281e535f2681de7cd33a1012202610322a50ee745d1bb02ac3c18 \
  --key https://registry.scout.docker.com/keyring/dhi/latest.pub \
  --insecure-ignore-tlog=true
```

> Note
>
> The `--insecure-ignore-tlog=true` flag is needed because DHI attestations may not be recorded in the public Rekor transparency log to protect private customer information. The attestation signature is still verified against Docker's public key.

#### [Handle missing transparency log entries](#handle-missing-transparency-log-entries)

When using `--verify` with Docker Scout or `cosign verify`, you may sometimes see an error like:

```text
ERROR no matching signatures: signature not found in transparency log
```

This occurs because Docker Hardened Images don't always record attestations in the public [Rekor](https://docs.sigstore.dev/logging/overview/) transparency log. In cases where an attestation would contain private user information (for example, your organization's namespace in the image reference), writing it to Rekor would expose that information publicly.

Even if the Rekor entry is missing, the attestation is still signed with Docker's public key and can be verified offline by skipping the Rekor transparency log check.

To skip the transparency log check and validate against Docker's key, use the `--skip-tlog` flag:

```console
$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/<image>:<tag> \
  --verify --skip-tlog
```

> Note
>
> The `--skip-tlog` flag is only available in Docker Scout CLI version 1.18.2 and later.
>
> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://dhi.io/python:3.13` instead of `dhi.io/python:3.13`.

This is equivalent to using `cosign` with the `--insecure-ignore-tlog=true` flag, which validates the signature against Docker's published public key, but ignores the transparency log check.

### [Show the equivalent cosign command](#show-the-equivalent-cosign-command)

When using the `--verify` flag, it also prints the corresponding [cosign](https://docs.sigstore.dev/) command to verify the image signature:

```console
$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  --verify \
  dhi.io/<image>:<tag>
```

> Note
>
> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://dhi.io/python:3.13` instead of `dhi.io/python:3.13`.

For example:

```console
$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  --verify \
  dhi.io/python:3.13
```

If verification succeeds, Docker Scout prints the full `cosign verify` command.

Example output:

```console
    v SBOM obtained from attestation, 101 packages found
    v Provenance obtained from attestation
    v cosign verify ...
```

> Important
>
> When using cosign, you must first authenticate to both the DHI registry and the Docker Scout registry.
>
> For example:
>
> ```console
> $ docker login dhi.io
> $ docker login registry.scout.docker.com
> $ cosign verify ...
> ```

## [Verify package attestations](#verify-package-attestations)

In addition to image attestations, individual hardened packages have their own attestations. These package-level attestations allow you to verify the provenance and build information for specific packages within an image.

For instructions on how to extract package information from image attestations and retrieve package-level attestations, see [Package attestations](https://docs.docker.com/dhi/how-to/hardened-packages/#package-attestations).

## [Verify Helm chart attestations with Docker Scout](#verify-helm-chart-attestations-with-docker-scout)

Docker Hardened Image Helm charts include the same comprehensive attestations as container images. The verification process for charts is identical to that for images, using the same Docker Scout CLI commands.

### [List available chart attestations](#list-available-chart-attestations)

To list attestations for a DHI Helm chart:

```console
$ docker scout attest list dhi.io/<chart>:<version>
```

For example, to list attestations for the external-dns chart:

```console
$ docker scout attest list dhi.io/external-dns-chart:1.20.0
```

This command shows all available chart attestations, including SBOMs, provenance, vulnerability reports, and more.

### [Retrieve a specific chart attestation](#retrieve-a-specific-chart-attestation)

To retrieve a specific attestation from a Helm chart, use the `--predicate-type` flag with the full predicate type URI:

```console
$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/<chart>:<version>
```

For example:

```console
$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  dhi.io/external-dns-chart:1.20.0
```

To retrieve only the predicate body:

```console
$ docker scout attest get \
  --predicate-type https://cyclonedx.org/bom/v1.6 \
  --predicate \
  dhi.io/<chart>:<version>
```

### [Validate chart attestations with Docker Scout](#validate-chart-attestations-with-docker-scout)

To validate a chart attestation using Docker Scout, use the `--verify` flag:

```console
$ docker scout attest get dhi.io/<chart>:<version> \
   --predicate-type https://scout.docker.com/sbom/v0.1 --verify
```

For example, to verify the SBOM attestation for the external-dns chart:

```console
$ docker scout attest get dhi.io/external-dns-chart:1.20.0 \
   --predicate-type https://scout.docker.com/sbom/v0.1 --verify
```

The same `--skip-tlog` flag described in [Handle missing transparency log entries](#handle-missing-transparency-log-entries) can also be used with chart attestations when needed.

## [Available DHI attestations](#available-dhi-attestations)

See [available attestations](https://docs.docker.com/dhi/core-concepts/attestations/#image-attestations) for a list of attestations available for each DHI image and [Helm chart attestations](https://docs.docker.com/dhi/core-concepts/attestations/#helm-chart-attestations) for a list of attestations available for each DHI chart.

## [Explore attestations on Docker Hub](#explore-attestations-on-docker-hub)

You can also browse attestations visually when [exploring an image variant](https://docs.docker.com/dhi/how-to/explore/#image-variant-details). The **Attestations** section lists each available attestation with its:

* Type (e.g. SBOM, VEX)
* Predicate type URI
* Digest reference for use with `cosign`

These attestations are generated and signed automatically as part of the Docker Hardened Image or chart build process.

----
url: https://docs.docker.com/guides/docker-scout/sbom/
----

# Software Bill of Materials

***

Table of contents

***

A Bill of Materials (BOM) is a list of materials, parts, and the quantities of each needed to manufacture a product. For example, a BOM for a computer might list the motherboard, CPU, RAM, power supply, storage devices, case, and other components, along with the quantities of each that are needed to build the computer.

A Software Bill of Materials (SBOM) is a list of all the components that make up a piece of software. This includes open source and third-party components, as well as any custom code that has been written for the software. An SBOM is similar to a BOM for a physical product, but for software.

In the context of software supply chain security, SBOMs can help with identifying and mitigating security and compliance risks in software. By knowing exactly what components are used in a piece of software, you can quickly identify and patch vulnerabilities in your components, or determine if a component is licensed in a way that is incompatible with your project.

## [Contents of an SBOM](#contents-of-an-sbom)

An SBOM typically includes the following information:

* The name of the software, such as the name of a library or framework, that the SBOM describes.
* The version of the software.
* The license under which the software is distributed.
* A list of other components that the software depends on.

## [How Docker Scout uses SBOMs](#how-docker-scout-uses-sboms)

Docker Scout uses SBOMs to determine the components that are used in a Docker image. When you analyze an image, Docker Scout will either use the SBOM that is attached to the image as an attestation, or it will generate an SBOM on the fly by analyzing the contents of the image.

The SBOM is cross-referenced with the [advisory database](https://docs.docker.com/scout/deep-dive/advisory-db-sources/) to determine if any of the components in the image have known vulnerabilities.

[Attestations »](https://docs.docker.com/guides/docker-scout/attestations/)

----
url: https://docs.docker.com/reference/cli/docker/sandbox/rm/
----

# docker sandbox rm

***

| Description                                                               | Remove one or more sandboxes             |
| ------------------------------------------------------------------------- | ---------------------------------------- |
| Usage                                                                     | `docker sandbox rm SANDBOX [SANDBOX...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker sandbox remove`                  |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Remove one or more sandboxes and all their associated resources.

This command will:

* Check if the sandbox exists
* Remove the sandbox and clean up its associated resources

## [Examples](#examples)

### [Remove a sandbox](#remove-a-sandbox)

```console
$ docker sandbox rm abc123def
abc123def
```

### [Remove multiple sandboxes](#remove-multiple-sandboxes)

```console
$ docker sandbox rm abc123def def456ghi
abc123def
def456ghi
```

### [Remove all sandboxes](#remove-all-sandboxes)

```console
$ docker sandbox rm $(docker sandbox ls -q)
```

----
url: https://docs.docker.com/reference/samples/agentic-ai/
----

# Agentic AI samples

| Name                                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Agent-to-Agent](https://github.com/docker/compose-for-agents/tree/main/a2a)                                                          | This app is a modular AI agent runtime built on Google's Agent Development Kit (ADK) and the A2A (Agent-to-Agent) protocol. It wraps a large language model (LLM)-based agent in an HTTP API and uses structured execution flows with streaming responses, memory, and tools. It is designed to make agents callable as network services and composable with other agents.                                                                                                                                |
| [ADK Multi-Agent Fact Checker](https://github.com/docker/compose-for-agents/tree/main/adk)                                            | This project demonstrates a collaborative multi-agent system built with the Agent Development Kit (ADK), where a top-level Auditor agent coordinates the workflow to verify facts. The Critic agent gathers evidence via live internet searches using DuckDuckGo through the Model Context Protocol (MCP), while the Reviser agent analyzes and refines the conclusion using internal reasoning alone. The system showcases how agents with distinct roles and tools can collaborate under orchestration. |
| [DevDuck agents](https://github.com/docker/compose-for-agents/tree/main/adk-cerebras)                                                 | A multi-agent system for Go programming assistance built with Google Agent Development Kit (ADK). This project features a coordinating agent (DevDuck) that manages two specialized sub-agents (Bob and Cerebras) for different programming tasks.                                                                                                                                                                                                                                                        |
| [Agno](https://github.com/docker/compose-for-agents/tree/main/agno)                                                                   | This app is a multi-agent orchestration system powered by LLMs (like Qwen and OpenAI) and connected to tools via a Model Control Protocol (MCP) gateway. Its purpose is to retrieve, summarize, and document GitHub issues—automatically creating Notion pages from the summaries. It also supports file content summarization from GitHub.                                                                                                                                                               |
| [CrewAI](https://github.com/docker/compose-for-agents/tree/main/crew-ai)                                                              | This project showcases an autonomous, multi-agent virtual marketing team built with CrewAI. It automates the creation of a high-quality, end-to-end marketing strategy — from research to copywriting — using task delegation, web search, and creative synthesis.                                                                                                                                                                                                                                        |
| [SQL Agent with LangGraph](https://github.com/docker/compose-for-agents/tree/main/langgraph)                                          | This project demonstrates a zero-config AI agent that uses LangGraph to answer natural language questions by querying a SQL database — all orchestrated with Docker Compose.                                                                                                                                                                                                                                                                                                                              |
| [Langchaingo Brave Search Example - Model Context Protocol (MCP)](https://github.com/docker/compose-for-agents/tree/main/langchaingo) | This example demonstrates how to create a Go Model Context Protocol (MCP) client that communicates with the Brave Search MCP Server. The application shows how to build an MCP client that enables natural language interactions with Brave Search, allowing you to perform internet searches through a conversational interface. This example uses the official Go SDK for Model Context Protocol servers and clients, to set up the MCP client.                                                         |
| [Spring AI Brave Search Example - Model Context Protocol (MCP)](https://github.com/docker/compose-for-agents/tree/main/spring-ai)     | This example demonstrates how to create a Spring AI Model Context Protocol (MCP) client that communicates with the Brave Search MCP Server. The application shows how to build an MCP client that enables natural language interactions with Brave Search, allowing you to perform internet searches through a conversational interface. This example uses Spring Boot autoconfiguration to set up the MCP client through configuration files.                                                            |
| [MCP UI with Vercel AI SDK](https://github.com/docker/compose-for-agents/tree/main/vercel)                                            | Start an MCP UI application that uses the Vercel AI SDK to provide a chat interface for local models, provided by the Docker Model Runner, with access to MCPs from the Docker MCP Catalog.                                                                                                                                                                                                                                                                                                               |

----
url: https://docs.docker.com/docker-hub/usage/pulls/
----

# Docker Hub pull usage and limits

***

Table of contents

***

Unauthenticated and Docker Personal users are subject to a 6-hour pull rate limit on Docker Hub. In contrast, Docker Pro, Team, and Business users benefit from an unlimited pull rate.

The following pull usage and limits apply based on your subscription, subject to fair use:

| User type                | Pull rate limit per 6 hours             |
| ------------------------ | --------------------------------------- |
| Business (authenticated) | Unlimited                               |
| Team (authenticated)     | Unlimited                               |
| Pro (authenticated)      | Unlimited                               |
| Personal (authenticated) | 200                                     |
| Unauthenticated Users    | 100 per IPv4 address or IPv6 /64 subnet |

## [Pull definition](#pull-definition)

A pull is defined as the following:

* A Docker pull includes both a version check and any download that occurs as a result of the pull. Depending on the client, a `docker pull` can verify the existence of an image or tag without downloading it by performing a version check.
* Version checks do not count towards usage pricing.
* A pull for a normal image makes one pull for a [single manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md).
* A pull for a multi-arch image will count as one pull for each different architecture.

## [Pull attribution](#pull-attribution)

Pulls from authenticated users can be attributed to either a personal or an [organization namespace](https://docs.docker.com/accounts/general-faqs/#whats-an-organization-name-or-namespace).

Attribution is based on the following:

* Private pulls: Pulls for private repositories are attributed to the repository's namespace owner.

* Public pulls: When pulling images from a public repository, attribution is determined based on domain affiliation and organization membership.

* Verified domain ownership: When pulling an image from an account linked to a verified domain, the attribution is set to be the owner of that [domain](https://docs.docker.com/enterprise/security/single-sign-on/faqs/domain-faqs/).

* Single organization membership:

  * If the owner of the verified domain is a company and the user is part of only one organization within that [company](https://docs.docker.com/admin/company/company-faqs/), the pull is attributed to that specific organization.
  * If the user is part of only one organization, the pull is attributed to that specific organization.

* Multiple organization memberships: If the user is part of multiple organizations under the company, the pull is attributed to the user's personal namespace.

### [Authentication](#authentication)

To ensure correct attribution of your pulls, you must authenticate with Docker Hub. The following sections provide information on how to sign in to Docker Hub to authenticate your pulls.

#### [Docker Desktop](#docker-desktop)

If you are using Docker Desktop, you can sign in to Docker Hub from the Docker Desktop menu.

Select **Sign in / Create Docker ID** from the Docker Desktop menu and follow the on-screen instructions to complete the sign-in process.

#### [Docker Engine](#docker-engine)

If you're using a standalone version of Docker Engine, run the `docker login` command from a terminal to authenticate with Docker Hub. For information on how to use the command, see [docker login](/reference/cli/docker/login/).

#### [Docker Swarm](#docker-swarm)

If you're running Docker Swarm, you must use the `--with-registry-auth` flag to authenticate with Docker Hub. For more information, see [Create a service](/reference/cli/docker/service/create/#with-registry-auth). If you are using a Docker Compose file to deploy an application stack, see [docker stack deploy](/reference/cli/docker/stack/deploy/).

#### [GitHub Actions](#github-actions)

If you're using GitHub Actions to build and push Docker images to Docker Hub, see [login action](https://github.com/docker/login-action#dockerhub). If you are using another Action, you must add your username and access token in a similar way for authentication.

#### [Kubernetes](#kubernetes)

If you're running Kubernetes, follow the instructions in [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for information on authentication.

#### [Third-party platforms](#third-party-platforms)

If you're using any third-party platforms, follow your provider’s instructions on using registry authentication.

> Note
>
> When pulling images via a third-party platform, the platform may use the same IPv4 address or IPv6 /64 subnet to pull images for multiple users. Even if you are authenticated, pulls attributed to a single IPv4 address or IPv6 /64 subnet may cause [abuse rate limiting](https://docs.docker.com/docker-hub/usage/#abuse-rate-limit).

* [Artifactory](https://www.jfrog.com/confluence/display/JFROG/Advanced+Settings#AdvancedSettings-RemoteCredentials)
* [AWS CodeBuild](https://aws.amazon.com/blogs/devops/how-to-use-docker-images-from-a-private-registry-in-aws-codebuild-for-your-build-environment/)
* [AWS ECS/Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)
* [Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops\&tabs=yaml)
* [Chipper CI](https://docs.chipperci.com/builds/docker/#rate-limit-auth)
* [CircleCI](https://circleci.com/docs/guides/execution-managed/private-images/)
* [Codefresh](https://codefresh.io/docs/docs/docker-registries/external-docker-registries/docker-hub/)
* [Drone.io](https://docs.drone.io/pipeline/docker/syntax/images/#pulling-private-images)
* [GitLab](https://docs.gitlab.com/ee/user/packages/container_registry/#authenticate-with-the-container-registry)
* [LayerCI](https://layerci.com/docs/advanced-workflows#logging-in-to-docker)
* [TeamCity](https://www.jetbrains.com/help/teamcity/integrating-teamcity-with-docker.html#Conforming+with+Docker+download+rate+limits)

## [View monthly pulls and included usage](#view-monthly-pulls-and-included-usage)

You can view your monthly pulls on the [Usage page](https://hub.docker.com/usage/pulls) in Docker Hub.

On that page, you can also send a report to your email that contains a comma separated file with the following detailed information.

| CSV column           | Definition                                                                                                                                                                                                         | Usage guidance                                                                                                                                                                      |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `datehour`           | The date and hour (`yyyy/mm/dd/hh`) of the pull that resulted in the data transfer.                                                                                                                                | This helps in identifying peak usage times and patterns.                                                                                                                            |
| `user_name`          | The Docker ID of the user that pulled the image                                                                                                                                                                    | This lets organization owners track data consumption per user and manage resources effectively.                                                                                     |
| `repository`         | The name of the repository of the image that was pulled.                                                                                                                                                           | This lets you identify which repositories are most frequently accessed and consume most of the data transfer.                                                                       |
| `access_token_name`  | Name of the access token that was used for authentication with Docker CLI. `generated` tokens are automatically generated by the Docker client when a user signs in.                                               | Personal access tokens are usually used to authenticate automated tools (Docker Desktop, CI/CD tools, etc.). This is useful for identifying which automated system issued the pull. |
| `ips`                | The IP address that was used to pull the image. This field is aggregated, so more than one IP address may appear, representing all the IPs used to pull an image within the same date and hour.                    | This helps you understand the origin of the data transfer, which is useful for diagnosing and identifying patterns in automated or manual pulls.                                    |
| `repository_privacy` | The privacy state of the image repository that was pulled. This can either be `public` or `private`.                                                                                                               | This distinguishes between public and private repositories to identify which data transfer threshold the pull impacts.                                                              |
| `tag`                | The tag for the image. The tag is only available if the pull included a tag.                                                                                                                                       | This helps in identifying the image. Tags are often used to identify specific versions or variants of an image.                                                                     |
| `digest`             | The unique image digest for the image.                                                                                                                                                                             | This helps in identifying the image.                                                                                                                                                |
| `version_checks`     | The number of version checks accumulated for the date and hour of each image repository. Depending on the client, a pull can do a version check to verify the existence of an image or tag without downloading it. | This helps identify the frequency of version checks, which you can use to analyze usage trends and potential unexpected behaviors.                                                  |
| `pulls`              | The number of pulls accumulated for the date and hour of each image repository.                                                                                                                                    | This helps identify the frequency of repository pulls, which you can use to analyze usage trends and potential unexpected behaviors.                                                |

## [View pull rate and limit](#view-pull-rate-and-limit)

The pull rate limit is calculated on a 6-hour basis. There is no pull rate limit for users or automated systems with a paid subscription. Unauthenticated and Docker Personal users using Docker Hub will experience rate limits on image pulls.

When you issue a pull and you are over the limit, Docker Hub returns a `429` response code with the following body when the manifest is requested:

```text
You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limits
```

This error message appears in the Docker CLI or in the Docker Engine logs.

To view your current pull rate and limit:

> Note
>
> To check your limits, you need `curl` and `jq` installed.

1. Get a token.

   * To get a token anonymously, if you are pulling anonymously:

     ```console
     $ TOKEN=$(curl "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
     ```

   * To get a token with a user account, if you are authenticated, insert your username and password in the following command:

     ```console
     $ TOKEN=$(curl --user 'username:password' "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
     ```

2. Get the headers that contain your limits. These headers are returned on both GET and HEAD requests. Using GET emulates a real pull and counts towards the limit. Using HEAD won't.

   ```console
   $ curl --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest
   ```

3. Examine the headers. You should see the following headers.

   ```text
   ratelimit-limit: 100;w=21600
   ratelimit-remaining: 20;w=21600
   docker-ratelimit-source: 192.0.2.1
   ```

   In the previous example, the pull limit is 100 pulls per 21600 seconds (6 hours), and there are 20 pulls remaining.

   If you don't see any `ratelimit` header, it could be because the image or your IP is unlimited in partnership with a publisher, provider, or an open source organization. It could also mean that the user you are pulling as is part of a paid Docker subscription. Pulling that image won't count toward pull rate limits if you don't see these headers.

----
url: https://docs.docker.com/guides/docker-scout/demo/
----

# Docker Scout demo

***

***

Docker Scout has powerful features for enhancing containerized application security and ensuring a robust software supply chain.

* Define vulnerability remediation
* Discuss why remediation is essential to maintain the security and integrity of containerized applications
* Discuss common vulnerabilities
* Implement remediation techniques: updating base images, applying patches, removing unnecessary packages
* Verify and validate remediation efforts using Docker Scout

[Software supply chain security »](https://docs.docker.com/guides/docker-scout/s3c/)

----
url: https://docs.docker.com/guides/admin-user-management/audit-and-monitor/
----

# Monitoring and insights

***

Table of contents

***

Activity logs and Insights are useful tools for user and access management in Docker. They provide visibility into user actions, team workflows, and organizational trends, helping enhance security, ensure compliance, and boost productivity.

## [Activity logs](#activity-logs)

Activity logs track events at the organization and repository levels, offering a clear view of activities like repository changes, team updates, and billing adjustments.

Activity logs are available for Docker Team or Docker Business plans, with data retained for three months.

### [Key features](#key-features)

* Change tracking: View what changed, who made the change, and when.
* Comprehensive reporting: Monitor critical events such as repository creation, deletion, privacy changes, and role assignments.

### [Example scenarios](#example-scenarios)

* Audit trail for security: A repository’s privacy settings were updated unexpectedly. The activity logs reveal which user made the change and when, helping administrators address potential security risks.
* Team collaboration review: Logs show which team members pushed updates to a critical repository, ensuring accountability during a development sprint.
* Billing adjustments: Track who added or removed subscription seats to maintain budgetary control and compliance.

For more information, see [Activity logs](https://docs.docker.com/admin/activity-logs/).

## [Insights](#insights)

Insights provide data-driven views of Docker usage to improve team productivity and resource allocation.

### [Key benefits](#key-benefits)

* Standardized environments: Ensure consistent configurations and enforce best practices across teams.
* Improved visibility: Monitor metrics like Docker Desktop usage, builds, and container activity to understand team workflows and engagement.
* Optimized resources: Track license usage and feature adoption to maximize the value of your Docker subscription.

### [Example scenarios](#example-scenarios-1)

* Usage trends: Identify underutilized licenses or resources, allowing reallocation to more active teams.
* Build efficiency: Track average build times and success rates to pinpoint bottlenecks in development processes.
* Container utilization: Analyze container activity across departments to ensure proper resource distribution and cost efficiency.

For more information, see [Insights](https://docs.docker.com/admin/insights/).

## [Next steps](#next-steps)

Now that you've mastered user and access management in Docker, you can:

* Review your [activity logs](https://docs.docker.com/admin/activity-logs/) regularly to maintain security awareness
* Check your [Insights dashboard](https://docs.docker.com/admin/insights/) to identify opportunities for optimization
* Explore [advanced security features](https://docs.docker.com/enterprise/security/) to further enhance your Docker environment
* Share best practices with your team to ensure consistent adoption of security policies

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/dynamic-mcp/
----

# Dynamic MCP

***

Table of contents

***

Dynamic MCP enables AI agents to discover and add MCP servers on-demand during a conversation, without manual configuration. Instead of pre-configuring every MCP server before starting your agent session, clients can search the [MCP Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/) and add servers as needed.

This capability is enabled automatically when you connect an MCP client to the [MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/). The gateway provides a set of primordial tools that agents use to discover and manage servers during runtime.

```
</span>
<strong>Experimental</strong>
```

Dynamic MCP is an experimental feature in early development. While you're welcome to try it out and explore its capabilities, you may encounter unexpected behavior or limitations. Feedback is welcome via at [GitHub issues](https://github.com/docker/mcp-gateway/issues) for bug reports and [GitHub discussions](https://github.com/docker/mcp-gateway/discussions) for general questions and feature requests.

## [How it works](#how-it-works)

When you connect a client to the MCP Gateway, the gateway exposes a small set of management tools alongside any MCP servers in your active profile. These management tools let agents interact with the gateway's configuration:

| Tool             | Description                                                              |
| ---------------- | ------------------------------------------------------------------------ |
| `mcp-find`       | Search for MCP servers in the catalog by name or description             |
| `mcp-add`        | Add a new MCP server to the current session                              |
| `mcp-config-set` | Configure settings for an MCP server                                     |
| `mcp-remove`     | Remove an MCP server from the session                                    |
| `mcp-exec`       | Execute a tool by name that exists in the current session                |
| `code-mode`      | Create a JavaScript-enabled tool that combines multiple MCP server tools |

With these tools available, an agent can search the catalog, add servers, handle authentication, and use newly added tools directly without requiring a restart or manual configuration.

Dynamically added servers and tools are associated with your *current session only*. They're not persisted to your profile. When you start a new session, only servers you've added to your profile through the [MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/) or [Profiles](https://docs.docker.com/ai/mcp-catalog-and-toolkit/profiles/) are available.

## [Prerequisites](#prerequisites)

To use Dynamic MCP, you need:

* Docker Desktop version 4.50 or later, with [MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/) enabled
* An LLM application that supports MCP (such as Claude Desktop, Visual Studio Code, or Claude Code)
* Your client configured to connect to the MCP Gateway

See [Get started with Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/get-started/) for setup instructions.

## [Usage](#usage)

Dynamic MCP is enabled automatically when you use the MCP Toolkit. Your connected clients can now use `mcp-find`, `mcp-add`, and other management tools during conversations.

To see Dynamic MCP in action, connect your AI client to the Docker MCP Toolkit and try this prompt:

```plaintext
What MCP servers can I use for working with SQL databases?
```

Given this prompt, your agent will use the `mcp-find` tool provided by MCP Toolkit to search for SQL-related servers in the [MCP Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/).

And to add a server to a session, simply write a prompt and the MCP Toolkit takes care of installing and running the server:

```plaintext
Add the postgres mcp server
```

## [Tool composition with code mode](#tool-composition-with-code-mode)

The `code-mode` tool is available as an experimental capability for creating custom JavaScript functions that combine multiple MCP server tools. The intended use case is to enable workflows that coordinate multiple services in a single operation.

> **Note**
>
> Code mode is in early development and is not yet reliable for general use. The documentation intentionally omits usage examples at this time.
>
> The core Dynamic MCP capabilities (`mcp-find`, `mcp-add`, `mcp-config-set`, `mcp-remove`) work as documented and are the recommended focus for current use.

The architecture works as follows:

1. The agent calls `code-mode` with a list of server names and a tool name
2. The gateway creates a sandbox with access to those servers' tools
3. A new tool is registered in the current session with the specified name
4. The agent calls the newly created tool
5. The code executes in the sandbox with access to the specified tools
6. Results are returned to the agent

The sandbox can only interact with the outside world through MCP tools, which are already running in isolated containers with restricted privileges.

## [Security considerations](#security-considerations)

Dynamic MCP maintains the same security model as static MCP server configuration in MCP Toolkit:

* All servers in the MCP Catalog are built, signed, and maintained by Docker
* Servers run in isolated containers with restricted resources
* Code mode runs agent-written JavaScript in an isolated sandbox that can only interact through MCP tools
* Credentials are managed by the gateway and injected securely into containers

The key difference with dynamic capabilities is that agents can add new tools during runtime.

## [Disabling Dynamic MCP](#disabling-dynamic-mcp)

Dynamic MCP is enabled by default in the MCP Toolkit. If you prefer to use only statically configured MCP servers, you can disable the dynamic tools feature:

```console
$ docker mcp feature disable dynamic-tools
```

To re-enable the feature later:

```console
$ docker mcp feature enable dynamic-tools
```

After changing this setting, you may need to restart any connected MCP clients.

## [Further reading](#further-reading)

Check out the [Dynamic MCP servers with Docker](https://docker.com/blog) blog post for more examples and inspiration on how you can use dynamic tools.

----
url: https://docs.docker.com/engine/security/trust/trust_delegation/
----

# Delegations for content trust

***

Table of contents

***

Delegations in Docker Content Trust (DCT) allow you to control who can and cannot sign an image tag. A delegation will have a pair of private and public delegation keys. A delegation could contain multiple pairs of keys and contributors in order to a) allow multiple users to be part of a delegation, and b) to support key rotation.

The most important delegation within Docker Content Trust is `targets/releases`. This is seen as the canonical source of a trusted image tag, and without a contributor's key being under this delegation, they will be unable to sign a tag.

Fortunately when using the `$ docker trust` commands, we will automatically initialize a repository, manage the repository keys, and add a collaborator's key to the `targets/releases` delegation via `docker trust signer add`.

## [Configuring the Docker client](#configuring-the-docker-client)

By default, the `$ docker trust` commands expect the notary server URL to be the same as the registry URL specified in the image tag (following a similar logic to `$ docker push`). When using Docker Hub or DTR, the notary server URL is the same as the registry URL. However, for self-hosted environments or 3rd party registries, you will need to specify an alternative URL of the notary server. This is done with:

```console
$ export DOCKER_CONTENT_TRUST_SERVER=https://URL:PORT
```

If you do not export this variable in self-hosted environments, you may see errors such as:

```console
$ docker trust signer add --key cert.pem jeff registry.example.com/admin/demo
Adding signer "jeff" to registry.example.com/admin/demo...
<...>
Error: trust data missing for remote repository registry.example.com/admin/demo or remote repository not found: timestamp key trust data unavailable.  Has a notary repository been initialized?

$ docker trust inspect registry.example.com/admin/demo --pretty
WARN[0000] Error while downloading remote metadata, using cached timestamp - this might not be the latest version available remotely
<...>
```

If you have enabled authentication for your notary server, or are using DTR, you will need to log in before you can push data to the notary server.

```console
$ docker login registry.example.com/user/repo
Username: admin
Password:

Login Succeeded

$ docker trust signer add --key cert.pem jeff registry.example.com/user/repo
Adding signer "jeff" to registry.example.com/user/repo...
Initializing signed repository for registry.example.com/user/repo...
Successfully initialized "registry.example.com/user/repo"
Successfully added signer: jeff to registry.example.com/user/repo
```

If you do not log in, you will see:

```console
$ docker trust signer add --key cert.pem jeff registry.example.com/user/repo
Adding signer "jeff" to registry.example.com/user/repo...
Initializing signed repository for registry.example.com/user/repo...
you are not authorized to perform this operation: server returned 401.

Failed to add signer to: registry.example.com/user/repo
```

## [Configuring the Notary client](#configuring-the-notary-client)

Some of the more advanced features of DCT require the Notary CLI. To install and configure the Notary CLI:

1. Download the [client](https://github.com/theupdateframework/notary/releases) and ensure that it is available on your path.

2. Create a configuration file at `~/.notary/config.json` with the following content:

```json
{
  "trust_dir" : "~/.docker/trust",
  "remote_server": {
    "url": "https://registry.example.com",
    "root_ca": "../.docker/ca.pem"
  }
}
```

The newly created configuration file contains information about the location of your local Docker trust data and the notary server URL.

For more detailed information about how to use notary outside of the Docker Content Trust use cases, refer to the [Notary CLI documentation](https://github.com/theupdateframework/notary/blob/master/docs/command_reference.md)

## [Creating delegation keys](#creating-delegation-keys)

A prerequisite to adding your first contributor is a pair of delegation keys. These keys can either be generated locally using `$ docker trust`, generated by a certificate authority.

### [Using Docker Trust to generate keys](#using-docker-trust-to-generate-keys)

Docker trust has a built-in generator for a delegation key pair, `$ docker trust generate <name>`. Running this command will automatically load the delegation private key in to the local Docker trust store.

```console
$ docker trust key generate jeff

Generating key for jeff...
Enter passphrase for new jeff key with ID 9deed25: 
Repeat passphrase for new jeff key with ID 9deed25: 
Successfully generated and loaded private key. Corresponding public key available: /home/ubuntu/Documents/mytrustdir/jeff.pub
```

### [Manually generating keys](#manually-generating-keys)

If you need to manually generate a private key (either RSA or ECDSA) and an X.509 certificate containing the public key, you can use local tools like openssl or cfssl along with a local or company-wide Certificate Authority.

Here is an example of how to generate a 2048-bit RSA portion key (all RSA keys must be at least 2048 bits):

```console
$ openssl genrsa -out delegation.key 2048

Generating RSA private key, 2048 bit long modulus
....................................................+++
............+++
e is 65537 (0x10001)
```

They should keep `delegation.key` private because it is used to sign tags.

Then they need to generate an x509 certificate containing the public key, which is what you need from them. Here is the command to generate a CSR (certificate signing request):

```console
$ openssl req -new -sha256 -key delegation.key -out delegation.csr
```

Then they can send it to whichever CA you trust to sign certificates, or they can self-sign the certificate (in this example, creating a certificate that is valid for 1 year):

```console
$ openssl x509 -req -sha256 -days 365 -in delegation.csr -signkey delegation.key -out delegation.crt
```

Then they need to give you `delegation.crt`, whether it is self-signed or signed by a CA.

Finally you will need to add the private key into your local Docker trust store.

```console
$ docker trust key load delegation.key --name jeff

Loading key from "delegation.key"...
Enter passphrase for new jeff key with ID 8ae710e: 
Repeat passphrase for new jeff key with ID 8ae710e: 
Successfully imported key from delegation.key
```

### [Viewing local delegation keys](#viewing-local-delegation-keys)

To list the keys that have been imported in to the local Docker trust store we can use the Notary CLI.

```console
$ notary key list

ROLE       GUN                          KEY ID                                                              LOCATION
----       ---                          ------                                                              --------
root                                    f6c6a4b00fefd8751f86194c7d87a3bede444540eb3378c4a11ce10852ab1f96    /home/ubuntu/.docker/trust/private
jeff                                    9deed251daa1aa6f9d5f9b752847647cf8d705da0763aa5467650d0987ed5306    /home/ubuntu/.docker/trust/private
```

## [Managing delegations in a Notary Server](#managing-delegations-in-a-notary-server)

When the first delegation is added to the Notary Server using `$ docker trust`, we automatically initiate trust data for the repository. This includes creating the notary target and snapshots keys, and rotating the snapshot key to be managed by the notary server. More information on these keys can be found in [Manage keys for content trust](https://docs.docker.com/engine/security/trust/trust_key_mng/).

When initiating a repository, you will need the key and the passphrase of a local Notary Canonical Root Key. If you have not initiated a repository before, and therefore don't have a Notary root key, `$ docker trust` will create one for you.

> Important
>
> Be sure to protect and back up your [Notary Canonical Root Key](https://docs.docker.com/engine/security/trust/trust_key_mng/).

### [Initiating the repository](#initiating-the-repository)

To upload the first key to a delegation, at the same time initiating a repository, you can use the `$ docker trust signer add` command. This will add the contributor's public key to the `targets/releases` delegation, and create a second `targets/<name>` delegation.

For DCT the name of the second delegation, in the below example `jeff`, is there to help you keep track of the owner of the keys. In more advanced use cases of Notary additional delegations are used for hierarchy.

```console
$ docker trust signer add --key cert.pem jeff registry.example.com/admin/demo

Adding signer "jeff" to registry.example.com/admin/demo...
Initializing signed repository for registry.example.com/admin/demo...
Enter passphrase for root key with ID f6c6a4b: 
Enter passphrase for new repository key with ID b0014f8: 
Repeat passphrase for new repository key with ID b0014f8: 
Successfully initialized "registry.example.com/admin/demo"
Successfully added signer: jeff to registry.example.com/admin/demo
```

You can see which keys have been pushed to the Notary server for each repository with the `$ docker trust inspect` command.

```console
$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures for registry.example.com/admin/demo


List of signers and their keys for registry.example.com/admin/demo

SIGNER              KEYS
jeff                1091060d7bfd

Administrative keys for registry.example.com/admin/demo

  Repository Key:	b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
  Root Key:	64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7
```

You could also use the Notary CLI to list delegations and keys. Here you can clearly see the keys were attached to `targets/releases` and `targets/jeff`.

```console
$ notary delegation list registry.example.com/admin/demo

ROLE                PATHS             KEY IDS                                                             THRESHOLD
----                -----             -------                                                             ---------
targets/jeff        "" <all paths>    1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    1
                                          
targets/releases    "" <all paths>    1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    1 
```

### [Adding additional signers](#adding-additional-signers)

Docker Trust allows you to configure multiple delegations per repository, allowing you to manage the lifecycle of delegations. When adding additional delegations with `$ docker trust` the collaborators key is once again added to the `targets/release` role.

> Note you will need the passphrase for the repository key; this would have been configured when you first initiated the repository.

```console
$ docker trust signer add --key ben.pub ben registry.example.com/admin/demo

Adding signer "ben" to registry.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8: 
Successfully added signer: ben to registry.example.com/admin/demo
```

Check to prove that there are now 2 delegations (Signer).

```console
$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures for registry.example.com/admin/demo

List of signers and their keys for registry.example.com/admin/demo

SIGNER              KEYS
ben                 afa404703b25
jeff                1091060d7bfd

Administrative keys for registry.example.com/admin/demo

  Repository Key:	b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
  Root Key:	64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7
```

### [Adding keys to an existing delegation](#adding-keys-to-an-existing-delegation)

To support things like key rotation and expiring / retiring keys you can publish multiple contributor keys per delegation. The only prerequisite here is to make sure you use the same the delegation name, in this case `jeff`. Docker trust will automatically handle adding this new key to `targets/releases`.

> Note
>
> You will need the passphrase for the repository key; this would have been configured when you first initiated the repository.

```console
$ docker trust signer add --key cert2.pem jeff registry.example.com/admin/demo

Adding signer "jeff" to registry.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8: 
Successfully added signer: jeff to registry.example.com/admin/demo
```

Check to prove that the delegation (Signer) now contains multiple Key IDs.

```console
$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures for registry.example.com/admin/demo


List of signers and their keys for registry.example.com/admin/demo

SIGNER              KEYS
jeff                1091060d7bfd, 5570b88df073

Administrative keys for registry.example.com/admin/demo

  Repository Key:	b0014f8e4863df2d028095b74efcb05d872c3591de0af06652944e310d96598d
  Root Key:	64d147e59e44870311dd2d80b9f7840039115ef3dfa5008127d769a5f657a5d7
```

### [Removing a delegation](#removing-a-delegation)

If you need to remove a delegation, including the contributor keys that are attached to the `targets/releases` role, you can use the `$ docker trust signer remove` command.

> Note
>
> Tags that were signed by the removed delegation will need to be resigned by an active delegation

```console
$ docker trust signer remove ben registry.example.com/admin/demo
Removing signer "ben" from registry.example.com/admin/demo...
Enter passphrase for repository key with ID b0014f8: 
Successfully removed ben from registry.example.com/admin/demo
```

#### [Troubleshooting](#troubleshooting)

1. If you see an error that there are no usable keys in `targets/releases`, you will need to add additional delegations using `docker trust signer add` before resigning images.

   ```text
   WARN[0000] role targets/releases has fewer keys than its threshold of 1; it will not be usable until keys are added to it
   ```

2. If you have added additional delegations already and are seeing an error message that there are no valid signatures in `targets/releases`, you will need to resign the `targets/releases` delegation file with the Notary CLI.

   ```text
   WARN[0000] Error getting targets/releases: valid signatures did not meet threshold for targets/releases 
   ```

   Resigning the delegation file is done with the `$ notary witness` command

   ```console
   $ notary witness registry.example.com/admin/demo targets/releases --publish
   ```

   For more information on the `notary witness` command, refer to the [Notary client advanced usage guide](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#recovering-a-delegation)

### [Removing a contributor's key from a delegation](#removing-a-contributors-key-from-a-delegation)

As part of rotating keys for a delegation, you may want to remove an individual key but retain the delegation. This can be done with the Notary CLI.

Remember you will have to remove the key from both the `targets/releases` role and the role specific to that signer `targets/<name>`.

1. We will need to grab the Key ID from the Notary Server

   ```console
   $ notary delegation list registry.example.com/admin/demo

   ROLE                PATHS             KEY IDS                                                             THRESHOLD
   ----                -----             -------                                                             ---------
   targets/jeff        "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1
                                         1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    
   targets/releases    "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1
                                         1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    
   ```

2. Remove from the `targets/releases` delegation

   ```console
   $ notary delegation remove registry.example.com/admin/demo targets/releases 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 --publish

   Auto-publishing changes to registry.example.com/admin/demo
   Enter username: admin
   Enter password: 
   Enter passphrase for targets key with ID b0014f8: 
   Successfully published changes for repository registry.example.com/admin/demo
   ```

3. Remove from the `targets/<name>` delegation

   ```console
   $ notary delegation remove registry.example.com/admin/demo targets/jeff 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 --publish

   Removal of delegation role targets/jeff with keys [5570b88df0736c468493247a07e235e35cf3641270c944d0e9e8899922fc6f99], to repository "registry.example.com/admin/demo" staged for next publish.

   Auto-publishing changes to registry.example.com/admin/demo
   Enter username: admin    
   Enter password: 
   Enter passphrase for targets key with ID b0014f8: 
   Successfully published changes for repository registry.example.com/admin/demo
   ```

4. Check the remaining delegation list

   ```console
   $ notary delegation list registry.example.com/admin/demo

   ROLE                PATHS             KEY IDS                                                             THRESHOLD
   ----                -----             -------                                                             ---------
   targets/jeff        "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1    
   targets/releases    "" <all paths>    8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    1    
   ```

### [Removing a local delegation private key](#removing-a-local-delegation-private-key)

As part of rotating delegation keys, you may need to remove a local delegation key from the local Docker trust store. This is done with the Notary CLI, using the `$ notary key remove` command.

1. We will need to get the Key ID from the local Docker Trust store

   ```console
   $ notary key list

   ROLE       GUN                          KEY ID                                                              LOCATION
   ----       ---                          ------                                                              --------
   root                                    f6c6a4b00fefd8751f86194c7d87a3bede444540eb3378c4a11ce10852ab1f96    /home/ubuntu/.docker/trust/private
   admin                                   8fb597cbaf196f0781628b2f52bff6b3912e4e8075720378fda60d17232bbcf9    /home/ubuntu/.docker/trust/private
   jeff                                    1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1    /home/ubuntu/.docker/trust/private
   targets    ...example.com/admin/demo    c819f2eda8fba2810ec6a7f95f051c90276c87fddfc3039058856fad061c009d    /home/ubuntu/.docker/trust/private
   ```

2. Remove the key from the local Docker Trust store

   ```console
   $ notary key remove 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1

   Are you sure you want to remove 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 (role jeff) from /home/ubuntu/.docker/trust/private?  (yes/no)  y

   Deleted 1091060d7bfd938dfa5be703fa057974f9322a4faef6f580334f3d6df44c02d1 (role jeff) from /home/ubuntu/.docker/trust/private.
   ```

## [Removing all trust data from a repository](#removing-all-trust-data-from-a-repository)

You can remove all trust data from a repository, including repository, target, snapshot and all delegations keys using the Notary CLI.

This is often required by a container registry before a particular repository can be deleted.

```console
$ notary delete registry.example.com/admin/demo --remote

Deleting trust data for repository registry.example.com/admin/demo
Enter username: admin
Enter password: 
Successfully deleted local and remote trust data for repository registry.example.com/admin/demo

$ docker trust inspect --pretty registry.example.com/admin/demo

No signatures or cannot access registry.example.com/admin/demo
```

## [Related information](#related-information)

* [Content trust in Docker](https://docs.docker.com/engine/security/trust/)
* [Manage keys for content trust](https://docs.docker.com/engine/security/trust/trust_key_mng/)
* [Automation with content trust](https://docs.docker.com/engine/security/trust/trust_automation/)
* [Play in a content trust sandbox](https://docs.docker.com/engine/security/trust/trust_sandbox/)

----
url: https://docs.docker.com/reference/cli/docker/model/
----

# docker model

***

| Description | Docker Model Runner |
| ----------- | ------------------- |

## [Description](#description)

Use Docker Model Runner to run and interact with AI models directly from the command line. For more information, see the [documentation](/ai/model-runner/)

## [Subcommands](#subcommands)

| Command                                                                                                 | Description                                                            |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [`docker model bench`](https://docs.docker.com/reference/cli/docker/model/bench/)                       | Benchmark a model's performance at different concurrency levels        |
| [`docker model context`](https://docs.docker.com/reference/cli/docker/model/context/)                   | Manage Docker Model Runner contexts                                    |
| [`docker model df`](https://docs.docker.com/reference/cli/docker/model/df/)                             | Show Docker Model Runner disk usage                                    |
| [`docker model gateway`](https://docs.docker.com/reference/cli/docker/model/gateway/)                   | Run an OpenAI-compatible LLM gateway                                   |
| [`docker model inspect`](https://docs.docker.com/reference/cli/docker/model/inspect/)                   | Display detailed information on one model                              |
| [`docker model install-runner`](https://docs.docker.com/reference/cli/docker/model/install-runner/)     | Install Docker Model Runner (Docker Engine only)                       |
| [`docker model launch`](https://docs.docker.com/reference/cli/docker/model/launch/)                     | Launch an app configured to use Docker Model Runner                    |
| [`docker model list`](https://docs.docker.com/reference/cli/docker/model/list/)                         | List the models pulled to your local environment                       |
| [`docker model logs`](https://docs.docker.com/reference/cli/docker/model/logs/)                         | Fetch the Docker Model Runner logs                                     |
| [`docker model package`](https://docs.docker.com/reference/cli/docker/model/package/)                   | Package a model into a Docker Model OCI artifact                       |
| [`docker model ps`](https://docs.docker.com/reference/cli/docker/model/ps/)                             | List running models                                                    |
| [`docker model pull`](https://docs.docker.com/reference/cli/docker/model/pull/)                         | Pull a model from Docker Hub or HuggingFace to your local environment  |
| [`docker model purge`](https://docs.docker.com/reference/cli/docker/model/purge/)                       | Remove all models                                                      |
| [`docker model push`](https://docs.docker.com/reference/cli/docker/model/push/)                         | Push a model to Docker Hub or Hugging Face                             |
| [`docker model reinstall-runner`](https://docs.docker.com/reference/cli/docker/model/reinstall-runner/) | Reinstall Docker Model Runner (Docker Engine only)                     |
| [`docker model requests`](https://docs.docker.com/reference/cli/docker/model/requests/)                 | Fetch requests+responses from Docker Model Runner                      |
| [`docker model restart-runner`](https://docs.docker.com/reference/cli/docker/model/restart-runner/)     | Restart Docker Model Runner (Docker Engine only)                       |
| [`docker model rm`](https://docs.docker.com/reference/cli/docker/model/rm/)                             | Remove local models downloaded from Docker Hub                         |
| [`docker model run`](https://docs.docker.com/reference/cli/docker/model/run/)                           | Run a model and interact with it using a submitted prompt or chat mode |
| [`docker model search`](https://docs.docker.com/reference/cli/docker/model/search/)                     | Search for models on Docker Hub and HuggingFace                        |
| [`docker model show`](https://docs.docker.com/reference/cli/docker/model/show/)                         | Show information for a model                                           |
| [`docker model skills`](https://docs.docker.com/reference/cli/docker/model/skills/)                     | Install Docker Model Runner skills for AI coding assistants            |
| [`docker model start-runner`](https://docs.docker.com/reference/cli/docker/model/start-runner/)         | Start Docker Model Runner (Docker Engine only)                         |
| [`docker model status`](https://docs.docker.com/reference/cli/docker/model/status/)                     | Check if the Docker Model Runner is running                            |
| [`docker model stop-runner`](https://docs.docker.com/reference/cli/docker/model/stop-runner/)           | Stop Docker Model Runner (Docker Engine only)                          |
| [`docker model tag`](https://docs.docker.com/reference/cli/docker/model/tag/)                           | Tag a model                                                            |
| [`docker model uninstall-runner`](https://docs.docker.com/reference/cli/docker/model/uninstall-runner/) | Uninstall Docker Model Runner (Docker Engine only)                     |
| [`docker model unload`](https://docs.docker.com/reference/cli/docker/model/unload/)                     | Unload running models                                                  |
| [`docker model version`](https://docs.docker.com/reference/cli/docker/model/version/)                   | Show the Docker Model Runner version                                   |

----
url: https://docs.docker.com/build/bake/compose-file/
----

# Building with Bake from a Compose file

***

Table of contents

***

Bake supports the [Compose file format](https://docs.docker.com/reference/compose-file/) to parse a Compose file and translate each service to a [target](https://docs.docker.com/build/bake/reference/#target).

```yaml
# compose.yaml
services:
  webapp-dev:
    build: &build-dev
      dockerfile: Dockerfile.webapp
      tags:
        - docker.io/username/webapp:latest
      cache_from:
        - docker.io/username/webapp:cache
      cache_to:
        - docker.io/username/webapp:cache

  webapp-release:
    build:
      <<: *build-dev
      x-bake:
        platforms:
          - linux/amd64
          - linux/arm64

  db:
    image: docker.io/username/db
    build:
      dockerfile: Dockerfile.db
```

```console
$ docker buildx bake --print
```

```json
{
  "group": {
    "default": {
      "targets": ["db", "webapp-dev", "webapp-release"]
    }
  },
  "target": {
    "db": {
      "context": ".",
      "dockerfile": "Dockerfile.db",
      "tags": ["docker.io/username/db"]
    },
    "webapp-dev": {
      "context": ".",
      "dockerfile": "Dockerfile.webapp",
      "tags": ["docker.io/username/webapp:latest"],
      "cache-from": [
        {
          "ref": "docker.io/username/webapp:cache",
          "type": "registry"
        }
      ],
      "cache-to": [
        {
          "ref": "docker.io/username/webapp:cache",
          "type": "registry"
        }
      ]
    },
    "webapp-release": {
      "context": ".",
      "dockerfile": "Dockerfile.webapp",
      "tags": ["docker.io/username/webapp:latest"],
      "cache-from": [
        {
          "ref": "docker.io/username/webapp:cache",
          "type": "registry"
        }
      ],
      "cache-to": [
        {
          "ref": "docker.io/username/webapp:cache",
          "type": "registry"
        }
      ],
      "platforms": ["linux/amd64", "linux/arm64"]
    }
  }
}
```

The compose format has some limitations compared to the HCL format:

* Specifying variables or global scope attributes is not supported
* `inherits` service field is not supported, but you can use [YAML anchors](https://docs.docker.com/reference/compose-file/fragments/) to reference other services, as demonstrated in the previous example with `&build-dev`.

## [`.env` file](#env-file)

You can declare default environment variables in an environment file named `.env`. This file will be loaded from the current working directory, where the command is executed and applied to compose definitions passed with `-f`.

```yaml
# compose.yaml
services:
  webapp:
    image: docker.io/username/webapp:${TAG:-v1.0.0}
    build:
      dockerfile: Dockerfile
```

```sh
# .env
TAG=v1.1.0
```

```console
$ docker buildx bake --print
```

```json
{
  "group": {
    "default": {
      "targets": ["webapp"]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": ["docker.io/username/webapp:v1.1.0"]
    }
  }
}
```

> Note
>
> System environment variables take precedence over environment variables in `.env` file.

## [Extension field with `x-bake`](#extension-field-with-x-bake)

Where some fields are not available in the compose specification, you can use the [special extension](https://docs.docker.com/reference/compose-file/extension/) field `x-bake` in your compose file to evaluate extra fields:

```yaml
# compose.yaml
services:
  addon:
    image: ct-addon:bar
    build:
      context: .
      dockerfile: ./Dockerfile
      args:
        CT_ECR: foo
        CT_TAG: bar
      x-bake:
        tags:
          - ct-addon:foo
          - ct-addon:alp
        platforms:
          - linux/amd64
          - linux/arm64
        cache-from:
          - user/app:cache
          - type=local,src=path/to/cache
        cache-to:
          - type=local,dest=path/to/cache
        pull: true

  aws:
    image: ct-fake-aws:bar
    build:
      dockerfile: ./aws.Dockerfile
      args:
        CT_ECR: foo
        CT_TAG: bar
      x-bake:
        secret:
          - id=mysecret,src=./secret
          - id=mysecret2,src=./secret2
        platforms: linux/arm64
        output: type=docker
        no-cache: true
```

```console
$ docker buildx bake --print
```

```json
{
  "group": {
    "default": {
      "targets": ["addon", "aws"]
    }
  },
  "target": {
    "addon": {
      "context": ".",
      "dockerfile": "./Dockerfile",
      "args": {
        "CT_ECR": "foo",
        "CT_TAG": "bar"
      },
      "tags": ["ct-addon:foo", "ct-addon:alp"],
      "cache-from": [
        {
          "ref": "user/app:cache",
          "type": "registry"
        },
        {
          "src": "path/to/cache",
          "type": "local"
        }
      ],
      "cache-to": [
        {
          "dest": "path/to/cache",
          "type": "local"
        }
      ],
      "platforms": ["linux/amd64", "linux/arm64"],
      "pull": true
    },
    "aws": {
      "context": ".",
      "dockerfile": "./aws.Dockerfile",
      "args": {
        "CT_ECR": "foo",
        "CT_TAG": "bar"
      },
      "tags": ["ct-fake-aws:bar"],
      "secret": [
        {
          "id": "mysecret",
          "src": "./secret"
        },
        {
          "id": "mysecret2",
          "src": "./secret2"
        }
      ],
      "platforms": ["linux/arm64"],
      "output": [
        {
          "type": "docker"
        }
      ],
      "no-cache": true
    }
  }
}
```

Complete list of valid fields for `x-bake`:

* `cache-from`
* `cache-to`
* `contexts`
* `no-cache`
* `no-cache-filter`
* `output`
* `platforms`
* `pull`
* `secret`
* `ssh`
* `tags`

----
url: https://docs.docker.com/scout/integrations/ci/gitlab/
----

# Integrate Docker Scout with GitLab CI/CD

***

Table of contents

***

The following examples runs in GitLab CI in a repository containing a Docker image's definition and contents. Triggered by a commit, the pipeline builds the image. If the commit was to the default branch, it uses Docker Scout to get a CVE report. If the commit was to a different branch, it uses Docker Scout to compare the new version to the current published version.

## [Steps](#steps)

First, set up the rest of the workflow. There's a lot that's not specific to Docker Scout but needed to create the images to compare.

Add the following to a `.gitlab-ci.yml` file at the root of your repository.

```yaml
docker-build:
  image: docker:latest
  stage: build
  services:
    - docker:dind
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

    # Install curl and the Docker Scout CLI
    - |
      apk add --update curl
      curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- 
      apk del curl 
      rm -rf /var/cache/apk/*
    # Login to Docker Hub required for Docker Scout CLI
    - echo "$DOCKER_HUB_PAT" | docker login -u "$DOCKER_HUB_USER" --password-stdin
```

This sets up the workflow to build Docker images with Docker-in-Docker mode, running Docker inside a container.

It then downloads `curl` and the Docker Scout CLI plugin, logs into the Docker registry using environment variables defined in your repository's settings.

Add the following to the YAML file:

```yaml
script:
  - |
    if [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]]; then
      tag=""
      echo "Running on default branch '$CI_DEFAULT_BRANCH': tag = 'latest'"
    else
      tag=":$CI_COMMIT_REF_SLUG"
      echo "Running on branch '$CI_COMMIT_BRANCH': tag = $tag"
    fi
  - docker build --pull -t "$CI_REGISTRY_IMAGE${tag}" .
  - |
    if [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]]; then
      # Get a CVE report for the built image and fail the pipeline when critical or high CVEs are detected
      docker scout cves "$CI_REGISTRY_IMAGE${tag}" --exit-code --only-severity critical,high    
    else
      # Compare image from branch with latest image from the default branch and fail if new critical or high CVEs are detected
      docker scout compare "$CI_REGISTRY_IMAGE${tag}" --to "$CI_REGISTRY_IMAGE:latest" --exit-code --only-severity critical,high --ignore-unchanged
    fi

  - docker push "$CI_REGISTRY_IMAGE${tag}"
```

This creates the flow mentioned previously. If the commit was to the default branch, Docker Scout generates a CVE report. If the commit was to a different branch, Docker Scout compares the new version to the current published version. It only shows critical or high-severity vulnerabilities and ignores vulnerabilities that haven't changed since the last analysis.

Add the following to the YAML file:

```yaml
rules:
  - if: $CI_COMMIT_BRANCH
    exists:
      - Dockerfile
```

These final lines ensure that the pipeline only runs if the commit contains a Dockerfile and if the commit was to the CI branch.

## [Video walkthrough](#video-walkthrough)

The following is a video walkthrough of the process of setting up the workflow with GitLab.

----
url: https://docs.docker.com/guides/docker-build-cloud/why/
----

# Why Docker Build Cloud?

***

***

Docker Build Cloud is a service that lets you build container images faster, both locally and in CI. Builds run on cloud infrastructure optimally dimensioned for your workloads, with no configuration required. The service uses a remote build cache, ensuring fast builds anywhere and for all team members.

Docker Build Cloud provides several benefits over local builds:

* Improved build speed
* Shared build cache
* Native multi-platform builds

There’s no need to worry about managing builders or infrastructure — simply connect to your builders and start building. Each cloud builder provisioned to an organization is completely isolated to a single Amazon EC2 instance, with a dedicated EBS volume for build cache and encryption in transit. That means there are no shared processes or data between cloud builders.

[Demo: set up and use Docker Build Cloud in development »](https://docs.docker.com/guides/docker-build-cloud/dev/)

----
url: https://docs.docker.com/reference/cli/docker/scout/cves/
----

# docker scout cves

***

| Description | Display CVEs identified in a software artifact            |
| ----------- | --------------------------------------------------------- |
| Usage       | `docker scout cves [OPTIONS] [IMAGE\|DIRECTORY\|ARCHIVE]` |

## [Description](#description)

The `docker scout cves` command analyzes a software artifact for vulnerabilities.

| Option                 | Default             | Description                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--details`            |                     | Print details on default text output                                                                                                                                                                                                                                                                                            |
| `--env`                |                     | Name of environment                                                                                                                                                                                                                                                                                                             |
| [`--epss`](#epss)      |                     | Display the EPSS scores and organize the package's CVEs according to their EPSS score                                                                                                                                                                                                                                           |
| `--epss-percentile`    |                     | Exclude CVEs with EPSS scores less than the specified percentile (0 to 1)                                                                                                                                                                                                                                                       |
| `--epss-score`         |                     | Exclude CVEs with EPSS scores less than the specified value (0 to 1)                                                                                                                                                                                                                                                            |
| `-e, --exit-code`      |                     | Return exit code '2' if vulnerabilities are detected                                                                                                                                                                                                                                                                            |
| `--format`             | `packages`          | Output format of the generated vulnerability report: - packages: default output, plain text with vulnerabilities grouped by packages - sarif: json Sarif output - spdx: json SPDX output - gitlab: json GitLab output - markdown: markdown output (including some html tags like collapsible sections) - sbom: json SBOM output |
| `--ignore-base`        |                     | Filter out CVEs introduced from base image                                                                                                                                                                                                                                                                                      |
| `--ignore-suppressed`  |                     | Filter CVEs found in Scout exceptions based on the specified exception scope                                                                                                                                                                                                                                                    |
| `--locations`          |                     | Print package locations including file paths and layer diff\_id                                                                                                                                                                                                                                                                 |
| `--multi-stage`        |                     | Show packages from multi-stage Docker builds                                                                                                                                                                                                                                                                                    |
| `--only-base`          |                     | Only show CVEs introduced by the base image                                                                                                                                                                                                                                                                                     |
| `--only-cisa-kev`      |                     | Filter to CVEs listed in the CISA KEV catalog                                                                                                                                                                                                                                                                                   |
| `--only-cve-id`        |                     | Comma separated list of CVE ids (like CVE-2021-45105) to search for                                                                                                                                                                                                                                                             |
| `--only-fixed`         |                     | Filter to fixable CVEs                                                                                                                                                                                                                                                                                                          |
| `--only-metric`        |                     | Comma separated list of CVSS metrics (like AV:N or PR:L) to filter CVEs by                                                                                                                                                                                                                                                      |
| `--only-package`       |                     | Comma separated regular expressions to filter packages by                                                                                                                                                                                                                                                                       |
| `--only-package-type`  |                     | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc)                                                                                                                                                                                                                                              |
| `--only-severity`      |                     | Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by                                                                                                                                                                                                                                 |
| `--only-stage`         |                     | Comma separated list of multi-stage Docker build stage names                                                                                                                                                                                                                                                                    |
| `--only-unfixed`       |                     | Filter to unfixed CVEs                                                                                                                                                                                                                                                                                                          |
| `--only-vex-affected`  |                     | Filter CVEs by VEX statements with status not affected                                                                                                                                                                                                                                                                          |
| `--only-vuln-packages` |                     | When used with --format=only-packages ignore packages with no vulnerabilities                                                                                                                                                                                                                                                   |
| `--org`                |                     | Namespace of the Docker organization                                                                                                                                                                                                                                                                                            |
| `-o, --output`         |                     | Write the report to a file                                                                                                                                                                                                                                                                                                      |
| `--platform`           |                     | Platform of image to analyze                                                                                                                                                                                                                                                                                                    |
| `--ref`                |                     | Reference to use if the provided tarball contains multiple references. Can only be used with archive                                                                                                                                                                                                                            |
| `--vex-author`         | `[<.*@docker.com>]` | List of VEX statement authors to accept                                                                                                                                                                                                                                                                                         |
| `--vex-location`       |                     | File location of directory or file containing VEX statements                                                                                                                                                                                                                                                                    |

## [Examples](#examples)

### [Display vulnerabilities grouped by package](#display-vulnerabilities-grouped-by-package)

```console
$ docker scout cves alpine
Analyzing image alpine
✓ Image stored for indexing
✓ Indexed 18 packages
✓ No vulnerable package detected
```

### [Display vulnerabilities from a `docker save` tarball](#display-vulnerabilities-from-a-docker-save-tarball)

```console
$ docker save alpine > alpine.tar

$ docker scout cves archive://alpine.tar
Analyzing archive alpine.tar
✓ Archive read
✓ SBOM of image already cached, 18 packages indexed
✓ No vulnerable package detected
```

### [Display vulnerabilities from an OCI directory](#display-vulnerabilities-from-an-oci-directory)

```console
$ skopeo copy --override-os linux docker://alpine oci:alpine

$ docker scout cves oci-dir://alpine
Analyzing OCI directory alpine
✓ OCI directory read
✓ Image stored for indexing
✓ Indexed 19 packages
✓ No vulnerable package detected
```

### [Display vulnerabilities from the current directory](#display-vulnerabilities-from-the-current-directory)

```console
$ docker scout cves fs://.
```

### [Export vulnerabilities to a SARIF JSON file](#export-vulnerabilities-to-a-sarif-json-file)

```console
$ docker scout cves --format sarif --output alpine.sarif.json alpine
Analyzing image alpine
✓ SBOM of image already cached, 18 packages indexed
✓ No vulnerable package detected
✓ Report written to alpine.sarif.json
```

### [Display markdown output](#display-markdown-output)

The following example shows how to generate the vulnerability report as markdown.

```console
$ docker scout cves --format markdown alpine
✓ Pulled
✓ SBOM of image already cached, 19 packages indexed
✗ Detected 1 vulnerable package with 3 vulnerabilities
<h2>:mag: Vulnerabilities of <code>alpine</code></h2>

<details open="true"><summary>:package: Image Reference</strong> <code>alpine</code></summary>
<table>
<tr><td>digest</td><td><code>sha256:e3bd82196e98898cae9fe7fbfd6e2436530485974dc4fb3b7ddb69134eda2407</code></td><tr><tr><td>vulnerabilities</td><td><img alt="critical: 0" src="https://img.shields.io/badge/critical-0-lightgrey"/> <img alt="high: 0" src="https://img.shields.io/badge/high-0-lightgrey"/> <img alt="medium: 2" src="https://img.shields.io/badge/medium-2-fbb552"/> <img alt="low: 0" src="https://img.shields.io/badge/low-0-lightgrey"/> <img alt="unspecified: 1" src="https://img.shields.io/badge/unspecified-1-lightgrey"/></td></tr>
<tr><td>platform</td><td>linux/arm64</td></tr>
<tr><td>size</td><td>3.3 MB</td></tr>
<tr><td>packages</td><td>19</td></tr>
</table>
</details></table>
</details>
...
```

### [List all vulnerable packages of a certain type](#list-all-vulnerable-packages-of-a-certain-type)

The following example shows how to generate a list of packages, only including packages of the specified type, and only showing packages that are vulnerable.

```console
$ docker scout cves --format only-packages --only-package-type golang --only-vuln-packages golang:1.18.0
✓ Pulled
✓ SBOM of image already cached, 296 packages indexed
✗ Detected 1 vulnerable package with 40 vulnerabilities

Name   Version   Type         Vulnerabilities
───────────────────────────────────────────────────────────
stdlib  1.18     golang     2C    29H     8M     1L
```

### [Display EPSS score (--epss)](#epss)

The `--epss` flag adds [Exploit Prediction Scoring System (EPSS)](https://www.first.org/epss/) scores to the `docker scout cves` output. EPSS scores are estimates of the likelihood (probability) that a software vulnerability will be exploited in the wild in the next 30 days. The higher the score, the greater the probability that a vulnerability will be exploited.

```console
$ docker scout cves --epss nginx
 ✓ Provenance obtained from attestation
 ✓ SBOM obtained from attestation, 232 packages indexed
 ✓ Pulled
 ✗ Detected 23 vulnerable packages with a total of 39 vulnerabilities

...

 ✗ HIGH CVE-2023-52425
   https://scout.docker.com/v/CVE-2023-52425
   Affected range  : >=2.5.0-1
   Fixed version   : not fixed
   EPSS Score      : 0.000510
   EPSS Percentile : 0.173680
```

* `EPSS Score` is a floating point number between 0 and 1 representing the probability of exploitation in the wild in the next 30 days (following score publication).
* `EPSS Percentile` is the percentile of the current score, the proportion of all scored vulnerabilities with the same or a lower EPSS score.

You can use the `--epss-score` and `--epss-percentile` flags to filter the output of `docker scout cves` based on these scores. For example, to only show vulnerabilities with an EPSS score higher than 0.5:

```console
$ docker scout cves --epss --epss-score 0.5 nginx
 ✓ SBOM of image already cached, 232 packages indexed
 ✓ EPSS scores for 2024-03-01 already cached
 ✗ Detected 1 vulnerable package with 1 vulnerability

...

 ✗ LOW CVE-2023-44487
   https://scout.docker.com/v/CVE-2023-44487
   Affected range  : >=1.22.1-9
   Fixed version   : not fixed
   EPSS Score      : 0.705850
   EPSS Percentile : 0.979410
```

EPSS scores are updated on a daily basis. By default, the latest available score is displayed. You can use the `--epss-date` flag to manually specify a date in the format `yyyy-mm-dd` for fetching EPSS scores.

```console
$ docker scout cves --epss --epss-date 2024-01-02 nginx
```

### [List vulnerabilities from an SPDX file](#list-vulnerabilities-from-an-spdx-file)

The following example shows how to generate a list of vulnerabilities from an SPDX file using `syft`.

```console
$ syft -o spdx-json alpine:3.16.1 | docker scout cves sbom://
 ✔ Pulled image
 ✔ Loaded image                                                                                                                              alpine:3.16.1
 ✔ Parsed image                                                                    sha256:3d81c46cd8756ddb6db9ec36fa06a6fb71c287fb265232ba516739dc67a5f07d
 ✔ Cataloged contents                                                                     274a317d88b54f9e67799244a1250cad3fe7080f45249fa9167d1f871218d35f
   ├── ✔ Packages                        [14 packages]
   ├── ✔ File digests                    [75 files]
   ├── ✔ File metadata                   [75 locations]
   └── ✔ Executables                     [16 executables]
    ✗ Detected 2 vulnerable packages with a total of 11 vulnerabilities
```

----
url: https://docs.docker.com/guides/testcontainers-python-getting-started/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

Run the tests using pytest:

```console
$ pytest -v
```

You should see output similar to:

```text
============================= test session starts ==============================
platform linux -- Python 3.13.x, pytest-9.x.x
collected 2 items

tests/test_customers.py::test_get_all_customers PASSED                   [ 50%]
tests/test_customers.py::test_get_customer_by_email PASSED               [100%]

============================== 2 passed in 1.90s ===============================
```

The tests run against a real PostgreSQL database instead of mocks, which gives more confidence in the implementation.

## [Summary](#summary)

The Testcontainers for Python library helps you write integration tests using the same type of database (Postgres) that you use in production, instead of mocks. Because you aren't using mocks and instead talk to real services, you're free to refactor code and still verify that the application works as expected.

In addition to PostgreSQL, Testcontainers for Python provides modules for many SQL databases, NoSQL databases, messaging queues, and more. You can use Testcontainers to run any containerized dependency for your tests.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [testcontainers-python documentation](https://testcontainers-python.readthedocs.io/)
* [Getting started with Testcontainers for Go](/guides/testcontainers-go-getting-started/)
* [Getting started with Testcontainers for Java](https://testcontainers.com/guides/getting-started-with-testcontainers-for-java/)
* [Getting started with Testcontainers for Node.js](https://testcontainers.com/guides/getting-started-with-testcontainers-for-nodejs/)

----
url: https://docs.docker.com/engine/logging/drivers/syslog/
----

# Syslog logging driver

***

Table of contents

***

The `syslog` logging driver routes logs to a `syslog` server. The `syslog` protocol uses a raw string as the log message and supports a limited set of metadata. The syslog message must be formatted in a specific way to be valid. From a valid message, the receiver can extract the following information:

* Priority: the logging level, such as `debug`, `warning`, `error`, `info`.
* Timestamp: when the event occurred.
* Hostname: where the event happened.
* Facility: which subsystem logged the message, such as `mail` or `kernel`.
* Process name and process ID (PID): The name and ID of the process that generated the log.

The format is defined in [RFC 5424](https://tools.ietf.org/html/rfc5424) and Docker's syslog driver implements the [ABNF reference](https://tools.ietf.org/html/rfc5424#section-6) in the following way:

```text
                TIMESTAMP SP HOSTNAME SP APP-NAME SP PROCID SP MSGID
                    +          +             +           |        +
                    |          |             |           |        |
                    |          |             |           |        |
       +------------+          +----+        |           +----+   +---------+
       v                            v        v                v             v
2017-04-01T17:41:05.616647+08:00 a.vm {taskid:aa,version:} 1787791 {taskid:aa,version:}
```

## [Usage](#usage)

To use the `syslog` driver as the default logging driver, set the `log-driver` and `log-opt` keys to appropriate values in the `daemon.json` file. For more about configuring Docker using `daemon.json`, see [daemon.json](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file).

> Note
>
> If you're using Docker Desktop, edit the daemon configuration through the Docker Desktop Dashboard. Open **Settings** and select **Docker Engine**. For details, see [Docker Engine settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine).

The following example sets the log driver to `syslog` and sets the `syslog-address` option. The `syslog-address` options supports both UDP and TCP; this example uses UDP.

```json
{
  "log-driver": "syslog",
  "log-opts": {
    "syslog-address": "udp://1.2.3.4:1111"
  }
}
```

Restart Docker for the changes to take effect.

> Note
>
> `log-opts` configuration options in the `daemon.json` configuration file must be provided as strings. Numeric and Boolean values (such as the value for `syslog-tls-skip-verify`) must therefore be enclosed in quotes (`"`).

You can set the logging driver for a specific container by using the `--log-driver` flag to `docker container create` or `docker run`:

```console
$ docker run \
      --log-driver syslog --log-opt syslog-address=udp://1.2.3.4:1111 \
      alpine echo hello world
```

## [Options](#options)

The following logging options are supported as options for the `syslog` logging driver. They can be set as defaults in the `daemon.json`, by adding them as key-value pairs to the `log-opts` JSON array. They can also be set on a given container by adding a `--log-opt <key>=<value>` flag for each option when starting the container.

| Option                   | Description                                                                                                                                                                                                                                                                                                      | Example value                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `syslog-address`         | The address of an external `syslog` server. The URI specifier may be `[tcp\|udp\|tcp+tls]://host:port`, `unix://path`, or `unixgram://path`. If the transport is `tcp`, `udp`, or `tcp+tls`, the default port is `514`.                                                                                          | `--log-opt syslog-address=tcp+tls://192.168.1.3:514`, `--log-opt syslog-address=unix:///tmp/syslog.sock` |
| `syslog-facility`        | The `syslog` facility to use. Can be the number or name for any valid `syslog` facility. See the [syslog documentation](https://tools.ietf.org/html/rfc5424#section-6.2.1).                                                                                                                                      | `--log-opt syslog-facility=daemon`                                                                       |
| `syslog-tls-ca-cert`     | The absolute path to the trust certificates signed by the CA. Ignored if the address protocol isn't `tcp+tls`.                                                                                                                                                                                                   | `--log-opt syslog-tls-ca-cert=/etc/ca-certificates/custom/ca.pem`                                        |
| `syslog-tls-cert`        | The absolute path to the TLS certificate file. Ignored if the address protocol isn't `tcp+tls`.                                                                                                                                                                                                                  | `--log-opt syslog-tls-cert=/etc/ca-certificates/custom/cert.pem`                                         |
| `syslog-tls-key`         | The absolute path to the TLS key file. Ignored if the address protocol isn't `tcp+tls`.                                                                                                                                                                                                                          | `--log-opt syslog-tls-key=/etc/ca-certificates/custom/key.pem`                                           |
| `syslog-tls-skip-verify` | If set to `true`, TLS verification is skipped when connecting to the `syslog` daemon. Defaults to `false`. Ignored if the address protocol isn't `tcp+tls`.                                                                                                                                                      | `--log-opt syslog-tls-skip-verify=true`                                                                  |
| `tag`                    | A string that's appended to the `APP-NAME` in the `syslog` message. By default, Docker uses the first 12 characters of the container ID to tag log messages. Refer to the [log tag option documentation](https://docs.docker.com/engine/logging/log_tags/) for customizing the log tag format.                   | `--log-opt tag=mailer`                                                                                   |
| `syslog-format`          | The `syslog` message format to use. If not specified the local Unix syslog format is used, without a specified hostname. Specify `rfc3164` for the RFC-3164 compatible format, `rfc5424` for RFC-5424 compatible format, or `rfc5424micro` for RFC-5424 compatible format with microsecond timestamp resolution. | `--log-opt syslog-format=rfc5424micro`                                                                   |
| `labels`                 | Applies when starting the Docker daemon. A comma-separated list of logging-related labels this daemon accepts. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                                                                                                            | `--log-opt labels=production_status,geo`                                                                 |
| `labels-regex`           | Applies when starting the Docker daemon. Similar to and compatible with `labels`. A regular expression to match logging-related labels. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                                                                                   | `--log-opt labels-regex=^(production_status\|geo)`                                                       |
| `env`                    | Applies when starting the Docker daemon. A comma-separated list of logging-related environment variables this daemon accepts. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                                                                                             | `--log-opt env=os,customer`                                                                              |
| `env-regex`              | Applies when starting the Docker daemon. Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                                                                       | `--log-opt env-regex=^(os\|customer)`                                                                    |

----
url: https://docs.docker.com/build/buildkit/frontend/
----

# Custom Dockerfile syntax

***

Table of contents

***

## [Dockerfile frontend](#dockerfile-frontend)

BuildKit supports loading frontends dynamically from container images. To use an external Dockerfile frontend, the first line of your [Dockerfile](https://docs.docker.com/reference/dockerfile/) needs to set the [`syntax` directive](https://docs.docker.com/reference/dockerfile/#syntax) pointing to the specific image you want to use:

```dockerfile
# syntax=[remote image reference]
```

For example:

```dockerfile
# syntax=docker/dockerfile:1
# syntax=docker.io/docker/dockerfile:1
# syntax=example.com/user/repo:tag@sha256:abcdef...
```

You can also use the predefined `BUILDKIT_SYNTAX` build argument to set the frontend image reference on the command line:

```console
$ docker build --build-arg BUILDKIT_SYNTAX=docker/dockerfile:1 .
```

This defines the location of the Dockerfile syntax that is used to build the Dockerfile. The BuildKit backend allows seamlessly using external implementations that are distributed as Docker images and execute inside a container sandbox environment.

Custom Dockerfile implementations allow you to:

* Automatically get bug fixes without updating the Docker daemon
* Make sure all users are using the same implementation to build your Dockerfile
* Use the latest features without updating the Docker daemon
* Try out new features or third-party features before they are integrated in the Docker daemon
* Use [alternative build definitions, or create your own](https://github.com/moby/buildkit#exploring-llb)
* Build your own Dockerfile frontend with custom features

> Note
>
> BuildKit ships with a built-in Dockerfile frontend, but it's recommended to use an external image to make sure that all users use the same version on the builder and to pick up bug fixes automatically without waiting for a new version of BuildKit or Docker Engine.

## [Official releases](#official-releases)

Docker distributes official versions of the images that can be used for building Dockerfiles under `docker/dockerfile` repository on Docker Hub. There are two channels where new images are released: `stable` and `labs`.

### [Stable channel](#stable-channel)

The `stable` channel follows [semantic versioning](https://semver.org). For example:

* `docker/dockerfile:1` - kept updated with the latest `1.x.x` minor *and* patch release.
* `docker/dockerfile:1.2` - kept updated with the latest `1.2.x` patch release, and stops receiving updates once version `1.3.0` is released.
* `docker/dockerfile:1.2.1` - immutable: never updated.

We recommend using `docker/dockerfile:1`, which always points to the latest stable release of the version 1 syntax, and receives both "minor" and "patch" updates for the version 1 release cycle. BuildKit automatically checks for updates of the syntax when performing a build, making sure you are using the most current version.

If a specific version is used, such as `1.2` or `1.2.1`, the Dockerfile needs to be updated manually to continue receiving bugfixes and new features. Old versions of the Dockerfile remain compatible with the new versions of the builder.

### [Labs channel](#labs-channel)

The `labs` channel provides early access to Dockerfile features that are not yet available in the `stable` channel. `labs` images are released at the same time as stable releases, and follow the same version pattern, but use the `-labs` suffix, for example:

* `docker/dockerfile:labs` - latest release on `labs` channel.
* `docker/dockerfile:1-labs` - same as `dockerfile:1`, with experimental features enabled.
* `docker/dockerfile:1.2-labs` - same as `dockerfile:1.2`, with experimental features enabled.
* `docker/dockerfile:1.2.1-labs` - immutable: never updated. Same as `dockerfile:1.2.1`, with experimental features enabled.

Choose a channel that best fits your needs. If you want to benefit from new features, use the `labs` channel. Images in the `labs` channel contain all the features in the `stable` channel, plus early access features. Stable features in the `labs` channel follow [semantic versioning](https://semver.org), but early access features don't, and newer releases may not be backwards compatible. Pin the version to avoid having to deal with breaking changes.

## [Other resources](#other-resources)

For documentation on `labs` features, master builds, and nightly feature releases, refer to the description in [the BuildKit source repository on GitHub](https://github.com/moby/buildkit/blob/master/README.md). For a full list of available images, visit the [`docker/dockerfile` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile), and the [`docker/dockerfile-upstream` repository on Docker Hub](https://hub.docker.com/r/docker/dockerfile-upstream) for development builds.

----
url: https://docs.docker.com/reference/cli/sbx/policy/reset/
----

# sbx policy reset

| Description | Reset policies to defaults |
| ----------- | -------------------------- |
| Usage       | `sbx policy reset [flags]` |

## [Description](#description)

Remove all custom policies and restart the daemon to restore defaults.

This deletes the local policy store and stops the daemon. When the daemon restarts (automatically on next command), the default policy is installed.

If sandboxes are currently running, they will be stopped when the daemon shuts down. You will be prompted for confirmation unless --force is used.

## [Options](#options)

| Option        | Default | Description              |
| ------------- | ------- | ------------------------ |
| `-f, --force` |         | Skip confirmation prompt |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Reset policies (prompts if sandboxes are running)
sbx policy reset

# Reset policies without confirmation
sbx policy reset --force
```

----
url: https://docs.docker.com/billing/3d-secure/
----

# Use 3D Secure authentication for Docker billing

***

Table of contents

***

Docker supports 3D Secure (3DS), an extra layer of authentication required for certain credit card payments. If your bank or card issuer requires 3DS, you may need to verify your identity before your payment can be completed.

## [How it works](#how-it-works)

When a 3DS check is triggered during checkout, your bank or card issuer may ask you to verify your identity. This can include:

* Entering a one-time password sent to your phone
* Approving the charge through your mobile banking app
* Answering a security question or using biometrics

The exact verification steps depend on your financial institution's requirements.

## [When you need to verify](#when-you-need-to-verify)

You may be asked to verify your identity when performing any of the following actions:

* Starting a [paid subscription](https://docs.docker.com/subscription/setup/)
* Changing your [billing cycle](https://docs.docker.com/billing/cycle/) from monthly to annual
* [Upgrading your subscription](https://docs.docker.com/subscription/change/)
* [Adding seats](https://docs.docker.com/subscription/manage-seats/) to an existing subscription

If 3DS is required and your payment method supports it, the verification prompt will appear during checkout.

## [Troubleshooting payment verification](#troubleshooting-payment-verification)

If you're unable to complete your payment due to 3DS:

1. Retry your transaction. Make sure you're completing the verification prompt in the same browser tab.
2. Use a different payment method. Some cards may not support 3DS properly or be blocked.
3. Contact your bank. Your bank may be blocking the payment or the 3DS verification attempt.

> Note
>
> Disabling ad blockers or browser extensions that block pop-ups can help the 3DS prompt display correctly.

----
url: https://docs.docker.com/reference/cli/docker/debug/
----

# docker debug

***

| Description | Get a shell into any container or image. An alternative to debugging with \`docker exec\`. |
| ----------- | ------------------------------------------------------------------------------------------ |
| Usage       | `debug [OPTIONS] {CONTAINER\|IMAGE}`                                                       |

## [Description](#description)

Docker Debug is a CLI command that helps you follow best practices by keeping your images small and secure. With Docker Debug, you can debug your images while they contain the bare minimum to run your application. It does this by letting you create and work with slim images or containers that are often difficult to debug because all tools have been removed. For example, while typical debug approaches like `docker exec -it my-app bash` may not work on a slim container, `docker debug` will work.

With `docker debug` you can get a debug shell into any container or image, even if they don't contain a shell. You don't need to modify the image to use Docker Debug. However, using Docker Debug still won't modify your image. Docker Debug brings its own toolbox that you can easily customize. The toolbox comes with many standard Linux tools pre-installed, such as `vim`, `nano`, `htop`, and `curl`. Use the builtin `install` command to add additional tools available on <https://search.nixos.org/packages>. Docker Debug supports `bash`, `fish`, and `zsh`. By default it tries to auto-detect your shell.

Custom builtin tools:

* `install [tool1] [tool2]`: Add Nix packages from: <https://search.nixos.org/packages>, see [example](#managing-your-toolbox-using-the-install-command).
* `uninstall [tool1] [tool2]`: Uninstall Nix packages.
* `entrypoint`: Print, lint, or run the entrypoint, see [example](#understanding-the-default-startup-command-of-a-container-entry-points).
* `builtins`: Show custom builtin tools.

> Note
>
> For images and stopped containers, all changes are discarded when leaving the shell. At no point, do changes affect the actual image or container. When accessing running or paused containers, all filesystem changes are directly visible to the container. The `/nix` directory is never visible to the actual image or container.

## [Options](#options)

| Option          | Default | Description                                                                                                                                                    |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--shell`       | `auto`  | Select a shell. Supported: `bash`, `fish`, `zsh`, `auto`.                                                                                                      |
| `-c, --command` |         | Evaluate the specified commands instead of starting an interactive session, see [example](#running-commands-directly-eg-for-scripting).                        |
| `--host`        |         | Daemon docker socket to connect to. E.g.: `ssh://root@example.org`, `unix:///some/path/docker.sock`, see [example](#remote-debugging-using-the---host-option). |

## [Examples](#examples)

### [Debugging containers that have no shell (slim containers)](#debugging-containers-that-have-no-shell-slim-containers)

The `hello-world` image is very simple and only contains the `/hello` binary. It's a good example of a slim image. There are no other tools and no shell.

Run a container from the `hello-world` image:

```console
$ docker run --name my-app hello-world
```

The container exits immediately. To get a debug shell inside, run:

```console
$ docker debug my-app
```

The debug shell allows you to inspect the filesystem:

```console
docker > ls
dev  etc  hello  nix  proc  sys
```

The file `/hello` is the binary that was executed when running the container. You can confirm this by running it directly:

```console
docker > /hello
```

After running the binary, it produces the same output.

### [Debugging (slim) images](#debugging-slim-images)

You can debug images directly by running:

```console
$ docker debug hello-world
...
docker > ls
dev  etc  hello  nix  proc  sys
```

You don't even need to pull the image as `docker debug` will do this automatically like the `docker run` command.

### [Modifying files of a running container](#modifying-files-of-a-running-container)

Docker debug lets you modify files in any running container. The toolbox comes with `vim` and `nano` pre-installed.

Run an nginx container and change the default `index.html`:

```console
$ docker run -d --name web-app -p 8080:80 nginx
d3d6074d0ea901c96cac8e49e6dad21359616bef3dc0623b3c2dfa536c31dfdb
```

To confirm nginx is running, open a browser and navigate to http\://localhost:8080. You should see the default nginx page. Now, change it using vim:

```console
vim /usr/share/nginx/html/index.html
```

Change the title to "Welcome to my app!" and save the file. Now, reload the page in the browser and you should see the updated page.

### [Managing your toolbox using the `install` command](#managing-your-toolbox-using-the-install-command)

The builtin `install` command lets you add any tool from <https://search.nixos.org/packages> to the toolbox. Keep in mind adding a tool never modifies the actual image or container. Tools get added to only your toolbox. Run `docker debug` and then install `nmap`:

```console
$ docker debug nginx
...
docker > install nmap
Tip: You can install any package available at: https://search.nixos.org/packages.
installing 'nmap-7.93'
these 2 paths will be fetched (5.58 MiB download, 26.27 MiB unpacked):
/nix/store/brqjf4i23fagizaq2gn4d6z0f406d0kg-lua-5.3.6
/nix/store/xqd17rhgmn6pg85a3g18yqxpcya6d06r-nmap-7.93
copying path '/nix/store/brqjf4i23fagizaq2gn4d6z0f406d0kg-lua-5.3.6' from 'https://cache.nixos.org'...
copying path '/nix/store/xqd17rhgmn6pg85a3g18yqxpcya6d06r-nmap-7.93' from 'https://cache.nixos.org'...
building '/nix/store/k8xw5wwarh8dc1dvh5zx8rlwamxfsk3d-user-environment.drv'...

docker > nmap --version
Nmap version 7.93 ( https://nmap.org )
Platform: x86_64-unknown-linux-gnu
Compiled with: liblua-5.3.6 openssl-3.0.11 libssh2-1.11.0 nmap-libz-1.2.12 libpcre-8.45 libpcap-1.10.4 nmap-libdnet-1.12 ipv6
Compiled without:
Available nsock engines: epoll poll select
```

You can confirm `nmap` is now part of your toolbox by getting a debug shell into a different image:

```console
$ docker debug hello-world
...
docker > nmap --version

Nmap version 7.93 ( https://nmap.org )
Platform: x86_64-unknown-linux-gnu
Compiled with: liblua-5.3.6 openssl-3.0.11 libssh2-1.11.0 nmap-libz-1.2.12 libpcre-8.45 libpcap-1.10.4 nmap-libdnet-1.12 ipv6
Compiled without:
Available nsock engines: epoll poll select

docker > exit
```

`nmap` is still there.

### [Understanding the default startup command of a container (entry points)](#understanding-the-default-startup-command-of-a-container-entry-points)

Docker Debug comes with a builtin tool, `entrypoint`. Enter the `hello-world` image and confirm the entrypoint is `/hello`:

```console
$ docker debug hello-world
...
docker > entrypoint --print
/hello
```

The `entrypoint` command evaluates the `ENTRYPOINT` and `CMD` statement of the underlying image and lets you print, lint, or run the resulting entrypoint. However, it can be difficult to understand all the corner cases from [Understand how CMD and ENTRYPOINT interact](/reference/dockerfile/#understand-how-cmd-and-entrypoint-interact). In these situations, `entrypoint` can help.

Use `entrypoint` to investigate what actually happens when you run a container from the Nginx image:

```console
$ docker debug nginx
...
docker > entrypoint
Understand how ENTRYPOINT/CMD work and if they are set correctly.
From CMD in Dockerfile:
 ['nginx', '-g', 'daemon off;']

From ENTRYPOINT in Dockerfile:
 ['/docker-entrypoint.sh']

By default, any container from this image will be started with following   command:

/docker-entrypoint.sh nginx -g daemon off;

path: /docker-entrypoint.sh
args: nginx -g daemon off;
cwd:
PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Lint results:
 PASS: '/docker-entrypoint.sh' found
 PASS: no mixing of shell and exec form
 PASS: no double use of shell form

Docs:
- https://docs.docker.com/reference/dockerfile/#cmd
- https://docs.docker.com/reference/dockerfile/#entrypoint
- https://docs.docker.com/reference/dockerfile/#understand-how-cmd-and-entrypoint-interact
```

The output tells you that on startup of the nginx image, a script `/docker-entrypoint.sh` is executed with the arguments `nginx -g daemon off;`. You can test the entrypoint by using the `--run` option:

```console
$ docker debug nginx
...
docker > entrypoint --run
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Sourcing /docker-entrypoint.d/15-local-resolvers.envsh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
2024/01/19 17:34:39 [notice] 50#50: using the "epoll" event method
2024/01/19 17:34:39 [notice] 50#50: nginx/1.25.3
2024/01/19 17:34:39 [notice] 50#50: built by gcc 12.2.0 (Debian 12.2.0-14)
2024/01/19 17:34:39 [notice] 50#50: OS: Linux 5.15.133.1-microsoft-standard-WSL2
2024/01/19 17:34:39 [notice] 50#50: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2024/01/19 17:34:39 [notice] 50#50: start worker processes
2024/01/19 17:34:39 [notice] 50#50: start worker process 77
...
```

This starts nginx in your debug shell without having to actually run a container. You can shutdown nginx by pressing `Ctrl`+`C`.

### [Running commands directly (e.g., for scripting)](#running-commands-directly-eg-for-scripting)

Use the `--command` option to evaluate a command directly instead of starting an interactive session. For example, this is similar to `bash -c "arg1 arg2 ..."`. The following example runs the `cat` command in the nginx image without starting an interactive session.

```console
$ docker debug --command "cat /usr/share/nginx/html/index.html" nginx

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>
```

### [Remote debugging using the --host option](#remote-debugging-using-the---host-option)

The following examples shows how to use the `--host` option. The first example uses SSH to connect to a remote Docker instance at `example.org` as the `root` user, and get a shell into the `my-container` container.

```console
$ docker debug --host ssh://root@example.org my-container
```

The following example connects to a different local Docker Engine, and gets a shell into the `my-container` container.

```console
$ docker debug --host=unix:///some/path/docker.sock my-container
```

----
url: https://docs.docker.com/compose/support-and-feedback/feedback/
----

***

Table of contents

***

There are many ways you can provide feedback on Docker Compose.

### [Report bugs or problems on GitHub](#report-bugs-or-problems-on-github)

To report bugs or problems, visit [Docker Compose on GitHub](https://github.com/docker/compose/issues)

### [Feedback via Community Slack channels](#feedback-via-community-slack-channels)

You can also provide feedback through the `#docker-compose` [Docker Community Slack](https://dockr.ly/comm-slack) channel.

----
url: https://docs.docker.com/extensions/extensions-sdk/
----

# Overview of the Extensions SDK

***

***

The resources in this section help you create your own Docker extension.

The Docker CLI tool provides a set of commands to help you build and publish your extension, packaged as a specially formatted Docker image.

At the root of the image filesystem is a `metadata.json` file which describes the content of the extension. It's a fundamental element of a Docker extension.

An extension can contain a UI part and backend parts that run either on the host or in the Desktop virtual machine. For further information, see [Architecture](https://docs.docker.com/extensions/extensions-sdk/architecture/).

You distribute extensions through Docker Hub. However, you can develop them locally without the need to push the extension to Docker Hub. See [Extensions distribution](https://docs.docker.com/extensions/extensions-sdk/extensions/DISTRIBUTION/) for further details.

> Already built an extension?
>
> Let us know about your experience using the [feedback form](https://survey.alchemer.com/s3/7184948/Publishers-Feedback-Form).

### [The build and publish process](/extensions/extensions-sdk/process/)

[Understand the process for building and publishing an extension.](/extensions/extensions-sdk/process/)

### [Quickstart guide](/extensions/extensions-sdk/quickstart/)

[Follow the quickstart guide to create a basic Docker extension quickly.](/extensions/extensions-sdk/quickstart/)

### [View the design guidelines](/extensions/extensions-sdk/design/design-guidelines/)

[Ensure your extension aligns to Docker's design guidelines and principles.](/extensions/extensions-sdk/design/design-guidelines/)

### [Publish your extension](/extensions/extensions-sdk/extensions/)

[Understand how to publish your extension to the Marketplace.](/extensions/extensions-sdk/extensions/)

### [Interacting with Kubernetes](/extensions/extensions-sdk/guides/kubernetes/)

[Find information on how to interact indirectly with a Kubernetes cluster from your Docker extension.](/extensions/extensions-sdk/guides/kubernetes/)

### [Multi-arch extensions](/extensions/extensions-sdk/extensions/multi-arch/)

[Build your extension for multiple architectures.](/extensions/extensions-sdk/extensions/multi-arch/)

----
url: https://docs.docker.com/get-started/docker_cheatsheet.pdf
----

CLI Cheat Sheet  Build an Image from a Dockerfile  Build an Image from a Dockerfile without the cache  docker   build   -t   <image_name>   .   –no-cache  List local images  docker   images  Delete an Image  docker   rmi   <image_name>  Remove all unused images  docker   image   prune  Login into Docker  docker   login   -u   <username>  Publish an image to Docker Hub  docker   push   <username>/<image_name>  Search Hub for an image  docker   search   <image_name>  Pull an image from a Docker Hub  docker   pull   <image_name>  Create and run a container from an image, with a custom name:  docker   run   --name   <container_name>   <image_name>  Run a container with and publish a container’s port(s) to the host.  docker   run   -p   <host_port>:<container_port>   <image_name>  Run a container in the background  docker   run   -d   <image_name>  Start or stop an existing container:  docker   start|stop   <container_name>   (or   <container-id>)  Remove a stopped container:  docker   rm   <container_name>  Open a shell inside a running container:  docker   exec   -it   <container_name>   sh  Fetch and follow the logs of a container:  docker   logs   -f   <container_name>  To inspect a running container:  docker   inspect   <container_name>   (or   <container_id>)  To list currently running containers:  docker   ps  List all docker containers (running and stopped):  docker   ps   --all  View resource usage stats  docker   container   stats  GENERAL COMMANDS  Docker provides the ability to package and run an application in a loosely isolated environment called a container.  The isolation and security allows you to run many containers simultaneously on a given host. Containers are  lightweight and contain everything needed to run the application, so you do not need to rely on what is currently  installed on the host. You can easily share containers while you work, and be sure that everyone you share with gets  the same container that works in the same way.  IMAGES  Docker images are a lightweight, standalone, executable package  of software that includes everything needed to run an application:  code, runtime, system tools, system libraries and settings.  DOCKER HUB  Docker Hub is a service provided by Docker for finding and sharing  container images with your team. Learn more and find images  at https://hub.docker.com  CONTAINERS  A container is a runtime instance of a docker image. A container  will always run the same, regardless of the infrastructure.  Containers isolate software from its environment and ensure  that it works uniformly despite differences for instance between  development and staging.  Start the docker daemon  docker   -d  Get help with Docker. Can also use –help on all subcommands  docker   --help  Display system-wide information  docker   info  INSTALLATION  Docker Desktop is available for Mac, Linux and Windows  https://docs.docker.com/desktop  View example projects that use Docker  https://github.com/docker/awesome-compose  Check out our docs for information on using Docker  https://docs.docker.com  docker   build   -t   <image_name> .

----
url: https://docs.docker.com/engine/containers/run/
----

# Running containers

***

Table of contents

***

Docker runs processes in isolated containers. A container is a process which runs on a host. The host may be local or remote. When you execute `docker run`, the container process that runs is isolated in that it has its own file system, its own networking, and its own isolated process tree separate from the host.

This page details how to use the `docker run` command to run containers.

## [General form](#general-form)

A `docker run` command takes the following form:

```console
$ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...]
```

The `docker run` command must specify an [image reference](#image-references) to create the container from.

### [Image references](#image-references)

The image reference is the name and version of the image. You can use the image reference to create or run a container based on an image.

* `docker run IMAGE[:TAG][@DIGEST]`
* `docker create IMAGE[:TAG][@DIGEST]`

An image tag is the image version, which defaults to `latest` when omitted. Use the tag to run a container from specific version of an image. For example, to run version `24.04` of the `ubuntu` image: `docker run ubuntu:24.04`.

#### [Image digests](#image-digests)

Images using the v2 or later image format have a content-addressable identifier called a digest. As long as the input used to generate the image is unchanged, the digest value is predictable.

The following example runs a container from the `alpine` image with the `sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0` digest:

```console
$ docker run alpine@sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 date
```

### [Options](#options)

`[OPTIONS]` let you configure options for the container. For example, you can give the container a name (`--name`), or run it as a background process (`-d`). You can also set options to control things like resource constraints and networking.

### [Commands and arguments](#commands-and-arguments)

You can use the `[COMMAND]` and `[ARG...]` positional arguments to specify commands and arguments for the container to run when it starts up. For example, you can specify `sh` as the `[COMMAND]`, combined with the `-i` and `-t` flags, to start an interactive shell in the container (if the image you select has an `sh` executable on `PATH`).

```console
$ docker run -it IMAGE sh
```

> Note
>
> Depending on your Docker system configuration, you may be required to preface the `docker run` command with `sudo`. To avoid having to use `sudo` with the `docker` command, your system administrator can create a Unix group called `docker` and add users to it. For more information about this configuration, refer to the Docker installation documentation for your operating system.

## [Foreground and background](#foreground-and-background)

When you start a container, the container runs in the foreground by default. If you want to run the container in the background instead, you can use the `--detach` (or `-d`) flag. This starts the container without occupying your terminal window.

```console
$ docker run -d IMAGE
```

While the container runs in the background, you can interact with the container using other CLI commands. For example, `docker logs` lets you view the logs for the container, and `docker attach` brings it to the foreground.

```console
$ docker run -d nginx
0246aa4d1448a401cabd2ce8f242192b6e7af721527e48a810463366c7ff54f1
$ docker ps
CONTAINER ID   IMAGE     COMMAND                  CREATED         STATUS        PORTS     NAMES
0246aa4d1448   nginx     "/docker-entrypoint.…"   2 seconds ago   Up 1 second   80/tcp    pedantic_liskov
$ docker logs -n 5 0246aa4d1448
2023/11/06 15:58:23 [notice] 1#1: start worker process 33
2023/11/06 15:58:23 [notice] 1#1: start worker process 34
2023/11/06 15:58:23 [notice] 1#1: start worker process 35
2023/11/06 15:58:23 [notice] 1#1: start worker process 36
2023/11/06 15:58:23 [notice] 1#1: start worker process 37
$ docker attach 0246aa4d1448
^C
2023/11/06 15:58:40 [notice] 1#1: signal 2 (SIGINT) received, exiting
...
```

For more information about `docker run` flags related to foreground and background modes, see:

* [`docker run --detach`](https://docs.docker.com/reference/cli/docker/container/run/#detach): run container in background
* [`docker run --attach`](https://docs.docker.com/reference/cli/docker/container/run/#attach): attach to `stdin`, `stdout`, and `stderr`
* [`docker run --tty`](https://docs.docker.com/reference/cli/docker/container/run/#tty): allocate a pseudo-tty
* [`docker run --interactive`](https://docs.docker.com/reference/cli/docker/container/run/#interactive): keep `stdin` open even if not attached

For more information about re-attaching to a background container, see [`docker attach`](https://docs.docker.com/reference/cli/docker/container/attach/).

## [Container identification](#container-identification)

You can identify a container in three ways:

| Identifier type       | Example value                                                      |
| --------------------- | ------------------------------------------------------------------ |
| UUID long identifier  | `f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778` |
| UUID short identifier | `f78375b1c487`                                                     |
| Name                  | `evil_ptolemy`                                                     |

The UUID identifier is a random ID assigned to the container by the daemon.

The daemon generates a random string name for containers automatically. You can also define a custom name using [the `--name` flag](https://docs.docker.com/reference/cli/docker/container/run/#name). Defining a `name` can be a handy way to add meaning to a container. If you specify a `name`, you can use it when referring to the container in a user-defined network. This works for both background and foreground Docker containers.

A container identifier is not the same thing as an image reference. The image reference specifies which image to use when you run a container. You can't run `docker exec nginx:alpine sh` to open a shell in a container based on the `nginx:alpine` image, because `docker exec` expects a container identifier (name or ID), not an image.

While the image used by a container is not an identifier for the container, you find out the IDs of containers using an image by using the `--filter` flag. For example, the following `docker ps` command gets the IDs of all running containers based on the `nginx:alpine` image:

```console
$ docker ps -q --filter ancestor=nginx:alpine
```

For more information about using filters, see [Filtering](https://docs.docker.com/config/filter/).

## [Container networking](#container-networking)

Containers have networking enabled by default, and they can make outgoing connections. If you're running multiple containers that need to communicate with each other, you can create a custom network and attach the containers to the network.

When multiple containers are attached to the same custom network, they can communicate with each other using the container names as a DNS hostname. The following example creates a custom network named `my-net`, and runs two containers that attach to the network.

```console
$ docker network create my-net
$ docker run -d --name web --network my-net nginx:alpine
$ docker run --rm -it --network my-net busybox
/ # ping web
PING web (172.18.0.2): 56 data bytes
64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.326 ms
64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.257 ms
64 bytes from 172.18.0.2: seq=2 ttl=64 time=0.281 ms
^C
--- web ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 0.257/0.288/0.326 ms
```

For more information about container networking, see [Networking overview](https://docs.docker.com/network/)

## [Filesystem mounts](#filesystem-mounts)

By default, the data in a container is stored in an ephemeral, writable container layer. Removing the container also removes its data. If you want to use persistent data with containers, you can use filesystem mounts to store the data persistently on the host system. Filesystem mounts can also let you share data between containers and the host.

Docker supports two main categories of mounts:

* Volume mounts
* Bind mounts

Volume mounts are great for persistently storing data for containers, and for sharing data between containers. Bind mounts, on the other hand, are for sharing data between a container and the host.

You can add a filesystem mount to a container using the `--mount` flag for the `docker run` command.

The following sections show basic examples of how to create volumes and bind mounts. For more in-depth examples and descriptions, refer to the section of the [storage section](https://docs.docker.com/storage/) in the documentation.

### [Volume mounts](#volume-mounts)

To create a volume mount:

```console
$ docker run --mount source=VOLUME_NAME,target=[PATH] [IMAGE] [COMMAND...]
```

The `--mount` flag takes two parameters in this case: `source` and `target`. The value for the `source` parameter is the name of the volume. The value of `target` is the mount location of the volume inside the container. Once you've created the volume, any data you write to the volume is persisted, even if you stop or remove the container:

```console
$ docker run --rm --mount source=my_volume,target=/foo busybox \
  echo "hello, volume!" > /foo/hello.txt
$ docker run --mount source=my_volume,target=/bar busybox
  cat /bar/hello.txt
hello, volume!
```

The `target` must always be an absolute path, such as `/src/docs`. An absolute path starts with a `/` (forward slash). Volume names must start with an alphanumeric character, followed by `a-z0-9`, `_` (underscore), `.` (period) or `-` (hyphen).

### [Bind mounts](#bind-mounts)

To create a bind mount:

```console
$ docker run -it --mount type=bind,source=[PATH],target=[PATH] busybox
```

In this case, the `--mount` flag takes three parameters. A type (`bind`), and two paths. The `source` path is the location on the host that you want to bind mount into the container. The `target` path is the mount destination inside the container.

By default, bind mounts require the source path to exist on the daemon host. If the source path doesn't exist, an error is returned. To create the source path on the daemon host if it doesn't exist, use the `bind-create-src` option:

```console
$ docker run -it --mount type=bind,source=[PATH],target=[PATH],bind-create-src busybox
```

Bind mounts are read-write by default, meaning that you can both read and write files to and from the mounted location from the container. Changes that you make, such as adding or editing files, are reflected on the host filesystem:

```console
$ docker run -it --mount type=bind,source=.,target=/foo busybox
/ # echo "hello from container" > /foo/hello.txt
/ # exit
$ cat hello.txt
hello from container
```

## [Exit status](#exit-status)

The exit code from `docker run` gives information about why the container failed to run or why it exited. The following sections describe the meanings of different container exit codes values.

### [125](#125)

Exit code `125` indicates that the error is with Docker daemon itself.

```console
$ docker run --foo busybox; echo $?

flag provided but not defined: --foo
See 'docker run --help'.
125
```

### [126](#126)

Exit code `126` indicates that the specified contained command can't be invoked. The container command in the following example is: `/etc`.

```console
$ docker run busybox /etc; echo $?

docker: Error response from daemon: Container command '/etc' could not be invoked.
126
```

### [127](#127)

Exit code `127` indicates that the contained command can't be found.

```console
$ docker run busybox foo; echo $?

docker: Error response from daemon: Container command 'foo' not found or does not exist.
127
```

### [Other exit codes](#other-exit-codes)

Any exit code other than `125`, `126`, and `127` represent the exit code of the provided container command.

```console
$ docker run busybox /bin/sh -c 'exit 3'
$ echo $?
3
```

## [Runtime constraints on resources](#runtime-constraints-on-resources)

The operator can also adjust the performance parameters of the container:

| Option                     | Description                                                                                                                                                                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-m`, `--memory=""`        | Memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 6M.                                                                                                                                                        |
| `--memory-swap=""`         | Total memory limit (memory + swap, format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`.                                                                                                                                                  |
| `--memory-reservation=""`  | Memory soft limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`.                                                                                                                                                                  |
| `-c`, `--cpu-shares=0`     | CPU shares (relative weight)                                                                                                                                                                                                                                                             |
| `--cpus=0.000`             | Number of CPUs. Number is a fractional number. 0.000 means no limit.                                                                                                                                                                                                                     |
| `--cpu-period=0`           | Limit the CPU CFS (Completely Fair Scheduler) period                                                                                                                                                                                                                                     |
| `--cpuset-cpus=""`         | CPUs in which to allow execution (0-3, 0,1)                                                                                                                                                                                                                                              |
| `--cpuset-mems=""`         | Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                                                              |
| `--cpu-quota=0`            | Limit the CPU CFS (Completely Fair Scheduler) quota                                                                                                                                                                                                                                      |
| `--cpu-rt-period=0`        | Limit the CPU real-time period. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits.                                                                                                                                             |
| `--cpu-rt-runtime=0`       | Limit the CPU real-time runtime. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits.                                                                                                                                            |
| `--blkio-weight=0`         | Block IO weight (relative weight) accepts a weight value between 10 and 1000.                                                                                                                                                                                                            |
| `--blkio-weight-device=""` | Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`)                                                                                                                                                                                                                   |
| `--device-read-bps=""`     | Limit read rate from a device (format: `<device-path>:<number>[<unit>]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`.                                                                                                                                          |
| `--device-write-bps=""`    | Limit write rate to a device (format: `<device-path>:<number>[<unit>]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`.                                                                                                                                           |
| `--device-read-iops=""`    | Limit read rate (IO per second) from a device (format: `<device-path>:<number>`). Number is a positive integer.                                                                                                                                                                          |
| `--device-write-iops=""`   | Limit write rate (IO per second) to a device (format: `<device-path>:<number>`). Number is a positive integer.                                                                                                                                                                           |
| `--oom-kill-disable=false` | Whether to disable OOM Killer for the container or not.                                                                                                                                                                                                                                  |
| `--oom-score-adj=0`        | Tune container's OOM preferences (-1000 to 1000)                                                                                                                                                                                                                                         |
| `--memory-swappiness=""`   | Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                                                                                     |
| `--shm-size=""`            | Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. |

### [User memory constraints](#user-memory-constraints)

We have four ways to set user memory usage:

| Option                                      | Result                                                                                                                                                                                  |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **memory=inf, memory-swap=inf** (default)   | There is no memory limit for the container. The container can use as much memory as needed.                                                                                             |
| **memory=L\<inf, memory-swap=inf**          | (specify memory and set memory-swap as `-1`) The container is not allowed to use more than L bytes of memory, but can use as much swap as is needed (if the host supports swap memory). |
| **memory=L\<inf, memory-swap=2\*L**         | (specify memory without memory-swap) The container is not allowed to use more than L bytes of memory, swap *plus* memory usage is double of that.                                       |
| **memory=L\<inf, memory-swap=S\<inf, L<=S** | (specify both memory and memory-swap) The container is not allowed to use more than L bytes of memory, swap *plus* memory usage is limited by S.                                        |

Examples:

```console
$ docker run -it ubuntu:24.04 /bin/bash
```

We set nothing about memory, this means the processes in the container can use as much memory and swap memory as they need.

```console
$ docker run -it -m 300M --memory-swap -1 ubuntu:24.04 /bin/bash
```

We set memory limit and disabled swap memory limit, this means the processes in the container can use 300M memory and as much swap memory as they need (if the host supports swap memory).

```console
$ docker run -it -m 300M ubuntu:24.04 /bin/bash
```

We set memory limit only, this means the processes in the container can use 300M memory and 300M swap memory, by default, the total virtual memory size (`--memory-swap`) will be set as double of memory, in this case, memory + swap would be 2\*300M, so processes can use 300M swap memory as well.

```console
$ docker run -it -m 300M --memory-swap 1G ubuntu:24.04 /bin/bash
```

We set both memory and swap memory, so the processes in the container can use 300M memory and 700M swap memory.

Memory reservation is a kind of memory soft limit that allows for greater sharing of memory. Under normal circumstances, containers can use as much of the memory as needed and are constrained only by the hard limits set with the `-m`/`--memory` option. When memory reservation is set, Docker detects memory contention or low memory and forces containers to restrict their consumption to a reservation limit.

Always set the memory reservation value below the hard limit, otherwise the hard limit takes precedence. A reservation of 0 is the same as setting no reservation. By default (without reservation set), memory reservation is the same as the hard memory limit.

Memory reservation is a soft-limit feature and does not guarantee the limit won't be exceeded. Instead, the feature attempts to ensure that, when memory is heavily contended for, memory is allocated based on the reservation hints/setup.

The following example limits the memory (`-m`) to 500M and sets the memory reservation to 200M.

```console
$ docker run -it -m 500M --memory-reservation 200M ubuntu:24.04 /bin/bash
```

Under this configuration, when the container consumes memory more than 200M and less than 500M, the next system memory reclaim attempts to shrink container memory below 200M.

The following example set memory reservation to 1G without a hard memory limit.

```console
$ docker run -it --memory-reservation 1G ubuntu:24.04 /bin/bash
```

The container can use as much memory as it needs. The memory reservation setting ensures the container doesn't consume too much memory for long time, because every memory reclaim shrinks the container's consumption to the reservation.

By default, kernel kills processes in a container if an out-of-memory (OOM) error occurs. To change this behaviour, use the `--oom-kill-disable` option. Only disable the OOM killer on containers where you have also set the `-m/--memory` option. If the `-m` flag is not set, this can result in the host running out of memory and require killing the host's system processes to free memory.

The following example limits the memory to 100M and disables the OOM killer for this container:

```console
$ docker run -it -m 100M --oom-kill-disable ubuntu:24.04 /bin/bash
```

The following example, illustrates a dangerous way to use the flag:

```console
$ docker run -it --oom-kill-disable ubuntu:24.04 /bin/bash
```

The container has unlimited memory which can cause the host to run out memory and require killing system processes to free memory. The `--oom-score-adj` parameter can be changed to select the priority of which containers will be killed when the system is out of memory, with negative scores making them less likely to be killed, and positive scores more likely.

### [Swappiness constraint](#swappiness-constraint)

By default, a container's kernel can swap out a percentage of anonymous pages. To set this percentage for a container, specify a `--memory-swappiness` value between 0 and 100. A value of 0 turns off anonymous page swapping. A value of 100 sets all anonymous pages as swappable. By default, if you are not using `--memory-swappiness`, memory swappiness value will be inherited from the parent.

For example, you can set:

```console
$ docker run -it --memory-swappiness=0 ubuntu:24.04 /bin/bash
```

Setting the `--memory-swappiness` option is helpful when you want to retain the container's working set and to avoid swapping performance penalties.

### [CPU share constraint](#cpu-share-constraint)

By default, all containers get the same proportion of CPU cycles. This proportion can be modified by changing the container's CPU share weighting relative to the weighting of all other running containers.

To modify the proportion from the default of 1024, use the `-c` or `--cpu-shares` flag to set the weighting to 2 or higher. If 0 is set, the system will ignore the value and use the default of 1024.

The proportion will only apply when CPU-intensive processes are running. When tasks in one container are idle, other containers can use the left-over CPU time. The actual amount of CPU time will vary depending on the number of containers running on the system.

For example, consider three containers, one has a cpu-share of 1024 and two others have a cpu-share setting of 512. When processes in all three containers attempt to use 100% of CPU, the first container would receive 50% of the total CPU time. If you add a fourth container with a cpu-share of 1024, the first container only gets 33% of the CPU. The remaining containers receive 16.5%, 16.5% and 33% of the CPU.

On a multi-core system, the shares of CPU time are distributed over all CPU cores. Even if a container is limited to less than 100% of CPU time, it can use 100% of each individual CPU core.

For example, consider a system with more than three cores. If you start one container `{C0}` with `-c=512` running one process, and another container `{C1}` with `-c=1024` running two processes, this can result in the following division of CPU shares:

```
PID    container	CPU	CPU share
100    {C0}		0	100% of CPU0
101    {C1}		1	100% of CPU1
102    {C1}		2	100% of CPU2
```

### [CPU period constraint](#cpu-period-constraint)

The default CPU CFS (Completely Fair Scheduler) period is 100ms. We can use `--cpu-period` to set the period of CPUs to limit the container's CPU usage. And usually `--cpu-period` should work with `--cpu-quota`.

Examples:

```console
$ docker run -it --cpu-period=50000 --cpu-quota=25000 ubuntu:24.04 /bin/bash
```

If there is 1 CPU, this means the container can get 50% CPU worth of run-time every 50ms.

In addition to use `--cpu-period` and `--cpu-quota` for setting CPU period constraints, it is possible to specify `--cpus` with a float number to achieve the same purpose. For example, if there is 1 CPU, then `--cpus=0.5` will achieve the same result as setting `--cpu-period=50000` and `--cpu-quota=25000` (50% CPU).

The default value for `--cpus` is `0.000`, which means there is no limit.

For more information, see the [CFS documentation on bandwidth limiting](https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt).

### [Cpuset constraint](#cpuset-constraint)

We can set cpus in which to allow execution for containers.

Examples:

```console
$ docker run -it --cpuset-cpus="1,3" ubuntu:24.04 /bin/bash
```

This means processes in container can be executed on cpu 1 and cpu 3.

```console
$ docker run -it --cpuset-cpus="0-2" ubuntu:24.04 /bin/bash
```

This means processes in container can be executed on cpu 0, cpu 1 and cpu 2.

We can set mems in which to allow execution for containers. Only effective on NUMA systems.

Examples:

```console
$ docker run -it --cpuset-mems="1,3" ubuntu:24.04 /bin/bash
```

This example restricts the processes in the container to only use memory from memory nodes 1 and 3.

```console
$ docker run -it --cpuset-mems="0-2" ubuntu:24.04 /bin/bash
```

This example restricts the processes in the container to only use memory from memory nodes 0, 1 and 2.

### [CPU quota constraint](#cpu-quota-constraint)

The `--cpu-quota` flag limits the container's CPU usage. The default 0 value allows the container to take 100% of a CPU resource (1 CPU). The CFS (Completely Fair Scheduler) handles resource allocation for executing processes and is default Linux Scheduler used by the kernel. Set this value to 50000 to limit the container to 50% of a CPU resource. For multiple CPUs, adjust the `--cpu-quota` as necessary. For more information, see the [CFS documentation on bandwidth limiting](https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt).

### [Block IO bandwidth (Blkio) constraint](#block-io-bandwidth-blkio-constraint)

By default, all containers get the same proportion of block IO bandwidth (blkio). This proportion is 500. To modify this proportion, change the container's blkio weight relative to the weighting of all other running containers using the `--blkio-weight` flag.

> Note
>
> The blkio weight setting is only available for direct IO. Buffered IO is not currently supported.

The `--blkio-weight` flag can set the weighting to a value between 10 to 1000. For example, the commands below create two containers with different blkio weight:

```console
$ docker run -it --name c1 --blkio-weight 300 ubuntu:24.04 /bin/bash
$ docker run -it --name c2 --blkio-weight 600 ubuntu:24.04 /bin/bash
```

If you do block IO in the two containers at the same time, by, for example:

```console
$ time dd if=/mnt/zerofile of=test.out bs=1M count=1024 oflag=direct
```

You'll find that the proportion of time is the same as the proportion of blkio weights of the two containers.

The `--blkio-weight-device="DEVICE_NAME:WEIGHT"` flag sets a specific device weight. The `DEVICE_NAME:WEIGHT` is a string containing a colon-separated device name and weight. For example, to set `/dev/sda` device weight to `200`:

```console
$ docker run -it \
    --blkio-weight-device "/dev/sda:200" \
    ubuntu
```

If you specify both the `--blkio-weight` and `--blkio-weight-device`, Docker uses the `--blkio-weight` as the default weight and uses `--blkio-weight-device` to override this default with a new value on a specific device. The following example uses a default weight of `300` and overrides this default on `/dev/sda` setting that weight to `200`:

```console
$ docker run -it \
    --blkio-weight 300 \
    --blkio-weight-device "/dev/sda:200" \
    ubuntu
```

The `--device-read-bps` flag limits the read rate (bytes per second) from a device. For example, this command creates a container and limits the read rate to `1mb` per second from `/dev/sda`:

```console
$ docker run -it --device-read-bps /dev/sda:1mb ubuntu
```

The `--device-write-bps` flag limits the write rate (bytes per second) to a device. For example, this command creates a container and limits the write rate to `1mb` per second for `/dev/sda`:

```console
$ docker run -it --device-write-bps /dev/sda:1mb ubuntu
```

Both flags take limits in the `<device-path>:<limit>[unit]` format. Both read and write rates must be a positive integer. You can specify the rate in `kb` (kilobytes), `mb` (megabytes), or `gb` (gigabytes).

The `--device-read-iops` flag limits read rate (IO per second) from a device. For example, this command creates a container and limits the read rate to `1000` IO per second from `/dev/sda`:

```console
$ docker run -it --device-read-iops /dev/sda:1000 ubuntu
```

The `--device-write-iops` flag limits write rate (IO per second) to a device. For example, this command creates a container and limits the write rate to `1000` IO per second to `/dev/sda`:

```console
$ docker run -it --device-write-iops /dev/sda:1000 ubuntu
```

Both flags take limits in the `<device-path>:<limit>` format. Both read and write rates must be a positive integer.

## [Additional groups](#additional-groups)

```console
--group-add: Add additional groups to run as
```

By default, the docker container process runs with the supplementary groups looked up for the specified user. If one wants to add more to that list of groups, then one can use this flag:

```console
$ docker run --rm --group-add audio --group-add nogroup --group-add 777 busybox id

uid=0(root) gid=0(root) groups=10(wheel),29(audio),99(nogroup),777
```

## [Runtime privilege and Linux capabilities](#runtime-privilege-and-linux-capabilities)

| Option         | Description                                                                     |
| -------------- | ------------------------------------------------------------------------------- |
| `--cap-add`    | Add Linux capabilities                                                          |
| `--cap-drop`   | Drop Linux capabilities                                                         |
| `--privileged` | Give extended privileges to this container                                      |
| `--device=[]`  | Allows you to run devices inside the container without the `--privileged` flag. |

By default, Docker containers are "unprivileged" and cannot, for example, run a Docker daemon inside a Docker container. This is because by default a container is not allowed to access any devices, but a "privileged" container is given access to all devices (see the documentation on [cgroups devices](https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt)).

The `--privileged` flag gives all capabilities to the container. When the operator executes `docker run --privileged`, Docker enables access to all devices on the host, and reconfigures AppArmor or SELinux to allow the container nearly all the same access to the host as processes running outside containers on the host. Use this flag with caution. For more information about the `--privileged` flag, see the [`docker run` reference](https://docs.docker.com/reference/cli/docker/container/run/#privileged).

If you want to limit access to a specific device or devices you can use the `--device` flag. It allows you to specify one or more devices that will be accessible within the container.

```console
$ docker run --device=/dev/snd:/dev/snd ...
```

By default, the container will be able to `read`, `write`, and `mknod` these devices. This can be overridden using a third `:rwm` set of options to each `--device` flag:

```console
$ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk  /dev/xvdc

Command (m for help): q
$ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk  /dev/xvdc
You will not be able to write the partition table.

Command (m for help): q

$ docker run --device=/dev/sda:/dev/xvdc:w --rm -it ubuntu fdisk  /dev/xvdc
    crash....

$ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk  /dev/xvdc
fdisk: unable to open /dev/xvdc: Operation not permitted
```

In addition to `--privileged`, the operator can have fine grain control over the capabilities using `--cap-add` and `--cap-drop`. By default, Docker has a default list of capabilities that are kept. The following table lists the Linux capability options which are allowed by default and can be dropped.

| Capability Key     | Capability Description                                                                                                        |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| AUDIT\_WRITE       | Write records to kernel auditing log.                                                                                         |
| CHOWN              | Make arbitrary changes to file UIDs and GIDs (see chown(2)).                                                                  |
| DAC\_OVERRIDE      | Bypass file read, write, and execute permission checks.                                                                       |
| FOWNER             | Bypass permission checks on operations that normally require the file system UID of the process to match the UID of the file. |
| FSETID             | Don't clear set-user-ID and set-group-ID permission bits when a file is modified.                                             |
| KILL               | Bypass permission checks for sending signals.                                                                                 |
| MKNOD              | Create special files using mknod(2).                                                                                          |
| NET\_BIND\_SERVICE | Bind a socket to internet domain privileged ports (port numbers less than 1024).                                              |
| NET\_RAW           | Use RAW and PACKET sockets.                                                                                                   |
| SETFCAP            | Set file capabilities.                                                                                                        |
| SETGID             | Make arbitrary manipulations of process GIDs and supplementary GID list.                                                      |
| SETPCAP            | Modify process capabilities.                                                                                                  |
| SETUID             | Make arbitrary manipulations of process UIDs.                                                                                 |
| SYS\_CHROOT        | Use chroot(2), change root directory.                                                                                         |

The next table shows the capabilities which are not granted by default and may be added.

| Capability Key      | Capability Description                                                                                                      |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| AUDIT\_CONTROL      | Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules.             |
| AUDIT\_READ         | Allow reading the audit log via multicast netlink socket.                                                                   |
| BLOCK\_SUSPEND      | Allow preventing system suspends.                                                                                           |
| BPF                 | Allow creating BPF maps, loading BPF Type Format (BTF) data, retrieve JITed code of BPF programs, and more.                 |
| CHECKPOINT\_RESTORE | Allow checkpoint/restore related operations. Introduced in kernel 5.9.                                                      |
| DAC\_READ\_SEARCH   | Bypass file read permission checks and directory read and execute permission checks.                                        |
| IPC\_LOCK           | Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)).                                                                    |
| IPC\_OWNER          | Bypass permission checks for operations on System V IPC objects.                                                            |
| LEASE               | Establish leases on arbitrary files (see fcntl(2)).                                                                         |
| LINUX\_IMMUTABLE    | Set the FS\_APPEND\_FL and FS\_IMMUTABLE\_FL i-node flags.                                                                  |
| MAC\_ADMIN          | Allow MAC configuration or state changes. Implemented for the Smack LSM.                                                    |
| MAC\_OVERRIDE       | Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM).                             |
| NET\_ADMIN          | Perform various network-related operations.                                                                                 |
| NET\_BROADCAST      | Make socket broadcasts, and listen to multicasts.                                                                           |
| PERFMON             | Allow system performance and observability privileged operations using perf\_events, i915\_perf and other kernel subsystems |
| SYS\_ADMIN          | Perform a range of system administration operations.                                                                        |
| SYS\_BOOT           | Use reboot(2) and kexec\_load(2), reboot and load a new kernel for later execution.                                         |
| SYS\_MODULE         | Load and unload kernel modules.                                                                                             |
| SYS\_NICE           | Raise process nice value (nice(2), setpriority(2)) and change the nice value for arbitrary processes.                       |
| SYS\_PACCT          | Use acct(2), switch process accounting on or off.                                                                           |
| SYS\_PTRACE         | Trace arbitrary processes using ptrace(2).                                                                                  |
| SYS\_RAWIO          | Perform I/O port operations (iopl(2) and ioperm(2)).                                                                        |
| SYS\_RESOURCE       | Override resource Limits.                                                                                                   |
| SYS\_TIME           | Set system clock (settimeofday(2), stime(2), adjtimex(2)); set real-time (hardware) clock.                                  |
| SYS\_TTY\_CONFIG    | Use vhangup(2); employ various privileged ioctl(2) operations on virtual terminals.                                         |
| SYSLOG              | Perform privileged syslog(2) operations.                                                                                    |
| WAKE\_ALARM         | Trigger something that will wake up the system.                                                                             |

Further reference information is available on the [capabilities(7) - Linux man page](https://man7.org/linux/man-pages/man7/capabilities.7.html), and in the [Linux kernel source code](https://github.com/torvalds/linux/blob/124ea650d3072b005457faed69909221c2905a1f/include/uapi/linux/capability.h).

Both flags support the value `ALL`, so to allow a container to use all capabilities except for `MKNOD`:

```console
$ docker run --cap-add=ALL --cap-drop=MKNOD ...
```

The `--cap-add` and `--cap-drop` flags accept capabilities to be specified with a `CAP_` prefix. The following examples are therefore equivalent:

```console
$ docker run --cap-add=SYS_ADMIN ...
$ docker run --cap-add=CAP_SYS_ADMIN ...
```

For interacting with the network stack, instead of using `--privileged` they should use `--cap-add=NET_ADMIN` to modify the network interfaces.

```console
$ docker run -it --rm  ubuntu:24.04 ip link add dummy0 type dummy

RTNETLINK answers: Operation not permitted

$ docker run -it --rm --cap-add=NET_ADMIN ubuntu:24.04 ip link add dummy0 type dummy
```

To mount a FUSE based filesystem, you need to combine both `--cap-add` and `--device`:

```console
$ docker run --rm -it --cap-add SYS_ADMIN sshfs sshfs sven@10.10.10.20:/home/sven /mnt

fuse: failed to open /dev/fuse: Operation not permitted

$ docker run --rm -it --device /dev/fuse sshfs sshfs sven@10.10.10.20:/home/sven /mnt

fusermount: mount failed: Operation not permitted

$ docker run --rm -it --cap-add SYS_ADMIN --device /dev/fuse sshfs

# sshfs sven@10.10.10.20:/home/sven /mnt
The authenticity of host '10.10.10.20 (10.10.10.20)' can't be established.
ECDSA key fingerprint is 25:34:85:75:25:b0:17:46:05:19:04:93:b5:dd:5f:c6.
Are you sure you want to continue connecting (yes/no)? yes
sven@10.10.10.20's password:

root@30aa0cfaf1b5:/# ls -la /mnt/src/docker

total 1516
drwxrwxr-x 1 1000 1000   4096 Dec  4 06:08 .
drwxrwxr-x 1 1000 1000   4096 Dec  4 11:46 ..
-rw-rw-r-- 1 1000 1000     16 Oct  8 00:09 .dockerignore
-rwxrwxr-x 1 1000 1000    464 Oct  8 00:09 .drone.yml
drwxrwxr-x 1 1000 1000   4096 Dec  4 06:11 .git
-rw-rw-r-- 1 1000 1000    461 Dec  4 06:08 .gitignore
....
```

The default seccomp profile will adjust to the selected capabilities, in order to allow use of facilities allowed by the capabilities, so you should not have to adjust this.

## [Overriding image defaults](#overriding-image-defaults)

When you build an image from a [Dockerfile](https://docs.docker.com/reference/dockerfile/), or when committing it, you can set a number of default parameters that take effect when the image starts up as a container. When you run an image, you can override those defaults using flags for the `docker run` command.

* [Default entrypoint](#default-entrypoint)
* [Default command and options](#default-command-and-options)
* [Expose ports](#exposed-ports)
* [Environment variables](#environment-variables)
* [Healthcheck](#healthchecks)
* [User](#user)
* [Working directory](#working-directory)

### [Default command and options](#default-command-and-options)

The command syntax for `docker run` supports optionally specifying commands and arguments to the container's entrypoint, represented as `[COMMAND]` and `[ARG...]` in the following synopsis example:

```console
$ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...]
```

This command is optional because whoever created the `IMAGE` may have already provided a default `COMMAND`, using the Dockerfile `CMD` instruction. When you run a container, you can override that `CMD` instruction just by specifying a new `COMMAND`.

If the image also specifies an `ENTRYPOINT` then the `CMD` or `COMMAND` get appended as arguments to the `ENTRYPOINT`.

### [Default entrypoint](#default-entrypoint)

```text
--entrypoint="": Overwrite the default entrypoint set by the image
```

The entrypoint refers to the default executable that's invoked when you run a container. A container's entrypoint is defined using the Dockerfile `ENTRYPOINT` instruction. It's similar to specifying a default command because it specifies, but the difference is that you need to pass an explicit flag to override the entrypoint, whereas you can override default commands with positional arguments. The defines a container's default behavior, with the idea that when you set an entrypoint you can run the container *as if it were that binary*, complete with default options, and you can pass in more options as commands. But there are cases where you may want to run something else inside the container. This is when overriding the default entrypoint at runtime comes in handy, using the `--entrypoint` flag for the `docker run` command.

The `--entrypoint` flag expects a string value, representing the name or path of the binary that you want to invoke when the container starts. The following example shows you how to run a Bash shell in a container that has been set up to automatically run some other binary (like `/usr/bin/redis-server`):

```console
$ docker run -it --entrypoint /bin/bash example/redis
```

The following examples show how to pass additional parameters to the custom entrypoint, using the positional command arguments:

```console
$ docker run -it --entrypoint /bin/bash example/redis -c ls -l
$ docker run -it --entrypoint /usr/bin/redis-cli example/redis --help
```

You can reset a containers entrypoint by passing an empty string, for example:

```console
$ docker run -it --entrypoint="" mysql bash
```

> Note
>
> Passing `--entrypoint` clears out any default command set on the image. That is, any `CMD` instruction in the Dockerfile used to build it.

### [Exposed ports](#exposed-ports)

By default, when you run a container, none of the container's ports are exposed to the host. This means you won't be able to access any ports that the container might be listening on. To make a container's ports accessible from the host, you need to publish the ports.

You can start the container with the `-P` or `-p` flags to expose its ports:

* The `-P` (or `--publish-all`) flag publishes all the exposed ports to the host. Docker binds each exposed port to a random port on the host.

  The `-P` flag only publishes port numbers that are explicitly flagged as exposed, either using the Dockerfile `EXPOSE` instruction or the `--expose` flag for the `docker run` command.

* The `-p` (or `--publish`) flag lets you explicitly map a single port or range of ports in the container to the host.

The port number inside the container (where the service listens) doesn't need to match the port number published on the outside of the container (where clients connect). For example, inside the container an HTTP service might be listening on port 80. At runtime, the port might be bound to 42800 on the host. To find the mapping between the host ports and the exposed ports, use the `docker port` command.

### [Environment variables](#environment-variables)

Docker automatically sets some environment variables when creating a Linux container. Docker doesn't set any environment variables when creating a Windows container.

The following environment variables are set for Linux containers:

| Variable   | Value                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| `HOME`     | Set based on the value of `USER`                                                                     |
| `HOSTNAME` | The hostname associated with the container                                                           |
| `PATH`     | Includes popular directories, such as `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` |
| `TERM`     | `xterm` if the container is allocated a pseudo-TTY                                                   |

Additionally, you can set any environment variable in the container by using one or more `-e` flags. You can even override the variables mentioned above, or variables defined using a Dockerfile `ENV` instruction when building the image.

If you name an environment variable without specifying a value, the current value of the named variable on the host is propagated into the container's environment:

```console
$ export today=Wednesday
$ docker run -e "deep=purple" -e today --rm alpine env

PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=d2219b854598
deep=purple
today=Wednesday
HOME=/root
```

```powershell
PS C:\> docker run --rm -e "foo=bar" microsoft/nanoserver cmd /s /c set
ALLUSERSPROFILE=C:\ProgramData
APPDATA=C:\Users\ContainerAdministrator\AppData\Roaming
CommonProgramFiles=C:\Program Files\Common Files
CommonProgramFiles(x86)=C:\Program Files (x86)\Common Files
CommonProgramW6432=C:\Program Files\Common Files
COMPUTERNAME=C2FAEFCC8253
ComSpec=C:\Windows\system32\cmd.exe
foo=bar
LOCALAPPDATA=C:\Users\ContainerAdministrator\AppData\Local
NUMBER_OF_PROCESSORS=8
OS=Windows_NT
Path=C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0\;C:\Users\ContainerAdministrator\AppData\Local\Microsoft\WindowsApps
PATHEXT=.COM;.EXE;.BAT;.CMD
PROCESSOR_ARCHITECTURE=AMD64
PROCESSOR_IDENTIFIER=Intel64 Family 6 Model 62 Stepping 4, GenuineIntel
PROCESSOR_LEVEL=6
PROCESSOR_REVISION=3e04
ProgramData=C:\ProgramData
ProgramFiles=C:\Program Files
ProgramFiles(x86)=C:\Program Files (x86)
ProgramW6432=C:\Program Files
PROMPT=$P$G
PUBLIC=C:\Users\Public
SystemDrive=C:
SystemRoot=C:\Windows
TEMP=C:\Users\ContainerAdministrator\AppData\Local\Temp
TMP=C:\Users\ContainerAdministrator\AppData\Local\Temp
USERDOMAIN=User Manager
USERNAME=ContainerAdministrator
USERPROFILE=C:\Users\ContainerAdministrator
windir=C:\Windows
```

### [Healthchecks](#healthchecks)

The following flags for the `docker run` command let you control the parameters for container healthchecks:

| Option                    | Description                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------- |
| `--health-cmd`            | Command to run to check health                                                        |
| `--health-interval`       | Time between running the check                                                        |
| `--health-retries`        | Consecutive failures needed to report unhealthy                                       |
| `--health-timeout`        | Maximum time to allow one check to run                                                |
| `--health-start-period`   | Start period for the container to initialize before starting health-retries countdown |
| `--health-start-interval` | Time between running the check during the start period                                |
| `--no-healthcheck`        | Disable any container-specified `HEALTHCHECK`                                         |

Example:

```console
$ docker run --name=test -d \
    --health-cmd='stat /etc/passwd || exit 1' \
    --health-interval=2s \
    busybox sleep 1d
$ sleep 2; docker inspect --format='{{.State.Health.Status}}' test
healthy
$ docker exec test rm /etc/passwd
$ sleep 2; docker inspect --format='{{json .State.Health}}' test
{
  "Status": "unhealthy",
  "FailingStreak": 3,
  "Log": [
    {
      "Start": "2016-05-25T17:22:04.635478668Z",
      "End": "2016-05-25T17:22:04.7272552Z",
      "ExitCode": 0,
      "Output": "  File: /etc/passwd\n  Size: 334       \tBlocks: 8          IO Block: 4096   regular file\nDevice: 32h/50d\tInode: 12          Links: 1\nAccess: (0664/-rw-rw-r--)  Uid: (    0/    root)   Gid: (    0/    root)\nAccess: 2015-12-05 22:05:32.000000000\nModify: 2015..."
    },
    {
      "Start": "2016-05-25T17:22:06.732900633Z",
      "End": "2016-05-25T17:22:06.822168935Z",
      "ExitCode": 0,
      "Output": "  File: /etc/passwd\n  Size: 334       \tBlocks: 8          IO Block: 4096   regular file\nDevice: 32h/50d\tInode: 12          Links: 1\nAccess: (0664/-rw-rw-r--)  Uid: (    0/    root)   Gid: (    0/    root)\nAccess: 2015-12-05 22:05:32.000000000\nModify: 2015..."
    },
    {
      "Start": "2016-05-25T17:22:08.823956535Z",
      "End": "2016-05-25T17:22:08.897359124Z",
      "ExitCode": 1,
      "Output": "stat: can't stat '/etc/passwd': No such file or directory\n"
    },
    {
      "Start": "2016-05-25T17:22:10.898802931Z",
      "End": "2016-05-25T17:22:10.969631866Z",
      "ExitCode": 1,
      "Output": "stat: can't stat '/etc/passwd': No such file or directory\n"
    },
    {
      "Start": "2016-05-25T17:22:12.971033523Z",
      "End": "2016-05-25T17:22:13.082015516Z",
      "ExitCode": 1,
      "Output": "stat: can't stat '/etc/passwd': No such file or directory\n"
    }
  ]
}
```

The health status is also displayed in the `docker ps` output.

### [User](#user)

The default user within a container is `root` (uid = 0). You can set a default user to run the first process with the Dockerfile `USER` instruction. When starting a container, you can override the `USER` instruction by passing the `-u` option.

```text
-u="", --user="": Sets the username or UID used and optionally the groupname or GID for the specified command.
```

The following examples are all valid:

```text
--user=[ user | user:group | uid | uid:gid | user:gid | uid:group ]
```

> Note
>
> If you pass a numeric user ID, it must be in the range of 0-2147483647. If you pass a username, the user must exist in the container.

### [Working directory](#working-directory)

The default working directory for running binaries within a container is the root directory (`/`). The default working directory of an image is set using the Dockerfile `WORKDIR` command. You can override the default working directory for an image using the `-w` (or `--workdir`) flag for the `docker run` command:

```text
$ docker run --rm -w /my/workdir alpine pwd
/my/workdir
```

If the directory doesn't already exist in the container, it's created.

----
url: https://docs.docker.com/build/ci/github-actions/export-docker/
----

# Export to Docker with GitHub Actions

***

***

You may want your build result to be available in the Docker client through `docker images` to be able to use it in another step of your workflow:

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
      
      - name: Build
        uses: docker/build-push-action@v7
        with:
          load: true
          tags: myimage:latest
      
      - name: Inspect
        run: |
          docker image inspect myimage:latest
```

----
url: https://docs.docker.com/guides/opencode-model-runner/
----

[Use OpenCode with Docker Model Runner](https://docs.docker.com/guides/opencode-model-runner/)

Connect OpenCode to Docker Model Runner with an OpenAI-compatible endpoint, choose coding models, and package `gpt-oss` with a larger context window.

AI

10 minutes

[« Back to all guides](/guides/)

# Use OpenCode with Docker Model Runner

***

Table of contents

***

This guide shows how to connect OpenCode to Docker Model Runner so OpenCode can use local models for coding tasks. You'll configure an `opencode.json` file, verify the API endpoint, and run OpenCode against models served from your local Docker environment.

> **Acknowledgment**
>
> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide.

Unlike the [OpenCode sandbox guide](https://docs.docker.com/ai/sandboxes/agents/opencode/), this guide focuses on using OpenCode as a local coding tool backed by Docker Model Runner rather than running OpenCode in a containerized sandbox.

In this guide, you'll learn how to:

* Pull coding models for OpenCode
* Configure OpenCode to use Docker Model Runner
* Verify the local API endpoint and start OpenCode
* Package `gpt-oss` with a larger context window when you need it

## [Prerequisites](#prerequisites)

Before you start, make sure you have:

* [Docker Desktop](https://docs.docker.com/get-started/get-docker/) or Docker Engine installed
* [Docker Model Runner enabled](https://docs.docker.com/ai/model-runner/get-started/#enable-docker-model-runner)
* [OpenCode installed](https://opencode.ai/docs)

If you use Docker Desktop, turn on TCP access in **Settings** > **AI**, or run:

```console
$ docker desktop enable model-runner --tcp 12434
```

## [Step 1: Pull a coding model](#step-1-pull-a-coding-model)

Pull one or more models before you configure OpenCode:

```console
$ docker model pull ai/qwen3-coder
$ docker model pull ai/devstral-small-2
```

These models are a good fit for coding workflows because they support large context windows.

## [Step 2: Create an OpenCode configuration](#step-2-create-an-opencode-configuration)

OpenCode reads configuration from either of these locations:

* `~/.config/opencode/opencode.json` for a global setup
* `opencode.json` in your project root for a project-specific setup

Project-level configuration overrides the global file.

Add a provider that points to Docker Model Runner:

opencode.json

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "dmr": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Docker Model Runner",
      "options": {
        "baseURL": "http://localhost:12434/v1"
      },
      "models": {
        "qwen3-coder": {
          "name": "ai/qwen3-coder"
        },
        "devstral-small-2": {
          "name": "ai/devstral-small-2"
        }
      }
    }
  }
}
```

This configuration adds Docker Model Runner as an OpenCode provider and exposes two local models.

> Note
>
> If your setup expects the older OpenAI-compatible path, use `http://localhost:12434/engines/v1` instead.

## [Step 3: Verify the endpoint](#step-3-verify-the-endpoint)

Check that Docker Model Runner is reachable before you open OpenCode:

```console
$ curl http://localhost:12434/v1/models
```

If you use the older path, run:

```console
$ curl http://localhost:12434/engines/v1/models
```

The response should list the models available through Docker Model Runner.

## [Step 4: Start OpenCode](#step-4-start-opencode)

From your project directory, run:

```console
$ opencode
```

To switch models from the TUI, run:

```text
/models
```

Then select the model from the `dmr` provider.

## [Step 5: Package `gpt-oss` with a larger context window](#step-5-package-gpt-oss-with-a-larger-context-window)

This step is optional. Use it if you need a larger context window for repository-scale tasks.

`gpt-oss` defaults to a smaller context window than coding-focused models. If you want to use it for repository-scale tasks, package a larger variant:

```console
$ docker model pull ai/gpt-oss
$ docker model package --from ai/gpt-oss --context-size 128000 gpt-oss:128k
```

Then add it to your OpenCode configuration:

opencode.json

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "dmr": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Docker Model Runner",
      "options": {
        "baseURL": "http://localhost:12434/v1"
      },
      "models": {
        "gpt-oss:128k": {
          "name": "gpt-oss:128k"
        }
      }
    }
  }
}
```

## [Troubleshooting](#troubleshooting)

If OpenCode can't connect, check Docker Model Runner status:

```console
$ docker model status
```

If OpenCode does not show your model, list local models:

```console
$ docker model ls
```

If the model is missing, pull it first and confirm the model name in `opencode.json` matches the local model you want to use.

## [Learn more](#learn-more)

* [Docker Model Runner overview](https://docs.docker.com/ai/model-runner/)
* [Docker Model Runner API reference](https://docs.docker.com/ai/model-runner/api-reference/)
* [IDE and tool integrations](https://docs.docker.com/ai/model-runner/ide-integrations/)

----
url: https://docs.docker.com/reference/api/extensions-sdk/ServiceError/
----

# Interface: ServiceError

***

Table of contents

***

Error thrown when an HTTP response is received with a status code that falls out to the range of 2xx.

**`Since`**

0.2.0

## [Properties](#properties)

### [name](#name)

• **name**: `string`

***

### [message](#message)

• **message**: `string`

***

### [statusCode](#statuscode)

• **statusCode**: `number`

----
url: https://docs.docker.com/enterprise/security/provisioning/
----

# Provision users

***

Table of contents

***

Subscription: Business

For: Administrators

After configuring your SSO connection, the next step is to provision users. This process ensures that users can access your organization through automated user management.

This page provides an overview of user provisioning and the supported provisioning methods.

## [What is provisioning?](#what-is-provisioning)

Provisioning helps manage users by automating tasks like account creation, updates, and deactivation based on data from your identity provider (IdP). There are several methods for user provisioning, each offering benefits for different organizational needs:

| Provisioning method                                | Description                                                                                                                                    | Default setting in Docker | Recommended for                                                                         |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------- |
| System for Cross-domain Identity Management (SCIM) | Continuously syncs user data between your IdP and Docker, ensuring user attributes remain updated without manual intervention                  | Disabled by default       | Larger organizations or environments with frequent changes in user information or roles |
| Group mapping                                      | Maps user groups from your IdP to specific roles and permissions within Docker, enabling fine-grained access control based on group membership | Disabled by default       | Organizations requiring strict access control and role-based user management            |
| Just-in-Time (JIT)                                 | Automatically creates and provisions user accounts when they first sign in via SSO                                                             | Enabled by default        | Organizations needing minimal setup, smaller teams, or low-security environments        |
| Auto-provision                                     | Adds users when email addresses match a verified domain                                                                                        | Disabled by default       | Orgs without SSO that need to add existing Docker users by domain                       |

## [Default provisioning setup](#default-provisioning-setup)

By default, Docker enables JIT provisioning when you configure an SSO connection. With JIT enabled, user accounts are automatically created the first time a user signs in using your SSO flow.

JIT provisioning may not provide sufficient control or security for some organizations. In such cases, SCIM or group mapping can be configured to give administrators more control over user access and attributes.

## [SSO attributes](#sso-attributes)

When a user signs in through SSO, Docker obtains several attributes from your IdP to manage the user's identity and permissions. These attributes include:

* Email address: The unique identifier for the user
* Full name: The user's complete name
* Groups: Optional. Used for group-based access control
* Docker Org: Optional. Specifies the organization the user belongs to
* Docker Team: Optional. Defines the team the user belongs to within the organization
* Docker Role: Optional. Determines the user's permissions within Docker
* Docker session minutes: Optional. Sets the session duration before users must re-authenticate with their IdP. Must be a positive integer greater than 0. If not provided, default session timeouts apply

> Note
>
> Default session timeouts apply when Docker session minutes is not specified. Docker Desktop sessions expire after 90 days or 30 days of inactivity. Docker Hub and Docker Home sessions expire after 24 hours.

## [SAML attribute mapping](#saml-attribute-mapping)

If your organization uses SAML for SSO, Docker retrieves these attributes from the SAML assertion message. Different IdPs may use different names for these attributes.

| SSO Attribute                     | SAML Assertion Message Attributes                                                                                                                                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Email address                     | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"`, `email` |
| Full name                         | `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"`, `name`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`, `"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"`           |
| Groups (optional)                 | `"http://schemas.xmlsoap.org/claims/Group"`, `"http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"`, `Groups`, `groups`                                                                                      |
| Docker Org (optional)             | `dockerOrg`                                                                                                                                                                                                              |
| Docker Team (optional)            | `dockerTeam`                                                                                                                                                                                                             |
| Docker Role (optional)            | `dockerRole`                                                                                                                                                                                                             |
| Docker session minutes (optional) | `dockerSessionMinutes`, must be a positive integer > 0                                                                                                                                                                   |

## [Next steps](#next-steps)

Choose the provisioning method that best fits your organization's needs:

### [SCIM provisioning](scim/)

[Enable continuous user data synchronization between your IdP and Docker. Best for larger organizations.](scim/)

### [Just-in-Time (JIT) provisioning](just-in-time/)

[Set up automatic user creation on first sign-in. Ideal for smaller teams with minimal setup requirements.](just-in-time/)

### [Auto-provisioning](auto-provisioning/)

[Associate members to an organization when email addresses match a verified domain.](auto-provisioning/)

----
url: https://docs.docker.com/reference/cli/docker/model/bench/
----

# docker model bench

***

| Description | Benchmark a model's performance at different concurrency levels |
| ----------- | --------------------------------------------------------------- |
| Usage       | `docker model bench MODEL`                                      |

## [Description](#description)

Benchmark a model's performance showing tokens per second at different concurrency levels.

This command runs a series of benchmarks with 1, 2, 4, and 8 concurrent requests by default, measuring the tokens per second (TPS) that the model can generate.

## [Options](#options)

| Option          | Default                                                                         | Description                           |
| --------------- | ------------------------------------------------------------------------------- | ------------------------------------- |
| `--concurrency` | `[1,2,4,8]`                                                                     | Concurrency levels to test            |
| `--duration`    | `30s`                                                                           | Duration to run each concurrency test |
| `--json`        |                                                                                 | Output results in JSON format         |
| `--prompt`      | `Write a comprehensive 100 word summary on whales and their impact on society.` | Prompt to use for benchmarking        |
| `--timeout`     | `5m0s`                                                                          | Timeout for each individual request   |

----
url: https://docs.docker.com/reference/samples/mongodb/
----

# MongoDB samples

| Name                                                                                                     | Description                                                              |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [NGINX / Flask / MongoDB](https://github.com/docker/awesome-compose/tree/master/nginx-flask-mongo)       | A sample Python/Flask application with Nginx proxy and a Mongo database. |
| [React / Express / MongoDB](https://github.com/docker/awesome-compose/tree/master/react-express-mongodb) | A sample React application with a Node.js backend and a Mongo database.  |
| [slack-clone-docker](https://github.com/dockersamples/slack-clone-docker)                                | A sample Slack Clone app built with the MERN stack.                      |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/reference/cli/docker/builder/
----

# docker builder

***

| Description | Manage builds    |
| ----------- | ---------------- |
| Usage       | `docker builder` |

## [Description](#description)

Manage builds

## [Subcommands](#subcommands)

| Command                                                                               | Description                      |
| ------------------------------------------------------------------------------------- | -------------------------------- |
| [`docker builder build`](https://docs.docker.com/reference/cli/docker/builder/build/) | Build an image from a Dockerfile |
| [`docker builder prune`](https://docs.docker.com/reference/cli/docker/builder/prune/) | Remove build cache               |

----
url: https://docs.docker.com/build/metadata/attestations/slsa-definitions/
----

# SLSA definitions

***

Table of contents

***

BuildKit supports the [creation of SLSA Provenance](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) for builds that it runs.

The provenance format generated by BuildKit is defined by the SLSA Provenance format (supports both [v0.2](https://slsa.dev/spec/v0.2/provenance) and [v1](https://slsa.dev/spec/v1.1/provenance)).

This page describes how BuildKit populate each field, and whether the field gets included when you generate attestations `mode=min` and `mode=max`.

## [SLSA v1](#slsa-v1)

### [`buildDefinition.buildType`](#builddefinitionbuildtype)

* Ref: <https://slsa.dev/spec/v1.1/provenance#buildType>
* Included with `mode=min` and `mode=max`.

The `buildDefinition.buildType` field is set to `https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md` and can be used to determine the structure of the provenance content.

```json
    "buildDefinition": {
      "buildType": "https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-definitions.md",
      ...
    }
```

### [`buildDefinition.externalParameters.configSource`](#builddefinitionexternalparametersconfigsource)

* Ref: <https://slsa.dev/spec/v1.1/provenance#externalParameters>
* Included with `mode=min` and `mode=max`.

Describes the config that initialized the build.

```json
    "buildDefinition": {
      "externalParameters": {
        "configSource": {
          "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0",
          "digest": {
            "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0"
          },
          "path": "Dockerfile"
        },
        ...
      },
    }
```

For builds initialized from a remote context, like a Git or HTTP URL, this object defines the context URL and its immutable digest in the `uri` and `digest` fields. For builds using a local frontend, such as a Dockerfile, the `path` field defines the path for the frontend file that initialized the build (`filename` frontend option).

### [`buildDefinition.externalParameters.request`](#builddefinitionexternalparametersrequest)

* Ref: <https://slsa.dev/spec/v1.1/provenance#externalParameters>
* Partially included with `mode=min`.

Describes build inputs passed to the build.

```json
    "buildDefinition": {
      "externalParameters": {
        "request": {
          "frontend": "gateway.v0",
          "args": {
            "build-arg:BUILDKIT_CONTEXT_KEEP_GIT_DIR": "1",
            "label:FOO": "bar",
            "source": "docker/dockerfile-upstream:master",
            "target": "release"
          },
          "secrets": [
            {
              "id": "GIT_AUTH_HEADER",
              "optional": true
            },
            ...
          ],
          "ssh": [],
          "locals": []
        },
        ...
      },
    }
```

The following fields are included with both `mode=min` and `mode=max`:

* `locals` lists any local sources used in the build, including the build context and frontend file.

* `frontend` defines type of BuildKit frontend used for the build. Currently, this can be `dockerfile.v0` or `gateway.v0`.

* `args` defines the build arguments passed to the BuildKit frontend.

  The keys inside the `args` object reflect the options as BuildKit receives them. For example, `build-arg` and `label` prefixes are used for build arguments and labels, and `target` key defines the target stage that was built. The `source` key defines the source image for the Gateway frontend, if used.

The following fields are only included with `mode=max`:

* `secrets` defines secrets used during the build. Note that actual secret values are not included.
* `ssh` defines the ssh forwards used during the build.

### [`buildDefinition.internalParameters.buildConfig`](#builddefinitioninternalparametersbuildconfig)

* Ref: <https://slsa.dev/spec/v1.1/provenance#internalParameters>
* Only included with `mode=max`.

Defines the build steps performed during the build.

BuildKit internally uses LLB definition to execute the build steps. The LLB definition of the build steps is defined in the `buildDefinition.internalParameters.buildConfig.llbDefinition` field.

Each LLB step is the JSON definition of the [LLB ProtoBuf API](https://github.com/moby/buildkit/blob/v0.10.0/solver/pb/ops.proto). The dependencies for a vertex in the LLB graph can be found in the `inputs` field for every step.

```json
    "buildDefinition": {
      "internalParameters": {
        "buildConfig": {
          "llbDefinition": [
            {
              "id": "step0",
              "op": {
                "Op": {
                  "exec": {
                    "meta": {
                      "args": [
                        "/bin/sh",
                        "-c",
                        "go build ."
                      ],
                      "env": [
                        "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                        "GOPATH=/go",
                        "GOFLAGS=-mod=vendor",
                      ],
                      "cwd": "/src",
                    },
                    "mounts": [...]
                  }
                },
                "platform": {...},
              },
              "inputs": [
                "step8:0",
                "step2:0",
              ]
            },
            ...
          ]
        },
      }
    }
```

### [`buildDefinition.internalParameters.builderPlatform`](#builddefinitioninternalparametersbuilderplatform)

* Ref: <https://slsa.dev/spec/v1.1/provenance#internalParameters>
* Included with `mode=min` and `mode=max`.

```json
    "buildDefinition": {
      "internalParameters": {
        "builderPlatform": "linux/amd64"
        ...
      },
    }
```

BuildKit sets the `builderPlatform` of the build machine. Note that this is not necessarily the platform of the build result that can be determined from the `in-toto` subject field.

### [`buildDefinition.resolvedDependencies`](#builddefinitionresolveddependencies)

* Ref: <https://slsa.dev/spec/v1.1/provenance#resolvedDependencies>
* Included with `mode=min` and `mode=max`.

Defines all the external artifacts that were part of the build. The value depends on the type of artifact:

* The URL of Git repositories containing source code for the image
* HTTP URLs if you are building from a remote tarball, or that was included using an `ADD` command in Dockerfile
* Any Docker images used during the build

The URLs to the Docker images will be in [Package URL](https://github.com/package-url/purl-spec) format.

All the build materials will include the immutable checksum of the artifact. When building from a mutable tag, you can use the digest information to determine if the artifact has been updated compared to when the build ran.

```json
    "buildDefinition": {
      "resolvedDependencies": [
        {
          "uri": "pkg:docker/alpine@3.17?platform=linux%2Famd64",
          "digest": {
            "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4"
          }
        },
        {
          "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0",
          "digest": {
            "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0"
          }
        },
        ...
      ],
      ...
    }
```

### [`runDetails.builder.id`](#rundetailsbuilderid)

* Ref: <https://slsa.dev/spec/v1.1/provenance#builder.id>
* Included with `mode=min` and `mode=max`.

The field is set to the URL of the build, if available.

```json
    "runDetails": {
      "builder": {
        "id": "https://github.com/docker/buildx/actions/runs/3709599520"
        ...
      },
      ...
    }
```

> Note
>
> This value can be set using the `builder-id` attestation parameter.

### [`runDetails.metadata.invocationID`](#rundetailsmetadatainvocationid)

* Ref: <https://slsa.dev/spec/v1.1/provenance#invocationId>
* Included with `mode=min` and `mode=max`.

Unique identifier for the build invocation. When building a multi-platform image with a single build request, this value will be the shared by all the platform versions of the image.

```json
    "runDetails": {
      "metadata": {
        "invocationID": "rpv7a389uzil5lqmrgwhijwjz",
        ...
      },
      ...
    }
```

### [`runDetails.metadata.startedOn`](#rundetailsmetadatastartedon)

* Ref: <https://slsa.dev/spec/v1.1/provenance#startedOn>
* Included with `mode=min` and `mode=max`.

Timestamp when the build started.

```json
    "runDetails": {
      "metadata": {
        "startedOn": "2021-11-17T15:00:00Z",
        ...
      },
      ...
    }
```

### [`runDetails.metadata.finishedOn`](#rundetailsmetadatafinishedon)

* Ref: <https://slsa.dev/spec/v1.1/provenance#finishedOn>
* Included with `mode=min` and `mode=max`.

Timestamp when the build finished.

```json
    "runDetails": {
      "metadata": {
        "finishedOn": "2021-11-17T15:01:00Z",
        ...
      },
    }
```

### [`runDetails.metadata.buildkit_metadata`](#rundetailsmetadatabuildkit_metadata)

* Ref: <https://slsa.dev/spec/v1.1/provenance#extension-fields>
* Partially included with `mode=min`.

This extension field defines BuildKit-specific additional metadata that is not part of the SLSA provenance spec.

```json
    "runDetails": {
      "metadata": {
        "buildkit_metadata": {
          "source": {...},
          "layers": {...},
          "vcs": {...},
        },
        ...
      },
    }
```

#### [`source`](#source)

Only included with `mode=max`.

Defines a source mapping of LLB build steps, defined in the `buildDefinition.internalParameters.buildConfig.llbDefinition` field, to their original source code (for example, Dockerfile commands). The `source.locations` field contains the ranges of all the Dockerfile commands ran in an LLB step. `source.infos` array contains the source code itself. This mapping is present if the BuildKit frontend provided it when creating the LLB definition.

#### [`layers`](#layers)

Only included with `mode=max`.

Defines the layer mapping of LLB build step mounts defined in `buildDefinition.internalParameters.buildConfig.llbDefinition` to the OCI descriptors of equivalent layers. This mapping is present if the layer data was available, usually when attestation is for an image or if the build step pulled in image data as part of the build.

#### [`vcs`](#vcs)

Included with `mode=min` and `mode=max`.

Defines optional metadata for the version control system used for the build. If a build uses a remote context from Git repository, BuildKit extracts the details of the version control system automatically and displays it in the `buildDefinition.externalParameters.configSource` field. But if the build uses a source from a local directory, the VCS information is lost even if the directory contained a Git repository. In this case, the build client can send additional `vcs:source` and `vcs:revision` build options and BuildKit will add them to the provenance attestations as extra metadata. Note that, contrary to the `buildDefinition.externalParameters.configSource` field, BuildKit doesn't verify the `vcs` values, and as such they can't be trusted and should only be used as a metadata hint.

### [`runDetails.metadata.buildkit_hermetic`](#rundetailsmetadatabuildkit_hermetic)

* Ref: <https://slsa.dev/spec/v1.1/provenance#extension-fields>
* Included with `mode=min` and `mode=max`.

This extension field is set to true if the build was hermetic and did not access the network. In Dockerfiles, a build is hermetic if it does not use `RUN` commands or disables network with `--network=none` flag.

```json
    "runDetails": {
      "metadata": {
        "buildkit_hermetic": true,
        ...
      },
    }
```

### [`runDetails.metadata.buildkit_completeness`](#rundetailsmetadatabuildkit_completeness)

* Ref: <https://slsa.dev/spec/v1.1/provenance#extension-fields>
* Included with `mode=min` and `mode=max`.

This extension field defines if the provenance information is complete. It is similar to `metadata.completeness` field in SLSA v0.2.

`buildkit_completeness.request` is true if all the build arguments are included in the `buildDefinition.externalParameters.request` field. When building with `min` mode, the build arguments are not included in the provenance information and request is not complete. Request is also not complete on direct LLB builds that did not use a frontend.

`buildkit_completeness.resolvedDependencies` is true if `buildDefinition.resolvedDependencies` field includes all the dependencies of the build. When building from un-tracked source in a local directory, the dependencies are not complete, while when building from a remote Git repository all dependencies can be tracked by BuildKit and `buildkit_completeness.resolvedDependencies` is true.

```json
    "runDetails": {
      "metadata": {
        "buildkit_completeness": {
          "request": true,
          "resolvedDependencies": true
        },
        ...
      },
    }
```

### [`runDetails.metadata.buildkit_reproducible`](#rundetailsmetadatabuildkit_reproducible)

* Ref: <https://slsa.dev/spec/v1.1/provenance#extension-fields>
* Included with `mode=min` and `mode=max`.

This extension field defines if the build result is supposed to be byte-by-byte reproducible. It is similar to `metadata.reproducible` field in SLSA v0.2. This value can be set by the user with the `reproducible=true` attestation parameter.

```json
    "runDetails": {
      "metadata": {
        "buildkit_reproducible": false,
        ...
      },
    }
```

## [SLSA v0.2](#slsa-v02)

### [`builder.id`](#builderid)

* Ref: <https://slsa.dev/spec/v0.2/provenance#builder.id>
* Included with `mode=min` and `mode=max`.

The field is set to the URL of the build, if available.

```json
    "builder": {
      "id": "https://github.com/docker/buildx/actions/runs/3709599520"
    },
```

> Note
>
> This value can be set using the `builder-id` attestation parameter.

### [`buildType`](#buildtype)

* Ref: <https://slsa.dev/spec/v0.2/provenance#buildType>
* Included with `mode=min` and `mode=max`.

The `buildType` field is set to `https://mobyproject.org/buildkit@v1` and can be used to determine the structure of the provenance content.

```json
    "buildType": "https://mobyproject.org/buildkit@v1",
```

### [`invocation.configSource`](#invocationconfigsource)

* Ref: <https://slsa.dev/spec/v0.2/provenance#invocation.configSource>
* Included with `mode=min` and `mode=max`.

Describes the config that initialized the build.

```json
    "invocation": {
      "configSource": {
        "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0",
        "digest": {
          "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0"
        },
        "entryPoint": "Dockerfile"
      },
      ...
    },
```

For builds initialized from a remote context, like a Git or HTTP URL, this object defines the context URL and its immutable digest in the `uri` and `digest` fields. For builds using a local frontend, such as a Dockerfile, the `entryPoint` field defines the path for the frontend file that initialized the build (`filename` frontend option).

### [`invocation.parameters`](#invocationparameters)

* Ref: <https://slsa.dev/spec/v0.2/provenance#invocation.parameters>
* Partially included with `mode=min`.

Describes build inputs passed to the build.

```json
    "invocation": {
      "parameters": {
        "frontend": "gateway.v0",
        "args": {
          "build-arg:BUILDKIT_CONTEXT_KEEP_GIT_DIR": "1",
          "label:FOO": "bar",
          "source": "docker/dockerfile-upstream:master",
          "target": "release"
        },
        "secrets": [
          {
            "id": "GIT_AUTH_HEADER",
            "optional": true
          },
          ...
        ],
        "ssh": [],
        "locals": []
      },
      ...
    },
```

The following fields are included with both `mode=min` and `mode=max`:

* `locals` lists any local sources used in the build, including the build context and frontend file.

* `frontend` defines type of BuildKit frontend used for the build. Currently, this can be `dockerfile.v0` or `gateway.v0`.

* `args` defines the build arguments passed to the BuildKit frontend.

  The keys inside the `args` object reflect the options as BuildKit receives them. For example, `build-arg` and `label` prefixes are used for build arguments and labels, and `target` key defines the target stage that was built. The `source` key defines the source image for the Gateway frontend, if used.

The following fields are only included with `mode=max`:

* `secrets` defines secrets used during the build. Note that actual secret values are not included.
* `ssh` defines the ssh forwards used during the build.

### [`invocation.environment`](#invocationenvironment)

* Ref: <https://slsa.dev/spec/v0.2/provenance#invocation.environment>
* Included with `mode=min` and `mode=max`.

```json
    "invocation": {
      "environment": {
        "platform": "linux/amd64"
      },
      ...
    },
```

The only value BuildKit currently sets is the `platform` of the current build machine. Note that this is not necessarily the platform of the build result that can be determined from the `in-toto` subject field.

### [`materials`](#materials)

* Ref: <https://slsa.dev/spec/v0.2/provenance#materials>
* Included with `mode=min` and `mode=max`.

Defines all the external artifacts that were part of the build. The value depends on the type of artifact:

* The URL of Git repositories containing source code for the image
* HTTP URLs if you are building from a remote tarball, or that was included using an `ADD` command in Dockerfile
* Any Docker images used during the build

The URLs to the Docker images will be in [Package URL](https://github.com/package-url/purl-spec) format.

All the build materials will include the immutable checksum of the artifact. When building from a mutable tag, you can use the digest information to determine if the artifact has been updated compared to when the build ran.

```json
    "materials": [
      {
        "uri": "pkg:docker/alpine@3.17?platform=linux%2Famd64",
        "digest": {
          "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4"
        }
      },
      {
        "uri": "https://github.com/moby/buildkit.git#refs/tags/v0.11.0",
        "digest": {
          "sha1": "4b220de5058abfd01ff619c9d2ff6b09a049bea0"
        }
      },
      ...
    ],
```

### [`buildConfig`](#buildconfig)

* Ref: <https://slsa.dev/spec/v0.2/provenance#buildConfig>
* Only included with `mode=max`.

Defines the build steps performed during the build.

BuildKit internally uses LLB definition to execute the build steps. The LLB definition of the build steps is defined in `buildConfig.llbDefinition` field.

Each LLB step is the JSON definition of the [LLB ProtoBuf API](https://github.com/moby/buildkit/blob/v0.10.0/solver/pb/ops.proto). The dependencies for a vertex in the LLB graph can be found in the `inputs` field for every step.

```json
  "buildConfig": {
    "llbDefinition": [
      {
        "id": "step0",
        "op": {
          "Op": {
            "exec": {
              "meta": {
                "args": [
                  "/bin/sh",
                  "-c",
                  "go build ."
                ],
                "env": [
                  "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                  "GOPATH=/go",
                  "GOFLAGS=-mod=vendor",
                ],
                "cwd": "/src",
              },
              "mounts": [...]
            }
          },
          "platform": {...},
        },
        "inputs": [
          "step8:0",
          "step2:0",
        ]
      },
      ...
    ]
  },
```

### [`metadata.buildInvocationId`](#metadatabuildinvocationid)

* Ref: <https://slsa.dev/spec/v0.2/provenance#buildInvocationId>
* Included with `mode=min` and `mode=max`.

Unique identifier for the build invocation. When building a multi-platform image with a single build request, this value will be the shared by all the platform versions of the image.

```json
    "metadata": {
      "buildInvocationID": "rpv7a389uzil5lqmrgwhijwjz",
      ...
    },
```

### [`metadata.buildStartedOn`](#metadatabuildstartedon)

* Ref: <https://slsa.dev/spec/v0.2/provenance#buildStartedOn>
* Included with `mode=min` and `mode=max`.

Timestamp when the build started.

```json
    "metadata": {
      "buildStartedOn": "2021-11-17T15:00:00Z",
      ...
    },
```

### [`metadata.buildFinishedOn`](#metadatabuildfinishedon)

* Ref: <https://slsa.dev/spec/v0.2/provenance#buildFinishedOn>
* Included with `mode=min` and `mode=max`.

Timestamp when the build finished.

```json
    "metadata": {
      "buildFinishedOn": "2021-11-17T15:01:00Z",
      ...
    },
```

### [`metadata.completeness`](#metadatacompleteness)

* Ref: <https://slsa.dev/spec/v0.2/provenance#metadata.completeness>
* Included with `mode=min` and `mode=max`.

Defines if the provenance information is complete.

`completeness.parameters` is true if all the build arguments are included in the `parameters` field. When building with `min` mode, the build arguments are not included in the provenance information and parameters are not complete. Parameters are also not complete on direct LLB builds that did not use a frontend.

`completeness.environment` is always true for BuildKit builds.

`completeness.materials` is true if `materials` field includes all the dependencies of the build. When building from un-tracked source in a local directory, the materials are not complete, while when building from a remote Git repository all materials can be tracked by BuildKit and `completeness.materials` is true.

```json
    "metadata": {
      "completeness": {
        "parameters": true,
        "environment": true,
        "materials": true
      },
      ...
    },
```

### [`metadata.reproducible`](#metadatareproducible)

* Ref: <https://slsa.dev/spec/v0.2/provenance#metadata.reproducible>
* Included with `mode=min` and `mode=max`.

Defines if the build result is supposed to be byte-by-byte reproducible. This value can be set by the user with the `reproducible=true` attestation parameter.

```json
    "metadata": {
      "reproducible": false,
      ...
    },
```

### [`metadata.https://mobyproject.org/buildkit@v1#hermetic`](#metadatahttpsmobyprojectorgbuildkitv1hermetic)

Included with `mode=min` and `mode=max`.

This extension field is set to true if the build was hermetic and did not access the network. In Dockerfiles, a build is hermetic if it does not use `RUN` commands or disables network with `--network=none` flag.

```json
    "metadata": {
      "https://mobyproject.org/buildkit@v1#hermetic": true,
      ...
    },
```

### [`metadata.https://mobyproject.org/buildkit@v1#metadata`](#metadatahttpsmobyprojectorgbuildkitv1metadata)

Partially included with `mode=min`.

This extension field defines BuildKit-specific additional metadata that is not part of the SLSA provenance spec.

```json
    "metadata": {
      "https://mobyproject.org/buildkit@v1#metadata": {
        "source": {...},
        "layers": {...},
        "vcs": {...},
      },
      ...
    },
```

#### [`source`](#source-1)

Only included with `mode=max`.

Defines a source mapping of LLB build steps, defined in the `buildConfig.llbDefinition` field, to their original source code (for example, Dockerfile commands). The `source.locations` field contains the ranges of all the Dockerfile commands ran in an LLB step. `source.infos` array contains the source code itself. This mapping is present if the BuildKit frontend provided it when creating the LLB definition.

#### [`layers`](#layers-1)

Only included with `mode=max`.

Defines the layer mapping of LLB build step mounts defined in `buildConfig.llbDefinition` to the OCI descriptors of equivalent layers. This mapping is present if the layer data was available, usually when attestation is for an image or if the build step pulled in image data as part of the build.

#### [`vcs`](#vcs-1)

Included with `mode=min` and `mode=max`.

Defines optional metadata for the version control system used for the build. If a build uses a remote context from Git repository, BuildKit extracts the details of the version control system automatically and displays it in the `invocation.configSource` field. But if the build uses a source from a local directory, the VCS information is lost even if the directory contained a Git repository. In this case, the build client can send additional `vcs:source` and `vcs:revision` build options and BuildKit will add them to the provenance attestations as extra metadata. Note that, contrary to the `invocation.configSource` field, BuildKit doesn't verify the `vcs` values, and as such they can't be trusted and should only be used as a metadata hint.

----
url: https://docs.docker.com/reference/cli/sbx/policy/log/
----

# sbx policy log

| Description | Show sandbox policy logs           |
| ----------- | ---------------------------------- |
| Usage       | `sbx policy log [SANDBOX] [flags]` |

## [Description](#description)

Show policy logs for all sandboxes, or filter by a specific sandbox name.

Displays which hosts were allowed or blocked by the proxy, along with the matching rule, proxy type, and request count. Useful for debugging connectivity issues or auditing network activity.

## [Options](#options)

| Option        | Default | Description                                             |
| ------------- | ------- | ------------------------------------------------------- |
| `--json`      |         | Output in JSON format                                   |
| `--limit`     | `0`     | Maximum number of log entries to show                   |
| `-q, --quiet` |         | Only display log entries                                |
| `--type`      | `all`   | Filter logs by type: "all" or "network" (default "all") |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Show all policy logs
sbx policy log

# Show logs for a specific sandbox
sbx policy log my-sandbox

# Output in JSON format
sbx policy log --json

# Show the last 20 entries
sbx policy log --limit 20
```

----
url: https://docs.docker.com/reference/cli/docker/scout/policy/
----

# docker scout policy

***

| Description | Evaluate policies against an image and display the policy evaluation results (experimental) |
| ----------- | ------------------------------------------------------------------------------------------- |
| Usage       | `docker scout policy [IMAGE \| REPO]`                                                       |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

The `docker scout policy` command evaluates policies against an image. The image analysis is uploaded to Docker Scout where policies get evaluated.

The policy evaluation results may take a few minutes to become available.

## [Options](#options)

| Option            | Default | Description                                                 |
| ----------------- | ------- | ----------------------------------------------------------- |
| `-e, --exit-code` |         | Return exit code '2' if policies are not met, '0' otherwise |
| `--only-policy`   |         | Comma separated list of policies to evaluate                |
| `--org`           |         | Namespace of the Docker organization                        |
| `-o, --output`    |         | Write the report to a file                                  |
| `--platform`      |         | Platform of image to pull policy results from               |
| `--to-env`        |         | Name of the environment to compare to                       |
| `--to-latest`     |         | Latest image processed to compare to                        |

## [Examples](#examples)

### [Evaluate policies against an image and display the results](#evaluate-policies-against-an-image-and-display-the-results)

```console
$ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1
```

### [Evaluate policies against an image for a specific organization](#evaluate-policies-against-an-image-for-a-specific-organization)

```console
$ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1 --org dockerscoutpolicy
```

### [Evaluate policies against an image with a specific platform](#evaluate-policies-against-an-image-with-a-specific-platform)

```console
$ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1 --platform linux/amd64
```

### [Compare policy results for a repository in a specific environment](#compare-policy-results-for-a-repository-in-a-specific-environment)

```console
$ docker scout policy dockerscoutpolicy/customers-api-service --to-env production
```

----
url: https://docs.docker.com/guides/bun/
----

# Bun language-specific guide

Table of contents

***

Learn how to containerize JavaScript applications with the Bun runtime.

**Time to complete** 10 minutes

The Bun getting started guide teaches you how to create a containerized Bun application using Docker.

> **Acknowledgment**
>
> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide.

## [What will you learn?](#what-will-you-learn)

* Containerize and run a Bun application using Docker
* Set up a local environment to develop a Bun application using containers
* Configure a CI/CD pipeline for a containerized Bun application using GitHub Actions
* Deploy your containerized application locally to Kubernetes to test and debug your deployment

## [Prerequisites](#prerequisites)

* Basic understanding of JavaScript is assumed.
* You must have familiarity with Docker concepts like containers, images, and Dockerfiles. If you are new to Docker, you can start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide.

After completing the Bun getting started modules, you should be able to containerize your own Bun application based on the examples and instructions provided in this guide.

Start by containerizing an existing Bun application.

## [Modules](#modules)

1. [Containerize your app](https://docs.docker.com/guides/bun/containerize/)

   Learn how to containerize a Bun application.

2. [Develop your app](https://docs.docker.com/guides/bun/develop/)

   Learn how to develop your Bun application locally.

3. [Configure CI/CD](https://docs.docker.com/guides/bun/configure-ci-cd/)

   Learn how to configure CI/CD using GitHub Actions for your Bun application.

4. [Test your deployment](https://docs.docker.com/guides/bun/deploy/)

   Learn how to develop locally using Kubernetes

----
url: https://docs.docker.com/guides/admin-user-management/
----

# Mastering user and access management

Table of contents

***

Simplify user access while ensuring security and efficiency in Docker.

**Time to complete** 20 minutes

Managing roles and permissions is key to securing your Docker environment while enabling easy collaboration and operational efficiency. This guide walks IT administrators through the essentials of user and access management, offering strategies for assigning roles, provisioning users, and using tools like activity logs and Insights to monitor and optimize Docker usage.

## [Who's this for?](#whos-this-for)

* IT teams tasked with configuring and maintaining secure user access
* Security professionals focused on enforcing secure access practices
* Project managers overseeing team collaboration and resource management

## [What you'll learn](#what-youll-learn)

* How to assess and manage Docker user access and align accounts with organizational needs
* When to use team configurations for scalable access control
* How to automate and streamline user provisioning with SSO, SCIM, and JIT
* How to get the most out of Docker's monitoring tools

## [Tools integration](#tools-integration)

This guide covers integration with:

* Okta
* Entra ID SAML 2.0
* Azure Connect (OIDC)

## [Modules](#modules)

1. [Setting up roles and permissions in Docker](https://docs.docker.com/guides/admin-user-management/setup/)

   A guide to securely managing access and collaboration in Docker through roles and teams.

2. [Onboarding and managing roles and permissions in Docker](https://docs.docker.com/guides/admin-user-management/onboard/)

   Learn how to manage roles, invite members, and implement scalable access control in Docker for secure and efficient collaboration.

3. [Monitoring and insights](https://docs.docker.com/guides/admin-user-management/audit-and-monitor/)

   Track user actions, team workflows, and organizational trends with Activity logs and Insights to enhance security and productivity in Docker.

----
url: https://docs.docker.com/reference/api/engine/version/v1.46/
----

# Docker Engine API v1.46 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.46.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.46.yaml)

# Docker Engine API (1.46)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.46.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.46) is used. For example, calling `/info` is the same as calling `/v1.46/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.46/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.46/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.46/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"AppArmorProfile": "",
"Args": [
"-c",
"exit 9"
],
"Config": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"/bin/sh",
"-c",
"exit 9"
],
"Domainname": "",
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Healthcheck": {
"Test": [
"CMD-SHELL",
"exit 0"
]
},
"Hostname": "ba033ac44011",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"MacAddress": "",
"NetworkDisabled": false,
"OpenStdin": false,
"StdinOnce": false,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"StopSignal": "SIGTERM",
"StopTimeout": 10
},
"Created": "2015-01-06T15:47:31.485331387Z",
"Driver": "overlay2",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 0,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"ContainerIDFile": "",
"CpusetCpus": "",
"CpusetMems": "",
"CpuPercent": 80,
"CpuShares": 0,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"Devices": [ ],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"IpcMode": "",
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"OomKillDisable": false,
"OomScoreAdj": 500,
"NetworkMode": "bridge",
"PidMode": "",
"PortBindings": { },
"Privileged": false,
"ReadonlyRootfs": false,
"PublishAllPorts": false,
"RestartPolicy": {
"MaximumRetryCount": 2,
"Name": "on-failure"
},
"LogConfig": {
"Type": "json-file"
},
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Ulimits": [
{ }
],
"VolumeDriver": "",
"ShmSize": 67108864
},
"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
"MountLabel": "",
"Name": "/boring_euclid",
"NetworkSettings": {
"Bridge": "",
"SandboxID": "",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": 0,
"SandboxKey": "",
"EndpointID": "",
"Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"MacAddress": "",
"Networks": {
"bridge": {
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
"EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Path": "/bin/sh",
"ProcessLabel": "",
"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
"RestartCount": 1,
"State": {
"Error": "",
"ExitCode": 9,
"FinishedAt": "2015-01-06T15:47:32.080254511Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2019-12-22T10:59:05.6385933Z",
"End": "2019-12-22T10:59:05.8078452Z",
"ExitCode": 0,
"Output": ""
}
]
},
"OOMKilled": false,
"Dead": false,
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z",
"Status": "running"
},
"Mounts": [
{
"Name": "fac362...80535",
"Source": "/data",
"Destination": "/data",
"Driver": "local",
"Mode": "ro,Z",
"RW": false,
"Propagation": ""
}
]
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.46/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
],
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.46/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.46/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.46/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.46/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"read": "2015-01-08T22:57:31.547920715Z",
"pids_stats": {
"current": 3
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"memory_stats": {
"stats": {
"total_pgmajfault": 0,
"cache": 0,
"mapped_file": 0,
"total_inactive_file": 0,
"pgpgout": 414,
"rss": 6537216,
"total_mapped_file": 0,
"writeback": 0,
"unevictable": 0,
"pgpgin": 477,
"total_unevictable": 0,
"pgmajfault": 0,
"total_rss": 6537216,
"total_rss_huge": 6291456,
"total_writeback": 0,
"total_inactive_anon": 0,
"rss_huge": 6291456,
"hierarchical_memory_limit": 67108864,
"total_pgfault": 964,
"total_active_file": 0,
"active_anon": 6537216,
"total_active_anon": 6537216,
"total_pgpgout": 414,
"total_cache": 0,
"inactive_anon": 0,
"active_file": 0,
"pgfault": 964,
"inactive_file": 0,
"total_pgpgin": 477
},
"max_usage": 6651904,
"usage": 6537216,
"failcnt": 0,
"limit": 67108864
},
"blkio_stats": { },
"cpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24472255,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100215355,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 739306590000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24350896,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100093996,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 9492140000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.46/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.46/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.46/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.46/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.46/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime.This field is omitted when empty.                         |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.46/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"string"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.46/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.46/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.46/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.46/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.46/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.46/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.46/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.46/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.46/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.46/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.46/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.46/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.46/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| keep-storage | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| all          | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.46/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.46/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.46/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"DockerVersion": "27.0.1",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "web:web",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": true,
"Image": "",
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.46/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag      | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed.                                                                                                                                                                                                                                                                                                                   |
| platform | stringJSON-encoded OCI platform to select the platform-variant to push. If not provided, all available variants will attempt to be pushed.If the daemon provides a multi-platform image store, this selects the platform-variant to push to the registry. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.46/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.46/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|         |                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------ |
| force   | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags |
| noprune | booleanDefault: falseDo not delete untagged parent images                                              |

### Responses

/v1.46/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                   |
| limit        | integerMaximum number of results to return                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.46/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.46/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.46/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.46/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                          |
| ----- | ---------------------------------------- |
| names | Array of stringsImage names to filter by |

### Responses

/v1.46/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                                             |
| ----- | ----------------------------------------------------------- |
| quiet | booleanDefault: falseSuppress progress details during load. |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.46/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.46/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.46/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.46/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|              |                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired | stringThe network's name.                                                                                                                                                                                                              |
| Driver       | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope        | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal     | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable   | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress      | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly   | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|              | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|              | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv6   | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|              | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|              | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.46/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.46/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
},
"MacAddress": "02:42:ac:12:05:02"
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.46/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.46/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.46/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.46/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.46/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.46/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.46/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.46/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.46/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.46/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.46/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.46/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.46/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.46/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.46/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.46/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.46/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.46/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.46/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.46/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.46/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.46/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.46/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.46/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.46/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.46/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.46/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.46/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.46/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.46/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.46/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.46/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.46/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.46/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.46/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.46/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.46/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.46/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.46/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.46/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.46/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.46/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.46/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.46/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.46/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.46/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.46/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.46/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.46/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.46/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.46/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.46/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.46/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.46/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.46/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"BridgeNfIptables": true,
"BridgeNfIp6tables": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "6.8.0-31-generic",
"OperatingSystem": "Ubuntu 24.04 LTS",
"OSVersion": "24.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"AllowNondistributableArtifactsCIDRs": [ ],
"AllowNondistributableArtifactsHostnames": [ ],
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "27.0.1",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
],
"Containerd": {
"Address": "/run/containerd/containerd.sock",
"Namespaces": {
"Containers": "moby",
"Plugins": "plugins.moby"
}
}
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.46/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "27.0.1",
"Details": { }
}
],
"Version": "27.0.1",
"ApiVersion": "1.46",
"MinAPIVersion": "1.24",
"GitCommit": "48a66213fe",
"GoVersion": "go1.21.11",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "6.8.0-31-generic",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.46/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.46/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.46/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|      |                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |

### Responses

/v1.46/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parents": [ ],
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parents": [
"ndlpt0hhvkqcdfkputsk4cq9c"
],
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.46/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 3987495
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.46/session

----
url: https://docs.docker.com/desktop/setup/install/linux/ubuntu/
----

# Install Docker Desktop on Ubuntu

***

Table of contents

***

> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250 employees or more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopUbuntuInstall).

This page contains information on how to install, launch and upgrade Docker Desktop on an Ubuntu distribution.

## [Prerequisites](#prerequisites)

To install Docker Desktop successfully, you must:

* Meet the [general system requirements](https://docs.docker.com/desktop/setup/install/linux/#general-system-requirements).
* Have an x86-64 system with Ubuntu 26.04 LTS or 24.04 LTS.
* If you're not using GNOME, you must install `gnome-terminal` to enable terminal access from Docker Desktop:
  ```console
  $ sudo apt install gnome-terminal
  ```

## [Install Docker Desktop](#install-docker-desktop)

Recommended approach to install Docker Desktop on Ubuntu:

1. Set up Docker's package repository. See step one of [Install using the `apt` repository](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository).

2. Download the latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64). For checksums, see the [Release notes](https://docs.docker.com/desktop/release-notes/).

3. Install the package using `apt`:

   ```console
   $ sudo apt-get update
   $ sudo apt install ./docker-desktop-amd64.deb
   ```

   > Note
   >
   > At the end of the installation process, `apt` displays an error due to installing a downloaded package. You can ignore this error message.
   >
   > ```text
   > N: Download is performed unsandboxed as root, as file '/home/user/Downloads/docker-desktop.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
   > ```

   By default, Docker Desktop is installed at `/opt/docker-desktop`.

The DEB package includes a post-install script that completes additional setup steps automatically.

The post-install script:

* Sets the capability on the Docker Desktop binary to map privileged ports and set resource limits.
* Adds a DNS name for Kubernetes to `/etc/hosts`.
* Creates a symlink from `/usr/local/bin/com.docker.cli` to `/usr/bin/docker`. This is because the classic Docker CLI is installed at `/usr/bin/docker`. The Docker Desktop installer also installs a Docker CLI binary that includes cloud-integration capabilities and is essentially a wrapper for the Compose CLI, at `/usr/local/bin/com.docker.cli`. The symlink ensures that the wrapper can access the classic Docker CLI.

```console
$ systemctl --user start docker-desktop
```

When Docker Desktop starts, it creates a dedicated [context](/engine/context/working-with-contexts) that the Docker CLI can use as a target and sets it as the current context in use. This is to avoid a clash with a local Docker Engine that may be running on the Linux host and using the default context. On shutdown, Docker Desktop resets the current context to the previous one.

The Docker Desktop installer updates Docker Compose and the Docker CLI binaries on the host. It installs Docker Compose V2 and gives users the choice to link it as docker-compose from the Settings panel. Docker Desktop installs the new Docker CLI binary that includes cloud-integration capabilities in `/usr/local/bin/com.docker.cli` and creates a symlink to the classic Docker CLI at `/usr/local/bin`.

After you’ve successfully installed Docker Desktop, you can check the versions of these binaries by running the following commands:

```console
$ docker compose version
Docker Compose version v2.39.4

$ docker --version
Docker version 28.4.0, build d8eb465

$ docker version
Client:
 Version:           28.4.0
 API version:       1.51
 Go version:        go1.24.7
<...>
```

To enable Docker Desktop to start on sign in, from the Docker menu, select **Settings** > **General** > **Start Docker Desktop when you sign in to your computer**.

Alternatively, open a terminal and run:

```console
$ systemctl --user enable docker-desktop
```

To stop Docker Desktop, select the Docker menu icon to open the Docker menu and select **Quit Docker Desktop**.

Alternatively, open a terminal and run:

```console
$ systemctl --user stop docker-desktop
```

## [Upgrade Docker Desktop](#upgrade-docker-desktop)

When a new version for Docker Desktop is released, the Docker UI shows a notification. You need to download the new package each time you want to upgrade Docker Desktop and run:

```console
$ sudo apt install ./docker-desktop-amd64.deb
```

## [Next steps](#next-steps)

* Review [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopUbuntuInstall) to see what Docker can offer you.
* Follow the [Docker workshop](https://docs.docker.com/get-started/workshop/) to learn how to build an image and run it as a containerized application.
* [Explore Docker Desktop](https://docs.docker.com/desktop/use-desktop/) and all its features.
* [Troubleshooting](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/) describes common problems, workarounds, how to run and submit diagnostics, and submit issues.
* [FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/general/) provide answers to frequently asked questions.
* [Release notes](https://docs.docker.com/desktop/release-notes/) lists component updates, new features, and improvements associated with Docker Desktop releases.
* [Back up and restore data](https://docs.docker.com/desktop/settings-and-maintenance/backup-and-restore/) provides instructions on backing up and restoring data related to Docker.

----
url: https://docs.docker.com/reference/cli/sbx/create/docker-agent/
----

# sbx create docker-agent

| Description | Create a sandbox for docker-agent                |
| ----------- | ------------------------------------------------ |
| Usage       | `sbx create docker-agent PATH [PATH...] [flags]` |

## [Description](#description)

Create a sandbox with access to a host workspace for docker-agent.

The workspace path is required and will be mounted inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Global options](#global-options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `-D, --debug`    |         | Enable debug logging                                                                                                                                                                                                   |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Examples](#examples)

```console
# Create in the current directory
sbx create docker-agent .

# Create with a specific path
sbx create docker-agent /path/to/project

# Create with additional read-only workspaces
sbx create docker-agent . /path/to/docs:ro
```

----
url: https://docs.docker.com/accounts/create-account/
----

# Create a Docker account

***

Table of contents

***

You can create a free Docker account with your email address or by signing up with your Google or GitHub account. After creating a unique Docker ID, you can access all Docker products, including Docker Hub, Docker Desktop, and Docker Scout.

Your Docker ID becomes your username for hosted Docker services, and [Docker forums](https://forums.docker.com/).

> Tip
>
> Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs\&refAction=DocsCreateAccount) to see what else Docker can offer you.

## [Create and verify your account](#create-and-verify-your-account)

Signing up with an email address, Google, or GitHub account requires additional verification to complete account creation:

* If you sign up with Google or GitHub, you must first verify your email address with that provider.

* If you sign up with an email address, you need to follow verification steps.

  * After creating an account, Docker asks for a one-time password (OTP).
  * Find the email from Docker with your code, then return to the OTP page to paste in your OTP code.

Docker blocks sign-in until you've verified your account.

### [Sign up with your email](#sign-up-with-your-email)

1. Go to the [Docker sign-up page](https://app.docker.com/signup/) and enter a unique, valid email address.
2. Enter a username to use as your Docker ID. Once you create your Docker ID you can't reuse it in the future if you deactivate this account. Your username: - Must be between 4 and 30 characters long - Can only contain numbers and lowercase letters
3. Choose a password that's at least 9 characters long, then select **Sign Up**.
4. Verify your email address when you receive the Docker OTP verification email. This completes the registration process.

### [Sign up with Google or GitHub](#sign-up-with-google-or-github)

1. Go to the [Docker sign-up page](https://app.docker.com/signup/).

2. Select your social provider, Google or GitHub.

3. Select the social account you want to link to your Docker account.

4. Select **Authorize Docker** to let Docker access your social account information. You will be re-routed to the sign-up page.

5. Enter a username to use as your Docker ID. Your username:

   * Must be between 4 and 30 characters long
   * Can only contain numbers and lowercase letters

6. Select **Sign up**.

## [Sign in to your account](#sign-in-to-your-account)

You can sign in with your email, Google or GitHub account, or from the Docker CLI.

### [Sign in with email or Docker ID](#sign-in-with-email-or-docker-id)

1. Go to the [Docker sign in page](https://login.docker.com).
2. Enter your email address or Docker ID and select **Continue**.
3. Enter your password and select **Continue**.

To reset your password, see [Reset your password](#reset-your-password).

### [Sign in with Google or GitHub](#sign-in-with-google-or-github)

You can sign in using your Google or GitHub credentials. If your social account uses the same email address as an existing Docker ID, the accounts are automatically linked.

If no Docker ID exists, Docker creates a new account for you.

Docker doesn't support linking multiple sign-in methods to the same Docker ID.

### [Sign in using the CLI](#sign-in-using-the-cli)

Use the `docker login` command to authenticate from the command line. For details, see [`docker login`](/reference/cli/docker/login/).

> Warning
>
> The `docker login` command stores credentials in your home directory under `.docker/config.json`. The password is base64-encoded.
>
> To improve security, use [Docker credential helpers](https://github.com/docker/docker-credential-helpers). For even stronger protection, use a [personal access token](https://docs.docker.com/security/access-tokens/) instead of a password. This is especially useful in CI/CD environments or when credential helpers aren't available.

## [Reset your password](#reset-your-password)

To reset your password:

1. Go to the [Docker sign in page](https://login.docker.com/).
2. Enter your email address.
3. When prompted for your password, select **Forgot password?**.

## [Troubleshooting](#troubleshooting)

If you have a paid Docker subscription, [contact the Support team](https://hub.docker.com/support/contact/) for assistance.

All Docker users can seek troubleshooting information and support through the following resources, where Docker or the community respond on a best effort basis:

* [Docker Community Forums](https://forums.docker.com/)
* [Docker Community Slack](http://dockr.ly/comm-slack)

----
url: https://docs.docker.com/guides/nextjs/
----

# Containerize a Next.js application

Table of contents

***

This guide explains how to containerize Next.js applications, set up development and testing in containers, automate builds with GitHub Actions, and deploy to Kubernetes.

**Time to complete** 20 minutes

This guide shows you how to containerize a Next.js application using Docker, following best practices for creating efficient, production-ready containers.

[Next.js](https://nextjs.org/) is a React framework that enables server-side rendering, static site generation, and full-stack capabilities. Docker provides a consistent containerized environment from development to production.

> **Acknowledgment**
>
> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide and contributing the official [Next.js Docker examples](https://github.com/vercel/next.js/tree/canary/examples/with-docker) to the Vercel Next.js repository, including the standalone and export output examples. As a Docker Captain and experienced engineer, his expertise in Docker, DevOps, and modern web development has made this resource invaluable for the community, helping developers navigate and optimize their Docker workflows.

***

## [What will you learn?](#what-will-you-learn)

In this guide, you will learn how to:

* Containerize and run a Next.js application using Docker.
* Set up a local development environment for Next.js inside a container.
* Run tests for your Next.js application within a Docker container.
* Configure a CI/CD pipeline using GitHub Actions for your containerized app.
* Deploy the containerized Next.js application to a local Kubernetes cluster for testing and debugging.

To begin, you'll start by containerizing an existing Next.js application.

***

## [Prerequisites](#prerequisites)

Before you begin, make sure you're familiar with the following:

* Basic understanding of [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) or [TypeScript](https://www.typescriptlang.org/).
* Basic knowledge of [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts.
* Familiarity with [React](https://react.dev/) and [Next.js](https://nextjs.org/) fundamentals.
* Understanding of Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide.

Once you've completed the Next.js getting started modules, you'll be ready to containerize your own Next.js application using the examples and instructions provided in this guide.

## [Modules](#modules)

1. [Containerize](https://docs.docker.com/guides/nextjs/containerize/)

   Learn how to containerize a Next.js application with Docker by creating an optimized, production-ready image using best practices for performance, security, and scalability.

2. [Develop your app](https://docs.docker.com/guides/nextjs/develop/)

   Learn how to develop your Next.js application locally using containers.

3. [Run your tests and lint](https://docs.docker.com/guides/nextjs/run-tests/)

   Learn how to run your Next.js tests and lint in a container.

4. [GitHub Actions CI](https://docs.docker.com/guides/nextjs/configure-github-actions/)

   Learn how to configure CI/CD using GitHub Actions for your Next.js application.

5. [Test your deployment](https://docs.docker.com/guides/nextjs/deploy/)

   Learn how to deploy locally to test and debug your Kubernetes deployment

----
url: https://docs.docker.com/extensions/extensions-sdk/quickstart/
----

# Quickstart

***

Table of contents

***

Follow this guide to get started with creating a basic Docker extension. The Quickstart guide automatically generates boilerplate files for you.

## [Prerequisites](#prerequisites)

* [Docker Desktop](https://docs.docker.com/desktop/release-notes/)
* [NodeJS](https://nodejs.org/)
* [Go](https://go.dev/dl/)

> Note
>
> NodeJS and Go are only required when you follow the quickstart guide to create an extension. It uses the `docker extension init` command to automatically generate boilerplate files. This command uses a template based on a ReactJS and Go application.

In Docker Desktop settings, ensure you can install the extension you're developing. You may need to navigate to the **Extensions** tab in Docker Desktop settings and deselect **Allow only extensions distributed through the Docker Marketplace**.

## [Step one: Set up your directory](#step-one-set-up-your-directory)

To set up your directory, use the `init` subcommand and provide a name for your extension.

```console
$ docker extension init <my-extension>
```

The command asks a series of questions about your extension, such as its name, a description, and the name of your Hub repository. This helps the CLI generate a set of boilerplate files for you to get started. It stores the boilerplate files in the `my-extension` directory.

The automatically generated extension contains:

* A Go backend service in the `backend` folder that listens on a socket. It has one endpoint `/hello` that returns a JSON payload.
* A React frontend in the `frontend` folder that can call the backend and output the backend’s response.

For more information and guidelines on building the UI, see the [Design and UI styling section](https://docs.docker.com/extensions/extensions-sdk/design/design-guidelines/).

## [Step two: Build the extension](#step-two-build-the-extension)

To build the extension, move into the newly created directory and run:

```console
$ docker build -t <name-of-your-extension> .
```

`docker build` builds the extension and generates an image named the same as the chosen hub repository. For example, if you typed `john/my-extension` as the answer to the following question:

```console
? Hub repository (eg. namespace/repository on hub): john/my-extension`
```

The `docker build` generates an image with name `john/my-extension`.

## [Step three: Install and preview the extension](#step-three-install-and-preview-the-extension)

To install the extension in Docker Desktop, run:

```console
$ docker extension install <name-of-your-extension>
```

To preview the extension in Docker Desktop, once the installation is complete and you should see a **Quickstart** item underneath the **Extensions** menu. Selecting this item opens the extension's frontend.

> Tip
>
> During UI development, it’s helpful to use hot reloading to test your changes without rebuilding your entire extension. See [Preview whilst developing the UI](https://docs.docker.com/extensions/extensions-sdk/dev/test-debug/#hot-reloading-whilst-developing-the-ui) for more information.

You may also want to inspect the containers that belong to the extension. By default, extension containers are hidden from the Docker Dashboard. You can change this in **Settings**, see [how to show extension containers](https://docs.docker.com/extensions/extensions-sdk/dev/test-debug/#show-the-extension-containers) for more information.

## [Step four: Submit and publish your extension to the Marketplace](#step-four-submit-and-publish-your-extension-to-the-marketplace)

If you want to make your extension available to all Docker Desktop users, you can submit it for publication in the Marketplace. For more information, see [Publish](https://docs.docker.com/extensions/extensions-sdk/extensions/).

## [Clean up](#clean-up)

To remove the extension, run:

```console
$ docker extension rm <name-of-your-extension>
```

## [What's next](#whats-next)

* Build a more [advanced frontend](https://docs.docker.com/extensions/extensions-sdk/build/frontend-extension-tutorial/) for your extension.
* Learn how to [test and debug](https://docs.docker.com/extensions/extensions-sdk/dev/test-debug/) your extension.
* Learn how to [setup CI for your extension](https://docs.docker.com/extensions/extensions-sdk/dev/continuous-integration/).
* Learn more about extensions [architecture](https://docs.docker.com/extensions/extensions-sdk/architecture/).
* Learn more about [designing the UI](https://docs.docker.com/extensions/extensions-sdk/design/design-guidelines/).

----
url: https://docs.docker.com/guides/dotnet/containerize/
----

# Containerize a .NET application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client.

## [Overview](#overview)

This section walks you through containerizing and running a .NET application.

## [Get the sample applications](#get-the-sample-applications)

In this guide, you will use a pre-built .NET application. The application is similar to the application built in the Docker Blog article, [Building a Multi-Container .NET App Using Docker Desktop](https://www.docker.com/blog/building-multi-container-net-app-using-docker-desktop/).

Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository.

```console
$ git clone https://github.com/docker/docker-dotnet-sample
```

## [Create Docker assets](#create-docker-assets)

Now that you have an application, you can create the necessary Docker assets to containerize it. You can choose between using the official .NET images or Docker Hardened Images (DHI).

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

> [Docker Hardened Images (DHIs)](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. DHI images are recommended for better security—they are designed to reduce vulnerabilities and simplify compliance.

Docker Hardened Images (DHIs) for .NET are available in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/aspnetcore). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide.

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Pull the .NET SDK DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/dotnet:10-sdk
   ```

3. Pull the ASP.NET Core runtime DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/aspnetcore:10
   ```

Create the following files in your `docker-dotnet-sample` directory.

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1

FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build
ARG TARGETARCH
COPY . /source
WORKDIR /source/src
RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \
    dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app

FROM dhi.io/aspnetcore:10 AS final
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "myWebApp.dll"]
```

> Note
>
> DHI runtime images already run as a non-root user (`nonroot`, UID 65532), so there's no need to create a user or specify `USER` in your Dockerfile. This reduces the attack surface and simplifies your configuration.

compose.yaml

```yaml
# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Docker Compose reference guide at
# https://docs.docker.com/go/compose-spec-reference/

# Here the instructions define your application as a service called "server".
# This service is built from the Dockerfile in the current directory.
# You can add other services your application may depend on here, such as a
# database or a cache. For examples, see the Awesome Compose repository:
# https://github.com/docker/awesome-compose
services:
  server:
    build:
      context: .
      target: final
    ports:
      - 8080:8080

# The commented out section below is an example of how to define a PostgreSQL
# database that your application can use. `depends_on` tells Docker Compose to
# start the database before your application. The `db-data` volume persists the
# database data between container restarts. The `db-password` secret is used
# to set the database password. You must create `db/password.txt` and add
# a password of your choosing to it before running `docker compose up`.
#     depends_on:
#       db:
#         condition: service_healthy
#   db:
#     image: postgres
#     restart: always
#     user: postgres
#     secrets:
#       - db-password
#     volumes:
#       - db-data:/var/lib/postgresql/data
#     environment:
#       - POSTGRES_DB=example
#       - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
#     expose:
#       - 5432
#     healthcheck:
#       test: [ "CMD", "pg_isready" ]
#       interval: 10s
#       timeout: 5s
#       retries: 5
# volumes:
#   db-data:
# secrets:
#   db-password:
#     file: db/password.txt
```

.dockerignore

```text
# Include any files or directories that you don't want to be copied to your
# container here (e.g., local build artifacts, temporary files, etc.).
#
# For more help, visit the .dockerignore file reference guide at
# https://docs.docker.com/go/build-context-dockerignore/

**/.classpath
**/.dockerignore
**/.env
**/.git
**/.gitignore
**/.project
**/.settings
**/.toolstarget
**/.vs
**/.vscode
**/*.*proj.user
**/*.dbmdl
**/*.jfm
**/bin
**/charts
**/docker-compose*
**/compose.y*ml
**/Dockerfile*
**/node_modules
**/npm-debug.log
**/obj
**/secrets.dev.yaml
**/values.dev.yaml
LICENSE
README.md
```

Create the following files in your `docker-dotnet-sample` directory.

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1

FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build
ARG TARGETARCH
COPY . /source
WORKDIR /source/src
RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \
    dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app

FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
WORKDIR /app
COPY --from=build /app .
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser
USER appuser
ENTRYPOINT ["dotnet", "myWebApp.dll"]
```

compose.yaml

```yaml
# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Docker Compose reference guide at
# https://docs.docker.com/go/compose-spec-reference/

# Here the instructions define your application as a service called "server".
# This service is built from the Dockerfile in the current directory.
# You can add other services your application may depend on here, such as a
# database or a cache. For examples, see the Awesome Compose repository:
# https://github.com/docker/awesome-compose
services:
  server:
    build:
      context: .
      target: final
    ports:
      - 8080:8080

# The commented out section below is an example of how to define a PostgreSQL
# database that your application can use. `depends_on` tells Docker Compose to
# start the database before your application. The `db-data` volume persists the
# database data between container restarts. The `db-password` secret is used
# to set the database password. You must create `db/password.txt` and add
# a password of your choosing to it before running `docker compose up`.
#     depends_on:
#       db:
#         condition: service_healthy
#   db:
#     image: postgres
#     restart: always
#     user: postgres
#     secrets:
#       - db-password
#     volumes:
#       - db-data:/var/lib/postgresql/data
#     environment:
#       - POSTGRES_DB=example
#       - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
#     expose:
#       - 5432
#     healthcheck:
#       test: [ "CMD", "pg_isready" ]
#       interval: 10s
#       timeout: 5s
#       retries: 5
# volumes:
#   db-data:
# secrets:
#   db-password:
#     file: db/password.txt
```

.dockerignore

```text
# Include any files or directories that you don't want to be copied to your
# container here (e.g., local build artifacts, temporary files, etc.).
#
# For more help, visit the .dockerignore file reference guide at
# https://docs.docker.com/go/build-context-dockerignore/

**/.classpath
**/.dockerignore
**/.env
**/.git
**/.gitignore
**/.project
**/.settings
**/.toolstarget
**/.vs
**/.vscode
**/*.*proj.user
**/*.dbmdl
**/*.jfm
**/bin
**/charts
**/docker-compose*
**/compose.y*ml
**/Dockerfile*
**/node_modules
**/npm-debug.log
**/obj
**/secrets.dev.yaml
**/values.dev.yaml
LICENSE
README.md
```

You should now have the following contents in your `docker-dotnet-sample` directory.

```text
├── docker-dotnet-sample/
│ ├── .git/
│ ├── src/
│ ├── .dockerignore
│ ├── compose.yaml
│ ├── Dockerfile
│ └── README.md
```

To learn more about the files, see the following:

* [Dockerfile](https://docs.docker.com/reference/dockerfile/)
* [.dockerignore](https://docs.docker.com/reference/dockerfile/#dockerignore-file)
* [compose.yaml](https://docs.docker.com/reference/compose-file/)

## [Run the application](#run-the-application)

Inside the `docker-dotnet-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:8080>. You should see a simple web application.

In the terminal, press `ctrl`+`c` to stop the application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `docker-dotnet-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:8080>. You should see a simple web application.

In the terminal, run the following command to stop the application.

```console
$ docker compose down
```

For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

## [Summary](#summary)

In this section, you learned how you can containerize and run your .NET application using Docker.

Related information:

* [Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
* [.dockerignore file reference](https://docs.docker.com/reference/dockerfile/#dockerignore-file)
* [Docker Compose overview](https://docs.docker.com/compose/)
* [Docker Hardened Images](/dhi/)

## [Next steps](#next-steps)

In the next section, you'll learn how you can develop your application using Docker containers.

[Use containers for .NET development »](https://docs.docker.com/guides/dotnet/develop/)

----
url: https://docs.docker.com/enterprise/security/single-sign-on/connect/
----

# Set up single sign-on

***

Table of contents

***

Subscription: Business

For: Administrators

To set up a single sign-on (SSO), you need to establish a connection between Docker and your identity provider (IdP). While this guide uses Okta and Microsoft Entra ID as a working example, the general process remains the same for other IdPs.

If you're unfamiliar with the SSO process, first review [SSO overview](https://docs.docker.com/enterprise/security/single-sign-on/) to learn about how SSO works.

## [Prerequisites](#prerequisites)

Docker supports any SAML 2.0 or OIDC-compatible identity provider. Before you begin, make sure the following conditions are met:

* Notify your company about the upcoming SSO sign-in process.
* Confirm that each Docker user has a valid IdP account using the same email address as their Unique Primary Identifier (UPN).
* Ensure CI/CD pipelines use PATs or OATs instead of passwords.

## [Set up an SSO connection](#set-up-an-sso-connection)

> Tip
>
> These procedures have you copy and paste values between Docker and your IdP. Complete this guide in one session with separate browser windows open for Docker and your IdP.

### [Step 1: Add a domain](#step-1-add-a-domain)

To add a domain:

1. Sign in to [app.docker.com](https://app.docker.com), then choose your organization. If your organization is part of a company, then select the company to manage the domain at the company level.
2. Select **Admin Console**, then **Domain management**.
3. Select **Add a domain**.
4. Enter your domain in the text box and select **Add domain**.
5. In the modal, copy the **TXT Record Value** provided for domain verification.

### [Step 2: Verify your domain](#step-2-verify-your-domain)

To confirm domain ownership, add a TXT record to your Domain Name System (DNS) host using the TXT Record Value from Docker. DNS propagation can take up to 72 hours. Docker automatically checks for the record during this time.

> Tip
>
> When adding a record name, use `@` or leave it empty for root domains like `example.com`. Avoid common values like `docker`, `docker-verification`, `www`, or your domain name itself. Always check your DNS provider's documentation to verify their specific record name requirements.

1. To add your TXT record to AWS, see [Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html).
2. Wait up to 72 hours for TXT record verification.
3. After the record is live, go to **Domain management** in the [Admin Console](https://app.docker.com/admin) and select **Verify**.

1) To add your TXT record to Google Cloud DNS, see [Verifying your domain with a TXT record](https://cloud.google.com/identity/docs/verify-domain-txt).
2) Wait up to 72 hours for TXT record verification.
3) After the record is live, go to **Domain management** in the [Admin Console](https://app.docker.com/admin) and select **Verify**.

1. To add your TXT record to GoDaddy, see [Add a TXT record](https://www.godaddy.com/help/add-a-txt-record-19232).
2. Wait up to 72 hours for TXT record verification.
3. After the record is live, go to **Domain management** in the [Admin Console](https://app.docker.com/admin) and select **Verify**.

1) Sign in to your domain host.
2) Add a TXT record to your DNS settings and save the record.
3) Wait up to 72 hours for TXT record verification.
4) After the record is live, go to **Domain management** in the [Admin Console](https://app.docker.com/admin) and select **Verify**.

### [Step 3: Create an SSO connection in Docker](#step-3-create-an-sso-connection-in-docker)

1. From [app.docker.com](https://app.docker.com), choose your organization. Select **Admin Console**.

2. Choose **SSO and SCIM** from the **Security** section.

3. Select **Create Connection**. Name the connection, then choose **SAML 2.0**.

4. Keep this window open. You need to copy and paste these values in your Okta window:

   * **Entity ID**
   * **ACS URL**
   * **Connection ID**

You will return here to finish connecting after creating an SSO connection in your IdP.

### [Step 4: Create an SSO connection in your IdP](#step-4-create-an-sso-connection-in-your-idp)

Use the following tabs based on your IdP provider.

You need [super admin permissions](https://help.okta.com/en-us/content/topics/security/administrators-super-admin.htm) for the Okta org.

1. Sign in to your Okta Admin account. From the top nav, select the **Admin** button to go to Okta's Admin Console.

2. From the **Applications** section in the left nav, choose **Applications**. Select **Create App Integration**.

3. Choose SAML 2.0 to match your selection from Docker's Admin Console.

4. For **General Settings**, name your app "Docker." Uploading a logo is optional.

5. For **Configure SAML**, input the following values:

   * For the **Single Sign On URL** value, paste the Docker ACS URL.
   * For the **Audience URI (SP Entity ID)** value, paste the Docker Entity ID.
   * For **Name ID format**, choose `EmailAddress`
   * For **Application username**, choose `Email`
   * For **Update application username on**, choose `Create and update`
   * Optional. Add [SAML attributes](https://docs.docker.com/enterprise/security/provisioning/#sso-attributes), if required by your org.

6. For **Feedback**, choose **This is an internal app that we have created** checkbox before finishing.

Keep your Okta window open for the next step.

To enable SSO with Microsoft Entra, you need [Cloud Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#cloud-application-administrator) permissions.

1. From Microsoft Entra admin center, select **Entra ID**, then go to **Enterprise apps**. Select **All applications**.

2. Choose **Create your own application** and name your app "Docker". Select **Non-gallery**.

3. After creating your app, go to **Single Sign-On** and select **SAML**.

4. Select **Edit** on the **Basic SAML configuration** section. From **Basic SAML configuration**, choose **Edit** and paste the values you copied from creating an SSO connection in Docker:

   * For the **Identifier** value, paste the Docker Entity ID.
   * For the **Reply URL** value, paste Docker ACS URL.

5. Optional. Add [SAML attributes](https://docs.docker.com/enterprise/security/provisioning/#sso-attributes), if required by your org.

6. From the **SAML Signing Certificate** section, download your **Certificate (Base64)**.

#### [Register the app](#register-the-app)

1. Sign in to [Microsoft Entra admin center](https://entra.microsoft.com/).
2. Go to **App Registration** and select **New Registration**.
3. Name the application "Docker".
4. Set account types and paste the **Redirect URI** from Docker.
5. Select **Register**.
6. Copy the **Client ID**.

#### [Create client secrets](#create-client-secrets)

1. In your app, go to **Certificates & secrets**.
2. Select **New client secret**, describe and configure duration, then **Add**.
3. Copy the **value** of the new secret.

#### [Set API permissions](#set-api-permissions)

1. In your app, go to **API permissions**.
2. Select **Grant admin consent** and confirm.
3. Select **Add a permissions** > **Delegated permissions**.
4. Search and select `User.Read`.
5. Confirm that admin consent is granted.

### [Step 5: Connect Docker to your IdP](#step-5-connect-docker-to-your-idp)

Complete the integration by pasting your IdP values into Docker.

> Important
>
> When prompted to copy a certificate, copy the entire certificate starting with `----BEGIN CERTIFICATE----` and including the `----END CERTIFICATE----` lines.

1. Go to **Applications** and choose **Applications**. Choose your app from the **ACTIVE** table.
2. From **Sign on**, go to **View SAML setup instructions**. This page contains the **SAML Sign-in URL** and **x509 Certificate**. Keep this page open.
3. Return to your opened Docker window for the **Create single sign-on connection** step. Paste in the **SAML Sign-in URL** and **x509 Certificate** values.
4. Optional. Select a default team, if required by your org.
5. Review and select **Create connection**.

1) Open your downloaded **Certificate (Base64)** in a text editor.

2) Copy the following values:

   * From Azure AD: **Login URL**
   * **Certificate (Base64)** contents

3) Return to the Docker Admin Console, then paste the **Login URL** and **Certificate (Base64)** values.

4) Choose your domain from the drop-down.

5) Optional. Select a default team, if required by your org.

6) Review and select **Create connection**.

1. Return to the Docker Admin Console.

2. Paste the following values:

   * **Client ID**
   * **Client Secret**
   * **Azure AD Domain**

3. Optional. Select a default team, if required by your org.

4. Review and select **Create connection**.

### [Step 6: Test the connection](#step-6-test-the-connection)

IdPs like Microsoft Entra and Okta may require that you assign a user to an application before testing SSO. You can review [Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso#test-single-sign-on)'s documentation and [Okta](https://help.okta.com/wf/en-us/content/topics/workflows/connector-reference/okta/actions/assignusertoapplicationforsso.htm)'s documentation to learn how to assign yourself or other users to an app.

After assigning yourself to an app:

1. Open an incognito browser window and sign in to the Admin Console using your domain email address.
2. When redirected to your IdP's sign in page, authenticate with your domain email instead of using your Docker ID.

If you have multiple IdPs, choose the sign-in option **Continue with SSO**. If you're using the CLI, you must authenticate using a personal access token.

## [Configure multiple IdPs](#configure-multiple-idps)

Docker supports multiple identity provider (IdP) configurations by letting you associate one domain with more than one IdP. Each connection must use the same domain, which lets users choose their IdP when they select **Continue with SSO** at sign in.

To add multiple IdPs:

1. Use the same domain for each connection.
2. Repeat steps 3-6 from the [Set up an SSO connection](https://docs.docker.com/enterprise/security/single-sign-on/connect/#set-up-an-sso-connection) procedures on this page. Repeat these steps for each IdP your organization intends to use.

Because you must use the same domain for each IdP, you won't need to repeat steps to add and verify your domains.

## [Enforce SSO](#enforce-sso)

If SSO is not enforced, users can still sign in using Docker usernames and passwords. Enforcing SSO requires users to use SSO when signing into Docker, which centralizes authentication and enforces policies set by the IdP.

Before enforcing SSO, users accessing Docker through the CLI must [create a personal access token (PAT)](https://docs.docker.com/security/access-tokens/). The PAT replaces their username and password for authentication.

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization or company.
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the SSO connections table, select the **Action** menu, then **Enable enforcement**.
4. Follow the on-screen instructions.
5. Select **Turn on enforcement**.

When you enforce SSO, your users cannot modify their email address and password, convert a user account to an organization, or set up 2FA through Docker Hub. If you want to use 2FA, you must enable 2FA through your IdP.

## [Next steps](#next-steps)

* [Provision users](https://docs.docker.com/enterprise/security/provisioning/).
* [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).
* [Create personal access tokens](https://docs.docker.com/security/access-tokens/).
* [Troubleshoot SSO](https://docs.docker.com/enterprise/security/single-sign-on/troubleshoot-sso/) issues.

----
url: https://docs.docker.com/ai/sandboxes/agents/cursor/
----

# Cursor

***

Table of contents

***

This guide covers authentication, configuration, and usage of Cursor in a sandboxed environment.

Official documentation: [Cursor CLI](https://cursor.com/cli)

## [Quick start](#quick-start)

Create a sandbox and run Cursor for a project directory:

```console
$ sbx run cursor ~/my-project
```

The workspace parameter is optional and defaults to the current directory:

```console
$ cd ~/my-project
$ sbx run cursor
```

## [Authentication](#authentication)

Cursor supports two authentication methods: an API key or OAuth.

**API key**: Store your Cursor API key using [stored secrets](https://docs.docker.com/ai/sandboxes/security/credentials/#stored-secrets):

```console
$ sbx secret set -g cursor
```

Alternatively, export the `CURSOR_API_KEY` environment variable in your shell before running the sandbox. See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for details on both methods.

**OAuth**: If no API key is set, Cursor prompts you to sign in interactively on first run. The proxy intercepts the token exchange with `api2.cursor.sh/auth/poll`, so credentials are managed by the host and aren't stored inside the sandbox.

## [Configuration](#configuration)

Sandboxes don't pick up user-level configuration from your host, such as `~/.cursor`. Only project-level configuration in the working directory is available inside the sandbox. See [Why doesn't the sandbox use my user-level agent configuration?](https://docs.docker.com/ai/sandboxes/faq/#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for workarounds.

Cursor reads `AGENTS.md` from the workspace for agent-specific instructions.

### [Default startup command](#default-startup-command)

Without extra args, the sandbox runs:

```text
cursor-agent --yolo
```

Args after `--` replace these defaults rather than being appended. To keep `--yolo`, include it yourself:

```console
$ sbx run cursor -- --yolo -p "refactor this"
```

## [Base image](#base-image)

Template: `docker/sandbox-templates:cursor-agent-docker`

Preconfigured with HTTP/1.1 and server-sent events for agent traffic so requests flow through the host proxy. Authentication state is persisted across sandbox restarts.

See [Customize](https://docs.docker.com/ai/sandboxes/customize/) to pre-install tools or customize this environment.

----
url: https://docs.docker.com/guides/github-sonarqube-sandbox/troubleshoot/
----

# Troubleshoot code quality workflows

***

Table of contents

***

This page covers common issues you might encounter when building code quality workflows with E2B sandboxes and MCP servers, along with their solutions.

If you're experiencing problems not covered here, check the [E2B documentation](https://e2b.dev/docs).

## [MCP tools not available](#mcp-tools-not-available)

Issue: Claude reports `I don't have any MCP tools available`.

Solution:

1. Verify you're using the authorization header:

   ```plaintext
   --header "Authorization: Bearer ${mcpToken}"
   ```

2. Check you're waiting for MCP initialization.

   ```typescript
   // typescript
   await new Promise((resolve) => setTimeout(resolve, 1000));
   ```

   ```python
   # python
   await asyncio.sleep(1)
   ```

3. Ensure credentials are in both `envs` and `mcp` configuration:

   ```typescript
   // typescript
   const sbx = await Sandbox.betaCreate({
     envs: {
       ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
       GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
       SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!,
     },
     mcp: {
       githubOfficial: {
         githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
       },
       sonarqube: {
         org: process.env.SONARQUBE_ORG!,
         token: process.env.SONARQUBE_TOKEN!,
         url: "https://sonarcloud.io",
       },
     },
   });
   ```

   ```python
   # python
   sbx = await AsyncSandbox.beta_create(
       envs={
           "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
           "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
           "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"),
       },
       mcp={
           "githubOfficial": {
               "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
           },
           "sonarqube": {
               "org": os.getenv("SONARQUBE_ORG"),
               "token": os.getenv("SONARQUBE_TOKEN"),
               "url": "https://sonarcloud.io",
           },
       },
   )
   ```

4. Verify your API tokens are valid and have proper scopes.

## [GitHub tools work but SonarQube doesn't](#github-tools-work-but-sonarqube-doesnt)

Issue: GitHub MCP tools load but SonarQube tools don't appear.

Solution: SonarQube MCP server requires GitHub to be configured simultaneously. Always include both servers in your sandbox configuration, even if you're only testing one.

```typescript
// Include both servers even if only using one
const sbx = await Sandbox.betaCreate({
  envs: {
    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
    GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
    SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!,
  },
  mcp: {
    githubOfficial: {
      githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
    },
    sonarqube: {
      org: process.env.SONARQUBE_ORG!,
      token: process.env.SONARQUBE_TOKEN!,
      url: "https://sonarcloud.io",
    },
  },
});
```

```python
# Include both servers even if only using one
sbx = await AsyncSandbox.beta_create(
    envs={
        "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
        "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
        "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"),
    },
    mcp={
        "githubOfficial": {
            "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
        },
        "sonarqube": {
            "org": os.getenv("SONARQUBE_ORG"),
            "token": os.getenv("SONARQUBE_TOKEN"),
            "url": "https://sonarcloud.io",
        },
    },
)
```

## [Claude can't access private repositories](#claude-cant-access-private-repositories)

Issue: "I don't have access to that repository".

Solution:

1. Verify your GitHub token has `repo` scope (not just `public_repo`).

2. Test with a public repository first.

3. Ensure the repository owner and name are correct in your `.env`:

   ```plaintext
   GITHUB_OWNER=your_github_username
   GITHUB_REPO=your_repository_name
   ```

   ```plaintext
   GITHUB_OWNER=your_github_username
   GITHUB_REPO=your_repository_name
   ```

## [Workflow times out or runs too long](#workflow-times-out-or-runs-too-long)

Issue: Workflow doesn't complete or Claude credits run out.

Solutions:

1. Use `timeoutMs: 0` (TypeScript) or `timeout_ms=0` (Python) for complex workflows to allow unlimited time:

   ```typescript
   await sbx.commands.run(
     `echo '${prompt}' | claude -p --dangerously-skip-permissions`,
     {
       timeoutMs: 0, // No timeout
       onStdout: console.log,
       onStderr: console.log,
     },
   );
   ```

   ```python
   await sbx.commands.run(
       f"echo '{prompt}' | claude -p --dangerously-skip-permissions",
       timeout_ms=0,  # No timeout
       on_stdout=print,
       on_stderr=print,
   )
   ```

2. Break complex workflows into smaller, focused tasks.

3. Monitor your Anthropic API credit usage.

4. Add checkpoints in prompts: "After each step, show progress before continuing".

## [Sandbox cleanup errors](#sandbox-cleanup-errors)

Issue: Sandboxes aren't being cleaned up properly, leading to resource exhaustion.

Solution: Always use proper error handling with cleanup in the `finally` block:

```typescript
async function robustWorkflow() {
  let sbx: Sandbox | undefined;

  try {
    sbx = await Sandbox.betaCreate({
      // ... configuration
    });

    // ... workflow logic
  } catch (error) {
    console.error("Workflow failed:", error);
    process.exit(1);
  } finally {
    if (sbx) {
      console.log("Cleaning up sandbox...");
      await sbx.kill();
    }
  }
}
```

```python
async def robust_workflow():
    sbx = None

    try:
        sbx = await AsyncSandbox.beta_create(
            # ... configuration
        )

        # ... workflow logic

    except Exception as error:
        print(f"Workflow failed: {error}")
        sys.exit(1)
    finally:
        if sbx:
            print("Cleaning up sandbox...")
            await sbx.kill()
```

## [Environment variable not loading](#environment-variable-not-loading)

Issue: Script fails with "undefined" or "None" for environment variables.

Solution:

1. Ensure `dotenv` is loaded at the top of your file:

   ```typescript
   import "dotenv/config";
   ```

2. Verify the `.env` file is in the same directory as your script.

3. Check variable names match exactly (case-sensitive):

   ```typescript
   // .env file
   GITHUB_TOKEN = ghp_xxxxx;

   // In code
   process.env.GITHUB_TOKEN; // Correct
   process.env.github_token; // Wrong - case doesn't match
   ```

1) Ensure `dotenv` is loaded at the top of your file:

   ```python
   from dotenv import load_dotenv
   load_dotenv()
   ```

2) Verify the `.env` file is in the same directory as your script.

3) Check variable names match exactly (case-sensitive):

   ```python
   # .env file
   GITHUB_TOKEN=ghp_xxxxx

   # In code
   os.getenv("GITHUB_TOKEN")  # Correct
   os.getenv("github_token")  # Wrong - case doesn't match
   ```

## [SonarQube returns empty results](#sonarqube-returns-empty-results)

Issue: SonarQube analysis returns no projects or issues.

Solution:

1. Verify your SonarCloud organization key is correct.
2. Ensure you have at least one project configured in SonarCloud.
3. Check that your SonarQube token has the necessary permissions.
4. Confirm your project has been analyzed at least once in SonarCloud.

----
url: https://docs.docker.com/reference/cli/docker/compose/cp/
----

# docker compose cp

***

| Description | Copy files/folders between a service container and the local filesystem                                               |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| Usage       | `docker compose cp [OPTIONS] SERVICE:SRC_PATH DEST_PATH\|- docker compose cp [OPTIONS] SRC_PATH\|- SERVICE:DEST_PATH` |

## [Description](#description)

Copy files/folders between a service container and the local filesystem

## [Options](#options)

| Option              | Default | Description                                             |
| ------------------- | ------- | ------------------------------------------------------- |
| `--all`             |         | Include containers created by the run command           |
| `-a, --archive`     |         | Archive mode (copy all uid/gid information)             |
| `-L, --follow-link` |         | Always follow symbol link in SRC\_PATH                  |
| `--index`           |         | Index of the container if service has multiple replicas |

----
url: https://docs.docker.com/guides/text-classification/
----

[Build a text recognition app](https://docs.docker.com/guides/text-classification/)

This guide details how to containerize text classification models using Docker.

Python AI

20 minutes

[« Back to all guides](/guides/)

# Build a text recognition app

***

Table of contents

***

## [Overview](#overview)

In this guide, you'll learn how to create and run a text recognition application. You'll build the application using Python with scikit-learn and the Natural Language Toolkit (NLTK). Then you'll set up the environment and run the application using Docker.

The application analyzes the sentiment of a user's input text using NLTK's SentimentIntensityAnalyzer. It lets the user input text, which is then processed to determine its sentiment, classifying it as either positive or negative. Also, it displays the accuracy and a detailed classification report of its sentiment analysis model based on a predefined dataset.

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop.
* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Get the sample application](#get-the-sample-application)

1. Open a terminal, and clone the sample application's repository using the following command.

   ```console
   $ git clone https://github.com/harsh4870/Docker-NLP.git
   ```

2. Verify that you cloned the repository.

   You should see the following files in your `Docker-NLP` directory.

   ```text
   01_sentiment_analysis.py
   02_name_entity_recognition.py
   03_text_classification.py
   04_text_summarization.py
   05_language_translation.py
   entrypoint.sh
   requirements.txt
   Dockerfile
   README.md
   ```

## [Explore the application code](#explore-the-application-code)

The source code for the text classification application is in the `Docker-NLP/03_text_classification.py` file. Open `03_text_classification.py` in a text or code editor to explore its contents in the following steps.

1. Import the required libraries.

   ```python
   import nltk
   from nltk.sentiment import SentimentIntensityAnalyzer
   from sklearn.metrics import accuracy_score, classification_report
   from sklearn.model_selection import train_test_split
   import ssl
   ```

   * `nltk`: A popular Python library for natural language processing (NLP).
   * `SentimentIntensityAnalyzer`: A component of `nltk` for sentiment analysis.
   * `accuracy_score`, `classification_report`: Functions from scikit-learn for evaluating the model.
   * `train_test_split`: Function from scikit-learn to split datasets into training and testing sets.
   * `ssl`: Used for handling SSL certificate issues which might occur while downloading data for `nltk`.

2. Handle SSL certificate verification.

   ```python
   try:
       _create_unverified_https_context = ssl._create_unverified_context
   except AttributeError:
       pass
   else:
       ssl._create_default_https_context = _create_unverified_https_context
   ```

   This block is a workaround for certain environments where downloading data through NLTK might fail due to SSL certificate verification issues. It's telling Python to ignore SSL certificate verification for HTTPS requests.

3. Download NLTK resources.

   ```python
   nltk.download('vader_lexicon')
   ```

   The `vader_lexicon` is a lexicon used by the `SentimentIntensityAnalyzer` for sentiment analysis.

4. Define text for testing and corresponding labels.

   ```python
   texts = [...]
   labels = [0, 1, 2, 0, 1, 2]
   ```

   This section defines a small dataset of texts and their corresponding labels (0 for positive, 1 for negative, and 2 for spam).

5. Split the test data.

   ```python
   X_train, X_test, y_train, y_test = train_test_split(texts, labels, test_size=0.2, random_state=42)
   ```

   This part splits the dataset into training and testing sets, with 20% of data as the test set. As this application uses a pre-trained model, it doesn't train the model.

6. Set up sentiment analysis.

   ```python
   sia = SentimentIntensityAnalyzer()
   ```

   This code initializes the `SentimentIntensityAnalyzer` to analyze the sentiment of text.

7. Generate predictions and classifications for the test data.

   ```python
   vader_predictions = [sia.polarity_scores(text)["compound"] for text in X_test]
   threshold = 0.2
   vader_classifications = [0 if score > threshold else 1 for score in vader_predictions]
   ```

   This part generates sentiment scores for each text in the test set and classifies them as positive or negative based on a threshold.

8. Evaluate the model.

   ```python
   accuracy = accuracy_score(y_test, vader_classifications)
   report_vader = classification_report(y_test, vader_classifications, zero_division='warn')
   ```

   This part calculates the accuracy and classification report for the predictions.

9. Specify the main execution block.

   ```python
   if __name__ == "__main__":
   ```

   This Python idiom ensures that the following code block runs only if this script is the main program. It provides flexibility, allowing the script to function both as a standalone program and as an imported module.

10. Create an infinite loop for continuous input.

    ```python
       while True:
        input_text = input("Enter the text for classification (type 'exit' to end): ")

          if input_text.lower() == 'exit':
             print("Exiting...")
             break
    ```

    This while loop runs indefinitely until it's explicitly broken. It lets the user continuously enter text for entity recognition until they decide to exit.

11. Analyze the text.

    ```python
            input_text_score = sia.polarity_scores(input_text)["compound"]
            input_text_classification = 0 if input_text_score > threshold else 1
    ```

12. Print the VADER Classification Report and the sentiment analysis.

    ```python
            print(f"Accuracy: {accuracy:.2f}")
            print("\nVADER Classification Report:")
            print(report_vader)

            print(f"\nTest Text (Positive): '{input_text}'")
            print(f"Predicted Sentiment: {'Positive' if input_text_classification == 0 else 'Negative'}")
    ```

13. Create `requirements.txt`. The sample application already contains the `requirements.txt` file to specify the necessary packages that the application imports. Open `requirements.txt` in a code or text editor to explore its contents.

    ```text
    # 01 sentiment_analysis
    nltk==3.6.5

    ...

    # 03 text_classification
    scikit-learn==1.3.2

    ...
    ```

    Both the `nltk` and `scikit-learn` modules are required for the text classification application.

## [Explore the application environment](#explore-the-application-environment)

You'll use Docker to run the application in a container. Docker lets you containerize the application, providing a consistent and isolated environment for running it. This means the application will operate as intended within its Docker container, regardless of the underlying system differences.

To run the application in a container, a Dockerfile is required. A Dockerfile is a text document that contains all the commands you would call on the command line to assemble an image. An image is a read-only template with instructions for creating a Docker container.

The sample application already contains a `Dockerfile`. Open the `Dockerfile` in a code or text editor to explore its contents.

The following steps explain each part of the `Dockerfile`. For more details, see the [Dockerfile reference](/reference/dockerfile/).

1. Specify the base image.

   ```dockerfile
   FROM python:3.8-slim
   ```

   This command sets the foundation for the build. `python:3.8-slim` is a lightweight version of the Python 3.8 image, optimized for size and speed. Using this slim image reduces the overall size of your Docker image, leading to quicker downloads and less surface area for security vulnerabilities. This is particularly useful for a Python-based application where you might not need the full standard Python image.

2. Set the working directory.

   ```dockerfile
   WORKDIR /app
   ```

   `WORKDIR` sets the current working directory within the Docker image. By setting it to `/app`, you ensure that all subsequent commands in the Dockerfile (like `COPY` and `RUN`) are executed in this directory. This also helps in organizing your Docker image, as all application-related files are contained in a specific directory.

3. Copy the requirements file into the image.

   ```dockerfile
   COPY requirements.txt /app
   ```

   The `COPY` command transfers the `requirements.txt` file from your local machine into the Docker image. This file lists all Python dependencies required by the application. Copying it into the container lets the next command (`RUN pip install`) install these dependencies inside the image environment.

4. Install the Python dependencies in the image.

   ```dockerfile
   RUN pip install --no-cache-dir -r requirements.txt
   ```

   This line uses `pip`, Python's package installer, to install the packages listed in `requirements.txt`. The `--no-cache-dir` option disables the cache, which reduces the size of the Docker image by not storing the unnecessary cache data.

5. Run additional commands.

   ```dockerfile
   RUN python -m spacy download en_core_web_sm
   ```

   This step is specific to NLP applications that require the spaCy library. It downloads the `en_core_web_sm` model, which is a small English language model for spaCy. While not needed for this app, it's included for compatibility with other NLP applications that might use this Dockerfile.

6. Copy the application code into the image.

   ```dockerfile
   COPY *.py /app
   COPY entrypoint.sh /app
   ```

   These commands copy your Python scripts and the `entrypoint.sh` script into the image's `/app` directory. This is crucial because the container needs these scripts to run the application. The `entrypoint.sh` script is particularly important as it dictates how the application starts inside the container.

7. Set permissions for the `entrypoint.sh` script.

   ```dockerfile
   RUN chmod +x /app/entrypoint.sh
   ```

   This command modifies the file permissions of `entrypoint.sh`, making it executable. This step is necessary to ensure that the Docker container can run this script to start the application.

8. Set the entry point.

   ```dockerfile
   ENTRYPOINT ["/app/entrypoint.sh"]
   ```

   The `ENTRYPOINT` instruction configures the container to run `entrypoint.sh` as its default executable. This means that when the container starts, it automatically executes the script.

   You can explore the `entrypoint.sh` script by opening it in a code or text editor. As the sample contains several applications, the script lets you specify which application to run when the container starts.

## [Run the application](#run-the-application)

To run the application using Docker:

1. Build the image.

   In a terminal, run the following command inside the directory of where the `Dockerfile` is located.

   ```console
   $ docker build -t basic-nlp .
   ```

   ```console
   $ docker run -it basic-nlp 03_text_classification.py
   ```

   The following is a break down of the command:

   * `docker run`: This is the primary command used to run a new container from a Docker image.

   * `-it`: This is a combination of two options:

     * `-i` or `--interactive`: This keeps the standard input (STDIN) open even if not attached. It lets the container remain running in the foreground and be interactive.
     * `-t` or `--tty`: This allocates a pseudo-TTY, essentially simulating a terminal, like a command prompt or a shell. It's what lets you interact with the application inside the container.

   * `basic-nlp`: This specifies the name of the Docker image to use for creating the container. In this case, it's the image named `basic-nlp` that you created with the `docker build` command.

   * `03_text_classification.py`: This is the script you want to run inside the Docker container. It gets passed to the `entrypoint.sh` script, which runs it when the container starts.

   For more details, see the [docker run CLI reference](/reference/cli/docker/container/run/).

   > Note
   >
   > For Windows users, you may get an error when running the container. Verify that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), then rebuild the image. For more details, see \[Avoid unexpected syntax errors, use Unix style line endings for files in containers]\(/desktop/troubleshoot-and-support/troubleshoot/topics/#Unexpected-syntax-errors-use-Unix-style-line endings-for-files-in-containers).

   You will see the following in your console after the container starts.

   ```console
   Enter the text for classification (type 'exit' to end):
   ```

3. Test the application.

   Enter some text to get the text classification.

   ```console
   Enter the text for classification (type 'exit' to end): I love containers!
   Accuracy: 1.00

   VADER Classification Report:
                 precision    recall  f1-score   support

              0       1.00      1.00      1.00         1
              1       1.00      1.00      1.00         1

       accuracy                           1.00         2
      macro avg       1.00      1.00      1.00         2
   weighted avg       1.00      1.00      1.00         2

   Test Text (Positive): 'I love containers!'
   Predicted Sentiment: Positive
   ```

## [Summary](#summary)

In this guide, you learned how to build and run a text classification application. You learned how to build the application using Python with scikit-learn and NLTK. Then you learned how to set up the environment and run the application using Docker.

Related information:

* [Docker CLI reference](/reference/cli/docker/)
* [Dockerfile reference](/reference/dockerfile/)
* [Natural Language Toolkit](https://www.nltk.org/)
* [Python documentation](https://docs.python.org/3/)
* [scikit-learn](https://scikit-learn.org/)

## [Next steps](#next-steps)

Explore more [natural language processing guides](https://docs.docker.com/guides/).

----
url: https://docs.docker.com/engine/storage/volumes/
----

# Volumes

***

Table of contents

***

Volumes are persistent data stores for containers, created and managed by Docker. You can create a volume explicitly using the `docker volume create` command, or Docker can create a volume during container or service creation.

When you create a volume, it's stored within a directory on the Docker host. When you mount the volume into a container, this directory is what's mounted into the container. This is similar to the way that bind mounts work, except that volumes are managed by Docker and are isolated from the core functionality of the host machine.

## [When to use volumes](#when-to-use-volumes)

Volumes are the preferred mechanism for persisting data generated by and used by Docker containers. While [bind mounts](https://docs.docker.com/engine/storage/bind-mounts/) are dependent on the directory structure and OS of the host machine, volumes are completely managed by Docker. Volumes are a good choice for the following use cases:

* Volumes are easier to back up or migrate than bind mounts.
* You can manage volumes using Docker CLI commands or the Docker API.
* Volumes work on both Linux and Windows containers.
* Volumes can be more safely shared among multiple containers.
* New volumes can have their content pre-populated by a container or build.
* When your application requires high-performance I/O.

Volumes are not a good choice if you need to access the files from the host, as the volume is completely managed by Docker. Use [bind mounts](https://docs.docker.com/engine/storage/bind-mounts/) if you need to access files or directories from both containers and the host.

Volumes are often a better choice than writing data directly to a container, because a volume doesn't increase the size of the containers using it. Using a volume is also faster; writing into a container's writable layer requires a [storage driver](https://docs.docker.com/engine/storage/drivers/) to manage the filesystem. The storage driver provides a union filesystem, using the Linux kernel. This extra abstraction reduces performance as compared to using volumes, which write directly to the host filesystem.

If your container generates non-persistent state data, consider using a [tmpfs mount](https://docs.docker.com/engine/storage/tmpfs/) to avoid storing the data anywhere permanently, and to increase the container's performance by avoiding writing into the container's writable layer.

Volumes use `rprivate` (recursive private) bind propagation, and bind propagation isn't configurable for volumes.

## [A volume's lifecycle](#a-volumes-lifecycle)

A volume's contents exist outside the lifecycle of a given container. When a container is destroyed, the writable layer is destroyed with it. Using a volume ensures that the data is persisted even if the container using it is removed.

A given volume can be mounted into multiple containers simultaneously. When no running container is using a volume, the volume is still available to Docker and isn't removed automatically. You can remove unused volumes using `docker volume prune`.

## [Mounting a volume over existing data](#mounting-a-volume-over-existing-data)

If you mount a *non-empty volume* into a directory in the container in which files or directories exist, the pre-existing files are obscured by the mount. This is similar to if you were to save files into `/mnt` on a Linux host, and then mounted a USB drive into `/mnt`. The contents of `/mnt` would be obscured by the contents of the USB drive until the USB drive was unmounted.

With containers, there's no straightforward way of removing a mount to reveal the obscured files again. Your best option is to recreate the container without the mount.

If you mount an *empty volume* into a directory in the container in which files or directories exist, these files or directories are propagated (copied) into the volume by default. Similarly, if you start a container and specify a volume which does not already exist, an empty volume is created for you. This is a good way to pre-populate data that another container needs.

To prevent Docker from copying a container's pre-existing files into an empty volume, use the `volume-nocopy` option, see [Options for --mount](#options-for---mount).

## [Named and anonymous volumes](#named-and-anonymous-volumes)

A volume may be named or anonymous. Anonymous volumes are given a random name that's guaranteed to be unique within a given Docker host. Just like named volumes, anonymous volumes persist even if you remove the container that uses them, except if you use the `--rm` flag when creating the container, in which case the anonymous volume associated with the container is destroyed. See [Remove anonymous volumes](https://docs.docker.com/engine/storage/volumes/#remove-anonymous-volumes).

If you create multiple containers consecutively that each use anonymous volumes, each container creates its own volume. Anonymous volumes aren't reused or shared between containers automatically. To share an anonymous volume between two or more containers, you must mount the anonymous volume using the random volume ID.

## [Syntax](#syntax)

To mount a volume with the `docker run` command, you can use either the `--mount` or `--volume` flag.

```console
$ docker run --mount type=volume,src=<volume-name>,dst=<mount-path>
$ docker run --volume <volume-name>:<mount-path>
```

In general, `--mount` is preferred. The main difference is that the `--mount` flag is more explicit and supports all the available options.

You must use `--mount` if you want to:

* Specify [volume driver options](#use-a-volume-driver)
* Mount a [volume subdirectory](#mount-a-volume-subdirectory)
* Mount a volume into a Swarm service

### [Options for --mount](#options-for---mount)

The `--mount` flag consists of multiple key-value pairs, separated by commas and each consisting of a `<key>=<value>` tuple. The order of the keys isn't significant.

```console
$ docker run --mount type=volume[,src=<volume-name>],dst=<mount-path>[,<key>=<value>...]
```

Valid options for `--mount type=volume` include:

| Option                         | Description                                                                                                                                                                                                                     |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`, `src`                | The source of the mount. For named volumes, this is the name of the volume. For anonymous volumes, this field is omitted.                                                                                                       |
| `destination`, `dst`, `target` | The path where the file or directory is mounted in the container.                                                                                                                                                               |
| `volume-subpath`               | A path to a subdirectory within the volume to mount into the container. The subdirectory must exist in the volume before the volume is mounted to a container. See [Mount a volume subdirectory](#mount-a-volume-subdirectory). |
| `readonly`, `ro`               | If present, causes the volume to be [mounted into the container as read-only](#use-a-read-only-volume).                                                                                                                         |
| `volume-nocopy`                | If present, data at the destination isn't copied into the volume if the volume is empty. By default, content at the target destination gets copied into a mounted volume if empty.                                              |
| `volume-opt`                   | Can be specified more than once, takes a key-value pair consisting of the option name and its value.                                                                                                                            |

Example

```console
$ docker run --mount type=volume,src=myvolume,dst=/data,ro,volume-subpath=/foo
```

### [Options for --volume](#options-for---volume)

The `--volume` or `-v` flag consists of three fields, separated by colon characters (`:`). The fields must be in the correct order.

```console
$ docker run -v [<volume-name>:]<mount-path>[:opts]
```

In the case of named volumes, the first field is the name of the volume, and is unique on a given host machine. For anonymous volumes, the first field is omitted. The second field is the path where the file or directory is mounted in the container.

The third field is optional, and is a comma-separated list of options. Valid options for `--volume` with a data volume include:

| Option           | Description                                                                                                                                                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `readonly`, `ro` | If present, causes the volume to be [mounted into the container as read-only](#use-a-read-only-volume).                                                                            |
| `volume-nocopy`  | If present, data at the destination isn't copied into the volume if the volume is empty. By default, content at the target destination gets copied into a mounted volume if empty. |

Example

```console
$ docker run -v myvolume:/data:ro
```

## [Create and manage volumes](#create-and-manage-volumes)

Unlike a bind mount, you can create and manage volumes outside the scope of any container.

Create a volume:

```console
$ docker volume create my-vol
```

List volumes:

```console
$ docker volume ls

local               my-vol
```

Inspect a volume:

```console
$ docker volume inspect my-vol
[
    {
        "Driver": "local",
        "Labels": {},
        "Mountpoint": "/var/lib/docker/volumes/my-vol/_data",
        "Name": "my-vol",
        "Options": {},
        "Scope": "local"
    }
]
```

Remove a volume:

```console
$ docker volume rm my-vol
```

## [Start a container with a volume](#start-a-container-with-a-volume)

If you start a container with a volume that doesn't yet exist, Docker creates the volume for you. The following example mounts the volume `myvol2` into `/app/` in the container.

The following `-v` and `--mount` examples produce the same result. You can't run them both unless you remove the `devtest` container and the `myvol2` volume after running the first one.

```console
$ docker run -d \
  --name devtest \
  --mount source=myvol2,target=/app \
  nginx:latest
```

```console
$ docker run -d \
  --name devtest \
  -v myvol2:/app \
  nginx:latest
```

Use `docker inspect devtest` to verify that Docker created the volume and it mounted correctly. Look for the `Mounts` section:

```json
"Mounts": [
    {
        "Type": "volume",
        "Name": "myvol2",
        "Source": "/var/lib/docker/volumes/myvol2/_data",
        "Destination": "/app",
        "Driver": "local",
        "Mode": "",
        "RW": true,
        "Propagation": ""
    }
],
```

This shows that the mount is a volume, it shows the correct source and destination, and that the mount is read-write.

Stop the container and remove the volume. Note volume removal is a separate step.

```console
$ docker container stop devtest

$ docker container rm devtest

$ docker volume rm myvol2
```

## [Use a volume with Docker Compose](#use-a-volume-with-docker-compose)

The following example shows a single Docker Compose service with a volume:

```yaml
services:
  frontend:
    image: node:lts
    volumes:
      - myapp:/home/node/app
volumes:
  myapp:
```

Running `docker compose up` for the first time creates a volume. Docker reuses the same volume when you run the command subsequently.

You can create a volume directly outside of Compose using `docker volume create` and then reference it inside `compose.yaml` as follows:

```yaml
services:
  frontend:
    image: node:lts
    volumes:
      - myapp:/home/node/app
volumes:
  myapp:
    external: true
```

For more information about using volumes with Compose, refer to the [Volumes](https://docs.docker.com/reference/compose-file/volumes/) section in the Compose specification.

### [Start a service with volumes](#start-a-service-with-volumes)

When you start a service and define a volume, each service container uses its own local volume. None of the containers can share this data if you use the `local` volume driver. However, some volume drivers do support shared storage.

The following example starts an `nginx` service with four replicas, each of which uses a local volume called `myvol2`.

```console
$ docker service create -d \
  --replicas=4 \
  --name devtest-service \
  --mount source=myvol2,target=/app \
  nginx:latest
```

Use `docker service ps devtest-service` to verify that the service is running:

```console
$ docker service ps devtest-service

ID                  NAME                IMAGE               NODE                DESIRED STATE       CURRENT STATE            ERROR               PORTS
4d7oz1j85wwn        devtest-service.1   nginx:latest        moby                Running             Running 14 seconds ago
```

You can remove the service to stop the running tasks:

```console
$ docker service rm devtest-service
```

Removing the service doesn't remove any volumes created by the service. Volume removal is a separate step.

### [Populate a volume using a container](#populate-a-volume-using-a-container)

If you start a container which creates a new volume, and the container has files or directories in the directory to be mounted such as `/app/`, Docker copies the directory's contents into the volume. The container then mounts and uses the volume, and other containers which use the volume also have access to the pre-populated content.

To show this, the following example starts an `nginx` container and populates the new volume `nginx-vol` with the contents of the container's `/usr/share/nginx/html` directory. This is where Nginx stores its default HTML content.

The `--mount` and `-v` examples have the same end result.

```console
$ docker run -d \
  --name=nginxtest \
  --mount source=nginx-vol,destination=/usr/share/nginx/html \
  nginx:latest
```

```console
$ docker run -d \
  --name=nginxtest \
  -v nginx-vol:/usr/share/nginx/html \
  nginx:latest
```

After running either of these examples, run the following commands to clean up the containers and volumes. Note volume removal is a separate step.

```console
$ docker container stop nginxtest

$ docker container rm nginxtest

$ docker volume rm nginx-vol
```

## [Use a read-only volume](#use-a-read-only-volume)

For some development applications, the container needs to write into the bind mount so that changes are propagated back to the Docker host. At other times, the container only needs read access to the data. Multiple containers can mount the same volume. You can simultaneously mount a single volume as `read-write` for some containers and as `read-only` for others.

The following example changes the previous one. It mounts the directory as a read-only volume, by adding `ro` to the (empty by default) list of options, after the mount point within the container. Where multiple options are present, you can separate them using commas.

The `--mount` and `-v` examples have the same result.

```console
$ docker run -d \
  --name=nginxtest \
  --mount source=nginx-vol,destination=/usr/share/nginx/html,readonly \
  nginx:latest
```

```console
$ docker run -d \
  --name=nginxtest \
  -v nginx-vol:/usr/share/nginx/html:ro \
  nginx:latest
```

Use `docker inspect nginxtest` to verify that Docker created the read-only mount correctly. Look for the `Mounts` section:

```json
"Mounts": [
    {
        "Type": "volume",
        "Name": "nginx-vol",
        "Source": "/var/lib/docker/volumes/nginx-vol/_data",
        "Destination": "/usr/share/nginx/html",
        "Driver": "local",
        "Mode": "",
        "RW": false,
        "Propagation": ""
    }
],
```

Stop and remove the container, and remove the volume. Volume removal is a separate step.

```console
$ docker container stop nginxtest

$ docker container rm nginxtest

$ docker volume rm nginx-vol
```

## [Mount a volume subdirectory](#mount-a-volume-subdirectory)

When you mount a volume to a container, you can specify a subdirectory of the volume to use, with the `volume-subpath` parameter for the `--mount` flag. The subdirectory that you specify must exist in the volume before you attempt to mount it into a container; if it doesn't exist, the mount fails.

Specifying `volume-subpath` is useful if you only want to share a specific portion of a volume with a container. Say for example that you have multiple containers running and you want to store logs from each container in a shared volume. You can create a subdirectory for each container in the shared volume, and mount the subdirectory to the container.

The following example creates a `logs` volume and initiates the subdirectories `app1` and `app2` in the volume. It then starts two containers and mounts one of the subdirectories of the `logs` volume to each container. This example assumes that the processes in the containers write their logs to `/var/log/app1` and `/var/log/app2`.

```console
$ docker volume create logs
$ docker run --rm \
  --mount src=logs,dst=/logs \
  alpine mkdir -p /logs/app1 /logs/app2
$ docker run -d \
  --name=app1 \
  --mount src=logs,dst=/var/log/app1,volume-subpath=app1 \
  app1:latest
$ docker run -d \
  --name=app2 \
  --mount src=logs,dst=/var/log/app2,volume-subpath=app2 \
  app2:latest
```

With this setup, the containers write their logs to separate subdirectories of the `logs` volume. The containers can't access the other container's logs.

## [Share data between machines](#share-data-between-machines)

When building fault-tolerant applications, you may need to configure multiple replicas of the same service to have access to the same files.

There are several ways to achieve this when developing your applications. One is to add logic to your application to store files on a cloud object storage system like Amazon S3. Another is to create volumes with a driver that supports writing files to an external storage system like NFS or Amazon S3.

Volume drivers let you abstract the underlying storage system from the application logic. For example, if your services use a volume with an NFS driver, you can update the services to use a different driver. For example, to store data in the cloud, without changing the application logic.

## [Use a volume driver](#use-a-volume-driver)

When you create a volume using `docker volume create`, or when you start a container which uses a not-yet-created volume, you can specify a volume driver. The following examples use the `rclone/docker-volume-rclone` volume driver, first when creating a standalone volume, and then when starting a container which creates a new volume.

> Note
>
> If your volume driver accepts a comma-separated list as an option, you must escape the value from the outer CSV parser. To escape a `volume-opt`, surround it with double quotes (`"`) and surround the entire mount parameter with single quotes (`'`).
>
> For example, the `local` driver accepts mount options as a comma-separated list in the `o` parameter. This example shows the correct way to escape the list.
>
> ```console
> $ docker service create \
>  --mount 'type=volume,src=<VOLUME-NAME>,dst=<CONTAINER-PATH>,volume-driver=local,volume-opt=type=nfs,volume-opt=device=<nfs-server>:<nfs-path>,"volume-opt=o=addr=<nfs-address>,vers=4,soft,timeo=180,bg,tcp,rw"'
>  --name myservice \
>  IMAGE
> ```

### [Initial setup](#initial-setup)

The following example assumes that you have two nodes, the first of which is a Docker host and can connect to the second node using SSH.

On the Docker host, install the `rclone/docker-volume-rclone` plugin:

```console
$ docker plugin install --grant-all-permissions rclone/docker-volume-rclone --aliases rclone
```

### [Create a volume using a volume driver](#create-a-volume-using-a-volume-driver)

This example mounts the `/remote` directory on host `1.2.3.4` into a volume named `rclonevolume`. Each volume driver may have zero or more configurable options, you specify each of them using an `-o` flag.

```console
$ docker volume create \
  -d rclone \
  --name rclonevolume \
  -o type=sftp \
  -o path=remote \
  -o sftp-host=1.2.3.4 \
  -o sftp-user=user \
  -o "sftp-password=$(cat file_containing_password_for_remote_host)"
```

This volume can now be mounted into containers.

### [Start a container which creates a volume using a volume driver](#start-a-container-which-creates-a-volume-using-a-volume-driver)

> Note
>
> If the volume driver requires you to pass any options, you must use the `--mount` flag to mount the volume, and not `-v`.

```console
$ docker run -d \
  --name rclone-container \
  --mount type=volume,volume-driver=rclone,src=rclonevolume,target=/app,volume-opt=type=sftp,volume-opt=path=remote, volume-opt=sftp-host=1.2.3.4,volume-opt=sftp-user=user,volume-opt=-o "sftp-password=$(cat file_containing_password_for_remote_host)" \
  nginx:latest
```

### [Create a service which creates an NFS volume](#create-a-service-which-creates-an-nfs-volume)

The following example shows how you can create an NFS volume when creating a service. It uses `10.0.0.10` as the NFS server and `/var/docker-nfs` as the exported directory on the NFS server. Note that the volume driver specified is `local`.

#### [NFSv3](#nfsv3)

```console
$ docker service create -d \
  --name nfs-service \
  --mount 'type=volume,source=nfsvolume,target=/app,volume-driver=local,volume-opt=type=nfs,volume-opt=device=:/var/docker-nfs,volume-opt=o=addr=10.0.0.10' \
  nginx:latest
```

#### [NFSv4](#nfsv4)

```console
$ docker service create -d \
    --name nfs-service \
    --mount 'type=volume,source=nfsvolume,target=/app,volume-driver=local,volume-opt=type=nfs,volume-opt=device=:/var/docker-nfs,"volume-opt=o=addr=10.0.0.10,rw,nfsvers=4,async"' \
    nginx:latest
```

### [Create CIFS/Samba volumes](#create-cifssamba-volumes)

You can mount a Samba share directly in Docker without configuring a mount point on your host.

```console
$ docker volume create \
	--driver local \
	--opt type=cifs \
	--opt device=//uxxxxx.your-server.de/backup \
	--opt o=addr=uxxxxx.your-server.de,username=uxxxxxxx,password=*****,file_mode=0777,dir_mode=0777 \
	--name cifs-volume
```

The `addr` option is required if you specify a hostname instead of an IP. This lets Docker perform the hostname lookup.

### [Block storage devices](#block-storage-devices)

You can mount a block storage device, such as an external drive or a drive partition, to a container. The following example shows how to create and use a file as a block storage device, and how to mount the block device as a container volume.

> Important
>
> The following procedure is only an example. The solution illustrated here isn't recommended as a general practice. Don't attempt this approach unless you're confident about what you're doing.

#### [How mounting block devices works](#how-mounting-block-devices-works)

Under the hood, the `--mount` flag using the `local` storage driver invokes the Linux `mount` syscall and forwards the options you pass to it unaltered. Docker doesn't implement any additional functionality on top of the native mount features supported by the Linux kernel.

If you're familiar with the [Linux `mount` command](https://man7.org/linux/man-pages/man8/mount.8.html), you can think of the `--mount` options as forwarded to the `mount` command in the following manner:

```console
$ mount -t <mount.volume-opt.type> <mount.volume-opt.device> <mount.dst> -o <mount.volume-opts.o>
```

To explain this further, consider the following `mount` command example. This command mounts the `/dev/loop5` device to the path `/external-drive` on the system.

```console
$ mount -t ext4 /dev/loop5 /external-drive
```

The following `docker run` command achieves a similar result, from the point of view of the container being run. Running a container with this `--mount` option sets up the mount in the same way as if you had executed the `mount` command from the previous example.

```console
$ docker run \
  --mount='type=volume,dst=/external-drive,volume-driver=local,volume-opt=device=/dev/loop5,volume-opt=type=ext4'
```

You can't run the `mount` command inside the container directly, because the container is unable to access the `/dev/loop5` device. That's why the `docker run` command uses the `--mount` option.

#### [Example: Mounting a block device in a container](#example-mounting-a-block-device-in-a-container)

The following steps create an `ext4` filesystem and mounts it into a container. The filesystem support of your system depends on the version of the Linux kernel you are using.

1. Create a file and allocate some space to it:

   ```console
   $ fallocate -l 1G disk.raw
   ```

2. Build a filesystem onto the `disk.raw` file:

   ```console
   $ mkfs.ext4 disk.raw
   ```

3. Create a loop device:

   ```console
   $ losetup -f --show disk.raw
   /dev/loop5
   ```

   > Note
   >
   > `losetup` creates an ephemeral loop device that's removed after system reboot, or manually removed with `losetup -d`.

4. Run a container that mounts the loop device as a volume:

   ```console
   $ docker run -it --rm \
     --mount='type=volume,dst=/external-drive,volume-driver=local,volume-opt=device=/dev/loop5,volume-opt=type=ext4' \
     ubuntu bash
   ```

   When the container starts, the path `/external-drive` mounts the `disk.raw` file from the host filesystem as a block device.

5. When you're done, and the device is unmounted from the container, detach the loop device to remove the device from the host system:

   ```console
   $ losetup -d /dev/loop5
   ```

## [Back up, restore, or migrate data volumes](#back-up-restore-or-migrate-data-volumes)

Volumes are useful for backups, restores, and migrations. Use the `--volumes-from` flag to create a new container that mounts that volume.

### [Back up a volume](#back-up-a-volume)

For example, create a new container named `dbstore`:

```console
$ docker run -v /dbdata --name dbstore ubuntu /bin/bash
```

In the next command:

* Launch a new container and mount the volume from the `dbstore` container
* Mount a local host directory as `/backup`
* Pass a command that tars the contents of the `dbdata` volume to a `backup.tar` file inside the `/backup` directory.

```console
$ docker run --rm --volumes-from dbstore -v $(pwd):/backup ubuntu tar cvf /backup/backup.tar /dbdata
```

When the command completes and the container stops, it creates a backup of the `dbdata` volume.

### [Restore volume from a backup](#restore-volume-from-a-backup)

With the backup just created, you can restore it to the same container, or to another container that you created elsewhere.

For example, create a new container named `dbstore2`:

```console
$ docker run -v /dbdata --name dbstore2 ubuntu /bin/bash
```

Then, un-tar the backup file in the new container’s data volume:

```console
$ docker run --rm --volumes-from dbstore2 -v $(pwd):/backup ubuntu bash -c "cd /dbdata && tar xvf /backup/backup.tar --strip 1"
```

You can use these techniques to automate backup, migration, and restore testing using your preferred tools.

## [Remove volumes](#remove-volumes)

A Docker data volume persists after you delete a container. There are two types of volumes to consider:

* Named volumes have a specific name, for example, `awesome:/bar`, where `awesome` is the name.
* Anonymous volumes have no specific name. Therefore, when the container is deleted, you can instruct the Docker Engine daemon to remove them.

### [Remove anonymous volumes](#remove-anonymous-volumes)

To automatically remove anonymous volumes, use the `--rm` option. For example, this command creates an anonymous `/foo` volume. When you remove the container, the Docker Engine removes the `/foo` volume but not the `awesome` volume.

The `--rm` option works with both foreground and detached (`-d`) containers. The anonymous volumes are cleaned up when the container exits.

```console
$ docker run --rm -v /foo -v awesome:/bar busybox top
```

> Note
>
> If another container binds the volumes with `--volumes-from`, the volume definitions are *copied* and the anonymous volume also stays after the first container is removed.

### [Remove all volumes](#remove-all-volumes)

To remove all unused volumes and free up space:

```console
$ docker volume prune
```

## [Next steps](#next-steps)

* Learn about [bind mounts](https://docs.docker.com/engine/storage/bind-mounts/).
* Learn about [tmpfs mounts](https://docs.docker.com/engine/storage/tmpfs/).
* Learn about [storage drivers](/engine/storage/drivers/).
* Learn about [third-party volume driver plugins](/engine/extend/legacy_plugins/).

----
url: https://docs.docker.com/engine/extend/plugins_logging/
----

# Docker log driver plugins

***

Table of contents

***

This document describes logging driver plugins for Docker.

Logging drivers enables users to forward container logs to another service for processing. Docker includes several logging drivers as built-ins, however can never hope to support all use-cases with built-in drivers. Plugins allow Docker to support a wide range of logging services without requiring to embed client libraries for these services in the main Docker codebase. See the [plugin documentation](https://docs.docker.com/engine/extend/legacy_plugins/) for more information.

## [Create a logging plugin](#create-a-logging-plugin)

The main interface for logging plugins uses the same JSON+HTTP RPC protocol used by other plugin types. See the [example](https://github.com/cpuguy83/docker-log-driver-test) plugin for a reference implementation of a logging plugin. The example wraps the built-in `jsonfilelog` log driver.

## [LogDriver protocol](#logdriver-protocol)

Logging plugins must register as a `LogDriver` during plugin activation. Once activated users can specify the plugin as a log driver.

There are two HTTP endpoints that logging plugins must implement:

### [`/LogDriver.StartLogging`](#logdriverstartlogging)

Signals to the plugin that a container is starting that the plugin should start receiving logs for.

Logs will be streamed over the defined file in the request. On Linux this file is a FIFO. Logging plugins are not currently supported on Windows.

Request:

```json
{
  "File": "/path/to/file/stream",
  "Info": {
          "ContainerID": "123456"
  }
}
```

`File` is the path to the log stream that needs to be consumed. Each call to `StartLogging` should provide a different file path, even if it's a container that the plugin has already received logs for prior. The file is created by Docker with a randomly generated name.

`Info` is details about the container that's being logged. This is fairly free-form, but is defined by the following struct definition:

```go
type Info struct {
	Config              map[string]string
	ContainerID         string
	ContainerName       string
	ContainerEntrypoint string
	ContainerArgs       []string
	ContainerImageID    string
	ContainerImageName  string
	ContainerCreated    time.Time
	ContainerEnv        []string
	ContainerLabels     map[string]string
	LogPath             string
	DaemonName          string
}
```

`ContainerID` will always be supplied with this struct, but other fields may be empty or missing.

Response:

```json
{
  "Err": ""
}
```

If an error occurred during this request, add an error message to the `Err` field in the response. If no error then you can either send an empty response (`{}`) or an empty value for the `Err` field.

The driver should at this point be consuming log messages from the passed in file. If messages are unconsumed, it may cause the container to block while trying to write to its stdio streams.

Log stream messages are encoded as protocol buffers. The protobuf definitions are in the [moby repository](https://github.com/moby/moby/blob/master/api/types/plugins/logdriver/entry.proto).

Since protocol buffers are not self-delimited you must decode them from the stream using the following stream format:

```text
[size][message]
```

Where `size` is a 4-byte big endian binary encoded uint32. `size` in this case defines the size of the next message. `message` is the actual log entry.

A reference golang implementation of a stream encoder/decoder can be found [here](https://github.com/docker/docker/blob/master/api/types/plugins/logdriver/io.go)

### [`/LogDriver.StopLogging`](#logdriverstoplogging)

Signals to the plugin to stop collecting logs from the defined file. Once a response is received, the file will be removed by Docker. You must make sure to collect all logs on the stream before responding to this request or risk losing log data.

Requests on this endpoint does not mean that the container has been removed only that it has stopped.

Request:

```json
{
  "File": "/path/to/file/stream"
}
```

Response:

```json
{
  "Err": ""
}
```

If an error occurred during this request, add an error message to the `Err` field in the response. If no error then you can either send an empty response (`{}`) or an empty value for the `Err` field.

## [Optional endpoints](#optional-endpoints)

Logging plugins can implement two extra logging endpoints:

### [`/LogDriver.Capabilities`](#logdrivercapabilities)

Defines the capabilities of the log driver. You must implement this endpoint for Docker to be able to take advantage of any of the defined capabilities.

Request:

```json
{}
```

Response:

```json
{
  "ReadLogs": true
}
```

Supported capabilities:

* `ReadLogs` - this tells Docker that the plugin is capable of reading back logs to clients. Plugins that report that they support `ReadLogs` must implement the `/LogDriver.ReadLogs` endpoint

### [`/LogDriver.ReadLogs`](#logdriverreadlogs)

Reads back logs to the client. This is used when `docker logs <container>` is called.

In order for Docker to use this endpoint, the plugin must specify as much when `/LogDriver.Capabilities` is called.

Request:

```json
{
  "ReadConfig": {},
  "Info": {
    "ContainerID": "123456"
  }
}
```

`ReadConfig` is the list of options for reading, it is defined with the following golang struct:

```go
type ReadConfig struct {
	Since  time.Time
	Tail   int
	Follow bool
}
```

* `Since` defines the oldest log that should be sent.
* `Tail` defines the number of lines to read (e.g. like the command `tail -n 10`)
* `Follow` signals that the client wants to stay attached to receive new log messages as they come in once the existing logs have been read.

`Info` is the same type defined in `/LogDriver.StartLogging`. It should be used to determine what set of logs to read.

Response:

```text
{{ log stream }}
```

The response should be the encoded log message using the same format as the messages that the plugin consumed from Docker.

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/config/
----

# docker mcp profile config

***

| Description | Update the configuration of a profile                                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Usage       | `docker mcp profile config <profile-id> [--set <config-arg1> <config-arg2> ...] [--get <config-key1> <config-key2> ...] [--del <config-arg1> <config-arg2> ...]` |

## [Description](#description)

Update the configuration of a profile

## [Options](#options)

| Option      | Default | Description                                                                                                            |
| ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `--del`     |         | Delete configuration values: (can be specified multiple times)                                                         |
| `--format`  | `human` | Supported: json, yaml, human.                                                                                          |
| `--get`     |         | Get configuration values: (can be specified multiple times)                                                            |
| `--get-all` |         | Get all configuration values                                                                                           |
| `--set`     |         | Set configuration values: = (repeatable). Value may be JSON to set typed values (arrays, numbers, booleans, objects).  |

----
url: https://docs.docker.com/guides/dex/
----

[Mocking OAuth services in testing with Dex](https://docs.docker.com/guides/dex/)

Mocking OAuth services in testing with Dex

App development Distributed systems

10 minutes

[« Back to all guides](/guides/)

# Mocking OAuth services in testing with Dex

***

Table of contents

***

Dex is an open-source OpenID Connect (OIDC) and OAuth 2.0 identity provider that can be configured to authenticate against various backend identity providers, such as LDAP, SAML, and OAuth. Running Dex in a Docker container allows developers to simulate an OAuth 2.0 server for testing and development purposes. This guide will walk you through setting up Dex as an OAuth mock server using Docker containers.

Nowadays OAuth is the preferred choice to authenticate in web services, the highest part of them give the possibility to access using popular OAuth services like GitHub, Google or Apple. Using OAuth guarantees a higher level of security and simplification since it is not necessary to create new profiles for each service. This means that, by allowing applications to access resources on behalf of users without sharing passwords, OAuth minimizes the risk of credential exposure.

In this guide, you'll learn how to:

* Use Docker to launch up a Dex container.
* Use mock OAuth in the GitHub Action (GHA) without relying on an external OAuth provider.

## [Using Dex with Docker](#using-dex-with-docker)

The official [Docker image for Dex](https://hub.docker.com/r/dexidp/dex/) provides a convenient way to deploy and manage Dex instances. Dex is available for various CPU architectures, including amd64, armv7, and arm64, ensuring compatibility with different devices and platforms. You can learn more about Dex standalone on the [Dex docs site](https://dexidp.io/docs/getting-started/).

### [Prerequisites](#prerequisites)

[Docker Compose](/compose/): Recommended for managing multi-container Docker applications.

### [Setting up Dex with Docker](#setting-up-dex-with-docker)

Begin by creating a directory for your Dex project:

```bash
mkdir dex-mock-server
cd dex-mock-server
```

Organize your project with the following structure:

```bash
dex-mock-server/
├── config.yaml
└── compose.yaml
```

Create the Dex Configuration File: The config.yaml file defines Dex's settings, including connectors, clients, and storage. For a mock server setup, you can use the following minimal configuration:

```yaml
# config.yaml
issuer: http://localhost:5556/dex
storage:
  type: memory
web:
  http: 0.0.0.0:5556
staticClients:
  - id: example-app
    redirectURIs:
      - 'http://localhost:5555/callback'
    name: 'Example App'
    secret: ZXhhbXBsZS1hcHAtc2VjcmV0
enablePasswordDB: true
staticPasswords:
  - email: "admin@example.com"
    hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
    username: "admin"
    userID: "1234"
```

Explanation:

* issuer: The public URL of Dex.

* storage: Using in-memory storage for simplicity.

* web: Dex will listen on port 5556.

* staticClients: Defines a client application (example-app) with its redirect URI and secret.

* enablePasswordDB: Enables static password authentication.

* staticPasswords: Defines a static user for authentication. The hash is a bcrypt hash of the password.

> Note
>
> Ensure the hash is a valid bcrypt hash of your desired password. You can generate this using tools like [bcrypt-generator.com](https://bcrypt-generator.com/). or use CLI tools like [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) like in this following example:`echo password | htpasswd -BinC 10 admin | cut -d: -f2`

With Docker Compose configured, start Dex:

```yaml
# compose.yaml

services:
  dex:
    image: dexidp/dex:latest
    container_name: dex
    ports:
      - "5556:5556"
    volumes:
      - ./config.yaml:/etc/dex/config.yaml
    command: ["dex", "serve", "/etc/dex/config.yaml"]
```

Now it is possible to run the container using the `docker compose` command.

```bash
docker compose up -d
```

This command will download the Dex Docker image (if not already available) and start the container in detached mode.

To verify that Dex is running, check the logs to ensure Dex started successfully:

```bash
docker compose logs -f dex
```

You should see output indicating that Dex is listening on the specified port.

### [Using Dex OAuth testing in GHA](#using-dex-oauth-testing-in-gha)

To test the OAuth flow, you'll need a client application configured to authenticate against Dex. One of the most typical use cases is to use it inside GitHub Actions. Since Dex supports mock authentication, you can predefine test users as suggested in the [docs](https://dexidp.io/docs). The `config.yaml` file should looks like:

```yaml
issuer: http://127.0.0.1:5556/dex

storage:
  type: memory

web:
  http: 0.0.0.0:5556

oauth2:
  skipApprovalScreen: true

staticClients:
  - name: TestClient
    id: client_test_id
    secret: client_test_secret
    redirectURIs:
      - http://{ip-your-app}/path/to/callback/ # example: http://localhost:5555/callback

connectors:
# mockCallback connector always returns the user 'kilgore@kilgore.trout'.
- type: mockCallback
  id: mock
  name: Mock
```

Now you can insert the Dex service inside your `~/.github/workflows/ci.yaml` file:

```yaml
[...]
jobs:
  test-oauth:
    runs-on: ubuntu-latest
    steps:
      - name: Install Dex
        run: |
          curl -L https://github.com/dexidp/dex/releases/download/v2.37.0/dex_linux_amd64 -o dex
          chmod +x dex

      - name: Start Dex Server
        run: |
          nohup ./dex serve config.yaml > dex.log 2>&1 &
          sleep 5  # Give Dex time to start
[...]
```

### [Conclusion](#conclusion)

By following this guide, you've set up Dex as an OAuth mock server using Docker. This setup is invaluable for testing and development, allowing you to simulate OAuth flows without relying on external identity providers. For more advanced configurations and integrations, refer to the [Dex documentation](https://dexidp.io/docs/).

----
url: https://docs.docker.com/enterprise/enterprise-deployment/dev-box/
----

# Docker Desktop in Microsoft Dev Box

***

Table of contents

***

Docker Desktop is available as a pre-configured image in the Microsoft Azure Marketplace for use with Microsoft Dev Box, allowing developers to quickly set up consistent development environments in the cloud.

Microsoft Dev Box provides cloud-based, pre-configured developer workstations that allow you to code, build, and test applications without configuring a local development environment. The Docker Desktop image for Microsoft Dev Box comes with Docker Desktop and its dependencies pre-installed, giving you a ready-to-use containerized development environment.

## [Key benefits](#key-benefits)

* Docker Desktop, WSL2, and dependencies pre-installed
* Identical environment for every team member
* More compute and storage than a typical local machine
* Session state persists between uses
* Works with your existing Docker subscription

## [Setup](#setup)

### [Prerequisites](#prerequisites)

* An Azure subscription

* Access to Microsoft Dev Box

* A Docker subscription (Pro, Team, or Business). You can use Docker Desktop in Microsoft Dev Box with any of the following subscription options:

  * An existing or new Docker subscription
  * A new Docker subscription purchased through Azure Marketplace
  * A Docker Business subscription with SSO configured for your organization

### [Set up Docker Desktop in Dev Box](#set-up-docker-desktop-in-dev-box)

1. Navigate to the [Docker Desktop for Microsoft Dev Box](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/dockerinc1694120899427.devbox_azuremachine?tab=Overview) listing in Azure Marketplace.
2. Select **Get It Now** to add the virtual machine image to your subscription.
3. Follow the Azure workflow to complete the setup.
4. Use the image to create VMs, assign to Dev Centers, or create Dev Box Pools according to your organization's setup.

### [Activate Docker Desktop](#activate-docker-desktop)

Once your Dev Box is provisioned with the Docker Desktop image:

1. Start your Dev Box instance.
2. Launch Docker Desktop.
3. Sign in with your Docker ID.

## [Support](#support)

For issues related to:

* Docker Desktop configuration, usage, or licensing: Create a support ticket through [Docker Support](https://hub.docker.com/support).
* Dev Box creation, Azure portal configuration, or networking: Contact Azure Support.

## [Limitations](#limitations)

* Microsoft Dev Box is only available on Windows 10 and 11 (Linux VMs are not supported).
* Performance may vary based on your Dev Box configuration and network conditions.

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/server/add/
----

# docker mcp catalog server add

***

| Description | Add MCP servers to a catalog                                                          |
| ----------- | ------------------------------------------------------------------------------------- |
| Usage       | `docker mcp catalog server add <oci-reference> [--server <ref1> --server <ref2> ...]` |

## [Description](#description)

Add MCP servers to a catalog using various URI schemes.

## [Options](#options)

| Option     | Default | Description                                                                                                                                                                                                        |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--server` |         | Server to include specified with a URI: https\:// (MCP Registry reference) or docker:// (Docker Image reference) or catalog:// (Catalog reference) or file:// (Local file path). Can be specified multiple times.  |

## [Examples](#examples)

# [Add servers from another catalog](#add-servers-from-another-catalog)

docker mcp catalog server add mcp/my-catalog:latest --server catalog://mcp/docker-mcp-catalog:latest/github

# [Add servers with OCI references](#add-servers-with-oci-references)

docker mcp catalog server add mcp/my-catalog:latest --server docker://my-server:latest

# [Add servers with MCP Registry references](#add-servers-with-mcp-registry-references)

docker mcp catalog server add mcp/my-catalog:latest --server <https://registry.modelcontextprotocol.io/v0/servers/71de5a2a-6cfb-4250-a196-f93080ecc860>

# [Mix server references](#mix-server-references)

docker mcp catalog server add mcp/my-catalog:latest --server catalog://mcp/docker-mcp-catalog:latest/github --server docker://my-server:latest

----
url: https://docs.docker.com/desktop/settings-and-maintenance/settings/
----

# Change your Docker Desktop settings

***

Table of contents

***

Customize Docker Desktop behavior and optimize performance and resource usage with Docker Desktop's settings.

To open **Settings** either:

* Select the Docker menu and then **Settings**
* Select the **Settings** icon from the Docker Desktop Dashboard.

You can also locate the `settings-store.json` file at:

* Mac: `~/Library/Group\ Containers/group.com.docker/settings-store.json`
* Windows: `C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json`
* Linux: `~/.docker/desktop/settings-store.json`

For information on enforcing settings at an organization level, see [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/settings-reference/).

## [General](#general)

Configure startup behavior, UI appearance, terminal preferences, and feature defaults for Docker Desktop.

| Setting                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                 | Default                  | Platform                       | Notes                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Start Docker Desktop when you sign in to your computer**   | Automatically start Docker Desktop when you sign in to your machine.                                                                                                                                                                                                                                                                                                                                                                        | Disabled                 | All                            | Recommended for frequent users.                                                                                                                                                                                                                                                                                                                |
| **Open Docker Dashboard when Docker Desktop starts**         | Automatically open the dashboard when starting Docker Desktop.                                                                                                                                                                                                                                                                                                                                                                              | Disabled                 | All                            |                                                                                                                                                                                                                                                                                                                                                |
| **Choose theme for Docker Desktop**                          | Apply a **Light** or **Dark** theme to Docker Desktop.                                                                                                                                                                                                                                                                                                                                                                                      | **Use system settings**. | All                            |                                                                                                                                                                                                                                                                                                                                                |
| **Configure shell completions**                              | Edits your shell configuration to enable word completion for commands, flags, and Docker objects when you press `<Tab>` in your terminal. For more information, see [Completion](https://docs.docker.com/engine/cli/completion/).                                                                                                                                                                                                           | Disabled                 | All                            |                                                                                                                                                                                                                                                                                                                                                |
| **Choose container terminal**                                | Sets which terminal opens when you select a container terminal. Use the integrated terminal to run commands in a running container from the Dashboard. For more information, see [Explore containers](https://docs.docker.com/desktop/use-desktop/container/).                                                                                                                                                                              | Disabled                 | All                            |                                                                                                                                                                                                                                                                                                                                                |
| **Enable Docker terminal**.                                  | Interact with your host machine and execute commands directly from Docker Desktop.                                                                                                                                                                                                                                                                                                                                                          | Disabled                 | All                            |                                                                                                                                                                                                                                                                                                                                                |
| **Enable Docker Debug by default**                           | Use Docker Debug by default opening the integrated terminal. For more information, see [Explore containers](https://docs.docker.com/desktop/use-desktop/container/#integrated-terminal).                                                                                                                                                                                                                                                    | Disabled                 | All                            |                                                                                                                                                                                                                                                                                                                                                |
| **Include VM in Time Machine backups**                       | Back up the Docker Desktop virtual machine.                                                                                                                                                                                                                                                                                                                                                                                                 | Disabled                 | Mac                            |                                                                                                                                                                                                                                                                                                                                                |
| **Use containerd for pulling and storing images**            | Uses containerd image store instead of classic image store. For more information, see [containerd image store](https://docs.docker.com/desktop/features/containerd/).                                                                                                                                                                                                                                                                       | Enabled                  | All                            |                                                                                                                                                                                                                                                                                                                                                |
| **Expose daemon on tcp\://localhost:2375 without TLS**       | Allow legacy clients to connect to the Docker daemon. Use with caution as exposing the daemon without TLS can result in remote code execution attacks.                                                                                                                                                                                                                                                                                      | Disabled                 | Windows (Hyper-V backend only) |                                                                                                                                                                                                                                                                                                                                                |
| **Use the WSL 2 based engine**                               | WSL 2 provides better performance than the Hyper-V backend. For more information, see [Docker Desktop WSL 2 backend](https://docs.docker.com/desktop/features/wsl/).                                                                                                                                                                                                                                                                        | Disabled                 | Windows                        |                                                                                                                                                                                                                                                                                                                                                |
| **Add \*.docker.internal to host file**                      | Adds internal DNS entries.                                                                                                                                                                                                                                                                                                                                                                                                                  | Enabled                  | Windows                        | Helps resolve Docker-internal domains                                                                                                                                                                                                                                                                                                          |
| **Choose Virtual Machine Manager (VMM)**                     | Choose the VMM for creating and managing the Docker Desktop Linux VM. For more information, see [Virtual Machine Manager](https://docs.docker.com/desktop/features/vmm/).                                                                                                                                                                                                                                                                   |                          | Mac                            | Select **Docker VMM** for the latest and most performant Hypervisor/Virtual Machine Manager. This option is available only on Apple Silicon Macs and is in Beta.                                                                                                                                                                               |
| **Choose file sharing implementation for your containers**   | Choose whether you want to share files using **VirtioFS**, **gRPC FUSE**, or **osxfs (Legacy)**                                                                                                                                                                                                                                                                                                                                             | **VirtioFS**             | Mac                            | Use VirtioFS for speedy file sharing. VirtioFS has reduced the time taken to complete filesystem operations by [up to 98%](https://github.com/docker/roadmap/issues/7#issuecomment-1044452206). It is the only file sharing implementation supported by Docker VMM.                                                                            |
| **Use Rosetta for x86\_64/amd64 emulation on Apple Silicon** | Accelerate x86/AMD64 binary emulation on Apple Silicon. This option is only available if you have selected **Apple Virtualization framework** as the Virtual Machine Manager.                                                                                                                                                                                                                                                               | Disabled                 | Mac                            |                                                                                                                                                                                                                                                                                                                                                |
| **Send usage statistics**                                    | Send diagnostics, crash reports, and usage data to Docker to improve and troubleshoot the application. Docker may periodically prompt you for more information.                                                                                                                                                                                                                                                                             | Enabled                  | All                            |                                                                                                                                                                                                                                                                                                                                                |
| **Use Enhanced Container Isolation**                         | Prevent containers from breaching the Linux VM. For more information, see [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/).                                                                                                                                                                                                                                       | Disabled                 | All                            | Must be signed in and have a Docker Business subscription.                                                                                                                                                                                                                                                                                     |
| **Show CLI hints**                                           | Display helpful CLI suggestions in terminal.                                                                                                                                                                                                                                                                                                                                                                                                | Enabled                  | All                            | Improves discoverability                                                                                                                                                                                                                                                                                                                       |
| **Enable Docker Scout image analysis**                       | Show a **Start analysis** button when inspecting an image, which analyzes the image with Docker Scout.                                                                                                                                                                                                                                                                                                                                      | Enabled                  | All                            |                                                                                                                                                                                                                                                                                                                                                |
| **Enable background SBOM indexing**                          | Automatically analyze images that you build or pull.                                                                                                                                                                                                                                                                                                                                                                                        | Disabled                 | All                            |                                                                                                                                                                                                                                                                                                                                                |
| **Automatically check configuration**                        | Regularly check your configuration to ensure no unexpected changes have been made by another application. Notifies you if changes are found with the option to restore the configuration directly from the notification. For more information, see the [FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/macfaqs/#why-do-i-keep-getting-a-notification-telling-me-an-application-has-changed-my-desktop-configurations). | Enabled                  | Mac                            | Docker Desktop checks if your setup, configured during installation, has been altered by external apps like Orbstack. Docker Desktop checks the symlinks of Docker binaries to `/usr/local/bin` and the symlink of the default Docker socket. Additionally, Docker Desktop ensures that the context is switched to `desktop-linux` on startup. |

## [Resources](#resources)

Control the CPU, memory, disk, file sharing, proxy, and network resources available to Docker Desktop.

### [Advanced](#advanced)

| Setting                 | Description                                                                                                                                                                                                                                     | Platform                    | Notes                                                                                                                                                                                                |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CPU limit**           | Specify the maximum number of CPUs to be used by Docker Desktop.                                                                                                                                                                                | Mac, Linux, Windows Hyper-V |                                                                                                                                                                                                      |
| **Memory limit**        | RAM allocated to the Docker VM                                                                                                                                                                                                                  | Mac, Linux, Windows Hyper-V | Defaults to 50% of your host's memory.                                                                                                                                                               |
| **Swap**                | Configure swap file size as needed.                                                                                                                                                                                                             | Mac, Linux, Windows Hyper-V | 1 GB default.                                                                                                                                                                                        |
| **Disk usage limit**    | Specify the maximum amount of disk space the engine can use.                                                                                                                                                                                    | Mac, Linux, Windows Hyper-V |                                                                                                                                                                                                      |
| **Disk image location** | Specify the location of the Linux volume where containers and images are stored. On the **Advanced** tab, you can limit resources available to the Docker Linux VM.                                                                             | Mac, Linux, Windows Hyper-V | You can also move the disk image to a different location. If you attempt to move a disk image to a location that already has one, you are asked if you want to use the existing image or replace it. |
| **Resource Saver**      | Enable or disable [Resource Saver mode](https://docs.docker.com/desktop/use-desktop/resource-saver/), which significantly reduces CPU and memory utilization on the host by automatically turning off the Linux VM when Docker Desktop is idle. | Mac, Linux, Windows Hyper-V | Restarts automatically when containers run. Restart may take 3–10 seconds.                                                                                                                           |

In WSL 2 mode, configure memory, CPU, and swap limits on the [WSL 2 utility VM](https://docs.microsoft.com/en-us/windows/wsl/wsl-config#configure-global-options-with-wslconfig).

> Tip
>
> If you feel Docker Desktop starting to get slow or you're running multi-container workloads, increase the memory and disk image space allocation.

### [File sharing](#file-sharing)

Use File sharing to allow local directories on your machine to be shared with Linux containers. This is especially useful for editing source code in an IDE on the host while running and testing the code in a container.

| Setting                      | Description                                                                                                                                                                                                                                                                                                     | Platform                    | Notes                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------------------------- |
| **Synchronized file shares** | Fast and flexible host-to-VM file sharing, enhancing bind mount performance through the use of synchronized filesystem caches. To learn more, see [Synchronized file share](https://docs.docker.com/desktop/features/synchronized-file-sharing/).                                                               | Mac, Linux, Windows Hyper-V | Available with Pro, Team, and Business subscriptions. |
| **Virtual file shares**      | Share local directories with Linux containers. By default the `/Users`, `/Volumes`, `/private`, `/tmp` and `/var/folders` directory are shared. If your project is outside this directory then it must be added to the list, otherwise you may get `Mounts denied` or `cannot start service` errors at runtime. | Mac, Linux, Windows Hyper-V |                                                       |

* Share only the directories that you need with the container. File sharing introduces overhead as any changes to the files on the host need to be notified to the Linux VM. Sharing too many files can lead to high CPU load and slow filesystem performance.
* Shared folders are designed to allow application code to be edited on the host while being executed in containers. For non-code items such as cache directories or databases, the performance will be much better if they are stored in the Linux VM, using a [data volume](https://docs.docker.com/engine/storage/volumes/) (named volume) or [data container](https://docs.docker.com/engine/storage/volumes/).
* If you share the whole of your home directory into a container, Mac may prompt you to give Docker access to personal areas of your home directory such as your Reminders or Downloads.
* By default, Mac file systems are case-insensitive while Linux is case-sensitive. On Linux, it is possible to create two separate files: `test` and `Test`, while on Mac these filenames would actually refer to the same underlying file. This can lead to problems where an app works correctly on a developer's machine (where the file contents are shared) but fails when run in Linux in production (where the file contents are distinct). To avoid this, Docker Desktop insists that all shared files are accessed as their original case. Therefore, if a file is created called `test`, it must be opened as `test`. Attempts to open `Test` will fail with the error "No such file or directory". Similarly, once a file called `test` is created, attempts to create a second file called `Test` will fail.

For more information, see [Volume mounting requires file sharing for any project directories outside of `/Users`](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/).

### [Proxies](#proxies)

Docker Desktop supports HTTP/HTTPS and SOCKS5 proxies. SOCKS5 requires a Business subscription.

To prevent developers from accidentally changing the proxy settings, see [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/#what-features-can-i-configure-with-settings-management).

#### [Docker Desktop proxy](#docker-desktop-proxy)

Used for signing in to Docker, pulling and pushing images, fetching artifacts during image builds, and reporting error diagnostics.

| Proxy mode               | Description                                                                                                                                                                                                                                                                  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **System proxy**         | Use the proxy configured on the host (static or Proxy Auto-Configuration (PAC)). Docker Desktop reads this automatically.                                                                                                                                                    |
| **No proxy**             | Connect directly without a proxy.                                                                                                                                                                                                                                            |
| **Manual configuration** | Enter a **Web Server (HTTP)** and **Secure Web Server (HTTPS)** URL manually. Use the format `http://proxy:port` or `https://proxy:port`. You can also specify hosts and domains that should bypass the proxy, for example: `registry-1.docker.com,*.docker.com,10.0.0.0/8`. |

> Note
>
> If you use a PAC file hosted on a web server, add the MIME type `application/x-ns-proxy-autoconfig` for the `.pac` extension. Without this, the PAC file may not parse correctly. See [Hardened Docker Desktop](https://docs.docker.com/enterprise/security/hardened-desktop/air-gapped-containers/#proxy-auto-configuration-files).

#### [Containers proxy](#containers-proxy)

Used for outbound traffic from running containers.

| Proxy mode               | Description                                                                                                                                                                                                                                                                  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Same as host proxy**   | Use the same proxy configuration as the Docker Desktop proxy.                                                                                                                                                                                                                |
| **System proxy**         | Use the proxy configured on the host.                                                                                                                                                                                                                                        |
| **No proxy**             | Connect directly without a proxy.                                                                                                                                                                                                                                            |
| **Manual configuration** | Enter a **Web Server (HTTP)** and **Secure Web Server (HTTPS)** URL manually. Use the format `http://proxy:port` or `https://proxy:port`. You can also specify hosts and domains that should bypass the proxy, for example: `registry-1.docker.com,*.docker.com,10.0.0.0/8`. |

> Note
>
> The HTTPS proxy used for image scanning is configured using the `HTTPS_PROXY` environment variable.

#### [Proxy authentication](#proxy-authentication)

| Method              | Behavior                                                                                                                                                                                                   | Notes                                                                                                                                                                                                                                                                               |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Basic**           | Docker Desktop prompts for credentials and caches them in the OS credential store.                                                                                                                         | Use an `https://` proxy URL to protect passwords in transit. Supports TLS 1.3.                                                                                                                                                                                                      |
| **Kerberos / NTLM** | Centralizes authentication — developers aren't prompted for credentials, reducing the risk of account lockouts. If the proxy returns multiple schemes in a 407 response, Docker Desktop defaults to Basic. | Requires a Business subscription. To enable Kerberos or NTLM proxy authentication you must pass the `--proxy-enable-kerberosntlm` installer flag during installation via the command line, and ensure your proxy server is properly configured for Kerberos or NTLM authentication. |

### [Network](#network)

> Note
>
> On Windows, the **Network** tab is not available in Windows container mode because Windows manages networking.

| Setting                           | Description                                                                                                                                                                                                      | Platform |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **Docker subnet**                 | Set a custom subnet to avoid conflicts with IPs in your environment. Docker Desktop uses a private IPv4 network for internal services, including a DNS server and HTTP proxy. Default: `192.168.65.0/24`.        | All      |
| **Use kernel networking for UDP** | Use a more efficient kernel networking path for UDP traffic. May not be compatible with VPN software.                                                                                                            | Mac      |
| **Enable host networking**        | Allows containers started with `--net=host` to use `localhost` to connect to TCP and UDP services on the host. Also allows host software to use `localhost` to connect to TCP and UDP services in the container. | Mac      |

On Windows and Mac, you can also set the default networking mode and DNS resolution behavior. For more information, see [Networking](https://docs.docker.com/desktop/features/networking/networking-how-tos/#network-how-tos-for-mac-and-windows).

### [WSL integration (Windows only)](#wsl-integration-windows-only)

| Setting                      | Description                                                           | Notes                                                                                                                                                 |
| ---------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| WSL distribution integration | Select which WSL 2 distributions have Docker WSL integration enabled. | Integration is enabled on your default WSL distribution by default. To change your default distribution, run `wsl --set-default <distribution name>`. |

For more details on configuring Docker Desktop to use WSL 2, see [Docker Desktop WSL 2 backend](https://docs.docker.com/desktop/features/wsl/).

## [Docker Engine](#docker-engine)

Configure the Docker daemon using a JSON configuration file.

The file is located at `$HOME/.docker/daemon.json`. Edit it directly in the Docker Desktop Dashboard or in a text editor.

To see the full list of possible configuration options, see the [dockerd command reference](/reference/cli/dockerd/).

## [Builders](#builders)

Use the **Builders** tab to inspect and manage builders in the Docker Desktop settings.

### [Inspect](#inspect)

To inspect builders, find the builder that you want to inspect and select the expand icon. You can only inspect active builders.

Inspecting an active builder shows:

* BuildKit version
* Status
* Driver type
* Supported capabilities and platforms
* Disk usage
* Endpoint address

### [Select a different builder](#select-a-different-builder)

The **Selected builder** section displays the selected builder. To select a different builder:

1. Find the builder that you want to use under **Available builders**
2. Open the drop-down menu next to the builder's name.
3. Select **Use** to switch to this builder.

Your build commands now use the selected builder by default.

### [Create a builder](#create-a-builder)

To create a builder, use the Docker CLI. See [Create a new builder](/build/builders/manage/#create-a-new-builder)

### [Remove a builder](#remove-a-builder)

You can remove a builder if:

* The builder isn't your [selected builder](/build/builders/#selected-builder)

* The builder isn't [associated with a Docker context](/build/builders/#default-builder).

  To remove builders associated with a Docker context, remove the context using the `docker context rm` command.

To remove a builder:

1. Find the builder that you want to remove under **Available builders**
2. Open the drop-down menu.
3. Select **Remove** to remove this builder.

If the builder uses the `docker-container` or `kubernetes` driver, the build cache is also removed, along with the builder.

### [Stop and start a builder](#stop-and-start-a-builder)

Builders that use the [`docker-container` driver](/build/builders/drivers/docker-container/) run the BuildKit daemon in a container. You can start and stop the BuildKit container using the drop-down menu.

Running a build automatically starts the container if it's stopped.

You can only start and stop builders using the `docker-container` driver.

## [AI](#ai)

From the AI tab, you can configure settings for:

* [Gordon](https://docs.docker.com/ai/gordon/), the AI-powered assistant that takes action on your Docker workflows.
* [Docker Model Runner](https://docs.docker.com/ai/model-runner/), which makes it easy to manage, run, and deploy AI models using Docker.

## [Kubernetes](#kubernetes)

> Note
>
> On Windows the **Kubernetes** tab is not available in Windows container mode.

Enable and configure the built-in standalone Kubernetes cluster for testing container deployments.

| Setting                               | Description                                                                                                                                                                   |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable Kubernetes**                 | Install and run a standalone Kubernetes server as a Docker container for testing deployments.                                                                                 |
| **Cluster provisioning method**       | Choose either **Kubeadm**, a single-node cluster with the version set by Docker Desktop, or **Kind**, a multi-node cluster where you can set the version and number of nodes. |
| **Show system containers (advanced)** | Show internal containers when using Docker commands.                                                                                                                          |
| **Reset Kubernetes cluster**          | Delete all stacks and Kubernetes resources.                                                                                                                                   |

For more information about using the Kubernetes integration with Docker Desktop, see [Explore the Kubernetes view](https://docs.docker.com/desktop/use-desktop/kubernetes/).

## [Software updates](#software-updates)

Manage how and when Docker Desktop checks for and downloads updates.

| Setting                             | Description                                                                                                                        | Default  |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **Automatically check for updates** | Notifies you of available updates in the Docker menu and Dashboard footer.                                                         | Enabled  |
| **Always download updates**         | Automatically download new versions of Docker Desktop in the background.                                                           | Disabled |
| **Automatically update components** | Update Docker Desktop components (such as Docker Compose, Docker Scout, and the Docker CLI) independently, without a full restart. | Enabled  |

## [Extensions](#extensions)

Enable Docker Extensions and control which extensions are available to install and run.

| Setting                                                              | Description                                               |
| -------------------------------------------------------------------- | --------------------------------------------------------- |
| **Enable Docker Extensions**                                         | Turn Docker Extensions on or off. Turned off by default.  |
| **Allow only extensions distributed through the Docker Marketplace** | Restrict extensions to Marketplace-approved sources only. |
| **Show Docker Extensions system containers**                         | Show containers used by Docker Extensions.                |

For more information about Docker extensions, see [Docker Extensions](https://docs.docker.com/extensions/).

## [Beta features](#beta-features)

Beta features provide access to future product functionality. These features are intended for testing and feedback only as they may change between releases without warning or remove them entirely from a future release. Beta features must not be used in production environments. Docker doesn't offer support for beta features.

You can also sign up to the [Developer Preview program](https://www.docker.com/community/get-involved/developer-preview/) from the **Beta features** tab.

For a list of current experimental features in the Docker CLI, see [Docker CLI Experimental features](https://github.com/docker/cli/blob/master/experimental/README.md).

## [Notifications](#notifications)

Choose which types of Docker Desktop notifications you want to receive.

| Notification type                     | Default                            |
| ------------------------------------- | ---------------------------------- |
| Status updates on tasks and processes | Enabled                            |
| Recommendations from Docker           | Enabled                            |
| Docker announcements                  | Enabled                            |
| Docker surveys                        | Enabled                            |
| Error notifications                   | Always Enabled (cannot be changed) |
| New releases                          | Always Enabled (cannot be changed) |

Notifications appear briefly in the lower-right of the Docker Desktop Dashboard, then move to the **Notifications** drawer, accessible from the top-right of the Dashboard.

## [Advanced (Mac only)](#advanced-mac-only)

Reconfigure CLI tool installation paths and privileged system permissions set during initial install.

| Setting                                        | Description                                                                                                                                                                                                                                                              | Notes                                                                                                                                      |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| CLI tools installation — **System**            | Install Docker CLI tools to `/usr/local/bin`.                                                                                                                                                                                                                            |                                                                                                                                            |
| CLI tools installation — **User**              | Install Docker CLI tools to `$HOME/.docker/bin`                                                                                                                                                                                                                          | Add `$HOME/.docker/bin` to your PATH by appending `export PATH=$PATH:~/.docker/bin` to `~/.bashrc` or `~/.zshrc`, then restart your shell. |
| **Allow the default Docker socket to be used** | Creates `/var/run/docker.sock` which some third party clients may use to communicate with Docker Desktop. For more information, see [permission requirements for macOS](https://docs.docker.com/desktop/setup/install/mac-permission-requirements/#installing-symlinks). | Requires password                                                                                                                          |
| **Allow privileged port mapping**              | Starts the privileged helper process which binds the ports that are between 1 and 1024. For more information, see [permission requirements for macOS](https://docs.docker.com/desktop/setup/install/mac-permission-requirements/#binding-privileged-ports).              | Requires password                                                                                                                          |

## [Docker Offload](#docker-offload)

Enable Docker Offload and configure idle timeout and GPU support for cloud-based workloads.

| Setting                   | Description                                                                                                                                                                                                                         | Notes                                        |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **Enable Docker Offload** | Run your containers in the cloud.                                                                                                                                                                                                   | Requires sign-in and an Offload subscription |
| **Idle timeout**          | Set the duration of time between no activity and Docker Offload entering idle mode. For details about idle timeout, see [Active and idle states](https://docs.docker.com/offload/configuration/#understand-active-and-idle-states). |                                              |
| **Enable GPU support**    | Let your workloads use cloud GPU if available.                                                                                                                                                                                      |                                              |

----
url: https://docs.docker.com/docker-hub/repos/manage/builds/setup/
----

# Set up automated builds

***

Table of contents

***

> Warning
>
> Docker Hub Automated Builds is a deprecated feature. It will be fully retired on April 1, 2027.

> Note
>
> Automated builds require a Docker Pro, Team, or Business subscription.

## [Configure automated builds](#configure-automated-builds)

You can configure repositories in Docker Hub so that they automatically build an image each time you push new code to your source provider. If you have [automated tests](https://docs.docker.com/docker-hub/repos/manage/builds/automated-testing/) configured, the new image is only pushed when the tests succeed.

1. In [Docker Hub](https://hub.docker.com), go to **My Hub** > **Repositories**, and select a repository to view its details.

2. Select the **Builds** tab.

3. Select either GitHub or Bitbucket to connect where the image's source code is stored.

   > Note
   >
   > You may be redirected to the settings page to [link the code repository service](https://docs.docker.com/docker-hub/repos/manage/builds/link-source/). Otherwise, if you are editing the build settings for an existing automated build, select **Configure automated builds**.

4. Select the **source repository** to build the Docker images from.

   > Note
   >
   > You might need to specify an organization or user from the source code provider. Once you select a user, source code repositories appear in the **Select repository** drop-down list.

5. Optional. Enable [autotests](https://docs.docker.com/docker-hub/repos/manage/builds/automated-testing/#enable-automated-tests-on-a-repository).

6. Review the default **Build Rules**.

   Build rules control what Docker Hub builds into images from the contents of the source code repository, and how the resulting images are tagged within the Docker repository.

   A default build rule is set up for you, which you can edit or delete. This default rule sets builds from the `Branch` in your source code repository called `master` or `main`, and creates a Docker image tagged with `latest`. For more information, see [set up build rules](#set-up-build-rules).

7. Optional. Select the **plus** icon to add and [configure more build rules](#set-up-build-rules).

8. For each branch or tag, enable or disable the **Autobuild** toggle.

   Only branches or tags with autobuild enabled are built, tested, and have the resulting image pushed to the repository. Branches with autobuild disabled are built for test purposes (if enabled at the repository level), but the built Docker image isn't pushed to the repository.

9. For each branch or tag, enable or disable the **Build Caching** toggle.

   [Build caching](https://docs.docker.com/build/building/best-practices/#leverage-build-cache) can save time if you are building a large image frequently or have many dependencies. Leave the build caching disabled to make sure all of your dependencies are resolved at build time, or if you have a large layer that's quicker to build locally.

10. Select **Save** to save the settings, or select **Save and build** to save and run an initial test.

    > Note
    >
    > A webhook is automatically added to your source code repository to notify Docker Hub on every push. Only pushes to branches that are listed as the source for one or more tags, trigger a build.

### [Set up build rules](#set-up-build-rules)

By default when you set up automated builds, a basic build rule is created for you. This default rule watches for changes to the `master` or `main` branch in your source code repository, and builds the `master` or `main` branch into a Docker image tagged with `latest`.

In the **Build Rules** section, enter one or more sources to build.

For each source:

* Select the **Source type** to build either a tag or a branch. This tells the build system what to look for in the source code repository.

* Enter the name of the **Source** branch or tag you want to build.

  The first time you configure automated builds, a default build rule is set up for you. This default set builds from the `Branch` in your source code called `master`, and creates a Docker image tagged with `latest`.

  You can also use a regex to select which source branches or tags to build. To learn more, see [regexes](#regexes-and-automated-builds).

* Enter the tag to apply to Docker images built from this source.

  If you configured a regex to select the source, you can reference the capture groups and use its result as part of the tag. To learn more, see [regexes](#regexes-and-automated-builds).

* Specify the **Dockerfile location** as a path relative to the root of the source code repository. If the Dockerfile is at the repository root, leave this path set to `/`.

> Note
>
> When Docker Hub pulls a branch from a source code repository, it performs a shallow clone - only the tip of the specified branch. Refer to [Advanced options for autobuild and autotest](https://docs.docker.com/docker-hub/repos/manage/builds/advanced/#source-repository-or-branch-clones) for more information.

### [Environment variables for builds](#environment-variables-for-builds)

You can set the values for environment variables used in your build processes when you configure an automated build. Add your build environment variables by selecting the **plus** icon next to the **Build environment variables** section, and then entering a variable name and the value.

When you set variable values from the Docker Hub UI, you can use them by the commands you set in `hooks` files. However, they're stored so that only users who have `admin` access to the Docker Hub repository can see their values. This means you can use them to store access tokens or other information that should remain secret.

> Note
>
> The variables set on the build configuration screen are used during the build processes only and shouldn't get confused with the environment values used by your service, for example to create service links.

## [Advanced automated build options](#advanced-automated-build-options)

At the minimum you need a build rule composed of a source branch, or tag, and a destination Docker tag to set up an automated build. You can also:

* Change where the build looks for the Dockerfile
* Set a path to the files the build should use (the build context)
* Set up multiple static tags or branches to build from
* Use regular expressions (regexes) to dynamically select source code to build and create dynamic tags

All of these options are available from the **Build configuration** screen for each repository. In [Docker Hub](https://hub.docker.com), select **My Hub** > **Repositories**, and select the name of the repository you want to edit. Select the **Builds** tab, and then select **Configure Automated builds**.

### [Tag and branch builds](#tag-and-branch-builds)

You can configure your automated builds so that pushes to specific branches or tags trigger a build.

1. In the **Build Rules** section, select the **plus** icon to add more sources to build.

2. Select the **Source type** to build either a tag or a branch.

   > Note
   >
   > This tells the build system what type of source to look for in the code repository.

3. Enter the name of the **Source** branch or tag you want to build.

   > Note
   >
   > You can enter a name, or use a regex to match which source branch or tag names to build. To learn more, see [regexes](#regexes-and-automated-builds).

4. Enter the tag to apply to Docker images built from this source.

   > Note
   >
   > If you configured a regex to select the source, you can reference the capture groups and use its result as part of the tag. To learn more, see [regexes](#regexes-and-automated-builds).

5. Repeat steps 2 through 4 for each new build rule you set up.

### [Set the build context and Dockerfile location](#set-the-build-context-and-dockerfile-location)

Depending on how you arrange the files in your source code repository, the files required to build your images may not be at the repository root. If that's the case, you can specify a path where the build looks for the files.

The build context is the path to the files needed for the build, relative to the root of the repository. Enter the path to these files in the **Build context** field. Enter `/` to set the build context as the root of the source code repository.

> Note
>
> If you delete the default path `/` from the **Build context** field and leave it blank, the build system uses the path to the Dockerfile as the build context. However, to avoid confusion it's recommended that you specify the complete path.

You can specify the **Dockerfile location** as a path relative to the build context. If the Dockerfile is at the root of the build context path, leave the Dockerfile path set to `/`. If the build context field is blank, set the path to the Dockerfile from the root of the source repository.

### [Regexes and automated builds](#regexes-and-automated-builds)

You can specify a regular expression (regex) so that only matching branches or tags are built. You can also use the results of the regex to create the Docker tag that's applied to the built image.

You can use up to nine regular expression capture groups, or expressions enclosed in parentheses, to select a source to build, and reference these in the **Docker Tag** field using `{\1}` through `{\9}`.

### [Build images with BuildKit](#build-images-with-buildkit)

Autobuilds use the BuildKit build system by default. If you want to use the legacy Docker build system, add the [environment variable](https://docs.docker.com/docker-hub/repos/manage/builds/#environment-variables-for-builds) `DOCKER_BUILDKIT=0`. Refer to the [BuildKit](https://docs.docker.com/build/buildkit/) page for more information on BuildKit.

## [Autobuild for teams](#autobuild-for-teams)

When you create an automated build repository in your own user account, you can start, cancel, and retry builds, and edit and delete your own repositories.

These same actions are also available for team repositories from Docker Hub if you are an owner. If you are a member of a team with `write` permissions you can start, cancel, and retry builds in your team's repositories, but you cannot edit the team repository settings or delete the team repositories. If your user account has `read` permission, or if you're a member of a team with `read` permission, you can view the build configuration including any testing settings.

| Action/Permission    | Read | Write | Admin | Owner |
| -------------------- | ---- | ----- | ----- | ----- |
| view build details   | x    | x     | x     | x     |
| start, cancel, retry |      | x     | x     | x     |
| edit build settings  |      |       | x     | x     |
| delete build         |      |       |       | x     |

### [Service users for team autobuilds](#service-users-for-team-autobuilds)

> Note
>
> Only owners can set up automated builds for teams.

When you set up automated builds for teams, you grant Docker Hub access to your source code repositories using OAuth tied to a specific user account. This means that Docker Hub has access to everything that the linked source provider account can access.

For organizations and teams, it's recommended you create a dedicated service account to grant access to the source provider. This ensures that no builds break as individual users' access permissions change, and that an individual user's personal projects aren't exposed to an entire organization.

This service account should have access to any repositories to be built, and must have administrative access to the source code repositories so it can manage deploy keys. If needed, you can limit this account to only a specific set of repositories required for a specific build.

If you are building repositories with linked private submodules (private dependencies), you also need to add an override `SSH_PRIVATE` environment variable to automated builds associated with the account. For more information, see [Troubleshoot](https://docs.docker.com/docker-hub/repos/manage/builds/troubleshoot/#build-repositories-with-linked-private-submodules)

1. Create a service user account on your source provider, and generate SSH keys for it.

2. Create a "build" team in your organization.

3. Ensure that the new "build" team has access to each repository and submodule you need to build.

   1. On GitHub or Bitbucket, go to the repository's **Settings** page.

   2. Add the new "build" team to the list of approved users.

      * GitHub: Add the team in **Collaborators and Teams**.
      * Bitbucket: Add the team in **Access management**.

4. Add the service user to the "build" team on the source provider.

5. Sign in to Docker Hub as an owner, switch to the organization, and follow the instructions to [link to source code repository](https://docs.docker.com/docker-hub/repos/manage/builds/link-source/) using the service account.

   > Note
   >
   > You may need to sign out of your individual account on the source code provider to create the link to the service account.

6. Optional. Use the SSH keys you generated to set up any builds with private submodules, using the service account and [the previous instructions](https://docs.docker.com/docker-hub/repos/manage/builds/troubleshoot/#build-repositories-with-linked-private-submodules).

## [What's Next?](#whats-next)

* [Customize your build process](https://docs.docker.com/docker-hub/repos/manage/builds/advanced/) with environment variables, hooks, and more
* [Add automated tests](https://docs.docker.com/docker-hub/repos/manage/builds/automated-testing/)
* [Manage your builds](https://docs.docker.com/docker-hub/repos/manage/builds/manage-builds/)
* [Troubleshoot](https://docs.docker.com/docker-hub/repos/manage/builds/troubleshoot/)

----
url: https://docs.docker.com/reference/cli/docker/model/ps/
----

# docker model ps

***

| Description | List running models |
| ----------- | ------------------- |
| Usage       | `docker model ps`   |

## [Description](#description)

List running models

----
url: https://docs.docker.com/guides/r/containerize/
----

# Containerize a R application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client.

## [Overview](#overview)

This section walks you through containerizing and running a R application.

## [Get the sample application](#get-the-sample-application)

The sample application uses the popular [Shiny](https://shiny.posit.co/) framework.

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/mfranzon/r-docker-dev.git && cd r-docker-dev
```

You should now have the following contents in your `r-docker-dev` directory.

```text
├── r-docker-dev/
│ ├── src/
│ │ └── app.R
│ ├── src_db/
│ │ └── app_db.R
│ ├── compose.yaml
│ ├── Dockerfile
│ └── README.md
```

To learn more about the files in the repository, see the following:

* [Dockerfile](https://docs.docker.com/reference/dockerfile/)
* [.dockerignore](https://docs.docker.com/reference/dockerfile/#dockerignore-file)
* [compose.yaml](https://docs.docker.com/reference/compose-file/)

## [Run the application](#run-the-application)

Inside the `r-docker-dev` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:3838>. You should see a simple Shiny application.

In the terminal, press `ctrl`+`c` to stop the application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `r-docker-dev` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:3838>.

You should see a simple Shiny application.

In the terminal, run the following command to stop the application.

```console
$ docker compose down
```

For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

## [Summary](#summary)

In this section, you learned how you can containerize and run your R application using Docker.

Related information:

* [Docker Compose overview](https://docs.docker.com/compose/)

## [Next steps](#next-steps)

In the next section, you'll learn how you can develop your application using containers.

[Use containers for R development »](https://docs.docker.com/guides/r/develop/)

----
url: https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/
----

# Set environment variables within your container's environment

***

Table of contents

***

A container's environment is not set until there's an explicit entry in the service configuration to make this happen. With Compose, there are two ways you can set environment variables in your containers with your Compose file.

> Tip
>
> Don't use environment variables to pass sensitive information, such as passwords, in to your containers. Use [secrets](https://docs.docker.com/compose/how-tos/use-secrets/) instead.

## [Use the `environment` attribute](#use-the-environment-attribute)

You can set environment variables directly in your container's environment with the [`environment` attribute](https://docs.docker.com/reference/compose-file/services/#environment) in your `compose.yaml`.

It supports both list and mapping syntax:

```yaml
services:
  webapp:
    environment:
      DEBUG: "true"
```

is equivalent to

```yaml
services:
  webapp:
    environment:
      - DEBUG=true
```

See [`environment` attribute](https://docs.docker.com/reference/compose-file/services/#environment) for more examples on how to use it.

### [Additional information](#additional-information)

* You can choose not to set a value and pass the environment variables from your shell straight through to your containers. It works in the same way as `docker run -e VARIABLE ...`:
  ```yaml
  web:
    environment:
      - DEBUG
  ```

The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run. Note that in this case no warning is issued if the `DEBUG` variable in the shell environment is not set.

* You can also take advantage of [interpolation](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/#interpolation-syntax). In the following example, the result is similar to the one above but Compose gives you a warning if the `DEBUG` variable is not set in the shell environment or in an `.env` file in the project directory.

  ```yaml
  web:
    environment:
      - DEBUG=${DEBUG}
  ```

## [Use the `env_file` attribute](#use-the-env_file-attribute)

A container's environment can also be set using [`.env` files](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/#env-file) along with the [`env_file` attribute](https://docs.docker.com/reference/compose-file/services/#env_file).

```yaml
services:
  webapp:
    env_file: "webapp.env"
```

Using an `.env` file lets you use the same file for use by a plain `docker run --env-file ...` command, or to share the same `.env` file within multiple services without the need to duplicate a long `environment` YAML block.

It can also help you keep your environment variables separate from your main configuration file, providing a more organized and secure way to manage sensitive information, as you do not need to place your `.env` file in the root of your project's directory.

The [`env_file` attribute](https://docs.docker.com/reference/compose-file/services/#env_file) also lets you use multiple `.env` files in your Compose application.

The paths to your `.env` file, specified in the `env_file` attribute, are relative to the location of your `compose.yaml` file.

> Important
>
> Interpolation in `.env` files is a Docker Compose CLI feature.
>
> It is not supported when running `docker run --env-file ...`.

### [Additional information](#additional-information-1)

* If multiple files are specified, they are evaluated in order and can override values set in previous files.
* As of Docker Compose version 2.24.0, you can set your `.env` file, defined by the `env_file` attribute, to be optional by using the `required` field. When `required` is set to `false` and the `.env` file is missing, Compose silently ignores the entry.
  ```yaml
  env_file:
    - path: ./default.env
      required: true # default
    - path: ./override.env
      required: false
  ```
* As of Docker Compose version 2.30.0, you can use an alternative file format for the `env_file` with the `format` attribute. For more information, see [`format`](https://docs.docker.com/reference/compose-file/services/#format).
* Values in your `.env` file can be overridden from the command line by using [`docker compose run -e`](#set-environment-variables-with-docker-compose-run---env).

## [Set environment variables with `docker compose run --env`](#set-environment-variables-with-docker-compose-run---env)

Similar to `docker run --env`, you can set environment variables temporarily with `docker compose run --env` or its short form `docker compose run -e`:

```console
$ docker compose run -e DEBUG=1 web python console.py
```

### [Additional information](#additional-information-2)

* You can also pass a variable from the shell or your environment files by not giving it a value:

  ```console
  $ docker compose run -e DEBUG web python console.py
  ```

The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run or from the environment files.

## [Further resources](#further-resources)

* [Understand environment variable precedence](https://docs.docker.com/compose/how-tos/environment-variables/envvars-precedence/).
* [Set or change predefined environment variables](https://docs.docker.com/compose/how-tos/environment-variables/envvars/)
* [Explore best practices](https://docs.docker.com/compose/how-tos/environment-variables/best-practices/)
* [Understand interpolation](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/)

----
url: https://docs.docker.com/desktop/setup/install/linux/archlinux/
----

# Install Docker Desktop on Arch-based distributions

***

Table of contents

***

Availability: Experimental

> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250 employees OR more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopArchlinuxInstall).

This page contains information on how to install, launch and upgrade Docker Desktop on an Arch-based distribution.

## [Prerequisites](#prerequisites)

To install Docker Desktop successfully, you must meet the [general system requirements](https://docs.docker.com/desktop/setup/install/linux/#general-system-requirements).

## [Install Docker Desktop](#install-docker-desktop)

1. [Install the Docker client binary on Linux](https://docs.docker.com/engine/install/binaries/#install-daemon-and-client-binaries-on-linux). Static binaries for the Docker client are available for Linux as `docker`. You can use:

   ```console
   $ wget https://download.docker.com/linux/static/stable/x86_64/docker-29.5.2.tgz -qO- | tar xvfz - docker/docker --strip-components=1
   $ sudo cp -rp ./docker /usr/local/bin/ && rm -r ./docker
   ```

2. Download the latest Arch package from the [Release notes](https://docs.docker.com/desktop/release-notes/).

3. Install the package:

   ```console
   $ sudo pacman -U ./docker-desktop-x86_64.pkg.tar.zst
   ```

   By default, Docker Desktop is installed at `/opt/docker-desktop`.

```console
$ systemctl --user start docker-desktop
```

When Docker Desktop starts, it creates a dedicated [context](/engine/context/working-with-contexts) that the Docker CLI can use as a target and sets it as the current context in use. This is to avoid a clash with a local Docker Engine that may be running on the Linux host and using the default context. On shutdown, Docker Desktop resets the current context to the previous one.

The Docker Desktop installer updates Docker Compose and the Docker CLI binaries on the host. It installs Docker Compose V2 and gives users the choice to link it as docker-compose from the Settings panel. Docker Desktop installs the new Docker CLI binary that includes cloud-integration capabilities in `/usr/local/bin/com.docker.cli` and creates a symlink to the classic Docker CLI at `/usr/local/bin`.

After you’ve successfully installed Docker Desktop, you can check the versions of these binaries by running the following commands:

```console
$ docker compose version
Docker Compose version v2.39.4

$ docker --version
Docker version 28.4.0, build d8eb465

$ docker version
Client:
 Version:           28.4.0
 API version:       1.51
 Go version:        go1.24.7
<...>
```

To enable Docker Desktop to start on sign in, from the Docker menu, select **Settings** > **General** > **Start Docker Desktop when you sign in to your computer**.

Alternatively, open a terminal and run:

```console
$ systemctl --user enable docker-desktop
```

To stop Docker Desktop, select the Docker menu icon to open the Docker menu and select **Quit Docker Desktop**.

Alternatively, open a terminal and run:

```console
$ systemctl --user stop docker-desktop
```

## [Next steps](#next-steps)

* Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopArchlinuxInstall) to see what Docker can offer you.

----
url: https://docs.docker.com/reference/cli/docker/buildx/history/inspect/
----

# docker buildx history inspect

***

| Description | Inspect a build record                          |
| ----------- | ----------------------------------------------- |
| Usage       | `docker buildx history inspect [OPTIONS] [REF]` |

## [Description](#description)

Inspect a build record to view metadata such as duration, status, build inputs, platforms, outputs, and attached artifacts. You can also use flags to extract provenance, SBOMs, or other detailed information.

## [Options](#options)

| Option                | Default  | Description       |
| --------------------- | -------- | ----------------- |
| [`--format`](#format) | `pretty` | Format the output |

## [Examples](#examples)

### [Inspect the most recent build](#inspect-the-most-recent-build)

```console
$ docker buildx history inspect
Name:           buildx (binaries)
Context:        .
Dockerfile:     Dockerfile
VCS Repository: https://github.com/crazy-max/buildx.git
VCS Revision:   f15eaa1ee324ffbbab29605600d27a84cab86361
Target:         binaries
Platforms:      linux/amd64
Keep Git Dir:   true

Started:        2025-02-07 11:56:24
Duration:       1m  1s
Build Steps:    16/16 (25% cached)

Image Resolve Mode:     local

Materials:
URI                                                             DIGEST
pkg:docker/docker/dockerfile@1                                  sha256:93bfd3b68c109427185cd78b4779fc82b484b0b7618e36d0f104d4d801e66d25
pkg:docker/golang@1.23-alpine3.21?platform=linux%2Famd64        sha256:2c49857f2295e89b23b28386e57e018a86620a8fede5003900f2d138ba9c4037
pkg:docker/tonistiigi/xx@1.6.1?platform=linux%2Famd64           sha256:923441d7c25f1e2eb5789f82d987693c47b8ed987c4ab3b075d6ed2b5d6779a3

Attachments:
DIGEST                                                                  PLATFORM        TYPE
sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3                 https://slsa.dev/provenance/v0.2
```

### [Inspect a specific build](#inspect-a-specific-build)

```console
# Using a build ID
docker buildx history inspect qu2gsuo8ejqrwdfii23xkkckt

# Or using a relative offset
docker buildx history inspect ^1
```

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints the output to `pretty` (default), `json` or using a Go template.

#### [Pretty output](#pretty-output)

```console
$ docker buildx history inspect
Name:           buildx (binaries)
Context:        .
Dockerfile:     Dockerfile
VCS Repository: https://github.com/crazy-max/buildx.git
VCS Revision:   f15eaa1ee324ffbbab29605600d27a84cab86361
Target:         binaries
Platforms:      linux/amd64
Keep Git Dir:   true

Started:        2025-02-07 11:56:24
Duration:       1m  1s
Build Steps:    16/16 (25% cached)

Image Resolve Mode:     local

Materials:
URI                                                             DIGEST
pkg:docker/docker/dockerfile@1                                  sha256:93bfd3b68c109427185cd78b4779fc82b484b0b7618e36d0f104d4d801e66d25
pkg:docker/golang@1.23-alpine3.21?platform=linux%2Famd64        sha256:2c49857f2295e89b23b28386e57e018a86620a8fede5003900f2d138ba9c4037
pkg:docker/tonistiigi/xx@1.6.1?platform=linux%2Famd64           sha256:923441d7c25f1e2eb5789f82d987693c47b8ed987c4ab3b075d6ed2b5d6779a3

Attachments:
DIGEST                                                                  PLATFORM        TYPE
sha256:217329d2af959d4f02e3a96dcbe62bf100cab1feb8006a047ddfe51a5397f7e3                 https://slsa.dev/provenance/v0.2

Print build logs: docker buildx history logs g9808bwrjrlkbhdamxklx660b
```

#### [JSON output](#json-output)

```console
$ docker buildx history inspect --format json
{
  "Name": "buildx (binaries)",
  "Ref": "5w7vkqfi0rf59hw4hnmn627r9",
  "Context": ".",
  "Dockerfile": "Dockerfile",
  "VCSRepository": "https://github.com/crazy-max/buildx.git",
  "VCSRevision": "f15eaa1ee324ffbbab29605600d27a84cab86361",
  "Target": "binaries",
  "Platform": [
    "linux/amd64"
  ],
  "KeepGitDir": true,
  "StartedAt": "2025-02-07T12:01:05.75807272+01:00",
  "CompletedAt": "2025-02-07T12:02:07.991778875+01:00",
  "Duration": 62233706155,
  "Status": "completed",
  "NumCompletedSteps": 16,
  "NumTotalSteps": 16,
  "NumCachedSteps": 4,
  "Config": {
    "ImageResolveMode": "local"
  },
  "Materials": [
    {
      "URI": "pkg:docker/docker/dockerfile@1",
      "Digests": [
        "sha256:93bfd3b68c109427185cd78b4779fc82b484b0b7618e36d0f104d4d801e66d25"
      ]
    },
    {
      "URI": "pkg:docker/golang@1.23-alpine3.21?platform=linux%2Famd64",
      "Digests": [
        "sha256:2c49857f2295e89b23b28386e57e018a86620a8fede5003900f2d138ba9c4037"
      ]
    },
    {
      "URI": "pkg:docker/tonistiigi/xx@1.6.1?platform=linux%2Famd64",
      "Digests": [
        "sha256:923441d7c25f1e2eb5789f82d987693c47b8ed987c4ab3b075d6ed2b5d6779a3"
      ]
    }
  ],
  "Attachments": [
    {
      "Digest": "sha256:450fdd2e6b868fecd69e9891c2c404ba461aa38a47663b4805edeb8d2baf80b1",
      "Type": "https://slsa.dev/provenance/v0.2"
    }
  ]
}
```

#### [Go template output](#go-template-output)

```console
$ docker buildx history inspect --format "{{.Name}}: {{.VCSRepository}} ({{.VCSRevision}})"
buildx (binaries): https://github.com/crazy-max/buildx.git (f15eaa1ee324ffbbab29605600d27a84cab86361)
```

## [Subcommands](#subcommands)

| Command                                                                                                                       | Description                       |
| ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| [`docker buildx history inspect attachment`](https://docs.docker.com/reference/cli/docker/buildx/history/inspect/attachment/) | Inspect a build record attachment |

----
url: https://docs.docker.com/reference/cli/docker/mcp/secret/rm/
----

# docker mcp secret rm

***

| Description | Remove secrets from the local OS Keychain |
| ----------- | ----------------------------------------- |
| Usage       | `docker mcp secret rm name1 name2 ...`    |

## [Description](#description)

Remove secrets from the local OS Keychain

## [Options](#options)

| Option  | Default | Description        |
| ------- | ------- | ------------------ |
| `--all` |         | Remove all secrets |

----
url: https://docs.docker.com/guides/java/run-tests/
----

# Run your Java tests

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a Java application](https://docs.docker.com/guides/java/containerize/).

## [Overview](#overview)

Testing is an essential part of modern software development. Testing can mean a lot of things to different development teams. There are unit tests, integration tests and end-to-end testing. In this guide you'll take a look at running your unit tests in Docker.

### [Multi-stage Dockerfile for testing](#multi-stage-dockerfile-for-testing)

In the following example, you'll pull the testing commands into your Dockerfile. Replace the contents of your Dockerfile with the following.

```dockerfile
# syntax=docker/dockerfile:1

FROM eclipse-temurin:21-jdk-jammy as base
WORKDIR /build
COPY --chmod=0755 mvnw mvnw
COPY .mvn/ .mvn/

FROM base as test
WORKDIR /build
COPY ./src src/
RUN --mount=type=bind,source=pom.xml,target=pom.xml \
    --mount=type=cache,target=/root/.m2 \
    ./mvnw test

FROM base as deps
WORKDIR /build
RUN --mount=type=bind,source=pom.xml,target=pom.xml \
    --mount=type=cache,target=/root/.m2 \
    ./mvnw dependency:go-offline -DskipTests

FROM deps as package
WORKDIR /build
COPY ./src src/
RUN --mount=type=bind,source=pom.xml,target=pom.xml \
    --mount=type=cache,target=/root/.m2 \
    ./mvnw package -DskipTests && \
    mv target/$(./mvnw help:evaluate -Dexpression=project.artifactId -q -DforceStdout)-$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout).jar target/app.jar

FROM package as extract
WORKDIR /build
RUN java -Djarmode=layertools -jar target/app.jar extract --destination target/extracted

FROM extract as development
WORKDIR /build
RUN cp -r /build/target/extracted/dependencies/. ./
RUN cp -r /build/target/extracted/spring-boot-loader/. ./
RUN cp -r /build/target/extracted/snapshot-dependencies/. ./
RUN cp -r /build/target/extracted/application/. ./
ENV JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000"
CMD [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ]

FROM eclipse-temurin:21-jre-jammy AS final
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser
USER appuser
COPY --from=extract build/target/extracted/dependencies/ ./
COPY --from=extract build/target/extracted/spring-boot-loader/ ./
COPY --from=extract build/target/extracted/snapshot-dependencies/ ./
COPY --from=extract build/target/extracted/application/ ./
EXPOSE 8080
ENTRYPOINT [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ]
```

First, you added a new base stage. In the base stage, you added common instructions that both the test and deps stage will need.

Next, you added a new test stage labeled `test` based on the base stage. In this stage you copied in the necessary source files and then specified `RUN` to run `./mvnw test`. Instead of using `CMD`, you used `RUN` to run the tests. The reason is that the `CMD` instruction runs when the container runs, and the `RUN` instruction runs when the image is being built. When using `RUN`, the build will fail if the tests fail.

Finally, you updated the deps stage to be based on the base stage and removed the instructions that are now in the base stage.

Run the following command to build a new image using the test stage as the target and view the test results. Include `--progress=plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target test` to target the test stage.

Now, build your image and run your tests. You'll run the `docker build` command and add the `--target test` flag so that you specifically run the test build stage.

```console
$ docker build -t java-docker-image-test --progress=plain --no-cache --target=test .
```

You should see output containing the following

```console
...

#15 101.3 [WARNING] Tests run: 45, Failures: 0, Errors: 0, Skipped: 2
#15 101.3 [INFO]
#15 101.3 [INFO] ------------------------------------------------------------------------
#15 101.3 [INFO] BUILD SUCCESS
#15 101.3 [INFO] ------------------------------------------------------------------------
#15 101.3 [INFO] Total time:  01:39 min
#15 101.3 [INFO] Finished at: 2024-02-01T23:24:48Z
#15 101.3 [INFO] ------------------------------------------------------------------------
#15 DONE 101.4s
```

## [Next steps](#next-steps)

In the next section, you’ll take a look at how to set up a CI/CD pipeline using GitHub Actions.

[Configure CI/CD for your Java application »](https://docs.docker.com/guides/java/configure-ci-cd/)

----
url: https://docs.docker.com/engine/manage-resources/labels/
----

# Docker object labels

***

Table of contents

***

Labels are a mechanism for applying metadata to Docker objects, including:

* Images
* Containers
* Local daemons
* Volumes
* Networks
* Swarm nodes
* Swarm services

You can use labels to organize your images, record licensing information, annotate relationships between containers, volumes, and networks, or in any way that makes sense for your business or application.

## [Label keys and values](#label-keys-and-values)

A label is a key-value pair, stored as a string. You can specify multiple labels for an object, but each key must be unique within an object. If the same key is given multiple values, the most-recently-written value overwrites all previous values.

### [Key format recommendations](#key-format-recommendations)

A label key is the left-hand side of the key-value pair. Keys are alphanumeric strings which may contain periods (`.`), underscores (`_`), slashes (`/`), and hyphens (`-`). Most Docker users use images created by other organizations, and the following guidelines help to prevent inadvertent duplication of labels across objects, especially if you plan to use labels as a mechanism for automation.

* Authors of third-party tools should prefix each label key with the reverse DNS notation of a domain they own, such as `com.example.some-label`.

* Don't use a domain in your label key without the domain owner's permission.

* The `com.docker.*`, `io.docker.*`, and `org.dockerproject.*` namespaces are reserved by Docker for internal use.

* Label keys should begin and end with a lower-case letter and should only contain lower-case alphanumeric characters, the period character (`.`), and the hyphen character (`-`). Consecutive periods or hyphens aren't allowed.

* The period character (`.`) separates namespace "fields". Label keys without namespaces are reserved for CLI use, allowing users of the CLI to interactively label Docker objects using shorter typing-friendly strings.

These guidelines aren't currently enforced and additional guidelines may apply to specific use cases.

### [Value guidelines](#value-guidelines)

Label values can contain any data type that can be represented as a string, including (but not limited to) JSON, XML, CSV, or YAML. The only requirement is that the value be serialized to a string first, using a mechanism specific to the type of structure. For instance, to serialize JSON into a string, you might use the `JSON.stringify()` JavaScript method.

Since Docker doesn't deserialize the value, you can't treat a JSON or XML document as a nested structure when querying or filtering by label value unless you build this functionality into third-party tooling.

## [Manage labels on objects](#manage-labels-on-objects)

Each type of object with support for labels has mechanisms for adding and managing them and using them as they relate to that type of object.

Labels on images, containers, local daemons, volumes, and networks are static for the lifetime of the object. To change these labels you must recreate the object. Labels on Swarm nodes and services can be updated dynamically.

### [Images](#images)

Add labels to images using the [`LABEL` instruction](https://docs.docker.com/reference/dockerfile/#label) in a Dockerfile:

```dockerfile
LABEL com.example.version="1.0"
LABEL com.example.description="Web application"
```

You can also set labels at build time with the `--label` flag, without needing a `LABEL` instruction in the Dockerfile:

```console
$ docker build --label "com.example.version=1.0" -t myapp .
```

Inspect labels on an image using `docker inspect`:

```console
$ docker inspect --format='{{json .Config.Labels}}' myapp
```

Filter images by label with [`docker image ls --filter`](/reference/cli/docker/image/ls/#filter):

```console
$ docker image ls --filter "label=com.example.version"
```

### [Containers](#containers)

Override or add labels when starting a container with [`docker run --label`](/reference/cli/docker/container/run/#label):

```console
$ docker run --label "com.example.env=prod" myapp
```

Inspect labels on a container:

```console
$ docker inspect --format='{{json .Config.Labels}}' mycontainer
```

Filter containers by label with [`docker container ls --filter`](/reference/cli/docker/container/ls/#filter):

```console
$ docker container ls --filter "label=com.example.env=prod"
```

### [Local Docker daemons](#local-docker-daemons)

Add labels to the Docker daemon by passing `--label` flags when starting `dockerd`, or by setting `"labels"` in the [daemon configuration file](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file):

```json
{
  "labels": ["com.example.environment=production"]
}
```

View daemon labels with `docker system info`.

### [Volumes](#volumes)

Add labels when [creating a volume](/reference/cli/docker/volume/create/):

```console
$ docker volume create --label "com.example.purpose=database" myvolume
```

Inspect volume labels:

```console
$ docker volume inspect myvolume --format='{{json .Labels}}'
```

Filter volumes by label with [`docker volume ls --filter`](/reference/cli/docker/volume/ls/#filter):

```console
$ docker volume ls --filter "label=com.example.purpose"
```

### [Networks](#networks)

Add labels when [creating a network](/reference/cli/docker/network/create/):

```console
$ docker network create --label "com.example.purpose=frontend" mynetwork
```

Inspect network labels:

```console
$ docker network inspect mynetwork --format='{{json .Labels}}'
```

Filter networks by label with [`docker network ls --filter`](/reference/cli/docker/network/ls/#filter):

```console
$ docker network ls --filter "label=com.example.purpose"
```

### [Swarm nodes](#swarm-nodes)

* [Adding or updating a Swarm node's labels](/reference/cli/docker/node/update/#label-add)
* [Filtering Swarm nodes by label](/reference/cli/docker/node/ls/#filter)

### [Swarm services](#swarm-services)

* [Adding labels when creating a Swarm service](/reference/cli/docker/service/create/#label)
* [Updating a Swarm service's labels](/reference/cli/docker/service/update/)
* [Filtering Swarm services by label](/reference/cli/docker/service/ls/#filter)

----
url: https://docs.docker.com/guides/text-summarization/
----

[Build a text summarization app](https://docs.docker.com/guides/text-summarization/)

This guide shows how to containerize text summarization models with Docker.

Python AI

20 minutes

[« Back to all guides](/guides/)

# Build a text summarization app

***

Table of contents

***

## [Overview](#overview)

In this guide, you'll learn how to build and run a text summarization application. You'll build the application using Python with the Bert Extractive Summarizer, and then set up the environment and run the application using Docker.

The sample text summarization application uses the Bert Extractive Summarizer. This tool utilizes the HuggingFace Pytorch transformers library to run extractive summarizations. This works by first embedding the sentences, then running a clustering algorithm, finding the sentences that are closest to the cluster's centroids.

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop.
* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Get the sample application](#get-the-sample-application)

1. Open a terminal, and clone the sample application's repository using the following command.

   ```console
   $ git clone https://github.com/harsh4870/Docker-NLP.git
   ```

2. Verify that you cloned the repository.

   You should see the following files in your `Docker-NLP` directory.

   ```text
   01_sentiment_analysis.py
   02_name_entity_recognition.py
   03_text_classification.py
   04_text_summarization.py
   05_language_translation.py
   entrypoint.sh
   requirements.txt
   Dockerfile
   README.md
   ```

## [Explore the application code](#explore-the-application-code)

The source code for the text summarization application is in the `Docker-NLP/04_text_summarization.py` file. Open `04_text_summarization.py` in a text or code editor to explore its contents in the following steps.

1. Import the required libraries.

   ```python
   from summarizer import Summarizer
   ```

   This line of code imports the `Summarizer` class from the `summarizer` package, essential for your text summarization application. The summarizer module implements the Bert Extractive Summarizer, leveraging the HuggingFace Pytorch transformers library, renowned in the NLP (Natural Language Processing) domain. This library offers access to pre-trained models like BERT, which revolutionized language understanding tasks, including text summarization.

   The BERT model, or Bidirectional Encoder Representations from Transformers, excels in understanding context in language, using a mechanism known as "attention" to determine the significance of words in a sentence. For summarization, the model embeds sentences and then uses a clustering algorithm to identify key sentences, those closest to the centroids of these clusters, effectively capturing the main ideas of the text.

2. Specify the main execution block.

   ```python
   if __name__ == "__main__":
   ```

   This Python idiom ensures that the following code block runs only if this script is the main program. It provides flexibility, allowing the script to function both as a standalone program and as an imported module.

3. Create an infinite loop for continuous input.

   ```python
      while True:
         input_text = input("Enter the text for summarization (type 'exit' to end): ")

         if input_text.lower() == 'exit':
            print("Exiting...")
            break
   ```

   An infinite loop continuously prompts you for text input, ensuring interactivity. The loop breaks when you type `exit`, allowing you to control the application flow effectively.

4. Create an instance of Summarizer.

   ```python
         bert_model = Summarizer()
   ```

   Here, you create an instance of the Summarizer class named `bert_model`. This instance is now ready to perform the summarization task using the BERT model, simplifying the complex processes of embedding sentences and clustering into an accessible interface.

5. Generate and print a summary.

   ```python
   summary = bert_model(input_text)
   print(summary)
   ```

   Your input text is processed by the bert\_model instance, which then returns a summarized version. This demonstrates the power of Python's high-level libraries in enabling complex operations with minimal code.

6. Create `requirements.txt`. The sample application already contains the `requirements.txt` file to specify the necessary modules that the application imports. Open `requirements.txt` in a code or text editor to explore its contents.

   ```text
   ...

   # 04 text_summarization
   bert-extractive-summarizer==0.10.1

   ...

   torch==2.1.2
   ```

   The `bert-extractive-summarizer` and `torch` modules are required for the text summarization application. The summarizer module generates a summary of the input text. This requires PyTorch because the underlying BERT model, which is used for generating the summary, is implemented in PyTorch.

## [Explore the application environment](#explore-the-application-environment)

You'll use Docker to run the application in a container. Docker lets you containerize the application, providing a consistent and isolated environment for running it. This means the application will operate as intended within its Docker container, regardless of the underlying system differences.

To run the application in a container, a Dockerfile is required. A Dockerfile is a text document that contains all the commands you would call on the command line to assemble an image. An image is a read-only template with instructions for creating a Docker container.

The sample application already contains a `Dockerfile`. Open the `Dockerfile` in a code or text editor to explore its contents.

The following steps explain each part of the `Dockerfile`. For more details, see the [Dockerfile reference](/reference/dockerfile/).

1. Specify the base image.

   ```dockerfile
   FROM python:3.8-slim
   ```

   This command sets the foundation for the build. `python:3.8-slim` is a lightweight version of the Python 3.8 image, optimized for size and speed. Using this slim image reduces the overall size of your Docker image, leading to quicker downloads and less surface area for security vulnerabilities. This is particularly useful for a Python-based application where you might not need the full standard Python image.

2. Set the working directory.

   ```dockerfile
   WORKDIR /app
   ```

   `WORKDIR` sets the current working directory within the Docker image. By setting it to `/app`, you ensure that all subsequent commands in the Dockerfile (like `COPY` and `RUN`) are executed in this directory. This also helps in organizing your Docker image, as all application-related files are contained in a specific directory.

3. Copy the requirements file into the image.

   ```dockerfile
   COPY requirements.txt /app
   ```

   The `COPY` command transfers the `requirements.txt` file from your local machine into the Docker image. This file lists all Python dependencies required by the application. Copying it into the container lets the next command (`RUN pip install`) to install these dependencies inside the image environment.

4. Install the Python dependencies in the image.

   ```dockerfile
   RUN pip install --no-cache-dir -r requirements.txt
   ```

   This line uses `pip`, Python's package installer, to install the packages listed in `requirements.txt`. The `--no-cache-dir` option disables the cache, which reduces the size of the Docker image by not storing the unnecessary cache data.

5. Run additional commands.

   ```dockerfile
   RUN python -m spacy download en_core_web_sm
   ```

   This step is specific to NLP applications that require the spaCy library. It downloads the `en_core_web_sm` model, which is a small English language model for spaCy. While not needed for this app, it's included for compatibility with other NLP applications that might use this Dockerfile.

6. Copy the application code into the image.

   ```dockerfile
   COPY *.py /app
   COPY entrypoint.sh /app
   ```

   These commands copy your Python scripts and the `entrypoint.sh` script into the image's `/app` directory. This is crucial because the container needs these scripts to run the application. The `entrypoint.sh` script is particularly important as it dictates how the application starts inside the container.

7. Set permissions for the `entrypoint.sh` script.

   ```dockerfile
   RUN chmod +x /app/entrypoint.sh
   ```

   This command modifies the file permissions of `entrypoint.sh`, making it executable. This step is necessary to ensure that the Docker container can run this script to start the application.

8. Set the entry point.

   ```dockerfile
   ENTRYPOINT ["/app/entrypoint.sh"]
   ```

   The `ENTRYPOINT` instruction configures the container to run `entrypoint.sh` as its default executable. This means that when the container starts, it automatically executes the script.

   You can explore the `entrypoint.sh` script by opening it in a code or text editor. As the sample contains several applications, the script lets you specify which application to run when the container starts.

## [Run the application](#run-the-application)

To run the application using Docker:

1. Build the image.

   In a terminal, run the following command inside the directory of where the `Dockerfile` is located.

   ```console
   $ docker build -t basic-nlp .
   ```

   ```console
   $ docker run -it basic-nlp 04_text_summarization.py
   ```

   The following is a break down of the command:

   * `docker run`: This is the primary command used to run a new container from a Docker image.

   * `-it`: This is a combination of two options:

     * `-i` or `--interactive`: This keeps the standard input (STDIN) open even if not attached. It lets the container remain running in the foreground and be interactive.
     * `-t` or `--tty`: This allocates a pseudo-TTY, essentially simulating a terminal, like a command prompt or a shell. It's what lets you interact with the application inside the container.

   * `basic-nlp`: This specifies the name of the Docker image to use for creating the container. In this case, it's the image named `basic-nlp` that you created with the `docker build` command.

   * `04_text_summarization.py`: This is the script you want to run inside the Docker container. It gets passed to the `entrypoint.sh` script, which runs it when the container starts.

   For more details, see the [docker run CLI reference](/reference/cli/docker/container/run/).

   > Note
   >
   > For Windows users, you may get an error when running the container. Verify that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), then rebuild the image. For more details, see \[Avoid unexpected syntax errors, use Unix style line endings for files in containers]\(/desktop/troubleshoot-and-support/troubleshoot/topics/#Unexpected-syntax-errors-use-Unix-style-line endings-for-files-in-containers).

   You will see the following in your console after the container starts.

   ```console
   Enter the text for summarization (type 'exit' to end):
   ```

3. Test the application.

   Enter some text to get the text summarization.

   ```console
   Enter the text for summarization (type 'exit' to end): Artificial intelligence (AI) is a branch of computer science that aims to create machines capable of intelligent behavior. These machines are designed to mimic human cognitive functions such as learning, problem-solving, and decision-making. AI technologies can be classified into two main types: narrow or weak AI, which is designed for a particular task, and general or strong AI, which possesses the ability to understand, learn, and apply knowledge across various domains. One of the most popular approaches in AI is machine learning, where algorithms are trained on large datasets to recognize patterns and make predictions.

   Artificial intelligence (AI) is a branch of computer science that aims to create machines capable of intelligent behavior. These machines are designed to mimic human cognitive functions such as learning, problem-solving, and decision-making.
   ```

## [Summary](#summary)

In this guide, you learned how to build and run a text summarization application. You learned how to build the application using Python with Bert Extractive Summarizer, and then set up the environment and run the application using Docker.

Related information:

* [Docker CLI reference](/reference/cli/docker/)
* [Dockerfile reference](/reference/dockerfile/)
* [Bert Extractive Summarizer](https://github.com/dmmiller612/bert-extractive-summarizer)
* [PyTorch](https://pytorch.org/)
* [Python documentation](https://docs.python.org/3/)

## [Next steps](#next-steps)

Explore more [natural language processing guides](https://docs.docker.com/guides/).

----
url: https://docs.docker.com/guides/testcontainers-python-getting-started/
----

# Getting started with Testcontainers for Python

Table of contents

***

Learn how to create a Python application and test database interactions using Testcontainers for Python with a real PostgreSQL instance.

**Time to complete** 15 minutes

In this guide, you will learn how to:

* Create a Python application that uses PostgreSQL to store customer data
* Use `psycopg` to interact with the database
* Write integration tests using `testcontainers-python` and `pytest`
* Manage container lifecycle with pytest fixtures

## [Prerequisites](#prerequisites)

* Python 3.10+
* pip
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-python-getting-started/create-project/)

   Set up a Python project with a PostgreSQL-backed customer service.

2. [Write tests](https://docs.docker.com/guides/testcontainers-python-getting-started/write-tests/)

   Write integration tests using testcontainers-python and pytest with a real PostgreSQL database.

3. [Run tests](https://docs.docker.com/guides/testcontainers-python-getting-started/run-tests/)

   Run your Testcontainers-based integration tests and explore next steps.

----
url: https://docs.docker.com/reference/cli/docker/plugin/
----

# docker plugin

***

| Description | Manage plugins  |
| ----------- | --------------- |
| Usage       | `docker plugin` |

## [Description](#description)

Manage plugins.

## [Subcommands](#subcommands)

| Command                                                                                 | Description                                                                                                           |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| [`docker plugin create`](https://docs.docker.com/reference/cli/docker/plugin/create/)   | Create a plugin from a rootfs and configuration. Plugin data directory must contain config.json and rootfs directory. |
| [`docker plugin disable`](https://docs.docker.com/reference/cli/docker/plugin/disable/) | Disable a plugin                                                                                                      |
| [`docker plugin enable`](https://docs.docker.com/reference/cli/docker/plugin/enable/)   | Enable a plugin                                                                                                       |
| [`docker plugin inspect`](https://docs.docker.com/reference/cli/docker/plugin/inspect/) | Display detailed information on one or more plugins                                                                   |
| [`docker plugin install`](https://docs.docker.com/reference/cli/docker/plugin/install/) | Install a plugin                                                                                                      |
| [`docker plugin ls`](https://docs.docker.com/reference/cli/docker/plugin/ls/)           | List plugins                                                                                                          |
| [`docker plugin push`](https://docs.docker.com/reference/cli/docker/plugin/push/)       | Push a plugin to a registry                                                                                           |
| [`docker plugin rm`](https://docs.docker.com/reference/cli/docker/plugin/rm/)           | Remove one or more plugins                                                                                            |
| [`docker plugin set`](https://docs.docker.com/reference/cli/docker/plugin/set/)         | Change settings for a plugin                                                                                          |
| [`docker plugin upgrade`](https://docs.docker.com/reference/cli/docker/plugin/upgrade/) | Upgrade an existing plugin                                                                                            |

----
url: https://docs.docker.com/guides/testcontainers-cloud/demo-local/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Setting up Testcontainers Cloud by Docker

***

***

This demo shows the process of setting up Testcontainers Cloud by Docker to work in your local development environment using the Testcontainers Desktop application. By the end of this walkthrough, you'll have Testcontainers Cloud by Docker up and running, ready to offload container management from your local machine to the cloud for more efficient testing.

* Install and configure Testcontainers Cloud and the CLI to seamlessly integrate with your local development environment.
* Set up and configure the Testcontainers Desktop application to monitor and manage cloud-based containers during local tests.
* Create and run integration tests using Testcontainers that leverage cloud-based container resources.
* Monitor and manage containers efficiently, understanding how Testcontainers Cloud automates cleanup and ensures consistent testing environments.
* Review options for monitoring and troubleshooting in the Testcontainers Cloud Dashboard.

[Configuring Testcontainers Cloud in the CI Pipeline »](https://docs.docker.com/guides/testcontainers-cloud/demo-ci/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/history/ls/
----

# docker buildx history ls

***

| Description | List build records                   |
| ----------- | ------------------------------------ |
| Usage       | `docker buildx history ls [OPTIONS]` |

## [Description](#description)

List completed builds recorded by the active builder. Each entry includes the build ID, name, status, timestamp, and duration.

By default, only records for the current builder are shown. You can filter results using flags.

## [Options](#options)

| Option                    | Default | Description                                  |
| ------------------------- | ------- | -------------------------------------------- |
| [`--filter`](#filter)     |         | Provide filter values (e.g., `status=error`) |
| [`--format`](#format)     | `table` | Format the output                            |
| [`--local`](#local)       |         | List records for current repository only     |
| [`--no-trunc`](#no-trunc) |         | Don't truncate output                        |

## [Examples](#examples)

### [List all build records for the current builder](#list-all-build-records-for-the-current-builder)

```console
$ docker buildx history ls
BUILD ID                    NAME           STATUS     CREATED AT        DURATION
qu2gsuo8ejqrwdfii23xkkckt   .dev/2850      Completed  3 days ago        1.4s
qsiifiuf1ad9pa9qvppc0z1l3   .dev/2850      Completed  3 days ago        1.3s
g9808bwrjrlkbhdamxklx660b   .dev/3120      Completed  5 days ago        2.1s
```

### [List failed builds (--filter)](#filter)

```console
docker buildx history ls --filter status=error
```

You can filter the list using the `--filter` flag. Supported filters include:

| Filter                                 | Supported comparisons                            | Example                    |
| -------------------------------------- | ------------------------------------------------ | -------------------------- |
| `ref`, `repository`, `status`          | Support `=` and `!=` comparisons                 | `--filter status!=success` |
| `startedAt`, `completedAt`, `duration` | Support `<` and `>` comparisons with time values | `--filter duration>30s`    |

You can combine multiple filters by repeating the `--filter` flag:

```console
docker buildx history ls --filter status=error --filter duration>30s
```

### [List builds from the current project (--local)](#local)

```console
docker buildx history ls --local
```

### [Display full output without truncation (--no-trunc)](#no-trunc)

```console
docker buildx history ls --no-trunc
```

### [Format output (--format)](#format)

#### [JSON output](#json-output)

```console
$ docker buildx history ls --format json
[
  {
    "ID": "qu2gsuo8ejqrwdfii23xkkckt",
    "Name": ".dev/2850",
    "Status": "Completed",
    "CreatedAt": "2025-04-15T12:33:00Z",
    "Duration": "1.4s"
  },
  {
    "ID": "qsiifiuf1ad9pa9qvppc0z1l3",
    "Name": ".dev/2850",
    "Status": "Completed",
    "CreatedAt": "2025-04-15T12:29:00Z",
    "Duration": "1.3s"
  }
]
```

#### [Go template output](#go-template-output)

```console
$ docker buildx history ls --format '{{.Name}} - {{.Duration}}'
.dev/2850 - 1.4s
.dev/2850 - 1.3s
.dev/3120 - 2.1s
```

----
url: https://docs.docker.com/reference/cli/docker/checkpoint/rm/
----

# docker checkpoint rm

***

| Description                                                               | Remove a checkpoint                                   |
| ------------------------------------------------------------------------- | ----------------------------------------------------- |
| Usage                                                                     | `docker checkpoint rm [OPTIONS] CONTAINER CHECKPOINT` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker checkpoint remove`                            |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Remove a checkpoint

## [Options](#options)

| Option             | Default | Description                               |
| ------------------ | ------- | ----------------------------------------- |
| `--checkpoint-dir` |         | Use a custom checkpoint storage directory |

----
url: https://docs.docker.com/engine/swarm/
----

# Swarm mode

***

Table of contents

***

> Note
>
> Swarm mode is an advanced feature for managing a cluster of Docker daemons.
>
> Use Swarm mode if you intend to use Swarm as a production runtime environment.
>
> If you're not planning on deploying with Swarm, use [Docker Compose](/compose/) instead. If you're developing for a Kubernetes deployment, consider using the [integrated Kubernetes feature](https://docs.docker.com/desktop/use-desktop/kubernetes/) in Docker Desktop.

Current versions of Docker include Swarm mode for natively managing a cluster of Docker Engines called a swarm. Use the Docker CLI to create a swarm, deploy application services to a swarm, and manage swarm behavior.

Docker Swarm mode is built into the Docker Engine. Do not confuse Docker Swarm mode with [Docker Classic Swarm](https://github.com/docker/classicswarm) which is no longer actively developed.

## [Feature highlights](#feature-highlights)

### [Cluster management integrated with Docker Engine](#cluster-management-integrated-with-docker-engine)

Use the Docker Engine CLI to create a swarm of Docker Engines where you can deploy application services. You don't need additional orchestration software to create or manage a swarm.

### [Decentralized design](#decentralized-design)

Instead of handling differentiation between node roles at deployment time, the Docker Engine handles any specialization at runtime. You can deploy both kinds of nodes, managers and workers, using the Docker Engine. This means you can build an entire swarm from a single disk image.

### [Declarative service model](#declarative-service-model)

Docker Engine uses a declarative approach to let you define the desired state of the various services in your application stack. For example, you might describe an application comprised of a web front end service with message queueing services and a database backend.

### [Scaling](#scaling)

For each service, you can declare the number of tasks you want to run. When you scale up or down, the swarm manager automatically adapts by adding or removing tasks to maintain the desired state.

### [Desired state reconciliation](#desired-state-reconciliation)

The swarm manager node constantly monitors the cluster state and reconciles any differences between the actual state and your expressed desired state. For example, if you set up a service to run 10 replicas of a container, and a worker machine hosting two of those replicas crashes, the manager creates two new replicas to replace the replicas that crashed. The swarm manager assigns the new replicas to workers that are running and available.

### [Multi-host networking](#multi-host-networking)

You can specify an overlay network for your services. The swarm manager automatically assigns addresses to the containers on the overlay network when it initializes or updates the application.

### [Service discovery](#service-discovery)

Swarm manager nodes assign each service in the swarm a unique DNS name and load balance running containers. You can query every container running in the swarm through a DNS server embedded in the swarm.

### [Load balancing](#load-balancing)

You can expose the ports for services to an external load balancer. Internally, the swarm lets you specify how to distribute service containers between nodes.

### [Secure by default](#secure-by-default)

Each node in the swarm enforces TLS mutual authentication and encryption to secure communications between itself and all other nodes. You have the option to use self-signed root certificates or certificates from a custom root CA.

### [Rolling updates](#rolling-updates)

At rollout time you can apply service updates to nodes incrementally. The swarm manager lets you control the delay between service deployment to different sets of nodes. If anything goes wrong, you can roll back to a previous version of the service.

## [What's next?](#whats-next)

* Learn Swarm mode [key concepts](https://docs.docker.com/engine/swarm/key-concepts/).

* Get started with the [Swarm mode tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/).

* Explore Swarm mode CLI commands

  * [swarm init](/reference/cli/docker/swarm/init/)
  * [swarm join](/reference/cli/docker/swarm/join/)
  * [service create](/reference/cli/docker/service/create/)
  * [service inspect](/reference/cli/docker/service/inspect/)
  * [service ls](/reference/cli/docker/service/ls/)
  * [service rm](/reference/cli/docker/service/rm/)
  * [service scale](/reference/cli/docker/service/scale/)
  * [service ps](/reference/cli/docker/service/ps/)
  * [service update](/reference/cli/docker/service/update/)

----
url: https://docs.docker.com/reference/cli/docker/volume/
----

# docker volume

***

| Description | Manage volumes          |
| ----------- | ----------------------- |
| Usage       | `docker volume COMMAND` |

## [Description](#description)

Manage volumes. You can use subcommands to create, inspect, list, remove, or prune volumes.

## [Subcommands](#subcommands)

| Command                                                                                 | Description                                         |
| --------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [`docker volume create`](https://docs.docker.com/reference/cli/docker/volume/create/)   | Create a volume                                     |
| [`docker volume inspect`](https://docs.docker.com/reference/cli/docker/volume/inspect/) | Display detailed information on one or more volumes |
| [`docker volume ls`](https://docs.docker.com/reference/cli/docker/volume/ls/)           | List volumes                                        |
| [`docker volume prune`](https://docs.docker.com/reference/cli/docker/volume/prune/)     | Remove unused local volumes                         |
| [`docker volume rm`](https://docs.docker.com/reference/cli/docker/volume/rm/)           | Remove one or more volumes                          |
| [`docker volume update`](https://docs.docker.com/reference/cli/docker/volume/update/)   | Update a volume (cluster volumes only)              |

----
url: https://docs.docker.com/build/ci/
----

# Continuous integration with Docker

***

Table of contents

***

Continuous Integration (CI) is the part of the development process where you're looking to get your code changes merged with the main branch of the project. At this point, development teams run tests and builds to vet that the code changes don't cause any unwanted or unexpected behaviors.

There are several uses for Docker at this stage of development, even if you don't end up packaging your application as a container image.

## [Docker as a build environment](#docker-as-a-build-environment)

Containers are reproducible, isolated environments that yield predictable results. Building and testing your application in a Docker container makes it easier to prevent unexpected behaviors from occurring. Using a Dockerfile, you define the exact requirements for the build environment, including programming runtimes, operating system, binaries, and more.

Using Docker to manage your build environment also eases maintenance. For example, updating to a new version of a programming runtime can be as simple as changing a tag or digest in a Dockerfile. No need to SSH into a pet VM to manually reinstall a newer version and update the related configuration files.

Additionally, just as you expect third-party open source packages to be secure, the same should go for your build environment. You can scan and index a builder image, just like you would for any other containerized application.

The following links provide instructions for how you can get started using Docker for building your applications in CI:

* [GitHub Actions](https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action)
* [GitLab](https://docs.gitlab.com/runner/executors/docker.html)
* [Circle CI](https://circleci.com/docs/using-docker/)
* [Render](https://render.com/docs/docker)

### [Docker in Docker](#docker-in-docker)

You can also use a Dockerized build environment to build container images using Docker. That is, your build environment runs inside a container which itself is equipped to run Docker builds. This method is referred to as "Docker in Docker".

Docker provides an official [Docker image](https://hub.docker.com/_/docker) that you can use for this purpose.

## [What's next](#whats-next)

Docker maintains a set of official GitHub Actions that you can use to build, annotate, and push container images on the GitHub Actions platform. See [Introduction to GitHub Actions](https://docs.docker.com/build/ci/github-actions/) to learn more and get started.

----
url: https://docs.docker.com/docker-hub/repos/manage/export/
----

# Export organization repositories to CSV

***

Table of contents

***

This guide shows you how to export a complete list of repositories from your Docker Hub organization, including private repositories. You'll use a Personal Access Token (PAT) from an administrator account to authenticate with the Docker Hub API and export repository details to a CSV file for reporting or analysis.

The exported data includes repository name, visibility status, last updated date, pull count, and star count.

## [Prerequisites](#prerequisites)

Before you begin, ensure you have:

* Administrator access to a Docker Hub organization
* `curl` installed for making API requests
* `jq` installed for JSON parsing
* A spreadsheet application to view the CSV

## [Create a personal access token](#create-a-personal-access-token)

[Create a personal access token](/security/access-tokens/) from a user account that has access to the organization's repositories. When creating the token, select at minimum **Read-only** access permissions to list repositories.

> Important
>
> Use a PAT from a user account that is a member of the organization. Users with owner roles can export all organization repositories. Members can only export repositories they have permission to access.

## [Authenticate with the Docker Hub API](#authenticate-with-the-docker-hub-api)

Exchange your personal access token for a JWT bearer token that you'll use for subsequent API requests.

1. Set your Docker Hub username, organization name, and personal access token as variables:

   ```bash
   USERNAME="<your-docker-username>"
   ORG="<org-name>"
   PAT="<your_personal_access_token>"
   ```

2. Call the authentication endpoint to get a JWT:

   ```bash
   TOKEN=$(
     curl -s https://hub.docker.com/v2/auth/token \
       -H 'Content-Type: application/json' \
       -d "{\"identifier\":\"$USERNAME\",\"secret\":\"$PAT\"}" \
     | jq -r '.access_token'
   )
   ```

3. Verify the token was retrieved successfully:

   ```console
   $ echo "Got JWT: ${#TOKEN} chars"
   ```

You'll use this JWT as a Bearer token in the `Authorization` header for all subsequent API calls.

## [Retrieve all repositories](#retrieve-all-repositories)

The Docker Hub API paginates repository lists. This script retrieves all pages and combines the results.

1. Set the page size and initial API endpoint:

   ```bash
   PAGE_SIZE=100
   URL="https://hub.docker.com/v2/namespaces/$ORG/repositories?page_size=$PAGE_SIZE"
   ```

2. Paginate through all results:

   ```bash
   ALL=$(
     while [ -n "$URL" ] && [ "$URL" != "null" ]; do
       RESP=$(curl -s "$URL" -H "Authorization: Bearer $TOKEN")
       echo "$RESP" | jq -c '.results[]'
       URL=$(echo "$RESP" | jq -r '.next')
     done | jq -s '.'
   )
   ```

3. Verify the number of repositories retrieved:

   ```console
   $ echo "$ALL" | jq 'length'
   ```

The script continues requesting the `next` URL from each response until pagination is complete.

## [Export to CSV](#export-to-csv)

Generate a CSV file with repository details that you can open in spreadsheet applications.

Run the following command to create `repos.csv`:

```bash
echo "$ALL" | jq -r '
  (["namespace","name","is_private","last_updated","pull_count","star_count"] | @csv),
  (.[] | [
    .namespace, .name, .is_private, .last_updated, (.pull_count//0), (.star_count//0)
  ] | @csv)
' > repos.csv
```

Verify the export completed:

```console
$ echo "Rows:" $(wc -l < repos.csv)
```

Open the `repos.csv` file in your preferred spreadsheet application to view and analyze your repository data.

## [Troubleshooting](#troubleshooting)

### [Only public repositories appear](#only-public-repositories-appear)

The Docker Hub account associated with your personal access token may not have access to private repositories in the organization.

To fix this:

1. Verify the account is a member of the organization
2. Check that the account has appropriate permissions (owner or member role)
3. Ensure the personal access token has sufficient access permissions
4. Regenerate the JWT and retry the export

### [API returns 403 or missing fields](#api-returns-403-or-missing-fields)

Ensure you're using the JWT from the `/v2/auth/token` endpoint as a Bearer token in the `Authorization` header, not the personal access token directly.

Verify your authentication:

```console
$ curl -s "https://hub.docker.com/v2/namespaces/$ORG/repositories?page_size=1" \
  -H "Authorization: Bearer $TOKEN" | jq
```

If this returns an error, re-run the authentication step to get a fresh JWT.

----
url: https://docs.docker.com/guides/go-prometheus-monitoring/compose/
----

# Connecting services with Docker Compose

***

Table of contents

***

Now that you have containerized the Golang application, you will use Docker Compose to connect your services together. You will connect the Golang application, Prometheus, and Grafana services together to monitor the Golang application with Prometheus and Grafana.

## [Creating a Docker Compose file](#creating-a-docker-compose-file)

Create a new file named `compose.yml` in the root directory of your Golang application. The Docker Compose file contains instructions to run multiple services and connect them together.

Here is a Docker Compose file for a project that uses Golang, Prometheus, and Grafana. You will also find this file in the `go-prometheus-monitoring` directory.

```yaml
services:
  api:
    container_name: go-api
    build:
      context: .
      dockerfile: Dockerfile
    image: go-api:latest
    ports:
      - 8000:8000
    networks:
      - go-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 5
    develop:
      watch:
        - path: .
          action: rebuild
      
  prometheus:
    container_name: prometheus
    image: prom/prometheus:v2.55.0
    volumes:
      - ./Docker/prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - 9090:9090
    networks:
      - go-network
  
  grafana:
    container_name: grafana
    image: grafana/grafana:11.3.0
    volumes:
      - ./Docker/grafana.yml:/etc/grafana/provisioning/datasources/datasource.yaml
      - grafana-data:/var/lib/grafana
    ports:
      - 3000:3000
    networks:
      - go-network
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=password

volumes:
  grafana-data:

networks:
  go-network:
    driver: bridge
```

## [Understanding the Docker Compose file](#understanding-the-docker-compose-file)

The Docker Compose file consists of three services:

* **Golang application service**: This service builds the Golang application using the Dockerfile and runs it in a container. It exposes the application's port `8000` and connects to the `go-network` network. It also defines a health check to monitor the application's health. You have also used `healthcheck` to monitor the health of the application. The health check runs every 30 seconds and retries 5 times if the health check fails. The health check uses the `curl` command to check the `/health` endpoint of the application. Apart from the health check, you have also added a `develop` section to watch the changes in the application's source code and rebuild the application using the Docker Compose Watch feature.

* **Prometheus service**: This service runs the Prometheus server in a container. It uses the official Prometheus image `prom/prometheus:v2.55.0`. It exposes the Prometheus server on port `9090` and connects to the `go-network` network. You have also mounted the `prometheus.yml` file from the `Docker` directory which is present in the root directory of your project. The `prometheus.yml` file contains the Prometheus configuration to scrape the metrics from the Golang application. This is how you connect the Prometheus server to the Golang application.

  ```yaml
  global:
    scrape_interval: 10s
    evaluation_interval: 10s

  scrape_configs:
    - job_name: myapp
      static_configs:
        - targets: ["api:8000"]
  ```

  In the `prometheus.yml` file, you have defined a job named `myapp` to scrape the metrics from the Golang application. The `targets` field specifies the target to scrape the metrics from. In this case, the target is the Golang application running on port `8000`. The `api` is the service name of the Golang application in the Docker Compose file. The Prometheus server will scrape the metrics from the Golang application every 10 seconds.

* **Grafana service**: This service runs the Grafana server in a container. It uses the official Grafana image `grafana/grafana:11.3.0`. It exposes the Grafana server on port `3000` and connects to the `go-network` network. You have also mounted the `grafana.yml` file from the `Docker` directory which is present in the root directory of your project. The `grafana.yml` file contains the Grafana configuration to add the Prometheus data source. This is how you connect the Grafana server to the Prometheus server. In the environment variables, you have set the Grafana admin user and password, which will be used to log in to the Grafana dashboard.

  ```yaml
  apiVersion: 1
  datasources:
  - name: Prometheus (Main)
    type: prometheus
    url: http://prometheus:9090
    isDefault: true
  ```

  In the `grafana.yml` file, you have defined a Prometheus data source named `Prometheus (Main)`. The `type` field specifies the type of the data source, which is `prometheus`. The `url` field specifies the URL of the Prometheus server to fetch the metrics from. In this case, the URL is `http://prometheus:9090`. `prometheus` is the service name of the Prometheus server in the Docker Compose file. The `isDefault` field specifies whether the data source is the default data source in Grafana.

Apart from the services, the Docker Compose file also defines a volume named `grafana-data` to persist the Grafana data and a network named `go-network` to connect the services together. You have created a custom network `go-network` to connect the services together. The `driver: bridge` field specifies the network driver to use for the network.

## [Building and running the services](#building-and-running-the-services)

Now that you have the Docker Compose file, you can build the services and run them together using Docker Compose.

To build and run the services, run the following command in the terminal:

```console
$ docker compose up
```

The `docker compose up` command builds the services defined in the Docker Compose file and runs them together. You will see the similar output in the terminal:

```console
 ✔ Network go-prometheus-monitoring_go-network  Created                                                           0.0s 
 ✔ Container grafana                            Created                                                           0.3s 
 ✔ Container go-api                             Created                                                           0.2s 
 ✔ Container prometheus                         Created                                                           0.3s 
Attaching to go-api, grafana, prometheus
go-api      | [GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
go-api      | 
go-api      | [GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
go-api      |  - using env:     export GIN_MODE=release
go-api      |  - using code:    gin.SetMode(gin.ReleaseMode)
go-api      | 
go-api      | [GIN-debug] GET    /metrics                  --> main.PrometheusHandler.func1 (3 handlers)
go-api      | [GIN-debug] GET    /health                   --> main.main.func1 (4 handlers)
go-api      | [GIN-debug] GET    /v1/users                 --> main.main.func2 (4 handlers)
go-api      | [GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value.
go-api      | Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details.
go-api      | [GIN-debug] Listening and serving HTTP on :8000
prometheus  | ts=2025-03-15T05:57:06.676Z caller=main.go:627 level=info msg="No time or size retention was set so using the default time retention" duration=15d
prometheus  | ts=2025-03-15T05:57:06.678Z caller=main.go:671 level=info msg="Starting Prometheus Server" mode=server version="(version=2.55.0, branch=HEAD, revision=91d80252c3e528728b0f88d254dd720f6be07cb8)"
grafana     | logger=settings t=2025-03-15T05:57:06.865335506Z level=info msg="Config overridden from command line" arg="default.log.mode=console"
grafana     | logger=settings t=2025-03-15T05:57:06.865337131Z level=info msg="Config overridden from Environment variable" var="GF_PATHS_DATA=/var/lib/grafana"
grafana     | logger=ngalert.state.manager t=2025-03-15T05:57:07.088956839Z level=info msg="State
.
.
grafana     | logger=plugin.angulardetectorsprovider.dynamic t=2025-03-15T05:57:07.530317298Z level=info msg="Patterns update finished" duration=440.489125ms
```

The services will start running, and you can access the Golang application at `http://localhost:8000`, Prometheus at `http://localhost:9090/health`, and Grafana at `http://localhost:3000`. You can also check the running containers using the `docker ps` command.

```console
$ docker ps
```

## [Summary](#summary)

In this section, you learned how to connect services together using Docker Compose. You created a Docker Compose file to run multiple services together and connect them using networks. You also learned how to build and run the services using Docker Compose.

Related information:

* [Docker Compose overview](https://docs.docker.com/compose/)
* [Compose file reference](https://docs.docker.com/reference/compose-file/)

Next, you will learn how to develop the Golang application with Docker Compose and monitor it with Prometheus and Grafana.

## [Next steps](#next-steps)

In the next section, you will learn how to develop the Golang application with Docker. You will also learn how to use Docker Compose Watch to rebuild the image whenever you make changes to the code. Lastly, you will test the application and visualize the metrics in Grafana using Prometheus as the data source.

[Developing your application »](https://docs.docker.com/guides/go-prometheus-monitoring/develop/)

----
url: https://docs.docker.com/ai/sandboxes/agents/gemini/
----

# Gemini

***

Table of contents

***

This guide covers authentication, configuration, and usage of Google Gemini in a sandboxed environment.

Official documentation: [Gemini CLI](https://geminicli.com/docs/)

## [Quick start](#quick-start)

Create a sandbox and run Gemini for a project directory:

```console
$ sbx run gemini ~/my-project
```

The workspace parameter is optional and defaults to the current directory:

```console
$ cd ~/my-project
$ sbx run gemini
```

## [Authentication](#authentication)

Gemini requires either a Google API key or a Google account with Gemini access.

**API key**: Store your key using [stored secrets](https://docs.docker.com/ai/sandboxes/security/credentials/#stored-secrets):

```console
$ sbx secret set -g google
```

Alternatively, export the `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable in your shell before running the sandbox. See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for details on both methods.

**Google account**: If no API key is set, Gemini prompts you to sign in interactively when it starts. Interactive authentication is scoped to the sandbox and doesn't persist if you remove and recreate it.

## [Configuration](#configuration)

Sandboxes don't pick up user-level configuration from your host, such as `~/.gemini`. Only project-level configuration in the working directory is available inside the sandbox. See [Why doesn't the sandbox use my user-level agent configuration?](https://docs.docker.com/ai/sandboxes/faq/#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for workarounds.

The sandbox disables Gemini's built-in sandbox tool (since the sandbox itself provides isolation).

### [Default startup command](#default-startup-command)

Without extra args, the sandbox runs:

```text
gemini --yolo
```

Args after `--` replace these defaults rather than being appended. To keep `--yolo`, include it yourself:

```console
$ sbx run gemini -- --yolo -p "explain this"
```

## [Base image](#base-image)

Template: `docker/sandbox-templates:gemini`

Gemini is configured to disable its built-in OAuth flow. Authentication is managed through the proxy with API keys.

See [Customize](https://docs.docker.com/ai/sandboxes/customize/) to pre-install tools or customize this environment.

----
url: https://docs.docker.com/reference/cli/docker/service/rm/
----

# docker service rm

***

| Description                                                               | Remove one or more services              |
| ------------------------------------------------------------------------- | ---------------------------------------- |
| Usage                                                                     | `docker service rm SERVICE [SERVICE...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker service remove`                  |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Removes the specified services from the swarm.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Examples](#examples)

Remove the `redis` service:

```console
$ docker service rm redis

redis

$ docker service ls

ID  NAME  MODE  REPLICAS  IMAGE
```

> Warning
>
> Unlike `docker rm`, this command does not ask for confirmation before removing a running service.

----
url: https://docs.docker.com/reference/cli/docker/compose/scale/
----

# docker compose scale

***

| Description | Scale services                               |
| ----------- | -------------------------------------------- |
| Usage       | `docker compose scale [SERVICE=REPLICAS...]` |

## [Description](#description)

Scale services

## [Options](#options)

| Option      | Default | Description                 |
| ----------- | ------- | --------------------------- |
| `--no-deps` |         | Don't start linked services |

----
url: https://docs.docker.com/desktop/previous-versions/3.x-mac/
----

# Docker Desktop for Mac 3.x release notes

***

Table of contents

***

This page contains release notes for Docker Desktop for Mac 3.x.

## [Docker Desktop 3.6.0](#docker-desktop-360)

2021-08-11

### [New](#new)

* **Dev Environments**: You can now create a Dev Environment from your local Git repository.
* **Volume Management**: You can now sort volumes by the name, the date created, and the size of the volume. You can also search for specific volumes using the **Search** field. For more information, see [Explore volumes](https://docs.docker.com/desktop/use-desktop/volumes/).

### [Upgrades](#upgrades)

* [Compose V2 RC1](https://github.com/docker/compose-cli/releases/tag/v2.0.0-rc.1)

  * Docker compose command line completion.
  * Allow setting 0 scale/replicas.
  * Detect new container on logs —follow.

* [Go 1.16.7](https://github.com/golang/go/releases/tag/go1.16.7)

* [Docker Engine 20.10.8](https://docs.docker.com/engine/release-notes/20.10/#20108)

* [containerd v1.4.9](https://github.com/containerd/containerd/releases/tag/v1.4.9)

* [runc v1.0.1](https://github.com/opencontainers/runc/releases/tag/v1.0.1)

* [Kubernetes 1.21.3](https://github.com/kubernetes/kubernetes/releases/tag/v1.21.3)

* [Linux kernel 5.10.47](https://hub.docker.com/layers/docker/for-desktop-kernel/5.10.47-0b705d955f5e283f62583c4e227d64a7924c138f/images/sha256-a4c79bc185ec9eba48dcc802a8881b9d97e532b3f803d23e5b8d4951588f4d51?context=repo)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes)

* Update kernel configuration to fix a performance regression in [Docker Desktop 3.0.0](#docker-desktop-300) that caused publishing container ports to take 10 times longer than on older versions. For more information, see [linuxkit/linuxkit#3701](https://github.com/linuxkit/linuxkit/pull/3701) and [docker/for-mac#5668](https://github.com/docker/for-mac/issues/5668).
* Fixed a bug where the DNS server would fail after receiving an unexpectedly large datagram.
* Fixed an issue related to hardware acceleration [docker/for-mac#5121](https://github.com/docker/for-mac/issues/5121)
* Fixed an issue related to Skip This Update for mac [docker/for-mac#5842](https://github.com/docker/for-mac/issues/5842)

## [Docker Desktop 3.5.2](#docker-desktop-352)

2021-07-08

### [New](#new-1)

**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts.

### [Upgrades](#upgrades-1)

* [Compose V2 beta 6](https://github.com/docker/compose-cli/releases/tag/v2.0.0-beta.6)

  * `compose run` and `compose exec` commands use separate streams for stdout and stderr. See [docker/compose-cli#1873](https://github.com/docker/compose-cli/issues/1873).
  * `compose run` and `compose exec` commands support detach keys. Fixes [docker/compose-cli#1709](https://github.com/docker/compose-cli/issues/1709).
  * Fixed `--force` and `--volumes` flags on `compose rm` command. See [docker/compose-cli#1844](https://github.com/docker/compose-cli/issues/1844).
  * Fixed network's IPAM configuration. Service can define a fixed IP. Fixes for [docker/compose-cli#1678](https://github.com/docker/compose-cli/issues/1678) and [docker/compose-cli#1816](https://github.com/docker/compose-cli/issues/1816)

* Dev Environments

  * Support VS Code Insiders.
  * Allow users to specify a branch when cloning a project.

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-1)

* Dev Environments: Fixed a blank screen in some create and remove scenarios. Fixes [dev-environments#4](https://github.com/docker/dev-environments/issues/4)
* Dev Environments: Fixed error handling when removing an environment. Fixes [dev-environments#8](https://github.com/docker/dev-environments/issues/8)
* Dev Environments: The **Start**, **Stop**, and **Share** buttons are disabled while an environment is being created or removed.
* Fixed a connection leak when using `virtualization.framework` and not using `vpnkit`.
* Fixed spurious traces on iptables updates.
* Fixed a delay when adding a multiple port forwarding option.

## [Docker Desktop 3.5.1](#docker-desktop-351)

2021-06-25

### [New](#new-2)

**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts.

**Compose V2 beta**: Docker Desktop now includes the beta version of Compose V2, which supports the `docker compose` command as part of the Docker CLI. While `docker-compose` is still supported and maintained, Compose V2 implementation relies directly on the compose-go bindings which are maintained as part of the specification. The compose command in the Docker CLI supports most of the `docker-compose` commands and flags. It is expected to be a drop-in replacement for `docker-compose`. There are a few remaining flags that have yet to be implemented, see the docker-compose compatibility list for more information about the flags that are supported in the new compose command. If you run into any problems with Compose V2, you can easily switch back to Compose v1 by either by making changes in Docker Desktop **Experimental** Settings, or by running the command `docker-compose disable-v2`. Let us know your feedback on the new ‘compose’ command by creating an issue in the [Compose-CLI](https://github.com/docker/compose-cli/issues) GitHub repository.

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-2)

* Fixed a link to the policy that provides details on how Docker handles the uploaded diagnostics data. Fixes [docker/for-mac#5741](https://github.com/docker/for-mac/issues/5741)

## [Docker Desktop 3.5.0](#docker-desktop-350)

2021-06-23

### [New](#new-3)

**Dev Environments Preview**: Dev Environments enable you to seamlessly collaborate with your team members without moving between Git branches to get your code onto your team members' machines. When using Dev Environments, you can share your in-progress work with your team members in just one click, and without having to deal with any merge conflicts.

**Compose V2 beta**: Docker Desktop now includes the beta version of Compose V2, which supports the `docker compose` command as part of the Docker CLI. While `docker-compose` is still supported and maintained, Compose V2 implementation relies directly on the compose-go bindings which are maintained as part of the specification. The compose command in the Docker CLI supports most of the `docker-compose` commands and flags. It is expected to be a drop-in replacement for `docker-compose`. There are a few remaining flags that have yet to be implemented, see the docker-compose compatibility list for more information about the flags that are supported in the new compose command. If you run into any problems with Compose V2, you can easily switch back to Compose v1 by either by making changes in Docker Desktop **Experimental** Settings, or by running the command `docker-compose disable-v2`. Let us know your feedback on the new ‘compose’ command by creating an issue in the [Compose-CLI](https://github.com/docker/compose-cli/issues) GitHub repository.

### [Upgrades](#upgrades-2)

* [Compose V2 beta](https://github.com/docker/compose-cli/releases/tag/v2.0.0-beta.4)

  * Fixed a bug where a container cannot be started when a file is bind-mounted into a nested mountpoint. Fixes [docker/compose-cli#1795](https://github.com/docker/compose-cli/issues/1795).
  * Added support for container links and external links.
  * Introduced the `docker compose logs --since --until` option.
  * `docker compose config --profiles` now lists all defined profiles.

* From [Kubernetes 1.21.1](https://github.com/kubernetes/kubernetes/releases/tag/v1.21.1) to [Kubernetes 1.21.2](https://github.com/kubernetes/kubernetes/releases/tag/v1.21.2)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-3)

* **Volume Management**

  * Users can now remove a file or directory inside a volume using the Docker Dashboard.
  * The **Volumes** view in Docker Dashboard displays the last modified time and the size of the contents inside a volume.
  * Users can save the files and directories inside a volume from Docker Dashboard.

* Fixed a bug that caused Docker to fail to start because `/usr/bin` was not present on the `PATH`. Fixes [docker/for-mac#5770](https://github.com/docker/for-mac/issues/5770)

* Docker Desktop now allows files to be modified inside a host directory which is a nested mountpoint in a container. Fixes [docker/for-mac#5748](https://github.com/docker/for-mac/issues/5748).

* Fixed a settings migration bug which caused Docker Desktop not to find images and containers data after upgrading to 3.4.0. Fixes [docker/for-mac#5754](https://github.com/docker/for-mac/issues/5754).

* Docker Desktop now highlights the architecture of the non-native images in the Docker Dashboard on Apple Silicon.

* Fix using virtualization.framework on macOS 12 (Monterey).

* The default `docker` CLI `context` is now `desktop-linux`.

* Show the Docker Desktop Feedback popup only when clicking Docker menu.

## [Docker Desktop 3.4.0](#docker-desktop-340)

2021-06-09

### [New](#new-4)

**Volume Management**: Docker Desktop users can now create and delete volumes using the Docker Dashboard and also see which volumes are being used. For more information, see [Explore volumes](https://docs.docker.com/desktop/use-desktop/volumes/).

**Compose V2 beta**: Docker Desktop now includes the beta version of Compose V2, which supports the `docker compose` command as part of the Docker CLI. While `docker-compose` is still supported and maintained, Compose V2 implementation relies directly on the compose-go bindings which are maintained as part of the specification. The compose command in the Docker CLI supports most of the `docker-compose` commands and flags. It is expected to be a drop-in replacement for `docker-compose`. There are a few remaining flags that have yet to be implemented, see the docker-compose compatibility list for more information about the flags that are supported in the new compose command. If you run into any problems with Compose V2, you can easily switch back to Compose v1 by either by making changes in Docker Desktop **Experimental** Settings, or by running the command `docker-compose disable-v2`. Let us know your feedback on the new ‘compose’ command by creating an issue in the [Compose-CLI](https://github.com/docker/compose-cli/issues) GitHub repository.

**Skip Docker Desktop updates**: All users can now skip an update when they are prompted to install individual Docker Desktop releases.

### [Deprecation](#deprecation)

* Docker Desktop no longer installs Notary. You can now use [Docker Content Trust](https://docs.docker.com/engine/security/trust/) for image signing.

### [Upgrades](#upgrades-3)

* [Docker Engine 20.10.7](https://docs.docker.com/engine/release-notes/20.10/#20107)
* [Docker Compose 1.29.2](https://github.com/docker/compose/releases/tag/1.29.2)
* [Docker Hub Tool v0.4.1](https://github.com/docker/hub-tool/releases/tag/v0.4.1)
* [Compose CLI v1.0.16](https://github.com/docker/compose-cli/releases/tag/v1.0.16)
* [Kubernetes 1.21.1](https://github.com/kubernetes/kubernetes/releases/tag/v1.21.1)
* [containerd v1.4.6](https://github.com/containerd/containerd/releases/tag/v1.4.6)
* [runc v1.0.0-rc95](https://github.com/opencontainers/runc/releases/tag/v1.0.0-rc95)
* [Go 1.16.5](https://github.com/golang/go/releases/tag/go1.16.5)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-4)

* Prevent `docker run` from hanging if inotify event injection fails. Fixes [docker/for-mac#5590](https://github.com/docker/for-mac/issues/5590).
* Fixed error showing stderr log in the UI. Fixes [docker/for-mac#5688](https://github.com/docker/for-mac/issues/5688).
* Fixed an issue which caused `riscv64` emulation to fail on Docker Desktop. Fixes [docker/for-mac#5699](https://github.com/docker/for-mac/issues/5699).
* Automatically reclaim space after deleting containers by deleting volumes and removing build cache.
* Docker Desktop now allows a blank HTTP proxy to be configured for the Docker engine, which will completely disable the internal HTTP proxy. See [docker/for-mac#2467](https://github.com/docker/for-mac/issues/2467).
* Docker Compose applications with file names other than `docker-compose.yml` can now be removed from Docker Desktop. Fixes [docker/for-win#11046](https://github.com/docker/for-win/issues/11046)
* Docker Desktop now exposes the host CPU on Apple silicon. Fixes [docker/for-mac#5681](https://github.com/docker/for-mac/issues/5681).
* Avoid leaking open ports bound to privileged ports and specific IPs over engine Restart. Fixes [docker/for-mac#5649](https://github.com/docker/for-mac/issues/5649).
* Use `vpnkit` with `virtualization.framework` to fix connectivity issues with VPN clients such as Cisco AnyConnect.
* Fixed version number missing in update dialog window.
* Fixed an issue where the diagnostics were sometimes not uploaded correctly from the **Support** dialog.
* Fixed DNS entries for `*.docker.internal` and Kubernetes cluster reset after the VM IP changes. Fixes [docker/for-mac#5707](https://github.com/docker/for-mac/issues/5707), [docker/for-mac#5680](https://github.com/docker/for-mac/issues/5680), [docker/for-mac#5663](https://github.com/docker/for-mac/issues/5663) and [docker/for-mac#5653](https://github.com/docker/for-mac/issues/5653).
* Avoid running `com.docker.osxfs` when gRPC FUSE is enabled. Fixes [docker/for-mac#5725](https://github.com/docker/for-mac/issues/5725).

### [Known issues](#known-issues)

* On Apple Silicon in native `arm64` containers, older versions of `libssl` in `debian:buster`, `ubuntu:20.04` and `centos:8` will segfault when connected to some TLS servers, for example `curl https://dl.yarnpkg.com`. The bug is fixed in newer versions of `libssl` in `debian:bullseye`, `ubuntu:21.04` and `fedora:35`.

## [Docker Desktop 3.3.3](#docker-desktop-333)

2021-05-06

### [Upgrades](#upgrades-4)

* [Snyk v1.563.0](https://github.com/snyk/snyk/releases/tag/v1.563.0)
* [Docker Scan v0.8.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.8.0)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-5)

* Fixed the diagnostics failing to upload from the Troubleshoot screen.

### [Docker Desktop 3.3.2](#docker-desktop-332)

2021-05-03

### [Upgrades](#upgrades-5)

* [Compose CLI v1.0.14](https://github.com/docker/compose-cli/tree/v1.0.14)
* [Go 1.16.3](https://golang.org/doc/go1.16)
* [Docker Compose 1.29.1](https://github.com/docker/compose/releases/tag/1.29.1)
* [Docker Engine 20.10.6](https://docs.docker.com/engine/release-notes/20.10/#20106)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-6)

* Fixed a bug with an Apple chip where the last byte in a network transfer was occasionally lost.
* Fixed a bug where a `metrics-port` defined in the engine's `daemon.json` blocks application restart.
* Fixed a leak of ephemeral ports. Fixes [docker/for-mac#5611](https://github.com/docker/for-mac/issues/5611).
* Emulate a more modern Intel CPU with `qemu` on an Apple chip, for better image compatibility. See [docker/for-mac#5561](https://github.com/docker/for-mac/issues/5561).
* Enable buildkit garbage collection by default.
* Fixed a bug which blocked binding to port 123. Fixes [docker/for-mac#5589](https://github.com/docker/for-mac/issues/5589).
* Disable the HTTP and HTTPS transparent proxies when there is no upstream proxy set. Fixes [docker/for-mac#5572](https://github.com/docker/for-mac/issues/5572).
* Revert to the HTTP and HTTPS proxy implementation used in 3.2.2.
* Removed the "Deploy Docker Stacks to Kubernetes by default" Kubernetes setting. The component was removed in 2.4.0.0 but we forgot to remove the setting. Fixes [docker/for-mac#4966](https://github.com/docker/for-mac/issues/4966).

## [Docker Desktop 3.3.1](#docker-desktop-331)

2021-04-15

### [New](#new-5)

Docker Desktop is now available for Apple silicon as well as Intel chips. This enables developers with their choice of local development environments, and extends development pipelines for ARM-based applications. For more information, see [Docker Desktop for Apple silicon](https://docs.docker.com/desktop/setup/install/mac-install/).

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-7)

* Docker Desktop now ensures the permissions of `/dev/null` and other devices are correctly set to `0666` (`rw-rw-rw-`) inside `--privileged` containers. Fixes [docker/for-mac#5527](https://github.com/docker/for-mac/issues/5527)

* Fixed an issue that caused Docker Desktop to fail during startup when it is unable to establish a connection with Docker Hub in the backend. Fixes [docker/for-win#10896](https://github.com/docker/for-win/issues/10896)

* **Mac with Apple silicon**: Docker Desktop now reduces the idle CPU consumption.

### [Known issues](#known-issues-1)

**Apple silicon**

* `ping` from inside a container to the Internet does not work as expected. To test the network, we recommend using `curl` or `wget`. See [docker/for-mac#5322](https://github.com/docker/for-mac/issues/5322#issuecomment-809392861).
* Users may occasionally experience data drop when a TCP stream is half-closed.

## [Docker Desktop 3.3.0](#docker-desktop-330)

2021-04-08

You can now specify when to download and install a Docker Desktop update. When an update becomes available, Docker Desktop displays an icon to indicate the availability of a newer version. You can download the update in the background whenever convenient. When the download is complete, all you need to do is to click Update and restart to install the latest update.

Developers who use Docker Desktop for professional development purposes may at times need to skip a specific update. For this reason, users with a paid Docker subscription can skip notifications for a particular update when a reminder appears.

For developers in IT managed environments, who don’t have administrative access to install updates to Docker Desktop, there is now an option in the Settings menu to opt out of notifications altogether for Docker Desktop updates if your Docker ID is part of a Team subscription.

### [Upgrades](#upgrades-6)

* [Docker Compose 1.29.0](https://github.com/docker/compose/releases/tag/1.29.0)
* [Compose CLI v1.0.12](https://github.com/docker/compose-cli/tree/v1.0.12)
* [Linux kernel 5.10.25](https://hub.docker.com/layers/docker/for-desktop-kernel/5.10.25-6594e668feec68f102a58011bb42bd5dc07a7a9b/images/sha256-80e22cd9c9e6a188a785d0e23b4cefae76595abe1e4a535449627c2794b10871?context=repo)
* [Snyk v1.461.0](https://github.com/snyk/snyk/releases/tag/v1.461.0)
* [Docker Hub Tool v0.3.1](https://github.com/docker/hub-tool/releases/tag/v0.3.1)
* [containerd v1.4.4](https://github.com/containerd/containerd/releases/tag/v1.4.4)
* [runc v1.0.0-rc93](https://github.com/opencontainers/runc/releases/tag/v1.0.0-rc93)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-8)

* Fixed an issue when viewing compose applications that have been started with an explicit project name. Fixes [docker/for-win#10564](https://github.com/docker/for-win/issues/10564).
* Fixed a bug that `--add-host host.docker.internal:host-gateway` caused `host.docker.internal` to resolve to the wrong IP address. See [docker/for-linux#264](https://github.com/docker/for-linux/issues/264#issuecomment-785137844).
* Fixed a bug that caused inter-container HTTP traffic to be misrouted to the external HTTP proxy. Fixes [docker/for-mac#5476](https://github.com/docker/for-mac/issues/5476).
* Fixed a bug that could cause other files in the same folder as the VM disk to be deleted when the disk was resized. Fixes [docker/for-mac#5486](https://github.com/docker/for-mac/issues/5486).
* Fixed an issue where delta downloads caused an `Illegal instruction exception`. Fixes [docker/for-mac#5459](https://github.com/docker/for-mac/issues/5459).
* Apply domain-based HTTPS proxy `no_proxy` rules for encrypted connections. Fixes [docker/for-mac#2732](https://github.com/docker/for-mac/issues/2732).
* Fixed missing text in reset to factory defaults dialog. Fixes [docker/for-mac#5457](https://github.com/docker/for-mac/issues/5457).
* Fixed an issue where running a container with a random port on the host caused Docker Desktop dashboard to incorrectly open a browser with port 0, instead of using the allocated port.
* Fixed an issue where pulling an image from Docker Hub using the Docker Desktop dashboard was failing silently.
* Removed unused DNS name `docker.for.mac.http.internal`.
* Perform a filesystem check when starting the Linux VM.
* Detect Linux kernel crashes and escalate them to the user.

## [Docker Desktop 3.2.2](#docker-desktop-322)

2021-03-15

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-9)

* Fixed an issue that stopped containers binding to port 53. Fixes [docker/for-mac#5416](https://github.com/docker/for-mac/issues/5416).
* Fixed an issue that 32-bit Intel binaries were emulated on Intel CPUs. Fixes [docker/for-win#10594](https://github.com/docker/for-win/issues/10594).
* Fixed an issue related to high CPU consumption and frozen UI when the network connection is lost. Fixes [for-win/#10563](https://github.com/docker/for-win/issues/10563).
* Fixed an issue opening a terminal in iTerm2 when it has no other windows open. Fixes [docker/roadmap#98](https://github.com/docker/roadmap/issues/98#issuecomment-791927788).

## [Docker Desktop 3.2.1](#docker-desktop-321)

2021-03-05

### [Upgrades](#upgrades-7)

* [Docker Engine 20.10.5](https://docs.docker.com/engine/release-notes/20.10/#20105)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-10)

* Fixed an issue that sometimes caused Docker Desktop to fail to start after updating to version 3.2.0. Fixes [docker/for-mac#5406](https://github.com/docker/for-mac/issues/5406). If you are still experiencing this issue when trying to update from 3.2.0 to 3.2.1, we recommend that you uninstall 3.2.0 and manually install Docker Desktop 3.2.1.

## [Docker Desktop 3.2.0](#docker-desktop-320)

2021-03-01

### [New](#new-6)

* The Docker Dashboard opens automatically when you start Docker Desktop.
* The Docker Dashboard displays a tip once a week.
* Docker Desktop uses iTerm2 to launch the terminal on the container if it is installed. Otherwise, it launches the default Terminal.App. [docker/roadmap#98](https://github.com/docker/roadmap/issues/98)
* Add experimental support to use the new Apple Virtualization framework (requires macOS Big Sur 11.1 or later)
* BuildKit is now the default builder for all users, not just for new installations. To turn this setting off, go to **Preferences** > **Docker Engine** and add the following block to the Docker daemon configuration file:

```json
"features": {
    "buildkit": false
}
```

### [Upgrades](#upgrades-8)

* [Docker Engine 20.10.3](https://docs.docker.com/engine/release-notes/20.10/#20103)
* [Docker Compose 1.28.5](https://github.com/docker/compose/releases/tag/1.28.5)
* [Compose CLI v1.0.9](https://github.com/docker/compose-cli/tree/v1.0.9)
* [Docker Hub Tool v0.3.0](https://github.com/docker/hub-tool/releases/tag/v0.3.0)
* [QEMU 5.0.1](https://wiki.qemu.org/ChangeLog/5.0)
* [Amazon ECR Credential Helper v0.5.0](https://github.com/awslabs/amazon-ecr-credential-helper/releases/tag/v0.5.0)
* [Alpine 3.13](https://alpinelinux.org/posts/Alpine-3.13.0-released.html)
* [Kubernetes 1.19.7](https://github.com/kubernetes/kubernetes/releases/tag/v1.19.7)
* [Go 1.16](https://golang.org/doc/go1.16)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-11)

* Fixed an issue on the container detail screen where the buttons would disappear when scrolling the logs. Fixes [docker/for-mac#5290](https://github.com/docker/for-mac/issues/5290)
* Fixed an issue when port forwarding multiple ports with an IPv6 container network. Fixes [docker/for-mac#5247](https://github.com/docker/for-mac/issues/5247)
* Fixed a regression where `docker load` could not use an xz archive anymore. Fixes [docker/for-mac#5271](https://github.com/docker/for-mac/issues/5271)
* Fixed a navigation issue in the **Containers / Apps** view. Fixes [docker/for-win#10160](https://github.com/docker/for-win/issues/10160#issuecomment-764660660)
* Fixed container instance view with long container/image name. Fixes [docker/for-mac#5290](https://github.com/docker/for-mac/issues/5290)
* Fixed an issue when binding ports on specific IPs. Note: It may now take a bit of time before the `docker inspect` command shows the open ports. Fixes [docker/for-mac#4541](https://github.com/docker/for-mac/issues/4541)
* Fixed an issue where an image deleted from the Docker dashboard was still displayed on the **Images** view.

### [Known issue](#known-issue)

Docker Desktop can sometimes fail to start after updating to version 3.2.0. If you are experiencing this issue, we recommend that you uninstall 3.2.0 and manually install [Docker Desktop 3.2.1](#docker-desktop-321). See [docker/for-mac#5406](https://github.com/docker/for-mac/issues/5406).

## [Docker Desktop 3.1.0](#docker-desktop-310)

2021-01-14

### [New](#new-7)

* Docker daemon now runs within a Debian Buster based container (instead of Alpine).

### [Upgrades](#upgrades-9)

* [Compose CLI v1.0.7](https://github.com/docker/compose-cli/tree/v1.0.7)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-12)

* Fixed UI reliability issues when users create or delete a lot of objects in batches.
* Fixed an issue with DNS address resolution in Alpine containers. Fixes [docker/for-mac#5020](https://github.com/docker/for-mac/issues/5020).
* Redesigned the **Support** UI to improve usability.

## [Docker Desktop 3.0.4](#docker-desktop-304)

2021-01-06

### [Upgrades](#upgrades-10)

* [Docker Engine 20.10.2](https://docs.docker.com/engine/release-notes/20.10/#20102)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-13)

* Avoid timeouts during `docker-compose up` by making cache invalidation faster. Fixes [docker/for-mac#4957](https://github.com/docker/for-mac/issues/4957).
* Avoid generating a spurious filesystem DELETE event while invalidating caches. Fixes [docker/for-mac#5124](https://github.com/docker/for-mac/issues/5124).

### [Known issues](#known-issues-2)

* Some DNS addresses fail to resolve within containers based on Alpine Linux 3.13. See [docker/for-mac#5020](https://github.com/docker/for-mac/issues/5020).

## [Docker Desktop 3.0.3](#docker-desktop-303)

2020-12-21

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-14)

* Fixed an issue that caused overlapping volume mounts to fail. Fixes [docker/for-mac#5157](https://github.com/docker/for-mac/issues/5157). However, the fixes for [docker/for-mac#4957](https://github.com/docker/for-mac/issues/4957) and [docker/for-mac#5124](https://github.com/docker/for-mac/issues/5124) have been reverted as a result of this change, so those issues are now present again.

### [Known issues](#known-issues-3)

* Some DNS addresses fail to resolve within containers based on Alpine Linux 3.13. See [docker/for-mac#5020](https://github.com/docker/for-mac/issues/5020).
* There can be timeouts during docker-compose up if there are several services being started. See [docker/for-mac#4957](https://github.com/docker/for-mac/issues/4957) and [docker/for-mac#5124](https://github.com/docker/for-mac/issues/5124).

## [Docker Desktop 3.0.2](#docker-desktop-302)

2020-12-18

\### Bug fixes and minor changes

* Avoid timeouts during `docker-compose up` by making cache invalidation faster. Fixes [docker/for-mac#4957](https://github.com/docker/for-mac/issues/4957).
* Avoid generating a spurious filesystem DELETE event while invalidating caches. Fixes [docker/for-mac#5124](https://github.com/docker/for-mac/issues/5124).
* It is now possible to share directories in `~/Library` (except Docker Desktop data directories) with a container. Fixes [docker/for-mac#5115](https://github.com/docker/for-mac/issues/5115).
* You will now see a performance warning pop-up message if you create a container that shares the `Home` or a user `Library` directory.

### [Known issues](#known-issues-4)

* Some DNS addresses fail to resolve within containers based on Alpine Linux 3.13. See [docker/for-mac#5020](https://github.com/docker/for-mac/issues/5020).

## [Docker Desktop 3.0.1](#docker-desktop-301)

2020-12-11

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-15)

* Fixed an issue that caused certain directories not to be mountable into containers. Fixes [docker/for-mac#5115](https://github.com/docker/for-mac/issues/5115). See Known issues below.

### [Known issues](#known-issues-5)

* It is currently not possible to bind mount files within `~/Library` into a container. See [docker/for-mac#5115](https://github.com/docker/for-mac/issues/5115).
* Building an image with BuildKit from a git URL fails when using the form `github.com/org/repo`. To work around this issue, use the form `git://github.com/org/repo`.
* Some DNS addresses fail to resolve within containers based on Alpine Linux 3.13. See [docker/for-mac#5020](https://github.com/docker/for-mac/issues/5020).

## [Docker Desktop 3.0.0](#docker-desktop-300)

2020-12-10

### [New](#new-8)

* Use of three-digit version number for Docker Desktop releases.

* Starting with Docker Desktop 3.0.0, updates are now much smaller as they will be applied using delta patches.

* First version of `docker compose` (as an alternative to the existing `docker-compose`). Supports some basic commands but not the complete functionality of `docker-compose` yet.

  * Supports the following subcommands: `up`, `down`, `logs`, `build`, `pull`, `push`, `ls`, `ps`

  * Supports basic volumes, bind mounts, networks, and environment variables

    Let us know your feedback by creating an issue in the [compose-cli](https://github.com/docker/compose-cli/issues) GitHub repository.

* [Docker Hub Tool v0.2.0](https://github.com/docker/roadmap/issues/117)

### [Upgrades](#upgrades-11)

* [Docker Engine 20.10.0](https://docs.docker.com/engine/release-notes/20.10/#20100)
* [Go 1.15.6](https://github.com/golang/go/issues?q=milestone%3AGo1.15.6+label%3ACherryPickApproved+)
* [Compose CLI v1.0.4](https://github.com/docker/compose-cli/releases/tag/v1.0.4)
* [Snyk v1.432.0](https://github.com/snyk/snyk/releases/tag/v1.432.0)

### [Bug fixes and minor changes](#bug-fixes-and-minor-changes-16)

* Downgraded the kernel to [4.19.121](https://hub.docker.com/layers/docker/for-desktop-kernel/4.19.121-2a1dbedf3f998dac347c499808d7c7e029fbc4d3-amd64/images/sha256-4e7d94522be4f25f1fbb626d5a0142cbb6e785f37e437f6fd4285e64a199883a?context=repo) to reduce the CPU usage of hyperkit. Fixes [docker/for-mac#5044](https://github.com/docker/for-mac/issues/5044)
* Avoid caching bad file sizes and modes when using `osxfs`. Fixes [docker/for-mac#5045](https://github.com/docker/for-mac/issues/5045).
* Fixed a possible file sharing error where a file may appear to have the wrong size in a container when it is modified on the host. This is a partial fix for [docker/for-mac#4999](https://github.com/docker/for-mac/issues/4999).
* Removed unnecessary log messages which slow down filesystem event injection.
* Re-enabled the experimental SOCKS proxy. Fixes [docker/for-mac#5048](https://github.com/docker/for-mac/issues/5048).
* Fixed an unexpected EOF error when trying to start a non-existing container with `-v /var/run/docker.sock:`. See [docker/for-mac#5025](https://github.com/docker/for-mac/issues/5025).
* Display an error message instead of crashing when the application needs write access on specific directories. See [docker/for-mac#5068](https://github.com/docker/for-mac/issues/5068)

### [Known issues](#known-issues-6)

* Building an image with BuildKit from a git URL fails when using the form `github.com/org/repo`. To work around this issue, use the form `git://github.com/org/repo`.
* Some DNS addresses fail to resolve within containers based on Alpine Linux 3.13.

----
url: https://docs.docker.com/reference/api/dvp/latest/
----

# Docker Verified Publisher API reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Verified Publisher API.

* [Open Markdown](https://docs.docker.com/reference/api/dvp/latest.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/dvp/latest.yaml)

[](/reference)

* API

  * Authentication Endpoints

    * postCreate an authentication token
    * postSecond factor authentication

  * Discovery

    * getGet namespaces and repos
    * getGet user's namespaces
    * getGet namespace

  * Namespace data

    * getGet pull data
    * getGet pull data
    * getGet years with data
    * getGet timespans with data
    * getGet namespace metadata for timespan
    * getGet namespace data for timespan
    * getGet pull data for multiple repos

* Models

  * ResponseDataFile
  * Year Data Model
  * Month Data Model
  * Week Data Model

[API docs by Redocly](https://redocly.com/redoc/)

# DVP Data API (1.0.0)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/dvp/latest.yaml)

The Docker DVP Data API allows [Docker Verified Publishers](https://docs.docker.com/docker-hub/publish/) to view image pull analytics data for their namespaces. Analytics data can be retrieved in a CSV as raw data, or in a summary format.

#### Summary data

In your summary data CSV, you will have access to the data points listed below. You can request summary data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month).

There are two levels of summary data:

* Repository-level, a summary of every namespace and repository
* Tag- or digest-level, a summary of every namespace, repository, and reference (tag or digest)

The summary data formats contain the following data points:

* Unique IP address count
* Pulls by tag count
* Pulls by digest count
* Version check count

#### Raw data

In your raw data CSV you will have access to the data points listed below. You can request raw data for a complete week (Monday through Sunday) or for a complete month (available on the first day of the following month). **Note:** each action is represented as a single row.

* Type (industry)

* Host (cloud provider)

* Country (geolocation)

* Timestamp

* Namespace

* Repository

* Reference (digest is always included, tag is provided when available)

* HTTP request method

* Action, one of the following:

  * Pull by tag
  * Pull by digest
  * Version check

* User-Agent

## [](#tag/authentication)Authentication Endpoints

## [](#tag/authentication/operation/PostUsersLogin)Create an authentication token

Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.

The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.

Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.

##### Request Body schema: application/jsonrequired

Login details.

|                  |                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| usernamerequired | stringThe username of the Docker Hub account to authenticate with.                                |
| passwordrequired | stringThe password or personal access token (PAT) of the Docker Hub account to authenticate with. |

### Responses

/v2/users/login

### Request samples

* Payload

Content type

application/json

`{
"username": "myusername",
"password": "hunter2"

## [](#tag/authentication/operation/PostUsers2FALogin)Second factor authentication

When a user has 2FA enabled, this is the second call to perform after `/v2/users/login` call.

Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.

The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.

Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.

##### Request Body schema: application/jsonrequired

Login details.

|                           |                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------- |
| login\_2fa\_tokenrequired | stringThe intermediate 2FA token returned from `/v2/users/login` API.                  |
| coderequired              | stringThe Time-based One-Time Password of the Docker Hub account to authenticate with. |

### Responses

/v2/users/2fa-login

## [](#tag/discovery)Discovery

## [](#tag/discovery/operation/getNamespaces)Get namespaces and repos

Gets a list of your namespaces and repos which have data available.

##### Authorizations:

*Docker Hub Authentication*

### Responses

/api/publisher/analytics/v1/

### Response samples

* 200

Content type

application/json

`{
"namespaces": [
"string"
]
}`

## [](#tag/discovery/operation/getUserNamespaces)Get user's namespaces

Get metadata associated with the namespaces the user has access to, including extra repos associated with the namespaces.

##### Authorizations:

*Docker Hub Authentication*

### Responses

/api/publisher/analytics/v1/namespaces

### Response samples

* 200

Content type

application/json

`[
{
"namespace": "string",
"extraRepos": [
"string"
],
"datasets": [
{
"name": "pulls",
"views": [
"raw"
],
"timespans": [
"months"
]
}
]
}
]`

## [](#tag/discovery/operation/getNamespace)Get namespace

Gets metadata associated with specified namespace, including extra repos associated with the namespace.

##### Authorizations:

*Docker Hub Authentication*

##### path Parameters

|                   |                                   |
| ----------------- | --------------------------------- |
| namespacerequired | stringNamespace to fetch data for |

### Responses

/api/publisher/analytics/v1/namespaces/{namespace}

### Response samples

* 200

Content type

application/json

`{
"namespace": "string",
"extraRepos": [
"string"
],
"datasets": [
{
"name": "pulls",
"views": [
"raw"
],
"timespans": [
"months"
]
}
]
}`

## [](#tag/namespaces)Namespace data

## [](#tag/namespaces/operation/getNamespacePulls)Get pull data

Gets pulls for the given namespace.

##### Authorizations:

*Docker Hub Authentication*

##### path Parameters

|                   |                                   |
| ----------------- | --------------------------------- |
| namespacerequired | stringNamespace to fetch data for |

##### query Parameters

|          |                                                                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| timespan | string (TimespanType)Enum: "months" "weeks"Timespan type for fetching data                                                           |
| period   | string (PeriodType)Enum: "last-2-months" "last-3-months" "last-6-months" "last-12-months"Relative period of the period to fetch data |
| group    | string (GroupType)Enum: "repo" "namespace"Field to group the data by                                                                 |

### Responses

/api/publisher/analytics/v1/namespaces/{namespace}/pulls

### Response samples

* 200

Content type

application/json

`{
"pulls": [
{
"start": "string",
"end": "string",
"repo": "string",
"namespace": "string",
"pullCount": 0,
"ipCount": 0,
"country": "string"
}
]
}`

## [](#tag/namespaces/operation/getRepoPulls)Get pull data

Gets pulls for the given repo.

##### Authorizations:

*Docker Hub Authentication*

##### path Parameters

|                   |                                    |
| ----------------- | ---------------------------------- |
| namespacerequired | stringNamespace to fetch data for  |
| reporequired      | stringRepository to fetch data for |

##### query Parameters

|          |                                                                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| timespan | string (TimespanType)Enum: "months" "weeks"Timespan type for fetching data                                                           |
| period   | string (PeriodType)Enum: "last-2-months" "last-3-months" "last-6-months" "last-12-months"Relative period of the period to fetch data |
| group    | string (GroupType)Enum: "repo" "namespace"Field to group the data by                                                                 |

### Responses

/api/publisher/analytics/v1/namespaces/{namespace}/repos/{repo}/pulls

### Response samples

* 200

Content type

application/json

`{
"pulls": [
{
"start": "string",
"end": "string",
"repo": "string",
"namespace": "string",
"pullCount": 0,
"ipCount": 0,
"country": "string"
}
]
}`

## [](#tag/namespaces/operation/getNamespaceYears)Get years with data

Gets a list of years that have data for the given namespace.

##### Authorizations:

*Docker Hub Authentication*

##### path Parameters

|                   |                                   |
| ----------------- | --------------------------------- |
| namespacerequired | stringNamespace to fetch data for |

### Responses

/api/publisher/analytics/v1/namespaces/{namespace}/pulls/exports/years

### Response samples

* 200

Content type

application/json

`{
"years": [
{
"year": 0
}
]
}`

## [](#tag/namespaces/operation/getNamespaceTimespans)Get timespans with data

Gets a list of timespans of the given type that have data for the given namespace and year.

##### Authorizations:

*Docker Hub Authentication*

##### path Parameters

|                      |                                                                               |
| -------------------- | ----------------------------------------------------------------------------- |
| namespacerequired    | stringNamespace to fetch data for                                             |
| yearrequired         | integerYear to fetch data for                                                 |
| timespantyperequired | string (TimespanType)Enum: "months" "weeks"Type of timespan to fetch data for |

### Responses

/api/publisher/analytics/v1/namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}

### Response samples

* 200

Content type

application/json

Example

MonthData

`{
"months": [
{
"month": 0
}
]
}`

## [](#tag/namespaces/operation/getNamespaceTimespanMetadata)Get namespace metadata for timespan

Gets info about data for the given namespace and timespan.

##### Authorizations:

*Docker Hub Authentication*

##### path Parameters

|                      |                                                                               |
| -------------------- | ----------------------------------------------------------------------------- |
| namespacerequired    | stringNamespace to fetch data for                                             |
| yearrequired         | integerYear to fetch data for                                                 |
| timespantyperequired | string (TimespanType)Enum: "months" "weeks"Type of timespan to fetch data for |
| timespanrequired     | integerTimespan to fetch data for                                             |

### Responses

/api/publisher/analytics/v1/namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}/{timespan}

### Response samples

* 200

Content type

application/json

Example

MonthModel

`{
"month": 0
}`

## [](#tag/namespaces/operation/getNamespaceDataByTimespan)Get namespace data for timespan

Gets a list of URLs that can be used to download the pull data for the given namespace and timespan.

##### Authorizations:

*Docker Hub Authentication*

##### path Parameters

|                      |                                                                                                    |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| namespacerequired    | stringNamespace to fetch data for                                                                  |
| yearrequired         | integerYear to fetch data for                                                                      |
| timespantyperequired | string (TimespanType)Enum: "months" "weeks"Type of timespan to fetch data for                      |
| timespanrequired     | integerTimespan to fetch data for                                                                  |
| dataviewrequired     | string (DataviewType)Enum: "raw" "summary" "repo-summary" "namespace-summary"Type of data to fetch |

### Responses

/api/publisher/analytics/v1/namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}/{timespan}/{dataview}

### Response samples

* 200

Content type

application/json

`{
"data": [
{
"url": "string",
"size": 0
}
]
}`

## [](#tag/namespaces/operation/getManyReposPulls)Get pull data for multiple repos

Gets pull for the given repos.

##### Authorizations:

*Docker Hub Authentication*

##### query Parameters

|               |                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| reposrequired | Array of stringsRepositories to fetch data for (maximum of 50 repositories per request).                                             |
| timespan      | string (TimespanType)Enum: "months" "weeks"Timespan type for fetching data                                                           |
| period        | string (PeriodType)Enum: "last-2-months" "last-3-months" "last-6-months" "last-12-months"Relative period of the period to fetch data |
| group         | string (GroupType)Enum: "repo" "namespace"Field to group the data by                                                                 |

### Responses

/api/publisher/analytics/v1/repos/pulls

### Response samples

* 200

Content type

application/json

`{
"repos": {
"property1": {
"pulls": [
{
"start": "string",
"end": "string",
"repo": "string",
"namespace": "string",
"pullCount": 0,
"ipCount": 0,
"country": "string"
}
]
},
"property2": {
"pulls": [
{
"start": "string",
"end": "string",
"repo": "string",
"namespace": "string",
"pullCount": 0,
"ipCount": 0,
"country": "string"
}
]
}
}
}`

## [](#tag/responseDataFile)ResponseDataFile

|      |                  |
| ---- | ---------------- |
| url  | string           |
| size | integer \<int64> |

`{
"url": "string",
"size": 0
}`

## [](#tag/yearModel)Year Data Model

|      |         |
| ---- | ------- |
| year | integer |

`{
"year": 0
}`

## [](#tag/monthModel)Month Data Model

|       |         |
| ----- | ------- |
| month | integer |

`{
"month": 0
}`

## [](#tag/weekModel)Week Data Model

|      |         |
| ---- | ------- |
| week | integer |

`{
"week": 0
}`

----
url: https://docs.docker.com/dhi/explore/build-process/
----

# How Docker Hardened Images are built

***

Table of contents

***

Docker Hardened Images are built through an automated pipeline that monitors upstream sources, applies security updates, and publishes signed artifacts. This page explains the build process for both base DHI images and customized images available with DHI Select and DHI Enterprise subscriptions.

With DHI Select or DHI Enterprise subscriptions, the automated security update pipeline for both base and customized images is backed by [SLA commitments](https://docs.docker.com/go/dhi-sla/), including a 7-day SLA for critical and high severity vulnerabilities. DHI Community offers a secure baseline but no guaranteed remediation timelines.

## [Build transparency](#build-transparency)

Docker Hardened Images provide transparency into how images are built through publicly available definitions and verifiable attestations.

### [Image definitions](#image-definitions)

All image definitions are publicly available in the [catalog repository](https://github.com/docker-hardened-images/catalog).

Each image definition is a declarative YAML specification that includes metadata, contents, build pipeline steps, security configurations, and runtime settings.

### [SLSA attestations](#slsa-attestations)

Every Docker Hardened Image includes a SLSA Build Level 3 attestation that provides verifiable build provenance. For details on SLSA attestations and how to verify them, see [SLSA](https://docs.docker.com/dhi/core-concepts/slsa/).

## [Build triggers](#build-triggers)

Builds start automatically. You don't trigger them manually. The system monitors for changes and starts builds in two scenarios:

* [Upstream updates](#upstream-updates)
* [Customization changes](#customization-changes)

### [Upstream updates](#upstream-updates)

New releases, package updates, or CVE fixes from upstream projects trigger base image rebuilds. These builds go through quality checks to ensure security and reliability.

#### [Monitoring for updates](#monitoring-for-updates)

Docker continuously monitors upstream projects for new releases, package updates, and security advisories. When changes are detected, the system automatically queues affected images for rebuild using a SLSA Build Level 3-compliant build system.

Docker uses three strategies to track updates:

* GitHub releases: Monitors specific GitHub repositories for new releases and automatically updates the image definition when a new version is published.
* GitHub tags: Tracks tags in GitHub repositories to detect new versions.
* Package repositories: Monitors Alpine Linux, Debian, and Ubuntu package repositories through Docker Scout's package database to detect updated packages.

In addition to explicit upstream tracking, Docker also monitors transitive dependencies. When a package update is detected (for example, a security patch for a library), Docker automatically identifies and rebuilds all images within the support window that use that package.

### [Customization changes](#customization-changes)

Subscription: Docker Hardened Images Select or Enterprise

Updates to your OCI artifact customizations trigger rebuilds of your customized images.

When you customize a DHI image with DHI Select or DHI Enterprise, your changes are packaged as OCI artifacts that layer on top of the base image. Docker monitors your artifact repositories and automatically rebuilds your customized images whenever you push updates.

The rebuild process fetches the current base image, applies your OCI artifacts, signs the result, and publishes it automatically. You don't need to manage builds or maintain CI pipelines for your customized images.

Customized images are also rebuilt automatically when the base DHI image they depend on receives updates, ensuring your images always include the latest security patches.

## [Build pipeline](#build-pipeline)

The following sections describe the build pipeline architecture and workflow for Docker Hardened Images based on:

* [Base image pipeline](#base-image-pipeline)
* [Customized image pipeline](#customized-image-pipeline)

### [Base image pipeline](#base-image-pipeline)

Each Docker Hardened Image is built through an automated pipeline:

1. Monitoring: Docker monitors upstream sources for updates (new releases, package updates, security advisories).
2. Rebuild trigger: When changes are detected, an automated rebuild starts.
3. AI guardrail: An AI system fetches upstream diffs and scans them with language-aware checks. The guardrail focuses on high-leverage issues that can cause significant problems, such as inverted error checks, ignored failures, resource mishandling, or suspicious contributor activity. When it spots potential risks, it blocks the PR from auto-merging.
4. Human review: If the AI identifies risks with high confidence, Docker engineers review the flagged code, reproduce the issue, and decide on the appropriate action. Engineers often contribute fixes back to upstream projects, improving the code for the entire community. When fixes are accepted upstream, the DHI build pipeline applies the patch immediately to protect customers while the fix moves through the upstream release process.
5. Testing and scanning: Images undergo comprehensive [testing](https://docs.docker.com/dhi/explore/test/) for compatibility and functionality, and are [scanned for malware](https://docs.docker.com/dhi/explore/malware-scanning/), secrets, and vulnerabilities.
6. Signing and attestations: Docker signs each image and generates attestations (SBOMs, VEX documents, build provenance).
7. Publishing: The signed image is published to the DHI registry and the attestations are published to the Docker Scout registry.
8. Cascade rebuilds: If any customized images use this base, their rebuilds are automatically triggered.

Docker responds quickly to critical vulnerabilities. By building essential components from source rather than waiting for packaged updates, Docker can patch critical and high severity CVEs within days of upstream fixes and publish updated images with new attestations. For DHI Enterprise subscriptions, this rapid response is backed by a [7-day SLA for critical and high severity vulnerabilities](https://docs.docker.com/go/dhi-sla/).

The following diagram shows the base image build flow:

### [Customized image pipeline](#customized-image-pipeline)

Subscription: Docker Hardened Images Select or Enterprise

When you customize a DHI image with DHI Select or DHI Enterprise, the build process is simplified:

1. Monitoring: Docker monitors your OCI artifact repositories for changes.
2. Rebuild trigger: When you push updates to your OCI artifacts, or when the base DHI image is updated, an automated rebuild starts.
3. Fetch base image: The latest base DHI image is fetched.
4. Apply customizations: Your OCI artifacts are applied to the base image.
5. Scanning: The customized image is [scanned for malware](https://docs.docker.com/dhi/explore/malware-scanning/), secrets, and vulnerabilities.
6. Signing and attestations: Docker signs the customized image and generates attestations (SBOMs, VEX documents, build provenance).
7. Publishing: The signed customized image is published to Docker Hub and the attestations are published to the Docker Scout registry.

Docker handles the entire process automatically, so you don't need to manage builds for your customized images. However, you're responsible for testing your customized images and managing any CVEs introduced by your OCI artifacts.

The following diagram shows the customized image build flow:

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/build/
----

# docker dhi customization build

***

| Description | Manage customization builds |
| ----------- | --------------------------- |

## [Description](#description)

Commands to manage Docker Hardened Images customization builds

## [Subcommands](#subcommands)

| Command                                                                                                             | Description                    |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`docker dhi customization build get`](https://docs.docker.com/reference/cli/docker/dhi/customization/build/get/)   | Get details of a build         |
| [`docker dhi customization build list`](https://docs.docker.com/reference/cli/docker/dhi/customization/build/list/) | List builds of a customization |
| [`docker dhi customization build logs`](https://docs.docker.com/reference/cli/docker/dhi/customization/build/logs/) | Get logs of a build            |

----
url: https://docs.docker.com/scout/integrations/ci/azure/
----

# Integrate Docker Scout with Microsoft Azure DevOps Pipelines

***

***

The following examples runs in an Azure DevOps-connected repository containing a Docker image's definition and contents. Triggered by a commit to the main branch, the pipeline builds the image and uses Docker Scout to create a CVE report.

First, set up the rest of the workflow and set up the variables available to all pipeline steps. Add the following to an *azure-pipelines.yml* file:

```yaml
trigger:
  - main

resources:
  - repo: self

variables:
  tag: "$(Build.BuildId)"
  image: "vonwig/nodejs-service"
```

This sets up the workflow to use a particular container image for the application and tag each new image build with the build ID.

Add the following to the YAML file:

```yaml
stages:
  - stage: Build
    displayName: Build image
    jobs:
      - job: Build
        displayName: Build
        pool:
          vmImage: ubuntu-latest
        steps:
          - task: Docker@2
            displayName: Build an image
            inputs:
              command: build
              dockerfile: "$(Build.SourcesDirectory)/Dockerfile"
              repository: $(image)
              tags: |
                $(tag)
          - task: CmdLine@2
            displayName: Find CVEs on image
            inputs:
              script: |
                # Install the Docker Scout CLI
                curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s --
                # Login to Docker Hub required for Docker Scout CLI
                echo $(DOCKER_HUB_PAT) | docker login -u $(DOCKER_HUB_USER) --password-stdin
                # Get a CVE report for the built image and fail the pipeline when critical or high CVEs are detected
                docker scout cves $(image):$(tag) --exit-code --only-severity critical,high
```

This creates the flow mentioned previously. It builds and tags the image using the checked-out Dockerfile, downloads the Docker Scout CLI, and then runs the `cves` command against the new tag to generate a CVE report. It only shows critical or high-severity vulnerabilities.

----
url: https://docs.docker.com/reference/build-checks/reserved-stage-name/
----

# ReservedStageName

***

Table of contents

***

## [Output](#output)

```text
'scratch' is reserved and should not be used as a stage name
```

## [Description](#description)

Reserved words should not be used as names for stages in multi-stage builds. The reserved words are:

* `context`
* `scratch`

## [Examples](#examples)

❌ Bad: `scratch` and `context` are reserved names.

```dockerfile
FROM alpine AS scratch
FROM alpine AS context
```

✅ Good: the stage name `builder` is not reserved.

```dockerfile
FROM alpine AS builder
```

----
url: https://docs.docker.com/ai/docker-agent/local-models/
----

# Local models with Docker Model Runner

***

Table of contents

***

Docker Model Runner lets you run AI models locally on your machine. No API keys, no recurring costs, and your data stays private.

## [Why use local models](#why-use-local-models)

Docker Model Runner lets you run models locally without API keys or recurring costs. Your data stays on your machine, and you can work offline once models are downloaded. This is an alternative to [cloud model providers](https://docs.docker.com/ai/docker-agent/model-providers/).

## [Prerequisites](#prerequisites)

You need Docker Model Runner installed and running:

* Docker Desktop (macOS/Windows) - Enable Docker Model Runner in **Settings > AI > Enable Docker Model Runner**. See [Get started with DMR](https://docs.docker.com/ai/model-runner/get-started/#enable-docker-model-runner) for detailed instructions.
* Docker Engine (Linux) - Install with `sudo apt-get install docker-model-plugin` or `sudo dnf install docker-model-plugin`. See [Get started with DMR](https://docs.docker.com/ai/model-runner/get-started/#docker-engine).

Verify Docker Model Runner is available:

```console
$ docker model version
```

If the command returns version information, you're ready to use local models.

## [Using models with DMR](#using-models-with-dmr)

Docker Model Runner can run any compatible model. Models can come from:

* Docker Hub repositories (`docker.io/namespace/model-name`)
* Your own OCI artifacts packaged and pushed to any registry
* HuggingFace models directly (`hf.co/org/model-name`)
* The Docker Model catalog in Docker Desktop

To see models available to the local Docker catalog, run:

```console
$ docker model list --openai
```

To use a model, reference it in your configuration. DMR automatically pulls models on first use if they're not already local.

## [Configuration](#configuration)

Configure your agent to use Docker Model Runner with the `dmr` provider:

```yaml
agents:
  root:
    model: dmr/ai/qwen3
    instruction: You are a helpful assistant
    toolsets:
      - type: filesystem
```

When you first run your agent, Docker Agent prompts you to pull the model if it's not already available locally:

```console
$ docker agent run agent.yaml
Model not found locally. Do you want to pull it now? ([y]es/[n]o)
```

## [How it works](#how-it-works)

When you configure an agent to use DMR, Docker Agent automatically connects to your local Docker Model Runner and routes inference requests to it. If a model isn't available locally, Docker Agent prompts you to pull it on first use. No API keys or authentication are required.

## [Advanced configuration](#advanced-configuration)

For more control over model behavior, define a model configuration:

```yaml
models:
  local-qwen:
    provider: dmr
    model: ai/qwen3:14B
    temperature: 0.7
    max_tokens: 8192

agents:
  root:
    model: local-qwen
    instruction: You are a helpful coding assistant
```

### [Faster inference with speculative decoding](#faster-inference-with-speculative-decoding)

Speed up model responses using speculative decoding with a smaller draft model:

```yaml
models:
  fast-qwen:
    provider: dmr
    model: ai/qwen3:14B
    provider_opts:
      speculative_draft_model: ai/qwen3:0.6B-Q4_K_M
      speculative_num_tokens: 16
      speculative_acceptance_rate: 0.8
```

The draft model generates token candidates, and the main model validates them. This can significantly improve throughput for longer responses.

### [Runtime flags](#runtime-flags)

Pass engine-specific flags to optimize performance:

```yaml
models:
  optimized-qwen:
    provider: dmr
    model: ai/qwen3
    provider_opts:
      runtime_flags: ["--ngl=33", "--threads=8"]
```

Common flags:

* `--ngl` - Number of GPU layers
* `--threads` - CPU thread count
* `--repeat-penalty` - Repetition penalty

## [Using DMR for RAG](#using-dmr-for-rag)

Docker Model Runner supports both embeddings and reranking for RAG workflows.

### [Embedding with DMR](#embedding-with-dmr)

Use local embeddings for indexing your knowledge base:

```yaml
rag:
  codebase:
    docs: [./src]
    strategies:
      - type: chunked-embeddings
        embedding_model: dmr/ai/embeddinggemma
        database: ./code.db
```

### [Reranking with DMR](#reranking-with-dmr)

DMR provides native reranking for improved RAG results:

```yaml
models:
  reranker:
    provider: dmr
    model: hf.co/ggml-org/qwen3-reranker-0.6b-q8_0-gguf

rag:
  docs:
    docs: [./documentation]
    strategies:
      - type: chunked-embeddings
        embedding_model: dmr/ai/embeddinggemma
        limit: 20
    results:
      reranking:
        model: reranker
        threshold: 0.5
      limit: 5
```

Native DMR reranking is the fastest option for reranking RAG results.

## [Troubleshooting](#troubleshooting)

If Docker Agent can't find Docker Model Runner:

1. Verify Docker Model Runner status:

   ```console
   $ docker model status
   ```

2. Check available models:

   ```console
   $ docker model list
   ```

3. Check model logs for errors:

   ```console
   $ docker model logs
   ```

4. Ensure Docker Desktop has Model Runner enabled in settings (macOS/Windows)

## [What's next](#whats-next)

* Follow the [tutorial](https://docs.docker.com/ai/docker-agent/tutorial/) to build your first agent with local models
* Learn about [RAG](https://docs.docker.com/ai/docker-agent/rag/) to give your agents access to codebases and documentation
* See the [configuration reference](https://docs.docker.com/ai/docker-agent/reference/config/#docker-model-runner-dmr) for all DMR options

----
url: https://docs.docker.com/docker-hub/repos/manage/hub-images/bulk-migrate/
----

# Bulk migrate images

***

Table of contents

***

This guide shows you how to migrate Docker images in bulk between Docker Hub organizations or namespaces. Whether you're consolidating repositories, changing organization structure, or moving images to a new account, these techniques help you migrate efficiently while preserving image integrity.

The topic is structured to build up in scale:

1. [Migrate a single image tag](#migrate-a-single-image-tag)
2. [Migrate all tags for a repository](#migrate-all-tags-for-a-repository)
3. [Migrate multiple repositories](#migrate-multiple-repositories)

The recommended tool for this workflow is `crane`. An equivalent alternative using `regctl` is also shown. Both tools perform registry-to-registry copies without pulling images locally and preserve multi-architecture images.

`crane` is recommended for its simplicity and focused image-copying workflow. `regctl` is also a good choice, particularly if you already use it for broader registry management tasks beyond image copying.

> Note
>
> The main workflows in this topic operate on tagged images only. Untagged manifests or content no longer reachable from tags are not migrated. In practice, these are usually unused artifacts, but be aware of this limitation before migration. While you can migrate specific untagged manifests using [digest references](#migrate-by-digest), there is no API to enumerate untagged manifests in a repository.

## [Prerequisites](#prerequisites)

Before you begin, ensure you have:

* One of the following installed and available in your `$PATH`:

  * [`crane`](https://github.com/google/go-containerregistry)
  * [`regctl`](https://regclient.org/usage/regctl/)

* Push access to both the source and destination organizations

* Registry authentication configured for your chosen tool

## [Authenticate to registries](#authenticate-to-registries)

Both tools authenticate directly against registries:

* `crane` uses Docker credential helpers and `~/.docker/config.json`. See the [crane documentation](https://github.com/google/go-containerregistry/tree/main/cmd/crane/doc).
* `regctl` uses its own configuration file and can import Docker credentials. See the [regctl documentation](https://github.com/regclient/regclient/tree/main/docs).

Follow the authentication instructions for your registry and tool of choice.

## [Migrate a single image tag](#migrate-a-single-image-tag)

This is the simplest and most common migration scenario.

The following example script copies the image manifest directly between registries and preserves multi-architecture images when present. Repeat this process for each tag you want to migrate. Replace the environment variable values with your source and destination organization names, repository name, and tag.

```bash
#!/usr/bin/env bash
set -euo pipefail

SRC_ORG="oldorg"
DEST_ORG="neworg"
REPO="myapp"
TAG="1.2.3"

SRC_IMAGE="${SRC_ORG}/${REPO}:${TAG}"
DEST_IMAGE="${DEST_ORG}/${REPO}:${TAG}"

# Using crane (recommended)
crane cp "${SRC_IMAGE}" "${DEST_IMAGE}"

# Using regctl (alternative)
# regctl image copy "${SRC_IMAGE}" "${DEST_IMAGE}"
```

### [Migrate by digest](#migrate-by-digest)

To migrate a specific image by digest instead of tag, use the digest in the source reference. This is useful when you need to migrate an exact image version, even if the tag has been updated. Replace the environment variable values with your source and destination organization names, repository name, digest, and tag. You can choose between `crane` and `regctl` for the copy operation.

```bash
#!/usr/bin/env bash
set -euo pipefail

SRC_ORG="oldorg"
DEST_ORG="neworg"
REPO="myapp"
DIGEST="sha256:abcd1234..."
TAG="stable"

SRC_IMAGE="${SRC_ORG}/${REPO}@${DIGEST}"
DEST_IMAGE="${DEST_ORG}/${REPO}:${TAG}"

# Using crane
crane cp "${SRC_IMAGE}" "${DEST_IMAGE}"

# Using regctl
# regctl image copy "${SRC_IMAGE}" "${DEST_IMAGE}"
```

## [Migrate all tags for a repository](#migrate-all-tags-for-a-repository)

To migrate every tagged image in a repository, use the Docker Hub API to enumerate tags and copy each one. The following example script retrieves all tags for a given repository and migrates them in a loop. This approach scales to repositories with many tags without overwhelming local resources. Note that there is a rate limit on Docker Hub requests, so you may need to add delays or pagination handling for large repositories.

Replace the environment variable values with your source and destination organization names and repository name. If your source repository is private, also set `HUB_USER` and `HUB_TOKEN` with credentials that have pull access. You can also choose between `crane` and `regctl` for the copy operation.

```bash
#!/usr/bin/env bash
set -euo pipefail

# Use environment variables if set, otherwise use defaults
SRC_ORG="${SRC_ORG:-oldorg}"
DEST_ORG="${DEST_ORG:-neworg}"
REPO="${REPO:-myapp}"

# Optional: for private repositories
# HUB_USER="your-username"
# HUB_TOKEN="your-access-token"
# AUTH="-u ${HUB_USER}:${HUB_TOKEN}"
AUTH=""

TOOL="crane"   # or: TOOL="regctl"

TAGS_URL="https://hub.docker.com/v2/repositories/${SRC_ORG}/${REPO}/tags?page_size=100"

while [[ -n "${TAGS_URL}" && "${TAGS_URL}" != "null" ]]; do
  RESP=$(curl -fsSL ${AUTH} "${TAGS_URL}")

  echo "${RESP}" | jq -r '.results[].name' | while read -r TAG; do
    [[ -z "${TAG}" ]] && continue

    SRC_IMAGE="${SRC_ORG}/${REPO}:${TAG}"
    DEST_IMAGE="${DEST_ORG}/${REPO}:${TAG}"

    echo "Migrating ${SRC_IMAGE} → ${DEST_IMAGE}"

    case "${TOOL}" in
      crane)
        crane cp "${SRC_IMAGE}" "${DEST_IMAGE}"
        ;;
      regctl)
        regctl image copy "${SRC_IMAGE}" "${DEST_IMAGE}"
        ;;
    esac
  done

  TAGS_URL=$(echo "${RESP}" | jq -r '.next')
done
```

> Note
>
> Docker Hub automatically creates the destination repository on first push if your account has permission.

## [Migrate multiple repositories](#migrate-multiple-repositories)

To migrate several repositories, create a list and run the single-repository script for each one.

For example, create a `repos.txt` file with repository names:

```text
api
web
worker
```

Save the script from the previous section as `migrate-single-repo.sh`. Then, run the following example script that processes each repository in the file. Replace the environment variable values with your source and destination organization names.

```bash
#!/usr/bin/env bash
set -euo pipefail

SRC_ORG="oldorg"
DEST_ORG="neworg"

while read -r REPO; do
  [[ -z "${REPO}" ]] && continue
  echo "==== Migrating repo: ${REPO}"
  SRC_ORG="${SRC_ORG}" DEST_ORG="${DEST_ORG}" REPO="${REPO}" ./migrate-single-repo.sh
done < repos.txt
```

## [Verify migration integrity](#verify-migration-integrity)

After copying, verify that source and destination match by comparing digests.

### [Basic digest verification](#basic-digest-verification)

The following example script retrieves the image digest for a specific tag from both source and destination and compares them. If the digests match, the migration is successful. Replace the environment variable values with your source and destination organization names, repository name, and tag. You can choose between `crane` and `regctl` for retrieving digests.

```bash
#!/usr/bin/env bash
set -euo pipefail

SRC_ORG="oldorg"
DEST_ORG="neworg"
REPO="myapp"
TAG="1.2.3"

SRC_IMAGE="${SRC_ORG}/${REPO}:${TAG}"
DEST_IMAGE="${DEST_ORG}/${REPO}:${TAG}"

# Using crane
SRC_DIGEST=$(crane digest "${SRC_IMAGE}")
DEST_DIGEST=$(crane digest "${DEST_IMAGE}")

# Using regctl (alternative)
# SRC_DIGEST=$(regctl image digest "${SRC_IMAGE}")
# DEST_DIGEST=$(regctl image digest "${DEST_IMAGE}")

echo "Source:      ${SRC_DIGEST}"
echo "Destination: ${DEST_DIGEST}"

if [[ "${SRC_DIGEST}" == "${DEST_DIGEST}" ]]; then
  echo "✓ Migration verified: digests match"
else
  echo "✗ Migration failed: digests do not match"
  exit 1
fi
```

### [Multi-arch verification](#multi-arch-verification)

For multi-architecture images, also verify the manifest list to ensure all platforms were copied correctly. Replace the environment variable values with your source and destination organization names, repository name, and tag. You can choose between `crane` and `regctl` for retrieving manifests.

```bash
#!/usr/bin/env bash
set -euo pipefail

SRC_ORG="oldorg"
DEST_ORG="neworg"
REPO="myapp"
TAG="1.2.3"

SRC_IMAGE="${SRC_ORG}/${REPO}:${TAG}"
DEST_IMAGE="${DEST_ORG}/${REPO}:${TAG}"

# Using crane
SRC_MANIFEST=$(crane manifest "${SRC_IMAGE}")
DEST_MANIFEST=$(crane manifest "${DEST_IMAGE}")

# Using regctl (alternative)
# SRC_MANIFEST=$(regctl image manifest --format raw-body "${SRC_IMAGE}")
# DEST_MANIFEST=$(regctl image manifest --format raw-body "${DEST_IMAGE}")

# Check if it's a manifest list (multi-arch)
if echo "${SRC_MANIFEST}" | jq -e '.manifests' > /dev/null 2>&1; then
  echo "Multi-arch image detected"
  
  # Compare platform list
  SRC_PLATFORMS=$(echo "${SRC_MANIFEST}" | jq -r '.manifests[] | "\(.platform.os)/\(.platform.architecture)"' | sort)
  DEST_PLATFORMS=$(echo "${DEST_MANIFEST}" | jq -r '.manifests[] | "\(.platform.os)/\(.platform.architecture)"' | sort)
  
  if [[ "${SRC_PLATFORMS}" == "${DEST_PLATFORMS}" ]]; then
    echo "✓ Platform list matches:"
    echo "${SRC_PLATFORMS}"
  else
    echo "✗ Platform lists do not match"
    echo "Source platforms:"
    echo "${SRC_PLATFORMS}"
    echo "Destination platforms:"
    echo "${DEST_PLATFORMS}"
    exit 1
  fi
else
  echo "Single-arch image"
fi
```

## [Complete the migration](#complete-the-migration)

After migrating your images, complete these additional steps:

1. Copy repository metadata in the Docker Hub UI or via API:

   * README content
   * Repository description
   * Topics and tags

2. Configure repository settings to match the source:

   * Visibility (public or private)
   * Team permissions and access controls

3. Reconfigure integrations in the destination organization:

   * Webhooks
   * Automated builds
   * Security scanners

4. Update image references in your projects:

   * Change `FROM oldorg/repo:tag` to `FROM neworg/repo:tag` in Dockerfiles
   * Update deployment configurations
   * Update documentation

5. Deprecate the old location:

   * Update the source repository description to point to the new location
   * Consider adding a grace period before making the old repository private or read-only

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/enable-eci/
----

# Enable Enhanced Container Isolation

***

Table of contents

***

Subscription: Business

For: Administrators

ECI prevents malicious containers from compromising Docker Desktop while maintaining full developer productivity.

This page shows you how to turn on Enhanced Container Isolation (ECI) and verify it's working correctly.

## [Prerequisites](#prerequisites)

Before you begin, you must have:

* A Docker Business subscription
* [Enforced sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) (for administrators managing organization-wide settings only)

## [Enable Enhanced Container Isolation](#enable-enhanced-container-isolation)

### [For developers](#for-developers)

Turn on ECI in your Docker Desktop settings:

1. Sign in to your organization in Docker Desktop. Your organization must have a Docker Business subscription.

2. Stop and remove all existing containers:

   ```console
   $ docker stop $(docker ps -q)
   $ docker rm $(docker ps -aq)
   ```

3. In Docker Desktop, go to **Settings** > **General**.

4. Select the **Use Enhanced Container Isolation** checkbox.

5. Select **Apply and restart**.

> Important
>
> ECI doesn't protect containers created before turning on the feature. Remove existing containers before turning on ECI.

### [For administrators](#for-administrators)

Configure Enhanced Container Isolation organization-wide using Settings Management:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down.
2. Go to **Admin Console** > **Desktop Settings Management**.
3. [Create or edit a setting policy](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/).
4. Set **Enhanced Container Isolation** to **Always enabled**.

1) Create an [`admin-settings.json` file](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/) and add:

   ```json
   {
     "configurationFileVersion": 2,
     "enhancedContainerIsolation": {
       "value": true,
       "locked": true
     }
   }
   ```

2) Configure the following as needed:

   * `"value": true`: Turns on ECI by default (required)
   * `"locked": true`: Prevents developers from turning off ECI
   * `"locked": false`: Allows developers to control the setting

### [Apply the configuration](#apply-the-configuration)

For ECI settings to take effect:

* New installations: Users launch Docker Desktop and sign in
* Existing installations: Users must fully quit Docker Desktop and relaunch

> Important
>
> Restarting from the Docker Desktop menu isn't sufficient. Users must completely quit and reopen Docker Desktop.

You can also configure [Docker socket mount permissions](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/) for trusted images that need Docker API access.

## [Verify Enhanced Container Isolation is active](#verify-enhanced-container-isolation-is-active)

After turning on ECI, verify it's working correctly using these methods.

### [Check user namespace mapping](#check-user-namespace-mapping)

Run a container and examine the user namespace mapping:

```console
$ docker run --rm alpine cat /proc/self/uid_map
```

With ECI turned on:

```text
0     100000      65536
```

This shows the container's root user (0) maps to an unprivileged user (100000) in the Docker Desktop VM, with a range of 64K user IDs. Each container gets an exclusive user ID range for isolation.

With ECI turned off:

```text
0          0 4294967295
```

This shows the container root user (0) maps directly to the VM root user (0), providing less isolation.

### [Check container runtime](#check-container-runtime)

Verify the container runtime being used:

```console
$ docker inspect --format='{{.HostConfig.Runtime}}' <container_name>
```

With ECI turned on, it turns `sysbox-runc`. With ECI turned off, it returns `runc`.

### [Test security restrictions](#test-security-restrictions)

Verify that ECI security restrictions are active.

Test namespace sharing:

```console
$ docker run -it --rm --pid=host alpine
```

With ECI turned on, this command fails with an error about Sysbox containers not being able to share namespaces with the host.

Test Docker socket access:

```console
$ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock alpine
```

With ECI turned on, this command fails unless you've configured Docker socket exceptions for trusted images.

## [What users see with enforced ECI](#what-users-see-with-enforced-eci)

When administrators enforce Enhanced Container Isolation through Settings Management:

* The **Use Enhanced Container Isolation** setting appears turned on in Docker Desktop settings.
* If set to `"locked": true`, the setting is locked and greyed out.
* All new containers automatically use Linux user namespaces.
* Existing development workflows continue to work without modification.
* Users see `sysbox-runc` as the container runtime in `docker inspect` output.

## [Next steps](#next-steps)

* Review [Configure Docker socket exceptions and advanced settings](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/).
* Review [Enhanced Container Isolation limitations](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations/).

----
url: https://docs.docker.com/engine/cli/formatting/
----

# Format command and log output

***

Table of contents

***

Docker supports [Go templates](https://golang.org/pkg/text/template/) which you can use to manipulate the output format of certain commands and log drivers.

Docker provides a set of basic functions to manipulate template elements. All of these examples use the `docker inspect` command, but many other CLI commands have a `--format` flag, and many of the CLI command references include examples of customizing the output format.

> Note
>
> When using the `--format` flag, you need to observe your shell environment. In a POSIX shell, you can run the following with a single quote:
>
> ```console
> $ docker inspect --format '{{join .Args " , "}}'
> ```
>
> Otherwise, in a Windows shell (for example, PowerShell), you need to use single quotes, but escape the double quotes inside the parameters as follows:
>
> ```console
> $ docker inspect --format '{{join .Args \" , \"}}'
> ```

## [join](#join)

`join` concatenates a list of strings to create a single string. It puts a separator between each element in the list.

```console
$ docker inspect --format '{{join .Args " , "}}' container
```

## [table](#table)

`table` specifies which fields you want to see its output.

```console
$ docker image list --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}\t{{.Size}}"
```

## [json](#json)

`json` encodes an element as a json string.

```console
$ docker inspect --format '{{json .Mounts}}' container
```

## [lower](#lower)

`lower` transforms a string into its lowercase representation.

```console
$ docker inspect --format "{{lower .Name}}" container
```

## [split](#split)

`split` slices a string into a list of strings separated by a separator.

```console
$ docker inspect --format '{{split .Image ":"}}' container
```

## [title](#title)

`title` capitalizes the first character of a string.

```console
$ docker inspect --format "{{title .Name}}" container
```

## [upper](#upper)

`upper` transforms a string into its uppercase representation.

```console
$ docker inspect --format "{{upper .Name}}" container
```

## [pad](#pad)

`pad` adds whitespace padding to a string. You can specify the number of spaces to add before and after the string.

```console
$ docker image list --format '{{pad .Repository 5 10}}'
```

This example adds 5 spaces before the image repository name and 10 spaces after.

## [truncate](#truncate)

`truncate` shortens a string to a specified length. If the string is shorter than the specified length, it remains unchanged.

```console
$ docker image list --format '{{truncate .Repository 15}}'
```

This example displays the image repository name, truncating it to the first 15 characters if it's longer.

## [`println`](#println)

`println` prints each value on a new line.

```console
$ docker inspect --format='{{range .NetworkSettings.Networks}}{{println .IPAddress}}{{end}}' container
```

## [Hint](#hint)

To find out what data can be printed, show all content as json:

```console
$ docker container ls --format='{{json .}}'
```

----
url: https://docs.docker.com/testcontainers/
----

# Testcontainers

***

Table of contents

***

Testcontainers is a set of open source libraries that provides easy and lightweight APIs for bootstrapping local development and test dependencies with real services wrapped in Docker containers. Using Testcontainers, you can write tests that depend on the same services you use in production without mocks or in-memory services.

### [What is Testcontainers?](https://testcontainers.com/getting-started/#what-is-testcontainers)

[Learn about what Testcontainers does and its key benefits](https://testcontainers.com/getting-started/#what-is-testcontainers)

### [The Testcontainers workflow](https://testcontainers.com/getting-started/#testcontainers-workflow)

[Understand the Testcontainers workflow](https://testcontainers.com/getting-started/#testcontainers-workflow)

## [Quickstart](#quickstart)

### [Supported languages](#supported-languages)

Testcontainers provide support for the most popular languages, and Docker sponsors the development of the following Testcontainers implementations:

* [Go](https://golang.testcontainers.org/quickstart/)
* [Java](https://java.testcontainers.org/quickstart/junit_5_quickstart/)

The rest are community-driven and maintained by independent contributors.

### [Prerequisites](#prerequisites)

Testcontainers requires a Docker-API compatible container runtime. During development, Testcontainers is actively tested against recent versions of Docker on Linux, as well as against Docker Desktop on Mac and Windows. These Docker environments are automatically detected and used by Testcontainers without any additional configuration being necessary.

It is possible to configure Testcontainers to work for other Docker setups, such as a remote Docker host or Docker alternatives. However, these are not actively tested in the main development workflow, so not all Testcontainers features might be available and additional manual configuration might be necessary.

If you have further questions about configuration details for your setup or whether it supports running Testcontainers-based tests, contact the Testcontainers team and other users from the Testcontainers community on [Slack](https://slack.testcontainers.org/).

### [Testcontainers for Go](https://golang.testcontainers.org/quickstart/)

[A Go package that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests.](https://golang.testcontainers.org/quickstart/)

### [Testcontainers for Java](https://java.testcontainers.org/)

[A Java library that supports JUnit tests, providing lightweight, throwaway instances of anything that can run in a Docker container.](https://java.testcontainers.org/)

## [Guides](#guides)

Explore hands-on Testcontainers guides to learn how to use Testcontainers with different languages and popular frameworks:

* [Getting started with Testcontainers for .NET](/guides/testcontainers-dotnet-getting-started/)
* [Getting started with Testcontainers for Go](/guides/testcontainers-go-getting-started/)
* [Getting started with Testcontainers for Java](/guides/testcontainers-java-getting-started/)
* [Getting started with Testcontainers for Node.js](/guides/testcontainers-nodejs-getting-started/)
* [Getting started with Testcontainers for Python](/guides/testcontainers-python-getting-started/)
* [Testing a Spring Boot REST API with Testcontainers](/guides/testcontainers-java-spring-boot-rest-api/)
* [Testcontainers container lifecycle management](/guides/testcontainers-java-lifecycle/)
* [Replace H2 with a real database for testing](/guides/testcontainers-java-replace-h2/)
* [Configuration of services running in a container](/guides/testcontainers-java-service-configuration/)
* [Testing an ASP.NET Core web app](/guides/testcontainers-dotnet-aspnet-core/)
* [Testing Spring Boot Kafka Listener](/guides/testcontainers-java-spring-boot-kafka/)
* [Testing REST API integrations using MockServer](/guides/testcontainers-java-mockserver/)
* [Testing AWS service integrations using LocalStack](/guides/testcontainers-java-aws-localstack/)
* [Testing Quarkus applications with Testcontainers](/guides/testcontainers-java-quarkus/)
* [Working with jOOQ and Flyway using Testcontainers](/guides/testcontainers-java-jooq-flyway/)
* [Testing REST API integrations using WireMock](/guides/testcontainers-java-wiremock/)
* [Securing Spring Boot with Keycloak and Testcontainers](/guides/testcontainers-java-keycloak-spring-boot/)
* [Testing Micronaut REST API with WireMock](/guides/testcontainers-java-micronaut-wiremock/)
* [Testing Micronaut Kafka Listener](/guides/testcontainers-java-micronaut-kafka/)

----
url: https://docs.docker.com/extensions/extensions-sdk/dev/api/docker/
----

# Docker

***

Table of contents

***

## [Docker objects](#docker-objects)

▸ **listContainers**(`options?`): `Promise`<`unknown`>

To get the list of containers:

```typescript
const containers = await ddClient.docker.listContainers();
```

▸ **listImages**(`options?`): `Promise`<`unknown`>

To get the list of local container images:

```typescript
const images = await ddClient.docker.listImages();
```

See the [Docker API reference](https://docs.docker.com/reference/api/extensions-sdk/Docker/) for details about these methods.

> Deprecated access to Docker objects
>
> The methods below are deprecated and will be removed in a future version. Use the methods specified above.

```typescript
const containers = await window.ddClient.listContainers();

const images = await window.ddClient.listImages();
```

## [Docker commands](#docker-commands)

Extensions can also directly execute the `docker` command line.

▸ **exec**(`cmd`, `args`): `Promise`< [`ExecResult`](https://docs.docker.com/reference/api/extensions-sdk/ExecResult/)>

```typescript
const result = await ddClient.docker.cli.exec("info", [
  "--format",
  '"{{ json . }}"',
]);
```

The result contains both the standard output and the standard error of the executed command:

```json
{
  "stderr": "...",
  "stdout": "..."
}
```

In this example, the command output is JSON. For convenience, the command result object also has methods to easily parse it:

* `result.lines(): string[]` splits output lines.
* `result.parseJsonObject(): any` parses a well-formed json output.
* `result.parseJsonLines(): any[]` parses each output line as a json object.

▸ **exec**(`cmd`, `args`, `options`): `void`

The command above streams the output as a result of the execution of a Docker command. This is useful if you need to get the output as a stream or the output of the command is too long.

```typescript
await ddClient.docker.cli.exec("logs", ["-f", "..."], {
  stream: {
    onOutput(data) {
      if (data.stdout) {
        console.error(data.stdout);
      } else {
        console.log(data.stderr);
      }
    },
    onError(error) {
      console.error(error);
    },
    onClose(exitCode) {
      console.log("onClose with exit code " + exitCode);
    },
    splitOutputLines: true,
  },
});
```

The child process created by the extension is killed (`SIGTERM`) automatically when you close the dashboard in Docker Desktop or when you exit the extension UI. If needed, you can also use the result of the `exec(streamOptions)` call in order to kill (`SIGTERM`) the process.

```typescript
const logListener = await ddClient.docker.cli.exec("logs", ["-f", "..."], {
  stream: {
    // ...
  },
});

// when done listening to logs or before starting a new one, kill the process
logListener.close();
```

This `exec(streamOptions)` API can also be used to listen to docker events:

```typescript
await ddClient.docker.cli.exec(
  "events",
  ["--format", "{{ json . }}", "--filter", "container=my-container"],
  {
    stream: {
      onOutput(data) {
        if (data.stdout) {
          const event = JSON.parse(data.stdout);
          console.log(event);
        } else {
          console.log(data.stderr);
        }
      },
      onClose(exitCode) {
        console.log("onClose with exit code " + exitCode);
      },
      splitOutputLines: true,
    },
  }
);
```

> Note
>
> You cannot use this to chain commands in a single `exec()` invocation (like `docker kill $(docker ps -q)` or using pipe between commands).
>
> You need to invoke `exec()` for each command and parse results to pass parameters to the next command if needed.

See the [Exec API reference](https://docs.docker.com/reference/api/extensions-sdk/Exec/) for details about these methods.

> Deprecated execution of Docker commands
>
> This method is deprecated and will be removed in a future version. Use the one specified just below.

```typescript
const output = await window.ddClient.execDockerCmd(
  "info",
  "--format",
  '"{{ json . }}"'
);

window.ddClient.spawnDockerCmd("logs", ["-f", "..."], (data, error) => {
  console.log(data.stdout);
});
```

----
url: https://docs.docker.com/reference/cli/docker/scout/integration/configure/
----

# docker scout integration configure

***

| Description | Configure or update a new integration configuration |
| ----------- | --------------------------------------------------- |
| Usage       | `docker scout integration configure INTEGRATION`    |

## [Description](#description)

The docker scout integration configure command creates or updates a new integration configuration for an organization.

## [Options](#options)

| Option        | Default | Description                                                  |
| ------------- | ------- | ------------------------------------------------------------ |
| `--name`      |         | Name of integration configuration to create                  |
| `--org`       |         | Namespace of the Docker organization                         |
| `--parameter` |         | Integration parameters in the form of --parameter NAME=VALUE |

----
url: https://docs.docker.com/desktop/use-desktop/container/
----

# Explore the Containers view in Docker Desktop

***

Table of contents

***

The **Containers** view lists all running and stopped containers and applications. It provides a clean interface to manage the lifecycle of your containers, interact with running applications, and inspect Docker objects—including Docker Compose apps.

## [Container actions](#container-actions)

Use the **Search** field to find a specific container by name.

From the **Containers** view you can:

* Start, stop, pause, resume, or restart containers
* View image packages and CVEs
* Delete containers
* Open the application in VS code
* Open the port exposed by the container in a browser
* Copy the `docker run` command for reuse or modification
* Use [Docker Debug](#execdebug)

## [Resource usage](#resource-usage)

From the **Containers** view you can monitor your containers' CPU and memory usage over time. This can help you understand if something is wrong with your containers or if you need to allocate additional resources.

When you [inspect a container](#inspect-a-container), the **Stats** tab displays further information about a container's resource utilization. You can see how much CPU, memory, network and disk space your container is using over time.

## [Inspect a container](#inspect-a-container)

You can obtain detailed information about the container when you select it.

From here, you can use the quick action buttons to perform various actions such as pause, resume, start or stop, or explore the **Logs**, **Inspect**, **Bind mounts**, **Debug**, **Files**, and **Stats** tabs.

### [Logs](#logs)

Select **Logs** to view output from the container in real time. While viewing logs, you can:

* Use `Cmd + f`/`Ctrl + f` to open the search bar and find specific entries. Search matches are highlighted in yellow.
* Press `Enter` or `Shift + Enter` to jump to the next or previous search match respectively.
* Use the **Copy** icon in the top right-hand corner to copy all the logs to your clipboard.
* Show timestamps
* Use the **Clear terminal** icon in the top right-hand corner to clear the logs terminal.
* Select and view external links that may be in your logs.

You can refine your view by:

* Filtering logs for specific containers, if you're running a multi-container application.
* Using regular expressions or exact match search terms

### [Inspect](#inspect)

Select **Inspect** to view low-level information about the container. It displays the local path, version number of the image, SHA-256, port mapping, and other details.

### [Exec/Debug](#execdebug)

If you have not enabled Docker Debug in settings, the **Exec** tab displays. It lets you quickly run commands within your running container.

Using the **Exec** tab is the same as running one of the following commands:

* `docker exec -it <container-id> /bin/sh`
* `docker exec -it <container-id> cmd.exe` when accessing Windows containers

For more details, see the [`docker exec` CLI reference](/reference/cli/docker/container/exec/).

If you have enabled Docker Debug in settings, or toggled on **Debug mode** to the right of the tab options, the **Debug** tab displays.

Debug mode has several advantages, such as:

* A customizable toolbox. The toolbox comes with many standard Linux tools pre-installed, such as `vim`, `nano`, `htop`, and `curl`. For more details, see the [`docker debug` CLI reference](/reference/cli/docker/debug/).
* The ability to access containers that don't have a shell, for example, slim or distroless containers.

To use debug mode:

* Hover over your running container and under the **Actions** column, select the **Show container actions** menu. From the drop-down menu, select **Use Docker Debug**.
* Or, select the container and then select the **Debug** tab.

To use debug mode by default, navigate to the **General** tab in **Settings** and select the **Enable Docker Debug by default** option.

### [Files](#files)

Select **Files** to explore the filesystem of running or stopped containers. You can also:

* See which files have been recently added, modified, or deleted
* Edit a file straight from the built-in editor
* Drag and drop files and folders between the host and the container
* Delete unnecessary files when you right-click on a file
* Download files and folders from the container straight to the host

## [Additional resources](#additional-resources)

* [What is a container](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/)
* [Run multi-container applications](https://docs.docker.com/get-started/docker-concepts/running-containers/multi-container-applications/)

----
url: https://docs.docker.com/engine/security/non-events/
----

# Docker security non-events

***

***

This page lists security vulnerabilities which Docker mitigated, such that processes run in Docker containers were never vulnerable to the bug—even before it was fixed. This assumes containers are run without adding extra capabilities or not run as `--privileged`.

The list below is not even remotely complete. Rather, it is a sample of the few bugs we've actually noticed to have attracted security review and publicly disclosed vulnerabilities. In all likelihood, the bugs that haven't been reported far outnumber those that have. Luckily, since Docker's approach to secure by default through apparmor, seccomp, and dropping capabilities, it likely mitigates unknown bugs just as well as it does known ones.

Bugs mitigated:

* [CVE-2013-1956](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1956), [1957](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1957), [1958](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1958), [1959](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1959), [1979](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1979), [CVE-2014-4014](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-4014), [5206](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-5206), [5207](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-5207), [7970](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-7970), [7975](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-7975), [CVE-2015-2925](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-2925), [8543](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-8543), [CVE-2016-3134](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-3134), [3135](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-3135), etc.: The introduction of unprivileged user namespaces lead to a huge increase in the attack surface available to unprivileged users by giving such users legitimate access to previously root-only system calls like `mount()`. All of these CVEs are examples of security vulnerabilities due to introduction of user namespaces. Docker can use user namespaces to set up containers, but then disallows the process inside the container from creating its own nested namespaces through the default seccomp profile, rendering these vulnerabilities unexploitable.
* [CVE-2014-0181](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-0181), [CVE-2015-3339](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-3339): These are bugs that require the presence of a setuid binary. Docker disables setuid binaries inside containers via the `NO_NEW_PRIVS` process flag and other mechanisms.
* [CVE-2014-4699](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-4699): A bug in `ptrace()` could allow privilege escalation. Docker disables `ptrace()` inside the container using apparmor, seccomp and by dropping `CAP_PTRACE`. Three times the layers of protection there!
* [CVE-2014-9529](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-9529): A series of crafted `keyctl()` calls could cause kernel DoS / memory corruption. Docker disables `keyctl()` inside containers using seccomp.
* [CVE-2015-3214](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-3214), [4036](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-4036): These are bugs in common virtualization drivers which could allow a guest OS user to execute code on the host OS. Exploiting them requires access to virtualization devices in the guest. Docker hides direct access to these devices when run without `--privileged`. Interestingly, these seem to be cases where containers are "more secure" than a VM, going against common wisdom that VMs are "more secure" than containers.
* [CVE-2016-0728](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-0728): Use-after-free caused by crafted `keyctl()` calls could lead to privilege escalation. Docker disables `keyctl()` inside containers using the default seccomp profile.
* [CVE-2016-2383](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-2383): A bug in eBPF -- the special in-kernel DSL used to express things like seccomp filters -- allowed arbitrary reads of kernel memory. The `bpf()` system call is blocked inside Docker containers using (ironically) seccomp.
* [CVE-2016-3134](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-3134), [4997](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-4997), [4998](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-4998): A bug in setsockopt with `IPT_SO_SET_REPLACE`, `ARPT_SO_SET_REPLACE`, and `ARPT_SO_SET_REPLACE` causing memory corruption / local privilege escalation. These arguments are blocked by `CAP_NET_ADMIN`, which Docker does not allow by default.

Bugs not mitigated:

* [CVE-2015-3290](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-3290), [5157](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-5157): Bugs in the kernel's non-maskable interrupt handling allowed privilege escalation. Can be exploited in Docker containers because the `modify_ldt()` system call is not currently blocked using seccomp.
* [CVE-2016-5195](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2016-5195): A race condition was found in the way the Linux kernel's memory subsystem handled the copy-on-write (COW) breakage of private read-only memory mappings, which allowed unprivileged local users to gain write access to read-only memory. Also known as "dirty COW." *Partial mitigations:* on some operating systems this vulnerability is mitigated by the combination of seccomp filtering of `ptrace` and the fact that `/proc/self/mem` is read-only.

----
url: https://docs.docker.com/reference/cli/docker/sandbox/version/
----

# docker sandbox version

***

| Description | Show sandbox version information |
| ----------- | -------------------------------- |
| Usage       | `docker sandbox version`         |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Show sandbox version information

## [Examples](#examples)

### [Show version information](#show-version-information)

```console
$ docker sandbox version
github.com/docker/sandboxes/cli-plugin v0.7.1 f00f0d6473647c2201cd0507ce31613345c48ae6
```

----
url: https://docs.docker.com/reference/cli/sbx/secret/ls/
----

# sbx secret ls

| Description | List stored secrets               |
| ----------- | --------------------------------- |
| Usage       | `sbx secret ls [SANDBOX] [flags]` |

## [Options](#options)

| Option         | Default | Description                   |
| -------------- | ------- | ----------------------------- |
| `-g, --global` |         | Only list global secrets      |
| `--service`    |         | Filter by secret service name |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# List all secrets
sbx secret ls

# List only global secrets
sbx secret ls -g

# List secrets for a specific sandbox
sbx secret ls my-sandbox

# Filter by service
sbx secret ls --service github
```

----
url: https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog/
----

# Fix "Docker.app is damaged and can't be opened" on macOS

***

Table of contents

***

## [Error message](#error-message)

macOS shows the following dialog when you try to open Docker Desktop:

```text
Docker.app is damaged and can't be opened. You should move it to the Trash.
```

This error prevents Docker Desktop from launching and can occur during installation or after updates.

## [Possible cause](#possible-cause)

This issue occurs due to a non-atomic copy during a drag/drop installation. When you drag and drop `Docker.app` from a DMG file while another application, like VS Code, is invoking the Docker CLI through symlinks, the copy operation may be interrupted, leaving the app in a partially copied state that Gatekeeper marks as "damaged".

## [Solution](#solution)

Follow these steps to resolve the issue:

### [Step one: Quit third-party software](#step-one-quit-third-party-software)

Close any applications that might call Docker in the background:

* Visual Studio Code and other IDEs
* Terminal applications
* Agent apps or development tools
* Any scripts or processes that use the Docker CLI

### [Step two: Remove any partial installation](#step-two-remove-any-partial-installation)

1. Move `/Applications/Docker.app` to Trash and empty Trash.
2. If you used a DMG installer, eject and re-mount the Docker DMG.

### [Step three: Reinstall Docker Desktop](#step-three-reinstall-docker-desktop)

Follow the instructions in the [macOS installation guide](https://docs.docker.com/desktop/setup/install/mac-install/) to reinstall Docker Desktop.

### [If the dialog persists](#if-the-dialog-persists)

If you continue to see the "damaged" dialog after following the recovery steps:

1. Gather diagnostics using the terminal. Follow the instructions in [Diagnose from the terminal](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/#diagnose-from-the-terminal).

   * Note down the your diagnostics ID displayed in the terminal after running diagnostics.

2. Get help:

   * If you have a paid Docker subscription, [contact support](https://docs.docker.com/support/) and include your diagnostics ID
   * For community users, [open an issue on GitHub](https://github.com/docker/desktop-feedback) and include your diagnostics ID

## [Prevention](#prevention)

To avoid this issue in the future:

* If your organization allows, update Docker Desktop via the in-app update flow
* Always quit applications that use Docker before installing Docker Desktop via the DMG installer drag-and-drop approach
* In managed environments, use PKG installations over DMG drag-and-drop
* Keep installer volumes mounted until installation is complete

## [Related information](#related-information)

* [Install Docker Desktop on Mac](https://docs.docker.com/desktop/setup/install/mac-install/)
* [PKG installer documentation](https://docs.docker.com/enterprise/enterprise-deployment/pkg-install-and-configure/)
* [Troubleshoot Docker Desktop](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/)
* [Known issues](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/known-issues/)

----
url: https://docs.docker.com/ai/sandboxes/customize/kit-examples/
----

# Kit examples

***

Table of contents

***

Availability: Early Access

> Note
>
> Kits are experimental. The kit file format, CLI commands, and experience for creating, loading, and managing kits are subject to change as the feature evolves. Share feedback and bug reports in the [docker/sbx-releases](https://github.com/docker/sbx-releases) repository.

Each section below shows one `spec.yaml` snippet that demonstrates a single kit pattern. These aren't complete, distributable kits — they're small, focused examples you can lift into your own kit. For the full spec reference, see [Kits](https://docs.docker.com/ai/sandboxes/customize/kits/).

## [Drop a shared config file](#drop-a-shared-config-file)

Use static files under `files/workspace/` when the content is the same across every sandbox and doesn't need any runtime values substituted in. Typical use cases: linter rules, editor settings, a shared `.editorconfig`, team dotfiles.

```text
ruff-lint/
├── spec.yaml
└── files/
    └── workspace/
        └── ruff.toml
```

ruff-lint/spec.yaml

```yaml
schemaVersion: "1"
kind: mixin
name: ruff-lint
displayName: Ruff
description: Python linting with shared team config

commands:
  install:
    - command: "uv tool install ruff@latest"
      user: "1000"
```

ruff-lint/files/workspace/ruff.toml

```toml
line-length = 80

[lint]
select = ["E", "F", "I"]
```

## [Install a tool at sandbox creation](#install-a-tool-at-sandbox-creation)

`commands.install` runs once per sandbox, at creation time. It's where anything that needs to land in the image goes — package managers (`apt-get`, `pip`, `npm`), binary downloads, or vendor install scripts.

```yaml
commands:
  install:
    - command: "apt-get update && apt-get install -y jq"
    - command: "curl -fsSL https://example.com/install.sh | sh"
```

Install commands run as root by default. Set `user: "1000"` when the step should run as the agent user — for example, `npm install -g` against a user-scoped prefix, or anything that writes to `/home/agent/`.

## [Run a background service](#run-a-background-service)

`commands.startup` runs at every sandbox start. For long-running services, background them inside a shell command and redirect output to a log file. Relying on the `background: true` field alone can leave the service attached to a shell that exits, which silently kills it.

```yaml
commands:
  startup:
    - command:
        - sh
        - -c
        - nohup my-service --port 8080 > /tmp/my-service.log 2>&1 &
      user: "1000"
```

The log file is worth the extra flag: if the service exits early, its stderr goes to a parent shell that isn't attached to anything you can read. An empty log file tells you the wrapper ran; a populated one tells you why it failed.

## [Bake runtime values into a file with initFiles](#bake-runtime-values-into-a-file-with-initfiles)

When a config file needs a value that isn't known until sandbox start — most often the absolute workspace path — use `commands.initFiles`. The `${WORKDIR}` placeholder expands to the primary workspace path when the file is written.

```yaml
commands:
  initFiles:
    - path: /home/agent/.local/bin/start-code-server.sh
      content: |
        exec code-server --bind-addr 0.0.0.0:8080 --auth none "${WORKDIR}"
      mode: "0755"
  startup:
    - command:
        - sh
        - -c
        - nohup /home/agent/.local/bin/start-code-server.sh > /tmp/code-server.log 2>&1 &
      user: "1000"
```

`mode: "0755"` makes the generated file executable so the startup command can invoke it directly.

Use `initFiles` instead of a static file whenever the content depends on a runtime value. Use a static file otherwise.

> Tip
>
> This snippet is lifted from the [code-server kit](https://github.com/docker/sbx-kits-contrib/tree/main/code-server) in the contrib repository, which is also a runnable sample that demonstrates the full pattern.

## [Ship a Claude Code skill](#ship-a-claude-code-skill)

Claude Code reads project-scoped skills from `.claude/skills/<name>/SKILL.md` in the workspace. Drop one into `files/workspace/` and it's available in the sandbox.

```text
docker-review/
├── spec.yaml
└── files/
    └── workspace/
        └── .claude/
            └── skills/
                └── docker-review/
                    └── SKILL.md
```

docker-review/spec.yaml

```yaml
schemaVersion: "1"
kind: mixin
name: docker-review
displayName: Dockerfile review skill
description: Ships a Claude Code skill that reviews Dockerfiles
```

docker-review/files/workspace/.claude/skills/docker-review/SKILL.md

```markdown
---
name: docker-review
description: Review a Dockerfile for best practices. Use when the user asks to review, audit, or improve a Dockerfile.
---

When reviewing a Dockerfile, check:

1. Base image — pinned tag or digest, appropriate for the workload
2. Layer order — dependencies copied before application source
3. Image size — multi-stage builds, `.dockerignore`, package-manager cache flags
4. Security — non-root `USER`, no secrets in `ARG`/`ENV`
5. Reproducibility — pinned package versions, frontend directive where relevant
```

Kits have to target the workspace rather than `~/.claude/` because sandboxes don't pick up user-level agent configuration from the host. See the [FAQ](https://docs.docker.com/ai/sandboxes/faq/#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for details.

## [Override agent settings](#override-agent-settings)

Sandboxes seed settings files for some built-in agents during setup. For example, the sandbox writes `/home/agent/.claude/settings.json` for the `claude` agent. This happens after the kit's static files and `initFiles`, so a kit can't override those paths with either mechanism. Use `commands.startup` instead, which runs after the sandbox seeds its files:

```yaml
commands:
  startup:
    - command:
        - sh
        - -c
        - |
          mkdir -p /home/agent/.claude
          cat > /home/agent/.claude/settings.json <<'JSON'
          {"permissions": {"allow": ["Bash(echo:*)"]}}
          JSON
      user: "1000"
      description: Write user-scope claude settings
```

Startup commands replay on every sandbox start, so the script must be idempotent. The heredoc pattern overwrites cleanly each time.

## [Fork an existing agent](#fork-an-existing-agent)

Agent kits (`kind: agent`) define a full agent from scratch. The most common variant is a fork of a built-in agent — same image and credentials, but a different entrypoint. This example reproduces the built-in `claude` agent but drops `--dangerously-skip-permissions` so every tool call prompts for approval:

claude-safe/spec.yaml

```yaml
schemaVersion: "1"
kind: agent
name: claude-safe
displayName: Claude Code (with approval prompts)
description: Claude Code without --dangerously-skip-permissions

agent:
  image: "docker/sandbox-templates:claude-code-docker"
  aiFilename: CLAUDE.md
  persistence: persistent
  entrypoint:
    run: [claude]

network:
  serviceDomains:
    api.anthropic.com: anthropic
    console.anthropic.com: anthropic
  serviceAuth:
    anthropic:
      headerName: x-api-key
      valueFormat: "%s"
  allowedDomains:
    - "claude.com:443"

credentials:
  sources:
    anthropic:
      env:
        - ANTHROPIC_API_KEY
```

Launch with the kit's `name:` as the agent argument to `sbx run`:

```console
$ sbx run claude-safe --kit ./claude-safe
```

For a step-by-step walkthrough of building a new agent kit from scratch, see [Build an agent](https://docs.docker.com/ai/sandboxes/customize/build-an-agent/).

## [More examples](#more-examples)

These patterns are all drawn from working kits in the [sbx-kits-contrib](https://github.com/docker/sbx-kits-contrib) repository, which contains each example as a complete, loadable kit. Use it to study the full shape of a kit, or load one directly:

```console
$ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=<kit>"
```

----
url: https://docs.docker.com/reference/cli/docker/pass/ls/
----

# docker pass ls

***

| Description | List all secrets from local keychain. |
| ----------- | ------------------------------------- |
| Usage       | `docker pass ls`                      |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Lists the names of all secrets stored in the local OS keychain.

----
url: https://docs.docker.com/reference/cli/docker/volume/rm/
----

# docker volume rm

***

| Description                                                               | Remove one or more volumes                      |
| ------------------------------------------------------------------------- | ----------------------------------------------- |
| Usage                                                                     | `docker volume rm [OPTIONS] VOLUME [VOLUME...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker volume remove`                          |

## [Description](#description)

Remove one or more volumes. You can't remove a volume that's in use by a container.

## [Options](#options)

| Option        | Default | Description                                        |
| ------------- | ------- | -------------------------------------------------- |
| `-f, --force` |         | API 1.25+ Force the removal of one or more volumes |

## [Examples](#examples)

```console
$ docker volume rm hello

hello
```

----
url: https://docs.docker.com/reference/samples/rust/
----

# Rust samples

| Name                                                                                                   | Description                                                             |
| ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| [React / Rust / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/react-rust-postgres) | A sample React application with a Rust backend and a Postgres database. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/
----

# docker mcp catalog

***

| Description                                                               | Manage MCP server OCI catalogs                  |
| ------------------------------------------------------------------------- | ----------------------------------------------- |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker mcp catalogs` `docker mcp catalog-next` |

## [Description](#description)

Manage MCP server OCI catalogs

## [Subcommands](#subcommands)

| Command                                                                                         | Description                                                                |
| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [`docker mcp catalog create`](https://docs.docker.com/reference/cli/docker/mcp/catalog/create/) | Create a new catalog from a profile, legacy catalog, or community registry |
| [`docker mcp catalog list`](https://docs.docker.com/reference/cli/docker/mcp/catalog/list/)     | List catalogs                                                              |
| [`docker mcp catalog ls`](https://docs.docker.com/reference/cli/docker/mcp/catalog/ls/)         | List all configured catalogs                                               |
| [`docker mcp catalog pull`](https://docs.docker.com/reference/cli/docker/mcp/catalog/pull/)     | Pull a catalog from an OCI registry                                        |
| [`docker mcp catalog push`](https://docs.docker.com/reference/cli/docker/mcp/catalog/push/)     | Push a catalog to an OCI registry                                          |
| [`docker mcp catalog remove`](https://docs.docker.com/reference/cli/docker/mcp/catalog/remove/) | Remove a catalog                                                           |
| [`docker mcp catalog rm`](https://docs.docker.com/reference/cli/docker/mcp/catalog/rm/)         | Remove a catalog                                                           |
| [`docker mcp catalog server`](https://docs.docker.com/reference/cli/docker/mcp/catalog/server/) | Manage servers in catalogs                                                 |
| [`docker mcp catalog show`](https://docs.docker.com/reference/cli/docker/mcp/catalog/show/)     | Show a catalog                                                             |
| [`docker mcp catalog tag`](https://docs.docker.com/reference/cli/docker/mcp/catalog/tag/)       | Create a tagged copy of a catalog                                          |

----
url: https://docs.docker.com/reference/cli/sbx/policy/rm/network/
----

# sbx policy rm network

| Description | Remove a network rule                           |
| ----------- | ----------------------------------------------- |
| Usage       | `sbx policy rm network [-g \| SANDBOX] [flags]` |

## [Description](#description)

Remove a network rule by rule ID, resource, or both.

Use -g/--global to remove from the global policy, or provide SANDBOX to remove from policy "local" scoped to that sandbox.

Use "sbx policy ls" to see active policies and their IDs/resources.

## [Options](#options)

| Option         | Default | Description                                  |
| -------------- | ------- | -------------------------------------------- |
| `-g, --global` |         | Remove from the global policy                |
| `--id`         |         | Remove by rule ID                            |
| `--resource`   |         | Remove by resource value(s), comma-separated |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# List policies to find the ID or resource to remove
sbx policy ls

# Remove a global rule by resource
sbx policy rm network -g --resource api.example.com

# Remove a global rule by ID
sbx policy rm network -g --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67

# Remove a sandbox-scoped rule by resource
sbx policy rm network my-sandbox --resource api.example.com
```

----
url: https://docs.docker.com/guides/kafka/
----

[Developing event-driven applications with Kafka and Docker](https://docs.docker.com/guides/kafka/)

This guide explains how to run Apache Kafka in Docker containers.

JavaScript Distributed systems

20 minutes

[« Back to all guides](/guides/)

# Developing event-driven applications with Kafka and Docker

***

Table of contents

***

With the rise of microservices, event-driven architectures have become increasingly popular. [Apache Kafka](https://kafka.apache.org/), a distributed event streaming platform, is often at the heart of these architectures. Unfortunately, setting up and deploying your own Kafka instance for development is often tricky. Fortunately, Docker and containers make this much easier.

In this guide, you will learn how to:

1. Use Docker to launch up a Kafka cluster
2. Connect a non-containerized app to the cluster
3. Connect a containerized app to the cluster
4. Deploy Kafka-UI to help with troubleshooting and debugging

## [Prerequisites](#prerequisites)

The following prerequisites are required to follow along with this how-to guide:

* [Docker Desktop](https://www.docker.com/products/docker-desktop/)
* [Node.js](https://nodejs.org/en/download/package-manager) and [yarn](https://yarnpkg.com/)
* Basic knowledge of Kafka and Docker

## [Launching Kafka](#launching-kafka)

Beginning with [Kafka 3.3](https://www.confluent.io/blog/apache-kafka-3-3-0-new-features-and-updates/), the deployment of Kafka was greatly simplified by no longer requiring Zookeeper thanks to KRaft (Kafka Raft). With KRaft, setting up a Kafka instance for local development is much easier. Starting with the launch of [Kafka 3.8](https://www.confluent.io/blog/introducing-apache-kafka-3-8/), a new [kafka-native](https://hub.docker.com/r/apache/kafka-native) Docker image is now available, providing a significantly faster startup and lower memory footprint.

> Tip
>
> This guide will be using the apache/kafka image, as it includes many helpful scripts to manage and work with Kafka. However, you may want to use the apache/kafka-native image, as it starts more quickly and requires fewer resources.

### [Starting Kafka](#starting-kafka)

Start a basic Kafka cluster by doing the following steps. This example will launch a cluster, exposing port 9092 onto the host to let a native-running application to connect to it.

1. Start a Kafka container by running the following command:

   ```console
   $ docker run -d --name=kafka -p 9092:9092 apache/kafka
   ```

2. Once the image pulls, you’ll have a Kafka instance up and running within a second or two.

3. The apache/kafka image ships with several helpful scripts in the `/opt/kafka/bin` directory. Run the following command to verify the cluster is up and running and get its cluster ID:

   ```console
   $ docker exec -ti kafka /opt/kafka/bin/kafka-cluster.sh cluster-id --bootstrap-server :9092
   ```

   Doing so will produce output similar to the following:

   ```plaintext
   Cluster ID: 5L6g3nShT-eMCtK--X86sw
   ```

4. Create a sample topic and produce (or publish) a few messages by running the following command:

   ```console
   $ docker exec -ti kafka /opt/kafka/bin/kafka-console-producer.sh --bootstrap-server :9092 --topic demo
   ```

   After running, you can enter a message per line. For example, enter a few messages, one per line. A few examples might be:

   ```plaintext
   First message
   ```

   And

   ```plaintext
   Second message
   ```

   Press `enter` to send the last message and then press ctrl+c when you’re done. The messages will be published to Kafka.

5. Confirm the messages were published into the cluster by consuming the messages:

   ```console
   $ docker exec -ti kafka /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server :9092 --topic demo --from-beginning
   ```

   You should then see your messages in the output:

   ```plaintext
   First message
   Second message
   ```

   If you want, you can open another terminal and publish more messages and see them appear in the consumer.

   When you’re done, hit ctrl+c to stop consuming messages.

You have a locally running Kafka cluster and have validated you can connect to it.

## [Connecting to Kafka from a non-containerized app](#connecting-to-kafka-from-a-non-containerized-app)

Now that you’ve shown you can connect to the Kafka instance from a command line, it’s time to connect to the cluster from an application. In this example, you will use a simple Node project that uses the [KafkaJS](https://github.com/tulios/kafkajs) library.

Since the cluster is running locally and is exposed at port 9092, the app can connect to the cluster at localhost:9092 (since it’s running natively and not in a container right now). Once connected, this sample app will log messages it consumes from the `demo` topic. Additionally, when it runs in development mode, it will also create the topic if it isn’t found.

1. If you don’t have the Kafka cluster running from the previous step, run the following command to start a Kafka instance:

   ```console
   $ docker run -d --name=kafka -p 9092:9092 apache/kafka
   ```

2. Clone the [GitHub repository](https://github.com/dockersamples/kafka-development-node) locally.

   ```console
   $ git clone https://github.com/dockersamples/kafka-development-node.git
   ```

3. Navigate into the project.

   ```console
   cd kafka-development-node/app
   ```

4. Install the dependencies using yarn.

   ```console
   $ yarn install
   ```

5. Start the application using `yarn dev`. This will set the `NODE_ENV` environment variable to `development` and use `nodemon` to watch for file changes.

   ```console
   $ yarn dev
   ```

6. With the application now running, it will log received messages to the console. In a new terminal, publish a few messages using the following command:

   ```console
   $ docker exec -ti kafka /opt/kafka/bin/kafka-console-producer.sh --bootstrap-server :9092 --topic demo
   ```

   And then send a message to the cluster:

   ```plaintext
   Test message
   ```

   Remember to press `ctrl+c` when you’re done to stop producing messages.

## [Connecting to Kafka from both containers and native apps](#connecting-to-kafka-from-both-containers-and-native-apps)

Now that you have an application connecting to Kafka through its exposed port, it’s time to explore what changes are needed to connect to Kafka from another container. To do so, you will now run the application out of a container instead of natively.

But before you do that, it’s important to understand how Kafka listeners work and how those listeners help clients connect.

### [Understanding Kafka listeners](#understanding-kafka-listeners)

When a client connects to a Kafka cluster, it actually connects to a “broker”. While brokers have many roles, one of them is to support load balancing of clients. When a client connects, the broker returns a set of connection URLs the client should then use for the client to connect for the producing or consuming of messages. How are these connection URLs configured?

Each Kafka instance has a set of listeners and advertised listeners. The “listeners” are what Kafka binds to and the “advertised listeners” configure how clients should connect to the cluster. The connection URLs a client receives is based on which listener a client connects to.

### [Defining the listeners](#defining-the-listeners)

To help this make sense, let’s look at how Kafka needs to be configured to support two connection opportunities:

1. Host connections (those coming through the host’s mapped port) - these will need to connect using localhost
2. Docker connections (those coming from inside the Docker networks) - these can not connect using localhost, but the network alias (or DNS address) of the Kafka service

Since there are two different methods clients need to connect, two different listeners are required - `HOST` and `DOCKER`. The `HOST` listener will tell clients to connect using localhost:9092, while the `DOCKER` listener will inform clients to connect using `kafka:9093`. Notice this means Kafka is listening on both ports 9092 and 9093. But, only the host listener needs to be exposed to the host.

In order to set this up, the `compose.yaml` for Kafka needs some additional configuration. Once you start overriding some of the defaults, you also need to specify a few other options in order for KRaft mode to work.

```yaml
services:
  kafka:
    image: apache/kafka-native
    ports:
      - "9092:9092"
    environment:
      # Configure listeners for both docker and host communication
      KAFKA_LISTENERS: CONTROLLER://localhost:9091,HOST://0.0.0.0:9092,DOCKER://0.0.0.0:9093
      KAFKA_ADVERTISED_LISTENERS: HOST://localhost:9092,DOCKER://kafka:9093
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,DOCKER:PLAINTEXT,HOST:PLAINTEXT

      # Settings required for KRaft mode
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9091

      # Listener to use for broker-to-broker communication
      KAFKA_INTER_BROKER_LISTENER_NAME: DOCKER

      # Required for a single node cluster
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
```

Give it a try using the steps below.

1. If you have the Node app running from the previous step, go ahead and stop it by pressing `ctrl+c` in the terminal.

2. If you have the Kafka cluster running from the previous section, go ahead and stop that container using the following command:

   ```console
   $ docker rm -f kafka
   ```

3. Start the Compose stack by running the following command at the root of the cloned project directory:

   ```console
   $ docker compose up
   ```

   After a moment, the application will be up and running.

4. In the stack is another service that can be used to publish messages. Open it by going to <http://localhost:3000>. As you type in a message and submit the form, you should see the log message of the message being received by the app.

   This helps demonstrate how a containerized approach makes it easy to add additional services to help test and troubleshoot your application.

## [Adding cluster visualization](#adding-cluster-visualization)

Once you start using containers in your development environment, you start to realize the ease of adding additional services that are solely focused on helping development, such as visualizers and other supporting services. Since you have Kafka running, it might be helpful to visualize what’s going on in the Kafka cluster. To do so, you can run the [Kafbat UI web application](https://github.com/kafbat/kafka-ui).

To add it to your own project (it’s already in the demo application), you only need to add the following configuration to your Compose file:

```yaml
services:
  kafka-ui:
    image: kafbat/kafka-ui:main
    ports:
      - 8080:8080
    environment:
      DYNAMIC_CONFIG_ENABLED: "true"
      KAFKA_CLUSTERS_0_NAME: local
      KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9093
    depends_on:
      - kafka
```

Then, once the Compose stack starts, you can open your browser to <http://localhost:8080> and navigate around to view additional details about the cluster, check on consumers, publish test messages, and more.

## [Testing with Kafka](#testing-with-kafka)

If you’re interested in learning how you can integrate Kafka easily into your integration tests, check out the [Testing Spring Boot Kafka Listener using Testcontainers guide](https://testcontainers.com/guides/testing-spring-boot-kafka-listener-using-testcontainers/). This guide will teach you how to use Testcontainers to manage the lifecycle of Kafka containers in your tests.

## [Conclusion](#conclusion)

By using Docker, you can simplify the process of developing and testing event-driven applications with Kafka. Containers simplify the process of setting up and deploying the various services you need to develop. And once they’re defined in Compose, everyone on the team can benefit from the ease of use.

In case you missed it earlier, all of the sample app code can be found at dockersamples/kafka-development-node.

----
url: https://docs.docker.com/guides/github-sonarqube-sandbox/workflow/
----

# Build a code quality check workflow

***

Table of contents

***

In this section, you'll build a complete code quality automation workflow step-by-step. You'll start by creating an E2B sandbox with GitHub and SonarQube MCP servers, then progressively add functionality until you have a production-ready workflow that analyzes code quality and creates pull requests.

By working through each step sequentially, you'll learn how MCP servers work, how to interact with them through Claude, and how to chain operations together to build powerful automation workflows.

## [Prerequisites](#prerequisites)

Before you begin, make sure you have:

* E2B account with [API access](https://e2b.dev/docs/api-key)

* [Anthropic API key](https://docs.claude.com/en/api/admin-api/apikeys/get-api-key)

  > Note
  >
  > This example uses Claude CLI which comes pre-installed in E2B sandboxes, but you can adapt the example to work with other AI assistants of your choice. See [E2B's MCP documentation](https://e2b.dev/docs/mcp/quickstart) for alternative connection methods.

* GitHub account with:

  * A repository containing code to analyze
  * [Personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with `repo` scope

* SonarCloud account with:

  * [Organization](https://docs.sonarsource.com/sonarqube-cloud/administering-sonarcloud/resources-structure/organization) created
  * [Project configured](https://docs.sonarsource.com/sonarqube-community-build/project-administration/creating-and-importing-projects) for your repository
  * [User token](https://docs.sonarsource.com/sonarqube-server/instance-administration/security/administering-tokens) generated

* Language runtime installed:

  * TypeScript: [Node.js 18+](https://nodejs.org/en/download)
  * Python: [Python 3.8+](https://www.python.org/downloads/)

> Note
>
> This guide uses Claude's `--dangerously-skip-permissions` flag to enable automated command execution in E2B sandboxes. This flag bypasses permission prompts, which is appropriate for isolated container environments like E2B where sandboxes are disposable and separate from your local machine.
>
> However, be aware that Claude can execute any commands within the sandbox, including accessing files and credentials available in that environment. Only use this approach with trusted code and workflows. For more information, see [Anthropic's guidance on container security](https://docs.anthropic.com/en/docs/claude-code/devcontainer).

## [Set up your project](#set-up-your-project)

1. Create a new directory for your workflow and initialize Node.js:

   ```bash
   mkdir github-sonarqube-workflow
   cd github-sonarqube-workflow
   npm init -y
   ```

2. Open `package.json` and configure it for ES modules:

   ```json
   {
     "name": "github-sonarqube-workflow",
     "version": "1.0.0",
     "description": "Automated code quality workflow using E2B, GitHub, and SonarQube",
     "type": "module",
     "main": "quality-workflow.ts",
     "scripts": {
       "start": "tsx quality-workflow.ts"
     },
     "keywords": ["e2b", "github", "sonarqube", "mcp", "code-quality"],
     "author": "",
     "license": "MIT"
   }
   ```

3. Install required dependencies:

   ```bash
   npm install e2b dotenv
   npm install -D typescript tsx @types/node
   ```

4. Create a `.env` file in your project root:

   ```bash
   touch .env
   ```

5. Add your API keys and configuration, replacing the placeholders with your actual credentials:

   ```plaintext
   E2B_API_KEY=your_e2b_api_key_here
   ANTHROPIC_API_KEY=your_anthropic_api_key_here
   GITHUB_TOKEN=ghp_your_personal_access_token_here
   GITHUB_OWNER=your_github_username
   GITHUB_REPO=your_repository_name
   SONARQUBE_ORG=your_sonarcloud_org_key
   SONARQUBE_TOKEN=your_sonarqube_user_token
   SONARQUBE_URL=https://sonarcloud.io
   ```

6. Protect your credentials by adding `.env` to `.gitignore`:

   ```bash
   echo ".env" >> .gitignore
   echo "node_modules/" >> .gitignore
   ```

1) Create a new directory for your workflow:

   ```bash
   mkdir github-sonarqube-workflow
   cd github-sonarqube-workflow
   ```

2) Create a virtual environment and activate it:

   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3) Install required dependencies:

   ```bash
   pip install e2b python-dotenv
   ```

4) Create a `.env` file in your project root:

   ```bash
   touch .env
   ```

5) Add your API keys and configuration, replacing the placeholders with your actual credentials:

   ```plaintext
   E2B_API_KEY=your_e2b_api_key_here
   ANTHROPIC_API_KEY=your_anthropic_api_key_here
   GITHUB_TOKEN=ghp_your_personal_access_token_here
   GITHUB_OWNER=your_github_username
   GITHUB_REPO=your_repository_name
   SONARQUBE_ORG=your_sonarcloud_org_key
   SONARQUBE_TOKEN=your_sonarqube_user_token
   SONARQUBE_URL=https://sonarcloud.io
   ```

6) Protect your credentials by adding `.env` to `.gitignore`:

   ```bash
   echo ".env" >> .gitignore
   echo "venv/" >> .gitignore
   echo "__pycache__/" >> .gitignore
   ```

## [Step 1: Create your first sandbox](#step-1-create-your-first-sandbox)

Let's start by creating a sandbox and verifying the MCP servers are configured correctly.

Create a file named `01-test-connection.ts` in your project root:

```typescript
import "dotenv/config";
import { Sandbox } from "e2b";

async function testConnection() {
  console.log(
    "Creating E2B sandbox with GitHub and SonarQube MCP servers...\n",
  );

  const sbx = await Sandbox.betaCreate({
    envs: {
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
      GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
      SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!,
    },
    mcp: {
      githubOfficial: {
        githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
      },
      sonarqube: {
        org: process.env.SONARQUBE_ORG!,
        token: process.env.SONARQUBE_TOKEN!,
        url: "https://sonarcloud.io",
      },
    },
  });

  const mcpUrl = sbx.betaGetMcpUrl();
  const mcpToken = await sbx.betaGetMcpToken();

  console.log(" Sandbox created successfully!");
  console.log(`MCP Gateway URL: ${mcpUrl}\n`);

  // Wait for MCP initialization
  await new Promise((resolve) => setTimeout(resolve, 1000));

  // Configure Claude to use the MCP gateway
  console.log("Connecting Claude CLI to MCP gateway...");
  await sbx.commands.run(
    `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`,
    {
      timeoutMs: 0,
      onStdout: console.log,
      onStderr: console.log,
    },
  );

  console.log("\nœConnection successful! Cleaning up...");
  await sbx.kill();
}

testConnection().catch(console.error);
```

Run this script to verify your setup:

```bash
npx tsx 01-test-connection.ts
```

Create a file named `01_test_connection.py` in your project root:

```python
import os
import asyncio
from dotenv import load_dotenv
from e2b import AsyncSandbox

load_dotenv()

async def test_connection():
    print("Creating E2B sandbox with GitHub and SonarQube MCP servers...\n")

    sbx = await AsyncSandbox.beta_create(
        envs={
            "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
            "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
            "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"),
        },
        mcp={
            "githubOfficial": {
                "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
            },
            "sonarqube": {
                "org": os.getenv("SONARQUBE_ORG"),
                "token": os.getenv("SONARQUBE_TOKEN"),
                "url": "https://sonarcloud.io",
            },
        },
    )

    mcp_url = sbx.beta_get_mcp_url()
    mcp_token = await sbx.beta_get_mcp_token()

    print(" Sandbox created successfully!")
    print(f"MCP Gateway URL: {mcp_url}\n")

    # Wait for MCP initialization
    await asyncio.sleep(1)

    # Configure Claude to use the MCP gateway
    print("Connecting Claude CLI to MCP gateway...")
    await sbx.commands.run(
        f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"',
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    print("\n Connection successful! Cleaning up...")
    await sbx.kill()

if __name__ == "__main__":
    asyncio.run(test_connection())
```

Run this script to verify your setup:

```bash
python 01_test_connection.py
```

Your output should look similar to the following example:

```console
Creating E2B sandbox with GitHub and SonarQube MCP servers...

✓ Sandbox created successfully!
MCP Gateway URL: https://50005-xxxxx.e2b.app/mcp

Connecting Claude CLI to MCP gateway...
Added HTTP MCP server e2b-mcp-gateway with URL: https://50005-xxxxx.e2b.app/mcp to local config
Headers: {
  "Authorization": "Bearer xxxxx-xxxx-xxxx"
}
File modified: /home/user/.claude.json [project: /home/user]

✓ Connection successful! Cleaning up...
```

You've just learned how to create an E2B sandbox with multiple MCP servers configured. The `betaCreate` method initializes a cloud environment with Claude CLI and your specified MCP servers.

## [Step 2: Discover available MCP tools](#step-2-discover-available-mcp-tools)

MCP servers expose tools that Claude can call. The GitHub MCP server provides repository management tools, while SonarQube provides code analysis tools. By listing their tools, you know what operations are possible.

To try listing MCP tools:

Create `02-list-tools.ts`:

```typescript
import "dotenv/config";
import { Sandbox } from "e2b";

async function listTools() {
  console.log("Creating sandbox...\n");

  const sbx = await Sandbox.betaCreate({
    envs: {
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
      GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
      SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!,
    },
    mcp: {
      githubOfficial: {
        githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
      },
      sonarqube: {
        org: process.env.SONARQUBE_ORG!,
        token: process.env.SONARQUBE_TOKEN!,
        url: "https://sonarcloud.io",
      },
    },
  });

  const mcpUrl = sbx.betaGetMcpUrl();
  const mcpToken = await sbx.betaGetMcpToken();

  // Wait for MCP initialization
  await new Promise((resolve) => setTimeout(resolve, 1000));

  await sbx.commands.run(
    `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`,
    { timeoutMs: 0, onStdout: console.log, onStderr: console.log },
  );

  console.log("\nDiscovering available MCP tools...\n");

  const prompt =
    "List all MCP tools you have access to. For each tool, show its exact name and a brief description.";

  await sbx.commands.run(
    `echo '${prompt}' | claude -p --dangerously-skip-permissions`,
    { timeoutMs: 0, onStdout: console.log, onStderr: console.log },
  );

  await sbx.kill();
}

listTools().catch(console.error);
```

Run the script:

```bash
npx tsx 02-list-tools.ts
```

Create `02_list_tools.py`:

```python
import os
import asyncio
from dotenv import load_dotenv
from e2b import AsyncSandbox

load_dotenv()

async def list_tools():
    print("Creating sandbox...\n")

    sbx = await AsyncSandbox.beta_create(
        envs={
            "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
            "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
            "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"),
        },
        mcp={
            "githubOfficial": {
                "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
            },
            "sonarqube": {
                "org": os.getenv("SONARQUBE_ORG"),
                "token": os.getenv("SONARQUBE_TOKEN"),
                "url": "https://sonarcloud.io",
            },
        },
    )

    mcp_url = sbx.beta_get_mcp_url()
    mcp_token = await sbx.beta_get_mcp_token()

    # Wait for MCP initialization
    await asyncio.sleep(1)

    await sbx.commands.run(
        f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"',
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    print("\nDiscovering available MCP tools...\n")

    prompt = "List all MCP tools you have access to. For each tool, show its exact name and a brief description."

    await sbx.commands.run(
        f"echo '{prompt}' | claude -p --dangerously-skip-permissions",
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    await sbx.kill()

if __name__ == "__main__":
    asyncio.run(list_tools())
```

Run the script:

```bash
python 02_list_tools.py
```

In the console, you should see a list of MCP tools:

```console
Creating sandbox...

Sandbox created
Connecting to MCP gateway...

Discovering available MCP tools...

I have access to the following MCP tools:

**GitHub Tools:**
1. mcp__create_repository - Create a new GitHub repository
2. mcp__list_issues - List issues in a repository
3. mcp__create_issue - Create a new issue
4. mcp__get_file_contents - Get file contents from a repository
5. mcp__create_or_update_file - Create or update files in a repository
6. mcp__create_pull_request - Create a pull request
7. mcp__create_branch - Create a new branch
8. mcp__push_files - Push multiple files in a single commit
... (30+ more GitHub tools)

**SonarQube Tools:**
1. mcp__get_projects - List projects in organization
2. mcp__get_quality_gate_status - Get quality gate status for a project
3. mcp__list_project_issues - List quality issues in a project
4. mcp__search_issues - Search for specific quality issues
... (SonarQube analysis tools)
```

## [Step 3: Test GitHub MCP tools](#step-3-test-github-mcp-tools)

Let's try testing GitHub using MCP tools. Start simple by listing repository issues.

Create `03-test-github.ts`:

```typescript
import "dotenv/config";
import { Sandbox } from "e2b";

async function testGitHub() {
  console.log("Creating sandbox...\n");

  const sbx = await Sandbox.betaCreate({
    envs: {
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
      GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
    },
    mcp: {
      githubOfficial: {
        githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
      },
    },
  });

  const mcpUrl = sbx.betaGetMcpUrl();
  const mcpToken = await sbx.betaGetMcpToken();

  await new Promise((resolve) => setTimeout(resolve, 1000));

  await sbx.commands.run(
    `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`,
    { timeoutMs: 0, onStdout: console.log, onStderr: console.log },
  );

  const repoPath = `${process.env.GITHUB_OWNER}/${process.env.GITHUB_REPO}`;

  console.log(`\nListing issues in ${repoPath}...\n`);

  const prompt = `Using the GitHub MCP tools, list all open issues in the repository "${repoPath}". Show the issue number, title, and author for each.`;

  await sbx.commands.run(
    `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`,
    {
      timeoutMs: 0,
      onStdout: console.log,
      onStderr: console.log,
    },
  );

  await sbx.kill();
}

testGitHub().catch(console.error);
```

Run the script:

```bash
npx tsx 03-test-github.ts
```

Create `03_test_github.py`:

```python
import os
import asyncio
from dotenv import load_dotenv
from e2b import AsyncSandbox

load_dotenv()

async def test_github():
    print("Creating sandbox...\n")

    sbx = await AsyncSandbox.beta_create(
        envs={
            "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
            "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
        },
        mcp={
            "githubOfficial": {
                "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
            },
        },
    )

    mcp_url = sbx.beta_get_mcp_url()
    mcp_token = await sbx.beta_get_mcp_token()

    await asyncio.sleep(1)

    await sbx.commands.run(
        f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"',
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    repo_path = f"{os.getenv('GITHUB_OWNER')}/{os.getenv('GITHUB_REPO')}"

    print(f"\nListing issues in {repo_path}...\n")

    prompt = f'Using the GitHub MCP tools, list all open issues in the repository "{repo_path}". Show the issue number, title, and author for each.'

    await sbx.commands.run(
        f"echo '{prompt}' | claude -p --dangerously-skip-permissions",
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    await sbx.kill()

if __name__ == "__main__":
    asyncio.run(test_github())
```

Run the script:

```bash
python 03_test_github.py
```

You should see Claude use the GitHub MCP tools to list your repository's issues:

```console
Creating sandbox...
Connecting to MCP gateway...

Listing issues in <your-repo>...

Here are the first 10 open issues in the <your-repo> repository:

1. **Issue #23577**: Update README (author: user1)
2. **Issue #23575**: release-notes for Compose v2.40.1 version (author: user2)
3. **Issue #23570**: engine-cli: fix `docker volume prune` output (author: user3)
4. **Issue #23568**: Engdocs update (author: user4)
5. **Issue #23565**: add new section (author: user5)
... (continues with more issues)
```

You can now send prompts to Claude and interact with GitHub through natural language. Claude decides what tool to call based on your prompt.

## [Step 4: Test SonarQube MCP tools](#step-4-test-sonarqube-mcp-tools)

Let's analyze code quality using SonarQube MCP tools.

Create `04-test-sonarqube.ts`:

```typescript
import "dotenv/config";
import { Sandbox } from "e2b";

async function testSonarQube() {
  console.log("Creating sandbox...\n");

  const sbx = await Sandbox.betaCreate({
    envs: {
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
      GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
      SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!,
    },
    mcp: {
      githubOfficial: {
        githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
      },
      sonarqube: {
        org: process.env.SONARQUBE_ORG!,
        token: process.env.SONARQUBE_TOKEN!,
        url: "https://sonarcloud.io",
      },
    },
  });

  const mcpUrl = sbx.betaGetMcpUrl();
  const mcpToken = await sbx.betaGetMcpToken();

  await new Promise((resolve) => setTimeout(resolve, 1000));

  await sbx.commands.run(
    `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`,
    { timeoutMs: 0, onStdout: console.log, onStderr: console.log },
  );

  console.log("\nAnalyzing code quality with SonarQube...\n");

  const prompt = `Using the SonarQube MCP tools:
    1. List all projects in my organization
    2. For the first project, show:
    - Quality gate status (pass/fail)
    - Number of bugs
    - Number of code smells
    - Number of security vulnerabilities
    3. List the top 5 most critical issues found`;

  await sbx.commands.run(
    `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`,
    {
      timeoutMs: 0,
      onStdout: console.log,
      onStderr: console.log,
    },
  );

  await sbx.kill();
}

testSonarQube().catch(console.error);
```

Run the script:

```bash
npx tsx 04-test-sonarqube.ts
```

Create `04_test_sonarqube.py`:

```python
import os
import asyncio
from dotenv import load_dotenv
from e2b import AsyncSandbox

load_dotenv()

async def test_sonarqube():
    print("Creating sandbox...\n")

    sbx = await AsyncSandbox.beta_create(
        envs={
            "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
            "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
            "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"),
        },
        mcp={
            "githubOfficial": {
                "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
            },
            "sonarqube": {
                "org": os.getenv("SONARQUBE_ORG"),
                "token": os.getenv("SONARQUBE_TOKEN"),
                "url": "https://sonarcloud.io",
            },
        },
    )

    mcp_url = sbx.beta_get_mcp_url()
    mcp_token = await sbx.beta_get_mcp_token()

    await asyncio.sleep(1)

    await sbx.commands.run(
        f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"',
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    print("\nAnalyzing code quality with SonarQube...\n")

    prompt = """Using the SonarQube MCP tools:
    1. List all projects in my organization
    2. For the first project, show:
    - Quality gate status (pass/fail)
    - Number of bugs
    - Number of code smells
    - Number of security vulnerabilities
    3. List the top 5 most critical issues found"""

    await sbx.commands.run(
        f"echo '{prompt}' | claude -p --dangerously-skip-permissions",
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    await sbx.kill()

if __name__ == "__main__":
    asyncio.run(test_sonarqube())
```

Run the script:

```bash
python 04_test_sonarqube.py
```

> Note
>
> This script may take a few minutes to run.

You should see Claude output SonarQube analysis results:

```console
Creating sandbox...

Analyzing code quality with SonarQube...

## SonarQube Analysis Results

### 1. Projects in Your Organization

Found **1 project**:
- **Project Name**: project-1
- **Project Key**: project-testing

### 2. Project Analysis

...

### 3. Top 5 Most Critical Issues

Found 1 total issues (all are code smells with no critical/blocker severity):

1. **MAJOR Severity** - test.js:2
   - **Rule**: javascript:S1854
   - **Message**: Remove this useless assignment to variable "unusedVariable"
   - **Status**: OPEN

**Summary**: The project is in good health with no bugs or vulnerabilities detected.
```

You can now use SonarQube MCP tools to analyze code quality through natural language. You can retrieve quality metrics, identify issues, and understand what code needs fixing.

## [Step 5: Create a branch and make code changes](#step-5-create-a-branch-and-make-code-changes)

Now, let's teach Claude to fix code based on quality issues discovered by SonarQube.

Create `05-fix-code-issue.ts`:

```typescript
import "dotenv/config";
import { Sandbox } from "e2b";

async function fixCodeIssue() {
  console.log("Creating sandbox...\n");

  const sbx = await Sandbox.betaCreate({
    envs: {
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
      GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
      SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!,
    },
    mcp: {
      githubOfficial: {
        githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
      },
      sonarqube: {
        org: process.env.SONARQUBE_ORG!,
        token: process.env.SONARQUBE_TOKEN!,
        url: "https://sonarcloud.io",
      },
    },
  });

  const mcpUrl = sbx.betaGetMcpUrl();
  const mcpToken = await sbx.betaGetMcpToken();

  await new Promise((resolve) => setTimeout(resolve, 1000));

  await sbx.commands.run(
    `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`,
    { timeoutMs: 0, onStdout: console.log, onStderr: console.log },
  );

  const repoPath = `${process.env.GITHUB_OWNER}/${process.env.GITHUB_REPO}`;
  const branchName = `quality-fix-${Date.now()}`;

  console.log("\nFixing a code quality issue...\n");

  const prompt = `Using GitHub and SonarQube MCP tools:

    1. Analyze code quality in repository "${repoPath}" with SonarQube
    2. Find ONE simple issue that can be confidently fixed (like an unused variable or code smell)
    3. Create a new branch called "${branchName}"
    4. Read the file containing the issue using GitHub tools
    5. Fix the issue in the code
    6. Commit the fix to the new branch with a clear commit message

    Important: Only fix issues you're 100% confident about. Explain what you're fixing and why.`;

  await sbx.commands.run(
    `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`,
    {
      timeoutMs: 0,
      onStdout: console.log,
      onStderr: console.log,
    },
  );

  console.log(`\nœCheck your repository for branch: ${branchName}`);

  await sbx.kill();
}

fixCodeIssue().catch(console.error);
```

Run the script:

```bash
npx tsx 05-fix-code-issue.ts
```

Create `05_fix_code_issue.py`:

```python
import os
import asyncio
import time
from dotenv import load_dotenv
from e2b import AsyncSandbox

load_dotenv()

async def fix_code_issue():
    print("Creating sandbox...\n")

    sbx = await AsyncSandbox.beta_create(
        envs={
            "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
            "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
            "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"),
        },
        mcp={
            "githubOfficial": {
                "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
            },
            "sonarqube": {
                "org": os.getenv("SONARQUBE_ORG"),
                "token": os.getenv("SONARQUBE_TOKEN"),
                "url": "https://sonarcloud.io",
            },
        },
    )

    mcp_url = sbx.beta_get_mcp_url()
    mcp_token = await sbx.beta_get_mcp_token()

    await asyncio.sleep(1)

    await sbx.commands.run(
        f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"',
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    repo_path = f"{os.getenv('GITHUB_OWNER')}/{os.getenv('GITHUB_REPO')}"
    branch_name = f"quality-fix-{int(time.time() * 1000)}"

    print("\nFixing a code quality issue...\n")

    prompt = f"""Using GitHub and SonarQube MCP tools:

    1. Analyze code quality in repository "{repo_path}" with SonarQube
    2. Find ONE simple issue that can be confidently fixed (like an unused variable or code smell)
    3. Create a new branch called "{branch_name}"
    4. Read the file containing the issue using GitHub tools
    5. Fix the issue in the code
    6. Commit the fix to the new branch with a clear commit message

    Important: Only fix issues you're 100% confident about. Explain what you're fixing and why."""

    await sbx.commands.run(
        f"echo '{prompt}' | claude -p --dangerously-skip-permissions",
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    print(f"\n Check your repository for branch: {branch_name}")

    await sbx.kill()

if __name__ == "__main__":
    asyncio.run(fix_code_issue())
```

Run the script:

```bash
python 05_fix_code_issue.py
```

> Note
>
> This script may take a few minutes to run.

Claude will analyze your repository and fix a code quality issue:

```console
Creating sandbox...

Fixing a code quality issue...

## Task Completed Successfully!

I've successfully analyzed the repository and fixed a code quality issue. Here's what I did:

### 1. Analysis
Found 1 SonarQube issues in the `<your-repo>` repository:
- **Unused variable** (MINOR severity, line 2)
- Useless assignment (MAJOR severity, line 2)
- For-of loop suggestion (MINOR severity, lines 5-7)

### 2. Issue Fixed
**Location:** test.js:2
**Issue:** Unused variable declaration
**SonarQube Rule:** javascript:S1481
**What was wrong:** The line `const unusedVariable = "this is not used";` declared a variable that was never used anywhere in the function.

### 3. Why This Fix is Safe
- The variable was only declared and assigned, never referenced
- Removing it has zero impact on functionality
- It eliminates dead code and improves code quality
- This is a textbook example of a code smell that should be removed

### 4. Changes Made
- Created branch: `quality-fix-xxxxx`
- Removed the unused variable declaration
- Committed with a clear message explaining the fix and referencing the SonarQube rule

**Commit SHA:** `xxxxxxxxxxxxxxxxxxxxxxxxx`
**Branch:** https://github.com/<github-org>/<your-repo>/tree/quality-fix-xxxxx

The fix is ready for review and can be merged to improve the code quality of the repository!
```

You can now use GitHub and SonarQube MCP tools in the same workflow to read files, make code changes, and commit them.

## [Step 6: Create quality-gated pull requests](#step-6-create-quality-gated-pull-requests)

Finally, let's build the complete workflow: analyze quality, fix issues, and create a PR only if improvements are made.

Create `06-quality-gated-pr.ts`:

```typescript
import "dotenv/config";
import { Sandbox } from "e2b";

async function qualityGatedPR() {
  console.log("Creating sandbox for quality-gated PR workflow...\n");

  const sbx = await Sandbox.betaCreate({
    envs: {
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
      GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
      SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!,
    },
    mcp: {
      githubOfficial: {
        githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
      },
      sonarqube: {
        org: process.env.SONARQUBE_ORG!,
        token: process.env.SONARQUBE_TOKEN!,
        url: "https://sonarcloud.io",
      },
    },
  });

  const mcpUrl = sbx.betaGetMcpUrl();
  const mcpToken = await sbx.betaGetMcpToken();

  await new Promise((resolve) => setTimeout(resolve, 1000));

  await sbx.commands.run(
    `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`,
    { timeoutMs: 0, onStdout: console.log, onStderr: console.log },
  );

  const repoPath = `${process.env.GITHUB_OWNER}/${process.env.GITHUB_REPO}`;
  const branchName = `quality-improvements-${Date.now()}`;

  console.log("\nRunning quality-gated PR workflow...\n");

  const prompt = `You are a code quality engineer. Using GitHub and SonarQube MCP tools:

    STEP 1: ANALYSIS
    - Get current code quality status from SonarQube for "${repoPath}"
    - Record the current number of bugs, code smells, and vulnerabilities
    - Identify 1-3 issues that you can confidently fix

    STEP 2: FIX ISSUES
    - Create branch "${branchName}"
    - For each issue you're fixing:
        * Read the file with the issue
        * Make the fix
        * Commit with a descriptive message
    - Only fix issues where you're 100% confident the fix is correct

    STEP 3: VERIFICATION
        - After your fixes, check if quality metrics would improve
        - Calculate: Would this reduce bugs/smells/vulnerabilities?

    STEP 4: QUALITY GATE
        - Only proceed if your changes improve quality
        - If quality would not improve, explain why and stop

    STEP 5: CREATE PR (only if quality gate passes)
        - Create a pull request from "${branchName}" to main
        - Title: "Quality improvements: [describe what you fixed]"
        - Description should include:
            * What issues you fixed
            * Before/after quality metrics
            * Why these fixes improve code quality
        - Add a comment with detailed SonarQube analysis

    Be thorough and explain your decisions at each step.`;

  await sbx.commands.run(
    `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`,
    {
      timeoutMs: 0,
      onStdout: console.log,
      onStderr: console.log,
    },
  );

  console.log(`\n Workflow complete! Check ${repoPath} for new pull request.`);

  await sbx.kill();
}

qualityGatedPR().catch(console.error);
```

Run the script:

```bash
npx tsx 06-quality-gated-pr.ts
```

Create `06_quality_gated_pr.py`:

```python
import os
import asyncio
import time
from dotenv import load_dotenv
from e2b import AsyncSandbox

load_dotenv()

async def quality_gated_pr():
    print("Creating sandbox for quality-gated PR workflow...\n")

    sbx = await AsyncSandbox.beta_create(
        envs={
            "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
            "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
            "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"),
        },
        mcp={
            "githubOfficial": {
                "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
            },
            "sonarqube": {
                "org": os.getenv("SONARQUBE_ORG"),
                "token": os.getenv("SONARQUBE_TOKEN"),
                "url": "https://sonarcloud.io",
            },
        },
    )

    mcp_url = sbx.beta_get_mcp_url()
    mcp_token = await sbx.beta_get_mcp_token()

    await asyncio.sleep(1)

    await sbx.commands.run(
        f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"',
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    repo_path = f"{os.getenv('GITHUB_OWNER')}/{os.getenv('GITHUB_REPO')}"
    branch_name = f"quality-improvements-{int(time.time() * 1000)}"

    print("\nRunning quality-gated PR workflow...\n")

    prompt = f"""You are a code quality engineer. Using GitHub and SonarQube MCP tools:

    STEP 1: ANALYSIS
    - Get current code quality status from SonarQube for "{repo_path}"
    - Record the current number of bugs, code smells, and vulnerabilities
    - Identify 1-3 issues that you can confidently fix

    STEP 2: FIX ISSUES
    - Create branch "{branch_name}"
    - For each issue you are fixing:
        Read the file with the issue
        Make the fix
        Commit with a descriptive message
    - Only fix issues where you are 100 percent confident the fix is correct

    STEP 3: VERIFICATION
        - After your fixes, check if quality metrics would improve
        - Calculate: Would this reduce bugs/smells/vulnerabilities?

    STEP 4: QUALITY GATE
        - Only proceed if your changes improve quality
        - If quality would not improve, explain why and stop

    STEP 5: CREATE PR (only if quality gate passes)
        - Create a pull request from "{branch_name}" to main
        - Title: "Quality improvements: [describe what you fixed]"
        - Description should include:
            What issues you fixed
            Before/after quality metrics
            Why these fixes improve code quality
        - Add a comment with detailed SonarQube analysis

    Be thorough and explain your decisions at each step."""

    await sbx.commands.run(
        f"echo '{prompt.replace(chr(39), chr(39) + chr(92) + chr(39) + chr(39))}' | claude -p --dangerously-skip-permissions",
        timeout=0,
        on_stdout=print,
        on_stderr=print,
    )

    print(f"\n Workflow complete! Check {repo_path} for new pull request.")

    await sbx.kill()

if __name__ == "__main__":
    asyncio.run(quality_gated_pr())
```

Run the script:

```bash
python 06_quality_gated_pr.py
```

> Note
>
> This script may take a few minutes to run.

Claude will run the entire workflow, creating a quality improvement and opening a PR in GitHub:

```console
Creating sandbox for quality-gated PR workflow...

Running quality-gated PR workflow...

## Complete - Code Quality Improvement Successfully Executed

### Summary of Work Completed

**Pull Request Created:** https://github.com/<github-org>/<your-repo>/pull/1

---

### STEP 1: ANALYSIS

**Current State:**
- **Bugs:** 0
- **Vulnerabilities:** 0
- **Code Smells:** 1
- **Lines of Code:** 12
- **All Ratings:** A (Reliability, Security, Maintainability)

**Issues Identified (all in test.js):**
1. xxxxxxxxx - Unused variable declaration (MINOR)

---

### STEP 2: FIX ISSUES

**Branch Created:** `quality-improvements-xxxxxxxx`

**Changes Made:**
1. **Removed unused variable** (line 2) - Eliminated dead code that served no purpose
2. **Modernized loop pattern** (lines 5-7) - Converted `for (let i = 0; i < items.length; i++)` to `for (const item of items)`

**Commit:** xxxxxxxxxx

---

### STEP 3: VERIFICATION

**Expected Impact:**
- Code Smells: 1 → 0 (100% reduction)
- Bugs: 0 → 0 (maintained)
- Vulnerabilities: 0 → 0 (maintained)
- All quality ratings maintained at A

---

### STEP 4: QUALITY GATE PASSED

**Decision Criteria Met:**
- ✅ Reduces code smells by 100%
- ✅ No new bugs or vulnerabilities introduced
- ✅ Code is more readable and maintainable
- ✅ Follows modern JavaScript best practices
- ✅ All fixes are low-risk refactorings with no behavioral changes

---

### STEP 5: CREATE PR

**Pull Request Details:**
- **Number:** #1
- **Title:** Quality improvements: Remove unused variable and modernize for loop
- **Branch:** quality-improvements-xxxxxxxx → main
- **URL:** https://github.com/<github-org)/<your-repo>/pull/1

**PR Includes:**
- Comprehensive description with before/after metrics
- Detailed SonarQube analysis comment with issue breakdown
- Code comparison showing improvements
- Quality metrics table

The pull request is now ready for review and merge!
```

You've now built a complete, multi-step workflow with conditional logic. Claude analyzes quality with SonarQube, makes fixes using GitHub tools, verifies improvements, and only creates a PR if quality actually improves.

## [Step 7: Add error handling](#step-7-add-error-handling)

Production workflows need error handling. Let's make the workflow more robust.

Create `07-robust-workflow.ts`:

```typescript
import "dotenv/config";
import { Sandbox } from "e2b";

async function robustWorkflow() {
  let sbx: Sandbox | undefined;

  try {
    console.log("Creating sandbox...\n");

    sbx = await Sandbox.betaCreate({
      envs: {
        ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
        GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
        SONARQUBE_TOKEN: process.env.SONARQUBE_TOKEN!,
      },
      mcp: {
        githubOfficial: {
          githubPersonalAccessToken: process.env.GITHUB_TOKEN!,
        },
        sonarqube: {
          org: process.env.SONARQUBE_ORG!,
          token: process.env.SONARQUBE_TOKEN!,
          url: "https://sonarcloud.io",
        },
      },
    });

    const mcpUrl = sbx.betaGetMcpUrl();
    const mcpToken = await sbx.betaGetMcpToken();

    await new Promise((resolve) => setTimeout(resolve, 1000));

    await sbx.commands.run(
      `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`,
      { timeoutMs: 0, onStdout: console.log, onStderr: console.log },
    );

    const repoPath = `${process.env.GITHUB_OWNER}/${process.env.GITHUB_REPO}`;

    console.log("\nRunning workflow with error handling...\n");

    const prompt = `Run a quality improvement workflow for "${repoPath}".

    ERROR HANDLING RULES:
    1. If SonarQube is unreachable, explain the error and stop gracefully
    2. If GitHub API fails, retry once, then explain and stop
    3. If no fixable issues are found, explain why and exit (this is not an error)
    4. If file modifications fail, explain which file and why
    5. At each step, check for errors before proceeding

    Run the workflow and handle any errors you encounter professionally.`;

    await sbx.commands.run(
      `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`,
      {
        timeoutMs: 0,
        onStdout: console.log,
        onStderr: console.log,
      },
    );

    console.log("\n Workflow completed");
  } catch (error) {
    const err = error as Error;
    console.error("\n Workflow failed:", err.message);

    if (err.message.includes("403")) {
      console.error("\n Check your E2B account has MCP gateway access");
    } else if (err.message.includes("401")) {
      console.error("\n Check your API tokens are valid");
    } else if (err.message.includes("Credit balance")) {
      console.error("\n Check your Anthropic API credit balance");
    }

    process.exit(1);
  } finally {
    if (sbx) {
      console.log("\n Cleaning up sandbox...");
      await sbx.kill();
    }
  }
}

robustWorkflow().catch(console.error);
```

Run the script:

```bash
npx tsx 07-robust-workflow.ts
```

Create `07_robust_workflow.py`:

```python
import os
import asyncio
import sys
from dotenv import load_dotenv
from e2b import AsyncSandbox

load_dotenv()

async def robust_workflow():
    sbx = None

    try:
        print("Creating sandbox...\n")

        sbx = await AsyncSandbox.beta_create(
            envs={
                "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
                "GITHUB_TOKEN": os.getenv("GITHUB_TOKEN"),
                "SONARQUBE_TOKEN": os.getenv("SONARQUBE_TOKEN"),
            },
            mcp={
                "githubOfficial": {
                    "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
                },
                "sonarqube": {
                    "org": os.getenv("SONARQUBE_ORG"),
                    "token": os.getenv("SONARQUBE_TOKEN"),
                    "url": "https://sonarcloud.io",
                },
            },
        )

        mcp_url = sbx.beta_get_mcp_url()
        mcp_token = await sbx.beta_get_mcp_token()

        await asyncio.sleep(1)

        await sbx.commands.run(
            f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"',
            timeout=0,  # Fixed: was timeout_ms
            on_stdout=print,
            on_stderr=print,
        )

        repo_path = f"{os.getenv('GITHUB_OWNER')}/{os.getenv('GITHUB_REPO')}"

        print("\nRunning workflow with error handling...\n")

        prompt = f"""Run a quality improvement workflow for "{repo_path}".

        ERROR HANDLING RULES:
        1. If SonarQube is unreachable, explain the error and stop gracefully
        2. If GitHub API fails, retry once, then explain and stop
        3. If no fixable issues are found, explain why and exit (this is not an error)
        4. If file modifications fail, explain which file and why
        5. At each step, check for errors before proceeding

        Run the workflow and handle any errors you encounter professionally."""

        await sbx.commands.run(
            f"echo '{prompt}' | claude -p --dangerously-skip-permissions",
            timeout=0,
            on_stdout=print,
            on_stderr=print,
        )

        print("\n Workflow completed")

    except Exception as error:
        print(f"\n✗ Workflow failed: {str(error)}")

        error_msg = str(error)
        if "403" in error_msg:
            print("\n Check your E2B account has MCP gateway access")
        elif "401" in error_msg:
            print("\n Check your API tokens are valid")
        elif "Credit balance" in error_msg:
            print("\n Check your Anthropic API credit balance")

        sys.exit(1)

    finally:
        if sbx:
            print("\n Cleaning up sandbox...")
            await sbx.kill()

if __name__ == "__main__":
    asyncio.run(robust_workflow())
```

Run the script:

```bash
python 07_robust_workflow.py
```

Claude will run the entire workflow, and if it encounters an error, respond with robust error messaging.

## [Next steps](#next-steps)

In the next section, you'll customize your workflow for your needs.

[Customize a code quality check workflow »](https://docs.docker.com/guides/github-sonarqube-sandbox/customize/)

----
url: https://docs.docker.com/extensions/extensions-sdk/extensions/labels/
----

# Extension image labels

***

Table of contents

***

Extensions use image labels to provide additional information such as a title, description, screenshots, and more.

This information is then displayed as an overview of the extension, so users can choose to install it.

You can define [image labels](https://docs.docker.com/reference/dockerfile/#label) in the extension's `Dockerfile`.

> Important
>
> If any of the **required** labels are missing in the `Dockerfile`, Docker Desktop considers the extension invalid and doesn't list it in the Marketplace.

Here is the list of labels you can or need to specify when building your extension:

| Label                                       | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Example                                                                                                                                                                                                                                                         |
| ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `org.opencontainers.image.title`            | Yes      | Human-readable title of the image (string). This appears in the UI for Docker Desktop.                                                                                                                                                                                                                                                                                                                                                                                                                                    | my-extension                                                                                                                                                                                                                                                    |
| `org.opencontainers.image.description`      | Yes      | Human-readable description of the software packaged in the image (string)                                                                                                                                                                                                                                                                                                                                                                                                                                                 | This extension is cool.                                                                                                                                                                                                                                         |
| `org.opencontainers.image.vendor`           | Yes      | Name of the distributing entity, organization, or individual.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Acme, Inc.                                                                                                                                                                                                                                                      |
| `com.docker.desktop.extension.api.version`  | Yes      | Version of the Docker Extension manager that the extension is compatible with. It must follow [semantic versioning](https://semver.org/).                                                                                                                                                                                                                                                                                                                                                                                 | A specific version like `0.1.0` or, a constraint expression: `>= 0.1.0`, `>= 1.4.7, < 2.0` . For your first extension, you can use `docker extension version` to know the SDK API version and specify `>= <SDK_API_VERSION>`.                                   |
| `com.docker.desktop.extension.icon`         | Yes      | The extension icon (format: .svg .png .jpg)                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `https://example.com/assets/image.svg`                                                                                                                                                                                                                          |
| `com.docker.extension.screenshots`          | Yes      | A JSON array of image URLs and an alternative text displayed to users (in the order they appear in your metadata) in your extension's details page. **Note:** The recommended size for screenshots is 2400x1600 pixels.                                                                                                                                                                                                                                                                                                   | `[{"alt":"alternative text for image 1",` `"url":"https://example.com/image1.png"},` `{"alt":"alternative text for image2",` `"url":"https://example.com/image2.jpg"}]`                                                                                         |
| `com.docker.extension.detailed-description` | Yes      | Additional information in plain text or HTML about the extension to display in the details dialog.                                                                                                                                                                                                                                                                                                                                                                                                                        | `My detailed description` or `<h1>My detailed description</h1>`                                                                                                                                                                                                 |
| `com.docker.extension.publisher-url`        | Yes      | The publisher website URL to display in the details dialog.                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `https://example.com`                                                                                                                                                                                                                                           |
| `com.docker.extension.additional-urls`      | No       | A JSON array of titles and additional URLs displayed to users (in the order they appear in your metadata) in your extension's details page. Docker recommends you display the following links if they apply: documentation, support, terms of service, and privacy policy links.                                                                                                                                                                                                                                          | `[{"title":"Documentation","url":"https://example.com/docs"},` `{"title":"Support","url":"https://example.com/bar/support"},` `{"title":"Terms of Service","url":"https://example.com/tos"},` `{"title":"Privacy policy","url":"https://example.com/privacy"}]` |
| `com.docker.extension.changelog`            | Yes      | Changelog in plain text or HTML containing the change for the current version only.                                                                                                                                                                                                                                                                                                                                                                                                                                       | `Extension changelog` or `<p>Extension changelog<ul>` `<li>New feature A</li>` `<li>Bug fix on feature B</li></ul></p>`                                                                                                                                         |
| `com.docker.extension.account-info`         | No       | Whether the user needs to register to a SaaS platform to use some features of the extension.                                                                                                                                                                                                                                                                                                                                                                                                                              | `required` in case it does, leave it empty otherwise.                                                                                                                                                                                                           |
| `com.docker.extension.categories`           | No       | The list of Marketplace categories that your extension belongs to: `ci-cd`, `container-orchestration`, `cloud-deployment`, `cloud-development`, `database`, `kubernetes`, `networking`, `image-registry`, `security`, `testing-tools`, `utility-tools`,`volumes`. If you don't specify this label, users won't be able to find your extension in the Extensions Marketplace when filtering by a category. Extensions published to the Marketplace before the 22nd of September 2022 have been auto-categorized by Docker. | Specified as comma separated values in case of having multiple categories e.g: `kubernetes,security` or a single value e.g. `kubernetes`.                                                                                                                       |

> Tip
>
> Docker Desktop applies CSS styles to the provided HTML content. You can make sure that it renders correctly [within the Marketplace](#preview-the-extension-in-the-marketplace). It is recommended that you follow the [styling guidelines](https://docs.docker.com/extensions/extensions-sdk/design/).

## [Preview the extension in the Marketplace](#preview-the-extension-in-the-marketplace)

You can validate that the image labels render as you expect.

When you create and install your unpublished extension, you can preview the extension in the Marketplace's **Managed** tab. You can see how the extension labels render in the list and in the details page of the extension.

> Preview extensions already listed in Marketplace
>
> When you install a local image of an extension already published in the Marketplace, for example with the tag `latest`, your local image is not detected as "unpublished".
>
> You can re-tag your image in order to have a different image name that's not listed as a published extension. Use `docker tag org/published-extension unpublished-extension` and then `docker extension install unpublished-extension`.

----
url: https://docs.docker.com/reference/cli/docker/mcp/feature/ls/
----

# docker mcp feature ls

***

| Description                                                               | List all available features and their status |
| ------------------------------------------------------------------------- | -------------------------------------------- |
| Usage                                                                     | `docker mcp feature ls`                      |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker mcp feature list`                    |

## [Description](#description)

List all available experimental features and show whether they are enabled or disabled.

----
url: https://docs.docker.com/reference/cli/docker/offload/diagnose/
----

# docker offload diagnose

***

| Description | Print diagnostic information for Docker Offload |
| ----------- | ----------------------------------------------- |
| Usage       | `docker offload diagnose`                       |

----
url: https://docs.docker.com/engine/security/trust/
----

# Content trust in Docker

***

Table of contents

***

When transferring data among networked systems, trust is a central concern. In particular, when communicating over an untrusted medium such as the internet, it is critical to ensure the integrity and the publisher of all the data a system operates on. You use Docker Engine to push and pull images (data) to a public or private registry. Content trust gives you the ability to verify both the integrity and the publisher of all the data received from a registry over any channel.

## [About Docker Content Trust (DCT)](#about-docker-content-trust-dct)

Docker Content Trust (DCT) provides the ability to use digital signatures for data sent to and received from remote Docker registries. These signatures allow client-side or runtime verification of the integrity and publisher of specific image tags.

Through DCT, image publishers can sign their images and image consumers can ensure that the images they pull are signed. Publishers could be individuals or organizations manually signing their content or automated software supply chains signing content as part of their release process.

> Note
>
> Docker is retiring DCT for Docker Official Images (DOI). You should start planning to transition to a different image signing and verification solution (like [Sigstore](https://www.sigstore.dev/) or [Notation](https://github.com/notaryproject/notation#readme)). Timelines for the complete deprecation of DCT are being finalized and will be published soon.
>
> For more information, see [Retiring Docker Content Trust](https://www.docker.com/blog/retiring-docker-content-trust/).

### [Image tags and DCT](#image-tags-and-dct)

An individual image record has the following identifier:

```text
[REGISTRY_HOST[:REGISTRY_PORT]/]REPOSITORY[:TAG]
```

A particular image `REPOSITORY` can have multiple tags. For example, `latest` and `3.1.2` are both tags on the `mongo` image. An image publisher can build an image and tag combination many times changing the image with each build.

DCT is associated with the `TAG` portion of an image. Each image repository has a set of keys that image publishers use to sign an image tag. Image publishers have discretion on which tags they sign.

An image repository can contain an image with one tag that is signed and another tag that is not. For example, consider [the Mongo image repository](https://hub.docker.com/_/mongo/tags/). The `latest` tag could be unsigned while the `3.1.6` tag could be signed. It is the responsibility of the image publisher to decide if an image tag is signed or not. In this representation, some image tags are signed, others are not:

Publishers can choose to sign a specific tag or not. As a result, the content of an unsigned tag and that of a signed tag with the same name may not match. For example, a publisher can push a tagged image `someimage:latest` and sign it. Later, the same publisher can push an unsigned `someimage:latest` image. This second push replaces the last unsigned tag `latest` but does not affect the signed `latest` version. The ability to choose which tags they can sign, allows publishers to iterate over the unsigned version of an image before officially signing it.

Image consumers can enable DCT to ensure that images they use were signed. If a consumer enables DCT, they can only pull, run, or build with trusted images. Enabling DCT is a bit like applying a "filter" to your registry. Consumers "see" only signed image tags and the less desirable, unsigned image tags are "invisible" to them.

To the consumer who has not enabled DCT, nothing about how they work with Docker images changes. Every image is visible regardless of whether it is signed or not.

### [Docker Content Trust Keys](#docker-content-trust-keys)

Trust for an image tag is managed through the use of signing keys. A key set is created when an operation using DCT is first invoked. A key set consists of the following classes of keys:

* An offline key that is the root of DCT for an image tag
* Repository or tagging keys that sign tags
* Server-managed keys such as the timestamp key, which provides freshness security guarantees for your repository

The following image depicts the various signing keys and their relationships:

> Warning
>
> The root key once lost is not recoverable. If you lose any other key, send an email to [Docker Hub Support](mailto:hub-support@docker.com). This loss also requires manual intervention from every consumer that used a signed tag from this repository prior to the loss.

You should back up the root key somewhere safe. Given that it is only required to create new repositories, it is a good idea to store it offline in hardware. For details on securing, and backing up your keys, make sure you read how to [manage keys for DCT](https://docs.docker.com/engine/security/trust/trust_key_mng/).

## [Signing images with Docker Content Trust](#signing-images-with-docker-content-trust)

Within the Docker CLI we can sign and push a container image with the `$ docker trust` command syntax. This is built on top of the Notary feature set. For more information, see the [Notary GitHub repository](https://github.com/theupdateframework/notary).

A prerequisite for signing an image is a Docker Registry with a Notary server (such as Docker Hub) attached. Refer to [Deploying Notary](/engine/security/trust/deploying_notary/) for instructions.

To sign a Docker Image you will need a delegation key pair. These keys can be generated locally using `$ docker trust key generate` or generated by a certificate authority.

First we will add the delegation private key to the local Docker trust repository. (By default this is stored in `~/.docker/trust/`). If you are generating delegation keys with `$ docker trust key generate`, the private key is automatically added to the local trust store. If you are importing a separate key, you will need to use the `$ docker trust key load` command.

```console
$ docker trust key generate jeff
Generating key for jeff...
Enter passphrase for new jeff key with ID 9deed25:
Repeat passphrase for new jeff key with ID 9deed25:
Successfully generated and loaded private key. Corresponding public key available: /home/ubuntu/Documents/mytrustdir/jeff.pub
```

Or if you have an existing key:

```console
$ docker trust key load key.pem --name jeff
Loading key from "key.pem"...
Enter passphrase for new jeff key with ID 8ae710e:
Repeat passphrase for new jeff key with ID 8ae710e:
Successfully imported key from key.pem
```

Next we will need to add the delegation public key to the Notary server; this is specific to a particular image repository in Notary known as a Global Unique Name (GUN). If this is the first time you are adding a delegation to that repository, this command will also initiate the repository, using a local Notary canonical root key. To understand more about initiating a repository, and the role of delegations, head to [delegations for content trust](https://docs.docker.com/engine/security/trust/trust_delegation/).

```console
$ docker trust signer add --key cert.pem jeff registry.example.com/admin/demo
Adding signer "jeff" to registry.example.com/admin/demo...
Enter passphrase for new repository key with ID 10b5e94:
```

Finally, we will use the delegation private key to sign a particular tag and push it up to the registry.

```console
$ docker trust sign registry.example.com/admin/demo:1
Signing and pushing trust data for local image registry.example.com/admin/demo:1, may overwrite remote trust data
The push refers to repository [registry.example.com/admin/demo]
7bff100f35cb: Pushed
1: digest: sha256:3d2e482b82608d153a374df3357c0291589a61cc194ec4a9ca2381073a17f58e size: 528
Signing and pushing trust metadata
Enter passphrase for signer key with ID 8ae710e:
Successfully signed registry.example.com/admin/demo:1
```

Alternatively, once the keys have been imported an image can be pushed with the `$ docker push` command, by exporting the DCT environmental variable.

```console
$ export DOCKER_CONTENT_TRUST=1

$ docker push registry.example.com/admin/demo:1
The push refers to repository [registry.example.com/admin/demo:1]
7bff100f35cb: Pushed
1: digest: sha256:3d2e482b82608d153a374df3357c0291589a61cc194ec4a9ca2381073a17f58e size: 528
Signing and pushing trust metadata
Enter passphrase for signer key with ID 8ae710e:
Successfully signed registry.example.com/admin/demo:1
```

Remote trust data for a tag or a repository can be viewed by the `$ docker trust inspect` command:

```console
$ docker trust inspect --pretty registry.example.com/admin/demo:1

Signatures for registry.example.com/admin/demo:1

SIGNED TAG          DIGEST                                                             SIGNERS
1                   3d2e482b82608d153a374df3357c0291589a61cc194ec4a9ca2381073a17f58e   jeff

List of signers and their keys for registry.example.com/admin/demo:1

SIGNER              KEYS
jeff                8ae710e3ba82

Administrative keys for registry.example.com/admin/demo:1

  Repository Key:	10b5e94c916a0977471cc08fa56c1a5679819b2005ba6a257aa78ce76d3a1e27
  Root Key:	84ca6e4416416d78c4597e754f38517bea95ab427e5f95871f90d460573071fc
```

Remote Trust data for a tag can be removed by the `$ docker trust revoke` command:

```console
$ docker trust revoke registry.example.com/admin/demo:1
Enter passphrase for signer key with ID 8ae710e:
Successfully deleted signature for registry.example.com/admin/demo:1
```

## [Client enforcement with Docker Content Trust](#client-enforcement-with-docker-content-trust)

Content trust is disabled by default in the Docker Client. To enable it, set the `DOCKER_CONTENT_TRUST` environment variable to `1`. This prevents users from working with tagged images unless they contain a signature.

When DCT is enabled in the Docker client, `docker` CLI commands that operate on tagged images must either have content signatures or explicit content hashes. The commands that operate with DCT are:

* `push`
* `build`
* `create`
* `pull`
* `run`

For example, with DCT enabled a `docker pull someimage:latest` only succeeds if `someimage:latest` is signed. However, an operation with an explicit content hash always succeeds as long as the hash exists:

```console
$ docker pull registry.example.com/user/image:1
Error: remote trust data does not exist for registry.example.com/user/image: registry.example.com does not have trust data for registry.example.com/user/image

$ docker pull registry.example.com/user/image@sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d850b2a2a67f2819a
sha256:ee7491c9c31db1ffb7673d91e9fac5d6354a89d0e97408567e09df069a1687c1: Pulling from user/image
ff3a5c916c92: Pull complete
a59a168caba3: Pull complete
Digest: sha256:ee7491c9c31db1ffb7673d91e9fac5d6354a89d0e97408567e09df069a1687c1
Status: Downloaded newer image for registry.example.com/user/image@sha256:ee7491c9c31db1ffb7673d91e9fac5d6354a89d0e97408567e09df069a1687c1
```

## [Related information](#related-information)

* [Delegations for content trust](https://docs.docker.com/engine/security/trust/trust_delegation/)
* [Automation with content trust](https://docs.docker.com/engine/security/trust/trust_automation/)
* [Manage keys for content trust](https://docs.docker.com/engine/security/trust/trust_key_mng/)
* [Play in a content trust sandbox](https://docs.docker.com/engine/security/trust/trust_sandbox/)

----
url: https://docs.docker.com/extensions/extensions-sdk/guides/invoke-host-binaries/
----

# Invoke host binaries

***

Table of contents

***

In some cases, your extension may need to invoke some command from the host. For example, you might want to invoke the CLI of your cloud provider to create a new resource, or the CLI of a tool your extension provides, or even a shell script that you want to run on the host.

You could do that by executing the CLI from a container with the extension SDK. But this CLI needs to access the host's filesystem, which isn't easy nor fast if it runs in a container.

This page describes how to run executables on the host (binaries, shell scripts) that are shipped as part of your extension and deployed to the host. As extensions can run on multiple platforms, this means that you need to ship the executables for all the platforms you want to support.

Learn more about extensions [architecture](https://docs.docker.com/extensions/extensions-sdk/architecture/).

> Note
>
> Note that extensions run with user access rights, this API is not restricted to binaries listed in the [host section](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#host-section) of the extension metadata (some extensions might install software during user interaction, and invoke newly installed binaries even if not listed in the extension metadata).

In this example, the CLI is a simple `Hello world` script that must be invoked with a parameter and returns a string.

## [Add the executables to the extension](#add-the-executables-to-the-extension)

Create a `bash` script for macOS and Linux, in the file `binaries/unix/hello.sh` with the following content:

```bash
#!/bin/sh
echo "Hello, $1!"
```

Create a `batch script` for Windows in another file `binaries/windows/hello.cmd` with the following content:

```bash
@echo off
echo "Hello, %1!"
```

Then update the `Dockerfile` to copy the `binaries` folder into the extension's container filesystem and make the files executable.

```dockerfile
# Copy the binaries into the right folder
COPY --chmod=0755 binaries/windows/hello.cmd /windows/hello.cmd
COPY --chmod=0755 binaries/unix/hello.sh /linux/hello.sh
COPY --chmod=0755 binaries/unix/hello.sh /darwin/hello.sh
```

## [Invoke the executable from the UI](#invoke-the-executable-from-the-ui)

In your extension, use the Docker Desktop Client object to [invoke the shell script](https://docs.docker.com/extensions/extensions-sdk/dev/api/backend/#invoke-an-extension-binary-on-the-host) provided by the extension with the `ddClient.extension.host.cli.exec()` function. In this example, the binary returns a string as result, obtained by `result?.stdout`, as soon as the extension view is rendered.

```typescript
export function App() {
  const ddClient = createDockerDesktopClient();
  const [hello, setHello] = useState("");

  useEffect(() => {
    const run = async () => {
      let binary = "hello.sh";
      if (ddClient.host.platform === 'win32') {
        binary = "hello.cmd";
      }

      const result = await ddClient.extension.host?.cli.exec(binary, ["world"]);
      setHello(result?.stdout);

    };
    run();
  }, [ddClient]);
    
  return (
    <div>
      {hello}
    </div>
  );
}
```

> Important
>
> We don't have an example for Vue yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Vue) and let us know if you'd like a sample with Vue.

> Important
>
> We don't have an example for Angular yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Angular) and let us know if you'd like a sample with Angular.

> Important
>
> We don't have an example for Svelte yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Svelte) and let us know if you'd like a sample with Svelte.

## [Configure the metadata file](#configure-the-metadata-file)

The host binaries must be specified in the `metadata.json` file so that Docker Desktop copies them on to the host when installing the extension. Once the extension is uninstalled, the binaries that were copied are removed as well.

```json
{
  "vm": {
    ...
  },
  "ui": {
    ...
  },
  "host": {
    "binaries": [
      {
        "darwin": [
          {
            "path": "/darwin/hello.sh"
          }
        ],
        "linux": [
          {
            "path": "/linux/hello.sh"
          }
        ],
        "windows": [
          {
            "path": "/windows/hello.cmd"
          }
        ]
      }
    ]
  }
}
```

The `path` must reference the path of the binary inside the container.

----
url: https://docs.docker.com/engine/swarm/how-swarm-mode-works/swarm-task-states/
----

# Swarm task states

***

Table of contents

***

Docker lets you create services, which can start tasks. A service is a description of a desired state, and a task does the work. Work is scheduled on swarm nodes in this sequence:

1. Create a service by using `docker service create`.
2. The request goes to a Docker manager node.
3. The Docker manager node schedules the service to run on particular nodes.
4. Each service can start multiple tasks.
5. Each task has a life cycle, with states like `NEW`, `PENDING`, and `COMPLETE`.

Tasks are execution units that run once to completion. When a task stops, it isn't executed again, but a new task may take its place.

Tasks advance through a number of states until they complete or fail. Tasks are initialized in the `NEW` state. The task progresses forward through a number of states, and its state doesn't go backward. For example, a task never goes from `COMPLETE` to `RUNNING`.

Tasks go through the states in the following order:

| Task state  | Description                                                                                                 |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| `NEW`       | The task was initialized.                                                                                   |
| `PENDING`   | Resources for the task were allocated.                                                                      |
| `ASSIGNED`  | Docker assigned the task to nodes.                                                                          |
| `ACCEPTED`  | The task was accepted by a worker node. If a worker node rejects the task, the state changes to `REJECTED`. |
| `READY`     | The worker node is ready to start the task                                                                  |
| `PREPARING` | Docker is preparing the task.                                                                               |
| `STARTING`  | Docker is starting the task.                                                                                |
| `RUNNING`   | The task is executing.                                                                                      |
| `COMPLETE`  | The task exited without an error code.                                                                      |
| `FAILED`    | The task exited with an error code.                                                                         |
| `SHUTDOWN`  | Docker requested the task to shut down.                                                                     |
| `REJECTED`  | The worker node rejected the task.                                                                          |
| `ORPHANED`  | The node was down for too long.                                                                             |
| `REMOVE`    | The task is not terminal but the associated service was removed or scaled down.                             |

## [View task state](#view-task-state)

Run `docker service ps <service-name>` to get the state of a task. The `CURRENT STATE` field shows the task's state and how long it's been there.

```console
$ docker service ps webserver
ID             NAME              IMAGE    NODE        DESIRED STATE  CURRENT STATE            ERROR                              PORTS
owsz0yp6z375   webserver.1       nginx    UbuntuVM    Running        Running 44 seconds ago
j91iahr8s74p    \_ webserver.1   nginx    UbuntuVM    Shutdown       Failed 50 seconds ago    "No such container: webserver.…"
7dyaszg13mw2    \_ webserver.1   nginx    UbuntuVM    Shutdown       Failed 5 hours ago       "No such container: webserver.…"
```

## [Where to go next](#where-to-go-next)

* [Learn about swarm tasks](https://github.com/moby/swarmkit/blob/master/design/task_model.md)

----
url: https://docs.docker.com/dhi/core-concepts/provenance/
----

# Image provenance

***

Table of contents

***

## [What is image provenance?](#what-is-image-provenance)

Image provenance refers to metadata that traces the origin, authorship, and integrity of a container image. It answers critical questions such as:

* Where did this image come from?
* Who built it?
* Has it been tampered with?

Provenance establishes a chain of custody, helping you verify that the image you're using is the result of a trusted and verifiable build process.

## [Why image provenance matters](#why-image-provenance-matters)

Provenance is foundational to securing your software supply chain. Without it, you risk:

* Running unverified or malicious images
* Failing to meet internal or regulatory compliance requirements
* Losing visibility into the components and workflows that produce your containers

With reliable provenance, you gain:

* Trust: Know that your images are authentic and unchanged.
* Traceability: Understand the full build process and source inputs.
* Auditability: Provide verifiable evidence of compliance and build integrity.

Provenance also supports automated policy enforcement and is a key requirement for frameworks like SLSA (Supply-chain Levels for Software Artifacts).

## [How Docker Hardened Images support provenance](#how-docker-hardened-images-support-provenance)

Docker Hardened Images (DHIs) are designed with built-in provenance to help you adopt secure-by-default practices and meet supply chain security standards.

### [Attestations](#attestations)

DHIs include [attestations](https://docs.docker.com/dhi/core-concepts/attestations/)—machine-readable metadata that describe how, when, and where the image was built. These are generated using industry standards such as [in-toto](https://in-toto.io/) and align with [SLSA provenance](https://slsa.dev/spec/v1.0/provenance/).

Attestations allow you to:

* Validate that builds followed the expected steps
* Confirm that inputs and environments meet policy
* Trace the build process across systems and stages

### [Code signing](#code-signing)

Each Docker Hardened Image is cryptographically [signed](https://docs.docker.com/dhi/core-concepts/signatures/) and stored in the registry alongside its digest. These signatures are verifiable proofs of authenticity and are compatible with tools like `cosign`, Docker Scout, and Kubernetes admission controllers.

With image signatures, you can:

* Confirm that the image was published by Docker
* Detect if an image has been modified or republished
* Enforce signature validation in CI/CD or production deployments

## [Additional resources](#additional-resources)

* [Provenance attestations](/build/metadata/attestations/slsa-provenance/)
* [Image signatures](https://docs.docker.com/dhi/core-concepts/signatures/)
* [Attestations overview](https://docs.docker.com/dhi/core-concepts/attestations/)

----
url: https://docs.docker.com/reference/api/extensions-sdk/ExecResult/
----

# Interface: ExecResult

***

Table of contents

***

**`Since`**

0.2.0

## [Hierarchy](#hierarchy)

* [`RawExecResult`](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/)

  ↳ **`ExecResult`**

***

### [parseJsonLines](#parsejsonlines)

▸ **parseJsonLines**(): `any`\[]

Parse each output line as a JSON object.

#### [Returns](#returns-1)

`any`\[]

The list of lines where each line is a JSON object.

***

### [parseJsonObject](#parsejsonobject)

▸ **parseJsonObject**(): `any`

Parse a well-formed JSON output.

#### [Returns](#returns-2)

`any`

The JSON object.

## [Properties](#properties)

### [cmd](#cmd)

• `Optional` `Readonly` **cmd**: `string`

#### [Inherited from](#inherited-from)

[RawExecResult](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/).[cmd](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/#cmd)

***

### [killed](#killed)

• `Optional` `Readonly` **killed**: `boolean`

#### [Inherited from](#inherited-from-1)

[RawExecResult](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/).[killed](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/#killed)

***

### [signal](#signal)

• `Optional` `Readonly` **signal**: `string`

#### [Inherited from](#inherited-from-2)

[RawExecResult](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/).[signal](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/#signal)

***

### [code](#code)

• `Optional` `Readonly` **code**: `number`

#### [Inherited from](#inherited-from-3)

[RawExecResult](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/).[code](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/#code)

***

### [stdout](#stdout)

• `Readonly` **stdout**: `string`

#### [Inherited from](#inherited-from-4)

[RawExecResult](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/).[stdout](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/#stdout)

***

### [stderr](#stderr)

• `Readonly` **stderr**: `string`

#### [Inherited from](#inherited-from-5)

[RawExecResult](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/).[stderr](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/#stderr)

----
url: https://docs.docker.com/reference/cli/docker/buildx/policy/eval/
----

# docker buildx policy eval

***

| Description | Evaluate policy for a source                 |
| ----------- | -------------------------------------------- |
| Usage       | `docker buildx policy eval [OPTIONS] source` |

## [Description](#description)

Evaluate policy for a source

## [Options](#options)

| Option       | Default      | Description                           |
| ------------ | ------------ | ------------------------------------- |
| `--fields`   |              | Fields to evaluate                    |
| `-f, --file` | `Dockerfile` | Policy filename to evaluate           |
| `--platform` |              | Target platform for policy evaluation |
| `--print`    |              | Print policy output                   |

----
url: https://docs.docker.com/reference/api/extensions-sdk/RequestConfig/
----

# Interface: RequestConfig

***

Table of contents

***

**`Since`**

0.2.0

## [Properties](#properties)

### [url](#url)

• `Readonly` **url**: `string`

***

### [method](#method)

• `Readonly` **method**: `string`

***

### [headers](#headers)

• `Readonly` **headers**: `Record`<`string`, `string`>

***

### [data](#data)

• `Readonly` **data**: `any`

----
url: https://docs.docker.com/build/bake/overrides/
----

# Overriding configurations

***

Table of contents

***

Bake supports loading build definitions from files, but sometimes you need even more flexibility to configure these definitions. For example, you might want to override an attribute when building in a particular environment or for a specific target.

The following list of attributes can be overridden:

* `args`
* `attest`
* `cache-from`
* `cache-to`
* `context`
* `contexts`
* `dockerfile`
* `entitlements`
* `labels`
* `network`
* `no-cache`
* `output`
* `platform`
* `pull`
* `secrets`
* `ssh`
* `tags`
* `target`

To override these attributes, you can use the following methods:

* [File overrides](#file-overrides)
* [CLI overrides](#command-line)
* [Environment variable overrides](#environment-variables)

## [File overrides](#file-overrides)

You can load multiple Bake files that define build configurations for your targets. This is useful when you want to separate configurations into different files for better organization, or to conditionally override configurations based on which files are loaded.

### [Default file lookup](#default-file-lookup)

You can use the `--file` or `-f` flag to specify which files to load. If you don't specify any files, Bake will use the following lookup order:

If more than one Bake file is found, all files are loaded and merged into a single definition. Files are merged according to the lookup order.

```console
$ docker buildx bake --print
[+] Building 0.0s (1/1) FINISHED                                                                                                                                                                                            
 => [internal] load local bake definitions                                                                                                                                                                             0.0s
 => => reading compose.yaml 45B / 45B                                                                                                                                                                                  0.0s
 => => reading docker-bake.hcl 113B / 113B                                                                                                                                                                             0.0s
 => => reading docker-bake.override.hcl 65B / 65B
```

If merged files contain duplicate attribute definitions, those definitions are either merged or overridden by the last occurrence, depending on the attribute.

Bake will attempt to load all of the files in the order they are found. If multiple files define the same target, attributes are either merged or overridden. In the case of overrides, the last one loaded takes precedence.

For example, given the following files:

docker-bake.hcl

```hcl
variable "TAG" {
  default = "foo"
}

target "default" {
  tags = ["username/my-app:${TAG}"]
}
```

docker-bake.override.hcl

```hcl
variable "TAG" {
  default = "bar"
}
```

Since `docker-bake.override.hcl` is loaded last in the default lookup order, the `TAG` variable is overridden with the value `bar`.

```console
$ docker buildx bake --print
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": ["username/my-app:bar"]
    }
  }
}
```

### [Manual file overrides](#manual-file-overrides)

You can use the `--file` flag to explicitly specify which files to load, and use this as a way to conditionally apply override files.

For example, you can create a file that defines a set of configurations for a specific environment, and load it only when building for that environment. The following example shows how to load an `override.hcl` file that sets the `TAG` variable to `bar`. The `TAG` variable is then used in the `default` target.

docker-bake.hcl

```hcl
variable "TAG" {
  default = "foo"
}

target "default" {
  tags = ["username/my-app:${TAG}"]
}
```

overrides.hcl

```hcl
variable "TAG" {
  default = "bar"
}
```

Printing the build configuration without the `--file` flag shows the `TAG` variable is set to the default value `foo`.

```console
$ docker buildx bake --print
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "username/my-app:foo"
      ]
    }
  }
}
```

Using the `--file` flag to load the `overrides.hcl` file overrides the `TAG` variable with the value `bar`.

```console
$ docker buildx bake -f docker-bake.hcl -f overrides.hcl --print
{
  "target": {
    "default": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": [
        "username/my-app:bar"
      ]
    }
  }
}
```

## [Command line](#command-line)

You can also override target configurations from the command line with the [`--set` flag](/reference/cli/docker/buildx/bake/#set):

```hcl
# docker-bake.hcl
target "app" {
  args = {
    mybuildarg = "foo"
  }
}
```

```console
$ docker buildx bake --set app.args.mybuildarg=bar --set app.platform=linux/arm64 app --print
```

```json
{
  "group": {
    "default": {
      "targets": ["app"]
    }
  },
  "target": {
    "app": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "mybuildarg": "bar"
      },
      "platforms": ["linux/arm64"]
    }
  }
}
```

> Note
>
> `--set` is a repeatable flag. For array fields such as `tags`, repeat `--set` to provide multiple values or use the `+=` operator to append without replacing. Array literal syntax like `--set target.tags=[a,b]` is not supported.

Pattern matching syntax defined in <https://golang.org/pkg/path/#Match> is also supported:

```console
$ docker buildx bake --set foo*.args.mybuildarg=value  # overrides build arg for all targets starting with "foo"
$ docker buildx bake --set *.platform=linux/arm64      # overrides platform for all targets
$ docker buildx bake --set foo*.no-cache               # bypass caching only for targets starting with "foo"
```

Complete list of attributes that can be overridden with `--set` are:

* `args`
* `attest`
* `cache-from`
* `cache-to`
* `context`
* `contexts`
* `dockerfile`
* `entitlements`
* `labels`
* `network`
* `no-cache`
* `output`
* `platform`
* `pull`
* `secrets`
* `ssh`
* `tags`
* `target`

## [Environment variables](#environment-variables)

You can also use environment variables to override configurations.

Bake lets you use environment variables to override the value of a `variable` block. Only `variable` blocks can be overridden with environment variables. This means you need to define the variables in the bake file and then set the environment variable with the same name to override it.

The following example shows how you can define a `TAG` variable with a default value in the Bake file, and override it with an environment variable.

```hcl
variable "TAG" {
  default = "latest"
}

target "default" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["docker.io/username/webapp:${TAG}"]
}
```

```console
$ export TAG=$(git rev-parse --short HEAD)
$ docker buildx bake --print webapp
```

The `TAG` variable is overridden with the value of the environment variable, which is the short commit hash generated by `git rev-parse --short HEAD`.

```json
{
  "group": {
    "default": {
      "targets": ["webapp"]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": ["docker.io/username/webapp:985e9e9"]
    }
  }
}
```

### [Type coercion](#type-coercion)

Overriding non-string variables with environment variables is supported. Values passed as environment variables are coerced into suitable types first.

The following example defines a `PORT` variable. The `backend` target uses the `PORT` variable as-is, and the `frontend` target uses the value of `PORT` incremented by one.

```hcl
variable "PORT" {
  default = 3000
}

group "default" {
  targets = ["backend", "frontend"]
}

target "backend" {
  args = {
    PORT = PORT
  }
}

target "frontend" {
  args = {
    PORT = add(PORT, 1)
  }
}
```

Overriding `PORT` using an environment variable will first coerce the value into the expected type, an integer, before the expression in the `frontend` target runs.

```console
$ PORT=7070 docker buildx bake --print
```

```json
{
  "group": {
    "default": {
      "targets": [
        "backend",
        "frontend"
      ]
    }
  },
  "target": {
    "backend": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "PORT": "7070"
      }
    },
    "frontend": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "PORT": "7071"
      }
    }
  }
}
```

----
url: https://docs.docker.com/dhi/core-concepts/hardening/
----

# Base image hardening

***

Table of contents

***

## [What is base image hardening?](#what-is-base-image-hardening)

Base image hardening is the process of securing the foundational layers of a container image by minimizing what they include and configuring them with security-first defaults. A hardened base image removes unnecessary components, like shells, compilers, and package managers, which limits the available attack surface, making it more difficult for an attacker to gain control or escalate privileges inside the container.

Hardening also involves applying best practices like running as a non-root user, reducing writable surfaces, and ensuring consistency through immutability. While [Docker Official Images](https://docs.docker.com/docker-hub/image-library/trusted-content/#docker-official-images) and [Docker Verified Publisher Images](https://docs.docker.com/docker-hub/image-library/trusted-content/#verified-publisher-images) follow best practices for security, they may not be as hardened as Docker Hardened Images, as they are designed to support a broader range of use cases.

## [Why is it important?](#why-is-it-important)

Most containers inherit their security posture from the base image they use. If the base image includes unnecessary tools or runs with elevated privileges, every container built on top of it is exposed to those risks.

Hardening the base image:

* Reduces the attack surface by removing tools and libraries that could be exploited
* Enforces least privilege by dropping root access and restricting what the container can do
* Improves reliability and consistency by avoiding runtime changes and drift
* Aligns with secure software supply chain practices and helps meet compliance standards

Using hardened base images is a critical first step in securing the software you build and run in containers.

## [What's removed and why](#whats-removed-and-why)

Hardened images typically exclude common components that are risky or unnecessary in secure production environments:

| Removed component                                | Reason                                                                           |
| ------------------------------------------------ | -------------------------------------------------------------------------------- |
| Shells (e.g., `sh`, `bash`)                      | Prevents users or attackers from executing arbitrary commands inside containers  |
| Package managers (e.g., `apt`, `apk`)            | Disables the ability to install software post-build, reducing drift and exposure |
| Compilers and interpreters                       | Avoids introducing tools that could be used to run or inject malicious code      |
| Debugging tools (e.g., `strace`, `curl`, `wget`) | Reduces risk of exploitation or information leakage                              |
| Unused libraries or locales                      | Shrinks image size and minimizes attack vectors                                  |

## [How Docker Hardened Images apply base image hardening](#how-docker-hardened-images-apply-base-image-hardening)

Docker Hardened Images (DHIs) apply base image hardening principles by design. Each image is constructed to include only what is necessary for its specific purpose, whether that’s building applications (with `-dev` or `-sdk` tags) or running them in production.

### [Docker Hardened Image traits](#docker-hardened-image-traits)

Docker Hardened Images are built to be:

* Minimal: Only essential libraries and binaries are included
* Immutable: Images are fixed at build time—no runtime installations
* Non-root by default: Containers run as an unprivileged user unless configured otherwise
* Purpose-scoped: Different tags are available for development (`-dev`), SDK-based builds (`-sdk`), and production runtime

These characteristics help enforce consistent, secure behavior across development, testing, and production environments.

### [Docker Hardened Image compatibility considerations](#docker-hardened-image-compatibility-considerations)

Because Docker Hardened Images strip out many common tools, they may not work out of the box for all use cases. You may need to:

* Use multi-stage builds to compile code or install dependencies in a `-dev` image and copy the output into a hardened runtime image
* Replace shell scripts with equivalent entrypoint binaries or explicitly include a shell if needed
* Use [Docker Debug](/reference/cli/docker/debug/) to temporarily inspect or troubleshoot containers without altering the base image

These trade-offs are intentional and help support best practices for building secure, reproducible, and production-ready containers.

----
url: https://docs.docker.com/reference/samples/nginx/
----

# NGINX samples

| Name                                                                                                   | Description                                                                                                                        |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| [Go / NGINX / MySQL](https://github.com/docker/awesome-compose/tree/master/nginx-golang-mysql)         | A sample Go application with an Nginx proxy and a MySQL database.                                                                  |
| [Go / NGINX / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/nginx-golang-postgres) | A sample Go application with an Nginx proxy and a PostgreSQL database.                                                             |
| [NGINX / ASP.NET / MySQL](https://github.com/docker/awesome-compose/tree/master/nginx-aspnet-mysql)    | A sample Nginx reverse proxy with a C# backend using ASP.NET.                                                                      |
| [NGINX / Flask / MongoDB](https://github.com/docker/awesome-compose/tree/master/nginx-flask-mongo)     | A sample Python/Flask application with Nginx proxy and a Mongo database.                                                           |
| [NGINX / Flask / MySQL](https://github.com/docker/awesome-compose/tree/master/nginx-flask-mysql)       | A sample Python/Flask application with an Nginx proxy and a MySQL database.                                                        |
| [NGINX / Node.js / Redis](https://github.com/docker/awesome-compose/tree/master/nginx-nodejs-redis)    | A sample Node.js application with Nginx proxy and a Redis database.                                                                |
| [NGINX / Go](https://github.com/docker/awesome-compose/tree/master/nginx-golang)                       | A sample Nginx proxy with a Go backend.                                                                                            |
| [NGINX / WSGI / Flask](https://github.com/docker/awesome-compose/tree/master/nginx-wsgi-flask)         | A sample Nginx reverse proxy with a Flask backend using WSGI.                                                                      |
| [React / NGINX](https://github.com/docker/awesome-compose/tree/master/react-nginx)                     | A sample React application with Nginx.                                                                                             |
| [atsea-sample-shop-app](https://github.com/dockersamples/atsea-sample-shop-app)                        | A sample app that uses a Java Spring Boot backend connected to a database to display a fictitious art shop with a React front-end. |
| [linux\_tweet\_app](https://github.com/dockersamples/linux_tweet_app)                                  | A very simple webapp based on NGINX.                                                                                               |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/guides/testcontainers-go-getting-started/test-suites/
----

# Reuse containers with test suites

***

Table of contents

***

In the previous section, you saw how to spin up a Postgres Docker container for a single test. But often you have multiple tests in a single file, and you may want to reuse the same Postgres Docker container for all of them.

You can use the [testify suite](https://pkg.go.dev/github.com/stretchr/testify/suite) package to implement common test setup and teardown actions.

## [Extract container setup](#extract-container-setup)

First, extract the `PostgresContainer` creation logic into a separate file called `testhelpers/containers.go`:

```go
package testhelpers

import (
	"context"
	"path/filepath"
	"testing"

	"github.com/stretchr/testify/require"
	"github.com/testcontainers/testcontainers-go"
	"github.com/testcontainers/testcontainers-go/modules/postgres"
)

type PostgresContainer struct {
	*postgres.PostgresContainer
	ConnectionString string
}

func CreatePostgresContainer(t *testing.T, ctx context.Context) *PostgresContainer {
	t.Helper()

	ctr, err := postgres.Run(ctx,
		"postgres:16-alpine",
		postgres.WithInitScripts(filepath.Join("..", "testdata", "init-db.sql")),
		postgres.WithDatabase("test-db"),
		postgres.WithUsername("postgres"),
		postgres.WithPassword("postgres"),
		postgres.BasicWaitStrategies(),
	)
	testcontainers.CleanupContainer(t, ctr)
	require.NoError(t, err)

	connStr, err := ctr.ConnectionString(ctx, "sslmode=disable")
	require.NoError(t, err)

	return &PostgresContainer{
		PostgresContainer: ctr,
		ConnectionString:  connStr,
	}
}
```

In `containers.go`, `PostgresContainer` extends the testcontainers-go `PostgresContainer` to provide easy access to `ConnectionString`. The `CreatePostgresContainer()` function accepts `*testing.T` as its first parameter, calls `t.Helper()` so that test failures point to the caller, and uses `testcontainers.CleanupContainer()` to register automatic cleanup.

## [Write the test suite](#write-the-test-suite)

Create `customer/repo_suite_test.go` and implement tests for creating a customer and getting a customer by email using the testify suite package:

```go
package customer

import (
	"context"
	"testing"

	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/require"
	"github.com/stretchr/testify/suite"
	"github.com/testcontainers/testcontainers-go-demo/testhelpers"
)

type CustomerRepoTestSuite struct {
	suite.Suite
	pgContainer *testhelpers.PostgresContainer
	repository  *Repository
	ctx         context.Context
}

func (suite *CustomerRepoTestSuite) SetupSuite() {
	suite.ctx = context.Background()
	suite.pgContainer = testhelpers.CreatePostgresContainer(suite.T(), suite.ctx)

	repository, err := NewRepository(suite.ctx, suite.pgContainer.ConnectionString)
	require.NoError(suite.T(), err)
	suite.repository = repository
}

func (suite *CustomerRepoTestSuite) TestCreateCustomer() {
	t := suite.T()

	customer, err := suite.repository.CreateCustomer(suite.ctx, Customer{
		Name:  "Henry",
		Email: "henry@gmail.com",
	})
	require.NoError(t, err)
	assert.NotNil(t, customer.Id)
}

func (suite *CustomerRepoTestSuite) TestGetCustomerByEmail() {
	t := suite.T()

	customer, err := suite.repository.GetCustomerByEmail(suite.ctx, "john@gmail.com")
	require.NoError(t, err)
	assert.Equal(t, "John", customer.Name)
	assert.Equal(t, "john@gmail.com", customer.Email)
}

func TestCustomerRepoTestSuite(t *testing.T) {
	suite.Run(t, new(CustomerRepoTestSuite))
}
```

Here's what the code does:

* `CustomerRepoTestSuite` extends `suite.Suite` and includes fields shared across multiple tests.
* `SetupSuite()` runs once before all tests. It calls `CreatePostgresContainer(suite.T(), ...)` which handles cleanup registration automatically via `CleanupContainer`, so no `TearDownSuite()` is needed.
* `TestCreateCustomer()` uses `require.NoError()` for the create operation (fail immediately if it errors) and `assert.NotNil()` for the ID check.
* `TestGetCustomerByEmail()` uses `require.NoError()` then asserts on the returned values.
* `TestCustomerRepoTestSuite(t *testing.T)` runs the test suite when you execute `go test`.

> Tip
>
> For the purpose of this guide, the tests don't reset data in the database. In practice, it's a good idea to reset the database to a known state before running each test.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-go-getting-started/run-tests/)

----
url: https://docs.docker.com/reference/cli/docker/compose/push/
----

# docker compose push

***

| Description | Push service images                          |
| ----------- | -------------------------------------------- |
| Usage       | `docker compose push [OPTIONS] [SERVICE...]` |

## [Description](#description)

Pushes images for services to their respective registry/repository.

The following assumptions are made:

* You are pushing an image you have built locally
* You have access to the build key

Examples

```yaml
services:
  service1:
    build: .
    image: localhost:5000/yourimage  ## goes to local registry

  service2:
    build: .
    image: your-dockerid/yourimage  ## goes to your repository on Docker Hub
```

## [Options](#options)

| Option                   | Default | Description                                            |
| ------------------------ | ------- | ------------------------------------------------------ |
| `--ignore-push-failures` |         | Push what it can and ignores images with push failures |
| `--include-deps`         |         | Also push images of services declared as dependencies  |
| `-q, --quiet`            |         | Push without printing progress information             |

----
url: https://docs.docker.com/reference/cli/docker/manifest/annotate/
----

# docker manifest annotate

***

| Description | Add additional information to a local image manifest        |
| ----------- | ----------------------------------------------------------- |
| Usage       | `docker manifest annotate [OPTIONS] MANIFEST_LIST MANIFEST` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Add additional information to a local image manifest

## [Options](#options)

| Option          | Default | Description                  |
| --------------- | ------- | ---------------------------- |
| `--arch`        |         | Set architecture             |
| `--os`          |         | Set operating system         |
| `--os-features` |         | Set operating system feature |
| `--os-version`  |         | Set operating system version |
| `--variant`     |         | Set architecture variant     |

----
url: https://docs.docker.com/get-started/get-docker/
----

# Get Docker

***

***

Docker is an open platform for developing, shipping, and running applications.

Docker allows you to separate your applications from your infrastructure so you can deliver software quickly. With Docker, you can manage your infrastructure in the same ways you manage your applications.

By taking advantage of Docker’s methodologies for shipping, testing, and deploying code quickly, you can significantly reduce the delay between writing code and running it in production.

You can download and install Docker on multiple platforms. Refer to the following section and choose the best installation path for you.

> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250 employees OR more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsGetDocker).

### [Docker Desktop for Mac](/desktop/setup/install/mac-install/)

[A native application using the macOS sandbox security model that delivers all Docker tools to your Mac.](/desktop/setup/install/mac-install/)

### [Docker Desktop for Windows](/desktop/setup/install/windows-install/)

[A native Windows application that delivers all Docker tools to your Windows computer.](/desktop/setup/install/windows-install/)

### [Docker Desktop for Linux](/desktop/setup/install/linux/)

[A native Linux application that delivers all Docker tools to your Linux computer.](/desktop/setup/install/linux/)

> Note
>
> If you're looking for information on how to install Docker Engine, see [Docker Engine installation overview](/engine/install/).

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/
----

# Hardened Docker Desktop

***

Table of contents

***

Subscription: Business

For: Administrators

Hardened Docker Desktop provides a collection of security features designed to strengthen developer environments without compromising productivity or developer experience.

With Hardened Docker Desktop, you can enforce strict security policies that prevent developers and containers from bypassing organizational controls. You can also enhance container isolation to protect against security threats like malicious payloads that might breach the Docker Desktop Linux VM or underlying host system.

## [Who should use Hardened Docker Desktop?](#who-should-use-hardened-docker-desktop)

Hardened Docker Desktop is ideal for security-focused organizations that:

* Don't provide root or administrator access to developers' machines
* Want centralized control over Docker Desktop configurations
* Must meet specific compliance requirements

## [How Hardened Docker Desktop works](#how-hardened-docker-desktop-works)

Hardened Docker Desktop features work independently and together to create a defense-in-depth security strategy. They protect developer workstations against attacks across multiple layers, including Docker Desktop configuration, container image management, and container runtime security:

* Registry Access Management and Image Access Management prevent access to unauthorized container registries and image types, reducing exposure to malicious payloads
* Enhanced Container Isolation runs containers without root privileges inside a Linux user namespace, limiting the impact of malicious containers
* Air-gapped containers let you configure network restrictions for containers, preventing malicious containers from accessing your organization's internal network resources
* Namespace access controls whether organization members can push content to their personal Docker Hub namespaces, preventing accidental publication of images outside approved locations
* Settings Management locks down Docker Desktop configurations to enforce company policies and prevent developers from introducing insecure settings, whether intentionally or accidentally

## [Next steps](#next-steps)

Explore Hardened Docker Desktop features to understand how they can strengthen your organization's security posture:

### [Namespace access](/enterprise/security/hardened-desktop/namespace-access/)

[Control whether organization members can push content to their personal namespaces.](/enterprise/security/hardened-desktop/namespace-access/)

----
url: https://docs.docker.com/engine/release-notes/18.09/
----

# Docker Engine 18.09 release notes

***

Table of contents

***

> **Note:**
>
> With this release, the daemon, client and container runtime are now all shipped in separate packages. When updating, you need to update all packages at the same time to get the latest patch releases for each. For example, on Ubuntu:
>
> ```console
> $ sudo apt-get install docker-ce docker-ce-cli containerd.io
> ```
>
> See the [installation instructions](https://docs.docker.com/engine/install/) for the corresponding Linux distribution for details.

## [18.09.9](#18099)

2019-09-03

### [Client](#client)

* Fix Windows absolute path detection on non-Windows. [docker/cli#1990](https://github.com/docker/cli/pull/1990)
* Fix Docker refusing to load key from delegation.key on Windows. [docker/cli#1968](https://github.com/docker/cli/pull/1968)
* Completion scripts updates for bash and zsh.

### [Logging](#logging)

* Fix for reading journald logs. [moby/moby#37819](https://github.com/moby/moby/pull/37819) [moby/moby#38859](https://github.com/moby/moby/pull/38859)

### [Networking](#networking)

* Prevent panic on network attached to a container with disabled networking. [moby/moby#39589](https://github.com/moby/moby/pull/39589)
* Fix service port for an application becomes unavailable randomly. [docker/libnetwork#2069](https://github.com/docker/libnetwork/pull/2069)
* Fix cleaning up `--config-only` networks `--config-from` networkshave ungracefully exited. [docker/libnetwork#2373](https://github.com/docker/libnetwork/pull/2373)

### [Runtime](#runtime)

* Update to Go 1.11.13.
* Fix a potential engine panic when using XFS disk quota for containers. [moby/moby#39644](https://github.com/moby/moby/pull/39644)

### [Swarm](#swarm)

* Fix "grpc: received message larger than max" errors. [moby/moby#39306](https://github.com/moby/moby/pull/39306)
* Fix an issue where nodes several tasks could not be removed. [docker/swarmkit#2867](https://github.com/docker/swarmkit/pull/2867)

## [18.09.8](#18098)

2019-07-17

### [Runtime](#runtime-1)

* Masked the secrets updated to the log files when running Docker Engine in debug mode. [CVE-2019-13509](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-13509): If a Docker engine is running in debug mode, and `docker stack deploy` is used to redeploy a stack which includes non-external secrets, the logs will contain the secret.

### [Client](#client-1)

* Fixed rollback config type interpolation for `parallelism` and `max_failure_ratio` fields.

### [Known Issue](#known-issue)

* There are important changes to the upgrade process that, if not correctly followed, can have an impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before 18.09 to version 18.09 or later.

## [18.09.7](#18097)

2019-06-27

### [Builder](#builder)

* Fixed a panic error when building dockerfiles that contain only comments. [moby/moby#38487](https://github.com/moby/moby/pull/38487)
* Added a workaround for GCR authentication issue. [moby/moby#38246](https://github.com/moby/moby/pull/38246)
* Builder-next: Fixed a bug in the GCR token cache implementation workaround. [moby/moby#39183](https://github.com/moby/moby/pull/39183)

### [Networking](#networking-1)

* Fixed an error where `--network-rm` would fail to remove a network. [moby/moby#39174](https://github.com/moby/moby/pull/39174)

### [Runtime](#runtime-2)

* Added performance optimizations in aufs and layer store that helps in massively parallel container creation and removal. [moby/moby#39107](https://github.com/moby/moby/pull/39107), [moby/moby#39135](https://github.com/moby/moby/pull/39135)
* Updated containerd to version 1.2.6. [moby/moby#39016](https://github.com/moby/moby/pull/39016)
* Fixed [CVE-2018-15664](https://nvd.nist.gov/vuln/detail/CVE-2018-15664) symlink-exchange attack with directory traversal. [moby/moby#39357](https://github.com/moby/moby/pull/39357)
* Windows: fixed support for `docker service create --limit-cpu`. [moby/moby#39190](https://github.com/moby/moby/pull/39190)
* daemon: fixed a mirrors validation issue. [moby/moby#38991](https://github.com/moby/moby/pull/38991)
* Docker no longer supports sorting UID and GID ranges in ID maps. [moby/moby#39288](https://github.com/moby/moby/pull/39288)

### [Logging](#logging-1)

* Added a fix that now allows large log lines for logger plugins. [moby/moby#39038](https://github.com/moby/moby/pull/39038)

### [Known Issue](#known-issue-1)

* There are important changes to the upgrade process that, if not correctly followed, can have an impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before 18.09 to version 18.09 or later.

## [18.09.6](#18096)

2019-05-06

### [Builder](#builder-1)

* Fixed `COPY` and `ADD` with multiple `<src>` to not invalidate cache if `DOCKER_BUILDKIT=1`.[moby/moby#38964](https://github.com/moby/moby/issues/38964)

### [Networking](#networking-2)

* Cleaned up the cluster provider when the agent is closed. [docker/libnetwork#2354](https://github.com/docker/libnetwork/pull/2354)
* Windows: Now selects a random host port if the user does not specify a host port. [docker/libnetwork#2369](https://github.com/docker/libnetwork/pull/2369)

### [Known Issues](#known-issues)

* There are important changes to the upgrade process that, if not correctly followed, can have an impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before 18.09 to version 18.09 or later.

## [18.09.5](#18095)

2019-04-11

### [Builder](#builder-2)

* Fixed `DOCKER_BUILDKIT=1 docker build --squash ..` [docker/engine#176](https://github.com/docker/engine/pull/176)

### [Client](#client-2)

* Fixed tty initial size error. [docker/cli#1775](https://github.com/docker/cli/pull/1775)
* Fixed dial-stdio goroutine leakage. [docker/cli#1795](https://github.com/docker/cli/pull/1795)
* Fixed the stack informer's selector used to track deployment. [docker/cli#1794](https://github.com/docker/cli/pull/1794)

### [Networking](#networking-3)

* Fixed `network=host` using wrong `resolv.conf` with `systemd-resolved`. [docker/engine#180](https://github.com/docker/engine/pull/180)
* Fixed Windows ARP entries getting corrupted randomly under load. [docker/engine#192](https://github.com/docker/engine/pull/192)

### [Runtime](#runtime-3)

* Now showing stopped containers with restart policy as `Restarting`. [docker/engine#181](https://github.com/docker/engine/pull/181)
* Now using original process spec for execs. [docker/engine#178](https://github.com/docker/engine/pull/178)

### [Swarm Mode](#swarm-mode)

* Fixed leaking task resources when nodes are deleted. [docker/engine#185](https://github.com/docker/engine/pull/185)

### [Known Issues](#known-issues-1)

* There are important changes to the upgrade process that, if not correctly followed, can have an impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before 18.09 to version 18.09 or later.

## [18.09.4](#18094)

2019-03-28

### [Builder](#builder-3)

* Fixed [CVE-2019-13139](https://nvd.nist.gov/vuln/detail/CVE-2019-13139) by adding validation for `git ref` to avoid misinterpretation as a flag. [moby/moby#38944](https://github.com/moby/moby/pull/38944)

### [Runtime](#runtime-4)

* Fixed `docker cp` error for filenames greater than 100 characters. [moby/moby#38634](https://github.com/moby/moby/pull/38634)
* Fixed `layer/layer_store` to ensure `NewInputTarStream` resources are released. [moby/moby#38413](https://github.com/moby/moby/pull/38413)
* Increased GRPC limit for `GetConfigs`. [moby/moby#38800](https://github.com/moby/moby/pull/38800)
* Updated `containerd` 1.2.5. [docker/engine#173](https://github.com/docker/engine/pull/173)

### [Swarm Mode](#swarm-mode-1)

* Fixed nil pointer exception when joining node to swarm. [moby/moby#38618](https://github.com/moby/moby/issues/38618)
* Fixed issue for swarm nodes not being able to join as masters if http proxy is set. \[moby/moby#36951]

### [Known Issues](#known-issues-2)

* There are important changes to the upgrade process that, if not correctly followed, can have impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before 18.09 to version 18.09 or later.

## [18.09.3](#18093)

2019-02-28

### [Networking fixes](#networking-fixes)

* Windows: now avoids regeneration of network IDs to prevent broken references to networks. [docker/engine#149](https://github.com/docker/engine/pull/149)
* Windows: Fixed an issue to address `- restart always` flag on standalone containers not working when specifying a network. (docker/escalation#1037)
* Fixed an issue to address the IPAM state from networkdb if the manager is not attached to the overlay network. (docker/escalation#1049)

### [Runtime fixes and updates](#runtime-fixes-and-updates)

* Updated to Go version 1.10.8.
* Modified names in the container name generator. [docker/engine#159](https://github.com/docker/engine/pull/159)
* When copying an existing folder, xattr set errors when the target filesystem doesn't support xattr are now ignored. [docker/engine#135](https://github.com/docker/engine/pull/135)
* Graphdriver: fixed "device" mode not being detected if "character-device" bit is set. [docker/engine#160](https://github.com/docker/engine/pull/160)
* Fixed nil pointer dereference on failure to connect to containerd. [docker/engine#162](https://github.com/docker/engine/pull/162)
* Deleted stale containerd object on start failure. [docker/engine#154](https://github.com/docker/engine/pull/154)

### [Known Issues](#known-issues-3)

* There are important changes to the upgrade process that, if not correctly followed, can have impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before 18.09 to version 18.09 or greater.

## [18.09.2](#18092)

2019-02-11

### [Security fixes](#security-fixes)

* Update `runc` to address a critical vulnerability that allows specially-crafted containers to gain administrative privileges on the host. [CVE-2019-5736](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-5736)
* Ubuntu 14.04 customers using a 3.13 kernel will need to upgrade to a supported Ubuntu 4.x kernel

For additional information, [refer to the Docker blog post](https://blog.docker.com/2019/02/docker-security-update-cve-2018-5736-and-container-security-best-practices/).

### [Known Issues](#known-issues-4)

* There are important changes to the upgrade process that, if not correctly followed, can have impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before 18.09 to version 18.09 or greater.

## [18.09.1](#18091)

2019-01-09

#### [Important notes about this release](#important-notes-about-this-release)

In Docker versions prior to 18.09, containerd was managed by the Docker engine daemon. In Docker Engine 18.09, containerd is managed by systemd. Since containerd is managed by systemd, any custom configuration to the `docker.service` systemd configuration which changes mount settings (for example, `MountFlags=slave`) breaks interactions between the Docker Engine daemon and containerd, and you will not be able to start containers.

Run the following command to get the current value of the `MountFlags` property for the `docker.service`:

```console
$ sudo systemctl show --property=MountFlags docker.service
MountFlags=
```

Update your configuration if this command prints a non-empty value for `MountFlags`, and restart the docker service.

### [Security fixes](#security-fixes-1)

* Upgraded Go language to 1.10.6 to resolve [CVE-2018-16873](https://nvd.nist.gov/vuln/detail/CVE-2018-16873), [CVE-2018-16874](https://nvd.nist.gov/vuln/detail/CVE-2018-16874), and [CVE-2018-16875](https://nvd.nist.gov/vuln/detail/CVE-2018-16875).
* Fixed authz plugin for 0-length content and path validation.
* Added `/proc/asound` to masked paths [docker/engine#126](https://github.com/docker/engine/pull/126)

### [Improvements](#improvements)

* Updated to BuildKit 0.3.3 [docker/engine#122](https://github.com/docker/engine/pull/122)
* Updated to containerd 1.2.2 [docker/engine#144](https://github.com/docker/engine/pull/144)
* Provided additional warnings for use of deprecated legacy overlay and devicemapper storage drivers [docker/engine#85](https://github.com/docker/engine/pull/85)
* prune: perform image pruning before build cache pruning [docker/cli#1532](https://github.com/docker/cli/pull/1532)
* Added bash completion for experimental CLI commands (manifest) [docker/cli#1542](https://github.com/docker/cli/pull/1542)
* Windows: allow process isolation on Windows 10 [docker/engine#81](https://github.com/docker/engine/pull/81)

### [Fixes](#fixes)

* Disable kmem accounting in runc on RHEL/CentOS (docker/escalation#614, docker/escalation#692) [docker/engine#121](https://github.com/docker/engine/pull/121)
* Fixed inefficient networking configuration [docker/engine#123](https://github.com/docker/engine/pull/123)
* Fixed docker system prune doesn't accept until filter [docker/engine#122](https://github.com/docker/engine/pull/122)
* Avoid unset credentials in `containerd` [docker/engine#122](https://github.com/docker/engine/pull/122)
* Fixed iptables compatibility on Debian [docker/engine#107](https://github.com/docker/engine/pull/107)
* Fixed setting default schema to tcp for docker host [docker/cli#1454](https://github.com/docker/cli/pull/1454)
* Fixed bash completion for `service update --force` [docker/cli#1526](https://github.com/docker/cli/pull/1526)
* Windows: DetachVhd attempt in cleanup [docker/engine#113](https://github.com/docker/engine/pull/113)
* API: properly handle invalid JSON to return a 400 status [docker/engine#110](https://github.com/docker/engine/pull/110)
* API: ignore default address-pools on API < 1.39 [docker/engine#118](https://github.com/docker/engine/pull/118)
* API: add missing default address pool fields to swagger [docker/engine#119](https://github.com/docker/engine/pull/119)
* awslogs: account for UTF-8 normalization in limits [docker/engine#112](https://github.com/docker/engine/pull/112)
* Prohibit reading more than 1MB in HTTP error responses [docker/engine#114](https://github.com/docker/engine/pull/114)
* apparmor: allow receiving of signals from `docker kill` [docker/engine#116](https://github.com/docker/engine/pull/116)
* overlay2: use index=off if possible (fix EBUSY on mount) [docker/engine#84](https://github.com/docker/engine/pull/84)

### [Packaging](#packaging)

* Add docker.socket requirement for docker.service. [docker/docker-ce-packaging#276](https://github.com/docker/docker-ce-packaging/pull/276)
* Add socket activation for RHEL-based distributions. [docker/docker-ce-packaging#274](https://github.com/docker/docker-ce-packaging/pull/274)
* Add libseccomp requirement for RPM packages. [docker/docker-ce-packaging#266](https://github.com/docker/docker-ce-packaging/pull/266)

### [Known Issues](#known-issues-5)

* When upgrading from 18.09.0 to 18.09.1, `containerd` is not upgraded to the correct version on Ubuntu.
* There are important changes to the upgrade process that, if not correctly followed, can have impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before 18.09 to version 18.09 or greater.

## [18.09.0](#18090)

2018-11-08

### [Important notes about this release](#important-notes-about-this-release-1)

In Docker versions prior to 18.09, containerd was managed by the Docker engine daemon. In Docker Engine 18.09, containerd is managed by systemd. Since containerd is managed by systemd, any custom configuration to the `docker.service` systemd configuration which changes mount settings (for example, `MountFlags=slave`) breaks interactions between the Docker Engine daemon and containerd, and you will not be able to start containers.

Run the following command to get the current value of the `MountFlags` property for the `docker.service`:

```console
$ sudo systemctl show --property=MountFlags docker.service
MountFlags=
```

Update your configuration if this command prints a non-empty value for `MountFlags`, and restart the docker service.

### [New features](#new-features)

* Updated API version to 1.39 [moby/moby#37640](https://github.com/moby/moby/pull/37640)
* Added support for remote connections using SSH [docker/cli#1014](https://github.com/docker/cli/pull/1014)
* Builder: added prune options to the API [moby/moby#37651](https://github.com/moby/moby/pull/37651)
* Added "Warnings" to `/info` endpoint, and move detection to the daemon [moby/moby#37502](https://github.com/moby/moby/pull/37502)
* Allows BuildKit builds to run without experimental mode enabled. Buildkit can now be configured with an option in daemon.json [moby/moby#37593](https://github.com/moby/moby/pull/37593) [moby/moby#37686](https://github.com/moby/moby/pull/37686) [moby/moby#37692](https://github.com/moby/moby/pull/37692) [docker/cli#1303](https://github.com/docker/cli/pull/1303) [docker/cli#1275](https://github.com/docker/cli/pull/1275)
* Added support for build-time secrets using a `--secret` flag when using BuildKit [docker/cli#1288](https://github.com/docker/cli/pull/1288)
* Added SSH agent socket forwarder (`docker build --ssh $SSHMOUNTID=$SSH_AUTH_SOCK`) when using BuildKit [docker/cli#1438](https://github.com/docker/cli/pull/1438) / [docker/cli#1419](https://github.com/docker/cli/pull/1419)
* Added `--chown` flag support for `ADD` and `COPY` commands on Windows [moby/moby#35521](https://github.com/moby/moby/pull/35521)
* Added `builder prune` subcommand to prune BuildKit build cache [docker/cli#1295](https://github.com/docker/cli/pull/1295) [docker/cli#1334](https://github.com/docker/cli/pull/1334)
* BuildKit: Adds configurable garbage collection policy for the BuildKit build cache [docker/engine#59](https://github.com/docker/engine/pull/59) / [moby/moby#37846](https://github.com/moby/moby/pull/37846)
* BuildKit: Adds support for `docker build --pull ...` when using BuildKit [moby/moby#37613](https://github.com/moby/moby/pull/37613)
* BuildKit: Adds support or "registry-mirrors" and "insecure-registries" when using BuildKit [docker/engine#59](https://github.com/docker/engine/pull/59) / [moby/moby#37852](https://github.com/moby/moby/pull/37852)
* BuildKit: Enables net modes and bridge. [moby/moby#37620](https://github.com/moby/moby/pull/37620)
* Added `docker engine` subcommand to manage the lifecycle of a Docker Engine running as a privileged container on top of containerd, and to allow upgrades to Docker Engine Enterprise [docker/cli#1260](https://github.com/docker/cli/pull/1260)
* Exposed product license in `docker info` output [docker/cli#1313](https://github.com/docker/cli/pull/1313)
* Showed warnings produced by daemon in `docker info` output [docker/cli#1225](https://github.com/docker/cli/pull/1225)
* Added "local" log driver [moby/moby#37092](https://github.com/moby/moby/pull/37092)
* Amazon CloudWatch: adds `awslogs-endpoint` logging option [moby/moby#37374](https://github.com/moby/moby/pull/37374)
* Added support for global default address pools [moby/moby#37558](https://github.com/moby/moby/pull/37558) [docker/cli#1233](https://github.com/docker/cli/pull/1233)
* Configured containerd log-level to be the same as dockerd [moby/moby#37419](https://github.com/moby/moby/pull/37419)
* Added configuration option for cri-containerd [moby/moby#37519](https://github.com/moby/moby/pull/37519)
* Updates containerd client to v1.2.0-rc.1 [moby/moby#37664](https://github.com/moby/moby/pull/37664), [docker/engine#75](https://github.com/docker/engine/pull/75) / [moby/moby#37710](https://github.com/moby/moby/pull/37710)
* Added support for global default address pools [moby/moby#37558](https://github.com/moby/moby/pull/37558) [docker/cli#1233](https://github.com/docker/cli/pull/1233)
* Moved the `POST /session` endpoint out of experimental. [moby/moby#40028](https://github.com/moby/moby/pull/40028)

### [Improvements](#improvements-1)

* Does not return "`<unknown>`" in /info response [moby/moby#37472](https://github.com/moby/moby/pull/37472)
* BuildKit: Changes `--console=[auto,false,true]` to `--progress=[auto,plain,tty]` [docker/cli#1276](https://github.com/docker/cli/pull/1276)
* BuildKit: Sets BuildKit's ExportedProduct variable to show useful errors in the future. [moby/moby#37439](https://github.com/moby/moby/pull/37439)
* Hides `--data-path-addr` flags when connected to a daemon that doesn't support this option [docker/docker/cli#1240](https://github.com/docker/cli/pull/1240)
* Only shows buildkit-specific flags if BuildKit is enabled [docker/cli#1438](https://github.com/docker/cli/pull/1438) / [docker/cli#1427](https://github.com/docker/cli/pull/1427)
* Improves version output alignment [docker/cli#1204](https://github.com/docker/cli/pull/1204)
* Sorts plugin names and networks in a natural order [docker/cli#1166](https://github.com/docker/cli/pull/1166), [docker/cli#1266](https://github.com/docker/cli/pull/1266)
* Updates bash and zsh [completion scripts](https://github.com/docker/cli/issues?q=label%3Aarea%2Fcompletion+milestone%3A18.09.0+is%3Aclosed)
* Passes log-level to containerd. [moby/moby#37419](https://github.com/moby/moby/pull/37419)
* Uses direct server return (DSR) in east-west overlay load balancing [docker/engine#93](https://github.com/docker/engine/pull/93) / [docker/libnetwork#2270](https://github.com/docker/libnetwork/pull/2270)
* Builder: temporarily disables bridge networking when using buildkit. [moby/moby#37691](https://github.com/moby/moby/pull/37691)
* Blocks task starting until node attachments are ready [moby/moby#37604](https://github.com/moby/moby/pull/37604)
* Propagates the provided external CA certificate to the external CA object in swarm. [docker/cli#1178](https://github.com/docker/cli/pull/1178)
* Removes Ubuntu 14.04 "Trusty Tahr" as a supported platform [docker-ce-packaging#255](https://github.com/docker/docker-ce-packaging/pull/255) / [docker-ce-packaging#254](https://github.com/docker/docker-ce-packaging/pull/254)
* Removes Debian 8 "Jessie" as a supported platform [docker-ce-packaging#255](https://github.com/docker/docker-ce-packaging/pull/255) / [docker-ce-packaging#254](https://github.com/docker/docker-ce-packaging/pull/254)
* Removes 'docker-' prefix for containerd and runc binaries [docker/engine#61](https://github.com/docker/engine/pull/61) / [moby/moby#37907](https://github.com/moby/moby/pull/37907), [docker-ce-packaging#241](https://github.com/docker/docker-ce-packaging/pull/241)
* Splits "engine", "cli", and "containerd" to separate packages, and run containerd as a separate systemd service [docker-ce-packaging#131](https://github.com/docker/docker-ce-packaging/pull/131), [docker-ce-packaging#158](https://github.com/docker/docker-ce-packaging/pull/158)
* Builds binaries with Go 1.10.4 [docker-ce-packaging#181](https://github.com/docker/docker-ce-packaging/pull/181)
* Removes `-ce` suffix from version string [docker-ce-packaging#206](https://github.com/docker/docker-ce-packaging/pull/206)

### [Fixes](#fixes-1)

* BuildKit: Do not cancel buildkit status request. [moby/moby#37597](https://github.com/moby/moby/pull/37597)
* Fixes no error is shown if build args are missing during docker build [moby/moby#37396](https://github.com/moby/moby/pull/37396)
* Fixes error "unexpected EOF" when adding an 8GB file [moby/moby#37771](https://github.com/moby/moby/pull/37771)
* LCOW: Ensures platform is populated on `COPY`/`ADD`. [moby/moby#37563](https://github.com/moby/moby/pull/37563)
* Fixes mapping a range of host ports to a single container port [docker/cli#1102](https://github.com/docker/cli/pull/1102)
* Fixes `trust inspect` typo: "`AdminstrativeKeys`" [docker/cli#1300](https://github.com/docker/cli/pull/1300)
* Fixes environment file parsing for imports of absent variables and those with no name. [docker/cli#1019](https://github.com/docker/cli/pull/1019)
* Fixes a potential "out of memory exception" when running `docker image prune` with a large list of dangling images [docker/cli#1432](https://github.com/docker/cli/pull/1432) / [docker/cli#1423](https://github.com/docker/cli/pull/1423)
* Fixes pipe handling in ConEmu and ConsoleZ on Windows [moby/moby#37600](https://github.com/moby/moby/pull/37600)
* Fixes long startup on windows, with non-hns governed Hyper-V networks [docker/engine#67](https://github.com/docker/engine/pull/67) / [moby/moby#37774](https://github.com/moby/moby/pull/37774)
* Fixes daemon won't start when "runtimes" option is defined both in config file and cli [docker/engine#57](https://github.com/docker/engine/pull/57) / [moby/moby#37871](https://github.com/moby/moby/pull/37871)
* Loosens permissions on `/etc/docker` directory to prevent "permission denied" errors when using `docker manifest inspect` [docker/engine#56](https://github.com/docker/engine/pull/56) / [moby/moby#37847](https://github.com/moby/moby/pull/37847)
* Fixes denial of service with large numbers in `cpuset-cpus` and `cpuset-mems` [docker/engine#70](https://github.com/docker/engine/pull/70) / [moby/moby#37967](https://github.com/moby/moby/pull/37967)
* LCOW: Add `--platform` to `docker import` [docker/cli#1375](https://github.com/docker/cli/pull/1375) / [docker/cli#1371](https://github.com/docker/cli/pull/1371)
* LCOW: Add LinuxMetadata support by default on Windows [moby/moby#37514](https://github.com/moby/moby/pull/37514)
* LCOW: Mount to short container paths to avoid command-line length limit [moby/moby#37659](https://github.com/moby/moby/pull/37659)
* LCOW: Fix builder using wrong cache layer [moby/moby#37356](https://github.com/moby/moby/pull/37356)
* Fixes json-log file descriptors leaking when using `--follow` [docker/engine#48](https://github.com/docker/engine/pull/48) [moby/moby#37576](https://github.com/moby/moby/pull/37576) [moby/moby#37734](https://github.com/moby/moby/pull/37734)
* Fixes a possible deadlock on closing the watcher on kqueue [moby/moby#37392](https://github.com/moby/moby/pull/37392)
* Uses poller based watcher to work around the file caching issue in Windows [moby/moby#37412](https://github.com/moby/moby/pull/37412)
* Handles systemd-resolved case by providing appropriate resolv.conf to networking layer [moby/moby#37485](https://github.com/moby/moby/pull/37485)
* Removes support for TLS < 1.2 [moby/moby#37660](https://github.com/moby/moby/pull/37660)
* Seccomp: Whitelist syscalls linked to `CAP_SYS_NICE` in default seccomp profile [moby/moby#37242](https://github.com/moby/moby/pull/37242)
* Seccomp: move the syslog syscall to be gated by `CAP_SYS_ADMIN` or `CAP_SYSLOG` [docker/engine#64](https://github.com/docker/engine/pull/64) / [moby/moby#37929](https://github.com/moby/moby/pull/37929)
* SELinux: Fix relabeling of local volumes specified via Mounts API on selinux-enabled systems [moby/moby#37739](https://github.com/moby/moby/pull/37739)
* Adds warning if REST API is accessible through an insecure connection [moby/moby#37684](https://github.com/moby/moby/pull/37684)
* Masks proxy credentials from URL when displayed in system info [docker/engine#72](https://github.com/docker/engine/pull/72) / [moby/moby#37934](https://github.com/moby/moby/pull/37934)
* Fixes mount propagation for btrfs [docker/engine#86](https://github.com/docker/engine/pull/86) / [moby/moby#38026](https://github.com/moby/moby/pull/38026)
* Fixes nil pointer dereference in node allocation [docker/engine#94](https://github.com/docker/engine/pull/94) / [docker/swarmkit#2764](https://github.com/docker/swarmkit/pull/2764)

### [Known Issues](#known-issues-6)

* There are important changes to the upgrade process that, if not correctly followed, can have impact on the availability of applications running on the Swarm during upgrades. These constraints impact any upgrades coming from any version before 18.09 to version 18.09 or greater.

* With <https://github.com/boot2docker/boot2docker/releases/download/v18.09.0/boot2docker.iso>, connection is being refused from a node on the virtual machine. Any publishing of swarm ports in virtualbox-created docker-machine VM's will not respond. This is occurring on macOS and Windows 10, using docker-machine version 0.15 and 0.16.

  The following `docker run` command works, allowing access from host browser:

  `docker run -d -p 4000:80 nginx`

  However, the following `docker service` command fails, resulting in curl/chrome unable to connect (connection refused):

  `docker service create -p 5000:80 nginx`

  This issue is not apparent when provisioning 18.09.0 cloud VM's using docker-machine.

  Workarounds:

  * Use cloud VM's that don't rely on boot2docker.
  * `docker run` is unaffected.
  * For Swarm, set VIRTUALBOX\_BOOT2DOCKER\_URL=https\://github.com/boot2docker/boot2docker/releases/download/v18.06.1-ce/boot2docker.iso.

  This issue is resolved in 18.09.1.

### [Deprecation Notices](#deprecation-notices)

* Docker has deprecated support for Device Mapper as a storage driver. It will continue to be supported at this time, but support will be removed in a future release.

  The [Overlay2 storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/) is now the default for Docker Engine implementations.

For more information on the list of deprecated flags and APIs, have a look at the [deprecation information](/engine/deprecated/) where you can find the target removal dates.

### [End of Life Notification](#end-of-life-notification)

In this release, Docker has also removed support for TLS < 1.2 [moby/moby#37660](https://github.com/moby/moby/pull/37660), Ubuntu 14.04 "Trusty Tahr" [docker-ce-packaging#255](https://github.com/docker/docker-ce-packaging/pull/255) / [docker-ce-packaging#254](https://github.com/docker/docker-ce-packaging/pull/254), and Debian 8 "Jessie" [docker-ce-packaging#255](https://github.com/docker/docker-ce-packaging/pull/255) / [docker-ce-packaging#254](https://github.com/docker/docker-ce-packaging/pull/254).

----
url: https://docs.docker.com/reference/cli/docker/node/update/
----

# docker node update

***

| Description | Update a node                       |
| ----------- | ----------------------------------- |
| Usage       | `docker node update [OPTIONS] NODE` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Update metadata about a node, such as its availability, labels, or roles.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                      | Default | Description                                           |
| --------------------------- | ------- | ----------------------------------------------------- |
| `--availability`            |         | Availability of the node (`active`, `pause`, `drain`) |
| [`--label-add`](#label-add) |         | Add or update a node label (`key=value`)              |
| `--label-rm`                |         | Remove a node label if exists                         |
| `--role`                    |         | Role of the node (`worker`, `manager`)                |

## [Examples](#examples)

### [Add label metadata to a node (--label-add)](#label-add)

Add metadata to a swarm node using node labels. You can specify a node label as a key with an empty value:

```bash
$ docker node update --label-add foo worker1
```

To add multiple labels to a node, pass the `--label-add` flag for each label:

```console
$ docker node update --label-add foo --label-add bar worker1
```

When you [create a service](/reference/cli/docker/service/create/), you can use node labels as a constraint. A constraint limits the nodes where the scheduler deploys tasks for a service.

For example, to add a `type` label to identify nodes where the scheduler should deploy message queue service tasks:

```bash
$ docker node update --label-add type=queue worker1
```

The labels you set for nodes using `docker node update` apply only to the node entity within the swarm. Do not confuse them with the docker daemon labels for [dockerd](/reference/cli/dockerd/).

For more information about labels, refer to [apply custom metadata](/engine/userguide/labels-custom-metadata/).

----
url: https://docs.docker.com/compose/how-tos/profiles/
----

# Using profiles with Compose

***

Table of contents

***

Profiles help you adjust your Compose application for different environments or use cases by selectively activating services. Services can be assigned to one or more profiles; unassigned services start/stop by default, while assigned ones only start/stop when their profile is active. This setup means specific services, like those for debugging or development, to be included in a single `compose.yml` file and activated only as needed.

## [Assigning profiles to services](#assigning-profiles-to-services)

Services are associated with profiles through the [`profiles` attribute](https://docs.docker.com/reference/compose-file/services/#profiles) which takes an array of profile names:

```yaml
services:
  frontend:
    image: frontend
    profiles: [frontend]

  phpmyadmin:
    image: phpmyadmin
    depends_on: [db]
    profiles: [debug]

  backend:
    image: backend

  db:
    image: mysql
```

Here the services `frontend` and `phpmyadmin` are assigned to the profiles `frontend` and `debug` respectively and as such are only started when their respective profiles are enabled.

Services without a `profiles` attribute are always enabled. In this case running `docker compose up` would only start `backend` and `db`.

Valid profiles names follow the regex format of `[a-zA-Z0-9][a-zA-Z0-9_.-]+`.

> Tip
>
> The core services of your application shouldn't be assigned `profiles` so they are always enabled and automatically started.

## [Start specific profiles](#start-specific-profiles)

To start a specific profile supply the `--profile` [command-line option](/reference/cli/docker/compose/) or use the [`COMPOSE_PROFILES` environment variable](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_profiles):

```console
$ docker compose --profile debug up
```

```console
$ COMPOSE_PROFILES=debug docker compose up
```

Both commands start the services with the `debug` profile enabled. In the previous `compose.yaml` file, this starts the services `db`, `backend` and `phpmyadmin`.

### [Start multiple profiles](#start-multiple-profiles)

You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` will be enabled.

Multiple profiles can be specified by passing multiple `--profile` flags or a comma-separated list for the `COMPOSE_PROFILES` environment variable:

```console
$ docker compose --profile frontend --profile debug up
```

```console
$ COMPOSE_PROFILES=frontend,debug docker compose up
```

If you want to enable all profiles at the same time, you can run `docker compose --profile "*"`.

## [Auto-starting profiles and dependency resolution](#auto-starting-profiles-and-dependency-resolution)

When you explicitly target a service on the command line that has one or more profiles assigned, you do not need to enable the profile manually as Compose runs that service regardless of whether its profile is activated. This is useful for running one-off services or debugging tools.

Only the targeted service (and any of its declared dependencies via `depends_on`) is started. Other services that share the same profile will not be started unless:

* They are also explicitly targeted, or
* The profile is explicitly enabled using `--profile` or `COMPOSE_PROFILES`.

When a service with assigned `profiles` is explicitly targeted on the command line its profiles are started automatically so you don't need to start them manually. This can be used for one-off services and debugging tools. As an example consider the following configuration:

```yaml
services:
  backend:
    image: backend

  db:
    image: mysql

  db-migrations:
    image: backend
    command: myapp migrate
    depends_on:
      - db
    profiles:
      - tools
```

```sh
# Only start backend and db (no profiles involved)
$ docker compose up -d

# Run the db-migrations service without manually enabling the 'tools' profile
$ docker compose run db-migrations
```

In this example, `db-migrations` runs even though it is assigned to the tools profile, because it was explicitly targeted. The `db` service is also started automatically because it is listed in `depends_on`.

If the targeted service has dependencies that are also gated behind a profile, you must ensure those dependencies are either:

* In the same profile
* Started separately
* Not assigned to any profile so are always enabled

## [Stop application and services with specific profiles](#stop-application-and-services-with-specific-profiles)

As with starting specific profiles, you can use the `--profile` [command-line option](/reference/cli/docker/compose/#use--p-to-specify-a-project-name) or use the [`COMPOSE_PROFILES` environment variable](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_profiles):

```console
$ docker compose --profile debug down
```

```console
$ COMPOSE_PROFILES=debug docker compose down
```

Both commands stop and remove services with the `debug` profile and services without a profile. In the following `compose.yaml` file, this stops the services `db`, `backend` and `phpmyadmin`.

```yaml
services:
  frontend:
    image: frontend
    profiles: [frontend]

  phpmyadmin:
    image: phpmyadmin
    depends_on: [db]
    profiles: [debug]

  backend:
    image: backend

  db:
    image: mysql
```

if you only want to stop the `phpmyadmin` service, you can run

```console
$ docker compose down phpmyadmin
```

or

```console
$ docker compose stop phpmyadmin
```

> Note
>
> Running `docker compose down` only stops `backend` and `db`.

## [Reference information](#reference-information)

[`profiles`](https://docs.docker.com/reference/compose-file/services/#profiles)

----
url: https://docs.docker.com/build/cache/backends/inline/
----

# Inline cache

***

Table of contents

***

The `inline` cache storage backend is the simplest way to get an external cache and is easy to get started using if you're already building and pushing an image.

The downside of inline cache is that it doesn't scale with multi-stage builds as well as the other drivers do. It also doesn't offer separation between your output artifacts and your cache output. This means that if you're using a particularly complex build flow, or not exporting your images directly to a registry, then you may want to consider the [registry](https://docs.docker.com/build/cache/backends/registry/) cache.

## [Synopsis](#synopsis)

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=inline \
  --cache-from type=registry,ref=<registry>/<image> .
```

No additional parameters are supported for the `inline` cache.

To export cache using `inline` storage, pass `type=inline` to the `--cache-to` option:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=inline .
```

Alternatively, you can also export inline cache by setting the build argument `BUILDKIT_INLINE_CACHE=1`, instead of using the `--cache-to` flag:

```console
$ docker buildx build --push -t <registry>/<image> \
  --build-arg BUILDKIT_INLINE_CACHE=1 .
```

To import the resulting cache on a future build, pass `type=registry` to `--cache-from` which lets you extract the cache from inside a Docker image in the specified registry:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-from type=registry,ref=<registry>/<image> .
```

## [Further reading](#further-reading)

For an introduction to caching see [Docker build cache](https://docs.docker.com/build/cache/).

For more information on the `inline` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#inline-push-image-and-cache-together).

----
url: https://docs.docker.com/reference/cli/docker/volume/ls/
----

# docker volume ls

***

| Description                                                               | List volumes                 |
| ------------------------------------------------------------------------- | ---------------------------- |
| Usage                                                                     | `docker volume ls [OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker volume list`         |

## [Description](#description)

List all the volumes known to Docker. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filter) section for more information about available filter options.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cluster`               |         | API 1.42+ Swarm Display only cluster volumes, and use cluster volume list formatting                                                                                                                                                                                                                                                                                                   |
| [`-f, --filter`](#filter) |         | Provide filter values (e.g. `dangling=true`)                                                                                                                                                                                                                                                                                                                                           |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-q, --quiet`             |         | Only display volume names                                                                                                                                                                                                                                                                                                                                                              |

## [Examples](#examples)

### [Create a volume](#create-a-volume)

```console
$ docker volume create rosemary

rosemary

$ docker volume create tyler

tyler

$ docker volume ls

DRIVER              VOLUME NAME
local               rosemary
local               tyler
```

### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)

The currently supported filters are:

* dangling (Boolean - true or false, 0 or 1)
* driver (a volume driver's name)
* label (`label=<key>` or `label=<key>=<value>`)
* name (a volume's name)

#### [dangling](#dangling)

The `dangling` filter matches on all volumes not referenced by any containers

```console
$ docker run -d  -v tyler:/tmpwork  busybox

f86a7dd02898067079c99ceacd810149060a70528eff3754d0b0f1a93bd0af18
$ docker volume ls -f dangling=true
DRIVER              VOLUME NAME
local               rosemary
```

#### [driver](#driver)

The `driver` filter matches volumes based on their driver.

The following example matches volumes that are created with the `local` driver:

```console
$ docker volume ls -f driver=local

DRIVER              VOLUME NAME
local               rosemary
local               tyler
```

#### [label](#label)

The `label` filter matches volumes based on the presence of a `label` alone or a `label` and a value.

First, create some volumes to illustrate this;

```console
$ docker volume create the-doctor --label is-timelord=yes

the-doctor
$ docker volume create daleks --label is-timelord=no

daleks
```

The following example filter matches volumes with the `is-timelord` label regardless of its value.

```console
$ docker volume ls --filter label=is-timelord

DRIVER              VOLUME NAME
local               daleks
local               the-doctor
```

As the above example demonstrates, both volumes with `is-timelord=yes`, and `is-timelord=no` are returned.

Filtering on both `key` *and* `value` of the label, produces the expected result:

```console
$ docker volume ls --filter label=is-timelord=yes

DRIVER              VOLUME NAME
local               the-doctor
```

Specifying multiple label filter produces an "and" search; all conditions should be met;

```console
$ docker volume ls --filter label=is-timelord=yes --filter label=is-timelord=no

DRIVER              VOLUME NAME
```

#### [name](#name)

The `name` filter matches on all or part of a volume's name.

The following filter matches all volumes with a name containing the `rose` string.

```console
$ docker volume ls -f name=rose

DRIVER              VOLUME NAME
local               rosemary
```

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints volumes output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder   | Description                                                                           |
| ------------- | ------------------------------------------------------------------------------------- |
| `.Name`       | Volume name                                                                           |
| `.Driver`     | Volume driver                                                                         |
| `.Scope`      | Volume scope (local, global)                                                          |
| `.Mountpoint` | The mount point of the volume on the host                                             |
| `.Labels`     | All labels assigned to the volume                                                     |
| `.Label`      | Value of a specific label for this volume. For example `{{.Label "project.version"}}` |

When using the `--format` option, the `volume ls` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `Name` and `Driver` entries separated by a colon (`:`) for all volumes:

```console
$ docker volume ls --format "{{.Name}}: {{.Driver}}"

vol1: local
vol2: local
vol3: local
```

To list all volumes in JSON format, use the `json` directive:

```console
$ docker volume ls --format json
{"Driver":"local","Labels":"","Links":"N/A","Mountpoint":"/var/lib/docker/volumes/docker-cli-dev-cache/_data","Name":"docker-cli-dev-cache","Scope":"local","Size":"N/A"}
```

----
url: https://docs.docker.com/dhi/features/
----

# Docker Hardened Images features

***

Table of contents

***

Docker Hardened Images (DHI) are minimal, secure, and production-ready container base and application images maintained by Docker. Designed to reduce vulnerabilities and simplify compliance, DHI integrates easily into your existing Docker-based workflows with little to no retooling required.

DHI provides security for everyone:

* [DHI Community](#dhi-community-features) provides core security features available to everyone with no licensing restrictions under Apache 2.0.
* [DHI Select and DHI Enterprise](#dhi-select-and-enterprise-features) add SLA-backed security updates, FIPS/STIG compliance variants, and customization capabilities, with DHI Enterprise offering unlimited customization, full catalog access, and optional Extended Lifecycle Support (ELS) for post-EOL coverage.

## [DHI Community features](#dhi-community-features)

DHI's core features are open and free to use, share, and build on with no licensing surprises, backed by an Apache 2.0 license.

### [Security by default](#security-by-default)

* Near-zero CVEs: Continuously scanned and patched to maintain minimal known exploitable vulnerabilities, with no SLA-backed time commitments for DHI Community users
* Minimal attack surface: Distroless variants reduce attack surface by up to 95% by removing unnecessary components
* Non-root execution: Run as non-root by default, following the principle of least privilege
* Transparent vulnerability reporting: Every CVE is visible and assessed using public data—no suppressed feeds or proprietary scoring

### [Hardened system packages](#hardened-system-packages)

Docker Hardened Images maintain supply chain integrity throughout the entire image stack with hardened system packages:

* Source-built packages: For supported distributions, system packages are built from source code by Docker
* Cryptographic signatures: Every package is cryptographically signed and verified
* Supply chain security: Eliminates risk from potentially compromised public packages

Hardened system packages are included in supported distributions of DHI images. Community users can also configure their package manager to use Docker's public hardened package repository in their own images for the same packages included in the base images. See [Use hardened system packages](https://docs.docker.com/dhi/how-to/hardened-packages/) for details.

### [Total transparency](#total-transparency)

Every image includes complete, verifiable security metadata:

* SLSA Build Level 3 provenance: Verifiable, tamper-resistant builds that meet supply chain security standards
* Signed SBOMs: Complete Software Bill of Materials for every component
* VEX statements: Vulnerability Exploitability eXchange documents provide context about known CVEs
* Cryptographic signatures: All images and metadata are signed for authenticity

### [Built for developers](#built-for-developers)

* Familiar foundations: Built on Alpine and Debian, requiring minimal changes to adopt
* glibc and musl support: Available in both variants for broad application compatibility
* Development and runtime variants: Use dev images for building, minimal runtime images for production
* Drop-in compatibility: Works seamlessly with existing Docker workflows, CI/CD pipelines, and tools

### [Continuous maintenance](#continuous-maintenance)

* Automatic patching: Images are rebuilt and updated when upstream security patches become available, with no SLA-backed time commitments for DHI Community users
* Scanner integration: Direct integration with scanners and other security platforms

### [Kubernetes and Helm chart support](#kubernetes-and-helm-chart-support)

Docker Hardened Image (DHI) charts are Docker-provided Helm charts built from upstream sources, designed for compatibility with Docker Hardened Images. These charts are available as OCI artifacts within the DHI catalog on Docker Hub. DHI charts are robustly tested after building to ensure they work out-of-the-box with Docker Hardened Images. This removes friction in migration and reduces developer workload in implementing the charts, ensuring seamless compatibility.

Like the hardened images, DHI charts incorporate multiple layers of security metadata to ensure transparency and trust:

* SLSA Level 3 compliance: Each chart is built with Docker's SLSA Build Level 3 system, including a detailed build provenance, and meeting the standards set by the Supply-chain Levels for Software Artifacts (SLSA) framework.
* Software Bill of Materials (SBOMs): Comprehensive SBOMs are provided, detailing all components referenced within the chart to facilitate vulnerability management and compliance audits.
* Cryptographic signing: All associated metadata is cryptographically signed by Docker, ensuring integrity and authenticity.
* Hardened configuration: Charts automatically reference Docker hardened images, ensuring security in deployments.

## [DHI Select and Enterprise features](#dhi-select-and-enterprise-features)

For organizations with strict security requirements, regulatory demands, or operational needs, DHI Select and Enterprise deliver additional capabilities.

DHI Select offers customizations, compliance variants, and SLA-backed updates for teams and organizations with production workloads. DHI Enterprise includes everything in Select with unlimited customizations, plus an optional Extended Lifecycle Support add-on and full catalog access for large enterprises with advanced security needs.

For a detailed comparison, see [Docker Hardened Images subscription comparison](https://www.docker.com/products/hardened-images/#compare).

### [SLA-backed security ](#sla-backed-security)DHI Select or DHI Enterprise

* CVE remediation SLA: 7-day SLA for critical and high severity vulnerabilities
* Continuous patching: Regular security updates backed by SLA commitments
* Enterprise support: Access to Docker's support team for mission-critical applications

For complete details, see the [Support Service Level Agreement](https://docs.docker.com/go/dhi-sla/).

### [Compliance variants ](#compliance-variants)DHI Select or DHI Enterprise

* FIPS-enabled images: For regulated industries and government systems
* STIG-ready images: Meet DoD Security Technical Implementation Guide requirements

### [Customization and control ](#customization-and-control)DHI Select or DHI Enterprise

* Build custom images: Add your own packages, tools, certificates, and configurations

  * DHI Select: Up to 5 customizations
  * DHI Enterprise: Unlimited customizations

* Hardened packages: Access to additional compliance-specific packages (such as FIPS variants) and Docker-patched packages not available in the public repository

  * DHI Select: Add these packages through the customization UI when customizing hardened images
  * DHI Enterprise: Add these packages through the customization UI, or configure your package manager to use the enterprise package repository in your own images

* Secure build infrastructure: Customizations built on Docker's trusted infrastructure

* Full chain of trust: Customized images maintain provenance and cryptographic signing

* Automatic updates: Custom images are automatically rebuilt when base images are patched

### [Extended Lifecycle Support ](#extended-lifecycle-support)DHI Enterprise add-on

* Post-EOL security coverage: Continue receiving patches for years after upstream support ends
* Continuous compliance: Updated SBOMs, provenance, and signing for audit requirements
* Production continuity: Keep production running securely without forced migrations

## [Learn more](#learn-more)

* [Explore how DHI images are built and more](/dhi/explore/)
* [Get started using DHIs](/dhi/get-started/)
* [Contact Docker for DHI Enterprise](https://www.docker.com/pricing/contact-sales/)

----
url: https://docs.docker.com/engine/network/drivers/ipvlan/
----

# IPvlan network driver

***

Table of contents

***

The IPvlan driver gives users total control over both IPv4 and IPv6 addressing. The VLAN driver builds on top of that in giving operators complete control of layer 2 VLAN tagging and even IPvlan L3 routing for users interested in underlay network integration. For overlay deployments that abstract away physical constraints see the [multi-host overlay](https://docs.docker.com/engine/network/drivers/overlay/) driver.

IPvlan is a new twist on the tried and true network virtualization technique. The Linux implementations are extremely lightweight because rather than using the traditional Linux bridge for isolation, they are associated to a Linux Ethernet interface or sub-interface to enforce separation between networks and connectivity to the physical network.

IPvlan offers a number of unique features and plenty of room for further innovations with the various modes. Two high level advantages of these approaches are, the positive performance implications of bypassing the Linux bridge and the simplicity of having fewer moving parts. Removing the bridge that traditionally resides in between the Docker host NIC and container interface leaves a simple setup consisting of container interfaces, attached directly to the Docker host interface. This result is easy to access for external facing services as there is no need for port mappings in these scenarios.

## [Options](#options)

The following table describes the driver-specific options that you can pass to `--opt` when creating a network using the `ipvlan` driver.

| Option        | Default  | Description                                                           |
| ------------- | -------- | --------------------------------------------------------------------- |
| `ipvlan_mode` | `l2`     | Sets the IPvlan operating mode. Can be one of: `l2`, `l3`, `l3s`      |
| `ipvlan_flag` | `bridge` | Sets the IPvlan mode flag. Can be one of: `bridge`, `private`, `vepa` |
| `parent`      |          | Specifies the parent interface to use.                                |

## [Examples](#examples)

### [Prerequisites](#prerequisites)

* The examples on this page are all single host.
* All examples can be performed on a single host running Docker. Any example using a sub-interface like `eth0.10` can be replaced with `eth0` or any other valid parent interface on the Docker host. Sub-interfaces with a `.` are created on the fly. `-o parent` interfaces can also be left out of the `docker network create` all together and the driver will create a `dummy` interface that will enable local host connectivity to perform the examples.
* Kernel requirements:
  * IPvlan Linux kernel v4.2+ (support for earlier kernels exists but is buggy). To check your current kernel version, use `uname -r`

### [IPvlan L2 mode example usage](#ipvlan-l2-mode-example-usage)

An example of the IPvlan `L2` mode topology is shown in the following image. The driver is specified with `-d driver_name` option. In this case `-d ipvlan`.

The parent interface in the next example `-o parent=eth0` is configured as follows:

```console
$ ip addr show eth0
3: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    inet 192.168.1.250/24 brd 192.168.1.255 scope global eth0
```

Use the network from the host's interface as the `--subnet` in the `docker network create`. The container will be attached to the same network as the host interface as set via the `-o parent=` option.

Create the IPvlan network and run a container attaching to it:

```console
# IPvlan  (-o ipvlan_mode= Defaults to L2 mode if not specified)
$ docker network create -d ipvlan \
    --subnet=192.168.1.0/24 \
    --gateway=192.168.1.1 \
    -o ipvlan_mode=l2 \
    -o parent=eth0 db_net

# Start a container on the db_net network
$ docker run --net=db_net -it --rm alpine /bin/sh

# NOTE: the containers can NOT ping the underlying host interfaces as
# they are intentionally filtered by Linux for additional isolation.
```

The default mode for IPvlan is `l2`. If `-o ipvlan_mode=` is left unspecified, the default mode will be used. Similarly, if the `--gateway` is left empty, the first usable address on the network will be set as the gateway. For example, if the subnet provided in the network create is `--subnet=192.168.1.0/24` then the gateway the container receives is `192.168.1.1`.

To help understand how this mode interacts with other hosts, the following figure shows the same layer 2 segment between two Docker hosts that applies to and IPvlan L2 mode.

The following will create the exact same network as the network `db_net` created earlier, with the driver defaults for `--gateway=192.168.1.1` and `-o ipvlan_mode=l2`.

```console
# IPvlan  (-o ipvlan_mode= Defaults to L2 mode if not specified)
$ docker network create -d ipvlan \
    --subnet=192.168.1.0/24 \
    -o parent=eth0 db_net_ipv

# Start a container with an explicit name in daemon mode
$ docker run --net=db_net_ipv --name=ipv1 -itd alpine /bin/sh

# Start a second container and ping using the container name
# to see the docker included name resolution functionality
$ docker run --net=db_net_ipv --name=ipv2 -it --rm alpine /bin/sh
$ ping -c 4 ipv1

# NOTE: the containers can NOT ping the underlying host interfaces as
# they are intentionally filtered by Linux for additional isolation.
```

The drivers also support the `--internal` flag that will completely isolate containers on a network from any communications external to that network. Since network isolation is tightly coupled to the network's parent interface the result of leaving the `-o parent=` option off of a `docker network create` is the exact same as the `--internal` option. If the parent interface is not specified or the `--internal` flag is used, a netlink type `dummy` parent interface is created for the user and used as the parent interface effectively isolating the network completely.

The following two `docker network create` examples result in identical networks that you can attach container to:

```console
# Empty '-o parent=' creates an isolated network
$ docker network create -d ipvlan \
    --subnet=192.168.10.0/24 isolated1

# Explicit '--internal' flag is the same:
$ docker network create -d ipvlan \
    --subnet=192.168.11.0/24 --internal isolated2

# Even the '--subnet=' can be left empty and the default
# IPAM subnet of 172.18.0.0/16 will be assigned
$ docker network create -d ipvlan isolated3

$ docker run --net=isolated1 --name=cid1 -it --rm alpine /bin/sh
$ docker run --net=isolated2 --name=cid2 -it --rm alpine /bin/sh
$ docker run --net=isolated3 --name=cid3 -it --rm alpine /bin/sh

# To attach to any use `docker exec` and start a shell
$ docker exec -it cid1 /bin/sh
$ docker exec -it cid2 /bin/sh
$ docker exec -it cid3 /bin/sh
```

### [IPvlan 802.1Q trunk L2 mode example usage](#ipvlan-8021q-trunk-l2-mode-example-usage)

Architecturally, IPvlan L2 mode trunking is the same as Macvlan with regard to gateways and L2 path isolation. There are nuances that can be advantageous for CAM table pressure in ToR switches, one MAC per port and MAC exhaustion on a host's parent NIC to name a few. The 802.1Q trunk scenario looks the same. Both modes adhere to tagging standards and have seamless integration with the physical network for underlay integration and hardware vendor plugin integrations.

Hosts on the same VLAN are typically on the same subnet and almost always are grouped together based on their security policy. In most scenarios, a multi-tier application is tiered into different subnets because the security profile of each process requires some form of isolation. For example, hosting your credit card processing on the same virtual network as the frontend webserver would be a regulatory compliance issue, along with circumventing the long standing best practice of layered defense in depth architectures. VLANs or the equivocal VNI (Virtual Network Identifier) when using the Overlay driver, are the first step in isolating tenant traffic.

The Linux sub-interface tagged with a VLAN can either already exist or will be created when you call a `docker network create`. `docker network rm` will delete the sub-interface. Parent interfaces such as `eth0` are not deleted, only sub-interfaces with a netlink parent index > 0.

For the driver to add/delete the VLAN sub-interfaces the format needs to be `interface_name.vlan_tag`. Other sub-interface naming can be used as the specified parent, but the link will not be deleted automatically when `docker network rm` is invoked.

The option to use either existing parent VLAN sub-interfaces or let Docker manage them enables the user to either completely manage the Linux interfaces and networking or let Docker create and delete the VLAN parent sub-interfaces (netlink `ip link`) with no effort from the user.

For example: use `eth0.10` to denote a sub-interface of `eth0` tagged with the VLAN id of `10`. The equivalent `ip link` command would be `ip link add link eth0 name eth0.10 type vlan id 10`.

The example creates the VLAN tagged networks and then starts two containers to test connectivity between containers. Different VLANs cannot ping one another without a router routing between the two networks. The default namespace is not reachable per IPvlan design in order to isolate container namespaces from the underlying host.

#### [VLAN ID 20](#vlan-id-20)

In the first network tagged and isolated by the Docker host, `eth0.20` is the parent interface tagged with VLAN id `20` specified with `-o parent=eth0.20`. Other naming formats can be used, but the links need to be added and deleted manually using `ip link` or Linux configuration files. As long as the `-o parent` exists, anything can be used if it is compliant with Linux netlink.

```console
# now add networks and hosts as you would normally by attaching to the master (sub)interface that is tagged
$ docker network create -d ipvlan \
    --subnet=192.168.20.0/24 \
    --gateway=192.168.20.1 \
    -o parent=eth0.20 ipvlan20

# in two separate terminals, start a Docker container and the containers can now ping one another.
$ docker run --net=ipvlan20 -it --name ivlan_test1 --rm alpine /bin/sh
$ docker run --net=ipvlan20 -it --name ivlan_test2 --rm alpine /bin/sh
```

#### [VLAN ID 30](#vlan-id-30)

In the second network, tagged and isolated by the Docker host, `eth0.30` is the parent interface tagged with VLAN id `30` specified with `-o parent=eth0.30`. The `ipvlan_mode=` defaults to l2 mode `ipvlan_mode=l2`. It can also be explicitly set with the same result as shown in the next example.

```console
# now add networks and hosts as you would normally by attaching to the master (sub)interface that is tagged.
$ docker network create -d ipvlan \
    --subnet=192.168.30.0/24 \
    --gateway=192.168.30.1 \
    -o parent=eth0.30 \
    -o ipvlan_mode=l2 ipvlan30

# in two separate terminals, start a Docker container and the containers can now ping one another.
$ docker run --net=ipvlan30 -it --name ivlan_test3 --rm alpine /bin/sh
$ docker run --net=ipvlan30 -it --name ivlan_test4 --rm alpine /bin/sh
```

The gateway is set inside of the container as the default gateway. That gateway would typically be an external router on the network.

```console
$$ ip route
  default via 192.168.30.1 dev eth0
  192.168.30.0/24 dev eth0  src 192.168.30.2
```

Example: Multi-Subnet IPvlan L2 Mode starting two containers on the same subnet and pinging one another. In order for the `192.168.114.0/24` to reach `192.168.116.0/24` it requires an external router in L2 mode. L3 mode can route between subnets that share a common `-o parent=`.

Secondary addresses on network routers are common as an address space becomes exhausted to add another secondary to an L3 VLAN interface or commonly referred to as a "switched virtual interface" (SVI).

```console
$ docker network create -d ipvlan \
    --subnet=192.168.114.0/24 --subnet=192.168.116.0/24 \
    --gateway=192.168.114.254 --gateway=192.168.116.254 \
    -o parent=eth0.114 \
    -o ipvlan_mode=l2 ipvlan114

$ docker run --net=ipvlan114 --ip=192.168.114.10 -it --rm alpine /bin/sh
$ docker run --net=ipvlan114 --ip=192.168.114.11 -it --rm alpine /bin/sh
```

A key takeaway is, operators have the ability to map their physical network into their virtual network for integrating containers into their environment with no operational overhauls required. NetOps drops an 802.1Q trunk into the Docker host. That virtual link would be the `-o parent=` passed in the network creation. For untagged (non-VLAN) links, it is as simple as `-o parent=eth0` or for 802.1Q trunks with VLAN IDs each network gets mapped to the corresponding VLAN/Subnet from the network.

An example being, NetOps provides VLAN ID and the associated subnets for VLANs being passed on the Ethernet link to the Docker host server. Those values are plugged into the `docker network create` commands when provisioning the Docker networks. These are persistent configurations that are applied every time the Docker engine starts which alleviates having to manage often complex configuration files. The network interfaces can also be managed manually by being pre-created and Docker networking will never modify them, and use them as parent interfaces. Example mappings from NetOps to Docker network commands are as follows:

* VLAN: 10, Subnet: 172.16.80.0/24, Gateway: 172.16.80.1
  * `--subnet=172.16.80.0/24 --gateway=172.16.80.1 -o parent=eth0.10`
* VLAN: 20, IP subnet: 172.16.50.0/22, Gateway: 172.16.50.1
  * `--subnet=172.16.50.0/22 --gateway=172.16.50.1 -o parent=eth0.20`
* VLAN: 30, Subnet: 10.1.100.0/16, Gateway: 10.1.100.1
  * `--subnet=10.1.100.0/16 --gateway=10.1.100.1 -o parent=eth0.30`

### [IPvlan L3 mode example](#ipvlan-l3-mode-example)

IPvlan will require routes to be distributed to each endpoint. The driver only builds the IPvlan L3 mode port and attaches the container to the interface. Route distribution throughout a cluster is beyond the initial implementation of this single host scoped driver. In L3 mode, the Docker host is very similar to a router starting new networks in the container. They are on networks that the upstream network will not know about without route distribution. For those curious how IPvlan L3 will fit into container networking, see the following examples.

IPvlan L3 mode drops all broadcast and multicast traffic. This reason alone makes IPvlan L3 mode a prime candidate for those looking for massive scale and predictable network integrations. It is predictable and in turn will lead to greater uptimes because there is no bridging involved. Bridging loops have been responsible for high profile outages that can be hard to pinpoint depending on the size of the failure domain. This is due to the cascading nature of BPDUs (Bridge Port Data Units) that are flooded throughout a broadcast domain (VLAN) to find and block topology loops. Eliminating bridging domains, or at the least, keeping them isolated to a pair of ToRs (top of rack switches) will reduce hard to troubleshoot bridging instabilities. IPvlan L2 modes is well suited for isolated VLANs only trunked into a pair of ToRs that can provide a loop-free non-blocking fabric. The next step further is to route at the edge via IPvlan L3 mode that reduces a failure domain to a local host only.

* L3 mode needs to be on a separate subnet as the default namespace since it requires a netlink route in the default namespace pointing to the IPvlan parent interface.
* The parent interface used in this example is `eth0` and it is on the subnet `192.168.1.0/24`. Notice the `docker network` is not on the same subnet as `eth0`.
* Unlike IPvlan l2 modes, different subnets/networks can ping one another as long as they share the same parent interface `-o parent=`.

```console
$$ ip a show eth0
3: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 00:50:56:39:45:2e brd ff:ff:ff:ff:ff:ff
    inet 192.168.1.250/24 brd 192.168.1.255 scope global eth0
```

* A traditional gateway doesn't mean much to an L3 mode IPvlan interface since there is no broadcast traffic allowed. Because of that, the container default gateway points to the containers `eth0` device. See below for CLI output of `ip route` or `ip -6 route` from inside an L3 container for details.

The mode `-o ipvlan_mode=l3` must be explicitly specified since the default IPvlan mode is `l2`.

The following example does not specify a parent interface. The network drivers will create a dummy type link for the user rather than rejecting the network creation and isolating containers from only communicating with one another.

```console
# Create the IPvlan L3 network
$ docker network create -d ipvlan \
    --subnet=192.168.214.0/24 \
    --subnet=10.1.214.0/24 \
    -o ipvlan_mode=l3 ipnet210

# Test 192.168.214.0/24 connectivity
$ docker run --net=ipnet210 --ip=192.168.214.10 -itd alpine /bin/sh
$ docker run --net=ipnet210 --ip=10.1.214.10 -itd alpine /bin/sh

# Test L3 connectivity from 10.1.214.0/24 to 192.168.214.0/24
$ docker run --net=ipnet210 --ip=192.168.214.9 -it --rm alpine ping -c 2 10.1.214.10

# Test L3 connectivity from 192.168.214.0/24 to 10.1.214.0/24
$ docker run --net=ipnet210 --ip=10.1.214.9 -it --rm alpine ping -c 2 192.168.214.10
```

> Note
>
> Notice that there is no `--gateway=` option in the network create. The field is ignored if one is specified `l3` mode. Take a look at the container routing table from inside of the container:
>
> ```console
> # Inside an L3 mode container
> $$ ip route
>  default dev eth0
>   192.168.214.0/24 dev eth0  src 192.168.214.10
> ```

In order to ping the containers from a remote Docker host or the container be able to ping a remote host, the remote host or the physical network in between need to have a route pointing to the host IP address of the container's Docker host eth interface.

### [Dual stack IPv4 IPv6 IPvlan L2 mode](#dual-stack-ipv4-ipv6-ipvlan-l2-mode)

* Not only does Libnetwork give you complete control over IPv4 addressing, but it also gives you total control over IPv6 addressing as well as feature parity between the two address families.

* The next example will start with IPv6 only. Start two containers on the same VLAN `139` and ping one another. Since the IPv4 subnet is not specified, the default IPAM will provision a default IPv4 subnet. That subnet is isolated unless the upstream network is explicitly routing it on VLAN `139`.

```console
# Create a v6 network
$ docker network create -d ipvlan \
    --ipv6 --subnet=2001:db8:abc2::/64 --gateway=2001:db8:abc2::22 \
    -o parent=eth0.139 v6ipvlan139

# Start a container on the network
$ docker run --net=v6ipvlan139 -it --rm alpine /bin/sh
```

View the container eth0 interface and v6 routing table:

```console
# Inside the IPv6 container
$$ ip a show eth0
75: eth0@if55: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default
    link/ether 00:50:56:2b:29:40 brd ff:ff:ff:ff:ff:ff
    inet 172.18.0.2/16 scope global eth0
       valid_lft forever preferred_lft forever
    inet6 2001:db8:abc4::250:56ff:fe2b:2940/64 scope link
       valid_lft forever preferred_lft forever
    inet6 2001:db8:abc2::1/64 scope link nodad
       valid_lft forever preferred_lft forever

$$ ip -6 route
2001:db8:abc4::/64 dev eth0  proto kernel  metric 256
2001:db8:abc2::/64 dev eth0  proto kernel  metric 256
default via 2001:db8:abc2::22 dev eth0  metric 1024
```

Start a second container and ping the first container's v6 address.

```console
# Test L2 connectivity over IPv6
$ docker run --net=v6ipvlan139 -it --rm alpine /bin/sh

# Inside the second IPv6 container
$$ ip a show eth0
75: eth0@if55: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default
    link/ether 00:50:56:2b:29:40 brd ff:ff:ff:ff:ff:ff
    inet 172.18.0.3/16 scope global eth0
       valid_lft forever preferred_lft forever
    inet6 2001:db8:abc4::250:56ff:fe2b:2940/64 scope link tentative dadfailed
       valid_lft forever preferred_lft forever
    inet6 2001:db8:abc2::2/64 scope link nodad
       valid_lft forever preferred_lft forever

$$ ping6 2001:db8:abc2::1
PING 2001:db8:abc2::1 (2001:db8:abc2::1): 56 data bytes
64 bytes from 2001:db8:abc2::1%eth0: icmp_seq=0 ttl=64 time=0.044 ms
64 bytes from 2001:db8:abc2::1%eth0: icmp_seq=1 ttl=64 time=0.058 ms

2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max/stddev = 0.044/0.051/0.058/0.000 ms
```

The next example with setup a dual stack IPv4/IPv6 network with an example VLAN ID of `140`.

Next create a network with two IPv4 subnets and one IPv6 subnets, all of which have explicit gateways:

```console
$ docker network create -d ipvlan \
    --subnet=192.168.140.0/24 --subnet=192.168.142.0/24 \
    --gateway=192.168.140.1 --gateway=192.168.142.1 \
    --subnet=2001:db8:abc9::/64 --gateway=2001:db8:abc9::22 \
    -o parent=eth0.140 \
    -o ipvlan_mode=l2 ipvlan140
```

Start a container and view eth0 and both v4 & v6 routing tables:

```console
$ docker run --net=ipvlan140 --ip6=2001:db8:abc2::51 -it --rm alpine /bin/sh

$ ip a show eth0
78: eth0@if77: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default
    link/ether 00:50:56:2b:29:40 brd ff:ff:ff:ff:ff:ff
    inet 192.168.140.2/24 scope global eth0
       valid_lft forever preferred_lft forever
    inet6 2001:db8:abc4::250:56ff:fe2b:2940/64 scope link
       valid_lft forever preferred_lft forever
    inet6 2001:db8:abc9::1/64 scope link nodad
       valid_lft forever preferred_lft forever

$$ ip route
default via 192.168.140.1 dev eth0
192.168.140.0/24 dev eth0  proto kernel  scope link  src 192.168.140.2

$$ ip -6 route
2001:db8:abc4::/64 dev eth0  proto kernel  metric 256
2001:db8:abc9::/64 dev eth0  proto kernel  metric 256
default via 2001:db8:abc9::22 dev eth0  metric 1024
```

Start a second container with a specific `--ip4` address and ping the first host using IPv4 packets:

```console
$ docker run --net=ipvlan140 --ip=192.168.140.10 -it --rm alpine /bin/sh
```

> Note
>
> Different subnets on the same parent interface in IPvlan `L2` mode cannot ping one another. That requires a router to proxy-arp the requests with a secondary subnet. However, IPvlan `L3` will route the unicast traffic between disparate subnets as long as they share the same `-o parent` parent link.

### [Dual stack IPv4 IPv6 IPvlan L3 mode](#dual-stack-ipv4-ipv6-ipvlan-l3-mode)

Example: IPvlan L3 Mode Dual Stack IPv4/IPv6, Multi-Subnet w/ 802.1Q VLAN Tag:118

As in all of the examples, a tagged VLAN interface does not have to be used. The sub-interfaces can be swapped with `eth0`, `eth1`, `bond0` or any other valid interface on the host other then the `lo` loopback.

The primary difference you will see is that L3 mode does not create a default route with a next-hop but rather sets a default route pointing to `dev eth` only since ARP/Broadcasts/Multicast are all filtered by Linux as per the design. Since the parent interface is essentially acting as a router, the parent interface IP and subnet needs to be different from the container networks. That is the opposite of bridge and L2 modes, which need to be on the same subnet (broadcast domain) in order to forward broadcast and multicast packets.

```console
# Create an IPv6+IPv4 Dual Stack IPvlan L3 network
# Gateways for both v4 and v6 are set to a dev e.g. 'default dev eth0'
$ docker network create -d ipvlan \
    --subnet=192.168.110.0/24 \
    --subnet=192.168.112.0/24 \
    --ipv6 --subnet=2001:db8:abc6::/64 \
    -o parent=eth0 \
    -o ipvlan_mode=l3 ipnet110


# Start a few of containers on the network (ipnet110)
# in separate terminals and check connectivity
$ docker run --net=ipnet110 -it --rm alpine /bin/sh
# Start a second container specifying the v6 address
$ docker run --net=ipnet110 --ip6=2001:db8:abc6::10 -it --rm alpine /bin/sh
# Start a third specifying the IPv4 address
$ docker run --net=ipnet110 --ip=192.168.112.30 -it --rm alpine /bin/sh
# Start a 4th specifying both the IPv4 and IPv6 addresses
$ docker run --net=ipnet110 --ip6=2001:db8:abc6::50 --ip=192.168.112.50 -it --rm alpine /bin/sh
```

Interface and routing table outputs are as follows:

```console
$$ ip a show eth0
63: eth0@if59: <BROADCAST,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default
    link/ether 00:50:56:2b:29:40 brd ff:ff:ff:ff:ff:ff
    inet 192.168.112.2/24 scope global eth0
       valid_lft forever preferred_lft forever
    inet6 2001:db8:abc4::250:56ff:fe2b:2940/64 scope link
       valid_lft forever preferred_lft forever
    inet6 2001:db8:abc6::10/64 scope link nodad
       valid_lft forever preferred_lft forever

# Note the default route is the eth device because ARPs are filtered.
$$ ip route
  default dev eth0  scope link
  192.168.112.0/24 dev eth0  proto kernel  scope link  src 192.168.112.2

$$ ip -6 route
2001:db8:abc4::/64 dev eth0  proto kernel  metric 256
2001:db8:abc6::/64 dev eth0  proto kernel  metric 256
default dev eth0  metric 1024
```

> Note
>
> There may be a bug when specifying `--ip6=` addresses when you delete a container with a specified v6 address and then start a new container with the same v6 address it throws the following like the address isn't properly being released to the v6 pool. It will fail to unmount the container and be left dead.

```console
docker: Error response from daemon: Address already in use.
```

### [Manually create 802.1Q links](#manually-create-8021q-links)

#### [VLAN ID 40](#vlan-id-40)

If a user does not want the driver to create the VLAN sub-interface, it needs to exist before running `docker network create`. If you have sub-interface naming that is not `interface.vlan_id` it is honored in the `-o parent=` option again as long as the interface exists and is up.

Links, when manually created, can be named anything as long as they exist when the network is created. Manually created links do not get deleted regardless of the name when the network is deleted with `docker network rm`.

```console
# create a new sub-interface tied to dot1q vlan 40
$ ip link add link eth0 name eth0.40 type vlan id 40

# enable the new sub-interface
$ ip link set eth0.40 up

# now add networks and hosts as you would normally by attaching to the master (sub)interface that is tagged
$ docker network create -d ipvlan \
    --subnet=192.168.40.0/24 \
    --gateway=192.168.40.1 \
    -o parent=eth0.40 ipvlan40

# in two separate terminals, start a Docker container and the containers can now ping one another.
$ docker run --net=ipvlan40 -it --name ivlan_test5 --rm alpine /bin/sh
$ docker run --net=ipvlan40 -it --name ivlan_test6 --rm alpine /bin/sh
```

Example: VLAN sub-interface manually created with any name:

```console
# create a new sub interface tied to dot1q vlan 40
$ ip link add link eth0 name foo type vlan id 40

# enable the new sub-interface
$ ip link set foo up

# now add networks and hosts as you would normally by attaching to the master (sub)interface that is tagged
$ docker network create -d ipvlan \
    --subnet=192.168.40.0/24 --gateway=192.168.40.1 \
    -o parent=foo ipvlan40

# in two separate terminals, start a Docker container and the containers can now ping one another.
$ docker run --net=ipvlan40 -it --name ivlan_test5 --rm alpine /bin/sh
$ docker run --net=ipvlan40 -it --name ivlan_test6 --rm alpine /bin/sh
```

Manually created links can be cleaned up with:

```console
$ ip link del foo
```

As with all of the Libnetwork drivers, they can be mixed and matched, even as far as running 3rd party ecosystem drivers in parallel for maximum flexibility to the Docker user.

----
url: https://docs.docker.com/scout/integrations/environment/sysdig/
----

# Integrate Docker Scout with Sysdig

***

Table of contents

***

The Sysdig integration enables Docker Scout to automatically detect the images you're using for your running workloads. Activating this integration gives you real-time insights about your security posture, and lets you compare your builds with what's running in production.

## [How it works](#how-it-works)

The Sysdig Agent captures the images of your container workloads. Docker Scout integrates with the Sysdig API to discover the images in your cluster. This integration uses Sysdig's Risk Spotlight feature. For more information, see [Risk Spotlight Integrations (Sysdig docs)](https://docs.sysdig.com/en/docs/sysdig-secure/integrations-for-sysdig-secure/risk-spotlight-integrations/).

> Tip
>
> Sysdig offers a free trial for Docker users to try out the new Docker Scout integration.
>
> [Sign up](https://sysdig.com/free-trial-for-docker-customers/)

Each Sysdig integration maps to an environment. When you enable a Sysdig integration, you specify the environment name for that cluster, such as `production` or `staging`. Docker Scout assigns the images in the cluster to the corresponding environment. This lets you use the environment filters to see vulnerability status and policy compliance for an environment.

Only images analyzed by Docker Scout can be assigned to an environment. The Sysdig runtime integration doesn't trigger image analysis by itself. To analyze images automatically, enable a [registry integration](https://docs.docker.com/scout/integrations/#container-registries).

Image analysis must not necessarily precede the runtime integration, but the environment assignment only takes place once Docker Scout has analyzed the image.

## [Prerequisites](#prerequisites)

* Install the Sysdig Agent in the cluster that you want to integrate, see [Install Sysdig Agent (Sysdig docs)](https://docs.sysdig.com/en/docs/installation/sysdig-monitor/install-sysdig-agent/).
* Enable profiling for Risk Spotlight Integrations in Sysdig, see [Profiling (Sysdig docs)](https://docs.sysdig.com/en/docs/sysdig-secure/policies/profiling/#enablement).
* You must be an organization owner to enable the integration in the Docker Scout Dashboard.

## [Integrate an environment](#integrate-an-environment)

1. Go to the [Sysdig integration page](https://scout.docker.com/settings/integrations/sysdig/) on the Docker Scout Dashboard.

2. In the **How to integrate** section, enter a configuration name for this integration. Docker Scout uses this label as a display name for the integration.

3. Select **Next**.

4. Enter a Risk Spotlight API token and select the region in the drop-down list.

   The Risk Spotlight API token is the Sysdig token that Docker Scout needs to integrate with Sysdig. For more instructions on how to generate a Risk Spotlight token, See [Risk Spotlight Integrations (Sysdig docs)](https://docs.sysdig.com/en/docs/sysdig-secure/integrations-for-sysdig-secure/risk-spotlight-integrations/docker-scout/#generate-a-token-for-the-integration).

   The region corresponds to the `global.sysdig.region` configuration parameter set when deploying the Sysdig Agent.

5. Select **Next**.

   After selecting **Next**, Docker Scout connects to Sysdig and retrieves the cluster names for your Sysdig account. Cluster names correspond to the `global.clusterConfig.name` configuration parameter set when deploying Sysdig Agents.

   An error displays if Docker Scout fails to connect to Sysdig using the provided token. If there's an error, you won't be able to continue the integration. Go back and verify that the configuration details are correct.

6. Select a cluster name in the drop-down list.

7. Select **Next**.

8. Assign an environment name for this cluster.

   You can reuse an existing environment or create a new one.

9. Select **Enable integration**.

After enabling the integration, Docker Scout automatically detects images running in the cluster, and assigns those images to the environment associated with the cluster. For more information about environments, see [Environment monitoring](https://docs.docker.com/scout/integrations/environment/).

> Note
>
> Docker Scout only detects images that have been analyzed. To trigger an image analysis, enable a [registry integration](https://docs.docker.com/scout/integrations/#container-registries) and push an image to your registry.
>
> If you created a new environment for this integration, the environment appears in Docker Scout when at least one image has been analyzed.

To integrate more clusters, go to the [Sysdig integrations page](https://scout.docker.com/settings/integrations/sysdig/) and select the **Add** button.

----
url: https://docs.docker.com/reference/cli/docker/search/
----

# docker search

***

| Description | Search Docker Hub for images   |
| ----------- | ------------------------------ |
| Usage       | `docker search [OPTIONS] TERM` |

## [Description](#description)

Search [Docker Hub](https://hub.docker.com) for images

## [Options](#options)

| Option                    | Default | Description                                |
| ------------------------- | ------- | ------------------------------------------ |
| [`-f, --filter`](#filter) |         | Filter output based on conditions provided |
| [`--format`](#format)     |         | Pretty-print search using a Go template    |
| [`--limit`](#limit)       |         | Max number of search results               |
| [`--no-trunc`](#no-trunc) |         | Don't truncate output                      |

## [Examples](#examples)

### [Search images by name](#search-images-by-name)

This example displays images with a name containing 'busybox':

```console
$ docker search busybox

NAME                             DESCRIPTION                                     STARS     OFFICIAL
busybox                          Busybox base image.                             316       [OK]
progrium/busybox                                                                 50
radial/busyboxplus               Full-chain, Internet enabled, busybox made...   8
odise/busybox-python                                                             2
azukiapp/busybox                 This image is meant to be used as the base...   2
ofayau/busybox-jvm               Prepare busybox to install a 32 bits JVM.       1
shingonoide/archlinux-busybox    Arch Linux, a lightweight and flexible Lin...   1
odise/busybox-curl                                                               1
ofayau/busybox-libc32            Busybox with 32 bits (and 64 bits) libs         1
peelsky/zulu-openjdk-busybox                                                     1
skomma/busybox-data              Docker image suitable for data volume cont...   1
elektritter/busybox-teamspeak    Lightweight teamspeak3 container based on...    1
socketplane/busybox                                                              1
oveits/docker-nginx-busybox      This is a tiny NginX docker image based on...   0
ggtools/busybox-ubuntu           Busybox ubuntu version with extra goodies       0
nikfoundas/busybox-confd         Minimal busybox based distribution of confd     0
openshift/busybox-http-app                                                       0
jllopis/busybox                                                                  0
swyckoff/busybox                                                                 0
powellquiring/busybox                                                            0
williamyeh/busybox-sh            Docker image for BusyBox's sh                   0
simplexsys/busybox-cli-powered   Docker busybox images, with a few often us...   0
fhisamoto/busybox-java           Busybox java                                    0
scottabernethy/busybox                                                           0
marclop/busybox-solr
```

### [Display non-truncated description (--no-trunc)](#no-trunc)

This example displays images with a name containing 'busybox', at least 3 stars and the description isn't truncated in the output:

```console
$ docker search --filter=stars=3 --no-trunc busybox

NAME                 DESCRIPTION                                                                               STARS     OFFICIAL
busybox              Busybox base image.                                                                       325       [OK]
progrium/busybox                                                                                               50
radial/busyboxplus   Full-chain, Internet enabled, busybox made from scratch. Comes in git and cURL flavors.   8
```

### [Limit search results (--limit)](#limit)

The flag `--limit` is the maximum number of results returned by a search. If no value is set, the default is set by the daemon.

### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter is-official=true --filter stars=3`).

The currently supported filters are:

* stars (int - number of stars the image has)
* is-automated (boolean - true or false) - is the image automated or not (deprecated)
* is-official (boolean - true or false) - is the image official or not

#### [stars](#stars)

This example displays images with a name containing 'busybox' and at least 3 stars:

```console
$ docker search --filter stars=3 busybox

NAME                 DESCRIPTION                                     STARS     OFFICIAL
busybox              Busybox base image.                             325       [OK]
progrium/busybox                                                     50
radial/busyboxplus   Full-chain, Internet enabled, busybox made...   8
```

#### [is-official](#is-official)

This example displays images with a name containing 'busybox', at least 3 stars and are official builds:

```console
$ docker search --filter is-official=true --filter stars=3 busybox

NAME      DESCRIPTION           STARS     OFFICIAL
busybox   Busybox base image.   325       [OK]
```

### [Format the output (--format)](#format)

The formatting option (`--format`) pretty-prints search output using a Go template.

Valid placeholders for the Go template are:

| Placeholder    | Description                   |
| -------------- | ----------------------------- |
| `.Name`        | Image Name                    |
| `.Description` | Image description             |
| `.StarCount`   | Number of stars for the image |
| `.IsOfficial`  | "OK" if image is official     |

When you use the `--format` option, the `search` command will output the data exactly as the template declares. If you use the `table` directive, column headers are included as well.

The following example uses a template without headers and outputs the `Name` and `StarCount` entries separated by a colon (`:`) for all images:

```console
$ docker search --format "{{.Name}}: {{.StarCount}}" nginx

nginx: 5441
jwilder/nginx-proxy: 953
richarvey/nginx-php-fpm: 353
million12/nginx-php: 75
webdevops/php-nginx: 70
h3nrik/nginx-ldap: 35
bitnami/nginx: 23
evild/alpine-nginx: 14
million12/nginx: 9
maxexcloo/nginx: 7
```

This example outputs a table format:

```console
$ docker search --format "table {{.Name}}\t{{.IsOfficial}}" nginx

NAME                                     OFFICIAL
nginx                                    [OK]
jwilder/nginx-proxy
richarvey/nginx-php-fpm
jrcs/letsencrypt-nginx-proxy-companion
million12/nginx-php
webdevops/php-nginx
```

----
url: https://docs.docker.com/engine/extend/plugins_volume/
----

# Docker volume plugins

***

Table of contents

***

Docker Engine volume plugins enable Engine deployments to be integrated with external storage systems such as Amazon EBS, and enable data volumes to persist beyond the lifetime of a single Docker host. See the [plugin documentation](https://docs.docker.com/engine/extend/legacy_plugins/) for more information.

## [Changelog](#changelog)

### [1.13.0](#1130)

* If used as part of the v2 plugin architecture, mountpoints that are part of paths returned by the plugin must be mounted under the directory specified by `PropagatedMount` in the plugin configuration ([#26398](https://github.com/docker/docker/pull/26398))

### [1.12.0](#1120)

* Add `Status` field to `VolumeDriver.Get` response ([#21006](https://github.com/docker/docker/pull/21006#))
* Add `VolumeDriver.Capabilities` to get capabilities of the volume driver ([#22077](https://github.com/docker/docker/pull/22077))

### [1.10.0](#1100)

* Add `VolumeDriver.Get` which gets the details about the volume ([#16534](https://github.com/docker/docker/pull/16534))
* Add `VolumeDriver.List` which lists all volumes owned by the driver ([#16534](https://github.com/docker/docker/pull/16534))

### [1.8.0](#180)

* Initial support for volume driver plugins ([#14659](https://github.com/docker/docker/pull/14659))

## [Command-line changes](#command-line-changes)

To give a container access to a volume, use the `--volume` and `--volume-driver` flags on the `docker container run` command. The `--volume` (or `-v`) flag accepts a volume name and path on the host, and the `--volume-driver` flag accepts a driver type.

```console
$ docker volume create --driver=myplugin volumename

$ docker container run -it --volume volumename:/data busybox sh
```

### [`--volume`](#--volume)

The `--volume` (or `-v`) flag takes a value that is in the format `<volume_name>:<mountpoint>`. The two parts of the value are separated by a colon (`:`) character.

* The volume name is a human-readable name for the volume, and cannot begin with a `/` character. It is referred to as `volume_name` in the rest of this topic.
* The `Mountpoint` is the path on the host (v1) or in the plugin (v2) where the volume has been made available.

### [`--volume-driver`](#--volume-driver)

Specifying the `--volume-driver` flag together with a volume name (using `--volume`) allows you to use plugins to manage volumes for the container.

The `--volume-driver` flag is used as a default for all volumes created for the container, including anonymous volumes. Use the [`--mount`](https://docs.docker.com/reference/cli/docker/container/run/#mount) flag with the [`volume-driver`](https://docs.docker.com/engine/storage/volumes/#start-a-container-which-creates-a-volume-using-a-volume-driver) option to specify the driver to use for each volume individually.

## [Create a VolumeDriver](#create-a-volumedriver)

The container creation endpoint (`/containers/create`) accepts a `VolumeDriver` field of type `string` allowing to specify the name of the driver. If not specified, it defaults to `"local"` (the default driver for local volumes).

## [Volume plugin protocol](#volume-plugin-protocol)

If a plugin registers itself as a `VolumeDriver` when activated, it must provide the Docker Daemon with writeable paths on the host filesystem. The Docker daemon provides these paths to containers to consume. The Docker daemon makes the volumes available by bind-mounting the provided paths into the containers.

> Note
>
> Volume plugins should *not* write data to the `/var/lib/docker/` directory, including `/var/lib/docker/volumes`. The `/var/lib/docker/` directory is reserved for Docker.

### [`/VolumeDriver.Create`](#volumedrivercreate)

Request:

```json
{
    "Name": "volume_name",
    "Opts": {}
}
```

Instruct the plugin that the user wants to create a volume, given a user specified volume name. The plugin does not need to actually manifest the volume on the filesystem yet (until `Mount` is called). `Opts` is a map of driver specific options passed through from the user request.

Response:

```json
{
    "Err": ""
}
```

Respond with a string error if an error occurred.

### [`/VolumeDriver.Remove`](#volumedriverremove)

Request:

```json
{
    "Name": "volume_name"
}
```

Delete the specified volume from disk. This request is issued when a user invokes `docker rm -v` to remove volumes associated with a container.

Response:

```json
{
    "Err": ""
}
```

Respond with a string error if an error occurred.

### [`/VolumeDriver.Mount`](#volumedrivermount)

Request:

```json
{
    "Name": "volume_name",
    "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c"
}
```

Docker requires the plugin to provide a volume, given a user specified volume name. `Mount` is called once per container start. If the same `volume_name` is requested more than once, the plugin may need to keep track of each new mount request and provision at the first mount request and deprovision at the last corresponding unmount request.

`ID` is a unique ID for the caller that is requesting the mount.

Response:

* v1

  ```json
  {
      "Mountpoint": "/path/to/directory/on/host",
      "Err": ""
  }
  ```

* v2

  ```json
  {
      "Mountpoint": "/path/under/PropagatedMount",
      "Err": ""
  }
  ```

`Mountpoint` is the path on the host (v1) or in the plugin (v2) where the volume has been made available.

`Err` is either empty or contains an error string.

### [`/VolumeDriver.Path`](#volumedriverpath)

Request:

```json
{
    "Name": "volume_name"
}
```

Request the path to the volume with the given `volume_name`.

Response:

* v1

  ```json
  {
      "Mountpoint": "/path/to/directory/on/host",
      "Err": ""
  }
  ```

* v2

  ```json
  {
      "Mountpoint": "/path/under/PropagatedMount",
      "Err": ""
  }
  ```

Respond with the path on the host (v1) or inside the plugin (v2) where the volume has been made available, and/or a string error if an error occurred.

`Mountpoint` is optional. However, the plugin may be queried again later if one is not provided.

### [`/VolumeDriver.Unmount`](#volumedriverunmount)

Request:

```json
{
    "Name": "volume_name",
    "ID": "b87d7442095999a92b65b3d9691e697b61713829cc0ffd1bb72e4ccd51aa4d6c"
}
```

Docker is no longer using the named volume. `Unmount` is called once per container stop. Plugin may deduce that it is safe to deprovision the volume at this point.

`ID` is a unique ID for the caller that is requesting the mount.

Response:

```json
{
    "Err": ""
}
```

Respond with a string error if an error occurred.

### [`/VolumeDriver.Get`](#volumedriverget)

Request:

```json
{
    "Name": "volume_name"
}
```

Get info about `volume_name`.

Response:

* v1

  ```json
  {
    "Volume": {
      "Name": "volume_name",
      "Mountpoint": "/path/to/directory/on/host",
      "Status": {}
    },
    "Err": ""
  }
  ```

* v2

  ```json
  {
    "Volume": {
      "Name": "volume_name",
      "Mountpoint": "/path/under/PropagatedMount",
      "Status": {}
    },
    "Err": ""
  }
  ```

Respond with a string error if an error occurred. `Mountpoint` and `Status` are optional.

### [/VolumeDriver.List](#volumedriverlist)

Request:

```json
{}
```

Get the list of volumes registered with the plugin.

Response:

* v1

  ```json
  {
    "Volumes": [
      {
        "Name": "volume_name",
        "Mountpoint": "/path/to/directory/on/host"
      }
    ],
    "Err": ""
  }
  ```

* v2

  ```json
  {
    "Volumes": [
      {
        "Name": "volume_name",
        "Mountpoint": "/path/under/PropagatedMount"
      }
    ],
    "Err": ""
  }
  ```

Respond with a string error if an error occurred. `Mountpoint` is optional.

### [/VolumeDriver.Capabilities](#volumedrivercapabilities)

Request:

```json
{}
```

Get the list of capabilities the driver supports.

The driver is not required to implement `Capabilities`. If it is not implemented, the default values are used.

Response:

```json
{
  "Capabilities": {
    "Scope": "global"
  }
}
```

Supported scopes are `global` and `local`. Any other value in `Scope` will be ignored, and `local` is used. `Scope` allows cluster managers to handle the volume in different ways. For instance, a scope of `global`, signals to the cluster manager that it only needs to create the volume once instead of on each Docker host. More capabilities may be added in the future.

----
url: https://docs.docker.com/docker-hub/repos/manage/access/
----

# Access management

***

Table of contents

***

In this topic learn about the features available to manage access to your repositories. This includes visibility, collaborators, roles, teams, and organization access tokens.

## [Repository visibility](#repository-visibility)

The most basic repository access is controlled via the visibility. A repository's visibility can be public or private.

With public visibility, the repository appears in Docker Hub search results and can be pulled by everyone. To manage push access to public personal repositories, you can use collaborators. To manage push access to public organization repositories, you can use roles, teams, or organization access tokens.

With private visibility, the repository doesn't appear in Docker Hub search results and is only accessible to those with granted permission. To manage push and pull access to private personal repositories, you can use collaborators. To manage push and pull access to private organization repositories, you can use roles, teams, or organization access tokens.

### [Change repository visibility](#change-repository-visibility)

When creating a repository in Docker Hub, you can set the repository visibility. In addition, you can set the default repository visibility when a repository is created in your personal repository settings. The following describes how to change the visibility after the repository has been created.

To change repository visibility:

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Settings** tab.

5. Under **Visibility settings**, select one of the following:

   * **Make public**: The repository appears in Docker Hub search results and can be pulled by everyone.
   * **Make private**: The repository doesn't appear in Docker Hub search results and is only accessible to you and collaborators. In addition, if the repository is in an organization's namespace, then the repository is accessible to those with applicable roles or permissions.

6. Type the repository's name to verify the change.

7. Select **Make public** or **Make private**.

## [Collaborators](#collaborators)

A collaborator is someone you want to give `push` and `pull` access to a personal repository. Collaborators aren't able to perform any administrative tasks such as deleting the repository or changing its visibility from private to public. In addition, collaborators can't add other collaborators.

Only personal repositories can use collaborators. You can add unlimited collaborators to public repositories, and Docker Pro accounts can add up to 1 collaborator on private repositories.

Organization repositories can't use collaborators, but can use member roles, teams, or organization access tokens to manage access.

### [Manage collaborators](#manage-collaborators)

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Collaborators** tab.

5. Add or remove collaborators based on their Docker username.

You can choose collaborators and manage their access to a private repository from that repository's **Settings** page.

## [Organization roles](#organization-roles)

Organizations can use roles for individuals, giving them different permissions in the organization. For more details, see [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/).

## [Organization teams](#organization-teams)

Organizations can use teams. A team can be assigned fine-grained repository access.

### [Configure team repository permissions](#configure-team-repository-permissions)

You must create a team before you are able to configure repository permissions. For more details, see [Create and manage a team](https://docs.docker.com/admin/organization/manage/manage-a-team/).

To configure team repository permissions:

## [Organization access tokens (OATs)](#organization-access-tokens-oats)

Organizations can use OATs. OATs let you assign fine-grained repository access permissions to tokens. For more details, see [Organization access tokens](https://docs.docker.com/enterprise/security/access-tokens/).

## [Gated distribution](#gated-distribution)

Availability: Early Access

Gated distribution allows publishers to securely share private container images with external customers or partners, without giving them full organization access or visibility into your teams, collaborators, or other repositories.

This feature is ideal for commercial software publishers who want to control who can pull specific images while preserving a clean separation between internal users and external consumers.

If you are interested in Gated Distribution contact the [Docker Sales Team](https://www.docker.com/pricing/contact-sales/) for more information.

### [Key features](#key-features)

* **Private repository distribution**: Content is stored in private repositories and only accessible to explicitly invited users.

* **External access without organization membership**: External users don't need to be added to your internal organization to pull images.

* **Pull-only permissions**: External users receive pull-only access and cannot push or modify repository content.

* **Invite-only access**: Access is granted through authenticated email invites, managed via API.

### [Invite distributor members via API](#invite-distributor-members-via-api)

> Note
>
> When you invite members, you assign them a role. See [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/) for details about the access permissions for each role.

Distributor members (used for gated distribution) can only be invited using the Docker Hub API. UI-based invitations are not currently supported for this role. To invite distributor members, use the Bulk create invites API endpoint.

To invite distributor members:

1. Use the [Authentication API](https://docs.docker.com/reference/api/hub/latest/#tag/authentication-api/operation/AuthCreateAccessToken) to generate a bearer token for your Docker Hub account.

2. Create a team in the Hub UI or use the [Teams API](https://docs.docker.com/reference/api/hub/latest/#tag/groups/paths/~1v2~1orgs~1%7Borg_name%7D~1groups/post).

3. Grant repository access to the team:

   * In the Hub UI: Navigate to your repository settings and add the team with "Read-only" permissions
   * Using the [Repository Teams API](https://docs.docker.com/reference/api/hub/latest/#tag/repositories/paths/~1v2~1repositories~1%7Bnamespace%7D~1%7Brepository%7D~1groups/post): Assign the team to your repositories with "read-only" access level

4. Use the [Bulk create invites endpoint](https://docs.docker.com/reference/api/hub/latest/#tag/invites/paths/~1v2~1invites~1bulk/post) to send email invites with the distributor member role. In the request body, set the "role" field to "distributor\_member".

5. The invited user will receive an email with a link to accept the invite. After signing in with their Docker ID, they'll be granted pull-only access to the specified private repository as a distributor member.

----
url: https://docs.docker.com/compose/how-tos/networking/
----

# Networking in Compose

***

Table of contents

***

Compose handles networking for you by default, but gives you fine-grained control when you need it. This page explains how the default network works and how containers discover each other by name. It also covers when and how to define custom networks, connect services across separate Compose projects, map custom hostnames, and debug connectivity issues.

## [Default network and service discovery](#default-network-and-service-discovery)

By default, Compose sets up a single [network](/reference/cli/docker/network/create/) for your app. Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by its service name. This network uses the `bridge` driver. To understand when you'd use a different driver, see [Network drivers: bridge vs host](#change-the-network-mode).

For most development setups, the default network is sufficient. When you run `docker compose up`, Compose creates a network named `<project-name>_default` and attaches all services to it. Each service registers its name with an internal DNS server, so containers can reach each other using the service name directly. No IP addresses or manual configuration is needed.

For example, suppose your app is in a directory called `myapp`, and your `compose.yaml` looks like this:

```yaml
services:
  web:
    build: .
    ports:
      - "8000:8000"
  db:
    image: postgres:latest
    ports:
      - "8001:5432"
```

Compose automatically connects all services to the default network, so you don't need to define `networks` explicitly in the Compose file.

When you run `docker compose up`, the following happens:

1. A network called `myapp_default` is created.
2. A container is created using `web`'s configuration. It joins `myapp_default` under the name `web`.
3. A container is created using `db`'s configuration. It joins `myapp_default` under the name `db`.

Each container can now look up the service name `web` or `db` and get back the appropriate container's IP address. The `web` service can connect to the database at `postgres://db:5432`. From the host machine, the same database is accessible at `postgres://localhost:8001` if your container is running locally.

> Tip
>
> Docker assigns container IP addresses dynamically from the network's subnet each time a container starts so they are not persisted across restarts or recreations. This means you should always reference services by name, not IP address. When containers are recreated, for example after a configuration change, they receive a new IP address. The service name stays stable.

Your app's network is given a name based on the "project name", which is taken from the name of the directory it lives in. You can override the project name with either the [`--project-name` flag](/reference/cli/docker/compose/) or the [`COMPOSE_PROJECT_NAME` environment variable](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_project_name).

The `HOST_PORT` and `CONTAINER_PORT` serve different purposes. In the example above, for `db`, the `HOST_PORT` is `8001` and the container port is `5432` (the Postgres default). Networked service-to-service communication uses the `CONTAINER_PORT`. The host port is only used when accessing the service from outside the network.

### [Updating containers on the network](#updating-containers-on-the-network)

If you make a configuration change to a service and run `docker compose up` to update it, the old container is removed and the new one joins the network under a different IP address but the same name. Running containers can look up that name and connect to the new address, but the old address stops working.

If any containers have connections open to the old container, they are closed. It is each container's responsibility to detect this condition, look up the name again, and reconnect.

## [Change the network mode](#change-the-network-mode)

By default, each service joins the project's bridge network. It is the most secure networking mode. If you don't specify [`network_mode`](https://docs.docker.com/reference/compose-file/services/#network_mode), this is the type of network you are creating.

You can override the networking mode on a per-service basis. The `network_mode` option accepts the following values:

* `host`: The container shares the host's network stack. No port mapping is needed or supported, and service name DNS resolution does not work. Use for system-level tools like network monitors that require direct access to host interfaces. A container using `network_mode: host` can access all host ports and observe all network traffic on the host. Use it only when genuinely required.
* `none`: Turns off all container networking.
* `service:{name}`: Gives the container access to the specified container by referring to its service name.
* `container:{name}`: Gives the container access to the specified container by referring to its container ID.

You can mix modes in a single project:

```yaml
services:
  app:
    image: myapp
    networks:
      - isolated
    ports:
      - "3000:3000"

  monitoring:
    image: netdata/netdata
    network_mode: host   # Can monitor host system and all host ports

networks:
  isolated:
    driver: bridge
```

## [Specify custom networks](#specify-custom-networks)

Instead of just using the default app network, you can specify your own networks with the top-level `networks` key. This lets you create more complex topologies and specify [custom network drivers](/engine/extend/plugins_network/) and options. You can also use it to connect services to externally-created networks which aren't managed by Compose.

Each service can specify what networks to connect to with the service-level `networks` key, which is a list of names referencing entries under the top-level `networks` key.

The following example shows a Compose file which defines two custom networks. The `proxy` service is isolated from the `db` service, because they do not share a network in common. Only `app` can talk to both.

```yaml
services:
  proxy:
    build: ./proxy
    networks:
      - frontend
  app:
    build: ./app
    networks:
      - frontend
      - backend
  db:
    image: postgres:latest
    networks:
      - backend

networks:
  frontend:
    driver: bridge   # Specify driver options
    driver_opts:
      com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"
  backend:
    driver: custom-driver  # Use a custom driver
```

Networks can be configured with static IP addresses by setting the [ipv4\_address and/or ipv6\_address](https://docs.docker.com/reference/compose-file/services/#ipv4_address-ipv6_address) for each attached network.

Networks can also be given a [custom name](https://docs.docker.com/reference/compose-file/networks/#name):

```yaml
services:
  # ...
networks:
  frontend:
    name: custom_frontend
    driver: custom-driver-1
```

### [Internal networks](#internal-networks)

Setting `internal: true` on a network creates it without a connection to the host's network interfaces. It has no default gateway for external connectivity. This is useful for services like databases that should be completely unreachable from outside the container network:

```yaml
services:
  cache:
    image: redis
    networks:
      - isolated

  worker:
    image: myworker
    networks:
      - isolated
      - public

networks:
  isolated:
    internal: true   # No external connectivity
  public:   # Standard bridge network, created by Compose on docker compose up
```

Note that a service connected to both an internal and a non-internal network (like `worker` above) can still reach the internet via the non-internal network `public`.

### [Configure the default network](#configure-the-default-network)

Instead of, or as well as, specifying your own networks, you can also change the settings of the app-wide default network by defining an entry under `networks` named `default`:

```yaml
services:
  web:
    build: .
    ports:
      - "8000:8000"
  db:
    image: postgres:latest

networks:
  default:
    driver: custom-driver-1   # Use a custom driver
```

## [Use an existing external network](#use-an-existing-external-network)

If you've manually created a bridge network using `docker network create`, you can connect your Compose services to it by marking the network as [`external`](https://docs.docker.com/reference/compose-file/networks/#external):

```yaml
services:
  # ...
networks:
  network1:
    name: my-pre-existing-network
    external: true
```

Instead of creating `<project-name>_default`, Compose looks for a network called `my-pre-existing-network` and connects your containers to it.

### [Connecting multiple Compose projects](#connecting-multiple-compose-projects)

External networks are particularly useful when services in separate Compose projects need to communicate. Create a shared network once, then reference it as external in each project:

```bash
docker network create inter-project
```

backend-compose.yaml:

```yaml
services:
  api:
    image: myapi:latest
    networks:
      - shared
      - default   # Also keep the project's internal network

networks:
  shared:
    external: true
    name: inter-project
```

frontend-compose.yaml:

```yaml
services:
  web:
    image: myfrontend:latest
    environment:
      API_URL: http://api:8080   # Reference by service name
    networks:
      - shared

networks:
  shared:
    external: true
    name: inter-project
```

Services on the same external network can reach each other by service name, just like services within a single project.

> Important
>
> The external network must exist before you run `docker compose up`. If it doesn't, Compose fails with a `Network not found` error. Always create it first with `docker network create`.

## [Hybrid networking](#hybrid-networking)

A service can belong to both an external shared network and its own project-internal network. This lets you expose only the services that need to be reachable from other projects, while keeping everything else, such as databases, fully isolated:

```yaml
services:
  api:
    image: myapp-api
    networks:
      - shared     # Reachable from other projects
      - internal   # Can also reach the database

  database:
    image: postgres:latest
    networks:
      - internal   # Not exposed on the shared network

networks:
  shared:
    name: inter-project
    external: true
  internal: {}     # Project-specific, isolated
```

## [Custom DNS with `extra_hosts`](#custom-dns-with-extra_hosts)

You can add custom hostname-to-IP mappings to a container's `/etc/hosts` file using [`extra_hosts`](https://docs.docker.com/reference/compose-file/services/#extra_hosts). This is useful when a service needs to resolve a hostname that isn't registered in Docker's internal DNS. For example, a fixed-IP dependency or a staging endpoint:

```yaml
services:
  app:
    image: myapp
    extra_hosts:
      - "api.staging:192.168.1.100"
      - "cache.internal:192.168.1.101"
```

To map a hostname dynamically to the host machine's IP, use the special `host-gateway` value:

```yaml
services:
  app:
    image: myapp
    extra_hosts:
      - "host.docker.internal:host-gateway"
```

On Linux, `host-gateway` resolves to the host's IP on the default bridge network. On Mac and Windows, Docker automatically provides this, `host-gateway` resolves to the same internal IP address as `host.docker.internal`.

You can also drive `extra_hosts` from environment variables, which makes it easy to point services at different targets per environment:

```yaml
services:
  app:
    image: myapp
    extra_hosts:
      - "api.service:${API_HOST:-127.0.0.1}"
      - "auth.service:${AUTH_HOST:-127.0.0.1}"
```

Where `.env.development` might set `API_HOST=localhost` and a production env file might set `API_HOST=10.0.1.50`.

To verify what has been injected, inspect the hosts file inside the container:

```bash
$ docker compose exec app cat /etc/hosts
```

## [Multi-host networking](#multi-host-networking)

When deploying a Compose application on a Docker Engine with [Swarm mode enabled](https://docs.docker.com/engine/swarm/), you can use the built-in `overlay` driver to enable multi-host communication. Overlay networks are always created as `attachable`. You can optionally set the [`attachable`](https://docs.docker.com/reference/compose-file/networks/#attachable) property to `false`.

To learn more, see the [overlay network driver documentation](https://docs.docker.com/engine/network/drivers/overlay/).

## [Link containers](#link-containers)

Links allow you to define extra aliases by which a service is reachable from another service. They are not required for basic service-to-service communication. By default, any service can reach any other service at that service's name. In the following example, `db` is reachable from `web` at both the hostnames `db` and `database`:

```yaml
services:
  web:
    build: .
    links:
      - "db:database"
  db:
    image: postgres:latest
```

See the [links reference](https://docs.docker.com/reference/compose-file/services/#links) for more information.

## [Debugging](#debugging)

When a service can't reach another, work through the following steps in order: first confirm the network configuration looks right, then confirm the containers are actually attached, then test live connectivity.

### [Inspect port mappings](#inspect-port-mappings)

To find out which host port maps to a container port, use `docker compose port`:

```bash
# Which host port maps to container port 5432 on db?
$ docker compose port db 5432
# Output: 0.0.0.0:8001
```

This is especially useful when using dynamic port mapping, where the host port changes on every `docker compose up`:

```yaml
services:
  web:
    image: nginx
    ports:
      - "80"   # Docker assigns the host port dynamically
```

```bash
$ docker compose port web 80
# Output: 0.0.0.0:55432
```

When you scale a service, each replica gets its own dynamic port. Use `--index` to query a specific replica:

```bash
$ docker compose up -d --scale web=3

$ docker compose port --index=1 web 80   # Output: 0.0.0.0:55001
$ docker compose port --index=2 web 80   # Output: 0.0.0.0:55002
$ docker compose port --index=3 web 80   # Output: 0.0.0.0:55003
```

By default, `docker compose port` looks for TCP mappings. If a service exposes both TCP and UDP on the same port, use `--protocol`:

```bash
$ docker compose port --protocol=udp myservice 53
```

### [Verify network membership](#verify-network-membership)

To check which containers are attached to a network (useful when troubleshooting connectivity across external or custom networks):

```bash
$ docker network inspect <network-name>
```

### [Check connectivity](#check-connectivity)

If the network membership looks correct but services still can't reach each other, test connectivity from inside a running container using `docker compose exec`.

## [Further reference information](#further-reference-information)

For full details of the network configuration options available, see the following references:

* [Top-level `networks` element](https://docs.docker.com/reference/compose-file/networks/)
* [Service-level `networks` attribute](https://docs.docker.com/reference/compose-file/services/#networks)

----
url: https://docs.docker.com/scout/integrations/ci/
----

# Using Docker Scout in continuous integration

***

***

You can analyze Docker images in continuous integration pipelines as you build them using a GitHub action or the Docker Scout CLI plugin.

Available integrations:

* [GitHub Actions](https://docs.docker.com/scout/integrations/ci/gha/)
* [GitLab](https://docs.docker.com/scout/integrations/ci/gitlab/)
* [Microsoft Azure DevOps Pipelines](https://docs.docker.com/scout/integrations/ci/azure/)
* [Circle CI](https://docs.docker.com/scout/integrations/ci/circle-ci/)
* [Jenkins](https://docs.docker.com/scout/integrations/ci/jenkins/)

You can also add runtime integration as part of your CI/CD pipeline, which lets you assign an image to an environment, such as `production` or `staging`, when you deploy it. For more information, see [Environment monitoring](https://docs.docker.com/scout/integrations/environment/).

----
url: https://docs.docker.com/guides/golang/
----

# Go language-specific guide

Table of contents

***

This guide teaches you how to containerize Go applications using Docker.

**Time to complete** 30 minutes

This guide will show you how to create, test, and deploy containerized Go applications using Docker.

> **Acknowledgment**
>
> Docker would like to thank [Oliver Frolovs](https://www.linkedin.com/in/ofr/) for his contribution to this guide.

## [What will you learn?](#what-will-you-learn)

In this guide, you’ll learn how to:

* Create a `Dockerfile` which contains the instructions for building a container image for a program written in Go.
* Run the image as a container in your local Docker instance and manage the container's lifecycle.
* Use multi-stage builds for building small images efficiently while keeping your Dockerfiles easy to read and maintain.
* Use Docker Compose to orchestrate running of multiple related containers together in a development environment.
* Configure a CI/CD pipeline for your application using [GitHub Actions](https://docs.github.com/en/actions)
* Deploy your containerized Go application.

## [Prerequisites](#prerequisites)

Some basic understanding of Go and its toolchain is assumed. This isn't a Go tutorial. If you are new to the : languages:, the [Go website](https://golang.org/) is a great place to explore, so *go* (pun intended) check it out!

You also must know some basic [Docker concepts](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) as well as to be at least vaguely familiar with the [Dockerfile format](https://docs.docker.com/build/concepts/dockerfile/).

Your Docker set-up must have BuildKit enabled. BuildKit is enabled by default for all users on [Docker Desktop](https://docs.docker.com/desktop/). If you have installed Docker Desktop, you don’t have to manually enable BuildKit. If you are running Docker on Linux, please check out BuildKit [getting started](https://docs.docker.com/build/buildkit/#getting-started) page.

Some familiarity with the command line is also expected.

## [What's next?](#whats-next)

The aim of this guide is to provide enough examples and instructions for you to containerize your own Go application and deploy it into the Cloud.

Start by building your first Go image.

## [Modules](#modules)

1. [Build images](https://docs.docker.com/guides/golang/build-images/)

   Learn how to build your first Docker image by writing a Dockerfile

2. [Run containers](https://docs.docker.com/guides/golang/run-containers/)

   Learn how to run the image as a container.

3. [Develop your app](https://docs.docker.com/guides/golang/develop/)

   Learn how to develop your application locally.

4. [Run your tests](https://docs.docker.com/guides/golang/run-tests/)

   How to build and run your Go tests in a container

5. [Configure CI/CD](https://docs.docker.com/guides/golang/configure-ci-cd/)

   Learn how to Configure CI/CD for your Go application

6. [Test your deployment](https://docs.docker.com/guides/golang/deploy/)

   Learn how to deploy your Go application

----
url: https://docs.docker.com/extensions/extensions-sdk/dev/api/dashboard-routes-navigation/
----

# Navigation

***

Table of contents

***

`ddClient.desktopUI.navigate` enables navigation to specific screens of Docker Desktop such as the containers tab, the images tab, or a specific container's logs.

For example, navigate to a given container logs:

```typescript
const id = '8c7881e6a107';
try {
  await ddClient.desktopUI.navigate.viewContainerLogs(id);
} catch (e) {
  console.error(e);
  ddClient.desktopUI.toast.error(
    `Failed to navigate to logs for container "${id}".`
  );
}
```

#### [Parameters](#parameters)

| Name | Type     | Description                                                                                                                                                                                            |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |

#### [Returns](#returns)

`Promise`<`void`>

A promise that fails if the container doesn't exist.

For more details about all navigation methods, see the [Navigation API reference](https://docs.docker.com/reference/api/extensions-sdk/NavigationIntents/).

> Deprecated navigation methods
>
> These methods are deprecated and will be removed in a future version. Use the methods specified above.

```typescript
window.ddClient.navigateToContainers();
// id - the full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`
window.ddClient.navigateToContainer(id);
window.ddClient.navigateToContainerLogs(id);
window.ddClient.navigateToContainerInspect(id);
window.ddClient.navigateToContainerStats(id);

window.ddClient.navigateToImages();
window.ddClient.navigateToImage(id, tag);

window.ddClient.navigateToVolumes();
window.ddClient.navigateToVolume(volume);

window.ddClient.navigateToDevEnvironments();
```

----
url: https://docs.docker.com/ai-overview/
----

# Docker AI overview

***

Table of contents

***

Docker provides tools for working with AI across your development workflow. Each tool serves a different purpose.

## [Which tool do I need?](#which-tool-do-i-need)

| I want to...                                                    | Use                                                                            | CLI command      |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------- |
| Get AI help with Docker tasks (containers, images, Dockerfiles) | [Gordon](https://docs.docker.com/ai/gordon/)                                   | `docker ai`      |
| Run AI models locally with an OpenAI-compatible API             | [Model Runner](https://docs.docker.com/ai/model-runner/)                       | `docker model`   |
| Connect AI tools to external services via MCP                   | [MCP Catalog and Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/) | `docker mcp`     |
| Build and orchestrate custom multi-agent teams                  | [Docker Agent](https://docs.docker.com/ai/docker-agent/)                       | `docker agent`   |
| Run coding agents in isolated environments                      | [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/)                      | `docker sandbox` |

## [How these tools relate](#how-these-tools-relate)

**Gordon** is Docker's built-in AI assistant. It helps with Docker-specific tasks like debugging containers, writing Dockerfiles, and managing images. You interact with it through Docker Desktop or the `docker ai` command.

**Docker Agent** is an open-source framework for defining teams of AI agents in YAML. You configure agents with specific roles, models, and tools, then run them from your terminal. Docker Agent is a general-purpose agent runtime, not specific to Docker tasks.

**Docker Sandboxes** provides isolated microVM environments for running coding agents. It supports multiple agents including Claude Code, Codex, Copilot, Gemini, and Docker Agent. Sandboxes is the isolation layer — the agents themselves are separate tools.

**Model Runner** lets you run LLMs locally. Other tools like Docker Agent can use Model Runner as a model provider.

**MCP Catalog and Toolkit** manages connections between AI tools and external services using the Model Context Protocol. Gordon, Docker Agent, and third-party tools can all use MCP servers configured through the Toolkit.

----
url: https://docs.docker.com/reference/cli/docker/container/create/
----

# docker container create

***

| Description                                                               | Create a new container                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Usage                                                                     | `docker container create [OPTIONS] IMAGE [COMMAND] [ARG...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker create`                                              |

## [Description](#description)

The `docker container create` (or shorthand: `docker create`) command creates a new container from the specified image, without starting it.

When creating a container, the Docker daemon creates a writeable container layer over the specified image and prepares it for running the specified command. The container ID is then printed to `STDOUT`. This is similar to `docker run -d` except the container is never started. You can then use the `docker container start` (or shorthand: `docker start`) command to start the container at any point.

This is useful when you want to set up a container configuration ahead of time so that it's ready to start when you need it. The initial status of the new container is `created`.

The `docker create` command shares most of its options with the `docker run` command (which performs a `docker create` before starting it). Refer to the [`docker run` CLI reference](/reference/cli/docker/container/run/) for details on the available flags and options.

## [Options](#options)

| Option                    | Default   | Description                                                                                                                                                                                                                                                                               |
| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--add-host`              |           | Add a custom host-to-IP mapping (host:ip)                                                                                                                                                                                                                                                 |
| `--annotation`            |           | API 1.43+ Add an annotation to the container (passed through to the OCI runtime)                                                                                                                                                                                                          |
| `-a, --attach`            |           | Attach to STDIN, STDOUT or STDERR                                                                                                                                                                                                                                                         |
| `--blkio-weight`          |           | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0)                                                                                                                                                                                                              |
| `--blkio-weight-device`   |           | Block IO weight (relative device weight)                                                                                                                                                                                                                                                  |
| `--cap-add`               |           | Add Linux capabilities                                                                                                                                                                                                                                                                    |
| `--cap-drop`              |           | Drop Linux capabilities                                                                                                                                                                                                                                                                   |
| `--cgroup-parent`         |           | Optional parent cgroup for the container                                                                                                                                                                                                                                                  |
| `--cgroupns`              |           | API 1.41+ Cgroup namespace to use (host\|private) 'host': Run the container in the Docker host's cgroup namespace 'private': Run the container in its own private cgroup namespace '': Use the cgroup namespace as configured by the default-cgroupns-mode option on the daemon (default) |
| `--cidfile`               |           | Write the container ID to the file                                                                                                                                                                                                                                                        |
| `--cpu-count`             |           | CPU count (Windows only)                                                                                                                                                                                                                                                                  |
| `--cpu-percent`           |           | CPU percent (Windows only)                                                                                                                                                                                                                                                                |
| `--cpu-period`            |           | Limit CPU CFS (Completely Fair Scheduler) period                                                                                                                                                                                                                                          |
| `--cpu-quota`             |           | Limit CPU CFS (Completely Fair Scheduler) quota                                                                                                                                                                                                                                           |
| `--cpu-rt-period`         |           | API 1.25+ Limit CPU real-time period in microseconds                                                                                                                                                                                                                                      |
| `--cpu-rt-runtime`        |           | API 1.25+ Limit CPU real-time runtime in microseconds                                                                                                                                                                                                                                     |
| `-c, --cpu-shares`        |           | CPU shares (relative weight)                                                                                                                                                                                                                                                              |
| `--cpus`                  |           | API 1.25+ Number of CPUs                                                                                                                                                                                                                                                                  |
| `--cpuset-cpus`           |           | CPUs in which to allow execution (0-3, 0,1)                                                                                                                                                                                                                                               |
| `--cpuset-mems`           |           | MEMs in which to allow execution (0-3, 0,1)                                                                                                                                                                                                                                               |
| `--device`                |           | Add a host device to the container                                                                                                                                                                                                                                                        |
| `--device-cgroup-rule`    |           | Add a rule to the cgroup allowed devices list                                                                                                                                                                                                                                             |
| `--device-read-bps`       |           | Limit read rate (bytes per second) from a device                                                                                                                                                                                                                                          |
| `--device-read-iops`      |           | Limit read rate (IO per second) from a device                                                                                                                                                                                                                                             |
| `--device-write-bps`      |           | Limit write rate (bytes per second) to a device                                                                                                                                                                                                                                           |
| `--device-write-iops`     |           | Limit write rate (IO per second) to a device                                                                                                                                                                                                                                              |
| `--dns`                   |           | Set custom DNS servers                                                                                                                                                                                                                                                                    |
| `--dns-option`            |           | Set DNS options                                                                                                                                                                                                                                                                           |
| `--dns-search`            |           | Set custom DNS search domains                                                                                                                                                                                                                                                             |
| `--domainname`            |           | Container NIS domain name                                                                                                                                                                                                                                                                 |
| `--entrypoint`            |           | Overwrite the default ENTRYPOINT of the image                                                                                                                                                                                                                                             |
| `-e, --env`               |           | Set environment variables                                                                                                                                                                                                                                                                 |
| `--env-file`              |           | Read in a file of environment variables                                                                                                                                                                                                                                                   |
| `--expose`                |           | Expose a port or a range of ports                                                                                                                                                                                                                                                         |
| `--gpus`                  |           | API 1.40+ GPU devices to add to the container ('all' to pass all GPUs)                                                                                                                                                                                                                    |
| `--group-add`             |           | Add additional groups to join                                                                                                                                                                                                                                                             |
| `--health-cmd`            |           | Command to run to check health                                                                                                                                                                                                                                                            |
| `--health-interval`       |           | Time between running the check (ms\|s\|m\|h) (default 0s)                                                                                                                                                                                                                                 |
| `--health-retries`        |           | Consecutive failures needed to report unhealthy                                                                                                                                                                                                                                           |
| `--health-start-interval` |           | API 1.44+ Time between running the check during the start period (ms\|s\|m\|h) (default 0s)                                                                                                                                                                                               |
| `--health-start-period`   |           | API 1.29+ Start period for the container to initialize before starting health-retries countdown (ms\|s\|m\|h) (default 0s)                                                                                                                                                                |
| `--health-timeout`        |           | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s)                                                                                                                                                                                                                         |
| `--help`                  |           | Print usage                                                                                                                                                                                                                                                                               |
| `-h, --hostname`          |           | Container host name                                                                                                                                                                                                                                                                       |
| `--init`                  |           | API 1.25+ Run an init inside the container that forwards signals and reaps processes                                                                                                                                                                                                      |
| `-i, --interactive`       |           | Keep STDIN open even if not attached                                                                                                                                                                                                                                                      |
| `--io-maxbandwidth`       |           | Maximum IO bandwidth limit for the system drive (Windows only)                                                                                                                                                                                                                            |
| `--io-maxiops`            |           | Maximum IOps limit for the system drive (Windows only)                                                                                                                                                                                                                                    |
| `--ip`                    | ``        | IPv4 address (e.g., 172.30.100.104)                                                                                                                                                                                                                                                       |
| `--ip6`                   | ``        | IPv6 address (e.g., 2001:db8::33)                                                                                                                                                                                                                                                         |
| `--ipc`                   |           | IPC mode to use                                                                                                                                                                                                                                                                           |
| `--isolation`             |           | Container isolation technology                                                                                                                                                                                                                                                            |
| `-l, --label`             |           | Set meta data on a container                                                                                                                                                                                                                                                              |
| `--label-file`            |           | Read in a line delimited file of labels                                                                                                                                                                                                                                                   |
| `--link`                  |           | Add link to another container                                                                                                                                                                                                                                                             |
| `--link-local-ip`         |           | Container IPv4/IPv6 link-local addresses                                                                                                                                                                                                                                                  |
| `--log-driver`            |           | Logging driver for the container                                                                                                                                                                                                                                                          |
| `--log-opt`               |           | Log driver options                                                                                                                                                                                                                                                                        |
| `--mac-address`           |           | Container MAC address (e.g., 92:d0:c6:0a:29:33)                                                                                                                                                                                                                                           |
| `-m, --memory`            |           | Memory limit                                                                                                                                                                                                                                                                              |
| `--memory-reservation`    |           | Memory soft limit                                                                                                                                                                                                                                                                         |
| `--memory-swap`           |           | Swap limit equal to memory plus swap: '-1' to enable unlimited swap                                                                                                                                                                                                                       |
| `--memory-swappiness`     | `-1`      | Tune container memory swappiness (0 to 100)                                                                                                                                                                                                                                               |
| `--mount`                 |           | Attach a filesystem mount to the container                                                                                                                                                                                                                                                |
| `--name`                  |           | Assign a name to the container                                                                                                                                                                                                                                                            |
| `--network`               |           | Connect a container to a network                                                                                                                                                                                                                                                          |
| `--network-alias`         |           | Add network-scoped alias for the container                                                                                                                                                                                                                                                |
| `--no-healthcheck`        |           | Disable any container-specified HEALTHCHECK                                                                                                                                                                                                                                               |
| `--oom-kill-disable`      |           | Disable OOM Killer                                                                                                                                                                                                                                                                        |
| `--oom-score-adj`         |           | Tune host's OOM preferences (-1000 to 1000)                                                                                                                                                                                                                                               |
| `--pid`                   |           | PID namespace to use                                                                                                                                                                                                                                                                      |
| `--pids-limit`            |           | Tune container pids limit (set -1 for unlimited)                                                                                                                                                                                                                                          |
| `--platform`              |           | API 1.32+ Set platform if server is multi-platform capable                                                                                                                                                                                                                                |
| `--privileged`            |           | Give extended privileges to this container                                                                                                                                                                                                                                                |
| `-p, --publish`           |           | Publish a container's port(s) to the host                                                                                                                                                                                                                                                 |
| `-P, --publish-all`       |           | Publish all exposed ports to random ports                                                                                                                                                                                                                                                 |
| `--pull`                  | `missing` | Pull image before creating (`always`, `\|missing`, `never`)                                                                                                                                                                                                                               |
| `-q, --quiet`             |           | Suppress the pull output                                                                                                                                                                                                                                                                  |
| `--read-only`             |           | Mount the container's root filesystem as read only                                                                                                                                                                                                                                        |
| `--restart`               | `no`      | Restart policy to apply when a container exits                                                                                                                                                                                                                                            |
| `--rm`                    |           | Automatically remove the container and its associated anonymous volumes when it exits                                                                                                                                                                                                     |
| `--runtime`               |           | Runtime to use for this container                                                                                                                                                                                                                                                         |
| `--security-opt`          |           | Security Options                                                                                                                                                                                                                                                                          |
| `--shm-size`              |           | Size of /dev/shm                                                                                                                                                                                                                                                                          |
| `--stop-signal`           |           | Signal to stop the container                                                                                                                                                                                                                                                              |
| `--stop-timeout`          |           | API 1.25+ Timeout (in seconds) to stop a container                                                                                                                                                                                                                                        |
| `--storage-opt`           |           | Storage driver options for the container                                                                                                                                                                                                                                                  |
| `--sysctl`                |           | Sysctl options                                                                                                                                                                                                                                                                            |
| `--tmpfs`                 |           | Mount a tmpfs directory                                                                                                                                                                                                                                                                   |
| `-t, --tty`               |           | Allocate a pseudo-TTY                                                                                                                                                                                                                                                                     |
| `--ulimit`                |           | Ulimit options                                                                                                                                                                                                                                                                            |
| `--use-api-socket`        |           | experimental (CLI) Bind mount Docker API socket and required auth                                                                                                                                                                                                                         |
| `-u, --user`              |           | Username or UID (format: \<name\|uid>\[:\<group\|gid>])                                                                                                                                                                                                                                   |
| `--userns`                |           | User namespace to use                                                                                                                                                                                                                                                                     |
| `--uts`                   |           | UTS namespace to use                                                                                                                                                                                                                                                                      |
| `-v, --volume`            |           | Bind mount a volume                                                                                                                                                                                                                                                                       |
| `--volume-driver`         |           | Optional volume driver for the container                                                                                                                                                                                                                                                  |
| `--volumes-from`          |           | Mount volumes from the specified container(s)                                                                                                                                                                                                                                             |
| `-w, --workdir`           |           | Working directory inside the container                                                                                                                                                                                                                                                    |

## [Examples](#examples)

### [Create and start a container](#create-and-start-a-container)

The following example creates an interactive container with a pseudo-TTY attached, then starts the container and attaches to it:

```console
$ docker container create -i -t --name mycontainer alpine
6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752

$ docker container start --attach -i mycontainer
/ # echo hello world
hello world
```

The above is the equivalent of a `docker run`:

```console
$ docker run -it --name mycontainer2 alpine
/ # echo hello world
hello world
```

### [Initialize volumes](#initialize-volumes)

Container volumes are initialized during the `docker create` phase (i.e., `docker run` too). For example, this allows you to `create` the `data` volume container, and then use it from another container:

```console
$ docker create -v /data --name data ubuntu

240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57

$ docker run --rm --volumes-from data ubuntu ls -la /data

total 8
drwxr-xr-x  2 root root 4096 Dec  5 04:10 .
drwxr-xr-x 48 root root 4096 Dec  5 04:11 ..
```

Similarly, `create` a host directory bind mounted volume container, which can then be used from the subsequent container:

```console
$ docker create -v /home/docker:/docker --name docker ubuntu

9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03

$ docker run --rm --volumes-from docker ubuntu ls -la /docker

total 20
drwxr-sr-x  5 1000 staff  180 Dec  5 04:00 .
drwxr-xr-x 48 root root  4096 Dec  5 04:13 ..
-rw-rw-r--  1 1000 staff 3833 Dec  5 04:01 .ash_history
-rw-r--r--  1 1000 staff  446 Nov 28 11:51 .ashrc
-rw-r--r--  1 1000 staff   25 Dec  5 04:00 .gitconfig
drwxr-sr-x  3 1000 staff   60 Dec  1 03:28 .local
-rw-r--r--  1 1000 staff  920 Nov 28 11:51 .profile
drwx--S---  2 1000 staff  460 Dec  5 00:51 .ssh
drwxr-xr-x 32 1000 staff 1140 Dec  5 04:01 docker
```

----
url: https://docs.docker.com/guides/vuejs/containerize/
----

# Containerize an Vue.js Application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Before you begin, make sure the following tools are installed and available on your system:

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client.

> **New to Docker?**\
> Start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide to get familiar with key concepts like images, containers, and Dockerfiles.

***

## [Overview](#overview)

This guide walks you through the complete process of containerizing an Vue.js application with Docker. You’ll learn how to create a production-ready Docker image using best practices that improve performance, security, scalability, and deployment efficiency.

By the end of this guide, you will:

* Containerize an Vue.js application using Docker.
* Create and optimize a Dockerfile for production builds.
* Use multi-stage builds to minimize image size.
* Serve the application efficiently with a custom Nginx configuration.
* Build secure and maintainable Docker images by following best practices.

***

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, navigate to the directory where you want to work, and run the following command to clone the git repository:

```console
$ git clone https://github.com/kristiyan-velkov/docker-vuejs-sample
```

***

## [Build the Docker image](#build-the-docker-image)

Vue.js is a front-end framework that compiles into static assets, so the Dockerfile is customized to align with how Vue.js applications are built and efficiently served in a production environment.

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

### [Step 1: Create the Dockerfile](#step-1-create-the-dockerfile)

Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog).

Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/).

> Important
>
> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application.
>
> Official Node.js Docker Images: <https://hub.docker.com/_/node>

Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide.

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Pull the Node.js DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/node:24-alpine3.22-dev
   ```

3. Pull the Nginx DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/nginx:1.28.0-alpine3.21-dev
   ```

In the following Dockerfile, the `FROM` instructions use `dhi.io/node:24-alpine3.22-dev` and `dhi.io/nginx:1.28.0-alpine3.21-dev` as the base images.

```dockerfile
# =========================================
# Stage 1: Build the Vue.js Application
# =========================================
# Use a lightweight DHI Node.js image for building
FROM dhi.io/node:24-alpine3.22-dev AS builder

# Set the working directory inside the container
WORKDIR /app

# Copy package-related files first to leverage Docker's caching mechanism
COPY package.json package-lock.json* ./

# Install project dependencies using npm ci (ensures a clean, reproducible install)
RUN --mount=type=cache,target=/root/.npm npm ci

# Copy the rest of the application source code into the container
COPY . .

# Build the Vue.js application
RUN npm run build

# =========================================
# Stage 2: Prepare Nginx to Serve Static Files
# =========================================

FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner

# Copy custom Nginx config
COPY nginx.conf /etc/nginx/nginx.conf

# Copy the static build output from the build stage to Nginx's default HTML serving directory
COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html

# Use a built-in non-root user for security best practices
USER nginx

# Expose port 8080 to allow HTTP traffic
# Note: The default Nginx container now listens on port 8080 instead of 80 
EXPOSE 8080

# Start Nginx directly with custom config
ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"]
CMD ["-g", "daemon off;"]
```

Create a file named `Dockerfile` with the following contents:

```dockerfile
# =========================================
# Stage 1: Build the Vue.js Application
# =========================================
ARG NODE_VERSION=24.12.0-alpine
ARG NGINX_VERSION=alpine3.22

# Use a lightweight Node.js image for building (customizable via ARG)
FROM node:${NODE_VERSION} AS builder

# Set the working directory inside the container
WORKDIR /app

# Copy package-related files first to leverage Docker's caching mechanism
COPY package.json package-lock.json* ./

# Install project dependencies using npm ci (ensures a clean, reproducible install)
RUN --mount=type=cache,target=/root/.npm npm ci

# Copy the rest of the application source code into the container
COPY . .

# Build the Vue.js application
RUN npm run build

# =========================================
# Stage 2: Prepare Nginx to Serve Static Files
# =========================================

FROM nginxinc/nginx-unprivileged:${NGINX_VERSION} AS runner

# Copy custom Nginx config
COPY nginx.conf /etc/nginx/nginx.conf

# Copy the static build output from the build stage to Nginx's default HTML serving directory
COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html

# Use a built-in non-root user for security best practices
USER nginx

# Expose port 8080 to allow HTTP traffic
# Note: The default Nginx container now listens on port 8080 instead of 80 
EXPOSE 8080

# Start Nginx directly with custom config
ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"]
CMD ["-g", "daemon off;"]
```

> Note
>
> We are using nginx-unprivileged instead of the standard Nginx image to follow security best practices. Running as a non-root user in the final image:
>
> * Reduces the attack surface
> * Aligns with Docker’s recommendations for container hardening
> * Helps comply with stricter security policies in production environments

### [Step 2: Create the compose.yaml file](#step-2-create-the-composeyaml-file)

Create a file named `compose.yaml` with the following contents:

compose.yaml

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 8080:8080
```

### [Step 3: Create the .dockerignore file](#step-3-create-the-dockerignore-file)

The `.dockerignore` file plays a crucial role in optimizing your Docker image by specifying which files and directories should be excluded from the build context.

> Note
>
> This helps:
>
> * Reduce image size
> * Speed up the build process
> * Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image.
>
> To learn more, visit the [.dockerignore reference](https://docs.docker.com/reference/dockerfile/#dockerignore-file).

Create a file named `.dockerignore` with the following contents:

```dockerignore
# -------------------------------
# Dependency directories
# -------------------------------
node_modules/

# -------------------------------
# Production and build outputs
# -------------------------------
dist/
out/
build/
public/build/

# -------------------------------
# Vite, VuePress, and cache dirs
# -------------------------------
.vite/
.vitepress/
.cache/
.tmp/

# -------------------------------
# Test output and coverage
# -------------------------------
coverage/
reports/
jest/
cypress/
cypress/screenshots/
cypress/videos/

# -------------------------------
# Environment and config files
# -------------------------------
*.env*
!.env.production    # Keep production env if needed
*.local
*.log

# -------------------------------
# TypeScript artifacts
# -------------------------------
*.tsbuildinfo

# -------------------------------
# Editor and IDE config
# -------------------------------
.vscode/
.idea/
*.swp

# -------------------------------
# System files
# -------------------------------
.DS_Store
Thumbs.db

# -------------------------------
# Lockfiles (optional)
# -------------------------------
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*

# -------------------------------
# Git files
# -------------------------------
.git/
.gitignore

# -------------------------------
# Docker-related files
# -------------------------------
Dockerfile
.dockerignore
docker-compose.yml
docker-compose.override.yml
```

### [Step 4: Create the `nginx.conf` file](#step-4-create-the-nginxconf-file)

To serve your Vue.js application efficiently inside the container, you’ll configure Nginx with a custom setup. This configuration is optimized for performance, browser caching, gzip compression, and support for client-side routing.

Create a file named `nginx.conf` in the root of your project directory, and add the following content:

> Note
>
> To learn more about configuring Nginx, see the [official Nginx documentation](https://nginx.org/en/docs/).

```nginx
worker_processes auto;
pid /tmp/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    charset       utf-8;

    access_log    off;
    error_log     /dev/stderr warn;

    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  65;
    keepalive_requests 1000;

    gzip on;
    gzip_comp_level 6;
    gzip_proxied any;
    gzip_min_length 256;
    gzip_vary on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml;

    server {
        listen       8080;
        server_name  localhost;

        root   /usr/share/nginx/html;
        index  index.html;

        location / {
            try_files $uri $uri/ /index.html;
        }

        location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|svg|map)$ {
            expires 1y;
            access_log off;
            add_header Cache-Control "public, immutable";
            add_header X-Content-Type-Options nosniff;
        }

        location /assets/ {
            expires 1y;
            add_header Cache-Control "public, immutable";
            add_header X-Content-Type-Options nosniff;
        }

        error_page 404 /index.html;
    }
}
```

### [Step 5: Build the Vue.js application image](#step-5-build-the-vuejs-application-image)

With your custom configuration in place, you're now ready to build the Docker image for your Vue.js application.

The updated setup includes:

* The updated setup includes a clean, production-ready Nginx configuration tailored specifically for Vue.js.
* Efficient multi-stage Docker build, ensuring a small and secure final image.

After completing the previous steps, your project directory should now contain the following files:

```text
├── docker-vuejs-sample/
│ ├── Dockerfile
│ ├── .dockerignore
│ ├── compose.yaml
│ └── nginx.conf
```

Now that your Dockerfile is configured, you can build the Docker image for your Vue.js application.

> Note
>
> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)).

Run the following command from the root of your project:

```console
$ docker build --tag docker-vuejs-sample .
```

What this command does:

* Uses the Dockerfile in the current directory (.)
* Packages the application and its dependencies into a Docker image
* Tags the image as docker-vuejs-sample so you can reference it later

### [Step 6: View local images](#step-6-view-local-images)

After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](https://docs.docker.com/desktop/use-desktop/images/). Since you're already working in the terminal, let's use the Docker CLI.

To list all locally available Docker images, run the following command:

```console
$ docker images
```

Example Output:

```shell
REPOSITORY                TAG               IMAGE ID       CREATED         SIZE
docker-vuejs-sample       latest            8c9c199179d4   14 seconds ago   76.2MB
```

This output provides key details about your images:

* **Repository** – The name assigned to the image.
* **Tag** – A version label that helps identify different builds (e.g., latest).
* **Image ID** – A unique identifier for the image.
* **Created** – The timestamp indicating when the image was built.
* **Size** – The total disk space used by the image.

If the build was successful, you should see `docker-vuejs-sample` image listed.

***

## [Run the containerized application](#run-the-containerized-application)

In the previous step, you created a Dockerfile for your Vue.js application and built a Docker image using the docker build command. Now it’s time to run that image in a container and verify that your application works as expected.

Inside the `docker-vuejs-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:8080>. You should see a simple Vue.js web application.

Press `ctrl+c` in the terminal to stop your application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `docker-vuejs-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:8080>. You should see your Vue.js application running in the browser.

To confirm that the container is running, use `docker ps` command:

```console
$ docker ps
```

This will list all active containers along with their ports, names, and status. Look for a container exposing port 8080.

Example Output:

```shell
CONTAINER ID   IMAGE                          COMMAND                  CREATED             STATUS             PORTS                    NAMES
37a1fa85e4b0   docker-vuejs-sample-server     "nginx -c /etc/nginx…"   About a minute ago  Up About a minute  0.0.0.0:8080->8080/tcp   docker-vuejs-sample-server-1
```

To stop the application, run:

```console
$ docker compose down
```

> Note
>
> For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

***

## [Summary](#summary)

In this guide, you learned how to containerize, build, and run an Vue.js application using Docker. By following best practices, you created a secure, optimized, and production-ready setup.

What you accomplished:

* Created a multi-stage `Dockerfile` that compiles the Vue.js application and serves the static files using Nginx.
* Created a `.dockerignore` file to exclude unnecessary files and keep the image clean and efficient.
* Built your Docker image using `docker build`.
* Ran the container using `docker compose up`, both in the foreground and in detached mode.
* Verified that the app was running by visiting <http://localhost:8080>.
* Learned how to stop the containerized application using `docker compose down`.

You now have a fully containerized Vue.js application, running in a Docker container, and ready for deployment across any environment with confidence and consistency.

***

***

## [Next steps](#next-steps)

With your Vue.js application now containerized, you're ready to move on to the next step.

In the next section, you'll learn how to develop your application using Docker containers, enabling a consistent, isolated, and reproducible development environment across any machine.

[Use containers for Vue.js development »](https://docs.docker.com/guides/vuejs/develop/)

----
url: https://docs.docker.com/dhi/migration/migrate-with-ai/
----

# Migrate using Gordon

***

***

Availability: Experimental

Requires: Docker Desktop [4.38.0](https://docs.docker.com/desktop/release-notes/#4380) or later

You can use Gordon to automatically migrate your Dockerfile to use Docker Hardened Images (DHI).

1. Ensure Gordon is [enabled](https://docs.docker.com/ai/gordon/#enable-ask-gordon).
2. In the terminal, navigate to the directory containing your Dockerfile.
3. Start a conversation with the assistant:
   ```bash
   docker ai
   ```
4. Type:
   ```console
   "Migrate my dockerfile to DHI"
   ```
5. Follow the conversation with the assistant. The assistant will edit your Dockerfile, so when it requests access to the filesystem and more, type `yes` to allow the assistant to proceed.

When the migration is complete, you see a success message:

```text
The migration to Docker Hardened Images (DHI) is complete. The updated Dockerfile
successfully builds the image, and no vulnerabilities were detected in the final image.
The functionality and optimizations of the original Dockerfile have been preserved.
```

> Important
>
> As with any AI tool, you must verify the assistant's edits and test your image.

----
url: https://docs.docker.com/guides/github-sonarqube-sandbox/customize/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Customize a code quality check workflow

***

Table of contents

***

Now that you understand the basics of automating code quality workflows with GitHub and SonarQube in E2B sandboxes, you can customize the workflow for your needs.

## [Focus on specific quality issues](#focus-on-specific-quality-issues)

Modify the prompt to prioritize certain issue types:

```typescript
const prompt = `Using SonarQube and GitHub MCP tools:

Focus only on:
- Security vulnerabilities (CRITICAL priority)
- Bugs (HIGH priority)
- Skip code smells for this iteration

Analyze "${repoPath}" and fix the highest priority issues first.`;
```

```python
prompt = f"""Using SonarQube and GitHub MCP tools:

Focus only on:
- Security vulnerabilities (CRITICAL priority)
- Bugs (HIGH priority)
- Skip code smells for this iteration

Analyze "{repo_path}" and fix the highest priority issues first."""
```

## [Integrate with CI/CD](#integrate-with-cicd)

Add this workflow to GitHub Actions to run automatically on pull requests:

```yaml
name: Automated quality checks
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v5
        with:
          node-version: "24"
      - run: npm install
      - run: npx tsx 06-quality-gated-pr.ts
        env:
          E2B_API_KEY: ${{ secrets.E2B_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SONARQUBE_TOKEN: ${{ secrets.SONARQUBE_TOKEN }}
          GITHUB_OWNER: ${{ github.repository_owner }}
          GITHUB_REPO: ${{ github.event.repository.name }}
          SONARQUBE_ORG: your-org-key
```

```yaml
name: Automated quality checks
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with:
          python-version: "3.14"
      - run: pip install e2b python-dotenv
      - run: python 06_quality_gated_pr.py
        env:
          E2B_API_KEY: ${{ secrets.E2B_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SONARQUBE_TOKEN: ${{ secrets.SONARQUBE_TOKEN }}
          GITHUB_OWNER: ${{ github.repository_owner }}
          GITHUB_REPO: ${{ github.event.repository.name }}
          SONARQUBE_ORG: your-org-key
```

## [Filter by file patterns](#filter-by-file-patterns)

Target specific parts of your codebase:

```typescript
const prompt = `Analyze code quality but only consider:
- Files in src/**/*.js
- Exclude test files (*.test.js, *.spec.js)
- Exclude build artifacts in dist/

Focus on production code only.`;
```

```python
prompt = """Analyze code quality but only consider:
- Files in src/**/*.js
- Exclude test files (*.test.js, *.spec.js)
- Exclude build artifacts in dist/

Focus on production code only."""
```

## [Set quality thresholds](#set-quality-thresholds)

Define when PRs should be created:

```typescript
const prompt = `Quality gate thresholds:
- Only create PR if:
  * Bug count decreases by at least 1
  * No new security vulnerabilities introduced
  * Code coverage does not decrease
  * Technical debt reduces by at least 15 minutes

If changes do not meet these thresholds, explain why and skip PR creation.`;
```

```python
prompt = """Quality gate thresholds:
- Only create PR if:
  * Bug count decreases by at least 1
  * No new security vulnerabilities introduced
  * Code coverage does not decrease
  * Technical debt reduces by at least 15 minutes

If changes do not meet these thresholds, explain why and skip PR creation."""
```

## [Next steps](#next-steps)

Learn how to troubleshoot common issues.

[Troubleshoot code quality workflows »](https://docs.docker.com/guides/github-sonarqube-sandbox/troubleshoot/)

----
url: https://docs.docker.com/desktop/use-desktop/builds/
----

# Explore the Builds view in Docker Desktop

***

Table of contents

***

The **Builds** view provides an interactive interface for inspecting build history, monitoring active builds, and managing builders directly in Docker Desktop.

By default, the **Build history** tab displays a list of completed builds, sorted by date (newest first). Switch to the **Active builds** tab to view ongoing builds.

If you're connected to a cloud builder through [Docker Build Cloud](https://docs.docker.com/build-cloud/), the Builds view also lists any active or completed cloud builds by other team members connected to the same cloud builder.

> Note
>
> Windows container image builds use the legacy builder and do not appear in the **Builds** view. Only BuildKit-powered builds are shown here.

## [Show build list](#show-build-list)

Open the **Builds** view from the Docker Dashboard to access:

* **Build history**: Completed builds with access to logs, dependencies, traces, and more
* **Active builds**: Builds currently in progress

Only builds from active, running builders are listed. Builds from removed or stopped builders are not shown.

### [Builder settings](#builder-settings)

The top-right corner shows the name of your currently selected builder, and the **Builder settings** button lets you [manage builders](#manage-builders) in the Docker Desktop settings.

### [Import builds](#import-builds)

The **Import builds** button lets you import build records for builds by other people, or builds in a CI environment. When you've imported a build record, it gives you full access to the logs, traces, and other data for that build, directly in Docker Desktop.

The [build summary](https://docs.docker.com/build/ci/github-actions/build-summary/) for the `docker/build-push-action` and `docker/bake-action` GitHub Actions includes a link to download the build records, for inspecting CI jobs with Docker Desktop.

## [Inspect builds](#inspect-builds)

To inspect a build, select the build that you want to view in the list. The inspection view contains a number of tabs.

The **Info** tab displays details about the build.

If you're inspecting a multi-platform build, the drop-down menu in the top-right of this tab lets you filter the information down to a specific platform:

The **Source details** section shows information about the frontend [frontend](https://docs.docker.com/build/buildkit/frontend/) and, if available, the source code repository used for the build.

### [Build timing](#build-timing)

The **Build timing** section of the Info tab contains charts showing a breakdown of the build execution from various angles.

* **Real time** refers to the wall-clock time that it took to complete the build.
* **Accumulated time** shows the total CPU time for all steps.
* **Cache usage** shows the extent to which build operations were cached.
* **Parallel execution** shows how much of the build execution time was spent running steps in parallel.

The chart colors and legend keys describe the different build operations. Build operations are defined as follows:

| Build operation      | Description                                                                                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Local file transfers | Time spent transferring local files from the client to the builder.                                                                                                             |
| File operations      | Any operations that involve creating and copying files in the build. For example, the `COPY`, `WORKDIR`, `ADD` instructions in a Dockerfile frontend all incur file operations. |
| Image pulls          | Time spent pulling images.                                                                                                                                                      |
| Executions           | Container executions, for example commands defined as `RUN` instructions in a Dockerfile frontend.                                                                              |
| HTTP                 | Remote artifact downloads using `ADD`.                                                                                                                                          |
| Git                  | Same as **HTTP** but for Git URLs.                                                                                                                                              |
| Result exports       | Time spent exporting the build results.                                                                                                                                         |
| SBOM                 | Time spent generating the [SBOM attestation](https://docs.docker.com/build/metadata/attestations/sbom/).                                                                        |
| Idle                 | Idle time for build workers, which can happen if you have configured a [max parallelism limit](https://docs.docker.com/build/buildkit/configure/#max-parallelism).              |

### [Build dependencies](#build-dependencies)

The **Dependencies** section shows images and remote resources used during the build. Resources listed here include:

* Container images used during the build
* Git repositories included using the `ADD` Dockerfile instruction
* Remote HTTPS resources included using the `ADD` Dockerfile instruction

### [Arguments, secrets, and other parameters](#arguments-secrets-and-other-parameters)

The **Configuration** section of the Info tab shows parameters passed to the build:

* Build arguments, including the resolved value
* Secrets, including their IDs (but not their values)
* SSH sockets
* Labels
* [Additional contexts](/reference/cli/docker/buildx/build/#build-context)

### [Outputs and artifacts](#outputs-and-artifacts)

The **Build results** section shows a summary of the generated build artifacts, including image manifest details, attestations, and build traces.

Attestations are metadata records attached to a container image. The metadata describes something about the image, for example how it was built or what packages it contains. For more information about attestations, see [Build attestations](https://docs.docker.com/build/metadata/attestations/).

Build traces capture information about the build execution steps in Buildx and BuildKit. The traces are available in two formats: OTLP and Jaeger. You can download build traces from Docker Desktop by opening the actions menu and selecting the format you want to download.

#### [Inspect build traces with Jaeger](#inspect-build-traces-with-jaeger)

Using a Jaeger client, you can import and inspect build traces from Docker Desktop. The following steps show you how to export a trace from Docker Desktop and view it in [Jaeger](https://www.jaegertracing.io/):

1. Start Jaeger UI:

   ```console
   $ docker run -d --name jaeger -p "16686:16686" jaegertracing/all-in-one
   ```

2. Open the Builds view in Docker Desktop, and select a completed build.

3. Navigate to the **Build results** section, open the actions menu and select **Download as Jaeger format**.

4. Go to <http://localhost:16686> in your browser to open Jaeger UI.

5. Select the **Upload** tab and open the Jaeger build trace you just exported.

Now you can analyze the build trace using the Jaeger UI:

Screenshot of a build trace in the Jaeger UI

### [Dockerfile source and errors](#dockerfile-source-and-errors)

When inspecting a successful completed build or an ongoing active build, the **Source** tab shows the [frontend](https://docs.docker.com/build/buildkit/frontend/) used to create the build.

If the build failed, an **Error** tab displays instead of the **Source** tab. The error message is inlined in the Dockerfile source, indicating where the failure happened and why.

### [Build logs](#build-logs)

The **Logs** tab displays the build logs. For active builds, the logs are updated in real-time.

You can toggle between a **List view** and a **Plain-text view** of a build log.

* The **List view** presents all build steps in a collapsible format, with a timeline for navigating the log along a time axis.

* The **Plain-text view** displays the log as plain text.

The **Copy** button lets you copy the plain-text version of the log to your clipboard.

### [Build history](#build-history)

The **History** tab displays statistics data about completed builds.

The time series chart illustrates trends in duration, build steps, and cache usage for related builds, helping you identify patterns and shifts in build operations over time. For instance, significant spikes in build duration or a high number of cache misses could signal opportunities for optimizing the Dockerfile.

You can navigate to and inspect a related build by selecting it in the chart, or using the **Past builds** list below the chart.

## [Manage builders](#manage-builders)

The **Builder** tab in **Settings** lets you:

* Inspect the state and configuration of active builders
* Start and stop a builder
* Delete build history
* Add or remove builders (or connect and disconnect, in the case of cloud builders)

For more information about managing builders, see [Change settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#builders)

----
url: https://docs.docker.com/build/exporters/image-registry/
----

# Image and registry exporters

***

Table of contents

***

The `image` exporter outputs the build result into a container image format. The `registry` exporter is identical, but it automatically pushes the result by setting `push=true`.

## [Synopsis](#synopsis)

Build a container image using the `image` and `registry` exporters:

```console
$ docker buildx build --output type=image[,parameters] .
$ docker buildx build --output type=registry[,parameters] .
```

The following table describes the available parameters that you can pass to `--output` for `type=image`:

| Parameter              | Type                                   | Default | Description                                                                                                                                                                                                                         |
| ---------------------- | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                 | String                                 |         | Specify image name(s)                                                                                                                                                                                                               |
| `push`                 | `true`,`false`                         | `false` | Push after creating the image.                                                                                                                                                                                                      |
| `push-by-digest`       | `true`,`false`                         | `false` | Push image without name.                                                                                                                                                                                                            |
| `registry.insecure`    | `true`,`false`                         | `false` | Allow pushing to insecure registry.                                                                                                                                                                                                 |
| `dangling-name-prefix` | `<value>`                              |         | Name image with `prefix@<digest>`, used for anonymous images                                                                                                                                                                        |
| `name-canonical`       | `true`,`false`                         |         | Add additional canonical name `name@<digest>`                                                                                                                                                                                       |
| `compression`          | `uncompressed`,`gzip`,`estargz`,`zstd` | `gzip`  | Compression type, see [compression](https://docs.docker.com/build/exporters/#compression)                                                                                                                                           |
| `compression-level`    | `0..22`                                |         | Compression level, see [compression](https://docs.docker.com/build/exporters/#compression)                                                                                                                                          |
| `force-compression`    | `true`,`false`                         | `false` | Forcefully apply compression, see [compression](https://docs.docker.com/build/exporters/#compression)                                                                                                                               |
| `rewrite-timestamp`    | `true`,`false`                         | `false` | Rewrite the file timestamps to the `SOURCE_DATE_EPOCH` value. See [build reproducibility](https://github.com/moby/buildkit/blob/master/docs/build-repro.md) for how to specify the `SOURCE_DATE_EPOCH` value.                       |
| `oci-mediatypes`       | `true`,`false`                         | `false` | Use OCI media types in exporter manifests, see [OCI Media types](https://docs.docker.com/build/exporters/#oci-media-types)                                                                                                          |
| `oci-artifact`         | `true`,`false`                         | `false` | Attestations are formatted as OCI artifacts, see [OCI Media types](https://docs.docker.com/build/exporters/#oci-media-types)                                                                                                        |
| `unpack`               | `true`,`false`                         | `false` | Unpack image after creation (for use with containerd)                                                                                                                                                                               |
| `store`                | `true`,`false`                         | `true`  | Store the result images to the worker's (for example, containerd) image store, and ensures that the image has all blobs in the content store. Ignored if the worker doesn't have image store (when using OCI workers, for example). |
| `annotation.<key>`     | String                                 |         | Attach an annotation with the respective `key` and `value` to the built image,see [annotations](#annotations)                                                                                                                       |

## [Annotations](#annotations)

These exporters support adding OCI annotation using `annotation` parameter, followed by the annotation name using dot notation. The following example sets the `org.opencontainers.image.title` annotation:

```console
$ docker buildx build \
    --output "type=<type>,name=<registry>/<image>,annotation.org.opencontainers.image.title=<title>" .
```

For more information about annotations, see [BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/annotations.md).

## [Further reading](#further-reading)

For more information on the `image` or `registry` exporters, see the [BuildKit README](https://github.com/moby/buildkit/blob/master/README.md#imageregistry).

----
url: https://docs.docker.com/reference/cli/docker/model/context/ls/
----

# docker model context ls

***

| Description                                                               | List Model Runner contexts  |
| ------------------------------------------------------------------------- | --------------------------- |
| Usage                                                                     | `docker model context ls`   |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker model context list` |

## [Description](#description)

List Model Runner contexts

----
url: https://docs.docker.com/docker-hub/usage/manage/
----

# Best practices for optimizing Docker Hub usage

***

***

Use the following steps to help optimize and manage your Docker Hub usage for both individuals and organizations:

1. [View your Docker Hub usage](https://hub.docker.com/usage).

2. Use the Docker Hub usage data to identify which accounts consume the most data, determine peak usage times, and identify which images are related to the most data usage. In addition, look for usage trends, such as the following:

   * Inefficient pull behavior: Identify frequently accessed repositories to assess whether you can optimize caching practices or consolidate usage to reduce pulls.
   * Inefficient automated systems: Check which automated tools, such as CI/CD pipelines, may be causing higher pull rates, and configure them to avoid unnecessary image pulls.

3. Optimize image pulls by:

   * Using caching: Implement local image caching via [mirroring](/docker-hub/mirror/) or within your CI/CD pipelines to reduce redundant pulls.
   * Automating manual workflows: Avoid unnecessary pulls by configuring automated systems to pull only when a new version of an image is available.

4. Optimize your storage by:

   * Regularly auditing and [removing entire repositories](https://docs.docker.com/docker-hub/repos/delete/) with untagged, unused, or outdated images.
   * Using [Image Management](https://docs.docker.com/docker-hub/repos/manage/hub-images/manage/) to remove stale and outdated images within a repository.

5. For organizations, monitor and enforce organizational policies by doing the following:

   * Routinely [view Docker Hub usage](https://hub.docker.com/usage) to monitor usage.
   * [Enforce sign-in](/security/for-admins/enforce-sign-in/) to ensure that you can monitor the usage of your users and users receive higher usage limits.
   * Look for duplicate user accounts in Docker and remove accounts from your organization as needed.

----
url: https://docs.docker.com/desktop/setup/sign-in/
----

# Sign in to Docker Desktop

***

Table of contents

***

Docker recommends signing in with the **Sign in** option in the top-right corner of the Docker Dashboard.

In large enterprises where admin access is restricted, administrators can [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).

> Tip
>
> Explore [Docker's core subscriptions](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopSignIn) to see what else Docker can offer you.

## [Benefits of signing in](#benefits-of-signing-in)

* Access your Docker Hub repositories directly from Docker Desktop.

* Increase your pull rate limit compared to anonymous users. See [Usage and limits](https://docs.docker.com/docker-hub/usage/).

* Enhance your organization’s security posture for containerized development with [Hardened Desktop](https://docs.docker.com/enterprise/security/hardened-desktop/).

> Note
>
> Docker Desktop automatically signs you out after 90 days, or after 30 days of inactivity.

## [Signing in with Docker Desktop for Linux](#signing-in-with-docker-desktop-for-linux)

Docker Desktop for Linux relies on [`pass`](https://www.passwordstore.org/) to store credentials in GPG-encrypted files. Before signing in to Docker Desktop with your [Docker ID](/accounts/create-account/), you must initialize `pass`. Docker Desktop displays a warning if `pass` is not configured.

1. Generate a GPG key. You can initialize pass by using a gpg key. To generate a gpg key, run:

   ```console
   $ gpg --generate-key
   ```

2. Enter your name and email once prompted.

   Once confirmed, GPG creates a key pair. Look for the `pub` line that contains your GPG ID, for example:

   ```text
   ...
   pubrsa3072 2022-03-31 [SC] [expires: 2024-03-30]
    3ABCD1234EF56G78
   uid          Molly <molly@example.com>
   ```

3. Copy the GPG ID and use it to initialize `pass`. For example

   ```console
   $ pass init 3ABCD1234EF56G78
   ```

   You should see output similar to:

   ```text
   mkdir: created directory '/home/molly/.password-store/'
   Password store initialized for <generated_gpg-id_public_key>
   ```

Once you initialize `pass`, you can sign in and pull your private images. When Docker CLI or Docker Desktop use credentials, a user prompt may pop up for the password you set during the GPG key generation.

```console
$ docker pull molly/privateimage
Using default tag: latest
latest: Pulling from molly/privateimage
3b9cc81c3203: Pull complete 
Digest: sha256:3c6b73ce467f04d4897d7a7439782721fd28ec9bf62ea2ad9e81a5fb7fb3ff96
Status: Downloaded newer image for molly/privateimage:latest
docker.io/molly/privateimage:latest
```

## [What's next?](#whats-next)

* [Explore Docker Desktop](https://docs.docker.com/desktop/use-desktop/) and its features.
* Change your [Docker Desktop settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/).
* [Browse common FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/general/).

----
url: https://docs.docker.com/engine/storage/drivers/overlayfs-driver/
----

# OverlayFS storage driver

***

Table of contents

***

OverlayFS is a union filesystem.

This page refers to the Linux kernel driver as `OverlayFS` and to the Docker storage driver as `overlay2`.

> Note
>
> Docker Engine 29.0 and later uses the [containerd image store](https://docs.docker.com/engine/storage/containerd/) by default. The `overlay2` driver is a legacy storage driver that is superseded by the `overlayfs` containerd snapshotter. For more information, see [Select a storage driver](https://docs.docker.com/engine/storage/drivers/select-storage-driver/).

> Note
>
> For `fuse-overlayfs` driver, check [Rootless mode documentation](https://docs.docker.com/engine/security/rootless/).

## [Prerequisites](#prerequisites)

The `overlay2` driver is supported if you meet the following prerequisites:

* Version 4.0 or higher of the Linux kernel, or RHEL or CentOS using version 3.10.0-514 of the kernel or higher.

* The `overlay2` driver is supported on `xfs` backing filesystems, but only with `d_type=true` enabled.

  Use `xfs_info` to verify that the `ftype` option is set to `1`. To format an `xfs` filesystem correctly, use the flag `-n ftype=1`.

* Changing the storage driver makes existing containers and images inaccessible on the local system. Use `docker save` to save any images you have built or push them to Docker Hub or a private registry before changing the storage driver, so that you don't need to re-create them later.

## [Configure Docker with the `overlay2` storage driver](#configure-docker-with-the-overlay2-storage-driver)

[]()

Before following this procedure, you must first meet all the [prerequisites](#prerequisites).

The following steps outline how to configure the `overlay2` storage driver.

1. Stop Docker.

   ```console
   $ sudo systemctl stop docker
   ```

2. Copy the contents of `/var/lib/docker` to a temporary location.

   ```console
   $ cp -au /var/lib/docker /var/lib/docker.bk
   ```

3. If you want to use a separate backing filesystem from the one used by `/var/lib/`, format the filesystem and mount it into `/var/lib/docker`. Make sure to add this mount to `/etc/fstab` to make it permanent.

4. Edit `/etc/docker/daemon.json`. If it doesn't yet exist, create it. Assuming that the file was empty, add the following contents.

   ```json
   {
     "storage-driver": "overlay2"
   }
   ```

   Docker doesn't start if the `daemon.json` file contains invalid JSON.

5. Start Docker.

   ```console
   $ sudo systemctl start docker
   ```

6. Verify that the daemon is using the `overlay2` storage driver. Use the `docker info` command and look for `Storage Driver` and `Backing filesystem`.

   ```console
   $ docker info

   Containers: 0
   Images: 0
   Storage Driver: overlay2
    Backing Filesystem: xfs
    Supports d_type: true
    Native Overlay Diff: true
   <...>
   ```

Docker is now using the `overlay2` storage driver and has automatically created the overlay mount with the required `lowerdir`, `upperdir`, `merged`, and `workdir` constructs.

Continue reading for details about how OverlayFS works within your Docker containers, as well as performance advice and information about limitations of its compatibility with different backing filesystems.

## [How the `overlay2` driver works](#how-the-overlay2-driver-works)

OverlayFS layers two directories on a single Linux host and presents them as a single directory. These directories are called layers, and the unification process is referred to as a union mount. OverlayFS refers to the lower directory as `lowerdir` and the upper directory as `upperdir`. The unified view is exposed through its own directory called `merged`.

The `overlay2` driver natively supports up to 128 lower OverlayFS layers. This capability provides better performance for layer-related Docker commands such as `docker build` and `docker commit`, and consumes fewer inodes on the backing filesystem.

### [Image and container layers on-disk](#image-and-container-layers-on-disk)

After downloading a five-layer image using `docker pull ubuntu`, you can see six directories under `/var/lib/docker/overlay2`.

> Warning
>
> Don't directly manipulate any files or directories within `/var/lib/docker/`. These files and directories are managed by Docker.

```console
$ ls -l /var/lib/docker/overlay2

total 24
drwx------ 5 root root 4096 Jun 20 07:36 223c2864175491657d238e2664251df13b63adb8d050924fd1bfcdb278b866f7
drwx------ 3 root root 4096 Jun 20 07:36 3a36935c9df35472229c57f4a27105a136f5e4dbef0f87905b2e506e494e348b
drwx------ 5 root root 4096 Jun 20 07:36 4e9fa83caff3e8f4cc83693fa407a4a9fac9573deaf481506c102d484dd1e6a1
drwx------ 5 root root 4096 Jun 20 07:36 e8876a226237217ec61c4baf238a32992291d059fdac95ed6303bdff3f59cff5
drwx------ 5 root root 4096 Jun 20 07:36 eca1e4e1694283e001f200a667bb3cb40853cf2d1b12c29feda7422fed78afed
drwx------ 2 root root 4096 Jun 20 07:36 l
```

The new `l` (lowercase `L`) directory contains shortened layer identifiers as symbolic links. These identifiers are used to avoid hitting the page size limitation on arguments to the `mount` command.

```console
$ ls -l /var/lib/docker/overlay2/l

total 20
lrwxrwxrwx 1 root root 72 Jun 20 07:36 6Y5IM2XC7TSNIJZZFLJCS6I4I4 -> ../3a36935c9df35472229c57f4a27105a136f5e4dbef0f87905b2e506e494e348b/diff
lrwxrwxrwx 1 root root 72 Jun 20 07:36 B3WWEFKBG3PLLV737KZFIASSW7 -> ../4e9fa83caff3e8f4cc83693fa407a4a9fac9573deaf481506c102d484dd1e6a1/diff
lrwxrwxrwx 1 root root 72 Jun 20 07:36 JEYMODZYFCZFYSDABYXD5MF6YO -> ../eca1e4e1694283e001f200a667bb3cb40853cf2d1b12c29feda7422fed78afed/diff
lrwxrwxrwx 1 root root 72 Jun 20 07:36 NFYKDW6APBCCUCTOUSYDH4DXAT -> ../223c2864175491657d238e2664251df13b63adb8d050924fd1bfcdb278b866f7/diff
lrwxrwxrwx 1 root root 72 Jun 20 07:36 UL2MW33MSE3Q5VYIKBRN4ZAGQP -> ../e8876a226237217ec61c4baf238a32992291d059fdac95ed6303bdff3f59cff5/diff
```

The lowest layer contains a file called `link`, which contains the name of the shortened identifier, and a directory called `diff` which contains the layer's contents.

```console
$ ls /var/lib/docker/overlay2/3a36935c9df35472229c57f4a27105a136f5e4dbef0f87905b2e506e494e348b/

diff  link

$ cat /var/lib/docker/overlay2/3a36935c9df35472229c57f4a27105a136f5e4dbef0f87905b2e506e494e348b/link

6Y5IM2XC7TSNIJZZFLJCS6I4I4

$ ls  /var/lib/docker/overlay2/3a36935c9df35472229c57f4a27105a136f5e4dbef0f87905b2e506e494e348b/diff

bin  boot  dev  etc  home  lib  lib64  media  mnt  opt  proc  root  run  sbin  srv  sys  tmp  usr  var
```

The second-lowest layer, and each higher layer, contain a file called `lower`, which denotes its parent, and a directory called `diff` which contains its contents. It also contains a `merged` directory, which contains the unified contents of its parent layer and itself, and a `work` directory which is used internally by OverlayFS.

```console
$ ls /var/lib/docker/overlay2/223c2864175491657d238e2664251df13b63adb8d050924fd1bfcdb278b866f7

diff  link  lower  merged  work

$ cat /var/lib/docker/overlay2/223c2864175491657d238e2664251df13b63adb8d050924fd1bfcdb278b866f7/lower

l/6Y5IM2XC7TSNIJZZFLJCS6I4I4

$ ls /var/lib/docker/overlay2/223c2864175491657d238e2664251df13b63adb8d050924fd1bfcdb278b866f7/diff/

etc  sbin  usr  var
```

To view the mounts which exist when you use the `overlay` storage driver with Docker, use the `mount` command. The output below is truncated for readability.

```console
$ mount | grep overlay

overlay on /var/lib/docker/overlay2/9186877cdf386d0a3b016149cf30c208f326dca307529e646afce5b3f83f5304/merged
type overlay (rw,relatime,
lowerdir=l/DJA75GUWHWG7EWICFYX54FIOVT:l/B3WWEFKBG3PLLV737KZFIASSW7:l/JEYMODZYFCZFYSDABYXD5MF6YO:l/UL2MW33MSE3Q5VYIKBRN4ZAGQP:l/NFYKDW6APBCCUCTOUSYDH4DXAT:l/6Y5IM2XC7TSNIJZZFLJCS6I4I4,
upperdir=9186877cdf386d0a3b016149cf30c208f326dca307529e646afce5b3f83f5304/diff,
workdir=9186877cdf386d0a3b016149cf30c208f326dca307529e646afce5b3f83f5304/work)
```

The `rw` on the second line shows that the `overlay` mount is read-write.

The following diagram shows how a Docker image and a Docker container are layered. The image layer is the `lowerdir` and the container layer is the `upperdir`. If the image has multiple layers, multiple `lowerdir` directories are used. The unified view is exposed through a directory called `merged` which is effectively the containers mount point.

Where the image layer and the container layer contain the same files, the container layer (`upperdir`) takes precedence and obscures the existence of the same files in the image layer.

To create a container, the `overlay2` driver combines the directory representing the image's top layer plus a new directory for the container. The image's layers are the `lowerdirs` in the overlay and are read-only. The new directory for the container is the `upperdir` and is writable.

### [Image and container layers on-disk (legacy overlay driver)](#image-and-container-layers-on-disk-legacy-overlay-driver)

The following `docker pull` command shows a Docker host downloading a Docker image comprising five layers.

```console
$ docker pull ubuntu

Using default tag: latest
latest: Pulling from library/ubuntu

5ba4f30e5bea: Pull complete
9d7d19c9dc56: Pull complete
ac6ad7efd0f9: Pull complete
e7491a747824: Pull complete
a3ed95caeb02: Pull complete
Digest: sha256:46fb5d001b88ad904c5c732b086b596b92cfb4a4840a3abd0e35dbb6870585e4
Status: Downloaded newer image for ubuntu:latest
```

#### [The image layers](#the-image-layers)

Each image layer has its own directory within `/var/lib/docker/overlay/`, which contains its contents, as shown in the following example. The image layer IDs don't correspond to the directory IDs.

> Warning
>
> Don't directly manipulate any files or directories within `/var/lib/docker/`. These files and directories are managed by Docker.

```console
$ ls -l /var/lib/docker/overlay/

total 20
drwx------ 3 root root 4096 Jun 20 16:11 38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8
drwx------ 3 root root 4096 Jun 20 16:11 55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358
drwx------ 3 root root 4096 Jun 20 16:11 824c8a961a4f5e8fe4f4243dab57c5be798e7fd195f6d88ab06aea92ba931654
drwx------ 3 root root 4096 Jun 20 16:11 ad0fe55125ebf599da124da175174a4b8c1878afe6907bf7c78570341f308461
drwx------ 3 root root 4096 Jun 20 16:11 edab9b5e5bf73f2997524eebeac1de4cf9c8b904fa8ad3ec43b3504196aa3801
```

The image layer directories contain the files unique to that layer as well as hard links to the data shared with lower layers. This allows for efficient use of disk space.

```console
$ ls -i /var/lib/docker/overlay2/38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8/root/bin/ls

19793696 /var/lib/docker/overlay2/38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8/root/bin/ls

$ ls -i /var/lib/docker/overlay2/55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358/root/bin/ls

19793696 /var/lib/docker/overlay2/55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358/root/bin/ls
```

#### [The container layer](#the-container-layer)

Containers also exist on-disk in the Docker host's filesystem under `/var/lib/docker/overlay/`. If you list a running container's subdirectory using the `ls -l` command, three directories and one file exist:

```console
$ ls -l /var/lib/docker/overlay2/<directory-of-running-container>

total 16
-rw-r--r-- 1 root root   64 Jun 20 16:39 lower-id
drwxr-xr-x 1 root root 4096 Jun 20 16:39 merged
drwxr-xr-x 4 root root 4096 Jun 20 16:39 upper
drwx------ 3 root root 4096 Jun 20 16:39 work
```

The `lower-id` file contains the ID of the top layer of the image the container is based on, which is the OverlayFS `lowerdir`.

```console
$ cat /var/lib/docker/overlay2/ec444863a55a9f1ca2df72223d459c5d940a721b2288ff86a3f27be28b53be6c/lower-id

55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358
```

The `upper` directory contains the contents of the container's read-write layer, which corresponds to the OverlayFS `upperdir`.

The `merged` directory is the union mount of the `lowerdir` and `upperdirs`, which comprises the view of the filesystem from within the running container.

The `work` directory is internal to OverlayFS.

To view the mounts which exist when you use the `overlay2` storage driver with Docker, use the `mount` command. The following output is truncated for readability.

```console
$ mount | grep overlay

overlay on /var/lib/docker/overlay2/l/ec444863a55a.../merged
type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/55f1e14c361b.../root,
upperdir=/var/lib/docker/overlay2/l/ec444863a55a.../upper,
workdir=/var/lib/docker/overlay2/l/ec444863a55a.../work)
```

The `rw` on the second line shows that the `overlay` mount is read-write.

## [How container reads and writes work with `overlay2`](#how-container-reads-and-writes-work-with-overlay2)

[]()

### [Reading files](#reading-files)

Consider three scenarios where a container opens a file for read access with overlay.

#### [The file does not exist in the container layer](#the-file-does-not-exist-in-the-container-layer)

If a container opens a file for read access and the file does not already exist in the container (`upperdir`) it is read from the image (`lowerdir`). This incurs very little performance overhead.

#### [The file only exists in the container layer](#the-file-only-exists-in-the-container-layer)

If a container opens a file for read access and the file exists in the container (`upperdir`) and not in the image (`lowerdir`), it's read directly from the container.

#### [The file exists in both the container layer and the image layer](#the-file-exists-in-both-the-container-layer-and-the-image-layer)

If a container opens a file for read access and the file exists in the image layer and the container layer, the file's version in the container layer is read. Files in the container layer (`upperdir`) obscure files with the same name in the image layer (`lowerdir`).

### [Modifying files or directories](#modifying-files-or-directories)

Consider some scenarios where files in a container are modified.

#### [Writing to a file for the first time](#writing-to-a-file-for-the-first-time)

The first time a container writes to an existing file, that file does not exist in the container (`upperdir`). The `overlay2` driver performs a `copy_up` operation to copy the file from the image (`lowerdir`) to the container (`upperdir`). The container then writes the changes to the new copy of the file in the container layer.

However, OverlayFS works at the file level rather than the block level. This means that all OverlayFS `copy_up` operations copy the entire file, even if the file is large and only a small part of it's being modified. This can have a noticeable impact on container write performance. However, two things are worth noting:

* The `copy_up` operation only occurs the first time a given file is written to. Subsequent writes to the same file operate against the copy of the file already copied up to the container.

* OverlayFS works with multiple layers. This means that performance can be impacted when searching for files in images with many layers.

#### [Deleting files and directories](#deleting-files-and-directories)

* When a *file* is deleted within a container, a *whiteout* file is created in the container (`upperdir`). The version of the file in the image layer (`lowerdir`) is not deleted (because the `lowerdir` is read-only). However, the whiteout file prevents it from being available to the container.

* When a *directory* is deleted within a container, an *opaque directory* is created within the container (`upperdir`). This works in the same way as a whiteout file and effectively prevents the directory from being accessed, even though it still exists in the image (`lowerdir`).

#### [Renaming directories](#renaming-directories)

Calling `rename(2)` for a directory is allowed only when both the source and the destination path are on the top layer. Otherwise, it returns `EXDEV` error ("cross-device link not permitted"). Your application needs to be designed to handle `EXDEV` and fall back to a "copy and unlink" strategy.

## [OverlayFS and Docker Performance](#overlayfs-and-docker-performance)

`overlay2` may perform better than `btrfs`. However, be aware of the following details:

### [Page caching](#page-caching)

OverlayFS supports page cache sharing. Multiple containers accessing the same file share a single page cache entry for that file. This makes the `overlay2` drivers efficient with memory and a good option for high-density use cases such as PaaS.

### [Copyup](#copyup)

As with other copy-on-write filesystems, OverlayFS performs copy-up operations whenever a container writes to a file for the first time. This can add latency into the write operation, especially for large files. However, once the file has been copied up, all subsequent writes to that file occur in the upper layer, without the need for further copy-up operations.

### [Performance best practices](#performance-best-practices)

The following generic performance best practices apply to OverlayFS.

#### [Use fast storage](#use-fast-storage)

Solid-state drives (SSDs) provide faster reads and writes than spinning disks.

#### [Use volumes for write-heavy workloads](#use-volumes-for-write-heavy-workloads)

Volumes provide the best and most predictable performance for write-heavy workloads. This is because they bypass the storage driver and don't incur any of the potential overheads introduced by thin provisioning and copy-on-write. Volumes have other benefits, such as allowing you to share data among containers and persisting your data even if no running container is using them.

## [Limitations on OverlayFS compatibility](#limitations-on-overlayfs-compatibility)

To summarize the OverlayFS's aspect which is incompatible with other filesystems:

* [`open(2)`](https://linux.die.net/man/2/open)

  OverlayFS only implements a subset of the POSIX standards. This can result in certain OverlayFS operations breaking POSIX standards. One such operation is the copy-up operation. Suppose that your application calls `fd1=open("foo", O_RDONLY)` and then `fd2=open("foo", O_RDWR)`. In this case, your application expects `fd1` and `fd2` to refer to the same file. However, due to a copy-up operation that occurs after the second calling to `open(2)`, the descriptors refer to different files. The `fd1` continues to reference the file in the image (`lowerdir`) and the `fd2` references the file in the container (`upperdir`). A workaround for this is to `touch` the files which causes the copy-up operation to happen. All subsequent `open(2)` operations regardless of read-only or read-write access mode reference the file in the container (`upperdir`).

`yum` is known to be affected unless the `yum-plugin-ovl` package is installed. If the `yum-plugin-ovl` package is not available in your distribution such as RHEL/CentOS prior to 6.8 or 7.2, you may need to run `touch /var/lib/rpm/*` before running `yum install`. This package implements the `touch` workaround referenced above for `yum`.

* [`rename(2)`](https://linux.die.net/man/2/rename)

  OverlayFS does not fully support the `rename(2)` system call. Your application needs to detect its failure and fall back to a "copy and unlink" strategy.

----
url: https://docs.docker.com/guides/testcontainers-python-getting-started/create-project/
----

# Create the Python project

***

Table of contents

***

## [Initialize the project](#initialize-the-project)

Start by creating a Python project with a virtual environment:

```console
$ mkdir tc-python-demo
$ cd tc-python-demo
$ python3 -m venv venv
$ source venv/bin/activate
```

This guide uses [psycopg3](https://www.psycopg.org/psycopg3/) to interact with the Postgres database, [pytest](https://pytest.org/) for testing, and [testcontainers-python](https://testcontainers-python.readthedocs.io/) for running a PostgreSQL database in a container.

Install the dependencies:

```console
$ pip install "psycopg[binary]" pytest testcontainers[postgres]
$ pip freeze > requirements.txt
```

The `pip freeze` command generates a `requirements.txt` file so that others can install the same package versions using `pip install -r requirements.txt`.

## [Create the database helper](#create-the-database-helper)

Create a `db/connection.py` file with a function to get a database connection:

```python
import os

import psycopg


def get_connection():
    host = os.getenv("DB_HOST", "localhost")
    port = os.getenv("DB_PORT", "5432")
    username = os.getenv("DB_USERNAME", "postgres")
    password = os.getenv("DB_PASSWORD", "postgres")
    database = os.getenv("DB_NAME", "postgres")
    return psycopg.connect(f"host={host} dbname={database} user={username} password={password} port={port}")
```

Instead of hard-coding the database connection parameters, the function uses environment variables. This makes it possible to run the application in different environments without changing code.

## [Create the business logic](#create-the-business-logic)

Create a `customers/customers.py` file and define the `Customer` class:

```python
class Customer:
    def __init__(self, cust_id, name, email):
        self.id = cust_id
        self.name = name
        self.email = email

    def __str__(self):
        return f"Customer({self.id}, {self.name}, {self.email})"
```

Add a `create_table()` function to create the `customers` table:

```python
from db.connection import get_connection


def create_table():
    with get_connection() as conn:
        with conn.cursor() as cur:
            cur.execute("""
                CREATE TABLE customers (
                    id serial PRIMARY KEY,
                    name varchar not null,
                    email varchar not null unique)
                """)
            conn.commit()
```

The function obtains a database connection using `get_connection()` and creates the `customers` table. The `with` statement automatically closes the connection when done.

Add the remaining CRUD functions:

```python
def create_customer(name, email):
    with get_connection() as conn:
        with conn.cursor() as cur:
            cur.execute(
                "INSERT INTO customers (name, email) VALUES (%s, %s)", (name, email))
            conn.commit()


def get_all_customers() -> list[Customer]:
    with get_connection() as conn:
        with conn.cursor() as cur:
            cur.execute("SELECT * FROM customers")
            return [Customer(cid, name, email) for cid, name, email in cur]


def get_customer_by_email(email) -> Customer:
    with get_connection() as conn:
        with conn.cursor() as cur:
            cur.execute("SELECT id, name, email FROM customers WHERE email = %s", (email,))
            (cid, name, email) = cur.fetchone()
            return Customer(cid, name, email)


def delete_all_customers():
    with get_connection() as conn:
        with conn.cursor() as cur:
            cur.execute("DELETE FROM customers")
            conn.commit()
```

> Note
>
> To keep it straightforward for this guide, each function creates a new connection. In a real-world application, use a connection pool to reuse connections.

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-python-getting-started/write-tests/)

----
url: https://docs.docker.com/reference/cli/docker/model/stop-runner/
----

# docker model stop-runner

***

| Description | Stop Docker Model Runner (Docker Engine only) |
| ----------- | --------------------------------------------- |
| Usage       | `docker model stop-runner`                    |

## [Description](#description)

This command stops the Docker Model Runner by removing the running containers, but preserves the container images on disk. Use this command when you want to temporarily stop the runner but plan to start it again later.

To completely remove the runner including images, use `docker model uninstall-runner --images` instead.

## [Options](#options)

| Option     | Default | Description                 |
| ---------- | ------- | --------------------------- |
| `--models` |         | Remove model storage volume |

----
url: https://docs.docker.com/guides/rag-ollama/develop/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Use containers for RAG development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a RAG application](https://docs.docker.com/guides/rag-ollama/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment to access all the services that your generative RAG application needs. This includes:

* Adding a local database
* Adding a local or remote LLM service

> Note
>
> You can see more samples of containerized GenAI applications in the [GenAI Stack](https://github.com/docker/genai-stack) demo applications.

## [Add a local database](#add-a-local-database)

You can use containers to set up local services, like a database. In this section, you'll explore the database service in the `docker-compose.yaml` file.

To run the database service:

1. In the cloned repository's directory, open the `docker-compose.yaml` file in an IDE or text editor.

2. In the `docker-compose.yaml` file, you'll see the following:

   ```yaml
   services:
     qdrant:
       image: qdrant/qdrant
       container_name: qdrant
       ports:
         - "6333:6333"
       volumes:
         - qdrant_data:/qdrant/storage
   ```

   > Note
   >
   > To learn more about Qdrant, see the [Qdrant Official Docker Image](https://hub.docker.com/r/qdrant/qdrant).

3. Start the application. Inside the `winy` directory, run the following command in a terminal.

   ```console
   $ docker compose up --build
   ```

4. Access the application. Open a browser and view the application at <http://localhost:8501>. You should see a simple Streamlit application.

5. Stop the application. In the terminal, press `ctrl`+`c` to stop the application.

## [Add a local or remote LLM service](#add-a-local-or-remote-llm-service)

The sample application supports both [Ollama](https://ollama.ai/). This guide provides instructions for the following scenarios:

* Run Ollama in a container
* Run Ollama outside of a container

While all platforms can use any of the previous scenarios, the performance and GPU support may vary. You can use the following guidelines to help you choose the appropriate option:

* Run Ollama in a container if you're on Linux, and using a native installation of the Docker Engine, or Windows 10/11, and using Docker Desktop, you have a CUDA-supported GPU, and your system has at least 8 GB of RAM.
* Run Ollama outside of a container if running Docker Desktop on a Linux Machine.

Choose one of the following options for your LLM service.

When running Ollama in a container, you should have a CUDA-supported GPU. While you can run Ollama in a container without a supported GPU, the performance may not be acceptable. Only Linux and Windows 11 support GPU access to containers.

To run Ollama in a container and provide GPU access:

1. Install the prerequisites.

   * For Docker Engine on Linux, install the [NVIDIA Container Toolkilt](https://github.com/NVIDIA/nvidia-container-toolkit).
   * For Docker Desktop on Windows 10/11, install the latest [NVIDIA driver](https://www.nvidia.com/Download/index.aspx) and make sure you are using the [WSL2 backend](https://docs.docker.com/desktop/features/wsl/#turn-on-docker-desktop-wsl-2)

2. The `docker-compose.yaml` file already contains the necessary instructions. In your own apps, you'll need to add the Ollama service in your `docker-compose.yaml`. The following is the updated `docker-compose.yaml`:

   ```yaml
   ollama:
     image: ollama/ollama
     container_name: ollama
     ports:
       - "8000:8000"
     deploy:
       resources:
         reservations:
           devices:
             - driver: nvidia
               count: 1
               capabilities: [gpu]
   ```

   > Note
   >
   > For more details about the Compose instructions, see [Turn on GPU access with Docker Compose](https://docs.docker.com/compose/how-tos/gpu-support/).

3. Once the Ollama container is up and running it is possible to use the `download_model.sh` inside the `tools` folder with this command:

   ```console
   . ./download_model.sh <model-name>
   ```

Pulling an Ollama model can take several minutes.

To run Ollama outside of a container:

1. [Install](https://github.com/jmorganca/ollama) and run Ollama on your host machine.

2. Pull the model to Ollama using the following command.

   ```console
   $ ollama pull llama2
   ```

3. Remove the `ollama` service from the `docker-compose.yaml` and update properly the connection variables in `winy` service:

   ```diff
   - OLLAMA=http://ollama:11434
   + OLLAMA=<your-url>
   ```

## [Run your RAG application](#run-your-rag-application)

At this point, you have the following services in your Compose file:

* Server service for your main RAG application
* Database service to store vectors in a Qdrant database
* (optional) Ollama service to run the LLM service

Once the application is running, open a browser and access the application at <http://localhost:8501>.

Depending on your system and the LLM service that you chose, it may take several minutes to answer.

## [Summary](#summary)

In this section, you learned how to set up a development environment to provide access all the services that your GenAI application needs.

Related information:

* [Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
* [Compose file reference](https://docs.docker.com/reference/compose-file/)
* [Ollama Docker image](https://hub.docker.com/r/ollama/ollama)
* [GenAI Stack demo applications](https://github.com/docker/genai-stack)

## [Next steps](#next-steps)

See samples of more GenAI applications in the [GenAI Stack demo applications](https://github.com/docker/genai-stack).

----
url: https://docs.docker.com/ai/sandboxes/faq/
----

# FAQ

***

Table of contents

***

## [Why do I need to sign in?](#why-do-i-need-to-sign-in)

Docker Sandboxes is built around the idea that you and your agents are a team. Signing in gives each sandbox a verified identity, which lets Docker:

* **Tie sandboxes to a real person.** Governance matters when agents can build containers, install packages, and push code. Your Docker identity is the anchor.
* **Enable team features.** Team-scale features like [organization governance](https://docs.docker.com/ai/sandboxes/security/governance/), shared environments, and audit logs need a concept of "who," and adding that later would be worse for everyone.
* **Authenticate against Docker infrastructure.** Sandboxes pull images, run daemons, and talk to Docker services. A Docker account makes that seamless.

Your Docker account email is only used for authentication, not marketing.

## [Can I enforce sandbox policies across my organization?](#can-i-enforce-sandbox-policies-across-my-organization)

Yes. Admins can centrally manage network and filesystem policies from the Docker Admin Console. Rules defined there apply to every sandbox in the organization and take precedence over local rules set with `sbx policy`. Admins can optionally delegate specific rule types back to local control so developers can add additional allow rules.

See [Organization governance](https://docs.docker.com/ai/sandboxes/security/governance/). This feature requires a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) to get started.

## [Does the CLI collect telemetry?](#does-the-cli-collect-telemetry)

The `sbx` CLI collects basic usage data about CLI invocations:

* Which command you ran
* Whether it succeeded or failed
* How long it took
* If you're signed in, your Docker username is included

Docker Sandboxes doesn't monitor sessions, read your prompts, or access your code. Your code stays in the sandbox and on your host.

To opt out of all analytics, set the `SBX_NO_TELEMETRY` environment variable:

```console
$ export SBX_NO_TELEMETRY=1
```

## [How do I set custom environment variables inside a sandbox?](#how-do-i-set-custom-environment-variables-inside-a-sandbox)

The [`sbx secret`](/reference/cli/sbx/secret/) command only supports a fixed set of [services](https://docs.docker.com/ai/sandboxes/security/credentials/#built-in-services) (Anthropic, OpenAI, GitHub, and others). If your agent needs an environment variable that isn't tied to a supported service, such as `BRAVE_API_KEY` or a custom internal token, write it to `/etc/sandbox-persistent.sh` inside the sandbox. This file is sourced on every shell login, so the variable persists across agent sessions for the sandbox's lifetime.

Use `sbx exec` to append the export:

```console
$ sbx exec -d <sandbox-name> bash -c "echo 'export BRAVE_API_KEY=your_key' >> /etc/sandbox-persistent.sh"
```

The `bash -c` wrapper is required so the `>>` redirect runs inside the sandbox instead of on your host.

> Note
>
> Unlike `sbx secret`, which injects credentials through a host-side proxy without exposing them to the agent, this approach stores the value inside the sandbox. The agent process can read it directly. Only use this for credentials where proxy-based injection isn't available.

Variables in `/etc/sandbox-persistent.sh` are sourced automatically when bash runs inside the sandbox, including interactive sessions and agents started with `sbx run`. If you run a command directly with `sbx exec <name> <command>`, the command runs without a shell, so the persistent environment file is not sourced. Wrap the command in `bash -c` to load the environment:

```console
$ sbx exec <sandbox-name> bash -c "your-command"
```

To verify the variable is set, open a shell in the sandbox:

```console
$ sbx exec -it <sandbox-name> bash
$ echo $BRAVE_API_KEY
```

## [Why do agents run without approval prompts?](#why-do-agents-run-without-approval-prompts)

The sandbox itself is the safety boundary. Because agents run inside an isolated microVM with [network policies](https://docs.docker.com/ai/sandboxes/security/policy/), [credential isolation](https://docs.docker.com/ai/sandboxes/security/credentials/), and no access to your host system outside the workspace, the usual reasons for approval prompts (preventing destructive commands, network access, file modifications) are handled by the sandbox isolation layers instead.

If you prefer to re-enable approval prompts, change the permission mode inside the session. Most agents let you switch permission modes after startup. In Claude Code, use the `/permissions` command to change the mode interactively.

To make approval prompts the default for every session, define a custom agent kit that overrides the agent's entrypoint to drop the permission-skipping flag. For example, a kit that launches Claude Code without `--dangerously-skip-permissions`:

claude-safe/spec.yaml

```yaml
schemaVersion: "1"
kind: agent
name: claude-safe
agent:
  image: "docker/sandbox-templates:claude-code-docker"
  entrypoint:
    run: [claude]
```

Run it with `sbx run claude-safe --kit ./claude-safe/`. See [Agent kits](https://docs.docker.com/ai/sandboxes/customize/kits/#agent-kits) for the full pattern.

## [How do I know if my agent is running in a sandbox?](#how-do-i-know-if-my-agent-is-running-in-a-sandbox)

Ask the agent. The agent can see whether or not it's running inside a sandbox. In Claude Code, use the `/btw` slash command to ask without interrupting an in-progress task:

```text
/btw are you running in a sandbox?
```

## [Why doesn't the sandbox use my user-level agent configuration?](#why-doesnt-the-sandbox-use-my-user-level-agent-configuration)

Sandboxes don't pick up user-level agent configuration from your host. This includes directories like `~/.claude` for Claude Code or `~/.codex` for Codex, where hooks, skills, and other settings are stored. Only project-level configuration in the working directory is available inside the sandbox.

To make configuration available in a sandbox, copy or move what you need into your project directory before starting a session:

```console
$ cp -r ~/.claude/skills .claude/skills
```

Don't use symlinks — a sandboxed agent can't follow symlinks to paths outside the sandbox.

Collocating skills and other agent configuration with the project itself is a good practice regardless of sandboxes. It's versioned alongside the code and evolves with the project as it changes.

----
url: https://docs.docker.com/reference/cli/docker/compose/events/
----

# docker compose events

***

| Description | Receive real time events from containers       |
| ----------- | ---------------------------------------------- |
| Usage       | `docker compose events [OPTIONS] [SERVICE...]` |

## [Description](#description)

Stream container events for every container in the project.

With the `--json` flag, a json object is printed one per line with the format:

```json
{
    "time": "2015-11-20T18:01:03.615550",
    "type": "container",
    "action": "create",
    "id": "213cf7...5fc39a",
    "service": "web",
    "attributes": {
      "name": "application_web_1",
      "image": "alpine:edge"
    }
}
```

The events that can be received using this can be seen [here](/reference/cli/docker/system/events/#object-types).

## [Options](#options)

| Option    | Default | Description                               |
| --------- | ------- | ----------------------------------------- |
| `--json`  |         | Output events as a stream of json objects |
| `--since` |         | Show all events created since timestamp   |
| `--until` |         | Stream events until this timestamp        |

----
url: https://docs.docker.com/guides/testcontainers-java-micronaut-wiremock/create-project/
----

# Create the Micronaut project

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Micronaut project from [Micronaut Launch](https://micronaut.io/launch) by selecting the **http-client**, **micronaut-test-rest-assured**, and **testcontainers** features.

Alternatively, clone the [guide repository](https://github.com/testcontainers/tc-guide-testing-rest-api-integrations-in-micronaut-apps-using-wiremock).

After generating the project, add the **WireMock** and **Testcontainers WireMock** libraries as test dependencies. The key dependencies in `pom.xml` are:

```xml
<parent>
    <groupId>io.micronaut.platform</groupId>
    <artifactId>micronaut-parent</artifactId>
    <version>4.1.2</version>
</parent>

<properties>
    <jdk.version>17</jdk.version>
    <micronaut.version>4.1.2</micronaut.version>
    <micronaut.runtime>netty</micronaut.runtime>
</properties>

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>io.micronaut</groupId>
        <artifactId>micronaut-http-client</artifactId>
        <scope>compile</scope>
    </dependency>
    <dependency>
        <groupId>io.micronaut</groupId>
        <artifactId>micronaut-http-server-netty</artifactId>
        <scope>compile</scope>
    </dependency>
    <dependency>
        <groupId>io.micronaut.serde</groupId>
        <artifactId>micronaut-serde-jackson</artifactId>
        <scope>compile</scope>
    </dependency>
    <dependency>
        <groupId>io.micronaut.test</groupId>
        <artifactId>micronaut-test-junit5</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.micronaut.test</groupId>
        <artifactId>micronaut-test-rest-assured</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.wiremock</groupId>
        <artifactId>wiremock-standalone</artifactId>
        <version>3.2.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.wiremock.integrations.testcontainers</groupId>
        <artifactId>wiremock-testcontainers-module</artifactId>
        <version>1.0-alpha-13</version>
        <scope>test</scope>
    </dependency>
</dependencies>
```

This guide builds an application that manages video albums. A third-party REST API handles photo assets. For demonstration purposes, the application uses the publicly available [JSONPlaceholder](https://jsonplaceholder.typicode.com/) API as a photo service.

The application exposes a `GET /api/albums/{albumId}` endpoint that calls the photo service to fetch photos for a given album. [WireMock](https://wiremock.org/) is a tool for building mock APIs. Testcontainers provides a [WireMock module](https://testcontainers.com/modules/wiremock/) that runs WireMock as a Docker container.

## [Create the Album and Photo models](#create-the-album-and-photo-models)

Create `Album.java` using Java records. Annotate both records with `@Serdeable` to allow serialization and deserialization:

```java
package com.testcontainers.demo;

import io.micronaut.serde.annotation.Serdeable;
import java.util.List;

@Serdeable
public record Album(Long albumId, List<Photo> photos) {}

@Serdeable
record Photo(Long id, String title, String url, String thumbnailUrl) {}
```

## [Create the PhotoServiceClient](#create-the-photoserviceclient)

Micronaut provides [declarative HTTP client](https://docs.micronaut.io/latest/guide/#httpClient) support. Create an interface with a method that fetches photos for a given album ID:

```java
package com.testcontainers.demo;

import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.PathVariable;
import io.micronaut.http.client.annotation.Client;
import java.util.List;

@Client(id = "photosapi")
interface PhotoServiceClient {

    @Get("/albums/{albumId}/photos")
    List<Photo> getPhotos(@PathVariable Long albumId);
}
```

The `@Client(id = "photosapi")` annotation ties this client to a named configuration. Add the following property to `src/main/resources/application.properties` to set the base URL:

```properties
micronaut.http.services.photosapi.url=https://jsonplaceholder.typicode.com
```

## [Create the REST API endpoint](#create-the-rest-api-endpoint)

Create `AlbumController.java`:

```java
package com.testcontainers.demo;

import static io.micronaut.scheduling.TaskExecutors.BLOCKING;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.PathVariable;
import io.micronaut.scheduling.annotation.ExecuteOn;

@Controller("/api")
class AlbumController {

    private final PhotoServiceClient photoServiceClient;

    AlbumController(PhotoServiceClient photoServiceClient) {
        this.photoServiceClient = photoServiceClient;
    }

    @ExecuteOn(BLOCKING)
    @Get("/albums/{albumId}")
    public Album getAlbumById(@PathVariable Long albumId) {
        return new Album(albumId, photoServiceClient.getPhotos(albumId));
    }
}
```

Here's what this controller does:

* `@Controller("/api")` maps the controller to the `/api` path.
* Constructor injection provides a `PhotoServiceClient` bean.
* `@ExecuteOn(BLOCKING)` offloads blocking I/O to a separate thread pool so it doesn't block the event loop.
* `@Get("/albums/{albumId}")` maps the `getAlbumById()` method to an HTTP GET request.

This endpoint calls the photo service for a given album ID and returns a response like:

```json
{
  "albumId": 1,
  "photos": [
    {
      "id": 51,
      "title": "non sunt voluptatem placeat consequuntur rem incidunt",
      "url": "https://via.placeholder.com/600/8e973b",
      "thumbnailUrl": "https://via.placeholder.com/150/8e973b"
    },
    {
      "id": 52,
      "title": "eveniet pariatur quia nobis reiciendis laboriosam ea",
      "url": "https://via.placeholder.com/600/121fa4",
      "thumbnailUrl": "https://via.placeholder.com/150/121fa4"
    }
  ]
}
```

[Write tests with WireMock and Testcontainers »](https://docs.docker.com/guides/testcontainers-java-micronaut-wiremock/write-tests/)

----
url: https://docs.docker.com/reference/cli/docker/context/
----

# docker context

***

| Description | Manage contexts  |
| ----------- | ---------------- |
| Usage       | `docker context` |

## [Description](#description)

Manage contexts.

## [Subcommands](#subcommands)

| Command                                                                                   | Description                                                       |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [`docker context create`](https://docs.docker.com/reference/cli/docker/context/create/)   | Create a context                                                  |
| [`docker context export`](https://docs.docker.com/reference/cli/docker/context/export/)   | Export a context to a tar archive FILE or a tar stream on STDOUT. |
| [`docker context import`](https://docs.docker.com/reference/cli/docker/context/import/)   | Import a context from a tar or zip file                           |
| [`docker context inspect`](https://docs.docker.com/reference/cli/docker/context/inspect/) | Display detailed information on one or more contexts              |
| [`docker context ls`](https://docs.docker.com/reference/cli/docker/context/ls/)           | List contexts                                                     |
| [`docker context rm`](https://docs.docker.com/reference/cli/docker/context/rm/)           | Remove one or more contexts                                       |
| [`docker context show`](https://docs.docker.com/reference/cli/docker/context/show/)       | Print the name of the current context                             |
| [`docker context update`](https://docs.docker.com/reference/cli/docker/context/update/)   | Update a context                                                  |
| [`docker context use`](https://docs.docker.com/reference/cli/docker/context/use/)         | Set the default docker context                                    |

----
url: https://docs.docker.com/guides/cpp/
----

# C++ language-specific guide

***

This guide explains how to containerize C++ applications using Docker.

**Time to complete** 20 minutes

The C++ getting started guide teaches you how to create a containerized C++ application using Docker. In this guide, you'll learn how to:

> **Acknowledgment**
>
> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) and [Mohammad-Ali A'râbi](https://twitter.com/MohammadAliEN) for their contribution to this guide.

* Containerize and run a C++ application using a multi-stage Docker build
* Build and run a C++ application using Docker Compose
* Set up a local environment to develop a C++ application using containers
* Configure a CI/CD pipeline for a containerized C++ application using GitHub Actions
* Deploy your containerized application locally to Kubernetes to test and debug your deployment
* Use BuildKit to generate SBOM attestations during the build process

After completing the C++ getting started modules, you should be able to containerize your own C++ application based on the examples and instructions provided in this guide.

Start by containerizing an existing C++ application.

## [Modules](#modules)

1. [Multi-stage build](https://docs.docker.com/guides/cpp/multistage/)

   Learn how to create a multi-stage build for a C++ application.

2. [Containerize](https://docs.docker.com/guides/cpp/containerize/)

   Learn how to use Docker Compose to build and run a C++ application.

3. [Develop your app](https://docs.docker.com/guides/cpp/develop/)

   Learn how to develop your C++ application locally.

4. [Configure CI/CD](https://docs.docker.com/guides/cpp/configure-ci-cd/)

   Learn how to configure CI/CD using GitHub Actions for your C++ application.

5. [Test your deployment](https://docs.docker.com/guides/cpp/deploy/)

   Learn how to develop locally using Kubernetes

6. [Supply-chain security](https://docs.docker.com/guides/cpp/security/)

   Learn how to extract SBOMs from C++ Docker images.

----
url: https://docs.docker.com/offload/
----

# Docker Offload

***

***

Subscription: Docker Offload

Requires: Docker Desktop 4.68 or later

Docker Offload is a fully managed service that lets you offload building and running containers to the cloud using the Docker tools you already know. It enables developers to work efficiently in virtual desktop infrastructure (VDI) environments or systems that don't support nested virtualization.

In the following topics, learn about Docker Offload, how to set it up, use it for your workflows, and troubleshoot common issues.

### [Quickstart](/offload/quickstart/)

[Get up and running with Docker Offload in just a few steps.](/offload/quickstart/)

### [About](/offload/about/)

[Learn about Docker Offload and how it works.](/offload/about/)

### [Configure](/offload/configuration/)

[Configure Docker Offload settings for your organization and Docker Desktop.](/offload/configuration/)

### [Usage](/offload/usage/)

[Learn about Docker Offload usage and how to monitor your cloud resources.](/offload/usage/)

### [Optimize](/offload/optimize/)

[Improve performance and cost efficiency in Docker Offload.](/offload/optimize/)

### [Troubleshoot](/offload/troubleshoot/)

[Learn how to troubleshoot issues with Docker Offload.](/offload/troubleshoot/)

### [Feedback](/offload/feedback/)

[Provide feedback on Docker Offload.](/offload/feedback/)

----
url: https://docs.docker.com/reference/cli/docker/desktop/disable/model-runner/
----

# docker desktop disable model-runner

***

| Description | Disable Docker Model Runner           |
| ----------- | ------------------------------------- |
| Usage       | `docker desktop disable model-runner` |

## [Description](#description)

Disable Docker Model Runner

----
url: https://docs.docker.com/guides/gha/
----

[Introduction to GitHub Actions with Docker](https://docs.docker.com/guides/gha/)

Learn how to automate image build and push with GitHub Actions.

DevOps

10 minutes

[« Back to all guides](/guides/)

# Introduction to GitHub Actions with Docker

***

Table of contents

***

This guide provides an introduction to building CI pipelines using Docker and GitHub Actions. You will learn how to use Docker's official GitHub Actions to build your application as a Docker image and push it to Docker Hub. By the end of the guide, you'll have a simple, functional GitHub Actions configuration for Docker builds. Use it as-is, or extend it further to fit your needs.

## [Prerequisites](#prerequisites)

If you want to follow along with the guide, ensure you have the following:

* A verified Docker account.
* Familiarity with Dockerfiles.

This guide assumes basic knowledge of Docker concepts but provides explanations for using Docker in GitHub Actions workflows.

## [Get the sample app](#get-the-sample-app)

This guide is project-agnostic and assumes you have an application with a Dockerfile.

If you need a sample project to follow along, you can use [this sample application](https://github.com/dvdksn/rpg-name-generator.git), which includes a Dockerfile for building a containerized version of the app. Alternatively, use your own GitHub project or create a new repository from the template.

```dockerfile
#syntax=docker/dockerfile:1

# builder installs dependencies and builds the node app
FROM node:lts-alpine AS builder
WORKDIR /src
RUN --mount=src=package.json,target=package.json \
    --mount=src=package-lock.json,target=package-lock.json \
    --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN --mount=type=cache,target=/root/.npm \
    npm run build

# release creates the runtime image
FROM node:lts-alpine AS release
WORKDIR /app
COPY --from=builder /src/build .
EXPOSE 3000
CMD ["node", "."]
```

## [Configure your GitHub repository](#configure-your-github-repository)

The workflow in this guide pushes the image you build to Docker Hub. To do that, you must authenticate with your Docker credentials (username and access token) as part of the GitHub Actions workflow.

For instructions on how to create a Docker access token, see [Create and manage access tokens](https://docs.docker.com/security/access-tokens/).

Once you have your Docker credentials ready, add the credentials to your GitHub repository so you can use them in GitHub Actions:

1. Open your repository's **Settings**.
2. Under **Security**, go to **Secrets and variables > Actions**.
3. Under **Secrets**, create a new repository secret named `DOCKER_PASSWORD`, containing your Docker access token.
4. Next, under **Variables**, create a `DOCKER_USERNAME` repository variable containing your Docker Hub username.

## [Set up your GitHub Actions workflow](#set-up-your-github-actions-workflow)

GitHub Actions workflows define a series of steps to automate tasks, such as building and pushing Docker images, in response to triggers like commits or pull requests. In this guide, the workflow focuses on automating Docker builds and testing, ensuring your containerized application works correctly before publishing it.

Create a file named `docker-ci.yml` in the `.github/workflows/` directory of your repository. Start with the basic workflow configuration:

```yaml
name: Build and Push Docker Image

on:
  push:
    branches:
      - main
  pull_request:
```

This configuration runs the workflow on pushes to the main branch and on pull requests. By including both triggers, you can ensure that the image builds correctly for a pull request before it's merged.

## [Extract metadata for tags and annotations](#extract-metadata-for-tags-and-annotations)

For the first step in your workflow, use the `docker/metadata-action` to generate metadata for your image. This action extracts information about your Git repository, such as branch names and commit SHAs, and generates image metadata such as tags and annotations.

Add the following YAML to your workflow file:

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Extract Docker image metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ vars.DOCKER_USERNAME }}/my-image
```

These steps prepare metadata to tag and annotate your images during the build and push process.

* The **Checkout** step clones the Git repository.
* The **Extract Docker image metadata** step extracts Git metadata and generates image tags and annotations for the Docker build.

## [Authenticate to your registry](#authenticate-to-your-registry)

Before you build the image, authenticate to your registry to ensure that you can push your built image to the registry.

To authenticate with Docker Hub, add the following step to your workflow:

```yaml
      - name: Log in to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}
```

This step uses the Docker credentials [configured in the repository settings](#configure-your-github-repository).

## [Build and push the image](#build-and-push-the-image)

Finally, build the final production image and push it to your registry. The following configuration builds the image and pushes it directly to a registry.

```yaml
      - name: Build and push Docker image
        uses: docker/build-push-action@v7
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
```

In this configuration:

* `push: ${{ github.event_name != 'pull_request' }}` ensures that images are only pushed when the event is not a pull request. This way, the workflow builds and tests images for pull requests but only pushes images for commits to the main branch.
* `tags` and `annotations` use the outputs from the metadata action to apply consistent tags and [annotations](https://docs.docker.com/build/metadata/annotations/) to the image automatically.

## [Attestations](#attestations)

SBOM (Software Bill of Materials) and provenance attestations improve security and traceability, ensuring your images meet modern software supply chain requirements.

With a small amount of additional configuration, you can configure `docker/build-push-action` to generate Software Bill of Materials (SBOM) and provenance attestations for the image, at build-time.

To generate this additional metadata, you need to make two changes to your workflow:

* Before the build step, add a step that uses `docker/setup-buildx-action`. This action configures your Docker build client with additional capabilities that the default client doesn't support.
* Then, update the **Build and push Docker image** step to also enable SBOM and provenance attestations.

Here's the updated snippet:

```yaml
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
      
      - name: Build and push Docker image
        uses: docker/build-push-action@v7
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          provenance: true
          sbom: true
```

For more details about attestations, refer to [the documentation](https://docs.docker.com/build/metadata/attestations/).

## [Conclusion](#conclusion)

With all the steps outlined in the previous section, here's the full workflow configuration:

```yaml
name: Build and Push Docker Image

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Extract Docker image metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ vars.DOCKER_USERNAME }}/my-image

      - name: Log in to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
      
      - name: Build and push Docker image
        uses: docker/build-push-action@v7
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          provenance: true
          sbom: true
```

This workflow implements best practices for building and pushing Docker images using GitHub Actions. This configuration can be used as-is or extended with additional features based on your project's needs, such as [multi-platform](https://docs.docker.com/build/building/multi-platform/).

### [Further reading](#further-reading)

* Learn more about advanced configurations and examples in the [Docker Build GitHub Actions](https://docs.docker.com/build/ci/github-actions/) section.
* For more complex build setups, you may want to consider [Bake](https://docs.docker.com/build/bake/). (See also the [Mastering Buildx Bake guide](https://docs.docker.com/guides/bake/).)
* Learn about Docker's managed build service, designed for faster, multi-platform builds, see [Docker Build Cloud](https://docs.docker.com/guides/docker-build-cloud/).

----
url: https://docs.docker.com/reference/api/extensions-sdk/DesktopUI/
----

# Interface: DesktopUI

***

Table of contents

***

**`Since`**

0.2.0

## [Properties](#properties)

### [toast](#toast)

• `Readonly` **toast**: [`Toast`](https://docs.docker.com/reference/api/extensions-sdk/Toast/)

***

### [dialog](#dialog)

• `Readonly` **dialog**: [`Dialog`](https://docs.docker.com/reference/api/extensions-sdk/Dialog/)

***

### [navigate](#navigate)

• `Readonly` **navigate**: [`NavigationIntents`](https://docs.docker.com/reference/api/extensions-sdk/NavigationIntents/)

----
url: https://docs.docker.com/ai/sandboxes/security/defaults/
----

# Default security posture

***

Table of contents

***

A sandbox created with `sbx run` and no additional flags has the following security posture.

## [Network defaults](#network-defaults)

All outbound HTTP and HTTPS traffic is blocked unless an explicit rule allows it (deny-by-default). All non-HTTP protocols (raw TCP, UDP including DNS, and ICMP) are blocked at the network layer. Traffic to private IP ranges, loopback addresses, and link-local addresses is also blocked.

Run `sbx policy ls` to see the active network rules for your installation. To customize network access, see [Policies](https://docs.docker.com/ai/sandboxes/security/policy/). If your organization manages sandbox policies centrally, those rules apply on top of the defaults described here. See [Organization governance](https://docs.docker.com/ai/sandboxes/security/governance/).

## [Workspace defaults](#workspace-defaults)

Sandboxes use a direct mount by default. The agent sees and modifies your working tree directly, and changes appear on your host immediately.

The agent can read, write, and delete any file within the workspace directory, including hidden files, configuration files, build scripts, and Git hooks. See [Workspace isolation](https://docs.docker.com/ai/sandboxes/security/isolation/#workspace-isolation) for what to review after an agent session.

## [Credential defaults](#credential-defaults)

No credentials are available to the sandbox unless you provide them using `sbx secret` or environment variables. When credentials are provided, the host-side proxy injects them into outbound HTTP headers. The agent cannot read the raw credential values.

See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for setup instructions.

## [Agent capabilities inside the sandbox](#agent-capabilities-inside-the-sandbox)

The agent runs with full control inside the sandbox VM:

* `sudo` access (the agent runs as a non-root user with sudo privileges)
* A private Docker Engine for building images and running containers
* Package installation through `apt`, `pip`, `npm`, and other package managers
* Full read and write access to the VM filesystem

Everything the agent installs or creates inside the VM, including packages, Docker images, and configuration changes, persists across stop and restart cycles. When you remove the sandbox with `sbx rm`, the VM and its contents are deleted. Only workspace files remain on the host.

## [What is blocked by default](#what-is-blocked-by-default)

The following are blocked for all sandboxes and cannot be changed through policy configuration:

* Host filesystem access outside the workspace directory
* Host Docker daemon
* Host network and localhost
* Communication between sandboxes
* Raw TCP, UDP, and ICMP connections
* Traffic to private IP ranges and link-local addresses

Outbound HTTP/HTTPS to domains not in the allow list is also blocked by default, but you can add allow rules with `sbx policy allow`.

----
url: https://docs.docker.com/guides/testcontainers-java-spring-boot-rest-api/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

```console
$ ./mvnw test
```

Or with Gradle:

```console
$ ./gradlew test
```

You should see the Postgres Docker container start and all tests pass. After the tests finish, the container stops and is removed automatically.

## [Summary](#summary)

The Testcontainers library helps you write integration tests by using the same type of database (Postgres) that you use in production, instead of mocks or in-memory databases. Because you test against real services, you're free to refactor code and still verify that the application works as expected.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/)
* [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/)
* [Testcontainers JDBC support](https://java.testcontainers.org/modules/databases/jdbc/)

----
url: https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-registry/
----

# What is a registry?

***

Table of contents

***

## [Explanation](#explanation)

Now that you know what a container image is and how it works, you might wonder - where do you store these images?

Well, you can store your container images on your computer system, but what if you want to share them with your friends or use them on another machine? That's where the image registry comes in.

An image registry is a centralized location for storing and sharing your container images. It can be either public or private. [Docker Hub](https://hub.docker.com) is a public registry that anyone can use and is the default registry.

While Docker Hub is a popular option, there are many other available container registries available today, including [Amazon Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/), [Azure Container Registry (ACR)](https://azure.microsoft.com/en-in/products/container-registry), and [Google Container Registry (GCR)](https://cloud.google.com/artifact-registry). You can even run your private registry on your local system or inside your organization. For example, Harbor, JFrog Artifactory, GitLab Container registry etc.

### [Registry vs. repository](#registry-vs-repository)

While you're working with registries, you might hear the terms *registry* and *repository* as if they're interchangeable. Even though they're related, they're not quite the same thing.

A *registry* is a centralized location that stores and manages container images, whereas a *repository* is a collection of related container images within a registry. Think of it as a folder where you organize your images based on projects. Each repository contains one or more container images.

The following diagram shows the relationship between a registry, repositories, and images.

```
```

> Tip
>
> A Docker Personal plan gives you one private repository and unlimited public repositories. To get unlimited private repositories, upgrade to the [Docker Team plan](https://www.docker.com/pricing?ref=Docs\&refAction=DocsConceptsRegistry).

## [Try it out](#try-it-out)

In this hands-on, you will learn how to build and push a Docker image to the Docker Hub repository.

### [Sign up for a free Docker account](#sign-up-for-a-free-docker-account)

1. If you haven't created one yet, head over to the [Docker Hub](https://hub.docker.com) page to sign up for a new Docker account. Be sure to finish the verification steps sent to your email.

   You can use your Google or GitHub account to authenticate.

### [Create your first repository](#create-your-first-repository)

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select the **Create repository** button in the top-right corner.

3. Select your namespace (most likely your username) and enter `docker-quickstart` as the repository name.

4. Set the visibility to **Public**.

5. Select the **Create** button to create the repository.

That's it. You've successfully created your first repository. 🎉

This repository is empty right now. You'll now fix this by pushing an image to it.

### [Sign in with Docker Desktop](#sign-in-with-docker-desktop)

1. [Download and install](https://www.docker.com/products/docker-desktop/) Docker Desktop, if not already installed.
2. In the Docker Desktop GUI, select the **Sign in** button in the top-right corner

### [Clone sample Node.js code](#clone-sample-nodejs-code)

In order to create an image, you first need a project. To get you started quickly, you'll use a sample Node.js project found at [github.com/dockersamples/helloworld-demo-node](https://github.com/dockersamples/helloworld-demo-node). This repository contains a pre-built Dockerfile necessary for building a Docker image.

Don't worry about the specifics of the Dockerfile, as you'll learn about that in later sections.

1. Clone the GitHub repository using the following command:

   ```console
   git clone https://github.com/dockersamples/helloworld-demo-node
   ```

2. Navigate into the newly created directory.

   ```console
   cd helloworld-demo-node
   ```

3. Run the following command to build a Docker image, swapping out `YOUR_DOCKER_USERNAME` with your username.

   ```console
   docker build -t YOUR_DOCKER_USERNAME/docker-quickstart .
   ```

   > Note
   >
   > Make sure you include the dot (.) at the end of the `docker build` command. This tells Docker where to find the Dockerfile.

4. Run the following command to list the newly created Docker image:

   ```console
   docker images
   ```

   You will see output like the following:

   ```console
   REPOSITORY                                 TAG       IMAGE ID       CREATED         SIZE
   YOUR_DOCKER_USERNAME/docker-quickstart   latest    476de364f70e   2 minutes ago   170MB
   ```

5. Start a container to test the image by running the following command (swap out the username with your own username):

   ```console
   docker run -d -p 8080:8080 YOUR_DOCKER_USERNAME/docker-quickstart
   ```

   You can verify if the container is working by visiting <http://localhost:8080> with your browser.

6. Use the [`docker tag`](/reference/cli/docker/image/tag/) command to tag the Docker image. Docker tags allow you to label and version your images.

   ```console
   docker tag YOUR_DOCKER_USERNAME/docker-quickstart YOUR_DOCKER_USERNAME/docker-quickstart:1.0
   ```

7. Finally, it's time to push the newly built image to your Docker Hub repository by using the [`docker push`](/reference/cli/docker/image/push/) command:

   ```console
   docker push YOUR_DOCKER_USERNAME/docker-quickstart:1.0
   ```

8. Open [Docker Hub](https://hub.docker.com) and navigate to your repository. Navigate to the **Tags** section and see your newly pushed image.

In this walkthrough, you signed up for a Docker account, created your first Docker Hub repository, and built, tagged, and pushed a container image to your Docker Hub repository.

## [Additional resources](#additional-resources)

* [Docker Hub Quickstart](/docker-hub/quickstart/)
* [Manage Docker Hub Repositories](/docker-hub/repos/)

## [Next steps](#next-steps)

Now that you understand the basics of containers and images, you're ready to learn about Docker Compose.

[What is Docker Compose?](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-docker-compose/)

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/push/
----

# docker mcp profile push

***

| Description | Push profile to OCI registry                           |
| ----------- | ------------------------------------------------------ |
| Usage       | `docker mcp profile push <profile-id> <oci-reference>` |

## [Description](#description)

Push profile to OCI registry

----
url: https://docs.docker.com/desktop/setup/install/linux/fedora/
----

# Install Docker Desktop on Fedora

***

Table of contents

***

> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250 employees OR more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopFedoraInstall).

This page contains information on how to install, launch and upgrade Docker Desktop on a Fedora distribution.

## [Prerequisites](#prerequisites)

To install Docker Desktop successfully, you must:

* Meet the [general system requirements](https://docs.docker.com/desktop/setup/install/linux/#general-system-requirements).

* Have a 64-bit version of Fedora 42 or Fedora 43.

* For a GNOME desktop environment you must install AppIndicator and KStatusNotifierItem [GNOME extensions](https://extensions.gnome.org/extension/615/appindicator-support/).

* If you're not using GNOME, you must install `gnome-terminal` to enable terminal access from Docker Desktop:

  ```console
  $ sudo dnf install gnome-terminal
  ```

## [Install Docker Desktop](#install-docker-desktop)

To install Docker Desktop on Fedora:

1. Set up [Docker's package repository](https://docs.docker.com/engine/install/fedora/#set-up-the-repository).

2. Download the latest [RPM package](https://desktop.docker.com/linux/main/amd64/docker-desktop-x86_64.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64). For checksums, see the [Release notes](https://docs.docker.com/desktop/release-notes/).

3. Install the package with dnf as follows:

   ```console
   $ sudo dnf install ./docker-desktop-x86_64.rpm
   ```

   By default, Docker Desktop is installed at `/opt/docker-desktop`.

The RPM package includes a post-install script that completes additional setup steps automatically.

```console
$ systemctl --user start docker-desktop
```

When Docker Desktop starts, it creates a dedicated [context](/engine/context/working-with-contexts) that the Docker CLI can use as a target and sets it as the current context in use. This is to avoid a clash with a local Docker Engine that may be running on the Linux host and using the default context. On shutdown, Docker Desktop resets the current context to the previous one.

The Docker Desktop installer updates Docker Compose and the Docker CLI binaries on the host. It installs Docker Compose V2 and gives users the choice to link it as docker-compose from the Settings panel. Docker Desktop installs the new Docker CLI binary that includes cloud-integration capabilities in `/usr/local/bin/com.docker.cli` and creates a symlink to the classic Docker CLI at `/usr/local/bin`.

After you’ve successfully installed Docker Desktop, you can check the versions of these binaries by running the following commands:

```console
$ docker compose version
Docker Compose version v2.39.4

$ docker --version
Docker version 28.4.0, build d8eb465

$ docker version
Client:
 Version:           28.4.0
 API version:       1.51
 Go version:        go1.24.7
<...>
```

To enable Docker Desktop to start on sign in, from the Docker menu, select **Settings** > **General** > **Start Docker Desktop when you sign in to your computer**.

Alternatively, open a terminal and run:

```console
$ systemctl --user enable docker-desktop
```

To stop Docker Desktop, select the Docker menu icon to open the Docker menu and select **Quit Docker Desktop**.

Alternatively, open a terminal and run:

```console
$ systemctl --user stop docker-desktop
```

## [Upgrade Docker Desktop](#upgrade-docker-desktop)

Once a new version for Docker Desktop is released, the Docker UI shows a notification. You need to first remove the previous version and then download the new package each time you want to upgrade Docker Desktop. Run:

```console
$ sudo dnf remove docker-desktop
$ sudo dnf install ./docker-desktop-x86_64.rpm
```

## [Next steps](#next-steps)

* Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopFedoraInstall) to see what Docker can offer you.
* Take a look at the [Docker workshop](https://docs.docker.com/get-started/workshop/) to learn how to build an image and run it as a containerized application.
* [Explore Docker Desktop](https://docs.docker.com/desktop/use-desktop/) and all its features.
* [Troubleshooting](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/) describes common problems, workarounds, how to run and submit diagnostics, and submit issues.
* [FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/general/) provide answers to frequently asked questions.
* [Release notes](https://docs.docker.com/desktop/release-notes/) lists component updates, new features, and improvements associated with Docker Desktop releases.
* [Back up and restore data](https://docs.docker.com/desktop/settings-and-maintenance/backup-and-restore/) provides instructions on backing up and restoring data related to Docker.

----
url: https://docs.docker.com/guides/postgresql/companions-for-postgresql/
----

# Companions for PostgreSQL

***

Table of contents

***

## [PostgreSQL ecosystem companions: pgAdmin, PgBouncer, and performance testing](#postgresql-ecosystem-companions-pgadmin-pgbouncer-and-performance-testing)

Running a standalone PostgreSQL container is often just the beginning. What happens when thousands of connections arrive, or when you need a visual interface to manage your database?

This is where **companion tools** come into play. These applications extend PostgreSQL with capabilities the core database engine doesn't provide natively: visual administration, connection pooling, and performance benchmarking. This guide covers how to deploy pgAdmin 4, PgBouncer, Pgpool-II, and `pgbench` in Docker, when to use each tool, and real-world benchmark results demonstrating their performance impact.

## [pgAdmin 4: Visual management platform](#pgadmin-4-visual-management-platform)

pgAdmin 4 is the industry-standard open source management tool for PostgreSQL. When deployed in Docker, it typically runs in **Server Mode**, providing a multi-user web interface to manage one or more database instances.

While you can accomplish everything from the command line using `psql`, a visual interface significantly simplifies writing complex queries, visualizing table structures, and exploring database objects.

### [Key considerations](#key-considerations)

When running pgAdmin in Docker, keep these points in mind:

* **Image**: Use the official `dpage/pgadmin4` image
* **Networking**: In a Docker Compose environment, pgAdmin connects to the database using the internal service name (for example, `db:5432`) rather than `localhost`

### [Docker Compose configuration](#docker-compose-configuration)

To quickly deploy pgAdmin:

```yaml
pgadmin:
  image: dpage/pgadmin4:8.14
  environment:
    PGADMIN_DEFAULT_EMAIL: admin@example.com
    PGADMIN_DEFAULT_PASSWORD: secure_password
  volumes:
    - pgadmin_data:/var/lib/pgadmin
  ports:
    - "8080:80"
```

With this configuration, access the pgAdmin interface at `http://localhost:8080`. Use the email and password specified in the environment variables for initial sign in.

> Important
>
> In production environments, pass `PGADMIN_DEFAULT_PASSWORD` as an external environment variable or use Docker secrets. Storing passwords in plain text within `docker-compose.yml` poses a security risk.

Now that you have visual database management in place, the next challenge in production environments is handling connection load. The following section explains how to manage high-volume database traffic.

## [PgBouncer: Lightweight connection pooling](#pgbouncer-lightweight-connection-pooling)

PostgreSQL creates a new process for every client connection, which consumes significant RAM. What happens when you have 1,000 concurrent users? PgBouncer solves exactly this problem.

PgBouncer is a lightweight proxy that pools connections, allowing thousands of applications to share a small number of actual database backends. Think of it as a traffic controller: everyone wants to pass through simultaneously, but the controller regulates the flow to prevent congestion.

### [Pooling modes](#pooling-modes)

PgBouncer offers three distinct pooling modes:

| Mode            | Description                                     | Use case                                        |
| --------------- | ----------------------------------------------- | ----------------------------------------------- |
| **Session**     | Connection assigned for entire session duration | Long-lived connections, session variables       |
| **Transaction** | Connection returned after each transaction ends | Web applications, microservices (most common)   |
| **Statement**   | Connection returned after every SQL statement   | Simple queries, no multi-statement transactions |

### [When to use PgBouncer](#when-to-use-pgbouncer)

PgBouncer becomes essential when you encounter:

* "too many connections" errors
* High memory consumption due to connection overhead
* Many short-lived connections (web applications, serverless functions)
* Need to serve thousands of clients with limited database connections

### [Complete Docker Compose setup](#complete-docker-compose-setup)

To run PostgreSQL and PgBouncer together, you need three files: `docker-compose.yml`, `pgbouncer.ini`, and `userlist.txt`.

First, create the PgBouncer configuration file (`pgbouncer.ini`):

```bash
[databases]
benchmark = host=postgres port=5432 dbname=benchmark user=postgres

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = trust
auth_file = /etc/pgbouncer/userlist.txt
admin_users = postgres
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 50
min_pool_size = 10
reserve_pool_size = 10
max_db_connections = 100
```

Next, create the user authentication file (`userlist.txt`):

```bash
"postgres" "postgres"
```

Finally, create the Docker Compose file (`docker-compose.yml`):

```yaml
services:
  postgres:
    image: postgres:18
    container_name: postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: benchmark
      POSTGRES_HOST_AUTH_METHOD: trust
    volumes:
      - postgres_data:/var/lib/postgresql
    ports:
      - "5432:5432"
    networks:
      - pgnet
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  pgbouncer:
    image: percona/percona-pgbouncer:1.25.0
    container_name: pgbouncer
    volumes:
      - ./pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini
      - ./userlist.txt:/etc/pgbouncer/userlist.txt
    ports:
      - "6432:6432"
    networks:
      - pgnet
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:

networks:
  pgnet:
    driver: bridge
```

Key configuration notes:

* `PgBouncer` listens on port **6432**, avoiding confusion with the direct PostgreSQL connection on port 5432
* The `depends_on` directive with `service_healthy` condition ensures PgBouncer starts only after PostgreSQL is ready
* `pool_mode = transaction` is the optimal choice for most web applications
* The [Percona PgBouncer image](https://hub.docker.com/r/percona/percona-pgbouncer) requires mounted configuration files (without the `:ro` flag, as the entrypoint script needs to modify them)
* This example uses `trust` authentication for simplicity. In production, configure proper SCRAM-SHA-256 authentication

> Note
>
> The `Percona PgBouncer` entrypoint script processes the configuration files on startup. Mount them without the read-only flag to avoid permission errors.

## [`pgbench`: Performance benchmarking](#pgbench-performance-benchmarking)

`pgbench` is a benchmarking utility included with the official PostgreSQL image. It allows you to simulate heavy workloads and verify how your Docker configuration performs under pressure.

### [Initialize benchmark tables](#initialize-benchmark-tables)

First, create the test tables. The `-s` (scale) parameter determines data size—scale factor 50 creates approximately 5 million rows:

```bash
docker exec postgres pgbench -i -s 50 -U postgres benchmark
```

### [Run stress tests](#run-stress-tests)

Key parameters:

* `-c`: Number of simulated clients
* `-j`: Number of threads
* `-T`: Duration in seconds

Test with direct PostgreSQL connection:

```bash
docker exec postgres pgbench -h localhost -U postgres -c 50 -j 4 -T 60 benchmark
```

Test through PgBouncer:

```bash
docker exec postgres pgbench -h pgbouncer -p 6432 -U postgres -c 50 -j 4 -T 60 benchmark
```

## [Understanding benchmark results](#understanding-benchmark-results)

Does PgBouncer actually make a difference? Run the benchmarks yourself to find out. Your results will vary based on your hardware, Docker configuration, network setup, and system load.

### [What to expect](#what-to-expect)

When you run these benchmarks, you'll observe patterns rather than specific numbers. Think of it like comparing two different routes to work: the "faster" route depends on traffic conditions, time of day, and your vehicle.

### [Key observations](#key-observations)

When comparing direct connections versus PgBouncer, you'll typically notice:

#### [1. Connection overhead differs significantly](#1-connection-overhead-differs-significantly)

Direct connections require PostgreSQL to spawn a new process for each client. PgBouncer reuses existing connections. Watch the "initial connection time" metric in your results—PgBouncer often shows dramatically faster connection setup.

#### [2. Behavior under pressure reveals the real difference](#2-behavior-under-pressure-reveals-the-real-difference)

Try increasing the client count (`-c` parameter) gradually: 50, 100, 150, 200. At some point, direct connections will fail with "too many clients already" while PgBouncer continues handling requests. This is PgBouncer's primary value: **it prevents connection exhaustion**.

#### [3. Throughput varies by environment](#3-throughput-varies-by-environment)

On some systems, direct connections show higher transactions per second (TPS) at low concurrency. On others, PgBouncer wins even with few clients. The difference depends on:

* CPU and memory available
* Docker networking overhead
* Disk I/O speed
* Whether connections are being rapidly opened and closed

----
url: https://docs.docker.com/desktop/use-desktop/resource-saver/
----

# Docker Desktop's Resource Saver mode

***

Table of contents

***

Resource Saver mode significantly reduces Docker Desktop's CPU and memory utilization on the host by 2 GBs or more, by automatically stopping the Docker Desktop Linux VM when no containers are running for a period of time. The default time is set to 5 minutes, but this can be adjusted to suit your needs.

With Resource Saver mode, Docker Desktop uses minimal system resources when it's idle, thereby allowing you to save battery life on your laptop and improve your multi-tasking experience.

## [Configure Resource Saver](#configure-resource-saver)

Resource Saver is enabled by default but can be disabled by navigating to the **Resources** tab, in **Settings**. You can also configure the idle timer as shown below.

If the values available aren't sufficient for your needs, you can reconfigure it to any value, as long as the value is larger than 30 seconds, by changing `autoPauseTimeoutSeconds` in the Docker Desktop `settings-store.json` file (or `settings.json` for Docker Desktop versions 4.34 and earlier):

* Mac: `~/Library/Group Containers/group.com.docker/settings-store.json`
* Windows: `C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json`
* Linux: `~/.docker/desktop/settings-store.json`

There's no need to restart Docker Desktop after reconfiguring.

When Docker Desktop enters Resource Saver mode:

* A moon icon displays on the Docker Desktop status bar as well as on the Docker icon in the system tray.
* Docker commands that don't run containers, for example listing container images or volumes, don't necessarily trigger an exit from Resource Saver mode as Docker Desktop can serve such commands without unnecessarily waking up the Linux VM.

> Note
>
> Docker Desktop exits the Resource Saver mode automatically when it needs to. Commands that cause an exit from Resource Saver take a little longer to execute (about 3 to 10 seconds) as Docker Desktop restarts the Linux VM. It's generally faster on Mac and Linux, and slower on Windows with Hyper-V. Once the Linux VM is restarted, subsequent container runs occur immediately as usual.

## [Resource Saver mode versus Pause](#resource-saver-mode-versus-pause)

Resource Saver has higher precedence than the older [Pause](https://docs.docker.com/desktop/use-desktop/pause/) feature, meaning that while Docker Desktop is in Resource Saver mode, manually pausing Docker Desktop is not possible (nor does it make sense since Resource Saver actually stops the Docker Desktop Linux VM). In general, we recommend keeping Resource Saver enabled as opposed to disabling it and using the manual Pause feature, as it results in much better CPU and memory savings.

## [Resource Saver mode on Windows](#resource-saver-mode-on-windows)

Resource Saver works a bit differently on Windows with WSL. Instead of stopping the WSL VM, it only pauses the Docker Engine inside the `docker-desktop` WSL distribution. That's because in WSL there's a single Linux VM shared by all WSL distributions, so Docker Desktop can't stop the Linux VM (i.e., the WSL Linux VM is not owned by Docker Desktop). As a result, Resource Saver reduces CPU utilization on WSL, but it does not reduce Docker's memory utilization.

To reduce memory utilization on WSL, we instead recommend that users enable WSL's `autoMemoryReclaim` feature as described in the [Docker Desktop WSL docs](https://docs.docker.com/desktop/features/wsl/). Finally, since Docker Desktop does not stop the Linux VM on WSL, exit from Resource Saver mode is immediate (there's no exit delay).

----
url: https://docs.docker.com/reference/cli/docker/compose/alpha/scale/
----

# docker compose alpha scale

***

| Description | Scale services                                     |
| ----------- | -------------------------------------------------- |
| Usage       | `docker compose alpha scale [SERVICE=REPLICAS...]` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Scale services

## [Options](#options)

| Option      | Default | Description                  |
| ----------- | ------- | ---------------------------- |
| `--no-deps` |         | Don't start linked services. |

----
url: https://docs.docker.com/reference/cli/sbx/policy/allow/network/
----

# sbx policy allow network

| Description | Allow network access to specified hosts                      |
| ----------- | ------------------------------------------------------------ |
| Usage       | `sbx policy allow network [-g \| SANDBOX] RESOURCES [flags]` |

## [Description](#description)

Allow sandbox network access to the specified hosts.

RESOURCES is a comma-separated list of hostnames, domains, or IP addresses. Supports exact domains (example.com), wildcard subdomains (\*.example.com), and optional port suffixes (example.com:443). Use "\*\*" to allow all hosts.

Use -g/--global to apply the rule globally to all sandboxes, or provide SANDBOX before RESOURCES to add the rule to policy "local" scoped to that sandbox.

## [Options](#options)

| Option         | Default | Description                              |
| -------------- | ------- | ---------------------------------------- |
| `-g, --global` |         | Apply the rule globally to all sandboxes |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Allow access to a single host globally
sbx policy allow network -g api.example.com

# Allow access to multiple hosts globally
sbx policy allow network -g "api.example.com,cdn.example.com"

# Allow a host only for a specific sandbox
sbx policy allow network my-sandbox api.example.com

# Allow all subdomains of a host
sbx policy allow network -g "*.npmjs.org"

# Allow all outbound traffic globally
sbx policy allow network -g "**"
```

----
url: https://docs.docker.com/reference/cli/docker/config/ls/
----

# docker config ls

***

| Description                                                               | List configs                 |
| ------------------------------------------------------------------------- | ---------------------------- |
| Usage                                                                     | `docker config ls [OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker config list`         |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Run this command on a manager node to list the configs in the Swarm.

For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).

> Note
>
> This is a cluster management command, and must be executed on a Swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --filter`](#filter) |         | Filter output based on conditions provided                                                                                                                                                                                                                                                                                                                                             |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-q, --quiet`             |         | Only display IDs                                                                                                                                                                                                                                                                                                                                                                       |

## [Examples](#examples)

```console
$ docker config ls

ID                          NAME                        CREATED             UPDATED
6697bflskwj1998km1gnnjr38   q5s5570vtvnimefos1fyeo2u2   6 weeks ago         6 weeks ago
9u9hk4br2ej0wgngkga6rp4hq   my_config                   5 weeks ago         5 weeks ago
mem02h8n73mybpgqjf0kfi1n0   test_config                 3 seconds ago       3 seconds ago
```

### [Filtering (-f, --filter)](#filter)

The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)

The currently supported filters are:

* [id](#id) (config's ID)
* [label](#label) (`label=<key>` or `label=<key>=<value>`)
* [name](#name) (config's name)

#### [id](#id)

The `id` filter matches all or prefix of a config's id.

```console
$ docker config ls -f "id=6697bflskwj1998km1gnnjr38"

ID                          NAME                        CREATED             UPDATED
6697bflskwj1998km1gnnjr38   q5s5570vtvnimefos1fyeo2u2   6 weeks ago         6 weeks ago
```

#### [label](#label)

The `label` filter matches configs based on the presence of a `label` alone or a `label` and a value.

The following filter matches all configs with a `project` label regardless of its value:

```console
$ docker config ls --filter label=project

ID                          NAME                        CREATED             UPDATED
mem02h8n73mybpgqjf0kfi1n0   test_config                 About an hour ago   About an hour ago
```

The following filter matches only services with the `project` label with the `project-a` value.

```console
$ docker config ls --filter label=project=project-a

ID                          NAME                        CREATED             UPDATED
mem02h8n73mybpgqjf0kfi1n0   test_config                 About an hour ago   About an hour ago
```

#### [name](#name)

The `name` filter matches on all or prefix of a config's name.

The following filter matches config with a name containing a prefix of `test`.

```console
$ docker config ls --filter name=test

ID                          NAME                        CREATED             UPDATED
mem02h8n73mybpgqjf0kfi1n0   test_config                 About an hour ago   About an hour ago
```

### [Format the output (--format)](#format)

The formatting option (`--format`) pretty prints configs output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder  | Description                                                                    |
| ------------ | ------------------------------------------------------------------------------ |
| `.ID`        | Config ID                                                                      |
| `.Name`      | Config name                                                                    |
| `.CreatedAt` | Time when the config was created                                               |
| `.UpdatedAt` | Time when the config was updated                                               |
| `.Labels`    | All labels assigned to the config                                              |
| `.Label`     | Value of a specific label for this config. For example `{{.Label "my-label"}}` |

When using the `--format` option, the `config ls` command will either output the data exactly as the template declares or, when using the `table` directive, will include column headers as well.

The following example uses a template without headers and outputs the `ID` and `Name` entries separated by a colon (`:`) for all images:

```console
$ docker config ls --format "{{.ID}}: {{.Name}}"

77af4d6b9913: config-1
b6fa739cedf5: config-2
78a85c484f71: config-3
```

To list all configs with their name and created date in a table format you can use:

```console
$ docker config ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}"

ID                  NAME                      CREATED
77af4d6b9913        config-1                  5 minutes ago
b6fa739cedf5        config-2                  3 hours ago
78a85c484f71        config-3                  10 days ago
```

----
url: https://docs.docker.com/guides/python/configure-github-actions/
----

# Automate your builds with GitHub Actions

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a Python application](https://docs.docker.com/guides/python/containerize/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

```yaml
name: Build and push Docker image

on:
  push:
    branches:
      - main

jobs:
  lint-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      
      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.14'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt

      - name: Run pre-commit hooks
        run: pre-commit run --all-files

      - name: Run pyright
        run: pyright

  build_and_push:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
```

In this section, you learned how to set up a GitHub Actions workflow for your Python application that includes:

* Running pre-commit hooks for linting and formatting
* Static type checking with Pyright
* Building and pushing Docker images

Related information:

* [Introduction to GitHub Actions](https://docs.docker.com/guides/gha/)
* [Docker Build GitHub Actions](https://docs.docker.com/build/ci/github-actions/)
* [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)

## [Next steps](#next-steps)

In the next section, you'll learn how you can develop locally using kubernetes.

[Test your Python deployment »](https://docs.docker.com/guides/python/deploy/)

----
url: https://docs.docker.com/reference/cli/docker/scout/vex/
----

# docker scout vex

***

| Description                                                               | Manage VEX attestations on images |
| ------------------------------------------------------------------------- | --------------------------------- |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker scout vex`                |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Manage VEX attestations on images

## [Subcommands](#subcommands)

| Command                                                                               | Description                   |
| ------------------------------------------------------------------------------------- | ----------------------------- |
| [`docker scout vex get`](https://docs.docker.com/reference/cli/docker/scout/vex/get/) | Get VEX attestation for image |

----
url: https://docs.docker.com/reference/cli/docker/scout/repo/enable/
----

# docker scout repo enable

***

| Description | Enable Docker Scout                     |
| ----------- | --------------------------------------- |
| Usage       | `docker scout repo enable [REPOSITORY]` |

## [Description](#description)

The docker scout repo enable command enables Docker Scout on repositories.

## [Options](#options)

| Option          | Default | Description                                                                  |
| --------------- | ------- | ---------------------------------------------------------------------------- |
| `--all`         |         | Enable all repositories of the organization. Can not be used with --filter.  |
| `--filter`      |         | Regular expression to filter repositories by name                            |
| `--integration` |         | Name of the integration to use for enabling an image                         |
| `--org`         |         | Namespace of the Docker organization                                         |
| `--registry`    |         | Container Registry                                                           |

## [Examples](#examples)

### [Enable a specific repository](#enable-a-specific-repository)

```console
$ docker scout repo enable my/repository
```

### [Enable all repositories of the organization](#enable-all-repositories-of-the-organization)

```console
$ docker scout repo enable --all
```

### [Enable some repositories based on a filter](#enable-some-repositories-based-on-a-filter)

```console
$ docker scout repo enable --filter namespace/backend
```

### [Enable a repository from a specific registry](#enable-a-repository-from-a-specific-registry)

```console
$ docker scout repo enable my/repository --registry 123456.dkr.ecr.us-east-1.amazonaws.com
```

----
url: https://docs.docker.com/reference/cli/docker/compose/pull/
----

# docker compose pull

***

| Description | Pull service images                          |
| ----------- | -------------------------------------------- |
| Usage       | `docker compose pull [OPTIONS] [SERVICE...]` |

## [Description](#description)

Pulls an image associated with a service defined in a `compose.yaml` file, but does not start containers based on those images

## [Options](#options)

| Option                   | Default | Description                                            |
| ------------------------ | ------- | ------------------------------------------------------ |
| `--ignore-buildable`     |         | Ignore images that can be built                        |
| `--ignore-pull-failures` |         | Pull what it can and ignores images with pull failures |
| `--include-deps`         |         | Also pull services declared as dependencies            |
| `--policy`               |         | Apply pull policy ("missing"\|"always")                |
| `-q, --quiet`            |         | Pull without printing progress information             |

## [Examples](#examples)

Consider the following `compose.yaml`:

```yaml
services:
  db:
    image: postgres
  web:
    build: .
    command: bundle exec rails s -p 3000 -b '0.0.0.0'
    volumes:
      - .:/myapp
    ports:
      - "3000:3000"
    depends_on:
      - db
```

If you run `docker compose pull ServiceName` in the same directory as the `compose.yaml` file that defines the service, Docker pulls the associated image. For example, to call the postgres image configured as the db service in our example, you would run `docker compose pull db`.

```console
$ docker compose pull db
[+] Running 1/15
 ⠸ db Pulling                                                             12.4s
   ⠿ 45b42c59be33 Already exists                                           0.0s
   ⠹ 40adec129f1a Downloading  3.374MB/4.178MB                             9.3s
   ⠹ b4c431d00c78 Download complete                                        9.3s
   ⠹ 2696974e2815 Download complete                                        9.3s
   ⠹ 564b77596399 Downloading  5.622MB/7.965MB                             9.3s
   ⠹ 5044045cf6f2 Downloading  216.7kB/391.1kB                             9.3s
   ⠹ d736e67e6ac3 Waiting                                                  9.3s
   ⠹ 390c1c9a5ae4 Waiting                                                  9.3s
   ⠹ c0e62f172284 Waiting                                                  9.3s
   ⠹ ebcdc659c5bf Waiting                                                  9.3s
   ⠹ 29be22cb3acc Waiting                                                  9.3s
   ⠹ f63c47038e66 Waiting                                                  9.3s
   ⠹ 77a0c198cde5 Waiting                                                  9.3s
   ⠹ c8752d5b785c Waiting                                                  9.3s
```

`docker compose pull` tries to pull image for services with a build section. If pull fails, it lets you know this service image must be built. You can skip this by setting `--ignore-buildable` flag.

----
url: https://docs.docker.com/engine/cli/completion/
----

# Completion

***

Table of contents

***

You can generate a shell completion script for the Docker CLI using the `docker completion` command. The completion script gives you word completion for commands, flags, and Docker objects (such as container and volume names) when you hit `<Tab>` as you type into your terminal.

You can generate completion scripts for the following shells:

* [Bash](#bash)
* [Zsh](#zsh)
* [fish](#fish)

## [Bash](#bash)

To get Docker CLI completion with Bash, you first need to install the `bash-completion` package which contains a number of Bash functions for shell completion.

```bash
# Install using APT:
sudo apt install bash-completion

# Install using Homebrew (Bash version 4 or later):
brew install bash-completion@2
# Homebrew install for older versions of Bash:
brew install bash-completion

# With pacman:
sudo pacman -S bash-completion
```

After installing `bash-completion`, source the script in your shell configuration file (in this example, `.bashrc`):

```bash
# On Linux:
cat <<EOT >> ~/.bashrc
if [ -f /etc/bash_completion ]; then
    . /etc/bash_completion
fi
EOT

# On macOS / with Homebrew:
cat <<EOT >> ~/.bash_profile
[[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && . "$(brew --prefix)/etc/profile.d/bash_completion.sh"
EOT
```

And reload your shell configuration:

```console
$ source ~/.bashrc
```

Now you can generate the Bash completion script using the `docker completion` command:

```console
$ mkdir -p ~/.local/share/bash-completion/completions
$ docker completion bash > ~/.local/share/bash-completion/completions/docker
```

## [Zsh](#zsh)

The Zsh [completion system](http://zsh.sourceforge.net/Doc/Release/Completion-System.html) takes care of things as long as the completion can be sourced using `FPATH`.

If you use Oh My Zsh, you can install completions without modifying `~/.zshrc` by storing the completion script in the `~/.oh-my-zsh/completions` directory.

```console
$ mkdir -p ~/.oh-my-zsh/completions
$ docker completion zsh > ~/.oh-my-zsh/completions/_docker
```

If you're not using Oh My Zsh, store the completion script in a directory of your choice and add the directory to `FPATH` in your `.zshrc`.

```console
$ mkdir -p ~/.docker/completions
$ docker completion zsh > ~/.docker/completions/_docker
```

```console
$ cat <<"EOT" >> ~/.zshrc
FPATH="$HOME/.docker/completions:$FPATH"
autoload -Uz compinit
compinit
EOT
```

## [Fish](#fish)

fish shell supports a [completion system](https://fishshell.com/docs/current/#tab-completion) natively. To activate completion for Docker commands, copy or symlink the completion script to your fish shell `completions/` directory:

```console
$ mkdir -p ~/.config/fish/completions
$ docker completion fish > ~/.config/fish/completions/docker.fish
```

----
url: https://docs.docker.com/security/faqs/containers/
----

# Container security FAQs

***

Table of contents

***

## [How are containers isolated from the host in Docker Desktop?](#how-are-containers-isolated-from-the-host-in-docker-desktop)

Docker Desktop runs all containers inside a customized Linux virtual machine (except for native Windows containers). This adds strong isolation between containers and the host machine, even when containers run as root.

Important considerations include:

* Containers have access to host files configured for file sharing via Docker Desktop settings
* Containers run as root with limited capabilities inside the Docker Desktop VM by default
* Privileged containers (`--privileged`, `--pid=host`, `--cap-add`) run with elevated privileges inside the VM, giving them access to VM internals and Docker Engine

With Enhanced Container Isolation turned on, each container runs in a dedicated Linux user namespace inside the Docker Desktop VM. Even privileged containers only have privileges within their container boundary, not the VM. ECI uses advanced techniques to prevent containers from breaching the Docker Desktop VM and Docker Engine.

## [Which portions of the host filesystem can containers access?](#which-portions-of-the-host-filesystem-can-containers-access)

Containers can only access host files that are:

1. Shared using Docker Desktop settings
2. Explicitly bind-mounted into the container (e.g., `docker run -v /path/to/host/file:/mnt`)

## [Can containers running as root access admin-owned files on the host?](#can-containers-running-as-root-access-admin-owned-files-on-the-host)

No. Host file sharing uses a user-space file server (running in `com.docker.backend` as the Docker Desktop user), so containers can only access files that the Docker Desktop user already has permission to access.

----
url: https://docs.docker.com/guides/testcontainers-dotnet-aspnet-core/write-tests/
----

# Write tests with Testcontainers

***

Table of contents

***

The existing tests use an in-memory SQLite database. While convenient, this doesn't match production behavior. You can replace it with a real Microsoft SQL Server instance managed by Testcontainers.

## [Add dependencies](#add-dependencies)

Change to the test project directory and add the SQL Server Entity Framework provider and the Testcontainers MSSQL module:

```console
$ cd tests/RazorPagesProject.Tests
$ dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 7.0.0
$ dotnet add package Testcontainers.MsSql --version 3.0.0
```

> Note
>
> Testcontainers for .NET offers a range of [modules](https://www.nuget.org/profiles/Testcontainers) that follow best practice configurations.

## [Create the test class](#create-the-test-class)

Create a `MsSqlTests.cs` file in the `IntegrationTests` directory. This class manages the SQL Server container lifecycle and contains a nested test class.

```csharp
using System.Data.Common;
using System.Net;
using AngleSharp.Html.Dom;
using Microsoft.AspNetCore.Mvc.Testing;
using Microsoft.EntityFrameworkCore;
using RazorPagesProject.Data;
using RazorPagesProject.Tests.Helpers;
using Testcontainers.MsSql;
using Xunit;

namespace RazorPagesProject.Tests.IntegrationTests;

public sealed class MsSqlTests : IAsyncLifetime
{
    private readonly MsSqlContainer _msSqlContainer = new MsSqlBuilder().Build();

    public Task InitializeAsync()
    {
        return _msSqlContainer.StartAsync();
    }

    public Task DisposeAsync()
    {
        return _msSqlContainer.DisposeAsync().AsTask();
    }

    public sealed class IndexPageTests : IClassFixture<MsSqlTests>, IDisposable
    {
        private readonly WebApplicationFactory<Program> _webApplicationFactory;

        private readonly HttpClient _httpClient;

        public IndexPageTests(MsSqlTests fixture)
        {
            var clientOptions = new WebApplicationFactoryClientOptions();
            clientOptions.AllowAutoRedirect = false;

            _webApplicationFactory = new CustomWebApplicationFactory(fixture);
            _httpClient = _webApplicationFactory.CreateClient(clientOptions);
        }

        public void Dispose()
        {
            _webApplicationFactory.Dispose();
        }

        [Fact]
        public async Task Post_DeleteAllMessagesHandler_ReturnsRedirectToRoot()
        {
            // Arrange
            var defaultPage = await _httpClient.GetAsync("/")
                .ConfigureAwait(false);

            var document = await HtmlHelpers.GetDocumentAsync(defaultPage)
                .ConfigureAwait(false);

            // Act
            var form = (IHtmlFormElement)document.QuerySelector("form[id='messages']");
            var submitButton = (IHtmlButtonElement)document.QuerySelector("button[id='deleteAllBtn']");

            var response = await _httpClient.SendAsync(form, submitButton)
                .ConfigureAwait(false);

            // Assert
            Assert.Equal(HttpStatusCode.OK, defaultPage.StatusCode);
            Assert.Equal(HttpStatusCode.Redirect, response.StatusCode);
            Assert.Equal("/", response.Headers.Location.OriginalString);
        }

        private sealed class CustomWebApplicationFactory : WebApplicationFactory<Program>
        {
            private readonly string _connectionString;

            public CustomWebApplicationFactory(MsSqlTests fixture)
            {
                _connectionString = fixture._msSqlContainer.GetConnectionString();
            }

            protected override void ConfigureWebHost(IWebHostBuilder builder)
            {
                builder.ConfigureServices(services =>
                {
                    services.Remove(services.SingleOrDefault(service => typeof(DbContextOptions<ApplicationDbContext>) == service.ServiceType));
                    services.Remove(services.SingleOrDefault(service => typeof(DbConnection) == service.ServiceType));
                    services.AddDbContext<ApplicationDbContext>((_, option) => option.UseSqlServer(_connectionString));
                });
            }
        }
    }
}
```

## [Understand the test structure](#understand-the-test-structure)

### [Container lifecycle with IAsyncLifetime](#container-lifecycle-with-iasynclifetime)

The outer `MsSqlTests` class implements `IAsyncLifetime`. xUnit calls `InitializeAsync()` right after creating the class instance, which starts the SQL Server container. After all tests complete, `DisposeAsync()` stops and removes the container.

```csharp
private readonly MsSqlContainer _msSqlContainer = new MsSqlBuilder().Build();
```

`MsSqlBuilder().Build()` creates a pre-configured Microsoft SQL Server container. Testcontainers modules follow best practices, so you don't need to configure ports, passwords, or startup wait strategies yourself.

### [Nested test class with IClassFixture](#nested-test-class-with-iclassfixture)

The `IndexPageTests` class is nested inside `MsSqlTests` and implements `IClassFixture<MsSqlTests>`. This gives the test class access to the container's private field and creates a clean hierarchy in the test explorer.

### [Custom WebApplicationFactory](#custom-webapplicationfactory)

Instead of using the SQLite-based factory, the nested `CustomWebApplicationFactory` retrieves the connection string from the running SQL Server container and passes it to `UseSqlServer()`:

```csharp
private sealed class CustomWebApplicationFactory : WebApplicationFactory<Program>
{
    private readonly string _connectionString;

    public CustomWebApplicationFactory(MsSqlTests fixture)
    {
        _connectionString = fixture._msSqlContainer.GetConnectionString();
    }

    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureServices(services =>
        {
            services.Remove(services.SingleOrDefault(service => typeof(DbContextOptions<ApplicationDbContext>) == service.ServiceType));
            services.Remove(services.SingleOrDefault(service => typeof(DbConnection) == service.ServiceType));
            services.AddDbContext<ApplicationDbContext>((_, option) => option.UseSqlServer(_connectionString));
        });
    }
}
```

This factory:

1. Removes the existing `DbContextOptions<ApplicationDbContext>` registration
2. Removes the existing `DbConnection` registration
3. Adds a new `ApplicationDbContext` configured with the SQL Server connection string from the Testcontainers-managed container

> Note
>
> The Microsoft SQL Server Docker image isn't compatible with ARM devices, such as Macs with Apple Silicon. You can use the [SqlEdge](https://www.nuget.org/packages/Testcontainers.SqlEdge) module or [Testcontainers Cloud](https://www.testcontainers.cloud/) as alternatives.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-dotnet-aspnet-core/run-tests/)

----
url: https://docs.docker.com/guides/testcontainers-cloud/common-questions/
----

# Common challenges and questions

***

Table of contents

***

### [How is Testcontainers Cloud different from the open-source Testcontainers framework?](#how-is-testcontainers-cloud-different-from-the-open-source-testcontainers-framework)

While the open-source Testcontainers is a library that provides a lightweight APIs for bootstrapping local development and test dependencies with real services wrapped in Docker containers, Testcontainers Cloud provides a cloud runtime for these containers. This reduces the resource strain on local environments and provides more scalability, especially in CI/CD workflows, that enables consistent Testcontainers experience across the organization.

### [What types of containers can I run with Testcontainers Cloud?](#what-types-of-containers-can-i-run-with-testcontainers-cloud)

Testcontainers Cloud supports any containers you would typically use with the Testcontainers framework, including databases (PostgreSQL, MySQL, MongoDB), message brokers (Kafka, RabbitMQ), and other services required for integration testing.

### [Do I need to change my existing test code to use Testcontainers Cloud?](#do-i-need-to-change-my-existing-test-code-to-use-testcontainers-cloud)

No, you don't need to change your existing test code. Testcontainers Cloud integrates seamlessly with the open-source Testcontainers framework. Once the cloud configuration is set up, it automatically manages the containers in the cloud without requiring code changes.

### [How do I integrate Testcontainers Cloud into my project?](#how-do-i-integrate-testcontainers-cloud-into-my-project)

To integrate Testcontainers Cloud, you need to install the Testcontainers Desktop app and select run with Testcontainers Cloud option in the menu. In CI you’ll need to add a workflow step that downloads Testcontainers Cloud agent. No code changes are required beyond enabling Cloud runtime via the Testcontainers Desktop app locally or installing Testcontainers Cloud agent in CI.

### [Can I use Testcontainers Cloud in a CI/CD pipeline?](#can-i-use-testcontainers-cloud-in-a-cicd-pipeline)

Yes, Testcontainers Cloud is designed to work efficiently in CI/CD pipelines. It helps reduce build times and resource bottlenecks by offloading containers that you spin up with Testcontainers library to the cloud, making it a perfect fit for continuous testing environments.

### [What are the benefits of using Testcontainers Cloud?](#what-are-the-benefits-of-using-testcontainers-cloud)

The key benefits include reduced resource usage on local machines and CI servers, scalability (run more containers without performance degradation), consistent testing environments, centralized monitoring, ease of CI configuration with removed security concerns of running Docker-in-Docker or a privileged daemon.

### [Does Testcontainers Cloud support all programming languages?](#does-testcontainers-cloud-support-all-programming-languages)

Testcontainers Cloud supports any language that works with the open-source Testcontainers libraries, including Java, Python, Node.js, Go, and others. As long as your project uses Testcontainers, it can be offloaded to Testcontainers Cloud.

### [How is container cleanup handled in Testcontainers Cloud?](#how-is-container-cleanup-handled-in-testcontainers-cloud)

While Testcontainers library automatically handles container lifecycle management, Testcontainers Cloud manages the allocated cloud worker lifetime. This means that containers are spun up, monitored, and cleaned up after tests are completed by Testcontainers library, and the worker where these containers have being running will be removed automatically after the \~35 min idle period by Testcontainers Cloud. This approach frees developers from manually managing containers and associated cloud resources.

### [Is there a free tier or pricing model for Testcontainers Cloud?](#is-there-a-free-tier-or-pricing-model-for-testcontainers-cloud)

Pricing details for Testcontainers Cloud can be found on the [pricing page](https://testcontainers.com/cloud/pricing/).

----
url: https://docs.docker.com/reference/cli/sbx/completion/zsh/
----

# sbx completion zsh

| Description | Generate the autocompletion script for zsh |
| ----------- | ------------------------------------------ |
| Usage       | `sbx completion zsh [flags]`               |

## [Description](#description)

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

```
echo "autoload -U compinit; compinit" >> ~/.zshrc
```

To load completions in your current shell session:

```
source <(sbx completion zsh)
```

To load completions for every new session, execute once:

#### [Linux:](#linux)

```
sbx completion zsh > "${fpath[1]}/_sbx"
```

#### [macOS:](#macos)

```
sbx completion zsh > $(brew --prefix)/share/zsh/site-functions/_sbx
```

You will need to start a new shell for this setup to take effect.

## [Options](#options)

| Option              | Default | Description                     |
| ------------------- | ------- | ------------------------------- |
| `--no-descriptions` |         | disable completion descriptions |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/reference/cli/docker/dhi/auth/
----

# docker dhi auth

***

| Description | Authenticate with Docker Hub |
| ----------- | ---------------------------- |

## [Description](#description)

Commands to authenticate with Docker Hub

## [Subcommands](#subcommands)

| Command                                                                             | Description                                            |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [`docker dhi auth apk`](https://docs.docker.com/reference/cli/docker/dhi/auth/apk/) | Create authentication details for DHI APK repositories |
| [`docker dhi auth deb`](https://docs.docker.com/reference/cli/docker/dhi/auth/deb/) | Create authentication details for DHI DEB repositories |

----
url: https://docs.docker.com/reference/cli/docker/compose/port/
----

# docker compose port

***

| Description | Print the public port for a port binding             |
| ----------- | ---------------------------------------------------- |
| Usage       | `docker compose port [OPTIONS] SERVICE PRIVATE_PORT` |

## [Description](#description)

Prints the public port for a port binding

## [Options](#options)

| Option       | Default | Description                                             |
| ------------ | ------- | ------------------------------------------------------- |
| `--index`    |         | Index of the container if service has multiple replicas |
| `--protocol` | `tcp`   | tcp or udp                                              |

----
url: https://docs.docker.com/reference/cli/docker/volume/create/
----

# docker volume create

***

| Description | Create a volume                           |
| ----------- | ----------------------------------------- |
| Usage       | `docker volume create [OPTIONS] [VOLUME]` |

## [Description](#description)

Creates a new volume that containers can consume and store data in. If a name is not specified, Docker generates a random name.

## [Options](#options)

| Option                 | Default  | Description                                                                             |
| ---------------------- | -------- | --------------------------------------------------------------------------------------- |
| `--availability`       | `active` | API 1.42+ Swarm Cluster Volume availability (`active`, `pause`, `drain`)                |
| `-d, --driver`         | `local`  | Specify volume driver name                                                              |
| `--group`              |          | API 1.42+ Swarm Cluster Volume group (cluster volumes)                                  |
| `--label`              |          | Set metadata for a volume                                                               |
| `--limit-bytes`        |          | API 1.42+ Swarm Minimum size of the Cluster Volume in bytes                             |
| [`-o, --opt`](#opt)    |          | Set driver specific options                                                             |
| `--required-bytes`     |          | API 1.42+ Swarm Maximum size of the Cluster Volume in bytes                             |
| `--scope`              | `single` | API 1.42+ Swarm Cluster Volume access scope (`single`, `multi`)                         |
| `--secret`             |          | API 1.42+ Swarm Cluster Volume secrets                                                  |
| `--sharing`            | `none`   | API 1.42+ Swarm Cluster Volume access sharing (`none`, `readonly`, `onewriter`, `all`)  |
| `--topology-preferred` |          | API 1.42+ Swarm A topology that the Cluster Volume would be preferred in                |
| `--topology-required`  |          | API 1.42+ Swarm A topology that the Cluster Volume must be accessible from              |
| `--type`               | `block`  | API 1.42+ Swarm Cluster Volume access type (`mount`, `block`)                           |

## [Examples](#examples)

Create a volume and then configure the container to use it:

```console
$ docker volume create hello

hello

$ docker run -d -v hello:/world busybox ls /world
```

The mount is created inside the container's `/world` directory. Docker doesn't support relative paths for mount points inside the container.

Multiple containers can use the same volume. This is useful if two containers need access to shared data. For example, if one container writes and the other reads the data.

Volume names must be unique among drivers. This means you can't use the same volume name with two different drivers. Attempting to create two volumes with the same name results in an error:

```console
A volume named  "hello"  already exists with the "some-other" driver. Choose a different volume name.
```

If you specify a volume name already in use on the current driver, Docker assumes you want to reuse the existing volume and doesn't return an error.

### [Driver-specific options (-o, --opt)](#opt)

Some volume drivers may take options to customize the volume creation. Use the `-o` or `--opt` flags to pass driver options:

```console
$ docker volume create --driver fake \
    --opt tardis=blue \
    --opt timey=wimey \
    foo
```

These options are passed directly to the volume driver. Options for different volume drivers may do different things (or nothing at all).

The built-in `local` driver accepts no options on Windows. On Linux and with Docker Desktop, the `local` driver accepts options similar to the Linux `mount` command. You can provide multiple options by passing the `--opt` flag multiple times. Some `mount` options (such as the `o` option) can take a comma-separated list of options. Complete list of available mount options can be found [here](https://man7.org/linux/man-pages/man8/mount.8.html).

For example, the following creates a `tmpfs` volume called `foo` with a size of 100 megabyte and `uid` of 1000.

```console
$ docker volume create --driver local \
    --opt type=tmpfs \
    --opt device=tmpfs \
    --opt o=size=100m,uid=1000 \
    foo
```

Another example that uses `btrfs`:

```console
$ docker volume create --driver local \
    --opt type=btrfs \
    --opt device=/dev/sda2 \
    foo
```

Another example that uses `nfs` to mount the `/path/to/dir` in `rw` mode from `192.168.1.1`:

```console
$ docker volume create --driver local \
    --opt type=nfs \
    --opt o=addr=192.168.1.1,rw \
    --opt device=:/path/to/dir \
    foo
```

----
url: https://docs.docker.com/build/concepts/context/
----

# Build context

***

Table of contents

***

The `docker build` and `docker buildx build` commands build Docker images from a [Dockerfile](https://docs.docker.com/reference/dockerfile/) and a context.

## [What is a build context?](#what-is-a-build-context)

The build context is the set of files that your build can access. The positional argument that you pass to the build command specifies the context that you want to use for the build:

```console
$ docker build [OPTIONS] PATH | URL | -
                         ^^^^^^^^^^^^^^
```

You can pass any of the following inputs as the context for a build:

* The relative or absolute path to a local directory
* A remote URL of a Git repository, tarball, or plain-text file
* A plain-text file or tarball piped to the `docker build` command through standard input

### [Filesystem contexts](#filesystem-contexts)

When your build context is a local directory, a remote Git repository, or a tar file, then that becomes the set of files that the builder can access during the build. Build instructions such as `COPY` and `ADD` can refer to any of the files and directories in the context.

A filesystem build context is processed recursively:

* When you specify a local directory or a tarball, all subdirectories are included
* When you specify a remote Git repository, the repository and all submodules are included

For more information about the different types of filesystem contexts that you can use with your builds, see:

* [Local files](#local-context)
* [Git repositories](#git-repositories)
* [Remote tarballs](#remote-tarballs)

### [Text file contexts](#text-file-contexts)

When your build context is a plain-text file, the builder interprets the file as a Dockerfile. With this approach, the build doesn't use a filesystem context.

For more information, see [empty build context](#empty-context).

## [Local context](#local-context)

To use a local build context, you can specify a relative or absolute filepath to the `docker build` command. The following example shows a build command that uses the current directory (`.`) as a build context:

```console
$ docker build .
...
#16 [internal] load build context
#16 sha256:23ca2f94460dcbaf5b3c3edbaaa933281a4e0ea3d92fe295193e4df44dc68f85
#16 transferring context: 13.16MB 2.2s done
...
```

This makes files and directories in the current working directory available to the builder. The builder loads the files it needs from the build context when needed.

You can also use local tarballs as build context, by piping the tarball contents to the `docker build` command. See [Tarballs](#local-tarballs).

### [Local directories](#local-directories)

Consider the following directory structure:

```text
.
├── index.ts
├── src/
├── Dockerfile
├── package.json
└── package-lock.json
```

Dockerfile instructions can reference and include these files in the build if you pass this directory as a context.

```dockerfile
# syntax=docker/dockerfile:1
FROM node:latest
WORKDIR /src
COPY package.json package-lock.json .
RUN npm ci
COPY index.ts src .
```

```console
$ docker build .
```

### [Local context with Dockerfile from stdin](#local-context-with-dockerfile-from-stdin)

Use the following syntax to build an image using files on your local filesystem, while using a Dockerfile from stdin.

```console
$ docker build -f- PATH
```

The syntax uses the -f (or --file) option to specify the Dockerfile to use, and it uses a hyphen (-) as filename to instruct Docker to read the Dockerfile from stdin.

The following example uses the current directory (.) as the build context, and builds an image using a Dockerfile passed through stdin using a here-document.

```bash
# create a directory to work in
mkdir example
cd example

# create an example file
touch somefile.txt

# build an image using the current directory as context
# and a Dockerfile passed through stdin
docker build -t myimage:latest -f- . <<EOF
FROM busybox
COPY somefile.txt ./
RUN cat /somefile.txt
EOF
```

### [Local tarballs](#local-tarballs)

When you pipe a tarball to the build command, the build uses the contents of the tarball as a filesystem context.

For example, given the following project directory:

```text
.
├── Dockerfile
├── Makefile
├── README.md
├── main.c
├── scripts
├── src
└── test.Dockerfile
```

You can create a tarball of the directory and pipe it to the build for use as a context:

```console
$ tar czf foo.tar.gz *
$ docker build - < foo.tar.gz
```

The build resolves the Dockerfile from the tarball context. You can use the `--file` flag to specify the name and location of the Dockerfile relative to the root of the tarball. The following command builds using `test.Dockerfile` in the tarball:

```console
$ docker build --file test.Dockerfile - < foo.tar.gz
```

## [Remote context](#remote-context)

You can specify the address of a remote Git repository, tarball, or plain-text file as your build context.

* For Git repositories, the builder automatically clones the repository. See [Git repositories](#git-repositories).
* For tarballs, the builder downloads and extracts the contents of the tarball. See [Tarballs](#remote-tarballs).

If the remote tarball is a text file, the builder receives no [filesystem context](#filesystem-contexts), and instead assumes that the remote file is a Dockerfile. See [Empty build context](#empty-context).

### [Git repositories](#git-repositories)

When you pass a URL pointing to the location of a Git repository as an argument to `docker build`, the builder uses the repository as the build context.

The builder performs a shallow clone of the repository, downloading only the HEAD commit, not the entire history.

The builder recursively clones the repository and any submodules it contains.

```console
$ docker build https://github.com/user/myrepo.git
```

By default, the builder clones the latest commit on the default branch of the repository that you specify.

#### [URL fragments](#url-fragments)

You can append URL fragments to the Git repository address to make the builder clone a specific branch, tag, and subdirectory of a repository.

The format of the URL fragment is `#ref:dir`, where:

* `ref` is the name of the branch, tag, or commit hash
* `dir` is a subdirectory inside the repository

For example, the following command uses the `container` branch, and the `docker` subdirectory in that branch, as the build context:

```console
$ docker build https://github.com/user/myrepo.git#container:docker
```

The following table represents all the valid suffixes with their build contexts:

| Build Syntax Suffix            | Commit Used                   | Build Context Used |
| ------------------------------ | ----------------------------- | ------------------ |
| `myrepo.git`                   | `refs/heads/<default branch>` | `/`                |
| `myrepo.git#mytag`             | `refs/tags/mytag`             | `/`                |
| `myrepo.git#mybranch`          | `refs/heads/mybranch`         | `/`                |
| `myrepo.git#pull/42/head`      | `refs/pull/42/head`           | `/`                |
| `myrepo.git#:myfolder`         | `refs/heads/<default branch>` | `/myfolder`        |
| `myrepo.git#master:myfolder`   | `refs/heads/master`           | `/myfolder`        |
| `myrepo.git#mytag:myfolder`    | `refs/tags/mytag`             | `/myfolder`        |
| `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch`         | `/myfolder`        |

When you use a commit hash as the `ref` in the URL fragment, use the full, 40-character string SHA-1 hash of the commit. A short hash, for example a hash truncated to 7 characters, is not supported.

```bash
# ✅ The following works:
docker build github.com/docker/buildx#d4f088e689b41353d74f1a0bfcd6d7c0b213aed2
# ❌ The following doesn't work because the commit hash is truncated:
docker build github.com/docker/buildx#d4f088e
```

#### [URL queries](#url-queries)

Requires: Docker Buildx [0.28.0](https://github.com/docker/buildx/releases/tag/v0.28.0) and later, Dockerfile [1.18.0](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.18.0) and later, and Docker Desktop [4.46.0](https://docs.docker.com/desktop/release-notes/#4460) and later

URL queries are more structured and recommended over [URL fragments](#url-fragments):

```console
$ docker buildx build 'https://github.com/user/myrepo.git?branch=container&subdir=docker'
```

| Build syntax suffix                          | Commit used                   | Build context used |
| -------------------------------------------- | ----------------------------- | ------------------ |
| `myrepo.git`                                 | `refs/heads/<default branch>` | `/`                |
| `myrepo.git?tag=mytag`                       | `refs/tags/mytag`             | `/`                |
| `myrepo.git?branch=mybranch`                 | `refs/heads/mybranch`         | `/`                |
| `myrepo.git?ref=pull/42/head`                | `refs/pull/42/head`           | `/`                |
| `myrepo.git?subdir=myfolder`                 | `refs/heads/<default branch>` | `/myfolder`        |
| `myrepo.git?branch=master&subdir=myfolder`   | `refs/heads/master`           | `/myfolder`        |
| `myrepo.git?tag=mytag&subdir=myfolder`       | `refs/tags/mytag`             | `/myfolder`        |
| `myrepo.git?branch=mybranch&subdir=myfolder` | `refs/heads/mybranch`         | `/myfolder`        |

A commit hash can be specified as a `checksum` (alias `commit`) query, along with `tag`, `branch`, or `ref` queries to verify that the reference resolves to the expected commit:

```console
$ docker buildx build 'https://github.com/moby/buildkit.git?tag=v0.21.1&checksum=66735c67'
```

If it doesn't match, the build fails:

```console
$ docker buildx build 'https://github.com/user/myrepo.git?tag=v0.1.0&commit=deadbeef'
...
#3 [internal] load git source https://github.com/user/myrepo.git?tag=v0.1.0-rc1&commit=deadbeef
#3 0.484 bb41e835b6c3523c7c45b248cf4b45e7f862bc42       refs/tags/v0.1.0
#3 ERROR: expected checksum to match deadbeef, got bb41e835b6c3523c7c45b248cf4b45e7f862bc42
```

> Note
>
> Short commit hash is supported with `checksum` (alias `commit`) query but for `ref`, only the full hash of the commit is supported.

#### [Keep `.git` directory](#keep-git-directory)

By default, BuildKit doesn't keep the `.git` directory when using Git contexts. You can configure BuildKit to keep the directory by setting the [`BUILDKIT_CONTEXT_KEEP_GIT_DIR` build argument](https://docs.docker.com/reference/dockerfile/#buildkit-built-in-build-args). This can be useful to if you want to retrieve Git information during your build:

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
WORKDIR /src
RUN --mount=target=. \
  make REVISION=$(git rev-parse HEAD) build
```

```console
$ docker build \
  --build-arg BUILDKIT_CONTEXT_KEEP_GIT_DIR=1
  https://github.com/user/myrepo.git#main
```

#### [Private repositories](#private-repositories)

When you specify a Git context that's also a private repository, the builder needs you to provide the necessary authentication credentials. You can use either SSH or token-based authentication.

Buildx automatically detects and uses SSH credentials if the Git context you specify is an SSH or Git address. By default, this uses `$SSH_AUTH_SOCK`. You can configure the SSH credentials to use with the [`--ssh` flag](/reference/cli/docker/buildx/build/#ssh).

```console
$ docker buildx build --ssh default git@github.com:user/private.git
```

If you want to use token-based authentication instead, you can pass the token using the [`--secret` flag](/reference/cli/docker/buildx/build/#secret).

```console
$ GIT_AUTH_TOKEN=<token> docker buildx build \
  --secret id=GIT_AUTH_TOKEN \
  https://github.com/user/private.git
```

> Note
>
> Don't use `--build-arg` for secrets.

### [Remote context with Dockerfile from stdin](#remote-context-with-dockerfile-from-stdin)

Use the following syntax to build an image using files on your local filesystem, while using a Dockerfile from stdin.

```console
$ docker build -f- URL
```

The syntax uses the -f (or --file) option to specify the Dockerfile to use, and it uses a hyphen (-) as filename to instruct Docker to read the Dockerfile from stdin.

This can be useful in situations where you want to build an image from a repository that doesn't contain a Dockerfile. Or if you want to build with a custom Dockerfile, without maintaining your own fork of the repository.

The following example builds an image using a Dockerfile from stdin, and adds the `hello.c` file from the [hello-world](https://github.com/docker-library/hello-world) repository on GitHub.

```bash
docker build -t myimage:latest -f- https://github.com/docker-library/hello-world.git <<EOF
FROM busybox
COPY hello.c ./
EOF
```

### [Remote tarballs](#remote-tarballs)

If you pass the URL to a remote tarball, the URL itself is sent to the builder.

```console
$ docker build http://server/context.tar.gz
#1 [internal] load remote build context
#1 DONE 0.2s

#2 copy /context /
#2 DONE 0.1s
...
```

The download operation will be performed on the host where the BuildKit daemon is running. Note that if you're using a remote Docker context or a remote builder, that's not necessarily the same machine as where you issue the build command. BuildKit fetches the `context.tar.gz` and uses it as the build context. Tarball contexts must be tar archives conforming to the standard `tar` Unix format and can be compressed with any one of the `xz`, `bzip2`, `gzip` or `identity` (no compression) formats.

## [Empty context](#empty-context)

When you use a text file as the build context, the builder interprets the file as a Dockerfile. Using a text file as context means that the build has no filesystem context.

You can build with an empty build context when your Dockerfile doesn't depend on any local files.

### [How to build without a context](#how-to-build-without-a-context)

You can pass the text file using a standard input stream, or by pointing at the URL of a remote text file.

```console
$ docker build - < Dockerfile
```

```powershell
Get-Content Dockerfile | docker build -
```

```bash
docker build -t myimage:latest - <<EOF
FROM busybox
RUN echo "hello world"
EOF
```

```console
$ docker build https://raw.githubusercontent.com/dvdksn/clockbox/main/Dockerfile
```

When you build without a filesystem context, Dockerfile instructions such as `COPY` can't refer to local files:

```console
$ ls
main.c
$ docker build -<<< $'FROM scratch\nCOPY main.c .'
[+] Building 0.0s (4/4) FINISHED
 => [internal] load build definition from Dockerfile       0.0s
 => => transferring dockerfile: 64B                        0.0s
 => [internal] load .dockerignore                          0.0s
 => => transferring context: 2B                            0.0s
 => [internal] load build context                          0.0s
 => => transferring context: 2B                            0.0s
 => ERROR [1/1] COPY main.c .                              0.0s
------
 > [1/1] COPY main.c .:
------
Dockerfile:2
--------------------
   1 |     FROM scratch
   2 | >>> COPY main.c .
   3 |
--------------------
ERROR: failed to solve: failed to compute cache key: failed to calculate checksum of ref 7ab2bb61-0c28-432e-abf5-a4c3440bc6b6::4lgfpdf54n5uqxnv9v6ymg7ih: "/main.c": not found
```

## [.dockerignore files](#dockerignore-files)

You can use a `.dockerignore` file to exclude files or directories from the build context.

```text
# .dockerignore
node_modules
bar
```

This helps avoid sending unwanted files and directories to the builder, improving build speed, especially when using a remote builder.

### [Filename and location](#filename-and-location)

When you run a build command, the build client looks for a file named `.dockerignore` in the root directory of the context. If this file exists, the files and directories that match patterns in the files are removed from the build context before it's sent to the builder.

If you use multiple Dockerfiles, you can use different ignore-files for each Dockerfile. You do so using a special naming convention for the ignore-files. Place your ignore-file in the same directory as the Dockerfile, and prefix the ignore-file with the name of the Dockerfile, as shown in the following example.

```text
.
├── index.ts
├── src/
├── docker
│   ├── build.Dockerfile
│   ├── build.Dockerfile.dockerignore
│   ├── lint.Dockerfile
│   ├── lint.Dockerfile.dockerignore
│   ├── test.Dockerfile
│   └── test.Dockerfile.dockerignore
├── package.json
└── package-lock.json
```

A Dockerfile-specific ignore-file takes precedence over the `.dockerignore` file at the root of the build context if both exist.

### [Syntax](#syntax)

The `.dockerignore` file is a newline-separated list of patterns similar to the file globs of Unix shells. Leading and trailing slashes in ignore patterns are disregarded. The following patterns all exclude a file or directory named `bar` in the subdirectory `foo` under the root of the build context:

* `/foo/bar/`
* `/foo/bar`
* `foo/bar/`
* `foo/bar`

If a line in `.dockerignore` file starts with `#` in column 1, then this line is considered as a comment and is ignored before interpreted by the CLI.

```gitignore
#/this/is/a/comment
```

If you're interested in learning the precise details of the `.dockerignore` pattern matching logic, check out the [moby/patternmatcher repository](https://github.com/moby/patternmatcher/tree/main/ignorefile) on GitHub, which contains the source code.

#### [Matching](#matching)

The following code snippet shows an example `.dockerignore` file.

```text
# comment
*/temp*
*/*/temp*
temp?
```

This file causes the following build behavior:

| Rule        | Behavior                                                                                                                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `# comment` | Ignored.                                                                                                                                                                                                      |
| `*/temp*`   | Exclude files and directories whose names start with `temp` in any immediate subdirectory of the root. For example, the plain file `/somedir/temporary.txt` is excluded, as is the directory `/somedir/temp`. |
| `*/*/temp*` | Exclude files and directories starting with `temp` from any subdirectory that is two levels below the root. For example, `/somedir/subdir/temporary.txt` is excluded.                                         |
| `temp?`     | Exclude files and directories in the root directory whose names are a one-character extension of `temp`. For example, `/tempa` and `/tempb` are excluded.                                                     |

Matching is done using Go's [`filepath.Match` function](https://golang.org/pkg/path/filepath#Match) rules. A preprocessing step uses Go's [`filepath.Clean` function](https://golang.org/pkg/path/filepath/#Clean) to trim whitespace and remove `.` and `..`. Lines that are blank after preprocessing are ignored.

> Note
>
> For historical reasons, the pattern `.` is ignored.

Beyond Go's `filepath.Match` rules, Docker also supports a special wildcard string `**` that matches any number of directories (including zero). For example, `**/*.go` excludes all files that end with `.go` found anywhere in the build context.

You can use the `.dockerignore` file to exclude the `Dockerfile` and `.dockerignore` files. These files are still sent to the builder as they're needed for running the build. But you can't copy the files into the image using `ADD`, `COPY`, or bind mounts.

#### [Negating matches](#negating-matches)

You can prepend lines with a `!` (exclamation mark) to make exceptions to exclusions. The following is an example `.dockerignore` file that uses this mechanism:

```text
*.md
!README.md
```

All markdown files right under the context directory *except* `README.md` are excluded from the context. Note that markdown files under subdirectories are still included.

The placement of `!` exception rules influences the behavior: the last line of the `.dockerignore` that matches a particular file determines whether it's included or excluded. Consider the following example:

```text
*.md
!README*.md
README-secret.md
```

No markdown files are included in the context except README files other than `README-secret.md`.

Now consider this example:

```text
*.md
README-secret.md
!README*.md
```

All of the README files are included. The middle line has no effect because `!README*.md` matches `README-secret.md` and comes last.

## [Named contexts](#named-contexts)

In addition to the default build context (the positional argument to the `docker build` command), you can also pass additional named contexts to builds.

Named contexts are specified using the `--build-context` flag, followed by a name-value pair. This lets you include files and directories from multiple sources during the build, while keeping them logically separated.

```console
$ docker build --build-context docs=./docs .
```

In this example:

* The named `docs` context points to the `./docs` directory.
* The default context (`.`) points to the current working directory.

### [Using named contexts in a Dockerfile](#using-named-contexts-in-a-dockerfile)

Dockerfile instructions can reference named contexts as if they are stages in a multi-stage build.

For example, the following Dockerfile:

1. Uses a `COPY` instruction to copy files from the default context into the current build stage.
2. Bind mounts the files in a named context to process the files as part of the build.

```dockerfile
# syntax=docker/dockerfile:1
FROM buildbase
WORKDIR /app

# Copy all files from the default context into /app/src in the build container
COPY . /app/src
RUN make bin

# Mount the files from the named "docs" context to build the documentation
RUN --mount=from=docs,target=/app/docs \
    make manpages
```

### [Use cases for named contexts](#use-cases-for-named-contexts)

Using named contexts allows for greater flexibility and efficiency when building Docker images. Here are some scenarios where using named contexts can be useful:

#### [Example: combine local and remote sources](#example-combine-local-and-remote-sources)

You can define separate named contexts for different types of sources. For example, consider a project where the application source code is local, but the deployment scripts are stored in a Git repository:

```console
$ docker build --build-context scripts=https://github.com/user/deployment-scripts.git .
```

In the Dockerfile, you can use these contexts independently:

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine:latest

# Copy application code from the main context
COPY . /opt/app

# Run deployment scripts using the remote "scripts" context
RUN --mount=from=scripts,target=/scripts /scripts/main.sh
```

#### [Example: dynamic builds with custom dependencies](#example-dynamic-builds-with-custom-dependencies)

In some scenarios, you might need to dynamically inject configuration files or dependencies into the build from external sources. Named contexts make this straightforward by allowing you to mount different configurations without modifying the default build context.

```console
$ docker build --build-context config=./configs/prod .
```

Example Dockerfile:

```dockerfile
# syntax=docker/dockerfile:1
FROM nginx:alpine

# Use the "config" context for environment-specific configurations
COPY --from=config nginx.conf /etc/nginx/nginx.conf
```

#### [Example: pin or override images](#example-pin-or-override-images)

You can refer to named contexts in a Dockerfile the same way you can refer to an image. That means you can change an image reference in your Dockerfile by overriding it with a named context. For example, given the following Dockerfile:

```dockerfile
FROM alpine:3.23
```

If you want to force image reference to resolve to a different version, without changing the Dockerfile, you can pass a context with the same name to the build. For example:

```console
docker buildx build --build-context alpine:3.23=docker-image://alpine:edge .
```

The `docker-image://` prefix marks the context as an image reference. The reference can be a local image or an image in your registry.

### [Named contexts with Bake](#named-contexts-with-bake)

[Bake](https://docs.docker.com/build/bake/) is a tool built into `docker build` that lets you manage your build configuration with a configuration file. Bake fully supports named contexts.

To define named contexts in a Bake file:

docker-bake.hcl

```hcl
target "app" {
  contexts = {
    docs = "./docs"
  }
}
```

This is equivalent to the following CLI invocation:

```console
$ docker build --build-context docs=./docs .
```

#### [Linking targets with named contexts](#linking-targets-with-named-contexts)

In addition to making complex builds more manageable, Bake also provides additional features on top of what you can do with `docker build` on the CLI. You can use named contexts to create build pipelines, where one target depends on and builds on top of another. For example, consider a Docker build setup where you have two Dockerfiles:

* `base.Dockerfile`: for building a base image
* `app.Dockerfile`: for building an application image

The `app.Dockerfile` uses the image produced by `base.Dockerfile` as it's base image:

app.Dockerfile

```dockerfile
FROM mybaseimage
```

Normally, you would have to build the base image first, and then either load it to Docker Engine's local image store or push it to a registry. With Bake, you can reference other targets directly, creating a dependency between the `app` target and the `base` target.

docker-bake.hcl

```hcl
target "base" {
  dockerfile = "base.Dockerfile"
}

target "app" {
  dockerfile = "app.Dockerfile"
  contexts = {
    # the target: prefix indicates that 'base' is a Bake target
    mybaseimage = "target:base"
  }
}
```

With this configuration, references to `mybaseimage` in `app.Dockerfile` use the results from building the `base` target. Building the `app` target will also trigger a rebuild of `mybaseimage`, if necessary:

```console
$ docker buildx bake app
```

### [Further reading](#further-reading)

For more information about working with named contexts, see:

* [`--build-context` CLI reference](/reference/cli/docker/buildx/build/#build-context)
* [Using Bake with additional contexts](https://docs.docker.com/build/bake/contexts/)

----
url: https://docs.docker.com/build-cloud/setup/
----

# Docker Build Cloud setup

***

Table of contents

***

Before you can start using Docker Build Cloud, you must add the builder to your local environment.

## [Prerequisites](#prerequisites)

To get started with Docker Build Cloud, you need to:

* Download and install Docker Desktop version 4.26.0 or later.
* Create a cloud builder on the [Docker Build Cloud Dashboard](https://app.docker.com/build/).
  * When you create the builder, choose a name for it (for example, `default`). You will use this name as `BUILDER_NAME` in the CLI steps below.

### [Use Docker Build Cloud without Docker Desktop](#use-docker-build-cloud-without-docker-desktop)

To use Docker Build Cloud without Docker Desktop, you must download and install a version of Buildx with support for Docker Build Cloud (the `cloud` driver). You can find compatible Buildx binaries on the releases page of [this repository](https://github.com/docker/buildx-desktop).

If you plan on building with Docker Build Cloud using the `docker compose build` command, you also need a version of Docker Compose that supports Docker Build Cloud. You can find compatible Docker Compose binaries on the releases page of [this repository](https://github.com/docker/compose-desktop).

## [Steps](#steps)

You can add a cloud builder using the CLI, with the `docker buildx create` command, or using the Docker Desktop settings GUI.

1. Sign in to your Docker account.

   ```console
   $ docker login
   ```

2. Connect Buildx to your cloud builder.

   ```console
   $ docker buildx create --driver cloud ORG/BUILDER_NAME
   ```

   Replace `<ORG>` with the Docker Hub namespace of your Docker organization (or your username if you are using a personal account), and `<BUILDER_NAME>` with the name you chose when creating the builder in the dashboard.

   This registers a local endpoint for the cloud builder named `cloud-ORG-BUILDER_NAME`.

   > Note
   >
   > This command connects Buildx to an existing Docker Build Cloud builder. It does not create a new cloud builder. To add a new builder, use the [Docker Build Cloud Dashboard](https://app.docker.com/build/).

   > Note
   >
   > If your organization is `acme` and you named your builder `default`, use:
   >
   > ```console
   > $ docker buildx create --driver cloud acme/default
   > ```

1) Sign in to your Docker account using the **Sign in** button in Docker Desktop.

2) Open the Docker Desktop settings and navigate to the **Builders** tab.

3) Under **Available builders**, select **Connect to builder**.

The builder has native support for the `linux/amd64` and `linux/arm64` architectures. This gives you a high-performance build cluster for building multi-platform images natively.

## [Firewall configuration](#firewall-configuration)

To use Docker Build Cloud behind a firewall, ensure that your firewall allows traffic to the following addresses:

* 3.211.38.21
* <https://auth.docker.io>
* <https://build-cloud.docker.com>
* <https://hub.docker.com>

## [What's next](#whats-next)

* See [Building with Docker Build Cloud](https://docs.docker.com/build-cloud/usage/) for examples on how to use Docker Build Cloud.
* See [Use Docker Build Cloud in CI](https://docs.docker.com/build-cloud/ci/) for examples on how to use Docker Build Cloud with CI systems.

----
url: https://docs.docker.com/compose/how-tos/lifecycle/
----

# Using lifecycle hooks with Compose

***

Table of contents

***

Requires: Docker Compose [2.30.0](https://github.com/docker/compose/releases/tag/v2.30.0) and later

## [Services lifecycle hooks](#services-lifecycle-hooks)

When Docker Compose runs a container, it uses two elements, [ENTRYPOINT and COMMAND](https://docs.docker.com/engine/containers/run/#default-command-and-options), to manage what happens when the container starts and stops.

However, it can sometimes be easier to handle these tasks separately with lifecycle hooks - commands that run right after the container starts or just before it stops.

Lifecycle hooks are particularly useful because they can have special privileges (like running as the root user), even when the container itself runs with lower privileges for security. This means that certain tasks requiring higher permissions can be done without compromising the overall security of the container.

### [Post-start hooks](#post-start-hooks)

Post-start hooks are commands that run after the container has started, but there's no set time for when exactly they will execute. The hook execution timing is not assured during the execution of the container's `entrypoint`.

Because there is no ordering guarantee between the hook and the container's entrypoint, post-start hooks are best suited for tasks that do not need to complete before the application begins running, such as registering the container with an external system.

In the following example, after the container starts, a root-level hook registers the service with an internal service registry. The application does not depend on registration being complete before it starts serving requests.

```yaml
services:
  app:
    image: backend
    user: 1001
    post_start:
      - command: /opt/scripts/register-service.sh
        user: root
```

### [Pre-stop hooks](#pre-stop-hooks)

Pre-stop hooks are commands that run before the container is stopped by a specific command (like `docker compose down` or stopping it manually with `Ctrl+C`). These hooks won't run if the container stops by itself or gets killed suddenly.

Because the pre-stop hook runs before the stop signal is sent to the container, it is suited for actions that must complete while the application is still fully running.

In the following example, the hook backs up a data file before the container receives the stop signal.

```yaml
services:
  app:
    image: backend
    volumes:
      - data:/data
    pre_stop:
      - command: cp /data/app.db /data/app.db.bak

volumes:
  data: {} # a Docker volume is created with root ownership
```

## [Reference information](#reference-information)

* [`post_start`](https://docs.docker.com/reference/compose-file/services/#post_start)
* [`pre_stop`](https://docs.docker.com/reference/compose-file/services/#pre_stop)

----
url: https://docs.docker.com/build/bake/stdlib/
----

# Bake standard library functions

***

Table of contents

***

| Name                                                | Description                                                                                                                                                                                                                                          |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`absolute`](#absolute)                             | If the given number is negative then returns its positive equivalent, or otherwise returns the given number unchanged.                                                                                                                               |
| [`add`](#add)                                       | Returns the sum of the two given numbers.                                                                                                                                                                                                            |
| [`and`](#and)                                       | Applies the logical AND operation to the given boolean values.                                                                                                                                                                                       |
| [`base64decode`](#base64decode)                     | Decodes a string containing a base64 sequence.                                                                                                                                                                                                       |
| [`base64encode`](#base64encode)                     | Encodes a string to a base64 sequence.                                                                                                                                                                                                               |
| [`basename`](#basename)                             | Returns the last element of a path.                                                                                                                                                                                                                  |
| [`bcrypt`](#bcrypt)                                 | Computes a hash of the given string using the Blowfish cipher.                                                                                                                                                                                       |
| [`byteslen`](#byteslen)                             | Returns the total number of bytes in the given buffer.                                                                                                                                                                                               |
| [`bytesslice`](#bytesslice)                         | Extracts a subslice from the given buffer.                                                                                                                                                                                                           |
| [`can`](#can)                                       | Tries to evaluate the expression given in its first argument.                                                                                                                                                                                        |
| [`ceil`](#ceil)                                     | Returns the smallest whole number that is greater than or equal to the given value.                                                                                                                                                                  |
| [`chomp`](#chomp)                                   | Removes one or more newline characters from the end of the given string.                                                                                                                                                                             |
| [`chunklist`](#chunklist)                           | Splits a single list into multiple lists where each has at most the given number of elements.                                                                                                                                                        |
| [`cidrhost`](#cidrhost)                             | Calculates a full host IP address within a given IP network address prefix.                                                                                                                                                                          |
| [`cidrnetmask`](#cidrnetmask)                       | Converts an IPv4 address prefix given in CIDR notation into a subnet mask address.                                                                                                                                                                   |
| [`cidrsubnet`](#cidrsubnet)                         | Calculates a subnet address within a given IP network address prefix.                                                                                                                                                                                |
| [`cidrsubnets`](#cidrsubnets)                       | Calculates many consecutive subnet addresses at once, rather than just a single subnet extension.                                                                                                                                                    |
| [`coalesce`](#coalesce)                             | Returns the first of the given arguments that isn't null, or raises an error if there are no non-null arguments.                                                                                                                                     |
| [`coalescelist`](#coalescelist)                     | Returns the first of the given sequences that has a length greater than zero.                                                                                                                                                                        |
| [`compact`](#compact)                               | Removes all empty string elements from the given list of strings.                                                                                                                                                                                    |
| [`concat`](#concat)                                 | Concatenates together all of the given lists or tuples into a single sequence, preserving the input order.                                                                                                                                           |
| [`contains`](#contains)                             | Returns true if the given value is a value in the given list, tuple, or set, or false otherwise.                                                                                                                                                     |
| [`convert`](#convert)                               | Converts a value to a specified type constraint, using HCL's customdecode extension for type expression support.                                                                                                                                     |
| [`csvdecode`](#csvdecode)                           | Parses the given string as Comma Separated Values (as defined by RFC 4180) and returns a map of objects representing the table of data, using the first row as a header row to define the object attributes.                                         |
| [`dirname`](#dirname)                               | Returns the directory of a path.                                                                                                                                                                                                                     |
| [`distinct`](#distinct)                             | Removes any duplicate values from the given list, preserving the order of remaining elements.                                                                                                                                                        |
| [`divide`](#divide)                                 | Divides the first given number by the second.                                                                                                                                                                                                        |
| [`element`](#element)                               | Returns the element with the given index from the given list or tuple, applying the modulo operation to the given index if it's greater than the number of elements.                                                                                 |
| [`equal`](#equal)                                   | Returns true if the two given values are equal, or false otherwise.                                                                                                                                                                                  |
| [`flatten`](#flatten)                               | Transforms a list, set, or tuple value into a tuple by replacing any given elements that are themselves sequences with a flattened tuple of all of the nested elements concatenated together.                                                        |
| [`floor`](#floor)                                   | Returns the greatest whole number that is less than or equal to the given value.                                                                                                                                                                     |
| [`format`](#format)                                 | Constructs a string by applying formatting verbs to a series of arguments, using a similar syntax to the C function "printf".                                                                                                                        |
| [`formatdate`](#formatdate)                         | Deprecated: use formattimestamp instead. Formats a timestamp given in RFC 3339 syntax into another timestamp in some other machine-oriented time syntax, as described in the format string.                                                          |
| [`formatlist`](#formatlist)                         | Constructs a list of strings by applying formatting verbs to a series of arguments, using a similar syntax to the C function "printf".                                                                                                               |
| [`formattimestamp`](#formattimestamp)               | Formats a timestamp string in RFC 3339 syntax or a unix timestamp integer into another timestamp in some other machine-oriented time syntax, as described in the format string. The special format string "X" returns the unix timestamp in seconds. |
| [`greaterthan`](#greaterthan)                       | Returns true if and only if the second number is greater than the first.                                                                                                                                                                             |
| [`greaterthanorequalto`](#greaterthanorequalto)     | Returns true if and only if the second number is greater than or equal to the first.                                                                                                                                                                 |
| [`hasindex`](#hasindex)                             | Returns true if if the given collection can be indexed with the given key without producing an error, or false otherwise.                                                                                                                            |
| [`homedir`](#homedir)                               | Returns the current user's home directory.                                                                                                                                                                                                           |
| [`indent`](#indent)                                 | Adds a given number of spaces after each newline character in the given string.                                                                                                                                                                      |
| [`index`](#index)                                   | Returns the element with the given key from the given collection, or raises an error if there is no such element.                                                                                                                                    |
| [`indexof`](#indexof)                               | Finds the element index for a given value in a list.                                                                                                                                                                                                 |
| [`int`](#int)                                       | Discards any fractional portion of the given number.                                                                                                                                                                                                 |
| [`join`](#join)                                     | Concatenates together the elements of all given lists with a delimiter, producing a single string.                                                                                                                                                   |
| [`jsondecode`](#jsondecode)                         | Parses the given string as JSON and returns a value corresponding to what the JSON document describes.                                                                                                                                               |
| [`jsonencode`](#jsonencode)                         | Returns a string containing a JSON representation of the given value.                                                                                                                                                                                |
| [`keys`](#keys)                                     | Returns a list of the keys of the given map in lexicographical order.                                                                                                                                                                                |
| [`length`](#length)                                 | Returns the number of elements in the given collection.                                                                                                                                                                                              |
| [`lessthan`](#lessthan)                             | Returns true if and only if the second number is less than the first.                                                                                                                                                                                |
| [`lessthanorequalto`](#lessthanorequalto)           | Returns true if and only if the second number is less than or equal to the first.                                                                                                                                                                    |
| [`log`](#log)                                       | Returns the logarithm of the given number in the given base.                                                                                                                                                                                         |
| [`lookup`](#lookup)                                 | Returns the value of the element with the given key from the given map, or returns the default value if there is no such element.                                                                                                                    |
| [`lower`](#lower)                                   | Returns the given string with all Unicode letters translated to their lowercase equivalents.                                                                                                                                                         |
| [`max`](#max)                                       | Returns the numerically greatest of all of the given numbers.                                                                                                                                                                                        |
| [`md5`](#md5)                                       | Computes the MD5 hash of a given string and encodes it with hexadecimal digits.                                                                                                                                                                      |
| [`merge`](#merge)                                   | Merges all of the elements from the given maps into a single map, or the attributes from given objects into a single object.                                                                                                                         |
| [`min`](#min)                                       | Returns the numerically smallest of all of the given numbers.                                                                                                                                                                                        |
| [`modulo`](#modulo)                                 | Divides the first given number by the second and then returns the remainder.                                                                                                                                                                         |
| [`multiply`](#multiply)                             | Returns the product of the two given numbers.                                                                                                                                                                                                        |
| [`negate`](#negate)                                 | Multiplies the given number by -1.                                                                                                                                                                                                                   |
| [`not`](#not)                                       | Applies the logical NOT operation to the given boolean value.                                                                                                                                                                                        |
| [`notequal`](#notequal)                             | Returns false if the two given values are equal, or true otherwise.                                                                                                                                                                                  |
| [`or`](#or)                                         | Applies the logical OR operation to the given boolean values.                                                                                                                                                                                        |
| [`parseint`](#parseint)                             | Parses the given string as a number of the given base, or raises an error if the string contains invalid characters.                                                                                                                                 |
| [`pow`](#pow)                                       | Returns the given number raised to the given power (exponentiation).                                                                                                                                                                                 |
| [`range`](#range)                                   | Returns a list of numbers spread evenly over a particular range.                                                                                                                                                                                     |
| [`regex`](#regex)                                   | Applies the given regular expression pattern to the given string and returns information about a single match, or raises an error if there is no match.                                                                                              |
| [`regex_replace`](#regex_replace)                   | Applies the given regular expression pattern to the given string and replaces all matches with the given replacement string.                                                                                                                         |
| [`regexall`](#regexall)                             | Applies the given regular expression pattern to the given string and returns a list of information about all non-overlapping matches, or an empty list if there are no matches.                                                                      |
| [`replace`](#replace)                               | Replaces all instances of the given substring in the given string with the given replacement string.                                                                                                                                                 |
| [`reverse`](#reverse)                               | Returns the given string with all of its Unicode characters in reverse order.                                                                                                                                                                        |
| [`reverselist`](#reverselist)                       | Returns the given list with its elements in reverse order.                                                                                                                                                                                           |
| [`rsadecrypt`](#rsadecrypt)                         | Decrypts an RSA-encrypted ciphertext.                                                                                                                                                                                                                |
| [`sanitize`](#sanitize)                             | Replaces all non-alphanumeric characters with a underscore, leaving only characters that are valid for a Bake target name.                                                                                                                           |
| [`semvercmp`](#semvercmp)                           | Returns true if version satisfies a constraint.                                                                                                                                                                                                      |
| [`sethaselement`](#sethaselement)                   | Returns true if the given set contains the given element, or false otherwise.                                                                                                                                                                        |
| [`setintersection`](#setintersection)               | Returns the intersection of all given sets.                                                                                                                                                                                                          |
| [`setproduct`](#setproduct)                         | Calculates the cartesian product of two or more sets.                                                                                                                                                                                                |
| [`setsubtract`](#setsubtract)                       | Returns the relative complement of the two given sets.                                                                                                                                                                                               |
| [`setsymmetricdifference`](#setsymmetricdifference) | Returns the symmetric difference of the two given sets.                                                                                                                                                                                              |
| [`setunion`](#setunion)                             | Returns the union of all given sets.                                                                                                                                                                                                                 |
| [`sha1`](#sha1)                                     | Computes the SHA1 hash of a given string and encodes it with hexadecimal digits.                                                                                                                                                                     |
| [`sha256`](#sha256)                                 | Computes the SHA256 hash of a given string and encodes it with hexadecimal digits.                                                                                                                                                                   |
| [`sha512`](#sha512)                                 | Computes the SHA512 hash of a given string and encodes it with hexadecimal digits.                                                                                                                                                                   |
| [`signum`](#signum)                                 | Returns 0 if the given number is zero, 1 if the given number is positive, or -1 if the given number is negative.                                                                                                                                     |
| [`slice`](#slice)                                   | Extracts a subslice of the given list or tuple value.                                                                                                                                                                                                |
| [`sort`](#sort)                                     | Applies a lexicographic sort to the elements of the given list.                                                                                                                                                                                      |
| [`split`](#split)                                   | Produces a list of one or more strings by splitting the given string at all instances of a given separator substring.                                                                                                                                |
| [`strlen`](#strlen)                                 | Returns the number of Unicode characters (technically: grapheme clusters) in the given string.                                                                                                                                                       |
| [`substr`](#substr)                                 | Extracts a substring from the given string.                                                                                                                                                                                                          |
| [`subtract`](#subtract)                             | Returns the difference between the two given numbers.                                                                                                                                                                                                |
| [`timeadd`](#timeadd)                               | Adds the duration represented by the given duration string to the given RFC 3339 timestamp string, returning another RFC 3339 timestamp.                                                                                                             |
| [`timestamp`](#timestamp)                           | Returns a string representation of the current date and time.                                                                                                                                                                                        |
| [`title`](#title)                                   | Replaces one letter after each non-letter and non-digit character with its uppercase equivalent.                                                                                                                                                     |
| [`trim`](#trim)                                     | Removes consecutive sequences of characters in "cutset" from the start and end of the given string.                                                                                                                                                  |
| [`trimprefix`](#trimprefix)                         | Removes the given prefix from the start of the given string, if present.                                                                                                                                                                             |
| [`trimspace`](#trimspace)                           | Removes any consecutive space characters (as defined by Unicode) from the start and end of the given string.                                                                                                                                         |
| [`trimsuffix`](#trimsuffix)                         | Removes the given suffix from the start of the given string, if present.                                                                                                                                                                             |
| [`try`](#try)                                       | Variadic function that tries to evaluate all of is arguments in sequence until one succeeds, in which case it returns that result, or returns an error if none of them succeed.                                                                      |
| [`unixtimestampparse`](#unixtimestampparse)         | Given a unix timestamp integer, will parse and return an object representation of that date and time. A unix timestamp is the number of seconds elapsed since January 1, 1970 UTC.                                                                   |
| [`upper`](#upper)                                   | Returns the given string with all Unicode letters translated to their uppercase equivalents.                                                                                                                                                         |
| [`urlencode`](#urlencode)                           | Applies URL encoding to a given string.                                                                                                                                                                                                              |
| [`uuidv4`](#uuidv4)                                 | Generates and returns a Type-4 UUID in the standard hexadecimal string format.                                                                                                                                                                       |
| [`uuidv5`](#uuidv5)                                 | Generates and returns a Type-5 UUID in the standard hexadecimal string format.                                                                                                                                                                       |
| [`values`](#values)                                 | Returns the values of elements of a given map, or the values of attributes of a given object, in lexicographic order by key or attribute name.                                                                                                       |
| [`zipmap`](#zipmap)                                 | Constructs a map from a list of keys and a corresponding list of values, which must both be of the same length.                                                                                                                                      |

## [`absolute`](#absolute)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    val = "${absolute(-42)}" # => 42
  }
}
```

## [`add`](#add)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${add(123, 1)}" # => 124
  }
}
```

## [`and`](#and)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${and(true, false)}" # => false
  }
}
```

## [`base64decode`](#base64decode)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    decoded = "${base64decode("SGVsbG8=")}" # => "Hello"
  }
}
```

## [`base64encode`](#base64encode)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    encoded = "${base64encode("Hello")}" # => "SGVsbG8="
  }
}
```

## [`basename`](#basename)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    file = "${basename("/usr/local/bin/docker")}" # => "docker"
  }
}
```

## [`bcrypt`](#bcrypt)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    hash = "${bcrypt("mypassword")}" # => "$2a$10$..."
  }
}
```

## [`byteslen`](#byteslen)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    length = "${byteslen("Docker")}" # => 6
  }
}
```

## [`bytesslice`](#bytesslice)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    part = "${bytesslice("Docker", 0, 3)}" # => "Doc"
  }
}
```

## [`can`](#can)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    safe = "${can(parseint("123", 10))}" # => true
  }
}
```

## [`ceil`](#ceil)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    rounded = "${ceil(3.14)}" # => 4"
  }
}
```

## [`chomp`](#chomp)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${chomp("Hello\n\n")}" # => "Hello"
  }
}
```

## [`chunklist`](#chunklist)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${chunklist([1,2,3,4,5], 2)}"     # => [[1,2],[3,4],[5]]
  }
}
```

## [`cidrhost`](#cidrhost)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${cidrhost("10.0.0.0/16", 5)}"   # => "10.0.0.5"
  }
}
```

## [`cidrnetmask`](#cidrnetmask)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    mask = "${cidrnetmask("10.0.0.0/16")}"     # => "255.255.0.0"
  }
}
```

## [`cidrsubnet`](#cidrsubnet)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    subnet = "${cidrsubnet("10.0.0.0/16", 4, 2)}" # => "10.0.32.0/20"
  }
}
```

## [`cidrsubnets`](#cidrsubnets)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    subs = "${cidrsubnets("10.0.0.0/16", 4, 4)}" # => ["10.0.0.0/20","10.0.16.0/20",...]
  }
}
```

## [`coalesce`](#coalesce)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    first = "${coalesce(null, "", "docker")}"  # => "docker"
  }
}
```

## [`coalescelist`](#coalescelist)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    first = "${coalescelist([], [1,2], [3])}" # => [1,2]
  }
}
```

## [`compact`](#compact)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    list = "${compact(["a", "", "b", ""])}" # => ["a","b"]
  }
}
```

## [`concat`](#concat)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    list = "${concat([1,2],[3,4])}" # => [1,2,3,4]
  }
}
```

## [`contains`](#contains)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    check = "${contains([1,2,3], 2)}" # => true
  }
}
```

## [`convert`](#convert)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${convert("42", number)}" # => 42
  }
}
```

## [`csvdecode`](#csvdecode)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    data = "${csvdecode("name,age\nAlice,30\nBob,40")}" # => [{"name":"Alice","age":"30"},{"name":"Bob","age":"40"}]
  }
}
```

## [`dirname`](#dirname)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    dir = "${dirname("/usr/local/bin/docker")}" # => "/usr/local/bin"
  }
}
```

## [`distinct`](#distinct)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${distinct([1,2,2,3,3,3])}" # => [1,2,3]
  }
}
```

## [`divide`](#divide)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${divide(10, 2)}" # => 5
  }
}
```

## [`element`](#element)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    val = "${element(["a","b","c"], 1)}" # => "b"
  }
}
```

## [`equal`](#equal)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    check = "${equal(2, 2)}" # => true
  }
}
```

## [`flatten`](#flatten)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    flat = "${flatten([[1,2],[3,4],[5]])}" # => [1,2,3,4,5]
  }
}
```

## [`floor`](#floor)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${floor(3.99)}" # => 3
  }
}
```

## [`format`](#format)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${format("Hello, %s!", "World")}" # => "Hello, World!"
  }
}
```

## [`formatdate`](#formatdate)

> Warning
>
> Deprecated: use `formattimestamp` instead. `formatdate` only accepts RFC3339 timestamp strings.

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    date = "${formatdate("YYYY-MM-DD", "2025-09-16T12:00:00Z")}" # => "2025-09-16"
  }
}
```

## [`formattimestamp`](#formattimestamp)

Formats either an RFC3339 timestamp string or a unix timestamp integer. The special format `X` returns the unix timestamp in seconds.

```hcl
# docker-bake.hcl
variable "SOURCE_DATE_EPOCH" {
  type    = number
  default = formattimestamp("X", "2015-10-21T00:00:00Z") # => 1445385600
}

target "default" {
  dockerfile = "Dockerfile"
  labels = {
    "org.opencontainers.image.created" = formattimestamp("YYYY-MM-DD'T'hh:mm:ssZ", SOURCE_DATE_EPOCH) # => "2015-10-21T00:00:00Z"
  }
  args = {
    build_date = formattimestamp("YYYY-MM-DD", "2025-09-16T12:00:00Z") # => "2025-09-16"
  }
}
```

## [`formatlist`](#formatlist)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    list = "${formatlist("Hi %s", ["Alice", "Bob"])}" # => ["Hi Alice","Hi Bob"]
  }
}
```

## [`greaterthan`](#greaterthan)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${greaterthan(2, 5)}" # => true
  }
}
```

## [`greaterthanorequalto`](#greaterthanorequalto)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${greaterthanorequalto(5, 5)}" # => true
  }
}
```

## [`hasindex`](#hasindex)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    exists = "${hasindex([10, 20, 30], 1)}"  # => true
    missing = "${hasindex([10, 20, 30], 5)}" # => false
  }
}
```

## [`homedir`](#homedir)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    home = "${homedir()}" # => e.g., "/home/user"
  }
}
```

## [`indent`](#indent)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    text = "${indent(4, "Hello\nWorld")}" 
    # => "    Hello\n    World"
  }
}
```

## [`index`](#index)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    val = "${index({foo = "bar", baz = "qux"}, "baz")}" # => "qux"
  }
}
```

## [`indexof`](#indexof)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    pos = "${indexof(["a","b","c"], "b")}" # => 1
  }
}
```

## [`int`](#int)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    number = "${int(3.75)}" # => 3
  }
}
```

## [`join`](#join)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    csv = "${join(",", ["a","b","c"])}" # => "a,b,c"
  }
}
```

## [`jsondecode`](#jsondecode)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    obj = "${jsondecode("{\"name\":\"Docker\",\"stars\":5}")}" # => {"name":"Docker","stars":5}
  }
}
```

## [`jsonencode`](#jsonencode)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    str = "${jsonencode({name="Docker", stars=5})}" # => "{\"name\":\"Docker\",\"stars\":5}"
  }
}
```

## [`keys`](#keys)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    list = "${keys({foo = 1, bar = 2, baz = 3})}" 
    # => ["bar","baz","foo"] (sorted order)
  }
}
```

## [`length`](#length)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    size = "${length([1,2,3,4])}" # => 4
  }
}
```

## [`lessthan`](#lessthan)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${lessthan(10, 3)}" # => false
  }
}
```

## [`lessthanorequalto`](#lessthanorequalto)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${lessthanorequalto(5, 7)}" # => true
  }
}
```

## [`log`](#log)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    val = "${log(100, 10)}" # => 2
  }
}
```

## [`lookup`](#lookup)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    found    = "${lookup({a="apple", b="banana"}, "a", "none")}" # => "apple"
    fallback = "${lookup({a="apple", b="banana"}, "c", "none")}" # => "none"
  }
}
```

## [`lower`](#lower)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    val = "${lower("HELLO")}" # => "hello"
  }
}
```

## [`max`](#max)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${max(3, 9, 7)}" # => 9
  }
}
```

## [`md5`](#md5)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    hash = "${md5("docker")}" # => "597dd5f6a..." (hex string)
  }
}
```

## [`merge`](#merge)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    combined = "${merge({a=1, b=2}, {b=3, c=4})}" # => {a=1, b=3, c=4}
  }
}
```

## [`min`](#min)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${min(3, 9, 7)}" # => 3
  }
}
```

## [`modulo`](#modulo)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${modulo(10, 3)}" # => 1
  }
}
```

## [`multiply`](#multiply)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${multiply(6, 7)}" # => 42
  }
}
```

## [`negate`](#negate)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${negate(7)}" # => -7
  }
}
```

## [`not`](#not)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${not(true)}" # => false
  }
}
```

## [`notequal`](#notequal)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${notequal(4, 5)}" # => true
  }
}
```

## [`or`](#or)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${or(true, false)}" # => true
  }
}
```

## [`parseint`](#parseint)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${parseint("ff", 16)}" # => 255
  }
}
```

## [`pow`](#pow)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${pow(3, 2)}" # => 9
  }
}
```

## [`range`](#range)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${range(0, 5)}" # => [0,1,2,3,4]
  }
}
```

## [`regex`](#regex)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${regex("h.llo", "hello")}" # => "hello"
  }
}
```

## [`regex_replace`](#regex_replace)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${regex_replace("[0-9]+", "abc123xyz", "NUM")}" # => "abcNUMxyz"
  }
}
```

## [`regexall`](#regexall)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = matches = "${regexall("[a-z]+", "abc123xyz")}" # => ["abc","xyz"]
  }
}
```

## [`replace`](#replace)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${replace("banana", "na", "--")}" # => "ba-- --"
  }
}
```

## [`reverse`](#reverse)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${reverse("stressed")}" # => "desserts"
  }
}
```

## [`reverselist`](#reverselist)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${reverselist([1,2,3])}" # => [3,2,1]
  }
}
```

## [`rsadecrypt`](#rsadecrypt)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${rsadecrypt("eczGaDhXDbOFRZ...", "MIIEowIBAAKCAQEAgUElV5...")}"
  }
}
```

## [`sanitize`](#sanitize)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sanitize("My App! v1.0")}" # => "My_App__v1_0"
  }
}
```

## [`semvercmp`](#semvercmp)

This function checks if a semantic version fits within a set of constraints. See [Checking Version Constraints](https://github.com/Masterminds/semver?tab=readme-ov-file#checking-version-constraints) for details.

```hcl
# docker-bake.hcl
variable "ALPINE_VERSION" {
  default = "3.23"
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  platforms = semvercmp(ALPINE_VERSION, ">= 3.20") ? [
    "linux/amd64",
    "linux/arm64",
    "linux/riscv64"
  ] : [
    "linux/amd64",
    "linux/arm64"
  ]
}
```

## [`sethaselement`](#sethaselement)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sethaselement([1,2,3], 2)}"  # => true
  }
}
```

## [`setintersection`](#setintersection)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${setintersection(["a","b","c"], ["b","c","d"])}" # => ["b","c"]
  }
}
```

## [`setproduct`](#setproduct)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${setproduct(["x","y"], [1,2])}" # => [["x",1],["x",2],["y",1],["y",2]]
  }
}
```

## [`setsubtract`](#setsubtract)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${setsubtract([1,2,3], [2])}" # => [1,3]
  }
}
```

## [`setsymmetricdifference`](#setsymmetricdifference)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${setsymmetricdifference([1,2,3], [3,4])}" # => [1,2,4]
  }
}
```

## [`setunion`](#setunion)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${setunion(["a","b"], ["b","c"])}" # => ["a","b","c"]
  }
}
```

## [`sha1`](#sha1)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sha1("hello")}" # => "aaf4c61d..." (hex)
  }
}
```

## [`sha256`](#sha256)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sha256("hello")}" # => "2cf24dba..." (hex)
  }
}
```

## [`sha512`](#sha512)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sha512("hello")}" # => "9b71d224..." (hex)
  }
}
```

## [`signum`](#signum)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    zero = "${signum(0)}"    # => 0
    pos  = "${signum(12)}"   # => 1
    neg  = "${signum(-12)}"  # => -1
  }
}
```

## [`slice`](#slice)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${slice(["a","b","c","d"], 1, 3)}" # => ["b","c"]
  }
}
```

## [`sort`](#sort)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${sort(["b","c","a"])}" # => ["a","b","c"]
  }
}
```

## [`split`](#split)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${split(",", "a,b,c")}" # => ["a","b","c"]
  }
}
```

## [`strlen`](#strlen)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${strlen("Docker")}" # => 6
  }
}
```

## [`substr`](#substr)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${substr("abcdef", 2, 3)}" # => "cde"
  }
}
```

## [`subtract`](#subtract)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${subtract(10, 3)}" # => 7
  }
}
```

## [`timeadd`](#timeadd)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${timeadd("2025-09-24T12:00:00Z", "1h30m")}" # => "2025-09-24T13:30:00Z"
  }
}
```

## [`timestamp`](#timestamp)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${timestamp()}" # => current RFC3339 time at evaluation
  }
}
```

## [`title`](#title)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${title("hello world-from_docker")}" # => "Hello World-From_Docker"
  }
}
```

## [`trim`](#trim)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${trim("--hello--", "-")}" # => "hello"
  }
}
```

## [`trimprefix`](#trimprefix)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${trimprefix("docker-build", "docker-")}" # => "build"
  }
}
```

## [`trimspace`](#trimspace)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${trimspace("   hello   ")}" # => "hello"
  }
}
```

## [`trimsuffix`](#trimsuffix)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${trimsuffix("filename.txt", ".txt")}" # => "filename"
  }
}
```

## [`try`](#try)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    # First expr errors (invalid hex), second succeeds → returns 255
    val1 = "${try(parseint("zz", 16), parseint("ff", 16))}" # => 255

    # First expr errors (missing key), fallback string is used
    val2 = "${try(index({a="apple"}, "b"), "fallback")}"    # => "fallback"
  }
}
```

## [`unixtimestampparse`](#unixtimestampparse)

The returned object has the following attributes:

* `year` (Number) The year for the unix timestamp.
* `year_day` (Number) The day of the year for the unix timestamp, in the range 1-365 for non-leap years, and 1-366 in leap years.
* `day` (Number) The day of the month for the unix timestamp.
* `month` (Number) The month of the year for the unix timestamp.
* `month_name` (String) The name of the month for the unix timestamp (ex. "January").
* `weekday` (Number) The day of the week for the unix timestamp.
* `weekday_name` (String) The name of the day for the unix timestamp (ex. "Sunday").
* `hour` (Number) The hour within the day for the unix timestamp, in the range 0-23.
* `minute` (Number) The minute offset within the hour for the unix timestamp, in the range 0-59.
* `second` (Number) The second offset within the minute for the unix timestamp, in the range 0-59.
* `rfc3339` (String) The RFC3339 format string.
* `iso_year` (Number) The ISO 8601 year number.
* `iso_week` (Number) The ISO 8601 week number.

```hcl
# docker-bake.hcl
variable "SOURCE_DATE_EPOCH" {
  type    = number
  default = 1690328596
}

target "default" {
  args = {
    SOURCE_DATE_EPOCH = SOURCE_DATE_EPOCH
  }
  labels = {
    "org.opencontainers.image.created" = unixtimestampparse(SOURCE_DATE_EPOCH).rfc3339
  }
}
```

## [`upper`](#upper)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    result = "${upper("hello")}" # => "HELLO"
  }
}
```

## [`urlencode`](#urlencode)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    url = "${urlencode("a b=c&d")}" # => "a+b%3Dc%26d"
  }
}
```

## [`uuidv4`](#uuidv4)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    id = "${uuidv4()}" # => random v4 UUID each evaluation
  }
}
```

## [`uuidv5`](#uuidv5)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    # Uses the DNS namespace UUID per RFC 4122
    # "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    id = "${uuidv5("6ba7b810-9dad-11d1-80b4-00c04fd430c8", "example.com")}"
    # => always "9073926b-929f-31c2-abc9-fad77ae3e8eb" for "example.com"
  }
}
```

## [`values`](#values)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    vals = "${values({a=1, c=3, b=2})}" # => [1,2,3] (ordered by key: a,b,c)
  }
}
```

## [`zipmap`](#zipmap)

```hcl
# docker-bake.hcl
target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp:latest"]
  args = {
    obj = "${zipmap(["name","stars"], ["Docker", 5])}" # => {name="Docker", stars=5}
  }
}
```

----
url: https://docs.docker.com/build/bake/variables/
----

# Variables in Bake

***

Table of contents

***

You can define and use variables in a Bake file to set attribute values, interpolate them into other values, and perform arithmetic operations. Variables can be defined with default values, and can be overridden with environment variables.

## [Using variables as attribute values](#using-variables-as-attribute-values)

Use the `variable` block to define a variable.

docker-bake.hcl

```hcl
variable "TAG" {
  default = "docker.io/username/webapp:latest"
}
```

The following example shows how to use the `TAG` variable in a target.

docker-bake.hcl

```hcl
target "webapp" {
  context = "."
  dockerfile = "Dockerfile"
  tags = [ TAG ]
}
```

## [Interpolate variables into values](#interpolate-variables-into-values)

Bake supports string interpolation of variables into values. You can use the `${}` syntax to interpolate a variable into a value. The following example defines a `TAG` variable with a value of `latest`.

docker-bake.hcl

```hcl
variable "TAG" {
  default = "latest"
}
```

To interpolate the `TAG` variable into the value of an attribute, use the `${TAG}` syntax.

docker-bake.hcl

```hcl
group "default" {
  targets = [ "webapp" ]
}

variable "TAG" {
  default = "latest"
}

target "webapp" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["docker.io/username/webapp:${TAG}"]
}
```

Printing the Bake file with the `--print` flag shows the interpolated value in the resolved build configuration.

```console
$ docker buildx bake --print
```

```json
{
  "group": {
    "default": {
      "targets": ["webapp"]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": ["docker.io/username/webapp:latest"]
    }
  }
}
```

## [Validating variables](#validating-variables)

To verify that the value of a variable conforms to an expected type, value range, or other condition, you can define custom validation rules using the `validation` block.

In the following example, validation is used to enforce a numeric constraint on a variable value; the `PORT` variable must be 1024 or greater.

docker-bake.hcl

```hcl
# Define a variable `PORT` with a default value and a validation rule
variable "PORT" {
  default = 3000  # Default value assigned to `PORT`

  # Validation block to ensure `PORT` is a valid number within the acceptable range
  validation {
    condition = PORT >= 1024  # Ensure `PORT` is at least 1024
    error_message = "The variable 'PORT' must be 1024 or greater."  # Error message for invalid values
  }
}
```

If the `condition` expression evaluates to `false`, the variable value is considered invalid, whereby the build invocation fails and `error_message` is emitted. For example, if `PORT=443`, the condition evaluates to `false`, and the error is raised.

Values are coerced into the expected type before the validation is set. This ensures that any overrides set with environment variables work as expected.

### [Validate multiple conditions](#validate-multiple-conditions)

To evaluate more than one condition, define multiple `validation` blocks for the variable. All conditions must be `true`.

Here’s an example:

docker-bake.hcl

```hcl
# Define a variable `VAR` with multiple validation rules
variable "VAR" {
  # First validation block: Ensure the variable is not empty
  validation {
    condition = VAR != ""
    error_message = "The variable 'VAR' must not be empty."
  }

  # Second validation block: Ensure the value contains only alphanumeric characters
  validation {
    # VAR and the regex match must be identical:
    condition = VAR == regex("[a-zA-Z0-9]+", VAR)
    error_message = "The variable 'VAR' can only contain letters and numbers."
  }
}
```

This example enforces:

* The variable must not be empty.
* The variable must match a specific character set.

For invalid inputs like `VAR="hello@world"`, the validation would fail.

### [Validating variable dependencies](#validating-variable-dependencies)

You can reference other Bake variables in your condition expression, enabling validations that enforce dependencies between variables. This ensures that dependent variables are set correctly before proceeding.

Here’s an example:

docker-bake.hcl

```hcl
# Define a variable `FOO`
variable "FOO" {}

# Define a variable `BAR` with a validation rule that references `FOO`
variable "BAR" {
  # Validation block to ensure `FOO` is set if `BAR` is used
  validation {
    condition = FOO != ""  # Check if `FOO` is not an empty string
    error_message = "The variable 'BAR' requires 'FOO' to be set."
  }
}
```

This configuration ensures that the `BAR` variable can only be used if `FOO` has been assigned a non-empty value. Attempting to build without setting `FOO` will trigger the validation error.

## [Escape variable interpolation](#escape-variable-interpolation)

If you want to bypass variable interpolation when parsing the Bake definition, use double dollar signs (`$${VARIABLE}`).

docker-bake.hcl

```hcl
target "webapp" {
  dockerfile-inline = <<EOF
  FROM alpine
  ARG TARGETARCH
  RUN echo "Building for $${TARGETARCH/amd64/x64}"
  EOF
  platforms = ["linux/amd64", "linux/arm64"]
}
```

```console
$ docker buildx bake --progress=plain
...
#8 [linux/arm64 2/2] RUN echo "Building for arm64"
#8 0.036 Building for arm64
#8 DONE 0.0s

#9 [linux/amd64 2/2] RUN echo "Building for x64"
#9 0.046 Building for x64
#9 DONE 0.1s
...
```

## [Using variables in variables across files](#using-variables-in-variables-across-files)

When multiple files are specified, one file can use variables defined in another file. In the following example, the `vars.hcl` file defines a `BASE_IMAGE` variable with a default value of `docker.io/library/alpine`.

vars.hcl

```hcl
variable "BASE_IMAGE" {
  default = "docker.io/library/alpine"
}
```

The following `docker-bake.hcl` file defines a `BASE_LATEST` variable that references the `BASE_IMAGE` variable.

docker-bake.hcl

```hcl
variable "BASE_LATEST" {
  default = "${BASE_IMAGE}:latest"
}

target "webapp" {
  contexts = {
    base = BASE_LATEST
  }
}
```

When you print the resolved build configuration, using the `-f` flag to specify the `vars.hcl` and `docker-bake.hcl` files, you see that the `BASE_LATEST` variable is resolved to `docker.io/library/alpine:latest`.

```console
$ docker buildx bake -f vars.hcl -f docker-bake.hcl --print app
```

```json
{
  "target": {
    "webapp": {
      "context": ".",
      "contexts": {
        "base": "docker.io/library/alpine:latest"
      },
      "dockerfile": "Dockerfile"
    }
  }
}
```

## [Additional resources](#additional-resources)

Here are some additional resources that show how you can use variables in Bake:

* You can override `variable` values using environment variables. See [Overriding configurations](https://docs.docker.com/build/bake/overrides/#environment-variables) for more information.
* You can refer to and use global variables in functions. See [HCL functions](https://docs.docker.com/build/bake/funcs/#variables-in-functions)
* You can use variable values when evaluating expressions. See [Expression evaluation](https://docs.docker.com/build/bake/expressions/#expressions-with-variables)

----
url: https://docs.docker.com/reference/cli/docker/image/import/
----

# docker image import

***

| Description                                                               | Import the contents from a tarball to create a filesystem image |
| ------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Usage                                                                     | `docker image import [OPTIONS] file\|URL\|- [REPOSITORY[:TAG]]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker import`                                                 |

## [Description](#description)

You can specify a `URL` or `-` (dash) to take data directly from `STDIN`. The `URL` can point to an archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a filesystem or to an individual file on the Docker host. If you specify an archive, Docker untars it in the container relative to the `/` (root). If you specify an individual file, you must specify the full path within the host. To import from a remote location, specify a `URI` that begins with the `http://` or `https://` protocol.

## [Options](#options)

| Option                      | Default | Description                                                |
| --------------------------- | ------- | ---------------------------------------------------------- |
| [`-c, --change`](#change)   |         | Apply Dockerfile instruction to the created image          |
| [`-m, --message`](#message) |         | Set commit message for imported image                      |
| [`--platform`](#platform)   |         | API 1.32+ Set platform if server is multi-platform capable |

## [Examples](#examples)

### [Import from a remote location](#import-from-a-remote-location)

This creates a new untagged image.

```console
$ docker import https://example.com/exampleimage.tgz
```

### [Import from a local file](#import-from-a-local-file)

Import to docker via pipe and `STDIN`.

```console
$ cat exampleimage.tgz | docker import - exampleimagelocal:new
```

Import to docker from a local archive.

```console
$ docker import /path/to/exampleimage.tgz
```

### [Import from a local directory](#import-from-a-local-directory)

```console
$ sudo tar -c . | docker import - exampleimagedir
```

Note the `sudo` in this example – you must preserve the ownership of the files (especially root ownership) during the archiving with tar. If you are not root (or the sudo command) when you tar, then the ownerships might not get preserved.

### [Import with new configurations (-c, --change)](#change)

The `--change` option applies `Dockerfile` instructions to the image that is created. Not all `Dockerfile` instructions are supported; the list of instructions is limited to metadata (configuration) changes. The following `Dockerfile` instructions are supported:

* [`CMD`](/reference/dockerfile/#cmd)
* [`ENTRYPOINT`](/reference/dockerfile/#entrypoint)
* [`ENV`](/reference/dockerfile/#env)
* [`EXPOSE`](/reference/dockerfile/#expose)
* [`HEALTHCHECK`](/reference/dockerfile/#healthcheck)
* [`LABEL`](/reference/dockerfile/#label)
* [`ONBUILD`](/reference/dockerfile/#onbuild)
* [`STOPSIGNAL`](/reference/dockerfile/#stopsignal)
* [`USER`](/reference/dockerfile/#user)
* [`VOLUME`](/reference/dockerfile/#volume)
* [`WORKDIR`](/reference/dockerfile/#workdir)

The following example imports an image from a TAR-file containing a root-filesystem, and sets the `DEBUG` environment-variable in the resulting image:

```console
$ docker import --change "ENV DEBUG=true" ./rootfs.tgz exampleimagedir
```

The `--change` option can be set multiple times to apply multiple `Dockerfile` instructions. The example below sets the `LABEL1` and `LABEL2` labels on the imported image, in addition to the `DEBUG` environment variable from the previous example:

```console
$ docker import \
    --change "ENV DEBUG=true" \
    --change "LABEL LABEL1=hello" \
    --change "LABEL LABEL2=world" \
    ./rootfs.tgz exampleimagedir
```

### [Import with a commit message (-m, --message)](#message)

The `--message` (or `-m`) option allows you to set a custom comment in the image's metadata. The following example imports an image from a local archive and sets a custom message.

```console
$ docker import --message "New image imported from tarball" ./rootfs.tgz exampleimagelocal:new
sha256:25e54c0df7dc49da9093d50541e0ed4508a6b78705057f1a9bebf1d564e2cb00
```

After importing, the message is set in the "Comment" field of the image's configuration, which is shown when viewing the image's history:

```console
$ docker image history exampleimagelocal:new

IMAGE          CREATED         CREATED BY   SIZE      COMMENT
25e54c0df7dc   2 minutes ago                53.6MB    New image imported from tarball
```

### [When the daemon supports multiple operating systems](#when-the-daemon-supports-multiple-operating-systems)

If the daemon supports multiple operating systems, and the image being imported does not match the default operating system, it may be necessary to add `--platform`. This would be necessary when importing a Linux image into a Windows daemon.

```console
$ docker import --platform=linux .\linuximage.tar
```

### [Set the platform for the imported image (--platform)](#platform)

The `--platform` option allows you to specify the platform for the imported image. By default, the daemon's native platform is used as platform, but the `--platform` option allows you to override the default, for example, in situations where the imported root filesystem is for a different architecture or operating system.

The platform option takes the `os[/arch[/variant]]` format; for example, `linux/amd64` or `linux/arm64/v8`. Architecture and variant are optional, and default to the daemon's native architecture if omitted.

The following example imports an image from a root-filesystem in `rootfs.tgz`, and sets the image's platform to `linux/amd64`;

```console
$ docker image import --platform=linux/amd64  ./rootfs.tgz imported:latest
sha256:44a8b44157dad5edcff85f0c93a3e455f3b20a046d025af4ec50ed990d7ebc09
```

After importing the image, the image's platform is set in the image's configuration;

```console
$ docker image inspect --format '{{.Os}}/{{.Architecture}}' imported:latest
linux/amd64
```

----
url: https://docs.docker.com/extensions/extensions-sdk/design/mui-best-practices/
----

# MUI best practices

***

Table of contents

***

This article assumes you're following our recommended practice by using our [Material UI theme](https://www.npmjs.com/package/@docker/docker-mui-theme). Following the steps below maximizes compatibility with Docker Desktop and minimizes the work you need to do as an extension author. They should be considered supplementary to the non-MUI-specific guidelines found in the [UI Styling overview](https://docs.docker.com/extensions/extensions-sdk/design/).

## [Assume the theme can change at any time](#assume-the-theme-can-change-at-any-time)

Resist the temptation to fine-tune your UI with precise colors, offsets and font sizings to make it look as attractive as possible. Any specializations you make today will be relative to the current MUI theme, and may look worse when the theme changes. Any part of the theme might change without warning, including (but not limited to):

* The font, or font sizes

* Border thicknesses or styles

* Colors:

  * Our palette members (e.g. `red-100`) could change their RGB values
  * The semantic colors (e.g. `error`, `primary`, `textPrimary`, etc) could be changed to use a different member of our palette
  * Background colors (e.g. those of the page, or of dialogs) could change

* Spacings:

  * The size of the basic unit of spacing,(exposed via `theme.spacing`. For instance, we may allow users to customize the density of the UI
  * The default spacing between paragraphs or grid items

The best way to build your UI, so that it’s robust against future theming changes, is to:

* Override the default styling as little as possible.
* Use semantic typography. e.g. use `Typography`s or `Link`s with appropriate `variant`s instead of using typographical HTML elements (`<a>`, `<p>`, `<h1>`, etc) directly.
* Use canned sizes. e.g. use `size="small"` on buttons, or `fontSize="small"` on icons, instead of specifying sizes in pixels.
* Prefer semantic colors. e.g. use `error` or `primary` over explicit color codes.
* Write as little CSS as possible. Write semantic markup instead. For example, if you want to space out paragraphs of text, use the `paragraph` prop on your `Typography` instances. If you want to space out something else, use a `Stack` or `Grid` with the default spacing.
* Use visual idioms you’ve seen in the Docker Desktop UI, since these are the main ones we’ll test any theme changes against.

## [When you go custom, centralize it](#when-you-go-custom-centralize-it)

Sometimes you’ll need a piece of UI that doesn’t exist in our design system. If so, we recommend that you first reach out to us. We may already have something in our internal design system, or we may be able to expand our design system to accommodate your use case.

If you still decide to build it yourself after contacting us, try and define the new UI in a reusable fashion. If you define your custom UI in just one place, it’ll make it easier to change in the future if our core theme changes. You could use:

* A new `variant` of an existing component - see [MUI docs](https://mui.com/material-ui/customization/theme-components/#creating-new-component-variants)
* A MUI mixin (a freeform bundle of reusable styling rules defined inside a theme)
* A new [reusable component](https://mui.com/material-ui/customization/how-to-customize/#2-reusable-component)

Some of the above options require you to extend our MUI theme. See the MUI documentation on [theme composition](https://mui.com/material-ui/customization/theming/#nesting-the-theme).

## [What's next?](#whats-next)

* Take a look at our [UI styling guide](https://docs.docker.com/extensions/extensions-sdk/design/).
* Learn how to [publish your extension](https://docs.docker.com/extensions/extensions-sdk/extensions/).

----
url: https://docs.docker.com/ai/gordon/how-to/configure-tools/
----

# Configure Gordon's tools

***

Table of contents

***

Requires: Docker Desktop [4.74.0](https://docs.docker.com/desktop/release-notes/#4740) or later

Gordon includes built-in tools that extend its capabilities. You can configure which tools Gordon has access to based on your security requirements and workflow needs.

Tool configuration provides an additional layer of control:

* Enabled tools: Gordon can propose actions using these tools (subject to your approval)
* Disabled tools: Gordon cannot use these tools, and will not request permission to use them

## [Accessing tool settings](#accessing-tool-settings)

To configure Gordon's tools:

1. Open Docker Desktop.

2. Select **Gordon** in the sidebar.

3. Select the settings icon at the bottom of the text input area.

The tool settings dialog opens with two tabs: **Basic** and **Advanced**.

## [Basic tool settings](#basic-tool-settings)

In the **Basic** tab, you can enable or disable individual tools globally.

To disable a tool:

1. Find the tool you want to disable in the list.
2. Toggle it off.
3. Select **Save**.

Disabled tools cannot be used by Gordon, even with your approval.

## [Advanced tool settings](#advanced-tool-settings)

The **Advanced** tab lets you create fine-grained allow-lists and deny-lists for specific commands or patterns.

Allow-lists: Gordon can use allow-listed commands even when the main tool is disabled. For example, disable the shell tool but allow `cat`, `grep`, and `ls`.

Deny-lists: Block specific commands while keeping the tool enabled. For example, allow the shell tool but deny `chown` and `chmod`.

To configure:

1. Switch to the **Advanced** tab.
2. Add commands to **Allow rules** or **Deny rules**.
3. Select **Save**.

Gordon still requests approval before running allow-listed tools, unless YOLO mode (auto-approve mode that bypasses permission checks) is enabled.

## [Organizational controls](#organizational-controls)

For Business subscriptions, administrators can control tool access for the entire organization using Settings Management.

Administrators can:

* Disable specific tools for all users
* Lock tool configuration to prevent users from changing it
* Set organization-wide tool policies

See [Settings Management](/enterprise/security/hardened-desktop/settings-management/) for details.

----
url: https://docs.docker.com/engine/swarm/ingress/
----

# Use Swarm mode routing mesh

***

Table of contents

***

Docker Engine Swarm mode makes it easy to publish ports for services to make them available to resources outside the swarm. All nodes participate in an ingress routing mesh. The routing mesh enables each node in the swarm to accept connections on published ports for any service running in the swarm, even if there's no task running on the node. The routing mesh routes all incoming requests to published ports on available nodes to an active container.

To use the ingress network in the swarm, you need to have the following ports open between the swarm nodes before you enable Swarm mode:

* Port `7946` TCP/UDP for container network discovery.
* Port `4789` UDP (configurable) for the container ingress network.

When setting up networking in a Swarm, special care should be taken. Consult the [tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/#open-protocols-and-ports-between-the-hosts) for an overview.

You must also open the published port between the swarm nodes and any external resources, such as an external load balancer, that require access to the port.

You can also [bypass the routing mesh](#bypass-the-routing-mesh) for a given service.

## [Publish a port for a service](#publish-a-port-for-a-service)

Use the `--publish` flag to publish a port when you create a service. `target` is used to specify the port inside the container, and `published` is used to specify the port to bind on the routing mesh. If you leave off the `published` port, a random high-numbered port is bound for each service task. You need to inspect the task to determine the port.

```console
$ docker service create \
  --name <SERVICE-NAME> \
  --publish published=<PUBLISHED-PORT>,target=<CONTAINER-PORT> \
  IMAGE
```

> Note
>
> The older form of this syntax is a colon-separated string, where the published port is first and the target port is second, such as `-p 8080:80`. The new syntax is preferred because it is easier to read and allows more flexibility.

The `<PUBLISHED-PORT>` is the port where the swarm makes the service available. If you omit it, a random high-numbered port is bound. The `<CONTAINER-PORT>` is the port where the container listens. This parameter is required.

For example, the following command publishes port 80 in the nginx container to port 8080 for any node in the swarm:

```console
$ docker service create \
  --name my-web \
  --publish published=8080,target=80 \
  --replicas 2 \
  nginx
```

When you access port 8080 on any node, Docker routes your request to an active container. On the swarm nodes themselves, port 8080 may not actually be bound, but the routing mesh knows how to route the traffic and prevents any port conflicts from happening.

The routing mesh listens on the published port for any IP address assigned to the node. For externally routable IP addresses, the port is available from outside the host. For all other IP addresses the access is only available from within the host.

You can publish a port for an existing service using the following command:

```console
$ docker service update \
  --publish-add published=<PUBLISHED-PORT>,target=<CONTAINER-PORT> \
  SERVICE
```

You can use `docker service inspect` to view the service's published port. For instance:

```console
$ docker service inspect --format="{{json .Endpoint.Spec.Ports}}" my-web

[{"Protocol":"tcp","TargetPort":80,"PublishedPort":8080}]
```

The output shows the `<CONTAINER-PORT>` (labeled `TargetPort`) from the containers and the `<PUBLISHED-PORT>` (labeled `PublishedPort`) where nodes listen for requests for the service.

### [Publish a port for TCP only or UDP only](#publish-a-port-for-tcp-only-or-udp-only)

By default, when you publish a port, it is a TCP port. You can specifically publish a UDP port instead of or in addition to a TCP port. When you publish both TCP and UDP ports, if you omit the protocol specifier, the port is published as a TCP port. If you use the longer syntax (recommended), set the `protocol` key to either `tcp` or `udp`.

#### [TCP only](#tcp-only)

Long syntax:

```console
$ docker service create --name dns-cache \
  --publish published=53,target=53 \
  dns-cache
```

Short syntax:

```console
$ docker service create --name dns-cache \
  -p 53:53 \
  dns-cache
```

#### [TCP and UDP](#tcp-and-udp)

Long syntax:

```console
$ docker service create --name dns-cache \
  --publish published=53,target=53 \
  --publish published=53,target=53,protocol=udp \
  dns-cache
```

Short syntax:

```console
$ docker service create --name dns-cache \
  -p 53:53 \
  -p 53:53/udp \
  dns-cache
```

#### [UDP only](#udp-only)

Long syntax:

```console
$ docker service create --name dns-cache \
  --publish published=53,target=53,protocol=udp \
  dns-cache
```

Short syntax:

```console
$ docker service create --name dns-cache \
  -p 53:53/udp \
  dns-cache
```

## [Bypass the routing mesh](#bypass-the-routing-mesh)

By default, swarm services which publish ports do so using the routing mesh. When you connect to a published port on any swarm node (whether it is running a given service or not), you are redirected to a worker which is running that service, transparently. Effectively, Docker acts as a load balancer for your swarm services.

You can bypass the routing mesh, so that when you access the bound port on a given node, you are always accessing the instance of the service running on that node. This is referred to as `host` mode. There are a few things to keep in mind.

* If you access a node which is not running a service task, the service does not listen on that port. It is possible that nothing is listening, or that a completely different application is listening.

* If you expect to run multiple service tasks on each node (such as when you have 5 nodes but run 10 replicas), you cannot specify a static target port. Either allow Docker to assign a random high-numbered port (by leaving off the `published`), or ensure that only a single instance of the service runs on a given node, by using a global service rather than a replicated one, or by using placement constraints.

To bypass the routing mesh, you must use the long `--publish` service and set `mode` to `host`. If you omit the `mode` key or set it to `ingress`, the routing mesh is used. The following command creates a global service using `host` mode and bypassing the routing mesh.

```console
$ docker service create --name dns-cache \
  --publish published=53,target=53,protocol=udp,mode=host \
  --mode global \
  dns-cache
```

## [Configure an external load balancer](#configure-an-external-load-balancer)

You can configure an external load balancer for swarm services, either in combination with the routing mesh or without using the routing mesh at all.

### [Using the routing mesh](#using-the-routing-mesh)

You can configure an external load balancer to route requests to a swarm service. For example, you could configure [HAProxy](https://www.haproxy.org) to balance requests to an nginx service published to port 8080.

In this case, port 8080 must be open between the load balancer and the nodes in the swarm. The swarm nodes can reside on a private network that is accessible to the proxy server, but that is not publicly accessible.

You can configure the load balancer to balance requests between every node in the swarm even if there are no tasks scheduled on the node. For example, you could have the following HAProxy configuration in `/etc/haproxy/haproxy.cfg`:

```bash
global
        log /dev/log    local0
        log /dev/log    local1 notice
...snip...

# Configure HAProxy to listen on port 80
frontend http_front
   bind *:80
   stats uri /haproxy?stats
   default_backend http_back

# Configure HAProxy to route requests to swarm nodes on port 8080
backend http_back
   balance roundrobin
   server node1 192.168.99.100:8080 check
   server node2 192.168.99.101:8080 check
   server node3 192.168.99.102:8080 check
```

When you access the HAProxy load balancer on port 80, it forwards requests to nodes in the swarm. The swarm routing mesh routes the request to an active task. If, for any reason the swarm scheduler dispatches tasks to different nodes, you don't need to reconfigure the load balancer.

You can configure any type of load balancer to route requests to swarm nodes. To learn more about HAProxy, see the [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/).

### [Without the routing mesh](#without-the-routing-mesh)

To use an external load balancer without the routing mesh, set `--endpoint-mode` to `dnsrr` instead of the default value of `vip`. In this case, there is not a single virtual IP. Instead, Docker sets up DNS entries for the service such that a DNS query for the service name returns a list of IP addresses, and the client connects directly to one of these.

You can't use `--endpoint-mode dnsrr` together with `--publish mode=ingress`. You must run your own load balancer in front of the service. A DNS query for the service name on the Docker host returns a list of IP addresses for the nodes running the service. Configure your load balancer to consume this list and balance the traffic across the nodes. See [Configure service discovery](https://docs.docker.com/engine/swarm/networking/#configure-service-discovery).

## [Learn more](#learn-more)

* [Deploy services to a swarm](https://docs.docker.com/engine/swarm/services/)

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/
----

# docker dhi customization

***

| Description                                                               | Manage Docker Hardened Images customizations |
| ------------------------------------------------------------------------- | -------------------------------------------- |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker dhi c` `docker dhi custo`            |

## [Description](#description)

Commands to list, create, edit, and delete Docker Hardened Images customizations

## [Options](#options)

| Option  | Default | Description                                |
| ------- | ------- | ------------------------------------------ |
| `--org` |         | Docker Hub organization (overrides config) |

## [Subcommands](#subcommands)

| Command                                                                                                       | Description                                                     |
| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [`docker dhi customization build`](https://docs.docker.com/reference/cli/docker/dhi/customization/build/)     | Manage customization builds                                     |
| [`docker dhi customization create`](https://docs.docker.com/reference/cli/docker/dhi/customization/create/)   | Create a new customization from YAML file                       |
| [`docker dhi customization delete`](https://docs.docker.com/reference/cli/docker/dhi/customization/delete/)   | Delete one or more customizations                               |
| [`docker dhi customization edit`](https://docs.docker.com/reference/cli/docker/dhi/customization/edit/)       | Edit an existing customization from YAML file                   |
| [`docker dhi customization get`](https://docs.docker.com/reference/cli/docker/dhi/customization/get/)         | Get details of a specific customization                         |
| [`docker dhi customization list`](https://docs.docker.com/reference/cli/docker/dhi/customization/list/)       | List all customizations                                         |
| [`docker dhi customization prepare`](https://docs.docker.com/reference/cli/docker/dhi/customization/prepare/) | Prepare a new customization YAML file from a DHI base image tag |

----
url: https://docs.docker.com/scout/integrations/environment/cli/
----

# Generic environment integration with CLI

***

Table of contents

***

You can create a generic environment integration by running the Docker Scout CLI client in your CI workflows. The CLI client is available as a binary on GitHub and as a container image on Docker Hub. Use the client to invoke the `docker scout environment` command to assign your images to environments.

For more information about how to use the `docker scout environment` command, refer to the [CLI reference](/reference/cli/docker/scout/environment/).

## [Examples](#examples)

Before you start, set the following environment variables in your CI system:

* `DOCKER_SCOUT_HUB_USER`: your Docker Hub username
* `DOCKER_SCOUT_HUB_PASSWORD`: your Docker Hub personal access token

Make sure the variables are accessible to your project.

```yaml
version: 2.1

jobs:
  record_environment:
    machine:
      image: ubuntu-2204:current
    image: namespace/repo
    steps:
      - run: |
          if [[ -z "$CIRCLE_TAG" ]]; then
            tag="$CIRCLE_TAG"
            echo "Running tag '$CIRCLE_TAG'"
          else
            tag="$CIRCLE_BRANCH"
            echo "Running on branch '$CI_COMMIT_BRANCH'"
          fi    
          echo "tag = $tag"
      - run: docker run -it \
          -e DOCKER_SCOUT_HUB_USER=$DOCKER_SCOUT_HUB_USER \
          -e DOCKER_SCOUT_HUB_PASSWORD=$DOCKER_SCOUT_HUB_PASSWORD \
          docker/scout-cli:1.0.2 environment \
          --org "MY_DOCKER_ORG" \
          "ENVIRONMENT" ${image}:${tag}
```

The following example uses the [Docker executor](https://docs.gitlab.com/runner/executors/docker.html).

```yaml
variables:
  image: namespace/repo

record_environment:
  image: docker/scout-cli:1.0.2
  script:
    - |
      if [[ -z "$CI_COMMIT_TAG" ]]; then
        tag="latest"
        echo "Running tag '$CI_COMMIT_TAG'"
      else
        tag="$CI_COMMIT_REF_SLUG"
        echo "Running on branch '$CI_COMMIT_BRANCH'"
      fi    
      echo "tag = $tag"
    - environment --org MY_DOCKER_ORG "PRODUCTION" ${image}:${tag}
```

```yaml
trigger:
  - main

resources:
  - repo: self

variables:
  tag: "$(Build.BuildId)"
  image: "namespace/repo"

stages:
  - stage: Docker Scout
    displayName: Docker Scout environment integration
    jobs:
      - job: Record
        displayName: Record environment
        pool:
          vmImage: ubuntu-latest
        steps:
          - task: Docker@2
          - script: docker run -it \
              -e DOCKER_SCOUT_HUB_USER=$DOCKER_SCOUT_HUB_USER \
              -e DOCKER_SCOUT_HUB_PASSWORD=$DOCKER_SCOUT_HUB_PASSWORD \
              docker/scout-cli:1.0.2 environment \
              --org "MY_DOCKER_ORG" \
              "ENVIRONMENT" $(image):$(tag)
```

```groovy
stage('Analyze image') {
    steps {
        // Install Docker Scout
        sh 'curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- -b /usr/local/bin'
        
        // Log into Docker Hub
        sh 'echo $DOCKER_SCOUT_HUB_PASSWORD | docker login -u $DOCKER_SCOUT_HUB_USER --password-stdin'

        // Analyze and fail on critical or high vulnerabilities
        sh 'docker-scout environment --org "MY_DOCKER_ORG" "ENVIRONMENT" $IMAGE_TAG
    }
}
```

----
url: https://docs.docker.com/reference/cli/docker/mcp/secret/set/
----

# docker mcp secret set

***

| Description | Set a secret in the local OS Keychain |
| ----------- | ------------------------------------- |
| Usage       | `docker mcp secret set key[=value]`   |

## [Description](#description)

Set a secret in the local OS Keychain

## [Examples](#examples)

### [Pass the secret via STDIN](#pass-the-secret-via-stdin)

```console
echo my-secret-password > pwd.txt
cat pwd.txt | docker mcp secret set postgres_password
```

----
url: https://docs.docker.com/reference/api/engine/version/v1.54/
----

# Docker Engine API v1.54 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.54.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.54.yaml)

# Docker Engine API (1.54)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.54.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.54/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.54/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.54/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf",
"Created": "2025-02-17T17:43:39.64001363Z",
"Path": "/bin/sh",
"Args": [
"-c",
"exit 9"
],
"State": {
"Status": "running",
"Running": true,
"Paused": false,
"Restarting": false,
"OOMKilled": false,
"Dead": false,
"Pid": 1234,
"ExitCode": 0,
"Error": "string",
"StartedAt": "2020-01-06T09:06:59.461876391Z",
"FinishedAt": "2020-01-06T09:07:59.461876391Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2020-01-04T10:44:24.496525531Z",
"End": "2020-01-04T10:45:21.364524523Z",
"ExitCode": 0,
"Output": "string"
}
]
}
},
"Image": "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782",
"ResolvConfPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/resolv.conf",
"HostnamePath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hostname",
"HostsPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hosts",
"LogPath": "/var/lib/docker/containers/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59-json.log",
"Name": "/funny_chatelet",
"RestartCount": 0,
"Driver": "overlayfs",
"Platform": "linux",
"ImageManifestDescriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"MountLabel": "",
"ProcessLabel": "",
"AppArmorProfile": "",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"CpuShares": 0,
"Memory": 0,
"CgroupParent": "string",
"BlkioWeight": 1000,
"BlkioWeightDevice": [
{
"Path": "string",
"Weight": 0
}
],
"BlkioDeviceReadBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceReadIOps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteIOps": [
{
"Path": "string",
"Rate": 0
}
],
"CpuPeriod": 0,
"CpuQuota": 0,
"CpuRealtimePeriod": 0,
"CpuRealtimeRuntime": 0,
"CpusetCpus": "0-3",
"CpusetMems": "string",
"Devices": [
{
"PathOnHost": "/dev/deviceName",
"PathInContainer": "/dev/deviceName",
"CgroupPermissions": "mrw"
}
],
"DeviceCgroupRules": [
"c 13:* rwm"
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 100,
"NanoCpus": 0,
"OomKillDisable": true,
"Init": true,
"PidsLimit": 0,
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
],
"CpuCount": 0,
"CpuPercent": 0,
"IOMaximumIOps": 0,
"IOMaximumBandwidth": 0,
"Binds": [
"string"
],
"ContainerIDFile": "",
"LogConfig": {
"Type": "local",
"Config": {
"max-file": "5",
"max-size": "10m"
}
},
"NetworkMode": "string",
"PortBindings": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"VolumeDriver": "string",
"VolumesFrom": [
"string"
],
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"ConsoleSize": [
80,
64
],
"Annotations": {
"property1": "string",
"property2": "string"
},
"CapAdd": [
"string"
],
"CapDrop": [
"string"
],
"CgroupnsMode": "private",
"Dns": [
"string"
],
"DnsOptions": [
"string"
],
"DnsSearch": [
"string"
],
"ExtraHosts": [
"string"
],
"GroupAdd": [
"string"
],
"IpcMode": "string",
"Cgroup": "string",
"Links": [
"string"
],
"OomScoreAdj": 500,
"PidMode": "string",
"Privileged": true,
"PublishAllPorts": true,
"ReadonlyRootfs": true,
"SecurityOpt": [
"string"
],
"StorageOpt": {
"property1": "string",
"property2": "string"
},
"Tmpfs": {
"property1": "string",
"property2": "string"
},
"UTSMode": "string",
"UsernsMode": "string",
"ShmSize": 0,
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Runtime": "string",
"Isolation": "default",
"MaskedPaths": [
"/proc/asound",
"/proc/acpi",
"/proc/kcore",
"/proc/keys",
"/proc/latency_stats",
"/proc/timer_list",
"/proc/timer_stats",
"/proc/sched_debug",
"/proc/scsi",
"/sys/firmware",
"/sys/devices/virtual/powercap"
],
"ReadonlyPaths": [
"/proc/bus",
"/proc/fs",
"/proc/irq",
"/proc/sys",
"/proc/sysrq-trigger"
]
},
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"Storage": {
"RootFS": {
"Snapshot": {
"Name": "string"
}
}
},
"SizeRw": "122880",
"SizeRootFs": "1653948416",
"Mounts": [
{
"Type": "volume",
"Name": "myvolume",
"Source": "/var/lib/docker/volumes/myvolume/_data",
"Destination": "/usr/share/nginx/html/",
"Driver": "local",
"Mode": "z",
"RW": true,
"Propagation": ""
}
],
"Config": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"NetworkSettings": {
"SandboxID": "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3",
"SandboxKey": "/var/run/docker/netns/8ab54b426c38",
"Ports": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"Networks": {
"property1": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
},
"property2": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
}
}
}
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.54/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": {
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
]
},
"Processes": {
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.54/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.54/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.54/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.54/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"name": "boring_wozniak",
"os_type": "linux",
"read": "2025-01-16T13:55:22.165243637Z",
"cpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"memory_stats": {
"usage": 0,
"max_usage": 0,
"stats": {
"active_anon": 1572864,
"active_file": 5115904,
"anon": 1572864,
"anon_thp": 0,
"file": 7626752,
"file_dirty": 0,
"file_mapped": 2723840,
"file_writeback": 0,
"inactive_anon": 0,
"inactive_file": 2510848,
"kernel_stack": 16384,
"pgactivate": 0,
"pgdeactivate": 0,
"pgfault": 2042,
"pglazyfree": 0,
"pglazyfreed": 0,
"pgmajfault": 45,
"pgrefill": 0,
"pgscan": 0,
"pgsteal": 0,
"shmem": 0,
"slab": 1180928,
"slab_reclaimable": 725576,
"slab_unreclaimable": 455352,
"sock": 0,
"thp_collapse_alloc": 0,
"thp_fault_alloc": 1,
"unevictable": 0,
"workingset_activate": 0,
"workingset_nodereclaim": 0,
"workingset_refault": 0
},
"failcnt": 0,
"limit": 8217579520,
"commitbytes": 0,
"commitpeakbytes": 0,
"privateworkingset": 0
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"pids_stats": {
"current": 5,
"limit": "18446744073709551615"
},
"blkio_stats": {
"io_service_bytes_recursive": [
{
"major": 254,
"minor": 0,
"op": "read",
"value": 7593984
},
{
"major": 254,
"minor": 0,
"op": "write",
"value": 100
}
],
"io_serviced_recursive": null,
"io_queue_recursive": null,
"io_service_time_recursive": null,
"io_wait_time_recursive": null,
"io_merged_recursive": null,
"io_time_recursive": null,
"sectors_recursive": null
},
"num_procs": 16,
"storage_stats": {
"read_count_normalized": 7593984,
"read_size_bytes": 7593984,
"write_count_normalized": 7593984,
"write_size_bytes": 7593984
},
"preread": "2025-01-16T13:55:21.160452595Z",
"precpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.54/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.54/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.54/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.54/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.54/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.54/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"Published ports are discarded when using host network mode"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.54/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.54/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.54/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.54/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.54/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.54/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.54/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.54/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.54/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.54/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.54/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |
| manifests   | booleanDefault: falseInclude `Manifests` in the image summary.                                                                                                                                                                                                                                                                                                                                       |
| identity    | booleanDefault: falseInclude `Identity` in each manifest summary. Requires `manifests=1`.                                                                                                                                                                                                                                                                                                            |

### Responses

/v1.54/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2,
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Identity": {
"Signature": [
{
"Name": "string",
"Timestamps": [
{
"Type": null,
"URI": null,
"Timestamp": null
}
],
"KnownSigner": "DHI",
"DockerReference": "string",
"Signer": {
"CertificateIssuer": "string",
"SubjectAlternativeName": "string",
"Issuer": "string",
"BuildSignerURI": "string",
"BuildSignerDigest": "string",
"RunnerEnvironment": "string",
"SourceRepositoryURI": "string",
"SourceRepositoryDigest": "string",
"SourceRepositoryRef": "string",
"SourceRepositoryIdentifier": "string",
"SourceRepositoryOwnerURI": "string",
"SourceRepositoryOwnerIdentifier": "string",
"BuildConfigURI": "string",
"BuildConfigDigest": "string",
"BuildTrigger": "string",
"RunInvocationURI": "string",
"SourceRepositoryVisibilityAtSigning": "string"
},
"SignatureType": "bundle-v0.3",
"Error": "string",
"Warnings": [
"string"
]
}
],
"Pull": [
{
"Repository": "string"
}
],
"Build": [
{
"Ref": "string",
"CreatedAt": "2019-08-24T14:15:22Z"
}
]
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
}
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.54/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| reserved-space | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| max-used-space | integer \<int64>Maximum amount of disk space allowed to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                   |
| min-free-space | integer \<int64>Target amount of free disk space after pruning                                                                                                                                                                                                                                                                                                                                                                                                           |
| all            | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters        | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.54/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. If the name includes a tag or digest, specific behavior applies:- If only `fromImage` includes a tag, that tag is used.
- If both `fromImage` and `tag` are provided, `tag` takes precedence.
- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.
- If neither a tag nor digest is specified, all tags are pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.54/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| manifests | booleanDefault: falseInclude Manifests in the image summary.The `manifests` and `platform` options are mutually exclusive, and an error is produced if both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show inspect. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.The `platform` and `manifests` options are mutually exclusive, and an error is produced if both are set.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.54/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Identity": {
"Signature": [
{
"Name": "string",
"Timestamps": [
{
"Type": "Tlog",
"URI": "string",
"Timestamp": "2019-08-24T14:15:22Z"
}
],
"KnownSigner": "DHI",
"DockerReference": "string",
"Signer": {
"CertificateIssuer": "string",
"SubjectAlternativeName": "string",
"Issuer": "string",
"BuildSignerURI": "string",
"BuildSignerDigest": "string",
"RunnerEnvironment": "string",
"SourceRepositoryURI": "string",
"SourceRepositoryDigest": "string",
"SourceRepositoryRef": "string",
"SourceRepositoryIdentifier": "string",
"SourceRepositoryOwnerURI": "string",
"SourceRepositoryOwnerIdentifier": "string",
"BuildConfigURI": "string",
"BuildConfigDigest": "string",
"BuildTrigger": "string",
"RunInvocationURI": "string",
"SourceRepositoryVisibilityAtSigning": "string"
},
"SignatureType": "bundle-v0.3",
"Error": "string",
"Warnings": [
"string"
]
}
],
"Pull": [
{
"Repository": "string"
}
],
"Build": [
{
"Ref": "string",
"CreatedAt": "2019-08-24T14:15:22Z"
}
]
},
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Identity": {
"Signature": [
{
"Name": "string",
"Timestamps": [
{
"Type": "Tlog",
"URI": "string",
"Timestamp": "2019-08-24T14:15:22Z"
}
],
"KnownSigner": "DHI",
"DockerReference": "string",
"Signer": {
"CertificateIssuer": "string",
"SubjectAlternativeName": "string",
"Issuer": "string",
"BuildSignerURI": "string",
"BuildSignerDigest": "string",
"RunnerEnvironment": "string",
"SourceRepositoryURI": "string",
"SourceRepositoryDigest": "string",
"SourceRepositoryRef": "string",
"SourceRepositoryIdentifier": "string",
"SourceRepositoryOwnerURI": "string",
"SourceRepositoryOwnerIdentifier": "string",
"BuildConfigURI": "string",
"BuildConfigDigest": "string",
"BuildTrigger": "string",
"RunInvocationURI": "string",
"SourceRepositoryVisibilityAtSigning": "string"
},
"SignatureType": "bundle-v0.3",
"Error": "string",
"Warnings": [
"string"
]
}
],
"Pull": [
{
"Repository": "string"
}
],
"Build": [
{
"Ref": "string",
"CreatedAt": "2019-08-24T14:15:22Z"
}
]
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"Author": "",
"Config": {
"User": "web:web",
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show the history for. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.54/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag      | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed.                                                                                                                                                                                                                                                                                                                   |
| platform | stringJSON-encoded OCI platform to select the platform-variant to push. If not provided, all available variants will attempt to be pushed.If the daemon provides a multi-platform image store, this selects the platform-variant to push to the registry. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.54/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.54/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|           |                                                                                                                                                     |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| force     | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags                                              |
| noprune   | booleanDefault: falseDo not delete untagged parent images                                                                                           |
| platforms | Array of stringsSelect platform-specific content to delete. Multiple values are accepted. Each platform is a OCI platform encoded as a JSON string. |

### Responses

/v1.54/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                   |
| limit        | integerMaximum number of results to return                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.54/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.54/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.54/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | Array of stringsJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.54/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| names    | Array of stringsImage names to filter by                                                                                                                                                                                                                                             |
| platform | Array of stringsJSON encoded OCI platform(s) which will be used to select the platform-specific image(s) to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.54/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| quiet    | booleanDefault: falseSuppress progress details during load.                                                                                                                                                                                                                       |
| platform | Array of stringsJSON encoded OCI platform(s) which will be used to select the platform-specific image(s) to load if the image is multi-platform. If not provided, the full multi-platform image will be loaded.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.54/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.54/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv4": true,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.54/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Services": {
"property1": null,
"property2": null
},
"Status": {
"IPAM": {
"Subnets": {
"172.16.0.0/16": {
"IPsInUse": 3,
"DynamicIPsAvailable": 65533
},
"2001:db8:abcd:0012::0/96": {
"IPsInUse": 5,
"DynamicIPsAvailable": 4294967291
}
}
}
},
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv4": true,
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.54/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|              |                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired | stringThe network's name.                                                                                                                                                                                                              |
| Driver       | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope        | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal     | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable   | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress      | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly   | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|              | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|              | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv4   | booleanEnable IPv4 on the network.                                                                                                                                                                                                     |
| EnableIPv6   | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|              | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|              | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.54/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv4": true,
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|                   |                                                                  |
| ----------------- | ---------------------------------------------------------------- |
| Containerrequired | stringThe ID or name of the container to connect to the network. |
|                   | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.54/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|                   |                                                                          |
| ----------------- | ------------------------------------------------------------------------ |
| Containerrequired | stringThe ID or name of the container to disconnect from the network.    |
| Force             | booleanDefault: falseForce the container to disconnect from the network. |

### Responses

/v1.54/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"Force": false
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.54/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.54/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.54/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.54/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.54/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.54/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.54/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.54/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.54/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.54/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.54/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.54/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.54/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.54/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.54/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.54/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.54/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.54/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.54/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.54/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.54/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.54/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.54/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.54/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"SwapBytes": -1,
"MemorySwappiness": -1
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.54/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.54/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.54/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"SwapBytes": -1,
"MemorySwappiness": -1
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.54/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.54/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.54/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.54/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.54/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.54/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.54/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.54/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.54/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.54/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.54/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.54/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.54/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.54/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.54/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.54/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.54/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.54/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.54/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.54/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.54/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.54/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.54/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.54/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.54/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |        |
| ------------- | ------ |
| username      | string |
| password      | string |
| serveraddress | string |

### Responses

/v1.54/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.54/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "6.8.0-31-generic",
"OperatingSystem": "Ubuntu 24.04 LTS",
"OSVersion": "24.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "27.0.1",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"FirewallBackend": {
"Driver": "nftables",
"Info": [ [
"ReloadedAt",
"2025-01-01T00:00:00Z"
]
]
},
"DiscoveredDevices": [
{
"Source": "cdi",
"ID": "vendor.com/gpu=0"
}
],
"NRI": {
"Info": [ [
"plugin-path",
"/opt/docker/nri/plugins"
]
]
},
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
],
"Containerd": {
"Address": "/run/containerd/containerd.sock",
"Namespaces": {
"Containers": "moby",
"Plugins": "plugins.moby"
}
}
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.54/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "27.0.1",
"Details": { }
}
],
"Version": "27.0.1",
"ApiVersion": "1.47",
"MinAPIVersion": "1.24",
"GitCommit": "48a66213fe",
"GoVersion": "go1.22.7",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "6.8.0-31-generic",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.54/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.54/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.54/events

### Response samples

* 200
* 400
* 500

Content type

application/jsonl

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|         |                                                                                                                           |
| ------- | ------------------------------------------------------------------------------------------------------------------------- |
| type    | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |
| verbose | booleanDefault: falseShow detailed information on space usage.                                                            |

### Responses

/v1.54/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"ImageUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
},
"ContainerUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
},
"VolumeUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
},
"BuildCacheUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
}
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.54/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

> **Deprecated**: This endpoint is deprecated and will be removed in a future version. Server should support gRPC directly on the listening socket.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.54/session

----
url: https://docs.docker.com/engine/network/firewall-iptables/
----

# Docker with iptables

***

Table of contents

***

Docker creates iptables rules in the host's network namespace for bridge networks. For bridge and other network types, iptables rules for DNS are also created in the container's network namespace.

Creation of iptables rules can be disabled using daemon options `iptables` and `ip6tables`, see [Prevent Docker from manipulating firewall rules](https://docs.docker.com/engine/network/packet-filtering-firewalls/#prevent-docker-from-manipulating-firewall-rules). However, this is not recommended for most users as it will likely break container networking.

### [Docker and iptables chains](#docker-and-iptables-chains)

To support bridge and overlay networks, Docker creates the following custom `iptables` chains in the `filter` table:

* `DOCKER-USER`
  * A placeholder for user-defined rules that will be processed before rules in the `DOCKER-FORWARD` and `DOCKER` chains.
* `DOCKER-FORWARD`
  * The first stage of processing for Docker's networks. Rules that pass packets that are not related to established connections to the other Docker chains, as well as rules to accept packets that are part of established connections.
* `DOCKER`, `DOCKER-BRIDGE`, `DOCKER-INTERNAL`
  * Rules that determine whether a packet that is not part of an established connection should be accepted, based on the port forwarding configuration of running containers.
* `DOCKER-CT`
  * Per-bridge connection tracking rules.
* `DOCKER-INGRESS`
  * Rules related to Swarm networking.

In the `FORWARD` chain, Docker adds rules that unconditionally jump to the `DOCKER-USER`, `DOCKER-FORWARD` and `DOCKER-INGRESS` chains.

In the `nat` table, Docker creates chain `DOCKER` and adds rules to implement masquerading and port-mapping.

Docker requires IP Forwarding to be enabled on the host for its default bridge network configuration. If it enables IP Forwarding, it also sets the default policy of the iptables `FORWARD` chain in the `filter` table to `DROP`.

### [Add iptables policies before Docker's rules](#add-iptables-policies-before-dockers-rules)

Packets that get accepted or rejected by rules in these custom chains will not be seen by user-defined rules appended to the `FORWARD` chain. So, to add additional rules to filter these packets, use the `DOCKER-USER` chain.

Rules appended to the `FORWARD` chain will be processed after Docker's rules.

### [Match the original IP and ports for requests](#match-the-original-ip-and-ports-for-requests)

When packets arrive to the `DOCKER-USER` chain, they have already passed through a Destination Network Address Translation (DNAT) filter. That means that the `iptables` flags you use can only match internal IP addresses and ports of containers.

If you want to match traffic based on the original IP and port in the network request, you must use the [`conntrack` iptables extension](https://ipset.netfilter.org/iptables-extensions.man.html#lbAO). For example:

```console
$ sudo iptables -I DOCKER-USER -p tcp -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
$ sudo iptables -I DOCKER-USER -p tcp -m conntrack --ctorigdst 198.51.100.2 --ctorigdstport 80 -j ACCEPT
```

> Important
>
> Using the `conntrack` extension may result in degraded performance.

### [Allow forwarding between host interfaces](#allow-forwarding-between-host-interfaces)

If Docker has set the default policy of the `FORWARD` chain in the `filter` table to `DROP`, a rule in `DOCKER-USER` can be used to allow forwarding between host interfaces. For example:

```console
$ iptables -I DOCKER-USER -i src_if -o dst_if -j ACCEPT
```

### [Restrict external connections to containers](#restrict-external-connections-to-containers)

By default, all external source IPs are allowed to connect to ports that have been published to the Docker host's addresses.

To allow only a specific IP or network to access the containers, insert a negated rule at the top of the `DOCKER-USER` filter chain. For example, the following rule drops packets from all IP addresses except `192.0.2.2`:

```console
$ iptables -I DOCKER-USER -i ext_if ! -s 192.0.2.2 -j DROP
```

You will need to change `ext_if` to correspond with your host's actual external interface. You could instead allow connections from a source subnet. The following rule only allows access from the subnet `192.0.2.0/24`:

```console
$ iptables -I DOCKER-USER -i ext_if ! -s 192.0.2.0/24 -j DROP
```

Finally, you can specify a range of IP addresses to accept using `--src-range` (Remember to also add `-m iprange` when using `--src-range` or `--dst-range`):

```console
$ iptables -I DOCKER-USER -m iprange -i ext_if ! --src-range 192.0.2.1-192.0.2.3 -j DROP
```

You can combine `-s` or `--src-range` with `-d` or `--dst-range` to control both the source and destination. For example, if the Docker host has addresses `2001:db8:1111::2` and `2001:db8:2222::2`, you can make rules specific to `2001:db8:1111::2` and leave `2001:db8:2222::2` open.

You may need to allow responses from servers outside the permitted external address ranges. For example, containers may send DNS or HTTP requests to hosts that are not allowed to access the container's services. The following rule accepts any incoming or outgoing packet belonging to a flow that has already been accepted by other rules. It must be placed before `DROP` rules that restrict access from external address ranges.

```console
$ iptables -I DOCKER-USER -m state --state RELATED,ESTABLISHED -j ACCEPT
```

For more information about iptables configuration and advanced usage, refer to the [Netfilter.org HOWTO](https://www.netfilter.org/documentation/HOWTO/NAT-HOWTO.html).

----
url: https://docs.docker.com/build/ci/github-actions/manage-tags-labels/
----

# Manage tags and labels with GitHub Actions

***

***

If you want an "automatic" tag management and [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md) for labels, you can do it in a dedicated setup step. The following workflow will use the [Docker Metadata Action](https://github.com/docker/metadata-action) to handle tags and labels based on GitHub Actions events and Git metadata:

```yaml
name: ci

on:
  schedule:
    - cron: "0 10 * * *"
  push:
    branches:
      - "**"
    tags:
      - "v*.*.*"
  pull_request:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v6
        with:
          # list of Docker images to use as base name for tags
          images: |
            name/app
            ghcr.io/username/app
          # generate Docker tags based on the following events/attributes
          tags: |
            type=schedule
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=semver,pattern={{major}}
            type=sha

      - name: Login to Docker Hub
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Login to GHCR
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
```

----
url: https://docs.docker.com/reference/cli/docker/scout/vex/get/
----

# docker scout vex get

***

| Description | Get VEX attestation for image        |
| ----------- | ------------------------------------ |
| Usage       | `docker scout vex get OPTIONS IMAGE` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

The docker scout vex get command gets a VEX attestation for images.

## [Options](#options)

| Option         | Default                                                    | Description                                                                                          |
| -------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--key`        | `https://registry.scout.docker.com/keyring/dhi/latest.pub` | Signature key to use for verification                                                                |
| `--org`        |                                                            | Namespace of the Docker organization                                                                 |
| `-o, --output` |                                                            | Write the report to a file                                                                           |
| `--platform`   |                                                            | Platform of image to analyze                                                                         |
| `--ref`        |                                                            | Reference to use if the provided tarball contains multiple references. Can only be used with archive |
| `--skip-tlog`  |                                                            | Skip signature verification against public transaction log                                           |
| `--verify`     |                                                            | Verify the signature on the attestation                                                              |

----
url: https://docs.docker.com/admin/organization/setup/general-settings/
----

# Change general organization information

***

Table of contents

***

Learn how to update your organization information using the Admin Console.

## [Update organization information](#update-organization-information)

General organization information appears on your organization landing page in the Admin Console.

This information includes:

* Organization Name
* Company
* Location
* Website
* Gravatar email: To add an avatar to your Docker account, create a [Gravatar account](https://gravatar.com/) and upload an avatar. Next, add your Gravatar email to your Docker account settings. It may take some time for your avatar to update in Docker.

To edit this information:

1. Sign in to the [Admin Console](https://app.docker.com/admin) and select your organization from the top-left account drop-down.
2. Enter or update your organization’s details, then select **Save**.

## [Next steps](#next-steps)

After configuring your organization information, you can:

* [Configure single sign-on (SSO)](https://docs.docker.com/enterprise/security/single-sign-on/connect/)
* [Set up SCIM provisioning](https://docs.docker.com/enterprise/security/provisioning/scim/)
* [Manage domains](https://docs.docker.com/enterprise/security/domain-management/)
* [Create a company](https://docs.docker.com/admin/company/new-company/)

----
url: https://docs.docker.com/guides/java/configure-ci-cd/
----

# Configure CI/CD for your Java application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete the previous sections of this guide, starting with [Containerize your app](https://docs.docker.com/guides/java/containerize/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

   ```console
   $ git remote set-url origin https://github.com/your-username/your-repository.git
   ```

7. Run the following commands to stage, commit, and push your local repository to GitHub.

   ```console
   $ git add -A
   $ git commit -m "my commit"
   $ git push -u origin main
   ```

## [Step two: Set up the workflow](#step-two-set-up-the-workflow)

Set up your GitHub Actions workflow for building, testing, and pushing the image to Docker Hub.

1. Go to your repository on GitHub and then select the **Actions** tab. The project already has the `maven-build` workflow to build and test your Java application with Maven. If you want, you can optionally disable this workflow because you won't use it in this guide. You'll create a new, alternate workflow to build, test, and push your image.

2. Select **New workflow**.

3. Select **set up a workflow yourself**.

   This takes you to a page for creating a new GitHub actions workflow file in your repository, under `.github/workflows/main.yml` by default.

4. In the editor window, copy and paste the following YAML configuration.

   ```yaml
   name: ci

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Login to Docker Hub
           uses: docker/login-action@v4
           with:
             username: ${{ vars.DOCKER_USERNAME }}
             password: ${{ secrets.DOCKERHUB_TOKEN }}

         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v4

         - name: Build and test
           uses: docker/build-push-action@v7
           with:
             target: test
             load: true

         - name: Build and push
           uses: docker/build-push-action@v7
           with:
             platforms: linux/amd64,linux/arm64
             push: true
             target: final
             tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
   ```

[Test your Java deployment »](https://docs.docker.com/guides/java/deploy/)

----
url: https://docs.docker.com/engine/network/ca-certs/
----

# Use CA certificates with Docker

***

Table of contents

***

> Caution
>
> Best practices should be followed when using Man-in-the-Middle (MITM) CA certificates in production containers. If compromised, attackers could intercept sensitive data, spoof a trusted service, or perform man-in-the-middle attacks. Consult your security team before you proceed.

If your company uses a proxy that inspects HTTPS traffic, you might need to add the required root certificates to your host machine and your Docker containers or images. This is because Docker and its containers, when pulling images or making network requests, need to trust the proxy’s certificates.

On the host, adding the root certificate ensures that any Docker commands (like `docker pull`) work without issues. For containers, you'll need to add the root certificate to the container's trust store either during the build process or at runtime. This ensures that applications running inside the containers can communicate through the proxy without encountering security warnings or connection failures.

## [Add CA certificate to the host](#add-ca-certificate-to-the-host)

The following sections describe how to install CA certificates on your macOS or Windows host. For Linux, refer to the documentation for your distribution.

### [macOS](#macos)

1. Download the CA certificate for your MITM proxy software.
2. Open the **Keychain Access** app.
3. In Keychain Access, select **System**, then switch to the **Certificates** tab.
4. Drag-and-drop the downloaded certificate into the list of certificates. Enter your password if prompted.
5. Find the newly added certificate, double-click it, and expand the **Trust** section.
6. Set **Always Trust** for the certificate. Enter your password if prompted.
7. Start Docker Desktop and verify that `docker pull` works, assuming Docker Desktop is configured to use the MITM proxy.

### [Windows](#windows)

Choose whether you want to install the certificate using the Microsoft Management Console (MMC) or your web browser.

1. Download CA certificate for the MITM proxy software.

2. Open the Microsoft Management Console (`mmc.exe`).

3. Add the **Certificates Snap-In** in the MMC.

   1. Select **File** → **Add/Remove Snap-in**, and then select **Certificates** → **Add >**.
   2. Select **Computer Account** and then **Next**.
   3. Select **Local computer** and then select **Finish**.

4. Import the CA certificate:

   1. From the MMC, expand **Certificates (Local Computer)**.
   2. Expand the **Trusted Root Certification Authorities** section.
   3. Right-click **Certificates** and select **All Tasks** and **Import…**.
   4. Follow the prompts to import your CA certificate.

5. Select **Finish** and then **Close**.

6. Start Docker Desktop and verify that `docker pull` succeeds (assuming Docker Desktop is already configured to use the MITM proxy server).

> Note
>
> Depending on the SDK and/or runtime/framework in use, further steps may be required beyond adding the CA certificate to the operating system's trust store.

1. Download the CA certificate for your MITM proxy software.
2. Open your web browser, go to **Settings** and open **Manage certificates**
3. Select the **Trusted Root Certification Authorities** tab.
4. Select **Import**, then browse for the downloaded CA certificate.
5. Select **Open**, then choose **Place all certificates in the following store**.
6. Ensure **Trusted Root Certification Authorities** is selected and select **Next**.
7. Select **Finish** and then **Close**.
8. Start Docker Desktop and verify that `docker pull` succeeds (assuming Docker Desktop is already configured to use the MITM proxy server).

## [Add CA certificates to Linux images and containers](#add-ca-certificates-to-linux-images-and-containers)

If you need to run containerized workloads that rely on internal or custom certificates, such as in environments with corporate proxies or secure services, you must ensure that the containers trust these certificates. Without adding the necessary CA certificates, applications inside your containers may encounter failed requests or security warnings when attempting to connect to HTTPS endpoints.

By [adding CA certificates to images](#add-certificates-to-images) at build time, you ensure that any containers started from the image will trust the specified certificates. This is particularly important for applications that require seamless access to internal APIs, databases, or other services during production.

In cases where rebuilding the image isn't feasible, you can instead [add certificates to containers](#add-certificates-to-containers) directly. However, certificates added at runtime won’t persist if the container is destroyed or recreated, so this method is typically used for temporary fixes or testing scenarios.

## [Add certificates to images](#add-certificates-to-images)

> Note
>
> The following commands are for an Ubuntu base image. If your build uses a different Linux distribution, use equivalent commands for package management (`apt-get`, `update-ca-certificates`, and so on).

To add ca certificate to a container image when you're building it, add the following instructions to your Dockerfile.

```dockerfile
# Install the ca-certificate package
RUN apt-get update && apt-get install -y ca-certificates
# Copy the CA certificate from the context to the build container
COPY your_certificate.crt /usr/local/share/ca-certificates/
# Update the CA certificates in the container
RUN update-ca-certificates
```

### [Add certificates to containers](#add-certificates-to-containers)

> Note
>
> The following commands are for an Ubuntu-based container. If your container uses a different Linux distribution, use equivalent commands for package management (`apt-get`, `update-ca-certificates`, and so on).

To add a CA certificate to a running Linux container:

1. Download the CA certificate for your MITM proxy software.

2. If the certificate is in a format other than `.crt`, convert it to `.crt` format:

   Example command

   ```console
   $ openssl x509 -in cacert.der -inform DER -out myca.crt
   ```

3. Copy the certificate into the running container:

   ```console
   $ docker cp myca.crt <containerid>:/tmp
   ```

4. Attach to the container:

   ```console
   $ docker exec -it <containerid> sh
   ```

5. Ensure the `ca-certificates` package is installed (required for updating certificates):

   ```console
   # apt-get update && apt-get install -y ca-certificates
   ```

6. Copy the certificate to the correct location for CA certificates:

   ```console
   # cp /tmp/myca.crt /usr/local/share/ca-certificates/root_cert.crt
   ```

7. Update the CA certificates:

   ```console
   # update-ca-certificates
   ```

   Example output

   ```plaintext
   Updating certificates in /etc/ssl/certs...
   rehash: warning: skipping ca-certificates.crt, it does not contain exactly one certificate or CRL
   1 added, 0 removed; done.
   ```

8. Verify that the container can communicate via the MITM proxy:

   ```console
   # curl https://example.com
   ```

   Example output

   ```plaintext
   <!doctype html>
   <html>
   <head>
       <title>Example Domain</title>
   ...
   ```

----
url: https://docs.docker.com/engine/release-notes/18.03/
----

# Docker Engine 18.03 release notes

***

Table of contents

***

## [18.03.1-ce](#18031-ce)

2018-04-26

### [Client](#client)

* Fix error with merge compose file with networks [docker/cli#983](https://github.com/docker/cli/pull/983)

- Fix docker stack deploy re-deploying services after the service was updated with `--force` [docker/cli#963](https://github.com/docker/cli/pull/963)
- Fix docker version output alignment [docker/cli#965](https://github.com/docker/cli/pull/965)

### [Runtime](#runtime)

* Fix AppArmor profiles not being applied to `docker exec` processes [moby/moby#36466](https://github.com/moby/moby/pull/36466)
* Don't sort plugin mount slice [moby/moby#36711](https://github.com/moby/moby/pull/36711)
* Daemon/cluster: handle partial attachment entries during configure [moby/moby#36769](https://github.com/moby/moby/pull/36769)

- Bump Golang to 1.9.5 [moby/moby#36779](https://github.com/moby/moby/pull/36779) [docker/cli#986](https://github.com/docker/cli/pull/986)

* Daemon/stats: more resilient cpu sampling [moby/moby#36519](https://github.com/moby/moby/pull/36519)

- Containerd: update to 1.0.3 release [moby/moby#36749](https://github.com/moby/moby/pull/36749)

* Fix Windows layer leak when write fails [moby/moby#36728](https://github.com/moby/moby/pull/36728)

- Don't make container mount unbindable [moby/moby#36768](https://github.com/moby/moby/pull/36768)

* Fix Daemon panics on container export after a daemon restart [moby/moby/36586](https://github.com/moby/moby/pull/36586)
* Fix digest cache being removed on autherrors [moby/moby#36509](https://github.com/moby/moby/pull/36509)
* Make sure plugin container is removed on failure [moby/moby#36715](https://github.com/moby/moby/pull/36715)
* Copy: avoid using all system memory with authz plugins [moby/moby#36595](https://github.com/moby/moby/pull/36595)
* Relax some libcontainerd client locking [moby/moby#36848](https://github.com/moby/moby/pull/36848)
* Update `hcsshim` to v0.6.10 to address [CVE-2018-8115](https://portal.msrc.microsoft.com/en-us/security-guidance/advisory/CVE-2018-8115)

### [Swarm Mode](#swarm-mode)

* Increase raft Election tick to 10 times Heartbeat tick [moby/moby#36672](https://github.com/moby/moby/pull/36672)

### [Networking](#networking)

* Gracefully remove LB endpoints from services [docker/libnetwork#2112](https://github.com/docker/libnetwork/pull/2112)
* Retry other external DNS servers on ServFail [docker/libnetwork#2121](https://github.com/docker/libnetwork/pull/2121)
* Improve scalability of bridge network isolation rules [docker/libnetwork#2117](https://github.com/docker/libnetwork/pull/2117)
* Allow for larger preset property values, do not override [docker/libnetwork#2124](https://github.com/docker/libnetwork/pull/2124)
* Prevent panics on concurrent reads/writes when calling `changeNodeState` [docker/libnetwork#2136](https://github.com/docker/libnetwork/pull/2136)

## [18.03.0-ce](#18030-ce)

2018-03-21

### [Builder](#builder)

* Switch to -buildmode=pie [moby/moby#34369](https://github.com/moby/moby/pull/34369)
* Allow Dockerfile to be outside of build-context [docker/cli#886](https://github.com/docker/cli/pull/886)
* Builder: fix wrong cache hits building from tars [moby/moby#36329](https://github.com/moby/moby/pull/36329)

- Fixes files leaking to other images in a multi-stage build [moby/moby#36338](https://github.com/moby/moby/pull/36338)

### [Client](#client-1)

* Simplify the marshaling of compose types.Config [docker/cli#895](https://github.com/docker/cli/pull/895)

- Add support for multiple composefile when deploying [docker/cli#569](https://github.com/docker/cli/pull/569)

* Fix broken Kubernetes stack flags [docker/cli#831](https://github.com/docker/cli/pull/831)
* Fix stack marshaling for Kubernetes [docker/cli#890](https://github.com/docker/cli/pull/890)
* Fix and simplify bash completion for service env, mounts and labels [docker/cli#682](https://github.com/docker/cli/pull/682)
* Fix `before` and `since` filter for `docker ps` [moby/moby#35938](https://github.com/moby/moby/pull/35938)
* Fix `--label-file` weird behavior [docker/cli#838](https://github.com/docker/cli/pull/838)
* Fix compilation of defaultCredentialStore() on unsupported platforms [docker/cli#872](https://github.com/docker/cli/pull/872)

- Improve and fix bash completion for images [docker/cli#717](https://github.com/docker/cli/pull/717)

* Added check for empty source in bind mount [docker/cli#824](https://github.com/docker/cli/pull/824)

- Fix TLS from environment variables in client [moby/moby#36270](https://github.com/moby/moby/pull/36270)

* docker build now runs faster when registry-specific credential helper(s) are configured [docker/cli#840](https://github.com/docker/cli/pull/840)
* Update event filter zsh completion with `disable`, `enable`, `install` and `remove` [docker/cli#372](https://github.com/docker/cli/pull/372)
* Produce errors when empty ids are passed into inspect calls [moby/moby#36144](https://github.com/moby/moby/pull/36144)
* Marshall version for the k8s controller [docker/cli#891](https://github.com/docker/cli/pull/891)
* Set a non-zero timeout for HTTP client communication with plugin backend [docker/cli#883](https://github.com/docker/cli/pull/883)

- Add DOCKER\_TLS environment variable for --tls option [docker/cli#863](https://github.com/docker/cli/pull/863)
- Add --template-driver option for secrets/configs [docker/cli#896](https://github.com/docker/cli/pull/896)
- Move `docker trust` commands out of experimental [docker/cli#934](https://github.com/docker/cli/pull/934) [docker/cli#935](https://github.com/docker/cli/pull/935) [docker/cli#944](https://github.com/docker/cli/pull/944)

### [Logging](#logging)

* AWS logs - don't add new lines to maximum sized events [moby/moby#36078](https://github.com/moby/moby/pull/36078)
* Move log validator logic after plugins are loaded [moby/moby#36306](https://github.com/moby/moby/pull/36306)
* Support a proxy in Splunk log driver [moby/moby#36220](https://github.com/moby/moby/pull/36220)

- Fix log tail with empty logs [moby/moby#36305](https://github.com/moby/moby/pull/36305)

### [Networking](#networking-1)

* Libnetwork revendoring [moby/moby#36137](https://github.com/moby/moby/pull/36137)

- Fix for deadlock on exit with Memberlist revendor [docker/libnetwork#2040](https://github.com/docker/libnetwork/pull/2040)

* Fix user specified ndots option [docker/libnetwork#2065](https://github.com/docker/libnetwork/pull/2065)

- Fix to use ContainerID for Windows instead of SandboxID [docker/libnetwork#2010](https://github.com/docker/libnetwork/pull/2010)

* Verify NetworkingConfig to make sure EndpointSettings is not nil [moby/moby#36077](https://github.com/moby/moby/pull/36077)

- Fix `DockerNetworkInternalMode` issue [moby/moby#36298](https://github.com/moby/moby/pull/36298)
- Fix race in attachable network attachment [moby/moby#36191](https://github.com/moby/moby/pull/36191)
- Fix timeout issue of `InspectNetwork` on AArch64 [moby/moby#36257](https://github.com/moby/moby/pull/36257)

* Verbose info is missing for partial overlay ID [moby/moby#35989](https://github.com/moby/moby/pull/35989)
* Update `FindNetwork` to address network name duplications [moby/moby#30897](https://github.com/moby/moby/pull/30897)
* Disallow attaching ingress network [docker/swarmkit#2523](https://github.com/docker/swarmkit/pull/2523)

- Prevent implicit removal of the ingress network [moby/moby#36538](https://github.com/moby/moby/pull/36538)
- Fix stale HNS endpoints on Windows [moby/moby#36603](https://github.com/moby/moby/pull/36603)
- IPAM fixes for duplicate IP addresses [docker/libnetwork#2104](https://github.com/docker/libnetwork/pull/2104) [docker/libnetwork#2105](https://github.com/docker/libnetwork/pull/2105)

### [Runtime](#runtime-1)

* Enable HotAdd for Windows [moby/moby#35414](https://github.com/moby/moby/pull/35414)
* LCOW: Graphdriver fix deadlock in hotRemoveVHDs [moby/moby#36114](https://github.com/moby/moby/pull/36114)
* LCOW: Regular mount if only one layer [moby/moby#36052](https://github.com/moby/moby/pull/36052)
* Remove interim env var LCOW\_API\_PLATFORM\_IF\_OMITTED [moby/moby#36269](https://github.com/moby/moby/pull/36269)
* Revendor Microsoft/opengcs @ v0.3.6 [moby/moby#36108](https://github.com/moby/moby/pull/36108)

- Fix issue of ExitCode and PID not show up in Task.Status.ContainerStatus [moby/moby#36150](https://github.com/moby/moby/pull/36150)
- Fix issue with plugin scanner going too deep [moby/moby#36119](https://github.com/moby/moby/pull/36119)

* Do not make graphdriver homes private mounts [moby/moby#36047](https://github.com/moby/moby/pull/36047)
* Do not recursive unmount on cleanup of zfs/btrfs [moby/moby#36237](https://github.com/moby/moby/pull/36237)
* Don't restore image if layer does not exist [moby/moby#36304](https://github.com/moby/moby/pull/36304)
* Adjust minimum API version for templated configs/secrets [moby/moby#36366](https://github.com/moby/moby/pull/36366)
* Bump containerd to 1.0.2 (cfd04396dc68220d1cecbe686a6cc3aa5ce3667c) [moby/moby#36308](https://github.com/moby/moby/pull/36308)
* Bump Golang to 1.9.4 [moby/moby#36243](https://github.com/moby/moby/pull/36243)
* Ensure daemon root is unmounted on shutdown [moby/moby#36107](https://github.com/moby/moby/pull/36107)
* Update runc to 6c55f98695e902427906eed2c799e566e3d3dfb5 [moby/moby#36222](https://github.com/moby/moby/pull/36222)

- Fix container cleanup on daemon restart [moby/moby#36249](https://github.com/moby/moby/pull/36249)

* Support SCTP port mapping (bump up API to v1.37) [moby/moby#33922](https://github.com/moby/moby/pull/33922)
* Support SCTP port mapping [docker/cli#278](https://github.com/docker/cli/pull/278)

- Fix Volumes property definition in ContainerConfig [moby/moby#35946](https://github.com/moby/moby/pull/35946)

* Bump moby and dependencies [docker/cli#829](https://github.com/docker/cli/pull/829)
* C.RWLayer: check for nil before use [moby/moby#36242](https://github.com/moby/moby/pull/36242)

- Add `REMOVE` and `ORPHANED` to TaskState [moby/moby#36146](https://github.com/moby/moby/pull/36146)

* Fixed error detection using `IsErrNotFound` and `IsErrNotImplemented` for `ContainerStatPath`, `CopyFromContainer`, and `CopyToContainer` methods [moby/moby#35979](https://github.com/moby/moby/pull/35979)

- Add an integration/internal/container helper package [moby/moby#36266](https://github.com/moby/moby/pull/36266)
- Add canonical import path [moby/moby#36194](https://github.com/moby/moby/pull/36194)
- Add/use container.Exec() to integration [moby/moby#36326](https://github.com/moby/moby/pull/36326)

* Fix "--node-generic-resource" singular/plural [moby/moby#36125](https://github.com/moby/moby/pull/36125)

- Daemon.cleanupContainer: nullify container RWLayer upon release [moby/moby#36160](https://github.com/moby/moby/pull/36160)
- Daemon: passdown the `--oom-kill-disable` option to containerd [moby/moby#36201](https://github.com/moby/moby/pull/36201)
- Display a warn message when there is binding ports and net mode is host [moby/moby#35510](https://github.com/moby/moby/pull/35510)
- Refresh containerd remotes on containerd restarted [moby/moby#36173](https://github.com/moby/moby/pull/36173)
- Set daemon root to use shared propagation [moby/moby#36096](https://github.com/moby/moby/pull/36096)
- Optimizations for recursive unmount [moby/moby#34379](https://github.com/moby/moby/pull/34379)
- Perform plugin mounts in the runtime [moby/moby#35829](https://github.com/moby/moby/pull/35829)
- Graphdriver: Fix RefCounter memory leak [moby/moby#36256](https://github.com/moby/moby/pull/36256)
- Use continuity fs package for volume copy [moby/moby#36290](https://github.com/moby/moby/pull/36290)
- Use proc/exe for reexec [moby/moby#36124](https://github.com/moby/moby/pull/36124)

* Add API support for templated secrets and configs [moby/moby#33702](https://github.com/moby/moby/pull/33702) and [moby/moby#36366](https://github.com/moby/moby/pull/36366)

- Use rslave propagation for mounts from daemon root [moby/moby#36055](https://github.com/moby/moby/pull/36055)

* Add /proc/keys to masked paths [moby/moby#36368](https://github.com/moby/moby/pull/36368)

- Bump Runc to 1.0.0-rc5 [moby/moby#36449](https://github.com/moby/moby/pull/36449)

* Fixes `runc exec` on big-endian architectures [moby/moby#36449](https://github.com/moby/moby/pull/36449)

- Use chroot when mount namespaces aren't provided [moby/moby#36449](https://github.com/moby/moby/pull/36449)

* Fix systemd slice expansion so that it could be consumed by cAdvisor [moby/moby#36449](https://github.com/moby/moby/pull/36449)
* Fix devices mounted with wrong uid/gid [moby/moby#36449](https://github.com/moby/moby/pull/36449)
* Fix read-only containers with IPC private mounts `/dev/shm` read-only [moby/moby#36526](https://github.com/moby/moby/pull/36526)

### [Swarm Mode](#swarm-mode-1)

* Replace EC Private Key with PKCS#8 PEMs [docker/swarmkit#2246](https://github.com/docker/swarmkit/pull/2246)
* Fix IP overlap with empty EndpointSpec [docker/swarmkit #2505](https://github.com/docker/swarmkit/pull/2505)
* Add support for Support SCTP port mapping [docker/swarmkit#2298](https://github.com/docker/swarmkit/pull/2298)
* Do not reschedule tasks if only placement constraints change and are satisfied by the assigned node [docker/swarmkit#2496](https://github.com/docker/swarmkit/pull/2496)
* Ensure task reaper stopChan is closed no more than once [docker/swarmkit #2491](https://github.com/docker/swarmkit/pull/2491)
* Synchronization fixes [docker/swarmkit#2495](https://github.com/docker/swarmkit/pull/2495)
* Add log message to indicate message send retry if streaming unimplemented [docker/swarmkit#2483](https://github.com/docker/swarmkit/pull/2483)
* Debug logs for session, node events on dispatcher, heartbeats [docker/swarmkit#2486](https://github.com/docker/swarmkit/pull/2486)

- Add swarm types to bash completion event type filter [docker/cli#888](https://github.com/docker/cli/pull/888)

* Fix issue where network inspect does not show Created time for networks in swarm scope [moby/moby#36095](https://github.com/moby/moby/pull/36095)

----
url: https://docs.docker.com/reference/cli/docker/sandbox/ls/
----

# docker sandbox ls

***

| Description                                                               | List VMs                      |
| ------------------------------------------------------------------------- | ----------------------------- |
| Usage                                                                     | `docker sandbox ls [OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker sandbox list`         |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

List all VMs managed by sandboxd with their sandboxes

## [Options](#options)

| Option                  | Default | Description           |
| ----------------------- | ------- | --------------------- |
| `--json`                |         | Output in JSON format |
| [`-q, --quiet`](#quiet) |         | Only display VM names |

## [Examples](#examples)

### [List all VMs](#list-all-vms)

```console
$ docker sandbox ls
VM ID         NAME       STATUS    WORKSPACE                    SOCKET PATH                           SANDBOXES    AGENTS
abc123def     claude-vm  running   /home/user/my-project        /Users/.../docker-1764682554072.sock  2           claude
def456ghi     gemini-vm  stopped   /home/user/ml-projects
```

### [Show only VM names (--quiet)](#quiet)

```text
--quiet
```

Output only VM names:

```console
$ docker sandbox ls --quiet
claude-vm
gemini-vm
```

### [JSON output (--json)](#json-output---json)

```text
--json
```

Output detailed VM information in JSON format:

```console
$ docker sandbox ls --json
{
  "vms": [
    {
      "name": "claude-vm",
      "agent": "claude",
      "status": "running",
      "socket_path": "/Users/user/.docker/sandboxes/vm/claude-vm/docker-1234567890.sock",
      "sandbox_count": 2,
      "workspaces": [
        "/home/user/my-project",
        "/home/user/another-project"
      ]
    },
    {
      "name": "gemini-vm",
      "agent": "gemini",
      "status": "stopped",
      "sandbox_count": 0
    }
  ]
}
```

----
url: https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/
----

# How services work

***

Table of contents

***

To deploy an application image when Docker Engine is in Swarm mode, you create a service. Frequently a service is the image for a microservice within the context of some larger application. Examples of services might include an HTTP server, a database, or any other type of executable program that you wish to run in a distributed environment.

When you create a service, you specify which container image to use and which commands to execute inside running containers. You also define options for the service including:

* The port where the swarm makes the service available outside the swarm
* An overlay network for the service to connect to other services in the swarm
* CPU and memory limits and reservations
* A rolling update policy
* The number of replicas of the image to run in the swarm

## [Services, tasks, and containers](#services-tasks-and-containers)

When you deploy the service to the swarm, the swarm manager accepts your service definition as the desired state for the service. Then it schedules the service on nodes in the swarm as one or more replica tasks. The tasks run independently of each other on nodes in the swarm.

For example, imagine you want to load balance between three instances of an HTTP listener. The diagram below shows an HTTP listener service with three replicas. Each of the three instances of the listener is a task in the swarm.

A container is an isolated process. In the Swarm mode model, each task invokes exactly one container. A task is analogous to a “slot” where the scheduler places a container. Once the container is live, the scheduler recognizes that the task is in a running state. If the container fails health checks or terminates, the task terminates.

## [Tasks and scheduling](#tasks-and-scheduling)

A task is the atomic unit of scheduling within a swarm. When you declare a desired service state by creating or updating a service, the orchestrator realizes the desired state by scheduling tasks. For instance, you define a service that instructs the orchestrator to keep three instances of an HTTP listener running at all times. The orchestrator responds by creating three tasks. Each task is a slot that the scheduler fills by spawning a container. The container is the instantiation of the task. If an HTTP listener task subsequently fails its health check or crashes, the orchestrator creates a new replica task that spawns a new container.

A task is a one-directional mechanism. It progresses monotonically through a series of states: `ASSIGNED`, `PREPARING`, `RUNNING`, etc. If the task fails, the orchestrator removes the task and its container and then creates a new task to replace it according to the desired state specified by the service.

The underlying logic of Docker's Swarm mode is a general purpose scheduler and orchestrator. The service and task abstractions themselves are unaware of the containers they implement. Hypothetically, you could implement other types of tasks such as virtual machine tasks or non-containerized process tasks. The scheduler and orchestrator are agnostic about the type of the task. However, Docker only supports container tasks.

The diagram below shows how Swarm mode accepts service create requests and schedules tasks to worker nodes.

### [Pending services](#pending-services)

A service may be configured in such a way that no node currently in the swarm can run its tasks. In this case, the service remains in state `pending`. Here are a few examples of when a service might remain in state `pending`.

> Tip
>
> If your only intention is to prevent a service from being deployed, scale the service to 0 instead of trying to configure it in such a way that it remains in `pending`.

* If all nodes are paused or drained, and you create a service, it is pending until a node becomes available. In reality, the first node to become available gets all of the tasks, so this is not a good thing to do in a production environment.

* You can reserve a specific amount of memory for a service. If no node in the swarm has the required amount of memory, the service remains in a pending state until a node is available which can run its tasks. If you specify a very large value, such as 500 GB, the task stays pending forever, unless you really have a node which can satisfy it.

* You can impose placement constraints on the service, and the constraints may not be able to be honored at a given time.

This behavior illustrates that the requirements and configuration of your tasks are not tightly tied to the current state of the swarm. As the administrator of a swarm, you declare the desired state of your swarm, and the manager works with the nodes in the swarm to create that state. You do not need to micro-manage the tasks on the swarm.

## [Replicated and global services](#replicated-and-global-services)

There are two types of service deployments, replicated and global.

For a replicated service, you specify the number of identical tasks you want to run. For example, you decide to deploy an HTTP service with three replicas, each serving the same content.

A global service is a service that runs one task on every node. There is no pre-specified number of tasks. Each time you add a node to the swarm, the orchestrator creates a task and the scheduler assigns the task to the new node. Good candidates for global services are monitoring agents, anti-virus scanners or other types of containers that you want to run on every node in the swarm.

The diagram below shows a three-service replica in gray and a global service in black.

## [Learn more](#learn-more)

* Read about how Swarm mode [nodes](https://docs.docker.com/engine/swarm/how-swarm-mode-works/nodes/) work.

----
url: https://docs.docker.com/extensions/extensions-sdk/extensions/validate/
----

# Validate your extension

***

***

Validate your extension before you share or publish it. Validating the extension ensures that the extension:

* Is built with the [image labels](https://docs.docker.com/extensions/extensions-sdk/extensions/labels/) it requires to display correctly in the marketplace
* Installs and runs without problems

The Extensions CLI lets you validate your extension before installing and running it locally.

The validation checks if the extension’s `Dockerfile` specifies all the required labels and if the metadata file is valid against the JSON schema file.

To validate, run:

```console
$ docker extension validate <name-of-your-extension>
```

If your extension is valid, the following message displays:

```console
The extension image "name-of-your-extension" is valid
```

Before the image is built, it's also possible to validate only the `metadata.json` file:

```console
$ docker extension validate /path/to/metadata.json
```

The JSON schema used to validate the `metadata.json` file against can be found under the [releases page](https://github.com/docker/extensions-sdk/releases/latest).

----
url: https://docs.docker.com/dhi/how-to/
----

# How-tos

***

Table of contents

***

This section provides practical, task-based guidance for working with Docker Hardened Images (DHIs). Whether you're evaluating DHIs for the first time or integrating them into a production CI/CD pipeline, these topics cover the key tasks across the adoption journey: discover, adopt, verify, and govern.

The topics are organized around the typical lifecycle of working with DHIs, but you can use them as needed based on your specific workflow.

Explore the topics below that match your current needs.

## [Discover](#discover)

Explore available images and metadata in the DHI catalog.

### [Search and evaluate Docker Hardened Images](/dhi/how-to/explore/)

[Learn how to find and evaluate image repositories, variants, metadata, and attestations in the DHI catalog on Docker Hub.](/dhi/how-to/explore/)

## [Adopt](#adopt)

Mirror trusted images, customize as needed, and integrate into your workflows.

### [Get started with DHI Select and Enterprise](/dhi/how-to/select-enterprise/)

[Learn how to mirror repositories, customize images, and access compliance variants with DHI Select and Enterprise subscriptions.](/dhi/how-to/select-enterprise/)

### [Use the DHI CLI](/dhi/how-to/cli/)

[Use the dhictl command-line tool to manage and interact with Docker Hardened Images.](/dhi/how-to/cli/)

### [Mirror a Docker Hardened Image repository](/dhi/how-to/mirror/)

[Learn how to mirror an image into your organization's namespace and optionally push it to another private registry.](/dhi/how-to/mirror/)

### [Customize a Docker Hardened Image or chart](/dhi/how-to/customize/)

[Learn how to customize Docker Hardened Images and charts.](/dhi/how-to/customize/)

### [Use hardened system packages](/dhi/how-to/hardened-packages/)

[Learn how to use Docker's hardened system packages in your images.](/dhi/how-to/hardened-packages/)

### [Use a Docker Hardened Image](/dhi/how-to/use/)

[Learn how to pull, run, and reference Docker Hardened Images in Dockerfiles, CI pipelines, and standard development workflows.](/dhi/how-to/use/)

### [Use a Docker Hardened Image chart](/dhi/how-to/helm/)

[Learn how to use a Docker Hardened Image chart.](/dhi/how-to/helm/)

## [Verify](#verify)

Check signatures, SBOMs, and provenance, and scan for vulnerabilities.

### [Verify a Docker Hardened Image or chart](/dhi/how-to/verify/)

[Use Docker Scout or cosign to verify signed attestations like SBOMs, provenance, and vulnerability data for Docker Hardened Images and charts.](/dhi/how-to/verify/)

### [Scan Docker Hardened Images](/dhi/how-to/scan/)

[Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, or Trivy.](/dhi/how-to/scan/)

## [Govern](#govern)

Enforce policies to maintain security and compliance.

### [Enforce Docker Hardened Image usage with policies](/dhi/how-to/policies/)

[Learn how to use image policies with Docker Scout for Docker Hardened Images.](/dhi/how-to/policies/)

----
url: https://docs.docker.com/guides/agentic-ai/
----

[Build and run agentic AI applications with Docker](https://docs.docker.com/guides/agentic-ai/)

Learn how to create AI agent applications using Docker Model Runner, and MCP Toolkit.

30 minutes

[« Back to all guides](/guides/)

# Build and run agentic AI applications with Docker

***

Table of contents

***

> Tip
>
> This guide uses the familiar Docker Compose workflow to orchestrate agentic AI applications. For a smoother development experience, check out [Docker Agent](https://docs.docker.com/ai/docker-agent/), a purpose-built agent runtime that simplifies running and managing AI agents.

## [Introduction](#introduction)

Agentic applications are transforming how software gets built. These apps don't just respond, they decide, plan, and act. They're powered by models, orchestrated by agents, and integrated with APIs, tools, and services in real time.

All these new agentic applications, no matter what they do, share a common architecture. It's a new kind of stack, built from three core components:

* Models: These are your GPTs, CodeLlamas, Mistrals. They're doing the reasoning, writing, and planning. They're the engine behind the intelligence.

* Agent: This is where the logic lives. Agents take a goal, break it down, and figure out how to get it done. They orchestrate everything. They talk to the UI, the tools, the model, and the gateway.

* MCP gateway: This is what links your agents to the outside world, including APIs, tools, and services. It provides a standard way for agents to call capabilities via the Model Context Protocol (MCP).

Docker makes this AI-powered stack simpler, faster, and more secure by unifying models, and tool gateways into a developer-friendly workflow that uses Docker Compose.

This guide walks you through the core components of agentic development and shows how Docker ties them all together with the following tools:

* [Docker Model Runner](https://docs.docker.com/ai/model-runner/) lets you run LLMs locally with simple command and OpenAI-compatible APIs.
* [Docker MCP Catalog and Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/) helps you discover and securely run external tools, like APIs and databases, using the Model Context Protocol (MCP).
* [Docker MCP Gateway](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/) lets you orchestrate and manage MCP servers.
* [Docker Compose](https://docs.docker.com/ai/compose/models-and-compose/) is the tool that ties it all together, letting you define and run multi-container applications with a single file.

For this guide, you'll use the same Compose workflow you're already familiar with. Then, you'll dig into the Compose file, Dockerfile, and app to see how it all works together.

## [Prerequisites](#prerequisites)

To follow this guide, you need to:

* [Install Docker Desktop 4.43 or later](https://docs.docker.com/get-started/get-docker/)

* [Enable Docker Model Runner](https://docs.docker.com/ai/model-runner/#enable-dmr-in-docker-desktop)

* At least the following hardware specifications:

  * VRAM: 3.5 GB
  * Storage: 2.31 GB

## [Step 1: Clone the sample application](#step-1-clone-the-sample-application)

You'll use an existing sample application that demonstrates how to connect a model to an external tool using Docker's AI features.

```console
$ git clone https://github.com/docker/compose-for-agents.git
$ cd compose-for-agents/adk/
```

## [Step 2: Run the application locally](#step-2-run-the-application-locally)

Your machine must meet the necessary hardware requirements to run the entire application stack locally using Docker Compose. This lets you test the application end-to-end, including the model and MCP gateway, without needing to run in the cloud. This particular example uses the [Gemma 3 4B model](https://hub.docker.com/r/ai/gemma3) with a context size of `10000`.

Hardware requirements:

* VRAM: 3.5 GB
* Storage: 2.31 GB

If your machine exceeds those requirements, consider running the application with a larger context size or a larger model to improve the agents performance. You can easily update model and context size in the `compose.yaml` file.

To run the application locally, follow these steps:

1. In the `adk/` directory of the cloned repository, run the following command in a terminal to build and run the application:

   ```console
   $ docker compose up
   ```

   The first time you run this command, Docker pulls the model from Docker Hub, which may take some time.

2. Visit <http://localhost:8080>. Enter a correct or incorrect fact in the prompt and hit enter. An agent searches DuckDuckGo to verify it and another agent revises the output.

3. Press ctrl-c in the terminal to stop the application when you're done.

## [Step 3: Review the application environment](#step-3-review-the-application-environment)

You can find the `compose.yaml` file in the `adk/` directory. Open it in a text editor to see how the services are defined.

compose.yaml

```yaml
services:
  adk:
    build:
      context: .
    ports:
      # expose port for web interface
      - "8080:8080"
    environment:
      # point adk at the MCP gateway
      - MCPGATEWAY_ENDPOINT=http://mcp-gateway:8811/sse
    depends_on:
      - mcp-gateway
    models:
      gemma3:
        endpoint_var: MODEL_RUNNER_URL
        model_var: MODEL_RUNNER_MODEL

  mcp-gateway:
    # mcp-gateway secures your MCP servers
    image: docker/mcp-gateway:latest
    use_api_socket: true
    command:
      - --transport=sse
      # add any MCP servers you want to use
      - --servers=duckduckgo

models:
  gemma3:
    # pre-pull the model when starting Docker Model Runner
    model: ai/gemma3:4B-Q4_0
    context_size: 10000 # 3.5 GB VRAM
    # increase context size to handle search results
    # context_size: 131000 # 7.6 GB VRAM
```

The app consists of three main components:

* The `adk` service, which is the web application that runs the agentic AI application. This service talks to the MCP gateway and model.
* The `mcp-gateway` service, which is the MCP gateway that connects the app to external tools and services.
* The `models` block, which defines the model to use with the application.

When you examine the `compose.yaml` file, you'll notice two notable elements for the model:

* A service‑level `models` block in the `adk` service
* A top-level `models` block

These two blocks together let Docker Compose automatically start and connect your ADK web app to the specified LLM.

> Tip
>
> Looking for more models to use? Check out the [Docker AI Model Catalog](https://hub.docker.com/catalogs/models/).

When examining the `compose.yaml` file, you'll notice the gateway service is a Docker-maintained image, [`docker/mcp-gateway:latest`](https://hub.docker.com/r/docker/agents_gateway). This image is Docker's open source [MCP Gateway](https://github.com/docker/docker-mcp/) that enables your application to connect to MCP servers, which expose tools that models can call. In this example, it uses the [`duckduckgo` MCP server](https://hub.docker.com/mcp/server/duckduckgo/overview) to perform web searches.

> Tip
>
> Looking for more MCP servers to use? Check out the [Docker MCP Catalog](https://hub.docker.com/catalogs/mcp/).

With only a few lines of instructions in a Compose file, you're able to run and connect all the necessary services of an agentic AI application.

In addition to the Compose file, the Dockerfile and the `entrypoint.sh` script it creates, play a role in wiring up the AI stack at build and runtime. You can find the `Dockerfile` in the `adk/` directory. Open it in a text editor.

Dockerfile

```dockerfile
# Use Python 3.11 slim image as base
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1

RUN pip install uv

WORKDIR /app
# Install system dependencies
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy \
    uv pip install --system .
# Copy application code
COPY agents/ ./agents/
RUN python -m compileall -q .

COPY <<EOF /entrypoint.sh
#!/bin/sh
set -e

if test -f /run/secrets/openai-api-key; then
    export OPENAI_API_KEY=$(cat /run/secrets/openai-api-key)
fi

if test -n "\${OPENAI_API_KEY}"; then
    echo "Using OpenAI with \${OPENAI_MODEL_NAME}"
else
    echo "Using Docker Model Runner with \${MODEL_RUNNER_MODEL}"
    export OPENAI_BASE_URL=\${MODEL_RUNNER_URL}
    export OPENAI_MODEL_NAME=openai/\${MODEL_RUNNER_MODEL}
    export OPENAI_API_KEY=cannot_be_empty
fi
exec adk web --host 0.0.0.0 --port 8080 --log_level DEBUG
EOF
RUN chmod +x /entrypoint.sh

# Create non-root user
RUN useradd --create-home --shell /bin/bash app \
    && chown -R app:app /app
USER app

ENTRYPOINT [ "/entrypoint.sh" ]
```

The `entrypoint.sh` has five key environment variables:

* `MODEL_RUNNER_URL`: Injected by Compose (via the service-level `models:` block) to point at your Docker Model Runner HTTP endpoint.

* `MODEL_RUNNER_MODEL`: Injected by Compose to select which model to launch in Model Runner.

* `OPENAI_API_KEY`: If you define an `openai-api-key` secret in your Compose file, Compose will mount it at `/run/secrets/openai-api-key`. The entrypoint script reads that file and exports it as `OPENAI_API_KEY`, causing the app to use hosted OpenAI instead of Model Runner.

* `OPENAI_BASE_URL`: When no real key is present, this is set to `MODEL_RUNNER_URL` so the ADK's OpenAI-compatible client sends requests to Docker Model Runner.

* `OPENAI_MODEL_NAME`: When falling back to Model Runner, the model is prefixed with `openai/` so the client picks up the right model alias.

Together, these variables let the same ADK web server code seamlessly target either:

* Hosted OpenAI: if you supply `OPENAI_API_KEY` (and optionally `OPENAI_MODEL_NAME`)
* Model Runner: by remapping `MODEL_RUNNER_URL` and `MODEL_RUNNER_MODEL` into the OpenAI client’s expected variables

## [Step 4: Review the application](#step-4-review-the-application)

The `adk` web application is an agent implementation that connects to the MCP gateway and a model through environment variables and API calls. It uses the [ADK (Agent Development Kit)](https://github.com/google/adk-python) to define a root agent named Auditor, which coordinates two sub-agents, Critic and Reviser, to verify and refine model-generated answers.

The three agents are:

* Critic: Verifies factual claims using the toolset, such as DuckDuckGo.
* Reviser: Edits answers based on the verification verdicts provided by the Critic.
* Auditor: A higher-level agent that sequences the Critic and Reviser. It acts as the entry point, evaluating LLM-generated answers, verifying them, and refining the final output.

All of the application's behavior is defined in Python under the `agents/` directory. Here's a breakdown of the notable files:

* `agents/agent.py`: Defines the Auditor, a SequentialAgent that chains together the Critic and Reviser agents. This agent is the main entry point of the application and is responsible for auditing LLM-generated content using real-world verification tools.

* `agents/sub_agents/critic/agent.py`: Defines the Critic agent. It loads the language model (via Docker Model Runner), sets the agent’s name and behavior, and connects to MCP tools (like DuckDuckGo).

* `agents/sub_agents/critic/prompt.py`: Contains the Critic prompt, which instructs the agent to extract and verify claims using external tools.

* `agents/sub_agents/critic/tools.py`: Defines the MCP toolset configuration, including parsing `mcp/` strings, creating tool connections, and handling MCP gateway communication.

* `agents/sub_agents/reviser/agent.py`: Defines the Reviser agent, which takes the Critic’s findings and minimally rewrites the original answer. It also includes callbacks to clean up the LLM output and ensure it's in the right format.

* `agents/sub_agents/reviser/prompt.py`: Contains the Reviser prompt, which instructs the agent to revise the answer text based on the verified claim verdicts.

The MCP gateway is configured via the `MCPGATEWAY_ENDPOINT` environment variable. In this case, `http://mcp-gateway:8811/sse`. This allows the app to use Server-Sent Events (SSE) to communicate with the MCP gateway container, which itself brokers access to external tool services like DuckDuckGo.

## [Summary](#summary)

Agent-based AI applications are emerging as a powerful new software architecture. In this guide, you explored a modular, chain-of-thought system where an Auditor agent coordinates the work of a Critic and a Reviser to fact-check and refine model-generated answers. This architecture shows how to combine local model inference with external tool integrations in a structured, modular way.

You also saw how Docker simplifies this process by providing a suite of tools that support agentic AI development:

* [Docker Model Runner](https://docs.docker.com/ai/model-runner/): Run and serve open-source models locally via OpenAI-compatible APIs.
* [Docker MCP Catalog and Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/): Launch and manage tool integrations that follow the Model Context Protocol (MCP) standard.
* [Docker MCP Gateway](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/): Orchestrate and manage MCP servers to connect agents to external tools and services.
* [Docker Compose](https://docs.docker.com/ai/compose/models-and-compose/): Define and run multi-container agentic AI applications with a single file, using the same workflow.

With these tools, you can develop and test agentic AI applications efficiently, using the same consistent workflow throughout.

----
url: https://docs.docker.com/scout/explore/dashboard/
----

# Dashboard

***

Table of contents

***

The [Docker Scout Dashboard](https://scout.docker.com/) helps you share the analysis of images in an organization with your team. Developers can see an overview of their security status across all their images from Docker Hub, and get remediation advice at their fingertips. It helps team members in roles such as security, compliance, and operations to know what vulnerabilities and issues they need to focus on.

## [Overview](#overview)

The **Overview** tab provides a summary for the repositories in the selected organization.

At the top of this page, you can select which **Environment** to view. By default, the most recently pushed images are shown. To learn more about environments, see [Environment monitoring](https://docs.docker.com/scout/integrations/environment/).

The **Policy** boxes show your current compliance rating for each policy, and a trend indication for the selected environment. The trend describes the policy delta for the most recent images compared to the previous version. For more information about policies, see [Policy Evaluation](https://docs.docker.com/scout/policy/).

The vulnerability chart shows the total number of vulnerabilities for images in the selected environment over time. You can configure the timescale for the chart using the drop-down menu.

Use the header menu at the top of the website to access the different main sections of the Docker Scout Dashboard:

* **Policies**: shows the policy compliance for the organization, see [Policies](#policies)
* **Images**: lists all Docker Scout-enabled repositories in the organization, see [Images](#images)
* **Base images**: lists all base images used by repositories in an organization
* **Packages**: lists all packages across repositories in the organization
* **Vulnerabilities**: lists all CVEs in the organization's images, see [Vulnerabilities](#vulnerabilities)
* **Integrations**: create and manage third-party integrations, see [Integrations](#integrations)
* **Settings**: manage repository settings, see [Settings](#settings)

## [Policies](#policies)

The **Policies** view shows a breakdown of policy compliance for all of the images in the selected organization and environment. You can use the **Image** drop-down menu to view a policy breakdown for a specific environment.

For more information about policies, see [Policy Evaluation](https://docs.docker.com/scout/policy/).

## [Images](#images)

The **Images** view shows all images in Scout-enabled repositories for the selected environment. You can filter the list by selecting a different environment, or by repository name using the text filter.

For each repository, the list displays the following details:

* The repository name (image reference without the tag or digest)
* The most recent tag of the image in the selected environment
* Operating systems and architectures for the most recent tag
* Vulnerabilities status for the most recent tag
* Policy status for the most recent tag

Selecting a repository link takes you to a list of all images in that repository that have been analyzed. From here you can view the full analysis results for a specific image, and compare tags to view the differences in packages and vulnerabilities

Selecting an image link takes you to a details view for the selected tag or digest. This view contains two tabs that detail the composition and policy compliance for the image:

* **Policy status** shows the policy evaluation results for the selected image. Here you also have links for details about the policy violations.

  For more information about policy, see [Policy Evaluation](https://docs.docker.com/scout/policy/).

* **Image layers** shows a breakdown of the image analysis results. You can get a complete view of the vulnerabilities your image contains and understand how they got in.

## [Vulnerabilities](#vulnerabilities)

The **Vulnerabilities** view shows a list of all vulnerabilities for images in the organization. This list includes details about CVE such as the severity and Common Vulnerability Scoring System (CVSS) score, as well as whether there's a fix version available. The CVSS score displayed here is the highest score out of all available [sources](https://docs.docker.com/scout/deep-dive/advisory-db-sources/).

Selecting the links on this page opens the vulnerability details page, This page is a publicly visible page, and shows detailed information about a CVE. You can share the link to a particular CVE description with other people even if they're not a member of your Docker organization or signed in to Docker Scout.

If you are signed in, the **My images** tab on this page lists all of your images affected by the CVE.

## [Integrations](#integrations)

The **Integrations** page lets you create and manage your Docker Scout integrations, such as environment integrations and registry integrations. For more information on how to get started with integrations, see [Integrating Docker Scout with other systems](https://docs.docker.com/scout/integrations/).

## [Settings](#settings)

The settings menu in the Docker Scout Dashboard contains:

* [**Repository settings**](#repository-settings) for enabling and disabling repositories
* [**Notifications**](#notification-settings) for managing your notification preferences for Docker Scout.

### [Repository settings](#repository-settings)

When you enable Docker Scout for a repository, Docker Scout analyzes new tags automatically when you push to that repository. To enable repositories in Amazon ECR, Azure ACR, or other third-party registries, you first need to integrate them. See [Container registry integrations](https://docs.docker.com/scout/integrations/#container-registries)

### [Notification settings](#notification-settings)

The [Notification settings](https://scout.docker.com/settings/notifications) page is where you can change the preferences for receiving notifications from Docker Scout. Notification settings are personal, and changing notification settings only affects your personal account, not the entire organization.

The purpose of notifications in Docker Scout is to raise awareness about upstream changes that affect you. Docker Scout will notify you about when a new vulnerability is disclosed in a security advisory, and it affects one or more of your images. You will not receive notifications about changes to vulnerability exposure or policy compliance as a result of pushing a new image.

> Note
>
> Notifications are only triggered for the *last pushed* image tags for each repository. "Last pushed" refers to the image tag that was most recently pushed to the registry and analyzed by Docker Scout. If the last pushed image is not affected by a newly disclosed CVE, then no notification will be triggered.

The available notification settings are:

* **Repository scope**

  Here you can select whether you want to enable notifications for all repositories, or only for specific repositories. These settings apply to the currently selected organization, and can be changed for each organization you are a member of.

  * **All repositories**: select this option to receive notifications for all repositories that you have access to.
  * **Specific repositories**: select this option to receive notifications for specific repositories. You can then enter the names of repositories you want to receive notifications for.

* **Delivery preferences**

  These settings control how you receive notifications from Docker Scout. They apply to all organizations that you're a member of.

  * **Notification pop-ups**: select this check-box to receive notification pop-up messages in the Docker Scout Dashboard.
  * **OS notifications**: select this check-box to receive OS-level notifications from your browser if you have the Docker Scout Dashboard open in a browser tab.

  To enable OS notifications, Docker Scout needs permissions to send notifications using the browser API.

From this page, you can also go to the settings for Team collaboration integrations, such as the [Slack](https://docs.docker.com/scout/integrations/team-collaboration/slack/) integration.

You can also configure your notification settings in Docker Desktop by going to **Settings** > **Notifications**.

----
url: https://docs.docker.com/reference/api/engine/version/v1.47/
----

# Docker Engine API v1.47 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.47.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.47.yaml)

# Docker Engine API (1.47)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.47.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.47) is used. For example, calling `/info` is the same as calling `/v1.47/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.47/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.47/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.47/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"AppArmorProfile": "",
"Args": [
"-c",
"exit 9"
],
"Config": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"/bin/sh",
"-c",
"exit 9"
],
"Domainname": "",
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Healthcheck": {
"Test": [
"CMD-SHELL",
"exit 0"
]
},
"Hostname": "ba033ac44011",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"MacAddress": "",
"NetworkDisabled": false,
"OpenStdin": false,
"StdinOnce": false,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"StopSignal": "SIGTERM",
"StopTimeout": 10
},
"Created": "2015-01-06T15:47:31.485331387Z",
"Driver": "overlay2",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 0,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"ContainerIDFile": "",
"CpusetCpus": "",
"CpusetMems": "",
"CpuPercent": 80,
"CpuShares": 0,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"Devices": [ ],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"IpcMode": "",
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"OomKillDisable": false,
"OomScoreAdj": 500,
"NetworkMode": "bridge",
"PidMode": "",
"PortBindings": { },
"Privileged": false,
"ReadonlyRootfs": false,
"PublishAllPorts": false,
"RestartPolicy": {
"MaximumRetryCount": 2,
"Name": "on-failure"
},
"LogConfig": {
"Type": "json-file"
},
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Ulimits": [
{ }
],
"VolumeDriver": "",
"ShmSize": 67108864
},
"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
"MountLabel": "",
"Name": "/boring_euclid",
"NetworkSettings": {
"Bridge": "",
"SandboxID": "",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": 0,
"SandboxKey": "",
"EndpointID": "",
"Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"MacAddress": "",
"Networks": {
"bridge": {
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
"EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Path": "/bin/sh",
"ProcessLabel": "",
"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
"RestartCount": 1,
"State": {
"Error": "",
"ExitCode": 9,
"FinishedAt": "2015-01-06T15:47:32.080254511Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2019-12-22T10:59:05.6385933Z",
"End": "2019-12-22T10:59:05.8078452Z",
"ExitCode": 0,
"Output": ""
}
]
},
"OOMKilled": false,
"Dead": false,
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z",
"Status": "running"
},
"Mounts": [
{
"Name": "fac362...80535",
"Source": "/data",
"Destination": "/data",
"Driver": "local",
"Mode": "ro,Z",
"RW": false,
"Propagation": ""
}
]
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.47/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
],
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.47/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.47/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.47/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.47/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"read": "2015-01-08T22:57:31.547920715Z",
"pids_stats": {
"current": 3
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"memory_stats": {
"stats": {
"total_pgmajfault": 0,
"cache": 0,
"mapped_file": 0,
"total_inactive_file": 0,
"pgpgout": 414,
"rss": 6537216,
"total_mapped_file": 0,
"writeback": 0,
"unevictable": 0,
"pgpgin": 477,
"total_unevictable": 0,
"pgmajfault": 0,
"total_rss": 6537216,
"total_rss_huge": 6291456,
"total_writeback": 0,
"total_inactive_anon": 0,
"rss_huge": 6291456,
"hierarchical_memory_limit": 67108864,
"total_pgfault": 964,
"total_active_file": 0,
"active_anon": 6537216,
"total_active_anon": 6537216,
"total_pgpgout": 414,
"total_cache": 0,
"inactive_anon": 0,
"active_file": 0,
"pgfault": 964,
"inactive_file": 0,
"total_pgpgin": 477
},
"max_usage": 6651904,
"usage": 6537216,
"failcnt": 0,
"limit": 67108864
},
"blkio_stats": { },
"cpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24472255,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100215355,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 739306590000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24350896,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100093996,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 9492140000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.47/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.47/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.47/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.47/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.47/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime.This field is omitted when empty.                         |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.47/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"string"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.47/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.47/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.47/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.47/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.47/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.47/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.47/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.47/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.47/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.47/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.47/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |
| manifests   | booleanDefault: falseInclude `Manifests` in the image summary.                                                                                                                                                                                                                                                                                                                                       |

### Responses

/v1.47/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2,
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 3987495
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
]
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.47/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| keep-storage | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| all          | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.47/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.47/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.47/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"DockerVersion": "27.0.1",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "web:web",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": true,
"Image": "",
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.47/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag      | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed.                                                                                                                                                                                                                                                                                                                   |
| platform | stringJSON-encoded OCI platform to select the platform-variant to push. If not provided, all available variants will attempt to be pushed.If the daemon provides a multi-platform image store, this selects the platform-variant to push to the registry. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.47/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.47/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|         |                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------ |
| force   | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags |
| noprune | booleanDefault: falseDo not delete untagged parent images                                              |

### Responses

/v1.47/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                   |
| limit        | integerMaximum number of results to return                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.47/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.47/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.47/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.47/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                          |
| ----- | ---------------------------------------- |
| names | Array of stringsImage names to filter by |

### Responses

/v1.47/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                                             |
| ----- | ----------------------------------------------------------- |
| quiet | booleanDefault: falseSuppress progress details during load. |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.47/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.47/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv4": true,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.47/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv4": true,
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.47/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|              |                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired | stringThe network's name.                                                                                                                                                                                                              |
| Driver       | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope        | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal     | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable   | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress      | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly   | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|              | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|              | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv4   | booleanEnable IPv4 on the network. To disable IPv4, the daemon must be started with experimental features enabled.                                                                                                                     |
| EnableIPv6   | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|              | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|              | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.47/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv4": true,
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.47/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
},
"MacAddress": "02:42:ac:12:05:02"
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.47/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.47/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.47/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.47/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.47/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.47/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.47/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.47/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.47/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.47/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.47/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.47/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.47/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.47/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.47/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.47/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.47/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.47/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.47/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.47/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.47/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.47/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.47/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.47/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.47/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.47/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.47/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.47/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.47/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.47/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.47/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.47/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.47/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.47/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.47/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.47/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.47/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.47/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.47/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.47/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.47/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.47/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.47/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.47/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.47/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.47/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.47/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.47/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.47/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.47/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.47/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.47/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.47/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.47/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.47/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"BridgeNfIptables": true,
"BridgeNfIp6tables": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "6.8.0-31-generic",
"OperatingSystem": "Ubuntu 24.04 LTS",
"OSVersion": "24.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"AllowNondistributableArtifactsCIDRs": [ ],
"AllowNondistributableArtifactsHostnames": [ ],
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "27.0.1",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
],
"Containerd": {
"Address": "/run/containerd/containerd.sock",
"Namespaces": {
"Containers": "moby",
"Plugins": "plugins.moby"
}
}
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.47/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "27.0.1",
"Details": { }
}
],
"Version": "27.0.1",
"ApiVersion": "1.47",
"MinAPIVersion": "1.24",
"GitCommit": "48a66213fe",
"GoVersion": "go1.21.13",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "6.8.0-31-generic",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.47/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.47/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.47/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|      |                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |

### Responses

/v1.47/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parents": [ ],
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parents": [
"ndlpt0hhvkqcdfkputsk4cq9c"
],
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.47/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 3987495
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.47/session

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/build/logs/
----

# docker dhi customization build logs

***

| Description | Get logs of a build                                                  |
| ----------- | -------------------------------------------------------------------- |
| Usage       | `docker dhi customization build logs <repository> <name> <build-id>` |

## [Description](#description)

Get the logs of a Docker Hardened Images customization build

## [Options](#options)

| Option   | Default | Description           |
| -------- | ------- | --------------------- |
| `--json` |         | Output in JSON format |

----
url: https://docs.docker.com/reference/cli/sbx/stop/
----

# sbx stop

| Description | Stop one or more sandboxes without removing them |
| ----------- | ------------------------------------------------ |
| Usage       | `sbx stop SANDBOX [SANDBOX...]`                  |

## [Description](#description)

Stop one or more running sandboxes without removing them.

Stopped sandboxes retain their state and can be restarted with "sbx run".

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/scout/explore/analysis/
----

# Docker Scout image analysis

***

Table of contents

***

When you activate image analysis for a repository, Docker Scout automatically analyzes new images that you push to that repository.

Image analysis extracts the Software Bill of Material (SBOM) and other image metadata,and evaluates it against vulnerability data from [security advisories](https://docs.docker.com/scout/deep-dive/advisory-db-sources/).

If you run image analysis as a one-off task using the CLI or Docker Desktop, Docker Scout won't store any data about your image. If you enable Docker Scout for your container image repositories however, Docker Scout saves a metadata snapshot of your images after the analysis. As new vulnerability data becomes available, Docker Scout recalibrates the analysis using the metadata snapshot, which means your security status for images is updated in real-time. This dynamic evaluation means there's no need to re-analyze images when new CVE information is disclosed.

Docker Scout image analysis is available by default for Docker Hub repositories. You can also integrate third-party registries and other services. To learn more, see [Integrating Docker Scout with other systems](https://docs.docker.com/scout/integrations/).

## [Activate Docker Scout on a repository](#activate-docker-scout-on-a-repository)

See [Subscriptions and features](https://www.docker.com/pricing?ref=Docs\&refAction=DocsScoutAnalysis) to learn how many Scout-enabled repositories come with each subscription tier.

Before you can activate image analysis on a repository in a third-party registry, the registry must be integrated with Docker Scout for your Docker organization. Docker Hub is integrated by default. For more information, see See [Container registry integrations](https://docs.docker.com/scout/integrations/#container-registries)

> Note
>
> You must have the **Editor** or **Owner** role in the Docker organization to activate image analysis on a repository.

To activate image analysis:

1. Go to [Repository settings](https://scout.docker.com/settings/repos) in the Docker Scout Dashboard.
2. Select the repositories that you want to enable.
3. Select **Enable image analysis**.

If your repositories already contain images, Docker Scout pulls and analyzes the latest images automatically.

## [Analyze registry images](#analyze-registry-images)

To trigger image analysis for an image in a registry, push the image to a registry that's integrated with Docker Scout, to a repository where image analysis is activated.

> Note
>
> Image analysis on the Docker Scout platform has a maximum image file size limit of 10 GB, unless the image has an SBOM attestation. See [Maximum image size](#maximum-image-size).

1. Sign in with your Docker ID, either using the `docker login` command or the **Sign in** button in Docker Desktop.

2. Build and push the image that you want to analyze.

   ```console
   $ docker build --push --tag <org>/<image:tag> --provenance=true --sbom=true .
   ```

   Building with the `--provenance=true` and `--sbom=true` flags attaches [build attestations](https://docs.docker.com/build/metadata/attestations/) to the image. Docker Scout uses attestations to provide more fine-grained analysis results.

   > Note
   >
   > The default `docker` driver only supports build attestations if you use the [containerd image store](https://docs.docker.com/desktop/features/containerd/).

3. Go to the [Images page](https://scout.docker.com/reports/images) in the Docker Scout Dashboard.

   The image appears in the list shortly after you push it to the registry. It may take a few minutes for the analysis results to appear.

## [Analyze images locally](#analyze-images-locally)

You can analyze local images with Docker Scout using Docker Desktop or the `docker scout` commands for the Docker CLI.

### [Docker Desktop](#docker-desktop)

> Note
>
> Docker Desktop background indexing supports images up to 10 GB in size. See [Maximum image size](#maximum-image-size).

To analyze an image locally using the Docker Desktop GUI:

1. Pull or build the image that you want to analyze.

2. Go to the **Images** view in the Docker Dashboard.

3. Select one of your local images in the list.

   This opens the [Image details view](https://docs.docker.com/scout/explore/image-details-view/), showing a breakdown of packages and vulnerabilities found by the Docker Scout analysis for the image you selected.

### [CLI](#cli)

The `docker scout` CLI commands provide a command line interface for using Docker Scout from your terminal.

* `docker scout quickview`: summary of the specified image, see [Quickview](#quickview)
* `docker scout cves`: local analysis of the specified image, see [CVEs](#cves)
* `docker scout compare`: analyzes and compares two images

By default, the results are printed to standard output. You can also export results to a file in a structured format, such as Static Analysis Results Interchange Format (SARIF).

#### [Quickview](#quickview)

The `docker scout quickview` command provides an overview of the vulnerabilities found in a given image and its base image.

```console
$ docker scout quickview traefik:latest
    ✓ SBOM of image already cached, 311 packages indexed

  Your image  traefik:latest  │    0C     2H     8M     1L
  Base image  alpine:3        │    0C     0H     0M     0L
```

If your the base image is out of date, the `quickview` command also shows how updating your base image would change the vulnerability exposure of your image.

```console
$ docker scout quickview postgres:13.1
    ✓ Pulled
    ✓ Image stored for indexing
    ✓ Indexed 187 packages

  Your image  postgres:13.1                 │   17C    32H    35M    33L
  Base image  debian:buster-slim            │    9C    14H     9M    23L
  Refreshed base image  debian:buster-slim  │    0C     1H     6M    29L
                                            │    -9    -13     -3     +6
  Updated base image  debian:stable-slim    │    0C     0H     0M    17L
                                            │    -9    -14     -9     -6
```

#### [CVEs](#cves)

The `docker scout cves` command gives you a complete view of all the vulnerabilities in the image. This command supports several flags that lets you specify more precisely which vulnerabilities you're interested in, for example, by severity or package type:

```console
$ docker scout cves --format only-packages --only-vuln-packages \
  --only-severity critical postgres:13.1
    ✓ SBOM of image already cached, 187 packages indexed
    ✗ Detected 10 vulnerable packages with a total of 17 vulnerabilities

     Name            Version         Type        Vulnerabilities
───────────────────────────────────────────────────────────────────────────
  dpkg        1.19.7                 deb      1C     0H     0M     0L
  glibc       2.28-10                deb      4C     0H     0M     0L
  gnutls28    3.6.7-4+deb10u6        deb      2C     0H     0M     0L
  libbsd      0.9.1-2                deb      1C     0H     0M     0L
  libksba     1.3.5-2                deb      2C     0H     0M     0L
  libtasn1-6  4.13-3                 deb      1C     0H     0M     0L
  lz4         1.8.3-1                deb      1C     0H     0M     0L
  openldap    2.4.47+dfsg-3+deb10u5  deb      1C     0H     0M     0L
  openssl     1.1.1d-0+deb10u4       deb      3C     0H     0M     0L
  zlib        1:1.2.11.dfsg-1        deb      1C     0H     0M     0L
```

For more information about these commands and how to use them, refer to the CLI reference documentation:

* [`docker scout quickview`](/reference/cli/docker/scout/quickview/)
* [`docker scout cves`](/reference/cli/docker/scout/cves/)

## [Vulnerability severity assessment](#vulnerability-severity-assessment)

Docker Scout assigns a severity rating to vulnerabilities based on vulnerability data from [advisory sources](https://docs.docker.com/scout/deep-dive/advisory-db-sources/). Advisories are ranked and prioritized depending on the type of package that's affected by a vulnerability. For example, if a vulnerability affects an OS package, the severity level assigned by the distribution maintainer is prioritized.

If the preferred advisory source has assigned a severity rating to a CVE, but not a CVSS score, Docker Scout falls back to displaying a CVSS score from another source. The severity rating from the preferred advisory and the CVSS score from the fallback advisory are displayed together. This means a vulnerability can have a severity rating of `LOW` with a CVSS score of 9.8, if the preferred advisory assigns a `LOW` rating but no CVSS score, and a fallback advisory assigns a CVSS score of 9.8.

Vulnerabilities that haven't been assigned a CVSS score in any source are categorized as **Unspecified** (U).

Docker Scout doesn't implement a proprietary vulnerability metrics system. All metrics are inherited from security advisories that Docker Scout integrates with. Advisories may use different thresholds for classifying vulnerabilities, but most of them adhere to the CVSS v3.0 specification, which maps CVSS scores to severity ratings according to the following table:

| CVSS score | Severity rating  |
| ---------- | ---------------- |
| 0.1 – 3.9  | **Low** (L)      |
| 4.0 – 6.9  | **Medium** (M)   |
| 7.0 – 8.9  | **High** (H)     |
| 9.0 – 10.0 | **Critical** (C) |

For more information, see [Vulnerability Metrics (NIST)](https://nvd.nist.gov/vuln-metrics/cvss).

Note that, given the advisory prioritization and fallback mechanism described earlier, severity ratings displayed in Docker Scout may deviate from this rating system.

## [Maximum image size](#maximum-image-size)

Image analysis on the Docker Scout platform, and analysis triggered by background indexing in Docker Desktop, has an image file size limit of 10 GB (uncompressed). To analyze images larger than that:

* Attach an [SBOM attestation](https://docs.docker.com/build/metadata/attestations/sbom/) at build-time. When an image includes an SBOM attestation, Docker Scout uses it instead of generating one, so the 10 GB limit doesn’t apply.
* Alternatively, you can use the [CLI](#cli) to analyze the image locally. The 10 GB limit doesn’t apply when using the CLI. If the image includes an SBOM attestation, the CLI uses it to complete the analysis faster.

----
url: https://docs.docker.com/compose/how-tos/environment-variables/envvars-precedence/
----

# Environment variables precedence in Docker Compose

***

Table of contents

***

When the same environment variable is set in multiple sources, Docker Compose follows a precedence rule to determine the value for that variable in your container's environment.

This page explains how Docker Compose determines the final value of an environment variable when it's defined in multiple locations.

The order of precedence (highest to lowest) is as follows:

1. Set using [`docker compose run -e` in the CLI](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/#set-environment-variables-with-docker-compose-run---env).
2. Set with either the `environment` or `env_file` attribute but with the value interpolated from your [shell](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/#substitute-from-the-shell) or an environment file. (either your default [`.env` file](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/#env-file), or with the [`--env-file` argument](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/#substitute-with---env-file) in the CLI).
3. Set using just the [`environment` attribute](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/#use-the-environment-attribute) in the Compose file.
4. Use of the [`env_file` attribute](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/#use-the-env_file-attribute) in the Compose file.
5. Set in a container image in the [ENV directive](https://docs.docker.com/reference/dockerfile/#env). Having any `ARG` or `ENV` setting in a `Dockerfile` evaluates only if there is no Docker Compose entry for `environment`, `env_file` or `run --env`.

## [Simple example](#simple-example)

In the following example, a different value for the same environment variable in an `.env` file and with the `environment` attribute in the Compose file:

```console
$ cat ./webapp.env
NODE_ENV=test

$ cat compose.yaml
services:
  webapp:
    image: 'webapp'
    env_file:
     - ./webapp.env
    environment:
     - NODE_ENV=production
```

The environment variable defined with the `environment` attribute takes precedence.

```console
$ docker compose run webapp env | grep NODE_ENV
NODE_ENV=production
```

## [Advanced example](#advanced-example)

The following table uses `VALUE`, an environment variable defining the version for an image, as an example.

### [How the table works](#how-the-table-works)

Each column represents a context from where you can set a value, or substitute in a value for `VALUE`.

The columns `Host OS environment` and `.env` file is listed only for illustration purposes. In reality, they don't result in a variable in the container by itself, but in conjunction with either the `environment` or `env_file` attribute.

Each row represents a combination of contexts where `VALUE` is set, substituted, or both. The **Result** column indicates the final value for `VALUE` in each scenario.

| #  | `docker compose run` | `environment` attribute | `env_file` attribute | Image `ENV` | `Host OS` environment | `.env` file | Result          |
| -- | -------------------- | ----------------------- | -------------------- | ----------- | --------------------- | ----------- | --------------- |
| 1  | -                    | -                       | -                    | -           | `VALUE=1.4`           | `VALUE=1.3` | -               |
| 2  | -                    | -                       | `VALUE=1.6`          | `VALUE=1.5` | `VALUE=1.4`           | -           | **`VALUE=1.6`** |
| 3  | -                    | `VALUE=1.7`             | -                    | `VALUE=1.5` | `VALUE=1.4`           | -           | **`VALUE=1.7`** |
| 4  | -                    | -                       | -                    | `VALUE=1.5` | `VALUE=1.4`           | `VALUE=1.3` | **`VALUE=1.5`** |
| 5  | `--env VALUE=1.8`    | -                       | -                    | `VALUE=1.5` | `VALUE=1.4`           | `VALUE=1.3` | **`VALUE=1.8`** |
| 6  | `--env VALUE`        | -                       | -                    | `VALUE=1.5` | `VALUE=1.4`           | `VALUE=1.3` | **`VALUE=1.4`** |
| 7  | `--env VALUE`        | -                       | -                    | `VALUE=1.5` | -                     | `VALUE=1.3` | **`VALUE=1.3`** |
| 8  | -                    | -                       | `VALUE`              | `VALUE=1.5` | `VALUE=1.4`           | `VALUE=1.3` | **`VALUE=1.4`** |
| 9  | -                    | -                       | `VALUE`              | `VALUE=1.5` | -                     | `VALUE=1.3` | **`VALUE=1.3`** |
| 10 | -                    | `VALUE`                 | -                    | `VALUE=1.5` | `VALUE=1.4`           | `VALUE=1.3` | **`VALUE=1.4`** |
| 11 | -                    | `VALUE`                 | -                    | `VALUE=1.5` | -                     | `VALUE=1.3` | **`VALUE=1.3`** |
| 12 | `--env VALUE`        | `VALUE=1.7`             | -                    | `VALUE=1.5` | `VALUE=1.4`           | `VALUE=1.3` | **`VALUE=1.4`** |
| 13 | `--env VALUE=1.8`    | `VALUE=1.7`             | -                    | `VALUE=1.5` | `VALUE=1.4`           | `VALUE=1.3` | **`VALUE=1.8`** |
| 14 | `--env VALUE=1.8`    | -                       | `VALUE=1.6`          | `VALUE=1.5` | `VALUE=1.4`           | `VALUE=1.3` | **`VALUE=1.8`** |
| 15 | `--env VALUE=1.8`    | `VALUE=1.7`             | `VALUE=1.6`          | `VALUE=1.5` | `VALUE=1.4`           | `VALUE=1.3` | **`VALUE=1.8`** |

### [Understanding precedence results](#understanding-precedence-results)

Result 1: The local environment takes precedence, but the Compose file is not set to replicate this inside the container, so no such variable is set.

Result 2: The `env_file` attribute in the Compose file defines an explicit value for `VALUE` so the container environment is set accordingly.

Result 3: The `environment` attribute in the Compose file defines an explicit value for `VALUE`, so the container environment is set accordingly.

Result 4: The image's `ENV` directive declares the variable `VALUE`, and since the Compose file is not set to override this value, this variable is defined by image

Result 5: The `docker compose run` command has the `--env` flag set with an explicit value, and overrides the value set by the image.

Result 6: The `docker compose run` command has the `--env` flag set to replicate the value from the environment. Host OS value takes precedence and is replicated into the container's environment.

Result 7: The `docker compose run` command has the `--env` flag set to replicate the value from the environment. Value from `.env` file is selected to define the container's environment.

Result 8: The `env_file` attribute in the Compose file is set to replicate `VALUE` from the local environment. Host OS value takes precedence and is replicated into the container's environment.

Result 9: The `env_file` attribute in the Compose file is set to replicate `VALUE` from the local environment. Value from `.env` file is selected to define the container's environment.

Result 10: The `environment` attribute in the Compose file is set to replicate `VALUE` from the local environment. Host OS value takes precedence and is replicated into the container's environment.

Result 11: The `environment` attribute in the Compose file is set to replicate `VALUE` from the local environment. Value from `.env` file is selected to define the container's environment.

Result 12: The `--env` flag has higher precedence than the `environment` and `env_file` attributes and is to set to replicate `VALUE` from the local environment. Host OS value takes precedence and is replicated into the container's environment.

Results 13 to 15: The `--env` flag has higher precedence than the `environment` and `env_file` attributes and so sets the value.

## [Next steps](#next-steps)

* [Set environment variables in Compose](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/)
* [Use variable interpolation in Compose files](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/)

----
url: https://docs.docker.com/ai/docker-agent/
----

***

Table of contents

***

[Docker Agent](https://github.com/docker/docker-agent) is an open-source framework for building teams of specialized AI agents. Instead of prompting one generalist model, you define agents with specific roles and instructions that collaborate to solve problems. Run these agent teams from your terminal using any LLM provider.

> Note
>
> Docker Agent is a framework for building and running custom agent teams. For Docker's built-in AI assistant, see [Gordon](/ai/gordon/) (`docker ai`).

## [Why agent teams](#why-agent-teams)

One agent handling complex work means constant context-switching. Split the work across focused agents instead - each handles what it's best at. Docker Agent manages the coordination.

Here's a two-agent team that debugs problems:

```yaml
agents:
  root:
    model: openai/gpt-5-mini # Change to the model that you want to use
    description: Bug investigator
    instruction: |
      Analyze error messages, stack traces, and code to find bug root causes.
      Explain what's wrong and why it's happening.
      Delegate fix implementation to the fixer agent.
    sub_agents: [fixer]
    toolsets:
      - type: filesystem
      - type: mcp
        ref: docker:duckduckgo

  fixer:
    model: anthropic/claude-sonnet-4-5 # Change to the model that you want to use
    description: Fix implementer
    instruction: |
      Write fixes for bugs diagnosed by the investigator.
      Make minimal, targeted changes and add tests to prevent regression.
    toolsets:
      - type: filesystem
      - type: shell
```

The root agent investigates and explains the problem. When it understands the issue, it hands off to `fixer` for implementation. Each agent stays focused on its specialty.

## [Installation](#installation)

Docker Agent is included in Docker Desktop 4.63 and later. In Docker Desktop versions 4.49 through 4.62, this feature was called cagent.

For Docker Engine users or custom installations:

* **Homebrew**: `brew install docker-agent`
* **Winget**: `winget install Docker.Agent`
* **Pre-built binaries**: [GitHub releases](https://github.com/docker/docker-agent/releases)
* **From source**: See the [Docker Agent repository](https://github.com/docker/docker-agent?tab=readme-ov-file#build-from-source)

The `docker-agent` binary should be copied to `~/.docker/cli-plugins` and then can be used with the `docker agent` command. Alternatively, it can be used as a standalone binary.

## [Get started](#get-started)

Try the bug analyzer team:

1. Set your API key for the model provider you want to use:

   ```console
   $ export ANTHROPIC_API_KEY=<your_key>  # For Claude models
   $ export OPENAI_API_KEY=<your_key>     # For OpenAI models
   $ export GOOGLE_API_KEY=<your_key>     # For Gemini models
   ```

2. Save the [example configuration](#why-agent-teams) as `debugger.yaml`.

3. Run your agent team:

   ```console
   $ docker agent run debugger.yaml
   ```

You'll see a prompt where you can describe bugs or paste error messages. The investigator analyzes the problem, then hands off to the fixer for implementation.

## [How it works](#how-it-works)

You interact with the *root agent*, which can delegate work to sub-agents you define. Each agent:

* Uses its own model and parameters
* Has its own context (agents don't share knowledge)
* Can access built-in tools like todo lists, memory, and task delegation
* Can use external tools via [MCP servers](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/)

The root agent delegates tasks to agents listed under `sub_agents`. Sub-agents can have their own sub-agents for deeper hierarchies.

## [Configuration options](#configuration-options)

Agent configurations are YAML files. A basic structure looks like this:

```yaml
agents:
  root:
    model: claude-sonnet-4-0
    description: Brief role summary
    instruction: |
      Detailed instructions for this agent...
    sub_agents: [helper]

  helper:
    model: gpt-5-mini
    description: Specialist agent role
    instruction: |
      Instructions for the helper agent...
```

You can also configure model settings (like context limits), tools (including MCP servers), and more. See the [configuration reference](https://docs.docker.com/ai/docker-agent/reference/config/) for complete details.

## [Share agent teams](#share-agent-teams)

Agent configurations are packaged as OCI artifacts. Push and pull them like container images:

```console
$ docker agent share push ./debugger.yaml myusername/debugger
$ docker agent share pull myusername/debugger
```

Use Docker Hub or any OCI-compatible registry. Pushing creates the repository if it doesn't exist yet.

## [What's next](#whats-next)

* Follow the [tutorial](https://docs.docker.com/ai/docker-agent/tutorial/) to build your first coding agent
* Learn [best practices](https://docs.docker.com/ai/docker-agent/best-practices/) for building effective agents
* Integrate Docker Agent with your [editor](https://docs.docker.com/ai/docker-agent/integrations/acp/) or use agents as [tools in MCP clients](https://docs.docker.com/ai/docker-agent/integrations/mcp/)
* Browse example agent configurations in the [Docker Agent repository](https://github.com/docker/docker-agent/tree/main/examples)
* Use `docker agent new` to generate agent teams with AI
* Connect agents to external tools via the [Docker MCP Gateway](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/)
* Read the full [configuration reference](https://github.com/docker/docker-agent?tab=readme-ov-file#-configuration-reference)

----
url: https://docs.docker.com/guides/r/deploy/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Test your R deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Containerize a R application](https://docs.docker.com/guides/r/containerize/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your `r-docker-dev` directory, create a file named `docker-r-kubernetes.yaml`. Open the file in an IDE or text editor and add the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the name of the repository that you created in [Configure CI/CD for your R application](https://docs.docker.com/guides/r/configure-ci-cd/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-r-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: shiny
  template:
    metadata:
      labels:
        service: shiny
    spec:
      containers:
        - name: shiny-service
          image: DOCKER_USERNAME/REPO_NAME
          imagePullPolicy: Always
          env:
            - name: POSTGRES_PASSWORD
              value: mysecretpassword
---
apiVersion: v1
kind: Service
metadata:
  name: service-entrypoint
  namespace: default
spec:
  type: NodePort
  selector:
    service: shiny
  ports:
    - port: 3838
      targetPort: 3838
      nodePort: 30001
```

In this Kubernetes YAML file, there are two objects, separated by the `---`:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your R application](https://docs.docker.com/guides/r/configure-ci-cd/).
* A NodePort service, which will route traffic from port 30001 on your host to port 3838 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to `r-docker-dev` and deploy your application to Kubernetes.

   ```console
   $ kubectl apply -f docker-r-kubernetes.yaml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```text
   deployment.apps/docker-r-demo created
   service/service-entrypoint created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```shell
   NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
   docker-r-demo   1/1     1            1           15s
   ```

   This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```shell
   NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
   kubernetes           ClusterIP   10.96.0.1       <none>        443/TCP          23h
   service-entrypoint   NodePort    10.99.128.230   <none>        3838:30001/TCP   75s
   ```

   In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP.

3. In a browser, visit the following address. Note that a database was not deployed in this example.

   ```console
   http://localhost:30001/
   ```

4. Run the following command to tear down your application.

   ```console
   $ kubectl delete -f docker-r-kubernetes.yaml
   ```

----
url: https://docs.docker.com/reference/cli/docker/mcp/feature/enable/
----

# docker mcp feature enable

***

| Description | Enable an experimental feature             |
| ----------- | ------------------------------------------ |
| Usage       | `docker mcp feature enable <feature-name>` |

## [Description](#description)

Enable an experimental feature.

Available features: oauth-interceptor Enable GitHub OAuth flow interception for automatic authentication mcp-oauth-dcr Enable Dynamic Client Registration (DCR) for automatic OAuth client setup dynamic-tools Enable internal MCP management tools (mcp-find, mcp-add, mcp-remove) profiles Enable profile management (docker mcp profile ) tool-name-prefix Prefix all tool names with server name to avoid conflicts

----
url: https://docs.docker.com/ai/sandboxes/get-started/
----

# Get started with Docker Sandboxes

***

Table of contents

***

Docker Sandboxes run AI coding agents in isolated microVM sandboxes. Each sandbox gets its own Docker daemon, filesystem, and network — the agent can build containers, install packages, and modify files without touching your host system.

This page walks through a typical first session: installing the CLI, authenticating your agent, running a sandbox, working with branches, and cleaning up.

## [Prerequisites](#prerequisites)

* macOS Sonoma (version 14) or later
* Apple silicon

- 64-bit Intel or AMD (x86\_64)
- Windows 11
- Windows Hypervisor Platform enabled. Open an elevated PowerShell prompt (Run as Administrator) and run:
  ```powershell
  Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All
  ```

* Ubuntu 24.04 or later
* 64-bit Intel or AMD (x86\_64)
* KVM hardware virtualization supported and enabled by the CPU. If you're running inside a VM, nested virtualization must be turned on. Verify that KVM is available:
  ```console
  $ lsmod | grep kvm
  ```
  A working setup shows `kvm_intel` or `kvm_amd` in the output. If the output is empty, run `kvm-ok` for diagnostics. If KVM is unavailable, `sbx` will not start.
* Your user in the `kvm` group:
  ```console
  $ sudo usermod -aG kvm $USER
  ```
  Log out and back in (or run `newgrp kvm`) for the group change to take effect.

An API key or authentication method for the agent you want to use. Most agents require an API key for their model provider (Anthropic, OpenAI, Google, and others). See the [agent pages](https://docs.docker.com/ai/sandboxes/agents/) for provider-specific instructions.

Docker Desktop is not required to use `sbx`.

## [Install and sign in](#install-and-sign-in)

```console
$ brew install docker/tap/sbx
$ sbx login
```

```powershell
> winget install -h Docker.sbx
> sbx login
```

```console
$ curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
$ sudo apt-get install docker-sbx
$ sbx login
```

The first command adds Docker's `apt` repository to your system.

If you need to install `sbx` manually, download a binary directly from the [sbx-releases](https://github.com/docker/sbx-releases/releases) repository.

`sbx login` opens a browser for Docker OAuth. On first login (and after `sbx policy reset`), the CLI prompts you to choose a default network policy for your sandboxes:

```plaintext
Choose a default network policy:

     1. Open         — All network traffic allowed, no restrictions.
     2. Balanced     — Default deny, with common dev sites allowed.
     3. Locked Down  — All network traffic blocked unless you allow it.

Use ↑/↓ to navigate, Enter to select, or press 1–3.
```

**Balanced** is a good starting point — it permits traffic to common development services while blocking everything else. You can adjust individual rules later. See [Policies](https://docs.docker.com/ai/sandboxes/security/policy/) for a full description of each option.

> Note
>
> See the [FAQ](https://docs.docker.com/ai/sandboxes/faq/) for details on why sign-in is required and what happens with your data.

## [Authenticate your agent](#authenticate-your-agent)

Agents need credentials for their model provider. How you provide them depends on the agent.

For Claude Code with a Claude subscription (Max, Team, or Enterprise), no upfront setup is needed — use the `/login` command inside the sandbox to sign in with OAuth. The session token stays on your host and is injected by a proxy, not stored inside the sandbox.

For agents that use API keys (or if you prefer API key authentication for Claude Code), store the key before starting a sandbox:

```console
$ sbx secret set -g anthropic
```

This prompts for the secret value and stores it in your OS keychain. A proxy on your host injects the key into outbound API requests so it's never exposed inside the sandbox. See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for details on scoping, supported services, and alternative methods.

To give the agent access to GitHub for creating pull requests or interacting with repositories:

```console
$ sbx secret set -g github -t "$(gh auth token)"
```

## [Run your first sandbox](#run-your-first-sandbox)

Pick a project directory and launch an agent with [`sbx run`](/reference/cli/sbx/run/):

```console
$ cd ~/my-project
$ sbx run claude
```

Replace `claude` with the agent you want to use — see [Agents](https://docs.docker.com/ai/sandboxes/agents/) for the full list.

The first run takes a little longer while the agent image is pulled. Subsequent runs reuse the cached image and start in seconds.

You can check what's running at any time:

```console
$ sbx ls
SANDBOX              AGENT    STATUS    PORTS   WORKSPACE
claude-my-project    claude   running           ~/my-project
```

You can also run `sbx` with no arguments to open an interactive dashboard. The dashboard shows your sandboxes with live status, lets you attach to agents, open shells, and manage network rules from one place. See [Interactive mode](https://docs.docker.com/ai/sandboxes/usage/#interactive-mode) for details.

## [Use branch mode](#use-branch-mode)

By default, the agent edits your working tree directly. To give it its own Git branch, use `--branch`:

```console
$ sbx run claude --branch my-feature
```

This creates a [Git worktree](https://git-scm.com/docs/git-worktree) under `.sbx/` in your repository root. The agent works on its own branch and directory without touching your main working tree.

When the session ends, review what the agent did from the worktree:

```console
$ cd .sbx/claude-my-project-worktrees/my-feature
$ git log
$ git diff main
```

If you're satisfied, push the branch and open a pull request:

```console
$ git push -u origin my-feature
$ gh pr create
```

Branch mode is especially useful when running multiple agents on the same repository — each gets its own branch and can't overwrite the other's changes. See [Branch mode](https://docs.docker.com/ai/sandboxes/usage/#branch-mode) for more options, including `--branch auto` and multiple branches per sandbox.

## [Manage network access](#manage-network-access)

Your network policy controls what the sandbox can reach. If the agent fails to connect to an API or service, it's likely blocked by the policy.

Check which rules are in effect:

```console
$ sbx policy ls
```

To allow a specific host:

```console
$ sbx policy allow network -g registry.npmjs.org
```

With **Locked Down**, even your model provider API is blocked unless you explicitly allow it. With **Balanced**, common development services are permitted by default. See [Policies](https://docs.docker.com/ai/sandboxes/security/policy/) for the full rule set and how to customize it.

## [Clean up](#clean-up)

Sandboxes persist after the agent exits. To stop a sandbox without deleting it:

```console
$ sbx stop claude-my-project
```

The sandbox name comes from the agent and workspace directory — see [Reconnecting and naming](https://docs.docker.com/ai/sandboxes/usage/#reconnecting-and-naming) for details, or run `sbx ls` to see the names of your existing sandboxes.

Installed packages, Docker images, and configuration changes are preserved across restarts. When you're done with a sandbox, remove it to reclaim disk space:

```console
$ sbx rm claude-my-project
```

Removing a sandbox deletes everything inside it — installed packages, Docker images, and any branch mode worktrees under `.sbx/`. Files in your main working tree are unaffected.

## [Next steps](#next-steps)

* [Usage guide](https://docs.docker.com/ai/sandboxes/usage/) — sandbox management, reconnecting, multiple workspaces, port forwarding, and more
* [Agents](https://docs.docker.com/ai/sandboxes/agents/) — supported agents and configuration
* [Customize](https://docs.docker.com/ai/sandboxes/customize/) — build reusable templates or declare capabilities with kits
* [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) — credential storage and management
* [Workspace isolation](https://docs.docker.com/ai/sandboxes/security/isolation/#workspace-isolation) — what the agent can affect on your host, and how to review changes
* [Policies](https://docs.docker.com/ai/sandboxes/security/policy/) — control outbound access

----
url: https://docs.docker.com/guides/nextjs/containerize/
----

# Containerize a Next.js Application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Before you begin, make sure the following tools are installed and available on your system:

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client.

> Note
>
> New to Docker? Start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide to get familiar with key concepts like images, containers, and Dockerfiles.

***

## [Overview](#overview)

This guide walks you through containerizing a Next.js application with Docker. You'll learn how to create a production-ready Docker image using best practices that improve performance, security, scalability, and deployment efficiency.

By the end of this guide, you will:

* Containerize a Next.js application using Docker.
* Create and optimize a Dockerfile for production builds.
* Use multi-stage builds to minimize image size.
* Leverage Next.js standalone or export output for efficient containerization.
* Follow best practices for building secure and maintainable Docker images.

***

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the git repository:

```console
$ git clone https://github.com/kristiyan-velkov/docker-nextjs-sample
```

***

## [Build the Docker image](#build-the-docker-image)

Next.js has specific requirements for production deployments. This guide shows two approaches: `standalone` output (Node.js server) and `export` output (static files with Nginx).

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

### [Step 1: Configure Next.js and create the Dockerfile](#step-1-configure-nextjs-and-create-the-dockerfile)

Before creating a Dockerfile, choose a base image: the [Node.js Official Image](https://hub.docker.com/_/node) or a [Docker Hardened Image (DHI)](https://hub.docker.com/hardened-images/catalog) from the Hardened Image catalog. Choosing DHI gives you a production-ready, lightweight, and secure image. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/).

> Important
>
> This guide uses stable Node.js LTS image tags that are considered secure when the guide is written. Because new releases and security patches are published regularly, always review the [official Node.js Docker images](https://hub.docker.com/_/node) and select a secure, up-to-date version before building or deploying.

***

#### [1.1 Next.js with standalone output](#11-nextjs-with-standalone-output)

Standalone output (`output: "standalone"`) makes Next.js build a self-contained output that includes only the files and dependencies needed to run the application. A single `node server.js` can serve the app, which is ideal for Docker and supports server-side rendering, API routes, and incremental static regeneration. For details, see the [Next.js output configuration documentation](https://nextjs.org/docs/app/api-reference/config/next-config-js/output) (including the "standalone" option).

The container runs the Next.js server with Node.js on port 3000.

Configure Next.js — Open or create `next.config.ts` in your project root:

```ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone",
};

export default nextConfig;
```

Choose either a Docker Hardened Image or the Docker Official Image, then create a `Dockerfile` using the content from the selected tab below.

Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). For more information, see the [DHI quickstart](/dhi/get-started/) guide.

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Pull the Node.js DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/node:24-alpine3.22-dev
   ```

3. Create a file named `Dockerfile` with the following contents. The `FROM` instructions use `dhi.io/node:24-alpine3.22-dev`. Check the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog) for the latest versions and update the image tags as needed for security and compatibility.

   ```dockerfile
   # ============================================
   # Stage 1: Dependencies Installation Stage
   # ============================================

   # IMPORTANT: Docker Hardened Image (DHI) Version Maintenance
   # This Dockerfile uses dhi.io/node. Regularly validate and update to the latest DHI versions in the catalog for security and compatibility.

   FROM dhi.io/node:24-alpine3.22-dev AS dependencies

   # Set working directory
   WORKDIR /app

   # Copy package-related files first to leverage Docker's caching mechanism
   COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./

   # Install project dependencies with frozen lockfile for reproducible builds
   RUN --mount=type=cache,target=/root/.npm \
       --mount=type=cache,target=/usr/local/share/.cache/yarn \
       --mount=type=cache,target=/root/.local/share/pnpm/store \
     if [ -f package-lock.json ]; then \
       npm ci --no-audit --no-fund; \
     elif [ -f yarn.lock ]; then \
       corepack enable yarn && yarn install --frozen-lockfile --production=false; \
     elif [ -f pnpm-lock.yaml ]; then \
       corepack enable pnpm && pnpm install --frozen-lockfile; \
     else \
       echo "No lockfile found." && exit 1; \
     fi

   # ============================================
   # Stage 2: Build Next.js application in standalone mode
   # ============================================

   FROM dhi.io/node:24-alpine3.22-dev AS builder

   # Set working directory
   WORKDIR /app

   # Copy project dependencies from dependencies stage
   COPY --from=dependencies /app/node_modules ./node_modules

   # Copy application source code
   COPY . .

   ENV NODE_ENV=production

   # Next.js collects completely anonymous telemetry data about general usage.
   # Learn more here: https://nextjs.org/telemetry
   # Uncomment the following line in case you want to disable telemetry during the build.
   # ENV NEXT_TELEMETRY_DISABLED=1

   # Build Next.js application
   # If you want to speed up Docker rebuilds, you can cache the build artifacts
   # by adding: --mount=type=cache,target=/app/.next/cache
   # This caches the .next/cache directory across builds, but it also prevents
   # .next/cache/fetch-cache from being included in the final image, meaning
   # cached fetch responses from the build won't be available at runtime.
   RUN if [ -f package-lock.json ]; then \
       npm run build; \
     elif [ -f yarn.lock ]; then \
       corepack enable yarn && yarn build; \
     elif [ -f pnpm-lock.yaml ]; then \
       corepack enable pnpm && pnpm build; \
     else \
       echo "No lockfile found." && exit 1; \
     fi

   # ============================================
   # Stage 3: Run Next.js application
   # ============================================

   FROM dhi.io/node:24-alpine3.22-dev AS runner

   # Set working directory
   WORKDIR /app

   # Set production environment variables
   ENV NODE_ENV=production
   ENV PORT=3000
   ENV HOSTNAME="0.0.0.0"

   # Next.js collects completely anonymous telemetry data about general usage.
   # Learn more here: https://nextjs.org/telemetry
   # Uncomment the following line in case you want to disable telemetry during the run time.
   # ENV NEXT_TELEMETRY_DISABLED=1

   # Copy production assets
   COPY --from=builder --chown=node:node /app/public ./public

   # Set the correct permission for prerender cache
   RUN mkdir .next
   RUN chown node:node .next

   # Automatically leverage output traces to reduce image size
   # https://nextjs.org/docs/advanced-features/output-file-tracing
   COPY --from=builder --chown=node:node /app/.next/standalone ./
   COPY --from=builder --chown=node:node /app/.next/static ./.next/static

   # If you want to persist the fetch cache generated during the build so that
   # cached responses are available immediately on startup, uncomment this line:
   # COPY --from=builder --chown=node:node /app/.next/cache ./.next/cache

   # Switch to non-root user for security best practices
   USER node

   # Expose port 3000 to allow HTTP traffic
   EXPOSE 3000

   # Start Next.js standalone server
   CMD ["node", "server.js"]
   ```

Create a file named `Dockerfile` with the following contents (uses `node`):

```dockerfile
  # ============================================
  # Stage 1: Dependencies Installation Stage
  # ============================================

  ARG NODE_VERSION=24.14.0-slim

  FROM node:${NODE_VERSION} AS dependencies

  # Set working directory
  WORKDIR /app

  # Copy package-related files first to leverage Docker's caching mechanism
  COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./

  # Install project dependencies with frozen lockfile for reproducible builds
  RUN --mount=type=cache,target=/root/.npm \
      --mount=type=cache,target=/usr/local/share/.cache/yarn \
      --mount=type=cache,target=/root/.local/share/pnpm/store \
    if [ -f package-lock.json ]; then \
      npm ci --no-audit --no-fund; \
    elif [ -f yarn.lock ]; then \
      corepack enable yarn && yarn install --frozen-lockfile --production=false; \
    elif [ -f pnpm-lock.yaml ]; then \
      corepack enable pnpm && pnpm install --frozen-lockfile; \
    else \
      echo "No lockfile found." && exit 1; \
    fi

  # ============================================
  # Stage 2: Build Next.js application in standalone mode
  # ============================================

  FROM node:${NODE_VERSION} AS builder

  # Set working directory
  WORKDIR /app

  # Copy project dependencies from dependencies stage
  COPY --from=dependencies /app/node_modules ./node_modules

  # Copy application source code
  COPY . .

  ENV NODE_ENV=production

  # Next.js collects completely anonymous telemetry data about general usage.
  # Learn more here: https://nextjs.org/telemetry
  # Uncomment the following line in case you want to disable telemetry during the build.
  # ENV NEXT_TELEMETRY_DISABLED=1

  # Build Next.js application
  # If you want to speed up Docker rebuilds, you can cache the build artifacts
  # by adding: --mount=type=cache,target=/app/.next/cache
  # This caches the .next/cache directory across builds, but it also prevents
  # .next/cache/fetch-cache from being included in the final image, meaning
  # cached fetch responses from the build won't be available at runtime.
  RUN if [ -f package-lock.json ]; then \
      npm run build; \
    elif [ -f yarn.lock ]; then \
      corepack enable yarn && yarn build; \
    elif [ -f pnpm-lock.yaml ]; then \
      corepack enable pnpm && pnpm build; \
    else \
      echo "No lockfile found." && exit 1; \
    fi

  # ============================================
  # Stage 3: Run Next.js application
  # ============================================

  FROM node:${NODE_VERSION} AS runner

  # Set working directory
  WORKDIR /app

  # Set production environment variables
  ENV NODE_ENV=production
  ENV PORT=3000
  ENV HOSTNAME="0.0.0.0"

  # Next.js collects completely anonymous telemetry data about general usage.
  # Learn more here: https://nextjs.org/telemetry
  # Uncomment the following line in case you want to disable telemetry during the run time.
  # ENV NEXT_TELEMETRY_DISABLED=1

  # Copy production assets
  COPY --from=builder --chown=node:node /app/public ./public

  # Set the correct permission for prerender cache
  RUN mkdir .next
  RUN chown node:node .next

  # Automatically leverage output traces to reduce image size
  # https://nextjs.org/docs/advanced-features/output-file-tracing
  COPY --from=builder --chown=node:node /app/.next/standalone ./
  COPY --from=builder --chown=node:node /app/.next/static ./.next/static

  # If you want to persist the fetch cache generated during the build so that
  # cached responses are available immediately on startup, uncomment this line:
  # COPY --from=builder --chown=node:node /app/.next/cache ./.next/cache

  # Switch to non-root user for security best practices
  USER node

  # Expose port 3000 to allow HTTP traffic
  EXPOSE 3000

  # Start Next.js standalone server
  CMD ["node", "server.js"]
```

> Note
>
> This Dockerfile uses three stages: `dependencies`, `builder`, and `runner`. The final image runs `node server.js` and listens on port 3000.

***

#### [1.2 Next.js with export output](#12-nextjs-with-export-output)

Output export (`output: "export"`) makes Next.js build a fully static site at build time. It generates HTML, CSS, and JavaScript into an `out` directory that can be served by any static host or CDN—no Node.js server at runtime. Use this when you don't need server-side rendering or API routes. For details, see the [Next.js output configuration documentation](https://nextjs.org/docs/app/api-reference/config/next-config-js/output).

Configure Next.js — Open `next.config.ts` in your project root and add the following code:

```ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
  trailingSlash: true,
  images: {
    unoptimized: true,
  },
};

export default nextConfig;
```

Choose either a Docker Hardened Image or the Docker Official Image, then create a `Dockerfile` using the content from the selected tab below.

Docker Hardened Images (DHIs) are available for Node.js and Nginx in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog). For more information, see the [DHI quickstart](/dhi/get-started/) guide.

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Pull the Node.js DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/node:24-alpine3.22-dev
   ```

3. Pull the Nginx DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/nginx:1.28.0-alpine3.21-dev
   ```

4. Create a file named `Dockerfile` with the following contents. The `FROM` instructions use Docker Hardened Images: `dhi.io/node:24-alpine3.22-dev` and `dhi.io/nginx:1.28.0-alpine3.21-dev`. Check the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog) for the latest versions and update the image tags as needed for security and compatibility.

   ```dockerfile
   # ============================================
   # Stage 1: Dependencies Installation Stage
   # ============================================

   # IMPORTANT: Docker Hardened Image (DHI) Version Maintenance
   # This Dockerfile uses dhi.io/node and dhi.io/nginx. Regularly validate and update to the latest DHI versions in the catalog for security and compatibility.

   FROM dhi.io/node:24-alpine3.22-dev AS dependencies

   # Set the working directory
   WORKDIR /app

   # Copy package-related files first to leverage Docker's caching mechanism
   COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./

   # Install project dependencies with frozen lockfile for reproducible builds
   RUN --mount=type=cache,target=/root/.npm \
       --mount=type=cache,target=/usr/local/share/.cache/yarn \
       --mount=type=cache,target=/root/.local/share/pnpm/store \
     if [ -f package-lock.json ]; then \
       npm ci --no-audit --no-fund; \
     elif [ -f yarn.lock ]; then \
       corepack enable yarn && yarn install --frozen-lockfile --production=false; \
     elif [ -f pnpm-lock.yaml ]; then \
       corepack enable pnpm && pnpm install --frozen-lockfile; \
     else \
       echo "No lockfile found." && exit 1; \
     fi

   # ============================================
   # Stage 2: Build Next.js Application
   # ============================================

   FROM dhi.io/node:24-alpine3.22-dev AS builder

   # Set the working directory
   WORKDIR /app

   # Copy project dependencies from dependencies stage
   COPY --from=dependencies /app/node_modules ./node_modules

   # Copy application source code
   COPY . .

   ENV NODE_ENV=production

   # Next.js collects completely anonymous telemetry data about general usage.
   # Learn more here: https://nextjs.org/telemetry
   # Uncomment the following line in case you want to disable telemetry during the build.
   # ENV NEXT_TELEMETRY_DISABLED=1

   # Build Next.js application
   RUN --mount=type=cache,target=/app/.next/cache \
     if [ -f package-lock.json ]; then \
       npm run build; \
     elif [ -f yarn.lock ]; then \
       corepack enable yarn && yarn build; \
     elif [ -f pnpm-lock.yaml ]; then \
       corepack enable pnpm && pnpm build; \
     else \
       echo "No lockfile found." && exit 1; \
     fi

   # =========================================
   # Stage 3: Serve Static Files with Nginx
   # =========================================

   FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner

   # Set the working directory
   WORKDIR /app

   # Next.js collects completely anonymous telemetry data about general usage.
   # Learn more here: https://nextjs.org/telemetry
   # Uncomment the following line in case you want to disable telemetry during the run time.
   # ENV NEXT_TELEMETRY_DISABLED=1

   # Copy custom Nginx config
   COPY nginx.conf /etc/nginx/nginx.conf

   # Copy the static build output from the build stage to Nginx's default HTML serving directory
   COPY --chown=nginx:nginx --from=builder /app/out /usr/share/nginx/html

   # Non-root user for security best practices
   USER nginx

   # Expose port 8080 to allow HTTP traffic
   EXPOSE 8080

   # Start Nginx directly with custom config
   ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"]
   CMD ["-g", "daemon off;"]
   ```

Create a file named `Dockerfile` with the following contents (uses `node` and `nginxinc/nginx-unprivileged`):

```dockerfile
# ============================================
# Stage 1: Dependencies Installation Stage
# ============================================

ARG NODE_VERSION=24.14.0-slim
ARG NGINXINC_IMAGE_TAG=alpine3.22

FROM node:${NODE_VERSION} AS dependencies

# Set the working directory
WORKDIR /app

# Copy package-related files first to leverage Docker's caching mechanism
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./

# Install project dependencies with frozen lockfile for reproducible builds
RUN --mount=type=cache,target=/root/.npm \
    --mount=type=cache,target=/usr/local/share/.cache/yarn \
    --mount=type=cache,target=/root/.local/share/pnpm/store \
  if [ -f package-lock.json ]; then \
    npm ci --no-audit --no-fund; \
  elif [ -f yarn.lock ]; then \
    corepack enable yarn && yarn install --frozen-lockfile --production=false; \
  elif [ -f pnpm-lock.yaml ]; then \
    corepack enable pnpm && pnpm install --frozen-lockfile; \
  else \
    echo "No lockfile found." && exit 1; \
  fi

# ============================================
# Stage 2: Build Next.js Application
# ============================================

FROM node:${NODE_VERSION} AS builder

# Set the working directory
WORKDIR /app

# Copy project dependencies from dependencies stage
COPY --from=dependencies /app/node_modules ./node_modules

# Copy application source code
COPY . .

ENV NODE_ENV=production

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry during the build.
# ENV NEXT_TELEMETRY_DISABLED=1

# Build Next.js application
RUN --mount=type=cache,target=/app/.next/cache \
  if [ -f package-lock.json ]; then \
    npm run build; \
  elif [ -f yarn.lock ]; then \
    corepack enable yarn && yarn build; \
  elif [ -f pnpm-lock.yaml ]; then \
    corepack enable pnpm && pnpm build; \
  else \
    echo "No lockfile found." && exit 1; \
  fi

# =========================================
# Stage 3: Serve Static Files with Nginx
# =========================================

FROM nginxinc/nginx-unprivileged:${NGINXINC_IMAGE_TAG} AS runner

# Set the working directory
WORKDIR /app

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry during the run time.
# ENV NEXT_TELEMETRY_DISABLED=1

# Copy custom Nginx config
COPY nginx.conf /etc/nginx/nginx.conf

# Copy the static build output from the build stage to Nginx's default HTML serving directory
COPY --from=builder /app/out /usr/share/nginx/html

# Non-root user for security best practices
USER nginx

# Expose port 8080 to allow HTTP traffic
EXPOSE 8080

# Start Nginx directly with custom config
ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"]
CMD ["-g", "daemon off;"]
```

> Note
>
> This guide uses [nginx-unprivileged](https://hub.docker.com/r/nginxinc/nginx-unprivileged) instead of the standard Nginx image to run as a non-root user, following security best practices.

1. Create `nginx.conf` (required for export output only) — Create a file named `nginx.conf` in the root of your project:

   ```nginx
   # Minimal Nginx config for static Next.js app
   worker_processes 1;

   # Store PID in /tmp (always writable)
   pid /tmp/nginx.pid;

   events {
       worker_connections 1024;
   }

   http {
       include       /etc/nginx/mime.types;
       default_type  application/octet-stream;

       # Disable logging to avoid permission issues
       access_log off;
       error_log  /dev/stderr;

       # Optimize static file serving
       sendfile        on;
       tcp_nopush      on;
       tcp_nodelay     on;
       keepalive_timeout  65;

       # Gzip compression
       gzip on;
       gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
       gzip_min_length 256;

       server {
           listen       8080;
           server_name  localhost;

           # Serve static files
           root /usr/share/nginx/html;
           index index.html;

           # Handle Next.js static export routing
           # See: https://nextjs.org/docs/app/guides/static-exports#deploying
           location / {
               try_files $uri $uri.html $uri/ =404;
           }

           # This is necessary when `trailingSlash: false` (default).
           # You can omit this when `trailingSlash: true` in next.config.
           # Handles nested routes like /blog/post -> /blog/post.html
           location ~ ^/(.+)/$ {
               rewrite ^/(.+)/$ /$1.html break;
           }

           # Serve Next.js static assets
           location ~ ^/_next/ {
               try_files $uri =404;
               expires 1y;
               add_header Cache-Control "public, immutable";
           }

           # Optional 404 handling
           error_page 404 /404.html;
           location = /404.html {
               internal;
           }
       }
   }
   ```

   > Note
   >
   > Export uses port 8080. For more details, see the [Next.js output configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/output) and [Nginx documentation](https://nginx.org/en/docs/).

### [Step 2: Create the compose.yaml file](#step-2-create-the-composeyaml-file)

Create a file named `compose.yaml` with the following contents:

compose.yaml

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 3000:3000
```

> Note
>
> If using export output (Nginx), change the port mapping to `8080:8080`.

### [Step 3: Create the .dockerignore file](#step-3-create-the-dockerignore-file)

The `.dockerignore` file tells Docker which files and folders to exclude when building the image.

> Note
>
> This helps:
>
> * Reduce image size
> * Speed up the build process
> * Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image.
>
> To learn more, visit the [.dockerignore reference](https://docs.docker.com/reference/dockerfile/#dockerignore-file).

Create a file named `.dockerignore` with the following contents:

```dockerignore
# Dependencies (installed inside the image, never copy from host)
node_modules/
.pnp/
.pnp.js
.pnpm-store/

# Next.js build output (generated during the image build)
.next/
out/
dist/
build/
.vercel/

# Testing (not needed in the production image)
coverage/
.nyc_output/
__tests__/
__mocks__/
jest/
cypress/
playwright-report/
test-results/
.vitest/

# Environment files (avoid leaking secrets into the build context)
.env
.env*
.env.local
.env.development.local
.env.test.local
.env.production.local

# Debug and log files
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*
*.log

# IDE and editor files
.vscode/
.idea/
.cursor/
.cursorrules
.copilot/
*.swp
*.swo
*~

# Git
.git/
.gitignore
.gitattributes

# Docker files (reduce build context; not needed inside the image)
Dockerfile*
.dockerignore
docker-compose*.yml
compose*.yaml

# Documentation (not needed in the image)
*.md
docs/

# CI/CD (not needed in the image)
.github/
.gitlab-ci.yml
.travis.yml
.circleci/
Jenkinsfile

# TypeScript and build metadata
*.tsbuildinfo

# Cache and temporary directories
.cache/
.parcel-cache/
.eslintcache
.stylelintcache
.turbo/
.tmp/
.temp/

# Sensitive or dev-only config (optional; omit if your build needs these)
.pem
.editorconfig
.prettierrc*
.eslintrc*
.stylelintrc*
.babelrc*
*.iml

# OS-specific files
.DS_Store
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
Desktop.ini
```

### [Step 4: Build the Next.js application image](#step-4-build-the-nextjs-application-image)

With your custom configuration in place, you're now ready to build the Docker image. Use the Dockerfile you created in Step 1 (standalone or export).

The setup includes:

* Multi-stage builds for optimized image size
* Standalone: Node.js server on port 3000; Export: Nginx serving static files on port 8080
* Non-root user for enhanced security
* Proper file permissions and ownership

After completing the previous steps, your project directory should contain at least the following files (export also requires `nginx.conf`):

```text
├── docker-nextjs-sample/
│ ├── Dockerfile
│ ├── .dockerignore
│ ├── compose.yaml
│ └── next.config.ts
```

Now that your Dockerfile is configured, you can build the Docker image for your Next.js application.

> Note
>
> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)).

Run the following command from the root of your project:

```console
$ docker build --tag nextjs-sample .
```

What this command does:

* Uses the Dockerfile in the current directory (.)
* Packages the application and its dependencies into a Docker image
* Tags the image as nextjs-sample so you can reference it later

### [Step 5: View local images](#step-5-view-local-images)

After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](https://docs.docker.com/desktop/use-desktop/images/). Since you're already working in the terminal, let's use the Docker CLI.

To list all locally available Docker images, run the following command:

```console
$ docker images
```

Example Output:

```shell
REPOSITORY                TAG               IMAGE ID       CREATED         SIZE
nextjs-sample             latest            8c5fc80f098e   14 seconds ago   130MB
```

This output provides key details about your images:

* Repository – The name assigned to the image.
* Tag – A version label that helps identify different builds (e.g., latest).
* Image ID – A unique identifier for the image.
* Created – The timestamp indicating when the image was built.
* Size – The total disk space used by the image.

If the build was successful, you should see `nextjs-sample` image listed.

***

## [Run the containerized application](#run-the-containerized-application)

In the previous step, you created a Dockerfile for your Next.js application and built a Docker image using the docker build command. Now it's time to run that image in a container and verify that your application works as expected.

Run the following command in a terminal. Use the port that matches your setup: standalone uses port 3000, export uses port 8080.

```console
$ docker run -p 3000:3000 nextjs-sample
```

For export output, use port 8080 instead:

```console
$ docker run -p 8080:8080 nextjs-sample
```

Open a browser and view the application: <http://localhost:3000> for standalone or <http://localhost:8080> for export. You should see your Next.js web application.

Press `ctrl+c` in the terminal to stop your application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option and `--name` to give the container a name so you can stop it later:

```console
$ docker run -d -p 3000:3000 --name nextjs-app nextjs-sample
```

For export output, use port 8080:

```console
$ docker run -d -p 8080:8080 --name nextjs-app nextjs-sample
```

Open a browser and view the application: <http://localhost:3000> for standalone or <http://localhost:8080> for export. You should see your web application.

To confirm that the container is running, use the `docker ps` command:

```console
$ docker ps
```

This will list all active containers along with their ports, names, and status. Look for a container exposing port 3000 (standalone) or 8080 (export).

Example Output:

```shell
CONTAINER ID   IMAGE           COMMAND                  CREATED             STATUS             PORTS                    NAMES
f49b74736a9d   nextjs-sample   "node server.js"         About a minute ago   Up About a minute   0.0.0.0:3000->3000/tcp nextjs-app
```

To stop the application, run:

```console
$ docker stop nextjs-app
```

> Note
>
> For more information about running containers, see the [`docker run` CLI reference](/reference/cli/docker/container/run/) and the [`docker stop` CLI reference](/reference/cli/docker/container/stop/).

***

## [Summary](#summary)

In this guide, you learned how to containerize, build, and run a Next.js application using Docker. By following best practices, you created a secure, optimized, and production-ready setup.

What you accomplished:

* Configured Next.js for either standalone output (Node.js server) or export output (static files with Nginx).
* Added a multi-stage Dockerfile for your chosen approach: standalone (port 3000) or export (port 8080, with `nginx.conf`).
* Created a `.dockerignore` file to exclude unnecessary files and keep the image clean and efficient.
* Built your Docker image using `docker build`.
* Ran the container using `docker run` with the image name `nextjs-sample`, both in the foreground and in detached mode.
* Verified that the app was running by visiting <http://localhost:3000> (standalone) or <http://localhost:8080> (export).
* Learned how to stop the containerized application using `docker stop nextjs-app`.

You now have a fully containerized Next.js application, running in a Docker container, and ready for deployment across any environment with confidence and consistency.

***

## [Related resources](#related-resources)

Explore official references and best practices to sharpen your Docker workflow:

* [Multi-stage builds](/build/building/multi-stage/) – Learn how to separate build and runtime stages.
* [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles.
* [Build context in Docker](/build/concepts/context/) – Learn how context affects image builds.
* [Next.js output configuration](https://nextjs.org/docs/app/api-reference/config/next-config-js/output) – Learn about Next.js production optimization (standalone and export).
* [Next.js with Docker (standalone)](https://github.com/vercel/next.js/tree/canary/examples/with-docker) – Official Next.js example: standalone output with Node.js.
* [Next.js with Docker (export)](https://github.com/vercel/next.js/tree/canary/examples/with-docker-export-output) – Official Next.js example: static export with Nginx or serve.
* [`docker build` CLI reference](/reference/cli/docker/image/build/) – Build Docker images from a Dockerfile.
* [`docker images` CLI reference](/reference/cli/docker/image/ls/) – Manage and inspect local Docker images.
* [`docker run` CLI reference](/reference/cli/docker/container/run/) – Run a command in a new container.
* [`docker stop` CLI reference](/reference/cli/docker/container/stop/) – Stop one or more running containers.

***

## [Next steps](#next-steps)

With your Next.js application now containerized, you're ready to move on to the next step.

In the next section, you'll learn how to develop your application using Docker containers, enabling a consistent, isolated, and reproducible development environment across any machine.

[Use containers for Next.js development »](https://docs.docker.com/guides/nextjs/develop/)

----
url: https://docs.docker.com/reference/cli/docker/sandbox/run/
----

# docker sandbox run

***

| Description | Run an agent in a sandbox                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| Usage       | `docker sandbox run SANDBOX [-- AGENT_ARGS...] \| AGENT [WORKSPACE] [EXTRA_WORKSPACE...] [-- AGENT_ARGS...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Run an agent in a sandbox. Create the sandbox if it does not exist.

Pass agent arguments after the "--" separator. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Examples:

# [Create and run a sandbox with claude in current directory](#create-and-run-a-sandbox-with-claude-in-current-directory)

docker sandbox run claude

# [Create and run a sandbox with claude in current directory (explicit)](#create-and-run-a-sandbox-with-claude-in-current-directory-explicit)

docker sandbox run claude .

# [Create and run with additional workspaces (read-only)](#create-and-run-with-additional-workspaces-read-only)

docker sandbox run claude . /path/to/docs:ro

# [Run an existing sandbox](#run-an-existing-sandbox)

docker sandbox run existing-sandbox

# [Run a sandbox with agent arguments](#run-a-sandbox-with-agent-arguments)

docker sandbox run claude -- --continue

## [Options](#options)

| Option                        | Default   | Description                                                                                                                        |
| ----------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [`--name`](#name)             |           | Name for the sandbox (default: -)                                                                                                  |
| `--pull-template`             | `missing` | Template image pull policy: always (always pull from registry), missing (pull only if not cached), never (use only cached images)  |
| [`-t, --template`](#template) |           | Container image to use for the sandbox (default: agent-specific image)                                                             |

## [Examples](#examples)

### [Create and run Claude in the current directory](#create-and-run-claude-in-the-current-directory)

```console
$ docker sandbox run claude .
```

### [Run an existing sandbox](#run-an-existing-sandbox)

```console
$ docker sandbox run my-sandbox
```

### [Create and run with a specific workspace](#create-and-run-with-a-specific-workspace)

```console
$ docker sandbox run claude ~/projects/my-app
```

The workspace directory is mounted at the same absolute path inside the sandbox.

### [Name the sandbox (--name)](#name)

```text
--name NAME
```

Assign a custom name when creating a sandbox:

```console
$ docker sandbox run --name my-project claude .
```

### [Use a custom base image (-t, --template)](#template)

```text
--template IMAGE
```

Specify a custom container image when creating a sandbox:

```console
$ docker sandbox run --template python:3-alpine claude .
```

By default, each agent uses a pre-configured image. The `--template` option lets you substitute a different image.

### [Pass arguments to the agent](#pass-arguments-to-the-agent)

Use `--` to separate sandbox options from agent arguments:

```console
$ docker sandbox run claude . -- -p "What version are you running?"
```

----
url: https://docs.docker.com/reference/build-checks/workdir-relative-path/
----

# WorkdirRelativePath

***

Table of contents

***

## [Output](#output)

```text
Relative workdir 'app/src' can have unexpected results if the base image changes
```

## [Description](#description)

When specifying `WORKDIR` in a build stage, you can use an absolute path, like `/build`, or a relative path, like `./build`. Using a relative path means that the working directory is relative to whatever the previous working directory was. So if your base image uses `/usr/local/foo` as a working directory, and you specify a relative directory like `WORKDIR build`, the effective working directory becomes `/usr/local/foo/build`.

The `WorkdirRelativePath` build rule warns you if you use a `WORKDIR` with a relative path without first specifying an absolute path in the same Dockerfile. The rationale for this rule is that using a relative working directory for base image built externally is prone to breaking, since working directory may change upstream without warning, resulting in a completely different directory hierarchy for your build.

## [Examples](#examples)

❌ Bad: this assumes that `WORKDIR` in the base image is `/` (if that changes upstream, the `web` stage is broken).

```dockerfile
FROM nginx AS web
WORKDIR usr/share/nginx/html
COPY public .
```

✅ Good: a leading slash ensures that `WORKDIR` always ends up at the desired path.

```dockerfile
FROM nginx AS web
WORKDIR /usr/share/nginx/html
COPY public .
```

----
url: https://docs.docker.com/reference/samples/prometheus/
----

# Prometheus samples

| Name                                                                                             | Description                                                                        |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| [Prometheus / Grafana](https://github.com/docker/awesome-compose/tree/master/prometheus-grafana) | A sample Prometheus and Grafana stack.                                             |
| [aspnet-monitoring](https://github.com/dockersamples/aspnet-monitoring)                          | Monitoring ASP.NET Fx applications in Windows Docker containers, using Prometheus. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/offload/feedback/
----

***

Table of contents

***

There are several ways you can provide feedback on Docker Offload.

## [Quick survey](#quick-survey)

The fastest way to share your thoughts is to fill out this short [Docker Offload feedback survey](https://docker.qualtrics.com/jfe/form/SV_br8Ki4CCdqeIYl0). It only takes a minute and helps the Docker Team improve your experience.

## [In-product feedback](#in-product-feedback)

On each Docker Desktop Dashboard view, there is a **Give feedback** link. This opens a feedback form where you can share ideas directly with the Docker Team.

## [Report bugs or problems on GitHub](#report-bugs-or-problems-on-github)

To report bugs or problems, visit the [Docker Desktop issue tracker](https://github.com/docker/desktop-feedback).

----
url: https://docs.docker.com/guides/pgadmin/
----

[Visualizing your PostgreSQL databases with pgAdmin](https://docs.docker.com/guides/pgadmin/)

Explore how to add pgAdmin to your development stack and make it as easy as possible for your teammates to navigate through your PostgreSQL databases.

Databases

10 minutes

[« Back to all guides](/guides/)

# Visualizing your PostgreSQL databases with pgAdmin

***

Table of contents

***

Many applications use PostgreSQL databases in the application stack. However, not all developers are knowledgeable about navigating and working with PostgreSQL databases.

Fortunately, when you use containers in development, it is easy to add additional services to help with troubleshooting and debugging.

The [pgAdmin](https://www.pgadmin.org/) tool is a popular open-source tool designed to help administer and visualize PostgreSQL databases.

In this guide you will learn how to:

1. Add pgAdmin to your application stack
2. Configure pgAdmin to automatically connect to the development database

## [Adding pgAdmin to your stack](#adding-pgadmin-to-your-stack)

1. In your `compose.yaml` file, add the `pgadmin` service next to your existing `postgres` service:

   ```yaml
   services:
     postgres:
       image: postgres:18
       environment:
         POSTGRES_USER: postgres
         POSTGRES_PASSWORD: secret
         POSTGRES_DB: demo

     pgadmin:
       image: dpage/pgadmin4:9.8
       ports:
         - 5050:80
       environment:
         # Required by pgAdmin
         PGADMIN_DEFAULT_EMAIL: demo@example.com
         PGADMIN_DEFAULT_PASSWORD: secret

         # Don't require the user to login
         PGADMIN_CONFIG_SERVER_MODE: 'False'

         # Don't require a "master" password after logging in
         PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED: 'False'
   ```

2. Start the Compose stack with the following command:

   ```console
   $ docker compose up
   ```

   After the image is downloaded the container starts, you will see output that looks similar to the following indicating pgAdmin is ready:

   ```console
   pgadmin-1   | [2025-09-22 15:52:47 +0000] [1] [INFO] Starting gunicorn 23.0.0
   pgadmin-1   | [2025-09-22 15:52:47 +0000] [1] [INFO] Listening at: http://[::]:80 (1)
   pgadmin-1   | [2025-09-22 15:52:47 +0000] [1] [INFO] Using worker: gthread
   pgadmin-1   | [2025-09-22 15:52:47 +0000] [119] [INFO] Booting worker with pid: 119
   ```

3. Open pgAdmin by going to http\://localhost:5050.

4. Once in the admin panel, select the **Add New Server** link to define a new server. Enter the following details:

   * **General** tab:
     * **Name**: `postgres`

   * **Connection** tab:

     * **Host name/address**: `postgres`
     * **Username**: `postgres`
     * **Password**: `secret`
     * Enable the **Save password?** field

   > Important
   >
   > These connection details assume you are using the previous Compose file snippet. If you are using an existing Compose file, adjust the connection details as required. The **Host name/address** field should match the name of your postgres service.

5. Select the **Save** button to create the new database.

You now have pgAdmin setup and connected to your containerized database. Feel free to navigate around, view the tables, and explore your database.

## [Configuring pgAdmin to auto-connect to the database](#configuring-pgadmin-to-auto-connect-to-the-database)

Although you have pgAdmin running, it would be nice if you could simply open the app without needing to configure the database connection. Reducing the setup steps would be a great way to make it easier for teammates to get value from this tool.

Fortunately, there is an ability to auto-connect to the database.

> Warning
>
> In order to auto-connect, the database credentials are shared using plaintext files. During local development, this is often acceptable as local data is not real customer data. However, if you are using production or sensitive data, this practice is strongly discouraged.

1. First, you need to define the server itself, which pgAdmin does using a `servers.json` file.

   Add the following to your `compose.yaml` file to define a config file for the `servers.json` file:

   ```yaml
   configs:
     pgadmin-servers:
       content: |
         {
           "Servers": {
             "1": {
               "Name": "Local Postgres",
               "Group": "Servers",
               "Host": "postgres",
               "Port": 5432,
               "MaintenanceDB": "postgres",
               "Username": "postgres",
               "PassFile": "/config/pgpass"
             }
           }
         }
   ```

2. The `servers.json` file defines a `PassFile` field, which is a reference to a [postgreSQL password files](https://www.postgresql.org/docs/current/libpq-pgpass.html). These are often referred to as a pgpass file.

   Add the following config to your `compose.yaml` file to define a pgpass file:

   ```yaml
   config:
     pgadmin-pgpass:
       content: |
         postgres:5432:*:postgres:secret
   ```

   This will indicate any connection requests to `postgres:5432` using the username `postgres` should provide a password of `secret`.

3. In your `compose.yaml`, update the `pgadmin` service to inject the config files:

   ```yaml
   services:
     pgadmin:
       ...
       configs:
         - source: pgadmin-pgpass
           target: /config/pgpass
           uid: "5050"
           gid: "5050"
           mode: 0400
         - source: pgadmin-servers
           target: /pgadmin4/servers.json
           mode: 0444
   ```

4. Update the application stack by running `docker compose up` again:

   ```console
   $ docker compose up
   ```

5. Once the application is restarted, open your browser to http\://localhost:5050. You should be able to access the database without any logging in or configuration.

## [Conclusion](#conclusion)

Using containers makes it easy to not only run your application's dependencies, but also additional tools to help with troubleshooting and debugging.

When you add tools, think about the experience and possible friction your teammates might experience and how you might be able to remove it. In this case, you were able to take an extra step to add configuration to automatically configure and connect the databases, saving your teammates valuable time.

----
url: https://docs.docker.com/get-started/docker-concepts/building-images/writing-a-dockerfile/
----

# Writing a Dockerfile

***

Table of contents

***

## [Explanation](#explanation)

A Dockerfile is a text-based document that's used to create a container image. It provides instructions to the image builder on the commands to run, files to copy, startup command, and more.

As an example, the following Dockerfile would produce a ready-to-run Python application:

```dockerfile
FROM python:3.13
WORKDIR /usr/local/app

# Install the application dependencies
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

# Copy in the source code
COPY src ./src
EXPOSE 8080

# Setup an app user so the container doesn't run as the root user
RUN useradd app
USER app

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]
```

### [Common instructions](#common-instructions)

Some of the most common instructions in a `Dockerfile` include:

* `FROM <image>` - this specifies the base image that the build will extend.
* `WORKDIR <path>` - this instruction specifies the "working directory" or the path in the image where files will be copied and commands will be executed.
* `COPY <host-path> <image-path>` - this instruction tells the builder to copy files from the host and put them into the container image.
* `RUN <command>` - this instruction tells the builder to run the specified command.
* `ENV <name> <value>` - this instruction sets an environment variable that a running container will use.
* `EXPOSE <port-number>` - this instruction sets configuration on the image that indicates a port the image would like to expose.
* `USER <user-or-uid>` - this instruction sets the default user for all subsequent instructions.
* `CMD ["<command>", "<arg1>"]` - this instruction sets the default command a container using this image will run.

To read through all of the instructions or go into greater detail, check out the [Dockerfile reference](https://docs.docker.com/engine/reference/builder/).

## [Try it out](#try-it-out)

Just as you saw with the previous example, a Dockerfile typically follows these steps:

1. Determine your base image
2. Install application dependencies
3. Copy in any relevant source code and/or binaries
4. Configure the final image

In this quick hands-on guide, you'll write a Dockerfile that builds a simple Node.js application. If you're not familiar with JavaScript-based applications, don't worry. It isn't necessary for following along with this guide.

### [Set up](#set-up)

[Download this ZIP file](https://github.com/docker/getting-started-todo-app/archive/refs/heads/build-image-from-scratch.zip) and extract the contents into a directory on your machine.

If you'd rather not download a ZIP file, clone the <https://github.com/docker/getting-started-todo-app> project and checkout the `build-image-from-scratch` branch.

### [Creating the Dockerfile](#creating-the-dockerfile)

Now that you have the project, you’re ready to create the `Dockerfile`.

1. [Download and install](https://www.docker.com/products/docker-desktop/) Docker Desktop.

2. Examine the project.

   Explore the contents of `getting-started-todo-app/app/`. You'll notice that a `Dockerfile` already exists. It is a simple text file that you can open in any text or code editor.

3. Delete the existing `Dockerfile`.

   For this exercise, you'll pretend you're starting from scratch and will create a new `Dockerfile`.

4. Create a file named `Dockerfile` in the `getting-started-todo-app/app/` folder.

   > **Dockerfile file extensions**
   >
   > It's important to note that the `Dockerfile` has *no* file extension. Some editors will automatically add an extension to the file (or complain it doesn't have one).

5. In the `Dockerfile`, define your base image by adding the following line:

   ```dockerfile
   FROM node:22-alpine
   ```

6. Now, define the working directory by using the `WORKDIR` instruction. This will specify where future commands will run and the directory files will be copied inside the container image.

   ```dockerfile
   WORKDIR /app
   ```

7. Copy all of the files from your project on your machine into the container image by using the `COPY` instruction:

   ```dockerfile
   COPY . .
   ```

8. Install the app's dependencies by using the `yarn` CLI and package manager. To do so, run a command using the `RUN` instruction:

   ```dockerfile
   RUN yarn install --production
   ```

9. Finally, specify the default command to run by using the `CMD` instruction:

   ```dockerfile
   CMD ["node", "./src/index.js"]
   ```

   And with that, you should have the following Dockerfile:

   ```dockerfile
   FROM node:22-alpine
   WORKDIR /app
   COPY . .
   RUN yarn install --production
   CMD ["node", "./src/index.js"]
   ```

> **This Dockerfile isn't production-ready yet**
>
> It's important to note that this Dockerfile is *not* following all of the best practices yet (by design). It will build the app, but the builds won't be as fast, or the images as secure, as they could be.
>
> Keep reading to learn more about how to make the image maximize the build cache, run as a non-root user, and multi-stage builds.

## [Additional resources](#additional-resources)

To learn more about writing a Dockerfile, visit the following resources:

* [Dockerfile reference](/reference/dockerfile/)
* [Dockerfile best practices](/develop/develop-images/dockerfile_best-practices/)
* [Base images](/build/building/base-images/)
* [Gordon](/ai/gordon/) — Docker's AI assistant can generate a Dockerfile for your project. Ask Gordon to analyze your code and suggest a Dockerfile optimized for your language and framework.

## [Next steps](#next-steps)

Now that you have created a Dockerfile and learned the basics, it's time to learn about building, tagging, and pushing the images.

[Build, tag and publish the Image](https://docs.docker.com/get-started/docker-concepts/building-images/build-tag-and-publish-an-image/)

----
url: https://docs.docker.com/guides/testcontainers-java-service-configuration/exec-in-container/
----

# Execute commands inside containers

***

Table of contents

***

Some Docker containers provide CLI tools for performing actions. You can use `container.execInContainer(String...)` to run any available command inside a running container.

## [Example: Create an S3 bucket in LocalStack](#example-create-an-s3-bucket-in-localstack)

The [LocalStack](https://localstack.cloud/) module emulates AWS services. To test S3 file uploads, create a bucket before running tests:

```java
package com.testcontainers.demo;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.testcontainers.containers.localstack.LocalStackContainer.Service.S3;

import java.io.IOException;
import java.net.URI;
import java.util.List;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.localstack.LocalStackContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.utility.DockerImageName;
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.Bucket;

@Testcontainers
class LocalStackTest {

  static final String bucketName = "mybucket";

  @Container
  static LocalStackContainer localStack = new LocalStackContainer(
    DockerImageName.parse("localstack/localstack:3.4.0")
  );

  @BeforeAll
  static void beforeAll() throws IOException, InterruptedException {
    localStack.execInContainer("awslocal", "s3", "mb", "s3://" + bucketName);

    org.testcontainers.containers.Container.ExecResult execResult =
      localStack.execInContainer("awslocal", "s3", "ls");
    String stdout = execResult.getStdout();
    int exitCode = execResult.getExitCode();
    assertTrue(stdout.contains(bucketName));
    assertEquals(0, exitCode);
  }

  @Test
  void shouldListBuckets() {
    URI s3Endpoint = localStack.getEndpointOverride(S3);
    StaticCredentialsProvider credentialsProvider =
      StaticCredentialsProvider.create(
        AwsBasicCredentials.create(
          localStack.getAccessKey(),
          localStack.getSecretKey()
        )
      );
    S3Client s3 = S3Client
      .builder()
      .endpointOverride(s3Endpoint)
      .credentialsProvider(credentialsProvider)
      .region(Region.of(localStack.getRegion()))
      .build();

    List<String> s3Buckets = s3
      .listBuckets()
      .buckets()
      .stream()
      .map(Bucket::name)
      .toList();

    assertTrue(s3Buckets.contains(bucketName));
  }
}
```

The `execInContainer("awslocal", "s3", "mb", "s3://mybucket")` call runs the `awslocal` CLI tool (provided by the LocalStack image) to create an S3 bucket.

You can capture the output and exit code from any command:

```java
Container.ExecResult execResult =
    localStack.execInContainer("awslocal", "s3", "ls");
String stdout = execResult.getStdout();
int exitCode = execResult.getExitCode();
```

> Note
>
> The `withCopyFileToContainer()` and `execInContainer()` methods are inherited from `GenericContainer`, so they're available for all Testcontainers modules.

## [Summary](#summary)

* Use `withCopyFileToContainer()` to place initialization files inside containers before they start.
* Use `execInContainer()` to run commands inside running containers for setup tasks like creating buckets, topics, or queues.

## [Further reading](#further-reading)

* [Getting started with Testcontainers for Java](/guides/testcontainers-java-getting-started/)
* [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/)
* [Testcontainers LocalStack module](https://java.testcontainers.org/modules/localstack/)

----
url: https://docs.docker.com/reference/cli/docker/scout/attestation/list/
----

# docker scout attestation list

***

| Description                                                               | List attestations for image                   |
| ------------------------------------------------------------------------- | --------------------------------------------- |
| Usage                                                                     | `docker scout attestation list OPTIONS IMAGE` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker scout attest list`                    |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

The docker scout attestation list command lists attestations for images.

## [Options](#options)

| Option             | Default | Description                                                                                                                   |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--format`         | `list`  | Output format: - list: list of attestations of the image - json: json representation of the attestation list (default "json") |
| `--org`            |         | Namespace of the Docker organization                                                                                          |
| `-o, --output`     |         | Write the report to a file                                                                                                    |
| `--platform`       |         | Platform of image to analyze                                                                                                  |
| `--predicate-type` |         | Predicate-type for attestations                                                                                               |
| `--ref`            |         | Reference to use if the provided tarball contains multiple references. Can only be used with archive                          |

----
url: https://docs.docker.com/reference/samples/traefik/
----

# Traefik samples

| Name                                                                            | Description                               |
| ------------------------------------------------------------------------------- | ----------------------------------------- |
| [Traefik](https://github.com/docker/awesome-compose/tree/master/traefik-golang) | A sample Traefik proxy with a Go backend. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/guides/testcontainers-java-getting-started/write-tests/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Write tests with Testcontainers

***

Table of contents

***

You have the `CustomerService` implementation ready, but for testing you need a PostgreSQL database. You can use Testcontainers to spin up a Postgres database in a Docker container and run your tests against it.

## [Add Testcontainers dependencies](#add-testcontainers-dependencies)

Add the Testcontainers PostgreSQL module as a test dependency in `pom.xml`:

```xml
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers-postgresql</artifactId>
    <version>2.0.4</version>
    <scope>test</scope>
</dependency>
```

Since the application uses a Postgres database, the Testcontainers Postgres module provides a `PostgreSQLContainer` class for managing the container.

## [Write the test](#write-the-test)

Create `CustomerServiceTest.java` under `src/test/java`:

```java
package com.testcontainers.demo;

import static org.junit.jupiter.api.Assertions.assertEquals;

import java.util.List;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.testcontainers.postgresql.PostgreSQLContainer;

class CustomerServiceTest {

  static PostgreSQLContainer postgres = new PostgreSQLContainer(
    "postgres:16-alpine"
  );

  CustomerService customerService;

  @BeforeAll
  static void beforeAll() {
    postgres.start();
  }

  @AfterAll
  static void afterAll() {
    postgres.stop();
  }

  @BeforeEach
  void setUp() {
    DBConnectionProvider connectionProvider = new DBConnectionProvider(
      postgres.getJdbcUrl(),
      postgres.getUsername(),
      postgres.getPassword()
    );
    customerService = new CustomerService(connectionProvider);
  }

  @Test
  void shouldGetCustomers() {
    customerService.createCustomer(new Customer(1L, "George"));
    customerService.createCustomer(new Customer(2L, "John"));

    List<Customer> customers = customerService.getAllCustomers();
    assertEquals(2, customers.size());
  }
}
```

Here's what the test does:

* Declares a `PostgreSQLContainer` with the `postgres:16-alpine` Docker image.
* The `@BeforeAll` callback starts the Postgres container before any test methods run.
* The `@BeforeEach` callback creates a `DBConnectionProvider` using the JDBC connection parameters from the container, then creates a `CustomerService`. The `CustomerService` constructor creates the `customers` table if it doesn't exist.
* `shouldGetCustomers()` inserts 2 customer records, fetches all customers, and asserts the count.
* The `@AfterAll` callback stops the container after all test methods finish.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-getting-started/run-tests/)

----
url: https://docs.docker.com/desktop/setup/install/linux/
----

# Install Docker Desktop on Linux

***

Table of contents

***

> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250 employees or more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopLinuxInstall).

This page contains information about general system requirements, supported platforms, and instructions on how to install Docker Desktop for Linux.

> Important
>
> Docker Desktop on Linux runs a Virtual Machine (VM) which creates and uses a custom docker context, `desktop-linux`, on startup.
>
> This means images and containers deployed on the Linux Docker Engine (before installation) are not available in Docker Desktop for Linux.
>
> > Important
> >
> > For commercial use of Docker Engine obtained via Docker Desktop within larger enterprises (exceeding 250 employees or with annual revenue surpassing $10 million USD), a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopLinuxInstall) is required.
>
> Docker Desktop for Linux provides a user-friendly graphical interface that simplifies the management of containers and services. It includes Docker Engine as this is the core technology that powers Docker containers. Docker Desktop for Linux also comes with additional features like Docker Scout and Docker Extensions.
>
> ### [Installing Docker Desktop and Docker Engine](#installing-docker-desktop-and-docker-engine)
>
> Docker Desktop for Linux and Docker Engine can be installed side-by-side on the same machine. Docker Desktop for Linux stores containers and images in an isolated storage location within a VM and offers controls to restrict [its resources](https://docs.docker.com/desktop/settings-and-maintenance/settings/#resources). Using a dedicated storage location for Docker Desktop prevents it from interfering with a Docker Engine installation on the same machine.
>
> While it's possible to run both Docker Desktop and Docker Engine simultaneously, there may be situations where running both at the same time can cause issues. For example, when mapping network ports (`-p` / `--publish`) for containers, both Docker Desktop and Docker Engine may attempt to reserve the same port on your machine, which can lead to conflicts ("port already in use").
>
> We generally recommend stopping the Docker Engine while you're using Docker Desktop to prevent the Docker Engine from consuming resources and to prevent conflicts as described above.
>
> Use the following command to stop the Docker Engine service:
>
> ```console
> $ sudo systemctl stop docker docker.socket containerd
> ```
>
> Depending on your installation, the Docker Engine may be configured to automatically start as a system service when your machine starts. Use the following command to disable the Docker Engine service, and to prevent it from starting automatically:
>
> ```console
> $ sudo systemctl disable docker docker.socket containerd
> ```
>
> ### [Switching between Docker Desktop and Docker Engine](#switching-between-docker-desktop-and-docker-engine)
>
> The Docker CLI can be used to interact with multiple Docker Engines. For example, you can use the same Docker CLI to control a local Docker Engine and to control a remote Docker Engine instance running in the cloud. [Docker Contexts](https://docs.docker.com/engine/manage-resources/contexts/) allow you to switch between Docker Engines instances.
>
> When installing Docker Desktop, a dedicated "desktop-linux" context is created to interact with Docker Desktop. On startup, Docker Desktop automatically sets its own context (`desktop-linux`) as the current context. This means that subsequent Docker CLI commands target Docker Desktop. On shutdown, Docker Desktop resets the current context to the `default` context.
>
> Use the `docker context ls` command to view what contexts are available on your machine. The current context is indicated with an asterisk (`*`).
>
> ```console
> $ docker context ls
> NAME            DESCRIPTION                               DOCKER ENDPOINT                                  ...
> default *       Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                      ...
> desktop-linux                                             unix:///home/<user>/.docker/desktop/docker.sock  ...
> ```
>
> If you have both Docker Desktop and Docker Engine installed on the same machine, you can run the `docker context use` command to switch between the Docker Desktop and Docker Engine contexts. For example, use the "default" context to interact with the Docker Engine:
>
> ```console
> $ docker context use default
> default
> Current context is now "default"
> ```
>
> And use the `desktop-linux` context to interact with Docker Desktop:
>
> ```console
> $ docker context use desktop-linux
> desktop-linux
> Current context is now "desktop-linux"
> ```
>
> Refer to the [Docker Context documentation](https://docs.docker.com/engine/manage-resources/contexts/) for more details.

## [Supported platforms](#supported-platforms)

Docker provides `.deb` and `.rpm` packages for the following Linux distributions and architectures:

| Platform                                                                                     | x86\_64 / amd64 |
| -------------------------------------------------------------------------------------------- | --------------- |
| [Ubuntu](https://docs.docker.com/desktop/setup/install/linux/ubuntu/)                        | ✅               |
| [Debian](https://docs.docker.com/desktop/setup/install/linux/debian/)                        | ✅               |
| [Red Hat Enterprise Linux (RHEL)](https://docs.docker.com/desktop/setup/install/linux/rhel/) | ✅               |
| [Fedora](https://docs.docker.com/desktop/setup/install/linux/fedora/)                        | ✅               |

An experimental package is available for [Arch](https://docs.docker.com/desktop/setup/install/linux/archlinux/)-based distributions. Docker has not tested or verified the installation.

Docker supports Docker Desktop on the current and previous LTS releases of the aforementioned distributions, as well as the most recent version.

## [General system requirements](#general-system-requirements)

To install Docker Desktop successfully, your Linux host must meet the following general requirements:

* 64-bit kernel and CPU support for virtualization.
* KVM virtualization support. Follow the [KVM virtualization support instructions](#kvm-virtualization-support) to check if the KVM kernel modules are enabled and how to provide access to the KVM device.
* QEMU must be version 5.2 or later. We recommend upgrading to the latest version.
* systemd init system.
* GNOME, KDE, or MATE desktop environments are supported but others may work.
  * For many Linux distributions, the GNOME environment does not support tray icons. To add support for tray icons, you need to install a GNOME extension. For example, [AppIndicator](https://extensions.gnome.org/extension/615/appindicator-support/).
* At least 4 GB of RAM.
* Enable configuring ID mapping in user namespaces, see [File sharing](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/linuxfaqs/#how-do-i-enable-file-sharing). Note that for Docker Desktop version 4.35 and later, this is not required anymore.
* Recommended: [Initialize `pass`](https://docs.docker.com/desktop/setup/sign-in/#credentials-management-for-linux-users) for credentials management.

Docker Desktop for Linux runs a Virtual Machine (VM). For more information on why, see [Why Docker Desktop for Linux runs a VM](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/linuxfaqs/#why-does-docker-desktop-for-linux-run-a-vm).

> Note
>
> Docker does not provide support for running Docker Desktop for Linux in nested virtualization scenarios. We recommend that you run Docker Desktop for Linux natively on supported distributions.

### [KVM virtualization support](#kvm-virtualization-support)

Docker Desktop runs a VM that requires [KVM support](https://www.linux-kvm.org).

The `kvm` module should load automatically if the host has virtualization support. To load the module manually, run:

```console
$ modprobe kvm
```

Depending on the processor of the host machine, the corresponding module must be loaded:

```console
$ modprobe kvm_intel  # Intel processors

$ modprobe kvm_amd    # AMD processors
```

If the above commands fail, you can view the diagnostics by running:

```console
$ kvm-ok
```

To check if the KVM modules are enabled, run:

```console
$ lsmod | grep kvm
kvm_amd               167936  0
ccp                   126976  1 kvm_amd
kvm                  1089536  1 kvm_amd
irqbypass              16384  1 kvm
```

#### [Set up KVM device user permissions](#set-up-kvm-device-user-permissions)

To check ownership of `/dev/kvm`, run :

```console
$ ls -al /dev/kvm
```

Add your user to the kvm group in order to access the kvm device:

```console
$ sudo usermod -aG kvm $USER
```

Sign out and sign back in so that your group membership is re-evaluated.

## [Using Docker SDKs with Docker Desktop](#using-docker-sdks-with-docker-desktop)

Docker Desktop for Linux uses a per-user socket instead of the system-wide `/var/run/docker.sock`. Docker SDKs and tools that connect directly to the Docker daemon need the `DOCKER_HOST` environment variable set to connect to Docker Desktop. For configuration details, see [How do I use Docker SDKs with Docker Desktop for Linux?](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/linuxfaqs/#how-do-i-use-docker-sdks-with-docker-desktop-for-linux).

## [Where to go next](#where-to-go-next)

* Install Docker Desktop for Linux for your specific Linux distribution:

  * [Install on Ubuntu](https://docs.docker.com/desktop/setup/install/linux/ubuntu/)
  * [Install on Debian](https://docs.docker.com/desktop/setup/install/linux/debian/)
  * [Install on Red Hat Enterprise Linux (RHEL)](https://docs.docker.com/desktop/setup/install/linux/rhel/)
  * [Install on Fedora](https://docs.docker.com/desktop/setup/install/linux/fedora/)
  * [Install on Arch](https://docs.docker.com/desktop/setup/install/linux/archlinux/)

----
url: https://docs.docker.com/guides/admin-set-up/comms-and-info-gathering/
----

# Communication and information gathering

***

Table of contents

***

## [Communicate with your developers and IT teams](#communicate-with-your-developers-and-it-teams)

Before rolling out Docker Desktop across your organization, coordinate with key stakeholders to ensure a smooth transition.

### [Notify Docker Desktop users](#notify-docker-desktop-users)

You may already have Docker Desktop users within your company. Some steps in this onboarding process may affect how they interact with the platform.

Communicate early with users to inform them that:

* They'll be upgraded to a supported version of Docker Desktop as part of the subscription onboarding
* Settings will be reviewed and optimized for productivity
* They'll need to sign in to the company's Docker organization using their business email to access subscription benefits

### [Engage with your MDM team](#engage-with-your-mdm-team)

Device management solutions, such as Intune and Jamf, are commonly used for software distribution across enterprises. These tools are typically managed by a dedicated MDM team.

Engage with this team early in the process to:

* Understand their requirements and lead time for deploying changes
* Coordinate the distribution of configuration files

Several setup steps in this guide require JSON files, registry keys, or .plist files to be distributed to developer machines. Use MDM tools to deploy these configuration files and ensure their integrity.

## [Identify Docker organizations](#identify-docker-organizations)

Some companies may have more than one [Docker organization](https://docs.docker.com/admin/organization/) created. These organizations may have been created for specific purposes, or may not be needed anymore.

If you suspect your company has multiple Docker organizations:

* Survey your teams to see if they have their own organizations
* Contact your Docker Support to get a list of organizations with users whose emails match your domain name

## [Gather requirements](#gather-requirements)

[Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) lets you preset numerous configuration parameters for Docker Desktop.

Work with the following stakeholders to establish your company's baseline configuration:

* Docker organization owner
* Development lead
* Information security representative

Review these areas together:

* Security features and [enforcing sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) for Docker Desktop users
* Additional Docker products included in your subscriptions

To view the parameters that can be preset, see [Configure Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/#step-two-configure-the-settings-you-want-to-lock-in).

## [Optional: Meet with the Docker Implementation team](#optional-meet-with-the-docker-implementation-team)

The Docker Implementation team can help you set up your organization, configure SSO, enforce sign-in, and configure Docker Desktop.

To schedule a meeting, email <successteam@docker.com>.

[Finalize plans and begin setup »](https://docs.docker.com/guides/admin-set-up/finalize-plans-and-setup/)

----
url: https://docs.docker.com/guides/testcontainers-dotnet-getting-started/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

Run the tests:

```console
$ dotnet test
```

You can see in the output that Testcontainers pulls the Postgres Docker image from Docker Hub (if not already available locally), starts the container, and runs the test.

Writing an integration test using Testcontainers works like writing a unit test that you can run from your IDE. Your teammates can clone the project and run tests without installing Postgres on their machines.

## [Summary](#summary)

The Testcontainers for .NET library helps you write integration tests using the same type of database (Postgres) that you use in production, instead of mocks. Because you aren't using mocks and instead talk to real services, you're free to refactor code and still verify that the application works as expected.

In addition to Postgres, Testcontainers provides dedicated [modules](https://www.nuget.org/profiles/Testcontainers) for many SQL databases, NoSQL databases, messaging queues, and more.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testing an ASP.NET Core web app](https://testcontainers.com/guides/testing-an-aspnet-core-web-app/)

----
url: https://docs.docker.com/dhi/
----

# Docker Hardened Images

***

***

Docker Hardened Images (DHI) provide minimal, secure, and production-ready container images, Helm charts, and system packages maintained by Docker. Designed to reduce vulnerabilities and simplify compliance, DHI integrates easily into your existing Docker-based workflows with little to no retooling required.

DHI is available in the following three subscriptions.

| Feature                                                         | Community | Select    | Enterprise                     |
| --------------------------------------------------------------- | --------- | --------- | ------------------------------ |
| Hardened, minimal images                                        | ✅         | ✅         | ✅                              |
| Near-zero CVEs                                                  | ✅         | ✅         | ✅                              |
| Verifiable SBOMs & SLSA Build L3 provenance                     | ✅         | ✅         | ✅                              |
| Full, unsuppressed CVE visibility                               | ✅         | ✅         | ✅                              |
| Drop-in adoption, no workflow changes                           | ✅         | ✅         | ✅                              |
| Full catalog of open source images under Apache 2.0             | ✅         | ✅         | ✅                              |
| Built with Docker Hardened System Packages                      | ✅         | ✅         | ✅                              |
| Upstream cadence for Docker-released patches                    | ✅         | ✅         | ✅                              |
| FIPS/STIG variants                                              | ❌         | ✅         | ✅                              |
| Critical CVE fixes < 7 days with SLA-backed continuous patching | ❌         | ✅         | ✅                              |
| Customizations                                                  | ❌         | ✅ Up to 5 | ✅ Unlimited                    |
| Access to Hardened System Packages repository                   | ❌         | ❌         | ✅                              |
| Full catalog access available                                   | ❌         | ❌         | ✅                              |
| Extended Lifecycle Support add-on available                     | ❌         | ❌         | ✅ +5 years of hardened updates |

For pricing and more details, see the [Docker Hardened Images subscription comparison](https://www.docker.com/products/hardened-images/#compare).

Explore the sections below to get started with Docker Hardened Images, integrate them into your workflow, and learn what makes them secure and enterprise-ready.

### [Quickstart](/dhi/get-started/)

[Follow a step-by-step guide to explore and run a Docker Hardened Image.](/dhi/get-started/)

### [Explore](/dhi/explore/)

[Learn what Docker Hardened Images are, how they're built, and what sets them apart from typical base images.](/dhi/explore/)

### [Features](/dhi/features/)

[Discover the security, compliance, and enterprise-readiness features built into Docker Hardened Images.](/dhi/features/)

### [How-tos](/dhi/how-to/)

[Step-by-step guides for using, verifying, scanning, and migrating to Docker Hardened Images.](/dhi/how-to/)

### [Core concepts](/dhi/core-concepts/)

[Understand the secure supply chain principles that make Docker Hardened Images production-ready.](/dhi/core-concepts/)

### [Troubleshoot](/dhi/troubleshoot/)

[Resolve common issues with building, running, or debugging Docker Hardened Images.](/dhi/troubleshoot/)

### [Additional resources](/dhi/resources/)

[Guides, blog posts, Docker Hub catalog, GitHub repositories, and more.](/dhi/resources/)

----
url: https://docs.docker.com/guides/testcontainers-java-lifecycle/singleton-containers/
----

# Singleton containers pattern

***

Table of contents

***

As the number of test classes grows, starting containers for each class adds up. The singleton containers pattern starts all required containers once in a common base class and reuses them across all integration tests.

## [Define the base class](#define-the-base-class)

Create an abstract base class that starts the containers in a static initializer:

```java
package com.testcontainers.demo;

import org.testcontainers.postgresql.PostgreSQLContainer;
import org.testcontainers.kafka.ConfluentKafkaContainer;

public abstract class AbstractIntegrationTest {

   static PostgreSQLContainer postgres = new PostgreSQLContainer(
           "postgres:16-alpine");
   static ConfluentKafkaContainer kafka = new ConfluentKafkaContainer(
           "confluentinc/cp-kafka:7.8.0");

   static {
       postgres.start();
       kafka.start();
   }
}
```

The containers start once when the class loads and Testcontainers uses the [Ryuk container](https://github.com/testcontainers/moby-ryuk) to remove them after the JVM exits.

> Tip
>
> Instead of starting containers sequentially, start them in parallel using `Startables.deepStart(postgres, kafka).join();`

## [Extend the base class](#extend-the-base-class)

Each test class inherits from the base class and reuses the same containers:

```java
class ProductControllerTest extends AbstractIntegrationTest {

   ProductRepository productRepository;

   @BeforeEach
   void setUp() {
       productRepository = new ProductRepository(...);
       productRepository.deleteAll();
   }

   @Test
   void shouldGetAllProducts() {
       // test logic using the shared postgres container
   }
}
```

## [Avoid a common misconfiguration](#avoid-a-common-misconfiguration)

A common mistake is combining singleton containers with the `@Testcontainers` and `@Container` annotations:

```java
// DON'T DO THIS — containers will stop after each test class
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@Testcontainers
public abstract class AbstractIntegrationTest {

   @Container
   static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>(
           DockerImageName.parse("postgres:16-alpine"));

   @DynamicPropertySource
   static void configureProperties(DynamicPropertyRegistry registry) {
       registry.add("spring.datasource.url", postgres::getJdbcUrl);
       registry.add("spring.datasource.username", postgres::getUsername);
       registry.add("spring.datasource.password", postgres::getPassword);
   }
}
```

The `@Testcontainers` extension stops containers at the end of **each test class**. Subsequent test classes reuse the cached Spring context, but the containers are already stopped — causing connection failures.

Instead, use a static initializer or `@BeforeAll` to start the containers, without the `@Testcontainers` and `@Container` annotations.

## [Summary](#summary)

* Use **JUnit 5 lifecycle callbacks** (`@BeforeAll`/`@AfterAll`) for explicit control over container startup and shutdown.
* Use **extension annotations** (`@Testcontainers`/`@Container`) for less boilerplate in single test classes.
* Use the **singleton containers pattern** (static initializer in a base class) to share containers across multiple test classes.
* Don't mix singleton containers with `@Testcontainers`/`@Container` annotations.

## [Further reading](#further-reading)

* [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/)
* [Testcontainers singleton containers pattern](https://java.testcontainers.org/test_framework_integration/manual_lifecycle_control/#singleton-containers)
* [Testing a Spring Boot REST API with Testcontainers](/guides/testcontainers-java-spring-boot-rest-api/)

----
url: https://docs.docker.com/guides/testcontainers-nodejs-getting-started/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

Add the test script to `package.json` if it isn't there already:

```json
{
  "scripts": {
    "test": "jest"
  }
}
```

Then run the tests:

```console
$ npm test
```

You should see output like:

```text
 PASS  src/customer-repository.test.js
  Customer Repository
    ✓ should create and return multiple customers (5 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
```

To see what Testcontainers is doing under the hood — which containers it starts, what versions it uses — set the `DEBUG` environment variable:

```console
$ DEBUG=testcontainers* npm test
```

## [Summary](#summary)

The Testcontainers for Node.js library helps you write integration tests using the same type of database (Postgres) that you use in production, instead of mocks. Because you aren't using mocks and instead talk to real services, you're free to refactor code and still verify that the application works as expected.

In addition to PostgreSQL, Testcontainers provides dedicated [modules](https://github.com/testcontainers/testcontainers-node/tree/main/packages/modules) for many SQL databases, NoSQL databases, messaging queues, and more.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testcontainers for Node.js documentation](https://node.testcontainers.org)

----
url: https://docs.docker.com/reference/samples/angular/
----

# Angular samples

| Name                                                                        | Description                                             |
| --------------------------------------------------------------------------- | ------------------------------------------------------- |
| [Angular](https://github.com/docker/awesome-compose/tree/master/angular)    | A sample Angular application.                           |
| [dotnet-album-viewer](https://github.com/dockersamples/dotnet-album-viewer) | West Wind Album Viewer ASP.NET Core and Angular sample. |

----
url: https://docs.docker.com/reference/cli/docker/system/df/
----

# docker system df

***

| Description | Show docker disk usage       |
| ----------- | ---------------------------- |
| Usage       | `docker system df [OPTIONS]` |

## [Description](#description)

The `docker system df` command displays information regarding the amount of disk space used by the Docker daemon.

## [Options](#options)

| Option          | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--format`      |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-v, --verbose` |         | Show detailed information on space usage                                                                                                                                                                                                                                                                                                                                               |

## [Examples](#examples)

By default the command displays a summary of the data used:

```console
$ docker system df

TYPE                TOTAL               ACTIVE              SIZE                RECLAIMABLE
Images              5                   2                   16.43 MB            11.63 MB (70%)
Containers          2                   0                   212 B               212 B (100%)
Local Volumes       2                   1                   36 B                0 B (0%)
```

Use the `-v, --verbose` flag to get more detailed information:

```console
$ docker system df -v

Images space usage:

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE                SHARED SIZE         UNIQUE SIZE         CONTAINERS
my-curl             latest              b2789dd875bf        6 minutes ago       11 MB               11 MB               5 B                 0
my-jq               latest              ae67841be6d0        6 minutes ago       9.623 MB            8.991 MB            632.1 kB            0
<none>              <none>              a0971c4015c1        6 minutes ago       11 MB               11 MB               0 B                 0
alpine              latest              4e38e38c8ce0        9 weeks ago         4.799 MB            0 B                 4.799 MB            1
alpine              3.3                 47cf20d8c26c        9 weeks ago         4.797 MB            4.797 MB            0 B                 1

Containers space usage:

CONTAINER ID        IMAGE               COMMAND             LOCAL VOLUMES       SIZE                CREATED             STATUS                      NAMES
4a7f7eebae0f        alpine:latest       "sh"                1                   0 B                 16 minutes ago      Exited (0) 5 minutes ago    hopeful_yalow
f98f9c2aa1ea        alpine:3.3          "sh"                1                   212 B               16 minutes ago      Exited (0) 48 seconds ago   anon-vol

Local Volumes space usage:

NAME                                                               LINKS               SIZE
07c7bdf3e34ab76d921894c2b834f073721fccfbbcba792aa7648e3a7a664c2e   2                   36 B
my-named-vol                                                       0                   0 B
```

* `SHARED SIZE` is the amount of space that an image shares with another one (i.e. their common data)
* `UNIQUE SIZE` is the amount of space that's only used by a given image
* `SIZE` is the virtual size of the image, it's the sum of `SHARED SIZE` and `UNIQUE SIZE`

> Note
>
> Network information isn't shown, because it doesn't consume disk space.

----
url: https://docs.docker.com/guides/lab-agentic-apps/
----

[Lab: Building Agentic Apps with Docker](https://docs.docker.com/guides/lab-agentic-apps/)

Hands-on lab: Build agentic apps with Docker Model Runner, MCP Gateway, and Compose. Learn about models, tools, and agentic frameworks.

AI Labs

20 minutes

Resources:

* [Docker Model Runner docs](/ai/model-runner/)
* [Docker MCP Gateway docs](/ai/mcp-gateway/)
* [Labspace repository](https://github.com/dockersamples/labspace-agentic-apps-with-docker)

[« Back to all guides](/guides/)

# Lab: Building Agentic Apps with Docker

***

Table of contents

***

Get up and running with building agentic applications using Compose, Docker Model Runner, and the Docker MCP Gateway. This hands-on lab takes you from understanding AI models to building complete agentic applications.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-agentic-apps-with-docker up -d
   ```

   > Note
   >
   > This lab uses an AI model, which requires [the Docker Model Runner to be enabled](https://docs.docker.com/ai/model-runner/get-started/). The model may take some time to download.

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

This lab covers three core areas of agentic application development:

**Models**: What models are, how to interact with them, configuring Docker Model Runner in Compose, and writing code that connects to the Model Runner

**Tools**: Understanding tools and how they work, how MCP (Model Context Protocol) fits in, configuring the Docker MCP Gateway, and connecting to the MCP Gateway in code

**Code**: What agentic frameworks are, defining models and tools in a Compose file, and configuring your app to use those models and tools

## [Modules](#modules)

| # | Module                           | Description                                              |
| - | -------------------------------- | -------------------------------------------------------- |
| 1 | Introduction                     | Overview of agentic applications and the Docker AI stack |
| 2 | Understanding Model Interactions | Learn how to interact with AI models                     |
| 3 | The Docker Model Runner          | Configure and use Docker Model Runner with Compose       |
| 4 | Understanding Tools and MCP      | Deep dive into tools, tool calling, and MCP              |
| 5 | The Docker MCP Gateway           | Set up and configure the MCP Gateway                     |
| 6 | Putting It All Together          | Build a complete agentic application                     |
| 7 | Conclusion                       | Summary and next steps                                   |

----
url: https://docs.docker.com/reference/cli/docker/compose/up/
----

# docker compose up

***

| Description | Create and start containers                |
| ----------- | ------------------------------------------ |
| Usage       | `docker compose up [OPTIONS] [SERVICE...]` |

## [Description](#description)

Builds, (re)creates, starts, and attaches to containers for a service.

Unless they are already running, this command also starts any linked services.

The `docker compose up` command aggregates the output of each container (like `docker compose logs --follow` does). One can optionally select a subset of services to attach to using `--attach` flag, or exclude some services using `--no-attach` to prevent output to be flooded by some verbose services.

When the command exits, all containers are stopped. Running `docker compose up --detach` starts the containers in the background and leaves them running.

If there are existing containers for a service, and the service’s configuration or image was changed after the container’s creation, `docker compose up` picks up the changes by stopping and recreating the containers (preserving mounted volumes). To prevent Compose from picking up changes, use the `--no-recreate` flag.

If you want to force Compose to stop and recreate all containers, use the `--force-recreate` flag.

If the process encounters an error, the exit code for this command is `1`. If the process is interrupted using `SIGINT` (ctrl + C) or `SIGTERM`, the containers are stopped, and the exit code is `0`.

## [Options](#options)

| Option                         | Default  | Description                                                                                                                                           |
| ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--abort-on-container-exit`    |          | Stops all containers if any container was stopped. Incompatible with -d                                                                               |
| `--abort-on-container-failure` |          | Stops all containers if any container exited with failure. Incompatible with -d                                                                       |
| `--always-recreate-deps`       |          | Recreate dependent containers. Incompatible with --no-recreate.                                                                                       |
| `--attach`                     |          | Restrict attaching to the specified services. Incompatible with --attach-dependencies.                                                                |
| `--attach-dependencies`        |          | Automatically attach to log output of dependent services                                                                                              |
| `--build`                      |          | Build images before starting containers                                                                                                               |
| `-d, --detach`                 |          | Detached mode: Run containers in the background                                                                                                       |
| `--exit-code-from`             |          | Return the exit code of the selected service container. Implies --abort-on-container-exit                                                             |
| `--force-recreate`             |          | Recreate containers even if their configuration and image haven't changed                                                                             |
| `--menu`                       |          | Enable interactive shortcuts when running attached. Incompatible with --detach. Can also be enable/disable by setting COMPOSE\_MENU environment var.  |
| `--no-attach`                  |          | Do not attach (stream logs) to the specified services                                                                                                 |
| `--no-build`                   |          | Don't build an image, even if it's policy                                                                                                             |
| `--no-color`                   |          | Produce monochrome output                                                                                                                             |
| `--no-deps`                    |          | Don't start linked services                                                                                                                           |
| `--no-log-prefix`              |          | Don't print prefix in logs                                                                                                                            |
| `--no-recreate`                |          | If containers already exist, don't recreate them. Incompatible with --force-recreate.                                                                 |
| `--no-start`                   |          | Don't start the services after creating them                                                                                                          |
| `--pull`                       | `policy` | Pull image before running ("always"\|"missing"\|"never")                                                                                              |
| `--quiet-build`                |          | Suppress the build output                                                                                                                             |
| `--quiet-pull`                 |          | Pull without printing progress information                                                                                                            |
| `--remove-orphans`             |          | Remove containers for services not defined in the Compose file                                                                                        |
| `-V, --renew-anon-volumes`     |          | Recreate anonymous volumes instead of retrieving data from the previous containers                                                                    |
| `--scale`                      |          | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present.                                                         |
| `-t, --timeout`                |          | Use this timeout in seconds for container shutdown when attached or when containers are already running                                               |
| `--timestamps`                 |          | Show timestamps                                                                                                                                       |
| `--wait`                       |          | Wait for services to be running\|healthy. Implies detached mode.                                                                                      |
| `--wait-timeout`               |          | Maximum duration in seconds to wait for the project to be running\|healthy                                                                            |
| `-w, --watch`                  |          | Watch source code and rebuild/refresh containers when files are updated.                                                                              |
| `-y, --yes`                    |          | Assume "yes" as answer to all prompts and run non-interactively                                                                                       |

----
url: https://docs.docker.com/build/exporters/local-tar/
----

# Local and tar exporters

***

Table of contents

***

The `local` and `tar` exporters output the root filesystem of the build result into a local directory. They're useful for producing artifacts that aren't container images.

* `local` exports files and directories.
* `tar` exports the same, but bundles the export into a tarball.

## [Synopsis](#synopsis)

Build a container image using the `local` exporter:

```console
$ docker buildx build --output type=local[,parameters] .
$ docker buildx build --output type=tar[,parameters] .
```

The following table describes the available parameters:

| Parameter        | Type    | Default | Description                                                                       |
| ---------------- | ------- | ------- | --------------------------------------------------------------------------------- |
| `dest`           | String  |         | Path to copy files to                                                             |
| `platform-split` | Boolean | `true`  | `local` exporter only. Split multi-platform outputs into platform subdirectories. |

## [Multi-platform builds with local exporter](#multi-platform-builds-with-local-exporter)

The `platform-split` parameter controls how multi-platform build outputs are organized.

Consider this Dockerfile that creates platform-specific files:

```dockerfile
FROM busybox AS build
ARG TARGETOS
ARG TARGETARCH
RUN mkdir /out && echo foo > /out/hello-$TARGETOS-$TARGETARCH

FROM scratch
COPY --from=build /out /
```

### [Split by platform (default)](#split-by-platform-default)

By default, the local exporter creates a separate subdirectory for each platform:

```console
$ docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --output type=local,dest=./output \
  .
```

This produces the following directory structure:

```text
output/
├── linux_amd64/
│   └── hello-linux-amd64
└── linux_arm64/
    └── hello-linux-arm64
```

### [Merge all platforms](#merge-all-platforms)

To merge files from all platforms into the same directory, set `platform-split=false`:

```console
$ docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --output type=local,dest=./output,platform-split=false \
  .
```

This produces a flat directory structure:

```text
output/
├── hello-linux-amd64
└── hello-linux-arm64
```

Files from all platforms merge into a single directory. If multiple platforms produce files with identical names, the export fails with an error.

### [Single-platform builds](#single-platform-builds)

Single-platform builds export directly to the destination directory without creating a platform subdirectory:

```console
$ docker buildx build \
  --platform linux/amd64 \
  --output type=local,dest=./output \
  .
```

This produces:

```text
output/
└── hello-linux-amd64
```

To include the platform subdirectory even for single-platform builds, explicitly set `platform-split=true`:

```console
$ docker buildx build \
  --platform linux/amd64 \
  --output type=local,dest=./output,platform-split=true \
  .
```

This produces:

```text
output/
└── linux_amd64/
    └── hello-linux-amd64
```

## [Further reading](#further-reading)

For more information on the `local` or `tar` exporters, see the [BuildKit README](https://github.com/moby/buildkit/blob/master/README.md#local-directory).

----
url: https://docs.docker.com/reference/cli/docker/stack/services/
----

# docker stack services

***

| Description | List the services in the stack          |
| ----------- | --------------------------------------- |
| Usage       | `docker stack services [OPTIONS] STACK` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Lists the services that are running as part of the specified stack.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --filter`](#filter) |         | Filter output based on conditions provided                                                                                                                                                                                                                                                                                                                                             |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-q, --quiet`             |         | Only display IDs                                                                                                                                                                                                                                                                                                                                                                       |

## [Examples](#examples)

The following command shows all services in the `myapp` stack:

```console
$ docker stack services myapp

ID            NAME            REPLICAS  IMAGE                                                                          COMMAND
7be5ei6sqeye  myapp_web       1/1       nginx@sha256:23f809e7fd5952e7d5be065b4d3643fbbceccd349d537b62a123ef2201bc886f
dn7m7nhhfb9y  myapp_db        1/1       mysql@sha256:a9a5b559f8821fe73d58c3606c812d1c044868d42c63817fa5125fd9d8b7b539
```

### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`). Multiple filter flags are combined as an `OR` filter.

The following command shows both the `web` and `db` services:

```console
$ docker stack services --filter name=myapp_web --filter name=myapp_db myapp

ID            NAME            REPLICAS  IMAGE                                                                          COMMAND
7be5ei6sqeye  myapp_web       1/1       nginx@sha256:23f809e7fd5952e7d5be065b4d3643fbbceccd349d537b62a123ef2201bc886f
dn7m7nhhfb9y  myapp_db        1/1       mysql@sha256:a9a5b559f8821fe73d58c3606c812d1c044868d42c63817fa5125fd9d8b7b539
```

The currently supported filters are:

* id / ID (`--filter id=7be5ei6sqeye`, or `--filter ID=7be5ei6sqeye`)
* label (`--filter label=key=value`)
* mode (`--filter mode=replicated`, or `--filter mode=global`)
  * Swarm: not supported
* name (`--filter name=myapp_web`)
* node (`--filter node=mynode`)
  * Swarm: not supported
* service (`--filter service=web`)
  * Swarm: not supported

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints services output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder | Description                       |
| ----------- | --------------------------------- |
| `.ID`       | Service ID                        |
| `.Name`     | Service name                      |
| `.Mode`     | Service mode (replicated, global) |
| `.Replicas` | Service replicas                  |
| `.Image`    | Service image                     |

When using the `--format` option, the `stack services` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services:

```console
$ docker stack services --format "{{.ID}}: {{.Mode}} {{.Replicas}}"

0zmvwuiu3vue: replicated 10/10
fm6uf97exkul: global 5/5
```

To list all services in JSON format, use the `json` directive:

```console
$ docker stack services ls --format json
{"ID":"0axqbl293vwm","Image":"localstack/localstack:latest","Mode":"replicated","Name":"myapp_localstack","Ports":"*:4566-\u003e4566/tcp, *:8080-\u003e8080/tcp","Replicas":"0/1"}
{"ID":"384xvtzigz3p","Image":"redis:6.0.9-alpine3.12","Mode":"replicated","Name":"myapp_redis","Ports":"*:6379-\u003e6379/tcp","Replicas":"1/1"}
{"ID":"hyujct8cnjkk","Image":"postgres:13.2-alpine","Mode":"replicated","Name":"myapp_repos-db","Ports":"*:5432-\u003e5432/tcp","Replicas":"0/1"}
```

----
url: https://docs.docker.com/extensions/extensions-sdk/dev/usage/
----

***

***

The Extensions CLI is an extension development tool that is used to manage Docker extensions. Actions include install, list, remove, and validate extensions.

* `docker extension enable` turns on Docker extensions.
* `docker extension dev` commands for extension development.
* `docker extension disable` turns off Docker extensions.
* `docker extension init` creates a new Docker extension.
* `docker extension install` installs a Docker extension with the specified image.
* `docker extension ls` list installed Docker extensions.
* `docker extension rm` removes a Docker extension.
* `docker extension update` removes and re-installs a Docker extension.
* `docker extension validate` validates the extension metadata file against the JSON schema.

----
url: https://docs.docker.com/engine/install/raspberry-pi-os/
----

# Install Docker Engine on Raspberry Pi OS (32-bit / armhf)

***

Table of contents

***

> Warning
>
> **Raspberry Pi OS 32-bit (armhf) Deprecation**
>
> Docker Engine v28 will be the last major version to support Raspberry Pi OS 32-bit (armhf). Starting with Docker Engine v29, new major versions will no longer provide packages for Raspberry Pi OS 32-bit (armhf).
>
> **Migration options**
>
> * **64-bit ARM:** Install the Debian `arm64` packages (fully supported). See the [Debian installation instructions](https://docs.docker.com/engine/install/debian/).
> * **32-bit ARM (v7):** Install the Debian `armhf` packages (targets ARMv7 CPUs).
>
> **Note:** Older devices based on the ARMv6 architecture are no longer supported by official packages, including:
>
> * Raspberry Pi 1 (Model A/B/A+/B+)
> * Raspberry Pi Zero and Zero W

To get started with Docker Engine on Raspberry Pi OS, make sure you [meet the prerequisites](#prerequisites), and then follow the [installation steps](#installation-methods).

> Important
>
> This installation instruction refers to the 32-bit (armhf) version of Raspberry Pi OS. If you're using the 64-bit (arm64) version, follow the instructions for [Debian](https://docs.docker.com/engine/install/debian/).

## [Prerequisites](#prerequisites)

### [Firewall limitations](#firewall-limitations)

> Warning
>
> Before you install Docker, make sure you consider the following security implications and firewall incompatibilities.

* If you use ufw or firewalld to manage firewall settings, be aware that when you expose container ports using Docker, these ports bypass your firewall rules. For more information, refer to [Docker and ufw](https://docs.docker.com/engine/network/packet-filtering-firewalls/#docker-and-ufw).
* Docker is only compatible with `iptables-nft` and `iptables-legacy`. Firewall rules created with `nft` are not supported on a system with Docker installed. Make sure that any firewall rulesets you use are created with `iptables` or `ip6tables`, and that you add them to the `DOCKER-USER` chain, see [Packet filtering and firewalls](https://docs.docker.com/engine/network/packet-filtering-firewalls/).

### [OS requirements](#os-requirements)

To install Docker Engine, you need one of the following OS versions:

* 32-bit Raspberry Pi OS Bookworm 12 (stable)
* 32-bit Raspberry Pi OS Bullseye 11 (oldstable)

> Warning
>
> Docker Engine v28 is the last major version to support Raspberry Pi OS 32-bit (armhf). Starting with v29, no new packages will be provided for 32-bit Raspberry Pi OS.
>
> Migration options:
>
> * 64-bit ARM: use Debian `arm64` packages; see the [Debian installation instructions](https://docs.docker.com/engine/install/debian/).
> * 32-bit ARM (v7): use Debian `armhf` packages (targets ARMv7 CPUs).
>
> Note: ARMv6-based devices (Raspberry Pi 1 models and Raspberry Pi Zero/Zero W) are not supported by official packages.

```console
$ for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove $pkg; done
```

`apt-get` might report that you have none of these packages installed.

Images, containers, volumes, and networks stored in `/var/lib/docker/` aren't automatically removed when you uninstall Docker. If you want to start with a clean installation, and prefer to clean up any existing data, read the [uninstall Docker Engine](#uninstall-docker-engine) section.

## [Installation methods](#installation-methods)

You can install Docker Engine in different ways, depending on your needs:

* Docker Engine comes bundled with [Docker Desktop for Linux](https://docs.docker.com/desktop/setup/install/linux/). This is the easiest and quickest way to get started.

* Set up and install Docker Engine from [Docker's `apt` repository](#install-using-the-repository).

* [Install it manually](#install-from-a-package) and manage upgrades manually.

* Use a [convenience script](#install-using-the-convenience-script). Only recommended for testing and development environments.

Apache License, Version 2.0. See [LICENSE](https://github.com/moby/moby/blob/master/LICENSE) for the full license.

### [Install using the `apt` repository](#install-using-the-repository)

Before you install Docker Engine for the first time on a new host machine, you need to set up the Docker `apt` repository. Afterward, you can install and update Docker from the repository.

1. Set up Docker's `apt` repository.

   ```bash
   # Add Docker's official GPG key:
   sudo apt-get update
   sudo apt-get install ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/raspbian/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc

   # Add the repository to Apt sources:
   echo \
     "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/raspbian \
     $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
     sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   sudo apt-get update
   ```

2. Install the Docker packages.

   To install the latest version, run:

   ```console
   $ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   To install a specific version of Docker Engine, start by listing the available versions in the repository:

   ```console
   # List the available versions:
   $ apt-cache madison docker-ce | awk '{ print $3 }'

   5:29.5.2-1~raspbian.12~bookworm
   5:29.5.1-1~raspbian.12~bookworm
   ...
   ```

   Select the desired version and install:

   ```console
   $ VERSION_STRING=5:29.5.2-1~raspbian.12~bookworm
   $ sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   > Note
   >
   > After installation, verify that Docker is running:
   >
   > ```console
   > $ sudo systemctl status docker
   > ```
   >
   > If Docker is not running, start it manually:
   >
   > ```console
   > $ sudo systemctl start docker
   > ```

3. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

#### [Upgrade Docker Engine](#upgrade-docker-engine)

To upgrade Docker Engine, follow step 2 of the [installation instructions](#install-using-the-repository), choosing the new version you want to install.

### [Install from a package](#install-from-a-package)

If you can't use Docker's `apt` repository to install Docker Engine, you can download the `deb` file for your release and install it manually. You need to download a new file each time you want to upgrade Docker Engine.

1. Go to [`https://download.docker.com/linux/raspbian/dists/`](https://download.docker.com/linux/raspbian/dists/).

2. Select your Raspberry Pi OS version in the list.

   ```console
   $ sudo dpkg -i ./containerd.io_<version>_<arch>.deb \
     ./docker-ce_<version>_<arch>.deb \
     ./docker-ce-cli_<version>_<arch>.deb \
     ./docker-buildx-plugin_<version>_<arch>.deb \
     ./docker-compose-plugin_<version>_<arch>.deb
   ```

   > Note
   >
   > After installation, verify that Docker is running:
   >
   > ```console
   > $ sudo systemctl status docker
   > ```
   >
   > If Docker is not running, start it manually:
   >
   > ```console
   > $ sudo systemctl start docker
   > ```

6. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

> Tip
>
> Preview script steps before running. You can run the script with the `--dry-run` option to learn what steps the script will run when invoked:
>
> ```console
> $ curl -fsSL https://get.docker.com -o get-docker.sh
> $ sudo sh ./get-docker.sh --dry-run
> ```

This example downloads the script from <https://get.docker.com/> and runs it to install the latest stable release of Docker on Linux:

```console
$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh get-docker.sh
Executing docker install script, commit: 7cae5f8b0decc17d6571f9f52eb840fbc13b2737
<...>
```

You have now successfully installed and started Docker Engine. The `docker` service starts automatically on Debian based distributions. On `RPM` based distributions, such as CentOS, Fedora or RHEL, you need to start it manually using the appropriate `systemctl` or `service` command. As the message indicates, non-root users can't run Docker commands by default.

> **Use Docker as a non-privileged user, or install in rootless mode?**
>
> The installation script requires `root` or `sudo` privileges to install and use Docker. If you want to grant non-root users access to Docker, refer to the [post-installation steps for Linux](/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). You can also install Docker without `root` privileges, or configured to run in rootless mode. For instructions on running Docker in rootless mode, refer to [run the Docker daemon as a non-root user (rootless mode)](/engine/security/rootless/).

#### [Install pre-releases](#install-pre-releases)

Docker also provides a convenience script at <https://test.docker.com/> to install pre-releases of Docker on Linux. This script is equal to the script at `get.docker.com`, but configures your package manager to use the test channel of the Docker package repository. The test channel includes both stable and pre-releases (beta versions, release-candidates) of Docker. Use this script to get early access to new releases, and to evaluate them in a testing environment before they're released as stable.

To install the latest version of Docker on Linux from the test channel, run:

```console
$ curl -fsSL https://test.docker.com -o test-docker.sh
$ sudo sh test-docker.sh
```

#### [Upgrade Docker after using the convenience script](#upgrade-docker-after-using-the-convenience-script)

If you installed Docker using the convenience script, you should upgrade Docker using your package manager directly. There's no advantage to re-running the convenience script. Re-running it can cause issues if it attempts to re-install repositories which already exist on the host machine.

## [Uninstall Docker Engine](#uninstall-docker-engine)

1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages:

   ```console
   $ sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
   ```

2. Images, containers, volumes, or custom configuration files on your host aren't automatically removed. To delete all images, containers, and volumes:

   ```console
   $ sudo rm -rf /var/lib/docker
   $ sudo rm -rf /var/lib/containerd
   ```

3. Remove source list and keyrings

   ```console
   $ sudo rm /etc/apt/sources.list.d/docker.list
   $ sudo rm /etc/apt/keyrings/docker.asc
   ```

You have to delete any edited configuration files manually.

## [Next steps](#next-steps)

* Continue to [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/).

----
url: https://docs.docker.com/build/policies/testing/
----

# Test build policies

***

Table of contents

***

The [`docker buildx policy test`](/reference/cli/docker/buildx/policy/test/) command runs unit tests for build policies using OPA's [standard test framework](https://www.openpolicyagent.org/docs/policy-testing).

```console
$ docker buildx policy test <path>
```

This validates policy logic with mocked inputs.

For testing against real sources (actual image metadata, Git repositories), use [`docker buildx policy eval`](/reference/cli/docker/buildx/policy/eval/) instead. You can use the `eval --print` option to resolve input for a specific source for writing a test case.

## [Basic example](#basic-example)

Start with a simple policy that only allows `alpine` images:

Dockerfile.rego

```rego
package docker

default allow = false

allow if {
    input.image.repo == "alpine"
}

decision := {"allow": allow}
```

Create a test file with the `*_test.rego` suffix. Test functions must start with `test_`:

Dockerfile\_test.rego

```rego
package docker

test_alpine_allowed if {
    decision.allow with input as {"image": {"repo": "alpine"}}
}

test_ubuntu_denied if {
    not decision.allow with input as {"image": {"repo": "ubuntu"}}
}
```

Run the tests:

```console
$ docker buildx policy test .
test_alpine_allowed: PASS (allow=true)
test_ubuntu_denied: PASS (allow=false)
```

`PASS` indicates that the tests defined in `Dockerfile_test.rego` executed successfully and all assertions were satisfied.

## [Command options](#command-options)

Filter tests by name with `--run`:

```console
$ docker buildx policy test --run alpine .
test_alpine_allowed: PASS (allow=true)
```

Test policies with non-default filenames using `--filename`:

```console
$ docker buildx policy test --filename app.Dockerfile .
```

This loads `app.Dockerfile.rego` and runs `*_test.rego` files against it.

## [Test output](#test-output)

Passed tests show the allow status and any deny messages:

```console
test_alpine_allowed: PASS (allow=true)
test_ubuntu_denied: PASS (allow=false, deny_msg=only alpine images are allowed)
```

Failed tests show input, decision output, and missing fields:

```console
test_invalid: FAIL (allow=false)
input:
  {
    "image": {}
  }
decision:
  {
    "allow": false,
    "deny_msg": [
      "only alpine images are allowed"
    ]
  }
missing_input: input.image.repo
```

## [Test deny messages](#test-deny-messages)

To test custom error messages, capture the full decision result and assert on the `deny_msg` field.

For a policy with deny messages:

Dockerfile.rego

```rego
package docker

default allow = false

allow if {
    input.image.repo == "alpine"
}

deny_msg contains msg if {
    not allow
    msg := "only alpine images are allowed"
}

decision := {"allow": allow, "deny_msg": deny_msg}
```

Test the deny message:

Dockerfile\_test.rego

```rego
test_deny_message if {
    result := decision with input as {"image": {"repo": "ubuntu"}}
    not result.allow
    "only alpine images are allowed" in result.deny_msg
}
```

## [Test patterns](#test-patterns)

**Test environment-specific rules:**

```rego
test_production_requires_digest if {
    decision.allow with input as {
        "env": {"target": "production"},
        "image": {"isCanonical": true}
    }
}

test_development_allows_tags if {
    decision.allow with input as {
        "env": {"target": "development"},
        "image": {"isCanonical": false}
    }
}
```

**Test multiple registries:**

```rego
test_dockerhub_allowed if {
    decision.allow with input as {
        "image": {
            "ref": "docker.io/library/alpine",
            "host": "docker.io",
            "repo": "alpine"
        }
    }
}

test_ghcr_allowed if {
    decision.allow with input as {
        "image": {
            "ref": "ghcr.io/myorg/myapp",
            "host": "ghcr.io",
            "repo": "myorg/myapp"
        }
    }
}
```

For available input fields, see the [Input reference](https://docs.docker.com/build/policies/inputs/).

## [Organize test files](#organize-test-files)

The test runner discovers all `*_test.rego` files recursively:

```plaintext
build-policies/
├── Dockerfile.rego
├── Dockerfile_test.rego
└── tests/
    ├── registries_test.rego
    ├── signatures_test.rego
    └── environments_test.rego
```

Run all tests:

```console
$ docker buildx policy test .
```

Or test specific files:

```console
$ docker buildx policy test tests/registries_test.rego
```

----
url: https://docs.docker.com/guides/php/configure-ci-cd/
----

# Configure CI/CD for your PHP application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a PHP application](https://docs.docker.com/guides/php/containerize/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

   ```console
   $ git remote set-url origin https://github.com/your-username/your-repository.git
   ```

7. In your local repository on your machine, run the following command to rename the branch to main.

   ```console
   $ git branch -M main
   ```

8. Run the following commands to stage, commit, and then push your local repository to GitHub.

   ```console
   $ git add -A
   $ git commit -m "my first commit"
   $ git push -u origin main
   ```

## [Step two: Set up the workflow](#step-two-set-up-the-workflow)

Set up your GitHub Actions workflow for building, testing, and pushing the image to Docker Hub.

1. Go to your repository on GitHub and then select the **Actions** tab.

2. Select **set up a workflow yourself**.

   This takes you to a page for creating a new GitHub actions workflow file in your repository, under `.github/workflows/main.yml` by default.

3. In the editor window, copy and paste the following YAML configuration.

   ```yaml
   name: ci

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Login to Docker Hub
           uses: docker/login-action@v4
           with:
             username: ${{ vars.DOCKER_USERNAME }}
             password: ${{ secrets.DOCKERHUB_TOKEN }}

         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v4

         - name: Build and test
           uses: docker/build-push-action@v7
           with:
             target: test
             load: true

         - name: Build and push
           uses: docker/build-push-action@v7
           with:
             platforms: linux/amd64,linux/arm64
             push: true
             target: final
             tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
   ```

[Test your PHP deployment »](https://docs.docker.com/guides/php/deploy/)

----
url: https://docs.docker.com/build/builders/drivers/docker-container/
----

# Docker container driver

***

Table of contents

***

The Docker container driver allows creation of a managed and customizable BuildKit environment in a dedicated Docker container.

Using the Docker container driver has a couple of advantages over the default Docker driver. For example:

* Specify custom BuildKit versions to use.
* Build multi-arch images, see [QEMU](#qemu)
* Advanced options for [cache import and export](https://docs.docker.com/build/cache/backends/)

## [Synopsis](#synopsis)

Run the following command to create a new builder, named `container`, that uses the Docker container driver:

```console
$ docker buildx create \
  --name container \
  --driver=docker-container \
  --driver-opt=[key=value,...]
container
```

The following table describes the available driver-specific options that you can pass to `--driver-opt`:

| Parameter            | Type    | Default          | Description                                                                                                                            |
| -------------------- | ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `image`              | String  |                  | Sets the BuildKit image to use for the container.                                                                                      |
| `memory`             | String  |                  | Sets the amount of memory the container can use.                                                                                       |
| `memory-swap`        | String  |                  | Sets the memory swap limit for the container.                                                                                          |
| `cpu-quota`          | String  |                  | Imposes a CPU CFS quota on the container.                                                                                              |
| `cpu-period`         | String  |                  | Sets the CPU CFS scheduler period for the container.                                                                                   |
| `cpu-shares`         | String  |                  | Configures CPU shares (relative weight) of the container.                                                                              |
| `cpuset-cpus`        | String  |                  | Limits the set of CPU cores the container can use.                                                                                     |
| `cpuset-mems`        | String  |                  | Limits the set of CPU memory nodes the container can use.                                                                              |
| `default-load`       | Boolean | `false`          | Automatically load images to the Docker Engine image store.                                                                            |
| `network`            | String  |                  | Sets the network mode for the container.                                                                                               |
| `cgroup-parent`      | String  | `/docker/buildx` | Sets the cgroup parent of the container if Docker is using the "cgroupfs" driver.                                                      |
| `restart-policy`     | String  | `unless-stopped` | Sets the container's [restart policy](https://docs.docker.com/engine/containers/start-containers-automatically/#use-a-restart-policy). |
| `env.<key>`          | String  |                  | Sets the environment variable `key` to the specified `value` in the container.                                                         |
| `provenance-add-gha` | Boolean | `true`           | Automatically writes GitHub Actions context into the builder for provenance.                                                           |

Before you configure the resource limits for the container, read about [configuring runtime resource constraints for containers](/engine/containers/resource_constraints/).

## [Usage](#usage)

When you run a build, Buildx pulls the specified `image` (by default, [`moby/buildkit`](https://hub.docker.com/r/moby/buildkit)). When the container has started, Buildx submits the build submitted to the containerized build server.

```console
$ docker buildx build -t <image> --builder=container .
WARNING: No output specified with docker-container driver. Build result will only remain in the build cache. To push result image into registry use --push or to load image into docker use --load
#1 [internal] booting buildkit
#1 pulling image moby/buildkit:buildx-stable-1
#1 pulling image moby/buildkit:buildx-stable-1 1.9s done
#1 creating container buildx_buildkit_container0
#1 creating container buildx_buildkit_container0 0.5s done
#1 DONE 2.4s
...
```

## [Cache persistence](#cache-persistence)

The `docker-container` driver supports cache persistence, as it stores all the BuildKit state and related cache into a dedicated Docker volume.

To persist the `docker-container` driver's cache, even after recreating the driver using `docker buildx rm` and `docker buildx create`, you can destroy the builder using the `--keep-state` flag:

For example, to create a builder named `container` and then remove it while persisting state:

```console
# setup a builder
$ docker buildx create --name=container --driver=docker-container --use --bootstrap
container
$ docker buildx ls
NAME/NODE       DRIVER/ENDPOINT              STATUS   BUILDKIT PLATFORMS
container *     docker-container
  container0    desktop-linux                running  v0.10.5  linux/amd64
$ docker volume ls
DRIVER    VOLUME NAME
local     buildx_buildkit_container0_state

# remove the builder while persisting state
$ docker buildx rm --keep-state container
$ docker volume ls
DRIVER    VOLUME NAME
local     buildx_buildkit_container0_state

# the newly created driver with the same name will have all the state of the previous one!
$ docker buildx create --name=container --driver=docker-container --use --bootstrap
container
```

## [QEMU](#qemu)

The `docker-container` driver supports using [QEMU](https://www.qemu.org/) (user mode) to build non-native platforms. Use the `--platform` flag to specify which architectures that you want to build for.

For example, to build a Linux image for `amd64` and `arm64`:

```console
$ docker buildx build \
  --builder=container \
  --platform=linux/amd64,linux/arm64 \
  -t <registry>/<image> \
  --push .
```

> Note
>
> Emulation with QEMU can be much slower than native builds, especially for compute-heavy tasks like compilation and compression or decompression.

## [Custom network](#custom-network)

You can customize the network that the builder container uses. This is useful if you need to use a specific network for your builds.

For example, let's [create a network](/reference/cli/docker/network/create/) named `foonet`:

```console
$ docker network create foonet
```

Now create a [`docker-container` builder](/reference/cli/docker/buildx/create/) that will use this network:

```console
$ docker buildx create --use \
  --name mybuilder \
  --driver docker-container \
  --driver-opt "network=foonet"
```

Boot and [inspect `mybuilder`](/reference/cli/docker/buildx/inspect/):

```console
$ docker buildx inspect --bootstrap
```

[Inspect the builder container](/reference/cli/docker/inspect/) and see what network is being used:

```console
$ docker inspect buildx_buildkit_mybuilder0 --format={{.NetworkSettings.Networks}}
map[foonet:0xc00018c0c0]
```

## [Further reading](#further-reading)

For more information on the Docker container driver, see the [buildx reference](/reference/cli/docker/buildx/create/#driver).

----
url: https://docs.docker.com/build/exporters/
----

# Exporters overview

***

Table of contents

***

Exporters save your build results to a specified output type. You specify the exporter to use with the [`--output` CLI option](/reference/cli/docker/buildx/build/#output). Buildx supports the following exporters:

* `image`: exports the build result to a container image.
* `registry`: exports the build result into a container image, and pushes it to the specified registry.
* `local`: exports the build root filesystem into a local directory.
* `tar`: packs the build root filesystem into a local tarball.
* `oci`: exports the build result to the local filesystem in the [OCI image layout](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md) format.
* `docker`: exports the build result to the local filesystem in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/v25.0.0/image/spec/v1.2.md) format.
* `cacheonly`: doesn't export a build output, but runs the build and creates a cache.

## [Using exporters](#using-exporters)

To specify an exporter, use the following command syntax:

```console
$ docker buildx build --tag <registry>/<image> \
  --output type=TYPE .
```

Most common use cases don't require that you specify which exporter to use explicitly. You only need to specify the exporter if you intend to customize the output, or if you want to save it to disk. The `--load` and `--push` options allow Buildx to infer the exporter settings to use.

For example, if you use the `--push` option in combination with `--tag`, Buildx automatically uses the `image` exporter, and configures the exporter to push the results to the specified registry.

To get the full flexibility out of the various exporters BuildKit has to offer, you use the `--output` flag that lets you configure exporter options.

## [Use cases](#use-cases)

Each exporter type is designed for different use cases. The following sections describe some common scenarios, and how you can use exporters to generate the output that you need.

### [Load to image store](#load-to-image-store)

Buildx is often used to build container images that can be loaded to an image store. That's where the `docker` exporter comes in. The following example shows how to build an image using the `docker` exporter, and have that image loaded to the local image store, using the `--output` option:

```console
$ docker buildx build \
  --output type=docker,name=<registry>/<image> .
```

Buildx CLI will automatically use the `docker` exporter and load it to the image store if you supply the `--tag` and `--load` options:

```console
$ docker buildx build --tag <registry>/<image> --load .
```

Building images using the `docker` driver are automatically loaded to the local image store.

Images loaded to the image store are available to `docker run` immediately after the build finishes, and you'll see them in the list of images when you run the `docker images` command.

### [Push to registry](#push-to-registry)

To push a built image to a container registry, you can use the `registry` or `image` exporters.

When you pass the `--push` option to the Buildx CLI, you instruct BuildKit to push the built image to the specified registry:

```console
$ docker buildx build --tag <registry>/<image> --push .
```

Under the hood, this uses the `image` exporter, and sets the `push` parameter. It's the same as using the following long-form command using the `--output` option:

```console
$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true .
```

You can also use the `registry` exporter, which does the same thing:

```console
$ docker buildx build \
  --output type=registry,name=<registry>/<image> .
```

### [Export image layout to file](#export-image-layout-to-file)

You can use either the `oci` or `docker` exporters to save the build results to image layout on your local filesystem. Both of these exporters generate a tar archive file containing the corresponding image layout. The `dest` parameter defines the target output path for the tarball.

```console
$ docker buildx build --output type=oci,dest=./image.tar .
[+] Building 0.8s (7/7) FINISHED
 ...
 => exporting to oci image format                                                                     0.0s
 => exporting layers                                                                                  0.0s
 => exporting manifest sha256:c1ef01a0a0ef94a7064d5cbce408075730410060e253ff8525d1e5f7e27bc900        0.0s
 => exporting config sha256:eadab326c1866dd247efb52cb715ba742bd0f05b6a205439f107cf91b3abc853          0.0s
 => sending tarball                                                                                   0.0s
$ mkdir -p out && tar -C out -xf ./image.tar
$ tree out
out
├── blobs
│   └── sha256
│       ├── 9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e
│       ├── c78795f3c329dbbbfb14d0d32288dea25c3cd12f31bd0213be694332a70c7f13
│       ├── d1cf38078fa218d15715e2afcf71588ee482352d697532cf316626164699a0e2
│       ├── e84fa1df52d2abdfac52165755d5d1c7621d74eda8e12881f6b0d38a36e01775
│       └── fe9e23793a27fe30374308988283d40047628c73f91f577432a0d05ab0160de7
├── index.json
├── manifest.json
└── oci-layout
```

### [Export filesystem](#export-filesystem)

If you don't want to build an image from your build results, but instead export the filesystem that was built, you can use the `local` and `tar` exporters.

The `local` exporter unpacks the filesystem into a directory structure in the specified location. The `tar` exporter creates a tarball archive file.

```console
$ docker buildx build --output type=local,dest=<path/to/output> .
```

The `local` exporter is useful in [multi-stage builds](https://docs.docker.com/build/building/multi-stage/) since it allows you to export only a minimal number of build artifacts, such as self-contained binaries.

### [Cache-only export](#cache-only-export)

The `cacheonly` exporter can be used if you just want to run a build, without exporting any output. This can be useful if, for example, you want to run a test build. Or, if you want to run the build first, and create exports using subsequent commands. The `cacheonly` exporter creates a build cache, so any successive builds are instant.

```console
$ docker buildx build --output type=cacheonly
```

If you don't specify an exporter, and you don't provide short-hand options like `--load` that automatically selects the appropriate exporter, Buildx defaults to using the `cacheonly` exporter. Except if you build using the `docker` driver, in which case you use the `docker` exporter.

Buildx logs a warning message when using `cacheonly` as a default:

```console
$ docker buildx build .
WARNING: No output specified with docker-container driver.
         Build result will only remain in the build cache.
         To push result image into registry use --push or
         to load image into docker use --load
```

## [Multiple exporters](#multiple-exporters)

Requires: Docker Buildx [0.13.0](https://github.com/docker/buildx/releases/tag/v0.13.0) and later

You can use multiple exporters for any given build by specifying the `--output` flag multiple times. This requires **both Buildx and BuildKit** version 0.13.0 or later.

The following example runs a single build, using three different exporters:

* The `registry` exporter to push the image to a registry
* The `local` exporter to extract the build results to the local filesystem
* The `--load` flag (a shorthand for the `image` exporter) to load the results to the local image store.

```console
$ docker buildx build \
  --output type=registry,tag=<registry>/<image> \
  --output type=local,dest=<path/to/output> \
  --load .
```

## [Configuration options](#configuration-options)

This section describes some configuration options available for exporters.

The options described here are common for at least two or more exporter types. Additionally, the different exporters types support specific parameters as well. See the detailed page about each exporter for more information about which configuration parameters apply.

The common parameters described here are:

* [Compression](#compression)
* [OCI media type](#oci-media-types)

### [Compression](#compression)

When you export a compressed output, you can configure the exact compression algorithm and level to use. While the default values provide a good out-of-the-box experience, you can tweak the parameters to optimize for storage versus compute costs. Changing the compression parameters can reduce storage space required, and improve image download times, but will increase build times.

To select the compression algorithm, you can use the `compression` option. For example, to build an `image` with `compression=zstd`:

```console
$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,compression=zstd .
```

Use the `compression-level=<value>` option alongside the `compression` parameter to choose a compression level for the algorithms which support it:

* 0-9 for `gzip` and `estargz`
* 0-22 for `zstd`

As a general rule, the higher the number, the smaller the resulting file will be, and the longer the compression will take to run.

Use the `force-compression=true` option to force re-compressing layers imported from a previous image, if the requested compression algorithm is different from the previous compression algorithm.

> Note
>
> The `gzip` and `estargz` compression methods use the [`compress/gzip` package](https://pkg.go.dev/compress/gzip), while `zstd` uses the [`github.com/klauspost/compress/zstd` package](https://github.com/klauspost/compress/tree/master/zstd).

#### [zstd compression levels](#zstd-compression-levels)

When you specify `compression=zstd`, the `compression-level` parameter accepts values from 0 to 22. BuildKit maps these values to four internal compression levels:

| compression-level | Internal level | Approximate zstd level | Description                           |
| ----------------- | -------------- | ---------------------- | ------------------------------------- |
| 0-2               | Fastest        | \~1                    | Fastest compression, larger file size |
| 3-6 (default)     | Default        | \~3                    | Balanced compression and speed        |
| 7-8               | Better         | \~7                    | Better compression, slower            |
| 9-22              | Best           | \~11                   | Best compression, slowest             |

For example, setting `compression-level=5` and `compression-level=6` produces the same compression output, since both map to the "Default" internal level.

### [OCI media types](#oci-media-types)

The `image`, `registry`, `oci` and `docker` exporters create container images. These exporters support both Docker media types (default) and OCI media types

To export images with OCI media types set, use the `oci-mediatypes` property.

```console
$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,oci-mediatypes=true .
```

## [What's next](#whats-next)

Read about each of the exporters to learn about how they work and how to use them:

* [Image and registry exporters](https://docs.docker.com/build/exporters/image-registry/)
* [OCI and Docker exporters](https://docs.docker.com/build/exporters/oci-docker/).
* [Local and tar exporters](https://docs.docker.com/build/exporters/local-tar/)

----
url: https://docs.docker.com/release-lifecycle/
----

# Docker's product release lifecycle

***

Table of contents

***

This page details Docker's product release lifecycle and how Docker defines each stage. It also provides information on the product retirement process. Features and products may progress through some or all of these phases.

> Note
>
> Our [Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) governs your use of Docker and covers details of eligibility, content, use, payments and billing, and warranties. This document is not a contract and all use of Docker’s services are subject to Docker’s [Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement).

## [Lifecycle stage](#lifecycle-stage)

| Lifecycle stage                                       | Customer availability                                     | Support availability | Limitations                                                                                          | Retirement                                            |
| ----------------------------------------------------- | --------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [Experimental](#experimental)                         | Limited availability                                      | Community support    | Software may have limitations, bugs and/or stability concerns                                        | Can be discontinued without notice                    |
| [Beta](#beta)                                         | All or those involved in a Beta Feedback Program          | Community support    | Software may have limitations, bugs and/or stability concerns                                        | Can be discontinued without notice                    |
| [Early Access (EA)](#early-access-ea)                 | All or those involved in an Early Access Feedback Program | Full                 | Software may have limitations, bugs and/or stability concerns. These limitations will be documented. | Follows the [retirement process](#retirement-process) |
| [General Availability (GA)](#general-availability-ga) | All                                                       | Full                 | Few or no limitations for supported use cases                                                        | Follows the [retirement process](#retirement-process) |

### [Experimental](#experimental)

Experimental offerings are features that Docker is currently experimenting with. Customers who access experimental features have the opportunity to test, validate, and provide feedback on future functionality. This helps us focus our efforts on what provides the most value to our customers.

**Customer availability:** Availability of experimental features is limited. A portion of users may have access to none, one or many experimental features.

**Support:** Support for experimental features is best effort via Community support channels and forums.

**Limitations:** Experimental features may have potentially significant limitations such as functional limitations, performance limitations, and API limitations. Features and programmatic interfaces may change at any time without notice.

**Retirement:** During the experimental period, Docker will determine whether to continue an offering through its lifecycle. We reserve the right to change the scope of or discontinue an Experimental product or feature at any point in time without notice, as outlined in our [Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement).

### [Beta](#beta)

Beta offerings are initial releases of potential future products or features. Customers who participate in our beta programs have the opportunity to test, validate, and provide feedback on future functionality. This helps us focus our efforts on what provides the most value to our customers.

**Customer availability:** Participation in beta releases is by invitation or via use of clearly identified beta features in product. Beta invitations may be public or private.

**Support:** Support for beta features is best effort via Community support channels and forums.

**Limitations:** Beta releases may have potentially significant limitations such as functional limitations, performance limitations, and API limitations. Features and programmatic interfaces may change at any time without notice.

**Retirement:** During the beta period, Docker will determine whether to continue an offering through its lifecycle. We reserve the right to change the scope of or discontinue a Beta product or feature at any point in time without notice, as outlined in our [Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement).

### [Early Access (EA)](#early-access-ea)

Early Access offerings are products or features that may have potential feature limitations and are enabled for specific user groups as part of an incremental roll-out strategy. They are ready to be released to the world, pending some fine tuning.

**Customer availability:** Early Access functionality can be rolled out to all customers or specific segments of users in addition to or in place of existing functionality.

**Support:** Early Access offerings are provided with the same level of support as General Availability features and products.

**Limitations:** Early Access releases may have potentially significant limitations such as functional limitations, performance limitations, and API limitations, though these limitations will be documented. Breaking changes to features and programmatic interfaces will follow the [retirement process](#retirement-process) outlined below.

**Retirement:** In the event we retire an Early Access product before General Availability, we will strive to follow the [retirement process](#retirement-process) outlined below.

### [General Availability (GA)](#general-availability-ga)

General Availability offerings are fully functional products or features that are openly accessible to all Docker customers.

**Customer availability:** All Docker users have access to GA offerings according to their subscription levels.

**Limitations:** General Availability features and products will have few or no limitations for supported use cases.

**Support:** All GA offerings are fully supported, as described in our [support page](https://www.docker.com/support/).

**Retirement:** General Availability offerings follow the [retirement process](#retirement-process) outlined below.

## [Retirement process](#retirement-process)

The decision to retire or deprecate features follows a rigorous process including understanding the demand, use, impact of feature retirement and, most importantly, customer feedback. Our goal is to invest resources in areas that will add the most value for the most customers

Docker is committed to being clear, transparent, and proactive when interacting with our customers, especially about changes to our platform. To that end, we will make best efforts to follow these guidelines when retiring functionality:

* **Advance notice:** For retirement of major features or products, we will attempt to notify customers at least 6 months in advance.
* **Viable alternatives:** Docker will strive to provide viable alternatives to our customers when retiring functionality. These may be alternative offerings from Docker or recommended alternatives from 3rd party providers. Where possible and appropriate, Docker will automatically migrate customers to alternatives for retired functionality.
* **Continued support:** Docker commits to providing continued support for functionality until its retirement date.

We may need to accelerate the timeline for retirement of functionality in extenuating circumstances, such as essential changes necessary to protect the integrity of our platform or the security of our customers and others. In these cases, it is important that those changes occur as quickly as possible.

Similarly, integrated third party software or services may need to be retired due to the third-party decision to change or retire their solution. In these situations, the pace of retirement will be out of our control.

However, even under these circumstances, we will provide as much advance notice as possible.

----
url: https://docs.docker.com/reference/samples/nodejs/
----

# Node.js samples

| Name                                                                                                     | Description                                                             |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [NGINX / Node.js / Redis](https://github.com/docker/awesome-compose/tree/master/nginx-nodejs-redis)      | A sample Node.js application with Nginx proxy and a Redis database.     |
| [React / Express / MySQL](https://github.com/docker/awesome-compose/tree/master/react-express-mysql)     | A sample React application with a Node.js backend and a MySQL database. |
| [React / Express / MongoDB](https://github.com/docker/awesome-compose/tree/master/react-express-mongodb) | A sample React application with a Node.js backend and a Mongo database. |
| [example-voting-app](https://github.com/dockersamples/example-voting-app)                                | A sample Docker Compose app.                                            |
| [slack-clone-docker](https://github.com/dockersamples/slack-clone-docker)                                | A sample Slack Clone app built with the MERN stack.                     |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/guides/lab-container-supported-development/
----

[Lab: Container-Supported Development](https://docs.docker.com/guides/lab-container-supported-development/)

Hands-on lab: Run dependent services in containers during local development. Start a PostgreSQL database, write a compose.yaml, and add a database visualizer — all without installing anything on the host.

Labs

30 minutes

Resources:

* [Docker Compose docs](/compose/)
* [Bind mounts](/engine/storage/bind-mounts/)
* [Labspace repository](https://github.com/dockersamples/labspace-container-supported-development)

[« Back to all guides](/guides/)

# Lab: Container-Supported Development

***

Table of contents

***

Use containers to run the services your app depends on — databases, caches, message queues — without installing anything locally. This lab walks through running PostgreSQL in a container, writing a `compose.yaml` your whole team can share, and adding a pgAdmin visualizer to the dev stack.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-container-supported-development up -d
   ```

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

By the end of this Labspace, you will have completed the following:

* Run a PostgreSQL database in a container with no local installation
* Use bind mounts to seed a database with schema and initial data at startup
* Write a `compose.yaml` that codifies the entire dev stack for the team
* Add a pgAdmin container to visualize and inspect the database
* Understand how containerized dev stacks reduce onboarding time and environment drift

## [Modules](#modules)

| # | Module                           | Description                                                                     |
| - | -------------------------------- | ------------------------------------------------------------------------------- |
| 1 | Introduction                     | Meet the sample app and understand the container-supported development approach |
| 2 | Running a Containerized Database | Start PostgreSQL, connect the app, and seed the database using bind mounts      |
| 3 | Making Life Easier with Compose  | Replace `docker run` commands with a shared `compose.yaml`                      |
| 4 | Adding Dev Tools                 | Add pgAdmin to the Compose stack for database visualization                     |
| 5 | Recap                            | Review key takeaways and explore related guides                                 |

----
url: https://docs.docker.com/guides/testcontainers-java-jooq-flyway/create-project/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Create the Spring Boot project

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Spring Boot project from [Spring Initializr](https://start.spring.io) by selecting Maven as the build tool and adding the **JOOQ Access Layer**, **Flyway Migration**, **Spring Boot DevTools**, **PostgreSQL Driver**, and **Testcontainers** starters.

Alternatively, clone the [guide repository](https://github.com/testcontainers/tc-guide-working-with-jooq-flyway-using-testcontainers).

jOOQ (jOOQ Object Oriented Querying) provides a fluent API for building typesafe SQL queries. To get the full benefit of its typesafe DSL, you need to generate Java code from your database tables, views, and other objects.

> Tip
>
> To learn more about how the jOOQ code generator helps, read [Why You Should Use jOOQ With Code Generation](https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/).

The typical process for building and testing the application with jOOQ code generation is:

1. Create a database instance using Testcontainers.
2. Apply Flyway database migrations.
3. Run the jOOQ code generator to produce Java code from the database objects.
4. Run integration tests.

The [testcontainers-jooq-codegen-maven-plugin](https://github.com/testcontainers/testcontainers-jooq-codegen-maven-plugin) automates this as part of the Maven build.

## [Create Flyway migration scripts](#create-flyway-migration-scripts)

The sample application has `users`, `posts`, and `comments` tables. Create the first migration script following the Flyway naming convention.

Create `src/main/resources/db/migration/V1__create_tables.sql`:

```sql
create table users
(
    id         bigserial not null,
    name       varchar   not null,
    email      varchar   not null,
    created_at timestamp,
    updated_at timestamp,
    primary key (id),
    constraint user_email_unique unique (email)
);

create table posts
(
    id         bigserial                    not null,
    title      varchar                      not null,
    content    varchar                      not null,
    created_by bigint references users (id) not null,
    created_at timestamp,
    updated_at timestamp,
    primary key (id)
);

create table comments
(
    id         bigserial                    not null,
    name       varchar                      not null,
    content    varchar                      not null,
    post_id    bigint references posts (id) not null,
    created_at timestamp,
    updated_at timestamp,
    primary key (id)
);

ALTER SEQUENCE users_id_seq RESTART WITH 101;
ALTER SEQUENCE posts_id_seq RESTART WITH 101;
ALTER SEQUENCE comments_id_seq RESTART WITH 101;
```

The sequence values restart at 101 so that you can insert sample data with explicit primary key values for testing.

## [Configure jOOQ code generation](#configure-jooq-code-generation)

Add the `testcontainers-jooq-codegen-maven-plugin` to `pom.xml`:

```xml
<properties>
    <testcontainers.version>2.0.4</testcontainers.version>
    <testcontainers-jooq-codegen-maven-plugin.version>0.0.4</testcontainers-jooq-codegen-maven-plugin.version>
</properties>

<build>
    <plugins>
        <plugin>
            <groupId>org.testcontainers</groupId>
            <artifactId>testcontainers-jooq-codegen-maven-plugin</artifactId>
            <version>${testcontainers-jooq-codegen-maven-plugin.version}</version>
            <dependencies>
                <dependency>
                    <groupId>org.testcontainers</groupId>
                    <artifactId>testcontainers-postgresql</artifactId>
                    <version>${testcontainers.version}</version>
                </dependency>
                <dependency>
                    <groupId>org.postgresql</groupId>
                    <artifactId>postgresql</artifactId>
                    <version>${postgresql.version}</version>
                </dependency>
            </dependencies>
            <executions>
                <execution>
                    <id>generate-jooq-sources</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <phase>generate-sources</phase>
                    <configuration>
                        <database>
                            <type>POSTGRES</type>
                            <containerImage>postgres:16-alpine</containerImage>
                        </database>
                        <flyway>
                            <locations>
                                filesystem:src/main/resources/db/migration
                            </locations>
                        </flyway>
                        <jooq>
                            <generator>
                                <database>
                                    <includes>.*</includes>
                                    <excludes>flyway_schema_history</excludes>
                                    <inputSchema>public</inputSchema>
                                </database>
                                <target>
                                    <packageName>com.testcontainers.demo.jooq</packageName>
                                    <directory>target/generated-sources/jooq</directory>
                                </target>
                            </generator>
                        </jooq>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```

Here's what the plugin configuration does:

* The `<configuration>/<database>` section sets the database type to `POSTGRES` and the Docker image to `postgres:16-alpine`.
* The `<configuration>/<flyway>` section points to the Flyway migration scripts.
* The `<configuration>/<jooq>` section configures the package name and output directory for the generated code. You can use any configuration option that the official `jooq-code-generator` plugin supports.

When you run `./mvnw clean package`, the plugin uses Testcontainers to spin up a PostgreSQL container, applies the Flyway migrations, and generates Java code under `target/generated-sources/jooq`.

## [Create model classes](#create-model-classes)

Create model classes to represent the data structures for various use cases. These records hold a subset of column values from the tables.

`User.java`:

```java
package com.testcontainers.demo.domain;

public record User(Long id, String name, String email) {}
```

`Post.java`:

```java
package com.testcontainers.demo.domain;

import java.time.LocalDateTime;
import java.util.List;

public record Post(
  Long id,
  String title,
  String content,
  User createdBy,
  List<Comment> comments,
  LocalDateTime createdAt,
  LocalDateTime updatedAt
) {}
```

`Comment.java`:

```java
package com.testcontainers.demo.domain;

import java.time.LocalDateTime;

public record Comment(
  Long id,
  String name,
  String content,
  LocalDateTime createdAt,
  LocalDateTime updatedAt
) {}
```

## [Implement repositories using jOOQ](#implement-repositories-using-jooq)

Create `UserRepository.java` with methods to create a user and look up a user by email:

```java
package com.testcontainers.demo.domain;

import static com.testcontainers.demo.jooq.tables.Users.USERS;
import static org.jooq.Records.mapping;

import java.time.LocalDateTime;
import java.util.Optional;
import org.jooq.DSLContext;
import org.springframework.stereotype.Repository;

@Repository
class UserRepository {

  private final DSLContext dsl;

  UserRepository(DSLContext dsl) {
    this.dsl = dsl;
  }

  public User createUser(User user) {
    return this.dsl.insertInto(USERS)
      .set(USERS.NAME, user.name())
      .set(USERS.EMAIL, user.email())
      .set(USERS.CREATED_AT, LocalDateTime.now())
      .returningResult(USERS.ID, USERS.NAME, USERS.EMAIL)
      .fetchOne(mapping(User::new));
  }

  public Optional<User> getUserByEmail(String email) {
    return this.dsl.select(USERS.ID, USERS.NAME, USERS.EMAIL)
      .from(USERS)
      .where(USERS.EMAIL.equalIgnoreCase(email))
      .fetchOptional(mapping(User::new));
  }
}
```

The jOOQ DSL looks similar to SQL but written in Java. Because the code is generated from the database schema, it stays in sync with the database structure and provides type safety. For example, `where(USERS.EMAIL.equalIgnoreCase(email))` expects a `String` value. If you pass a non-string value like `123`, you get a compiler error.

## [Fetch complex object graphs](#fetch-complex-object-graphs)

jOOQ shines when it comes to complex queries. The database has a many-to-one relationship from `Post` to `User` and a one-to-many relationship from `Post` to `Comment`.

Create `PostRepository.java` to load a `Post` with its creator and comments using a single query with jOOQ's MULTISET feature:

```java
package com.testcontainers.demo.domain;

import static com.testcontainers.demo.jooq.Tables.COMMENTS;
import static com.testcontainers.demo.jooq.tables.Posts.POSTS;
import static org.jooq.Records.mapping;
import static org.jooq.impl.DSL.multiset;
import static org.jooq.impl.DSL.row;
import static org.jooq.impl.DSL.select;

import java.util.Optional;
import org.jooq.DSLContext;
import org.springframework.stereotype.Repository;

@Repository
class PostRepository {

  private final DSLContext dsl;

  PostRepository(DSLContext dsl) {
    this.dsl = dsl;
  }

  public Optional<Post> getPostById(Long id) {
    return this.dsl.select(
        POSTS.ID,
        POSTS.TITLE,
        POSTS.CONTENT,
        row(POSTS.users().ID, POSTS.users().NAME, POSTS.users().EMAIL)
          .mapping(User::new)
          .as("createdBy"),
        multiset(
          select(
            COMMENTS.ID,
            COMMENTS.NAME,
            COMMENTS.CONTENT,
            COMMENTS.CREATED_AT,
            COMMENTS.UPDATED_AT
          )
            .from(COMMENTS)
            .where(POSTS.ID.eq(COMMENTS.POST_ID))
        )
          .as("comments")
          .convertFrom(r -> r.map(mapping(Comment::new))),
        POSTS.CREATED_AT,
        POSTS.UPDATED_AT
      )
      .from(POSTS)
      .where(POSTS.ID.eq(id))
      .fetchOptional(mapping(Post::new));
  }
}
```

This uses jOOQ's [nested records](https://www.jooq.org/doc/latest/manual/sql-building/column-expressions/nested-records/) for the many-to-one `Post`-to-`User` association and [MULTISET](https://www.jooq.org/doc/latest/manual/sql-building/column-expressions/multiset-value-constructor/) for the one-to-many `Post`-to-`Comment` association.

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-java-jooq-flyway/write-tests/)

----
url: https://docs.docker.com/reference/cli/sbx/run/
----

# sbx run

| Description | Run an agent in a sandbox                                       |
| ----------- | --------------------------------------------------------------- |
| Usage       | `sbx run [flags] SANDBOX \| AGENT [PATH...] [-- AGENT_ARGS...]` |

## [Description](#description)

Run an agent in a sandbox, creating the sandbox if it does not already exist.

Pass agent arguments after the "--" separator. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

To create a sandbox without attaching, use "sbx create" instead.

Available agents: claude, codex, copilot, cursor, docker-agent, droid, gemini, kiro, opencode, shell

## [Options](#options)

| Option           | Default | Description                                                                                                                                                                |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository; must be set at sandbox creation time (no-op when re-attaching to an existing clone-mode sandbox) |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                 |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                    |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                          |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                    |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>)                                                                                                                        |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                     |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Create and run a sandbox with claude in current directory
sbx run claude

# Create and run with additional workspaces (read-only)
sbx run claude . /path/to/docs:ro

# Run an existing sandbox
sbx run existing-sandbox

# Run a sandbox with agent arguments
sbx run claude -- --continue
```

----
url: https://docs.docker.com/reference/cli/docker/compose/alpha/dry-run/
----

# docker compose alpha dry-run

***

| Description | EXPERIMENTAL - Dry run command allow you to test a command without applying changes |
| ----------- | ----------------------------------------------------------------------------------- |
| Usage       | `docker compose alpha dry-run -- [COMMAND...]`                                      |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

EXPERIMENTAL - Dry run command allow you to test a command without applying changes

----
url: https://docs.docker.com/guides/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

***

## All guides

Filtered results: showing 102 out of 102 guides.

By clicking “Accept All Cookies”, you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts.

## Privacy Preference Center

When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.\
[More information](https://cookiepedia.co.uk/giving-consent-to-cookies)

### Manage Consent Preferences

#### Functional Cookies

Functional Cookies

These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.

#### Strictly Necessary Cookies

Always Active

These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.

#### Performance Cookies

Performance Cookies

These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.

#### Targeting Cookies

Targeting Cookies

These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising.

### Cookie List

checkbox label label

Consent Leg.Interest

checkbox label label

checkbox label label

checkbox label label

[](https://www.onetrust.com/products/cookie-consent/)

----
url: https://docs.docker.com/scout/integrations/team-collaboration/slack/
----

# Integrate Docker Scout with Slack

***

Table of contents

***

You can integrate Docker Scout with Slack by creating a Slack webhook and adding it to the Docker Scout Dashboard. Docker Scout will notify you about when a new vulnerability is disclosed, and it affects one or more of your images.

Example Slack notification from Docker Scout

## [How it works](#how-it-works)

After configuring the integration, Docker Scout sends notifications about changes to policy compliance and vulnerability exposure for your repositories, to the Slack channels associated with the webhook.

> Note
>
> Notifications are only triggered for the *last pushed* image tags for each repository. "Last pushed" refers to the image tag that was most recently pushed to the registry and analyzed by Docker Scout. If the last pushed image is not by a newly disclosed CVE, then no notification will be triggered.

For more information about Docker Scout notifications, see [Notification settings](https://docs.docker.com/scout/explore/dashboard/#notification-settings)

## [Setup](#setup)

To add a Slack integration:

1. Create a webhook, see [Slack documentation](https://api.slack.com/messaging/webhooks).

2. Go to the [Slack integration page](https://scout.docker.com/settings/integrations/slack/) in the Docker Scout Dashboard.

3. In the **How to integrate** section, enter a **Configuration name**. Docker Scout uses this label as a display name for the integration, so you might want to change the default name into something more meaningful. For example the `#channel-name`, or the name of the team that this configuration belongs to.

4. Paste the webhook you just created in the **Slack webhook** field.

   Select the **Test webhook** button if you wish to verify the connection. Docker Scout will send a test message to the specified webhook.

5. Select whether you want to enable notifications for all your Scout-enabled image repositories, or enter the names of the repositories that you want to send notifications for.

6. When you're ready to enable the integration, select **Create**.

After creating the webhook, Docker Scout begins to send notifications updates to the Slack channels associated with the webhook.

## [Remove a Slack integration](#remove-a-slack-integration)

To remove a Slack integration:

1. Go to the [Slack integration page](https://scout.docker.com/settings/integrations/slack/) in the Docker Scout Dashboard.
2. Select the **Remove** icon for the integration that you want to remove.
3. Confirm by selecting **Remove** again in the confirmation dialog.

----
url: https://docs.docker.com/reference/build-checks/from-as-casing/
----

# FromAsCasing

***

Table of contents

***

## [Output](#output)

```text
'as' and 'FROM' keywords' casing do not match
```

## [Description](#description)

While Dockerfile keywords can be either uppercase or lowercase, mixing case styles is not recommended for readability. This rule reports violations where mixed case style occurs for a `FROM` instruction with an `AS` keyword declaring a stage name.

## [Examples](#examples)

❌ Bad: `FROM` is uppercase, `AS` is lowercase.

```dockerfile
FROM debian:latest as builder
```

✅ Good: `FROM` and `AS` are both uppercase

```dockerfile
FROM debian:latest AS deb-builder
```

✅ Good: `FROM` and `AS` are both lowercase.

```dockerfile
from debian:latest as deb-builder
```

## [Related errors](#related-errors)

* [`FileConsistentCommandCasing`](https://docs.docker.com/reference/build-checks/consistent-instruction-casing/)

----
url: https://docs.docker.com/get-started/introduction/get-docker-desktop/
----

# Get Docker Desktop

***

Table of contents

***

## [Explanation](#explanation)

Docker Desktop is the all-in-one package to build images, run containers, and so much more. This guide will walk you through the installation process, enabling you to experience Docker Desktop firsthand.

> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250 employees OR more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsGetDockerDesktop).

### Docker Desktop for Mac

[Download (Apple Silicon)](https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) | [Download (Intel)](https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64) | [Install instructions](/desktop/setup/install/mac-install)

### Docker Desktop for Windows

[Download](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows) | [Install instructions](/desktop/setup/install/windows-install)

### Docker Desktop for Linux

[Install instructions](/desktop/setup/install/linux/)

Once it's installed, complete the setup process and you're all set to run a Docker container.

## [Try it out](#try-it-out)

In this hands-on guide, you will see how to run a Docker container using Docker Desktop.

Follow the instructions to run a container using the CLI.

## [Run your first container](#run-your-first-container)

Open your CLI terminal and start a container by running the `docker run` command:

```console
$ docker run -d -p 8080:80 docker/welcome-to-docker
```

## [Access the frontend](#access-the-frontend)

For this container, the frontend is accessible on port `8080`. To open the website, visit <http://localhost:8080> in your browser.

## [Manage containers using Docker Desktop](#manage-containers-using-docker-desktop)

1. Open Docker Desktop and select the **Containers** field on the left sidebar.

2. You can view information about your container including logs, and files, and even access the shell by selecting the **Exec** tab.

3. Select the **Inspect** field to obtain detailed information about the container. You can perform various actions such as pause, resume, start or stop containers, or explore the **Logs**, **Bind mounts**, **Exec**, **Files**, and **Stats** tabs.

Docker Desktop simplifies container management for developers by streamlining the setup, configuration, and compatibility of applications across different environments, thereby addressing the pain points of environment inconsistencies and deployment challenges.

## [What's next?](#whats-next)

Now that you have Docker Desktop installed and ran your first container, it's time to start developing with containers.

[Develop with containers](https://docs.docker.com/get-started/introduction/develop-with-containers/)

----
url: https://docs.docker.com/reference/cli/sbx/rm/
----

# sbx rm

| Description | Remove one or more sandboxes  |
| ----------- | ----------------------------- |
| Usage       | `sbx rm [SANDBOX...] [flags]` |

## [Description](#description)

Remove one or more sandboxes and all associated resources.

Stops running sandboxes, removes their containers, cleans up any Git worktrees, and deletes sandbox state. This action cannot be undone.

Removal requires confirmation; use --force to skip confirmation prompts (for non-interactive scripts). Use --all to remove every sandbox.

## [Options](#options)

| Option        | Default | Description               |
| ------------- | ------- | ------------------------- |
| `--all`       |         | Remove all sandboxes      |
| `-f, --force` |         | Skip confirmation prompts |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/billing/
----

# Manage billing and payments

***

***

Use the resources in this section to manage billing and payments for your Docker subscriptions.

### [Add or update a payment method](/billing/payment-method/)

[Learn how to add or update a payment method for your personal account or organization.](/billing/payment-method/)

### [Update billing information](/billing/details/)

[Discover how to update the billing information for your personal account or organization.](/billing/details/)

### [View billing history](/billing/history/)

[Learn how to view billing history and download past invoices.](/billing/history/)

### [Billing FAQs](/billing/faqs/)

[Find the answers you need and explore common questions.](/billing/faqs/)

### [Register a tax certificate](/billing/tax-certificate/)

[Learn how to register a tax exemption certificate.](/billing/tax-certificate/)

### [3D Secure authentication](/billing/3d-secure/)

[Discover how Docker billing supports 3DS and how to troubleshoot potential issues.](/billing/3d-secure/)

----
url: https://docs.docker.com/guides/angular/
----

# Angular language-specific guide

Table of contents

***

This guide explains how to containerize Angular applications using Docker.

**Time to complete** 20 minutes

The Angular language-specific guide shows you how to containerize an Angular application using Docker, following best practices for creating efficient, production-ready containers.

[Angular](https://angular.dev/) is a robust and widely adopted framework for building dynamic, enterprise-grade web applications. However, managing dependencies, environments, and deployments can become complex as applications scale. Docker streamlines these challenges by offering a consistent, isolated environment for development and production.

> **Acknowledgment**
>
> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and experienced Front-end engineer, his expertise in Docker, DevOps, and modern web development has made this resource essential for the community, helping developers navigate and optimize their Docker workflows.

***

## [What will you learn?](#what-will-you-learn)

In this guide, you will learn how to:

* Containerize and run an Angular application using Docker.
* Set up a local development environment for Angular inside a container.
* Run tests for your Angular application within a Docker container.
* Configure a CI/CD pipeline using GitHub Actions for your containerized app.
* Deploy the containerized Angular application to a local Kubernetes cluster for testing and debugging.

You'll start by containerizing an existing Angular application and work your way up to production-level deployments.

***

## [Prerequisites](#prerequisites)

Before you begin, ensure you have a working knowledge of:

* Basic understanding of [TypeScript](https://www.typescriptlang.org/) and [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript).
* Familiarity with [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts.
* Familiarity with [Angular](https://angular.io/) fundamentals.
* Understanding of core Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide.

Once you've completed the Angular getting started modules, you’ll be fully prepared to containerize your own Angular application using the detailed examples and best practices outlined in this guide.

## [Modules](#modules)

1. [Containerize](https://docs.docker.com/guides/angular/containerize/)

   Learn how to containerize an Angular application with Docker by creating an optimized, production-ready image using best practices for performance, security, and scalability.

2. [Develop your app](https://docs.docker.com/guides/angular/develop/)

   Learn how to develop your Angular application locally using containers.

3. [Run your tests](https://docs.docker.com/guides/angular/run-tests/)

   Learn how to run your Angular tests in a container.

4. [GitHub Actions CI](https://docs.docker.com/guides/angular/configure-github-actions/)

   Learn how to configure CI/CD using GitHub Actions for your Angular application.

5. [Test your deployment](https://docs.docker.com/guides/angular/deploy/)

   Learn how to deploy locally to test and debug your Kubernetes deployment

----
url: https://docs.docker.com/reference/api/extensions-sdk/Docker/
----

# Interface: Docker

***

Table of contents

***

**`Since`**

0.2.0

## [Properties](#properties)

### [cli](#cli)

• `Readonly` **cli**: [`DockerCommand`](https://docs.docker.com/reference/api/extensions-sdk/DockerCommand/)

You can also directly execute the Docker binary.

```typescript
const output = await ddClient.docker.cli.exec("volume", [
  "ls",
  "--filter",
  "dangling=true"
]);
```

Output:

```json
{
  "stderr": "...",
  "stdout": "..."
}
```

For convenience, the command result object also has methods to easily parse it depending on output format. See [ExecResult](https://docs.docker.com/reference/api/extensions-sdk/ExecResult/) instead.

***

Streams the output as a result of the execution of a Docker command. It is useful when the output of the command is too long, or you need to get the output as a stream.

```typescript
await ddClient.docker.cli.exec("logs", ["-f", "..."], {
  stream: {
    onOutput(data): void {
        // As we can receive both `stdout` and `stderr`, we wrap them in a JSON object
        JSON.stringify(
          {
            stdout: data.stdout,
            stderr: data.stderr,
          },
          null,
          "  "
        );
    },
    onError(error: any): void {
      console.error(error);
    },
    onClose(exitCode: number): void {
      console.log("onClose with exit code " + exitCode);
    },
  },
});
```

## [Methods](#methods)

### [listContainers](#listcontainers)

▸ **listContainers**(`options?`): `Promise`<`unknown`>

Get the list of running containers (same as `docker ps`).

By default, this will not list stopped containers. You can use the option `{"all": true}` to list all the running and stopped containers.

```typescript
const containers = await ddClient.docker.listContainers();
```

#### [Parameters](#parameters)

| Name       | Type  | Description                                                                                                                                                                                                                                                                                                    |
| ---------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options?` | `any` | (Optional). A JSON like `{ "all": true, "limit": 10, "size": true, "filters": JSON.stringify({ status: ["exited"] }), }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/reference/api/engine/version/v1.52/#operation/ContainerList). |

#### [Returns](#returns)

`Promise`<`unknown`>

***

### [listImages](#listimages)

▸ **listImages**(`options?`): `Promise`<`unknown`>

Get the list of local container images

```typescript
const images = await ddClient.docker.listImages();
```

#### [Parameters](#parameters-1)

| Name       | Type  | Description                                                                                                                                                                                                                                                                             |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options?` | `any` | (Optional). A JSON like `{ "all": true, "filters": JSON.stringify({ dangling: ["true"] }), "digests": true * }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/reference/api/engine/version/v1.52/#tag/Image). |

#### [Returns](#returns-1)

----
url: https://docs.docker.com/reference/cli/docker/compose/volumes/
----

# docker compose volumes

***

| Description | List volumes                                    |
| ----------- | ----------------------------------------------- |
| Usage       | `docker compose volumes [OPTIONS] [SERVICE...]` |

## [Description](#description)

List volumes

## [Options](#options)

| Option        | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--format`    | `table` | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-q, --quiet` |         | Only display volume names                                                                                                                                                                                                                                                                                                                                                              |

----
url: https://docs.docker.com/reference/cli/docker/network/connect/
----

# docker network connect

***

| Description | Connect a container to a network                     |
| ----------- | ---------------------------------------------------- |
| Usage       | `docker network connect [OPTIONS] NETWORK CONTAINER` |

## [Description](#description)

Connects a container to a network. You can connect a container by name or by ID. Once connected, the container can communicate with other containers in the same network.

## [Options](#options)

| Option              | Default | Description                                                                              |
| ------------------- | ------- | ---------------------------------------------------------------------------------------- |
| [`--alias`](#alias) |         | Add network-scoped alias for the container                                               |
| `--driver-opt`      |         | driver options for the network                                                           |
| `--gw-priority`     |         | Highest gw-priority provides the default gateway. Accepts positive and negative values.  |
| [`--ip`](#ip)       | ``      | IPv4 address (e.g., `172.30.100.104`)                                                    |
| `--ip6`             | ``      | IPv6 address (e.g., `2001:db8::33`)                                                      |
| [`--link`](#link)   |         | Add link to another container                                                            |
| `--link-local-ip`   |         | Add a link-local address for the container                                               |

## [Examples](#examples)

### [Connect a running container to a network](#connect-a-running-container-to-a-network)

```console
$ docker network connect multi-host-network container1
```

### [Connect a container to a network when it starts](#connect-a-container-to-a-network-when-it-starts)

You can also use the `docker run --network=<network-name>` option to start a container and immediately connect it to a network.

```console
$ docker run -itd --network=multi-host-network busybox
```

### [Specify the IP address a container will use on a given network (--ip)](#ip)

You can specify the IP address you want to be assigned to the container's interface.

```console
$ docker network connect --ip 10.10.36.122 multi-host-network container2
```

### [Use the legacy `--link` option (--link)](#link)

You can use `--link` option to link another container with a preferred alias.

```console
$ docker network connect --link container1:c1 multi-host-network container2
```

### [Create a network alias for a container (--alias)](#alias)

`--alias` option can be used to resolve the container by another name in the network being connected to.

```console
$ docker network connect --alias db --alias mysql multi-host-network container2
```

### [Set sysctls for a container's interface (--driver-opt)](#sysctl)

`sysctl` settings that start with `net.ipv4.` and `net.ipv6.` can be set per-interface using `--driver-opt` label `com.docker.network.endpoint.sysctls`. The name of the interface must be replaced by `IFNAME`.

To set more than one `sysctl` for an interface, quote the whole value of the `driver-opt` field, remembering to escape the quotes for the shell if necessary. For example, if the interface to `my-net` is given name `eth3`, the following example sets `net.ipv4.conf.eth3.log_martians=1` and `net.ipv4.conf.eth3.forwarding=0`.

```console
$ docker network connect --driver-opt=\"com.docker.network.endpoint.sysctls=net.ipv4.conf.IFNAME.log_martians=1,net.ipv4.conf.IFNAME.forwarding=0\" multi-host-network container2
```

> Note
>
> Network drivers may restrict the sysctl settings that can be modified and, to protect the operation of the network, new restrictions may be added in the future.

### [Network implications of stopping, pausing, or restarting containers](#network-implications-of-stopping-pausing-or-restarting-containers)

You can pause, restart, and stop containers that are connected to a network. A container connects to its configured networks when it runs.

If specified, the container's IP address(es) is reapplied when a stopped container is restarted. If the IP address is no longer available, the container fails to start. One way to guarantee that the IP address is available is to specify an `--ip-range` when creating the network, and choose the static IP address(es) from outside that range. This ensures that the IP address is not given to another container while this container is not on the network.

```console
$ docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 multi-host-network
```

```console
$ docker network connect --ip 172.20.128.2 multi-host-network container2
```

To verify the container is connected, use the `docker network inspect` command. Use `docker network disconnect` to remove a container from the network.

Once connected in network, containers can communicate using only another container's IP address or name. For `overlay` networks or custom plugins that support multi-host connectivity, containers connected to the same multi-host network but launched from different Engines can also communicate in this way.

You can connect a container to one or more networks. The networks need not be the same type. For example, you can connect a single container bridge and overlay networks.

----
url: https://docs.docker.com/reference/cli/docker/secret/inspect/
----

# docker secret inspect

***

| Description | Display detailed information on one or more secrets  |
| ----------- | ---------------------------------------------------- |
| Usage       | `docker secret inspect [OPTIONS] SECRET [SECRET...]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Inspects the specified secret.

By default, this renders all results in a JSON array. If a format is specified, the given template will be executed for each result.

Go's [text/template](https://pkg.go.dev/text/template) package describes all the details of the format.

For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/).

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                             |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --format`](#format) |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `--pretty`                |         | Print the information in a human friendly format                                                                                                                                                                                        |

## [Examples](#examples)

### [Inspect a secret by name or ID](#inspect-a-secret-by-name-or-id)

You can inspect a secret, either by its name or ID.

For example, given the following secret:

```console
$ docker secret ls

ID                          NAME                CREATED             UPDATED
eo7jnzguqgtpdah3cm5srfb97   my_secret           3 minutes ago       3 minutes ago
```

```console
$ docker secret inspect secret.json
```

The output is in JSON format, for example:

```json
[
  {
    "ID": "eo7jnzguqgtpdah3cm5srfb97",
    "Version": {
      "Index": 17
    },
    "CreatedAt": "2017-03-24T08:15:09.735271783Z",
    "UpdatedAt": "2017-03-24T08:15:09.735271783Z",
    "Spec": {
      "Name": "my_secret",
      "Labels": {
        "env": "dev",
        "rev": "20170324"
      }
    }
  }
]
```

### [Format the output (--format)](#format)

You can use the `--format` option to obtain specific information about a secret. The following example command outputs the creation time of the secret.

```console
$ docker secret inspect --format='{{.CreatedAt}}' eo7jnzguqgtpdah3cm5srfb97

2017-03-24 08:15:09.735271783 +0000 UTC
```

----
url: https://docs.docker.com/guides/genai-pdf-bot/containerize/
----

# Containerize a generative AI application

***

Table of contents

***

## [Prerequisites](#prerequisites)

> Note
>
> GenAI applications can often benefit from GPU acceleration. Currently Docker Desktop supports GPU acceleration only on [Windows with the WSL2 backend](https://docs.docker.com/desktop/features/gpu/#using-nvidia-gpus-with-wsl2). Linux users can also access GPU acceleration using a native installation of the [Docker Engine](https://docs.docker.com/engine/install/).

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/) or, if you are a Linux user and are planning to use GPU acceleration, [Docker Engine](https://docs.docker.com/engine/install/). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop.
* You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client.

## [Overview](#overview)

This section walks you through containerizing a generative AI (GenAI) application using Docker Desktop.

> Note
>
> You can see more samples of containerized GenAI applications in the [GenAI Stack](https://github.com/docker/genai-stack) demo applications.

## [Get the sample application](#get-the-sample-application)

The sample application used in this guide is a modified version of the PDF Reader application from the [GenAI Stack](https://github.com/docker/genai-stack) demo applications. The application is a full stack Python application that lets you ask questions about a PDF file.

The application uses [LangChain](https://www.langchain.com/) for orchestration, [Streamlit](https://streamlit.io/) for the UI, [Ollama](https://ollama.ai/) to run the LLM, and [Neo4j](https://neo4j.com/) to store vectors.

Clone the sample application. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/craig-osterhout/docker-genai-sample
```

You should now have the following files in your `docker-genai-sample` directory.

```text
├── docker-genai-sample/
│ ├── .gitignore
│ ├── app.py
│ ├── chains.py
│ ├── env.example
│ ├── requirements.txt
│ ├── util.py
│ ├── LICENSE
│ └── README.md
```

## [Create Docker assets](#create-docker-assets)

Now that you have an application, you can create the necessary Docker assets to containerize it.

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

Create the following files in your `docker-genai-sample` directory.

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1

# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Dockerfile reference guide at
# https://docs.docker.com/go/dockerfile-reference/

ARG PYTHON_VERSION=3.11.4
FROM python:${PYTHON_VERSION}-slim as base

# Prevents Python from writing pyc files.
ENV PYTHONDONTWRITEBYTECODE=1

# Keeps Python from buffering stdout and stderr to avoid situations where
# the application crashes without emitting any logs due to buffering.
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Create a non-privileged user that the app will run under.
# See https://docs.docker.com/go/dockerfile-user-best-practices/
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser

# Download dependencies as a separate step to take advantage of Docker's caching.
# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds.
# Leverage a bind mount to requirements.txt to avoid having to copy them into
# into this layer.
RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    python -m pip install -r requirements.txt

# Switch to the non-privileged user to run the application.
USER appuser

# Copy the source code into the container.
COPY . .

# Expose the port that the application listens on.
EXPOSE 8000

# Run the application.
CMD ["streamlit", "run", "app.py", "--server.address=0.0.0.0", "--server.port=8000"]
```

compose.yaml

```yaml
# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Docker Compose reference guide at
# https://docs.docker.com/go/compose-spec-reference/

# Here the instructions define your application as a service called "server".
# This service is built from the Dockerfile in the current directory.
# You can add other services your application may depend on here, such as a
# database or a cache. For examples, see the Awesome Compose repository:
# https://github.com/docker/awesome-compose
services:
  server:
    build:
      context: .
    ports:
      - 8000:8000

# The commented out section below is an example of how to define a PostgreSQL
# database that your application can use. `depends_on` tells Docker Compose to
# start the database before your application. The `db-data` volume persists the
# database data between container restarts. The `db-password` secret is used
# to set the database password. You must create `db/password.txt` and add
# a password of your choosing to it before running `docker compose up`.
#     depends_on:
#       db:
#         condition: service_healthy
#   db:
#     image: postgres
#     restart: always
#     user: postgres
#     secrets:
#       - db-password
#     volumes:
#       - db-data:/var/lib/postgresql/data
#     environment:
#       - POSTGRES_DB=example
#       - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
#     expose:
#       - 5432
#     healthcheck:
#       test: [ "CMD", "pg_isready" ]
#       interval: 10s
#       timeout: 5s
#       retries: 5
# volumes:
#   db-data:
# secrets:
#   db-password:
#     file: db/password.txt
```

.dockerignore

```text
# Include any files or directories that you don't want to be copied to your
# container here (e.g., local build artifacts, temporary files, etc.).
#
# For more help, visit the .dockerignore file reference guide at
# https://docs.docker.com/go/build-context-dockerignore/

**/.DS_Store
**/__pycache__
**/.venv
**/.classpath
**/.dockerignore
**/.env
**/.git
**/.gitignore
**/.project
**/.settings
**/.toolstarget
**/.vs
**/.vscode
**/*.*proj.user
**/*.dbmdl
**/*.jfm
**/bin
**/charts
**/docker-compose*
**/compose.y*ml
**/Dockerfile*
**/node_modules
**/npm-debug.log
**/obj
**/secrets.dev.yaml
**/values.dev.yaml
LICENSE
README.md
```

You should now have the following contents in your `docker-genai-sample` directory.

```text
├── docker-genai-sample/
│ ├── .dockerignore
│ ├── .gitignore
│ ├── app.py
│ ├── chains.py
│ ├── compose.yaml
│ ├── env.example
│ ├── requirements.txt
│ ├── util.py
│ ├── Dockerfile
│ ├── LICENSE
│ └── README.md
```

To learn more about these files, see the following:

* [Dockerfile](https://docs.docker.com/reference/dockerfile/)
* [.dockerignore](https://docs.docker.com/reference/dockerfile/#dockerignore-file)
* [compose.yaml](https://docs.docker.com/reference/compose-file/)

## [Run the application](#run-the-application)

Inside the `docker-genai-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Docker builds and runs your application. Depending on your network connection, it may take several minutes to download all the dependencies. You'll see a message like the following in the terminal when the application is running.

```console
server-1  |   You can now view your Streamlit app in your browser.
server-1  |
server-1  |   URL: http://0.0.0.0:8000
server-1  |
```

Open a browser and view the application at <http://localhost:8000>. You should see a simple Streamlit application. The application may take a few minutes to download the embedding model. While the download is in progress, **Running** appears in the top-right corner.

The application requires a Neo4j database service and an LLM service to function. If you have access to services that you ran outside of Docker, specify the connection information and try it out. If you don't have the services running, continue with this guide to learn how you can run some or all of these services with Docker.

In the terminal, press `ctrl`+`c` to stop the application.

## [Summary](#summary)

In this section, you learned how you can containerize and run your GenAI application using Docker.

## [Next steps](#next-steps)

In the next section, you'll learn how you can run your application, database, and LLM service all locally using Docker.

[Use containers for generative AI development »](https://docs.docker.com/guides/genai-pdf-bot/develop/)

----
url: https://docs.docker.com/build/bake/introduction/
----

# Introduction to Bake

***

Table of contents

***

Bake is an abstraction for the `docker build` command that lets you more easily manage your build configuration (CLI flags, environment variables, etc.) in a consistent way for everyone on your team.

Bake is a command built into the Buildx CLI, so as long as you have Buildx installed, you also have access to bake, via the `docker buildx bake` command.

## [Building a project with Bake](#building-a-project-with-bake)

Here's a simple example of a `docker build` command:

```console
$ docker build -f Dockerfile -t myapp:latest .
```

This command builds the Dockerfile in the current directory and tags the resulting image as `myapp:latest`.

To express the same build configuration using Bake:

docker-bake.hcl

```hcl
target "myapp" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["myapp:latest"]
}
```

Bake provides a structured way to manage your build configuration, and it saves you from having to remember all the CLI flags for `docker build` every time. With this file, building the image is as simple as running:

```console
$ docker buildx bake myapp
```

For simple builds, the difference between `docker build` and `docker buildx bake` is minimal. However, as your build configuration grows more complex, Bake provides a more structured way to manage that complexity, that would be difficult to manage with CLI flags for the `docker build`. It also provides a way to share build configurations across your team, so that everyone is building images in a consistent way, with the same configuration.

## [The Bake file format](#the-bake-file-format)

You can write Bake files in HCL or JSON. Bake can also read [Docker Compose files](https://docs.docker.com/build/bake/compose-file/) and translate each service to a build target. HCL is the most expressive and flexible format, which is why you'll see it used in most of the examples in this documentation, and in projects that use Bake.

The properties that can be set for a target closely resemble the CLI flags for `docker build`. For instance, consider the following `docker build` command:

```console
$ docker build \
  -f Dockerfile \
  -t myapp:latest \
  --build-arg foo=bar \
  --no-cache \
  --platform linux/amd64,linux/arm64 \
  .
```

The Bake equivalent would be:

docker-bake.hcl

```hcl
target "myapp" {
  context = "."
  dockerfile = "Dockerfile"
  tags = ["myapp:latest"]
  args = {
    foo = "bar"
  }
  no-cache = true
  platforms = ["linux/amd64", "linux/arm64"]
}
```

> Tip
>
> Want a better editing experience for Bake files in VS Code? Check out the [Docker DX](https://marketplace.visualstudio.com/items?itemName=docker.docker) extension for linting, code navigation, and vulnerability scanning.

## [Next steps](#next-steps)

To learn more about using Bake, see the following topics:

* Learn how to define and use [targets](https://docs.docker.com/build/bake/targets/) in Bake
* To see all the properties that can be set for a target, refer to the [Bake file reference](/build/bake/reference/).

----
url: https://docs.docker.com/subscription/
----

# Subscription

***

***

Docker subscriptions provide licensing for commercial use of Docker products including Docker Desktop, Docker Hub, Docker Build Cloud, Docker Scout, and Testcontainers Cloud.

Use these resources to choose the right subscription for your needs or manage your existing subscription.

### [Compare Docker subscriptions](https://www.docker.com/pricing?ref=Docs\&refAction=DocsSubscription)

[Visit the pricing page to see what's included in different Docker subscriptions.](https://www.docker.com/pricing?ref=Docs\&refAction=DocsSubscription)

### [Set up your subscription](/subscription/setup/)

[Get started setting up a personal or organization subscription.](/subscription/setup/)

### [Scale your subscription](/subscription/scale/)

[Scale your subscription to fit your needs.](/subscription/scale/)

### [Change your subscription](/subscription/change/)

[Learn how to upgrade or downgrade your subscription.](/subscription/change/)

### [Manage seats](/subscription/manage-seats/)

[Learn how to add or remove seats from your subscription.](/subscription/manage-seats/)

### [Docker Desktop license agreement](/subscription/desktop-license/)

[Review the terms of the Docker Subscription Service Agreement.](/subscription/desktop-license/)

### [Subscription FAQs](/subscription/faq/)

[Find the answers you need and explore common questions.](/subscription/faq/)

----
url: https://docs.docker.com/build/concepts/dockerfile/
----

# Dockerfile overview

***

Table of contents

***

## [Dockerfile](#dockerfile)

It all starts with a Dockerfile.

Docker builds images by reading the instructions from a Dockerfile. A Dockerfile is a text file containing instructions for building your source code. The Dockerfile instruction syntax is defined by the specification reference in the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/).

Here are the most common types of instructions:

| Instruction                                                                    | Description                                                                                                                                                                                              |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`FROM <image>`](https://docs.docker.com/reference/dockerfile/#from)           | Defines a base for your image.                                                                                                                                                                           |
| [`RUN <command>`](https://docs.docker.com/reference/dockerfile/#run)           | Executes any commands in a new layer on top of the current image and commits the result. `RUN` also has a shell form for running commands.                                                               |
| [`WORKDIR <directory>`](https://docs.docker.com/reference/dockerfile/#workdir) | Sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY`, and `ADD` instructions that follow it in the Dockerfile.                                                                          |
| [`COPY <src> <dest>`](https://docs.docker.com/reference/dockerfile/#copy)      | Copies new files or directories from `<src>` and adds them to the filesystem of the container at the path `<dest>`.                                                                                      |
| [`CMD <command>`](https://docs.docker.com/reference/dockerfile/#cmd)           | Lets you define the default program that is run once you start the container based on this image. Each Dockerfile only has one `CMD`, and only the last `CMD` instance is respected when multiple exist. |

Dockerfiles are crucial inputs for image builds and can facilitate automated, multi-layer image builds based on your unique configurations. Dockerfiles can start simple and grow with your needs to support more complex scenarios.

### [Filename](#filename)

The default filename to use for a Dockerfile is `Dockerfile`, without a file extension. Using the default name allows you to run the `docker build` command without having to specify additional command flags.

Some projects may need distinct Dockerfiles for specific purposes. A common convention is to name these `<something>.Dockerfile`. You can specify the Dockerfile filename using the `--file` flag for the `docker build` command. Refer to the [`docker build` CLI reference](/reference/cli/docker/buildx/build/#file) to learn about the `--file` flag.

> Note
>
> We recommend using the default (`Dockerfile`) for your project's primary Dockerfile.

## [Docker images](#docker-images)

Docker images consist of layers. Each layer is the result of a build instruction in the Dockerfile. Layers are stacked sequentially, and each one is a delta representing the changes applied to the previous layer.

### [Example](#example)

Here's what a typical workflow for building applications with Docker looks like.

The following example code shows a small "Hello World" application written in Python, using the Flask framework.

```python
from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello World!"
```

In order to ship and deploy this application without Docker Build, you would need to make sure that:

* The required runtime dependencies are installed on the server
* The Python code gets uploaded to the server's filesystem
* The server starts your application, using the necessary parameters

The following Dockerfile creates a container image, which has all the dependencies installed and that automatically starts your application.

```dockerfile
# syntax=docker/dockerfile:1
FROM ubuntu:22.04

# install app dependencies
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip install flask==3.0.*

# install app
COPY hello.py /

# final configuration
ENV FLASK_APP=hello
EXPOSE 8000
CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"]
```

Here's a breakdown of what this Dockerfile does:

* [Dockerfile syntax](#dockerfile-syntax)
* [Base image](#base-image)
* [Environment setup](#environment-setup)
* [Comments](#comments)
* [Installing dependencies](#installing-dependencies)
* [Copying files](#copying-files)
* [Setting environment variables](#setting-environment-variables)
* [Exposed ports](#exposed-ports)
* [Starting the application](#starting-the-application)

### [Dockerfile syntax](#dockerfile-syntax)

The first line to add to a Dockerfile is a [`# syntax` parser directive](https://docs.docker.com/reference/dockerfile/#syntax). While optional, this directive instructs the Docker builder what syntax to use when parsing the Dockerfile, and allows older Docker versions with [BuildKit enabled](https://docs.docker.com/build/buildkit/#getting-started) to use a specific [Dockerfile frontend](https://docs.docker.com/build/buildkit/frontend/) before starting the build. [Parser directives](https://docs.docker.com/reference/dockerfile/#parser-directives) must appear before any other comment, whitespace, or Dockerfile instruction in your Dockerfile, and should be the first line in Dockerfiles.

```dockerfile
# syntax=docker/dockerfile:1
```

> Tip
>
> We recommend using `docker/dockerfile:1`, which always points to the latest release of the version 1 syntax. BuildKit automatically checks for updates of the syntax before building, making sure you are using the most current version.

### [Base image](#base-image)

The line following the syntax directive defines what base image to use:

```dockerfile
FROM ubuntu:22.04
```

The [`FROM` instruction](https://docs.docker.com/reference/dockerfile/#from) sets your base image to the 22.04 release of Ubuntu. All instructions that follow are executed in this base image: an Ubuntu environment. The notation `ubuntu:22.04`, follows the `name:tag` standard for naming Docker images. When you build images, you use this notation to name your images. There are many public images you can leverage in your projects, by importing them into your build steps using the Dockerfile `FROM` instruction.

[Docker Hub](https://hub.docker.com/search?badges=official) contains a large set of official images that you can use for this purpose.

### [Environment setup](#environment-setup)

The following line executes a build command inside the base image.

```dockerfile
# install app dependencies
RUN apt-get update && apt-get install -y python3 python3-pip
```

This [`RUN` instruction](https://docs.docker.com/reference/dockerfile/#run) executes a shell in Ubuntu that updates the APT package index and installs Python tools in the container.

### [Comments](#comments)

Note the `# install app dependencies` line. This is a comment. Comments in Dockerfiles begin with the `#` symbol. As your Dockerfile evolves, comments can be instrumental to document how your Dockerfile works for any future readers and editors of the file, including your future self.

> Note
>
> You might've noticed that comments are denoted using the same symbol as the [syntax directive](#dockerfile-syntax) on the first line of the file. The symbol is only interpreted as a directive if the pattern matches a directive and appears at the beginning of the Dockerfile. Otherwise, it's treated as a comment.

### [Installing dependencies](#installing-dependencies)

The second `RUN` instruction installs the `flask` dependency required by the Python application.

```dockerfile
RUN pip install flask==3.0.*
```

A prerequisite for this instruction is that `pip` is installed into the build container. The first `RUN` command installs `pip`, which ensures that we can use the command to install the flask web framework.

### [Copying files](#copying-files)

The next instruction uses the [`COPY` instruction](https://docs.docker.com/reference/dockerfile/#copy) to copy the `hello.py` file from the local build context into the root directory of our image.

```dockerfile
COPY hello.py /
```

A [build context](https://docs.docker.com/build/concepts/context/) is the set of files that you can access in Dockerfile instructions such as `COPY` and `ADD`.

After the `COPY` instruction, the `hello.py` file is added to the filesystem of the build container.

### [Setting environment variables](#setting-environment-variables)

If your application uses environment variables, you can set environment variables in your Docker build using the [`ENV` instruction](https://docs.docker.com/reference/dockerfile/#env).

```dockerfile
ENV FLASK_APP=hello
```

This sets a Linux environment variable we'll need later. Flask, the framework used in this example, uses this variable to start the application. Without this, flask wouldn't know where to find our application to be able to run it.

### [Exposed ports](#exposed-ports)

The [`EXPOSE` instruction](https://docs.docker.com/reference/dockerfile/#expose) marks that our final image has a service listening on port `8000`.

```dockerfile
EXPOSE 8000
```

This instruction isn't required, but it is a good practice and helps tools and team members understand what this application is doing.

### [Starting the application](#starting-the-application)

Finally, [`CMD` instruction](https://docs.docker.com/reference/dockerfile/#cmd) sets the command that is run when the user starts a container based on this image.

```dockerfile
CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"]
```

This command starts the flask development server listening on all addresses on port `8000`. The example here uses the "exec form" version of `CMD`. It's also possible to use the "shell form":

```dockerfile
CMD flask run --host 0.0.0.0 --port 8000
```

There are subtle differences between these two versions, for example in how they trap signals like `SIGTERM` and `SIGKILL`. For more information about these differences, see [Shell and exec form](https://docs.docker.com/reference/dockerfile/#shell-and-exec-form)

## [Building](#building)

To build a container image using the Dockerfile example from the [previous section](#example), you use the `docker build` command:

```console
$ docker build -t test:latest .
```

The `-t test:latest` option specifies the name and tag of the image.

The single dot (`.`) at the end of the command sets the [build context](https://docs.docker.com/build/concepts/context/) to the current directory. This means that the build expects to find the Dockerfile and the `hello.py` file in the directory where the command is invoked. If those files aren't there, the build fails.

After the image has been built, you can run the application as a container with `docker run`, specifying the image name:

```console
$ docker run -p 127.0.0.1:8000:8000 test:latest
```

This publishes the container's port 8000 to `http://localhost:8000` on the Docker host.

> Tip
>
> To improve linting, code navigation, and vulnerability scanning of your Dockerfiles in Visual Studio Code see the [Docker DX](https://marketplace.visualstudio.com/items?itemName=docker.docker) extension.

----
url: https://docs.docker.com/guides/deno/configure-ci-cd/
----

# Configure CI/CD for your Deno application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a Deno application](https://docs.docker.com/guides/deno/containerize/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

   ```console
   $ git remote set-url origin https://github.com/your-username/your-repository.git
   ```

7. Run the following commands to stage, commit, and push your local repository to GitHub.

   ```console
   $ git add -A
   $ git commit -m "my commit"
   $ git push -u origin main
   ```

## [Step two: Set up the workflow](#step-two-set-up-the-workflow)

Set up your GitHub Actions workflow for building and pushing the image to Docker Hub.

1. Go to your repository on GitHub and then select the **Actions** tab.

2. Select **set up a workflow yourself**.

   This takes you to a page for creating a new GitHub actions workflow file in your repository, under `.github/workflows/main.yml` by default.

3. In the editor window, copy and paste the following YAML configuration and commit the changes.

   ```yaml
   name: ci

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         -
           name: Login to Docker Hub
           uses: docker/login-action@v4
           with:
             username: ${{ vars.DOCKER_USERNAME }}
             password: ${{ secrets.DOCKERHUB_TOKEN }}
         -
           name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v4
         -
           name: Build and push
           uses: docker/build-push-action@v7
           with:
             platforms: linux/amd64,linux/arm64
             push: true
             tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
   ```

In this section, you learned how to set up a GitHub Actions workflow for your Deno application.

Related information:

* [Introduction to GitHub Actions](https://docs.docker.com/build/ci/github-actions/)
* [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)

## [Next steps](#next-steps)

Next, learn how you can locally test and debug your workloads on Kubernetes before deploying.

[Test your Deno deployment »](https://docs.docker.com/guides/deno/deploy/)

----
url: https://docs.docker.com/reference/cli/docker/compose/convert/
----

# docker compose convert

***

| Description                                                               | Converts the compose file to platform's canonical format |
| ------------------------------------------------------------------------- | -------------------------------------------------------- |
| Usage                                                                     | `docker compose convert [OPTIONS] [SERVICE...]`          |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker compose config`                                  |

## [Description](#description)

`docker compose convert` renders the actual data model to be applied on the target platform. When used with the Docker engine, it merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into the canonical format.

To allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`

## [Options](#options)

| Option                    | Default | Description                                                                  |
| ------------------------- | ------- | ---------------------------------------------------------------------------- |
| `--format`                | `yaml`  | Format the output. Values: \[yaml \| json]                                   |
| `--hash`                  |         | Print the service config hash, one per line.                                 |
| `--images`                |         | Print the image names, one per line.                                         |
| `--no-consistency`        |         | Don't check model consistency - warning: may produce invalid Compose output  |
| `--no-interpolate`        |         | Don't interpolate environment variables.                                     |
| `--no-normalize`          |         | Don't normalize compose model.                                               |
| `-o, --output`            |         | Save to file (default to stdout)                                             |
| `--profiles`              |         | Print the profile names, one per line.                                       |
| `-q, --quiet`             |         | Only validate the configuration, don't print anything.                       |
| `--resolve-image-digests` |         | Pin image tags to digests.                                                   |
| `--services`              |         | Print the service names, one per line.                                       |
| `--volumes`               |         | Print the volume names, one per line.                                        |

----
url: https://docs.docker.com/reference/api/extensions-sdk/SpawnOptions/
----

# Interface: SpawnOptions

***

Table of contents

***

**`Since`**

0.3.0

## [Hierarchy](#hierarchy)

* [`ExecOptions`](https://docs.docker.com/reference/api/extensions-sdk/ExecOptions/)

  ↳ **`SpawnOptions`**

## [Properties](#properties)

### [cwd](#cwd)

• `Optional` **cwd**: `string`

#### [Inherited from](#inherited-from)

[ExecOptions](https://docs.docker.com/reference/api/extensions-sdk/ExecOptions/).[cwd](https://docs.docker.com/reference/api/extensions-sdk/ExecOptions/#cwd)

***

### [env](#env)

• `Optional` **env**: `ProcessEnv`

#### [Inherited from](#inherited-from-1)

[ExecOptions](https://docs.docker.com/reference/api/extensions-sdk/ExecOptions/).[env](https://docs.docker.com/reference/api/extensions-sdk/ExecOptions/#env)

***

### [stream](#stream)

• **stream**: [`ExecStreamOptions`](https://docs.docker.com/reference/api/extensions-sdk/ExecStreamOptions/)

----
url: https://docs.docker.com/reference/cli/docker/compose/images/
----

# docker compose images

***

| Description | List images used by the created containers     |
| ----------- | ---------------------------------------------- |
| Usage       | `docker compose images [OPTIONS] [SERVICE...]` |

## [Description](#description)

List images used by the created containers

## [Options](#options)

| Option        | Default | Description                                 |
| ------------- | ------- | ------------------------------------------- |
| `--format`    | `table` | Format the output. Values: \[table \| json] |
| `-q, --quiet` |         | Only display IDs                            |

----
url: https://docs.docker.com/reference/cli/docker/config/rm/
----

# docker config rm

***

| Description                                                               | Remove one or more configs            |
| ------------------------------------------------------------------------- | ------------------------------------- |
| Usage                                                                     | `docker config rm CONFIG [CONFIG...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker config remove`                |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Removes the specified configs from the Swarm.

For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).

> Note
>
> This is a cluster management command, and must be executed on a Swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Examples](#examples)

This example removes a config:

```console
$ docker config rm my_config
sapth4csdo5b6wz2p5uimh5xg
```

> Warning
>
> This command doesn't ask for confirmation before removing a config.

----
url: https://docs.docker.com/reference/api/hub/latest/
----

# Docker Hub API reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Hub API.

* [Open Markdown](https://docs.docker.com/reference/api/hub/latest.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/hub/latest.yaml)

[](/reference)

* General

  * Changelog

  * Resources

  * Rate Limiting

  * Authentication

    * Types

      * Password
      * Personal Access Token (PAT)
      * Organization Access Token (OAT)

    * Labels

* API

  * Authentication

    * postCreate an authentication token
    * postSecond factor authentication
    * postCreate access token

  * Personal Access Tokens

    * postCreate personal access token
    * getList personal access tokens
    * patchUpdate personal access token
    * getGet personal access token
    * delDelete personal access token

  * Audit Logs

    * getList audit log actions
    * getList audit log events

  * Org Settings

    * getGet organization settings
    * putUpdate organization settings

  * Repositories

    * getList repository tags
    * headCheck repository tags
    * getRead repository tag
    * headCheck repository tag
    * patchUpdate repository immutable tags
    * postVerify repository immutable tags
    * postAssign a group (Team) to a repository for access
    * getList repositories in a namespace
    * postCreate a new repository
    * getGet repository in a namespace
    * headCheck repository in a namespace

  * SCIM

    * getGet service provider config
    * getList resource types
    * getGet a resource type
    * getList schemas
    * getGet a schema
    * getList users
    * postCreate user
    * getGet a user
    * putUpdate a user

  * Organizations

    * getList org members
    * getExport org members CSV
    * putUpdate org member (role)
    * delRemove member from org

  * Organization Access Tokens

    * postCreate access token
    * getList access tokens
    * getGet access token
    * patchUpdate access token
    * delDelete access token

  * Groups (Teams)

    * getGet groups of an organization
    * postCreate a new group
    * getGet a group of an organization
    * putUpdate the details for an organization group
    * patchUpdate some details for an organization group
    * delDelete an organization group
    * getList members of a group
    * postAdd a member to a group
    * delRemove a user from a group

  * Invites

    * getList org invites
    * delCancel an invite
    * patchResend an invite
    * postBulk create invites

[API docs by Redocly](https://redocly.com/redoc/)

# Docker HUB API (2-beta)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/hub/latest.yaml)

Docker Hub is a service provided by Docker for finding and sharing container images with your team.

It is the world's largest library and community for container images.

In addition to the [Docker Hub UI](https://docs.docker.com/docker-hub/) and [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental), Docker provides an API that allows you to interact with Docker Hub.

Browse through the Docker Hub API documentation to explore the supported endpoints.

## [](#tag/changelog)Changelog

See the [Changelog](/reference/api/hub/changelog) for a summary of changes across Docker Hub API versions.

## [](#tag/resources)Resources

The following resources are available to interact with the documented API:

* [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme) (currently experimental)

## [](#tag/rate-limiting)Rate Limiting

The Docker Hub API is limited on the amount of requests you can perform per minute against it.

If you haven't hit the limit, each request to the API will return the following headers in the response.

* `X-RateLimit-Limit` - The limit of requests per minute.
* `X-RateLimit-Remaining` - The remaining amount of calls within the limit period.
* `X-RateLimit-Reset` - The unix timestamp of when the remaining resets.

If you have hit the limit, you will receive a response status of `429` and the `Retry-After` header in the response.

The [`Retry-After` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After) specifies the number of seconds to wait until you can call the API again.

**Note**: These rate limits are separate from anti-abuse and Docker Hub download, or pull rate limiting. To learn more about Docker Hub pull rate limiting, see [Usage and limits](https://docs.docker.com/docker-hub/usage/).

## [](#tag/authentication)Authentication

Most Docker Hub API endpoints require you to authenticate using your Docker credentials before using them.

Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your subscription (Personal, Pro, or Team) and your account's permissions.

To learn more about the features available in each subscription and to upgrade your existing subscription, see [Docker Pricing](https://www.docker.com/pricing?ref=Docs\&refAction=DocsApiHub).

## [](#tag/authentication/Types)Types

The Docker Hub API supports the following authentication types.

You must use each authentication type with the [Create access token](#tag/authentication-api/operation/AuthCreateAccessToken) route to obtain a bearer token.

## [](#tag/authentication/Types/Password)Password

Using a username and password is the most powerful, yet least secure way to authenticate with Docker as a user. It allows access to resources for the user without scopes.

*In general, it is recommended to use a personal access token (PAT) instead.*

***The password authentication type is not available if your organization has SSO enforced.***

## [](#tag/authentication/Types/Personal-Access-Token-\(PAT\))Personal Access Token (PAT)

Using a username and PAT is the most secure way to authenticate with Docker as a user. PATs are scoped to specific resources and scopes.

Currently, a PAT is a more secure password due to limited functionality. In the future, we may add fine-grained access like organization access tokens for enhanced usage and security.

## [](#tag/authentication/Types/Organization-Access-Token-\(OAT\))Organization Access Token (OAT)

Organization access tokens are scoped to specific resources and scopes in an organization. They are managed by organization owners.

These tokens are meant for automation and are not meant to be used by users.

## [](#tag/authentication/Labels)Labels

These labels will show up on routes in this reference that allow for use of bearer tokens issued from them.

## [](#tag/authentication-api)Authentication

The authentication endpoints allow you to authenticate with Docker Hub APIs.

For more information, see [Authentication](#tag/authentication).

## [](#tag/authentication-api/operation/PostUsersLogin)Create an authentication token Deprecated

Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.

The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.

***As of September 16, 2024, this route requires a personal access token (PAT) instead of a password if your organization has SSO enforced.***

**Deprecated**: Use \[[Create access token](#tag/authentication-api/operation/AuthCreateAccessToken)] instead.

##### Request Body schema: application/jsonrequired

Login details.

|                  |                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| usernamerequired | stringThe username of the Docker Hub account to authenticate with.                                |
| passwordrequired | stringThe password or personal access token (PAT) of the Docker Hub account to authenticate with. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/users/login

### Request samples

* Payload

Content type

application/json

`{
"username": "myusername",
"password": "p@ssw0rd"

## [](#tag/authentication-api/operation/PostUsers2FALogin)Second factor authentication

When a user has two-factor authentication (2FA) enabled, this is the second call to perform after `/v2/users/login` call.

Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs.

The returned token is used in the HTTP Authorization header like `Authorization: Bearer {TOKEN}`.

Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository.

##### Request Body schema: application/jsonrequired

Login details.

|                           |                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------- |
| login\_2fa\_tokenrequired | stringThe intermediate 2FA token returned from `/v2/users/login` API.                  |
| coderequired              | stringThe Time-based One-Time Password of the Docker Hub account to authenticate with. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/users/2fa-login

## [](#tag/authentication-api/operation/AuthCreateAccessToken)Create access token

Creates and returns a short-lived access token in JWT format for use as a bearer when calling Docker APIs.

If successful, the access token returned should be used in the HTTP Authorization header like `Authorization: Bearer {access_token}`.

***If your organization has SSO enforced, you must use a personal access token (PAT) instead of a password.***

##### Request Body schema: application/json

|                    |                                                                                                                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| identifierrequired | stringThe identifier of the account to create an access token for. If using a password or personal access token, this must be a username. If using an organization access token, this must be an organization name. |
| secretrequired     | stringThe secret of the account to create an access token for. This can be a password, personal access token, or organization access token.                                                                         |

### Responses

Docker HUB API

https\://hub.docker.com/v2/auth/token

### Request samples

* Payload

Content type

application/json

`{
"identifier": "myusername",
"secret": "dckr_pat_124509ugsdjga93"
}`

### Response samples

* 200
* 401

Content type

application/json

`{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}`

## [](#tag/access-tokens)Personal Access Tokens

The Personal Access Token endpoints lets you manage personal access tokens. For more information, see [Access Tokens](https://docs.docker.com/security/access-tokens/).

You can use a personal access token instead of a password in the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/) or in the [Create an authentication token](#operation/PostUsersLogin) route to obtain a bearer token.

### Scopes

For each scope grouping (in this case "repo"), you only need to define 1 scope as any lower scopes are assumed. For example: If you define `repo:write`, the API assumes the scope of both `repo:read` *and* `repo:public_read` as well. If you were to define both `repo:write` *and* `repo:read`, then `repo:read` is assumed by `repo:write` and ignored.

***Treat your personal access token like your password and keep it secret. You cannot retrieve your token after it is generated.***

## [](#tag/access-tokens/paths/~1v2~1access-tokens/post)Create personal access token

Creates and returns a personal access token.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/jsonrequired

|                      |                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| token\_labelrequired | string \[ 1 .. 100 ] charactersFriendly name for you to identify the token.                                      |
| scopesrequired       | Array of stringsValid scopes: "repo:admin", "repo:write", "repo:read", "repo:public\_read"                       |
| expires\_at          | string \<date-time>Optional expiration date for the token. If omitted, the token will remain valid indefinitely. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/access-tokens

### Request samples

* Payload

Content type

application/json

`{
"token_label": "My read only token",
"scopes": [
"repo:read"
],
"expires_at": "2021-10-28T18:30:19.520861Z"
}`

### Response samples

* 201
* 400
* 401

Content type

application/json

`{
"uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb",
"client_id": "HUB",
"creator_ip": "127.0.0.1",
"creator_ua": "some user agent",
"created_at": "2021-07-20T12:00:00.000000Z",
"last_used": null,
"generated_by": "manual",
"is_active": true,
"token": "a7a5ef25-8889-43a0-8cc7-f2a94268e861",
"token_label": "My read only token",
"scopes": [
"repo:read"
],
"expires_at": "2021-10-28T18:30:19.520861Z"
}`

## [](#tag/access-tokens/paths/~1v2~1access-tokens/get)List personal access tokens

Returns a paginated list of personal access tokens.

##### Authorizations:

*bearerAuth*

##### query Parameters

|            |                   |
| ---------- | ----------------- |
| page       | numberDefault: 1  |
| page\_size | numberDefault: 10 |

### Responses

Docker HUB API

https\://hub.docker.com/v2/access-tokens

### Response samples

* 200
* 400
* 401

Content type

application/json

`{
"count": 1,
"next": null,
"previous": null,
"active_count": 1,
"results": [
{
"uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb",
"client_id": "HUB",
"creator_ip": "127.0.0.1",
"creator_ua": "some user agent",
"created_at": "2021-07-20T12:00:00.000000Z",
"last_used": null,
"generated_by": "manual",
"is_active": true,
"token": "",
"token_label": "My read only token",
"scopes": [
"repo:read"
],
"expires_at": "2021-10-28T18:30:19.520861Z"
}
]
}`

## [](#tag/access-tokens/paths/~1v2~1access-tokens~1{uuid}/patch)Update personal access token

Updates a personal access token partially. You can either update the token's label or enable/disable it.

##### Authorizations:

*bearerAuth*

##### path Parameters

|              |        |
| ------------ | ------ |
| uuidrequired | string |

##### Request Body schema: application/jsonrequired

|              |                                 |
| ------------ | ------------------------------- |
| token\_label | string \[ 1 .. 100 ] characters |
| is\_active   | boolean                         |

### Responses

Docker HUB API

https\://hub.docker.com/v2/access-tokens/{uuid}

### Request samples

* Payload

Content type

application/json

`{
"token_label": "My read only token",
"is_active": false
}`

### Response samples

* 200
* 400
* 401

Content type

application/json

`{
"uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb",
"client_id": "HUB",
"creator_ip": "127.0.0.1",
"creator_ua": "some user agent",
"created_at": "2021-07-20T12:00:00.000000Z",
"last_used": null,
"generated_by": "manual",
"is_active": true,
"token": "a7a5ef25-8889-43a0-8cc7-f2a94268e861",
"token_label": "My read only token",
"scopes": [
"repo:read"
],
"expires_at": "2021-10-28T18:30:19.520861Z"
}`

## [](#tag/access-tokens/paths/~1v2~1access-tokens~1{uuid}/get)Get personal access token

Returns a personal access token by UUID.

##### Authorizations:

*bearerAuth*

##### path Parameters

|              |        |
| ------------ | ------ |
| uuidrequired | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/access-tokens/{uuid}

### Response samples

* 200
* 401
* 404

Content type

application/json

`{
"uuid": "b30bbf97-506c-4ecd-aabc-842f3cb484fb",
"client_id": "HUB",
"creator_ip": "127.0.0.1",
"creator_ua": "some user agent",
"created_at": "2021-07-20T12:00:00.000000Z",
"last_used": null,
"generated_by": "manual",
"is_active": true,
"token": "",
"token_label": "My read only token",
"scopes": [
"repo:read"
],
"expires_at": "2021-10-28T18:30:19.520861Z"
}`

## [](#tag/access-tokens/paths/~1v2~1access-tokens~1{uuid}/delete)Delete personal access token

Deletes a personal access token permanently. This cannot be undone.

##### Authorizations:

*bearerAuth*

##### path Parameters

|              |        |
| ------------ | ------ |
| uuidrequired | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/access-tokens/{uuid}

### Response samples

* 401
* 404

Content type

application/json

`{
"detail": "string",
"message": "string"
}`

## [](#tag/audit-logs)Audit Logs

The Audit Logs API endpoints allow you to query audit log events across a namespace.

For more information, see [Audit Logs](https://docs.docker.com/admin/activity-logs/).

## [](#tag/audit-logs/operation/AuditLogs_ListAuditActions)List audit log actions

List audit log actions for a namespace to be used as a filter for querying audit log events.

##### Authorizations:

*bearerAuth*

##### path Parameters

|                 |                                                 |
| --------------- | ----------------------------------------------- |
| accountrequired | stringNamespace to query audit log actions for. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/auditlogs/{account}/actions

### Response samples

* 200
* 429
* 500
* default

Content type

application/json

`{
"actions": {
"billing": {
"actions": [
{
"name": "plan.upgrade",
"description": "Occurs when your organization’s billing plan is upgraded to a higher tier plan.",
"label": "Plan Upgraded"
},
{
"name": "plan.downgrade",
"description": "Occurs when your organization’s billing plan is downgraded to a lower tier plan.",
"label": "Plan Downgraded"
},
{
"name": "plan.seat_add",
"description": "Occurs when a seat is added to your organization’s billing plan.",
"label": "Seat Added"
},
{
"name": "plan.seat_remove",
"description": "Occurs when a seat is removed from your organization’s billing plan.",
"label": "Seat Removed"
},
{
"name": "plan.cycle_change",
"description": "Occurs when there is a change in the recurring interval that your organization is charged.",
"label": "Billing Cycle Changed"
},
{
"name": "plan.downgrade_cancel",
"description": "Occurs when a scheduled plan downgrade for your organization is canceled.",
"label": "Plan Downgrade Canceled"
},
{
"name": "plan.seat_removal_cancel",
"description": "Occurs when a scheduled seat removal for an organization’s billing plan is canceled.",
"label": "Seat Removal Canceled"
},
{
"name": "plan.upgrade.request",
"description": "Occurs when a user in your organization requests a plan upgrade.",
"label": "Plan Upgrade Requested"
},
{
"name": "plan.downgrade.request",
"description": "Occurs when a user in your organization requests a plan downgrade.",
"label": "Plan Downgrade Requested"
},
{
"name": "plan.seat_add.request",
"description": "Occurs when a user in your organization requests an increase in the number of seats.",
"label": "Seat Addition Requested"
},
{
"name": "plan.seat_removal.request",
"description": "Occurs when a user in your organization requests a decrease in the number of seats.",
"label": "Seat Removal Requested"
},
{
"name": "plan.cycle_change.request",
"description": "Occurs when a user in your organization requests a change in the billing cycle.",
"label": "Billing Cycle Change Requested"
},
{
"name": "plan.downgrade_cancel.request",
"description": "Occurs when a user in your organization requests a cancellation of a scheduled plan downgrade.",
"label": "Plan Downgrade Cancellation Requested"
},
{
"name": "plan.seat_removal_cancel.request",
"description": "Occurs when a user in your organization requests a cancellation of a scheduled seat removal.",
"label": "Seat Removal Cancellation Requested"
},
{
"name": "plan.product_change",
"description": "Occurs when there is a change in the product that your organization subscribes to.",
"label": "Billing Product Changed"
}
],
"label": "Billing"
},
"enterprise": {
"actions": [
{
"name": "setting.policy.create",
"description": "Details of adding an admin settings policy",
"label": "Policy created"
},
{
"name": "setting.policy.update",
"description": "Details of updating an admin settings policy",
"label": "Policy updated"
},
{
"name": "setting.policy.delete",
"description": "Details of deleting an admin settings policy",
"label": "Policy deleted"
},
{
"name": "setting.policy.transfer",
"description": "Details of transferring an admin settings policy to another owner",
"label": "Policy transferred"
},
{
"name": "sso.connection.create",
"description": "Details of creating a new org/company SSO connection",
"label": "Create SSO Connection"
},
{
"name": "sso.connection.update",
"description": "Details of updating an existing org/company SSO connection",
"label": "Update SSO Connection"
},
{
"name": "sso.connection.delete",
"description": "Details of deleting an existing org/company SSO connection",
"label": "Delete SSO Connection"
},
{
"name": "sso.connection.enforcement_toggle",
"description": "Details of toggling enforcement on an existing org/company SSO connection",
"label": "Enforce SSO"
},
{
"name": "sso.connection.scim_toggle",
"description": "Details of toggling SCIM on an existing org/company SSO connection",
"label": "Enforce SCIM"
},
{
"name": "sso.connection.scim_token_refresh",
"description": "Details of a SCIM token refresh on an existing org/company SSO connection",
"label": "Refresh SCIM Token"
},
{
"name": "sso.connection.connection_type_change",
"description": "Details of a connection type change on an existing org/company SSO connection",
"label": "Change SSO Connection Type"
},
{
"name": "sso.connection.jit_toggle",
"description": "Details of a JIT toggle on an existing org/company SSO connection",
"label": "Toggle JIT provisioning"
}
],
"label": "Enterprise"
},
"offload": {
"actions": [
{
"name": "lease.start",
"description": "Details of the started Offload lease.",
"label": "Offload lease start"
},
{
"name": "lease.end",
"description": "Details of the ended Offload lease.",
"label": "Offload lease end"
}
],
"label": "Offload"
},
"oidc": {
"actions": [
{
"name": "connection.create",
"description": "Details of creating an OIDC connection.",
"label": "OIDC connection created"
},
{
"name": "connection.update",
"description": "Details of updating an OIDC connection.",
"label": "OIDC connection updated"
},
{
"name": "connection.delete",
"description": "Details of deleting an OIDC connection.",
"label": "OIDC connection deleted"
}
],
"label": "OIDC"
},
"org": {
"actions": [
{
"name": "create",
"description": "Activities related to the creation of a new organization",
"label": "Organization Created"
},
{
"name": "member.add",
"description": "Details of the member added to your organization",
"label": "Organization Member Added"
},
{
"name": "member.remove",
"description": "Details about the member removed from your organization",
"label": "Organization Member Removed"
},
{
"name": "member.role.change",
"description": "Details about the role changed for a member in your organization",
"label": "Member Role Changed"
},
{
"name": "member.invite.send",
"description": "Details of the member invited to your organization",
"label": "Org Member Invited"
},
{
"name": "team.create",
"description": "Activities related to the creation of a team",
"label": "Organization Created"
},
{
"name": "team.update",
"description": "Activities related to the modification of a team",
"label": "Organization Deleted"
},
{
"name": "team.delete",
"description": "Activities related to the deletion of a team",
"label": "Organization Deleted"
},
{
"name": "team.member.add",
"description": "Details of the member added to your team",
"label": "Team Member Added"
},
{
"name": "team.member.remove",
"description": "Details of the member removed from your team",
"label": "Team Member Removed"
},
{
"name": "domain.create",
"description": "Details of the single sign-on domain added to your organization",
"label": "Single Sign-On domain added"
},
{
"name": "domain.verify",
"description": "Details of the single sign-on domain verified for your organization",
"label": "Single Sign-On domain verified"
},
{
"name": "domain.delete",
"description": "Details of the single sign-on domain removed from your organization",
"label": "Single Sign-On domain deleted"
},
{
"name": "domain.auto-provisioning.toggle",
"description": "Details of toggling the Auto-Provisioning feature on a domain on or off",
"label": "Organization Auto-Provisioning Toggled"
},
{
"name": "settings.update",
"description": "Details related to the organization setting that was updated",
"label": "Organization Settings Updated"
},
{
"name": "registry_access.enabled",
"description": "Activities related to enabling Registry Access Management",
"label": "Registry Access Management enabled"
},
{
"name": "registry_access.disabled",
"description": "Activities related to disabling Registry Access Management",
"label": "Registry Access Management disabled"
},
{
"name": "registry_access.registry_added",
"description": "Activities related to the addition of a registry",
"label": "Registry Access Management registry added"
},
{
"name": "registry_access.registry_updated",
"description": "Details related to the registry that was updated",
"label": "Registry Access Management registry updated"
},
{
"name": "registry_access.registry_removed",
"description": "Activities related to the removal of a registry",
"label": "Registry Access Management registry removed"
},
{
"name": "access_token.create",
"description": "Access token created in organization",
"label": "Access token created"
},
{
"name": "access_token.update",
"description": "Access token updated in organization",
"label": "Access token updated"
},
{
"name": "access_token.delete",
"description": "Access token deleted in organization",
"label": "Access token deleted"
},
{
"name": "customrole.create",
"description": "A custom role was created",
"label": "Custom role created"
},
{
"name": "customrole.update",
"description": "An existing custom role was updated",
"label": "Custom role updated"
},
{
"name": "customrole.delete",
"description": "A custom role was deleted",
"label": "Custom role deleted"
},
{
"name": "securepolicyconfigure.create",
"description": "A secure policy configuration was created",
"label": "Secure Policy Configuration created"
},
{
"name": "securepolicyconfigure.update",
"description": "A secure policy configuration was updated",
"label": "Secure Policy Configuration updated"
},
{
"name": "securepolicyconfigure.delete",
"description": "A secure policy configuration was deleted",
"label": "Secure Policy Configuration deleted"
},
{
"name": "securepolicyclient.create",
"description": "A secure policy client was created",
"label": "Secure Policy Client created"
},
{
"name": "securepolicyclient.update",
"description": "A secure policy client was updated",
"label": "Secure Policy Client updated"
},
{
"name": "securepolicyclient.delete",
"description": "A secure policy client was deleted",
"label": "Secure Policy Client deleted"
},
{
"name": "securepolicyprofile.create",
"description": "A secure policy profile was created",
"label": "Secure Policy Profile created"
},
{
"name": "securepolicyprofile.update",
"description": "A secure policy profile was updated",
"label": "Secure Policy Profile updated"
},
{
"name": "securepolicyprofile.delete",
"description": "A secure policy profile was deleted",
"label": "Secure Policy Profile deleted"
}
],
"label": "Organization"
},
"repo": {
"actions": [
{
"name": "create",
"description": "Activities related to the creation of a new repository",
"label": "Repository Created"
},
{
"name": "update",
"description": "Activities related to the modification of a repository",
"label": "Repository Updated"
},
{
"name": "delete",
"description": "Activities related to the deletion of a repository",
"label": "Repository Deleted"
},
{
"name": "change_privacy",
"description": "Details related to the privacy policies that were updated",
"label": "Privacy Changed"
},
{
"name": "category.updated",
"description": "Details related to updating a repository categories",
"label": "Categories updated"
},
{
"name": "immutable.tags.updated",
"description": "Details related to updating tag immutability of a repository",
"label": "Tag immutability updated"
},
{
"name": "tag.push",
"description": "Activities related to the tags pushed",
"label": "Tag Pushed"
},
{
"name": "tag.delete",
"description": "Activities related to the tags deleted",
"label": "Tag Deleted"
}
],
"label": "Repository"
}
}
}`

## [](#tag/audit-logs/operation/AuditLogs_ListAuditLogs)List audit log events

List audit log events for a given namespace.

##### Authorizations:

*bearerAuth*

##### path Parameters

|                 |                                          |
| --------------- | ---------------------------------------- |
| accountrequired | stringNamespace to query audit logs for. |

##### query Parameters

|            |                                                                                                                                                                                                                                                                          |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| action     | stringaction name one of \["repo.tag.push", ...]. Optional parameter to filter specific audit log actions.                                                                                                                                                               |
| name       | stringname. Optional parameter to filter audit log events to a specific name. For repository events, this is the name of the repository. For organization events, this is the name of the organization. For team member events, this is the username of the team member. |
| actor      | stringactor name. Optional parameter to filter audit log events to the specific user who triggered the event.                                                                                                                                                            |
| from       | string \<date-time>Start of the time window you wish to query audit events for.                                                                                                                                                                                          |
| to         | string \<date-time>End of the time window you wish to query audit events for.                                                                                                                                                                                            |
| page       | integer \<int32>Default: 1page - specify page number. Page number to get.                                                                                                                                                                                                |
| page\_size | integer \<int32>Default: 25page\_size - specify page size. Number of events to return per page.                                                                                                                                                                          |

### Responses

Docker HUB API

https\://hub.docker.com/v2/auditlogs/{account}

### Response samples

* 200
* 429
* 500
* default

Content type

application/json

`{
"logs": [
{
"account": "docker",
"action": "repo.tag.push",
"name": "docker/example",
"actor": "docker",
"data": {
"digest": "sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa",
"tag": "latest"
},
"timestamp": "2021-02-19T01:34:35Z",
"action_description": "pushed the tag latest with the digest sha256:c1ae9c435032a to the repository docker/example\n"
}
]
}`

## [](#tag/org-settings)Org Settings

The Org Settings API endpoints allow you to manage your organization's settings.

## [](#tag/org-settings/paths/~1v2~1orgs~1{name}~1settings/get)Get organization settings

Returns organization settings by name.

##### Authorizations:

*bearerAuth*

##### path Parameters

|              |                                 |
| ------------ | ------------------------------- |
| namerequired | stringName of the organization. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{name}/settings

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"restricted_images": {
"enabled": true,
"allow_official_images": true,
"allow_verified_publishers": true
}
}`

## [](#tag/org-settings/paths/~1v2~1orgs~1{name}~1settings/put)Update organization settings

Updates an organization's settings. Some settings are only used when the organization is on a business subscription.

***Only users with administrative privileges for the organization (owner role) can modify these settings.***

The following settings are only used on a business subscription:

* `restricted_images`

##### Authorizations:

*bearerAuth*

##### path Parameters

|              |                                 |
| ------------ | ------------------------------- |
| namerequired | stringName of the organization. |

##### Request Body schema: application/jsonrequired

|          |        |
| -------- | ------ |
| required | object |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{name}/settings

### Request samples

* Payload

Content type

application/json

`{
"restricted_images": {
"enabled": true,
"allow_official_images": true,
"allow_verified_publishers": true
}
}`

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"restricted_images": {
"enabled": true,
"allow_official_images": true,
"allow_verified_publishers": true
}
}`

## [](#tag/repositories)Repositories

The repository endpoints allow you to access your repository's tags.

## [](#tag/repositories/operation/ListRepositoryTags)List repository tags

##### Authorizations:

*bearerAuth*

##### path Parameters

|                    |        |
| ------------------ | ------ |
| namespacerequired  | string |
| repositoryrequired | string |

##### query Parameters

|            |                                                                     |
| ---------- | ------------------------------------------------------------------- |
| page       | integerPage number to get. Defaults to 1.                           |
| page\_size | integerNumber of items to get per page. Defaults to 10. Max of 100. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/namespaces/{namespace}/repositories/{repository}/tags

### Response samples

* 200
* 403
* 404

Content type

application/json

`{
"count": 0,
"next": "string",
"previous": "string",
"results": [
{
"id": 0,
"images": {
"architecture": "string",
"features": "string",
"variant": "string",
"digest": "string",
"layers": [
{
"digest": "string",
"size": 0,
"instruction": "string"
}
],
"os": "string",
"os_features": "string",
"os_version": "string",
"size": 0,
"status": "active",
"last_pulled": "2021-01-05T21:06:53.506400Z",
"last_pushed": "2021-01-05T21:06:53.506400Z"
},
"creator": 0,
"last_updated": "2021-01-05T21:06:53.506400Z",
"last_updater": 0,
"last_updater_username": "string",
"name": "string",
"repository": 0,
"full_size": 0,
"v2": "string",
"status": "active",
"tag_last_pulled": "2021-01-05T21:06:53.506400Z",
"tag_last_pushed": "2021-01-05T21:06:53.506400Z"
}
]
}`

## [](#tag/repositories/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags/head)Check repository tags

##### Authorizations:

*bearerAuth*

##### path Parameters

|                    |        |
| ------------------ | ------ |
| namespacerequired  | string |
| repositoryrequired | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/namespaces/{namespace}/repositories/{repository}/tags

### Response samples

* 403
* 404

Content type

application/json

`{
"detail": "string",
"message": "string"
}`

## [](#tag/repositories/operation/GetRepositoryTag)Read repository tag

##### Authorizations:

*bearerAuth*

##### path Parameters

|                    |        |
| ------------------ | ------ |
| namespacerequired  | string |
| repositoryrequired | string |
| tagrequired        | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}

### Response samples

* 200
* 403
* 404

Content type

application/json

`{
"id": 0,
"images": {
"architecture": "string",
"features": "string",
"variant": "string",
"digest": "string",
"layers": [
{
"digest": "string",
"size": 0,
"instruction": "string"
}
],
"os": "string",
"os_features": "string",
"os_version": "string",
"size": 0,
"status": "active",
"last_pulled": "2021-01-05T21:06:53.506400Z",
"last_pushed": "2021-01-05T21:06:53.506400Z"
},
"creator": 0,
"last_updated": "2021-01-05T21:06:53.506400Z",
"last_updater": 0,
"last_updater_username": "string",
"name": "string",
"repository": 0,
"full_size": 0,
"v2": "string",
"status": "active",
"tag_last_pulled": "2021-01-05T21:06:53.506400Z",
"tag_last_pushed": "2021-01-05T21:06:53.506400Z"
}`

## [](#tag/repositories/paths/~1v2~1namespaces~1{namespace}~1repositories~1{repository}~1tags~1{tag}/head)Check repository tag

##### Authorizations:

*bearerAuth*

##### path Parameters

|                    |        |
| ------------------ | ------ |
| namespacerequired  | string |
| repositoryrequired | string |
| tagrequired        | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}

### Response samples

* 403
* 404

Content type

application/json

`{
"detail": "string",
"message": "string"
}`

## [](#tag/repositories/operation/UpdateRepositoryImmutableTags)Update repository immutable tags

Updates the immutable tags configuration for this repository.

**Only users with administrative privileges for the repository can modify these settings.**

##### Authorizations:

*bearerAuth*

##### path Parameters

|                    |        |
| ------------------ | ------ |
| namespacerequired  | string |
| repositoryrequired | string |

##### Request Body schema: application/jsonrequired

|                                |                                             |
| ------------------------------ | ------------------------------------------- |
| immutable\_tagsrequired        | booleanWhether immutable tags are enabled   |
| immutable\_tags\_rulesrequired | Array of stringsList of immutable tag rules |

### Responses

Docker HUB API

https\://hub.docker.com/v2/namespaces/{namespace}/repositories/{repository}/immutabletags

### Request samples

* Payload

Content type

application/json

`{
"immutable_tags": true,
"immutable_tags_rules": [
"v.*",
".*-RELEASE"
]
}`

### Response samples

* 200
* 400
* 401
* 403
* 404

Content type

application/json

`{
"user": "string",
"name": "string",
"namespace": "string",
"repository_type": "string",
"status": 0,
"status_description": "string",
"description": "string",
"is_private": true,
"is_automated": true,
"star_count": 0,
"pull_count": 0,
"last_updated": "2021-01-05T21:06:53.506400Z",
"last_modified": "2021-01-05T21:06:53.506400Z",
"date_registered": "2021-01-05T21:06:53.506400Z",
"collaborator_count": 0,
"affiliation": "string",
"hub_user": "string",
"has_starred": true,
"full_description": "string",
"permissions": {
"read": true,
"write": true,
"admin": true
},
"media_types": [
"string"
],
"content_types": [
"string"
],
"categories": [
{
"name": "Databases",
"slug": "databases"
}
],
"immutable_tags_settings": {
"enabled": true,
"rules": [
"string"
]
},
"storage_size": 0,
"source": "string"
}`

## [](#tag/repositories/operation/VerifyRepositoryImmutableTags)Verify repository immutable tags

Validates the immutable tags regex pass in parameter and returns a list of tags matching it in this repository.

**Only users with administrative privileges for the repository call this endpoint.**

##### Authorizations:

*bearerAuth*

##### path Parameters

|                    |        |
| ------------------ | ------ |
| namespacerequired  | string |
| repositoryrequired | string |

##### Request Body schema: application/jsonrequired

|               |                                                                                                                                                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| regexrequired | string^\[a-z0-9]+((\\\\.\|\_\|\_\_\|-+)\[a-z0-9]+)\*(\\\\/\[a-z0-...Immutable tags rule regex pattern. Must match format: \[a-z0-9]+((\\.\|*\|\_\_\|-+)\[a-z0-9]+)\*(\\/\[a-z0-9]+((\\.\|*\|\_\_\|-+)\[a-z0-9]+)*)* |

### Responses

Docker HUB API

https\://hub.docker.com/v2/namespaces/{namespace}/repositories/{repository}/immutabletags/verify

### Request samples

* Payload

Content type

application/json

`{
"regex": "v.*"
}`

### Response samples

* 200
* 400
* 401
* 403
* 404

Content type

application/json

`{
"tags": [
"v1.0.0",
"v2.1.3",
"latest"
]
}`

## [](#tag/repositories/operation/CreateRepositoryGroup)Assign a group (Team) to a repository for access

##### Authorizations:

*bearerAuth*

##### path Parameters

|                    |        |
| ------------------ | ------ |
| namespacerequired  | string |
| repositoryrequired | string |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                              |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| group\_idrequired  | integer \<int64>The ID of the organization group to grant access to                                                                                                                                                                          |
| permissionrequired | stringEnum: "read" "write" "admin"The permission level to grant to the group:- read: Can view and pull from the repository
- write: Can view, pull, and push to the repository
- admin: Can view, pull, push, and manage repository settings |

### Responses

Docker HUB API

https\://hub.docker.com/v2/repositories/{namespace}/{repository}/groups

### Request samples

* Payload

Content type

application/json

`{
"group_id": 12345,
"permission": "write"
}`

### Response samples

* 200
* 400
* 401
* 403
* 404

Content type

application/json

`{
"group_name": "developers",
"permission": "write",
"group_id": 12345
}`

## [](#tag/repositories/operation/listNamespaceRepositories)List repositories in a namespace

Returns a list of repositories within the specified namespace (organization or user).

Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions.

##### Authorizations:

*bearerAuth*None

##### path Parameters

|                   |        |
| ----------------- | ------ |
| namespacerequired | string |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page       | integer >= 1Default: 1Page number to get. Defaults to 1.                                                                                                                                                                                                                                                                                                                                                 |
| page\_size | integer \[ 1 .. 100 ]Default: 10Number of repositories to get per page. Defaults to 10. Max of 100.                                                                                                                                                                                                                                                                                                      |
| name       | stringFilter repositories by name (partial match).                                                                                                                                                                                                                                                                                                                                                       |
| ordering   | stringEnum: "name" "-name" "last\_updated" "-last\_updated" "pull\_count" "-pull\_count"Order repositories by the specified field. Prefix with '-' for descending order. Available options:- `name` / `-name`: Repository name (ascending/descending)
- `last_updated` / `-last_updated`: Last update time (ascending/descending)
- `pull_count` / `-pull_count`: Number of pulls (ascending/descending) |

### Responses

Docker HUB API

https\://hub.docker.com/v2/namespaces/{namespace}/repositories

### Response samples

* 200
* 400
* 401
* 403
* 404

Content type

application/json

`{
"count": 287,
"next": "https://hub.docker.com/v2/namespaces/docker/repositories?page=2&page_size=2",
"previous": null,
"results": [
{
"name": "highland_builder",
"namespace": "docker",
"repository_type": "image",
"status": 1,
"status_description": "active",
"description": "Image for performing Docker build requests",
"is_private": false,
"star_count": 7,
"pull_count": 15722123,
"last_updated": "2023-06-20T10:44:45.459826Z",
"last_modified": "2024-10-16T13:48:34.145251Z",
"date_registered": "2015-05-19T21:13:35.937763Z",
"affiliation": "",
"media_types": [
"application/octet-stream",
"application/vnd.docker.container.image.v1+json",
"application/vnd.docker.distribution.manifest.v1+prettyjws"
],
"content_types": [
"unrecognized",
"image"
],
"categories": [
{
"name": "Languages & frameworks",
"slug": "languages-and-frameworks"
},
{
"name": "Integration & delivery",
"slug": "integration-and-delivery"
},
{
"name": "Operating systems",
"slug": "operating-systems"
}
],
"storage_size": 488723114800
},
{
"name": "whalesay",
"namespace": "docker",
"repository_type": null,
"status": 1,
"status_description": "active",
"description": "An image for use in the Docker demo tutorial",
"is_private": false,
"star_count": 757,
"pull_count": 130737682,
"last_updated": "2015-06-19T19:06:27.388123Z",
"last_modified": "2024-10-16T13:48:34.145251Z",
"date_registered": "2015-06-09T18:16:36.527329Z",
"affiliation": "",
"media_types": [
"application/vnd.docker.distribution.manifest.v1+prettyjws"
],
"content_types": [
"image"
],
"categories": [
{
"name": "Languages & frameworks",
"slug": "languages-and-frameworks"
},
{
"name": "Integration & delivery",
"slug": "integration-and-delivery"
}
],
"storage_size": 103666708
}
]
}`

## [](#tag/repositories/operation/CreateRepository)Create a new repository

Creates a new repository within the specified namespace. The repository will be created with the provided metadata including name, description, and privacy settings.

##### Authorizations:

None

##### path Parameters

|                   |        |
| ----------------- | ------ |
| namespacerequired | string |

##### Request Body schema: application/jsonrequired

|                   |                                                                                                                                                                                                                                                      |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired      | string \[ 2 .. 255 ] characters ^\[a-z0-9]+(?:\[.\_-]\[a-z0-9]+)\*$The name of the repository. Must be 2-255 characters long and may only include alphanumeric characters, periods (.), underscores (\_), or hyphens (-). Letters must be lowercase. |
| namespacerequired | stringThe namespace where the repository will be created                                                                                                                                                                                             |
| description       | string <= 100 charactersShort description of the repository                                                                                                                                                                                          |
| full\_description | string <= 25000 charactersDetailed description of the repository                                                                                                                                                                                     |
| registry          | stringThe registry where the repository will be hosted                                                                                                                                                                                               |
| is\_private       | booleanDefault: falseWhether the repository should be private                                                                                                                                                                                        |

### Responses

Docker HUB API

https\://hub.docker.com/v2/namespaces/{namespace}/repositories

### Request samples

* Payload

Content type

application/json

`{
"name": "my-app",
"namespace": "myorganization",
"description": "A sample application repository",
"full_description": "This is a comprehensive description of my application repository that contains additional details about the project.",
"registry": "docker.io",
"is_private": false
}`

### Response samples

* 201
* 400
* 401
* 403
* 404
* 500

Content type

application/json

`{
"name": "my-app",
"namespace": "myorganization",
"repository_type": "image",
"status": 1,
"status_description": "Active",
"description": "A sample application repository",
"is_private": false,
"is_automated": false,
"star_count": 0,
"pull_count": 0,
"last_updated": "2025-01-20T10:30:00Z",
"date_registered": "2025-01-20T10:30:00Z",
"collaborator_count": 0,
"hub_user": "myorganization",
"has_starred": false,
"full_description": "This is a comprehensive description of my application repository that contains additional details about the project.",
"media_types": [ ],
"content_types": [ ],
"categories": [ ],
"immutable_tags_settings": {
"enabled": false,
"rules": [ ]
},
"storage_size": null,
"source": null
}`

## [](#tag/repositories/operation/GetRepository)Get repository in a namespace

Returns a repository within the specified namespace (organization or user).

Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions.

##### Authorizations:

*bearerAuth*None

##### path Parameters

|                    |        |
| ------------------ | ------ |
| namespacerequired  | string |
| repositoryrequired | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/namespaces/{namespace}/repositories/{repository}

### Response samples

* 200
* 401
* 403
* 404
* 500

Content type

application/json

`{
"name": "my-app",
"namespace": "myorganization",
"repository_type": "image",
"status": 1,
"status_description": "Active",
"description": "A sample application repository",
"is_private": false,
"is_automated": false,
"star_count": 0,
"pull_count": 0,
"last_updated": "2025-01-20T10:30:00Z",
"date_registered": "2025-01-20T10:30:00Z",
"collaborator_count": 0,
"hub_user": "myorganization",
"has_starred": false,
"full_description": "This is a comprehensive description of my application repository that contains additional details about the project.",
"media_types": [ ],
"content_types": [ ],
"categories": [ ],
"immutable_tags_settings": {
"enabled": false,
"rules": [ ]
},
"storage_size": null,
"source": null
}`

## [](#tag/repositories/operation/CheckRepository)Check repository in a namespace

Check a repository within the specified namespace (organization or user).

Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions.

##### Authorizations:

*bearerAuth*None

##### path Parameters

|                    |        |
| ------------------ | ------ |
| namespacerequired  | string |
| repositoryrequired | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/namespaces/{namespace}/repositories/{repository}

### Response samples

* 200
* 401
* 403
* 404
* 500

Content type

application/json

`{
"name": "my-app",
"namespace": "myorganization",
"repository_type": "image",
"status": 1,
"status_description": "Active",
"description": "A sample application repository",
"is_private": false,
"is_automated": false,
"star_count": 0,
"pull_count": 0,
"last_updated": "2025-01-20T10:30:00Z",
"date_registered": "2025-01-20T10:30:00Z",
"collaborator_count": 0,
"hub_user": "myorganization",
"has_starred": false,
"full_description": "This is a comprehensive description of my application repository that contains additional details about the project.",
"media_types": [ ],
"content_types": [ ],
"categories": [ ],
"immutable_tags_settings": {
"enabled": false,
"rules": [ ]
},
"storage_size": null,
"source": null
}`

## [](#tag/scim)SCIM

SCIM is a provisioning system that lets you manage users within your identity provider (IdP).

For more information, see [System for Cross-domain Identity management](https://docs.docker.com/security/for-admins/provisioning/scim/).

## [](#tag/scim/paths/~1v2~1scim~12.0~1ServiceProviderConfig/get)Get service provider config

Returns a service provider config for Docker's configuration.

##### Authorizations:

*bearerSCIMAuth*

### Responses

Docker HUB API

https\://hub.docker.com/v2/scim/2.0/ServiceProviderConfig

### Response samples

* 200
* 401
* 500

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
],
"documentationUri": "",
"patch": {
"supported": false
},
"bulk": {
"supported": false,
"maxOperations": 0,
"maxPayloadSize": 0
},
"filter": {
"supported": true,
"maxResults": 99999
},
"changePassword": {
"supported": false
},
"sort": {
"supported": true
},
"etag": {
"supported": false
},
"authenticationSchemes": {
"name": "OAuth 2.0 Bearer Token",
"description": "The OAuth 2.0 Bearer Token Authentication scheme. OAuth enables clients to access protected resources by obtaining an access token, which is defined in RFC 6750 as \"a string representing an access authorization issued to the client\", rather than using the resource owner's credentials directly.",
"specUri": "http://tools.ietf.org/html/rfc6750",
"type": "oauthbearertoken"
}
}`

## [](#tag/scim/paths/~1v2~1scim~12.0~1ResourceTypes/get)List resource types

Returns all resource types supported for the SCIM configuration.

##### Authorizations:

*bearerSCIMAuth*

### Responses

Docker HUB API

https\://hub.docker.com/v2/scim/2.0/ResourceTypes

### Response samples

* 200
* 401
* 500

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:ResourceType"
],
"id": "User",
"name": "User",
"description": "User",
"endpoint": "/Users",
"schema": "urn:ietf:params:scim:schemas:core:2.0:User"
}
]
}`

## [](#tag/scim/paths/~1v2~1scim~12.0~1ResourceTypes~1{name}/get)Get a resource type

Returns a resource type by name.

##### Authorizations:

*bearerSCIMAuth*

##### path Parameters

|              |                     |
| ------------ | ------------------- |
| namerequired | stringExample: User |

### Responses

Docker HUB API

https\://hub.docker.com/v2/scim/2.0/ResourceTypes/{name}

### Response samples

* 200
* 401
* 404
* 500

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:ResourceType"
],
"id": "User",
"name": "User",
"description": "User",
"endpoint": "/Users",
"schema": "urn:ietf:params:scim:schemas:core:2.0:User"
}`

## [](#tag/scim/paths/~1v2~1scim~12.0~1Schemas/get)List schemas

Returns all schemas supported for the SCIM configuration.

##### Authorizations:

*bearerSCIMAuth*

### Responses

Docker HUB API

https\://hub.docker.com/v2/scim/2.0/Schemas

### Response samples

* 200
* 401
* 500

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Schema"
],
"id": "urn:ietf:params:scim:schemas:core:2.0:User",
"name": "User",
"description": "User Account",
"attributes": [ ]
}
]
}`

## [](#tag/scim/paths/~1v2~1scim~12.0~1Schemas~1{id}/get)Get a schema

Returns a schema by ID.

##### Authorizations:

*bearerSCIMAuth*

##### path Parameters

|            |                                                           |
| ---------- | --------------------------------------------------------- |
| idrequired | stringExample: urn:ietf:params:scim:schemas:core:2.0:User |

### Responses

Docker HUB API

https\://hub.docker.com/v2/scim/2.0/Schemas/{id}

### Response samples

* 200
* 401
* 404
* 500

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Schema"
],
"id": "urn:ietf:params:scim:schemas:core:2.0:User",
"name": "User",
"description": "User Account",
"attributes": [ ]
}`

## [](#tag/scim/paths/~1v2~1scim~12.0~1Users/get)List users

Returns paginated users for an organization. Use `startIndex` and `count` query parameters to receive paginated results.

**Sorting:**

Sorting allows you to specify the order in which resources are returned by specifying a combination of `sortBy` and `sortOrder` query parameters.

The `sortBy` parameter specifies the attribute whose value will be used to order the returned responses. The `sortOrder` parameter defines the order in which the `sortBy` parameter is applied. Allowed values are "ascending" and "descending".

**Filtering:**

You can request a subset of resources by specifying the `filter` query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value.

Supported operators are listed below.

* `eq` equal
* `ne` not equal
* `co` contains
* `sw` starts with
* `and` Logical "and"
* `or` Logical "or"
* `not` "Not" function
* `()` Precedence grouping

##### Authorizations:

*bearerSCIMAuth*

##### query Parameters

|            |                                                                                                               |
| ---------- | ------------------------------------------------------------------------------------------------------------- |
| startIndex | integer >= 1Example: startIndex=1                                                                             |
| count      | integer \[ 1 .. 200 ]Example: count=10                                                                        |
| filter     | stringExample: filter=userName eq "jon.snow\@docker.com"                                                      |
| attributes | stringExample: attributes=userName,displayNameComma delimited list of attributes to limit to in the response. |
| sortOrder  | stringEnum: "ascending" "descending"                                                                          |
| sortBy     | stringExample: sortBy=userNameUser attribute to sort by.                                                      |

### Responses

Docker HUB API

https\://hub.docker.com/v2/scim/2.0/Users

### Response samples

* 200
* 400
* 401
* 403
* 404
* 500

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 10,
"resources": [
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c",
"userName": "jon.snow@docker.com",
"name": {
"givenName": "Jon",
"familyName": "Snow"
},
"displayName": "jonsnow",
"active": true,
"emails": [
{
"value": "jon.snow@docker.com",
"display": "jon.snow@docker.com",
"primary": true
}
],
"groups": [
{
"value": "nightswatch",
"display": "nightswatch"
}
],
"meta": {
"resourceType": "User",
"location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c",
"created": "2022-05-20T00:54:18Z",
"lastModified": "2022-05-20T00:54:18Z"
}
}
]
}`

## [](#tag/scim/paths/~1v2~1scim~12.0~1Users/post)Create user

Creates a user. If the user already exists by email, they are assigned to the organization on the "company" team.

##### Authorizations:

*bearerSCIMAuth*

##### Request Body schema: application/scim+jsonrequired

|                  |                                                                                          |
| ---------------- | ---------------------------------------------------------------------------------------- |
| schemasrequired  | Array of strings (scim\_user\_schemas) \[ items non-empty ]                              |
| userNamerequired | string (scim\_user\_username)The user's email address. This must be reachable via email. |
|                  | object (scim\_user\_name)                                                                |

### Responses

Docker HUB API

https\://hub.docker.com/v2/scim/2.0/Users

### Request samples

* Payload

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "jon.snow@docker.com",
"name": {
"givenName": "Jon",
"familyName": "Snow"
}
}`

### Response samples

* 201
* 400
* 401
* 403
* 404
* 409
* 500

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c",
"userName": "jon.snow@docker.com",
"name": {
"givenName": "Jon",
"familyName": "Snow"
},
"displayName": "jonsnow",
"active": true,
"emails": [
{
"value": "jon.snow@docker.com",
"display": "jon.snow@docker.com",
"primary": true
}
],
"groups": [
{
"value": "nightswatch",
"display": "nightswatch"
}
],
"meta": {
"resourceType": "User",
"location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c",
"created": "2022-05-20T00:54:18Z",
"lastModified": "2022-05-20T00:54:18Z"
}
}`

## [](#tag/scim/paths/~1v2~1scim~12.0~1Users~1{id}/get)Get a user

Returns a user by ID.

##### Authorizations:

*bearerSCIMAuth*

##### path Parameters

|            |                                                                 |
| ---------- | --------------------------------------------------------------- |
| idrequired | stringExample: d80f7c79-7730-49d8-9a41-7c42fb622d9cThe user ID. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/scim/2.0/Users/{id}

### Response samples

* 200
* 400
* 401
* 403
* 404
* 500

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c",
"userName": "jon.snow@docker.com",
"name": {
"givenName": "Jon",
"familyName": "Snow"
},
"displayName": "jonsnow",
"active": true,
"emails": [
{
"value": "jon.snow@docker.com",
"display": "jon.snow@docker.com",
"primary": true
}
],
"groups": [
{
"value": "nightswatch",
"display": "nightswatch"
}
],
"meta": {
"resourceType": "User",
"location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c",
"created": "2022-05-20T00:54:18Z",
"lastModified": "2022-05-20T00:54:18Z"
}
}`

## [](#tag/scim/paths/~1v2~1scim~12.0~1Users~1{id}/put)Update a user

Updates a user. This route is used to change the user's name, activate, and deactivate the user.

##### Authorizations:

*bearerSCIMAuth*

##### path Parameters

|            |                                                                 |
| ---------- | --------------------------------------------------------------- |
| idrequired | stringExample: d80f7c79-7730-49d8-9a41-7c42fb622d9cThe user ID. |

##### Request Body schema: application/scim+jsonrequired

|                 |                                                                                                                                        |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| schemasrequired | Array of strings (scim\_user\_schemas) \[ items non-empty ]                                                                            |
|                 | objectIf this is omitted from the request, the update will skip the update on it. We will only ever change the name, but not clear it. |
| enabled         | booleanDefault: falseIf this is omitted from the request, it will default to false resulting in a deactivated user.                    |

### Responses

Docker HUB API

https\://hub.docker.com/v2/scim/2.0/Users/{id}

### Request samples

* Payload

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"name": {
"givenName": "Jon",
"familyName": "Snow"
},
"enabled": false
}`

### Response samples

* 200
* 400
* 401
* 403
* 404
* 409
* 500

Content type

application/scim+json

`{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "d80f7c79-7730-49d8-9a41-7c42fb622d9c",
"userName": "jon.snow@docker.com",
"name": {
"givenName": "Jon",
"familyName": "Snow"
},
"displayName": "jonsnow",
"active": true,
"emails": [
{
"value": "jon.snow@docker.com",
"display": "jon.snow@docker.com",
"primary": true
}
],
"groups": [
{
"value": "nightswatch",
"display": "nightswatch"
}
],
"meta": {
"resourceType": "User",
"location": "https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c",
"created": "2022-05-20T00:54:18Z",
"lastModified": "2022-05-20T00:54:18Z"
}
}`

## [](#tag/orgs)Organizations

The organization endpoints allow you to interact with and manage your organizations.

For more information, see [Organization administration overview](https://docs.docker.com/admin/organization/).

## [](#tag/orgs/paths/~1v2~1orgs~1{org_name}~1members/get)List org members

Returns a list of members for an organization.

*The following fields are only visible to orgs with insights enabled.*

* `last_logged_in_at`
* `last_seen_at`
* `last_desktop_version`

To make visible, please see [View Insights for organization users](https://docs.docker.com/admin/insights/#view-insights-for-organization-users).

##### Authorizations:

*bearerAuth*

##### path Parameters

|                   |                                                                    |
| ----------------- | ------------------------------------------------------------------ |
| org\_namerequired | stringExample: myorganizationName of the organization (namespace). |

##### query Parameters

|            |                                                          |
| ---------- | -------------------------------------------------------- |
| search     | integerSearch term.                                      |
| page       | integerPage number (starts on 1).                        |
| page\_size | integerNumber of items (rows) per page.                  |
| invites    | booleanInclude invites in the response.                  |
| type       | stringEnum: "all" "invitee" "member"Example: type=all    |
| role       | stringEnum: "owner" "editor" "member"Example: role=owner |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/members

### Response samples

* 200
* 400
* 401
* 403
* 404

Content type

application/json

`[
{
"count": 120,
"previous": "https://hub.docker.com/v2/some/resources/items?page=1&page_size=20",
"next": "https://hub.docker.com/v2/some/resources/items?page=3&page_size=20",
"results": [
{
"email": "example@docker.com",
"role": "Owner",
"groups": [
"developers",
"owners"
],
"is_guest": false,
"primary_email": "example@docker.com",
"last_logged_in_at": "2021-01-05T21:06:53.506400Z",
"last_seen_at": "2021-01-05T21:06:53.506400Z",
"last_desktop_version": "4.29.0",
"id": "0ab70deb065a43fcacd55d48caa945d8",
"company": "Docker Inc",
"date_joined": "2021-01-05T21:06:53.506400Z",
"full_name": "Jon Snow",
"gravatar_email": "string",
"gravatar_url": "string",
"location": "string",
"profile_url": "string",
"type": "User",
"username": "dockeruser"
}
]
}
]`

## [](#tag/orgs/paths/~1v2~1orgs~1{org_name}~1members~1export/get)Export org members CSV

Export members of an organization as a CSV

##### Authorizations:

*bearerAuth*

##### path Parameters

|                   |                                                                    |
| ----------------- | ------------------------------------------------------------------ |
| org\_namerequired | stringExample: myorganizationName of the organization (namespace). |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/members/export

### Response samples

* 400
* 401
* 403
* 404

Content type

application/json

`{
"errinfo": { },
"detail": "string",
"message": "string"
}`

## [](#tag/orgs/paths/~1v2~1orgs~1{org_name}~1members~1{username}/put)Update org member (role)

Updates the role of a member in the organization. ***Only users in the "owners" group of the organization can use this endpoint.***

##### Authorizations:

*bearerAuth*

##### path Parameters

|                   |                                                                                |
| ----------------- | ------------------------------------------------------------------------------ |
| org\_namerequired | stringExample: myorganizationName of the organization (namespace).             |
| usernamerequired  | stringExample: jonsnowUsername, identifier for the user (namespace, DockerID). |

##### Request Body schema: application/jsonrequired

|              |                                                         |
| ------------ | ------------------------------------------------------- |
| rolerequired | stringEnum: "owner" "editor" "member"Role of the member |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/members/{username}

### Request samples

* Payload

Content type

application/json

`{
"role": "owner"
}`

### Response samples

* 200
* 400
* 401
* 403
* 404

Content type

application/json

`{
"email": "example@docker.com",
"role": "Owner",
"groups": [
"developers",
"owners"
],
"is_guest": false,
"primary_email": "example@docker.com",
"last_logged_in_at": "2021-01-05T21:06:53.506400Z",
"last_seen_at": "2021-01-05T21:06:53.506400Z",
"last_desktop_version": "4.29.0",
"id": "0ab70deb065a43fcacd55d48caa945d8",
"company": "Docker Inc",
"date_joined": "2021-01-05T21:06:53.506400Z",
"full_name": "Jon Snow",
"gravatar_email": "string",
"gravatar_url": "string",
"location": "string",
"profile_url": "string",
"type": "User",
"username": "dockeruser"
}`

## [](#tag/orgs/paths/~1v2~1orgs~1{org_name}~1members~1{username}/delete)Remove member from org

Removes the member from the org, ie. all groups in the org, unless they're the last owner

##### Authorizations:

*bearerAuth*

##### path Parameters

|                   |                                                                                |
| ----------------- | ------------------------------------------------------------------------------ |
| org\_namerequired | stringExample: myorganizationName of the organization (namespace).             |
| usernamerequired  | stringExample: jonsnowUsername, identifier for the user (namespace, DockerID). |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/members/{username}

### Response samples

* 400
* 401
* 403
* 404

Content type

application/json

`{
"errinfo": { },
"detail": "string",
"message": "string"
}`

## [](#tag/org-access-tokens)Organization Access Tokens

The organization access token endpoints allow you to manage organization access tokens (OATs). See [Organization access tokens](https://docs.docker.com/security/for-admins/access-tokens/) for more information.

## [](#tag/org-access-tokens/paths/~1v2~1orgs~1{name}~1access-tokens/post)Create access token

Create an access token for an organization.

##### Authorizations:

*bearerAuth*

##### Request Body schema: application/jsonrequired

|             |                                                                             |
| ----------- | --------------------------------------------------------------------------- |
| label       | stringLabel for the access token                                            |
| description | stringDescription of the access token                                       |
|             | Array of objects (orgAccessTokenResource)Resources this token has access to |
| expires\_at | string or null \<date-time>Expiration date for the token                    |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{name}/access-tokens

### Request samples

* Payload

Content type

application/json

`{
"label": "My organization token",
"description": "Token for CI/CD pipeline",
"resources": [
{
"type": "TYPE_REPO",
"path": "myorg/myrepo",
"scopes": [
"scope-image-pull"
]
}
],
"expires_at": "2023-05-20T00:54:18Z"
}`

### Response samples

* 201
* 400
* 401
* 403
* 404

Content type

application/json

`{
"id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861",
"label": "My organization token",
"is_active": true,
"created_at": "2022-05-20T00:54:18Z",
"expires_at": "2023-05-20T00:54:18Z",
"last_used_at": "2022-06-15T12:30:45Z",
"token": "dckr_oat_7awgM4jG5SQvxcvmNzhKj8PQjxo",
"resources": [
{
"type": "TYPE_REPO",
"path": "myorg/myrepo",
"scopes": [
"scope-image-pull"
]
}
]
}`

## [](#tag/org-access-tokens/paths/~1v2~1orgs~1{name}~1access-tokens/get)List access tokens

List access tokens for an organization.

##### Authorizations:

*bearerAuth*

##### query Parameters

|            |                   |
| ---------- | ----------------- |
| page       | numberDefault: 1  |
| page\_size | numberDefault: 10 |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{name}/access-tokens

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"total": 10,
"next": "https://hub.docker.com/v2/orgs/docker/access-tokens?page=2&page_size=10",
"previous": "https://hub.docker.com/v2/orgs/docker/access-tokens?page=1&page_size=10",
"results": [
{
"id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861",
"label": "My organization token",
"created_by": "johndoe",
"is_active": true,
"created_at": "2022-05-20T00:54:18Z",
"expires_at": "2023-05-20T00:54:18Z",
"last_used_at": "2022-06-15T12:30:45Z"
}
]
}`

## [](#tag/org-access-tokens/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/get)Get access token

Get details of a specific access token for an organization.

##### Authorizations:

*bearerAuth*

##### path Parameters

|                           |                                                                                           |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| org\_namerequired         | stringExample: myorganizationName of the organization (namespace).                        |
| access\_token\_idrequired | stringExample: a7a5ef25-8889-43a0-8cc7-f2a94268e861The ID of the access token to retrieve |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/access-tokens/{access\_token\_id}

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861",
"label": "My organization token",
"created_by": "johndoe",
"is_active": true,
"created_at": "2022-05-20T00:54:18Z",
"expires_at": "2023-05-20T00:54:18Z",
"last_used_at": "2022-06-15T12:30:45Z",
"resources": [
{
"type": "TYPE_REPO",
"path": "myorg/myrepo",
"scopes": [
"scope-image-pull"
]
}
]
}`

## [](#tag/org-access-tokens/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/patch)Update access token

Update a specific access token for an organization.

##### Authorizations:

*bearerAuth*

##### path Parameters

|                           |                                                                                           |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| org\_namerequired         | stringExample: myorganizationName of the organization (namespace).                        |
| access\_token\_idrequired | stringExample: a7a5ef25-8889-43a0-8cc7-f2a94268e861The ID of the access token to retrieve |

##### Request Body schema: application/jsonrequired

|             |                                                                             |
| ----------- | --------------------------------------------------------------------------- |
| label       | stringLabel for the access token                                            |
| description | stringDescription of the access token                                       |
|             | Array of objects (orgAccessTokenResource)Resources this token has access to |
| is\_active  | booleanWhether the token is active                                          |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/access-tokens/{access\_token\_id}

### Request samples

* Payload

Content type

application/json

`{
"label": "My organization token",
"description": "Token for CI/CD pipeline",
"resources": [
{
"type": "TYPE_REPO",
"path": "myorg/myrepo",
"scopes": [
"scope-image-pull"
]
}
],
"is_active": true
}`

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"id": "a7a5ef25-8889-43a0-8cc7-f2a94268e861",
"label": "My organization token",
"created_by": "johndoe",
"is_active": true,
"created_at": "2022-05-20T00:54:18Z",
"expires_at": "2023-05-20T00:54:18Z",
"last_used_at": "2022-06-15T12:30:45Z",
"resources": [
{
"type": "TYPE_REPO",
"path": "myorg/myrepo",
"scopes": [
"scope-image-pull"
]
}
]
}`

## [](#tag/org-access-tokens/paths/~1v2~1orgs~1{org_name}~1access-tokens~1{access_token_id}/delete)Delete access token

Delete a specific access token for an organization. This action cannot be undone.

##### Authorizations:

*bearerAuth*

##### path Parameters

|                           |                                                                                           |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| org\_namerequired         | stringExample: myorganizationName of the organization (namespace).                        |
| access\_token\_idrequired | stringExample: a7a5ef25-8889-43a0-8cc7-f2a94268e861The ID of the access token to retrieve |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/access-tokens/{access\_token\_id}

### Response samples

* 401
* 403
* 404

Content type

application/json

`{
"detail": "string",
"message": "string"
}`

## [](#tag/groups)Groups (Teams)

The groups endpoints allow you to manage your organization's teams and their members.

For more information, see [Create and manage a team](https://docs.docker.com/admin/organization/manage/manage-a-team/).

## [](#tag/groups/paths/~1v2~1orgs~1{org_name}~1groups/get)Get groups of an organization

##### Authorizations:

*bearerAuth*

##### path Parameters

|                   |                                                                    |
| ----------------- | ------------------------------------------------------------------ |
| org\_namerequired | stringExample: myorganizationName of the organization (namespace). |

##### query Parameters

|            |                                                                  |
| ---------- | ---------------------------------------------------------------- |
| page       | integerPage number (starts on 1).                                |
| page\_size | integerNumber of items (rows) per page.                          |
| username   | stringGet groups for the specified username in the organization. |
| search     | stringGet groups for the specified group in the organization.    |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/groups

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 10,
"uuid": "string",
"name": "mygroup",
"description": "Groups description",
"member_count": 10
}
]
}`

## [](#tag/groups/paths/~1v2~1orgs~1{org_name}~1groups/post)Create a new group

Create a new group within an organization.

##### Authorizations:

*bearerAuth*

##### path Parameters

|                   |                                                                    |
| ----------------- | ------------------------------------------------------------------ |
| org\_namerequired | stringExample: myorganizationName of the organization (namespace). |

##### Request Body schema: application/json

|              |        |
| ------------ | ------ |
| namerequired | string |
| description  | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/groups

### Request samples

* Payload

Content type

application/json

`{
"name": "string",
"description": "string"
}`

### Response samples

* 201
* 400
* 401
* 403

Content type

application/json

`{
"id": 10,
"uuid": "string",
"name": "mygroup",
"description": "Groups description",
"member_count": 10
}`

## [](#tag/groups/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/get)Get a group of an organization

##### Authorizations:

*bearerAuth*

##### path Parameters

|                     |                                                                        |
| ------------------- | ---------------------------------------------------------------------- |
| org\_namerequired   | stringExample: myorganizationName of the organization (namespace).     |
| group\_namerequired | stringExample: developersName of the group (team) in the organization. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/groups/{group\_name}

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"id": 10,
"uuid": "string",
"name": "mygroup",
"description": "Groups description",
"member_count": 10
}`

## [](#tag/groups/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/put)Update the details for an organization group

##### Authorizations:

*bearerAuth*

##### path Parameters

|                     |                                                                        |
| ------------------- | ---------------------------------------------------------------------- |
| org\_namerequired   | stringExample: myorganizationName of the organization (namespace).     |
| group\_namerequired | stringExample: developersName of the group (team) in the organization. |

##### Request Body schema: application/json

|              |        |
| ------------ | ------ |
| namerequired | string |
| description  | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/groups/{group\_name}

### Request samples

* Payload

Content type

application/json

`{
"name": "string",
"description": "string"
}`

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"id": 10,
"uuid": "string",
"name": "mygroup",
"description": "Groups description",
"member_count": 10
}`

## [](#tag/groups/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/patch)Update some details for an organization group

##### Authorizations:

*bearerAuth*

##### path Parameters

|                     |                                                                        |
| ------------------- | ---------------------------------------------------------------------- |
| org\_namerequired   | stringExample: myorganizationName of the organization (namespace).     |
| group\_namerequired | stringExample: developersName of the group (team) in the organization. |

##### Request Body schema: application/json

|             |        |
| ----------- | ------ |
| name        | string |
| description | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/groups/{group\_name}

### Request samples

* Payload

Content type

application/json

`{
"name": "string",
"description": "string"
}`

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"id": 10,
"uuid": "string",
"name": "mygroup",
"description": "Groups description",
"member_count": 10
}`

## [](#tag/groups/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}/delete)Delete an organization group

##### Authorizations:

*bearerAuth*

##### path Parameters

|                     |                                                                        |
| ------------------- | ---------------------------------------------------------------------- |
| org\_namerequired   | stringExample: myorganizationName of the organization (namespace).     |
| group\_namerequired | stringExample: developersName of the group (team) in the organization. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/groups/{group\_name}

### Response samples

* 401
* 403
* 404

Content type

application/json

`{
"errinfo": { },
"detail": "string",
"message": "string"
}`

## [](#tag/groups/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/get)List members of a group

List the members (users) that are in a group. If user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails.

##### Authorizations:

*bearerAuth*

##### path Parameters

|                     |                                                                        |
| ------------------- | ---------------------------------------------------------------------- |
| org\_namerequired   | stringExample: myorganizationName of the organization (namespace).     |
| group\_namerequired | stringExample: developersName of the group (team) in the organization. |

##### query Parameters

|            |                                                        |
| ---------- | ------------------------------------------------------ |
| page       | integerPage number (starts on 1).                      |
| page\_size | integerNumber of items (rows) per page.                |
| search     | stringSearch members by username, full\_name or email. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/groups/{group\_name}/members

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "0ab70deb065a43fcacd55d48caa945d8",
"company": "Docker Inc",
"date_joined": "2021-01-05T21:06:53.506400Z",
"full_name": "John Snow",
"gravatar_email": "string",
"gravatar_url": "string",
"location": "string",
"profile_url": "string",
"type": "User",
"username": "dockeruser",
"email": "dockeruser@docker.com"
}
]
}`

## [](#tag/groups/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members/post)Add a member to a group

##### Authorizations:

*bearerAuth*

##### path Parameters

|                     |                                                                        |
| ------------------- | ---------------------------------------------------------------------- |
| org\_namerequired   | stringExample: myorganizationName of the organization (namespace).     |
| group\_namerequired | stringExample: developersName of the group (team) in the organization. |

##### Request Body schema: application/jsonrequired

|                |        |
| -------------- | ------ |
| memberrequired | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/groups/{group\_name}/members

### Request samples

* Payload

Content type

application/json

`{
"member": "jonsnow"
}`

### Response samples

* 401
* 403
* 404
* 500

Content type

application/json

`{
"errinfo": { },
"detail": "string",
"message": "string"
}`

## [](#tag/groups/paths/~1v2~1orgs~1{org_name}~1groups~1{group_name}~1members~1{username}/delete)Remove a user from a group

##### Authorizations:

*bearerAuth*

##### path Parameters

|                     |                                                                                |
| ------------------- | ------------------------------------------------------------------------------ |
| org\_namerequired   | stringExample: myorganizationName of the organization (namespace).             |
| group\_namerequired | stringExample: developersName of the group (team) in the organization.         |
| usernamerequired    | stringExample: jonsnowUsername, identifier for the user (namespace, DockerID). |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/groups/{group\_name}/members/{username}

### Response samples

* 401
* 403
* 404

Content type

application/json

`{
"errinfo": { },
"detail": "string",
"message": "string"
}`

## [](#tag/invites)Invites

The invites endpoints allow you to manage invites for users to join your Docker organization.

For more information, see [Invite members](https://docs.docker.com/admin/organization/manage/members/#invite-members).

## [](#tag/invites/paths/~1v2~1orgs~1{org_name}~1invites/get)List org invites

Return all pending invites for a given org, only team owners can call this endpoint

##### Authorizations:

*bearerAuth*

##### path Parameters

|                   |                                                                    |
| ----------------- | ------------------------------------------------------------------ |
| org\_namerequired | stringExample: myorganizationName of the organization (namespace). |

### Responses

Docker HUB API

https\://hub.docker.com/v2/orgs/{org\_name}/invites

### Response samples

* 200
* 401
* 403
* 404

Content type

application/json

`{
"data": [
{
"id": "e36eca69-4cc8-4f17-9845-ae8c2b832691",
"inviter_username": "moby",
"invitee": "invitee@docker.com",
"org": "docker",
"team": "owners",
"created_at": "2021-10-28T18:30:19.520861Z"
}
]
}`

## [](#tag/invites/paths/~1v2~1invites~1{id}/delete)Cancel an invite

Mark the invite as cancelled so it doesn't show up on the list of pending invites

##### Authorizations:

*bearerAuth*

##### path Parameters

|            |        |
| ---------- | ------ |
| idrequired | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/invites/{id}

### Response samples

* 401
* 403
* 404

Content type

application/json

`{
"errinfo": { },
"detail": "string",
"message": "string"
}`

## [](#tag/invites/paths/~1v2~1invites~1{id}~1resend/patch)Resend an invite

Resend a pending invite to the user, any org owner can resend an invite

##### Authorizations:

*bearerAuth*

##### path Parameters

|            |        |
| ---------- | ------ |
| idrequired | string |

### Responses

Docker HUB API

https\://hub.docker.com/v2/invites/{id}/resend

### Response samples

* 401
* 403
* 404

Content type

application/json

`{
"errinfo": { },
"detail": "string",
"message": "string"
}`

## [](#tag/invites/paths/~1v2~1invites~1bulk/post)Bulk create invites

Create multiple invites by emails or DockerIDs. Only a team owner can create invites.

##### Authorizations:

*bearerAuth*

##### header Parameters

|                            |                                                                                                      |
| -------------------------- | ---------------------------------------------------------------------------------------------------- |
| X-Analytics-Client-Feature | stringOptional string that indicates the feature used to submit the bulk invites (e.g.'file', 'web') |

##### Request Body schema: application/jsonrequired

|                  |                                                                         |
| ---------------- | ----------------------------------------------------------------------- |
| orgrequired      | stringorganization name                                                 |
| team             | stringteam name                                                         |
| role             | stringrole for invitees                                                 |
| inviteesrequired | Array of stringslist of invitees emails or Docker Ids                   |
| dry\_run         | booleanOptional, run through validation but don't actually change data. |

### Responses

Docker HUB API

https\://hub.docker.com/v2/invites/bulk

### Request samples

* Payload

Content type

application/json

`{
"org": "docker",
"team": "owners",
"role": "member",
"invitees": [
"invitee1DockerId",
"invitee2@docker.com",
"invitee3@docker.com"
],
"dry_run": true
}`

### Response samples

* 202
* 400
* 409

Content type

application/json

`{
"invitees": {
"invitees": [
{
"invitee": "invitee@docker.com",
"status": "invited",
"invite": {
"id": "e36eca69-4cc8-4f17-9845-ae8c2b832691",
"inviter_username": "moby",
"invitee": "invitee@docker.com",
"org": "docker",
"team": "owners",
"created_at": "2021-10-28T18:30:19.520861Z"
}
},
{
"invitee": "invitee2@docker.com",
"status": "existing_org_member"
},
{
"invitee": "invitee3@docker.com",
"status": "invalid_email_or_docker_id"
}
]
}
}`

----
url: https://docs.docker.com/guides/genai-pdf-bot/develop/
----

# Use containers for generative AI development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a generative AI application](https://docs.docker.com/guides/genai-pdf-bot/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment to access all the services that your generative AI (GenAI) application needs. This includes:

* Adding a local database
* Adding a local or remote LLM service

> Note
>
> You can see more samples of containerized GenAI applications in the [GenAI Stack](https://github.com/docker/genai-stack) demo applications.

## [Add a local database](#add-a-local-database)

You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service. In addition, you'll specify an environment variables file to load the database connection information rather than manually entering the information every time.

To run the database service:

1. In the cloned repository's directory, rename `env.example` file to `.env`. This file contains the environment variables that the containers will use.

2. In the cloned repository's directory, open the `compose.yaml` file in an IDE or text editor.

3. In the `compose.yaml` file, add the following:

   * Add instructions to run a Neo4j database
   * Specify the environment file under the server service in order to pass in the environment variables for the connection

   The following is the updated `compose.yaml` file. All comments have been removed.

   ```yaml
   services:
     server:
       build:
         context: .
       ports:
         - 8000:8000
       env_file:
         - .env
       depends_on:
         database:
           condition: service_healthy
     database:
       image: neo4j:5.11
       ports:
         - "7474:7474"
         - "7687:7687"
       environment:
         - NEO4J_AUTH=${NEO4J_USERNAME}/${NEO4J_PASSWORD}
       healthcheck:
         test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider localhost:7474 || exit 1"]
         interval: 5s
         timeout: 3s
         retries: 5
   ```

   > Note
   >
   > To learn more about Neo4j, see the [Neo4j Official Docker Image](https://hub.docker.com/_/neo4j).

4. Run the application. Inside the `docker-genai-sample` directory, run the following command in a terminal.

   ```console
   $ docker compose up --build
   ```

5. Access the application. Open a browser and view the application at <http://localhost:8000>. You should see a simple Streamlit application. Note that asking questions to a PDF will cause the application to fail because the LLM service specified in the `.env` file isn't running yet.

6. Stop the application. In the terminal, press `ctrl`+`c` to stop the application.

## [Add a local or remote LLM service](#add-a-local-or-remote-llm-service)

The sample application supports both [Ollama](https://ollama.ai/) and [OpenAI](https://openai.com/). This guide provides instructions for the following scenarios:

* Run Ollama in a container
* Run Ollama outside of a container
* Use OpenAI

While all platforms can use any of the previous scenarios, the performance and GPU support may vary. You can use the following guidelines to help you choose the appropriate option:

* Run Ollama in a container if you're on Linux, and using a native installation of the Docker Engine, or Windows 10/11, and using Docker Desktop, you have a CUDA-supported GPU, and your system has at least 8 GB of RAM.
* Run Ollama outside of a container if you're on an Apple silicon Mac.
* Use OpenAI if the previous two scenarios don't apply to you.

Choose one of the following options for your LLM service.

When running Ollama in a container, you should have a CUDA-supported GPU. While you can run Ollama in a container without a supported GPU, the performance may not be acceptable. Only Linux and Windows 11 support GPU access to containers.

To run Ollama in a container and provide GPU access:

1. Install the prerequisites.

   * For Docker Engine on Linux, install the [NVIDIA Container Toolkit](https://github.com/NVIDIA/nvidia-container-toolkit).
   * For Docker Desktop on Windows 10/11, install the latest [NVIDIA driver](https://www.nvidia.com/Download/index.aspx) and make sure you are using the [WSL2 backend](https://docs.docker.com/desktop/features/wsl/#turn-on-docker-desktop-wsl-2)

2. Add the Ollama service and a volume in your `compose.yaml`. The following is the updated `compose.yaml`:

   ```yaml
   services:
     server:
       build:
         context: .
       ports:
         - 8000:8000
       env_file:
         - .env
       depends_on:
         database:
           condition: service_healthy
     database:
       image: neo4j:5.11
       ports:
         - "7474:7474"
         - "7687:7687"
       environment:
         - NEO4J_AUTH=${NEO4J_USERNAME}/${NEO4J_PASSWORD}
       healthcheck:
         test:
           [
             "CMD-SHELL",
             "wget --no-verbose --tries=1 --spider localhost:7474 || exit 1",
           ]
         interval: 5s
         timeout: 3s
         retries: 5
     ollama:
       image: ollama/ollama:latest
       ports:
         - "11434:11434"
       volumes:
         - ollama_volume:/root/.ollama
       deploy:
         resources:
           reservations:
             devices:
               - driver: nvidia
                 count: all
                 capabilities: [gpu]
   volumes:
     ollama_volume:
   ```

   > Note
   >
   > For more details about the Compose instructions, see [Turn on GPU access with Docker Compose](https://docs.docker.com/compose/how-tos/gpu-support/).

3. Add the ollama-pull service to your `compose.yaml` file. This service uses the `docker/genai:ollama-pull` image, based on the GenAI Stack's [pull\_model.Dockerfile](https://github.com/docker/genai-stack/blob/main/pull_model.Dockerfile). The service will automatically pull the model for your Ollama container. The following is the updated section of the `compose.yaml` file:

   ```yaml
   services:
     server:
       build:
         context: .
       ports:
         - 8000:8000
       env_file:
         - .env
       depends_on:
         database:
           condition: service_healthy
         ollama-pull:
           condition: service_completed_successfully
     ollama-pull:
       image: docker/genai:ollama-pull
       env_file:
         - .env
     # ...
   ```

To run Ollama outside of a container:

1. [Install](https://github.com/jmorganca/ollama) and run Ollama on your host machine.
2. Update the `OLLAMA_BASE_URL` value in your `.env` file to `http://host.docker.internal:11434`.
3. Pull the model to Ollama using the following command.
   ```console
   $ ollama pull llama2
   ```

> Important
>
> Using OpenAI requires an [OpenAI account](https://platform.openai.com/login). OpenAI is a third-party hosted service and charges may apply.

1. Update the `LLM` value in your `.env` file to `gpt-3.5`.
2. Uncomment and update the `OPENAI_API_KEY` value in your `.env` file to your [OpenAI API key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-api-key).

## [Run your GenAI application](#run-your-genai-application)

At this point, you have the following services in your Compose file:

* Server service for your main GenAI application
* Database service to store vectors in a Neo4j database
* (optional) Ollama service to run the LLM
* (optional) Ollama-pull service to automatically pull the model for the Ollama service

To run all the services, run the following command in your `docker-genai-sample` directory:

```console
$ docker compose up --build
```

If your Compose file has the ollama-pull service, it may take several minutes for the ollama-pull service to pull the model. The ollama-pull service will continuously update the console with its status. After pulling the model, the ollama-pull service container will stop and you can access the application.

Once the application is running, open a browser and access the application at <http://localhost:8000>.

Upload a PDF file, for example the [Docker CLI Cheat Sheet](https://docs.docker.com/get-started/docker_cheatsheet.pdf), and ask a question about the PDF.

Depending on your system and the LLM service that you chose, it may take several minutes to answer. If you are using Ollama and the performance isn't acceptable, try using OpenAI.

## [Summary](#summary)

In this section, you learned how to set up a development environment to provide access all the services that your GenAI application needs.

Related information:

* [Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
* [Compose file reference](https://docs.docker.com/reference/compose-file/)
* [Ollama Docker image](https://hub.docker.com/r/ollama/ollama)
* [Neo4j Official Docker Image](https://hub.docker.com/_/neo4j)
* [GenAI Stack demo applications](https://github.com/docker/genai-stack)

## [Next steps](#next-steps)

See samples of more GenAI applications in the [GenAI Stack demo applications](https://github.com/docker/genai-stack).

----
url: https://docs.docker.com/guides/go-prometheus-monitoring/containerize/
----

# Containerize a Golang application

***

Table of contents

***

Containerization helps you bundle the application and its dependencies into a single package called a container. This package can run on any platform without worrying about the environment. In this section, you will learn how to containerize a Golang application using Docker.

To containerize a Golang application, you first need to create a Dockerfile. The Dockerfile contains instructions to build and run the application in a container. Also, when creating a Dockerfile, you can follow different sets of best practices to optimize the image size and make it more secure.

## [Creating a Dockerfile](#creating-a-dockerfile)

Create a new file named `Dockerfile` in the root directory of your Golang application. The Dockerfile contains instructions to build and run the application in a container.

The following is a Dockerfile for a Golang application. You will also find this file in the `go-prometheus-monitoring` directory.

```dockerfile
# Use the official Golang image as the base
FROM golang:1.24-alpine AS builder

# Set environment variables
ENV CGO_ENABLED=0 \
    GOOS=linux \
    GOARCH=amd64

# Set working directory inside the container
WORKDIR /build

# Copy go.mod and go.sum files for dependency installation
COPY go.mod go.sum ./

# Download dependencies
RUN go mod download

# Copy the entire application source
COPY . .

# Build the Go binary
RUN go build -o /app .

# Final lightweight stage
FROM alpine:3.21 AS final

# Copy the compiled binary from the builder stage
COPY --from=builder /app /bin/app

# Expose the application's port
EXPOSE 8000

# Run the application
CMD ["bin/app"]
```

## [Understanding the Dockerfile](#understanding-the-dockerfile)

The Dockerfile consists of two stages:

1. **Build stage**: This stage uses the official Golang image as the base and sets the necessary environment variables. It also sets the working directory inside the container, copies the `go.mod` and `go.sum` files for dependency installation, downloads the dependencies, copies the entire application source, and builds the Go binary.

   You use the `golang:1.24-alpine` image as the base image for the build stage. The `CGO_ENABLED=0` environment variable disables CGO, which is useful for building static binaries. You also set the `GOOS` and `GOARCH` environment variables to `linux` and `amd64`, respectively, to build the binary for the Linux platform.

2. **Final stage**: This stage uses the official Alpine image as the base and copies the compiled binary from the build stage. It also exposes the application's port and runs the application.

   You use the `alpine:3.21` image as the base image for the final stage. You copy the compiled binary from the build stage to the final image. You expose the application's port using the `EXPOSE` instruction and run the application using the `CMD` instruction.

   Apart from the multi-stage build, the Dockerfile also follows best practices such as using the official images, setting the working directory, and copying only the necessary files to the final image. You can further optimize the Dockerfile by other best practices.

## [Build the Docker image and run the application](#build-the-docker-image-and-run-the-application)

One you have the Dockerfile, you can build the Docker image and run the application in a container.

To build the Docker image, run the following command in the terminal:

```console
$ docker build -t go-api:latest .
```

After building the image, you can run the application in a container using the following command:

```console
$ docker run -p 8000:8000 go-api:latest
```

The application will start running inside the container, and you can access it at `http://localhost:8000`. You can also check the running containers using the `docker ps` command.

```console
$ docker ps
```

## [Summary](#summary)

In this section, you learned how to containerize a Golang application using a Dockerfile. You created a multi-stage Dockerfile to build and run the application in a container. You also learned about best practices to optimize the Docker image size and make it more secure.

Related information:

* [Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
* [.dockerignore file](https://docs.docker.com/reference/dockerfile/#dockerignore-file)

## [Next steps](#next-steps)

In the next section, you will learn how to use Docker Compose to connect and run multiple services together to monitor a Golang application with Prometheus and Grafana.

[Connecting services with Docker Compose »](https://docs.docker.com/guides/go-prometheus-monitoring/compose/)

----
url: https://docs.docker.com/guides/lab-docker-for-ai-redirect/
----

***

## All guides

Filtered results: showing 12 out of 102 guides.

----
url: https://docs.docker.com/guides/pre-seeding/
----

[Pre-seeding database with schema and data at startup for development environment](https://docs.docker.com/guides/pre-seeding/)

Pre-seeding database with schema and data at startup for development environment

App development Databases

20 minutes

[« Back to all guides](/guides/)

# Pre-seeding database with schema and data at startup for development environment

***

Table of contents

***

Pre-seeding databases with essential data and schema during local development is a common practice to enhance the development and testing workflow. By simulating real-world scenarios, this practice helps catch frontend issues early, ensures alignment between Database Administrators and Software Engineers, and facilitates smoother collaboration. Pre-seeding offers benefits like confident deployments, consistency across environments, and early issue detection, ultimately improving the overall development process.

In this guide, you will learn how to:

* Use Docker to launch up a Postgres container
* Pre-seed Postgres using a SQL script
* Pre-seed Postgres by copying SQL files into Docker image
* Pre-seed Postgres using JavaScript code

## [Using Postgres with Docker](#using-postgres-with-docker)

The [official Docker image for Postgres](https://hub.docker.com/_/postgres) provides a convenient way to run Postgres database on your development machine. A Postgres Docker image is a pre-configured environment that encapsulates the PostgreSQL database system. It's a self-contained unit, ready to run in a Docker container. By using this image, you can quickly and easily set up a Postgres instance without the need for manual configuration.

## [Prerequisites](#prerequisites)

The following prerequisites are required to follow along with this how-to guide:

* [Docker Desktop](https://www.docker.com/products/docker-desktop/)

## [Launching Postgres](#launching-postgres)

Launch a quick demo of Postgres by using the following steps:

1. Open the terminal and run the following command to start a Postgres container.

   This example will launch a Postgres container, expose port `5432` onto the host to let a native-running application to connect to it with the password `mysecretpassword`.

   ```console
   $ docker run -d --name postgres -p 5432:5432 -e POSTGRES_PASSWORD=mysecretpassword postgres
   ```

2. Verify that Postgres is up and running by selecting the container and checking the logs on Docker Dashboard.

   ```plaintext
   PostgreSQL Database directory appears to contain a database; Skipping initialization

   2024-09-08 09:09:47.136 UTC [1] LOG:  starting PostgreSQL 16.4 (Debian 16.4-1.pgdg120+1) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit
   2024-09-08 09:09:47.137 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
   2024-09-08 09:09:47.137 UTC [1] LOG:  listening on IPv6 address "::", port 5432
   2024-09-08 09:09:47.139 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
   2024-09-08 09:09:47.142 UTC [29] LOG:  database system was shut down at 2024-09-08 09:07:09 UTC
   2024-09-08 09:09:47.148 UTC [1] LOG:  database system is ready to accept connections
   ```

3. Connect to Postgres from the local system.

   The `psql` is the PostgreSQL interactive shell that is used to connect to a Postgres database and let you start executing SQL commands. Assuming that you already have `psql` utility installed on your local system, it's time to connect to the Postgres database. Run the following command on your local terminal:

   ```console
   $ docker exec -it postgres psql -h localhost -U postgres
   ```

   You can now execute any SQL queries or commands you need within the `psql` prompt.

   Use `\q` or `\quit` to exit from the Postgres interactive shell.

## [Pre-seed the Postgres database using a SQL script](#pre-seed-the-postgres-database-using-a-sql-script)

Now that you've familiarized yourself with Postgres, it's time to see how to pre-seed it with sample data. In this demonstration, you'll first create a script that holds SQL commands. The script defines the database, and table structure and inserts sample data. Then you will connect the database to verify the data.

Assuming that you have an existing Postgres database instance up and running, follow these steps to seed the database.

1. Create an empty file named `seed.sql` and add the following content.

   ```sql
   CREATE DATABASE sampledb;

   \c sampledb

   CREATE TABLE users (
     id SERIAL PRIMARY KEY,
     name VARCHAR(50),
     email VARCHAR(100) UNIQUE
   );

   INSERT INTO users (name, email) VALUES
     ('Alpha', 'alpha@example.com'),
     ('Beta', 'beta@example.com'),
     ('Gamma', 'gamma@example.com');  
   ```

   The SQL script creates a new database called `sampledb`, connects to it, and creates a `users` table. The table includes an auto-incrementing `id` as the primary key, a `name` field with a maximum length of 50 characters, and a unique `email` field with up to 100 characters.

   After creating the table, the `INSERT` command inserts three users into the `users` table with their respective names and emails. This setup forms a basic database structure to store user information with unique email addresses.

2. Seed the database.

   It’s time to feed the content of the `seed.sql` directly into the database by using the `<` operator. The command is used to execute a SQL script named `seed.sql` against a Postgres database named `sampledb`.

   ```console
   $ cat seed.sql | docker exec -i postgres psql -h localhost -U postgres -f-
   ```

   Once the query is executed, you will see the following results:

   ```plaintext
   CREATE DATABASE
   You are now connected to database "sampledb" as user "postgres".
   CREATE TABLE
   INSERT 0 3
   ```

3. Run the following `psql` command to verify if the table named users is populated in the database `sampledb` or not.

   ```console
   $ docker exec -it postgres psql -h localhost -U postgres sampledb
   ```

   You can now run `\l` in the `psql` shell to list all the databases on the Postgres server.

   ```console
   sampledb=# \l
                                                List of databases
   Name    |  Owner   | Encoding |  Collate   |   Ctype    | ICU Locale | Locale Provider |   Access privileges
   -----------+----------+----------+------------+------------+------------+-----------------+-----------------------
   postgres  | postgres | UTF8     | en_US.utf8 | en_US.utf8 |            | libc            |
   sampledb  | postgres | UTF8     | en_US.utf8 | en_US.utf8 |            | libc            |
   template0 | postgres | UTF8     | en_US.utf8 | en_US.utf8 |            | libc            | =c/postgres          +
             |          |          |            |            |            |                 | postgres=CTc/postgres
   template1 | postgres | UTF8     | en_US.utf8 | en_US.utf8 |            | libc            | =c/postgres          +
             |          |          |            |            |            |                 | postgres=CTc/postgres
   (4 rows)
   ```

   To retrieve all the data from the users table, enter the following query:

   ```console
   sampledb=# SELECT * FROM users;
   id | name  |       email
   ----+-------+-------------------
    1 | Alpha | alpha@example.com
    2 | Beta  | beta@example.com
    3 | Gamma | gamma@example.com
   (3 rows)
   ```

   Use `\q` or `\quit` to exit from the Postgres interactive shell.

## [Pre-seed the database by bind-mounting a SQL script](#pre-seed-the-database-by-bind-mounting-a-sql-script)

In Docker, mounting refers to making files or directories from the host system accessible within a container. This let you to share data or configuration files between the host and the container, enabling greater flexibility and persistence.

Now that you have learned how to launch Postgres and pre-seed the database using an SQL script, it’s time to learn how to mount an SQL file directly into the Postgres containers’ initialization directory (`/docker-entrypoint-initdb.d`). The `/docker-entrypoint-initdb.d` is a special directory in PostgreSQL Docker containers that is used for initializing the database when the container is first started

Make sure you stop any running Postgres containers (along with volumes) to prevent port conflicts before you follow the steps:

```console
$ docker container stop postgres
```

1. Modify the `seed.sql` with the following entries:

   ```sql
   CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(50),
    email VARCHAR(100) UNIQUE
   );

   INSERT INTO users (name, email) VALUES
    ('Alpha', 'alpha@example.com'),
    ('Beta', 'beta@example.com'),
    ('Gamma', 'gamma@example.com')
   ON CONFLICT (email) DO NOTHING;
   ```

2. Create a text file named `Dockerfile` and copy the following content.

   ```plaintext
   # syntax=docker/dockerfile:1
   FROM postgres:18
   COPY seed.sql /docker-entrypoint-initdb.d/
   ```

   This Dockerfile copies the `seed.sql` script directly into the PostgreSQL container's initialization directory.

3. Use Docker Compose.

   Using Docker Compose makes it even easier to manage and deploy the PostgreSQL container with the seeded database. This compose.yml file defines a Postgres service named `db` using the latest Postgres image, which sets up a database with the name `sampledb`, along with a user `postgres` and a password `mysecretpassword`.

   ```yaml
   services:
     db:
       build:
         context: .
         dockerfile: Dockerfile
       container_name: my_postgres_db
       environment:
         POSTGRES_USER: postgres
         POSTGRES_PASSWORD: mysecretpassword
         POSTGRES_DB: sampledb
       ports:
         - "5432:5432"
       volumes:
         - data_sql:/var/lib/postgresql   # Persistent data storage

   volumes:
     data_sql:
   ```

   It maps port `5432` on the host to the container's `5432`, let you access to the Postgres database from outside the container. It also define `data_sql` for persisting the database data, ensuring that data is not lost when the container is stopped.

   It is important to note that the port mapping to the host is only necessary if you want to connect to the database from non-containerized programs. If you containerize the service that connects to the DB, you should connect to the database over a custom bridge network.

4. Bring up the Compose service.

   Assuming that you've placed the `seed.sql` file in the same directory as the Dockerfile, execute the following command:

   ```console
   $ docker compose up -d --build
   ```

5. It’s time to verify if the table `users` get populated with the data.

   ```console
   $ docker exec -it my_postgres_db psql -h localhost -U postgres sampledb
   ```

   ```sql
   sampledb=# SELECT * FROM users;
     id | name  |       email
   ----+-------+-------------------
      1 | Alpha | alpha@example.com
      2 | Beta  | beta@example.com
      3 | Gamma | gamma@example.com
    (3 rows)

   sampledb=#
   ```

## [Pre-seed the database using JavaScript code](#pre-seed-the-database-using-javascript-code)

Now that you have learned how to seed the database using various methods like SQL script, mounting volumes etc., it's time to try to achieve it using JavaScript code.

1. Create a .env file with the following:

   ```plaintext
   POSTGRES_USER=postgres
   POSTGRES_DB_HOST=localhost
   POSTGRES_DB=sampledb
   POSTGRES_PASSWORD=mysecretpassword
   POSTGRES_PORT=5432
   ```

2. Create a new JavaScript file called seed.js with the following content:

   The following JavaScript code imports the `dotenv` package which is used to load environment variables from an `.env` file. The `.config()` method reads the `.env` file and sets the environment variables as properties of the `process.env` object. This let you to securely store sensitive information like database credentials outside of your code.

   Then, it creates a new Pool instance from the pg library, which provides a connection pool for efficient database interactions. The `seedData` function is defined to perform the database seeding operations. It is called at the end of the script to initiate the seeding process. The try...catch...finally block is used for error handling.

   ```plaintext
   require('dotenv').config();  // Load environment variables from .env file
   const { Pool } = require('pg');

   // Create a new pool using environment variables
   const pool = new Pool({
     user: process.env.POSTGRES_USER,
     host: process.env.POSTGRES_DB_HOST,
     database: process.env.POSTGRES_DB,
     port: process.env.POSTGRES_PORT,
     password: process.env.POSTGRES_PASSWORD,
   });

   const seedData = async () => {
     try {
        // Drop the table if it already exists (optional)
        await pool.query(`DROP TABLE IF EXISTS todos;`);

        // Create the table with the correct structure
        await pool.query(`
          CREATE TABLE todos (
            id SERIAL PRIMARY KEY,
            task VARCHAR(255) NOT NULL,
            completed BOOLEAN DEFAULT false
              );
        `   );

        // Insert seed data
        await pool.query(`
          INSERT INTO todos (task, completed) VALUES
          ('Watch netflix', false),
          ('Finish podcast', false),
          ('Pick up kid', false);
          `);
          console.log('Database seeded successfully!');
        } catch (err) {
          console.error('Error seeding the database', err);
        } finally {
          pool.end();
       }
     };

     // Call the seedData function to run the script
     seedData();
   ```

3. Kick off the seeding process

   ```console
   $ node seed.js
   ```

   You should see the following command:

   ```plaintext
   Database seeded successfully!
   ```

4. Verify if the database is seeded correctly:

   ```console
   $ docker exec -it postgres psql -h localhost -U postgres sampledb
   ```

   ```console
   sampledb=# SELECT * FROM todos;
   id |      task      | completed
   ----+----------------+-----------
   1 | Watch netflix  | f
   2 | Finish podcast | f
   3 | Pick up kid    | f
   (3 rows)  
   ```

## [Recap](#recap)

Pre-seeding a database with schema and data at startup is essential for creating a consistent and realistic testing environment, which helps in identifying issues early in development and aligning frontend and backend work. This guide has equipped you with the knowledge and practical steps to achieve pre-seeding using various methods, including SQL script, Docker integration, and JavaScript code.

----
url: https://docs.docker.com/reference/samples/postgres/
----

# PostgreSQL samples

| Name                                                                                                   | Description                                                                                                                        |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| [Go / NGINX / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/nginx-golang-postgres) | A sample Go application with an Nginx proxy and a PostgreSQL database.                                                             |
| [PostgreSQL / pgAdmin](https://github.com/docker/awesome-compose/tree/master/postgresql-pgadmin)       | A sample setup for postgreSQL database with pgAdmin web interface.                                                                 |
| [React / Rust / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/react-rust-postgres) | A sample React application with a Rust backend and a Postgres database.                                                            |
| [Spring / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/spring-postgres)           | A sample Java application with Spring framework and a Postgres database.                                                           |
| [Nextcloud / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/nextcloud-postgres)     | A sample Nextcloud setup.                                                                                                          |
| [example-voting-app](https://github.com/dockersamples/example-voting-app)                              | A sample Docker Compose app.                                                                                                       |
| [atsea-sample-shop-app](https://github.com/dockersamples/atsea-sample-shop-app)                        | A sample app that uses a Java Spring Boot backend connected to a database to display a fictitious art shop with a React front-end. |
| [wordsmith](https://github.com/dockersamples/wordsmith)                                                | A demo app that runs three containers, including PostgreSQL, Java, and Go.                                                         |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: http://docs.docker.com/go/buildx/
----

# Docker Build Overview

***

Table of contents

***

> Note
>
> While `docker build` invokes Buildx under the hood, there are subtle differences between this command and the canonical `docker buildx build`. For details, see [Difference between `docker build` and `docker buildx build`](https://docs.docker.com/build/builders/#difference-between-docker-build-and-docker-buildx-build).

----
url: https://docs.docker.com/guides/tensorflowjs/
----

[Face detection with TensorFlow.js](https://docs.docker.com/guides/tensorflowjs/)

This guide explains how to run TensorFlow\.js in Docker containers.

JavaScript AI

20 minutes

[« Back to all guides](/guides/)

# Face detection with TensorFlow\.js

***

Table of contents

***

This guide introduces the seamless integration of TensorFlow\.js with Docker to perform face detection. In this guide, you'll explore how to:

* Run a containerized TensorFlow\.js application using Docker.
* Implement face detection in a web application with TensorFlow\.js.
* Construct a Dockerfile for a TensorFlow\.js web application.
* Use Docker Compose for real-time application development and updates.
* Share your Docker image on Docker Hub to facilitate deployment and extend reach.

> **Acknowledgment**
>
> Docker would like to thank [Harsh Manvar](https://github.com/harsh4870) for his contribution to this guide.

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [Git client](https://git-scm.com/downloads). The examples in this guide use a command-line based Git client, but you can use any client.

## [What is TensorFlow.js?](#what-is-tensorflowjs)

[TensorFlow.js](https://www.tensorflow.org/js) is an open-source JavaScript library for machine learning that enables you to train and deploy ML models in the browser or on Node.js. It supports creating new models from scratch or using pre-trained models, facilitating a wide range of ML applications directly in web environments. TensorFlow\.js offers efficient computation, making sophisticated ML tasks accessible to web developers without deep ML expertise.

## [Why use TensorFlow.js and Docker together?](#why-use-tensorflowjs-and-docker-together)

* Environment consistency and simplified deployment: Docker packages TensorFlow\.js applications and their dependencies into containers, ensuring consistent runs across all environments and simplifying deployment.
* Efficient development and easy scaling: Docker enhances development efficiency with features like hot reloading and facilitates easy scaling of - TensorFlow\.js applications using orchestration tools like Kubernetes.
* Isolation and enhanced security: Docker isolates TensorFlow\.js applications in secure environments, minimizing conflicts and security vulnerabilities while running applications with limited permissions.

## [Get and run the sample application](#get-and-run-the-sample-application)

In a terminal, clone the sample application using the following command.

```console
$ git clone https://github.com/harsh4870/TensorJS-Face-Detection
```

After cloning the application, you'll notice the application has a `Dockerfile`. This Dockerfile lets you build and run the application locally with nothing more than Docker.

Before you run the application as a container, you must build it into an image. Run the following command inside the `TensorJS-Face-Detection` directory to build an image named `face-detection-tensorjs`.

```console
$ docker build -t face-detection-tensorjs .
```

The command builds the application into an image. Depending on your network connection, it can take several minutes to download the necessary components the first time you run the command.

To run the image as a container, run the following command in a terminal.

```console
$ docker run -p 80:80 face-detection-tensorjs
```

The command runs the container and maps port 80 in the container to port 80 on your system.

Once the application is running, open a web browser and access the application at <http://localhost:80>. You may need to grant access to your webcam for the application.

In the web application, you can change the backend to use one of the following:

* WASM
* WebGL
* CPU

To stop the application, press `ctrl`+`c` in the terminal.

## [About the application](#about-the-application)

The sample application performs real-time face detection using [MediaPipe](https://developers.google.com/mediapipe/), a comprehensive framework for building multimodal machine learning pipelines. It's specifically using the BlazeFace model, a lightweight model for detecting faces in images.

In the context of TensorFlow\.js or similar web-based machine learning frameworks, the WASM, WebGL, and CPU backends can be used to execute operations. Each of these backends utilizes different resources and technologies available in modern browsers and has its strengths and limitations. The following sections are a brief breakdown of the different backends.

### [WASM](#wasm)

WebAssembly (WASM) is a low-level, assembly-like language with a compact binary format that runs at near-native speed in web browsers. It allows code written in languages like C/C++ to be compiled into a binary that can be executed in the browser.

It's a good choice when high performance is required, and either the WebGL backend is not supported or you want consistent performance across all devices without relying on the GPU.

### [WebGL](#webgl)

WebGL is a browser API that allows for GPU-accelerated usage of physics and image processing and effects as part of the web page canvas.

WebGL is well-suited for operations that are parallelizable and can significantly benefit from GPU acceleration, such as matrix multiplications and convolutions commonly found in deep learning models.

### [CPU](#cpu)

The CPU backend uses pure JavaScript execution, utilizing the device's central processing unit (CPU). This backend is the most universally compatible and serves as a fallback when neither WebGL nor WASM backends are available or suitable.

## [Explore the application's code](#explore-the-applications-code)

Explore the purpose of each file and their contents in the following sections.

### [The index.html file](#the-indexhtml-file)

The `index.html` file serves as the frontend for the web application that utilizes TensorFlow\.js for real-time face detection from the webcam video feed. It incorporates several technologies and libraries to facilitate machine learning directly in the browser. It uses several TensorFlow\.js libraries, including:

* tfjs-core and tfjs-converter for core TensorFlow\.js functionality and model conversion.
* tfjs-backend-webgl, tfjs-backend-cpu, and the tf-backend-wasm script for different computational backend options that TensorFlow\.js can use for processing. These backends allow the application to perform machine learning tasks efficiently by leveraging the user's hardware capabilities.
* The BlazeFace library, a TensorFlow model for face detection.

It also uses the following additional libraries:

* dat.GUI for creating a graphical interface to interact with the application's settings in real-time, such as switching between TensorFlow\.js backends.
* Stats.min.js for displaying performance metrics (like FPS) to monitor the application's efficiency during operation.

```html
<style>
  body {
    margin: 25px;
  }

  .true {
    color: green;
  }

  .false {
    color: red;
  }

  #main {
    position: relative;
    margin: 50px 0;
  }

  canvas {
    position: absolute;
    top: 0;
    left: 0;
  }

  #description {
    margin-top: 20px;
    width: 600px;
  }

  #description-title {
    font-weight: bold;
    font-size: 18px;
  }
</style>

<body>
  <div id="main">
    <video
      id="video"
      playsinline
      style="
      -webkit-transform: scaleX(-1);
      transform: scaleX(-1);
      width: auto;
      height: auto;
      "
    ></video>
    <canvas id="output"></canvas>
    <video
      id="video"
      playsinline
      style="
      -webkit-transform: scaleX(-1);
      transform: scaleX(-1);
      visibility: hidden;
      width: auto;
      height: auto;
      "
    ></video>
  </div>
</body>
<script src="https://unpkg.com/@tensorflow/tfjs-core@2.1.0/dist/tf-core.js"></script>
<script src="https://unpkg.com/@tensorflow/tfjs-converter@2.1.0/dist/tf-converter.js"></script>

<script src="https://unpkg.com/@tensorflow/tfjs-backend-webgl@2.1.0/dist/tf-backend-webgl.js"></script>
<script src="https://unpkg.com/@tensorflow/tfjs-backend-cpu@2.1.0/dist/tf-backend-cpu.js"></script>
<script src="./tf-backend-wasm.js"></script>

<script src="https://unpkg.com/@tensorflow-models/blazeface@0.0.5/dist/blazeface.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/dat-gui/0.7.6/dat.gui.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/stats.js/r16/Stats.min.js"></script>
<script src="./index.js"></script>
```

### [The index.js file](#the-indexjs-file)

The `index.js` file conducts the facial detection logic. It demonstrates several advanced concepts in web development and machine learning integration. Here's a breakdown of some of its key components and functionalities:

* Stats.js: The script starts by creating a Stats instance to monitor and display the frame rate (FPS) of the application in real time. This is helpful for performance analysis, especially when testing the impact of different TensorFlow\.js backends on the application's speed.
* TensorFlow\.js: The application allows users to switch between different computation backends (wasm, webgl, and cpu) for TensorFlow\.js through a graphical interface provided by dat.GUI. Changing the backend can affect performance and compatibility depending on the device and browser. The addFlagLabels function dynamically checks and displays whether SIMD (Single Instruction, Multiple Data) and multithreading are supported, which are relevant for performance optimization in the wasm backend.
* setupCamera function: Initializes the user's webcam using the MediaDevices Web API. It configures the video stream to not include audio and to use the front-facing camera (facingMode: 'user'). Once the video metadata is loaded, it resolves a promise with the video element, which is then used for face detection.
* BlazeFace: The core of this application is the renderPrediction function, which performs real-time face detection using the BlazeFace model, a lightweight model for detecting faces in images. The function calls model.estimateFaces on each animation frame to detect faces from the video feed. For each detected face, it draws a red rectangle around the face and blue dots for facial landmarks on a canvas overlaying the video.

```javascript
const stats = new Stats();
stats.showPanel(0);
document.body.prepend(stats.domElement);

let model, ctx, videoWidth, videoHeight, video, canvas;

const state = {
  backend: "wasm",
};

const gui = new dat.GUI();
gui
  .add(state, "backend", ["wasm", "webgl", "cpu"])
  .onChange(async (backend) => {
    await tf.setBackend(backend);
    addFlagLabels();
  });

async function addFlagLabels() {
  if (!document.querySelector("#simd_supported")) {
    const simdSupportLabel = document.createElement("div");
    simdSupportLabel.id = "simd_supported";
    simdSupportLabel.style = "font-weight: bold";
    const simdSupported = await tf.env().getAsync("WASM_HAS_SIMD_SUPPORT");
    simdSupportLabel.innerHTML = `SIMD supported: <span class=${simdSupported}>${simdSupported}<span>`;
    document.querySelector("#description").appendChild(simdSupportLabel);
  }

  if (!document.querySelector("#threads_supported")) {
    const threadSupportLabel = document.createElement("div");
    threadSupportLabel.id = "threads_supported";
    threadSupportLabel.style = "font-weight: bold";
    const threadsSupported = await tf
      .env()
      .getAsync("WASM_HAS_MULTITHREAD_SUPPORT");
    threadSupportLabel.innerHTML = `Threads supported: <span class=${threadsSupported}>${threadsSupported}</span>`;
    document.querySelector("#description").appendChild(threadSupportLabel);
  }
}

async function setupCamera() {
  video = document.getElementById("video");

  const stream = await navigator.mediaDevices.getUserMedia({
    audio: false,
    video: { facingMode: "user" },
  });
  video.srcObject = stream;

  return new Promise((resolve) => {
    video.onloadedmetadata = () => {
      resolve(video);
    };
  });
}

const renderPrediction = async () => {
  stats.begin();

  const returnTensors = false;
  const flipHorizontal = true;
  const annotateBoxes = true;
  const predictions = await model.estimateFaces(
    video,
    returnTensors,
    flipHorizontal,
    annotateBoxes,
  );

  if (predictions.length > 0) {
    ctx.clearRect(0, 0, canvas.width, canvas.height);

    for (let i = 0; i < predictions.length; i++) {
      if (returnTensors) {
        predictions[i].topLeft = predictions[i].topLeft.arraySync();
        predictions[i].bottomRight = predictions[i].bottomRight.arraySync();
        if (annotateBoxes) {
          predictions[i].landmarks = predictions[i].landmarks.arraySync();
        }
      }

      const start = predictions[i].topLeft;
      const end = predictions[i].bottomRight;
      const size = [end[0] - start[0], end[1] - start[1]];
      ctx.fillStyle = "rgba(255, 0, 0, 0.5)";
      ctx.fillRect(start[0], start[1], size[0], size[1]);

      if (annotateBoxes) {
        const landmarks = predictions[i].landmarks;

        ctx.fillStyle = "blue";
        for (let j = 0; j < landmarks.length; j++) {
          const x = landmarks[j][0];
          const y = landmarks[j][1];
          ctx.fillRect(x, y, 5, 5);
        }
      }
    }
  }

  stats.end();

  requestAnimationFrame(renderPrediction);
};

const setupPage = async () => {
  await tf.setBackend(state.backend);
  addFlagLabels();
  await setupCamera();
  video.play();

  videoWidth = video.videoWidth;
  videoHeight = video.videoHeight;
  video.width = videoWidth;
  video.height = videoHeight;

  canvas = document.getElementById("output");
  canvas.width = videoWidth;
  canvas.height = videoHeight;
  ctx = canvas.getContext("2d");
  ctx.fillStyle = "rgba(255, 0, 0, 0.5)";

  model = await blazeface.load();

  renderPrediction();
};

setupPage();
```

### [The tf-backend-wasm.js file](#the-tf-backend-wasmjs-file)

The `tf-backend-wasm.js` file is part of the [TensorFlow.js library](https://github.com/tensorflow/tfjs/tree/master/tfjs-backend-wasm). It contains initialization logic for the TensorFlow\.js WASM backend, some utilities for interacting with the WASM binaries, and functions to set custom paths for the WASM binaries.

### [The tfjs-backend-wasm-simd.wasm file](#the-tfjs-backend-wasm-simdwasm-file)

The `tfjs-backend-wasm-simd.wasm` file is part of the [TensorFlow.js library](https://github.com/tensorflow/tfjs/tree/master/tfjs-backend-wasm). It's a WASM binary that's used for the WebAssembly backend, specifically optimized to utilize SIMD (Single Instruction, Multiple Data) instructions.

## [Explore the Dockerfile](#explore-the-dockerfile)

In a Docker-based project, the Dockerfile serves as the foundational asset for building your application's environment.

A Dockerfile is a text file that instructs Docker how to create an image of your application's environment. An image contains everything you want and need when running application, such as files, packages, and tools.

The following is the Dockerfile for this project.

```dockerfile
FROM nginx:stable-alpine3.17-slim
WORKDIR /usr/share/nginx/html
COPY . .
```

This Dockerfile defines an image that serves static content using Nginx from an Alpine Linux base image.

## [Develop with Compose](#develop-with-compose)

Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application's services, networks, and volumes. In this case, the application isn't a multi-container application, but Docker Compose has other useful features for development, like [Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

The sample application doesn't have a Compose file yet. To create a Compose file, in the `TensorJS-Face-Detection` directory, create a text file named `compose.yaml` and then add the following contents.

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 80:80
    develop:
      watch:
        - action: sync
          path: .
          target: /usr/share/nginx/html
```

This Compose file defines a service that is built using the Dockerfile in the same directory. It maps port 80 on the host to port 80 in the container. It also has a `develop` subsection with the `watch` attribute that defines a list of rules that control automatic service updates based on local file changes. For more details about the Compose instructions, see the [Compose file reference](https://docs.docker.com/reference/compose-file/).

Save the changes to your `compose.yaml` file and then run the following command to run the application.

```console
$ docker compose watch
```

Once the application is running, open a web browser and access the application at <http://localhost:80>. You may need to grant access to your webcam for the application.

Now you can make changes to the source code and see the changes automatically reflected in the container without having to rebuild and rerun the container.

Open the `index.js` file and update the landmark points to be green instead of blue on line 83.

```diff
-        ctx.fillStyle = "blue";
+        ctx.fillStyle = "green";
```

Save the changes to the `index.js` file and then refresh the browser page. The landmark points should now appear green.

To stop the application, press `ctrl`+`c` in the terminal.

## [Share your image](#share-your-image)

Publishing your Docker image on Docker Hub streamlines deployment processes for others, enabling seamless integration into diverse projects. It also promotes the adoption of your containerized solutions, broadening their impact across the developer ecosystem. To share your image:

1. [Sign up](https://www.docker.com/pricing?ref=Docs\&refAction=DocsGuidesTensorflowjs) or sign in to [Docker Hub](https://hub.docker.com).

2. Rebuild your image to include the changes to your application. This time, prefix the image name with your Docker ID. Docker uses the name to determine which repository to push it to. Open a terminal and run the following command in the `TensorJS-Face-Detection` directory. Replace `YOUR-USER-NAME` with your Docker ID.

   ```console
   $ docker build -t YOUR-USER-NAME/face-detection-tensorjs .
   ```

3. Run the following `docker push` command to push the image to Docker Hub. Replace `YOUR-USER-NAME` with your Docker ID.

   ```console
   $ docker push YOUR-USER-NAME/face-detection-tensorjs
   ```

4. Verify that you pushed the image to Docker Hub.

   1. Go to [Docker Hub](https://hub.docker.com).
   2. Select **My Hub** > **Repositories**.
   3. View the **Last pushed** time for your repository.

Other users can now download and run your image using the `docker run` command. They need to replace `YOUR-USER-NAME` with your Docker ID.

```console
$ docker run -p 80:80 YOUR-USER-NAME/face-detection-tensorjs
```

## [Summary](#summary)

This guide demonstrated leveraging TensorFlow\.js and Docker for face detection in web applications. It highlighted the ease of running containerized TensorFlow\.js applications, and developing with Docker Compose for real-time code changes. Additionally, it covered how sharing your Docker image on Docker Hub can streamline deployment for others, enhancing the application's reach within the developer community.

Related information:

* [TensorFlow.js website](https://www.tensorflow.org/js)
* [MediaPipe website](https://developers.google.com/mediapipe/)
* [Dockerfile reference](/reference/dockerfile/)
* [Compose file reference](https://docs.docker.com/reference/compose-file/)
* [Docker CLI reference](/reference/cli/docker/)
* [Docker Blog: Accelerating Machine Learning with TensorFlow.js](https://www.docker.com/blog/accelerating-machine-learning-with-tensorflow-js-using-pretrained-models-and-docker/)

----
url: https://docs.docker.com/engine/containers/multi-service_container/
----

# Run multiple processes in a container

***

Table of contents

***

A container's main running process is the `ENTRYPOINT` and/or `CMD` at the end of the `Dockerfile`. It's best practice to separate areas of concern by using one service per container. That service may fork into multiple processes (for example, Apache web server starts multiple worker processes). It's ok to have multiple processes, but to get the most benefit out of Docker, avoid one container being responsible for multiple aspects of your overall application. You can connect multiple containers using user-defined networks and shared volumes.

The container's main process is responsible for managing all processes that it starts. In some cases, the main process isn't well-designed, and doesn't handle "reaping" (stopping) child processes gracefully when the container exits. If your process falls into this category, you can use the `--init` option when you run the container. The `--init` flag inserts a tiny init-process into the container as the main process, and handles reaping of all processes when the container exits. Handling such processes this way is superior to using a full-fledged init process such as `sysvinit` or `systemd` to handle process lifecycle within your container.

If you need to run more than one service within a container, you can achieve this in a few different ways.

## [Use a wrapper script](#use-a-wrapper-script)

Put all of your commands in a wrapper script, complete with testing and debugging information. Run the wrapper script as your `CMD`. The following is a naive example. First, the wrapper script:

```bash
#!/bin/bash

# Start the first process
./my_first_process &

# Start the second process
./my_second_process &

# Wait for any process to exit
wait -n

# Exit with status of process that exited first
exit $?
```

Next, the Dockerfile:

```dockerfile
# syntax=docker/dockerfile:1
FROM ubuntu:latest
COPY my_first_process my_first_process
COPY my_second_process my_second_process
COPY my_wrapper_script.sh my_wrapper_script.sh
CMD ./my_wrapper_script.sh
```

## [Use Bash job controls](#use-bash-job-controls)

If you have one main process that needs to start first and stay running but you temporarily need to run some other processes (perhaps to interact with the main process) then you can use bash's job control. First, the wrapper script:

```bash
#!/bin/bash

# turn on bash's job control
set -m

# Start the primary process and put it in the background
./my_main_process &

# Start the helper process
./my_helper_process

# the my_helper_process might need to know how to wait on the
# primary process to start before it does its work and returns


# now we bring the primary process back into the foreground
# and leave it there
fg %1
```

```dockerfile
# syntax=docker/dockerfile:1
FROM ubuntu:latest
COPY my_main_process my_main_process
COPY my_helper_process my_helper_process
COPY my_wrapper_script.sh my_wrapper_script.sh
CMD ./my_wrapper_script.sh
```

## [Use a process manager](#use-a-process-manager)

Use a process manager like `supervisord`. This is more involved than the other options, as it requires you to bundle `supervisord` and its configuration into your image (or base your image on one that includes `supervisord`), along with the different applications it manages. Then you start `supervisord`, which manages your processes for you.

The following Dockerfile example shows this approach. The example assumes that these files exist at the root of the build context:

* `supervisord.conf`
* `my_first_process`
* `my_second_process`

```dockerfile
# syntax=docker/dockerfile:1
FROM ubuntu:latest
RUN apt-get update && apt-get install -y supervisor
RUN mkdir -p /var/log/supervisor
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
COPY my_first_process my_first_process
COPY my_second_process my_second_process
CMD ["/usr/bin/supervisord"]
```

If you want to make sure both processes output their `stdout` and `stderr` to the container logs, you can add the following to the `supervisord.conf` file:

```ini
[supervisord]
nodaemon=true
logfile=/dev/null
logfile_maxbytes=0

[program:app]
stdout_logfile=/dev/fd/1
stdout_logfile_maxbytes=0
redirect_stderr=true
```

----
url: https://docs.docker.com/reference/cli/docker/checkpoint/ls/
----

# docker checkpoint ls

***

| Description                                                               | List checkpoints for a container           |
| ------------------------------------------------------------------------- | ------------------------------------------ |
| Usage                                                                     | `docker checkpoint ls [OPTIONS] CONTAINER` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker checkpoint list`                   |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

List checkpoints for a container

## [Options](#options)

| Option             | Default | Description                               |
| ------------------ | ------- | ----------------------------------------- |
| `--checkpoint-dir` |         | Use a custom checkpoint storage directory |

----
url: https://docs.docker.com/reference/api/extensions-sdk/DockerDesktopClient/
----

# Interface: DockerDesktopClient

***

Table of contents

***

An amalgam of the v0 and v1 interfaces of the Docker Desktop API client, provided for backwards compatibility reasons. Unless you're working with a legacy extension, use the v1 type instead.

## [Properties](#properties)

### [backend](#backend)

• `Readonly` **backend**: `undefined` | [`BackendV0`](https://docs.docker.com/reference/api/extensions-sdk/BackendV0/)

The `window.ddClient.backend` object can be used to communicate with the backend defined in the vm section of the extension metadata. The client is already connected to the backend.

> Warning
>
> It will be removed in a future version. Use [extension](https://docs.docker.com/reference/api/extensions-sdk/DockerDesktopClient/#extension) instead.

#### [Inherited from](#inherited-from)

DockerDesktopClientV0.backend

***

### [extension](#extension)

• `Readonly` **extension**: [`Extension`](https://docs.docker.com/reference/api/extensions-sdk/Extension/)

The `ddClient.extension` object can be used to communicate with the backend defined in the vm section of the extension metadata. The client is already connected to the backend.

#### [Inherited from](#inherited-from-1)

DockerDesktopClientV1.extension

***

### [desktopUI](#desktopui)

• `Readonly` **desktopUI**: [`DesktopUI`](https://docs.docker.com/reference/api/extensions-sdk/DesktopUI/)

#### [Inherited from](#inherited-from-2)

DockerDesktopClientV1.desktopUI

***

### [host](#host)

• `Readonly` **host**: [`Host`](https://docs.docker.com/reference/api/extensions-sdk/Host/)

#### [Inherited from](#inherited-from-3)

DockerDesktopClientV1.host

***

### [docker](#docker)

• `Readonly` **docker**: [`Docker`](https://docs.docker.com/reference/api/extensions-sdk/Docker/)

#### [Inherited from](#inherited-from-4)

DockerDesktopClientV1.docker

## [Container Methods](#container-methods)

### [listContainers](#listcontainers)

▸ **listContainers**(`options`): `Promise`<`unknown`>

Get the list of running containers (same as `docker ps`).

By default, this will not list stopped containers. You can use the option `{"all": true}` to list all the running and stopped containers.

```typescript
const containers = await window.ddClient.listContainers();
```

> Warning
>
> It will be removed in a future version. Use [listContainers](https://docs.docker.com/reference/api/extensions-sdk/Docker/#listcontainers) instead.

#### [Parameters](#parameters)

| Name      | Type    | Description                                                                                                                                                                                                                                                                                                    |
| --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options` | `never` | (Optional). A JSON like `{ "all": true, "limit": 10, "size": true, "filters": JSON.stringify({ status: ["exited"] }), }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/reference/api/engine/version/v1.52/#operation/ContainerList). |

#### [Returns](#returns)

`Promise`<`unknown`>

#### [Inherited from](#inherited-from-5)

DockerDesktopClientV0.listContainers

***

## [Image Methods](#image-methods)

### [listImages](#listimages)

▸ **listImages**(`options`): `Promise`<`unknown`>

Get the list of images

```typescript
const images = await window.ddClient.listImages();
```

> Warning
>
> It will be removed in a future version. Use [listImages](https://docs.docker.com/reference/api/extensions-sdk/Docker/#listimages) instead.

#### [Parameters](#parameters-1)

| Name      | Type    | Description                                                                                                                                                                                                                                                                           |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options` | `never` | (Optional). A JSON like `{ "all": true, "filters": JSON.stringify({ dangling: ["true"] }), "digests": true }` For more information about the different properties see [the Docker API endpoint documentation](https://docs.docker.com/reference/api/engine/version/v1.52/#tag/Image). |

#### [Returns](#returns-1)

`Promise`<`unknown`>

#### [Inherited from](#inherited-from-6)

DockerDesktopClientV0.listImages

***

## [Navigation Methods](#navigation-methods)

### [navigateToContainers](#navigatetocontainers)

▸ **navigateToContainers**(): `void`

Navigate to the container's window in Docker Desktop.

```typescript
window.ddClient.navigateToContainers();
```

> Warning
>
> It will be removed in a future version. Use [viewContainers](https://docs.docker.com/reference/api/extensions-sdk/NavigationIntents/#viewcontainers) instead.

#### [Returns](#returns-2)

`void`

#### [Inherited from](#inherited-from-7)

DockerDesktopClientV0.navigateToContainers

***

### [navigateToContainer](#navigatetocontainer)

▸ **navigateToContainer**(`id`): `Promise`<`any`>

Navigate to the container window in Docker Desktop.

```typescript
await window.ddClient.navigateToContainer(id);
```

> Warning
>
> It will be removed in a future version.

#### [Parameters](#parameters-2)

| Name | Type     | Description                                                                                                                                                                                            |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |

#### [Returns](#returns-3)

`Promise`<`any`>

A promise that fails if the container doesn't exist.

#### [Inherited from](#inherited-from-8)

DockerDesktopClientV0.navigateToContainer

***

### [navigateToContainerLogs](#navigatetocontainerlogs)

▸ **navigateToContainerLogs**(`id`): `Promise`<`any`>

Navigate to the container logs window in Docker Desktop.

```typescript
await window.ddClient.navigateToContainerLogs(id);
```

> Warning
>
> It will be removed in a future version.

#### [Parameters](#parameters-3)

| Name | Type     | Description                                                                                                                                                                                            |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |

#### [Returns](#returns-4)

`Promise`<`any`>

A promise that fails if the container doesn't exist.

#### [Inherited from](#inherited-from-9)

DockerDesktopClientV0.navigateToContainerLogs

***

### [navigateToContainerInspect](#navigatetocontainerinspect)

▸ **navigateToContainerInspect**(`id`): `Promise`<`any`>

Navigate to the container inspect window in Docker Desktop.

```typescript
await window.ddClient.navigateToContainerInspect(id);
```

> Warning
>
> It will be removed in a future version.

#### [Parameters](#parameters-4)

| Name | Type     | Description                                                                                                                                                                                            |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |

#### [Returns](#returns-5)

`Promise`<`any`>

A promise that fails if the container doesn't exist.

#### [Inherited from](#inherited-from-10)

DockerDesktopClientV0.navigateToContainerInspect

***

### [navigateToContainerStats](#navigatetocontainerstats)

▸ **navigateToContainerStats**(`id`): `Promise`<`any`>

Navigate to the container stats to see the CPU, memory, disk read/write and network I/O usage.

```typescript
await window.ddClient.navigateToContainerStats(id);
```

> Warning
>
> It will be removed in a future version.

#### [Parameters](#parameters-5)

| Name | Type     | Description                                                                                                                                                                                            |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |

#### [Returns](#returns-6)

`Promise`<`any`>

A promise that fails if the container doesn't exist.

#### [Inherited from](#inherited-from-11)

DockerDesktopClientV0.navigateToContainerStats

***

### [navigateToImages](#navigatetoimages)

▸ **navigateToImages**(): `void`

Navigate to the images window in Docker Desktop.

```typescript
await window.ddClient.navigateToImages(id);
```

> Warning
>
> It will be removed in a future version. Use [viewImages](https://docs.docker.com/reference/api/extensions-sdk/NavigationIntents/#viewimages) instead.

#### [Returns](#returns-7)

`void`

#### [Inherited from](#inherited-from-12)

DockerDesktopClientV0.navigateToImages

***

### [navigateToImage](#navigatetoimage)

▸ **navigateToImage**(`id`, `tag`): `Promise`<`any`>

Navigate to a specific image referenced by `id` and `tag` in Docker Desktop. In this navigation route you can find the image layers, commands, created time and size.

```typescript
await window.ddClient.navigateToImage(id, tag);
```

> Warning
>
> It will be removed in a future version. Use [viewImage](https://docs.docker.com/reference/api/extensions-sdk/NavigationIntents/#viewimage) instead.

#### [Parameters](#parameters-6)

| Name  | Type     | Description                                                                                                        |
| ----- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `id`  | `string` | The full image id (including sha), e.g. `sha256:34ab3ae068572f4e85c448b4035e6be5e19cc41f69606535cd4d768a63432673`. |
| `tag` | `string` | The tag of the image, e.g. `latest`, `0.0.1`, etc.                                                                 |

#### [Returns](#returns-8)

`Promise`<`any`>

A promise that fails if the container doesn't exist.

#### [Inherited from](#inherited-from-13)

DockerDesktopClientV0.navigateToImage

***

### [navigateToVolumes](#navigatetovolumes)

▸ **navigateToVolumes**(): `void`

Navigate to the volumes window in Docker Desktop.

```typescript
await window.ddClient.navigateToVolumes();
```

> Warning
>
> It will be removed in a future version. Use [viewVolumes](https://docs.docker.com/reference/api/extensions-sdk/NavigationIntents/#viewvolumes) instead.

#### [Returns](#returns-9)

`void`

#### [Inherited from](#inherited-from-14)

DockerDesktopClientV0.navigateToVolumes

***

### [navigateToVolume](#navigatetovolume)

▸ **navigateToVolume**(`volume`): `void`

Navigate to a specific volume in Docker Desktop.

```typescript
window.ddClient.navigateToVolume(volume);
```

> Warning
>
> It will be removed in a future version. Use [viewVolume](https://docs.docker.com/reference/api/extensions-sdk/NavigationIntents/#viewvolume) instead.

#### [Parameters](#parameters-7)

| Name     | Type     | Description                               |
| -------- | -------- | ----------------------------------------- |
| `volume` | `string` | The name of the volume, e.g. `my-volume`. |

#### [Returns](#returns-10)

`void`

#### [Inherited from](#inherited-from-15)

DockerDesktopClientV0.navigateToVolume

***

## [Other Methods](#other-methods)

### [execHostCmd](#exechostcmd)

▸ **execHostCmd**(`cmd`): `Promise`<[`ExecResultV0`](https://docs.docker.com/reference/api/extensions-sdk/ExecResultV0/)>

Invoke a binary on the host. The binary is typically shipped with your extension using the host section in the extension metadata. Note that extensions run with user access rights, this API is not restricted to binaries listed in the host section of the extension metadata (some extensions might install software during user interaction, and invoke newly installed binaries even if not listed in the extension metadata)

```typescript
window.ddClient.execHostCmd(`cliShippedOnHost xxx`).then((cmdResult: any) => {
 console.log(cmdResult);
});
```

> Warning
>
> It will be removed in a future version. Use [exec](https://docs.docker.com/reference/api/extensions-sdk/ExtensionCli/#exec) instead.

#### [Parameters](#parameters-8)

| Name  | Type     | Description                 |
| ----- | -------- | --------------------------- |
| `cmd` | `string` | The command to be executed. |

#### [Returns](#returns-11)

`Promise`<[`ExecResultV0`](https://docs.docker.com/reference/api/extensions-sdk/ExecResultV0/)>

#### [Inherited from](#inherited-from-16)

DockerDesktopClientV0.execHostCmd

***

### [spawnHostCmd](#spawnhostcmd)

▸ **spawnHostCmd**(`cmd`, `args`, `callback`): `void`

Invoke an extension binary on your host and get the output stream.

```typescript
window.ddClient.spawnHostCmd(
  `cliShippedOnHost`,
  [`arg1`, `arg2`],
  (data: any, err: any) => {
    console.log(data.stdout, data.stderr);
    // Once the command exits we get the status code
    if (data.code) {
      console.log(data.code);
    }
  }
);
```

> Warning
>
> It will be removed in a future version. Use [exec](https://docs.docker.com/reference/api/extensions-sdk/ExtensionCli/#exec) instead.

#### [Parameters](#parameters-9)

| Name       | Type                                      | Description                                                                    |
| ---------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
| `cmd`      | `string`                                  | The command to be executed.                                                    |
| `args`     | `string`\[]                               | The arguments of the command to execute.                                       |
| `callback` | (`data`: `any`, `error`: `any`) => `void` | The callback function where to listen from the command output data and errors. |

#### [Returns](#returns-12)

`void`

#### [Inherited from](#inherited-from-17)

DockerDesktopClientV0.spawnHostCmd

***

### [execDockerCmd](#execdockercmd)

▸ **execDockerCmd**(`cmd`, `...args`): `Promise`<[`ExecResultV0`](https://docs.docker.com/reference/api/extensions-sdk/ExecResultV0/)>

You can also directly execute the Docker binary.

```typescript
const output = await window.ddClient.execDockerCmd("info");
```

> Warning
>
> It will be removed in a future version. Use [exec](https://docs.docker.com/reference/api/extensions-sdk/DockerCommand/#exec) instead.

#### [Parameters](#parameters-10)

| Name      | Type        | Description                              |
| --------- | ----------- | ---------------------------------------- |
| `cmd`     | `string`    | The command to execute.                  |
| `...args` | `string`\[] | The arguments of the command to execute. |

#### [Returns](#returns-13)

`Promise`<[`ExecResultV0`](https://docs.docker.com/reference/api/extensions-sdk/ExecResultV0/)>

The result will contain both the standard output and the standard error of the executed command:

```json
{
  "stderr": "...",
  "stdout": "..."
}
```

For convenience, the command result object also has methods to easily parse it depending on the output format:

* `output.lines(): string[]` splits output lines.
* `output.parseJsonObject(): any` parses a well-formed JSON output.
* `output.parseJsonLines(): any[]` parses each output line as a JSON object.

If the output of the command is too long, or you need to get the output as a stream you can use the

* spawnDockerCmd function:

```typescript
window.ddClient.spawnDockerCmd("logs", ["-f", "..."], (data, error) => {
  console.log(data.stdout);
});
```

#### [Inherited from](#inherited-from-18)

DockerDesktopClientV0.execDockerCmd

***

### [spawnDockerCmd](#spawndockercmd)

▸ **spawnDockerCmd**(`cmd`, `args`, `callback`): `void`

> Warning
>
> It will be removed in a future version. Use [exec](https://docs.docker.com/reference/api/extensions-sdk/DockerCommand/#exec) instead.

#### [Parameters](#parameters-11)

| Name       | Type                                      |
| ---------- | ----------------------------------------- |
| `cmd`      | `string`                                  |
| `args`     | `string`\[]                               |
| `callback` | (`data`: `any`, `error`: `any`) => `void` |

#### [Returns](#returns-14)

`void`

#### [Inherited from](#inherited-from-19)

DockerDesktopClientV0.spawnDockerCmd

***

### [openExternal](#openexternal)

▸ **openExternal**(`url`): `void`

Opens an external URL with the system default browser.

```typescript
window.ddClient.openExternal("https://docker.com");
```

> Warning
>
> It will be removed in a future version. Use [openExternal](https://docs.docker.com/reference/api/extensions-sdk/Host/#openexternal) instead.

#### [Parameters](#parameters-12)

| Name  | Type     | Description                                                           |
| ----- | -------- | --------------------------------------------------------------------- |
| `url` | `string` | The URL the browser opens (must have the protocol `http` or `https`). |

#### [Returns](#returns-15)

`void`

#### [Inherited from](#inherited-from-20)

DockerDesktopClientV0.openExternal

***

## [Toast Methods](#toast-methods)

### [toastSuccess](#toastsuccess)

▸ **toastSuccess**(`msg`): `void`

Display a toast message of type success.

```typescript
window.ddClient.toastSuccess("message");
```

> **Warning\`**
>
> It will be removed in a future version. Use [success](https://docs.docker.com/reference/api/extensions-sdk/Toast/#success) instead.

#### [Parameters](#parameters-13)

| Name  | Type     | Description                          |
| ----- | -------- | ------------------------------------ |
| `msg` | `string` | The message to display in the toast. |

#### [Returns](#returns-16)

`void`

#### [Inherited from](#inherited-from-21)

DockerDesktopClientV0.toastSuccess

***

### [toastWarning](#toastwarning)

▸ **toastWarning**(`msg`): `void`

Display a toast message of type warning.

```typescript
window.ddClient.toastWarning("message");
```

> Warning
>
> It will be removed in a future version. Use [warning](https://docs.docker.com/reference/api/extensions-sdk/Toast/#warning) instead.

#### [Parameters](#parameters-14)

| Name  | Type     | Description                          |
| ----- | -------- | ------------------------------------ |
| `msg` | `string` | The message to display in the toast. |

#### [Returns](#returns-17)

`void`

#### [Inherited from](#inherited-from-22)

DockerDesktopClientV0.toastWarning

***

### [toastError](#toasterror)

▸ **toastError**(`msg`): `void`

Display a toast message of type error.

```typescript
window.ddClient.toastError("message");
```

> Warning
>
> It will be removed in a future version. Use [error](https://docs.docker.com/reference/api/extensions-sdk/Toast/#error) instead.

#### [Parameters](#parameters-15)

| Name  | Type     | Description                          |
| ----- | -------- | ------------------------------------ |
| `msg` | `string` | The message to display in the toast. |

#### [Returns](#returns-18)

`void`

#### [Inherited from](#inherited-from-23)

DockerDesktopClientV0.toastError

----
url: https://docs.docker.com/engine/security/userns-remap/
----

# Isolate containers with a user namespace

***

Table of contents

***

Linux namespaces provide isolation for running processes, limiting their access to system resources without the running process being aware of the limitations. For more information on Linux namespaces, see [Linux namespaces](https://www.linux.com/news/understanding-and-securing-linux-namespaces).

The best way to prevent privilege-escalation attacks from within a container is to configure your container's applications to run as unprivileged users. For containers whose processes must run as the `root` user within the container, you can re-map this user to a less-privileged user on the Docker host. The mapped user is assigned a range of UIDs which function within the namespace as normal UIDs from 0 to 65536, but have no privileges on the host machine itself.

> Note
>
> With `userns-remap`, the Docker daemon still runs as root. To run both the daemon and containers without root privileges, see [Rootless mode](https://docs.docker.com/engine/security/rootless/) instead.

## [About remapping and subordinate user and group IDs](#about-remapping-and-subordinate-user-and-group-ids)

The remapping itself is handled by two files: `/etc/subuid` and `/etc/subgid`. Each file works the same, but one is concerned with the user ID range, and the other with the group ID range. Consider the following entry in `/etc/subuid`:

```text
testuser:231072:65536
```

This means that `testuser` is assigned a subordinate user ID range of `231072` and the next 65536 integers in sequence. UID `231072` is mapped within the namespace (within the container, in this case) as UID `0` (`root`). UID `231073` is mapped as UID `1`, and so forth. If a process attempts to escalate privilege outside of the namespace, the process is running as an unprivileged high-number UID on the host, which does not even map to a real user. This means the process has no privileges on the host system at all.

> Note
>
> It is possible to assign multiple subordinate ranges for a given user or group by adding multiple non-overlapping mappings for the same user or group in the `/etc/subuid` or `/etc/subgid` file. In this case, Docker uses only the first five mappings, in accordance with the kernel's limitation of only five entries in `/proc/self/uid_map` and `/proc/self/gid_map`.

When you configure Docker to use the `userns-remap` feature, you can optionally specify an existing user and/or group, or you can specify `default`. If you specify `default`, a user and group `dockremap` is created and used for this purpose.

> Warning
>
> Some distributions do not automatically add the new group to the `/etc/subuid` and `/etc/subgid` files. If that's the case, you may have to manually edit these files and assign non-overlapping ranges. This step is covered in [Prerequisites](#prerequisites).

It is very important that the ranges do not overlap, so that a process cannot gain access in a different namespace. On most Linux distributions, system utilities manage the ranges for you when you add or remove users.

This re-mapping is transparent to the container, but introduces some configuration complexity in situations where the container needs access to resources on the Docker host, such as bind mounts into areas of the filesystem that the system user cannot write to. From a security standpoint, it is best to avoid these situations.

## [Prerequisites](#prerequisites)

1. The subordinate UID and GID ranges must be associated with an existing user, even though the association is an implementation detail. The user owns the namespaced storage directories under `/var/lib/docker/`. If you don't want to use an existing user, Docker can create one for you and use that. If you want to use an existing username or user ID, it must already exist. Typically, this means that the relevant entries need to be in `/etc/passwd` and `/etc/group`, but if you are using a different authentication back-end, this requirement may translate differently.

   To verify this, use the `id` command:

   ```console
   $ id testuser

   uid=1001(testuser) gid=1001(testuser) groups=1001(testuser)
   ```

2. The way the namespace remapping is handled on the host is using two files, `/etc/subuid` and `/etc/subgid`. These files are typically managed automatically when you add or remove users or groups, but on some distributions, you may need to manage these files manually.

   Each file contains three fields: the username or ID of the user, followed by a beginning UID or GID (which is treated as UID or GID 0 within the namespace) and a maximum number of UIDs or GIDs available to the user. For instance, given the following entry:

   ```text
   testuser:231072:65536
   ```

   This means that user-namespaced processes started by `testuser` are owned by host UID `231072` (which looks like UID `0` inside the namespace) through 296607 (231072 + 65536 - 1). These ranges should not overlap, to ensure that namespaced processes cannot access each other's namespaces.

   After adding your user, check `/etc/subuid` and `/etc/subgid` to see if your user has an entry in each. If not, you need to add it, being careful to avoid overlap.

   If you want to use the `dockremap` user automatically created by Docker, check for the `dockremap` entry in these files after configuring and restarting Docker.

3. If there are any locations on the Docker host where the unprivileged user needs to write, adjust the permissions of those locations accordingly. This is also true if you want to use the `dockremap` user automatically created by Docker, but you can't modify the permissions until after configuring and restarting Docker.

4. Enabling `userns-remap` effectively masks existing image and container layers, as well as other Docker objects within `/var/lib/docker/`. This is because Docker needs to adjust the ownership of these resources and actually stores them in a subdirectory within `/var/lib/docker/`. It is best to enable this feature on a new Docker installation rather than an existing one.

   Along the same lines, if you disable `userns-remap` you can't access any of the resources created while it was enabled.

5. Check the [limitations](#user-namespace-known-limitations) on user namespaces to be sure your use case is possible.

## [Enable userns-remap on the daemon](#enable-userns-remap-on-the-daemon)

You can start `dockerd` with the `--userns-remap` flag or follow this procedure to configure the daemon using the `daemon.json` configuration file. The `daemon.json` method is recommended. If you use the flag, use the following command as a model:

```console
$ dockerd --userns-remap="testuser:testuser"
```

1. Edit `/etc/docker/daemon.json`. Assuming the file was previously empty, the following entry enables `userns-remap` using user and group called `testuser`. You can address the user and group by ID or name. You only need to specify the group name or ID if it is different from the user name or ID. If you provide both the user and group name or ID, separate them by a colon (`:`) character. The following formats all work for the value, assuming the UID and GID of `testuser` are `1001`:

   * `testuser`
   * `testuser:testuser`
   * `1001`
   * `1001:1001`
   * `testuser:1001`
   * `1001:testuser`

   ```json
   {
     "userns-remap": "testuser"
   }
   ```

   > Note
   >
   > To use the `dockremap` user and have Docker create it for you, set the value to `default` rather than `testuser`.

   Save the file and restart Docker.

2. If you are using the `dockremap` user, verify that Docker created it using the `id` command.

   ```console
   $ id dockremap

   uid=112(dockremap) gid=116(dockremap) groups=116(dockremap)
   ```

   Verify that the entry has been added to `/etc/subuid` and `/etc/subgid`:

   ```console
   $ grep dockremap /etc/subuid

   dockremap:231072:65536

   $ grep dockremap /etc/subgid

   dockremap:231072:65536
   ```

   If these entries are not present, edit the files as the `root` user and assign a starting UID and GID that is the highest-assigned one plus the offset (in this case, `65536`). Be careful not to allow any overlap in the ranges.

3. Verify that previous images are not available using the `docker image ls` command. The output should be empty.

4. Start a container from the `hello-world` image.

   ```console
   $ docker run hello-world
   ```

5. Verify that a namespaced directory exists within `/var/lib/docker/` named with the UID and GID of the namespaced user, owned by that UID and GID, and not group-or-world-readable. Some of the subdirectories are still owned by `root` and have different permissions.

   ```console
   $ sudo ls -ld /var/lib/docker/231072.231072/

   drwx------ 11 231072 231072 11 Jun 21 21:19 /var/lib/docker/231072.231072/

   $ sudo ls -l /var/lib/docker/231072.231072/

   total 14
   drwx------ 5 231072 231072 5 Jun 21 21:19 aufs
   drwx------ 3 231072 231072 3 Jun 21 21:21 containers
   drwx------ 3 root   root   3 Jun 21 21:19 image
   drwxr-x--- 3 root   root   3 Jun 21 21:19 network
   drwx------ 4 root   root   4 Jun 21 21:19 plugins
   drwx------ 2 root   root   2 Jun 21 21:19 swarm
   drwx------ 2 231072 231072 2 Jun 21 21:21 tmp
   drwx------ 2 root   root   2 Jun 21 21:19 trust
   drwx------ 2 231072 231072 3 Jun 21 21:19 volumes
   ```

   Your directory listing may have some differences, especially if you use a different container storage driver than `aufs`.

   The directories which are owned by the remapped user are used instead of the same directories directly beneath `/var/lib/docker/` and the unused versions (such as `/var/lib/docker/tmp/` in the example here) can be removed. Docker does not use them while `userns-remap` is enabled.

## [Disable namespace remapping for a container](#disable-namespace-remapping-for-a-container)

If you enable user namespaces on the daemon, all containers are started with user namespaces enabled by default. In some situations, such as privileged containers, you may need to disable user namespaces for a specific container. See [user namespace known limitations](#user-namespace-known-limitations) for some of these limitations.

To disable user namespaces for a specific container, add the `--userns=host` flag to the `docker container create`, `docker container run`, or `docker container exec` command.

There is a side effect when using this flag: user remapping will not be enabled for that container but, because the read-only (image) layers are shared between containers, ownership of the containers filesystem will still be remapped.

What this means is that the whole container filesystem will belong to the user specified in the `--userns-remap` daemon config (`231072` in the example above). This can lead to unexpected behavior of programs inside the container. For instance `sudo` (which checks that its binaries belong to user `0`) or binaries with a `setuid` flag.

## [User namespace known limitations](#user-namespace-known-limitations)

The following standard Docker features are incompatible with running a Docker daemon with user namespaces enabled:

* Sharing PID or NET namespaces with the host (`--pid=host` or `--network=host`).
* External (volume or storage) drivers which are unaware or incapable of using daemon user mappings.
* Using the `--privileged` mode flag on `docker run` without also specifying `--userns=host`.

User namespaces are an advanced feature and require coordination with other capabilities. For example, if volumes are mounted from the host, file ownership must be pre-arranged if you need read or write access to the volume contents.

While the root user inside a user-namespaced container process has many of the expected privileges of the superuser within the container, the Linux kernel imposes restrictions based on internal knowledge that this is a user-namespaced process. One notable restriction is the inability to use the `mknod` command. Permission is denied for device creation within the container when run by the `root` user.

----
url: https://docs.docker.com/reference/samples/django/
----

# Django samples

| Name                                                                                                               | Description                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| [Django](https://github.com/docker/awesome-compose/tree/master/django)                                             | A sample Django application.                                                                                    |
| [Compose and Django](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/django/) | This quick-start guide demonstrates how to use Docker Compose to set up and run a simple Django/PostgreSQL app. |

----
url: https://docs.docker.com/guides/docker-build-cloud/ci/
----

# Demo: Using Docker Build Cloud in CI

***

***

Docker Build Cloud can significantly decrease the time it takes for your CI builds take to run, saving you time and money.

Since the builds run remotely, your CI runner can still use the Docker tooling CLI without needing elevated permissions, making your builds more secure by default.

In this demo, you will see:

* How to integrate Docker Build Cloud into a variety of CI platforms
* How to use Docker Build Cloud in GitHub Actions to build multi-architecture images
* Speed differences between a workflow using Docker Build Cloud and a workflow running natively
* How to use Docker Build Cloud in a GitLab Pipeline

[Common challenges and questions »](https://docs.docker.com/guides/docker-build-cloud/common-questions/)

----
url: https://docs.docker.com/extensions/extensions-sdk/dev/continuous-integration/
----

# Continuous Integration (CI)

***

Table of contents

***

In order to help validate your extension and ensure it's functional, the Extension SDK provides tools to help you setup continuous integration for your extension.

> Important
>
> The [Docker Desktop Action](https://github.com/docker/desktop-action) and the [extension-test-helper library](https://www.npmjs.com/package/@docker/extension-test-helper) are both [experimental](https://docs.docker.com/release-lifecycle/#experimental).

## [Setup CI environment with GitHub Actions](#setup-ci-environment-with-github-actions)

You need Docker Desktop to be able to install and validate your extension. You can start Docker Desktop in GitHub Actions using the [Docker Desktop Action](https://github.com/docker/desktop-action), by adding the following to a workflow file:

```yaml
steps:
  - id: start_desktop
    uses: docker/desktop-action/start@v0.1.0
```

> Note
>
> This action supports only GitHub Actions macOS runners at the moment. You need to specify `runs-on: macOS-latest` for your end to end tests.

Once the step has executed, the next steps use Docker Desktop and the Docker CLI to install and test the extension.

## [Validating your extension with Puppeteer](#validating-your-extension-with-puppeteer)

Once Docker Desktop starts in CI, you can build, install, and validate your extension with Jest and Puppeteer.

First, build and install the extension from your test:

```ts
import { DesktopUI } from "@docker/extension-test-helper";
import { exec as originalExec } from "child_process";
import * as util from "util";

export const exec = util.promisify(originalExec);

// keep a handle on the app to stop it at the end of tests
let dashboard: DesktopUI;

beforeAll(async () => {
  await exec(`docker build -t my/extension:latest .`, {
    cwd: "my-extension-src-root",
  });

  await exec(`docker extension install -f my/extension:latest`);
});
```

Then open the Docker Desktop Dashboard and run some tests in your extension's UI:

```ts
describe("Test my extension", () => {
  test("should be functional", async () => {
    dashboard = await DesktopUI.start();

    const eFrame = await dashboard.navigateToExtension("my/extension");

    // use puppeteer APIs to manipulate the UI, click on buttons, expect visual display and validate your extension
    await eFrame.waitForSelector("#someElementId");
  });
});
```

Finally, close the Docker Desktop Dashboard and uninstall your extension:

```ts
afterAll(async () => {
  dashboard?.stop();
  await exec(`docker extension uninstall my/extension`);
});
```

## [What's next](#whats-next)

* Build an [advanced frontend](https://docs.docker.com/extensions/extensions-sdk/build/frontend-extension-tutorial/) extension.
* Learn more about extensions [architecture](https://docs.docker.com/extensions/extensions-sdk/architecture/).

----
url: https://docs.docker.com/engine/extend/config/
----

# Plugin Config Version 1 of Plugin V2

***

Table of contents

***

This document outlines the format of the V0 plugin configuration.

Plugin configs describe the various constituents of a Docker engine plugin. Plugin configs can be serialized to JSON format with the following media types:

| Config Type | Media Type                              |
| ----------- | --------------------------------------- |
| config      | `application/vnd.docker.plugin.v1+json` |

## [Config Field Descriptions](#config-field-descriptions)

Config provides the base accessible fields for working with V0 plugin format in the registry.

* `description` string

  Description of the plugin

* `documentation` string

  Link to the documentation about the plugin

* `interface` PluginInterface

  Interface implemented by the plugins, struct consisting of the following fields:

  * `types` string array

    Types indicate what interface(s) the plugin currently implements.

    Supported types:

    * `docker.volumedriver/1.0`

    * `docker.networkdriver/1.0`

    * `docker.ipamdriver/1.0`

    * `docker.authz/1.0`

    * `docker.logdriver/1.0`

    * `docker.metricscollector/1.0`

  * `socket` string

    Socket is the name of the socket the engine should use to communicate with the plugins. the socket will be created in `/run/docker/plugins`.

* `entrypoint` string array

  Entrypoint of the plugin, see [`ENTRYPOINT`](https://docs.docker.com/reference/dockerfile/#entrypoint)

* `workdir` string

  Working directory of the plugin, see [`WORKDIR`](https://docs.docker.com/reference/dockerfile/#workdir)

* `network` PluginNetwork

  Network of the plugin, struct consisting of the following fields:

  * `type` string

    Network type.

    Supported types:

    * `bridge`
    * `host`
    * `none`

* `mounts` PluginMount array

  Mount of the plugin, struct consisting of the following fields. See [`MOUNTS`](https://github.com/opencontainers/runtime-spec/blob/master/config.md#mounts).

  * `name` string

    Name of the mount.

  * `description` string

    Description of the mount.

  * `source` string

    Source of the mount.

  * `destination` string

    Destination of the mount.

  * `type` string

    Mount type.

  * `options` string array

    Options of the mount.

* `ipchost` Boolean

  Access to host ipc namespace.

* `pidhost` Boolean

  Access to host PID namespace.

* `propagatedMount` string

  Path to be mounted as rshared, so that mounts under that path are visible to Docker. This is useful for volume plugins. This path will be bind-mounted outside of the plugin rootfs so it's contents are preserved on upgrade.

* `env` PluginEnv array

  Environment variables of the plugin, struct consisting of the following fields:

  * `name` string

    Name of the environment variable.

  * `description` string

    Description of the environment variable.

  * `value` string

    Value of the environment variable.

* `args` PluginArgs

  Arguments of the plugin, struct consisting of the following fields:

  * `name` string

    Name of the arguments.

  * `description` string

    Description of the arguments.

  * `value` string array

    Values of the arguments.

* `linux` PluginLinux

  * `capabilities` string array

    Capabilities of the plugin (Linux only), see list [`here`](https://github.com/opencontainers/runc/blob/master/libcontainer/SPEC.md#security)

  * `allowAllDevices` Boolean

    If `/dev` is bind mounted from the host, and allowAllDevices is set to true, the plugin will have `rwm` access to all devices on the host.

  * `devices` PluginDevice array

    Device of the plugin, (Linux only), struct consisting of the following fields. See [`DEVICES`](https://github.com/opencontainers/runtime-spec/blob/master/config-linux.md#devices).

    * `name` string

      Name of the device.

    * `description` string

      Description of the device.

    * `path` string

      Path of the device.

## [Example Config](#example-config)

The following example shows the 'tiborvass/sample-volume-plugin' plugin config.

```json
{
  "Args": {
    "Description": "",
    "Name": "",
    "Settable": null,
    "Value": null
  },
  "Description": "A sample volume plugin for Docker",
  "Documentation": "https://docs.docker.com/engine/extend/plugins/",
  "Entrypoint": [
    "/usr/bin/sample-volume-plugin",
    "/data"
  ],
  "Env": [
    {
      "Description": "",
      "Name": "DEBUG",
      "Settable": [
        "value"
      ],
      "Value": "0"
    }
  ],
  "Interface": {
    "Socket": "plugin.sock",
    "Types": [
      "docker.volumedriver/1.0"
    ]
  },
  "Linux": {
    "Capabilities": null,
    "AllowAllDevices": false,
    "Devices": null
  },
  "Mounts": null,
  "Network": {
    "Type": ""
  },
  "PropagatedMount": "/data",
  "User": {},
  "Workdir": ""
}
```

----
url: https://docs.docker.com/extensions/extensions-sdk/guides/use-docker-socket-from-backend/
----

# Use the Docker socket from the extension backend

***

***

Extensions can invoke Docker commands directly from the frontend with the SDK.

In some cases, it is useful to also interact with Docker Engine from the backend.

Extension backend containers can mount the Docker socket and use it to interact with Docker Engine from the extension backend logic. Learn more about the [Docker Engine socket](/reference/cli/dockerd/#examples)

However, when mounting the Docker socket from an extension container that lives in the Desktop virtual machine, you want to mount the Docker socket from inside the VM, and not mount `/var/run/docker.sock` from the host filesystem (using the Docker socket from the host can lead to permission issues in containers).

In order to do so, you can use `/var/run/docker.sock.raw`. Docker Desktop mounts the socket that lives in the Desktop VM, and not from the host.

```yaml
services:
  myExtension:
    image: ${DESKTOP_PLUGIN_IMAGE}
    volumes:
      - /var/run/docker.sock.raw:/var/run/docker.sock
```

----
url: https://docs.docker.com/reference/build-checks/maintainer-deprecated/
----

# MaintainerDeprecated

***

Table of contents

***

## [Output](#output)

```text
MAINTAINER instruction is deprecated in favor of using label
```

## [Description](#description)

The `MAINTAINER` instruction, used historically for specifying the author of the Dockerfile, is deprecated. To set author metadata for an image, use the `org.opencontainers.image.authors` [OCI label](https://github.com/opencontainers/image-spec/blob/main/annotations.md#pre-defined-annotation-keys).

## [Examples](#examples)

❌ Bad: don't use the `MAINTAINER` instruction

```dockerfile
MAINTAINER moby@example.com
```

✅ Good: specify the author using the `org.opencontainers.image.authors` label

```dockerfile
LABEL org.opencontainers.image.authors="moby@example.com"
```

----
url: https://docs.docker.com/ai/sandboxes/security/governance/
----

# Organization governance

***

Table of contents

***

This page covers how to configure organization policies in the Docker Admin Console under AI governance settings. For local sandbox policies that individual users configure on their own machine, see [Policies](https://docs.docker.com/ai/sandboxes/security/policy/).

Sandbox network and filesystem policies defined in the [Docker Admin Console](https://app.docker.com/admin) apply uniformly to every sandbox in the organization. Rules are enforced across all developers' machines, take precedence over local `sbx policy` rules, and can't be overridden by individual users. Admins can optionally [delegate](#delegate-rules-to-local-policy) specific rule types back to local control so developers can add additional allow rules.

> Note
>
> Sandbox organization governance is available on a separate paid subscription. [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) to request access.

## [Network policies](#network-policies)

### [Configuring org-level network rules](#configuring-org-level-network-rules)

Define network allow and deny rules in the Admin Console under **AI governance > Network access**. Each rule takes a network target (domain, wildcard, or CIDR range) and an action (allow or deny). You can add multiple entries at once, one per line.

Rules support exact domains (`example.com`), wildcard subdomains (`*.example.com`), and optional port suffixes (`example.com:443`).

`example.com` doesn't match subdomains, and `*.example.com` doesn't match the root domain. Specify both to cover both.

### [Delegate rules to local policy](#delegate-rules-to-local-policy)

When organization governance is active, local rules are ignored by default — only the organization policy is in effect. Admins can delegate a rule type back to local policy by turning on the **User defined** setting for that rule type in AI governance settings. Turning the setting on delegates the rule type: local `sbx policy` rules of that type are evaluated alongside organization rules, letting users add hosts to the allowlist from their own machine.

If a rule type isn't delegated, local rules of that type still appear in `sbx policy ls` but with an `inactive` status and a note that the organization hasn't delegated the rule type to local policy:

```console
$ sbx policy ls
NAME                  TYPE      ORIGIN               DECISION   STATUS                                                  RESOURCES
balanced-dev          network   local                allow      inactive — corporate policy takes precedence and does   api.anthropic.com
                                                                not delegate this rule type to local policy.
allow AI services     network   remote               allow      active                                                  api.anthropic.com
                                                                                                                        api.openai.com
allow Docker services network   remote               allow      active                                                  *.docker.com
                                                                                                                        *.docker.io
```

Organization rules show up with `remote` in the `ORIGIN` column.

Delegated local rules can expand access for domains the organization hasn't explicitly denied, but can't override organization-level deny rules. This applies to exact matches and wildcard matches alike; if the organization denies `*.example.com`, a local allow for `api.example.com` has no effect because the org-level wildcard deny covers it.

For example, given an organization policy that allows `api.anthropic.com` and denies `*.corp.internal`:

* `sbx policy allow network -g api.example.com` — works, because the organization hasn't denied `api.example.com`
* `sbx policy allow network -g build.corp.internal` — no effect, because the organization denies `*.corp.internal`

#### [Blocked values in delegated rules](#blocked-values-in-delegated-rules)

To prevent overly broad rules from undermining the organization's policy, certain catch-all values are blocked in delegated local rules:

* Domain patterns: `*`, `**`, `*.com`, `**.com`, `*.*`, `**.**`
* CIDR ranges: `0.0.0.0/0`, `::/0`

Scoped wildcards like `*.example.com` are still allowed. If a user attempts to use a blocked value, `sbx policy` returns an error immediately.

## [Filesystem policies](#filesystem-policies)

Filesystem policies control which host paths a sandbox can mount as workspaces. By default, sandboxes can mount any directory the user has access to.

Admins can restrict which paths are mountable by defining filesystem allow and deny rules in the Admin Console under **AI governance > Filesystem access**. Each rule takes a path pattern and an action (allow or deny).

> Caution
>
> Use `**` (double wildcard) rather than `*` (single wildcard) when writing path patterns to match path segments recursively. A single `*` only matches within a single path segment. For example, `~/**` matches all paths under the user's home directory, whereas `~/*` matches only paths directly under `~`.

## [Precedence](#precedence)

Within any layer, deny rules beat allow rules. If a domain matches both, it's blocked regardless of specificity. Outbound traffic is blocked unless a rule allows it.

When organization governance is active, local rules are not evaluated. Only organization rules set in the Admin Console determine what is allowed or denied. Organization-level denials can't be overridden locally.

If the admin [delegates](#delegate-rules-to-local-policy) a rule type to local policy by turning on the **User defined** setting, local rules of that type are also evaluated alongside organization rules. Delegated local rules can expand access for domains the organization hasn't explicitly denied, but can't override organization-level denials.

The same model applies to filesystem policies: organization-level rules take precedence over local behavior.

To unblock a domain, identify where the deny rule comes from. For local rules, remove it with `sbx policy rm`. For organization-level rules, update the rule in the Admin Console.

## [Troubleshooting](#troubleshooting)

### [Policy changes not taking effect](#policy-changes-not-taking-effect)

After updating organization policies in the Admin Console, changes take up to 5 minutes to propagate to developer machines. To apply changes immediately, users can run `sbx policy reset`, which stops the daemon and forces it to pull the latest organization policies on the next `sbx` command.

> Warning
>
> `sbx policy reset` deletes all locally configured policy rules. The command prompts for confirmation before proceeding.

### [Sandbox cannot mount workspace](#sandbox-cannot-mount-workspace)

If a sandbox fails to mount with a `mount policy denied` error, verify that the filesystem allow rule in the Admin Console uses `**` rather than `*`. A single `*` doesn't match across directory separators.

----
url: https://docs.docker.com/ai/docker-agent/sharing-agents/
----

# Sharing agents

***

Table of contents

***

Push your agent to a registry and share it by name. Your teammates reference `agentcatalog/security-expert` instead of copying YAML files around or asking you where your agent configuration lives.

When you update the agent in the registry, everyone gets the new version the next time they pull or restart their client.

## [Prerequisites](#prerequisites)

To push agents to a registry, authenticate first:

```console
$ docker login
```

For other registries, use their authentication method.

## [Publishing agents](#publishing-agents)

Push your agent configuration to a registry:

```console
$ docker agent share push ./agent.yml myusername/agent-name
```

Push creates the repository if it doesn't exist yet. Use Docker Hub or any OCI-compatible registry.

Tag specific versions:

```console
$ docker agent share push ./agent.yml myusername/agent-name:v1.0.0
$ docker agent share push ./agent.yml myusername/agent-name:latest
```

## [Using published agents](#using-published-agents)

Pull an agent to inspect it locally:

```console
$ docker agent share pull agentcatalog/pirate
```

This saves the configuration as a local YAML file.

Run agents directly from the registry:

```console
$ docker agent run agentcatalog/pirate
```

Or reference it directly in integrations:

### [Editor integration (ACP)](#editor-integration-acp)

Use registry references in ACP configurations so your editor always uses the latest version:

```json
{
  "agent_servers": {
    "myagent": {
      "command": "docker",
      "args": ["agent", "aserve", "acp", "agentcatalog/pirate"]
    }
  }
}
```

### [MCP client integration](#mcp-client-integration)

Agents can be exposed as tools in MCP clients:

```json
{
  "mcpServers": {
    "myagent": {
      "command": "docker",
      "args": ["agent", "serve", "mcp", "agentcatalog/pirate"]
    }
  }
}
```

## [What's next](#whats-next)

* Set up [ACP integration](https://docs.docker.com/ai/docker-agent/integrations/acp/) with shared agents
* Configure [MCP integration](https://docs.docker.com/ai/docker-agent/integrations/mcp/) with shared agents
* Browse the [agent catalog](https://hub.docker.com/u/agentcatalog) for examples

----
url: https://docs.docker.com/engine/swarm/networking/
----

# Manage swarm service networks

***

Table of contents

***

This page describes networking for swarm services.

## [Swarm and types of traffic](#swarm-and-types-of-traffic)

A Docker swarm generates two different kinds of traffic:

* Control and management plane traffic: This includes swarm management messages, such as requests to join or leave the swarm. This traffic is always encrypted.

* Application data plane traffic: This includes container traffic and traffic to and from external clients.

## [Key network concepts](#key-network-concepts)

The following three network concepts are important to swarm services:

* Overlay networks manage communications among the Docker daemons participating in the swarm. You can create overlay networks, in the same way as user-defined networks for standalone containers. You can attach a service to one or more existing overlay networks as well, to enable service-to-service communication. Overlay networks are Docker networks that use the `overlay` network driver.

* The ingress network is a special overlay network that facilitates load balancing among a service's nodes. When any swarm node receives a request on a published port, it hands that request off to a module called `IPVS`. `IPVS` keeps track of all the IP addresses participating in that service, selects one of them, and routes the request to it, over the `ingress` network.

  The `ingress` network is created automatically when you initialize or join a swarm. Most users do not need to customize its configuration, but Docker allows you to do so.

* The docker\_gwbridge is a bridge network that connects the overlay networks (including the `ingress` network) to an individual Docker daemon's physical network. By default, each container a service is running is connected to its local Docker daemon host's `docker_gwbridge` network.

  The `docker_gwbridge` network is created automatically when you initialize or join a swarm. Most users do not need to customize its configuration, but Docker allows you to do so.

> Tip
>
> See also [Networking overview](https://docs.docker.com/engine/network/) for more details about Swarm networking in general.

## [Firewall considerations](#firewall-considerations)

Docker daemons participating in a swarm need the ability to communicate with each other over the following ports:

* Port `7946` TCP/UDP for container network discovery.
* Port `4789` UDP (configurable) for the overlay network (including ingress) data path.

When setting up networking in a Swarm, special care should be taken. Consult the [tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/#open-protocols-and-ports-between-the-hosts) for an overview.

## [Overlay networking](#overlay-networking)

When you initialize a swarm or join a Docker host to an existing swarm, two new networks are created on that Docker host:

* An overlay network called `ingress`, which handles the control and data traffic related to swarm services. When you create a swarm service and do not connect it to a user-defined overlay network, it connects to the `ingress` network by default.
* A bridge network called `docker_gwbridge`, which connects the individual Docker daemon to the other daemons participating in the swarm.

### [Create an overlay network](#create-an-overlay-network)

To create an overlay network, specify the `overlay` driver when using the `docker network create` command:

```console
$ docker network create \
  --driver overlay \
  my-network
```

The above command doesn't specify any custom options, so Docker assigns a subnet and uses default options. You can see information about the network using `docker network inspect`.

When no containers are connected to the overlay network, its configuration is not very exciting:

```console
$ docker network inspect my-network
[
    {
        "Name": "my-network",
        "Id": "fsf1dmx3i9q75an49z36jycxd",
        "Created": "0001-01-01T00:00:00Z",
        "Scope": "swarm",
        "Driver": "overlay",
        "EnableIPv6": false,
        "IPAM": {
            "Driver": "default",
            "Options": null,
            "Config": []
        },
        "Internal": false,
        "Attachable": false,
        "Ingress": false,
        "Containers": null,
        "Options": {
            "com.docker.network.driver.overlay.vxlanid_list": "4097"
        },
        "Labels": null
    }
]
```

In the above output, notice that the driver is `overlay` and that the scope is `swarm`, rather than `local`, `host`, or `global` scopes you might see in other types of Docker networks. This scope indicates that only hosts which are participating in the swarm can access this network.

The network's subnet and gateway are dynamically configured when a service connects to the network for the first time. The following example shows the same network as above, but with three containers of a `redis` service connected to it.

```console
$ docker network inspect my-network
[
    {
        "Name": "my-network",
        "Id": "fsf1dmx3i9q75an49z36jycxd",
        "Created": "2017-05-31T18:35:58.877628262Z",
        "Scope": "swarm",
        "Driver": "overlay",
        "EnableIPv6": false,
        "IPAM": {
            "Driver": "default",
            "Options": null,
            "Config": [
                {
                    "Subnet": "10.0.0.0/24",
                    "Gateway": "10.0.0.1"
                }
            ]
        },
        "Internal": false,
        "Attachable": false,
        "Ingress": false,
        "Containers": {
            "0e08442918814c2275c31321f877a47569ba3447498db10e25d234e47773756d": {
                "Name": "my-redis.1.ka6oo5cfmxbe6mq8qat2djgyj",
                "EndpointID": "950ce63a3ace13fe7ef40724afbdb297a50642b6d47f83a5ca8636d44039e1dd",
                "MacAddress": "02:42:0a:00:00:03",
                "IPv4Address": "10.0.0.3/24",
                "IPv6Address": ""
            },
            "88d55505c2a02632c1e0e42930bcde7e2fa6e3cce074507908dc4b827016b833": {
                "Name": "my-redis.2.s7vlybipal9xlmjfqnt6qwz5e",
                "EndpointID": "dd822cb68bcd4ae172e29c321ced70b731b9994eee5a4ad1d807d9ae80ecc365",
                "MacAddress": "02:42:0a:00:00:05",
                "IPv4Address": "10.0.0.5/24",
                "IPv6Address": ""
            },
            "9ed165407384f1276e5cfb0e065e7914adbf2658794fd861cfb9b991eddca754": {
                "Name": "my-redis.3.hbz3uk3hi5gb61xhxol27hl7d",
                "EndpointID": "f62c686a34c9f4d70a47b869576c37dffe5200732e1dd6609b488581634cf5d2",
                "MacAddress": "02:42:0a:00:00:04",
                "IPv4Address": "10.0.0.4/24",
                "IPv6Address": ""
            }
        },
        "Options": {
            "com.docker.network.driver.overlay.vxlanid_list": "4097"
        },
        "Labels": {},
        "Peers": [
            {
                "Name": "moby-e57c567e25e2",
                "IP": "192.168.65.2"
            }
        ]
    }
]
```

### [Customize an overlay network](#customize-an-overlay-network)

There may be situations where you don't want to use the default configuration for an overlay network. For a full list of configurable options, run the command `docker network create --help`. The following are some of the most common options to change.

#### [Configure the subnet and gateway](#configure-the-subnet-and-gateway)

By default, the network's subnet and gateway are configured automatically when the first service is connected to the network. You can configure these when creating a network using the `--subnet` and `--gateway` flags. The following example extends the previous one by configuring the subnet and gateway.

```console
$ docker network create \
  --driver overlay \
  --subnet 10.0.9.0/24 \
  --gateway 10.0.9.99 \
  my-network
```

##### [Using custom default address pools](#using-custom-default-address-pools)

To customize subnet allocation for your Swarm networks, you can [optionally configure them](https://docs.docker.com/engine/swarm/swarm-mode/) during `swarm init`.

For example, the following command is used when initializing Swarm:

```console
$ docker swarm init --default-addr-pool 10.20.0.0/16 --default-addr-pool-mask-length 26
```

Whenever a user creates a network, but does not use the `--subnet` command line option, the subnet for this network will be allocated sequentially from the next available subnet from the pool. If the specified network is already allocated, that network will not be used for Swarm.

Multiple pools can be configured if discontiguous address space is required. However, allocation from specific pools is not supported. Network subnets will be allocated sequentially from the IP pool space and subnets will be reused as they are deallocated from networks that are deleted.

The default mask length can be configured and is the same for all networks. It is set to `/24` by default. To change the default subnet mask length, use the `--default-addr-pool-mask-length` command line option.

> Note
>
> Default address pools can only be configured on `swarm init` and cannot be altered after cluster creation.

##### [Overlay network size limitations](#overlay-network-size-limitations)

Docker recommends creating overlay networks with `/24` blocks. The `/24` overlay network blocks limit the network to 256 IP addresses.

This recommendation addresses [limitations with swarm mode](https://github.com/moby/moby/issues/30820). If you need more than 256 IP addresses, do not increase the IP block size. You can either use `dnsrr` endpoint mode with an external load balancer, or use multiple smaller overlay networks. See [Configure service discovery](#configure-service-discovery) for more information about different endpoint modes.

#### [Configure encryption of application data](#encryption)

Management and control plane data related to a swarm is always encrypted. For more details about the encryption mechanisms, see the [Docker swarm mode overlay network security model](https://docs.docker.com/engine/network/drivers/overlay/).

Application data among swarm nodes is not encrypted by default. To encrypt this traffic on a given overlay network, use the `--opt encrypted` flag on `docker network create`. This enables IPSEC encryption at the level of the vxlan. This encryption imposes a non-negligible performance penalty, so you should test this option before using it in production.

> Note
>
> You must [customize the automatically created ingress](#customize-ingress) to enable encryption. By default, all ingress traffic is unencrypted, as encryption is a network-level option.

## [Attach a service to an overlay network](#attach-a-service-to-an-overlay-network)

To attach a service to an existing overlay network, pass the `--network` flag to `docker service create`, or the `--network-add` flag to `docker service update`.

```console
$ docker service create \
  --replicas 3 \
  --name my-web \
  --network my-network \
  nginx
```

Service containers connected to an overlay network can communicate with each other across it.

To see which networks a service is connected to, use `docker service ls` to find the name of the service, then `docker service ps <service-name>` to list the networks. Alternately, to see which services' containers are connected to a network, use `docker network inspect <network-name>`. You can run these commands from any swarm node which is joined to the swarm and is in a `running` state.

### [Configure service discovery](#configure-service-discovery)

Service discovery is the mechanism Docker uses to route a request from your service's external clients to an individual swarm node, without the client needing to know how many nodes are participating in the service or their IP addresses or ports. You don't need to publish ports which are used between services on the same network. For instance, if you have a WordPress service that stores its data in a MySQL service, and they are connected to the same overlay network, you do not need to publish the MySQL port to the client, only the WordPress HTTP port.

Service discovery can work in two different ways: internal connection-based load-balancing at Layers 3 and 4 using the embedded DNS and a virtual IP (VIP), or external and customized request-based load-balancing at Layer 7 using DNS round robin (DNSRR). You can configure this per service.

* By default, when you attach a service to a network and that service publishes one or more ports, Docker assigns the service a virtual IP (VIP), which is the "front end" for clients to reach the service. Docker keeps a list of all worker nodes in the service, and routes requests between the client and one of the nodes. Each request from the client might be routed to a different node.

* If you configure a service to use DNS round-robin (DNSRR) service discovery, there is not a single virtual IP. Instead, Docker sets up DNS entries for the service such that a DNS query for the service name returns a list of IP addresses, and the client connects directly to one of these.

  DNS round-robin is useful in cases where you want to use your own load balancer, such as HAProxy. To configure a service to use DNSRR, use the flag `--endpoint-mode dnsrr` when creating a new service or updating an existing one.

## [Customize the ingress network](#customize-ingress)

Most users never need to configure the `ingress` network, but Docker allows you to do so. This can be useful if the automatically-chosen subnet conflicts with one that already exists on your network, or you need to customize other low-level network settings such as the MTU, or if you want to [enable encryption](#encryption).

Customizing the `ingress` network involves removing and recreating it. This is usually done before you create any services in the swarm. If you have existing services which publish ports, those services need to be removed before you can remove the `ingress` network.

During the time that no `ingress` network exists, existing services which do not publish ports continue to function but are not load-balanced. This affects services which publish ports, such as a WordPress service which publishes port 80.

1. Inspect the `ingress` network using `docker network inspect ingress`, and remove any services whose containers are connected to it. These are services that publish ports, such as a WordPress service which publishes port 80. If all such services are not stopped, the next step fails.

2. Remove the existing `ingress` network:

   ```console
   $ docker network rm ingress

   WARNING! Before removing the routing-mesh network, make sure all the nodes
   in your swarm run the same docker engine version. Otherwise, removal may not
   be effective and functionality of newly created ingress networks will be
   impaired.
   Are you sure you want to continue? [y/N]
   ```

3. Create a new overlay network using the `--ingress` flag, along with the custom options you want to set. This example sets the MTU to 1200, sets the subnet to `10.11.0.0/16`, and sets the gateway to `10.11.0.2`.

   ```console
   $ docker network create \
     --driver overlay \
     --ingress \
     --subnet=10.11.0.0/16 \
     --gateway=10.11.0.2 \
     --opt com.docker.network.driver.mtu=1200 \
     my-ingress
   ```

   > Note
   >
   > You can name your `ingress` network something other than `ingress`, but you can only have one. An attempt to create a second one fails.

4. Restart the services that you stopped in the first step.

## [Customize the docker\_gwbridge](#customize-the-docker_gwbridge)

The `docker_gwbridge` is a virtual bridge that connects the overlay networks (including the `ingress` network) to an individual Docker daemon's physical network. Docker creates it automatically when you initialize a swarm or join a Docker host to a swarm, but it is not a Docker device. It exists in the kernel of the Docker host. If you need to customize its settings, you must do so before joining the Docker host to the swarm, or after temporarily removing the host from the swarm.

You need to have the `brctl` application installed on your operating system in order to delete an existing bridge. The package name is `bridge-utils`.

1. Stop Docker.

2. Use the `brctl show docker_gwbridge` command to check whether a bridge device exists called `docker_gwbridge`. If so, remove it using `brctl delbr docker_gwbridge`.

3. Start Docker. Do not join or initialize the swarm.

4. Create or re-create the `docker_gwbridge` bridge with your custom settings. This example uses the subnet `10.11.0.0/16`. For a full list of customizable options, see [Bridge driver options](/reference/cli/docker/network/create/#bridge-driver-options).

   ```console
   $ docker network create \
   --subnet 10.11.0.0/16 \
   --opt com.docker.network.bridge.name=docker_gwbridge \
   --opt com.docker.network.bridge.enable_icc=false \
   --opt com.docker.network.bridge.enable_ip_masquerade=true \
   docker_gwbridge
   ```

5. Initialize or join the swarm.

## [Use a separate interface for control and data traffic](#use-a-separate-interface-for-control-and-data-traffic)

By default, all swarm traffic is sent over the same interface, including control and management traffic for maintaining the swarm itself and data traffic to and from the service containers.

You can separate this traffic by passing the `--data-path-addr` flag when initializing or joining the swarm. If there are multiple interfaces, `--advertise-addr` must be specified explicitly, and `--data-path-addr` defaults to `--advertise-addr` if not specified. Traffic about joining, leaving, and managing the swarm is sent over the `--advertise-addr` interface, and traffic among a service's containers is sent over the `--data-path-addr` interface. These flags can take an IP address or a network device name, such as `eth0`.

This example initializes a swarm with a separate `--data-path-addr`. It assumes that your Docker host has two different network interfaces: 10.0.0.1 should be used for control and management traffic and 192.168.0.1 should be used for traffic relating to services.

```console
$ docker swarm init --advertise-addr 10.0.0.1 --data-path-addr 192.168.0.1
```

This example joins the swarm managed by host `192.168.99.100:2377` and sets the `--advertise-addr` flag to `eth0` and the `--data-path-addr` flag to `eth1`.

```console
$ docker swarm join \
  --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2d7c \
  --advertise-addr eth0 \
  --data-path-addr eth1 \
  192.168.99.100:2377
```

## [Publish ports on an overlay network](#publish-ports-on-an-overlay-network)

Swarm services connected to the same overlay network effectively expose all ports to each other. For a port to be accessible outside of the service, that port must be *published* using the `-p` or `--publish` flag on `docker service create` or `docker service update`. Both the legacy colon-separated syntax and the newer comma-separated value syntax are supported. The longer syntax is preferred because it is somewhat self-documenting.

| Flag value                                                                                                             | Description                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p 8080:80` or `-p published=8080,target=80`                                                                          | Map TCP port 80 on the service to port 8080 on the routing mesh.                                                                              |
| `-p 8080:80/udp` or `-p published=8080,target=80,protocol=udp`                                                         | Map UDP port 80 on the service to port 8080 on the routing mesh.                                                                              |
| `-p 8080:80/tcp -p 8080:80/udp` or `-p published=8080,target=80,protocol=tcp -p published=8080,target=80,protocol=udp` | Map TCP port 80 on the service to TCP port 8080 on the routing mesh, and map UDP port 80 on the service to UDP port 8080 on the routing mesh. |

## [Learn more](#learn-more)

* [Deploy services to a swarm](https://docs.docker.com/engine/swarm/services/)
* [Swarm administration guide](https://docs.docker.com/engine/swarm/admin_guide/)
* [Swarm mode tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/)
* [Networking overview](https://docs.docker.com/engine/network/)
* [Docker CLI reference](/reference/cli/docker/)

----
url: https://docs.docker.com/reference/cli/docker/scout/repo/disable/
----

# docker scout repo disable

***

| Description | Disable Docker Scout                     |
| ----------- | ---------------------------------------- |
| Usage       | `docker scout repo disable [REPOSITORY]` |

## [Description](#description)

The docker scout repo disable command disables Docker Scout on repositories.

## [Options](#options)

| Option          | Default | Description                                                                   |
| --------------- | ------- | ----------------------------------------------------------------------------- |
| `--all`         |         | Disable all repositories of the organization. Can not be used with --filter.  |
| `--filter`      |         | Regular expression to filter repositories by name                             |
| `--integration` |         | Name of the integration to use for enabling an image                          |
| `--org`         |         | Namespace of the Docker organization                                          |
| `--registry`    |         | Container Registry                                                            |

## [Examples](#examples)

### [Disable a specific repository](#disable-a-specific-repository)

```console
$ docker scout repo disable my/repository
```

### [Disable all repositories of the organization](#disable-all-repositories-of-the-organization)

```console
$ docker scout repo disable --all
```

### [Disable some repositories based on a filter](#disable-some-repositories-based-on-a-filter)

```console
$ docker scout repo disable --filter namespace/backend
```

### [Disable a repository from a specific registry](#disable-a-repository-from-a-specific-registry)

```console
$ docker scout repo disable my/repository --registry 123456.dkr.ecr.us-east-1.amazonaws.com
```

----
url: https://docs.docker.com/desktop/features/wasm/
----

# Wasm workloads

***

Table of contents

***

Availability: Beta

> Important
>
> Wasm workloads are deprecated and will be removed in a future Docker Desktop release. This feature is no longer actively maintained.

WebAssembly (Wasm) is a fast, light alternative to Linux and Windows containers. With Docker Desktop, you can now run Wasm workloads side by side with traditional containers.

This page provides information about the ability to run Wasm applications alongside your Linux containers in Docker.

> Tip
>
> Learn more about Wasm use cases and tradeoffs in the [Docker Wasm technical preview blog post](https://www.docker.com/blog/docker-wasm-technical-preview/).

## [Turn on Wasm workloads](#turn-on-wasm-workloads)

Wasm workloads require the [containerd image store](https://docs.docker.com/desktop/features/containerd/) feature to be turned on. If you’re not already using the containerd image store, then pre-existing images and containers will be inaccessible.

1. Navigate to **Settings** in Docker Desktop.
2. In the **General** tab, check **Use containerd for pulling and storing images**.
3. Go to **Features in development** and check the **Enable Wasm** option.
4. Select **Apply** to save the settings.
5. In the confirmation dialog, select **Install** to install the Wasm runtimes.

Docker Desktop downloads and installs the following runtimes:

* `io.containerd.slight.v1`
* `io.containerd.spin.v2`
* `io.containerd.wasmedge.v1`
* `io.containerd.wasmtime.v1`
* `io.containerd.lunatic.v1`
* `io.containerd.wws.v1`
* `io.containerd.wasmer.v1`

## [Usage examples](#usage-examples)

### [Running a Wasm application with `docker run`](#running-a-wasm-application-with-docker-run)

The following `docker run` command starts a Wasm container on your system:

```console
$ docker run \
  --runtime=io.containerd.wasmedge.v1 \
  --platform=wasi/wasm \
  secondstate/rust-example-hello
```

After running this command, you can visit <http://localhost:8080/> to see the "Hello world" output from this example module.

If you are receiving an error message, see the [troubleshooting section](#troubleshooting) for help.

Note the `--runtime` and `--platform` flags used in this command:

* `--runtime=io.containerd.wasmedge.v1`: Informs the Docker engine that you want to use the Wasm containerd shim instead of the standard Linux container runtime
* `--platform=wasi/wasm`: Specifies the architecture of the image you want to use. By leveraging a Wasm architecture, you don’t need to build separate images for the different machine architectures. The Wasm runtime takes care of the final step of converting the Wasm binary to machine instructions.

### [Running a Wasm application with Docker Compose](#running-a-wasm-application-with-docker-compose)

The same application can be run using the following Docker Compose file:

```yaml
services:
  app:
    image: secondstate/rust-example-hello
    platform: wasi/wasm
    runtime: io.containerd.wasmedge.v1
```

Start the application using the normal Docker Compose commands:

```console
$ docker compose up
```

### [Running a multi-service application with Wasm](#running-a-multi-service-application-with-wasm)

Networking works the same as you'd expect with Linux containers, giving you the flexibility to combine Wasm applications with other containerized workloads, such as a database, in a single application stack.

In the following example, the Wasm application leverages a MariaDB database running in a container.

1. Clone the repository.

   ```console
   $ git clone https://github.com/second-state/microservice-rust-mysql.git
   Cloning into 'microservice-rust-mysql'...
   remote: Enumerating objects: 75, done.
   remote: Counting objects: 100% (75/75), done.
   remote: Compressing objects: 100% (42/42), done.
   remote: Total 75 (delta 29), reused 48 (delta 14), pack-reused 0
   Receiving objects: 100% (75/75), 19.09 KiB | 1.74 MiB/s, done.
   Resolving deltas: 100% (29/29), done.
   ```

2. Navigate into the cloned project and start the project using Docker Compose.

   ```console
   $ cd microservice-rust-mysql
   $ docker compose up
   [+] Running 0/1
   ⠿ server Warning                                                                                                  0.4s
   [+] Building 4.8s (13/15)
   ...
   microservice-rust-mysql-db-1      | 2022-10-19 19:54:45 0 [Note] mariadbd: ready for connections.
   microservice-rust-mysql-db-1      | Version: '10.9.3-MariaDB-1:10.9.3+maria~ubu2204'  socket: '/run/mysqld/mysqld.sock'  port: 3306  mariadb.org binary distribution
   ```

   If you run `docker image ls` from another terminal window, you can see the Wasm image in your image store.

   ```console
   $ docker image ls
   REPOSITORY   TAG       IMAGE ID       CREATED         SIZE
   server       latest    2c798ddecfa1   2 minutes ago   3MB
   ```

   Inspecting the image shows the image has a `wasi/wasm` platform, a combination of OS and architecture:

   ```console
   $ docker image inspect server | grep -A 3 "Architecture"
           "Architecture": "wasm",
           "Os": "wasi",
           "Size": 3001146,
           "VirtualSize": 3001146,
   ```

3. Open the URL `http://localhost:8090` in a browser and create a few sample orders. All of these are interacting with the Wasm server.

4. When you're all done, tear everything down by hitting `Ctrl+C` in the terminal you launched the application.

### [Building and pushing a Wasm module](#building-and-pushing-a-wasm-module)

1. Create a Dockerfile that builds your Wasm application.

   Exactly how to do this varies depending on the programming language you use.

2. In a separate stage in your `Dockerfile`, extract the module and set it as the `ENTRYPOINT`.

   ```dockerfile
   # syntax=docker/dockerfile:1
   FROM scratch
   COPY --from=build /build/hello_world.wasm /hello_world.wasm
   ENTRYPOINT [ "/hello_world.wasm" ]
   ```

3. Build and push the image specifying the `wasi/wasm` architecture. Buildx makes this easy to do in a single command.

   ```console
   $ docker buildx build --platform wasi/wasm -t username/hello-world .
   ...
   => exporting to image                                                                             0.0s
   => => exporting layers                                                                            0.0s
   => => exporting manifest sha256:2ca02b5be86607511da8dc688234a5a00ab4d58294ab9f6beaba48ab3ba8de56  0.0s
   => => exporting config sha256:a45b465c3b6760a1a9fd2eda9112bc7e3169c9722bf9e77cf8c20b37295f954b    0.0s
   => => naming to docker.io/username/hello-world:latest                                            0.0s
   => => unpacking to docker.io/username/hello-world:latest                                         0.0s
   $ docker push username/hello-world
   ```

## [Troubleshooting](#troubleshooting)

This section contains instructions on how to resolve common issues.

### [Unknown runtime specified](#unknown-runtime-specified)

If you try to run a Wasm container without the [containerd image store](https://docs.docker.com/desktop/features/containerd/), an error similar to the following displays:

```text
docker: Error response from daemon: Unknown runtime specified io.containerd.wasmedge.v1.
```

[Turn on the containerd feature](https://docs.docker.com/desktop/features/containerd/#enable-the-containerd-image-store) in Docker Desktop settings and try again.

### [Failed to start shim: failed to resolve runtime path](#failed-to-start-shim-failed-to-resolve-runtime-path)

If you use an older version of Docker Desktop that doesn't support running Wasm workloads, you will see an error message similar to the following:

```text
docker: Error response from daemon: failed to start shim: failed to resolve runtime path: runtime "io.containerd.wasmedge.v1" binary not installed "containerd-shim-wasmedge-v1": file does not exist: unknown.
```

Update your Docker Desktop to the latest version and try again.

## [Known issues](#known-issues)

* Docker Compose may not exit cleanly when interrupted. As a workaround, clean up `docker-compose` processes by sending them a SIGKILL (`killall -9 docker-compose`).
* Pushes to Docker Hub might give an error stating `server message: insufficient_scope: authorization failed`, even after signing in through Docker Desktop. As a workaround, run `docker login` in the CLI

----
url: https://docs.docker.com/reference/cli/docker/node/promote/
----

# docker node promote

***

| Description | Promote one or more nodes to manager in the swarm |
| ----------- | ------------------------------------------------- |
| Usage       | `docker node promote NODE [NODE...]`              |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Promotes a node to manager. This command can only be executed on a manager node.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Examples](#examples)

```console
$ docker node promote <node name>
```

----
url: https://docs.docker.com/reference/samples/wordpress/
----

# WordPress samples

| Name                                                                                                                     | Description                                                                         |
| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| [WordPress / MySQL](https://github.com/docker/awesome-compose/tree/master/wordpress-mysql)                               | A sample WordPress setup.                                                           |
| [Compose and WordPress](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/wordpress/) | This quick-start guide demonstrates how to use Compose to set up and run WordPress. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/dhi/migration/
----

# Migration

***

Table of contents

***

This section provides guidance for migrating your applications to Docker Hardened Images (DHI). Migrating to DHI enhances the security posture of your containerized applications by leveraging hardened base images with built-in security features.

## [Migration paths](#migration-paths)

Choose the migration approach that best fits your needs:

### [Migrate with Gordon](/dhi/migration/migrate-with-ai/)

[Use Gordon to automatically migrate your Dockerfile to Docker Hardened Images with guidance and recommendations.](/dhi/migration/migrate-with-ai/)

### [Migrate from Alpine or Debian images](/dhi/migration/migrate-from-doi/)

[Manual migration guide for moving from Docker Official Images (Alpine or Debian-based) to Docker Hardened Images.](/dhi/migration/migrate-from-doi/)

### [Migrate from Ubuntu](/dhi/migration/migrate-from-ubuntu/)

[Manual migration guide for transitioning from Ubuntu-based images to Docker Hardened Images.](/dhi/migration/migrate-from-ubuntu/)

### [Migrate from Wolfi](/dhi/migration/migrate-from-wolfi/)

[Manual migration guide for transitioning from Wolfi-based images to Docker Hardened Images.](/dhi/migration/migrate-from-wolfi/)

## [Resources](#resources)

### [Migration checklist](/dhi/migration/checklist/)

[A comprehensive checklist of migration considerations to ensure successful transition to Docker Hardened Images.](/dhi/migration/checklist/)

### [Examples](/dhi/migration/examples/)

[Example Dockerfile migrations for different programming languages and frameworks to guide your migration process.](/dhi/migration/examples/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/version/
----

# docker buildx version

***

| Description | Show buildx version information |
| ----------- | ------------------------------- |
| Usage       | `docker buildx version`         |

## [Description](#description)

View version information

```console
$ docker buildx version
github.com/docker/buildx v0.11.2 9872040b6626fb7d87ef7296fd5b832e8cc2ad17
```

----
url: https://docs.docker.com/guides/testcontainers-go-getting-started/write-tests/
----

# Write tests with Testcontainers

***

Table of contents

***

You have the `Repository` implementation ready, but for testing you need a PostgreSQL database. You can use testcontainers-go to spin up a Postgres database in a Docker container and run your tests against that database.

## [Set up the test database](#set-up-the-test-database)

In real applications you might use a database migration tool, but for this guide, use a script to initialize the database.

Create a `testdata/init-db.sql` file to create the `CUSTOMERS` table and insert sample data:

```sql
CREATE TABLE IF NOT EXISTS customers (id serial, name varchar(255), email varchar(255));

INSERT INTO customers(name, email) VALUES ('John', 'john@gmail.com');
```

## [Understand the testcontainers-go API](#understand-the-testcontainers-go-api)

The testcontainers-go library provides the generic `Container` abstraction that can run any containerized service. To further simplify, testcontainers-go provides technology-specific modules that reduce boilerplate and provide a functional options pattern to construct the container instance.

For example, `PostgresContainer` provides `WithDatabase()`, `WithUsername()`, `WithPassword()`, and other functions to set various properties of Postgres containers.

## [Write the test](#write-the-test)

Create the `customer/repo_test.go` file and implement the test:

```go
package customer

import (
	"context"
	"path/filepath"
	"testing"

	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/require"
	"github.com/testcontainers/testcontainers-go"
	"github.com/testcontainers/testcontainers-go/modules/postgres"
)

func TestCustomerRepository(t *testing.T) {
	ctx := context.Background()

	ctr, err := postgres.Run(ctx,
		"postgres:16-alpine",
		postgres.WithInitScripts(filepath.Join("..", "testdata", "init-db.sql")),
		postgres.WithDatabase("test-db"),
		postgres.WithUsername("postgres"),
		postgres.WithPassword("postgres"),
		postgres.BasicWaitStrategies(),
	)
	testcontainers.CleanupContainer(t, ctr)
	require.NoError(t, err)

	connStr, err := ctr.ConnectionString(ctx, "sslmode=disable")
	require.NoError(t, err)

	customerRepo, err := NewRepository(ctx, connStr)
	require.NoError(t, err)

	c, err := customerRepo.CreateCustomer(ctx, Customer{
		Name:  "Henry",
		Email: "henry@gmail.com",
	})
	assert.NoError(t, err)
	assert.NotNil(t, c)

	customer, err := customerRepo.GetCustomerByEmail(ctx, "henry@gmail.com")
	assert.NoError(t, err)
	assert.NotNil(t, customer)
	assert.Equal(t, "Henry", customer.Name)
	assert.Equal(t, "henry@gmail.com", customer.Email)
}
```

Here's what the test does:

* Calls `postgres.Run()` with the `postgres:16-alpine` Docker image as the first argument. This is the v0.41.0 API — the image is a required positional parameter instead of an option.
* Configures initialization scripts using `WithInitScripts(...)` so that the `CUSTOMERS` table is created and sample data is inserted after the database starts.
* Uses `postgres.BasicWaitStrategies()` which combines waiting for the Postgres log message and for the port to be ready. This replaces manual wait strategy configuration.
* Calls `testcontainers.CleanupContainer(t, ctr)` right after `postgres.Run()`. This registers automatic cleanup with the test framework, replacing the manual `t.Cleanup` and `Terminate` pattern.
* Obtains the database `ConnectionString` from the container and initializes a `Repository`.
* Creates a customer with the email `henry@gmail.com` and verifies that the customer exists in the database.

[Reuse containers with test suites »](https://docs.docker.com/guides/testcontainers-go-getting-started/test-suites/)

----
url: https://docs.docker.com/reference/api/engine/version/v1.48/
----

# Docker Engine API v1.48 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.48.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.48.yaml)

# Docker Engine API (1.48)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.48.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.48) is used. For example, calling `/info` is the same as calling `/v1.48/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means the server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.48/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.48/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.48/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf",
"Created": "2025-02-17T17:43:39.64001363Z",
"Path": "/bin/sh",
"Args": [
"-c",
"exit 9"
],
"State": {
"Status": "running",
"Running": true,
"Paused": false,
"Restarting": false,
"OOMKilled": false,
"Dead": false,
"Pid": 1234,
"ExitCode": 0,
"Error": "string",
"StartedAt": "2020-01-06T09:06:59.461876391Z",
"FinishedAt": "2020-01-06T09:07:59.461876391Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2020-01-04T10:44:24.496525531Z",
"End": "2020-01-04T10:45:21.364524523Z",
"ExitCode": 0,
"Output": "string"
}
]
}
},
"Image": "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782",
"ResolvConfPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/resolv.conf",
"HostnamePath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hostname",
"HostsPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hosts",
"LogPath": "/var/lib/docker/containers/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59-json.log",
"Name": "/funny_chatelet",
"RestartCount": 0,
"Driver": "overlayfs",
"Platform": "linux",
"ImageManifestDescriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"MountLabel": "",
"ProcessLabel": "",
"AppArmorProfile": "",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"CpuShares": 0,
"Memory": 0,
"CgroupParent": "string",
"BlkioWeight": 1000,
"BlkioWeightDevice": [
{
"Path": "string",
"Weight": 0
}
],
"BlkioDeviceReadBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceReadIOps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteIOps": [
{
"Path": "string",
"Rate": 0
}
],
"CpuPeriod": 0,
"CpuQuota": 0,
"CpuRealtimePeriod": 0,
"CpuRealtimeRuntime": 0,
"CpusetCpus": "0-3",
"CpusetMems": "string",
"Devices": [
{
"PathOnHost": "/dev/deviceName",
"PathInContainer": "/dev/deviceName",
"CgroupPermissions": "mrw"
}
],
"DeviceCgroupRules": [
"c 13:* rwm"
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"KernelMemoryTCP": 0,
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 100,
"NanoCpus": 0,
"OomKillDisable": true,
"Init": true,
"PidsLimit": 0,
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
],
"CpuCount": 0,
"CpuPercent": 0,
"IOMaximumIOps": 0,
"IOMaximumBandwidth": 0,
"Binds": [
"string"
],
"ContainerIDFile": "",
"LogConfig": {
"Type": "local",
"Config": {
"max-file": "5",
"max-size": "10m"
}
},
"NetworkMode": "string",
"PortBindings": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"VolumeDriver": "string",
"VolumesFrom": [
"string"
],
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"ConsoleSize": [
80,
64
],
"Annotations": {
"property1": "string",
"property2": "string"
},
"CapAdd": [
"string"
],
"CapDrop": [
"string"
],
"CgroupnsMode": "private",
"Dns": [
"string"
],
"DnsOptions": [
"string"
],
"DnsSearch": [
"string"
],
"ExtraHosts": [
"string"
],
"GroupAdd": [
"string"
],
"IpcMode": "string",
"Cgroup": "string",
"Links": [
"string"
],
"OomScoreAdj": 500,
"PidMode": "string",
"Privileged": true,
"PublishAllPorts": true,
"ReadonlyRootfs": true,
"SecurityOpt": [
"string"
],
"StorageOpt": {
"property1": "string",
"property2": "string"
},
"Tmpfs": {
"property1": "string",
"property2": "string"
},
"UTSMode": "string",
"UsernsMode": "string",
"ShmSize": 0,
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Runtime": "string",
"Isolation": "default",
"MaskedPaths": [
"/proc/asound",
"/proc/acpi",
"/proc/kcore",
"/proc/keys",
"/proc/latency_stats",
"/proc/timer_list",
"/proc/timer_stats",
"/proc/sched_debug",
"/proc/scsi",
"/sys/firmware",
"/sys/devices/virtual/powercap"
],
"ReadonlyPaths": [
"/proc/bus",
"/proc/fs",
"/proc/irq",
"/proc/sys",
"/proc/sysrq-trigger"
]
},
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"SizeRw": "122880",
"SizeRootFs": "1653948416",
"Mounts": [
{
"Type": "volume",
"Name": "myvolume",
"Source": "/var/lib/docker/volumes/myvolume/_data",
"Destination": "/usr/share/nginx/html/",
"Driver": "local",
"Mode": "z",
"RW": true,
"Propagation": ""
}
],
"Config": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"NetworkSettings": {
"Bridge": "docker0",
"SandboxID": "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": "",
"Ports": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"SandboxKey": "/var/run/docker/netns/8ab54b426c38",
"SecondaryIPAddresses": [
{
"Addr": "string",
"PrefixLen": 0
}
],
"SecondaryIPv6Addresses": [
{
"Addr": "string",
"PrefixLen": 0
}
],
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"MacAddress": "02:42:ac:11:00:04",
"Networks": {
"property1": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
},
"property2": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
}
}
}
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.48/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": {
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
]
},
"Processes": {
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.48/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.48/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.48/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.48/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"name": "boring_wozniak",
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"read": "2025-01-16T13:55:22.165243637Z",
"preread": "2025-01-16T13:55:21.160452595Z",
"pids_stats": {
"current": 5,
"limit": "18446744073709551615"
},
"blkio_stats": {
"io_service_bytes_recursive": [
{
"major": 254,
"minor": 0,
"op": "read",
"value": 7593984
},
{
"major": 254,
"minor": 0,
"op": "write",
"value": 100
}
],
"io_serviced_recursive": null,
"io_queue_recursive": null,
"io_service_time_recursive": null,
"io_wait_time_recursive": null,
"io_merged_recursive": null,
"io_time_recursive": null,
"sectors_recursive": null
},
"num_procs": 16,
"storage_stats": {
"read_count_normalized": 7593984,
"read_size_bytes": 7593984,
"write_count_normalized": 7593984,
"write_size_bytes": 7593984
},
"cpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"memory_stats": {
"usage": 0,
"max_usage": 0,
"stats": {
"active_anon": 1572864,
"active_file": 5115904,
"anon": 1572864,
"anon_thp": 0,
"file": 7626752,
"file_dirty": 0,
"file_mapped": 2723840,
"file_writeback": 0,
"inactive_anon": 0,
"inactive_file": 2510848,
"kernel_stack": 16384,
"pgactivate": 0,
"pgdeactivate": 0,
"pgfault": 2042,
"pglazyfree": 0,
"pglazyfreed": 0,
"pgmajfault": 45,
"pgrefill": 0,
"pgscan": 0,
"pgsteal": 0,
"shmem": 0,
"slab": 1180928,
"slab_reclaimable": 725576,
"slab_unreclaimable": 455352,
"sock": 0,
"thp_collapse_alloc": 0,
"thp_fault_alloc": 1,
"unevictable": 0,
"workingset_activate": 0,
"workingset_nodereclaim": 0,
"workingset_refault": 0
},
"failcnt": 0,
"limit": 8217579520,
"commitbytes": 0,
"commitpeakbytes": 0,
"privateworkingset": 0
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.48/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.48/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.48/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.48/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.48/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime.This field is omitted when empty.                         |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.48/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"Published ports are discarded when using host network mode"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.48/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.48/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.48/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.48/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.48/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.48/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.48/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.48/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.48/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.48/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.48/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |
| manifests   | booleanDefault: falseInclude `Manifests` in the image summary.                                                                                                                                                                                                                                                                                                                                       |

### Responses

/v1.48/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2,
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
}
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.48/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| keep-storage   | integer \<int64>Amount of disk space in bytes to keep for cache> **Deprecated**: This parameter is deprecated and has been renamed to "reserved-space". It is kept for backward compatibility and will be removed in API v1.52.                                                                                                                                                                                                                                          |
| reserved-space | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| max-used-space | integer \<int64>Maximum amount of disk space allowed to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                   |
| min-free-space | integer \<int64>Target amount of free disk space after pruning                                                                                                                                                                                                                                                                                                                                                                                                           |
| all            | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters        | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.48/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. If the name includes a tag or digest, specific behavior applies:- If only `fromImage` includes a tag, that tag is used.
- If both `fromImage` and `tag` are provided, `tag` takes precedence.
- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.
- If neither a tag nor digest is specified, all tags are pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.48/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

##### query Parameters

|           |                                                              |
| --------- | ------------------------------------------------------------ |
| manifests | booleanDefault: falseInclude Manifests in the image summary. |

### Responses

/v1.48/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"DockerVersion": "27.0.1",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "web:web",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": true,
"Image": "",
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show the history for. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.48/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag      | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed.                                                                                                                                                                                                                                                                                                                   |
| platform | stringJSON-encoded OCI platform to select the platform-variant to push. If not provided, all available variants will attempt to be pushed.If the daemon provides a multi-platform image store, this selects the platform-variant to push to the registry. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.48/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.48/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|         |                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------ |
| force   | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags |
| noprune | booleanDefault: falseDo not delete untagged parent images                                              |

### Responses

/v1.48/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                   |
| limit        | integerMaximum number of results to return                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.48/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.48/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.48/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.48/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| names    | Array of stringsImage names to filter by                                                                                                                                                                                                                                                 |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.48/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| quiet    | booleanDefault: falseSuppress progress details during load.                                                                                                                                                                                                                              |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be load if the image is multi-platform. If not provided, the full multi-platform image will be loaded.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.48/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.48/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv4": true,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.48/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv4": true,
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.48/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|              |                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired | stringThe network's name.                                                                                                                                                                                                              |
| Driver       | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope        | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal     | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable   | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress      | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly   | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|              | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|              | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv4   | booleanEnable IPv4 on the network.                                                                                                                                                                                                     |
| EnableIPv6   | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|              | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|              | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.48/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv4": true,
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.48/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
},
"MacAddress": "02:42:ac:12:05:02",
"Priority": 100
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.48/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.48/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.48/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.48/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.48/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.48/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.48/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.48/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.48/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.48/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.48/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.48/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.48/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.48/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.48/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.48/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.48/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.48/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.48/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.48/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.48/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.48/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.48/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.48/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.48/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.48/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.48/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.48/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.48/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.48/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.48/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.48/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.48/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.48/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.48/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.48/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.48/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.48/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.48/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.48/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.48/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.48/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.48/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.48/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.48/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.48/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.48/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.48/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.48/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.48/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.48/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.48/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.48/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.48/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.48/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"BridgeNfIptables": false,
"BridgeNfIp6tables": false,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "6.8.0-31-generic",
"OperatingSystem": "Ubuntu 24.04 LTS",
"OSVersion": "24.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"AllowNondistributableArtifactsCIDRs": [ ],
"AllowNondistributableArtifactsHostnames": [ ],
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "27.0.1",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
],
"Containerd": {
"Address": "/run/containerd/containerd.sock",
"Namespaces": {
"Containers": "moby",
"Plugins": "plugins.moby"
}
}
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.48/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "27.0.1",
"Details": { }
}
],
"Version": "27.0.1",
"ApiVersion": "1.47",
"MinAPIVersion": "1.24",
"GitCommit": "48a66213fe",
"GoVersion": "go1.22.7",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "6.8.0-31-generic",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.48/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.48/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.48/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|      |                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |

### Responses

/v1.48/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parents": [ ],
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parents": [
"ndlpt0hhvkqcdfkputsk4cq9c"
],
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.48/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.48/session

----
url: https://docs.docker.com/build/builders/manage/
----

# Manage builders

***

Table of contents

***

You can create, inspect, and manage builders using `docker buildx` commands, or [using Docker Desktop](#manage-builders-with-docker-desktop).

## [Create a new builder](#create-a-new-builder)

The default builder uses the [`docker` driver](https://docs.docker.com/build/builders/drivers/docker/). You can't manually create new `docker` builders, but you can create builders that use other drivers, such as the [`docker-container` driver](https://docs.docker.com/build/builders/drivers/docker-container/), which runs the BuildKit daemon in a container.

Use the [`docker buildx create`](/reference/cli/docker/buildx/create/) command to create a builder.

```console
$ docker buildx create --name=<builder-name>
```

Buildx uses the `docker-container` driver by default if you omit the `--driver` flag. For more information about available drivers, see [Build drivers](https://docs.docker.com/build/builders/drivers/).

## [List available builders](#list-available-builders)

Use `docker buildx ls` to see builder instances available on your system, and the drivers they're using.

```console
$ docker buildx ls
NAME/NODE       DRIVER/ENDPOINT      STATUS   BUILDKIT PLATFORMS
default *       docker
  default       default              running  v0.11.6  linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
my_builder      docker-container
  my_builder0   default              running  v0.11.6  linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
```

The asterisk (`*`) next to the builder name indicates the [selected builder](https://docs.docker.com/build/builders/#selected-builder).

## [Inspect a builder](#inspect-a-builder)

To inspect a builder with the CLI, use `docker buildx inspect <name>`. You can only inspect a builder if the builder is active. You can add the `--bootstrap` flag to the command to start the builder.

```console
$ docker buildx inspect --bootstrap my_builder
[+] Building 1.7s (1/1) FINISHED                                                                  
 => [internal] booting buildkit                                                              1.7s
 => => pulling image moby/buildkit:buildx-stable-1                                           1.3s
 => => creating container buildx_buildkit_my_builder0                                        0.4s
Name:          my_builder
Driver:        docker-container
Last Activity: 2023-06-21 18:28:37 +0000 UTC

Nodes:
Name:      my_builder0
Endpoint:  unix:///var/run/docker.sock
Status:    running
Buildkit:  v0.11.6
Platforms: linux/arm64, linux/amd64, linux/amd64/v2, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6
```

If you want to see how much disk space a builder is using, use the `docker buildx du` command. By default, this command shows the total disk usage for all available builders. To see usage for a specific builder, use the `--builder` flag.

```console
$ docker buildx du --builder my_builder
ID                                        RECLAIMABLE SIZE        LAST ACCESSED
olkri5gq6zsh8q2819i69aq6l                 true        797.2MB     37 seconds ago
6km4kasxgsywxkm6cxybdumbb*                true        438.5MB     36 seconds ago
qh3wwwda7gx2s5u4hsk0kp4w7                 true        213.8MB     37 seconds ago
54qq1egqem8max3lxq6180cj8                 true        200.2MB     37 seconds ago
ndlp969ku0950bmrw9muolw0c*                true        116.7MB     37 seconds ago
u52rcsnfd1brwc0chwsesb3io*                true        116.7MB     37 seconds ago
rzoeay0s4nmss8ub59z6lwj7d                 true        46.25MB     4 minutes ago
itk1iibhmv7awmidiwbef633q                 true        33.33MB     37 seconds ago
4p78yqnbmgt6xhcxqitdieeln                 true        19.46MB     4 minutes ago
dgkjvv4ay0szmr9bl7ynla7fy*                true        19.24MB     36 seconds ago
tuep198kmcw299qc9e4d1a8q2                 true        8.663MB     4 minutes ago
n1wzhauk9rpmt6ib1es7dktvj                 true        20.7kB      4 minutes ago
0a2xfhinvndki99y69157udlm                 true        16.56kB     37 seconds ago
gf0z1ypz54npfererqfeyhinn                 true        16.38kB     37 seconds ago
nz505f12cnsu739dw2pw0q78c                 true        8.192kB     37 seconds ago
hwpcyq5hdfvioltmkxu7fzwhb*                true        8.192kB     37 seconds ago
acekq89snc7j6im1rjdizvsg1*                true        8.192kB     37 seconds ago
Reclaimable:  2.01GB
Total:        2.01GB
```

## [Remove a builder](#remove-a-builder)

Use the [`docker buildx remove`](/reference/cli/docker/buildx/create/) command to remove a builder.

```console
$ docker buildx rm <builder-name>
```

If you remove your currently selected builder, the default `docker` builder is automatically selected. You can't remove the default builder.

Local build cache for the builder is also removed.

### [Removing remote builders](#removing-remote-builders)

Removing a remote builder doesn't affect the remote build cache. It also doesn't stop the remote BuildKit daemon. It only removes your connection to the builder.

## [Manage builders with Docker Desktop](#manage-builders-with-docker-desktop)

If you have turned on the [Docker Desktop Builds view](https://docs.docker.com/desktop/use-desktop/builds/), you can inspect builders in [Docker Desktop settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#builders).

----
url: https://docs.docker.com/reference/cli/docker/dhi/catalog/
----

# docker dhi catalog

***

| Description | Browse the Docker Hardened Images catalog |
| ----------- | ----------------------------------------- |

## [Description](#description)

Commands to browse available Docker Hardened Images and Helm charts

## [Options](#options)

| Option  | Default | Description                                |
| ------- | ------- | ------------------------------------------ |
| `--org` |         | Docker Hub organization (overrides config) |

## [Subcommands](#subcommands)

| Command                                                                                     | Description                            |
| ------------------------------------------------------------------------------------------- | -------------------------------------- |
| [`docker dhi catalog get`](https://docs.docker.com/reference/cli/docker/dhi/catalog/get/)   | Get details of a Docker Hardened Image |
| [`docker dhi catalog list`](https://docs.docker.com/reference/cli/docker/dhi/catalog/list/) | List available Docker Hardened Images  |

----
url: https://docs.docker.com/reference/cli/docker/sandbox/create/opencode/
----

# docker sandbox create opencode

***

| Description | Create a sandbox for opencode                                   |
| ----------- | --------------------------------------------------------------- |
| Usage       | `docker sandbox create opencode WORKSPACE [EXTRA_WORKSPACE...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Create a sandbox with access to a host workspace for opencode.

The workspace path is required and will be exposed inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use 'docker sandbox run SANDBOX' to start opencode after creation.

## [Examples](#examples)

### [Create an OpenCode sandbox in the current directory](#create-an-opencode-sandbox-in-the-current-directory)

```console
$ docker sandbox create opencode .
```

### [Create with an absolute path](#create-with-an-absolute-path)

```console
$ docker sandbox create opencode /home/user/my-project
```

### [Create and then run](#create-and-then-run)

```console
$ docker sandbox create --name my-opencode opencode ~/my-project
$ docker sandbox run my-opencode
```

----
url: https://docs.docker.com/reference/compose-file/networks/
----

# Define and manage networks in Docker Compose

***

Table of contents

***

Networks let services communicate with each other. By default Compose sets up a single network for your app. Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by the service's name. The top-level `networks` element lets you configure named networks that can be reused across multiple services.

To use a network across multiple services, you must explicitly grant each service access by using the [networks](https://docs.docker.com/reference/compose-file/services/) attribute within the `services` top-level element. The `networks` top-level element has additional syntax that provides more granular control.

## [Examples](#examples)

### [Basic example](#basic-example)

In the following example, at runtime, networks `front-tier` and `back-tier` are created and the `frontend` service is connected to `front-tier` and `back-tier` networks.

```yml
services:
  frontend:
    image: example/webapp
    networks:
      - front-tier
      - back-tier

networks:
  front-tier:
  back-tier:
```

### [Advanced example](#advanced-example)

```yml
services:
  proxy:
    build: ./proxy
    networks:
      - frontend
  app:
    build: ./app
    networks:
      - frontend
      - backend
  db:
    image: postgres:18
    networks:
      - backend

networks:
  frontend:
    # Specify driver options
    driver: bridge
    driver_opts:
      com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"
  backend:
    # Use a custom driver
    driver: custom-driver
```

This example shows a Compose file which defines two custom networks. The `proxy` service is isolated from the `db` service, because they do not share a network in common. Only `app` can talk to both.

## [The default network](#the-default-network)

When a Compose file doesn't declare explicit networks, Compose uses an implicit `default` network. Services without an explicit [`networks`](https://docs.docker.com/reference/compose-file/services/#networks) declaration are connected by Compose to this `default` network:

```yml
services:
  some-service:
    image: foo
```

This example is actually equivalent to:

```yml
services:
  some-service:
    image: foo
    networks:
      default: {}  
networks:
  default: {}      
```

You can customize the `default` network with an explicit declaration:

```yml
networks:
  default: 
    name: a_network # Use a custom name
    driver_opts:    # pass options to driver for network creation
      com.docker.network.bridge.host_binding_ipv4: 127.0.0.1
```

For options, see the [Docker Engine docs](https://docs.docker.com/engine/network/drivers/bridge/#options).

## [Attributes](#attributes)

### [`attachable`](#attachable)

If `attachable` is set to `true`, then standalone containers should be able to attach to this network, in addition to services. If a standalone container attaches to the network, it can communicate with services and other standalone containers that are also attached to the network.

```yml
networks:
  mynet1:
    driver: overlay
    attachable: true
```

### [`driver`](#driver)

`driver` specifies which driver should be used for this network. Compose returns an error if the driver is not available on the platform.

```yml
networks:
  db-data:
    driver: bridge
```

For more information on drivers and available options, see [Network drivers](https://docs.docker.com/engine/network/drivers/).

### [`driver_opts`](#driver_opts)

`driver_opts` specifies a list of options as key-value pairs to pass to the driver. These options are driver-dependent.

```yml
networks:
  frontend:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.host_binding_ipv4: "127.0.0.1"
```

Consult the [network drivers documentation](https://docs.docker.com/engine/network/) for more information.

### [`enable_ipv4`](#enable_ipv4)

Requires: Docker Compose [2.33.1](https://github.com/docker/compose/releases/tag/v2.33.1) and later

`enable_ipv4` can be used to disable IPv4 address assignment.

```yml
  networks:
    ip6net:
      enable_ipv4: false
      enable_ipv6: true
```

### [`enable_ipv6`](#enable_ipv6)

`enable_ipv6` enables IPv6 address assignment.

```yml
  networks:
    ip6net:
      enable_ipv6: true
```

### [`external`](#external)

If set to `true`:

* `external` specifies that this network’s lifecycle is maintained outside of that of the application. Compose doesn't attempt to create these networks, and returns an error if one doesn't exist.
* All other attributes apart from name are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid.

In the following example, `proxy` is the gateway to the outside world. Instead of attempting to create a network, Compose queries the platform for an existing network called `outside` and connects the `proxy` service's containers to it.

```yml
services:
  proxy:
    image: example/proxy
    networks:
      - outside
      - default
  app:
    image: example/app
    networks:
      - default

networks:
  outside:
    external: true
```

### [`ipam`](#ipam)

`ipam` specifies a custom IPAM configuration. This is an object with several properties, each of which is optional:

* `driver`: Custom IPAM driver, instead of the default.

* `config`: A list with zero or more configuration elements, each containing a:

  * `subnet`: Subnet in CIDR format that represents a network segment
  * `ip_range`: Range of IPs from which to allocate container IPs
  * `gateway`: IPv4 or IPv6 gateway for the master subnet
  * `aux_addresses`: Auxiliary IPv4 or IPv6 addresses used by Network driver, as a mapping from hostname to IP

* `options`: Driver-specific options as a key-value mapping.

```yml
networks:
  mynet1:
    ipam:
      driver: default
      config:
        - subnet: 172.28.0.0/16
          ip_range: 172.28.5.0/24
          gateway: 172.28.5.254
          aux_addresses:
            host1: 172.28.1.5
            host2: 172.28.1.6
            host3: 172.28.1.7
      options:
        foo: bar
        baz: "0"
```

### [`internal`](#internal)

By default, Compose provides external connectivity to networks. `internal`, when set to `true`, lets you create an externally isolated network.

### [`labels`](#labels)

Add metadata to containers using `labels`. You can use either an array or a dictionary.

It is recommended that you use reverse-DNS notation to prevent labels from conflicting with those used by other software.

```yml
networks:
  mynet1:
    labels:
      com.example.description: "Financial transaction network"
      com.example.department: "Finance"
      com.example.label-with-empty-value: ""
```

```yml
networks:
  mynet1:
    labels:
      - "com.example.description=Financial transaction network"
      - "com.example.department=Finance"
      - "com.example.label-with-empty-value"
```

Compose sets `com.docker.compose.project` and `com.docker.compose.network` labels.

### [`name`](#name)

`name` sets a custom name for the network. The name field can be used to reference networks which contain special characters. The name is used as is and is not scoped with the project name.

```yml
networks:
  network1:
    name: my-app-net
```

It can also be used in conjunction with the `external` property to define the platform network that Compose should retrieve, typically by using a parameter so the Compose file doesn't need to hard-code runtime specific values:

```yml
networks:
  network1:
    external: true
    name: "${NETWORK_ID}"
```

## [Additional resources](#additional-resources)

For more examples, see [Networking in Compose](https://docs.docker.com/compose/how-tos/networking/).

----
url: https://docs.docker.com/guides/vuejs/run-tests/
----

# Run vue.js tests in a container

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize Vue.js application](https://docs.docker.com/guides/vuejs/containerize/).

## [Overview](#overview)

Testing is a critical part of the development process. In this section, you'll learn how to:

* Run unit tests using Vitest inside a Docker container.
* Use Docker Compose to run tests in an isolated, reproducible environment.

You’ll use [Vitest](https://vitest.dev) — a blazing fast test runner designed for Vite — together with [@vue/test-utils](https://test-utils.vuejs.org/) to write unit tests that validate your component logic, props, events, and reactive behavior.

This setup ensures your Vue.js components are tested in an environment that mirrors how users actually interact with your application.

***

## [Run tests during development](#run-tests-during-development)

`docker-vuejs-sample` application includes a sample test file at location:

```console
$ src/components/__tests__/HelloWorld.spec.ts
```

This test uses Vitest and Vue Test Utils to verify the behavior of the HelloWorld component.

***

### [Step 1: Update compose.yaml](#step-1-update-composeyaml)

Add a new service named `vuejs-test` to your `compose.yaml` file. This service allows you to run your test suite in an isolated containerized environment.

|                                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```
``` | ```yaml
services:
  vuejs-prod:
    build:
      context: .
      dockerfile: Dockerfile
    image: docker-vuejs-sample
    ports:
      - "8080:8080"

  vuejs-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "5173:5173"
    develop:
      watch:
        - action: sync
          path: .
          target: /app
          
  vuejs-test:
    build:
      context: .
      dockerfile: Dockerfile.dev
    command: ["npm", "run", "test:unit"]
``` |

The vuejs-test service reuses the same `Dockerfile.dev` used for [development](https://docs.docker.com/guides/vuejs/develop/) and overrides the default command to run tests with `npm run test`. This setup ensures a consistent test environment that matches your local development configuration.

After completing the previous steps, your project directory should contain the following files:

```text
├── docker-vuejs-sample/
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ ├── .dockerignore
│ ├── compose.yaml
│ └── nginx.conf
```

### [Step 2: Run the tests](#step-2-run-the-tests)

To execute your test suite inside the container, run the following command from your project root:

```console
$ docker compose run --rm vuejs-test
```

This command will:

* Start the `vuejs-test` service defined in your `compose.yaml` file.
* Execute the `npm run test` script using the same environment as development.
* Automatically remove the container after the tests complete [`docker compose run --rm`](/reference/cli/docker/compose/run/) command.

You should see output similar to the following:

```shell
Test Files: 1 passed (1)
Tests:      1 passed (1)
Start at:   16:50:55
Duration:   718ms
```

> Note
>
> For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

***

## [Summary](#summary)

In this section, you learned how to run unit tests for your Vue.js application inside a Docker container using Vitest and Docker Compose.

What you accomplished:

* Created a `vuejs-test` service in `compose.yaml` to isolate test execution.
* Reused the development `Dockerfile.dev` to ensure consistency between dev and test environments.
* Ran tests inside the container using `docker compose run --rm vuejs-test`.
* Ensured reliable, repeatable testing across environments without depending on your local machine setup.

***

## [Related resources](#related-resources)

Explore official references and best practices to sharpen your Docker testing workflow:

* [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax.
* [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles.
* [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`.
* [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container.

***

## [Next steps](#next-steps)

Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions to automatically build and test your Vue.js application in a containerized environment. This ensures your code is validated on every push or pull request, maintaining consistency and reliability across your development workflow.

[Automate your builds with GitHub Actions »](https://docs.docker.com/guides/vuejs/configure-github-actions/)

----
url: https://docs.docker.com/scout/policy/scores/
----

# Docker Scout health scores

***

Table of contents

***

Subscription: Pro Team Business

Availability: Beta

Docker Scout health scores provide a security assessment, and overall supply chain health, of images on Docker Hub, helping you determine whether an image meets established security best practices. The scores range from A to F, where A represents the highest level of security and F the lowest, offering an at-a-glance view of the security posture of your images.

Only users who are members of the organization that owns the repository, and have at least “read” access to the repository, can view the health score. The score is not visible to users outside the organization or members without "read" access.

## [Viewing health scores](#viewing-health-scores)

To view the health score of an image in Docker Hub:

1. Go to Docker Hub and sign in.
2. Navigate to your organization's page.

In the list of repositories, you can see the health score of each repository based on the latest pushed tag.

To view the health score of an image in Docker Desktop:

1. Open Docker Desktop and sign in to your Docker account.
2. Navigate to the **Images** view and select the **Hub** tab.

In the list of repositories, the **Health** column displays the scores of the different tags that have been pushed to Docker Hub.

The health score badge is color-coded to indicate the overall health of the repository:

* **Green**: A score of A or B.
* **Yellow**: A score of C.
* **Orange**: A score of D.
* **Red**: A score of E or F.
* **Gray**: An `N/A` score.

The score is also displayed on the Docker Hub page for a given repository, along with each policy that contributed to the score.

## [Scoring system](#scoring-system)

Health scores are determined by evaluating images against Docker Scout [policies](https://docs.docker.com/scout/policy/). These policies align with best practices for the software supply chain.

If your image repositories are already enrolled with Docker Scout, the health score is calculated automatically based on the policies that are enabled for your organization. This also includes any custom policies that you have configured.

If you're not using Docker Scout, the health scores show the compliance of your images with the default policies, a set of supply chain rules recommended by Docker as foundational standards for images. You can enable Docker Scout for your organization and edit the policy configurations to get a more relevant health score based on your specific policies.

### [Scoring process](#scoring-process)

Each policy is assigned a points value based on its [type](https://docs.docker.com/scout/policy/#policy-types). If the image is compliant with a policy, it is awarded the points value for that policy type. The health score of an image is calculated based on the percentage of points achieved relative to the total possible points.

1. Policy compliance is evaluated for the image.

2. Points are awarded based on compliance with policies.

3. The points achieved percentage is calculated:

   ```text
   Percentage = (Points / Total) * 100
   ```

4. The final score is assigned based on the percentage of points achieved, as shown in the following table:

   | Points percentage (awarded out of total) | Score |
   | ---------------------------------------- | ----- |
   | More than 90%                            | A     |
   | 71% to 90%                               | B     |
   | 51% to 70%                               | C     |
   | 31% to 50%                               | D     |
   | 11% to 30%                               | E     |
   | Less than 10%                            | F     |

### [N/A scores](#na-scores)

Images can also be assigned an `N/A` score, which can happen when:

* The image is larger than 4GB (compressed size).
* The image architecture is not `linux/amd64` or `linux/arm64`.
* The image is too old and does not have fresh data for evaluation.

If you see an `N/A` score, consider the following:

* If the image is too large, try reducing the size of the image.
* If the image has an unsupported architecture, rebuild the image for a supported architecture.
* If the image is too old, push a new tag to trigger a fresh evaluation.

### [Policy weights](#policy-weights)

Different policy types carry varying weights, which impact the score assigned to an image during evaluation, as shown in the following table.

| Policy type                                                                                        | Points |
| -------------------------------------------------------------------------------------------------- | ------ |
| [Severity-Based Vulnerability](https://docs.docker.com/scout/policy/#severity-based-vulnerability) | 20     |
| [High-Profile Vulnerabilities](https://docs.docker.com/scout/policy/#high-profile-vulnerabilities) | 20     |
| [Supply Chain Attestations](https://docs.docker.com/scout/policy/#supply-chain-attestations)       | 15     |
| [Approved Base Images](https://docs.docker.com/scout/policy/#approved-base-images)                 | 15     |
| [Up-to-Date Base Images](https://docs.docker.com/scout/policy/#up-to-date-base-images)             | 10     |
| [SonarQube Quality Gates](https://docs.docker.com/scout/policy/#sonarqube-quality-gates) \*        | 10     |
| [Default Non-Root User](https://docs.docker.com/scout/policy/#default-non-root-user)               | 5      |
| [Compliant Licenses](https://docs.docker.com/scout/policy/#compliant-licenses)                     | 5      |

\* *This policy is not enabled by default and must be configured by the user.*

### [Evaluation](#evaluation)

Health scores are calculated for new images pushed to Docker Hub after the feature is enabled. The health scores help you maintain high security standards and ensure your applications are built on secure and reliable images.

### [Repository scores](#repository-scores)

In addition to individual image scores (per tag or digest), each repository receives a health score based on the latest pushed tag, providing an overall view of the repository's security status.

### [Example](#example)

For an image with a total possible score of 100 points:

* If the image only deviates from one policy, worth 5 points, its score will be 95 out of 100. Since this score is above the 90th percentile, the image receives an A health score.
* If the image is non-compliant with more policies and scores 65 out of 100, it receives a C health score, reflecting its lower compliance.

## [Improving your health score](#improving-your-health-score)

To improve the health score of an image, take steps to ensure that the image is compliant with the Docker Scout recommended [policies](https://docs.docker.com/scout/policy/).

1. Go to the [Docker Scout Dashboard](https://scout.docker.com/).
2. Sign in using your Docker ID.
3. Go to [Repository settings](https://scout.docker.com/settings/repos) and enable Docker Scout for your Docker Hub image repositories.
4. Analyze the [policy compliance](https://docs.docker.com/scout/policy/) for your repositories, and take actions to ensure your images are policy-compliant.

Since policies are weighted differently, prioritize the policies with the highest scores for a greater impact on your image's overall score.

----
url: https://docs.docker.com/reference/cli/docker/mcp/client/ls/
----

# docker mcp client ls

***

| Description | List client configurations |
| ----------- | -------------------------- |
| Usage       | `docker mcp client ls`     |

## [Description](#description)

List client configurations

## [Options](#options)

| Option         | Default | Description                                                                          |
| -------------- | ------- | ------------------------------------------------------------------------------------ |
| `-g, --global` |         | Change the system wide configuration or the clients setup in your current git repo.  |
| `--json`       |         | Print as JSON.                                                                       |

----
url: https://docs.docker.com/reference/cli/docker/trust/key/generate/
----

# docker trust key generate

***

| Description | Generate and load a signing key-pair |
| ----------- | ------------------------------------ |
| Usage       | `docker trust key generate NAME`     |

## [Description](#description)

`docker trust key generate` generates a key-pair to be used with signing, and loads the private key into the local Docker trust keystore.

## [Options](#options)

| Option  | Default | Description                                                 |
| ------- | ------- | ----------------------------------------------------------- |
| `--dir` |         | Directory to generate key in, defaults to current directory |

## [Examples](#examples)

### [Generate a key-pair](#generate-a-key-pair)

```console
$ docker trust key generate alice

Generating key for alice...
Enter passphrase for new alice key with ID 17acf3c:
Repeat passphrase for new alice key with ID 17acf3c:
Successfully generated and loaded private key. Corresponding public key available: alice.pub
$ ls
alice.pub
```

The private signing key is encrypted by the passphrase and loaded into the Docker trust keystore. All passphrase requests to sign with the key will be referred to by the provided `NAME`.

The public key component `alice.pub` will be available in the current working directory, and can be used directly by `docker trust signer add`.

Provide the `--dir` argument to specify a directory to generate the key in:

```console
$ docker trust key generate alice --dir /foo

Generating key for alice...
Enter passphrase for new alice key with ID 17acf3c:
Repeat passphrase for new alice key with ID 17acf3c:
Successfully generated and loaded private key. Corresponding public key available: alice.pub
$ ls /foo
alice.pub
```

----
url: https://docs.docker.com/guides/vuejs/develop/
----

# Use containers for Vue.js development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize Vue.js application](https://docs.docker.com/guides/vuejs/containerize/).

***

## [Overview](#overview)

In this section, you'll set up both production and development environments for your Vue.js application using Docker Compose. This approach streamlines your workflow—delivering a lightweight, static site via Nginx in production, and providing a fast, live-reloading dev server with Compose Watch for efficient local development.

You’ll learn how to:

* Configure isolated environments: Set up separate containers optimized for production and development use cases.
* Live-reload in development: Use Compose Watch to automatically sync file changes, enabling real-time updates without manual intervention.
* Preview and debug with ease: Develop inside containers with a seamless preview and debug experience—no rebuilds required after every change.

***

## [Automatically update services (development mode)](#automatically-update-services-development-mode)

Leverage Compose Watch to enable real-time file synchronization between your local machine and the containerized Vue.js development environment. This powerful feature eliminates the need to manually rebuild or restart containers, providing a fast, seamless, and efficient development workflow.

With Compose Watch, your code updates are instantly reflected inside the container—perfect for rapid testing, debugging, and live previewing changes.

## [Step 1: Create a development Dockerfile](#step-1-create-a-development-dockerfile)

Create a file named `Dockerfile.dev` in your project root with the following content:

```dockerfile
# =========================================
# Stage 1: Develop the Vue.js Application
# =========================================
ARG NODE_VERSION=24.12.0-alpine

# Use a lightweight Node.js image for development
FROM node:${NODE_VERSION} AS dev

# Set environment variable to indicate development mode
ENV NODE_ENV=development

# Set the working directory inside the container
WORKDIR /app

# Copy package-related files first to leverage Docker's caching mechanism
COPY package.json package-lock.json* ./

# Install project dependencies
RUN --mount=type=cache,target=/root/.npm npm install

# Copy the rest of the application source code into the container
COPY . .

# Change ownership of the application directory to the node user
RUN chown -R node:node /app

# Switch to the node user
USER node

# Expose the port used by the Vite development server
EXPOSE 5173

# Use a default command, can be overridden in Docker compose.yml file
CMD [ "npm", "run", "dev", "--", "--host" ]
```

This file sets up a lightweight development environment for your Vue.js application using the dev server.

### [Step 2: Update your `compose.yaml` file](#step-2-update-your-composeyaml-file)

Open your `compose.yaml` file and define two services: one for production (`vuejs-prod`) and one for development (`vuejs-dev`).

Here’s an example configuration for an Vue.js application:

```yaml
services:
  vuejs-prod:
    build:
      context: .
      dockerfile: Dockerfile
    image: docker-vuejs-sample
    ports:
      - "8080:8080"

  vuejs-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "5173:5173"
    develop:
      watch:
        - path: ./src
          target: /app/src
          action: sync
        - path: ./package.json
          target: /app/package.json
          action: restart
        - path: ./vite.config.js
          target: /app/vite.config.js
          action: restart
```

* The `vuejs-prod` service builds and serves your static production app using Nginx.
* The `vuejs-dev` service runs your Vue.js development server with live reload and hot module replacement.
* `watch` triggers file sync with Compose Watch.

> Note
>
> For more details, see the official guide: [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

After completing the previous steps, your project directory should now contain the following files:

```text
├── docker-vuejs-sample/
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ ├── .dockerignore
│ ├── compose.yaml
│ └── nginx.conf
```

### [Step 4: Start Compose Watch](#step-4-start-compose-watch)

Run the following command from the project root to start the container in watch mode

```console
$ docker compose watch vuejs-dev
```

### [Step 5: Test Compose Watch with Vue.js](#step-5-test-compose-watch-with-vuejs)

To confirm that Compose Watch is functioning correctly:

1. Open the `src/App.vue` file in your text editor.

2. Locate the following line:

   ```html
   <HelloWorld msg="You did it!" />
   ```

3. Change it to:

   ```html
   <HelloWorld msg="Hello from Docker Compose Watch" />
   ```

4. Save the file.

5. Open your browser at <http://localhost:5173>.

You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected.

***

## [Summary](#summary)

In this section, you set up a complete development and production workflow for your Vue.js application using Docker and Docker Compose.

Here’s what you accomplished:

* Created a `Dockerfile.dev` to streamline local development with hot reloading
* Defined separate `vuejs-dev` and `vuejs-prod` services in your `compose.yaml` file
* Enabled real-time file syncing using Compose Watch for a smoother development experience
* Verified that live updates work seamlessly by modifying and previewing a component

With this setup, you're now equipped to build, run, and iterate on your Vue.js app entirely within containers—efficiently and consistently across environments.

***

In the next section, you'll learn how to run unit tests for your Vue.js application inside Docker containers. This ensures consistent testing across all environments and removes dependencies on local machine setup.

[Run vue.js tests in a container »](https://docs.docker.com/guides/vuejs/run-tests/)

----
url: https://docs.docker.com/security/
----

# Security for developers

***

Table of contents

***

Docker helps you protect your local environments, infrastructure, and networks with its developer-level security features.

Use tools like two-factor authentication (2FA), personal access tokens, and Docker Scout to manage access and detect vulnerabilities early in your workflow. You can also integrate secrets securely into your development stack using Docker Compose, or enhance your software supply security with Docker Hardened Images.

Explore the following sections to learn more.

## [For developers](#for-developers)

### [Set up two-factor authentication](/security/2fa/)

[Add an extra layer of authentication to your Docker account.](/security/2fa/)

### [Manage access tokens](/security/access-tokens/)

[Create personal access tokens as an alternative to your password.](/security/access-tokens/)

### [Static vulnerability scanning](/docker-hub/repos/manage/vulnerability-scanning/)

[Automatically run a point-in-time scan on your Docker images for vulnerabilities.](/docker-hub/repos/manage/vulnerability-scanning/)

### [Docker Engine security](/engine/security/)

[Understand how to keep Docker Engine secure.](/engine/security/)

### [Secrets in Docker Compose](/compose/how-tos/use-secrets/)

[Learn how to use secrets in Docker Compose.](/compose/how-tos/use-secrets/)

## [More resources](#more-resources)

### [Security FAQs](/faq/security/general/)

[Explore common security FAQs.](/faq/security/general/)

### [Security best practices](/develop/security-best-practices/)

[Understand the steps you can take to improve the security of your container.](/develop/security-best-practices/)

### [Suppress CVEs with VEX](/scout/guides/vex/)

[Learn how to suppress non-applicable or fixed vulnerabilities found in your images.](/scout/guides/vex/)

### [Docker Hardened Images](/dhi/)

[Learn how to use Docker Hardened Images to enhance your software supply security.](/dhi/)

----
url: https://docs.docker.com/guides/testcontainers-cloud/
----

# Mastering Testcontainers Cloud by Docker: streamlining integration testing with containers

Table of contents

***

Automate, scale, and optimize testing workflows with Testcontainers Cloud

**Time to complete** 12 minutes

Testcontainers Cloud is a cloud-based solution designed to streamline and enhance the process of running integration tests using Testcontainers. Testcontainers is the open source framework, which allows developers to easily spin up containerized dependencies such as databases, message brokers, and other services required for testing. By shifting the management of Testcontainers-based services to the cloud, Testcontainers Cloud optimizes performance, reduces resource constraints on local machines or CI servers, and ensures consistent test environments. This solution is particularly beneficial for teams working on complex, distributed systems, as it allows for scalable, isolated, and reliable testing without the typical overhead of managing containers locally.

## [What you'll learn](#what-youll-learn)

* Understand the fundamentals of Docker Testcontainers Cloud and its role in integration testing.
* Learn how to set up and configure Docker Testcontainers Cloud for automated testing in various environments.
* Explore how Testcontainers Cloud integrates with CI/CD pipelines to streamline testing workflows.

## [Tools integration](#tools-integration)

Works well with Docker Desktop, GitHub Actions, Jenkins, Kubernetes, and other CI solutions

Docker Pro, Team, and Business subscriptions come with Testcontainers Cloud runtime minutes, and additional minutes are available via consumption pricing. Testcontainers Cloud runtime minutes do not rollover month to month.

## [Who’s this for?](#whos-this-for)

* Teams that build cloud-native applications and are already using Testcontainers open source.
* DevOps Teams that integrate automated container-based testing into CI/CD pipelines for continuous testing.
* QA Teams that seek scalable and consistent test environments for comprehensive integration and end-to-end testing.
* Developers who need reliable, containerized test environments for testing microservices and databases.

## [Modules](#modules)

1. [Why Testcontainers Cloud?](https://docs.docker.com/guides/testcontainers-cloud/why/)

   Learn how Testcontainers Cloud by Docker can help you optimize integration testing.

2. [Setting up Testcontainers Cloud by Docker](https://docs.docker.com/guides/testcontainers-cloud/demo-local/)

   Set up Testcontainers Cloud by Docker in a local development environment.

3. [Configuring Testcontainers Cloud in the CI Pipeline](https://docs.docker.com/guides/testcontainers-cloud/demo-ci/)

   Use Testcontainers Cloud with GitHub Workflows to automate testing in a CI pipeline.

4. [Common challenges and questions](https://docs.docker.com/guides/testcontainers-cloud/common-questions/)

   Explore common challenges and questions related to Testcontainers Cloud by Docker.

----
url: https://docs.docker.com/build/
----

# Docker Build

***

***

Docker Build is one of Docker Engine's most used features. Whenever you are creating an image you are using Docker Build. Build is a key part of your software development life cycle allowing you to package and bundle your code and ship it anywhere.

Docker Build is more than a command for building images, and it's not only about packaging your code. It's a whole ecosystem of tools and features that support not only common workflow tasks but also provides support for more complex and advanced scenarios.

### [Packaging your software](/build/concepts/overview/)

[Build and package your application to run it anywhere: locally or in the cloud.](/build/concepts/overview/)

### [Multi-stage builds](/build/building/multi-stage/)

[Keep your images small and secure with minimal dependencies.](/build/building/multi-stage/)

### [Multi-platform images](/build/building/multi-platform/)

[Build, push, pull, and run images seamlessly on different computer architectures.](/build/building/multi-platform/)

### [BuildKit](/build/buildkit/)

[Explore BuildKit, the open source build engine.](/build/buildkit/)

### [Build drivers](/build/builders/drivers/)

[Configure where and how you run your builds.](/build/builders/drivers/)

### [Exporters](/build/exporters/)

[Export any artifact you like, not just Docker images.](/build/exporters/)

### [Build caching](/build/cache/)

[Avoid unnecessary repetitions of costly operations, such as package installs.](/build/cache/)

### [Bake](/build/bake/)

[Orchestrate your builds with Bake.](/build/bake/)

----
url: https://docs.docker.com/reference/cli/docker/offload/version/
----

# docker offload version

***

| Description | Prints the version                 |
| ----------- | ---------------------------------- |
| Usage       | `docker offload version [OPTIONS]` |

## [Options](#options)

| Option    | Default | Description                |
| --------- | ------- | -------------------------- |
| `--json`  |         | Prints the version as JSON |
| `--short` |         | Prints the short version   |

----
url: https://docs.docker.com/reference/api/extensions-sdk/
----

# Extensions API Reference

***

Table of contents

***

## [Dashboard interfaces](#dashboard-interfaces)

* [Host](https://docs.docker.com/reference/api/extensions-sdk/Host/)
* [NavigationIntents](https://docs.docker.com/reference/api/extensions-sdk/NavigationIntents/)
* [Toast](https://docs.docker.com/reference/api/extensions-sdk/Toast/)

## [Other interfaces](#other-interfaces)

* [ExecResultV0](https://docs.docker.com/reference/api/extensions-sdk/ExecResultV0/)
* [RequestConfigV0](https://docs.docker.com/reference/api/extensions-sdk/RequestConfigV0/)
* [BackendV0](https://docs.docker.com/reference/api/extensions-sdk/BackendV0/)
* [OpenDialogResult](https://docs.docker.com/reference/api/extensions-sdk/OpenDialogResult/)
* [Dialog](https://docs.docker.com/reference/api/extensions-sdk/Dialog/)
* [Docker](https://docs.docker.com/reference/api/extensions-sdk/Docker/)
* [DockerCommand](https://docs.docker.com/reference/api/extensions-sdk/DockerCommand/)
* [ExecOptions](https://docs.docker.com/reference/api/extensions-sdk/ExecOptions/)
* [SpawnOptions](https://docs.docker.com/reference/api/extensions-sdk/SpawnOptions/)
* [Exec](https://docs.docker.com/reference/api/extensions-sdk/Exec/)
* [ExecProcess](https://docs.docker.com/reference/api/extensions-sdk/ExecProcess/)
* [ExecStreamOptions](https://docs.docker.com/reference/api/extensions-sdk/ExecStreamOptions/)
* [ExecResult](https://docs.docker.com/reference/api/extensions-sdk/ExecResult/)
* [RawExecResult](https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/)
* [Extension](https://docs.docker.com/reference/api/extensions-sdk/Extension/)
* [DesktopUI](https://docs.docker.com/reference/api/extensions-sdk/DesktopUI/)
* [ExtensionVM](https://docs.docker.com/reference/api/extensions-sdk/ExtensionVM/)
* [ExtensionHost](https://docs.docker.com/reference/api/extensions-sdk/ExtensionHost/)
* [ExtensionCli](https://docs.docker.com/reference/api/extensions-sdk/ExtensionCli/)
* [HttpService](https://docs.docker.com/reference/api/extensions-sdk/HttpService/)
* [RequestConfig](https://docs.docker.com/reference/api/extensions-sdk/RequestConfig/)
* [ServiceError](https://docs.docker.com/reference/api/extensions-sdk/ServiceError/)
* [DockerDesktopClient](https://docs.docker.com/reference/api/extensions-sdk/DockerDesktopClient/)

----
url: https://docs.docker.com/build/ci/github-actions/github-builder/
----

# Docker GitHub Builder

***

***

Docker GitHub Builder is a set of [reusable workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows) in the [`docker/github-builder` repository](https://github.com/docker/github-builder) for building container images and local artifacts with [BuildKit](https://docs.docker.com/build/buildkit/). This section explains what the workflows solve, how they differ from wiring together individual GitHub Actions in each repository, and when to use [`build.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/build/) or [`bake.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/bake/).

If you compose a build job from `docker/login-action`, `docker/setup-buildx-action`, `docker/metadata-action`, and either `docker/build-push-action` or `docker/bake-action`, your repository owns every detail of how the build runs. That approach works, but it also means every repository has to maintain its own runner selection, [cache setup](https://docs.docker.com/build/ci/github-actions/cache/), [Provenance settings](https://docs.docker.com/build/ci/github-actions/attestations/), signing behavior, and [multi-platform manifest handling](https://docs.docker.com/build/ci/github-actions/multi-platform/). Docker GitHub Builder moves that implementation into Docker-maintained reusable workflows, so your workflow only decides when to build and which inputs to pass.

The difference is easiest to see in the job definition. A conventional workflow spells out each action step:

```yaml
jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        
      - name: Docker meta
        uses: docker/metadata-action@v6
        id: meta
        with:
          images: name/app

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha
```

With Docker GitHub Builder, the same build is a reusable workflow call:

```yaml
jobs:
  build:
    uses: docker/github-builder/.github/workflows/build.yml@v1
    permissions:
      contents: read # to fetch the repository content
      id-token: write # for signing attestation(s) with GitHub OIDC Token
    with:
      output: image
      push: ${{ github.event_name != 'pull_request' }}
      meta-images: name/app
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
```

This model gives you a build pipeline that is maintained in the Docker organization, uses a pinned [BuildKit](https://docs.docker.com/build/buildkit/) environment, distributes [multi-platform builds](https://docs.docker.com/build/building/multi-platform/) across runners when that helps, and emits signed [SLSA provenance](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) that records both the source commit and the builder identity.

That tradeoff is intentional. You keep control of when the build runs and which inputs it uses, but the build implementation itself lives in the Docker-maintained workflow rather than in per-repository job steps.

Use [`build.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/build/) when your repository builds from a Dockerfile and the familiar `build-push-action` inputs map cleanly to your workflow. Use [`bake.yml`](https://docs.docker.com/build/ci/github-actions/github-builder/bake/) when your repository already describes builds in a [Bake definition](https://docs.docker.com/build/bake/), or when you want Bake targets, overrides, and variables to stay as the source of truth.

Both workflows support image output, local output, cache export to the [GitHub Actions cache backend](https://docs.docker.com/build/cache/backends/gha/), [SBOM generation](https://docs.docker.com/build/metadata/attestations/sbom/), and signing. The Bake workflow adds Bake definition validation and builds one target per workflow call.

* [Docker GitHub Builder architecture](/build/ci/github-actions/github-builder/architecture/)

* [Build with Docker GitHub Builder](/build/ci/github-actions/github-builder/build/)

* [Bake with Docker GitHub Builder](/build/ci/github-actions/github-builder/bake/)

----
url: https://docs.docker.com/reference/cli/docker/swarm/ca/
----

# docker swarm ca

***

| Description | Display and rotate the root CA |
| ----------- | ------------------------------ |
| Usage       | `docker swarm ca [OPTIONS]`    |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

View or rotate the current swarm CA certificate.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default     | Description                                                                              |
| ------------------------- | ----------- | ---------------------------------------------------------------------------------------- |
| `--ca-cert`               |             | Path to the PEM-formatted root CA certificate to use for the new cluster                 |
| `--ca-key`                |             | Path to the PEM-formatted root CA key to use for the new cluster                         |
| `--cert-expiry`           | `2160h0m0s` | Validity period for node certificates (ns\|us\|ms\|s\|m\|h)                              |
| [`-d, --detach`](#detach) |             | Exit immediately instead of waiting for the root rotation to converge                    |
| `--external-ca`           |             | Specifications of one or more certificate signing endpoints                              |
| `-q, --quiet`             |             | Suppress progress output                                                                 |
| [`--rotate`](#rotate)     |             | Rotate the swarm CA - if no certificate or key are provided, new ones will be generated  |

## [Examples](#examples)

Run the `docker swarm ca` command without any options to view the current root CA certificate in PEM format.

```console
$ docker swarm ca

-----BEGIN CERTIFICATE-----
MIIBazCCARCgAwIBAgIUJPzo67QC7g8Ebg2ansjkZ8CbmaswCgYIKoZIzj0EAwIw
EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAzMTcxMDAwWhcNMzcwNDI4MTcx
MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
A0IABKL6/C0sihYEb935wVPRA8MqzPLn3jzou0OJRXHsCLcVExigrMdgmLCC+Va4
+sJ+SLVO1eQbvLHH8uuDdF/QOU6jQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
Af8EBTADAQH/MB0GA1UdDgQWBBSfUy5bjUnBAx/B0GkOBKp91XvxzjAKBggqhkjO
PQQDAgNJADBGAiEAnbvh0puOS5R/qvy1PMHY1iksYKh2acsGLtL/jAIvO4ACIQCi
lIwQqLkJ48SQqCjG1DBTSBsHmMSRT+6mE2My+Z3GKA==
-----END CERTIFICATE-----
```

Pass the `--rotate` flag (and optionally a `--ca-cert`, along with a `--ca-key` or `--external-ca` parameter flag), in order to rotate the current swarm root CA.

```console
$ docker swarm ca --rotate
desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e
  rotated TLS certificates:  [=========================>                         ] 1/2 nodes
  rotated CA certificates:   [>                                                  ] 0/2 nodes
```

Once the rotation is finished (all the progress bars have completed) the now-current CA certificate will be printed:

```console
$ docker swarm ca --rotate
desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e
  rotated TLS certificates:  [==================================================>] 2/2 nodes
  rotated CA certificates:   [==================================================>] 2/2 nodes
-----BEGIN CERTIFICATE-----
MIIBazCCARCgAwIBAgIUFynG04h5Rrl4lKyA4/E65tYKg8IwCgYIKoZIzj0EAwIw
EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTE2MDAxMDAwWhcNMzcwNTExMDAx
MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
A0IABC2DuNrIETP7C7lfiEPk39tWaaU0I2RumUP4fX4+3m+87j0DU0CsemUaaOG6
+PxHhGu2VXQ4c9pctPHgf7vWeVajQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
Af8EBTADAQH/MB0GA1UdDgQWBBSEL02z6mCI3SmMDmITMr12qCRY2jAKBggqhkjO
PQQDAgNJADBGAiEA263Eb52+825EeNQZM0AME+aoH1319Zp9/J5ijILW+6ACIQCg
gyg5u9Iliel99l7SuMhNeLkrU7fXs+Of1nTyyM73ig==
-----END CERTIFICATE-----
```

### [Root CA rotation (--rotate)](#rotate)

> Note
>
> Mirantis Kubernetes Engine (MKE), formerly known as Docker UCP, provides an external certificate manager service for the swarm. If you run swarm on MKE, you shouldn't rotate the CA certificates manually. Instead, contact Mirantis support if you need to rotate a certificate.

Root CA Rotation is recommended if one or more of the swarm managers have been compromised, so that those managers can no longer connect to or be trusted by any other node in the cluster.

Alternately, root CA rotation can be used to give control of the swarm CA to an external CA, or to take control back from an external CA.

The `--rotate` flag does not require any parameters to do a rotation, but you can optionally specify a certificate and key, or a certificate and external CA URL, and those will be used instead of an automatically-generated certificate/key pair.

Because the root CA key should be kept secret, if provided it will not be visible when viewing swarm any information via the CLI or API.

The root CA rotation will not be completed until all registered nodes have rotated their TLS certificates. If the rotation is not completing within a reasonable amount of time, try running `docker node ls --format '{{.ID}} {{.Hostname}} {{.Status}} {{.TLSStatus}}'` to see if any nodes are down or otherwise unable to rotate TLS certificates.

### [Run root CA rotation in detached mode (--detach)](#detach)

Initiate the root CA rotation, but do not wait for the completion of or display the progress of the rotation.

----
url: https://docs.docker.com/guides/testcontainers-java-keycloak-spring-boot/write-tests/
----

# Write tests with Testcontainers

***

Table of contents

***

To test the secured API endpoints, you need a running Keycloak instance and a PostgreSQL database, plus a started Spring context. Testcontainers spins up both services in Docker containers and connects them to Spring through dynamic property registration.

## [Configure the test containers](#configure-the-test-containers)

Spring Boot's Testcontainers support lets you declare containers as beans. For Keycloak, `@ServiceConnection` isn't available, but you can use `DynamicPropertyRegistry` to set the JWT issuer URI dynamically.

Create `ContainersConfig.java` under `src/test/java`:

```java
package com.testcontainers.products;

import dasniko.testcontainers.keycloak.KeycloakContainer;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.testcontainers.postgresql.PostgreSQLContainer;

@TestConfiguration(proxyBeanMethods = false)
public class ContainersConfig {

  static String POSTGRES_IMAGE = "postgres:16-alpine";
  static String KEYCLOAK_IMAGE = "quay.io/keycloak/keycloak:25.0";
  static String realmImportFile = "/keycloaktcdemo-realm.json";
  static String realmName = "keycloaktcdemo";

  @Bean
  @ServiceConnection
  PostgreSQLContainer postgres() {
    return new PostgreSQLContainer(POSTGRES_IMAGE);
  }

  @Bean
  KeycloakContainer keycloak(DynamicPropertyRegistry registry) {
    var keycloak = new KeycloakContainer(KEYCLOAK_IMAGE)
      .withRealmImportFile(realmImportFile);
    registry.add(
      "spring.security.oauth2.resourceserver.jwt.issuer-uri",
      () -> keycloak.getAuthServerUrl() + "/realms/" + realmName
    );
    return keycloak;
  }
}
```

This configuration:

* Declares a `PostgreSQLContainer` bean with `@ServiceConnection`, which starts a PostgreSQL container and automatically registers the datasource properties.
* Declares a `KeycloakContainer` bean using the `quay.io/keycloak/keycloak:25.0` image, imports the realm configuration file, and dynamically registers the JWT issuer URI from the Keycloak container's auth server URL.

## [Write the test](#write-the-test)

Create `ProductControllerTests.java`:

```java
package com.testcontainers.products.api;

import static io.restassured.RestAssured.given;
import static io.restassured.RestAssured.when;
import static java.util.Collections.singletonList;
import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT;

import com.fasterxml.jackson.annotation.JsonProperty;
import com.testcontainers.products.ContainersConfig;
import io.restassured.RestAssured;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.security.oauth2.resource.OAuth2ResourceServerProperties;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.server.LocalServerPort;
import org.springframework.context.annotation.Import;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.client.RestTemplate;

@SpringBootTest(webEnvironment = RANDOM_PORT)
@Import(ContainersConfig.class)
class ProductControllerTests {

  static final String GRANT_TYPE_CLIENT_CREDENTIALS = "client_credentials";
  static final String CLIENT_ID = "product-service";
  static final String CLIENT_SECRET = "jTJJqdzeCSt3DmypfHZa42vX8U9rQKZ9";

  @LocalServerPort
  private int port;

  @Autowired
  OAuth2ResourceServerProperties oAuth2ResourceServerProperties;

  @BeforeEach
  void setup() {
    RestAssured.port = port;
  }

  @Test
  void shouldGetProductsWithoutAuthToken() {
    when().get("/api/products").then().statusCode(200);
  }

  @Test
  void shouldGetUnauthorizedWhenCreateProductWithoutAuthToken() {
    given()
      .contentType("application/json")
      .body(
        """
            {
                "title": "New Product",
                "description": "Brand New Product"
            }
        """
      )
      .when()
      .post("/api/products")
      .then()
      .statusCode(401);
  }

  @Test
  void shouldCreateProductWithAuthToken() {
    String token = getToken();

    given()
      .header("Authorization", "Bearer " + token)
      .contentType("application/json")
      .body(
        """
            {
                "title": "New Product",
                "description": "Brand New Product"
            }
        """
      )
      .when()
      .post("/api/products")
      .then()
      .statusCode(201);
  }

  private String getToken() {
    RestTemplate restTemplate = new RestTemplate();
    HttpHeaders httpHeaders = new HttpHeaders();
    httpHeaders.setContentType(MediaType.APPLICATION_FORM_URLENCODED);

    MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
    map.put("grant_type", singletonList(GRANT_TYPE_CLIENT_CREDENTIALS));
    map.put("client_id", singletonList(CLIENT_ID));
    map.put("client_secret", singletonList(CLIENT_SECRET));

    String authServerUrl =
      oAuth2ResourceServerProperties.getJwt().getIssuerUri() +
      "/protocol/openid-connect/token";

    var request = new HttpEntity<>(map, httpHeaders);
    KeyCloakToken token = restTemplate.postForObject(
      authServerUrl,
      request,
      KeyCloakToken.class
    );

    assert token != null;
    return token.accessToken();
  }

  record KeyCloakToken(@JsonProperty("access_token") String accessToken) {}
}
```

Here's what the tests cover:

* `shouldGetProductsWithoutAuthToken()` invokes `GET /api/products` without an `Authorization` header. Because this endpoint is configured to permit unauthenticated access, the response status code is 200.
* `shouldGetUnauthorizedWhenCreateProductWithoutAuthToken()` invokes the secured `POST /api/products` endpoint without an `Authorization` header and asserts the response status code is 401 (Unauthorized).
* `shouldCreateProductWithAuthToken()` first obtains an `access_token` using the Client Credentials flow. It then includes the token as a Bearer token in the `Authorization` header when invoking `POST /api/products` and asserts the response status code is 201 (Created).

The `getToken()` helper method requests an access token from the Keycloak token endpoint using the client ID and client secret that were configured in the exported realm.

## [Use Testcontainers for local development](#use-testcontainers-for-local-development)

Spring Boot's Testcontainers support also works for local development. Create `TestApplication.java` under `src/test/java`:

```java
package com.testcontainers.products;

import org.springframework.boot.SpringApplication;

public class TestApplication {

  public static void main(String[] args) {
    SpringApplication
      .from(Application::main)
      .with(ContainersConfig.class)
      .run(args);
  }
}
```

Run `TestApplication.java` from your IDE instead of the main `Application.java`. It starts the containers defined in `ContainersConfig` and configures the application to use the dynamically registered properties, so you don't have to install or configure PostgreSQL and Keycloak manually.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-keycloak-spring-boot/run-tests/)

----
url: https://docs.docker.com/reference/cli/docker/compose/ps/
----

# docker compose ps

***

| Description | List containers                            |
| ----------- | ------------------------------------------ |
| Usage       | `docker compose ps [OPTIONS] [SERVICE...]` |

## [Description](#description)

Lists containers for a Compose project, with current status and exposed ports.

```console
$ docker compose ps
NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
```

By default, only running containers are shown. `--all` flag can be used to include stopped containers.

```console
$ docker compose ps --all
NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
example-bar-1   alpine    "/entrypoint.…"   bar        4 seconds ago   exited (0)
```

## [Options](#options)

| Option                | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-a, --all`           |         | Show all stopped containers (including those created by the run command)                                                                                                                                                                                                                                                                                                               |
| [`--filter`](#filter) |         | Filter services by a property (supported filters: status)                                                                                                                                                                                                                                                                                                                              |
| [`--format`](#format) | `table` | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `--no-trunc`          |         | Don't truncate output                                                                                                                                                                                                                                                                                                                                                                  |
| `--orphans`           | `true`  | Include orphaned services (not declared by project)                                                                                                                                                                                                                                                                                                                                    |
| `-q, --quiet`         |         | Only display IDs                                                                                                                                                                                                                                                                                                                                                                       |
| `--services`          |         | Display services                                                                                                                                                                                                                                                                                                                                                                       |
| [`--status`](#status) |         | Filter services by status. Values: \[paused \| restarting \| removing \| running \| dead \| created \| exited]                                                                                                                                                                                                                                                                         |

## [Examples](#examples)

### [Format the output (--format)](#format)

By default, the `docker compose ps` command uses a table ("pretty") format to show the containers. The `--format` flag allows you to specify alternative presentations for the output. Currently, supported options are `pretty` (default), and `json`, which outputs information about the containers as a JSON array:

```console
$ docker compose ps --format json
[{"ID":"1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a","Name":"example-bar-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"bar","State":"exited","Health":"","ExitCode":0,"Publishers":null},{"ID":"f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0","Name":"example-foo-1","Command":"/docker-entrypoint.sh nginx -g 'daemon off;'","Project":"example","Service":"foo","State":"running","Health":"","ExitCode":0,"Publishers":[{"URL":"0.0.0.0","TargetPort":80,"PublishedPort":8080,"Protocol":"tcp"}]}]
```

The JSON output allows you to use the information in other tools for further processing, for example, using the [`jq` utility](https://stedolan.github.io/jq/) to pretty-print the JSON:

```console
$ docker compose ps --format json | jq .
[
  {
    "ID": "1553b0236cf4d2715845f053a4ee97042c4f9a2ef655731ee34f1f7940eaa41a",
    "Name": "example-bar-1",
    "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
    "Project": "example",
    "Service": "bar",
    "State": "exited",
    "Health": "",
    "ExitCode": 0,
    "Publishers": null
  },
  {
    "ID": "f02a4efaabb67416e1ff127d51c4b5578634a0ad5743bd65225ff7d1909a3fa0",
    "Name": "example-foo-1",
    "Command": "/docker-entrypoint.sh nginx -g 'daemon off;'",
    "Project": "example",
    "Service": "foo",
    "State": "running",
    "Health": "",
    "ExitCode": 0,
    "Publishers": [
      {
        "URL": "0.0.0.0",
        "TargetPort": 80,
        "PublishedPort": 8080,
        "Protocol": "tcp"
      }
    ]
  }
]
```

### [Filter containers by status (--status)](#status)

Use the `--status` flag to filter the list of containers by status. For example, to show only containers that are running or only containers that have exited:

```console
$ docker compose ps --status=running
NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp

$ docker compose ps --status=exited
NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
example-bar-1   alpine    "/entrypoint.…"   bar        4 seconds ago   exited (0)
```

### [Filter containers by status (--filter)](#filter)

The [`--status` flag](#status) is a convenient shorthand for the `--filter status=<status>` flag. The example below is the equivalent to the example from the previous section, this time using the `--filter` flag:

```console
$ docker compose ps --filter status=running
NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
```

The `docker compose ps` command currently only supports the `--filter status=<status>` option, but additional filter options may be added in the future.

----
url: https://docs.docker.com/reference/cli/docker/compose/ls/
----

# docker compose ls

***

| Description | List running compose projects |
| ----------- | ----------------------------- |
| Usage       | `docker compose ls [OPTIONS]` |

## [Description](#description)

Lists running Compose projects

## [Options](#options)

| Option        | Default | Description                                 |
| ------------- | ------- | ------------------------------------------- |
| `-a, --all`   |         | Show all stopped Compose projects           |
| `--filter`    |         | Filter output based on conditions provided  |
| `--format`    | `table` | Format the output. Values: \[table \| json] |
| `-q, --quiet` |         | Only display project names                  |

----
url: https://docs.docker.com/reference/cli/sbx/policy/rm/
----

# sbx policy rm

| Description | Remove a policy rule    |
| ----------- | ----------------------- |
| Usage       | `sbx policy rm COMMAND` |

## [Description](#description)

Remove a previously added allow or deny rule.

## [Commands](#commands)

| Command                                                                                 | Description           |
| --------------------------------------------------------------------------------------- | --------------------- |
| [`sbx policy rm network`](https://docs.docker.com/reference/cli/sbx/policy/rm/network/) | Remove a network rule |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/guides/rag-ollama/
----

# Build a RAG application using Ollama and Docker

***

This guide demonstrates how to use Docker to deploy Retrieval-Augmented Generation (RAG) models with Ollama.

**Time to complete** 20 minutes

The Retrieval Augmented Generation (RAG) guide teaches you how to containerize an existing RAG application using Docker. The example application is a RAG that acts like a sommelier, giving you the best pairings between wines and food. In this guide, you’ll learn how to:

* Containerize and run a RAG application
* Set up a local environment to run the complete RAG stack locally for development

Start by containerizing an existing RAG application.

## [Modules](#modules)

1. [Containerize your app](https://docs.docker.com/guides/rag-ollama/containerize/)

   Learn how to containerize a RAG application.

2. [Develop your app](https://docs.docker.com/guides/rag-ollama/develop/)

   Learn how to develop your generative RAG application locally.

----
url: https://docs.docker.com/engine/release-notes/29/
----

# Docker Engine version 29 release notes

***

Table of contents

***

This page describes the latest changes, additions, known issues, and fixes for Docker Engine version 29.

For more information about:

* Deprecated and removed features, see [Deprecated Engine Features](https://docs.docker.com/engine/deprecated/).
* Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history/).

## [29.5.2](#2952)

*2026-05-20*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.5.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.5.2)
* [moby/moby, 29.5.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.5.2)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* Fix a regression introduced in 29.5.1 where `docker cp` failed with "mkdirat: file exists" when a container had a bind mount whose target traversed an in-container symlink (e.g. `/var/run -> /run`). [moby/moby#52655](https://github.com/moby/moby/pull/52655)

## [29.5.1](#2951)

*2026-05-18*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.5.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.5.1)
* [moby/moby, 29.5.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.5.1)

### [Security](#security)

This release includes fixes for multiple security vulnerabilities affecting Docker Engine.

* **CVE-2026-41567** Fix a vulnerability in `docker cp` where archive decompression binaries (e.g. `xz`, `unpigz`) were resolved via `PATH` inside the container filesystem while running as host root, allowing a malicious container to execute arbitrary binaries with host root privileges.\
  [GHSA-x86f-5xw2-fm2r](https://github.com/moby/moby/security/advisories/GHSA-x86f-5xw2-fm2r)

* **CVE-2026-41568** Fix a TOCTOU vulnerability in `docker cp` that allowed a container process to create files or directories at arbitrary locations on the host filesystem.\
  [GHSA-vp62-88p7-qqf5](https://github.com/moby/moby/security/advisories/GHSA-vp62-88p7-qqf5)

* **CVE-2026-42306** Fix a TOCTOU vulnerability in `docker cp` that allowed a container process to redirect a bind mount to an arbitrary location on the host filesystem.\
  [GHSA-rg2x-37c3-w2rh](https://github.com/moby/moby/security/advisories/GHSA-rg2x-37c3-w2rh)

### [Networking](#networking)

* Fix UDP conntrack entries not being deleted when not bound to a specific IP address. [moby/moby#52640](https://github.com/moby/moby/pull/52640)

## [29.5.0](#2950)

*2026-05-14*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.5.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.5.0)
* [moby/moby, 29.5.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.5.0)

> Note
>
> Rootless: `gvisor-tap-vsock` is now the new default rootless network driver and should be preferred over `slirp4netns` which is no longer installed via Docker packaging.

### [New](#new)

* Rootless: Add new default `gvisor-tap-vsock` network driver. [moby/moby#52319](https://github.com/moby/moby/pull/52319)
* Enable private time namespace for containers by default on supported kernels. [moby/moby#52326](https://github.com/moby/moby/pull/52326)
* The `local` logging driver now has support for custom attributes, adding support for the `label`, `label-regex`, `env`, `env-regex`, and `tag` log options. [moby/moby#52348](https://github.com/moby/moby/pull/52348)
* Windows: The daemon now supports listening on a Unix socket (`-H unix://...`), with optional group-based access control via `--group`. [moby/moby#52365](https://github.com/moby/moby/pull/52365)

### [Security](#security-1)

* CVE-2026-32288: Fix a denial of service where pulling a maliciously crafted image could cause the daemon to allocate unbounded memory when processing sparse tar archives. [GHSA-x4jj-h2v8-hqqv](https://github.com/advisories/GHSA-x4jj-h2v8-hqqv). [moby/moby#52478](https://github.com/moby/moby/pull/52478)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

* `docker ps --format` now supports a `.HealthStatus` placeholder to print container health state (`starting`, `healthy`, `unhealthy`) as a dedicated field. [docker/cli#6913](https://github.com/docker/cli/pull/6913)
* Add "time-namespaces" feature flag to disable time-namespaces. [moby/moby#52577](https://github.com/moby/moby/pull/52577)
* containerd integration: Fix auth token requests ignoring per-host TLS settings (custom CAs, insecure-registries). [moby/moby#52600](https://github.com/moby/moby/pull/52600)
* Daemon reload events now signify that the daemon reload has fully completed. [moby/moby#52589](https://github.com/moby/moby/pull/52589)
* Expose diagnostic data about userland proxy in `docker info`. [moby/moby#52321](https://github.com/moby/moby/pull/52321)
* Fix `docker image ls --filter reference=...` (`GET /images/json`) to also match fully qualified canonical image names (e.g. `docker.io/library/alpine`), not only the familiar short form. [moby/moby#52333](https://github.com/moby/moby/pull/52333)
* Fix a bug where leaving an autolock-enabled swarm could leave orphaned state, causing subsequent swarm init to fail with "Swarm is encrypted and needs to be unlocked". [moby/moby#52479](https://github.com/moby/moby/pull/52479)
* Fix an issue where logging errors appeared as empty strings in the daemon log instead of the message that failed to write. [moby/moby#52442](https://github.com/moby/moby/pull/52442)
* Fix incorrect SHARED SIZE and UNIQUE SIZE reporting in `docker system df -v` by including shared content blobs in size calculation. [moby/moby#52482](https://github.com/moby/moby/pull/52482)
* Fix support for CDI specifications that request additional group IDs. [moby/moby#52579](https://github.com/moby/moby/pull/52579)
* Fix volume subpath file mounts over an existing file in the image failing container creation with "not a directory". [moby/moby#52584](https://github.com/moby/moby/pull/52584)
* Sort labels in `volume`, `network`, `config`, and `secret` formatters for deterministic output. [docker/cli#6954](https://github.com/docker/cli/pull/6954)
* Swarm: Prevent corruption of Raft snapshots when swarm state is large. [moby/moby#52441](https://github.com/moby/moby/pull/52441)

### [Packaging updates](#packaging-updates)

* Update BuildKit to [v0.30.0](https://github.com/moby/buildkit/releases/tag/v0.30.0). [moby/moby#52618](https://github.com/moby/moby/pull/52618)
* Update Go runtime to [1.26.3](https://go.dev/doc/devel/release#go1.26.3). [moby/moby#52572](https://github.com/moby/moby/pull/52572), [docker/cli#6967](https://github.com/docker/cli/pull/6967)

### [Networking](#networking-1)

* Fix conntrack entries being incorrectly deleted for UDP containers sharing the same port on different IPs when one container is restarted. [moby/moby#52423](https://github.com/moby/moby/pull/52423)
* Fix stale VIP DNS records for swarm service network aliases not being removed during rolling updates. [moby/moby#52236](https://github.com/moby/moby/pull/52236)
* Fix the userland proxy silently dropping UDP datagrams when a previous write to an unavailable backend left a stale ECONNREFUSED error on the socket. [moby/moby#52483](https://github.com/moby/moby/pull/52483)
* Rootless: Properly support `--net=host` and localhost registries. [moby/moby#47103](https://github.com/moby/moby/pull/47103)

### [Rootless](#rootless)

* Update RootlessKit to [v3.0.0](https://github.com/rootless-containers/rootlesskit/releases/tag/v3.0.0). [moby/moby#52319](https://github.com/moby/moby/pull/52319)

### [Go SDK](#go-sdk)

* cli/config/configfile: `GetAuthConfig`, `GetCredentialsStore`: normalize hostname when resolving auth. [docker/cli#6846](https://github.com/docker/cli/pull/6846)

### [Deprecations](#deprecations)

* cli/command/image/build: remove deprecated `DefaultDockerfileName` const. [docker/cli#6737](https://github.com/docker/cli/pull/6737)
* cli/command/image/build: remove deprecated `DetectArchiveReader` util. [docker/cli#6737](https://github.com/docker/cli/pull/6737)
* cli/command/image/build: remove deprecated `IsArchive` utility. [docker/cli#6737](https://github.com/docker/cli/pull/6737)
* cli/command/image/build: remove deprecated `ResolveAndValidateContextPath` util. [docker/cli#6737](https://github.com/docker/cli/pull/6737)
* cli/command/image/build: remove deprecated `WriteTempDockerfile` util. [docker/cli#6737](https://github.com/docker/cli/pull/6737)

## [29.4.3](#2943)

*2026-05-06*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.4.3 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.4.3)
* [moby/moby, 29.4.3 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.4.3)

### [Security](#security-2)

* **CVE-2026-31431**: Replace the socketcall(2) seccomp deny that broke 32-bit programs with targeted AppArmor (deny network alg) and SELinux (alg\_socket) rules that block AF\_ALG at the LSM layer, covering both socket(2) and socketcall(2) paths without disrupting legitimate 32-bit workloads. [moby/moby#52537](https://github.com/moby/moby/pull/52537)

  On SELinux-based systems, the SELinux mitigation requires the daemon to be configured with `selinux-enabled: true` (via `daemon.json` or the `--selinux-enabled` CLI flag). This option is not enabled by default.

* Fix the default AppArmor profile not being updated on daemon restart, requiring a system reboot to pick up profile changes from daemon upgrades. [moby/moby#52537](https://github.com/moby/moby/pull/52537)

## [29.4.2](#2942)

*2026-05-01*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.4.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.4.2)
* [moby/moby, 29.4.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.4.2)

### [Security](#security-3)

This release includes hardening for **CVE-2026-31431**.

* Block `AF_ALG` sockets and the `socketcall(2)` multiplexer in the default seccomp profile to prevent in-container privilege escalation via the kernel crypto API ("Copy Fail"). [moby/moby#52501](https://github.com/moby/moby/pull/52501)

### [Known issues](#known-issues)

The hardening can break 32-bit programs and i386 images, including SteamCMD and some Wine-based workloads. [moby/moby#52506](https://github.com/moby/moby/issues/52506)

#### [Workaround](#workaround)

> Warning
>
> Don't use `--security-opt seccomp=unconfined` to work around this issue.\
> Don't use the `seccomp/v0.2.0` profile.

If you need a workaround, use the `seccomp/v0.2.1` profile from `moby/profiles`. Make sure you use a kernel that includes the fix for CVE-2026-31431.

This profile unblocks `socketcall` while keeping `AF_ALG` blocked for `socket`.

> Important
>
> Use this workaround only for containers that require it.\
> Containers that use this profile can still exploit CVE-2026-31431 through the `socketcall` syscall.

Download the `seccomp/v0.2.1` profile:

```console
$ curl -fsSL https://raw.githubusercontent.com/moby/profiles/refs/tags/seccomp/v0.2.1/seccomp/default.json \
  -o /etc/docker/seccomp-profile-v0.2.1.json
```

Use one of these options. You don't need both.

1. To use the profile for a specific container when you control the `docker run` command, use `--security-opt`:

```console
$ docker run --security-opt seccomp=<path> ...
```

2. To use the profile as the default for containers created by the daemon, add `seccomp-profile` to your `daemon.json`:

```json
{
  "seccomp-profile": "/etc/docker/seccomp-profile-v0.2.1.json"
}
```

## [29.4.1](#2941)

*2026-04-20*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.4.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.4.1)
* [moby/moby, 29.4.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.4.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

* containerd image store: Fix `docker image prune --filter label!=key=value` incorrectly skipping images that don't have the specified label. [moby/moby#52338](https://github.com/moby/moby/pull/52338)
* Fix `--log-opt "tag={{.ImageID}}"` not stripping the digest's algorithm. [moby/moby#52343](https://github.com/moby/moby/pull/52343)
* Fix intermittent container start failures (`EBUSY` on secrets/configs remount) on busy Swarm nodes by retrying the read-only remount. [moby/moby#52235](https://github.com/moby/moby/pull/52235)

### [Packaging updates](#packaging-updates-1)

* Update containerd (static binaries only) to [v2.2.3](https://github.com/containerd/containerd/releases/tag/v2.2.3). [moby/moby#52360](https://github.com/moby/moby/pull/52360)
* Update Go runtime to [1.26.2](https://go.dev/doc/devel/release#go1.26.2). [docker/cli#6920](https://github.com/docker/cli/pull/6920), [moby/moby#52329](https://github.com/moby/moby/pull/52329)

### [Networking](#networking-2)

* if a container has an IPv4-only or an IPv6-only endpoint with higher "gateway priority" than a dual stack endpoint, the single stack endpoint will now be used as the default gateway for its address family. [moby/moby#52328](https://github.com/moby/moby/pull/52328)

## [29.4.0](#2940)

*2026-04-07*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.4.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.4.0)
* [moby/moby, 29.4.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.4.0)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-3)

* docker cp: report both content size and transferred size. [docker/cli#6800](https://github.com/docker/cli/pull/6800)
* Fix `docker stats --all` still showing containers that were removed. [docker/cli#6863](https://github.com/docker/cli/pull/6863)
* Fix a rare bug that could cause containers to become unremovable. [moby/moby#51724](https://github.com/moby/moby/pull/51724)
* Fixed privileged containers losing their explicit AppArmor profile (`--security-opt apparmor=<profile>`) after a container restart. [moby/moby#52215](https://github.com/moby/moby/pull/52215)
* Improved duplicate container-exit handling by using live containerd task state (not timestamps). [moby/moby#52156](https://github.com/moby/moby/pull/52156)
* Improved image pull and push performance by enabling HTTP keep-alive for registry connections, avoiding redundant TCP and TLS handshakes. [moby/moby#52198](https://github.com/moby/moby/pull/52198)
* shell completions: add shell completion for `docker rm --link` and exclude legacy links for container names. [docker/cli#6872](https://github.com/docker/cli/pull/6872)
* shell completions: don't provide completions that were already used. [docker/cli#6871](https://github.com/docker/cli/pull/6871)
* Update runc (in static binaries) to [v1.3.5](https://github.com/opencontainers/runc/releases/tag/v1.3.5). [moby/moby#52244](https://github.com/moby/moby/pull/52244)
* Windows: Fix `DOCKER_TMPDIR` not being respected. [moby/moby#52181](https://github.com/moby/moby/pull/52181)

### [Packaging updates](#packaging-updates-2)

* Update BuildKit to [v0.29.0](https://github.com/moby/buildkit/releases/tag/v0.29.0). [moby/moby#52272](https://github.com/moby/moby/pull/52272)

### [Networking](#networking-3)

* Prevent a daemon crash during startup after upgrading if a container config containers a malformed IP-address. [moby/moby#52275](https://github.com/moby/moby/pull/52275)

### [Go SDK](#go-sdk-1)

* cli/streams: Out, In: preserve original os.File when available. [docker/cli#6906](https://github.com/docker/cli/pull/6906)
* Update minimum go version to go1.25. [docker/cli#6897](https://github.com/docker/cli/pull/6897)

### [Deprecations](#deprecations-1)

* Go SDK: cli-plugins/hooks: deprecate `HookMessage `and rename to `cli-plugins/hooks.Response`. [docker/cli#6859](https://github.com/docker/cli/pull/6859)
* Go SDK: cli-plugins/hooks: deprecate `HookType` and rename to `cli-plugins/hooks.ResponseType`. [docker/cli#6859](https://github.com/docker/cli/pull/6859)
* Go SDK: cli-plugins/manager: deprecate `HookPluginData` and move to `cli-plugins/hooks.Request`. [docker/cli#6859](https://github.com/docker/cli/pull/6859)

## [29.3.1](#2931)

*2026-03-25*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.3.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.3.1)
* [moby/moby, 29.3.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.3.1)

### [Security](#security-4)

This release includes fixes for multiple security vulnerabilities affecting Docker Engine and related components.

* **CVE-2026-34040** Fix an authorization bypass in AuthZ plugins that could allow authorization plugins to be bypassed under specific conditions. [GHSA-x744-4wpc-v9h2](https://github.com/moby/moby/security/advisories/GHSA-x744-4wpc-v9h2)

* **CVE-2026-33997** Fix a flaw in `docker plugin install` where privilege validation could be partially bypassed, potentially leading to unauthorized privilege escalation. [GHSA-pxq6-2prw-chj9](https://github.com/moby/moby/security/advisories/GHSA-pxq6-2prw-chj9)

* **CVE-2026-33748** Fix insufficient validation of Git URL `#ref:subdir` fragments in BuildKit, which could allow access to files outside the intended repository scope. [GHSA-4vrq-3vrq-g6gg](https://github.com/moby/buildkit/security/advisories/GHSA-4vrq-3vrq-g6gg)

* **CVE-2026-33747** Fix a vulnerability in BuildKit where an untrusted frontend could cause files to be written outside the BuildKit state directory. [GHSA-3c29-8rgm-jvjj](https://github.com/moby/buildkit/security/advisories/GHSA-4c29-8rgm-jvjj)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-4)

* Fix a daemon crash during docker build if `.dockerignore` contained an invalid pattern. [moby/moby#52214](https://github.com/moby/moby/pull/52214)
* Fix a panic when the containerd client uses a closed stream. [moby/moby#52211](https://github.com/moby/moby/pull/52211)

### [Packaging updates](#packaging-updates-3)

* Update containerd (static binaries) to [v2.2.2](https://github.com/containerd/containerd/releases/tag/v2.2.2). [moby/moby#52213](https://github.com/moby/moby/pull/52213)
* Update Go runtime to [1.25.8](https://go.dev/doc/devel/release#go1.25.8). [moby/moby#52210](https://github.com/moby/moby/pull/52210), [docker/cli#6883](https://github.com/docker/cli/pull/6883)

### [Go SDK](#go-sdk-2)

* Add missing build-tag, which could cause `cannot range over 10 (untyped int constant)` when importing the `cli/command` package. [docker/cli#6884](https://github.com/docker/cli/pull/6884)

## [29.3.0](#2930)

*2026-03-05*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.3.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.3.0)
* [moby/moby, 29.3.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.3.0)

### [New](#new-1)

* Add `bind-create-src` option to `--mount` flag for bind mounts. [docker/cli#6792](https://github.com/docker/cli/pull/6792)
* CLI plugin hooks now fire on command failure (not just success), and plugins can use "error-hooks" to show hints only when commands fail. [docker/cli#6794](https://github.com/docker/cli/pull/6794)
* Lower minimum API version from v1.44 to v1.40 (Docker 19.03). [moby/moby#52067](https://github.com/moby/moby/pull/52067)

### [Packaging updates](#packaging-updates-4)

* Update BuildKit to [v0.28.0](https://github.com/moby/buildkit/releases/tag/v0.28.0). [moby/moby#52135](https://github.com/moby/moby/pull/52135)

### [Networking](#networking-4)

* Fix DNS config corruption on daemon reload. [moby/moby#52060](https://github.com/moby/moby/pull/52060)

### [API](#api)

* `POST /networks/{id}/connect` now correctly applies the `MacAddress` field in `EndpointSettings`. This field was added in API v1.44, but was previously ignored. [moby/moby#52040](https://github.com/moby/moby/pull/52040)
* `GET /images/json` now supports an `identity` query parameter. When set, the response includes manifest summaries and may include an `Identity` field for each manifest with trusted identity and origin information. [moby/moby#52030](https://github.com/moby/moby/pull/52030)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-5)

* The `--gpus` option now uses CDI-based injection for AMD GPUs. [moby/moby#52048](https://github.com/moby/moby/pull/52048)
* Add `sd_notify` ["RELOADING"](https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html#RELOADING=1) notifications when signalling the daemon to reload its configuration. [moby/moby#52041](https://github.com/moby/moby/pull/52041)
* Send `sd_notify` ["READY"](https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html#READY=1) and ["STOPPING"](https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html#STOPPING=1) synchronously to make sure they are sent before we proceed. [moby/moby#52041](https://github.com/moby/moby/pull/52041)
* Add support for the systemd 253 `Type=notify-reload` service reload protocol. [moby/moby#52041](https://github.com/moby/moby/pull/52041)
* Don't log "failed to determine if container is already mounted" warnings for stopped containers during startup. [moby/moby#52076](https://github.com/moby/moby/pull/52076)
* Fix `docker system prune` failing with "rw layer snapshot not found" when a container is concurrently removed. [moby/moby#52090](https://github.com/moby/moby/pull/52090)
* Fix a panic when running `docker top` on a non-running Windows container. [moby/moby#52025](https://github.com/moby/moby/pull/52025)
* Fix a regression in v29.2.0 that prevented registering the dockerd service on Windows if system requirements were not yet installed. [moby/moby#52006](https://github.com/moby/moby/pull/52006)
* Fix shared mount detection for paths mounted multiple times, which caused "not a shared mount" errors when using bind propagation. [moby/moby#51787](https://github.com/moby/moby/pull/51787)
* Fix spurious "ShouldRestart failed" warning on shutdown. [moby/moby#52079](https://github.com/moby/moby/pull/52079)
* Preserve leading and trailing whitespace when storing registry passwords. [docker/cli#6784](https://github.com/docker/cli/pull/6784)
* Prevent logging "not found" warnings when calculating volume sizes. [moby/moby#52018](https://github.com/moby/moby/pull/52018)
* Update Go runtime to [1.25.7](https://go.dev/doc/devel/release#go1.25.7). [moby/moby#52003](https://github.com/moby/moby/pull/52003), [docker/cli#6780](https://github.com/docker/cli/pull/6780)

## [29.2.1](#2921)

*2026-02-02*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.2.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.2.1)
* [moby/moby, 29.2.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.2.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-6)

* Update BuildKit to [v0.27.1](https://github.com/moby/buildkit/releases/tag/v0.27.1). [moby/moby#51962](https://github.com/moby/moby/pull/51962)
* Fix `docker system df` failing when run concurrently with `docker system prune`. [moby/moby#51979](https://github.com/moby/moby/pull/51979)
* Fix daemon handling of duplicate container exit events to avoid repeated cleanup and state transitions. [moby/moby#51925](https://github.com/moby/moby/pull/51925)
* Fix panic after failed daemon initialization. [moby/moby#51943](https://github.com/moby/moby/pull/51943)
* Fix encrypted overlay networks not passing traffic to containers on v28 and older Engines. Encrypted overlay networks will no longer pass traffic to containers on v29.2.0 thru v29.0.0, v28.2.2, v25.0.14 or v25.0.13. [moby/moby#51951](https://github.com/moby/moby/pull/51951)
* Fix potential panic on `docker network prune`. [moby/moby#51966](https://github.com/moby/moby/pull/51966)

## [29.2.0](#2920)

*2026-01-26*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.2.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.2.0)
* [moby/moby, 29.2.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.2.0)

### [New](#new-2)

* `docker info` now includes `NRI` section. [docker/cli#6710](https://github.com/docker/cli/pull/6710)
* Add experimental NRI support. [moby/moby#51711](https://github.com/moby/moby/pull/51711), [moby/moby#51712](https://github.com/moby/moby/pull/51712), [moby/moby#51675](https://github.com/moby/moby/pull/51675), [moby/moby#51674](https://github.com/moby/moby/pull/51674), [moby/moby#51636](https://github.com/moby/moby/pull/51636), [moby/moby#51634](https://github.com/moby/moby/pull/51634)
* New `Identity` field has been added to the inspect endpoint to show trusted origin information about the image. This includes build ref for locally built images, remote registry repository for pulled images, and verified signature information for images that contain a valid signed provenance attestation. [moby/moby#51737](https://github.com/moby/moby/pull/51737)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-7)

* Improve validation of `--detach-keys` command-line options. [docker/cli#6742](https://github.com/docker/cli/pull/6742)
* Prevent a potential panic on daemon shutdown after an incomplete initialization. [moby/moby#51797](https://github.com/moby/moby/pull/51797)
* Remove restriction on anonymous read-only volumes. [moby/moby#51682](https://github.com/moby/moby/pull/51682)
* The `--validate` flag on dockerd now also verifies system requirements, allowing for system requirements to be checked before starting the daemon. [moby/moby#51868](https://github.com/moby/moby/pull/51868)
* Handle `--gpus` requests for NVIDIA devices using CDI if possible. [moby/moby#50228](https://github.com/moby/moby/pull/50228)

### [Packaging updates](#packaging-updates-5)

* Update BuildKit to [v0.27.0](https://github.com/moby/buildkit/releases/tag/v0.27.0). [moby/moby#51886](https://github.com/moby/moby/pull/51886)
* Update containerd (static binaries only) to [v2.2.1](https://github.com/containerd/containerd/releases/tag/v2.2.1). [moby/moby#51765](https://github.com/moby/moby/pull/51765)

### [Rootless](#rootless-1)

* Rootless: Consider `$XDG_CONFIG_HOME/cdi` and `$XDG_RUNTIME_DIR/cdi` when looking for CDI devices. [moby/moby#51624](https://github.com/moby/moby/pull/51624)
* Update RootlessKit to [v2.3.6](https://github.com/rootless-containers/rootlesskit/releases/tag/v2.3.6). [moby/moby#51757](https://github.com/moby/moby/pull/51757)

### [API](#api-1)

* Natively support gRPC on the listening socket. [moby/moby#50744](https://github.com/moby/moby/pull/50744)

### [Go SDK](#go-sdk-3)

* cli/command: add WithAPIClientOptions option. [docker/cli#6740](https://github.com/docker/cli/pull/6740)

### [Deprecations](#deprecations-2)

* Remove `%PROGRAMDATA%\Docker\cli-plugins` from the list of paths used for CLI plugins on Windows. This path was present for backward compatibility with old installation, but replaced by `%ProgramFiles%\Docker\cli-plugins`. [docker/cli#6713](https://github.com/docker/cli/pull/6713)

## [29.1.5](#2915)

*2026-01-16*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.1.5 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.1.5)
* [moby/moby, 29.1.5 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.1.5)

### [Packaging updates](#packaging-updates-6)

* Update Go runtime to [1.25.6](https://go.dev/doc/devel/release#go1.25.6). [moby/moby#51860](https://github.com/moby/moby/pull/51860), [docker/cli#6750](https://github.com/docker/cli/pull/6750)

### [Networking](#networking-5)

* Fixed a regression where established network connections could be disrupted during a container's shutdown grace period. [moby/moby#51843](https://github.com/moby/moby/pull/51843)

## [29.1.4](#2914)

*2026-01-08*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.1.4 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.1.4)
* [moby/moby, 29.1.4 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.1.4)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-8)

* Fix `docker run --network none` panic on Windows. [moby/moby#51830](https://github.com/moby/moby/pull/51830)
* Fix image mounts failing with "file name too long" for long mount paths. [moby/moby#51829](https://github.com/moby/moby/pull/51829)
* Fix potential creation of orphaned overlay2 layers. [moby/moby#51826](https://github.com/moby/moby/pull/51826), [moby/moby#51824](https://github.com/moby/moby/pull/51824)

### [Packaging updates](#packaging-updates-7)

* Update BuildKit to [v0.26.3](https://github.com/moby/buildkit/releases/tag/v0.26.3). [moby/moby#51821](https://github.com/moby/moby/pull/51821)

## [29.1.3](#2913)

*2025-12-12*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.1.3 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.1.3)
* [moby/moby, 29.1.3 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.1.3)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-9)

* Add shell completion for `docker stack deploy --compose-file`. [docker/cli#6690](https://github.com/docker/cli/pull/6690)
* containerd image store: Fix a bug causing `docker build` to ignore the explicitly set `unpack` image exporter option. [moby/moby#51514](https://github.com/moby/moby/pull/51514)
* Fix `docker image ls` dangling image handling. [docker/cli#6704](https://github.com/docker/cli/pull/6704)
* Fix a bug that could cause the Engine to leave containers with autoremove set in 'dead' state on shutdown, and never reclaim them. [moby/moby#51693](https://github.com/moby/moby/pull/51693)
* Fix build on i386. [moby/moby#51528](https://github.com/moby/moby/pull/51528)
* Fix explicit graphdriver configuration (`"storage-driver"`) being treated as containerd snapshotter when prior graphdriver state exists. [moby/moby#51516](https://github.com/moby/moby/pull/51516)
* Fix potential creation of orphaned overlay2 layers. [moby/moby#51703](https://github.com/moby/moby/pull/51703)

### [Networking](#networking-6)

* Allow creation of a container with a specific IP address when its networks were not configured with a specific subnet. [moby/moby#51583](https://github.com/moby/moby/pull/51583)
* Don't crash when starting a container created via the API before upgrade to v29.1.2, with `PublishAll` and a nil `PortBindings` map. [moby/moby#51691](https://github.com/moby/moby/pull/51691)
* Fix a bug preventing DNS resolution of containers attached to non swarm-scoped networks once the node has joined a Swarm cluster. [moby/moby#51515](https://github.com/moby/moby/pull/51515)
* Fix an issue that caused daemon crash when using a remote network driver plugin. [moby/moby#51558](https://github.com/moby/moby/pull/51558)
* Fix an issue that could lead to an "endpoint not found" error when creating a container with multiple network connections, when one of the networks is non-internal but does not have its own external IP connectivity. [moby/moby#51538](https://github.com/moby/moby/pull/51538)
* Fix an issue that prevented rootless Docker from starting on a host with IPv6 disabled. [moby/moby#51543](https://github.com/moby/moby/pull/51543)
* Return an error when a container is created with a port-mapping pointing to container port 0. [moby/moby#51695](https://github.com/moby/moby/pull/51695)

## [29.1.2](#2912)

*2025-12-02*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.1.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.1.2)
* [moby/moby, 29.1.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.1.2)

### [Security](#security-5)

* Update Go runtime to [1.25.5](https://go.dev/doc/devel/release#go1.25.5). [moby/moby#51648](https://github.com/moby/moby/pull/51648), [docker/cli#6688](https://github.com/docker/cli/pull/6688)

  * Fixes a potential DoS via excessive resource usage when formatting hostname validation errors [**CVE-2025-61729**](https://nvd.nist.gov/vuln/detail/CVE-2025-61729)
  * Fixes incorrect enforcement of excluded subdomain constraints for wildcard SANs, which could allow improperly trusted certificates [**CVE-2025-61727**](https://nvd.nist.gov/vuln/detail/CVE-2025-22874)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-10)

* containerd image store: Fix `docker image inspect` failing to return available image data in case where not all distributable blobs are available locally. [moby/moby#51629](https://github.com/moby/moby/pull/51629)
* dockerd-rootless-setuptool.sh: fix `nsenter: no namespace specified`. [moby/moby#51622](https://github.com/moby/moby/pull/51622)
* Fix `docker system df` showing `N/A` for shared size and unique size when using graph-drivers as storage. [moby/moby#51631](https://github.com/moby/moby/pull/51631)

### [Packaging updates](#packaging-updates-8)

* Update runc (in static binaries) to [v1.3.4](https://github.com/opencontainers/runc/releases/tag/v1.3.4). [moby/moby#51633](https://github.com/moby/moby/pull/51633)

### [Networking](#networking-7)

* Fix a bug preventing port mappings in rootless mode when slirp4netns is used. [moby/moby#51616](https://github.com/moby/moby/pull/51616)
* Prevent a crash when making an API request with `HostConfig.PublishAllPorts` set (`-P`), and no port bindings. [moby/moby#51621](https://github.com/moby/moby/pull/51621)

## [29.1.1](#2911)

*2025-11-28*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.1.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.1.1)
* [moby/moby, 29.1.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.1.1)

### [Networking](#networking-8)

* Revert a PR breaking external DNS resolution on all custom bridge networks. [moby/moby#51615](https://github.com/moby/moby/pull/51615)

## [29.1.0](#2910)

*2025-11-27*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.1.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.1.0)
* [moby/moby, 29.1.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.1.0)

### [Packaging updates](#packaging-updates-9)

* Update BuildKit to [v0.26.1](https://github.com/moby/buildkit/releases/tag/v0.26.1). [moby/moby#51551](https://github.com/moby/moby/pull/51551)
* Update containerd binary to v2.2.0 (static binaries). [moby/moby#51271](https://github.com/moby/moby/pull/51271)

### [Networking](#networking-9)

* Do not overwrite user-modified `/etc/resolv.conf` across container restarts. [moby/moby#51507](https://github.com/moby/moby/pull/51507)
* fix `--publish-all` / `-P` for Windows containers. [moby/moby#51586](https://github.com/moby/moby/pull/51586)
* Fix an issue that prevented container restart or network reconnection when gateway configuration failed during container stop or network disconnect. [moby/moby#51592](https://github.com/moby/moby/pull/51592)
* Windows containers: don't display an IPv6-mapped IPv4 address in port mappings. For example, `[::ffff:0.0.0.0]:8080->80/tcp` instead of `0.0.0.0:8080->80/tcp`. [moby/moby#51587](https://github.com/moby/moby/pull/51587)

## [29.0.4](#2904)

*2025-11-24*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.0.4 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.0.4)
* [moby/moby, 29.0.4 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.0.4)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-11)

* `docker image ls` no longer truncates the image names. [docker/cli#6675](https://github.com/docker/cli/pull/6675)

### [Networking](#networking-10)

* Allow creation of a container with a specific IP address when its networks were not configured with a specific subnet. [moby/moby#51583](https://github.com/moby/moby/pull/51583)

## [29.0.3](#2903)

*2025-11-24*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.0.3 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.0.3)
* [moby/moby, 29.0.3 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.0.3)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-12)

* `docker version --format json`: restore top-level `BuildTime` field to use RFC3339Nano format. [docker/cli#6668](https://github.com/docker/cli/pull/6668)
* Fix `docker image ls` ignoring a custom `imageFormat` from `docker.json`. [docker/cli#6667](https://github.com/docker/cli/pull/6667)

### [Networking](#networking-11)

* Fix an issue that caused daemon crash when using a remote network driver plugin. [moby/moby#51558](https://github.com/moby/moby/pull/51558)

## [29.0.2](#2902)

*2025-11-17*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.0.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.0.2)
* [moby/moby, 29.0.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.0.2)

### [Networking](#networking-12)

* Fix an issue that could lead to an "endpoint not found" error when creating a container with multiple network connections, when one of the networks is non-internal but does not have its own external IP connectivity. [moby/moby#51538](https://github.com/moby/moby/pull/51538)
* Fix an issue that prevented rootless Docker from starting on a host with IPv6 disabled. [moby/moby#51543](https://github.com/moby/moby/pull/51543)

## [29.0.1](#2901)

*2025-11-14*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.0.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.0.1)
* [moby/moby, 29.0.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.0.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-13)

* `docker image ls` no longer truncates the name width when output is redirect (e.g. for `grep`). [docker/cli#6656](https://github.com/docker/cli/pull/6656)
* `docker image ls` now considers the `NO_COLOR` environment variable for choosing the colored output. [docker/cli#6654](https://github.com/docker/cli/pull/6654)
* containerd image store: Fix a bug causing `docker build` to ignore the explicitly set `unpack` image exporter option. [moby/moby#51514](https://github.com/moby/moby/pull/51514)
* Fix a bug causing `docker image ls --all` to not show untagged/dangling images. [docker/cli#6657](https://github.com/docker/cli/pull/6657)
* Fix build on i386. [moby/moby#51528](https://github.com/moby/moby/pull/51528)
* Fix explicit graphdriver configuration (`"storage-driver"`) being treated as containerd snapshotter when prior graphdriver state exists. [moby/moby#51516](https://github.com/moby/moby/pull/51516)
* Fix output format of the `ApiVersion` and `MinApiVersion` fields in `docker version --format=json` to align with previous versions. [docker/cli#6648](https://github.com/docker/cli/pull/6648)

### [Networking](#networking-13)

* Fix a bug preventing DNS resolution of containers attached to non swarm-scoped networks once the node has joined a Swarm cluster. [moby/moby#51515](https://github.com/moby/moby/pull/51515)

## [29.0.0](#2900)

*2025-11-10*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 29.0.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A29.0.0)
* [moby/moby, 29.0.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A29.0.0)

> Caution
>
> This release includes several breaking changes and deprecations. Review the release notes carefully before upgrading.

* Experimental support for nftables can now be enabled by setting Docker daemon's `firewall-backend` option to `nftables`. For more information, see [Docker Engine docs](https://docs.docker.com/engine/network/firewall-nftables/).
* containerd image store is now the default for **fresh installs**. This doesn't apply to daemons configured with `userns-remap` (see [moby#47377](https://github.com/moby/moby/issues/47377)).

### [Breaking Changes](#breaking-changes)

* The Go module `github.com/docker/docker` is deprecated in favor of `github.com/moby/moby/client` and `github.com/moby/moby/api`. The `github.com/moby/moby` module is considered an **internal implementation detail** - the only supported public modules are `client` and `api`. Starting with v29, releases are tagged with the `docker-` prefix (e.g., `docker-v29.0.0`). **This only affects Go module users and package maintainers.**
* The daemon now requires API version `v1.44` or later (Docker v25.0+).
* Debian armhf (32-bit) packages now target ARMv7 CPUs and will not work on ARMv6 devices.
* Official Raspbian (32-bit) packages are no longer provided. Use Debian arm64 packages for 64-bit devices, or Debian armhf packages for 32-bit ARMv7 devices.
* **cgroup v1 is deprecated.** Support continues until at least May 2029, but migrate to cgroup v2 as soon as possible. See [moby#51111](https://github.com/moby/moby/issues/51111).
* Docker Content Trust was removed from the Docker CLI. Can be built as a separate plugin: <https://github.com/docker/cli/blob/v29.0.0/cmd/docker-trust/main.go>

***

### [New](#new-3)

* `docker image load` and `docker image save` now supports multiple platform selection via `--platform` flag (e.g., `docker image load --platform linux/amd64,linux/arm64 -i image.tar`). [docker/cli#6126](https://github.com/docker/cli/pull/6126)
* `docker image ls` now uses the new view (like `--tree` but collapsed) by default. [docker/cli#6566](https://github.com/docker/cli/pull/6566)
* `docker run --runtime <...>` is now supported on Windows. [moby/moby#50546](https://github.com/moby/moby/pull/50546)
* `GET /containers/json` now includes a `Health` field describing container healthcheck status. [moby/moby#50281](https://github.com/moby/moby/pull/50281)
* Add `device` entitlement to builder configuration. [moby/moby#50386](https://github.com/moby/moby/pull/50386)
* Add support for `memory-swap` and `memory-swappiness` flags to `docker service create` and `docker service update` commands. [docker/cli#6619](https://github.com/docker/cli/pull/6619)
* Allow Docker CLI to set the `GODEBUG` environment variable when the key-value pair (`"GODEBUG":"..."`) exists inside the Docker context metadata. [docker/cli#6371](https://github.com/docker/cli/pull/6371)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-14)

* `docker image ls --tree` now sorts images alphabetically by name instead of by creation date. [docker/cli#6595](https://github.com/docker/cli/pull/6595)
* `docker image ls` no longer shows untagged images by default if no `--all` flag is provided. [docker/cli#6574](https://github.com/docker/cli/pull/6574)
* `docker save`: Fixed inconsistent tar member timestamps when exporting images with the overlay2 storage driver. [moby/moby#51365](https://github.com/moby/moby/pull/51365)
* Add a new log option for fluentd log driver (`fluentd-read-timeout`), which enables specifying read timeouts for reading acks from fluentd connections. [moby/moby#50249](https://github.com/moby/moby/pull/50249)
* Add image name completion for `docker images`. [docker/cli#6452](https://github.com/docker/cli/pull/6452)
* Add shell completion for `docker inspect` if a `--type` is set. [docker/cli#6444](https://github.com/docker/cli/pull/6444)
* Add shell completion for `docker plugin` subcommands. [docker/cli#6445](https://github.com/docker/cli/pull/6445)
* api/types/container: make ContainerState, HealthStatus concrete types. [moby/moby#51439](https://github.com/moby/moby/pull/51439)
* containerd image store is temporarily not available when userns remapping is enabled as a workaround for [moby#47377](https://github.com/moby/moby/issues/47377). [moby/moby#51042](https://github.com/moby/moby/pull/51042)
* contrib: remove contrib/httpserver, which was only used for integration tests. [moby/moby#50654](https://github.com/moby/moby/pull/50654)
* daemon: improve validation of the `--dns` option and corresponding `"dns"` field in `daemon.json`. [moby/moby#50600](https://github.com/moby/moby/pull/50600)
* dockerd-rootless.sh: if slirp4netns is not installed, try using pasta (passt). [moby/moby#51149](https://github.com/moby/moby/pull/51149)
* Fix `--mount type=image` failure when mounting the same image multiple times to a different destinations. [moby/moby#50268](https://github.com/moby/moby/pull/50268)
* Fix `docker stats <container>` not exiting gracefully. [docker/cli#6582](https://github.com/docker/cli/pull/6582)
* Fix a bug preventing the API server from shutting down quickly when there's an open connection to the `/events` endpoint. [moby/moby#51448](https://github.com/moby/moby/pull/51448)
* Fix a bug where collecting container stats in "one-shot" mode would not include the container's ID and Name. [moby/moby#51302](https://github.com/moby/moby/pull/51302)
* Fix an issue where all new tasks in the Swarm could get stuck in the PENDING state forever after scaling up a service with placement preferences. [moby/moby#50202](https://github.com/moby/moby/pull/50202)
* Fix issue where custom meta-headers were not passed through when using the containerd image store. [moby/moby#51024](https://github.com/moby/moby/pull/51024)
* Fix requests not being logged when running the daemon with `--log-level=trace`. [moby/moby#50986](https://github.com/moby/moby/pull/50986)
* Fix Swarm services becoming unreachable from published ports after a firewalld reload. [moby/moby#50443](https://github.com/moby/moby/pull/50443)
* Improve errors when failing to connect to the API to provide more context to the user. [moby/moby#50285](https://github.com/moby/moby/pull/50285)
* Improve shell completion for `docker secret` and `docker config` subcommands. [docker/cli#6446](https://github.com/docker/cli/pull/6446)
* Prefer explicit device driver name over GPU capabilities when selecting the device driver with `docker run --gpus`. [moby/moby#50717](https://github.com/moby/moby/pull/50717)
* Update runc to [v1.3.3](https://github.com/opencontainers/runc/releases/tag/v1.3.3). [moby/moby#51393](https://github.com/moby/moby/pull/51393)
* Update SwarmKit internal TLS configuration to exclude known insecure cipher suites. [moby/moby#51139](https://github.com/moby/moby/pull/51139)
* Windows: Fix BuildKit creating containers which isolation mode is inconsistent with the daemon's config. [moby/moby#50942](https://github.com/moby/moby/pull/50942)

### [Packaging updates](#packaging-updates-10)

* client: remove legacy CBC cipher suites from client config. [moby/moby#50126](https://github.com/moby/moby/pull/50126)

* contrib: remove `editorconfig` as it was unmaintained. [moby/moby#50607](https://github.com/moby/moby/pull/50607)

* contrib: remove Dockerfile syntax highlighting files for `nano` and TextMate (`tmbundle`) as they were unmaintained and outdated. [moby/moby#50606](https://github.com/moby/moby/pull/50606)

* contrib: remove mkimage-xxx scripts as they were unmaintained and not tested. [moby/moby#50297](https://github.com/moby/moby/pull/50297)

* If Docker is downgraded to a version that does not have this support the network will become unusable, it must be deleted and re-created. [moby/moby#50114](https://github.com/moby/moby/pull/50114)

* The Windows overlay network driver now supports option `--dns`. [moby/moby#51229](https://github.com/moby/moby/pull/51229)

* Update BuildKit to [v0.25.2](https://github.com/moby/buildkit/releases/tag/v0.25.2). [moby/moby#51397](https://github.com/moby/moby/pull/51397)

* Update containerd to [v2.1.5](https://github.com/containerd/containerd/releases/tag/v2.1.5). [moby/moby#51409](https://github.com/moby/moby/pull/51409)

  containerd v2.1.5 now uses systemd's default `LimitNOFILE` for containers, changing the open file descriptor limit (`ulimit -n`) from `1048576` to `1024`. This extends a change introduced in Docker Engine v25.0 for build containers to all containers.

  This prevents programs that adjust behavior based on ulimits from consuming excessive memory when the limit is set to `infinity`. Containers now behave the same way as programs running on the host.

  If your workload needs a higher limit, use `--ulimit` with `docker run`, or set defaults in `/etc/docker/daemon.json`:

  ```json
  {
    "default-ulimits": {
      "nofile": {
        "Name": "nofile",
        "Soft": 1048576,
        "Hard": 1048576
      }
    }
  }
  ```

  For more information, see [moby#51485](https://github.com/moby/moby/issues/51485).

* Update Go runtime to [1.25.4](https://go.dev/doc/devel/release#go1.25.4). [moby/moby#51418](https://github.com/moby/moby/pull/51418), [docker/cli#6632](https://github.com/docker/cli/pull/6632)

* Users can request a specific prefix size for networks allocated from the default pools by using the unspecified address, for example `--subnet 0.0.0.0/24 --subnet ::/96`. [moby/moby#50114](https://github.com/moby/moby/pull/50114)

### [Networking](#networking-14)

* Add daemon option `--bridge-accept-fwmark`. Packets with this firewall mark will accepted by bridge networks, overriding Docker's iptables or nftables "drop" rules. [moby/moby#50476](https://github.com/moby/moby/pull/50476)

* api/types/system: deprecated top level `DiskUsage` fields for type specific fields. [moby/moby#51235](https://github.com/moby/moby/pull/51235)

* Ensure bridge devices are removed when bridge network creation fails. [moby/moby#51147](https://github.com/moby/moby/pull/51147)

* Ensure that Windows NAT networks are recreated with their original labels when the Engine restarts. [moby/moby#50447](https://github.com/moby/moby/pull/50447)

* Environment variables set on a container using legacy links are deprecated and aren't added automatically anymore. [moby/moby#50719](https://github.com/moby/moby/pull/50719)

  * The daemon can be started with `DOCKER_KEEP_DEPRECATED_LEGACY_LINKS_ENV_VARS=1` to get them back
  * Users are encouraged to stop relying on these as they're deprecated, and the escape hatch will be removed in a later version

* Fix a bug in NetworkDB which would sometimes cause entries to get stuck deleted on some of the nodes, leading to connectivity issues between containers on overlay networks. [moby/moby#50342](https://github.com/moby/moby/pull/50342)

* Fix a bug that could cause the Engine and another host process to bind the same UDP port. [moby/moby#50669](https://github.com/moby/moby/pull/50669)

* Fix a deadlock that could happen if a firewalld reload was processed while the bridge networking driver was starting up, or creating or deleting a network, or creating port-mappings. [moby/moby#50620](https://github.com/moby/moby/pull/50620)

* Fix an issue preventing container startup or selection of its network gateway when IPv6 is only disabled on a specific interface. [moby/moby#48971](https://github.com/moby/moby/pull/48971)

* For Linux, `docker info` now reports the firewall backend if available. [docker/cli#6191](https://github.com/docker/cli/pull/6191)

* Greatly improve the reliability of overlay networking and the Swarm routing mesh. [moby/moby#50393](https://github.com/moby/moby/pull/50393)

* Improve the convergence rate of NetworkDB, part of the management plane for overlay networking, after bursts of updates. [moby/moby#50193](https://github.com/moby/moby/pull/50193)

* Improve the reliability of the overlay network driver. [moby/moby#50260](https://github.com/moby/moby/pull/50260)

* Improved error handling for connection of a container to a network. [moby/moby#50945](https://github.com/moby/moby/pull/50945)

* macvlan and IPvlan-l2 networks: no default gateway will be configured unless a `--gateway` is explicitly included in IPAM configuration. This addresses an issue which could cause container startup to fail in networks with IPv6 auto-configuration enabled. [moby/moby#50929](https://github.com/moby/moby/pull/50929)

* nftables: Docker will not enable IP forwarding on the host. If forwarding is needed by a bridge network, but not enabled, daemon startup or network creation will fail with an error. You must either enable forwarding and ensure firewall rules are in place to prevent unwanted forwarding between non-Docker interfaces. Or, use daemon option `--ip-forward=false` to disable the check, but some bridge network functionality including port forwarding may not work. See [Engine Docs](https://docs.docker.com/engine/network/firewall-nftables) for more information about migration from iptables to nftables. [moby/moby#50646](https://github.com/moby/moby/pull/50646)

* On daemon startup, restart containers that share their network stacks before containers that need those stacks. [moby/moby#50327](https://github.com/moby/moby/pull/50327)

* Published ports are now always accessible in networks with gateway mode "routed". Previously, rules to open those ports were only added when the routed mode network was selected as the container's default gateway. [moby/moby#50140](https://github.com/moby/moby/pull/50140)

* Since 28.0.0, an `iptables` mangle rule for checksumming SCTP was only added if environment variable `DOCKER_IPTABLES_SCTP_CHECKSUM=1` was set. The rule has now been removed, the environment variable now has no effect. [moby/moby#50539](https://github.com/moby/moby/pull/50539)

* The iptables rules for bridge networks have been updated, including removal of the `DOCKER-ISOLATION-STAGE-1` and `DOCKER-ISOLATION-STAGE-2` chains. With these changes:. [moby/moby#49981](https://github.com/moby/moby/pull/49981)

  * Containers can now access ports published to host addresses by containers in other networks when the userland-proxy is not running
  * Containers can now access ports on container addresses in other networks that have gateway mode "nat-unprotected"

* When dynamically linked, the Docker daemon now depends on libnftables. [moby/moby#51033](https://github.com/moby/moby/pull/51033)

* Windows: `network inspect`: the HNS network name is now reported in option `com.docker.network.windowsshim.networkname` rather than the Docker network name, which was only reported after a daemon restart. [moby/moby#50961](https://github.com/moby/moby/pull/50961)

* Windows: when restoring networks on daemon restart, preserve their association with non-default IPAM drivers. [moby/moby#50649](https://github.com/moby/moby/pull/50649)

### [API](#api-2)

* `events` API now reports content-type as `application/x-ndjson` for newline-delimited JSON event stream. [moby/moby#50953](https://github.com/moby/moby/pull/50953)

* `GET /images/{name}/get` and `POST /images/load` now accept multiple `platform` query parameters, allowing export and load of images for multiple platforms. [moby/moby#50166](https://github.com/moby/moby/pull/50166)

* `GET /images/{name}/json` now omits the following fields if their value is empty: `Parent`, `Comment`, `DockerVersion`, `Author`. [moby/moby#51072](https://github.com/moby/moby/pull/51072)

* `GET /images/{name}/json`: omit empty `Config` fields when not set. [moby/moby#50915](https://github.com/moby/moby/pull/50915)

* `POST /images/{name:}/push`: remove compatibility with API v1.4 auth-config in body. [moby/moby#50371](https://github.com/moby/moby/pull/50371)

* Add support for memory swappiness in Swarm services. [moby/moby#51114](https://github.com/moby/moby/pull/51114)

  * `GET /services` now returns `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements
  * `GET /services/{id}` now returns `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements
  * `POST /services/create` now accepts `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements
  * `POST /services/{id}/update` now accepts `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements
  * `GET /tasks` now returns `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements
  * `GET /tasks/{id}` now returns `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements

* api/types/build: move `CachePruneOptions` type to `client.BuildCachePruneOptions`. [moby/moby#50772](https://github.com/moby/moby/pull/50772)

* api/types/checkpoint: move checkpoint options to client module. [moby/moby#50905](https://github.com/moby/moby/pull/50905)

* api/types/container: `OnBuild` will now be omitted if its value is empty or zero. [moby/moby#51154](https://github.com/moby/moby/pull/51154)

* api/types/container: make the container config `MacAddress` obsolete for v1.52 and onwards. Use network endpoint settings instead. [moby/moby#51189](https://github.com/moby/moby/pull/51189)

* api/types/container: move `ResizeOptions` type to `ContainerResizeOptions` in the client. [moby/moby#50773](https://github.com/moby/moby/pull/50773)

* api/types/events: move `ListOptions` type to the client `EventsListOptions`. [moby/moby#50774](https://github.com/moby/moby/pull/50774)

* api/types/image: move image options out to the client. [moby/moby#50776](https://github.com/moby/moby/pull/50776)

* api/types/network: move `CreateOptions`, `ConnectOptions` and `DisconnectOptions` to the client module. [moby/moby#50817](https://github.com/moby/moby/pull/50817)

* api/types/network: move the `ListOptions` and `InspectOptions` types to the client. [moby/moby#50786](https://github.com/moby/moby/pull/50786)

* api/types/plugin: change `ListResponse` to a non-pointer slice. [moby/moby#51440](https://github.com/moby/moby/pull/51440)

* api/types/plugin: remove deprecated `Config.DockerVersion`. [moby/moby#51458](https://github.com/moby/moby/pull/51458)

* api/types/registry: move `SearchOptions` to `ImageSearchOptions` in the client. [moby/moby#50787](https://github.com/moby/moby/pull/50787)

* api/types/registry: moved `ServiceConfig` legacy field marshaling support into daemon backend. [moby/moby#50826](https://github.com/moby/moby/pull/50826)

* api/types/registry: moved encode/decode auth config functions into reference utility package. [moby/moby#50785](https://github.com/moby/moby/pull/50785)

* api/types/storage: add `Storage` type and integrate in container inspect. [moby/moby#50857](https://github.com/moby/moby/pull/50857)

* api/types/swarm: deprecated and dropped support for `PortConfigProtocol`; use `network.IPProtocol` instead. [moby/moby#51094](https://github.com/moby/moby/pull/51094)

* api/types/swarm: move option types to the client module. [moby/moby#50794](https://github.com/moby/moby/pull/50794)

* api/types/swarm: move the `SecretListOptions` type to the client module. [moby/moby#50816](https://github.com/moby/moby/pull/50816)

* api/types/system: move `DiskUsageOptions` to the client. [moby/moby#50788](https://github.com/moby/moby/pull/50788)

* api/types/system: move `SecurityOpt` and `DecodeSecurityOptions` to client module. [moby/moby#50825](https://github.com/moby/moby/pull/50825)

* api/types/volume: change ListResponse.Volumes to a non-pointer slice. [moby/moby#51454](https://github.com/moby/moby/pull/51454)

* api/types/volume: move the `ListOptions` type to the client module. [moby/moby#50789](https://github.com/moby/moby/pull/50789)

* api/types/volume: moved `UpdateOptions` into client module. [moby/moby#51205](https://github.com/moby/moby/pull/51205)

* api/types: daemon: move the disk usage structs to the backend server. [moby/moby#50764](https://github.com/moby/moby/pull/50764)

* api: make `GraphDriver` field in `image.InspectResponse` optional. This field will continue to be emitted when using the legacy graph drivers and will be omitted when using the containerd image backend. [moby/moby#50893](https://github.com/moby/moby/pull/50893)

* api: redefine container network port types. [moby/moby#50710](https://github.com/moby/moby/pull/50710)

* client: PluginListResult: change Items field to a non-pointer slice. [moby/moby#51440](https://github.com/moby/moby/pull/51440)

* Inspecting networks with API v1.52 and newer provides statistics about IPAM allocations for the subnets assigned to the network. [moby/moby#50917](https://github.com/moby/moby/pull/50917)

* MAC address fields are represented as byte slices compatible with the standard library net.HardwareAddr type instead of strings. [moby/moby#51355](https://github.com/moby/moby/pull/51355)

* Swagger definitions for `NetworkSummary` and `NetworkInspect` have been added to the Swagger spec describing the Engine API. [moby/moby#50855](https://github.com/moby/moby/pull/50855)

* Update API version to 1.52. [moby/moby#50418](https://github.com/moby/moby/pull/50418)

### [Go SDK](#go-sdk-4)

* `api/pkg/progress` and `api/pkg/streamformatter` have been removed. [moby/moby#51153](https://github.com/moby/moby/pull/51153)
* `api/types/registry`: `EncodeAuthConfig`: use empty string for zero value. [moby/moby#50426](https://github.com/moby/moby/pull/50426)
* `api/types/versions` has moved to the client and daemon. [moby/moby#51284](https://github.com/moby/moby/pull/51284)
* `client.ConfigCreate`, `client.ConfigList`, `client.ConfigInspectWithRaw`, `client.ConfigUpdate`, and `client.ConfigRemove` methods now accept option structs instead of positional arguments, and return dedicated result structs. [moby/moby#51078](https://github.com/moby/moby/pull/51078)
* `client.ImageBuild`, `client.BuildCancel`, `client.ImageList`, `client.ImageRemove`, `client.ImageTag`, and `client.ImageSearch` methods now accept option structs instead of positional arguments, and return dedicated result structs. [moby/moby#51227](https://github.com/moby/moby/pull/51227)
* `client`: `ContainerExec...` methods were renamed to `Exec...`. [moby/moby#51262](https://github.com/moby/moby/pull/51262)
* `client`: Wrap return values of `ImageInspect`, `ImageHistory`, `ImageLoad` and `ImageSave` in a struct. [moby/moby#51236](https://github.com/moby/moby/pull/51236)
* `ImagePull` now returns an object with `JSONMessages` method returning iterator over the message objects. [moby/moby#50935](https://github.com/moby/moby/pull/50935)
* `ImagePush` now returns an object with `JSONMessages` method returning iterator over the message objects. [moby/moby#51148](https://github.com/moby/moby/pull/51148)
* api/types/container: move `StatsResponseReader` to `client` package. [moby/moby#50521](https://github.com/moby/moby/pull/50521)
* api/types/container: move container options to client. [moby/moby#50897](https://github.com/moby/moby/pull/50897)
* api/types/container: rename `Port` to `PortSummary`. [moby/moby#50711](https://github.com/moby/moby/pull/50711)
* api/types/container: StatsResponse: add `OSType` field. [moby/moby#51305](https://github.com/moby/moby/pull/51305)
* api/types: move `ErrorResponse` to `common/ErrorResponse`. [moby/moby#50632](https://github.com/moby/moby/pull/50632)
* api: remove unused `DefaultVersion`, `MinSupportedAPIVersion` consts. [moby/moby#50587](https://github.com/moby/moby/pull/50587)
* cli/command: add `WithUserAgent` option. [docker/cli#4574](https://github.com/docker/cli/pull/4574)
* client: `ContainerCommitOptions`: remove `Pause` field in favor of `NoPause`. [moby/moby#51019](https://github.com/moby/moby/pull/51019)
* client: add `DefaultAPIVersion` const, which defines the default (and maximum) API version supported by the client. [moby/moby#50433](https://github.com/moby/moby/pull/50433)
* client: add `ExecAPIClient` interface for exec methods provided by the client. [moby/moby#50997](https://github.com/moby/moby/pull/50997)
* client: Client.PluginList: add options-struct. [moby/moby#51207](https://github.com/moby/moby/pull/51207)
* client: ContainersPrune: rewrite to use option structs and result. [moby/moby#51200](https://github.com/moby/moby/pull/51200)
* client: ImagesPrune: rewrite to use option structs and result. [moby/moby#51200](https://github.com/moby/moby/pull/51200)
* client: NetworksPrune: rewrite to use option structs and result. [moby/moby#51200](https://github.com/moby/moby/pull/51200)
* client: remove `client.ContainerStatsResult.OSType` field. [moby/moby#51305](https://github.com/moby/moby/pull/51305)
* client: VolumesPrune: rewrite to use option structs and result. [moby/moby#51200](https://github.com/moby/moby/pull/51200)
* daemon/config: add `DefaultAPIVersion` const, which defines the default (and maximum) API version supported by the daemon. [moby/moby#50436](https://github.com/moby/moby/pull/50436)
* Fix data race in `ContainerExecStart`, `ContainerList`, and `Events`. [moby/moby#50448](https://github.com/moby/moby/pull/50448)
* IP addresses and subnets are now of type `netip.Addr` and `netip.Prefix`, respectively. [moby/moby#50956](https://github.com/moby/moby/pull/50956)
* Remove structs `NetworkSettingsBase` and `DefaultNetworkSettings`. Fields in `NetworkSettingsBase` that were not deprecated are now directly in `NetworkSettings`. [moby/moby#50846](https://github.com/moby/moby/pull/50846)
* the client now uses its own `client.Filters` type for filtering API requests, with a more ergonomic interface. Users of the `github.com/docker/docker/api/types/filters` package will need to refactor when they upgrade to the v29 client. [moby/moby#51115](https://github.com/moby/moby/pull/51115)
* Types `"github.com/moby/moby/api/types/network".Summary` and `"github.com/moby/moby/api/types/network".Inspect` are no longer aliases, and most of their fields have been moved into an embedded struct. Engine API clients may require some source-level changes when migrating to the new github.com/moby/moby/api module. [moby/moby#50878](https://github.com/moby/moby/pull/50878)
* Update minimum Go version to 1.24. [docker/cli#6624](https://github.com/docker/cli/pull/6624)

### [Deprecations](#deprecations-3)

* `client/pkg/jsonmessage`: remove deprecated `ProgressMessage`, `ErrorMessage`, `DisplayJSONMessagesToStream` and `Stream` interface. [moby/moby#49264](https://github.com/moby/moby/pull/49264)
* `GET /events` no longer includes the deprecated `status`, `id`, and `from` fields. These fields were removed in API v1.22, but still included in the response. These fields are now omitted when using API v1.52 or later. [moby/moby#50832](https://github.com/moby/moby/pull/50832)
* api/types/network: CreateRequest: remove deprecated CheckDuplicate field. [moby/moby#50998](https://github.com/moby/moby/pull/50998)
* api/types/plugin: deprecate `Config.DockerVersion` field. [moby/moby#51109](https://github.com/moby/moby/pull/51109)
* api/types/registry: remove deprecated AuthConfig.Email field. [moby/moby#51059](https://github.com/moby/moby/pull/51059)
* api/types/strslice: deprecate StrSlice in favor of using a regular `[]string`. [moby/moby#50292](https://github.com/moby/moby/pull/50292)
* api/types/system: remove deprecated `DiskUsage.BuilderSize`. [moby/moby#51180](https://github.com/moby/moby/pull/51180)
* api/types: move plugin types to api/types/plugin. [moby/moby#48114](https://github.com/moby/moby/pull/48114)
* API: Deprecation: the Engine was automatically backfilling empty `PortBindings` lists with a PortBinding with an empty HostIP and HostPort when starting a container. This behavior is deprecated for API 1.52, and will be dropped in API 1.53. [moby/moby#50874](https://github.com/moby/moby/pull/50874)
* build: remove DCT support for classic builder. [docker/cli#6195](https://github.com/docker/cli/pull/6195)
* cli/command: Remove deprecated `ResolveDefaultContext`. [docker/cli#6555](https://github.com/docker/cli/pull/6555)
* client: ImageBuildResponse: remove OSType field. [moby/moby#50995](https://github.com/moby/moby/pull/50995)
* client: Remove `ImageCreate` method - use`ImagePull` or `ImageImport` instead. [moby/moby#51366](https://github.com/moby/moby/pull/51366)
* client: remove deprecated `ImageListOptions.ContainerCount`. [moby/moby#51006](https://github.com/moby/moby/pull/51006)
* client: remove support for negotiating API version < v1.44 (docker 25.0). [moby/moby#51119](https://github.com/moby/moby/pull/51119)
* client: remove unused `Client.HTTPClient()` method. [moby/moby#51011](https://github.com/moby/moby/pull/51011)
* daemon/graphdriver: remove deprecated `GetDriver()`. [moby/moby#50377](https://github.com/moby/moby/pull/50377)
* daemon: raise minimum API version to v1.44. [moby/moby#51186](https://github.com/moby/moby/pull/51186)
* Deprecate the `--pause` flag on `docker commit` in favor of `--no-pause`. [docker/cli#6460](https://github.com/docker/cli/pull/6460)
* Deprecate cgroup v1. [moby/moby#51360](https://github.com/moby/moby/pull/51360), [docker/cli#6598](https://github.com/docker/cli/pull/6598)
* Go SDK: `cli-plugins/manager`: deprecate metadata aliases in favor of their equivalent in `cli-plugins/manager/metadata`. [docker/cli#6237](https://github.com/docker/cli/pull/6237)
* Go SDK: `cli-plugins/manager`: remove `Candidate` interface, which was only for internal use. [docker/cli#6237](https://github.com/docker/cli/pull/6237)
* Go SDK: `cli-plugins/manager`: remove `NewPluginError` function, which was only for internal use. [docker/cli#6237](https://github.com/docker/cli/pull/6237)
* Go SDK: `cli-plugins/manager`: remove deprecated `ResourceAttributesEnvvar` const. [docker/cli#6237](https://github.com/docker/cli/pull/6237)
* Go SDK: `cli/command`: remove the `ErrPromptTerminated`, `DisableInputEcho`, `PromptForInput`, and `PromptForConfirmation` utilities. These utilities were for internal use and are no longer used. [docker/cli#6243](https://github.com/docker/cli/pull/6243)
* Go SDK: `cli/registry/client`: remove deprecated `RepoNameForReference`. [docker/cli#6206](https://github.com/docker/cli/pull/6206)
* Go SDK: api/types/build: remove deprecated BuildCache.Parent field. [moby/moby#51185](https://github.com/moby/moby/pull/51185)
* Go SDK: api/types/container: remove deprecated `ContainerTopOKBody` alias. [moby/moby#50400](https://github.com/moby/moby/pull/50400)
* Go SDK: api/types/container: remove deprecated `ContainerUpdateOKBody` alias. [moby/moby#50400](https://github.com/moby/moby/pull/50400)
* Go SDK: api/types/container: remove deprecated `Stats` type. [moby/moby#50492](https://github.com/moby/moby/pull/50492)
* Go SDK: api/types/filters: remove deprecated `ToParamWithVersion`. [moby/moby#50561](https://github.com/moby/moby/pull/50561)
* Go SDK: api/types/image: `InspectResponse`: remove deprecated `VirtualSize`, `Container`, `ContainerConfig`, `Parent`, and `DockerVersion` fields. [moby/moby#51103](https://github.com/moby/moby/pull/51103)
* Go SDK: api/types/image: remove deprecated Summary.VirtualSize field. [moby/moby#51190](https://github.com/moby/moby/pull/51190)
* Go SDK: api/types/registry: remove deprecated `ServiceConfig.AllowNondistributableArtifactsCIDRs` and `ServiceConfig.AllowNondistributableArtifactsHostnames` fields. [moby/moby#50375](https://github.com/moby/moby/pull/50375)
* Go SDK: api/types/swarm: remove deprecated ServiceSpec.Networks field. [moby/moby#51184](https://github.com/moby/moby/pull/51184)
* GO SDK: api/types/system: remove deprecated `Commit.Expected` field. [moby/moby#51127](https://github.com/moby/moby/pull/51127)
* Go SDK: api/types: remove deprecated aliases. [moby/moby#50452](https://github.com/moby/moby/pull/50452)
* Go SDK: api: deprecate `NoBaseImageSpecifier` const. This const is no longer used and will be removed in the next release. [moby/moby#50437](https://github.com/moby/moby/pull/50437)
* Go SDK: api: remove `NoBaseImageSpecifier`. [moby/moby#50574](https://github.com/moby/moby/pull/50574)
* Go SDK: cli/command/builder: remove `CachePrune()`, which was no longer used. [docker/cli#6236](https://github.com/docker/cli/pull/6236)
* Go SDK: cli/command/builder: remove `NewBuilderCommand` and `NewBakeStubCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/checkpoint: remove `NewCheckpointCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/checkpoint: remove deprecated `NewFormat`, `FormatWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/completion: remove deprecated `NoComplete`. [docker/cli#6408](https://github.com/docker/cli/pull/6408)
* Go SDK: cli/command/config: remove `NewConfigCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/config: remove deprecated `NewFormat`, `FormatWrite`, `InspectFormatWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/config: remove deprecated `RunConfigCreate`, `CreateOptions`, `RunConfigInspect`, `InspectOptions`, `RunConfigList`, `ListOptions`, `RunConfigRemove`, and `RemoveOptions`. [docker/cli#6370](https://github.com/docker/cli/pull/6370)
* Go SDK: cli/command/container: deprecate `NewDiffFormat`, `DiffFormatWrite`. These functions were only used internally and will be removed in the next release. [docker/cli#6187](https://github.com/docker/cli/pull/6187)
* Go SDK: cli/command/container: remove `NewBuildCommand`, `NewPullCommand`, `NewPushCommand`, `NewImagesCommand`, `NewImageCommand`, `NewHistoryCommand`, `NewImportCommand`, `NewLoadCommand`, `NewRemoveCommand`, `NewSaveCommand`, `NewTagCommand`, `NewPruneCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/container: remove `NewRunCommand`, `NewExecCommand`, `NewPsCommand`, `NewContainerCommand`, `NewAttachCommand`, `NewCommitCommand`, `NewCopyCommand`, `NewCreateCommand`, `NewDiffCommand`, `NewExportCommand`, `NewKillCommand`, `NewLogsCommand`, `NewPauseCommand`, `NewPortCommand`, `NewRenameCommand`, `NewRestartCommand`, `NewRmCommand`, `NewStartCommand`, `NewStatsCommand`, `NewStopCommand`, `NewTopCommand`, `NewUnpauseCommand`, `NewUpdateCommand`, `NewWaitCommand`, `NewPruneCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/container: remove `RunPrune()`, which was no longer used. [docker/cli#6236](https://github.com/docker/cli/pull/6236)
* Go SDK: cli/command/container: remove deprecated `NewDiffFormat`, `DiffFormatWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/context: remove `NewContextCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/context: remove deprecated `RunCreate` and `CreateOptions`. [docker/cli#6407](https://github.com/docker/cli/pull/6407)
* Go SDK: cli/command/context: remove deprecated `RunExport` and `ExportOptions`. [docker/cli#6407](https://github.com/docker/cli/pull/6407)
* Go SDK: cli/command/context: remove deprecated `RunImport`. [docker/cli#6407](https://github.com/docker/cli/pull/6407)
* Go SDK: cli/command/context: remove deprecated `RunRemove` and `RemoveOptions`. [docker/cli#6407](https://github.com/docker/cli/pull/6407)
* Go SDK: cli/command/context: remove deprecated `RunUpdate` and `UpdateOptions`. [docker/cli#6407](https://github.com/docker/cli/pull/6407)
* Go SDK: cli/command/context: remove deprecated `RunUse`. [docker/cli#6407](https://github.com/docker/cli/pull/6407)
* Go SDK: cli/command/formatter/swarm: remove deprecated `GetStacks` function. [docker/cli#6406](https://github.com/docker/cli/pull/6406)
* Go SDK: cli/command/image/build: deprecate `DefaultDockerfileName`, `DetectArchiveReader`, `WriteTempDockerfile`, `ResolveAndValidateContextPath`. These utilities were only used internally and will be removed in the next release. [docker/cli#6561](https://github.com/docker/cli/pull/6561)
* Go SDK: cli/command/image: remove `RunPrune()`, which was no longer used. [docker/cli#6236](https://github.com/docker/cli/pull/6236)
* Go SDK: cli/command/image: remove deprecated `AuthResolver` utility. [docker/cli#6373](https://github.com/docker/cli/pull/6373)
* Go SDK: cli/command/image: remove deprecated `NewHistoryFormat`, `HistoryWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339), [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/manifest: remove `NewManifestCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/network: remove `NewNetworkCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/network: remove `RunPrune()`, which was no longer used. [docker/cli#6236](https://github.com/docker/cli/pull/6236)
* Go SDK: cli/command/network: remove deprecated `NewFormat`, `FormatWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/node: remove `NewNodeCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/node: remove deprecated `NewFormat`, `FormatWrite`, `InspectFormatWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/plugin: remove `NewPluginCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/plugin: remove deprecated `NewFormat`, `FormatWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/registry: remove `NewLoginCommand`, `NewLogoutCommand`, `NewSearchCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/registry: remove deprecated `NewSearchFormat`, `SearchWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/registry: remove deprecated `OauthLoginEscapeHatchEnvVar` const. [docker/cli#6463](https://github.com/docker/cli/pull/6463)
* Go SDK: cli/command/secret: remove `NewSecretCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/secret: remove deprecated `NewFormat`, `FormatWrite`, `InspectFormatWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/service: remove `NewServiceCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/service: remove deprecated `NewFormat`, `InspectFormatWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/stack/swarm: remove deprecated RunPS and options.PS. [docker/cli#6398](https://github.com/docker/cli/pull/6398)
* Go SDK: cli/command/stack: remove `NewStackCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/stack: remove deprecated RunList and options.List. [docker/cli#6398](https://github.com/docker/cli/pull/6398)
* Go SDK: cli/command/stack: remove deprecated RunServices and swarm.GetServices. [docker/cli#6398](https://github.com/docker/cli/pull/6398)
* Go SDK: cli/command/swarm: remove `NewSwarmCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/system: remove `NewVersionCommand`, `NewInfoCommand`, `NewSystemCommand`, `NewEventsCommand`, `NewInspectCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/task: remove deprecated `NewTaskFormat`, `FormatWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/trust: remove `NewTrustCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/trust: remove deprecated `NewPruneCommand`. [docker/cli#6344](https://github.com/docker/cli/pull/6344)
* Go SDK: cli/command/trust: remove deprecated `SignedTagInfo`, `SignerInfo`, `NewTrustTagFormat`, `NewSignerInfoFormat`, `TagWrite`, `SignerInfoWrite`. [docker/cli#6339](https://github.com/docker/cli/pull/6339)
* Go SDK: cli/command/volume: remove `NewVolumeCommand`, `NewPruneCommand`. [docker/cli#6335](https://github.com/docker/cli/pull/6335)
* Go SDK: cli/command/volume: remove `RunPrune()`, which was no longer used. [docker/cli#6236](https://github.com/docker/cli/pull/6236)
* Go SDK: cli/command: remove `AddTrustSigningFlags`, `AddTrustVerificationFlags`, and `AddPlatformFlag` utilities, which were only used internally. [docker/cli#6244](https://github.com/docker/cli/pull/6244)
* Go SDK: cli/command: remove deprecated `DockerCli.Apply`. [docker/cli#6503](https://github.com/docker/cli/pull/6503)
* Go SDK: cli/command: remove deprecated `DockerCli.ContentTrustEnabled`. [docker/cli#6502](https://github.com/docker/cli/pull/6502)
* Go SDK: cli/command: remove deprecated `DockerCli.DefaultVersion`. [docker/cli#6502](https://github.com/docker/cli/pull/6502)
* Go SDK: cli/command: remove deprecated `RegistryAuthenticationPrivilegedFunc`. [docker/cli#6349](https://github.com/docker/cli/pull/6349)
* Go SDK: cli/command: remove deprecated `WithContentTrustFromEnv`, `WithContentTrust` options. [docker/cli#6502](https://github.com/docker/cli/pull/6502)
* Go SDK: cli/config/configfile: remove deprecated `ConfigFile.Experimental` field. [docker/cli#6464](https://github.com/docker/cli/pull/6464)
* Go SDK: cli/config/types: remove deprecated `AuthConfig.Email` field. [docker/cli#6515](https://github.com/docker/cli/pull/6515)
* Go SDK: cli/manifest/store: remove deprecated `IsNotFound`. [docker/cli#6523](https://github.com/docker/cli/pull/6523)
* Go SDK: cli: remove deprecated `VisitAll`, `DisableFlagsInUseLine` utilities. [docker/cli#6296](https://github.com/docker/cli/pull/6296)
* Go SDK: client: remove `APIClient.ImageInspectWithRaw` from the `APIClient` interface. [moby/moby#50485](https://github.com/moby/moby/pull/50485)
* Go SDK: client: remove `ImageAPIClient.ImageInspectWithRaw` from the `ImageAPIClient` interface. [moby/moby#50485](https://github.com/moby/moby/pull/50485)
* Go SDK: client: remove `ImageAPIClientDeprecated.ImageInspectWithRaw` from the `ImageAPIClientDeprecated`. [moby/moby#50485](https://github.com/moby/moby/pull/50485)
* Go SDK: client: remove deprecated `ErrorConnectionFailed` and `IsErrNotFound` functions. [moby/moby#50485](https://github.com/moby/moby/pull/50485)
* Go SDK: client: remove deprecated `NewClient` and `NewEnvClient` functions. [moby/moby#50485](https://github.com/moby/moby/pull/50485)
* Go SDK: client: remove the `CommonAPIClient` interface. [moby/moby#50485](https://github.com/moby/moby/pull/50485)
* Go SDK: client: remove the `ImageAPIClientDeprecated` interface. [moby/moby#50485](https://github.com/moby/moby/pull/50485)
* Go SDK: client: remove the deprecated `Client.ImageInspectWithRaw` method. [moby/moby#50485](https://github.com/moby/moby/pull/50485)
* Go SDK: container: remove deprecated `IsValidHealthString`. [moby/moby#50378](https://github.com/moby/moby/pull/50378)
* Go SDK: container: remove deprecated `IsValidStateString`. [moby/moby#50378](https://github.com/moby/moby/pull/50378)
* Go SDK: container: remove deprecated `StateStatus`, `WaitCondition`, and the related `WaitConditionNotRunning`, `WaitConditionNextExit`, and `WaitConditionRemoved` consts. [moby/moby#50378](https://github.com/moby/moby/pull/50378)
* Go SDK: deprecate `pkg/stdcopy`, which was moved to `api/pkg/stdcopy`. [moby/moby#50462](https://github.com/moby/moby/pull/50462)
* Go SDK: Deprecate field `NetworkSettingsBase.Bridge`, struct `NetworkSettingsBase`, all the fields of `DefaultNetworkSettings`, and struct `DefaultNetworkSettings`. [moby/moby#50848](https://github.com/moby/moby/pull/50848)
* Go SDK: deprecate pkg/stringid in favour of `github.com/moby/moby/client/pkg/stringid`. [moby/moby#50504](https://github.com/moby/moby/pull/50504)
* Go SDK: deprecate profiles package which got migrated to `github.com/moby/profiles`. [moby/moby#50481](https://github.com/moby/moby/pull/50481)
* Go SDK: oci: deprecate SetCapabilities, and some minor cleanups/fixes. [moby/moby#50461](https://github.com/moby/moby/pull/50461)
* Go SDK: opts: remove deprecated `ListOpts.GetAll`. It's no longer used and replaced by `ListOpts.GetSlice`. [docker/cli#6293](https://github.com/docker/cli/pull/6293)
* Go SDK: opts: remove deprecated `NewNamedListOptsRef`, `NewNamedMapOpts`, `NamedListOpts`, `NamedMapOpts`, and `NamedOption`. These types and functions are no longer used and will be removed in the next release. [docker/cli#6293](https://github.com/docker/cli/pull/6293)
* Go SDK: opts: remove deprecated `ParseEnvFile` in favour of `kvfile.Parse`. [docker/cli#6382](https://github.com/docker/cli/pull/6382)
* Go SDK: opts: remove deprecated `QuotedString`. [docker/cli#6293](https://github.com/docker/cli/pull/6293)
* Go SDK: opts: remove deprecated `ValidateHost`. [docker/cli#6293](https://github.com/docker/cli/pull/6293)
* Go SDK: pkg/system was removed, and is now an internal package. [moby/moby#50559](https://github.com/moby/moby/pull/50559)
* Go SDK: pkg/system: deprecate `EscapeArgs()` and `IsAbs`. These functions were only used internally and will be removed in the next release. [moby/moby#50399](https://github.com/moby/moby/pull/50399)
* Go SDK: registry: remove deprecated `APIEndpoint.TrimHostName`, `APIEndpoint.Official`, and `APIEndpoint.AllowNondistributableArtifacts` fields. [moby/moby#50376](https://github.com/moby/moby/pull/50376)
* Go SDK: registry: remove deprecated `HostCertsDir()` and `SetCertsDir()` functions. [moby/moby#50373](https://github.com/moby/moby/pull/50373)
* Go SDK: registry: remove deprecated `RepositoryInfo.Official` and `RepositoryInfo.Class` field. [moby/moby#50498](https://github.com/moby/moby/pull/50498)
* Go SDK: registry: remove deprecated `Service.ResolveRepository()`. [moby/moby#50374](https://github.com/moby/moby/pull/50374)
* Go SDK: Remove `buildkit.ClientOpts`. [moby/moby#50318](https://github.com/moby/moby/pull/50318)
* Go SDK: remove `pkg/fileutils`. [moby/moby#50558](https://github.com/moby/moby/pull/50558)
* Go SDK: Remove deprecated `IsNotFound`, `CommandAnnotationPlugin`, `CommandAnnotationPluginVendor`, `CommandAnnotationPluginVersion`, `CommandAnnotationPluginInvalid`, `CommandAnnotationPluginCommandPath`, `NamePrefix`, `MetadataSubcommandName`, `HookSubcommandName`, `Metadata`, and `ReexecEnvvar` from `cli-plugins/manager` in favor of their `cli-plugins/manager/metadata` equivalents. [docker/cli#6414](https://github.com/docker/cli/pull/6414)
* Go SDK: remove deprecated `types/plugins/logdriver` and `types/swarm/runtime` packages; plugin-runtime spec is now exposed as `types/swarm.RuntimeSpec` and `types/swarm.RuntimePrivilege`. [moby/moby#50554](https://github.com/moby/moby/pull/50554)
* Go SDK: remove deprecated `cli/command/formatter` package. [docker/cli#6406](https://github.com/docker/cli/pull/6406)
* Go SDK: remove deprecated `cli/registry/client` package. [docker/cli#6462](https://github.com/docker/cli/pull/6462)
* Go SDK: remove deprecated `pkg/idtools` package. [moby/moby#50456](https://github.com/moby/moby/pull/50456)
* Go SDK: templates: remove deprecated `NewParse` function. [docker/cli#6453](https://github.com/docker/cli/pull/6453)
* Hide the `--kernel-memory` option on `docker run` and `docker create`, and produce a warning when used as it's no longer supported by the daemon and kernel. [docker/cli#6455](https://github.com/docker/cli/pull/6455)
* Remove `VirtualSize` field from `docker image ls` output when using JSON format. [docker/cli#6524](https://github.com/docker/cli/pull/6524)
* Remove `VirtualSize` formatting options and output. [docker/cli#6524](https://github.com/docker/cli/pull/6524)
* Remove API version compatibility for API version < v1.44 (Docker v24.0 and older). [docker/cli#6551](https://github.com/docker/cli/pull/6551)
* Remove deprecated `bind-nonrecursive` option for `--mount`. [docker/cli#6241](https://github.com/docker/cli/pull/6241)
* Remove deprecated packages (`pkg/archive`, `pkg/chrootarchive`, `pkg/atomicwriter`, `pkg/reexec`, `pkg/platform`, `pkg/parsers`), `pkg/system.MkdirAll`. For replacements, see `github.com/moby/go-archive`, `github.com/moby/sys` and the standard library. [moby/moby#50208](https://github.com/moby/moby/pull/50208)
* Remove special handling for quoted values for the `--tlscacert`, `--tlscert`, and `--tlskey` command-line flags. [docker/cli#6306](https://github.com/docker/cli/pull/6306)
* Remove support for AutoRemove (`--rm`) on API < 1.30. [docker/cli#6525](https://github.com/docker/cli/pull/6525)
* Remove support for loading legacy (pre-Docker 1.10) images. [moby/moby#50324](https://github.com/moby/moby/pull/50324)

----
url: https://docs.docker.com/docker-hub/repos/manage/hub-images/
----

# Image management

***

***

Docker Hub provides powerful features for managing and organizing your repository content, ensuring that your images and artifacts are accessible, version-controlled, and easy to share. This section covers key image management tasks, including tagging, pushing images, transferring images between repositories, and supported software artifacts.

* [Tags](https://docs.docker.com/docker-hub/repos/manage/hub-images/tags/): Tags help you version and organize different iterations of your images within a single repository. This topic explains tagging and provides guidance on how to create, view, and delete tags in Docker Hub.
* [Image Management](https://docs.docker.com/docker-hub/repos/manage/hub-images/manage/): View, filter, and delete images and image indexes in your repository.
* [Software artifacts](https://docs.docker.com/docker-hub/repos/manage/hub-images/oci-artifacts/): Docker Hub supports OCI (Open Container Initiative) artifacts, allowing you to store, manage, and distribute a range of content beyond standard Docker images, including Helm charts, vulnerability reports, and more. This section provides an overview of OCI artifacts as well as some examples of pushing them to Docker Hub.
* [Push images to Hub](https://docs.docker.com/docker-hub/repos/manage/hub-images/push/): Docker Hub enables you to push local images to it, making them available for your team or the Docker community. Learn how to configure your images and use the `docker push` command to upload them to Docker Hub.
* [Move images between repositories](https://docs.docker.com/docker-hub/repos/manage/hub-images/move/): Organizing content across different repositories can help streamline collaboration and resource management. This topic details how to move images from one Docker Hub repository to another, whether for personal consolidation or to share images with an organization.

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/server/
----

# docker mcp catalog server

***

| Description | Manage servers in catalogs |
| ----------- | -------------------------- |

## [Description](#description)

Manage servers in catalogs

## [Subcommands](#subcommands)

| Command                                                                                                         | Description                       |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| [`docker mcp catalog server add`](https://docs.docker.com/reference/cli/docker/mcp/catalog/server/add/)         | Add MCP servers to a catalog      |
| [`docker mcp catalog server inspect`](https://docs.docker.com/reference/cli/docker/mcp/catalog/server/inspect/) | Inspect a server in a catalog     |
| [`docker mcp catalog server ls`](https://docs.docker.com/reference/cli/docker/mcp/catalog/server/ls/)           | List servers in a catalog         |
| [`docker mcp catalog server remove`](https://docs.docker.com/reference/cli/docker/mcp/catalog/server/remove/)   | Remove MCP servers from a catalog |

----
url: https://docs.docker.com/guides/dotnet/
----

# .NET language-specific guide

***

Learn how to containerize .NET applications using Docker.

**Time to complete** 20 minutes

The .NET getting started guide teaches you how to create a containerized .NET application using Docker. In this guide, you'll learn how to:

* Containerize and run a .NET application
* Set up a local environment to develop a .NET application using containers
* Run tests for a .NET application using containers
* Configure a CI/CD pipeline for a containerized .NET application using GitHub Actions
* Deploy your containerized application locally to Kubernetes to test and debug your deployment

After completing the .NET getting started modules, you should be able to containerize your own .NET application based on the examples and instructions provided in this guide.

Start by containerizing an existing .NET application.

## [Modules](#modules)

1. [Containerize your app](https://docs.docker.com/guides/dotnet/containerize/)

   Learn how to containerize an ASP.NET application.

2. [Develop your app](https://docs.docker.com/guides/dotnet/develop/)

   Learn how to develop your .NET application locally using containers.

3. [Run your tests](https://docs.docker.com/guides/dotnet/run-tests/)

   Learn how to run your .NET tests in a container.

4. [Configure CI/CD](https://docs.docker.com/guides/dotnet/configure-ci-cd/)

   Learn how to Configure CI/CD for your .NET application

5. [Test your deployment](https://docs.docker.com/guides/dotnet/deploy/)

   Learn how to deploy your application

----
url: https://docs.docker.com/extensions/extensions-sdk/build/backend-extension-tutorial/
----

# Add a backend to your extension

***

Table of contents

***

Your extension can ship a backend part with which the frontend can interact with. This page provides information on why and how to add a backend.

Before you start, make sure you have installed the latest version of [Docker Desktop](https://www.docker.com/products/docker-desktop/).

> Tip
>
> Check the [Quickstart guide](https://docs.docker.com/extensions/extensions-sdk/quickstart/) and `docker extension init <my-extension>`. They provide a better base for your extension as it's more up-to-date and related to your install of Docker Desktop.

## [Why add a backend?](#why-add-a-backend)

Thanks to the Docker Extensions SDK, most of the time you should be able to do what you need from the Docker CLI directly from [the frontend](https://docs.docker.com/extensions/extensions-sdk/build/frontend-extension-tutorial/#use-the-extension-apis-client).

Nonetheless, there are some cases where you might need to add a backend to your extension. So far, extension builders have used the backend to:

* Store data in a local database and serve them back with a REST API.
* Store the extension state, for example when a button starts a long-running process, so that if you navigate away from the extension user interface and comes back, the frontend can pick up where it left off.

For more information about extension backends, see [Architecture](https://docs.docker.com/extensions/extensions-sdk/architecture/#the-backend).

## [Add a backend to the extension](#add-a-backend-to-the-extension)

If you created your extension using the `docker extension init` command, you already have a backend setup. Otherwise, you have to first create a `vm` directory that contains the code and updates the Dockerfile to containerize it.

Here is the extension folder structure with a backend:

```bash
.
├── Dockerfile # (1)
├── Makefile
├── metadata.json
├── ui
    └── index.html
└── vm # (2)
    ├── go.mod
    └── main.go
```

1. Contains everything required to build the backend and copy it in the extension's container filesystem.
2. The source folder that contains the backend code of the extension.

Although you can start from an empty directory or from the `vm-ui extension` [sample](https://github.com/docker/extensions-sdk/tree/main/samples), it is highly recommended that you start from the `docker extension init` command and change it to suit your needs.

> Tip
>
> The `docker extension init` generates a Go backend. But you can still use it as a starting point for your own extension and use any other language like Node.js, Python, Java, .Net, or any other language and framework.

In this tutorial, the backend service simply exposes one route that returns a JSON payload that says "Hello".

```json
{ "Message": "Hello" }
```

> Important
>
> We recommend that, the frontend and the backend communicate through sockets, and named pipes on Windows, instead of HTTP. This prevents port collision with any other running application or container running on the host. Also, some Docker Desktop users are running in constrained environments where they can't open ports on their machines. When choosing the language and framework for your backend, make sure it supports sockets connection.

```go
package main

import (
	"flag"
	"log"
	"net"
	"net/http"
	"os"

	"github.com/labstack/echo"
	"github.com/sirupsen/logrus"
)

func main() {
	var socketPath string
	flag.StringVar(&socketPath, "socket", "/run/guest/volumes-service.sock", "Unix domain socket to listen on")
	flag.Parse()

	os.RemoveAll(socketPath)

	logrus.New().Infof("Starting listening on %s\n", socketPath)
	router := echo.New()
	router.HideBanner = true

	startURL := ""

	ln, err := listen(socketPath)
	if err != nil {
		log.Fatal(err)
	}
	router.Listener = ln

	router.GET("/hello", hello)

	log.Fatal(router.Start(startURL))
}

func listen(path string) (net.Listener, error) {
	return net.Listen("unix", path)
}

func hello(ctx echo.Context) error {
	return ctx.JSON(http.StatusOK, HTTPMessageBody{Message: "hello world"})
}

type HTTPMessageBody struct {
	Message string
}
```

> Important
>
> We don't have a working example for Node yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.25798127=Node) and let us know if you'd like a sample for Node.

> Important
>
> We don't have a working example for Python yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.25798127=Python) and let us know if you'd like a sample for Python.

> Important
>
> We don't have a working example for Java yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.25798127=Java) and let us know if you'd like a sample for Java.

> Important
>
> We don't have a working example for .NET. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.25798127=.Net) and let us know if you'd like a sample for .NET.

## [Adapt the Dockerfile](#adapt-the-dockerfile)

> Note
>
> When using the `docker extension init`, it creates a `Dockerfile` that already contains what is needed for a Go backend.

To deploy your Go backend when installing the extension, you need first to configure the `Dockerfile`, so that it:

* Builds the backend application
* Copies the binary in the extension's container filesystem
* Starts the binary when the container starts listening on the extension socket

> Tip
>
> To ease version management, you can reuse the same image to build the frontend, build the backend service, and package the extension.

```dockerfile
# syntax=docker/dockerfile:1
FROM node:17.7-alpine3.14 AS client-builder
# ... build frontend application

# Build the Go backend
FROM golang:1.17-alpine AS builder
ENV CGO_ENABLED=0
WORKDIR /backend
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    --mount=type=bind,source=vm/.,target=. \
    go build -trimpath -ldflags="-s -w" -o bin/service

FROM alpine:3.15
# ... add labels and copy the frontend application

COPY --from=builder /backend/bin/service /
CMD /service -socket /run/guest-services/extension-allthethings-extension.sock
```

> Important
>
> We don't have a working Dockerfile for Node yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.25798127=Node) and let us know if you'd like a Dockerfile for Node.

> Important
>
> We don't have a working Dockerfile for Python yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.25798127=Python) and let us know if you'd like a Dockerfile for Python.

> Important
>
> We don't have a working Dockerfile for Java yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.25798127=Java) and let us know if you'd like a Dockerfile for Java.

> Important
>
> We don't have a working Dockerfile for .Net. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.25798127=.Net) and let us know if you'd like a Dockerfile for .Net.

## [Configure the metadata file](#configure-the-metadata-file)

To start the backend service of your extension inside the VM of Docker Desktop, you have to configure the image name in the `vm` section of the `metadata.json` file.

```json
{
  "vm": {
    "image": "${DESKTOP_PLUGIN_IMAGE}"
  },
  "icon": "docker.svg",
  "ui": {
    ...
  }
}
```

For more information on the `vm` section of the `metadata.json`, see [Metadata](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/).

> Warning
>
> Do not replace the `${DESKTOP_PLUGIN_IMAGE}` placeholder in the `metadata.json` file. The placeholder is replaced automatically with the correct image name when the extension is installed.

## [Invoke the extension backend from your frontend](#invoke-the-extension-backend-from-your-frontend)

Using the [advanced frontend extension example](https://docs.docker.com/extensions/extensions-sdk/build/frontend-extension-tutorial/), we can invoke our extension backend.

Use the Docker Desktop Client object and then invoke the `/hello` route from the backend service with `ddClient. extension.vm.service.get` that returns the body of the response.

Replace the `ui/src/App.tsx` file with the following code:

```tsx

// ui/src/App.tsx
import React, { useEffect } from 'react';
import { createDockerDesktopClient } from "@docker/extension-api-client";

//obtain docker desktop extension client
const ddClient = createDockerDesktopClient();

export function App() {
  const ddClient = createDockerDesktopClient();
  const [hello, setHello] = useState<string>();

  useEffect(() => {
    const getHello = async () => {
      const result = await ddClient.extension.vm?.service?.get('/hello');
      setHello(JSON.stringify(result));
    }
    getHello()
  }, []);

  return (
    <Typography>{hello}</Typography>
  );
}
```

> Important
>
> We don't have an example for Vue yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Vue) and let us know if you'd like a sample with Vue.

> Important
>
> We don't have an example for Angular yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Angular) and let us know if you'd like a sample with Angular.

> Important
>
> We don't have an example for Svelte yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Svelte) and let us know if you'd like a sample with Svelte.

## [Re-build the extension and update it](#re-build-the-extension-and-update-it)

Since you have modified the configuration of the extension and added a stage in the Dockerfile, you must re-build the extension.

```bash
docker build --tag=awesome-inc/my-extension:latest .
```

Once built, you need to update it, or install it if you haven't already done so.

```bash
docker extension update awesome-inc/my-extension:latest
```

Now you can see the backend service running in the **Containers** view of the Docker Desktop Dashboard and watch the logs when you need to debug it.

> Tip
>
> You may need to turn on the **Show system containers** option in **Settings** to see the backend container running. See [Show extension containers](https://docs.docker.com/extensions/extensions-sdk/dev/test-debug/#show-the-extension-containers) for more information.

Open the Docker Desktop Dashboard and select the **Containers** tab. You should see the response from the backend service call displayed.

## [What's next?](#whats-next)

* Learn how to [share and publish your extension](https://docs.docker.com/extensions/extensions-sdk/extensions/).
* Learn more about extensions [architecture](https://docs.docker.com/extensions/extensions-sdk/architecture/).

----
url: https://docs.docker.com/reference/cli/docker/network/create/
----

# docker network create

***

| Description | Create a network                          |
| ----------- | ----------------------------------------- |
| Usage       | `docker network create [OPTIONS] NETWORK` |

## [Description](#description)

Creates a new network. The `DRIVER` accepts `bridge` or `overlay` which are the built-in network drivers. If you have installed a third party or your own custom network driver you can specify that `DRIVER` here also. If you don't specify the `--driver` option, the command automatically creates a `bridge` network for you. When you install Docker Engine it creates a `bridge` network automatically. This network corresponds to the `docker0` bridge that Docker Engine has traditionally relied on. When you launch a new container with `docker run` it automatically connects to this bridge network. You cannot remove this default bridge network, but you can create new ones using the `network create` command.

```console
$ docker network create -d bridge my-bridge-network
```

Bridge networks are isolated networks on a single Docker Engine installation. If you want to create a network that spans multiple Docker hosts each running Docker Engine, you must enable Swarm mode, and create an `overlay` network. To read more about overlay networks with Swarm mode, see ["*use overlay networks*"](/network/overlay/).

Once you have enabled swarm mode, you can create a swarm-scoped overlay network:

```console
$ docker network create --scope=swarm --attachable -d overlay my-multihost-network
```

By default, swarm-scoped networks do not allow manually started containers to be attached. This restriction is added to prevent someone that has access to a non-manager node in the swarm cluster from running a container that is able to access the network stack of a swarm service.

The `--attachable` option used in the example above disables this restriction, and allows for both swarm services and manually started containers to attach to the overlay network.

Network names must be unique. The Docker daemon attempts to identify naming conflicts but this is not guaranteed. It is the user's responsibility to avoid name conflicts.

### [Overlay network limitations](#overlay-network-limitations)

You should create overlay networks with `/24` blocks (the default), which limits you to 256 IP addresses, when you create networks using the default VIP-based endpoint-mode. This recommendation addresses [limitations with swarm mode](https://github.com/moby/moby/issues/30820). If you need more than 256 IP addresses, do not increase the IP block size. You can either use `dnsrr` endpoint mode with an external load balancer, or use multiple smaller overlay networks. See [Configure service discovery](/engine/swarm/networking/#configure-service-discovery) for more information about different endpoint modes.

## [Options](#options)

| Option                    | Default  | Description                                                |
| ------------------------- | -------- | ---------------------------------------------------------- |
| `--attachable`            |          | API 1.25+ Enable manual container attachment               |
| `--aux-address`           |          | Auxiliary IPv4 or IPv6 addresses used by Network driver    |
| `--config-from`           |          | API 1.30+ The network from which to copy the configuration |
| `--config-only`           |          | API 1.30+ Create a configuration only network              |
| `-d, --driver`            | `bridge` | Driver to manage the Network                               |
| `--gateway`               |          | IPv4 or IPv6 Gateway for the master subnet                 |
| [`--ingress`](#ingress)   |          | API 1.29+ Create swarm routing-mesh network                |
| [`--internal`](#internal) |          | Restrict external access to the network                    |
| `--ip-range`              |          | Allocate container ip from a sub-range                     |
| `--ipam-driver`           |          | IP Address Management Driver                               |
| `--ipam-opt`              |          | Set IPAM driver specific options                           |
| `--ipv4`                  | `true`   | Enable or disable IPv4 address assignment                  |
| `--ipv6`                  |          | Enable or disable IPv6 address assignment                  |
| `--label`                 |          | Set metadata on a network                                  |
| `-o, --opt`               |          | Set driver specific options                                |
| `--scope`                 |          | API 1.30+ Control the network's scope                      |
| `--subnet`                |          | Subnet in CIDR format that represents a network segment    |

## [Examples](#examples)

### [Connect containers](#connect-containers)

When you start a container, use the `--network` flag to connect it to a network. This example adds the `busybox` container to the `mynet` network:

```console
$ docker run -itd --network=mynet busybox
```

If you want to add a container to a network after the container is already running, use the `docker network connect` subcommand.

You can connect multiple containers to the same network. Once connected, the containers can communicate using only another container's IP address or name. For `overlay` networks or custom plugins that support multi-host connectivity, containers connected to the same multi-host network but launched from different daemons can also communicate in this way.

You can disconnect a container from a network using the `docker network disconnect` command.

### [Specify advanced options](#specify-advanced-options)

When you create a network, Docker Engine creates a non-overlapping subnetwork for the network by default. This subnetwork is not a subdivision of an existing network. It is purely for ip-addressing purposes. You can override this default and specify subnetwork values directly using the `--subnet` option. On a `bridge` network you can only create a single subnet:

```console
$ docker network create --driver=bridge --subnet=192.168.0.0/16 br0
```

Additionally, you also specify the `--gateway` `--ip-range` and `--aux-address` options.

```console
$ docker network create \
  --driver=bridge \
  --subnet=172.28.0.0/16 \
  --ip-range=172.28.5.0/24 \
  --gateway=172.28.5.254 \
  br0
```

If you omit the `--gateway` flag, Docker Engine selects one for you from inside a preferred pool. For `overlay` networks and for network driver plugins that support it you can create multiple subnetworks. This example uses two `/25` subnet mask to adhere to the current guidance of not having more than 256 IPs in a single overlay network. Each of the subnetworks has 126 usable addresses.

```console
$ docker network create -d overlay \
  --subnet=192.168.10.0/25 \
  --subnet=192.168.20.0/25 \
  --gateway=192.168.10.100 \
  --gateway=192.168.20.100 \
  --aux-address="my-router=192.168.10.5" --aux-address="my-switch=192.168.10.6" \
  --aux-address="my-printer=192.168.20.5" --aux-address="my-nas=192.168.20.6" \
  my-multihost-network
```

Be sure that your subnetworks do not overlap. If they do, the network create fails and Docker Engine returns an error.

### [Bridge driver options](#bridge-driver-options)

When creating a custom `bridge` network, the following additional options can be passed. Some of these have equivalent flags that can be used on the dockerd command line or in `daemon.json` to configure the default bridge, `docker0`:

| Network create option                            | Daemon option for `docker0` | Description                                           |
| ------------------------------------------------ | --------------------------- | ----------------------------------------------------- |
| `com.docker.network.bridge.name`                 | -                           | Bridge name to be used when creating the Linux bridge |
| `com.docker.network.bridge.enable_ip_masquerade` | `--ip-masq`                 | Enable IP masquerading                                |
| `com.docker.network.bridge.enable_icc`           | `--icc`                     | Enable or Disable Inter Container Connectivity        |
| `com.docker.network.bridge.host_binding_ipv4`    | `--ip`                      | Default IP when binding container ports               |
| `com.docker.network.driver.mtu`                  | `--mtu`                     | Set the containers network MTU                        |
| `com.docker.network.container_iface_prefix`      | -                           | Set a custom prefix for container interfaces          |

The following arguments can be passed to `docker network create` for any network driver, again with their approximate equivalents to Docker daemon flags used for the `docker0` bridge:

| Network create option | Daemon option for `docker0`       | Description                                |
| --------------------- | --------------------------------- | ------------------------------------------ |
| `--gateway`           | -                                 | IPv4 or IPv6 Gateway for the master subnet |
| `--ip-range`          | `--fixed-cidr`, `--fixed-cidr-v6` | Allocate IP addresses from a range         |
| `--internal`          | -                                 | Restrict external access to the network    |
| `--ipv4`              | -                                 | Enable or disable IPv4 address assignment  |
| `--ipv6`              | `--ipv6`                          | Enable or disable IPv6 address assignment  |
| `--subnet`            | `--bip`, `--bip6`                 | Subnet for network                         |

For example, let's use `-o` or `--opt` options to specify an IP address binding when publishing ports:

```console
$ docker network create \
    -o "com.docker.network.bridge.host_binding_ipv4"="172.19.0.1" \
    simple-network
```

### [Network internal mode (--internal)](#internal)

Containers on an internal network may communicate between each other, but not with any other network, as no default route is configured and firewall rules are set up to drop all traffic to or from other networks. Communication with the gateway IP address (and thus appropriately configured host services) is possible, and the host may communicate with any container IP directly.

By default, when you connect a container to an `overlay` network, Docker also connects a bridge network to it to provide external connectivity. If you want to create an externally isolated `overlay` network, you can specify the `--internal` option.

### [Network ingress mode (--ingress)](#ingress)

You can create the network which will be used to provide the routing-mesh in the swarm cluster. You do so by specifying `--ingress` when creating the network. Only one ingress network can be created at the time. The network can be removed only if no services depend on it. Any option available when creating an overlay network is also available when creating the ingress network, besides the `--attachable` option.

```console
$ docker network create -d overlay \
  --subnet=10.11.0.0/16 \
  --ingress \
  --opt com.docker.network.driver.mtu=9216 \
  --opt encrypted=true \
  my-ingress-network
```

### [Run services on predefined networks](#run-services-on-predefined-networks)

You can create services on the predefined Docker networks `bridge` and `host`.

```console
$ docker service create --name my-service \
  --network host \
  --replicas 2 \
  busybox top
```

### [Swarm networks with local scope drivers](#swarm-networks-with-local-scope-drivers)

You can create a swarm network with local scope network drivers. You do so by promoting the network scope to `swarm` during the creation of the network. You will then be able to use this network when creating services.

```console
$ docker network create -d bridge \
  --scope swarm \
  --attachable \
  swarm-network
```

For network drivers which provide connectivity across hosts (ex. macvlan), if node specific configurations are needed in order to plumb the network on each host, you will supply that configuration via a configuration only network. When you create the swarm scoped network, you will then specify the name of the network which contains the configuration.

```console
node1$ docker network create --config-only --subnet 192.168.100.0/24 --gateway 192.168.100.115 mv-config
node2$ docker network create --config-only --subnet 192.168.200.0/24 --gateway 192.168.200.202 mv-config
node1$ docker network create -d macvlan --scope swarm --config-from mv-config --attachable swarm-network
```

----
url: https://docs.docker.com/desktop/features/wsl/use-wsl/
----

# Develop with Docker Desktop using WSL 2 on Windows

***

Table of contents

***

The following section describes how to start developing your applications using Docker and WSL 2.

For the best development experience, store your code inside your default Linux distribution. After you have turned on the WSL 2 feature on Docker Desktop, you can start working with your code inside the Linux distribution and ideally with your IDE still in Windows. This workflow is straightforward if you are using [VS Code](https://code.visualstudio.com/download).

## [Develop with Docker and WSL 2](#develop-with-docker-and-wsl-2)

Before you begin, make sure you have enabled WSL 2 integration in Docker Desktop under **Settings** > **Resources** > **WSL Integration**.

1. Open VS Code and install the [WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) extension. This extension lets you work with a remote server in the Linux distribution and your IDE client still on Windows.

2. Open your terminal and type:

   ```console
   $ wsl
   ```

3. Navigate to your project directory and then type:

   ```console
   $ code .
   ```

   This opens a new VS Code window connected remotely to your default Linux distribution which you can check in the bottom corner of the screen.

Alternatively, you can open your default Linux distribution from the **Start** menu, navigate to your project directory, and then run `code .`

----
url: https://docs.docker.com/docker-hub/repos/manage/vulnerability-scanning/
----

# Image security insights

***

Table of contents

***

Strengthen the security of your Docker images with Docker Hub's image security insights. Docker Hub lets you perform either point-in-time static vulnerability scanning or always up-to-date image analysis using Docker Scout.

## [Docker Scout image analysis](#docker-scout-image-analysis)

After turning on Docker Scout image analysis, Docker Scout automatically analyzes images in your Docker Hub repository.

Image analysis extracts the Software Bill of Material (SBOM) and other image metadata, and evaluates it against vulnerability data from security advisories.

The following sections describe how to turn on or off Docker Scout image analysis for a Docker Hub repository. For more details about the image analysis, see [Docker Scout](https://docs.docker.com/scout/).

### [Turn on Docker Scout image analysis](#turn-on-docker-scout-image-analysis)

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Settings** tab.

5. Under **Image security insight settings**, select **Docker Scout image analysis**.

6. Select **Save**.

### [Turn off Docker Scout image analysis](#turn-off-docker-scout-image-analysis)

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Settings** tab.

5. Under **Image security insight settings**, select **None**.

6. Select **Save**.

## [Static vulnerability scanning](#static-vulnerability-scanning)

> Note
>
> Docker Hub static vulnerability scanning requires a Docker Pro, Team, or Business subscription.

When you push an image to a Docker Hub repository after turning on static scanning, Docker Hub automatically scans the image to identify vulnerabilities. The scan results shows the security state of your images at the time when the scan was run.

Scan results include:

* The source of the vulnerability, such as Operating System (OS) packages and libraries
* The version in which it was introduced
* A recommended fixed version, if available, to remediate the vulnerabilities discovered.

### [Changes to static scanning in Docker Hub](#changes-to-static-scanning-in-docker-hub)

From February 27th, 2023, Docker changed the technology that supports the Docker Hub static scanning feature. The static scanning is now powered natively by Docker, instead of a third-party.

As a result of this change, scanning now detects vulnerabilities at a more granular level than before. This in turn means that vulnerability reports may show a higher number of vulnerabilities. If you used vulnerability scanning before February 27th, 2023, you may see that new vulnerability reports list a higher number of vulnerabilities, due to a more thorough analysis.

There is no action required on your part. Scans continue to run as usual with no interruption or changes to pricing. Historical data continues to be available.

### [Turn on static vulnerability scanning](#turn-on-static-vulnerability-scanning)

Repository owners and administrators can enable static vulnerability scanning on a repository. If you are a member of a Team or a Business subscription, ensure the repository you would like to enable scanning on is part of the Team or a Business tier.

When scanning is active on a repository, anyone with push access can trigger a scan by pushing an image to Docker Hub.

To enable static vulnerability scanning:

> Note
>
> Static vulnerability scanning supports scanning images which are of AMD64 architecture, Linux OS, and are less than 10 GB in size.

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Settings** tab.

5. Under **Image security insight settings**, select **Static scanning**.

6. Select **Save**.

### [Scan an image](#scan-an-image)

To scan an image for vulnerabilities, push the image to Docker Hub, to the repository for which you have turned on scanning.

### [View the vulnerability report](#view-the-vulnerability-report)

To view the vulnerability report:

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears. It may take a couple of minutes for the vulnerability report to appear in your repository.

4. Select the **Tags** tab, then **Digest**, then **Vulnerabilities** to view the detailed scan report.

   The scan report displays vulnerabilities identified by the scan, sorting them according to their severity, with highest severity listed at the top. It displays information about the package that contains the vulnerability, the version in which it was introduced, and whether the vulnerability is fixed in a later version.

For more information on this view, see [Image details view](https://docs.docker.com/scout/explore/image-details-view/).

### [Inspect vulnerabilities](#inspect-vulnerabilities)

The vulnerability report sorts vulnerabilities based on their severity. It displays information about the package that contains the vulnerability, the version in which it was introduced, and whether the vulnerability has been fixed in a later version.

The vulnerability scan report also allows development teams and security leads to compare the vulnerability counts across tags to see whether the vulnerabilities are decreasing or increasing over time.

### [Fix vulnerabilities](#fix-vulnerabilities)

Once a list of vulnerabilities have been identified, there are a couple of actions you can take to remediate the vulnerabilities. For example, you can:

1. Specify an updated base image in the Dockerfile, check your application-level dependencies, rebuild the Docker image, and then push the new image to Docker Hub.
2. Rebuild the Docker image, run an update command on the OS packages, and push a newer version of image to Docker Hub.
3. Edit the Dockerfile to manually remove or update specific libraries that contain vulnerabilities, rebuild the image, and push the new image to Docker Hub

Docker Scout can provide you with concrete and contextual remediation steps for improving image security. For more information, see [Docker Scout](https://docs.docker.com/scout/).

### [Turn off static vulnerability scanning](#turn-off-static-vulnerability-scanning)

Repository owners and administrators can disable static vulnerability scanning on a repository. To disable scanning:

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Settings** tab.

5. Under **Image security insight settings**, select **None**.

6. Select **Save**.

----
url: https://docs.docker.com/build/cache/backends/local/
----

# Local cache

***

Table of contents

***

The `local` cache store is a simple cache option that stores your cache as files in a directory on your filesystem, using an [OCI image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) for the underlying directory structure. Local cache is a good choice if you're just testing, or if you want the flexibility to self-manage a shared storage solution.

## [Synopsis](#synopsis)

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=local,dest=path/to/local/dir[,parameters...] \
  --cache-from type=local,src=path/to/local/dir .
```

The following table describes the available CSV parameters that you can pass to `--cache-to` and `--cache-from`.

| Name                | Option       | Type                    | Default | Description                                                                                                                                                                                 |
| ------------------- | ------------ | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src`               | `cache-from` | String                  |         | Path of the local directory where cache gets imported from.                                                                                                                                 |
| `digest`            | `cache-from` | String                  |         | Digest of manifest to import, see [cache versioning](#cache-versioning).                                                                                                                    |
| `dest`              | `cache-to`   | String                  |         | Path of the local directory where cache gets exported to.                                                                                                                                   |
| `mode`              | `cache-to`   | `min`,`max`             | `min`   | Cache layers to export, see [cache mode](https://docs.docker.com/build/cache/backends/#cache-mode).                                                                                         |
| `oci-mediatypes`    | `cache-to`   | `true`,`false`          | `true`  | Use OCI media types in exported manifests, see [OCI media types](https://docs.docker.com/build/cache/backends/#oci-media-types).                                                            |
| `image-manifest`    | `cache-to`   | `true`,`false`          | `true`  | When using OCI media types, generate an image manifest instead of an image index for the cache image, see [OCI media types](https://docs.docker.com/build/cache/backends/#oci-media-types). |
| `compression`       | `cache-to`   | `gzip`,`estargz`,`zstd` | `gzip`  | Compression type, see [cache compression](https://docs.docker.com/build/cache/backends/#cache-compression).                                                                                 |
| `compression-level` | `cache-to`   | `0..22`                 |         | Compression level, see [cache compression](https://docs.docker.com/build/cache/backends/#cache-compression).                                                                                |
| `force-compression` | `cache-to`   | `true`,`false`          | `false` | Forcibly apply compression, see [cache compression](https://docs.docker.com/build/cache/backends/#cache-compression).                                                                       |
| `ignore-error`      | `cache-to`   | Boolean                 | `false` | Ignore errors caused by failed cache exports.                                                                                                                                               |

If the `src` cache doesn't exist, then the cache import step will fail, but the build continues.

## [Cache versioning](#cache-versioning)

This section describes how versioning works for caches on a local filesystem, and how you can use the `digest` parameter to use older versions of cache.

If you inspect the cache directory manually, you can see the resulting OCI image layout:

```console
$ ls cache
blobs  index.json  ingest
$ cat cache/index.json | jq
{
  "schemaVersion": 2,
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.index.v1+json",
      "digest": "sha256:6982c70595cb91769f61cd1e064cf5f41d5357387bab6b18c0164c5f98c1f707",
      "size": 1560,
      "annotations": {
        "org.opencontainers.image.ref.name": "latest"
      }
    }
  ]
}
```

Like other cache types, local cache gets replaced on export, by replacing the contents of the `index.json` file. However, previous caches will still be available in the `blobs` directory. These old caches are addressable by digest, and kept indefinitely. Therefore, the size of the local cache will continue to grow (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896) for more information).

When importing cache using `--cache-from`, you can specify the `digest` parameter to force loading an older version of the cache, for example:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=local,dest=path/to/local/dir \
  --cache-from type=local,ref=path/to/local/dir,digest=sha256:6982c70595cb91769f61cd1e064cf5f41d5357387bab6b18c0164c5f98c1f707 .
```

## [Further reading](#further-reading)

For an introduction to caching see [Docker build cache](https://docs.docker.com/build/cache/).

For more information on the `local` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#local-directory-1).

----
url: https://docs.docker.com/guides/wiremock/
----

[Mocking API services in development and testing with WireMock](https://docs.docker.com/guides/wiremock/)

Mocking API services in development and testing with WireMock

JavaScript App development Distributed systems

20 minutes

[« Back to all guides](/guides/)

# Mocking API services in development and testing with WireMock

***

Table of contents

***

During local development and testing, it's quite common to encounter situations where your app is dependent on the remote APIs. Network issues, rate limits, or even downtime of the API provider can halt your progress. This can significantly hinder your productivity and make testing more challenging. This is where WireMock comes into play.

WireMock is an open-source tool that helps developers to create a mock server that simulates the behavior of real APIs, providing a controlled environment for development and testing.

Imagine you have both an API and a frontend app, and you want to test how the frontend interacts with the API. Using WireMock, you can set up a mock server to simulate the API's responses, allowing you to test the frontend behavior without relying on the actual API. This can be particularly helpful when the API is still under development or when you want to test different scenarios without affecting the actual API. WireMock supports both HTTP and HTTPS protocols and can simulate various response scenarios, including delays, errors, and different HTTP status codes.

In this guide, you'll learn how to:

* Use Docker to launch up a WireMock container.
* Use mock data in the local development without relying on an external API
* Use a Live API in production to fetch real-time weather data from AccuWeather.

## [Using WireMock with Docker](#using-wiremock-with-docker)

The official [Docker image for WireMock](https://hub.docker.com/r/wiremock/wiremock) provides a convenient way to deploy and manage WireMock instances. WireMock is available for various CPU architectures, including amd64, armv7, and armv8, ensuring compatibility with different devices and platforms. You can learn more about WireMock standalone on the [WireMock docs site](https://wiremock.org/docs/standalone/docker/).

### [Prerequisites](#prerequisites)

The following prerequisites are required to follow along with this how-to guide:

* [Docker Desktop](https://www.docker.com/products/docker-desktop/)

### [Launching WireMock](#launching-wiremock)

Launch a quick demo of WireMock by using the following steps:

1. Clone the [GitHub repository](https://github.com/dockersamples/wiremock-node-docker) locally.

   ```console
   $ git clone https://github.com/dockersamples/wiremock-node-docker
   ```

2. Navigate to the `wiremock-endpoint` directory

   ```console
   $ cd wiremock-node-docker/
   ```

   WireMock acts as the mock API that your backend will communicate with to retrieve data. The mock API responses have already been created for you in the mappings directory.

3. Start the Compose stack by running the following command at the root of the cloned project directory

   ```console
   $ docker compose up -d
   ```

   After a moment, the application will be up and running.

   You can check the logs by selecting the `wiremock-node-docker` container:

4. Test the Mock API.

   ```console
   $ curl http://localhost:8080/api/v1/getWeather\?city\=Bengaluru
   ```

   It will return the following canned response with mock data:

   ```plaintext
   {"city":"Bengaluru","temperature":27.1,"conditions":"Mostly cloudy","forecasts":[{"date":"2024-09-02T07:00:00+05:30","temperature":83,"conditions":"Partly sunny w/ t-storms"},{"date":"2024-09-03T07:00:00+05:30","temperature":83,"conditions":"Thunderstorms"},{"date":"2024-09-04T07:00:00+05:30","temperature":83,"conditions":"Intermittent clouds"},{"date":"2024-09-05T07:00:00+05:30","temperature":82,"conditions":"Dreary"},{"date":"2024-09-06T07:00:00+05:30","temperature":82,"conditions":"Dreary"}]}
   ```

   With WireMock, you define canned responses using mapping files. For this request, the mock data is defined in the JSON file at `wiremock-endpoint/mappings/getWeather/getWeatherBengaluru.json`.

   For more information about stubbing canned responses, refer to the [WireMock documentation](https://wiremock.org/docs/stubbing/).

## [Using WireMock in development](#using-wiremock-in-development)

Now that you have tried WireMock, let’s use it in development and testing. In this example, you will use a sample application that has a Node.js backend. This app stack has the following configuration:

* Local Development Environment: The context in which the Node.js backend and WireMock are running.
* Node.js Backend: Represents the backend application that handles HTTP requests.
* External AccuWeather API: The real API from which live weather data is fetched.
* WireMock: The mock server that simulates the API responses during testing. It runs as a Docker container.

- In development, the Node.js backend sends a request to WireMock instead of the actual AccuWeather API.
- In production, it connects directly to the live AccuWeather API for real data.

## [Use mock data in local development](#use-mock-data-in-local-development)

Let’s set up a Node app to send requests to the WireMock container instead of the actual AccuWeather API.

### [Prerequisite](#prerequisite)

* Install [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
* Ensure that WireMock container is up and running (see [Launching Wiremock](#launching-wiremock)

Follow the steps to setup a non-containerized Node application:

1. Navigate to the `accuweather-api` directory

   Make sure you're in the directory where your `package.json` file is located.

2. Set the environment variable.

   Open `.env` file placed under `accuweather-api/` directory. Remove the old entries and ensure that it just contains the following single line.

   ```plaintext
   API_ENDPOINT_BASE=http://localhost:8080
   ```

   This will tell your Node.js application to use the WireMock server for API calls.

3. Examine the Application Entry Point

   * The main file for the application is `index.js`, located in the `accuweather-api/src/api` directory.
   * This file starts the `getWeather.js` module, which is essential for your Node.js application. It uses the `dotenv` package to load environment variables from the`.env` file.
   * Based on the value of `API_ENDPOINT_BASE`, the application routes requests either to the WireMock server (`http://localhost:8080`) or the AccuWeather API. In this setup, it uses the WireMock server.
   * The code ensures that the `ACCUWEATHER_API_KEY` is required only if the application is not using WireMock, enhancing efficiency and avoiding errors.

   ```javascript
   require("dotenv").config();

   const express = require("express");
   const axios = require("axios");

   const router = express.Router();
   const API_ENDPOINT_BASE = process.env.API_ENDPOINT_BASE;
   const API_KEY = process.env.ACCUWEATHER_API_KEY;

   console.log('API_ENDPOINT_BASE:', API_ENDPOINT_BASE);  // Log after it's defined
   console.log('ACCUWEATHER_API_KEY is set:', !!API_KEY); // Log boolean instead of actual key

   if (!API_ENDPOINT_BASE) {
     throw new Error("API_ENDPOINT_BASE is not defined in environment variables");
   }

   // Only check for API key if not using WireMock
   if (API_ENDPOINT_BASE !== 'http://localhost:8080' && !API_KEY) {
     throw new Error("ACCUWEATHER_API_KEY is not defined in environment variables");
   }
   // Function to fetch the location key for the city
   async function fetchLocationKey(townName) {
     const { data: locationData } = await
   axios.get(`${API_ENDPOINT_BASE}/locations/v1/cities/search`, {
       params: { q: townName, details: false, apikey: API_KEY },
     });
     return locationData[0]?.Key;
   }
   ```

4. Start the Node server

   Before you start the Node server, ensure that you have already installed the node packages listed in the package.json file by running `npm install`.

   ```console
   npm install 
   npm run start
   ```

   You should see the following output:

   ```plaintext
   > express-api-starter@1.2.0 start
   > node src/index.js

   API_ENDPOINT_BASE: http://localhost:8080
   ..
   Listening: http://localhost:5001
   ```

   The output indicates that your Node application has successfully started. Keep this terminal window open.

5. Test the Mocked API

   Open a new terminal window and run the following command to test the mocked API:

   ```console
   $ curl "http://localhost:5001/api/v1/getWeather?city=Bengaluru"
   ```

   You should see the following output:

   ```plaintext
   {"city":"Bengaluru","temperature":27.1,"conditions":"Mostly cloudy","forecasts":[{"date":"2024-09-02T07:00:00+05:30","temperature":83,"conditions":"Partly sunny w/ t-storms"},{"date":"2024-09-03T07:00:00+05:30","temperature":83,"conditions":"Thunderstorms"},{"date":"2024-09-04T07:00:00+05:30","temperature":83,"conditions":"Intermittent clouds"},{"date":"2024-09-05T07:00:00+05:30","temperature":82,"conditions":"Dreary"},{"date":"2024-09-06T07:00:00+05:30","temperature":82,"conditions":"Dreary"}]}%
   ```

   This indicates that your Node.js application is now successfully routing requests to the WireMock container and receiving the mocked responses

   You might have noticed that you’re trying to use `http://localhost:5001` as the URL instead of port `8080`. This is because your Node.js application is running on port `5001`, and it's routing requests to the WireMock container that's listening on port `8080`.

   > Tip
   >
   > Before you proceed to the next step, ensure that you stop the node application service.

## [Use a live API in production to fetch real-time weather data from AccuWeather](#use-a-live-api-in-production-to-fetch-real-time-weather-data-from-accuweather)

To enhance your Node.js application with real-time weather data, you can seamlessly integrate the AccuWeather API. This section of the guide will walk you through the steps involved in setting up a non-containerized Node.js application and fetching weather information directly from the AccuWeather API.

1. Create an AccuWeather API Key

   Sign up for a free AccuWeather developer account at<https://developer.accuweather.com/>. Within your account, create a new app by selecting `MY APPS` on the top navigation menu to get your unique API key.

   [AccuWeather API](https://developer.accuweather.com/) is a web API that provides real-time weather data and forecasts. Developers can use this API to integrate weather information into their applications, websites, or other projects.

2. Change directory to `accuweather-api`

   ```console
   $ cd accuweather-api
   ```

3. Set your AccuWeather API key using the `.env` file:

   > Tip
   >
   > To prevent conflicts, ensure that any existing environment variables named `API_ENDPOINT_BASE` or `ACCUWEATHER_API_KEY` are removed before modifying the `.env` file.

   Run the following command on your terminal:

   ```console
   unset API_ENDPOINT_BASE
   unset ACCUWEATHER_API_KEY
   ```

   It’s time to set the environment variables in the `.env` file:

   ```plaintext
   ACCUWEATHER_API_KEY=XXXXXX
   API_ENDPOINT_BASE=http://dataservice.accuweather.com
   ```

   Make sure to populate `ACCUWEATHER_API_KEY` with the correct value.

4. Install the dependencies

   Run the following command to install the required packages:

   ```console
   $ npm install
   ```

   This will install all the packages listed in your `package.json` file. These packages are essential for the project to function correctly.

   If you encounter any warnings related to deprecated packages, you can ignore them for now for this demonstration.

5. Assuming that you don’t have a pre-existing Node server running on your system, go ahead and start the Node server by running the following command:

   ```console
   $ npm run start
   ```

   You should see the following output:

   ```plaintext
   > express-api-starter@1.2.0 start
   > node src/index.js

   API_ENDPOINT_BASE: http://dataservice.accuweather.com
   ACCUWEATHER_API_KEY is set: true 
   Listening: http://localhost:5001
   ```

   Keep this terminal window open.

6. Run the curl command to send a GET request to the server URL.

   In the new terminal window, enter the following command:

   ```console
   $ curl "http://localhost:5000/api/v1/getWeather?city=Bengaluru"
   ```

   By running the command, you're essentially telling your local server to provide you with weather data for a city named `Bengaluru`. The request is specifically targeting the `/api/v1/getWeather` endpoint, and you're providing the query parameter `city=Bengaluru`. Once you execute the command, the server processes this request, fetches the data and returns it as a response, which `curl` will display in your terminal.

   When fetching data from the external AccuWeather API, you're interacting with live data that reflects the latest weather conditions.

## [Recap](#recap)

This guide has walked you through setting up WireMock using Docker. You’ve learned how to create stubs to simulate API endpoints, allowing you to develop and test your application without relying on external services. By using WireMock, you can create reliable and consistent test environments, reproduce edge cases, and speed up your development workflow.

----
url: https://docs.docker.com/dhi/how-to/use/
----

# Use a Docker Hardened Image

***

Table of contents

***

You can use a Docker Hardened Image (DHI) just like any other image on Docker Hub. DHIs follow the same familiar usage patterns. Pull them with `docker pull`, reference them in your Dockerfile, and run containers with `docker run`.

The key difference is that DHIs are security-focused and intentionally minimal to reduce the attack surface. This means some variants don't include a shell or package manager, and may run as a non-root user by default.

> Important
>
> You must authenticate to the Docker Hardened Images registry (`dhi.io`) to pull DHI Community images. You can authenticate using either of the following:
>
> * **Docker ID and password:** Use your Docker Hub username and password. If you don't have a Docker account, [create one](https://docs.docker.com/accounts/create-account/) for free.
> * **Access token:** Use a [personal access token (PAT)](https://docs.docker.com/security/access-tokens/) for personal accounts, or an [organization access token (OAT)](https://docs.docker.com/enterprise/security/access-tokens/) with your organization name as the username.
>
> Run `docker login dhi.io` to authenticate.

## [Considerations when adopting DHIs](#considerations-when-adopting-dhis)

Docker Hardened Images are intentionally minimal to improve security. If you're updating existing Dockerfiles or frameworks to use DHIs, keep in mind that runtime images don't include shells or package managers, run as non-root users by default, and may have different configurations than images you're familiar with.

For a comprehensive checklist of migration considerations and detailed guidance, see [Migrate to Docker Hardened Images](https://docs.docker.com/dhi/migration/).

## [Pull, run, and reference DHIs](#pull-run-and-reference-dhis)

Docker Hardened Images use different image references depending on your subscription:

| Subscription        | Image reference            | Authentication        |
| ------------------- | -------------------------- | --------------------- |
| Community           | `dhi.io/<image>:<tag>`     | `docker login dhi.io` |
| Select & Enterprise | `<your-org>/<image>:<tag>` | `docker login`        |

Select and Enterprise users should [mirror](https://docs.docker.com/dhi/how-to/mirror/) repositories to their Docker Hub organization to access compliance variants and customization features.

After authenticating, use the image reference in standard Docker commands and Dockerfiles. For example:

```console
$ docker pull dhi.io/python:3.13
$ docker run --rm dhi.io/python:3.13 python -c "print('Hello from DHI')"
```

```dockerfile
FROM dhi.io/python:3.13
COPY . /app
CMD ["python", "/app/main.py"]
```

For multi-stage builds:

* Use a `-dev` tag for build stages that need a shell or package manager. See [Use dev variants for framework-based applications](#use-dev-variants-for-framework-based-applications).
* Use the `static` image for compiled executables with minimal runtime dependencies. See [Use a static image for compiled executables](#use-a-static-image-for-compiled-executables).

To learn how to search for available variants, see [Search and evaluate images](https://docs.docker.com/dhi/how-to/explore/).

## [Use a DHI in CI/CD pipelines](#use-a-dhi-in-cicd-pipelines)

Docker Hardened Images work just like any other image in your CI/CD pipelines. You can reference them in Dockerfiles, pull them as part of a pipeline step, or run containers based on them during builds and tests.

Unlike typical container images, DHIs also include signed [attestations](https://docs.docker.com/dhi/core-concepts/attestations/) such as SBOMs and provenance metadata. You can incorporate these into your pipeline to support supply chain security, policy checks, or audit requirements if your tooling supports it.

To strengthen your software supply chain, consider adding your own attestations when building images from DHIs. This lets you document how the image was built, verify its integrity, and enable downstream validation and policy enforcement using tools like Docker Scout.

To learn how to attach attestations during the build process, see [Docker Build Attestations](https://docs.docker.com/build/metadata/attestations/).

### [Discover attestations with ORAS](#discover-attestations-with-oras)

You can use [ORAS](https://oras.land/) to discover and inspect the attestations attached to Docker Hardened Images. This is particularly useful in CI/CD pipelines for supply chain security validation and compliance checks.

For automated workflows, authenticate using an [organization access token (OAT)](https://docs.docker.com/enterprise/security/access-tokens/). OATs are owned by the organization rather than an individual user, making them better suited for CI/CD pipelines.

To discover attestations with ORAS:

1. [Generate an organization access token](https://docs.docker.com/enterprise/security/access-tokens/) with **Read public repositories** scope.

   The following example shows how to discover attestations on DHI community images from `dhi.io`. If you're discovering attestations on images mirrored to your organization, generate an OAT scoped to read from your mirrored repository instead of **Read public repositories**.

2. Sign in to `dhi.io` using your organization name as the username and the OAT as the password.

   > Warning
   >
   > The following examples export credentials directly on the command line for demonstration purposes. This exposes sensitive tokens in your shell history and process list. In production environments, use secure methods such as reading from files with restricted permissions, environment files loaded at runtime, or secret management tools.

   ```console
   $ oras login dhi.io -u YOUR_ORGANIZATION_NAME
   ```

   Or non-interactively in a CI/CD pipeline, set your organization name and token:

   ```console
   $ export DOCKER_ORG="YOUR_ORGANIZATION_NAME"
   $ export OAT="YOUR_ORGANIZATION_ACCESS_TOKEN"
   $ echo $OAT | oras login dhi.io -u "$DOCKER_ORG" --password-stdin
   ```

3. Discover attestations on a DHI image:

   ```console
   $ oras discover dhi.io/node:24-dev --platform linux/amd64
   ```

   > Note
   >
   > The `--platform` flag is required. Without it, `oras discover` resolves to the multi-arch image index, which returns only an index-level signature rather than the full set of per-platform attestations.

   A successful response lists the attestations attached to the image, including SBOMs, provenance, vulnerability reports, and changelog metadata.

## [Use a static image for compiled executables](#use-a-static-image-for-compiled-executables)

Docker Hardened Images include a `static` image repository designed specifically for running compiled executables in an extremely minimal and secure runtime. Unlike a non-hardened `FROM scratch` image, the DHI `static` image includes attestations and essential packages like `ca-certificates`.

Use a `-dev` or other builder image to compile your binary, then copy the output into a `static` image:

```dockerfile
FROM dhi.io/golang:1.22-dev AS build
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 go build -o myapp

FROM dhi.io/static:20230311
COPY --from=build /app/myapp /myapp
ENTRYPOINT ["/myapp"]
```

For more multi-stage build patterns, see the [Go migration example](https://docs.docker.com/dhi/migration/examples/go/).

## [Use dev variants for framework-based applications](#use-dev-variants-for-framework-based-applications)

If you're building applications with frameworks that require package managers or build tools (such as Python, Node.js, or Go), use a `-dev` variant during the development or build stage. These variants include essential utilities like shells, compilers, and package managers to support local iteration and CI workflows.

Use `-dev` images in your inner development loop or in isolated CI stages to maximize productivity. Once you're ready to produce artifacts for production, switch to a smaller runtime variant to reduce the attack surface and image size.

For detailed multi-stage Dockerfile examples using dev variants, see the migration examples:

* [Go](https://docs.docker.com/dhi/migration/examples/go/)
* [Python](https://docs.docker.com/dhi/migration/examples/python/)
* [Node.js](https://docs.docker.com/dhi/migration/examples/node/)

## [Use compliance and ELS variants](#use-compliance-and-els-variants)

Subscription: Docker Hardened Images Select or Enterprise

With a DHI Select or DHI Enterprise subscription, you can access additional image variants:

* Compliance variants: FIPS-enabled and STIG-ready images for regulatory requirements
* ELS (Extended Lifecycle Support) variants (requires add-on): Security patches for end-of-life image versions

To access these variants, [mirror](https://docs.docker.com/dhi/how-to/mirror/) the repository to your Docker Hub organization. For ELS, enable **Mirror end-of-life images** when setting up mirroring. Once mirrored, use the compliance or EOL tags like any other image tag.

## [Use with Kubernetes](#use-with-kubernetes)

When deploying Docker Hardened Images to Kubernetes, the process is similar to using any other container image with one key difference: you must configure image pull secrets to authenticate to the DHI registry. This applies whether you're pulling directly from `dhi.io`, from a mirror on Docker Hub, or from your own third-party registry.

### [Create an image pull secret](#create-an-image-pull-secret)

You can create an image pull secret using either an access token or Docker Desktop credentials.

For the `--docker-server` value:

* Use `dhi.io` for community images pulled directly from Docker Hardened Images
* Use `docker.io` for mirrored repositories on Docker Hub
* Use your registry's hostname for third-party registries

#### [Using an access token](#using-an-access-token)

Create a secret using a [Personal Access Token (PAT)](https://docs.docker.com/security/access-tokens/) or [Organization Access Token (OAT)](https://docs.docker.com/enterprise/security/access-tokens/). Ensure the token has at least read-only access to the repositories.

```console
$ kubectl create -n <kubernetes namespace> secret docker-registry <secret name> --docker-server=<registry server> \
        --docker-username=<registry user> --docker-password=<access token> \
        --docker-email=<registry email>
```

#### [Using Docker Desktop credentials](#using-docker-desktop-credentials)

If you're already authenticated with Docker Desktop, you can create a secret using your stored credentials. This method works for registries you've authenticated to via Docker Desktop (using `docker login <registry>`).

```console
$ NS=<namespace>
$ kubectl create -n ${NS} secret docker-registry dhi-pull-secret \
    --docker-server=<registry server> \
    --docker-username=<registry user> \
    --docker-password="$(echo https://<registry server> | docker-credential-desktop get | jq -r .Secret)" \
    --docker-email=<registry email>
```

This method extracts credentials from Docker Desktop's credential store, avoiding the need to create a separate access token for local development.

### [Test the image pull secret](#test-the-image-pull-secret)

After creating the secret, verify it works by deploying a test pod that references the secret in its `imagePullSecrets` configuration.

Create a test pod:

```console
kubectl apply --wait -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: dhi-test
  namespace: <kubernetes namespace>
spec:
  containers:
  - name: test
    image: bash:5
    command: [ "sh", "-c", "echo 'Hello from DHI in Kubernetes!'" ]
  imagePullSecrets:
  - name: <secret name>
EOF
```

Check the pod status to ensure it completed successfully:

```console
$ kubectl get -n <kubernetes namespace> pods/dhi-test
```

A successful test shows `Completed` status:

```console
NAME       READY   STATUS      RESTARTS     AGE
dhi-test   0/1     Completed   ...          ...
```

If you see `ErrImagePull` status instead, there's an issue with your secret configuration:

```console
NAME       READY   STATUS         RESTARTS   AGE
dhi-test   0/1     ErrImagePull   0          ...
```

Verify the pod output matches the expected message:

```console
$ kubectl logs -n <kubernetes namespace> pods/dhi-test
Hello from DHI in Kubernetes!
```

Clean up the test pod:

```console
$ kubectl delete -n <kubernetes namespace> pods/dhi-test
```

----
url: https://docs.docker.com/reference/cli/docker/compose/exec/
----

# docker compose exec

***

| Description | Execute a command in a running container                  |
| ----------- | --------------------------------------------------------- |
| Usage       | `docker compose exec [OPTIONS] SERVICE COMMAND [ARGS...]` |

## [Description](#description)

This is the equivalent of `docker exec` targeting a Compose service.

With this subcommand, you can run arbitrary commands in your services. Commands allocate a TTY by default, so you can use a command such as `docker compose exec web sh` to get an interactive prompt.

By default, Compose will enter container in interactive mode and allocate a TTY, while the equivalent `docker exec` command requires passing `--interactive --tty` flags to get the same behavior. Compose also supports those two flags to offer a smooth migration between commands, whenever they are no-op by default. Still, `interactive` can be used to force disabling interactive mode (`--interactive=false`), typically when `docker compose exec` command is used inside a script.

## [Options](#options)

| Option          | Default | Description                                                                       |
| --------------- | ------- | --------------------------------------------------------------------------------- |
| `-d, --detach`  |         | Detached mode: Run command in the background                                      |
| `-e, --env`     |         | Set environment variables                                                         |
| `--index`       |         | Index of the container if service has multiple replicas                           |
| `-T, --no-tty`  | `true`  | Disable pseudo-TTY allocation. By default 'docker compose exec' allocates a TTY.  |
| `--privileged`  |         | Give extended privileges to the process                                           |
| `-u, --user`    |         | Run the command as this user                                                      |
| `-w, --workdir` |         | Path to workdir directory for this command                                        |

----
url: https://docs.docker.com/engine/extend/
----

# Docker Engine managed plugin system

***

Table of contents

***

* [Installing and using a plugin](https://docs.docker.com/engine/extend/#installing-and-using-a-plugin)
* [Developing a plugin](https://docs.docker.com/engine/extend/#developing-a-plugin)
* [Debugging plugins](https://docs.docker.com/engine/extend/#debugging-plugins)

Docker Engine's plugin system lets you install, start, stop, and remove plugins using Docker Engine.

For information about legacy (non-managed) plugins, refer to [Understand legacy Docker Engine plugins](https://docs.docker.com/engine/extend/legacy_plugins/).

> Note
>
> Docker Engine managed plugins are currently not supported on Windows daemons.

## [Installing and using a plugin](#installing-and-using-a-plugin)

Plugins are distributed as Docker images and can be hosted on Docker Hub or on a private registry.

To install a plugin, use the `docker plugin install` command, which pulls the plugin from Docker Hub or your private registry, prompts you to grant permissions or capabilities if necessary, and enables the plugin.

To check the status of installed plugins, use the `docker plugin ls` command. Plugins that start successfully are listed as enabled in the output.

After a plugin is installed, you can use it as an option for another Docker operation, such as creating a volume.

In the following example, you install the [`rclone` plugin](https://rclone.org/docker/), verify that it is enabled, and use it to create a volume.

> Note
>
> This example is intended for instructional purposes only.

1. Set up the pre-requisite directories. By default they must exist on the host at the following locations:

   * `/var/lib/docker-plugins/rclone/config`. Reserved for the `rclone.conf` config file and must exist even if it's empty and the config file is not present.
   * `/var/lib/docker-plugins/rclone/cache`. Holds the plugin state file as well as optional VFS caches.

2. Install the `rclone` plugin.

   ```console
   $ docker plugin install rclone/docker-volume-rclone --alias rclone

   Plugin "rclone/docker-volume-rclone" is requesting the following privileges:
    - network: [host]
    - mount: [/var/lib/docker-plugins/rclone/config]
    - mount: [/var/lib/docker-plugins/rclone/cache]
    - device: [/dev/fuse]
    - capabilities: [CAP_SYS_ADMIN]
   Do you grant the above permissions? [y/N] 
   ```

   The plugin requests 5 privileges:

   * It needs access to the `host` network.

   * Access to pre-requisite directories to mount to store:

     * Your Rclone config files
     * Temporary cache data

   * Gives access to the FUSE (Filesystem in Userspace) device. This is required because Rclone uses FUSE to mount remote storage as if it were a local filesystem.

   * It needs the `CAP_SYS_ADMIN` capability, which allows the plugin to run the `mount` command.

3. Check that the plugin is enabled in the output of `docker plugin ls`.

   ```console
   $ docker plugin ls

   ID                    NAME                      DESCRIPTION                                ENABLED
   aede66158353          rclone:latest             Rclone volume plugin for Docker            true
   ```

4. Create a volume using the plugin. This example mounts the `/remote` directory on host `1.2.3.4` into a volume named `rclonevolume`.

   This volume can now be mounted into containers.

   ```console
   $ docker volume create \
     -d rclone \
     --name rclonevolume \
     -o type=sftp \
     -o path=remote \
     -o sftp-host=1.2.3.4 \
     -o sftp-user=user \
     -o "sftp-password=$(cat file_containing_password_for_remote_host)"
   ```

5. Verify that the volume was created successfully.

   ```console
   $ docker volume ls

   DRIVER              NAME
   rclone         rclonevolume
   ```

6. Start a container that uses the volume `rclonevolume`.

   ```console
   $ docker run --rm -v rclonevolume:/data busybox ls /data

   <content of /remote on machine 1.2.3.4>
   ```

7. Remove the volume `rclonevolume`

   ```console
   $ docker volume rm rclonevolume

   sshvolume
   ```

To disable a plugin, use the `docker plugin disable` command. To completely remove it, use the `docker plugin remove` command. For other available commands and options, see the [command line reference](https://docs.docker.com/reference/cli/docker/).

## [Developing a plugin](#developing-a-plugin)

#### [The rootfs directory](#the-rootfs-directory)

The `rootfs` directory represents the root filesystem of the plugin. In this example, it was created from a Dockerfile:

> Note
>
> The `/run/docker/plugins` directory is mandatory inside of the plugin's filesystem for Docker to communicate with the plugin.

```console
$ git clone https://github.com/vieux/docker-volume-sshfs
$ cd docker-volume-sshfs
$ docker build -t rootfsimage .
$ id=$(docker create rootfsimage true) # id was cd851ce43a403 when the image was created
$ sudo mkdir -p myplugin/rootfs
$ sudo docker export "$id" | sudo tar -x -C myplugin/rootfs
$ docker rm -vf "$id"
$ docker rmi rootfsimage
```

#### [The config.json file](#the-configjson-file)

The `config.json` file describes the plugin. See the [plugins config reference](https://docs.docker.com/engine/extend/config/).

Consider the following `config.json` file.

```json
{
  "description": "sshFS plugin for Docker",
  "documentation": "https://docs.docker.com/engine/extend/plugins/",
  "entrypoint": ["/docker-volume-sshfs"],
  "network": {
    "type": "host"
  },
  "interface": {
    "types": ["docker.volumedriver/1.0"],
    "socket": "sshfs.sock"
  },
  "linux": {
    "capabilities": ["CAP_SYS_ADMIN"]
  }
}
```

This plugin is a volume driver. It requires a `host` network and the `CAP_SYS_ADMIN` capability. It depends upon the `/docker-volume-sshfs` entrypoint and uses the `/run/docker/plugins/sshfs.sock` socket to communicate with Docker Engine. This plugin has no runtime parameters.

#### [Creating the plugin](#creating-the-plugin)

A new plugin can be created by running `docker plugin create <plugin-name> ./path/to/plugin/data` where the plugin data contains a plugin configuration file `config.json` and a root filesystem in subdirectory `rootfs`.

After that the plugin `<plugin-name>` will show up in `docker plugin ls`. Plugins can be pushed to remote registries with `docker plugin push <plugin-name>`.

## [Debugging plugins](#debugging-plugins)

Stdout of a plugin is redirected to dockerd logs. Such entries have a `plugin=<ID>` suffix. Here are a few examples of commands for pluginID `f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62` and their corresponding log entries in the docker daemon logs.

```console
$ docker plugin install tiborvass/sample-volume-plugin

INFO[0036] Starting...       Found 0 volumes on startup  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
```

```console
$ docker volume create -d tiborvass/sample-volume-plugin samplevol

INFO[0193] Create Called...  Ensuring directory /data/samplevol exists on host...  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0193] open /var/lib/docker/plugin-data/local-persist.json: no such file or directory  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0193]                   Created volume samplevol with mountpoint /data/samplevol  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0193] Path Called...    Returned path /data/samplevol  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
```

```console
$ docker run -v samplevol:/tmp busybox sh

INFO[0421] Get Called...     Found samplevol                plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0421] Mount Called...   Mounted samplevol              plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0421] Path Called...    Returned path /data/samplevol  plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
INFO[0421] Unmount Called... Unmounted samplevol            plugin=f52a3df433b9aceee436eaada0752f5797aab1de47e5485f1690a073b860ff62
```

#### [Using runc to obtain logfiles and shell into the plugin.](#using-runc-to-obtain-logfiles-and-shell-into-the-plugin)

Use `runc`, the default docker container runtime, for debugging plugins by collecting plugin logs redirected to a file.

```console
$ sudo runc --root /run/docker/runtime-runc/plugins.moby list

ID                                                                 PID         STATUS      BUNDLE                                                                                                                                       CREATED                          OWNER
93f1e7dbfe11c938782c2993628c895cf28e2274072c4a346a6002446c949b25   15806       running     /run/docker/containerd/daemon/io.containerd.runtime.v1.linux/moby-plugins/93f1e7dbfe11c938782c2993628c895cf28e2274072c4a346a6002446c949b25   2018-02-08T21:40:08.621358213Z   root
9b4606d84e06b56df84fadf054a21374b247941c94ce405b0a261499d689d9c9   14992       running     /run/docker/containerd/daemon/io.containerd.runtime.v1.linux/moby-plugins/9b4606d84e06b56df84fadf054a21374b247941c94ce405b0a261499d689d9c9   2018-02-08T21:35:12.321325872Z   root
c5bb4b90941efcaccca999439ed06d6a6affdde7081bb34dc84126b57b3e793d   14984       running     /run/docker/containerd/daemon/io.containerd.runtime.v1.linux/moby-plugins/c5bb4b90941efcaccca999439ed06d6a6affdde7081bb34dc84126b57b3e793d   2018-02-08T21:35:12.321288966Z   root
```

```console
$ sudo runc --root /run/docker/runtime-runc/plugins.moby exec 93f1e7dbfe11c938782c2993628c895cf28e2274072c4a346a6002446c949b25 cat /var/log/plugin.log
```

If the plugin has a built-in shell, then exec into the plugin can be done as follows:

```console
$ sudo runc --root /run/docker/runtime-runc/plugins.moby exec -t 93f1e7dbfe11c938782c2993628c895cf28e2274072c4a346a6002446c949b25 sh
```

#### [Using curl to debug plugin socket issues.](#using-curl-to-debug-plugin-socket-issues)

To verify if the plugin API socket that the docker daemon communicates with is responsive, use curl. In this example, we will make API calls from the docker host to volume and network plugins using curl 7.47.0 to ensure that the plugin is listening on the said socket. For a well functioning plugin, these basic requests should work. Note that plugin sockets are available on the host under `/var/run/docker/plugins/<pluginID>`

```console
$ curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/docker/plugins/e8a37ba56fc879c991f7d7921901723c64df6b42b87e6a0b055771ecf8477a6d/plugin.sock http:/VolumeDriver.List

{"Mountpoint":"","Err":"","Volumes":[{"Name":"myvol1","Mountpoint":"/data/myvol1"},{"Name":"myvol2","Mountpoint":"/data/myvol2"}],"Volume":null}
```

```console
$ curl -H "Content-Type: application/json" -XPOST -d '{}' --unix-socket /var/run/docker/plugins/45e00a7ce6185d6e365904c8bcf62eb724b1fe307e0d4e7ecc9f6c1eb7bcdb70/plugin.sock http:/NetworkDriver.GetCapabilities

{"Scope":"local"}
```

When using curl 7.5 and above, the URL should be of the form `http://hostname/APICall`, where `hostname` is the valid hostname where the plugin is installed and `APICall` is the call to the plugin API.

For example, `http://localhost/VolumeDriver.List`

----
url: https://docs.docker.com/desktop/troubleshoot-and-support/faqs/general/
----

# General FAQs for Desktop

***

Table of contents

***

### [Can I use Docker Desktop offline?](#can-i-use-docker-desktop-offline)

Yes, you can use Docker Desktop offline. However, you cannot access features that require an active internet connection. Additionally, any functionality that requires you to sign in won't work while using Docker Desktop offline or in air-gapped environments.

### [How do I connect to the remote Docker Engine API?](#how-do-i-connect-to-the-remote-docker-engine-api)

To connect to the remote Engine API, you might need to provide the location of the Engine API for Docker clients and development tools.

Mac and Windows WSL 2 users can connect to the Docker Engine through a Unix socket: `unix:///var/run/docker.sock`. Docker Desktop for Linux uses a [per-user socket](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/linuxfaqs/#how-do-i-use-docker-sdks-with-docker-desktop-for-linux) located at `~/.docker/desktop/docker.sock` instead of the system-wide `/var/run/docker.sock`.

If you are working with applications like [Apache Maven](https://maven.apache.org/) that expect settings for `DOCKER_HOST` and `DOCKER_CERT_PATH` environment variables, specify these to connect to Docker instances through Unix sockets.

For example:

```console
$ export DOCKER_HOST=unix:///var/run/docker.sock
```

Docker Desktop Windows users can connect to the Docker Engine through a **named pipe**: `npipe:////./pipe/docker_engine`, or **TCP socket** at this URL: `tcp://localhost:2375`.

For details, see [Docker Engine API](https://docs.docker.com/reference/api/engine/).

### [How do I connect from a container to a service on the host?](#how-do-i-connect-from-a-container-to-a-service-on-the-host)

The host has a changing IP address, or none if you have no network access. It is recommend that you connect to the special DNS name `host.docker.internal`, which resolves to the internal IP address used by the host.

For more information and examples, see [how to connect from a container to a service on the host](https://docs.docker.com/desktop/features/networking/#connect-a-container-to-a-service-on-the-host).

### [Can I pass through a USB device to a container?](#can-i-pass-through-a-usb-device-to-a-container)

Docker Desktop does not support direct USB device passthrough. However, you can use USB over IP to connect common USB devices to the Docker Desktop VM and in turn be forwarded to a container. For more details, see [Using USB/IP with Docker Desktop](https://docs.docker.com/desktop/features/usbip/).

### [How do I verify Docker Desktop is using a proxy server ?](#how-do-i-verify-docker-desktop-is-using-a-proxy-server-)

To verify, look at the most recent events logged in `httpproxy.log`. This is located at `~/Library/Containers/com.docker.docker/Data/log/host` on macOS or `%LOCALAPPDATA%/Docker/log/host/` on Windows.

The following shows a few examples of what you can expect to see:

* Docker Desktop using app level settings (proxy mode manual) for proxy:

  ```console
  host will use proxy: app settings http_proxy=http://172.211.16.3:3128 https_proxy=http://172.211.16.3:3128
  Linux will use proxy: app settings http_proxy=http://172.211.16.3:3128 https_proxy=http://172.211.16.3:3128
  ```

* Docker Desktop using system level settings (proxy mode system) for proxy:

  ```console
  host will use proxy: static system http_proxy=http://172.211.16.3:3128 https_proxy=http://172.211.16.3:3128 no_proxy=
  Linux will use proxy: static system http_proxy=http://172.211.16.3:3128 https_proxy=http://172.211.16.3:3128 no_proxy=
  ```

* Docker Desktop is not configured to use a proxy server:

  ```console
  host will use proxy: disabled
  Linux will use proxy: disabled
  ```

* Docker Desktop is configured to use app level settings (proxy mode manual) and using a PAC file:

  ```console
  using a proxy PAC file: http://127.0.0.1:8081/proxy.pac
  host will use proxy: app settings from PAC file http://127.0.0.1:8081/proxy.pac
  Linux will use proxy: app settings from PAC file http://127.0.0.1:8081/proxy.pac
  ```

* Connect request using the configured proxy server:

  ```console
  CONNECT desktop.docker.com:443: host connecting via static system HTTPS proxy http://172.211.16.3:3128
  ```

### [How do I run Docker Desktop without administrator privileges?](#how-do-i-run-docker-desktop-without-administrator-privileges)

Docker Desktop requires administrator privileges only for installation. Once installed, administrator privileges are not needed to run it. However, for non-admin users to run Docker Desktop, it must be installed using a specific installer flag and meet certain prerequisites, which vary by platform.

To run Docker Desktop on Mac without requiring administrator privileges, install via the command line and pass the `—user=<userid>` installer flag:

```console
$ /Applications/Docker.app/Contents/MacOS/install --user=<userid>
```

You can then sign in to your machine with the user ID specified, and launch Docker Desktop.

> Note
>
> Before launching Docker Desktop, if a `settings-store.json` file already exists in the `~/Library/Group Containers/group.com.docker/` directory, you will see a **Finish setting up Docker Desktop** window that prompts for administrator privileges when you select **Finish**. To avoid this, ensure you delete the `settings-store.json` file left behind from any previous installations before launching the application.

> Note
>
> If you are using the WSL 2 backend, first make sure that you meet the [minimum required version](https://docs.docker.com/desktop/features/wsl/best-practices/) for WSL 2. Otherwise, update WSL 2 first.

To run Docker Desktop on Windows without requiring administrator privileges, install via the command line and pass the `—always-run-service` installer flag.

```console
$ "Docker Desktop Installer.exe" install —always-run-service
```

----
url: https://docs.docker.com/ai/sandboxes/security/credentials/
----

# Credentials

***

Table of contents

***

Most agents need an API key for their model provider. An HTTP/HTTPS proxy on your host intercepts outbound requests from the sandbox, looks up the matching credential on the host, and overwrites the auth header before forwarding. The real credential stays on the host; the sandbox sees only a sentinel value. For the security model behind this, see [Credential isolation](https://docs.docker.com/ai/sandboxes/security/isolation/#credential-isolation).

## [How credential injection works](#how-credential-injection-works)

The proxy needs three things to inject a credential: which outbound traffic to match, what header to write, and what value to use. The kit (or built-in agent definition) declares the first two. You provide the value on the host.

There are two host-side stores, plus a host shell fallback:

* Stored secrets, keyed on a service identifier: built-in agents declare service identifiers (`anthropic`, `openai`, `github`, etc.) in their kit specs; custom kits can declare their own. `sbx secret set` stores a value keyed on that identifier. When a sandboxed request matches a service's domain, the proxy reads the stored value and writes the configured header. Inside the sandbox, the environment variable holds a sentinel like `proxy-managed`, so SDKs that read the variable see something non-empty without seeing the real secret. See [Stored secrets](#stored-secrets).

* Stored secrets, keyed on a target domain and environment variable name: `sbx secret set-custom` stores a value alongside a target domain, an environment variable name, and an optional placeholder. The sandbox sees the placeholder; the proxy substitutes it with the real value anywhere it appears in outbound traffic to that domain. Use this when the service-identifier model doesn't fit — for example, when the agent validates the variable format at boot, or when the credential lands in a request body. See [Custom secrets](#custom-secrets).

* Host shell environment variables: as a fallback, the proxy reads from your shell environment. Useful for one-off testing or development; stored secrets are preferred because shell environment variables are plaintext and visible to other processes running as your user. See [Environment variables](#environment-variables).

Registry credentials are a separate store with a different purpose. They authenticate the `sbx` CLI (and optionally the sandbox itself) to private OCI registries for template and kit pulls, and are not used by the credential-injection proxy. See [Registry credentials](#registry-credentials).

If both a stored secret and a host environment variable are set for the same service, the stored secret takes precedence. For multi-provider agents (OpenCode, Docker Agent), the proxy selects credentials based on the API endpoint being called. See individual [agent pages](https://docs.docker.com/ai/sandboxes/agents/) for provider-specific details.

## [Stored secrets](#stored-secrets)

`sbx secret set` stores credentials in your OS keychain, keyed on a service identifier. Built-in agents declare a fixed set of services. Custom kits can declare their own. The same `sbx secret set` flow works for both.

### [Store a secret](#store-a-secret)

```console
$ sbx secret set -g anthropic
```

This prompts you for the secret value interactively. The `-g` flag stores the secret globally so it's available to all sandboxes. To scope a secret to a specific sandbox instead:

```console
$ sbx secret set my-sandbox openai
```

> Note
>
> A sandbox-scoped secret takes effect immediately, even if the sandbox is running. A global secret (`-g`) only applies when a sandbox is created. If you set or change a global secret while a sandbox is running, recreate the sandbox for the new value to take effect.

You can also pipe in a value for non-interactive use:

```console
$ echo "$ANTHROPIC_API_KEY" | sbx secret set -g anthropic
```

### [Built-in services](#built-in-services)

Each built-in service name maps to a set of environment variables the proxy checks and the API domains it authenticates requests to:

| Service     | Environment variables              | API domains                         |
| ----------- | ---------------------------------- | ----------------------------------- |
| `anthropic` | `ANTHROPIC_API_KEY`                | `api.anthropic.com`                 |
| `aws`       | `AWS_ACCESS_KEY_ID`                | AWS Bedrock endpoints               |
| `github`    | `GH_TOKEN`, `GITHUB_TOKEN`         | `api.github.com`, `github.com`      |
| `google`    | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | `generativelanguage.googleapis.com` |
| `groq`      | `GROQ_API_KEY`                     | `api.groq.com`                      |
| `mistral`   | `MISTRAL_API_KEY`                  | `api.mistral.ai`                    |
| `nebius`    | `NEBIUS_API_KEY`                   | `api.studio.nebius.ai`              |
| `openai`    | `OPENAI_API_KEY`                   | `api.openai.com`                    |
| `xai`       | `XAI_API_KEY`                      | `api.x.ai`                          |

When you store a secret with `sbx secret set -g <service>`, the proxy uses it the same way it would use the corresponding environment variable. You don't need to set both.

### [Services declared by kits](#services-declared-by-kits)

Custom kits can declare their own service identifiers in `spec.yaml` — they're not limited to the table above. To provide a credential for a kit-declared service, run `sbx secret set` with the same identifier the kit declares under `credentials.sources`:

```console
$ sbx secret set -g my-service
```

There's no separate registration step; the keychain entry is keyed on the identifier the kit already uses. See [Authenticate to external services](https://docs.docker.com/ai/sandboxes/customize/kits/#authenticate-to-external-services) for the kit-side wiring.

### [List and remove secrets](#list-and-remove-secrets)

List all stored secrets:

```console
$ sbx secret ls
SCOPE      TYPE      NAME      SECRET
(global)   service   github    gho_GCaw4o****...****43qy
```

Remove a secret:

```console
$ sbx secret rm -g github
```

> Note
>
> Running `sbx reset` deletes all stored secrets along with all sandbox state. You'll need to re-add your secrets after a reset.

### [GitHub token](#github-token)

The `github` service gives the agent access to the `gh` CLI inside the sandbox. Pass your existing GitHub CLI token:

```console
$ echo "$(gh auth token)" | sbx secret set -g github
```

This is useful for agents that create pull requests, open issues, or interact with GitHub APIs on your behalf.

### [SSH agent](#ssh-agent)

If your host has an SSH agent and `SSH_AUTH_SOCK` is set, Docker Sandboxes forwards the agent into the sandbox and sets `SSH_AUTH_SOCK` there. The private keys stay on your host. Processes inside the sandbox can request signatures from the forwarded agent, but they can't read or copy the private key.

Use SSH agent forwarding for Git operations over SSH and SSH-based commit signing. The signing key must be loaded in the host SSH agent for sandboxed commit signing to work. Outbound SSH connections are still subject to sandbox network policy. For details, see [Signed commits](https://docs.docker.com/ai/sandboxes/usage/#signed-commits).

## [Custom secrets](#custom-secrets)

> Important
>
> Custom secrets are experimental. The `set-custom` command is hidden from `sbx --help`, and behavior, flags, and the placeholder format may change.

For credentials that don't fit the service-identifier model — for example, when an agent validates the environment variable format at boot, or when the credential lands in a request body rather than a header — use `sbx secret set-custom`. The secret is keyed on a target domain, an environment variable name, and an optional placeholder string, instead of a service identifier.

```console
$ sbx secret set-custom -g \
    --host api.example.com \
    --env API_KEY \
    --value <secret>
```

> Warning
>
> Passing the secret as `--value <secret>` records it in your shell history and exposes it to other processes running as your user. Avoid pasting real credentials inline — read the value from a variable that's already in your environment, and clear shell history if a real secret was passed on the command line.

Inside the sandbox, `API_KEY` is set to a generated placeholder (for example, `sbx-cs-<rand>`). When a sandboxed process sends a request to `api.example.com` and the placeholder appears anywhere in the request, the proxy replaces it with the real value. The agent never sees the real secret.

Prefer the [service-based flow](#stored-secrets) whenever it's an option — the kit handles the wiring; you only provide the value.

## [Registry credentials](#registry-credentials)

Registry credentials authenticate to private OCI registries when pulling [templates](https://docs.docker.com/ai/sandboxes/customize/templates/) or [kits](https://docs.docker.com/ai/sandboxes/customize/kits/). Use `sbx secret set --registry <host>` to store them. They are independent from service secrets: the proxy doesn't touch them, and they're used directly by the `sbx` CLI when resolving image references.

For Docker Hub, `sbx` reuses your `sbx login` session — no registry secret needed. For other registries (GitHub Container Registry, ECR, ACR, self-hosted Nexus, and so on), store credentials with `sbx secret set --registry`.

### [Store registry credentials](#store-registry-credentials)

Pipe a token from stdin and target the registry hostname:

```console
$ gh auth token | sbx secret set --registry ghcr.io --password-stdin
```

For registries that require a username (for example, ACR with an admin account), add `--username`:

```console
$ echo "$ACR_PASSWORD" | sbx secret set \
    --registry myregistry.azurecr.io \
    --username myuser \
    --password-stdin
```

Three scopes control where the credential is used:

* Host-only (no `-g`, no sandbox name): the `sbx` CLI uses it to pull templates and kits when creating a sandbox. The credential is not injected into the sandbox itself, so processes inside the sandbox can't use it.
* Global (`-g`): same as host-only, plus written into `~/.docker/config.json` in every new sandbox. Use this when agents need to pull or push from inside the sandbox — for example, when an agent builds and publishes container images.
* Sandbox-scoped (positional `SANDBOX` argument): credential applies only to that named sandbox. Useful when only one sandbox needs access to a private registry.

```console
$ gh auth token | sbx secret set -g --registry ghcr.io --password-stdin
$ gh auth token | sbx secret set my-sandbox --registry ghcr.io --password-stdin
```

`sbx kit pull` also uses these credentials, with the Docker credential store as a fallback. `sbx kit push` uses only the Docker credential store — push targets still require a prior `docker login`.

### [Remove registry credentials](#remove-registry-credentials)

Remove both the host-only and global entries for a registry:

```console
$ sbx secret rm --registry ghcr.io -f
```

To remove only the global (sandbox-injected) entry and leave the host-only credential in place, pass `-g`:

```console
$ sbx secret rm -g --registry ghcr.io -f
```

To remove a sandbox-scoped credential, pass the sandbox name:

```console
$ sbx secret rm my-sandbox --registry ghcr.io -f
```

## [Environment variables](#environment-variables)

As an alternative to stored secrets, export the relevant environment variable in your shell before running a sandbox:

```console
$ export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
$ sbx run claude
```

The proxy reads the variable from your terminal session. See individual [agent pages](https://docs.docker.com/ai/sandboxes/agents/) for the variable names each agent expects.

> Note
>
> These environment variables are set on your host, not inside the sandbox. Sandbox agents are pre-configured to use credentials managed by the host-side proxy. For custom environment variables not tied to a [built-in service](#built-in-services), see [Setting custom environment variables](https://docs.docker.com/ai/sandboxes/faq/#how-do-i-set-custom-environment-variables-inside-a-sandbox).

## [Best practices](#best-practices)

* Use [stored secrets](#stored-secrets) over environment variables. The OS keychain encrypts credentials at rest and controls access, while environment variables are plaintext in your shell.
* Don't set API keys manually inside the sandbox. Sandbox agents are pre-configured to use proxy-managed credentials.
* For Claude Code and Codex, OAuth is another secure option: the flow runs on the host, so the token is never exposed inside the sandbox. For Claude Code, use `/login` inside the agent. For Codex, run `sbx secret set -g openai --oauth`.

## [Custom templates and placeholder values](#custom-templates-and-placeholder-values)

When building custom templates or installing agents manually in a shell sandbox, some agents require environment variables like `OPENAI_API_KEY` to be set before they start. Set these to placeholder values (e.g. `proxy-managed`) if needed. The proxy injects actual credentials regardless of the environment variable value.

----
url: https://docs.docker.com/dhi/how-to/helm/
----

# Use a Docker Hardened Image chart

***

Table of contents

***

Docker Hardened Image (DHI) charts are Docker-provided [Helm charts](https://helm.sh/docs/) built from upstream sources, designed for compatibility with Docker Hardened Images. These charts are available as OCI artifacts within the DHI catalog on Docker Hub. For more details, see [Docker Hardened Image charts](/dhi/features/helm/).

DHI charts incorporate multiple layers of supply chain security that aren't present in upstream charts:

* SLSA Level 3 compliance: Each chart is built with SLSA Build Level 3 standards, including detailed build provenance
* Software Bill of Materials (SBOMs): Comprehensive SBOMs detail all components referenced within the chart
* Cryptographic signing: All associated metadata is cryptographically signed by Docker for integrity and authenticity
* Hardened configuration: Charts automatically reference Docker Hardened Images for secure deployments
* Tested compatibility: Charts are robustly tested to work out-of-the-box with Docker Hardened Images

You can use a DHI chart like any other Helm chart stored in an OCI registry. When you have a Docker Hardened Images subscription, you can also customize DHI charts to reference customized images and mirrored repositories. The customized chart build pipeline ensures that your customizations are built securely, use the latest base charts, and include attestations.

## [Find a Docker Helm chart](#find-a-docker-helm-chart)

To find a Docker Helm chart for DHI:

1. Go to the Hardened Images catalog in [Docker Hub](https://hub.docker.com/hardened-images/catalog) and sign in.
2. In the left sidebar, select **Hardened Images** > **Catalog**.
3. Select **Filter by** for **Helm Charts**.
4. Select a Helm chart repository to view its details.

## [Mirror a Helm chart and/or its images to a third-party registry](#mirror-a-helm-chart-andor-its-images-to-a-third-party-registry)

If you want to mirror to your own third-party registry, you can follow the instructions in [Mirror a Docker Hardened Image repository](/dhi/how-to/mirror/) for either the chart, the image, or both.

The same `regctl` tool that is used for mirroring container images can also be used for mirroring Helm charts, as Helm charts are OCI artifacts.

For example:

```console
regctl image copy \
    "${SRC_CHART_REPO}:${TAG}" \
    "${DEST_REG}/${DEST_CHART_REPO}:${TAG}" \
    --referrers \
    --referrers-src "${SRC_ATT_REPO}" \
    --referrers-tgt "${DEST_REG}/${DEST_CHART_REPO}" \
    --force-recursive
```

## [Create a Kubernetes secret for pulling images](#create-a-kubernetes-secret-for-pulling-images)

You need to create a Kubernetes secret for pulling images from `dhi.io`, Docker Hub, or your own registry. This is necessary because Docker Hardened Image repositories require authentication. If you mirror the images to your own registry, you still need to create this secret if the registry requires authentication.

1. For `dhi.io` or Docker Hub, create a [personal access token (PAT)](/security/access-tokens/) using your Docker account or an [organization access token (OAT)](/enterprise/security/access-tokens/). Ensure the token has at least read-only access to the Docker Hardened Image repositories.

2. Create a secret in Kubernetes using the following command. Replace `<your-secret-name>`, `<your-username>`, `<your-personal-access-token>`, and `<your-email>` with your own values.

   > Note
   >
   > You need to create this secret in each Kubernetes namespace that uses a DHI. If you've mirror your DHIs to another registry, replace `dhi.io` with your registry's hostname. Replace `<your-username>`, `<your-access-token>`, and `<your-email>` with your own values. `<your-username>` is Docker ID if using a PAT or your organization name if using an OAT. `<your-secret-name>` is a name you choose for the secret.

   ```console
   $ kubectl create secret docker-registry <your-secret-name> \
       --docker-server=dhi.io \
       --docker-username=<your-username> \
       --docker-password=<your-access-token> \
       --docker-email=<your-email>
   ```

   For example:

   ```console
   $ kubectl create secret docker-registry dhi-pull-secret \
       --docker-server=dhi.io \
       --docker-username=docs \
       --docker-password=dckr_pat_12345 \
       --docker-email=moby@example.com
   ```

## [Install a Helm chart](#install-a-helm-chart)

To install a Helm chart from Docker Hardened Images:

1. Sign in to the registry using Helm:

   ```console
   $ echo $ACCESS_TOKEN | helm registry login dhi.io --username <your-username> --password-stdin
   ```

   Replace `<your-username>` and set `$ACCESS_TOKEN`.

2. Install the chart using `helm install`. Optionally, you can also use the `--dry-run` flag to test the installation without actually installing anything.

   ```console
   $ helm install <release-name> oci://dhi.io/<helm-chart-repository> --version <chart-version> \
     --set "imagePullSecrets[0].name=<your-secret-name>"
   ```

   Replace `<helm-chart-repository>` and `<chart-version>` accordingly. If the chart is in your own registry or another repository, replace `dhi.io/<helm-chart-repository>` with your own location. Replace `<your-secret-name>` with the name of the image pull secret created from [Create a Kubernetes secret for pulling images](#create-a-kubernetes-secret-for-pulling-images).

## [Customize a Helm chart](#customize-a-helm-chart)

You can customize Docker Hardened Image Helm charts to reference customized images and mirrored repositories. For more details, see [Customize Docker Hardened Images and charts](https://docs.docker.com/dhi/how-to/customize/).

## [Verify a Helm chart and view its attestations](#verify-a-helm-chart-and-view-its-attestations)

You can verify Helm charts. For more details, see [Verify Helm chart attestations](https://docs.docker.com/dhi/how-to/verify/#verify-helm-chart-attestations-with-docker-scout).

----
url: https://docs.docker.com/dhi/core-concepts/sscs/
----

# Software Supply Chain Security

***

Table of contents

***

## [What is Software Supply Chain Security (SSCS)?](#what-is-software-supply-chain-security-sscs)

SSCS encompasses practices and strategies designed to safeguard the entire lifecycle of software development from initial code creation to deployment and maintenance. It focuses on securing all components. This includes code, dependencies, build processes, and distribution channels in order to prevent malicious actors from compromising the software supply chain. Given the increasing reliance on open-source libraries and third-party components, ensuring the integrity and security of these elements is paramount

## [Why is SSCS important?](#why-is-sscs-important)

The significance of SSCS has escalated due to sophisticated cyberattacks targeting software supply chains. High-profile supply chain attacks and the exploitation of vulnerabilities in open-source components underscore the critical need for robust supply chain security measures. Compromises at any stage of the software lifecycle can lead to widespread vulnerabilities, data breaches, and significant financial losses.

## [How Docker Hardened Images contribute to SSCS](#how-docker-hardened-images-contribute-to-sscs)

Docker Hardened Images (DHI) are purpose-built container images designed with security at their core, addressing the challenges of modern software supply chain security. By integrating DHI into your development and deployment pipelines, you can enhance your organization's SSCS posture through the following features:

* Minimal attack surface: DHIs are engineered to be ultra-minimal, stripping away unnecessary components and reducing the attack surface by up to 95%. This distroless approach minimizes potential entry points for malicious actors.

* Cryptographic signing and provenance: Each DHI is cryptographically signed, ensuring authenticity and integrity. Build provenance is maintained, providing verifiable evidence of the image's origin and build process, aligning with standards like SLSA (Supply-chain Levels for Software Artifacts).

* Software Bill of Materials (SBOM): DHIs include a comprehensive SBOM, detailing all components and dependencies within the image. This transparency aids in vulnerability management and compliance tracking, enabling teams to assess and mitigate risks effectively.

* Continuous maintenance and rapid CVE remediation: Docker maintains DHIs with regular updates and security patches, backed by an [SLA for addressing critical and high-severity vulnerabilities](https://docs.docker.com/go/dhi-sla/). This proactive approach helps ensure that images remain secure and compliant with enterprise standards.

----
url: https://docs.docker.com/scout/integrations/code-quality/sonarqube/
----

# Integrate Docker Scout with SonarQube

***

Table of contents

***

The SonarQube integration enables Docker Scout to surface SonarQube quality gate checks through Policy Evaluation, under a new [SonarQube Quality Gates Policy](https://docs.docker.com/scout/policy/#sonarqube-quality-gates-policy).

## [How it works](#how-it-works)

This integration uses [SonarQube webhooks](https://docs.sonarsource.com/sonarqube/latest/project-administration/webhooks/) to notify Docker Scout of when a SonarQube project analysis has completed. When the webhook is called, Docker Scout receives the analysis results, and stores them in the database.

When you push a new image to a repository, Docker Scout evaluates the results of the SonarQube analysis record corresponding to the image. Docker Scout uses Git provenance metadata on the images, from provenance attestations or an OCI annotations, to link image repositories with SonarQube analysis results.

> Note
>
> Docker Scout doesn't have access to historic SonarQube analysis records. Only analysis results recorded after the integration is enabled will be available to Docker Scout.

Both self-managed SonarQube instances and SonarCloud are supported.

## [Prerequisites](#prerequisites)

To integrate Docker Scout with SonarQube, ensure that:

* Your image repository is [integrated with Docker Scout](https://docs.docker.com/scout/integrations/#container-registries).
* Your images are built with [provenance attestations](https://docs.docker.com/build/metadata/attestations/slsa-provenance/), or the `org.opencontainers.image.revision` annotation, containing information about the Git repository.

## [Enable the SonarQube integration](#enable-the-sonarqube-integration)

1. Go to the [SonarQube integrations page](https://scout.docker.com/settings/integrations/sonarqube/) on the Docker Scout Dashboard.

2. In the **How to integrate** section, enter a configuration name for this integration. Docker Scout uses this label as a display name for the integration, and to name the webhook.

3. Select **Next**.

4. Enter the configuration details for your SonarQube instance. Docker Scout uses this information to create SonarQube webhook.

   In SonarQube, [generate a new **User token**](https://docs.sonarsource.com/sonarqube/latest/user-guide/user-account/generating-and-using-tokens/#generating-a-token). The token requires 'Administer' permission on the specified project, or global 'Administer' permission.

   Enter the token, your SonarQube URL, and the ID of your SonarQube organization. The SonarQube organization is required if you're using SonarCloud.

5. Select **Enable configuration**.

   Docker Scout performs a connection test to verify that the provided details are correct, and that the token has the necessary permissions.

6. After a successful connection test, you're redirected to the SonarQube integration overview, which lists all your SonarQube integrations and their statuses.

From the integration overview page, you can go directly to the **SonarQube Quality Gates Policy**. This policy will have no results initially. To start seeing evaluation results for this policy, trigger a new SonarQube analysis of your project and push the corresponding image to a repository. For more information, refer to the [policy description](https://docs.docker.com/scout/policy/#sonarqube-quality-gates).

----
url: https://docs.docker.com/engine/storage/drivers/select-storage-driver/
----

# Select a storage driver

***

Table of contents

***

Ideally, very little data is written to a container's writable layer, and you use Docker volumes to write data. However, some workloads require you to be able to write to the container's writable layer. This is where storage drivers come in.

> Note
>
> Docker Engine 29.0 and later uses the [containerd image store](https://docs.docker.com/engine/storage/containerd/) by default for fresh installations. If you upgraded from an earlier version, your daemon continues using the classic storage drivers described on this page. You can migrate to the containerd image store following the instructions in the [containerd image store](https://docs.docker.com/engine/storage/containerd/) documentation.

Docker supports several storage drivers, using a pluggable architecture. The storage driver controls how images and containers are stored and managed on your Docker host. After you have read the [storage driver overview](https://docs.docker.com/engine/storage/drivers/), the next step is to choose the best storage driver for your workloads. Use the storage driver with the best overall performance and stability in the most usual scenarios.

> Note
>
> This page discusses storage drivers for Docker Engine on Linux. If you're running the Docker daemon with Windows as the host OS, the only supported storage driver is windowsfilter. For more information, see [windowsfilter](https://docs.docker.com/engine/storage/drivers/windowsfilter-driver/).

The Docker Engine provides the following storage backends on Linux:

| Backend                     | Description                                                                                                                                                                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `containerd` (snapshotters) | The default for Docker Engine 29.0 and later. Uses containerd snapshotters for image storage. Supports multi-platform images and attestations. See [containerd image store](https://docs.docker.com/engine/storage/containerd/) for details.                            |
| `overlay2`                  | Classic storage driver. Most widely compatible across all currently supported Linux distributions, and requires no extra configuration.                                                                                                                                 |
| `fuse-overlayfs`            | Preferred only for running Rootless Docker on hosts that don't support rootless `overlay2`. Not needed since Linux kernel 5.11, as `overlay2` works in rootless mode. See [rootless mode documentation](https://docs.docker.com/engine/security/rootless/) for details. |
| `btrfs` and `zfs`           | Allow for advanced options, such as creating snapshots, but require more maintenance and setup. Each relies on the backing filesystem being configured correctly.                                                                                                       |
| `vfs`                       | Intended for testing purposes, and for situations where no copy-on-write filesystem can be used. Performance is poor, and not generally recommended for production use.                                                                                                 |

The Docker Engine has a prioritized list of which storage driver to use if no storage driver is explicitly configured, assuming that the storage driver meets the prerequisites, and automatically selects a compatible storage driver. You can see the order in the [source code for Docker Engine 29.5.2](https://github.com/moby/moby/blob/docker-v29.5.2/daemon/graphdriver/driver_linux.go).

Some storage drivers require you to use a specific format for the backing filesystem. If you have external requirements to use a specific backing filesystem, this may limit your choices. See [Supported backing filesystems](#supported-backing-filesystems).

After you have narrowed down which storage drivers you can choose from, your choice is determined by the characteristics of your workload and the level of stability you need. See [Other considerations](#other-considerations) for help in making the final decision.

## [Supported storage drivers per Linux distribution](#supported-storage-drivers-per-linux-distribution)

> Note
>
> Modifying the storage driver by editing the daemon configuration file isn't supported on Docker Desktop. Docker Desktop uses the [containerd image store](https://docs.docker.com/desktop/features/containerd/) by default (version 4.34 and later for clean installs). The following table is also not applicable for the Docker Engine in rootless mode. For the drivers available in rootless mode, see the [Rootless mode documentation](https://docs.docker.com/engine/security/rootless/).

This section applies to classic storage drivers only. If you're using the containerd image store (the default for Docker Engine 29.0+), see the [containerd image store documentation](https://docs.docker.com/engine/storage/containerd/) instead.

Your operating system and kernel may not support every classic storage driver. For example, `btrfs` is only supported if your system uses `btrfs` as storage. In general, the following configurations work on recent versions of the Linux distribution:

| Linux distribution | Default classic driver | Alternative drivers |
| ------------------ | ---------------------- | ------------------- |
| Ubuntu             | `overlay2`             | `zfs`, `vfs`        |
| Debian             | `overlay2`             | `vfs`               |
| CentOS             | `overlay2`             | `zfs`, `vfs`        |
| Fedora             | `overlay2`             | `zfs`, `vfs`        |
| SLES 15            | `overlay2`             | `vfs`               |
| RHEL               | `overlay2`             | `vfs`               |

For systems using classic storage drivers, `overlay2` provides broad compatibility across Linux distributions. Use Docker volumes for write-heavy workloads instead of relying on writing data to the container's writable layer.

The `vfs` storage driver is usually not the best choice, and primarily intended for debugging purposes in situations where no other storage-driver is supported. Before using the `vfs` storage driver, be sure to read about [its performance and storage characteristics and limitations](https://docs.docker.com/engine/storage/drivers/vfs-driver/).

The recommendations in the table above are known to work for a large number of users. If you use a recommended configuration and find a reproducible issue, it's likely to be fixed very quickly. If the driver that you want to use is not recommended according to this table, you can run it at your own risk. You can and should still report any issues you run into. However, such issues have a lower priority than issues encountered when using a recommended configuration.

Depending on your Linux distribution, other storage-drivers, such as `btrfs` may be available. These storage drivers can have advantages for specific use-cases, but may require additional set-up or maintenance, which make them not recommended for common scenarios. Refer to the documentation for those storage drivers for details.

## [Supported backing filesystems](#supported-backing-filesystems)

With regard to Docker, the backing filesystem is the filesystem where `/var/lib/docker/` is located. Some storage drivers only work with specific backing filesystems.

| Storage driver   | Supported backing filesystems                   |
| ---------------- | ----------------------------------------------- |
| `overlay2`       | `xfs` with ftype=1, `ext4`, `btrfs`, (and more) |
| `fuse-overlayfs` | any filesystem                                  |
| `btrfs`          | `btrfs`                                         |
| `zfs`            | `zfs`                                           |
| `vfs`            | any filesystem                                  |

> Note
>
> Most filesystems should work if they have the required features. Consult [OverlayFS](https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html) for more information.

## [Other considerations](#other-considerations)

### [Suitability for your workload](#suitability-for-your-workload)

Among other things, each storage driver has its own performance characteristics that make it more or less suitable for different workloads. Consider the following generalizations:

* `overlay2` operates at the file level rather than the block level. This uses memory more efficiently, but the container's writable layer may grow quite large in write-heavy workloads.
* Block-level storage drivers such as `btrfs`, and `zfs` perform better for write-heavy workloads (though not as well as Docker volumes).
* `btrfs` and `zfs` require a lot of memory.
* `zfs` is a good choice for high-density workloads such as PaaS.

More information about performance, suitability, and best practices is available in the documentation for each storage driver.

### [Shared storage systems and the storage driver](#shared-storage-systems-and-the-storage-driver)

If you use SAN, NAS, hardware RAID, or other shared storage systems, those systems may provide high availability, increased performance, thin provisioning, deduplication, and compression. In many cases, Docker can work on top of these storage systems, but Docker doesn't closely integrate with them.

Each Docker storage driver is based on a Linux filesystem or volume manager. Be sure to follow existing best practices for operating your storage driver (filesystem or volume manager) on top of your shared storage system. For example, if using the ZFS storage driver on top of a shared storage system, be sure to follow best practices for operating ZFS filesystems on top of that specific shared storage system.

### [Stability](#stability)

For some users, stability is more important than performance. Though Docker considers all of the storage drivers mentioned here to be stable, some are newer and are still under active development. In general, `overlay2` provides the highest stability.

### [Test with your own workloads](#test-with-your-own-workloads)

You can test Docker's performance when running your own workloads on different storage drivers. Make sure to use equivalent hardware and workloads to match production conditions, so you can see which storage driver offers the best overall performance.

## [Check your current storage driver](#check-your-current-storage-driver)

The detailed documentation for each individual storage driver details all of the set-up steps to use a given storage driver.

To see what storage driver Docker is currently using, use `docker info` and look for the `Storage Driver` line:

```console
$ docker info

Containers: 0
Images: 0
Storage Driver: overlay2
 Backing Filesystem: xfs
<...>
```

To change the storage driver, see the specific instructions for the new storage driver. Some drivers require additional configuration, including configuration to physical or logical disks on the Docker host.

> Important
>
> When you change the storage driver, any existing images and containers become inaccessible. This is because their layers can't be used by the new storage driver. If you revert your changes, you can access the old images and containers again, but any that you pulled or created using the new driver are then inaccessible.

## [Related information](#related-information)

* [Storage drivers](https://docs.docker.com/engine/storage/drivers/)
* [`overlay2` storage driver](https://docs.docker.com/engine/storage/drivers/overlayfs-driver/)
* [`btrfs` storage driver](https://docs.docker.com/engine/storage/drivers/btrfs-driver/)
* [`zfs` storage driver](https://docs.docker.com/engine/storage/drivers/zfs-driver/)
* [`windowsfilter` storage driver](https://docs.docker.com/engine/storage/drivers/windowsfilter-driver/)

----
url: https://docs.docker.com/reference/cli/docker/builder/prune/
----

# docker builder prune

***

| Description | Remove build cache     |
| ----------- | ---------------------- |
| Usage       | `docker builder prune` |

## [Description](#description)

Remove build cache

## [Options](#options)

| Option           | Default | Description                                           |
| ---------------- | ------- | ----------------------------------------------------- |
| `-a, --all`      |         | Remove all unused build cache, not just dangling ones |
| `--filter`       |         | Provide filter values (e.g. `until=24h`)              |
| `-f, --force`    |         | Do not prompt for confirmation                        |
| `--keep-storage` |         | Amount of disk space to keep for cache                |

----
url: https://docs.docker.com/guides/reactjs/
----

# React.js language-specific guide

Table of contents

***

This guide explains how to containerize React.js applications using Docker.

**Time to complete** 20 minutes

The React.js language-specific guide shows you how to containerize a React.js application using Docker, following best practices for creating efficient, production-ready containers.

[React.js](https://react.dev/) is a widely used library for building interactive user interfaces. However, managing dependencies, environments, and deployments efficiently can be complex. Docker simplifies this process by providing a consistent and containerized environment.

> **Acknowledgment**
>
> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and experienced Front-end engineer, his expertise in Docker, DevOps, and modern web development has made this resource invaluable for the community, helping developers navigate and optimize their Docker workflows.

***

## [What will you learn?](#what-will-you-learn)

In this guide, you will learn how to:

* Containerize and run a React.js application using Docker.
* Set up a local development environment for React.js inside a container.
* Run tests for your React.js application within a Docker container.
* Configure a CI/CD pipeline using GitHub Actions for your containerized app.
* Deploy the containerized React.js application to a local Kubernetes cluster for testing and debugging.

To begin, you’ll start by containerizing an existing React.js application.

***

## [Prerequisites](#prerequisites)

Before you begin, make sure you're familiar with the following:

* Basic understanding of [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) or [TypeScript](https://www.typescriptlang.org/).
* Basic knowledge of [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts.
* Familiarity with [React.js](https://react.dev/) fundamentals.
* Understanding of Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide.

Once you've completed the React.js getting started modules, you’ll be ready to containerize your own React.js application using the examples and instructions provided in this guide.

## [Modules](#modules)

1. [Containerize](https://docs.docker.com/guides/reactjs/containerize/)

   Learn how to containerize a React.js application with Docker by creating an optimized, production-ready image using best practices for performance, security, and scalability.

2. [Develop your app](https://docs.docker.com/guides/reactjs/develop/)

   Learn how to develop your React.js application locally using containers.

3. [Run your tests](https://docs.docker.com/guides/reactjs/run-tests/)

   Learn how to run your React.js tests in a container.

4. [GitHub Actions CI](https://docs.docker.com/guides/reactjs/configure-github-actions/)

   Learn how to configure CI/CD using GitHub Actions for your React.js application.

5. [Test your deployment](https://docs.docker.com/guides/reactjs/deploy/)

   Learn how to deploy locally to test and debug your Kubernetes deployment

----
url: https://docs.docker.com/billing/faqs/
----

# Billing FAQs

***

Table of contents

***

### [What happens if my subscription payment fails?](#what-happens-if-my-subscription-payment-fails)

If your subscription payment fails, there is a grace period of 15 days, including the due date. Docker retries to collect the payment 3 times using the following schedule:

* 3 days after the due date
* 5 days after the previous attempt
* 7 days after the previous attempt

Docker also sends an email notification `Action Required - Credit Card Payment Failed` with an attached unpaid invoice after each failed payment attempt.

Once the grace period is over and the invoice is still not paid, the subscription downgrades to a free subscription and all paid features are disabled.

### [Can I manually retry a failed payment?](#can-i-manually-retry-a-failed-payment)

No. Docker retries failed payments on a [retry schedule](https://docs.docker.com/billing/faqs/#what-happens-if-my-subscription-payment-fails).

To ensure a retired payment is successful, verify your default payment is updated. If you need to update your default payment method, see [Manage payment method](https://docs.docker.com/billing/payment-method/#manage-payment-method).

### [Does Docker collect sales tax and/or VAT?](#does-docker-collect-sales-tax-andor-vat)

Docker collects sales tax and/or VAT from the following:

* For United States customers, Docker began collecting sales tax on July 1, 2024.
* For European customers, Docker began collecting VAT on March 1, 2025.
* For United Kingdom customers, Docker began collecting VAT on May 1, 2025.

To ensure that tax assessments are correct, make sure that your billing information and VAT/Tax ID, if applicable, are updated. See [Update the billing information](https://docs.docker.com/billing/details/).

If you're exempt from sales tax, see [Register a tax certificate](https://docs.docker.com/billing/tax-certificate/).

### [Does Docker offer academic pricing?](#does-docker-offer-academic-pricing)

For academic pricing, contact the [Docker Sales Team](https://www.docker.com/company/contact).

### [Can I use pay by invoice for upgrades or additional seats?](#can-i-use-pay-by-invoice-for-upgrades-or-additional-seats)

No. Pay by invoice is only available for renewing annual subscriptions, not for purchasing upgrades or additional seats. You must use card payment or US bank accounts for these changes.

For a list of supported payment methods, see [Add or update a payment method](https://docs.docker.com/billing/payment-method/).

----
url: https://docs.docker.com/reference/samples/nextcloud/
----

# Nextcloud samples

| Name                                                                                                         | Description               |
| ------------------------------------------------------------------------------------------------------------ | ------------------------- |
| [Nextcloud / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/nextcloud-postgres)           | A sample Nextcloud setup. |
| [Nextcloud / Redis / MariaDB](https://github.com/docker/awesome-compose/tree/master/nextcloud-redis-mariadb) | A sample Nextcloud setup. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/guides/testcontainers-cloud/why/
----

# Why Testcontainers Cloud?

***

***

Testcontainers Cloud is a powerful cloud-based solution designed to optimize integration testing with Testcontainers by offloading container management to the cloud. It helps developers and teams overcome the limitations of traditional local and CI-based testing, ensuring consistent environments, faster test execution, and scalable workflows. Whether you're new to Testcontainers or looking to enhance your existing setup, Testcontainers Cloud offers a seamless way to manage containerized tests, improving efficiency and reliability in your development pipeline.

Testcontainers Cloud provides several benefits:

* **Offloading to the Cloud:** Frees up local resources by shifting container management to the cloud, keeping your laptop responsive.
* **Consistent Testing Environments:** Ensures that tests run in isolated, reliable environments, reducing inconsistencies across platforms from Dev to CI.
* **Scalability:** Allows running large numbers of containers simultaneously without being limited by local or CI resources.
* **Faster CI/CD Pipelines:** Reduces configuration bottlenecks and speeds up build times by offloading containers to multiple on-demand cloud workers with the Turbo-mode feature.

Testcontainers Cloud streamlines integration testing by offloading container management to the cloud, ensuring consistent environments and faster test execution resulting in reduced resource strain, making it an essential tool for improving the stability of your Testcontainers-based workflows.

[Setting up Testcontainers Cloud by Docker »](https://docs.docker.com/guides/testcontainers-cloud/demo-local/)

----
url: https://docs.docker.com/guides/swarm-deploy/
----

[Deploy to Swarm](https://docs.docker.com/guides/swarm-deploy/)

Discover how to deploy and manage Docker containers using Docker Swarm.

Deployment

10 minutes

[« Back to all guides](/guides/)

# Deploy to Swarm

***

Table of contents

***

> Note
>
> Swarm mode is an advanced feature for managing a cluster of Docker daemons.
>
> Use Swarm mode if you intend to use Swarm as a production runtime environment.
>
> If you're not planning on deploying with Swarm, use [Docker Compose](/compose/) instead. If you're developing for a Kubernetes deployment, consider using the [integrated Kubernetes feature](https://docs.docker.com/desktop/use-desktop/kubernetes/) in Docker Desktop.

## [Prerequisites](#prerequisites)

* Download and install Docker Desktop as described in [Get Docker](https://docs.docker.com/get-started/get-docker/).

* Work through containerizing an application in [Docker workshop part 2](https://docs.docker.com/get-started/workshop/02_our_app/)

* Make sure that Swarm is enabled on your Docker Desktop by typing `docker system info`, and looking for a message `Swarm: active` (you might have to scroll up a little).

  If Swarm isn't running, simply type `docker swarm init` in a shell prompt to set it up.

## [Introduction](#introduction)

Now that you've demonstrated that the individual components of your application run as stand-alone containers and shown how to deploy it using Kubernetes, you can look at how to arrange for them to be managed by Docker Swarm. Swarm provides many tools for scaling, networking, securing and maintaining your containerized applications, above and beyond the abilities of containers themselves.

In order to validate that your containerized application works well on Swarm, you'll use Docker Desktop's built in Swarm environment right on your development machine to deploy your application, before handing it off to run on a full Swarm cluster in production. The Swarm environment created by Docker Desktop is fully featured, meaning it has all the Swarm features your app will enjoy on a real cluster, accessible from the convenience of your development machine.

## [Describe apps using stack files](#describe-apps-using-stack-files)

Swarm never creates individual containers like you did in the previous step of this tutorial. Instead, all Swarm workloads are scheduled as services, which are scalable groups of containers with added networking features maintained automatically by Swarm. Furthermore, all Swarm objects can and should be described in manifests called stack files. These YAML files describe all the components and configurations of your Swarm app, and can be used to create and destroy your app in any Swarm environment.

Now you can write a simple stack file to run and manage your Todo app, the container `getting-started` image created in [Part 2](https://docs.docker.com/get-started/workshop/02_our_app/) of the tutorial. Place the following in a file called `bb-stack.yaml`:

> Note
>
> The `docker stack deploy` command uses the legacy [Compose file version 3](/reference/compose-file/legacy-versions/) format, used by Compose V1. The latest format, defined by the [Compose specification](/reference/compose-file/) isn't compatible with the `docker stack deploy` command.
>
> For more information about the evolution of Compose, see [History of Compose](/compose/history/).

```yaml
version: "3.7"

services:
  bb-app:
    image: getting-started
    ports:
      - "8000:3000"
```

In this Swarm YAML file, there is one object, a `service`, describing a scalable group of identical containers. In this case, you'll get just one container (the default), and that container will be based on your `getting-started` image created in [Part 2](https://docs.docker.com/get-started/workshop/02_our_app/) of the tutorial. In addition, you've asked Swarm to forward all traffic arriving at port 8000 on your development machine to port 3000 inside our getting-started container.

> **Kubernetes Services and Swarm Services are very different**
>
> Despite the similar name, the two orchestrators mean very different things by the term 'service'. In Swarm, a service provides both scheduling and networking facilities, creating containers and providing tools for routing traffic to them. In Kubernetes, scheduling and networking are handled separately, deployments (or other controllers) handle the scheduling of containers as pods, while services are responsible only for adding networking features to those pods.

## [Deploy and check your application](#deploy-and-check-your-application)

1. Deploy your application to Swarm:

   ```console
   $ docker stack deploy -c bb-stack.yaml demo
   ```

   If all goes well, Swarm will report creating all your stack objects with no complaints:

   ```shell
   Creating network demo_default
   Creating service demo_bb-app
   ```

   Notice that in addition to your service, Swarm also creates a Docker network by default to isolate the containers deployed as part of your stack.

2. Make sure everything worked by listing your service:

   ```console
   $ docker service ls
   ```

   If all has gone well, your service will report with 1/1 of its replicas created:

   ```shell
   ID                  NAME                MODE                REPLICAS            IMAGE               PORTS
   il7elwunymbs        demo_bb-app         replicated          1/1                 getting-started:latest   *:8000->3000/tcp
   ```

   This indicates 1/1 containers you asked for as part of your services are up and running. Also, you see that port 8000 on your development machine is getting forwarded to port 3000 in your getting-started container.

3. Open a browser and visit your Todo app at `localhost:8000`; you should see your Todo application, the same as when you ran it as a stand-alone container in [Part 2](https://docs.docker.com/get-started/workshop/02_our_app/) of the tutorial.

4. Once satisfied, tear down your application:

   ```console
   $ docker stack rm demo
   ```

## [Conclusion](#conclusion)

At this point, you've successfully used Docker Desktop to deploy your application to a fully-featured Swarm environment on your development machine. You can now add other components to your app and taking advantage of all the features and power of Swarm, right on your own machine.

In addition to deploying to Swarm, you've also described your application as a stack file. This simple text file contains everything you need to create your application in a running state; you can check it in to version control and share it with your colleagues, letting you to distribute your applications to other clusters (like the testing and production clusters that probably come after your development environments).

## [Swarm and CLI references](#swarm-and-cli-references)

Further documentation for all new Swarm objects and CLI commands used in this article are available here:

* [Swarm Mode](https://docs.docker.com/engine/swarm/)
* [Swarm Mode Services](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/)
* [Swarm Stacks](https://docs.docker.com/engine/swarm/stack-deploy/)
* [`docker stack *`](/reference/cli/docker/stack/)
* [`docker service *`](/reference/cli/docker/service/)

----
url: https://docs.docker.com/reference/cli/docker/context/update/
----

# docker context update

***

| Description | Update a context                          |
| ----------- | ----------------------------------------- |
| Usage       | `docker context update [OPTIONS] CONTEXT` |

## [Description](#description)

Updates an existing `context`. See [context create](/reference/cli/docker/context/create/).

## [Options](#options)

| Option          | Default | Description                |
| --------------- | ------- | -------------------------- |
| `--description` |         | Description of the context |
| `--docker`      |         | set the docker endpoint    |

## [Examples](#examples)

### [Update an existing context](#update-an-existing-context)

```console
$ docker context update \
    --description "some description" \
    --docker "host=tcp://myserver:2376,ca=~/ca-file,cert=~/cert-file,key=~/key-file" \
    my-context
```

----
url: https://docs.docker.com/reference/cli/docker/config/create/
----

# docker config create

***

| Description | Create a config from a file or STDIN            |
| ----------- | ----------------------------------------------- |
| Usage       | `docker config create [OPTIONS] CONFIG file\|-` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Creates a config using standard input or from a file for the config content.

For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).

> Note
>
> This is a cluster management command, and must be executed on a Swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                  | Default | Description               |
| ----------------------- | ------- | ------------------------- |
| [`-l, --label`](#label) |         | Config labels             |
| `--template-driver`     |         | API 1.37+ Template driver |

## [Examples](#examples)

### [Create a config](#create-a-config)

```console
$ printf <config> | docker config create my_config -

onakdyv307se2tl7nl20anokv

$ docker config ls

ID                          NAME                CREATED             UPDATED
onakdyv307se2tl7nl20anokv   my_config           6 seconds ago       6 seconds ago
```

### [Create a config with a file](#create-a-config-with-a-file)

```console
$ docker config create my_config ./config.json

dg426haahpi5ezmkkj5kyl3sn

$ docker config ls

ID                          NAME                CREATED             UPDATED
dg426haahpi5ezmkkj5kyl3sn   my_config           7 seconds ago       7 seconds ago
```

### [Create a config with labels (-l, --label)](#label)

```console
$ docker config create \
    --label env=dev \
    --label rev=20170324 \
    my_config ./config.json

eo7jnzguqgtpdah3cm5srfb97
```

```console
$ docker config inspect my_config

[
    {
        "ID": "eo7jnzguqgtpdah3cm5srfb97",
        "Version": {
            "Index": 17
        },
        "CreatedAt": "2017-03-24T08:15:09.735271783Z",
        "UpdatedAt": "2017-03-24T08:15:09.735271783Z",
        "Spec": {
            "Name": "my_config",
            "Labels": {
                "env": "dev",
                "rev": "20170324"
            },
            "Data": "aGVsbG8K"
        }
    }
]
```

----
url: https://docs.docker.com/engine/network/drivers/none/
----

# None network driver

***

Table of contents

***

If you want to completely isolate the networking stack of a container, you can use the `--network none` flag when starting the container. Within the container, only the loopback device is created.

The following example shows the output of `ip link show` in an `alpine` container using the `none` network driver.

```console
$ docker run --rm --network none alpine:latest ip link show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
```

No IPv6 loopback address is configured for containers using the `none` driver.

```console
$ docker run --rm --network none --name no-net-alpine alpine:latest ip addr show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
```

## [Next steps](#next-steps)

* Learn about [networking from the container's point of view](https://docs.docker.com/engine/network/)
* Learn about [host networking](https://docs.docker.com/engine/network/drivers/host/)
* Learn about [bridge networks](https://docs.docker.com/engine/network/drivers/bridge/)
* Learn about [overlay networks](https://docs.docker.com/engine/network/drivers/overlay/)
* Learn about [Macvlan networks](https://docs.docker.com/engine/network/drivers/macvlan/)

----
url: https://docs.docker.com/engine/swarm/swarm-tutorial/deploy-service/
----

# Deploy a service to the swarm

***

***

After you [create a swarm](https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/), you can deploy a service to the swarm. For this tutorial, you also [added worker nodes](https://docs.docker.com/engine/swarm/swarm-tutorial/add-nodes/), but that is not a requirement to deploy a service.

1. Open a terminal and ssh into the machine where you run your manager node. For example, the tutorial uses a machine named `manager1`.

2. Run the following command:

   ```console
   $ docker service create --replicas 1 --name helloworld alpine ping docker.com

   9uk4639qpg7npwf3fn2aasksr
   ```

   * The `docker service create` command creates the service.
   * The `--name` flag names the service `helloworld`.
   * The `--replicas` flag specifies the desired state of 1 running instance.
   * The arguments `alpine ping docker.com` define the service as an Alpine Linux container that executes the command `ping docker.com`.

3. Run `docker service ls` to see the list of running services:

   ```console
   $ docker service ls

   ID            NAME        SCALE  IMAGE   COMMAND
   9uk4639qpg7n  helloworld  1/1    alpine  ping docker.com
   ```

## [Next steps](#next-steps)

Now you're ready to inspect the service.

[Inspect the service](https://docs.docker.com/engine/swarm/swarm-tutorial/inspect-service/)

----
url: https://docs.docker.com/guides/docker-compose/why/
----

# Why Docker Compose?

***

***

Docker Compose is an essential tool for defining and running multi-container Docker applications. Docker Compose simplifies the Docker experience, making it easier for developers to create, manage, and deploy applications by using YAML files to configure application services.

Docker Compose provides several benefits:

* Lets you define multi-container applications in a single YAML file.
* Ensures consistent environments across development, testing, and production.
* Manages the startup and linking of multiple containers effortlessly.
* Streamlines development workflows and reduces setup time.
* Ensures that each service runs in its own container, avoiding conflicts.

[Demo: set up and use Docker Compose »](https://docs.docker.com/guides/docker-compose/setup/)

----
url: https://docs.docker.com/guides/testcontainers-java-mockserver/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

```console
$ ./mvnw test
```

Or with Gradle:

```console
$ ./gradlew test
```

You should see the MockServer Docker container start in the console output. It acts as the photo service, serving mock responses based on the configured expectations. All tests should pass.

## [Summary](#summary)

You built a Spring Boot application that integrates with an external REST API using declarative HTTP clients, then tested that integration using the Testcontainers MockServer module. Testing at the HTTP protocol level instead of mocking Java methods lets you catch serialization issues and simulate realistic failure scenarios.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testcontainers MockServer module](https://java.testcontainers.org/modules/mockserver/)
* [MockServer documentation](https://www.mock-server.com/)
* [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/)

----
url: https://docs.docker.com/guides/admin-set-up/deploy/
----

# Deploy your Docker setup

***

Table of contents

***

> Warning
>
> Communicate with your users before proceeding, and confirm that your IT and MDM teams are prepared to handle any unexpected issues, as these steps will affect all existing users signing into your Docker organization.

## [Enforce SSO](#enforce-sso)

Enforcing SSO means that anyone who has a Docker profile with an email address that matches your verified domain must sign in using your SSO connection. Make sure the Identity provider groups associated with your SSO connection cover all the developer groups that you want to have access to the Docker subscription.

For instructions on how to enforce SSO, see [Enforce SSO](https://docs.docker.com/enterprise/security/single-sign-on/connect/).

## [Deploy configuration settings and enforce sign-in to users](#deploy-configuration-settings-and-enforce-sign-in-to-users)

Have the MDM team deploy the configuration files for Docker to all users.

## [Next steps](#next-steps)

Congratulations, you've successfully completed the admin implementation process for Docker.

To continue optimizing your Docker environment:

* Review your [organization's usage data](https://docs.docker.com/admin/insights/) to track adoption
* Monitor [Docker Scout findings](https://docs.docker.com/scout/explore/analysis/) for security insights
* Explore [additional security features](https://docs.docker.com/enterprise/security/) to enhance your configuration

----
url: https://docs.docker.com/guides/genai-claude-code-mcp/claude-code-mcp-guide/
----

[Generate Docker Compose Files with Claude Code and Docker MCP Toolkit](https://docs.docker.com/guides/genai-claude-code-mcp/claude-code-mcp-guide/)

This guide shows how to wire Claude Code to the Docker MCP Toolkit so it can search Docker Hub images and generate complete Docker Compose stacks from natural language. You’ll enable the Docker Hub MCP server, connect Claude Code, verify MCP access, and create a Node.js + PostgreSQL stack with a conversational prompt.

AI

15 minutes

[« Back to all guides](/guides/)

# Generate Docker Compose Files with Claude Code and Docker MCP Toolkit

***

Table of contents

***

This guide introduces how to use Claude Code together with Docker MCP Toolkit so Claude can search Docker Hub in real time and generate a complete `docker-compose.yaml` from natural language.

Instead of manually writing YAML or looking for image tags, you describe your stack once — Claude uses the Model Context Protocol (MCP) to query Docker Hub and build a production-ready Compose file.

In this guide, you’ll learn how to:

* Enable Docker MCP Toolkit in Docker Desktop
* Add the Docker Hub MCP server
* Connect Claude Code to the MCP Gateway (GUI or CLI)
* Verify MCP connectivity inside Claude
* Ask Claude to generate and save a Compose file for a Node.js + PostgreSQL app
* Deploy it instantly with `docker compose up`

***

## [Use Claude Code and Docker MCP Toolkit to generate a Docker Compose file from natural language](#use-claude-code-and-docker-mcp-toolkit-to-generate-a-docker-compose-file-from-natural-language)

* Setup: Enable MCP Toolkit → Add Docker Hub MCP server → Connect Claude Code
* Use Claude: Describe your stack in plain English
* Automate: Claude queries Docker Hub via MCP and builds a complete `docker-compose.yaml`
* Deploy: Run `docker compose up` → Node.js + PostgreSQL live on `localhost:3000`
* Benefit: Zero YAML authoring. Zero image searching. Describe once → Claude builds it.

Estimated time: \~15 minutes

***

## [1. What you are building](#1-what-you-are-building)

The goal is simple: use Claude Code together with the Docker MCP Toolkit to search Docker Hub images and generate a complete Docker Compose file for a Node.js and PostgreSQL setup.

The Model Context Protocol (MCP) bridges Claude Code and Docker Desktop, giving Claude real-time access to Docker's tools. Instead of context-switching between Docker, terminal commands, and YAML editors, you describe your requirements once and Claude handles the infrastructure details.

Why this matters: This pattern scales to complex multi-service setups, database migrations, networking, security policies — all through conversational prompts.

***

## [2. Prerequisites](#2-prerequisites)

Make sure you have:

* Docker Desktop installed

* Enable Docker Desktop updated with [MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/get-started/#setup) support

* Claude Code installed

***

## [3. Install the Docker Hub MCP server](#3-install-the-docker-hub-mcp-server)

1. Open Docker Desktop
2. Select **MCP Toolkit**
3. Go to the **Catalog** tab
4. Search for **Docker Hub**
5. Select the **Docker Hub**MCP server
6. Add the MCP server, then open the **Configuration** tab
7. Enter your Docker Hub username
8. [Create a read-only personal access token](/security/access-tokens/#create-a-personal-access-token) and enter your access token under **Secrets**
9. Save the configuration

Docker Hub

Public images work without credentials. For private repositories, you can add your Docker Hub username and token later.

Docker Hub Secrets

***

## [4. Connect Claude Code to Docker MCP Toolkit](#4-connect-claude-code-to-docker-mcp-toolkit)

You can connect from Docker Desktop or using the CLI.

### [Option A. Connect with Docker Desktop](#option-a-connect-with-docker-desktop)

1. Open **MCP Toolkit**
2. Go to the **Clients** tab
3. Locate Claude Code
4. Select **Connect**

### [Option B. Connect using the CLI](#option-b-connect-using-the-cli)

```console
$ claude mcp add MCP_DOCKER -s user -- docker mcp gateway run
```

***

## [5. Verify MCP servers inside Claude Code](#5-verify-mcp-servers-inside-claude-code)

1. Navigate to your project folder:

```console
$ cd /path/to/project
```

1. Start Claude Code:

```console
$ claude
```

1. In the input box, type:

```console
/mcp
```

You should now see:

* The MCP gateway (for example `MCP_DOCKER`)
* Tools provided by the Docker Hub MCP server

If not, restart Claude Code or check Docker Desktop to confirm the connection.

***

## [6. Create a basic Node.js app](#6-create-a-basic-nodejs-app)

Claude Code generates more accurate Compose files when it can inspect a real project. Set up the application code now so the agent can bind mount it later.

Inside project folder, create a folder named `app`:

```console
$ mkdir app
$ cd app
$ npm init -y
$ npm install express
```

Create `index.js`:

```console
const express = require("express");
const app = express();

app.get("/", (req, res) => {
  res.send("Node.js, Docker, and MCP Toolkit are working together!");
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});
```

Add a start script to `package.json`:

```console
"scripts": {
  "start": "node index.js"
}
```

Return to your project root (`cd ..`) once the app is ready.

***

## [7. Ask Claude Code to design your Docker Compose stack](#7-ask-claude-code-to-design-your-docker-compose-stack)

Paste this message into Claude Code:

```console
Using the Docker Hub MCP server:

Search Docker Hub for an official Node.js image and a PostgreSQL image.
Choose stable, commonly used tags such as the Node LTS version and a recent major Postgres version.

Generate a Docker Compose file (`docker-compose.yaml`) with:
- app:
  - runs on port 3000
  - bind mounts the existing ./app directory into /usr/src/app
  - sets /usr/src/app as the working directory and runs `npm install && npm start`
- db: running on port 5432 using a named volume

Include:
- Environment variables for Postgres
- A shared bridge network
- Healthchecks where appropriate
- Pin the image version using the tag + index digest
```

Claude will search images through MCP, inspect the `app` directory, and generate a Compose file that mounts and runs your local code.

***

## [8. Save the generated Docker Compose file](#8-save-the-generated-docker-compose-file)

Tell Claude:

```console
Save the final Docker Compose file (docker-compose.yaml) into the current project directory.
```

You should see something like this:

```console
services:
  app:
    image: node:<tag>
    working_dir: /usr/src/app
    volumes:
      - .:/usr/src/app
    ports:
      - "3000:3000"
    depends_on:
      - db
    networks:
      - app-net

  db:
    image: postgres:18
    environment:
      POSTGRES_USER: example
      POSTGRES_PASSWORD: example
      POSTGRES_DB: appdb
    volumes:
      - db-data:/var/lib/postgresql
    ports:
      - "5432:5432"
    networks:
      - app-net

volumes:
  db-data:

networks:
  app-net:
    driver: bridge
```

***

## [9. Run the Docker Compose stack](#9-run-the-docker-compose-stack)

From your project root:

```console
$ docker compose up
```

Docker will:

* Pull the Node and Postgres images selected through Docker Hub MCP
* Create networks and volumes
* Start the containers

Open your browser:

```console
http://localhost:3000
```

Your Node.js app should now be running.

***

## [Conclusion](#conclusion)

By combining Claude Code with the Docker MCP Toolkit, Docker Desktop, and the Docker Hub MCP server, you can describe your stack in natural language and let MCP handle the details. This removes context switching and replaces it with a smooth, guided workflow powered by model context protocol integrations.

***

### [Next steps](#next-steps)

* Explore the 220+ MCP servers available in the [Docker MCP catalog](https://hub.docker.com/mcp)
* Connect Claude Code to your databases, internal APIs, and team tools
* Share your MCP setup with your team so everyone works consistently

The future of development is not about switching between tools. It is about tools working together in a simple, safe, and predictable way. The Docker MCP Toolkit brings that future into your everyday workflow.

## [Learn more](#learn-more)

* [Explore the MCP Catalog](https://hub.docker.com/mcp): Discover containerized, security-hardened MCP servers
* [Get started with MCP Toolkit in Docker Desktop](https://hub.docker.com/open-desktop?url=https://open.docker.com/dashboard/mcp): Requires version 4.48 or newer to launch automatically
* [Read the MCP Horror Stories series](https://www.docker.com/blog/mcp-horror-stories-the-supply-chain-attack/): Learn about common MCP security pitfalls and how to avoid them

----
url: https://docs.docker.com/desktop/setup/install/linux/rhel/
----

# Install Docker Desktop on RHEL

***

Table of contents

***

> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250 employees or more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopRhelInstall).

This page contains information on how to install, launch and upgrade Docker Desktop on a Red Hat Enterprise Linux (RHEL) distribution.

## [Prerequisites](#prerequisites)

To install Docker Desktop successfully, you must:

* Meet the [general system requirements](https://docs.docker.com/desktop/setup/install/linux/#general-system-requirements).

* Have a 64-bit version of either RHEL 9 or RHEL 10.

* If `pass` is not installed, or it can't be installed, you must enable [CodeReady Linux Builder (CRB) repository](https://access.redhat.com/articles/4348511) and [Extra Packages for Enterprise Linux (EPEL)](https://docs.fedoraproject.org/en-US/epel/).

  ```console
  $ sudo subscription-manager repos --enable codeready-builder-for-rhel-10-$(arch)-rpms
  $ sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-10.noarch.rpm
  $ sudo dnf install pass
  ```

  ```console
  $ sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
  $ sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
  $ sudo dnf install pass
  ```

* For a GNOME desktop environment you must install AppIndicator and KStatusNotifierItem [GNOME extensions](https://extensions.gnome.org/extension/615/appindicator-support/). You must also enable EPEL.

  ```console
  $ # enable EPEL as described above
  $ sudo dnf install gnome-shell-extension-appindicator
  $ sudo gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com
  ```

  ```console
  $ # enable EPEL as described above
  $ sudo dnf install gnome-shell-extension-appindicator
  $ sudo gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com
  ```

* If you're not using GNOME, you must install `gnome-terminal` to enable terminal access from Docker Desktop:

  ```console
  $ sudo dnf install gnome-terminal
  ```

## [Install Docker Desktop](#install-docker-desktop)

To install Docker Desktop on RHEL:

1. Set up Docker's package repository as follows:

   ```console
   $ sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
   ```

2. Download the latest [RPM package](https://desktop.docker.com/linux/main/amd64/docker-desktop-x86_64-rhel.rpm?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64).

3. Install the package with dnf as follows:

   ```console
   $ sudo dnf install ./docker-desktop-x86_64-rhel.rpm
   ```

The RPM package includes a post-install script that completes additional setup steps automatically.

The post-install script:

* Sets the capability on the Docker Desktop binary to map privileged ports and set resource limits.
* Adds a DNS name for Kubernetes to `/etc/hosts`.
* Creates a symlink from `/usr/local/bin/com.docker.cli` to `/usr/bin/docker`. This is because the classic Docker CLI is installed at `/usr/bin/docker`. The Docker Desktop installer also installs a Docker CLI binary that includes cloud-integration capabilities and is essentially a wrapper for the Compose CLI, at `/usr/local/bin/com.docker.cli`. The symlink ensures that the wrapper can access the classic Docker CLI.
* Creates a symlink from `/usr/libexec/qemu-kvm` to `/usr/local/bin/qemu-system-x86_64`.

```console
$ systemctl --user start docker-desktop
```

When Docker Desktop starts, it creates a dedicated [context](/engine/context/working-with-contexts) that the Docker CLI can use as a target and sets it as the current context in use. This is to avoid a clash with a local Docker Engine that may be running on the Linux host and using the default context. On shutdown, Docker Desktop resets the current context to the previous one.

The Docker Desktop installer updates Docker Compose and the Docker CLI binaries on the host. It installs Docker Compose V2 and gives users the choice to link it as docker-compose from the Settings panel. Docker Desktop installs the new Docker CLI binary that includes cloud-integration capabilities in `/usr/local/bin/com.docker.cli` and creates a symlink to the classic Docker CLI at `/usr/local/bin`.

After you’ve successfully installed Docker Desktop, you can check the versions of these binaries by running the following commands:

```console
$ docker compose version
Docker Compose version v2.39.4

$ docker --version
Docker version 28.4.0, build d8eb465

$ docker version
Client:
 Version:           28.4.0
 API version:       1.51
 Go version:        go1.24.7
<...>
```

To enable Docker Desktop to start on sign in, from the Docker menu, select **Settings** > **General** > **Start Docker Desktop when you sign in to your computer**.

Alternatively, open a terminal and run:

```console
$ systemctl --user enable docker-desktop
```

To stop Docker Desktop, select the Docker menu icon to open the Docker menu and select **Quit Docker Desktop**.

Alternatively, open a terminal and run:

```console
$ systemctl --user stop docker-desktop
```

> Tip
>
> To attach Red Hat subscription data to containers, see [Red Hat verified solution](https://access.redhat.com/solutions/5870841).
>
> For example:
>
> ```console
> $ docker run --rm -it -v "/etc/pki/entitlement:/etc/pki/entitlement" -v "/etc/rhsm:/etc/rhsm-host" -v "/etc/yum.repos.d/redhat.repo:/etc/yum.repos.d/redhat.repo" registry.access.redhat.com/ubi9
> ```

## [Upgrade Docker Desktop](#upgrade-docker-desktop)

Once a new version for Docker Desktop is released, the Docker UI shows a notification. You need to first remove the previous version and then download the new package each time you want to upgrade Docker Desktop. Run:

```console
$ sudo dnf remove docker-desktop
$ sudo dnf install ./docker-desktop-<arch>-rhel.rpm
```

## [Next steps](#next-steps)

* Review [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopRhelInstall) to see what Docker can offer you.
* Take a look at the [Docker workshop](https://docs.docker.com/get-started/workshop/) to learn how to build an image and run it as a containerized application.
* [Explore Docker Desktop](https://docs.docker.com/desktop/use-desktop/) and all its features.
* [Troubleshooting](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/) describes common problems, workarounds, how to run and submit diagnostics, and submit issues.
* [FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/general/) provide answers to frequently asked questions.
* [Release notes](https://docs.docker.com/desktop/release-notes/) lists component updates, new features, and improvements associated with Docker Desktop releases.
* [Back up and restore data](https://docs.docker.com/desktop/settings-and-maintenance/backup-and-restore/) provides instructions on backing up and restoring data related to Docker.

----
url: https://docs.docker.com/guides/testcontainers-go-getting-started/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

Run all the tests using `go test ./...`. Optionally add the `-v` flag for verbose output:

```console
$ go test -v ./...
```

You should see two Postgres Docker containers start automatically: one for the suite and its two tests, and another for the initial standalone test. All tests should pass. After the tests finish, the containers are stopped and removed automatically.

## [Summary](#summary)

The Testcontainers for Go library helps you write integration tests by using the same type of database (Postgres) that you use in production, instead of mocks. Because you aren't using mocks and instead talk to real services, you're free to refactor code and still verify that the application works as expected.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testcontainers for Go documentation](https://golang.testcontainers.org/)
* [Testcontainers for Go quickstart](https://golang.testcontainers.org/quickstart/)
* [Testcontainers Postgres module for Go](https://golang.testcontainers.org/modules/postgres/)

----
url: https://docs.docker.com/guides/vuejs/configure-github-actions/
----

# Automate your builds with GitHub Actions

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize an Vue.js application](https://docs.docker.com/guides/vuejs/containerize/).

You must also have:

* A [GitHub](https://github.com/signup) account.
* A verified [Docker Hub](https://hub.docker.com/signup) account.

***

## [Overview](#overview)

In this section, you'll set up a CI/CD pipeline using [GitHub Actions](https://docs.github.com/en/actions) to automatically:

* Build your Vue.js application inside a Docker container.
* Run tests in a consistent environment.
* Push the production-ready image to [Docker Hub](https://hub.docker.com).

***

## [Connect your GitHub repository to Docker Hub](#connect-your-github-repository-to-docker-hub)

To enable GitHub Actions to build and push Docker images, you’ll securely store your Docker Hub credentials in your new GitHub repository.

### [Step 1: Generate Docker Hub credentials and set GitHub secrets](#step-1-generate-docker-hub-credentials-and-set-github-secrets)

1. Create a Personal Access Token (PAT) from [Docker Hub](https://hub.docker.com)

   1. Go to your **Docker Hub account → Account Settings → Security**.
   2. Generate a new Access Token with **Read/Write** permissions.
   3. Name it something like `docker-vuejs-sample`.
   4. Copy and save the token — you’ll need it in Step 4.

2. Create a repository in [Docker Hub](https://hub.docker.com/repositories/)

   1. Go to your **Docker Hub account → Create a repository**.
   2. For the Repository Name, use something descriptive — for example: `vuejs-sample`.
   3. Once created, copy and save the repository name — you’ll need it in Step 4.

3. Create a new [GitHub repository](https://github.com/new) for your Vue.js project

4. Add Docker Hub credentials as GitHub repository secrets

   In your newly created GitHub repository:

   1. Navigate to: **Settings → Secrets and variables → Actions → New repository secret**.

   2. Add the following secrets:

   | Name                     | Value                                            |
   | ------------------------ | ------------------------------------------------ |
   | `DOCKER_USERNAME`        | Your Docker Hub username                         |
   | `DOCKERHUB_TOKEN`        | Your Docker Hub access token (created in Step 1) |
   | `DOCKERHUB_PROJECT_NAME` | Your Docker Project Name (created in Step 2)     |

   These secrets allow GitHub Actions to authenticate securely with Docker Hub during automated workflows.

5. Connect Your Local Project to GitHub

   Link your local project `docker-vuejs-sample` to the GitHub repository you just created by running the following command from your project root:

   ```console
      $ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git
   ```

   > Important
   >
   > Replace `{your-username}` and `{your-repository}` with your actual GitHub username and repository name.

   To confirm that your local project is correctly connected to the remote GitHub repository, run:

   ```console
   $ git remote -v
   ```

   You should see output similar to:

   ```console
   origin  https://github.com/{your-username}/{your-repository-name}.git (fetch)
   origin  https://github.com/{your-username}/{your-repository-name}.git (push)
   ```

   This confirms that your local repository is properly linked and ready to push your source code to GitHub.

6. Push your source code to GitHub

   Follow these steps to commit and push your local project to your GitHub repository:

   1. Stage all files for commit.

      ```console
      $ git add -A
      ```

      This command stages all changes — including new, modified, and deleted files — preparing them for commit.

   2. Commit the staged changes with a descriptive message.

      ```console
      $ git commit -m "Initial commit"
      ```

      This command creates a commit that snapshots the staged changes with a descriptive message.

   3. Push the code to the `main` branch.

      ```console
      $ git push -u origin main
      ```

      This command pushes your local commits to the `main` branch of the remote GitHub repository and sets the upstream branch.

Once completed, your code will be available on GitHub, and any GitHub Actions workflow you’ve configured will run automatically.

> Note
>
> Learn more about the Git commands used in this step:
>
> * [Git add](https://git-scm.com/docs/git-add) – Stage changes (new, modified, deleted) for commit
> * [Git commit](https://git-scm.com/docs/git-commit) – Save a snapshot of your staged changes
> * [Git push](https://git-scm.com/docs/git-push) – Upload local commits to your GitHub repository
> * [Git remote](https://git-scm.com/docs/git-remote) – View and manage remote repository URLs

***

### [Step 2: Set up the workflow](#step-2-set-up-the-workflow)

Now you'll create a GitHub Actions workflow that builds your Docker image, runs tests, and pushes the image to Docker Hub.

1. Go to your repository on GitHub and select the **Actions** tab in the top menu.

2. Select **Set up a workflow yourself** when prompted.

   This opens an inline editor to create a new workflow file. By default, it will be saved to: `.github/workflows/main.yml`

3. Add the following workflow configuration to the new file:

```yaml
name: CI/CD – Vue.js App with Docker

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

jobs:
  build-test-deploy:
    name: Build, Test & Deploy
    runs-on: ubuntu-latest

    steps:
      # 1. Checkout the codebase
      - name: Checkout Code
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      # 2. Set up Docker Buildx
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      # 3. Cache Docker layers
      - name: Cache Docker Layers
        uses: actions/cache@v5
        with:
          path: /tmp/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-buildx-

      # 4. Cache npm dependencies
      - name: Cache npm Dependencies
        uses: actions/cache@v5
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-npm-

      # 5. Generate build metadata
      - name: Generate Build Metadata
        id: meta
        run: |
          echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT"
          echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"

      # 6. Build Docker image for testing
      - name: Build Dev Docker Image
        uses: docker/build-push-action@v7
        with:
          context: .
          file: Dockerfile.dev
          tags: ${{ steps.meta.outputs.REPO_NAME }}-dev:latest
          load: true
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache,mode=max

      # 7. Run unit tests inside container
      - name: Run Vue.js Tests
        run: |
          docker run --rm \
            --workdir /app \
            --entrypoint "" \
            ${{ steps.meta.outputs.REPO_NAME }}-dev:latest \
            sh -c "npm ci && npm run test -- --ci --runInBand"
        env:
          CI: true
          NODE_ENV: test
        timeout-minutes: 10

      # 8. Log in to Docker Hub
      - name: Docker Hub Login
        uses: docker/login-action@v4
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      # 9. Build and push production image
      - name: Build and Push Production Image
        uses: docker/build-push-action@v7
        with:
          context: .
          file: Dockerfile
          push: true
          platforms: linux/amd64,linux/arm64
          tags: |
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }}
          cache-from: type=local,src=/tmp/.buildx-cache
```

This workflow performs the following tasks for your Vue.js application:

> Note
>
> For more information about `docker/build-push-action`, refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md).

***

### [Step 3: Run the workflow](#step-3-run-the-workflow)

After you've added your workflow file, it's time to trigger and observe the CI/CD process in action.

1. Commit and push your workflow file

   * Select "Commit changes…" in the GitHub editor.

     * Repository name: `${your-repository-name}`

     * Tags include:

       * `latest` – represents the most recent successful build; ideal for quick testing or deployment.
       * `<short-sha>` – a unique identifier based on the commit hash, useful for version tracking, rollbacks, and traceability.

> Tip
>
> To maintain code quality and prevent accidental direct pushes, enable branch protection rules:
>
> * Navigate to your **GitHub repo → Settings → Branches**.
>
> * Under Branch protection rules, click **Add rule**.
>
> * Specify `main` as the branch name.
>
> * Enable options like:
>
>   * *Require a pull request before merging*.
>   * *Require status checks to pass before merging*.
>
> This ensures that only tested and reviewed code is merged into `main` branch.

***

## [Summary](#summary)

In this section, you set up a complete CI/CD pipeline for your containerized Vue.js application using GitHub Actions.

With this setup, your Vue.js application is now ready for automated testing and deployment across environments — increasing confidence, consistency, and team productivity.

***

***

## [Next steps](#next-steps)

Next, learn how you can locally test and debug your Vue.js workloads on Kubernetes before deploying. This helps you ensure your application behaves as expected in a production-like environment, reducing surprises during deployment.

[Test your Vue.js deployment »](https://docs.docker.com/guides/vuejs/deploy/)

----
url: https://docs.docker.com/build/builders/drivers/docker/
----

# Docker driver

***

Table of contents

***

The Buildx Docker driver is the default driver. It uses the BuildKit server components built directly into the Docker Engine. The Docker driver requires no configuration.

Unlike the other drivers, builders using the Docker driver can't be manually created. They're only created automatically from the Docker context.

Images built with the Docker driver are automatically loaded to the local image store.

## [Synopsis](#synopsis)

```console
# The Docker driver is used by buildx by default
docker buildx build .
```

It's not possible to configure which BuildKit version to use, or to pass any additional BuildKit parameters to a builder using the Docker driver. The BuildKit version and parameters are preset by the Docker Engine internally.

If you need additional configuration and flexibility, consider using the [Docker container driver](https://docs.docker.com/build/builders/drivers/docker-container/).

## [Further reading](#further-reading)

For more information on the Docker driver, see the [buildx reference](/reference/cli/docker/buildx/create/#driver).

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/tag/
----

# docker mcp catalog tag

***

| Description | Create a tagged copy of a catalog                              |
| ----------- | -------------------------------------------------------------- |
| Usage       | `docker mcp catalog tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]` |

## [Description](#description)

Create a new catalog by tagging an existing catalog with a new name or version. This creates a copy of the source catalog with a new reference, similar to Docker image tagging.

## [Examples](#examples)

# [Tag a catalog with a new version](#tag-a-catalog-with-a-new-version)

docker mcp catalog tag mcp/my-catalog:v1 mcp/my-catalog:v2

# [Create a tagged copy with a different name](#create-a-tagged-copy-with-a-different-name)

docker mcp catalog tag mcp/team-catalog:latest mcp/prod-catalog:v1.0

# [Tag without explicit version (uses latest)](#tag-without-explicit-version-uses-latest)

docker mcp catalog tag mcp/my-catalog mcp/my-catalog:backup

----
url: https://docs.docker.com/reference/build-checks/stage-name-casing/
----

# StageNameCasing

***

Table of contents

***

## [Output](#output)

```text
Stage name 'BuilderBase' should be lowercase
```

## [Description](#description)

To help distinguish Dockerfile instruction keywords from identifiers, this rule forces names of stages in a multi-stage Dockerfile to be all lowercase.

## [Examples](#examples)

❌ Bad: mixing uppercase and lowercase characters in the stage name.

```dockerfile
FROM alpine AS BuilderBase
```

✅ Good: stage name is all in lowercase.

```dockerfile
FROM alpine AS builder-base
```

----
url: https://docs.docker.com/engine/daemon/prometheus/
----

# Collect Docker metrics with Prometheus

***

Table of contents

***

[Prometheus](https://prometheus.io/) is an open-source systems monitoring and alerting toolkit. You can configure Docker as a Prometheus target.

> Warning
>
> The available metrics and the names of those metrics are in active development and may change at any time.

Currently, you can only monitor Docker itself. You can't currently monitor your application using the Docker target.

## [Example](#example)

The following example shows you how to configure your Docker daemon, set up Prometheus to run as a container on your local machine, and monitor your Docker instance using Prometheus.

### [Configure the daemon](#configure-the-daemon)

To configure the Docker daemon as a Prometheus target, you need to specify the `metrics-address` in the `daemon.json` configuration file. This daemon expects the file to be located at one of the following locations by default. If the file doesn't exist, create it.

* **Linux**: `/etc/docker/daemon.json`
* **Windows Server**: `C:\ProgramData\docker\config\daemon.json`
* **Docker Desktop**: Open the Docker Desktop settings and select **Docker Engine** to edit the file.

Add the following configuration:

```json
{
  "metrics-addr": "127.0.0.1:9323"
}
```

Save the file, or in the case of Docker Desktop for Mac or Docker Desktop for Windows, save the configuration. Restart Docker.

Docker now exposes Prometheus-compatible metrics on port 9323 via the loopback interface. You can configure it to use the wildcard address `0.0.0.0` instead, but this will expose the Prometheus port to the wider network. Consider your threat model carefully when deciding which option best suits your environment.

### [Create a Prometheus configuration](#create-a-prometheus-configuration)

Copy the following configuration file and save it to a location of your choice, for example `/tmp/prometheus.yml`. This is a stock Prometheus configuration file, except for the addition of the Docker job definition at the bottom of the file.

```yml
# my global config
global:
  scrape_interval: 15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
  # scrape_timeout is set to the global default (10s).

  # Attach these labels to any time series or alerts when communicating with
  # external systems (federation, remote storage, Alertmanager).
  external_labels:
    monitor: "codelab-monitor"

# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
rule_files:
  # - "first.rules"
  # - "second.rules"

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: prometheus

    # metrics_path defaults to '/metrics'
    # scheme defaults to 'http'.

    static_configs:
      - targets: ["localhost:9090"]

  - job_name: docker
      # metrics_path defaults to '/metrics'
      # scheme defaults to 'http'.

    static_configs:
      - targets: ["host.docker.internal:9323"]
```

### [Run Prometheus in a container](#run-prometheus-in-a-container)

Next, start a Prometheus container using this configuration.

```console
$ docker run --name my-prometheus \
    --mount type=bind,source=/tmp/prometheus.yml,destination=/etc/prometheus/prometheus.yml \
    -p 9090:9090 \
    --add-host host.docker.internal=host-gateway \
    prom/prometheus
```

If you're using Docker Desktop, the `--add-host` flag is optional. This flag makes sure that the host's internal IP gets exposed to the Prometheus container. Docker Desktop does this by default. The host IP is exposed as the `host.docker.internal` hostname. This matches the configuration defined in `prometheus.yml` in the previous step.

### [Open the Prometheus Dashboard](#open-the-prometheus-dashboard)

Verify that the Docker target is listed at `http://localhost:9090/targets/`.

> Note
>
> You can't access the endpoint URLs on this page directly if you use Docker Desktop.

### [Use Prometheus](#use-prometheus)

Create a graph. Select the **Graphs** link in the Prometheus UI. Choose a metric from the combo box to the right of the **Execute** button, and click **Execute**. The screenshot below shows the graph for `engine_daemon_network_actions_seconds_count`.

The graph shows a pretty idle Docker instance, unless you're already running active workloads on your system.

To make the graph more interesting, run a container that uses some network actions by starting downloading some packages using a package manager:

```console
$ docker run --rm alpine apk add git make musl-dev go
```

Wait a few seconds (the default scrape interval is 15 seconds) and reload your graph. You should see an uptick in the graph, showing the increased network traffic caused by the container you just ran.

## [Next steps](#next-steps)

The example provided here shows how to run Prometheus as a container on your local system. In practice, you'll probably be running Prometheus on another system or as a cloud service somewhere. You can set up the Docker daemon as a Prometheus target in such contexts too. Configure the `metrics-addr` of the daemon and add the address of the daemon as a scrape endpoint in your Prometheus configuration.

```yaml
- job_name: docker
  static_configs:
    - targets: ["docker.daemon.example:PORT"]
```

For more information about Prometheus, refer to the [Prometheus documentation](https://prometheus.io/docs/introduction/overview/)

----
url: https://docs.docker.com/reference/cli/docker/model/inspect/
----

# docker model inspect

***

| Description | Display detailed information on one model |
| ----------- | ----------------------------------------- |
| Usage       | `docker model inspect MODEL`              |

## [Description](#description)

Display detailed information on one model

## [Options](#options)

| Option         | Default | Description                    |
| -------------- | ------- | ------------------------------ |
| `--openai`     |         | List model in an OpenAI format |
| `-r, --remote` |         | Show info for remote models    |

----
url: https://docs.docker.com/reference/cli/docker/container/kill/
----

# docker container kill

***

| Description                                                               | Kill one or more running containers                        |
| ------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Usage                                                                     | `docker container kill [OPTIONS] CONTAINER [CONTAINER...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker kill`                                              |

## [Description](#description)

The `docker kill` subcommand kills one or more containers. The main process inside the container is sent `SIGKILL` signal (default), or the signal that is specified with the `--signal` option. You can reference a container by its ID, ID-prefix, or name.

The `--signal` flag sets the system call signal that is sent to the container. This signal can be a signal name in the format `SIG<NAME>`, for instance `SIGINT`, or an unsigned number that matches a position in the kernel's syscall table, for instance `2`.

While the default (`SIGKILL`) signal will terminate the container, the signal set through `--signal` may be non-terminal, depending on the container's main process. For example, the `SIGHUP` signal in most cases will be non-terminal, and the container will continue running after receiving the signal.

> Note
>
> `ENTRYPOINT` and `CMD` in the *shell* form run as a child process of `/bin/sh -c`, which does not pass signals. This means that the executable is not the container’s PID 1 and does not receive Unix signals.

## [Options](#options)

| Option                    | Default | Description                     |
| ------------------------- | ------- | ------------------------------- |
| [`-s, --signal`](#signal) |         | Signal to send to the container |

## [Examples](#examples)

### [Send a KILL signal to a container](#send-a-kill-signal-to-a-container)

The following example sends the default `SIGKILL` signal to the container named `my_container`:

```console
$ docker kill my_container
```

### [Send a custom signal to a container (--signal)](#signal)

The following example sends a `SIGHUP` signal to the container named `my_container`:

```console
$ docker kill --signal=SIGHUP  my_container
```

You can specify a custom signal either by *name*, or *number*. The `SIG` prefix is optional, so the following examples are equivalent:

```console
$ docker kill --signal=SIGHUP my_container
$ docker kill --signal=HUP my_container
$ docker kill --signal=1 my_container
```

Refer to the [`signal(7)`](https://man7.org/linux/man-pages/man7/signal.7.html) man-page for a list of standard Linux signals.

----
url: https://docs.docker.com/reference/samples/rails/
----

# Rails samples

| Name                                                                                                             | Description                                                                                         |
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [Compose and Rails](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/rails/) | This Quickstart guide shows you how to use Docker Compose to set up and run a Rails/PostgreSQL app. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/guides/grafana-mcp-server-gemini/
----

[Connect Gemini to Grafana via MCP](https://docs.docker.com/guides/grafana-mcp-server-gemini/)

Learn how to leverage the Model Context Protocol (MCP) to interact with Grafana dashboards and datasources directly from your terminal.

15 minutes

[« Back to all guides](/guides/)

# Connect Gemini to Grafana via MCP

***

Table of contents

***

This guide shows how to connect Gemini CLI to a Grafana instance using the **Docker MCP Toolkit**.

## [Prerequisites](#prerequisites)

* **Gemini CLI** installed and authenticated.
* **Docker Desktop** with the **MCP Toolkit** extension enabled.
* An active **Grafana** instance.

## [Step 1: Provision Grafana access](#step-1-provision-grafana-access)

The MCP server requires a **Service Account Token** to interact with the Grafana API. Service Account Tokens are preferred over personal API keys because they can be revoked independently without affecting user access, and permissions can be scoped more narrowly.

1. Navigate to **Administration > Users and access > Service accounts** in your Grafana dashboard.
2. Create a new Service Account (e.g., `gemini-mcp-connector`).
3. Assign the **Viewer** role (or **Editor** if you require alert management capabilities).
4. Generate a new token. Copy the token immediately — you won't be able to view it again.

## [Step 2: Configure the MCP server](#step-2-configure-the-mcp-server)

The Docker MCP Toolkit provides a pre-configured Grafana catalog item. This connects the LLM to the Grafana API.

1. Open the **MCP Toolkit** in Docker Desktop.
2. Locate **Grafana** in the Catalog and add it to your active servers.
3. In the **Configuration** view, define the following:

* **Grafana URL:** The endpoint or URL of your instance.
* **Service Account Token:** The token generated in the previous step.

## [Step 3: Integrate Gemini CLI](#step-3-integrate-gemini-cli)

To register the Docker MCP gateway within Gemini, update your global configuration file located at `~/.gemini/settings.json`.

Ensure the `mcpServers` object includes the following entry:

```json
{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}
```

## [Step 4: Validate the setup](#step-4-validate-the-setup)

Restart your Gemini CLI session to load the new configuration. Verify the status of the MCP tools by running:

```bash
> /mcp list
```

A successful connection will show `MCP_DOCKER` as **Ready**, exposing dozens tools for data fetching, dashboard searching, and alert inspection.

## [Use Cases](#use-cases)

### [Data source Discovery](#data-source-discovery)

*List all Prometheus and Loki data sources.*

### [Logs Inspection](#logs-inspection)

Gemini performs intent parsing and translates the user's request into a precise LogQL query: `{device_name="edge-device-01"} |= "nginx"`. Once the system identifies Loki as the active datasource, the AI autonomously constructs this command to bridge the gap between human intent and complex syntax. This query targets specific Kubernetes pod logs, extracting raw OpenTelemetry (OTel) data—including pod UIDs, container metadata, and system labels—which Gemini then uses to identify the root cause of the issue within the containerized environment.

In the final step, Gemini performs reasoning over the raw telemetry. After filtering through hundreds of lines to confirm the existence of Nginx logs, Gemini extracts a specific node\_filesystem\_device\_error buried within the stream. By surfacing this critical event, it alerts the DevOps engineer to a volume mounting issue on the edge node, transforming raw data into an actionable incident report.

### [Dashboard Navigation](#dashboard-navigation)

*How many dashboards do we have?*

*Tell me the summary of X dashboard*

### [Other scenarios](#other-scenarios)

Imagine you get a page that an application is slow. You could:

1. Use `list_alert_rules` to see which alert is firing.
2. Use `search_dashboards` to find the relevant application dashboard.
3. Use `get_panel_image` on a key panel to see the performance spike visually.
4. Use `query_loki_logs` to search for "error" or "timeout" messages during the time of the spike.
5. If you find the root cause, use create\_incident to start the formal response and `add_activity_to_incident` to log your findings.

## [Next steps](#next-steps)

* Learn about [Advanced LogQL queries](https://grafana.com/docs/loki/latest/query/log_queries/)
* Set up [Team-wide MCP configurations](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
* Explore [Grafana alerting with MCP](https://github.com/grafana/mcp-grafana)
* Get help in the [Docker Community Forums](https://forums.docker.com)

Need help setting up your Docker MCP environment or customizing your Gemini prompts? Visit the [Docker Community Forums](https://forums.docker.com) or see the [Get Started Guide](https://docs.docker.com/ai/mcp-catalog-and-toolkit/get-started/).

----
url: https://docs.docker.com/guides/testcontainers-java-jooq-flyway/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

```console
$ ./mvnw test
```

You should see the PostgreSQL Docker container start, jOOQ code generation complete, and all tests pass. After the tests finish, the container stops and is removed automatically.

## [Summary](#summary)

The Testcontainers library helps you generate Java code from the database using the jOOQ code generator and test your persistence layer against the same type of database (PostgreSQL) that you use in production, instead of mocks or in-memory databases.

Because the code is always generated from the database's current state, you can be confident that your code stays in sync with database changes. You're free to refactor and still verify that the application works as expected.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [jOOQ documentation](https://www.jooq.org/)
* [jOOQ code generation](https://www.jooq.org/doc/latest/manual/code-generation/)
* [Spring Boot Testcontainers support](https://docs.spring.io/spring-boot/reference/testing/testcontainers.html)
* [Replace H2 with a real database for testing](/guides/testcontainers-java-replace-h2/)

----
url: https://docs.docker.com/guides/golang/run-tests/
----

# Run your tests using Go test

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete the [Build your Go image](https://docs.docker.com/guides/golang/build-images/) section of this guide.

## [Overview](#overview)

Testing is an essential part of modern software development. Testing can mean a lot of things to different development teams. There are unit tests, integration tests and end-to-end testing. In this guide you take a look at running your unit tests in Docker when building.

For this section, use the `docker-gs-ping` project that you cloned in [Build your Go image](https://docs.docker.com/guides/golang/build-images/).

## [Run tests when building](#run-tests-when-building)

To run your tests when building, you need to add a test stage to the `Dockerfile.multistage`. The `Dockerfile.multistage` in the sample application's repository already has the following content:

```dockerfile
# syntax=docker/dockerfile:1

# Build the application from source
FROM golang:1.19 AS build-stage

WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY *.go ./

RUN CGO_ENABLED=0 GOOS=linux go build -o /docker-gs-ping

# Run the tests in the container
FROM build-stage AS run-test-stage
RUN go test -v ./...

# Deploy the application binary into a lean image
FROM gcr.io/distroless/base-debian11 AS build-release-stage

WORKDIR /

COPY --from=build-stage /docker-gs-ping /docker-gs-ping

EXPOSE 8080

USER nonroot:nonroot

ENTRYPOINT ["/docker-gs-ping"]
```

Run the following command to build an image using the `run-test-stage` stage as the target and view the test results. Include `--progress plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target run-test-stage` to target the test stage.

```console
$ docker build -f Dockerfile.multistage -t docker-gs-ping-test --progress plain --no-cache --target run-test-stage .
```

You should see output containing the following.

```text
#13 [run-test-stage 1/1] RUN go test -v ./...
#13 4.915 === RUN   TestIntMinBasic
#13 4.915 --- PASS: TestIntMinBasic (0.00s)
#13 4.915 === RUN   TestIntMinTableDriven
#13 4.915 === RUN   TestIntMinTableDriven/0,1
#13 4.915 === RUN   TestIntMinTableDriven/1,0
#13 4.915 === RUN   TestIntMinTableDriven/2,-2
#13 4.915 === RUN   TestIntMinTableDriven/0,-1
#13 4.915 === RUN   TestIntMinTableDriven/-1,0
#13 4.915 --- PASS: TestIntMinTableDriven (0.00s)
#13 4.915     --- PASS: TestIntMinTableDriven/0,1 (0.00s)
#13 4.915     --- PASS: TestIntMinTableDriven/1,0 (0.00s)
#13 4.915     --- PASS: TestIntMinTableDriven/2,-2 (0.00s)
#13 4.915     --- PASS: TestIntMinTableDriven/0,-1 (0.00s)
#13 4.915     --- PASS: TestIntMinTableDriven/-1,0 (0.00s)
#13 4.915 PASS
```

## [Next steps](#next-steps)

In this section, you learned how to run tests when building your image. Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions.

[Configure CI/CD for your Go application »](https://docs.docker.com/guides/golang/configure-ci-cd/)

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/
----

# MCP Gateway

***

Table of contents

***

The MCP Gateway is Docker's open source solution for orchestrating Model Context Protocol (MCP) servers. It acts as a centralized proxy between clients and servers, managing configuration, credentials, and access control.

When using MCP servers without the MCP Gateway, you need to configure applications individually for each AI application. With the MCP Gateway, you configure applications to connect to the Gateway. The Gateway then handles server lifecycle, routing, and authentication across all servers in your [profiles](https://docs.docker.com/ai/mcp-catalog-and-toolkit/profiles/).

> Note
>
> If you use Docker Desktop with MCP Toolkit enabled, the Gateway runs automatically in the background. You don't need to start or configure it manually. This documentation is for users who want to understand how the Gateway works or run it directly for advanced use cases.

> Tip
>
> E2B sandboxes now include direct access to the Docker MCP Catalog, giving developers access to over 200 tools and services to seamlessly build and run AI agents. For more information, see [E2B Sandboxes](https://docs.docker.com/ai/sandboxes/).

## [How it works](#how-it-works)

MCP Gateway runs MCP servers in isolated Docker containers with restricted privileges, network access, and resource usage. It includes built-in logging and call-tracing capabilities to ensure full visibility and governance of AI tool activity.

The MCP Gateway manages the server's entire lifecycle. When an AI application needs to use a tool, it sends a request to the Gateway. The Gateway identifies which server handles that tool and, if the server isn't already running, starts it as a Docker container. The Gateway then injects any required credentials, applies security restrictions, and forwards the request to the server. The server processes the request and returns the result through the Gateway back to the AI application.

The MCP Gateway solves a fundamental problem: MCP servers are just programs that need to run somewhere. Running them directly on your machine means dealing with installation, dependencies, updates, and security risks. By running them as containers managed by the Gateway, you get isolation, consistent environments, and centralized control.

The Gateway works with profiles to determine which servers are available. When you run the Gateway, you specify which profile to use with the `--profile` flag to determine which servers are made available to clients.

## [Usage](#usage)

To use the MCP Gateway, you'll need Docker Desktop with MCP Toolkit enabled. Follow the [MCP Toolkit guide](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/) to enable and configure servers through the Docker Desktop interface, or see [Use MCP Toolkit from the CLI](https://docs.docker.com/ai/mcp-catalog-and-toolkit/cli/) for terminal-based workflows.

### [Install the MCP Gateway manually](#install-the-mcp-gateway-manually)

For Docker Engine without Docker Desktop, you'll need to download and install the MCP Gateway separately before you can run it.

1. Download the latest binary from the [GitHub releases page](https://github.com/docker/mcp-gateway/releases/latest).

2. Move or symlink the binary to the destination matching your OS:

   | OS      | Binary destination                  |
   | ------- | ----------------------------------- |
   | Linux   | `~/.docker/cli-plugins/docker-mcp`  |
   | macOS   | `~/.docker/cli-plugins/docker-mcp`  |
   | Windows | `%USERPROFILE%\.docker\cli-plugins` |

3. Make the binaries executable:

   ```bash
   $ chmod +x ~/.docker/cli-plugins/docker-mcp
   ```

You can now use the `docker mcp` command:

```bash
docker mcp --help
```

## [Additional information](#additional-information)

For more details on how the MCP Gateway works and available customization options, see the complete documentation [on GitHub](https://github.com/docker/mcp-gateway).

----
url: https://docs.docker.com/reference/cli/docker/model/context/create/
----

# docker model context create

***

| Description | Create a named Model Runner context |
| ----------- | ----------------------------------- |
| Usage       | `docker model context create NAME`  |

## [Description](#description)

Create a named Model Runner context

## [Options](#options)

| Option              | Default | Description                                                   |
| ------------------- | ------- | ------------------------------------------------------------- |
| `--description`     |         | Optional human-readable description for this context          |
| `--host`            |         | Model Runner API base URL (e.g. http\://192.168.1.100:12434)  |
| `--tls`             |         | Enable TLS for connections to this context                    |
| `--tls-ca-cert`     |         | Path to a custom CA certificate PEM file for TLS verification |
| `--tls-skip-verify` |         | Skip TLS server certificate verification                      |

----
url: https://docs.docker.com/build/checks/
----

# Checking your build configuration

***

Table of contents

***

> Tip
>
> To improve linting, code navigation, and vulnerability scanning of your Dockerfiles in Visual Studio Code see the [Docker DX](https://marketplace.visualstudio.com/items?itemName=docker.docker) extension.

## [Build with checks](#build-with-checks)

Build checks are supported in:

* Buildx version 0.15.0 and later
* [docker/build-push-action](https://github.com/docker/build-push-action) version 6.6.0 and later
* [docker/bake-action](https://github.com/docker/bake-action) version 5.6.0 and later

Invoking a build runs the checks by default, and displays any violations in the build output. For example, the following command both builds the image and runs the checks:

```console
$ docker build .
[+] Building 3.5s (11/11) FINISHED
...

1 warning found (use --debug to expand):
  - Lint Rule 'JSONArgsRecommended': JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 7)
```

In this example, the build ran successfully, but a [JSONArgsRecommended](/reference/build-checks/json-args-recommended/) warning was reported, because `CMD` instructions should use JSON array syntax.

With the GitHub Actions, the checks display in the diff view of pull requests.

```yaml
name: Build and push Docker images
on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build and push
        uses: docker/build-push-action@v7
```

### [More verbose output](#more-verbose-output)

Check warnings for a regular `docker build` display a concise message containing the rule name, the message, and the line number of where in the Dockerfile the issue originated. If you want to see more detailed information about the checks, you can use the `--debug` flag. For example:

```console
$ docker --debug build .
[+] Building 3.5s (11/11) FINISHED
...

 1 warning found:
 - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 4)
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals
More info: https://docs.docker.com/go/dockerfile/rule/json-args-recommended/
Dockerfile:4
--------------------
   2 |
   3 |     FROM alpine
   4 | >>> CMD echo "Hello, world!"
   5 |
--------------------
```

With the `--debug` flag, the output includes a link to the documentation for the check, and a snippet of the Dockerfile where the issue was found.

## [Check a build without building](#check-a-build-without-building)

To run build checks without actually building, you can use the `docker build` command as you typically would, but with the addition of the `--check` flag. Here's an example:

```console
$ docker build --check .
```

Instead of executing the build steps, this command only runs the checks and reports any issues it finds. If there are any issues, they will be reported in the output. For example:

Output with --check

```text
[+] Building 1.5s (5/5) FINISHED
=> [internal] connecting to local controller
=> [internal] load build definition from Dockerfile
=> => transferring dockerfile: 253B
=> [internal] load metadata for docker.io/library/node:22
=> [auth] library/node:pull token for registry-1.docker.io
=> [internal] load .dockerignore
=> => transferring context: 50B
JSONArgsRecommended - https://docs.docker.com/go/dockerfile/rule/json-args-recommended/
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals
Dockerfile:7
--------------------
5 |
6 |     COPY index.js .
7 | >>> CMD node index.js
8 |
--------------------
```

This output with `--check` shows the [verbose message](#more-verbose-output) for the check.

Unlike a regular build, if any violations are reported when using the `--check` flag, the command exits with a non-zero status code.

## [Fail build on check violations](#fail-build-on-check-violations)

Check violations for builds are reported as warnings, with exit code 0, by default. You can configure Docker to fail the build when violations are reported, using a `check=error=true` directive in your Dockerfile. This will cause the build to error out when after the build checks are run, before the actual build gets executed.

Dockerfile

|                   |                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| ```
1
2
3
4
5
``` | ```dockerfile
# syntax=docker/dockerfile:1
# check=error=true

FROM alpine
CMD echo "Hello, world!"
``` |

Without the `# check=error=true` directive, this build would complete with an exit code of 0. However, with the directive, build check violation results in non-zero exit code:

```console
$ docker build .
[+] Building 1.5s (5/5) FINISHED
...

 1 warning found (use --debug to expand):
 - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 5)
Dockerfile:1
--------------------
   1 | >>> # syntax=docker/dockerfile:1
   2 |     # check=error=true
   3 |
--------------------
ERROR: lint violation found for rules: JSONArgsRecommended
$ echo $?
1
```

You can also set the error directive on the CLI by passing the `BUILDKIT_DOCKERFILE_CHECK` build argument:

```console
$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=error=true" .
```

## [Skip checks](#skip-checks)

By default, all checks are run when you build an image. If you want to skip specific checks, you can use the `check=skip` directive in your Dockerfile. The `skip` parameter takes a CSV string of the check IDs you want to skip. For example:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=skip=JSONArgsRecommended,StageNameCasing

FROM alpine AS BASE_STAGE
CMD echo "Hello, world!"
```

Building this Dockerfile results in no check violations.

You can also skip checks by passing the `BUILDKIT_DOCKERFILE_CHECK` build argument with a CSV string of check IDs you want to skip. For example:

```console
$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing" .
```

To skip all checks, use the `skip=all` parameter:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=skip=all
```

## [Combine error and skip parameters for check directives](#combine-error-and-skip-parameters-for-check-directives)

To both skip specific checks and error on check violations, pass both the `skip` and `error` parameters separated by a semi-colon (`;`) to the `check` directive in your Dockerfile or in a build argument. For example:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=skip=JSONArgsRecommended,StageNameCasing;error=true
```

Build argument

```console
$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing;error=true" .
```

## [Experimental checks](#experimental-checks)

Before checks are promoted to stable, they may be available as experimental checks. Experimental checks are disabled by default. To see the list of experimental checks available, refer to the [Build checks reference](/reference/build-checks/).

To enable all experimental checks, set the `BUILDKIT_DOCKERFILE_CHECK` build argument to `experimental=all`:

```console
$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=experimental=all" .
```

You can also enable experimental checks in your Dockerfile using the `check` directive:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=experimental=all
```

To selectively enable experimental checks, you can pass a CSV string of the check IDs you want to enable, either to the `check` directive in your Dockerfile or as a build argument. For example:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=experimental=JSONArgsRecommended,StageNameCasing
```

Note that the `experimental` directive takes precedence over the `skip` directive, meaning that experimental checks will run regardless of the `skip` directive you have set. For example, if you set `skip=all` and enable experimental checks, the experimental checks will still run:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=skip=all;experimental=all
```

## [Further reading](#further-reading)

For more information about using build checks, see:

* [Build checks reference](/reference/build-checks/)
* [Validating build configuration with GitHub Actions](https://docs.docker.com/build/ci/github-actions/checks/)

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/faq/
----

# Enhanced Container Isolation FAQs

***

Table of contents

***

Subscription: Business

For: Administrators

This page answers common questions about Enhanced Container Isolation (ECI) that aren't covered in the main documentation.

## [Do I need to change the way I use Docker when ECI is switched on?](#do-i-need-to-change-the-way-i-use-docker-when-eci-is-switched-on)

No. ECI works automatically in the background by creating more secure containers. You can continue using all your existing Docker commands, workflows, and development tools without any changes.

## [Do all container workloads work well with ECI?](#do-all-container-workloads-work-well-with-eci)

Most container workloads run without issues when ECI is turned on. However, some advanced workloads that require specific kernel-level access may not work. For details about which workloads are affected, see [ECI limitations](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations/).

## [Why not just restrict usage of the `--privileged` flag?](#why-not-just-restrict-usage-of-the---privileged-flag)

Privileged containers serve legitimate purposes like Docker-in-Docker, Kubernetes-in-Docker, and accessing hardware devices. ECI provides a better solution by allowing these advanced workloads to run securely while preventing them from compromising the Docker Desktop VM.

## [Does ECI affect container performance?](#does-eci-affect-container-performance)

ECI has minimal impact on container performance. The only exception is containers that perform many `mount` and `umount` system calls, as these are inspected by the Sysbox runtime for security. Most development workloads see no noticeable performance difference.

## [Can I override the container runtime with ECI turned on?](#can-i-override-the-container-runtime-with-eci-turned-on)

No. When ECI is turned on, all containers use the Sysbox runtime regardless of any `--runtime` flags:

```console
$ docker run --runtime=runc alpine echo "test"
# This still uses sysbox-runc, not runc
```

The `--runtime` flag is ignored to prevent users from bypassing ECI security by running containers as true root in the Docker Desktop VM.

## [Does ECI protect containers created before turning it on?](#does-eci-protect-containers-created-before-turning-it-on)

No. ECI only protects containers created after it's turned on. Remove existing containers before turning on ECI:

```console
$ docker stop $(docker ps -q)
$ docker rm $(docker ps -aq)
```

For more details, see [Enable Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/enable-eci/).

## [Which containers does ECI protect?](#which-containers-does-eci-protect)

ECI protection varies by container type and Docker Desktop version:

### [Always protected](#always-protected)

* Containers created with `docker run` and `docker create`
* Containers using the `docker-container` build driver
* Kubernetes with the Kind provisioner

### [Platform dependent](#platform-dependent)

* Docker Build: Protected in Docker Desktop for Mac, Linux, and Windows with Hyper-V backend

### [Not protected](#not-protected)

* Docker Extensions
* Docker Debug containers
* Kubernetes with Kubeadm provisioner

For complete details, see [ECI limitations](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations/).

## [Can I mount the Docker socket with ECI turned on?](#can-i-mount-the-docker-socket-with-eci-turned-on)

By default, no. ECI blocks Docker socket bind mounts for security. However, you can configure exceptions for trusted images like Testcontainers.

For configuration details, see [Configure Docker socket exceptions](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/).

## [What bind mounts does ECI restrict?](#what-bind-mounts-does-eci-restrict)

ECI restricts bind mounts of Docker Desktop VM directories but allows host directory mounts configured in Docker Desktop Settings.

----
url: https://docs.docker.com/ai/sandboxes/agents/kiro/
----

# Kiro

***

Table of contents

***

This guide covers authentication, configuration, and usage of Kiro in a sandboxed environment.

Official documentation: [Kiro CLI](https://kiro.dev/docs/cli/)

## [Quick start](#quick-start)

Create a sandbox and run Kiro for a project directory:

```console
$ sbx run kiro ~/my-project
```

The workspace parameter is optional and defaults to the current directory:

```console
$ cd ~/my-project
$ sbx run kiro
```

On first run, Kiro prompts you to authenticate using device flow.

## [Authentication](#authentication)

Kiro uses device flow authentication, which requires interactive login through a web browser. This method provides secure authentication without storing API keys directly.

### [Device flow login](#device-flow-login)

When you first run Kiro, it prompts you to authenticate:

1. Kiro displays a URL and a verification code
2. Open the URL in your web browser
3. Enter the verification code
4. Complete the authentication flow in your browser
5. Return to the terminal - Kiro proceeds automatically

The authentication session is persisted in the sandbox and doesn't require repeated login unless you destroy and recreate the sandbox.

### [Manual login](#manual-login)

You can trigger the login flow manually:

```console
$ sbx run kiro --name <sandbox-name> -- login --use-device-flow
```

This command initiates device flow authentication without starting a coding session.

### [Authentication persistence](#authentication-persistence)

Kiro stores authentication state in `~/.local/share/kiro-cli/data.sqlite3` inside the sandbox. This database persists as long as the sandbox exists. If you destroy the sandbox, you'll need to authenticate again when you recreate it.

## [Configuration](#configuration)

Sandboxes don't pick up user-level configuration from your host. Only project-level configuration in the working directory is available inside the sandbox. See [Why doesn't the sandbox use my user-level agent configuration?](https://docs.docker.com/ai/sandboxes/faq/#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for workarounds.

Kiro requires minimal configuration. The agent runs with trust-all-tools mode by default, which lets it execute commands without repeated approval prompts.

### [Default startup command](#default-startup-command)

Without extra args, the sandbox runs:

```text
kiro chat --trust-all-tools
```

Args after `--` replace these defaults rather than being appended. This is why `sbx run kiro -- login --use-device-flow` works for the login subcommand. To keep `chat --trust-all-tools` alongside your own args, include them yourself:

```console
$ sbx run kiro -- chat --trust-all-tools --resume
```

## [Base image](#base-image)

Template: `docker/sandbox-templates:kiro`

Authentication state is persisted across sandbox restarts.

----
url: https://docs.docker.com/build/ci/github-actions/copy-image-registries/
----

# Copy image between registries with GitHub Actions

***

***

[Multi-platform images](https://docs.docker.com/build/building/multi-platform/) built using Buildx can be copied from one registry to another using the [`buildx imagetools create` command](/reference/cli/docker/buildx/imagetools/create/):

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: |
            user/app:latest
            user/app:1.0.0

      - name: Push image to GHCR
        run: |
          docker buildx imagetools create \
            --tag ghcr.io/user/app:latest \
            --tag ghcr.io/user/app:1.0.0 \
            user/app:latest
```

----
url: https://docs.docker.com/reference/cli/sbx/cp/
----

# sbx cp

| Description | Copy files or directories between a sandbox and the host |
| ----------- | -------------------------------------------------------- |
| Usage       | `sbx cp [flags] SRC DST`                                 |

## [Description](#description)

Either SRC or DST must be a sandbox path, written as SANDBOX:PATH. The other must be a local path. Copying between two sandboxes is not supported.

When copying a directory, the directory itself is placed at the destination. If the destination path does not exist it is created; if it already exists as a directory, the source is placed inside it.

## [Options](#options)

| Option              | Default | Description                                                                |
| ------------------- | ------- | -------------------------------------------------------------------------- |
| `-L, --follow-link` |         | Follow symbolic links in the source path when copying from host to sandbox |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Copy a file from host to sandbox
sbx cp ./config.json my-sandbox:/home/user/

# Copy a file from sandbox to host
sbx cp my-sandbox:/home/user/output.log ./

# Copy a directory
sbx cp ./src/ my-sandbox:/home/user/src
```

----
url: https://docs.docker.com/guides/admin-set-up/testing/
----

# Testing

***

Table of contents

***

## [SSO and SCIM testing](#sso-and-scim-testing)

Test SSO and SCIM by signing in to Docker Desktop or Docker Hub with the email address linked to a Docker account that is part of the verified domain. Developers who sign in using their Docker usernames remain unaffected by the SSO and SCIM setup.

> Important
>
> Some users may need CLI based logins to Docker Hub, and for this they will need a [personal access token (PAT)](https://docs.docker.com/security/access-tokens/).

## [Test Registry Access Management and Image Access Management](#test-registry-access-management-and-image-access-management)

> Warning
>
> Communicate with your users before proceeding, as this step will impact all existing users signing into your Docker organization.

If you plan to use [Registry Access Management (RAM)](https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/) and/or [Image Access Management (IAM)](https://docs.docker.com/enterprise/security/hardened-desktop/image-access-management/):

1. Ensure your test developer signs in to Docker Desktop using their organization credentials
2. Have them attempt to pull an unauthorized image or one from a disallowed registry via the Docker CLI
3. Verify they receive an error message indicating that the registry is restricted by the organization

## [Deploy settings and enforce sign in to test group](#deploy-settings-and-enforce-sign-in-to-test-group)

Deploy the Docker settings and enforce sign-in for a small group of test users via MDM. Have this group test their development workflows with containers on Docker Desktop and Docker Hub to ensure all settings and the sign-in enforcement function as expected.

## [Test Docker Build Cloud capabilities](#test-docker-build-cloud-capabilities)

Have one of your Docker Desktop testers [connect to the cloud builder you created and use it to build](https://docs.docker.com/build-cloud/usage/).

## [Test Testcontainers Cloud](#test-testcontainers-cloud)

Have a test developer [connect to Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started) and run a container in the cloud to verify the setup is working correctly.

## [Verify Docker Scout monitoring of repositories](#verify-docker-scout-monitoring-of-repositories)

Check the [Docker Scout dashboard](https://scout.docker.com/) to confirm that data is being properly received for the repositories where Docker Scout has been enabled.

## [Verify access to Docker Hardened Images](#verify-access-to-docker-hardened-images)

Have a test developer attempt to [pull a Docker Hardened Image](https://docs.docker.com/dhi/get-started/) to confirm that the team has proper access and can integrate these images into their workflows.

[Deploy your Docker setup »](https://docs.docker.com/guides/admin-set-up/deploy/)

----
url: https://docs.docker.com/reference/cli/sbx/create/
----

# sbx create

| Description | Create a sandbox for an agent             |
| ----------- | ----------------------------------------- |
| Usage       | `sbx create [flags] AGENT PATH [PATH...]` |

## [Description](#description)

Create a sandbox with access to a host workspace for an agent.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Commands](#commands)

| Command                                                                                     | Description                       |
| ------------------------------------------------------------------------------------------- | --------------------------------- |
| [`sbx create claude`](https://docs.docker.com/reference/cli/sbx/create/claude/)             | Create a sandbox for claude       |
| [`sbx create codex`](https://docs.docker.com/reference/cli/sbx/create/codex/)               | Create a sandbox for codex        |
| [`sbx create copilot`](https://docs.docker.com/reference/cli/sbx/create/copilot/)           | Create a sandbox for copilot      |
| [`sbx create cursor`](https://docs.docker.com/reference/cli/sbx/create/cursor/)             | Create a sandbox for cursor       |
| [`sbx create docker-agent`](https://docs.docker.com/reference/cli/sbx/create/docker-agent/) | Create a sandbox for docker-agent |
| [`sbx create droid`](https://docs.docker.com/reference/cli/sbx/create/droid/)               | Create a sandbox for droid        |
| [`sbx create gemini`](https://docs.docker.com/reference/cli/sbx/create/gemini/)             | Create a sandbox for gemini       |
| [`sbx create kiro`](https://docs.docker.com/reference/cli/sbx/create/kiro/)                 | Create a sandbox for kiro         |
| [`sbx create opencode`](https://docs.docker.com/reference/cli/sbx/create/opencode/)         | Create a sandbox for opencode     |
| [`sbx create shell`](https://docs.docker.com/reference/cli/sbx/create/shell/)               | Create a sandbox for shell        |

## [Options](#options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Create a sandbox for Claude in the current directory
sbx create claude .

# Create a sandbox with a custom name
sbx create --name my-project claude /path/to/project

# Create with additional read-only workspaces
sbx create claude . /path/to/docs:ro

# Run the agent on an in-container clone of the host repo, wired back via a git-daemon
sbx create --clone claude .
```

----
url: https://docs.docker.com/reference/cli/docker/mcp/gateway/
----

# docker mcp gateway

***

| Description | Manage the MCP Server gateway |
| ----------- | ----------------------------- |

## [Description](#description)

Manage the MCP Server gateway

## [Subcommands](#subcommands)

| Command                                                                                   | Description     |
| ----------------------------------------------------------------------------------------- | --------------- |
| [`docker mcp gateway run`](https://docs.docker.com/reference/cli/docker/mcp/gateway/run/) | Run the gateway |

----
url: https://docs.docker.com/guides/testcontainers-java-lifecycle/extension-annotations/
----

# JUnit 5 extension annotations

***

***

The Testcontainers library provides a JUnit 5 extension that simplifies starting and stopping containers using annotations. To use it, add the `org.testcontainers:testcontainers-junit-jupiter` test dependency.

```java
package com.testcontainers.demo;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.List;
import java.util.Optional;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.testcontainers.postgresql.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@Testcontainers
class CustomerServiceWithJUnit5ExtensionTest {

  @Container
  static PostgreSQLContainer postgres = new PostgreSQLContainer(
    "postgres:16-alpine"
  );

  CustomerService customerService;

  @BeforeEach
  void setUp() {
    customerService =
    new CustomerService(
      postgres.getJdbcUrl(),
      postgres.getUsername(),
      postgres.getPassword()
    );
    customerService.deleteAllCustomers();
  }

  @Test
  void shouldCreateCustomer() {
    customerService.createCustomer(new Customer(1L, "George"));

    Optional<Customer> customer = customerService.getCustomer(1L);
    assertTrue(customer.isPresent());
    assertEquals(1L, customer.get().id());
    assertEquals("George", customer.get().name());
  }

  @Test
  void shouldGetCustomers() {
    customerService.createCustomer(new Customer(1L, "George"));
    customerService.createCustomer(new Customer(2L, "John"));

    List<Customer> customers = customerService.getAllCustomers();
    assertEquals(2, customers.size());
  }
}
```

Instead of manually starting and stopping the container in `@BeforeAll` and `@AfterAll`, the `@Testcontainers` annotation on the class and the `@Container` annotation on the field handle it automatically:

* The extension finds all `@Container`-annotated fields.
* **Static fields** start once before all tests and stop after all tests.
* **Instance fields** start before each test and stop after each test (not recommended — it's resource-intensive).

[Singleton containers pattern »](https://docs.docker.com/guides/testcontainers-java-lifecycle/singleton-containers/)

----
url: https://docs.docker.com/reference/samples/express/
----

# Express samples

| Name                                                                                                     | Description                                                             |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [React / Express / MySQL](https://github.com/docker/awesome-compose/tree/master/react-express-mysql)     | A sample React application with a Node.js backend and a MySQL database. |
| [React / Express / MongoDB](https://github.com/docker/awesome-compose/tree/master/react-express-mongodb) | A sample React application with a Node.js backend and a Mongo database. |
| [slack-clone-docker](https://github.com/dockersamples/slack-clone-docker)                                | A sample Slack Clone app built with the MERN stack.                     |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/guides/rust/build-images/
----

# Build your Rust image

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client.

## [Overview](#overview)

This guide walks you through building your first Rust image. An image includes everything needed to run an application - the code or binary, runtime, dependencies, and any other file system objects required.

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/docker/docker-rust-hello && cd docker-rust-hello
```

## [Choose a base image](#choose-a-base-image)

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

Before editing your Dockerfile, you need to choose a base image. You can use the [Rust Docker Official Image](https://hub.docker.com/_/rust),\
or a [Docker Hardened Image (DHI)](https://hub.docker.com/hardened-images/catalog/dhi/rust).

Docker Hardened Images (DHIs) are minimal, secure, and production-ready base images maintained by Docker.\
They help reduce vulnerabilities and simplify compliance. For more details, see [Docker Hardened Images](/dhi/).

Docker Hardened Images (DHIs) are publicly available and can be used directly as base images. To pull Docker Hardened Images, authenticate once with Docker:

```bash
docker login dhi.io
```

Use DHIs from the dhi.io registry, for example:

```bash
FROM dhi.io/rust:${RUST_VERSION}-alpine3.22-dev AS build
```

The following Dockerfile uses a Rust DHI as the build base image:

Dockerfile

```dockerfile
# Make sure RUST_VERSION matches the Rust version
ARG RUST_VERSION=1.92
ARG APP_NAME=docker-rust-hello

################################################################################
# Create a stage for building the application.
################################################################################

FROM dhi.io/rust:${RUST_VERSION}-alpine3.22-dev AS build
ARG APP_NAME
WORKDIR /app

# Install host build dependencies.
RUN apk add --no-cache clang lld musl-dev git

# Build the application.
RUN --mount=type=bind,source=src,target=src \
    --mount=type=bind,source=Cargo.toml,target=Cargo.toml \
    --mount=type=bind,source=Cargo.lock,target=Cargo.lock \
    --mount=type=cache,target=/app/target/ \
    --mount=type=cache,target=/usr/local/cargo/git/db \
    --mount=type=cache,target=/usr/local/cargo/registry/ \
    cargo build --locked --release && \
    cp ./target/release/$APP_NAME /bin/server

################################################################################
# Create a new stage for running the application that contains the minimal
# We use dhi.io/static for the final stage because it’s a minimal Docker Hardened Image runtime (basically “just # enough OS to run the binary”), which helps keep the image small and with a lower attack surface compared to a # # full Alpine/Debian runtime.
################################################################################

FROM dhi.io/static:20250419 AS final

# Copy the executable from the "build" stage.
COPY --from=build /bin/server /bin/

# Configure rocket to listen on all interfaces.
ENV ROCKET_ADDRESS=0.0.0.0

# Expose the port that the application listens on.
EXPOSE 8000

# What the container should run when it is started.
CMD ["/bin/server"]
```

Dockerfile

```dockerfile
# Pin the Rust toolchain version used in the build stage.
ARG RUST_VERSION=1.92

# Name of the compiled binary produced by Cargo (must match Cargo.toml package name).
ARG APP_NAME=docker-rust-hello

################################################################################
# Build stage (DOI Rust image)
# This stage compiles the application.
################################################################################

FROM docker.io/library/rust:${RUST_VERSION}-alpine AS build

# Re-declare args inside the stage if you want to use them here.
ARG APP_NAME

# All build steps happen inside /app.
WORKDIR /app

# Install build dependencies needed to compile Rust crates on Alpine
RUN apk add --no-cache clang lld musl-dev git

# Build the application 
RUN --mount=type=bind,source=src,target=src \
    --mount=type=bind,source=Cargo.toml,target=Cargo.toml \
    --mount=type=bind,source=Cargo.lock,target=Cargo.lock \
    --mount=type=cache,target=/app/target/ \
    --mount=type=cache,target=/usr/local/cargo/git/db \
    --mount=type=cache,target=/usr/local/cargo/registry/ \
    cargo build --locked --release && \
    cp ./target/release/$APP_NAME /bin/server

################################################################################
# Runtime stage (DOI Alpine image)
# This stage runs the already-compiled binary with minimal dependencies.
################################################################################

FROM docker.io/library/alpine:3.18 AS final

# Create a non-privileged user (recommended best practice)
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser

# Drop privileges for runtime.
USER appuser

# Copy only the compiled binary from the build stage.
COPY --from=build /bin/server /bin/

# Rocket: listen on all interfaces inside the container.
ENV ROCKET_ADDRESS=0.0.0.0

# Document the port your app listens on.
EXPOSE 8000

# Start the application.
CMD ["/bin/server"]
```

For building an image, only the Dockerfile is necessary. Open the Dockerfile in your favorite IDE or text editor and see what it contains. To learn more about Dockerfiles, see the [Dockerfile reference](https://docs.docker.com/reference/dockerfile/).

## [.dockerignore file](#dockerignore-file)

The [`.dockerignore`](https://docs.docker.com/reference/dockerfile/#dockerignore-file) file specifies patterns and paths that you don't want copied into the image in order to keep the image as small as possible. Open up the `.dockerignore` file in your favorite IDE or text editor to review its contents.

## [Build an image](#build-an-image)

Now that you’ve created the Dockerfile, you can build the image. To do this, use the `docker build` command. The `docker build` command builds Docker images from a Dockerfile and a context. A build's context is the set of files located in the specified PATH or URL. The Docker build process can access any of the files located in this context.

The build command optionally takes a `--tag` flag. The tag sets the name of the image and an optional tag in the format `name:tag`. If you don't pass a tag, Docker uses "latest" as its default tag.

Build the Docker image.

```console
$ docker build --tag docker-rust-image-dhi .
```

You should see output like the following.

```console
[+] Building 1.4s (13/13) FINISHED                                                                                                                                 docker:desktop-linux
 => [internal] load build definition from Dockerfile                                                                                                                               0.0s
 => => transferring dockerfile: 1.67kB                                                                                                                                             0.0s
 => [internal] load metadata for dhi.io/static:20250419                                                                                                                            1.1s
 => [internal] load metadata for dhi.io/rust:1.92-alpine3.22-dev                                                                                                                   1.2s
 => [auth] static:pull token for dhi.io                                                                                                                                            0.0s
 => [auth] rust:pull token for dhi.io                                                                                                                                              0.0s
 => [internal] load .dockerignore                                                                                                                                                  0.0s
 => => transferring context: 646B                                                                                                                                                  0.0s
 => [build 1/3] FROM dhi.io/rust:1.92-alpine3.22-dev@sha256:49eb72825a9e15fe48f2c4875a63c7e7f52a5b430bb52b8254b91d132aa5bf38                                                       0.0s
 => => resolve dhi.io/rust:1.92-alpine3.22-dev@sha256:49eb72825a9e15fe48f2c4875a63c7e7f52a5b430bb52b8254b91d132aa5bf38                                                             0.0s
 => [final 1/2] FROM dhi.io/static:20250419@sha256:74fc43fa240887b8159970e434244039aab0c6efaaa9cf044004cdc22aa2a34d                                                                0.0s
 => => resolve dhi.io/static:20250419@sha256:74fc43fa240887b8159970e434244039aab0c6efaaa9cf044004cdc22aa2a34d                                                                      0.0s
 => [internal] load build context                                                                                                                                                  0.0s
 => => transferring context: 117B                                                                                                                                                  0.0s
 => CACHED [build 2/3] WORKDIR /build                                                                                                                                              0.0s
 => CACHED [build 3/3] RUN --mount=type=bind,source=src,target=src     --mount=type=bind,source=Cargo.toml,target=Cargo.toml     --mount=type=bind,source=Cargo.lock,target=Cargo  0.0s
 => CACHED [final 2/2] COPY --from=build /build/target/release/docker-rust-hello /server                                                                                           0.0s
 => exporting to image                                                                                                                                                             0.1s
 => => exporting layers                                                                                                                                                            0.0s
 => => exporting manifest sha256:cc937bbdd712ef6e5445501f77e02ef8455ef64c567598786d46b7b21a4d4fa8                                                                                  0.0s
 => => exporting config sha256:077507b483af4b5e1a928e527e4bb3a4aaf0557e1eea81cd39465f564c187669                                                                                    0.0s
 => => exporting attestation manifest sha256:11b60e7608170493da1fdd88c120e2d2957f2a72a22edbc9cfbdd0dd37d21f89                                                                      0.0s
 => => exporting manifest list sha256:99a1b925a8d6ebf80e376b8a1e50cd806ec42d194479a3375e1cd9d2911b4db9                                                                             0.0s
 => => naming to docker.io/library/docker-rust-image-dhi:latest                                                                                                                    0.0s
 => => unpacking to docker.io/library/docker-rust-image-dhi:latest                                                                                                                 0.0s

View build details: docker-desktop://dashboard/build/desktop-linux/desktop-linux/yczk0ijw8kc5g20e8nbc8r6lj
```

## [View local images](#view-local-images)

To see a list of images you have on your local machine, you have two options. One is to use the Docker CLI and the other is to use [Docker Desktop](https://docs.docker.com/desktop/use-desktop/images/). As you are working in the terminal already, take a look at listing images using the CLI.

To list images, run the `docker images` command.

```console
$ docker images
IMAGE                          ID             DISK USAGE   CONTENT SIZE   EXTRA
docker-rust-image-dhi:latest   99a1b925a8d6       11.6MB         2.45MB    U   
```

You should see at least one image listed, including the image you just built `docker-rust-image-dhi:latest`.

## [Tag images](#tag-images)

As mentioned earlier, an image name is made up of slash-separated name components. Name components may contain lowercase letters, digits, and separators. A separator can include a period, one or two underscores, or one or more dashes. A name component may not start or end with a separator.

An image is made up of a manifest and a list of layers. Don't worry too much about manifests and layers at this point other than a "tag" points to a combination of these artifacts. You can have multiple tags for an image. Create a second tag for the image you built and take a look at its layers.

To create a new tag for the image you built, run the following command.

```console
$ docker tag docker-rust-image-dhi:latest docker-rust-image-dhi:v1.0.0
```

The `docker tag` command creates a new tag for an image. It doesn't create a new image. The tag points to the same image and is just another way to reference the image.

Now, run the `docker images` command to see a list of the local images.

```console
$ docker images
IMAGE                          ID             DISK USAGE   CONTENT SIZE   EXTRA
docker-rust-image-dhi:latest   99a1b925a8d6       11.6MB         2.45MB    U   
docker-rust-image-dhi:v1.0.0   99a1b925a8d6       11.6MB         2.45MB    U  
```

You can see that two images start with `docker-rust-image-dhi`. You know they're the same image because if you take a look at the `IMAGE ID` column, you can see that the values are the same for the two images.

Remove the tag you just created. To do this, use the `rmi` command. The `rmi` command stands for remove image.

```console
$ docker rmi docker-rust-image-dhi:v1.0.0
Untagged: docker-rust-image-dhi:v1.0.0
```

Note that the response from Docker tells you that Docker didn't remove the image, but only "untagged" it. You can check this by running the `docker images` command.

```console
$ docker images
IMAGE                          ID             DISK USAGE   CONTENT SIZE   EXTRA
docker-rust-image-dhi:latest   99a1b925a8d6       11.6MB         2.45MB    U   
```

Docker removed the image tagged with `:v1.0.0`, but the `docker-rust-image-dhi:latest` tag is available on your machine.

## [Summary](#summary)

This section showed how to create a Dockerfile and `.dockerignore` file for a Rust application, build an image, and tag and list images.

Related information:

* [Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
* [.dockerignore file](https://docs.docker.com/reference/dockerfile/#dockerignore-file)
* [docker build CLI reference](/reference/cli/docker/buildx/build/)
* [Docker Hardened Images](/dhi/)

## [Next steps](#next-steps)

In the next section learn how to run your image as a container.

[Run your Rust image as a container »](https://docs.docker.com/guides/rust/run-containers/)

----
url: https://docs.docker.com/guides/testcontainers-java-micronaut-kafka/create-project/
----

# Create the Micronaut project

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Micronaut project from [Micronaut Launch](https://micronaut.io/launch) by selecting the **kafka**, **data-jpa**, **mysql**, **awaitility**, **assertj**, and **testcontainers** features.

Alternatively, clone the [guide repository](https://github.com/testcontainers/tc-guide-testing-micronaut-kafka-listener).

You'll use the [Awaitility](http://www.awaitility.org/) library to assert the expectations of an asynchronous process flow.

The key dependencies in `pom.xml` are:

```xml
<parent>
    <groupId>io.micronaut.platform</groupId>
    <artifactId>micronaut-parent</artifactId>
    <version>4.1.4</version>
</parent>
<dependencies>
    <dependency>
        <groupId>io.micronaut.data</groupId>
        <artifactId>micronaut-data-hibernate-jpa</artifactId>
        <scope>compile</scope>
    </dependency>
    <dependency>
        <groupId>io.micronaut.kafka</groupId>
        <artifactId>micronaut-kafka</artifactId>
        <scope>compile</scope>
    </dependency>
    <dependency>
        <groupId>io.micronaut.serde</groupId>
        <artifactId>micronaut-serde-jackson</artifactId>
        <scope>compile</scope>
    </dependency>
    <dependency>
        <groupId>io.micronaut.sql</groupId>
        <artifactId>micronaut-jdbc-hikari</artifactId>
        <scope>compile</scope>
    </dependency>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.awaitility</groupId>
        <artifactId>awaitility</artifactId>
        <version>4.2.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-kafka</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-mysql</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

The Micronaut parent POM manages the Testcontainers BOM, so you don't need to specify versions for Testcontainers modules individually.

## [Create the JPA entity](#create-the-jpa-entity)

The application listens to a topic called `product-price-changes`. When a message arrives, it extracts the product code and price from the event payload and updates the price for that product in the MySQL database.

Create `Product.java`:

```java
package com.testcontainers.demo;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import java.math.BigDecimal;

@Entity
@Table(name = "products")
public class Product {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String code;

    @Column(nullable = false)
    private String name;

    @Column(nullable = false)
    private BigDecimal price;

    public Product() {}

    public Product(Long id, String code, String name, BigDecimal price) {
        this.id = id;
        this.code = code;
        this.name = name;
        this.price = price;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public BigDecimal getPrice() {
        return price;
    }

    public void setPrice(BigDecimal price) {
        this.price = price;
    }
}
```

## [Create the Micronaut Data JPA repository](#create-the-micronaut-data-jpa-repository)

Create a repository interface for the `Product` entity with a method to find a product by code and a method to update the price for a given product code:

```java
package com.testcontainers.demo;

import io.micronaut.data.annotation.Query;
import io.micronaut.data.annotation.Repository;
import io.micronaut.data.jpa.repository.JpaRepository;
import java.math.BigDecimal;
import java.util.Optional;

@Repository
public interface ProductRepository extends JpaRepository<Product, Long> {

    Optional<Product> findByCode(String code);

    @Query("update Product p set p.price = :price where p.code = :productCode")
    void updateProductPrice(String productCode, BigDecimal price);
}
```

Unlike Spring Data JPA, Micronaut Data uses compile-time annotation processing to implement repository methods, avoiding runtime reflection.

## [Create the event payload](#create-the-event-payload)

Create a record named `ProductPriceChangedEvent` that represents the structure of the event payload received from the Kafka topic:

```java
package com.testcontainers.demo;

import io.micronaut.serde.annotation.Serdeable;
import java.math.BigDecimal;

@Serdeable
public record ProductPriceChangedEvent(String productCode, BigDecimal price) {}
```

The `@Serdeable` annotation tells Micronaut Serialization that this type can be serialized and deserialized.

The sender and receiver agree on the following JSON format:

```json
{
  "productCode": "P100",
  "price": 25.0
}
```

## [Implement the Kafka listener](#implement-the-kafka-listener)

Create `ProductPriceChangedEventHandler.java`, which handles messages from the `product-price-changes` topic and updates the product price in the database:

```java
package com.testcontainers.demo;

import static io.micronaut.configuration.kafka.annotation.OffsetReset.EARLIEST;

import io.micronaut.configuration.kafka.annotation.KafkaListener;
import io.micronaut.configuration.kafka.annotation.Topic;
import jakarta.inject.Singleton;
import jakarta.transaction.Transactional;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

@Singleton
@Transactional
class ProductPriceChangedEventHandler {

    private static final Logger LOG = LoggerFactory.getLogger(ProductPriceChangedEventHandler.class);

    private final ProductRepository productRepository;

    ProductPriceChangedEventHandler(ProductRepository productRepository) {
        this.productRepository = productRepository;
    }

    @Topic("product-price-changes")
    @KafkaListener(offsetReset = EARLIEST, groupId = "demo")
    public void handle(ProductPriceChangedEvent event) {
        LOG.info("Received a ProductPriceChangedEvent with productCode:{}: ", event.productCode());
        productRepository.updateProductPrice(event.productCode(), event.price());
    }
}
```

Key details:

* The `@KafkaListener` annotation marks this class as a Kafka message listener. Setting `offsetReset` to `EARLIEST` makes the listener start consuming messages from the beginning of the partition, which is useful during testing.
* The `@Topic` annotation specifies which topic to subscribe to.
* Micronaut handles JSON deserialization of the `ProductPriceChangedEvent` automatically using Micronaut Serialization.

## [Configure the datasource](#configure-the-datasource)

Add the following properties to `src/main/resources/application.properties`:

```properties
micronaut.application.name=tc-guide-testing-micronaut-kafka-listener
datasources.default.db-type=mysql
datasources.default.dialect=MYSQL
jpa.default.properties.hibernate.hbm2ddl.auto=update
jpa.default.entity-scan.packages=com.testcontainers.demo
datasources.default.driver-class-name=com.mysql.cj.jdbc.Driver
```

Hibernate's `hbm2ddl.auto=update` creates and updates the database schema automatically. For testing, you'll override this to `create-drop` in the test properties file.

Create `src/test/resources/application-test.properties`:

```properties
jpa.default.properties.hibernate.hbm2ddl.auto=create-drop
```

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-java-micronaut-kafka/write-tests/)

----
url: https://docs.docker.com/docker-hub/repos/manage/information/
----

# Repository information

***

Table of contents

***

Each repository can include a description, an overview, and categories to help users understand its purpose and usage. Adding clear repository information ensures that others can find your images and use them effectively.

You can only modify the repository information of repositories that aren't archived. If a repository is archived, you must unarchive it to modify the information. For more details, see [Unarchive a repository](https://docs.docker.com/docker-hub/repos/archive/#unarchive-a-repository).

## [Repository description](#repository-description)

The description appears in search results when using the `docker search` command and in the search results on Docker Hub.

Consider the following repository description best practices.

* Summarize the purpose. Clearly state what the image does in a concise and specific manner. Make it clear if it's for a particular application, tool, or platform, or has a distinct use case.
* Highlight key features or benefits. Briefly mention the primary benefits or unique features that differentiate the image. Examples include high performance, ease of use, lightweight build, or compatibility with specific frameworks or operating systems.
* Include relevant keywords. Use keywords that users may search for to increase visibility, such as technology stacks, use cases, or environments.
* Keep it concise. The description can be a maximum of 100 characters. Aim to stay within one or two sentences for the description to ensure it's easy to read in search results. Users should quickly understand the image's value.
* Focus on the audience. Consider your target audience (developers, system administrators, etc.) and write the description to address their needs directly.

Following these practices can help make the description more engaging and effective in search results, driving more relevant traffic to your repository.

### [Add or update a repository description](#add-or-update-a-repository-description)

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the pencil icon under the description field.

5. Specify a description.

   The description can be up to 100 characters long.

6. Select **Update**.

## [Repository overview](#repository-overview)

An overview describes what your image does and how to run it. It displays in the public view of your repository when the repository has at least one image. If automated builds are enabled, the overview will be synced from the source code repository's `README.md` file on each successful build.

Consider the following repository overview best practices.

* Describe what the image is, the features it offers, and why it should be used. Can include examples of usage or the team behind the project.
* Explain how to get started with running a container using the image. You can include a minimal example of how to use the image in a Dockerfile.
* List the key image variants and tags to use them, as well as use cases for the variants.
* Link to documentation or support sites, communities, or mailing lists for additional resources.
* Provide contact information for the image maintainers.
* Include the license for the image and where to find more details if needed.

### [Add or update a repository overview](#add-or-update-a-repository-overview)

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Under **Repository overview**, select **Edit** or **Add overview**.

   The **Write** and **Preview** tabs appear.

5. Under **Write**, specify your repository overview.

   You can use basic Markdown and use the **Preview** tab to preview the formatting.

6. Select **Update**.

## [Repository categories](#repository-categories)

You can tag Docker Hub repositories with categories, representing the primary intended use cases for your images. This lets users more easily find and explore content for the problem domain that they're interested in.

### [Available categories](#available-categories)

The Docker Hub content team maintains a curated list of categories.

### [Auto-generated categories](#auto-generated-categories)

> Note
>
> Auto-generated categories only apply to Docker Verified Publishers and Docker-Sponsored Open Source program participants.

For repositories that pre-date the Categories feature in Docker Hub, categories have been automatically generated and applied, using OpenAI, based on the repository title and description.

As an owner of a repository that has been auto-categorized, you can manually edit the categories if you think they're inaccurate. See [Manage categories for a repository](#manage-categories-for-a-repository).

The auto-generated categorization was a one-time effort to help seed categories onto repositories created before the feature existed. Categories are not assigned to new repositories automatically.

### [Manage categories for a repository](#manage-categories-for-a-repository)

You can tag a repository with up to three categories.

To edit the categories of a repository:

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the pencil icon under the description field.

5. Select the categories you want to apply.

6. Select **Update**.

If you're missing a category, use the [Give feedback link](https://docker.qualtrics.com/jfe/form/SV_03CrMyAkCWVylKu) to let us know what categories you'd like to see.

----
url: https://docs.docker.com/scout/explore/exceptions/
----

# Manage vulnerability exceptions

***

Table of contents

***

Vulnerabilities found in container images sometimes need additional context. Just because an image contains a vulnerable package, it doesn't mean that the vulnerability is exploitable. **Exceptions** in Docker Scout lets you acknowledge accepted risks or address false positives in image analysis.

By negating non-applicable vulnerabilities, you can make it easier for yourself and downstream consumers of your images to understand the security implications of a vulnerability in the context of an image.

In Docker Scout, exceptions are automatically factored into the results. If an image contains an exception that flags a CVE as non-applicable, then that CVE is excluded from analysis results.

## [Create exceptions](#create-exceptions)

To create an exception for an image, you can:

* Create an exception in the [GUI](https://docs.docker.com/scout/how-tos/create-exceptions-gui/) of Docker Scout Dashboard or Docker Desktop.
* Create a [VEX](https://docs.docker.com/scout/how-tos/create-exceptions-vex/) document and attach it to the image.

The recommended way to create exceptions is to use Docker Scout Dashboard or Docker Desktop. The GUI provides a user-friendly interface for creating exceptions. It also lets you create exceptions for multiple images, or your entire organization, all at once.

## [View exceptions](#view-exceptions)

To view exceptions for images, you need to have the appropriate permissions.

* Exceptions created [using the GUI](https://docs.docker.com/scout/how-tos/create-exceptions-gui/) are visible to members of your Docker organization. Unauthenticated users or users who aren't members of your organization cannot see these exceptions.
* Exceptions created [using VEX documents](https://docs.docker.com/scout/how-tos/create-exceptions-vex/) are visible to anyone who can pull the image, since the VEX document is stored in the image manifest or on filesystem of the image.

### [View exceptions in Docker Scout Dashboard or Docker Desktop](#view-exceptions-in-docker-scout-dashboard-or-docker-desktop)

The [**Exceptions** tab](https://scout.docker.com/reports/vulnerabilities/exceptions) of the Vulnerabilities page in Docker Scout Dashboard lists all exceptions for for all images in your organization. From here, you can see more details about each exception, the CVEs being suppressed, the images that exceptions apply to, the type of exception and how it was created, and more.

For exceptions created using the [GUI](https://docs.docker.com/scout/how-tos/create-exceptions-gui/), selecting the action menu lets you edit or remove the exception.

To view all exceptions for a specific image tag:

1. Go to the [Images page](https://scout.docker.com/reports/images).
2. Select the tag that you want to inspect.
3. Open the **Exceptions** tab.

1) Open the **Images** view in Docker Desktop.
2) Open the **Hub** tab.
3) Select the tag you want to inspect.
4) Open the **Exceptions** tab.

### [View exceptions in the CLI](#view-exceptions-in-the-cli)

Availability: Experimental

Requires: Docker Scout CLI [1.15.0](https://docs.docker.com/scout/release-notes/cli/#1150) and later

Vulnerability exceptions are highlighted in the CLI when you run `docker scout cves <image>`. If a CVE is suppressed by an exception, a `SUPPRESSED` label appears next to the CVE ID. Details about the exception are also displayed.

> Important
>
> In order to view exceptions in the CLI, you must configure the CLI to use the same Docker organization that you used to create the exceptions.
>
> To configure an organization for the CLI, run:
>
> ```console
> $ docker scout configure organization <organization>
> ```
>
> Replace `<organization>` with the name of your Docker organization.
>
> You can also set the organization on a per-command basis by using the `--org` flag:
>
> ```console
> $ docker scout cves --org <organization> <image>
> ```

To exclude suppressed CVEs from the output, use the `--ignore-suppressed` flag:

```console
$ docker scout cves --ignore-suppressed <image>
```

----
url: https://docs.docker.com/reference/build-checks/expose-invalid-format/
----

# ExposeInvalidFormat

***

Table of contents

***

## [Output](#output)

```text
EXPOSE instruction should not define an IP address or host-port mapping, found '127.0.0.1:80:80'
```

## [Description](#description)

The [`EXPOSE`](https://docs.docker.com/reference/dockerfile/#expose) instruction in a Dockerfile is used to indicate which ports the container listens on at runtime. It should not include an IP address or host-port mapping, as this is not the intended use of the `EXPOSE` instruction. Instead, it should only specify the port number and optionally the protocol (TCP or UDP).

> Important
>
> This will become an error in a future release.

## [Examples](#examples)

❌ Bad: IP address and host-port mapping used.

```dockerfile
FROM alpine
EXPOSE 127.0.0.1:80:80
```

✅ Good: only the port number is specified.

```dockerfile
FROM alpine
EXPOSE 80
```

❌ Bad: Host-port mapping used.

```dockerfile
FROM alpine
EXPOSE 80:80
```

✅ Good: only the port number is specified.

```dockerfile
FROM alpine
EXPOSE 80
```

----
url: https://docs.docker.com/compose/how-tos/dependent-images/
----

# Build dependent images

***

Table of contents

***

Requires: Docker Compose [2.22.0](https://github.com/docker/compose/releases/tag/v2.22.0) and later

To reduce push/pull time and image weight, a common practice for Compose applications is to have services share base layers as much as possible. You typically select the same operating system base image for all services. But you can also get one step further by sharing image layers when your images share the same system packages. The challenge to address is then to avoid repeating the exact same Dockerfile instruction in all services.

For illustration, this page assumes you want all your services to be built with an `alpine` base image and install the system package `openssl`.

## [Multi-stage Dockerfile](#multi-stage-dockerfile)

The recommended approach is to group the shared declaration in a single Dockerfile, and use multi-stage features so that service images are built from this shared declaration.

Dockerfile:

```dockerfile
FROM alpine as base
RUN /bin/sh -c apk add --update --no-cache openssl

FROM base as service_a
# build service a
...

FROM base as service_b
# build service b
...
```

Compose file:

```yaml
services:
  a:
     build:
       target: service_a
  b:
     build:
       target: service_b
```

## [Use another service's image as the base image](#use-another-services-image-as-the-base-image)

A popular pattern is to reuse a service image as a base image in another service. As Compose does not parse the Dockerfile, it can't automatically detect this dependency between services to correctly order the build execution.

a.Dockerfile:

```dockerfile
FROM alpine
RUN /bin/sh -c apk add --update --no-cache openssl
```

b.Dockerfile:

```dockerfile
FROM service_a
# build service b
```

Compose file:

```yaml
services:
  a:
     image: service_a 
     build:
       dockerfile: a.Dockerfile
  b:
     image: service_b
     build:
       dockerfile: b.Dockerfile
```

Legacy Docker Compose v1 used to build images sequentially, which made this pattern usable out of the box. Compose v2 uses BuildKit to optimise builds and build images in parallel and requires an explicit declaration.

The recommended approach is to declare the dependent base image as an additional build context:

Compose file:

```yaml
services:
  a:
     image: service_a
     build: 
       dockerfile: a.Dockerfile
  b:
     image: service_b
     build:
       dockerfile: b.Dockerfile
       additional_contexts:
         # `FROM service_a` will be resolved as a dependency on service "a" which has to be built first
         service_a: "service:a"
```

With the `additional_contexts` attribute, you can refer to an image built by another service without needing to explicitly name it:

b.Dockerfile:

```dockerfile

FROM base_image  
# `base_image` doesn't resolve to an actual image. This is used to point to a named additional context

# build service b
```

Compose file:

```yaml
services:
  a:
     build: 
       dockerfile: a.Dockerfile
       # built image will be tagged <project_name>_a
  b:
     build:
       dockerfile: b.Dockerfile
       additional_contexts:
         # `FROM base_image` will be resolved as a dependency on service "a" which has to be built first
         base_image: "service:a"
```

## [Build with Bake](#build-with-bake)

Using [Bake](https://docs.docker.com/build/bake/) let you pass the complete build definition for all services and to orchestrate build execution in the most efficient way.

To enable this feature, run Compose with the `COMPOSE_BAKE=true` variable set in your environment.

```console
$ COMPOSE_BAKE=true docker compose build
[+] Building 0.0s (0/1)                                                         
 => [internal] load local bake definitions                                 0.0s
...
[+] Building 2/2 manifest list sha256:4bd2e88a262a02ddef525c381a5bdb08c83  0.0s
 ✔ service_b  Built                                                        0.7s 
 ✔ service_a  Built    
```

Bake can also be selected as the default builder by editing your `$HOME/.docker/config.json` config file:

```json
{
  ...
  "plugins": {
    "compose": {
      "build": "bake"
    }
  }
  ...
}
```

## [Additional resources](#additional-resources)

* [Docker Compose build reference](/reference/cli/docker/compose/build/)
* [Learn about multi-stage Dockerfiles](https://docs.docker.com/build/building/multi-stage/)

----
url: https://docs.docker.com/reference/build-checks/no-empty-continuation/
----

# NoEmptyContinuation

***

Table of contents

***

## [Output](#output)

```text
Empty continuation line found in: RUN apk add     gnupg     curl
```

## [Description](#description)

Support for empty continuation (`/`) lines have been deprecated and will generate errors in future versions of the Dockerfile syntax.

Empty continuation lines are empty lines following a newline escape:

```dockerfile
FROM alpine
RUN apk add \

    gnupg \

    curl
```

Support for such empty lines is deprecated, and a future BuildKit release will remove support for this syntax entirely, causing builds to break. To avoid future errors, remove the empty lines, or add comments, since lines with comments aren't considered empty.

## [Examples](#examples)

❌ Bad: empty continuation line between `EXPOSE` and 80.

```dockerfile
FROM alpine
EXPOSE \

80
```

✅ Good: comments do not count as empty lines.

```dockerfile
FROM alpine
EXPOSE \
# Port
80
```

----
url: https://docs.docker.com/extensions/extensions-sdk/extensions/
----

# Part two: Publish

***

Table of contents

***

This section describes how to make your extension available and more visible, so users can discover it and install it with a single click.

## [Release your extension](#release-your-extension)

After you have developed your extension and tested it locally, you are ready to release the extension and make it available for others to install and use (either internally with your team, or more publicly).

Releasing your extension consists of:

* Providing information about your extension: description, screenshots, etc. so users can decide to install your extension
* [Validating](https://docs.docker.com/extensions/extensions-sdk/extensions/validate/) that the extension is built in the right format and includes the required information
* Making the extension image available on [Docker Hub](https://hub.docker.com/)

See [Package and release your extension](https://docs.docker.com/extensions/extensions-sdk/extensions/DISTRIBUTION/) for more details about the release process.

## [Promote your extension](#promote-your-extension)

Once your extension is available on Docker Hub, users who have access to the extension image can install it using the Docker CLI.

### [Use a share extension link](#use-a-share-extension-link)

You can also [generate a share URL](https://docs.docker.com/extensions/extensions-sdk/extensions/share/) in order to share your extension within your team, or promote your extension on the internet. The share link lets users view the extension description and screenshots.

### [Publish your extension in the Marketplace](#publish-your-extension-in-the-marketplace)

You can publish your extension in the Extensions Marketplace to make it more discoverable. You must [submit your extension](https://docs.docker.com/extensions/extensions-sdk/extensions/publish/) if you want to have it published in the Marketplace.

## [What happens next](#what-happens-next)

### [New releases](#new-releases)

Once you have released your extension, you can push a new release just by pushing a new version of the extension image, with an incremented tag (still using `semver` conventions). Extensions published in the Marketplace benefit from update notifications to all Desktop users that have installed the extension. For more details, see [new releases and updates](https://docs.docker.com/extensions/extensions-sdk/extensions/DISTRIBUTION/#new-releases-and-updates).

### [Extension support and user feedback](#extension-support-and-user-feedback)

In addition to providing a description of your extension's features and screenshots, you should also specify additional URLs using [extension labels](https://docs.docker.com/extensions/extensions-sdk/extensions/labels/). This direct users to your website for reporting bugs and feedback, and accessing documentation and support.

> Already built an extension?
>
> Let us know about your experience using the [feedback form](https://survey.alchemer.com/s3/7184948/Publishers-Feedback-Form).

----
url: https://docs.docker.com/guides/reactjs/deploy/
----

# Test your React.js deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

Before you begin, make sure you’ve completed the following:

* Complete all the previous sections of this guide, starting with [Containerize React.js application](https://docs.docker.com/guides/reactjs/containerize/).
* [Enable Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

> **New to Kubernetes?**\
> Visit the [Kubernetes basics tutorial](https://kubernetes.io/docs/tutorials/kubernetes-basics/) to get familiar with how clusters, pods, deployments, and services work.

***

## [Overview](#overview)

This section guides you through deploying your containerized React.js application locally using [Docker Desktop’s built-in Kubernetes](/desktop/kubernetes/). Running your app in a local Kubernetes cluster allows you to closely simulate a real production environment, enabling you to test, validate, and debug your workloads with confidence before promoting them to staging or production.

***

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

Follow these steps to define your deployment configuration:

1. In the root of your project, create a new file named: reactjs-sample-kubernetes.yaml

2. Open the file in your IDE or preferred text editor.

3. Add the following configuration, and be sure to replace `{DOCKER_USERNAME}` and `{DOCKERHUB_PROJECT_NAME}` with your actual Docker Hub username and repository name from the previous [Automate your builds with GitHub Actions](https://docs.docker.com/guides/reactjs/configure-github-actions/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: reactjs-sample
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: reactjs-sample
  template:
    metadata:
      labels:
        app: reactjs-sample
    spec:
      containers:
        - name: reactjs-container
          image: {DOCKER_USERNAME}/{DOCKERHUB_PROJECT_NAME}:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name:  reactjs-sample-service
  namespace: default
spec:
  type: NodePort
  selector:
    app:  reactjs-sample
  ports:
    - port: 8080
      targetPort: 8080
      nodePort: 30001
```

This manifest defines two key Kubernetes resources, separated by `---`:

* Deployment Deploys a single replica of your React.js application inside a pod. The pod uses the Docker image built and pushed by your GitHub Actions CI/CD workflow\
  (refer to [Automate your builds with GitHub Actions](https://docs.docker.com/guides/reactjs/configure-github-actions/)).\
  The container listens on port `8080`, which is typically used by [Nginx](https://nginx.org/en/docs/) to serve your production React app.

* Service (NodePort) Exposes the deployed pod to your local machine.\
  It forwards traffic from port `30001` on your host to port `8080` inside the container.\
  This lets you access the application in your browser at <http://localhost:30001>.

> Note
>
> To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

***

## [Deploy and check your application](#deploy-and-check-your-application)

Follow these steps to deploy your containerized React.js app into a local Kubernetes cluster and verify that it’s running correctly.

### [Step 1. Apply the Kubernetes configuration](#step-1-apply-the-kubernetes-configuration)

In your terminal, navigate to the directory where your `reactjs-sample-kubernetes.yaml` file is located, then deploy the resources using:

```console
  $ kubectl apply -f reactjs-sample-kubernetes.yaml
```

If everything is configured properly, you’ll see confirmation that both the Deployment and the Service were created:

```shell
  deployment.apps/reactjs-sample created
  service/reactjs-sample-service created
```

This output means that both the Deployment and the Service were successfully created and are now running inside your local cluster.

### [Step 2. Check the deployment status](#step-2-check-the-deployment-status)

Run the following command to check the status of your deployment:

```console
  $ kubectl get deployments
```

You should see an output similar to:

```shell
  NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
  reactjs-sample       1/1     1            1           14s
```

This confirms that your pod is up and running with one replica available.

### [Step 3. Verify the service exposure](#step-3-verify-the-service-exposure)

Check if the NodePort service is exposing your app to your local machine:

```console
$ kubectl get services
```

You should see something like:

```shell
NAME                     TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
reactjs-sample-service   NodePort    10.100.244.65    <none>        8080:30001/TCP   1m
```

This output confirms that your app is available via NodePort on port 30001.

### [Step 4. Access your app in the browser](#step-4-access-your-app-in-the-browser)

Open your browser and navigate to <http://localhost:30001>.

You should see your production-ready React.js Sample application running — served by your local Kubernetes cluster.

### [Step 5. Clean up Kubernetes resources](#step-5-clean-up-kubernetes-resources)

Once you're done testing, you can delete the deployment and service using:

```console
  $ kubectl delete -f reactjs-sample-kubernetes.yaml
```

Expected output:

```shell
  deployment.apps "reactjs-sample" deleted
  service "reactjs-sample-service" deleted
```

This ensures your cluster stays clean and ready for the next deployment.

***

## [Summary](#summary)

In this section, you learned how to deploy your React.js application to a local Kubernetes cluster using Docker Desktop. This setup allows you to test and debug your containerized app in a production-like environment before deploying it to the cloud.

What you accomplished:

* Created a Kubernetes Deployment and NodePort Service for your React.js app
* Used `kubectl apply` to deploy the application locally
* Verified the app was running and accessible at `http://localhost:30001`
* Cleaned up your Kubernetes resources after testing

***

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/import/
----

# docker mcp profile import

***

| Description | Import profile from file                 |
| ----------- | ---------------------------------------- |
| Usage       | `docker mcp profile import <input-file>` |

## [Description](#description)

Import profile from file

----
url: https://docs.docker.com/reference/cli/sbx/completion/
----

# sbx completion

| Description | Generate the autocompletion script for the specified shell |
| ----------- | ---------------------------------------------------------- |

## [Description](#description)

Generate the autocompletion script for sbx for the specified shell. See each sub-command's help for details on how to use the generated script.

## [Commands](#commands)

| Command                                                                                         | Description                                       |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| [`sbx completion bash`](https://docs.docker.com/reference/cli/sbx/completion/bash/)             | Generate the autocompletion script for bash       |
| [`sbx completion fish`](https://docs.docker.com/reference/cli/sbx/completion/fish/)             | Generate the autocompletion script for fish       |
| [`sbx completion powershell`](https://docs.docker.com/reference/cli/sbx/completion/powershell/) | Generate the autocompletion script for powershell |
| [`sbx completion zsh`](https://docs.docker.com/reference/cli/sbx/completion/zsh/)               | Generate the autocompletion script for zsh        |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/guides/testcontainers-java-lifecycle/lifecycle-callbacks/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# JUnit 5 lifecycle callbacks

***

***

When testing with Testcontainers, you want to start the required containers before executing any tests and remove them afterwards. You can use JUnit 5 `@BeforeAll` and `@AfterAll` lifecycle callback methods for this:

```java
package com.testcontainers.demo;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.List;
import java.util.Optional;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.testcontainers.postgresql.PostgreSQLContainer;

class CustomerServiceWithLifeCycleCallbacksTest {

  static PostgreSQLContainer postgres = new PostgreSQLContainer(
    "postgres:16-alpine"
  );

  CustomerService customerService;

  @BeforeAll
  static void startContainers() {
    postgres.start();
  }

  @AfterAll
  static void stopContainers() {
    postgres.stop();
  }

  @BeforeEach
  void setUp() {
    customerService =
    new CustomerService(
      postgres.getJdbcUrl(),
      postgres.getUsername(),
      postgres.getPassword()
    );
    customerService.deleteAllCustomers();
  }

  @Test
  void shouldCreateCustomer() {
    customerService.createCustomer(new Customer(1L, "George"));

    Optional<Customer> customer = customerService.getCustomer(1L);
    assertTrue(customer.isPresent());
    assertEquals(1L, customer.get().id());
    assertEquals("George", customer.get().name());
  }

  @Test
  void shouldGetCustomers() {
    customerService.createCustomer(new Customer(1L, "George"));
    customerService.createCustomer(new Customer(2L, "John"));

    List<Customer> customers = customerService.getAllCustomers();
    assertEquals(2, customers.size());
  }
}
```

Here's what the code does:

* `PostgreSQLContainer` is declared as a **static field**. The container starts before all tests and stops after all tests in this class.
* `@BeforeAll` starts the container, `@AfterAll` stops it.
* `@BeforeEach` initializes `CustomerService` with the container's JDBC parameters and deletes all rows to give each test a clean database.

Key observations:

* Because the container is a **static field**, it's shared across all test methods in the class. You can declare it as a non-static field and use `@BeforeEach`/`@AfterEach` to start a new container per test, but this isn't recommended as it's resource-intensive.
* Even without explicitly stopping the container in `@AfterAll`, Testcontainers uses the [Ryuk container](https://github.com/testcontainers/moby-ryuk) to clean up containers automatically when the JVM exits.

[JUnit 5 extension annotations »](https://docs.docker.com/guides/testcontainers-java-lifecycle/extension-annotations/)

----
url: https://docs.docker.com/reference/cli/docker/compose/top/
----

# docker compose top

***

| Description | Display the running processes      |
| ----------- | ---------------------------------- |
| Usage       | `docker compose top [SERVICES...]` |

## [Description](#description)

Displays the running processes

## [Examples](#examples)

```console
$ docker compose top
example_foo_1
UID    PID      PPID     C    STIME   TTY   TIME       CMD
root   142353   142331   2    15:33   ?     00:00:00   ping localhost -c 5
```

----
url: https://docs.docker.com/reference/cli/docker/container/commit/
----

# docker container commit

***

| Description                                                               | Create a new image from a container's changes                    |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Usage                                                                     | `docker container commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker commit`                                                  |

## [Description](#description)

It can be useful to commit a container's file changes or settings into a new image. This lets you debug a container by running an interactive shell, or export a working dataset to another server.

Commits do not include any data contained in mounted volumes.

By default, the container being committed and its processes will be paused while the image is committed. This reduces the likelihood of encountering data corruption during the process of creating the commit. If this behavior is undesired, set the `--pause` option to false.

The `--change` option will apply `Dockerfile` instructions to the image that's created. Supported `Dockerfile` instructions: `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`LABEL`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR`

## [Options](#options)

| Option                    | Default | Description                                                |
| ------------------------- | ------- | ---------------------------------------------------------- |
| `-a, --author`            |         | Author (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| [`-c, --change`](#change) |         | Apply Dockerfile instruction to the created image          |
| `-m, --message`           |         | Commit message                                             |
| `--no-pause`              |         | Disable pausing container during commit                    |

## [Examples](#examples)

### [Commit a container](#commit-a-container)

```console
$ docker ps

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
c3f279d17e0a        ubuntu:24.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
197387f1b436        ubuntu:24.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton

$ docker commit c3f279d17e0a  svendowideit/testimage:version3

f5283438590d

$ docker images

REPOSITORY                        TAG                 ID                  CREATED             SIZE
svendowideit/testimage            version3            f5283438590d        16 seconds ago      335.7 MB
```

### [Commit a container with new configurations (--change)](#change)

```console
$ docker ps

CONTAINER ID       IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
c3f279d17e0a       ubuntu:24.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
197387f1b436       ubuntu:24.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton

$ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a

[HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin]

$ docker commit --change "ENV DEBUG=true" c3f279d17e0a  svendowideit/testimage:version3

f5283438590d

$ docker inspect -f "{{ .Config.Env }}" f5283438590d

[HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true]
```

### [Commit a container with new `CMD` and `EXPOSE` instructions](#commit-a-container-with-new-cmd-and-expose-instructions)

```console
$ docker ps

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS              NAMES
c3f279d17e0a        ubuntu:24.04        /bin/bash           7 days ago          Up 25 hours                            desperate_dubinsky
197387f1b436        ubuntu:24.04        /bin/bash           7 days ago          Up 25 hours                            focused_hamilton

$ docker commit --change='CMD ["apachectl", "-DFOREGROUND"]' -c "EXPOSE 80" c3f279d17e0a  svendowideit/testimage:version4

f5283438590d

$ docker run -d svendowideit/testimage:version4

89373736e2e7f00bc149bd783073ac43d0507da250e999f3f1036e0db60817c0

$ docker ps

CONTAINER ID        IMAGE               COMMAND                 CREATED             STATUS              PORTS              NAMES
89373736e2e7        testimage:version4  "apachectl -DFOREGROU"  3 seconds ago       Up 2 seconds        80/tcp             distracted_fermat
c3f279d17e0a        ubuntu:24.04        /bin/bash               7 days ago          Up 25 hours                            desperate_dubinsky
197387f1b436        ubuntu:24.04        /bin/bash               7 days ago          Up 25 hours                            focused_hamilton
```

----
url: https://docs.docker.com/admin/
----

# Administration

***

Table of contents

***

Administrators can manage companies and organizations using the [Docker Admin Console](https://app.docker.com/admin). The Admin Console provides centralized observability, access management, and security controls across Docker environments.

## [Company and organization hierarchy](#company-and-organization-hierarchy)

The [Docker Admin Console](https://app.docker.com/admin) provides administrators with centralized observability, access management, and controls for their company and organizations. To provide these features, Docker uses the following hierarchy and roles.

### [Company](#company)

A company groups multiple Docker organizations for centralized configuration. Companies have the company owner administrator role available.

The company owner:

* Can view and manage all organizations within the company
* Has full access to company-wide settings and inherits the same permissions as organization owners
* Does not occupy a seat

Companies are only available for Docker Business subscribers.

### [Organization](#organization)

Organization owners have the organization owner administrator role available. They can manage organization settings, users, and access controls, but occupy a [seat](https://docs.docker.com/admin/organization/organization-faqs/#what-is-the-difference-between-user-invitee-seat-and-member).

* An organization contains teams and repositories.
* All Docker Team and Business subscribers must have at least one organization.

> Tip
>
> [Upgrading to a Docker Business plan](https://www.docker.com/pricing?ref=Docs\&refAction=DocsAdmin) grants you the company owner role so you can manage multiple organizations.

### [Team](#team)

Teams are optional and let you group members to assign repository permissions collectively. Teams simplify permission management across projects or functions.

### [Member](#member)

A member is any Docker user added to an organization. Organization and company owners can assign roles to members to define their level of access.

## [Admin Console features](#admin-console-features)

Docker's [Admin Console](https://app.docker.com/admin) allows you to:

* Create and manage companies and organizations
* Assign roles and permissions to members
* Group members into teams to manage access by project or role
* Set company-wide policies, including SCIM provisioning and security enforcement

## [Manage companies and organizations](#manage-companies-and-organizations)

Learn how to manage companies and organizations in the following sections.

### [Company administration](/admin/company/)

[Explore how to manage a company.](/admin/company/)

### [Organization administration](/admin/organization/)

[Learn about organization administration.](/admin/organization/)

### [Onboard your organization](/admin/organization/setup/onboard)

[Learn how to onboard and secure your organization.](/admin/organization/setup/onboard)

### [Company FAQ](/faq/admin/company-faqs/)

[Discover common questions and answers about companies.](/faq/admin/company-faqs/)

### [Organization FAQ](/faq/admin/organization-faqs/)

[Explore popular FAQ topics about organizations.](/faq/admin/organization-faqs/)

### [Security](/security/)

[Explore security features for administrators.](/security/)

----
url: https://docs.docker.com/engine/daemon/start/
----

# Start the daemon

***

Table of contents

***

This page shows how to start the daemon, either manually or using OS utilities.

## [Start the daemon using operating system utilities](#start-the-daemon-using-operating-system-utilities)

On a typical installation the Docker daemon is started by a system utility, not manually by a user. This makes it easier to automatically start Docker when the machine reboots.

The command to start Docker depends on your operating system. Check the correct page under [Install Docker](https://docs.docker.com/engine/install/).

### [Start with systemd](#start-with-systemd)

On some operating systems, like Ubuntu and Debian, the Docker daemon service starts automatically. Use the following command to start it manually:

```console
$ sudo systemctl start docker
```

If you want Docker to start at boot, see [Configure Docker to start on boot](https://docs.docker.com/engine/install/linux-postinstall/#configure-docker-to-start-on-boot-with-systemd).

## [Start the daemon manually](#start-the-daemon-manually)

If you don't want to use a system utility to manage the Docker daemon, or just want to test things out, you can manually run it using the `dockerd` command. You may need to use `sudo`, depending on your operating system configuration.

When you start Docker this way, it runs in the foreground and sends its logs directly to your terminal.

```console
$ dockerd

INFO[0000] +job init_networkdriver()
INFO[0000] +job serveapi(unix:///var/run/docker.sock)
INFO[0000] Listening for HTTP on unix (/var/run/docker.sock)
```

To stop Docker when you have started it manually, issue a `Ctrl+C` in your terminal.

----
url: https://docs.docker.com/offload/about/
----

# About Docker Offload

***

Table of contents

***

Subscription: Docker Offload

Requires: Docker Desktop 4.68 or later

Docker Offload is a fully managed service for building and running containers in the cloud using the Docker tools you already know, including Docker Desktop, the Docker CLI, and Docker Compose. It extends your local development workflow into a scalable, cloud-powered environment, enabling developers to work efficiently even in virtual desktop infrastructure (VDI) environments or systems that don't support nested virtualization.

## [Key features](#key-features)

Docker Offload includes the following capabilities to support modern container workflows:

* Ephemeral cloud runners: Automatically provision and tear down cloud environments for each container session.
* Secure communication: Use encrypted tunnels between Docker Desktop and cloud environments with support for secure secrets and image pulling.
* Port forwarding and bind mounts: Retain a local development experience even when running containers in the cloud.
* VDI-friendly: [Use Docker Desktop](https://docs.docker.com/desktop/setup/vm-vdi/) in virtual desktop environments or systems that don't support nested virtualization.

For more information, see the [Docker Offload product page](https://www.docker.com/products/docker-offload/).

## [How Docker Offload works](#how-docker-offload-works)

Docker Offload replaces the need to build or run containers locally by connecting Docker Desktop to secure, dedicated cloud resources.

### [Running containers with Docker Offload](#running-containers-with-docker-offload)

When you use Docker Offload to build or run containers, Docker Desktop creates a secure SSH tunnel to a Docker daemon running in the cloud. Your containers are started and managed entirely in that remote environment.

Here's what happens:

1. Docker Desktop connects to the cloud and triggers container creation.
2. Docker Offload builds or pulls the required images and starts containers in the cloud.
3. The connection stays open while the containers run and you remain active.
4. When the containers stop running, the environment shuts down and is cleaned up automatically.

This setup avoids the overhead of running containers locally and enables fast, reliable containers even on low-powered machines, including machines that do not support nested virtualization. This makes Docker Offload ideal for developers using environments such as virtual desktops, cloud-hosted development machines, or older hardware.

Despite running remotely, features like bind mounts and port forwarding continue to work seamlessly, providing a local-like experience from within Docker Desktop and the CLI.

### [Cloud resources](#cloud-resources)

Docker Offload uses cloud hosts with 4 vCPUs and 8 GiB of memory. If you have different requirements, [contact Docker](https://www.docker.com/pricing/contact-sales/) to explore options.

### [Session management and idle state](#session-management-and-idle-state)

Docker Offload uses session management and idle state policies to ensure fair use of cloud resources across all users, see [Fair use](#fair-use).

Each user can run one Docker Offload session at a time. When Docker Desktop is in an **Offload idle** state, it waits for activity on the Docker API and only connects to a cloud environment when needed. Once connected, the session moves to an **Offload running** state and stays connected as long as Docker detects activity. Activity includes any Docker API call, a running container, or an active build.

#### [When you'll see a prompt](#when-youll-see-a-prompt)

While Docker Offload is running, Docker Desktop shows prompts in the Dashboard to check if you're still active. Prompts appear in two cases:

1. No activity is detected for more than 3 minutes.
2. The session has been running for a long time.

When a prompt appears, you can:

* Select **Ask me again later** to confirm you're still active and continue your session.
* Select **Idle now** to return to an idle state immediately.
* Do nothing, and the session returns to an idle state automatically.

#### [What happens when your session goes idle](#what-happens-when-your-session-goes-idle)

After your session returns to an idle state, there is a 5-minute grace period. You can resume the session during this time by running any Docker command.

> Important
>
> If the idle period exceeds 5 minutes without activity, the session is terminated. Docker Offload environments are ephemeral, so the remote environment and any containers, images, or volumes in it are deleted. To keep work between sessions, push images to a registry such as [Docker Hub](/docker-hub/) before your session ends.

#### [Long session prompts](#long-session-prompts)

Long session prompts appear every 3 hours during a session. After 8 hours of cumulative usage in a day, prompts appear every hour. The 8-hour counter resets at the start of each day.

## [Fair use](#fair-use)

Docker Offload enforces a fair use policy to prevent resource abuse. Fair use is defined as up to 8 compute hours per named user per day, totaled across all user sessions. Usage in excess of this threshold may be subject to session management at Docker's discretion.

## [What's next](#whats-next)

Get hands-on with Docker Offload by following the [Docker Offload quickstart](/offload/quickstart/).

----
url: https://docs.docker.com/engine/network/drivers/bridge/
----

# Bridge network driver

***

Table of contents

***

A Docker bridge network has an IPv4 subnet and, optionally, an IPv6 subnet. Each container connected to the bridge network has a network interface with addresses in the network's subnets. By default, it:

* Allows unrestricted network access to containers in the network from the host, and from other containers connected to the same bridge network.
* Blocks access from containers in other networks and from outside the Docker host.
* Uses masquerading to give containers external network access. Devices on the host's external networks only see the IP address of the Docker host.
* Supports port publishing, where network traffic is forwarded between container ports and ports on host IP addresses. The published ports can be accessed from outside the Docker host, on its IP addresses.

In terms of Docker, a bridge network uses a software bridge which lets containers connected to the same bridge network communicate, while providing isolation from containers that aren't connected to that bridge network. By default, the Docker bridge driver automatically installs rules in the host machine so that containers connected to different bridge networks can only communicate with each other using published ports.

Bridge networks apply to containers running on the same Docker daemon host. For communication among containers running on different Docker daemon hosts, you can either manage routing at the OS level, or you can use an [overlay network](https://docs.docker.com/engine/network/drivers/overlay/).

When you start Docker, a [default bridge network](#use-the-default-bridge-network) (also called `bridge`) is created automatically, and newly-started containers connect to it unless otherwise specified. You can also create user-defined custom bridge networks. **User-defined bridge networks are superior to the default `bridge` network.**

## [Differences between user-defined bridges and the default bridge](#differences-between-user-defined-bridges-and-the-default-bridge)

* **User-defined bridges provide automatic DNS resolution between containers**.

  Containers on the default bridge network can only access each other by IP addresses, unless you use the [`--link` option](https://docs.docker.com/engine/network/links/), which is considered legacy. On a user-defined bridge network, containers can resolve each other by name or alias.

  Imagine an application with a web front-end and a database back-end. If you call your containers `web` and `db`, the web container can connect to the db container at `db`, no matter which Docker host the application stack is running on.

  If you run the same application stack on the default bridge network, you need to manually create links between the containers (using the legacy `--link` flag). These links need to be created in both directions, so you can see this gets complex with more than two containers which need to communicate. Alternatively, you can manipulate the `/etc/hosts` files within the containers, but this creates problems that are difficult to debug.

* **User-defined bridges provide better isolation**.

  All containers without a `--network` specified, are attached to the default bridge network. This can be a risk, as unrelated stacks/services/containers are then able to communicate.

  Using a user-defined network provides a scoped network in which only containers attached to that network are able to communicate.

* **Containers can be attached and detached from user-defined networks on the fly**.

  During a container's lifetime, you can connect or disconnect it from user-defined networks on the fly. To remove a container from the default bridge network, you need to stop the container and recreate it with different network options.

* **Each user-defined network creates a configurable bridge**.

  If your containers use the default bridge network, you can configure it, but all the containers use the same settings, such as MTU and `iptables` rules. In addition, configuring the default bridge network happens outside of Docker itself, and requires a restart of Docker.

  User-defined bridge networks are created and configured using `docker network create`. If different groups of applications have different network requirements, you can configure each user-defined bridge separately, as you create it.

* **Linked containers on the default bridge network share environment variables**.

  Originally, the only way to share environment variables between two containers was to link them using the [`--link` flag](https://docs.docker.com/engine/network/links/). This type of variable sharing isn't possible with user-defined networks. However, there are superior ways to share environment variables. A few ideas:

  * Multiple containers can mount a file or directory containing the shared information, using a Docker volume.

  * Multiple containers can be started together using `docker-compose` and the compose file can define the shared variables.

  * You can use swarm services instead of standalone containers, and take advantage of shared [secrets](https://docs.docker.com/engine/swarm/secrets/) and [configs](https://docs.docker.com/engine/swarm/configs/).

Containers connected to the same user-defined bridge network effectively expose all ports to each other. For a port to be accessible to containers or non-Docker hosts on different networks, that port must be *published* using the `-p` or `--publish` flag.

## [Options](#options)

The following table describes the driver-specific options that you can pass to `--opt` when creating a custom network using the `bridge` driver.

| Option                                                                                      | Default                     | Description                                                                                                                              |
| ------------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `com.docker.network.bridge.name`                                                            |                             | Interface name to use when creating the Linux bridge.                                                                                    |
| `com.docker.network.bridge.enable_ip_masquerade`                                            | `true`                      | Enable IP masquerading.                                                                                                                  |
| `com.docker.network.host_ipv4` `com.docker.network.host_ipv6`                               |                             | Address to use for source NAT. See [Packet filtering and firewalls](https://docs.docker.com/engine/network/packet-filtering-firewalls/). |
| `com.docker.network.bridge.gateway_mode_ipv4` `com.docker.network.bridge.gateway_mode_ipv6` | `nat`                       | Control external connectivity. See [Packet filtering and firewalls](https://docs.docker.com/engine/network/packet-filtering-firewalls/). |
| `com.docker.network.bridge.enable_icc`                                                      | `true`                      | Enable or Disable inter-container connectivity.                                                                                          |
| `com.docker.network.bridge.host_binding_ipv4`                                               | all IPv4 and IPv6 addresses | Default IP when binding container ports.                                                                                                 |
| `com.docker.network.driver.mtu`                                                             | `0` (no limit)              | Set the containers network Maximum Transmission Unit (MTU).                                                                              |
| `com.docker.network.container_iface_prefix`                                                 | `eth`                       | Set a custom prefix for container interfaces.                                                                                            |
| `com.docker.network.bridge.inhibit_ipv4`                                                    | `false`                     | Prevent Docker from [assigning an IP address](#skip-bridge-ip-address-configuration) to the bridge.                                      |

Some of these options are also available as flags to the `dockerd` CLI, and you can use them to configure the default `docker0` bridge when starting the Docker daemon. The following table shows which options have equivalent flags in the `dockerd` CLI.

| Option                                           | Flag        |
| ------------------------------------------------ | ----------- |
| `com.docker.network.bridge.name`                 | -           |
| `com.docker.network.bridge.enable_ip_masquerade` | `--ip-masq` |
| `com.docker.network.bridge.enable_icc`           | `--icc`     |
| `com.docker.network.bridge.host_binding_ipv4`    | `--ip`      |
| `com.docker.network.driver.mtu`                  | `--mtu`     |
| `com.docker.network.container_iface_prefix`      | -           |

The Docker daemon supports a `--bridge` flag, which you can use to define your own `docker0` bridge. Use this option if you want to run multiple daemon instances on the same host. For details, see [Run multiple daemons](https://docs.docker.com/reference/cli/dockerd/#run-multiple-daemons).

### [Default host binding address](#default-host-binding-address)

When no host address is given in port publishing options like `-p 80` or `-p 8080:80`, the default is to make the container's port 80 available on all host addresses, IPv4 and IPv6.

The bridge network driver option `com.docker.network.bridge.host_binding_ipv4` can be used to modify the default address for published ports.

Despite the option's name, it is possible to specify an IPv6 address.

When the default binding address is an address assigned to a specific interface, the container's port will only be accessible via that address.

Setting the default binding address to `::` means published ports will only be available on the host's IPv6 addresses. However, setting it to `0.0.0.0` means it will be available on the host's IPv4 and IPv6 addresses.

To restrict a published port to IPv4 only, the address must be included in the container's publishing options. For example, `-p 0.0.0.0:8080:80`.

## [Manage a user-defined bridge](#manage-a-user-defined-bridge)

Use the `docker network create` command to create a user-defined bridge network.

```console
$ docker network create my-net
```

You can specify the subnet, the IP address range, the gateway, and other options. See the [docker network create](/reference/cli/docker/network/create/#specify-advanced-options) reference or the output of `docker network create --help` for details.

Use the `docker network rm` command to remove a user-defined bridge network. If containers are currently connected to the network, [disconnect them](#disconnect-a-container-from-a-user-defined-bridge) first.

```console
$ docker network rm my-net
```

> **What's really happening?**
>
> When you create or remove a user-defined bridge or connect or disconnect a container from a user-defined bridge, Docker uses tools specific to the operating system to manage the underlying network infrastructure (such as adding or removing bridge devices or configuring `iptables` rules on Linux). These details should be considered implementation details. Let Docker manage your user-defined networks for you.

## [Connect a container to a user-defined bridge](#connect-a-container-to-a-user-defined-bridge)

When you create a new container, you can specify one or more `--network` flags. This example connects an Nginx container to the `my-net` network. It also publishes port 80 in the container to port 8080 on the Docker host, so external clients can access that port. Any other container connected to the `my-net` network has access to all ports on the `my-nginx` container, and vice versa.

```console
$ docker create --name my-nginx \
  --network my-net \
  --publish 8080:80 \
  nginx:latest
```

To connect a **running** container to an existing user-defined bridge, use the `docker network connect` command. The following command connects an already-running `my-nginx` container to an already-existing `my-net` network:

```console
$ docker network connect my-net my-nginx
```

## [Disconnect a container from a user-defined bridge](#disconnect-a-container-from-a-user-defined-bridge)

To disconnect a running container from a user-defined bridge, use the `docker network disconnect` command. The following command disconnects the `my-nginx` container from the `my-net` network.

```console
$ docker network disconnect my-net my-nginx
```

## [Use IPv6 in a user-defined bridge network](#use-ipv6-in-a-user-defined-bridge-network)

When you create your network, you can specify the `--ipv6` flag to enable IPv6.

```console
$ docker network create --ipv6 --subnet 2001:db8:1234::/64 my-net
```

If you do not provide a `--subnet` option, a Unique Local Address (ULA) prefix will be chosen automatically.

## [IPv6-only bridge networks](#ipv6-only-bridge-networks)

To skip IPv4 address configuration on the bridge and in its containers, create the network with option `--ipv4=false`, and enable IPv6 using `--ipv6`.

```console
$ docker network create --ipv6 --ipv4=false v6net
```

IPv4 address configuration cannot be disabled in the default bridge network.

## [Use the default bridge network](#use-the-default-bridge-network)

The default `bridge` network is considered a legacy detail of Docker and is not recommended for production use. Configuring it is a manual operation, and it has [technical shortcomings](#differences-between-user-defined-bridges-and-the-default-bridge).

### [Connect a container to the default bridge network](#connect-a-container-to-the-default-bridge-network)

If you do not specify a network using the `--network` flag, and you do specify a network driver, your container is connected to the default `bridge` network by default. Containers connected to the default `bridge` network can communicate, but only by IP address, unless they're linked using the [legacy `--link` flag](https://docs.docker.com/engine/network/links/).

### [Configure the default bridge network](#configure-the-default-bridge-network)

To configure the default `bridge` network, you specify options in `daemon.json`. Here is an example `daemon.json` with several options specified. Only specify the settings you need to customize.

```json
{
  "bip": "192.168.1.1/24",
  "fixed-cidr": "192.168.1.0/25",
  "mtu": 1500,
  "default-gateway": "192.168.1.254",
  "dns": ["10.20.1.2", "10.20.1.3"]
}
```

In this example:

* The bridge's address is "192.168.1.1/24" (from `bip`).
* The bridge network's subnet is "192.168.1.0/24" (from `bip`).
* Container addresses will be allocated from "192.168.1.0/25" (from `fixed-cidr`).

### [Use IPv6 with the default bridge network](#use-ipv6-with-the-default-bridge-network)

IPv6 can be enabled for the default bridge using the following options in `daemon.json`, or their command line equivalents.

These three options only affect the default bridge, they are not used by user-defined networks. The addresses in below are examples from the IPv6 documentation range.

* Option `ipv6` is required.

* Option `bip6` is optional, it specifies the address of the default bridge, which will be used as the default gateway by containers. It also specifies the subnet for the bridge network.

* Option `fixed-cidr-v6` is optional, it specifies the address range Docker may automatically allocate to containers.

  * The prefix should normally be `/64` or shorter.
  * For experimentation on a local network, it is better to use a Unique Local Address (ULA) prefix (matching `fd00::/8`) than a Link Local prefix (matching `fe80::/10`).

* Option `default-gateway-v6` is optional. If unspecified, the default is the first address in the `fixed-cidr-v6` subnet.

```json
{
  "ipv6": true,
  "bip6": "2001:db8::1111/64",
  "fixed-cidr-v6": "2001:db8::/64",
  "default-gateway-v6": "2001:db8:abcd::89"
}
```

If no `bip6` is specified, `fixed-cidr-v6` defines the subnet for the bridge network. If no `bip6` or `fixed-cidr-v6` is specified, a ULA prefix will be chosen.

Restart Docker for changes to take effect.

## [Connection limit for bridge networks](#connection-limit-for-bridge-networks)

Due to limitations set by the Linux kernel, bridge networks become unstable and inter-container communications may break when 1000 containers or more connect to a single network.

For more information about this limitation, see [moby/moby#44973](https://github.com/moby/moby/issues/44973#issuecomment-1543747718).

## [Skip Bridge IP address configuration](#skip-bridge-ip-address-configuration)

The bridge is normally assigned the network's `--gateway` address, which is used as the default route from the bridge network to other networks.

The `com.docker.network.bridge.inhibit_ipv4` option lets you create a network without the IPv4 gateway address being assigned to the bridge. This is useful if you want to configure the gateway IP address for the bridge manually. For instance if you add a physical interface to your bridge, and need it to have the gateway address.

With this configuration, north-south traffic (to and from the bridge network) won't work unless you've manually configured the gateway address on the bridge, or a device attached to it.

This option can only be used with user-defined bridge networks.

## [Usage examples](#usage-examples)

This section provides hands-on examples for working with bridge networks.

### [Use the default bridge network](#use-the-default-bridge-network-1)

This example shows how the default `bridge` network works. You start two `alpine` containers on the default bridge and test how they communicate.

> Note
>
> The default `bridge` network is not recommended for production. Use user-defined bridge networks instead.

1. List current networks:

   ```console
   $ docker network ls

   NETWORK ID          NAME                DRIVER              SCOPE
   17e324f45964        bridge              bridge              local
   6ed54d316334        host                host                local
   7092879f2cc8        none                null                local
   ```

   The default `bridge` network is listed, along with `host` and `none`.

2. Start two `alpine` containers running `ash`. The `-dit` flags mean detached, interactive, and with a TTY. Since you haven't specified a `--network` flag, the containers connect to the default `bridge` network.

   ```console
   $ docker run -dit --name alpine1 alpine ash
   $ docker run -dit --name alpine2 alpine ash
   ```

   Verify both containers are running:

   ```console
   $ docker container ls

   CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
   602dbf1edc81        alpine              "ash"               4 seconds ago       Up 3 seconds                            alpine2
   da33b7aa74b0        alpine              "ash"               17 seconds ago      Up 16 seconds                           alpine1
   ```

3. Inspect the `bridge` network to see connected containers:

   ```console
   $ docker network inspect bridge
   ```

   The output shows both containers connected, with their assigned IP addresses (`172.17.0.2` for `alpine1` and `172.17.0.3` for `alpine2`).

4. Connect to `alpine1`:

   ```console
   $ docker attach alpine1

   / #
   ```

   Show the network interfaces for `alpine1` from within the container:

   ```console
   # ip addr show

   1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN qlen 1
       link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
       inet 127.0.0.1/8 scope host lo
          valid_lft forever preferred_lft forever
       inet6 ::1/128 scope host
          valid_lft forever preferred_lft forever
   27: eth0@if28: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP
       link/ether 02:42:ac:11:00:02 brd ff:ff:ff:ff:ff:ff
       inet 172.17.0.2/16 scope global eth0
          valid_lft forever preferred_lft forever
   ```

   In this example, the `eth0` interface has the IP address `172.17.0.2`.

5. From within `alpine1`, verify you can connect to the internet:

   ```console
   # ping -c 2 google.com

   PING google.com (172.217.3.174): 56 data bytes
   64 bytes from 172.217.3.174: seq=0 ttl=41 time=9.841 ms
   64 bytes from 172.217.3.174: seq=1 ttl=41 time=9.897 ms

   --- google.com ping statistics ---
   2 packets transmitted, 2 packets received, 0% packet loss
   round-trip min/avg/max = 9.841/9.869/9.897 ms
   ```

6. Ping the second container by its IP address:

   ```console
   # ping -c 2 172.17.0.3

   PING 172.17.0.3 (172.17.0.3): 56 data bytes
   64 bytes from 172.17.0.3: seq=0 ttl=64 time=0.086 ms
   64 bytes from 172.17.0.3: seq=1 ttl=64 time=0.094 ms

   --- 172.17.0.3 ping statistics ---
   2 packets transmitted, 2 packets received, 0% packet loss
   round-trip min/avg/max = 0.086/0.090/0.094 ms
   ```

   This succeeds. Now try pinging by container name:

   ```console
   # ping -c 2 alpine2

   ping: bad address 'alpine2'
   ```

   On the default bridge network, containers can't resolve each other by name.

7. Detach from `alpine1` without stopping it using `CTRL+p CTRL+q`.

8. Clean up: stop the containers and remove them.

   ```console
   $ docker container stop alpine1 alpine2
   $ docker container rm alpine1 alpine2
   ```

   Stopped containers lose their IP addresses.

### [Use user-defined bridge networks](#use-user-defined-bridge-networks)

This example shows how user-defined bridge networks provide better isolation and automatic DNS resolution between containers.

1. Create the `alpine-net` network:

   ```console
   $ docker network create --driver bridge alpine-net
   ```

2. List Docker's networks:

   ```console
   $ docker network ls

   NETWORK ID          NAME                DRIVER              SCOPE
   e9261a8c9a19        alpine-net          bridge              local
   17e324f45964        bridge              bridge              local
   6ed54d316334        host                host                local
   7092879f2cc8        none                null                local
   ```

   Inspect the `alpine-net` network:

   ```console
   $ docker network inspect alpine-net
   ```

   This shows the network's gateway (for example, `172.18.0.1`) and that no containers are connected yet.

3. Create four containers. Three connect to `alpine-net`, and one connects to the default `bridge`. Then connect one container to both networks:

   ```console
   $ docker run -dit --name alpine1 --network alpine-net alpine ash
   $ docker run -dit --name alpine2 --network alpine-net alpine ash
   $ docker run -dit --name alpine3 alpine ash
   $ docker run -dit --name alpine4 --network alpine-net alpine ash
   $ docker network connect bridge alpine4
   ```

   Verify all containers are running:

   ```console
   $ docker container ls

   CONTAINER ID        IMAGE               COMMAND             CREATED              STATUS              PORTS               NAMES
   156849ccd902        alpine              "ash"               41 seconds ago       Up 41 seconds                           alpine4
   fa1340b8d83e        alpine              "ash"               51 seconds ago       Up 51 seconds                           alpine3
   a535d969081e        alpine              "ash"               About a minute ago   Up About a minute                       alpine2
   0a02c449a6e9        alpine              "ash"               About a minute ago   Up About a minute                       alpine1
   ```

4. Inspect both networks again to see which containers are connected:

   ```console
   $ docker network inspect bridge
   ```

   Containers `alpine3` and `alpine4` are connected to the `bridge` network.

   ```console
   $ docker network inspect alpine-net
   ```

   Containers `alpine1`, `alpine2`, and `alpine4` are connected to `alpine-net`.

5. On user-defined networks, containers can resolve each other by name. Connect to `alpine1` and test:

   > Note
   >
   > Automatic service discovery only resolves custom container names, not default automatically generated names.

   ```console
   $ docker container attach alpine1

   # ping -c 2 alpine2

   PING alpine2 (172.18.0.3): 56 data bytes
   64 bytes from 172.18.0.3: seq=0 ttl=64 time=0.085 ms
   64 bytes from 172.18.0.3: seq=1 ttl=64 time=0.090 ms

   --- alpine2 ping statistics ---
   2 packets transmitted, 2 packets received, 0% packet loss
   round-trip min/avg/max = 0.085/0.087/0.090 ms

   # ping -c 2 alpine4

   PING alpine4 (172.18.0.4): 56 data bytes
   64 bytes from 172.18.0.4: seq=0 ttl=64 time=0.076 ms
   64 bytes from 172.18.0.4: seq=1 ttl=64 time=0.091 ms

   --- alpine4 ping statistics ---
   2 packets transmitted, 2 packets received, 0% packet loss
   round-trip min/avg/max = 0.076/0.083/0.091 ms
   ```

6. From `alpine1`, you can't connect to `alpine3` because it's on a different network:

   ```console
   # ping -c 2 alpine3

   ping: bad address 'alpine3'
   ```

   You also can't connect by IP address. If `alpine3`'s IP is `172.17.0.2`:

   ```console
   # ping -c 2 172.17.0.2

   PING 172.17.0.2 (172.17.0.2): 56 data bytes

   --- 172.17.0.2 ping statistics ---
   2 packets transmitted, 0 packets received, 100% packet loss
   ```

   Detach from `alpine1` using `CTRL+p CTRL+q`.

7. Since `alpine4` is connected to both networks, it can reach all containers. However, you need to use `alpine3`'s IP address:

   ```console
   $ docker container attach alpine4

   # ping -c 2 alpine1

   PING alpine1 (172.18.0.2): 56 data bytes
   64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.074 ms
   64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.082 ms

   --- alpine1 ping statistics ---
   2 packets transmitted, 2 packets received, 0% packet loss
   round-trip min/avg/max = 0.074/0.078/0.082 ms

   # ping -c 2 alpine2

   PING alpine2 (172.18.0.3): 56 data bytes
   64 bytes from 172.18.0.3: seq=0 ttl=64 time=0.075 ms
   64 bytes from 172.18.0.3: seq=1 ttl=64 time=0.080 ms

   --- alpine2 ping statistics ---
   2 packets transmitted, 2 packets received, 0% packet loss
   round-trip min/avg/max = 0.075/0.077/0.080 ms

   # ping -c 2 alpine3
   ping: bad address 'alpine3'

   # ping -c 2 172.17.0.2

   PING 172.17.0.2 (172.17.0.2): 56 data bytes
   64 bytes from 172.17.0.2: seq=0 ttl=64 time=0.089 ms
   64 bytes from 172.17.0.2: seq=1 ttl=64 time=0.075 ms

   --- 172.17.0.2 ping statistics ---
   2 packets transmitted, 2 packets received, 0% packet loss
   round-trip min/avg/max = 0.075/0.082/0.089 ms
   ```

8. Verify all containers can connect to the internet:

   ```console
   # ping -c 2 google.com

   PING google.com (172.217.3.174): 56 data bytes
   64 bytes from 172.217.3.174: seq=0 ttl=41 time=9.778 ms
   64 bytes from 172.217.3.174: seq=1 ttl=41 time=9.634 ms

   --- google.com ping statistics ---
   2 packets transmitted, 2 packets received, 0% packet loss
   round-trip min/avg/max = 9.634/9.706/9.778 ms
   ```

   Detach with `CTRL+p CTRL+q` and repeat for `alpine3` and `alpine1` if desired.

9. Clean up:

   ```console
   $ docker container stop alpine1 alpine2 alpine3 alpine4
   $ docker container rm alpine1 alpine2 alpine3 alpine4
   $ docker network rm alpine-net
   ```

## [Next steps](#next-steps)

* Learn about [networking from the container's point of view](https://docs.docker.com/engine/network/)
* Learn about [overlay networks](https://docs.docker.com/engine/network/drivers/overlay/)
* Learn about [Macvlan networks](https://docs.docker.com/engine/network/drivers/macvlan/)

----
url: https://docs.docker.com/enterprise/enterprise-deployment/use-jamf-pro/
----

# Deploy with Jamf Pro

***

Table of contents

***

For: Administrators

Learn how to deploy Docker Desktop for Mac using Jamf Pro, including uploading the installer and creating a deployment policy.

First, upload the package:

1. From the Jamf Pro console, navigate to **Computers** > **Management Settings** > **Computer Management** > **Packages**.
2. Select **New** to add a new package.
3. Upload the `Docker.pkg` file.

Next, create a policy for deployment:

1. Navigate to **Computers** > **Policies**.
2. Select **New** to create a new policy.
3. Enter a name for the policy, for example "Deploy Docker Desktop".
4. Under the **Packages** tab, add the Docker package you uploaded.
5. Configure the scope to target the devices or device groups on which you want to install Docker.
6. Save the policy and deploy.

For more information, see [Jamf Pro's official documentation](https://learn.jamf.com/en-US/bundle/jamf-pro-documentation-current/page/Policies.html).

## [Additional resources](#additional-resources)

* Learn how to [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) for your users.

----
url: https://docs.docker.com/dhi/explore/malware-scanning/
----

# Malware scanning

***

Table of contents

***

The Docker Hardened Image (DHI) pipeline scans for viruses and malware as part of the build process. The scan results are embedded as a signed attestation, which you can independently retrieve and verify.

## [How it works](#how-it-works)

Docker uses [ClamAV](https://www.clamav.net/), an open source antivirus engine, to scan every layer of each image. The scan runs automatically during the build process and checks all files in the image, including files inside archives, for known viruses and malware signatures.

The scan results are published as a signed attestation attached to the image. The attestation includes the full ClamAV scan report, including the number of files scanned, the virus signature database version, and whether any infected files were detected.

## [View the malware scan attestation](#view-the-malware-scan-attestation)

You can retrieve the malware scan attestation using the Docker Scout CLI.

1. Use the `docker scout attest get` command with the virus scan predicate type:

   ```console
   $ docker scout attest get \
     --predicate-type https://scout.docker.com/virus/v0.1 \
     --predicate \
     dhi.io/<image>:<tag>
   ```

   > Note
   >
   > If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://dhi.io/python` instead of `dhi.io/python`.

   For example:

   ```console
   $ docker scout attest get \
     --predicate-type https://scout.docker.com/virus/v0.1 \
     --predicate \
     dhi.io/python:3.13
   ```

   The output is a JSON object containing the scanner used and the base64-encoded scan report:

   ```json
   {
     "scanner": {
       "report": "<base64-encoded ClamAV report>",
       "uri": "clamav/clamav:stable"
     }
   }
   ```

   Decoding the report shows the full ClamAV output, ending with a scan summary:

   ```text
   ----------- SCAN SUMMARY -----------
   Known viruses: 3627833
   Engine version: 1.5.2
   Scanned directories: 4
   Scanned files: 21
   Infected files: 0
   Data scanned: 44.90 MiB
   Data read: 23.88 MiB (ratio 1.88:1)
   Time: 11.473 sec (0 m 11 s)
   Start Date: 2026:04:12 02:36:19
   End Date:   2026:04:12 02:36:30
   ```

2. Verify the attestation signature. To ensure the attestation is authentic and signed by Docker, run:

   ```console
   $ docker scout attest get \
     --predicate-type https://scout.docker.com/virus/v0.1 \
     --verify \
     dhi.io/<image>:<tag> --platform <platform>
   ```

   If the attestation is valid, Docker Scout confirms the signature and shows the matching `cosign verify` command.

To view other attestations, such as SBOMs or test results, see [Verify an image](https://docs.docker.com/dhi/how-to/verify/).

----
url: https://docs.docker.com/dhi/migration/checklist/
----

# Migration checklist

***

Table of contents

***

Use this checklist to ensure you address key considerations when migrating to Docker Hardened Images.

## [Migration considerations](#migration-considerations)

| Item               | Action required                                                                                                                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base image         | Update your Dockerfile `FROM` statements to reference a Docker Hardened Image instead of your current base image.                                                                                                                           |
| Package management | Install packages only in `dev`-tagged images during build stages. Use `apk` for Alpine-based images or `apt` for Debian-based images. Copy the necessary artifacts to your runtime stage, as runtime images don't include package managers. |
| Non-root user      | Verify that all files and directories your application needs are readable and writable by the nonroot user (UID 65532), as runtime images run as nonroot by default.                                                                        |
| Multi-stage build  | Use `dev` or `sdk`-tagged images for build stages where you need build tools and package managers. Use non-dev images for your final runtime stage.                                                                                         |
| TLS certificates   | Remove any steps that install ca-certificates, as DHIs include ca-certificates by default.                                                                                                                                                  |
| Ports              | Configure your application to listen on port 1025 or higher inside the container, as the nonroot user can't bind to privileged ports (below 1024) in Kubernetes or Docker Engine versions older than 20.10.                                 |
| Entry point        | Check the entry point of your chosen DHI using `docker inspect` or the image documentation. Update your Dockerfile's `ENTRYPOINT` or `CMD` instructions if your application relies on a different entry point.                              |
| No shell           | Move any shell commands (`RUN`, `SHELL`) to build stages using `dev`-tagged images. Runtime images don't include a shell, so copy all necessary artifacts from the build stage.                                                             |

----
url: https://docs.docker.com/guides/ruby/configure-github-actions/
----

# Automate your builds with GitHub Actions

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a Ruby on Rails application](https://docs.docker.com/guides/ruby/containerize/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

```yaml
name: Build and push Docker image

on:
  push:
    branches:
      - main

jobs:
  build_and_push:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
```

In this section, you learned how to set up a GitHub Actions workflow for your Ruby on Rails application.

Related information:

* [Introduction to GitHub Actions](https://docs.docker.com/guides/gha/)
* [Docker Build GitHub Actions](https://docs.docker.com/build/ci/github-actions/)
* [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)

## [Next steps](#next-steps)

In the next section, you'll learn how you can develop your application using containers.

[Use containers for Ruby on Rails development »](https://docs.docker.com/guides/ruby/develop/)

----
url: https://docs.docker.com/guides/r/develop/
----

# Use containers for R development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a R application](https://docs.docker.com/guides/r/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment for your containerized application. This includes:

* Adding a local database and persisting data
* Configuring Compose to automatically update your running Compose services as you edit and save your code

## [Get the sample application](#get-the-sample-application)

You'll need to clone a new repository to get a sample application that includes logic to connect to the database.

Change to a directory where you want to clone the repository and run the following command.

```console
$ git clone https://github.com/mfranzon/r-docker-dev.git
```

## [Configure the application to use the database](#configure-the-application-to-use-the-database)

To try the connection between the Shiny application and the local database you have to modify the `Dockerfile` changing the `COPY` instruction:

```diff
-COPY src/ .
+COPY src_db/ .
```

## [Add a local database and persist data](#add-a-local-database-and-persist-data)

You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data.

In the cloned repository's directory, open the `compose.yaml` file in an IDE or text editor.

In the `compose.yaml` file, you need to un-comment the properties for configuring the database. You must also mount the database password file and set an environment variable on the `shiny-app` service pointing to the location of the file in the container.

The following is the updated `compose.yaml` file.

```yaml
services:
  shiny-app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - 3838:3838
    environment:
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    depends_on:
      db:
        condition: service_healthy
    secrets:
      - db-password
  db:
    image: postgres:18
    restart: always
    user: postgres
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    expose:
      - 5432
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
```

> Note
>
> To learn more about the instructions in the Compose file, see [Compose file reference](/reference/compose-file/).

Before you run the application using Compose, notice that this Compose file specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository.

In the cloned repository's directory, create a new directory named `db` and inside that directory create a file named `password.txt` that contains the password for the database. Using your favorite IDE or text editor, add the following contents to the `password.txt` file.

```text
mysecretpassword
```

Save and close the `password.txt` file.

You should now have the following contents in your `r-docker-dev` directory.

```text
├── r-docker-dev/
│ ├── db/
│ │ └── password.txt
│ ├── src/
│ │ └── app.R
│ ├── src_db/
│ │ └── app_db.R
│ ├── requirements.txt
│ ├── .dockerignore
│ ├── compose.yaml
│ ├── Dockerfile
│ └── README.md
```

Now, run the following `docker compose up` command to start your application.

```console
$ docker compose up --build
```

Now test your DB connection opening a browser at:

```console
http://localhost:3838
```

You should see a pop-up message:

```text
DB CONNECTED
```

Press `ctrl+c` in the terminal to stop your application.

## [Automatically update services](#automatically-update-services)

Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

Lines 15 to 18 in the `compose.yaml` file contain properties that trigger Docker to rebuild the image when a file in the current working directory is changed:

|                                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
``` | ```yaml
services:
  shiny-app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - 3838:3838
    environment:
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    depends_on:
      db:
        condition: service_healthy
    secrets:
      - db-password
    develop:
      watch:
        - action: rebuild
          path: .
  db:
    image: postgres:18
    restart: always
    user: postgres
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    expose:
      - 5432
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
``` |

Run the following command to run your application with Compose Watch.

```console
$ docker compose watch
```

Now, if you modify your `app.R` you will see the changes in real time without re-building the image!

In the next section, you'll take a look at how to set up a CI/CD pipeline using GitHub Actions.

[Configure CI/CD for your R application »](https://docs.docker.com/guides/r/configure-ci-cd/)

----
url: https://docs.docker.com/reference/cli/docker/desktop/engine/use/
----

# docker desktop engine use

***

| Description | Switch to Windows or Linux containers (Windows only) |
| ----------- | ---------------------------------------------------- |
| Usage       | `docker desktop engine use NAME`                     |

----
url: https://docs.docker.com/guides/go-prometheus-monitoring/
----

# Monitor a Golang application with Prometheus and Grafana

Table of contents

***

Learn how to containerize a Golang application and monitor it with Prometheus and Grafana.

**Time to complete** 45 minutes

The guide teaches you how to containerize a Golang application and monitor it with Prometheus and Grafana.

> **Acknowledgment**
>
> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide.

## [Overview](#overview)

To make sure your application is working as intended, monitoring is important. One of the most popular monitoring tools is Prometheus. Prometheus is an open-source monitoring and alerting toolkit that is designed for reliability and scalability. It collects metrics from monitored targets by scraping metrics HTTP endpoints on these targets. To visualize the metrics, you can use Grafana. Grafana is an open-source platform for monitoring and observability that allows you to query, visualize, alert on, and understand your metrics no matter where they are stored.

In this guide, you will be creating a Golang server with some endpoints to simulate a real-world application. Then you will expose metrics from the server using Prometheus. Finally, you will visualize the metrics using Grafana. You will containerize the Golang application, and using the Docker Compose file, you will connect all the services: Golang, Prometheus, and Grafana.

## [What will you learn?](#what-will-you-learn)

* Create a Golang application with custom Prometheus metrics.
* Containerize a Golang application.
* Use Docker Compose to run multiple services and connect them together to monitor a Golang application with Prometheus and Grafana.
* Visualize the metrics using Grafana dashboards.

## [Prerequisites](#prerequisites)

* A good understanding of Golang is assumed.
* You must me familiar with Prometheus and creating dashboards in Grafana.
* You must have familiarity with Docker concepts like containers, images, and Dockerfiles. If you are new to Docker, you can start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide.

## [Next steps](#next-steps)

You will create a Golang server and expose metrics using Prometheus.

## [Modules](#modules)

1. [Understand the application](https://docs.docker.com/guides/go-prometheus-monitoring/application/)

   Learn how to create a Golang server to register metrics with Prometheus.

2. [Containerize your app](https://docs.docker.com/guides/go-prometheus-monitoring/containerize/)

   Learn how to containerize a Golang application.

3. [Connect with Compose](https://docs.docker.com/guides/go-prometheus-monitoring/compose/)

   Learn how to connect services with Docker Compose to monitor a Golang application with Prometheus and Grafana.

4. [Develop your app](https://docs.docker.com/guides/go-prometheus-monitoring/develop/)

   Learn how to develop the Golang application with Docker.

----
url: https://docs.docker.com/dhi/core-concepts/distroless/
----

# Minimal or distroless images

***

Table of contents

***

Minimal images, sometimes called distroless images, are container images stripped of unnecessary components such as package managers, shells, or even the underlying operating system distribution. Docker Hardened Images (DHI) embrace this minimal approach to reduce vulnerabilities and enforce secure software delivery. [Docker Official Images](https://docs.docker.com/docker-hub/image-library/trusted-content/#docker-official-images) and [Docker Verified Publisher Images](https://docs.docker.com/docker-hub/image-library/trusted-content/#verified-publisher-images) follow similar best practices for minimalism and security but may not be as stripped down to ensure compatibility with a wider range of use cases.

## [What are minimal or distroless images?](#what-are-minimal-or-distroless-images)

Traditional container images include a full OS, often more than what is needed to run an application. In contrast, minimal or distroless images include only:

* The application binary
* Its runtime dependencies (e.g., libc, Java, Python)
* Any explicitly required configuration or metadata

They typically exclude:

* OS tools (e.g., `ls`, `ps`, `cat`)
* Shells (e.g., `sh`, `bash`)
* Package managers (e.g., `apt`, `apk`)
* Debugging utilities (e.g., `curl`, `wget`, `strace`)

Docker Hardened Images are based on this model, ensuring a smaller and more secure runtime surface.

## [What you gain](#what-you-gain)

| Benefit                | Description                                                                   |
| ---------------------- | ----------------------------------------------------------------------------- |
| Smaller attack surface | Fewer components mean fewer vulnerabilities and less exposure to CVEs         |
| Faster startup         | Smaller image sizes result in faster pull and start times                     |
| Improved security      | Lack of shell and package manager limits what attackers can do if compromised |
| Better compliance      | Easier to audit and verify, especially with SBOMs and attestations            |

## [Addressing common tradeoffs](#addressing-common-tradeoffs)

Minimal and distroless images offer strong security benefits, but they can change how you work with containers. Docker Hardened Images are designed to maintain productivity while enhancing security.

| Concern       | How Docker Hardened Images help                                                                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Debuggability | Hardened images exclude shells and CLI tools by default. Use [Docker Debug](/reference/cli/docker/debug/) to temporarily attach a debug sidecar for troubleshooting without modifying the original container. |
| Familiarity   | DHI supports multiple base images, including Alpine and Debian variants, so you can choose a familiar environment while still benefiting from hardening practices.                                            |
| Flexibility   | Runtime immutability helps secure your containers. Use multi-stage builds and CI/CD to control changes, and optionally use dev-focused base images during development.                                        |

By balancing minimalism with practical tooling, Docker Hardened Images support modern development workflows without compromising on security or reliability.

## [Best practices for using minimal images](#best-practices-for-using-minimal-images)

* Use multi-stage builds to separate build-time and runtime environments
* Validate image behavior using CI pipelines, not interactive inspection
* Include runtime-specific dependencies explicitly in your Dockerfile
* Use Docker Scout to continuously monitor for CVEs, even in minimal images

By adopting minimal or distroless images through Docker Hardened Images, you gain a more secure, predictable, and production-ready container environment that's designed for automation, clarity, and reduced risk.

----
url: https://docs.docker.com/guides/testcontainers-dotnet-getting-started/create-project/
----

# Create the .NET project

***

Table of contents

***

## [Set up the solution](#set-up-the-solution)

Create a .NET solution with source and test projects:

```console
$ dotnet new sln -o TestcontainersDemo
$ cd TestcontainersDemo
$ dotnet new classlib -o CustomerService
$ dotnet sln add ./CustomerService/CustomerService.csproj
$ dotnet new xunit -o CustomerService.Tests
$ dotnet sln add ./CustomerService.Tests/CustomerService.Tests.csproj
$ dotnet add ./CustomerService.Tests/CustomerService.Tests.csproj reference ./CustomerService/CustomerService.csproj
```

Add the Npgsql dependency to the source project:

```console
$ dotnet add ./CustomerService/CustomerService.csproj package Npgsql
```

## [Implement the business logic](#implement-the-business-logic)

Create a `Customer` record type:

```csharp
namespace Customers;

public readonly record struct Customer(long Id, string Name);
```

Create a `DbConnectionProvider` class to manage database connections:

```csharp
using System.Data.Common;
using Npgsql;

namespace Customers;

public sealed class DbConnectionProvider
{
    private readonly string _connectionString;

    public DbConnectionProvider(string connectionString)
    {
        _connectionString = connectionString;
    }

    public DbConnection GetConnection()
    {
        return new NpgsqlConnection(_connectionString);
    }
}
```

Create the `CustomerService` class:

```csharp
namespace Customers;

public sealed class CustomerService
{
    private readonly DbConnectionProvider _dbConnectionProvider;

    public CustomerService(DbConnectionProvider dbConnectionProvider)
    {
        _dbConnectionProvider = dbConnectionProvider;
        CreateCustomersTable();
    }

    public IEnumerable<Customer> GetCustomers()
    {
        IList<Customer> customers = new List<Customer>();

        using var connection = _dbConnectionProvider.GetConnection();
        using var command = connection.CreateCommand();
        command.CommandText = "SELECT id, name FROM customers";
        command.Connection?.Open();

        using var dataReader = command.ExecuteReader();
        while (dataReader.Read())
        {
            var id = dataReader.GetInt64(0);
            var name = dataReader.GetString(1);
            customers.Add(new Customer(id, name));
        }

        return customers;
    }

    public void Create(Customer customer)
    {
        using var connection = _dbConnectionProvider.GetConnection();
        using var command = connection.CreateCommand();

        var id = command.CreateParameter();
        id.ParameterName = "@id";
        id.Value = customer.Id;

        var name = command.CreateParameter();
        name.ParameterName = "@name";
        name.Value = customer.Name;

        command.CommandText = "INSERT INTO customers (id, name) VALUES(@id, @name)";
        command.Parameters.Add(id);
        command.Parameters.Add(name);
        command.Connection?.Open();
        command.ExecuteNonQuery();
    }

    private void CreateCustomersTable()
    {
        using var connection = _dbConnectionProvider.GetConnection();
        using var command = connection.CreateCommand();
        command.CommandText = "CREATE TABLE IF NOT EXISTS customers (id BIGINT NOT NULL, name VARCHAR NOT NULL, PRIMARY KEY (id))";
        command.Connection?.Open();
        command.ExecuteNonQuery();
    }
}
```

Here's what `CustomerService` does:

* The constructor calls `CreateCustomersTable()` to ensure the table exists.
* `GetCustomers()` fetches all rows from the `customers` table and returns them as `Customer` objects.
* `Create()` inserts a customer record into the database.

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-dotnet-getting-started/write-tests/)

----
url: https://docs.docker.com/guides/testcontainers-java-replace-h2/jdbc-url-approach/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Replace H2 with the Testcontainers JDBC URL

***

Table of contents

***

Replacing H2 with a real PostgreSQL database requires two test properties:

```java
@DataJpaTest
@TestPropertySource(properties = {
  "spring.test.database.replace=none",
  "spring.datasource.url=jdbc:tc:postgresql:16-alpine:///db"
})
class ProductRepositoryWithJdbcUrlTest {

  @Autowired
  ProductRepository productRepository;

  @Test
  @Sql("classpath:/sql/seed-data.sql")
  void shouldGetAllProducts() {
    List<Product> products = productRepository.findAll();
    assertEquals(2, products.size());
  }
}
```

That's it — two properties and your tests run against a real PostgreSQL database.

## [How the special JDBC URL works](#how-the-special-jdbc-url-works)

A standard PostgreSQL JDBC URL looks like:

```text
jdbc:postgresql://localhost:5432/postgres
```

The Testcontainers special JDBC URL inserts `tc:` after `jdbc:`:

```text
jdbc:tc:postgresql:///db
```

The hostname, port, and database name are ignored — Testcontainers manages them automatically. You can specify the Docker image tag after the database name:

```text
jdbc:tc:postgresql:16-alpine:///db
```

This creates a container from the `postgres:16-alpine` image.

## [Initialize the database with a script](#initialize-the-database-with-a-script)

Pass `TC_INITSCRIPT` to run an SQL script when the container starts:

```text
jdbc:tc:postgresql:16-alpine:///db?TC_INITSCRIPT=sql/init-db.sql
```

Testcontainers runs the script automatically. For production applications, use a database migration tool like Flyway or Liquibase instead.

The special JDBC URL also works for MySQL, MariaDB, PostGIS, YugabyteDB, CockroachDB, and other databases with Testcontainers JDBC support.

## [Testing JdbcTemplate-based repositories](#testing-jdbctemplate-based-repositories)

The same approach works for `JdbcTemplate`-based repositories. Use `@JdbcTest` instead of `@DataJpaTest`:

```java
@JdbcTest
@TestPropertySource(properties = {
  "spring.test.database.replace=none",
  "spring.datasource.url=jdbc:tc:postgresql:16-alpine:///db?TC_INITSCRIPT=sql/init-db.sql"
})
class JdbcProductRepositoryTest {

  @Autowired
  private JdbcTemplate jdbcTemplate;

  private JdbcProductRepository productRepository;

  @BeforeEach
  void setUp() {
    productRepository = new JdbcProductRepository(jdbcTemplate);
  }

  @Test
  @Sql("/sql/seed-data.sql")
  void shouldGetAllProducts() {
    List<Product> products = productRepository.getAllProducts();
    assertEquals(2, products.size());
  }
}
```

[Use the JUnit 5 extension for more control »](https://docs.docker.com/guides/testcontainers-java-replace-h2/junit-extension-approach/)

----
url: https://docs.docker.com/enterprise/security/provisioning/scim/migrate-scim/
----

# Migrate JIT to SCIM

***

Table of contents

***

If you already have users provisioned through Just-in-Time (JIT) and want to enable full SCIM lifecycle management, you need to migrate them. Users originally created by JIT cannot be automatically de-provisioned through SCIM, even after SCIM is enabled.

## [Why migrate](#why-migrate)

Organizations using JIT provisioning may encounter limitations with user lifecycle management, particularly around de-provisioning. Migrating to SCIM provides:

* Automatic user de-provisioning when users leave your organization. This is the primary benefit for large organizations that need full automation.
* Continuous synchronization of user attributes
* Centralized user management through your identity provider
* Enhanced security through automated access control

> Important
>
> Users originally created through JIT provisioning cannot be automatically de-provisioned by SCIM, even after SCIM is enabled. To enable full lifecycle management including automatic de-provisioning through your identity provider, you must manually remove these users so SCIM can re-create them with proper lifecycle management capabilities.

This migration is most critical for larger organizations that require fully automated user de-provisioning when employees leave the company.

## [Prerequisites](#prerequisites)

Before migrating, ensure you have:

* SCIM configured and tested in your organization
* A maintenance window for the migration

> Warning
>
> This migration temporarily disrupts user access. Plan to perform this migration during a low-usage window and communicate the timeline to affected users.

## [Prepare for migration](#prepare-for-migration)

### [Transfer ownership](#transfer-ownership)

Before removing users, ensure that any repositories, teams, or organization resources they own are transferred to another administrator or service account. When a user is removed from the organization, any resources they own may become inaccessible.

1. Review repositories, organization resources, and team ownership for affected users.
2. Transfer ownership to another administrator.

> Warning
>
> If ownership is not transferred, repositories owned by removed users may become inaccessible when the user is removed. Ensure all critical resources are transferred before proceeding.

### [Verify identity provider configuration](#verify-identity-provider-configuration)

1. Confirm all JIT-provisioned users are assigned to the Docker application in your identity provider.
2. Verify identity provider group to Docker Team mappings are configured and tested.

Users not assigned to the Docker application in your identity provider are not re-created by SCIM after removal.

### [Export user records](#export-user-records)

Export a list of JIT-provisioned users from Docker Admin Console:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization.
2. Select **Admin Console**, then **Members**.
3. Select **Export members** to download the member list as CSV for backup and reference.

Keep this CSV list of JIT-provisioned users as a rollback reference if needed.

## [Complete the migration](#complete-the-migration)

### [Disable JIT provisioning](#disable-jit-provisioning)

> Important
>
> Before disabling JIT, ensure SCIM is fully configured and tested in your organization. Do not disable JIT until you have verified SCIM is working correctly.

1. Sign in to [Docker Home](https://app.docker.com) and select your organization.
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the SSO connections table, select the **Actions** menu for your connection.
4. Select **Disable JIT provisioning**.
5. Select **Disable** to confirm.

Disabling JIT prevents new users from being automatically added through SSO during the migration.

### [Remove JIT-origin users](#remove-jit-origin-users)

> Important
>
> Users originally created through JIT provisioning cannot be automatically de-provisioned by SCIM, even after SCIM is enabled. To enable full lifecycle management including automatic de-provisioning through your identity provider, you must manually remove these users so SCIM can re-create them with proper lifecycle management capabilities.

This step is most critical for large organizations that require fully automated user de-provisioning when employees leave the company.

1. Sign in to [Docker Home](https://app.docker.com) and select your organization.
2. Select **Admin Console**, then **Members**.
3. Identify and remove JIT-provisioned users in manageable batches.
4. Monitor for any errors during removal.

> Tip
>
> To efficiently identify JIT users, compare the member list exported before SCIM was enabled with the current member list. Users who existed before SCIM was enabled were likely provisioned via JIT.

### [Verify SCIM re-provisioning](#verify-scim-re-provisioning)

After removing JIT users, SCIM automatically re-creates user accounts:

1. In your identity provider system log, confirm "create app user" events for Docker.
2. In Docker Admin Console, confirm users reappear with SCIM provisioning.
3. Verify users are added to the correct teams via group mapping.

### [Validate user access](#validate-user-access)

Perform post-migration validation:

1. Select a subset of migrated users to test sign-in and access.
2. Verify team membership matches identity provider group assignments.
3. Confirm repository access is restored.
4. Test that de-provisioning works correctly by removing a test user from your identity provider.

Keep audit exports and logs for compliance purposes.

## [Migration results](#migration-results)

After completing the migration:

* All users in your organization are SCIM-provisioned
* User de-provisioning works reliably through your identity provider
* No new JIT users are created
* Consistent identity lifecycle management is maintained

## [Troubleshoot migration issues](#troubleshoot-migration-issues)

If a user fails to reappear after removal:

1. Check that the user is assigned to the Docker application in your identity provider.
2. Verify SCIM is enabled in both Docker and your identity provider.
3. Trigger a manual SCIM sync in your identity provider.
4. Check provisioning logs in your identity provider for errors.

For more troubleshooting guidance, see [Troubleshoot provisioning](https://docs.docker.com/enterprise/security/provisioning/troubleshoot-provisioning/).

## [Next steps](#next-steps)

* Set up [Group mapping](https://docs.docker.com/enterprise/security/provisioning/scim/group-mapping/).
* [Assign roles](https://docs.docker.com/enterprise/security/roles-and-permissions/core-roles/) to members of your org.
* [Enforce sign in](https://docs.docker.com/enterprise/security/enforce-sign-in/), if needed.

----
url: https://docs.docker.com/engine/logging/drivers/awslogs/
----

# Amazon CloudWatch Logs logging driver

***

Table of contents

***

The `awslogs` logging driver sends container logs to [Amazon CloudWatch Logs](https://aws.amazon.com/cloudwatch/details/#log-monitoring). Log entries can be retrieved through the [AWS Management Console](https://console.aws.amazon.com/cloudwatch/home#logs:) or the [AWS SDKs and Command Line Tools](https://docs.aws.amazon.com/cli/latest/reference/logs/index.html).

## [Usage](#usage)

To use the `awslogs` driver as the default logging driver, set the `log-driver` and `log-opt` keys to appropriate values in the `daemon.json` file. For more about configuring Docker using `daemon.json`, see [daemon.json](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file).

> Note
>
> If you're using Docker Desktop, edit the daemon configuration through the Docker Desktop Dashboard. Open **Settings** and select **Docker Engine**. For details, see [Docker Engine settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine).

The following example sets the log driver to `awslogs` and sets the `awslogs-region` option.

```json
{
  "log-driver": "awslogs",
  "log-opts": {
    "awslogs-region": "us-east-1"
  }
}
```

Restart Docker for the changes to take effect.

You can set the logging driver for a specific container by using the `--log-driver` option to `docker run`:

```console
$ docker run --log-driver=awslogs ...
```

If you are using Docker Compose, set `awslogs` using the following declaration example:

```yaml
myservice:
  logging:
    driver: awslogs
    options:
      awslogs-region: us-east-1
```

## [Amazon CloudWatch Logs options](#amazon-cloudwatch-logs-options)

You can add logging options to the `daemon.json` to set Docker-wide defaults, or use the `--log-opt NAME=VALUE` flag to specify Amazon CloudWatch Logs logging driver options when starting a container.

### [awslogs-region](#awslogs-region)

The `awslogs` logging driver sends your Docker logs to a specific region. Use the `awslogs-region` log option or the `AWS_REGION` environment variable to set the region. By default, if your Docker daemon is running on an EC2 instance and no region is set, the driver uses the instance's region.

```console
$ docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 ...
```

### [awslogs-endpoint](#awslogs-endpoint)

By default, Docker uses either the `awslogs-region` log option or the detected region to construct the remote CloudWatch Logs API endpoint. Use the `awslogs-endpoint` log option to override the default endpoint with the provided endpoint.

> Note
>
> The `awslogs-region` log option or detected region controls the region used for signing. You may experience signature errors if the endpoint you've specified with `awslogs-endpoint` uses a different region.

### [awslogs-group](#awslogs-group)

You must specify a [log group](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) for the `awslogs` logging driver. You can specify the log group with the `awslogs-group` log option:

```console
$ docker run --log-driver=awslogs --log-opt awslogs-region=us-east-1 --log-opt awslogs-group=myLogGroup ...
```

### [awslogs-stream](#awslogs-stream)

To configure which [log stream](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) should be used, you can specify the `awslogs-stream` log option. If not specified, the container ID is used as the log stream.

> Note
>
> Log streams within a given log group should only be used by one container at a time. Using the same log stream for multiple containers concurrently can cause reduced logging performance.

### [awslogs-create-group](#awslogs-create-group)

Log driver returns an error by default if the log group doesn't exist. However, you can set the `awslogs-create-group` to `true` to automatically create the log group as needed. The `awslogs-create-group` option defaults to `false`.

```console
$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-create-group=true \
    ...
```

> Note
>
> Your AWS IAM policy must include the `logs:CreateLogGroup` permission before you attempt to use `awslogs-create-group`.

### [awslogs-create-stream](#awslogs-create-stream)

By default, the log driver creates the AWS CloudWatch Logs stream used for container log persistence.

Set `awslogs-create-stream` to `false` to disable log stream creation. When disabled, the Docker daemon assumes the log stream already exists. A use case where this is beneficial is when log stream creation is handled by another process avoiding redundant AWS CloudWatch Logs API calls.

If `awslogs-create-stream` is set to `false` and the log stream does not exist, log persistence to CloudWatch fails during container runtime, resulting in `Failed to put log events` error messages in daemon logs.

```console
$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-stream=myLogStream \
    --log-opt awslogs-create-stream=false \
    ...
```

### [awslogs-datetime-format](#awslogs-datetime-format)

The `awslogs-datetime-format` option defines a multi-line start pattern in [Python `strftime` format](https://strftime.org). A log message consists of a line that matches the pattern and any following lines that don't match the pattern. Thus the matched line is the delimiter between log messages.

One example of a use case for using this format is for parsing output such as a stack dump, which might otherwise be logged in multiple entries. The correct pattern allows it to be captured in a single entry.

This option always takes precedence if both `awslogs-datetime-format` and `awslogs-multiline-pattern` are configured.

> Note
>
> Multi-line logging performs regular expression parsing and matching of all log messages, which may have a negative impact on logging performance.

Consider the following log stream, where new log messages start with a timestamp:

```console
[May 01, 2017 19:00:01] A message was logged
[May 01, 2017 19:00:04] Another multi-line message was logged
Some random message
with some random words
[May 01, 2017 19:01:32] Another message was logged
```

The format can be expressed as a `strftime` expression of `[%b %d, %Y %H:%M:%S]`, and the `awslogs-datetime-format` value can be set to that expression:

```console
$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-datetime-format='\[%b %d, %Y %H:%M:%S\]' \
    ...
```

This parses the logs into the following CloudWatch log events:

```console
# First event
[May 01, 2017 19:00:01] A message was logged

# Second event
[May 01, 2017 19:00:04] Another multi-line message was logged
Some random message
with some random words

# Third event
[May 01, 2017 19:01:32] Another message was logged
```

The following `strftime` codes are supported:

| Code | Meaning                                                          | Example  |
| ---- | ---------------------------------------------------------------- | -------- |
| `%a` | Weekday abbreviated name.                                        | Mon      |
| `%A` | Weekday full name.                                               | Monday   |
| `%w` | Weekday as a decimal number where 0 is Sunday and 6 is Saturday. | 0        |
| `%d` | Day of the month as a zero-padded decimal number.                | 08       |
| `%b` | Month abbreviated name.                                          | Feb      |
| `%B` | Month full name.                                                 | February |
| `%m` | Month as a zero-padded decimal number.                           | 02       |
| `%Y` | Year with century as a decimal number.                           | 2008     |
| `%y` | Year without century as a zero-padded decimal number.            | 08       |
| `%H` | Hour (24-hour clock) as a zero-padded decimal number.            | 19       |
| `%I` | Hour (12-hour clock) as a zero-padded decimal number.            | 07       |
| `%p` | AM or PM.                                                        | AM       |
| `%M` | Minute as a zero-padded decimal number.                          | 57       |
| `%S` | Second as a zero-padded decimal number.                          | 04       |
| `%f` | Microseconds as a zero-padded decimal number.                    | 000345   |
| `%z` | UTC offset in the form +HHMM or -HHMM.                           | +1300    |
| `%Z` | Time zone name.                                                  | PST      |
| `%j` | Day of the year as a zero-padded decimal number.                 | 363      |

In addition, the following non-`strftime` codes are supported:

| Code | Meaning                                                              | Example |
| ---- | -------------------------------------------------------------------- | ------- |
| `%L` | Milliseconds as a zero-padded decimal number preceded with a period. | .123    |

### [awslogs-multiline-pattern](#awslogs-multiline-pattern)

The `awslogs-multiline-pattern` option defines a multi-line start pattern using a regular expression. A log message consists of a line that matches the pattern and any following lines that don't match the pattern. Thus the matched line is the delimiter between log messages.

This option is ignored if `awslogs-datetime-format` is also configured.

> Note
>
> Multi-line logging performs regular expression parsing and matching of all log messages. This may have a negative impact on logging performance.

Consider the following log stream, where each log message should start with the pattern `INFO`:

```console
INFO A message was logged
INFO Another multi-line message was logged
     Some random message
INFO Another message was logged
```

You can use the regular expression of `^INFO`:

```console
$ docker run \
    --log-driver=awslogs \
    --log-opt awslogs-region=us-east-1 \
    --log-opt awslogs-group=myLogGroup \
    --log-opt awslogs-multiline-pattern='^INFO' \
    ...
```

This parses the logs into the following CloudWatch log events:

```console
# First event
INFO A message was logged

# Second event
INFO Another multi-line message was logged
     Some random message

# Third event
INFO Another message was logged
```

### [tag](#tag)

Specify `tag` as an alternative to the `awslogs-stream` option. `tag` interprets Go template markup, such as `{{.ID}}`, `{{.FullID}}` or `{{.Name}}` `docker.{{.ID}}`. See the [tag option documentation](https://docs.docker.com/engine/logging/log_tags/) for details on supported template substitutions.

When both `awslogs-stream` and `tag` are specified, the value supplied for `awslogs-stream` overrides the template specified with `tag`.

If not specified, the container ID is used as the log stream.

> Note
>
> The CloudWatch log API doesn't support `:` in the log name. This can cause some issues when using the `{{ .ImageName }}` as a tag, since a Docker image has a format of `IMAGE:TAG`, such as `alpine:latest`. Template markup can be used to get the proper format. To get the image name and the first 12 characters of the container ID, you can use:
>
> ```bash
> --log-opt tag='{{ with split .ImageName ":" }}{{join . "_"}}{{end}}-{{.ID}}'
> ```
>
> the output is something like: `alpine_latest-bf0072049c76`

### [awslogs-force-flush-interval-seconds](#awslogs-force-flush-interval-seconds)

The `awslogs` driver periodically flushes logs to CloudWatch.

The `awslogs-force-flush-interval-seconds` option changes log flush interval seconds.

Default is 5 seconds.

### [awslogs-max-buffered-events](#awslogs-max-buffered-events)

The `awslogs` driver buffers logs.

The `awslogs-max-buffered-events` option changes log buffer size.

Default is 4K.

## [Credentials](#credentials)

You must provide AWS credentials to the Docker daemon to use the `awslogs` logging driver. You can provide these credentials with the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables, the default AWS shared credentials file (`~/.aws/credentials` of the root user), or if you are running the Docker daemon on an Amazon EC2 instance, the Amazon EC2 instance profile.

Credentials must have a policy applied that allows the `logs:CreateLogStream` and `logs:PutLogEvents` actions, as shown in the following example.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": ["logs:CreateLogStream", "logs:PutLogEvents"],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}
```

----
url: https://docs.docker.com/reference/cli/docker/container/top/
----

# docker container top

***

| Description                                                               | Display the running processes of a container  |
| ------------------------------------------------------------------------- | --------------------------------------------- |
| Usage                                                                     | `docker container top CONTAINER [ps OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker top`                                  |

## [Description](#description)

Display the running processes of a container

----
url: https://docs.docker.com/dhi/explore/available/
----

# Available types of Docker Hardened Images

***

Table of contents

***

Docker Hardened Images (DHI) is a comprehensive catalog of security-hardened container images built to meet diverse development and production needs.

You can explore the DHI catalog on [Docker Hub](https://hub.docker.com/search?q=\&image_filter=store%2Cdhi) or use the [DHI CLI](https://docs.docker.com/dhi/how-to/cli/) to browse available images, tags, and metadata from the command line.

## [Framework and application images](#framework-and-application-images)

DHI includes a selection of popular frameworks and application images, each hardened and maintained to ensure security and compliance. These images integrate seamlessly into existing workflows, allowing developers to focus on building applications without compromising on security.

For example, you might find repositories like the following in the DHI catalog:

* `node`: framework for Node.js applications
* `python`: framework for Python applications
* `nginx`: web server image

## [Base image distributions](#base-image-distributions)

Docker Hardened Images are available in different base image options, giving you flexibility to choose the best match for your environment and workload requirements:

* Debian-based images: A good fit if you're already working in glibc-based environments. Debian is widely used and offers strong compatibility across many language ecosystems and enterprise systems.

* Alpine-based images: A smaller and more lightweight option using musl libc. These images tend to be small and are therefore faster to pull and have a reduced footprint.

Each image maintains a minimal and secure runtime layer by removing non-essential components like shells, package managers, and debugging tools. This helps reduce the attack surface while retaining compatibility with common runtime environments. To maintain this lean, secure foundation, DHI standardizes on Debian for glibc-based images, which provides broad compatibility while minimizing complexity and maintenance overhead.

Example tags include:

* `3.9.23-alpine3.21`: Alpine-based image for Python 3.9.23
* `3.9.23-debian12`: Debian-based image for Python 3.9.23

If you're not sure which to choose, start with the base you're already familiar with. Debian tends to offer the broadest compatibility.

## [Development and runtime variants](#development-and-runtime-variants)

To accommodate different stages of the application lifecycle, DHI offers all language framework images and select application images in two variants:

* Development (dev) images: Equipped with necessary development tools and libraries, these images facilitate the building and testing of applications in a secure environment. They include a shell, package manager, a root user, and other tools needed for development.

* Runtime images: Stripped of development tools, these images contain only the essential components needed to run applications, ensuring a minimal attack surface in production.

This separation supports multi-stage builds, enabling developers to compile code in a secure build environment and deploy it using a lean runtime image.

For example, you might find tags like the following in a DHI repository:

* `3.9.23-debian12`: runtime image for Python 3.9.23
* `3.9.23-debian12-dev`: development image for Python 3.9.23

## [FIPs and STIG variants](#fips-and-stig-variants)

Subscription: Docker Hardened Images Select or Enterprise

Some Docker Hardened Images include a `-fips` variant. These variants use cryptographic modules that have been validated under [FIPS 140](https://docs.docker.com/dhi/core-concepts/fips/), a U.S. government standard for secure cryptographic operations.

FIPS variants are designed to help organizations meet regulatory and compliance requirements related to cryptographic use in sensitive or regulated environments.

You can recognize FIPS variants by their tag that includes `-fips`.

For example:

* `3.13-fips`: FIPS variant of the Python 3.13 image
* `3.9.23-debian12-fips`: FIPS variant of the Debian-based Python 3.9.23 image

FIPS variants can be used in the same way as any other Docker Hardened Image and are ideal for teams operating in regulated industries or under compliance frameworks that require cryptographic validation.

In addition to FIPS variants, some Docker Hardened Images also include STIG-ready variants. These images are scanned against custom STIG-based profiles and come with signed STIG scan attestations to support audits and compliance reporting. To identify STIG-ready variants, look for the **STIG** in the **Compliance** column of the image tags list in the Docker Hub catalog.

## [Compatibility variants](#compatibility-variants)

Some Docker Hardened Images include a compatibility variant. These variants provide additional tools and configurations for specific use cases without bloating the minimal base images.

Compatibility variants are created to support:

* Helm chart compatibility: Applications deployed via Helm charts and Kubernetes that require specific runtime configurations or utilities for seamless integration with popular Helm charts.

* Special application use-cases: Applications that need optional tools not included in the minimal image.

By offering these as separate image flavors, DHI ensures that the minimal images remain lean and secure, while providing the tools you need in dedicated variants. This approach maintains a minimal attack surface for standard deployments while supporting specialized requirements when needed.

You can recognize compatibility variants by their tag that includes `-compat`.

Use compatibility variants when your deployment requires additional tools beyond the minimal runtime, such as when using Helm charts or applications with specific tooling requirements.

----
url: https://docs.docker.com/reference/api/engine/version/v1.52/
----

# Docker Engine API v1.52 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.52.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.52.yaml)

# Docker Engine API (1.52)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.52.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.52/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.52/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.52/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf",
"Created": "2025-02-17T17:43:39.64001363Z",
"Path": "/bin/sh",
"Args": [
"-c",
"exit 9"
],
"State": {
"Status": "running",
"Running": true,
"Paused": false,
"Restarting": false,
"OOMKilled": false,
"Dead": false,
"Pid": 1234,
"ExitCode": 0,
"Error": "string",
"StartedAt": "2020-01-06T09:06:59.461876391Z",
"FinishedAt": "2020-01-06T09:07:59.461876391Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2020-01-04T10:44:24.496525531Z",
"End": "2020-01-04T10:45:21.364524523Z",
"ExitCode": 0,
"Output": "string"
}
]
}
},
"Image": "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782",
"ResolvConfPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/resolv.conf",
"HostnamePath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hostname",
"HostsPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hosts",
"LogPath": "/var/lib/docker/containers/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59-json.log",
"Name": "/funny_chatelet",
"RestartCount": 0,
"Driver": "overlayfs",
"Platform": "linux",
"ImageManifestDescriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"MountLabel": "",
"ProcessLabel": "",
"AppArmorProfile": "",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"CpuShares": 0,
"Memory": 0,
"CgroupParent": "string",
"BlkioWeight": 1000,
"BlkioWeightDevice": [
{
"Path": "string",
"Weight": 0
}
],
"BlkioDeviceReadBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceReadIOps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteIOps": [
{
"Path": "string",
"Rate": 0
}
],
"CpuPeriod": 0,
"CpuQuota": 0,
"CpuRealtimePeriod": 0,
"CpuRealtimeRuntime": 0,
"CpusetCpus": "0-3",
"CpusetMems": "string",
"Devices": [
{
"PathOnHost": "/dev/deviceName",
"PathInContainer": "/dev/deviceName",
"CgroupPermissions": "mrw"
}
],
"DeviceCgroupRules": [
"c 13:* rwm"
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 100,
"NanoCpus": 0,
"OomKillDisable": true,
"Init": true,
"PidsLimit": 0,
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
],
"CpuCount": 0,
"CpuPercent": 0,
"IOMaximumIOps": 0,
"IOMaximumBandwidth": 0,
"Binds": [
"string"
],
"ContainerIDFile": "",
"LogConfig": {
"Type": "local",
"Config": {
"max-file": "5",
"max-size": "10m"
}
},
"NetworkMode": "string",
"PortBindings": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"VolumeDriver": "string",
"VolumesFrom": [
"string"
],
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"ConsoleSize": [
80,
64
],
"Annotations": {
"property1": "string",
"property2": "string"
},
"CapAdd": [
"string"
],
"CapDrop": [
"string"
],
"CgroupnsMode": "private",
"Dns": [
"string"
],
"DnsOptions": [
"string"
],
"DnsSearch": [
"string"
],
"ExtraHosts": [
"string"
],
"GroupAdd": [
"string"
],
"IpcMode": "string",
"Cgroup": "string",
"Links": [
"string"
],
"OomScoreAdj": 500,
"PidMode": "string",
"Privileged": true,
"PublishAllPorts": true,
"ReadonlyRootfs": true,
"SecurityOpt": [
"string"
],
"StorageOpt": {
"property1": "string",
"property2": "string"
},
"Tmpfs": {
"property1": "string",
"property2": "string"
},
"UTSMode": "string",
"UsernsMode": "string",
"ShmSize": 0,
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Runtime": "string",
"Isolation": "default",
"MaskedPaths": [
"/proc/asound",
"/proc/acpi",
"/proc/kcore",
"/proc/keys",
"/proc/latency_stats",
"/proc/timer_list",
"/proc/timer_stats",
"/proc/sched_debug",
"/proc/scsi",
"/sys/firmware",
"/sys/devices/virtual/powercap"
],
"ReadonlyPaths": [
"/proc/bus",
"/proc/fs",
"/proc/irq",
"/proc/sys",
"/proc/sysrq-trigger"
]
},
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"Storage": {
"RootFS": {
"Snapshot": {
"Name": "string"
}
}
},
"SizeRw": "122880",
"SizeRootFs": "1653948416",
"Mounts": [
{
"Type": "volume",
"Name": "myvolume",
"Source": "/var/lib/docker/volumes/myvolume/_data",
"Destination": "/usr/share/nginx/html/",
"Driver": "local",
"Mode": "z",
"RW": true,
"Propagation": ""
}
],
"Config": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"NetworkSettings": {
"SandboxID": "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3",
"SandboxKey": "/var/run/docker/netns/8ab54b426c38",
"Ports": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"Networks": {
"property1": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
},
"property2": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
}
}
}
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.52/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": {
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
]
},
"Processes": {
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.52/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.52/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.52/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.52/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"name": "boring_wozniak",
"os_type": "linux",
"read": "2025-01-16T13:55:22.165243637Z",
"cpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"memory_stats": {
"usage": 0,
"max_usage": 0,
"stats": {
"active_anon": 1572864,
"active_file": 5115904,
"anon": 1572864,
"anon_thp": 0,
"file": 7626752,
"file_dirty": 0,
"file_mapped": 2723840,
"file_writeback": 0,
"inactive_anon": 0,
"inactive_file": 2510848,
"kernel_stack": 16384,
"pgactivate": 0,
"pgdeactivate": 0,
"pgfault": 2042,
"pglazyfree": 0,
"pglazyfreed": 0,
"pgmajfault": 45,
"pgrefill": 0,
"pgscan": 0,
"pgsteal": 0,
"shmem": 0,
"slab": 1180928,
"slab_reclaimable": 725576,
"slab_unreclaimable": 455352,
"sock": 0,
"thp_collapse_alloc": 0,
"thp_fault_alloc": 1,
"unevictable": 0,
"workingset_activate": 0,
"workingset_nodereclaim": 0,
"workingset_refault": 0
},
"failcnt": 0,
"limit": 8217579520,
"commitbytes": 0,
"commitpeakbytes": 0,
"privateworkingset": 0
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"pids_stats": {
"current": 5,
"limit": "18446744073709551615"
},
"blkio_stats": {
"io_service_bytes_recursive": [
{
"major": 254,
"minor": 0,
"op": "read",
"value": 7593984
},
{
"major": 254,
"minor": 0,
"op": "write",
"value": 100
}
],
"io_serviced_recursive": null,
"io_queue_recursive": null,
"io_service_time_recursive": null,
"io_wait_time_recursive": null,
"io_merged_recursive": null,
"io_time_recursive": null,
"sectors_recursive": null
},
"num_procs": 16,
"storage_stats": {
"read_count_normalized": 7593984,
"read_size_bytes": 7593984,
"write_count_normalized": 7593984,
"write_size_bytes": 7593984
},
"preread": "2025-01-16T13:55:21.160452595Z",
"precpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.52/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.52/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.52/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.52/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.52/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.52/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"Published ports are discarded when using host network mode"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.52/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.52/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.52/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.52/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.52/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.52/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.52/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.52/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.52/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.52/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.52/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |
| manifests   | booleanDefault: falseInclude `Manifests` in the image summary.                                                                                                                                                                                                                                                                                                                                       |

### Responses

/v1.52/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2,
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
}
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.52/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| reserved-space | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| max-used-space | integer \<int64>Maximum amount of disk space allowed to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                   |
| min-free-space | integer \<int64>Target amount of free disk space after pruning                                                                                                                                                                                                                                                                                                                                                                                                           |
| all            | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters        | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.52/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. If the name includes a tag or digest, specific behavior applies:- If only `fromImage` includes a tag, that tag is used.
- If both `fromImage` and `tag` are provided, `tag` takes precedence.
- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.
- If neither a tag nor digest is specified, all tags are pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.52/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| manifests | booleanDefault: falseInclude Manifests in the image summary.The `manifests` and `platform` options are mutually exclusive, and an error is produced if both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show inspect. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.The `platform` and `manifests` options are mutually exclusive, and an error is produced if both are set.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.52/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"Author": "",
"Config": {
"User": "web:web",
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show the history for. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.52/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag      | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed.                                                                                                                                                                                                                                                                                                                   |
| platform | stringJSON-encoded OCI platform to select the platform-variant to push. If not provided, all available variants will attempt to be pushed.If the daemon provides a multi-platform image store, this selects the platform-variant to push to the registry. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.52/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.52/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|           |                                                                                                                                                     |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| force     | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags                                              |
| noprune   | booleanDefault: falseDo not delete untagged parent images                                                                                           |
| platforms | Array of stringsSelect platform-specific content to delete. Multiple values are accepted. Each platform is a OCI platform encoded as a JSON string. |

### Responses

/v1.52/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                   |
| limit        | integerMaximum number of results to return                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.52/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.52/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.52/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | Array of stringsJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.52/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| names    | Array of stringsImage names to filter by                                                                                                                                                                                                                                             |
| platform | Array of stringsJSON encoded OCI platform(s) which will be used to select the platform-specific image(s) to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.52/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| quiet    | booleanDefault: falseSuppress progress details during load.                                                                                                                                                                                                                       |
| platform | Array of stringsJSON encoded OCI platform(s) which will be used to select the platform-specific image(s) to load if the image is multi-platform. If not provided, the full multi-platform image will be loaded.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.52/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.52/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv4": true,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.52/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Services": {
"property1": null,
"property2": null
},
"Status": {
"IPAM": {
"Subnets": {
"172.16.0.0/16": {
"IPsInUse": 3,
"DynamicIPsAvailable": 65533
},
"2001:db8:abcd:0012::0/96": {
"IPsInUse": 5,
"DynamicIPsAvailable": 4294967291
}
}
}
},
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv4": true,
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.52/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|              |                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired | stringThe network's name.                                                                                                                                                                                                              |
| Driver       | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope        | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal     | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable   | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress      | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly   | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|              | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|              | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv4   | booleanEnable IPv4 on the network.                                                                                                                                                                                                     |
| EnableIPv6   | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|              | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|              | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.52/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv4": true,
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|                   |                                                                  |
| ----------------- | ---------------------------------------------------------------- |
| Containerrequired | stringThe ID or name of the container to connect to the network. |
|                   | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.52/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|                   |                                                                          |
| ----------------- | ------------------------------------------------------------------------ |
| Containerrequired | stringThe ID or name of the container to disconnect from the network.    |
| Force             | booleanDefault: falseForce the container to disconnect from the network. |

### Responses

/v1.52/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"Force": false
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.52/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.52/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.52/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.52/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.52/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.52/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.52/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.52/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.52/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.52/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.52/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.52/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.52/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.52/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.52/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.52/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.52/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.52/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.52/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.52/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.52/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.52/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.52/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.52/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"SwapBytes": -1,
"MemorySwappiness": -1
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.52/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.52/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.52/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"SwapBytes": -1,
"MemorySwappiness": -1
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.52/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.52/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.52/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.52/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.52/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.52/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.52/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.52/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.52/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.52/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.52/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.52/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.52/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.52/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.52/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.52/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.52/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.52/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.52/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.52/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.52/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.52/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.52/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.52/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.52/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |        |
| ------------- | ------ |
| username      | string |
| password      | string |
| serveraddress | string |

### Responses

/v1.52/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.52/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "6.8.0-31-generic",
"OperatingSystem": "Ubuntu 24.04 LTS",
"OSVersion": "24.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "27.0.1",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"FirewallBackend": {
"Driver": "nftables",
"Info": [ [
"ReloadedAt",
"2025-01-01T00:00:00Z"
]
]
},
"DiscoveredDevices": [
{
"Source": "cdi",
"ID": "vendor.com/gpu=0"
}
],
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
],
"Containerd": {
"Address": "/run/containerd/containerd.sock",
"Namespaces": {
"Containers": "moby",
"Plugins": "plugins.moby"
}
}
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.52/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "27.0.1",
"Details": { }
}
],
"Version": "27.0.1",
"ApiVersion": "1.47",
"MinAPIVersion": "1.24",
"GitCommit": "48a66213fe",
"GoVersion": "go1.22.7",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "6.8.0-31-generic",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.52/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.52/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.52/events

### Response samples

* 200
* 400
* 500

Content type

application/x-ndjson

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|         |                                                                                                                           |
| ------- | ------------------------------------------------------------------------------------------------------------------------- |
| type    | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |
| verbose | booleanDefault: falseShow detailed information on space usage.                                                            |

### Responses

/v1.52/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"ImageUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
},
"ContainerUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
},
"VolumeUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
},
"BuildCacheUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
}
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.52/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.52/session

----
url: https://docs.docker.com/docker-hub/repos/manage/builds/automated-testing/
----

# Automated repository tests

***

Table of contents

***

> Warning
>
> Docker Hub Automated Builds is a deprecated feature. It will be fully retired on April 1, 2027.

> Note
>
> Automated builds require a Docker Pro, Team, or Business subscription.

Docker Hub can automatically test changes to your source code repositories using containers. You can enable `Autotest` on any Docker Hub repository to run tests on each pull request to the source code repository to create a continuous integration testing service.

Enabling `Autotest` builds an image for testing purposes, but does not automatically push the built image to the Docker repository. If you want to push built images to your Docker Hub repository, enable [Automated Builds](https://docs.docker.com/docker-hub/repos/manage/builds/).

## [Set up automated test files](#set-up-automated-test-files)

To set up your automated tests, create a `docker-compose.test.yml` file which defines a `sut` service that lists the tests to be run. The `docker-compose.test.yml` file should be located in the same directory that contains the Dockerfile used to build the image.

For example:

```yaml
services:
  sut:
    build: .
    command: run_tests.sh
```

The previous example builds the repository, and runs the `run_tests.sh` file inside a container using the built image.

You can define any number of linked services in this file. The only requirement is that `sut` is defined. Its return code determines if tests passed or not. Tests pass if the `sut` service returns `0`, and fail otherwise.

> Note
>
> Only the `sut` service and all other services listed in [`depends_on`](https://docs.docker.com/reference/compose-file/services/#depends_on) are started. If you have services that poll for changes in other services, be sure to include the polling services in the [`depends_on`](https://docs.docker.com/reference/compose-file/services/#depends_on) list to make sure all of your services start.

You can define more than one `docker-compose.test.yml` file if needed. Any file that ends in `.test.yml` is used for testing, and the tests run sequentially. You can also use [custom build hooks](https://docs.docker.com/docker-hub/repos/manage/builds/advanced/#override-build-test-or-push-commands) to further customize your test behavior.

> Note
>
> If you enable automated builds, they also run any tests defined in the `test.yml` files.

## [Enable automated tests on a repository](#enable-automated-tests-on-a-repository)

To enable testing on a source code repository, you must first create an associated build-repository in Docker Hub. Your `Autotest` settings are configured on the same page as [automated builds](https://docs.docker.com/docker-hub/repos/manage/builds/), however you do not need to enable autobuilds to use autotest. Autobuild is enabled per branch or tag, and you do not need to enable it at all.

Only branches that are configured to use autobuild push images to the Docker repository, regardless of the Autotest settings.

1. Sign in to Docker Hub and select **My Hub** > **Repositories**.

2. Select the repository you want to enable `Autotest` on.

3. From the repository view, select the **Builds** tab.

4. Select **Configure automated builds**.

5. Configure the automated build settings as explained in [Automated builds](https://docs.docker.com/docker-hub/repos/manage/builds/).

   At minimum you must configure:

   * The source code repository
   * The build location
   * At least one build rule

6. Choose your **Autotest** option.

   The following options are available:

   * `Off`: No additional test builds. Tests only run if they're configured as part of an automated build.

   * `Internal pull requests`: Run a test build for any pull requests to branches that match a build rule, but only when the pull request comes from the same source repository.

   * `Internal and external pull requests`: Run a test build for any pull requests to branches that match a build rule, including when the pull request originated in an external source repository.

   > Important
   >
   > For security purposes, autotest on external pull requests is limited on public repositories. Private images are not pulled and environment variables defined in Docker Hub are not available. Automated builds continue to work as usual.

7. Select **Save** to save the settings, or select **Save and build** to save and run an initial test.

## [Check your test results](#check-your-test-results)

From the repository's details page, select **Timeline**.

From this tab you can see any pending, in-progress, successful, and failed builds and test runs for the repository.

You can choose any timeline entry to view the logs for each test run.

----
url: https://docs.docker.com/engine/swarm/manage-nodes/
----

# Manage nodes in a swarm

***

Table of contents

***

As part of the swarm management lifecycle, you may need to:

* [List nodes in the swarm](#list-nodes)
* [Inspect an individual node](#inspect-an-individual-node)
* [Update a node](#update-a-node)
* [Leave the swarm](#leave-the-swarm)

## [List nodes](#list-nodes)

To view a list of nodes in the swarm run `docker node ls` from a manager node:

```console
$ docker node ls

ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
46aqrk4e473hjbt745z53cr3t    node-5    Ready   Active        Reachable
61pi3d91s0w3b90ijw3deeb2q    node-4    Ready   Active        Reachable
a5b2m3oghd48m8eu391pefq5u    node-3    Ready   Active
e7p8btxeu3ioshyuj6lxiv6g0    node-2    Ready   Active
ehkv3bcimagdese79dn78otj5 *  node-1    Ready   Active        Leader
```

The `AVAILABILITY` column shows whether or not the scheduler can assign tasks to the node:

* `Active` means that the scheduler can assign tasks to the node.
* `Pause` means the scheduler doesn't assign new tasks to the node, but existing tasks remain running.
* `Drain` means the scheduler doesn't assign new tasks to the node. The scheduler shuts down any existing tasks and schedules them on an available node.

The `MANAGER STATUS` column shows node participation in the Raft consensus:

* No value indicates a worker node that does not participate in swarm management.
* `Leader` means the node is the primary manager node that makes all swarm management and orchestration decisions for the swarm.
* `Reachable` means the node is a manager node participating in the Raft consensus quorum. If the leader node becomes unavailable, the node is eligible for election as the new leader.
* `Unavailable` means the node is a manager that can't communicate with other managers. If a manager node becomes unavailable, you should either join a new manager node to the swarm or promote a worker node to be a manager.

For more information on swarm administration refer to the [Swarm administration guide](https://docs.docker.com/engine/swarm/admin_guide/).

## [Inspect an individual node](#inspect-an-individual-node)

You can run `docker node inspect <NODE-ID>` on a manager node to view the details for an individual node. The output defaults to JSON format, but you can pass the `--pretty` flag to print the results in human-readable format. For example:

```console
$ docker node inspect self --pretty

ID:                     ehkv3bcimagdese79dn78otj5
Hostname:               node-1
Joined at:              2016-06-16 22:52:44.9910662 +0000 utc
Status:
 State:                 Ready
 Availability:          Active
Manager Status:
 Address:               172.17.0.2:2377
 Raft Status:           Reachable
 Leader:                Yes
Platform:
 Operating System:      linux
 Architecture:          x86_64
Resources:
 CPUs:                  2
 Memory:                1.954 GiB
Plugins:
  Network:              overlay, host, bridge, overlay, null
  Volume:               local
Engine Version:         1.12.0-dev
```

## [Update a node](#update-a-node)

You can modify node attributes to:

* [Change node availability](#change-node-availability)
* [Add or remove label metadata](#add-or-remove-label-metadata)
* [Change a node role](#promote-or-demote-a-node)

### [Change node availability](#change-node-availability)

Changing node availability lets you:

* Drain a manager node so that it only performs swarm management tasks and is unavailable for task assignment.
* Drain a node so you can take it down for maintenance.
* Pause a node so it can't receive new tasks.
* Restore unavailable or paused nodes availability status.

For example, to change a manager node to `Drain` availability:

```console
$ docker node update --availability drain node-1

node-1
```

See [list nodes](#list-nodes) for descriptions of the different availability options.

### [Add or remove label metadata](#add-or-remove-label-metadata)

Node labels provide a flexible method of node organization. You can also use node labels in service constraints. Apply constraints when you create a service to limit the nodes where the scheduler assigns tasks for the service.

Run `docker node update --label-add` on a manager node to add label metadata to a node. The `--label-add` flag supports either a `<key>` or a `<key>=<value>` pair.

Pass the `--label-add` flag once for each node label you want to add:

```console
$ docker node update --label-add foo --label-add bar=baz node-1

node-1
```

The labels you set for nodes using `docker node update` apply only to the node entity within the swarm. Do not confuse them with the Docker daemon labels for [dockerd](https://docs.docker.com/engine/manage-resources/labels/).

Therefore, node labels can be used to limit critical tasks to nodes that meet certain requirements. For example, schedule only on machines where special workloads should be run, such as machines that meet [PCI-SS compliance](https://www.pcisecuritystandards.org/).

A compromised worker could not compromise these special workloads because it cannot change node labels.

Engine labels, however, are still useful because some features that do not affect secure orchestration of containers might be better off set in a decentralized manner. For instance, an engine could have a label to indicate that it has a certain type of disk device, which may not be relevant to security directly. These labels are more easily "trusted" by the swarm orchestrator.

Refer to the `docker service create` [CLI reference](/reference/cli/docker/service/create/) for more information about service constraints.

### [Promote or demote a node](#promote-or-demote-a-node)

You can promote a worker node to the manager role. This is useful when a manager node becomes unavailable or if you want to take a manager offline for maintenance. Similarly, you can demote a manager node to the worker role.

> Note
>
> Regardless of your reason to promote or demote a node, you must always maintain a quorum of manager nodes in the swarm. For more information refer to the [Swarm administration guide](https://docs.docker.com/engine/swarm/admin_guide/).

To promote a node or set of nodes, run `docker node promote` from a manager node:

```console
$ docker node promote node-3 node-2

Node node-3 promoted to a manager in the swarm.
Node node-2 promoted to a manager in the swarm.
```

To demote a node or set of nodes, run `docker node demote` from a manager node:

```console
$ docker node demote node-3 node-2

Manager node-3 demoted in the swarm.
Manager node-2 demoted in the swarm.
```

`docker node promote` and `docker node demote` are convenience commands for `docker node update --role manager` and `docker node update --role worker` respectively.

## [Install plugins on swarm nodes](#install-plugins-on-swarm-nodes)

If your swarm service relies on one or more [plugins](/engine/extend/plugin_api/), these plugins need to be available on every node where the service could potentially be deployed. You can manually install the plugin on each node or script the installation. You can also deploy the plugin in a similar way as a global service using the Docker API, by specifying a `PluginSpec` instead of a `ContainerSpec`.

> Note
>
> There is currently no way to deploy a plugin to a swarm using the Docker CLI or Docker Compose. In addition, it is not possible to install plugins from a private repository.

The [`PluginSpec`](/engine/extend/plugin_api/#json-specification) is defined by the plugin developer. To add the plugin to all Docker nodes, use the [`service/create`](/reference/api/engine/v1.31/#operation/ServiceCreate) API, passing the `PluginSpec` JSON defined in the `TaskTemplate`.

## [Leave the swarm](#leave-the-swarm)

Run the `docker swarm leave` command on a node to remove it from the swarm.

For example to leave the swarm on a worker node:

```console
$ docker swarm leave

Node left the swarm.
```

When a node leaves the swarm, Docker Engine stops running in Swarm mode. The orchestrator no longer schedules tasks to the node.

If the node is a manager node, you receive a warning about maintaining the quorum. To override the warning, pass the `--force` flag. If the last manager node leaves the swarm, the swarm becomes unavailable requiring you to take disaster recovery measures.

For information about maintaining a quorum and disaster recovery, refer to the [Swarm administration guide](https://docs.docker.com/engine/swarm/admin_guide/).

After a node leaves the swarm, you can run `docker node rm` on a manager node to remove the node from the node list.

For instance:

```console
$ docker node rm node-2
```

## [Learn more](#learn-more)

* [Swarm administration guide](https://docs.docker.com/engine/swarm/admin_guide/)
* [Docker Engine command line reference](/reference/cli/docker/)
* [Swarm mode tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/)

----
url: https://docs.docker.com/guides/r/configure-ci-cd/
----

# Configure CI/CD for your R application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a R application](https://docs.docker.com/guides/r/containerize/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

   ```console
   $ git remote set-url origin https://github.com/your-username/your-repository.git
   ```

7. Run the following commands to stage, commit, and push your local repository to GitHub.

   ```console
   $ git add -A
   $ git commit -m "my commit"
   $ git push -u origin main
   ```

## [Step two: Set up the workflow](#step-two-set-up-the-workflow)

Set up your GitHub Actions workflow for building, testing, and pushing the image to Docker Hub.

1. Go to your repository on GitHub and then select the **Actions** tab.

2. Select **set up a workflow yourself**.

   This takes you to a page for creating a new GitHub actions workflow file in your repository, under `.github/workflows/main.yml` by default.

3. In the editor window, copy and paste the following YAML configuration.

   ```yaml
   name: ci

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Login to Docker Hub
           uses: docker/login-action@v4
           with:
             username: ${{ vars.DOCKER_USERNAME }}
             password: ${{ secrets.DOCKERHUB_TOKEN }}

         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v4

         - name: Build and push
           uses: docker/build-push-action@v7
           with:
             platforms: linux/amd64,linux/arm64
             push: true
             tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
   ```

In this section, you learned how to set up a GitHub Actions workflow for your R application.

Related information:

* [Introduction to GitHub Actions](https://docs.docker.com/guides/gha/)
* [Docker Build GitHub Actions](https://docs.docker.com/build/ci/github-actions/)
* [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)

## [Next steps](#next-steps)

Next, learn how you can locally test and debug your workloads on Kubernetes before deploying.

[Test your R deployment »](https://docs.docker.com/guides/r/deploy/)

----
url: https://docs.docker.com/guides/lab-building-images/
----

[Lab: Building Container Images](https://docs.docker.com/guides/lab-building-images/)

Hands-on lab: Transform a basic Dockerfile into a production-ready image. Master layer caching, multi-stage builds, .dockerignore, non-root users, base image selection, and build secrets.

Labs

45 minutes

Resources:

* [Dockerfile reference](/reference/dockerfile/)
* [Multi-stage builds](/build/building/multi-stage/)
* [Build secrets](/build/building/secrets/)
* [Labspace repository](https://github.com/dockersamples/labspace-building-images)

[« Back to all guides](/guides/)

# Lab: Building Container Images

***

Table of contents

***

Take a working but naïve Dockerfile and progressively improve it into a production-grade image. Each section introduces one technique, applied to a real Python Flask app, so you can see the impact directly.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-building-images up -d
   ```

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

By the end of this Labspace, you will have completed the following:

* Read an image's layer history and understand the layer cleanup pitfall
* Restructure a Dockerfile for fast, cache-efficient incremental builds
* Write a `.dockerignore` file and run containers as a non-root user
* Use multi-stage builds to run tests as a build gate and dramatically reduce image size
* Choose the right base image for production, including Docker Hardened Images
* Inject secrets safely at build time using `--mount=type=secret`

## [Modules](#modules)

| # | Module                     | Description                                                            |
| - | -------------------------- | ---------------------------------------------------------------------- |
| 1 | Welcome & Your First Build | Explore the sample app and build the initial image                     |
| 2 | Understanding Image Layers | Inspect layers with `docker history` and see the layer cleanup pitfall |
| 3 | Dockerfile Best Practices  | Fix cache ordering, add `.dockerignore`, and switch to a non-root user |
| 4 | Multi-Stage Builds         | Run tests as a build gate and use a slim base for the production stage |
| 5 | Choosing a Base Image      | Compare slim, Alpine, and Docker Hardened Images                       |
| 6 | Build Secrets              | Show why `ARG` leaks secrets and use `--mount=type=secret` safely      |
| 7 | Wrap-up                    | Review the complete best-practices checklist and next steps            |

----
url: https://docs.docker.com/extensions/private-marketplace/
----

# Configure a private marketplace for extensions

***

Table of contents

***

Availability: Beta

For: Administrators

Learn how to configure and set up a private marketplace with a curated list of extensions for your Docker Desktop users.

Docker Extensions' private marketplace is designed specifically for organizations who don’t give developers root access to their machines. It makes use of [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) so administrators have complete control over the private marketplace.

## [Prerequisites](#prerequisites)

* [Download and install Docker Desktop](https://docs.docker.com/desktop/release-notes/).
* You must be an administrator for your organization.
* You have the ability to push the `extension-marketplace` folder and `admin-settings.json` file to the locations specified below through device management software such as [Jamf](https://www.jamf.com/).

## [Step one: Initialize the private marketplace](#step-one-initialize-the-private-marketplace)

1. Create a folder locally for the content that will be deployed to your developers’ machines:

   ```console
   $ mkdir my-marketplace
   $ cd my-marketplace
   ```

2. Initialize the configuration files for your marketplace:

   ```console
   $ /Applications/Docker.app/Contents/Resources/bin/extension-admin init
   ```

   ```console
   # For all-user installations
   $ C:\Program Files\Docker\Docker\resources\bin\extension-admin init

   # For per-user installations
   $ %LOCALAPPDATA%\Programs\DockerDesktop\resources\bin\extension-admin init
   ```

   ```console
   $ /opt/docker-desktop/extension-admin init
   ```

This creates 2 files:

* `admin-settings.json`, which activates the private marketplace feature once it’s applied to Docker Desktop on your developers’ machines.
* `extensions.txt`, which determines which extensions to list in your private marketplace.

> Important
>
> If your org is using [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) via the [Admin Console](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/), you will not need the `admins-settings.json` file. Delete the generated file and keep only the `extensions.txt` file.

## [Step two: Set the behaviour](#step-two-set-the-behaviour)

The generated `admin-settings.json` file includes various settings you can modify.

> Important
>
> If your org is managing settings via the [Admin Console](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/), you will define the same settings in the Admin Console instead of the `admin-settings.json` file.

Each setting has a `value` that you can set, including a `locked` field that lets you lock the setting and make it unchangeable by your developers.

* `extensionsEnabled` enables Docker Extensions.

* `extensionsPrivateMarketplace` activates the private marketplace and ensures Docker Desktop connects to content defined and controlled by the administrator instead of the public Docker marketplace.

* `onlyMarketplaceExtensions` allows or blocks developers from installing other extensions by using the command line. Teams developing new extensions must have this setting unlocked (`"locked": false`) to install and test extensions being developed.

* `extensionsPrivateMarketplaceAdminContactURL` defines a contact link for developers to request new extensions in the private marketplace. If `value` is empty then no link is shown to your developers on Docker Desktop, otherwise this can be either an HTTP link or a “mailto:” link. For example,

  ```json
  "extensionsPrivateMarketplaceAdminContactURL": {
    "locked": true,
    "value": "mailto:admin@acme.com"
  }
  ```

To find out more information about the `admin-settings.json` file, see [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/).

## [Step three: List allowed extensions](#step-three-list-allowed-extensions)

The generated `extensions.txt` file defines the list of extensions that are available in your private marketplace.

Each line in the file is an allowed extension and follows the format of `org/repo:tag`.

For example, if you want to permit the Disk Usage extension you would enter the following into your `extensions.txt` file:

```console
docker/disk-usage-extension:0.2.8
```

If no tag is provided, the latest tag available for the image is used. You can also comment out lines with `#` so the extension is ignored.

This list can include different types of extension images:

* Extensions from the public marketplace or any public image stored in Docker Hub.
* Extension images stored in Docker Hub as private images. Developers need to be signed in and have pull access to these images.
* Extension images stored in a private registry. Developers need to be signed in and have pull access to these images.

> Important
>
> Your developers can only install the version of the extension that you’ve listed.

## [Step four: Generate the private marketplace](#step-four-generate-the-private-marketplace)

Once the list in `extensions.txt` is ready, you can generate the marketplace:

```console
$ /Applications/Docker.app/Contents/Resources/bin/extension-admin generate
```

```console
# For all-user installations
$ C:\Program Files\Docker\Docker\resources\bin\extension-admin generate

# For per-user installations
$ %LOCALAPPDATA%\Programs\DockerDesktop\resources\bin\extension-admin generate
```

```console
$ /opt/docker-desktop/extension-admin generate
```

This creates an `extension-marketplace` directory and downloads the marketplace metadata for all the allowed extensions.

The marketplace content is generated from extension image information as image labels, which is the [same format as public extensions](https://docs.docker.com/extensions/extensions-sdk/extensions/labels/). It includes the extension title, description, screenshots, links, etc.

## [Step five: Test the private marketplace setup](#step-five-test-the-private-marketplace-setup)

It's recommended that you try the private marketplace on your Docker Desktop installation.

1. Run the following command in your terminal. This command automatically copies the generated files to the location where Docker Desktop reads the configuration files. Depending on your operating system, the location is:

   * Mac: `/Library/Application\ Support/com.docker.docker`
   * Windows: `C:\ProgramData\DockerDesktop`
   * Linux: `/usr/share/docker-desktop`

   ```console
   $ sudo /Applications/Docker.app/Contents/Resources/bin/extension-admin apply
   ```

   ```console
   # For all-user installations
   $ C:\Program Files\Docker\Docker\resources\bin\extension-admin apply

   # For per-user installations
   $ %LOCALAPPDATA%\Programs\DockerDesktop\resources\bin\extension-admin apply
   ```

   ```console
   $ sudo /opt/docker-desktop/extension-admin apply
   ```

2. Quit and re-open Docker Desktop.

3. Sign in with a Docker account.

> Important
>
> > If your org is managing settings via the [Admin Console](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/), in Docker Desktop 4.59 and earlier, you must manually delete the `admin-settings.json` file created in the target folder by the `apply` command before step 2. In Docker Desktop 4.60 and later, this step is no longer necessary.

When you select the **Extensions** tab, you should see the private marketplace listing only the extensions you have allowed in `extensions.txt`.

## [Step six: Distribute the private marketplace](#step-six-distribute-the-private-marketplace)

Once you’ve confirmed that the private marketplace configuration works, the final step is to distribute the files to the developers’ machines with the MDM software your organization uses. For example, [Jamf](https://www.jamf.com/).

The files to distribute are:

* `admin-settings.json` (except if your org is managing settings via the [Admin Console](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/))
* the entire `extension-marketplace` folder and its subfolders

These files must be placed on developer's machines. Depending on your operating system, the target location is (as mentioned above):

* Mac: `/Library/Application\ Support/com.docker.docker`
* Windows: `C:\ProgramData\DockerDesktop`
* Linux: `/usr/share/docker-desktop`

Make sure your developers are signed in to Docker Desktop in order for the private marketplace configuration to take effect. As an administrator, you should [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).

## [Feedback](#feedback)

Give feedback or report any bugs you may find by emailing `extensions@docker.com`.

----
url: https://docs.docker.com/scout/integrations/
----

# Integrating Docker Scout with other systems

***

Table of contents

***

By default, Docker Scout integrates with your Docker organization and your Docker Scout-enabled repositories on Docker Hub. You can integrate Docker Scout with additional third-party systems to get access to even more insights, including real-time information about you running workloads.

## [Integration categories](#integration-categories)

You'll get different insights depending on where and how you choose to integrate Docker Scout.

### [Container registries](#container-registries)

Integrating Docker Scout with third-party container registries enables Docker Scout to run image analysis on those repositories, so that you can get insights into the composition of those images even if they aren't hosted on Docker Hub.

The following container registry integrations are available:

* [Amazon Elastic Container Registry](https://docs.docker.com/scout/integrations/registry/ecr/)
* [Azure Container Registry](https://docs.docker.com/scout/integrations/registry/acr/)
* [JFrog Artifactory](https://docs.docker.com/scout/integrations/registry/artifactory/)

### [Continuous Integration](#continuous-integration)

Integrating Docker Scout with Continuous Integration (CI) systems is a great way to get instant, automatic feedback about your security posture in your inner loop. Analysis running in CI also gets the benefit of additional context that's useful for getting even more insights.

The following CI integrations are available:

* [GitHub Actions](https://docs.docker.com/scout/integrations/ci/gha/)
* [GitLab](https://docs.docker.com/scout/integrations/ci/gitlab/)
* [Microsoft Azure DevOps Pipelines](https://docs.docker.com/scout/integrations/ci/azure/)
* [Circle CI](https://docs.docker.com/scout/integrations/ci/circle-ci/)
* [Jenkins](https://docs.docker.com/scout/integrations/ci/jenkins/)

### [Environment monitoring](#environment-monitoring)

Environment monitoring refers to integrating Docker Scout with your deployments. This can give you information in real-time about your running container workloads.

Integrating with environments lets you compare production workloads to other versions, in your image repositories or in your other environments.

The following environment monitoring integrations are available

* [Sysdig](https://docs.docker.com/scout/integrations/environment/sysdig/)

For more information about environment integrations, see [Environments](https://docs.docker.com/scout/integrations/environment/).

### [Code quality](#code-quality)

Integrating Docker Scout with code analysis tools enables quality checks directly on source code, helping you keep track of bugs, security issues, test coverage, and more. In addition to image analysis and environment monitoring, code quality gates let you shift left your supply chain management with Docker Scout.

Once you enable a code quality integration, Docker Scout includes the code quality assessments as policy evaluation results for the repositories where you've enabled the integration.

The following code quality integrations are available:

* [SonarQube](https://docs.docker.com/scout/integrations/code-quality/sonarqube/)

### [Source code management](#source-code-management)

Integrate Docker Scout with your version control system to get guided remediation advice on how to address issues detected by Docker Scout image analysis, directly in your repositories.

The following source code management integrations are available:

* [GitHub](https://docs.docker.com/scout/integrations/source-code-management/github/) Beta

### [Team collaboration](#team-collaboration)

Integrations in this category let you integrate Docker Scout with collaboration platforms for broadcasting notifications about your software supply chain in real-time to team communication platforms.

The following team collaboration integrations are available:

* [Slack](https://docs.docker.com/scout/integrations/team-collaboration/slack/)

----
url: https://docs.docker.com/reference/cli/docker/desktop/disable/
----

# docker desktop disable

***

| Description | Disable a feature |
| ----------- | ----------------- |

## [Description](#description)

Disable an individual feature

## [Subcommands](#subcommands)

| Command                                                                                                             | Description                 |
| ------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| [`docker desktop disable model-runner`](https://docs.docker.com/reference/cli/docker/desktop/disable/model-runner/) | Disable Docker Model Runner |

----
url: https://docs.docker.com/guides/genai-pdf-bot/
----

# PDF analysis and chat

***

Learn how to build a PDF bot for parsing PDF documents and generating responses using Docker and generative AI.

**Time to complete** 20 minutes

The generative AI (GenAI) guide teaches you how to containerize an existing GenAI application using Docker. In this guide, you’ll learn how to:

* Containerize and run a Python-based GenAI application
* Set up a local environment to run the complete GenAI stack locally for development

Start by containerizing an existing GenAI application.

## [Modules](#modules)

1. [Containerize your app](https://docs.docker.com/guides/genai-pdf-bot/containerize/)

   Learn how to containerize a generative AI (GenAI) application.

2. [Develop your app](https://docs.docker.com/guides/genai-pdf-bot/develop/)

   Learn how to develop your generative AI (GenAI) application locally.

----
url: https://docs.docker.com/reference/cli/docker/buildx/prune/
----

# docker buildx prune

***

| Description | Remove build cache    |
| ----------- | --------------------- |
| Usage       | `docker buildx prune` |

## [Description](#description)

Clears the build cache of the selected builder.

## [Options](#options)

| Option                                | Default | Description                                             |
| ------------------------------------- | ------- | ------------------------------------------------------- |
| [`-a, --all`](#all)                   |         | Include internal/frontend images                        |
| [`--filter`](#filter)                 |         | Provide filter values                                   |
| `-f, --force`                         |         | Do not prompt for confirmation                          |
| [`--max-used-space`](#max-used-space) |         | Maximum amount of disk space allowed to keep for cache  |
| [`--min-free-space`](#min-free-space) |         | Target amount of free disk space after pruning          |
| [`--reserved-space`](#reserved-space) |         | Amount of disk space always allowed to keep for cache   |
| `--timeout`                           | `20s`   | Override the default timeout for loading builder status |
| `--verbose`                           |         | Provide a more verbose output                           |

## [Examples](#examples)

### [Include internal/frontend images (--all)](#all)

The `--all` flag to allow clearing internal helper images and frontend images set using the `#syntax=` directive or the `BUILDKIT_SYNTAX` build argument.

### [Provide filter values (--filter)](#filter)

You can finely control which cache records to delete using the `--filter` flag.

The filter format is in the form of `<key><op><value>`, known as selectors. All selectors must match the target object for the filter to be true. We define the operators `=` for equality, `!=` for not equal and `~=` for a regular expression.

Valid filter keys are:

* `until` flag to keep records that have been used in the last duration time. Value is a duration string, e.g. `24h` or `2h30m`, with allowable units of `(h)ours`, `(m)inutes` and `(s)econds`.

* `id` flag to target a specific image ID.

* `parents` flag to target records that are parents of the specified image ID. Multiple parent IDs are separated by a semicolon (`;`).

* `description` flag to target records whose description is the specified substring.

* `inuse` flag to target records that are actively in use and therefore not reclaimable.

* `mutable` flag to target records that are mutable.

* `immutable` flag to target records that are immutable.

* `shared` flag to target records that are shared with other resources, typically images.

* `private` flag to target records that are not shared.

* `type` flag to target records by type. Valid types are:

  * `internal`
  * `frontend`
  * `source.local`
  * `source.git.checkout`
  * `exec.cachemount`
  * `regular`

Examples:

```console
docker buildx prune --filter "until=24h"
docker buildx prune --filter "description~=golang"
docker buildx prune --filter "parents=dpetmoi6n0yqanxjqrbnofz9n;kgoj0q6g57i35gdyrv546alz7"
docker buildx prune --filter "type=source.local"
docker buildx prune --filter "type!=exec.cachemount"
```

> Note
>
> Multiple `--filter` flags are ANDed together.

### [Maximum amount of disk space allowed to keep for cache (--max-used-space)](#max-used-space)

The `--max-used-space` flag allows setting a maximum amount of disk space that the build cache can use. If the cache is using more disk space than this value, the least recently used cache records are deleted until the total used space is less than or equal to the specified value.

The value is specified in bytes. You can use a human-readable memory string, e.g. `128mb`, `2gb`, etc. Units are case-insensitive.

### [Target amount of free disk space after pruning (--min-free-space)](#min-free-space)

The `--min-free-space` flag allows setting a target amount of free disk space that should be available after pruning. If the available disk space is less than this value, the least recently used cache records are deleted until the available free space is greater than or equal to the specified value.

The value is specified in bytes. You can use a human-readable memory string, e.g. `128mb`, `2gb`, etc. Units are case-insensitive.

### [Amount of disk space always allowed to keep for cache (--reserved-space)](#reserved-space)

The `--reserved-space` flag allows setting an amount of disk space that should always be kept for the build cache. If the available disk space is less than this value, the least recently used cache records are deleted until the available free space is greater than or equal to the specified value.

The value is specified in bytes. You can use a human-readable memory string, e.g. `128mb`, `2gb`, etc. Units are case-insensitive.

### [Override the configured builder instance (--builder)](#builder)

Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

----
url: https://docs.docker.com/extensions/extensions-sdk/extensions/publish/
----

# Publish in the Marketplace

***

Table of contents

***

## [Submit your extension to the Marketplace](#submit-your-extension-to-the-marketplace)

Docker Desktop displays published extensions in the Extensions Marketplace on [Docker Desktop](https://open.docker.com/extensions/marketplace) and [Docker Hub](https://hub.docker.com/search?q=\&type=extension). The Extensions Marketplace is a space where developers can discover extensions to improve their developer experience and propose their own extension to be available for all Desktop users.

Whenever you are [ready to publish](https://docs.docker.com/extensions/extensions-sdk/extensions/DISTRIBUTION/) your extension in the Marketplace, you can [self-publish your extension](https://github.com/docker/extensions-submissions/issues/new?assignees=\&labels=\&template=1_automatic_review.yaml\&title=%5BSubmission%5D%3A+)

> Note
>
> As the Extension Marketplace continues to add new features for both Extension users and publishers, you are expected to maintain your extension over time to ensure it stays available in the Marketplace.

> Important
>
> The Docker manual review process for extensions is paused at the moment. Submit your extension through the [automated submission process](https://github.com/docker/extensions-submissions/issues/new?assignees=\&labels=\&template=1_automatic_review.yaml\&title=%5BSubmission%5D%3A+)

### [Before you submit](#before-you-submit)

Before you submit your extension, it must pass the [validation](https://docs.docker.com/extensions/extensions-sdk/extensions/validate/) checks.

It is highly recommended that your extension follows the guidelines outlined in this section before submitting your extension. If you request a review from the Docker Extensions team and have not followed the guidelines, the review process may take longer.

These guidelines don't replace Docker's terms of service or guarantee approval:

* Review the [design guidelines](https://docs.docker.com/extensions/extensions-sdk/design/design-guidelines/)
* Ensure the [UI styling](https://docs.docker.com/extensions/extensions-sdk/design/) is in line with Docker Desktop guidelines
* Ensure your extensions support both light and dark mode
* Consider the needs of both new and existing users of your extension
* Test your extension with potential users
* Test your extension for crashes, bugs, and performance issues
* Test your extension on various platforms (Mac, Windows, Linux)
* Read the [Terms of Service](https://www.docker.com/legal/extensions_marketplace_developer_agreement/)

#### [Validation process](#validation-process)

Submitted extensions go through an automated validation process. If all the validation checks pass successfully, the extension is published on the Marketplace and accessible to all users within a few hours. It is the fastest way to get developers the tools they need and to get feedback from them as you work to evolve/polish your extension.

> Important
>
> Docker Desktop caches the list of extensions available in the Marketplace for 12 hours. If you don't see your extension in the Marketplace, you can restart Docker Desktop to force the cache to refresh.

----
url: https://docs.docker.com/reference/cli/docker/manifest/create/
----

# docker manifest create

***

| Description | Create a local manifest list for annotating and pushing to a registry |
| ----------- | --------------------------------------------------------------------- |
| Usage       | `docker manifest create MANIFEST_LIST MANIFEST [MANIFEST...]`         |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Create a local manifest list for annotating and pushing to a registry

## [Options](#options)

| Option        | Default | Description                                   |
| ------------- | ------- | --------------------------------------------- |
| `-a, --amend` |         | Amend an existing manifest list               |
| `--insecure`  |         | Allow communication with an insecure registry |

----
url: https://docs.docker.com/reference/samples/dotnet/
----

# .NET samples

| Name                                                                                                | Description                                                                        |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [ASP.NET / MS-SQL](https://github.com/docker/awesome-compose/tree/master/aspnet-mssql)              | A sample ASP.NET core application with MS SQL server database.                     |
| [NGINX / ASP.NET / MySQL](https://github.com/docker/awesome-compose/tree/master/nginx-aspnet-mysql) | A sample Nginx reverse proxy with a C# backend using ASP.NET.                      |
| [example-voting-app](https://github.com/dockersamples/example-voting-app)                           | A sample Docker Compose app.                                                       |
| [dotnet-album-viewer](https://github.com/dockersamples/dotnet-album-viewer)                         | West Wind Album Viewer ASP.NET Core and Angular sample.                            |
| [aspnet-monitoring](https://github.com/dockersamples/aspnet-monitoring)                             | Monitoring ASP.NET Fx applications in Windows Docker containers, using Prometheus. |

----
url: https://docs.docker.com/reference/cli/sbx/create/shell/
----

# sbx create shell

| Description | Create a sandbox for shell                |
| ----------- | ----------------------------------------- |
| Usage       | `sbx create shell PATH [PATH...] [flags]` |

## [Description](#description)

Create a sandbox with access to a host workspace for shell.

The workspace path is required and will be mounted inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Global options](#global-options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `-D, --debug`    |         | Enable debug logging                                                                                                                                                                                                   |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Examples](#examples)

```console
# Create in the current directory
sbx create shell .

# Create with a specific path
sbx create shell /path/to/project

# Create with additional read-only workspaces
sbx create shell . /path/to/docs:ro
```

----
url: https://docs.docker.com/guides/claude-code-model-runner/
----

[Use Claude Code with Docker Model Runner](https://docs.docker.com/guides/claude-code-model-runner/)

Connect Claude Code to Docker Model Runner with the Anthropic-compatible API, package `gpt-oss` with a larger context window, and inspect requests.

AI

10 minutes

[« Back to all guides](/guides/)

# Use Claude Code with Docker Model Runner

***

Table of contents

***

This guide shows how to run Claude Code with Docker Model Runner as the backend model provider. You'll point Claude Code at the local Anthropic-compatible API, run a coding model, and package `gpt-oss` with a larger context window for longer repository prompts.

> **Acknowledgment**
>
> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide.

In this guide, you'll learn how to:

* Pull a coding model and start Claude Code with Docker Model Runner
* Make the endpoint configuration persistent
* Verify the local API endpoint and inspect requests
* Package `gpt-oss` with a larger context window for longer prompts

## [Prerequisites](#prerequisites)

Before you start, make sure you have:

* [Docker Desktop](https://docs.docker.com/get-started/get-docker/) or Docker Engine installed
* [Docker Model Runner enabled](https://docs.docker.com/ai/model-runner/get-started/#enable-docker-model-runner)
* [Claude Code installed](https://code.claude.com/docs/en/quickstart)

If you use Docker Desktop, turn on TCP access in **Settings** > **AI**, or run:

```console
$ docker desktop enable model-runner --tcp 12434
```

## [Step 1: Pull a coding model](#step-1-pull-a-coding-model)

Pull a model before you start Claude Code:

```console
$ docker model pull ai/devstral-small-2
```

You can also use `ai/qwen3-coder` if you want another coding-focused model with a large context window.

## [Step 2: Start Claude Code with Docker Model Runner](#step-2-start-claude-code-with-docker-model-runner)

Set `ANTHROPIC_BASE_URL` to your local Docker Model Runner endpoint when you run Claude Code.

On macOS or Linux:

```console
$ ANTHROPIC_BASE_URL=http://localhost:12434 claude --model ai/devstral-small-2
```

On Windows PowerShell:

```powershell
$env:ANTHROPIC_BASE_URL="http://localhost:12434"
claude --model ai/devstral-small-2
```

Claude Code now sends requests to Docker Model Runner instead of Anthropic's hosted API.

## [Step 3: Troubleshoot your first launch](#step-3-troubleshoot-your-first-launch)

If Claude Code can't connect, check Docker Model Runner status:

```console
$ docker model status
```

If Claude Code can't find the model, list local models:

```console
$ docker model ls
```

If the model is missing, pull it first. If needed, use the fully qualified model name, such as `ai/devstral-small-2`.

## [Step 4: Make the endpoint persistent](#step-4-make-the-endpoint-persistent)

To avoid setting the environment variable each time, add it to your shell profile:

\~/.bashrc or \~/.zshrc

```bash
export ANTHROPIC_BASE_URL=http://localhost:12434
```

On Windows PowerShell, add it to your PowerShell profile:

$PROFILE

```powershell
$env:ANTHROPIC_BASE_URL = "http://localhost:12434"
```

After you reload your shell, you can run Claude Code with only the model flag:

```console
$ claude --model ai/devstral-small-2
```

## [Step 5: Verify the API endpoint](#step-5-verify-the-api-endpoint)

Send a test request to confirm the Anthropic-compatible API is reachable:

```console
$ curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/devstral-small-2",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "Say hello"}]
  }'
```

For more details about the request format, see the [Anthropic-compatible API reference](https://docs.docker.com/ai/model-runner/api-reference/#anthropic-compatible-api).

## [Step 6: Inspect Claude Code requests](#step-6-inspect-claude-code-requests)

To inspect the requests Claude Code sends to Docker Model Runner, run:

```console
$ docker model requests --model ai/devstral-small-2 | jq .
```

This helps you debug prompts, context usage, and compatibility issues.

## [Step 7: Package `gpt-oss` with a larger context window](#step-7-package-gpt-oss-with-a-larger-context-window)

`ai/gpt-oss` defaults to a smaller context window than coding-focused models. If you want to use it for repository-scale prompts, package a larger variant:

```console
$ docker model pull ai/gpt-oss
$ docker model package --from ai/gpt-oss --context-size 32000 gpt-oss:32k
```

Then run Claude Code with the packaged model:

```console
$ ANTHROPIC_BASE_URL=http://localhost:12434 claude --model gpt-oss:32k
```

## [Learn more](#learn-more)

* [Docker Model Runner overview](https://docs.docker.com/ai/model-runner/)
* [Docker Model Runner API reference](https://docs.docker.com/ai/model-runner/api-reference/)
* [IDE and tool integrations](https://docs.docker.com/ai/model-runner/ide-integrations/)

----
url: https://docs.docker.com/guides/bun/containerize/
----

# Containerize a Bun application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Overview](#overview)

For a long time, Node.js has been the de-facto runtime for server-side JavaScript applications. Recent years have seen a rise in new alternative runtimes in the ecosystem, including [Bun website](https://bun.sh/). Like Node.js, Bun is a JavaScript runtime. Bun is a comparatively lightweight runtime that is designed to be fast and efficient.

Why develop Bun applications with Docker? Having multiple runtimes to choose from is great. But as the number of runtimes increases, it becomes challenging to manage the different runtimes and their dependencies consistently across environments. This is where Docker comes in. Creating and destroying containers on demand is a great way to manage the different runtimes and their dependencies. Also, as it's fairly a new runtime, getting a consistent development environment for Bun can be challenging. Docker can help you set up a consistent development environment for Bun.

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/dockersamples/bun-docker.git && cd bun-docker
```

You should now have the following contents in your `bun-docker` directory.

```text
├── bun-docker/
│ ├── compose.yml
│ ├── Dockerfile
│ ├── LICENSE
│ ├── server.js
│ └── README.md
```

## [Create a Dockerfile](#create-a-dockerfile)

Before creating a Dockerfile, you need to choose a base image. You can either use the [Bun Docker Official Image](https://hub.docker.com/r/oven/bun) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog).

Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/).

Docker Hardened Images (DHIs) are available for Bun in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/bun). You can pull DHIs directly from the `dhi.io` registry.

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Pull the Bun DHI as `dhi.io/bun:1`. The tag (`1`) in this example refers to the version to the latest 1.x version of Bun.

   ```console
   $ docker pull dhi.io/bun:1
   ```

For other available versions, refer to the [catalog](https://hub.docker.com/hardened-images/catalog/dhi/bun).

```dockerfile
# Use the DHI Bun image as the base image
FROM dhi.io/bun:1

# Set the working directory in the container
WORKDIR /app

# Copy the current directory contents into the container at /app
COPY . .

# Expose the port on which the API will listen
EXPOSE 3000

# Run the server when the container launches
CMD ["bun", "server.js"]
```

Using the Docker Official Image is straightforward. In the following Dockerfile, you'll notice that the `FROM` instruction uses `oven/bun` as the base image.

You can find the image on [Docker Hub](https://hub.docker.com/r/oven/bun). This is the Docker Official Image for Bun created by Oven, the company behind Bun, and it's available on Docker Hub.

```dockerfile
# Use the official Bun image
FROM oven/bun:latest

# Set the working directory in the container
WORKDIR /app

# Copy the current directory contents into the container at /app
COPY . .

# Expose the port on which the API will listen
EXPOSE 3000

# Run the server when the container launches
CMD ["bun", "server.js"]
```

In addition to specifying the base image, the Dockerfile also:

* Sets the working directory in the container to `/app`.
* Copies the content of the current directory to the `/app` directory in the container.
* Exposes port 3000, where the API is listening for requests.
* And finally, starts the server when the container launches with the command `bun server.js`.

## [Run the application](#run-the-application)

Inside the `bun-docker` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:3000>. You will see a message `{"Status" : "OK"}` in the browser.

In the terminal, press `ctrl`+`c` to stop the application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `bun-docker` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:3000>.

In the terminal, run the following command to stop the application.

```console
$ docker compose down
```

## [Summary](#summary)

In this section, you learned how you can containerize and run your Bun application using Docker.

[Use containers for Bun development »](https://docs.docker.com/guides/bun/develop/)

----
url: https://docs.docker.com/desktop/features/wsl/custom-kernels/
----

# Custom kernels on WSL

***

Table of contents

***

> Warning
>
> Using a custom kernel with Docker Desktop on WSL 2 is not officially supported and may cause issues with Docker Desktop startup or operation.

Docker Desktop depends on several kernel features built into the default WSL 2 Linux kernel distributed by Microsoft.

However, in some cases it may be necessary to run custom kernels; Docker Desktop does not block their use, and some users have reported success using them.

## [Recommendations if you must use a custom kernel](#recommendations-if-you-must-use-a-custom-kernel)

If you choose to use a custom kernel, start from the kernel tree distributed by Microsoft from their [official repository](https://github.com/microsoft/WSL2-Linux-Kernel) and then add the features you need on top of that.

Also:

* Use the same kernel version as the one distributed by the latest WSL2 release. You can find the version by running `wsl.exe --system uname -r` in a terminal.
* Make sure that your kernel build environment includes `pahole` and its version is properly reflected in the corresponding kernel config (`CONFIG_PAHOLE_VERSION`).

----
url: https://docs.docker.com/engine/logging/drivers/etwlogs/
----

# ETW logging driver

***

Table of contents

***

The Event Tracing for Windows (ETW) logging driver forwards container logs as ETW events. ETW stands for Event Tracing in Windows, and is the common framework for tracing applications in Windows. Each ETW event contains a message with both the log and its context information. A client can then create an ETW listener to listen to these events.

The ETW provider that this logging driver registers with Windows, has the GUID identifier of: `{a3693192-9ed6-46d2-a981-f8226c8363bd}`. A client creates an ETW listener and registers to listen to events from the logging driver's provider. It doesn't matter the order in which the provider and listener are created. A client can create their ETW listener and start listening for events from the provider, before the provider has been registered with the system.

## [Usage](#usage)

Here is an example of how to listen to these events using the logman utility program included in most installations of Windows:

1. `logman start -ets DockerContainerLogs -p "{a3693192-9ed6-46d2-a981-f8226c8363bd}" 0x0 -o trace.etl`
2. Run your container(s) with the etwlogs driver, by adding `--log-driver=etwlogs` to the Docker run command, and generate log messages.
3. `logman stop -ets DockerContainerLogs`
4. This generates an etl file that contains the events. One way to convert this file into human-readable form is to run: `tracerpt -y trace.etl`.

Each ETW event contains a structured message string in this format:

```text
container_name: %s, image_name: %s, container_id: %s, image_id: %s, source: [stdout | stderr], log: %s
```

Details on each item in the message can be found below:

| Field            | Description                                    |
| ---------------- | ---------------------------------------------- |
| `container_name` | The container name at the time it was started. |
| `image_name`     | The name of the container's image.             |
| `container_id`   | The full 64-character container ID.            |
| `image_id`       | The full ID of the container's image.          |
| `source`         | `stdout` or `stderr`.                          |
| `log`            | The container log message.                     |

Here is an example event message (output formatted for readability):

```yaml
container_name: backstabbing_spence,
image_name: windowsservercore,
container_id: f14bb55aa862d7596b03a33251c1be7dbbec8056bbdead1da8ec5ecebbe29731,
image_id: sha256:2f9e19bd998d3565b4f345ac9aaf6e3fc555406239a4fb1b1ba879673713824b,
source: stdout,
log: Hello world!
```

A client can parse this message string to get both the log message, as well as its context information. The timestamp is also available within the ETW event.

> Note
>
> This ETW provider only emits a message string, and not a specially structured ETW event. Therefore, you don't have to register a manifest file with the system to read and interpret its ETW events.

----
url: https://docs.docker.com/reference/api/extensions-sdk/Extension/
----

# Interface: Extension

***

Table of contents

***

**`Since`**

0.2.0

## [Properties](#properties)

### [vm](#vm)

• `Optional` `Readonly` **vm**: [`ExtensionVM`](https://docs.docker.com/reference/api/extensions-sdk/ExtensionVM/)

***

### [host](#host)

• `Optional` `Readonly` **host**: [`ExtensionHost`](https://docs.docker.com/reference/api/extensions-sdk/ExtensionHost/)

***

### [image](#image)

• `Readonly` **image**: `string`

**`Since`**

0.3.3

----
url: https://docs.docker.com/ai/model-runner/examples/
----

# DMR examples

***

Table of contents

***

See some examples of complete workflows using Docker Model Runner.

## [Sample project](#sample-project)

You can now start building your generative AI application powered by Docker Model Runner.

If you want to try an existing GenAI application, follow these steps:

1. Set up the sample app. Clone and run the following repository:

   ```console
   $ git clone https://github.com/docker/hello-genai.git
   ```

2. In your terminal, go to the `hello-genai` directory.

3. Run `run.sh` to pull the chosen model and run the app.

4. Open your app in the browser at the addresses specified in the repository [README](https://github.com/docker/hello-genai).

You see the GenAI app's interface where you can start typing your prompts.

You can now interact with your own GenAI app, powered by a local model. Try a few prompts and notice how fast the responses are — all running on your machine with Docker.

## [Use Model Runner in GitHub Actions](#use-model-runner-in-github-actions)

Here is an example of how to use Model Runner as part of a GitHub workflow. The example installs Model Runner, tests the installation, pulls and runs a model, interacts with the model via the API, and deletes the model.

dmr-run.yml

```yaml
name: Docker Model Runner Example Workflow

permissions:
  contents: read

on:
  workflow_dispatch:
    inputs:
      test_model:
        description: 'Model to test with (default: ai/smollm2:360M-Q4_K_M)'
        required: false
        type: string
        default: 'ai/smollm2:360M-Q4_K_M'

jobs:
  dmr-test:
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      - name: Set up Docker
        uses: docker/setup-docker-action@v5

      - name: Install docker-model-plugin
        run: |
          echo "Installing docker-model-plugin..."
          # Add Docker's official GPG key:
          sudo apt-get update
          sudo apt-get install ca-certificates curl
          sudo install -m 0755 -d /etc/apt/keyrings
          sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
          sudo chmod a+r /etc/apt/keyrings/docker.asc
          
          # Add the repository to Apt sources:
          echo \
          "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
          $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
          sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
          sudo apt-get update
          sudo apt-get install -y docker-model-plugin
          
          echo "Installation completed successfully"

      - name: Test docker model version
        run: |
          echo "Testing docker model version command..."
          sudo docker model version
          
          # Verify the command returns successfully
          if [ $? -eq 0 ]; then
            echo "✅ docker model version command works correctly"
          else
            echo "❌ docker model version command failed"
            exit 1
          fi

      - name: Pull the provided model and run it
        run: |
          MODEL="${{ github.event.inputs.test_model || 'ai/smollm2:360M-Q4_K_M' }}"
          echo "Testing with model: $MODEL"
          
          # Test model pull
          echo "Pulling model..."
          sudo docker model pull "$MODEL"
          
          if [ $? -eq 0 ]; then
            echo "✅ Model pull successful"
          else
            echo "❌ Model pull failed"
            exit 1
          fi
                  
          # Test basic model run (with timeout to avoid hanging)
          echo "Testing docker model run..."
          timeout 60s sudo docker model run "$MODEL" "Give me a fact about whales." || {
            exit_code=$?
            if [ $exit_code -eq 124 ]; then
              echo "✅ Model run test completed (timed out as expected for non-interactive test)"
            else
              echo "❌ Model run failed with exit code: $exit_code"
              exit 1
            fi
          }
               - name: Test model pull and run
        run: |
          MODEL="${{ github.event.inputs.test_model || 'ai/smollm2:360M-Q4_K_M' }}"
          echo "Testing with model: $MODEL"
          
          # Test model pull
          echo "Pulling model..."
          sudo docker model pull "$MODEL"
          
          if [ $? -eq 0 ]; then
            echo "✅ Model pull successful"
          else
            echo "❌ Model pull failed"
            exit 1
          fi
                  
          # Test basic model run (with timeout to avoid hanging)
          echo "Testing docker model run..."
          timeout 60s sudo docker model run "$MODEL" "Give me a fact about whales." || {
            exit_code=$?
            if [ $exit_code -eq 124 ]; then
              echo "✅ Model run test completed (timed out as expected for non-interactive test)"
            else
              echo "❌ Model run failed with exit code: $exit_code"
              exit 1
            fi
          }

      - name: Test API endpoint
        run: |
          MODEL="${{ github.event.inputs.test_model || 'ai/smollm2:360M-Q4_K_M' }}"
          echo "Testing API endpoint with model: $MODEL"
                  
          # Test API call with curl
          echo "Testing API call..."
          RESPONSE=$(curl -s http://localhost:12434/engines/llama.cpp/v1/chat/completions \
            -H "Content-Type: application/json" \
            -d "{
                \"model\": \"$MODEL\",
                \"messages\": [
                    {
                        \"role\": \"user\",
                        \"content\": \"Say hello\"
                    }
                ],
                \"top_k\": 1,
                \"temperature\": 0
            }")
          
          if [ $? -eq 0 ]; then
            echo "✅ API call successful"
            echo "Response received: $RESPONSE"
            
            # Check if response contains "hello" (case-insensitive)
            if echo "$RESPONSE" | grep -qi "hello"; then
              echo "✅ Response contains 'hello' (case-insensitive)"
            else
              echo "❌ Response does not contain 'hello'"
              echo "Full response: $RESPONSE"
              exit 1
            fi
          else
            echo "❌ API call failed"
            exit 1
          fi

      - name: Test model cleanup
        run: |
          MODEL="${{ github.event.inputs.test_model || 'ai/smollm2:360M-Q4_K_M' }}"
          
          echo "Cleaning up test model..."
          sudo docker model rm "$MODEL" || echo "Model removal failed or model not found"
          
          # Verify model was removed
          echo "Verifying model cleanup..."
          sudo docker model ls
          
          echo "✅ Model cleanup completed"

      - name: Report success
        if: success()
        run: |
          echo "🎉 Docker Model Runner daily health check completed successfully!"
          echo "All tests passed:"
          echo "  ✅ docker-model-plugin installation successful"
          echo "  ✅ docker model version command working"
          echo "  ✅ Model pull and run operations successful"
          echo "  ✅ API endpoint operations successful"
          echo "  ✅ Cleanup operations successful"
```

## [Related pages](#related-pages)

* [Models and Compose](https://docs.docker.com/ai/compose/models-and-compose/)

----
url: https://docs.docker.com/engine/swarm/raft/
----

# Raft consensus in swarm mode

***

***

When Docker Engine runs in Swarm mode, manager nodes implement the [Raft Consensus Algorithm](http://thesecretlivesofdata.com/raft/) to manage the global cluster state.

The reason why Swarm mode is using a consensus algorithm is to make sure that all the manager nodes that are in charge of managing and scheduling tasks in the cluster are storing the same consistent state.

Having the same consistent state across the cluster means that in case of a failure, any Manager node can pick up the tasks and restore the services to a stable state. For example, if the Leader Manager which is responsible for scheduling tasks in the cluster dies unexpectedly, any other Manager can pick up the task of scheduling and re-balance tasks to match the desired state.

Systems using consensus algorithms to replicate logs in a distributed systems do require special care. They ensure that the cluster state stays consistent in the presence of failures by requiring a majority of nodes to agree on values.

Raft tolerates up to `(N-1)/2` failures and requires a majority or quorum of `(N/2)+1` members to agree on values proposed to the cluster. This means that in a cluster of 5 Managers running Raft, if 3 nodes are unavailable, the system cannot process any more requests to schedule additional tasks. The existing tasks keep running but the scheduler cannot rebalance tasks to cope with failures if the manager set is not healthy.

The implementation of the consensus algorithm in Swarm mode means it features the properties inherent to distributed systems:

* Agreement on values in a fault tolerant system. (Refer to [FLP impossibility theorem](https://www.the-paper-trail.org/post/2008-08-13-a-brief-tour-of-flp-impossibility/) and the [Raft Consensus Algorithm paper](https://www.usenix.org/system/files/conference/atc14/atc14-paper-ongaro.pdf))
* Mutual exclusion through the leader election process
* Cluster membership management
* Globally consistent object sequencing and CAS (compare-and-swap) primitives

----
url: https://docs.docker.com/reference/cli/docker/mcp/client/
----

# docker mcp client

***

| Description | Manage MCP clients |
| ----------- | ------------------ |

## [Description](#description)

Manage MCP clients

## [Subcommands](#subcommands)

| Command                                                                                               | Description                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`docker mcp client connect`](https://docs.docker.com/reference/cli/docker/mcp/client/connect/)       | Connect the Docker MCP Toolkit to a client. Supported clients: claude-code claude-desktop cline codex continue crush cursor gemini goose gordon kiro lmstudio opencode sema4 vscode zed      |
| [`docker mcp client disconnect`](https://docs.docker.com/reference/cli/docker/mcp/client/disconnect/) | Disconnect the Docker MCP Toolkit from a client. Supported clients: claude-code claude-desktop cline codex continue crush cursor gemini goose gordon kiro lmstudio opencode sema4 vscode zed |
| [`docker mcp client ls`](https://docs.docker.com/reference/cli/docker/mcp/client/ls/)                 | List client configurations                                                                                                                                                                   |

----
url: https://docs.docker.com/get-started/docker-concepts/building-images/build-tag-and-publish-an-image/
----

# Build, tag, and publish an image

***

Table of contents

***

## [Explanation](#explanation)

In this guide, you will learn the following:

* Building images - the process of building an image based on a `Dockerfile`
* Tagging images - the process of giving an image a name, which also determines where the image can be distributed
* Publishing images - the process to distribute or share the newly created image using a container registry

### [Building images](#building-images)

Most often, images are built using a Dockerfile. The most basic `docker build` command might look like the following:

```bash
docker build .
```

The final `.` in the command provides the path or URL to the [build context](https://docs.docker.com/build/concepts/context/#what-is-a-build-context). At this location, the builder will find the `Dockerfile` and other referenced files.

When you run a build, the builder pulls the base image, if needed, and then runs the instructions specified in the Dockerfile.

With the previous command, the image will have no name, but the output will provide the ID of the image. As an example, the previous command might produce the following output:

```console
$ docker build .
[+] Building 3.5s (11/11) FINISHED                                              docker:desktop-linux
 => [internal] load build definition from Dockerfile                                            0.0s
 => => transferring dockerfile: 308B                                                            0.0s
 => [internal] load metadata for docker.io/library/python:3.12                                  0.0s
 => [internal] load .dockerignore                                                               0.0s
 => => transferring context: 2B                                                                 0.0s
 => [1/6] FROM docker.io/library/python:3.12                                                    0.0s
 => [internal] load build context                                                               0.0s
 => => transferring context: 123B                                                               0.0s
 => [2/6] WORKDIR /usr/local/app                                                                0.0s
 => [3/6] RUN useradd app                                                                       0.1s
 => [4/6] COPY ./requirements.txt ./requirements.txt                                            0.0s
 => [5/6] RUN pip install --no-cache-dir --upgrade -r requirements.txt                          3.2s
 => [6/6] COPY ./app ./app                                                                      0.0s
 => exporting to image                                                                          0.1s
 => => exporting layers                                                                         0.1s
 => => writing image sha256:9924dfd9350407b3df01d1a0e1033b1e543523ce7d5d5e2c83a724480ebe8f00    0.0s
```

With the previous output, you could start a container by using the referenced image:

```console
docker run sha256:9924dfd9350407b3df01d1a0e1033b1e543523ce7d5d5e2c83a724480ebe8f00
```

That name certainly isn't memorable, which is where tagging becomes useful.

### [Tagging images](#tagging-images)

Tagging images is the method to provide an image with a memorable name. However, there is a structure to the name of an image. A full image name has the following structure:

```text
[HOST[:PORT_NUMBER]/]PATH[:TAG]
```

* `HOST`: The optional registry hostname where the image is located. If no host is specified, Docker's public registry at `docker.io` is used by default.
* `PORT_NUMBER`: The registry port number if a hostname is provided
* `PATH`: The path of the image, consisting of slash-separated components. For Docker Hub, the format follows `[NAMESPACE/]REPOSITORY`, where namespace is either a user's or organization's name. If no namespace is specified, `library` is used, which is the namespace for Docker Official Images.
* `TAG`: A custom, human-readable identifier that's typically used to identify different versions or variants of an image. If no tag is specified, `latest` is used by default.

Some examples of image names include:

* `nginx`, equivalent to `docker.io/library/nginx:latest`: this pulls an image from the `docker.io` registry, the `library` namespace, the `nginx` image repository, and the `latest` tag.
* `docker/welcome-to-docker`, equivalent to `docker.io/docker/welcome-to-docker:latest`: this pulls an image from the `docker.io` registry, the `docker` namespace, the `welcome-to-docker` image repository, and the `latest` tag
* `ghcr.io/dockersamples/example-voting-app-vote:pr-311`: this pulls an image from the GitHub Container Registry, the `dockersamples` namespace, the `example-voting-app-vote` image repository, and the `pr-311` tag

To tag an image during a build, add the `-t` or `--tag` flag:

```console
docker build -t my-username/my-image .
```

If you've already built an image, you can add another tag to the image by using the [`docker image tag`](https://docs.docker.com/engine/reference/commandline/image_tag/) command:

```console
docker image tag my-username/my-image another-username/another-image:v1
```

### [Publishing images](#publishing-images)

Once you have an image built and tagged, you're ready to push it to a registry. To do so, use the [`docker push`](https://docs.docker.com/engine/reference/commandline/image_push/) command:

```console
docker push my-username/my-image
```

Within a few seconds, all of the layers for your image will be pushed to the registry.

> **Requiring authentication**
>
> Before you're able to push an image to a repository, you will need to be authenticated. To do so, simply use the [docker login](https://docs.docker.com/engine/reference/commandline/login/) command.

## [Try it out](#try-it-out)

In this hands-on guide, you will build a simple image using a provided Dockerfile and push it to Docker Hub.

### [Set up](#set-up)

1. Get the sample application.

   If you have Git, you can clone the repository for the sample application. Otherwise, you can download the sample application. Choose one of the following options.

   Use the following command in a terminal to clone the sample application repository.

   ```console
   $ git clone https://github.com/docker/getting-started-todo-app
   ```

   Download the source and extract it.

   [Download the source](https://github.com/docker/getting-started-todo-app/raw/cd61f824da7a614a8298db503eed6630eeee33a3/app.zip)

2. [Download and install](https://www.docker.com/products/docker-desktop/) Docker Desktop.

3. If you don't have a Docker account yet, [create one now](https://hub.docker.com/). Once you've done that, sign in to Docker Desktop using that account.

### [Build an image](#build-an-image)

Now that you have a repository on Docker Hub, it's time for you to build an image and push it to the repository.

1. Using a terminal in the root of the sample app repository, run the following command. Replace `YOUR_DOCKER_USERNAME` with your Docker Hub username:

   ```console
   $ docker build -t YOUR_DOCKER_USERNAME/concepts-build-image-demo .
   ```

   As an example, if your username is `mobywhale`, you would run the command:

   ```console
   $ docker build -t mobywhale/concepts-build-image-demo .
   ```

2. Once the build has completed, you can view the image by using the following command:

   ```console
   $ docker image ls
   ```

   The command will produce output similar to the following:

   ```plaintext
   REPOSITORY                             TAG       IMAGE ID       CREATED          SIZE
   mobywhale/concepts-build-image-demo    latest    746c7e06537f   24 seconds ago   354MB
   ```

3. You can actually view the history (or how the image was created) by using the [docker image history](/reference/cli/docker/image/history/) command:

   ```console
   $ docker image history mobywhale/concepts-build-image-demo
   ```

   You'll then see output similar to the following:

   ```plaintext
   IMAGE          CREATED         CREATED BY                                      SIZE      COMMENT
   f279389d5f01   8 seconds ago   CMD ["node" "./src/index.js"]                   0B        buildkit.dockerfile.v0
   <missing>      8 seconds ago   EXPOSE map[3000/tcp:{}]                         0B        buildkit.dockerfile.v0 
   <missing>      8 seconds ago   WORKDIR /app                                    8.19kB    buildkit.dockerfile.v0
   <missing>      4 days ago      /bin/sh -c #(nop)  CMD ["node"]                 0B
   <missing>      4 days ago      /bin/sh -c #(nop)  ENTRYPOINT ["docker-entry…   0B
   <missing>      4 days ago      /bin/sh -c #(nop) COPY file:4d192565a7220e13…   20.5kB
   <missing>      4 days ago      /bin/sh -c apk add --no-cache --virtual .bui…   7.92MB
   <missing>      4 days ago      /bin/sh -c #(nop)  ENV YARN_VERSION=1.22.19     0B
   <missing>      4 days ago      /bin/sh -c addgroup -g 1000 node     && addu…   126MB
   <missing>      4 days ago      /bin/sh -c #(nop)  ENV NODE_VERSION=20.12.0     0B
   <missing>      2 months ago    /bin/sh -c #(nop)  CMD ["/bin/sh"]              0B
   <missing>      2 months ago    /bin/sh -c #(nop) ADD file:d0764a717d1e9d0af…   8.42MB
   ```

   This output shows the layers of the image, highlighting the layers you added and those that were inherited from your base image.

### [Push the image](#push-the-image)

Now that you have an image built, it's time to push the image to a registry.

1. Push the image using the [docker push](/reference/cli/docker/image/push/) command:

   ```console
   $ docker push YOUR_DOCKER_USERNAME/concepts-build-image-demo
   ```

   If you receive a `requested access to the resource is denied`, make sure you are both logged in and that your Docker username is correct in the image tag.

   After a moment, your image should be pushed to Docker Hub.

## [Additional resources](#additional-resources)

To learn more about building, tagging, and publishing images, visit the following resources:

* [What is a build context?](/build/concepts/context/#what-is-a-build-context)
* [docker build reference](/reference/cli/docker/buildx/build/)
* [docker image tag reference](/reference/cli/docker/image/tag/)
* [docker push reference](/reference/cli/docker/image/push/)
* [What is a registry?](/get-started/docker-concepts/the-basics/what-is-a-registry/)

## [Next steps](#next-steps)

Now that you have learned about building and publishing images, it's time to learn how to speed up the build process using the Docker build cache.

[Using the build cache](https://docs.docker.com/get-started/docker-concepts/building-images/using-the-build-cache/)

----
url: https://docs.docker.com/guides/testcontainers-java-aws-localstack/create-project/
----

# Create the Spring Boot project

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Spring Boot project from [Spring Initializr](https://start.spring.io) by selecting the **Testcontainers** starter. Spring Cloud AWS starters are not available on Spring Initializr, so you need to add them manually.

Alternatively, clone the [guide repository](https://github.com/testcontainers/tc-guide-testing-aws-service-integrations-using-localstack).

Add the Spring Cloud AWS BOM to your dependency management and add the S3, SQS starters as dependencies. Testcontainers provides a [LocalStack module](https://testcontainers.com/modules/localstack/) for testing AWS service integrations. You also need [Awaitility](http://www.awaitility.org/) for testing asynchronous SQS processing.

The key dependencies in `pom.xml` are:

```xml
<properties>
    <java.version>17</java.version>
    <testcontainers.version>2.0.4</testcontainers.version>
    <awspring.version>3.0.3</awspring.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>io.awspring.cloud</groupId>
        <artifactId>spring-cloud-aws-starter-s3</artifactId>
    </dependency>
    <dependency>
        <groupId>io.awspring.cloud</groupId>
        <artifactId>spring-cloud-aws-starter-sqs</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-testcontainers</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-localstack</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.awaitility</groupId>
        <artifactId>awaitility</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.awspring.cloud</groupId>
            <artifactId>spring-cloud-aws-dependencies</artifactId>
            <version>${awspring.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

## [Create the configuration properties](#create-the-configuration-properties)

To make the SQS queue and S3 bucket names configurable, create an `ApplicationProperties` record:

```java
package com.testcontainers.demo;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "app")
public record ApplicationProperties(String queue, String bucket) {}
```

Then add `@ConfigurationPropertiesScan` to the main application class so that Spring automatically scans for `@ConfigurationProperties`-annotated classes and registers them as beans:

```java
package com.testcontainers.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;

@SpringBootApplication
@ConfigurationPropertiesScan
public class Application {

  public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
  }
}
```

## [Implement StorageService for S3](#implement-storageservice-for-s3)

Spring Cloud AWS provides higher-level abstractions like `S3Template` with convenience methods for uploading and downloading files. Create a `StorageService` class:

```java
package com.testcontainers.demo;

import io.awspring.cloud.s3.S3Template;
import java.io.IOException;
import java.io.InputStream;
import org.springframework.stereotype.Service;

@Service
public class StorageService {

  private final S3Template s3Template;

  public StorageService(S3Template s3Template) {
    this.s3Template = s3Template;
  }

  public void upload(String bucketName, String key, InputStream stream) {
    this.s3Template.upload(bucketName, key, stream);
  }

  public InputStream download(String bucketName, String key)
    throws IOException {
    return this.s3Template.download(bucketName, key).getInputStream();
  }

  public String downloadAsString(String bucketName, String key)
    throws IOException {
    try (InputStream is = this.download(bucketName, key)) {
      return new String(is.readAllBytes());
    }
  }
}
```

## [Create the SQS message model](#create-the-sqs-message-model)

Create a `Message` record that represents the payload you send to the SQS queue:

```java
package com.testcontainers.demo;

import java.util.UUID;

public record Message(UUID uuid, String content) {}
```

## [Implement the message sender](#implement-the-message-sender)

Create `MessageSender`, which uses `SqsTemplate` to publish messages:

```java
package com.testcontainers.demo;

import io.awspring.cloud.sqs.operations.SqsTemplate;
import org.springframework.stereotype.Service;

@Service
public class MessageSender {

  private final SqsTemplate sqsTemplate;

  public MessageSender(SqsTemplate sqsTemplate) {
    this.sqsTemplate = sqsTemplate;
  }

  public void publish(String queueName, Message message) {
    sqsTemplate.send(to -> to.queue(queueName).payload(message));
  }
}
```

## [Implement the message listener](#implement-the-message-listener)

Create `MessageListener` with a handler method annotated with `@SqsListener`. When a message arrives, the listener uploads the content to an S3 bucket using the message UUID as the key:

```java
package com.testcontainers.demo;

import io.awspring.cloud.sqs.annotation.SqsListener;
import java.io.ByteArrayInputStream;
import java.nio.charset.StandardCharsets;
import org.springframework.stereotype.Service;

@Service
public class MessageListener {

  private final StorageService storageService;
  private final ApplicationProperties properties;

  public MessageListener(
    StorageService storageService,
    ApplicationProperties properties
  ) {
    this.storageService = storageService;
    this.properties = properties;
  }

  @SqsListener(queueNames = { "${app.queue}" })
  public void handle(Message message) {
    String bucketName = this.properties.bucket();
    String key = message.uuid().toString();
    ByteArrayInputStream is = new ByteArrayInputStream(
      message.content().getBytes(StandardCharsets.UTF_8)
    );
    this.storageService.upload(bucketName, key, is);
  }
}
```

The `${app.queue}` expression reads the queue name from application configuration instead of hard-coding it.

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-java-aws-localstack/write-tests/)

----
url: https://docs.docker.com/guides/testcontainers-java-replace-h2/junit-extension-approach/
----

# Use the JUnit 5 extension for more control

***

Table of contents

***

If the special JDBC URL doesn't meet your needs, or you need more control over container creation (for example, to copy initialization scripts), use the Testcontainers JUnit 5 extension:

```java
@DataJpaTest
@TestPropertySource(properties = {
    "spring.test.database.replace=none"
})
@Testcontainers
class ProductRepositoryTest {

  @Container
  static PostgreSQLContainer postgres =
    new PostgreSQLContainer("postgres:16-alpine")
      .withCopyFileToContainer(
        MountableFile.forClasspathResource("sql/init-db.sql"),
        "/docker-entrypoint-initdb.d/init-db.sql");

  @DynamicPropertySource
  static void configureProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.datasource.url", postgres::getJdbcUrl);
    registry.add("spring.datasource.username", postgres::getUsername);
    registry.add("spring.datasource.password", postgres::getPassword);
  }

  @Autowired
  ProductRepository productRepository;

  @Test
  @Sql("/sql/seed-data.sql")
  void shouldGetAllProducts() {
    List<Product> products = productRepository.findAll();
    assertEquals(2, products.size());
  }

  @Test
  @Sql("/sql/seed-data.sql")
  void shouldNotCreateAProductWithDuplicateCode() {
    Product product = new Product(3L, "p101", "Test Product");
    productRepository.createProductIfNotExists(product);
    Optional<Product> optionalProduct = productRepository.findById(
      product.getId()
    );
    assertThat(optionalProduct).isEmpty();
  }
}
```

This approach:

* Uses `@Testcontainers` and `@Container` to manage the container lifecycle.
* Copies `init-db.sql` into the container's init directory so PostgreSQL runs it at startup.
* Uses `@DynamicPropertySource` to register the container's connection details with Spring Boot.
* Tests PostgreSQL-specific features like `ON CONFLICT DO NOTHING` that wouldn't work with H2.

## [Summary](#summary)

* Use the **special JDBC URL** (`jdbc:tc:postgresql:...`) for the quickest way to switch from H2 to a real database — it's a one-property change.
* Use the **JUnit 5 extension** when you need more control over the container (custom init scripts, environment variables, etc.).
* Both approaches work with Spring Data JPA (`@DataJpaTest`) and JdbcTemplate (`@JdbcTest`) tests.

## [Further reading](#further-reading)

* [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/)
* [Testcontainers JDBC support](https://java.testcontainers.org/modules/databases/jdbc/)
* [Testing a Spring Boot REST API with Testcontainers](/guides/testcontainers-java-spring-boot-rest-api/)

----
url: https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/
----

# Extension metadata

***

Table of contents

***

## [The metadata.json file](#the-metadatajson-file)

The `metadata.json` file is the entry point for your extension. It contains the metadata for your extension, such as the name, version, and description. It also contains the information needed to build and run your extension. The image for a Docker extension must include a `metadata.json` file at the root of its filesystem.

The format of the `metadata.json` file must be:

```json
{
    "icon": "extension-icon.svg",
    "ui": ...
    "vm": ...
    "host": ...
}
```

The `ui`, `vm`, and `host` sections are optional and depend on what a given extension provides. They describe the extension content to be installed.

### [UI section](#ui-section)

The `ui` section defines a new tab that's added to the dashboard in Docker Desktop. It follows the form:

```json
"ui":{
    "dashboard-tab":
    {
        "title":"MyTitle",
        "root":"/ui",
        "src":"index.html"
    }
}
```

`root` specifies the folder where the UI code is within the extension image filesystem. `src` specifies the entrypoint that should be loaded in the extension tab.

Other UI extension points will be available in the future.

### [VM section](#vm-section)

The `vm` section defines a backend service that runs inside the Desktop VM. It must define either an `image` or a `compose.yaml` file that specifies what service to run in the Desktop VM.

```json
"vm": {
    "image":"${DESKTOP_PLUGIN_IMAGE}"
},
```

When you use `image`, a default compose file is generated for the extension.

> `${DESKTOP_PLUGIN_IMAGE}` is a specific keyword that allows an easy way to refer to the image packaging the extension. It is also possible to specify any other full image name here. However, in many cases using the same image makes things easier for extension development.

```json
"vm": {
    "composefile": "compose.yaml"
},
```

The Compose file, with a volume definition for example, would look like:

```yaml
services:
  myExtension:
    image: ${DESKTOP_PLUGIN_IMAGE}
    volumes:
      - /host/path:/container/path
```

### [Host section](#host-section)

The `host` section defines executables that Docker Desktop copies on the host.

```json
  "host": {
    "binaries": [
      {
        "darwin": [
          {
            "path": "/darwin/myBinary"
          },
        ],
        "windows": [
          {
            "path": "/windows/myBinary.exe"
          },
        ],
        "linux": [
          {
            "path": "/linux/myBinary"
          },
        ]
      }
    ]
  }
```

`binaries` defines a list of binaries Docker Desktop copies from the extension image to the host.

`path` specifies the binary path in the image filesystem. Docker Desktop is responsible for copying these files in its own location, and the JavaScript API allows invokes these binaries.

Learn how to [invoke executables](https://docs.docker.com/extensions/extensions-sdk/guides/invoke-host-binaries/).

----
url: https://docs.docker.com/reference/cli/sbx/template/save/
----

# sbx template save

| Description | Save a snapshot of the sandbox as a template |
| ----------- | -------------------------------------------- |
| Usage       | `sbx template save SANDBOX TAG [flags]`      |

## [Description](#description)

Save a snapshot of the sandbox as a template.

The saved image is stored in the sandbox runtime's image store and can be used as a template for new sandboxes with: sbx run -t TAG AGENT \[WORKSPACE]

Use --output to also export the image to a tar file that can be shared and loaded on another host with: sbx template load FILE

## [Options](#options)

| Option         | Default | Description                         |
| -------------- | ------- | ----------------------------------- |
| `-o, --output` |         | Also export the image to a tar file |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Save as a template for new sandboxes on this host
sbx template save my-sandbox myimage:v1.0

# Also export to a shareable tar file
sbx template save my-sandbox myimage:v1.0 --output /tmp/myimage.tar
```

----
url: https://docs.docker.com/build/policies/validate-git/
----

# Validating Git repositories

***

Table of contents

***

Git repositories often appear in Docker builds as source code inputs. The `ADD` instruction can clone repositories, and build contexts can reference Git URLs. Validating these inputs ensures you're building from trusted sources with verified versions.

This guide teaches you to write policies that validate Git inputs, from basic version pinning to verifying signed commits and tags.

## [Prerequisites](#prerequisites)

You should understand the policy basics from the [Introduction](https://docs.docker.com/build/policies/intro/): creating policy files, basic Rego syntax, and how policies evaluate during builds.

## [What are Git inputs?](#what-are-git-inputs)

Git inputs come from `ADD` instructions that reference Git repositories:

```dockerfile
# Clone a specific tag
ADD https://github.com/moby/buildkit.git#v0.26.1 /buildkit

# Clone a branch
ADD https://github.com/user/repo.git#main /src

# Clone a commit
ADD https://github.com/user/repo.git#abcde123 /src
```

The build context can also be a Git repository when you build with:

```console
$ docker build https://github.com/user/repo.git#main
```

Each Git reference triggers a policy evaluation. Your policy can inspect repository URLs, validate versions, check commit metadata, and verify signatures.

## [Match specific repositories](#match-specific-repositories)

The simplest Git policy restricts which repositories can be used:

Dockerfile.rego

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.git.host == "github.com"
  input.git.remote == "https://github.com/moby/buildkit.git"
}

decision := {"allow": allow}
```

This policy:

* Denies all inputs by default
* Allows local build context
* Allows only the BuildKit repository from GitHub

The `host` field contains the Git server hostname, and `remote` contains the full repository URL. Test it:

Dockerfile

```dockerfile
FROM scratch
ADD https://github.com/moby/buildkit.git#v0.26.1 /
```

```console
$ docker build .
```

The build succeeds. Try a different repository and it fails.

You can match multiple repositories with additional rules:

```rego
allow if {
  input.git.host == "github.com"
  input.git.remote == "https://github.com/moby/buildkit.git"
}

allow if {
  input.git.host == "github.com"
  input.git.remote == "https://github.com/docker/cli.git"
}

decision := {"allow": allow}
```

## [Pin to specific versions](#pin-to-specific-versions)

Tags and branches can change over time. Pin to specific versions to ensure reproducible builds:

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.git.remote == "https://github.com/moby/buildkit.git"
  input.git.tagName == "v0.26.1"
}

decision := {"allow": allow}
```

The `tagName` field contains the tag name when the Git reference points to a tag. Use `branch` for branches:

```rego
allow if {
  input.git.remote == "https://github.com/user/repo.git"
  input.git.branch == "main"
}
```

Or use `ref` for any type of reference (branch, tag, or commit SHA):

```rego
allow if {
  input.git.ref == "v0.26.1"
}
```

## [Use version allowlists](#use-version-allowlists)

For repositories you trust but want to control versions, maintain an allowlist:

```rego
package docker

default allow := false

allowed_versions = [
    {"tag": "v0.26.1", "annotated": true, "sha": "abc123"},
]

is_buildkit if {
    input.git.remote == "https://github.com/moby/buildkit.git"
}

allow if {
    not is_buildkit
}

allow if {
    is_buildkit
    some version in allowed_versions
    input.git.tagName == version.tag
    input.git.isAnnotatedTag == version.annotated
    startswith(input.git.commitChecksum, version.sha)
}

decision := {"allow": allow}
```

This policy:

* Defines an allowlist of approved versions with metadata
* Uses a helper rule (`is_buildkit`) for readability
* Allows all non-BuildKit inputs
* For BuildKit, checks the tag name, whether it's an annotated tag, and the commit SHA against the allowlist

The helper rule makes complex policies more maintainable. You can expand the allowlist as new versions are approved:

```rego
allowed_versions = [
    {"tag": "v0.26.1", "annotated": true, "sha": "abc123"},
    {"tag": "v0.27.0", "annotated": true, "sha": "def456"},
    {"tag": "v0.27.1", "annotated": true, "sha": "789abc"},
]
```

## [Validate with regex patterns](#validate-with-regex-patterns)

Use pattern matching for semantic versioning:

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.git.remote == "https://github.com/moby/buildkit.git"
  regex.match(`^v[0-9]+\.[0-9]+\.[0-9]+$`, input.git.tagName)
}

decision := {"allow": allow}
```

This allows any BuildKit tag matching the pattern `vX.Y.Z` where X, Y, and Z are numbers. The regex ensures you're using release versions, not pre-release tags like `v0.26.0-rc1`.

Match major versions:

```rego
# Only allow v0.x releases
allow if {
  input.git.remote == "https://github.com/moby/buildkit.git"
  regex.match(`^v0\.[0-9]+\.[0-9]+$`, input.git.tagName)
}
```

## [Inspect commit metadata](#inspect-commit-metadata)

The `commit` object provides detailed information about commits:

```rego
package docker

default allow := false

allow if input.local

# Check commit author
allow if {
  input.git.remote == "https://github.com/user/repo.git"
  input.git.commit.author.email == "trusted@example.com"
}

decision := {"allow": allow}
```

The `commit` object includes:

* `author.name`: Author's name
* `author.email`: Author's email
* `author.when`: When the commit was authored
* `committer.name`: Committer's name
* `committer.email`: Committer's email
* `committer.when`: When the commit was committed
* `message`: Commit message

Validate commit messages:

```rego
allow if {
  input.git.commit
  contains(input.git.commit.message, "Signed-off-by:")
}
```

Pin to specific commit SHA:

```rego
allow if {
  input.git.commitChecksum == "abc123def456..."
}
```

## [Require signed commits](#require-signed-commits)

GPG-signed commits prove authenticity. Check for commit signatures:

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.git.remote == "https://github.com/moby/buildkit.git"
  input.git.commit.pgpSignature != null
}

decision := {"allow": allow}
```

The `pgpSignature` field is `null` for unsigned commits. For signed commits, it contains signature details.

SSH signatures work similarly:

```rego
allow if {
  input.git.commit.sshSignature != null
}
```

## [Require signed tags](#require-signed-tags)

Annotated tags can be signed, providing a cryptographic guarantee of the release:

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.git.remote == "https://github.com/moby/buildkit.git"
  input.git.tag.pgpSignature != null
}

decision := {"allow": allow}
```

The `tag` object is only available for annotated tags. It includes:

* `tagger.name`: Who created the tag
* `tagger.email`: Tagger's email
* `tagger.when`: When the tag was created
* `message`: Tag message
* `pgpSignature`: GPP signature (if signed)
* `sshSignature`: SSH signature (if signed)

Lightweight tags don't have a `tag` object, so this policy effectively requires annotated, signed tags.

## [Verify signatures with public keys](#verify-signatures-with-public-keys)

Use the `verify_git_signature()` function to cryptographically verify Git signatures against trusted public keys:

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.git.remote == "https://github.com/moby/buildkit.git"
  input.git.tagName != ""
  verify_git_signature(input.git.tag, "keys.asc")
}

decision := {"allow": allow}
```

This verifies that Git tags are signed by keys in the `keys.asc` public key file. To set this up:

1. Export maintainer public keys:
   ```console
   $ curl https://github.com/user.gpg > keys.asc
   ```
2. Place `keys.asc` alongside your policy file

The function verifies PGP signatures on commits or tags. See [Built-in functions](https://docs.docker.com/build/policies/built-ins/) for more details.

## [Apply conditional rules](#apply-conditional-rules)

Use different rules for different contexts. Allow unsigned refs during development but require signing for production:

```rego
package docker

default allow := false

allow if input.local

is_buildkit if {
    input.git.remote == "https://github.com/moby/buildkit.git"
}

is_version_tag if {
    is_buildkit
    regex.match(`^v[0-9]+\.[0-9]+\.[0-9]+$`, input.git.tagName)
}

# Version tags must be signed
allow if {
    is_version_tag
    input.git.tagName != ""
    verify_git_signature(input.git.tag, "keys.asc")
}

# Non-version refs allowed in development
allow if {
    is_buildkit
    not is_version_tag
    input.env.target != "release"
}

decision := {"allow": allow}
```

This policy:

* Defines helper rules for readability
* Requires signed version tags from maintainers
* Allows unsigned refs (branches, commits) unless building the release target
* Uses `input.env.target` to detect the build target

Build a development target without signatures:

```console
$ docker buildx build --target=dev .
```

Build the release target, and signing is enforced:

```console
$ docker buildx build --target=release .
```

## [Next steps](#next-steps)

You now understand how to validate Git repositories in build policies. To continue learning:

* Browse [Example policies](https://docs.docker.com/build/policies/examples/) for complete policy patterns
* Read [Built-in functions](https://docs.docker.com/build/policies/built-ins/) for Git signature verification functions
* Check the [Input reference](https://docs.docker.com/build/policies/inputs/) for all available Git fields

----
url: https://docs.docker.com/desktop/features/gpu/
----

# GPU support in Docker Desktop for Windows

***

Table of contents

***

> Note
>
> GPU support in Docker Desktop is only available on Windows with the WSL2 backend.

Docker Desktop for Windows supports NVIDIA GPU Paravirtualization (GPU-PV) on NVIDIA GPUs, allowing containers to access GPU resources for compute-intensive workloads like AI, machine learning, or video processing.

## [Prerequisites](#prerequisites)

To enable WSL 2 GPU Paravirtualization, you need:

* A Windows machine with an NVIDIA GPU
* Up to date Windows 10 or Windows 11 installation
* [Up to date drivers](https://developer.nvidia.com/cuda/wsl) from NVIDIA supporting WSL 2 GPU Paravirtualization
* The latest version of the WSL 2 Linux kernel. Use `wsl --update` on the command line
* To make sure the [WSL 2 backend is turned on](https://docs.docker.com/desktop/features/wsl/#turn-on-docker-desktop-wsl-2) in Docker Desktop

## [Validate GPU support](#validate-gpu-support)

To confirm GPU access is working inside Docker, run the following:

```console
$ docker run --rm -it --gpus=all nvcr.io/nvidia/k8s/cuda-sample:nbody nbody -gpu -benchmark
```

This runs an n-body simulation benchmark on the GPU. The output will be similar to:

```console
Run "nbody -benchmark [-numbodies=<numBodies>]" to measure performance.
        -fullscreen       (run n-body simulation in fullscreen mode)
        -fp64             (use double precision floating point values for simulation)
        -hostmem          (stores simulation data in host memory)
        -benchmark        (run benchmark to measure performance)
        -numbodies=N    (number of bodies (>= 1) to run in simulation)
        -device=<d>       (where d=0,1,2.... for the CUDA device to use)
        -numdevices=<i>   (where i=(number of CUDA devices > 0) to use for simulation)
        -compare          (compares simulation results running once on the default GPU and once on the CPU)
        -cpu              (run n-body simulation on the CPU)
        -tipsy=<file.bin> (load a tipsy model file for simulation)

> NOTE: The CUDA Samples are not meant for performance measurements. Results may vary when GPU Boost is enabled.

> Windowed mode
> Simulation data stored in video memory
> Single precision floating point simulation
> 1 Devices used for simulation
MapSMtoCores for SM 7.5 is undefined.  Default to use 64 Cores/SM
GPU Device 0: "GeForce RTX 2060 with Max-Q Design" with compute capability 7.5

> Compute 7.5 CUDA device: [GeForce RTX 2060 with Max-Q Design]
30720 bodies, total time for 10 iterations: 69.280 ms
= 136.219 billion interactions per second
= 2724.379 single-precision GFLOP/s at 20 flops per interaction
```

## [Run a real-world model: SmolLM2 with Docker Model Runner](#run-a-real-world-model-smollm2-with-docker-model-runner)

Use Docker Model Runner to run the SmolLM2 LLM with vLLM and GPU acceleration:

```console
$ docker model install-runner --backend vllm --gpu cuda
```

Check it's correctly installed:

```console
$ docker model status
Docker Model Runner is running

Status:
llama.cpp: running llama.cpp version: c22473b
vllm: running vllm version: 0.11.0
```

Run the model:

```console
$ docker model run ai/smollm2-vllm hi
Hello! I'm sure everything goes smoothly here. How can I assist you today?
```

----
url: https://docs.docker.com/engine/release-notes/23.0/
----

# Docker Engine 23.0 release notes

***

Table of contents

***

> Note
>
> From Docker Engine version 23.0.0, Buildx is distributed in a separate package: `docker-buildx-plugin`. In earlier versions, Buildx was included in the `docker-ce-cli` package. When you upgrade to this version of Docker Engine, make sure you update all packages. For example, on Ubuntu:
>
> ```console
> $ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
> ```
>
> Refer to the [Docker Engine installation instructions](https://docs.docker.com/engine/install/) for your operating system for more details on upgrading Docker Engine.

This page describes the latest changes, additions, known issues, and fixes for Docker Engine version 23.0.

For more information about:

* Deprecated and removed features, see [Deprecated Engine Features](https://docs.docker.com/engine/deprecated/).
* Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history/).

Starting with the 23.0.0 release, Docker Engine moves away from using CalVer versioning, and starts using the [SemVer versioning format](https://semver.org/). Changing the version format is a stepping-stone towards Go module compatibility, but the repository doesn't yet use Go modules, and still requires using a "+incompatible" version. Work continues towards Go module compatibility in a future release.

## [23.0.6](#2306)

*2023-05-08*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 23.0.6 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A23.0.6)
* [moby/moby, 23.0.6 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A23.0.6)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* Fix vfs storage driver not working on NFS. [moby/moby#45465](https://github.com/moby/moby/pull/45465)

### [Packaging Updates](#packaging-updates)

* Upgrade Go to `1.19.9`. [docker/docker-ce-packaging#889](https://github.com/docker/docker-ce-packaging/pull/889), [docker/cli#4254](https://github.com/docker/cli/pull/4254), [moby/moby#45455](https://github.com/moby/moby/pull/45455)
* Upgrade `containerd` to [v1.6.21](https://github.com/containerd/containerd/releases/tag/v1.6.21)
* Upgrade `runc` to [v1.1.7](https://github.com/opencontainers/runc/releases/tag/v1.1.7)

## [23.0.5](#2305)

*2023-04-26*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 23.0.5 milestone](https://github.com/docker/cli/milestone/79?closed=1)
* [moby/moby, 23.0.5 milestone](https://github.com/moby/moby/milestone/118?closed=1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

* Add the `--all` / `-a` option when pruning volumes. [docker/cli#4229](https://github.com/docker/cli/pull/4229)
* Add `--format=json` for `docker info`. [docker/cli#4320](https://github.com/docker/cli/pull/4230)
* Fix log loss with the AWSLogs log driver. [moby/moby#45350](https://github.com/moby/moby/pull/45350)
* Fix a regression introduced in v23.0.4 where dockerd would refuse to start if the fixed-cidr config parameter is provided but not bip. [moby/moby#45403](https://github.com/moby/moby/pull/45403)
* Fix a panic in libnetwork during daemon start [moby/moby#45376](https://github.com/moby/moby/pull/45376)
* Fix "tag" event not being sent when an image is built with `buildx`. [moby/moby#45410](https://github.com/moby/moby/pull/45410)

### [Packaging Updates](#packaging-updates-1)

* Upgrade Compose to `2.17.3`. [docker/docker-ce-packaging#883](https://github.com/docker/docker-ce-packaging/pull/883)

## [23.0.4](#2304)

*2023-04-17*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 23.0.4 milestone](https://github.com/docker/cli/milestone/77?closed=1)
* [moby/moby, 23.0.4 milestone](https://github.com/moby/moby/milestone/117?closed=1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

* Fix a performance regression in Docker CLI 23.0.0 [docker/cli#4141](https://github.com/docker/cli/pull/4141).
* Fix progress indicator on `docker cp` not functioning as intended [docker/cli#4157](https://github.com/docker/cli/pull/4157).
* Fix shell completion for `docker compose --file` [docker/cli#4177](https://github.com/docker/cli/pull/4177).
* Fix an error caused by incorrect handling of "default-address-pools" in `daemon.json` [moby/moby#45246](https://github.com/moby/moby/pull/45246).

### [Packaging Updates](#packaging-updates-2)

* Fix missing packages for CentOS 9 Stream.
* Upgrade Go to `1.19.8`. [docker/docker-ce-packaging#878](https://github.com/docker/docker-ce-packaging/pull/878), [docker/cli#4164](https://github.com/docker/cli/pull/4164), [moby/moby#45277](https://github.com/moby/moby/pull/45277), which contains fixes for [CVE-2023-24537](https://github.com/advisories/GHSA-fp86-2355-v99r), [CVE-2023-24538](https://github.com/advisories/GHSA-v4m2-x4rp-hv22), [CVE-2023-24534](https://github.com/advisories/GHSA-8v5j-pwr7-w5f8), and [CVE-2023-24536](https://github.com/advisories/GHSA-9f7g-gqwh-jpf5)

## [23.0.3](#2303)

*2023-04-04*

> Note
>
> Due to an issue with CentOS 9 Stream's package repositories, packages for CentOS 9 are currently unavailable. Packages for CentOS 9 may be added later, or as part of the next (23.0.4) patch release.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-3)

* Fixed a number of issues that can cause Swarm encrypted overlay networks to fail to uphold their guarantees, addressing [CVE-2023-28841](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28841), [CVE-2023-28840](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28840), and [CVE-2023-28842](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28842).

  * A lack of kernel support for encrypted overlay networks now reports as an error.
  * Encrypted overlay networks are eagerly set up, rather than waiting for multiple nodes to attach.
  * Encrypted overlay networks are now usable on Red Hat Enterprise Linux 9 through the use of the `xt_bpf` kernel module.
  * Users of Swarm overlay networks should review [GHSA-vwm3-crmr-xfxw](https://github.com/moby/moby/security/advisories/GHSA-vwm3-crmr-xfxw) to ensure that unintentional exposure has not occurred.

### [Packaging Updates](#packaging-updates-3)

* Upgrade `containerd` to [v1.6.20](https://github.com/containerd/containerd/releases/tag/v1.6.20).
* Upgrade `runc` to [v1.1.5](https://github.com/opencontainers/runc/releases/tag/v1.1.5).

## [23.0.2](#2302)

*2023-03-28*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 23.0.2 milestone](https://github.com/docker/cli/milestone/75?closed=1)
* [moby/moby, 23.0.2 milestone](https://github.com/moby/moby/milestone/114?closed=1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-4)

* Fully resolve missing checks for `apparmor_parser` when an AppArmor enabled kernel is detected. [containerd/containerd#8087](https://github.com/containerd/containerd/pull/8087), [moby/moby#45043](https://github.com/moby/moby/pull/45043)
* Ensure that credentials are redacted from Git URLs when generating BuildKit buildinfo. Fixes [CVE-2023-26054](https://github.com/moby/buildkit/security/advisories/GHSA-gc89-7gcr-jxqc). [moby/moby#45110](https://github.com/moby/moby/pull/45110)
* Fix anonymous volumes created by a `VOLUME` line in a Dockerfile being excluded from volume prune. [moby/moby#45159](https://github.com/moby/moby/pull/45159)
* Fix a failure to properly propagate errors during removal of volumes on a Swarm node. [moby/moby#45155](https://github.com/moby/moby/pull/45155)
* Temporarily work around a bug in BuildKit `COPY --link` by disabling mergeop/diffop optimization. [moby/moby#45112](https://github.com/moby/moby/pull/45112)
* Properly clean up child tasks when a parent Swarm job is removed. [moby/swarmkit#3112](https://github.com/moby/swarmkit/pull/3112), [moby/moby#45107](https://github.com/moby/moby/pull/45107)
* Fix Swarm service creation logic so that both a GenericResource and a non-default network can be used together. [moby/swarmkit#3082](https://github.com/moby/swarmkit/pull/3082), [moby/moby#45107](https://github.com/moby/moby/pull/45107)
* Fix Swarm CSI support requiring the CSI plugin to offer staging endpoints in order to publish a volume. [moby/swarmkit#3116](https://github.com/moby/swarmkit/pull/3116), [moby/moby#45107](https://github.com/moby/moby/pull/45107)
* Fix a panic caused by log buffering in some configurations. [containerd/fifo#47](https://github.com/containerd/fifo/pull/47), [moby/moby#45051](https://github.com/moby/moby/pull/45051)
* Log errors in the REST to Swarm gRPC API translation layer at the debug level to reduce redundancy and noise. [moby/moby#45016](https://github.com/moby/moby/pull/45016)
* Fix a DNS resolution issue affecting containers created with `--dns-opt` or `--dns-search` when `systemd-resolved` is used outside the container. [moby/moby#45000](https://github.com/moby/moby/pull/45000)
* Fix a panic when logging errors in handling DNS queries originating from inside a container. [moby/moby#44980](https://github.com/moby/moby/pull/44980)
* Improve the speed of `docker ps` by allowing users to opt out of size calculations with `--size=false`. [docker/cli#4107](https://github.com/docker/cli/pull/4107)
* Extend support for Bash completion to all plugins. [docker/cli#4092](https://github.com/docker/cli/pull/4092)
* Fix `docker stack deploy` failing on Windows when special environment variables set by `cmd.exe` are present. [docker/cli#4083](https://github.com/docker/cli/pull/4083)
* Add forward compatibility for future API versions by considering empty image tags to be the same as `<none>`. [docker/cli#4065](https://github.com/docker/cli/pull/4065)
* Atomically write context files to greatly reduce the probability of corruption, and improve the error message for a corrupt context. [docker/cli#4063](https://github.com/docker/cli/pull/4063)

### [Packaging](#packaging)

* Upgrade Go to `1.19.7`. [docker/docker-ce-packaging#857](https://github.com/docker/docker-ce-packaging/pull/857), [docker/cli#4086](https://github.com/docker/cli/pull/4086), [moby/moby#45137](https://github.com/moby/moby/pull/45137)
* Upgrade `containerd` to `v1.6.19`. [moby/moby#45084](https://github.com/moby/moby/pull/45084), [moby/moby#45099](https://github.com/moby/moby/pull/45099)
* Upgrade Buildx to `v0.10.4`. [docker/docker-ce-packaging#855](https://github.com/docker/docker-ce-packaging/pull/855)
* Upgrade Compose to `v2.17.2`. [docker/docker-ce-packaging#867](https://github.com/docker/docker-ce-packaging/pull/867)

## [23.0.1](#2301)

*2023-02-09*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 23.0.1 milestone](https://github.com/docker/cli/milestone/73?closed=1)
* [moby/moby, 23.0.1 milestone](https://github.com/moby/moby/milestone/113?closed=1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-5)

* Fix containers not starting if the kernel has AppArmor enabled, but `apparmor_parser` is not available. [moby/moby#44942](https://github.com/moby/moby/pull/44942)
* Fix BuildKit-enabled builds with inline caching causing the daemon to crash. [moby/moby#44944](https://github.com/moby/moby/pull/44944)
* Fix BuildKit improperly loading cached layers created by previous versions. [moby/moby#44959](https://github.com/moby/moby/pull/44959)
* Fix an issue where `ipvlan` networks created prior to upgrading would prevent the daemon from starting. [moby/moby#44937](https://github.com/moby/moby/pull/44937)
* Fix the `overlay2` storage driver failing early in `metacopy` testing when initialized on an unsupported backing filesystem. [moby/moby#44922](https://github.com/moby/moby/pull/44922)
* Fix `exec` exit events being misinterpreted as container exits under some runtimes, such as Kata Containers. [moby/moby#44892](https://github.com/moby/moby/pull/44892)
* Improve the error message returned by the CLI when receiving a truncated JSON response caused by the API hanging up mid-request. [docker/cli#4004](https://github.com/docker/cli/pull/4004)
* Fix an incorrect CLI exit code when attempting to execute a directory with a `runc` compiled using Go 1.20. [docker/cli#4004](https://github.com/docker/cli/pull/4004)
* Fix mishandling the size argument to `--device-write-bps` as a path. [docker/cli#4004](https://github.com/docker/cli/pull/4004)

### [Packaging](#packaging-1)

* Add `/etc/docker` to RPM and DEB packaging. [docker/docker-ce-packaging#842](https://github.com/docker/docker-ce-packaging/pull/842)
  * Not all use cases will benefit; if you depend on this, you should explicitly `mkdir -p /etc/docker`.
* Upgrade Compose to `v2.16.0`. [docker/docker-ce-packaging#844](https://github.com/docker/docker-ce-packaging/pull/844)

## [23.0.0](#2300)

*2023-02-01*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 23.0.0 milestone](https://github.com/docker/cli/milestone/51?closed=1)
* [moby/moby, 23.0.0 milestone](https://github.com/moby/moby/milestone/91?closed=1)

### [New](#new)

* Set Buildx and BuildKit as the default builder on Linux. [moby/moby#43992](https://github.com/moby/moby/pull/43992)

  * Alias `docker build` to `docker buildx build`. [docker/cli#3314](https://github.com/docker/cli/pull/3314)
  * The legacy builder can still be used by explicitly setting `DOCKER_BUILDKIT=0`.
  * There are differences in how BuildKit and the legacy builder handle multi-stage builds. For more information, see [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/#differences-between-legacy-builder-and-buildkit).

* Add support for pulling `zstd` compressed layers. [moby/moby#41759](https://github.com/moby/moby/pull/41759), [moby/moby#42862](https://github.com/moby/moby/pull/42862)

* Add support for alternate OCI runtimes on Linux, compatible with the containerd runtime v2 API. [moby/moby#43887](https://github.com/moby/moby/pull/43887), [moby/moby#43993](https://github.com/moby/moby/pull/43993)

* Add support for the containerd `runhcs` shim on Windows (off by default). [moby/moby#42089](https://github.com/moby/moby/pull/42089)

* Add `dockerd --validate` to check the daemon JSON config and exit. [moby/moby#42393](https://github.com/moby/moby/pull/42393)

* Add the ability to configure the daemon's HTTP proxy via flags or JSON config. [moby/moby#42835](https://github.com/moby/moby/pull/42835)

* Add support for RFC 3021 point-to-point networks (IPv4 /31s) and single hosts (IPv4 /32s). For networks with two or fewer addresses, IPAM won't reserve a network and broadcast address. [moby/moby#42626](https://github.com/moby/moby/pull/42626)

* Add support for setting `ipvlan_flag` and using the `l3s` `ipvlan_mode` in the `ipvlan` network driver. [moby/moby#42542](https://github.com/moby/moby/pull/42542)

* Add support for displaying the value of the `metacopy` option for the `overlay2` storage driver. [moby/moby#43557](https://github.com/moby/moby/pull/43557)

* Add support for describing Windows devices using the syntax `IDType://ID`. [moby/moby#43368](https://github.com/moby/moby/pull/43368)

* Add `RootlessKit`, `slirp4netns`, and `VPNKit` version reporting. [moby/moby#42330](https://github.com/moby/moby/pull/42330)

* Add experimental support for SwarmKit cluster volumes (CSI). [moby/moby#41982](https://github.com/moby/moby/pull/41982)

  * CLI: Add cluster volume (CSI) options to `docker volume`. [docker/cli#3606](https://github.com/docker/cli/pull/3606)
  * CLI: Add cluster volume (CSI) support to `docker stack`. [docker/cli#3662](https://github.com/docker/cli/pull/3662)

* Add support for SwarmKit jobs in `docker stack deploy`. [docker/cli#2907](https://github.com/docker/cli/pull/2907)

* Add the `docker stack config` command to output the merged and interpolated config files as utilized by `stack deploy`. [docker/cli#3544](https://github.com/docker/cli/pull/3544)

* Add a new `docker context show` command that prints the name of the current context. [docker/cli#3567](https://github.com/docker/cli/pull/3567)

* Add the `--format=json` shorthand variant of `--format="{{ json . }}"` to all commands supporting the `--format` flag. [docker/cli#2936](https://github.com/docker/cli/pull/2936)

* Add a `--quiet` option to `docker create` and `docker run` commands to suppress output when pulling an image. [docker/cli#3377](https://github.com/docker/cli/pull/3377)

* Add a `--force` option to `docker network rm` subcommand. Causes CLI to return a 0 exit code even if the network doesn't exist. Has no effect on the server-side procedure for removing a network. [docker/cli#3547](https://github.com/docker/cli/pull/3547)

* Add a `--signal` option to `docker stop` and `docker restart`. [docker/cli#3614](https://github.com/docker/cli/pull/3614)

* Add a `-v/--version` flag to `docker-proxy`. [moby/moby#44703](https://github.com/moby/moby/pull/44703)

* Plugins are now discovered in well-known user-level paths when the daemon is running in rootless mode. [moby/moby#44778](https://github.com/moby/moby/pull/44778)

* The daemon now handles common alternate JSON encodings in the JSON configuration file gracefully, and reports useful errors. [moby/moby#44777](https://github.com/moby/moby/pull/44777), [moby/moby#44832](https://github.com/moby/moby/pull/44832)

  * UTF-8 with a byte order mark is accepted.
  * UTF-16 with a byte order mark is accepted.
  * Invalid UTF-8 is reported early and with a comprehensible error message.

* Allow use of `STOPSIGNAL` via `docker commit`. [moby/moby#43369](https://github.com/moby/moby/pull/43369)

* Add a new option to the `awslogs` log driver to allow skipping log stream creation in CloudWatch. [moby/moby#42132](https://github.com/moby/moby/pull/42132)

* Add a new option to the `awslogs` log driver to specify the log format that's sent to CloudWatch. [moby/moby#42838](https://github.com/moby/moby/pull/42838)

* Add a new option to the `fluentd` log driver to set the reconnection interval. [moby/moby#43100](https://github.com/moby/moby/pull/43100)

* Add new options-setters to the Go API client: `WithTLSClientConfigFromEnv()`, `WithHostFromEnv()`, and `WithVersionFromEnv()`. [moby/moby#42224](https://github.com/moby/moby/pull/42224)

* Add generation of shell command completion through a `docker completion` subcommand. [docker/cli#3429](https://github.com/docker/cli/pull/3429)

* API: Add a `Swarm` header to `GET /_ping` and `HEAD /_ping`, allowing single-request detection of Swarm support. [moby/moby#42064](https://github.com/moby/moby/pull/42064)

* API: Add a `signal` parameter to `POST /containers/{id}/stop` and `POST /containers/{id}/restart` to set the signal used. [moby/moby#43206](https://github.com/moby/moby/pull/43206)

* API: Add a `CreateMountPoint` parameter to `POST /containers/create`. [moby/moby#43484](https://github.com/moby/moby/pull/43484)

* API: Add a `shared-size` parameter to `GET /images/json` to enable shared-size computation of images. [moby/moby#42531](https://github.com/moby/moby/pull/42531)

* API: Add a `type` parameter to `GET /system/df`, to control what object types to are considered when computing disk usage. [moby/moby#42559](https://github.com/moby/moby/pull/42559)

* systemd: Use a systemd-managed containerd instead of a daemon-managed containerd. [moby/moby#42373](https://github.com/moby/moby/pull/42373)

* systemd: Start `docker.service` after `time-set.target`. [moby/moby#43107](https://github.com/moby/moby/pull/43107)

### [Removed](#removed)

* Remove support for reading configuration from `~/.dockercfg`. [docker/cli#2504](https://github.com/docker/cli/pull/2504)

  * This location has been deprecated since 1.7.0.
  * [Deprecation notice](https://docs.docker.com/engine/deprecated/#support-for-legacy-dockercfg-configuration-files)

* Remove the `-g` and `--graph` daemon options in favor of `--data-root`. [docker/cli#3739](https://github.com/docker/cli/pull/3739)

  * These options have been hidden and deprecated since 17.05.
  * [Deprecation notice](https://docs.docker.com/engine/deprecated/#-g-and---graph-flags-on-dockerd)

* Remove client-side sorting of results, in favor of the order in which the search API returns. [docker/cli#3470](https://github.com/docker/cli/pull/3470)

* Remove warnings related to deprecated storage drivers from the CLI. Warnings are now handled by the daemon instead. [docker/cli#3542](https://github.com/docker/cli/pull/3542)

* Remove `Experimental` client field from `docker version`. [docker/cli#3543](https://github.com/docker/cli/pull/3543)
  * [Deprecation notice](https://docs.docker.com/engine/deprecated/#configuration-options-for-experimental-cli-features)

* Require explicit opt-in to use deprecated storage drivers, and don't automatically select them when upgrading. [moby/moby#43378](https://github.com/moby/moby/pull/43378)

* Remove deprecated support for `overlay` and `overlay2` storage drivers on backing filesystems without `d_type` support. [moby/moby#43472](https://github.com/moby/moby/pull/43472)
  * [Deprecation notice](https://docs.docker.com/engine/deprecated/#backing-filesystem-without-d_type-support-for-overlayoverlay2)

* Remove the deprecated `overrideKernelCheck` option from the `overlay2` storage driver. [moby/moby#44279](https://github.com/moby/moby/pull/44279) [Deprecation notice](https://docs.docker.com/engine/deprecated/#support-for-the-overlay2override_kernel_check-storage-option)

* Remove support for the deprecated `io.containerd.runtime.v1.linux` OCI runtime. [moby/moby#43695](https://github.com/moby/moby/pull/43695)

* Remove LCOW (Linux Containers on Windows). [moby/moby#42451](https://github.com/moby/moby/pull/42451), [moby/moby#42499](https://github.com/moby/moby/pull/42499), [moby/moby#42506](https://github.com/moby/moby/pull/42506), [moby/moby#42511](https://github.com/moby/moby/pull/42511), [moby/moby#42520](https://github.com/moby/moby/pull/42520), [moby/moby#42683](https://github.com/moby/moby/pull/42683), [moby/moby#42684](https://github.com/moby/moby/pull/42684), [moby/moby#42685](https://github.com/moby/moby/pull/42685), [moby/moby#43187](https://github.com/moby/moby/pull/43187)

  * LCOW was introduced as a technical preview in 17.09 and deprecated in 20.10.
  * [Deprecation notice](https://docs.docker.com/engine/deprecated/#linux-containers-on-windows-lcow-experimental)

* Remove daemon options related to legacy overlay networks used with standalone Swarm.

  * Remove `--cluster-xx` options from `dockerd`. [moby/moby#40383](https://github.com/moby/moby/issues/40383)
  * Remove `host-discovery` and overlay networks with external k/v stores. [moby/moby#42247](https://github.com/moby/moby/pull/42247)
  * [Deprecation notice](https://docs.docker.com/engine/deprecated/#classic-swarm-and-overlay-networks-using-cluster-store)

* Remove a deprecated `arm` platform fallback. `--platform linux/arm/vY` will now return a error when `arm/vY` isn't available instead of pulling the wrong image. [moby/moby#44414](https://github.com/moby/moby/pull/44414)

* Remove the deprecated `SetCustomHTTPHeaders()`, `CustomHTTPHeaders()` options-setters from the Go client API. [moby/moby#42694](https://github.com/moby/moby/pull/42694)

* Remove the deprecated `WithDialer()` option-setter from the Go client API. [moby/moby#44022](https://github.com/moby/moby/pull/44022)
  * Use `WithDialContext()` instead.

* Remove the daemon implementation of `opts.QuotedString`. The implementation has moved to the CLI. [moby/moby#43250](https://github.com/moby/moby/pull/43250)

* Remove separate daemon ID from trust-key in the daemon, and disable generating the trust-key. [moby/moby#43555](https://github.com/moby/moby/pull/43555)

* API: Remove the deprecated `KernelMemory` option from `POST /containers/create` on API version >= 1.42. [moby/moby#43214](https://github.com/moby/moby/pull/43214)
  * [Deprecation notice](https://docs.docker.com/engine/deprecated/#kernel-memory-limit)

### [Deprecated](#deprecated)

* Require Windows Server RS5 / LTSC 2019 (build 17763) as the minimum to run the daemon. [moby/moby#43254](https://github.com/moby/moby/pull/43254)
* Deprecate `BuilderSize` on API version >= 1.42. [moby/moby#42608](https://github.com/moby/moby/pull/42608)
* Deprecate `BuildCache.Parent` in favor of the newly introduced `BuildCache.Parents` on API version >= 1.42. [moby/moby#43908](https://github.com/moby/moby/pull/43908)
* Deprecate `pkg/urlutil`, moving the implementation to `builder/remotecontext/urlutil`. [moby/moby#43477](https://github.com/moby/moby/pull/43477)

### [Upgrades](#upgrades)

* Upgrade Go to `1.19.5`. [docker/cli#3958](https://github.com/docker/cli/pull/3958), [moby/moby#44794](https://github.com/moby/moby/pull/44794)
* Upgrade `rootlesskit` to `v0.14.4`. [moby/moby#42708](https://github.com/moby/moby/pull/42708)
* Upgrade `buildkit` to `v0.10.6`. [moby/moby#43239](https://github.com/moby/moby/pull/43239)
* Upgrade `buildx` to `v0.10.2`. [docker/docker-ce-packaging#840](https://github.com/docker/docker-ce-packaging/pull/840)
* Upgrade `swarmkit` to `v2.0.0-20230119195359-904c221ac281`. [moby/moby#44858](https://github.com/moby/moby/pull/44858)
* Upgrade `containerd` to `v1.6.16`. [moby/moby#44766](https://github.com/moby/moby/pull/44766), [moby/moby#44769](https://github.com/moby/moby/pull/44769), [moby/moby#44881](https://github.com/moby/moby/pull/44881)
* Upgrade `runc` to `v1.1.4`. [moby/moby#44039](https://github.com/moby/moby/pull/44039)
* Upgrade `hcsshim` `v0.9.6`. [moby/moby#44658](https://github.com/moby/moby/pull/44658)
* The `btrfs` storage driver now depends on Linux kernel headers (>= 4.12) instead of headers from btrfs-progs. [moby/moby#44776](https://github.com/moby/moby/pull/44776)

### [Security](#security)

* Change permissions on container `hostconfig.json` files to `0600` (was `0644`). [moby/moby#41620](https://github.com/moby/moby/pull/41620)
* Fix `--seccomp-profile` not accepting `unconfined` and renamed the default seccomp profile to `builtin`. [moby/moby#42481](https://github.com/moby/moby/pull/42481)
* Always build with seccomp support, and remove the `seccomp` build tag. [moby/moby#42501](https://github.com/moby/moby/pull/42501)
* Add seccomp support on `riscv64`. [moby/moby#43553](https://github.com/moby/moby/pull/43553)
* Add support for setting flags passed to `seccomp(2)` in seccomp profiles. [moby/moby#42648](https://github.com/moby/moby/pull/42648)
* Refactor seccomp types to reuse runtime-spec, and add support for `ErrnoRet`. [moby/moby#42005](https://github.com/moby/moby/pull/42005)
* Add support for `DefaultErrnoRet` in `seccomp` profiles. [moby/moby#42604](https://github.com/moby/moby/pull/42604)
* Add an explicit `DefaultErrnoRet` field to the default seccomp profile, with no behavior change. [moby/moby#42649](https://github.com/moby/moby/pull/42649)
* Block `socket` with `AF_VSOCK` in the default seccomp profile. [moby/moby#44563](https://github.com/moby/moby/pull/44563)
* Re-enable `process_vm_readv` and `process_vm_writev` in the default seccomp profile. [moby/moby#42083](https://github.com/moby/moby/pull/42083)
* Add syscalls related to PKU to the default seccomp profile. [moby/moby#43812](https://github.com/moby/moby/pull/43812)
* Allow `clock_settime64` with `CAP_SYS_TIME`. [moby/moby#43775](https://github.com/moby/moby/pull/43775)
* Allow `bpf` with `CAP_BPF` and `perf_event_open` with `CAP_PERFMON`. [moby/moby#43988](https://github.com/moby/moby/pull/43988)
* Explicitly set the `clone3` syscall to return `ENOSYS` in the default seccomp profile, in order to ensure `glibc` will correctly fallback to using `clone`. [moby/moby#42681](https://github.com/moby/moby/pull/42681)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-6)

* Promote `overlay2` to be the default storage driver (`btrfs` and `zfs` are now opt-in). [moby/moby#42661](https://github.com/moby/moby/pull/42661)
* Add a loading spinner to the `docker cp` command. [docker/cli#2708](https://github.com/docker/cli/pull/2708)
* Deprecate the `ElectAuthServer` function, and made it return the default registry without calling the `GET /info` API endpoint. [docker/cli#2819](https://github.com/docker/cli/pull/2819)
* Progress bars are no longer reversed when rolling back Swarm services. [docker/cli#2940](https://github.com/docker/cli/pull/2940)
* Use `net.JoinHostPort()` to fix formatting with IPv6 addresses. [docker/cli#2972](https://github.com/docker/cli/pull/2972)
* CLI error messages are now printed to `stderr`. [docker/cli#3044](https://github.com/docker/cli/pull/3044)
* Improve performance of `docker info` if a custom `--format` is used that only uses local information. With this change, the CLI only uses the daemon API if it detects that information from the daemon is needed. [docker/cli#3179](https://github.com/docker/cli/pull/3179)
* Remove the default value from the `--stop-signal` flag, as it may not reflect the actual default used by the daemon. [docker/cli#3245](https://github.com/docker/cli/pull/3245)
* Add Compose schema `3.10` to `docker stack`; allow omitting the `version` field (resulting in `latest`). [docker/cli#3257](https://github.com/docker/cli/pull/3257)
* Compose version `3` is now equivalent to `3.x` (latest) in `docker stack`. [docker/cli#3445](https://github.com/docker/cli/pull/3445)
* Fix `<Ctrl-c>` hanging on Windows to exit after running a container in non-interactive mode. [docker/cli#3302](https://github.com/docker/cli/pull/3302)
* Add relative source paths to the `run` command in the `-v`/`--volume` and `-m`/`--mount` flags. [docker/cli#3469](https://github.com/docker/cli/pull/3469)
* `docker exec -t` now sets the console size for the executed process immediately when it's created. [docker/cli#3627](https://github.com/docker/cli/pull/3627)
* Update the pretty-print format of `docker info` to provide more details on installed plugins. [docker/cli#3645](https://github.com/docker/cli/pull/3645)
* Print warning messages for the `docker context list` and `docker context use` commands when the context is overridden by the environment. [docker/cli#3668](https://github.com/docker/cli/pull/3668)
* Add a custom `aliases` annotation that can be used to print all available aliases for a command. [docker/cli#3694](https://github.com/docker/cli/pull/3694)
* The CLI no longer creates or updates the CLI configuration file when running `docker context use` and selecting the current context. [docker/cli#3721](https://github.com/docker/cli/pull/3721)
* Non-existing contexts are now ignored when running `docker context rm --force`. [docker/cli#3791](https://github.com/docker/cli/pull/3791)
* Add the ability to override integers to `0` in Compose files. [docker/cli#3812](https://github.com/docker/cli/pull/3812)
* SIGINT (`<Ctrl-c>`) now passes through to running containers instead of causing the CLI to exit. [docker/cli#3849](https://github.com/docker/cli/pull/3849)
* Improve `docker port CONTAINER` UX by sorting ports before printing. [docker/cli#3892](https://github.com/docker/cli/pull/3892)
* API: `GET /containers/{id}/logs` and `POST /containers/{id}/attach` now report which raw-stream format is in use using the `Content-type` response header on API version >= 1.42. [moby/moby#39812](https://github.com/moby/moby/pull/39812)
* Set default sandbox size for Windows layers to 127GB, and ensure that the `--storage-opts` flag applies to all storage on Windows. [moby/moby#41636](https://github.com/moby/moby/pull/41636)
* Remove the plugin section from the containerd configuration file (`/var/run/docker/containerd/containerd.toml`). [moby/moby#41675](https://github.com/moby/moby/pull/41675)
* Reject `null` manifests during tar import. [moby/moby#41842](https://github.com/moby/moby/pull/41842)
* Add shim config for custom runtimes for plugins. [moby/moby#41854](https://github.com/moby/moby/pull/41854)
* Container health checks now resume when the daemon is restarted. [moby/moby#41935](https://github.com/moby/moby/pull/41935)
* Quota is no longer disabled on cleanup of the `btrfs` driver. [moby/moby#42273](https://github.com/moby/moby/pull/42273)
* Host devices that are accessible can now be mounted in `--privileged` rootless containers. [moby/moby#42638](https://github.com/moby/moby/pull/42638)
* Fix incorrect handling of `**/foo` recursive wildcard directory patterns in `.dockerignore`. [moby/moby#42676](https://github.com/moby/moby/pull/42676)
* Extend `docker import --platform` to allow marking an imported image as a foreign architecture. [moby/moby#43103](https://github.com/moby/moby/pull/43103)
* Validation of CPU real-time options is now performed when the daemon starts instead of performing validations for each individual container, allowing startup to fail early. [moby/moby#43131](https://github.com/moby/moby/pull/43131)
* Freeze the `namesgenerator` package against new additions. Users will have to be satisfied with the existing 25359 adjective-name combinations. [moby/moby#43210](https://github.com/moby/moby/pull/43210)
* API: `containers/{id}/attach/ws` only to streams according by `stdin`, `stdout` and `stderr` parameters on API version >= 1.42. [moby/moby#43322](https://github.com/moby/moby/pull/43322)
* Fix UDP traffic in containers not working after the container is restarted under sustained traffic. [moby/moby#43409](https://github.com/moby/moby/pull/43409)
* Add support for pulling images with custom amd64 micro-architecture feature levels as supported by the latest versions of Go, GCC, LLVM, and other compiler tools. [moby/moby#43434](https://github.com/moby/moby/pull/43434)
* Improve validation of invalid JSON requests in the API. [moby/moby#43463](https://github.com/moby/moby/pull/43463)
* Mitigate the impact of slow `exec` starts on health checks. Check timeout now only applies to the duration that the health check command is running. The time it takes to start the command no longer counts against the timeout. [moby/moby#43480](https://github.com/moby/moby/pull/43480)
* Console `tty` size is set immediately on creation. [moby/moby#43593](https://github.com/moby/moby/pull/43593), [moby/moby#43622](https://github.com/moby/moby/pull/43622)
* Fix `overlay2` mounts not being cleaned up after failed container starts, or daemon shutdown. [moby/moby#43659](https://github.com/moby/moby/pull/43659)
* Match manifest list resolution with `containerd`. [moby/moby#43675](https://github.com/moby/moby/pull/43675)
* Skip use of `firewalld` for networking when the daemon is running in rootless mode. [moby/moby#43813](https://github.com/moby/moby/pull/43813)
* Custom NAT networks are now re-created after daemon restart if missing on Windows. [moby/moby#43858](https://github.com/moby/moby/pull/43858)
* Fix terminating the container health-check process when it times out. [moby/moby#43994](https://github.com/moby/moby/pull/43994)
* Fix `live-restore` with restart policies and volume refs. [moby/moby#44237](https://github.com/moby/moby/pull/44237)
* API: Only anonymous volumes now pruned by default on API version >= v1.42. Pass the filter `all=true` to prune named volumes in addition to anonymous. [moby/moby#44259](https://github.com/moby/moby/pull/44259)
* API: Support concurrent calls on the `GET /system/df` endpoint. [moby/moby#42715](https://github.com/moby/moby/pull/42715)
* Improve the reliability of the daemon dumping the stack and exits with code 2 when sent a SIGQUIT. [moby/moby#44831](https://github.com/moby/moby/pull/44831)
* Improve the reliability of `docker logs -f` on Windows, and prevent newlines from being dropped in the `local` log driver. [moby/moby#43294](https://github.com/moby/moby/pull/43294)
* Fix a rare deadlock in the daemon caused by buffering of container logs. [moby/moby#44856](https://github.com/moby/moby/pull/44856)
* Improve error handling in misc filesystem operations so that the daemon can start on a overlayfs backing filesystem. [moby/moby#44834](https://github.com/moby/moby/pull/44834)
* Fix an issue where `--ipc=host` wasn't handled correctly when the daemon is running in rootless mode. [moby/moby#44863](https://github.com/moby/moby/pull/44863)
* Fix a long-standing set of issues where stale conntrack entries caused incorrect routing of UDP traffic for containers. [moby/moby#44752](https://github.com/moby/moby/pull/44752)
* Fix half-registered containers being listed in the API, as well as a nil pointer de-reference and panic caused by using a partially registered container in API calls. [moby/moby#44633](https://github.com/moby/moby/pull/44633)
* Fix a failure to create the `DOCKER-USER` ip6tables chain. [moby/moby#44845](https://github.com/moby/moby/pull/44845)
* Fix a failure to clean up iptables rules when the `ip6tables` command isn't available. [moby/moby#44727](https://github.com/moby/moby/pull/44727)
* Fix an issue where some iptables NAT rules weren't cleaned up after enabling the userland proxy. [moby/moby#44811](https://github.com/moby/moby/pull/44811)
* Fix a potentially leaked process in rare situations where cleaning up a failed attempt to start a container was mishandled. [moby/moby#44400](https://github.com/moby/moby/pull/44400)
* Fix the `CreatedAt` time of a volume reflecting initialization and not creation. [moby/moby#44725](https://github.com/moby/moby/pull/44725)
* Fix an issue where the CLI incorrectly reported an incompatible server instead of an unreachable server in some commands. [docker/cli#3901](https://github.com/docker/cli/pull/3901), [docker/cli#3904](https://github.com/docker/cli/pull/3904)
* Fix broken completion of volumes in Zsh. [docker/cli#2998](https://github.com/docker/cli/pull/2998)
* Improve output of `docker context` when an invalid context is present. [docker/cli#3847](https://github.com/docker/cli/pull/3847)
* Remove ANSI decoration of CLI help annotations when the output isn't a TTY, and added a newline for readability. [docker/cli#3973](https://github.com/docker/cli/pull/3973)
* Add `docker container remove` as an alias for `docker container rm`. [docker/cli#3986](https://github.com/docker/cli/pull/3986)

### [Known issues](#known-issues)

#### [apparmor\_parser (](#apparmor_parser-tracking-issue)[tracking issue](https://github.com/moby/moby/issues/44900))

Some Debian users have reported issues with containers failing to start after upgrading to the 23.0 branch. The error message indicates that the issue is due to a missing `apparmor_parser` binary:

```console
Error response from daemon: AppArmor enabled on system but the docker-default profile could not be loaded: running `apparmor_parser apparmor_parser --version` failed with output:
error: exec: "apparmor_parser": executable file not found in $PATH
Error: failed to start containers: somecontainer
```

The workaround to this issue is to install the `apparmor` package manually:

```console
apt-get install apparmor
```

#### [BuildKit inline cache (](#buildkit-inline-cache-tracking-issue)[tracking issue](https://github.com/moby/moby/issues/44918))

Attempting to build an image with BuildKit's inline cache feature (e.g. `docker build --build-arg BUILDKIT_INLINE_CACHE=1 .`, `docker buildx build --cache-to type=inline .`) will result in the daemon unexpectedly exiting:

```text
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x18 pc=0x147ff00]

goroutine 693 [running]:
github.com/docker/docker/vendor/github.com/moby/buildkit/cache.computeBlobChain.func4.1({0x245cca8, 0x4001394960})
        /go/src/github.com/docker/docker/vendor/github.com/moby/buildkit/cache/blobs.go:206 +0xc90
github.com/docker/docker/vendor/github.com/moby/buildkit/util/flightcontrol.(*call).run(0x40013c2240)
        /go/src/github.com/docker/docker/vendor/github.com/moby/buildkit/util/flightcontrol/flightcontrol.go:121 +0x64
sync.(*Once).doSlow(0x0?, 0x4001328240?)
        /usr/local/go/src/sync/once.go:74 +0x100
sync.(*Once).Do(0x4001328240?, 0x0?)
        /usr/local/go/src/sync/once.go:65 +0x24
created by github.com/docker/docker/vendor/github.com/moby/buildkit/util/flightcontrol.(*call).wait
```

The daemon will restart if configured to do so (e.g. via systemd) after such a crash. The only available mitigation in this release is to avoid performing builds with the inline cache feature enabled.

#### [BuildKit with warm cache (](#buildkit-with-warm-cache-tracking-issue)[tracking issue](https://github.com/moby/moby/issues/44943))

If an image was built with BuildKit on a previous version of the daemon, and is built with a 23.0 daemon, previously cached layers will not be restored correctly. The image may appear to build correctly if no lines are changed in the Dockerfile; however, if partial cache invalidation occurs due to changing some lines in the Dockerfile, the still valid and previously cached layers will not be loaded correctly.

This most often presents as files that should be present in the image not being present in a `RUN` stage, or any other stage that references files, after changing some lines in the Dockerfile:

```text
[+] Building 0.4s (6/6) FINISHED
 => [internal] load build definition from Dockerfile
 => => transferring dockerfile: 102B
 => [internal] load .dockerignore
 => => transferring context: 2B
 => [internal] load metadata for docker.io/library/node:18-alpine
 => [base 1/2] FROM docker.io/library/node:18-alpine@sha256:bc329c7332cffc30c2d4801e38df03cbfa8dcbae2a7a52a449db104794f168a3
 => CACHED [base 2/2] WORKDIR /app
 => ERROR [stage-1 1/1] RUN uname -a
------
 > [stage-1 1/1] RUN uname -a:
#0 0.138 runc run failed: unable to start container process: exec: "/bin/sh": stat /bin/sh: no such file or directory
------
Dockerfile:5
--------------------
   3 |
   4 |     FROM base
   5 | >>> RUN uname -a
   6 |
--------------------
ERROR: failed to solve: process "/bin/sh -c uname -a" did not complete successfully: exit code: 1
```

To mitigate this, the previous build cache must be discarded. `docker builder prune -a` will completely empty the build cache, and allow the affected builds to proceed again by removing the mishandled cache layers.

#### [ipvlan networks (](#ipvlan-networks-tracking-issue)[tracking issue](https://github.com/moby/moby/issues/44925))

When upgrading to the 23.0 branch, the existence of any [ipvlan](https://docs.docker.com/engine/network/drivers/ipvlan/) networks will prevent the daemon from starting:

```text
panic: interface conversion: interface {} is nil, not string

goroutine 1 [running]:
github.com/docker/docker/libnetwork/drivers/ipvlan.(*configuration).UnmarshalJSON(0x40011533b0, {0x400069c2d0, 0xef, 0xef})
        /go/src/github.com/docker/docker/libnetwork/drivers/ipvlan/ipvlan_store.go:196 +0x414
encoding/json.(*decodeState).object(0x4001153440, {0x5597157640?, 0x40011533b0?, 0x559524115c?})
        /usr/local/go/src/encoding/json/decode.go:613 +0x650
encoding/json.(*decodeState).value(0x4001153440, {0x5597157640?, 0x40011533b0?, 0x559524005c?})
        /usr/local/go/src/encoding/json/decode.go:374 +0x40
encoding/json.(*decodeState).unmarshal(0x4001153440, {0x5597157640?, 0x40011533b0?})
        /usr/local/go/src/encoding/json/decode.go:181 +0x204
encoding/json.Unmarshal({0x400069c2d0, 0xef, 0xef}, {0x5597157640, 0x40011533b0})
        /usr/local/go/src/encoding/json/decode.go:108 +0xf4
github.com/docker/docker/libnetwork/drivers/ipvlan.(*configuration).SetValue(0x4000d18050?, {0x400069c2d0?, 0x23?, 0x23?})
        /go/src/github.com/docker/docker/libnetwork/drivers/ipvlan/ipvlan_store.go:230 +0x38
```

To mitigate this, affected users can downgrade and remove the network, then upgrade again. Alternatively, the entire network store can be removed, and networks can be recreated after the upgrade. The network store is located at `/var/lib/docker/network/files/local-kv.db`. If the daemon is using an alternate `--data-root`, substitute `/var/lib/docker` for the alternate path.

#### [Kata Containers (](#kata-containers-tracking-issue)[tracking issue](https://github.com/kata-containers/kata-containers/issues/6154))

The 23.0 branch brings support for alternate containerd shims, such as `io.containerd.runsc.v1` (gVisor) and `io.containerd.kata.v2` (Kata Containers).

When using the Kata Containers runtime, exiting an `exec` session stops the running container, and hangs the connected CLI if a TTY was opened. There is no mitigation at this time beyond avoiding execing into containers running on the Kata runtime.

The root cause of this issue is a long-standing bug in Moby. This will be resolved in a future release. Be advised that support for alternate OCI runtimes is a new feature and that similar issues may be discovered as more users start exercising this functionality.

----
url: https://docs.docker.com/dhi/migration/migrate-from-doi/
----

# Migrate from Alpine or Debian

***

Table of contents

***

Docker Hardened Images (DHI) come in both [Alpine-based and Debian-based variants](https://docs.docker.com/dhi/explore/available/). In many cases, migrating from another image based on these distributions is as simple as changing the base image in your Dockerfile.

This guide helps you migrate from an existing Alpine-based or Debian-based Docker Official Image (DOI) to DHI.

If you're currently using a Debian-based Docker Official Image, migrate to the Debian-based DHI variant. If you're using an Alpine-based image, migrate to the Alpine-based DHI variant. This minimizes changes to package management and dependencies during migration.

## [Key differences](#key-differences)

When migrating from non-hardened images to DHI, be aware of these key differences:

| Item               | Non-hardened images                                            | Docker Hardened Images                                                                                                                                                                                                                                 |
| ------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Package management | Package managers generally available in all images.            | Package managers generally only available in images with a `dev` tag. Runtime images don't contain package managers. Use multi-stage builds and copy necessary artifacts from the build stage to the runtime stage.                                    |
| Non-root user      | Usually runs as root by default                                | Runtime variants run as the nonroot user by default. Ensure that necessary files and directories are accessible to the nonroot user.                                                                                                                   |
| Multi-stage build  | Optional                                                       | Recommended. Use images with a `dev` or `sdk` tags for build stages and non-dev images for runtime.                                                                                                                                                    |
| TLS certificates   | May need to be installed                                       | Contain standard TLS certificates by default. There is no need to install TLS certificates.                                                                                                                                                            |
| Ports              | Can bind to privileged ports (below 1024) when running as root | Run as a nonroot user by default. Applications can't bind to privileged ports (below 1024) when running in Kubernetes or in Docker Engine versions older than 20.10. Configure your application to listen on port 1025 or higher inside the container. |
| Entry point        | Varies by image                                                | May have different entry points than Docker Official Images. Inspect entry points and update your Dockerfile if necessary.                                                                                                                             |
| Shell              | Shell generally available in all images                        | Runtime images don't contain a shell. Use `dev` images in build stages to run shell commands and then copy artifacts to the runtime stage.                                                                                                             |

## [Migration steps](#migration-steps)

### [Step 1: Update the base image in your Dockerfile](#step-1-update-the-base-image-in-your-dockerfile)

Update the base image in your application's Dockerfile to a hardened image. This is typically going to be an image tagged as `dev` or `sdk` because it has the tools needed to install packages and dependencies.

The following example diff snippet from a Dockerfile shows the old base image replaced by the new hardened image.

> Note
>
> You must authenticate to `dhi.io` before you can pull Docker Hardened Images. Use your Docker ID credentials (the same username and password you use for Docker Hub). If you don't have a Docker account, [create one](https://docs.docker.com/accounts/create-account/) for free.
>
> Run `docker login dhi.io` to authenticate.

```diff
- ## Original base image
- FROM golang:1.25

+ ## Updated to use hardened base image
+ FROM dhi.io/golang:1.25-debian12-dev
```

Note that DHI does not have a `latest` tag in order to promote best practices around image versioning. Ensure that you specify the appropriate version tag for your image. To find the right tag, explore the available tags in the [DHI Catalog](https://hub.docker.com/hardened-images/catalog/). In addition, the distribution base is specified in the tag (for example, `-alpine3.22` or `-debian12`), so be sure to select the correct variant for your application.

### [Step 2: Update the runtime image in your Dockerfile](#step-2-update-the-runtime-image-in-your-dockerfile)

> Note
>
> Multi-stage builds are recommended to keep your final image minimal and secure. Single-stage builds are supported, but they include the full `dev` image and therefore result in a larger image with a broader attack surface.

To ensure that your final image is as minimal as possible, you should use a [multi-stage build](https://docs.docker.com/build/building/multi-stage/). All stages in your Dockerfile should use a hardened image. While intermediary stages will typically use images tagged as `dev` or `sdk`, your final runtime stage should use a runtime image.

Utilize the build stage to compile your application and copy the resulting artifacts to the final runtime stage. This ensures that your final image is minimal and secure.

The following example shows a multi-stage Dockerfile with a build stage and runtime stage:

```dockerfile
# Build stage
FROM dhi.io/golang:1.25-debian12-dev AS builder
WORKDIR /app
COPY . .
RUN go build -o myapp

# Runtime stage
FROM dhi.io/golang:1.25-debian12
WORKDIR /app
COPY --from=builder /app/myapp .
ENTRYPOINT ["/app/myapp"]
```

After updating your Dockerfile, build and test your application. If you encounter issues, see the [Troubleshoot](https://docs.docker.com/dhi/troubleshoot/) guide for common problems and solutions.

## [Language-specific examples](#language-specific-examples)

See the examples section for language-specific migration examples:

* [Go](https://docs.docker.com/dhi/migration/examples/go/)
* [Python](https://docs.docker.com/dhi/migration/examples/python/)
* [Node.js](https://docs.docker.com/dhi/migration/examples/node/)

----
url: https://docs.docker.com/ai/docker-agent/integrations/mcp/
----

# MCP mode

***

Table of contents

***

When you run Docker Agent in MCP mode, your agents show up as tools in Claude Desktop and other MCP clients. Instead of switching to a terminal to run your security agent, you ask Claude to use it and Claude calls it for you.

This guide covers setup for Claude Desktop and Claude Code. If you want agents embedded in your editor instead, see [ACP integration](https://docs.docker.com/ai/docker-agent/integrations/acp/).

## [How it works](#how-it-works)

You configure Claude Desktop (or another MCP client) to connect to Docker Agent. Your agents appear in Claude's tool list. When you ask Claude to use one, it calls that agent through the MCP protocol.

Say you have a security agent configured. Ask Claude Desktop "Use the security agent to audit this authentication code" and Claude calls it. The agent runs with its configured tools (filesystem, shell, whatever you gave it), then returns results to Claude.

If your configuration has multiple agents, each one becomes a separate tool. A config with `root`, `designer`, and `engineer` agents gives Claude three tools to choose from. Claude might call the engineer directly or use the root coordinator—depends on your agent descriptions and what you ask for.

## [MCP Gateway](#mcp-gateway)

Docker provides an [MCP Gateway](/ai/mcp-catalog-and-toolkit/mcp-gateway/) that gives agents access to a catalog of pre-configured MCP servers. Instead of configuring individual MCP servers, agents can use the gateway to access tools like web search, database queries, and more.

Configure MCP toolset with gateway reference:

```yaml
agents:
  root:
    toolsets:
      - type: mcp
        ref: docker:duckduckgo # Uses Docker MCP Gateway
```

The `docker:` prefix tells Docker Agent to use the MCP Gateway for this server. See the [MCP Catalog](/ai/mcp-catalog-and-toolkit/catalog/) for available servers and the [MCP Gateway documentation](/ai/mcp-catalog-and-toolkit/mcp-gateway/) for configuration options.

You can also use the [MCP Toolkit](/ai/mcp-catalog-and-toolkit/) to explore and manage MCP servers interactively.

## [Prerequisites](#prerequisites)

Before configuring MCP integration, you need:

* **Docker Agent installed** - See the [installation guide](https://docs.docker.com/ai/docker-agent/#installation)
* **Agent configuration** - A YAML file defining your agent. See the [tutorial](https://docs.docker.com/ai/docker-agent/tutorial/) or [example configurations](https://github.com/docker/docker-agent/tree/main/examples)
* **MCP client** - Claude Desktop, Claude Code, or another MCP-compatible application
* **API keys** - Environment variables for any model providers your agents use (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)

## [MCP client configuration](#mcp-client-configuration)

Your MCP client needs to know how to start Docker Agent and communicate with it. This typically involves adding Docker Agent as an MCP server in your client's configuration.

### [Claude Desktop](#claude-desktop)

Add Docker Agent to your Claude Desktop MCP settings file:

* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Example configuration:

```json
{
  "mcpServers": {
    "myagent": {
      "command": "docker",
      "args": [
        "agent",
        "serve",
        "mcp",
        "/path/to/agent.yml",
        "--working-dir",
        "/Users/yourname/projects"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "your_anthropic_key_here",
        "OPENAI_API_KEY": "your_openai_key_here"
      }
    }
  }
}
```

Configuration breakdown:

* `command`: Full path to your `docker` binary (use `which docker` to find it), or path to `docker-agent` if not using the Docker CLI plugin

* `args`: MCP command arguments:

  * `mcp`: The subcommand to run `docker agent` in MCP mode
  * `dockereng/myagent`: Your agent configuration (local file path or OCI reference)
  * `--working-dir`: Optional working directory for agent execution

* `env`: Environment variables your agents need:

  * Model provider API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
  * Any other environment variables your agents reference

After updating the configuration, restart Claude Desktop. Your agents will appear as available tools.

### [Claude Code](#claude-code)

Add Docker Agent as an MCP server using the `claude mcp add` command:

```console
$ claude mcp add --transport stdio myagent \
  --env OPENAI_API_KEY=$OPENAI_API_KEY \
  --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -- docker agent serve mcp /path/to/agent.yml --working-dir $(pwd)
```

Command breakdown:

* `claude mcp add`: Claude Code command to register an MCP server
* `--transport stdio`: Use stdio transport (standard for local MCP servers)
* `myagent`: Name for this MCP server in Claude Code
* `--env`: Pass environment variables (repeat for each variable)
* `--`: Separates Claude Code options from the MCP server command
* `docker agent serve mcp /path/to/agent.yml`: The Docker Agent MCP command with the path to your agent configuration
* `--working-dir $(pwd)`: Set the working directory for agent execution

After adding the server, your agents will be available as tools in Claude Code sessions.

### [Other MCP clients](#other-mcp-clients)

For other MCP-compatible clients, you need to:

1. Start Docker Agent with `docker agent serve mcp /path/to/agent.yml --working-dir /project/path`
2. Configure the client to communicate with Docker Agent over stdio
3. Pass required environment variables (API keys, etc.)

Consult your MCP client's documentation for specific configuration steps.

## [Agent references](#agent-references)

You can specify your agent configuration as a local file path or OCI registry reference:

```console
# Local file path
$ docker agent serve mcp ./agent.yml

# OCI registry reference
$ docker agent serve mcp agentcatalog/pirate
$ docker agent serve mcp dockereng/myagent:v1.0.0
```

Use the same syntax in MCP client configurations:

```json
{
  "mcpServers": {
    "myagent": {
      "command": "docker",
      "args": ["agent", "serve", "mcp", "agentcatalog/pirate"]
    }
  }
}
```

Registry references let your team use the same agent configuration without managing local files. See [Sharing agents](https://docs.docker.com/ai/docker-agent/sharing-agents/) for details.

## [Designing agents for MCP](#designing-agents-for-mcp)

MCP clients see each of your agents as a separate tool and can call any of them directly. This changes how you should think about agent design compared to running agents with `docker agent run`.

### [Write good descriptions](#write-good-descriptions)

The `description` field tells the MCP client what the agent does. This is how the client decides when to call it. "Analyzes code for security vulnerabilities and compliance issues" is specific. "A helpful security agent" doesn't say what it actually does.

```yaml
agents:
  security_auditor:
    description: Analyzes code for security vulnerabilities and compliance issues
    # Not: "A helpful security agent"
```

### [MCP clients call agents directly](#mcp-clients-call-agents-directly)

The MCP client can call any of your agents, not just root. If you have `root`, `designer`, and `engineer` agents, the client might call the engineer directly instead of going through root. Design each agent to work on its own:

```yaml
agents:
  engineer:
    description: Implements features and writes production code
    instruction: |
      You implement code based on requirements provided.
      You can work independently without a coordinator.
    toolsets:
      - type: filesystem
      - type: shell
```

If an agent needs others to work properly, say so in the description: "Coordinates design and engineering agents to implement complete features."

### [Test each agent on its own](#test-each-agent-on-its-own)

MCP clients call agents individually, so test them that way:

```console
$ docker agent run agent.yml --agent engineer
```

Make sure the agent works without going through root first. Check that it has the right tools and that its instructions make sense when it's called directly.

## [Testing your setup](#testing-your-setup)

Verify your MCP integration works:

1. Restart your MCP client after configuration changes
2. Check that agents appear as available tools
3. Invoke an agent with a simple test prompt
4. Verify the agent can access its configured tools (filesystem, shell, etc.)

If agents don't appear or fail to execute, check:

* `docker agent` command is available and executable
* Agent configuration file exists and is valid
* All required API keys are set in environment variables
* Working directory path exists and has appropriate permissions
* MCP client logs for connection or execution errors

## [Common workflows](#common-workflows)

### [Call specialist agents](#call-specialist-agents)

You have a security agent that knows your compliance rules and common vulnerabilities. In Claude Desktop, paste some authentication code and ask "Use the security agent to review this." The agent checks the code and reports what it finds. You stay in Claude's interface the whole time.

### [Work with agent teams](#work-with-agent-teams)

Your configuration has a coordinator that delegates to designer and engineer agents. Ask Claude Code "Use the coordinator to implement a login form" and the coordinator hands off UI work to the designer and code to the engineer. You get a complete implementation without running `docker agent run` yourself.

### [Run domain-specific tools](#run-domain-specific-tools)

You built an infrastructure agent with custom deployment scripts and monitoring queries. Ask any MCP client "Use the infra agent to check production status" and it runs your tools and returns results. Your deployment knowledge is now available wherever you use MCP clients.

### [Share agents](#share-agents)

Your team keeps agents in an OCI registry. Everyone adds `agentcatalog/security-expert` to their MCP client config. When you update the agent, they get the new version on their next restart. No YAML files to pass around.

## [What's next](#whats-next)

* Use the [MCP Gateway](/ai/mcp-catalog-and-toolkit/mcp-gateway/) to give your agents access to pre-configured MCP servers
* Explore MCP servers interactively with the [MCP Toolkit](/ai/mcp-catalog-and-toolkit/)
* Review the [configuration reference](https://docs.docker.com/ai/docker-agent/reference/config/) for advanced agent setup
* Explore the [toolsets reference](https://docs.docker.com/ai/docker-agent/reference/toolsets/) to learn what tools agents can use
* Add [RAG for codebase search](https://docs.docker.com/ai/docker-agent/rag/) to your agent
* Check the [CLI reference](https://docs.docker.com/ai/docker-agent/reference/cli/) for all `docker agent serve mcp` options
* Browse [example configurations](https://github.com/docker/docker-agent/tree/main/examples) for different agent types

----
url: https://docs.docker.com/reference/cli/docker/dhi/catalog/list/
----

# docker dhi catalog list

***

| Description | List available Docker Hardened Images |
| ----------- | ------------------------------------- |
| Usage       | `docker dhi catalog list`             |

## [Description](#description)

List all available Docker Hardened Images and Helm charts in the catalog

## [Options](#options)

| Option         | Default | Description                                                   |
| -------------- | ------- | ------------------------------------------------------------- |
| `-f, --filter` |         | Filter by name (case-insensitive substring match)             |
| `--fips`       |         | Filter to FIPS compliant images (use --fips=false to exclude) |
| `--json`       |         | Output in JSON format                                         |
| `--stig`       |         | Filter to STIG certified images (use --stig=false to exclude) |
| `--type`       |         | Filter by type (image, helm, chart, or helm-chart)            |

----
url: https://docs.docker.com/guides/reactjs/containerize/
----

# Containerize a React.js Application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Before you begin, make sure the following tools are installed and available on your system:

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client.

> **New to Docker?**\
> Start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide to get familiar with key concepts like images, containers, and Dockerfiles.

***

## [Overview](#overview)

This guide walks you through the complete process of containerizing a React.js application with Docker. You’ll learn how to create a production-ready Docker image using best practices that improve performance, security, scalability, and deployment efficiency.

By the end of this guide, you will:

* Containerize a React.js application using Docker.
* Create and optimize a Dockerfile for production builds.
* Use multi-stage builds to minimize image size.
* Serve the application efficiently with a custom NGINX configuration.
* Follow best practices for building secure and maintainable Docker images.

***

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the git repository:

```console
$ git clone https://github.com/kristiyan-velkov/docker-reactjs-sample
```

***

## [Build the Docker image](#build-the-docker-image)

React.js is a front-end library that compiles into static assets, so the Dockerfile is tailored to optimize how React applications are built and served in a production environment.

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

### [Step 1: Create the Dockerfile](#step-1-create-the-dockerfile)

Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog).

Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/).

> Important
>
> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application.
>
> Official Node.js Docker Images: <https://hub.docker.com/_/node>

Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide.

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Pull the Node.js DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/node:24-alpine3.22-dev
   ```

3. Pull the Nginx DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/nginx:1.28.0-alpine3.21-dev
   ```

In the following Dockerfile, the `FROM` instructions use `dhi.io/node:24-alpine3.22-dev` and `dhi.io/nginx:1.28.0-alpine3.21-dev` as the base images.

```dockerfile
# =========================================
# Stage 1: Build the React.js Application
# =========================================

# Use a lightweight Node.js image for building (customizable via ARG)
FROM dhi.io/node:24-alpine3.22-dev AS builder

# Set the working directory inside the container
WORKDIR /app

# Copy package-related files first to leverage Docker's caching mechanism
COPY package.json package-lock.json* ./

# Install project dependencies using npm ci (ensures a clean, reproducible install)
RUN --mount=type=cache,target=/root/.npm npm ci

# Copy the rest of the application source code into the container
COPY . .

# Build the React.js application (outputs to /app/dist)
RUN npm run build

# =========================================
# Stage 2: Prepare Nginx to Serve Static Files
# =========================================

FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner

# Copy custom Nginx config
COPY nginx.conf /etc/nginx/nginx.conf

# Copy the static build output from the build stage to Nginx's default HTML serving directory
COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html

# Use a non-root user for security best practices
USER nginx

# Expose port 8080 to allow HTTP traffic
# Note: The default NGINX container now listens on port 8080 instead of 80 
EXPOSE 8080

# Start Nginx directly with custom config
ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"]
CMD ["-g", "daemon off;"]
```

Create a file named `Dockerfile` with the following contents:

```dockerfile
# =========================================
# Stage 1: Build the React.js Application
# =========================================
ARG NODE_VERSION=24.12.0-alpine
ARG NGINX_VERSION=alpine3.22

# Use a lightweight Node.js image for building (customizable via ARG)
FROM node:${NODE_VERSION} AS builder

# Set the working directory inside the container
WORKDIR /app

# Copy package-related files first to leverage Docker's caching mechanism
COPY package.json package-lock.json* ./

# Install project dependencies using npm ci (ensures a clean, reproducible install)
RUN --mount=type=cache,target=/root/.npm npm ci

# Copy the rest of the application source code into the container
COPY . .

# Build the React.js application (outputs to /app/dist)
RUN npm run build

# =========================================
# Stage 2: Prepare Nginx to Serve Static Files
# =========================================

FROM nginxinc/nginx-unprivileged:${NGINX_VERSION} AS runner

# Copy custom Nginx config
COPY nginx.conf /etc/nginx/nginx.conf

# Copy the static build output from the build stage to Nginx's default HTML serving directory
COPY --chown=nginx:nginx --from=builder /app/dist /usr/share/nginx/html

# Use a built-in non-root user for security best practices
USER nginx

# Expose port 8080 to allow HTTP traffic
# Note: The default NGINX container now listens on port 8080 instead of 80 
EXPOSE 8080

# Start Nginx directly with custom config
ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"]
CMD ["-g", "daemon off;"]
```

> Note
>
> We are using nginx-unprivileged instead of the standard NGINX image to follow security best practices. Running as a non-root user in the final image:
>
> * Reduces the attack surface
> * Aligns with Docker’s recommendations for container hardening
> * Helps comply with stricter security policies in production environments

### [Step 2: Create the compose.yaml file](#step-2-create-the-composeyaml-file)

Create a file named `compose.yaml` with the following contents:

compose.yaml

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 8080:8080
```

### [Step 3: Create the .dockerignore file](#step-3-create-the-dockerignore-file)

The `.dockerignore` file tells Docker which files and folders to exclude when building the image.

> Note
>
> This helps:
>
> * Reduce image size
> * Speed up the build process
> * Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image.
>
> To learn more, visit the [.dockerignore reference](https://docs.docker.com/reference/dockerfile/#dockerignore-file).

Create a file named `.dockerignore` with the following contents:

```dockerignore
# Ignore dependencies and build output
node_modules/
dist/
out/
.tmp/
.cache/

# Ignore Vite, Webpack, and React-specific build artifacts
.vite/
.vitepress/
.eslintcache
.npm/
coverage/
jest/
cypress/
cypress/screenshots/
cypress/videos/
reports/

# Ignore environment and config files (sensitive data)
*.env*
*.log

# Ignore TypeScript build artifacts (if using TypeScript)
*.tsbuildinfo

# Ignore lockfiles (optional if using Docker for package installation)
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*

# Ignore local development files
.git/
.gitignore
.vscode/
.idea/
*.swp
.DS_Store
Thumbs.db

# Ignore Docker-related files (to avoid copying unnecessary configs)
Dockerfile
.dockerignore
docker-compose.yml
docker-compose.override.yml

# Ignore build-specific cache files
*.lock
```

### [Step 4: Create the `nginx.conf` file](#step-4-create-the-nginxconf-file)

To serve your React.js application efficiently inside the container, you’ll configure NGINX with a custom setup. This configuration is optimized for performance, browser caching, gzip compression, and support for client-side routing.

Create a file named `nginx.conf` in the root of your project directory, and add the following content:

> Note
>
> To learn more about configuring NGINX, see the [official NGINX documentation](https://nginx.org/en/docs/).

```nginx
worker_processes auto;

# Store PID in /tmp (always writable)
pid /tmp/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    # Disable logging to avoid permission issues
    access_log off;
    error_log  /dev/stderr warn;

    # Optimize static file serving
    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  65;
    keepalive_requests 1000;

    # Gzip compression for optimized delivery
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml;
    gzip_min_length 256;
    gzip_vary on;

    server {
        listen       8080;
        server_name  localhost;

        # Root directory where React.js build files are placed
        root /usr/share/nginx/html;
        index index.html;

        # Serve React.js static files with proper caching
        location / {
            try_files $uri /index.html;
        }

        # Serve static assets with long cache expiration
        location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|svg|map)$ {
            expires 1y;
            access_log off;
            add_header Cache-Control "public, immutable";
        }

        # Handle React.js client-side routing
        location /static/ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }
}
```

### [Step 5: Build the React.js application image](#step-5-build-the-reactjs-application-image)

With your custom configuration in place, you're now ready to build the Docker image for your React.js application.

The updated setup includes:

* Optimized browser caching and gzip compression
* Secure, non-root logging to avoid permission issues
* Support for React client-side routing by redirecting unmatched routes to `index.html`

After completing the previous steps, your project directory should now contain the following files:

```text
├── docker-reactjs-sample/
│ ├── Dockerfile
│ ├── .dockerignore
│ ├── compose.yaml
│ └── nginx.conf
```

Now that your Dockerfile is configured, you can build the Docker image for your React.js application.

> Note
>
> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)).

Run the following command from the root of your project:

```console
$ docker build --tag docker-reactjs-sample .
```

What this command does:

* Uses the Dockerfile in the current directory (.)
* Packages the application and its dependencies into a Docker image
* Tags the image as docker-reactjs-sample so you can reference it later

### [Step 6: View local images](#step-6-view-local-images)

After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](https://docs.docker.com/desktop/use-desktop/images/). Since you're already working in the terminal, let's use the Docker CLI.

To list all locally available Docker images, run the following command:

```console
$ docker images
```

Example Output:

```shell
REPOSITORY                TAG               IMAGE ID       CREATED         SIZE
docker-reactjs-sample     latest            f39b47a97156   14 seconds ago   75.8MB
```

This output provides key details about your images:

* **Repository** – The name assigned to the image.
* **Tag** – A version label that helps identify different builds (e.g., latest).
* **Image ID** – A unique identifier for the image.
* **Created** – The timestamp indicating when the image was built.
* **Size** – The total disk space used by the image.

If the build was successful, you should see `docker-reactjs-sample` image listed.

***

## [Run the containerized application](#run-the-containerized-application)

In the previous step, you created a Dockerfile for your React.js application and built a Docker image using the docker build command. Now it’s time to run that image in a container and verify that your application works as expected.

Inside the `docker-reactjs-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:8080>. You should see a simple React.js web application.

Press `ctrl+c` in the terminal to stop your application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `docker-reactjs-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:8080>. You should see a simple web application preview.

To confirm that the container is running, use `docker ps` command:

```console
$ docker ps
```

This will list all active containers along with their ports, names, and status. Look for a container exposing port 8080.

Example Output:

```shell
CONTAINER ID   IMAGE                          COMMAND                  CREATED             STATUS             PORTS                    NAMES
88bced6ade95   docker-reactjs-sample-server   "nginx -c /etc/nginx…"   About a minute ago  Up About a minute  0.0.0.0:8080->8080/tcp   docker-reactjs-sample-server-1
```

To stop the application, run:

```console
$ docker compose down
```

> Note
>
> For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

***

## [Summary](#summary)

In this guide, you learned how to containerize, build, and run a React.js application using Docker. By following best practices, you created a secure, optimized, and production-ready setup.

What you accomplished:

* Created a multi-stage `Dockerfile` that compiles the React.js application and serves the static files using Nginx.
* Created a `.dockerignore` file to exclude unnecessary files and keep the image clean and efficient.
* Built your Docker image using `docker build`.
* Ran the container using `docker compose up`, both in the foreground and in detached mode.
* Verified that the app was running by visiting <http://localhost:8080>.
* Learned how to stop the containerized application using `docker compose down`.

You now have a fully containerized React.js application, running in a Docker container, and ready for deployment across any environment with confidence and consistency.

***

***

## [Next steps](#next-steps)

With your React.js application now containerized, you're ready to move on to the next step.

In the next section, you'll learn how to develop your application using Docker containers, enabling a consistent, isolated, and reproducible development environment across any machine.

[Use containers for React.js development »](https://docs.docker.com/guides/reactjs/develop/)

----
url: https://docs.docker.com/get-started/workshop/06_bind_mounts/
----

# Use bind mounts

***

Table of contents

***

In [part 4](https://docs.docker.com/get-started/workshop/05_persisting_data/), you used a volume mount to persist the data in your database. A volume mount is a great choice when you need somewhere persistent to store your application data.

A bind mount is another type of mount, which lets you share a directory from the host's filesystem into the container. When working on an application, you can use a bind mount to mount source code into the container. The container sees the changes you make to the code immediately, as soon as you save a file. This means that you can run processes in the container that watch for filesystem changes and respond to them.

In this chapter, you'll see how you can use bind mounts and a tool called [nodemon](https://npmjs.com/package/nodemon) to watch for file changes, and then restart the application automatically. There are equivalent tools in most other languages and frameworks.

## [Quick volume type comparisons](#quick-volume-type-comparisons)

The following are examples of a named volume and a bind mount using `--mount`:

* Named volume: `type=volume,src=my-volume,target=/usr/local/data`
* Bind mount: `type=bind,src=/path/to/data,target=/usr/local/data`

The following table outlines the main differences between volume mounts and bind mounts.

|                                              | Named volumes  | Bind mounts |
| -------------------------------------------- | -------------- | ----------- |
| Host location                                | Docker chooses | You decide  |
| Populates new volume with container contents | Yes            | No          |
| Supports Volume Drivers                      | Yes            | No          |

## [Trying out bind mounts](#trying-out-bind-mounts)

Before looking at how you can use bind mounts for developing your application, you can run a quick experiment to get a practical understanding of how bind mounts work.

1. Verify that your `getting-started-app` directory is in a directory defined in Docker Desktop's file sharing setting. This setting defines which parts of your filesystem you can share with containers. For details about accessing the setting, see [File sharing](https://docs.docker.com/desktop/settings-and-maintenance/settings/#file-sharing).

   > Note
   >
   > The **File sharing** tab is only available in Hyper-V mode, because the files are automatically shared in WSL 2 mode and Windows container mode.

2. Open a terminal and change directory to the `getting-started-app` directory.

3. Run the following command to start `bash` in an `ubuntu` container with a bind mount.

   ```console
   $ docker run -it --mount type=bind,src=.,target=/src ubuntu bash
   ```

   ```console
   $ docker run -it --mount "type=bind,src=%cd%,target=/src" ubuntu bash
   ```

   ```console
   $ docker run -it --mount type=bind,src="./",target=/src ubuntu bash
   ```

   ```console
   $ docker run -it --mount "type=bind,src=.,target=/src" ubuntu bash
   ```

   The `--mount type=bind` option tells Docker to create a bind mount, where `src` is the current working directory on your host machine (`getting-started-app`), and `target` is where that directory should appear inside the container (`/src`).

4. After running the command, Docker starts an interactive `bash` session in the root directory of the container's filesystem.

   ```console
   root@ac1237fad8db:/# pwd
   /
   root@ac1237fad8db:/# ls
   bin   dev  home  media  opt   root  sbin  srv  tmp  var
   boot  etc  lib   mnt    proc  run   src   sys  usr
   ```

5. Change directory to the `src` directory.

   This is the directory that you mounted when starting the container. Listing the contents of this directory displays the same files as in the `getting-started-app` directory on your host machine.

   ```console
   root@ac1237fad8db:/# cd src
   root@ac1237fad8db:/src# ls
   Dockerfile  node_modules  package.json  package-lock.json  spec  src  
   ```

6. Create a new file named `myfile.txt`.

   ```console
   root@ac1237fad8db:/src# touch myfile.txt
   root@ac1237fad8db:/src# ls
   Dockerfile  myfile.txt  node_modules  package.json  package-lock.json  spec  src  
   ```

7. Open the `getting-started-app` directory on the host and observe that the `myfile.txt` file is in the directory.

   ```text
   ├── getting-started-app/
   │ ├── Dockerfile
   │ ├── myfile.txt
   │ ├── node_modules/
   │ ├── package.json
   │ ├── package-lock.json
   │ ├── spec/
   │ └── src/
   ```

8. From the host, delete the `myfile.txt` file.

9. In the container, list the contents of the `app` directory once more. Observe that the file is now gone.

   ```console
   root@ac1237fad8db:/src# ls
   Dockerfile  node_modules  package.json  package-lock.json spec  src  
   ```

10. Stop the interactive container session with `Ctrl` + `D`.

That's all for a brief introduction to bind mounts. This procedure demonstrated how files are shared between the host and the container, and how changes are immediately reflected on both sides. Now you can use bind mounts to develop software.

## [Development containers](#development-containers)

Using bind mounts is common for local development setups. The advantage is that the development machine doesn’t need to have all of the build tools and environments installed. With a single docker run command, Docker pulls dependencies and tools.

### [Run your app in a development container](#run-your-app-in-a-development-container)

The following steps describe how to run a development container with a bind mount that does the following:

* Mount your source code into the container
* Install all dependencies
* Start `nodemon` to watch for filesystem changes

You can use the CLI or Docker Desktop to run your container with a bind mount.

1. Make sure you don't have any `getting-started` containers currently running.

2. Run the following command from the `getting-started-app` directory.

   ```console
   $ docker run -dp 127.0.0.1:3000:3000 \
       -w /app --mount type=bind,src=.,target=/app \
       node:24-alpine \
       sh -c "npm install && npm run dev"
   ```

   The following is a breakdown of the command:

   * `-dp 127.0.0.1:3000:3000` - same as before. Run in detached (background) mode and create a port mapping
   * `-w /app` - sets the "working directory" or the current directory that the command will run from
   * `--mount type=bind,src=.,target=/app` - bind mount the current directory from the host into the `/app` directory in the container
   * `node:24-alpine` - the image to use. Note that this is the base image for your app from the Dockerfile
   * `sh -c "npm install && npm run dev"` - the command. You're starting a shell using `sh` (alpine doesn't have `bash`) and running `npm install` to install packages and then running `npm run dev` to start the development server. If you look in the `package.json`, you'll see that the `dev` script starts `nodemon`.

3. You can watch the logs using `docker logs <container-id>`. You'll know you're ready to go when you see this:

   ```console
   $ docker logs -f <container-id>
   nodemon -L src/index.js
   [nodemon] 2.0.20
   [nodemon] to restart at any time, enter `rs`
   [nodemon] watching path(s): *.*
   [nodemon] watching extensions: js,mjs,json
   [nodemon] starting `node src/index.js`
   Using sqlite database at /etc/todos/todo.db
   Listening on port 3000
   ```

   When you're done watching the logs, exit out by hitting `Ctrl`+`C`.

1) Make sure you don't have any `getting-started` containers currently running.

2) Run the following command from the `getting-started-app` directory.

   ```powershell
   $ docker run -dp 127.0.0.1:3000:3000 `
       -w /app --mount "type=bind,src=.,target=/app" `
       node:24-alpine `
       sh -c "npm install && npm run dev"
   ```

   The following is a breakdown of the command:

   * `-dp 127.0.0.1:3000:3000` - same as before. Run in detached (background) mode and create a port mapping
   * `-w /app` - sets the "working directory" or the current directory that the command will run from
   * `--mount "type=bind,src=.,target=/app"` - bind mount the current directory from the host into the `/app` directory in the container
   * `node:24-alpine` - the image to use. Note that this is the base image for your app from the Dockerfile
   * `sh -c "npm install && npm run dev"` - the command. You're starting a shell using `sh` (alpine doesn't have `bash`) and running `npm install` to install packages and then running `npm run dev` to start the development server. If you look in the `package.json`, you'll see that the `dev` script starts `nodemon`.

3) You can watch the logs using `docker logs <container-id>`. You'll know you're ready to go when you see this:

   ```console
   $ docker logs -f <container-id>
   nodemon -L src/index.js
   [nodemon] 2.0.20
   [nodemon] to restart at any time, enter `rs`
   [nodemon] watching path(s): *.*
   [nodemon] watching extensions: js,mjs,json
   [nodemon] starting `node src/index.js`
   Using sqlite database at /etc/todos/todo.db
   Listening on port 3000
   ```

   When you're done watching the logs, exit out by hitting `Ctrl`+`C`.

1. Make sure you don't have any `getting-started` containers currently running.

2. Run the following command from the `getting-started-app` directory.

   ```console
   $ docker run -dp 127.0.0.1:3000:3000 ^
       -w /app --mount "type=bind,src=%cd%,target=/app" ^
       node:24-alpine ^
       sh -c "npm install && npm run dev"
   ```

   The following is a breakdown of the command:

   * `-dp 127.0.0.1:3000:3000` - same as before. Run in detached (background) mode and create a port mapping
   * `-w /app` - sets the "working directory" or the current directory that the command will run from
   * `--mount "type=bind,src=%cd%,target=/app"` - bind mount the current directory from the host into the `/app` directory in the container
   * `node:24-alpine` - the image to use. Note that this is the base image for your app from the Dockerfile
   * `sh -c "npm install && npm run dev"` - the command. You're starting a shell using `sh` (alpine doesn't have `bash`) and running `npm install` to install packages and then running `npm run dev` to start the development server. If you look in the `package.json`, you'll see that the `dev` script starts `nodemon`.

3. You can watch the logs using `docker logs <container-id>`. You'll know you're ready to go when you see this:

   ```console
   $ docker logs -f <container-id>
   nodemon -L src/index.js
   [nodemon] 2.0.20
   [nodemon] to restart at any time, enter `rs`
   [nodemon] watching path(s): *.*
   [nodemon] watching extensions: js,mjs,json
   [nodemon] starting `node src/index.js`
   Using sqlite database at /etc/todos/todo.db
   Listening on port 3000
   ```

   When you're done watching the logs, exit out by hitting `Ctrl`+`C`.

1) Make sure you don't have any `getting-started` containers currently running.

2) Run the following command from the `getting-started-app` directory.

   ```console
   $ docker run -dp 127.0.0.1:3000:3000 \
       -w //app --mount type=bind,src="./",target=/app \
       node:24-alpine \
       sh -c "npm install && npm run dev"
   ```

   The following is a breakdown of the command:

   * `-dp 127.0.0.1:3000:3000` - same as before. Run in detached (background) mode and create a port mapping
   * `-w //app` - sets the "working directory" or the current directory that the command will run from
   * `--mount type=bind,src="/.",target=/app` - bind mount the current directory from the host into the `/app` directory in the container
   * `node:24-alpine` - the image to use. Note that this is the base image for your app from the Dockerfile
   * `sh -c "npm install && npm run dev"` - the command. You're starting a shell using `sh` (alpine doesn't have `bash`) and running `npm install` to install packages and then running `npm run dev` to start the development server. If you look in the `package.json`, you'll see that the `dev` script starts `nodemon`.

3) You can watch the logs using `docker logs <container-id>`. You'll know you're ready to go when you see this:

   ```console
   $ docker logs -f <container-id>
   nodemon -L src/index.js
   [nodemon] 2.0.20
   [nodemon] to restart at any time, enter `rs`
   [nodemon] watching path(s): *.*
   [nodemon] watching extensions: js,mjs,json
   [nodemon] starting `node src/index.js`
   Using sqlite database at /etc/todos/todo.db
   Listening on port 3000
   ```

   When you're done watching the logs, exit out by hitting `Ctrl`+`C`.

Make sure you don't have any `getting-started` containers currently running.

Run the image with a bind mount.

1. Select the search box at the top of Docker Desktop.

2. In the search window, select the **Images** tab.

3. In the search box, specify the container name, `getting-started`.

   > Tip
   >
   > Use the search filter to filter images and only show **Local images**.

4. Select your image and then select **Run**.

5. Select **Optional settings**.

6. In **Host path**, specify the path to the `getting-started-app` directory on your host machine.

7. In **Container path**, specify `/app`.

8. Select **Run**.

You can watch the container logs using Docker Desktop.

1. Select **Containers** in Docker Desktop.
2. Select your container name.

You'll know you're ready to go when you see this:

```console
nodemon -L src/index.js
[nodemon] 2.0.20
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,json
[nodemon] starting `node src/index.js`
Using sqlite database at /etc/todos/todo.db
Listening on port 3000
```

### [Develop your app with the development container](#develop-your-app-with-the-development-container)

Update your app on your host machine and see the changes reflected in the container.

1. In the `src/static/js/app.js` file, on line 109, change the "Add Item" button to simply say "Add":

   ```diff
   - {submitting ? 'Adding...' : 'Add Item'}
   + {submitting ? 'Adding...' : 'Add'}
   ```

   Save the file.

2. Refresh the page in your web browser, and you should see the change reflected almost immediately because of the bind mount. Nodemon detects the change and restarts the server. It might take a few seconds for the Node server to restart. If you get an error, try refreshing after a few seconds.

3. Feel free to make any other changes you'd like to make. Each time you make a change and save a file, the change is reflected in the container because of the bind mount. When Nodemon detects a change, it restarts the app inside the container automatically. When you're done, stop the container and build your new image using:

   ```console
   $ docker build -t getting-started .
   ```

## [Summary](#summary)

At this point, you can persist your database and see changes in your app as you develop without rebuilding the image.

In addition to volume mounts and bind mounts, Docker also supports other mount types and storage drivers for handling more complex and specialized use cases.

Related information:

* [docker CLI reference](/reference/cli/docker/)
* [Manage data in Docker](https://docs.docker.com/storage/)

## [Next steps](#next-steps)

In order to prepare your app for production, you need to migrate your database from working in SQLite to something that can scale a little better. For simplicity, you'll keep using a relational database and switch your application to use MySQL. But, how should you run MySQL? How do you allow the containers to talk to each other? You'll learn about that in the next section.

[Multi container apps](https://docs.docker.com/get-started/workshop/07_multi_container/)

----
url: https://docs.docker.com/engine/network/drivers/host/
----

# Host network driver

***

Table of contents

***

If you use the `host` network mode for a container, that container's network stack isn't isolated from the Docker host (the container shares the host's networking namespace), and the container doesn't get its own IP-address allocated. For instance, if you run a container which binds to port 80 and you use `host` networking, the container's application is available on port 80 on the host's IP address.

> Note
>
> Given that the container does not have its own IP-address when using `host` mode networking, [port-mapping](https://docs.docker.com/engine/network/drivers/overlay/#publish-ports) doesn't take effect, and the `-p`, `--publish`, `-P`, and `--publish-all` option are ignored, producing a warning instead:
>
> ```console
> WARNING: Published ports are discarded when using host network mode
> ```

Host mode networking can be useful for the following use cases:

* To optimize performance
* In situations where a container needs to handle a large range of ports

This is because it doesn't require network address translation (NAT), and no "userland-proxy" is created for each port.

## [Platform support](#platform-support)

The host networking driver is supported on:

* Docker Engine on Linux
* Docker Desktop version 4.34 and later (requires enabling the feature in Settings)

> Note
>
> For Docker Desktop users, see the [Docker Desktop section](#docker-desktop) below for setup instructions.

You can also use a `host` network for a swarm service, by passing `--network host` to the `docker service create` command. In this case, control traffic (traffic related to managing the swarm and the service) is still sent across an overlay network, but the individual swarm service containers send data using the Docker daemon's host network and ports. This creates some extra limitations. For instance, if a service container binds to port 80, only one service container can run on a given swarm node.

## [Docker Desktop](#docker-desktop)

Host networking is supported on Docker Desktop version 4.34 and later. To enable this feature:

1. Sign in to your Docker account in Docker Desktop.
2. Navigate to **Settings**.
3. Under the **Resources** tab, select **Network**.
4. Check the **Enable host networking** option.
5. Select **Apply and restart**.

This feature works in both directions. This means you can access a server that is running in a container from your host and you can access servers running on your host from any container that is started with host networking enabled. TCP as well as UDP are supported as communication protocols.

### [Examples](#examples)

The following command starts netcat in a container that listens on port `8000`:

```console
$ docker run --rm -it --net=host nicolaka/netshoot nc -lkv 0.0.0.0 8000
```

Port `8000` will then be available on the host and you can connect to it with the following command from another terminal:

```console
$ nc localhost 8000
```

What you type in here will then appear on the terminal where the container is running.

To access a service running on the host from the container, you can start a container with host networking enabled with this command:

```console
$ docker run --rm -it --net=host nicolaka/netshoot
```

If you then want to access a service on your host from the container (in this example a web server running on port `80`), you can do it like this:

```console
$ nc localhost 80
```

### [Limitations](#limitations)

* Processes inside the container cannot bind to the IP addresses of the host because the container has no direct access to the interfaces of the host.
* The host network feature of Docker Desktop works on layer 4. This means that unlike with Docker on Linux, network protocols that operate below TCP or UDP are not supported.
* This feature doesn't work with Enhanced Container Isolation enabled, since isolating your containers from the host and allowing them access to the host network contradict each other.
* Only Linux containers are supported. Host networking does not work with Windows containers.

## [Usage example](#usage-example)

This example shows how to start an Nginx container that binds directly to port 80 on the Docker host. From a networking perspective, this provides the same level of isolation as if Nginx were running directly on the host, but the container remains isolated in all other aspects (storage, process namespace, user namespace).

### [Prerequisites](#prerequisites)

* Port 80 must be available on the Docker host. To make Nginx listen on a different port, see the [Nginx image documentation](https://hub.docker.com/_/nginx/).
* The host networking driver only works on Linux hosts, and as an opt-in feature in Docker Desktop version 4.34 and later.

### [Steps](#steps)

1. Create and start the container as a detached process. The `--rm` option removes the container when it exits. The `-d` flag starts it in the background:

   ```console
   $ docker run --rm -d --network host --name my_nginx nginx
   ```

2. Access Nginx by browsing to <http://localhost:80/>.

3. Examine your network stack:

   Check all network interfaces and verify that no new interface was created:

   ```console
   $ ip addr show
   ```

   Verify which process is bound to port 80 using `netstat`. You need `sudo` because the process is owned by the Docker daemon user:

   ```console
   $ sudo netstat -tulpn | grep :80
   ```

4. Stop the container. It's removed automatically because of the `--rm` option:

   ```console
   $ docker container stop my_nginx
   ```

## [Next steps](#next-steps)

* Learn about [networking from the container's point of view](https://docs.docker.com/engine/network/)
* Learn about [bridge networks](https://docs.docker.com/engine/network/drivers/bridge/)
* Learn about [overlay networks](https://docs.docker.com/engine/network/drivers/overlay/)

----
url: https://docs.docker.com/reference/cli/docker/container/diff/
----

# docker container diff

***

| Description                                                               | Inspect changes to files or directories on a container's filesystem |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Usage                                                                     | `docker container diff CONTAINER`                                   |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker diff`                                                       |

## [Description](#description)

List the changed files and directories in a container᾿s filesystem since the container was created. Three different types of change are tracked:

| Symbol | Description                     |
| ------ | ------------------------------- |
| `A`    | A file or directory was added   |
| `D`    | A file or directory was deleted |
| `C`    | A file or directory was changed |

You can use the full or shortened container ID or the container name set using `docker run --name` option.

## [Examples](#examples)

Inspect the changes to an `nginx` container:

```console
$ docker diff 1fdfd1f54c1b

C /dev
C /dev/console
C /dev/core
C /dev/stdout
C /dev/fd
C /dev/ptmx
C /dev/stderr
C /dev/stdin
C /run
A /run/nginx.pid
C /var/lib/nginx/tmp
A /var/lib/nginx/tmp/client_body
A /var/lib/nginx/tmp/fastcgi
A /var/lib/nginx/tmp/proxy
A /var/lib/nginx/tmp/scgi
A /var/lib/nginx/tmp/uwsgi
C /var/log/nginx
A /var/log/nginx/access.log
A /var/log/nginx/error.log
```

----
url: https://docs.docker.com/reference/cli/docker/sandbox/network/
----

# docker sandbox network

***

| Description | Manage sandbox networking |
| ----------- | ------------------------- |
| Usage       | `docker sandbox network`  |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Manage sandbox networking

## [Examples](#examples)

### [View network logs](#view-network-logs)

```console
$ docker sandbox network log
```

### [Configure proxy for a sandbox](#configure-proxy-for-a-sandbox)

```console
$ docker sandbox network proxy my-sandbox --block-host example.com
```

See the subcommands for more details:

* [`docker sandbox network log`](/reference/cli/docker/sandbox/network/log/) - Show network logs
* [`docker sandbox network proxy`](/reference/cli/docker/sandbox/network/proxy/) - Manage proxy configuration

## [Subcommands](#subcommands)

| Command                                                                                               | Description                              |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| [`docker sandbox network log`](https://docs.docker.com/reference/cli/docker/sandbox/network/log/)     | Show network logs                        |
| [`docker sandbox network proxy`](https://docs.docker.com/reference/cli/docker/sandbox/network/proxy/) | Manage proxy configuration for a sandbox |

----
url: https://docs.docker.com/dhi/troubleshoot/
----

# Troubleshoot

***

Table of contents

***

This page covers debugging techniques and common issues you may encounter while migrating to or using Docker Hardened Images (DHIs).

## [General debugging](#general-debugging)

Docker Hardened Images prioritize minimalism and security, which means they intentionally leave out many common debugging tools (like shells or package managers). This makes direct troubleshooting difficult without introducing risk. To address this, you can use [Docker Debug](/reference/cli/docker/debug/), a secure workflow that temporarily attaches an ephemeral debug container to a running service or image without modifying the original image.

This section shows how to debug Docker Hardened Images locally during development. With Docker Debug, you can also debug containers remotely using the `--host` option.

### [Use Docker Debug](#use-docker-debug)

#### [Step 1: Run a container from a Hardened Image](#step-1-run-a-container-from-a-hardened-image)

Start with a DHI-based container that simulates an issue:

```console
$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)"
```

This container doesn't include a shell or tools like `ps`, `top`, or `cat`.

If you try:

```console
$ docker exec -it myapp sh
```

You'll see:

```console
exec: "sh": executable file not found in $PATH
```

#### [Step 2: Use Docker Debug to inspect the container](#step-2-use-docker-debug-to-inspect-the-container)

Use the `docker debug` command to attach a temporary, tool-rich debug container to the running instance.

```console
$ docker debug myapp
```

From here, you can inspect running processes, network status, or mounted files.

For example, to check running processes:

```console
$ ps aux
```

Type `exit` to leave the container when done.

### [Alternative debugging approaches](#alternative-debugging-approaches)

In addition to using Docker Debug, you can also use the following approaches for debugging DHI containers.

#### [Use the -dev variant](#use-the--dev-variant)

Docker Hardened Images offer a `-dev` variant that includes a shell and a package manager to install debugging tools. Simply replace the image tag with `-dev`:

```console
$ docker run -it --rm dhi.io/python:3.13-dev sh
```

Type `exit` to leave the container when done. Note that using the `-dev` variant increases the attack surface and it is not recommended as a runtime for production environments.

#### [Mount debugging tools with image mounts](#mount-debugging-tools-with-image-mounts)

You can use the image mount feature to mount debugging tools into your container without modifying the base image.

##### [Step 1: Run a container from a hardened image](#step-1-run-a-container-from-a-hardened-image-1)

Start with a DHI-based container that simulates an issue:

```console
$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)"
```

##### [Step 2: Mount debugging tools into the container](#step-2-mount-debugging-tools-into-the-container)

Run a new container that mounts a tool-rich image (like `busybox`) into the running container's namespace:

```console
$ docker run --rm -it --pid container:myapp \
  --mount type=image,source=busybox,destination=/dbg,ro \
  dhi.io/python:3.13 /dbg/bin/sh
```

This mounts the BusyBox image at `/dbg`, giving you access to its tools while keeping your original container image unchanged. Since the hardened Python image doesn't include standard utilities, you need to use the full path to the mounted tools:

```console
$ /dbg/bin/ls /
$ /dbg/bin/ps aux
$ /dbg/bin/cat /etc/os-release
```

Type `exit` to leave the container when done.

## [Common issues](#common-issues)

The following are specific issues you may encounter when working with Docker Hardened Images, along with recommended solutions.

### [Permissions](#permissions)

DHIs run as a nonroot user by default for enhanced security. This can result in permission issues when accessing files or directories. Ensure your application files and runtime directories are owned by the expected UID/GID or have appropriate permissions.

To find out which user a DHI runs as, check the repository page for the image on Docker Hub. See [View image variant details](https://docs.docker.com/dhi/how-to/explore/#image-variant-details) for more information.

### [Privileged ports](#privileged-ports)

Nonroot containers cannot bind to ports below 1024 by default. This is enforced by both the container runtime and the kernel (especially in Kubernetes and Docker Engine < 20.10).

Inside the container, configure your application to listen on an unprivileged port (1025 or higher). For example `docker run -p 80:8080 my-image` maps port 8080 in the container to port 80 on the host, allowing you to access it without needing root privileges.

### [No shell](#no-shell)

Runtime DHIs omit interactive shells like `sh` or `bash`. If your build or tooling assumes a shell is present (e.g., for `RUN` instructions), use a `dev` variant of the image in an earlier build stage and copy the final artifact into the runtime image.

To find out which shell, if any, a DHI has, check the repository page for the image on Docker Hub. See [View image variant details](https://docs.docker.com/dhi/how-to/explore/#image-variant-details) for more information.

Also, use Docker Debug when you need shell access to a running container. For more details, see [General debugging](#general-debugging).

### [Entry point differences](#entry-point-differences)

DHIs may define different entry points compared to Docker Official Images (DOIs) or other community images.

To find out the ENTRYPOINT or CMD for a DHI, check the repository page for the image on Docker Hub. See [View image variant details](https://docs.docker.com/dhi/how-to/explore/#image-variant-details) for more information.

### [No package manager](#no-package-manager)

Runtime Docker Hardened Images are stripped down for security and minimal attack surface. As a result, they don't include a package manager such as `apk` or `apt`. This means you can't install additional software directly in the runtime image.

If your build or application setup requires installing packages (for example, to compile code, install runtime dependencies, or add diagnostic tools), use a `dev` variant of the image in a build stage. Then, copy only the necessary artifacts into the final runtime image.

----
url: https://docs.docker.com/guides/testcontainers-java-quarkus/create-project/
----

# Create the Quarkus project

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Quarkus project from [code.quarkus.io](https://code.quarkus.io/) by selecting the **RESTEasy Classic**, **RESTEasy Classic Jackson**, **Hibernate Validator**, **Hibernate ORM with Panache**, **JDBC Driver - PostgreSQL**, and **Flyway** extensions.

Alternatively, clone the [guide repository](https://github.com/testcontainers/tc-guide-testcontainers-in-quarkus-applications).

The key dependencies in `pom.xml` are:

```xml
<properties>
    <quarkus.platform.version>3.22.3</quarkus.platform.version>
</properties>
<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-hibernate-orm-panache</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-flyway</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-hibernate-validator</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-resteasy</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-resteasy-jackson</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-jdbc-postgresql</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-junit5</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

## [Create the JPA entity](#create-the-jpa-entity)

Hibernate ORM with Panache supports the Active Record pattern and the Repository pattern to simplify JPA usage. This guide uses the Active Record pattern.

Create `Customer.java` by extending `PanacheEntity`. This gives the entity built-in persistence methods such as `persist()`, `listAll()`, and `findById()`.

```java
package com.testcontainers.demo;

import io.quarkus.hibernate.orm.panache.PanacheEntity;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.Table;

@Entity
@Table(name = "customers")
public class Customer extends PanacheEntity {

    @Column(nullable = false)
    public String name;

    @Column(nullable = false, unique = true)
    public String email;

    public Customer() {}

    public Customer(Long id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }
}
```

## [Create the CustomerService CDI bean](#create-the-customerservice-cdi-bean)

Create a `CustomerService` class annotated with `@ApplicationScoped` and `@Transactional` to handle persistence operations:

```java
package com.testcontainers.demo;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.transaction.Transactional;
import java.util.List;

@ApplicationScoped
@Transactional
public class CustomerService {

    public List<Customer> getAll() {
        return Customer.listAll();
    }

    public Customer create(Customer customer) {
        customer.persist();
        return customer;
    }
}
```

## [Add the Flyway database migration script](#add-the-flyway-database-migration-script)

Create `src/main/resources/db/migration/V1__init_database.sql`:

```sql
create sequence customers_seq start with 1 increment by 50;

create table customers
(
    id    bigint DEFAULT nextval('customers_seq') not null,
    name  varchar                                 not null,
    email varchar                                 not null,
    primary key (id)
);

insert into customers(name, email)
values ('john', 'john@mail.com'),
       ('rambo', 'rambo@mail.com');
```

Enable Flyway migrations in `src/main/resources/application.properties`:

```properties
quarkus.flyway.migrate-at-start=true
```

## [Create the REST API endpoints](#create-the-rest-api-endpoints)

Create `CustomerResource.java` with endpoints for fetching all customers and creating a customer:

```java
package com.testcontainers.demo;

import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;
import java.util.List;

@Path("/api/customers")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class CustomerResource {
    private final CustomerService customerService;

    public CustomerResource(CustomerService customerService) {
        this.customerService = customerService;
    }

    @GET
    public List<Customer> getAllCustomers() {
        return customerService.getAll();
    }

    @POST
    public Response createCustomer(Customer customer) {
        var savedCustomer = customerService.create(customer);
        return Response.status(Response.Status.CREATED).entity(savedCustomer).build();
    }
}
```

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-java-quarkus/write-tests/)

----
url: https://docs.docker.com/dhi/migration/examples/
----

# Migration examples

***

Table of contents

***

This section provides detailed migration examples for common programming languages and frameworks.

## [Available examples](#available-examples)

### [Go](/dhi/migration/examples/go/)

[Learn how to migrate Go applications to Docker Hardened Images with practical examples and best practices.](/dhi/migration/examples/go/)

### [Python](/dhi/migration/examples/python/)

[Learn how to migrate Python applications to Docker Hardened Images with practical examples and best practices.](/dhi/migration/examples/python/)

### [Node.js](/dhi/migration/examples/node/)

[Learn how to migrate Node.js applications to Docker Hardened Images with practical examples and best practices.](/dhi/migration/examples/node/)

In addition to this documentation, each Docker Hardened Image repository in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog) includes image-specific guidance and best practices for migrating applications built with that language or framework.

----
url: https://docs.docker.com/engine/release-notes/26.0/
----

# Docker Engine 26.0 release notes

***

Table of contents

***

This page describes the latest changes, additions, known issues, and fixes for Docker Engine version 26.0.

For more information about:

* Deprecated and removed features, see [Deprecated Engine Features](https://docs.docker.com/engine/deprecated/).
* Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history/).

## [26.0.2](#2602)

*2024-04-18*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 26.0.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A26.0.2)
* [moby/moby, 26.0.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A26.0.2)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v26.0.2/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v26.0.2/docs/api/version-history.md).

### [Security](#security)

This release contains a security fix for [CVE-2024-32473](https://github.com/moby/moby/security/advisories/GHSA-x84c-p2g9-rqv9), an unexpected configuration of IPv6 on IPv4-only interfaces.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* [CVE-2024-32473](https://github.com/moby/moby/security/advisories/GHSA-x84c-p2g9-rqv9): Ensure IPv6 is disabled on interfaces only allocated an IPv4 address by the engine. [moby#GHSA-x84c-p2g9-rqv9](https://github.com/moby/moby/security/advisories/GHSA-x84c-p2g9-rqv9)

## [26.0.1](#2601)

*2024-04-11*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 26.0.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A26.0.1)
* [moby/moby, 26.0.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A26.0.1)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v26.0.1/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v26.0.1/docs/api/version-history.md).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

* Fix a regression that meant network interface specific `--sysctl` options prevented container startup. [moby/moby#47646](https://github.com/moby/moby/pull/47646)
* Remove erroneous `platform` from image `config` OCI descriptor in `docker save` output. [moby/moby#47694](https://github.com/moby/moby/pull/47694)
* containerd image store: OCI archives produced by `docker save` will now have a non-empty `mediaType` field in `index.json` [moby/moby#47701](https://github.com/moby/moby/pull/47701)
* Fix a regression that prevented the internal resolver from forwarding requests from IPvlan L3 networks to external resolvers. [moby/moby#47705](https://github.com/moby/moby/pull/47705)
* Prevent the use of external resolvers in IPvlan and Macvlan networks created with no parent interface specified. [moby/moby#47705](https://github.com/moby/moby/pull/47705)

### [Packaging updates](#packaging-updates)

* Update Go runtime to 1.21.9 [moby/moby#47671](https://github.com/moby/moby/pull/47671), [docker/cli#4987](https://github.com/docker/cli/pull/4987)
* Update Compose to [v1.26.1 ](https://github.com/docker/compose/releases/tag/v2.26.1), [docker/docker-ce-packaging#1009](https://github.com/docker/docker-ce-packaging/pull/1009)
* Update containerd to [v1.7.15](https://github.com/containerd/containerd/releases/tag/v1.7.15) (static binaries only) [moby/moby#47692](https://github.com/moby/moby/pull/47692)

## [26.0.0](#2600)

*2024-03-20*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 26.0.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A26.0.0)
* [moby/moby, 26.0.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A26.0.0)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v26.0.0/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v26.0.0/docs/api/version-history.md).

### [Security](#security-1)

This release contains a security fix for [CVE-2024-29018](https://github.com/moby/moby/security/advisories/GHSA-mq39-4gv4-mvpx), a potential data exfiltration from 'internal' networks via authoritative DNS servers.

### [New](#new)

* Add `Subpath` field to the `VolumeOptions` making it possible to mount a subpath of a volume. [moby/moby#45687](https://github.com/moby/moby/pull/45687)
* Add `volume-subpath` support to the mount flag (`--mount type=volume,...,volume-subpath=<subpath>`). [docker/cli#4331](https://github.com/docker/cli/pull/4331)
* Accept `=` separators and `[ipv6]` in compose files for `docker stack deploy`. [docker/cli#4860](https://github.com/docker/cli/pull/4860)
* rootless: Add support for enabling host loopback by setting the `DOCKERD_ROOTLESS_ROOTLESSKIT_DISABLE_HOST_LOOPBACK` environment variable to `false` (defaults to `true`). This lets containers connect to the host by using IP address `10.0.2.2`. [moby/moby#47352](https://github.com/moby/moby/pull/47352)
* containerd image store: `docker image ls` no longer creates duplicates entries for multi-platform images. [moby/moby#45967](https://github.com/moby/moby/pull/45967)
* containerd image store: Send Prometheus metrics. [moby/moby#47555](https://github.com/moby/moby/pull/47555)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

* [CVE-2024-29018](https://github.com/moby/moby/security/advisories/GHSA-mq39-4gv4-mvpx): Do not forward requests to external DNS servers for a container that is only connected to an 'internal' network. Previously, requests were forwarded if the host's DNS server was running on a loopback address, like systemd's 127.0.0.53. [moby/moby#47589](https://github.com/moby/moby/pull/47589)

* Ensure that a generated MAC address is not restored when a container is restarted, but a configured MAC address is preserved. [moby/moby#47233](https://github.com/moby/moby/pull/47233)

  > Warning
  >
  > Containers created using Docker Engine 25.0.0 may have duplicate MAC addresses, they must be re-created. Containers created using version 25.0.0 or 25.0.1 with user-defined MAC addresses will get generated MAC addresses when they are started using 25.0.2. They must also be re-created.

* Always attempt to enable IPv6 on a container's loopback interface, and only include IPv6 in `/etc/hosts` if successful. [moby/moby#47062](https://github.com/moby/moby/pull/47062)

  > Note
  >
  > By default, IPv6 will remain enabled on a container's loopback interface when the container is not connected to an IPv6-enabled network. For example, containers that are only connected to an IPv4-only network now have the `::1` address on their loopback interface.
  >
  > To disable IPv6 in a container, use option `--sysctl net.ipv6.conf.all.disable_ipv6=1` in the `create` or `run` command, or the equivalent `sysctls` option in the service configuration section of a Compose file.
  >
  > If IPv6 is not available in a container because it has been explicitly disabled for the container, or the host's networking stack does not have IPv6 enabled (or for any other reason) the container's `/etc/hosts` file will not include IPv6 entries.

* Fix `ADD` Dockerfile instruction failing with `lsetxattr <file>: operation not supported` when unpacking archive with xattrs onto a filesystem that doesn't support them. [moby/moby#47175](https://github.com/moby/moby/pull/47175)

* Fix `docker container start` failing when used with `--checkpoint`. [moby/moby#47456](https://github.com/moby/moby/pull/47456)

* Restore IP connectivity between the host and containers on an internal bridge network. [moby/moby#47356](https://github.com/moby/moby/pull/47356)

* Do not enforce new validation rules for existing swarm networks. [moby/moby#47361](https://github.com/moby/moby/pull/47361)

* Restore DNS names for containers in the default "nat" network on Windows. [moby/moby#47375](https://github.com/moby/moby/pull/47375)

* Print hint when invoking `docker image ls` with ambiguous argument. [docker/cli#4849](https://github.com/docker/cli/pull/4849)

* Cleanup `@docker_cli_[UUID]` files on OpenBSD. [docker/cli#4862](https://github.com/docker/cli/pull/4862)

* Add explicit [deprecation notice](https://github.com/docker/cli/blob/v26.0.0/docs/deprecated.md#unauthenticated-tcp-connections) message when using remote TCP connections without TLS. [docker/cli#4928](https://github.com/docker/cli/pull/4928), [moby/moby#47556](https://github.com/moby/moby/pull/47556)

* Use IPv6 nameservers from the host's `resolv.conf` as upstream resolvers for Docker Engine's internal DNS, rather than listing them in the container's `resolv.conf`. [moby/moby#47512](https://github.com/moby/moby/pull/47512)

* containerd image store: Isolate images with different containerd namespaces when `--userns-remap` option is used. [moby/moby#46786](https://github.com/moby/moby/pull/46786)

* containerd image store: Fix image pull not emitting `Pulling fs layer` status. [moby/moby#47432](https://github.com/moby/moby/pull/47432)

### [API](#api)

* To preserve backwards compatibility, read-only mounts are not recursive by default when using older clients (API version < v1.44). [moby/moby#47391](https://github.com/moby/moby/pull/47391)
* `GET /images/{id}/json` omits the `Created` field (previously it was `0001-01-01T00:00:00Z`) if the `Created` field is missing from the image config. [moby/moby#47451](https://github.com/moby/moby/pull/47451)
* Populate a missing `Created` field in `GET /images/{id}/json` with `0001-01-01T00:00:00Z` for API version <= 1.43. [moby/moby#47387](https://github.com/moby/moby/pull/47387)
* The `is_automated` field in the `POST /images/search` endpoint results is always `false` now. Consequently, searching for `is-automated=true` will yield no results, while `is-automated=false` will be a no-op. [moby/moby#47465](https://github.com/moby/moby/pull/47465)
* Remove `Container` and `ContainerConfig` fields from the `GET /images/{name}/json` response. [moby/moby#47430](https://github.com/moby/moby/pull/47430)

### [Packaging updates](#packaging-updates-1)

* Update BuildKit to [v0.13.1](https://github.com/moby/buildkit/releases/tag/v0.13.1). [moby/moby#47582](https://github.com/moby/moby/pull/47582)
* Update Buildx to [v0.13.1](https://github.com/docker/buildx/releases/tag/v0.13.1). [docker/docker-ce-packaging#1000](https://github.com/docker/docker-ce-packaging/pull/1000)
* Update Compose to [v2.25.0](https://github.com/docker/compose/releases/tag/v2.25.0). [docker/docker-ce-packaging#1002](https://github.com/docker/docker-ce-packaging/pull/1002)
* Update Go runtime to [1.21.8](https://go.dev/doc/devel/release#go1.21.8). [moby/moby#47502](https://github.com/moby/moby/pull/47502)
* Update RootlessKit to [v2.0.2](https://github.com/rootless-containers/rootlesskit/releases/tag/v2.0.2). [moby/moby#47508](https://github.com/moby/moby/pull/47504)
* Update containerd to v1.7.13 (static binaries only) [moby/moby#47278](https://github.com/moby/moby/pull/47278)
* Update runc binary to v1.1.12 [moby/moby#47268](https://github.com/moby/moby/pull/47268)
* Update OTel to v0.46.1 / v1.21.0 [moby/moby#47245](https://github.com/moby/moby/pull/47245)

### [Removed](#removed)

* Remove `Container` and `ContainerConfig` fields from the `GET /images/{name}/json` response. [moby/moby#47430](https://github.com/moby/moby/pull/47430)

* Deprecate the ability to accept remote TCP connections without TLS. [Deprecation notice](https://github.com/docker/cli/tree/v26.0.0/deprecation.md#unauthenticated-tcp-connections) [docker/cli#4928](https://github.com/docker/cli/pull/4928) [moby/moby#47556](https://github.com/moby/moby/pull/47556).

* Remove deprecated API versions (API < v1.24) [moby/moby#47155](https://github.com/moby/moby/pull/47155)

* Disable pulling of deprecated image formats by default. These image formats are deprecated, and support will be removed in a future version. [moby/moby#47459](https://github.com/moby/moby/pull/47459)

* image: remove deprecated IDFromDigest [moby/moby#47198](https://github.com/moby/moby/pull/47198)

* Remove the deprecated `github.com/docker/docker/pkg/loopback` package. [moby/moby#47128](https://github.com/moby/moby/pull/47128)

* pkg/system: remove deprecated `ErrNotSupportedOperatingSystem`, `IsOSSupported` [moby/moby#47129](https://github.com/moby/moby/pull/47129)

* pkg/homedir: remove deprecated Key() and GetShortcutString() [moby/moby#47130](https://github.com/moby/moby/pull/47130)

* pkg/containerfs: remove deprecated ResolveScopedPath [moby/moby#47131](https://github.com/moby/moby/pull/47131)

* The daemon flag `--oom-score-adjust` was deprecated in v24.0 and is now removed. [moby/moby#46113](https://github.com/moby/moby/pull/46113)

* Remove deprecated aliases from the api/types package. These types were deprecated in v25.0.0, which provided temporary aliases. [moby/moby#47148](https://github.com/moby/moby/pull/47148) These aliases are now removed: `types.Info`, `types.Commit`, `types.PluginsInfo`, `types.NetworkAddressPool`, `types.Runtime`, `types.SecurityOpt`, `types.KeyValue`, `types.DecodeSecurityOptions`, `types.CheckpointCreateOptions`, `types.CheckpointListOptions`, `types.CheckpointDeleteOptions`, `types.Checkpoint`, `types.ImageDeleteResponseItem`, `types.ImageSummary`, `types.ImageMetadata`, `types.ServiceUpdateResponse`, `types.ServiceCreateResponse`, `types.ResizeOptions`, `types.ContainerAttachOptions`, `types.ContainerCommitOptions`, `types.ContainerRemoveOptions`, `types.ContainerStartOptions`, `types.ContainerListOptions`, `types.ContainerLogsOptions`

* cli/command/container: remove deprecated `NewStartOptions()` [docker/cli#4811](https://github.com/docker/cli/pull/4811)

* cli/command: remove deprecated `DockerCliOption`, `InitializeOpt` [docker/cli#4810](https://github.com/docker/cli/pull/4810)

----
url: https://docs.docker.com/reference/cli/docker/inspect/
----

# docker inspect

***

| Description | Return low-level information on Docker objects    |
| ----------- | ------------------------------------------------- |
| Usage       | `docker inspect [OPTIONS] NAME\|ID [NAME\|ID...]` |

## [Description](#description)

Docker inspect provides detailed information on constructs controlled by Docker.

By default, `docker inspect` will render results in a JSON array.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                             |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --format`](#format) |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| [`-s, --size`](#size)     |         | Display total file sizes if the type is container                                                                                                                                                                                       |
| [`--type`](#type)         |         | Only inspect objects of the given type                                                                                                                                                                                                  |

## [Examples](#examples)

### [Format the output (--format)](#format)

If a format is specified, the given template will be executed for each result.

Go's [text/template](https://pkg.go.dev/text/template) package describes all the details of the format.

### [Specify target type (--type)](#type)

`--type config|container|image|node|network|secret|service|volume|task|plugin`

The `docker inspect` command matches any type of object by either ID or name. In some cases multiple type of objects (for example, a container and a volume) exist with the same name, making the result ambiguous.

To restrict `docker inspect` to a specific type of object, use the `--type` option.

The following example inspects a volume named `myvolume`.

```console
$ docker inspect --type=volume myvolume
```

### [Inspect the size of a container (-s, --size)](#size)

The `--size`, or short-form `-s`, option adds two additional fields to the `docker inspect` output. This option only works for containers. The container doesn't have to be running, it also works for stopped containers.

```console
$ docker inspect --size mycontainer
```

The output includes the full output of a regular `docker inspect` command, with the following additional fields:

* `SizeRootFs`: the total size of all the files in the container, in bytes.
* `SizeRw`: the size of the files that have been created or changed in the container, compared to it's image, in bytes.

```console
$ docker run --name database -d redis
3b2cbf074c99db4a0cad35966a9e24d7bc277f5565c17233386589029b7db273
$ docker inspect --size database -f '{{ .SizeRootFs }}'
123125760
$ docker inspect --size database -f '{{ .SizeRw }}'
8192
$ docker exec database fallocate -l 1000 /newfile
$ docker inspect --size database -f '{{ .SizeRw }}'
12288
```

### [Get an instance's IP address](#get-an-instances-ip-address)

For the most part, you can pick out any field from the JSON in a fairly straightforward manner.

```console
$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $INSTANCE_ID
```

### [Get an instance's MAC address](#get-an-instances-mac-address)

```console
$ docker inspect --format='{{range .NetworkSettings.Networks}}{{.MacAddress}}{{end}}' $INSTANCE_ID
```

### [Get an instance's log path](#get-an-instances-log-path)

```console
$ docker inspect --format='{{.LogPath}}' $INSTANCE_ID
```

### [Get an instance's image name](#get-an-instances-image-name)

```console
$ docker inspect --format='{{.Config.Image}}' $INSTANCE_ID
```

### [List all port bindings](#list-all-port-bindings)

You can loop over arrays and maps in the results to produce simple text output:

```console
$ docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{with $conf}}{{(index . 0).HostPort}}{{else}}none{{end}} {{end}}' $INSTANCE_ID
```

### [Find a specific port mapping](#find-a-specific-port-mapping)

The `.Field` syntax doesn't work when the field name begins with a number, but the template language's `index` function does. The `.NetworkSettings.Ports` section contains a map of the internal port mappings to a list of external address/port objects. To grab just the numeric public port, you use `index` to find the specific port map, and then `index` 0 contains the first object inside of that. Then, specify the `HostPort` field to get the public address.

```console
$ docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID
```

### [Get a subsection in JSON format](#get-a-subsection-in-json-format)

If you request a field which is itself a structure containing other fields, by default you get a Go-style dump of the inner values. Docker adds a template function, `json`, which can be applied to get results in JSON format.

```console
$ docker inspect --format='{{json .Config}}' $INSTANCE_ID
```

----
url: https://docs.docker.com/reference/cli/docker/model/context/use/
----

# docker model context use

***

| Description | Set the active Model Runner context |
| ----------- | ----------------------------------- |
| Usage       | `docker model context use NAME`     |

## [Description](#description)

Set the active Model Runner context. Pass "default" to revert to automatic backend detection.

----
url: https://docs.docker.com/compose/how-tos/gpu-support/
----

# Run Docker Compose services with GPU access

***

Table of contents

***

Compose services can define GPU device reservations if the Docker host contains such devices and the Docker Daemon is set accordingly. For this, make sure you install the [prerequisites](https://docs.docker.com/engine/containers/resource_constraints/#gpu) if you haven't already done so.

The examples in the following sections focus specifically on providing service containers access to GPU devices with Docker Compose.

## [Enabling GPU access to service containers](#enabling-gpu-access-to-service-containers)

GPUs are referenced in a `compose.yaml` file using the [device](https://docs.docker.com/reference/compose-file/deploy/#devices) attribute from the Compose Deploy specification, within your services that need them.

This provides more granular control over a GPU reservation as custom values can be set for the following device properties:

* `capabilities`. This value is specified as a list of strings. For example, `capabilities: [gpu]`. You must set this field in the Compose file. Otherwise, it returns an error on service deployment.
* `count`. Specified as an integer or the value `all`, represents the number of GPU devices that should be reserved (providing the host holds that number of GPUs). If `count` is set to `all` or not specified, all GPUs available on the host are used by default.
* `device_ids`. This value, specified as a list of strings, represents GPU device IDs from the host. You can find the device ID in the output of `nvidia-smi` on the host. If no `device_ids` are set, all GPUs available on the host are used by default.
* `driver`. Specified as a string, for example `driver: 'nvidia'`
* `options`. Key-value pairs representing driver specific options.

> Important
>
> You must set the `capabilities` field. Otherwise, it returns an error on service deployment.

> Note
>
> `count` and `device_ids` are mutually exclusive. You must only define one field at a time.

For more information on these properties, see the [Compose Deploy Specification](https://docs.docker.com/reference/compose-file/deploy/#devices).

### [Example of a Compose file for running a service with access to 1 GPU device](#example-of-a-compose-file-for-running-a-service-with-access-to-1-gpu-device)

```yaml
services:
  test:
    image: nvidia/cuda:12.9.0-base-ubuntu22.04
    command: nvidia-smi
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
```

Run with Docker Compose:

```console
$ docker compose up
Creating network "gpu_default" with the default driver
Creating gpu_test_1 ... done
Attaching to gpu_test_1    
test_1  | +-----------------------------------------------------------------------------+
test_1  | | NVIDIA-SMI 450.80.02    Driver Version: 450.80.02    CUDA Version: 11.1     |
test_1  | |-------------------------------+----------------------+----------------------+
test_1  | | GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
test_1  | | Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
test_1  | |                               |                      |               MIG M. |
test_1  | |===============================+======================+======================|
test_1  | |   0  Tesla T4            On   | 00000000:00:1E.0 Off |                    0 |
test_1  | | N/A   23C    P8     9W /  70W |      0MiB / 15109MiB |      0%      Default |
test_1  | |                               |                      |                  N/A |
test_1  | +-------------------------------+----------------------+----------------------+
test_1  |                                                                                
test_1  | +-----------------------------------------------------------------------------+
test_1  | | Processes:                                                                  |
test_1  | |  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
test_1  | |        ID   ID                                                   Usage      |
test_1  | |=============================================================================|
test_1  | |  No running processes found                                                 |
test_1  | +-----------------------------------------------------------------------------+
gpu_test_1 exited with code 0
```

On machines hosting multiple GPUs, the `device_ids` field can be set to target specific GPU devices and `count` can be used to limit the number of GPU devices assigned to a service container.

You can use `count` or `device_ids` in each of your service definitions. An error is returned if you try to combine both, specify an invalid device ID, or use a value of count that’s higher than the number of GPUs in your system.

```console
$ nvidia-smi   
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 450.80.02    Driver Version: 450.80.02    CUDA Version: 11.0     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  Tesla T4            On   | 00000000:00:1B.0 Off |                    0 |
| N/A   72C    P8    12W /  70W |      0MiB / 15109MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+
|   1  Tesla T4            On   | 00000000:00:1C.0 Off |                    0 |
| N/A   67C    P8    11W /  70W |      0MiB / 15109MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+
|   2  Tesla T4            On   | 00000000:00:1D.0 Off |                    0 |
| N/A   74C    P8    12W /  70W |      0MiB / 15109MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+
|   3  Tesla T4            On   | 00000000:00:1E.0 Off |                    0 |
| N/A   62C    P8    11W /  70W |      0MiB / 15109MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+
```

## [Access specific devices](#access-specific-devices)

To allow access only to GPU-0 and GPU-3 devices:

```yaml
services:
  test:
    image: tensorflow/tensorflow:latest-gpu
    command: python -c "import tensorflow as tf;tf.test.gpu_device_name()"
    deploy:
      resources:
        reservations:
          devices:
          - driver: nvidia
            device_ids: ['0', '3']
            capabilities: [gpu]
```

----
url: https://docs.docker.com/reference/cli/docker/network/disconnect/
----

# docker network disconnect

***

| Description | Disconnect a container from a network                   |
| ----------- | ------------------------------------------------------- |
| Usage       | `docker network disconnect [OPTIONS] NETWORK CONTAINER` |

## [Description](#description)

Disconnects a container from a network. The container must be running to disconnect it from the network.

## [Options](#options)

| Option        | Default | Description                                      |
| ------------- | ------- | ------------------------------------------------ |
| `-f, --force` |         | Force the container to disconnect from a network |

## [Examples](#examples)

```console
$ docker network disconnect multi-host-network container1
```

----
url: https://docs.docker.com/guides/lab-mcp-gateway/
----

[Lab: Docker MCP Gateway](https://docs.docker.com/guides/lab-mcp-gateway/)

Hands-on lab: Configure, secure, and connect MCP servers to your agentic applications using the Docker MCP Gateway.

AI Labs

20 minutes

Resources:

* [Docker MCP Gateway docs](/ai/mcp-gateway/)
* [MCP Gateway GitHub](https://github.com/docker/mcp-gateway)
* [Labspace repository](https://github.com/dockersamples/labspace-mcp-gateway)

[« Back to all guides](/guides/)

# Lab: Docker MCP Gateway

***

Table of contents

***

This lab provides a comprehensive, hands-on overview of the Docker MCP Gateway, which lets you run containerized MCP servers safely and securely. Learn how to configure, secure, and connect MCP servers to your agentic applications.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-mcp-gateway up -d
   ```

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

* Learn about the Docker MCP Gateway and its architecture
* Run the MCP Gateway with a simple MCP server
* Inject secrets securely into MCP servers
* Filter tools to reduce noise and save tokens
* Connect the MCP Gateway to your application using popular agentic frameworks
* Configure and use custom MCP servers

## [Modules](#modules)

| # | Module                             | Description                                                 |
| - | ---------------------------------- | ----------------------------------------------------------- |
| 1 | Introduction                       | Overview of the MCP Gateway and why it matters              |
| 2 | Adding a Simple MCP Server         | Get started with a basic MCP server configuration           |
| 3 | Adding a Complex MCP Server        | Configure MCP servers with secrets and advanced options     |
| 4 | Filtering Available Tools          | Reduce noise and save tokens by filtering tool availability |
| 5 | Connecting MCP Gateway to Your App | Integrate the MCP Gateway with agentic frameworks           |
| 6 | Using a Custom MCP Server          | Build and run your own custom MCP server                    |
| 7 | Conclusion                         | Summary and next steps                                      |

----
url: https://docs.docker.com/guides/cpp/multistage/
----

# Create a multi-stage build for your C++ application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Overview](#overview)

This section walks you through creating a multi-stage Docker build for a C++ application. A multi-stage build is a Docker feature that allows you to use different base images for different stages of the build process, so you can optimize the size of your final image and separate build dependencies from runtime dependencies.

The standard practice for compiled languages like C++ is to have a build stage that compiles the code and a runtime stage that runs the compiled binary, because the build dependencies are not needed at runtime.

## [Get the sample application](#get-the-sample-application)

Let's use a simple C++ application that prints `Hello, World!` to the terminal. To do so, clone the sample repository to use with this guide:

```bash
$ git clone https://github.com/dockersamples/c-plus-plus-docker.git
```

The example for this section is under the `hello` directory in the repository. Get inside it and take a look at the files:

```bash
$ cd c-plus-plus-docker/hello
$ ls
```

You should see the following files:

```text
Dockerfile  hello.cpp
```

## [Check the Dockerfile](#check-the-dockerfile)

Open the `Dockerfile` in an IDE or text editor. The `Dockerfile` contains the instructions for building the Docker image.

```Dockerfile
# Stage 1: Build stage
FROM ubuntu:latest AS build

# Install build-essential for compiling C++ code
RUN apt-get update && apt-get install -y build-essential

# Set the working directory
WORKDIR /app

# Copy the source code into the container
COPY hello.cpp .

# Compile the C++ code statically to ensure it doesn't depend on runtime libraries
RUN g++ -o hello hello.cpp -static

# Stage 2: Runtime stage
FROM scratch

# Copy the static binary from the build stage
COPY --from=build /app/hello /hello

# Command to run the binary
CMD ["/hello"]
```

The `Dockerfile` has two stages:

1. **Build stage**: This stage uses the `ubuntu:latest` image to compile the C++ code and create a static binary.
2. **Runtime stage**: This stage uses the `scratch` image, which is an empty image, to copy the static binary from the build stage and run it.

## [Build the Docker image](#build-the-docker-image)

To build the Docker image, run the following command in the `hello` directory:

```bash
$ docker build -t hello .
```

The `-t` flag tags the image with the name `hello`.

## [Run the Docker container](#run-the-docker-container)

To run the Docker container, use the following command:

```bash
$ docker run hello
```

You should see the output `Hello, World!` in the terminal.

## [Summary](#summary)

In this section, you learned how to create a multi-stage build for a C++ application. Multi-stage builds help you optimize the size of your final image and separate build dependencies from runtime dependencies. In this example, the final image only contains the static binary and doesn't include any build dependencies.

As the image has an empty base, the usual OS tools are also absent. So, for example, you can't run a simple `ls` command in the container:

```bash
$ docker run hello ls
```

This makes the image very lightweight and secure.

[Containerize a C++ application »](https://docs.docker.com/guides/cpp/containerize/)

----
url: https://docs.docker.com/engine/logging/drivers/fluentd/
----

# Fluentd logging driver

***

Table of contents

***

The `fluentd` logging driver sends container logs to the [Fluentd](https://www.fluentd.org) collector as structured log data. Then, users can use any of the [various output plugins of Fluentd](https://www.fluentd.org/plugins) to write these logs to various destinations.

In addition to the log message itself, the `fluentd` log driver sends the following metadata in the structured log message:

| Field            | Description                                                                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `container_id`   | The full 64-character container ID.                                                                                                                   |
| `container_name` | The container name at the time it was started. If you use `docker rename` to rename a container, the new name isn't reflected in the journal entries. |
| `source`         | `stdout` or `stderr`                                                                                                                                  |
| `log`            | The container log                                                                                                                                     |

## [Usage](#usage)

Some options are supported by specifying `--log-opt` as many times as needed:

* `fluentd-address`: specify a socket address to connect to the Fluentd daemon, ex `fluentdhost:24224` or `unix:///path/to/fluentd.sock`.
* `tag`: specify a tag for Fluentd messages. Supports some Go template markup, ex `{{.ID}}`, `{{.FullID}}` or `{{.Name}}` `docker.{{.ID}}`.

To use the `fluentd` driver as the default logging driver, set the `log-driver` and `log-opt` keys to appropriate values in the `daemon.json` file. For more about configuring Docker using `daemon.json`, see [daemon.json](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file).

> Note
>
> If you're using Docker Desktop, edit the daemon configuration through the Docker Desktop Dashboard. Open **Settings** and select **Docker Engine**. For details, see [Docker Engine settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine).

The following example sets the log driver to `fluentd` and sets the `fluentd-address` option.

```json
{
  "log-driver": "fluentd",
  "log-opts": {
    "fluentd-address": "fluentdhost:24224"
  }
}
```

Restart Docker for the changes to take effect.

> Note
>
> `log-opts` configuration options in the `daemon.json` configuration file must be provided as strings. Boolean and numeric values (such as the value for `fluentd-async` or `fluentd-max-retries`) must therefore be enclosed in quotes (`"`).

To set the logging driver for a specific container, pass the `--log-driver` option to `docker run`:

```console
$ docker run --log-driver=fluentd ...
```

Before using this logging driver, launch a Fluentd daemon. The logging driver connects to this daemon through `localhost:24224` by default. Use the `fluentd-address` option to connect to a different address.

```console
$ docker run --log-driver=fluentd --log-opt fluentd-address=fluentdhost:24224
```

If container cannot connect to the Fluentd daemon, the container stops immediately unless the `fluentd-async` option is used.

## [Options](#options)

Users can use the `--log-opt NAME=VALUE` flag to specify additional Fluentd logging driver options.

### [fluentd-address](#fluentd-address)

By default, the logging driver connects to `localhost:24224`. Supply the `fluentd-address` option to connect to a different address. `tcp`(default) and `unix` sockets are supported.

```console
$ docker run --log-driver=fluentd --log-opt fluentd-address=fluentdhost:24224
$ docker run --log-driver=fluentd --log-opt fluentd-address=tcp://fluentdhost:24224
$ docker run --log-driver=fluentd --log-opt fluentd-address=unix:///path/to/fluentd.sock
```

Two of the above specify the same address, because `tcp` is default.

### [tag](#tag)

By default, Docker uses the first 12 characters of the container ID to tag log messages. Refer to the [log tag option documentation](https://docs.docker.com/engine/logging/log_tags/) for customizing the log tag format.

### [labels, labels-regex, env, and env-regex](#labels-labels-regex-env-and-env-regex)

The `labels` and `env` options each take a comma-separated list of keys. If there is collision between `label` and `env` keys, the value of the `env` takes precedence. Both options add additional fields to the extra attributes of a logging message.

The `env-regex` and `labels-regex` options are similar to and compatible with respectively `env` and `labels`. Their values are regular expressions to match logging-related environment variables and labels. It is used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).

### [fluentd-async](#fluentd-async)

Docker connects to Fluentd in the background. Messages are buffered until the connection is established. Defaults to `false`.

### [fluentd-async-reconnect-interval](#fluentd-async-reconnect-interval)

When `fluentd-async` is enabled, the `fluentd-async-reconnect-interval` option defines the interval, in milliseconds, at which the connection to `fluentd-address` is re-established. This option is useful if the address resolves to one or more IP addresses, for example a Consul service address.

### [fluentd-buffer-limit](#fluentd-buffer-limit)

Sets the number of events buffered on the memory. Records will be stored in memory up to this number. If the buffer is full, the call to record logs will fail. The default is 1048576. (<https://github.com/fluent/fluent-logger-golang/tree/master#bufferlimit>)

### [fluentd-retry-wait](#fluentd-retry-wait)

How long to wait between retries. Defaults to 1 second.

### [fluentd-max-retries](#fluentd-max-retries)

The maximum number of retries. Defaults to `4294967295` (2\*\*32 - 1).

### [fluentd-sub-second-precision](#fluentd-sub-second-precision)

Generates event logs in nanosecond resolution. Defaults to `false`.

### [fluentd-write-timeout](#fluentd-write-timeout)

Sets the timeout for the write call to the `fluentd` daemon. By default, writes have no timeout and will block indefinitely.

## [Fluentd daemon management with Docker](#fluentd-daemon-management-with-docker)

About `Fluentd` itself, see [the project webpage](https://www.fluentd.org) and [its documents](https://docs.fluentd.org).

To use this logging driver, start the `fluentd` daemon on a host. We recommend that you use [the Fluentd docker image](https://hub.docker.com/r/fluent/fluentd/). This image is especially useful if you want to aggregate multiple container logs on each host then, later, transfer the logs to another Fluentd node to create an aggregate store.

### [Test container loggers](#test-container-loggers)

1. Write a configuration file (`test.conf`) to dump input logs:

   ```text
   <source>
     @type forward
   </source>

   <match *>
     @type stdout
   </match>
   ```

2. Launch Fluentd container with this configuration file:

   ```console
   $ docker run -it -p 24224:24224 -v /path/to/conf/test.conf:/fluentd/etc/test.conf -e FLUENTD_CONF=test.conf fluent/fluentd:latest
   ```

3. Start one or more containers with the `fluentd` logging driver:

   ```console
   $ docker run --log-driver=fluentd your/application
   ```

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/
----

# Enhanced Container Isolation

***

Table of contents

***

Subscription: Business

For: Administrators

Enhanced Container Isolation (ECI) prevents malicious containers from compromising Docker Desktop or the host system. It applies advanced security techniques automatically while maintaining full developer productivity and workflow compatibility.

* ECI strengthens container isolation and locks in security configurations created by administrators, such as [Registry Access Management policies](https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/) and [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) controls.
* ECI works alongside other Docker security features like reduced Linux capabilities, seccomp, and AppArmor.

If you are using WSL2 backend, ensure you’re running WSL version 2.6 or later. This is required because ECI depends on a Linux kernel version of at least 6.3.0, and WSL 2.6+ includes kernel version 6.6.

## [Who should use Enhanced Container Isolation?](#who-should-use-enhanced-container-isolation)

ECI is designed for:

* Organizations that want to prevent container-based attacks and reduce security vulnerabilities in developer environments
* Security teams that need stronger container isolation without impacting developer workflows
* Enterprises that require additional protection when running untrusted or third-party container images

## [How Enhanced Container Isolation works](#how-enhanced-container-isolation-works)

Docker implements ECI using the [Sysbox container runtime](https://github.com/nestybox/sysbox), a security-enhanced fork of the standard OCI runc runtime. When ECI is turned on, containers created through `docker run` or `docker create` automatically use Sysbox instead of runc without requiring any changes to developer workflows. Docker's default runtime remains runc, but all user containers implicitly launch with Sysbox.

When ECI is turned on, the Docker CLI `--runtime` flag is ignored. Even containers using the `--privileged` flag run securely with ECI, preventing them from breaching the Docker Desktop virtual machine or other containers.

## [Key security features](#key-security-features)

### [Linux user namespace isolation](#linux-user-namespace-isolation)

With Enhanced Container Isolation, all containers leverage Linux user namespaces for stronger isolation. Container root users map to unprivileged users in the Docker Desktop VM:

```console
$ docker run -it --rm --name=first alpine
/ # cat /proc/self/uid_map
         0     100000      65536
```

This output shows that container root (0) maps to unprivileged user 100000 in the VM, with a range of 64K user IDs. Each container gets exclusive mappings:

```console
$ docker run -it --rm --name=second alpine
/ # cat /proc/self/uid_map
         0     165536      65536
```

Without Enhanced Container Isolation, containers run as true root:

```console
$ docker run -it --rm alpine
/ # cat /proc/self/uid_map
         0       0     4294967295
```

By using Linux user namespaces, ECI ensures container processes never run with valid user IDs in the Linux VM, constraining their capabilities to resources within the container only.

### [Secured privileged containers](#secured-privileged-containers)

Privileged containers (`docker run --privileged`) normally pose significant security risks because they provide unrestricted access to the Linux kernel. Without ECI, privileged containers can:

* Run as true root with all capabilities
* Bypass seccomp and AppArmor restrictions
* Access all hardware devices
* Modify global kernel settings

Organizations securing developer environments face challenges with privileged containers because they can gain control of the Docker Desktop VM and alter security settings like registry access management and network proxies.

Enhanced Container Isolation transforms privileged containers by ensuring they can only access resources within their container boundary. For example, privileged containers can't access Docker Desktop's network configuration:

```console
$ docker run --privileged djs55/bpftool map show
Error: can't get next map: Operation not permitted
```

Without ECI, privileged containers can easily access and modify these settings:

```console
$ docker run --privileged djs55/bpftool map show
17: ringbuf  name blocked_packets  flags 0x0
        key 0B  value 0B  max_entries 16777216  memlock 0B
18: hash  name allowed_map  flags 0x0
        key 4B  value 4B  max_entries 10000  memlock 81920B
```

Advanced container workloads like Docker-in-Docker and Kubernetes-in-Docker still work with ECI but run much more securely.

> Note
>
> ECI doesn't prevent users from running privileged containers, but makes them secure by containing their access. Privileged workloads that modify global kernel settings (loading kernel modules, changing Berkeley Packet Filter settings) receive "permission denied" errors.

### [Namespace isolation enforcement](#namespace-isolation-enforcement)

Enhanced Container Isolation prevents containers from sharing Linux namespaces with the Docker Desktop VM, maintaining isolation boundaries:

**PID namespace sharing blocked:**

```console
$ docker run -it --rm --pid=host alpine
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share namespaces [pid] with the host (because they use the linux user-namespace for isolation): unknown.
```

**Network namespace sharing blocked:**

```console
$ docker run -it --rm --network=host alpine
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: invalid or unsupported container spec: sysbox containers can't share a network namespace with the host (because they use the linux user-namespace for isolation): unknown.
```

**User namespace override ignored:**

```console
$ docker run -it --rm --userns=host alpine
/ # cat /proc/self/uid_map
         0     100000      65536
```

Docker build operations using `--network-host` and Docker buildx entitlements (`network.host`, `security.insecure`) are also blocked.

### [Protected bind mounts](#protected-bind-mounts)

Enhanced Container Isolation maintains support for standard file sharing while preventing access to sensitive VM directories:

Host directory mounts continue to work:

```console
$ docker run -it --rm -v $HOME:/mnt alpine
/ # ls /mnt
# Successfully lists home directory contents
```

VM configuration mounts are blocked:

```console
$ docker run -it --rm -v /etc/docker/daemon.json:/mnt/daemon.json alpine
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: error in the container spec: can't mount /etc/docker/daemon.json because it's configured as a restricted host mount: unknown
```

This prevents containers from reading or modifying Docker Engine configurations, registry access management settings, proxy configurations, and other security-related VM files.

> Note
>
> By default, ECI blocks bind mounting the Docker Engine socket (/var/run/docker.sock) as this would grant containers control over Docker Engine. Administrators can create exceptions for trusted container images.

### [Advanced system call protection](#advanced-system-call-protection)

Enhanced Container Isolation intercepts sensitive system calls to prevent containers from using legitimate capabilities maliciously:

```console
$ docker run -it --rm --cap-add SYS_ADMIN -v $HOME:/mnt:ro alpine
/ # mount -o remount,rw /mnt /mnt
mount: permission denied (are you root?)
```

Even with `CAP_SYS_ADMIN` capability, containers can't change read-only bind mounts to read-write, ensuring they can't breach container boundaries.

Containers can still create internal mounts within their filesystem:

```console
/ # mkdir /root/tmpfs
/ # mount -t tmpfs tmpfs /root/tmpfs
/ # mount -o remount,ro /root/tmpfs /root/tmpfs
/ # findmnt | grep tmpfs
├─/root/tmpfs    tmpfs      tmpfs    ro,relatime,uid=100000,gid=100000
```

ECI performs system call filtering efficiently by intercepting only control-path system calls (rarely used) while leaving data-path system calls unaffected, maintaining container performance.

### [Automatic filesystem user ID mapping](#automatic-filesystem-user-id-mapping)

Enhanced Container Isolation solves file sharing challenges between containers with different user ID ranges through automatic filesystem mapping.

Each container gets exclusive user ID mappings, but Sysbox uses filesystem user ID remapping via Linux kernel ID-mapped mounts (added in 2021) or alternative shiftsfs module. This maps filesystem accesses from containers' real user IDs to standard ranges, enabling:

* Volume sharing across containers with different user ID ranges
* Consistent file ownership regardless of container user ID mappings
* Transparent file access without user intervention

### [Information hiding through filesystem emulation](#information-hiding-through-filesystem-emulation)

ECI emulates portions of `/proc` and `/sys` filesystems within containers to hide sensitive host information and provide per-container views of kernel resources:

```console
$ docker run -it --rm alpine
/ # cat /proc/uptime
5.86 5.86
```

This shows container uptime instead of Docker Desktop VM uptime, preventing system information from leaking into containers.

Several `/proc/sys` resources that aren't namespaced by the Linux kernel are emulated per-container, with Sysbox coordinating values when programming kernel settings. This enables container workloads that normally require privileged access to run securely.

## [Performance and compatibility](#performance-and-compatibility)

Enhanced Container Isolation maintains optimized performance and full compatibility:

* No performance impact: System call filtering targets only control-path calls, leaving data-path operations unaffected
* Full workflow compatibility: Existing development processes, tools, and container images work unchanged
* Advanced workload support: Docker-in-Docker, Kubernetes-in-Docker, and other complex scenarios work securely
* Automatic management: User ID mappings, filesystem access, and security policies are handled automatically
* Standard image support: No special container images or modifications required

> Important
>
> ECI protection varies by Docker Desktop version and doesn't yet protect extension containers. Docker builds and Kubernetes in Docker Desktop have varying protection levels depending on the version. For details, see [Enhanced Container Isolation limitations](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations/).

----
url: https://docs.docker.com/guides/docker-compose/
----

# Defining and running multi-container applications with Docker Compose

Table of contents

***

Simplify the process of defining, configuring, and running multi-container Docker applications.

**Time to complete** 10 minutes

Developers face challenges with multi-container Docker applications, including complex configuration, dependency management, and maintaining consistent environments. Networking, resource allocation, data persistence, logging, and monitoring add to the difficulty. Security concerns and troubleshooting issues further complicate the process, requiring effective tools and practices for efficient management.

Docker Compose solves the problem of managing multi-container Docker applications by providing a simple way to define, configure, and run all the containers needed for an application using a single YAML file. This approach helps developers to easily set up, share, and maintain consistent development, testing, and production environments, ensuring that complex applications can be deployed with all their dependencies and services properly configured and orchestrated.

## [What you’ll learn](#what-youll-learn)

* What Docker Compose is and what it does
* How to define services
* Use cases for Docker Compose
* How things would be different without Docker Compose

## [Who’s this for?](#whos-this-for)

* Developers and DevOps engineers who need to define, manage, and orchestrate multi-container Docker applications efficiently across multiple environments.
* Development teams that want to increase productivity by streamlining development workflows and reducing setup time.

## [Tools integration](#tools-integration)

Works well with Docker CLI, CI/CD tools, and container orchestration tools.

## [Modules](#modules)

1. [Why Docker Compose?](https://docs.docker.com/guides/docker-compose/why/)

   Learn how Docker Compose can help you simplify app development.

2. [Demo: set up and use Docker Compose](https://docs.docker.com/guides/docker-compose/setup/)

   Learn how to get started with Docker Compose.

3. [Common challenges and questions](https://docs.docker.com/guides/docker-compose/common-questions/)

   Explore common challenges and questions related to Docker Compose.

----
url: https://docs.docker.com/guides/databases/
----

[Use containerized databases](https://docs.docker.com/guides/databases/)

Learn how to effectively run and manage databases as containers.

Databases

20 minutes

[« Back to all guides](/guides/)

# Use containerized databases

***

Table of contents

***

Using a local containerized database offers flexibility and ease of setup, letting you mirror production environments closely without the overhead of traditional database installations. Docker simplifies this process, enabling you to deploy, manage, and scale databases in isolated containers with just a few commands.

In this guide, you'll learn how to:

* Run a local containerized database
* Access the shell of a containerized database
* Connect to a containerized database from your host
* Connect to a containerized database from another container
* Persist database data in a volume
* Build a customized database image
* Use Docker Compose to run a database

This guide uses the MySQL image for examples, but the concepts can be applied to other database images.

## [Prerequisites](#prerequisites)

To follow along with this guide, you must have Docker installed. To install Docker, see [Get Docker](https://docs.docker.com/get-started/get-docker/).

## [Run a local containerized database](#run-a-local-containerized-database)

Most popular database systems, including MySQL, PostgreSQL, and MongoDB, have a Docker Official Image available on Docker Hub. These images are a curated set images that follow best practices, ensuring that you have access to the latest features and security updates. To get started, visit [Docker Hub](https://hub.docker.com) and search for the database you're interested in. Each image's page provides detailed instructions on how to run the container, customize your setup, and configure the database according to your needs. For more information about the MySQL image used in this guide, see the Docker Hub [MySQL image](https://hub.docker.com/_/mysql) page.

To run a database container, you can use either the Docker Desktop GUI or CLI.

To run a container using the CLI, run the following command in a terminal:

```console
$ docker run --name my-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -e MYSQL_DATABASE=mydb -d mysql:latest
```

In this command:

* `--name my-mysql` assigns the name my-mysql to your container for easier reference.
* `-e MYSQL_ROOT_PASSWORD=my-secret-pw` sets the root password for MySQL to my-secret-pw. Replace my-secret-pw with a secure password of your choice.
* `-e MYSQL_DATABASE=mydb` optionally creates a database named mydb. You can change mydb to your desired database name.
* `-d` runs the container in detached mode, meaning it runs in the background.
* `mysql:latest` specifies that you want to use the latest version of the MySQL image.

To verify that your container is running, run `docker ps` in a terminal

To run a container using the GUI:

1. In the Docker Desktop Dashboard, select the global search at the top of the window.

2. Specify `mysql` in the search box, and select the `Images` tab if not already selected.

3. Hover over the `mysql` image and select `Run`. The **Run a new container** modal appears.

4. Expand **Optional settings**.

5. In the optional settings, specify the following:

   * **Container name**: `my-mysql`

   * **Environment variables**:

     * `MYSQL_ROOT_PASSWORD`:`my-secret-pw`
     * `MYSQL_DATABASE`:`mydb`

6. Select `Run`.

7. Open the **Container** view in the Docker Desktop Dashboard to verify that your container is running.

## [Access the shell of a containerized database](#access-the-shell-of-a-containerized-database)

When you have a database running inside a Docker container, you may need to access its shell to manage the database, execute commands, or perform administrative tasks. Docker provides a straightforward way to do this using the `docker exec` command. Additionally, if you prefer a graphical interface, you can use Docker Desktop's GUI.

If you don't yet have a database container running, see [Run a local containerized database](#run-a-local-containerized-database).

To access the terminal of a MySQL container using the CLI, you can use the following `docker exec` command.

```console
$ docker exec -it my-mysql bash
```

In this command:

* `docker exec` tells Docker you want to execute a command in a running container.
* `-it` ensures that the terminal you're accessing is interactive, so you can type commands into it.
* `my-mysql` is the name of your MySQL container. If you named your container differently when you ran it, use that name instead.
* `bash` is the command you want to run inside the container. It opens up a bash shell that lets you interact with the container's file system and installed applications.

After executing this command, you will be given access to the bash shell inside your MySQL container, from which you can manage your MySQL server directly. You can run `exit` to return to your terminal.

1. Open the Docker Desktop Dashboard and select the **Containers** view.
2. In the **Actions** column for your container, select **Show container actions** and then select **Open in terminal**.

In this terminal you can access to the shell inside your MySQL container, from which you can manage your MySQL server directly.

Once you've accessed the container's terminal, you can run any tools available in that container. The following example shows using `mysql` in the container to list the databases.

```console
# mysql -u root -p
Enter password: my-secret-pw

mysql> SHOW DATABASES;

+--------------------+
| Database           |
+--------------------+
| information_schema |
| mydb               |
| mysql              |
| performance_schema |
| sys                |
+--------------------+
5 rows in set (0.00 sec)
```

## [Connect to a containerized database from your host](#connect-to-a-containerized-database-from-your-host)

Connecting to a containerized database from your host machine involves mapping a port inside the container to a port on your host machine. This process ensures that the database inside the container is accessible via the host machine's network. For MySQL, the default port is 3306. By exposing this port, you can use various database management tools or applications on your host machine to interact with your MySQL database.

Before you begin, you must remove any containers you previously ran for this guide. To stop and remove a container, either:

* In a terminal, run `docker rm --force my-mysql` to remove the container named `my-mysql`.
* Or, in the Docker Desktop Dashboard, select the **Delete** icon next to your container in the **Containers** view.

Next, you can use either the Docker Desktop GUI or CLI to run the container with the port mapped.

Run the following command in a terminal.

```console
$ docker run -p 3307:3306 --name my-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -e MYSQL_DATABASE=mydb -d mysql:latest
```

In this command, `-p 3307:3306` maps port 3307 on the host to port 3306 in the container.

To verify the port is mapped, run the following command.

```console
$ docker ps
```

You should see output like the following.

```console
CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                               NAMES
6eb776cfd73c   mysql:latest   "docker-entrypoint.s…"   17 minutes ago   Up 17 minutes   33060/tcp, 0.0.0.0:3307->3306/tcp   my-mysql
```

To run a container using the GUI:

1. In the Docker Desktop Dashboard, select the global search at the top of the window.

2. Specify `mysql` in the search box, and select the `Images` tab if not already selected.

3. Hover over the `mysql` image and select `Run`. The **Run a new container** modal appears.

4. Expand **Optional settings**.

5. In the optional settings, specify the following:

   * **Container name**: `my-mysql`

   * **Host port** for the **3306/tcp** port: `3307`

   * **Environment variables**:

     * `MYSQL_ROOT_PASSWORD`:`my-secret-pw`
     * `MYSQL_DATABASE`:`mydb`

6. Select `Run`.

7. In the **Containers** view, verify that the port is mapped under the **Port(s)** column. You should see `3307:3306` for the `my-mysql` container.

At this point, any application running on your host can access the MySQL service in the container at `localhost:3307`.

## [Connect to a containerized database from another container](#connect-to-a-containerized-database-from-another-container)

Connecting to a containerized database from another container is a common scenario in microservices architecture and during development processes. Docker's networking capabilities make it easy to establish this connection without having to expose the database to the host network. This is achieved by placing both the database container and the container that needs to access it on the same Docker network.

Before you begin, you must remove any containers you previously ran for this guide. To stop and remove a container, either:

* In a terminal, run `docker rm --force my-mysql` to remove the container named `my-mysql`.
* Or, in the Docker Desktop Dashboard, select the **Delete** icon next to your container in the **Containers** view.

To create a network and run containers on it:

1. Run the following command to create a Docker network named my-network.

   ```console
   $ docker network create my-network
   ```

2. Run your database container and specify the network using the `--network` option. This runs the container on the my-network network.

   ```console
   $ docker run --name my-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -e MYSQL_DATABASE=mydb --network my-network -d mysql:latest
   ```

3. Run your other containers and specify the network using the `--network` option. For this example, you'll run a phpMyAdmin container that can connect to your database.

   1. Run a phpMyAdmin container. Use the `--network` option to specify the network, the `-p` option to let you access the container from your host machine, and the `-e` option to specify a required environment variable for this image.

      ```console
      $ docker run --name my-phpmyadmin -d --network my-network -p 8080:80 -e PMA_HOST=my-mysql phpmyadmin
      ```

4. Verify that the containers can communicate. For this example, you'll access phpMyAdmin and verify that it connects to the database.

   1. Open <http://localhost:8080> to access your phpMyAdmin container.
   2. Log in using `root` as the username and `my-secret-pw` as the password. You should connect to the MySQL server and see your database listed.

At this point, any application running on your `my-network` container network can access the MySQL service in the container at `my-mysql:3306`.

## [Persist database data in a volume](#persist-database-data-in-a-volume)

Persisting database data in a Docker volume is necessary for ensuring that your data survives container restarts and removals. A Docker volume lets you store database files outside the container's writable layer, making it possible to upgrade the container, switch bases, and share data without losing it. Here’s how you can attach a volume to your database container using either the Docker CLI or the Docker Desktop GUI.

Before you begin, you must remove any containers you previously ran for this guide. To stop and remove a container, either:

* In a terminal, run `docker rm --force my-mysql` to remove the container named `my-mysql`.
* Or, in the Docker Desktop Dashboard, select the **Delete** icon next to your container in the **Containers** view.

Next, you can use either the Docker Desktop GUI or CLI to run the container with a volume.

To run your database container with a volume attached, include the `-v` option with your `docker run` command, specifying a volume name and the path where the database stores its data inside the container. If the volume doesn't exist, Docker automatically creates it for you.

To run a database container with a volume attached, and then verify that the data persists:

1. Run the container and attach the volume.

   ```console
   $ docker run --name my-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -e MYSQL_DATABASE=mydb -v my-db-volume:/var/lib/mysql -d mysql:latest
   ```

   This command mounts the volume named `my-db-volume` to the `/var/lib/mysql` directory in the container.

2. Create some data in the database. Use the `docker exec` command to run `mysql` inside the container and create a table.

   ```console
   $ docker exec my-mysql mysql -u root -pmy-secret-pw -e "CREATE TABLE IF NOT EXISTS mydb.mytable (column_name VARCHAR(255)); INSERT INTO mydb.mytable (column_name) VALUES ('value');"
   ```

   This command uses the `mysql` tool in the container to create a table named `mytable` with a column named `column_name`, and finally inserts a value of `value`.

3. Stop and remove the container. Without a volume, the table you created would be lost when removing the container.

   ```console
   $ docker rm --force my-mysql
   ```

4. Start a new container with the volume attached. This time, you don't need to specify any environment variables as the configuration is saved in the volume.

   ```console
   $ docker run --name my-mysql -v my-db-volume:/var/lib/mysql -d mysql:latest
   ```

5. Verify that the table you created still exists. Use the `docker exec` command again to run `mysql` inside the container.

   ```console
   $ docker exec my-mysql mysql -u root -pmy-secret-pw -e "SELECT * FROM mydb.mytable;"
   ```

   This command uses the `mysql` tool in the container to select all the records from the `mytable` table.

   You should see output like the following.

   ```console
   column_name
   value
   ```

To run a database container with a volume attached, and then verify that the data persists:

1. Run a container with a volume attached.

   1. In the Docker Desktop Dashboard, select the global search at the top of the window.

   2. Specify `mysql` in the search box, and select the **Images** tab if not already selected.

   3. Hover over the **mysql** image and select **Run**. The **Run a new container** modal appears.

   4. Expand **Optional settings**.

   5. In the optional settings, specify the following:

      * **Container name**: `my-mysql`

      * **Environment variables**:

        * `MYSQL_ROOT_PASSWORD`:`my-secret-pw`
        * `MYSQL_DATABASE`:`mydb`

      * **Volumes**:
        * `my-db-volume`:`/var/lib/mysql`

      Here, the name of the volume is `my-db-volume` and it is mounted in the container at `/var/lib/mysql`.

   6. Select `Run`.

2. Create some data in the database.

   1. In the **Containers** view, next to your container select the **Show container actions** icon, and then select **Open in terminal**.

   2. Run the following command in the container's terminal to add a table.

      ```console
      # mysql -u root -pmy-secret-pw -e "CREATE TABLE IF NOT EXISTS mydb.mytable (column_name VARCHAR(255)); INSERT INTO mydb.mytable (column_name) VALUES ('value');"
      ```

      This command uses the `mysql` tool in the container to create a table named `mytable` with a column named `column_name`, and finally inserts a value of value\`.

3. In the **Containers** view, select the **Delete** icon next to your container, and then select **Delete forever**. Without a volume, the table you created would be lost when deleting the container.

4. Run a container with a volume attached.

   1. In the Docker Desktop Dashboard, select the global search at the top of the window.

   2. Specify `mysql` in the search box, and select the **Images** tab if not already selected.

   3. Hover over the **mysql** image and select **Run**. The **Run a new container** modal appears.

   4. Expand **Optional settings**.

   5. In the optional settings, specify the following:

      * **Container name**: `my-mysql`

      * **Environment variables**:

        * `MYSQL_ROOT_PASSWORD`:`my-secret-pw`
        * `MYSQL_DATABASE`:`mydb`

      * **Volumes**:
        * `my-db-volume`:`/var/lib/mysql`

   6. Select `Run`.

5. Verify that the table you created still exists.

   1. In the **Containers** view, next to your container select the **Show container actions** icon, and then select **Open in terminal**.

   2. Run the following command in the container's terminal to verify that table you created still exists.

      ```console
      # mysql -u root -pmy-secret-pw -e "SELECT * FROM mydb.mytable;"
      ```

      This command uses the `mysql` tool in the container to select all the records from the `mytable` table.

      You should see output like the following.

      ```console
      column_name
      value
      ```

At this point, any MySQL container that mounts the `my-db-volume` will be able to access and save persisted data.

## [Build a customized database image](#build-a-customized-database-image)

Customizing your database image lets you include additional configuration, scripts, or tools alongside the base database server. This is particularly useful for creating a Docker image that matches your specific development or production environment needs. The following example outlines how to build and run a custom MySQL image that includes a table initialization script.

Before you begin, you must remove any containers you previously ran for this guide. To stop and remove a container, either:

* In a terminal, run `docker rm --force my-mysql` to remove the container named `my-mysql`.
* Or, in the Docker Desktop Dashboard, select the **Delete** icon next to your container in the **Containers** view.

To build and run your custom image:

1. Create a Dockerfile.

   1. Create a file named `Dockerfile` in your project directory. For this example, you can create the `Dockerfile` in an empty directory of your choice. This file will define how to build your custom MySQL image.

   2. Add the following content to the `Dockerfile`.

      ```dockerfile
      # syntax=docker/dockerfile:1

      # Use the base image mysql:latest
      FROM mysql:latest

      # Set environment variables
      ENV MYSQL_DATABASE mydb

      # Copy custom scripts or configuration files from your host to the container
      COPY ./scripts/ /docker-entrypoint-initdb.d/
      ```

      In this Dockerfile, you've set the environment variable for the MySQL database name. You can also use the `COPY` instruction to add custom configuration files or scripts into the container. In this example, files from your host's `./scripts/` directory are copied into the container's `/docker-entrypoint-initdb.d/` directory. In this directory, `.sh`, `.sql`, and `.sql.gz` scripts are executed when the container is started for the first time. For more details about Dockerfiles, see the [Dockerfile reference](/reference/dockerfile/).

   3. Create a script file to initialize a table in the database. In the directory where your `Dockerfile` is located, create a subdirectory named `scripts`, and then create a file named `create_table.sql` with the following content.

   ```text
   CREATE TABLE IF NOT EXISTS mydb.myothertable (
     column_name VARCHAR(255)
   );

   INSERT INTO mydb.myothertable (column_name) VALUES ('other_value');
   ```

   You should now have the following directory structure.

   ```text
   ├── your-project-directory/
   │ ├── scripts/
   │ │ └── create_table.sql
   │ └── Dockerfile
   ```

2. Build your image.

   1. In a terminal, change directory to the directory where your `Dockerfile` is located.

   2. Run the following command to build the image.

      ```console
      $ docker build -t my-custom-mysql .
      ```

      In this command, `-t my-custom-mysql` tags (names) your new image as `my-custom-mysql`. The period (.) at the end of the command specifies the current directory as the context for the build, where Docker looks for the Dockerfile and any other files needed for the build.

3. Run your image as you did in [Run a local containerized database](#run-a-local-containerized-database). This time, specify your image's name instead of `mysql:latest`. Also, you no longer need to specify the `MYSQL_DATABASE` environment variable as it's now defined by your Dockerfile.

   ```console
   $ docker run --name my-mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -d my-custom-mysql
   ```

4. Verify that your container is running with the following command.

   ```console
   $ docker ps
   ```

   You should see output like the following.

   ```console
   CONTAINER ID   IMAGE              COMMAND                  CREATED        STATUS          PORTS                 NAMES
   f74dcfdb0e59   my-custom-mysql   "docker-entrypoint.s…"    2 hours ago    Up 51 minutes   3306/tcp, 33060/tcp   my-mysql
   ```

5. Verify that your initialization script was ran. Run the following command in a terminal to show the contents of the `myothertable` table.

   ```console
   $ docker exec my-mysql mysql -u root -pmy-secret-pw -e "SELECT * FROM mydb.myothertable;"
   ```

   You should see output like the following.

   ```console
   column_name
   other_value
   ```

Any container ran using your `my-custom-mysql` image will have the table initialized when first started.

## [Use Docker Compose to run a database](#use-docker-compose-to-run-a-database)

Docker Compose is a tool for defining and running multi-container Docker applications. With a single command, you can configure all your application's services (like databases, web apps, etc.) and manage them. In this example, you'll create a Compose file and use it to run a MySQL database container and a phpMyAdmin container.

To run your containers with Docker Compose:

1. Create a Docker Compose file.

   1. Create a file named `compose.yaml` in your project directory. This file will define the services, networks, and volumes.

   2. Add the following content to the `compose.yaml` file.

      ```yaml
      services:
        db:
          image: mysql:latest
          environment:
            MYSQL_ROOT_PASSWORD: my-secret-pw
            MYSQL_DATABASE: mydb
          ports:
            - 3307:3306
          volumes:
            - my-db-volume:/var/lib/mysql

        phpmyadmin:
          image: phpmyadmin/phpmyadmin:latest
          environment:
            PMA_HOST: db
            PMA_PORT: 3306
            MYSQL_ROOT_PASSWORD: my-secret-pw
          ports:
            - 8080:80
          depends_on:
            - db

      volumes:
        my-db-volume:
      ```

      For the database service:

      * `db` is the name of the service.
      * `image: mysql:latest` specifies that the service uses the latest MySQL image from Docker Hub.
      * `environment` lists the environment variables used by MySQL to initialize the database, such as the root password and the database name.
      * `ports` maps port 3307 on the host to port 3306 in the container, allowing you to connect to the database from your host machine.
      * `volumes` mounts `my-db-volume` to `/var/lib/mysql` inside the container to persist database data.

      In addition to the database service, there is a phpMyAdmin service. By default Compose sets up a single network for your app. Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by the service's name. Therefore, in the `PMA_HOST` environment variable, you can specify the service name, `db`, in order to connect to the database service. For more details about Compose, see the [Compose file reference](/reference/compose-file/).

2. Run Docker Compose.

   1. Open a terminal and change directory to the directory where your `compose.yaml` file is located.

   2. Run Docker Compose using the following command.

      ```console
      $ docker compose up
      ```

      You can now access phpMyAdmin at <http://localhost:8080> and connect to your database using `root` as the username and `my-secret-pw` as the password.

   3. To stop the containers, press `ctrl`+`c` in the terminal.

Now, with Docker Compose you can start your database and app, mount volumes, configure networking, and more, all with a single command.

## [Summary](#summary)

This guide introduced you to the essentials of using containerized databases, specifically focusing on MySQL, to enhance flexibility, ease of setup, and consistency across your development environments. The use-cases covered in this guide not only streamline your development workflows but also prepare you for more advanced database management and deployment scenarios, ensuring your data-driven applications remain robust and scalable.

Related information:

* [Docker Hub database images](https://hub.docker.com/search?q=database\&type=image)
* [Dockerfile reference](/reference/dockerfile/)
* [Compose file reference](/reference/compose-file/)
* [CLI reference](/reference/cli/docker/)
* [Database samples](https://docs.docker.com/reference/samples/#databases)

----
url: https://docs.docker.com/reference/cli/docker/service/create/
----

# docker service create

***

| Description | Create a new service                                       |
| ----------- | ---------------------------------------------------------- |
| Usage       | `docker service create [OPTIONS] IMAGE [COMMAND] [ARG...]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Creates a service as described by the specified parameters.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                                              | Default      | Description                                                                                                    |
| --------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
| `--cap-add`                                         |              | API 1.41+ Add Linux capabilities                                                                               |
| `--cap-drop`                                        |              | API 1.41+ Drop Linux capabilities                                                                              |
| [`--config`](#config)                               |              | API 1.30+ Specify configurations to expose to the service                                                      |
| [`--constraint`](#constraint)                       |              | Placement constraints                                                                                          |
| `--container-label`                                 |              | Container labels                                                                                               |
| `--credential-spec`                                 |              | API 1.29+ Credential spec for managed service account (Windows only)                                           |
| `-d, --detach`                                      |              | API 1.29+ Exit immediately instead of waiting for the service to converge                                      |
| `--dns`                                             |              | API 1.25+ Set custom DNS servers                                                                               |
| `--dns-option`                                      |              | API 1.25+ Set DNS options                                                                                      |
| `--dns-search`                                      |              | API 1.25+ Set custom DNS search domains                                                                        |
| `--endpoint-mode`                                   | `vip`        | Endpoint mode (vip or dnsrr)                                                                                   |
| `--entrypoint`                                      |              | Overwrite the default ENTRYPOINT of the image                                                                  |
| [`-e, --env`](#env)                                 |              | Set environment variables                                                                                      |
| `--env-file`                                        |              | Read in a file of environment variables                                                                        |
| `--generic-resource`                                |              | User defined resources                                                                                         |
| `--group`                                           |              | API 1.25+ Set one or more supplementary user groups for the container                                          |
| `--health-cmd`                                      |              | API 1.25+ Command to run to check health                                                                       |
| `--health-interval`                                 |              | API 1.25+ Time between running the check (ms\|s\|m\|h)                                                         |
| `--health-retries`                                  |              | API 1.25+ Consecutive failures needed to report unhealthy                                                      |
| `--health-start-interval`                           |              | API 1.44+ Time between running the check during the start period (ms\|s\|m\|h)                                 |
| `--health-start-period`                             |              | API 1.29+ Start period for the container to initialize before counting retries towards unstable (ms\|s\|m\|h)  |
| `--health-timeout`                                  |              | API 1.25+ Maximum time to allow one check to run (ms\|s\|m\|h)                                                 |
| `--host`                                            |              | API 1.25+ Set one or more custom host-to-IP mappings (host:ip)                                                 |
| [`--hostname`](#hostname)                           |              | API 1.25+ Container hostname                                                                                   |
| `--init`                                            |              | API 1.37+ Use an init inside each service container to forward signals and reap processes                      |
| [`--isolation`](#isolation)                         |              | API 1.35+ Service container isolation mode                                                                     |
| [`-l, --label`](#label)                             |              | Service labels                                                                                                 |
| `--limit-cpu`                                       |              | Limit CPUs                                                                                                     |
| `--limit-memory`                                    |              | Limit Memory                                                                                                   |
| `--limit-pids`                                      |              | API 1.41+ Limit maximum number of processes (default 0 = unlimited)                                            |
| `--log-driver`                                      |              | Logging driver for service                                                                                     |
| `--log-opt`                                         |              | Logging driver options                                                                                         |
| `--max-concurrent`                                  |              | API 1.41+ Number of job tasks to run concurrently (default equal to --replicas)                                |
| `--memory-swap`                                     |              | API 1.52+ Swap Bytes (-1 for unlimited)                                                                        |
| `--memory-swappiness`                               | `-1`         | API 1.52+ Tune memory swappiness (0-100), -1 to reset to default                                               |
| `--mode`                                            | `replicated` | Service mode (`replicated`, `global`, `replicated-job`, `global-job`)                                          |
| [`--mount`](#mount)                                 |              | Attach a filesystem mount to the service                                                                       |
| `--name`                                            |              | Service name                                                                                                   |
| [`--network`](#network)                             |              | Network attachments                                                                                            |
| `--no-healthcheck`                                  |              | API 1.25+ Disable any container-specified HEALTHCHECK                                                          |
| `--no-resolve-image`                                |              | API 1.30+ Do not query the registry to resolve image digest and supported platforms                            |
| `--oom-score-adj`                                   |              | API 1.46+ Tune host's OOM preferences (-1000 to 1000)                                                          |
| [`--placement-pref`](#placement-pref)               |              | API 1.28+ Add a placement preference                                                                           |
| [`-p, --publish`](#publish)                         |              | Publish a port as a node port                                                                                  |
| `-q, --quiet`                                       |              | Suppress progress output                                                                                       |
| `--read-only`                                       |              | API 1.28+ Mount the container's root filesystem as read only                                                   |
| [`--replicas`](#replicas)                           |              | Number of tasks                                                                                                |
| [`--replicas-max-per-node`](#replicas-max-per-node) |              | API 1.40+ Maximum number of tasks per node (default 0 = unlimited)                                             |
| `--reserve-cpu`                                     |              | Reserve CPUs                                                                                                   |
| [`--reserve-memory`](#reserve-memory)               |              | Reserve Memory                                                                                                 |
| `--restart-condition`                               |              | Restart when condition is met (`none`, `on-failure`, `any`) (default `any`)                                    |
| `--restart-delay`                                   |              | Delay between restart attempts (ns\|us\|ms\|s\|m\|h) (default 5s)                                              |
| `--restart-max-attempts`                            |              | Maximum number of restarts before giving up                                                                    |
| `--restart-window`                                  |              | Window used to evaluate the restart policy (ns\|us\|ms\|s\|m\|h)                                               |
| `--rollback-delay`                                  |              | API 1.28+ Delay between task rollbacks (ns\|us\|ms\|s\|m\|h) (default 0s)                                      |
| `--rollback-failure-action`                         |              | API 1.28+ Action on rollback failure (`pause`, `continue`) (default `pause`)                                   |
| `--rollback-max-failure-ratio`                      |              | API 1.28+ Failure rate to tolerate during a rollback (default 0)                                               |
| `--rollback-monitor`                                |              | API 1.28+ Duration after each task rollback to monitor for failure (ns\|us\|ms\|s\|m\|h) (default 5s)          |
| `--rollback-order`                                  |              | API 1.29+ Rollback order (`start-first`, `stop-first`) (default `stop-first`)                                  |
| `--rollback-parallelism`                            | `1`          | API 1.28+ Maximum number of tasks rolled back simultaneously (0 to roll back all at once)                      |
| [`--secret`](#secret)                               |              | API 1.25+ Specify secrets to expose to the service                                                             |
| `--stop-grace-period`                               |              | Time to wait before force killing a container (ns\|us\|ms\|s\|m\|h) (default 10s)                              |
| `--stop-signal`                                     |              | API 1.28+ Signal to stop the container                                                                         |
| `--sysctl`                                          |              | API 1.40+ Sysctl options                                                                                       |
| `-t, --tty`                                         |              | API 1.25+ Allocate a pseudo-TTY                                                                                |
| `--ulimit`                                          |              | API 1.41+ Ulimit options                                                                                       |
| [`--update-delay`](#update-delay)                   |              | Delay between updates (ns\|us\|ms\|s\|m\|h) (default 0s)                                                       |
| `--update-failure-action`                           |              | Action on update failure (`pause`, `continue`, `rollback`) (default `pause`)                                   |
| `--update-max-failure-ratio`                        |              | API 1.25+ Failure rate to tolerate during an update (default 0)                                                |
| `--update-monitor`                                  |              | API 1.25+ Duration after each task update to monitor for failure (ns\|us\|ms\|s\|m\|h) (default 5s)            |
| `--update-order`                                    |              | API 1.29+ Update order (`start-first`, `stop-first`) (default `stop-first`)                                    |
| `--update-parallelism`                              | `1`          | Maximum number of tasks updated simultaneously (0 to update all at once)                                       |
| `-u, --user`                                        |              | Username or UID (format: \<name\|uid>\[:\<group\|gid>])                                                        |
| [`--with-registry-auth`](#with-registry-auth)       |              | Send registry authentication details to swarm agents                                                           |
| `-w, --workdir`                                     |              | Working directory inside the container                                                                         |

## [Examples](#examples)

### [Create a service](#create-a-service)

```console
$ docker service create --name redis redis:7.4.1

dmu1ept4cxcfe8k8lhtux3ro3

$ docker service create --mode global --name redis2 redis:7.4.1

a8q9dasaafudfs8q8w32udass

$ docker service ls

ID            NAME    MODE        REPLICAS  IMAGE
dmu1ept4cxcf  redis   replicated  1/1       redis:7.4.1
a8q9dasaafud  redis2  global      1/1       redis:7.4.1
```

#### [Create a service using an image on a private registry (--with-registry-auth)](#with-registry-auth)

If your image is available on a private registry which requires login, use the `--with-registry-auth` flag with `docker service create`, after logging in. If your image is stored on `registry.example.com`, which is a private registry, use a command like the following:

```console
$ docker login registry.example.com

$ docker service  create \
  --with-registry-auth \
  --name my_service \
  registry.example.com/acme/my_image:latest
```

This passes the login token from your local client to the swarm nodes where the service is deployed, using the encrypted WAL logs. With this information, the nodes are able to log in to the registry and pull the image.

### [Create a service with 5 replica tasks (--replicas)](#replicas)

Use the `--replicas` flag to set the number of replica tasks for a replicated service. The following command creates a `redis` service with `5` replica tasks:

```console
$ docker service create --name redis --replicas=5 redis:7.4.1

4cdgfyky7ozwh3htjfw0d12qv
```

The above command sets the *desired* number of tasks for the service. Even though the command returns immediately, actual scaling of the service may take some time. The `REPLICAS` column shows both the actual and desired number of replica tasks for the service.

In the following example the desired state is `5` replicas, but the current number of `RUNNING` tasks is `3`:

```console
$ docker service ls

ID            NAME   MODE        REPLICAS  IMAGE
4cdgfyky7ozw  redis  replicated  3/5       redis:7.4.1
```

Once all the tasks are created and `RUNNING`, the actual number of tasks is equal to the desired number:

```console
$ docker service ls

ID            NAME   MODE        REPLICAS  IMAGE
4cdgfyky7ozw  redis  replicated  5/5       redis:7.4.1
```

### [Create a service with secrets (--secret)](#secret)

Use the `--secret` flag to give a container access to a [secret](/reference/cli/docker/secret/create/).

Create a service specifying a secret:

```console
$ docker service create --name redis --secret secret.json redis:7.4.1

4cdgfyky7ozwh3htjfw0d12qv
```

Create a service specifying the secret, target, user/group ID, and mode:

```console
$ docker service create --name redis \
    --secret source=ssh-key,target=ssh \
    --secret source=app-key,target=app,uid=1000,gid=1001,mode=0400 \
    redis:7.4.1

4cdgfyky7ozwh3htjfw0d12qv
```

To grant a service access to multiple secrets, use multiple `--secret` flags.

Secrets are located in `/run/secrets` in the container if no target is specified. If no target is specified, the name of the secret is used as the in memory file in the container. If a target is specified, that is used as the filename. In the example above, two files are created: `/run/secrets/ssh` and `/run/secrets/app` for each of the secret targets specified.

### [Create a service with configs (--config)](#config)

Use the `--config` flag to give a container access to a [config](/reference/cli/docker/config/create/).

Create a service with a config. The config will be mounted into `redis-config`, be owned by the user who runs the command inside the container (often `root`), and have file mode `0444` or world-readable. You can specify the `uid` and `gid` as numerical IDs or names. When using names, the provided group/user names must pre-exist in the container. The `mode` is specified as a 4-number sequence such as `0755`.

```console
$ docker service create --name=redis --config redis-conf redis:7.4.1
```

Create a service with a config and specify the target location and file mode:

```console
$ docker service create --name redis \
  --config source=redis-conf,target=/etc/redis/redis.conf,mode=0400 redis:7.4.1
```

To grant a service access to multiple configs, use multiple `--config` flags.

Configs are located in `/` in the container if no target is specified. If no target is specified, the name of the config is used as the name of the file in the container. If a target is specified, that is used as the filename.

### [Create a service with a rolling update policy](#update-delay)

```console
$ docker service create \
  --replicas 10 \
  --name redis \
  --update-delay 10s \
  --update-parallelism 2 \
  redis:7.4.1
```

When you run a [service update](/reference/cli/docker/service/update/), the scheduler updates a maximum of 2 tasks at a time, with `10s` between updates. For more information, refer to the [rolling updates tutorial](/engine/swarm/swarm-tutorial/rolling-update/).

### [Set environment variables (-e, --env)](#env)

This sets an environment variable for all tasks in a service. For example:

```console
$ docker service create \
  --name redis_2 \
  --replicas 5 \
  --env MYVAR=foo \
  redis:7.4.1
```

To specify multiple environment variables, specify multiple `--env` flags, each with a separate key-value pair.

```console
$ docker service create \
  --name redis_2 \
  --replicas 5 \
  --env MYVAR=foo \
  --env MYVAR2=bar \
  redis:7.4.1
```

### [Create a service with specific hostname (--hostname)](#hostname)

This option sets the docker service containers hostname to a specific string. For example:

```console
$ docker service create --name redis --hostname myredis redis:7.4.1
```

### [Set metadata on a service (-l, --label)](#label)

A label is a `key=value` pair that applies metadata to a service. To label a service with two labels:

```console
$ docker service create \
  --name redis_2 \
  --label com.example.foo="bar" \
  --label bar=baz \
  redis:7.4.1
```

For more information about labels, refer to [apply custom metadata](/config/labels-custom-metadata/).

### [Add bind mounts, volumes or memory filesystems (--mount)](#mount)

Docker supports three different kinds of mounts, which allow containers to read from or write to files or directories, either on the host operating system, or on memory filesystems. These types are data volumes (often referred to simply as volumes), bind mounts, tmpfs, and named pipes.

A **bind mount** makes a file or directory on the host available to the container it is mounted within. A bind mount may be either read-only or read-write. For example, a container might share its host's DNS information by means of a bind mount of the host's `/etc/resolv.conf` or a container might write logs to its host's `/var/log/myContainerLogs` directory. If you use bind mounts and your host and containers have different notions of permissions, access controls, or other such details, you will run into portability issues.

A **named volume** is a mechanism for decoupling persistent data needed by your container from the image used to create the container and from the host machine. Named volumes are created and managed by Docker, and a named volume persists even when no container is currently using it. Data in named volumes can be shared between a container and the host machine, as well as between multiple containers. Docker uses a *volume driver* to create, manage, and mount volumes. You can back up or restore volumes using Docker commands.

A **tmpfs** mounts a tmpfs inside a container for volatile data.

A **npipe** mounts a named pipe from the host into the container.

Consider a situation where your image starts a lightweight web server. You could use that image as a base image, copy in your website's HTML files, and package that into another image. Each time your website changed, you'd need to update the new image and redeploy all of the containers serving your website. A better solution is to store the website in a named volume which is attached to each of your web server containers when they start. To update the website, you just update the named volume.

For more information about named volumes, see [Data Volumes](/storage/volumes/).

The following table describes options which apply to both bind mounts and named volumes in a service:

| Option                                   | Required                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **type**                                 |                                  | The type of mount, can be either `volume`, `bind`, `tmpfs`, or `npipe`. Defaults to `volume` if no type is specified.- `volume`: mounts a [managed volume](/reference/cli/docker/volume/create/) into the container.
- `bind`: bind-mounts a directory or file from the host into the container.
- `tmpfs`: mount a tmpfs in the container
- `npipe`: mounts named pipe from the host into the container (Windows containers only).                                                                                                                                                                                                                                                                                                                                                 |
| **src** or **source**                    | for `type=bind` and `type=npipe` | * `type=volume`: `src` is an optional way to specify the name of the volume (for example, `src=my-volume`). If the named volume does not exist, it is automatically created. If no `src` is specified, the volume is assigned a random name which is guaranteed to be unique on the host, but may not be unique cluster-wide. A randomly-named volume has the same lifecycle as its container and is destroyed when the *container* is destroyed (which is upon `service update`, or when scaling or re-balancing the service)

* `type=bind`: `src` is required, and specifies an absolute path to the file or directory to bind-mount (for example, `src=/path/on/host/`). An error is produced if the file or directory does not exist.

* `type=tmpfs`: `src` is not supported. |
| **dst** or **destination** or **target** | yes                              | Mount path inside the container, for example `/some/path/in/container/`. If the path does not exist in the container's filesystem, the Engine creates a directory at the specified location before mounting the volume or bind mount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **readonly** or **ro**                   |                                  | The Engine mounts binds and volumes `read-write` unless `readonly` option is given when mounting the bind or volume. Note that setting `readonly` for a bind-mount may not make its submounts `readonly` depending on the kernel version. See also `bind-recursive`.* `true` or `1` or no value: Mounts the bind or volume read-only.

* `false` or `0`: Mounts the bind or volume read-write.                                                                                                                                                                                                                                                                                                                                                                                      |

#### [Options for bind mounts](#options-for-bind-mounts)

The following options can only be used for bind mounts (`type=bind`):

| Option               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **bind-propagation** | See the [bind propagation section](#bind-propagation).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **consistency**      | The consistency requirements for the mount; one of- `default`: Equivalent to `consistent`.

- `consistent`: Full consistency. The container runtime and the host maintain an identical view of the mount at all times.

- `cached`: The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.

- `delegated`: The container runtime's view of the mount is authoritative. There may be delays before updates made in a container are visible on the host.                                                                                                                                                                                                                                                                                                                                                                                               |
| **bind-recursive**   | By default, submounts are recursively bind-mounted as well. However, this behavior can be confusing when a bind mount is configured with `readonly` option, because submounts may not be mounted as read-only, depending on the kernel version. Set `bind-recursive` to control the behavior of the recursive bind-mount. A value is one of: - <`enabled`: Enables recursive bind-mount. Read-only mounts are made recursively read-only if kernel is v5.12 or later. Otherwise they are not made recursively read-only.
- <`disabled`: Disables recursive bind-mount.
- <`writable`: Enables recursive bind-mount. Read-only mounts are not made recursively read-only.
- <`readonly`: Enables recursive bind-mount. Read-only mounts are made recursively read-only if kernel is v5.12 or later. Otherwise the Engine raises an error.When the option is not specified, the default behavior corresponds to setting `enabled`. |
| **bind-create-src**  | By default, bind mounts require the source path to exist on the daemon host. This is a significant difference from the `-v` flag, which creates the source path if it doesn't exist. Set `bind-create-src` to create the source path on the daemon host if it doesn't exist. A value is optional: - `true` or `1`: Create path on the daemon host if it doesn't exist.

- `false` or `0`: Default behavior. Produces an error if the source path doesn't exist on the daemon host.                                                                                                                                                                                                                                                                                                                                                                                                                                               |

##### [Bind propagation](#bind-propagation)

Bind propagation refers to whether or not mounts created within a given bind mount or named volume can be propagated to replicas of that mount. Consider a mount point `/mnt`, which is also mounted on `/tmp`. The propagation settings control whether a mount on `/tmp/a` would also be available on `/mnt/a`. Each propagation setting has a recursive counterpoint. In the case of recursion, consider that `/tmp/a` is also mounted as `/foo`. The propagation settings control whether `/mnt/a` and/or `/tmp/a` would exist.

The `bind-propagation` option defaults to `rprivate` for both bind mounts and volume mounts, and is only configurable for bind mounts. In other words, named volumes do not support bind propagation.

* **`shared`**: Sub-mounts of the original mount are exposed to replica mounts, and sub-mounts of replica mounts are also propagated to the original mount.
* **`slave`**: similar to a shared mount, but only in one direction. If the original mount exposes a sub-mount, the replica mount can see it. However, if the replica mount exposes a sub-mount, the original mount cannot see it.
* **`private`**: The mount is private. Sub-mounts within it are not exposed to replica mounts, and sub-mounts of replica mounts are not exposed to the original mount.
* **`rshared`**: The same as shared, but the propagation also extends to and from mount points nested within any of the original or replica mount points.
* **`rslave`**: The same as `slave`, but the propagation also extends to and from mount points nested within any of the original or replica mount points.
* **`rprivate`**: The default. The same as `private`, meaning that no mount points anywhere within the original or replica mount points propagate in either direction.

For more information about bind propagation, see the [Linux kernel documentation for shared subtree](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt).

#### [Options for named volumes](#options-for-named-volumes)

The following options can only be used for named volumes (`type=volume`):

| Option            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **volume-driver** | Name of the volume-driver plugin to use for the volume. Defaults to `"local"`, to use the local volume driver to create the volume if the volume does not exist.                                                                                                                                                                                                                                                                                                                                          |
| **volume-label**  | One or more custom metadata ("labels") to apply to the volume upon creation. For example, `volume-label=mylabel=hello-world,my-other-label=hello-mars`. For more information about labels, refer to [apply custom metadata](/config/labels-custom-metadata/).                                                                                                                                                                                                                                             |
| **volume-nocopy** | By default, if you attach an empty volume to a container, and files or directories already existed at the mount-path in the container (`dst`), the Engine copies those files and directories into the volume, allowing the host to access them. Set `volume-nocopy` to disable copying files from the container's filesystem to the volume and mount the empty volume. A value is optional: - `true` or `1`: Default if you do not provide a value. Disables copying.

- `false` or `0`: Enables copying. |
| **volume-opt**    | Options specific to a given volume driver, which will be passed to the driver when creating the volume. Options are provided as a comma-separated list of key/value pairs, for example, `volume-opt=some-option=some-value,volume-opt=some-other-option=some-other-value`. For available options for a given driver, refer to that driver's documentation.                                                                                                                                                |

#### [Options for tmpfs](#options-for-tmpfs)

The following options can only be used for tmpfs mounts (`type=tmpfs`);

| Option         | Description                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------- |
| **tmpfs-size** | Size of the tmpfs mount in bytes. Unlimited by default in Linux.                            |
| **tmpfs-mode** | File mode of the tmpfs in octal. (e.g. `"700"` or `"0700"`.) Defaults to `"1777"` in Linux. |

#### [Differences between "--mount" and "--volume"](#differences-between---mount-and---volume)

The `--mount` flag supports most options that are supported by the `-v` or `--volume` flag for `docker run`, with some important exceptions:

* The `--mount` flag allows you to specify a volume driver and volume driver options *per volume*, without creating the volumes in advance. In contrast, `docker run` allows you to specify a single volume driver which is shared by all volumes, using the `--volume-driver` flag.

* The `--mount` flag allows you to specify custom metadata ("labels") for a volume, before the volume is created.

* When you use `--mount` with `type=bind`, the host-path must refer to an *existing* path on the host. The path will not be created for you and the service will fail with an error if the path does not exist. You can use `bind-create-src` to create the host path if it doesn't exist.

* The `--mount` flag does not allow you to relabel a volume with `Z` or `z` flags, which are used for `selinux` labeling.

#### [Create a service using a named volume](#create-a-service-using-a-named-volume)

The following example creates a service that uses a named volume:

```console
$ docker service create \
  --name my-service \
  --replicas 3 \
  --mount type=volume,source=my-volume,destination=/path/in/container,volume-label="color=red",volume-label="shape=round" \
  nginx:alpine
```

For each replica of the service, the engine requests a volume named "my-volume" from the default ("local") volume driver where the task is deployed. If the volume does not exist, the engine creates a new volume and applies the "color" and "shape" labels.

When the task is started, the volume is mounted on `/path/in/container/` inside the container.

Be aware that the default ("local") volume is a locally scoped volume driver. This means that depending on where a task is deployed, either that task gets a *new* volume named "my-volume", or shares the same "my-volume" with other tasks of the same service. Multiple containers writing to a single shared volume can cause data corruption if the software running inside the container is not designed to handle concurrent processes writing to the same location. Also take into account that containers can be re-scheduled by the Swarm orchestrator and be deployed on a different node.

#### [Create a service that uses an anonymous volume](#create-a-service-that-uses-an-anonymous-volume)

The following command creates a service with three replicas with an anonymous volume on `/path/in/container`:

```console
$ docker service create \
  --name my-service \
  --replicas 3 \
  --mount type=volume,destination=/path/in/container \
  nginx:alpine
```

In this example, no name (`source`) is specified for the volume, so a new volume is created for each task. This guarantees that each task gets its own volume, and volumes are not shared between tasks. Anonymous volumes are removed after the task using them is complete.

#### [Create a service that uses a bind-mounted host directory](#create-a-service-that-uses-a-bind-mounted-host-directory)

The following example bind-mounts a host directory at `/path/in/container` in the containers backing the service:

```console
$ docker service create \
  --name my-service \
  --mount type=bind,source=/path/on/host,destination=/path/in/container \
  nginx:alpine
```

### [Set service mode (--mode)](#set-service-mode---mode)

The service mode determines whether this is a *replicated* service or a *global* service. A replicated service runs as many tasks as specified, while a global service runs on each active node in the swarm.

The following command creates a global service:

```console
$ docker service create \
 --name redis_2 \
 --mode global \
 redis:7.4.1
```

### [Specify service constraints (--constraint)](#constraint)

You can limit the set of nodes where a task can be scheduled by defining constraint expressions. Constraint expressions can either use a *match* (`==`) or *exclude* (`!=`) rule. Multiple constraints find nodes that satisfy every expression (AND match). Constraints can match node or Docker Engine labels as follows:

| node attribute       | matches                        | example                                       |
| -------------------- | ------------------------------ | --------------------------------------------- |
| `node.id`            | Node ID                        | `node.id==2ivku8v2gvtg4`                      |
| `node.hostname`      | Node hostname                  | `node.hostname!=node-2`                       |
| `node.role`          | Node role (`manager`/`worker`) | `node.role==manager`                          |
| `node.platform.os`   | Node operating system          | `node.platform.os==windows`                   |
| `node.platform.arch` | Node architecture              | `node.platform.arch==x86_64`                  |
| `node.labels`        | User-defined node labels       | `node.labels.security==high`                  |
| `engine.labels`      | Docker Engine's labels         | `engine.labels.operatingsystem==ubuntu-24.04` |

`engine.labels` apply to Docker Engine labels like operating system, drivers, etc. Swarm administrators add `node.labels` for operational purposes by using the [`docker node update`](/reference/cli/docker/node/update/) command.

For example, the following limits tasks for the redis service to nodes where the node type label equals queue:

```console
$ docker service create \
  --name redis_2 \
  --constraint node.platform.os==linux \
  --constraint node.labels.type==queue \
  redis:7.4.1
```

If the service constraints exclude all nodes in the cluster, a message is printed that no suitable node is found, but the scheduler will start a reconciliation loop and deploy the service once a suitable node becomes available.

In the example below, no node satisfying the constraint was found, causing the service to not reconcile with the desired state:

```console
$ docker service create \
  --name web \
  --constraint node.labels.region==east \
  nginx:alpine

lx1wrhhpmbbu0wuk0ybws30bc
overall progress: 0 out of 1 tasks
1/1: no suitable node (scheduling constraints not satisfied on 5 nodes)

$ docker service ls
ID                  NAME     MODE         REPLICAS   IMAGE               PORTS
b6lww17hrr4e        web      replicated   0/1        nginx:alpine
```

After adding the `region=east` label to a node in the cluster, the service reconciles, and the desired number of replicas are deployed:

```console
$ docker node update --label-add region=east yswe2dm4c5fdgtsrli1e8ya5l
yswe2dm4c5fdgtsrli1e8ya5l

$ docker service ls
ID                  NAME     MODE         REPLICAS   IMAGE               PORTS
b6lww17hrr4e        web      replicated   1/1        nginx:alpine
```

### [Specify service placement preferences (--placement-pref)](#placement-pref)

You can set up the service to divide tasks evenly over different categories of nodes. One example of where this can be useful is to balance tasks over a set of datacenters or availability zones. The example below illustrates this:

```console
$ docker service create \
  --replicas 9 \
  --name redis_2 \
  --placement-pref spread=node.labels.datacenter \
  redis:7.4.1
```

This uses `--placement-pref` with a `spread` strategy (currently the only supported strategy) to spread tasks evenly over the values of the `datacenter` node label. In this example, we assume that every node has a `datacenter` node label attached to it. If there are three different values of this label among nodes in the swarm, one third of the tasks will be placed on the nodes associated with each value. This is true even if there are more nodes with one value than another. For example, consider the following set of nodes:

* Three nodes with `node.labels.datacenter=east`
* Two nodes with `node.labels.datacenter=south`
* One node with `node.labels.datacenter=west`

Since we are spreading over the values of the `datacenter` label and the service has 9 replicas, 3 replicas will end up in each datacenter. There are three nodes associated with the value `east`, so each one will get one of the three replicas reserved for this value. There are two nodes with the value `south`, and the three replicas for this value will be divided between them, with one receiving two replicas and another receiving just one. Finally, `west` has a single node that will get all three replicas reserved for `west`.

If the nodes in one category (for example, those with `node.labels.datacenter=south`) can't handle their fair share of tasks due to constraints or resource limitations, the extra tasks will be assigned to other nodes instead, if possible.

Both engine labels and node labels are supported by placement preferences. The example above uses a node label, because the label is referenced with `node.labels.datacenter`. To spread over the values of an engine label, use `--placement-pref spread=engine.labels.<labelname>`.

It is possible to add multiple placement preferences to a service. This establishes a hierarchy of preferences, so that tasks are first divided over one category, and then further divided over additional categories. One example of where this may be useful is dividing tasks fairly between datacenters, and then splitting the tasks within each datacenter over a choice of racks. To add multiple placement preferences, specify the `--placement-pref` flag multiple times. The order is significant, and the placement preferences will be applied in the order given when making scheduling decisions.

The following example sets up a service with multiple placement preferences. Tasks are spread first over the various datacenters, and then over racks (as indicated by the respective labels):

```console
$ docker service create \
  --replicas 9 \
  --name redis_2 \
  --placement-pref 'spread=node.labels.datacenter' \
  --placement-pref 'spread=node.labels.rack' \
  redis:7.4.1
```

When updating a service with `docker service update`, `--placement-pref-add` appends a new placement preference after all existing placement preferences. `--placement-pref-rm` removes an existing placement preference that matches the argument.

### [Specify memory requirements and constraints for a service (--reserve-memory and --limit-memory)](#reserve-memory)

If your service needs a minimum amount of memory in order to run correctly, you can use `--reserve-memory` to specify that the service should only be scheduled on a node with this much memory available to reserve. If no node is available that meets the criteria, the task is not scheduled, but remains in a pending state.

The following example requires that 4GB of memory be available and reservable on a given node before scheduling the service to run on that node.

```console
$ docker service create --reserve-memory=4GB --name=too-big nginx:alpine
```

The managers won't schedule a set of containers on a single node whose combined reservations exceed the memory available on that node.

After a task is scheduled and running, `--reserve-memory` does not enforce a memory limit. Use `--limit-memory` to ensure that a task uses no more than a given amount of memory on a node. This example limits the amount of memory used by the task to 4GB. The task will be scheduled even if each of your nodes has only 2GB of memory, because `--limit-memory` is an upper limit.

```console
$ docker service create --limit-memory=4GB --name=too-big nginx:alpine
```

Using `--reserve-memory` and `--limit-memory` does not guarantee that Docker will not use more memory on your host than you want. For instance, you could create many services, the sum of whose memory usage could exhaust the available memory.

You can prevent this scenario from exhausting the available memory by taking into account other (non-containerized) software running on the host as well. If `--reserve-memory` is greater than or equal to `--limit-memory`, Docker won't schedule a service on a host that doesn't have enough memory. `--limit-memory` will limit the service's memory to stay within that limit, so if every service has a memory-reservation and limit set, Docker services will be less likely to saturate the host. Other non-service containers or applications running directly on the Docker host could still exhaust memory.

There is a downside to this approach. Reserving memory also means that you may not make optimum use of the memory available on the node. Consider a service that under normal circumstances uses 100MB of memory, but depending on load can "peak" at 500MB. Reserving 500MB for that service (to guarantee can have 500MB for those "peaks") results in 400MB of memory being wasted most of the time.

In short, you can take a more conservative or more flexible approach:

* **Conservative**: reserve 500MB, and limit to 500MB. Basically you're now treating the service containers as VMs, and you may be losing a big advantage containers, which is greater density of services per host.

* **Flexible**: limit to 500MB in the assumption that if the service requires more than 500MB, it is malfunctioning. Reserve something between the 100MB "normal" requirement and the 500MB "peak" requirement". This assumes that when this service is at "peak", other services or non-container workloads probably won't be.

The approach you take depends heavily on the memory-usage patterns of your workloads. You should test under normal and peak conditions before settling on an approach.

On Linux, you can also limit a service's overall memory footprint on a given host at the level of the host operating system, using `cgroups` or other relevant operating system tools.

### [Specify maximum replicas per node (--replicas-max-per-node)](#replicas-max-per-node)

Use the `--replicas-max-per-node` flag to set the maximum number of replica tasks that can run on a node. The following command creates a nginx service with 2 replica tasks but only one replica task per node.

One example where this can be useful is to balance tasks over a set of data centers together with `--placement-pref` and let `--replicas-max-per-node` setting make sure that replicas are not migrated to another datacenter during maintenance or datacenter failure.

The example below illustrates this:

```console
$ docker service create \
  --name nginx \
  --replicas 2 \
  --replicas-max-per-node 1 \
  --placement-pref 'spread=node.labels.datacenter' \
  nginx
```

### [Attach a service to an existing network (--network)](#network)

You can use overlay networks to connect one or more services within the swarm.

First, create an overlay network on a manager node the docker network create command:

```console
$ docker network create --driver overlay my-network

etjpu59cykrptrgw0z0hk5snf
```

After you create an overlay network in swarm mode, all manager nodes have access to the network.

When you create a service and pass the `--network` flag to attach the service to the overlay network:

```console
$ docker service create \
  --replicas 3 \
  --network my-network \
  --name my-web \
  nginx

716thylsndqma81j6kkkb5aus
```

The swarm extends my-network to each node running the service.

Containers on the same network can access each other using [service discovery](/engine/network/drivers/overlay/#container-discovery).

Long form syntax of `--network` allows to specify list of aliases and driver options: `--network name=my-network,alias=web1,driver-opt=field1=value1`

### [Publish service ports externally to the swarm (-p, --publish)](#publish)

You can publish service ports to make them available externally to the swarm using the `--publish` flag. The `--publish` flag can take two different styles of arguments. The short version is positional, and allows you to specify the published port and target port separated by a colon (`:`).

```console
$ docker service create --name my_web --replicas 3 --publish 8080:80 nginx
```

There is also a long format, which is easier to read and allows you to specify more options. The long format is preferred. You cannot specify the service's mode when using the short format. Here is an example of using the long format for the same service as above:

```console
$ docker service create --name my_web --replicas 3 --publish published=8080,target=80 nginx
```

The options you can specify are:

| Option                    | Short syntax                            | Long syntax                                       | Description                                                                                                                                                                                                                                                            |
| ------------------------- | --------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| published and target port | `--publish 8080:80`                     | `--publish published=8080,target=80`              | The target port within the container and the port to map it to on the nodes, using the routing mesh (`ingress`) or host-level networking. More options are available, later in this table. The key-value syntax is preferred, because it is somewhat self-documenting. |
| mode                      | Not possible to set using short syntax. | `--publish published=8080,target=80,mode=host`    | The mode to use for binding the port, either `ingress` or `host`. Defaults to `ingress` to use the routing mesh.                                                                                                                                                       |
| protocol                  | `--publish 8080:80/tcp`                 | `--publish published=8080,target=80,protocol=tcp` | The protocol to use, `tcp` , `udp`, or `sctp`. Defaults to `tcp`. To bind a port for both protocols, specify the `-p` or `--publish` flag twice.                                                                                                                       |

When you publish a service port using `ingress` mode, the swarm routing mesh makes the service accessible at the published port on every node regardless if there is a task for the service running on the node. If you use `host` mode, the port is only bound on nodes where the service is running, and a given port on a node can only be bound once. You can only set the publication mode using the long syntax. For more information refer to [Use swarm mode routing mesh](/engine/swarm/ingress/).

### [Provide credential specs for managed service accounts (--credentials-spec)](#credentials-spec)

This option is only used for services using Windows containers. The `--credential-spec` must be in the format `file://<filename>` or `registry://<value-name>`.

When using the `file://<filename>` format, the referenced file must be present in the `CredentialSpecs` subdirectory in the docker data directory, which defaults to `C:\ProgramData\Docker\` on Windows. For example, specifying `file://spec.json` loads `C:\ProgramData\Docker\CredentialSpecs\spec.json`.

When using the `registry://<value-name>` format, the credential spec is read from the Windows registry on the daemon's host. The specified registry value must be located in:

```
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs
```

### [Create services using templates](#create-services-using-templates)

You can use templates for some flags of `service create`, using the syntax provided by the Go's [text/template](https://pkg.go.dev/text/template) package.

The supported flags are the following :

* `--hostname`
* `--mount`
* `--env`

Valid placeholders for the Go template are listed below:

| Placeholder       | Description    |
| ----------------- | -------------- |
| `.Service.ID`     | Service ID     |
| `.Service.Name`   | Service name   |
| `.Service.Labels` | Service labels |
| `.Node.ID`        | Node ID        |
| `.Node.Hostname`  | Node Hostname  |
| `.Task.ID`        | Task ID        |
| `.Task.Name`      | Task name      |
| `.Task.Slot`      | Task slot      |

#### [Template example](#template-example)

In this example, we are going to set the template of the created containers based on the service's name, the node's ID and hostname where it sits.

```console
$ docker service create \
    --name hosttempl \
    --hostname="{{.Node.Hostname}}-{{.Node.ID}}-{{.Service.Name}}"\
    busybox top

va8ew30grofhjoychbr6iot8c

$ docker service ps va8ew30grofhjoychbr6iot8c

ID            NAME         IMAGE                                                                                   NODE          DESIRED STATE  CURRENT STATE               ERROR  PORTS
wo41w8hg8qan  hosttempl.1  busybox:latest@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912  2e7a8a9c4da2  Running        Running about a minute ago

$ docker inspect --format="{{.Config.Hostname}}" 2e7a8a9c4da2-wo41w8hg8qanxwjwsg4kxpprj-hosttempl

x3ti0erg11rjpg64m75kej2mz-hosttempl
```

### [Specify isolation mode on Windows (--isolation)](#isolation)

By default, tasks scheduled on Windows nodes are run using the default isolation mode configured for this particular node. To force a specific isolation mode, you can use the `--isolation` flag:

```console
$ docker service create --name myservice --isolation=process microsoft/nanoserver
```

Supported isolation modes on Windows are:

* `default`: use default settings specified on the node running the task
* `process`: use process isolation (Windows server only)
* `hyperv`: use Hyper-V isolation

### [Create services requesting Generic Resources (--generic-resources)](#generic-resources)

You can narrow the kind of nodes your task can land on through the using the `--generic-resource` flag (if the nodes advertise these resources):

```console
$ docker service create \
    --name cuda \
    --generic-resource "NVIDIA-GPU=2" \
    --generic-resource "SSD=1" \
    nvidia/cuda
```

### [Running as a job](#running-as-a-job)

Jobs are a special kind of service designed to run an operation to completion and then stop, as opposed to running long-running daemons. When a Task belonging to a job exits successfully (return value 0), the Task is marked as "Completed", and is not run again.

Jobs are started by using one of two modes, `replicated-job` or `global-job`

```console
$ docker service create --name myjob \
                        --mode replicated-job \
                        bash "true"
```

This command will run one Task, which will, using the `bash` image, execute the command `true`, which will return 0 and then exit.

Though Jobs are ultimately a different kind of service, they a couple of caveats compared to other services:

* None of the update or rollback configuration options are valid. Jobs can be updated, but cannot be rolled out or rolled back, making these configuration options moot.
* Jobs are never restarted on reaching the `Complete` state. This means that for jobs, setting `--restart-condition` to `any` is the same as setting it to `on-failure`.

Jobs are available in both replicated and global modes.

#### [Replicated Jobs](#replicated-jobs)

A replicated job is like a replicated service. Setting the `--replicas` flag will specify total number of iterations of a job to execute.

By default, all replicas of a replicated job will launch at once. To control the total number of replicas that are executing simultaneously at any one time, the `--max-concurrent` flag can be used:

```console
$ docker service create \
    --name mythrottledjob \
    --mode replicated-job \
    --replicas 10 \
    --max-concurrent 2 \
    bash "true"
```

The above command will execute 10 Tasks in total, but only 2 of them will be run at any given time.

#### [Global Jobs](#global-jobs)

Global jobs are like global services, in that a Task is executed once on each node matching placement constraints. Global jobs are represented by the mode `global-job`.

Note that after a Global job is created, any new Nodes added to the cluster will have a Task from that job started on them. The Global Job does not as a whole have a "done" state, except insofar as every Node meeting the job's constraints has a Completed task.

----
url: https://docs.docker.com/get-started/docker-overview/
----

# What is Docker?

***

Table of contents

***

Docker is an open platform for developing, shipping, and running applications. Docker enables you to separate your applications from your infrastructure so you can deliver software quickly. With Docker, you can manage your infrastructure in the same ways you manage your applications. By taking advantage of Docker's methodologies for shipping, testing, and deploying code, you can significantly reduce the delay between writing code and running it in production.

## [The Docker platform](#the-docker-platform)

Docker provides the ability to package and run an application in a loosely isolated environment called a container. The isolation and security let you run many containers simultaneously on a given host. Containers are lightweight and contain everything needed to run the application, so you don't need to rely on what's installed on the host. You can share containers while you work, and be sure that everyone you share with gets the same container that works in the same way.

Docker provides tooling and a platform to manage the lifecycle of your containers:

* Develop your application and its supporting components using containers.
* The container becomes the unit for distributing and testing your application.
* When you're ready, deploy your application into your production environment, as a container or an orchestrated service. This works the same whether your production environment is a local data center, a cloud provider, or a hybrid of the two.

## [What can I use Docker for?](#what-can-i-use-docker-for)

### [Fast, consistent delivery of your applications](#fast-consistent-delivery-of-your-applications)

Docker streamlines the development lifecycle by allowing developers to work in standardized environments using local containers which provide your applications and services. Containers are great for continuous integration and continuous delivery (CI/CD) workflows.

Consider the following example scenario:

* Your developers write code locally and share their work with their colleagues using Docker containers.
* They use Docker to push their applications into a test environment and run automated and manual tests.
* When developers find bugs, they can fix them in the development environment and redeploy them to the test environment for testing and validation.
* When testing is complete, getting the fix to the customer is as simple as pushing the updated image to the production environment.

### [Responsive deployment and scaling](#responsive-deployment-and-scaling)

Docker's container-based platform allows for highly portable workloads. Docker containers can run on a developer's local laptop, on physical or virtual machines in a data center, on cloud providers, or in a mixture of environments.

Docker's portability and lightweight nature also make it easy to dynamically manage workloads, scaling up or tearing down applications and services as business needs dictate, in near real time.

### [Running more workloads on the same hardware](#running-more-workloads-on-the-same-hardware)

Docker is lightweight and fast. It provides a viable, cost-effective alternative to hypervisor-based virtual machines, so you can use more of your server capacity to achieve your business goals. Docker is perfect for high density environments and for small and medium deployments where you need to do more with fewer resources.

## [Docker architecture](#docker-architecture)

Docker uses a client-server architecture. The Docker client talks to the Docker daemon, which does the heavy lifting of building, running, and distributing your Docker containers. The Docker client and daemon can run on the same system, or you can connect a Docker client to a remote Docker daemon. The Docker client and daemon communicate using a REST API, over UNIX sockets or a network interface. Another Docker client is Docker Compose, that lets you work with applications consisting of a set of containers.

### [The Docker daemon](#the-docker-daemon)

The Docker daemon (`dockerd`) listens for Docker API requests and manages Docker objects such as images, containers, networks, and volumes. A daemon can also communicate with other daemons to manage Docker services.

### [The Docker client](#the-docker-client)

The Docker client (`docker`) is the primary way that many Docker users interact with Docker. When you use commands such as `docker run`, the client sends these commands to `dockerd`, which carries them out. The `docker` command uses the Docker API. The Docker client can communicate with more than one daemon.

### [Docker Desktop](#docker-desktop)

Docker Desktop is an easy-to-install application for your Mac, Windows, or Linux environment that enables you to build and share containerized applications and microservices. Docker Desktop includes the Docker daemon (`dockerd`), the Docker client (`docker`), Docker Compose, Docker Content Trust, Kubernetes, and Credential Helper. For more information, see [Docker Desktop](https://docs.docker.com/desktop/).

### [Docker registries](#docker-registries)

A Docker registry stores Docker images. Docker Hub is a public registry that anyone can use, and Docker looks for images on Docker Hub by default. You can even run your own private registry.

When you use the `docker pull` or `docker run` commands, Docker pulls the required images from your configured registry. When you use the `docker push` command, Docker pushes your image to your configured registry.

### [Docker objects](#docker-objects)

When you use Docker, you are creating and using images, containers, networks, volumes, plugins, and other objects. This section is a brief overview of some of those objects.

#### [Images](#images)

An image is a read-only template with instructions for creating a Docker container. Often, an image is based on another image, with some additional customization. For example, you may build an image that is based on the Ubuntu image but includes the Apache web server and your application, as well as the configuration details needed to make your application run.

You might create your own images or you might only use those created by others and published in a registry. To build your own image, you create a Dockerfile with a simple syntax for defining the steps needed to create the image and run it. Each instruction in a Dockerfile creates a layer in the image. When you change the Dockerfile and rebuild the image, only those layers which have changed are rebuilt. This is part of what makes images so lightweight, small, and fast, when compared to other virtualization technologies.

#### [Containers](#containers)

A container is a runnable instance of an image. You can create, start, stop, move, or delete a container using the Docker API or CLI. You can connect a container to one or more networks, attach storage to it, or even create a new image based on its current state.

By default, a container is relatively well isolated from other containers and its host machine. You can control how isolated a container's network, storage, or other underlying subsystems are from other containers or from the host machine.

A container is defined by its image as well as any configuration options you provide to it when you create or start it. When a container is removed, any changes to its state that aren't stored in persistent storage disappear.

##### [Example `docker run` command](#example-docker-run-command)

The following command runs an `ubuntu` container, attaches interactively to your local command-line session, and runs `/bin/bash`.

```console
$ docker run -i -t ubuntu /bin/bash
```

When you run this command, the following happens (assuming you are using the default registry configuration):

1. If you don't have the `ubuntu` image locally, Docker pulls it from your configured registry, as though you had run `docker pull ubuntu` manually.

2. Docker creates a new container, as though you had run a `docker container create` command manually.

3. Docker allocates a read-write filesystem to the container, as its final layer. This allows a running container to create or modify files and directories in its local filesystem.

4. Docker creates a network interface to connect the container to the default network, since you didn't specify any networking options. This includes assigning an IP address to the container. By default, containers can connect to external networks using the host machine's network connection.

5. Docker starts the container and executes `/bin/bash`. Because the container is running interactively and attached to your terminal (due to the `-i` and `-t` flags), you can provide input using your keyboard while Docker logs the output to your terminal.

6. When you run `exit` to terminate the `/bin/bash` command, the container stops but isn't removed. You can start it again or remove it.

## [The underlying technology](#the-underlying-technology)

Docker is written in the [Go programming language](https://golang.org/) and takes advantage of several features of the Linux kernel to deliver its functionality. Docker uses a technology called `namespaces` to provide the isolated workspace called the container. When you run a container, Docker creates a set of namespaces for that container.

These namespaces provide a layer of isolation. Each aspect of a container runs in a separate namespace and its access is limited to that namespace.

## [Next steps](#next-steps)

* [Install Docker](https://docs.docker.com/get-started/get-docker/)
* [Get started with Docker](https://docs.docker.com/get-started/introduction/)

----
url: https://docs.docker.com/reference/cli/docker/compose/restart/
----

# docker compose restart

***

| Description | Restart service containers                      |
| ----------- | ----------------------------------------------- |
| Usage       | `docker compose restart [OPTIONS] [SERVICE...]` |

## [Description](#description)

Restarts all stopped and running services, or the specified services only.

If you make changes to your `compose.yml` configuration, these changes are not reflected after running this command. For example, changes to environment variables (which are added after a container is built, but before the container's command is executed) are not updated after restarting.

If you are looking to configure a service's restart policy, refer to [restart](https://github.com/compose-spec/compose-spec/blob/main/spec.md#restart) or [restart\_policy](https://github.com/compose-spec/compose-spec/blob/main/deploy.md#restart_policy).

## [Options](#options)

| Option          | Default | Description                           |
| --------------- | ------- | ------------------------------------- |
| `--no-deps`     |         | Don't restart dependent services      |
| `-t, --timeout` |         | Specify a shutdown timeout in seconds |

----
url: https://docs.docker.com/scout/quickstart/
----

# Docker Scout quickstart

***

Table of contents

***

Docker Scout analyzes image contents and generates a detailed report of packages and vulnerabilities that it detects. It can provide you with suggestions for how to remediate issues discovered by image analysis.

This guide takes a vulnerable container image and shows you how to use Docker Scout to identify and fix the vulnerabilities, compare image versions over time, and share the results with your team.

## [Step 1: Setup](#step-1-setup)

[This example project](https://github.com/docker/scout-demo-service) contains a vulnerable Node.js application that you can use to follow along.

1. Clone its repository:

   ```console
   $ git clone https://github.com/docker/scout-demo-service.git
   ```

2. Move into the directory:

   ```console
   $ cd scout-demo-service
   ```

3. Make sure you're signed in to your Docker account, either by running the `docker login` command or by signing in with Docker Desktop.

4. Build the image and push it to a `<ORG_NAME>/scout-demo:v1`, where `<ORG_NAME>` is the Docker Hub namespace you push to.

   ```console
   $ docker build --push -t ORG_NAME/scout-demo:v1 .
   ```

## [Step 2: Enable Docker Scout](#step-2-enable-docker-scout)

Docker Scout analyzes all local images by default. To analyze images in remote repositories, you need to enable it first. You can do this from Docker Hub, the Docker Scout Dashboard, and CLI. [Find out how in the overview guide](/scout).

1. Sign in to your Docker account with the `docker login` command or use the **Sign in** button in Docker Desktop.

2. Next, enroll your organization with Docker Scout, using the `docker scout enroll` command.

   ```console
   $ docker scout enroll ORG_NAME
   ```

3. Enable Docker Scout for your image repository with the `docker scout repo enable` command.

   ```console
   $ docker scout repo enable --org ORG_NAME ORG_NAME/scout-demo
   ```

## [Step 3: Analyze image vulnerabilities](#step-3-analyze-image-vulnerabilities)

After building, use the `docker scout` CLI command to see vulnerabilities detected by Docker Scout.

The example application for this guide uses a vulnerable version of Express. The following command shows all CVEs affecting Express in the image you just built:

```console
$ docker scout cves --only-package express
```

Docker Scout analyzes the image you built most recently by default, so there's no need to specify the name of the image in this case.

Learn more about the `docker scout cves` command in the [`CLI reference documentation`](/reference/cli/docker/scout/cves).

## [Step 4: Fix application vulnerabilities](#step-4-fix-application-vulnerabilities)

After the Docker Scout analysis, a high vulnerability CVE-2022-24999 was found, caused by an outdated version of the **express** package.

The version 4.17.3 of the express package fixes the vulnerability. Therefore, update the `package.json` file to the new version:

```diff
   "dependencies": {
-    "express": "4.17.1"
+    "express": "4.17.3"
   }
```

Rebuild the image with a new tag and push it to your Docker Hub repository:

```console
$ docker build --push -t ORG_NAME/scout-demo:v2 .
```

Run the `docker scout` command again and verify that HIGH CVE-2022-24999 is no longer present:

```console
$ docker scout cves --only-package express
    ✓ Provenance obtained from attestation
    ✓ Image stored for indexing
    ✓ Indexed 79 packages
    ✓ No vulnerable package detected


  ## Overview

                      │                  Analyzed Image                   
  ────────────────────┼───────────────────────────────────────────────────
    Target            │  mobywhale/scout-demo:v2                   
      digest          │  ef68417b2866                                     
      platform        │ linux/arm64                                       
      provenance      │ https://github.com/docker/scout-demo-service.git  
                      │  7c3a06793fc8f97961b4a40c73e0f7ed85501857         
      vulnerabilities │    0C     0H     0M     0L                        
      size            │ 19 MB                                             
      packages        │ 1                                                 


  ## Packages and Vulnerabilities

  No vulnerable packages detected
```

## [Step 5: Evaluate policy compliance](#step-5-evaluate-policy-compliance)

While inspecting vulnerabilities based on specific packages can be useful, it isn't the most effective way to improve your supply chain conduct.

Docker Scout also supports policy evaluation, a higher-level concept for detecting and fixing issues in your images. Policies are a set of customizable rules that let organizations track whether images are compliant with their supply chain requirements.

Because policy rules are specific to each organization, you must specify which organization's policy you're evaluating against. Use the `docker scout config` command to configure your Docker organization.

```console
$ docker scout config organization ORG_NAME
    ✓ Successfully set organization to ORG_NAME
```

Now you can run the `quickview` command to get an overview of the compliance status for the image you just built. The image is evaluated against the default policy configurations. You'll see output similar to the following:

```console
$ docker scout quickview

...
Policy status  FAILED  (2/6 policies met, 2 missing data)

  Status │                  Policy                      │           Results
─────────┼──────────────────────────────────────────────┼──────────────────────────────
  ✓      │ No copyleft licenses                         │    0 packages
  !      │ Default non-root user                        │
  !      │ No fixable critical or high vulnerabilities  │    2C    16H     0M     0L
  ✓      │ No high-profile vulnerabilities              │    0C     0H     0M     0L
  ?      │ No outdated base images                      │    No data
  ?      │ Supply chain attestations                    │    No data
```

Exclamation marks in the status column indicate a violated policy. Question marks indicate that there isn't enough metadata to complete the evaluation. A check mark indicates compliance.

## [Step 6: Improve compliance](#step-6-improve-compliance)

The output of the `quickview` command shows that there's room for improvement. Some of the policies couldn't evaluate successfully (`No data`) because the image lacks provenance and SBOM attestations. The image also failed the check on a few of the evaluations.

Policy evaluation does more than just check for vulnerabilities. Take the `Default non-root user` policy for example. This policy helps improve runtime security by ensuring that images aren't set to run as the `root` superuser by default.

To address this policy violation, edit the Dockerfile by adding a `USER` instruction, specifying a non-root user:

```diff
  CMD ["node","/app/app.js"]
  EXPOSE 3000
+ USER appuser
```

Additionally, to get a more complete policy evaluation result, your image should have SBOM and provenance attestations attached to it. Docker Scout uses the provenance attestations to determine how the image was built so that it can provide a better evaluation result.

Before you can build an image with attestations, you must enable the [containerd image store](https://docs.docker.com/desktop/features/containerd/) (or create a custom builder using the `docker-container` driver). The classic image store doesn't support manifest lists, which is how the provenance attestations are attached to an image.

Open **Settings** in Docker Desktop. Under the **General** section, make sure that the **Use containerd for pulling and storing images** option is checked, then select **Apply**. Note that changing image stores temporarily hides images and containers of the inactive image store until you switch back.

With the containerd image store enabled, rebuild the image with a new `v3` tag. This time, add the `--provenance=true` and `--sbom=true` flags.

```console
$ docker build --provenance=true --sbom=true --push -t ORG_NAME/scout-demo:v3 .
```

## [Step 7: View in Dashboard](#step-7-view-in-dashboard)

After pushing the updated image with attestations, it's time to view the results through a different lens: the Docker Scout Dashboard.

1. Open the [Docker Scout Dashboard](https://scout.docker.com/).
2. Sign in with your Docker account.
3. Select **Images** in the left-hand navigation.

The images page lists your Scout-enabled repositories.

Select the row for the image you want to view, anywhere in the row except on a link, to open the **Image details** sidebar.

The sidebar shows a compliance overview for the last pushed tag of a repository.

> Note
>
> If policy results haven't appeared yet, try refreshing the page. It might take a few minutes before the results appear if this is your first time using the Docker Scout Dashboard.

Go back to the image list and select the image version, available in the **Most recent image** column. Then, at the top right of the page, select the **Update base image** button to inspect the policy.

This policy checks whether base images you use are up-to-date. It currently has a non-compliant status, because the example image uses an old version `alpine` as a base image.

Close the **Recommended fixes for base image** modal. In the policy listing, select **View fixes** button, next to the policy name for details about the violation, and recommendations on how to address it.

In this case, the recommended action is to enable [Docker Scout's GitHub integration](https://docs.docker.com/scout/integrations/source-code-management/github/), which helps keep your base images up-to-date automatically.

> Tip
>
> You can't enable this integration for the demo app used in this guide. Feel free to push the code to a GitHub repository that you own, and try out the integration there!

## [Summary](#summary)

This quickstart guide has scratched the surface on some of the ways Docker Scout can support software supply chain management:

* How to enable Docker Scout for your repositories
* Analyzing images for vulnerabilities
* Policy and compliance
* Fixing vulnerabilities and improving compliance

## [What's next?](#whats-next)

There's lots more to discover, from third-party integrations, to policy customization, and runtime environment monitoring in real-time.

Check out the following sections:

* [Image analysis](https://docs.docker.com/scout/explore/analysis/)
* [Data sources](/scout/advisory-db-sources)
* [Docker Scout Dashboard](/scout/dashboard)
* [Integrations](https://docs.docker.com/scout/integrations/)
* [Policy evaluation](https://docs.docker.com/scout/policy/)

----
url: https://docs.docker.com/engine/release-notes/25.0/
----

# Docker Engine 25.0 release notes

***

Table of contents

***

This page describes the latest changes, additions, known issues, and fixes for Docker Engine version 25.0.

For more information about:

* Deprecated and removed features, see [Deprecated Engine Features](https://docs.docker.com/engine/deprecated/).
* Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history/).

## [25.0.5](#2505)

*2024-03-19*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 25.0.5 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A25.0.5)
* [moby/moby, 25.0.5 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A25.0.5)

### [Security](#security)

This release contains a security fix for [CVE-2024-29018](https://github.com/moby/moby/security/advisories/GHSA-mq39-4gv4-mvpx), a potential data exfiltration from 'internal' networks via authoritative DNS servers.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* [CVE-2024-29018](https://github.com/moby/moby/security/advisories/GHSA-mq39-4gv4-mvpx): Do not forward requests to external DNS servers for a container that is only connected to an 'internal' network. Previously, requests were forwarded if the host's DNS server was running on a loopback address, like systemd's 127.0.0.53. [moby/moby#47589](https://github.com/moby/moby/pull/47589)

* plugin: fix mounting /etc/hosts when running in UserNS. [moby/moby#47588](https://github.com/moby/moby/pull/47588)

* rootless: fix `open /etc/docker/plugins: permission denied`. [moby/moby#47587](https://github.com/moby/moby/pull/47587)

* Fix multiple parallel `docker build` runs leaking disk space. [moby/moby#47527](https://github.com/moby/moby/pull/47527)

## [25.0.4](#2504)

*2024-03-07*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 25.0.4 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A25.0.4)
* [moby/moby, 25.0.4 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A25.0.4)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

* Restore DNS names for containers in the default "nat" network on Windows. [moby/moby#47490](https://github.com/moby/moby/pull/47490)
* Fix `docker start` failing when used with `--checkpoint` [moby/moby#47466](https://github.com/moby/moby/pull/47466)
* Don't enforce new validation rules for existing swarm networks [moby/moby#47482](https://github.com/moby/moby/pull/47482)
* Restore IP connectivity between the host and containers on an internal bridge network. [moby/moby#47481](https://github.com/moby/moby/pull/47481)
* Fix a regression introduced in v25.0 that prevented the classic builder from adding tar archive with `xattrs` created on a non-Linux OS [moby/moby#47483](https://github.com/moby/moby/pull/47483)
* containerd image store: Fix image pull not emitting `Pulling fs layer status` [moby/moby#47484](https://github.com/moby/moby/pull/47484)
* API: To preserve backwards compatibility, make read-only mounts non-recursive by default when using older clients (API versions < v1.44). [moby/moby#47393](https://github.com/moby/moby/pull/47393)
* API: `GET /images/{id}/json` omits the `Created` field (previously it was `0001-01-01T00:00:00Z`) if the `Created` field was missing from the image config. [moby/moby#47451](https://github.com/moby/moby/pull/47451)
* API: Populate a missing `Created` field in `GET /images/{id}/json` with `0001-01-01T00:00:00Z` for API versions <= 1.43. [moby/moby#47387](https://github.com/moby/moby/pull/47387)
* API: Fix a regression that caused API socket connection failures to report an API version negotiation failure instead. [moby/moby#47470](https://github.com/moby/moby/pull/47470)
* API: Preserve supplied endpoint configuration in a container-create API request, when a container-wide MAC address is specified, but `NetworkMode` name or id is not the same as the name or id used in `NetworkSettings.Networks`. [moby/moby#47510](https://github.com/moby/moby/pull/47510)

### [Packaging updates](#packaging-updates)

* Upgrade Go runtime to 1.21.8. [moby/moby#47503](https://github.com/moby/moby/pull/47503)
* Upgrade RootlessKit to v2.0.2. [moby/moby#47508](https://github.com/moby/moby/pull/47508)
* Upgrade Compose to v2.24.7. [docker/docker-ce-packaging#998](https://github.com/moby/moby/pull/998)
* Upgrade Buildx to v0.13.0. [docker/docker-ce-packaging#997](https://github.com/moby/moby/pull/997)

## [25.0.3](#2503)

*2024-02-06*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 25.0.3 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A25.0.3)
* [moby/moby, 25.0.3 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A25.0.3)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

* containerd image store: Fix a bug where `docker image history` would fail if a manifest wasn't found in the content store. [moby/moby#47348](https://github.com/moby/moby/pull/47348)

* Ensure that a generated MAC address is not restored when a container is restarted, but a configured MAC address is preserved. [moby/moby#47304](https://github.com/moby/moby/pull/47304)

  > Note
  >
  > * Containers created with Docker Engine version 25.0.0 may have duplicate MAC addresses. They must be re-created.
  > * Containers with user-defined MAC addresses created with Docker Engine versions 25.0.0 or 25.0.1 receive new MAC addresses when started using Docker Engine version 25.0.2. They must also be re-created.

* Fix `docker save <image>@<digest>` producing an OCI archive with index without manifests. [moby/moby#47294](https://github.com/moby/moby/pull/47294)

* Fix a bug preventing bridge networks from being created with an MTU higher than 1500 on RHEL and CentOS 7. [moby/moby#47308](https://github.com/moby/moby/issues/47308), [moby/moby#47311](https://github.com/moby/moby/pull/47311)

* Fix a bug where containers are unable to communicate over an `internal` network. [moby/moby#47303](https://github.com/moby/moby/pull/47303)

* Fix a bug where the value of the `ipv6` daemon option was ignored. [moby/moby#47310](https://github.com/moby/moby/pull/47310)

* Fix a bug where trying to install a pulling using a digest revision would cause a panic. [moby/moby#47323](https://github.com/moby/moby/pull/47323)

* Fix a potential race condition in the managed containerd supervisor. [moby/moby#47313](https://github.com/moby/moby/pull/47313)

* Fix an issue with the `journald` log driver preventing container logs from being followed correctly with systemd version 255. [moby/moby#47243](https://github.com/moby/moby/pull/47243)

* seccomp: Update the builtin seccomp profile to include syscalls added in kernel v5.17 - v6.7 to align the profile with the profile used by containerd. [moby/moby#47341](https://github.com/moby/moby/pull/47341)

* Windows: Fix cache not being used when building images based on Windows versions older than the host's version. [moby/moby#47307](https://github.com/moby/moby/pull/47307), [moby/moby#47337](https://github.com/moby/moby/pull/47337)

### [Packaging updates](#packaging-updates-1)

* Removed support for Ubuntu Lunar (23.04). [docker/ce-packaging#986](https://github.com/docker/docker-ce-packaging/pull/986)

## [25.0.2](#2502)

*2024-01-31*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 25.0.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A25.0.2)
* [moby/moby, 25.0.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A25.0.2)

### [Security](#security-1)

This release contains security fixes for the following CVEs affecting Docker Engine and its components.

| CVE                                                         | Component     | Fix version | Severity         |
| ----------------------------------------------------------- | ------------- | ----------- | ---------------- |
| [CVE-2024-21626](https://scout.docker.com/v/CVE-2024-21626) | runc          | 1.1.12      | High, CVSS 8.6   |
| [CVE-2024-23651](https://scout.docker.com/v/CVE-2024-23651) | BuildKit      | 1.12.5      | High, CVSS 8.7   |
| [CVE-2024-23652](https://scout.docker.com/v/CVE-2024-23652) | BuildKit      | 1.12.5      | High, CVSS 8.7   |
| [CVE-2024-23653](https://scout.docker.com/v/CVE-2024-23653) | BuildKit      | 1.12.5      | High, CVSS 7.7   |
| [CVE-2024-23650](https://scout.docker.com/v/CVE-2024-23650) | BuildKit      | 1.12.5      | Medium, CVSS 5.5 |
| [CVE-2024-24557](https://scout.docker.com/v/CVE-2024-24557) | Docker Engine | 25.0.2      | Medium, CVSS 6.9 |

The potential impacts of the above vulnerabilities include:

* Unauthorized access to the host filesystem
* Compromising the integrity of the build cache
* In the case of CVE-2024-21626, a scenario that could lead to full container escape

For more information about the security issues addressed in this release, refer to the [blog post](https://www.docker.com/blog/docker-security-advisory-multiple-vulnerabilities-in-runc-buildkit-and-moby/). For details about each vulnerability, see the relevant security advisory:

* [CVE-2024-21626](https://github.com/opencontainers/runc/security/advisories/GHSA-xr7r-f8xq-vfvv)
* [CVE-2024-23651](https://github.com/moby/buildkit/security/advisories/GHSA-m3r6-h7wv-7xxv)
* [CVE-2024-23652](https://github.com/moby/buildkit/security/advisories/GHSA-4v98-7qmw-rqr8)
* [CVE-2024-23653](https://github.com/moby/buildkit/security/advisories/GHSA-wr6v-9f75-vh2g)
* [CVE-2024-23650](https://github.com/moby/buildkit/security/advisories/GHSA-9p26-698r-w4hx)
* [CVE-2024-24557](https://github.com/moby/moby/security/advisories/GHSA-xw73-rw38-6vjc)

### [Packaging updates](#packaging-updates-2)

* Upgrade containerd to [v1.6.28](https://github.com/containerd/containerd/releases/tag/v1.6.28).
* Upgrade containerd to v1.7.13 (static binaries only). [moby/moby#47280](https://github.com/moby/moby/pull/47280)
* Upgrade runc to v1.1.12. [moby/moby#47269](https://github.com/moby/moby/pull/47269)
* Upgrade Compose to v2.24.5. [docker/docker-ce-packaging#985](https://github.com/docker/docker-ce-packaging/pull/985)
* Upgrade BuildKit to v0.12.5. [moby/moby#47273](https://github.com/moby/moby/pull/47273)

## [25.0.1](#2501)

*2024-01-23*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 25.0.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A25.0.1)
* [moby/moby, 25.0.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A25.0.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-3)

* API: Fix incorrect HTTP status code for containers with an invalid network configuration created before upgrading to Docker Engine v25.0. [moby/moby#47159](https://github.com/moby/moby/pull/47159)
* Ensure that a MAC address based on a container's IP address is re-generated when the container is stopped and restarted, in case the generated IP/MAC addresses have been reused. [moby/moby#47171](https://github.com/moby/moby/pull/47171)
* Fix `host-gateway-ip` not working during build when not set through configuration. [moby/moby#47192](https://github.com/moby/moby/pull/47192)
* Fix a bug that prevented a container from being renamed twice. [moby/moby#47196](https://github.com/moby/moby/pull/47196)
* Fix an issue causing containers to have their short ID added to their network alias when inspecting them. [moby/moby#47182](https://github.com/moby/moby/pull/47182)
* Fix an issue in detecting whether a remote build context is a Git repository. [moby/moby#47136](https://github.com/moby/moby/pull/47136)
* Fix an issue with layers order in OCI manifests. [moby/moby#47150](https://github.com/moby/moby/issues/47150)
* Fix volume mount error when passing an `addr` or `ip` mount option. [moby/moby#47185](https://github.com/moby/moby/pull/47185)
* Improve error message related to extended attributes that can't be set due to improperly namespaced attribute names. [moby/moby#47178](https://github.com/moby/moby/pull/47178)
* Swarm: Fixed `start_interval` not being passed to the container config. [moby/moby#47163](https://github.com/moby/moby/pull/47163)

### [Packaging updates](#packaging-updates-3)

* Upgrade Compose to `2.24.2`. [docker/docker-ce-packaging#981](https://github.com/docker/docker-ce-packaging/pull/981)

## [25.0.0](#2500)

*2024-01-19*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 25.0.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A25.0.0)
* [moby/moby, 25.0.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A25.0.0)

> Note
>
> In earlier versions of Docker Engine, recursive mounts (submounts) would always be mounted as writable, even when specifying a read-only mount. This behavior has changed in v25.0.0, for hosts running on kernel version 5.12 or later. Now, read-only bind mounts are **recursively read-only** by default.
>
> To get the same behavior as earlier releases, you can specify the `bind-recursive` option for the `--mount` flag.
>
> ```console
> $ docker run --mount type=bind,src=SRC,dst=DST,readonly,bind-recursive=writable IMAGE
> ```
>
> This option isn't supported with the `-v` or `--volume` flag. For more information, see [Recursive mounts](https://docs.docker.com/engine/storage/bind-mounts/#recursive-mounts).

### [New](#new)

* The daemon now uses systemd's default `LimitNOFILE`. In earlier versions of Docker Engine, this limit was set to `infinity`. This would cause issues with recent versions of systemd, where the hard limit was increased, causing programs that adjusted their behaviors based on ulimits to consume a high amount of memory. [moby/moby#45534](https://github.com/moby/moby/pull/45534)

  The new setting makes containers behave the same way as programs running on the host, but may cause programs that make incorrect assumptions based on the soft limit to misbehave. To get the previous behavior, you can set `LimitNOFILE=1048576`.

  This change currently only affects build containers created with `docker build` when using BuildKit with the `docker` driver. Starting with Docker Engine v29.0 (containerd v2.1.5), this limit applies to all containers, not only build containers.

  If you're experiencing issues with the higher ulimit in systemd v240 or later, consider adding a system `drop-in` or `override` file to configure the ulimit settings for your setup. The [Flatcar Container Linux documentation](https://www.flatcar.org/docs/latest/setup/systemd/drop-in-units/) has a great article covering this topic in detail.

* Add OpenTelemetry tracing. [moby/moby#45652](https://github.com/moby/moby/pull/45652), [moby/moby#45579](https://github.com/moby/moby/pull/45579)

* Add support for CDI devices under Linux. [moby/moby#45134](https://github.com/moby/moby/pull/45134), [docker/cli#4510](https://github.com/docker/cli/pull/4510), [moby/moby#46004](https://github.com/moby/moby/pull/46004)

* Add an additional interval to be used by healthchecks during the container start period. [moby/moby#40894](https://github.com/moby/moby/pull/40894), [docker/cli#4405](https://github.com/docker/cli/pull/4405), [moby/moby#45965](https://github.com/moby/moby/pull/45965)

* Add a `--log-format` flag to `dockerd` to control the logging format: text (default) or JSON. [moby/moby#45737](https://github.com/moby/moby/pull/45737)

* Add support for recursive read-only mounts. [moby/moby#45278](https://github.com/moby/moby/pull/45278), [moby/moby#46037](https://github.com/moby/moby/pull/46037)

* Add support for filtering images based on timestamp with `docker image ls --filter=until=<timestamp>`. [moby/moby#46577](https://github.com/moby/moby/pull/46577)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-4)

* API: Fix error message for invalid policies at `ValidateRestartPolicy`. [moby/moby#46352](https://github.com/moby/moby/pull/46352)
* API: Update `/info` endpoint to use singleflight. [moby/moby#45847](https://github.com/moby/moby/pull/45847)
* Add an error message for when specifying a Dockerfile filename with `-f`, and also using `stdin`. [docker/cli#4346](https://github.com/docker/cli/pull/4346)
* Add support for `mac-address` and `link-local-ip` fields in `--network` long format. [docker/cli#4419](https://github.com/docker/cli/pull/4419)
* Add support for specifying multiple `--network` flags with `docker container create` and `docker run`. [moby/moby#45906](https://github.com/moby/moby/pull/45906)
* Automatically enable IPv6 on a network when an IPv6 subnet is specified. [moby/moby#46455](https://github.com/moby/moby/pull/46455)
* Add support for overlay networks over IPv6 transport. [moby/moby#46790](https://github.com/moby/moby/pull/46790)
* Configuration reloading is now more robust: if there's an error during the configuration reload process, no configuration changes are applied. [moby/moby#43980](https://github.com/moby/moby/pull/43980)
* Live restore: Containers with auto remove (`docker run --rm`) are no longer forcibly removed on engine restart. [moby/moby#46857](https://github.com/moby/moby/pull/46857)
* Live restore: containers that are live-restored will now be given another health-check start period when the daemon restarts. [moby/moby#47051](https://github.com/moby/moby/pull/47051)
* Container health status is flushed to disk less frequently, reducing wear on flash storage. [moby/moby#47044](https://github.com/moby/moby/pull/47044)
* Ensure network names are unique. [moby/moby#46251](https://github.com/moby/moby/pull/46251)
* Ensure that overlay2 layer metadata is correct. [moby/moby#46471](https://github.com/moby/moby/pull/46471)
* Fix `Downloading` progress message on image pull. [moby/moby#46515](https://github.com/moby/moby/pull/46515)
* Fix `NetworkConnect` and `ContainerCreate` with improved data validation, and return all validation errors at once. [moby/moby#46183](https://github.com/moby/moby/pull/46183)
* Fix `com.docker.network.host_ipv4` option when IPv6 and ip6tables are enabled. [moby/moby#46446](https://github.com/moby/moby/pull/46446)
* Fix daemon's `cleanupContainer` if containerd is stopped. [moby/moby#46213](https://github.com/moby/moby/pull/46213)
* Fix returning incorrect HTTP status codes for libnetwork errors. [moby/moby#46146](https://github.com/moby/moby/pull/46146)
* Fix various issues with images/json API filters and image list. [moby/moby#46034](https://github.com/moby/moby/pull/46034)
* CIFS volumes now resolves FQDN correctly. [moby/moby#46863](https://github.com/moby/moby/pull/46863)
* Improve validation of the `userland-proxy-path` daemon configuration option. Validation now happens during daemon startup, instead of producing an error when starting a container with port-mapping. [moby/moby#47000](https://github.com/moby/moby/pull/47000)
* Set the MAC address of container's interface when network mode is a short network ID. [moby/moby#46406](https://github.com/moby/moby/pull/46406)
* Sort unconsumed build arguments before display in build output. [moby/moby#45917](https://github.com/moby/moby/pull/45917)
* The `docker image save` tarball output is now OCI compliant. [moby/moby#44598](https://github.com/moby/moby/pull/44598)
* The daemon no longer appends `ACCEPT` rules to the end of the `INPUT` iptables chain for encrypted overlay networks. Depending on firewall configuration, a rule may be needed to permit incoming encrypted overlay network traffic. [moby/moby#45280](https://github.com/moby/moby/pull/45280)
* Unpacking layers with extended attributes onto an incompatible filesystem will now fail instead of silently discarding extended attributes. [moby/moby#45464](https://github.com/moby/moby/pull/45464)
* Update daemon MTU option to BridgeConfig and display warning on Windows. [moby/moby#45887](https://github.com/moby/moby/pull/45887)
* Validate IPAM config when creating a network. Automatically fix networks created prior to this release where `--ip-range` is larger than `--subnet`. [moby/moby#45759](https://github.com/moby/moby/pull/45759)
* Containers connected only to internal networks will now have no default route set, making the `connect` syscall fail-fast. [moby/moby#46603](https://github.com/moby/moby/pull/46603)
* containerd image store: Add image events for `push`, `pull`, and `save`. [moby/moby#46405](https://github.com/moby/moby/pull/46405)
* containerd image store: Add support for pulling legacy schema1 images. [moby/moby#46513](https://github.com/moby/moby/pull/46513)
* containerd image store: Add support for pushing all tags. [moby/moby#46485](https://github.com/moby/moby/pull/46485)
* containerd image store: Add support for registry token. [moby/moby#46475](https://github.com/moby/moby/pull/46475)
* containerd image store: Add support for showing the number of containers that use an image. [moby/moby#46511](https://github.com/moby/moby/pull/46511)
* containerd image store: Fix a bug related to the `ONBUILD`, `MAINTAINER`, and `HEALTHCHECK` Dockerfile instructions. [moby/moby#46313](https://github.com/moby/moby/pull/46313)
* containerd image store: Fix `Pulling from` progress message. [moby/moby#46494](https://github.com/moby/moby/pull/46494)
* containerd image store: Add support for referencing images via the truncated ID with `sha256:` prefix. [moby/moby#46435](https://github.com/moby/moby/pull/46435)
* containerd image store: Fix `docker images` showing intermediate layers by default. [moby/moby#46423](https://github.com/moby/moby/pull/46423)
* containerd image store: Fix checking if the specified platform exists when getting an image. [moby/moby#46495](https://github.com/moby/moby/pull/46495)
* containerd image store: Fix errors when multiple `ADD` or `COPY` instructions were used with the classic builder. [moby/moby#46383](https://github.com/moby/moby/pull/46383)
* containerd image store: Fix stack overflow errors when importing an image. [moby/moby#46418](https://github.com/moby/moby/pull/46418)
* containerd image store: Improve `docker pull` progress output. [moby/moby#46412](https://github.com/moby/moby/pull/46412)
* containerd image store: Print the tag, digest, and size after pushing an image. [moby/moby#46384](https://github.com/moby/moby/pull/46384)
* containerd image store: Remove panic from `UpdateConfig`. [moby/moby#46433](https://github.com/moby/moby/pull/46433)
* containerd image store: Return an error when an image tag resembles a digest. [moby/moby#46492](https://github.com/moby/moby/pull/46492)
* containerd image store: `docker image ls` now shows the correct image creation time and date. [moby/moby#46719](https://github.com/moby/moby/pull/46719)
* containerd image store: Fix an issue handling user namespace settings. [moby/moby#46375](https://github.com/moby/moby/pull/46375)
* containerd image store: Add support for pulling all tags (`docker pull -a`). [moby/moby#46618](https://github.com/moby/moby/pull/46618)
* containerd image store: Use the domain name in the image reference as the default registry authentication domain. [moby/moby#46779](https://github.com/moby/moby/pull/46779)

### [Packaging updates](#packaging-updates-4)

* Upgrade API to v1.44. [moby/moby#45468](https://github.com/moby/moby/pull/45468)
* Upgrade Compose to `2.24.1`. [docker/docker-ce-packaging#980](https://github.com/docker/docker-ce-packaging/pull/980)
* Upgrade containerd to v1.7.12 (static binaries only). [moby/moby#47070](https://github.com/moby/moby/pull/47070)
* Upgrade Go runtime to [1.21.6](https://go.dev/doc/devel/release#go1.21.minor). [moby/moby#47053](https://github.com/moby/moby/pull/47053)
* Upgrade runc to v1.1.11. [moby/moby#47007](https://github.com/moby/moby/pull/47007)
* Upgrade BuildKit to v0.12.4. [moby/moby#46882](https://github.com/moby/moby/pull/46882)
* Upgrade Buildx to v0.12.1. [docker/docker-ce-packaging#979](https://github.com/docker/docker-ce-packaging/pull/979)

### [Removed](#removed)

* API: Remove VirtualSize field for the `GET /images/json` and `GET /images/{id}/json` endpoints. [moby/moby#45469](https://github.com/moby/moby/pull/45469)
* Remove deprecated `devicemapper` storage driver. [moby/moby#43637](https://github.com/moby/moby/pull/43637)
* Remove deprecated orchestrator options. [docker/cli#4366](https://github.com/docker/cli/pull/4366)
* Remove support for Debian Upstart init system. [moby/moby#45548](https://github.com/moby/moby/pull/45548), [moby/moby#45551](https://github.com/moby/moby/pull/45551)
* Remove the `--oom-score-adjust` daemon option. [moby/moby#45484](https://github.com/moby/moby/pull/45484)
* Remove warning for deprecated `~/.dockercfg` file. [docker/cli#4281](https://github.com/docker/cli/pull/4281)
* Remove `logentries` logging driver. [moby/moby#46925](https://github.com/moby/moby/pull/46925)

### [Deprecated](#deprecated)

* Deprecate API versions older than 1.24. [Deprecation notice](https://docs.docker.com/engine/deprecated/#deprecate-legacy-api-versions)
* Deprecate `IsAutomated` field and `is-automated` filter for `docker search`. [Deprecation notice](https://docs.docker.com/engine/deprecated/#isautomated-field-and-is-automated-filter-on-docker-search)
* API: Deprecate `Container` and `ContainerConfig` properties for `/images/{id}/json` (`docker image inspect`). [moby/moby#46939](https://github.com/moby/moby/pull/46939)

### [Known limitations](#known-limitations)

#### [Extended attributes for tar files](#extended-attributes-for-tar-files)

In this release, the code that handles `tar` archives was changed to be more strict and to produce an error when failing to write extended attributes (`xattr`). The `tar` implementation for macOS generates additional extended attributes by default when creating tar files. These attribute prefixes aren't valid Linux `xattr` namespace prefixes, which causes an error when Docker attempts to process these files. For example, if you try to use a tar file with an `ADD` Dockerfile instruction, you might see an error message similar to the following:

```text
failed to solve: lsetxattr /sftp_key.ppk: operation not supported
```

Error messages related to extended attribute validation were improved to include more context in [v25.0.1](#2501), but the limitation in Docker being unable to process the files remains. Tar files created with the macOS `tar` using default arguments will produce an error when the tar file is used with Docker.

As a workaround, if you need to use tar files with Docker generated on macOS, you can either:

* Use the `--no-xattr` flag for the macOS `tar` command to strip **all** the extended attributes. If you want to preserve extended attributes, this isn't a recommended option.

* Install and use `gnu-tar` to create the tarballs on macOS instead of the default `tar` implementation. To install `gnu-tar` using Homebrew:

  ```console
  $ brew install gnu-tar
  ```

  After installing, add the `gnu-tar` binary to your `PATH`, for example by updating your `.zshrc` file:

  ```console
  $ echo 'PATH="/opt/homebrew/opt/gnu-tar/libexec/gnubin:$PATH"' >> ~/.zshrc
  $ source ~/.zshrc
  ```

----
url: https://docs.docker.com/build/metadata/attestations/sbom/
----

# SBOM attestations

***

Table of contents

***

SBOM attestations help ensure [software supply chain transparency](https://docs.docker.com/guides/docker-scout/s3c/) by verifying the software artifacts an image contains and the artifacts used to create the image. Metadata included in an [SBOM](https://docs.docker.com/guides/docker-scout/sbom/) for describing software artifacts may include:

* Name of the artifact
* Version
* License type
* Authors
* Unique package identifier

Indexing the contents of an image during the build has benefits over scanning a final image. When scanning happens as part of the build, you can detect software you used to build the image, which may not show up in the final image.

Docker supports SBOM generation and attestation through an SLSA-compliant build process using BuildKit and attestations. The SBOMs generated by [BuildKit](https://docs.docker.com/build/buildkit/) follow the SPDX standard and attach to the final image as a JSON-encoded SPDX document, using the format defined by the [in-toto SPDX predicate](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md). On this page, you’ll learn how to create, manage, and verify SBOM attestations using Docker tooling.

## [Create SBOM attestations](#create-sbom-attestations)

To create an SBOM attestation, pass the `--attest type=sbom` option to the `docker buildx build` command:

```console
$ docker buildx build --tag <namespace>/<image>:<version> \
    --attest type=sbom --push .
```

Alternatively, you can use the shorthand `--sbom=true` option instead of `--attest type=sbom`.

For an example on how to add SBOM attestations with GitHub Actions, see [Add attestations with GitHub Actions](https://docs.docker.com/build/ci/github-actions/attestations/).

## [Verify SBOM attestations](#verify-sbom-attestations)

Always validate the generated SBOM for your image before you push your image to a registry.

To validate, you can build the image using the `local` exporter. Building with the `local` exporter saves the build result to your local filesystem instead of creating an image. Attestations are written to a JSON file in the root directory of your export.

```console
$ docker buildx build \
  --sbom=true \
  --output type=local,dest=out .
```

The SBOM file appears in the root directory of the output, named `sbom.spdx.json`:

```console
$ ls -1 ./out | grep sbom
sbom.spdx.json
```

## [Arguments](#arguments)

By default, BuildKit only scans the final stage of an image. The resulting SBOM doesn't include build-time dependencies installed in earlier stages, or that exist in the build context. This may cause you to overlook vulnerabilities in those dependencies, which could impact the security of your final build artifacts.

For instance, you might use [multi-stage builds](https://docs.docker.com/build/building/multi-stage/), with a `FROM scratch` stanza for your final stage to achieve a smaller image size.

```dockerfile
FROM alpine AS build
# build the software ...

FROM scratch
COPY --from=build /path/to/bin /bin
ENTRYPOINT [ "/bin" ]
```

Scanning the resulting image built using this Dockerfile example would not reveal build-time dependencies used in the `build` stage.

To include build-time dependencies from your Dockerfile, you can set the build arguments `BUILDKIT_SBOM_SCAN_CONTEXT` and `BUILDKIT_SBOM_SCAN_STAGE`. This expands the scanning scope to include the build context and additional stages.

You can set the arguments as global arguments (after declaring the Dockerfile syntax directive, before the first `FROM` command) or individually in each stage. If set globally, the value propagates to each stage in the Dockerfile.

The `BUILDKIT_SBOM_SCAN_CONTEXT` and `BUILDKIT_SBOM_SCAN_STAGE` build arguments are special values. You can't perform variable substitution using these arguments, and you can't set them using environment variables from within the Dockerfile. The only way to set these values is using explicit `ARG` command in the Dockerfile.

### [Scan build context](#scan-build-context)

To scan the build context, set the `BUILDKIT_SBOM_SCAN_CONTEXT` to `true`.

```dockerfile
# syntax=docker/dockerfile:1
ARG BUILDKIT_SBOM_SCAN_CONTEXT=true
FROM alpine AS build
# ...
```

You can use the `--build-arg` CLI option to override the value specified in the Dockerfile.

```console
$ docker buildx build --tag <image>:<version> \
    --attest type=sbom \
    --build-arg BUILDKIT_SBOM_SCAN_CONTEXT=false .
```

Note that passing the option as a CLI argument only, without having declared it using `ARG` in the Dockerfile, will have no effect. You must specify the `ARG` in the Dockerfile, whereby you can override the context scanning behavior using `--build-arg`.

### [Scan stages](#scan-stages)

To scan more than just the final stage, set the `BUILDKIT_SBOM_SCAN_STAGE` argument to true, either globally or in the specific stages that you want to scan. The following table demonstrates the different possible settings for this argument.

| Value                               | Description                                            |
| ----------------------------------- | ------------------------------------------------------ |
| `BUILDKIT_SBOM_SCAN_STAGE=true`     | Enables scanning for the current stage                 |
| `BUILDKIT_SBOM_SCAN_STAGE=false`    | Disables scanning for the current stage                |
| `BUILDKIT_SBOM_SCAN_STAGE=base,bin` | Enables scanning for the stages named `base` and `bin` |

Only stages that are built will be scanned. Stages that aren't dependencies of the target stage won't be built, or scanned.

The following Dockerfile example uses multi-stage builds to build a static website with [Hugo](https://gohugo.io/).

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine as hugo
ARG BUILDKIT_SBOM_SCAN_STAGE=true
WORKDIR /src
COPY <<config.yml ./
title: My Hugo website
config.yml
RUN apk add --upgrade hugo && hugo

FROM scratch
COPY --from=hugo /src/public /
```

Setting `ARG BUILDKIT_SBOM_SCAN_STAGE=true` in the `hugo` stage ensures that the final SBOM includes the information that Alpine Linux and Hugo were used to create the website.

Building this image with the `local` exporter creates two JSON files:

```console
$ docker buildx build \
  --sbom=true \
  --output type=local,dest=out .
$ ls -1 out | grep sbom
sbom-hugo.spdx.json
sbom.spdx.json
```

## [Inspecting SBOMs](#inspecting-sboms)

To explore created SBOMs exported through the `image` exporter, you can use [`imagetools inspect`](/reference/cli/docker/buildx/imagetools/inspect/).

Using the `--format` option, you can specify a template for the output. All SBOM-related data is available under the `.SBOM` attribute. For example, to get the raw contents of an SBOM in SPDX format:

```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
    --format "{{ json .SBOM.SPDX }}"
{
  "SPDXID": "SPDXRef-DOCUMENT",
  ...
}
```

> Tip
>
> If the image is multi-platform, you can check the SBOM for a platform-specific index using `--format '{{ json (index .SBOM "linux/amd64").SPDX }}'`.

You can also construct more complex expressions using the full functionality of Go templates. For example, you can list all the installed packages and their version identifiers:

```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
    --format "{{ range .SBOM.SPDX.packages }}{{ .name }}@{{ .versionInfo }}{{ println }}{{ end }}"
adduser@3.118ubuntu2
apt@2.0.9
base-files@11ubuntu5.6
base-passwd@3.5.47
...
```

## [SBOM generator](#sbom-generator)

BuildKit generates the SBOM using a scanner plugin. By default, it uses the [BuildKit Syft scanner](https://github.com/docker/buildkit-syft-scanner) plugin. This plugin is built on top of [Anchore's Syft](https://github.com/anchore/syft), an open source tool for generating an SBOM.

You can select a different plugin to use with the `generator` option, specifying an image that implements the [BuildKit SBOM scanner protocol](https://github.com/moby/buildkit/blob/master/docs/attestations/sbom-protocol.md).

```console
$ docker buildx build --attest type=sbom,generator=<image> .
```

> Tip
>
> The Docker Scout SBOM generator is available. See [Docker Scout SBOMs](https://docs.docker.com/scout/how-tos/view-create-sboms/).

## [SBOM attestation example](#sbom-attestation-example)

The following JSON example shows what an SBOM attestation might look like.

```json
{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://spdx.dev/Document",
  "subject": [
    {
      "name": "pkg:docker/<registry>/<image>@<tag/digest>?platform=<platform>",
      "digest": {
        "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862"
      }
    }
  ],
  "predicate": {
    "SPDXID": "SPDXRef-DOCUMENT",
    "creationInfo": {
      "created": "2022-12-16T15:27:25.517047753Z",
      "creators": ["Organization: Anchore, Inc", "Tool: syft-v0.60.3"],
      "licenseListVersion": "3.18"
    },
    "dataLicense": "CC0-1.0",
    "documentNamespace": "https://anchore.com/syft/dir/run/src/core/sbom-cba61a72-fa95-4b60-b63f-03169eac25ca",
    "name": "/run/src/core/sbom",
    "packages": [
      {
        "SPDXID": "SPDXRef-b074348b8f56ea64",
        "downloadLocation": "NOASSERTION",
        "externalRefs": [
          {
            "referenceCategory": "SECURITY",
            "referenceLocator": "cpe:2.3:a:org:repo:\\(devel\\):*:*:*:*:*:*:*",
            "referenceType": "cpe23Type"
          },
          {
            "referenceCategory": "PACKAGE_MANAGER",
            "referenceLocator": "pkg:golang/github.com/org/repo@(devel)",
            "referenceType": "purl"
          }
        ],
        "filesAnalyzed": false,
        "licenseConcluded": "NONE",
        "licenseDeclared": "NONE",
        "name": "github.com/org/repo",
        "sourceInfo": "acquired package info from go module information: bin/server",
        "versionInfo": "(devel)"
      },
      {
        "SPDXID": "SPDXRef-1b96f57f8fed62d8",
        "checksums": [
          {
            "algorithm": "SHA256",
            "checksumValue": "0c13f1f3c1636491f716c2027c301f21f9dbed7c4a2185461ba94e3e58443408"
          }
        ],
        "downloadLocation": "NOASSERTION",
        "externalRefs": [
          {
            "referenceCategory": "SECURITY",
            "referenceLocator": "cpe:2.3:a:go-chi:chi\\/v5:v5.0.0:*:*:*:*:*:*:*",
            "referenceType": "cpe23Type"
          },
          {
            "referenceCategory": "SECURITY",
            "referenceLocator": "cpe:2.3:a:go_chi:chi\\/v5:v5.0.0:*:*:*:*:*:*:*",
            "referenceType": "cpe23Type"
          },
          {
            "referenceCategory": "SECURITY",
            "referenceLocator": "cpe:2.3:a:go:chi\\/v5:v5.0.0:*:*:*:*:*:*:*",
            "referenceType": "cpe23Type"
          },
          {
            "referenceCategory": "PACKAGE_MANAGER",
            "referenceLocator": "pkg:golang/github.com/go-chi/chi/v5@v5.0.0",
            "referenceType": "purl"
          }
        ],
        "filesAnalyzed": false,
        "licenseConcluded": "NONE",
        "licenseDeclared": "NONE",
        "name": "github.com/go-chi/chi/v5",
        "sourceInfo": "acquired package info from go module information: bin/server",
        "versionInfo": "v5.0.0"
      }
    ],
    "relationships": [
      {
        "relatedSpdxElement": "SPDXRef-1b96f57f8fed62d8",
        "relationshipType": "CONTAINS",
        "spdxElementId": "SPDXRef-043f7360d3c66bc31ba45388f16423aa58693289126421b71d884145f8837fe1"
      },
      {
        "relatedSpdxElement": "SPDXRef-b074348b8f56ea64",
        "relationshipType": "CONTAINS",
        "spdxElementId": "SPDXRef-043f7360d3c66bc31ba45388f16423aa58693289126421b71d884145f8837fe1"
      }
    ],
    "spdxVersion": "SPDX-2.2"
  }
}
```

----
url: https://docs.docker.com/engine/swarm/swarm-tutorial/add-nodes/
----

# Add nodes to the swarm

***

***

Once you've [created a swarm](https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/) with a manager node, you're ready to add worker nodes.

1. Open a terminal and ssh into the machine where you want to run a worker node. This tutorial uses the name `worker1`.

2. Run the command produced by the `docker swarm init` output from the [Create a swarm](https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/) tutorial step to create a worker node joined to the existing swarm:

   ```console
   $ docker swarm join \
     --token  SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
     192.168.99.100:2377

   This node joined a swarm as a worker.
   ```

   If you don't have the command available, you can run the following command on a manager node to retrieve the join command for a worker:

   ```console
   $ docker swarm join-token worker

   To add a worker to this swarm, run the following command:

       docker swarm join \
       --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
       192.168.99.100:2377
   ```

3. Open a terminal and ssh into the machine where you want to run a second worker node. This tutorial uses the name `worker2`.

4. Run the command produced by the `docker swarm init` output from the [Create a swarm](https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/) tutorial step to create a second worker node joined to the existing swarm:

   ```console
   $ docker swarm join \
     --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
     192.168.99.100:2377

   This node joined a swarm as a worker.
   ```

5. Open a terminal and ssh into the machine where the manager node runs and run the `docker node ls` command to see the worker nodes:

   ```console
   $ docker node ls
   ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
   03g1y59jwfg7cf99w4lt0f662    worker2   Ready   Active
   9j68exjopxe7wfl6yuxml7a7j    worker1   Ready   Active
   dxn1zf6l61qsb1josjja83ngz *  manager1  Ready   Active        Leader
   ```

   The `MANAGER` column identifies the manager nodes in the swarm. The empty status in this column for `worker1` and `worker2` identifies them as worker nodes.

   Swarm management commands like `docker node ls` only work on manager nodes.

## [What's next?](#whats-next)

Now your swarm consists of a manager and two worker nodes. Next, you'll deploy a service.

[Deploy a service](https://docs.docker.com/engine/swarm/swarm-tutorial/deploy-service/)

----
url: https://docs.docker.com/reference/cli/docker/image/rm/
----

# docker image rm

***

| Description                                                               | Remove one or more images                    |
| ------------------------------------------------------------------------- | -------------------------------------------- |
| Usage                                                                     | `docker image rm [OPTIONS] IMAGE [IMAGE...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker image remove` `docker rmi`           |

## [Description](#description)

Removes (and un-tags) one or more images from the host node. If an image has multiple tags, using this command with the tag as a parameter only removes the tag. If the tag is the only one for the image, both the image and the tag are removed.

This does not remove images from a registry. You cannot remove an image of a running container unless you use the `-f` option. To see all images on a host use the [`docker image ls`](/reference/cli/docker/image/ls/) command.

## [Options](#options)

| Option                    | Default | Description                                                                                                 |
| ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `-f, --force`             |         | Force removal of the image                                                                                  |
| `--no-prune`              |         | Do not delete untagged parents                                                                              |
| [`--platform`](#platform) |         | API 1.50+ Remove only the given platform variant. Formatted as `os[/arch[/variant]]` (e.g., `linux/amd64`)  |

## [Examples](#examples)

You can remove an image using its short or long ID, its tag, or its digest. If an image has one or more tags referencing it, you must remove all of them before the image is removed. Digest references are removed automatically when an image is removed by tag.

```console
$ docker images

REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
test1                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
test2                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)

$ docker rmi fd484f19954f

Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force
2013/12/11 05:47:16 Error: failed to remove one or more images

$ docker rmi test1:latest

Untagged: test1:latest

$ docker rmi test2:latest

Untagged: test2:latest


$ docker images

REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)

$ docker rmi test:latest

Untagged: test:latest
Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
```

If you use the `-f` flag and specify the image's short or long ID, then this command untags and removes all images that match the specified ID.

```console
$ docker images

REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
test1                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
test2                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)

$ docker rmi -f fd484f19954f

Untagged: test1:latest
Untagged: test:latest
Untagged: test2:latest
Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
```

An image pulled by digest has no tag associated with it:

```console
$ docker images --digests

REPOSITORY                     TAG       DIGEST                                                                    IMAGE ID        CREATED         SIZE
localhost:5000/test/busybox    <none>    sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf   4986bf8c1536    9 weeks ago     2.43 MB
```

To remove an image using its digest:

```console
$ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125
Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2
Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b
```

### [Remove specific platforms (`--platform`)](#platform)

The `--platform` option allows you to specify which platform variants of the image to remove. By default, `docker image remove` removes all platform variants that are present. Use the `--platform` option to specify which platform variant of the image to remove.

Removing a specific platform removes the image from all images that reference the same content, and requires the `--force` option to be used. Omitting the `--force` option produces a warning, and the remove is canceled:

```console
$ docker image rm --platform=linux/amd64 alpine
Error response from daemon: Content will be removed from all images referencing this variant. Use —-force to force delete.
```

The platform option takes the `os[/arch[/variant]]` format; for example, `linux/amd64` or `linux/arm64/v8`. Architecture and variant are optional, and default to the daemon's native architecture if omitted.

You can pass multiple platforms either by passing the `--platform` flag multiple times, or by passing a comma-separated list of platforms to remove. The following uses of this option are equivalent;

```console
$ docker image rm --platform linux/amd64 --platform linux/ppc64le myimage
$ docker image rm --platform linux/amd64,linux/ppc64le myimage
```

The following example removes the `linux/amd64` and `linux/ppc64le` variants of an `alpine` image that contains multiple platform variants in the image cache:

```console
$ docker image ls --tree

IMAGE                   ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:latest           a8560b36e8b8       37.8MB         11.2MB    U
├─ linux/amd64          1c4eef651f65       12.1MB         3.64MB    U
├─ linux/arm/v6         903bfe2ae994           0B             0B
├─ linux/arm/v7         9c2d245b3c01           0B             0B
├─ linux/arm64/v8       757d680068d7       12.8MB         3.99MB
├─ linux/386            2436f2b3b7d2           0B             0B
├─ linux/ppc64le        9ed53fd3b831       12.8MB         3.58MB
├─ linux/riscv64        1de5eb4a9a67           0B             0B
└─ linux/s390x          fe0dcdd1f783           0B             0B

$ docker image --platform=linux/amd64,linux/ppc64le --force alpine
Deleted: sha256:1c4eef651f65e2f7daee7ee785882ac164b02b78fb74503052a26dc061c90474
Deleted: sha256:9ed53fd3b83120f78b33685d930ce9bf5aa481f6e2d165c42cbbddbeaa196f6f
```

After the command completes, the given variants of the `alpine` image are removed from the image cache:

```console
$ docker image ls --tree

IMAGE                   ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:latest           a8560b36e8b8       12.8MB         3.99MB
├─ linux/amd64          1c4eef651f65           0B             0B
├─ linux/arm/v6         903bfe2ae994           0B             0B
├─ linux/arm/v7         9c2d245b3c01           0B             0B
├─ linux/arm64/v8       757d680068d7       12.8MB         3.99MB
├─ linux/386            2436f2b3b7d2           0B             0B
├─ linux/ppc64le        9ed53fd3b831           0B             0B
├─ linux/riscv64        1de5eb4a9a67           0B             0B
└─ linux/s390x          fe0dcdd1f783           0B             0B
```

----
url: https://docs.docker.com/reference/api/extensions-sdk/Exec/
----

# Interface: Exec

***

Table of contents

***

## [Callable](#callable)

### [Exec](#exec)

▸ **Exec**(`cmd`, `args`, `options?`): `Promise`<[`ExecResult`](https://docs.docker.com/reference/api/extensions-sdk/ExecResult/)>

Executes a command.

**`Since`**

0.2.0

#### [Parameters](#parameters)

| Name       | Type                                                                               | Description                              |
| ---------- | ---------------------------------------------------------------------------------- | ---------------------------------------- |
| `cmd`      | `string`                                                                           | The command to execute.                  |
| `args`     | `string`\[]                                                                        | The arguments of the command to execute. |
| `options?` | [`ExecOptions`](https://docs.docker.com/reference/api/extensions-sdk/ExecOptions/) | The list of options.                     |

#### [Returns](#returns)

`Promise`<[`ExecResult`](https://docs.docker.com/reference/api/extensions-sdk/ExecResult/)>

A promise that will resolve once the command finishes.

### [Exec](#exec-1)

▸ **Exec**(`cmd`, `args`, `options`): [`ExecProcess`](https://docs.docker.com/reference/api/extensions-sdk/ExecProcess/)

Streams the result of a command if `stream` is specified in the `options` parameter.

Specify the `stream` if the output of your command is too long or if you need to stream things indefinitely (for example container logs).

**`Since`**

0.2.2

#### [Parameters](#parameters-1)

| Name      | Type                                                                                 | Description                              |
| --------- | ------------------------------------------------------------------------------------ | ---------------------------------------- |
| `cmd`     | `string`                                                                             | The command to execute.                  |
| `args`    | `string`\[]                                                                          | The arguments of the command to execute. |
| `options` | [`SpawnOptions`](https://docs.docker.com/reference/api/extensions-sdk/SpawnOptions/) | The list of options.                     |

#### [Returns](#returns-1)

[`ExecProcess`](https://docs.docker.com/reference/api/extensions-sdk/ExecProcess/)

The spawned process.

----
url: https://docs.docker.com/reference/api/extensions-sdk/ExecResultV0/
----

# Interface: ExecResultV0

***

Table of contents

***

## [Properties](#properties)

### [cmd](#cmd)

• `Optional` `Readonly` **cmd**: `string`

***

### [killed](#killed)

• `Optional` `Readonly` **killed**: `boolean`

***

### [signal](#signal)

• `Optional` `Readonly` **signal**: `string`

***

### [code](#code)

• `Optional` `Readonly` **code**: `number`

***

### [stdout](#stdout)

• `Readonly` **stdout**: `string`

***

### [stderr](#stderr)

• `Readonly` **stderr**: `string`

***

### [parseJsonLines](#parsejsonlines)

▸ **parseJsonLines**(): `any`\[]

Parse each output line as a JSON object.

#### [Returns](#returns-1)

`any`\[]

The list of lines where each line is a JSON object.

***

### [parseJsonObject](#parsejsonobject)

▸ **parseJsonObject**(): `any`

Parse a well-formed JSON output.

#### [Returns](#returns-2)

`any`

The JSON object.

----
url: https://docs.docker.com/accounts/manage-account/
----

# Manage a Docker account

***

Table of contents

***

You can centrally manage your Docker account using Docker Home, including administrative and security settings.

> Tip
>
> If your account is associated with an organization that enforces single sign-on (SSO), you may not have permissions to update your account settings. You must contact your administrator to update your settings.

## [Update account information](#update-account-information)

Account information is visible on your **Account settings** page. You can update the following account information:

* Full name
* Company
* Location
* Website
* Gravatar email

To add or update your avatar using Gravatar:

1. Create a [Gravatar account](https://gravatar.com/).
2. Create your avatar.
3. Add your Gravatar email to your Docker account settings.

It may take some time for your avatar to update in Docker.

## [Update email address](#update-email-address)

To update your email address:

1. Sign in to your [Docker account](https://app.docker.com/login).
2. Go to **Settings**, then choose **Email**.
3. Enter your new email address and confirm your identity with your password. Select **Verify email**.
4. Go to the new Docker email and copy the 6-digit verification code.
5. Paste the verification code to complete updating your email.

Your verification session expires after 15 minutes.

> Note
>
> Docker accounts only support one verified email address at a time, which is used for account notifications and security-related communications. You can't add multiple verified email addresses to your account.

## [Change your password](#change-your-password)

You can change your password by initiating a password reset via email. To change your password:

1. Sign in to your [Docker account](https://app.docker.com/login).
2. Select your avatar in the top-right corner and select **Account settings**.
3. Select **Password**, then **Reset password**.
4. Docker will send you a password reset email with instructions to reset your password.

## [Manage two-factor authentication](#manage-two-factor-authentication)

To update your two-factor authentication (2FA) settings:

1. Sign in to your [Docker account](https://app.docker.com/login).
2. Select your avatar in the top-right corner and select **Account settings**.
3. Select **2FA**.

For more information, see [Enable two-factor authentication](https://docs.docker.com/security/2fa/).

## [Manage personal access tokens](#manage-personal-access-tokens)

To manage personal access tokens:

1. Sign in to your [Docker account](https://app.docker.com/login).
2. Select your avatar in the top-right corner and select **Account settings**.
3. Select **Personal access tokens**.

For more information, see [Create and manage access tokens](https://docs.docker.com/security/access-tokens/).

## [Manage connected accounts](#manage-connected-accounts)

You can unlink connected Google or GitHub accounts:

1. Sign in to your [Docker account](https://app.docker.com/login).
2. Select your avatar in the top-right corner and select **Account settings**.
3. Select **Connected accounts**.
4. Select **Disconnect** on your connected account.

To fully unlink your Docker account, you must also unlink Docker from Google or GitHub. See Google or GitHub's documentation for more information:

* [Manage connections between your Google Account and third-parties](https://support.google.com/accounts/answer/13533235?hl=en)
* [Reviewing and revoking authorization of GitHub Apps](https://docs.github.com/en/apps/using-github-apps/reviewing-and-revoking-authorization-of-github-apps)

## [Convert your account](#convert-your-account)

For information on converting your account into an organization, see [Convert an account into an organization](https://docs.docker.com/admin/organization/setup/convert-account/).

## [Deactivate your account](#deactivate-your-account)

For information on deactivating your account, see [Deactivating a user account](https://docs.docker.com/accounts/deactivate-user-account/).

----
url: https://docs.docker.com/reference/cli/sbx/create/cursor/
----

# sbx create cursor

| Description | Create a sandbox for cursor                |
| ----------- | ------------------------------------------ |
| Usage       | `sbx create cursor PATH [PATH...] [flags]` |

## [Description](#description)

Create a sandbox with access to a host workspace for cursor.

The workspace path is required and will be mounted inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Global options](#global-options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `-D, --debug`    |         | Enable debug logging                                                                                                                                                                                                   |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Examples](#examples)

```console
# Create in the current directory
sbx create cursor .

# Create with a specific path
sbx create cursor /path/to/project

# Create with additional read-only workspaces
sbx create cursor . /path/to/docs:ro
```

----
url: https://docs.docker.com/subscription/desktop-license/
----

# Docker Desktop license agreement

***

Table of contents

***

Docker Desktop is licensed under the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement). When you download and install Docker Desktop, you're asked to agree to these terms.

The Docker Subscription Service Agreement states:

* Docker Desktop is free for:

  * Small businesses (fewer than 250 employees AND less than $10 million in annual revenue)
  * Personal use
  * Education
  * Non-commercial open source projects

* Docker Desktop requires a paid subscription for:

  * Professional use in larger organizations
  * Government entities
  * Commercial use beyond the free tier limits

* Paid subscriptions that include Docker Desktop:
  * Docker Pro, Team, and Business subscriptions

## [Understanding licensing terms](#understanding-licensing-terms)

For detailed information about how these terms may affect your organization, see:

* [Subscription updates blog post](https://www.docker.com/blog/updating-product-subscriptions/)
* [Docker subscription FAQs](https://www.docker.com/pricing/faq) to learn how this may affect companies using Docker Desktop.

> Note
>
> The licensing and distribution terms for Docker and Moby open-source projects, such as Docker Engine, aren't changing.

Docker Desktop is built using open-source software. For information about the licensing of open-source components in Docker Desktop, select the whale menu > **About Docker Desktop** > **Acknowledgements**.

## [Open source components](#open-source-components)

Docker Desktop distributes some components that are licensed under the GNU General Public License. [Download the source code for these components here](https://download.docker.com/opensource/License.tar.gz).

----
url: https://docs.docker.com/engine/logging/drivers/json-file/
----

# JSON File logging driver

***

Table of contents

***

By default, Docker captures the standard output (and standard error) of all your containers, and writes them in files using the JSON format. The JSON format annotates each line with its origin (`stdout` or `stderr`) and its timestamp. Each log file contains information about only one container.

```json
{
  "log": "Log line is here\n",
  "stream": "stdout",
  "time": "2019-01-01T11:11:11.111111111Z"
}
```

> Warning
>
> The `json-file` logging driver uses file-based storage. These files are designed to be exclusively accessed by the Docker daemon. Interacting with these files with external tools may interfere with Docker's logging system and result in unexpected behavior, and should be avoided.

## [Usage](#usage)

To use the `json-file` driver as the default logging driver, set the `log-driver` and `log-opts` keys to appropriate values in the `daemon.json` file. For more information about configuring Docker using `daemon.json`, see [daemon.json](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file).

> Note
>
> If you're using Docker Desktop, edit the daemon configuration through the Docker Desktop Dashboard. Open **Settings** and select **Docker Engine**. For details, see [Docker Engine settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine).

The following example sets the log driver to `json-file` and sets the `max-size` and `max-file` options to enable automatic log-rotation.

```json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
```

> Note
>
> `log-opts` configuration options in the `daemon.json` configuration file must be provided as strings. Boolean and numeric values (such as the value for `max-file` in the example above) must therefore be enclosed in quotes (`"`).

Restart Docker for the changes to take effect for newly created containers. Existing containers don't use the new logging configuration automatically.

You can set the logging driver for a specific container by using the `--log-driver` flag to `docker container create` or `docker run`:

```console
$ docker run \
      --log-driver json-file --log-opt max-size=10m \
      alpine echo hello world
```

### [Options](#options)

The `json-file` logging driver supports the following logging options:

| Option         | Description                                                                                                                                                                                                          | Example value                                      |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `max-size`     | The maximum size of the log before it is rolled. A positive integer plus a modifier representing the unit of measure (`k`, `m`, or `g`). Defaults to -1 (unlimited).                                                 | `--log-opt max-size=10m`                           |
| `max-file`     | The maximum number of log files that can be present. If rolling the logs creates excess files, the oldest file is removed. **Only effective when `max-size` is also set.** A positive integer. Defaults to 1.        | `--log-opt max-file=3`                             |
| `labels`       | Applies when starting the Docker daemon. A comma-separated list of logging-related labels this daemon accepts. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                | `--log-opt labels=production_status,geo`           |
| `labels-regex` | Similar to and compatible with `labels`. A regular expression to match logging-related labels. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                                | `--log-opt labels-regex=^(production_status\|geo)` |
| `env`          | Applies when starting the Docker daemon. A comma-separated list of logging-related environment variables this daemon accepts. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/). | `--log-opt env=os,customer`                        |
| `env-regex`    | Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).                    | `--log-opt env-regex=^(os\|customer)`              |
| `compress`     | Toggles compression for rotated logs. Defaults to `false` (no compression).                                                                                                                                          | `--log-opt compress=true`                          |

### [Examples](#examples)

This example starts an `alpine` container which can have a maximum of 3 log files no larger than 10 megabytes each.

```console
$ docker run -it --log-opt max-size=10m --log-opt max-file=3 alpine ash
```

----
url: https://docs.docker.com/guides/vuejs/
----

# Vue.js language-specific guide

Table of contents

***

This guide explains how to containerize Vue.js applications using Docker.

**Time to complete** 20 minutes

The Vue.js language-specific guide shows you how to containerize an Vue.js application using Docker, following best practices for creating efficient, production-ready containers.

[Vue.js](https://vuejs.org/) is a progressive and flexible framework for building modern, interactive web applications. However, as applications scale, managing dependencies, environments, and deployments can become complex. Docker simplifies these challenges by providing a consistent, isolated environment for both development and production.

> **Acknowledgment**
>
> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and highly skilled Front-end engineer, Kristiyan brings exceptional expertise in modern web development, Docker, and DevOps. His hands-on approach and clear, actionable guidance make this guide an essential resource for developers aiming to build, optimize, and secure Vue.js applications with Docker.

***

## [What will you learn?](#what-will-you-learn)

In this guide, you will learn how to:

* Containerize and run an Vue.js application using Docker.
* Set up a local development environment for Vue.js inside a container.
* Run tests for your Vue.js application within a Docker container.
* Configure a CI/CD pipeline using GitHub Actions for your containerized app.
* Deploy the containerized Vue.js application to a local Kubernetes cluster for testing and debugging.

You'll start by containerizing an existing Vue.js application and work your way up to production-level deployments.

***

## [Prerequisites](#prerequisites)

Before you begin, ensure you have a working knowledge of:

* Basic understanding of [TypeScript](https://www.typescriptlang.org/) and [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript).
* Familiarity with [Node.js](https://nodejs.org/en) and [npm](https://docs.npmjs.com/about-npm) for managing dependencies and running scripts.
* Familiarity with [Vue.js](https://vuejs.org/) fundamentals.
* Understanding of core Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide.

Once you've completed the Vue.js getting started modules, you’ll be fully prepared to containerize your own Vue.js application using the detailed examples and best practices outlined in this guide.

## [Modules](#modules)

1. [Containerize](https://docs.docker.com/guides/vuejs/containerize/)

   Learn how to containerize an Vue.js application with Docker by creating an optimized, production-ready image using best practices for performance, security, and scalability.

2. [Develop your app](https://docs.docker.com/guides/vuejs/develop/)

   Learn how to develop your Vue.js application locally using containers.

3. [Run your tests](https://docs.docker.com/guides/vuejs/run-tests/)

   Learn how to run your vue.js tests in a container.

4. [GitHub Actions CI](https://docs.docker.com/guides/vuejs/configure-github-actions/)

   Learn how to configure CI/CD using GitHub Actions for your Vue.js application.

5. [Test your deployment](https://docs.docker.com/guides/vuejs/deploy/)

   Learn how to deploy locally to test and debug your Kubernetes deployment

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/
----

# Docker MCP Catalog and Toolkit

***

Table of contents

***

Availability: Beta

[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open protocol that standardizes how AI applications access external tools and data sources. By connecting LLMs to local development tools, databases, APIs, and other resources, MCP extends their capabilities beyond their base training.

The challenge is that running MCP servers locally creates operational friction. Each server requires separate installation and configuration for every application you use. You run untrusted code directly on your machine, manage updates manually, and troubleshoot dependency conflicts yourself. Configure a GitHub server for Claude, then configure it again for Cursor, and so on. Each time you manage credentials, permissions, and environment setup.

## [Docker MCP features](#docker-mcp-features)

The [MCP Toolkit](/ai/mcp-catalog-and-toolkit/toolkit/) and [MCP Gateway](/ai/mcp-catalog-and-toolkit/mcp-gateway/) solve these challenges through centralized management. Instead of configuring each server for every AI application separately, you set things up once and connect all your clients to it. The workflow centers on three concepts: catalogs, profiles, and clients.

[Catalogs](/ai/mcp-catalog-and-toolkit/catalog/) are curated collections of MCP servers. The Docker MCP Catalog provides 300+ verified servers packaged as container images with versioning, provenance, and security updates. Organizations can create [custom catalogs](/ai/mcp-catalog-and-toolkit/catalog/#custom-catalogs) with approved servers for their teams.

[Profiles](/ai/mcp-catalog-and-toolkit/profiles/) organize servers into named collections for different projects. Your "web-dev" profile might use GitHub and Playwright; your "backend" profile, database tools. Profiles support both containerized servers from catalogs and remote MCP servers. Configure a profile once, then share it across clients or with your team.

Clients are the AI applications that connect to your profiles. Claude Code, Cursor, Zed, and others connect through the MCP Gateway, which routes requests to the right server and handles authentication and lifecycle management.

## [Learn more](#learn-more)

### [Get started with MCP Toolkit](/ai/mcp-catalog-and-toolkit/get-started/)

[Learn how to quickly install and use the MCP Toolkit to set up servers and clients.](/ai/mcp-catalog-and-toolkit/get-started/)

### [MCP Catalog](/ai/mcp-catalog-and-toolkit/catalog/)

[Browse Docker's curated collection of verified MCP servers](/ai/mcp-catalog-and-toolkit/catalog/)

### [MCP Profiles](/ai/mcp-catalog-and-toolkit/profiles/)

[Organize servers into profiles for different projects and share configurations](/ai/mcp-catalog-and-toolkit/profiles/)

### [MCP Toolkit](/ai/mcp-catalog-and-toolkit/toolkit/)

[Use Docker Desktop's UI to discover, configure, and manage MCP servers](/ai/mcp-catalog-and-toolkit/toolkit/)

### [MCP Gateway](/ai/mcp-catalog-and-toolkit/mcp-gateway/)

[Use the CLI and Gateway to run MCP servers with custom configurations](/ai/mcp-catalog-and-toolkit/mcp-gateway/)

### [Dynamic MCP](/ai/mcp-catalog-and-toolkit/dynamic-mcp/)

[Discover and add MCP servers on-demand using natural language](/ai/mcp-catalog-and-toolkit/dynamic-mcp/)

### [Docker Hub MCP server](/ai/mcp-catalog-and-toolkit/hub-mcp/)

[Use the Docker Hub MCP server to search images and manage repositories](/ai/mcp-catalog-and-toolkit/hub-mcp/)

### [Security FAQs](/ai/mcp-catalog-and-toolkit/faqs/)

[Common questions about MCP security, credentials, and server verification](/ai/mcp-catalog-and-toolkit/faqs/)

### [E2B sandboxes](/ai/mcp-catalog-and-toolkit/e2b-sandboxes/)

[Cloud sandboxes for AI agents with built-in MCP Catalog access](/ai/mcp-catalog-and-toolkit/e2b-sandboxes/)

----
url: https://docs.docker.com/guides/nextjs/develop/
----

# Use containers for Next.js development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize Next.js application](https://docs.docker.com/guides/nextjs/containerize/).

***

## [Overview](#overview)

In this section, you'll learn how to set up both production and development environments for your containerized Next.js application using Docker Compose. This setup allows you to run a production build using the standalone server and to develop efficiently inside containers using Next.js's built-in hot reloading with Compose Watch.

You'll learn how to:

* Configure separate containers for production and development
* Enable automatic file syncing using Compose Watch in development
* Debug and live-preview your changes in real-time without manual rebuilds

***

## [Automatically update services (development mode)](#automatically-update-services-development-mode)

Use Compose Watch to automatically sync source file changes into your containerized development environment. This automatically syncs file changes without needing to restart or rebuild containers manually.

## [Step 1: Create a development Dockerfile](#step-1-create-a-development-dockerfile)

Create a file named `Dockerfile.dev` in your project root with the following content (matching the [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample)):

```dockerfile
# ============================================
# Development Dockerfile for Next.js
# ============================================
ARG NODE_VERSION=24.14.0-slim

FROM node:${NODE_VERSION} AS dev

WORKDIR /app

COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./

RUN --mount=type=cache,target=/root/.npm \
    --mount=type=cache,target=/usr/local/share/.cache/yarn \
    --mount=type=cache,target=/root/.local/share/pnpm/store \
  if [ -f package-lock.json ]; then \
    npm ci --no-audit --no-fund; \
  elif [ -f yarn.lock ]; then \
    corepack enable yarn && yarn install --frozen-lockfile --production=false; \
  elif [ -f pnpm-lock.yaml ]; then \
    corepack enable pnpm && pnpm install --frozen-lockfile; \
  else \
    echo "No lockfile found." && exit 1; \
  fi

COPY . .

ENV WATCHPACK_POLLING=true
ENV HOSTNAME="0.0.0.0"

RUN chown -R node:node /app
USER node

EXPOSE 3000

CMD ["sh", "-c", "if [ -f package-lock.json ]; then npm run dev; elif [ -f yarn.lock ]; then yarn dev; elif [ -f pnpm-lock.yaml ]; then pnpm dev; else npm run dev; fi"]
```

This file sets up a development environment for your Next.js app with hot module replacement and supports npm, yarn, and pnpm.

### [Step 2: Update your `compose.yaml` file](#step-2-update-your-composeyaml-file)

Open your `compose.yaml` file and define two services: one for production (`nextjs-prod-standalone`) and one for development (`nextjs-dev`). This matches the [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample) structure.

Here's an example configuration for a Next.js application:

```yaml
services:
  nextjs-prod-standalone:
    build:
      context: .
      dockerfile: Dockerfile
    image: nextjs-sample:prod
    container_name: nextjs-sample-prod
    ports:
      - "3000:3000"

  nextjs-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    image: nextjs-sample:dev
    container_name: nextjs-sample-dev
    ports:
      - "3000:3000"
    environment:
      - WATCHPACK_POLLING=true
    develop:
      watch:
        - action: sync
          path: .
          target: /app
          ignore:
            - node_modules/
            - .next/
        - action: rebuild
          path: package.json
```

* The `nextjs-prod-standalone` service builds and runs your production Next.js app using the standalone output.
* The `nextjs-dev` service runs your Next.js development server with hot module replacement.
* `watch` triggers file sync with Compose Watch.
* `WATCHPACK_POLLING=true` ensures file changes are detected properly inside Docker.
* The `rebuild` action for `package.json` ensures dependencies are reinstalled when the file changes.

> Note
>
> For more details, see the official guide: [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

### [Step 3: Configure Next.js for Docker development](#step-3-configure-nextjs-for-docker-development)

Next.js works well inside Docker containers out of the box, but there are a few configurations that can improve the development experience.

The `next.config.ts` file you created during containerization already includes the `output: "standalone"` option for production. For development, Next.js automatically uses its built-in development server with hot reloading enabled.

> Note
>
> The Next.js development server automatically:
>
> * Enables Hot Module Replacement (HMR) for instant updates
> * Watches for file changes and recompiles automatically
> * Provides detailed error messages in the browser
>
> The `WATCHPACK_POLLING=true` environment variable in the compose file ensures file watching works correctly inside Docker containers.

After completing the previous steps, your project directory should now contain the following files:

```text
├── docker-nextjs-sample/
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ ├── .dockerignore
│ ├── compose.yaml
│ └── next.config.ts
```

### [Step 4: Start Compose Watch](#step-4-start-compose-watch)

Run the following command from your project root to start your container in watch mode:

```console
$ docker compose watch nextjs-dev
```

### [Step 5: Test Compose Watch with Next.js](#step-5-test-compose-watch-with-nextjs)

To verify that Compose Watch is working correctly:

1. Open the `app/page.tsx` file in your text editor (or `src/app/page.tsx` if your project uses a `src` directory).

2. Locate the main content area and find a text element to modify.

3. Make a visible change, for example, update a heading:

   ```tsx
   <h1>Hello from Docker Compose Watch!</h1>
   ```

4. Save the file.

5. Open your browser at <http://localhost:3000>.

You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected.

***

## [Summary](#summary)

In this section, you set up a complete development and production workflow for your Next.js application using Docker and Docker Compose.

Here's what you achieved:

* Created a `Dockerfile.dev` to streamline local development with hot reloading
* Defined separate `nextjs-dev` and `nextjs-prod-standalone` services in your `compose.yaml` file
* Enabled real-time file syncing using Compose Watch for a smoother development experience
* Verified that live updates work seamlessly by modifying and previewing a component

With this setup, you can build, run, and iterate on your Next.js app entirely within containers across environments.

***

In the next section, you'll learn how to run unit tests for your Next.js application inside Docker containers. This ensures consistent testing across all environments and removes dependencies on local machine setup.

[Run Next.js tests in a container »](https://docs.docker.com/guides/nextjs/run-tests/)

----
url: https://docs.docker.com/desktop/use-desktop/logs/
----

# Explore the Logs view in Docker Desktop

***

Table of contents

***

Requires: Docker Desktop [4.65](https://docs.docker.com/desktop/release-notes/#4650) or later

The **Logs** view provides a unified, real-time log stream from all containers and recent builds in Docker Desktop. Unlike the logs accessible from the [**Containers** view](https://docs.docker.com/desktop/use-desktop/container/), the **Logs** view lets you monitor and search log output (up to a maximum of 100 000 entries) across your entire environment from a single interface.

## [Log entries](#log-entries)

Each log entry in the table view shows:

| Column        | Description                                                                    |
| ------------- | ------------------------------------------------------------------------------ |
| **Timestamp** | The date and time the log line was emitted, for example `2026-02-26 11:18:53`. |
| **Object**    | The container or build that produced the log line.                             |
| **Message**   | The full log message, including any status codes such as `[ OK ]`.             |

Selecting the expand arrow to the right of a row reveals the full message for that entry.

## [Search and filter logs](#search-and-filter-logs)

Use the **Search** field at the top of the Logs view to find specific entries. The search bar supports:

* Plain-text terms for exact match searches
* Regular expressions (for example, `/error|warn/`)

You can save your search terms for easy-access later.

To refine the log stream further, select the **Filter** icon in the toolbar to open the container filter panel. From here you can:

* Check individual containers to show only their output
* Check Compose stacks to show or hide entire groups
* Use **Select all** or **Clear all** to quickly toggle every container at once

## [Display settings](#display-settings)

Select the **Display settings** icon in the toolbar to toggle the following:

* **View build logs**: Include or exclude build-related log output in the stream
* **Wrap lines**
* **Show timestamps**

## [Feedback](#feedback)

Select **Give feedback** at the top of the view to share suggestions or report issues.

----
url: https://docs.docker.com/guides/testcontainers-java-quarkus/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

```console
$ ./mvnw test
```

Or with Gradle:

```console
$ ./gradlew test
```

You should see the PostgreSQL Docker container start and all tests pass. After the tests finish, the container stops and is removed automatically.

## [Run the application locally](#run-the-application-locally)

Quarkus Dev Services automatically provisions unconfigured services in development mode. Start the Quarkus application in dev mode:

```console
$ ./mvnw compile quarkus:dev
```

Or with Gradle:

```console
$ ./gradlew quarkusDev
```

Dev Services starts a PostgreSQL container automatically. If you're running a PostgreSQL database on your system and want to use that instead, configure the datasource properties in `src/main/resources/application.properties`:

```properties
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/postgres
quarkus.datasource.username=postgres
quarkus.datasource.password=postgres
```

When these properties are set explicitly, Dev Services doesn't provision the database container and instead connects to the configured database.

## [Summary](#summary)

Quarkus Dev Services improves the developer experience by automatically provisioning the required services using Testcontainers during development and testing. This guide covered:

* Building a REST API using JAX-RS with Hibernate ORM with Panache
* Testing API endpoints using REST Assured with Dev Services handling database provisioning
* Using `QuarkusTestResourceLifecycleManager` for services not supported by Dev Services
* Running the application locally with Dev Services

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Quarkus Dev Services overview](https://quarkus.io/guides/dev-services)
* [Quarkus testing guide](https://quarkus.io/guides/getting-started-testing)
* [Testcontainers Postgres module](https://java.testcontainers.org/modules/databases/postgres/)

----
url: https://docs.docker.com/reference/cli/docker/desktop/update/
----

# docker desktop update

***

| Description | Manage Docker Desktop updates     |
| ----------- | --------------------------------- |
| Usage       | `docker desktop update [OPTIONS]` |

## [Options](#options)

| Option             | Default | Description                             |
| ------------------ | ------- | --------------------------------------- |
| `-k, --check-only` |         | Check for updates without applying them |
| `-q, --quiet`      |         | Quietly check and apply updates         |

----
url: https://docs.docker.com/reference/cli/docker/swarm/unlock-key/
----

# docker swarm unlock-key

***

| Description | Manage the unlock key               |
| ----------- | ----------------------------------- |
| Usage       | `docker swarm unlock-key [OPTIONS]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

An unlock key is a secret key needed to unlock a manager after its Docker daemon restarts. These keys are only used when the autolock feature is enabled for the swarm.

You can view or rotate the unlock key using `swarm unlock-key`. To view the key, run the `docker swarm unlock-key` command without any arguments:

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                  | Default | Description        |
| ----------------------- | ------- | ------------------ |
| [`-q, --quiet`](#quiet) |         | Only display token |
| [`--rotate`](#rotate)   |         | Rotate unlock key  |

## [Examples](#examples)

```console
$ docker swarm unlock-key

To unlock a swarm manager after it restarts, run the `docker swarm unlock`
command and provide the following key:

    SWMKEY-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233...

Remember to store this key in a password manager, since without it you
will not be able to restart the manager.
```

Use the `--rotate` flag to rotate the unlock key to a new, randomly-generated key:

```console
$ docker swarm unlock-key --rotate

Successfully rotated manager unlock key.

To unlock a swarm manager after it restarts, run the `docker swarm unlock`
command and provide the following key:

    SWMKEY-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233...

Remember to store this key in a password manager, since without it you
will not be able to restart the manager.
```

The `-q` (or `--quiet`) flag only prints the key:

```console
$ docker swarm unlock-key -q

SWMKEY-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233...
```

### [`--rotate`](#rotate)

This flag rotates the unlock key, replacing it with a new randomly-generated key. The old unlock key will no longer be accepted.

### [`--quiet`](#quiet)

Only print the unlock key, without instructions.

----
url: https://docs.docker.com/engine/swarm/swarm-tutorial/
----

# Getting started with Swarm mode

***

Table of contents

***

This tutorial introduces you to the features of Docker Engine Swarm mode. You may want to familiarize yourself with the [key concepts](https://docs.docker.com/engine/swarm/key-concepts/) before you begin.

The tutorial guides you through:

* Initializing a cluster of Docker Engines in swarm mode
* Adding nodes to the swarm
* Deploying application services to the swarm
* Managing the swarm once you have everything running

This tutorial uses Docker Engine CLI commands entered on the command line of a terminal window.

If you are brand new to Docker, see [About Docker Engine](https://docs.docker.com/engine/).

## [Set up](#set-up)

To run this tutorial, you need:

* [Three Linux hosts which can communicate over a network, with Docker installed](#three-networked-host-machines)
* [The IP address of the manager machine](#the-ip-address-of-the-manager-machine)
* [Open ports between the hosts](#open-protocols-and-ports-between-the-hosts)

### [Three networked host machines](#three-networked-host-machines)

This tutorial requires three Linux hosts which have Docker installed and can communicate over a network. These can be physical machines, virtual machines, Amazon EC2 instances, or hosted in some other way. Check out [Deploy to Swarm](https://docs.docker.com/guides/swarm-deploy/#prerequisites) for one possible set-up for the hosts.

One of these machines is a manager (called `manager1`) and two of them are workers (`worker1` and `worker2`).

> Note
>
> You can follow many of the tutorial steps to test single-node swarm as well, in which case you need only one host. Multi-node commands do not work, but you can initialize a swarm, create services, and scale them.

#### [Install Docker Engine on Linux machines](#install-docker-engine-on-linux-machines)

If you are using Linux based physical computers or cloud-provided computers as hosts, simply follow the [Linux install instructions](https://docs.docker.com/engine/install/) for your platform. Spin up the three machines, and you are ready. You can test both single-node and multi-node swarm scenarios on Linux machines.

### [The IP address of the manager machine](#the-ip-address-of-the-manager-machine)

The IP address must be assigned to a network interface available to the host operating system. All nodes in the swarm need to connect to the manager at the IP address.

Because other nodes contact the manager node on its IP address, you should use a fixed IP address.

You can run `ifconfig` on Linux or macOS to see a list of the available network interfaces.

The tutorial uses `manager1` : `192.168.99.100`.

### [Open protocols and ports between the hosts](#open-protocols-and-ports-between-the-hosts)

The following ports must be available. On some systems, these ports are open by default.

* Port `2377` TCP for communication with and between manager nodes
* Port `7946` TCP/UDP for overlay network node discovery
* Port `4789` UDP (configurable) for overlay network traffic

If you plan on creating an overlay network with encryption (`--opt encrypted`), you also need to ensure IP protocol 50 (IPSec ESP) traffic is allowed.

Port `4789` is the default value for the Swarm data path port, also known as the VXLAN port. It is important to prevent any untrusted traffic from reaching this port, as VXLAN does not provide authentication. This port should only be opened to a trusted network, and never at a perimeter firewall.

If the network which Swarm traffic traverses is not fully trusted, it is strongly suggested that encrypted overlay networks be used. If encrypted overlay networks are in exclusive use, some additional hardening is suggested:

* [Customize the default ingress network](https://docs.docker.com/engine/swarm/networking/) to use encryption
* Only accept encrypted packets on the Data Path Port:

```bash
# Example iptables rule (order and other tools may require customization)
iptables -I INPUT -m udp --dport 4789 -m policy --dir in --pol none -j DROP
```

## [Next steps](#next-steps)

Next, you'll create a swarm.

[Create a swarm](https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/)

----
url: https://docs.docker.com/reference/api/dvp/changelog/
----

# Docker Verified Publisher API changelog

***

Table of contents

***

Here you can learn about the latest changes, new features, bug fixes, and known issues for Docker Verified Publisher API.

***

## [2025-06-27](#2025-06-27)

### [New](#new)

* Create changelog

----
url: https://docs.docker.com/dhi/migration/migrate-from-ubuntu/
----

# Migrate from Ubuntu

***

Table of contents

***

Docker Hardened Images (DHI) come in [Alpine-based and Debian-based variants](https://docs.docker.com/dhi/explore/available/). When migrating from an Ubuntu-based image, you should migrate to the Debian-based DHI variant, as both Ubuntu and Debian share the same package management system (APT) and underlying architecture, making migration straightforward.

This guide helps you migrate from an existing Ubuntu-based image to DHI.

## [Key differences](#key-differences)

When migrating from Ubuntu-based images to DHI Debian, be aware of these key differences:

| Item                 | Ubuntu-based images                                             | Docker Hardened Images                                                                                                                                                                                                                               |
| -------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Package management   | Varies by image. Some include APT package manager, others don't | Package managers generally only available in images with a `dev` tag. Runtime images don't contain package managers. Use multi-stage builds and copy necessary artifacts from the build stage to the runtime stage.                                  |
| Non-root user        | Varies by image. Some run as root, others as non-root           | Runtime variants run as the non-root user by default. Ensure that necessary files and directories are accessible to the non-root user.                                                                                                               |
| Multi-stage build    | Recommended                                                     | Recommended. Use images with a `dev` or `sdk` tags for build stages and non-dev images for runtime.                                                                                                                                                  |
| Ports                | Can bind to privileged ports (under 1024) when running as root  | Run as a non-root user by default. Applications can't bind to privileged ports (under 1024) when running in Kubernetes or in Docker Engine versions older than 20.10. Configure your application to listen on port 1025 and up inside the container. |
| Entry point          | Varies by image                                                 | May have different entry points than Ubuntu-based images. Inspect entry points and update your Dockerfile if necessary.                                                                                                                              |
| Shell                | Varies by image. Some include a shell, others don't             | Runtime images don't contain a shell. Use `dev` images in build stages to run shell commands and then copy artifacts to the runtime stage.                                                                                                           |
| Package repositories | Uses Ubuntu package repositories                                | Uses Debian package repositories. Most packages have similar names, but some may differ.                                                                                                                                                             |

## [Migration steps](#migration-steps)

### [Step 1: Update the base image in your Dockerfile](#step-1-update-the-base-image-in-your-dockerfile)

Update the base image in your application's Dockerfile to a hardened image. This is typically going to be an image tagged as `dev` or `sdk` because it has the tools needed to install packages and dependencies.

The following example diff snippet from a Dockerfile shows the old Ubuntu-based image replaced by the new DHI Debian image.

> Note
>
> You must authenticate to `dhi.io` before you can pull Docker Hardened Images. Use your Docker ID credentials (the same username and password you use for Docker Hub). If you don't have a Docker account, [create one](https://docs.docker.com/accounts/create-account/) for free.
>
> Run `docker login dhi.io` to authenticate.

```diff
- ## Original Ubuntu-based image
- FROM ubuntu/go:1.22-24.04

+ ## Updated to use hardened Debian-based image
+ FROM dhi.io/golang:1-debian13-dev
```

To find the right tag, explore the available tags in the [DHI Catalog](https://hub.docker.com/hardened-images/catalog/).

### [Step 2: Update package installation commands](#step-2-update-package-installation-commands)

Since Ubuntu and Debian both use APT for package management, most package installation commands remain similar. However, you need to ensure that package installations only occur in `dev` or `sdk` images, as runtime images don't contain package managers.

```diff
- ## Ubuntu: Installing packages
- FROM ubuntu/go:1.22-24.04
- RUN apt-get update && apt-get install -y \
-     git \
-     && rm -rf /var/lib/apt/lists/*

+ ## DHI: Use a language-specific dev image with package manager
+ FROM dhi.io/golang:1-debian13-dev
+ RUN apt-get update && apt-get install -y \
+     git \
+     && rm -rf /var/lib/apt/lists/*
```

Most Ubuntu packages are available in Debian with the same names. If you encounter missing packages, you can search for equivalent packages using the [Debian package search](https://packages.debian.org/) website.

### [Step 3: Update the runtime image in your Dockerfile](#step-3-update-the-runtime-image-in-your-dockerfile)

> Note
>
> Multi-stage builds are recommended to keep your final image minimal and secure. Single-stage builds are supported, but they include the full `dev` image and therefore result in a larger image with a broader attack surface.

To ensure that your final image is as minimal as possible, you should use a [multi-stage build](https://docs.docker.com/build/building/multi-stage/). All stages in your Dockerfile should use a hardened image. While intermediary stages will typically use images tagged as `dev` or `sdk`, your final runtime stage should use a runtime image.

Utilize the build stage to install dependencies and prepare your application, then copy the resulting artifacts to the final runtime stage. This ensures that your final image is minimal and secure.

The following example shows a multi-stage Dockerfile migrating from Ubuntu to DHI Debian:

```dockerfile
# Build stage
FROM dhi.io/golang:1-debian13-dev AS builder
WORKDIR /app

# Install system dependencies (only available in dev images)
RUN apt-get update && apt-get install -y \
    git \
    && rm -rf /var/lib/apt/lists/*

# Copy application files
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" -o main .

# Runtime stage
FROM dhi.io/golang:1-debian13
WORKDIR /app

# Copy compiled binary from builder
COPY --from=builder /app/main /app/main

# Run the application
ENTRYPOINT ["/app/main"]
```

## [Language-specific examples](#language-specific-examples)

See the examples section for language-specific migration examples:

* [Go](https://docs.docker.com/dhi/migration/examples/go/)
* [Python](https://docs.docker.com/dhi/migration/examples/python/)
* [Node.js](https://docs.docker.com/dhi/migration/examples/node/)

----
url: https://docs.docker.com/guides/testcontainers-java-micronaut-kafka/write-tests/
----

# Write tests with Testcontainers

***

Table of contents

***

To test the Kafka listener, you need a running Kafka broker and a MySQL database, plus a started Micronaut application context. Testcontainers spins up both services in Docker containers and the `TestPropertyProvider` interface connects them to Micronaut.

## [Create a Kafka client for testing](#create-a-kafka-client-for-testing)

First, create a `@KafkaClient` interface to publish events in the test:

```java
package com.testcontainers.demo;

import io.micronaut.configuration.kafka.annotation.KafkaClient;
import io.micronaut.configuration.kafka.annotation.KafkaKey;
import io.micronaut.configuration.kafka.annotation.Topic;

@KafkaClient
public interface ProductPriceChangesClient {

    @Topic("product-price-changes")
    void send(@KafkaKey String productCode, ProductPriceChangedEvent event);
}
```

Key details:

* The `@KafkaClient` annotation designates this interface as a Kafka producer.
* The `@Topic` annotation specifies the target topic.
* The `@KafkaKey` annotation marks the parameter used as the Kafka message key. If no such parameter exists, Micronaut sends the record with a null key.

## [Write the test](#write-the-test)

Create `ProductPriceChangedEventHandlerTest.java`:

```java
package com.testcontainers.demo;

import static java.util.concurrent.TimeUnit.SECONDS;
import static org.assertj.core.api.Assertions.assertThat;
import static org.awaitility.Awaitility.await;

import io.micronaut.context.annotation.Property;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import io.micronaut.test.support.TestPropertyProvider;
import java.math.BigDecimal;
import java.time.Duration;
import java.util.Collections;
import java.util.Map;
import java.util.Optional;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.TestInstance;
import org.testcontainers.kafka.ConfluentKafkaContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@MicronautTest(transactional = false)
@Property(name = "datasources.default.driver-class-name", value = "org.testcontainers.jdbc.ContainerDatabaseDriver")
@Property(name = "datasources.default.url", value = "jdbc:tc:mysql:8.0.32:///db")
@Testcontainers(disabledWithoutDocker = true)
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class ProductPriceChangedEventHandlerTest implements TestPropertyProvider {

    @Container
    static final ConfluentKafkaContainer kafka = new ConfluentKafkaContainer("confluentinc/cp-kafka:7.8.0");

    @Override
    public @NonNull Map<String, String> getProperties() {
        if (!kafka.isRunning()) {
            kafka.start();
        }
        return Collections.singletonMap("kafka.bootstrap.servers", kafka.getBootstrapServers());
    }

    @Test
    void shouldHandleProductPriceChangedEvent(
            ProductPriceChangesClient productPriceChangesClient, ProductRepository productRepository) {
        Product product = new Product(null, "P100", "Product One", BigDecimal.TEN);
        Long id = productRepository.save(product).getId();

        ProductPriceChangedEvent event = new ProductPriceChangedEvent("P100", new BigDecimal("14.50"));

        productPriceChangesClient.send(event.productCode(), event);

        await().pollInterval(Duration.ofSeconds(3)).atMost(10, SECONDS).untilAsserted(() -> {
            Optional<Product> optionalProduct = productRepository.findByCode("P100");
            assertThat(optionalProduct).isPresent();
            assertThat(optionalProduct.get().getCode()).isEqualTo("P100");
            assertThat(optionalProduct.get().getPrice()).isEqualTo(new BigDecimal("14.50"));
        });

        productRepository.deleteById(id);
    }
}
```

Here's what the test does:

* `@MicronautTest` initializes the Micronaut application context and the embedded server. Setting `transactional` to `false` prevents each test method from running inside a rolled-back transaction, which is necessary because the Kafka listener processes messages in a separate thread.
* The `@Property` annotations override the datasource driver and URL to use the Testcontainers special JDBC URL (`jdbc:tc:mysql:8.0.32:///db`). This spins up a MySQL container and configures it as the datasource automatically.
* `@Testcontainers` and `@Container` manage the Kafka container lifecycle. The `TestPropertyProvider` interface registers the Kafka bootstrap servers with Micronaut so that the producer and consumer connect to the test container.
* `@TestInstance(TestInstance.Lifecycle.PER_CLASS)` creates a single test instance for all test methods, which is required when implementing `TestPropertyProvider`.
* The test creates a `Product` record in the database, then sends a `ProductPriceChangedEvent` to the `product-price-changes` topic using the `ProductPriceChangesClient`.
* Because Kafka message processing is asynchronous, the test uses [Awaitility](http://www.awaitility.org/) to poll every 3 seconds (up to a maximum of 10 seconds) until the product price in the database matches the expected value.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-micronaut-kafka/run-tests/)

----
url: https://docs.docker.com/reference/cli/docker/compose/wait/
----

# docker compose wait

***

| Description | Block until containers of all (or specified) services stop. |
| ----------- | ----------------------------------------------------------- |
| Usage       | `docker compose wait SERVICE [SERVICE...] [OPTIONS]`        |

## [Description](#description)

Block until containers of all (or specified) services stop.

## [Options](#options)

| Option           | Default | Description                                  |
| ---------------- | ------- | -------------------------------------------- |
| `--down-project` |         | Drops project when the first container stops |

----
url: https://docs.docker.com/guides/cpp/security/
----

# Supply-chain security for C++ Docker images

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

* You have a Docker Desktop installed, with containerd enabled for pulling and storing images (it's a checkbox in **Settings** > **General**). Otherwise, if you use Docker Engine:

  * You have the [Docker Scout CLI plugin](https://docs.docker.com/scout/install/) installed. To install it on Docker Engine, use the following command:

    ```bash
    $ curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s --
    ```

  * You have [containerd enabled](https://docs.docker.com/engine/storage/containerd/) for Docker Engine.

## [Overview](#overview)

This section walks you through extracting Software Bill of Materials (SBOMs) from a C++ Docker image using Docker Scout. SBOMs provide a detailed list of all the components in a software package, including their versions and licenses. You can use SBOMs to track the provenance of your software and ensure that it complies with your organization's security and licensing policies.

## [Generate an SBOM](#generate-an-sbom)

Here we will use the Docker image that we built in the [Create a multi-stage build for your C++ application](/guides/language/cpp/multistage/) guide. If you haven't already built the image, follow the steps in that guide to build the image. The image is named `hello`. To generate an SBOM for the `hello` image, run the following command:

```bash
$ docker scout sbom --format list hello
```

The command will say "No packages discovered". This is because the final image is a scratch image and doesn't have any packages.

## [Generate an SBOM attestation](#generate-an-sbom-attestation)

The SBOM can be generated during the build process and "attached" to the image. This is called an SBOM attestation. To generate an SBOM attestation for the `hello` image, first let's change the Dockerfile:

```Dockerfile
ARG BUILDKIT_SBOM_SCAN_STAGE=true

FROM ubuntu:latest AS build

RUN apt-get update && apt-get install -y build-essential

WORKDIR /app

COPY hello.cpp .

RUN g++ -o hello hello.cpp -static

# --------------------
FROM scratch

COPY --from=build /app/hello /hello

CMD ["/hello"]
```

The first line `ARG BUILDKIT_SBOM_SCAN_STAGE=true` enables SBOM scanning in the build stage. Now, build the image with the following command:

```bash
$ docker buildx build --sbom=true -t hello:sbom .
```

This command will build the image and generate an SBOM attestation. You can verify that the SBOM is attached to the image by running the following command:

```bash
$ docker scout sbom --format list hello:sbom
```

Docker Scout reads the SBOM attestation when one is available, so this command reports packages from the build-stage metadata instead of indexing only the final scratch image filesystem.

## [Summary](#summary)

In this section, you learned how to generate SBOM attestation for a C++ Docker image during the build process. Image scanners that inspect only the final filesystem may not identify packages in scratch images. Use SBOM attestations to preserve package metadata from the build.

----
url: https://docs.docker.com/engine/release-notes/18.02/
----

# Docker Engine 18.02 release notes

***

Table of contents

***

## [18.02.0-ce](#18020-ce)

2018-02-07

### [Builder](#builder)

* Gitutils: fix checking out submodules [moby/moby#35737](https://github.com/moby/moby/pull/35737)

### [Client](#client)

* Attach: Ensure attach exit code matches container's [docker/cli#696](https://github.com/docker/cli/pull/696)

- Added support for tmpfs-mode in compose file [docker/cli#808](https://github.com/docker/cli/pull/808)
- Adds a new compose file version 3.6 [docker/cli#808](https://github.com/docker/cli/pull/808)

* Fix issue of filter in `docker ps` where `health=starting` returns nothing [moby/moby#35940](https://github.com/moby/moby/pull/35940)

- Improve presentation of published port ranges [docker/cli#581](https://github.com/docker/cli/pull/581)

* Bump Go to 1.9.3 [docker/cli#827](https://github.com/docker/cli/pull/827)

- Fix broken Kubernetes stack flags [docker/cli#831](https://github.com/docker/cli/pull/831)

* Annotate "stack" commands to be "swarm" and "kubernetes" [docker/cli#804](https://github.com/docker/cli/pull/804)

### [Experimental](#experimental)

* Add manifest command [docker/cli#138](https://github.com/docker/cli/pull/138)

- LCOW remotefs - return error in Read() implementation [moby/moby#36051](https://github.com/moby/moby/pull/36051)

* LCOW: Coalesce daemon stores, allow dual LCOW and WCOW mode [moby/moby#34859](https://github.com/moby/moby/pull/34859)

- LCOW: Fix OpenFile parameters [moby/moby#36043](https://github.com/moby/moby/pull/36043)

* LCOW: Raise minimum requirement to Windows RS3 RTM build (16299) [moby/moby#36065](https://github.com/moby/moby/pull/36065)

### [Logging](#logging)

* Improve daemon config reload; log active configuration [moby/moby#36019](https://github.com/moby/moby/pull/36019)

- Fixed error detection using IsErrNotFound and IsErrNotImplemented for the ContainerLogs method [moby/moby#36000](https://github.com/moby/moby/pull/36000)

* Add journald tag as SYSLOG\_IDENTIFIER [moby/moby#35570](https://github.com/moby/moby/pull/35570)

- Splunk: limit the reader size on error responses [moby/moby#35509](https://github.com/moby/moby/pull/35509)

### [Networking](#networking)

* Disable service on release network results in zero-downtime deployments with rolling upgrades [moby/moby#35960](https://github.com/moby/moby/pull/35960)

- Fix services failing to start if multiple networks with the same name exist in different spaces [moby/moby#30897](https://github.com/moby/moby/pull/30897)
- Fix duplicate networks being added with `docker service update --network-add` [docker/cli#780](https://github.com/docker/cli/pull/780)
- Fixing ingress network when upgrading from 17.09 to 17.12. [moby/moby#36003](https://github.com/moby/moby/pull/36003)
- Fix ndots configuration [docker/libnetwork#1995](https://github.com/docker/libnetwork/pull/1995)
- Fix IPV6 networking being deconfigured if live-restore is enabled [docker/libnetwork#2043](https://github.com/docker/libnetwork/pull/2043)

* Add support for MX type DNS queries in the embedded DNS server [docker/libnetwork#2041](https://github.com/docker/libnetwork/pull/2041)

### [Packaging](#packaging)

* Added packaging for Fedora 26, Fedora 27, and Centos 7 on aarch64 [docker/docker-ce-packaging#71](https://github.com/docker/docker-ce-packaging/pull/71)

- Removed support for Ubuntu Zesty [docker/docker-ce-packaging#73](https://github.com/docker/docker-ce-packaging/pull/73)
- Removed support for Fedora 25 [docker/docker-ce-packaging#72](https://github.com/docker/docker-ce-packaging/pull/72)

### [Runtime](#runtime)

* Fixes unexpected Docker Daemon shutdown based on pipe error [moby/moby#35968](https://github.com/moby/moby/pull/35968)
* Fix some occurrences of hcsshim::ImportLayer failed in Win32: The system cannot find the path specified [moby/moby#35924](https://github.com/moby/moby/pull/35924)

- Windows: increase the maximum layer size during build to 127GB [moby/moby#35925](https://github.com/moby/moby/pull/35925)

* Fix Devicemapper: Error running DeleteDevice dm\_task\_run failed [moby/moby#35919](https://github.com/moby/moby/pull/35919)

- Introduce « exec\_die » event [moby/moby#35744](https://github.com/moby/moby/pull/35744)

* Update API to version 1.36 [moby/moby#35744](https://github.com/moby/moby/pull/35744)

- Fix `docker update` not updating cpu quota, and cpu-period of a running container [moby/moby#36030](https://github.com/moby/moby/pull/36030)

* Make container shm parent unbindable [moby/moby#35830](https://github.com/moby/moby/pull/35830)

- Make image (layer) downloads faster by using pigz [moby/moby#35697](https://github.com/moby/moby/pull/35697)
- Protect the daemon from volume plugins that are slow or deadlocked [moby/moby#35441](https://github.com/moby/moby/pull/35441)

* Fix `DOCKER_RAMDISK` environment variable not being honoured [moby/moby#35957](https://github.com/moby/moby/pull/35957)

- Bump containerd to 1.0.1 (9b55aab90508bd389d7654c4baf173a981477d55) [moby/moby#35986](https://github.com/moby/moby/pull/35986)
- Update runc to fix hang during start and exec [moby/moby#36097](https://github.com/moby/moby/pull/36097)

* Fix "--node-generic-resource" singular/plural [moby/moby#36125](https://github.com/moby/moby/pull/36125)

----
url: https://docs.docker.com/engine/release-notes/24.0/
----

# Docker Engine 24.0 release notes

***

Table of contents

***

This page describes the latest changes, additions, known issues, and fixes for Docker Engine version 24.0.

For more information about:

* Deprecated and removed features, see [Deprecated Engine Features](https://docs.docker.com/engine/deprecated/).
* Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history/).

## [24.0.9](#2409)

*2024-01-31*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 24.0.9 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A24.0.9)
* [moby/moby, 24.0.9 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A24.0.9)

## [Security](#security)

This release contains security fixes for the following CVEs affecting Docker Engine and its components.

| CVE                                                         | Component     | Fix version | Severity         |
| ----------------------------------------------------------- | ------------- | ----------- | ---------------- |
| [CVE-2024-21626](https://scout.docker.com/v/CVE-2024-21626) | runc          | 1.1.12      | High, CVSS 8.6   |
| [CVE-2024-24557](https://scout.docker.com/v/CVE-2024-24557) | Docker Engine | 24.0.9      | Medium, CVSS 6.9 |

> Important
>
> Note that this release of Docker Engine doesn't include fixes for the following known vulnerabilities in BuildKit:
>
> * [CVE-2024-23651](https://scout.docker.com/v/CVE-2024-23651)
> * [CVE-2024-23652](https://scout.docker.com/v/CVE-2024-23652)
> * [CVE-2024-23653](https://scout.docker.com/v/CVE-2024-23653)
> * [CVE-2024-23650](https://scout.docker.com/v/CVE-2024-23650)
>
> To address these vulnerabilities, upgrade to [Docker Engine v25.0.2](https://docs.docker.com/engine/release-notes/25.0/#2502).

For more information about the security issues addressed in this release, and the unaddressed vulnerabilities in BuildKit, refer to the [blog post](https://www.docker.com/blog/docker-security-advisory-multiple-vulnerabilities-in-runc-buildkit-and-moby/).

For details about each vulnerability, see the relevant security advisory:

* [CVE-2024-21626](https://github.com/opencontainers/runc/security/advisories/GHSA-xr7r-f8xq-vfvv)
* [CVE-2024-24557](https://github.com/moby/moby/security/advisories/GHSA-xw73-rw38-6vjc)

### [Packaging updates](#packaging-updates)

* Upgrade runc to [v1.1.12](https://github.com/opencontainers/runc/releases/tag/v1.1.12). [moby/moby#47269](https://github.com/moby/moby/pull/47269)
* Upgrade containerd to [v1.7.13](https://github.com/containerd/containerd/releases/tag/v1.7.13) (static binaries only). [moby/moby#47280](https://github.com/moby/moby/pull/47280)

## [24.0.8](#2408)

*2024-01-25*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 24.0.8 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A24.0.8)
* [moby/moby, 24.0.8 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A24.0.8)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* Live restore: Containers with auto remove (`docker run --rm`) are no longer forcibly removed on engine restart. [moby/moby#46857](https://github.com/moby/moby/pull/46869)

### [Packaging updates](#packaging-updates-1)

* Upgrade Go to `go1.20.13`. [moby/moby#47054](https://github.com/moby/moby/pull/47054), [docker/cli#4826](https://github.com/docker/cli/pull/4826), [docker/docker-ce-packaging#975](https://github.com/docker/docker-ce-packaging/pull/975)
* Upgrade containerd (static binaries only) to [v1.7.12](https://github.com/containerd/containerd/releases/tag/v1.7.12) [moby/moby#47096](https://github.com/moby/moby/pull/47096)
* Upgrade runc to v1.1.11. [moby/moby#47010](https://github.com/moby/moby/pull/47010)

## [24.0.7](#2407)

*2023-10-27*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 24.0.7 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A24.0.7)
* [moby/moby, 24.0.7 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A24.0.7)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

* Write overlay2 layer metadata atomically. [moby/moby#46703](https://github.com/moby/moby/pull/46703)
* Fix "Rootful-in-Rootless" Docker-in-Docker on systemd version 250 and later. [moby/moby#46626](https://github.com/moby/moby/pull/46626)
* Fix `dockerd-rootless-setuptools.sh` when username contains a backslash. [moby/moby#46407](https://github.com/moby/moby/pull/46407)
* Fix a bug that would prevent network sandboxes to be fully deleted when stopping containers with no network attachments and when `dockerd --bridge=none` is used. [moby/moby#46702](https://github.com/moby/moby/pull/46702)
* Fix a bug where cancelling an API request could interrupt container restart. [moby/moby#46697](https://github.com/moby/moby/pull/46697)
* Fix an issue where containers would fail to start when providing `--ip-range` with a range larger than the subnet. [docker/for-mac#6870](https://github.com/docker/for-mac/issues/6870)
* Fix data corruption with zstd output. [moby/moby#46709](https://github.com/moby/moby/pull/46709)
* Fix the conditions under which the container's MAC address is applied. [moby/moby#46478](https://github.com/moby/moby/pull/46478)
* Improve the performance of the stats collector. [moby/moby#46448](https://github.com/moby/moby/pull/46448)
* Fix an issue with source policy rules ending up in the wrong order. [moby/moby#46441](https://github.com/moby/moby/pull/46441)

### [Packaging updates](#packaging-updates-2)

* Add support for Fedora 39 and Ubuntu 23.10. [docker/docker-ce-packaging#940](https://github.com/docker/docker-ce-packaging/pull/940), [docker/docker-ce-packaging#955](https://github.com/docker/docker-ce-packaging/pull/955)
* Fix `docker.socket` not getting disabled when uninstalling the `docker-ce` RPM package. [docker/docker-ce-packaging#852](https://github.com/docker/docker-ce-packaging/pull/852)
* Upgrade Go to `go1.20.10`. [docker/docker-ce-packaging#951](https://github.com/docker/docker-ce-packaging/pull/951)
* Upgrade containerd to `v1.7.6` (static binaries only). [moby/moby#46103](https://github.com/moby/moby/pull/46103)
* Upgrade the `containerd.io` package to [`v1.6.24`](https://github.com/containerd/containerd/releases/tag/v1.6.24).

### [Security](#security-1)

* Deny containers access to `/sys/devices/virtual/powercap` by default. This change hardens against [CVE-2020-8694](https://scout.docker.com/v/CVE-2020-8694), [CVE-2020-8695](https://scout.docker.com/v/CVE-2020-8695), and [CVE-2020-12912](https://scout.docker.com/v/CVE-2020-12912), and an attack known as [the PLATYPUS attack](https://platypusattack.com/).

  For more details, see [advisory](https://github.com/moby/moby/security/advisories/GHSA-jq35-85cj-fj4p), [commit](https://github.com/moby/moby/commit/c9ccbfad11a60e703e91b6cca4f48927828c7e35).

## [24.0.6](#2406)

*2023-09-05*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 24.0.6 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A24.0.6)
* [moby/moby, 24.0.6 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A24.0.6)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

* containerd storage backend: Fix `docker ps` failing when a container image is no longer present in the content store. [moby/moby#46095](https://github.com/moby/moby/pull/46095)
* containerd storage backend: Fix `docker ps -s -a` and `docker container prune` failing when a container image config is no longer present in the content store. [moby/moby#46097](https://github.com/moby/moby/pull/46097)
* containerd storage backend: Fix `docker inspect` failing when a container image config is no longer (or was never) present in the content store. [moby/moby#46244](https://github.com/moby/moby/pull/46244)
* containerd storage backend: Fix diff and export with the `overlayfs` snapshotter by using reference-counted rootfs mounts. [moby/moby#46266](https://github.com/moby/moby/pull/46266)
* containerd storage backend: Fix a misleading error message when the image platforms available locally do not match the desired platform. [moby/moby#46300](https://github.com/moby/moby/pull/46300)
* containerd storage backend: Fix the `FROM scratch` Dockerfile instruction with the classic builder. [moby/moby#46302](https://github.com/moby/moby/pull/46302)
* containerd storage backend: Fix `mismatched image rootfs and manifest layers` errors with the classic builder. [moby/moby#46310](https://github.com/moby/moby/pull/46310)
* Warn when pulling Docker Image Format v1, and Docker Image manifest version 2, schema 1 images from all registries. [moby/moby#46290](https://github.com/moby/moby/pull/46290)
* Fix live-restore of volumes with custom volume options. [moby/moby#46366](https://github.com/moby/moby/pull/46366)
* Fix incorrectly dropping capabilities bits when running a container as a non-root user (note: this change was already effectively present due to a regression). [moby/moby#46221](https://github.com/moby/moby/pull/46221)
* Fix network isolation iptables rules preventing IPv6 Neighbor Solicitation packets from being exchanged between containers. [moby/moby#46214](https://github.com/moby/moby/pull/46214)
* Fix `dockerd.exe --register-service` not working when the binary is in the current directory on Windows. [moby/moby#46215](https://github.com/moby/moby/pull/46215)
* Add a hint suggesting the use of a PAT to `docker login` against Docker Hub. [docker/cli#4500](https://github.com/docker/cli/pull/4500)
* Improve shell startup time for users of Bash completion for the CLI. [docker/cli#4517](https://github.com/docker/cli/pull/4517)
* Improve the speed of some commands by skipping `GET /_ping` when possible. [docker/cli#4508](https://github.com/docker/cli/pull/4508)
* Fix credential scopes when using a PAT to `docker manifest inspect` an image on Docker Hub. [docker/cli#4512](https://github.com/docker/cli/pull/4512)
* Fix `docker events` not supporting `--format=json`. [docker/cli#4544](https://github.com/docker/cli/pull/4544)

### [Packaging updates](#packaging-updates-3)

* Upgrade Go to `go1.20.7`. [moby/moby#46140](https://github.com/moby/moby/pull/46140), [docker/cli#4476](https://github.com/docker/cli/pull/4476), [docker/docker-ce-packaging#932](https://github.com/docker/docker-ce-packaging/pull/932)
* Upgrade containerd to `v1.7.3` (static binaries only). [moby/moby#46103](https://github.com/moby/moby/pull/46103)
* Upgrade Compose to `v2.21.0`. [docker/docker-ce-packaging#936](https://github.com/docker/docker-ce-packaging/pull/936)

## [24.0.5](#2405)

*2023-07-24*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 24.0.5 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A24.0.5)
* [moby/moby, 24.0.5 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A24.0.5)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-3)

* The Go client now avoids using UNIX socket paths in the HTTP `Host:` header, in order to be compatible with changes introduced in `go1.20.6`. [moby/moby#45962](https://github.com/moby/moby/pull/45962), [moby/moby#45990](https://github.com/moby/moby/pull/45990)
* containerd storage backend: Fix `Variant` not being included in `docker image inspect` and `GET /images/{name}/json`. [moby/moby#46025](https://github.com/moby/moby/pull/46025)
* containerd storage backend: Prevent potential garbage collection of content during image export. [moby/moby#46021](https://github.com/moby/moby/pull/46021)
* containerd storage backend: Prevent duplicate digest entries in `RepoDigests`. [moby/moby#46014](https://github.com/moby/moby/pull/46014)
* containerd storage backend: Fix operations taking place against the incorrect tag when working with an image referenced by tag and digest. [moby/moby#46013](https://github.com/moby/moby/pull/46013)
* containerd storage backend: Fix a panic caused by `EXPOSE` when building containers with the legacy builder. [moby/moby#45921](https://github.com/moby/moby/pull/45921)
* Fix a regression causing unintuitive errors to be returned when attempting to create an `overlay` network on a non-Swarm node. [moby/moby#45974](https://github.com/moby/moby/pull/45974)
* Properly report errors parsing volume specifications from the command line. [docker/cli#4423](https://github.com/docker/cli/pull/4423)
* Fix a panic caused when `auths: null` is found in the CLI config file. [docker/cli#4450](https://github.com/docker/cli/pull/4450)

### [Packaging updates](#packaging-updates-4)

* Use init scripts as provided by in moby/moby `contrib/init`. [docker/docker-ce-packaging#914](https://github.com/docker/docker-ce-packaging/pull/914), [docker/docker-ce-packaging#926](https://github.com/docker/docker-ce-packaging/pull/926)
* Drop Upstart from `contrib/init`. [moby/moby#46044](https://github.com/moby/moby/pull/46044)
* Upgrade Go to `go1.20.6`. [docker/cli#4428](https://github.com/docker/cli/pull/4428), [moby/moby#45970](https://github.com/moby/moby/pull/45970), [docker/docker-ce-packaging#921](https://github.com/docker/docker-ce-packaging/pull/921)
* Upgrade Compose to `v2.20.2`. [docker/docker-ce-packaging#924](https://github.com/docker/docker-ce-packaging/pull/924)
* Upgrade buildx to `v0.11.2`. [docker/docker-ce-packaging#922](https://github.com/docker/docker-ce-packaging/pull/922)

## [24.0.4](#2404)

*2023-07-07*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 24.0.4 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A24.0.4)
* [moby/moby, 24.0.4 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A24.0.4)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-4)

* Fix a regression introduced during 24.0.3 that causes a panic during live-restore of containers with bind mounts. [moby/moby#45903](https://github.com/moby/moby/pull/45903)

## [24.0.3](#2403)

*2023-07-06*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 24.0.3 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A24.0.3)
* [moby/moby, 24.0.3 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A24.0.3)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-5)

* containerd image store: Fix an issue where multi-platform images that did not include a manifest for the default platform could not be interacted with. [moby/moby#45849](https://github.com/moby/moby/pull/45849)
* containerd image store: Fix specious attempts to cache `FROM scratch` in container builds. [moby/moby#45822](https://github.com/moby/moby/pull/45822)
* containerd image store: Fix `docker cp` with snapshotters that cannot mount the same content multiple times. [moby/moby#45780](https://github.com/moby/moby/pull/45780), [moby/moby#45786](https://github.com/moby/moby/pull/45786)
* containerd image store: Fix builds with `type=image` not being correctly unpacked/stored. [moby/moby#45692](https://github.com/moby/moby/pull/45692)
* containerd image store: Fix incorrectly attempting to unpack pseudo-images (including attestations) in `docker load`. [moby/moby#45688](https://github.com/moby/moby/pull/45688)
* containerd image store: Correctly set the user agent, and include additional information like the snapshotter when interacting with registries. [moby/moby#45671](https://github.com/moby/moby/pull/45671), [moby/moby#45684](https://github.com/moby/moby/pull/45684)
* containerd image store: Fix a failure to unpack already-pulled content after switching between snapshotters. [moby/moby#45678](https://github.com/moby/moby/pull/45678)
* containerd image store: Fix images that have been re-tagged or with all tags removed being pruned while still in use. [moby/moby#45857](https://github.com/moby/moby/pull/45857)
* Fix a Swarm CSI issue where the Topology field was not propagated into NodeCSIInfo. [moby/moby#45810](https://github.com/moby/moby/pull/45810)
* Fix failures to add new Swarm managers caused by a very large raft log. [moby/moby#45703](https://github.com/moby/moby/pull/45703), [moby/swarmkit#3122](https://github.com/moby/swarmkit/pull/3122), [moby/swarmkit#3128](https://github.com/moby/swarmkit/pull/3128)
* `name_to_handle_at(2)` is now always allowed in the default seccomp profile. [moby/moby#45833](https://github.com/moby/moby/pull/45833)
* Fix an issue that prevented encrypted Swarm overlay networks from working on ports other than the default (4789). [moby/moby#45637](https://github.com/moby/moby/pull/45637)
* Fix a failure to restore mount reference-counts during live-restore. [moby/moby#45824](https://github.com/moby/moby/pull/45824)
* Fix various networking-related failures during live-restore. [moby/moby#45658](https://github.com/moby/moby/pull/45658), [moby/moby#45659](https://github.com/moby/moby/pull/45659)
* Fix running containers restoring with a zero (successful) exit status when the daemon is unexpectedly terminated. [moby/moby#45801](https://github.com/moby/moby/pull/45801)
* Fix a potential panic while executing healthcheck probes. [moby/moby#45798](https://github.com/moby/moby/pull/45798)
* Fix a panic caused by a race condition in container exec start. [moby/moby#45794](https://github.com/moby/moby/pull/45794)
* Fix an exception caused by attaching a terminal to an exec with a non-existent command. [moby/moby#45643](https://github.com/moby/moby/pull/45643)
* Fix `host-gateway` with BuildKit by passing the IP as a label (also requires [docker/buildx#1894](https://github.com/docker/buildx/pull/1894)). [moby/moby#45790](https://github.com/moby/moby/pull/45790)
* Fix an issue where `POST /containers/{id}/stop` would forcefully terminate the container when the request was canceled, instead of waiting until the specified timeout for a 'graceful' stop. [moby/moby#45774](https://github.com/moby/moby/pull/45774)
* Fix an issue where `docker cp -a` from the root (`/`) directory would fail. [moby/moby#45748](https://github.com/moby/moby/pull/45748)
* Improve compatibility with non-runc container runtimes by more correctly setting resource constraint parameters in the OCI config. [moby/moby#45746](https://github.com/moby/moby/pull/45746)
* Fix an issue caused by overlapping subuid/subgid ranges in certain configurations (e.g. LDAP) in rootless mode. [moby/moby#45747](https://github.com/moby/moby/pull/45747), [rootless-containers/rootlesskit#369](https://github.com/rootless-containers/rootlesskit/pull/369)
* Greatly reduce CPU and memory usage while populating the Debug section of `GET /info`. [moby/moby#45856](https://github.com/moby/moby/pull/45856)
* Fix an issue where debug information was not correctly printed during `docker info` when only the client is in debug mode. [docker/cli#4393](https://github.com/docker/cli/pull/4393)
* Fix issues related to hung connections when connecting to hosts over a SSH connection. [docker/cli#4395](https://github.com/docker/cli/pull/4395)

### [Packaging updates](#packaging-updates-5)

* Upgrade Go to `go1.20.5`. [moby/moby#45745](https://github.com/moby/moby/pull/45745), [docker/cli#4351](https://github.com/docker/cli/pull/4351), [docker/docker-ce-packaging#904](https://github.com/docker/docker-ce-packaging/pull/904)
* Upgrade Compose to `v2.19.1`. [docker/docker-ce-packaging#916](https://github.com/docker/docker-ce-packaging/pull/916)
* Upgrade buildx to `v0.11.1`. [docker/docker-ce-packaging#918](https://github.com/docker/docker-ce-packaging/pull/918)

## [24.0.2](#2402)

*2023-05-26*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 24.0.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A24.0.2)
* [moby/moby, 24.0.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A24.0.2)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-6)

* Fix a panic during build when referencing locally tagged images. [moby/buildkit#3899](https://github.com/moby/buildkit/pull/3899), [moby/moby#45582](https://github.com/moby/moby/pull/45582)
* Fix builds potentially failing with `exit code: 4294967295` when performing many concurrent build stages. [moby/moby#45620](https://github.com/moby/moby/pull/45620)
* Fix DNS resolution on Windows ignoring `etc/hosts` (`%WINDIR%\System32\Drivers\etc\hosts`), including resolution of `localhost`. [moby/moby#45562](https://github.com/moby/moby/pull/45562)
* Apply a workaround for a containerd bug that causes concurrent `docker exec` commands to take significantly longer than expected. [moby/moby#45625](https://github.com/moby/moby/pull/45625)
* containerd image store: Fix an issue where the image `Created` field would contain an incorrect value. [moby/moby#45623](https://github.com/moby/moby/pull/45623)
* containerd image store: Adjust the output of image pull progress so that the output has the same format regardless of whether the containerd image store is enabled. [moby/moby#45602](https://github.com/moby/moby/pull/45602)
* containerd image store: Switching between the default and containerd image store now requires a daemon restart. [moby/moby#45616](https://github.com/moby/moby/pull/45616)

### [Packaging updates](#packaging-updates-6)

* Upgrade Buildx to `v0.10.5`. [docker/docker-ce-packaging#900](https://github.com/docker/docker-ce-packaging/pull/900)

## [24.0.1](#2401)

*2023-05-19*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 24.0.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A24.0.1)
* [moby/moby, 24.0.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A24.0.1)

### [Removed](#removed)

* Remove CLI completions for storage drivers removed in the 24.0 major release. [docker/cli#4302](https://github.com/docker/cli/pull/4302)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-7)

* Fix an issue where DNS query NXDOMAIN replies from external servers were forwarded to the client as SERVFAIL. [moby/moby#45573](https://github.com/moby/moby/pull/45573)
* Fix an issue where `docker pull --platform` would report `No such image` regarding another tag pointing to the same image. [moby/moby#45562](https://github.com/moby/moby/pull/45562)
* Fix an issue where insecure registry configuration would be forgotten during config reload. [moby/moby#45571](https://github.com/moby/moby/pull/45571)
* containerd image store: Fix an issue where images which have no layers would not be listed in `docker images -a` [moby/moby#45588](https://github.com/moby/moby/pull/45588)
* API: Fix an issue where `GET /images/{id}/json` would return `null` instead of empty `RepoTags` and `RepoDigests`. [moby/moby#45564](https://github.com/moby/moby/pull/45564)
* API: Fix an issue where `POST /commit` did not accept an empty request body. [moby/moby#45568](https://github.com/moby/moby/pull/45568)

### [Packaging updates](#packaging-updates-7)

* Upgrade Compose to `v2.18.1`. [docker/docker-ce-packaging#896](https://github.com/docker/docker-ce-packaging/pull/896)

## [24.0.0](#2400)

*2023-05-16*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 24.0.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A24.0.0)
* [moby/moby, 24.0.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A24.0.0)

### [New](#new)

* Introduce experimental support for containerd as the content store (replacing the existing storage drivers). [moby/moby#43735](https://github.com/moby/moby/pull/43735), [other moby/moby pull requests](https://github.com/moby/moby/pulls?q=is%3Apr+is%3Amerged+milestone%3A24.0.0+-label%3Aprocess%2Fcherry-picked+label%3Acontainerd-integration+)
* The `--host` CLI flag now supports a path component in a `ssh://` host address, allowing use of an alternate socket path without configuration on the remote host. [docker/cli#4073](https://github.com/docker/cli/pull/4073)
* The `docker info` CLI command now reports a version and platform field. [docker/cli#4180](https://github.com/docker/cli/pull/4180)
* Introduce the daemon flag `--default-network-opt` to configure options for newly created networks. [moby/moby#43197](https://github.com/moby/moby/pull/43197)
* Restrict access to `AF_VSOCK` in the `socket(2)` family of syscalls in the default seccomp profile. [moby/moby#44562](https://github.com/moby/moby/pull/44562)
* Introduce support for setting OCI runtime annotations on containers. [docker/cli#4156](https://github.com/docker/cli/pull/4156), [moby/moby#45025](https://github.com/moby/moby/pull/45025)
* Alternative runtimes can now be configured in `daemon.json`, enabling runtime names to be aliased and options to be passed. [moby/moby#45032](https://github.com/moby/moby/pull/45032)
* The `docker-init` binary will now be discovered in FHS-compliant libexec directories, in addition to the `PATH`. [moby/moby#45198](https://github.com/moby/moby/pull/45198)
* API: Surface the daemon-level `--no-new-privileges` in `GET /info`. [moby/moby#45320](https://github.com/moby/moby/pull/45320)

### [Removed](#removed-1)

* `docker info` no longer reports `IndexServiceAddress`. [docker/cli#4204](https://github.com/docker/cli/pull/4204)
* libnetwork: Remove fallback code for obsolete kernel versions. [moby/moby#44684](https://github.com/moby/moby/pull/44684), [moby/moby#44802](https://github.com/moby/moby/pull/44802)
* libnetwork: Remove unused code related to classic Swarm. [moby/moby#44965](https://github.com/moby/moby/pull/44965)
* libnetwork: Remove usage of the `xt_u32` kernel module from encrypted Swarm overlay networks. [moby/moby#45281](https://github.com/moby/moby/pull/45281)
* Remove support for BuildKit's deprecated `buildinfo` in favor of standard provenance attestations. [moby/moby#45097](https://github.com/moby/moby/pull/45097)
* Remove the deprecated AUFS and legacy `overlay` storage drivers. [moby/moby#45342](https://github.com/moby/moby/pull/45342), [moby/moby#45359](https://github.com/moby/moby/pull/45359)
* Remove the deprecated `overlay2.override_kernel_check` storage driver option. [moby/moby#45368](https://github.com/moby/moby/pull/45368)
* Remove workarounds for obsolete versions of `apparmor_parser` from the AppArmor profiles. [moby/moby#45500](https://github.com/moby/moby/pull/45500)
* API: `GET /images/json` no longer represents empty RepoTags and RepoDigests as`<none>:<none>`/`<none>@<none>`. Empty arrays are returned instead on API >= 1.43. [moby/moby#45068](https://github.com/moby/moby/pull/45068)

### [Deprecated](#deprecated)

* Deprecate the `--oom-score-adjust` daemon option. [moby/moby#45315](https://github.com/moby/moby/pull/45315)
* API: Deprecate the `VirtualSize` field in `GET /images/json` and `GET /images/{id}/json`. [moby/moby#45346](https://github.com/moby/moby/pull/45346)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-8)

* The `docker stack` command no longer validates the `build` section of Compose files. [docker/cli#4214](https://github.com/docker/cli/pull/4214)
* Fix lingering healthcheck processes after the timeout is reached. [moby/moby#43739](https://github.com/moby/moby/pull/43739)
* Reduce the overhead of container startup when using the `overlay2` storage driver. [moby/moby#44285](https://github.com/moby/moby/pull/44285)
* API: Handle multiple `before=` and `since=` filters in `GET /images`. [moby/moby#44503](https://github.com/moby/moby/pull/44503)
* Fix numerous bugs in the embedded DNS resolver implementation used by user-defined networks. [moby/moby#44664](https://github.com/moby/moby/pull/44664)
* Add `execDuration` field to the map of event attributes. [moby/moby#45494](https://github.com/moby/moby/pull/45494)
* Swarm-level networks can now be created with the Windows `internal`, `l2bridge`, and `nat` drivers. [moby/swarmkit#3121](https://github.com/moby/swarmkit/pull/3121), [moby/moby#45291](https://github.com/moby/moby/pull/45291)

### [Packaging updates](#packaging-updates-8)

* Update Go to `1.20.4`. [docker/cli#4253](https://github.com/docker/cli/pull/4253), [moby/moby#45456](https://github.com/moby/moby/pull/45456), [docker/docker-ce-packaging#888](https://github.com/docker/docker-ce-packaging/pull/888)
* Update `containerd` to [`v1.7.1`](https://github.com/containerd/containerd/releases/tag/v1.7.1). [moby/moby#45537](https://github.com/moby/moby/pull/45537)
* Update `buildkit` to [`v0.11.6`](https://github.com/moby/buildkit/releases/v0.11.6). [moby/moby#45367](https://github.com/moby/moby/pull/45367)

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/get/
----

# docker dhi customization get

***

| Description | Get details of a specific customization |
| ----------- | --------------------------------------- |
| Usage       | `docker dhi customization get <id>`     |

## [Description](#description)

Get detailed information about a Docker Hardened Images customization by its ID.

----
url: https://docs.docker.com/guides/lab-docker-agent/
----

[Lab: Getting Started with Docker Agent](https://docs.docker.com/guides/lab-docker-agent/)

Hands-on lab: Create, share, and orchestrate intelligent AI agents using Docker Agent, MCP Toolkit, and Docker.

AI Labs

20 minutes

Resources:

* [Docker Agent documentation](https://github.com/docker/docker-agent)
* [Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/)
* [Labspace repository](https://github.com/ajeetraina/labspace-cagent)

[« Back to all guides](/guides/)

# Lab: Getting Started with Docker Agent

***

Table of contents

***

This lab walks you through building intelligent agents with Docker Agent. You'll learn beginner agent concepts, then build sophisticated multi-agent teams that handle complex real-world tasks. Learn how to create, share, and orchestrate AI agents with Docker.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-cagent up -d
   ```

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

* Create simple agents with Docker Agent
* Use built-in generic agentic tools for common tasks
* Integrate MCP servers from the MCP Toolkit
* Share agents using the Docker Registry
* Build multi-agent systems for complex workflows
* Use Docker Model Runner with Docker Agent (preview)

## [Modules](#modules)

| # | Module                     | Description                                             |
| - | -------------------------- | ------------------------------------------------------- |
| 1 | Introduction               | Overview of Docker Agent and intelligent agent concepts |
| 2 | Getting Started            | Create your first agent with Docker Agent               |
| 3 | Using Built-in Tools       | Leverage the generic agentic tools in Docker Agent      |
| 4 | Using MCP                  | Integrate MCP servers from the MCP Toolkit              |
| 5 | Sharing Agents             | Package and share agents via Docker Registry            |
| 6 | Introduction to Sub-agents | Build multi-agent systems with sub-agent orchestration  |
| 7 | Conclusion                 | Summary and next steps                                  |

----
url: https://docs.docker.com/desktop/features/networking/networking-how-tos/
----

# Explore networking how-tos on Docker Desktop

***

Table of contents

***

This page explains how to configure and use networking features, connect containers to host services, work behind proxies or VPNs, and troubleshoot common issues.

For details on how Docker Desktop routes network traffic and file I/O between containers, the VM, and the host, see [Network overview](https://docs.docker.com/desktop/features/networking/#overview).

## [Core networking how-tos](#core-networking-how-tos)

### [Connect a container to a service on the host](#connect-a-container-to-a-service-on-the-host)

The host has a changing IP address, or none if you have no network access. To connect to services running on your host, use the special DNS name:

| Name                      | Description                                      |
| ------------------------- | ------------------------------------------------ |
| `host.docker.internal`    | Resolves to the internal IP address of your host |
| `gateway.docker.internal` | Resolves to the gateway IP of the Docker VM      |

#### [Example](#example)

Run a simple HTTP server on port `8000`:

```console
$ python -m http.server 8000
```

Then run a container, install `curl`, and try to connect to the host using the following commands:

```console
$ docker run --rm -it alpine sh
# apk add curl
# curl http://host.docker.internal:8000
# exit
```

### [Connect to a container from the host](#connect-to-a-container-from-the-host)

To access containerized services from your host or local network, publish ports with the `-p` or `--publish` flag. For example:

```console
$ docker run -d -p 80:80 --name webserver nginx
```

Docker Desktop makes whatever is running on port `80` in the container, in this case, `nginx`, available on port `80` of `localhost`.

> Tip
>
> The syntax for `-p` is `HOST_PORT:CLIENT_PORT`.

To publish all ports, use the `-P` flag. For example, the following command starts a container (in detached mode) and the `-P` flag publishes all exposed ports of the container to random ports on the host.

```console
$ docker run -d -P --name webserver nginx
```

Alternatively, you can also use [host networking](https://docs.docker.com/engine/network/drivers/host/#docker-desktop) to give the container direct access to the network stack of the host.

See the [run command](/reference/cli/docker/container/run/) for more details on publish options used with `docker run`.

All inbound connections pass through the Docker Desktop backend process (`com.docker.backend` (Mac), `com.docker.backend` (Windows), or `qemu` (Linux), which handles port forwarding into the VM. For more details, see [How exposed ports work](https://docs.docker.com/desktop/features/networking/#how-exposed-ports-work)

### [Working with VPNs](#working-with-vpns)

Docker Desktop networking can work when attached to a VPN.

To do this, Docker Desktop intercepts traffic from the containers and injects it into the host as if it originated from the Docker application.

For details about how this traffic appears to host firewalls and endpoint detection systems, see [Firewalls and endpoint visibility](https://docs.docker.com/desktop/features/networking/#firewalls-and-endpoint-visibility).

### [Working with proxies](#working-with-proxies)

Docker Desktop can use your system proxy or a manual configuration. To configure proxies:

1. Navigate to the **Resources** tab in **Settings**.
2. From the dropdown menu select **Proxies**.
3. Switch on the **Manual proxy configuration** toggle.
4. Enter your HTTP, HTTPS or SOCKS5 proxy URLS.

For more details on proxies and proxy configurations, see the [Proxy settings documentation](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies).

## [Network how-tos for Mac and Windows](#network-how-tos-for-mac-and-windows)

You can control how Docker handles container networking and DNS resolution to better support a range of environments — from IPv4-only to dual-stack and IPv6-only systems. These settings help prevent timeouts and connectivity issues caused by incompatible or misconfigured host networks.

You can set the following settings on the **Network** tab in the Docker Desktop Dashboard settings, or if you're an admin, with Settings Management via the [`admin-settings.json` file](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/#networking), or the [Admin Console](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/)

> Note
>
> These settings can be overridden on a per-network basis using CLI flags or Compose file options.

### [Default networking mode](#default-networking-mode)

Choose the default IP protocol used when Docker creates new networks. This allows you to align Docker with your host’s network capabilities or organizational requirements, such as enforcing IPv6-only access.

| Mode                         | Description                                 |
| ---------------------------- | ------------------------------------------- |
| **Dual IPv4/IPv6 (default)** | Supports both IPv4 and IPv6. Most flexible. |
| **IPv4 only**                | Uses only IPv4 addressing.                  |
| **IPv6 only**                | Uses only IPv6 addressing.                  |

### [DNS resolution behavior](#dns-resolution-behavior)

Control how Docker filters DNS records returned to containers, improving reliability in environments where only IPv4 or IPv6 is supported. This setting is especially useful for preventing apps from trying to connect using IP families that aren't actually available, which can cause avoidable delays or failures.

| Option                         | Description                                                                 |
| ------------------------------ | --------------------------------------------------------------------------- |
| **Auto (recommended)**         | Automatically filters unsupported record types. (A for IPv4, AAAA for IPv6) |
| **Filter IPv4 (A records)**    | Blocks IPv4 lookups. Only available in dual-stack mode.                     |
| **Filter IPv6 (AAAA records)** | Blocks IPv6 lookups. Only available in dual-stack mode.                     |
| **No filtering**               | Returns both A and AAAA records.                                            |

> Important
>
> Switching the default networking mode resets the DNS filter to Auto.

## [Network how-tos for Mac and Linux](#network-how-tos-for-mac-and-linux)

### [SSH agent forwarding](#ssh-agent-forwarding)

Docker Desktop for Mac and Linux lets you use the host’s SSH agent inside a container. To do this:

1. Bind mount the SSH agent socket by adding the following parameter to your `docker run` command:

   ```console
   $--mount type=bind,src=/run/host-services/ssh-auth.sock,target=/run/host-services/ssh-auth.sock
   ```

2. Add the `SSH_AUTH_SOCK` environment variable in your container:

   ```console
   $ -e SSH_AUTH_SOCK="/run/host-services/ssh-auth.sock"
   ```

To enable the SSH agent in Docker Compose, add the following flags to your service:

```yaml
services:
 web:
   image: nginx:alpine
   volumes:
     - type: bind
       source: /run/host-services/ssh-auth.sock
       target: /run/host-services/ssh-auth.sock
   environment:
     - SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock
```

## [Known limitations](#known-limitations)

### [Changing internal IP addresses](#changing-internal-ip-addresses)

The internal IP addresses used by Docker can be changed from **Settings**. After changing IPs, you need to reset the Kubernetes cluster and to leave any active Swarm.

### [There is no `docker0` bridge on the host](#there-is-no-docker0-bridge-on-the-host)

Because of the way networking is implemented in Docker Desktop, you cannot see a `docker0` interface on the host. This interface is actually within the virtual machine.

### [I cannot ping my containers](#i-cannot-ping-my-containers)

Docker Desktop can't route traffic to Linux containers. However if you're a Windows user, you can ping the Windows containers.

### [Per-container IP addressing is not possible](#per-container-ip-addressing-is-not-possible)

This is because the Docker `bridge` network is not reachable from the host. However if you are a Windows user, per-container IP addressing is possible with Windows containers.

----
url: https://docs.docker.com/reference/cli/docker/container/pause/
----

# docker container pause

***

| Description                                                               | Pause all processes within one or more containers |
| ------------------------------------------------------------------------- | ------------------------------------------------- |
| Usage                                                                     | `docker container pause CONTAINER [CONTAINER...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker pause`                                    |

## [Description](#description)

The `docker pause` command suspends all processes in the specified containers. On Linux, this uses the freezer cgroup. Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. On Windows, only Hyper-V containers can be paused.

See the [freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) for further details.

## [Examples](#examples)

```console
$ docker pause my_container
```

----
url: https://docs.docker.com/reference/cli/docker/buildx/bake/
----

# docker buildx bake

***

| Description                                                               | Build from a file                          |
| ------------------------------------------------------------------------- | ------------------------------------------ |
| Usage                                                                     | `docker buildx bake [OPTIONS] [TARGET...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker buildx f`                          |

## [Description](#description)

Bake is a high-level build command. Each specified target runs in parallel as part of the build.

Read [High-level build options with Bake](/build/bake/) guide for introduction to writing bake files.

> Note
>
> `buildx bake` command may receive backwards incompatible features in the future if needed. We are looking for feedback on improving the command and extending the functionality further.

## [Options](#options)

| Option                              | Default | Description                                                                                                           |
| ----------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| [`--allow`](#allow)                 |         | Allow build to access specified resources                                                                             |
| [`--call`](#call)                   | `build` | Set method for evaluating build (`check`, `outline`, `targets`)                                                       |
| [`--check`](#check)                 |         | Shorthand for `--call=check`                                                                                          |
| [`-f, --file`](#file)               |         | Build definition file                                                                                                 |
| [`--list`](#list)                   |         | List targets or variables                                                                                             |
| [`--load`](#load)                   |         | Shorthand for `--set=*.output=type=docker`. Conditional.                                                              |
| [`--metadata-file`](#metadata-file) |         | Write build result metadata to a file                                                                                 |
| [`--no-cache`](#no-cache)           |         | Do not use cache when building the image                                                                              |
| `--policy`                          |         | Global policy evaluation options (format: `[disabled=true\|false][,strict=true\|false][,log-level=level]`)            |
| [`--print`](#print)                 |         | Print the options without building                                                                                    |
| [`--progress`](#progress)           | `auto`  | Set type of progress output (`auto`, `none`, `plain`, `quiet`, `rawjson`, `tty`). Use plain to show container output  |
| [`--provenance`](#provenance)       |         | Shorthand for `--set=*.attest=type=provenance`                                                                        |
| [`--pull`](#pull)                   |         | Always attempt to pull all referenced images                                                                          |
| [`--push`](#push)                   |         | Shorthand for `--set=*.output=type=registry`. Conditional.                                                            |
| [`--sbom`](#sbom)                   |         | Shorthand for `--set=*.attest=type=sbom`                                                                              |
| [`--set`](#set)                     |         | Override target value (e.g., `targetpattern.key=value`)                                                               |
| `--var`                             |         | Set a variable value (e.g., `name=value`)                                                                             |

## [Examples](#examples)

### [Allow extra privileged entitlement (--allow)](#allow)

```text
--allow=ENTITLEMENT[=VALUE]
```

Entitlements are designed to provide controlled access to privileged operations. By default, Buildx and BuildKit operates with restricted permissions to protect users and their systems from unintended side effects or security risks. The `--allow` flag explicitly grants access to additional entitlements, making it clear when a build or bake operation requires elevated privileges.

In addition to BuildKit's `network.host` and `security.insecure` entitlements (see [`docker buildx build --allow`](/reference/cli/docker/buildx/build/#allow)), Bake supports file system entitlements that grant granular control over file system access. These are particularly useful when working with builds that need access to files outside the default working directory.

Bake supports the following filesystem entitlements:

* `--allow fs=<path|*>` - Grant read and write access to files outside of the working directory.
* `--allow fs.read=<path|*>` - Grant read access to files outside of the working directory.
* `--allow fs.write=<path|*>` - Grant write access to files outside of the working directory.

The `fs` entitlements take a path value (relative or absolute) to a directory on the filesystem. Alternatively, you can pass a wildcard (`*`) to allow Bake to access the entire filesystem.

### [Example: fs.read](#example-fsread)

Given the following Bake configuration, Bake would need to access the parent directory, relative to the Bake file.

```hcl
target "app" {
  context = "../src"
}
```

Assuming `docker buildx bake app` is executed in the same directory as the `docker-bake.hcl` file, you would need to explicitly allow Bake to read from the `../src` directory. In this case, the following invocations all work:

```console
$ docker buildx bake --allow fs.read=* app
$ docker buildx bake --allow fs.read=../src app
$ docker buildx bake --allow fs=* app
```

### [Example: fs.write](#example-fswrite)

The following `docker-bake.hcl` file requires write access to the `/tmp` directory.

```hcl
target "app" {
  output = "/tmp"
}
```

Assuming `docker buildx bake app` is executed outside of the `/tmp` directory, you would need to allow the `fs.write` entitlement, either by specifying the path or using a wildcard:

```console
$ docker buildx bake --allow fs=/tmp app
$ docker buildx bake --allow fs.write=/tmp app
$ docker buildx bake --allow fs.write=* app
```

### [Override the configured builder instance (--builder)](#builder)

Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

### [Invoke a frontend method (--call)](#call)

Same as [`build --call`](/reference/cli/docker/buildx/build/#call).

#### [Call: check (--check)](#check)

Same as [`build --check`](/reference/cli/docker/buildx/build/#check).

### [Specify a build definition file (-f, --file)](#file)

Use the `-f` / `--file` option to specify the build definition file to use. The file can be an HCL, JSON or Compose file. If multiple files are specified, all are read and the build configurations are combined.

Alternatively, the environment variable `BUILDX_BAKE_FILE` can be used to specify the build definition to use. This is mutually exclusive with `-f` / `--file`; if both are specified, the environment variable is ignored. Multiple definitions can be specified by separating them with the system's path separator (typically `;` on Windows and `:` elsewhere), but can be changed with `BUILDX_BAKE_PATH_SEPARATOR`.

You can pass the names of the targets to build, to build only specific target(s). The following example builds the `db` and `webapp-release` targets that are defined in the `docker-bake.dev.hcl` file:

```hcl
# docker-bake.dev.hcl
group "default" {
  targets = ["db", "webapp-dev"]
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp"]
}

target "webapp-release" {
  inherits = ["webapp-dev"]
  platforms = ["linux/amd64", "linux/arm64"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  tags = ["docker.io/username/db"]
}
```

```console
$ docker buildx bake -f docker-bake.dev.hcl db webapp-release
```

See the [Bake file reference](/build/bake/reference/) for more details.

### [List targets and variables (--list)](#list)

The `--list` flag displays all available targets or variables in the Bake configuration, along with a description (if set using the `description` property in the Bake file).

To list all targets:

List targets

```console
$ docker buildx bake --list=targets
TARGET              DESCRIPTION
binaries
default             binaries
update-docs
validate
validate-golangci   Validate .golangci.yml schema (does not run Go linter)
```

To list variables:

```console
$ docker buildx bake --list=variables
VARIABLE      TYPE      VALUE                DESCRIPTION
REGISTRY      string    docker.io/username   Registry and namespace
IMAGE_NAME    string    my-app               Image name
GO_VERSION              <null>
DEBUG         bool      false                Add debug symbols
```

Variable types will be shown when set using the `type` property in the Bake file.

The `--list=variables` option displays variables defined in the Bake file, including their descriptions and default values.

### [Example: listing variables with descriptions](#example-listing-variables-with-descriptions)

```hcl
variable "GO_VERSION" {
  default     = "1.22"
  description = "Go version used for building the application"
}
```

```console
$ docker buildx bake --list=variables

NAME          DESCRIPTION                                      DEFAULT
GO_VERSION    Go version used for building the application     1.22
```

By default, the output of `docker buildx bake --list` is presented in a table format. Alternatively, you can use a long-form CSV syntax and specify a `format` attribute to output the list in JSON.

```console
$ docker buildx bake --list=type=targets,format=json
```

### [Load images into Docker (--load)](#load)

The `--load` flag is a convenience shorthand for adding an image export of type `docker`:

```console
--load   ≈   --set=*.output=type=docker
```

However, its behavior is conditional:

* If the build definition has no output defined, `--load` adds `type=docker`.
* If the build definition’s outputs are `docker`, `image`, `registry`, `oci`, `--load` will add a `type=docker` export if one is not already present.
* If the build definition contains `local` or `tar` outputs, `--load` does nothing. It will not override those outputs.

For example, with the following bake file:

```hcl
target "default" {
  output = ["type=tar,dest=hi.tar"]
}
```

With `--load`:

```console
$ docker buildx bake --load --print
...
"output": [
  {
    "dest": "hi.tar"
    "type": "tar",
   }
]
```

The `tar` output remains unchanged.

### [Write build results metadata to a file (--metadata-file)](#metadata-file)

Similar to [`buildx build --metadata-file`](/reference/cli/docker/buildx/build/#metadata-file) but writes a map of results for each target such as:

```hcl
# docker-bake.hcl
group "default" {
  targets = ["db", "webapp-dev"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  tags = ["docker.io/username/db"]
}

target "webapp-dev" {
  dockerfile = "Dockerfile.webapp"
  tags = ["docker.io/username/webapp"]
}
```

```console
$ docker buildx bake --load --metadata-file metadata.json .
$ cat metadata.json
```

```json
{
  "buildx.build.warnings": {},
  "db": {
    "buildx.build.provenance": {},
    "buildx.build.ref": "mybuilder/mybuilder0/0fjb6ubs52xx3vygf6fgdl611",
    "containerimage.config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
    "containerimage.descriptor": {
      "annotations": {
        "config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
        "org.opencontainers.image.created": "2022-02-08T21:28:03Z"
      },
      "digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 506
    },
    "containerimage.digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3"
  },
  "webapp-dev": {
    "buildx.build.provenance": {},
    "buildx.build.ref": "mybuilder/mybuilder0/kamngmcgyzebqxwu98b4lfv3n",
    "containerimage.config.digest": "sha256:9651cc2b3c508f697c9c43b67b64c8359c2865c019e680aac1c11f4b875b67e0",
    "containerimage.descriptor": {
      "annotations": {
        "config.digest": "sha256:9651cc2b3c508f697c9c43b67b64c8359c2865c019e680aac1c11f4b875b67e0",
        "org.opencontainers.image.created": "2022-02-08T21:28:15Z"
      },
      "digest": "sha256:6d9ac9237a84afe1516540f40a0fafdc86859b2141954b4d643af7066d598b74",
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 506
    },
    "containerimage.digest": "sha256:6d9ac9237a84afe1516540f40a0fafdc86859b2141954b4d643af7066d598b74"
  }
}
```

> Note
>
> Build record [provenance](/build/metadata/attestations/slsa-provenance/#provenance-attestation-example) (`buildx.build.provenance`) includes minimal provenance by default. Set the `BUILDX_METADATA_PROVENANCE` environment variable to customize this behavior:
>
> * `min` sets minimal provenance (default).
> * `max` sets full provenance.
> * `disabled`, `false` or `0` does not set any provenance.

> Note
>
> Build warnings (`buildx.build.warnings`) are not included by default. Set the `BUILDX_METADATA_WARNINGS` environment variable to `1` or `true` to include them.

### [Don't use cache when building the image (--no-cache)](#no-cache)

Same as `build --no-cache`. Don't use cache when building the image.

### [Print the options without building (--print)](#print)

Prints the resulting options of the targets desired to be built, in a JSON format, without starting a build.

```console
$ docker buildx bake -f docker-bake.hcl --print db
{
  "group": {
    "default": {
      "targets": [
        "db"
      ]
    }
  },
  "target": {
    "db": {
      "context": "./",
      "dockerfile": "Dockerfile",
      "tags": [
        "docker.io/tiborvass/db"
      ]
    }
  }
}
```

### [Set type of progress output (--progress)](#progress)

Same as [`build --progress`](/reference/cli/docker/buildx/build/#progress).

### [Create provenance attestations (--provenance)](#provenance)

Same as [`build --provenance`](/reference/cli/docker/buildx/build/#provenance).

### [Always attempt to pull a newer version of the image (--pull)](#pull)

Same as `build --pull`.

### [Push images to a registry (--push)](#push)

The `--push` flag follows the same logic as `--load`:

* If no outputs are defined, it adds a `type=image,push=true` export.
* For existing `image` outputs, it sets `push=true`.
* If outputs are set to `local` or `tar`, it does not override them.

### [Create SBOM attestations (--sbom)](#sbom)

Same as [`build --sbom`](/reference/cli/docker/buildx/build/#sbom).

### [Override target configurations from command line (--set)](#set)

```text
--set targetpattern.key[.subkey]=value
```

Override target configurations from command line. The pattern matching syntax is defined in <https://golang.org/pkg/path/#Match>.

```console
$ docker buildx bake --set target.args.mybuildarg=value
$ docker buildx bake --set target.platform=linux/arm64
$ docker buildx bake --set foo*.args.mybuildarg=value   # overrides build arg for all targets starting with 'foo'
$ docker buildx bake --set *.platform=linux/arm64       # overrides platform for all targets
$ docker buildx bake --set foo*.no-cache                # bypass caching only for targets starting with 'foo'
$ docker buildx bake --set target.platform+=linux/arm64 # appends 'linux/arm64' to the platform list
$ docker buildx bake --set target.contexts.bar=../bar   # overrides 'bar' named context
```

> Note
>
> `--set` is a repeatable flag. For array fields such as `tags`, repeat `--set` to provide multiple values or use the `+=` operator to append without replacing. Array literal syntax like `--set target.tags=[a,b]` is not supported.

You can override the following fields:

* `annotations`
* `attest`
* `args`
* `cache-from`
* `cache-to`
* `call`
* `context`
* `contexts`
* `dockerfile`
* `entitlements`
* `extra-hosts`
* `labels`
* `load`
* `no-cache`
* `no-cache-filter`
* `output`
* `platform`
* `pull`
* `push`
* `secrets`
* `ssh`
* `tags`
* `target`

You can append using `+=` operator for the following fields:

* `annotations`¹
* `attest`¹
* `cache-from`
* `cache-to`
* `entitlements`¹
* `no-cache-filter`
* `output`
* `platform`
* `secrets`
* `ssh`
* `tags`

> Note
>
> ¹ These fields already append by default.

----
url: https://docs.docker.com/extensions/extensions-sdk/design/
----

# UI styling overview for Docker extensions

***

Table of contents

***

Our Design System is a constantly evolving set of specifications that aim to ensure visual consistency across Docker products, and meet [level AA accessibility standards](https://www.w3.org/WAI/WCAG2AA-Conformance). We've opened parts of it to extension authors, documenting basic styles (color, typography) and components. See: [Docker Extensions Styleguide](https://www.figma.com/file/U7pLWfEf6IQKUHLhdateBI/Docker-Design-Guidelines?node-id=1%3A28771).

We require extensions to match the wider Docker Desktop UI to a certain degree, and reserve the right to make this stricter in the future.

To get started on your UI, follow the steps below.

## [Step one: Choose your framework](#step-one-choose-your-framework)

### [Recommended: React+MUI, using our theme](#recommended-reactmui-using-our-theme)

Docker Desktop's UI is written in React and [MUI](https://mui.com/) (using Material UI specifically). This is the only officially supported framework for building extensions, and the one that the `init` command automatically configures for you. Using it brings significant benefits to authors:

* You can use our [Material UI theme](https://www.npmjs.com/package/@docker/docker-mui-theme) to automatically replicate Docker Desktop's look and feel.
* In future, we'll release utilities and components specifically targeting this combination (e.g. custom MUI components, or React hooks for interacting with Docker).

Read our [MUI best practices](https://docs.docker.com/extensions/extensions-sdk/design/mui-best-practices/) guide to learn future-proof ways to use MUI with Docker Desktop.

### [Not recommended: Some other framework](#not-recommended-some-other-framework)

You may prefer to use another framework, perhaps because you or your team are more familiar with it or because you have existing assets you want to reuse. This is possible, but highly discouraged. It means that:

* You'll need to manually replicate the look and feel of Docker Desktop. This takes a lot of effort, and if you don't match our theme closely enough, users will find your extension jarring and we may ask you to make changes during a review process.
* You'll have a higher maintenance burden. Whenever Docker Desktop's theme changes (which could happen in any release), you'll need to manually change your extension to match it.
* If your extension is open-source, deliberately avoiding common conventions will make it harder for the community to contribute to it.

## [Step two: Follow the below recommendations](#step-two-follow-the-below-recommendations)

### [Follow our MUI best practices (if applicable)](#follow-our-mui-best-practices-if-applicable)

See our [MUI best practices](https://docs.docker.com/extensions/extensions-sdk/design/mui-best-practices/) article.

### [Only use colors from our palette](#only-use-colors-from-our-palette)

With minor exceptions, displaying your logo for example, you should only use colors from our palette. These can be found in our [style guide document](https://www.figma.com/file/U7pLWfEf6IQKUHLhdateBI/Docker-Design-Guidelines?node-id=1%3A28771), and will also soon be available in our MUI theme and via CSS variables.

### [Use counterpart colors in light/dark mode](#use-counterpart-colors-in-lightdark-mode)

Our colors have been chosen so that the counterpart colors in each variant of the palette should have the same essential characteristics. Anywhere you use `red-300` in light mode, you should use `red-300` in dark mode too.

## [What's next?](#whats-next)

* Take a look at our [MUI best practices](https://docs.docker.com/extensions/extensions-sdk/design/mui-best-practices/).
* Learn how to [publish your extension](https://docs.docker.com/extensions/extensions-sdk/extensions/).

----
url: https://docs.docker.com/engine/release-notes/17.11/
----

# Docker Engine 17.11 release notes

***

Table of contents

***

## [17.11.0-ce](#17110-ce)

2017-11-20

> Important
>
> Docker CE 17.11 is the first Docker release based on [containerd 1.0 beta](https://github.com/containerd/containerd/releases/tag/v1.0.0-beta.2). Docker CE 17.11 and later don't recognize containers started with previous Docker versions. If you use Live Restore, you must stop all containers before upgrading to Docker CE 17.11. If you don't, any containers started by Docker versions that predate 17.11 aren't recognized by Docker after the upgrade and keep running, un-managed, on the system.

### [Builder](#builder)

* Test & Fix build with rm/force-rm matrix [moby/moby#35139](https://github.com/moby/moby/pull/35139)

- Fix build with `--stream` with a large context [moby/moby#35404](https://github.com/moby/moby/pull/35404)

### [Client](#client)

* Hide help flag from help output [docker/cli#645](https://github.com/docker/cli/pull/645)
* Support parsing of named pipes for compose volumes [docker/cli#560](https://github.com/docker/cli/pull/560)
* \[Compose] Cast values to expected type after interpolating values [docker/cli#601](https://github.com/docker/cli/pull/601)

- Add output for "secrets" and "configs" on `docker stack deploy` [docker/cli#593](https://github.com/docker/cli/pull/593)

* Fix flag description for `--host-add` [docker/cli#648](https://github.com/docker/cli/pull/648)

- Do not truncate ID on docker service ps --quiet [docker/cli#579](https://github.com/docker/cli/pull/579)

### [Deprecation](#deprecation)

* Update bash completion and deprecation for synchronous service updates [docker/cli#610](https://github.com/docker/cli/pull/610)

### [Logging](#logging)

* copy to log driver's bufsize, fixes #34887 [moby/moby#34888](https://github.com/moby/moby/pull/34888)

- Add TCP support for GELF log driver [moby/moby#34758](https://github.com/moby/moby/pull/34758)
- Add credentials endpoint option for awslogs driver [moby/moby#35055](https://github.com/moby/moby/pull/35055)

### [Networking](#networking)

* Fix network name masking network ID on delete [moby/moby#34509](https://github.com/moby/moby/pull/34509)
* Fix returned error code for network creation from 500 to 409 [moby/moby#35030](https://github.com/moby/moby/pull/35030)
* Fix tasks fail with error "Unable to complete atomic operation, key modified" [docker/libnetwork#2004](https://github.com/docker/libnetwork/pull/2004)

### [Runtime](#runtime)

* Switch to Containerd 1.0 client [moby/moby#34895](https://github.com/moby/moby/pull/34895)
* Increase container default shutdown timeout on Windows [moby/moby#35184](https://github.com/moby/moby/pull/35184)
* LCOW: API: Add `platform` to /images/create and /build [moby/moby#34642](https://github.com/moby/moby/pull/34642)
* Stop filtering Windows manifest lists by version [moby/moby#35117](https://github.com/moby/moby/pull/35117)
* Use windows console mode constants from Azure/go-ansiterm [moby/moby#35056](https://github.com/moby/moby/pull/35056)
* Windows Daemon should respect DOCKER\_TMPDIR [moby/moby#35077](https://github.com/moby/moby/pull/35077)
* Windows: Fix startup logging [moby/moby#35253](https://github.com/moby/moby/pull/35253)

- Add support for Windows version filtering on pull [moby/moby#35090](https://github.com/moby/moby/pull/35090)

* Fixes LCOW after containerd 1.0 introduced regressions [moby/moby#35320](https://github.com/moby/moby/pull/35320)

- ContainerWait on remove: don't stuck on rm fail [moby/moby#34999](https://github.com/moby/moby/pull/34999)
- oci: obey CL\_UNPRIVILEGED for user namespaced daemon [moby/moby#35205](https://github.com/moby/moby/pull/35205)
- Don't abort when setting may\_detach\_mounts [moby/moby#35172](https://github.com/moby/moby/pull/35172)

* Fix panic on get container pid when live restore containers [moby/moby#35157](https://github.com/moby/moby/pull/35157)
* Mask `/proc/scsi` path for containers to prevent removal of devices (CVE-2017-16539) [moby/moby#35399](https://github.com/moby/moby/pull/35399)

- Update to <github.com/vbatts/tar-split@v0.10.2> (CVE-2017-14992) [moby/moby#35424](https://github.com/moby/moby/pull/35424)

### [Swarm Mode](#swarm-mode)

* Modifying integration test due to new ipam options in swarmkit [moby/moby#35103](https://github.com/moby/moby/pull/35103)

- Fix deadlock on getting swarm info [moby/moby#35388](https://github.com/moby/moby/pull/35388)

* Expand the scope of the `Err` field in `TaskStatus` to also cover non-terminal errors that block the task from progressing [docker/swarmkit#2287](https://github.com/docker/swarmkit/pull/2287)

### [Packaging](#packaging)

* Build packages for Debian 10 (Buster) [docker/docker-ce-packaging#50](https://github.com/docker/docker-ce-packaging/pull/50)
* Build packages for Ubuntu 17.10 (Artful) [docker/docker-ce-packaging#55](https://github.com/docker/docker-ce-packaging/pull/55)

----
url: https://docs.docker.com/guides/testcontainers-java-service-configuration/
----

# Configuration of services running in a container

Table of contents

***

Learn how to initialize and configure Docker containers for testing by copying files into containers and executing commands inside them.

**Time to complete** 15 minutes

In this guide, you will learn how to:

* Initialize containers by copying files into them
* Run commands inside running containers using `execInContainer()`
* Set up a PostgreSQL database with SQL scripts
* Create AWS S3 buckets in LocalStack containers

## [Prerequisites](#prerequisites)

* Java 17+
* Your preferred IDE
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Copy files](https://docs.docker.com/guides/testcontainers-java-service-configuration/copy-files/)

   Initialize containers by copying files into specific locations.

2. [Execute commands](https://docs.docker.com/guides/testcontainers-java-service-configuration/exec-in-container/)

   Run commands inside running containers to initialize services for testing.

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/namespace-access/
----

# Namespace access control

***

Table of contents

***

Subscription: Business

For: Administrators

Namespace access control lets organization administrators control whether all members of an organization can push content to their personal namespaces on Docker Hub. This prevents organizations from accidentally publishing images outside of approved, governed locations.

When namespace access control is enabled, organization members can still view and pull images from their personal namespaces and continue accessing all existing repositories and content. However, they're unable to create new repositories or push new images to their personal namespace.

> Important
>
> For users in multiple organizations, if namespace access control is enabled in any organization, that user cannot push to their personal namespace and cannot create new repositories in their personal namespace.

### [Configure namespace access control](#configure-namespace-access-control)

To configure namespace access control:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down.
2. Select **Admin Console**, then **Namespace access**.
3. Use the toggle to enable or disable namespace access control.
4. Select **Save changes**.

Once namespace access control is enabled, organization members can still view their personal namespace and existing repositories but they are not able to create any new repositories or push any new images to existing repositories.

### [Verify access restrictions](#verify-access-restrictions)

After configuring namespace access control, test that restrictions work correctly.

After any attempt to push to an existing repository in your personal namespace, you'll see an error message like the following:

```console
$ docker push <personal-namespace>/<image>:<tag>
Unavailable
authentication required - namespace access restriction from an organization you belong to prevents pushing new content in your personal namespace. Restriction applied by: <organizations>. Please contact your organization administrator
```

----
url: https://docs.docker.com/reference/api/extensions-sdk/NavigationIntents/
----

# Interface: NavigationIntents

***

Table of contents

***

**`Since`**

0.2.0

## [Container Methods](#container-methods)

### [viewContainers](#viewcontainers)

▸ **viewContainers**(): `Promise`<`void`>

Navigate to the **Containers** tab in Docker Desktop.

```typescript
ddClient.desktopUI.navigate.viewContainers()
```

#### [Returns](#returns)

`Promise`<`void`>

***

### [viewContainer](#viewcontainer)

▸ **viewContainer**(`id`): `Promise`<`void`>

Navigate to the **Container** tab in Docker Desktop.

```typescript
await ddClient.desktopUI.navigate.viewContainer(id)
```

#### [Parameters](#parameters)

| Name | Type     | Description                                                                                                                                                                                            |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |

#### [Returns](#returns-1)

`Promise`<`void`>

A promise that fails if the container doesn't exist.

***

### [viewContainerLogs](#viewcontainerlogs)

▸ **viewContainerLogs**(`id`): `Promise`<`void`>

Navigate to the **Container logs** tab in Docker Desktop.

```typescript
await ddClient.desktopUI.navigate.viewContainerLogs(id)
```

#### [Parameters](#parameters-1)

| Name | Type     | Description                                                                                                                                                                                            |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |

#### [Returns](#returns-2)

`Promise`<`void`>

A promise that fails if the container doesn't exist.

***

### [viewContainerInspect](#viewcontainerinspect)

▸ **viewContainerInspect**(`id`): `Promise`<`void`>

Navigate to the **Inspect container** view in Docker Desktop.

```typescript
await ddClient.desktopUI.navigate.viewContainerInspect(id)
```

#### [Parameters](#parameters-2)

| Name | Type     | Description                                                                                                                                                                                            |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |

#### [Returns](#returns-3)

`Promise`<`void`>

A promise that fails if the container doesn't exist.

***

### [viewContainerTerminal](#viewcontainerterminal)

▸ **viewContainerTerminal**(`id`): `Promise`<`void`>

Navigate to the container terminal window in Docker Desktop.

```typescript
await ddClient.desktopUI.navigate.viewContainerTerminal(id)
```

**`Since`**

0.3.4

#### [Parameters](#parameters-3)

| Name | Type     | Description                                                                                                                                                                                            |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |

#### [Returns](#returns-4)

`Promise`<`void`>

A promise that fails if the container doesn't exist.

***

### [viewContainerStats](#viewcontainerstats)

▸ **viewContainerStats**(`id`): `Promise`<`void`>

Navigate to the container stats to see the CPU, memory, disk read/write and network I/O usage.

```typescript
await ddClient.desktopUI.navigate.viewContainerStats(id)
```

#### [Parameters](#parameters-4)

| Name | Type     | Description                                                                                                                                                                                            |
| ---- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | The full container id, e.g. `46b57e400d801762e9e115734bf902a2450d89669d85881058a46136520aca28`. You can use the `--no-trunc` flag as part of the `docker ps` command to display the full container id. |

#### [Returns](#returns-5)

`Promise`<`void`>

A promise that fails if the container doesn't exist.

***

## [Images Methods](#images-methods)

### [viewImages](#viewimages)

▸ **viewImages**(): `Promise`<`void`>

Navigate to the **Images** tab in Docker Desktop.

```typescript
await ddClient.desktopUI.navigate.viewImages()
```

#### [Returns](#returns-6)

`Promise`<`void`>

***

### [viewImage](#viewimage)

▸ **viewImage**(`id`, `tag`): `Promise`<`void`>

Navigate to a specific image referenced by `id` and `tag` in Docker Desktop. In this navigation route you can find the image layers, commands, created time and size.

```typescript
await ddClient.desktopUI.navigate.viewImage(id, tag)
```

#### [Parameters](#parameters-5)

| Name  | Type     | Description                                                                                                        |
| ----- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `id`  | `string` | The full image id (including sha), e.g. `sha256:34ab3ae068572f4e85c448b4035e6be5e19cc41f69606535cd4d768a63432673`. |
| `tag` | `string` | The tag of the image, e.g. `latest`, `0.0.1`, etc.                                                                 |

#### [Returns](#returns-7)

`Promise`<`void`>

A promise that fails if the image doesn't exist.

***

## [Volume Methods](#volume-methods)

### [viewVolumes](#viewvolumes)

▸ **viewVolumes**(): `Promise`<`void`>

Navigate to the **Volumes** tab in Docker Desktop.

```typescript
ddClient.desktopUI.navigate.viewVolumes()
```

#### [Returns](#returns-8)

`Promise`<`void`>

***

### [viewVolume](#viewvolume)

▸ **viewVolume**(`volume`): `Promise`<`void`>

Navigate to a specific volume in Docker Desktop.

```typescript
await ddClient.desktopUI.navigate.viewVolume(volume)
```

#### [Parameters](#parameters-6)

| Name     | Type     | Description                               |
| -------- | -------- | ----------------------------------------- |
| `volume` | `string` | The name of the volume, e.g. `my-volume`. |

#### [Returns](#returns-9)

`Promise`<`void`>

----
url: https://docs.docker.com/docker-hub/repos/manage/builds/link-source/
----

# Configure automated builds from GitHub and BitBucket

***

Table of contents

***

> Warning
>
> Docker Hub Automated Builds is a deprecated feature. It will be fully retired on April 1, 2027.

> Note
>
> Automated builds require a Docker Pro, Team, or Business subscription.

To automate building and testing of your images, you link to your hosted source code service to Docker Hub so that it can access your source code repositories. You can configure this link for user accounts or organizations.

If you are linking a source code provider to create autobuilds for a team, follow the instructions to [create a service account](https://docs.docker.com/docker-hub/repos/manage/builds/setup/#service-users-for-team-autobuilds) for the team before linking the account as described below.

## [Link to a GitHub user account](#link-to-a-github-user-account)

1. Sign in to Docker Hub.

2. Select **My Hub** > **Settings** > **Linked accounts**.

3. Select **Link provider** for the source provider you want to link.

   If you want to unlink your current GitHub account and relink to a new GitHub account, make sure to completely sign out of [GitHub](https://github.com/) before linking via Docker Hub.

4. Review the settings for the **Docker Hub Builder** OAuth application.

   > Note
   >
   > If you are the owner of any GitHub organizations, you might see options to grant Docker Hub access to them from this screen. You can also individually edit an organization's third-party access settings to grant or revoke Docker Hub's access. See [Grant access to a GitHub organization](https://docs.docker.com/docker-hub/repos/manage/builds/link-source/#grant-access-to-a-github-organization) to learn more.

5. Select **Authorize docker** to save the link.

### [Grant access to a GitHub organization](#grant-access-to-a-github-organization)

If you are the owner of a GitHub organization, you can grant or revoke Docker Hub's access to the organization's repositories. Depending on the GitHub organization's settings, you may need to be an organization owner.

If the organization has not had specific access granted or revoked before, you can often grant access at the same time as you link your user account. In this case, a **Grant access** button appears next to the organization name in the link accounts screen, as shown below. If this button does not appear, you must manually grant the application's access.

To manually grant Docker Hub access to a GitHub organization:

1. Link your user account using the instructions above.

2. From your GitHub Account settings, locate the **Organization settings** section at the lower left.

3. Select the organization you want to give Docker Hub access to.

4. Select **Third-party access**.

   The page displays a list of third party applications and their access status.

5. Select the pencil icon next to **Docker Hub Builder**.

6. Select **Grant access** next to the organization.

### [Revoke access to a GitHub organization](#revoke-access-to-a-github-organization)

To revoke Docker Hub's access to an organization's GitHub repositories:

1. From your GitHub Account settings, locate the **Organization settings** section at the lower left.

2. Select the organization you want to revoke Docker Hub's access to.

3. From the Organization Profile menu, select **Third-party access**. The page displays a list of third party applications and their access status.

4. Select the pencil icon next to Docker Hub Builder.

5. On the next page, select **Deny access**.

### [Unlink a GitHub user account](#unlink-a-github-user-account)

To revoke Docker Hub's access to your GitHub account, you must unlink it both from Docker Hub, and from your GitHub account.

1. Select **My Hub** > **Settings** > **Linked accounts**.

2. Select **Unlink provider** next to the source provider you want to remove.

3. Go to your GitHub account's **Settings** page.

4. Select **Applications** in the left navigation bar.

5. Select the `...` menu to the right of the Docker Hub Builder application and select **Revoke**.

> Note
>
> Each repository that is configured as an automated build source contains a webhook that notifies Docker Hub of changes in the repository. This webhook is not automatically removed when you revoke access to a source code provider.

## [Link to a Bitbucket user account](#link-to-a-bitbucket-user-account)

1. Sign in to Docker Hub using your Docker ID.

2. Select **My Hub** > **Settings** > **Linked accounts**.

3. Select **Link provider** for the source provider you want to link.

4. If necessary, sign in to Bitbucket.

5. On the page that appears, select **Grant access**.

### [Unlink a Bitbucket user account](#unlink-a-bitbucket-user-account)

To permanently revoke Docker Hub's access to your Bitbucket account, you must unlink it both from Docker Hub, and revoke authorization in your Bitbucket account.

1. Sign in to Docker Hub.

2. Select **My Hub** > **Settings** > **Linked accounts**.

3. Select **Unlink provider** next to the source provider you want to remove.

> Important
>
> After unlinking the account on Docker Hub, you must also revoke the authorization on the Bitbucket end.

To revoke authorization in your Bitbucket account:

1. Go to your Bitbucket account and navigate to [**Bitbucket settings**](https://bitbucket.org/account/settings/app-authorizations/).

2. On the page that appears, select **OAuth**.

3. Select **Revoke** next to the Docker Hub line.

> Note
>
> Each repository that is configured as an automated build source contains a webhook that notifies Docker Hub of changes in the repository. This webhook is not automatically removed when you revoke access to a source code provider.

----
url: https://docs.docker.com/reference/cli/docker/buildx/du/
----

# docker buildx du

***

| Description | Disk usage         |
| ----------- | ------------------ |
| Usage       | `docker buildx du` |

## [Description](#description)

Disk usage

## [Options](#options)

| Option                  | Default | Description                                             |
| ----------------------- | ------- | ------------------------------------------------------- |
| [`--filter`](#filter)   |         | Provide filter values                                   |
| [`--format`](#format)   |         | Format the output                                       |
| `--timeout`             | `20s`   | Override the default timeout for loading builder status |
| [`--verbose`](#verbose) |         | Shorthand for `--format=pretty`                         |

## [Examples](#examples)

### [Show disk usage](#show-disk-usage)

The `docker buildx du` command shows the disk usage for the currently selected builder.

```console
$ docker buildx du
ID                                RECLAIMABLE    SIZE          LAST ACCESSED
12wgll9os87pazzft8lt0yztp*        true           1.704GB       13 days ago
iupsv3it5ubh92aweb7c1wojc*        true           1.297GB       36 minutes ago
ek4ve8h4obyv5kld6vicmtqyn         true           811.7MB       13 days ago
isovrfnmkelzhtdx942w9vjcb*        true           811.7MB       13 days ago
0jty7mjrndi1yo7xkv1baralh         true           810.5MB       13 days ago
jyzkefmsysqiaakgwmjgxjpcz*        true           810.5MB       13 days ago
z8w1y95jn93gvj92jtaj6uhwk         true           318MB         2 weeks ago
rz2zgfcwlfxsxd7d41w2sz2tt         true           8.224kB*      43 hours ago
n5bkzpewmk2eiu6hn9tzx18jd         true           8.224kB*      43 hours ago
ao94g6vtbzdl6k5zgdmrmnwpt         true           8.224kB*      43 hours ago
2pyjep7njm0wh39vcingxb97i         true           8.224kB*      43 hours ago
Shared:        115.5MB
Private:       10.25GB
Reclaimable:   10.36GB
Total:         10.36GB
```

If `RECLAIMABLE` is false, the `docker buildx du prune` command won't delete the record, even if you use `--all`. That's because the record is actively in use by some component of the builder.

The asterisks (\*) in the default output format indicate the following:

* An asterisk next to an ID (`zu7m6evdpebh5h8kfkpw9dlf2*`) indicates that the record is mutable. The size of the record may change, or another build can take ownership of it and change or commit to it. If you run the `du` command again, this item may not be there anymore, or the size might be different.
* An asterisk next to a size (`8.288kB*`) indicates that the record is shared. Storage of the record is shared with some other resource, typically an image. If you prune such a record then you will lose build cache but only metadata will be deleted as the image still needs to actual storage layers.

### [Provide filter values (--filter)](#filter)

Same as [`buildx prune --filter`](/reference/cli/docker/buildx/prune/#filter).

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints usage information output using a Go template.

Valid placeholders for the Go template are:

* `.ID`
* `.Parents`
* `.CreatedAt`
* `.Mutable`
* `.Reclaimable`
* `.Shared`
* `.Size`
* `.Description`
* `.UsageCount`
* `.LastUsedAt`
* `.Type`

When using the `--format` option, the `du` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The `pretty` format is useful for inspecting the disk usage records in more detail. It shows the mutable and shared states more clearly, as well as additional information about the corresponding layer:

```console
$ docker buildx du --format=pretty
...
ID:           6wqu0v6hjdwvhh8yjozrepaof
Parents:
 - bqx15bcewecz4wcg14b7iodvp
Created at:   2025-06-12 15:44:02.715795569 +0000 UTC
Mutable:      false
Reclaimable:  true
Shared:       true
Size:         1.653GB
Description:  [build-base 4/4] COPY . .
Usage count:  1
Last used:    2 months ago
Type:         regular

Shared:         35.57GB
Private:        97.94GB
Reclaimable:    131.5GB
Total:          133.5GB
```

The following example uses a template without headers and outputs the `ID` and `Size` entries separated by a colon (`:`):

```console
$ docker buildx du --format "{{.ID}}: {{.Size}}"
6wqu0v6hjdwvhh8yjozrepaof: 1.653GB
4m8061kctvjyh9qleus8rgpgx: 1.723GB
fcm9mlz2641u8r5eicjqdhy1l: 1.841GB
z2qu1swvo3afzd9mhihi3l5k0: 1.873GB
nmi6asc00aa3ja6xnt6o7wbrr: 2.027GB
0qlam41jxqsq6i27yqllgxed3: 2.495GB
3w9qhzzskq5jc262snfu90bfz: 2.617GB
```

The following example uses a `table` template and outputs the `ID` and `Description`:

```console
$ docker buildx du --format "table {{.ID}}    {{.Description}}"
ID                           DESCRIPTION
03bbhchaib8cygqs68um6hfnl    [binaries-linux 2/5] LINK COPY --link --from=binfmt-filter /out/ /
2h8un0tyg57oj64xvbas6mzea    [cni-plugins-export 2/4] LINK COPY --link --from=cni-plugins /opt/cni/bin/loopback /buildkit-cni-loopback
evckox33t07ob9dmollhn4h4j    [cni-plugins-export 3/4] LINK COPY --link --from=cni-plugins /opt/cni/bin/host-local /buildkit-cni-host-local
jlxzwcw6xaomxj8irerow9bhb    [binaries-linux 4/5] LINK COPY --link --from=buildctl /usr/bin/buildctl /
ov2oetgebkhpsw39rv1sbh5w1    [buildkit-linux 1/1] LINK COPY --link --from=binaries / /usr/bin/
ruoczhyq25n5v9ld7n231zalx    [binaries-linux 3/5] LINK COPY --link --from=cni-plugins-export-squashed / /
ax7cov6kizxi9ufvcwsef4occ*   local source for context
```

JSON output is also supported and will print as newline delimited JSON:

```console
$ docker buildx du --format=json
{"CreatedAt":"2025-07-29T12:36:01Z","Description":"pulled from docker.io/library/rust:1.85.1-bookworm@sha256:e51d0265072d2d9d5d320f6a44dde6b9ef13653b035098febd68cce8fa7c0bc4","ID":"ic1gfidvev5nciupzz53alel4","LastUsedAt":"2025-07-29T12:36:01Z","Mutable":false,"Parents":["hmpdhm4sjrfpmae4xm2y3m0ra"],"Reclaimable":true,"Shared":false,"Size":"829889526","Type":"regular","UsageCount":1}
{"CreatedAt":"2025-08-05T09:24:09Z","Description":"pulled from docker.io/library/node:22@sha256:3218f0d1b9e4b63def322e9ae362d581fbeac1ef21b51fc502ef91386667ce92","ID":"jsw7fx09l5zsda3bri1z4mwk5","LastUsedAt":"2025-08-05T09:24:09Z","Mutable":false,"Parents":["098jsj5ebbv1w47ikqigeuurs"],"Reclaimable":true,"Shared":true,"Size":"829898832","Type":"regular","UsageCount":1}
```

You can use `jq` to pretty-print the JSON output:

```console
$ docker buildx du --format=json | jq .
{
  "CreatedAt": "2025-07-29T12:36:01Z",
  "Description": "pulled from docker.io/library/rust:1.85.1-bookworm@sha256:e51d0265072d2d9d5d320f6a44dde6b9ef13653b035098febd68cce8fa7c0bc4",
  "ID": "ic1gfidvev5nciupzz53alel4",
  "LastUsedAt": "2025-07-29T12:36:01Z",
  "Mutable": false,
  "Parents": [
    "hmpdhm4sjrfpmae4xm2y3m0ra"
  ],
  "Reclaimable": true,
  "Shared": false,
  "Size": "829889526",
  "Type": "regular",
  "UsageCount": 1
}
{
  "CreatedAt": "2025-08-05T09:24:09Z",
  "Description": "pulled from docker.io/library/node:22@sha256:3218f0d1b9e4b63def322e9ae362d581fbeac1ef21b51fc502ef91386667ce92",
  "ID": "jsw7fx09l5zsda3bri1z4mwk5",
  "LastUsedAt": "2025-08-05T09:24:09Z",
  "Mutable": false,
  "Parents": [
    "098jsj5ebbv1w47ikqigeuurs"
  ],
  "Reclaimable": true,
  "Shared": true,
  "Size": "829898832",
  "Type": "regular",
  "UsageCount": 1
}
```

### [Use verbose output (--verbose)](#verbose)

Shorthand for [`--format=pretty`](#format):

```console
$ docker buildx du --verbose
...
ID:           6wqu0v6hjdwvhh8yjozrepaof
Parents:
 - bqx15bcewecz4wcg14b7iodvp
Created at:   2025-06-12 15:44:02.715795569 +0000 UTC
Mutable:      false
Reclaimable:  true
Shared:       true
Size:         1.653GB
Description:  [build-base 4/4] COPY . .
Usage count:  1
Last used:    2 months ago
Type:         regular

Shared:         35.57GB
Private:        97.94GB
Reclaimable:    131.5GB
Total:          133.5GB
```

### [Override the configured builder instance (--builder)](#builder)

Use the `--builder` flag to inspect the disk usage of a particular builder.

```console
$ docker buildx du --builder mybuilder
ID                                RECLAIMABLE    SIZE          LAST ACCESSED
g41agepgdczekxg2mtw0dujsv*        true           1.312GB       47 hours ago
e6ycrsa0bn9akigqgzu0sc6kr         true           318MB         47 hours ago
our9zg4ndly65ze1ccczdksiz         true           204.9MB       45 hours ago
b7xv3xpxnwupc81tc9ya3mgq6*        true           120.6MB       47 hours ago
zihgye15ss6vum3wmck9egdoy*        true           79.81MB       2 days ago
aaydharssv1ug98yhuwclkfrh*        true           79.81MB       2 days ago
ta1r4vmnjug5dhub76as4kkol*        true           74.51MB       47 hours ago
murma9f83j9h8miifbq68udjf*        true           74.51MB       47 hours ago
47f961866a49g5y8myz80ixw1*        true           74.51MB       47 hours ago
tzh99xtzlaf6txllh3cobag8t         true           74.49MB       47 hours ago
ld6laoeuo1kwapysu6afwqybl*        true           59.89MB       47 hours ago
yitxizi5kaplpyomqpos2cryp*        true           59.83MB       47 hours ago
iy8aa4b7qjn0qmy9wiga9cj8w         true           33.65MB       47 hours ago
mci7okeijyp8aqqk16j80dy09         true           19.86MB       47 hours ago
lqvj091he652slxdla4wom3pz         true           14.08MB       47 hours ago
fkt31oiv793nd26h42llsjcw7*        true           11.87MB       2 days ago
uj802yxtvkcjysnjb4kgwvn2v         true           11.68MB       45 hours ago
Reclaimable:    2.627GB
Total:          2.627GB
```

----
url: https://docs.docker.com/reference/cli/sbx/diagnose/
----

# sbx diagnose

| Description | Diagnose common issues with your sbx installation |
| ----------- | ------------------------------------------------- |
| Usage       | `sbx diagnose`                                    |

## [Options](#options)

| Option         | Default | Description                             |
| -------------- | ------- | --------------------------------------- |
| `-o, --output` |         | Output format: "json" or "github-issue" |
| `--upload`     |         | Upload diagnostics to Docker support    |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/reference/cli/docker/network/
----

# docker network

***

| Description | Manage networks  |
| ----------- | ---------------- |
| Usage       | `docker network` |

## [Description](#description)

Manage networks. You can use subcommands to create, inspect, list, remove, prune, connect, and disconnect networks.

## [Subcommands](#subcommands)

| Command                                                                                         | Description                                          |
| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [`docker network connect`](https://docs.docker.com/reference/cli/docker/network/connect/)       | Connect a container to a network                     |
| [`docker network create`](https://docs.docker.com/reference/cli/docker/network/create/)         | Create a network                                     |
| [`docker network disconnect`](https://docs.docker.com/reference/cli/docker/network/disconnect/) | Disconnect a container from a network                |
| [`docker network inspect`](https://docs.docker.com/reference/cli/docker/network/inspect/)       | Display detailed information on one or more networks |
| [`docker network ls`](https://docs.docker.com/reference/cli/docker/network/ls/)                 | List networks                                        |
| [`docker network prune`](https://docs.docker.com/reference/cli/docker/network/prune/)           | Remove all unused networks                           |
| [`docker network rm`](https://docs.docker.com/reference/cli/docker/network/rm/)                 | Remove one or more networks                          |

----
url: https://docs.docker.com/get-started/workshop/09_image_best/
----

# Image-building best practices

***

Table of contents

***

## [Image layering](#image-layering)

Using the `docker image history` command, you can see the command that was used to create each layer within an image.

1. Use the `docker image history` command to see the layers in the `getting-started` image you created.

   ```console
   $ docker image history getting-started
   ```

   You should get output that looks something like the following.

   ```plaintext
   IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
   a78a40cbf866        18 seconds ago      /bin/sh -c #(nop)  CMD ["node" "src/index.j…    0B                  
   f1d1808565d6        19 seconds ago      /bin/sh -c npm install --omit=dev               85.4MB              
   a2c054d14948        36 seconds ago      /bin/sh -c #(nop) COPY dir:5dc710ad87c789593…   198kB               
   9577ae713121        37 seconds ago      /bin/sh -c #(nop) WORKDIR /app                  0B                  
   b95baba1cfdb        13 days ago         /bin/sh -c #(nop)  CMD ["node"]                 0B                  
   <missing>           13 days ago         /bin/sh -c #(nop)  ENTRYPOINT ["docker-entry…   0B                  
   <missing>           13 days ago         /bin/sh -c #(nop) COPY file:238737301d473041…   116B                
   <missing>           13 days ago         /bin/sh -c apk add --no-cache --virtual .bui…   5.35MB              
   <missing>           13 days ago         /bin/sh -c addgroup -g 1000 node     && addu…   74.3MB              
   <missing>           13 days ago         /bin/sh -c #(nop)  ENV NODE_VERSION=12.14.1     0B                  
   <missing>           13 days ago         /bin/sh -c #(nop)  CMD ["/bin/sh"]              0B                  
   <missing>           13 days ago         /bin/sh -c #(nop) ADD file:e69d441d729412d24…   5.59MB   
   ```

   Each of the lines represents a layer in the image. The display here shows the base at the bottom with the newest layer at the top. Using this, you can also quickly see the size of each layer, helping diagnose large images.

2. You'll notice that several of the lines are truncated. If you add the `--no-trunc` flag, you'll get the full output.

   ```console
   $ docker image history --no-trunc getting-started
   ```

## [Layer caching](#layer-caching)

Now that you've seen the layering in action, there's an important lesson to learn to help decrease build times for your container images. Once a layer changes, all downstream layers have to be recreated as well.

Look at the following Dockerfile you created for the getting started app.

```dockerfile
# syntax=docker/dockerfile:1
FROM node:24-alpine
WORKDIR /app
COPY . .
RUN npm install --omit=dev
CMD ["node", "src/index.js"]
EXPOSE 3000
```

Going back to the image history output, you see that each command in the Dockerfile becomes a new layer in the image. You might remember that when you made a change to the image, the dependencies had to be reinstalled. It doesn't make much sense to ship around the same dependencies every time you build.

To fix it, you need to restructure your Dockerfile to help support the caching of the dependencies. For Node-based applications, those dependencies are defined in the `package.json` file. You can copy only that file in first, install the dependencies, and then copy in everything else. Then, you only recreate the dependencies if there was a change to the `package.json`.

1. Update the Dockerfile to copy in the `package.json` first, install dependencies, and then copy everything else in.

   ```dockerfile
   # syntax=docker/dockerfile:1
   FROM node:24-alpine
   WORKDIR /app
   COPY package.json package-lock.json ./
   RUN npm install --omit=dev
   COPY . .
   CMD ["node", "src/index.js"]
   ```

2. Build a new image using `docker build`.

   ```console
   $ docker build -t getting-started .
   ```

   You should see output like the following.

   ```plaintext
   [+] Building 16.1s (10/10) FINISHED
   => [internal] load build definition from Dockerfile
   => => transferring dockerfile: 175B
   => [internal] load .dockerignore
   => => transferring context: 2B
   => [internal] load metadata for docker.io/library/node:24-alpine
   => [internal] load build context
   => => transferring context: 53.37MB
   => [1/5] FROM docker.io/library/node:24-alpine
   => CACHED [2/5] WORKDIR /app
   => [3/5] COPY package.json package-lock.json ./
   => [4/5] RUN npm install --omit=dev
   => [5/5] COPY . .
   => exporting to image
   => => exporting layers
   => => writing image     sha256:d6f819013566c54c50124ed94d5e66c452325327217f4f04399b45f94e37d25
   => => naming to docker.io/library/getting-started
   ```

3. Now, make a change to the `src/static/index.html` file. For example, change the `<title>` to "The Awesome Todo App".

4. Build the Docker image now using `docker build -t getting-started .` again. This time, your output should look a little different.

   ```plaintext
   [+] Building 1.2s (10/10) FINISHED
   => [internal] load build definition from Dockerfile
   => => transferring dockerfile: 37B
   => [internal] load .dockerignore
   => => transferring context: 2B
   => [internal] load metadata for docker.io/library/node:24-alpine
   => [internal] load build context
   => => transferring context: 450.43kB
   => [1/5] FROM docker.io/library/node:24-alpine
   => CACHED [2/5] WORKDIR /app
   => CACHED [3/5] COPY package.json package-lock.json ./
   => CACHED [4/5] RUN npm install
   => [5/5] COPY . .
   => exporting to image
   => => exporting layers
   => => writing image     sha256:91790c87bcb096a83c2bd4eb512bc8b134c757cda0bdee4038187f98148e2eda
   => => naming to docker.io/library/getting-started
   ```

   First off, you should notice that the build was much faster. And, you'll see that several steps are using previously cached layers. Pushing and pulling this image and updates to it will be much faster as well.

## [Multi-stage builds](#multi-stage-builds)

Multi-stage builds are an incredibly powerful tool to help use multiple stages to create an image. There are several advantages for them:

* Separate build-time dependencies from runtime dependencies
* Reduce overall image size by shipping only what your app needs to run

### [Maven/Tomcat example](#maventomcat-example)

When building Java-based applications, you need a JDK to compile the source code to Java bytecode. However, that JDK isn't needed in production. Also, you might be using tools like Maven or Gradle to help build the app. Those also aren't needed in your final image. Multi-stage builds help.

```dockerfile
# syntax=docker/dockerfile:1
FROM maven AS build
WORKDIR /app
COPY . .
RUN mvn package

FROM tomcat
COPY --from=build /app/target/file.war /usr/local/tomcat/webapps 
```

In this example, you use one stage (called `build`) to perform the actual Java build using Maven. In the second stage (starting at `FROM tomcat`), you copy in files from the `build` stage. The final image is only the last stage being created, which can be overridden using the `--target` flag.

### [React example](#react-example)

When building React applications, you need a Node environment to compile the JS code (typically JSX), SASS stylesheets, and more into static HTML, JS, and CSS. If you aren't doing server-side rendering, you don't even need a Node environment for your production build. You can ship the static resources in a static nginx container.

```dockerfile
# syntax=docker/dockerfile:1
FROM node:24-alpine AS build
WORKDIR /app
COPY package* ./
RUN npm install
COPY public ./public
COPY src ./src
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/build /usr/share/nginx/html
```

In the previous Dockerfile example, it uses the `node:24-alpine` image to perform the build (maximizing layer caching) and then copies the output into an nginx container.

> Tips
>
> This React example is for illustration purposes. The getting-started todo app is a `Node.js` backend application, not a React frontend.

## [Summary](#summary)

In this section, you learned a few image building best practices, including layer caching and multi-stage builds.

Related information:

* [Dockerfile reference](/reference/dockerfile/)
* [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)

## [Next steps](#next-steps)

In the next section, you'll learn about additional resources you can use to continue learning about containers.

[What next](https://docs.docker.com/get-started/workshop/10_what_next/)

----
url: https://docs.docker.com/engine/network/packet-filtering-firewalls/
----

# Packet filtering and firewalls

***

Table of contents

***

On Linux, Docker creates firewall rules to implement network isolation, [port publishing](https://docs.docker.com/engine/network/port-publishing/) and filtering.

Because these rules are required for the correct functioning of Docker bridge networks, you should not modify the rules created by Docker.

This page describes options that control Docker's firewall rules to implement functionality including port publishing, and NAT/masquerading.

> Note
>
> Docker creates firewall rules for bridge networks.
>
> No rules are created for `ipvlan`, `macvlan` or `host` networking.

## [Firewall backend](#firewall-backend)

By default, Docker Engine creates its firewall rules using iptables, see [Docker with iptables](https://docs.docker.com/engine/network/firewall-iptables/). It also has support for nftables, see [Docker with nftables](https://docs.docker.com/engine/network/firewall-nftables/).

For bridge networks, iptables and nftables have the same functionality.

Docker Engine option `firewall-backend` can be used to select whether iptables or nftables is used. See [daemon configuration](https://docs.docker.com/reference/cli/dockerd/).

## [Docker on a router](#docker-on-a-router)

On Linux, Docker needs "IP Forwarding" enabled on the host. So, it enables the `sysctl` settings `net.ipv4.ip_forward` and `net.ipv6.conf.all.forwarding` if they are not already enabled when it starts. When it does that, it also configures the firewall to drop forwarded packets unless they are explicitly accepted.

When Docker sets the default forwarding policy to "drop", it will prevent your Docker host from acting as a router. This is the recommended setting when IP Forwarding is enabled, unless router functionality is required.

To stop Docker from setting the forwarding policy to "drop", include `"ip-forward-no-drop": true` in `/etc/docker/daemon.json`, or add option `--ip-forward-no-drop` to the `dockerd` command line.

> Note
>
> With the experimental nftables backend, Docker does not enable IP forwarding itself, and it will not create a default "drop" nftables policy. See [Migrating from iptables to nftables](https://docs.docker.com/engine/network/firewall-nftables/#migrating-from-iptables-to-nftables).

## [Prevent Docker from manipulating firewall rules](#prevent-docker-from-manipulating-firewall-rules)

Setting the `iptables` or `ip6tables` keys to `false` in [daemon configuration](https://docs.docker.com/reference/cli/dockerd/), will prevent Docker from creating most of its `iptables` or `nftables` rules. But, this option is not appropriate for most users, it is likely to break container networking for the Docker Engine.

For example, with Docker's firewalling disabled and no replacement rules, containers in bridge networks will not be able to access internet hosts by masquerading, but all of their ports will be accessible to hosts on the local network.

It is not possible to completely prevent Docker from creating firewall rules, and creating rules after-the-fact is extremely involved and beyond the scope of these instructions.

## [Integration with firewalld](#integration-with-firewalld)

If you are running Docker with the `iptables` or `ip6tables` options set to `true`, and [firewalld](https://firewalld.org) is enabled on your system, in addition to its usual iptables or nftables rules, Docker creates a `firewalld` zone called `docker`, with target `ACCEPT`.

All bridge network interfaces created by Docker (for example, `docker0`) are inserted into the `docker` zone.

Docker also creates a forwarding policy called `docker-forwarding` that allows forwarding from `ANY` zone to the `docker` zone.

## [Docker and ufw](#docker-and-ufw)

[Uncomplicated Firewall](https://launchpad.net/ufw) (ufw) is a frontend that ships with Debian and Ubuntu, and it lets you manage firewall rules. Docker and ufw use firewall rules in ways that make them incompatible with each other.

When you publish a container's ports using Docker, traffic to and from that container gets diverted before it goes through the ufw firewall settings. Docker routes container traffic in the `nat` table, which means that packets are diverted before it reaches the `INPUT` and `OUTPUT` chains that ufw uses. Packets are routed before the firewall rules can be applied, effectively ignoring your firewall configuration.

----
url: https://docs.docker.com/guides/bake/
----

[Mastering multi-platform builds, testing, and more with Docker Buildx Bake](https://docs.docker.com/guides/bake/)

Learn to automate Docker builds and testing with declarative configurations using Buildx Bake.

Go DevOps

30 minutes

[« Back to all guides](/guides/)

# Mastering multi-platform builds, testing, and more with Docker Buildx Bake

***

Table of contents

***

This guide demonstrates how to simplify and automate the process of building images, testing, and generating build artifacts using Docker Buildx Bake. By defining build configurations in a declarative `docker-bake.hcl` file, you can eliminate manual scripts and enable efficient workflows for complex builds, testing, and artifact generation.

## [Assumptions](#assumptions)

This guide assumes that you're familiar with:

* Docker
* [Buildx](https://docs.docker.com/build/concepts/overview/#buildx)
* [BuildKit](https://docs.docker.com/build/concepts/overview/#buildkit)
* [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/)
* [Multi-platform builds](https://docs.docker.com/build/building/multi-platform/)

## [Prerequisites](#prerequisites)

* You have a recent version of Docker installed on your machine.
* You have Git installed for cloning repositories.
* You're using the [containerd](https://docs.docker.com/desktop/features/containerd/) image store.

## [Introduction](#introduction)

This guide uses an example project to demonstrate how Docker Buildx Bake can streamline your build and test workflows. The repository includes both a Dockerfile and a `docker-bake.hcl` file, giving you a ready-to-use setup to try out Bake commands.

Start by cloning the example repository:

```bash
git clone https://github.com/dvdksn/bakeme.git
cd bakeme
```

The Bake file, `docker-bake.hcl`, defines the build targets in a declarative syntax, using targets and groups, allowing you to manage complex builds efficiently.

Here's what the Bake file looks like out-of-the-box:

```hcl
target "default" {
  target = "image"
  tags = [
    "bakeme:latest",
  ]
  attest = [
    "type=provenance,mode=max",
    "type=sbom",
  ]
  platforms = [
    "linux/amd64",
    "linux/arm64",
    "linux/riscv64",
  ]
}
```

The `target` keyword defines a build target for Bake. The `default` target defines the target to build when no specific target is specified on the command line. Here's a quick summary of the options for the `default` target:

* `target`: The target build stage in the Dockerfile.

* `tags`: Tags to assign to the image.

* `attest`: [Attestations](https://docs.docker.com/build/metadata/attestations/) to attach to the image.

  > Tip
  >
  > The attestations provide metadata such as build provenance, which tracks the source of the image's build, and an SBOM (Software Bill of Materials), useful for security audits and compliance.

* `platforms`: Platform variants to build.

To execute this build, run the following command in the root of the repository:

```console
$ docker buildx bake
```

With Bake, you avoid long, hard-to-remember command-line incantations, simplifying build configuration management by replacing manual, error-prone scripts with a structured configuration file.

For contrast, here's what this build command would look like without Bake:

```console
$ docker buildx build \
  --target=image \
  --tag=bakeme:latest \
  --provenance=true \
  --sbom=true \
  --platform=linux/amd64,linux/arm64,linux/riscv64 \
  .
```

## [Testing and linting](#testing-and-linting)

Bake isn't just for defining build configurations and running builds. You can also use Bake to run your tests, effectively using BuildKit as a task runner. Running your tests in containers is great for ensuring reproducible results. This section shows how to add two types of tests:

* Unit testing with `go test`.
* Linting for style violations with `golangci-lint`.

In Test-Driven Development (TDD) fashion, start by adding a new `test` target to the Bake file:

```hcl
target "test" {
  target = "test"
  output = ["type=cacheonly"]
}
```

> Tip
>
> Using `type=cacheonly` ensures that the build output is effectively discarded; the layers are saved to BuildKit's cache, but Buildx will not attempt to load the result to the Docker Engine's image store.
>
> For test runs, you don't need to export the build output — only the test execution matters.

To execute this Bake target, run `docker buildx bake test`. At this time, you'll receive an error indicating that the `test` stage does not exist in the Dockerfile.

```console
$ docker buildx bake test
[+] Building 1.2s (6/6) FINISHED
 => [internal] load local bake definitions
...
ERROR: failed to solve: target stage "test" could not be found
```

To satisfy this target, add the corresponding Dockerfile target. The `test` stage here is based on the same base stage as the build stage.

```dockerfile
FROM base AS test
RUN --mount=target=. \
    --mount=type=cache,target=/go/pkg/mod \
    go test .
```

> Tip
>
> The [`--mount=type=cache` directive](https://docs.docker.com/build/cache/optimize/#use-cache-mounts) caches Go modules between builds, improving build performance by avoiding the need to re-download dependencies. This shared cache ensures that the same dependency set is available across build, test, and other stages.

Now, running the `test` target with Bake will evaluate the unit tests for this project. If you want to verify that it works, you can make an arbitrary change to `main_test.go` to cause the test to fail.

Next, to enable linting, add another target to the Bake file, named `lint`:

```hcl
target "lint" {
  target = "lint"
  output = ["type=cacheonly"]
}
```

And in the Dockerfile, add the build stage. This stage will use the official `golangci-lint` image on Docker Hub.

> Tip
>
> Because this stage relies on executing an external dependency, it's generally a good idea to define the version you want to use as a build argument. This lets you manage version upgrades in the future by collocating dependency versions to the beginning of the Dockerfile.

```dockerfile
ARG GO_VERSION="1.23"
ARG GOLANGCI_LINT_VERSION="1.61"

#...

FROM golangci/golangci-lint:v${GOLANGCI_LINT_VERSION}-alpine AS lint
RUN --mount=target=.,rw \
    golangci-lint run
```

Lastly, to enable running both tests simultaneously, you can use the `groups` construct in the Bake file. A group can specify multiple targets to run with a single invocation.

```hcl
group "validate" {
  targets = ["test", "lint"]
}
```

Now, running both tests is as simple as:

```console
$ docker buildx bake validate
```

## [Building variants](#building-variants)

Sometimes you need to build more than one version of a program. The following example uses Bake to build separate "release" and "debug" variants of the program, using [matrices](https://docs.docker.com/build/bake/matrices/). Using matrices lets you run parallel builds with different configurations, saving time and ensuring consistency.

A matrix expands a single build into multiple builds, each representing a unique combination of matrix parameters. This means you can orchestrate Bake into building both the production and development build of your program in parallel, with minimal configuration changes.

The example project for this guide is set up to use a build-time option to conditionally enable debug logging and tracing capabilities.

* If you compile the program with `go build -tags="debug"`, the additional logging and tracing capabilities are enabled (development mode).
* If you build without the `debug` tag, the program is compiled with a default logger (production mode).

Update the Bake file by adding a matrix attribute which defines the variable combinations to build:

docker-bake.hcl

```diff
 target "default" {
+  matrix = {
+    mode = ["release", "debug"]
+  }
+  name = "image-${mode}"
   target = "image"
```

The `matrix` attribute defines the variants to build ("release" and "debug"). The `name` attribute defines how the matrix gets expanded into multiple distinct build targets. In this case, the matrix attribute expands the build into two workflows: `image-release` and `image-debug`, each using different configuration parameters.

Next, define a build argument named `BUILD_TAGS` which takes the value of the matrix variable.

docker-bake.hcl

```diff
   target = "image"
+  args = {
+    BUILD_TAGS = mode
+  }
   tags = [
```

You'll also want to change how the image tags are assigned to these builds. As written, both matrix paths would generate the same image tag names, and overwrite each other. Update the `tags` attribute use a conditional operator to set the tag depending on the matrix variable value.

docker-bake.hcl

```diff
   tags = [
-    "bakeme:latest",
+    mode == "release" ? "bakeme:latest" : "bakeme:dev"
   ]
```

* If `mode` is `release`, the tag name is `bakeme:latest`
* If `mode` is `debug`, the tag name is `bakeme:dev`

Finally, update the Dockerfile to consume the `BUILD_TAGS` argument during the compilation stage. When the `-tags="${BUILD_TAGS}"` option evaluates to `-tags="debug"`, the compiler uses the `configureLogging` function in the [`debug.go`](https://github.com/dvdksn/bakeme/blob/75c8a41e613829293c4bd3fc3b4f0c573f458f42/debug.go#L1) file.

Dockerfile

```diff
 # build compiles the program
 FROM base AS build
-ARG TARGETOS TARGETARCH
+ARG TARGETOS TARGETARCH BUILD_TAGS
 ENV GOOS=$TARGETOS
 ENV GOARCH=$TARGETARCH
 RUN --mount=target=. \
        --mount=type=cache,target=/go/pkg/mod \
-       go build -o "/usr/bin/bakeme" .
+       go build -tags="${BUILD_TAGS}" -o "/usr/bin/bakeme" .
```

That's all. With these changes, your `docker buildx bake` command now builds two multi-platform image variants. You can introspect the canonical build configuration that Bake generates using the `docker buildx bake --print` command. Running this command shows that Bake will run a `default` group with two targets with different build arguments and image tags.

```json
{
  "group": {
    "default": {
      "targets": ["image-release", "image-debug"]
    }
  },
  "target": {
    "image-debug": {
      "attest": ["type=provenance,mode=max", "type=sbom"],
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "BUILD_TAGS": "debug"
      },
      "tags": ["bakeme:dev"],
      "target": "image",
      "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"]
    },
    "image-release": {
      "attest": ["type=provenance,mode=max", "type=sbom"],
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "BUILD_TAGS": "release"
      },
      "tags": ["bakeme:latest"],
      "target": "image",
      "platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"]
    }
  }
}
```

Factoring in all of the platform variants as well, this means that the build configuration generates 6 different images.

```console
$ docker buildx bake
$ docker image ls --tree

IMAGE                   ID             DISK USAGE   CONTENT SIZE   USED
bakeme:dev              f7cb5c08beac       49.3MB         28.9MB
├─ linux/riscv64        0eae8ba0367a       9.18MB         9.18MB
├─ linux/arm64          56561051c49a         30MB         9.89MB
└─ linux/amd64          e8ca65079c1f        9.8MB          9.8MB

bakeme:latest           20065d2c4d22       44.4MB         25.9MB
├─ linux/riscv64        7cc82872695f       8.21MB         8.21MB
├─ linux/arm64          e42220c2b7a3       27.1MB         8.93MB
└─ linux/amd64          af5b2dd64fde       8.78MB         8.78MB
```

## [Exporting build artifacts](#exporting-build-artifacts)

Exporting build artifacts like binaries can be useful for deploying to environments without Docker or Kubernetes. For example, if your programs are meant to be run on a user's local machine.

> Tip
>
> The techniques discussed in this section can be applied not only to build output like binaries, but to any type of artifacts, such as test reports.

With programming languages like Go and Rust where the compiled binaries are usually portable, creating alternate build targets for exporting only the binary is trivial. All you need to do is add an empty stage in the Dockerfile containing nothing but the binary that you want to export.

First, let's add a quick way to build a binary for your local platform and export it to `./build/local` on the local filesystem.

In the `docker-bake.hcl` file, create a new `bin` target. In this stage, set the `output` attribute to a local filesystem path. Buildx automatically detects that the output looks like a filepath, and exports the results to the specified path using the [local exporter](https://docs.docker.com/build/exporters/local-tar/).

```hcl
target "bin" {
  target = "bin"
  output = ["build/bin"]
  platforms = ["local"]
}
```

Notice that this stage specifies a `local` platform. By default, if `platforms` is unspecified, builds target the OS and architecture of the BuildKit host. If you're using Docker Desktop, this often means builds target `linux/amd64` or `linux/arm64`, even if your local machine is macOS or Windows, because Docker runs in a Linux VM. Using the `local` platform forces the target platform to match your local environment.

Next, add the `bin` stage to the Dockerfile which copies the compiled binary from the build stage.

```dockerfile
FROM scratch AS bin
COPY --from=build "/usr/bin/bakeme" /
```

Now you can export your local platform version of the binary with `docker buildx bake bin`. For example, on macOS, this build target generates an executable in the [Mach-O format](https://en.wikipedia.org/wiki/Mach-O) — the standard executable format for macOS.

```console
$ docker buildx bake bin
$ file ./build/bin/bakeme
./build/bin/bakeme: Mach-O 64-bit executable arm64
```

Next, let's add a target to build all of the platform variants of the program. To do this, you can [inherit](https://docs.docker.com/build/bake/inheritance/) the `bin` target that you just created, and extend it by adding the desired platforms.

```hcl
target "bin-cross" {
  inherits = ["bin"]
  platforms = [
    "linux/amd64",
    "linux/arm64",
    "linux/riscv64",
  ]
}
```

Now, building the `bin-cross` target creates binaries for all platforms. Subdirectories are automatically created for each variant.

```console
$ docker buildx bake bin-cross
$ tree build/
build/
└── bin
    ├── bakeme
    ├── linux_amd64
    │   └── bakeme
    ├── linux_arm64
    │   └── bakeme
    └── linux_riscv64
        └── bakeme

5 directories, 4 files
```

To also generate "release" and "debug" variants, you can use a matrix just like you did with the default target. When using a matrix, you also need to differentiate the output directory based on the matrix value, otherwise the binary gets written to the same location for each matrix run.

```hcl
target "bin-all" {
  inherits = ["bin-cross"]
  matrix = {
    mode = ["release", "debug"]
  }
  name = "bin-${mode}"
  args = {
    BUILD_TAGS = mode
  }
  output = ["build/bin/${mode}"]
}
```

```console
$ rm -r ./build/
$ docker buildx bake bin-all
$ tree build/
build/
└── bin
    ├── debug
    │   ├── linux_amd64
    │   │   └── bakeme
    │   ├── linux_arm64
    │   │   └── bakeme
    │   └── linux_riscv64
    │       └── bakeme
    └── release
        ├── linux_amd64
        │   └── bakeme
        ├── linux_arm64
        │   └── bakeme
        └── linux_riscv64
            └── bakeme

10 directories, 6 files
```

## [Conclusion](#conclusion)

Docker Buildx Bake streamlines complex build workflows, enabling efficient multi-platform builds, testing, and artifact export. By integrating Buildx Bake into your projects, you can simplify your Docker builds, make your build configuration portable, and wrangle complex configurations.

Experiment with different configurations and extend your Bake files to suit your project's needs. You might consider integrating Bake into your CI/CD pipelines to automate builds, testing, and artifact deployment. The flexibility and power of Buildx Bake can significantly improve your development and deployment processes.

### [Further reading](#further-reading)

For more information about how to use Bake, check out these resources:

* [Bake documentation](https://docs.docker.com/build/bake/)
* [Matrix targets](https://docs.docker.com/build/bake/matrices/)
* [Bake file reference](https://docs.docker.com/build/bake/reference/)
* [Bake GitHub Action](https://github.com/docker/bake-action)

----
url: https://docs.docker.com/reference/samples/spring/
----

# Spring Boot samples

| Name                                                                                             | Description                                                                                                                        |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| [React / Spring / MySQL](https://github.com/docker/awesome-compose/tree/master/react-java-mysql) | A sample React application with a Spring backend and a MySQL database.                                                             |
| [Spring / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/spring-postgres)     | A sample Java application with Spring framework and a Postgres database.                                                           |
| [atsea-sample-shop-app](https://github.com/dockersamples/atsea-sample-shop-app)                  | A sample app that uses a Java Spring Boot backend connected to a database to display a fictitious art shop with a React front-end. |

----
url: https://docs.docker.com/guides/testcontainers-java-wiremock/create-project/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Create the Spring Boot project

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Spring Boot project from [Spring Initializr](https://start.spring.io) by selecting the **Spring Web** and **Testcontainers** starters.

Alternatively, clone the [guide repository](https://github.com/testcontainers/tc-guide-testing-rest-api-integrations-using-wiremock).

After generating the project, add the **REST Assured**, **WireMock**, and **WireMock Testcontainers module** libraries as test dependencies. The key dependencies in `pom.xml` are:

```xml
<properties>
    <java.version>17</java.version>
    <testcontainers.version>2.0.4</testcontainers.version>
    <wiremock-testcontainers.version>1.0-alpha-13</wiremock-testcontainers.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.wiremock</groupId>
        <artifactId>wiremock-standalone</artifactId>
        <version>3.6.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.wiremock.integrations.testcontainers</groupId>
        <artifactId>wiremock-testcontainers-module</artifactId>
        <version>${wiremock-testcontainers.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

Using the Testcontainers BOM (Bill of Materials) is recommended so that you don't have to repeat the version for every Testcontainers module dependency.

This guide builds an application that manages video albums. A third-party REST API handles photo assets. For demonstration purposes, the application uses the publicly available [JSONPlaceholder](https://jsonplaceholder.typicode.com/) API as a photo service.

The application exposes a `GET /api/albums/{albumId}` endpoint that calls the photo service to fetch photos for a given album. [WireMock](https://wiremock.org/) is a tool for building mock APIs. Testcontainers provides a [WireMock module](https://testcontainers.com/modules/wiremock/) that runs WireMock as a Docker container.

## [Create the Album and Photo models](#create-the-album-and-photo-models)

Create `Album.java` using Java records:

```java
package com.testcontainers.demo;

import java.util.List;

public record Album(Long albumId, List<Photo> photos) {}

record Photo(Long id, String title, String url, String thumbnailUrl) {}
```

## [Create the PhotoServiceClient](#create-the-photoserviceclient)

Create `PhotoServiceClient.java`, which uses `RestTemplate` to fetch photos for a given album ID:

```java
package com.testcontainers.demo;

import java.util.List;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;

@Service
class PhotoServiceClient {

  private final String baseUrl;
  private final RestTemplate restTemplate;

  PhotoServiceClient(
    @Value("${photos.api.base-url}") String baseUrl,
    RestTemplateBuilder builder
  ) {
    this.baseUrl = baseUrl;
    this.restTemplate = builder.build();
  }

  List<Photo> getPhotos(Long albumId) {
    String url = baseUrl + "/albums/{albumId}/photos";
    ResponseEntity<List<Photo>> response = restTemplate.exchange(
      url,
      HttpMethod.GET,
      null,
      new ParameterizedTypeReference<>() {},
      albumId
    );
    return response.getBody();
  }
}
```

The photo service base URL is externalized as a configuration property. Add the following entry to `src/main/resources/application.properties`:

```properties
photos.api.base-url=https://jsonplaceholder.typicode.com
```

## [Create the REST API endpoint](#create-the-rest-api-endpoint)

Create `AlbumController.java`:

```java
package com.testcontainers.demo;

import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestClientResponseException;

@RestController
@RequestMapping("/api")
class AlbumController {

  private static final Logger logger = LoggerFactory.getLogger(
    AlbumController.class
  );

  private final PhotoServiceClient photoServiceClient;

  AlbumController(PhotoServiceClient photoServiceClient) {
    this.photoServiceClient = photoServiceClient;
  }

  @GetMapping("/albums/{albumId}")
  public ResponseEntity<Album> getAlbumById(@PathVariable Long albumId) {
    try {
      List<Photo> photos = photoServiceClient.getPhotos(albumId);
      return ResponseEntity.ok(new Album(albumId, photos));
    } catch (RestClientResponseException e) {
      logger.error("Failed to get photos", e);
      return new ResponseEntity<>(e.getStatusCode());
    }
  }
}
```

This endpoint calls the photo service for a given album ID and returns a response like:

```json
{
  "albumId": 1,
  "photos": [
    {
      "id": 51,
      "title": "non sunt voluptatem placeat consequuntur rem incidunt",
      "url": "https://via.placeholder.com/600/8e973b",
      "thumbnailUrl": "https://via.placeholder.com/150/8e973b"
    },
    {
      "id": 52,
      "title": "eveniet pariatur quia nobis reiciendis laboriosam ea",
      "url": "https://via.placeholder.com/600/121fa4",
      "thumbnailUrl": "https://via.placeholder.com/150/121fa4"
    }
  ]
}
```

[Write tests with WireMock and Testcontainers »](https://docs.docker.com/guides/testcontainers-java-wiremock/write-tests/)

----
url: https://docs.docker.com/reference/cli/docker/dhi/mirror/list/
----

# docker dhi mirror list

***

| Description | List all mirrored Docker Hardened Images |
| ----------- | ---------------------------------------- |
| Usage       | `docker dhi mirror list`                 |

## [Description](#description)

List all Docker Hardened Images currently being mirrored to your organization's registry.

Shows the source repositories, destination repositories, and mirroring status.

Examples:

# [List all mirrored repositories](#list-all-mirrored-repositories)

docker dhi mirror list --org myorg

# [List only image repositories](#list-only-image-repositories)

docker dhi mirror list --org myorg --type image

# [List only helm chart repositories](#list-only-helm-chart-repositories)

docker dhi mirror list --org myorg --type helm-chart

# [Search for a specific repository by name](#search-for-a-specific-repository-by-name)

docker dhi mirror list --org myorg --filter dhi-python

# [Output in JSON format](#output-in-json-format)

docker dhi mirror list --org myorg --json

## [Options](#options)

| Option         | Default | Description                                     |
| -------------- | ------- | ----------------------------------------------- |
| `-f, --filter` |         | Filter by repository name (partial match)       |
| `--json`       |         | Output in JSON format                           |
| `--type`       |         | Filter by repository type (image or helm-chart) |

----
url: https://docs.docker.com/reference/build-checks/secrets-used-in-arg-or-env/
----

# SecretsUsedInArgOrEnv

***

Table of contents

***

## [Output](#output)

```text
Potentially sensitive data should not be used in the ARG or ENV commands
```

## [Description](#description)

While it is common to pass secrets to running processes through environment variables during local development, setting secrets in a Dockerfile using `ENV` or `ARG` is insecure because they persist in the final image. This rule reports violations where `ENV` and `ARG` keys indicate that they contain sensitive data.

Instead of `ARG` or `ENV`, you should use secret mounts, which expose secrets to your builds in a secure manner, and do not persist in the final image or its metadata. See [Build secrets](https://docs.docker.com/build/building/secrets/).

## [Examples](#examples)

❌ Bad: using ARG to pass AWS credentials.

```dockerfile
ARG AWS_ACCESS_KEY_ID
ARG AWS_SECRET_ACCESS_KEY
RUN aws s3 cp s3://my-bucket/file .
```

✅ Good: using secret mounts with environment variables.

```dockerfile
RUN --mount=type=secret,id=aws_key_id,env=AWS_ACCESS_KEY_ID \
    --mount=type=secret,id=aws_secret_key,env=AWS_SECRET_ACCESS_KEY \
    aws s3 cp s3://my-bucket/file .
```

To build with these secrets:

```console
$ docker buildx build \
    --secret id=aws_key_id,env=AWS_ACCESS_KEY_ID \
    --secret id=aws_secret_key,env=AWS_SECRET_ACCESS_KEY .
```

----
url: https://docs.docker.com/ai/docker-agent/reference/cli/
----

***

Table of contents

***

Command-line interface for running, managing, and deploying AI agents.

For agent configuration file syntax, see the [Configuration file reference](https://docs.docker.com/ai/docker-agent/reference/config/). For toolset capabilities, see the [Toolsets reference](https://docs.docker.com/ai/docker-agent/reference/toolsets/).

## [Synopsis](#synopsis)

```console
$ docker agent [command] [flags]
```

## [Global flags](#global-flags)

Work with all commands:

| Flag            | Type    | Default | Description          |
| --------------- | ------- | ------- | -------------------- |
| `-d`, `--debug` | boolean | false   | Enable debug logging |
| `-o`, `--otel`  | boolean | false   | Enable OpenTelemetry |
| `--log-file`    | string  | -       | Debug log file path  |

Debug logs write to `~/.cagent/cagent.debug.log` by default. Override with `--log-file`.

## [Runtime flags](#runtime-flags)

Work with most commands. Supported commands link to this section.

| Flag                | Type    | Default | Description                          |
| ------------------- | ------- | ------- | ------------------------------------ |
| `--models-gateway`  | string  | -       | Models gateway address               |
| `--env-from-file`   | array   | -       | Load environment variables from file |
| `--code-mode-tools` | boolean | false   | Enable JavaScript tool orchestration |
| `--working-dir`     | string  | -       | Working directory for the session    |

Set `--models-gateway` via `CAGENT_MODELS_GATEWAY` environment variable.

## [Commands](#commands)

### [a2a](#a2a)

Expose agent via the Agent2Agent (A2A) protocol. Allows other A2A-compatible systems to discover and interact with your agent. Auto-selects an available port if not specified.

```console
$ docker agent serve a2a agent-file|registry-ref
```

> Note
>
> A2A support is experimental. Tool calls are handled internally and not exposed as separate ADK events. Some ADK features are not integrated.

Arguments:

* `agent-file|registry-ref` - Path to YAML or OCI registry reference (required)

Flags:

| Flag            | Type    | Default | Description       |
| --------------- | ------- | ------- | ----------------- |
| `-a`, `--agent` | string  | root    | Agent name        |
| `--port`        | integer | 0       | Port (0 = random) |

Supports [runtime flags](#runtime-flags).

Examples:

```console
$ docker agent serve a2a ./agent.yaml --port 8080
$ docker agent serve a2a agentcatalog/pirate --port 9000
```

### [acp](#acp)

Start agent as ACP (Agent Client Protocol) server on stdio for editor integration. See [ACP integration](https://docs.docker.com/ai/docker-agent/integrations/acp/) for setup guides.

```console
$ docker agent serve acp agent-file|registry-ref
```

Arguments:

* `agent-file|registry-ref` - Path to YAML or OCI registry reference (required)

Supports [runtime flags](#runtime-flags).

### [alias add](#alias-add)

Create alias for agent.

```console
$ docker agent alias add name target
```

Arguments:

* `name` - Alias name (required)
* `target` - Path to YAML or registry reference (required)

Examples:

```console
$ docker agent alias add dev ./dev-agent.yaml
$ docker agent alias add prod docker.io/user/prod-agent:latest
$ docker agent alias add default ./agent.yaml
```

Setting alias name to "default" lets you run `docker agent run` without arguments.

### [alias list](#alias-list)

List all aliases.

```console
$ docker agent alias list
$ docker agent alias ls
```

### [alias remove](#alias-remove)

Remove alias.

```console
$ docker agent alias remove name
$ docker agent alias rm name
```

Arguments:

* `name` - Alias name (required)

### [api](#api)

HTTP API server.

```console
$ docker agent serve api agent-file|agents-dir
```

Arguments:

* `agent-file|agents-dir` - Path to YAML or directory with agents (required)

Flags:

| Flag                 | Type    | Default    | Description                       |
| -------------------- | ------- | ---------- | --------------------------------- |
| `-l`, `--listen`     | string  | :8080      | Listen address                    |
| `-s`, `--session-db` | string  | session.db | Session database path             |
| `--pull-interval`    | integer | 0          | Auto-pull OCI ref every N minutes |

Supports [runtime flags](#runtime-flags).

Examples:

```console
$ docker agent serve api ./agent.yaml
$ docker agent serve api ./agents/ --listen :9000
$ docker agent serve api docker.io/user/agent --pull-interval 10
```

The `--pull-interval` flag works only with OCI references. Automatically pulls and reloads at the specified interval.

### [build](#build)

Build Docker image for agent.

```console
$ docker agent build agent-file|registry-ref [image-name]
```

Arguments:

* `agent-file|registry-ref` - Path to YAML or OCI registry reference (required)
* `image-name` - Docker image name (optional)

Flags:

| Flag         | Type    | Default | Description                |
| ------------ | ------- | ------- | -------------------------- |
| `--dry-run`  | boolean | false   | Print Dockerfile only      |
| `--push`     | boolean | false   | Push image after build     |
| `--no-cache` | boolean | false   | Build without cache        |
| `--pull`     | boolean | false   | Pull all referenced images |

Example:

```console
$ docker agent build ./agent.yaml myagent:latest
$ docker agent build ./agent.yaml --dry-run
```

### [catalog list](#catalog-list)

List catalog agents.

```console
$ docker agent catalog list [org]
```

Arguments:

* `org` - Organization name (optional, default: `agentcatalog`)

Queries Docker Hub for agent repositories.

### [debug config](#debug-config)

Show resolved agent configuration.

```console
$ docker agent debug config agent-file|registry-ref
```

Arguments:

* `agent-file|registry-ref` - Path to YAML or OCI registry reference (required)

Supports [runtime flags](#runtime-flags).

Shows canonical configuration in YAML after all processing and defaults.

### [debug toolsets](#debug-toolsets)

List agent tools.

```console
$ docker agent debug toolsets agent-file|registry-ref
```

Arguments:

* `agent-file|registry-ref` - Path to YAML or OCI registry reference (required)

Supports [runtime flags](#runtime-flags).

Lists all tools for each agent in the configuration.

### [eval](#eval)

Run evaluation tests.

```console
$ docker agent eval agent-file|registry-ref [eval-dir]
```

Arguments:

* `agent-file|registry-ref` - Path to YAML or OCI registry reference (required)
* `eval-dir` - Evaluation files directory (optional, default: `./evals`)

Supports [runtime flags](#runtime-flags).

### [exec](#exec)

Single message execution without TUI.

```console
$ docker agent exec agent-file|registry-ref [message|-]
```

Arguments:

* `agent-file|registry-ref` - Path to YAML or OCI registry reference (required)
* `message` - Prompt, or `-` for stdin (optional)

Same flags as [run](#run).

Supports [runtime flags](#runtime-flags).

Examples:

```console
$ docker agent exec ./agent.yaml
$ docker agent exec ./agent.yaml "Check for security issues"
$ echo "Instructions" | docker agent exec ./agent.yaml -
```

### [feedback](#feedback)

Submit feedback.

```console
$ docker agent feedback
```

Shows link to submit feedback.

### [mcp](#mcp)

MCP (Model Context Protocol) server on stdio. Exposes agents as tools to MCP clients. See [MCP integration](https://docs.docker.com/ai/docker-agent/integrations/mcp/) for setup guides.

```console
$ docker agent serve mcp agent-file|registry-ref
```

Arguments:

* `agent-file|registry-ref` - Path to YAML or OCI registry reference (required)

Supports [runtime flags](#runtime-flags).

Examples:

```console
$ docker agent serve mcp ./agent.yaml
$ docker agent serve mcp docker.io/user/agent:latest
```

### [new](#new)

Create agent configuration interactively.

```console
$ docker agent new [message...]
```

Flags:

| Flag               | Type    | Default | Description                     |
| ------------------ | ------- | ------- | ------------------------------- |
| `--model`          | string  | -       | Model as `provider/model`       |
| `--max-iterations` | integer | 0       | Maximum agentic loop iterations |

Supports [runtime flags](#runtime-flags).

Opens interactive TUI to configure and generate agent YAML.

### [pull](#pull)

Pull agent from OCI registry.

```console
$ docker agent share pull registry-ref
```

Arguments:

* `registry-ref` - OCI registry reference (required)

Flags:

| Flag      | Type    | Default | Description                 |
| --------- | ------- | ------- | --------------------------- |
| `--force` | boolean | false   | Pull even if already exists |

Example:

```console
$ docker agent share pull docker.io/user/agent:latest
```

Saves to local YAML file.

### [push](#push)

Push agent to OCI registry.

```console
$ docker agent share push agent-file registry-ref
```

Arguments:

* `agent-file` - Path to local YAML (required)
* `registry-ref` - OCI reference like `docker.io/user/agent:latest` (required)

Example:

```console
$ docker agent share push ./agent.yaml docker.io/myuser/myagent:latest
```

### [run](#run)

Interactive terminal UI for agent sessions.

```console
$ docker agent run [agent-file|registry-ref] [message|-]
```

Arguments:

* `agent-file|registry-ref` - Path to YAML or OCI registry reference (optional)
* `message` - Initial prompt, or `-` for stdin (optional)

Flags:

| Flag            | Type    | Default | Description                  |
| --------------- | ------- | ------- | ---------------------------- |
| `-a`, `--agent` | string  | root    | Agent name                   |
| `--yolo`        | boolean | false   | Auto-approve all tool calls  |
| `--attach`      | string  | -       | Attach image file            |
| `--model`       | array   | -       | Override model (repeatable)  |
| `--dry-run`     | boolean | false   | Initialize without executing |
| `--remote`      | string  | -       | Remote runtime address       |

Supports [runtime flags](#runtime-flags).

Examples:

```console
$ docker agent run ./agent.yaml
$ docker agent run ./agent.yaml "Analyze this codebase"
$ docker agent run ./agent.yaml --agent researcher
$ echo "Instructions" | docker agent run ./agent.yaml -
$ docker agent run
```

Running without arguments uses the default agent or a "default" alias if configured.

Shows interactive TUI in a terminal. Falls back to exec mode otherwise.

#### [Interactive commands](#interactive-commands)

TUI slash commands:

| Command    | Description                      |
| ---------- | -------------------------------- |
| `/exit`    | Exit                             |
| `/reset`   | Clear history                    |
| `/eval`    | Save conversation for evaluation |
| `/compact` | Compact conversation             |
| `/yolo`    | Toggle auto-approval             |

### [version](#version)

Print version information.

```console
$ docker agent version
```

Shows Docker Agent version and commit hash.

## [Environment variables](#environment-variables)

| Variable                       | Description                     |
| ------------------------------ | ------------------------------- |
| `CAGENT_MODELS_GATEWAY`        | Models gateway address          |
| `TELEMETRY_ENABLED`            | Telemetry control (set `false`) |
| `CAGENT_HIDE_TELEMETRY_BANNER` | Hide telemetry banner (set `1`) |
| `OTEL_EXPORTER_OTLP_ENDPOINT`  | OpenTelemetry endpoint          |

## [Model overrides](#model-overrides)

Override models specified in your configuration file using the `--model` flag.

Format: `[agent=]provider/model`

Without an agent name, the model applies to all agents. With an agent name, it applies only to that specific agent.

Apply to all agents:

```console
$ docker agent run ./agent.yaml --model gpt-5
$ docker agent run ./agent.yaml --model anthropic/claude-sonnet-4-5
```

Apply to specific agents only:

```console
$ docker agent run ./agent.yaml --model researcher=gpt-5
$ docker agent run ./agent.yaml --model "agent1=gpt-5,agent2=claude-sonnet-4-5"
```

Providers: `openai`, `anthropic`, `google`, `dmr`

Omit provider for automatic selection based on model name.

----
url: https://docs.docker.com/desktop/troubleshoot-and-support/faqs/linuxfaqs/
----

# FAQs for Docker Desktop for Linux

***

Table of contents

***

### [Why does Docker Desktop for Linux run a VM?](#why-does-docker-desktop-for-linux-run-a-vm)

Docker Desktop for Linux runs a Virtual Machine (VM) for the following reasons:

1. To ensure that Docker Desktop provides a consistent experience across platforms.

   During research, the most frequently cited reason for users wanting Docker Desktop for Linux was to ensure a consistent Docker Desktop experience with feature parity across all major operating systems. Utilizing a VM ensures that the Docker Desktop experience for Linux users will closely match that of Windows and macOS.

2. To make use of new kernel features.

   Because Docker controls the kernel and the OS inside the VM, Docker can roll these out to all users immediately, even to users who are intentionally sticking on an LTS version of their machine OS.

3. To enhance security.

   Container image vulnerabilities pose a security risk for the host environment. There is a large number of unofficial images that are not guaranteed to be verified for known vulnerabilities. Malicious users can push images to public registries and use different methods to trick users into pulling and running them. The VM approach mitigates this threat as any malware that gains root privileges is restricted to the VM environment without access to the host.

   Why not run rootless Docker? Although this has the benefit of superficially limiting access to the root user so everything looks safer in "top", it allows unprivileged users to gain `CAP_SYS_ADMIN` in their own user namespace and access kernel APIs which are not expecting to be used by unprivileged users, resulting in [vulnerabilities](https://www.openwall.com/lists/oss-security/2022/01/18/7).

4. To provide the benefits of feature parity and enhanced security, with minimal impact on performance.

   The VM utilized by Docker Desktop for Linux uses [`VirtioFS`](https://virtio-fs.gitlab.io), a shared file system that allows virtual machines to access a directory tree located on the host. Docker's internal benchmarking shows that with the right resource allocation to the VM, near native file system performance can be achieved with VirtioFS.

   As such, the default memory available to the VM in Docker Desktop for Linux is adjusted. You can tweak this setting to your specific needs by using the **Memory** slider within the **Settings** > **Resources** tab of Docker Desktop.

### [How do I enable file sharing?](#how-do-i-enable-file-sharing)

Docker Desktop for Linux uses [VirtioFS](https://virtio-fs.gitlab.io/) as the default (and currently only) mechanism to enable file sharing between the host and Docker Desktop VM.

In order not to require elevated privileges, without unnecessarily restricting operations on the shared files, Docker Desktop runs the file sharing service (`virtiofsd`) inside a user namespace (see `user_namespaces(7)`) with UID and GID mapping configured. As a result Docker Desktop relies on the host being configured to enable the current user to use subordinate ID delegation. For this to be true `/etc/subuid` (see `subuid(5)`) and `/etc/subgid` (see `subgid(5)`) must be present. Docker Desktop only supports subordinate ID delegation configured via files. Docker Desktop maps the current user ID and GID to 0 in the containers. It uses the first entry corresponding to the current user in `/etc/subuid` and `/etc/subgid` to set up mappings for IDs greater than 0 in the containers.

| ID in container | ID on host                                                                       |
| --------------- | -------------------------------------------------------------------------------- |
| 0 (root)        | ID of the user running Docker Desktop (e.g. 1000)                                |
| 1               | 0 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100000) |
| 2               | 1 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100001) |
| 3               | 2 + beginning of ID range specified in `/etc/subuid`/`/etc/subgid` (e.g. 100002) |
| ...             | ...                                                                              |

If `/etc/subuid` and `/etc/subgid` are missing, they need to be created. Both should contain entries in the form - `<username>:<start of id range>:<id range size>`. For example, to allow the current user to use IDs from 100 000 to 165 535:

```console
$ grep "$USER" /etc/subuid >> /dev/null 2&>1 || (echo "$USER:100000:65536" | sudo tee -a /etc/subuid)
$ grep "$USER" /etc/subgid >> /dev/null 2&>1 || (echo "$USER:100000:65536" | sudo tee -a /etc/subgid)
```

To verify the configs have been created correctly, inspect their contents:

```console
$ echo $USER
exampleuser
$ cat /etc/subuid
exampleuser:100000:65536
$ cat /etc/subgid
exampleuser:100000:65536
```

In this scenario if a shared file is `chown`ed inside a Docker Desktop container owned by a user with a UID of 1000, it shows up on the host as owned by a user with a UID of 100999. This has the unfortunate side effect of preventing easy access to such a file on the host. The problem is resolved by creating a group with the new GID and adding our user to it, or by setting a recursive ACL (see `setfacl(1)`) for folders shared with the Docker Desktop VM.

### [How do I use Docker SDKs with Docker Desktop for Linux?](#how-do-i-use-docker-sdks-with-docker-desktop-for-linux)

Docker Desktop for Linux uses a per-user socket located at `~/.docker/desktop/docker.sock` instead of the system-wide `/var/run/docker.sock`. The Docker CLI handles this automatically through the `desktop-linux` context, but Docker SDKs and other tools that connect directly to the Docker daemon also need the `DOCKER_HOST` environment variable set.

Without setting `DOCKER_HOST`, SDKs attempt to connect to `/var/run/docker.sock` and fail with an error like:

```text
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
```

To fix this, set the `DOCKER_HOST` environment variable before running your SDK-based application:

```console
export DOCKER_HOST=unix://$HOME/.docker/desktop/docker.sock
```

Or dynamically retrieve it from the `desktop-linux` context:

```console
export DOCKER_HOST=$(docker context inspect desktop-linux --format '{{ .Endpoints.docker.Host }}')
```

To make this permanent, add the export command to your shell profile (`~/.bashrc`, `~/.zshrc`, or similar):

```console
echo 'export DOCKER_HOST=unix://$HOME/.docker/desktop/docker.sock' >> ~/.bashrc
```

### [Where does Docker Desktop store Linux containers?](#where-does-docker-desktop-store-linux-containers)

Docker Desktop stores Linux containers and images in a single, large "disk image" file in the Linux filesystem. This is different from Docker on Linux, which usually stores containers and images in the `/var/lib/docker` directory on the host's filesystem.

#### [Where is the disk image file?](#where-is-the-disk-image-file)

To locate the disk image file, select **Settings** from the Docker Desktop Dashboard then **Advanced** from the **Resources** tab.

The **Advanced** tab displays the location of the disk image. It also displays the maximum size of the disk image and the actual space the disk image is consuming. Note that other tools might display space usage of the file in terms of the maximum file size, and not the actual file size.

##### [What if the file is too large?](#what-if-the-file-is-too-large)

If the disk image file is too large, you can:

Do not move the file directly in Finder as this can cause Docker Desktop to lose track of the file.

##### [How do I delete unnecessary containers and images?](#how-do-i-delete-unnecessary-containers-and-images)

Check whether you have any unnecessary containers and images. If your client and daemon API are running version 1.25 or later (use the `docker version` command on the client to check your client and daemon API versions), you can see the detailed space usage information by running:

```console
$ docker system df -v
```

Alternatively, to list images, run:

```console
$ docker image ls
```

To list containers, run:

```console
$ docker container ls -a
```

If there are lots of redundant objects, run the command:

```console
$ docker system prune
```

This command removes all stopped containers, unused networks, dangling images, and build cache.

It might take a few minutes to reclaim space on the host depending on the format of the disk image file:

* If the file is named `Docker.raw`: space on the host should be reclaimed within a few seconds.
* If the file is named `Docker.qcow2`: space will be freed by a background process after a few minutes.

Space is only freed when images are deleted. Space is not freed automatically when files are deleted inside running containers. To trigger a space reclamation at any point, run the command:

```console
$ docker run --privileged --pid=host docker/desktop-reclaim-space
```

Note that many tools report the maximum file size, not the actual file size. To query the actual size of the file on the host from a terminal, run:

```console
$ cd ~/.docker/desktop/vms/0/data
$ ls -klsh Docker.raw
2333548 -rw-r--r--@ 1 username  staff    64G Dec 13 17:42 Docker.raw
```

In this example, the actual size of the disk is `2333548` KB, whereas the maximum size of the disk is `64` GB.

##### [How do I reduce the maximum size of the file?](#how-do-i-reduce-the-maximum-size-of-the-file)

To reduce the maximum size of the disk image file:

1. From Docker Desktop Dashboard select **Settings** then **Advanced** from the **Resources** tab.

2. The **Disk image size** section contains a slider that allows you to change the maximum size of the disk image. Adjust the slider to set a lower limit.

3. Select **Apply**.

When you reduce the maximum size, the current disk image file is deleted, and therefore, all containers and images are lost.

----
url: https://docs.docker.com/enterprise/security/single-sign-on/faqs/domain-faqs/
----

# SSO domain FAQs

***

Table of contents

***

## [Can I add sub-domains?](#can-i-add-sub-domains)

Yes, you can add sub-domains to your SSO connection. All email addresses must use domains you've added to the connection. Verify that your DNS provider supports multiple TXT records for the same domain.

## [Do I need to keep the DNS TXT record permanently?](#do-i-need-to-keep-the-dns-txt-record-permanently)

You can remove the TXT record after one-time verification to add the domain. However, if your organization changes identity providers and needs to set up SSO again, you'll need to verify the domain again.

## [Can I verify the same domain for multiple organizations?](#can-i-verify-the-same-domain-for-multiple-organizations)

You can't verify the same domain for multiple organizations at the organization level. To verify one domain for multiple organizations, you must have a Docker Business subscription and create a company. Companies allow centralized management of organizations and domain verification at the company level.

----
url: https://docs.docker.com/reference/api/extensions-sdk/BackendV0/
----

# Interface: BackendV0

***

Table of contents

***

## [Container Methods](#container-methods)

### [execInContainer](#execincontainer)

▸ **execInContainer**(`container`, `cmd`): `Promise`<[`ExecResultV0`](https://docs.docker.com/reference/api/extensions-sdk/ExecResultV0/)>

Executes a command inside a container.

```typescript
const output = await window.ddClient.backend.execInContainer(container, cmd);

console.log(output);
```

> Warning
>
> It will be removed in a future version.

#### [Parameters](#parameters)

| Name        | Type     | Description                 |
| ----------- | -------- | --------------------------- |
| `container` | `string` | -                           |
| `cmd`       | `string` | The command to be executed. |

#### [Returns](#returns)

`Promise`<[`ExecResultV0`](https://docs.docker.com/reference/api/extensions-sdk/ExecResultV0/)>

***

## [HTTP Methods](#http-methods)

### [get](#get)

▸ **get**(`url`): `Promise`<`unknown`>

Performs an HTTP GET request to a backend service.

```typescript
window.ddClient.backend
 .get("/some/service")
 .then((value: any) => console.log(value));
```

> Warning
>
> It will be removed in a future version. Use [get](https://docs.docker.com/reference/api/extensions-sdk/HttpService/#get) instead.

#### [Parameters](#parameters-1)

| Name  | Type     | Description                     |
| ----- | -------- | ------------------------------- |
| `url` | `string` | The URL of the backend service. |

#### [Returns](#returns-1)

`Promise`<`unknown`>

***

### [post](#post)

▸ **post**(`url`, `data`): `Promise`<`unknown`>

Performs an HTTP POST request to a backend service.

```typescript
window.ddClient.backend
 .post("/some/service", { ... })
 .then((value: any) => console.log(value));
```

> Warning
>
> It will be removed in a future version. Use [post](https://docs.docker.com/reference/api/extensions-sdk/HttpService/#post) instead.

#### [Parameters](#parameters-2)

| Name   | Type     | Description                     |
| ------ | -------- | ------------------------------- |
| `url`  | `string` | The URL of the backend service. |
| `data` | `any`    | The body of the request.        |

#### [Returns](#returns-2)

`Promise`<`unknown`>

***

### [put](#put)

▸ **put**(`url`, `data`): `Promise`<`unknown`>

Performs an HTTP PUT request to a backend service.

```typescript
window.ddClient.backend
 .put("/some/service", { ... })
 .then((value: any) => console.log(value));
```

> Warning
>
> It will be removed in a future version. Use [put](https://docs.docker.com/reference/api/extensions-sdk/HttpService/#put) instead.

#### [Parameters](#parameters-3)

| Name   | Type     | Description                     |
| ------ | -------- | ------------------------------- |
| `url`  | `string` | The URL of the backend service. |
| `data` | `any`    | The body of the request.        |

#### [Returns](#returns-3)

`Promise`<`unknown`>

***

### [patch](#patch)

▸ **patch**(`url`, `data`): `Promise`<`unknown`>

Performs an HTTP PATCH request to a backend service.

```typescript
window.ddClient.backend
 .patch("/some/service", { ... })
 .then((value: any) => console.log(value));
```

> Warning
>
> It will be removed in a future version. Use [patch](https://docs.docker.com/reference/api/extensions-sdk/HttpService/#patch) instead.

#### [Parameters](#parameters-4)

| Name   | Type     | Description                     |
| ------ | -------- | ------------------------------- |
| `url`  | `string` | The URL of the backend service. |
| `data` | `any`    | The body of the request.        |

#### [Returns](#returns-4)

`Promise`<`unknown`>

***

### [delete](#delete)

▸ **delete**(`url`): `Promise`<`unknown`>

Performs an HTTP DELETE request to a backend service.

```typescript
window.ddClient.backend
 .delete("/some/service")
 .then((value: any) => console.log(value));
```

> Warning
>
> It will be removed in a future version. Use [delete](https://docs.docker.com/reference/api/extensions-sdk/HttpService/#delete) instead.

#### [Parameters](#parameters-5)

| Name  | Type     | Description                     |
| ----- | -------- | ------------------------------- |
| `url` | `string` | The URL of the backend service. |

#### [Returns](#returns-5)

`Promise`<`unknown`>

***

### [head](#head)

▸ **head**(`url`): `Promise`<`unknown`>

Performs an HTTP HEAD request to a backend service.

```typescript
window.ddClient.backend
 .head("/some/service")
 .then((value: any) => console.log(value));
```

> Warning
>
> It will be removed in a future version. Use [head](https://docs.docker.com/reference/api/extensions-sdk/HttpService/#head) instead.

#### [Parameters](#parameters-6)

| Name  | Type     | Description                     |
| ----- | -------- | ------------------------------- |
| `url` | `string` | The URL of the backend service. |

#### [Returns](#returns-6)

`Promise`<`unknown`>

***

### [request](#request)

▸ **request**(`config`): `Promise`<`unknown`>

Performs an HTTP request to a backend service.

```typescript
window.ddClient.backend
 .request({ url: "/url", method: "GET", headers: { 'header-key': 'header-value' }, data: { ... }})
 .then((value: any) => console.log(value));
```

> Warning
>
> It will be removed in a future version. Use [request](https://docs.docker.com/reference/api/extensions-sdk/HttpService/#request) instead.

#### [Parameters](#parameters-7)

| Name     | Type                                                                                       | Description                     |
| -------- | ------------------------------------------------------------------------------------------ | ------------------------------- |
| `config` | [`RequestConfigV0`](https://docs.docker.com/reference/api/extensions-sdk/RequestConfigV0/) | The URL of the backend service. |

#### [Returns](#returns-7)

`Promise`<`unknown`>

***

## [VM Methods](#vm-methods)

### [execInVMExtension](#execinvmextension)

▸ **execInVMExtension**(`cmd`): `Promise`<[`ExecResultV0`](https://docs.docker.com/reference/api/extensions-sdk/ExecResultV0/)>

Executes a command inside the backend container. If your extensions ships with additional binaries that should be run inside the backend container you can use the `execInVMExtension` function.

```typescript
const output = await window.ddClient.backend.execInVMExtension(
  `cliShippedInTheVm xxx`
);

console.log(output);
```

> Warning
>
> It will be removed in a future version. Use [exec](https://docs.docker.com/reference/api/extensions-sdk/ExtensionCli/#exec) instead.

#### [Parameters](#parameters-8)

| Name  | Type     | Description                 |
| ----- | -------- | --------------------------- |
| `cmd` | `string` | The command to be executed. |

#### [Returns](#returns-8)

`Promise`<[`ExecResultV0`](https://docs.docker.com/reference/api/extensions-sdk/ExecResultV0/)>

***

### [spawnInVMExtension](#spawninvmextension)

▸ **spawnInVMExtension**(`cmd`, `args`, `callback`): `void`

Returns a stream from the command executed in the backend container.

```typescript
window.ddClient.spawnInVMExtension(
  `cmd`,
  [`arg1`, `arg2`],
  (data: any, err: any) => {
    console.log(data.stdout, data.stderr);
    // Once the command exits we get the status code
    if (data.code) {
      console.log(data.code);
    }
  }
);
```

> Warning
>
> It will be removed in a future version.

#### [Parameters](#parameters-9)

| Name       | Type                                      | Description                                                                    |
| ---------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
| `cmd`      | `string`                                  | The command to be executed.                                                    |
| `args`     | `string`\[]                               | The arguments of the command to execute.                                       |
| `callback` | (`data`: `any`, `error`: `any`) => `void` | The callback function where to listen from the command output data and errors. |

#### [Returns](#returns-9)

`void`

----
url: https://docs.docker.com/reference/cli/docker/model/requests/
----

# docker model requests

***

| Description | Fetch requests+responses from Docker Model Runner |
| ----------- | ------------------------------------------------- |
| Usage       | `docker model requests [OPTIONS]`                 |

## [Description](#description)

Fetch requests+responses from Docker Model Runner

## [Options](#options)

| Option               | Default | Description                                                                       |
| -------------------- | ------- | --------------------------------------------------------------------------------- |
| `-f, --follow`       |         | Follow requests stream                                                            |
| `--include-existing` |         | Include existing requests when starting to follow (only available with --follow)  |
| `--model`            |         | Specify the model to filter requests                                              |

----
url: https://docs.docker.com/compose/how-tos/environment-variables/envvars/
----

# Configure pre-defined environment variables in Docker Compose

***

Table of contents

***

Docker Compose includes several pre-defined environment variables. It also inherits common Docker CLI environment variables, such as `DOCKER_HOST` and `DOCKER_CONTEXT`. See [Docker CLI environment variable reference](/reference/cli/docker/#environment-variables) for details.

This page explains how to set or change the following pre-defined environment variables:

* `COMPOSE_PROJECT_NAME`
* `COMPOSE_FILE`
* `COMPOSE_PROFILES`
* `COMPOSE_CONVERT_WINDOWS_PATHS`
* `COMPOSE_PATH_SEPARATOR`
* `COMPOSE_IGNORE_ORPHANS`
* `COMPOSE_REMOVE_ORPHANS`
* `COMPOSE_PARALLEL_LIMIT`
* `COMPOSE_ANSI`
* `COMPOSE_STATUS_STDOUT`
* `COMPOSE_ENV_FILES`
* `COMPOSE_DISABLE_ENV_FILE`
* `COMPOSE_MENU`
* `COMPOSE_EXPERIMENTAL`
* `COMPOSE_PROGRESS`

## [Methods to override](#methods-to-override)

| Method                                                                                                                   | Description                                  |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| [`.env` file](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/)                     | Located in the working directory.            |
| [Shell](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/#substitute-from-the-shell) | Defined in the host operating system shell.  |
| CLI                                                                                                                      | Passed with `--env` or `-e` flag at runtime. |

When changing or setting any environment variables, be aware of [Environment variable precedence](https://docs.docker.com/compose/how-tos/environment-variables/envvars-precedence/).

## [Configuration details](#configuration-details)

### [Project and file configuration](#project-and-file-configuration)

#### [COMPOSE\_PROJECT\_NAME](#compose_project_name)

Sets the project name. This value is prepended along with the service name to the container's name on startup.

For example, if your project name is `myapp` and it includes two services `db` and `web`, then Compose starts containers named `myapp-db-1` and `myapp-web-1` respectively.

Compose can set the project name in different ways. The level of precedence (from highest to lowest) for each method is as follows:

1. The `-p` command line flag
2. `COMPOSE_PROJECT_NAME`
3. The top-level `name:` variable from the config file (or the last `name:` from a series of config files specified using `-f`)
4. The `basename` of the project directory containing the config file (or containing the first config file specified using `-f`)
5. The `basename` of the current directory if no config file is specified

Project names must contain only lowercase letters, decimal digits, dashes, and underscores, and must begin with a lowercase letter or decimal digit. If the `basename` of the project directory or current directory violates this constraint, you must use one of the other mechanisms.

See also [using `-p` to specify a project name](/reference/cli/docker/compose/#use--p-to-specify-a-project-name).

#### [COMPOSE\_FILE](#compose_file)

Specifies the path to a Compose file. Specifying multiple Compose files is supported.

* Default behavior: If not provided, Compose looks for a file named `compose.yaml` in the current directory and, if not found, then Compose searches each parent directory recursively until a file by that name is found.

* When specifying multiple Compose files, the path separators are, by default, on:

  * Mac and Linux: `:` (colon)

  * Windows: `;` (semicolon) For example:

    ```console
    COMPOSE_FILE=compose.yaml:compose.prod.yaml
    ```

  The path separator can also be customized using [`COMPOSE_PATH_SEPARATOR`](#compose_path_separator).

See also [using `-f` to specify name and path of one or more Compose files](/reference/cli/docker/compose/#use--f-to-specify-the-name-and-path-of-one-or-more-compose-files).

#### [COMPOSE\_PROFILES](#compose_profiles)

Specifies one or more profiles to be enabled when `docker compose up` is run.

Services with matching profiles are started as well as any services for which no profile has been defined.

For example, calling `docker compose up` with `COMPOSE_PROFILES=frontend` selects services with the `frontend` profile as well as any services without a profile specified.

If specifying multiple profiles, use a comma as a separator.

The following example enables all services matching both the `frontend` and `debug` profiles and services without a profile.

```console
COMPOSE_PROFILES=frontend,debug
```

See also [Using profiles with Compose](https://docs.docker.com/compose/how-tos/profiles/) and the [`--profile` command-line option](/reference/cli/docker/compose/#use-profiles-to-enable-optional-services).

#### [COMPOSE\_PATH\_SEPARATOR](#compose_path_separator)

Specifies a different path separator for items listed in `COMPOSE_FILE`.

* Defaults to:

  * On macOS and Linux to `:`
  * On Windows to`;`

#### [COMPOSE\_ENV\_FILES](#compose_env_files)

Specifies which environment files Compose should use if `--env-file` isn't used.

When using multiple environment files, use a comma as a separator. For example:

```console
COMPOSE_ENV_FILES=.env.envfile1,.env.envfile2
```

If `COMPOSE_ENV_FILES` is not set, and you don't provide `--env-file` in the CLI, Docker Compose uses the default behavior, which is to look for an `.env` file in the project directory.

#### [COMPOSE\_DISABLE\_ENV\_FILE](#compose_disable_env_file)

Lets you disable the use of the default `.env` file.

* Supported values:

  * `true` or `1`, Compose ignores the `.env` file
  * `false` or `0`, Compose looks for an `.env` file in the project directory

* Defaults to: `0`

### [Environment handling and container lifecycle](#environment-handling-and-container-lifecycle)

#### [COMPOSE\_CONVERT\_WINDOWS\_PATHS](#compose_convert_windows_paths)

When enabled, Compose performs path conversion from Windows-style to Unix-style in volume definitions.

* Supported values:

  * `true` or `1`, to enable
  * `false` or `0`, to disable

* Defaults to: `0`

#### [COMPOSE\_IGNORE\_ORPHANS](#compose_ignore_orphans)

When enabled, Compose doesn't try to detect orphaned containers for the project.

* Supported values:

  * `true` or `1`, to enable
  * `false` or `0`, to disable

* Defaults to: `0`

#### [COMPOSE\_REMOVE\_ORPHANS](#compose_remove_orphans)

When enabled, Compose automatically removes orphaned containers when updating a service or stack. Orphaned containers are those that were created by a previous configuration but are no longer defined in the current `compose.yaml` file.

* Supported values:

  * `true` or `1`, to enable automatic removal of orphaned containers
  * `false` or `0`, to disable automatic removal. Compose displays a warning about orphaned containers instead.

* Defaults to: `0`

#### [COMPOSE\_PARALLEL\_LIMIT](#compose_parallel_limit)

Specifies the maximum level of parallelism for concurrent engine calls.

### [Output](#output)

#### [COMPOSE\_ANSI](#compose_ansi)

Specifies when to print ANSI control characters.

* Supported values:

  * `auto`, Compose detects if TTY mode can be used. Otherwise, use plain text mode
  * `never`, use plain text mode
  * `always` or `0`, use TTY mode

* Defaults to: `auto`

#### [COMPOSE\_STATUS\_STDOUT](#compose_status_stdout)

When enabled, Compose writes its internal status and progress messages to `stdout` instead of `stderr`. The default value is false to clearly separate the output streams between Compose messages and your container's logs.

* Supported values:

  * `true` or `1`, to enable
  * `false` or `0`, to disable

* Defaults to: `0`

#### [COMPOSE\_PROGRESS](#compose_progress)

Requires: Docker Compose [2.36.0](https://github.com/docker/compose/releases/tag/v2.36.0) and later

Defines the type of progress output, if `--progress` isn't used.

Supported values are `auto`, `tty`, `plain`, `json`, and `quiet`. Default is `auto`.

### [User experience](#user-experience)

#### [COMPOSE\_MENU](#compose_menu)

Requires: Docker Compose [2.26.0](https://github.com/docker/compose/releases/tag/v2.26.0) and later

When enabled, Compose displays a navigation menu where you can choose to open the Compose stack in Docker Desktop, switch on [`watch` mode](https://docs.docker.com/compose/how-tos/file-watch/), or use [Docker Debug](/reference/cli/docker/debug/).

* Supported values:

  * `true` or `1`, to enable
  * `false` or `0`, to disable

* Defaults to: `1` if you obtained Docker Compose through Docker Desktop, otherwise the default is `0`

#### [COMPOSE\_EXPERIMENTAL](#compose_experimental)

Requires: Docker Compose [2.26.0](https://github.com/docker/compose/releases/tag/v2.26.0) and later

This is an opt-out variable. When turned off it deactivates the experimental features.

* Supported values:

  * `true` or `1`, to enable
  * `false` or `0`, to disable

* Defaults to: `1`

## [Unsupported in Compose V2](#unsupported-in-compose-v2)

The following environment variables have no effect in Compose V2.

* `COMPOSE_API_VERSION` By default the API version is negotiated with the server. Use `DOCKER_API_VERSION`.\
  See the [Docker CLI environment variable reference](/reference/cli/docker/#environment-variables) page.
* `COMPOSE_HTTP_TIMEOUT`
* `COMPOSE_TLS_VERSION`
* `COMPOSE_FORCE_WINDOWS_HOST`
* `COMPOSE_INTERACTIVE_NO_CLI`
* `COMPOSE_DOCKER_CLI_BUILD` Use `DOCKER_BUILDKIT` to select between BuildKit and the classic builder. If `DOCKER_BUILDKIT=0` then `docker compose build` uses the classic builder to build images.

----
url: https://docs.docker.com/reference/cli/docker/compose/down/
----

# docker compose down

***

| Description | Stop and remove containers, networks       |
| ----------- | ------------------------------------------ |
| Usage       | `docker compose down [OPTIONS] [SERVICES]` |

## [Description](#description)

Stops containers and removes containers, networks, volumes, and images created by `up`.

By default, the only things removed are:

* Containers for services defined in the Compose file.
* Networks defined in the networks section of the Compose file.
* The default network, if one is used.

Networks and volumes defined as external are never removed.

Anonymous volumes are not removed by default. However, as they don’t have a stable name, they are not automatically mounted by a subsequent `up`. For data that needs to persist between updates, use explicit paths as bind mounts or named volumes.

## [Options](#options)

| Option             | Default | Description                                                                                                              |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--remove-orphans` |         | Remove containers for services not defined in the Compose file                                                           |
| `--rmi`            |         | Remove images used by services. "local" remove only images that don't have a custom tag ("local"\|"all")                 |
| `-t, --timeout`    |         | Specify a shutdown timeout in seconds                                                                                    |
| `-v, --volumes`    |         | Remove named volumes declared in the "volumes" section of the Compose file and anonymous volumes attached to containers  |

----
url: https://docs.docker.com/engine/security/seccomp/
----

# Seccomp security profiles for Docker

***

Table of contents

***

Secure computing mode (`seccomp`) is a Linux kernel feature. You can use it to restrict the actions available within the container. The `seccomp()` system call operates on the seccomp state of the calling process. You can use this feature to restrict your application's access.

This feature is available only if Docker has been built with `seccomp` and the kernel is configured with `CONFIG_SECCOMP` enabled. To check if your kernel supports `seccomp`:

```console
$ grep CONFIG_SECCOMP= /boot/config-$(uname -r)
CONFIG_SECCOMP=y
```

## [Pass a profile for a container](#pass-a-profile-for-a-container)

The [default `seccomp` profile](https://github.com/moby/profiles/blob/main/seccomp/default.json) provides a sane default for running containers with seccomp and disables around 44 system calls out of 300+. It is moderately protective while providing wide application compatibility.

In effect, the profile is an allowlist that denies access to system calls by default and then allows specific system calls. The profile works by defining a `defaultAction` of `SCMP_ACT_ERRNO` and overriding that action only for specific system calls. The effect of `SCMP_ACT_ERRNO` is to cause a `Permission Denied` error. Next, the profile defines a specific list of system calls which are fully allowed, because their `action` is overridden to be `SCMP_ACT_ALLOW`. Finally, some specific rules are for individual system calls such as `personality`, and others, to allow variants of those system calls with specific arguments.

`seccomp` is instrumental for running Docker containers with least privilege. It is not recommended to change the default `seccomp` profile.

When you run a container, it uses the default profile unless you override it with the `--security-opt` option. For example, the following explicitly specifies a policy:

```console
$ docker run --rm \
             -it \
             --security-opt seccomp=/path/to/seccomp/profile.json \
             hello-world
```

### [Significant syscalls blocked by the default profile](#significant-syscalls-blocked-by-the-default-profile)

Docker's default seccomp profile is an allowlist which specifies the calls that are allowed. The table below lists the significant (but not all) syscalls that are effectively blocked because they are not on the allowlist. The table includes the reason each syscall is blocked rather than white-listed.

| Syscall             | Description                                                                                                                                                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `acct`              | Accounting syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_PACCT`.                                                                                                                                |
| `add_key`           | Prevent containers from using the kernel keyring, which is not namespaced.                                                                                                                                                                                           |
| `bpf`               | Deny loading potentially persistent BPF programs into kernel, already gated by `CAP_SYS_ADMIN`.                                                                                                                                                                      |
| `clock_adjtime`     | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`.                                                                                                                                                                                                           |
| `clock_settime`     | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`.                                                                                                                                                                                                           |
| `clone`             | Deny cloning new namespaces. Also gated by `CAP_SYS_ADMIN` for CLONE\_\* flags, except `CLONE_NEWUSER`.                                                                                                                                                              |
| `create_module`     | Deny manipulation and functions on kernel modules. Obsolete. Also gated by `CAP_SYS_MODULE`.                                                                                                                                                                         |
| `delete_module`     | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`.                                                                                                                                                                                   |
| `finit_module`      | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`.                                                                                                                                                                                   |
| `get_kernel_syms`   | Deny retrieval of exported kernel and module symbols. Obsolete.                                                                                                                                                                                                      |
| `get_mempolicy`     | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`.                                                                                                                                                                              |
| `init_module`       | Deny manipulation and functions on kernel modules. Also gated by `CAP_SYS_MODULE`.                                                                                                                                                                                   |
| `ioperm`            | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`.                                                                                                                                                                     |
| `iopl`              | Prevent containers from modifying kernel I/O privilege levels. Already gated by `CAP_SYS_RAWIO`.                                                                                                                                                                     |
| `io_uring_enter`    | Blocked due to security vulnerabilities that can be exploited to break out of containers. See [moby/moby#46762](https://github.com/moby/moby/pull/46762).                                                                                                            |
| `io_uring_register` | Blocked due to security vulnerabilities that can be exploited to break out of containers. See [moby/moby#46762](https://github.com/moby/moby/pull/46762).                                                                                                            |
| `io_uring_setup`    | Blocked due to security vulnerabilities that can be exploited to break out of containers. See [moby/moby#46762](https://github.com/moby/moby/pull/46762).                                                                                                            |
| `kcmp`              | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`.                                                                                                                                                                              |
| `kexec_file_load`   | Sister syscall of `kexec_load` that does the same thing, slightly different arguments. Also gated by `CAP_SYS_BOOT`.                                                                                                                                                 |
| `kexec_load`        | Deny loading a new kernel for later execution. Also gated by `CAP_SYS_BOOT`.                                                                                                                                                                                         |
| `keyctl`            | Prevent containers from using the kernel keyring, which is not namespaced.                                                                                                                                                                                           |
| `lookup_dcookie`    | Tracing/profiling syscall, which could leak a lot of information on the host. Also gated by `CAP_SYS_ADMIN`.                                                                                                                                                         |
| `mbind`             | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`.                                                                                                                                                                              |
| `mount`             | Deny mounting, already gated by `CAP_SYS_ADMIN`.                                                                                                                                                                                                                     |
| `move_pages`        | Syscall that modifies kernel memory and NUMA settings.                                                                                                                                                                                                               |
| `nfsservctl`        | Deny interaction with the kernel NFS daemon. Obsolete since Linux 3.1.                                                                                                                                                                                               |
| `open_by_handle_at` | Cause of an old container breakout. Also gated by `CAP_DAC_READ_SEARCH`.                                                                                                                                                                                             |
| `perf_event_open`   | Tracing/profiling syscall, which could leak a lot of information on the host.                                                                                                                                                                                        |
| `personality`       | Prevent container from enabling BSD emulation. Not inherently dangerous, but poorly tested, potential for a lot of kernel vulnerabilities.                                                                                                                           |
| `pivot_root`        | Deny `pivot_root`, should be privileged operation.                                                                                                                                                                                                                   |
| `process_vm_readv`  | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`.                                                                                                                                                                              |
| `process_vm_writev` | Restrict process inspection capabilities, already blocked by dropping `CAP_SYS_PTRACE`.                                                                                                                                                                              |
| `ptrace`            | Tracing/profiling syscall. Blocked in Linux kernel versions before 4.8 to avoid seccomp bypass. Tracing/profiling arbitrary processes is already blocked by dropping `CAP_SYS_PTRACE`, because it could leak a lot of information on the host.                       |
| `query_module`      | Deny manipulation and functions on kernel modules. Obsolete.                                                                                                                                                                                                         |
| `quotactl`          | Quota syscall which could let containers disable their own resource limits or process accounting. Also gated by `CAP_SYS_ADMIN`.                                                                                                                                     |
| `reboot`            | Don't let containers reboot the host. Also gated by `CAP_SYS_BOOT`.                                                                                                                                                                                                  |
| `request_key`       | Prevent containers from using the kernel keyring, which is not namespaced.                                                                                                                                                                                           |
| `set_mempolicy`     | Syscall that modifies kernel memory and NUMA settings. Already gated by `CAP_SYS_NICE`.                                                                                                                                                                              |
| `setns`             | Deny associating a thread with a namespace. Also gated by `CAP_SYS_ADMIN`.                                                                                                                                                                                           |
| `settimeofday`      | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`.                                                                                                                                                                                                           |
| `stime`             | Time/date is not namespaced. Also gated by `CAP_SYS_TIME`.                                                                                                                                                                                                           |
| `socket`            | Blocked for `AF_ALG` to prevent in-container privilege escalation via the kernel cryptographic API ([CVE-2026-31431](https://nvd.nist.gov/vuln/detail/CVE-2026-31431)). Also blocked for `AF_VSOCK`. See [moby/moby#52494](https://github.com/moby/moby/pull/52494). |
| `socketcall`        | Denied to prevent bypassing socket address family filters on architectures with the legacy `socketcall` multiplexer (i386, s390, MIPS o32). See [moby/moby#52494](https://github.com/moby/moby/pull/52494).                                                          |
| `swapon`            | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`.                                                                                                                                                                                              |
| `swapoff`           | Deny start/stop swapping to file/device. Also gated by `CAP_SYS_ADMIN`.                                                                                                                                                                                              |
| `sysfs`             | Obsolete syscall.                                                                                                                                                                                                                                                    |
| `_sysctl`           | Obsolete, replaced by /proc/sys.                                                                                                                                                                                                                                     |
| `umount`            | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`.                                                                                                                                                                                                     |
| `umount2`           | Should be a privileged operation. Also gated by `CAP_SYS_ADMIN`.                                                                                                                                                                                                     |
| `unshare`           | Deny cloning new namespaces for processes. Also gated by `CAP_SYS_ADMIN`, with the exception of `unshare --user`.                                                                                                                                                    |
| `uselib`            | Older syscall related to shared libraries, unused for a long time.                                                                                                                                                                                                   |
| `userfaultfd`       | Userspace page fault handling, largely needed for process migration.                                                                                                                                                                                                 |
| `ustat`             | Obsolete syscall.                                                                                                                                                                                                                                                    |
| `vm86`              | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`.                                                                                                                                                                                              |
| `vm86old`           | In kernel x86 real mode virtual machine. Also gated by `CAP_SYS_ADMIN`.                                                                                                                                                                                              |

## [Run without the default seccomp profile](#run-without-the-default-seccomp-profile)

You can pass `unconfined` to run a container without the default seccomp profile.

```console
$ docker run --rm -it --security-opt seccomp=unconfined debian:latest \
    unshare --map-root-user --user sh -c whoami
```

----
url: https://docs.docker.com/reference/cli/docker/context/ls/
----

# docker context ls

***

| Description                                                               | List contexts                 |
| ------------------------------------------------------------------------- | ----------------------------- |
| Usage                                                                     | `docker context ls [OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker context list`         |

## [Description](#description)

List contexts

## [Options](#options)

| Option        | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--format`    |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-q, --quiet` |         | Only show context names                                                                                                                                                                                                                                                                                                                                                                |

## [Examples](#examples)

Use `docker context ls` to print all contexts. The currently active context is indicated with an `*`:

```console
$ docker context ls

NAME                DESCRIPTION                               DOCKER ENDPOINT                      ORCHESTRATOR
default *           Current DOCKER_HOST based configuration   unix:///var/run/docker.sock          swarm
production                                                    tcp:///prod.corp.example.com:2376
staging                                                       tcp:///stage.corp.example.com:2376
```

----
url: https://docs.docker.com/docker-hub/repos/manage/hub-images/oci-artifacts/
----

# Software artifacts on Docker Hub

***

Table of contents

***

You can use Docker Hub to store any kind of software artifact, not just container images. A software artifact is any item produced during the software development process that contributes to the creation, maintenance, or understanding of the software. Docker Hub supports OCI artifacts by leveraging the config property on the image manifest.

## [What are OCI artifacts?](#what-are-oci-artifacts)

OCI artifacts are any arbitrary files related to a software application. Some examples include:

* Helm charts
* Software Bill of Materials (SBOM)
* Digital signatures
* Provenance data
* Attestations
* Vulnerability reports

Docker Hub supporting OCI artifacts means you can use one repository for storing and distributing container images as well as other assets.

A common use case for OCI artifacts is [Helm charts](https://helm.sh/docs/topics/charts/). Helm charts is a packaging format that defines a Kubernetes deployment for an application. Since Kubernetes is a popular runtime for containers, it makes sense to host application images and deployment templates all in one place.

## [Using OCI artifacts with Docker Hub](#using-oci-artifacts-with-docker-hub)

You manage OCI artifacts on Docker Hub in a similar way you would container images.

Pushing and pulling OCI artifacts to and from a registry is done using a registry client. [ORAS CLI](https://oras.land/docs/installation) is a command-line tool that provides the capability of managing OCI artifacts in a registry. If you use Helm charts, the [Helm CLI](https://helm.sh/docs/intro/install/) provides built-in functionality for pushing and pulling charts to and from a registry.

Registry clients invoke HTTP requests to the Docker Hub registry API. The registry API conforms to a standard protocol defined in the [OCI distribution specification](https://github.com/opencontainers/distribution-spec).

## [Examples](#examples)

This section shows some examples on using OCI artifacts with Docker Hub.

### [Push a Helm chart](#push-a-helm-chart)

The following procedure shows how to push a Helm chart as an OCI artifact to Docker Hub.

Prerequisites:

* Helm version 3.0.0 or later

Steps:

1. Create a new Helm chart

   ```console
   $ helm create demo
   ```

   This command generates a boilerplate template chart.

2. Package the Helm chart into a tarball.

   ```console
   $ helm package demo
   Successfully packaged chart and saved it to: demo-0.1.0.tgz
   ```

3. Sign in to Docker Hub with Helm, using your Docker credentials.

   ```console
   $ helm registry login registry-1.docker.io -u YOUR_DOCKER_USERNAME
   ```

4. Push the chart to a Docker Hub repository.

   ```console
   $ helm push demo-0.1.0.tgz oci://registry-1.docker.io/YOUR_DOCKER_USERNAME
   ```

   This uploads the Helm chart tarball to a `demo` repository in the `<YOUR_DOCKER_USERNAME>` namespace. Running this command creates a `<YOUR_DOCKER_USERNAME>/demo` repository if one does not already exist.

5. Go to the repository page on Docker Hub. The **Tags** section of the page shows the Helm chart tag.

6. Select the tag name to go to the page for that tag.

   The page lists a few useful commands for working with Helm charts.

### [Push a volume](#push-a-volume)

The following procedure shows how to push container volume as an OCI artifact to Docker Hub.

Prerequisites:

* ORAS CLI version 0.15 or later

Steps:

1. Create a dummy file to use as volume content.

   ```console
   $ touch myvolume.txt
   ```

2. Sign in to Docker Hub using the ORAS CLI.

   ```console
   $ oras login -u YOUR_DOCKER_USERNAME registry-1.docker.io
   ```

3. Push the file to Docker Hub.

   ```console
   $ oras push registry-1.docker.io/YOUR_DOCKER_USERNAME/demo:0.0.1 \
     --artifact-type=application/vnd.docker.volume.v1+tar.gz \
     myvolume.txt:text/plain
   ```

   This uploads the volume to a `demo` repository in the `<YOUR_DOCKER_USERNAME>` namespace. The `--artifact-type` flag specifies a special media type that makes Docker Hub recognize the artifact as a container volume.

4. Go to the repository page on Docker Hub. The **Tags** section on that page shows the volume tag.

### [Push a generic artifact file](#push-a-generic-artifact-file)

The following procedure shows how to push a generic OCI artifact to Docker Hub.

Prerequisites:

* ORAS CLI version 0.15 or later

Steps:

1. Create your artifact file.

   ```console
   $ touch myartifact.txt
   ```

2. Sign in to Docker Hub using the ORAS CLI.

   ```console
   $ oras login -u YOUR_DOCKER_USERNAME registry-1.docker.io
   ```

3. Push the file to Docker Hub.

   ```console
   $ oras push registry-1.docker.io/YOUR_DOCKER_USERNAME/demo:0.0.1 myartifact.txt:text/plain
   ```

4. Go to the repository page on Docker Hub. The **Tags** section on that page shows the artifact tag.

----
url: https://docs.docker.com/ai/docker-agent/reference/toolsets/
----

# Toolsets reference

***

Table of contents

***

This reference documents the toolsets available in Docker Agent and what each one does. Tools give agents the ability to take action—interacting with files, executing commands, accessing external resources, and managing state.

For configuration file syntax and how to set up toolsets in your agent YAML, see the [Configuration file reference](https://docs.docker.com/ai/docker-agent/reference/config/).

## [How agents use tools](#how-agents-use-tools)

When you configure toolsets for an agent, those tools become available in the agent's context. The agent can invoke tools by name with appropriate parameters based on the task at hand.

Tool invocation flow:

1. Agent analyzes the task and determines which tool to use
2. Agent constructs tool parameters based on requirements
3. Docker Agent executes the tool and returns results
4. Agent processes results and decides next steps

Agents can call multiple tools in sequence or make decisions based on tool results. Tool selection is automatic based on the agent's understanding of the task and available capabilities.

## [Tool types](#tool-types)

Docker Agent supports three types of toolsets:

* Built-in toolsets

  * Core functionality built directly into Docker Agent (`filesystem`, `shell`, `memory`, etc.). These provide essential capabilities for file operations, command execution, and state management. MCP toolsets
  * Tools provided by Model Context Protocol servers, either local processes (stdio) or remote servers (HTTP/SSE). MCP enables access to a wide ecosystem of standardized tools. Custom toolsets
  * Shell scripts wrapped as tools with typed parameters (`script`). This lets you define domain-specific tools for your use case.

## [Configuration](#configuration)

Toolsets are configured in your agent's YAML file under the `toolsets` array:

```yaml
agents:
  my_agent:
    model: anthropic/claude-sonnet-4-5
    description: A helpful coding assistant
    toolsets:
      # Built-in toolset
      - type: filesystem

      # Built-in toolset with configuration
      - type: memory
        path: ./memories.db

      # Local MCP server (stdio)
      - type: mcp
        command: npx
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

      # Remote MCP server (SSE)
      - type: mcp
        remote:
          url: https://mcp.example.com/sse
          transport_type: sse
          headers:
            Authorization: Bearer ${API_TOKEN}

      # Custom shell tools
      - type: script
        tools:
          build:
            cmd: npm run build
            description: Build the project
```

### [Common configuration options](#common-configuration-options)

All toolset types support these optional properties:

| Property      | Type             | Description                                                                                                                                                                                                                         |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `instruction` | string           | Additional instructions for using the toolset                                                                                                                                                                                       |
| `tools`       | array            | Specific tool names to enable (defaults to all)                                                                                                                                                                                     |
| `env`         | object           | Environment variables for the toolset                                                                                                                                                                                               |
| `toon`        | string           | Comma-delimited regex patterns matching tool names whose JSON outputs should be compressed. Reduces token usage by simplifying/compressing JSON responses from matched tools using automatic encoding. Example: `"search.*,list.*"` |
| `defer`       | boolean or array | Control which tools load into initial context. Set to `true` to defer all tools, or array of tool names to defer specific tools. Deferred tools don't consume context until explicitly loaded via `search_tool`/`add_tool`.         |

### [Tool selection](#tool-selection)

By default, agents have access to all tools from their configured toolsets. You can restrict this using the `tools` option:

```yaml
toolsets:
  - type: filesystem
    tools: [read_file, write_file, list_directory]
```

This is useful for:

* Limiting agent capabilities for security
* Reducing context size for smaller models
* Creating specialized agents with focused tool access

### [Deferred loading](#deferred-loading)

Deferred loading keeps tools out of the initial context window, loading them only when explicitly requested. This is useful for large toolsets where most tools won't be used, significantly reducing context consumption.

Defer all tools in a toolset:

```yaml
toolsets:
  - type: mcp
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    defer: true # All tools load on-demand
```

Or defer specific tools while loading others immediately:

```yaml
toolsets:
  - type: mcp
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    defer: [search_files, list_directory] # Only these are deferred
```

Agents can discover deferred tools via `search_tool` and load them into context via `add_tool` when needed. Best for toolsets with dozens of tools where only a few are typically used.

### [Output compression](#output-compression)

The `toon` property compresses JSON outputs from matched tools to reduce token usage. When a tool's output is JSON, it's automatically compressed using efficient encoding before being returned to the agent:

```yaml
toolsets:
  - type: mcp
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    toon: "search.*,list.*" # Compress outputs from search/list tools
```

Useful for tools that return large JSON responses (API results, file listings, search results). The compression is transparent to the agent but can significantly reduce context consumption for verbose tool outputs.

### [Auto-installation of tool binaries](#auto-installation-of-tool-binaries)

MCP and LSP toolsets that require a binary command can be auto-installed if the command isn't on your system. Docker Agent uses the [aqua registry](https://github.com/aquaproj/aqua-registry), a curated index of CLI tool packages, to resolve and download binaries.

When a toolset with a `command` property is loaded, Docker Agent:

1. Checks if the command exists in your `PATH`.
2. Checks the Docker Agent tools directory (`~/.cagent/tools/bin/`).
3. If still not found, looks up the command in the aqua registry and installs it.

Installed binaries are stored under `~/.cagent/tools/`. You can override this location with the `DOCKER_AGENT_TOOLS_DIR` environment variable.

Use the `version` property to pin a specific package and version:

```yaml
toolsets:
  - type: lsp
    command: gopls
    version: "golang/tools@v0.21.0"
    file_types: [".go"]

  - type: mcp
    command: some-mcp-server
    version: "owner/repo@v1.2.3"
```

The format is `owner/repo` or `owner/repo@version`. Without a version tag, Docker Agent uses the latest release. Without the `version` property entirely, Docker Agent tries to auto-detect the package from the command name.

To disable auto-installation for a single toolset, set `version` to `"false"`:

```yaml
toolsets:
  - type: mcp
    command: my-custom-server
    version: "false"
```

To disable auto-installation globally, set the `DOCKER_AGENT_AUTO_INSTALL` environment variable to `false`.

### [Per-agent tool configuration](#per-agent-tool-configuration)

Different agents can have different toolsets:

```yaml
agents:
  coordinator:
    model: anthropic/claude-sonnet-4-5
    sub_agents: [code_writer, code_reviewer]
    toolsets:
      - type: filesystem
        tools: [read_file]

  code_writer:
    model: openai/gpt-5-mini
    toolsets:
      - type: filesystem
      - type: shell

  code_reviewer:
    model: anthropic/claude-sonnet-4-5
    toolsets:
      - type: filesystem
        tools: [read_file, read_multiple_files]
```

This allows specialized agents with focused capabilities, security boundaries, and optimized performance.

## [Built-in tools reference](#built-in-tools-reference)

### [Filesystem](#filesystem)

The `filesystem` toolset gives your agent the ability to work with files and directories. Your agent can read files to understand context, write new files, make targeted edits to existing files, search for content, and explore directory structures. Essential for code analysis, documentation updates, configuration management, and any agent that needs to understand or modify project files.

Access is restricted to the current working directory by default. Agents can request access to additional directories at runtime, which requires your approval.

#### [Configuration](#configuration-1)

```yaml
toolsets:
  - type: filesystem

  # Optional: restrict to specific tools
  - type: filesystem
    tools: [read_file, write_file, edit_file]
```

### [LSP](#lsp)

The `lsp` toolset connects your agent to [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) servers, providing code intelligence like go-to-definition, find references, diagnostics, rename, formatting, and more.

You can configure multiple LSP servers for different programming languages, giving your agent code intelligence across your project.

#### [Configuration](#configuration-2)

```yaml
toolsets:
  - type: lsp
    command: gopls
    file_types: [".go"]

  - type: lsp
    command: typescript-language-server
    args: ["--stdio"]
    file_types: [".ts", ".tsx", ".js", ".jsx"]

  - type: lsp
    command: pylsp
    file_types: [".py"]
```

If an LSP server binary isn't in your PATH, Docker Agent can [auto-install it](#auto-installation-of-tool-binaries) using the `version` property.

#### [Properties](#properties)

| Property     | Type             | Required | Description                                                                                                         |
| ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `command`    | string           | Yes      | LSP server executable command                                                                                       |
| `args`       | array of strings | No       | Command-line arguments for the LSP server                                                                           |
| `env`        | object           | No       | Environment variables for the LSP server process                                                                    |
| `file_types` | array of strings | No       | File extensions this server handles (e.g., `[".go", ".mod"]`)                                                       |
| `version`    | string           | No       | Package reference for auto-installing the server binary (e.g., `"golang/tools@v0.21.0"`). Set `"false"` to disable. |

#### [Available tools](#available-tools)

| Tool                    | Description                                   | Read-only |
| ----------------------- | --------------------------------------------- | --------- |
| `lsp_workspace`         | Get workspace info and available capabilities | Yes       |
| `lsp_hover`             | Get type info and documentation for a symbol  | Yes       |
| `lsp_definition`        | Find where a symbol is defined                | Yes       |
| `lsp_references`        | Find all references to a symbol               | Yes       |
| `lsp_document_symbols`  | List all symbols in a file                    | Yes       |
| `lsp_workspace_symbols` | Search symbols across the workspace           | Yes       |
| `lsp_diagnostics`       | Get errors and warnings for a file            | Yes       |
| `lsp_code_actions`      | Get available quick fixes and refactorings    | Yes       |
| `lsp_rename`            | Rename a symbol across the workspace          | No        |
| `lsp_format`            | Format a file                                 | No        |
| `lsp_call_hierarchy`    | Find incoming and outgoing calls              | Yes       |
| `lsp_type_hierarchy`    | Find supertypes and subtypes                  | Yes       |
| `lsp_implementations`   | Find interface implementations                | Yes       |
| `lsp_signature_help`    | Get function signature at call site           | Yes       |
| `lsp_inlay_hints`       | Get type annotations and parameter names      | Yes       |

Not all LSP servers support all features. The agent uses `lsp_workspace` to discover the capabilities of each configured server.

#### [Language server examples](#language-server-examples)

The following examples show configurations for common languages:

| Language              | Command                      | `file_types`                     |
| --------------------- | ---------------------------- | -------------------------------- |
| Go                    | `gopls`                      | `[".go"]`                        |
| TypeScript/JavaScript | `typescript-language-server` | `[".ts", ".tsx", ".js", ".jsx"]` |
| Python                | `pylsp`                      | `[".py"]`                        |
| Rust                  | `rust-analyzer`              | `[".rs"]`                        |
| C/C++                 | `clangd`                     | `[".c", ".cpp", ".h", ".hpp"]`   |

For TypeScript/JavaScript, pass `args: ["--stdio"]` to the language server.

### [Shell](#shell)

The `shell` toolset lets your agent execute commands in your system's shell environment. Use this for agents that need to run builds, execute tests, manage processes, interact with CLI tools, or perform system operations. The agent can run commands in the foreground or background.

Commands execute in the current working directory and inherit environment variables from the Docker Agent process. This toolset is powerful but should be used with appropriate security considerations.

#### [Configuration](#configuration-3)

```yaml
toolsets:
  - type: shell
```

### [Think](#think)

The `think` toolset provides your agent with a reasoning scratchpad. The agent can record thoughts and reasoning steps without taking actions or modifying data. Particularly useful for complex tasks where the agent needs to plan multiple steps, verify requirements, or maintain context across a long conversation.

Agents use this to break down problems, list applicable rules, verify they have all needed information, and document their reasoning process before acting.

#### [Configuration](#configuration-4)

```yaml
toolsets:
  - type: think
```

### [Todo](#todo)

The `todo` toolset gives your agent task-tracking capabilities for managing multi-step operations. Your agent can break down complex work into discrete tasks, track progress through each step, and ensure nothing is missed before completing a request. Especially valuable for agents handling complex workflows with multiple dependencies.

The `shared` option allows todos to persist across different agents in a multi-agent system, enabling coordination.

#### [Configuration](#configuration-5)

```yaml
toolsets:
  - type: todo

  # Optional: share todos across agents
  - type: todo
    shared: true
```

### [Tasks](#tasks)

The `tasks` toolset is an advanced version of the `todo` toolset, and provides task management with priorities, dependencies, and persistence. Your agent can create tasks with different priority levels, establish prerequisite relationships between tasks, and automatically track which tasks are blocked by incomplete dependencies. Tasks are sorted by priority and blocking status, making it easy to identify the next actionable work.

Tasks are stored in a JSON file and persist across Docker Agent sessions.

#### [Configuration](#configuration-6)

```yaml
toolsets:
  - type: tasks

  # Optional: specify storage location
  - type: tasks
    path: ./project-tasks.json
```

#### [Available tools](#available-tools-1)

The tasks toolset provides these tools:

* **create\_task**: Create a new task with title, description, priority, and dependencies
* **get\_task**: Retrieve full details of a task by ID, including effective status
* **update\_task**: Modify task fields (title, description, priority, status, dependencies)
* **delete\_task**: Remove a task and clean up its dependencies
* **list\_tasks**: List all tasks sorted by priority, optionally filtered by status or priority
* **next\_task**: Get the highest-priority actionable task (not blocked or done)
* **add\_dependency**: Add a dependency between tasks (with cycle detection)
* **remove\_dependency**: Remove a dependency from a task

#### [Task statuses and priorities](#task-statuses-and-priorities)

Tasks have four statuses: `pending`, `in_progress`, `done`, and `blocked`. The agent automatically calculates the effective status. A task becomes `blocked` if any of its dependencies are not `done`, regardless of its assigned status.

Priority levels (from highest to lowest): `critical`, `high`, `medium` (default), `low`. Tasks are sorted by blocking status first (unblocked tasks first), then by priority, then by creation time.

### [Memory](#memory)

The `memory` toolset allows your agent to store and retrieve information across conversations and sessions. Your agent can remember user preferences, project context, previous decisions, and other information that should persist. Useful for agents that interact with users over time or need to maintain state about a project or environment.

Memories are stored in a local database file and persist across Docker Agent sessions.

#### [Configuration](#configuration-7)

```yaml
toolsets:
  - type: memory

  # Optional: specify database location
  - type: memory
    path: ./agent-memories.db
```

### [Fetch](#fetch)

The `fetch` toolset enables your agent to retrieve content from HTTP/HTTPS URLs. Your agent can fetch documentation, API responses, web pages, or any content accessible via HTTP GET requests. Useful for agents that need to access external resources, check API documentation, or retrieve web content.

The agent can specify custom HTTP headers when needed for authentication or other purposes.

#### [Configuration](#configuration-8)

```yaml
toolsets:
  - type: fetch
```

### [User Prompt](#user-prompt)

The `user_prompt` toolset lets your agent ask you questions during task execution. When the agent needs clarification, decisions, or additional information it can't determine on its own, it displays a dialog and waits for your response.

You'll see a prompt with the agent's question. Depending on what the agent needs, you might provide free-form text, select from options, or fill out a form with multiple fields. You can accept and provide the information, decline to answer, or cancel the operation entirely.

#### [Configuration](#configuration-9)

```yaml
toolsets:
  - type: user_prompt
```

No additional configuration is required. The tool becomes available to the agent once configured. When the agent calls this tool, the user sees a dialog with the prompt. The user can:

* **Accept**: Provide the requested information
* **Decline**: Refuse to provide the information
* **Cancel**: Cancel the operation

### [API](#api)

The `api` toolset lets you define custom tools that call HTTP APIs. Similar to `script` but for web services, this allows you to expose REST APIs, webhooks, or any HTTP endpoint as a tool your agent can use. The agent sees these as typed tools with automatic parameter validation.

Use this to integrate with external services, call internal APIs, trigger webhooks, or interact with any HTTP-based system.

#### [Configuration](#configuration-10)

Each API tool is defined with an `api_config` containing the endpoint, HTTP method, and optional typed parameters:

```yaml
toolsets:
  - type: api
    api_config:
      name: search_docs
      endpoint: https://api.example.com/search
      method: GET
      instruction: Search the documentation database
      headers:
        Authorization: Bearer ${API_TOKEN}
      args:
        query:
          type: string
          description: Search query
        limit:
          type: number
          description: Maximum results
      required: [query]

  - type: api
    api_config:
      name: create_ticket
      endpoint: https://api.example.com/tickets
      method: POST
      instruction: Create a support ticket
      args:
        title:
          type: string
          description: Ticket title
        description:
          type: string
          description: Ticket description
      required: [title, description]
```

For GET requests, parameters are interpolated into the endpoint URL. For POST requests, parameters are sent as JSON in the request body.

Supported argument types: `string`, `number`, `boolean`, `array`, `object`.

### [Script](#script)

The `script` toolset lets you define custom tools by wrapping shell commands with typed parameters. This allows you to expose domain-specific operations to your agent as first-class tools. The agent sees these custom tools just like built-in tools, with parameter validation and type checking handled automatically.

Use this to create tools for deployment scripts, build commands, test runners, or any operation specific to your project or workflow.

#### [Configuration](#configuration-11)

Each custom tool is defined with a command, description, and optional typed parameters:

```yaml
toolsets:
  - type: script
    tools:
      deploy:
        cmd: ./deploy.sh
        description: Deploy the application to an environment
        args:
          environment:
            type: string
            description: Target environment (dev, staging, prod)
          version:
            type: string
            description: Version to deploy
        required: [environment]

      run_tests:
        cmd: npm test
        description: Run the test suite
        args:
          filter:
            type: string
            description: Test name filter pattern
```

Supported argument types: `string`, `number`, `boolean`, `array`, `object`.

#### [Tools](#tools)

The tools you define become available to your agent. In the previous example, the agent would have access to `deploy` and `run_tests` tools.

## [Automatic tools](#automatic-tools)

Some tools are automatically added to agents based on their configuration. You don't configure these explicitly—they appear when needed.

### [transfer\_task](#transfer_task)

Automatically available when your agent has `sub_agents` configured. Allows the agent to delegate tasks to sub-agents and receive results back.

### [handoff](#handoff)

Automatically available when your agent has `handoffs` configured. Allows the agent to transfer the entire conversation to a different agent.

## [What's next](#whats-next)

* Read the [Configuration file reference](https://docs.docker.com/ai/docker-agent/reference/config/) for YAML file structure
* Review the [CLI reference](https://docs.docker.com/ai/docker-agent/reference/cli/) for running agents
* Explore [MCP servers](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/) for extended capabilities
* Browse [example configurations](https://github.com/docker/docker-agent/tree/main/examples)

----
url: https://docs.docker.com/reference/api/extensions-sdk/Toast/
----

# Interface: Toast

***

Table of contents

***

Toasts provide a brief notification to the user. They appear temporarily and shouldn't interrupt the user experience. They also don't require user input to disappear.

**`Since`**

0.2.0

## [Methods](#methods)

### [success](#success)

▸ **success**(`msg`): `void`

Display a toast message of type success.

```typescript
ddClient.desktopUI.toast.success("message");
```

#### [Parameters](#parameters)

| Name  | Type     | Description                          |
| ----- | -------- | ------------------------------------ |
| `msg` | `string` | The message to display in the toast. |

#### [Returns](#returns)

`void`

***

### [warning](#warning)

▸ **warning**(`msg`): `void`

Display a toast message of type warning.

```typescript
ddClient.desktopUI.toast.warning("message");
```

#### [Parameters](#parameters-1)

| Name  | Type     | Description                            |
| ----- | -------- | -------------------------------------- |
| `msg` | `string` | The message to display in the warning. |

#### [Returns](#returns-1)

`void`

***

### [error](#error)

▸ **error**(`msg`): `void`

Display a toast message of type error.

```typescript
ddClient.desktopUI.toast.error("message");
```

#### [Parameters](#parameters-2)

| Name  | Type     | Description                          |
| ----- | -------- | ------------------------------------ |
| `msg` | `string` | The message to display in the toast. |

#### [Returns](#returns-2)

`void`

----
url: https://docs.docker.com/reference/cli/docker/stack/deploy/
----

# docker stack deploy

***

| Description                                                               | Deploy a new stack or update an existing stack |
| ------------------------------------------------------------------------- | ---------------------------------------------- |
| Usage                                                                     | `docker stack deploy [OPTIONS] STACK`          |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker stack up`                              |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Create and update a stack from a `compose` file on the swarm.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                                | Default  | Description                                                                                                  |
| ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| [`-c, --compose-file`](#compose-file) |          | API 1.25+ Path to a Compose file, or `-` to read from stdin                                                  |
| `-d, --detach`                        | `true`   | Exit immediately instead of waiting for the stack services to converge                                       |
| `--prune`                             |          | API 1.27+ Prune services that are no longer referenced                                                       |
| `-q, --quiet`                         |          | Suppress progress output                                                                                     |
| `--resolve-image`                     | `always` | API 1.30+ Query the registry to resolve image digest and supported platforms (`always`, `changed`, `never`)  |
| `--with-registry-auth`                |          | Send registry authentication details to Swarm agents                                                         |

## [Examples](#examples)

### [Compose file (--compose-file)](#compose-file)

The `deploy` command supports Compose file version `3.0` and above.

```console
$ docker stack deploy --compose-file docker-compose.yml vossibility

Ignoring unsupported options: links

Creating network vossibility_vossibility
Creating network vossibility_default
Creating service vossibility_nsqd
Creating service vossibility_logstash
Creating service vossibility_elasticsearch
Creating service vossibility_kibana
Creating service vossibility_ghollector
Creating service vossibility_lookupd
```

The Compose file can also be provided as standard input with `--compose-file -`:

```console
$ cat docker-compose.yml | docker stack deploy --compose-file - vossibility

Ignoring unsupported options: links

Creating network vossibility_vossibility
Creating network vossibility_default
Creating service vossibility_nsqd
Creating service vossibility_logstash
Creating service vossibility_elasticsearch
Creating service vossibility_kibana
Creating service vossibility_ghollector
Creating service vossibility_lookupd
```

If your configuration is split between multiple Compose files, e.g. a base configuration and environment-specific overrides, you can provide multiple `--compose-file` flags.

```console
$ docker stack deploy --compose-file docker-compose.yml -c docker-compose.prod.yml vossibility

Ignoring unsupported options: links

Creating network vossibility_vossibility
Creating network vossibility_default
Creating service vossibility_nsqd
Creating service vossibility_logstash
Creating service vossibility_elasticsearch
Creating service vossibility_kibana
Creating service vossibility_ghollector
Creating service vossibility_lookupd
```

You can verify that the services were correctly created:

```console
$ docker service ls

ID            NAME                               MODE        REPLICAS  IMAGE
29bv0vnlm903  vossibility_lookupd                replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
4awt47624qwh  vossibility_nsqd                   replicated  1/1       nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
4tjx9biia6fs  vossibility_elasticsearch          replicated  1/1       elasticsearch@sha256:12ac7c6af55d001f71800b83ba91a04f716e58d82e748fa6e5a7359eed2301aa
7563uuzr9eys  vossibility_kibana                 replicated  1/1       kibana@sha256:6995a2d25709a62694a937b8a529ff36da92ebee74bafd7bf00e6caf6db2eb03
9gc5m4met4he  vossibility_logstash               replicated  1/1       logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe
axqh55ipl40h  vossibility_vossibility-collector  replicated  1/1       icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba
```

----
url: https://docs.docker.com/guides/python/
----

# Python language-specific guide

***

This guide explains how to containerize Python applications using Docker.

**Time to complete** 20 minutes

> **Acknowledgment**
>
> This guide is a community contribution. Docker would like to thank [Esteban Maya](https://www.linkedin.com/in/esteban-x64/) and [Igor Aleksandrov](https://www.linkedin.com/in/igor-aleksandrov/) for their contribution to this guide.

The Python language-specific guide teaches you how to containerize a Python application using Docker. In this guide, you’ll learn how to:

* Containerize and run a Python application
* Set up a local environment to develop a Python application using containers
* Lint, format, typing and best practices
* Configure a CI/CD pipeline for a containerized Python application using GitHub Actions
* Deploy your containerized Python application locally to Kubernetes to test and debug your deployment

Start by containerizing an existing Python application.

## [Modules](#modules)

1. [Containerize your app](https://docs.docker.com/guides/python/containerize/)

   Learn how to containerize a Python application.

2. [Develop your app](https://docs.docker.com/guides/python/develop/)

   Learn how to develop your Python application locally.

3. [Linting and typing](https://docs.docker.com/guides/python/lint-format-typing/)

   Learn how to set up linting, formatting and type checking for your Python application.

4. [GitHub Actions CI](https://docs.docker.com/guides/python/configure-github-actions/)

   Learn how to configure CI/CD using GitHub Actions for your Python application.

5. [Test your deployment](https://docs.docker.com/guides/python/deploy/)

----
url: https://docs.docker.com/build/buildkit/toml-configuration/
----

# buildkitd.toml

***

***

The TOML file used to configure the buildkitd daemon settings has a short list of global settings followed by a series of sections for specific areas of daemon configuration.

The file path is `/etc/buildkit/buildkitd.toml` for rootful mode, `~/.config/buildkit/buildkitd.toml` for rootless mode.

The following is a complete `buildkitd.toml` configuration example. Note that some configuration options are only useful in edge cases.

```toml
# root is where all buildkit state is stored.
root = "/var/lib/buildkit"
# insecure-entitlements allows insecure entitlements, disabled by default.
insecure-entitlements = [ "network.host", "security.insecure", "device" ]
# provenanceEnvDir is the directory where extra config is loaded that is added
# to the provenance of builds:
# slsa v0.2: invocation.environment.*
# slsa v1: buildDefinition.internalParameters.*
provenanceEnvDir = "/etc/buildkit/provenance.d"

[log]
  # log formatter: json or text
  format = "text"

  # log level (error/warn/info/debug/trace)
  level = "info"

[dns]
  nameservers=["1.1.1.1","8.8.8.8"]
  options=["edns0"]
  searchDomains=["example.com"]

[grpc]
  address = [ "tcp://0.0.0.0:1234" ]
  # debugAddress is address for attaching go profiles and debuggers.
  debugAddress = "0.0.0.0:6060"
  uid = 0
  gid = 0
  [grpc.tls]
    cert = "/etc/buildkit/tls.crt"
    key = "/etc/buildkit/tls.key"
    ca = "/etc/buildkit/tlsca.crt"

[otel]
  # OTEL collector trace socket path
  socketPath = "/run/buildkit/otel-grpc.sock"

[cdi]
  # Disables support of the Container Device Interface (CDI).
  disabled = true
  # List of directories to scan for CDI spec files. For more details about CDI
  # specification, please refer to https://github.com/cncf-tags/container-device-interface/blob/main/SPEC.md#cdi-json-specification
  specDirs = ["/etc/cdi", "/var/run/cdi", "/etc/buildkit/cdi"]

# config for build history API that stores information about completed build commands
[history]
  # maxAge is the maximum age of history entries to keep, in seconds.
  maxAge = 172800
  # maxEntries is the maximum number of history entries to keep.
  maxEntries = 50

[worker.oci]
  enabled = true
  # platforms is manually configure platforms, detected automatically if unset.
  platforms = [ "linux/amd64", "linux/arm64" ]
  snapshotter = "auto" # overlayfs or native, default value is "auto".
  rootless = false # see docs/rootless.md for the details on rootless mode.
  # Whether run subprocesses in main pid namespace or not, this is useful for
  # running rootless buildkit inside a container.
  noProcessSandbox = false
  # gc enables/disables garbage collection
  gc = true
  # reservedSpace is the minimum amount of disk space guaranteed to be
  # retained by this buildkit worker - any usage below this threshold will not
  # be reclaimed during garbage collection.
  # all disk space parameters can be an integer number of bytes (e.g.
  # 512000000), a string with a unit (e.g. "512MB"), or a string percentage
  # of the total disk space (e.g. "10%")
  reservedSpace = "30%"
  # maxUsedSpace is the maximum amount of disk space that may be used by
  # this buildkit worker - any usage above this threshold will be reclaimed
  # during garbage collection.
  maxUsedSpace = "60%"
  # minFreeSpace is the target amount of free disk space that the garbage
  # collector will attempt to leave - however, it will never be bought below
  # reservedSpace.
  minFreeSpace = "20GB"
  # alternate OCI worker binary name(example 'crun'), by default either 
  # buildkit-runc or runc binary is used
  binary = ""
  # name of the apparmor profile that should be used to constrain build containers.
  # the profile should already be loaded (by a higher level system) before creating a worker.
  apparmor-profile = ""
  # limit the number of parallel build steps that can run at the same time
  max-parallelism = 4
  # maintain a pool of reusable CNI network namespaces to amortize the overhead
  # of allocating and releasing the namespaces
  cniPoolSize = 16

  [worker.oci.labels]
    "foo" = "bar"

  [[worker.oci.gcpolicy]]
    # reservedSpace is the minimum amount of disk space guaranteed to be
    # retained by this policy - any usage below this threshold will not be
    # reclaimed during # garbage collection.
    reservedSpace = "512MB"
    # maxUsedSpace is the maximum amount of disk space that may be used by this
    # policy - any usage above this threshold will be reclaimed during garbage
    # collection.
    maxUsedSpace = "1GB"
    # minFreeSpace is the target amount of free disk space that the garbage
    # collector will attempt to leave - however, it will never be bought below
    # reservedSpace.
    minFreeSpace = "10GB"
    # keepDuration can be an integer number of seconds (e.g. 172800), or a
    # string duration (e.g. "48h")
    keepDuration = "48h"
    filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"]
  [[worker.oci.gcpolicy]]
    all = true
    reservedSpace = 1024000000

[worker.containerd]
  address = "/run/containerd/containerd.sock"
  enabled = true
  platforms = [ "linux/amd64", "linux/arm64" ]
  namespace = "buildkit"

  # gc enables/disables garbage collection
  gc = true
  # reservedSpace is the minimum amount of disk space guaranteed to be
  # retained by this buildkit worker - any usage below this threshold will not
  # be reclaimed during garbage collection.
  # all disk space parameters can be an integer number of bytes (e.g.
  # 512000000), a string with a unit (e.g. "512MB"), or a string percentage
  # of the total disk space (e.g. "10%")
  reservedSpace = "30%"
  # maxUsedSpace is the maximum amount of disk space that may be used by
  # this buildkit worker - any usage above this threshold will be reclaimed
  # during garbage collection.
  maxUsedSpace = "60%"
  # minFreeSpace is the target amount of free disk space that the garbage
  # collector will attempt to leave - however, it will never be bought below
  # reservedSpace.
  minFreeSpace = "20GB"
  # limit the number of parallel build steps that can run at the same time
  max-parallelism = 4
  # maintain a pool of reusable CNI network namespaces to amortize the overhead
  # of allocating and releasing the namespaces
  cniPoolSize = 16
  # defaultCgroupParent sets the parent cgroup of all containers.
  defaultCgroupParent = "buildkit"

  [worker.containerd.labels]
    "foo" = "bar"

  # configure the containerd runtime
  [worker.containerd.runtime]
    name = "io.containerd.runc.v2"
    path = "/path/to/containerd/runc/shim"
    options = { BinaryName = "runc" }

  [[worker.containerd.gcpolicy]]
    reservedSpace = 512000000
    keepDuration = 172800
    filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout"]
  [[worker.containerd.gcpolicy]]
    all = true
    reservedSpace = 1024000000

# registry configures a new Docker register used for cache import or output.
[registry."docker.io"]
  # mirror configuration to handle path in case a mirror registry requires a /project path rather than just a host:port
  mirrors = ["yourmirror.local:5000", "core.harbor.domain/proxy.docker.io"]
  # Use plain HTTP to connect to the mirrors.
  http = true
  # Use HTTPS with self-signed certificates. Do not enable this together with `http`.
  insecure = true
  # If you use token auth with self-signed certificates,
  # then buildctl also needs to trust the token provider CA (for example, certificates that are configured for registry)
  # because buildctl pulls tokens directly without daemon process
  ca=["/etc/config/myca.pem"]
  [[registry."docker.io".keypair]]
    key="/etc/config/key.pem"
    cert="/etc/config/cert.pem"

# optionally mirror configuration can be done by defining it as a registry.
[registry."yourmirror.local:5000"]
  http = true

# Frontend control
[frontend."dockerfile.v0"]
  enabled = true

[frontend."gateway.v0"]
  enabled = true
  # If allowedRepositories is empty, all gateway sources are allowed.
  # Otherwise, only the listed repositories are allowed as a gateway source.
  # 
  # NOTE: Only the repository name (without tag) is compared.
  #
  # Example:
  # allowedRepositories = [ "docker-registry.wikimedia.org/repos/releng/blubber/buildkit" ]
  allowedRepositories = []

[system]
  # how often buildkit scans for changes in the supported emulated platforms
  platformsCacheMaxAge = "1h"


# optional signed cache configuration for GitHub Actions backend
[ghacache.sign]
# command that signs the payload in stdin and outputs the signature to stdout. Normally you want cosign to produce the signature bytes.
cmd = ""
[ghacache.verify]
required = false
[ghacache.verify.policy]
timestampThreshold = 1
tlogThreshold = 1
# cetificate properties that need to match. Simple wildcards (*) are supported.
certificateIssuer = ""
subjectAlternativeName = ""
buildSignerURI = ""
```

----
url: https://docs.docker.com/dhi/core-concepts/immutability/
----

# Immutable infrastructure

***

Table of contents

***

Immutable infrastructure is a security and operations model where components such as servers, containers, and images are never modified after deployment. Instead of patching or reconfiguring live systems, you replace them entirely with new versions.

When using Docker Hardened Images, immutability is a best practice that reinforces the security posture of your software supply chain.

## [Why immutability matters](#why-immutability-matters)

Mutable systems are harder to secure and audit. Live patching or manual updates introduce risks such as:

* Configuration drift
* Untracked changes
* Inconsistent environments
* Increased attack surface

Immutable infrastructure solves this by making changes only through controlled, repeatable builds and deployments.

## [How Docker Hardened Images support immutability](#how-docker-hardened-images-support-immutability)

Docker Hardened Images are built to be minimal, locked-down, and non-interactive, which discourages in-place modification. For example:

* Many DHI images exclude shells, package managers, and debugging tools
* DHI images are designed to be scanned and signed before deployment
* DHI users are encouraged to rebuild and redeploy images rather than patch running containers

This design aligns with immutable practices and ensures that:

* Updates go through the CI/CD pipeline
* All changes are versioned and auditable
* Systems can be rolled back or reproduced consistently

## [Immutable patterns in practice](#immutable-patterns-in-practice)

Some common patterns that leverage immutability include:

* Container replacement: Instead of logging into a container to fix a bug or apply a patch, rebuild the image and redeploy it.
* Infrastructure as Code (IaC): Define your infrastructure and image configurations in version-controlled files.
* Blue/Green or Canary deployments: Roll out new images alongside old ones and gradually shift traffic to the new version.

By combining immutable infrastructure principles with hardened images, you create a predictable and secure deployment workflow that resists tampering and minimizes long-term risk.

----
url: https://docs.docker.com/guides/testcontainers-dotnet-getting-started/write-tests/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Write tests with Testcontainers

***

Table of contents

***

## [Add Testcontainers dependencies](#add-testcontainers-dependencies)

Add the Testcontainers PostgreSQL module to the test project:

```console
$ dotnet add ./CustomerService.Tests/CustomerService.Tests.csproj package Testcontainers.PostgreSql
```

## [Write the test](#write-the-test)

Create `CustomerServiceTest.cs` in the test project:

```csharp
using Testcontainers.PostgreSql;

namespace Customers.Tests;

public sealed class CustomerServiceTest : IAsyncLifetime
{
    private readonly PostgreSqlContainer _postgres = new PostgreSqlBuilder()
        .WithImage("postgres:16-alpine")
        .Build();

    public Task InitializeAsync()
    {
        return _postgres.StartAsync();
    }

    public Task DisposeAsync()
    {
        return _postgres.DisposeAsync().AsTask();
    }

    [Fact]
    public void ShouldReturnTwoCustomers()
    {
        // Given
        var customerService = new CustomerService(new DbConnectionProvider(_postgres.GetConnectionString()));

        // When
        customerService.Create(new Customer(1, "George"));
        customerService.Create(new Customer(2, "John"));
        var customers = customerService.GetCustomers();

        // Then
        Assert.Equal(2, customers.Count());
    }
}
```

Here's what the test does:

* Declares a `PostgreSqlContainer` using the `PostgreSqlBuilder` with the `postgres:16-alpine` Docker image.

* Implements `IAsyncLifetime` for container lifecycle management:

  * `InitializeAsync()` starts the container before the test runs.
  * `DisposeAsync()` stops and removes the container after the test finishes.

* `ShouldReturnTwoCustomers()` creates a `CustomerService` with connection details from the container, inserts two customers, fetches all customers, and asserts the count.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-dotnet-getting-started/run-tests/)

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/rm/
----

# docker mcp catalog rm

***

| Description | Remove a catalog               |
| ----------- | ------------------------------ |
| Usage       | `docker mcp catalog rm <name>` |

## [Description](#description)

Remove a locally configured catalog. This will delete the catalog and all its server definitions. The Docker official catalog cannot be removed.

## [Examples](#examples)

# [Remove a catalog](#remove-a-catalog)

docker mcp catalog rm old-servers

----
url: https://docs.docker.com/reference/cli/docker/model/logs/
----

# docker model logs

***

| Description | Fetch the Docker Model Runner logs |
| ----------- | ---------------------------------- |
| Usage       | `docker model logs [OPTIONS]`      |

## [Description](#description)

Fetch the Docker Model Runner logs

## [Options](#options)

| Option         | Default | Description                                   |
| -------------- | ------- | --------------------------------------------- |
| `-f, --follow` |         | View logs with real-time streaming            |
| `--no-engines` |         | Exclude inference engine logs from the output |

----
url: https://docs.docker.com/reference/cli/docker/service/
----

# docker service

***

| Description | Manage Swarm services |
| ----------- | --------------------- |
| Usage       | `docker service`      |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Manage Swarm services.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Subcommands](#subcommands)

| Command                                                                                     | Description                                          |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [`docker service create`](https://docs.docker.com/reference/cli/docker/service/create/)     | Create a new service                                 |
| [`docker service inspect`](https://docs.docker.com/reference/cli/docker/service/inspect/)   | Display detailed information on one or more services |
| [`docker service logs`](https://docs.docker.com/reference/cli/docker/service/logs/)         | Fetch the logs of a service or task                  |
| [`docker service ls`](https://docs.docker.com/reference/cli/docker/service/ls/)             | List services                                        |
| [`docker service ps`](https://docs.docker.com/reference/cli/docker/service/ps/)             | List the tasks of one or more services               |
| [`docker service rm`](https://docs.docker.com/reference/cli/docker/service/rm/)             | Remove one or more services                          |
| [`docker service rollback`](https://docs.docker.com/reference/cli/docker/service/rollback/) | Revert changes to a service's configuration          |
| [`docker service scale`](https://docs.docker.com/reference/cli/docker/service/scale/)       | Scale one or multiple replicated services            |
| [`docker service update`](https://docs.docker.com/reference/cli/docker/service/update/)     | Update a service                                     |

----
url: https://docs.docker.com/reference/cli/docker/swarm/join/
----

# docker swarm join

***

| Description | Join a swarm as a node and/or manager   |
| ----------- | --------------------------------------- |
| Usage       | `docker swarm join [OPTIONS] HOST:PORT` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Join a node to a swarm. The node joins as a manager node or worker node based upon the token you pass with the `--token` flag. If you pass a manager token, the node joins as a manager. If you pass a worker token, the node joins as a worker.

## [Options](#options)

| Option                                | Default        | Description                                                                              |
| ------------------------------------- | -------------- | ---------------------------------------------------------------------------------------- |
| [`--advertise-addr`](#advertise-addr) |                | Advertised address (format: `<ip\|interface>[:port]`)                                    |
| [`--availability`](#availability)     | `active`       | Availability of the node (`active`, `pause`, `drain`)                                    |
| [`--data-path-addr`](#data-path-addr) |                | API 1.31+ Address or interface to use for data path traffic (format: `<ip\|interface>`)  |
| [`--listen-addr`](#listen-addr)       | `0.0.0.0:2377` | Listen address (format: `<ip\|interface>[:port]`)                                        |
| [`--token`](#token)                   |                | Token for entry into the swarm                                                           |

## [Examples](#examples)

### [Join a node to swarm as a manager](#join-a-node-to-swarm-as-a-manager)

The example below demonstrates joining a manager node using a manager token.

```console
$ docker swarm join --token SWMTKN-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233... 192.168.99.121:2377
This node joined a swarm as a manager.

$ docker node ls
ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
dkp8vy1dq1kxleu9g4u78tlag *  manager2  Ready   Active        Reachable
dvfxp4zseq4s0rih1selh0d20    manager1  Ready   Active        Leader
```

A cluster should only have 3-7 managers at most, because a majority of managers must be available for the cluster to function. Nodes that aren't meant to participate in this management quorum should join as workers instead. Managers should be stable hosts that have static IP addresses.

### [Join a node to swarm as a worker](#join-a-node-to-swarm-as-a-worker)

The example below demonstrates joining a worker node using a worker token.

```console
$ docker swarm join --token SWMTKN-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233... 192.168.99.121:2377
This node joined a swarm as a worker.

$ docker node ls
ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
7ln70fl22uw2dvjn2ft53m3q5    worker2   Ready   Active
dkp8vy1dq1kxleu9g4u78tlag    worker1   Ready   Active        Reachable
dvfxp4zseq4s0rih1selh0d20 *  manager1  Ready   Active        Leader
```

### [`--listen-addr value`](#listen-addr)

If the node is a manager, it will listen for inbound swarm manager traffic on this address. The default is to listen on 0.0.0.0:2377. It is also possible to specify a network interface to listen on that interface's address; for example `--listen-addr eth0:2377`.

Specifying a port is optional. If the value is a bare IP address, or interface name, the default port 2377 will be used.

This flag is generally not necessary when joining an existing swarm.

### [`--advertise-addr value`](#advertise-addr)

This flag specifies the address that will be advertised to other members of the swarm for API access. If unspecified, Docker will check if the system has a single IP address, and use that IP address with the listening port (see `--listen-addr`). If the system has multiple IP addresses, `--advertise-addr` must be specified so that the correct address is chosen for inter-manager communication and overlay networking.

It is also possible to specify a network interface to advertise that interface's address; for example `--advertise-addr eth0:2377`.

Specifying a port is optional. If the value is a bare IP address, or interface name, the default port 2377 will be used.

This flag is generally not necessary when joining an existing swarm. If you're joining new nodes through a load balancer, you should use this flag to ensure the node advertises its IP address and not the IP address of the load balancer.

### [`--data-path-addr`](#data-path-addr)

This flag specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is then possible to separate the container's data traffic from the management traffic of the cluster. If unspecified, Docker will use the same IP address or interface that is used for the advertise address.

### [`--token string`](#token)

Secret value required for nodes to join the swarm

### [`--availability`](#availability)

This flag specifies the availability of the node at the time the node joins a master. Possible availability values are `active`, `pause`, or `drain`.

This flag is useful in certain situations. For example, a cluster may want to have dedicated manager nodes that are not served as worker nodes. This could be achieved by passing `--availability=drain` to `docker swarm join`.

----
url: https://docs.docker.com/compose/install/linux/
----

# Install the Docker Compose plugin

***

Table of contents

***

This page contains instructions on how to install the Docker Compose plugin on Linux from the command line.

To install the Docker Compose plugin on Linux, you can either:

* [Set up Docker's repository on your Linux system](#install-using-the-repository).
* [Install manually](#install-the-plugin-manually).

> Note
>
> These instructions assume you already have Docker Engine and Docker CLI installed and now want to install the Docker Compose plugin.

## [Install using the repository](#install-using-the-repository)

1. Set up the repository. Find distribution-specific instructions in:

   [Ubuntu](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository) | [CentOS](https://docs.docker.com/engine/install/centos/#set-up-the-repository) | [Debian](https://docs.docker.com/engine/install/debian/#install-using-the-repository) | [Raspberry Pi OS](https://docs.docker.com/engine/install/raspberry-pi-os/#install-using-the-repository) | [Fedora](https://docs.docker.com/engine/install/fedora/#set-up-the-repository) | [RHEL](https://docs.docker.com/engine/install/rhel/#set-up-the-repository).

2. Update the package index, and install the latest version of Docker Compose:

   * For Ubuntu and Debian, run:

     ```console
     $ sudo apt-get update
     $ sudo apt-get install docker-compose-plugin
     ```

   * For RPM-based distributions, run:

     ```console
     $ sudo yum update
     $ sudo yum install docker-compose-plugin
     ```

3. Verify that Docker Compose is installed correctly by checking the version.

   ```console
   $ docker compose version
   ```

### [Update Docker Compose](#update-docker-compose)

To update the Docker Compose plugin, run the following commands:

* For Ubuntu and Debian, run:

  ```console
  $ sudo apt-get update
  $ sudo apt-get install docker-compose-plugin
  ```

* For RPM-based distributions, run:

  ```console
  $ sudo yum update
  $ sudo yum install docker-compose-plugin
  ```

## [Install the plugin manually](#install-the-plugin-manually)

> Warning
>
> Manual installations don’t auto-update. For ease of maintenance, use the Docker repository method.

1. To download and install the Docker Compose CLI plugin, run:

   ```console
   $ DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
   $ mkdir -p $DOCKER_CONFIG/cli-plugins
   $ curl -SL https://github.com/docker/compose/releases/download/v5.1.2/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
   ```

   This command downloads and installs the latest release of Docker Compose for the active user under `$HOME` directory.

   To install:

   * Docker Compose for *all users* on your system, replace `~/.docker/cli-plugins` with `/usr/local/lib/docker/cli-plugins`.
   * A different version of Compose, substitute `v5.1.2` with the version of Compose you want to use.
   * For a different architecture, substitute `x86_64` with the [architecture you want](https://github.com/docker/compose/releases).

2. Apply executable permissions to the binary:

   ```console
   $ chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
   ```

   or, if you chose to install Compose for all users:

   ```console
   $ sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
   ```

3. Test the installation.

   ```console
   $ docker compose version
   ```

## [What's next?](#whats-next)

* [Understand how Compose works](https://docs.docker.com/compose/intro/compose-application-model/)
* [Try the Quickstart guide](https://docs.docker.com/compose/gettingstarted/)

----
url: https://docs.docker.com/engine/containers/resource_constraints/
----

# Resource constraints

***

Table of contents

***

By default, a container has no resource constraints and can use as much of a given resource as the host's kernel scheduler allows. Docker provides ways to control how much memory, or CPU a container can use, setting runtime configuration flags of the `docker run` command. This section provides details on when you should set such limits and the possible implications of setting them.

Many of these features require your kernel to support Linux capabilities. To check for support, you can use the [`docker info`](/reference/cli/docker/system/info/) command. If a capability is disabled in your kernel, you may see a warning at the end of the output like the following:

```console
WARNING: No swap limit support
```

Consult your operating system's documentation for enabling them. See also the [Docker Engine troubleshooting guide](https://docs.docker.com/engine/daemon/troubleshoot/#kernel-cgroup-swap-limit-capabilities) for more information.

## [Memory](#memory)

## [Understand the risks of running out of memory](#understand-the-risks-of-running-out-of-memory)

It's important not to allow a running container to consume too much of the host machine's memory. On Linux hosts, if the kernel detects that there isn't enough memory to perform important system functions, it throws an `OOME`, or `Out Of Memory Exception`, and starts killing processes to free up memory. Any process is subject to killing, including Docker and other important applications. This can effectively bring the entire system down if the wrong process is killed.

Docker attempts to mitigate these risks by adjusting the OOM priority on the Docker daemon so that it's less likely to be killed than other processes on the system. The OOM priority on containers isn't adjusted. This makes it more likely for an individual container to be killed than for the Docker daemon or other system processes to be killed. You shouldn't try to circumvent these safeguards by manually setting `--oom-score-adj` to an extreme negative number on the daemon or a container, or by setting `--oom-kill-disable` on a container.

For more information about the Linux kernel's OOM management, see [Out of Memory Management](https://www.kernel.org/doc/gorman/html/understand/understand016.html).

You can mitigate the risk of system instability due to OOME by:

* Perform tests to understand the memory requirements of your application before placing it into production.
* Ensure that your application runs only on hosts with adequate resources.
* Limit the amount of memory your container can use, as described below.
* Be mindful when configuring swap on your Docker hosts. Swap is slower than memory but can provide a buffer against running out of system memory.
* Consider converting your container to a [service](https://docs.docker.com/engine/swarm/services/), and using service-level constraints and node labels to ensure that the application runs only on hosts with enough memory

### [Limit a container's access to memory](#limit-a-containers-access-to-memory)

Docker can enforce hard or soft memory limits.

* Hard limits let the container use no more than a fixed amount of memory.
* Soft limits let the container use as much memory as it needs unless certain conditions are met, such as when the kernel detects low memory or contention on the host machine.

Some of these options have different effects when used alone or when more than one option is set.

Most of these options take a positive integer, followed by a suffix of `b`, `k`, `m`, `g`, to indicate bytes, kilobytes, megabytes, or gigabytes.

| Option                 | Description                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-m` or `--memory=`    | The maximum amount of memory the container can use. If you set this option, the minimum allowed value is `6m` (6 megabytes). That is, you must set the value to at least 6 megabytes.                                                                                                                                                                                                           |
| `--memory-swap`\*      | The amount of memory this container is allowed to swap to disk. See [`--memory-swap` details](#--memory-swap-details).                                                                                                                                                                                                                                                                          |
| `--memory-swappiness`  | By default, the host kernel can swap out a percentage of anonymous pages used by a container. You can set `--memory-swappiness` to a value between 0 and 100, to tune this percentage. See [`--memory-swappiness` details](#--memory-swappiness-details).                                                                                                                                       |
| `--memory-reservation` | Allows you to specify a soft limit smaller than `--memory` which is activated when Docker detects contention or low memory on the host machine. If you use `--memory-reservation`, it must be set lower than `--memory` for it to take precedence. Because it is a soft limit, it doesn't guarantee that the container doesn't exceed the limit.                                                |
| `--oom-kill-disable`   | By default, if an out-of-memory (OOM) error occurs, the kernel kills processes in a container. To change this behavior, use the `--oom-kill-disable` option. Only disable the OOM killer on containers where you have also set the `-m/--memory` option. If the `-m` flag isn't set, the host can run out of memory and the kernel may need to kill the host system's processes to free memory. |

For more information about cgroups and memory in general, see the documentation for [Memory Resource Controller](https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt).

### [`--memory-swap` details](#--memory-swap-details)

`--memory-swap` is a modifier flag that only has meaning if `--memory` is also set. Using swap allows the container to write excess memory requirements to disk when the container has exhausted all the RAM that's available to it. There is a performance penalty for applications that swap memory to disk often.

Its setting can have complicated effects:

* If `--memory-swap` is set to a positive integer, then both `--memory` and `--memory-swap` must be set. `--memory-swap` represents the total amount of memory and swap that can be used, and `--memory` controls the amount used by non-swap memory. So if `--memory="300m"` and `--memory-swap="1g"`, the container can use 300m of memory and 700m (`1g - 300m`) swap.

* If `--memory-swap` is set to `0`, the setting is ignored, and the value is treated as unset.

* If `--memory-swap` is set to the same value as `--memory`, and `--memory` is set to a positive integer, **the container doesn't have access to swap**. See [Prevent a container from using swap](#prevent-a-container-from-using-swap).

* If `--memory-swap` is unset, and `--memory` is set, the container can use as much swap as the `--memory` setting, if the host container has swap memory configured. For instance, if `--memory="300m"` and `--memory-swap` is not set, the container can use 600m in total of memory and swap.

* If `--memory-swap` is explicitly set to `-1`, the container is allowed to use unlimited swap, up to the amount available on the host system.

* Inside the container, tools like `free` report the host's available swap, not what's available inside the container. Don't rely on the output of `free` or similar tools to determine whether swap is present.

#### [Prevent a container from using swap](#prevent-a-container-from-using-swap)

If `--memory` and `--memory-swap` are set to the same value, this prevents containers from using any swap. This is because `--memory-swap` is the amount of combined memory and swap that can be used, while `--memory` is only the amount of physical memory that can be used.

### [`--memory-swappiness` details](#--memory-swappiness-details)

* A value of 0 turns off anonymous page swapping.
* A value of 100 sets all anonymous pages as swappable.
* By default, if you don't set `--memory-swappiness`, the value is inherited from the host machine.

## [CPU](#cpu)

By default, each container's access to the host machine's CPU cycles is unlimited. You can set various constraints to limit a given container's access to the host machine's CPU cycles. Most users use and configure the [default CFS scheduler](#configure-the-default-cfs-scheduler). You can also configure the [real-time scheduler](#configure-the-real-time-scheduler).

### [Configure the default CFS scheduler](#configure-the-default-cfs-scheduler)

The CFS is the Linux kernel CPU scheduler for normal Linux processes. Several runtime flags let you configure the amount of access to CPU resources your container has. When you use these settings, Docker modifies the settings for the container's cgroup on the host machine.

| Option                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cpus=<value>`       | Specify how much of the available CPU resources a container can use. For instance, if the host machine has two CPUs and you set `--cpus="1.5"`, the container is guaranteed at most one and a half of the CPUs. This is the equivalent of setting `--cpu-period="100000"` and `--cpu-quota="150000"`.                                                                                                                                                                                                                                                                                              |
| `--cpu-period=<value>` | Specify the CPU CFS scheduler period, which is used alongside `--cpu-quota`. Defaults to 100000 microseconds (100 milliseconds). Most users don't change this from the default. For most use-cases, `--cpus` is a more convenient alternative.                                                                                                                                                                                                                                                                                                                                                     |
| `--cpu-quota=<value>`  | Impose a CPU CFS quota on the container. The number of microseconds per `--cpu-period` that the container is limited to before being throttled. As such acting as the effective ceiling. For most use-cases, `--cpus` is a more convenient alternative.                                                                                                                                                                                                                                                                                                                                            |
| `--cpuset-cpus`        | Limit the specific CPUs or cores a container can use. A comma-separated list or hyphen-separated range of CPUs a container can use, if you have more than one CPU. The first CPU is numbered 0. A valid value might be `0-3` (to use the first, second, third, and fourth CPU) or `1,3` (to use the second and fourth CPU).                                                                                                                                                                                                                                                                        |
| `--cpu-shares`         | Set this flag to a value greater or less than the default of 1024 to increase or reduce the container's weight, and give it access to a greater or lesser proportion of the host machine's CPU cycles. This is only enforced when CPU cycles are constrained. When plenty of CPU cycles are available, all containers use as much CPU as they need. In that way, this is a soft limit. `--cpu-shares` doesn't prevent containers from being scheduled in Swarm mode. It prioritizes container CPU resources for the available CPU cycles. It doesn't guarantee or reserve any specific CPU access. |

If you have 1 CPU, each of the following commands guarantees the container at most 50% of the CPU every second.

```console
$ docker run -it --cpus=".5" ubuntu /bin/bash
```

Which is the equivalent to manually specifying `--cpu-period` and `--cpu-quota`;

```console
$ docker run -it --cpu-period=100000 --cpu-quota=50000 ubuntu /bin/bash
```

### [Configure the real-time scheduler](#configure-the-real-time-scheduler)

You can configure your container to use the real-time scheduler, for tasks which can't use the CFS scheduler. You need to [make sure the host machine's kernel is configured correctly](#configure-the-host-machines-kernel) before you can [configure the Docker daemon](#configure-the-docker-daemon) or [configure individual containers](#configure-individual-containers).

> Warning
>
> CPU scheduling and prioritization are advanced kernel-level features. Most users don't need to change these values from their defaults. Setting these values incorrectly can cause your host system to become unstable or unusable.

#### [Configure the host machine's kernel](#configure-the-host-machines-kernel)

Verify that `CONFIG_RT_GROUP_SCHED` is enabled in the Linux kernel by running `zcat /proc/config.gz | grep CONFIG_RT_GROUP_SCHED` or by checking for the existence of the file `/sys/fs/cgroup/cpu.rt_runtime_us`. For guidance on configuring the kernel real-time scheduler, consult the documentation for your operating system.

#### [Configure the Docker daemon](#configure-the-docker-daemon)

To run containers using the real-time scheduler, run the Docker daemon with the `--cpu-rt-runtime` flag set to the maximum number of microseconds reserved for real-time tasks per runtime period. For instance, with the default period of 1000000 microseconds (1 second), setting `--cpu-rt-runtime=950000` ensures that containers using the real-time scheduler can run for 950000 microseconds for every 1000000-microsecond period, leaving at least 50000 microseconds available for non-real-time tasks. To make this configuration permanent on systems which use `systemd`, create a systemd unit file for the `docker` service. For example, see the instruction on how to configure the daemon to use a proxy with a [systemd unit file](https://docs.docker.com/engine/daemon/proxy/#systemd-unit-file).

#### [Configure individual containers](#configure-individual-containers)

You can pass several flags to control a container's CPU priority when you start the container using `docker run`. Consult your operating system's documentation or the `ulimit` command for information on appropriate values.

| Option                     | Description                                                                                                                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cap-add=sys_nice`       | Grants the container the `CAP_SYS_NICE` capability, which allows the container to raise process `nice` values, set real-time scheduling policies, set CPU affinity, and other operations. |
| `--cpu-rt-runtime=<value>` | The maximum number of microseconds the container can run at real-time priority within the Docker daemon's real-time scheduler period. You also need the `--cap-add=sys_nice` flag.        |
| `--ulimit rtprio=<value>`  | The maximum real-time priority allowed for the container. You also need the `--cap-add=sys_nice` flag.                                                                                    |

The following example command sets each of these three flags on a `debian:jessie` container.

```console
$ docker run -it \
    --cpu-rt-runtime=950000 \
    --ulimit rtprio=99 \
    --cap-add=sys_nice \
    debian:jessie
```

If the kernel or Docker daemon isn't configured correctly, an error occurs.

## [GPU](#gpu)

For information on how to access NVIDIA GPUs from a container, see [GPU access](https://docs.docker.com/engine/containers/gpu/).

----
url: https://docs.docker.com/reference/cli/docker/secret/ls/
----

# docker secret ls

***

| Description                                                               | List secrets                 |
| ------------------------------------------------------------------------- | ---------------------------- |
| Usage                                                                     | `docker secret ls [OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker secret list`         |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Run this command on a manager node to list the secrets in the swarm.

For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/).

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --filter`](#filter) |         | Filter output based on conditions provided                                                                                                                                                                                                                                                                                                                                             |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-q, --quiet`             |         | Only display IDs                                                                                                                                                                                                                                                                                                                                                                       |

## [Examples](#examples)

```console
$ docker secret ls

ID                          NAME                        CREATED             UPDATED
6697bflskwj1998km1gnnjr38   q5s5570vtvnimefos1fyeo2u2   6 weeks ago         6 weeks ago
9u9hk4br2ej0wgngkga6rp4hq   my_secret                   5 weeks ago         5 weeks ago
mem02h8n73mybpgqjf0kfi1n0   test_secret                 3 seconds ago       3 seconds ago
```

### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).

The currently supported filters are:

* [id](#id) (secret's ID)
* [label](#label) (`label=<key>` or `label=<key>=<value>`)
* [name](#name) (secret's name)

#### [id](#id)

The `id` filter matches all or prefix of a secret's id.

```console
$ docker secret ls -f "id=6697bflskwj1998km1gnnjr38"

ID                          NAME                        CREATED             UPDATED
6697bflskwj1998km1gnnjr38   q5s5570vtvnimefos1fyeo2u2   6 weeks ago         6 weeks ago
```

#### [label](#label)

The `label` filter matches secrets based on the presence of a `label` alone or a `label` and a value.

The following filter matches all secrets with a `project` label regardless of its value:

```console
$ docker secret ls --filter label=project

ID                          NAME                        CREATED             UPDATED
mem02h8n73mybpgqjf0kfi1n0   test_secret                 About an hour ago   About an hour ago
```

The following filter matches only services with the `project` label with the `project-a` value.

```console
$ docker secret ls --filter label=project=project-a

ID                          NAME                        CREATED             UPDATED
mem02h8n73mybpgqjf0kfi1n0   test_secret                 About an hour ago   About an hour ago
```

#### [name](#name)

The `name` filter matches on all or prefix of a secret's name.

The following filter matches secret with a name containing a prefix of `test`.

```console
$ docker secret ls --filter name=test

ID                          NAME                        CREATED             UPDATED
mem02h8n73mybpgqjf0kfi1n0   test_secret                 About an hour ago   About an hour ago
```

### [Format the output (--format)](#format)

The formatting option (`--format`) pretty prints secrets output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder  | Description                                                                          |
| ------------ | ------------------------------------------------------------------------------------ |
| `.ID`        | Secret ID                                                                            |
| `.Name`      | Secret name                                                                          |
| `.CreatedAt` | Time when the secret was created                                                     |
| `.UpdatedAt` | Time when the secret was updated                                                     |
| `.Labels`    | All labels assigned to the secret                                                    |
| `.Label`     | Value of a specific label for this secret. For example `{{.Label "secret.ssh.key"}}` |

When using the `--format` option, the `secret ls` command will either output the data exactly as the template declares or, when using the `table` directive, will include column headers as well.

The following example uses a template without headers and outputs the `ID` and `Name` entries separated by a colon (`:`) for all images:

```console
$ docker secret ls --format "{{.ID}}: {{.Name}}"

77af4d6b9913: secret-1
b6fa739cedf5: secret-2
78a85c484f71: secret-3
```

To list all secrets with their name and created date in a table format you can use:

```console
$ docker secret ls --format "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}"

ID                  NAME                      CREATED
77af4d6b9913        secret-1                  5 minutes ago
b6fa739cedf5        secret-2                  3 hours ago
78a85c484f71        secret-3                  10 days ago
```

To list all secrets in JSON format, use the `json` directive:

```console
$ docker secret ls --format json
{"CreatedAt":"28 seconds ago","Driver":"","ID":"4y7hvwrt1u8e9uxh5ygqj7mzc","Labels":"","Name":"mysecret","UpdatedAt":"28 seconds ago"}
```

----
url: https://docs.docker.com/subscription/setup/
----

# Set up your subscription

***

Table of contents

***

Docker subscriptions provide features and benefits for individual developers, teams, and enterprise businesses. This page explains how to set up subscriptions for personal accounts and organizations.

Before you begin, make sure you have a [Docker ID](https://docs.docker.com/accounts/create-account/). To learn more about what's included in each tier, see [Docker Pricing](https://www.docker.com/pricing?ref=Docs\&refAction=DocsSubscriptionSetup).

## [Set up a Docker subscription for a personal account](#set-up-a-docker-subscription-for-a-personal-account)

When you [create your Docker ID](https://docs.docker.com/accounts/create-account/), you automatically get a Docker Personal subscription. This subscription includes essential Docker tools at no cost. If you want to continue with Docker Personal, no further action is needed. You can start using Docker Desktop, Docker Hub, and other tools immediately.

If you need additional features like Docker Build Cloud minutes and more Docker Scout repositories, see [Upgrade your subscription](https://docs.docker.com/subscription/change/#upgrade-your-subscription).

## [Set up a Docker subscription for an organization](#set-up-a-docker-subscription-for-an-organization)

You can subscribe a new or existing organization to Docker Team or Business subscriptions. Only organization owners can manage billing for the organization.

1. [Create your Docker ID](https://docs.docker.com/accounts/create-account/) if you don't already have one.
2. [Create your organization](https://docs.docker.com/admin/organization/setup/orgs/) or use an existing organization you own.
3. Select **Billing** to view your current plans, then select **Browse products**.
4. From the products catalog page, select **View plans** from the Docker tile. Choose a Docker Team or Business subscription for the organization.
5. Fill in plan entitlements, verify your billing details, then continue to payment to complete checkout.

## [Set up Docker Hardened Images Select for an organization](#set-up-docker-hardened-images-select-for-an-organization)

Docker Hardened Images (DHI) Select lets organization admins assign DHI repositories to organization accounts. When you add repositories for your organization, all members gain access to those DHI repositories. Members you add to the organization after setup inherit the same access.

To purchase hardened repositories with DHI Select:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Billing**, then **Browse products**.
3. Select **Hardened Images** from the products page.
4. Choose the organization account that should receive the DHI repository, then **Continue**. You can add repositories for one account at a time.
5. Select how many repositories the account can mirror.
6. Verify your billing details, continue to payment, and complete checkout.

> Tip
>
> Purchasing eight or more hardened repositories? [Contact Docker sales](https://www.docker.com/pricing/contact-sales/) to discuss an Enterprise plan.

## [What's next](#whats-next)

* To upgrade an existing organization's subscription, see [Upgrade your subscription](https://docs.docker.com/subscription/change/#upgrade-your-subscription).
* To add more repositories to your DHI Select plan, see [Add DHI repositories](https://docs.docker.com/subscription/scale/#add-dhi-repositories).
* To learn about DHI Select, see [Get started with DHI Select and Enterprise](https://docs.docker.com/dhi/how-to/select-enterprise/).

----
url: https://docs.docker.com/enterprise/security/single-sign-on/troubleshoot-sso/
----

# Troubleshoot single sign-on

***

Table of contents

***

This page describes common single sign-on (SSO) errors and their solutions. Issues can stem from your identity provider (IdP) configuration or Docker settings.

## [Check for errors](#check-for-errors)

If you experience SSO issues, check both Docker and your identity provider for errors first.

### [Check Docker error logs](#check-docker-error-logs)

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down.
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the SSO connections table, select the **Action** menu and then **View error logs**.
4. For more details on specific errors, select **View error details** next to an error message.
5. Note any errors you see on this page for further troubleshooting.

### [Check identity provider errors](#check-identity-provider-errors)

1. Review your IdP’s logs or audit trails for any failed authentication or provisioning attempts.
2. Confirm that your IdP’s SSO settings match the values provided in Docker.
3. If applicable, confirm that you have configured user provisioning correctly and that it is enabled in your IdP.
4. If applicable, verify that your IdP correctly maps Docker's required user attributes.
5. Try provisioning a test user from your IdP and verify if they appear in Docker.

For further troubleshooting, check your IdP's documentation or contact their support team.

## [Groups are not formatted correctly](#groups-are-not-formatted-correctly)

### [Error message](#error-message)

When this issue occurs, the following error message is common:

```text
Some of the groups assigned to the user are not formatted as '<organization name>:<team name>'. Directory groups will be ignored and user will be provisioned into the default organization and team.
```

### [Causes](#causes)

* Incorrect group name formatting in your identity provider (IdP): Docker requires groups to follow the format `<organization>:<team>`. If the groups assigned to a user do not follow this format, they will be ignored.
* Non-matching groups between IdP and Docker organization: If a group in your IdP does not have a corresponding team in Docker, it will not be recognized, and the user will be placed in the default organization and team.

### [Affected environments](#affected-environments)

* Docker single sign-on setup using IdPs such as Okta or Azure AD
* Organizations using group-based role assignments in Docker

### [Steps to replicate](#steps-to-replicate)

To replicate this issue:

1. Attempt to sign in to Docker using SSO.
2. The user is assigned groups in the IdP but does not get placed in the expected Docker Team.
3. Review Docker logs or IdP logs to find the error message.

### [Solutions](#solutions)

Update group names in your IdP:

1. Go to your IdP's group management section.
2. Check the groups assigned to the affected user.
3. Ensure each group follows the required format: `<organization>:<team>`
4. Update any incorrectly formatted groups to match this pattern.
5. Save changes and retry signing in with SSO.

## [User is not assigned to the organization](#user-is-not-assigned-to-the-organization)

### [Error message](#error-message-1)

When this issue occurs, the following error message is common:

```text
User '$username' is not assigned to this SSO organization. Contact your administrator. TraceID: XXXXXXXXXXXXX
```

### [Causes](#causes-1)

* User is not assigned to the organization: If Just-in-Time (JIT) provisioning is disabled, the user may not be assigned to your organization.
* User is not invited to the organization: If JIT is disabled and you do not want to enable it, the user must be manually invited.
* SCIM provisioning is misconfigured: If you use SCIM for user provisioning, it may not be correctly syncing users from your IdP.

### [Solutions](#solutions-1)

**Enable JIT provisioning**

JIT is enabled by default when you enable SSO. If you have JIT disabled and need to re-enable it:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down.
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the SSO connections table, select the **Action** menu and then **Enable JIT provisioning**.
4. Select **Enable** to confirm.

**Manually invite users**

When JIT is disabled, users are not automatically added to your organization when they authenticate through SSO. To manually invite users, see [Invite members](https://docs.docker.com/admin/organization/manage/members/#invite-members).

**Configure SCIM provisioning**

If you have SCIM enabled, troubleshoot your SCIM connection using the following steps:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down.

2. Select **Admin Console**, then **SSO and SCIM**.

3. In the SSO connections table, select the **Action** menu and then **View error logs**. For more details on specific errors, select **View error details** next to an error message. Note any errors you see on this page.

4. Navigate back to the **SSO and SCIM** page of the Admin Console and verify your SCIM configuration:

   * Ensure that the SCIM Base URL and API Token in your IdP match those provided in the Docker Admin Console.
   * Verify that SCIM is enabled in both Docker and your IdP.

5. Ensure that the attributes being synced from your IdP match Docker's [supported attributes](https://docs.docker.com/enterprise/security/provisioning/scim/provision-scim/#supported-attributes) for SCIM.

6. Test user provisioning by trying to provision a test user through your IdP and verify if they appear in Docker.

## [IdP-initiated sign in is not enabled for connection](#idp-initiated-sign-in-is-not-enabled-for-connection)

### [Error message](#error-message-2)

When this issue occurs, the following error message is common:

```text
IdP-Initiated sign in is not enabled for connection '$ssoConnection'.
```

### [Causes](#causes-2)

Docker does not support an IdP-initiated SAML flow. This error occurs when a user attempts to authenticate from your IdP, such as using the Docker SSO app tile on the sign in page.

### [Solutions](#solutions-2)

**Authenticate from Docker apps**

The user must initiate authentication from Docker applications (Hub, Desktop, etc). The user needs to enter their email address in a Docker app and they will get redirected to the configured SSO IdP for their domain.

**Hide the Docker SSO app**

You can hide the Docker SSO app from users in your IdP. This prevents users from attempting to start authentication from the IdP dashboard. You must hide and configure this in your IdP.

## [Not enough seats in organization](#not-enough-seats-in-organization)

### [Error message](#error-message-3)

When this issue occurs, the following error message is common:

```text
Not enough seats in organization '$orgName'. Add more seats or contact your administrator.
```

### [Causes](#causes-3)

This error occurs when the organization has no available seats for the user when provisioning via Just-in-Time (JIT) provisioning or SCIM.

### [Solutions](#solutions-3)

**Add more seats to the organization**

Purchase additional Docker Business subscription seats. For details, see [Manage subscription seats](https://docs.docker.com/subscription/manage-seats/).

**Remove users or pending invitations**

Review your organization members and pending invitations. Remove inactive users or pending invitations to free up seats. For more details, see [Manage organization members](https://docs.docker.com/admin/organization/manage/members/).

## [Domain is not verified for SSO connection](#domain-is-not-verified-for-sso-connection)

### [Error message](#error-message-4)

When this issue occurs, the following error message is common:

```text
Domain '$emailDomain' is not verified for your SSO connection. Contact your company administrator. TraceID: XXXXXXXXXXXXXX
```

### [Causes](#causes-4)

This error occurs if the IdP authenticated a user through SSO and the User Principal Name (UPN) returned to Docker doesn’t match any of the verified domains associated to the SSO connection configured in Docker.

### [Solutions](#solutions-4)

**Verify UPN attribute mapping**

Ensure that the IdP SSO connection is returning the correct UPN value in the assertion attributes.

**Add and verify all domains**

Add and verify all domains and subdomains used as UPN by your IdP and associate them with your Docker SSO connection. For details, see [Configure single sign-on](https://docs.docker.com/enterprise/security/single-sign-on/connect/).

## [Unable to find session](#unable-to-find-session)

### [Error message](#error-message-5)

When this issue occurs, the following error message is common:

```text
We couldn't find your session. You may have pressed the back button, refreshed the page, opened too many sign-in dialogs, or there is some issue with cookies. Try signing in again. If the issue persists, contact your administrator.
```

### [Causes](#causes-5)

The following causes may create this issue:

* The user pressed the back or refresh button during authentication.
* The authentication flow lost track of the initial request, preventing completion.

### [Solutions](#solutions-5)

**Do not disrupt the authentication flow**

Do not press the back or refresh button during sign-in.

**Restart authentication**

Close the browser tab and restart the authentication flow from the Docker application (Desktop, Hub, etc).

## [Name ID is not an email address](#name-id-is-not-an-email-address)

### [Error message](#error-message-6)

When this issue occurs, the following error message is common:

```text
The name ID sent by the identity provider is not an email address. Contact your company administrator.
```

### [Causes](#causes-6)

The following causes may create this issue:

* The IdP sends a Name ID (UPN) that does not comply with the email format required by Docker.
* Docker SSO requires the Name ID to be the primary email address of the user.

### [Solutions](#solutions-6)

In your IdP, ensure the Name ID attribute format is correct:

1. Verify that the Name ID attribute format in your IdP is set to `EmailAddress`.
2. Adjust your IdP settings to return the correct Name ID format.

----
url: https://docs.docker.com/reference/samples/wireguard/
----

# WireGuard samples

| Name                                                                         | Description               |
| ---------------------------------------------------------------------------- | ------------------------- |
| [Wireguard](https://github.com/docker/awesome-compose/tree/master/wireguard) | A sample Wireguard setup. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/ai/sandboxes/usage/
----

# Usage

***

Table of contents

***

## [Working with sandboxes](#working-with-sandboxes)

The basic workflow is [`run`](/reference/cli/sbx/run/) to start, [`ls`](/reference/cli/sbx/ls/) to check status, [`stop`](/reference/cli/sbx/stop/) to pause, and [`rm`](/reference/cli/sbx/rm/) to clean up:

```console
$ sbx run claude                    # start an agent
$ sbx ls                            # see what's running
$ sbx stop my-sandbox               # pause it
$ sbx rm my-sandbox                 # delete it entirely
```

To get a shell inside a running sandbox — useful for inspecting the environment, checking Docker containers, or manually installing something:

```console
$ sbx exec -it <sandbox-name> bash
```

If you need a clean slate, remove the sandbox and re-run:

```console
$ sbx rm my-sandbox
$ sbx run claude
```

## [Non-interactive login](#non-interactive-login)

For CI environments and scripts where a browser is not available, use a Docker Personal Access Token (PAT) with `--username` and `--password-stdin`:

```console
$ echo "$DOCKER_PAT" | sbx login --username <your-docker-id> --password-stdin
```

`--password-stdin` reads the token from standard input to keep it out of your shell history. Generate a PAT from your [Docker account settings](https://app.docker.com/settings/personal-access-tokens) with at least **Read** scope.

## [Interactive mode](#interactive-mode)

Running `sbx` with no subcommands opens an interactive terminal dashboard:

```console
$ sbx
```

The dashboard shows all your sandboxes as cards with live status, CPU, and memory usage. From here you can:

* **Create** a sandbox (`c`).
* **Start or stop** a sandbox (`s`).
* **Attach** to an agent session (`Enter`), same as `sbx run`.
* **Open a shell** inside the sandbox (`x`), same as `sbx exec`.
* **Remove** a sandbox (`r`).

The dashboard also includes a network governance panel where you can monitor outbound connections made by your sandboxes and manage network rules. Use `tab` to switch between the sandboxes panel and the network panel.

From the network panel you can browse connection logs, allow or block specific hosts, and add custom network rules. Press `?` to see all keyboard shortcuts.

## [Git workflow](#git-workflow)

When your workspace is a Git repository, you can choose one of two ways to share it with a sandbox. You make the choice when you create the sandbox:

* **Direct mode (default)** — the agent has read-write access to your working tree. Changes the agent makes appear on your host immediately. Best when you're collaborating turn-by-turn with the agent on a single repository.
* **[Clone mode](#clone-mode) (`--clone`)** — the agent works on a private Git clone inside the sandbox, with your host repository mounted read-only. The sandbox exposes its clone as a Git remote on your host, so you fetch the agent's commits the same way you'd fetch from any other remote. Best when you want the agent isolated from your host repository — for running multiple agents in parallel, working with untrusted code, or keeping your working tree clean while the agent works.

See [Workspace isolation](https://docs.docker.com/ai/sandboxes/security/isolation/#workspace-isolation) for the security model behind each mode.

### [Direct mode (default)](#direct-mode-default)

The agent edits your working tree directly. Stage, commit, and push as you normally would. If you run multiple agents on the same repository at the same time, they may step on each other's changes — use [clone mode](#clone-mode) to give each agent its own isolated workspace.

### [Clone mode](#clone-mode)

In clone mode, the sandbox becomes a Git remote on your host. The agent commits inside the sandbox; you pull its work back out by fetching from that remote.

> Note
>
> Clone mode was introduced in `sbx` v0.31.0 and replaces the `--branch` flag used in earlier versions. If your CLI doesn't recognize `--clone`, update to the latest version.

```console
$ sbx run --clone claude
```

You can also create the sandbox in the background and attach later:

```console
$ sbx create --clone --name my-sandbox claude .
$ sbx run my-sandbox
```

The clone follows whichever ref your host repository has checked out at create time. No new branch is created automatically. If you want the agent to work on a dedicated branch, instruct it to run `git checkout -b my-feature` inside the sandbox before it starts editing. Alternatively, open a shell with `sbx exec` and create the branch yourself.

> Note
>
> Clone mode is fixed at create time. To switch an existing sandbox to clone mode, remove it and recreate it with `sbx create --clone`.

#### [Reviewing and merging the agent's commits](#reviewing-and-merging-the-agents-commits)

The CLI wires the in-sandbox clone as a `sandbox-<sandbox-name>` Git remote on your host. Pull the agent's commits the same way you'd fetch any other remote — no `cd` into a separate directory, no extra tooling:

```console
$ git fetch sandbox-my-sandbox
$ git log sandbox-my-sandbox/<branch>
$ git diff main..sandbox-my-sandbox/<branch>
$ git checkout -b my-feature sandbox-my-sandbox/<branch>
$ git push -u origin my-feature
$ gh pr create
```

If you asked the agent to work on a dedicated branch, `<branch>` is that branch name. Otherwise it's whatever ref your host repository was on at create time.

Some agents don't commit automatically. If `git log sandbox-<name>/<branch>` shows nothing new, open a shell in the sandbox and commit from there:

```console
$ sbx exec -it my-sandbox bash
$ git commit -am "save work"
```

#### [Pushing to your fork from inside the sandbox](#pushing-to-your-fork-from-inside-the-sandbox)

When the sandbox starts, the CLI copies the Git remotes from your host repository (`origin`, `upstream`, and so on) into the in-sandbox clone with their existing URLs. The agent can push to your fork on GitHub directly — for example, by prompting:

> Commit these changes and push them to a new branch on `origin`.

The push uses the same `git push origin ...` invocation the agent would run on the host. This is interchangeable with fetching the commits to your host first and pushing from there.

Local-path remotes (`file://` URLs, filesystem paths) aren't copied, since they aren't reachable from inside the sandbox.

#### [Running multiple branches in parallel](#running-multiple-branches-in-parallel)

A single sandbox can hold several branches at once. Each branch the agent commits to appears as a separate ref on the `sandbox-<name>` remote, so you can fetch them independently from the host:

```console
$ git fetch sandbox-my-sandbox
$ git log sandbox-my-sandbox/feature-a
$ git log sandbox-my-sandbox/feature-b
```

A few common ways to have the agent start each task on its own branch:

* A subagent orchestrator such as Claude Code's [agents view](https://docs.docker.com/ai/sandboxes/agents/claude-code/#agents-view) dispatches each task to a subagent that creates its own worktree inside the clone.
* Agent-level instructions in `CLAUDE.md`, an orchestration skill, or a system prompt include a rule to start each task on a new branch.
* For one-off tasks, ask the agent to switch to a new branch before it starts.

#### [Sandbox lifecycle and the Git remote](#sandbox-lifecycle-and-the-git-remote)

The Git daemon that exposes the in-sandbox clone runs as part of the sandbox itself. It's only reachable while the sandbox is running:

* `sbx stop` shuts down the daemon. `git fetch sandbox-<name>` fails until the sandbox starts again.
* Restarting the sandbox assigns a new ephemeral port to the daemon. The CLI updates the `sandbox-<name>` remote URL in your host repository's Git config automatically, so fetching continues to work without manual reconfiguration.
* `sbx rm` removes the sandbox, the daemon, the published port, and the `sandbox-<name>` remote entry from your host repository.

> Warning
>
> Removing a clone-mode sandbox drops the in-sandbox clone along with it. Any commits you haven't fetched (`git fetch sandbox-<name>`) or pushed to an upstream remote are lost. `sbx rm` prints a warning before deleting a clone-mode sandbox — review it before confirming.

#### [Restrictions](#restrictions)

Clone mode requires a Git repository as the primary workspace, and is rejected at create time in two cases:

* `--clone` on a non-Git workspace. Omit `--clone` for non-Git workspaces.
* `--clone` from inside a Git worktree (other than the main one). The read-only bind mount can't resolve the worktree's `.git` pointer file. Run `sbx create --clone` from the main repository checkout instead.

You can also create a Git worktree yourself and run an agent inside it without `--clone`, but the sandbox won't have access to the `.git` directory in the parent repository, so the agent can't use Git at all. Clone mode is the supported alternative for working on a separate branch.

### [Signed commits](#signed-commits)

Sandboxes can sign Git commits with SSH keys from your host agent. The private key stays on your host.

On the host, load the key into your SSH agent:

```console
$ ssh-add ~/.ssh/id_ed25519
```

Inside the sandbox, check that the forwarded agent exposes the key:

```console
$ ssh-add -L
```

Configure Git globally inside the sandbox to use SSH commit signing. This writes to the sandbox user's Git config, not your repository's `.git/config`. Use an inline public key instead of a key file path, because host paths such as `~/.ssh/id_ed25519.pub` might not exist in the sandbox:

```console
$ git config --global gpg.format ssh
$ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"
```

Then commit as usual:

```console
$ git commit -S
```

For common signing failures, see [Sandbox commits aren't signed](https://docs.docker.com/ai/sandboxes/troubleshooting/#sandbox-commits-arent-signed).

## [Reconnecting and naming](#reconnecting-and-naming)

Sandboxes persist after the agent exits. Running the same workspace path again reconnects to the existing sandbox rather than creating a new one:

```console
$ sbx run claude ~/my-project  # creates sandbox
$ sbx run claude ~/my-project  # reconnects to same sandbox
```

Use `--name` to make this explicit and avoid ambiguity:

```console
$ sbx run claude --name my-project
```

## [Creating without attaching](#creating-without-attaching)

[`sbx run`](/reference/cli/sbx/run/) creates the sandbox and attaches you to the agent. To create a sandbox in the background without attaching:

```console
$ sbx create claude .
```

Unlike `run`, `create` requires an explicit workspace path. It uses direct mode by default, or pass `--clone` for [clone mode](#clone-mode). Attach later with `sbx run`:

```console
$ sbx run claude-my-project
```

## [Multiple workspaces](#multiple-workspaces)

You can mount extra directories into a sandbox alongside the main workspace. The first path is the primary workspace — the agent starts here, and the sandbox's in-container Git clone is populated from this directory if you use `--clone`. Extra workspaces are always mounted directly.

All workspaces appear inside the sandbox at their absolute host paths. Append `:ro` to mount an extra workspace read-only — useful for reference material or shared libraries the agent shouldn't modify:

```console
$ sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro
```

Each sandbox is completely isolated, so you can also run separate projects side-by-side. Remove unused sandboxes when you're done to reclaim disk space:

```console
$ sbx run claude ~/project-a
$ sbx run claude ~/project-b
$ sbx rm <sandbox-name>       # when finished
```

## [Copying files between host and sandbox](#copying-files-between-host-and-sandbox)

Use [`sbx cp`](/reference/cli/sbx/cp/) to copy files or directories between your host and a sandbox. This is useful for one-off files that aren't part of a mounted workspace, such as generated output, logs, or setup files.

```console
$ sbx cp ./config.json my-sandbox:/home/user/
$ sbx cp my-sandbox:/home/user/output.log ./
$ sbx cp ./src/ my-sandbox:/home/user/src
```

One side of the copy must use `SANDBOX:PATH`. Copying directly between two sandboxes isn't supported.

## [Installing dependencies and using Docker](#installing-dependencies-and-using-docker)

Ask the agent to install what's needed — it has sudo access, and installed packages persist for the sandbox's lifetime. For teams or repeated setups, see [Customize](https://docs.docker.com/ai/sandboxes/customize/) for reusable templates and declarative kits.

Agents can also build Docker images, run containers, and use [Compose](https://docs.docker.com/compose/). Everything runs inside the sandbox's private Docker daemon, so containers started by the agent never appear in your host's `docker ps`. When you remove the sandbox, all images, containers, and volumes inside it are deleted with it.

## [Accessing services in the sandbox](#accessing-services-in-the-sandbox)

Sandboxes are [network-isolated](https://docs.docker.com/ai/sandboxes/security/isolation/) — your browser or local tools can't reach a server running inside one by default. Use [`sbx ports`](/reference/cli/sbx/ports/) to forward traffic from your host into a running sandbox.

The common case: an agent has started a dev server or API, and you want to open it in your browser or run tests against it.

```console
$ sbx ports my-sandbox --publish 8080:3000   # host 8080 → sandbox port 3000
$ open http://localhost:8080
```

To let the OS pick a free host port instead of choosing one yourself:

```console
$ sbx ports my-sandbox --publish 3000        # ephemeral host port
$ sbx ports my-sandbox                       # check which port was assigned
```

`sbx ls` shows active port mappings alongside each sandbox, and `sbx ports` lists them in detail:

```console
$ sbx ls
SANDBOX         AGENT   STATUS   PORTS                    WORKSPACE
my-sandbox      claude  running  127.0.0.1:8080->3000/tcp /home/user/proj
```

To stop forwarding a port:

```console
$ sbx ports my-sandbox --unpublish 8080:3000
```

A few things to keep in mind:

* **Services must listen on all interfaces** — a service listening only on `127.0.0.1` inside the sandbox won't be reachable through a published port. Bind to `0.0.0.0` for IPv4, or `[::]` to accept both IPv4 and IPv6. Most dev servers default to `127.0.0.1`, so you'll usually need to pass a flag like `--host 0.0.0.0` or `--host '[::]'` when starting them.
* **`localhost` on the host can resolve to IPv6** — by default, `--publish` listens on both `127.0.0.1` and `::1`. Your browser or client may pick IPv6 when resolving `localhost`. If the sandboxed service only listens on IPv4, the IPv6 connection fails with "connection reset by peer" — even though `http://127.0.0.1:<port>/` works. To fix it, bind the sandboxed service to `[::]` so it accepts both families, or restrict the published port to one family with `--publish 8080:3000/tcp4` (IPv4) or `/tcp6` (IPv6).
* **Not persistent** — published ports are lost when the sandbox stops or the daemon restarts. Re-publish after restarting.
* **No create-time flag** — unlike `docker run -p`, there's no `--publish` option on `sbx run` or `sbx create`. Ports can only be published after the sandbox is running.
* **Unpublish requires the host port** — `--unpublish 3000` is rejected; you must use `--unpublish 8080:3000`. Run `sbx ports my-sandbox` first if you used an ephemeral port and need to find the assigned host port.

## [Accessing host services from a sandbox](#accessing-host-services-from-a-sandbox)

Services running on your host are reachable from inside a sandbox using the hostname `host.docker.internal`. Use this instead of `127.0.0.1` or your machine's local network IP address, which are not reachable from inside the sandbox.

The sandbox proxy translates `host.docker.internal` to `localhost` before forwarding the request, so you must add the `localhost` address with the specific port to your network policy allowlist:

```console
$ sbx policy allow network -g localhost:11434
```

Then use `host.docker.internal` in any configuration or request that points at the host service. For example, to verify connectivity from a sandbox shell:

```console
$ curl http://host.docker.internal:11434
```

## [Rolling out to a team](#rolling-out-to-a-team)

When rolling sandboxes out across a team, two features handle different needs:

* [Custom templates and kits](https://docs.docker.com/ai/sandboxes/customize/) let you package reusable agent configurations, MCP servers, base images, and per-project policies. Every developer pulls them down with their workspace.
* [Organization governance](https://docs.docker.com/ai/sandboxes/security/governance/) lets admins define network and filesystem rules in the Docker Admin Console. The rules apply across every developer's sandboxes and take precedence over local policy. Available on a separate paid subscription.

Customization gives developers shared starting points. Governance gives admins centralized enforcement.

## [What persists](#what-persists)

While a sandbox exists, installed packages, Docker images, configuration changes, and command history all persist across stops and restarts. When you remove a sandbox, everything inside is deleted — only your workspace files remain on your host. To preserve a configured environment, create a [custom template](https://docs.docker.com/ai/sandboxes/customize/templates/).

----
url: https://docs.docker.com/reference/compose-file/version-and-name/
----

# Version and name top-level elements

***

Table of contents

***

## [Version top-level element (obsolete)](#version-top-level-element-obsolete)

> Important
>
> The top-level `version` property is defined by the Compose Specification for backward compatibility. It is only informative and you'll receive a warning message that it is obsolete if used.

Compose always uses the most recent schema to validate the Compose file, regardless of the `version` field.

Compose validates whether it can fully parse the Compose file. If some fields are unknown, typically because the Compose file was written with fields defined by a newer version of the Specification, you'll receive a warning message.

## [Name top-level element](#name-top-level-element)

The top-level `name` property is defined by the Compose Specification as the project name to be used if you don't set one explicitly.

Compose offers a way for you to override this name, and sets a default project name to be used if the top-level `name` element is not set.

Whenever a project name is defined by top-level `name` or by some custom mechanism, it is exposed for [interpolation](https://docs.docker.com/reference/compose-file/interpolation/) and environment variable resolution as `COMPOSE_PROJECT_NAME`

```yml
name: myapp

services:
  foo:
    image: busybox
    command: echo "I'm running ${COMPOSE_PROJECT_NAME}"
```

For more information on other ways to name Compose projects, see [Specify a project name](https://docs.docker.com/compose/how-tos/project-name/).

----
url: https://docs.docker.com/reference/cli/docker/buildx/history/inspect/attachment/
----

# docker buildx history inspect attachment

***

| Description | Inspect a build record attachment                                   |
| ----------- | ------------------------------------------------------------------- |
| Usage       | `docker buildx history inspect attachment [OPTIONS] [REF [DIGEST]]` |

## [Description](#description)

Inspect a specific attachment from a build record, such as a provenance file or SBOM. Attachments are optional artifacts stored with the build and may be platform-specific.

## [Options](#options)

| Option                    | Default | Description            |
| ------------------------- | ------- | ---------------------- |
| [`--platform`](#platform) |         | Platform of attachment |
| [`--type`](#type)         |         | Type of attachment     |

## [Examples](#examples)

### [Inspect an attachment by platform (--platform)](#platform)

```console
$ docker buildx history inspect attachment --platform linux/amd64
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:814e63f06465bc78123775714e4df1ebdda37e6403e0b4f481df74947c047163",
    "size": 600
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:36537f3920ae948ce3e12b4ae34c21190280e6e7d58eeabde0dff3fdfb43b6b0",
      "size": 21664137
    }
  ]
}
```

### [Inspect an attachment by type (--type)](#type)

Supported types include:

* `index`
* `manifest`
* `image`
* `provenance`
* `sbom`

#### [Index](#index)

```console
$ docker buildx history inspect attachment --type index
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:a194e24f47dc6d0e65992c09577b9bc4e7bd0cd5cc4f81e7738918f868aa397b",
      "size": 481,
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:49e40223d6a96ea0667a12737fd3dde004cf217eb48cb28c9191288cd44c6ace",
      "size": 839,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:a194e24f47dc6d0e65992c09577b9bc4e7bd0cd5cc4f81e7738918f868aa397b",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      }
    }
  ]
}
```

#### [Manifest](#manifest)

```console
$ docker buildx history inspect attachment --type manifest
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:814e63f06465bc78123775714e4df1ebdda37e6403e0b4f481df74947c047163",
    "size": 600
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:36537f3920ae948ce3e12b4ae34c21190280e6e7d58eeabde0dff3fdfb43b6b0",
      "size": 21664137
    }
  ]
}
```

#### [Provenance](#provenance)

```console
$ docker buildx history inspect attachment --type provenance
{
  "builder": {
    "id": ""
  },
  "buildType": "https://mobyproject.org/buildkit@v1",
  "materials": [
    {
      "uri": "pkg:docker/docker/dockerfile@1",
      "digest": {
        "sha256": "9ba7531bd80fb0a858632727cf7a112fbfd19b17e94c4e84ced81e24ef1a0dbc"
      }
    },
    {
      "uri": "pkg:docker/golang@1.19.4-alpine?platform=linux%2Farm64",
      "digest": {
        "sha256": "a9b24b67dc83b3383d22a14941c2b2b2ca6a103d805cac6820fd1355943beaf1"
      }
    }
  ],
  "invocation": {
    "configSource": {
      "entryPoint": "Dockerfile"
    },
    "parameters": {
      "frontend": "gateway.v0",
      "args": {
        "cmdline": "docker/dockerfile:1",
        "source": "docker/dockerfile:1",
        "target": "binaries"
      },
      "locals": [
        {
          "name": "context"
        },
        {
          "name": "dockerfile"
        }
      ]
    },
    "environment": {
      "platform": "linux/arm64"
    }
  },
  "metadata": {
    "buildInvocationID": "c4a87v0sxhliuewig10gnsb6v",
    "buildStartedOn": "2022-12-16T08:26:28.651359794Z",
    "buildFinishedOn": "2022-12-16T08:26:29.625483253Z",
    "reproducible": false,
    "completeness": {
      "parameters": true,
      "environment": true,
      "materials": false
    },
    "https://mobyproject.org/buildkit@v1#metadata": {
      "vcs": {
        "revision": "a9ba846486420e07d30db1107411ac3697ecab68",
        "source": "git@github.com:<org>/<repo>.git"
      }
    }
  }
}
```

### [Inspect an attachment by digest](#inspect-an-attachment-by-digest)

You can inspect an attachment directly using its digest, which you can get from the `inspect` output:

```console
# Using a build ID
docker buildx history inspect attachment qu2gsuo8ejqrwdfii23xkkckt sha256:abcdef123456...

# Or using a relative offset
docker buildx history inspect attachment ^0 sha256:abcdef123456...
```

Use `--type sbom` or `--type provenance` to filter attachments by type. To inspect a specific attachment by digest, omit the `--type` flag.

----
url: https://docs.docker.com/reference/api/engine/
----

# Docker Engine API

***

Table of contents

***

Docker provides an API for interacting with the Docker daemon (called the Docker Engine API), as well as SDKs for Go and Python. The SDKs allow you to efficiently build and scale Docker apps and solutions. If Go or Python don't work for you, you can use the Docker Engine API directly.

For information about Docker Engine SDKs, see [Develop with Docker Engine SDKs](https://docs.docker.com/reference/api/engine/sdk/).

The Docker Engine API is a RESTful API accessed by an HTTP client such as `wget` or `curl`, or the HTTP library which is part of most modern programming languages.

## [View the API reference](#view-the-api-reference)

You can [view the reference for the latest version of the API](https://docs.docker.com/reference/api/engine/version/v1.54/) or [choose a specific version](/reference/api/engine/#api-version-matrix).

## [Versioned API and SDK](#versioned-api-and-sdk)

The version of the Docker Engine API you should use depends upon the version of your Docker daemon and Docker client.

A given version of the Docker Engine SDK supports a specific version of the Docker Engine API, as well as all earlier versions. If breaking changes occur, they are documented prominently.

> Note
>
> The Docker daemon and client don't necessarily need to be the same version at all times. However, keep the following in mind.
>
> * If the daemon is newer than the client, the client doesn't know about new features or deprecated API endpoints in the daemon.
>
> * If the client is newer than the daemon, the client can request API endpoints that the daemon doesn't know about.

A new version of the API is released when new features are added. The Docker API is backward-compatible, so you don't need to update code that uses the API unless you need to take advantage of new features.

To see the highest and lowest version of the API your Docker daemon and client support, use `docker version`:

```console
$ docker version
Client: Docker Engine - Community
 Version:           29.5.2
 API version:       1.54
 ...

Server: Docker Engine - Community
 Engine:
  Version:          29.5.2
  API version:      1.54 (minimum version 1.40)
  ...
```

You can specify the API version to use in any of the following ways:

* When using the SDK, use the latest version. At a minimum, use the version that incorporates the API version with the features you need.

* When using `curl` directly, specify the version as the first part of the URL. For instance, if the endpoint is `/containers/` you can use `/v1.54/containers/`.

* To force the Docker CLI or the Docker Engine SDKs to use an older version of the API than the version reported by `docker version`, set the environment variable `DOCKER_API_VERSION` to the correct version. This works on Linux, Windows, and macOS clients.

  ```console
  $ DOCKER_API_VERSION=1.53
  ```

  While the environment variable is set, that version of the API is used, even if the Docker daemon supports a newer version. This environment variable disables API version negotiation, so you should only use it if you must use a specific version of the API, or for debugging purposes.

* The Docker Go SDK allows you to enable API version negotiation, automatically selects an API version that's supported by both the client and the Docker Engine that's in use.

* For the SDKs, you can also specify the API version programmatically as a parameter to the `client` object. See the [Go constructor](https://pkg.go.dev/github.com/docker/docker/client#NewClientWithOpts) or the [Python SDK documentation for `client`](https://docker-py.readthedocs.io/en/stable/client.html).

### [Minimum API version](#minimum-api-version)

The Docker Engine API server and client support API-version negotiation. If a client connects to an older version of the Docker Engine, it negotiates the highest version of the API supported by both the client and daemon, downgrading to an older version of the API if necessary.

When downgrading to an older API version, features introduced in later API versions are disabled, and API requests and responses are adjusted for the API version negotiated.

API version negotiation allows tools that have not been upgraded yet to the latest API version specification to communicate with newer Docker Engines (and vice versa), but compatibility is "best effort"; while Docker strives to provide full compatibility, some functionality may not be available.

### [API version matrix](#api-version-matrix)

| Docker version | Maximum API version                          | Minimum API version                          | Change log                                                         |
| -------------- | -------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
| 29.5           | [1.54](/reference/api/engine/version/v1.54/) | [1.40](/reference/api/engine/version/v1.40/) | [changes](/reference/api/engine/version-history/#v154-api-changes) |
| 29.4           | [1.54](/reference/api/engine/version/v1.54/) | [1.40](/reference/api/engine/version/v1.40/) | [changes](/reference/api/engine/version-history/#v154-api-changes) |
| 29.3           | [1.54](/reference/api/engine/version/v1.54/) | [1.40](/reference/api/engine/version/v1.40/) | [changes](/reference/api/engine/version-history/#v154-api-changes) |
| 29.2           | [1.53](/reference/api/engine/version/v1.53/) | [1.44](/reference/api/engine/version/v1.44/) | [changes](/reference/api/engine/version-history/#v153-api-changes) |
| 29.1           | [1.52](/reference/api/engine/version/v1.52/) | [1.44](/reference/api/engine/version/v1.44/) | [changes](/reference/api/engine/version-history/#v152-api-changes) |
| 29.0           | [1.52](/reference/api/engine/version/v1.52/) | [1.44](/reference/api/engine/version/v1.44/) | [changes](/reference/api/engine/version-history/#v152-api-changes) |
| 28.5           | [1.51](/reference/api/engine/version/v1.51/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v151-api-changes) |
| 28.4           | [1.51](/reference/api/engine/version/v1.51/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v151-api-changes) |
| 28.3           | [1.51](/reference/api/engine/version/v1.51/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v151-api-changes) |
| 28.2           | [1.50](/reference/api/engine/version/v1.50/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v150-api-changes) |
| 28.1           | [1.49](/reference/api/engine/version/v1.49/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v149-api-changes) |
| 28.0           | [1.48](/reference/api/engine/version/v1.48/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v148-api-changes) |
| 27.5           | [1.47](/reference/api/engine/version/v1.47/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v147-api-changes) |
| 27.4           | [1.47](/reference/api/engine/version/v1.47/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v147-api-changes) |
| 27.3           | [1.47](/reference/api/engine/version/v1.47/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v147-api-changes) |
| 27.2           | [1.47](/reference/api/engine/version/v1.47/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v147-api-changes) |
| 27.1           | [1.46](/reference/api/engine/version/v1.46/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v146-api-changes) |
| 27.0           | [1.46](/reference/api/engine/version/v1.46/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v146-api-changes) |
| 26.1           | [1.45](/reference/api/engine/version/v1.45/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v145-api-changes) |
| 26.0           | [1.45](/reference/api/engine/version/v1.45/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v145-api-changes) |
| 25.0           | [1.44](/reference/api/engine/version/v1.44/) | 1.24                                         | [changes](/reference/api/engine/version-history/#v144-api-changes) |
| 24.0           | [1.43](/reference/api/engine/version/v1.43/) | 1.12                                         | [changes](/reference/api/engine/version-history/#v143-api-changes) |
| 23.0           | [1.42](/reference/api/engine/version/v1.42/) | 1.12                                         | [changes](/reference/api/engine/version-history/#v142-api-changes) |
| 20.10          | [1.41](/reference/api/engine/version/v1.41/) | 1.12                                         | [changes](/reference/api/engine/version-history/#v141-api-changes) |
| 19.03          | [1.40](/reference/api/engine/version/v1.40/) | 1.12                                         | [changes](/reference/api/engine/version-history/#v140-api-changes) |

### [Deprecated API versions](#deprecated-api-versions)

API versions before v1.40 are deprecated and no longer supported by current versions of the Docker Engine and CLI. You can find archived documentation for deprecated versions of the API [in the code repository on GitHub](https://github.com/moby/moby/tree/docker-v29.5.2/api/docs):

| Docker version | Maximum API version | Minimum API version | Change log                                                         |
| -------------- | ------------------- | ------------------- | ------------------------------------------------------------------ |
| 18.09          | 1.39                | 1.12                | [changes](/reference/api/engine/version-history/#v139-api-changes) |
| 18.06          | 1.38                | 1.12                | [changes](/reference/api/engine/version-history/#v138-api-changes) |
| 18.05          | 1.37                | 1.12                | [changes](/reference/api/engine/version-history/#v137-api-changes) |
| 18.04          | 1.37                | 1.12                | [changes](/reference/api/engine/version-history/#v137-api-changes) |
| 18.03          | 1.37                | 1.12                | [changes](/reference/api/engine/version-history/#v137-api-changes) |
| 18.02          | 1.36                | 1.12                | [changes](/reference/api/engine/version-history/#v136-api-changes) |
| 17.12          | 1.35                | 1.12                | [changes](/reference/api/engine/version-history/#v135-api-changes) |
| 17.11          | 1.34                | 1.12                | [changes](/reference/api/engine/version-history/#v134-api-changes) |
| 17.10          | 1.33                | 1.12                | [changes](/reference/api/engine/version-history/#v133-api-changes) |
| 17.09          | 1.32                | 1.12                | [changes](/reference/api/engine/version-history/#v132-api-changes) |
| 17.07          | 1.31                | 1.12                | [changes](/reference/api/engine/version-history/#v131-api-changes) |
| 17.06          | 1.30                | 1.12                | [changes](/reference/api/engine/version-history/#v130-api-changes) |
| 17.05          | 1.29                | 1.12                | [changes](/reference/api/engine/version-history/#v129-api-changes) |
| 17.04          | 1.28                | 1.12                | [changes](/reference/api/engine/version-history/#v128-api-changes) |
| 17.03.1        | 1.27                | 1.12                | [changes](/reference/api/engine/version-history/#v127-api-changes) |
| 17.03          | 1.26                | 1.12                | [changes](/reference/api/engine/version-history/#v126-api-changes) |
| 1.13.1         | 1.26                | 1.12                | [changes](/reference/api/engine/version-history/#v126-api-changes) |
| 1.13           | 1.25                | 1.12                | [changes](/reference/api/engine/version-history/#v125-api-changes) |
| 1.12           | 1.24                | 1.12                | [changes](/reference/api/engine/version-history/#v124-api-changes) |
| 1.11           | 1.23                | 1.12                | [changes](/reference/api/engine/version-history/#v123-api-changes) |
| 1.10           | 1.22                | 1.12                | [changes](/reference/api/engine/version-history/#v122-api-changes) |
| 1.9            | 1.21                | 1.12                | [changes](/reference/api/engine/version-history/#v121-api-changes) |
| 1.8            | 1.20                | 1.12                | [changes](/reference/api/engine/version-history/#v120-api-changes) |
| 1.7            | 1.19                | 1.0                 | [changes](/reference/api/engine/version-history/#v119-api-changes) |
| 1.6            | 1.18                | 1.0                 | [changes](/reference/api/engine/version-history/#v118-api-changes) |
| 1.5            | 1.17                | 1.0                 | [changes](/reference/api/engine/version-history/#v117-api-changes) |
| 1.4            | 1.16                | 1.0                 | [changes](/reference/api/engine/version-history/#v116-api-changes) |
| 1.3            | 1.15                | 1.0                 | [changes](/reference/api/engine/version-history/#v115-api-changes) |
| 1.2            | 1.14                | 1.0                 | [changes](/reference/api/engine/version-history/#v114-api-changes) |
| 1.1            | 1.13                | 1.0                 | [changes](/reference/api/engine/version-history/#v113-api-changes) |
| 1.0            | 1.12                | 1.0                 | [changes](/reference/api/engine/version-history/#v112-api-changes) |
| 0.12           | 1.12                | 1.0                 | [changes](/reference/api/engine/version-history/#v112-api-changes) |
| 0.11           | 1.11                | 1.0                 | [changes](/reference/api/engine/version-history/#v111-api-changes) |
| 0.10           | 1.10                | 1.0                 | [changes](/reference/api/engine/version-history/#v110-api-changes) |
| 0.9            | 1.10                | 1.0                 | [changes](/reference/api/engine/version-history/#v110-api-changes) |
| 0.8            | 1.9                 | 1.0                 | [changes](/reference/api/engine/version-history/#v19-api-changes)  |
| 0.7.1          | 1.8                 | 1.0                 | [changes](/reference/api/engine/version-history/#v18-api-changes)  |
| 0.7            | 1.7                 | 1.0                 | [changes](/reference/api/engine/version-history/#v17-api-changes)  |
| 0.6.4          | 1.6                 | 1.0                 | [changes](/reference/api/engine/version-history/#v16-api-changes)  |
| 0.6.2          | 1.5                 | 1.0                 | [changes](/reference/api/engine/version-history/#v15-api-changes)  |
| 0.6            | 1.4                 | 1.0                 | [changes](/reference/api/engine/version-history/#v14-api-changes)  |
| 0.5            | 1.3                 | 1.0                 | [changes](/reference/api/engine/version-history/#v13-api-changes)  |
| 0.4.1          | 1.2                 | 1.0                 | [changes](/reference/api/engine/version-history/#v12-api-changes)  |
| 0.3.4          | 1.1                 | 1.0                 | [changes](/reference/api/engine/version-history/#v11-api-changes)  |
| 0.3.3          | 1.0                 | 1.0                 | [changes](/reference/api/engine/version-history/#v10-api-changes)  |
| 0.3.2          | -                   | -                   |                                                                    |
| 0.2            | -                   | -                   |                                                                    |
| 0.1            | -                   | -                   |                                                                    |

----
url: https://docs.docker.com/engine/swarm/swarm_manager_locking/
----

# Lock your swarm to protect its encryption key

***

Table of contents

***

The Raft logs used by swarm managers are encrypted on disk by default. This at-rest encryption protects your service's configuration and data from attackers who gain access to the encrypted Raft logs. One of the reasons this feature was introduced was in support of the [Docker secrets](https://docs.docker.com/engine/swarm/secrets/) feature.

When Docker restarts, both the TLS key used to encrypt communication among swarm nodes and the key used to encrypt and decrypt Raft logs on disk are loaded into each manager node's memory. Docker has the ability to protect the mutual TLS encryption key and the key used to encrypt and decrypt Raft logs at rest, by allowing you to take ownership of these keys and to require manual unlocking of your managers. This feature is called autolock.

When Docker restarts, you must [unlock the swarm](#unlock-a-swarm) first, using a key encryption key generated by Docker when the swarm was locked. You can rotate this key encryption key at any time.

> Note
>
> You don't need to unlock the swarm when a new node joins the swarm, because the key is propagated to it over mutual TLS.

## [Initialize a swarm with autolocking enabled](#initialize-a-swarm-with-autolocking-enabled)

When you initialize a new swarm, you can use the `--autolock` flag to enable autolocking of swarm manager nodes when Docker restarts.

```console
$ docker swarm init --autolock

Swarm initialized: current node (k1q27tfyx9rncpixhk69sa61v) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-0j52ln6hxjpxk2wgk917abcnxywj3xed0y8vi1e5m9t3uttrtu-7bnxvvlz2mrcpfonjuztmtts9 \
    172.31.46.109:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

To unlock a swarm manager after it restarts, run the `docker swarm unlock`
command and provide the following key:

    SWMKEY-1-WuYH/IX284+lRcXuoVf38viIDK3HJEKY13MIHX+tTt8
```

Store the key in a safe place, such as in a password manager.

When Docker restarts, you need to [unlock the swarm](#unlock-a-swarm). A locked swarm causes an error like the following when you try to start or restart a service:

```console
$ sudo service docker restart

$ docker service ls

Error response from daemon: Swarm is encrypted and needs to be unlocked before it can be used. Use "docker swarm unlock" to unlock it.
```

## [Enable or disable autolock on an existing swarm](#enable-or-disable-autolock-on-an-existing-swarm)

To enable autolock on an existing swarm, set the `autolock` flag to `true`.

```console
$ docker swarm update --autolock=true

Swarm updated.
To unlock a swarm manager after it restarts, run the `docker swarm unlock`
command and provide the following key:

    SWMKEY-1-+MrE8NgAyKj5r3NcR4FiQMdgu+7W72urH0EZeSmP/0Y

Please remember to store this key in a password manager, since without it you
will not be able to restart the manager.
```

To disable autolock, set `--autolock` to `false`. The mutual TLS key and the encryption key used to read and write Raft logs are stored unencrypted on disk. There is a trade-off between the risk of storing the encryption key unencrypted at rest and the convenience of restarting a swarm without needing to unlock each manager.

```console
$ docker swarm update --autolock=false
```

Keep the unlock key around for a short time after disabling autolocking, in case a manager goes down while it is still configured to lock using the old key.

## [Unlock a swarm](#unlock-a-swarm)

To unlock a locked swarm, use `docker swarm unlock`.

```console
$ docker swarm unlock

Please enter unlock key:
```

Enter the encryption key that was generated and shown in the command output when you locked the swarm or rotated the key, and the swarm unlocks.

## [View the current unlock key for a running swarm](#view-the-current-unlock-key-for-a-running-swarm)

Consider a situation where your swarm is running as expected, then a manager node becomes unavailable. You troubleshoot the problem and bring the physical node back online, but you need to unlock the manager by providing the unlock key to read the encrypted credentials and Raft logs.

If the key has not been rotated since the node left the swarm, and you have a quorum of functional manager nodes in the swarm, you can view the current unlock key using `docker swarm unlock-key` without any arguments.

```console
$ docker swarm unlock-key

To unlock a swarm manager after it restarts, run the `docker swarm unlock`
command and provide the following key:

    SWMKEY-1-8jDgbUNlJtUe5P/lcr9IXGVxqZpZUXPzd+qzcGp4ZYA

Please remember to store this key in a password manager, since without it you
will not be able to restart the manager.
```

If the key was rotated after the swarm node became unavailable and you do not have a record of the previous key, you may need to force the manager to leave the swarm and join it back to the swarm as a new manager.

## [Rotate the unlock key](#rotate-the-unlock-key)

You should rotate the locked swarm's unlock key on a regular schedule.

```console
$ docker swarm unlock-key --rotate

Successfully rotated manager unlock key.

To unlock a swarm manager after it restarts, run the `docker swarm unlock`
command and provide the following key:

    SWMKEY-1-8jDgbUNlJtUe5P/lcr9IXGVxqZpZUXPzd+qzcGp4ZYA

Please remember to store this key in a password manager, since without it you
will not be able to restart the manager.
```

> Warning
>
> When you rotate the unlock key, keep a record of the old key around for a few minutes, so that if a manager goes down before it gets the new key, it may still be unlocked with the old one.

----
url: https://docs.docker.com/reference/samples/react/
----

# React samples

| Name                                                                                                     | Description                                                                                                                        |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [React / Spring / MySQL](https://github.com/docker/awesome-compose/tree/master/react-java-mysql)         | A sample React application with a Spring backend and a MySQL database.                                                             |
| [React / Express / MySQL](https://github.com/docker/awesome-compose/tree/master/react-express-mysql)     | A sample React application with a Node.js backend and a MySQL database.                                                            |
| [React / Express / MongoDB](https://github.com/docker/awesome-compose/tree/master/react-express-mongodb) | A sample React application with a Node.js backend and a Mongo database.                                                            |
| [React / Rust / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/react-rust-postgres)   | A sample React application with a Rust backend and a Postgres database.                                                            |
| [React / NGINX](https://github.com/docker/awesome-compose/tree/master/react-nginx)                       | A sample React application with Nginx.                                                                                             |
| [atsea-sample-shop-app](https://github.com/dockersamples/atsea-sample-shop-app)                          | A sample app that uses a Java Spring Boot backend connected to a database to display a fictitious art shop with a React front-end. |
| [slack-clone-docker](https://github.com/dockersamples/slack-clone-docker)                                | A sample Slack Clone app built with the MERN stack.                                                                                |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/ai/docker-agent/tutorial/
----

# Building a coding agent

***

Table of contents

***

This tutorial teaches you how to build a coding agent that can help with software development tasks. You'll start with a basic agent and progressively add capabilities until you have a production-ready assistant that can read code, make changes, run tests, and even look up documentation.

By the end, you'll understand how to structure agent instructions, configure tools, and compose multiple agents for complex workflows.

## [What you'll build](#what-youll-build)

A coding agent that can:

* Read and modify files in your project
* Run commands like tests and linters
* Follow a structured development workflow
* Look up documentation when needed
* Track progress through multi-step tasks

## [What you'll learn](#what-youll-learn)

* How to configure agents in YAML with Docker Agents
* How to give agents access to tools (filesystem, shell, etc.)
* How to write effective agent instructions
* How to compose multiple agents for specialized tasks
* How to adapt agents for your own projects

## [Prerequisites](#prerequisites)

Before starting, you need:

* **Docker Agent installed** - See the [installation guide](https://docs.docker.com/ai/docker-agent/#installation)
* **API key configured** - Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in your environment. Get keys from [Anthropic](https://console.anthropic.com/) or [OpenAI](https://platform.openai.com/api-keys)
* **A project to work with** - Any codebase where you want agent assistance

## [Creating your first agent](#creating-your-first-agent)

An agent is defined in a YAML configuration file. The minimal agent needs just a model and instructions that define its purpose.

Create a file named `agents.yml`:

```yaml
agents:
  root:
    model: openai/gpt-5
    description: A basic coding assistant
    instruction: |
      You are a helpful coding assistant.
      Help me write and understand code.
```

Run your agent:

```console
$ docker agent run agents.yml
```

Try asking it: "How do I read a file in Python?"

The agent can answer coding questions, but it can't see your files or run commands yet. To make it useful for real development work, it needs access to tools.

## [Adding tools](#adding-tools)

A coding agent needs to interact with your project files and run commands. You enable these capabilities by adding toolsets.

Update `agents.yml` to add filesystem and shell access:

```yaml
agents:
  root:
    model: openai/gpt-5
    description: A coding assistant with filesystem access
    instruction: |
      You are a helpful coding assistant.
      You can read and write files to help me develop software.
      Always check if code works before finishing a task.
    toolsets:
      - type: filesystem
      - type: shell
```

Run the updated agent and try: "Read the README.md file and summarize it."

Your agent can now:

* Read and write files in the current directory
* Execute shell commands
* Explore your project structure

> Note
>
> directory. The agent will request permission if it needs to access other directories.

The agent can now interact with your code, but its behavior is still generic. Next, you'll teach it how to work effectively.

## [Structuring agent instructions](#structuring-agent-instructions)

Generic instructions produce generic results. For production use, you want your agent to follow a specific workflow and understand your project's conventions.

Update your agent with structured instructions. This example shows a Go development agent, but you can adapt the pattern for any language:

```yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Expert Go developer
    instruction: |
      Your goal is to help with code-related tasks by examining, modifying,
      and validating code changes.

      TASK
          # Workflow:
          # 1. Analyze: Understand requirements and identify relevant code.
          # 2. Examine: Search for files, analyze structure and dependencies.
          # 3. Modify: Make changes following best practices.
          # 4. Validate: Run linters/tests. If issues found, return to Modify.
      </TASK>

      Constraints:
      - Be thorough in examination before making changes
      - Always validate changes before considering the task complete
      - Write code to files, don't show it in chat

      ## Development Workflow
      - `go build ./...` - Build the application
      - `go test ./...` - Run tests
      - `golangci-lint run` - Check code quality

    add_date: true
    add_environment_info: true
    toolsets:
      - type: filesystem
      - type: shell
      - type: todo
```

Try asking: "Add error handling to the `parseConfig` function in main.go"

The structured instructions give your agent:

* A clear workflow to follow (analyze, examine, modify, validate)
* Project-specific commands to run
* Constraints that prevent common mistakes
* Context about the environment (`add_date` and `add_environment_info`)

The `todo` toolset helps the agent track progress through multi-step tasks. When you ask for complex changes, the agent will break down the work and update its progress as it goes.

## [Composing multiple agents](#composing-multiple-agents)

Complex tasks often benefit from specialized agents. You can add sub-agents that handle specific responsibilities, like researching documentation while your main agent stays focused on coding.

Add a librarian agent that can search for documentation:

```yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Expert Go developer
    instruction: |
      Your goal is to help with code-related tasks by examining, modifying,
      and validating code changes.

      When you need to look up documentation or research how something works,
      ask the librarian agent.

      (rest of instructions from previous section...)
    toolsets:
      - type: filesystem
      - type: shell
      - type: todo
    sub_agents:
      - librarian

  librarian:
    model: anthropic/claude-haiku-4-5
    description: Documentation researcher
    instruction: |
      You are the librarian. Your job is to find relevant documentation,
      articles, or resources to help the developer agent.

      Search the internet and fetch web pages as needed.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo
      - type: fetch
```

Try asking: "How do I use `context.Context` in Go? Then add it to my server code."

Your main agent will delegate the research to the librarian, then use that information to modify your code. This keeps the main agent's context focused on the coding task while still having access to up-to-date documentation.

Using a smaller, faster model (Haiku) for the librarian saves costs since documentation lookup doesn't need the same reasoning depth as code changes.

## [Adapting for your project](#adapting-for-your-project)

Now that you understand the core concepts, adapt the agent for your specific project:

### [Update the development commands](#update-the-development-commands)

Replace the Go commands with your project's workflow:

```yaml
## Development Workflow
- `npm test` - Run tests
- `npm run lint` - Check code quality
- `npm run build` - Build the application
```

### [Add project-specific constraints](#add-project-specific-constraints)

If your agent keeps making the same mistakes, add explicit constraints:

```yaml
Constraints:
  - Always run tests before considering a task complete
  - Follow the existing code style in src/ directories
  - Never modify files in the generated/ directory
  - Use TypeScript strict mode for new files
```

### [Choose the right models](#choose-the-right-models)

For coding tasks, use reasoning-focused models:

* `anthropic/claude-sonnet-4-5` - Strong reasoning, good for complex code
* `openai/gpt-5` - Fast, good general coding ability

For auxiliary tasks like documentation lookup, smaller models work well:

* `anthropic/claude-haiku-4-5` - Fast and cost-effective
* `openai/gpt-5-mini` - Good for simple tasks

### [Iterate based on usage](#iterate-based-on-usage)

The best way to improve your agent is to use it. When you notice issues:

1. Add specific instructions to prevent the problem
2. Update constraints to guide behavior
3. Add relevant commands to the development workflow
4. Consider adding specialized sub-agents for complex areas

## [What you learned](#what-you-learned)

You now know how to:

* Create a basic Docker Agent configuration
* Add tools to enable agent capabilities
* Write structured instructions for consistent behavior
* Compose multiple agents for specialized tasks
* Adapt agents for different programming languages and workflows

## [Next steps](#next-steps)

* Learn [best practices](https://docs.docker.com/ai/docker-agent/best-practices/) for handling large outputs, structuring agent teams, and optimizing performance
* Integrate Docker Agent with your [editor](https://docs.docker.com/ai/docker-agent/integrations/acp/) or use agents as [tools in MCP clients](https://docs.docker.com/ai/docker-agent/integrations/mcp/)
* Review the [Configuration reference](https://docs.docker.com/ai/docker-agent/reference/config/) for all available options
* Explore the [Tools reference](https://docs.docker.com/ai/docker-agent/reference/toolsets/) to see what capabilities you can enable
* Check out [example configurations](https://github.com/docker/docker-agent/tree/main/examples) for different use cases
* See the full [golang\_developer.yaml](https://github.com/docker/docker-agent/blob/main/golang_developer.yaml) that the Docker Team uses to develop Docker Agent

----
url: https://docs.docker.com/reference/cli/docker/sandbox/create/codex/
----

# docker sandbox create codex

***

| Description | Create a sandbox for codex                                   |
| ----------- | ------------------------------------------------------------ |
| Usage       | `docker sandbox create codex WORKSPACE [EXTRA_WORKSPACE...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Create a sandbox with access to a host workspace for codex.

The workspace path is required and will be exposed inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use 'docker sandbox run SANDBOX' to start codex after creation.

## [Examples](#examples)

### [Create a Codex sandbox in the current directory](#create-a-codex-sandbox-in-the-current-directory)

```console
$ docker sandbox create codex .
```

### [Create with an absolute path](#create-with-an-absolute-path)

```console
$ docker sandbox create codex /home/user/my-project
```

### [Create and then run](#create-and-then-run)

```console
$ docker sandbox create --name my-codex codex ~/my-project
$ docker sandbox run my-codex
```

----
url: https://docs.docker.com/reference/cli/docker/container/logs/
----

# docker container logs

***

| Description                                                               | Fetch the logs of a container               |
| ------------------------------------------------------------------------- | ------------------------------------------- |
| Usage                                                                     | `docker container logs [OPTIONS] CONTAINER` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker logs`                               |

## [Description](#description)

The `docker logs` command batch-retrieves logs present at the time of execution.

For more information about selecting and configuring logging drivers, refer to [Configure logging drivers](/engine/logging/configure/).

The `docker logs --follow` command will continue streaming the new output from the container's `STDOUT` and `STDERR`.

Passing a negative number or a non-integer to `--tail` is invalid and the value is set to `all` in that case.

The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://pkg.go.dev/time#RFC3339Nano) , for example `2014-09-16T06:17:46.000000000Z`, to each log entry. To ensure that the timestamps are aligned the nano-second part of the timestamp will be padded with zero when necessary.

The `docker logs --details` command will add on extra attributes, such as environment variables and labels, provided to `--log-opt` when creating the container.

The `--since` option shows only the container logs generated after a given date. You can specify the date as an RFC 3339 date, a UNIX timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date format you may also use RFC3339Nano, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local timezone on the client will be used if you do not provide either a `Z` or a `+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds\[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long. You can combine the `--since` option with either or both of the `--follow` or `--tail` options.

## [Options](#options)

| Option              | Default | Description                                                                                                   |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `--details`         |         | Show extra details provided to logs                                                                           |
| `-f, --follow`      |         | Follow log output                                                                                             |
| `--since`           |         | Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes)               |
| `-n, --tail`        | `all`   | Number of lines to show from the end of the logs                                                              |
| `-t, --timestamps`  |         | Show timestamps                                                                                               |
| [`--until`](#until) |         | API 1.35+ Show logs before a timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes)  |

## [Examples](#examples)

### [Retrieve logs until a specific point in time (--until)](#until)

In order to retrieve logs before a specific point in time, run:

```console
$ docker run --name test -d busybox sh -c "while true; do $(echo date); sleep 1; done"
$ date
Tue 14 Nov 2017 16:40:00 CET
$ docker logs -f --until=2s test
Tue 14 Nov 2017 16:40:00 CET
Tue 14 Nov 2017 16:40:01 CET
Tue 14 Nov 2017 16:40:02 CET
```

----
url: https://docs.docker.com/reference/cli/docker/volume/prune/
----

# docker volume prune

***

| Description | Remove unused local volumes     |
| ----------- | ------------------------------- |
| Usage       | `docker volume prune [OPTIONS]` |

## [Description](#description)

Remove all unused local volumes. Unused local volumes are those which are not referenced by any containers. By default, it only removes anonymous volumes.

## [Options](#options)

| Option                | Default | Description                                                  |
| --------------------- | ------- | ------------------------------------------------------------ |
| [`-a, --all`](#all)   |         | API 1.42+ Remove all unused volumes, not just anonymous ones |
| [`--filter`](#filter) |         | Provide filter values (e.g. `label=<label>`)                 |
| `-f, --force`         |         | Do not prompt for confirmation                               |

## [Examples](#examples)

```console
$ docker volume prune

WARNING! This will remove anonymous local volumes not used by at least one container.
Are you sure you want to continue? [y/N] y
Deleted Volumes:
07c7bdf3e34ab76d921894c2b834f073721fccfbbcba792aa7648e3a7a664c2e

Total reclaimed space: 36 B
```

### [Filtering (--all, -a)](#all)

Use the `--all` flag to prune both unused anonymous and named volumes.

### [Filtering (--filter)](#filter)

The filtering flag (`--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).

When multiple filters are provided, they are combined as follows:

* Multiple filters with **different keys** are combined using AND logic. A volume must satisfy all filter conditions to be pruned.
* Multiple filters with the **same key** are combined using OR logic. A volume is pruned if it matches any of the values for that key.

For example, `--filter "label=foo" --filter "label=bar"` prunes volumes that have **either** the `foo` **or** `bar` label, while `--filter "label=foo" --filter "label!=bar"` prunes volumes that have the `foo` label **and** do not have the `bar` label.

The currently supported filters are:

* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove volumes with (or without, in case `label!=...` is used) the specified labels.

The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`), which removes volumes with the specified labels. The other format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes volumes without the specified labels.

----
url: https://docs.docker.com/admin/activity-logs/
----

# Activity logs

***

Table of contents

***

Subscription: Team Business

For: Administrators

Activity logs display a chronological list of activities that occur at organization and repository levels. The activity log provides organization owners with a record of all member activities.

With activity logs, owners can view and track:

* What changes were made
* The date when a change was made
* Who initiated the change

For example, activity logs display activities such as the date when a repository was created or deleted, the member who created the repository, the name of the repository, and when there was a change to the privacy settings.

Owners can also see the activity logs for their repository if the repository is part of the organization subscribed to a Docker Business or Team subscription.

## [Access activity logs](#access-activity-logs)

To view activity logs in Docker Home:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization.
2. Select **Admin Console**, then **Activity logs**.

To view activity logs using the Docker Hub API, use the [Audit logs endpoints](https://docs.docker.com/reference/api/hub/latest/#tag/audit-logs).

## [Filter and customize activity logs](#filter-and-customize-activity-logs)

> Important
>
> Docker Home retains activity logs for 30 days. To retrieve activities beyond 30 days, you must use the [Docker Hub API](https://docs.docker.com/reference/api/hub/latest/#tag/audit-logs).

By default, the **Activity** tab displays all recorded events within the last 30 days. To narrow your view, use the calendar to select a specific date range. The log updates to show only the activities that occurred during that period.

You can also filter by activity type. Use the **All Activities** drop-down to focus on organization-level, repository-level, or billing-related events. In Docker Hub, when viewing a repository, the **Activities** tab only shows events for that repository.

After selecting a category—**Organization**, **Repository**, or **Billing**—use the **All Actions** drop-down to refine the results even further by specific event type.

> Note
>
> Events triggered by Docker Support appear under the username **dockersupport**.

## [Types of activity log events](#types-of-activity-log-events)

Refer to the following section for a list of events and their descriptions:

### [Organization events](#organization-events)

| Event                                       | Description                                                                   |
| ------------------------------------------- | ----------------------------------------------------------------------------- |
| Team Created                                | Activities related to the creation of a team                                  |
| Team Updated                                | Activities related to the modification of a team                              |
| Team Deleted                                | Activities related to the deletion of a team                                  |
| Team Member Added                           | Details of the member added to your team                                      |
| Team Member Removed                         | Details of the member removed from your team                                  |
| Team Member Invited                         | Details of the member invited to your team                                    |
| Organization Member Added                   | Details of the member added to your organization                              |
| Organization Member Removed                 | Details about the member removed from your organization                       |
| Member Role Changed                         | Details about the role changed for a member in your organization              |
| Organization Created                        | Activities related to the creation of a new organization                      |
| Organization Settings Updated               | Details related to the organization setting that was updated                  |
| Registry Access Management enabled          | Activities related to enabling Registry Access Management                     |
| Registry Access Management disabled         | Activities related to disabling Registry Access Management                    |
| Registry Access Management registry added   | Activities related to the addition of a registry                              |
| Registry Access Management registry removed | Activities related to the removal of a registry                               |
| Registry Access Management registry updated | Details related to the registry that was updated                              |
| Single Sign-On domain added                 | Details of the single sign-on domain added to your organization               |
| Single Sign-On domain removed               | Details of the single sign-on domain removed from your organization           |
| Single Sign-On domain verified              | Details of the single sign-on domain verified for your organization           |
| Access token created                        | Access token created in organization                                          |
| Access token updated                        | Access token updated in organization                                          |
| Access token deleted                        | Access token deleted in organization                                          |
| Policy created                              | Details of adding a settings policy                                           |
| Policy updated                              | Details of updating a settings policy                                         |
| Policy deleted                              | Details of deleting a settings policy                                         |
| Policy transferred                          | Details of transferring a settings policy to another owner                    |
| Create SSO Connection                       | Details of creating a new org/company SSO connection                          |
| Update SSO Connection                       | Details of updating an existing org/company SSO connection                    |
| Delete SSO Connection                       | Details of deleting an existing org/company SSO connection                    |
| Enforce SSO                                 | Details of toggling enforcement on an existing org/company SSO connection     |
| Enforce SCIM                                | Details of toggling SCIM on an existing org/company SSO connection            |
| Refresh SCIM Token                          | Details of a SCIM token refresh on an existing org/company SSO connection     |
| Change SSO Connection Type                  | Details of a connection type change on an existing org/company SSO connection |
| Toggle JIT provisioning                     | Details of a JIT toggle on an existing org/company SSO connection             |

### [Repository events](#repository-events)

> Note
>
> Event descriptions that include a user action can refer to a Docker username, personal access token (PAT) or organization access token (OAT). For example, if a user pushes a tag to a repository, the event would include the description: `<user-access-token>` pushed the tag to the repository.

| Event              | Description                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------- |
| Repository Created | Activities related to the creation of a new repository                                      |
| Repository Deleted | Activities related to the deletion of a repository                                          |
| Repository Updated | Activities related to updating the description, full description, or status of a repository |
| Privacy Changed    | Details related to the privacy policies that were updated                                   |
| Tag Pushed         | Activities related to the tags pushed                                                       |
| Tag Deleted        | Activities related to the tags deleted                                                      |
| Categories Updated | Activities related to setting or updating categories of a repository                        |

### [Billing events](#billing-events)

| Event                                 | Description                                                                                    |
| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Plan Upgraded                         | Occurs when your organization’s billing plan is upgraded to a higher tier plan.                |
| Plan Downgraded                       | Occurs when your organization’s billing plan is downgraded to a lower tier plan.               |
| Seat Added                            | Occurs when a seat is added to your organization’s billing plan.                               |
| Seat Removed                          | Occurs when a seat is removed from your organization’s billing plan.                           |
| Billing Cycle Changed                 | Occurs when there is a change in the recurring interval that your organization is charged.     |
| Plan Downgrade Canceled               | Occurs when a scheduled plan downgrade for your organization is canceled.                      |
| Seat Removal Canceled                 | Occurs when a scheduled seat removal for an organization’s billing plan is canceled.           |
| Plan Upgrade Requested                | Occurs when a user in your organization requests a plan upgrade.                               |
| Plan Downgrade Requested              | Occurs when a user in your organization requests a plan downgrade.                             |
| Seat Addition Requested               | Occurs when a user in your organization requests an increase in the number of seats.           |
| Seat Removal Requested                | Occurs when a user in your organization requests a decrease in the number of seats.            |
| Billing Cycle Change Requested        | Occurs when a user in your organization requests a change in the billing cycle.                |
| Plan Downgrade Cancellation Requested | Occurs when a user in your organization requests a cancellation of a scheduled plan downgrade. |
| Seat Removal Cancellation Requested   | Occurs when a user in your organization requests a cancellation of a scheduled seat removal.   |

### [Offload events](#offload-events)

| Event               | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| Offload Lease Start | Occurs when an Offload lease is started in your organization. |
| Offload Lease End   | Occurs when an Offload lease is ended in your organization.   |

----
url: https://docs.docker.com/reference/cli/docker/container/cp/
----

# docker container cp

***

| Description                                                               | Copy files/folders between a container and the local filesystem                                                     |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Usage                                                                     | `docker container cp [OPTIONS] CONTAINER:SRC_PATH DEST_PATH\|- docker cp [OPTIONS] SRC_PATH\|- CONTAINER:DEST_PATH` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker cp`                                                                                                         |

## [Description](#description)

The `docker cp` utility copies the contents of `SRC_PATH` to the `DEST_PATH`. You can copy from the container's file system to the local machine or the reverse, from the local filesystem to the container. If `-` is specified for either the `SRC_PATH` or `DEST_PATH`, you can also stream a tar archive from `STDIN` or to `STDOUT`. The `CONTAINER` can be a running or stopped container. The `SRC_PATH` or `DEST_PATH` can be a file or directory.

The `docker cp` command assumes container paths are relative to the container's `/` (root) directory. This means supplying the initial forward slash is optional; The command sees `compassionate_darwin:/tmp/foo/myfile.txt` and `compassionate_darwin:tmp/foo/myfile.txt` as identical. Local machine paths can be an absolute or relative value. The command interprets a local machine's relative paths as relative to the current working directory where `docker cp` is run.

The `cp` command behaves like the Unix `cp -a` command in that directories are copied recursively with permissions preserved if possible. Ownership is set to the user and primary group at the destination. For example, files copied to a container are created with `UID:GID` of the root user. Files copied to the local machine are created with the `UID:GID` of the user which invoked the `docker cp` command. However, if you specify the `-a` option, `docker cp` sets the ownership to the user and primary group at the source. If you specify the `-L` option, `docker cp` follows any symbolic link in the `SRC_PATH`. `docker cp` doesn't create parent directories for `DEST_PATH` if they don't exist.

Assuming a path separator of `/`, a first argument of `SRC_PATH` and second argument of `DEST_PATH`, the behavior is as follows:

* `SRC_PATH` specifies a file

  * `DEST_PATH` does not exist
    * the file is saved to a file created at `DEST_PATH`
  * `DEST_PATH` does not exist and ends with `/`
    * Error condition: the destination directory must exist.
  * `DEST_PATH` exists and is a file
    * the destination is overwritten with the source file's contents
  * `DEST_PATH` exists and is a directory
    * the file is copied into this directory using the basename from `SRC_PATH`

* `SRC_PATH` specifies a directory

  * `DEST_PATH` does not exist
    * `DEST_PATH` is created as a directory and the *contents* of the source directory are copied into this directory

  * `DEST_PATH` exists and is a file
    * Error condition: cannot copy a directory to a file

  * `DEST_PATH` exists and is a directory

    * `SRC_PATH` does not end with `/.` (that is: *slash* followed by *dot*)
      * the source directory is copied into this directory
    * `SRC_PATH` does end with `/.` (that is: *slash* followed by *dot*)
      * the *content* of the source directory is copied into this directory

The command requires `SRC_PATH` and `DEST_PATH` to exist according to the above rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not the target, is copied by default. To copy the link target and not the link, specify the `-L` option.

A colon (`:`) is used as a delimiter between `CONTAINER` and its path. You can also use `:` when specifying paths to a `SRC_PATH` or `DEST_PATH` on a local machine, for example `file:name.txt`. If you use a `:` in a local machine path, you must be explicit with a relative or absolute path, for example:

```
`/path/to/file:name.txt` or `./file:name.txt`
```

## [Options](#options)

| Option              | Default | Description                                                                                                   |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `-a, --archive`     |         | Archive mode (copy all uid/gid information)                                                                   |
| `-L, --follow-link` |         | Always follow symlinks in SRC\_PATH                                                                           |
| `-q, --quiet`       |         | Suppress progress output during copy. Progress output is automatically suppressed if no terminal is attached  |

## [Examples](#examples)

Copy a local file into container

```console
$ docker cp ./some_file CONTAINER:/work
```

Copy files from container to local path

```console
$ docker cp CONTAINER:/var/logs/ /tmp/app_logs
```

Copy a file from container to stdout. Note `cp` command produces a tar stream

```console
$ docker cp CONTAINER:/var/logs/app.log - | tar x -O | grep "ERROR"
```

### [Corner cases](#corner-cases)

It isn't possible to copy certain system files such as resources under `/proc`, `/sys`, `/dev`, [tmpfs](/reference/cli/docker/container/run/#tmpfs), and mounts created by the user in the container. However, you can still copy such files by manually running `tar` in `docker exec`. Both of the following examples do the same thing in different ways (consider `SRC_PATH` and `DEST_PATH` are directories):

```console
$ docker exec CONTAINER tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | tar Cxf DEST_PATH -
```

```console
$ tar Ccf $(dirname SRC_PATH) - $(basename SRC_PATH) | docker exec -i CONTAINER tar Cxf DEST_PATH -
```

Using `-` as the `SRC_PATH` streams the contents of `STDIN` as a tar archive. The command extracts the content of the tar to the `DEST_PATH` in container's filesystem. In this case, `DEST_PATH` must specify a directory. Using `-` as the `DEST_PATH` streams the contents of the resource as a tar archive to `STDOUT`.

----
url: https://docs.docker.com/reference/cli/docker/manifest/push/
----

# docker manifest push

***

| Description | Push a manifest list to a repository           |
| ----------- | ---------------------------------------------- |
| Usage       | `docker manifest push [OPTIONS] MANIFEST_LIST` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Push a manifest list to a repository

## [Options](#options)

| Option        | Default | Description                               |
| ------------- | ------- | ----------------------------------------- |
| `--insecure`  |         | Allow push to an insecure registry        |
| `-p, --purge` |         | Remove the local manifest list after push |

----
url: https://docs.docker.com/guides/testcontainers-dotnet-aspnet-core/
----

# Testing an ASP.NET Core web app with Testcontainers

Table of contents

***

Learn how to test an ASP.NET Core web app using Testcontainers for .NET with a real Microsoft SQL Server instance instead of SQLite.

**Time to complete** 25 minutes

In this guide, you'll learn how to:

* Use Testcontainers for .NET to spin up a Microsoft SQL Server container for integration tests
* Replace SQLite with a production-like database provider in ASP.NET Core tests
* Customize `WebApplicationFactory` to configure test dependencies with Testcontainers
* Manage container lifecycle with xUnit's `IAsyncLifetime`

## [Prerequisites](#prerequisites)

* .NET 8.0+ SDK
* A code editor or IDE (Visual Studio, VS Code, Rider)
* A Docker environment supported by Testcontainers. For details, see the [Testcontainers .NET system requirements](https://dotnet.testcontainers.org/supported_docker_environment/).

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-dotnet-aspnet-core/create-project/)

   Set up an ASP.NET Core Razor Pages project with integration test dependencies.

2. [Write tests](https://docs.docker.com/guides/testcontainers-dotnet-aspnet-core/write-tests/)

   Replace SQLite with a real Microsoft SQL Server using Testcontainers for .NET.

3. [Run tests](https://docs.docker.com/guides/testcontainers-dotnet-aspnet-core/run-tests/)

   Run the Testcontainers-based integration tests and explore next steps.

----
url: https://docs.docker.com/reference/cli/docker/buildx/policy/test/
----

# docker buildx policy test

***

| Description | Run policy tests                   |
| ----------- | ---------------------------------- |
| Usage       | `docker buildx policy test <path>` |

## [Description](#description)

Run policy tests

## [Options](#options)

| Option       | Default      | Description                                        |
| ------------ | ------------ | -------------------------------------------------- |
| `--filename` | `Dockerfile` | Name of the Dockerfile to validate                 |
| `--run`      |              | Run only tests with name containing this substring |

----
url: https://docs.docker.com/guides/nodejs/deploy/
----

# Deploy your Node.js application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Containerize a Node.js application](https://docs.docker.com/guides/nodejs/containerize/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to deploy your containerized Node.js application to Kubernetes using Docker Desktop. This deployment uses production-ready configurations including security hardening, auto-scaling, persistent storage, and high availability features.

You'll deploy a complete stack including:

* Node.js Todo application with 3 replicas.
* PostgreSQL database with persistent storage.
* Auto-scaling based on CPU and memory usage.
* Ingress configuration for external access.
* Security settings.

## [Create a Kubernetes deployment file](#create-a-kubernetes-deployment-file)

Create a new file called `nodejs-sample-kubernetes.yaml` in your project root:

```yaml
# ========================================
# Node.js Todo App - Kubernetes Deployment
# ========================================

apiVersion: v1
kind: Namespace
metadata:
  name: todoapp
  labels:
    app: todoapp

---
# ========================================
# ConfigMap for Application Configuration
# ========================================
apiVersion: v1
kind: ConfigMap
metadata:
  name: todoapp-config
  namespace: todoapp
data:
  NODE_ENV: 'production'
  ALLOWED_ORIGINS: 'https://yourdomain.com'
  POSTGRES_HOST: 'todoapp-postgres'
  POSTGRES_PORT: '5432'
  POSTGRES_DB: 'todoapp'
  POSTGRES_USER: 'todoapp'

---
# ========================================
# Secret for Database Credentials
# ========================================
apiVersion: v1
kind: Secret
metadata:
  name: todoapp-secrets
  namespace: todoapp
type: Opaque
data:
  postgres-password: dG9kb2FwcF9wYXNzd29yZA== # base64 encoded "todoapp_password"

---
# ========================================
# PostgreSQL PersistentVolumeClaim
# ========================================
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-pvc
  namespace: todoapp
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
  storageClassName: standard

---
# ========================================
# PostgreSQL Deployment
# ========================================
apiVersion: apps/v1
kind: Deployment
metadata:
  name: todoapp-postgres
  namespace: todoapp
  labels:
    app: todoapp-postgres
spec:
  replicas: 1
  selector:
    matchLabels:
      app: todoapp-postgres
  template:
    metadata:
      labels:
        app: todoapp-postgres
    spec:
      containers:
        - name: postgres
          image: postgres:18-alpine
          ports:
            - containerPort: 5432
              name: postgres
          env:
            - name: POSTGRES_DB
              valueFrom:
                configMapKeyRef:
                  name: todoapp-config
                  key: POSTGRES_DB
            - name: POSTGRES_USER
              valueFrom:
                configMapKeyRef:
                  name: todoapp-config
                  key: POSTGRES_USER
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: todoapp-secrets
                  key: postgres-password
          volumeMounts:
            - name: postgres-storage
              mountPath: /var/lib/postgresql
          livenessProbe:
            exec:
              command:
                - pg_isready
                - -U
                - todoapp
                - -d
                - todoapp
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            exec:
              command:
                - pg_isready
                - -U
                - todoapp
                - -d
                - todoapp
            initialDelaySeconds: 5
            periodSeconds: 5
      volumes:
        - name: postgres-storage
          persistentVolumeClaim:
            claimName: postgres-pvc

---
# ========================================
# PostgreSQL Service
# ========================================
apiVersion: v1
kind: Service
metadata:
  name: todoapp-postgres
  namespace: todoapp
  labels:
    app: todoapp-postgres
spec:
  type: ClusterIP
  ports:
    - port: 5432
      targetPort: 5432
      protocol: TCP
      name: postgres
  selector:
    app: todoapp-postgres

---
# ========================================
# Application Deployment
# ========================================
apiVersion: apps/v1
kind: Deployment
metadata:
  name: todoapp-deployment
  namespace: todoapp
  labels:
    app: todoapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: todoapp
  template:
    metadata:
      labels:
        app: todoapp
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        fsGroup: 1001
      containers:
        - name: todoapp
          image: ghcr.io/your-username/docker-nodejs-sample:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 3000
              name: http
              protocol: TCP
          env:
            - name: NODE_ENV
              valueFrom:
                configMapKeyRef:
                  name: todoapp-config
                  key: NODE_ENV
            - name: ALLOWED_ORIGINS
              valueFrom:
                configMapKeyRef:
                  name: todoapp-config
                  key: ALLOWED_ORIGINS
            - name: POSTGRES_HOST
              valueFrom:
                configMapKeyRef:
                  name: todoapp-config
                  key: POSTGRES_HOST
            - name: POSTGRES_PORT
              valueFrom:
                configMapKeyRef:
                  name: todoapp-config
                  key: POSTGRES_PORT
            - name: POSTGRES_DB
              valueFrom:
                configMapKeyRef:
                  name: todoapp-config
                  key: POSTGRES_DB
            - name: POSTGRES_USER
              valueFrom:
                configMapKeyRef:
                  name: todoapp-config
                  key: POSTGRES_USER
            - name: POSTGRES_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: todoapp-secrets
                  key: postgres-password
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 5
          resources:
            requests:
              memory: '256Mi'
              cpu: '250m'
            limits:
              memory: '512Mi'
              cpu: '500m'
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop:
                - ALL

---
# ========================================
# Application Service
# ========================================
apiVersion: v1
kind: Service
metadata:
  name: todoapp-service
  namespace: todoapp
  labels:
    app: todoapp
spec:
  type: ClusterIP
  ports:
    - name: http
      port: 80
      targetPort: 3000
      protocol: TCP
  selector:
    app: todoapp

---
# ========================================
# Ingress for External Access
# ========================================
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: todoapp-ingress
  namespace: todoapp
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    cert-manager.io/cluster-issuer: 'letsencrypt-prod'
spec:
  tls:
    - hosts:
        - yourdomain.com
      secretName: todoapp-tls
  rules:
    - host: yourdomain.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: todoapp-service
                port:
                  number: 80

---
# ========================================
# HorizontalPodAutoscaler
# ========================================
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: todoapp-hpa
  namespace: todoapp
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: todoapp-deployment
  minReplicas: 1
  maxReplicas: 5
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

---
# ========================================
# PodDisruptionBudget
# ========================================
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: todoapp-pdb
  namespace: todoapp
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: todoapp
```

## [Configure the deployment](#configure-the-deployment)

Before deploying, you need to customize the deployment file for your environment:

1. Image reference: Replace `your-username` with your GitHub username or Docker Hub username:

   ```yaml
   image: ghcr.io/your-username/docker-nodejs-sample:latest
   ```

2. Domain name: Replace `yourdomain.com` with your actual domain in two places:

   ```yaml
   # In ConfigMap
   ALLOWED_ORIGINS: "https://yourdomain.com"

   # In Ingress
   - host: yourdomain.com
   ```

3. Database password (optional): The default password is already base64 encoded. To change it:

   ```console
   $ echo -n "your-new-password" | base64
   ```

   Then update the Secret:

   ```yaml
   data:
     postgres-password: <your-base64-encoded-password>
   ```

4. Storage class: Adjust based on your cluster (current: `standard`)

## [Understanding the deployment](#understanding-the-deployment)

The deployment file creates a complete application stack with multiple components working together.

### [Architecture](#architecture)

The deployment includes:

* Node.js application: Runs 3 replicas of your containerized Todo app
* PostgreSQL database: Single instance with 10Gi of persistent storage
* Services: Kubernetes services handle load balancing across application replicas
* Ingress: External access through an ingress controller with SSL/TLS support

### [Security](#security)

The deployment uses several security features:

* Containers run as a non-root user (UID 1001)
* Read-only root filesystem prevents unauthorized writes
* Linux capabilities are dropped to minimize attack surface
* Sensitive data like database passwords are stored in Kubernetes secrets

### [High availability](#high-availability)

To keep your application running reliably:

* Three application replicas ensure service continues if one pod fails
* Pod disruption budget maintains at least one available pod during updates
* Rolling updates allow zero-downtime deployments
* Health checks on the `/health` endpoint ensure only healthy pods receive traffic

### [Auto-scaling](#auto-scaling)

The Horizontal Pod Autoscaler scales your application based on resource usage:

* Scales between 1 and 5 replicas automatically
* Triggers scaling when CPU usage exceeds 70%
* Triggers scaling when memory usage exceeds 80%
* Resource limits: 256Mi-512Mi memory, 250m-500m CPU per pod

### [Data persistence](#data-persistence)

PostgreSQL data is stored persistently:

* 10Gi persistent volume stores database files
* Database initializes automatically on first startup
* Data persists across pod restarts and updates

## [Deploy your application](#deploy-your-application)

### [Step 1: Deploy to Kubernetes](#step-1-deploy-to-kubernetes)

Deploy your application to the local Kubernetes cluster:

```console
$ kubectl apply -f nodejs-sample-kubernetes.yaml
```

You should see output confirming all resources were created:

```shell
namespace/todoapp created
secret/todoapp-secrets created
configmap/todoapp-config created
persistentvolumeclaim/postgres-pvc created
deployment.apps/todoapp-postgres created
service/todoapp-postgres created
deployment.apps/todoapp-deployment created
service/todoapp-service created
ingress.networking.k8s.io/todoapp-ingress created
poddisruptionbudget.policy/todoapp-pdb created
horizontalpodautoscaler.autoscaling/todoapp-hpa created
```

### [Step 2: Verify the deployment](#step-2-verify-the-deployment)

Check that your deployments are running:

```console
$ kubectl get deployments -n todoapp
```

Expected output:

```shell
NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
todoapp-deployment   3/3     3            3           30s
todoapp-postgres     1/1     1            1           30s
```

Verify your services are created:

```console
$ kubectl get services -n todoapp
```

Expected output:

```shell
NAME               TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
todoapp-service    ClusterIP   10.111.101.229   <none>        80/TCP     45s
todoapp-postgres   ClusterIP   10.111.102.130   <none>        5432/TCP   45s
```

Check that persistent storage is working:

```console
$ kubectl get pvc -n todoapp
```

Expected output:

```shell
NAME           STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
postgres-pvc   Bound    pvc-12345678-1234-1234-1234-123456789012   10Gi       RWO            standard       1m
```

### [Step 3: Access your application](#step-3-access-your-application)

For local testing, use port forwarding to access your application:

```console
$ kubectl port-forward -n todoapp service/todoapp-service 8080:80
```

Open your browser and visit <http://localhost:8080> to see your Todo application running in Kubernetes.

### [Step 4: Test the deployment](#step-4-test-the-deployment)

Test that your application is working correctly:

1. Add some todos through the web interface

2. Check application pods:

   ```console
   $ kubectl get pods -n todoapp -l app=todoapp
   ```

3. View application logs:

   ```console
   $ kubectl logs -f deployment/todoapp-deployment -n todoapp
   ```

4. Check database connectivity:

   ```console
   $ kubectl get pods -n todoapp -l app=todoapp-postgres
   ```

5. Monitor auto-scaling:

   ```console
   $ kubectl describe hpa todoapp-hpa -n todoapp
   ```

### [Step 5: Clean up](#step-5-clean-up)

When you're done testing, remove the deployment:

```console
$ kubectl delete -f nodejs-sample-kubernetes.yaml
```

## [Summary](#summary)

You've deployed your containerized Node.js application to Kubernetes. You learned how to:

* Create a comprehensive Kubernetes deployment file with security hardening
* Deploy a multi-tier application (Node.js + PostgreSQL) with persistent storage
* Configure auto-scaling, health checks, and high availability features
* Test and monitor your deployment locally using Docker Desktop's Kubernetes

Your application is now running in a production-like environment with enterprise-grade features including security contexts, resource management, and automatic scaling.

***

[Automate your builds with GitHub Actions »](https://docs.docker.com/guides/nodejs/configure-github-actions/)

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/pull/
----

# docker mcp catalog pull

***

| Description | Pull a catalog from an OCI registry       |
| ----------- | ----------------------------------------- |
| Usage       | `docker mcp catalog pull <oci-reference>` |

## [Description](#description)

Pull a catalog from an OCI registry

----
url: https://docs.docker.com/reference/compose-file/develop/
----

# Compose Develop Specification

***

Table of contents

***

> Note
>
> Develop is an optional part of the Compose Specification. It is available with Docker Compose version 2.22.0 and later.

This page defines how Compose behaves to efficiently assist you and defines the development constraints and workflows set by Compose. Only a subset of Compose file services may require a `develop` subsection.

## [Illustrative example](#illustrative-example)

```yaml
services:
  frontend:
    image: example/webapp
    build: ./webapp
    develop:
      watch: 
        # sync static content
        - path: ./webapp/html
          action: sync
          target: /var/www
          ignore:
            - node_modules/

  backend:
    image: example/backend
    build: ./backend
    develop:
      watch: 
        # rebuild image and recreate service
        - path: ./backend/src
          action: rebuild
```

## [Attributes](#attributes)

The `develop` subsection defines configuration options that are applied by Compose to assist you during development of a service with optimized workflows.

### [`watch`](#watch)

The `watch` attribute defines a list of rules that control automatic service updates based on local file changes. `watch` is a sequence, each individual item in the sequence defines a rule to be applied by Compose to monitor source code for changes. For more information, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

#### [`action`](#action)

`action` defines the action to take when changes are detected. If `action` is set to:

* `rebuild`: Compose rebuilds the service image based on the `build` section and recreates the service with the updated image.
* `restart`: Compose restarts the service container. Available with Docker Compose version 2.32.0 and later.
* `sync`: Compose keeps the existing service container(s) running, but synchronizes source files with container content according to the `target` attribute.
* `sync+restart`: Compose synchronizes source files with container content according to the `target` attribute, and then restarts the container. Available with Docker Compose version 2.23.0 and later.
* `sync+exec`: Compose synchronizes source files with container content according to the `target` attribute, and then executes a command inside the container. Available with Docker Compose version 2.32.0 and later.

#### [`exec`](#exec)

Requires: Docker Compose [2.32.2](https://github.com/docker/compose/releases/tag/v2.32.2) and later

`exec` is only relevant when `action` is set to `sync+exec`. Like [service hooks](https://docs.docker.com/reference/compose-file/services/#post_start), `exec` is used to define the command to be run inside the container once it has started.

* `command`: Specifies the command to run once the container starts. This attribute is required, and you can choose to use either the shell form or the exec form.
* `user`: The user to run the command. If not set, the command is run with the same user as the main service command.
* `privileged`: Lets the command run with privileged access.
* `working_dir`: The working directory in which to run the command. If not set, it is run in the same working directory as the main service command.
* `environment`: Sets the environment variables to run the command. While the command inherits the environment variables defined for the service’s main command, this section lets you add new variables or override existing ones.

```yaml
services:
  frontend:
    image: ...
    develop:
      watch: 
        # sync content then run command to reload service without interruption
        - path: ./etc/config
          action: sync+exec
          target: /etc/config/
          exec:
            command: app reload
```

#### [`ignore`](#ignore)

The `ignore` attribute is used to define a list of patterns for paths to be ignored. Any updated file that matches a pattern, or belongs to a folder that matches a pattern, won't trigger services to be re-created. The syntax is the same as `.dockerignore` file:

* `*` matches 0 or more characters in a filename.
* `?` matches a single character in filename.
* `*/*` matches two nested folders with arbitrary names
* `**` matches an arbitrary number of nested folders

If the build context includes a `.dockerignore` file, the patterns in this file is loaded as implicit content for the `ignores` file, and values set in the Compose model are appended.

#### [`include`](#include)

It is sometimes easier to select files to be watched instead of declaring those that shouldn't be watched with `ignore`.

The `include` attribute is used to define a pattern, or a list of patterns, for paths to be considered for watching. Only files that match these patterns will be considered when applying a watch rule. The syntax is the same as `ignore`.

```yaml
services:
  backend:
    image: example/backend
    develop:
      watch: 
        # rebuild image and recreate service
        - path: ./src
          include: "*.go"  
          action: rebuild
```

> Note
>
> In many cases `include` patterns start with a wildcard (`*`) character. This has special meaning in YAML syntax to define an [alias node](https://yaml.org/spec/1.2.2/#alias-nodes) so you have to wrap pattern expression with quotes.

#### [`initial_sync`](#initial_sync)

When using `sync+x` actions, it can be useful to ensure that files inside containers are up to date at the start of a new watch session.

The `initial_sync` attribute instructs the Compose runtime, if containers for the service already exist, to check that the files from the path attribute are in sync within the service containers.

#### [`path`](#path)

`path` attribute defines the path to source code (relative to the project directory) to monitor for changes. Updates to any file inside the path, which doesn't match any `ignore` rule, triggers the configured action.

#### [`target`](#target)

`target` attribute only applies when `action` is configured for `sync`. Files within `path` that have changes are synchronized with the container's filesystem, so that the latter is always running with up-to-date content.

----
url: https://docs.docker.com/reference/cli/docker/model/package/
----

# docker model package

***

| Description | Package a model into a Docker Model OCI artifact                                                                                                                                       |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Usage       | `docker model package (--gguf <path> \| --safetensors-dir <path> \| --dduf <path> \| --from <model>) [--license <path>...] [--mmproj <path>] [--context-size <tokens>] [--push] MODEL` |

## [Description](#description)

Package a model into a Docker Model OCI artifact.

The model source must be one of: --gguf A GGUF file (single file or first shard of a sharded model) --safetensors-dir A directory containing .safetensors and configuration files --dduf A .dduf (Diffusers Unified Format) archive --from An existing packaged model reference

By default, the packaged artifact is loaded into the local Model Runner content store. Use --push to publish the model to a registry instead.

MODEL specifies the target model reference (for example: myorg/llama3:8b). When using --push, MODEL must be a registry-qualified reference.

Packaging behavior:

GGUF --gguf must point to a .gguf file. For sharded models, point to the first shard. All shards must: • reside in the same directory • follow an indexed naming convention (e.g. model-00001-of-00015.gguf) All shards are automatically discovered and packaged together.

Safetensors --safetensors-dir must point to a directory containing .safetensors files and required configuration files (e.g. model config, tokenizer files). All files under the directory (including nested subdirectories) are automatically discovered. Each file is packaged as a separate OCI layer.

DDUF --dduf must point to a .dduf archive file.

Repackaging --from repackages an existing model. You may override selected properties such as --context-size to create a variant of the original model.

Multimodal models Use --mmproj to include a multimodal projector file.

## [Options](#options)

| Option              | Default  | Description                                                                             |
| ------------------- | -------- | --------------------------------------------------------------------------------------- |
| `--chat-template`   |          | absolute path to chat template file (must be Jinja format)                              |
| `--context-size`    |          | context size in tokens                                                                  |
| `--dduf`            |          | absolute path to DDUF archive file (Diffusers Unified Format)                           |
| `--format`          | `docker` | output artifact format: "docker" (default) or "cncf" (CNCF ModelPack spec)              |
| `--from`            |          | reference to an existing model to repackage                                             |
| `--gguf`            |          | absolute path to gguf file                                                              |
| `-l, --license`     |          | absolute path to a license file                                                         |
| `--mmproj`          |          | absolute path to multimodal projector file                                              |
| `--push`            |          | push to registry (if not set, the model is loaded into the Model Runner content store)  |
| `--safetensors-dir` |          | absolute path to directory containing safetensors files and config                      |

----
url: https://docs.docker.com/docker-hub/repos/delete/
----

# Delete a repository

***

***

> Warning
>
> Deleting a repository deletes all the images it contains and its build settings. This action can't be undone.

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Settings** tab.

5. Select **Delete repository**.

6. Enter the name of your repository to confirm.

7. Select **Delete Repository Forever**.

----
url: https://docs.docker.com/reference/build-checks/undefined-arg-in-from/
----

# UndefinedArgInFrom

***

Table of contents

***

## [Output](#output)

```text
FROM argument 'VARIANT' is not declared
```

## [Description](#description)

This rule warns for cases where you're consuming an undefined build argument in `FROM` instructions.

Interpolating build arguments in `FROM` instructions can be a good way to add flexibility to your build, and lets you pass arguments that overriding the base image of a stage. For example, you might use a build argument to specify the image tag:

```dockerfile
ARG ALPINE_VERSION=3.20

FROM alpine:${ALPINE_VERSION}
```

This makes it possible to run the build with a different `alpine` version by specifying a build argument:

```console
$ docker buildx build --build-arg ALPINE_VERSION=edge .
```

This check also tries to detect and warn when a `FROM` instruction reference miss-spelled built-in build arguments, like `BUILDPLATFORM`.

## [Examples](#examples)

❌ Bad: the `VARIANT` build argument is undefined.

```dockerfile
FROM node:22${VARIANT} AS jsbuilder
```

✅ Good: the `VARIANT` build argument is defined.

```dockerfile
ARG VARIANT="-alpine3.20"
FROM node:22${VARIANT} AS jsbuilder
```

----
url: https://docs.docker.com/reference/build-checks/invalid-definition-description/
----

# InvalidDefinitionDescription

***

Table of contents

***

> Note
>
> This check is experimental and is not enabled by default. To enable it, see [Experimental checks](https://docs.docker.com/go/build-checks-experimental/).

## [Output](#output)

```text
Comment for build stage or argument should follow the format: `# <arg/stage name> <description>`. If this is not intended to be a description comment, add an empty line or comment between the instruction and the comment.
```

## [Description](#description)

The [`--call=outline`](https://docs.docker.com/reference/cli/docker/buildx/build/#call-outline) and [`--call=targets`](https://docs.docker.com/reference/cli/docker/buildx/build/#call-outline) flags for the `docker build` command print descriptions for build targets and arguments. The descriptions are generated from [Dockerfile comments](https://docs.docker.com/reference/cli/docker/buildx/build/#descriptions) that immediately precede the `FROM` or `ARG` instruction and that begin with the name of the build stage or argument. For example:

```dockerfile
# build-cli builds the CLI binary
FROM alpine AS build-cli
# VERSION controls the version of the program
ARG VERSION=1
```

In cases where preceding comments are not meant to be descriptions, add an empty line or comment between the instruction and the preceding comment.

## [Examples](#examples)

❌ Bad: A non-descriptive comment on the line preceding the `FROM` command.

```dockerfile
# a non-descriptive comment
FROM scratch AS base

# another non-descriptive comment
ARG VERSION=1
```

✅ Good: An empty line separating non-descriptive comments.

```dockerfile
# a non-descriptive comment

FROM scratch AS base

# another non-descriptive comment

ARG VERSION=1
```

✅ Good: Comments describing `ARG` keys and stages immediately proceeding the command.

```dockerfile
# base is a stage for compiling source
FROM scratch AS base
# VERSION This is the version number.
ARG VERSION=1
```

----
url: https://docs.docker.com/reference/cli/sbx/exec/
----

# sbx exec

| Description | Execute a command inside a sandbox          |
| ----------- | ------------------------------------------- |
| Usage       | `sbx exec [flags] SANDBOX COMMAND [ARG...]` |

## [Description](#description)

Execute a command in a sandbox. If the sandbox is stopped, it is started first.

Flags match the behavior of "docker exec".

## [Options](#options)

| Option              | Default | Description                                             |
| ------------------- | ------- | ------------------------------------------------------- |
| `-d, --detach`      |         | Detached mode: run command in the background            |
| `--detach-keys`     |         | Override the key sequence for detaching a container     |
| `-e, --env`         |         | Set environment variables                               |
| `--env-file`        |         | Read in a file of environment variables                 |
| `-i, --interactive` |         | Keep STDIN open even if not attached                    |
| `--privileged`      |         | Give extended privileges to the command                 |
| `-t, --tty`         |         | Allocate a pseudo-TTY                                   |
| `-u, --user`        |         | Username or UID (format: \<name\|uid>\[:\<group\|gid>]) |
| `-w, --workdir`     |         | Working directory inside the container                  |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Open a shell inside a sandbox
sbx exec -it my-sandbox bash

# Run a command in the background
sbx exec -d my-sandbox npm start

# Run as root
sbx exec -u root my-sandbox apt-get update
```

----
url: https://docs.docker.com/reference/samples/plex/
----

# Plex samples

| Name                                                               | Description          |
| ------------------------------------------------------------------ | -------------------- |
| [Plex](https://github.com/docker/awesome-compose/tree/master/plex) | A sample Plex setup. |

----
url: https://docs.docker.com/guides/testcontainers-java-mockserver/create-project/
----

# Create the Spring Boot project

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Spring Boot project from [Spring Initializr](https://start.spring.io) by selecting the **Spring Web**, **Spring Reactive Web**, and **Testcontainers** starters.

Alternatively, clone the [guide repository](https://github.com/testcontainers/tc-guide-testing-rest-api-integrations-using-mockserver).

After generating the project, add the **REST Assured** and **MockServer** libraries as test dependencies. The key dependencies in `pom.xml` are:

```xml
<properties>
    <java.version>17</java.version>
    <testcontainers.version>2.0.4</testcontainers.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-mockserver</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.mock-server</groupId>
        <artifactId>mockserver-netty</artifactId>
        <version>5.15.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

Using the Testcontainers BOM (Bill of Materials) is recommended so that you don't have to repeat the version for every Testcontainers module dependency.

This guide builds an application that manages video albums. A third-party REST API handles photo assets. For demonstration purposes, the application uses the publicly available [JSONPlaceholder](https://jsonplaceholder.typicode.com/) API as a photo service.

The application exposes a `GET /api/albums/{albumId}` endpoint that calls the photo service to fetch photos for a given album. [MockServer](https://www.mock-server.com/) is a library for mocking HTTP-based services. Testcontainers provides a [MockServer module](https://java.testcontainers.org/modules/mockserver/) that runs MockServer as a Docker container.

## [Create the Album and Photo models](#create-the-album-and-photo-models)

Create `Album.java` using Java records:

```java
package com.testcontainers.demo;

import java.util.List;

public record Album(Long albumId, List<Photo> photos) {}

record Photo(Long id, String title, String url, String thumbnailUrl) {}
```

## [Create the PhotoServiceClient interface](#create-the-photoserviceclient-interface)

Spring Framework 6 introduced [declarative HTTP client support](https://docs.spring.io/spring-framework/reference/integration/rest-clients.html#rest-http-interface). Create an interface with a method that fetches photos for a given album ID:

```java
package com.testcontainers.demo;

import java.util.List;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.service.annotation.GetExchange;

interface PhotoServiceClient {
  @GetExchange("/albums/{albumId}/photos")
  List<Photo> getPhotos(@PathVariable Long albumId);
}
```

## [Register PhotoServiceClient as a bean](#register-photoserviceclient-as-a-bean)

To generate a runtime implementation of `PhotoServiceClient`, register it as a Spring bean using `HttpServiceProxyFactory`. The factory requires an `HttpClientAdapter` implementation. Spring Boot provides `WebClientAdapter` as part of the `spring-webflux` library:

```java
package com.testcontainers.demo;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.reactive.function.client.support.WebClientAdapter;
import org.springframework.web.service.invoker.HttpServiceProxyFactory;

@Configuration
public class AppConfig {

  @Bean
  public PhotoServiceClient photoServiceClient(
    @Value("${photos.api.base-url}") String photosApiBaseUrl
  ) {
    WebClient client = WebClient.builder().baseUrl(photosApiBaseUrl).build();
    HttpServiceProxyFactory factory = HttpServiceProxyFactory
      .builder(WebClientAdapter.forClient(client))
      .build();
    return factory.createClient(PhotoServiceClient.class);
  }
}
```

The photo service base URL is externalized as a configuration property. Add the following entry to `src/main/resources/application.properties`:

```properties
photos.api.base-url=https://jsonplaceholder.typicode.com
```

## [Create the REST API endpoint](#create-the-rest-api-endpoint)

Create `AlbumController.java`:

```java
package com.testcontainers.demo;

import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.reactive.function.client.WebClientResponseException;

@RestController
@RequestMapping("/api")
class AlbumController {

  private static final Logger logger = LoggerFactory.getLogger(
    AlbumController.class
  );

  private final PhotoServiceClient photoServiceClient;

  AlbumController(PhotoServiceClient photoServiceClient) {
    this.photoServiceClient = photoServiceClient;
  }

  @GetMapping("/albums/{albumId}")
  public ResponseEntity<Album> getAlbumById(@PathVariable Long albumId) {
    try {
      List<Photo> photos = photoServiceClient.getPhotos(albumId);
      return ResponseEntity.ok(new Album(albumId, photos));
    } catch (WebClientResponseException e) {
      logger.error("Failed to get photos", e);
      return new ResponseEntity<>(e.getStatusCode());
    }
  }
}
```

This endpoint calls the photo service for a given album ID and returns a response like:

```json
{
  "albumId": 1,
  "photos": [
    {
      "id": 51,
      "title": "non sunt voluptatem placeat consequuntur rem incidunt",
      "url": "https://via.placeholder.com/600/8e973b",
      "thumbnailUrl": "https://via.placeholder.com/150/8e973b"
    },
    {
      "id": 52,
      "title": "eveniet pariatur quia nobis reiciendis laboriosam ea",
      "url": "https://via.placeholder.com/600/121fa4",
      "thumbnailUrl": "https://via.placeholder.com/150/121fa4"
    }
  ]
}
```

[Write tests with Testcontainers MockServer »](https://docs.docker.com/guides/testcontainers-java-mockserver/write-tests/)

----
url: https://docs.docker.com/compose/how-tos/production/
----

# Use Compose in production

***

Table of contents

***

When you define your app with Compose in development, you can use this definition to run your application in different environments such as CI, staging, and production.

The easiest way to deploy an application is to run it on a single server, similar to how you would run your development environment. If you want to scale up your application, you can run Compose apps on a Swarm cluster.

### [Modify your Compose file for production](#modify-your-compose-file-for-production)

You may need to make changes to your app configuration to make it ready for production. These changes might include:

* Removing any volume bindings for application code, so that code stays inside the container and can't be changed from outside
* Binding to different ports on the host
* Setting environment variables differently, such as reducing the verbosity of logging, or to specify settings for external services such as an email server
* Specifying a restart policy like [`restart: always`](https://docs.docker.com/reference/compose-file/services/#restart)to avoid downtime
* Adding extra services such as a log aggregator

For this reason, consider defining an additional Compose file, for example `compose.production.yaml`, with production-specific configuration details. This configuration file only needs to include the changes you want to make from the original Compose file. The additional Compose file is then applied over the original `compose.yaml` to create a new configuration.

Once you have a second configuration file, you can use it with the `-f` option:

```console
$ docker compose -f compose.yaml -f compose.production.yaml up -d
```

See [Using multiple compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/) for a more complete example, and other options.

### [Deploying changes](#deploying-changes)

When you make changes to your app code, remember to rebuild your image and recreate your app's containers. To redeploy a service called `web`, use:

```console
$ docker compose build web
$ docker compose up --no-deps -d web
```

This first command rebuilds the image for `web` and then stops, destroys, and recreates just the `web` service. The `--no-deps` flag prevents Compose from also recreating any services that `web` depends on.

### [Running Compose on a single server](#running-compose-on-a-single-server)

You can use Compose to deploy an app to a remote Docker host by setting the `DOCKER_HOST`, `DOCKER_TLS_VERIFY`, and `DOCKER_CERT_PATH` environment variables appropriately. For more information, see [pre-defined environment variables](https://docs.docker.com/compose/how-tos/environment-variables/envvars/).

Once you've set up your environment variables, all the normal `docker compose` commands work with no further configuration.

## [Next steps](#next-steps)

* [Familiarize yourself with Compose's trust model](https://docs.docker.com/compose/trust-model/)
* [Using multiple Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/)

----
url: https://docs.docker.com/guides/azure-pipelines/
----

[Introduction to Azure Pipelines with Docker](https://docs.docker.com/guides/azure-pipelines/)

Learn how to automate Docker image build and push using Azure Pipelines.

DevOps

10 minutes

[« Back to all guides](/guides/)

# Introduction to Azure Pipelines with Docker

***

Table of contents

***

> This guide is a community contribution. Docker would like to thank [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for his valuable contribution.

## [Prerequisites](#prerequisites)

Before you begin, ensure you have the following requirements:

* A [Docker Hub account](https://hub.docker.com) with a generated access token.
* An active [Azure DevOps project](https://dev.azure.com/) with a connected [Git repository](https://learn.microsoft.com/en-us/azure/devops/repos/git/?view=azure-devops).
* A project that includes a valid [`Dockerfile`](https://docs.docker.com/engine/reference/builder/) at its root or appropriate build context.

## [Overview](#overview)

This guide walks you through building and pushing Docker images using [Azure Pipelines](https://azure.microsoft.com/en-us/products/devops/pipelines), enabling a streamlined and secure CI workflow for containerized applications. You’ll learn how to:

* Configure Docker authentication securely.
* Set up an automated pipeline to build and push images.

## [Set up Azure DevOps to work with Docker Hub](#set-up-azure-devops-to-work-with-docker-hub)

### [Step 1: Configure a Docker Hub service connection](#step-1-configure-a-docker-hub-service-connection)

To securely authenticate with Docker Hub using Azure Pipelines:

1. Navigate to **Project Settings > Service Connections** in your Azure DevOps project.
2. Select **New service connection > Docker Registry**.
3. Choose **Docker Hub** and provide your Docker Hub credentials or access token.
4. Give the service connection a recognizable name, such as `my-docker-registry`.
5. Grant access only to the specific pipeline(s) that require it for improved security and least privilege.

> Important
>
> Avoid selecting the option to grant access to all pipelines unless absolutely necessary. Always apply the principle of least privilege.

### [Step 2: Create your pipeline](#step-2-create-your-pipeline)

Add the following `azure-pipelines.yml` file to the root of your repository:

```yaml
# Trigger pipeline on commits to the main branch
trigger:
  - main

# Trigger pipeline on pull requests targeting the main branch
pr:
  - main

# Define variables for reuse across the pipeline
variables:
  imageName: 'docker.io/$(dockerUsername)/my-image'
  buildTag: '$(Build.BuildId)'
  latestTag: 'latest'

stages:
  - stage: BuildAndPush
    displayName: Build and Push Docker Image
    jobs:
      - job: DockerJob
        displayName: Build and Push
        pool:
          vmImage: ubuntu-latest
          demands:
            - docker
        steps:
          - checkout: self
            displayName: Checkout Code

          - task: Docker@2
            displayName: Docker Login
            inputs:
              command: login
              containerRegistry: 'my-docker-registry'  # Service connection name

          - task: Docker@2
            displayName: Build Docker Image
            inputs:
              command: build
              repository: $(imageName)
              tags: |
                $(buildTag)
                $(latestTag)
              dockerfile: './Dockerfile'
              arguments: |
                --sbom=true
                --attest type=provenance
                --cache-from $(imageName):latest
            env:
              DOCKER_BUILDKIT: 1

          - task: Docker@2
            displayName: Push Docker Image
            condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
            inputs:
              command: push
              repository: $(imageName)
              tags: |
                $(buildTag)
                $(latestTag)

          # Optional: logout for self-hosted agents
          - script: docker logout
            displayName: Docker Logout (Self-hosted only)
            condition: ne(variables['Agent.OS'], 'Windows_NT')
```

## [What this pipeline does](#what-this-pipeline-does)

This pipeline automates the Docker image build and deployment process for the main branch. It ensures a secure and efficient workflow with best practices like caching, tagging, and conditional cleanup. Here's what it does:

* Triggers on commits and pull requests targeting the `main` branch.
* Authenticates securely with Docker Hub using an Azure DevOps service connection.
* Builds and tags the Docker image using Docker BuildKit for caching.
* Pushes both buildId and latest tags to Docker Hub.
* Logs out from Docker if running on a self-hosted Linux agent.

## [How the pipeline works](#how-the-pipeline-works)

### [Step 1: Define pipeline triggers](#step-1-define-pipeline-triggers)

```yaml
trigger:
  - main

pr:
  - main
```

This pipeline is triggered automatically on:

* Commits pushed to the `main` branch
* Pull requests targeting `main` main branch

> Tip
>
> Learn more: [Define pipeline triggers in Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/triggers?view=azure-devops)

### [Step 2: Define common variables](#step-2-define-common-variables)

```yaml
variables:
  imageName: 'docker.io/$(dockerUsername)/my-image'
  buildTag: '$(Build.BuildId)'
  latestTag: 'latest'
```

These variables ensure consistent naming, versioning, and reuse throughout the pipeline steps:

* `imageName`: your image path on Docker Hub
* `buildTag`: a unique tag for each pipeline run
* `latestTag`: a stable alias for your most recent image

> Important
>
> The variable `dockerUsername` is not set automatically.\
> Set it securely in your Azure DevOps pipeline variables:
>
> 1. Go to **Pipelines > Edit > Variables**
> 2. Add `dockerUsername` with your Docker Hub username
>
> Learn more: [Define and use variables in Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops\&tabs=yaml%2Cbatch)

### [Step 3: Define pipeline stages and jobs](#step-3-define-pipeline-stages-and-jobs)

```yaml
stages:
  - stage: BuildAndPush
    displayName: Build and Push Docker Image
```

This stage executes only if the source branch is `main`.

> Tip
>
> Learn more: [Stage conditions in Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/stages?view=azure-devops\&tabs=yaml)

### [Step 4: Job configuration](#step-4-job-configuration)

```yaml
jobs:
  - job: DockerJob
  displayName: Build and Push
  pool:
    vmImage: ubuntu-latest
    demands:
      - docker
```

This job utilizes the latest Ubuntu VM image with Docker support, provided by Microsoft-hosted agents. It can be replaced with a custom pool for self-hosted agents if necessary.

> Tip
>
> Learn more: [Specify a pool in your pipeline](https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/pools-queues?view=azure-devops\&tabs=yaml%2Cbrowser)

#### [Step 4.1: Checkout code](#step-41-checkout-code)

```yaml
steps:
  - checkout: self
    displayName: Checkout Code
```

This step pulls your repository code into the build agent, so the pipeline can access the Dockerfile and application files.

> Tip
>
> Learn more: [checkout step documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/yaml-schema/steps-checkout?view=azure-pipelines)

#### [Step 4.2: Authenticate to Docker Hub](#step-42-authenticate-to-docker-hub)

```yaml
- task: Docker@2
  displayName: Docker Login
  inputs:
    command: login
    containerRegistry: 'my-docker-registry'  # Replace with your service connection name
```

Uses a pre-configured Azure DevOps Docker registry service connection to authenticate securely without exposing credentials directly.

> Tip
>
> Learn more: [Use service connections for Docker Hub](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/service-endpoints?view=azure-devops#docker-hub-or-others)

#### [Step 4.3: Build the Docker image](#step-43-build-the-docker-image)

```yaml
 - task: Docker@2
    displayName: Build Docker Image
    inputs:
      command: build
      repository: $(imageName)
      tags: |
          $(buildTag)
          $(latestTag)
      dockerfile: './Dockerfile'
      arguments: |
          --sbom=true
          --attest type=provenance
          --cache-from $(imageName):latest
    env:
      DOCKER_BUILDKIT: 1
```

This builds the image with:

* Two tags: one with the unique Build ID and one as latest
* Docker BuildKit enabled for faster builds and efficient layer caching
* Cache pull from the most recent pushed latest image
* Software Bill of Materials (SBOM) for supply chain transparency
* Provenance attestation to verify how and where the image was built

> Tip
>
> Learn more:
>
> * [Docker task for Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/docker-v2?view=azure-pipelines\&tabs=yaml)
> * [Docker SBOM Attestations](https://docs.docker.com/build/metadata/attestations/slsa-provenance/)

#### [Step 4.4: Push the Docker image](#step-44-push-the-docker-image)

```yaml
- task: Docker@2
  displayName: Push Docker Image
  condition: eq(variables['Build.SourceBranch'], 'refs/heads/main')
  inputs:
      command: push
      repository: $(imageName)
      tags: |
        $(buildTag)
        $(latestTag)
```

By applying this condition, the pipeline builds the Docker image on every run to ensure early detection of issues, but only pushes the image to the registry when changes are merged into the main branch—keeping your Docker Hub clean and focused

This uploads both tags to Docker Hub:

* `$(buildTag)` ensures traceability per run.
* `latest` is used for most recent image references.

#### [Step 4.5 Logout of Docker (self-hosted agents)](#step-45--logout-of-docker-self-hosted-agents)

```yaml
- script: docker logout
  displayName: Docker Logout (Self-hosted only)
  condition: ne(variables['Agent.OS'], 'Windows_NT')
```

Executes docker logout at the end of the pipeline on Linux-based self-hosted agents to proactively clean up credentials and enhance security posture.

## [Summary](#summary)

With this Azure Pipelines CI setup, you get:

* Secure Docker authentication using a built-in service connection.
* Automated image building and tagging triggered by code changes.
* Efficient builds leveraging Docker BuildKit cache.
* Safe cleanup with logout on persistent agents.
* Build images that meet modern software supply chain requirements with SBOM and attestation

## [Learn more](#learn-more)

* [Azure Pipelines Documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/?view=azure-devops): Comprehensive guide to configuring and managing CI/CD pipelines in Azure DevOps.
* [Docker Task for Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/build/docker): Detailed reference for using the Docker task in Azure Pipelines to build and push images.
* [Docker Buildx Bake](https://docs.docker.com/build/bake/): Explore Docker's advanced build tool for complex, multi-stage, and multi-platform build setups. See also the [Mastering Buildx Bake Guide](https://docs.docker.com/guides/bake/) for practical examples and best practices.
* [Docker Build Cloud](https://docs.docker.com/guides/docker-build-cloud/): Learn about Docker's managed build service for faster, scalable, and multi-platform image builds in the cloud.

----
url: https://docs.docker.com/build/policies/usage/
----

# Using build policies

***

Table of contents

***

Build policies validate inputs before builds execute. This guide covers how to develop policies iteratively and apply them to real builds with `docker buildx build` and `docker buildx bake`.

## [Prerequisites](#prerequisites)

* Buildx 0.31.0 or later - Check your version: `docker buildx version`
* BuildKit 0.26.0 or later - Verify with: `docker buildx inspect --bootstrap`

If you're using Docker Desktop, ensure you're on a version that includes these updates.

## [Policy development workflow](#policy-development-workflow)

Buildx automatically loads policies that match your Dockerfile name. When you build with `Dockerfile`, Buildx looks for `Dockerfile.rego` in the same directory. For a file named `app.Dockerfile`, it looks for `app.Dockerfile.rego`. See the [Advanced: Policy configuration](#advanced-policy-configuration) section for configuration options and manual policy loading.

Writing policies is an iterative process:

1. Start with a basic deny-all policy.
2. Build with debug logging to see what inputs your Dockerfile uses.
3. Add rules to allow specific sources based on the debug output.
4. Test and refine.

### [Viewing inputs from your Dockerfile](#viewing-inputs-from-your-dockerfile)

To see the inputs that your Dockerfile references (images, Git repos, HTTP downloads), build with debug logging:

```console
$ docker buildx build --progress=plain --policy log-level=debug .
```

Example output for an image source:

```text
#1 0.010 checking policy for source docker-image://alpine:3.19 (linux/arm64)
#1 0.011 policy input: {
#1 0.011   "env": {
#1 0.011     "filename": "."
#1 0.011   },
#1 0.011   "image": {
#1 0.011     "ref": "docker.io/library/alpine:3.19",
#1 0.011     "host": "docker.io",
#1 0.011     "repo": "alpine",
#1 0.011     "tag": "3.19",
#1 0.011     "platform": "linux/arm64"
#1 0.011   }
#1 0.011 }
#1 0.011 unknowns for policy evaluation: [input.image.checksum input.image.labels ...]
#1 0.012 policy decision for source docker-image://alpine:3.19: ALLOW
```

This shows the complete input structure, which fields are unresolved, and the policy decision for each source. See [Input reference](https://docs.docker.com/build/policies/inputs/) for all available fields.

### [Testing policies with policy eval](#testing-policies-with-policy-eval)

Use [`docker buildx policy eval`](/reference/cli/docker/buildx/policy/eval/) to test whether your policy allows a specific source without running a full build.

Note: `docker buildx policy eval` tests the source specified as the argument. It doesn't parse your Dockerfile to evaluate all inputs - for that, [build with --progress=plain](#viewing-inputs-from-your-dockerfile).

Test if your policy allows the local context:

```console
$ docker buildx policy eval .
```

No output means the policy allowed the source. If denied, you see:

```console
ERROR: policy denied
```

Test other sources:

```console
$ docker buildx policy eval https://example.com              # Test HTTP
$ docker buildx policy eval https://github.com/org/repo.git  # Test Git
```

By default, `--print` shows reference information parsed from the source string (like `repo`, `tag`, `host`) without fetching from registries. To inspect metadata that requires fetching the source (like `labels`, `checksum`, or `hasProvenance`), specify which fields to fetch with `--fields`:

```console
$ docker buildx policy eval --print --fields image.labels docker-image://alpine:3.19
```

Multiple fields can be specified as a comma-separated list.

### [Iterative development example](#iterative-development-example)

Here's a practical workflow for developing policies:

1. Start with basic deny-all policy:

   Dockerfile.rego

   ```rego
   package docker

   default allow := false

   allow if input.local

   decision := {"allow": allow}
   ```

2. Build with debug logging to see what inputs your Dockerfile uses:

   ```console
   $ docker buildx build --progress=plain --policy log-level=debug .
   ```

   The output shows the denied image and its input structure:

   ```text
   #1 0.026 checking policy for source docker-image://docker.io/library/alpine:3.19
   #1 0.027 policy input: {
   #1 0.027   "image": {
   #1 0.027     "repo": "alpine",
   #1 0.027     "tag": "3.19",
   #1 0.027     ...
   #1 0.027   }
   #1 0.027 }
   #1 0.028 policy decision for source docker-image://alpine:3.19: DENY
   #1 ERROR: source "docker-image://alpine:3.19" not allowed by policy
   ```

3. Add a rule allowing the alpine image:

   ```rego
   allow if {
       input.image.repo == "alpine"
   }
   ```

4. Build again to verify the policy works:

   ```console
   $ docker buildx build .
   ```

If it fails, see [Debugging](https://docs.docker.com/build/policies/debugging/) for troubleshooting guidance.

## [Using policies with `docker build`](#using-policies-with-docker-build)

Once you've developed and tested your policy, apply it to real builds.

### [Basic usage](#basic-usage)

Create a policy alongside your Dockerfile:

Dockerfile

```dockerfile
FROM alpine:3.19
RUN echo "hello"
```

Dockerfile.rego

```rego
package docker

default allow := false

allow if input.local

allow if {
    input.image.repo == "alpine"
}

decision := {"allow": allow}
```

Build normally:

```console
$ docker buildx build .
```

Buildx loads the policy automatically and validates the `alpine:3.19` image before building.

### [Build with different Dockerfile names](#build-with-different-dockerfile-names)

Specify the Dockerfile with `-f`:

```console
$ docker buildx build -f app.Dockerfile .
```

Buildx looks for `app.Dockerfile.rego` in the same directory.

### [Build with manual policy](#build-with-manual-policy)

Add an extra policy to the automatic one:

```console
$ docker buildx build --policy filename=extra-checks.rego .
```

Both `Dockerfile.rego` (automatic) and `extra-checks.rego` (manual) must pass.

### [Build without automatic policy](#build-without-automatic-policy)

Use only your specified policy:

```console
$ docker buildx build --policy reset=true,filename=strict.rego .
```

## [Using policies with bake](#using-policies-with-bake)

[Bake](/build/bake/) supports automatic policy loading just like `docker buildx build`. Place `Dockerfile.rego` alongside your Dockerfile and run:

```console
$ docker buildx bake
```

### [Manual policy in bake files](#manual-policy-in-bake-files)

Specify additional policies in your `docker-bake.hcl`:

docker-bake.hcl

```hcl
target "default" {
  dockerfile = "Dockerfile"
  policy = ["extra.rego"]
}
```

The `policy` attribute takes a list of policy files. Bake loads these in addition to the automatic `Dockerfile.rego` (if it exists).

### [Multiple policies in bake](#multiple-policies-in-bake)

docker-bake.hcl

```hcl
target "webapp" {
  dockerfile = "Dockerfile"
  policy = [
    "shared/base-policy.rego",
    "security/image-signing.rego"
  ]
}
```

All policies must pass for the target to build successfully.

### [Different policies per target](#different-policies-per-target)

Apply different validation rules to different targets:

docker-bake.hcl

```hcl
target "development" {
  dockerfile = "dev.Dockerfile"
  policy = ["policies/permissive.rego"]
}

target "production" {
  dockerfile = "prod.Dockerfile"
  policy = ["policies/strict.rego", "policies/signing-required.rego"]
}
```

Build with the appropriate target:

```console
$ docker buildx bake development  # Uses permissive policy
$ docker buildx bake production   # Uses strict policies
```

### [Bake with policy options](#bake-with-policy-options)

Currently, bake doesn't support policy options (reset, strict, disabled) in the HCL file. Use command-line flags instead:

```console
$ docker buildx bake --policy disabled=true production
```

## [Testing in CI/CD](#testing-in-cicd)

Validate policies in continuous integration by running builds with the `--policy` flag. For unit testing policies before running builds, see [Test build policies](https://docs.docker.com/build/policies/testing/).

Test policies during CI builds:

.github/workflows/test-policies.yml

```yaml
name: Test Build Policies
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: docker/setup-buildx-action@v4
      - name: Test build with policy
        run: docker buildx build --policy strict=true .
```

This ensures policy changes don't break builds and that new rules work as intended. The `strict=true` flag fails the build if policies aren't loaded (for example, if the BuildKit instance used by the build is too old and doesn't support policies).

## [Advanced: Policy configuration](#advanced-policy-configuration)

This section covers advanced policy loading mechanisms and configuration options.

### [Automatic policy loading](#automatic-policy-loading)

Buildx automatically loads policies that match your Dockerfile name. When you build with `Dockerfile`, Buildx looks for `Dockerfile.rego` in the same directory. For a file named `app.Dockerfile`, it looks for `app.Dockerfile.rego`.

```text
project/
├── Dockerfile
├── Dockerfile.rego          # Loaded automatically for Dockerfile
├── app.Dockerfile
├── app.Dockerfile.rego      # Loaded automatically for app.Dockerfile
└── src/
```

This automatic loading means you don't need command-line flags in most cases. Create the policy file alongside your Dockerfile and build:

```console
$ docker buildx build .
```

Buildx detects `Dockerfile.rego` and evaluates it before running the build.

> Note
>
> Policy files must be in the same directory as the Dockerfile they validate. Buildx doesn't search parent directories or subdirectories.

### [When policies don't load](#when-policies-dont-load)

If buildx can't find a matching `.rego` file, the build proceeds without policy evaluation. To require policies and fail if none are found, use strict mode:

```console
$ docker buildx build --policy strict=true .
```

This fails the build if no policy loads or if the BuildKit daemon doesn't support policies.

### [Manual policy configuration](#manual-policy-configuration)

The `--policy` flag lets you specify additional policies, override automatic loading, or control policy behavior.

Basic syntax:

```console
$ docker buildx build --policy filename=custom.rego .
```

This loads `custom.rego` in addition to the automatic `Dockerfile.rego` (if it exists).

Multiple policies:

```console
$ docker buildx build --policy filename=policy1.rego --policy filename=policy2.rego .
```

All policies must pass for the build to succeed. Use this to enforce layered requirements (base policy + project-specific rules).

Available options:

| Option              | Description                                                                                                           | Example                |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `filename=<path>`   | Load policy from specified file                                                                                       | `filename=custom.rego` |
| `reset=true`        | Ignore automatic policies, use only specified ones                                                                    | `reset=true`           |
| `disabled=true`     | Disable all policy evaluation                                                                                         | `disabled=true`        |
| `strict=true`       | Fail if BuildKit doesn't support policies                                                                             | `strict=true`          |
| `log-level=<level>` | Control policy logging (error, warn, info, debug, none). Use `debug` to see complete input JSON and unresolved fields | `log-level=debug`      |

Combine options with commas:

```console
$ docker buildx build --policy filename=extra.rego,strict=true .
```

### [Exploring sources with policy eval](#exploring-sources-with-policy-eval)

The `docker buildx policy eval` command lets you quickly explore and test sources without running a build.

#### [Inspect input structure with --print](#inspect-input-structure-with---print)

Use `--print` to see the input structure for any source without running policy evaluation:

```console
$ docker buildx policy eval --print https://github.com/moby/buildkit.git
```

```json
{
  "git": {
    "schema": "https",
    "host": "github.com",
    "remote": "https://github.com/moby/buildkit.git"
  }
}
```

Test different source types:

```console
# HTTP downloads
$ docker buildx policy eval --print https://releases.hashicorp.com/terraform/1.5.0/terraform.zip

# Images (requires docker-image:// prefix)
$ docker buildx policy eval --print docker-image://alpine:3.19

# Local context
$ docker buildx policy eval --print .
```

Shows information parsed from the source without fetching. Use `--fields` to fetch specific metadata (see [above](#testing-policies-with-policy-eval)).

#### [Test with specific policy files](#test-with-specific-policy-files)

The `--filename` flag specifies which policy file to load by providing the base Dockerfile name (without the `.rego` extension). This is useful for testing sources against policies associated with different Dockerfiles.

For example, to test a source against the policy for `app.Dockerfile`:

```console
$ docker buildx policy eval --filename app.Dockerfile .
```

This loads `app.Dockerfile.rego` and tests whether it allows the source `.` (the local directory). The flag defaults to `Dockerfile` if not specified.

Test different sources against your policy:

```console
$ docker buildx policy eval --filename app.Dockerfile https://github.com/org/repo.git
$ docker buildx policy eval --filename app.Dockerfile docker-image://alpine:3.19
```

### [Reset automatic loading](#reset-automatic-loading)

To use only your specified policies and ignore automatic `.rego` files:

```console
$ docker buildx build --policy reset=true,filename=custom.rego .
```

This skips `Dockerfile.rego` and loads only `custom.rego`.

### [Disable policies temporarily](#disable-policies-temporarily)

Disable policy evaluation for testing or emergencies:

```console
$ docker buildx build --policy disabled=true .
```

The build proceeds without any policy checks. Use this carefully - you're bypassing security controls.

## [Next steps](#next-steps)

* Write unit tests for your policies: [Test build policies](https://docs.docker.com/build/policies/testing/)
* Debug policy failures: [Debugging](https://docs.docker.com/build/policies/debugging/)
* Browse working examples: [Example policies](https://docs.docker.com/build/policies/examples/)
* Reference all input fields: [Input reference](https://docs.docker.com/build/policies/inputs/)

----
url: https://docs.docker.com/ai/model-runner/api-reference/
----

# DMR REST API

***

Table of contents

***

Once Model Runner is enabled, new API endpoints are available. You can use these endpoints to interact with a model programmatically. Docker Model Runner provides compatibility with OpenAI, Anthropic, and Ollama API formats.

## [Determine the base URL](#determine-the-base-url)

The base URL to interact with the endpoints depends on how you run Docker and which API format you're using.

| Access from          | Base URL                              |
| -------------------- | ------------------------------------- |
| Containers           | `http://model-runner.docker.internal` |
| Host processes (TCP) | `http://localhost:12434`              |

> Note
>
> TCP host access must be enabled. See [Enable Docker Model Runner](https://docs.docker.com/ai/model-runner/get-started/#enable-docker-model-runner-in-docker-desktop).

| Access from    | Base URL                  |
| -------------- | ------------------------- |
| Containers     | `http://172.17.0.1:12434` |
| Host processes | `http://localhost:12434`  |

> Note
>
> The `172.17.0.1` interface may not be available by default to containers within a Compose project. In this case, add an `extra_hosts` directive to your Compose service YAML:
>
> ```yaml
> extra_hosts:
>   - "model-runner.docker.internal:host-gateway"
> ```
>
> Then you can access the Docker Model Runner APIs at `http://model-runner.docker.internal:12434/`

### [Base URLs for third-party tools](#base-urls-for-third-party-tools)

When configuring third-party tools that expect OpenAI-compatible APIs, use these base URLs:

| Tool type                 | Base URL format                     |
| ------------------------- | ----------------------------------- |
| OpenAI SDK / clients      | `http://localhost:12434/engines/v1` |
| Anthropic SDK / clients   | `http://localhost:12434`            |
| Ollama-compatible clients | `http://localhost:12434`            |

See [IDE and tool integrations](https://docs.docker.com/ai/model-runner/ide-integrations/) for specific configuration examples.

## [Supported APIs](#supported-apis)

Docker Model Runner supports multiple API formats:

| API                                                     | Description                                    | Use case                            |
| ------------------------------------------------------- | ---------------------------------------------- | ----------------------------------- |
| [OpenAI API](#openai-compatible-api)                    | OpenAI-compatible chat completions, embeddings | Most AI frameworks and tools        |
| [Anthropic API](#anthropic-compatible-api)              | Anthropic-compatible messages endpoint         | Tools built for Claude              |
| [Ollama API](#ollama-compatible-api)                    | Ollama-compatible endpoints                    | Tools built for Ollama              |
| [Image Generation API](#image-generation-api-diffusers) | Diffusers-based image generation               | Generating images from text prompts |
| [DMR API](#dmr-native-endpoints)                        | Native Docker Model Runner endpoints           | Model management                    |

## [OpenAI-compatible API](#openai-compatible-api)

DMR implements the OpenAI API specification for maximum compatibility with existing tools and frameworks.

### [Endpoints](#endpoints)

| Endpoint                                | Method | Description                                                                            |
| --------------------------------------- | ------ | -------------------------------------------------------------------------------------- |
| `/engines/v1/models`                    | GET    | [List models](https://platform.openai.com/docs/api-reference/models/list)              |
| `/engines/v1/models/{namespace}/{name}` | GET    | [Retrieve model](https://platform.openai.com/docs/api-reference/models/retrieve)       |
| `/engines/v1/chat/completions`          | POST   | [Create chat completion](https://platform.openai.com/docs/api-reference/chat/create)   |
| `/engines/v1/completions`               | POST   | [Create completion](https://platform.openai.com/docs/api-reference/completions/create) |
| `/engines/v1/embeddings`                | POST   | [Create embeddings](https://platform.openai.com/docs/api-reference/embeddings/create)  |

> Note
>
> You can optionally include the engine name in the path: `/engines/llama.cpp/v1/chat/completions`. This is useful when running multiple inference engines.

### [Model name format](#model-name-format)

When specifying a model in API requests, use the full model identifier including the namespace:

```json
{
  "model": "ai/smollm2",
  "messages": [...]
}
```

Common model name formats:

* Docker Hub models: `ai/smollm2`, `ai/llama3.2`, `ai/qwen2.5-coder`
* Tagged versions: `ai/smollm2:360M-Q4_K_M`
* Custom models: `myorg/mymodel`

### [Supported parameters](#supported-parameters)

The following OpenAI API parameters are supported:

| Parameter           | Type         | Description                                              |
| ------------------- | ------------ | -------------------------------------------------------- |
| `model`             | string       | Required. The model identifier.                          |
| `messages`          | array        | Required for chat completions. The conversation history. |
| `prompt`            | string       | Required for completions. The prompt text.               |
| `max_tokens`        | integer      | Maximum tokens to generate.                              |
| `temperature`       | float        | Sampling temperature (0.0-2.0).                          |
| `top_p`             | float        | Nucleus sampling parameter (0.0-1.0).                    |
| `stream`            | Boolean      | Enable streaming responses.                              |
| `stop`              | string/array | Stop sequences.                                          |
| `presence_penalty`  | float        | Presence penalty (-2.0 to 2.0).                          |
| `frequency_penalty` | float        | Frequency penalty (-2.0 to 2.0).                         |

### [Limitations and differences from OpenAI](#limitations-and-differences-from-openai)

Be aware of these differences when using DMR's OpenAI-compatible API:

| Feature          | DMR behavior                                                           |
| ---------------- | ---------------------------------------------------------------------- |
| API key          | Not required. DMR ignores the `Authorization` header.                  |
| Function calling | Supported with llama.cpp for compatible models.                        |
| Vision           | Supported for multi-modal models (e.g., LLaVA).                        |
| JSON mode        | Supported via `response_format: {"type": "json_object"}`.              |
| Logprobs         | Supported.                                                             |
| Token counting   | Uses the model's native token encoder, which may differ from OpenAI's. |

## [Anthropic-compatible API](#anthropic-compatible-api)

DMR provides [Anthropic Messages API](https://platform.claude.com/docs/en/api/messages) compatibility for tools and frameworks built for Claude.

### [Endpoints](#endpoints-1)

| Endpoint                              | Method | Description                                                                 |
| ------------------------------------- | ------ | --------------------------------------------------------------------------- |
| `/anthropic/v1/messages`              | POST   | [Create a message](https://platform.claude.com/docs/en/api/messages/create) |
| `/anthropic/v1/messages/count_tokens` | POST   | [Count tokens](https://docs.anthropic.com/en/api/messages-count-tokens)     |

### [Supported parameters](#supported-parameters-1)

The following Anthropic API parameters are supported:

| Parameter        | Type    | Description                          |
| ---------------- | ------- | ------------------------------------ |
| `model`          | string  | Required. The model identifier.      |
| `messages`       | array   | Required. The conversation messages. |
| `max_tokens`     | integer | Maximum tokens to generate.          |
| `temperature`    | float   | Sampling temperature (0.0-1.0).      |
| `top_p`          | float   | Nucleus sampling parameter.          |
| `top_k`          | integer | Top-k sampling parameter.            |
| `stream`         | Boolean | Enable streaming responses.          |
| `stop_sequences` | array   | Custom stop sequences.               |
| `system`         | string  | System prompt.                       |

### [Example: Chat with Anthropic API](#example-chat-with-anthropic-api)

```bash
curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

### [Example: Streaming response](#example-streaming-response)

```bash
curl http://localhost:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from 1 to 10"}
    ]
  }'
```

## [Ollama-compatible API](#ollama-compatible-api)

DMR also provides Ollama-compatible endpoints for tools and frameworks built for Ollama.

### [Endpoints](#endpoints-2)

| Endpoint          | Method | Description              |
| ----------------- | ------ | ------------------------ |
| `/api/tags`       | GET    | List available models    |
| `/api/show`       | POST   | Show model information   |
| `/api/chat`       | POST   | Generate chat completion |
| `/api/generate`   | POST   | Generate completion      |
| `/api/embeddings` | POST   | Generate embeddings      |

### [Example: Chat with Ollama API](#example-chat-with-ollama-api)

```bash
curl http://localhost:12434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

### [Example: List models](#example-list-models)

```bash
curl http://localhost:12434/api/tags
```

## [Image generation API (Diffusers)](#image-generation-api-diffusers)

DMR supports image generation through the Diffusers backend, enabling you to generate images from text prompts using models like Stable Diffusion.

> Note
>
> The Diffusers backend requires an NVIDIA GPU with CUDA support and is only available on Linux (x86\_64 and ARM64). See [Inference engines](https://docs.docker.com/ai/model-runner/inference-engines/#diffusers) for setup instructions.

### [Endpoint](#endpoint)

| Endpoint                                   | Method | Description                          |
| ------------------------------------------ | ------ | ------------------------------------ |
| `/engines/diffusers/v1/images/generations` | POST   | Generate an image from a text prompt |

### [Supported parameters](#supported-parameters-2)

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `model`   | string | Required. The model identifier (e.g., `stable-diffusion:Q4`). |
| `prompt`  | string | Required. The text description of the image to generate.      |
| `size`    | string | Image dimensions in `WIDTHxHEIGHT` format (e.g., `512x512`).  |

### [Response format](#response-format)

The API returns a JSON response with the generated image encoded in base64:

```json
{
  "data": [
    {
      "b64_json": "<base64-encoded-image-data>"
    }
  ]
}
```

### [Example: Generate an image](#example-generate-an-image)

```bash
curl -s -X POST http://localhost:12434/engines/diffusers/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stable-diffusion:Q4",
    "prompt": "A picture of a nice cat",
    "size": "512x512"
  }' | jq -r '.data[0].b64_json' | base64 -d > image.png
```

This command:

1. Sends a POST request to the Diffusers image generation endpoint
2. Specifies the model, prompt, and output image size
3. Extracts the base64-encoded image from the response using `jq`
4. Decodes the base64 data and saves it as `image.png`

## [DMR native endpoints](#dmr-native-endpoints)

These endpoints are specific to Docker Model Runner for model management:

| Endpoint                     | Method | Description          |
| ---------------------------- | ------ | -------------------- |
| `/models/create`             | POST   | Pull/create a model  |
| `/models`                    | GET    | List local models    |
| `/models/{namespace}/{name}` | GET    | Get model details    |
| `/models/{namespace}/{name}` | DELETE | Delete a local model |

## [REST API examples](#rest-api-examples)

### [Request from within a container](#request-from-within-a-container)

To call the `chat/completions` OpenAI endpoint from within another container using `curl`:

```bash
#!/bin/sh

curl http://model-runner.docker.internal/engines/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "ai/smollm2",
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Please write 500 words about the fall of Rome."
            }
        ]
    }'
```

### [Request from the host using TCP](#request-from-the-host-using-tcp)

To call the `chat/completions` OpenAI endpoint from the host via TCP:

1. Enable the host-side TCP support from the Docker Desktop GUI, or via the [Docker Desktop CLI](https://docs.docker.com/desktop/features/desktop-cli/). For example: `docker desktop enable model-runner --tcp <port>`.

   If you are running on Windows, also enable GPU-backed inference. See [Enable Docker Model Runner](https://docs.docker.com/ai/model-runner/get-started/#enable-docker-model-runner-in-docker-desktop).

2. Interact with it as documented in the previous section using `localhost` and the correct port.

```bash
#!/bin/sh

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
      "model": "ai/smollm2",
      "messages": [
          {
              "role": "system",
              "content": "You are a helpful assistant."
          },
          {
              "role": "user",
              "content": "Please write 500 words about the fall of Rome."
          }
      ]
  }'
```

### [Request from the host using a Unix socket](#request-from-the-host-using-a-unix-socket)

To call the `chat/completions` OpenAI endpoint through the Docker socket from the host using `curl`:

```bash
#!/bin/sh

curl --unix-socket $HOME/.docker/run/docker.sock \
    localhost/exp/vDD4.40/engines/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "ai/smollm2",
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "Please write 500 words about the fall of Rome."
            }
        ]
    }'
```

### [Streaming responses](#streaming-responses)

To receive streaming responses, set `stream: true`:

```bash
curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
      "model": "ai/smollm2",
      "stream": true,
      "messages": [
          {"role": "user", "content": "Count from 1 to 10"}
      ]
  }'
```

## [Using with OpenAI SDKs](#using-with-openai-sdks)

### [Python](#python)

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="not-needed"  # DMR doesn't require an API key
)

response = client.chat.completions.create(
    model="ai/smollm2",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)
```

### [Node.js](#nodejs)

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:12434/engines/v1',
  apiKey: 'not-needed',
});

const response = await client.chat.completions.create({
  model: 'ai/smollm2',
  messages: [{ role: 'user', content: 'Hello!' }],
});

console.log(response.choices[0].message.content);
```

## [What's next](#whats-next)

* [IDE and tool integrations](https://docs.docker.com/ai/model-runner/ide-integrations/) - Configure Cline, Continue, Cursor, and other tools
* [Configuration options](https://docs.docker.com/ai/model-runner/configuration/) - Adjust context size and runtime parameters
* [Inference engines](https://docs.docker.com/ai/model-runner/inference-engines/) - Learn about llama.cpp, vLLM, and Diffusers options

----
url: https://docs.docker.com/guides/deno/containerize/
----

# Containerize a Deno application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Overview](#overview)

For a long time, Node.js has been the go-to runtime for server-side JavaScript applications. However, recent years have introduced new alternative runtimes, including [Deno](https://deno.land/). Like Node.js, Deno is a JavaScript and TypeScript runtime, but it takes a fresh approach with modern security features, a built-in standard library, and native support for TypeScript.

Why develop Deno applications with Docker? Having a choice of runtimes is exciting, but managing multiple runtimes and their dependencies consistently across environments can be tricky. This is where Docker proves invaluable. Using containers to create and destroy environments on demand simplifies runtime management and ensures consistency. Additionally, as Deno continues to grow and evolve, Docker helps establish a reliable and reproducible development environment, minimizing setup challenges and streamlining the workflow.

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/dockersamples/docker-deno.git && cd docker-deno
```

You should now have the following contents in your `deno-docker` directory.

```text
├── deno-docker/
│ ├── compose.yml
│ ├── Dockerfile
│ ├── LICENSE
│ ├── server.ts
│ └── README.md
```

## [Understand the sample application](#understand-the-sample-application)

The sample application is a simple Deno application that uses the Oak framework to create a simple API that returns a JSON response. The application listens on port 8000 and returns a message `{"Status" : "OK"}` when you access the application in a browser.

```typescript
// server.ts
import { Application, Router } from "https://deno.land/x/oak@v12.0.0/mod.ts";

const app = new Application();
const router = new Router();

// Define a route that returns JSON
router.get("/", (context) => {
  context.response.body = { Status: "OK" };
  context.response.type = "application/json";
});

app.use(router.routes());
app.use(router.allowedMethods());

console.log("Server running on http://localhost:8000");
await app.listen({ port: 8000 });
```

## [Create a Dockerfile](#create-a-dockerfile)

Before creating a Dockerfile, you need to choose a base image. You can either use the [Deno Docker Official Image](https://hub.docker.com/r/denoland/deno) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog).

Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/).

Docker Hardened Images (DHIs) are available for Deno in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/deno). You can pull DHIs directly from the `dhi.io` registry.

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Pull the Deno DHI as `dhi.io/deno:2`. The tag (`2`) in this example refers to the version to the latest 2.x version of Deno.

   ```console
   $ docker pull dhi.io/deno:2
   ```

For other available versions, refer to the [catalog](https://hub.docker.com/hardened-images/catalog/dhi/deno).

```dockerfile
# Use the DHI Deno image as the base image
FROM dhi.io/deno:2

# Set the working directory
WORKDIR /app

# Copy server code into the container
COPY server.ts .

# Set permissions (optional but recommended for security)
USER deno

# Expose port 8000
EXPOSE 8000

# Run the Deno server
CMD ["run", "--allow-net", "server.ts"]
```

Using the Docker Official Image is straightforward. In the following Dockerfile, you'll notice that the `FROM` instruction uses `denoland/deno:latest` as the base image.

This is the official image for Deno. This image is [available on the Docker Hub](https://hub.docker.com/r/denoland/deno).

```dockerfile
# Use the official Deno image
FROM denoland/deno:latest

# Set the working directory
WORKDIR /app

# Copy server code into the container
COPY server.ts .

# Set permissions (optional but recommended for security)
USER deno

# Expose port 8000
EXPOSE 8000

# Run the Deno server
CMD ["run", "--allow-net", "server.ts"]
```

In addition to specifying the base image, the Dockerfile also:

* Sets the working directory in the container to `/app`.
* Copies `server.ts` into the container.
* Sets the user to `deno` to run the application as a non-root user.
* Exposes port 8000 to allow traffic to the application.
* Runs the Deno server using the `CMD` instruction.
* Uses the `--allow-net` flag to allow network access to the application. The `server.ts` file uses the Oak framework to create a simple API that listens on port 8000.

## [Run the application](#run-the-application)

Make sure you are in the `deno-docker` directory. Run the following command in a terminal to build and run the application.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:8000>. You will see a message `{"Status" : "OK"}` in the browser.

In the terminal, press `ctrl`+`c` to stop the application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `deno-docker` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:8000>.

In the terminal, run the following command to stop the application.

```console
$ docker compose down
```

## [Summary](#summary)

In this section, you learned how you can containerize and run your Deno application using Docker.

[Use containers for Deno development »](https://docs.docker.com/guides/deno/develop/)

----
url: https://docs.docker.com/ai/sandboxes/customize/build-an-agent/
----

# Build your own agent kit

***

Table of contents

***

Availability: Early Access

> Note
>
> Kits are experimental. The kit file format, CLI commands, and experience for creating, loading, and managing kits are subject to change as the feature evolves. Share feedback and bug reports in the [docker/sbx-releases](https://github.com/docker/sbx-releases) repository.

This tutorial walks through building an agent kit for the [Amp](https://ampcode.com/) coding agent. Each step explains the decision behind a part of the spec, so you can apply the same reasoning to other agents.

For reference on every field, see the [Kits](https://docs.docker.com/ai/sandboxes/customize/kits/) page. This tutorial focuses on the journey.

The finished kit is also published as a runnable sample at [docker/sbx-kits-contrib](https://github.com/docker/sbx-kits-contrib/tree/main/amp) — useful as a reference while you follow along.

## [Choose a base image](#choose-a-base-image)

An agent kit needs a container image that satisfies the [base image requirements](https://docs.docker.com/ai/sandboxes/customize/kits/#base-image-requirements): non-root `agent` user at UID 1000, passwordless sudo, `/home/agent/` home, and HTTP proxy environment variable forwarding.

Rather than build an image from scratch, extend one of the published sandbox templates. Three common starting points:

* `docker/sandbox-templates:shell`. Generic base with no pre-installed agent.
* `docker/sandbox-templates:shell-docker`. Same, with Docker Engine inside the sandbox.
* Agent-specific variants (`claude-code`, `codex`, etc.). Only useful if you're extending that specific agent.

For Amp, pick `shell-docker`:

* Amp isn't pre-installed in any variant, so you need a generic base (`shell`).
* Docker support is handy since coding agents often need to run containers.
* If you don't need Docker inside the sandbox, use the `shell` tag for a lighter, non-privileged environment.

## [Plan authentication](#plan-authentication)

Amp authenticates with an API key in `AMP_API_KEY`. To keep the real key out of the VM, you split the work in two:

* The kit's network section maps the API host to a service identifier and tells the proxy which header to inject.
* You provide your key once on the host, via sbx's secret store. The real value stays on the host; only a placeholder reaches the sandbox.

Inside the sandbox `AMP_API_KEY` is set to that placeholder. The proxy substitutes the real key on outbound requests to the API host, so the secret never enters the sandbox. A later section walks through the specific command for storing the key.

## [Write the agent block](#write-the-agent-block)

The `agent:` block tells the sandbox how to launch Amp when the user attaches.

amp/spec.yaml

```yaml
schemaVersion: "1"
kind: agent
name: amp
displayName: Amp
description: The frontier coding agent.

agent:
  image: "docker/sandbox-templates:shell-docker"
  aiFilename: AGENTS.md
  persistence: persistent
  entrypoint:
    run: [amp, --dangerously-allow-all]
```

* `aiFilename: AGENTS.md` tells the sandbox to create `AGENTS.md` at launch and append the [`memory`](#prime-amp-with-memory) block to it. Amp reads this file for instructions.
* `persistence: persistent` keeps Amp's state (auth tokens, history) in a named volume across sandbox restarts. Without it, you re-authenticate every time.
* `entrypoint.run` runs `amp` in "YOLO-mode" when the sandbox starts. Adjust if you want to pass different args on startup.

## [Install Amp](#install-amp)

Amp installs via a curl-to-bash script:

```yaml
commands:
  install:
    - command: "curl -fsSL https://ampcode.com/install.sh | bash"
      user: "1000"
      description: Install Amp
```

Note `user: "1000"`. That's the agent user. Install commands run as root (UID 0) by default, and Amp's installer puts the binary in the user's home directory. Running as root would land the binary in `/root/` where the agent can't reach it.

## [Allow network access](#allow-network-access)

The network block does two things: it lists the hosts the sandbox can reach (`allowedDomains`), and it wires the kit-side half of the auth flow from [Plan authentication](#plan-authentication) with `serviceDomains` and `serviceAuth`.

```yaml
network:
  serviceDomains:
    ampcode.com: amp
  serviceAuth:
    amp:
      headerName: Authorization
      valueFormat: "Bearer %s"
  allowedDomains:
    - "ampcode.com:443"
    - "*.ampcode.com:443"
```

`allowedDomains` here covers the apex (`ampcode.com`) and the install/CDN subdomains (`*.ampcode.com`). Treat it as a starting point; Amp may reach other domains (model providers, analytics, updates) that you'll discover by watching `sbx policy log` while testing.

Kits can also declare `deniedDomains` for hosts the sandbox should not reach, such as telemetry endpoints. Deny rules take precedence over allow rules and apply only to sandboxes that use the kit.

For the auth wiring, when the agent makes an outbound request to `ampcode.com`, the proxy looks up the host in `serviceDomains` to find the service id `amp`, then uses `serviceAuth.amp` to inject an `Authorization: Bearer <key>` header. The `<key>` value comes from the secret you'll register in [Register your API key](#register-your-api-key), matched by host. The service id (`amp`) is just a label that ties the two blocks together — pick any name.

> Important
>
> Keep `serviceDomains` narrow. Mapping `*.ampcode.com` would push the proxy into TLS-intercepting mode for every subdomain — including the binary CDN the install script downloads from — which corrupts those downloads. List only the host that actually needs auth.

## [Prime Amp with memory](#prime-amp-with-memory)

The `memory` field appends markdown to `AGENTS.md` at sandbox creation. Use it to tell Amp about the sandbox environment so it knows the conventions when it starts.

```yaml
memory: |
  ## Sandbox environment

  You are running inside a Docker sandbox. The workspace is mounted at
  its absolute host path. `sudo` is passwordless; use it for package
  installs. Docker is available inside the sandbox; containers you start
  are isolated in the microVM.
```

Keep this short and sandbox-specific. For project instructions, put a regular `AGENTS.md` in the workspace.

## [The full spec](#the-full-spec)

Putting it all together:

amp/spec.yaml

```yaml
schemaVersion: "1"
kind: agent
name: amp
displayName: Amp
description: The frontier coding agent.

agent:
  image: "docker/sandbox-templates:shell-docker"
  aiFilename: AGENTS.md
  persistence: persistent
  entrypoint:
    run: [amp, --dangerously-allow-all]

network:
  serviceDomains:
    ampcode.com: amp
  serviceAuth:
    amp:
      headerName: Authorization
      valueFormat: "Bearer %s"
  allowedDomains:
    - "ampcode.com:443"
    - "*.ampcode.com:443"

commands:
  install:
    - command: "curl -fsSL https://ampcode.com/install.sh | bash"
      user: "1000"
      description: Install Amp

memory: |
  ## Sandbox environment

  You are running inside a Docker sandbox. The workspace is mounted at
  its absolute host path. `sudo` is passwordless; use it for package
  installs.
```

## [Register your API key](#register-your-api-key)

Register your Amp API key on the host with `sbx secret set-custom`. The value goes into the host secret store, and a placeholder is exposed inside every sandbox you launch from this kit.

Amp validates `AMP_API_KEY`'s format at startup, so the placeholder needs to look like a real Amp key. Pick a placeholder shape that matches Amp's expected format:

```console
$ sbx secret set-custom -g \
    --host ampcode.com \
    --env AMP_API_KEY \
    --placeholder "sgamp-{rand}" \
    --value "$AMP_API_KEY"
```

`{rand}` expands to a random suffix at registration time. Inside the sandbox `AMP_API_KEY` is set to that placeholder; Amp accepts it as a syntactically valid key, and the proxy substitutes the real secret on outbound requests to `ampcode.com`.

> Tip
>
> `sbx secret set-custom` is only required because Amp validates the key's format. If your agent reads the env var without a local format check, you can declare `environment.proxyManaged: [AMP_API_KEY]` in the kit instead and skip this user-side step — the proxy uses a default sentinel value (`proxy-managed`) that the agent never sees rejected.

> Note
>
> `sbx secret set-custom` is an experimental command and isn't listed in `sbx secret --help`. It works today but may change in future releases. This tutorial surfaces it because there's no other path to register a custom-format placeholder.

## [Run it](#run-it)

Validate the spec:

```console
$ sbx kit validate ./amp/
```

Launch a sandbox with the kit, passing the kit's `name:` (`amp`) as the agent argument:

```console
$ sbx run --kit ./amp/ amp
```

The published copy of this kit also runs directly from the contrib repository:

```console
$ sbx run --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=amp" amp
```

## [Iterate](#iterate)

As you use the kit, you'll likely hit missing domains or install quirks. Two loops help:

* Watch the network policy log (`sbx policy log`) to catch blocked requests, then add their domains to `allowedDomains`.
* Add domains to `deniedDomains` when the agent should stay blocked from a host even if another policy permits it.
* Edit the spec and re-run `sbx run --kit ./amp/ amp` to pick up changes. Remove the sandbox first (`sbx rm <name>`) for a clean start.

Flesh out the `memory` block as you refine how Amp should behave in the sandbox.

## [Publish](#publish)

Once the kit works, share it by packaging as a ZIP, pushing to an OCI registry, or committing to a Git repository. See [Packaging and distribution](https://docs.docker.com/ai/sandboxes/customize/kits/#packaging-and-distribution) for the `sbx kit` subcommands.

## [Adapt this to another agent](#adapt-this-to-another-agent)

Most of the specifics here are Amp's. To port the pattern, work through the same decisions for your agent:

* **Base image**: `shell-docker` if you need Docker inside the sandbox, `shell` otherwise. Or extend either with your own image if the install is heavy.
* **Install**: a `commands.install` block at runtime, or bake the agent into a custom image. Pick install if it's a one-line script; bake if the install is slow or you need a pinned version.
* **Network mapping**: list only the API host in `serviceDomains`, not a wildcard. Keep install/CDN paths out of TLS-intercepting mode. Use `deniedDomains` for hosts the agent should not reach.
* **Credential injection**: if the agent validates the API key's format locally, register with `sbx secret set-custom` and pick a matching placeholder. If it accepts the env var as-is, declare `environment.proxyManaged` in the kit and skip the user-side step.

The rest — memory block, network-policy iteration, packaging — is the same regardless of agent.

## [Remove the stored secret](#remove-the-stored-secret)

To remove the entry created earlier with `sbx secret set-custom`, pass the host to `sbx secret rm`:

```console
$ sbx secret rm -g --host ampcode.com
```

The `--host` flag on `sbx secret rm` isn't listed in `sbx secret rm --help`, but it's the only way to remove entries created with `set-custom`. Like `set-custom` itself, it's experimental and may change.

----
url: https://docs.docker.com/engine/release-notes/prior-releases/
----

# Docker Engine prior releases

***

Table of contents

***

## [1.13.1 (2017-02-08)](#1131-2017-02-08)

> Important
>
> On Linux distributions where `devicemapper` was the default storage driver, the `overlay2`, or `overlay` is now used by default (if the kernel supports it). To use devicemapper, you can manually configure the storage driver to use through the `--storage-driver` daemon option, or by setting "storage-driver" in the `daemon.json` configuration file.

> Important
>
> In Docker 1.13, the managed plugin api changed, as compared to the experimental version introduced in Docker 1.12. You must **uninstall** plugins which you installed with Docker 1.12 *before* upgrading to Docker 1.13. You can uninstall plugins using the `docker plugin rm` command.

If you have already upgraded to Docker 1.13 without uninstalling previously-installed plugins, you may see this message when the Docker daemon starts:

```
Error starting daemon: json: cannot unmarshal string into Go value of type types.PluginEnv
```

To manually remove all plugins and resolve this problem, take the following steps:

1. Remove plugins.json from: `/var/lib/docker/plugins/`.
2. Restart Docker. Verify that the Docker daemon starts with no errors.
3. Reinstall your plugins.

### [Contrib](#contrib)

* Do not require a custom build of tini [#28454](https://github.com/docker/docker/pull/28454)
* Upgrade to Go 1.7.5 [#30489](https://github.com/docker/docker/pull/30489)

### [Remote API (v1.26) & Client](#remote-api-v126--client)

* Support secrets in docker stack deploy with compose file [#30144](https://github.com/docker/docker/pull/30144)

### [Runtime](#runtime)

* Fix size issue in `docker system df` [#30378](https://github.com/docker/docker/pull/30378)
* Fix error on `docker inspect` when Swarm certificates were expired. [#29246](https://github.com/docker/docker/pull/29246)
* Fix deadlock on v1 plugin with activate error [#30408](https://github.com/docker/docker/pull/30408)
* Fix SELinux regression [#30649](https://github.com/docker/docker/pull/30649)

### [Plugins](#plugins)

* Support global scoped network plugins (v2) in swarm mode [#30332](https://github.com/docker/docker/pull/30332)

- Add `docker plugin upgrade` [#29414](https://github.com/docker/docker/pull/29414)

### [Windows](#windows)

* Fix small regression with old plugins in Windows [#30150](https://github.com/docker/docker/pull/30150)
* Fix warning on Windows [#30730](https://github.com/docker/docker/pull/30730)

## [1.13.0 (2017-01-18)](#1130-2017-01-18)

> Important
>
> On Linux distributions where `devicemapper` was the default storage driver, the `overlay2`, or `overlay` is now used by default (if the kernel supports it). To use devicemapper, you can manually configure the storage driver to use through the `--storage-driver` daemon option, or by setting "storage-driver" in the `daemon.json` configuration file.

> Important
>
> In Docker 1.13, the managed plugin api changed, as compared to the experimental version introduced in Docker 1.12. You must **uninstall** plugins which you installed with Docker 1.12 *before* upgrading to Docker 1.13. You can uninstall plugins using the `docker plugin rm` command.

If you have already upgraded to Docker 1.13 without uninstalling previously-installed plugins, you may see this message when the Docker daemon starts:

```
Error starting daemon: json: cannot unmarshal string into Go value of type types.PluginEnv
```

To manually remove all plugins and resolve this problem, take the following steps:

1. Remove plugins.json from: `/var/lib/docker/plugins/`.
2. Restart Docker. Verify that the Docker daemon starts with no errors.
3. Reinstall your plugins.

### [Builder](#builder)

* Add capability to specify images used as a cache source on build. These images do not need to have local parent chain and can be pulled from other registries [#26839](https://github.com/docker/docker/pull/26839)
* (experimental) Add option to squash image layers to the FROM image after successful builds [#22641](https://github.com/docker/docker/pull/22641)

- Fix dockerfile parser with empty line after escape [#24725](https://github.com/docker/docker/pull/24725)

* Add step number on `docker build` [#24978](https://github.com/docker/docker/pull/24978)

- Add support for compressing build context during image build [#25837](https://github.com/docker/docker/pull/25837)
- add `--network` to `docker build` [#27702](https://github.com/docker/docker/pull/27702)

* Fix inconsistent behavior between `--label` flag on `docker build` and `docker run` [#26027](https://github.com/docker/docker/issues/26027)
* Fix image layer inconsistencies when using the overlay storage driver [#27209](https://github.com/docker/docker/pull/27209)

- Unused build-args are now allowed. A warning is presented instead of an error and failed build [#27412](https://github.com/docker/docker/pull/27412)

* Fix builder cache issue on Windows [#27805](https://github.com/docker/docker/pull/27805)

- Allow `USER` in builder on Windows [#28415](https://github.com/docker/docker/pull/28415)
- Handle env case-insensitive on Windows [#28725](https://github.com/docker/docker/pull/28725)

### [Contrib](#contrib-1)

* Add support for building docker debs for Ubuntu 16.04 Xenial on PPC64LE [#23438](https://github.com/docker/docker/pull/23438)
* Add support for building docker debs for Ubuntu 16.04 Xenial on s390x [#26104](https://github.com/docker/docker/pull/26104)
* Add support for building docker debs for Ubuntu 16.10 Yakkety Yak on PPC64LE [#28046](https://github.com/docker/docker/pull/28046)

- Add RPM builder for VMWare Photon OS [#24116](https://github.com/docker/docker/pull/24116)

* Add shell completions to tgz [#27735](https://github.com/docker/docker/pull/27735)

- Update the install script to allow using the mirror in China [#27005](https://github.com/docker/docker/pull/27005)

* Add DEB builder for Ubuntu 16.10 Yakkety Yak [#27993](https://github.com/docker/docker/pull/27993)
* Add RPM builder for Fedora 25 [#28222](https://github.com/docker/docker/pull/28222)
* Add `make deb` support for aarch64 [#27625](https://github.com/docker/docker/pull/27625)

### [Distribution](#distribution)

* Update notary dependency to 0.4.2 (full changelogs [here](https://github.com/docker/notary/releases/tag/v0.4.2)) [#27074](https://github.com/docker/docker/pull/27074)

  * Support for compilation on windows [docker/notary#970](https://github.com/docker/notary/pull/970)
  * Improved error messages for client authentication errors [docker/notary#972](https://github.com/docker/notary/pull/972)
  * Support for finding keys that are anywhere in the `~/.docker/trust/private` directory, not just under `~/.docker/trust/private/root_keys` or `~/.docker/trust/private/tuf_keys` [docker/notary#981](https://github.com/docker/notary/pull/981)
  * Previously, on any error updating, the client would fall back on the cache. Now we only do so if there is a network error or if the server is unavailable or missing the TUF data. Invalid TUF data will cause the update to fail - for example if there was an invalid root rotation. [docker/notary#982](https://github.com/docker/notary/pull/982)
  * Improve root validation and yubikey debug logging [docker/notary#858](https://github.com/docker/notary/pull/858) [docker/notary#891](https://github.com/docker/notary/pull/891)
  * Warn if certificates for root or delegations are near expiry [docker/notary#802](https://github.com/docker/notary/pull/802)
  * Warn if role metadata is near expiry [docker/notary#786](https://github.com/docker/notary/pull/786)
  * Fix passphrase retrieval attempt counting and terminal detection [docker/notary#906](https://github.com/docker/notary/pull/906)

- Avoid unnecessary blob uploads when different users push same layers to authenticated registry [#26564](https://github.com/docker/docker/pull/26564)

* Allow external storage for registry credentials [#26354](https://github.com/docker/docker/pull/26354)

### [Logging](#logging)

* Standardize the default logging tag value in all logging drivers [#22911](https://github.com/docker/docker/pull/22911)

- Improve performance and memory use when logging of long log lines [#22982](https://github.com/docker/docker/pull/22982)

* Enable syslog driver for windows [#25736](https://github.com/docker/docker/pull/25736)
* Add Logentries Driver [#27471](https://github.com/docker/docker/pull/27471)
* Update of AWS log driver to support tags [#27707](https://github.com/docker/docker/pull/27707)
* Unix socket support for fluentd [#26088](https://github.com/docker/docker/pull/26088)

- Enable fluentd logging driver on Windows [#28189](https://github.com/docker/docker/pull/28189)

* Sanitize docker labels when used as journald field names [#23725](https://github.com/docker/docker/pull/23725)
* Fix an issue where `docker logs --tail` returned less lines than expected [#28203](https://github.com/docker/docker/pull/28203)
* Splunk Logging Driver: performance and reliability improvements [#26207](https://github.com/docker/docker/pull/26207)
* Splunk Logging Driver: configurable formats and skip for verifying connection [#25786](https://github.com/docker/docker/pull/25786)

### [Networking](#networking)

* Add `--attachable` network support to enable `docker run` to work in swarm-mode overlay network [#25962](https://github.com/docker/docker/pull/25962)
* Add support for host port PublishMode in services using the `--publish` option in `docker service create` [#27917](https://github.com/docker/docker/pull/27917) and [#28943](https://github.com/docker/docker/pull/28943)
* Add support for Windows server 2016 overlay network driver (requires upcoming ws2016 update) [#28182](https://github.com/docker/docker/pull/28182)

- Change the default `FORWARD` policy to `DROP` [#28257](https://github.com/docker/docker/pull/28257)

* Add support for specifying static IP addresses for predefined network on windows [#22208](https://github.com/docker/docker/pull/22208)

- Fix `--publish` flag on `docker run` not working with IPv6 addresses [#27860](https://github.com/docker/docker/pull/27860)
- Fix inspect network show gateway with mask [#25564](https://github.com/docker/docker/pull/25564)
- Fix an issue where multiple addresses in a bridge may cause `--fixed-cidr` to not have the correct addresses [#26659](https://github.com/docker/docker/pull/26659)

* Add creation timestamp to `docker network inspect` [#26130](https://github.com/docker/docker/pull/26130)

- Show peer nodes in `docker network inspect` for swarm overlay networks [#28078](https://github.com/docker/docker/pull/28078)
- Enable ping for service VIP address [#28019](https://github.com/docker/docker/pull/28019)

### [Plugins](#plugins-1)

* Move plugins out of experimental [#28226](https://github.com/docker/docker/pull/28226)
* Add `--force` on `docker plugin remove` [#25096](https://github.com/docker/docker/pull/25096)

- Add support for dynamically reloading authorization plugins [#22770](https://github.com/docker/docker/pull/22770)

* Add description in `docker plugin ls` [#25556](https://github.com/docker/docker/pull/25556)
* Add `-f`/`--format` to `docker plugin inspect` [#25990](https://github.com/docker/docker/pull/25990)
* Add `docker plugin create` command [#28164](https://github.com/docker/docker/pull/28164)

- Send request's TLS peer certificates to authorization plugins [#27383](https://github.com/docker/docker/pull/27383)
- Support for global-scoped network and ipam plugins in swarm-mode [#27287](https://github.com/docker/docker/pull/27287)
- Split `docker plugin install` into two API call `/privileges` and `/pull` [#28963](https://github.com/docker/docker/pull/28963)

### [Remote API (v1.25) & Client](#remote-api-v125--client)

* Support `docker stack deploy` from a Compose file [#27998](https://github.com/docker/docker/pull/27998)
* (experimental) Implement checkpoint and restore [#22049](https://github.com/docker/docker/pull/22049)
* Add `--format` flag to `docker info` [#23808](https://github.com/docker/docker/pull/23808)

- Remove `--name` from `docker volume create` [#23830](https://github.com/docker/docker/pull/23830)

* Add `docker stack ls` [#23886](https://github.com/docker/docker/pull/23886)
* Add a new `is-task` ps filter [#24411](https://github.com/docker/docker/pull/24411)
* Add `--env-file` flag to `docker service create` [#24844](https://github.com/docker/docker/pull/24844)
* Add `--format` on `docker stats` [#24987](https://github.com/docker/docker/pull/24987)
* Make `docker node ps` default to `self` in swarm node [#25214](https://github.com/docker/docker/pull/25214)
* Add `--group` in `docker service create` [#25317](https://github.com/docker/docker/pull/25317)
* Add `--no-trunc` to service/node/stack ps output [#25337](https://github.com/docker/docker/pull/25337)
* Add Logs to `ContainerAttachOptions` so go clients can request to retrieve container logs as part of the attach process [#26718](https://github.com/docker/docker/pull/26718)
* Allow client to talk to an older server [#27745](https://github.com/docker/docker/pull/27745)

- Inform user client-side that a container removal is in progress [#26074](https://github.com/docker/docker/pull/26074)

* Add `Isolation` to the /info endpoint [#26255](https://github.com/docker/docker/pull/26255)
* Add `userns` to the /info endpoint [#27840](https://github.com/docker/docker/pull/27840)

- Do not allow more than one mode be requested at once in the services endpoint [#26643](https://github.com/docker/docker/pull/26643)

* Add capability to /containers/create API to specify mounts in a more granular and safer way [#22373](https://github.com/docker/docker/pull/22373)
* Add `--format` flag to `network ls` and `volume ls` [#23475](https://github.com/docker/docker/pull/23475)

- Allow the top-level `docker inspect` command to inspect any kind of resource [#23614](https://github.com/docker/docker/pull/23614)

* Add --cpus flag to control cpu resources for `docker run` and `docker create`, and add `NanoCPUs` to `HostConfig` [#27958](https://github.com/docker/docker/pull/27958)

- Allow unsetting the `--entrypoint` in `docker run` or `docker create` [#23718](https://github.com/docker/docker/pull/23718)

* Restructure CLI commands by adding `docker image` and `docker container` commands for more consistency [#26025](https://github.com/docker/docker/pull/26025)

- Remove `COMMAND` column from `service ls` output [#28029](https://github.com/docker/docker/pull/28029)

* Add `--format` to `docker events` [#26268](https://github.com/docker/docker/pull/26268)

- Allow specifying multiple nodes on `docker node ps` [#26299](https://github.com/docker/docker/pull/26299)
- Restrict fractional digits to 2 decimals in `docker images` output [#26303](https://github.com/docker/docker/pull/26303)

* Add `--dns-option` to `docker run` [#28186](https://github.com/docker/docker/pull/28186)
* Add Image ID to container commit event [#28128](https://github.com/docker/docker/pull/28128)
* Add external binaries version to docker info [#27955](https://github.com/docker/docker/pull/27955)
* Add information for `Manager Addresses` in the output of `docker info` [#28042](https://github.com/docker/docker/pull/28042)
* Add a new reference filter for `docker images` [#27872](https://github.com/docker/docker/pull/27872)

### [Runtime](#runtime-1)

* Add `--experimental` daemon flag to enable experimental features, instead of shipping them in a separate build [#27223](https://github.com/docker/docker/pull/27223)
* Add a `--shutdown-timeout` daemon flag to specify the default timeout (in seconds) to stop containers gracefully before daemon exit [#23036](https://github.com/docker/docker/pull/23036)
* Add `--stop-timeout` to specify the timeout value (in seconds) for individual containers to stop [#22566](https://github.com/docker/docker/pull/22566)
* Add a new daemon flag `--userland-proxy-path` to allow configuring the userland proxy instead of using the hardcoded `docker-proxy` from `$PATH` [#26882](https://github.com/docker/docker/pull/26882)
* Add boolean flag `--init` on `dockerd` and on `docker run` to use [tini](https://github.com/krallin/tini) a zombie-reaping init process as PID 1 [#26061](https://github.com/docker/docker/pull/26061) [#28037](https://github.com/docker/docker/pull/28037)
* Add a new daemon flag `--init-path` to allow configuring the path to the `docker-init` binary [#26941](https://github.com/docker/docker/pull/26941)
* Add support for live reloading insecure registry in configuration [#22337](https://github.com/docker/docker/pull/22337)
* Add support for storage-opt size on Windows daemons [#23391](https://github.com/docker/docker/pull/23391)

- Improve reliability of `docker run --rm` by moving it from the client to the daemon [#20848](https://github.com/docker/docker/pull/20848)

* Add support for `--cpu-rt-period` and `--cpu-rt-runtime` flags, allowing containers to run real-time threads when `CONFIG_RT_GROUP_SCHED` is enabled in the kernel [#23430](https://github.com/docker/docker/pull/23430)

- Allow parallel stop, pause, unpause [#24761](https://github.com/docker/docker/pull/24761) / [#26778](https://github.com/docker/docker/pull/26778)
- Implement XFS quota for overlay2 [#24771](https://github.com/docker/docker/pull/24771)

* Fix partial/full filter issue in `service tasks --filter` [#24850](https://github.com/docker/docker/pull/24850)
* Allow engine to run inside a user namespace [#25672](https://github.com/docker/docker/pull/25672)
* Fix a race condition between device deferred removal and resume device, when using the devicemapper graphdriver [#23497](https://github.com/docker/docker/pull/23497)
* Add `docker stats` support in Windows [#25737](https://github.com/docker/docker/pull/25737)
* Allow using `--pid=host` and `--net=host` when `--userns=host` [#25771](https://github.com/docker/docker/pull/25771)

- (experimental) Add metrics (Prometheus) output for basic `container`, `image`, and `daemon` operations [#25820](https://github.com/docker/docker/pull/25820)

* Fix issue in `docker stats` with `NetworkDisabled=true` [#25905](https://github.com/docker/docker/pull/25905)

- Add `docker top` support in Windows [#25891](https://github.com/docker/docker/pull/25891)
- Record pid of exec'd process [#27470](https://github.com/docker/docker/pull/27470)
- Add support for looking up user/groups via `getent` [#27599](https://github.com/docker/docker/pull/27599)
- Add new `docker system` command with `df` and `prune` subcommands for system resource management, as well as `docker {container,image,volume,network} prune` subcommands [#26108](https://github.com/docker/docker/pull/26108) [#27525](https://github.com/docker/docker/pull/27525) / [#27525](https://github.com/docker/docker/pull/27525)

* Fix an issue where containers could not be stopped or killed by setting xfs max\_retries to 0 upon ENOSPC with devicemapper [#26212](https://github.com/docker/docker/pull/26212)
* Fix `docker cp` failing to copy to a container's volume dir on CentOS with devicemapper [#28047](https://github.com/docker/docker/pull/28047)

- Promote overlay(2) graphdriver [#27932](https://github.com/docker/docker/pull/27932)

* Add `--seccomp-profile` daemon flag to specify a path to a seccomp profile that overrides the default [#26276](https://github.com/docker/docker/pull/26276)

- Fix ulimits in `docker inspect` when `--default-ulimit` is set on daemon [#26405](https://github.com/docker/docker/pull/26405)
- Add workaround for overlay issues during build in older kernels [#28138](https://github.com/docker/docker/pull/28138)

* Add `TERM` environment variable on `docker exec -t` [#26461](https://github.com/docker/docker/pull/26461)

- Honor a container’s `--stop-signal` setting upon `docker kill` [#26464](https://github.com/docker/docker/pull/26464)

### [Swarm Mode](#swarm-mode)

* Add secret management [#27794](https://github.com/docker/docker/pull/27794)
* Add support for templating service options (hostname, mounts, and environment variables) [#28025](https://github.com/docker/docker/pull/28025)

- Display the endpoint mode in the output of `docker service inspect --pretty` [#26906](https://github.com/docker/docker/pull/26906)
- Make `docker service ps` output more bearable by shortening service IDs in task names [#28088](https://github.com/docker/docker/pull/28088)
- Make `docker node ps` default to the current node [#25214](https://github.com/docker/docker/pull/25214)

* Add `--dns`, -`-dns-opt`, and `--dns-search` to service create. [#27567](https://github.com/docker/docker/pull/27567)
* Add `--force` to `docker service update` [#27596](https://github.com/docker/docker/pull/27596)
* Add `--health-*` and `--no-healthcheck` flags to `docker service create` and `docker service update` [#27369](https://github.com/docker/docker/pull/27369)
* Add `-q` to `docker service ps` [#27654](https://github.com/docker/docker/pull/27654)

- Display number of global services in `docker service ls` [#27710](https://github.com/docker/docker/pull/27710)

* Remove `--name` flag from `docker service update`. This flag is only functional on `docker service create`, so was removed from the `update` command [#26988](https://github.com/docker/docker/pull/26988)
* Fix worker nodes failing to recover because of transient networking issues [#26646](https://github.com/docker/docker/issues/26646)

- Add support for health aware load balancing and DNS records [#27279](https://github.com/docker/docker/pull/27279)

* Add `--hostname` to `docker service create` [#27857](https://github.com/docker/docker/pull/27857)
* Add `--host` to `docker service create`, and `--host-add`, `--host-rm` to `docker service update` [#28031](https://github.com/docker/docker/pull/28031)
* Add `--tty` flag to `docker service create`/`update` [#28076](https://github.com/docker/docker/pull/28076)

- Autodetect, store, and expose node IP address as seen by the manager [#27910](https://github.com/docker/docker/pull/27910)
- Encryption at rest of manager keys and raft data [#27967](https://github.com/docker/docker/pull/27967)

* Add `--update-max-failure-ratio`, `--update-monitor` and `--rollback` flags to `docker service update` [#26421](https://github.com/docker/docker/pull/26421)

- Fix an issue with address autodiscovery on `docker swarm init` running inside a container [#26457](https://github.com/docker/docker/pull/26457)

* (experimental) Add `docker service logs` command to view logs for a service [#28089](https://github.com/docker/docker/pull/28089)
* Pin images by digest for `docker service create` and `update` [#28173](https://github.com/docker/docker/pull/28173)

- Add short (`-f`) flag for `docker node rm --force` and `docker swarm leave --force` [#28196](https://github.com/docker/docker/pull/28196)

* Add options to customize Raft snapshots (`--max-snapshots`, `--snapshot-interval`) [#27997](https://github.com/docker/docker/pull/27997)

- Don't repull image if pinned by digest [#28265](https://github.com/docker/docker/pull/28265)

* Swarm-mode support for Windows [#27838](https://github.com/docker/docker/pull/27838)
* Allow hostname to be updated on service [#28771](https://github.com/docker/docker/pull/28771)
* Support v2 plugins [#29433](https://github.com/docker/docker/pull/29433)
* Add content trust for services [#29469](https://github.com/docker/docker/pull/29469)

### [Volume](#volume)

* Add support for labels on volumes [#21270](https://github.com/docker/docker/pull/21270)
* Add support for filtering volumes by label [#25628](https://github.com/docker/docker/pull/25628)

- Add a `--force` flag in `docker volume rm` to forcefully purge the data of the volume that has already been deleted [#23436](https://github.com/docker/docker/pull/23436)
- Enhance `docker volume inspect` to show all options used when creating the volume [#26671](https://github.com/docker/docker/pull/26671)
- Add support for local NFS volumes to resolve hostnames [#27329](https://github.com/docker/docker/pull/27329)

### [Security](#security)

* Fix selinux labeling of volumes shared in a container [#23024](https://github.com/docker/docker/pull/23024)
* Prohibit `/sys/firmware/**` from being accessed with apparmor [#26618](https://github.com/docker/docker/pull/26618)

### [Deprecation](#deprecation)

* Marked the `docker daemon` command as deprecated. The daemon is moved to a separate binary (`dockerd`), and should be used instead [#26834](https://github.com/docker/docker/pull/26834)
* Deprecate unversioned API endpoints [#28208](https://github.com/docker/docker/pull/28208)
* Remove Ubuntu 15.10 (Wily Werewolf) as supported platform. Ubuntu 15.10 is EOL, and no longer receives updates [#27042](https://github.com/docker/docker/pull/27042)
* Remove Fedora 22 as supported platform. Fedora 22 is EOL, and no longer receives updates [#27432](https://github.com/docker/docker/pull/27432)
* Remove Fedora 23 as supported platform. Fedora 23 is EOL, and no longer receives updates [#29455](https://github.com/docker/docker/pull/29455)
* Deprecate the `repo:shortid` syntax on `docker pull` [#27207](https://github.com/docker/docker/pull/27207)
* Deprecate backing filesystem without `d_type` for overlay and overlay2 storage drivers [#27433](https://github.com/docker/docker/pull/27433)
* Deprecate `MAINTAINER` in Dockerfile [#25466](https://github.com/docker/docker/pull/25466)
* Deprecate `filter` param for endpoint `/images/json` [#27872](https://github.com/docker/docker/pull/27872)
* Deprecate setting duplicate engine labels [#24533](https://github.com/docker/docker/pull/24533)
* Deprecate "top-level" network information in `NetworkSettings` [#28437](https://github.com/docker/docker/pull/28437)

## [1.12.6 (2017-01-10)](#1126-2017-01-10)

> Important
>
> Docker 1.12 ships with an updated systemd unit file for rpm based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if;
>
> * the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or
> * a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive

Starting the `docker service` will produce an error:

```
Failed to start docker.service: Unit docker.socket failed to load: No such file or directory.
```

or

```
no sockets found via socket activation: make sure the service was started by systemd.
```

To resolve this:

* Backup the current version of the unit file, and replace the file with the [version that ships with docker 1.12](https://raw.githubusercontent.com/docker/docker/v1.12.0/contrib/init/systemd/docker.service.rpm)
* Remove the `Requires=docker.socket` directive from the `/usr/lib/systemd/system/docker.service` file if present
* Remove `-H fd://` from the `ExecStart` directive (both in the main unit file, and in any drop-in files present).

After making those changes, run `sudo systemctl daemon-reload`, and `sudo systemctl restart docker` to reload changes and (re)start the docker daemon.

> Note
>
> Docker 1.12.5 will correctly validate that either an IPv6 subnet is provided or that the IPAM driver can provide one when you specify the `--ipv6` option.

If you are currently using the `--ipv6` option *without* specifying the `--fixed-cidr-v6` option, the Docker daemon will refuse to start with the following message:

```text
Error starting daemon: Error initializing network controller: Error creating
                       default "bridge" network: failed to parse pool request
                       for address space "LocalDefault" pool " subpool ":
                       could not find an available, non-overlapping IPv6 address
                       pool among the defaults to assign to the network
```

To resolve this error, either remove the `--ipv6` flag (to preserve the same behavior as in Docker 1.12.3 and earlier), or provide an IPv6 subnet as the value of the `--fixed-cidr-v6` flag.

In a similar way, if you specify the `--ipv6` flag when creating a network with the default IPAM driver, without providing an IPv6 `--subnet`, network creation will fail with the following message:

```text
Error response from daemon: failed to parse pool request for address space
                            "LocalDefault" pool "" subpool "": could not find an
                            available, non-overlapping IPv6 address pool among
                            the defaults to assign to the network
```

To resolve this, either remove the `--ipv6` flag (to preserve the same behavior as in Docker 1.12.3 and earlier), or provide an IPv6 subnet as the value of the `--subnet` flag.

The network creation will instead succeed if you use an external IPAM driver which supports automatic allocation of IPv6 subnets.

### [Runtime](#runtime-2)

* Fix runC privilege escalation (CVE-2016-9962)

## [1.12.5 (2016-12-15)](#1125-2016-12-15)

> Important
>
> Docker 1.12 ships with an updated systemd unit file for rpm based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if;
>
> * the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or
> * a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive

Starting the `docker service` will produce an error:

```
Failed to start docker.service: Unit docker.socket failed to load: No such file or directory.
```

or

```
no sockets found via socket activation: make sure the service was started by systemd.
```

To resolve this:

* Backup the current version of the unit file, and replace the file with the [version that ships with docker 1.12](https://raw.githubusercontent.com/docker/docker/v1.12.0/contrib/init/systemd/docker.service.rpm)
* Remove the `Requires=docker.socket` directive from the `/usr/lib/systemd/system/docker.service` file if present
* Remove `-H fd://` from the `ExecStart` directive (both in the main unit file, and in any drop-in files present).

After making those changes, run `sudo systemctl daemon-reload`, and `sudo systemctl restart docker` to reload changes and (re)start the docker daemon.

> Note
>
> Docker 1.12.5 will correctly validate that either an IPv6 subnet is provided or that the IPAM driver can provide one when you specify the `--ipv6` option.

If you are currently using the `--ipv6` option *without* specifying the `--fixed-cidr-v6` option, the Docker daemon will refuse to start with the following message:

```text
Error starting daemon: Error initializing network controller: Error creating
                       default "bridge" network: failed to parse pool request
                       for address space "LocalDefault" pool " subpool ":
                       could not find an available, non-overlapping IPv6 address
                       pool among the defaults to assign to the network
```

To resolve this error, either remove the `--ipv6` flag (to preserve the same behavior as in Docker 1.12.3 and earlier), or provide an IPv6 subnet as the value of the `--fixed-cidr-v6` flag.

In a similar way, if you specify the `--ipv6` flag when creating a network with the default IPAM driver, without providing an IPv6 `--subnet`, network creation will fail with the following message:

```text
Error response from daemon: failed to parse pool request for address space
                            "LocalDefault" pool "" subpool "": could not find an
                            available, non-overlapping IPv6 address pool among
                            the defaults to assign to the network
```

To resolve this, either remove the `--ipv6` flag (to preserve the same behavior as in Docker 1.12.3 and earlier), or provide an IPv6 subnet as the value of the `--subnet` flag.

The network network creation will instead succeed if you use an external IPAM driver which supports automatic allocation of IPv6 subnets.

### [Runtime](#runtime-3)

* Fix race on sending stdin close event [#29424](https://github.com/docker/docker/pull/29424)

### [Networking](#networking-1)

* Fix panic in docker network ls when a network was created with `--ipv6` and no ipv6 `--subnet` in older docker versions [#29416](https://github.com/docker/docker/pull/29416)

### [Contrib](#contrib-2)

* Fix compilation on Darwin [#29370](https://github.com/docker/docker/pull/29370)

## [1.12.4 (2016-12-12)](#1124-2016-12-12)

> Important
>
> Docker 1.12 ships with an updated systemd unit file for rpm based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if;
>
> * the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or
> * a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive

Starting the `docker service` will produce an error:

```
Failed to start docker.service: Unit docker.socket failed to load: No such file or directory.
```

or

```
no sockets found via socket activation: make sure the service was started by systemd.
```

To resolve this:

* Backup the current version of the unit file, and replace the file with the [version that ships with docker 1.12](https://raw.githubusercontent.com/docker/docker/v1.12.0/contrib/init/systemd/docker.service.rpm)
* Remove the `Requires=docker.socket` directive from the `/usr/lib/systemd/system/docker.service` file if present
* Remove `-H fd://` from the `ExecStart` directive (both in the main unit file, and in any drop-in files present).

After making those changes, run `sudo systemctl daemon-reload`, and `sudo systemctl restart docker` to reload changes and (re)start the docker daemon.

### [Runtime](#runtime-4)

* Fix issue where volume metadata was not removed [#29083](https://github.com/docker/docker/pull/29083)
* Asynchronously close streams to prevent holding container lock [#29050](https://github.com/docker/docker/pull/29050)
* Fix selinux labels for newly created container volumes [#29050](https://github.com/docker/docker/pull/29050)
* Remove hostname validation [#28990](https://github.com/docker/docker/pull/28990)
* Fix deadlocks caused by IO races [#29095](https://github.com/docker/docker/pull/29095) [#29141](https://github.com/docker/docker/pull/29141)
* Return an empty stats if the container is restarting [#29150](https://github.com/docker/docker/pull/29150)
* Fix volume store locking [#29151](https://github.com/docker/docker/pull/29151)
* Ensure consistent status code in API [#29150](https://github.com/docker/docker/pull/29150)
* Fix incorrect opaque directory permission in overlay2 [#29093](https://github.com/docker/docker/pull/29093)
* Detect plugin content and error out on `docker pull` [#29297](https://github.com/docker/docker/pull/29297)

### [Swarm Mode](#swarm-mode-1)

* Update Swarmkit [#29047](https://github.com/docker/docker/pull/29047)

  * orchestrator/global: Fix deadlock on updates [docker/swarmkit#1760](https://github.com/docker/swarmkit/pull/1760)
  * on leader switchover preserve the vxlan id for existing networks [docker/swarmkit#1773](https://github.com/docker/swarmkit/pull/1773)

- Refuse swarm spec not named "default" [#29152](https://github.com/docker/docker/pull/29152)

### [Networking](#networking-2)

* Update libnetwork [#29004](https://github.com/docker/docker/pull/29004) [#29146](https://github.com/docker/docker/pull/29146)

  * Fix panic in embedded DNS [docker/libnetwork#1561](https://github.com/docker/libnetwork/pull/1561)
  * Fix unmarhalling panic when passing --link-local-ip on global scope network [docker/libnetwork#1564](https://github.com/docker/libnetwork/pull/1564)
  * Fix panic when network plugin returns nil StaticRoutes [docker/libnetwork#1563](https://github.com/docker/libnetwork/pull/1563)
  * Fix panic in `osl.(*networkNamespace).DeleteNeighbor` [docker/libnetwork#1555](https://github.com/docker/libnetwork/pull/1555)
  * Fix panic in swarm networking concurrent map read/write [docker/libnetwork#1570](https://github.com/docker/libnetwork/pull/1570)

  - Allow encrypted networks when running docker inside a container [docker/libnetwork#1502](https://github.com/docker/libnetwork/pull/1502)

  * Do not block autoallocation of IPv6 pool [docker/libnetwork#1538](https://github.com/docker/libnetwork/pull/1538)
  * Set timeout for netlink calls [docker/libnetwork#1557](https://github.com/docker/libnetwork/pull/1557)
  * Increase networking local store timeout to one minute [docker/libkv#140](https://github.com/docker/libkv/pull/140)
  * Fix a panic in `libnetwork.(*sandbox).execFunc` [docker/libnetwork#1556](https://github.com/docker/libnetwork/pull/1556)
  * Honor icc=false for internal networks [docker/libnetwork#1525](https://github.com/docker/libnetwork/pull/1525)

### [Logging](#logging-1)

* Update syslog log driver [#29150](https://github.com/docker/docker/pull/29150)

### [Contrib](#contrib-3)

* Run "dnf upgrade" before installing in fedora [#29150](https://github.com/docker/docker/pull/29150)
* Add build-date back to RPM packages [#29150](https://github.com/docker/docker/pull/29150)
* deb package filename changed to include distribution to distinguish between distribution code names [#27829](https://github.com/docker/docker/pull/27829)

## [1.12.3 (2016-10-26)](#1123-2016-10-26)

> Important
>
> Docker 1.12 ships with an updated systemd unit file for rpm based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the Docker service if;
>
> * the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or
> * a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive

Starting the `docker service` will produce an error:

```
Failed to start docker.service: Unit docker.socket failed to load: No such file or directory.
```

or

```
no sockets found via socket activation: make sure the service was started by systemd.
```

To resolve this:

* Backup the current version of the unit file, and replace the file with the [version that ships with docker 1.12](https://raw.githubusercontent.com/docker/docker/v1.12.0/contrib/init/systemd/docker.service.rpm)
* Remove the `Requires=docker.socket` directive from the `/usr/lib/systemd/system/docker.service` file if present
* Remove `-H fd://` from the `ExecStart` directive (both in the main unit file, and in any drop-in files present).

After making those changes, run `sudo systemctl daemon-reload`, and `sudo systemctl restart docker` to reload changes and (re)start the docker daemon.

### [Runtime](#runtime-5)

* Fix ambient capability usage in containers (CVE-2016-8867) [#27610](https://github.com/docker/docker/pull/27610)
* Prevent a deadlock in libcontainerd for Windows [#27136](https://github.com/docker/docker/pull/27136)
* Fix error reporting in CopyFileWithTar [#27075](https://github.com/docker/docker/pull/27075)

- Reset health status to starting when a container is restarted [#27387](https://github.com/docker/docker/pull/27387)
- Properly handle shared mount propagation in storage directory [#27609](https://github.com/docker/docker/pull/27609)

* Fix docker exec [#27610](https://github.com/docker/docker/pull/27610)
* Fix backward compatibility with containerd’s events log [#27693](https://github.com/docker/docker/pull/27693)

### [Swarm Mode](#swarm-mode-2)

* Fix conversion of restart-policy [#27062](https://github.com/docker/docker/pull/27062)

- Update Swarmkit [#27554](https://github.com/docker/docker/pull/27554)
- Avoid restarting a task that has already been restarted [docker/swarmkit#1305](https://github.com/docker/swarmkit/pull/1305)
- Allow duplicate published ports when they use different protocols [docker/swarmkit#1632](https://github.com/docker/swarmkit/pull/1632)
- Allow multiple randomly assigned published ports on service [docker/swarmkit#1657](https://github.com/docker/swarmkit/pull/1657)

* Fix panic when allocations happen at init time [docker/swarmkit#1651](https://github.com/docker/swarmkit/pull/1651)

### [Networking](#networking-3)

* Update libnetwork [#27559](https://github.com/docker/docker/pull/27559)

- Fix race in serializing sandbox to string [docker/libnetwork#1495](https://github.com/docker/libnetwork/pull/1495)
- Fix race during deletion [docker/libnetwork#1503](https://github.com/docker/libnetwork/pull/1503)

* Reset endpoint port info on connectivity revoke in bridge driver [docker/libnetwork#1504](https://github.com/docker/libnetwork/pull/1504)

- Fix a deadlock in networking code [docker/libnetwork#1507](https://github.com/docker/libnetwork/pull/1507)
- Fix a race in load balancer state [docker/libnetwork#1512](https://github.com/docker/libnetwork/pull/1512)

### [Logging](#logging-2)

* Update fluent-logger-golang to v1.2.1 [#27474](https://github.com/docker/docker/pull/27474)

### [Contrib](#contrib-4)

* Update buildtags for armhf ubuntu-trusty [#27327](https://github.com/docker/docker/pull/27327)
* Add AppArmor to runc buildtags for armhf [#27421](https://github.com/docker/docker/pull/27421)

## [1.12.2 (2016-10-11)](#1122-2016-10-11)

> Important
>
> Docker 1.12 ships with an updated systemd unit file for rpm based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if;
>
> * the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or
> * a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive

Starting the `docker service` will produce an error:

```
Failed to start docker.service: Unit docker.socket failed to load: No such file or directory.
```

or

```
no sockets found via socket activation: make sure the service was started by systemd.
```

To resolve this:

* Backup the current version of the unit file, and replace the file with the [version that ships with docker 1.12](https://raw.githubusercontent.com/docker/docker/v1.12.0/contrib/init/systemd/docker.service.rpm)
* Remove the `Requires=docker.socket` directive from the `/usr/lib/systemd/system/docker.service` file if present
* Remove `-H fd://` from the `ExecStart` directive (both in the main unit file, and in any drop-in files present).

After making those changes, run `sudo systemctl daemon-reload`, and `sudo systemctl restart docker` to reload changes and (re)start the docker daemon.

### [Runtime](#runtime-6)

* Fix a panic due to a race condition filtering `docker ps` [#26049](https://github.com/docker/docker/pull/26049)

- Implement retry logic to prevent "Unable to remove filesystem" errors when using the aufs storage driver [#26536](https://github.com/docker/docker/pull/26536)
- Prevent devicemapper from removing device symlinks if `dm.use_deferred_removal` is enabled [#24740](https://github.com/docker/docker/pull/24740)

* Fix an issue where the CLI did not return correct exit codes if a command was run with invalid options [#26777](https://github.com/docker/docker/pull/26777)
* Fix a panic due to a bug in stdout / stderr processing in health checks [#26507](https://github.com/docker/docker/pull/26507)
* Fix exec's children handling [#26874](https://github.com/docker/docker/pull/26874)
* Fix exec form of HEALTHCHECK CMD [#26208](https://github.com/docker/docker/pull/26208)

### [Networking](#networking-4)

* Fix a daemon start panic on armv5 [#24315](https://github.com/docker/docker/issues/24315)

- Vendor libnetwork [#26879](https://github.com/docker/docker/pull/26879) [#26953](https://github.com/docker/docker/pull/26953)
- Avoid returning early on agent join failures [docker/libnetwork#1473](https://github.com/docker/libnetwork/pull/1473)

* Fix service published port cleanup issues [docker/libetwork#1432](https://github.com/docker/libnetwork/pull/1432) [docker/libnetwork#1433](https://github.com/docker/libnetwork/pull/1433)

- Recover properly from transient gossip failures [docker/libnetwork#1446](https://github.com/docker/libnetwork/pull/1446)
- Disambiguate node names known to gossip cluster to avoid node name collision [docker/libnetwork#1451](https://github.com/docker/libnetwork/pull/1451)
- Honor user provided listen address for gossip [docker/libnetwork#1460](https://github.com/docker/libnetwork/pull/1460)
- Allow reachability via published port across services on the same host [docker/libnetwork#1398](https://github.com/docker/libnetwork/pull/1398)
- Change the ingress sandbox name from random id to just `ingress_sbox` [docker/libnetwork#1449](https://github.com/docker/libnetwork/pull/1449)

* Disable service discovery in ingress network [docker/libnetwork#1489](https://github.com/docker/libnetwork/pull/1489)

### [Swarm Mode](#swarm-mode-3)

* Fix remote detection of a node's address when it joins the cluster [#26211](https://github.com/docker/docker/pull/26211)
* Vendor SwarmKit [#26765](https://github.com/docker/docker/pull/26765)
* Bounce session after failed status update [docker/swarmkit#1539](https://github.com/docker/swarmkit/pull/1539)

- Fix possible raft deadlocks [docker/swarmkit#1537](https://github.com/docker/swarmkit/pull/1537)
- Fix panic and endpoint leak when a service is updated with no endpoints [docker/swarmkit#1481](https://github.com/docker/swarmkit/pull/1481)

* Produce an error if the same port is published twice on `service create` or `service update` [docker/swarmkit#1495](https://github.com/docker/swarmkit/pull/1495)

- Fix an issue where changes to a service were not detected, resulting in the service not being updated [docker/swarmkit#1497](https://github.com/docker/swarmkit/pull/1497)
- Do not allow service creation on ingress network [docker/swarmkit#1600](https://github.com/docker/swarmkit/pull/1600)

### [Contrib](#contrib-5)

* Update the debian sysv-init script to use `dockerd` instead of `docker daemon` [#25869](https://github.com/docker/docker/pull/25869)
* Improve stability when running the docker client on MacOS Sierra [#26875](https://github.com/docker/docker/pull/26875)

- Fix installation on debian stretch [#27184](https://github.com/docker/docker/pull/27184)

### [Windows](#windows-1)

* Fix an issue where arrow-navigation did not work when running the docker client in ConEmu [#25578](https://github.com/docker/docker/pull/25578)

## [1.12.1 (2016-08-18)](#1121-2016-08-18)

> Important
>
> Docker 1.12 ships with an updated systemd unit file for rpm based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if;
>
> * the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or
> * a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive

Starting the `docker service` will produce an error:

```
Failed to start docker.service: Unit docker.socket failed to load: No such file or directory.
```

or

```
no sockets found via socket activation: make sure the service was started by systemd.
```

To resolve this:

* Backup the current version of the unit file, and replace the file with the [version that ships with docker 1.12](https://raw.githubusercontent.com/docker/docker/v1.12.0/contrib/init/systemd/docker.service.rpm)
* Remove the `Requires=docker.socket` directive from the `/usr/lib/systemd/system/docker.service` file if present
* Remove `-H fd://` from the `ExecStart` directive (both in the main unit file, and in any drop-in files present).

After making those changes, run `sudo systemctl daemon-reload`, and `sudo systemctl restart docker` to reload changes and (re)start the docker daemon.

### [Client](#client)

* Add `Joined at` information in `node inspect --pretty` [#25512](https://github.com/docker/docker/pull/25512)

- Fix a crash on `service inspect` [#25454](https://github.com/docker/docker/pull/25454)
- Fix issue preventing `service update --env-add` to work as intended [#25427](https://github.com/docker/docker/pull/25427)
- Fix issue preventing `service update --publish-add` to work as intended [#25428](https://github.com/docker/docker/pull/25428)
- Remove `service update --network-add` and `service update --network-rm` flags because this feature is not yet implemented in 1.12, but was inadvertently added to the client in 1.12.0 [#25646](https://github.com/docker/docker/pull/25646)

### [Contrib](#contrib-6)

* Official ARM installation for Debian Jessie, Ubuntu Trusty, and Raspbian Jessie [#24815](https://github.com/docker/docker/pull/24815) [#25591](https://github.com/docker/docker/pull/25637)

- Add selinux policy per distribution/version, fixing issue preventing successful installation on Fedora 24, and Oracle Linux [#25334](https://github.com/docker/docker/pull/25334) [#25593](https://github.com/docker/docker/pull/25593)

### [Networking](#networking-5)

* Fix issue that prevented containers to be accessed by hostname with Docker overlay driver in Swarm Mode [#25603](https://github.com/docker/docker/pull/25603) [#25648](https://github.com/docker/docker/pull/25648)
* Fix random network issues on service with published port [#25603](https://github.com/docker/docker/pull/25603)
* Fix unreliable inter-service communication after scaling down and up [#25603](https://github.com/docker/docker/pull/25603)
* Fix issue where removing all tasks on a node and adding them back breaks connectivity with other services [#25603](https://github.com/docker/docker/pull/25603)
* Fix issue where a task that fails to start results in a race, causing a `network xxx not found` error that masks the actual error [#25550](https://github.com/docker/docker/pull/25550)
* Relax validation of SRV records for external services that use SRV records not formatted according to RFC 2782 [#25739](https://github.com/docker/docker/pull/25739)

### [Plugins (experimental)](#plugins-experimental)

* Make daemon events listen for plugin lifecycle events [#24760](https://github.com/docker/docker/pull/24760)
* Check for plugin state before enabling plugin [#25033](https://github.com/docker/docker/pull/25033)

- Remove plugin root from filesystem on `plugin rm` [#25187](https://github.com/docker/docker/pull/25187)
- Prevent deadlock when more than one plugin is installed [#25384](https://github.com/docker/docker/pull/25384)

### [Runtime](#runtime-7)

* Mask join tokens in daemon logs [#25346](https://github.com/docker/docker/pull/25346)

- Fix `docker ps --filter` causing the results to no longer be sorted by creation time [#25387](https://github.com/docker/docker/pull/25387)
- Fix various crashes [#25053](https://github.com/docker/docker/pull/25053)

### [Security](#security-1)

* Add `/proc/timer_list` to the masked paths list to prevent information leak from the host [#25630](https://github.com/docker/docker/pull/25630)
* Allow systemd to run with only `--cap-add SYS_ADMIN` rather than having to also add `--cap-add DAC_READ_SEARCH` or disabling seccomp filtering [#25567](https://github.com/docker/docker/pull/25567)

### [Swarm](#swarm)

* Fix an issue where the swarm can get stuck electing a new leader after quorum is lost [#25055](https://github.com/docker/docker/issues/25055)
* Fix unwanted rescheduling of containers after a leader failover [#25017](https://github.com/docker/docker/issues/25017)
* Change swarm root CA key to P256 curve [swarmkit#1376](https://github.com/docker/swarmkit/pull/1376)
* Allow forced removal of a node from a swarm [#25159](https://github.com/docker/docker/pull/25159)
* Fix connection leak when a node leaves a swarm [swarmkit/#1277](https://github.com/docker/swarmkit/pull/1277)
* Backdate swarm certificates by one hour to tolerate more clock skew [swarmkit/#1243](https://github.com/docker/swarmkit/pull/1243)
* Avoid high CPU use with many unschedulable tasks [swarmkit/#1287](https://github.com/docker/swarmkit/pull/1287)
* Fix issue with global tasks not starting up [swarmkit/#1295](https://github.com/docker/swarmkit/pull/1295)
* Garbage collect raft logs [swarmkit/#1327](https://github.com/docker/swarmkit/pull/1327)

### [Volume](#volume-1)

* Persist local volume options after a daemon restart [#25316](https://github.com/docker/docker/pull/25316)
* Fix an issue where the mount ID was not returned on volume unmount [#25333](https://github.com/docker/docker/pull/25333)
* Fix an issue where a volume mount could inadvertently create a bind mount [#25309](https://github.com/docker/docker/pull/25309)
* `docker service create --mount type=bind,...` now correctly validates if the source path exists, instead of creating it [#25494](https://github.com/docker/docker/pull/25494)

## [1.12.0 (2016-07-28)](#1120-2016-07-28)

> Important
>
> Docker 1.12.0 ships with an updated systemd unit file for rpm based installs (which includes RHEL, Fedora, CentOS, and Oracle Linux 7). When upgrading from an older version of Docker, the upgrade process may not automatically install the updated version of the unit file, or fail to start the `docker service` if;
>
> * the systemd unit file (`/usr/lib/systemd/system/docker.service`) contains local changes, or
> * a systemd drop-in file is present, and contains `-H fd://` in the `ExecStart` directive

Starting the `docker service` will produce an error:

```
Failed to start docker.service: Unit docker.socket failed to load: No such file or directory.
```

or

```
no sockets found via socket activation: make sure the service was started by systemd.
```

To resolve this:

* Backup the current version of the unit file, and replace the file with the [version that ships with docker 1.12](https://raw.githubusercontent.com/docker/docker/v1.12.0/contrib/init/systemd/docker.service.rpm)
* Remove the `Requires=docker.socket` directive from the `/usr/lib/systemd/system/docker.service` file if present
* Remove `-H fd://` from the `ExecStart` directive (both in the main unit file, and in any drop-in files present).

After making those changes, run `sudo systemctl daemon-reload`, and `sudo systemctl restart docker` to reload changes and (re)start the docker daemon.

> Important
>
> With Docker 1.12, a Linux `docker` installation now has two additional binaries; `dockerd`, and `docker-proxy`. If you have scripts for installing `docker`, make sure to update them accordingly.

### [Builder](#builder-1)

* New `HEALTHCHECK` Dockerfile instruction to support user-defined healthchecks [#23218](https://github.com/docker/docker/pull/23218)
* New `SHELL` Dockerfile instruction to specify the default shell when using the shell form for commands in a Dockerfile [#22489](https://github.com/docker/docker/pull/22489)
* Add `#escape=` Dockerfile directive to support platform-specific parsing of file paths in Dockerfile [#22268](https://github.com/docker/docker/pull/22268)
* Add support for comments in `.dockerignore` [#23111](https://github.com/docker/docker/pull/23111)

- Support for UTF-8 in Dockerfiles [#23372](https://github.com/docker/docker/pull/23372)
- Skip UTF-8 BOM bytes from `Dockerfile` and `.dockerignore` if exist [#23234](https://github.com/docker/docker/pull/23234)
- Windows: support for `ARG` to match Linux [#22508](https://github.com/docker/docker/pull/22508)

* Fix error message when building using a daemon with the bridge network disabled [#22932](https://github.com/docker/docker/pull/22932)

### [Contrib](#contrib-7)

* Enable seccomp for Centos 7 and Oracle Linux 7 [#22344](https://github.com/docker/docker/pull/22344)

- Remove MountFlags in systemd unit to allow shared mount propagation [#22806](https://github.com/docker/docker/pull/22806)

### [Distribution](#distribution-1)

* Add `--max-concurrent-downloads` and `--max-concurrent-uploads` daemon flags useful for situations where network connections don't support multiple downloads/uploads [#22445](https://github.com/docker/docker/pull/22445)

- Registry operations now honor the `ALL_PROXY` environment variable [#22316](https://github.com/docker/docker/pull/22316)
- Provide more information to the user on `docker load` [#23377](https://github.com/docker/docker/pull/23377)
- Always save registry digest metadata about images pushed and pulled [#23996](https://github.com/docker/docker/pull/23996)

### [Logging](#logging-3)

* Syslog logging driver now supports DGRAM sockets [#21613](https://github.com/docker/docker/pull/21613)
* Add `--details` option to `docker logs` to also display log tags [#21889](https://github.com/docker/docker/pull/21889)
* Enable syslog logger to have access to env and labels [#21724](https://github.com/docker/docker/pull/21724)
* An additional syslog-format option `rfc5424micro` to allow microsecond resolution in syslog timestamp [#21844](https://github.com/docker/docker/pull/21844)

- Inherit the daemon log options when creating containers [#21153](https://github.com/docker/docker/pull/21153)
- Remove `docker/` prefix from log messages tag and replace it with `{{.DaemonName}}` so that users have the option of changing the prefix [#22384](https://github.com/docker/docker/pull/22384)

### [Networking](#networking-6)

* Built-in Virtual-IP based internal and ingress load-balancing using IPVS [#23361](https://github.com/docker/docker/pull/23361)
* Routing Mesh using ingress overlay network [#23361](https://github.com/docker/docker/pull/23361)
* Secured multi-host overlay networking using encrypted control-plane and Data-plane [#23361](https://github.com/docker/docker/pull/23361)
* MacVlan driver is out of experimental [#23524](https://github.com/docker/docker/pull/23524)
* Add `driver` filter to `network ls` [#22319](https://github.com/docker/docker/pull/22319)
* Adding `network` filter to `docker ps --filter` [#23300](https://github.com/docker/docker/pull/23300)
* Add `--link-local-ip` flag to `create`, `run` and `network connect` to specify a container's link-local address [#23415](https://github.com/docker/docker/pull/23415)
* Add network label filter support [#21495](https://github.com/docker/docker/pull/21495)

- Removed dependency on external KV-Store for Overlay networking in Swarm-Mode [#23361](https://github.com/docker/docker/pull/23361)
- Add container's short-id as default network alias [#21901](https://github.com/docker/docker/pull/21901)
- `run` options `--dns` and `--net=host` are no longer mutually exclusive [#22408](https://github.com/docker/docker/pull/22408)

* Fix DNS issue when renaming containers with generated names [#22716](https://github.com/docker/docker/pull/22716)
* Allow both `network inspect -f {{.Id}}` and `network inspect -f {{.ID}}` to address inconsistency with inspect output [#23226](https://github.com/docker/docker/pull/23226)

### [Plugins (experimental)](#plugins-experimental-1)

* New `plugin` command to manager plugins with `install`, `enable`, `disable`, `rm`, `inspect`, `set` subcommands [#23446](https://github.com/docker/docker/pull/23446)

### [Remote API (v1.24) & Client](#remote-api-v124--client)

* Split the binary into two: `docker` (client) and `dockerd` (daemon) [#20639](https://github.com/docker/docker/pull/20639)
* Add `before` and `since` filters to `docker images --filter` [#22908](https://github.com/docker/docker/pull/22908)
* Add `--limit` option to `docker search` [#23107](https://github.com/docker/docker/pull/23107)
* Add `--filter` option to `docker search` [#22369](https://github.com/docker/docker/pull/22369)
* Add security options to `docker info` output [#21172](https://github.com/docker/docker/pull/21172) [#23520](https://github.com/docker/docker/pull/23520)
* Add insecure registries to `docker info` output [#20410](https://github.com/docker/docker/pull/20410)
* Extend Docker authorization with TLS user information [#21556](https://github.com/docker/docker/pull/21556)
* devicemapper: expose Minimum Thin Pool Free Space through `docker info` [#21945](https://github.com/docker/docker/pull/21945)

- API now returns a JSON object when an error occurs making it more consistent [#22880](https://github.com/docker/docker/pull/22880)

* Prevent `docker run -i --restart` from hanging on exit [#22777](https://github.com/docker/docker/pull/22777)
* Fix API/CLI discrepancy on hostname validation [#21641](https://github.com/docker/docker/pull/21641)
* Fix discrepancy in the format of sizes in `stats` from HumanSize to BytesSize [#21773](https://github.com/docker/docker/pull/21773)
* authz: when request is denied return forbidden exit code (403) [#22448](https://github.com/docker/docker/pull/22448)
* Windows: fix tty-related displaying issues [#23878](https://github.com/docker/docker/pull/23878)

### [Runtime](#runtime-8)

* Split the userland proxy to a separate binary (`docker-proxy`) [#23312](https://github.com/docker/docker/pull/23312)
* Add `--live-restore` daemon flag to keep containers running when daemon shuts down, and regain control on startup [#23213](https://github.com/docker/docker/pull/23213)
* Ability to add OCI-compatible runtimes (via `--add-runtime` daemon flag) and select one with `--runtime` on `create` and `run` [#22983](https://github.com/docker/docker/pull/22983)
* New `overlay2` graphdriver for Linux 4.0+ with multiple lower directory support [#22126](https://github.com/docker/docker/pull/22126)
* New load/save image events [#22137](https://github.com/docker/docker/pull/22137)
* Add support for reloading daemon configuration through systemd [#22446](https://github.com/docker/docker/pull/22446)
* Add disk quota support for btrfs [#19651](https://github.com/docker/docker/pull/19651)
* Add disk quota support for zfs [#21946](https://github.com/docker/docker/pull/21946)
* Add support for `docker run --pid=container:<id>` [#22481](https://github.com/docker/docker/pull/22481)
* Align default seccomp profile with selected capabilities [#22554](https://github.com/docker/docker/pull/22554)
* Add a `daemon reload` event when the daemon reloads its configuration [#22590](https://github.com/docker/docker/pull/22590)
* Add `trace` capability in the pprof profiler to show execution traces in binary form [#22715](https://github.com/docker/docker/pull/22715)
* Add a `detach` event [#22898](https://github.com/docker/docker/pull/22898)
* Add support for setting sysctls with `--sysctl` [#19265](https://github.com/docker/docker/pull/19265)
* Add `--storage-opt` flag to `create` and `run` allowing to set `size` on devicemapper [#19367](https://github.com/docker/docker/pull/19367)
* Add `--oom-score-adjust` daemon flag with a default value of `-500` making the daemon less likely to be killed before containers [#24516](https://github.com/docker/docker/pull/24516)

- Undeprecate the `-c` short alias of `--cpu-shares` on `run`, `build`, `create`, `update` [#22621](https://github.com/docker/docker/pull/22621)
- Prevent from using aufs and overlay graphdrivers on an eCryptfs mount [#23121](https://github.com/docker/docker/pull/23121)

* Fix issues with tmpfs mount ordering [#22329](https://github.com/docker/docker/pull/22329)
* Created containers are no longer listed on `docker ps -a -f exited=0` [#21947](https://github.com/docker/docker/pull/21947)
* Fix an issue where containers are stuck in a "Removal In Progress" state [#22423](https://github.com/docker/docker/pull/22423)
* Fix bug that was returning an HTTP 500 instead of a 400 when not specifying a command on run/create [#22762](https://github.com/docker/docker/pull/22762)
* Fix bug with `--detach-keys` whereby input matching a prefix of the detach key was not preserved [#22943](https://github.com/docker/docker/pull/22943)
* SELinux labeling is now disabled when using `--privileged` mode [#22993](https://github.com/docker/docker/pull/22993)
* If volume-mounted into a container, `/etc/hosts`, `/etc/resolv.conf`, `/etc/hostname` are no longer SELinux-relabeled [#22993](https://github.com/docker/docker/pull/22993)
* Fix inconsistency in `--tmpfs` behavior regarding mount options [#22438](https://github.com/docker/docker/pull/22438)
* Fix an issue where daemon hangs at startup [#23148](https://github.com/docker/docker/pull/23148)
* Ignore SIGPIPE events to prevent journald restarts to crash docker in some cases [#22460](https://github.com/docker/docker/pull/22460)
* Containers are not removed from stats list on error [#20835](https://github.com/docker/docker/pull/20835)
* Fix `on-failure` restart policy when daemon restarts [#20853](https://github.com/docker/docker/pull/20853)
* Fix an issue with `stats` when a container is using another container's network [#21904](https://github.com/docker/docker/pull/21904)

### [Swarm Mode](#swarm-mode-4)

* New `swarm` command to manage swarms with `init`, `join`, `join-token`, `leave`, `update` subcommands [#23361](https://github.com/docker/docker/pull/23361) [#24823](https://github.com/docker/docker/pull/24823)
* New `service` command to manage swarm-wide services with `create`, `inspect`, `update`, `rm`, `ps` subcommands [#23361](https://github.com/docker/docker/pull/23361) [#25140](https://github.com/docker/docker/pull/25140)
* New `node` command to manage nodes with `accept`, `promote`, `demote`, `inspect`, `update`, `ps`, `ls` and `rm` subcommands [#23361](https://github.com/docker/docker/pull/23361) [#25140](https://github.com/docker/docker/pull/25140)
* (experimental) New `stack` and `deploy` commands to manage and deploy multi-service applications [#23522](https://github.com/docker/docker/pull/23522) [#25140](https://github.com/docker/docker/pull/25140)

### [Volume](#volume-2)

* Add support for local and global volume scopes (analogous to network scopes) [#22077](https://github.com/docker/docker/pull/22077)
* Allow volume drivers to provide a `Status` field [#21006](https://github.com/docker/docker/pull/21006)
* Add name/driver filter support for volume [#21361](https://github.com/docker/docker/pull/21361)

- Mount/Unmount operations now receives an opaque ID to allow volume drivers to differentiate between two callers [#21015](https://github.com/docker/docker/pull/21015)

* Fix issue preventing to remove a volume in a corner case [#22103](https://github.com/docker/docker/pull/22103)
* Windows: Enable auto-creation of host-path to match Linux [#22094](https://github.com/docker/docker/pull/22094)

### [Deprecation](#deprecation-1)

* Environment variables `DOCKER_CONTENT_TRUST_OFFLINE_PASSPHRASE` and `DOCKER_CONTENT_TRUST_TAGGING_PASSPHRASE` have been renamed to `DOCKER_CONTENT_TRUST_ROOT_PASSPHRASE` and `DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE` respectively [#22574](https://github.com/docker/docker/pull/22574)
* Remove deprecated `syslog-tag`, `gelf-tag`, `fluentd-tag` log option in favor of the more generic `tag` one [#22620](https://github.com/docker/docker/pull/22620)
* Remove deprecated feature of passing HostConfig at API container start [#22570](https://github.com/docker/docker/pull/22570)
* Remove deprecated `-f`/`--force` flag on docker tag [#23090](https://github.com/docker/docker/pull/23090)
* Remove deprecated `/containers/<id|name>/copy` endpoint [#22149](https://github.com/docker/docker/pull/22149)
* Remove deprecated `docker ps` flags `--since` and `--before` [#22138](https://github.com/docker/docker/pull/22138)
* Deprecate the old 3-args form of `docker import` [#23273](https://github.com/docker/docker/pull/23273)

## [1.11.2 (2016-05-31)](#1112-2016-05-31)

### [Networking](#networking-7)

* Fix a stale endpoint issue on overlay networks during ungraceful restart ([#23015](https://github.com/docker/docker/pull/23015))
* Fix an issue where the wrong port could be reported by `docker inspect/ps/port` ([#22997](https://github.com/docker/docker/pull/22997))

### [Runtime](#runtime-9)

* Fix a potential panic when running `docker build` ([#23032](https://github.com/docker/docker/pull/23032))
* Fix interpretation of `--user` parameter ([#22998](https://github.com/docker/docker/pull/22998))
* Fix a bug preventing container statistics to be correctly reported ([#22955](https://github.com/docker/docker/pull/22955))
* Fix an issue preventing container to be restarted after daemon restart ([#22947](https://github.com/docker/docker/pull/22947))
* Fix issues when running 32 bit binaries on Ubuntu 16.04 ([#22922](https://github.com/docker/docker/pull/22922))
* Fix a possible deadlock on image deletion and container attach ([#22918](https://github.com/docker/docker/pull/22918))
* Fix an issue where containers fail to start after a daemon restart if they depend on a containerized cluster store ([#22561](https://github.com/docker/docker/pull/22561))
* Fix an issue causing `docker ps` to hang on CentOS when using devicemapper ([#22168](https://github.com/docker/docker/pull/22168), [#23067](https://github.com/docker/docker/pull/23067))
* Fix a bug preventing to `docker exec` into a container when using devicemapper ([#22168](https://github.com/docker/docker/pull/22168), [#23067](https://github.com/docker/docker/pull/23067))

## [1.11.1 (2016-04-26)](#1111-2016-04-26)

### [Distribution](#distribution-2)

* Fix schema2 manifest media type to be of type `application/vnd.docker.container.image.v1+json` ([#21949](https://github.com/docker/docker/pull/21949))

### [Documentation](#documentation)

* Add missing API documentation for changes introduced with 1.11.0 ([#22048](https://github.com/docker/docker/pull/22048))

### [Builder](#builder-2)

* Append label passed to `docker build` as arguments as an implicit `LABEL` command at the end of the processed `Dockerfile` ([#22184](https://github.com/docker/docker/pull/22184))

### [Networking](#networking-8)

* Fix a panic that would occur when forwarding DNS query ([#22261](https://github.com/docker/docker/pull/22261))
* Fix an issue where OS threads could end up within an incorrect network namespace when using user defined networks ([#22261](https://github.com/docker/docker/pull/22261))

### [Runtime](#runtime-10)

* Fix a bug preventing labels configuration to be reloaded via the config file ([#22299](https://github.com/docker/docker/pull/22299))
* Fix a regression where container mounting `/var/run` would prevent other containers from being removed ([#22256](https://github.com/docker/docker/pull/22256))
* Fix an issue where it would be impossible to update both `memory-swap` and `memory` value together ([#22255](https://github.com/docker/docker/pull/22255))
* Fix a regression from 1.11.0 where the `/auth` endpoint would not initialize `serveraddress` if it is not provided ([#22254](https://github.com/docker/docker/pull/22254))
* Add missing cleanup of container temporary files when cancelling a schedule restart ([#22237](https://github.com/docker/docker/pull/22237))
* Remove scary error message when no restart policy is specified ([#21993](https://github.com/docker/docker/pull/21993))
* Fix a panic that would occur when the plugins were activated via the json spec ([#22191](https://github.com/docker/docker/pull/22191))
* Fix restart backoff logic to correctly reset delay if container ran for at least 10secs ([#22125](https://github.com/docker/docker/pull/22125))
* Remove error message when a container restart get cancelled ([#22123](https://github.com/docker/docker/pull/22123))
* Fix an issue where `docker` would not correctly clean up after `docker exec` ([#22121](https://github.com/docker/docker/pull/22121))
* Fix a panic that could occur when serving concurrent `docker stats` commands ([#22120](https://github.com/docker/docker/pull/22120))\`
* Revert deprecation of non-existent host directories auto-creation ([#22065](https://github.com/docker/docker/pull/22065))
* Hide misleading rpc error on daemon shutdown ([#22058](https://github.com/docker/docker/pull/22058))

## [1.11.0 (2016-04-13)](#1110-2016-04-13)

> Important
>
> With Docker 1.11, a Linux Docker installation is now made of 4 binaries (`docker`, [`docker-containerd`](https://github.com/docker/containerd), [`docker-containerd-shim`](https://github.com/docker/containerd) and [`docker-runc`](https://github.com/opencontainers/runc)). If you have scripts relying on `docker` being a single static binaries, make sure to update them. Interaction with the daemon stay the same otherwise, the usage of the other binaries should be transparent. A Windows Docker installation remains a single binary, `docker.exe`.

### [Builder](#builder-3)

* Fix a bug where Docker would not use the correct uid/gid when processing the `WORKDIR` command ([#21033](https://github.com/docker/docker/pull/21033))
* Fix a bug where copy operations with userns would not use the proper uid/gid ([#20782](https://github.com/docker/docker/pull/20782), [#21162](https://github.com/docker/docker/pull/21162))

### [Client](#client-1)

* Usage of the `:` separator for security option has been deprecated. `=` should be used instead ([#21232](https://github.com/docker/docker/pull/21232))

- The client user agent is now passed to the registry on `pull`, `build`, `push`, `login` and `search` operations ([#21306](https://github.com/docker/docker/pull/21306), [#21373](https://github.com/docker/docker/pull/21373))

* Allow setting the Domainname and Hostname separately through the API ([#20200](https://github.com/docker/docker/pull/20200))
* Docker info will now warn users if it can not detect the kernel version or the operating system ([#21128](https://github.com/docker/docker/pull/21128))

- Fix an issue where `docker stats --no-stream` output could be all 0s ([#20803](https://github.com/docker/docker/pull/20803))
- Fix a bug where some newly started container would not appear in a running `docker stats` command ([#20792](https://github.com/docker/docker/pull/20792))

* Post processing is no longer enabled for linux-cgo terminals ([#20587](https://github.com/docker/docker/pull/20587))

- Values to `--hostname` are now refused if they do not comply with [RFC1123](https://tools.ietf.org/html/rfc1123) ([#20566](https://github.com/docker/docker/pull/20566))

* Docker learned how to use a SOCKS proxy ([#20366](https://github.com/docker/docker/pull/20366), [#18373](https://github.com/docker/docker/pull/18373))
* Docker now supports external credential stores ([#20107](https://github.com/docker/docker/pull/20107))

- `docker ps` now supports displaying the list of volumes mounted inside a container ([#20017](https://github.com/docker/docker/pull/20017))
- `docker info` now also reports Docker's root directory location ([#19986](https://github.com/docker/docker/pull/19986))

* Docker now prohibits login in with an empty username (spaces are trimmed) ([#19806](https://github.com/docker/docker/pull/19806))

- Docker events attributes are now sorted by key ([#19761](https://github.com/docker/docker/pull/19761))
- `docker ps` no longer shows exported port for stopped containers ([#19483](https://github.com/docker/docker/pull/19483))

* Docker now cleans after itself if a save/export command fails ([#17849](https://github.com/docker/docker/pull/17849))

- Docker load learned how to display a progress bar ([#17329](https://github.com/docker/docker/pull/17329), [#120078](https://github.com/docker/docker/pull/20078))

### [Distribution](#distribution-3)

* Fix a panic that occurred when pulling an image with 0 layers ([#21222](https://github.com/docker/docker/pull/21222))
* Fix a panic that could occur on error while pushing to a registry with a misconfigured token service ([#21212](https://github.com/docker/docker/pull/21212))

- All first-level delegation roles are now signed when doing a trusted push ([#21046](https://github.com/docker/docker/pull/21046))
- OAuth support for registries was added ([#20970](https://github.com/docker/docker/pull/20970))

* `docker login` now handles token using the implementation found in [docker/distribution](https://github.com/docker/distribution) ([#20832](https://github.com/docker/docker/pull/20832))
* `docker login` will no longer prompt for an email ([#20565](https://github.com/docker/docker/pull/20565))
* Docker will now fallback to registry V1 if no basic auth credentials are available ([#20241](https://github.com/docker/docker/pull/20241))
* Docker will now try to resume layer download where it left off after a network error/timeout ([#19840](https://github.com/docker/docker/pull/19840))

- Fix generated manifest mediaType when pushing cross-repository ([#19509](https://github.com/docker/docker/pull/19509))
- Fix docker requesting additional push credentials when pulling an image if Content Trust is enabled ([#20382](https://github.com/docker/docker/pull/20382))

### [Logging](#logging-4)

* Fix a race in the journald log driver ([#21311](https://github.com/docker/docker/pull/21311))

- Docker syslog driver now uses the RFC-5424 format when emitting logs ([#20121](https://github.com/docker/docker/pull/20121))
- Docker GELF log driver now allows to specify the compression algorithm and level via the `gelf-compression-type` and `gelf-compression-level` options ([#19831](https://github.com/docker/docker/pull/19831))
- Docker daemon learned to output uncolorized logs via the `--raw-logs` options ([#19794](https://github.com/docker/docker/pull/19794))

* Docker, on Windows platform, now includes an ETW (Event Tracing in Windows) logging driver named `etwlogs` ([#19689](https://github.com/docker/docker/pull/19689))

- Journald log driver learned how to handle tags ([#19564](https://github.com/docker/docker/pull/19564))

* The fluentd log driver learned the following options: `fluentd-address`, `fluentd-buffer-limit`, `fluentd-retry-wait`, `fluentd-max-retries` and `fluentd-async-connect` ([#19439](https://github.com/docker/docker/pull/19439))
* Docker learned to send log to Google Cloud via the new `gcplogs` logging driver. ([#18766](https://github.com/docker/docker/pull/18766))

### [Misc](#misc)

* When saving linked images together with `docker save` a subsequent `docker load` will correctly restore their parent/child relationship ([#21385](https://github.com/docker/docker/pull/21385))
* Support for building the Docker cli for OpenBSD was added ([#21325](https://github.com/docker/docker/pull/21325))
* Labels can now be applied at network, volume and image creation ([#21270](https://github.com/docker/docker/pull/21270))

- The `dockremap` is now created as a system user ([#21266](https://github.com/docker/docker/pull/21266))

* Fix a few response body leaks ([#21258](https://github.com/docker/docker/pull/21258))
* Docker, when run as a service with systemd, will now properly manage its processes cgroups ([#20633](https://github.com/docker/docker/pull/20633))

- `docker info` now reports the value of cgroup KernelMemory or emits a warning if it is not supported ([#20863](https://github.com/docker/docker/pull/20863))
- `docker info` now also reports the cgroup driver in use ([#20388](https://github.com/docker/docker/pull/20388))
- Docker completion is now available on PowerShell ([#19894](https://github.com/docker/docker/pull/19894))
- `dockerinit` is no more ([#19490](https://github.com/docker/docker/pull/19490),[#19851](https://github.com/docker/docker/pull/19851))

* Support for building Docker on arm64 was added ([#19013](https://github.com/docker/docker/pull/19013))
* Experimental support for building docker.exe in a native Windows Docker installation ([#18348](https://github.com/docker/docker/pull/18348))

### [Networking](#networking-9)

* Fix panic if a node is forcibly removed from the cluster ([#21671](https://github.com/docker/docker/pull/21671))
* Fix "error creating vxlan interface" when starting a container in a Swarm cluster ([#21671](https://github.com/docker/docker/pull/21671))

- `docker network inspect` will now report all endpoints whether they have an active container or not ([#21160](https://github.com/docker/docker/pull/21160))

* Experimental support for the MacVlan and IPVlan network drivers has been added ([#21122](https://github.com/docker/docker/pull/21122))

- Output of `docker network ls` is now sorted by network name ([#20383](https://github.com/docker/docker/pull/20383))

* Fix a bug where Docker would allow a network to be created with the reserved `default` name ([#19431](https://github.com/docker/docker/pull/19431))

- `docker network inspect` returns whether a network is internal or not ([#19357](https://github.com/docker/docker/pull/19357))

* Control IPv6 via explicit option when creating a network (`docker network create --ipv6`). This shows up as a new `EnableIPv6` field in `docker network inspect` ([#17513](https://github.com/docker/docker/pull/17513))

- Support for AAAA Records (aka IPv6 Service Discovery) in embedded DNS Server ([#21396](https://github.com/docker/docker/pull/21396))

* Fix to not forward docker domain IPv6 queries to external servers ([#21396](https://github.com/docker/docker/pull/21396))

- Multiple A/AAAA records from embedded DNS Server for DNS Round robin ([#21019](https://github.com/docker/docker/pull/21019))

* Fix endpoint count inconsistency after an ungraceful daemon restart ([#21261](https://github.com/docker/docker/pull/21261))
* Move the ownership of exposed ports and port-mapping options from Endpoint to Sandbox ([#21019](https://github.com/docker/docker/pull/21019))
* Fixed a bug which prevents docker reload when host is configured with ipv6.disable=1 ([#21019](https://github.com/docker/docker/pull/21019))
* Added inbuilt nil IPAM driver ([#21019](https://github.com/docker/docker/pull/21019))
* Fixed bug in iptables.Exists() logic [#21019](https://github.com/docker/docker/pull/21019)
* Fixed a Veth interface leak when using overlay network ([#21019](https://github.com/docker/docker/pull/21019))
* Fixed a bug which prevents docker reload after a network delete during shutdown ([#20214](https://github.com/docker/docker/pull/20214))
* Make sure iptables chains are recreated on firewalld reload ([#20419](https://github.com/docker/docker/pull/20419))
* Allow to pass global datastore during config reload ([#20419](https://github.com/docker/docker/pull/20419))
* For anonymous containers use the alias name for IP to name mapping, ie:DNS PTR record ([#21019](https://github.com/docker/docker/pull/21019))
* Fix a panic when deleting an entry from /etc/hosts file ([#21019](https://github.com/docker/docker/pull/21019))
* Source the forwarded DNS queries from the container net namespace ([#21019](https://github.com/docker/docker/pull/21019))
* Fix to retain the network internal mode config for bridge networks on daemon reload (\[#21780] (<https://github.com/docker/docker/pull/21780>))
* Fix to retain IPAM driver option configs on daemon reload (\[#21914] (<https://github.com/docker/docker/pull/21914>))

### [Plugins](#plugins-2)

* Fix a file descriptor leak that would occur every time plugins were enumerated ([#20686](https://github.com/docker/docker/pull/20686))
* Fix an issue where Authz plugin would corrupt the payload body when faced with a large amount of data ([#20602](https://github.com/docker/docker/pull/20602))

### [Runtime](#runtime-11)

* Fix a panic that could occur when cleanup after a container started with invalid parameters ([#21716](https://github.com/docker/docker/pull/21716))
* Fix a race with event timers stopping early ([#21692](https://github.com/docker/docker/pull/21692))
* Fix race conditions in the layer store, potentially corrupting the map and crashing the process ([#21677](https://github.com/docker/docker/pull/21677))
* Un-deprecate auto-creation of host directories for mounts. This feature was marked deprecated in ([#21666](https://github.com/docker/docker/pull/21666)) Docker 1.9, but was decided to be too much of a backward-incompatible change, so it was decided to keep the feature.

- It is now possible for containers to share the NET and IPC namespaces when `userns` is enabled ([#21383](https://github.com/docker/docker/pull/21383))
- `docker inspect <image-id>` will now expose the rootfs layers ([#21370](https://github.com/docker/docker/pull/21370))
- Docker Windows gained a minimal `top` implementation ([#21354](https://github.com/docker/docker/pull/21354))

* Docker learned to report the faulty exe when a container cannot be started due to its condition ([#21345](https://github.com/docker/docker/pull/21345))
* Docker with device mapper will now refuse to run if `udev sync` is not available ([#21097](https://github.com/docker/docker/pull/21097))

- Fix a bug where Docker would not validate the config file upon configuration reload ([#21089](https://github.com/docker/docker/pull/21089))
- Fix a hang that would happen on attach if initial start was to fail ([#21048](https://github.com/docker/docker/pull/21048))
- Fix an issue where registry service options in the daemon configuration file were not properly taken into account ([#21045](https://github.com/docker/docker/pull/21045))
- Fix a race between the exec and resize operations ([#21022](https://github.com/docker/docker/pull/21022))
- Fix an issue where nanoseconds were not correctly taken in account when filtering Docker events ([#21013](https://github.com/docker/docker/pull/21013))
- Fix the handling of Docker command when passed a 64 bytes id ([#21002](https://github.com/docker/docker/pull/21002))

* Docker will now return a `204` (i.e http.StatusNoContent) code when it successfully deleted a network ([#20977](https://github.com/docker/docker/pull/20977))

- Fix a bug where the daemon would wait indefinitely in case the process it was about to killed had already exited on its own ([#20967](https://github.com/docker/docker/pull/20967)

* The devmapper driver learned the `dm.min_free_space` option. If the mapped device free space reaches the passed value, new device creation will be prohibited. ([#20786](https://github.com/docker/docker/pull/20786))

- Docker can now prevent processes in container to gain new privileges via the `--security-opt=no-new-privileges` flag ([#20727](https://github.com/docker/docker/pull/20727))

* Starting a container with the `--device` option will now correctly resolves symlinks ([#20684](https://github.com/docker/docker/pull/20684))

- Docker now relies on [`containerd`](https://github.com/docker/containerd) and [`runc`](https://github.com/opencontainers/runc) to spawn containers. ([#20662](https://github.com/docker/docker/pull/20662))

* Fix docker configuration reloading to only alter value present in the given config file ([#20604](https://github.com/docker/docker/pull/20604))

- Docker now allows setting a container hostname via the `--hostname` flag when `--net=host` ([#20177](https://github.com/docker/docker/pull/20177))
- Docker now allows executing privileged container while running with `--userns-remap` if both `--privileged` and the new `--userns=host` flag are specified ([#20111](https://github.com/docker/docker/pull/20111))

* Fix Docker not cleaning up correctly old containers upon restarting after a crash ([#19679](https://github.com/docker/docker/pull/19679))

- Docker will now error out if it doesn't recognize a configuration key within the config file ([#19517](https://github.com/docker/docker/pull/19517))

* Fix container loading, on daemon startup, when they depends on a plugin running within a container ([#19500](https://github.com/docker/docker/pull/19500))

- `docker update` learned how to change a container restart policy ([#19116](https://github.com/docker/docker/pull/19116))
- `docker inspect` now also returns a new `State` field containing the container state in a human readable way (i.e. one of `created`, `restarting`, `running`, `paused`, `exited` or `dead`)([#18966](https://github.com/docker/docker/pull/18966))

* Docker learned to limit the number of active pids (i.e. processes) within the container via the `pids-limit` flags. NOTE: This requires `CGROUP_PIDS=y` to be in the kernel configuration. ([#18697](https://github.com/docker/docker/pull/18697))

- `docker load` now has a `--quiet` option to suppress the load output ([#20078](https://github.com/docker/docker/pull/20078))
- Fix a bug in neighbor discovery for IPv6 peers ([#20842](https://github.com/docker/docker/pull/20842))
- Fix a panic during cleanup if a container was started with invalid options ([#21802](https://github.com/docker/docker/pull/21802))
- Fix a situation where a container cannot be stopped if the terminal is closed ([#21840](https://github.com/docker/docker/pull/21840))

### [Security](#security-2)

* Object with the `pcp_pmcd_t` selinux type were given management access to `/var/lib/docker(/.*)?` ([#21370](https://github.com/docker/docker/pull/21370))
* `restart_syscall`, `copy_file_range`, `mlock2` joined the list of allowed calls in the default seccomp profile ([#21117](https://github.com/docker/docker/pull/21117), [#21262](https://github.com/docker/docker/pull/21262))
* `send`, `recv` and `x32` were added to the list of allowed syscalls and arch in the default seccomp profile ([#19432](https://github.com/docker/docker/pull/19432))
* Docker Content Trust now requests the server to perform snapshot signing ([#21046](https://github.com/docker/docker/pull/21046))
* Support for using YubiKeys for Content Trust signing has been moved out of experimental ([#21591](https://github.com/docker/docker/pull/21591))

### [Volumes](#volumes)

* Output of `docker volume ls` is now sorted by volume name ([#20389](https://github.com/docker/docker/pull/20389))
* Local volumes can now accept options similar to the unix `mount` tool ([#20262](https://github.com/docker/docker/pull/20262))

- Fix an issue where one letter directory name could not be used as source for volumes ([#21106](https://github.com/docker/docker/pull/21106))

* `docker run -v` now accepts a new flag `nocopy`. This tells the runtime not to copy the container path content into the volume (which is the default behavior) ([#21223](https://github.com/docker/docker/pull/21223))

## [1.10.3 (2016-03-10)](#1103-2016-03-10)

### [Runtime](#runtime-12)

* Fix Docker client exiting with an "Unrecognized input header" error [#20706](https://github.com/docker/docker/pull/20706)
* Fix Docker exiting if Exec is started with both `AttachStdin` and `Detach` [#20647](https://github.com/docker/docker/pull/20647)

### [Distribution](#distribution-4)

* Fix a crash when pushing multiple images sharing the same layers to the same repository in parallel [#20831](https://github.com/docker/docker/pull/20831)
* Fix a panic when pushing images to a registry which uses a misconfigured token service [#21030](https://github.com/docker/docker/pull/21030)

### [Plugin system](#plugin-system)

* Fix issue preventing volume plugins to start when SELinux is enabled [#20834](https://github.com/docker/docker/pull/20834)
* Prevent Docker from exiting if a volume plugin returns a null response for Get requests [#20682](https://github.com/docker/docker/pull/20682)
* Fix plugin system leaking file descriptors if a plugin has an error [#20680](https://github.com/docker/docker/pull/20680)

### [Security](#security-3)

* Fix linux32 emulation to fail during docker build [#20672](https://github.com/docker/docker/pull/20672) It was due to the `personality` syscall being blocked by the default seccomp profile.
* Fix Oracle XE 10g failing to start in a container [#20981](https://github.com/docker/docker/pull/20981) It was due to the `ipc` syscall being blocked by the default seccomp profile.
* Fix user namespaces not working on Linux From Scratch [#20685](https://github.com/docker/docker/pull/20685)
* Fix issue preventing daemon to start if userns is enabled and the `subuid` or `subgid` files contain comments [#20725](https://github.com/docker/docker/pull/20725)

## [1.10.2 (2016-02-22)](#1102-2016-02-22)

### [Runtime](#runtime-13)

* Prevent systemd from deleting containers' cgroups when its configuration is reloaded [#20518](https://github.com/docker/docker/pull/20518)
* Fix SELinux issues by disregarding `--read-only` when mounting `/dev/mqueue` [#20333](https://github.com/docker/docker/pull/20333)
* Fix chown permissions used during `docker cp` when userns is used [#20446](https://github.com/docker/docker/pull/20446)
* Fix configuration loading issue with all booleans defaulting to `true` [#20471](https://github.com/docker/docker/pull/20471)
* Fix occasional panic with `docker logs -f` [#20522](https://github.com/docker/docker/pull/20522)

### [Distribution](#distribution-5)

* Keep layer reference if deletion failed to avoid a badly inconsistent state [#20513](https://github.com/docker/docker/pull/20513)
* Handle gracefully a corner case when canceling migration [#20372](https://github.com/docker/docker/pull/20372)
* Fix docker import on compressed data [#20367](https://github.com/docker/docker/pull/20367)
* Fix tar-split files corruption during migration that later cause docker push and docker save to fail [#20458](https://github.com/docker/docker/pull/20458)

### [Networking](#networking-10)

* Fix daemon crash if embedded DNS is sent garbage [#20510](https://github.com/docker/docker/pull/20510)

### [Volumes](#volumes-1)

* Fix issue with multiple volume references with same name [#20381](https://github.com/docker/docker/pull/20381)

### [Security](#security-4)

* Fix potential cache corruption and delegation conflict issues [#20523](https://github.com/docker/docker/pull/20523)

## [1.10.1 (2016-02-11)](#1101-2016-02-11)

### [Runtime](#runtime-14)

* Do not stop daemon on migration hard failure [#20156](https://github.com/docker/docker/pull/20156)

- Fix various issues with migration to content-addressable images [#20058](https://github.com/docker/docker/pull/20058)
- Fix ZFS permission bug with user namespaces [#20045](https://github.com/docker/docker/pull/20045)
- Do not leak /dev/mqueue from the host to all containers, keep it container-specific [#19876](https://github.com/docker/docker/pull/19876) [#20133](https://github.com/docker/docker/pull/20133)
- Fix `docker ps --filter before=...` to not show stopped containers without providing `-a` flag [#20135](https://github.com/docker/docker/pull/20135)

### [Security](#security-5)

* Fix issue preventing docker events to work properly with authorization plugin [#20002](https://github.com/docker/docker/pull/20002)

### [Distribution](#distribution-6)

* Add additional verifications and prevent from uploading invalid data to registries [#20164](https://github.com/docker/docker/pull/20164)

- Fix regression preventing uppercase characters in image reference hostname [#20175](https://github.com/docker/docker/pull/20175)

### [Networking](#networking-11)

* Fix embedded DNS for user-defined networks in the presence of firewalld [#20060](https://github.com/docker/docker/pull/20060)
* Fix issue where removing a network during shutdown left Docker inoperable [#20181](https://github.com/docker/docker/issues/20181) [#20235](https://github.com/docker/docker/issues/20235)
* Embedded DNS is now able to return compressed results [#20181](https://github.com/docker/docker/issues/20181)
* Fix port-mapping issue with `userland-proxy=false` [#20181](https://github.com/docker/docker/issues/20181)

### [Logging](#logging-5)

* Fix bug where tcp+tls protocol would be rejected [#20109](https://github.com/docker/docker/pull/20109)

### [Volumes](#volumes-2)

* Fix issue whereby older volume drivers would not receive volume options [#19983](https://github.com/docker/docker/pull/19983)

### [Misc](#misc-1)

* Remove TasksMax from Docker systemd service [#20167](https://github.com/docker/docker/pull/20167)

## [1.10.0 (2016-02-04)](#1100-2016-02-04)

> Important
>
> Docker 1.10 uses a new content-addressable storage for images and layers.

A migration is performed the first time `docker` is run, and can take a significant amount of time depending on the number of images present. Refer to this page on the wiki for more information: <https://github.com/docker/docker/wiki/Engine-v1.10.0-content-addressability-migration> We also released a cool migration utility that enables you to perform the migration before updating to reduce downtime. Engine 1.10 migrator can be found on Docker Hub: <https://hub.docker.com/r/docker/v1.10-migrator/>

### [Runtime](#runtime-15)

* New `docker update` command that allows updating resource constraints on running containers [#15078](https://github.com/docker/docker/pull/15078)
* Add `--tmpfs` flag to `docker run` to create a tmpfs mount in a container [#13587](https://github.com/docker/docker/pull/13587)
* Add `--format` flag to `docker images` command [#17692](https://github.com/docker/docker/pull/17692)
* Allow to set daemon configuration in a file and hot-reload it with the `SIGHUP` signal [#18587](https://github.com/docker/docker/pull/18587)
* Updated docker events to include more meta-data and event types [#18888](https://github.com/docker/docker/pull/18888) This change is backward compatible in the API, but not on the CLI.
* Add `--blkio-weight-device` flag to `docker run` [#13959](https://github.com/docker/docker/pull/13959)
* Add `--device-read-bps` and `--device-write-bps` flags to `docker run` [#14466](https://github.com/docker/docker/pull/14466)
* Add `--device-read-iops` and `--device-write-iops` flags to `docker run` [#15879](https://github.com/docker/docker/pull/15879)
* Add `--oom-score-adj` flag to `docker run` [#16277](https://github.com/docker/docker/pull/16277)
* Add `--detach-keys` flag to `attach`, `run`, `start` and `exec` commands to override the default key sequence that detaches from a container [#15666](https://github.com/docker/docker/pull/15666)
* Add `--shm-size` flag to `run`, `create` and `build` to set the size of `/dev/shm` [#16168](https://github.com/docker/docker/pull/16168)
* Show the number of running, stopped, and paused containers in `docker info` [#19249](https://github.com/docker/docker/pull/19249)
* Show the `OSType` and `Architecture` in `docker info` [#17478](https://github.com/docker/docker/pull/17478)
* Add `--cgroup-parent` flag on `daemon` to set cgroup parent for all containers [#19062](https://github.com/docker/docker/pull/19062)
* Add `-L` flag to docker cp to follow symlinks [#16613](https://github.com/docker/docker/pull/16613)
* New `status=dead` filter for `docker ps` [#17908](https://github.com/docker/docker/pull/17908)

- Change `docker run` exit codes to distinguish between runtime and application errors [#14012](https://github.com/docker/docker/pull/14012)
- Enhance `docker events --since` and `--until` to support nanoseconds and timezones [#17495](https://github.com/docker/docker/pull/17495)
- Add `--all`/`-a` flag to `stats` to include both running and stopped containers [#16742](https://github.com/docker/docker/pull/16742)
- Change the default cgroup-driver to `cgroupfs` [#17704](https://github.com/docker/docker/pull/17704)
- Emit a "tag" event when tagging an image with `build -t` [#17115](https://github.com/docker/docker/pull/17115)
- Best effort for linked containers' start order when starting the daemon [#18208](https://github.com/docker/docker/pull/18208)
- Add ability to add multiple tags on `build` [#15780](https://github.com/docker/docker/pull/15780)
- Permit `OPTIONS` request against any url, thus fixing issue with CORS [#19569](https://github.com/docker/docker/pull/19569)

* Fix the `--quiet` flag on `docker build` to actually be quiet [#17428](https://github.com/docker/docker/pull/17428)
* Fix `docker images --filter dangling=false` to now show all non-dangling images [#19326](https://github.com/docker/docker/pull/19326)
* Fix race condition causing autorestart turning off on restart [#17629](https://github.com/docker/docker/pull/17629)
* Recognize GPFS filesystems [#19216](https://github.com/docker/docker/pull/19216)
* Fix obscure bug preventing to start containers [#19751](https://github.com/docker/docker/pull/19751)
* Forbid `exec` during container restart [#19722](https://github.com/docker/docker/pull/19722)
* devicemapper: Increasing `--storage-opt dm.basesize` will now increase the base device size on daemon restart [#19123](https://github.com/docker/docker/pull/19123)

### [Security](#security-6)

* Add `--userns-remap` flag to `daemon` to support user namespaces (previously in experimental) [#19187](https://github.com/docker/docker/pull/19187)
* Add support for custom seccomp profiles in `--security-opt` [#17989](https://github.com/docker/docker/pull/17989)
* Add default seccomp profile [#18780](https://github.com/docker/docker/pull/18780)
* Add `--authorization-plugin` flag to `daemon` to customize ACLs [#15365](https://github.com/docker/docker/pull/15365)
* Docker Content Trust now supports the ability to read and write user delegations [#18887](https://github.com/docker/docker/pull/18887) This is an optional, opt-in feature that requires the explicit use of the Notary command-line utility in order to be enabled. Enabling delegation support in a specific repository will break the ability of Docker 1.9 and 1.8 to pull from that repository, if content trust is enabled.

- Allow SELinux to run in a container when using the BTRFS storage driver [#16452](https://github.com/docker/docker/pull/16452)

### [Distribution](#distribution-7)

* Use content-addressable storage for images and layers [#17924](https://github.com/docker/docker/pull/17924) A migration is performed the first time docker is run; it can take a significant amount of time depending on the number of images and containers present. Images no longer depend on the parent chain but contain a list of layer references. `docker load`/`docker save` tarballs now also contain content-addressable image configurations. For more information: <https://github.com/docker/docker/wiki/Engine-v1.10.0-content-addressability-migration>
* Add support for the new [manifest format ("schema2")](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md) [#18785](https://github.com/docker/docker/pull/18785)
* Lots of improvements for push and pull: performance++, retries on failed downloads, cancelling on client disconnect [#18353](https://github.com/docker/docker/pull/18353), [#18418](https://github.com/docker/docker/pull/18418), [#19109](https://github.com/docker/docker/pull/19109), [#18353](https://github.com/docker/docker/pull/18353)
* Limit v1 protocol fallbacks [#18590](https://github.com/docker/docker/pull/18590)

- Fix issue where docker could hang indefinitely waiting for a nonexistent process to pull an image [#19743](https://github.com/docker/docker/pull/19743)

### [Networking](#networking-12)

* Use DNS-based discovery instead of `/etc/hosts` [#19198](https://github.com/docker/docker/pull/19198)
* Support for network-scoped alias using `--net-alias` on `run` and `--alias` on `network connect` [#19242](https://github.com/docker/docker/pull/19242)
* Add `--ip` and `--ip6` on `run` and `network connect` to support custom IP addresses for a container in a network [#19001](https://github.com/docker/docker/pull/19001)
* Add `--ipam-opt` to `network create` for passing custom IPAM options [#17316](https://github.com/docker/docker/pull/17316)
* Add `--internal` flag to `network create` to restrict external access to and from the network [#19276](https://github.com/docker/docker/pull/19276)
* Add `kv.path` option to `--cluster-store-opt` [#19167](https://github.com/docker/docker/pull/19167)
* Add `discovery.heartbeat` and `discovery.ttl` options to `--cluster-store-opt` to configure discovery TTL and heartbeat timer [#18204](https://github.com/docker/docker/pull/18204)
* Add `--format` flag to `network inspect` [#17481](https://github.com/docker/docker/pull/17481)
* Add `--link` to `network connect` to provide a container-local alias [#19229](https://github.com/docker/docker/pull/19229)
* Support for Capability exchange with remote IPAM plugins [#18775](https://github.com/docker/docker/pull/18775)
* Add `--force` to `network disconnect` to force container to be disconnected from network [#19317](https://github.com/docker/docker/pull/19317)

- Support for multi-host networking using built-in overlay driver for all engine supported kernels: 3.10+ [#18775](https://github.com/docker/docker/pull/18775)
- `--link` is now supported on `docker run` for containers in user-defined network [#19229](https://github.com/docker/docker/pull/19229)
- Enhance `docker network rm` to allow removing multiple networks [#17489](https://github.com/docker/docker/pull/17489)
- Include container names in `network inspect` [#17615](https://github.com/docker/docker/pull/17615)
- Include auto-generated subnets for user-defined networks in `network inspect` [#17316](https://github.com/docker/docker/pull/17316)
- Add `--filter` flag to `network ls` to hide predefined networks [#17782](https://github.com/docker/docker/pull/17782)
- Add support for network connect/disconnect to stopped containers [#18906](https://github.com/docker/docker/pull/18906)
- Add network ID to container inspect [#19323](https://github.com/docker/docker/pull/19323)

* Fix MTU issue where Docker would not start with two or more default routes [#18108](https://github.com/docker/docker/pull/18108)
* Fix duplicate IP address for containers [#18106](https://github.com/docker/docker/pull/18106)
* Fix issue preventing sometimes docker from creating the bridge network [#19338](https://github.com/docker/docker/pull/19338)
* Do not substitute 127.0.0.1 name server when using `--net=host` [#19573](https://github.com/docker/docker/pull/19573)

### [Logging](#logging-6)

* New logging driver for Splunk [#16488](https://github.com/docker/docker/pull/16488)
* Add support for syslog over TCP+TLS [#18998](https://github.com/docker/docker/pull/18998)

- Enhance `docker logs --since` and `--until` to support nanoseconds and time [#17495](https://github.com/docker/docker/pull/17495)
- Enhance AWS logs to auto-detect region [#16640](https://github.com/docker/docker/pull/16640)

### [Volumes](#volumes-3)

* Add support to set the mount propagation mode for a volume [#17034](https://github.com/docker/docker/pull/17034)

- Add `ls` and `inspect` endpoints to volume plugin API [#16534](https://github.com/docker/docker/pull/16534) Existing plugins need to make use of these new APIs to satisfy users' expectation For that, use the new MIME type `application/vnd.docker.plugins.v1.2+json` [#19549](https://github.com/docker/docker/pull/19549)

* Fix data not being copied to named volumes [#19175](https://github.com/docker/docker/pull/19175)
* Fix issues preventing volume drivers from being containerized [#19500](https://github.com/docker/docker/pull/19500)
* Fix `docker volumes ls --dangling=false` to now show all non-dangling volumes [#19671](https://github.com/docker/docker/pull/19671)
* Do not remove named volumes on container removal [#19568](https://github.com/docker/docker/pull/19568)
* Allow external volume drivers to host anonymous volumes [#19190](https://github.com/docker/docker/pull/19190)

### [Builder](#builder-4)

* Add support for `**` in `.dockerignore` to wildcard multiple levels of directories [#17090](https://github.com/docker/docker/pull/17090)

- Fix handling of UTF-8 characters in Dockerfiles [#17055](https://github.com/docker/docker/pull/17055)
- Fix permissions problem when reading from STDIN [#19283](https://github.com/docker/docker/pull/19283)

### [Client](#client-2)

* Add support for overriding the API version to use via an `DOCKER_API_VERSION` environment-variable [#15964](https://github.com/docker/docker/pull/15964)

- Fix a bug preventing Windows clients to log in to Docker Hub [#19891](https://github.com/docker/docker/pull/19891)

### [Misc](#misc-2)

* systemd: Set TasksMax in addition to LimitNPROC in systemd service file [#19391](https://github.com/docker/docker/pull/19391)

### [Deprecations](#deprecations)

* Remove LXC support. The LXC driver was deprecated in Docker 1.8, and has now been removed [#17700](https://github.com/docker/docker/pull/17700)
* Remove `--exec-driver` daemon flag, because it is no longer in use [#17700](https://github.com/docker/docker/pull/17700)
* Remove old deprecated single-dashed long CLI flags (such as `-rm`; use `--rm` instead) [#17724](https://github.com/docker/docker/pull/17724)
* Deprecate HostConfig at API container start [#17799](https://github.com/docker/docker/pull/17799)
* Deprecate docker packages for newly EOL'd Linux distributions: Fedora 21 and Ubuntu 15.04 (Vivid) [#18794](https://github.com/docker/docker/pull/18794), [#18809](https://github.com/docker/docker/pull/18809)
* Deprecate `-f` flag for docker tag [#18350](https://github.com/docker/docker/pull/18350)

## [1.9.1 (2015-11-21)](#191-2015-11-21)

### [Runtime](#runtime-16)

* Do not prevent daemon from booting if images could not be restored (#17695)
* Force IPC mount to unmount on daemon shutdown/init (#17539)
* Turn IPC unmount errors into warnings (#17554)
* Fix `docker stats` performance regression (#17638)
* Clarify cryptic error message upon `docker logs` if `--log-driver=none` (#17767)
* Fix seldom panics (#17639, #17634, #17703)
* Fix opq whiteouts problems for files with dot prefix (#17819)
* devicemapper: try defaulting to xfs instead of ext4 for performance reasons (#17903, #17918)
* devicemapper: fix displayed fs in docker info (#17974)
* selinux: only relabel if user requested so with the `z` option (#17450, #17834)
* Do not make network calls when normalizing names (#18014)

### [Client](#client-3)

* Fix `docker login` on windows (#17738)
* Fix bug with `docker inspect` output when not connected to daemon (#17715)
* Fix `docker inspect -f {{.HostConfig.Dns}} somecontainer` (#17680)

### [Builder](#builder-5)

* Fix regression with symlink behavior in ADD/COPY (#17710)

### [Networking](#networking-13)

* Allow passing a network ID as an argument for `--net` (#17558)
* Fix connect to host and prevent disconnect from host for `host` network (#17476)
* Fix `--fixed-cidr` issue when gateway ip falls in ip-range and ip-range is not the first block in the network (#17853)
* Restore deterministic `IPv6` generation from `MAC` address on default `bridge` network (#17890)
* Allow port-mapping only for endpoints created on docker run (#17858)
* Fixed an endpoint delete issue with a possible stale sbox (#18102)

### [Distribution](#distribution-8)

* Correct parent chain in v2 push when v1Compatibility files on the disk are inconsistent (#18047)

## [1.9.0 (2015-11-03)](#190-2015-11-03)

### [Runtime](#runtime-17)

* `docker stats` now returns block IO metrics (#15005)
* `docker stats` now details network stats per interface (#15786)
* Add `ancestor=<image>` filter to `docker ps --filter` flag to filter containers based on their ancestor images (#14570)
* Add `label=<somelabel>` filter to `docker ps --filter` to filter containers based on label (#16530)
* Add `--kernel-memory` flag to `docker run` (#14006)
* Add `--message` flag to `docker import` allowing to specify an optional message (#15711)
* Add `--privileged` flag to `docker exec` (#14113)
* Add `--stop-signal` flag to `docker run` allowing to replace the container process stopping signal (#15307)
* Add a new `unless-stopped` restart policy (#15348)
* Inspecting an image now returns tags (#13185)
* Add container size information to `docker inspect` (#15796)
* Add `RepoTags` and `RepoDigests` field to `/images/{name:.*}/json` (#17275)

- Remove the deprecated `/container/ps` endpoint from the API (#15972)
- Send and document correct HTTP codes for `/exec/<name>/start` (#16250)
- Share shm and mqueue between containers sharing IPC namespace (#15862)
- Event stream now shows OOM status when `--oom-kill-disable` is set (#16235)
- Ensure special network files (/etc/hosts etc.) are read-only if bind-mounted with `ro` option (#14965)
- Improve `rmi` performance (#16890)
- Do not update /etc/hosts for the default bridge network, except for links (#17325)
- Fix conflict with duplicate container names (#17389)
- Fix an issue with incorrect template execution in `docker inspect` (#17284)
- DEPRECATE `-c` short flag variant for `--cpu-shares` in docker run (#16271)

### [Client](#client-4)

* Allow `docker import` to import from local files (#11907)

### [Builder](#builder-6)

* Add a `STOPSIGNAL` Dockerfile instruction allowing to set a different stop-signal for the container process (#15307)
* Add an `ARG` Dockerfile instruction and a `--build-arg` flag to `docker build` that allows to add build-time environment variables (#15182)

- Improve cache miss performance (#16890)

### [Storage](#storage)

* devicemapper: Implement deferred deletion capability (#16381)

### [Networking](#networking-14)

* `docker network` exits experimental and is part of standard release (#16645)
* New network top-level concept, with associated subcommands and API (#16645) WARNING: the API is different from the experimental API
* Support for multiple isolated/micro-segmented networks (#16645)
* Built-in multihost networking using VXLAN based overlay driver (#14071)
* Support for third-party network plugins (#13424)
* Ability to dynamically connect containers to multiple networks (#16645)
* Support for user-defined IP address management via pluggable IPAM drivers (#16910)
* Add daemon flags `--cluster-store` and `--cluster-advertise` for built-in nodes discovery (#16229)
* Add `--cluster-store-opt` for setting up TLS settings (#16644)
* Add `--dns-opt` to the daemon (#16031)

- DEPRECATE following container `NetworkSettings` fields in API v1.21: `EndpointID`, `Gateway`, `GlobalIPv6Address`, `GlobalIPv6PrefixLen`, `IPAddress`, `IPPrefixLen`, `IPv6Gateway` and `MacAddress`. Those are now specific to the `bridge` network. Use `NetworkSettings.Networks` to inspect the networking settings of a container per network.

### [Volumes](#volumes-4)

* New top-level `volume` subcommand and API (#14242)

- Move API volume driver settings to host-specific config (#15798)
- Print an error message if volume name is not unique (#16009)
- Ensure volumes created from Dockerfiles always use the local volume driver (#15507)
- DEPRECATE auto-creating missing host paths for bind mounts (#16349)

### [Logging](#logging-7)

* Add `awslogs` logging driver for Amazon CloudWatch (#15495)
* Add generic `tag` log option to allow customizing container/image information passed to driver (#15384)

- Implement the `docker logs` endpoint for the journald driver (#13707)
- DEPRECATE driver-specific log tags (#15384)

### [Distribution](#distribution-9)

* `docker search` now works with partial names (#16509)

- Push optimization: avoid buffering to file (#15493)
- The daemon will display progress for images that were already being pulled by another client (#15489)
- Only permissions required for the current action being performed are requested (#)

* Renaming trust keys (and respective environment variables) from `offline` to `root` and `tagging` to `repository` (#16894)

- DEPRECATE trust key environment variables `DOCKER_CONTENT_TRUST_OFFLINE_PASSPHRASE` and `DOCKER_CONTENT_TRUST_TAGGING_PASSPHRASE` (#16894)

### [Security](#security-7)

* Add SELinux profiles to the rpm package (#15832)

- Fix various issues with AppArmor profiles provided in the deb package (#14609)
- Add AppArmor policy that prevents writing to /proc (#15571)

## [1.8.3 (2015-10-12)](#183-2015-10-12)

### [Distribution](#distribution-10)

* Fix layer IDs lead to local graph poisoning (CVE-2014-8178)
* Fix manifest validation and parsing logic errors allow pull-by-digest validation bypass (CVE-2014-8179)

- Add `--disable-legacy-registry` to prevent a daemon from using a v1 registry

## [1.8.2 (2015-09-10)](#182-2015-09-10)

### [Distribution](#distribution-11)

* Fixes rare edge case of handling GNU LongLink and LongName entries.
* Fix ^C on docker pull.
* Fix docker pull issues on client disconnection.
* Fix issue that caused the daemon to panic when loggers weren't configured properly.
* Fix goroutine leak pulling images from registry V2.

### [Runtime](#runtime-18)

* Fix a bug mounting cgroups for docker daemons running inside docker containers.
* Initialize log configuration properly.

### [Client:](#client-5)

* Handle `-q` flag in `docker ps` properly when there is a default format.

### [Networking](#networking-15)

* Fix several corner cases with netlink.

### [Contrib](#contrib-8)

* Fix several issues with bash completion.

## [1.8.1 (2015-08-12)](#181-2015-08-12)

### [Distribution](#distribution-12)

* Fix a bug where pushing multiple tags would result in invalid images

## [1.8.0 (2015-08-11)](#180-2015-08-11)

### [Distribution](#distribution-13)

* Trusted pull, push and build, disabled by default

- Make tar layers deterministic between registries
- Don't allow deleting the image of running containers
- Check if a tag name to load is a valid digest
- Allow one character repository names
- Add a more accurate error description for invalid tag name
- Make build cache ignore mtime

### [Cli](#cli)

* Add support for DOCKER\_CONFIG/--config to specify config file dir
* Add --type flag for docker inspect command
* Add formatting options to `docker ps` with `--format`
* Replace `docker -d` with new subcommand `docker daemon`

- Zsh completion updates and improvements
- Add some missing events to bash completion
- Support daemon urls with base paths in `docker -H`
- Validate status= filter to docker ps
- Display when a container is in --net=host in docker ps
- Extend docker inspect to export image metadata related to graph driver
- Restore --default-gateway{,-v6} daemon options
- Add missing unpublished ports in docker ps
- Allow duration strings in `docker events` as --since/--until
- Expose more mounts information in `docker inspect`

### [Runtime](#runtime-19)

* Add new Fluentd logging driver
* Allow `docker import` to load from local files
* Add logging driver for GELF via UDP
* Allow to copy files from host to containers with `docker cp`
* Promote volume drivers from experimental to master
* Add rollover options to json-file log driver, and --log-driver-opts flag
* Add memory swappiness tuning options

- Remove cgroup read-only flag when privileged
- Make /proc, /sys, & /dev readonly for readonly containers
- Add cgroup bind mount by default
- Overlay: Export metadata for container and image in `docker inspect`
- Devicemapper: external device activation
- Devicemapper: Compare uuid of base device on startup
- Remove RC4 from the list of registry cipher suites
- Add syslog-facility option
- LXC execdriver compatibility with recent LXC versions
- Mark LXC execriver as deprecated (to be removed with the migration to runc)

### [Plugins](#plugins-3)

* Separate plugin sockets and specs locations
* Allow TLS connections to plugins

### [Bug fixes](#bug-fixes)

* Add missing 'Names' field to /containers/json API output
* Make `docker rmi` of dangling images safe while pulling
* Devicemapper: Change default basesize to 100G
* Go Scheduler issue with sync.Mutex and gcc
* Fix issue where Search API endpoint would panic due to empty AuthConfig
* Set image canonical names correctly
* Check dockerinit only if lxc driver is used
* Fix ulimit usage of nproc
* Always attach STDIN if -i,--interactive is specified
* Show error messages when saving container state fails
* Fixed incorrect assumption on --bridge=none treated as disable network
* Check for invalid port specifications in host configuration
* Fix endpoint leave failure for --net=host mode
* Fix goroutine leak in the stats API if the container is not running
* Check for apparmor file before reading it
* Fix DOCKER\_TLS\_VERIFY being ignored
* Set umask to the default on startup
* Correct the message of pause and unpause a non-running container
* Adjust disallowed CpuShares in container creation
* ZFS: correctly apply selinux context
* Display empty string instead of when IP opt is nil
* `docker kill` returns error when container is not running
* Fix COPY/ADD quoted/json form
* Fix goroutine leak on logs -f with no output
* Remove panic in nat package on invalid hostport
* Fix container linking in Fedora 22
* Fix error caused using default gateways outside of the allocated range
* Format times in inspect command with a template as RFC3339Nano
* Make registry client to accept 2xx and 3xx http status responses as successful
* Fix race issue that caused the daemon to crash with certain layer downloads failed in a specific order.
* Fix error when the docker ps format was not valid.
* Remove redundant ip forward check.
* Fix issue trying to push images to repository mirrors.
* Fix error cleaning up network entrypoints when there is an initialization issue.

## [1.7.1 (2015-07-14)](#171-2015-07-14)

### [Runtime](#runtime-20)

* Fix default user spawning exec process with `docker exec`
* Make `--bridge=none` not to configure the network bridge
* Publish networking stats properly
* Fix implicit devicemapper selection with static binaries
* Fix socket connections that hung intermittently
* Fix bridge interface creation on CentOS/RHEL 6.6
* Fix local dns lookups added to resolv.conf
* Fix copy command mounting volumes
* Fix read/write privileges in volumes mounted with --volumes-from

### [Remote API](#remote-api)

* Fix unmarshalling of Command and Entrypoint
* Set limit for minimum client version supported
* Validate port specification
* Return proper errors when attach/reattach fail

### [Distribution](#distribution-14)

* Fix pulling private images
* Fix fallback between registry V2 and V1

## [1.7.0 (2015-06-16)](#170-2015-06-16)

### [Runtime](#runtime-21)

* Experimental feature: support for out-of-process volume plugins

- The userland proxy can be disabled in favor of hairpin NAT using the daemon’s `--userland-proxy=false` flag
- The `exec` command supports the `-u|--user` flag to specify the new process owner

* Default gateway for containers can be specified daemon-wide using the `--default-gateway` and `--default-gateway-v6` flags
* The CPU CFS (Completely Fair Scheduler) quota can be set in `docker run` using `--cpu-quota`
* Container block IO can be controlled in `docker run` using`--blkio-weight`
* ZFS support
* The `docker logs` command supports a `--since` argument
* UTS namespace can be shared with the host with `docker run --uts=host`

### [Quality](#quality)

* Networking stack was entirely rewritten as part of the libnetwork effort
* Engine internals refactoring
* Volumes code was entirely rewritten to support the plugins effort

- Sending SIGUSR1 to a daemon will dump all goroutines stacks without exiting

### [Build](#build)

* Support ${variable:-value} and ${variable:+value} syntax for environment variables
* Support resource management flags `--cgroup-parent`, `--cpu-period`, `--cpu-quota`, `--cpuset-cpus`, `--cpuset-mems`
* git context changes with branches and directories

- The .dockerignore file support exclusion rules

### [Distribution](#distribution-15)

* Client support for v2 mirroring support for the official registry

### [Bugfixes](#bugfixes)

* Firewalld is now supported and will automatically be used when available
* mounting --device recursively

## [1.6.2 (2015-05-13)](#162-2015-05-13)

### [Runtime](#runtime-22)

* Revert change prohibiting mounting into /sys

## [1.6.1 (2015-05-07)](#161-2015-05-07)

### [Security](#security-8)

* Fix read/write /proc paths (CVE-2015-3630)
* Prohibit VOLUME /proc and VOLUME / (CVE-2015-3631)
* Fix opening of file-descriptor 1 (CVE-2015-3627)
* Fix symlink traversal on container respawn allowing local privilege escalation (CVE-2015-3629)
* Prohibit mount of /sys

### [Runtime](#runtime-23)

* Update AppArmor policy to not allow mounts

## [1.6.0 (2015-04-07)](#160-2015-04-07)

### [Builder](#builder-7)

* Building images from an image ID
* Build containers with resource constraints, ie `docker build --cpu-shares=100 --memory=1024m...`
* `commit --change` to apply specified Dockerfile instructions while committing the image
* `import --change` to apply specified Dockerfile instructions while importing the image
* Builds no longer continue in the background when canceled with CTRL-C

### [Client](#client-6)

* Windows Support

### [Runtime](#runtime-24)

* Container and image Labels
* `--cgroup-parent` for specifying a parent cgroup to place container cgroup within
* Logging drivers, `json-file`, `syslog`, or `none`
* Pulling images by ID
* `--ulimit` to set the ulimit on a container
* `--default-ulimit` option on the daemon which applies to all created containers (and overwritten by `--ulimit` on run)

## [1.5.0 (2015-02-10)](#150-2015-02-10)

### [Builder](#builder-8)

* Dockerfile to use for a given `docker build` can be specified with the `-f` flag

- Dockerfile and .dockerignore files can be themselves excluded as part of the .dockerignore file, thus preventing modifications to these files invalidating ADD or COPY instructions cache
- ADD and COPY instructions accept relative paths
- Dockerfile `FROM scratch` instruction is now interpreted as a no-base specifier
- Improve performance when exposing a large number of ports

### [Hack](#hack)

* Allow client-side only integration tests for Windows

- Include docker-py integration tests against Docker daemon as part of our test suites

### [Packaging](#packaging)

* Support for the new version of the registry HTTP API

- Speed up `docker push` for images with a majority of already existing layers

* Fixed contacting a private registry through a proxy

### [Remote API](#remote-api-1)

* A new endpoint will stream live container resource metrics and can be accessed with the `docker stats` command
* Containers can be renamed using the new `rename` endpoint and the associated `docker rename` command

- Container `inspect` endpoint show the ID of `exec` commands running in this container
- Container `inspect` endpoint show the number of times Docker auto-restarted the container
- New types of event can be streamed by the `events` endpoint: ‘OOM’ (container died with out of memory), ‘exec\_create’, and ‘exec\_start'

* Fixed returned string fields which hold numeric characters incorrectly omitting surrounding double quotes

### [Runtime](#runtime-25)

* Docker daemon has full IPv6 support
* The `docker run` command can take the `--pid=host` flag to use the host PID namespace, which makes it possible for example to debug host processes using containerized debugging tools
* The `docker run` command can take the `--read-only` flag to make the container’s root filesystem mounted as readonly, which can be used in combination with volumes to force a container’s processes to only write to locations that will be persisted
* Container total memory usage can be limited for `docker run` using the `--memory-swap` flag

- Major stability improvements for devicemapper storage driver
- Better integration with host system: containers will reflect changes to the host's `/etc/resolv.conf` file when restarted
- Better integration with host system: per-container iptable rules are moved to the DOCKER chain

* Fixed container exiting on out of memory to return an invalid exit code

### [Other](#other)

* The HTTP\_PROXY, HTTPS\_PROXY, and NO\_PROXY environment variables are properly taken into account by the client when connecting to the Docker daemon

## [1.4.1 (2014-12-15)](#141-2014-12-15)

### [Runtime](#runtime-26)

* Fix issue with volumes-from and bind mounts not being honored after create

## [1.4.0 (2014-12-11)](#140-2014-12-11)

### [Notable Features since 1.3.0](#notable-features-since-130)

* Set key=value labels to the daemon (displayed in `docker info`), applied with new `-label` daemon flag
* Add support for `ENV` in Dockerfile of the form: `ENV name=value name2=value2...`
* New Overlayfs Storage Driver
* `docker info` now returns an `ID` and `Name` field
* Filter events by event name, container, or image
* `docker cp` now supports copying from container volumes

- Fixed `docker tag`, so it honors `--force` when overriding a tag for existing image.

## [1.3.3 (2014-12-11)](#133-2014-12-11)

### [Security](#security-9)

* Fix path traversal vulnerability in processing of absolute symbolic links (CVE-2014-9356)
* Fix decompression of xz image archives, preventing privilege escalation (CVE-2014-9357)
* Validate image IDs (CVE-2014-9358)

### [Runtime](#runtime-27)

* Fix an issue when image archives are being read slowly

### [Client](#client-7)

* Fix a regression related to stdin redirection
* Fix a regression with `docker cp` when destination is the current directory

## [1.3.2 (2014-11-20)](#132-2014-11-20)

### [Security](#security-10)

* Fix tar breakout vulnerability

- Extractions are now sandboxed chroot

* Security options are no longer committed to images

### [Runtime](#runtime-28)

* Fix deadlock in `docker ps -f exited=1`
* Fix a bug when `--volumes-from` references a container that failed to start

### [Registry](#registry)

* `--insecure-registry` now accepts CIDR notation such as 10.1.0.0/16

- Private registries whose IPs fall in the 127.0.0.0/8 range do no need the `--insecure-registry` flag

* Skip the experimental registry v2 API when mirroring is enabled

## [1.3.1 (2014-10-28)](#131-2014-10-28)

### [Security](#security-11)

* Prevent fallback to SSL protocols < TLS 1.0 for client, daemon and registry

- Secure HTTPS connection to registries with certificate verification and without HTTP fallback unless `--insecure-registry` is specified

### [Runtime](#runtime-29)

* Fix issue where volumes would not be shared

### [Client](#client-8)

* Fix issue with `--iptables=false` not automatically setting `--ip-masq=false`
* Fix docker run output to non-TTY stdout

### [Builder](#builder-9)

* Fix escaping `$` for environment variables
* Fix issue with lowercase `onbuild` Dockerfile instruction
* Restrict environment variable expansion to `ENV`, `ADD`, `COPY`, `WORKDIR`, `EXPOSE`, `VOLUME` and `USER`

## [1.3.0 (2014-10-14)](#130-2014-10-14)

### [Notable features since 1.2.0](#notable-features-since-120)

* Docker `exec` allows you to run additional processes inside existing containers
* Docker `create` gives you the ability to create a container via the CLI without executing a process
* `--security-opts` options to allow user to customize container labels and apparmor profiles
* Docker `ps` filters

- Wildcard support to COPY/ADD

* Move production URLs to get.docker.com from get.docker.io
* Allocate IP address on the bridge inside a valid CIDR
* Use drone.io for PR and CI testing
* Ability to setup an official registry mirror
* Ability to save multiple images with docker `save`

## [1.2.0 (2014-08-20)](#120-2014-08-20)

### [Runtime](#runtime-30)

* Make /etc/hosts /etc/resolv.conf and /etc/hostname editable at runtime
* Auto-restart containers using policies
* Use /var/lib/docker/tmp for large temporary files
* `--cap-add` and `--cap-drop` to tweak what linux capability you want
* `--device` to use devices in containers

### [Client](#client-9)

* `docker search` on private registries
* Add `exited` filter to `docker ps --filter`

- `docker rm -f` now kills instead of stop

* Support for IPv6 addresses in `--dns` flag

### [Proxy](#proxy)

* Proxy instances in separate processes

- Small bug fix on UDP proxy

## [1.1.2 (2014-07-23)](#112-2014-07-23)

### [Runtime](#runtime-31)

* Fix port allocation for existing containers
* Fix containers restart on daemon restart

### [Packaging](#packaging-1)

* Fix /etc/init.d/docker issue on Debian

## [1.1.1 (2014-07-09)](#111-2014-07-09)

### [Builder](#builder-10)

* Fix issue with ADD

## [1.1.0 (2014-07-03)](#110-2014-07-03)

### [Notable features since 1.0.1](#notable-features-since-101)

* Add `.dockerignore` support
* Pause containers during `docker commit`
* Add `--tail` to `docker logs`

### [Builder](#builder-11)

* Allow a tar file as context for `docker build`

- Fix issue with white-spaces and multi-lines in `Dockerfiles`

### [Runtime](#runtime-32)

* Overall performance improvements
* Allow `/` as source of `docker run -v`
* Fix port allocation
* Fix bug in `docker save`
* Add links information to `docker inspect`

### [Client](#client-10)

* Improve command line parsing for `docker commit`

### [Remote API](#remote-api-2)

* Improve status code for the `start` and `stop` endpoints

## [1.0.1 (2014-06-19)](#101-2014-06-19)

### [Notable features since 1.0.0](#notable-features-since-100)

* Enhance security for the LXC driver

### [Builder](#builder-12)

* Fix `ONBUILD` instruction passed to grandchildren

### [Runtime](#runtime-33)

* Fix events subscription
* Fix /etc/hostname file with host networking
* Allow `-h` and `--net=none`
* Fix issue with hotplug devices in `--privileged`

### [Client](#client-11)

* Fix artifacts with events
* Fix a panic with empty flags
* Fix `docker cp` on Mac OS X

### [Miscellaneous](#miscellaneous)

* Fix compilation on Mac OS X
* Fix several races

## [1.0.0 (2014-06-09)](#100-2014-06-09)

### [Notable features since 0.12.0](#notable-features-since-0120)

* Production support

## [0.12.0 (2014-06-05)](#0120-2014-06-05)

### [Notable features since 0.11.0](#notable-features-since-0110)

* 40+ various improvements to stability, performance and usability
* New `COPY` Dockerfile instruction to allow copying a local file from the context into the container without ever extracting if the file is a tar file
* Inherit file permissions from the host on `ADD`
* New `pause` and `unpause` commands to allow pausing and unpausing of containers using cgroup freezer
* The `images` command has a `-f`/`--filter` option to filter the list of images
* Add `--force-rm` to clean up after a failed build
* Standardize JSON keys in Remote API to CamelCase
* Pull from a docker run now assumes `latest` tag if not specified
* Enhance security on Linux capabilities and device nodes

## [0.11.1 (2014-05-07)](#0111-2014-05-07)

### [Registry](#registry-1)

* Fix push and pull to private registry

## [0.11.0 (2014-05-07)](#0110-2014-05-07)

### [Notable features since 0.10.0](#notable-features-since-0100)

* SELinux support for mount and process labels
* Linked containers can be accessed by hostname
* Use the net `--net` flag to allow advanced network configuration such as host networking so that containers can use the host's network interfaces
* Add a ping endpoint to the Remote API to do healthchecks of your docker daemon
* Logs can now be returned with an optional timestamp
* Docker now works with registries that support SHA-512
* Multiple registry endpoints are supported to allow registry mirrors

## [0.10.0 (2014-04-08)](#0100-2014-04-08)

### [Builder](#builder-13)

* Fix printing multiple messages on a single line. Fixes broken output during builds.
* Follow symlinks inside container's root for ADD build instructions.
* Fix EXPOSE caching.

### [Documentation](#documentation-1)

* Add the new options of `docker ps` to the documentation.
* Add the options of `docker restart` to the documentation.
* Update daemon docs and help messages for --iptables and --ip-forward.
* Updated apt-cacher-ng docs example.
* Remove duplicate description of --mtu from docs.
* Add missing -t and -v for `docker images` to the docs.
* Add fixes to the cli docs.
* Update libcontainer docs.
* Update images in docs to remove references to AUFS and LXC.
* Update the nodejs\_web\_app in the docs to use the new epel RPM address.
* Fix external link on security of containers.
* Update remote API docs.
* Add image size to history docs.
* Be explicit about binding to all interfaces in redis example.
* Document DisableNetwork flag in the 1.10 remote api.
* Document that `--lxc-conf` is lxc only.
* Add chef usage documentation.
* Add example for an image with multiple for `docker load`.
* Explain what `docker run -a` does in the docs.

### [Contrib](#contrib-9)

* Add variable for DOCKER\_LOGFILE to sysvinit and use append instead of overwrite in opening the logfile.
* Fix init script cgroup mounting workarounds to be more similar to cgroupfs-mount and thus work properly.
* Remove inotifywait hack from the upstart host-integration example because it's not necessary any more.
* Add check-config script to contrib.
* Fix fish shell completion.

### [Hack](#hack-1)

* Clean up "go test" output from "make test" to be much more readable/scannable.
* Exclude more "definitely not unit tested Go source code" directories from hack/make/test.

- Generate md5 and sha256 hashes when building, and upload them via hack/release.sh.

* Include contributed completions in Ubuntu PPA.

- Add cli integration tests.

* Add tweaks to the hack scripts to make them simpler.

### [Remote API](#remote-api-3)

* Add TLS auth support for API.

- Move git clone from daemon to client.

* Fix content-type detection in docker cp.

- Split API into 2 go packages.

### [Runtime](#runtime-34)

* Support hairpin NAT without going through Docker server.

- devicemapper: succeed immediately when removing non-existent devices.
- devicemapper: improve handling of devicemapper devices (add per device lock, increase sleep time and unlock while sleeping).
- devicemapper: increase timeout in waitClose to 10 seconds.
- devicemapper: ensure we shut down thin pool cleanly.
- devicemapper: pass info, rather than hash to activateDeviceIfNeeded, deactivateDevice, setInitialized, deleteDevice.
- devicemapper: avoid AB-BA deadlock.
- devicemapper: make shutdown better/faster.
- improve alpha sorting in mflag.
- Remove manual http cookie management because the cookiejar is being used.
- Use BSD raw mode on Darwin. Fixes nano, tmux and others.
- Add FreeBSD support for the client.
- Merge auth package into registry.
- Add deprecation warning for -t on `docker pull`.
- Remove goroutine leak on error.
- Update parseLxcInfo to comply with new lxc1.0 format.
- Fix attach exit on darwin.
- Improve deprecation message.
- Retry to retrieve the layer metadata up to 5 times for `docker pull`.
- Only unshare the mount namespace for execin.
- Merge existing config when committing.
- Disable daemon startup timeout.
- Fix issue #4681: add loopback interface when networking is disabled.
- Add failing test case for issue #4681.
- Send SIGTERM to child, instead of SIGKILL.
- Show the driver and the kernel version in `docker info` even when not in debug mode.
- Always symlink /dev/ptmx for libcontainer. This fixes console related problems.
- Fix issue caused by the absence of /etc/apparmor.d.
- Don't leave empty cidFile behind when failing to create the container.
- Mount cgroups automatically if they're not mounted already.
- Use mock for search tests.
- Update to double-dash everywhere.
- Move .dockerenv parsing to lxc driver.
- Move all bind-mounts in the container inside the namespace.
- Don't use separate bind mount for container.
- Always symlink /dev/ptmx for libcontainer.
- Don't kill by pid for other drivers.
- Add initial logging to libcontainer.

* Sort by port in `docker ps`.

- Move networking drivers into runtime top level package.

* Add --no-prune to `docker rmi`.
* Add time since exit in `docker ps`.

- graphdriver: add build tags.
- Prevent allocation of previously allocated ports & prevent improve port allocation.

* Add support for --since/--before in `docker ps`.

- Clean up container stop.

* Add support for configurable dns search domains.

- Add support for relative WORKDIR instructions.
- Add --output flag for docker save.
- Remove duplication of DNS entries in config merging.
- Add cpuset.cpus to cgroups and native driver options.
- Remove docker-ci.
- Promote btrfs. btrfs is no longer considered experimental.
- Add --input flag to `docker load`.
- Return error when existing bridge doesn't match IP address.
- Strip comments before parsing line continuations to avoid interpreting instructions as comments.
- Fix TestOnlyLoopbackExistsWhenUsingDisableNetworkOption to ignore "DOWN" interfaces.
- Add systemd implementation of cgroups and make containers show up as systemd units.
- Fix commit and import when no repository is specified.
- Remount /var/lib/docker as --private to fix scaling issue.
- Use the environment's proxy when pinging the remote registry.
- Reduce error level from harmless errors.

* Allow --volumes-from to be individual files.

- Fix expanding buffer in StdCopy.
- Set error regardless of attach or stdin. This fixes #3364.
- Add support for --env-file to load environment variables from files.
- Symlink /etc/mtab and /proc/mounts.
- Allow pushing a single tag.
- Shut down containers cleanly at shutdown and wait forever for the containers to shut down. This makes container shutdown on daemon shutdown work properly via SIGTERM.
- Don't throw error when starting an already running container.
- Fix dynamic port allocation limit.
- remove setupDev from libcontainer.
- Add API version to `docker version`.
- Return correct exit code when receiving signal and make SIGQUIT quit without cleanup.
- Fix --volumes-from mount failure.
- Allow non-privileged containers to create device nodes.
- Skip login tests because of external dependency on a hosted service.
- Deprecate `docker images --tree` and `docker images --viz`.
- Deprecate `docker insert`.
- Include base abstraction for apparmor. This fixes some apparmor related problems on Ubuntu 14.04.
- Add specific error message when hitting 401 over HTTP on push.
- Fix absolute volume check.
- Remove volumes-from from the config.
- Move DNS options to hostconfig.
- Update the apparmor profile for libcontainer.
- Add deprecation notice for `docker commit -run`.

## [0.9.1 (2014-03-24)](#091-2014-03-24)

### [Builder](#builder-14)

* Fix printing multiple messages on a single line. Fixes broken output during builds.

### [Documentation](#documentation-2)

* Fix external link on security of containers.

### [Contrib](#contrib-10)

* Fix init script cgroup mounting workarounds to be more similar to cgroupfs-mount and thus work properly.
* Add variable for DOCKER\_LOGFILE to sysvinit and use append instead of overwrite in opening the logfile.

### [Hack](#hack-2)

* Generate md5 and sha256 hashes when building, and upload them via hack/release.sh.

### [Remote API](#remote-api-4)

* Fix content-type detection in `docker cp`.

### [Runtime](#runtime-35)

* Use BSD raw mode on Darwin. Fixes nano, tmux and others.
* Only unshare the mount namespace for execin.
* Retry to retrieve the layer metadata up to 5 times for `docker pull`.
* Merge existing config when committing.
* Fix panic in monitor.
* Disable daemon startup timeout.
* Fix issue #4681: add loopback interface when networking is disabled.
* Add failing test case for issue #4681.
* Send SIGTERM to child, instead of SIGKILL.
* Show the driver and the kernel version in `docker info` even when not in debug mode.
* Always symlink /dev/ptmx for libcontainer. This fixes console related problems.
* Fix issue caused by the absence of /etc/apparmor.d.
* Don't leave empty cidFile behind when failing to create the container.
* Improve deprecation message.
* Fix attach exit on darwin.
* devicemapper: improve handling of devicemapper devices (add per device lock, increase sleep time, unlock while sleeping).
* devicemapper: succeed immediately when removing non-existent devices.
* devicemapper: increase timeout in waitClose to 10 seconds.
* Remove goroutine leak on error.
* Update parseLxcInfo to comply with new lxc1.0 format.

## [0.9.0 (2014-03-10)](#090-2014-03-10)

### [Builder](#builder-15)

* Avoid extra mount/unmount during build. This fixes mount/unmount related errors during build.
* Add error to docker build --rm. This adds missing error handling.
* Forbid chained onbuild, `onbuild from` and `onbuild maintainer` triggers.
* Make `--rm` the default for `docker build`.

### [Documentation](#documentation-3)

* Download the docker client binary for Mac over https.
* Update the titles of the install instructions & descriptions.

- Add instructions for upgrading boot2docker.
- Add port forwarding example in OS X install docs.

* Attempt to disentangle repository and registry.
* Update docs to explain more about `docker ps`.
* Update sshd example to use a Dockerfile.
* Rework some examples, including the Python examples.
* Update docs to include instructions for a container's lifecycle.
* Update docs documentation to discuss the docs branch.
* Don't skip cert check for an example & use HTTPS.
* Bring back the memory and swap accounting section which was lost when the kernel page was removed.
* Explain DNS warnings and how to fix them on systems running and using a local nameserver.

### [Contrib](#contrib-11)

* Add Tanglu support for mkimage-debootstrap.
* Add SteamOS support for mkimage-debootstrap.

### [Hack](#hack-3)

* Get package coverage when running integration tests.
* Remove the Vagrantfile. This is being replaced with boot2docker.
* Fix tests on systems where aufs isn't available.
* Update packaging instructions and remove the dependency on lxc.

### [Remote API](#remote-api-5)

* Move code specific to the API to the api package.

- Fix header content type for the API. Makes all endpoints use proper content type.
- Fix registry auth & remove ping calls from CmdPush and CmdPull.
- Add newlines to the JSON stream functions.

### [Runtime](#runtime-36)

* Do not ping the registry from the CLI. All requests to registries flow through the daemon.

- Check for nil information return in the lxc driver. This fixes panics with older lxc versions.
- Devicemapper: cleanups and fix for unmount. Fixes two problems which were causing unmount to fail intermittently.
- Devicemapper: remove directory when removing device. Directories don't get left behind when removing the device.

* Devicemapper: enable skip\_block\_zeroing. Improves performance by not zeroing blocks.

- Devicemapper: fix shutdown warnings. Fixes shutdown warnings concerning pool device removal.
- Ensure docker cp stream is closed properly. Fixes problems with files not being copied by `docker cp`.
- Stop making `tcp://` default to `127.0.0.1:4243` and remove the default port for tcp.
- Fix `--run` in `docker commit`. This makes `docker commit --run` work again.
- Fix custom bridge related options. This makes custom bridges work again.

* Mount-bind the PTY as container console. This allows tmux/screen to run.
* Add the pure Go libcontainer library to make it possible to run containers using only features of the Linux kernel.
* Add native exec driver which uses libcontainer and make it the default exec driver.

- Add support for handling extended attributes in archives.

* Set the container MTU to be the same as the host MTU.

- Add simple sha256 checksums for layers to speed up `docker push`.

* Improve kernel version parsing.
* Allow flag grouping (`docker run -it`).

- Remove chroot exec driver.
- Fix divide by zero to fix panic.
- Rewrite `docker rmi`.
- Fix docker info with lxc 1.0.0.
- Fix fedora tty with apparmor.

* Don't always append env vars, replace defaults with vars from config.
* Fix a goroutine leak.
* Switch to Go 1.2.1.

- Fix unique constraint error checks.

* Handle symlinks for Docker's data directory and for TMPDIR.

- Add deprecation warnings for flags (-flag is deprecated in favor of --flag)
- Add apparmor profile for the native execution driver.

* Move system specific code from archive to pkg/system.

- Fix duplicate signal for `docker run -i -t` (issue #3336).
- Return correct process pid for lxc.
- Add a -G option to specify the group which unix sockets belong to.

* Add `-f` flag to `docker rm` to force removal of running containers.
* Kill ghost containers and restart all ghost containers when the docker daemon restarts.
* Add `DOCKER_RAMDISK` environment variable to make Docker work when the root is on a ramdisk.

## [0.8.1 (2014-02-18)](#081-2014-02-18)

### [Builder](#builder-16)

* Avoid extra mount/unmount during build. This removes an unneeded mount/unmount operation which was causing problems with devicemapper
* Fix regression with ADD of tar files. This stops Docker from decompressing tarballs added via ADD from the local file system
* Add error to `docker build --rm`. This adds a missing error check to ensure failures to remove containers are detected and reported

### [Documentation](#documentation-4)

* Update issue filing instructions
* Warn against the use of symlinks for Docker's storage folder
* Replace the Firefox example with an IceWeasel example
* Rewrite the PostgreSQL example using a Dockerfile and add more details to it
* Improve the OS X documentation

### [Remote API](#remote-api-6)

* Fix broken images API for version less than 1.7
* Use the right encoding for all API endpoints which return JSON
* Move remote api client to api/
* Queue calls to the API using generic socket wait

### [Runtime](#runtime-37)

* Fix the use of custom settings for bridges and custom bridges
* Refactor the devicemapper code to avoid many mount/unmount race conditions and failures
* Remove two panics which could make Docker crash in some situations
* Don't ping registry from the CLI client
* Enable skip\_block\_zeroing for devicemapper. This stops devicemapper from always zeroing entire blocks
* Fix --run in `docker commit`. This makes docker commit store `--run` in the image configuration
* Remove directory when removing devicemapper device. This cleans up leftover mount directories
* Drop NET\_ADMIN capability for non-privileged containers. Unprivileged containers can't change their network configuration
* Ensure `docker cp` stream is closed properly
* Avoid extra mount/unmount during container registration. This removes an unneeded mount/unmount operation which was causing problems with devicemapper
* Stop allowing tcp\:// as a default tcp bin address which binds to 127.0.0.1:4243 and remove the default port

- Mount-bind the PTY as container console. This allows tmux and screen to run in a container

* Clean up archive closing. This fixes and improves archive handling
* Fix engine tests on systems where temp directories are symlinked
* Add test methods for save and load
* Avoid temporarily unmounting the container when restarting it. This fixes a race for devicemapper during restart
* Support submodules when building from a GitHub repository
* Quote volume path to allow spaces
* Fix remote tar ADD behavior. This fixes a regression which was causing Docker to extract tarballs

## [0.8.0 (2014-02-04)](#080-2014-02-04)

### [Notable features since 0.7.0](#notable-features-since-070)

* Images and containers can be removed much faster

* Building an image from source with docker build is now much faster

* The Docker daemon starts and stops much faster

* The memory footprint of many common operations has been reduced, by streaming files instead of buffering them in memory, fixing memory leaks, and fixing various suboptimal memory allocations

* Several race conditions were fixed, making Docker more stable under very high concurrency load. This makes Docker more stable and less likely to crash and reduces the memory footprint of many common operations

* All packaging operations are now built on the Go language’s standard tar implementation, which is bundled with Docker itself. This makes packaging more portable across host distributions, and solves several issues caused by quirks and incompatibilities between different distributions of tar

* Docker can now create, remove and modify larger numbers of containers and images graciously thanks to more aggressive releasing of system resources. For example the storage driver API now allows Docker to do reference counting on mounts created by the drivers With the ongoing changes to the networking and execution subsystems of docker testing these areas have been a focus of the refactoring. By moving these subsystems into separate packages we can test, analyze, and monitor coverage and quality of these packages

* Many components have been separated into smaller sub-packages, each with a dedicated test suite. As a result the code is better-tested, more readable and easier to change

* The ADD instruction now supports caching, which avoids unnecessarily re-uploading the same source content again and again when it hasn’t changed

* The new ONBUILD instruction adds to your image a “trigger” instruction to be executed at a later time, when the image is used as the base for another build

* Docker now ships with an experimental storage driver which uses the BTRFS filesystem for copy-on-write

* Docker is officially supported on Mac OS X

* The Docker daemon supports systemd socket activation

## [0.7.6 (2014-01-14)](#076-2014-01-14)

### [Builder](#builder-17)

* Do not follow symlink outside of build context

### [Runtime](#runtime-38)

* Remount bind mounts when ro is specified

- Use https for fetching docker version

### [Other](#other-1)

* Inline the test.docker.io fingerprint
* Add ca-certificates to packaging documentation

## [0.7.5 (2014-01-09)](#075-2014-01-09)

### [Builder](#builder-18)

* Disable compression for build. More space usage but a much faster upload

- Fix ADD caching for certain paths
- Do not compress archive from git build

### [Documentation](#documentation-5)

* Fix error in GROUP add example

- Make sure the GPG fingerprint is inline in the documentation
- Give more specific advice on setting up signing of commits for DCO

### [Runtime](#runtime-39)

* Fix misspelled container names
* Do not add hostname when networking is disabled

- Return most recent image from the cache by date

* Return all errors from docker wait

- Add Content-Type Header "application/json" to GET /version and /info responses

### [Other](#other-2)

* Update DCO to version 1.1

- Update Makefile to use "docker:GIT\_BRANCH" as the generated image name

* Update Travis to check for new 1.1 DCO version

## [0.7.4 (2014-01-07)](#074-2014-01-07)

### [Builder](#builder-19)

* Fix ADD caching issue with . prefixed path
* Fix docker build on devicemapper by reverting sparse file tar option
* Fix issue with file caching and prevent wrong cache hit

- Use same error handling while unmarshalling CMD and ENTRYPOINT

### [Documentation](#documentation-6)

* Simplify and streamline Amazon Quickstart
* Install instructions use unprefixed Fedora image
* Update instructions for mtu flag for Docker on GCE

- Add Ubuntu Saucy to installation

* Fix for wrong version warning on master instead of latest

### [Runtime](#runtime-40)

* Only get the image's rootfs when we need to calculate the image size
* Correctly handle unmapping UDP ports

- Make CopyFileWithTar use a pipe instead of a buffer to save memory on docker build

* Fix login message to say pull instead of push
* Fix "docker load" help by removing "SOURCE" prompt and mentioning STDIN

- Make blank -H option default to the same as no -H was sent
- Extract cgroups utilities to own submodule

### [Other](#other-3)

* Add Travis CI configuration to validate DCO and gofmt requirements
* Add Developer Certificate of Origin Text

- Upgrade VBox Guest Additions
- Check standalone header when pinging a registry server

## [0.7.3 (2014-01-02)](#073-2014-01-02)

### [Builder](#builder-20)

* Update ADD to use the image cache, based on a hash of the added content

- Add error message for empty Dockerfile

### [Documentation](#documentation-7)

* Fix outdated link to the "Introduction" on [www.docker.io](https://www.docker.io)

- Update the docs to get wider when the screen does

* Add information about needing to install LXC when using raw binaries

- Update Fedora documentation to disentangle the docker and docker.io conflict
- Add a note about using the new `-mtu` flag in several GCE zones

* Add FrugalWare installation instructions
* Add a more complete example of `docker run`

- Fix API documentation for creating and starting Privileged containers
- Add missing "name" parameter documentation on "/containers/create"

* Add a mention of `lxc-checkconfig` as a way to check for some of the necessary kernel configuration

- Update the 1.8 API documentation with some additions that were added to the docs for 1.7

### [Hack](#hack-4)

* Add missing libdevmapper dependency to the packagers documentation

- Update minimum Go requirement to a hard line at Go 1.2+
- Many minor improvements to the Vagrantfile

* Add ability to customize dockerinit search locations when compiling (to be used very sparingly only by packagers of platforms who require a nonstandard location)
* Add coverprofile generation reporting

- Add `-a` to our Go build flags, removing the need for recompiling the stdlib manually

* Update Dockerfile to be more canonical and have less spurious warnings during build

- Fix some miscellaneous `docker pull` progress bar display issues

* Migrate more miscellaneous packages under the "pkg" folder
* Update TextMate highlighting to automatically be enabled for files named "Dockerfile"
* Reorganize syntax highlighting files under a common "contrib/syntax" directory
* Update install.sh script (<https://get.docker.io/>) to not fail if busybox fails to download or run at the end of the Ubuntu/Debian installation
* Add support for container names in bash completion

### [Packaging](#packaging-2)

* Add an official Docker client binary for Darwin (Mac OS X)

- Remove empty "Vendor" string and added "License" on deb package

* Add a stubbed version of "/etc/default/docker" in the deb package

### [Runtime](#runtime-41)

* Update layer application to extract tars in place, avoiding file churn while handling whiteouts

- Fix permissiveness of mtime comparisons in tar handling (since GNU tar and Go tar do not yet support sub-second mtime precision)

* Reimplement `docker top` in pure Go to work more consistently, and even inside Docker-in-Docker (thus removing the shell injection vulnerability present in some versions of `lxc-ps`)

- Update `-H unix://` to work similarly to `-H tcp://` by inserting the default values for missing portions

* Fix more edge cases regarding dockerinit and deleted or replaced docker or dockerinit files

- Update container name validation to include '.'

* Fix use of a symlink or non-absolute path as the argument to `-g` to work as expected

- Update to handle external mounts outside of LXC, fixing many small mounting quirks and making future execution backends and other features simpler
- Update to use proper box-drawing characters everywhere in `docker images -tree`
- Move MTU setting from LXC configuration to directly use netlink
- Add `-S` option to external tar invocation for more efficient spare file handling

* Add arch/os info to User-Agent string, especially for registry requests
* Add `-mtu` option to Docker daemon for configuring MTU

- Fix `docker build` to exit with a non-zero exit code on error

* Add `DOCKER_HOST` environment variable to configure the client `-H` flag without specifying it manually for every invocation

## [0.7.2 (2013-12-16)](#072-2013-12-16)

### [Runtime](#runtime-42)

* Validate container names on creation with standard regex

- Increase maximum image depth to 127 from 42
- Continue to move api endpoints to the job api

* Add -bip flag to allow specification of dynamic bridge IP via CIDR

- Allow bridge creation when ipv6 is not enabled on certain systems

* Set hostname and IP address from within dockerinit
* Drop capabilities from within dockerinit

- Fix volumes on host when symlink is present the image
- Prevent deletion of image if ANY container is depending on it even if the container is not running

* Update docker push to use new progress display
* Use os.Lstat to allow mounting unix sockets when inspecting volumes

- Adjust handling of inactive user login
- Add missing defines in devicemapper for older kernels
- Allow untag operations with no container validation
- Add auth config to docker build

### [Documentation](#documentation-8)

* Add more information about Docker logging

- Add RHEL documentation

* Add a direct example for changing the CMD that is run in a container
* Update Arch installation documentation

- Add section on Trusted Builds
- Add Network documentation page

### [Other](#other-4)

* Add new cover bundle for providing code coverage reporting

- Separate integration tests in bundles
- Make Tianon the hack maintainer
- Update mkimage-debootstrap with more tweaks for keeping images small
- Use https to get the install script
- Remove vendored dotcloud/tar now that Go 1.2 has been released

## [0.7.1 (2013-12-05)](#071-2013-12-05)

### [Documentation](#documentation-9)

* Add @SvenDowideit as documentation maintainer
* Add links example
* Add documentation regarding ambassador pattern
* Add Google Cloud Platform docs
* Add dockerfile best practices

- Update doc for RHEL
- Update doc for registry
- Update Postgres examples
- Update doc for Ubuntu install
- Improve remote api doc

### [Runtime](#runtime-43)

* Add hostconfig to docker inspect
* Implement `docker log -f` to stream logs
* Add env variable to disable kernel version warning
* Add -format to `docker inspect`
* Support bind-mount for files

- Fix bridge creation on RHEL
- Fix image size calculation
- Make sure iptables are called even if the bridge already exists
- Fix issue with stderr only attach
- Remove init layer when destroying a container
- Fix same port binding on different interfaces
- `docker build` now returns the correct exit code
- Fix `docker port` to display correct port
- `docker build` now check that the dockerfile exists client side
- `docker attach` now returns the correct exit code
- Remove the name entry when the container does not exist

### [Registry](#registry-2)

* Improve progress bars, add ETA for downloads
* Simultaneous pulls now waits for the first to finish instead of failing

- Tag only the top-layer image when pushing to registry
- Fix issue with offline image transfer
- Fix issue preventing using ':' in password for registry

### [Other](#other-5)

* Add pprof handler for debug
* Create a Makefile

- Use stdlib tar that now includes fix
- Improve make.sh test script
- Handle SIGQUIT on the daemon
- Disable verbose during tests
- Upgrade to go1.2 for official build
- Improve unit tests
- The test suite now runs all tests even if one fails
- Refactor C in Go (Devmapper)

* Fix OS X compilation

## [0.7.0 (2013-11-25)](#070-2013-11-25)

### [Notable features since 0.6.0](#notable-features-since-060)

* Storage drivers: choose from aufs, device-mapper, or vfs.
* Standard Linux support: docker now runs on unmodified Linux kernels and all major distributions.
* Links: compose complex software stacks by connecting containers to each other.
* Container naming: organize your containers by giving them memorable names.
* Advanced port redirects: specify port redirects per interface, or keep sensitive ports private.
* Offline transfer: push and pull images to the filesystem without losing information.
* Quality: numerous bugfixes and small usability improvements. Significant increase in test coverage.

## [0.6.7 (2013-11-21)](#067-2013-11-21)

### [Runtime](#runtime-44)

* Improve stability, fixes some race conditions
* Skip the volumes mounted when deleting the volumes of container.
* Fix layer size computation: handle hard links correctly
* Use the work Path for docker cp CONTAINER:PATH
* Fix tmp dir never cleanup
* Speedup docker ps
* More informative error message on name collisions
* Fix nameserver regex
* Always return long id's
* Fix container restart race condition
* Keep published ports on docker stop;docker start
* Fix container networking on Fedora
* Correctly express "any address" to iptables
* Fix network setup when reconnecting to ghost container
* Prevent deletion if image is used by a running container
* Lock around read operations in graph

### [RemoteAPI](#remoteapi)

* Return full ID on docker rmi

### [Client](#client-12)

* Add -tree option to images
* Offline image transfer

- Exit with status 2 on usage error and display usage on stderr
- Do not forward SIGCHLD to container
- Use string timestamp for docker events -since

### [Other](#other-6)

* Update to go 1.2rc5

- Add /etc/default/docker support to upstart

## [0.6.6 (2013-11-06)](#066-2013-11-06)

### [Runtime](#runtime-45)

* Ensure container name on register
* Fix regression in /etc/hosts

- Add lock around write operations in graph

* Check if port is valid
* Fix restart runtime error with ghost container networking

- Add some more colors and animals to increase the pool of generated names

* Fix issues in docker inspect

- Escape apparmor confinement
- Set environment variables using a file.

* Prevent docker insert to erase something

- Prevent DNS server conflicts in CreateBridgeIface
- Validate bind mounts on the server side
- Use parent image config in docker build

* Fix regression in /etc/hosts

### [Client](#client-13)

* Add -P flag to publish all exposed ports
* Add -notrunc and -q flags to docker history

- Fix docker commit, tag and import usage

* Add stars, trusted builds and library flags in docker search

- Fix docker logs with tty

### [RemoteAPI](#remoteapi-1)

* Make /events API send headers immediately
* Do not split last column docker top

- Add size to history

### [Other](#other-7)

* Contrib: Desktop integration. Firefox usecase.
* Dockerfile: bump to go1.2rc3

## [0.6.5 (2013-10-29)](#065-2013-10-29)

### [Runtime](#runtime-46)

* Containers can now be named
* Containers can now be linked together for service discovery
* 'run -a', 'start -a' and 'attach' can forward signals to the container for better integration with process supervisors
* Automatically start crashed containers after a reboot
* Expose IP, port, and proto as separate environment vars for container links

- Allow ports to be published to specific ips
- Prohibit inter-container communication by default

* Ignore ErrClosedPipe for stdin in Container.Attach
* Remove unused field kernelVersion

- Fix issue when mounting subdirectories of /mnt in container

* Fix untag during removal of images

- Check return value of syscall.Chdir when changing working directory inside dockerinit

### [Client](#client-14)

* Only pass stdin to hijack when needed to avoid closed pipe errors

- Use less reflection in command-line method invocation

* Monitor the tty size after starting the container, not prior
* Remove useless os.Exit() calls after log.Fatal

### [Hack](#hack-5)

* Add initial init scripts library and a safer Ubuntu packaging script that works for Debian

- Add -p option to invoke debootstrap with http\_proxy

* Update install.sh with $sh\_c to get sudo/su for modprobe

- Update all the mkimage scripts to use --numeric-owner as a tar argument
- Update hack/release.sh process to automatically invoke hack/make.sh and bail on build and test issues

### [Other](#other-8)

* Documentation: Fix the flags for nc in example
* Testing: Remove warnings and prevent mount issues

- Testing: Change logic for tty resize to avoid warning in tests
- Builder: Fix race condition in docker build with verbose output
- Registry: Fix content-type for PushImageJSONIndex method

* Contrib: Improve helper tools to generate debian and Arch linux server images

## [0.6.4 (2013-10-16)](#064-2013-10-16)

### [Runtime](#runtime-47)

* Add cleanup of container when Start() fails

- Add better comments to utils/stdcopy.go
- Add utils.Errorf for error logging

* Add -rm to docker run for removing a container on exit

- Remove error messages which are not actually errors
- Fix `docker rm` with volumes
- Fix some error cases where an HTTP body might not be closed
- Fix panic with wrong dockercfg file
- Fix the attach behavior with -i

* Record termination time in state.

- Use empty string so TempDir uses the OS's temp dir automatically
- Make sure to close the network allocators

* Autorestart containers by default

- Bump vendor kr/pty to commit 3b1f6487b `(syscall.O_NOCTTY)`
- lxc: Allow set\_file\_cap capability in container

* Move run -rm to the cli only

- Split stdout stderr
- Always create a new session for the container

### [Testing](#testing)

* Add aggregated docker-ci email report
* Add cleanup to remove leftover containers

- Add nightly release to docker-ci
- Add more tests around auth.ResolveAuthConfig

* Remove a few errors in tests
* Catch errClosing error when TCP and UDP proxies are terminated

- Only run certain tests with TESTFLAGS='-run TestName' make.sh
- Prevent docker-ci to test closing PRs
- Replace panic by log.Fatal in tests

* Increase TestRunDetach timeout

### [Documentation](#documentation-10)

* Add initial draft of the Docker infrastructure doc
* Add devenvironment link to CONTRIBUTING.md
* Add `apt-get install curl` to Ubuntu docs
* Add explanation for export restrictions
* Add .dockercfg doc
* Remove Gentoo install notes about #1422 workaround
* Fix help text for -v option
* Fix Ping endpoint documentation

- Fix parameter names in docs for ADD command
- Fix ironic typo in changelog

* Various command fixes in postgres example
* Document how to edit and release docs

- Minor updates to `postgresql_service.rst`

* Clarify LGTM process to contributors

- Corrected error in the package name

* Document what `vagrant up` is actually doing

- improve doc search results

* Cleanup whitespace in API 1.5 docs
* use angle brackets in MAINTAINER example email
* Update archlinux.rst

- Changes to a new style for the docs. Includes version switcher.

* Formatting, add information about multiline json
* Improve registry and index REST API documentation

- Replace deprecated upgrading reference to docker-latest.tgz, which hasn't been updated since 0.5.3

* Update Gentoo installation documentation now that we're in the portage tree proper
* Cleanup and reorganize docs and tooling for contributors and maintainers

- Minor spelling correction of protocoll -> protocol

### [Contrib](#contrib-12)

* Add vim syntax highlighting for Dockerfiles from @honza
* Add mkimage-arch.sh
* Reorganize contributed completion scripts to add zsh completion

### [Hack](#hack-6)

* Add vagrant user to the docker group
* Add proper bash completion for "docker push"
* Add xz utils as a runtime dep
* Add cleanup/refactor portion of #2010 for hack and Dockerfile updates

- Add contrib/mkimage-centos.sh back (from #1621), and associated documentation link

* Add several of the small make.sh fixes from #1920, and make the output more consistent and contributor-friendly

- Add @tianon to hack/MAINTAINERS

* Improve network performance for VirtualBox
* Revamp install.sh to be usable by more people, and to use official install methods whenever possible (apt repo, portage tree, etc.)

- Fix contrib/mkimage-debian.sh apt caching prevention

* Add Dockerfile.tmLanguage to contrib

- Configured FPM to make /etc/init/docker.conf a config file
- Enable SSH Agent forwarding in Vagrant VM
- Several small tweaks/fixes for contrib/mkimage-debian.sh

### [Other](#other-9)

* Builder: Abort build if mergeConfig returns an error and fix duplicate error message
* Packaging: Remove deprecated packaging directory
* Registry: Use correct auth config when logging in.
* Registry: Fix the error message so it is the same as the regex

## [0.6.3 (2013-09-23)](#063-2013-09-23)

### [Packaging](#packaging-3)

* Add 'docker' group on install for ubuntu package
* Update tar vendor dependency
* Download apt key over HTTPS

### [Runtime](#runtime-48)

* Only copy and change permissions on non-bindmount volumes

- Allow multiple volumes-from

* Fix HTTP imports from STDIN

### [Documentation](#documentation-11)

* Update section on extracting the docker binary after build
* Update development environment docs for new build process
* Remove 'base' image from documentation

### [Other](#other-10)

* Client: Fix detach issue
* Registry: Update regular expression to match index

## [0.6.2 (2013-09-17)](#062-2013-09-17)

### [Runtime](#runtime-49)

* Add domainname support
* Implement image filtering with path.Match

- Remove unnecessary warnings
- Remove os/user dependency
- Only mount the hostname file when the config exists
- Handle signals within the `docker login` command

* UID and GID are now also applied to volumes
* `docker start` set error code upon error
* `docker run` set the same error code as the process started

### [Builder](#builder-21)

* Add -rm option in order to remove intermediate containers

- Allow multiline for the RUN instruction

### [Registry](#registry-3)

* Implement login with private registry

- Fix push issues

### [Other](#other-11)

* Hack: Vendor all dependencies

- Remote API: Bump to v1.5
- Packaging: Break down hack/make.sh into small scripts, one per 'bundle': test, binary, ubuntu etc.
- Documentation: General improvements

## [0.6.1 (2013-08-23)](#061-2013-08-23)

### [Registry](#registry-4)

* Pass "meta" headers in API calls to the registry

### [Packaging](#packaging-4)

* Use correct upstart script with new build tool
* Use libffi-dev, don't build it from sources
* Remove duplicate mercurial install command

## [0.6.0 (2013-08-22)](#060-2013-08-22)

### [Runtime](#runtime-50)

* Add lxc-conf flag to allow custom lxc options
* Add an option to set the working directory

- Add Image name to LogEvent tests

* Add -privileged flag and relevant tests, docs, and examples

- Add websocket support to /container//attach/ws
- Add warning when net.ipv4.ip\_forwarding = 0
- Add hostname to environment
- Add last stable version in `docker version`

* Fix race conditions in parallel pull
* Fix Graph ByParent() to generate list of child images per parent image.
* Fix typo: fmt.Sprint -> fmt.Sprintf
* Fix small \n error un docker build

- Fix to "Inject dockerinit at /.dockerinit"
- Fix #910. print user name to docker info output
- Use Go 1.1.2 for dockerbuilder
- Use ranged for loop on channels

* Use utils.ParseRepositoryTag instead of strings.Split(name, ":") in server.ImageDelete
* Improve CMD, ENTRYPOINT, and attach docs.
* Improve connect message with socket error
* Load authConfig only when needed and fix useless WARNING
* Show tag used when image is missing

- Apply volumes-from before creating volumes

* Make docker run handle SIGINT/SIGTERM
* Prevent crash when .dockercfg not readable
* Install script should be fetched over https, not http.

- API, issue 1471: Use groups for socket permissions

* Correctly detect IPv4 forwarding

- Mount /dev/shm as a tmpfs

* Switch from http to https for get.docker.io

- Let userland proxy handle container-bound traffic
- Update the Docker CLI to specify a value for the "Host" header.

* Change network range to avoid conflict with EC2 DNS
* Reduce connect and read timeout when pinging the registry

- Parallel pull

* Handle ip route showing mask-less IP addresses

- Allow ENTRYPOINT without CMD

* Always consider localhost as a domain name when parsing the FQN repos name

- Refactor checksum

### [Documentation](#documentation-12)

* Add MongoDB image example
* Add instructions for creating and using the docker group
* Add sudo to examples and installation to documentation
* Add ufw doc
* Add a reference to ps -a
* Add information about Docker's high level tools over LXC.
* Fix typo in docs for docker run -dns
* Fix a typo in the ubuntu installation guide
* Fix to docs regarding adding docker groups
* Update default -H docs
* Update readme with dependencies for building
* Update amazon.rst to explain that Vagrant is not necessary for running Docker on ec2
* PostgreSQL service example in documentation
* Suggest installing linux-headers by default.
* Change the twitter handle
* Clarify Amazon EC2 installation
* 'Base' image is deprecated and should no longer be referenced in the docs.
* Move note about officially supported kernel

- Solved the logo being squished in Safari

### [Builder](#builder-22)

* Add USER instruction do Dockerfile
* Add workdir support for the Buildfile

- Add no cache for docker build

* Fix docker build and docker events output
* Only count known instructions as build steps
* Make sure ENV instruction within build perform a commit each time
* Forbid certain paths within docker build ADD
* Repository name (and optionally a tag) in build usage
* Make sure ADD will create everything in 0755

### [Remote API](#remote-api-7)

* Sort Images by most recent creation date.
* Reworking opaque requests in registry module
* Add image name in /events
* Use mime pkg to parse Content-Type
* 650 http utils and user agent field

### [Hack](#hack-7)

* Bash Completion: Limit commands to containers of a relevant state

- Add docker dependencies coverage testing into docker-ci

### [Packaging](#packaging-5)

* Docker-brew 0.5.2 support and memory footprint reduction

- Add new docker dependencies into docker-ci

* Revert "docker.upstart: avoid spawning a `sh` process"

- Docker-brew and Docker standard library
- Release docker with docker

* Fix the upstart script generated by get.docker.io
* Enabled the docs to generate manpages.
* Revert Bind daemon to 0.0.0.0 in Vagrant.

### [Register](#register)

* Improve auth push
* Registry unit tests + mock registry

### [Tests](#tests)

* Improve TestKillDifferentUser to prevent timeout on buildbot

- Fix typo in TestBindMounts (runContainer called without image)

* Improve TestGetContainersTop so it does not rely on sleep
* Relax the lo interface test to allow iface index != 1
* Add registry functional test to docker-ci
* Add some tests in server and utils

### [Other](#other-12)

* Contrib: bash completion script
* Client: Add docker cp command and copy api endpoint to copy container files/folders to the host
* Don't read from stdout when only attached to stdin

## [0.5.3 (2013-08-13)](#053-2013-08-13)

### [Runtime](#runtime-51)

* Use docker group for socket permissions

- Spawn shell within upstart script
- Handle ip route showing mask-less IP addresses
- Add hostname to environment

### [Builder](#builder-23)

* Make sure ENV instruction within build perform a commit each time

## [0.5.2 (2013-08-08)](#052-2013-08-08)

* Builder: Forbid certain paths within docker build ADD

- Runtime: Change network range to avoid conflict with EC2 DNS

* API: Change daemon to listen on unix socket by default

## [0.5.1 (2013-07-30)](#051-2013-07-30)

### [Runtime](#runtime-52)

* Add `ps` args to `docker top`
* Add support for container ID files (pidfile like)
* Add container=lxc in default env
* Support networkless containers with `docker run -n` and `docker -d -b=none`

- Stdout/stderr logs are now stored in the same file as JSON
- Allocate a /16 IP range by default, with fallback to /24. Try 12 ranges instead of 3.
- Change .dockercfg format to json and support multiple auth remote

* Do not override volumes from config
* Fix issue with EXPOSE override

### [API](#api)

* Docker client now sets useragent (RFC 2616)
* Add /events endpoint

### [Builder](#builder-24)

* ADD command now understands URLs
* CmdAdd and CmdEnv now respect Dockerfile-set ENV variables

- Create directories with 755 instead of 700 within ADD instruction

### [Hack](#hack-8)

* Simplify unit tests with helpers
* Improve docker.upstart event
* Add coverage testing into docker-ci

## [0.5.0 (2013-07-17)](#050-2013-07-17)

### [Runtime](#runtime-53)

* List all processes running inside a container with 'docker top'
* Host directories can be mounted as volumes with 'docker run -v'
* Containers can expose public UDP ports (eg, '-p 123/udp')
* Optionally specify an exact public port (eg. '-p 80:4500')

- 'docker login' supports additional options

* Don't save a container's hostname when committing an image.

### [Registry](#registry-5)

* New image naming scheme inspired by Go packaging convention allows arbitrary combinations of registries

- Fix issues when uploading images to a private registry

### [Builder](#builder-25)

* ENTRYPOINT instruction sets a default binary entry point to a container
* VOLUME instruction marks a part of the container as persistent data

- 'docker build' displays the full output of a build by default

## [0.4.8 (2013-07-01)](#048-2013-07-01)

* Builder: New build operation ENTRYPOINT adds an executable entry point to the container. - Runtime: Fix a bug which caused 'docker run -d' to no longer print the container ID.

- Tests: Fix issues in the test suite

## [0.4.7 (2013-06-28)](#047-2013-06-28)

### [Remote API](#remote-api-8)

* The progress bar updates faster when downloading and uploading large files

- Fix a bug in the optional unix socket transport

### [Runtime](#runtime-54)

* Improve detection of kernel version

- Host directories can be mounted as volumes with 'docker run -b'

* fix an issue when only attaching to stdin

- Use 'tar --numeric-owner' to avoid uid mismatch across multiple hosts

### [Hack](#hack-9)

* Improve test suite and dev environment
* Remove dependency on unit tests on 'os/user'

### [Other](#other-13)

* Registry: easier push/pull to a custom registry

- Documentation: add terminology section

## [0.4.6 (2013-06-22)](#046-2013-06-22)

* Runtime: fix a bug which caused creation of empty images (and volumes) to crash.

## [0.4.5 (2013-06-21)](#045-2013-06-21)

* Builder: 'docker build git://URL' fetches and builds a remote git repository

- Runtime: 'docker ps -s' optionally prints container size
- Tests: improved and simplified

* Runtime: fix a regression introduced in 0.4.3 which caused the logs command to fail.
* Builder: fix a regression when using ADD with single regular file.

## [0.4.4 (2013-06-19)](#044-2013-06-19)

* Builder: fix a regression introduced in 0.4.3 which caused builds to fail on new clients.

## [0.4.3 (2013-06-19)](#043-2013-06-19)

### [Builder](#builder-26)

* ADD of a local file will detect tar archives and unpack them

- ADD improvements: use tar for copy + automatically unpack local archives
- ADD uses tar/untar for copies instead of calling 'cp -ar'
- Fix the behavior of ADD to be (mostly) reverse-compatible, predictable and well-documented.

* Fix a bug which caused builds to fail if ADD was the first command

- Nicer output for 'docker build'

### [Runtime](#runtime-55)

* Remove bsdtar dependency
* Add unix socket and multiple -H support
* Prevent rm of running containers
* Use go1.1 cookiejar

- Fix issue detaching from running TTY container
- Forbid parallel push/pull for a single image/repo. Fixes `#311`
- Fix race condition within Run command when attaching.

### [Client](#client-15)

* HumanReadable ProgressBar sizes in pull
* Fix docker version's git commit output

### [API](#api-1)

* Send all tags on History API call
* Add tag lookup to history command. Fixes #882

### [Documentation](#documentation-13)

* Fix missing command in irc bouncer example

## [0.4.2 (2013-06-17)](#042-2013-06-17)

* Packaging: Bumped version to work around an Ubuntu bug

## [0.4.1 (2013-06-17)](#041-2013-06-17)

### [Remote Api](#remote-api-9)

* Add flag to enable cross domain requests
* Add images and containers sizes in docker ps and docker images

### [Runtime](#runtime-56)

* Configure dns configuration host-wide with 'docker -d -dns'
* Detect faulty DNS configuration and replace it with a public default
* Allow docker run :
* You can now specify public port (ex: -p 80:4500)

- Improve image removal to garbage-collect unreferenced parents

### [Client](#client-16)

* Allow multiple params in inspect
* Print the container id before the hijack in `docker run`

### [Registry](#registry-6)

* Add regexp check on repo's name
* Move auth to the client

- Remove login check on pull

### [Other](#other-14)

* Vagrantfile: Add the rest api port to vagrantfile's port\_forward
* Upgrade to Go 1.1

- Builder: don`t ignore last line in Dockerfile when it doesn`t end with \n

## [0.4.0 (2013-06-03)](#040-2013-06-03)

### [Builder](#builder-27)

* Introducing Builder
* 'docker build' builds a container, layer by layer, from a source repository containing a Dockerfile

### [Remote API](#remote-api-10)

* Introducing Remote API
* control Docker programmatically using a simple HTTP/json API

### [Runtime](#runtime-57)

* Various reliability and usability improvements

## [0.3.4 (2013-05-30)](#034-2013-05-30)

### [Builder](#builder-28)

* 'docker build' builds a container, layer by layer, from a source repository containing a Dockerfile
* 'docker build -t FOO' applies the tag FOO to the newly built container.

### [Runtime](#runtime-58)

* Interactive TTYs correctly handle window resize

- Fix how configuration is merged between layers

### [Remote API](#remote-api-11)

* Split stdout and stderr on 'docker run'
* Optionally listen on a different IP and port (use at your own risk)

### [Documentation](#documentation-14)

* Improve install instructions.

## [0.3.3 (2013-05-23)](#033-2013-05-23)

* Registry: Fix push regression
* Various bugfixes

## [0.3.2 (2013-05-09)](#032-2013-05-09)

### [Registry](#registry-7)

* Improve the checksum process
* Use the size to have a good progress bar while pushing
* Use the actual archive if it exists in order to speed up the push

- Fix error 400 on push

### [Runtime](#runtime-59)

* Store the actual archive on commit

## [0.3.1 (2013-05-08)](#031-2013-05-08)

### [Builder](#builder-29)

* Implement the autorun capability within docker builder
* Add caching to docker builder
* Add support for docker builder with native API as top level command
* Implement ENV within docker builder

- Check the command existence prior create and add Unit tests for the case

* use any whitespaces instead of tabs

### [Runtime](#runtime-60)

* Add go version to debug infos

- Kernel version - don't show the dash if flavor is empty

### [Registry](#registry-8)

* Add docker search top level command in order to search a repository

- Fix pull for official images with specific tag
- Fix issue when login in with a different user and trying to push

* Improve checksum - async calculation

### [Images](#images)

* Output graph of images to dot (graphviz)

- Fix ByParent function

### [Documentation](#documentation-15)

* New introduction and high-level overview
* Add the documentation for docker builder

- CSS fix for docker documentation to make REST API docs look better.
- Fix CouchDB example page header mistake
- Fix README formatting

* Update [www.docker.io](https://www.docker.io) website.

### [Other](#other-15)

* Website: new high-level overview

- Makefile: Swap "go get" for "go get -d", especially to compile on go1.1rc

* Packaging: packaging ubuntu; issue #510: Use golang-stable PPA package to build docker

## [0.3.0 (2013-05-06)](#030-2013-05-06)

### [Runtime](#runtime-61)

* Fix the command existence check
* strings.Split may return an empty string on no match
* Fix an index out of range crash if cgroup memory is not

### [Documentation](#documentation-16)

* Various improvements

- New example: sharing data between 2 couchdb databases

### [Other](#other-16)

* Vagrant: Use only one deb line in /etc/apt

- Registry: Implement the new registry

## [0.2.2 (2013-05-03)](#022-2013-05-03)

* Support for data volumes ('docker run -v=PATH')
* Share data volumes between containers ('docker run -volumes-from')
* Improve documentation

- Upgrade to Go 1.0.3
- Various upgrades to the dev environment for contributors

## [0.2.1 (2013-05-01)](#021-2013-05-01)

* 'docker commit -run' bundles a layer with default runtime options: command, ports etc.

- Improve install process on Vagrant

* New Dockerfile operation: "maintainer"
* New Dockerfile operation: "expose"
* New Dockerfile operation: "cmd"
* Contrib script to build a Debian base layer
* 'docker -d -r': restart crashed containers at daemon startup

- Runtime: improve test coverage

## [0.2.0 (2013-04-23)](#020-2013-04-23)

* Runtime: ghost containers can be killed and waited for

- Documentation: update install instructions

* Packaging: fix Vagrantfile
* Development: automate releasing binaries and ubuntu packages

- Add a changelog

* Various bugfixes

## [0.1.8 (2013-04-22)](#018-2013-04-22)

* Dynamically detect cgroup capabilities
* Issue stability warning on kernels <3.8
* 'docker push' buffers on disk instead of memory
* Fix 'docker diff' for removed files
* Fix 'docker stop' for ghost containers
* Fix handling of pidfile
* Various bugfixes and stability improvements

## [0.1.7 (2013-04-18)](#017-2013-04-18)

* Container ports are available on localhost
* 'docker ps' shows allocated TCP ports
* Contributors can run 'make hack' to start a continuous integration VM
* Streamline ubuntu packaging & uploading
* Various bugfixes and stability improvements

## [0.1.6 (2013-04-17)](#016-2013-04-17)

* Record the author an image with 'docker commit -author'

## [0.1.5 (2013-04-17)](#015-2013-04-17)

* Disable standalone mode
* Use a custom DNS resolver with 'docker -d -dns'
* Detect ghost containers
* Improve diagnosis of missing system capabilities
* Allow disabling memory limits at compile time
* Add debian packaging
* Documentation: installing on Arch Linux
* Documentation: running Redis on docker
* Fix lxc 0.9 compatibility
* Automatically load aufs module
* Various bugfixes and stability improvements

## [0.1.4 (2013-04-09)](#014-2013-04-09)

* Full support for TTY emulation
* Detach from a TTY session with the escape sequence `C-p C-q`
* Various bugfixes and stability improvements
* Minor UI improvements
* Automatically create our own bridge interface 'docker0'

## [0.1.3 (2013-04-04)](#013-2013-04-04)

* Choose TCP frontend port with '-p :PORT'
* Layer format is versioned
* Major reliability improvements to the process manager
* Various bugfixes and stability improvements

## [0.1.2 (2013-04-03)](#012-2013-04-03)

* Set container hostname with 'docker run -h'
* Selective attach at run with 'docker run -a \[stdin\[,stdout\[,stderr]]]'
* Various bugfixes and stability improvements
* UI polish
* Progress bar on push/pull
* Use XZ compression by default
* Make IP allocator lazy

## [0.1.1 (2013-03-31)](#011-2013-03-31)

* Display shorthand IDs for convenience
* Stabilize process management
* Layers can include a commit message
* Simplified 'docker attach'
* Fix support for re-attaching
* Various bugfixes and stability improvements
* Auto-download at run
* Auto-login on push
* Beefed up documentation

## [0.1.0 (2013-03-23)](#010-2013-03-23)

Initial public release

* Implement registry in order to push/pull images
* TCP port allocation
* Fix termcaps on Linux
* Add documentation
* Add Vagrant support with Vagrantfile
* Add unit tests
* Add repository/tags to ease image management
* Improve the layer implementation

----
url: https://docs.docker.com/reference/compose-file/build/
----

# Compose Build Specification

***

Table of contents

***

Build is an optional part of the Compose Specification. It tells Compose how to (re)build an application from source and lets you define the build process within a Compose file in a portable way. `build` can be either specified as a single string defining a context path, or as a detailed build definition.

When `build` is specified as a string, the whole path is used as a Docker context to execute a Docker build, looking for a canonical `Dockerfile` at the root of the directory.

When `build` is specified as a detailed structure, build arguments can be specified, including an alternate `Dockerfile` location.

In both cases, the path can be absolute or relative. If it is relative, it is resolved from the directory containing your Compose file. If it is absolute, the path prevents the Compose file from being portable so Compose displays a warning.

## [Using `build` and `image`](#using-build-and-image)

When Compose is confronted with both a `build` subsection for a service and an `image` attribute, it follows the rules defined by the [`pull_policy`](https://docs.docker.com/reference/compose-file/services/#pull_policy) attribute.

If `pull_policy` is missing from the service definition, Compose attempts to pull the image first and then builds from source if the image isn't found in the registry or platform cache.

## [Publishing built images](#publishing-built-images)

Compose with `build` support offers an option to push built images to a registry. When doing so, it doesn't try to push service images without an `image` attribute. Compose warns you about the missing `image` attribute which prevents images being pushed.

## [Illustrative example](#illustrative-example)

The following example illustrates Compose Build Specification concepts with a concrete sample application. The sample is non-normative.

```yaml
services:
  frontend:
    image: example/webapp
    build: ./webapp

  backend:
    image: example/database
    build:
      context: backend
      dockerfile: ../backend.Dockerfile

  custom:
    build: ~/custom
```

When used to build service images from source, the Compose file creates three Docker images:

* `example/webapp`: A Docker image is built using `webapp` sub-directory, within the Compose file's folder, as the Docker build context. Lack of a `Dockerfile` within this folder returns an error.
* `example/database`: A Docker image is built using `backend` sub-directory within the Compose file's folder. `backend.Dockerfile` file is used to define build steps, this file is searched relative to the context path, which means `..` resolves to the Compose file's folder, so `backend.Dockerfile` is a sibling file.
* A Docker image is built using the `custom` directory with the user's `$HOME` as the Docker context. Compose displays a warning about the non-portable path used to build image.

On push, both `example/webapp` and `example/database` Docker images are pushed to the default registry. The `custom` service image is skipped as no `image` attribute is set and Compose displays a warning about this missing attribute.

## [Attributes](#attributes)

The `build` subsection defines configuration options that are applied by Compose to build Docker images from source. `build` can be specified either as a string containing a path to the build context or as a detailed structure:

Using the string syntax, only the build context can be configured as either:

* A relative path to the Compose file's folder. This path must be a directory and must contain a `Dockerfile`

  ```yml
  services:
    webapp:
      build: ./dir
  ```

* A Git repository URL. Git URLs accept context configuration in their fragment section, separated by a colon (`:`). The first part represents the reference that Git checks out, and can be either a branch, a tag, or a remote reference. The second part represents a subdirectory inside the repository that is used as a build context.

  ```yml
  services:
    webapp:
      build: https://github.com/mycompany/example.git#branch_or_tag:subdirectory
  ```

Alternatively `build` can be an object with fields defined as follows:

### [`additional_contexts`](#additional_contexts)

Requires: Docker Compose [2.17.0](https://github.com/docker/compose/releases/tag/v2.17.0) and later

`additional_contexts` defines a list of named contexts the image builder should use during image build.

`additional_contexts` can be a mapping or a list:

```yml
build:
  context: .
  additional_contexts:
    - resources=/path/to/resources
    - app=docker-image://my-app:latest
    - source=https://github.com/myuser/project.git
```

```yml
build:
  context: .
  additional_contexts:
    resources: /path/to/resources
    app: docker-image://my-app:latest
    source: https://github.com/myuser/project.git
```

When used as a list, the syntax follows the `NAME=VALUE` format, where `VALUE` is a string. Validation beyond that is the responsibility of the image builder (and is builder specific). Compose supports at least absolute and relative paths to a directory and Git repository URLs, like [context](#context) does. Other context flavours must be prefixed to avoid ambiguity with a `type://` prefix.

Compose warns you if the image builder does not support additional contexts and may list the unused contexts.

Refer to the reference documentation for [`docker buildx build --build-context`](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-additional-build-contexts---build-context) for example usage.

`additional_contexts` can also refer to an image built by another service. This allows a service image to be built using another service image as a base image, and to share layers between service images.

```yaml
services:
  base:
    build:
      context: .
      dockerfile_inline: |
        FROM alpine
        RUN ...
  my-service:
    build:
      context: .
      dockerfile_inline: |
        FROM base # image built for service base
        RUN ...
      additional_contexts:
        base: service:base
```

### [`args`](#args)

`args` define build arguments, that is Dockerfile `ARG` values.

Using the following Dockerfile as an example:

```Dockerfile
ARG GIT_COMMIT
RUN echo "Based on commit: $GIT_COMMIT"
```

`args` can be set in the Compose file under the `build` key to define `GIT_COMMIT`. `args` can be set as a mapping or a list:

```yml
build:
  context: .
  args:
    GIT_COMMIT: cdc3b19
```

```yml
build:
  context: .
  args:
    - GIT_COMMIT=cdc3b19
```

Values can be omitted when specifying a build argument, in which case its value at build time must be obtained by user interaction, otherwise the build argument won't be set when building the Docker image.

```yml
args:
  - GIT_COMMIT
```

### [`cache_from`](#cache_from)

`cache_from` defines a list of sources the image builder should use for cache resolution.

Cache location syntax follows the global format `[NAME|type=TYPE[,KEY=VALUE]]`. Simple `NAME` is actually a shortcut notation for `type=registry,ref=NAME`.

Compose Build implementations may support custom types, the Compose Specification defines canonical types which must be supported:

* `registry` to retrieve build cache from an OCI image set by key `ref`

```yml
build:
  context: .
  cache_from:
    - alpine:latest
    - type=local,src=path/to/cache
    - type=gha
```

Unsupported caches are ignored and don't prevent you from building images.

### [`cache_to`](#cache_to)

`cache_to` defines a list of export locations to be used to share build cache with future builds.

```yml
build:
  context: .
  cache_to:
    - user/app:cache
    - type=local,dest=path/to/cache
```

Cache target is defined using the same `type=TYPE[,KEY=VALUE]` syntax defined by [`cache_from`](#cache_from).

Unsupported caches are ignored and don't prevent you from building images.

### [`context`](#context)

`context` defines either a path to a directory containing a Dockerfile, or a URL to a Git repository.

When the value supplied is a relative path, it is interpreted as relative to the project directory. Compose warns you about the absolute path used to define the build context as those prevent the Compose file from being portable.

```yml
build:
  context: ./dir
```

```yml
services:
  webapp:
    build: https://github.com/mycompany/webapp.git
```

If not set explicitly, `context` defaults to project directory (`.`).

### [`dockerfile`](#dockerfile)

`dockerfile` sets an alternate Dockerfile. A relative path is resolved from the build context. Compose warns you about the absolute path used to define the Dockerfile as it prevents Compose files from being portable.

When set, `dockerfile_inline` attribute is not allowed and Compose rejects any Compose file having both set.

```yml
build:
  context: .
  dockerfile: webapp.Dockerfile
```

### [`dockerfile_inline`](#dockerfile_inline)

Requires: Docker Compose [2.17.0](https://github.com/docker/compose/releases/tag/v2.17.0) and later

`dockerfile_inline` defines the Dockerfile content as an inlined string in a Compose file. When set, the `dockerfile` attribute is not allowed and Compose rejects any Compose file having both set.

Use of YAML multi-line string syntax is recommended to define the Dockerfile content:

```yml
build:
  context: .
  dockerfile_inline: |
    FROM baseimage
    RUN some command
```

### [`entitlements`](#entitlements)

Requires: Docker Compose [2.27.1](https://github.com/docker/compose/releases/tag/v2.27.1) and later

`entitlements` defines extra privileged entitlements to be allowed during the build.

```yaml
entitlements:
  - network.host
  - security.insecure
```

### [`extra_hosts`](#extra_hosts)

`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [`extra_hosts`](https://docs.docker.com/reference/compose-file/services/#extra_hosts).

```yml
extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"
```

IPv6 addresses can be enclosed in square brackets, for example:

```yml
extra_hosts:
  - "myhostv6=[::1]"
```

The separator `=` is preferred, but `:` can also be used. Introduced in Docker Compose version [2.24.1](https://github.com/docker/compose/releases/tag/v2.24.1). For example:

```yml
extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"
```

Compose creates matching entry with the IP address and hostname in the container's network configuration, which means for Linux `/etc/hosts` will get extra lines:

```text
162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6
```

### [`isolation`](#isolation)

`isolation` specifies a build’s container isolation technology. Like [isolation](https://docs.docker.com/reference/compose-file/services/#isolation), supported values are platform specific.

### [`labels`](#labels)

`labels` add metadata to the resulting image. `labels` can be set either as an array or a map.

It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with other software.

```yml
build:
  context: .
  labels:
    com.example.description: "Accounting webapp"
    com.example.department: "Finance"
    com.example.label-with-empty-value: ""
```

```yml
build:
  context: .
  labels:
    - "com.example.description=Accounting webapp"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"
```

### [`network`](#network)

Set the network containers connect to for the `RUN` instructions during build.

```yaml
build:
  context: .
  network: host
```

```yaml
build:
  context: .
  network: custom_network_1
```

Use `none` to disable networking during build:

```yaml
build:
  context: .
  network: none
```

### [`no_cache`](#no_cache)

`no_cache` disables image builder cache and enforces a full rebuild from source for all image layers. This only applies to layers declared in the Dockerfile, referenced images can be retrieved from local image store whenever tag has been updated on registry (see [pull](#pull)).

### [`platforms`](#platforms)

`platforms` defines a list of target [platforms](https://docs.docker.com/reference/compose-file/services/#platform).

```yml
build:
  context: "."
  platforms:
    - "linux/amd64"
    - "linux/arm64"
```

When the `platforms` attribute is omitted, Compose includes the service's platform in the list of the default build target platforms.

When the `platforms` attribute is defined, Compose includes the service's platform, otherwise users won't be able to run images they built.

Composes reports an error in the following cases:

* When the list contains multiple platforms but the implementation is incapable of storing multi-platform images.

* When the list contains an unsupported platform.

  ```yml
  build:
    context: "."
    platforms:
      - "linux/amd64"
      - "unsupported/unsupported"
  ```

* When the list is non-empty and does not contain the service's platform.

  ```yml
  services:
    frontend:
      platform: "linux/amd64"
      build:
        context: "."
        platforms:
          - "linux/arm64"
  ```

### [`privileged`](#privileged)

Requires: Docker Compose [2.15.0](https://github.com/docker/compose/releases/tag/v2.15.0) and later

`privileged` configures the service image to build with elevated privileges. Support and actual impacts are platform specific.

```yml
build:
  context: .
  privileged: true
```

### [`provenance`](#provenance)

Requires: Docker Compose [2.39.0](https://github.com/docker/compose/releases/tag/v2.39.0) and later

`provenance` configures the builder to add a [provenance attestation](https://slsa.dev/provenance/v0.2#schema) to the published image.

The value can be either a boolean to enable/disable provenance attestation, or a key=value string to set provenance configuration. You can use this to select the level of detail to be included in the provenance attestation by setting the `mode` parameter.

```yaml
build:
  context: .
  provenance: true
```

```yaml
build:
  context: .
  provenance: mode=max
```

### [`pull`](#pull)

`pull` requires the image builder to pull referenced images (`FROM` Dockerfile directive), even if those are already available in the local image store.

### [`sbom`](#sbom)

Requires: Docker Compose [2.39.0](https://github.com/docker/compose/releases/tag/v2.39.0) and later

`sbom` configures the builder to add a [provenance attestation](https://slsa.dev/provenance/v0.2#schema) to the published image. The value can be either a boolean to enable/disable sbom attestation, or a key=value string to set SBOM generator configuration. This let you select an alternative SBOM generator image (see <https://github.com/moby/buildkit/blob/master/docs/attestations/sbom-protocol.md>)

```yaml
build:
  context: .
  sbom: true
```

```yaml
build:
  context: .
  sbom: generator=docker/scout-sbom-indexer:latest # Use an alternative SBOM generator
```

### [`secrets`](#secrets)

`secrets` grants access to sensitive data defined by [secrets](https://docs.docker.com/reference/compose-file/services/#secrets) on a per-service build basis. Two different syntax variants are supported: the short syntax and the long syntax.

Compose reports an error if the secret isn't defined in the [`secrets`](https://docs.docker.com/reference/compose-file/secrets/) section of this Compose file.

#### [Short syntax](#short-syntax)

The short syntax variant only specifies the secret name. This grants the container access to the secret and mounts it as read-only to `/run/secrets/<secret_name>` within the container. The source name and destination mountpoint are both set to the secret name.

The following example uses the short syntax to grant the build of the `frontend` service access to the `server-certificate` secret. The value of `server-certificate` is set to the contents of the file `./server.cert`.

```yml
services:
  frontend:
    build:
      context: .
      secrets:
        - server-certificate
secrets:
  server-certificate:
    file: ./server.cert
```

#### [Long syntax](#long-syntax)

The long syntax provides more granularity in how the secret is created within the service's containers.

* `source`: The name of the secret as it exists on the platform.
* `target`: The ID of the secret as declared in the Dockerfile. Defaults to `source` if not specified.
* `uid` and `gid`: The numeric uid or gid that owns the file within `/run/secrets/` in the service's task containers. Default value is `USER`.
* `mode`: The [permissions](https://wintelguy.com/permissions-calc.pl) for the file to be mounted in `/run/secrets/` in the service's task containers, in octal notation. Default value is world-readable permissions (mode `0444`). The writable bit must be ignored if set. The executable bit may be set.

The following example sets the name of the `server-certificate` secret file to `server.crt` within the container, sets the mode to `0440` (group-readable) and sets the user and group to `103`. The value of `server-certificate` secret is provided by the platform through a lookup and the secret lifecycle not directly managed by Compose.

```yml
services:
  frontend:
    build:
      context: .
      secrets:
        - source: server-certificate
          target: cert # secret ID in Dockerfile
          uid: "103"
          gid: "103"
          mode: 0440
secrets:
  server-certificate:
    external: true
```

```dockerfile
# Dockerfile
FROM nginx
RUN --mount=type=secret,id=cert,required=true,target=/root/cert ...
```

Service builds may be granted access to multiple secrets. Long and short syntax for secrets may be used in the same Compose file. Defining a secret in the top-level `secrets` must not imply granting any service build access to it. Such grant must be explicit within service specification as [secrets](https://docs.docker.com/reference/compose-file/services/#secrets) service element.

### [`ssh`](#ssh)

`ssh` defines SSH authentications that the image builder should use during image build (e.g., cloning private repository).

`ssh` property syntax can be either:

* `default`: Let the builder connect to the SSH-agent.
* `ID=path`: A key/value definition of an ID and the associated path. It can be either a [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) file, or path to ssh-agent socket.

```yaml
build:
  context: .
  ssh:
    - default # mount the default SSH agent
```

or

```yaml
build:
  context: .
  ssh: ["default"] # mount the default SSH agent
```

Using a custom id `myproject` with path to a local SSH key:

```yaml
build:
  context: .
  ssh:
    - myproject=~/.ssh/myproject.pem
```

The image builder can then rely on this to mount the SSH key during build.

For illustration, [SSH mounts](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/reference.md#run---mounttypessh) can be used to mount the SSH key set by ID and access a secured resource:

```console
RUN --mount=type=ssh,id=myproject git clone ...
```

### [`shm_size`](#shm_size)

`shm_size` sets the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker images. Specify as an integer value representing the number of bytes or as a string expressing a [byte value](https://docs.docker.com/reference/compose-file/extension/#specifying-byte-values).

```yml
build:
  context: .
  shm_size: "2gb"
```

```yaml
build:
  context: .
  shm_size: 10000000
```

### [`tags`](#tags)

`tags` defines a list of tag mappings that must be associated to the build image. This list comes in addition to the `image` [property defined in the service section](https://docs.docker.com/reference/compose-file/services/#image)

```yml
tags:
  - "myimage:mytag"
  - "registry/username/myrepos:my-other-tag"
```

### [`target`](#target)

`target` defines the stage to build as defined inside a multi-stage `Dockerfile`.

```yml
build:
  context: .
  target: prod
```

### [`ulimits`](#ulimits)

Requires: Docker Compose [2.23.1](https://github.com/docker/compose/releases/tag/v2.23.1) and later

`ulimits` overrides the default `ulimits` for a container. It's specified either as an integer for a single limit or as mapping for soft/hard limits.

```yml
services:
  frontend:
    build:
      context: .
      ulimits:
        nproc: 65535
        nofile:
          soft: 20000
          hard: 40000
```

----
url: https://docs.docker.com/extensions/extensions-sdk/architecture/security/
----

# Extension security

***

Table of contents

***

## [Extension capabilities](#extension-capabilities)

An extension can have the following optional parts:

* A user interface in HTML or JavaScript, displayed in Docker Desktop Dashboard
* A backend part that runs as a container
* Executables deployed on the host machine.

Extensions are executed with the same permissions as the Docker Desktop user. Extension capabilities include running any Docker commands (including running containers and mounting folders), running extension binaries, and accessing files on your machine that are accessible by the user running Docker Desktop. Note that extensions are not restricted to execute binaries that they list in the [host section](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#host-section) of the extension metadata: since these binaries can contain any code running as user, they can in turn execute any other commands as long as the user has rights to execute them.

The Extensions SDK provides a set of JavaScript APIs to invoke commands or invoke these binaries from the extension UI code. Extensions can also provide a backend part that starts a long-lived running container in the background.

> Important
>
> Make sure you trust the publisher or author of the extension when you install it, as the extension has the same access rights as the user running Docker Desktop.

----
url: https://docs.docker.com/reference/api/extensions-sdk/Host/
----

# Interface: Host

***

Table of contents

***

**`Since`**

0.2.0

## [Methods](#methods)

### [openExternal](#openexternal)

▸ **openExternal**(`url`): `void`

Opens an external URL with the system default browser.

**`Since`**

0.2.0

```typescript
ddClient.host.openExternal("https://docker.com");
```

#### [Parameters](#parameters)

| Name  | Type     | Description                                                               |
| ----- | -------- | ------------------------------------------------------------------------- |
| `url` | `string` | The URL the browser will open (must have the protocol `http` or `https`). |

#### [Returns](#returns)

`void`

## [Properties](#properties)

### [platform](#platform)

• **platform**: `string`

Returns a string identifying the operating system platform. See <https://nodejs.org/api/os.html#osplatform>

**`Since`**

0.2.2

***

### [arch](#arch)

• **arch**: `string`

Returns the operating system CPU architecture. See <https://nodejs.org/api/os.html#osarch>

**`Since`**

0.2.2

***

### [hostname](#hostname)

• **hostname**: `string`

Returns the host name of the operating system. See <https://nodejs.org/api/os.html#oshostname>

**`Since`**

0.2.2

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/create/
----

# docker mcp catalog create

***

| Description | Create a new catalog from a profile, legacy catalog, or community registry                                                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Usage       | `docker mcp catalog create <oci-reference> [--server <ref1> --server <ref2> ...] [--from-profile <profile-id>] [--from-legacy-catalog <url>] [--from-community-registry <hostname>] [--title <title>]` |

## [Description](#description)

Create a new catalog from a profile, legacy catalog, or community registry

## [Options](#options)

| Option                      | Default | Description                                                                                                                                                                                                        |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--from-community-registry` |         | Community registry hostname to fetch servers from (e.g. registry.modelcontextprotocol.io)                                                                                                                          |
| `--from-legacy-catalog`     |         | Legacy catalog URL to create the catalog from                                                                                                                                                                      |
| `--from-profile`            |         | Profile ID to create the catalog from                                                                                                                                                                              |
| `--server`                  |         | Server to include specified with a URI: https\:// (MCP Registry reference) or docker:// (Docker Image reference) or catalog:// (Catalog reference) or file:// (Local file path). Can be specified multiple times.  |
| `--title`                   |         | Title of the catalog                                                                                                                                                                                               |

----
url: https://docs.docker.com/guides/testcontainers-nodejs-getting-started/create-project/
----

# Create the Node.js project

***

Table of contents

***

## [Initialize the project](#initialize-the-project)

Create a new Node.js project:

```console
$ npm init -y
```

Add `pg`, `jest`, and `@testcontainers/postgresql` as dependencies:

```console
$ npm install pg --save
$ npm install jest @testcontainers/postgresql --save-dev
```

## [Implement the customer repository](#implement-the-customer-repository)

Create `src/customer-repository.js` with functions to manage customers in PostgreSQL:

```javascript
async function createCustomerTable(client) {
  const sql =
    "CREATE TABLE IF NOT EXISTS customers (id INT NOT NULL, name VARCHAR NOT NULL, PRIMARY KEY (id))";
  await client.query(sql);
}

async function createCustomer(client, customer) {
  const sql = "INSERT INTO customers (id, name) VALUES($1, $2)";
  await client.query(sql, [customer.id, customer.name]);
}

async function getCustomers(client) {
  const sql = "SELECT * FROM customers";
  const result = await client.query(sql);
  return result.rows;
}

module.exports = { createCustomerTable, createCustomer, getCustomers };
```

The module provides three functions:

* `createCustomerTable()` creates the `customers` table if it doesn't exist.
* `createCustomer()` inserts a customer record.
* `getCustomers()` fetches all customer records.

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-nodejs-getting-started/write-tests/)

----
url: https://docs.docker.com/reference/cli/docker/compose/attach/
----

# docker compose attach

***

| Description | Attach local standard input, output, and error streams to a service's running container |
| ----------- | --------------------------------------------------------------------------------------- |
| Usage       | `docker compose attach [OPTIONS] SERVICE`                                               |

## [Description](#description)

Attach local standard input, output, and error streams to a service's running container

## [Options](#options)

| Option          | Default | Description                                               |
| --------------- | ------- | --------------------------------------------------------- |
| `--detach-keys` |         | Override the key sequence for detaching from a container. |
| `--index`       |         | index of the container if service has multiple replicas.  |
| `--no-stdin`    |         | Do not attach STDIN                                       |
| `--sig-proxy`   | `true`  | Proxy all received signals to the process                 |

----
url: https://docs.docker.com/reference/cli/sbx/policy/ls/
----

# sbx policy ls

| Description | List sandbox policy rules         |
| ----------- | --------------------------------- |
| Usage       | `sbx policy ls [SANDBOX] [flags]` |

## [Description](#description)

List all active policy rules.

Displays the provenance, scope, rule name (or ID if no name is set), type, decision (allow/deny), and the associated resources for each rule.

When SANDBOX is specified, only policies that apply to that sandbox are shown (global rules plus rules scoped to that sandbox).

## [Options](#options)

| Option   | Default | Description                                                 |
| -------- | ------- | ----------------------------------------------------------- |
| `--type` | `all`   | Filter policies by type: "all" or "network" (default "all") |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# List all policies
sbx policy ls

# List only network policies
sbx policy ls --type network

# List policies that apply to a specific sandbox
sbx policy ls my-sandbox
```

----
url: https://docs.docker.com/reference/cli/docker/buildx/history/logs/
----

# docker buildx history logs

***

| Description | Print the logs of a build record             |
| ----------- | -------------------------------------------- |
| Usage       | `docker buildx history logs [OPTIONS] [REF]` |

## [Description](#description)

Print the logs for a completed build. The output appears in the same format as `--progress=plain`, showing the full logs for each step.

By default, this shows logs for the most recent build on the current builder.

You can also specify an earlier build using an offset. For example:

* `^1` shows logs for the build before the most recent
* `^2` shows logs for the build two steps back

## [Options](#options)

| Option                    | Default | Description                                       |
| ------------------------- | ------- | ------------------------------------------------- |
| [`--progress`](#progress) | `plain` | Set type of progress output (plain, rawjson, tty) |

## [Examples](#examples)

### [Print logs for the most recent build](#print-logs-for-the-most-recent-build)

```console
$ docker buildx history logs
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 31B done
#1 DONE 0.0s
#2 [internal] load .dockerignore
#2 transferring context: 2B done
#2 DONE 0.0s
...
```

By default, this shows logs for the most recent build on the current builder.

### [Print logs for a specific build](#print-logs-for-a-specific-build)

To print logs for a specific build, use a build ID or offset:

```console
# Using a build ID
docker buildx history logs qu2gsuo8ejqrwdfii23xkkckt

# Or using a relative offset
docker buildx history logs ^1
```

### [Set type of progress output (--progress)](#progress)

```console
$ docker buildx history logs ^1 --progress rawjson
{"id":"buildx_step_1","status":"START","timestamp":"2024-05-01T12:34:56.789Z","detail":"[internal] load build definition from Dockerfile"}
{"id":"buildx_step_1","status":"COMPLETE","timestamp":"2024-05-01T12:34:57.001Z","duration":212000000}
...
```

----
url: https://docs.docker.com/guides/testcontainers-java-getting-started/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

Run the tests using Maven:

```console
$ mvn test
```

You can see in the logs that Testcontainers pulls the Postgres Docker image from Docker Hub (if not already available locally), starts the container, and runs the test.

Writing an integration test using Testcontainers works like writing a unit test that you can run from your IDE. Your teammates can clone the project and run tests without installing Postgres on their machines.

## [Summary](#summary)

The Testcontainers for Java library helps you write integration tests using the same type of database (Postgres) that you use in production, instead of mocks. Because you aren't using mocks and instead talk to real services, you're free to refactor code and still verify that the application works as expected.

In addition to Postgres, Testcontainers provides dedicated modules for many SQL databases, NoSQL databases, messaging queues, and more. You can use Testcontainers to run any containerized dependency for your tests.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testcontainers container lifecycle management using JUnit 5](https://testcontainers.com/guides/testcontainers-container-lifecycle/)
* [Replace H2 with a real database for testing](https://testcontainers.com/guides/replace-h2-with-real-database-for-testing/)
* [Getting started with Testcontainers in a Java Spring Boot project](https://testcontainers.com/guides/testing-spring-boot-rest-api-using-testcontainers/)

----
url: https://docs.docker.com/reference/cli/docker/scout/cache/prune/
----

# docker scout cache prune

***

| Description | Remove temporary or cached data |
| ----------- | ------------------------------- |
| Usage       | `docker scout cache prune`      |

## [Description](#description)

The `docker scout cache prune` command removes temporary data and SBOM cache.

By default, `docker scout cache prune` only deletes temporary data. To delete temporary data and clear the SBOM cache, use the `--sboms` flag.

## [Options](#options)

| Option        | Default | Description                    |
| ------------- | ------- | ------------------------------ |
| `-f, --force` |         | Do not prompt for confirmation |
| `--sboms`     |         | Prune cached SBOMs             |

## [Examples](#examples)

### [Delete temporary data](#delete-temporary-data)

```console
$ docker scout cache prune
? Are you sure to delete all temporary data? Yes
    ✓ temporary data deleted
```

### [Delete temporary and cache data](#delete-temporary-and-cache-data)

```console
$ docker scout cache prune --sboms
? Are you sure to delete all temporary data and all cached SBOMs? Yes
    ✓ temporary data deleted
    ✓ cached SBOMs deleted
```

----
url: https://docs.docker.com/docker-hub/repos/manage/builds/manage-builds/
----

# Manage autobuilds

***

Table of contents

***

> Warning
>
> Docker Hub Automated Builds is a deprecated feature. It will be fully retired on April 1, 2027.

> Note
>
> Automated builds require a Docker Pro, Team, or Business subscription.

## [Cancel or retry a build](#cancel-or-retry-a-build)

While a build is in queue or running, a **Cancel** icon appears next to its build report link on the **General** tab and on the **Builds** tab. You can also select **Cancel** on the **Build report** page, or from the **Timeline** tab's logs display for the build.

## [Check your active builds](#check-your-active-builds)

A summary of a repository's builds appears both on the repository **General** tab, and in the **Builds** tab. The **Builds** tab also displays a color coded bar chart of the build queue times and durations. Both views display the pending, in progress, successful, and failed builds for any tag of the repository.

From either location, you can select a build job to view its build report. The build report shows information about the build job. This includes the source repository and branch, or tag, the build logs, the build duration, creation time and location, and the user account the build occurred in.

> Note
>
> You can now view the progress of your builds every 30 seconds when you refresh the **Builds** page. With the in-progress build logs, you can debug your builds before they're finished.

## [Disable an automated build](#disable-an-automated-build)

Automated builds are enabled per branch or tag, and can be disabled and re-enabled. You might do this when you want to only build manually for a while, for example when you are doing major refactoring in your code. Disabling autobuilds doesn't disable [autotests](https://docs.docker.com/docker-hub/repos/manage/builds/automated-testing/).

To disable an automated build:

1. In [Docker Hub](https://hub.docker.com), go to **My Hub** > **Repositories**, select a repository, and select the **Builds** tab.

2. Select **Configure automated builds** to edit the repository's build settings.

3. In the **Build Rules** section, locate the branch or tag you no longer want to automatically build.

4. Select the **Autobuild** toggle next to the configuration line. When disabled the toggle is gray.

5. Select **Save**.

----
url: https://docs.docker.com/guides/python/containerize/
----

# Containerize a Python application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Overview](#overview)

This section walks you through containerizing and running a Python application.

## [Get the sample application](#get-the-sample-application)

The sample application uses the popular [FastAPI](https://fastapi.tiangolo.com) framework.

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/estebanx64/python-docker-example && cd python-docker-example
```

## [Create Docker assets](#create-docker-assets)

Now that you have an application, you can create the necessary Docker assets to containerize your application.

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

Before creating your Dockerfile, you need to choose a base image. You can use the [Python Docker Official Image](https://hub.docker.com/_/python), or a [Docker Hardened Image (DHI)](https://hub.docker.com/hardened-images/catalog/dhi/python).

Docker Hardened Images (DHIs) are minimal, secure, and production-ready base images maintained by Docker. They help reduce vulnerabilities and simplify compliance. For more details, see [Docker Hardened Images](/dhi/).

Create the following files in your project directory.

Create a file named `Dockerfile` with the following contents.

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1

# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Dockerfile reference guide at
# https://docs.docker.com/go/dockerfile-reference/

# This Dockerfile uses Python Docker Official Image
ARG PYTHON_VERSION=3.12
FROM python:${PYTHON_VERSION}-slim

# Prevents Python from writing pyc files.
ENV PYTHONDONTWRITEBYTECODE=1

# Keeps Python from buffering stdout and stderr to avoid situations where
# the application crashes without emitting any logs due to buffering.
ENV PYTHONUNBUFFERED=1

WORKDIR /app

# Create a non-privileged user that the app will run under.
# See https://docs.docker.com/go/dockerfile-user-best-practices/
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser

# Download dependencies as a separate step to take advantage of Docker's caching.
# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds.
# Leverage a bind mount to requirements.txt to avoid having to copy them into
# into this layer.
RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    python -m pip install -r requirements.txt

# Switch to the non-privileged user to run the application.
USER appuser

# Copy the source code into the container.
COPY . .

# Expose the port that the application listens on.
EXPOSE 8000

# Run the application.
CMD ["python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"]
```

Create a file named `compose.yaml` with the following contents.

compose.yaml

```yaml
# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Docker Compose reference guide at
# https://docs.docker.com/go/compose-spec-reference/

# Here the instructions define your application as a service called "server".
# This service is built from the Dockerfile in the current directory.
# You can add other services your application may depend on here, such as a
# database or a cache. For examples, see the Awesome Compose repository:
# https://github.com/docker/awesome-compose
services:
  server:
    build:
      context: .
    ports:
      - 8000:8000
```

Create a file named `.dockerignore` with the following contents.

.dockerignore

```text
# Include any files or directories that you don't want to be copied to your
# container here (e.g., local build artifacts, temporary files, etc.).
#
# For more help, visit the .dockerignore file reference guide at
# https://docs.docker.com/go/build-context-dockerignore/

**/.DS_Store
**/__pycache__
**/.venv
**/.classpath
**/.dockerignore
**/.env
**/.git
**/.gitignore
**/.project
**/.settings
**/.toolstarget
**/.vs
**/.vscode
**/*.*proj.user
**/*.dbmdl
**/*.jfm
**/bin
**/charts
**/docker-compose*
**/compose.y*ml
**/Dockerfile*
**/node_modules
**/npm-debug.log
**/obj
**/secrets.dev.yaml
**/values.dev.yaml
LICENSE
README.md
```

Create a file named `.gitignore` with the following contents.

.gitignore

```text
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/

# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
```

Docker Hardened Images (DHIs) are available for Python in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/python). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide.

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Pull the Python DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/python:3.12.12-debian13-fips-dev
   ```

Create a file named `Dockerfile` with the following contents.

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1

# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Dockerfile reference guide at
# https://docs.docker.com/go/dockerfile-reference/

# This Dockerfile uses Docker Hardened Images (DHI) for enhanced security.
# For more information, see https://docs.docker.com/dhi/
ARG PYTHON_VERSION=3.12.12-debian13-fips-dev
FROM dhi.io/python:${PYTHON_VERSION}

# Prevents Python from writing pyc files.
ENV PYTHONDONTWRITEBYTECODE=1

# Keeps Python from buffering stdout and stderr to avoid situations where
# the application crashes without emitting any logs due to buffering.
ENV PYTHONUNBUFFERED=1

#Add dependencies for adduser
RUN apt update -y && apt install adduser -y

WORKDIR /app

# Create a non-privileged user that the app will run under.
# See https://docs.docker.com/go/dockerfile-user-best-practices/
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser

# Download dependencies as a separate step to take advantage of Docker's caching.
# Leverage a cache mount to /root/.cache/pip to speed up subsequent builds.
# Leverage a bind mount to requirements.txt to avoid having to copy them into
# into this layer.
RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    python -m pip install -r requirements.txt

# Switch to the non-privileged user to run the application.
USER appuser

# Copy the source code into the container.
COPY . .

# Expose the port that the application listens on.
EXPOSE 8000

# Run the application.
CMD ["python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"]
```

Create a file named `compose.yaml` with the following contents.

compose.yaml

```yaml
# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Docker Compose reference guide at
# https://docs.docker.com/go/compose-spec-reference/

# Here the instructions define your application as a service called "server".
# This service is built from the Dockerfile in the current directory.
# You can add other services your application may depend on here, such as a
# database or a cache. For examples, see the Awesome Compose repository:
# https://github.com/docker/awesome-compose
services:
  server:
    build:
      context: .
    ports:
      - 8000:8000
```

Create a file named `.dockerignore` with the following contents.

.dockerignore

```text
# Include any files or directories that you don't want to be copied to your
# container here (e.g., local build artifacts, temporary files, etc.).
#
# For more help, visit the .dockerignore file reference guide at
# https://docs.docker.com/go/build-context-dockerignore/

**/.DS_Store
**/__pycache__
**/.venv
**/.classpath
**/.dockerignore
**/.env
**/.git
**/.gitignore
**/.project
**/.settings
**/.toolstarget
**/.vs
**/.vscode
**/*.*proj.user
**/*.dbmdl
**/*.jfm
**/bin
**/charts
**/docker-compose*
**/compose.y*ml
**/Dockerfile*
**/node_modules
**/npm-debug.log
**/obj
**/secrets.dev.yaml
**/values.dev.yaml
LICENSE
README.md
```

Create a file named `.gitignore` with the following contents.

.gitignore

```text
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/

# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
```

You should now have the following contents in your `python-docker-example` directory.

```text
├── python-docker-example/
│ ├── app.py
│ ├── requirements.txt
│ ├── .dockerignore
│ ├── .gitignore
│ ├── compose.yaml
│ ├── Dockerfile
│ └── README.md
```

To learn more about the files, see the following:

* [Dockerfile](https://docs.docker.com/reference/dockerfile/)
* [.dockerignore](https://docs.docker.com/reference/dockerfile/#dockerignore-file)
* [.gitignore](https://git-scm.com/docs/gitignore)
* [compose.yaml](https://docs.docker.com/reference/compose-file/)

## [Run the application](#run-the-application)

Inside the `python-docker-example` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:8000>. You should see a simple FastAPI application.

In the terminal, press `ctrl`+`c` to stop the application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `python-docker-example` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:8000>.

To see the OpenAPI docs you can go to <http://localhost:8000/docs>.

You should see a simple FastAPI application.

In the terminal, run the following command to stop the application.

```console
$ docker compose down
```

For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

## [Summary](#summary)

In this section, you learned how you can containerize and run your Python application using Docker.

Related information:

* [Docker Compose overview](https://docs.docker.com/compose/)

## [Next steps](#next-steps)

In the next section, you'll take a look at how to set up a local development environment using Docker containers.

[Use containers for Python development »](https://docs.docker.com/guides/python/develop/)

----
url: https://docs.docker.com/build/policies/validate-images/
----

# Validating image inputs

***

Table of contents

***

Container images are the most common build inputs. Every `FROM` instruction pulls an image, and `COPY --from` references pull additional images. Validating these images protects your build supply chain from compromised registries, unexpected updates, and unauthorized base images.

This guide teaches you to write policies that validate image inputs, progressing from basic allowlisting to advanced attestation checks.

## [Prerequisites](#prerequisites)

You should understand the policy basics from the [Introduction](https://docs.docker.com/build/policies/intro/): creating policy files, basic Rego syntax, and how policies evaluate during builds.

## [What are image inputs?](#what-are-image-inputs)

Image inputs come from two Dockerfile instructions:

```dockerfile
# FROM instructions
FROM alpine:3.22
FROM golang:1.25-alpine AS builder

# COPY --from references
COPY --from=builder /app /app
COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf
```

Each of these references triggers a policy evaluation. Your policy can inspect image metadata, verify attestations, and enforce constraints before the build proceeds.

## [Allowlist specific repositories](#allowlist-specific-repositories)

The simplest image policy restricts which repositories can be used. This prevents developers from using arbitrary images that haven't been vetted.

Create a policy that only allows Alpine:

Dockerfile.rego

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.image.repo == "alpine"
}

decision := {"allow": allow}
```

This policy:

* Denies all inputs by default
* Allows local build context
* Allows any image from the `alpine` repository (any tag or digest)

Test it with a Dockerfile:

Dockerfile

```dockerfile
FROM alpine
RUN echo "hello"
```

```console
$ docker build .
```

The build succeeds. Try changing to `FROM ubuntu`:

```console
$ docker build .
```

The build fails because `ubuntu` doesn't match the allowed repository.

## [Compare semantic versions](#compare-semantic-versions)

Restrict images to specific version ranges using Rego's `semver` functions:

```rego
package docker

default allow := false

allow if input.local

# Allow Go 1.21 or newer
allow if {
  input.image.repo == "golang"
  semver.is_valid(input.image.tag)
  semver.compare(input.image.tag, "1.21.0") >= 0
}

decision := {"allow": allow}
```

The `semver.compare(a, b)` function compares semantic versions and returns:

* `-1` if version `a` is less than `b`
* `0` if versions are equal
* `1` if version `a` is greater than `b`

Use `semver.is_valid()` to check if a tag is a valid semantic version before comparing.

Restrict to specific version ranges:

```rego
allow if {
  input.image.repo == "node"
  version := input.image.tag
  semver.is_valid(version)
  semver.compare(version, "20.0.0") >= 0  # 20.0.0 or newer
  semver.compare(version, "21.0.0") < 0   # older than 21.0.0
}
```

This allows only Node.js 20.x versions. The pattern works for any image using semantic versioning.

These `semver` functions are standard Rego built-ins documented in the [OPA policy reference](https://www.openpolicyagent.org/docs/latest/policy-reference/#semver).

## [Require digest references](#require-digest-references)

Tags like `alpine:3.22` can change - someone could push a new image with the same tag. Digests like `alpine@sha256:abc123...` are immutable.

### [Requiring users to provide digests](#requiring-users-to-provide-digests)

You can require that users always specify digests in their Dockerfiles:

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.image.isCanonical
}

decision := {"allow": allow}
```

The `isCanonical` field is `true` when the user's reference includes a digest. This policy would allow:

```dockerfile
FROM alpine@sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412
```

But reject tag-only references like `FROM alpine:3.22`.

### [Pinning to specific digests](#pinning-to-specific-digests)

Alternatively (or additionally), you can validate that an image's actual digest matches a specific value, regardless of how the user wrote the reference:

```rego
allow if {
  input.image.repo == "alpine"
  input.image.checksum == "sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412"
}

decision := {"allow": allow}
```

This checks the actual content digest of the pulled image. It would allow both:

```dockerfile
FROM alpine:3.22
FROM alpine@sha256:4b7ce...
```

As long as the resolved image has the specified digest. This is useful for pinning critical base images to known-good versions.

## [Restrict registries](#restrict-registries)

Control which registries your builds can pull from. This helps enforce corporate policies or restrict to trusted sources.

```rego
package docker

default allow := false

allow if input.local

# Allow Docker Hub images
allow if {
  input.image.host == "docker.io"  # Docker Hub
  input.image.repo == "alpine"
}

# Allow images from internal registry
allow if {
  input.image.host == "registry.company.com"
}

decision := {"allow": allow}
```

The `host` field contains the registry hostname. Docker Hub images use `"docker.io"` as the host value. Test with:

```dockerfile
FROM alpine                                    # Allowed (Docker Hub)
FROM registry.company.com/myapp:latest         # Allowed (company registry)
FROM ghcr.io/someorg/image:latest              # Denied (wrong registry)
```

Use `fullRepo` when you need the complete path including registry:

```rego
allow if {
  input.image.fullRepo == "docker.io/library/alpine"
}
```

## [Validate platform constraints](#validate-platform-constraints)

Multi-architecture images support different operating systems and CPU architectures. You can restrict builds to specific platforms:

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.image.os == "linux"
  input.image.arch in ["amd64", "arm64"]
}

decision := {"allow": allow}
```

This policy:

* Defines supported architectures in a list
* Checks `input.image.os` matches Linux
* Verifies `input.image.arch` is in the supported list

The `os` and `arch` fields come from the image manifest, reflecting the actual image platform. This works with Docker's automatic platform selection - policies validate what Buildx resolves, not what you specify.

## [Inspect image metadata](#inspect-image-metadata)

Images contain metadata like environment variables, labels, and working directories. You can validate these to ensure images meet requirements.

Check for specific environment variables:

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.image.repo == "golang"
  input.image.workingDir == "/go"
  some ver in input.image.env
  startswith(ver, "GOLANG_VERSION=")
  some toolchain in input.image.env
  toolchain == "GOTOOLCHAIN=local"
}

decision := {"allow": allow}
```

This policy validates the official Go image by checking:

* The working directory is `/go`
* The environment has `GOLANG_VERSION` set
* The environment includes `GOTOOLCHAIN=local`

The `input.image.env` field is an array of strings in `KEY=VALUE` format. Use Rego's `some` iteration to search the array.

Check image labels:

```rego
allow if {
  input.image.labels["org.opencontainers.image.vendor"] == "Example Corp"
  input.image.labels["org.opencontainers.image.version"] != ""
}
```

The `labels` field is a map, so you access values with bracket notation.

## [Require attestations and provenance](#require-attestations-and-provenance)

Modern images include [attestations](/build/metadata/attestations/): machine-readable metadata about how the image was built. [Provenance](/build/metadata/attestations/slsa-provenance/) attestations describe the build process, and [SBOMs](/build/metadata/attestations/sbom/) list the software inside.

Require provenance:

```rego
package docker

default allow := false

allow if input.local

allow if {
  input.image.hasProvenance
}

decision := {"allow": allow}
```

The `hasProvenance` field is `true` when the image has provenance or SBOM [attestations](https://docs.docker.com/build/metadata/attestations/).

## [Verify GitHub Actions signatures](#verify-github-actions-signatures)

For images built with GitHub Actions, verify they came from trusted workflows by inspecting signature metadata:

```rego
allow if {
  input.image.repo == "myapp"
  input.image.hasProvenance
  some sig in input.image.signatures
  valid_github_signature(sig)
}

# Helper to validate GitHub Actions signature
valid_github_signature(sig) if {
  sig.signer.certificateIssuer == "CN=sigstore-intermediate,O=sigstore.dev"
  sig.signer.issuer == "https://token.actions.githubusercontent.com"
  startswith(sig.signer.buildSignerURI, "https://github.com/myorg/")
  sig.signer.runnerEnvironment == "github-hosted"
}

decision := {"allow": allow}
```

This pattern works with any GitHub Actions workflow using Sigstore keyless signing. The signature metadata provides cryptographic proof of the build's origin. For complete signature verification examples, see [Example policies](https://docs.docker.com/build/policies/examples/).

## [Combine multiple checks](#combine-multiple-checks)

Real policies often combine several checks. Multiple conditions in one `allow` rule means AND - all must be true:

```rego
package docker

default allow := false

allow if input.local

# Production images need everything
allow if {
  input.image.repo == "alpine"
  input.image.isCanonical
  input.image.hasProvenance
}

decision := {"allow": allow}
```

Multiple `allow` rules means OR - any rule can match:

```rego
package docker

default allow := false

allow if input.local

# Allow Alpine with strict checks
allow if {
  input.image.repo == "alpine"
  input.image.isCanonical
}

# Allow Go with different checks
allow if {
  input.image.repo == "golang"
  input.image.workingDir == "/go"
}

decision := {"allow": allow}
```

Use this pattern to apply different requirements to different base images.

## [Next steps](#next-steps)

You now understand how to validate container images in build policies. To continue learning:

* Learn [Git repository validation](https://docs.docker.com/build/policies/validate-git/) for source code inputs
* Browse [Example policies](https://docs.docker.com/build/policies/examples/) for complete policy patterns
* Read [Built-in functions](https://docs.docker.com/build/policies/built-ins/) for signature verification and attestation checking
* Check the [Input reference](https://docs.docker.com/build/policies/inputs/) for all available image fields

----
url: https://docs.docker.com/admin/company/manage/organizations/
----

# Manage company organizations

***

Table of contents

***

Subscription: Business

For: Administrators

Learn to manage the organizations in a company using the Docker Admin Console.

## [View all organizations](#view-all-organizations)

1. Sign in to the [Docker Home](https://app.docker.com) and choose your company.
2. Select **Admin Console**, then **Organizations**.

The **Organizations** view displays all organizations under your company.

## [Add seats to an organization](#add-seats-to-an-organization)

If you have a self-serve subscription that has no pending subscription changes, you can add seats using Docker Home. For more information about adding seats, see [Manage seats](https://docs.docker.com/subscription/manage-seats/#add-seats-to-your-subscription).

If you have a sales-assisted subscription, you must contact Docker support or sales to add seats.

## [Add organizations to a company](#add-organizations-to-a-company)

To add an organization to a company, ensure the following:

* You are a company owner.
* You are an organization owner of the organization you want to add.
* The organization has a Docker Business subscription.
* There’s no limit to how many organizations can exist under a company.

> Important
>
> Once you add an organization to a company, you can't remove it from the company.

1. Sign in to [Docker Home](https://app.docker.com) and select your company from the top-left account drop-down.
2. Select **Admin Console**, then **Organizations**.
3. Select **Add organization**.
4. Choose the organization you want to add from the drop-down menu.
5. Select **Add organization** to confirm.

## [Manage an organization](#manage-an-organization)

1. Sign in to [Docker Home](https://app.docker.com) and select your company from the top-left account drop-down.
2. Select **Admin Console**, then **Organizations**.
3. Select the organization you want to manage.

For more details about managing an organization, see [Organization administration](https://docs.docker.com/admin/organization/).

## [More resources](#more-resources)

* [Video: Managing a company and nested organizations](https://youtu.be/XZ5_i6qiKho?feature=shared\&t=229)
* [Video: Adding nested organizations to a company](https://youtu.be/XZ5_i6qiKho?feature=shared\&t=454)

----
url: https://docs.docker.com/guides/testcontainers-java-mockserver/
----

# Testing REST API integrations using MockServer

Table of contents

***

Learn how to create a Spring Boot application that integrates with external REST APIs, then test those integrations using Testcontainers and MockServer.

**Time to complete** 20 minutes

In this guide, you will learn how to:

* Create a Spring Boot application that talks to external REST APIs
* Test external API integrations using the Testcontainers MockServer module

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-mockserver/create-project/)

   Set up a Spring Boot project with an external REST API integration using declarative HTTP clients.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-mockserver/write-tests/)

   Test external REST API integrations using the Testcontainers MockServer module and REST Assured.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-mockserver/run-tests/)

   Run your Testcontainers MockServer integration tests and explore next steps.

----
url: https://docs.docker.com/engine/logging/
----

# View container logs

***

Table of contents

***

The `docker logs` command shows information logged by a running container. The `docker service logs` command shows information logged by all containers participating in a service. The information that's logged and the format of the log depends almost entirely on the container's endpoint command.

By default, `docker logs` or `docker service logs` shows the command's output just as it would appear if you ran the command interactively in a terminal. Unix and Linux commands typically open three I/O streams when they run, called `STDIN`, `STDOUT`, and `STDERR`. `STDIN` is the command's input stream, which may include input from the keyboard or input from another command. `STDOUT` is usually a command's normal output, and `STDERR` is typically used to output error messages. By default, `docker logs` shows the command's `STDOUT` and `STDERR`. To read more about I/O and Linux, see the [Linux Documentation Project article on I/O redirection](https://tldp.org/LDP/abs/html/io-redirection.html).

In some cases, `docker logs` may not show useful information unless you take additional steps.

* If you use a [logging driver](https://docs.docker.com/engine/logging/configure/) which sends logs to a file, an external host, a database, or another logging back-end, and have ["dual logging"](https://docs.docker.com/engine/logging/dual-logging/) disabled, `docker logs` may not show useful information.
* If your image runs a non-interactive process such as a web server or a database, that application may send its output to log files instead of `STDOUT` and `STDERR`.

In the first case, your logs are processed in other ways and you may choose not to use `docker logs`. In the second case, the official `nginx` image shows one workaround, and the official Apache `httpd` image shows another.

The official `nginx` image creates a symbolic link from `/var/log/nginx/access.log` to `/dev/stdout`, and creates another symbolic link from `/var/log/nginx/error.log` to `/dev/stderr`, overwriting the log files and causing logs to be sent to the relevant special device instead. See the [Dockerfile](https://github.com/nginxinc/docker-nginx/blob/8921999083def7ba43a06fabd5f80e4406651353/mainline/jessie/Dockerfile#L21-L23).

The official `httpd` driver changes the `httpd` application's configuration to write its normal output directly to `/proc/self/fd/1` (which is `STDOUT`) and its errors to `/proc/self/fd/2` (which is `STDERR`). See the [Dockerfile](https://github.com/docker-library/httpd/blob/b13054c7de5c74bbaa6d595dbe38969e6d4f860c/2.2/Dockerfile#L72-L75).

## [Next steps](#next-steps)

* Configure [logging drivers](https://docs.docker.com/engine/logging/configure/).
* Write a [Dockerfile](https://docs.docker.com/reference/dockerfile/).

----
url: https://docs.docker.com/reference/cli/docker/mcp/tools/
----

# docker mcp tools

***

| Description | Manage tools |
| ----------- | ------------ |

## [Description](#description)

Manage tools

## [Options](#options)

| Option          | Default | Description                                |
| --------------- | ------- | ------------------------------------------ |
| `--format`      | `list`  | Output format (json\|list)                 |
| `--gateway-arg` |         | Additional arguments passed to the gateway |
| `--verbose`     |         | Verbose output                             |
| `--version`     | `2`     | Version of the gateway                     |

## [Subcommands](#subcommands)

| Command                                                                                       | Description    |
| --------------------------------------------------------------------------------------------- | -------------- |
| [`docker mcp tools call`](https://docs.docker.com/reference/cli/docker/mcp/tools/call/)       | Call a tool    |
| [`docker mcp tools count`](https://docs.docker.com/reference/cli/docker/mcp/tools/count/)     | Count tools    |
| [`docker mcp tools inspect`](https://docs.docker.com/reference/cli/docker/mcp/tools/inspect/) | Inspect a tool |
| [`docker mcp tools list`](https://docs.docker.com/reference/cli/docker/mcp/tools/list/)       | List tools     |
| [`docker mcp tools ls`](https://docs.docker.com/reference/cli/docker/mcp/tools/ls/)           | List tools     |

----
url: https://docs.docker.com/extensions/extensions-sdk/dev/api/overview/
----

# Extension UI API

***

***

The extensions UI runs in a sandboxed environment and doesn't have access to any electron or nodejs APIs.

The extension UI API provides a way for the frontend to perform different actions and communicate with the Docker Desktop dashboard or the underlying system.

JavaScript API libraries, with Typescript support, are available in order to get all the API definitions in to your extension code.

* [@docker/extension-api-client](https://www.npmjs.com/package/@docker/extension-api-client) gives access to the extension API entrypoint `DockerDesktopClient`.
* [@docker/extension-api-client-types](https://www.npmjs.com/package/@docker/extension-api-client-types) can be added as a dev dependency in order to get types auto-completion in your IDE.

```Typescript
import { createDockerDesktopClient } from '@docker/extension-api-client';

export function App() {
  // obtain Docker Desktop client
  const ddClient = createDockerDesktopClient();
  // use ddClient to perform extension actions
}
```

The `ddClient` object gives access to various APIs:

* [Extension Backend](https://docs.docker.com/extensions/extensions-sdk/dev/api/backend/)
* [Docker](https://docs.docker.com/extensions/extensions-sdk/dev/api/docker/)
* [Dashboard](https://docs.docker.com/extensions/extensions-sdk/dev/api/dashboard/)
* [Navigation](https://docs.docker.com/extensions/extensions-sdk/dev/api/dashboard-routes-navigation/)

See also the [Extensions API reference](https://docs.docker.com/reference/api/extensions-sdk/).

----
url: https://docs.docker.com/reference/compose-file/
----

# Compose file reference

***

***

> **New to Docker Compose?**
>
> Find more information about the [key features and use cases of Docker Compose](https://docs.docker.com/compose/intro/features-uses/) or [try the quickstart guide](https://docs.docker.com/compose/gettingstarted/).

The Compose Specification is the latest and recommended version of the Compose file format. It helps you define a [Compose file](https://docs.docker.com/compose/intro/compose-application-model/) which is used to configure your Docker application’s services, networks, volumes, and more.

Legacy versions 2.x and 3.x of the Compose file format were merged into the Compose Specification. It is implemented in versions 1.27.0 and above (also known as Compose v2) of the Docker Compose CLI.

The Compose Specification on Docker Docs is the Docker Compose implementation. If you wish to implement your own version of the Compose Specification, see the [Compose Specification repository](https://github.com/compose-spec/compose-spec).

Use the following links to navigate key sections of the Compose Specification.

> Tip
>
> Want a better editing experience for Compose files in VS Code? Check out the [Docker DX](https://marketplace.visualstudio.com/items?itemName=docker.docker) extension for linting, code navigation, and vulnerability scanning.

### [Version and name top-level element](/reference/compose-file/version-and-name/)

[Understand version and name attributes for Compose.](/reference/compose-file/version-and-name/)

### [Services top-level element](/reference/compose-file/services/)

[Explore all services attributes for Compose.](/reference/compose-file/services/)

### [Networks top-level element](/reference/compose-file/networks/)

[Find all networks attributes for Compose.](/reference/compose-file/networks/)

### [Volumes top-level element](/reference/compose-file/volumes/)

[Explore all volumes attributes for Compose.](/reference/compose-file/volumes/)

### [Configs top-level element](/reference/compose-file/configs/)

[Find out about configs in Compose.](/reference/compose-file/configs/)

### [Secrets top-level element](/reference/compose-file/secrets/)

[Learn about secrets in Compose.](/reference/compose-file/secrets/)

----
url: https://docs.docker.com/reference/cli/docker/model/uninstall-runner/
----

# docker model uninstall-runner

***

| Description | Uninstall Docker Model Runner (Docker Engine only) |
| ----------- | -------------------------------------------------- |
| Usage       | `docker model uninstall-runner`                    |

## [Description](#description)

Uninstall Docker Model Runner (Docker Engine only)

## [Options](#options)

| Option      | Default | Description                                         |
| ----------- | ------- | --------------------------------------------------- |
| `--backend` |         | Uninstall a deferred backend (e.g. vllm, diffusers) |
| `--images`  |         | Remove docker/model-runner images                   |
| `--models`  |         | Remove model storage volume                         |

----
url: https://docs.docker.com/guides/testcontainers-java-spring-boot-rest-api/create-project/
----

# Create the Spring Boot project

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Spring Boot project from [Spring Initializr](https://start.spring.io) by selecting the **Spring Web**, **Spring Data JPA**, **PostgreSQL Driver**, and **Testcontainers** starters.

Alternatively, clone the [guide repository](https://github.com/testcontainers/tc-guide-testing-spring-boot-rest-api).

The key dependencies in `pom.xml` are:

```xml
<properties>
    <java.version>17</java.version>
    <testcontainers.version>2.0.4</testcontainers.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-postgresql</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

Using the Testcontainers BOM (Bill of Materials) is recommended so that you don't have to repeat the version for every Testcontainers module dependency.

## [Create the JPA entity](#create-the-jpa-entity)

Create `Customer.java`:

```java
package com.testcontainers.demo;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;

@Entity
@Table(name = "customers")
class Customer {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;

  @Column(nullable = false)
  private String name;

  @Column(nullable = false, unique = true)
  private String email;

  public Customer() {}

  public Customer(Long id, String name, String email) {
    this.id = id;
    this.name = name;
    this.email = email;
  }

  public Long getId() {
    return id;
  }

  public void setId(Long id) {
    this.id = id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }
}
```

## [Create the Spring Data JPA repository](#create-the-spring-data-jpa-repository)

```java
package com.testcontainers.demo;

import org.springframework.data.jpa.repository.JpaRepository;

interface CustomerRepository extends JpaRepository<Customer, Long> {}
```

## [Add the schema creation script](#add-the-schema-creation-script)

Create `src/main/resources/schema.sql`:

```sql
create table if not exists customers (
    id bigserial not null,
    name varchar not null,
    email varchar not null,
    primary key (id),
    UNIQUE (email)
);
```

Enable schema initialization in `src/main/resources/application.properties`:

```properties
spring.sql.init.mode=always
```

## [Create the REST API endpoint](#create-the-rest-api-endpoint)

Create `CustomerController.java`:

```java
package com.testcontainers.demo;

import java.util.List;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
class CustomerController {

  private final CustomerRepository repo;

  CustomerController(CustomerRepository repo) {
    this.repo = repo;
  }

  @GetMapping("/api/customers")
  List<Customer> getAll() {
    return repo.findAll();
  }
}
```

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-java-spring-boot-rest-api/write-tests/)

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/tools/
----

# docker mcp profile tools

***

| Description | Manage tool allowlist for servers in a profile                                                                                                |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Usage       | `docker mcp profile tools <profile-id> [--enable <tool> ...] [--disable <tool> ...] [--enable-all <server> ...] [--disable-all <server> ...]` |

## [Description](#description)

Manage the tool allowlist for servers in a profile. Tools are specified using dot notation: .

Use --enable to enable specific tools for a server (can be specified multiple times). Use --disable to disable specific tools for a server (can be specified multiple times). Use --enable-all to enable all tools for a server (can be specified multiple times). Use --disable-all to disable all tools for a server (can be specified multiple times).

To view enabled tools, use: docker mcp profile show

## [Options](#options)

| Option          | Default | Description                                  |
| --------------- | ------- | -------------------------------------------- |
| `--disable`     |         | Disable specific tools: . (repeatable)       |
| `--disable-all` |         | Disable all tools for a server: (repeatable) |
| `--enable`      |         | Enable specific tools: . (repeatable)        |
| `--enable-all`  |         | Enable all tools for a server: (repeatable)  |

## [Examples](#examples)

# [Enable specific tools for a server](#enable-specific-tools-for-a-server)

docker mcp profile tools my-profile --enable github.create\_issue --enable github.list\_repos

# [Disable specific tools for a server](#disable-specific-tools-for-a-server)

docker mcp profile tools my-profile --disable github.create\_issue --disable github.search\_code

# [Enable and disable in one command](#enable-and-disable-in-one-command)

docker mcp profile tools my-profile --enable github.create\_issue --disable github.search\_code

# [Enable all tools for a server](#enable-all-tools-for-a-server)

docker mcp profile tools my-profile --enable-all github

# [Disable all tools for a server](#disable-all-tools-for-a-server)

docker mcp profile tools my-profile --disable-all github

# [View all enabled tools in the profile](#view-all-enabled-tools-in-the-profile)

docker mcp profile show my-profile

----
url: https://docs.docker.com/reference/cli/docker/compose/stop/
----

# docker compose stop

***

| Description | Stop services                                |
| ----------- | -------------------------------------------- |
| Usage       | `docker compose stop [OPTIONS] [SERVICE...]` |

## [Description](#description)

Stops running containers without removing them. They can be started again with `docker compose start`.

## [Options](#options)

| Option          | Default | Description                           |
| --------------- | ------- | ------------------------------------- |
| `-t, --timeout` |         | Specify a shutdown timeout in seconds |

----
url: https://docs.docker.com/reference/cli/docker/trust/signer/add/
----

# docker trust signer add

***

| Description | Add a signer                                                      |
| ----------- | ----------------------------------------------------------------- |
| Usage       | `docker trust signer add OPTIONS NAME REPOSITORY [REPOSITORY...]` |

## [Description](#description)

`docker trust signer add` adds signers to signed repositories.

## [Options](#options)

| Option  | Default | Description                          |
| ------- | ------- | ------------------------------------ |
| `--key` |         | Path to the signer's public key file |

## [Examples](#examples)

### [Add a signer to a repository](#add-a-signer-to-a-repository)

To add a new signer, `alice`, to this repository:

```console
$ docker trust inspect --pretty example/trust-demo

No signatures for example/trust-demo


List of signers and their keys:

SIGNER              KEYS
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: 642692c14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

Add `alice` with `docker trust signer add`:

```console
$ docker trust signer add alice example/trust-demo --key alice.crt
  Adding signer "alice" to example/trust-demo...
  Enter passphrase for repository key with ID 642692c:
Successfully added signer: alice to example/trust-demo
```

`docker trust inspect --pretty` now lists `alice` as a valid signer:

```console
$ docker trust inspect --pretty example/trust-demo

No signatures for example/trust-demo


List of signers and their keys:

SIGNER              KEYS
alice               05e87edcaecb
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: 642692c14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

----
url: https://docs.docker.com/engine/install/centos/
----

# Install Docker Engine on CentOS

***

Table of contents

***

To get started with Docker Engine on CentOS, make sure you [meet the prerequisites](#prerequisites), and then follow the [installation steps](#installation-methods).

## [Prerequisites](#prerequisites)

### [OS requirements](#os-requirements)

To install Docker Engine, you need a maintained version of one of the following CentOS versions:

* CentOS Stream 10
* CentOS Stream 9

The `centos-extras` repository must be enabled. This repository is enabled by default. If you have disabled it, you need to re-enable it.

### [Uninstall old versions](#uninstall-old-versions)

Before you can install Docker Engine, you need to uninstall any conflicting packages.

Your Linux distribution may provide unofficial Docker packages, which may conflict with the official packages provided by Docker. You must uninstall these packages before you install the official version of Docker Engine.

```console
$ sudo dnf remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-engine
```

```console
$ sudo dnf -y install dnf-plugins-core
$ sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
```

#### [Install Docker Engine](#install-docker-engine)

1. Install the Docker packages.

   To install the latest version, run:

   ```console
   $ sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   If prompted to accept the GPG key, verify that the fingerprint matches `060A 61C5 1B55 8A7F 742B 77AA C52F EB6B 621E 9F35`, and if so, accept it.

   This command installs Docker, but it doesn't start Docker. It also creates a `docker` group, however, it doesn't add any users to the group by default.

   To install a specific version, start by listing the available versions in the repository:

   ```console
   $ dnf list docker-ce --showduplicates | sort -r

   docker-ce.x86_64    3:29.5.2-1.el9    docker-ce-stable
   docker-ce.x86_64    3:29.5.1-1.el9    docker-ce-stable
   <...>
   ```

   The list returned depends on which repositories are enabled, and is specific to your version of CentOS (indicated by the `.el9` suffix in this example).

   Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), separated by a hyphen (`-`). For example, `docker-ce-3:29.5.2-1.el9`.

   Replace `<VERSION_STRING>` with the desired version and then run the following command to install:

   ```console
   $ sudo dnf install docker-ce-VERSION_STRING docker-ce-cli-VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   This command installs Docker, but it doesn't start Docker. It also creates a `docker` group, however, it doesn't add any users to the group by default.

2. Start Docker Engine.

   ```console
   $ sudo systemctl enable --now docker
   ```

   This configures the Docker systemd service to start automatically when you boot your system. If you don't want Docker to start automatically, use `sudo systemctl start docker` instead.

3. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

#### [Upgrade Docker Engine](#upgrade-docker-engine)

To upgrade Docker Engine, follow the [installation instructions](#install-using-the-repository), choosing the new version you want to install.

### [Install from a package](#install-from-a-package)

If you can't use Docker's `rpm` repository to install Docker Engine, you can download the `.rpm` file for your release and install it manually. You need to download a new file each time you want to upgrade Docker Engine.

1. Go to <https://download.docker.com/linux/centos/> and choose your version of CentOS. Then browse to `x86_64/stable/Packages/` and download the `.rpm` file for the Docker version you want to install.

2. Install Docker Engine, changing the following path to the path where you downloaded the Docker package.

   ```console
   $ sudo dnf install /path/to/package.rpm
   ```

   Docker is installed but not started. The `docker` group is created, but no users are added to the group.

3. Start Docker Engine.

   ```console
   $ sudo systemctl enable --now docker
   ```

   This configures the Docker systemd service to start automatically when you boot your system. If you don't want Docker to start automatically, use `sudo systemctl start docker` instead.

4. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

> Tip
>
> Preview script steps before running. You can run the script with the `--dry-run` option to learn what steps the script will run when invoked:
>
> ```console
> $ curl -fsSL https://get.docker.com -o get-docker.sh
> $ sudo sh ./get-docker.sh --dry-run
> ```

This example downloads the script from <https://get.docker.com/> and runs it to install the latest stable release of Docker on Linux:

```console
$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh get-docker.sh
Executing docker install script, commit: 7cae5f8b0decc17d6571f9f52eb840fbc13b2737
<...>
```

You have now successfully installed and started Docker Engine. The `docker` service starts automatically on Debian based distributions. On `RPM` based distributions, such as CentOS, Fedora or RHEL, you need to start it manually using the appropriate `systemctl` or `service` command. As the message indicates, non-root users can't run Docker commands by default.

> **Use Docker as a non-privileged user, or install in rootless mode?**
>
> The installation script requires `root` or `sudo` privileges to install and use Docker. If you want to grant non-root users access to Docker, refer to the [post-installation steps for Linux](/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). You can also install Docker without `root` privileges, or configured to run in rootless mode. For instructions on running Docker in rootless mode, refer to [run the Docker daemon as a non-root user (rootless mode)](/engine/security/rootless/).

#### [Install pre-releases](#install-pre-releases)

Docker also provides a convenience script at <https://test.docker.com/> to install pre-releases of Docker on Linux. This script is equal to the script at `get.docker.com`, but configures your package manager to use the test channel of the Docker package repository. The test channel includes both stable and pre-releases (beta versions, release-candidates) of Docker. Use this script to get early access to new releases, and to evaluate them in a testing environment before they're released as stable.

To install the latest version of Docker on Linux from the test channel, run:

```console
$ curl -fsSL https://test.docker.com -o test-docker.sh
$ sudo sh test-docker.sh
```

#### [Upgrade Docker after using the convenience script](#upgrade-docker-after-using-the-convenience-script)

If you installed Docker using the convenience script, you should upgrade Docker using your package manager directly. There's no advantage to re-running the convenience script. Re-running it can cause issues if it attempts to re-install repositories which already exist on the host machine.

## [Uninstall Docker Engine](#uninstall-docker-engine)

1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages:

   ```console
   $ sudo dnf remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
   ```

2. Images, containers, volumes, or custom configuration files on your host aren't automatically removed. To delete all images, containers, and volumes:

   ```console
   $ sudo rm -rf /var/lib/docker
   $ sudo rm -rf /var/lib/containerd
   ```

You have to delete any edited configuration files manually.

## [Next steps](#next-steps)

* Continue to [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/).

----
url: https://docs.docker.com/engine/storage/drivers/windowsfilter-driver/
----

# windowsfilter storage driver

***

Table of contents

***

The windowsfilter storage driver is the default storage driver for Docker Engine on Windows. The windowsfilter driver uses Windows-native file system layers to for storing Docker layers and volume data on disk. The windowsfilter storage driver only works on file systems formatted with NTFS.

## [Configure the windowsfilter storage driver](#configure-the-windowsfilter-storage-driver)

For most use case, no configuring the windowsfilter storage driver is not necessary.

The default storage limit for Docker Engine on Windows is 127GB. To use a different storage size, set the `size` option for the windowsfilter storage driver. See [windowsfilter options](https://docs.docker.com/reference/cli/dockerd/#windowsfilter-options).

Data is stored on the Docker host in `image` and `windowsfilter` subdirectories within `C:\ProgramData\docker` by default. You can change the storage location by configuring the `data-root` option in the [Daemon configuration file](https://docs.docker.com/reference/cli/dockerd/#on-windows):

```json
{
  "data-root": "d:\\docker"
}
```

You must restart the daemon for the configuration change to take effect.

## [Additional information](#additional-information)

For more information about how container storage works on Windows, refer to Microsoft's [Containers on Windows documentation](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/container-storage).

----
url: https://docs.docker.com/reference/cli/docker/container/stop/
----

# docker container stop

***

| Description                                                               | Stop one or more running containers                        |
| ------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Usage                                                                     | `docker container stop [OPTIONS] CONTAINER [CONTAINER...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker stop`                                              |

## [Description](#description)

The main process inside the container will receive `SIGTERM`, and after a grace period, `SIGKILL`. The first signal can be changed with the `STOPSIGNAL` instruction in the container's Dockerfile, or the `--stop-signal` option to `docker run` and `docker create`.

## [Options](#options)

| Option                      | Default | Description                                  |
| --------------------------- | ------- | -------------------------------------------- |
| [`-s, --signal`](#signal)   |         | Signal to send to the container              |
| [`-t, --timeout`](#timeout) |         | Seconds to wait before killing the container |

## [Examples](#examples)

```console
$ docker stop my_container
```

### [Stop container with signal (-s, --signal)](#signal)

The `--signal` flag sends the system call signal to the container to exit. This signal can be a signal name in the format `SIG<NAME>`, for instance `SIGKILL`, or an unsigned number that matches a position in the kernel's syscall table, for instance `9`. Refer to [signal(7)](https://man7.org/linux/man-pages/man7/signal.7.html) for available signals.

The default signal to use is defined by the image's [`StopSignal`](https://github.com/opencontainers/image-spec/blob/v1.1.0/config.md), which can be set through the [`STOPSIGNAL`](/reference/dockerfile/#stopsignal) Dockerfile instruction when building the image, or configured using the [`--stop-signal`](/reference/cli/docker/container/run/#stop-signal) option when creating the container. If no signal is configured for the container, `SIGTERM` is used as default.

### [Stop container with timeout (-t, --timeout)](#timeout)

The `--timeout` flag sets the number of seconds to wait for the container to stop after sending the pre-defined (see \[`--signal`]{#signal)) system call signal. If the container does not exit after the timeout elapses, it's forcibly killed with a `SIGKILL` signal.

If you set `--timeout` to `-1`, no timeout is applied, and the daemon waits indefinitely for the container to exit.

The default timeout can be specified using the [`--stop-timeout`](/reference/cli/docker/container/run/#stop-timeout) option when creating the container. If no default is configured for the container, the Daemon determines the default, and is 10 seconds for Linux containers, and 30 seconds for Windows containers.

----
url: https://docs.docker.com/build/ci/github-actions/multi-platform/
----

# Multi-platform image with GitHub Actions

***

Table of contents

***

You can build [multi-platform images](https://docs.docker.com/build/building/multi-platform/) using the `platforms` option, as shown in the following example:

> Note
>
> * For a list of available platforms, see the [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx) action.
> * If you want support for more platforms, you can use QEMU with the [Docker Setup QEMU](https://github.com/docker/setup-qemu-action) action.

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: user/app:latest
```

## [Build and load multi-platform images](#build-and-load-multi-platform-images)

The default Docker setup for GitHub Actions runners supports building and pushing multi-platform images to registries. However, it does not support loading multi-platform images to the local image store of the runner after building them. To load a multi-platform image locally, you need to enable the containerd image store option for the Docker Engine.

There is no way to configure the default Docker setup in the GitHub Actions runners directly, but you can use `docker/setup-docker-action` to customize the Docker Engine and CLI settings for a job.

The following example workflow enables the containerd image store, builds a multi-platform image, and loads the results into the GitHub runner's local image store.

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker
        uses: docker/setup-docker-action@v5
        with:
          daemon-config: |
            {
              "debug": true,
              "features": {
                "containerd-snapshotter": true
              }
            }

      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          platforms: linux/amd64,linux/arm64
          load: true
          tags: user/app:latest
```

## [Distribute build across multiple runners](#distribute-build-across-multiple-runners)

Building multiple platforms on the same runner can significantly extend build times, particularly when dealing with complex Dockerfiles or a high number of target platforms. If you want to split platform builds across multiple runners without maintaining a custom matrix and merge job, use the [Docker GitHub Builder](https://docs.docker.com/build/ci/github-actions/github-builder/). The reusable workflows compute the per-platform matrix, run each platform on its own runner, and create the final manifest for you.

The following workflow uses the [`build.yml` reusable workflow](https://docs.docker.com/build/ci/github-actions/github-builder/build/) to distribute a multi-platform Dockerfile build:

```yaml
name: ci

on:
  push:

permissions:
  contents: read

jobs:
  build:
    uses: docker/github-builder/.github/workflows/build.yml@v1
    permissions:
      contents: read
      id-token: write
    with:
      output: image
      push: true
      platforms: linux/amd64,linux/arm64
      meta-images: user/app
      meta-tags: |
        type=ref,event=branch
        type=ref,event=pr
        type=semver,pattern={{version}}
        type=semver,pattern={{major}}.{{minor}}
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
```

With `distribute: true`, which is the default, the workflow splits the build into one platform per runner and assembles the final multi-platform image in its finalize phase. The default `runner` mapping sends Linux Arm platforms to `ubuntu-24.04-arm` and uses `ubuntu-24.04` for other platforms. To customize the mapping, see [runner selection](https://docs.docker.com/build/ci/github-actions/github-builder/architecture/#runner-selection). If you need to control the Docker build inputs directly, see [Build with Docker GitHub Builder build.yml](https://docs.docker.com/build/ci/github-actions/github-builder/build/).

### [With Bake](#with-bake)

You can use the [`bake.yml` reusable workflow](https://docs.docker.com/build/ci/github-actions/github-builder/bake/) for the same pattern when your build is defined in a Bake file. The workflow reads the target platforms from the Bake definition, distributes the per-platform builds, and publishes the final manifest without a separate prepare or merge job.

```hcl
variable "DEFAULT_TAG" {
  default = "app:local"
}

// Special target: https://github.com/docker/metadata-action#bake-definition
target "docker-metadata-action" {
  tags = ["${DEFAULT_TAG}"]
}

// Default target if none specified
group "default" {
  targets = ["image-local"]
}

target "image" {
  inherits = ["docker-metadata-action"]
}

target "image-local" {
  inherits = ["image"]
  output = ["type=docker"]
}

target "image-all" {
  inherits = ["image"]
  platforms = [
    "linux/amd64",
    "linux/arm/v6",
    "linux/arm/v7",
    "linux/arm64"
  ]
}
```

```yaml
name: ci

on:
  push:

permissions:
  contents: read

jobs:
  bake:
    uses: docker/github-builder/.github/workflows/bake.yml@v1
    permissions:
      contents: read
      id-token: write
    with:
      output: image
      push: true
      target: image-all
      meta-images: user/app
      meta-tags: |
        type=ref,event=branch
        type=sha
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
```

----
url: https://docs.docker.com/dhi/how-to/mirror/
----

# Mirror a Docker Hardened Image repository

***

Table of contents

***

Subscription: Docker Hardened Images Select or Enterprise

Mirroring requires a DHI Select or Enterprise subscription. Without a subscription, you can pull Docker Hardened Images directly from `dhi.io` without mirroring. With a DHI Select or Enterprise subscription, you must mirror to your organization to get:

* Compliance variants (FIPS-enabled or STIG-ready images)
* Extended Lifecycle Support (ELS) variants (requires add-on)
* Image or Helm chart customization
* Air-gapped or restricted network environments
* [SLA-backed security updates](https://docs.docker.com/go/dhi-sla/)

## [How to mirror](#how-to-mirror)

This topic covers two types of mirroring for Docker Hardened Image (DHI) repositories:

* [Mirror to your organization](#mirror-a-dhi-repository-to-your-organization): Mirror a DHI repository to your organization's namespace on Docker Hub.

* [Mirror to a third-party registry](#mirror-a-dhi-repository-to-a-third-party-registry): Mirror a repository to another container registry, such as Amazon ECR, Google Artifact Registry, or a private Harbor instance.

## [Mirror a DHI repository to your organization](#mirror-a-dhi-repository-to-your-organization)

To mirror repositories, you must be an organization owner or editor, or use a personal access token (PAT) or organization access token (OAT). See the CLI and Terraform tabs in the following sections for required permission scopes.

* Image repositories: Mirroring lets you customize images by adding packages, OCI artifacts (such as custom certificates or additional tools), environment variables, labels, and other configuration settings. For more details, see [Customize a Docker Hardened Image](https://docs.docker.com/dhi/how-to/customize/#customize-a-docker-hardened-image).

* Chart repositories: Mirroring lets you customize image references within the chart. This is particularly useful when using customized images or when you've mirrored images to a third-party registry and need the chart to reference those custom locations. For more details, see [Customize a Docker Hardened Helm chart](https://docs.docker.com/dhi/how-to/customize/#customize-a-docker-hardened-helm-chart).

1. Go to [Docker Hub](https://hub.docker.com) and sign in.

2. Select **My Hub**.

3. In the namespace drop-down, select your organization.

4. Select **Hardened Images** > **Catalog**.

5. Select a DHI repository to view its details.

6. Mirror the repository:

   * To mirror an image repository, select **Use this image** > **Mirror repository**, and then follow the on-screen instructions. If you have the ELS add-on, you can also select **Enable support for end-of-life versions**.
   * To mirror a Helm chart repository, select **Get Helm chart**, and then follow the on-screen instructions.

It may take a few minutes for all the tags to finish mirroring.

Authenticate with `docker login` using your Docker credentials, a [personal access token (PAT)](https://docs.docker.com/security/access-tokens/) with **Read & Write** permissions, or an [organization access token (OAT)](https://docs.docker.com/enterprise/security/access-tokens/). When using an OAT, the available operations depend on the token's permission scope:

* To list mirrored repositories, the OAT must have read (pull) access to the relevant repositories. Results are scoped to repositories the OAT can access.
* To create a mirror to an existing destination repository, the OAT must have push access to that repository. To create a mirror to a new destination repository that doesn't yet exist, the OAT must have org-wide repository access (for example, `<org>/*` with pull or push). Repository-scoped access to the future repository name is not sufficient.
* To stop mirroring, the OAT must have push access to the relevant repository.
* OATs with public repository read-only access cannot list or manage mirrored repositories.

Use the [`docker dhi mirror`](/reference/cli/docker/dhi/mirror/) command:

```console
$ docker dhi mirror start --org my-org \
  dhi/golang,my-org/dhi-golang \
  dhi/nginx,my-org/dhi-nginx \
  dhi/prometheus-chart,my-org/dhi-prometheus-chart
```

Mirror with dependencies:

```console
$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --dependencies
```

List mirrored images in your organization:

```console
$ docker dhi mirror list --org my-org
```

Filter mirrored images by name or type:

```console
$ docker dhi mirror list --org my-org --filter python
$ docker dhi mirror list --org my-org --type image
$ docker dhi mirror list --org my-org --type helm-chart
```

You can manage DHI mirrors as infrastructure-as-code using the [DHI Terraform provider](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs).

First, install and configure the provider:

```hcl
terraform {
  required_providers {
    dhi = {
      source = "docker-hardened-images/dhi"
    }
  }
}

provider "dhi" {
  docker_hub_username = var.docker_username
  docker_hub_password = var.docker_password
  organization        = var.org_name
}
```

> Note
>
> Instead of specifying credentials in the provider block, you can set the `DOCKER_USERNAME`, `DOCKER_PASSWORD`, and `DHI_ORG` environment variables. You can also authenticate using an organization access token (OAT) in place of a password. Set `DOCKER_USERNAME` to your organization namespace and `DOCKER_PASSWORD` to the OAT. When using an OAT, the same permission scopes apply as with the CLI: read (pull) access is required to list mirrors, and push access is required to create or delete them.

Then, define a `dhi_mirror` resource for each repository you want to mirror:

```hcl
resource "dhi_mirror" "golang" {
  source_namespace = "dhi"
  source_name      = "golang"
  destination_name = "dhi-golang"
}

resource "dhi_mirror" "nginx" {
  source_namespace = "dhi"
  source_name      = "nginx"
  destination_name = "dhi-nginx"
}
```

To enable Extended Lifecycle Support (ELS) variants, set the `els` attribute:

```hcl
resource "dhi_mirror" "golang" {
  source_namespace = "dhi"
  source_name      = "golang"
  destination_name = "dhi-golang"
  els              = true
}
```

Run `terraform apply` to create the mirrors.

For the full list of resource attributes, see the [Terraform Registry documentation](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs/resources/mirror).

After mirroring, the repository appears in your organization's repository list, prefixed by `dhi-`, and continues to receive updated images. It behaves like any other Docker Hub repository, so you can manage access and permissions, configure webhooks, and use other standard Hub features. See [Docker Hub repositories](https://docs.docker.com/docker-hub/repos/) for details.

### [Stop mirroring a repository](#stop-mirroring-a-repository)

After you stop mirroring, the repository remains, but it no longer receives updates. You can still use the last images or charts that were mirrored.

> Note
>
> If you only want to stop mirroring ELS versions, you can clear the ELS option in the mirrored repository's **Settings** tab.

1. Go to [Docker Hub](https://hub.docker.com) and sign in.
2. Select **My Hub**.
3. In the namespace drop-down, select your organization that has access to DHI.
4. Select **Hardened Images** > **Manage**.
5. Select the **Mirrored Images** or **Mirrored Helm charts** tab.
6. In the far right column of the repository you want to stop mirroring, select the menu icon.
7. Select **Stop mirroring**.

Authenticate with `docker login` using your Docker credentials, a [personal access token (PAT)](https://docs.docker.com/security/access-tokens/) with **Read & Write** permissions, or an [organization access token (OAT)](https://docs.docker.com/enterprise/security/access-tokens/) with push access to the relevant repository.

Use the [`docker dhi mirror`](/reference/cli/docker/dhi/mirror/) command:

```console
$ docker dhi mirror stop --org my-org dhi-golang
```

To stop mirroring, remove the `dhi_mirror` resource from your Terraform configuration and run `terraform apply`. The repository remains in your organization but no longer receives updates.

## [Mirror a DHI repository to a third-party registry](#mirror-a-dhi-repository-to-a-third-party-registry)

After mirroring a DHI repository to your organization on Docker Hub, you can optionally mirror it to another container registry, such as Amazon ECR, Google Artifact Registry, GitHub Container Registry, or a private Harbor instance.

You can use any standard workflow to mirror the image, such as the [Docker CLI](/reference/cli/docker/), [Docker Hub Registry API](/reference/api/registry/latest/), third-party registry tools, or CI/CD automation.

However, to preserve the full security context, including attestations, you must also mirror its associated OCI artifacts. DHI repositories store the image layers on `dhi.io` (or `docker.io` for customized images) and the signed attestations in a separate registry (`registry.scout.docker.com`).

To copy both, you can use [`regctl`](https://regclient.org/cli/regctl/), an OCI-aware CLI that supports mirroring images along with attached artifacts such as SBOMs, vulnerability reports, and SLSA provenance. For ongoing synchronization, you can use [`regsync`](https://regclient.org/cli/regsync/).

### [Automate syncing with webhooks](#automate-syncing-with-webhooks)

To keep external registries or systems in sync with your mirrored Docker Hardened Images, and to receive notifications when updates occur, you can configure a [webhook](/docker-hub/repos/manage/webhooks/) on the mirrored repository in Docker Hub. A webhook sends a `POST` request to a URL you define whenever a new image tag is pushed or updated.

For example, you might configure a webhook to call a CI/CD system at `https://ci.example.com/hooks/dhi-sync` whenever a new tag is mirrored. The automation triggered by this webhook can pull the updated image from Docker Hub and push it to an internal registry such as Amazon ECR, Google Artifact Registry, or GitHub Container Registry.

Other common webhook use cases include:

* Triggering validation or vulnerability scanning workflows
* Signing or promoting images
* Sending notifications to downstream systems

#### [Example webhook payload](#example-webhook-payload)

When a webhook is triggered, Docker Hub sends a JSON payload like the following:

```json
{
  "callback_url": "https://registry.hub.docker.com/u/exampleorg/dhi-python/hook/abc123/",
  "push_data": {
    "pushed_at": 1712345678,
    "pusher": "trustedbuilder",
    "tag": "3.13-alpine3.21"
  },
  "repository": {
    "name": "dhi-python",
    "namespace": "exampleorg",
    "repo_name": "exampleorg/dhi-python",
    "repo_url": "https://hub.docker.com/r/exampleorg/dhi-python",
    "is_private": true,
    "status": "Active",
    ...
  }
}
```

### [Example mirroring with `regctl`](#example-mirroring-with-regctl)

The following example shows how to mirror a specific tag of a Docker Hardened Image from Docker Hub to another registry, along with its associated attestations using `regctl`. You must [install `regctl`](https://github.com/regclient/regclient) first.

The example assumes you have mirrored the DHI repository to your organization's namespace on Docker Hub as described in the previous section. You can apply the same steps to a non-mirrored image by updating the `SRC_ATT_REPO` and `SRC_REPO` variables accordingly.

1. Set environment variables for your specific environment. Replace the placeholders with your actual values.

   In this example, you authenticate as your Docker organization using an [organization access token (OAT)](https://docs.docker.com/enterprise/security/access-tokens/). The OAT must have at least pull access to every DHI repository you want to mirror. Only repositories in the token's scope are accessible. Alternatively, you can authenticate as a Docker Hub user with a [personal access token (PAT)](https://docs.docker.com/security/access-tokens/) that has `read only` access.

   > Warning
   >
   > The following examples export credentials directly on the command line for demonstration purposes. This exposes sensitive tokens in your shell history and process list. In production environments, use secure methods such as reading from files with restricted permissions, environment files loaded at runtime, or secret management tools.

   ```console
   $ export DOCKER_ORG="YOUR_DOCKER_ORG"
   $ export DOCKER_OAT="YOUR_DOCKER_OAT"
   $ export DEST_REG="registry.example.com"
   $ export DEST_REPO="mirror/dhi-python"
   $ export DEST_REG_USERNAME="YOUR_DESTINATION_REGISTRY_USERNAME"
   $ export DEST_REG_TOKEN="YOUR_DESTINATION_REGISTRY_TOKEN"
   $ export SRC_REPO="docker.io/${DOCKER_ORG}/dhi-python"
   $ export SRC_ATT_REPO="registry.scout.docker.com/${DOCKER_ORG}/dhi-python"
   $ export TAG="3.13-alpine3.21"
   ```

2. Sign in via `regctl` to Docker Hub, the Scout registry that contains the attestations, and your destination registry.

   ```console
   $ echo $DOCKER_OAT | regctl registry login -u "$DOCKER_ORG" --pass-stdin docker.io
   $ echo $DOCKER_OAT | regctl registry login -u "$DOCKER_ORG" --pass-stdin registry.scout.docker.com
   $ echo $DEST_REG_TOKEN | regctl registry login -u "$DEST_REG_USERNAME" --pass-stdin "$DEST_REG"
   ```

3. Mirror the image and attestations using `--referrers` and referrer endpoints:

   ```console
   $ regctl image copy \
        "${SRC_REPO}:${TAG}" \
        "${DEST_REG}/${DEST_REPO}:${TAG}" \
        --referrers \
        --referrers-src "${SRC_ATT_REPO}" \
        --referrers-tgt "${DEST_REG}/${DEST_REPO}" \
        --force-recursive
   ```

4. Verify that artifacts were preserved.

   First, get a digest for a specific tag and platform. For example, `linux/amd64`.

   ```console
   DIGEST="$(regctl manifest head "${DEST_REG}/${DEST_REPO}:${TAG}" --platform linux/amd64)"
   ```

   List attached artifacts (SBOM, provenance, VEX, vulnerability reports).

   ```console
   $ regctl artifact list "${DEST_REG}/${DEST_REPO}@${DIGEST}"
   ```

   Or, list attached artifacts with `docker scout`.

   ```console
   $ docker scout attest list "registry://${DEST_REG}/${DEST_REPO}@${DIGEST}"
   ```

### [Example ongoing mirroring with `regsync`](#example-ongoing-mirroring-with-regsync)

`regsync` automates pulling from your organizations mirrored DHI repositories on Docker Hub and pushing to your external registry including attestations. It reads a YAML configuration file and can filter tags.

The following example uses a `regsync.yaml` file that syncs Node 24 and Python 3.12 Debian 13 variants, excluding Alpine and Debian 12.

regsync.yaml

```yaml
version: 1
# Optional: inline creds if not relying on prior CLI logins
# creds:
#   - registry: docker.io
#     user: <your-docker-org>
#     pass: "{{file \"/run/secrets/docker_oat\"}}"
#   - registry: registry.scout.docker.com
#     user: <your-docker-org>
#     pass: "{{file \"/run/secrets/docker_oat\"}}"
#   - registry: registry.example.com
#     user: <service-user>
#     pass: "{{file \"/run/secrets/dest_token\"}}"

sync:
  - source: docker.io/<your-org>/dhi-node
    target: registry.example.com/mirror/dhi-node
    type: repository
    fastCopy: true
    referrers: true
    referrerSource: registry.scout.docker.com/<your-org>/dhi-node
    referrerTarget: registry.example.com/mirror/dhi-node
    tags:
      allow: [ "24.*" ]
      deny: [ ".*alpine.*", ".*debian12.*" ]

  - source: docker.io/<your-org>/dhi-python
    target: registry.example.com/mirror/dhi-python
    type: repository
    fastCopy: true
    referrers: true
    referrerSource: registry.scout.docker.com/<your-org>/dhi-python
    referrerTarget: registry.example.com/mirror/dhi-python
    tags:
      allow: [ "3.12.*" ]
      deny: [ ".*alpine.*", ".*debian12.*" ]
```

To do a dry run with the configuration file, you can run the following command. You must [install `regsync`](https://github.com/regclient/regclient) first.

```console
$ regsync check -c regsync.yaml
```

To run the sync with the configuration file:

```console
$ regsync once -c regsync.yaml
```

## [What next](#what-next)

After mirroring, see [Pull a DHI](https://docs.docker.com/dhi/how-to/use/#pull-a-dhi) to learn how to pull and use mirrored images.

----
url: https://docs.docker.com/reference/cli/docker/scout/watch/
----

# docker scout watch

***

| Description | Watch repositories in a registry and push images and indexes to Docker Scout |
| ----------- | ---------------------------------------------------------------------------- |
| Usage       | `docker scout watch`                                                         |

## [Description](#description)

The docker scout watch command watches repositories in a registry and pushes images or image indexes to Docker Scout.

## [Options](#options)

| Option               | Default | Description                                                                          |
| -------------------- | ------- | ------------------------------------------------------------------------------------ |
| `--all-images`       |         | Push all images instead of only the ones pushed during the watch command is running  |
| `--dry-run`          |         | Watch images and prepare them, but do not push them                                  |
| `--interval`         | `60`    | Interval in seconds between checks                                                   |
| `--org`              |         | Namespace of the Docker organization to which image will be pushed                   |
| `--refresh-registry` |         | Refresh the list of repositories of a registry at every run. Only with --registry.   |
| `--registry`         |         | Registry to watch                                                                    |
| `--repository`       |         | Repository to watch                                                                  |
| `--sbom`             | `true`  | Create and upload SBOMs                                                              |
| `--tag`              |         | Regular expression to match tags to watch                                            |
| `--workers`          | `3`     | Number of concurrent workers                                                         |

## [Examples](#examples)

### [Watch for new images from two repositories and push them](#watch-for-new-images-from-two-repositories-and-push-them)

```console
$ docker scout watch --org my-org --repository registry-1.example.com/repo-1 --repository registry-2.example.com/repo-2
```

### [Only push images with a specific tag](#only-push-images-with-a-specific-tag)

```console
$ docker scout watch --org my-org --repository registry.example.com/my-service --tag latest
```

### [Watch all repositories of a registry](#watch-all-repositories-of-a-registry)

```console
$ docker scout watch --org my-org --registry registry.example.com
```

### [Push all images and not just the new ones](#push-all-images-and-not-just-the-new-ones)

```console
$ docker scout watch --org my-org --repository registry.example.com/my-service --all-images
```

### [Configure Artifactory integration](#configure-artifactory-integration)

The following example creates a web hook endpoint for Artifactory to push new image events into:

```console
$ export DOCKER_SCOUT_ARTIFACTORY_API_USER=user
$ export DOCKER_SCOUT_ARTIFACTORY_API_PASSWORD=password
$ export DOCKER_SCOUT_ARTIFACTORY_WEBHOOK_SECRET=foo

$ docker scout watch --registry "type=artifactory,registry=example.jfrog.io,api=https://example.jfrog.io/artifactory,include=*/frontend*,exclude=*/dta/*,repository=docker-local,port=9000,subdomain-mode=true" --refresh-registry
```

This will launch an HTTP server on port `9000` that will receive all `component` web hook events, optionally validating the HMAC signature.

### [Configure Harbor integration](#configure-harbor-integration)

The following example creates a web hook endpoint for Harbor to push new image events into:

```console
$ export DOCKER_SCOUT_HARBOR_API_USER=admin
$ export DOCKER_SCOUT_HARBOR_API_PASSWORD=password
$ export DOCKER_SCOUT_HARBOR_WEBHOOK_AUTH="token foo"

$ docker scout watch --registry 'type=harbor,registry=demo.goharbor.io,api=https://demo.goharbor.io,include=*/foo/*,exclude=*/bar/*,port=9000' --refresh-registry
```

This will launch an HTTP server on port `9000` that will receive all `component` web hook events, optionally validating the HMAC signature.

### [Configure Nexus integration](#configure-nexus-integration)

The following example shows how to configure Sonartype Nexus integration:

```console
$ export DOCKER_SCOUT_NEXUS_API_USER=admin
$ export DOCKER_SCOUT_NEXUS_API_PASSWORD=admin124

$ docker scout watch --registry 'type=nexus,registry=localhost:8082,api=http://localhost:8081,include=*/foo/*,exclude=*/bar/*,"repository=docker-test1,docker-test2"' --refresh-registry
```

This ingests all images and tags in Nexus repositories called `docker-test1` and `docker-test2` that match the `*/foo/*` include and `*/bar/*` exclude glob pattern.

You can also create a web hook endpoint for Nexus to push new image events into:

```console
$ export DOCKER_SCOUT_NEXUS_API_USER=admin
$ export DOCKER_SCOUT_NEXUS_API_PASSWORD=admin124
$ export DOCKER_SCOUT_NEXUS_WEBHOOK_SECRET=mysecret

$ docker scout watch --registry 'type=nexus,registry=localhost:8082,api=http://localhost:8081,include=*/foo/*,exclude=*/bar/*,"repository=docker-test1,docker-test2",port=9000' --refresh-registry
```

This will launch an HTTP server on port `9000` that will receive all `component` web hook events, optionally validating the HMAC signature.

### [Configure integration for other OCI registries](#configure-integration-for-other-oci-registries)

The following example shows how to integrate an OCI registry that implements the `_catalog` endpoint:

```console
$ docker scout watch --registry 'type=oci,registry=registry.example.com,include=*/scout-artifact-registry/*'
```

----
url: https://docs.docker.com/ai/sandboxes/release-notes/
----

# Docker Sandboxes release notes

***

Table of contents

***

This page lists changes in recent stable releases of Docker Sandboxes. For the full release history, including pre-releases and downloads, see the [Docker Sandboxes releases on GitHub](https://github.com/docker/sbx-releases/releases).

## [0.31.1](#0311)

*2026-05-29*

[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.31.1)

### [Bug fixes](#bug-fixes)

* Fixes a bug introduced in v0.31.0 where sandboxes from earlier versions were not listed by sbx ls and could fail to run. Upgrading to v0.31.1 restores them.

## [0.31.0](#0310)

*2026-05-28*

[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.31.0)

### [Highlights](#highlights)

> Important
>
> This release has a known issue where sandboxes from earlier versions may not be listed by sbx ls and can fail to run. This is fixed in [v0.31.1](https://github.com/docker/sbx-releases/releases/tag/v0.31.1) — please upgrade.

#### [Clone mode: `--clone`](#clone-mode---clone)

The `--branch` flag has been removed in favor of `--clone` (clone mode). Using `--branch` now fails with:

```console
$ sbx run claude --branch foo
ERROR: --branch is no longer supported; use --clone instead
```

Clone mode does not create a branch or worktree on your behalf — instead of a host-side worktree, the sandbox now runs against an in-container read-only clone.

* Your source repository is mounted into the sandbox read-only, and the shallow clone sets that mount as a Git remote. The agent only ever writes to the in-container clone, never to your working tree or .git/
* The clone lives on the sandbox's filesystem and is exposed back to the host as a `sandbox-<name>` Git remote served by `git-daemon` (no more `.sbx/<name>-worktrees/...` on the host).
* Forge remotes (`origin`, `upstream`, etc.) on the host are propagated into the in-container clone, so the agent can `git push origin` directly, the same way you would. Local-path remotes are skipped.
* Fetched sandbox refs are mirrored into `refs/sandboxes/<name>/*` on the host and persist after the sandbox is removed. Restore a branch from a removed sandbox with `git branch <local-name> refs/sandboxes/<name>/<branch>`. Commits that were never fetched, or uncommitted changes, are still lost on `sbx rm`.
* The `sandbox-<name>` remote is added to your host on `sbx create --clone` / `sbx run --clone` and removed on `sbx rm`, including across stop and restart.

### [What's New](#whats-new)

#### [CLI](#cli)

* `sbx create` auto-starts the daemon when it isn't already running.
* `sbx logout` now stops the daemon and running sandboxes.
* Unify terminal environment variables across `sbx run` and `sbx exec`.

#### [Policies](#policies)

* Show policy and rule names in CLI list output and TUI details.
* Add filters to the policies listing.

#### [Kits](#kits)

* Mark kits as experimental.
* Verbose error reporting for kit apply failures.

#### [Sandboxes](#sandboxes)

* Opt a sandbox into virtiofs caching at create time via `DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=1` (off by default; the choice is persisted in the spec and survives daemon restarts).

#### [Networking](#networking)

* Allow public-CA CRL/OCSP/AIA endpoints in the balanced proxy preset. Applies to new installations or after `sbx policy reset` (which removes any user-added rules).

#### [Telemetry](#telemetry)

* Surface `port_publish_failed` inner error detail.

#### [Bug Fixes](#bug-fixes-1)

* Sort `template ls` output by repository, then tag.
* Retry `ExecResize` to keep the agent TUI in sync.
* Set `TERM=xterm-256color` when exec'ing with `-t`.
* Move the state directory symlink from `/tmp` to `~/.sbx/run/`.
* Stop `storageRootsGone` from locking the storagekit singleton.
* Use `engineError` and add retry debug logging in sandboxd.
* Retry transient shim start closures.
* Make Cursor session bootstrap proxy-local.
* Add bracketed `[::1]` to `NO_PROXY` for IPv6 loopback.
* Backdate proxy CA `NotBefore` to match the goproxy leaf cert window.

## [0.30.0](#0300)

*2026-05-19*

[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.30.0)

### [Highlights](#highlights-1)

The CLI gets **non-interactive Docker Hub login** for scripted workflows, and sandboxes now have **a configurable grace period before auto-stopping** when the last session exits. Plus a wave of fixes covering Linux packaging, macOS worktree compatibility, Windows installer paths, network isolation, and recoverable sandbox state when host directories vanish.

### [What's New](#whats-new-1)

#### [Governance & Policy](#governance--policy)

* Allow `sbx policy` setup before login

#### [Kits & Agents](#kits--agents)

* Re-run `commands.startup` on every container start so init hooks are idempotent across restarts
* Per-kit memory files for progressive disclosure
* Enumerate installed kits in the AI memory file's Kits section

#### [CLI & Auth](#cli--auth)

* Add non-interactive Docker Hub login for scripted workflows
* Migrate `/reset` to `/daemon/reset`; state-dir wipe is now daemon-side
* Print "Git repository detected" once when using `--branch`
* Skip implicit run options when the user provides explicit args

#### [Networking & Sandboxd](#networking--sandboxd)

* Bind both loopback stacks by default when publishing ports
* Allow raw TCP to `host.docker.internal` when localhost is allowed in policy
* Add grace period before auto-stopping a sandbox when the last session exits

#### [Bug Fixes](#bug-fixes-2)

* Build sailor's `ffi` crate instead of `ffi-krun` for packaged Linux release artifacts
* Keep sandboxes recoverable when workspace or worktree is deleted on the host
* Add macOS `/private` path compatibility for worktrees
* Probe canonical socket path for `sun_path` budget — fixes `krun_start_enter failed` on macOS with long usernames
* Namespace gVisor socket dir and auth/secret stores by `--app-name` so concurrent daemons don't collide
* Sanitize runtime ID when looking up gVisor network
* Check database version before starting the daemon; surface an instructive error instead of crashing
* Report Docker daemon startup time instead of the pre-start message in DinD
* Harden `BuildFileCredential` to check more than just file existence
* Open a sentinel connection in `cp` and `kit add` to prevent auto-stop race
* Remove redundant `ContainerKill` before `ContainerRemove` in sandboxlib
* Use a safe Windows `start` invocation for `OpenURL` in the TUI
* Rename WiX install directory id to `INSTALLFOLDER`

#### [Documentation](#documentation)

* Warn agents about worktree path traps with `--branch`
* Improve consistency and wording in CLI help strings

## [0.29.0](#0290)

*2026-05-13*

[GitHub release](https://github.com/docker/sbx-releases/releases/tag/v0.29.0)

### [Highlights](#highlights-2)

This release brings **per-sandbox network policies**, giving callers fine-grained control over which domains each sandbox can reach, including an explicit `deniedDomains` list and allowance for binary TCP protocols like SSH. Sandboxes now carry **daemon-assigned UUIDs**, enabling reliable identification across restarts and telemetry. Several **agent improvements** land in this release: Gemini gets SSO browser relay, Codex auth is more robust, and the OpenAI OAuth flow now auto-opens the browser. A round of **bug fixes** improves daemon robustness on macOS (long-username `sun_path` overflow), gVisor isolation under `--app-name`, and database-version handling.

### [What's New](#whats-new-2)

#### [Networking & Policy](#networking--policy)

* Support per-sandbox scoped network policies
* Add `deniedDomains` to network kit policy
* Allow binary TCP protocols (e.g. SSH) through domain allow rules
* Pipe in policykit error handler for better diagnostics

#### [Sandboxes](#sandboxes-1)

* Add daemon-assigned UUID to sandbox runtimes

#### [Agents](#agents)

* Enable SSO browser relay for Gemini
* Auto-open browser during OpenAI OAuth flow
* Skip auth.json placeholder for Codex when no host credentials
* Expose Claude guidance to Codex sandboxes

#### [CLI](#cli-1)

* Require confirmation for `sbx rm <name>` to prevent accidental deletion
* Unhide `kit` command in help output

#### [Bug Fixes](#bug-fixes-3)

* Namespace gVisor socket dir by `--app-name` so concurrent daemons don't share state
* Probe canonical socket path for `sun_path` budget — fixes `krun_start_enter failed` for macOS users with long usernames
* Check database version before starting the daemon and surface an instructive error instead of crashing
* Route gVisor sockets to a persistent, sandboxd-owned location
* Delete stranded tracker after failed auto-stop with no active sessions
* Clean up DinD volume even when container inspect fails
* Apply `SANDBOXES_STORAGE_ROOT` override to storage config
* Report running binary (not first `sbx` on PATH) in `diagnose`
* Explain how to configure OpenAI credentials in no-creds warning
* Allow MCR layer-blob CDN in default-code-and-containers policy
* Improve empty state of `sbx ls` with actionable guidance

## [Earlier releases](#earlier-releases)

For older versions, see the [Docker Sandboxes releases on GitHub](https://github.com/docker/sbx-releases/releases).

----
url: https://docs.docker.com/build/cache/backends/registry/
----

# Registry cache

***

Table of contents

***

The `registry` cache storage can be thought of as an extension to the `inline` cache. Unlike the `inline` cache, the `registry` cache is entirely separate from the image, which allows for more flexible usage - `registry`-backed cache can do everything that the inline cache can do, and more:

* Allows for separating the cache and resulting image artifacts so that you can distribute your final image without the cache inside.
* It can efficiently cache multi-stage builds in `max` mode, instead of only the final stage.
* It works with other exporters for more flexibility, instead of only the `image` exporter.

This cache storage backend is not supported with the default `docker` driver. To use this feature, create a new builder using a different driver. See [Build drivers](https://docs.docker.com/build/builders/drivers/) for more information.

## [Synopsis](#synopsis)

Unlike the simpler `inline` cache, the `registry` cache supports several configuration parameters:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>[,parameters...] \
  --cache-from type=registry,ref=<registry>/<cache-image> .
```

The following table describes the available CSV parameters that you can pass to `--cache-to` and `--cache-from`.

| Name                | Option                  | Type                    | Default | Description                                                                                                                                                                                 |
| ------------------- | ----------------------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref`               | `cache-to`,`cache-from` | String                  |         | Full name of the cache image to import.                                                                                                                                                     |
| `mode`              | `cache-to`              | `min`,`max`             | `min`   | Cache layers to export, see [cache mode](https://docs.docker.com/build/cache/backends/#cache-mode).                                                                                         |
| `oci-mediatypes`    | `cache-to`              | `true`,`false`          | `true`  | Use OCI media types in exported manifests, see [OCI media types](https://docs.docker.com/build/cache/backends/#oci-media-types).                                                            |
| `image-manifest`    | `cache-to`              | `true`,`false`          | `true`  | When using OCI media types, generate an image manifest instead of an image index for the cache image, see [OCI media types](https://docs.docker.com/build/cache/backends/#oci-media-types). |
| `compression`       | `cache-to`              | `gzip`,`estargz`,`zstd` | `gzip`  | Compression type, see [cache compression](https://docs.docker.com/build/cache/backends/#cache-compression).                                                                                 |
| `compression-level` | `cache-to`              | `0..22`                 |         | Compression level, see [cache compression](https://docs.docker.com/build/cache/backends/#cache-compression).                                                                                |
| `force-compression` | `cache-to`              | `true`,`false`          | `false` | Forcibly apply compression, see [cache compression](https://docs.docker.com/build/cache/backends/#cache-compression).                                                                       |
| `ignore-error`      | `cache-to`              | Boolean                 | `false` | Ignore errors caused by failed cache exports.                                                                                                                                               |

You can choose any valid value for `ref`, as long as it's not the same as the target location that you push your image to. You might choose different tags (e.g. `foo/bar:latest` and `foo/bar:build-cache`), separate image names (e.g. `foo/bar` and `foo/bar-cache`), or even different repositories (e.g. `docker.io/foo/bar` and `ghcr.io/foo/bar`). It's up to you to decide the strategy that you want to use for separating your image from your cache images.

If the `--cache-from` target doesn't exist, then the cache import step will fail, but the build continues.

## [Further reading](#further-reading)

For an introduction to caching see [Docker build cache](https://docs.docker.com/build/cache/).

For more information on the `registry` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#registry-push-image-and-cache-separately).

----
url: https://docs.docker.com/reference/cli/docker/pass/
----

# docker pass

***

| Description | Manage your local OS keychain secrets. |
| ----------- | -------------------------------------- |
| Usage       | `docker pass set\|get\|ls\|rm`         |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Docker Pass is a helper for securely storing secrets in your local OS keychain and injecting them into containers when needed. It uses platform-specific credential storage:

* Windows: Windows Credential Manager API
* macOS: Keychain services API
* Linux: org.freedesktop.secrets API (requires DBus + gnome-keyring or kdewallet)

Secrets can be injected into running containers at runtime using the se:// URI scheme.

## [Examples](#examples)

### [Using keychain secrets in containers](#using-keychain-secrets-in-containers)

Create a secret:

```console
$ docker pass set GH_TOKEN=123456789
```

Create a secret from STDIN:

```console
echo "my_val" | docker pass set GH_TOKEN
```

Run a container that uses the secret:

```console
$ docker run -e GH_TOKEN= -dt --name demo busybox
```

Inspect the secret from inside the container:

```console
$ docker exec demo sh -c 'echo $GH_TOKEN'
123456789
```

Explicitly assign a secret to a different environment variable:

```console
$ docker run -e GITHUB_TOKEN=se://GH_TOKEN -dt --name demo busybox
```

### [Using keychain secrets in Compose](#using-keychain-secrets-in-compose)

Store the secrets:

```console
$ docker pass set myapp/anthropic/api-key=sk-ant-...
$ docker pass set myapp/postgres/password=s3cr3t
```

```yaml
services:
  api:
    image: service1
    environment:
      - ANTHROPIC_API_KEY=se://myapp/anthropic/api-key
      - POSTGRES_PASSWORD=se://myapp/postgres/password

  worker:
    image: service2
    command: worker
    environment:
      - ANTHROPIC_API_KEY=se://myapp/anthropic/api-key

  db:
    image: postgres:17
    environment:
      - POSTGRES_PASSWORD=se://myapp/postgres/password
```

## [Subcommands](#subcommands)

| Command                                                                     | Description                           |
| --------------------------------------------------------------------------- | ------------------------------------- |
| [`docker pass get`](https://docs.docker.com/reference/cli/docker/pass/get/) | Get a secret from a keystore.         |
| [`docker pass ls`](https://docs.docker.com/reference/cli/docker/pass/ls/)   | List all secrets from local keychain. |
| [`docker pass rm`](https://docs.docker.com/reference/cli/docker/pass/rm/)   | Remove secrets from local keychain.   |
| [`docker pass set`](https://docs.docker.com/reference/cli/docker/pass/set/) | Set a secret                          |

----
url: https://docs.docker.com/engine/release-notes/18.04/
----

# Docker Engine 18.04 release notes

***

Table of contents

***

## [18.04.0-ce](#18040-ce)

2018-04-10

### [Builder](#builder)

* Fix typos in builder and client. [moby/moby#36424](https://github.com/moby/moby/pull/36424)

### [Client](#client)

* Print Stack API and Kubernetes versions in version command. [docker/cli#898](https://github.com/docker/cli/pull/898)

- Fix Kubernetes duplication in version command. [docker/cli#953](https://github.com/docker/cli/pull/953)

* Use HasAvailableFlags instead of HasFlags for Options in help. [docker/cli#959](https://github.com/docker/cli/pull/959)

- Add support for mandatory variables to stack deploy. [docker/cli#893](https://github.com/docker/cli/pull/893)

* Fix docker stack services command Port output. [docker/cli#943](https://github.com/docker/cli/pull/943)

- Deprecate unencrypted storage. [docker/cli#561](https://github.com/docker/cli/pull/561)
- Don't set a default filename for ConfigFile. [docker/cli#917](https://github.com/docker/cli/pull/917)

* Fix compose network name. [docker/cli#941](https://github.com/docker/cli/pull/941)

### [Logging](#logging)

* Silent login: use credentials from cred store to login. [docker/cli#139](https://github.com/docker/cli/pull/139)

- Add support for compressibility of log file. [moby/moby#29932](https://github.com/moby/moby/pull/29932)

* Fix empty LogPath with non-blocking logging mode. [moby/moby#36272](https://github.com/moby/moby/pull/36272)

### [Networking](#networking)

* Prevent explicit removal of ingress network. [moby/moby#36538](https://github.com/moby/moby/pull/36538)

### [Runtime](#runtime)

* Devmapper cleanup improvements. [moby/moby#36307](https://github.com/moby/moby/pull/36307)
* Devmapper.Mounted: remove. [moby/moby#36437](https://github.com/moby/moby/pull/36437)
* Devmapper/Remove(): use Rmdir, ignore errors. [moby/moby#36438](https://github.com/moby/moby/pull/36438)
* LCOW - Change platform parser directive to FROM statement flag. [moby/moby#35089](https://github.com/moby/moby/pull/35089)
* Split daemon service code to windows file. [moby/moby#36653](https://github.com/moby/moby/pull/36653)
* Windows: Block pulling uplevel images. [moby/moby#36327](https://github.com/moby/moby/pull/36327)
* Windows: Hyper-V containers are broken after 36586 was merged. [moby/moby#36610](https://github.com/moby/moby/pull/36610)
* Windows: Move kernel\_windows to use golang registry functions. [moby/moby#36617](https://github.com/moby/moby/pull/36617)
* Windows: Pass back system errors on container exit. [moby/moby#35967](https://github.com/moby/moby/pull/35967)
* Windows: Remove servicing mode. [moby/moby#36267](https://github.com/moby/moby/pull/36267)
* Windows: Report Version and UBR. [moby/moby#36451](https://github.com/moby/moby/pull/36451)
* Bump Runc to 1.0.0-rc5. [moby/moby#36449](https://github.com/moby/moby/pull/36449)
* Mount failure indicates the path that failed. [moby/moby#36407](https://github.com/moby/moby/pull/36407)
* Change return for errdefs.getImplementer(). [moby/moby#36489](https://github.com/moby/moby/pull/36489)
* Client: fix hijackedconn reading from buffer. [moby/moby#36663](https://github.com/moby/moby/pull/36663)
* Content encoding negotiation added to archive request. [moby/moby#36164](https://github.com/moby/moby/pull/36164)
* Daemon/stats: more resilient cpu sampling. [moby/moby#36519](https://github.com/moby/moby/pull/36519)
* Daemon/stats: remove obnoxious types file. [moby/moby#36494](https://github.com/moby/moby/pull/36494)
* Daemon: use context error rather than inventing new one. [moby/moby#36670](https://github.com/moby/moby/pull/36670)
* Enable CRIU on non-amd64 architectures (v2). [moby/moby#36676](https://github.com/moby/moby/pull/36676)

- Fixes intermittent client hang after closing stdin to attached container [moby/moby#36517](https://github.com/moby/moby/pull/36517)
- Fix daemon panic on container export after restart [moby/moby#36586](https://github.com/moby/moby/pull/36586)
- Follow-up fixes on multi-stage moby's Dockerfile. [moby/moby#36425](https://github.com/moby/moby/pull/36425)

* Freeze busybox and latest glibc in Docker image. [moby/moby#36375](https://github.com/moby/moby/pull/36375)
* If container will run as non root user, drop permitted, effective caps early. [moby/moby#36587](https://github.com/moby/moby/pull/36587)
* Layer: remove metadata store interface. [moby/moby#36504](https://github.com/moby/moby/pull/36504)
* Minor optimizations to dockerd. [moby/moby#36577](https://github.com/moby/moby/pull/36577)
* Whitelist statx syscall. [moby/moby#36417](https://github.com/moby/moby/pull/36417)

- Add missing error return for plugin creation. [moby/moby#36646](https://github.com/moby/moby/pull/36646)

* Fix AppArmor not being applied to Exec processes. [moby/moby#36466](https://github.com/moby/moby/pull/36466)

- Daemon/logger/ring.go: log error not instance. [moby/moby#36475](https://github.com/moby/moby/pull/36475)

* Fix stats collector spinning CPU if no stats are collected. [moby/moby#36609](https://github.com/moby/moby/pull/36609)
* Fix(distribution): digest cache should not be moved if it was an auth. [moby/moby#36509](https://github.com/moby/moby/pull/36509)
* Make sure plugin container is removed on failure. [moby/moby#36715](https://github.com/moby/moby/pull/36715)

- Bump to containerd 1.0.3. [moby/moby#36749](https://github.com/moby/moby/pull/36749)
- Don't sort plugin mount slice. [moby/moby#36711](https://github.com/moby/moby/pull/36711)

### [Swarm Mode](#swarm-mode)

* Fixes for synchronizing the dispatcher shutdown with in-progress rpcs. [moby/moby#36371](https://github.com/moby/moby/pull/36371)
* Increase raft ElectionTick to 10xHeartbeatTick. [moby/moby#36672](https://github.com/moby/moby/pull/36672)
* Make Swarm manager Raft quorum parameters configurable in daemon config. [moby/moby#36726](https://github.com/moby/moby/pull/36726)
* Ingress network should not be attachable. [docker/swarmkit#2523](https://github.com/docker/swarmkit/pull/2523)
* \[manager/state] Add fernet as an option for raft encryption. [docker/swarmkit#2535](https://github.com/docker/swarmkit/pull/2535)
* Log GRPC server errors. [docker/swarmkit#2541](https://github.com/docker/swarmkit/pull/2541)
* Log leadership changes at the manager level. [docker/swarmkit#2542](https://github.com/docker/swarmkit/pull/2542)
* Remove the containerd executor. [docker/swarmkit#2568](https://github.com/docker/swarmkit/pull/2568)
* Agent: backoff session when no remotes are available. [docker/swarmkit#2570](https://github.com/docker/swarmkit/pull/2570)
* \[ca/manager] Remove root CA key encryption support entirely. [docker/swarmkit#2573](https://github.com/docker/swarmkit/pull/2573)

- Fix agent logging race. [docker/swarmkit#2578](https://github.com/docker/swarmkit/pull/2578)

* Adding logic to restore networks in order. [docker/swarmkit#2571](https://github.com/docker/swarmkit/pull/2571)

----
url: https://docs.docker.com/reference/cli/docker/container/export/
----

# docker container export

***

| Description                                                               | Export a container's filesystem as a tar archive |
| ------------------------------------------------------------------------- | ------------------------------------------------ |
| Usage                                                                     | `docker container export [OPTIONS] CONTAINER`    |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker export`                                  |

## [Description](#description)

The `docker export` command doesn't export the contents of volumes associated with the container. If a volume is mounted on top of an existing directory in the container, `docker export` exports the contents of the underlying directory, not the contents of the volume.

Refer to [Backup, restore, or migrate data volumes](/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes) in the user guide for examples on exporting data in a volume.

## [Options](#options)

| Option         | Default | Description                        |
| -------------- | ------- | ---------------------------------- |
| `-o, --output` |         | Write to a file, instead of STDOUT |

## [Examples](#examples)

The following commands produce the same result.

```console
$ docker export red_panda > latest.tar
```

```console
$ docker export --output="latest.tar" red_panda
```

----
url: https://docs.docker.com/get-started/workshop/03_updating_app/
----

# Update the application

***

Table of contents

***

In [part 1](https://docs.docker.com/get-started/workshop/02_our_app/), you containerized a todo application. In this part, you'll update the application and image. You'll also learn how to stop and remove a container.

## [Update the source code](#update-the-source-code)

In the following steps, you'll change the "empty text" when you don't have any todo list items to "You have no todo items yet! Add one above!"

1. In the `src/static/js/app.js` file, update line 56 to use the new empty text.

   ```diff
   - <p className="text-center">No items yet! Add one above!</p>
   + <p className="text-center">You have no todo items yet! Add one above!</p>
   ```

2. Build your updated version of the image, using the `docker build` command.

   ```console
   $ docker build -t getting-started .
   ```

3. Start a new container using the updated code.

   ```console
   $ docker run -dp 127.0.0.1:3000:3000 getting-started
   ```

You probably saw an error like this:

```console
docker: Error response from daemon: driver failed programming external connectivity on endpoint laughing_burnell 
(bb242b2ca4d67eba76e79474fb36bb5125708ebdabd7f45c8eaf16caaabde9dd): Bind for 127.0.0.1:3000 failed: port is already allocated.
```

The error occurred because you aren't able to start the new container while your old container is still running. The reason is that the old container is already using the host's port 3000 and only one process on the machine (containers included) can listen to a specific port. To fix this, you need to remove the old container.

## [Remove the old container](#remove-the-old-container)

To remove a container, you first need to stop it. Once it has stopped, you can remove it. You can remove the old container using the CLI or Docker Desktop's graphical interface. Choose the option that you're most comfortable with.

### [Remove a container using the CLI](#remove-a-container-using-the-cli)

1. Get the ID of the container by using the `docker ps` command.

   ```console
   $ docker ps
   ```

2. Use the `docker stop` command to stop the container. Replace `<the-container-id>` with the ID from `docker ps`.

   ```console
   $ docker stop <the-container-id>
   ```

3. Once the container has stopped, you can remove it by using the `docker rm` command.

   ```console
   $ docker rm <the-container-id>
   ```

> Note
>
> You can stop and remove a container in a single command by adding the `force` flag to the `docker rm` command. For example: `docker rm -f <the-container-id>`

### [Remove a container using Docker Desktop](#remove-a-container-using-docker-desktop)

1. Open Docker Desktop to the **Containers** view.
2. Select the trash can icon under the **Actions** column for the container that you want to delete.
3. In the confirmation dialog, select **Delete forever**.

### [Start the updated app container](#start-the-updated-app-container)

1. Now, start your updated app using the `docker run` command.

   ```console
   $ docker run -dp 127.0.0.1:3000:3000 getting-started
   ```

2. Refresh your browser on <http://localhost:3000> and you should see your updated help text.

## [Summary](#summary)

In this section, you learned how to update and rebuild an image, as well as how to stop and remove a container.

Related information:

* [docker CLI reference](/reference/cli/docker/)

## [Next steps](#next-steps)

Next, you'll learn how to share images with others.

[Share the application](https://docs.docker.com/get-started/workshop/04_sharing_app/)

----
url: https://docs.docker.com/build/ci/github-actions/local-registry/
----

# Local registry with GitHub Actions

***

***

For testing purposes you may need to create a [local registry](https://hub.docker.com/_/registry) to push images into:

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    services:
      registry:
        image: registry:3
        ports:
          - 5000:5000
    steps:
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          driver-opts: network=host
      
      - name: Build and push to local registry
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: localhost:5000/name/app:latest
      
      - name: Inspect
        run: |
          docker buildx imagetools inspect localhost:5000/name/app:latest
```

----
url: https://docs.docker.com/scout/integrations/ci/jenkins/
----

# Integrate Docker Scout with Jenkins

***

***

You can add the following stage and steps definition to a `Jenkinsfile` to run Docker Scout as part of a Jenkins pipeline. The pipeline needs a `DOCKER_HUB` credential containing the username and password for authenticating to Docker Hub. It also needs an environment variable defined for the image and tag.

```groovy
pipeline {
    agent {
        // Agent details
    }

    environment {
        DOCKER_HUB = credentials('jenkins-docker-hub-credentials')
        IMAGE_TAG  = 'myorg/scout-demo-service:latest'
    }

    stages {
        stage('Analyze image') {
            steps {
                // Install Docker Scout
                sh 'curl -sSfL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh | sh -s -- -b /usr/local/bin'

                // Log into Docker Hub
                sh 'echo $DOCKER_HUB_PSW | docker login -u $DOCKER_HUB_USR --password-stdin'

                // Analyze and fail on critical or high vulnerabilities
                sh 'docker scout cves $IMAGE_TAG --exit-code --only-severity critical,high'
            }
        }
    }
}
```

This installs Docker Scout, logs into Docker Hub, and then runs Docker Scout to generate a CVE report for an image and tag. It only shows critical or high-severity vulnerabilities.

> Note
>
> If you're seeing a `permission denied` error related to the image cache, try setting the [`DOCKER_SCOUT_CACHE_DIR`](https://docs.docker.com/scout/how-tos/configure-cli/) environment variable to a writable directory. Or alternatively, disable local caching entirely with `DOCKER_SCOUT_NO_CACHE=true`.

----
url: https://docs.docker.com/reference/cli/docker/network/inspect/
----

# docker network inspect

***

| Description | Display detailed information on one or more networks    |
| ----------- | ------------------------------------------------------- |
| Usage       | `docker network inspect [OPTIONS] NETWORK [NETWORK...]` |

## [Description](#description)

Returns information about one or more networks. By default, this command renders all results in a JSON object.

## [Options](#options)

| Option          | Default | Description                                                                                                                                                                                                                             |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --format`  |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-v, --verbose` |         | Verbose output for diagnostics                                                                                                                                                                                                          |

----
url: https://docs.docker.com/reference/cli/docker/swarm/leave/
----

# docker swarm leave

***

| Description | Leave the swarm                |
| ----------- | ------------------------------ |
| Usage       | `docker swarm leave [OPTIONS]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

When you run this command on a worker, that worker leaves the swarm.

You can use the `--force` option on a manager to remove it from the swarm. However, this does not reconfigure the swarm to ensure that there are enough managers to maintain a quorum in the swarm. The safe way to remove a manager from a swarm is to demote it to a worker and then direct it to leave the quorum without using `--force`. Only use `--force` in situations where the swarm will no longer be used after the manager leaves, such as in a single-node swarm.

## [Options](#options)

| Option        | Default | Description                                           |
| ------------- | ------- | ----------------------------------------------------- |
| `-f, --force` |         | Force this node to leave the swarm, ignoring warnings |

## [Examples](#examples)

Consider the following swarm, as seen from the manager:

```console
$ docker node ls

ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
7ln70fl22uw2dvjn2ft53m3q5    worker2   Ready   Active
dkp8vy1dq1kxleu9g4u78tlag    worker1   Ready   Active
dvfxp4zseq4s0rih1selh0d20 *  manager1  Ready   Active        Leader
```

To remove `worker2`, issue the following command from `worker2` itself:

```console
$ docker swarm leave

Node left the default swarm.
```

The node will still appear in the node list, and marked as `down`. It no longer affects swarm operation, but a long list of `down` nodes can clutter the node list. To remove an inactive node from the list, use the [`node rm`](/reference/cli/docker/node/rm/) command.

----
url: https://docs.docker.com/admin/organization/manage/manage-products/
----

# Docker products

***

Table of contents

***

Subscription: Team Business

For: Administrators

In this section, learn how to manage access and view usage of the Docker products for your organization. For more detailed information about each product, including how to set up and configure them, see the following manuals:

* [Docker Desktop](https://docs.docker.com/desktop/)
* [Docker Hub](https://docs.docker.com/docker-hub/)
* [Docker Build Cloud](https://docs.docker.com/build-cloud/)
* [Docker Scout](https://docs.docker.com/scout/)
* [Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started)
* [Docker Offload](https://docs.docker.com/offload/)

## [Manage product access for your organization](#manage-product-access-for-your-organization)

Access to the Docker products included in your subscription is turned on by default for all users. For an overview of products included in your subscription, see [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs\&refAction=DocsAdminManageProducts).

### [Manage Docker Desktop access](#manage-docker-desktop-access)

To manage Docker Desktop access:

1. [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).
2. Manage members [manually](https://docs.docker.com/admin/organization/manage/members/) or use [provisioning](https://docs.docker.com/enterprise/security/provisioning/).

With sign-in enforced, only users who are a member of your organization can use Docker Desktop after signing in.

### [Manage Docker Hub access](#manage-docker-hub-access)

To manage Docker Hub access, sign in to [Docker Home](https://app.docker.com/) and configure [Registry Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/) or [Image Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/image-access-management/).

### [Manage Docker Build Cloud access](#manage-docker-build-cloud-access)

To initially set up and configure Docker Build Cloud, sign in to [Docker Build Cloud](https://app.docker.com/build) and follow the on-screen instructions.

To manage Docker Build Cloud access:

1. Sign in to [Docker Build Cloud](http://app.docker.com/build) as an organization owner.
2. Select **Account settings**.
3. Select **Lock access to Docker Build Account**.

### [Manage Docker Scout access](#manage-docker-scout-access)

To initially set up and configure Docker Scout, sign in to [Docker Scout](https://scout.docker.com/) and follow the on-screen instructions.

To manage Docker Scout access:

1. Sign in to [Docker Scout](https://scout.docker.com/) as an organization owner.
2. Select your organization, then **Settings**.
3. To manage what repositories are enabled for Docker Scout analysis, select **Repository settings**. For more information on, see [repository settings](https://docs.docker.com/scout/explore/dashboard/#repository-settings).
4. To manage access to Docker Scout for use on local images with Docker Desktop, use [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) and set `sbomIndexing` to `false` to disable, or to `true` to enable.

### [Manage Testcontainers Cloud access](#manage-testcontainers-cloud-access)

To initially set up and configure Testcontainers Cloud, sign in to [Testcontainers Cloud](https://app.testcontainers.cloud/) and follow the on-screen instructions.

To manage access to Testcontainers Cloud:

1. Sign in to the [Testcontainers Cloud](https://app.testcontainers.cloud/) and select **Account**.
2. Select **Settings**, then **Lock access to Testcontainers Cloud**.

### [Manage Docker Offload access](#manage-docker-offload-access)

> Note
>
> Docker Offload isn't included in the core Docker subscription plans. To make Docker Offload available, you must [contact sales](https://www.docker.com/products/docker-offload/) and subscribe.

To manage Docker Offload access for your organization, use [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/):

1. Sign in to [Docker Home](https://app.docker.com/) as an organization owner.

2. Select **Admin Console** > **Desktop Settings Management**.

3. Configure the **Enable Docker Offload** setting to control whether Docker Offload features are available in Docker Desktop. You can configure this setting in five states:

   * **Always enabled**: Docker Offload is always enabled and users cannot disable it. The Offload toggle is always visible in Docker Desktop header. Recommended for VDI environments where local Docker execution is not possible.
   * **Enabled**: Docker Offload is enabled by default but users can disable it in Docker Desktop settings. Suitable for hybrid environments.
   * **Disabled**: Docker Offload is disabled by default but users can enable it in Docker Desktop settings.
   * **Always disabled**: Docker Offload is disabled and users cannot enable it. The option is visible but locked. Use when Docker Offload is not approved for organizational use.
   * **User defined**: No enforced default. Users choose whether to enable or disable Docker Offload in their Docker Desktop settings.

4. Select **Save**.

For more details on Settings Management, see the [Settings reference](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/settings-reference/#enable-docker-offload).

## [Monitor product usage for your organization](#monitor-product-usage-for-your-organization)

To view usage for Docker products:

* Docker Desktop: View the **Insights** page in [Docker Home](https://app.docker.com/). For more details, see [Insights](https://docs.docker.com/admin/insights/).
* Docker Hub: View the [**Usage** page](https://hub.docker.com/usage) in Docker Hub.
* Docker Build Cloud: View the **Build minutes** page in [Docker Build Cloud](http://app.docker.com/build).
* Docker Scout: View the [**Repository settings** page](https://scout.docker.com/settings/repos) in Docker Scout.
* Testcontainers Cloud: View the [**Billing** page](https://app.testcontainers.cloud/dashboard/billing) in Testcontainers Cloud.
* Docker Offload: View the **Offload** > **Offload overview** page in [Docker Home](https://app.docker.com/). For more details, see [Docker Offload usage and billing](https://docs.docker.com/offload/usage/).

If your usage or seat count exceeds your subscription amount, you can [scale your subscription](https://docs.docker.com/subscription/scale/) to meet your needs.

----
url: https://docs.docker.com/dhi/core-concepts/signatures/
----

# Code signing

***

Table of contents

***

## [What is code signing?](#what-is-code-signing)

Code signing is the process of applying a cryptographic signature to software artifacts, such as Docker images, to verify their integrity and authenticity. By signing an image, you ensure that it has not been altered since it was signed and that it originates from a trusted source.

In the context of Docker Hardened Images (DHIs), code signing is achieved using [Cosign](https://docs.sigstore.dev/), a tool developed by the Sigstore project. Cosign enables secure and verifiable signing of container images, enhancing trust and security in the software supply chain.

## [Why is code signing important?](#why-is-code-signing-important)

Code signing plays a crucial role in modern software development and cybersecurity:

* Authenticity: Verifies that the image was created by a trusted source.
* Integrity: Ensures that the image has not been tampered with since it was signed.
* Compliance: Helps meet regulatory and organizational security requirements.

## [Docker Hardened Image code signing](#docker-hardened-image-code-signing)

Each DHI is cryptographically signed using Cosign, ensuring that the images have not been tampered with and originate from a trusted source.

## [Why sign your own images?](#why-sign-your-own-images)

Docker Hardened Images are signed by Docker to prove their origin and integrity, but if you're building application images that extend or use DHIs as a base, you should sign your own images as well.

By signing your own images, you can:

* Prove the image was built by your team or pipeline
* Ensure your build hasn't been tampered with after it's pushed
* Support software supply chain frameworks like SLSA
* Enable image verification in deployment workflows

This is especially important in CI/CD environments where you build and push images frequently, or in any scenario where image provenance must be auditable.

## [How to view and use code signatures](#how-to-view-and-use-code-signatures)

### [View signatures](#view-signatures)

You can verify that a Docker Hardened Image is signed and trusted using either Docker Scout or Cosign.

To lists all attestations, including signature metadata, attached to the image, use the following command:

```console
$ docker scout attest list <image-name>:<tag>
```

> Note
>
> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://dhi.io/python` instead of `dhi.io/python`.

To verify a specific signed attestation (e.g., SBOM, VEX, provenance):

```console
$ docker scout attest get \
  --predicate-type <predicate-uri> \
  --verify \
  <image-name>:<tag>
```

> Note
>
> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://dhi.io/python:3.13` instead of `dhi.io/python:3.13`.

For example:

```console
$ docker scout attest get \
  --predicate-type https://openvex.dev/ns/v0.2.0 \
  --verify \
  dhi.io/python:3.13
```

If valid, Docker Scout will confirm the signature and display signature payload, as well as the equivalent Cosign command to verify the image.

### [Sign images](#sign-images)

To sign a Docker image, use [Cosign](https://docs.sigstore.dev/). Replace `<image-name>:<tag>` with the image name and tag.

```console
$ cosign sign <image-name>:<tag>
```

This command will prompt you to authenticate via an OIDC provider (such as GitHub, Google, or Microsoft). Upon successful authentication, Cosign will generate a short-lived certificate and sign the image. The signature will be stored in a transparency log and associated with the image in the registry.

----
url: https://docs.docker.com/guides/zscaler/
----

[Using Docker with Zscaler](https://docs.docker.com/guides/zscaler/)

This guide explains how to embed Zscaler’s root certificate into Docker images, allowing containers to operate securely with Zscaler proxies and avoid SSL errors.

Networking Administration

10 minutes

[« Back to all guides](/guides/)

# Using Docker with Zscaler

***

Table of contents

***

In many corporate environments, network traffic is intercepted and monitored using HTTPS proxies, such as Zscaler. While Zscaler ensures security compliance and network control, it can cause issues for developers using Docker, particularly during build processes, where SSL certificate validation errors might occur. This guide outlines how to configure Docker containers and builds to properly handle Zscaler's custom certificates, ensuring smooth operation in monitored environments.

## [The role of certificates in Docker](#the-role-of-certificates-in-docker)

When Docker builds or runs containers, it often needs to fetch resources from the internet—whether it's pulling a base image from a registry, downloading dependencies, or communicating with external services. In a proxied environment, Zscaler intercepts HTTPS traffic and replaces the remote server's certificate with its own. However, Docker doesn't trust this Zscaler certificate by default, leading to SSL errors.

```plaintext
x509: certificate signed by unknown authority
```

These errors occur because Docker cannot verify the validity of the certificate presented by Zscaler. To avoid this, you must configure Docker to trust Zscaler's certificate.

## [Configure Zscaler proxy for Docker Desktop](#configure-zscaler-proxy-for-docker-desktop)

Depending on how Zscaler is deployed, you may need to configure Docker Desktop proxy settings manually to use the Zscaler proxy.

If you're using Zscaler as a system-level proxy via the [Zscaler Client Connector](https://help.zscaler.com/zscaler-client-connector/what-is-zscaler-client-connector), all traffic on the device is automatically routed through Zscaler, so Docker Desktop uses the Zscaler proxy automatically with no additional configuration necessary.

If you are not using Zscaler as a system-level proxy, manually configure proxy settings in Docker Desktop. Set up proxy settings for all clients in the organization using [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/), or edit proxy configuration in the Docker Desktop GUI under [**Settings > Resources > Proxies**](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies).

## [Install root certificates in Docker images](#install-root-certificates-in-docker-images)

To enable containers to use and trust the Zscaler proxy, embed the certificate in the image and configure the image's trust store. Installing certificates at image build time is the preferred approach, as it removes the need for configuration during startup and provides an auditable, consistent environment.

### [Obtaining the root certificate](#obtaining-the-root-certificate)

The easiest way to obtain the root certificate is to export it from a machine where an administrator has already installed it. You can use either a web browser or the system's certificate management service (for example, Windows Certificate Store).

#### [Example: Exporting the certificate using Google Chrome](#example-exporting-the-certificate-using-google-chrome)

1. In Google Chrome, navigate to `chrome://certificate-manager/`.
2. Under **Local certificates**, select **View imported certificates**.
3. Find the Zscaler root certificate, often labeled **Zscaler Root CA**.
4. Open the certificate details and select **Export**.
5. Save the certificate in ASCII PEM format.
6. Open the exported file in a text editor to confirm it includes `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`.

When you have obtained the certificate, store it in an accessible repository, such as JFrog Artifactory or a Git repository. Alternatively, use generic storage like AWS S3.

### [Building with the certificate](#building-with-the-certificate)

To install these certificates when building images, copy the certificate into the build container and update the trust store. An example Dockerfile looks like this:

```dockerfile
FROM debian:bookworm
COPY zscaler-root-ca.crt /usr/local/share/ca-certificates/zscaler-root-ca.crt
RUN apt-get update && \
    apt-get install -y ca-certificates && \
    update-ca-certificates
```

Here, `zscaler-root-ca.crt` is the root certificate, located at the root of the build context (often within the application's Git repository).

If you use an artifact repository, you can fetch the certificate directly using the `ADD` instruction. You can also use the `--checksum` flag to verify that the content digest of the certificate is correct.

```dockerfile
FROM debian:bookworm
ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \
    https://artifacts.example/certs/zscaler-root-ca.crt /usr/local/share/ca-certificates/zscaler-root-ca.crt
RUN apt-get update && \
    apt-get install -y ca-certificates && \
    update-ca-certificates
```

#### [Using multi-stage builds](#using-multi-stage-builds)

For multi-stage builds where certificates are needed in the final runtime image, ensure the certificate installation occurs in the final stage.

```dockerfile
FROM debian:bookworm AS build
WORKDIR /build
RUN apt-get update && apt-get install -y \
    build-essential \
    cmake \
    curl \
    git
RUN --mount=target=. cmake -B output/

FROM debian:bookworm-slim AS final
ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d \
    https://artifacts.example/certs/zscaler-root-ca.crt /usr/local/share/ca-certificates/zscaler-root-ca.crt
RUN apt-get update && \
    apt-get install -y ca-certificates && \
    update-ca-certificates
WORKDIR /app
COPY --from=build /build/output/bin .
ENTRYPOINT ["/app/bin"]
```

## [Conclusion](#conclusion)

Embedding the Zscaler root certificate directly into your Docker images ensures that containers run smoothly within Zscaler-proxied environments. By using this approach, you reduce potential runtime errors and create a consistent, auditable configuration that allows for smooth Docker operations within a monitored network.

----
url: https://docs.docker.com/guides/genai-video-bot/
----

[GenAI video transcription and chat](https://docs.docker.com/guides/genai-video-bot/)

Learn how to build and deploy a generative AI video analysis and transcription bot using Docker.

AI

20 minutes

[« Back to all guides](/guides/)

# GenAI video transcription and chat

***

Table of contents

***

## [Overview](#overview)

This guide presents a project on video transcription and analysis using a set of technologies related to the [GenAI Stack](https://www.docker.com/blog/introducing-a-new-genai-stack/).

The project showcases the following technologies:

* [Docker and Docker Compose](#docker-and-docker-compose)
* [OpenAI](#openai-api)
* [Whisper](#whisper)
* [Embeddings](#embeddings)
* [Chat completions](#chat-completions)
* [Pinecone](#pinecone)
* [Retrieval-Augmented Generation](#retrieval-augmented-generation)

> **Acknowledgment**
>
> This guide is a community contribution. Docker would like to thank [David Cardozo](https://www.davidcardozo.com/) for his contribution to this guide.

## [Prerequisites](#prerequisites)

* You have an [OpenAI API Key](https://platform.openai.com/api-keys).

  > Note
  >
  > OpenAI is a third-party hosted service and [charges](https://openai.com/pricing) may apply.

* You have a [Pinecone API Key](https://app.pinecone.io/).

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop.

* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [About the application](#about-the-application)

The application is a chatbot that can answer questions from a video. In addition, it provides timestamps from the video that can help you find the sources used to answer your question.

## [Get and run the application](#get-and-run-the-application)

1. Clone the sample application's repository. In a terminal, run the following command.

   ```console
   $ git clone https://github.com/Davidnet/docker-genai.git
   ```

   The project contains the following directories and files:

   ```text
   ├── docker-genai/
   │ ├── docker-bot/
   │ ├── yt-whisper/
   │ ├── .env.example
   │ ├── .gitignore
   │ ├── LICENSE
   │ ├── README.md
   │ └── docker-compose.yaml
   ```

2. Specify your API keys. In the `docker-genai` directory, create a text file called `.env` and specify your API keys inside. The following is the contents of the `.env.example` file that you can refer to as an example.

   ```text
   #----------------------------------------------------------------------------
   # OpenAI
   #----------------------------------------------------------------------------
   OPENAI_TOKEN=your-api-key # Replace your-api-key with your personal API key

   #----------------------------------------------------------------------------
   # Pinecone
   #----------------------------------------------------------------------------
   PINECONE_TOKEN=your-api-key # Replace your-api-key with your personal API key
   ```

3. Build and run the application. In a terminal, change directory to your `docker-genai` directory and run the following command.

   ```console
   $ docker compose up --build
   ```

   Docker Compose builds and runs the application based on the services defined in the `docker-compose.yaml` file. When the application is running, you'll see the logs of 2 services in the terminal.

   In the logs, you'll see the services are exposed on ports `8503` and `8504`. The two services are complimentary to each other.

   The `yt-whisper` service is running on port `8503`. This service feeds the Pinecone database with videos that you want to archive in your knowledge database. The following section explores this service.

## [Using the yt-whisper service](#using-the-yt-whisper-service)

The yt-whisper service is a YouTube video processing service that uses the OpenAI Whisper model to generate transcriptions of videos and stores them in a Pinecone database. The following steps show how to use the service.

1. Open a browser and access the yt-whisper service at <http://localhost:8503>.

2. Once the application appears, in the **Youtube URL** field specify a Youtube video URL and select **Submit**. The following example uses <https://www.youtube.com/watch?v=yaQZFhrW0fU>.

   The yt-whisper service downloads the audio of the video, uses Whisper to transcribe it into a WebVTT (`*.vtt`) format (which you can download), then uses the text-embedding-3-small model to create embeddings, and finally uploads those embeddings in to the Pinecone database.

   After processing the video, a video list appears in the web app that informs you which videos have been indexed in Pinecone. It also provides a button to download the transcript.

   You can now access the dockerbot service on port `8504` and ask questions about the videos.

## [Using the dockerbot service](#using-the-dockerbot-service)

The dockerbot service is a question-answering service that leverages both the Pinecone database and an AI model to provide responses. The following steps show how to use the service.

> Note
>
> You must process at least one video via the [yt-whisper service](#using-the-yt-whisper-service) before using the dockerbot service.

1. Open a browser and access the service at <http://localhost:8504>.

2. In the **What do you want to know about your videos?** text box, ask the Dockerbot a question about a video that was processed by the yt-whisper service. The following example asks the question, "What is a sugar cookie?". The answer to that question exists in the video processed in the previous example, <https://www.youtube.com/watch?v=yaQZFhrW0fU>.

   In this example, the Dockerbot answers the question and provides links to the video with timestamps, which may contain more information about the answer.

   The dockerbot service takes the question, turns it into an embedding using the text-embedding-3-small model, queries the Pinecone database to find similar embeddings, and then passes that context into the gpt-4-turbo-preview to generate an answer.

3. Select the first link to see what information it provides. Based on the previous example, select <https://www.youtube.com/watch?v=yaQZFhrW0fU&t=553s>.

   In the example link, you can see that the section of video perfectly answers the question, "What is a sugar cookie?".

## [Explore the application architecture](#explore-the-application-architecture)

The following image shows the application's high-level service architecture, which includes:

* yt-whisper: A local service, ran by Docker Compose, that interacts with the remote OpenAI and Pinecone services.
* dockerbot: A local service, ran by Docker Compose, that interacts with the remote OpenAI and Pinecone services.
* OpenAI: A remote third-party service.
* Pinecone: A remote third-party service.

## [Explore the technologies used and their role](#explore-the-technologies-used-and-their-role)

### [Docker and Docker Compose](#docker-and-docker-compose)

The application uses Docker to run the application in containers, providing a consistent and isolated environment for running it. This means the application will operate as intended within its Docker containers, regardless of the underlying system differences. To learn more about Docker, see the [Getting started overview](https://docs.docker.com/get-started/introduction/).

Docker Compose is a tool for defining and running multi-container applications. Compose makes it easy to run this application with a single command, `docker compose up`. For more details, see the [Compose overview](https://docs.docker.com/compose/).

### [OpenAI API](#openai-api)

The OpenAI API provides an LLM service that's known for its cutting-edge AI and machine learning technologies. In this application, OpenAI's technology is used to generate transcriptions from audio (using the Whisper model) and to create embeddings for text data, as well as to generate responses to user queries (using GPT and chat completions). For more details, see [openai.com](https://openai.com/product).

### [Whisper](#whisper)

Whisper is an automatic speech recognition system developed by OpenAI, designed to transcribe spoken language into text. In this application, Whisper is used to transcribe the audio from YouTube videos into text, enabling further processing and analysis of the video content. For more details, see [Introducing Whisper](https://openai.com/research/whisper).

### [Embeddings](#embeddings)

Embeddings are numerical representations of text or other data types, which capture their meaning in a way that can be processed by machine learning algorithms. In this application, embeddings are used to convert video transcriptions into a vector format that can be queried and analyzed for relevance to user input, facilitating efficient search and response generation in the application. For more details, see OpenAI's [Embeddings](https://platform.openai.com/docs/guides/embeddings) documentation.

### [Chat completions](#chat-completions)

Chat completion, as utilized in this application through OpenAI's API, refers to the generation of conversational responses based on a given context or prompt. In the application, it is used to provide intelligent, context-aware answers to user queries by processing and integrating information from video transcriptions and other inputs, enhancing the chatbot's interactive capabilities. For more details, see OpenAI's [Chat Completions API](https://platform.openai.com/docs/guides/text-generation) documentation.

### [Pinecone](#pinecone)

Pinecone is a vector database service optimized for similarity search, used for building and deploying large-scale vector search applications. In this application, Pinecone is employed to store and retrieve the embeddings of video transcriptions, enabling efficient and relevant search functionality within the application based on user queries. For more details, see [pincone.io](https://www.pinecone.io/).

### [Retrieval-Augmented Generation](#retrieval-augmented-generation)

Retrieval-Augmented Generation (RAG) is a technique that combines information retrieval with a language model to generate responses based on retrieved documents or data. In RAG, the system retrieves relevant information (in this case, via embeddings from video transcriptions) and then uses a language model to generate responses based on this retrieved data. For more details, see OpenAI's cookbook for [Retrieval Augmented Generative Question Answering with Pinecone](https://cookbook.openai.com/examples/vector_databases/pinecone/gen_qa).

## [Next steps](#next-steps)

Explore how to [create a PDF bot application](https://docs.docker.com/guides/genai-pdf-bot/) using generative AI, or view more GenAI samples in the [GenAI Stack](https://github.com/docker/genai-stack) repository.

----
url: https://docs.docker.com/guides/nextjs/deploy/
----

# Test your Next.js deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

Before you begin, make sure you've completed the following:

* Complete all the previous sections of this guide, starting with [Containerize Next.js application](https://docs.docker.com/guides/nextjs/containerize/).
* [Enable Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

> **New to Kubernetes?**\
> Visit the [Kubernetes basics tutorial](https://kubernetes.io/docs/tutorials/kubernetes-basics/) to get familiar with how clusters, pods, deployments, and services work.

***

## [Overview](#overview)

This section guides you through deploying your containerized Next.js application locally using [Docker Desktop's built-in Kubernetes](/desktop/kubernetes/). Running your app in a local Kubernetes cluster allows you to closely simulate a real production environment, enabling you to test, validate, and debug your workloads with confidence before promoting them to staging or production.

***

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

Follow these steps to define your deployment configuration:

1. In the root of your project, create a new file named: nextjs-sample-kubernetes.yaml

2. Open the file in your IDE or preferred text editor.

3. Add the following configuration, and be sure to replace `{DOCKER_USERNAME}` and `{DOCKERHUB_PROJECT_NAME}` with your actual Docker Hub username and repository name from the previous [Automate your builds with GitHub Actions](https://docs.docker.com/guides/nextjs/configure-github-actions/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nextjs-sample
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nextjs-sample
  template:
    metadata:
      labels:
        app: nextjs-sample
    spec:
      containers:
        - name: nextjs-container
          image: {DOCKER_USERNAME}/{DOCKERHUB_PROJECT_NAME}:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 3000
          env:
            - name: NODE_ENV
              value: "production"
            - name: HOSTNAME
              value: "0.0.0.0"
---
apiVersion: v1
kind: Service
metadata:
  name:  nextjs-sample-service
  namespace: default
spec:
  type: NodePort
  selector:
    app:  nextjs-sample
  ports:
    - port: 3000
      targetPort: 3000
      nodePort: 30001
```

This manifest defines two key Kubernetes resources, separated by `---`:

* Deployment Deploys a single replica of your Next.js application inside a pod. The pod uses the Docker image built and pushed by your GitHub Actions CI/CD workflow\
  (refer to [Automate your builds with GitHub Actions](https://docs.docker.com/guides/nextjs/configure-github-actions/)).\
  The container listens on port `3000`, which is the default port for Next.js applications.

* Service (NodePort) Exposes the deployed pod to your local machine.\
  It forwards traffic from port `30001` on your host to port `3000` inside the container.\
  This lets you access the application in your browser at <http://localhost:30001>.

> Note
>
> To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

***

## [Deploy and check your application](#deploy-and-check-your-application)

Follow these steps to deploy your containerized Next.js app into a local Kubernetes cluster and verify that it's running correctly.

### [Step 1. Apply the Kubernetes configuration](#step-1-apply-the-kubernetes-configuration)

In your terminal, navigate to the directory where your `nextjs-sample-kubernetes.yaml` file is located, then deploy the resources using:

```console
  $ kubectl apply -f nextjs-sample-kubernetes.yaml
```

If everything is configured properly, you'll see confirmation that both the Deployment and the Service were created:

```shell
  deployment.apps/nextjs-sample created
  service/nextjs-sample-service created
```

This output means that both the Deployment and the Service were successfully created and are now running inside your local cluster.

### [Step 2. Check the deployment status](#step-2-check-the-deployment-status)

Run the following command to check the status of your deployment:

```console
  $ kubectl get deployments
```

You should see an output similar to:

```shell
  NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
  nextjs-sample        1/1     1            1           14s
```

This confirms that your pod is up and running with one replica available.

### [Step 3. Verify the service exposure](#step-3-verify-the-service-exposure)

Check if the NodePort service is exposing your app to your local machine:

```console
$ kubectl get services
```

You should see something like:

```shell
NAME                     TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
nextjs-sample-service    NodePort    10.100.244.65    <none>        3000:30001/TCP   1m
```

This output confirms that your app is available via NodePort on port 30001.

### [Step 4. Access your app in the browser](#step-4-access-your-app-in-the-browser)

Open your browser and navigate to <http://localhost:30001>.

You should see your production-ready Next.js Sample application running — served by your local Kubernetes cluster.

### [Step 5. Clean up Kubernetes resources](#step-5-clean-up-kubernetes-resources)

Once you're done testing, you can delete the deployment and service using:

```console
  $ kubectl delete -f nextjs-sample-kubernetes.yaml
```

Expected output:

```shell
  deployment.apps "nextjs-sample" deleted
  service "nextjs-sample-service" deleted
```

This ensures your cluster stays clean and ready for the next deployment.

***

## [Summary](#summary)

In this section, you learned how to deploy your Next.js application to a local Kubernetes cluster using Docker Desktop. This setup allows you to test and debug your containerized app in a production-like environment before deploying it to the cloud.

What you accomplished:

* Created a Kubernetes Deployment and NodePort Service for your Next.js app
* Used `kubectl apply` to deploy the application locally
* Verified the app was running and accessible at `http://localhost:30001`
* Cleaned up your Kubernetes resources after testing

***

----
url: https://docs.docker.com/desktop/features/usbip/
----

# Using USB/IP with Docker Desktop

***

Table of contents

***

For: Docker Desktop for Mac, Linux, and Windows with the Hyper-V backend

USB/IP enables you to share USB devices over the network, which can then be accessed from within Docker containers. This page focuses on sharing USB devices connected to the machine you run Docker Desktop on. You can repeat the following process to attach and use additional USB devices as needed.

> Note
>
> Docker Desktop includes built-in drivers for many common USB devices but Docker can't guarantee every possible USB device works with this setup.

## [Setup and use](#setup-and-use)

### [Step one: Run a USB/IP server](#step-one-run-a-usbip-server)

To use USB/IP, you need to run a USB/IP server. For this guide, the implementation provided by [jiegec/usbip](https://github.com/jiegec/usbip) will be used.

1. Clone the repository.

   ```console
   $ git clone https://github.com/jiegec/usbip
   $ cd usbip
   ```

2. Run the emulated Human Interface Device (HID) device example.

   ```console
   $ env RUST_LOG=info cargo run --example hid_keyboard
   ```

### [Step two: Start a privileged Docker container](#step-two-start-a-privileged-docker-container)

To attach the USB device, start a privileged Docker container with the PID namespace set to `host`:

```console
$ docker run --rm -it --privileged --pid=host alpine
```

`--privileged` gives the container full access to the host, and `--pid=host` allows it to share the host’s process namespace.

### [Step three: Enter the mount namespace of PID 1](#step-three-enter-the-mount-namespace-of-pid-1)

Inside the container, enter the mount namespace of the `init` process to gain access to the pre-installed USB/IP tools:

```console
$ nsenter -t 1 -m
```

### [Step four: Use the USB/IP tools](#step-four-use-the-usbip-tools)

Now you can use the USB/IP tools as you would on any other system:

#### [List USB devices](#list-usb-devices)

To list exportable USB devices from the host:

```console
$ usbip list -r host.docker.internal
```

Expected output:

```console
Exportable USB devices
======================
 - host.docker.internal
      0-0-0: unknown vendor : unknown product (0000:0000)
           : /sys/bus/0/0/0
           : (Defined at Interface level) (00/00/00)
           :  0 - unknown class / unknown subclass / unknown protocol (03/00/00)
```

#### [Attach a USB device](#attach-a-usb-device)

To attach a specific USB device, or the emulated keyboard in this case:

```console
$ usbip attach -r host.docker.internal -d 0-0-0
```

#### [Verify device attachment](#verify-device-attachment)

After attaching the emulated keyboard, check the `/dev/input` directory for the device node:

```console
$ ls /dev/input/
```

Example output:

```console
event0  mice
```

### [Step five: Access the device from another container](#step-five-access-the-device-from-another-container)

While the initial container remains running to keep the USB device operational, you can access the attached device from another container. For example:

1. Start a new container with the attached device.

   ```console
   $ docker run --rm -it --device "/dev/input/event0" alpine
   ```

2. Install a tool like `evtest` to test the emulated keyboard.

   ```console
   $ apk add evtest
   $ evtest /dev/input/event0
   ```

3. Interact with the device, and observe the output.

   Example output:

   ```console
   Input driver version is 1.0.1
   Input device ID: bus 0x3 vendor 0x0 product 0x0 version 0x111
   ...
   Properties:
   Testing ... (interrupt to exit)
   Event: time 1717575532.881540, type 4 (EV_MSC), code 4 (MSC_SCAN), value 7001e
   Event: time 1717575532.881540, type 1 (EV_KEY), code 2 (KEY_1), value 1
   Event: time 1717575532.881540, -------------- SYN_REPORT ------------
   ...
   ```

> Important
>
> The initial container must remain running to maintain the connection to the USB device. Exiting the container will stop the device from working.

----
url: https://docs.docker.com/compose/how-tos/environment-variables/best-practices/
----

# Best practices for working with environment variables in Docker Compose

***

Table of contents

***

#### [Handle sensitive information securely](#handle-sensitive-information-securely)

Be cautious about including sensitive data in environment variables. Consider using [Secrets](https://docs.docker.com/compose/how-tos/use-secrets/) for managing sensitive information.

#### [Understand environment variable precedence](#understand-environment-variable-precedence)

Be aware of how Docker Compose handles the [precedence of environment variables](https://docs.docker.com/compose/how-tos/environment-variables/envvars-precedence/) from different sources (`.env` files, shell variables, Dockerfiles).

#### [Use specific environment files](#use-specific-environment-files)

Consider how your application adapts to different environments. For example development, testing, production, and use different `.env` files as needed.

#### [Know interpolation](#know-interpolation)

Understand how [interpolation](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) works within compose files for dynamic configurations.

#### [Command line overrides](#command-line-overrides)

Be aware that you can [override environment variables](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/#cli) from the command line when starting containers. This is useful for testing or when you have temporary changes.

----
url: https://docs.docker.com/guides/angular/configure-github-actions/
----

# Automate your builds with GitHub Actions

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize an Angular application](https://docs.docker.com/guides/angular/containerize/).

You must also have:

* A [GitHub](https://github.com/signup) account.
* A verified [Docker Hub](https://hub.docker.com/signup) account.

***

## [Overview](#overview)

In this section, you'll set up a CI/CD pipeline using [GitHub Actions](https://docs.github.com/en/actions) to automatically:

* Build your Angular application inside a Docker container.
* Run tests in a consistent environment.
* Push the production-ready image to [Docker Hub](https://hub.docker.com).

***

## [Connect your GitHub repository to Docker Hub](#connect-your-github-repository-to-docker-hub)

To enable GitHub Actions to build and push Docker images, you’ll securely store your Docker Hub credentials in your new GitHub repository.

### [Step 1: Generate Docker Hub credentials and set GitHub secrets](#step-1-generate-docker-hub-credentials-and-set-github-secrets)

1. Create a Personal Access Token (PAT) from [Docker Hub](https://hub.docker.com)

   1. Go to your **Docker Hub account → Account Settings → Security**.
   2. Generate a new Access Token with **Read/Write** permissions.
   3. Name it something like `docker-angular-sample`.
   4. Copy and save the token — you’ll need it in Step 4.

2. Create a repository in [Docker Hub](https://hub.docker.com/repositories/)

   1. Go to your **Docker Hub account → Create a repository**.
   2. For the Repository Name, use something descriptive — for example: `angular-sample`.
   3. Once created, copy and save the repository name — you’ll need it in Step 4.

3. Create a new [GitHub repository](https://github.com/new) for your Angular project

4. Add Docker Hub credentials as GitHub repository secrets

   In your newly created GitHub repository:

   1. Navigate to: **Settings → Secrets and variables → Actions → New repository secret**.

   2. Add the following secrets:

   | Name                     | Value                                            |
   | ------------------------ | ------------------------------------------------ |
   | `DOCKER_USERNAME`        | Your Docker Hub username                         |
   | `DOCKERHUB_TOKEN`        | Your Docker Hub access token (created in Step 1) |
   | `DOCKERHUB_PROJECT_NAME` | Your Docker Project Name (created in Step 2)     |

   These secrets allow GitHub Actions to authenticate securely with Docker Hub during automated workflows.

5. Connect Your Local Project to GitHub

   Link your local project `docker-angular-sample` to the GitHub repository you just created by running the following command from your project root:

   ```console
      $ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git
   ```

   > Important
   >
   > Replace `{your-username}` and `{your-repository}` with your actual GitHub username and repository name.

   To confirm that your local project is correctly connected to the remote GitHub repository, run:

   ```console
   $ git remote -v
   ```

   You should see output similar to:

   ```console
   origin  https://github.com/{your-username}/{your-repository-name}.git (fetch)
   origin  https://github.com/{your-username}/{your-repository-name}.git (push)
   ```

   This confirms that your local repository is properly linked and ready to push your source code to GitHub.

6. Push your source code to GitHub

   Follow these steps to commit and push your local project to your GitHub repository:

   1. Stage all files for commit.

      ```console
      $ git add -A
      ```

      This command stages all changes — including new, modified, and deleted files — preparing them for commit.

   2. Commit the staged changes with a descriptive message.

      ```console
      $ git commit -m "Initial commit"
      ```

      This command creates a commit that snapshots the staged changes with a descriptive message.

   3. Push the code to the `main` branch.

      ```console
      $ git push -u origin main
      ```

      This command pushes your local commits to the `main` branch of the remote GitHub repository and sets the upstream branch.

Once completed, your code will be available on GitHub, and any GitHub Actions workflow you’ve configured will run automatically.

> Note
>
> Learn more about the Git commands used in this step:
>
> * [Git add](https://git-scm.com/docs/git-add) – Stage changes (new, modified, deleted) for commit
> * [Git commit](https://git-scm.com/docs/git-commit) – Save a snapshot of your staged changes
> * [Git push](https://git-scm.com/docs/git-push) – Upload local commits to your GitHub repository
> * [Git remote](https://git-scm.com/docs/git-remote) – View and manage remote repository URLs

***

### [Step 2: Set up the workflow](#step-2-set-up-the-workflow)

Now you'll create a GitHub Actions workflow that builds your Docker image, runs tests, and pushes the image to Docker Hub.

1. Go to your repository on GitHub and select the **Actions** tab in the top menu.

2. Select **Set up a workflow yourself** when prompted.

   This opens an inline editor to create a new workflow file. By default, it will be saved to: `.github/workflows/main.yml`

3. Add the following workflow configuration to the new file:

```yaml
name: CI/CD – Angular Application with Docker

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

jobs:
  build-test-push:
    name: Build, Test, and Push Docker Image
    runs-on: ubuntu-latest

    steps:
      # 1. Checkout source code
      - name: Checkout source code
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      # 2. Set up Docker Buildx
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      # 3. Cache Docker layers
      - name: Cache Docker layers
        uses: actions/cache@v5
        with:
          path: /tmp/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-buildx-

      # 4. Cache npm dependencies
      - name: Cache npm dependencies
        uses: actions/cache@v5
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-npm-

      # 5. Extract metadata
      - name: Extract metadata
        id: meta
        run: |
          echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT"
          echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"

      # 6. Build dev Docker image
      - name: Build Docker image for tests
        uses: docker/build-push-action@v7
        with:
          context: .
          file: Dockerfile.dev
          tags: ${{ steps.meta.outputs.REPO_NAME }}-dev:latest
          load: true
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache,mode=max

      # 7. Run Angular tests with Jasmine
      - name: Run Angular Jasmine tests inside container
        run: |
          docker run --rm \
            --workdir /app \
            --entrypoint "" \
            ${{ steps.meta.outputs.REPO_NAME }}-dev:latest \
            sh -c "npm ci && npm run test -- --ci --runInBand"
        env:
          CI: true
          NODE_ENV: test
        timeout-minutes: 10

      # 8. Log in to Docker Hub
      - name: Log in to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      # 9. Build and push production image
      - name: Build and push production image
        uses: docker/build-push-action@v7
        with:
          context: .
          file: Dockerfile
          push: true
          platforms: linux/amd64,linux/arm64
          tags: |
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }}
          cache-from: type=local,src=/tmp/.buildx-cache
```

This workflow performs the following tasks for your Angular application:

> Note
>
> For more information about `docker/build-push-action`, refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md).

***

### [Step 3: Run the workflow](#step-3-run-the-workflow)

After you've added your workflow file, it's time to trigger and observe the CI/CD process in action.

1. Commit and push your workflow file

   * Select "Commit changes…" in the GitHub editor.


     * Repository name: `${your-repository-name}`

     * Tags include:

       * `latest` – represents the most recent successful build; ideal for quick testing or deployment.
       * `<short-sha>` – a unique identifier based on the commit hash, useful for version tracking, rollbacks, and traceability.

> Tip
>
> To maintain code quality and prevent accidental direct pushes, enable branch protection rules:
>
> * Navigate to your **GitHub repo → Settings → Branches**.
>
> * Under Branch protection rules, click **Add rule**.
>
> * Specify `main` as the branch name.
>
> * Enable options like:
>
>   * *Require a pull request before merging*.
>   * *Require status checks to pass before merging*.
>
> This ensures that only tested and reviewed code is merged into `main` branch.

***

## [Summary](#summary)

In this section, you set up a complete CI/CD pipeline for your containerized Angular application using GitHub Actions.

With this setup, your Angular application is now ready for automated testing and deployment across environments — increasing confidence, consistency, and team productivity.

***

***

## [Next steps](#next-steps)

Next, learn how you can locally test and debug your Angular workloads on Kubernetes before deploying. This helps you ensure your application behaves as expected in a production-like environment, reducing surprises during deployment.

[Test your Angular deployment »](https://docs.docker.com/guides/angular/deploy/)

----
url: https://docs.docker.com/build/metadata/attestations/slsa-provenance/
----

# Provenance attestations

***

Table of contents

***

The provenance attestations include facts about the build process, including details such as:

* Build timestamps
* Build parameters and environment
* Version control metadata
* Source code details
* Materials (files, scripts) consumed during the build

By default, provenance attestations follow the [SLSA provenance schema, version 0.2](https://slsa.dev/spec/v0.2/provenance#schema). You can optionally enable [SLSA Provenance v1](https://slsa.dev/spec/v1.1/provenance#schema) using [the `version` parameter](#version).

For more information about how BuildKit populates these provenance properties, refer to [SLSA definitions](https://docs.docker.com/build/metadata/attestations/slsa-definitions/).

## [Create provenance attestations](#create-provenance-attestations)

To create a provenance attestation, pass the `--attest type=provenance` option to the `docker buildx build` command:

```console
$ docker buildx build --tag <namespace>/<image>:<version> \
    --attest type=provenance,mode=[min,max],version=[v0.2,v1] .
```

Alternatively, you can use the shorthand `--provenance=true` option instead of `--attest type=provenance`. To specify the `mode` or `version` parameters using the shorthand option, use: `--provenance=mode=max,version=v1`.

For an example on how to add provenance attestations with GitHub Actions, see [Add attestations with GitHub Actions](https://docs.docker.com/build/ci/github-actions/attestations/).

## [Mode](#mode)

You can use the `mode` parameter to define the level of detail to be included in the provenance attestation. Supported values are `mode=min` (default) and `mode=max`.

### [Min](#min)

In `min` mode, the provenance attestations include a minimal set of information, such as:

* Build timestamps
* The frontend used
* Build materials
* Source repository and revision
* Build platform
* Reproducibility

Values of build arguments, the identities of secrets, and rich layer metadata are not included in `mode=min`. The `min`-level provenance is safe to use for all builds, as it doesn't leak information from any part of the build environment.

The following JSON example shows the information included in a provenance attestations created using the `min` mode:

```json
{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://slsa.dev/provenance/v0.2",
  "subject": [
    {
      "name": "pkg:docker/<registry>/<image>@<tag/digest>?platform=<platform>",
      "digest": {
        "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862"
      }
    }
  ],
  "predicate": {
    "builder": { "id": "" },
    "buildType": "https://mobyproject.org/buildkit@v1",
    "materials": [
      {
        "uri": "pkg:docker/docker/dockerfile@1",
        "digest": {
          "sha256": "9ba7531bd80fb0a858632727cf7a112fbfd19b17e94c4e84ced81e24ef1a0dbc"
        }
      },
      {
        "uri": "pkg:docker/golang@1.19.4-alpine?platform=linux%2Farm64",
        "digest": {
          "sha256": "a9b24b67dc83b3383d22a14941c2b2b2ca6a103d805cac6820fd1355943beaf1"
        }
      }
    ],
    "invocation": {
      "configSource": { "entryPoint": "Dockerfile" },
      "parameters": {
        "frontend": "gateway.v0",
        "args": {
          "cmdline": "docker/dockerfile:1",
          "source": "docker/dockerfile:1",
          "target": "binaries"
        },
        "locals": [{ "name": "context" }, { "name": "dockerfile" }]
      },
      "environment": { "platform": "linux/arm64" }
    },
    "metadata": {
      "buildInvocationID": "c4a87v0sxhliuewig10gnsb6v",
      "buildStartedOn": "2022-12-16T08:26:28.651359794Z",
      "buildFinishedOn": "2022-12-16T08:26:29.625483253Z",
      "reproducible": false,
      "completeness": {
        "parameters": true,
        "environment": true,
        "materials": false
      },
      "https://mobyproject.org/buildkit@v1#metadata": {
        "vcs": {
          "revision": "a9ba846486420e07d30db1107411ac3697ecab68",
          "source": "git@github.com:<org>/<repo>.git"
        }
      }
    }
  }
}
```

### [Max](#max)

The `max` mode includes all of the information included in the `min` mode, as well as:

* The LLB definition of the build. These show the exact steps taken to produce the image.
* Information about the Dockerfile, including a full base64-encoded version of the file.
* Source maps describing the relationship between build steps and image layers.

When possible, you should prefer `mode=max` as it contains significantly more detailed information for analysis.

> Warning
>
> Note that `mode=max` exposes the values of [build arguments](/reference/cli/docker/buildx/build/#build-arg).
>
> If you're misusing build arguments to pass credentials, authentication tokens, or other secrets, you should refactor your build to pass the secrets using [secret mounts](/reference/cli/docker/buildx/build/#secret) instead. Secret mounts don't leak outside of the build and are never included in provenance attestations.

## [Version](#version)

The `version` parameter lets you specify which SLSA provenance schema version to use. Supported values are `version=v0.2` (default) and `version=v1`.

To use SLSA Provenance v1:

```console
$ docker buildx build --tag <namespace>/<image>:<version> \
    --attest type=provenance,mode=max,version=v1 .
```

For more information about SLSA Provenance v1, see the [SLSA specification](https://slsa.dev/spec/v1.1/provenance). To see the difference between SLSA v0.2 and v1 provenance attestations, refer to [SLSA definitions](https://docs.docker.com/build/metadata/attestations/slsa-definitions/)

## [Inspecting Provenance](#inspecting-provenance)

To explore created Provenance exported through the `image` exporter, you can use [`imagetools inspect`](/reference/cli/docker/buildx/imagetools/inspect/).

Using the `--format` option, you can specify a template for the output. All provenance-related data is available under the `.Provenance` attribute. For example, to get the raw contents of the Provenance in the SLSA format:

```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
    --format "{{ json .Provenance.SLSA }}"
{
  "buildType": "https://mobyproject.org/buildkit@v1",
  ...
}
```

You can also construct more complex expressions using the full functionality of Go templates. For example, for provenance generated with `mode=max`, you can extract the full source code of the Dockerfile used to build the image:

```console
$ docker buildx imagetools inspect <namespace>/<image>:<version> \
    --format '{{ range (index .Provenance.SLSA.metadata "https://mobyproject.org/buildkit@v1#metadata").source.infos }}{{ if eq .filename "Dockerfile" }}{{ .data }}{{ end }}{{ end }}' | base64 -d
FROM ubuntu:24.04
RUN apt-get update
...
```

## [Provenance attestation example](#provenance-attestation-example)

The following example shows what a JSON representation of a provenance attestation with `mode=max` looks like:

```json
{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://slsa.dev/provenance/v0.2",
  "subject": [
    {
      "name": "pkg:docker/<registry>/<image>@<tag/digest>?platform=<platform>",
      "digest": {
        "sha256": "e8275b2b76280af67e26f068e5d585eb905f8dfd2f1918b3229db98133cb4862"
      }
    }
  ],
  "predicate": {
    "builder": { "id": "" },
    "buildType": "https://mobyproject.org/buildkit@v1",
    "materials": [
      {
        "uri": "pkg:docker/docker/dockerfile@1",
        "digest": {
          "sha256": "9ba7531bd80fb0a858632727cf7a112fbfd19b17e94c4e84ced81e24ef1a0dbc"
        }
      },
      {
        "uri": "pkg:docker/golang@1.19.4-alpine?platform=linux%2Farm64",
        "digest": {
          "sha256": "a9b24b67dc83b3383d22a14941c2b2b2ca6a103d805cac6820fd1355943beaf1"
        }
      }
    ],
    "buildConfig": {
      "llbDefinition": [
        {
          "id": "step4",
          "op": {
            "Op": {
              "exec": {
                "meta": {
                  "args": ["/bin/sh", "-c", "go mod download -x"],
                  "env": [
                    "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                    "GOLANG_VERSION=1.19.4",
                    "GOPATH=/go",
                    "CGO_ENABLED=0"
                  ],
                  "cwd": "/src"
                },
                "mounts": [
                  { "input": 0, "dest": "/", "output": 0 },
                  {
                    "input": -1,
                    "dest": "/go/pkg/mod",
                    "output": -1,
                    "mountType": 3,
                    "cacheOpt": { "ID": "//go/pkg/mod" }
                  },
                  {
                    "input": 1,
                    "selector": "/go.mod",
                    "dest": "/src/go.mod",
                    "output": -1,
                    "readonly": true
                  },
                  {
                    "input": 1,
                    "selector": "/go.sum",
                    "dest": "/src/go.sum",
                    "output": -1,
                    "readonly": true
                  }
                ]
              }
            },
            "platform": { "Architecture": "arm64", "OS": "linux" },
            "constraints": {}
          },
          "inputs": ["step3:0", "step1:0"]
        }
      ]
    },
    "metadata": {
      "buildInvocationID": "edf52vxjyf9b6o5qd7vgx0gru",
      "buildStartedOn": "2022-12-15T15:38:13.391980297Z",
      "buildFinishedOn": "2022-12-15T15:38:14.274565297Z",
      "reproducible": false,
      "completeness": {
        "parameters": true,
        "environment": true,
        "materials": false
      },
      "https://mobyproject.org/buildkit@v1#metadata": {
        "vcs": {
          "revision": "a9ba846486420e07d30db1107411ac3697ecab68-dirty",
          "source": "git@github.com:<org>/<repo>.git"
        },
        "source": {
          "locations": {
            "step4": {
              "locations": [
                {
                  "ranges": [
                    { "start": { "line": 5 }, "end": { "line": 5 } },
                    { "start": { "line": 6 }, "end": { "line": 6 } },
                    { "start": { "line": 7 }, "end": { "line": 7 } },
                    { "start": { "line": 8 }, "end": { "line": 8 } }
                  ]
                }
              ]
            }
          },
          "infos": [
            {
              "filename": "Dockerfile",
              "data": "RlJPTSBhbHBpbmU6bGF0ZXN0Cg==",
              "llbDefinition": [
                {
                  "id": "step0",
                  "op": {
                    "Op": {
                      "source": {
                        "identifier": "local://dockerfile",
                        "attrs": {
                          "local.differ": "none",
                          "local.followpaths": "[\"Dockerfile\",\"Dockerfile.dockerignore\",\"dockerfile\"]",
                          "local.session": "s4j58ngehdal1b5hn7msiqaqe",
                          "local.sharedkeyhint": "dockerfile"
                        }
                      }
                    },
                    "constraints": {}
                  }
                },
                { "id": "step1", "op": { "Op": null }, "inputs": ["step0:0"] }
              ]
            }
          ]
        },
        "layers": {
          "step2:0": [
            [
              {
                "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
                "digest": "sha256:261da4162673b93e5c0e7700a3718d40bcc086dbf24b1ec9b54bca0b82300626",
                "size": 3259190
              },
              {
                "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
                "digest": "sha256:bc729abf26b5aade3c4426d388b5ea6907fe357dec915ac323bb2fa592d6288f",
                "size": 286218
              },
              {
                "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
                "digest": "sha256:7f1d6579712341e8062db43195deb2d84f63b0f2d1ed7c3d2074891085ea1b56",
                "size": 116878653
              },
              {
                "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
                "digest": "sha256:652874aefa1343799c619d092ab9280b25f96d97939d5d796437e7288f5599c9",
                "size": 156
              }
            ]
          ]
        }
      }
    }
  }
}
```

----
url: https://docs.docker.com/ai/docker-agent/integrations/acp/
----

# ACP integration

***

Table of contents

***

Run agents directly in your editor using the Agent Client Protocol (ACP). Your agent gets access to your editor's filesystem context and can read and modify files as you work. The editor handles file operations while Docker Agent provides the AI capabilities.

This guide shows you how to configure Neovim, or Zed to run agents with Docker Agent. If you're looking to expose agents as tools to MCP clients like Claude Desktop or Claude Code, see [MCP integration](https://docs.docker.com/ai/docker-agent/integrations/mcp/) instead.

## [How it works](#how-it-works)

When you run Docker Agent with ACP, it becomes part of your editor's environment. You select code, highlight a function, or reference a file - the agent sees what you see. No copying file paths or switching to a terminal.

Ask "explain this function" and the agent reads the file you're viewing. Ask it to "add error handling" and it edits the code right in your editor. The agent works with your editor's view of the project, not some external file system it has to navigate.

The difference from running Docker Agent in a terminal: file operations go through your editor instead of the agent directly accessing your filesystem. When the agent needs to read or write a file, it requests it from your editor. This keeps the agent's view of your code synchronized with yours - same working directory, same files, same state.

## [Prerequisites](#prerequisites)

Before configuring your editor, you need:

* **Docker Agent installed** - See the [installation guide](https://docs.docker.com/ai/docker-agent/#installation)
* **Agent configuration** - A YAML file defining your agent. See the [tutorial](https://docs.docker.com/ai/docker-agent/tutorial/) or [example configurations](https://github.com/docker/docker-agent/tree/main/examples)
* **Editor with ACP support** - Neovim, Intellij, Zed, etc.

Your agents will use model provider API keys from your shell environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.). Make sure these are set before launching your editor.

## [Editor configuration](#editor-configuration)

### [Zed](#zed)

Zed has built-in ACP support.

1. Add `docker agent` to your agent servers in `settings.json`:

   ```json
   {
     "agent_servers": {
       "my-agent-team": {
         "command": "docker",
         "args": ["agent", "serve", "acp", "agent.yml"]
       }
     }
   }
   ```

   Replace:

   * `my-agent-team` with the name you want to use for the agent
   * `agent.yml` with the path to your agent configuration file.

   If you have multiple agent files that you like to run separately, you can create multiple entries under `agent_servers` for each agent.

2. Start a new external agent thread. Select your agent in the drop-down list.

### [Neovim](#neovim)

Use the [CodeCompanion](https://github.com/olimorris/codecompanion.nvim) plugin, which has native support for Docker Agent through a built-in adapter:

1. [Install CodeCompanion](https://codecompanion.olimorris.dev/installation) through your plugin manager.

2. Extend the `dockeragent` adapter in your CodeCompanion config:

   ```lua
   require("codecompanion").setup({
     adapters = {
       acp = {
         dockeragent = function()
           return require("codecompanion.adapters").extend("dockeragent", {
             commands = {
               default = {
                 "docker",
                 "agent", 
                 "serve",
                 "acp",
                 "agent.yml",
               },
             },
           })
         end,
       },
     },
   })
   ```

   Replace `agent.yml` with the path to your agent configuration file. If you have multiple agent files that you like to run separately, you can create multiple commands for each agent.

3. Restart Neovim and launch CodeCompanion:

   ```plaintext
   :CodeCompanion
   ```

4. Switch to the Docker Agent adapter (keymap `ga` in the CodeCompanion buffer, by default).

See the [CodeCompanion ACP documentation](https://codecompanion.olimorris.dev/usage/acp-protocol) for more information about ACP support in CodeCompanion. Note that terminal operations are not supported, so [toolsets](https://docs.docker.com/ai/docker-agent/reference/toolsets/) like `shell` or `script_shell` are not usable through CodeCompanion.

## [Agent references](#agent-references)

You can specify your agent configuration as a local file path or OCI registry reference:

```console
# Local file path
$ docker agent serve acp ./agent.yml

# OCI registry reference
$ docker agent serve acp agentcatalog/pirate
$ docker agent serve acp dockereng/myagent:v1.0.0
```

Use the same syntax in your editor configuration:

```json
{
  "agent_servers": {
    "myagent": {
      "command": "docker",
      "args": ["agent", "serve", "acp", "agentcatalog/pirate"]
    }
  }
}
```

Registry references enable team sharing, version management, and clean configuration without local file paths. See [Sharing agents](https://docs.docker.com/ai/docker-agent/sharing-agents/) for details on using OCI registries.

## [Testing your setup](#testing-your-setup)

Verify your configuration works:

1. Start the Docker Agent ACP server using your editor's configured method
2. Send a test prompt through your editor's interface
3. Check that the agent responds
4. Verify filesystem operations work by asking the agent to read a file

If the agent starts but can't access files or perform other actions, check:

* Working directory in your editor is set correctly to your project root
* Agent configuration file path is absolute or relative to working directory
* Your editor or plugin properly implements ACP protocol features

## [What's next](#whats-next)

* Review the [configuration reference](https://docs.docker.com/ai/docker-agent/reference/config/) for advanced agent setup
* Explore the [toolsets reference](https://docs.docker.com/ai/docker-agent/reference/toolsets/) to learn what tools are available
* Add [RAG for codebase search](https://docs.docker.com/ai/docker-agent/rag/) to your agent
* Check the [CLI reference](https://docs.docker.com/ai/docker-agent/reference/cli/) for all `docker agent serve acp` options
* Browse [example configurations](https://github.com/docker/docker-agent/tree/main/examples) for inspiration

----
url: https://docs.docker.com/reference/cli/docker/image/ls/
----

# docker image ls

***

| Description                                                               | List images                                    |
| ------------------------------------------------------------------------- | ---------------------------------------------- |
| Usage                                                                     | `docker image ls [OPTIONS] [REPOSITORY[:TAG]]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker image list` `docker images`            |

## [Description](#description)

The default `docker images` will show all top level images, their repository and tags, and their size.

Docker images have intermediate layers that increase reusability, decrease disk usage, and speed up `docker build` by allowing each step to be cached. These intermediate layers are not shown by default.

Untagged (dangling) images are also hidden by default. Use the `-a` (`--all`) flag to show intermediate layers and dangling images.

The `SIZE` is the cumulative space taken up by the image and all its parent images. This is also the disk space used by the contents of the Tar file created when you `docker save` an image.

An image will be listed more than once if it has multiple repository names or tags. This single image (identifiable by its matching `IMAGE ID`) uses up the `SIZE` listed only once.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-a, --all`               |         | Show all images (default hides intermediate and dangling images)                                                                                                                                                                                                                                                                                                                       |
| [`--digests`](#digests)   |         | Show digests                                                                                                                                                                                                                                                                                                                                                                           |
| [`-f, --filter`](#filter) |         | Filter output based on conditions provided                                                                                                                                                                                                                                                                                                                                             |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| [`--no-trunc`](#no-trunc) |         | Don't truncate output                                                                                                                                                                                                                                                                                                                                                                  |
| `-q, --quiet`             |         | Only show image IDs                                                                                                                                                                                                                                                                                                                                                                    |
| `--tree`                  |         | API 1.47+ experimental (CLI) List multi-platform images as a tree (EXPERIMENTAL)                                                                                                                                                                                                                                                                                                       |

## [Examples](#examples)

### [List the most recently created images](#list-the-most-recently-created-images)

```console
$ docker images

REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
<none>                    <none>              77af4d6b9913        19 hours ago        1.089 GB
committ                   latest              b6fa739cedf5        19 hours ago        1.089 GB
<none>                    <none>              78a85c484f71        19 hours ago        1.089 GB
docker                    latest              30557a29d5ab        20 hours ago        1.089 GB
<none>                    <none>              5ed6274db6ce        24 hours ago        1.089 GB
postgres                  9                   746b819f315e        4 days ago          213.4 MB
postgres                  9.3                 746b819f315e        4 days ago          213.4 MB
postgres                  9.3.5               746b819f315e        4 days ago          213.4 MB
postgres                  latest              746b819f315e        4 days ago          213.4 MB
```

### [List images by name and tag](#list-images-by-name-and-tag)

The `docker images` command takes an optional `[REPOSITORY[:TAG]]` argument that restricts the list to images that match the argument. If you specify `REPOSITORY`but no `TAG`, the `docker images` command lists all images in the given repository.

For example, to list all images in the `java` repository, run the following command:

```console
$ docker images java

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
java                8                   308e519aac60        6 days ago          824.5 MB
java                7                   493d82594c15        3 months ago        656.3 MB
java                latest              2711b1d6f3aa        5 months ago        603.9 MB
```

The `[REPOSITORY[:TAG]]` value must be an exact match. This means that, for example, `docker images jav` does not match the image `java`.

If both `REPOSITORY` and `TAG` are provided, only images matching that repository and tag are listed. To find all local images in the `java` repository with tag `8` you can use:

```console
$ docker images java:8

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
java                8                   308e519aac60        6 days ago          824.5 MB
```

If nothing matches `REPOSITORY[:TAG]`, the list is empty.

```console
$ docker images java:0

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
```

### [List the full length image IDs (--no-trunc)](#no-trunc)

```console
$ docker images --no-trunc

REPOSITORY                    TAG                 IMAGE ID                                                                  CREATED             SIZE
<none>                        <none>              sha256:77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182   19 hours ago        1.089 GB
committest                    latest              sha256:b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f   19 hours ago        1.089 GB
<none>                        <none>              sha256:78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921   19 hours ago        1.089 GB
docker                        latest              sha256:30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4   20 hours ago        1.089 GB
<none>                        <none>              sha256:0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5   20 hours ago        1.089 GB
<none>                        <none>              sha256:18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b   22 hours ago        1.082 GB
<none>                        <none>              sha256:f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a   23 hours ago        1.089 GB
tryout                        latest              sha256:2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074   23 hours ago        131.5 MB
<none>                        <none>              sha256:5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df   24 hours ago        1.089 GB
```

### [List image digests (--digests)](#digests)

Images that use the v2 or later format have a content-addressable identifier called a `digest`. As long as the input used to generate the image is unchanged, the digest value is predictable. To list image digest values, use the `--digests` flag:

```console
$ docker images --digests
REPOSITORY                         TAG                 DIGEST                                                                    IMAGE ID            CREATED             SIZE
localhost:5000/test/busybox        <none>              sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf   4986bf8c1536        9 weeks ago         2.43 MB
```

When pushing or pulling to a 2.0 registry, the `push` or `pull` command output includes the image digest. You can `pull` using a digest value. You can also reference by digest in `create`, `run`, and `rmi` commands, as well as the `FROM` image reference in a Dockerfile.

### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).

The currently supported filters are:

* dangling (boolean - true or false)
* label (`label=<key>` or `label=<key>=<value>`)
* before (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created before given id or references
* since (`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) - filter images created since given id or references
* reference (pattern of an image reference) - filter images whose reference matches the specified pattern

#### [Show untagged images (dangling)](#show-untagged-images-dangling)

```console
$ docker images --filter "dangling=true"

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
<none>              <none>              8abc22fbb042        4 weeks ago         0 B
<none>              <none>              48e5f45168b9        4 weeks ago         2.489 MB
<none>              <none>              bf747efa0e2f        4 weeks ago         0 B
<none>              <none>              980fe10e5736        12 weeks ago        101.4 MB
<none>              <none>              dea752e4e117        12 weeks ago        101.4 MB
<none>              <none>              511136ea3c5a        8 months ago        0 B
```

This will display untagged images that are the leaves of the images tree (not intermediary layers). These images occur when a new build of an image takes the `repo:tag` away from the image ID, leaving it as `<none>:<none>` or untagged. A warning will be issued if trying to remove an image when a container is presently using it. By having this flag it allows for batch cleanup.

You can use this in conjunction with `docker rmi`:

```console
$ docker rmi $(docker images -f "dangling=true" -q)

8abc22fbb042
48e5f45168b9
bf747efa0e2f
980fe10e5736
dea752e4e117
511136ea3c5a
```

Docker warns you if any containers exist that are using these untagged images.

#### [Show images with a given label](#show-images-with-a-given-label)

The `label` filter matches images based on the presence of a `label` alone or a `label` and a value.

The following filter matches images with the `com.example.version` label regardless of its value.

```console
$ docker images --filter "label=com.example.version"

REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
match-me-1          latest              eeae25ada2aa        About a minute ago   188.3 MB
match-me-2          latest              dea752e4e117        About a minute ago   188.3 MB
```

The following filter matches images with the `com.example.version` label with the `1.0` value.

```console
$ docker images --filter "label=com.example.version=1.0"

REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
match-me            latest              511136ea3c5a        About a minute ago   188.3 MB
```

In this example, with the `0.1` value, it returns an empty set because no matches were found.

```console
$ docker images --filter "label=com.example.version=0.1"
REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
```

#### [Filter images by time](#filter-images-by-time)

The `before` filter shows only images created before the image with a given ID or reference. For example, having these images:

```console
$ docker images

REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
image2              latest              dea752e4e117        9 minutes ago        188.3 MB
image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
```

Filtering with `before` would give:

```console
$ docker images --filter "before=image1"

REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
image2              latest              dea752e4e117        9 minutes ago        188.3 MB
image3              latest              511136ea3c5a        25 minutes ago       188.3 MB
```

Filtering with `since` would give:

```console
$ docker images --filter "since=image3"
REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
image1              latest              eeae25ada2aa        4 minutes ago        188.3 MB
image2              latest              dea752e4e117        9 minutes ago        188.3 MB
```

#### [Filter images by reference](#filter-images-by-reference)

The `reference` filter shows only images whose reference matches the specified pattern.

```console
$ docker images

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
busybox             latest              e02e811dd08f        5 weeks ago         1.09 MB
busybox             uclibc              e02e811dd08f        5 weeks ago         1.09 MB
busybox             musl                733eb3059dce        5 weeks ago         1.21 MB
busybox             glibc               21c16b6787c6        5 weeks ago         4.19 MB
```

Filtering with `reference` would give:

```console
$ docker images --filter=reference='busy*:*libc'

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
busybox             uclibc              e02e811dd08f        5 weeks ago         1.09 MB
busybox             glibc               21c16b6787c6        5 weeks ago         4.19 MB
```

Filtering with multiple `reference` would give, either match A or B:

```console
$ docker images --filter=reference='busy*:uclibc' --filter=reference='busy*:glibc'

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
busybox             uclibc              e02e811dd08f        5 weeks ago         1.09 MB
busybox             glibc               21c16b6787c6        5 weeks ago         4.19 MB
```

### [Format the output (--format)](#format)

The formatting option (`--format`) will pretty print container output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder     | Description                              |
| --------------- | ---------------------------------------- |
| `.ID`           | Image ID                                 |
| `.Repository`   | Image repository                         |
| `.Tag`          | Image tag                                |
| `.Digest`       | Image digest                             |
| `.CreatedSince` | Elapsed time since the image was created |
| `.CreatedAt`    | Time when the image was created          |
| `.Size`         | Image disk size                          |

When using the `--format` option, the `image` command will either output the data exactly as the template declares or, when using the `table` directive, will include column headers as well.

The following example uses a template without headers and outputs the `ID` and `Repository` entries separated by a colon (`:`) for all images:

```console
$ docker images --format "{{.ID}}: {{.Repository}}"

77af4d6b9913: <none>
b6fa739cedf5: committ
78a85c484f71: <none>
30557a29d5ab: docker
5ed6274db6ce: <none>
746b819f315e: postgres
746b819f315e: postgres
746b819f315e: postgres
746b819f315e: postgres
```

To list all images with their repository and tag in a table format you can use:

```console
$ docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID            REPOSITORY                TAG
77af4d6b9913        <none>                    <none>
b6fa739cedf5        committ                   latest
78a85c484f71        <none>                    <none>
30557a29d5ab        docker                    latest
5ed6274db6ce        <none>                    <none>
746b819f315e        postgres                  9
746b819f315e        postgres                  9.3
746b819f315e        postgres                  9.3.5
746b819f315e        postgres                  latest
```

To list all images in JSON format, use the `json` directive:

```console
$ docker images --format json
{"Containers":"N/A","CreatedAt":"2021-03-04 03:24:42 +0100 CET","CreatedSince":"5 days ago","Digest":"\u003cnone\u003e","ID":"4dd97cefde62","Repository":"ubuntu","SharedSize":"N/A","Size":"72.9MB","Tag":"latest","UniqueSize":"N/A"}
{"Containers":"N/A","CreatedAt":"2021-02-17 22:19:54 +0100 CET","CreatedSince":"2 weeks ago","Digest":"\u003cnone\u003e","ID":"28f6e2705743","Repository":"alpine","SharedSize":"N/A","Size":"5.61MB","Tag":"latest","UniqueSize":"N/A"}
```

----
url: https://docs.docker.com/guides/testcontainers-java-spring-boot-kafka/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Testing Spring Boot Kafka Listener using Testcontainers

Table of contents

***

Learn how to create a Spring Boot application with a Kafka listener that persists data in MySQL, then test it using Testcontainers Kafka and MySQL modules with Awaitility.

**Time to complete** 25 minutes

In this guide, you will learn how to:

* Create a Spring Boot application with Kafka integration
* Implement a Kafka listener and persist data in a MySQL database
* Test the Kafka listener using Testcontainers and Awaitility

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-spring-boot-kafka/create-project/)

   Set up a Spring Boot project with Kafka, Spring Data JPA, and MySQL.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-spring-boot-kafka/write-tests/)

   Test the Spring Boot Kafka listener using Testcontainers Kafka and MySQL modules with Awaitility.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-spring-boot-kafka/run-tests/)

   Run your Testcontainers-based Spring Boot Kafka integration tests and explore next steps.

----
url: https://docs.docker.com/guides/ruby/containerize/
----

# Containerize a Ruby on Rails application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [Git client](https://git-scm.com/downloads). The examples in this section show the Git CLI, but you can use any client.

## [Overview](#overview)

This section walks you through containerizing and running a [Ruby on Rails](https://rubyonrails.org/) application.

Starting from Rails 7.1 [Docker is supported out of the box](https://guides.rubyonrails.org/7_1_release_notes.html#generate-dockerfiles-for-new-rails-applications). This means that you will get a `Dockerfile`, `.dockerignore` and `bin/docker-entrypoint` files generated for you when you create a new Rails application.

If you have an existing Rails application, you will need to create the Docker assets manually from the examples below.

## [1. Create Docker assets](#1-create-docker-assets)

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

Rails 7.1 and newer generates multistage Dockerfile out of the box. Following are two versions of such a file: one using Docker Hardened Images (DHIs) and another using the Docker Official Image (DOIs). Although the Dockerfile is generated automatically, understanding its purpose and functionality is important. Reviewing the following example is highly recommended.

[Docker Hardened Images (DHIs)](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. DHIs are recommended whenever it is possible for better security. They are designed to reduce vulnerabilities and simplify compliance, freely available to everyone with no subscription required, no usage restrictions, and no vendor lock-in.

Multistage Dockerfiles help create smaller, more efficient images by separating build and runtime dependencies, ensuring only necessary components are included in the final image. Read more in the [Multi-stage builds guide](/get-started/docker-concepts/building-images/multi-stage-builds/).

You must authenticate to `dhi.io` before you can pull Docker Hardened Images. Run `docker login dhi.io` to authenticate.

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=error=true

# This Dockerfile is designed for production, not development.
# docker build -t app .
# docker run -d -p 80:80 -e RAILS_MASTER_KEY=<value from config/master.key> --name app app

# For a containerized dev environment, see Dev Containers: https://guides.rubyonrails.org/getting_started_with_devcontainer.html

# Make sure RUBY_VERSION matches the Ruby version in .ruby-version
ARG RUBY_VERSION=3.4.8
FROM dhi.io/ruby:$RUBY_VERSION-dev AS base

# Rails app lives here
WORKDIR /rails

# Install base packages
# Replace libpq-dev with sqlite3 if using SQLite, or libmysqlclient-dev if using MySQL
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y curl libjemalloc2 libvips libpq-dev && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

# Set production environment
ENV RAILS_ENV="production" \
    BUNDLE_DEPLOYMENT="1" \
    BUNDLE_PATH="/usr/local/bundle" \
    BUNDLE_WITHOUT="development"

# Throw-away build stage to reduce size of final image
FROM base AS build

# Install packages needed to build gems
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y build-essential curl git pkg-config libyaml-dev && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

# Install JavaScript dependencies and Node.js for asset compilation
#
# Uncomment the following lines if you are using NodeJS need to compile assets
#
# ARG NODE_VERSION=18.12.0
# ARG YARN_VERSION=1.22.19
# ENV PATH=/usr/local/node/bin:$PATH
# RUN curl -sL https://github.com/nodenv/node-build/archive/master.tar.gz | tar xz -C /tmp/ && \
#     /tmp/node-build-master/bin/node-build "${NODE_VERSION}" /usr/local/node && \
#     npm install -g yarn@$YARN_VERSION && \
#     npm install -g mjml && \
#     rm -rf /tmp/node-build-master

# Install application gems
COPY Gemfile Gemfile.lock ./
RUN bundle install && \
    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \
    bundle exec bootsnap precompile --gemfile

# Install node modules
#
# Uncomment the following lines if you are using NodeJS need to compile assets
#
# COPY package.json yarn.lock ./
# RUN --mount=type=cache,id=yarn,target=/rails/.cache/yarn YARN_CACHE_FOLDER=/rails/.cache/yarn \
#     yarn install --frozen-lockfile

# Copy application code
COPY . .

# Precompile bootsnap code for faster boot times
RUN bundle exec bootsnap precompile app/ lib/

# Precompiling assets for production without requiring secret RAILS_MASTER_KEY
RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile

# Final stage for app image
FROM base

# Copy built artifacts: gems, application
COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
COPY --from=build /rails /rails

# Run and own only the runtime files as a non-root user for security
RUN groupadd --system --gid 1000 rails && \
    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \
    chown -R rails:rails db log storage tmp
USER 1000:1000

# Entrypoint prepares the database.
ENTRYPOINT ["/rails/bin/docker-entrypoint"]

# Start server via Thruster by default, this can be overwritten at runtime
EXPOSE 80
CMD ["./bin/thrust", "./bin/rails", "server"]
```

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=error=true

# This Dockerfile is designed for production, not development.
# docker build -t app .
# docker run -d -p 80:80 -e RAILS_MASTER_KEY=<value from config/master.key> --name app app

# For a containerized dev environment, see Dev Containers: https://guides.rubyonrails.org/getting_started_with_devcontainer.html

# Make sure RUBY_VERSION matches the Ruby version in .ruby-version
ARG RUBY_VERSION=3.4.8
FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base

# Rails app lives here
WORKDIR /rails

# Install base packages
# Replace libpq-dev with sqlite3 if using SQLite, or libmysqlclient-dev if using MySQL
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y curl libjemalloc2 libvips libpq-dev && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

# Set production environment
ENV RAILS_ENV="production" \
    BUNDLE_DEPLOYMENT="1" \
    BUNDLE_PATH="/usr/local/bundle" \
    BUNDLE_WITHOUT="development"

# Throw-away build stage to reduce size of final image
FROM base AS build

# Install packages needed to build gems
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y build-essential curl git pkg-config libyaml-dev && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

# Install JavaScript dependencies and Node.js for asset compilation
#
# Uncomment the following lines if you are using NodeJS need to compile assets
#
# ARG NODE_VERSION=18.12.0
# ARG YARN_VERSION=1.22.19
# ENV PATH=/usr/local/node/bin:$PATH
# RUN curl -sL https://github.com/nodenv/node-build/archive/master.tar.gz | tar xz -C /tmp/ && \
#     /tmp/node-build-master/bin/node-build "${NODE_VERSION}" /usr/local/node && \
#     npm install -g yarn@$YARN_VERSION && \
#     npm install -g mjml && \
#     rm -rf /tmp/node-build-master

# Install application gems
COPY Gemfile Gemfile.lock ./
RUN bundle install && \
    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git && \
    bundle exec bootsnap precompile --gemfile

# Install node modules
#
# Uncomment the following lines if you are using NodeJS need to compile assets
#
# COPY package.json yarn.lock ./
# RUN --mount=type=cache,id=yarn,target=/rails/.cache/yarn YARN_CACHE_FOLDER=/rails/.cache/yarn \
#     yarn install --frozen-lockfile

# Copy application code
COPY . .

# Precompile bootsnap code for faster boot times
RUN bundle exec bootsnap precompile app/ lib/

# Precompiling assets for production without requiring secret RAILS_MASTER_KEY
RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile

# Final stage for app image
FROM base

# Copy built artifacts: gems, application
COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
COPY --from=build /rails /rails

# Run and own only the runtime files as a non-root user for security
RUN groupadd --system --gid 1000 rails && \
    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \
    chown -R rails:rails db log storage tmp
USER 1000:1000

# Entrypoint prepares the database.
ENTRYPOINT ["/rails/bin/docker-entrypoint"]

# Start server via Thruster by default, this can be overwritten at runtime
EXPOSE 80
CMD ["./bin/thrust", "./bin/rails", "server"]
```

The Dockerfile above assumes you are using Thruster together with Puma as an application server. In case you are using any other server, you can replace the last three lines with the following:

```dockerfile
# Start the application server
EXPOSE 3000
CMD ["./bin/rails", "server"]
```

This Dockerfile uses a script at `./bin/docker-entrypoint` as the container's entrypoint. This script prepares the database and runs the application server. Below is an example of such a script.

docker-entrypoint

```bash
#!/bin/bash -e

# Enable jemalloc for reduced memory usage and latency.
if [ -z "${LD_PRELOAD+x}" ]; then
    LD_PRELOAD=$(find /usr/lib -name libjemalloc.so.2 -print -quit)
    export LD_PRELOAD
fi

# If running the rails server then create or migrate existing database
if [ "${@: -2:1}" == "./bin/rails" ] && [ "${@: -1:1}" == "server" ]; then
  ./bin/rails db:prepare
fi

exec "${@}"
```

Besides the two files above you will also need a `.dockerignore` file. This file is used to exclude files and directories from the context of the build. Below is an example of a `.dockerignore` file.

.dockerignore

```text
# See https://docs.docker.com/engine/reference/builder/#dockerignore-file for more about ignoring files.

# Ignore git directory.
/.git/
/.gitignore

# Ignore bundler config.
/.bundle

# Ignore all environment files.
/.env*

# Ignore all default key files.
/config/master.key
/config/credentials/*.key

# Ignore all logfiles and tempfiles.
/log/*
/tmp/*
!/log/.keep
!/tmp/.keep

# Ignore pidfiles, but keep the directory.
/tmp/pids/*
!/tmp/pids/.keep

# Ignore storage (uploaded files in development and any SQLite databases).
/storage/*
!/storage/.keep
/tmp/storage/*
!/tmp/storage/.keep

# Ignore assets.
/node_modules/
/app/assets/builds/*
!/app/assets/builds/.keep
/public/assets

# Ignore CI service files.
/.github

# Ignore development files
/.devcontainer

# Ignore Docker-related files
/.dockerignore
/Dockerfile*
```

The last optional file that you may want is the `compose.yaml` file, which is used by Docker Compose to define the services that make up the application. Since SQLite is being used as the database, there is no need to define a separate service for the database. The only service required is the Rails application itself.

compose.yaml

```yaml
services:
  web:
    build: .
    environment:
      - RAILS_MASTER_KEY
    ports:
      - "3000:80"
```

You should now have the following files in your application folder:

* `.dockerignore`
* `compose.yaml`
* `Dockerfile`
* `bin/docker-entrypoint`

To learn more about the files, see the following:

* [Dockerfile](/reference/dockerfile)
* [.dockerignore](/reference/dockerfile#dockerignore-file)
* [compose.yaml](https://docs.docker.com/reference/compose-file/)
* [docker-entrypoint](/reference/dockerfile/#entrypoint)

## [2. Run the application](#2-run-the-application)

To run the application, run the following command in a terminal inside the application's directory.

```console
$ RAILS_MASTER_KEY=<master_key_value> docker compose up --build
```

Open a browser and view the application at <http://localhost:3000>. You should see a simple Ruby on Rails application.

In the terminal, press `ctrl`+`c` to stop the application.

## [3. Run the application in the background](#3-run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `docker-ruby-on-rails` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:3000>.

You should see a simple Ruby on Rails application.

In the terminal, run the following command to stop the application.

```console
$ docker compose down
```

For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

## [Summary](#summary)

In this section, you learned how you can containerize and run your Ruby application using Docker.

Related information:

* [Docker Compose overview](https://docs.docker.com/compose/)

## [Next steps](#next-steps)

In the next section, you'll take a look at how to set up a CI/CD pipeline using GitHub Actions.

[Automate your builds with GitHub Actions »](https://docs.docker.com/guides/ruby/configure-github-actions/)

----
url: https://docs.docker.com/extensions/marketplace/
----

# Marketplace extensions

***

Table of contents

***

There are two types of extensions available in the Extensions Marketplace:

* Docker-reviewed extensions
* Self-published extensions

Docker-reviewed extensions are manually reviewed by the Docker Extensions team to ensure an extra level of trust and quality. They appear as **Reviewed** in the Marketplace.

Self-published extensions are autonomously published by extension developers and go through an automated validation process. They appear as **Not reviewed** in the Marketplace.

> Important
>
> Marketplace extensions are reviewed by Docker, but are not subject to a full security audit. Extensions run with host-level privileges. They can install binaries, access Docker Engine, invoke commands, and access files on your machine. Only install extensions from publishers you trust.

## [Install an extension](#install-an-extension)

> Note
>
> For some extensions, a separate account needs to be created before use.

To install an extension:

1. Open Docker Desktop.
2. From the Docker Desktop Dashboard, select the **Extensions** tab. The Extensions Marketplace opens on the **Browse** tab.
3. Browse the available extensions. You can sort the list of extensions by **Recently added**, **Most installed**, or alphabetically. Alternatively, use the **Content** or **Categories** drop-down menu to search for extensions by whether they have been reviewed or not, or by category.
4. Choose an extension and select **Install**.

From here, you can select **Open** to access the extension or install additional extensions. The extension also appears in the left-hand menu and in the **Manage** tab.

## [Update an extension](#update-an-extension)

You can update any extension outside of Docker Desktop releases. To update an extension to the latest version, navigate to the Docker Desktop Dashboard and select the **Manage** tab.

The **Manage** tab displays with all your installed extensions. If an extension has a new version available, it displays an **Update** button.

## [Uninstall an extension](#uninstall-an-extension)

You can uninstall an extension at any time.

> Note
>
> Any data used by the extension that's stored in a volume must be manually deleted.

1. Navigate to the Docker Desktop Dashboard and select the **Manage** tab. This displays a list of extensions you've installed.
2. Select the ellipsis to the right of extension you want to uninstall.
3. Select **Uninstall**.

----
url: https://docs.docker.com/engine/release-notes/17.07/
----

# Docker Engine 17.07 release notes

***

Table of contents

***

## [17.07.0-ce](#17070-ce)

2017-08-29

### [API & Client](#api--client)

* Add support for proxy configuration in config.json [docker/cli#93](https://github.com/docker/cli/pull/93)
* Enable pprof/debug endpoints by default [moby/moby#32453](https://github.com/moby/moby/pull/32453)
* Passwords can now be passed using `STDIN` using the new `--password-stdin` flag on `docker login` [docker/cli#271](https://github.com/docker/cli/pull/271)

- Add `--detach` to docker scale [docker/cli#243](https://github.com/docker/cli/pull/243)

* Prevent `docker logs --no-stream` from hanging due to non-existing containers [moby/moby#34004](https://github.com/moby/moby/pull/34004)

- Fix `docker stack ps` printing error to `stdout` instead of `stderr` [docker/cli#298](https://github.com/docker/cli/pull/298)

* Fix progress bar being stuck on `docker service create` if an error occurs during deploy [docker/cli#259](https://github.com/docker/cli/pull/259)
* Improve presentation of progress bars in interactive mode [docker/cli#260](https://github.com/docker/cli/pull/260) [docker/cli#237](https://github.com/docker/cli/pull/237)
* Print a warning if `docker login --password` is used, and recommend `--password-stdin` [docker/cli#270](https://github.com/docker/cli/pull/270)
* Make API version negotiation more robust [moby/moby#33827](https://github.com/moby/moby/pull/33827)
* Hide `--detach` when connected to daemons older than Docker 17.05 [docker/cli#219](https://github.com/docker/cli/pull/219)

- Add `scope` filter in `GET /networks/(id or name)` [moby/moby#33630](https://github.com/moby/moby/pull/33630)

### [Builder](#builder)

* Implement long running interactive session and sending build context incrementally [moby/moby#32677](https://github.com/moby/moby/pull/32677) [docker/cli#231](https://github.com/docker/cli/pull/231) [moby/moby#33859](https://github.com/moby/moby/pull/33859)
* Warn on empty continuation lines [moby/moby#33719](https://github.com/moby/moby/pull/33719)

- Fix `.dockerignore` entries with a leading `/` not matching anything [moby/moby#32088](https://github.com/moby/moby/pull/32088)

### [Logging](#logging)

* Fix wrong filemode for rotate log files [moby/moby#33926](https://github.com/moby/moby/pull/33926)
* Fix stderr logging for journald and syslog [moby/moby#33832](https://github.com/moby/moby/pull/33832)

### [Runtime](#runtime)

* Allow stopping of paused container [moby/moby#34027](https://github.com/moby/moby/pull/34027)

- Add quota support for the overlay2 storage driver [moby/moby#32977](https://github.com/moby/moby/pull/32977)

* Remove container locks on `docker ps` [moby/moby#31273](https://github.com/moby/moby/pull/31273)
* Store container names in memdb [moby/moby#33886](https://github.com/moby/moby/pull/33886)
* Fix race condition between `docker exec` and `docker pause` [moby/moby#32881](https://github.com/moby/moby/pull/32881)
* Devicemapper: Rework logging and add `--storage-opt dm.libdm_log_level` [moby/moby#33845](https://github.com/moby/moby/pull/33845)
* Devicemapper: Prevent "device in use" errors if deferred removal is enabled, but not deferred deletion [moby/moby#33877](https://github.com/moby/moby/pull/33877)
* Devicemapper: Use KeepAlive to prevent tasks being garbage-collected while still in use [moby/moby#33376](https://github.com/moby/moby/pull/33376)
* Report intermediate prune results if prune is cancelled [moby/moby#33979](https://github.com/moby/moby/pull/33979)

- Fix run `docker rename <container-id> new_name` concurrently resulting in the having multiple names [moby/moby#33940](https://github.com/moby/moby/pull/33940)

* Fix file-descriptor leak and error handling [moby/moby#33713](https://github.com/moby/moby/pull/33713)

- Fix SIGSEGV when running containers [docker/cli#303](https://github.com/docker/cli/pull/303)

* Prevent a goroutine leak when healthcheck gets stopped [moby/moby#33781](https://github.com/moby/moby/pull/33781)

* Image: Improve store locking [moby/moby#33755](https://github.com/moby/moby/pull/33755)

* Fix Btrfs quota groups not being removed when container is destroyed [moby/moby#29427](https://github.com/moby/moby/pull/29427)

* Libcontainerd: fix defunct containerd processes not being properly reaped [moby/moby#33419](https://github.com/moby/moby/pull/33419)

* Preparations for Linux Containers on Windows

  * LCOW: Dedicated scratch space for service VM utilities [moby/moby#33809](https://github.com/moby/moby/pull/33809)
  * LCOW: Support most operations excluding remote filesystem [moby/moby#33241](https://github.com/moby/moby/pull/33241) [moby/moby#33826](https://github.com/moby/moby/pull/33826)
  * LCOW: Change directory from lcow to "Linux Containers" [moby/moby#33835](https://github.com/moby/moby/pull/33835)
  * LCOW: pass command arguments without extra quoting [moby/moby#33815](https://github.com/moby/moby/pull/33815)
  * LCOW: Updates necessary due to platform schema change [moby/moby#33785](https://github.com/moby/moby/pull/33785)

### [Swarm mode](#swarm-mode)

* Initial support for pluggable secret backends [moby/moby#34157](https://github.com/moby/moby/pull/34157) [moby/moby#34123](https://github.com/moby/moby/pull/34123)
* Sort swarm stacks and nodes using natural sorting [docker/cli#315](https://github.com/docker/cli/pull/315)
* Make engine support cluster config event [moby/moby#34032](https://github.com/moby/moby/pull/34032)
* Only pass a join address when in the process of joining a cluster [moby/moby#33361](https://github.com/moby/moby/pull/33361)
* Fix error during service creation if a network with the same name exists both as "local" and "swarm" scoped network [docker/cli#184](https://github.com/docker/cli/pull/184)
* (experimental) Add support for plugins on swarm [moby/moby#33575](https://github.com/moby/moby/pull/33575)

----
url: https://docs.docker.com/security/security-announcements/
----

# Docker security announcements

***

Table of contents

***

[Subscribe to security RSS feed](/security/security-announcements/index.xml)

## [Docker Desktop 4.71.0 security update: CVE-2026-5843](#docker-desktop-4710-security-update-cve-2026-5843)

A vulnerability in Docker Desktop was fixed on April 27 in the [4.71.0](https://docs.docker.com/desktop/release-notes/#4710) release:

* Addressed [CVE-2026-5843](https://www.cve.org/cverecord?id=CVE-2026-5843), container-to-host code execution in the Docker Model Runner MLX inference backend.

## [Docker Desktop 4.68.0 security update: CVE-2026-5817](#docker-desktop-4680-security-update-cve-2026-5817)

A vulnerability in Docker Desktop was fixed on April 7 in the [4.68.0](https://docs.docker.com/desktop/release-notes/#4680) release:

* Addressed [CVE-2026-5817](https://www.cve.org/cverecord?id=CVE-2026-5817), container-to-host code execution in the Docker Model Runner vllm-metal inference backend.

## [Docker Desktop 4.67.0 security update: CVE-2026-33990](#docker-desktop-4670-security-update-cve-2026-33990)

A vulnerability in Docker Desktop was fixed on March 30 in the [4.67.0](https://docs.docker.com/desktop/release-notes/#4670) release:

* Addressed [CVE-2026-33990](https://www.cve.org/cverecord?id=CVE-2026-33990), SSRF in Docker Model Runner OCI Registry Client

## [Docker Desktop 4.62.0 security update: CVE-2026-28400](#docker-desktop-4620-security-update-cve-2026-28400)

A vulnerability in Docker Desktop was fixed on February 23 in the [4.62.0](https://docs.docker.com/desktop/release-notes/#4620) release:

* Addressed [CVE-2026-28400](https://www.cve.org/cverecord?id=CVE-2026-28400), runtime flag injection in Docker Model Runner.

## [Docker Desktop 4.62.0 security update: CVE-2026-2664](#docker-desktop-4620-security-update-cve-2026-2664)

A vulnerability in Docker Desktop was fixed on February 23 in the [4.62.0](https://docs.docker.com/desktop/release-notes/#4620) release:

* Fixed [CVE-2026-2664](https://www.cve.org/cverecord?id=CVE-2026-2664), out of bounds read in gRPC-FUSE kernel module.

## [Docker Desktop 4.54.0 security update: CVE-2025-13743](#docker-desktop-4540-security-update-cve-2025-13743)

A vulnerability in Docker Desktop was fixed on December 4 in the [4.54.0](https://docs.docker.com/desktop/release-notes/#4540) release:

* Fixed [CVE-2025-13743](https://www.cve.org/cverecord?id=CVE-2025-13743) where Docker Desktop diagnostics bundles were found to include expired Hub PATs in log output due to error object serialization.

## [Docker Desktop 4.49.0 security update: CVE-2025-9164](#docker-desktop-4490-security-update-cve-2025-9164)

A vulnerability in Docker Desktop for Windows was fixed on October 23 in the [4.49.0](https://docs.docker.com/desktop/release-notes/#4490) release:

* Fixed [CVE-2025-9164](https://www.cve.org/cverecord?id=CVE-2025-9164) where the Docker Desktop for Windows installer was vulnerable to DLL hijacking due to insecure DLL search order. The installer searches for required DLLs in the user's Downloads folder before checking system directories, allowing local privilege escalation through malicious DLL placement.

## [Docker Desktop 4.47.0 security update: CVE-2025-10657](#docker-desktop-4470-security-update-cve-2025-10657)

A vulnerability in Docker Desktop was fixed on September 25 in the [4.47.0](https://docs.docker.com/desktop/release-notes/#4470) release:

* Fixed [CVE-2025-10657](https://www.cve.org/CVERecord?id=CVE-2025-10657) where the Enhanced Container Isolation [Docker Socket command restrictions](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/#command-restrictions) feature was not working properly in Docker Desktop 4.46.0 only (the configuration for it was being ignored).

## [Docker Desktop 4.44.3 security update: CVE-2025-9074](#docker-desktop-4443-security-update-cve-2025-9074)

*Last updated August 20, 2025*

A vulnerability in Docker Desktop was fixed on August 20 in the [4.44.3](https://docs.docker.com/desktop/release-notes/#4443) release:

* Fixed [CVE-2025-9074](https://www.cve.org/CVERecord?id=CVE-2025-9074) where a malicious container running on Docker Desktop could access the Docker Engine and launch additional containers without requiring the Docker socket to be mounted. This could allow unauthorized access to user files on the host system. Enhanced Container Isolation (ECI) does not mitigate this vulnerability.

## [Docker Desktop 4.44.0 security update: CVE-2025-23266](#docker-desktop-4440-security-update-cve-2025-23266)

*Last updated July 31, 2025*

We are aware of [CVE-2025-23266](https://nvd.nist.gov/vuln/detail/CVE-2025-23266), a critical vulnerability affecting the NVIDIA Container Toolkit in CDI mode up to version 1.17.7. Docker Desktop includes version 1.17.8, which is not impacted. However, older versions of Docker Desktop that bundled earlier toolkit versions may be affected if CDI mode was manually enabled. Upgrade to Docker Desktop 4.44 or later to ensure you're using the patched version.

## [Docker Desktop 4.43.0 security update: CVE-2025-6587](#docker-desktop-4430-security-update-cve-2025-6587)

*Last updated July 03, 2025*

A vulnerability in Docker Desktop was fixed on July 03 in the [4.43.0](https://docs.docker.com/desktop/release-notes/#4430) release:

* Fixed [CVE-2025-6587](https://www.cve.org/CVERecord?id=CVE-2025-6587) where sensitive system environment variables were included in Docker Desktop diagnostic logs, allowing for potential secret exposure.

## [Docker Desktop 4.41.0 Security Update: CVE-2025-3224, CVE-2025-4095, and CVE-2025-3911](#docker-desktop-4410-security-update-cve-2025-3224-cve-2025-4095-and-cve-2025-3911)

*Last updated May 15, 2025*

Three vulnerabilities in Docker Desktop were fixed on April 28 in the [4.41.0](https://docs.docker.com/desktop/release-notes/#4410) release.

* Fixed [CVE-2025-3224](https://www.cve.org/CVERecord?id=CVE-2025-3224) allowing an attacker with access to a user machine to perform an elevation of privilege when Docker Desktop updates.
* Fixed [CVE-2025-4095](https://www.cve.org/CVERecord?id=CVE-2025-4095) where Registry Access Management (RAM) policies were not enforced when using a MacOS configuration profile, allowing users to pull images from unapproved registries.
* Fixed [CVE-2025-3911](https://www.cve.org/CVERecord?id=CVE-2025-3911) allowing an attacker with read access to a user's machine to obtain sensitive information from Docker Desktop log files, including environment variables configured for running containers.

We strongly encourage you to update to Docker Desktop [4.41.0](https://docs.docker.com/desktop/release-notes/#4410).

## [Docker Desktop 4.34.2 Security Update: CVE-2024-8695 and CVE-2024-8696](#docker-desktop-4342-security-update-cve-2024-8695-and-cve-2024-8696)

*Last updated September 13, 2024*

Two remote code execution (RCE) vulnerabilities in Docker Desktop related to Docker Extensions were reported by [Cure53](https://cure53.de/) and were fixed on September 12 in the [4.34.2](https://docs.docker.com/desktop/release-notes/#4342) release.

* [CVE-2024-8695](https://www.cve.org/cverecord?id=CVE-2024-8695): A remote code execution (RCE) vulnerability via crafted extension description/changelog could be abused by a malicious extension in Docker Desktop before 4.34.2. \[Critical]
* [CVE-2024-8696](https://www.cve.org/cverecord?id=CVE-2024-8696): A remote code execution (RCE) vulnerability via crafted extension publisher-url/additional-urls could be abused by a malicious extension in Docker Desktop before 4.34.2. \[High]

No existing extensions exploiting the vulnerabilities were found in the Extensions Marketplace. The Docker Team will be closely monitoring and diligently reviewing any requests for publishing new extensions.

We strongly encourage you to update to Docker Desktop [4.34.2](https://docs.docker.com/desktop/release-notes/#4342). If you are unable to update promptly, you can [disable Docker Extensions](https://docs.docker.com/extensions/settings-feedback/#turn-on-or-turn-off-extensions) as a workaround.

## [Deprecation of password logins on CLI when SSO enforced](#deprecation-of-password-logins-on-cli-when-sso-enforced)

*Last updated July, 2024*

When [SSO enforcement](https://docs.docker.com/enterprise/security/single-sign-on/connect/) was first introduced, Docker provided a grace period to continue to let passwords be used on the Docker CLI when authenticating to Docker Hub. This was allowed so organizations could more easily use SSO enforcement. It is recommended that administrators configuring SSO encourage users using the CLI [to switch over to Personal Access Tokens](https://docs.docker.com/enterprise/security/single-sign-on/#prerequisites) in anticipation of this grace period ending.

On September 16, 2024 the grace period will end and passwords will no longer be able to authenticate to Docker Hub via the Docker CLI when SSO is enforced. Affected users are required to switch over to using PATs to continue signing in.

At Docker, we want the experience to be the most secure for our developers and organizations and this deprecation is an essential step in that direction.

## [SOC 2 Type 2 attestation and ISO 27001 certification](#soc-2-type-2-attestation-and-iso-27001-certification)

*Last updated June, 2024*

Docker is pleased to announce that we have received our SOC 2 Type 2 attestation and ISO 27001 certification with no exceptions or major non-conformities.

Security is a fundamental pillar to Docker's operations, which is embedded into our overall mission and company strategy. Docker's products are core to our user community and our SOC 2 Type 2 attestation and ISO 27001 certification demonstrate Docker's ongoing commitment to security to our user base.

For more information, see the [Blog announcement](https://www.docker.com/blog/docker-announces-soc-2-type-2-attestation-iso-27001-certification/).

## [Docker Security Advisory: Multiple Vulnerabilities in runc, BuildKit, and Moby](#docker-security-advisory-multiple-vulnerabilities-in-runc-buildkit-and-moby)

*Last updated February 2, 2024*

We at Docker prioritize the security and integrity of our software and the trust of our users. Security researchers at Snyk Labs identified and reported four security vulnerabilities in the container ecosystem. One of the vulnerabilities, [CVE-2024-21626](https://scout.docker.com/v/CVE-2024-21626), concerns the runc container runtime, and the other three affect BuildKit ([CVE-2024-23651](https://scout.docker.com/v/CVE-2024-23651), [CVE-2024-23652](https://scout.docker.com/v/CVE-2024-23652), and [CVE-2024-23653](https://scout.docker.com/v/CVE-2024-23653)). We want to assure our community that our team, in collaboration with the reporters and open source maintainers, has been diligently working on coordinating and implementing necessary remediations.

We are committed to maintaining the highest security standards. We have published patched versions of runc, BuildKit, and Moby on January 31 and released an update for Docker Desktop on February 1 to address these vulnerabilities. Additionally, our latest BuildKit and Moby releases included fixes for [CVE-2024-23650](https://scout.docker.com/v/CVE-2024-23650) and [CVE-2024-24557](https://scout.docker.com/v/CVE-2024-24557), discovered respectively by an independent researcher and through Docker's internal research initiatives.

|                        | Versions Impacted       |
| ---------------------- | ----------------------- |
| `runc`                 | <= 1.1.11               |
| `BuildKit`             | <= 0.12.4               |
| `Moby (Docker Engine)` | <= 25.0.1 and <= 24.0.8 |
| `Docker Desktop`       | <= 4.27.0               |

### [What should I do if I'm on an affected version?](#what-should-i-do-if-im-on-an-affected-version)

If you are using affected versions of runc, BuildKit, Moby, or Docker Desktop, make sure to update to the latest versions, linked in the following table:

|                        | Patched Versions                                                                                                                  |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `runc`                 | >= [1.1.12](https://github.com/opencontainers/runc/releases/tag/v1.1.12)                                                          |
| `BuildKit`             | >= [0.12.5](https://github.com/moby/buildkit/releases/tag/v0.12.5)                                                                |
| `Moby (Docker Engine)` | >= [25.0.2](https://github.com/moby/moby/releases/tag/v25.0.2) and >= [24.0.9](https://github.com/moby/moby/releases/tag/v24.0.9) |
| `Docker Desktop`       | >= [4.27.1](https://docs.docker.com/desktop/release-notes/#4271)                                                                  |

If you are unable to update to an unaffected version promptly, follow these best practices to mitigate risk:

* Only use trusted Docker images (such as [Docker Official Images](https://docs.docker.com/docker-hub/image-library/trusted-content/#docker-official-images)).

* Don't build Docker images from untrusted sources or untrusted Dockerfiles.

* If you are a Docker Business customer using Docker Desktop and unable to update to v4.27.1, make sure to enable [Hardened Docker Desktop](https://docs.docker.com/enterprise/security/hardened-desktop/) features such as:

  * [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/), which mitigates the impact of CVE-2024-21626 in the case of running containers from malicious images.
  * [Image Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/image-access-management/), and [Registry Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/), which give organizations control over which images and repositories their users can access.

* For CVE-2024-23650, CVE-2024-23651, CVE-2024-23652, and CVE-2024-23653, avoid using BuildKit frontend from an untrusted source. A frontend image is usually specified as the #syntax line on your Dockerfile, or with `--frontend` flag when using the `buildctl build` command.

* To mitigate CVE-2024-24557, make sure to either use BuildKit or disable caching when building images. From the CLI this can be done via the `DOCKER_BUILDKIT=1` environment variable (default for Moby >= v23.0 if the buildx plugin is installed) or the `--no-cache flag`. If you are using the HTTP API directly or through a client, the same can be done by setting `nocache` to `true` or `version` to `2` for the [/build API endpoint](https://docs.docker.com/reference/api/engine/version/v1.44/#tag/Image/operation/ImageBuild).

### [Technical details and impact](#technical-details-and-impact)

#### [CVE-2024-21626 (High)](#cve-2024-21626-high)

In runc v1.1.11 and earlier, due to certain leaked file descriptors, an attacker can gain access to the host filesystem by causing a newly-spawned container process (from `runc exec`) to have a working directory in the host filesystem namespace, or by tricking a user to run a malicious image and allow a container process to gain access to the host filesystem through `runc run`. The attacks can also be adapted to overwrite semi-arbitrary host binaries, allowing for complete container escapes. Note that when using higher-level runtimes (such as Docker or Kubernetes), this vulnerability can be exploited by running a malicious container image without additional configuration or by passing specific workdir options when starting a container. The vulnerability can also be exploited from within Dockerfiles in the case of Docker.

*The issue has been fixed in runc v1.1.12.*

#### [CVE-2024-23651 (High)](#cve-2024-23651-high)

In BuildKit <= v0.12.4, two malicious build steps running in parallel sharing the same cache mounts with subpaths could cause a race condition, leading to files from the host system being accessible to the build container. This will only occur if a user is trying to build a Dockerfile of a malicious project.

*The issue has been fixed in BuildKit v0.12.5.*

#### [CVE-2024-23652 (High)](#cve-2024-23652-high)

In BuildKit <= v0.12.4, a malicious BuildKit frontend or Dockerfile using `RUN --mount` could trick the feature that removes empty files created for the mountpoints into removing a file outside the container from the host system. This will only occur if a user is using a malicious Dockerfile.

*The issue has been fixed in BuildKit v0.12.5.*

#### [CVE-2024-23653 (High)](#cve-2024-23653-high)

In addition to running containers as build steps, BuildKit also provides APIs for running interactive containers based on built images. In BuildKit <= v0.12.4, it is possible to use these APIs to ask BuildKit to run a container with elevated privileges. Normally, running such containers is only allowed if special `security.insecure` entitlement is enabled both by buildkitd configuration and allowed by the user initializing the build request.

*The issue has been fixed in BuildKit v0.12.5.*

#### [CVE-2024-23650 (Medium)](#cve-2024-23650-medium)

In BuildKit <= v0.12.4, a malicious BuildKit client or frontend could craft a request that could lead to BuildKit daemon crashing with a panic.

*The issue has been fixed in BuildKit v0.12.5.*

#### [CVE-2024-24557 (Medium)](#cve-2024-24557-medium)

In Moby <= v25.0.1 and <= v24.0.8, the classic builder cache system is prone to cache poisoning if the image is built FROM scratch. Also, changes to some instructions (most important being `HEALTHCHECK` and `ONBUILD`) would not cause a cache miss. An attacker with knowledge of the Dockerfile someone is using could poison their cache by making them pull a specially crafted image that would be considered a valid cache candidate for some build steps.

*The issue has been fixed in Moby >= v25.0.2 and >= v24.0.9.*

### [How are Docker products affected?](#how-are-docker-products-affected)

#### [Docker Desktop](#docker-desktop)

Docker Desktop v4.27.0 and earlier are affected. Docker Desktop v4.27.1 was released on February 1 and includes runc, BuildKit, and dockerd binaries patches. In addition to updating to this new version, we encourage all Docker users to diligently use Docker images and Dockerfiles and ensure you only use trusted content in your builds.

As always, you should check Docker Desktop system requirements for your operating system ( [Windows](https://docs.docker.com/desktop/setup/install/windows-install/#system-requirements), [Linux](https://docs.docker.com/desktop/setup/install/linux/#general-system-requirements), [Mac](https://docs.docker.com/desktop/setup/install/mac-install/#system-requirements)) before updating to ensure full compatibility.

#### [Docker Build Cloud](#docker-build-cloud)

Any new Docker Build Cloud builder instances will be provisioned with the latest Docker Engine and BuildKit versions and will, therefore, be unaffected by these CVEs. Updates have also been rolled out to existing Docker Build Cloud builders.

*No other Docker products are affected by these vulnerabilities.*

### [Advisory links](#advisory-links)

* Runc
  * [CVE-2024-21626](https://github.com/opencontainers/runc/security/advisories/GHSA-xr7r-f8xq-vfvv)

* BuildKit

  * [CVE-2024-23650](https://github.com/moby/buildkit/security/advisories/GHSA-9p26-698r-w4hx)
  * [CVE-2024-23651](https://github.com/moby/buildkit/security/advisories/GHSA-m3r6-h7wv-7xxv)
  * [CVE-2024-23652](https://github.com/moby/buildkit/security/advisories/GHSA-4v98-7qmw-rqr8)
  * [CVE-2024-23653](https://github.com/moby/buildkit/security/advisories/GHSA-wr6v-9f75-vh2g)

* Moby
  * [CVE-2024-24557](https://github.com/moby/moby/security/advisories/GHSA-xw73-rw38-6vjc)

## [Text4Shell CVE-2022-42889](#text4shell-cve-2022-42889)

*Last updated October 2022*

[CVE-2022-42889](https://nvd.nist.gov/vuln/detail/CVE-2022-42889) has been discovered in the popular Apache Commons Text library. Versions of this library up to but not including 1.10.0 are affected by this vulnerability.

We strongly encourage you to update to the latest version of [Apache Commons Text](https://commons.apache.org/proper/commons-text/download_text.cgi).

### [Scan images on Docker Hub](#scan-images-on-docker-hub)

Docker Hub security scans triggered after 1200 UTC 21 October 2021 are now correctly identifying the Text4Shell CVE. Scans before this date do not currently reflect the status of this vulnerability. Therefore, we recommend that you trigger scans by pushing new images to Docker Hub to view the status of the Text4Shell CVE in the vulnerability report. For detailed instructions, see [Scan images on Docker Hub](https://docs.docker.com/docker-hub/repos/manage/vulnerability-scanning/).

### [Docker Official Images impacted by CVE-2022-42889](#docker-official-images-impacted-by-cve-2022-42889)

A number of [Docker Official Images](https://docs.docker.com/docker-hub/image-library/trusted-content/#docker-official-images) contain the vulnerable versions of Apache Commons Text. The following lists Docker Official Images that may contain the vulnerable versions of Apache Commons Text:

* [bonita](https://hub.docker.com/_/bonita)
* [Couchbase](https://hub.docker.com/_/couchbase)
* [Geonetwork](https://hub.docker.com/_/geonetwork)
* [neo4j](https://hub.docker.com/_/neo4j)
* [sliverpeas](https://hub.docker.com/_/sliverpeas)
* [solr](https://hub.docker.com/_/solr)
* [xwiki](https://hub.docker.com/_/xwiki)

We have updated Apache Commons Text in these images to the latest version. Some of these images may not be vulnerable for other reasons. We recommend that you also review the guidelines published on the upstream websites.

## [Log4j 2 CVE-2021-44228](#log4j-2-cve-2021-44228)

*Last updated December 2021*

The [Log4j 2 CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228) vulnerability in Log4j 2, a very common Java logging library, allows remote code execution, often from a context that is easily available to an attacker. For example, it was found in Minecraft servers which allowed the commands to be typed into chat logs as these were then sent to the logger. This makes it a very serious vulnerability, as the logging library is used so widely and it may be simple to exploit. Many open source maintainers are working hard with fixes and updates to the software ecosystem.

The vulnerable versions of Log4j 2 are versions 2.0 to version 2.14.1 inclusive. The first fixed version is 2.15.0. We strongly encourage you to update to the [latest version](https://logging.apache.org/log4j/2.x/download.html) if you can. If you are using a version before 2.0, you are also not vulnerable.

You may not be vulnerable if you are using these versions, as your configuration may already mitigate this, or the things you log may not include any user input. This may be difficult to validate however without understanding all the code paths that may log in detail, and where they may get input from. So you probably will want to upgrade all code using vulnerable versions.

> CVE-2021-45046
>
> As an update to [CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228), the fix made in version 2.15.0 was incomplete. Additional issues have been identified and are tracked with [CVE-2021-45046](https://nvd.nist.gov/vuln/detail/CVE-2021-45046) and [CVE-2021-45105](https://nvd.nist.gov/vuln/detail/CVE-2021-45105). For a more complete fix to this vulnerability, we recommended that you update to 2.17.0 where possible.

### [Scan images on Docker Hub](#scan-images-on-docker-hub-1)

Docker Hub security scans triggered after 1700 UTC 13 December 2021 are now correctly identifying the Log4j 2 CVEs. Scans before this date do not currently reflect the status of this vulnerability. Therefore, we recommend that you trigger scans by pushing new images to Docker Hub to view the status of Log4j 2 CVE in the vulnerability report. For detailed instructions, see [Scan images on Docker Hub](https://docs.docker.com/docker-hub/repos/manage/vulnerability-scanning/).

## [Docker Official Images impacted by Log4j 2 CVE](#docker-official-images-impacted-by-log4j-2-cve)

*Last updated December 2021*

A number of [Docker Official Images](https://docs.docker.com/docker-hub/image-library/trusted-content/#docker-official-images) contain the vulnerable versions of Log4j 2 CVE-2021-44228. The following table lists Docker Official Images that may contained the vulnerable versions of Log4j 2. We updated Log4j 2 in these images to the latest version. Some of these images may not be vulnerable for other reasons. We recommend that you also review the guidelines published on the upstream websites.

| Repository                                              | Patched version                | Additional documentation                                                                                                |
| ------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| [couchbase](https://hub.docker.com/_/couchbase)         | 7.0.3                          | [Couchbase blog](https://blog.couchbase.com/what-to-know-about-the-log4j-vulnerability-cve-2021-44228/)                 |
| [Elasticsearch](https://hub.docker.com/_/elasticsearch) | 6.8.22, 7.16.2                 | [Elasticsearch announcement](https://www.elastic.co/blog/new-elasticsearch-and-logstash-releases-upgrade-apache-log4j2) |
| [Flink](https://hub.docker.com/_/flink)                 | 1.11.6, 1.12.7, 1.13.5, 1.14.2 | [Flink advice on Log4j CVE](https://flink.apache.org/2021/12/10/log4j-cve.html)                                         |
| [Geonetwork](https://hub.docker.com/_/geonetwork)       | 3.10.10                        | [Geonetwork GitHub discussion](https://github.com/geonetwork/core-geonetwork/issues/6076)                               |
| [lightstreamer](https://hub.docker.com/_/lightstreamer) | Awaiting info                  | Awaiting info                                                                                                           |
| [logstash](https://hub.docker.com/_/logstash)           | 6.8.22, 7.16.2                 | [Elasticsearch announcement](https://www.elastic.co/blog/new-elasticsearch-and-logstash-releases-upgrade-apache-log4j2) |
| [neo4j](https://hub.docker.com/_/neo4j)                 | 4.4.2                          | [Neo4j announcement](https://community.neo4j.com/t/log4j-cve-mitigation-for-neo4j/48856)                                |
| [solr](https://hub.docker.com/_/solr)                   | 8.11.1                         | [Solr security news](https://solr.apache.org/security.html#apache-solr-affected-by-apache-log4j-cve-2021-44228)         |
| [sonarqube](https://hub.docker.com/_/sonarqube)         | 8.9.5, 9.2.2                   | [SonarQube announcement](https://community.sonarsource.com/t/sonarqube-sonarcloud-and-the-log4j-vulnerability/54721)    |
| [storm](https://hub.docker.com/_/storm)                 | Awaiting info                  | Awaiting info                                                                                                           |

> Note
>
> Although [xwiki](https://hub.docker.com/_/xwiki) images may be detected as vulnerable by some scanners, the authors believe the images are not vulnerable by Log4j 2 CVE as the API jars do not contain the vulnerability. The [Nuxeo](https://hub.docker.com/_/nuxeo) image is deprecated and will not be updated.

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/show/
----

# docker mcp catalog show

***

| Description | Show a catalog                                                   |
| ----------- | ---------------------------------------------------------------- |
| Usage       | `docker mcp catalog show <oci-reference> [--pull <pull-option>]` |

## [Description](#description)

Show a catalog

## [Options](#options)

| Option       | Default | Description                                                                                                                     |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `--format`   | `human` | Supported: json, yaml, human.                                                                                                   |
| `--no-tools` |         | Exclude tools from output (deprecated, use --yq instead)                                                                        |
| `--pull`     | `never` | Supported: missing, never, always, initial, exists, or duration (e.g. '1h', '1d'). Duration represents time since last update.  |
| `--yq`       |         | YQ expression to apply to the output                                                                                            |

----
url: https://docs.docker.com/dhi/core-concepts/stig/
----

# STIG

***

Table of contents

***

Subscription: Docker Hardened Images Select or Enterprise

## [What is STIG?](#what-is-stig)

[Security Technical Implementation Guides (STIGs)](https://public.cyber.mil/stigs/) are configuration standards published by the U.S. Defense Information Systems Agency (DISA). They define security requirements for operating systems, applications, databases, and other technologies used in U.S. Department of Defense (DoD) environments.

STIGs help ensure that systems are configured securely and consistently to reduce vulnerabilities. They are often based on broader requirements like the DoD's General Purpose Operating System Security Requirements Guide (GPOS SRG).

## [Why STIG guidance matters](#why-stig-guidance-matters)

Following STIG guidance is critical for organizations that work with or support U.S. government systems. It demonstrates alignment with DoD security standards and helps:

* Accelerate Authority to Operate (ATO) processes for DoD systems
* Reduce the risk of misconfiguration and exploitable weaknesses
* Simplify audits and reporting through standardized baselines

Even outside of federal environments, STIGs are used by security-conscious organizations as a benchmark for hardened system configurations.

STIGs are derived from broader NIST guidance, particularly [NIST Special Publication 800-53](https://csrc.nist.gov/publications/sp800), which defines a catalog of security and privacy controls for federal systems. Organizations pursuing compliance with 800-53 or related frameworks (such as FedRAMP) can use STIGs as implementation guides that help meet applicable control requirements.

## [How Docker Hardened Images help apply STIG guidance](#how-docker-hardened-images-help-apply-stig-guidance)

Docker Hardened Images (DHIs) include STIG variants that are scanned against custom STIG-based profiles and include signed STIG scan attestations. These attestations can support audits and compliance reporting.

While Docker Hardened Images are available to all, the STIG variant requires a Docker subscription.

Docker creates custom STIG-based profiles for images based on the GPOS SRG and DoD Container Hardening Process Guide. Because DISA has not published a STIG specifically for containers, these profiles help apply STIG-like guidance to container environments in a consistent, reviewable way and are designed to reduce false positives common in container images.

## [Identify images that include STIG scan results](#identify-images-that-include-stig-scan-results)

Docker Hardened Images that include STIG scan results are labeled as **STIG** in the Docker Hardened Images catalog.

To find DHI repositories with STIG image variants, [explore images](https://docs.docker.com/dhi/how-to/explore/#image-variants) and:

* Use the **STIG** filter on the catalog page
* Look for **STIG** labels on individual image listings

To find a STIG image variant within a repository, go to the **Tags** tab in the repository, and find images labeled with **STIG** in the **Compliance** column.

## [Use a STIG variant](#use-a-stig-variant)

To use a STIG variant, you must [mirror](https://docs.docker.com/dhi/how-to/mirror/) the repository and then pull the STIG image from your mirrored repository.

## [View and verify STIG scan results](#view-and-verify-stig-scan-results)

Docker provides a signed [STIG scan attestation](https://docs.docker.com/dhi/core-concepts/attestations/) for each STIG-ready image. These attestations include:

* A summary of the scan results, including the number of passed, failed, and not applicable checks
* The name and version of the STIG profile used
* Full output in both HTML and XCCDF (XML) formats

### [View STIG scan attestations](#view-stig-scan-attestations)

You can retrieve and inspect a STIG scan attestation using the Docker Scout CLI:

```console
$ docker scout attest get \
  --predicate-type https://docker.com/dhi/stig/v0.1 \
  --verify \
  --predicate \
  dhi.io/<image>:<tag>
```

### [Extract HTML report](#extract-html-report)

To extract and view the human-readable HTML report:

```console
$ docker scout attest get dhi.io/<image>:<tag> \
  --predicate-type https://docker.com/dhi/stig/v0.1 \
  --verify \
  --predicate \
  | jq -r '.[0].output[] | select(.format == "html").content | @base64d' > stig_report.html
```

### [Extract XCCDF report](#extract-xccdf-report)

To extract the XML (XCCDF) report for integration with other tools:

```console
$ docker scout attest get dhi.io/<image>:<tag> \
  --predicate-type https://docker.com/dhi/stig/v0.1 \
  --verify \
  --predicate \
  | jq -r '.[0].output[] | select(.format == "xccdf").content | @base64d' > stig_report.xml
```

### [View STIG scan summary](#view-stig-scan-summary)

To view just the scan summary without the full reports:

```console
$ docker scout attest get dhi.io/<image>:<tag> \
  --predicate-type https://docker.com/dhi/stig/v0.1 \
  --verify \
  --predicate \
  | jq -r '.[0] | del(.output)'
```

----
url: https://docs.docker.com/reference/cli/sbx/create/codex/
----

# sbx create codex

| Description | Create a sandbox for codex                |
| ----------- | ----------------------------------------- |
| Usage       | `sbx create codex PATH [PATH...] [flags]` |

## [Description](#description)

Create a sandbox with access to a host workspace for codex.

The workspace path is required and will be mounted inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Global options](#global-options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `-D, --debug`    |         | Enable debug logging                                                                                                                                                                                                   |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Examples](#examples)

```console
# Create in the current directory
sbx create codex .

# Create with a specific path
sbx create codex /path/to/project

# Create with additional read-only workspaces
sbx create codex . /path/to/docs:ro
```

----
url: https://docs.docker.com/guides/postgresql/immediate-setup-and-data-persistence/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Immediate setup & data persistence

***

Table of contents

***

This guide gets you from zero to a running PostgreSQL container in under five minutes, then explains how to keep your data safe across container restarts and removals.

## [Overview](#overview)

Running PostgreSQL in Docker requires understanding one critical concept: containers are ephemeral, but your data shouldn't be. This guide covers:

* Starting PostgreSQL with a single command
* Understanding why containers lose data by default
* Configuring volumes for persistent storage
* Translating your setup to Docker Compose

## [Quick start (minimal viable container)](#quick-start-minimal-viable-container)

> Note
>
> [Docker Hardened Images (DHIs)](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. DHIs are recommended whenever it is possible for better security. They are designed to reduce vulnerabilities and simplify compliance, freely available to everyone with no subscription required, no usage restrictions, and no vendor lock-in.

Run PostgreSQL immediately with this single command:

You must authenticate to dhi.io before you can pull Docker Hardened Images. Run `docker login dhi.io` to authenticate.

```console
docker run --rm --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d dhi.io/postgres:18
```

```console
$ docker run --rm --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d postgres:18
```

### [Understanding the flags](#understanding-the-flags)

| Flag                       | Purpose                                              |
| -------------------------- | ---------------------------------------------------- |
| `--rm`                     | Automatically removes the container when it stops    |
| `--name postgres-dev`      | Assigns a memorable name instead of a random string  |
| `-e POSTGRES_PASSWORD=...` | Sets the superuser password (required)               |
| `-p 5432:5432`             | Maps host port 5432 to container port 5432           |
| `-d`                       | Runs the container in the background (detached mode) |

Verify the container is running:

```console
$ docker ps --filter name=postgres-dev
CONTAINER ID   IMAGE         COMMAND                  STATUS         PORTS                    NAMES
a1b2c3d4e5f6   postgres:18   "docker-entrypoint.s…"   Up 2 seconds   0.0.0.0:5432->5432/tcp   postgres-dev
```

Connect using `psql` from inside the container:

```console
$ docker exec -it postgres-dev psql -U postgres
psql (18.0)
Type "help" for help.

postgres=#
```

You now have a working PostgreSQL instance. But there's a problem—stop this container and your data disappears.

## [The data persistence problem](#the-data-persistence-problem)

Containers use an ephemeral filesystem. When a container is removed, everything inside it, including your database files, is deleted.

Demonstrate this yourself:

```console
$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;"
CREATE DATABASE

$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb
 testdb    | postgres | UTF8     | libc            | en_US.utf8 | en_US.utf8 |            |           |

$ docker stop postgres-dev
postgres-dev

$ docker run --rm --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d dhi.io/postgres:18

$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb
(no output - database is gone)
```

```console
$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;"
CREATE DATABASE

$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb
 testdb    | postgres | UTF8     | libc            | en_US.utf8 | en_US.utf8 |            |           |

$ docker stop postgres-dev
postgres-dev

$ docker run --rm --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d postgres:18

$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb
(no output - database is gone)
```

Your `testdb` database vanished because the new container started with a fresh filesystem. This is expected behavior—and exactly why volumes exist.

## [Named volumes](#named-volumes)

Named volumes are Docker-managed storage locations that persist independently of containers. Docker handles the filesystem location, permissions, and lifecycle.

Create a container with a named volume:

You must authenticate to dhi.io before you can pull Docker Hardened Images. Run `docker login dhi.io` to authenticate.

```console
$ docker run --rm --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql \
  -d dhi.io/postgres:18
```

```console
$ docker run --rm --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql \
  -d postgres:18
```

The `-v postgres_data:/var/lib/postgresql` flag mounts a named volume called `postgres_data` to PostgreSQL's data directory. If the volume doesn't exist, Docker creates it automatically.

> Note
>
> PostgreSQL 18+ stores data in a version-specific subdirectory under `/var/lib/postgresql`. Mounting at this level (rather than `/var/lib/postgresql/data`) allows for easier upgrades using `pg_upgrade --link`.

### [Verify persistence works](#verify-persistence-works)

To verify data persistence, repeat the previous test, but this time with the named volume attached in place.

```console
$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;"
CREATE DATABASE

$ docker stop postgres-dev
postgres-dev

$ docker run --rm --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql \
  -d dhi.io/postgres:18

$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb
 testdb    | postgres | UTF8     | libc            | en_US.utf8 | en_US.utf8 |            |           |
```

```console
$ docker exec postgres-dev psql -U postgres -c "CREATE DATABASE testdb;"
CREATE DATABASE

$ docker stop postgres-dev
postgres-dev

$ docker run --rm --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql \
  -d postgres:18

$ docker exec postgres-dev psql -U postgres -c "\l" | grep testdb
 testdb    | postgres | UTF8     | libc            | en_US.utf8 | en_US.utf8 |            |           |
```

If you see `testdb` in the output, persistence works: The database survived because the volume preserved the data directory.

### [Managing volumes](#managing-volumes)

List all volumes:

```console
$ docker volume ls --filter name=postgres_data
DRIVER    VOLUME NAME
local     postgres_data
```

Inspect a volume to see its details:

```console
$ docker volume inspect postgres_data
[
    {
        "CreatedAt": "2025-01-05T10:30:00Z",
        "Driver": "local",
        "Labels": null,
        "Mountpoint": "/var/lib/docker/volumes/postgres_data/_data",
        "Name": "postgres_data",
        "Options": null,
        "Scope": "local"
    }
]
```

Remove an unused volume (warning: this deletes all data):

```console
$ docker volume rm postgres_data
```

## [Bind mounts (alternative)](#bind-mounts-alternative)

Bind mounts map a specific host directory to a container path. Unlike named volumes, you control exactly where data lives on the host filesystem.

Create a directory on your host machine to store Postgres data.

```console
mkdir -p ~/postgres-data && sudo chown -R 999:999 ~/postgres-data
```

Run Postgres using a bind mount.

```console
docker run --rm --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -v ~/postgres-data:/var/lib/postgresql \
  -d dhi.io/postgres:18
```

```console
$ mkdir -p ~/postgres-data
```

Run Postgres using a bind mount.

```console
$ docker run --rm --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -v ~/postgres-data:/var/lib/postgresql \
  -d postgres:18
```

### [When to use bind mounts](#when-to-use-bind-mounts)

Bind mounts are useful when you need direct filesystem access to the data directory for backup scripts that read files directly, when integrating with host-level monitoring tools, or when specific permission requirements exist. For most development and production scenarios, named volumes are simpler and less error-prone.

### [Common bind mount issues](#common-bind-mount-issues)

Permission errors are the most frequent problem with bind mounts. PostgreSQL runs as user `postgres` (UID 999) inside the container. If your host directory has restrictive permissions, the container fails to start.

Check logs if the container exits immediately:

```console
$ docker logs postgres-dev
```

## [Docker Compose configuration](#docker-compose-configuration)

Docker Compose captures your entire configuration in a file, making setups reproducible and easier to manage as complexity grows.

Create a `compose.yaml` file:

```yaml
services:
  db:
    image: postgres:18
    container_name: postgres-dev
    environment:
      POSTGRES_PASSWORD: mysecretpassword
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql

volumes:
  postgres_data:
```

Start the database:

```console
$ docker compose up -d
```

Stop and remove containers (volume persists):

```console
$ docker compose down
```

Alternatively, you can stop, remove containers, and delete the volume:

```console
$ docker compose down -v
```

This compose file becomes the foundation for adding initialization scripts, performance tuning, and companion services covered in subsequent guides.

### [Environment variables reference](#environment-variables-reference)

The official PostgreSQL image supports these environment variables:

| Variable            | Required | Description                                               |
| ------------------- | -------- | --------------------------------------------------------- |
| `POSTGRES_PASSWORD` | Yes      | Superuser password                                        |
| `POSTGRES_USER`     | No       | Superuser name (default: `postgres`)                      |
| `POSTGRES_DB`       | No       | Default database name (default: value of `POSTGRES_USER`) |

## [Next steps](#next-steps)

With persistent storage configured, you're ready to customize PostgreSQL further. The next chapter of the guide covers:

* Automated schema creation with initialization scripts
* Performance tuning for containerized workloads
* Timezone and locale configuration

[Advanced Configuration and Initialization »](https://docs.docker.com/guides/postgresql/advanced-configuration-and-initialization/)

----
url: https://docs.docker.com/reference/cli/docker/dhi/mirror/start/
----

# docker dhi mirror start

***

| Description | Start mirroring Docker Hardened Images |
| ----------- | -------------------------------------- |
| Usage       | `docker dhi mirror start`              |

## [Description](#description)

Start mirroring one or more Docker Hardened Images to your organization's registry.

Repository mappings are specified as arguments. The following formats are supported:

source Only the source repository; destination is auto-generated as /dhi- source,destination Source and destination; the destination namespace is filled from config if omitted ns/source,ns/dest Fully qualified source and destination

The source namespace defaults to "dhi" when not specified. The destination namespace defaults to the configured organization (--org or config).

Examples: docker dhi mirror start --org myorg dhi/golang,myorg/dhi-golang dhi/node,myorg/dhi-node docker dhi mirror start --org myorg golang,dhi-golang node,dhi-node docker dhi mirror start --org myorg golang node

## [Options](#options)

| Option               | Default | Description                       |
| -------------------- | ------- | --------------------------------- |
| `-d, --dependencies` |         | Mirrors any existing dependencies |
| `--json`             |         | Output in JSON format             |

----
url: https://docs.docker.com/reference/api/extensions-sdk/ExtensionCli/
----

# Interface: ExtensionCli

***

Table of contents

***

**`Since`**

0.2.0

## [Properties](#properties)

### [exec](#exec)

• **exec**: [`Exec`](https://docs.docker.com/reference/api/extensions-sdk/Exec/)

----
url: https://docs.docker.com/reference/cli/docker/image/inspect/
----

# docker image inspect

***

| Description | Display detailed information on one or more images |
| ----------- | -------------------------------------------------- |
| Usage       | `docker image inspect [OPTIONS] IMAGE [IMAGE...]`  |

## [Description](#description)

Display detailed information on one or more images

## [Options](#options)

| Option         | Default | Description                                                                                                                                                                                                                                          |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --format` |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates              |
| `--platform`   |         | API 1.49+ Inspect a specific platform of the multi-platform image. If the image or the server is not multi-platform capable, the command will error out if the platform does not match. 'os\[/arch\[/variant]]': Explicit platform (eg. linux/amd64) |

----
url: https://docs.docker.com/guides/deno/develop/
----

# Use containers for Deno development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a Deno application](https://docs.docker.com/guides/deno/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment for your containerized application. This includes:

* Configuring Compose to automatically update your running Compose services as you edit and save your code

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/dockersamples/docker-deno.git && cd docker-deno
```

## [Automatically update services](#automatically-update-services)

Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

Open your `compose.yml` file in an IDE or text editor and then add the Compose Watch instructions. The following example shows how to add Compose Watch to your `compose.yml` file.

|                                             |                                                                                                                                                                                                                      |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```
``` | ```yaml
services:
  server:
    image: deno-server
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    develop:
      watch:
        - action: rebuild
          path: .
``` |

Run the following command to run your application with Compose Watch.

```console
$ docker compose watch
```

Now, if you modify your `server.ts` you will see the changes in real time without re-building the image.

To test it out, open the `server.ts` file in your favorite text editor and change the message from `{"Status" : "OK"}` to `{"Status" : "Updated"}`. Save the file and refresh your browser at `http://localhost:8000`. You should see the updated message.

[Configure CI/CD for your Deno application »](https://docs.docker.com/guides/deno/configure-ci-cd/)

----
url: https://docs.docker.com/engine/manage-resources/contexts/
----

# Docker contexts

***

Table of contents

***

## [Introduction](#introduction)

This guide shows how you can use contexts to manage Docker daemons from a single client.

Each context contains all information required to manage resources on the daemon. The `docker context` command makes it easy to configure these contexts and switch between them.

As an example, a single Docker client might be configured with two contexts:

* A default context running locally
* A remote, shared context

Once these contexts are configured, you can use the `docker context use <context-name>` command to switch between them.

## [Prerequisites](#prerequisites)

To follow the examples in this guide, you'll need:

* A Docker client that supports the top-level `context` command

Run `docker context` to verify that your Docker client supports contexts.

## [The anatomy of a context](#the-anatomy-of-a-context)

A context is a combination of several properties. These include:

* Name and description
* Endpoint configuration
* TLS info

To list available contexts, use the `docker context ls` command.

```console
$ docker context ls
NAME        DESCRIPTION                               DOCKER ENDPOINT               ERROR
default *                                             unix:///var/run/docker.sock
```

This shows a single context called "default". It's configured to talk to a daemon through the local `/var/run/docker.sock` Unix socket.

The asterisk in the `NAME` column indicates that this is the active context. This means all `docker` commands run against this context, unless overridden with environment variables such as `DOCKER_HOST` and `DOCKER_CONTEXT`, or on the command-line with the `--context` and `--host` flags.

Dig a bit deeper with `docker context inspect`. The following example shows how to inspect the context called `default`.

```console
$ docker context inspect default
[
    {
        "Name": "default",
        "Metadata": {},
        "Endpoints": {
            "docker": {
                "Host": "unix:///var/run/docker.sock",
                "SkipTLSVerify": false
            }
        },
        "TLSMaterial": {},
        "Storage": {
            "MetadataPath": "\u003cIN MEMORY\u003e",
            "TLSPath": "\u003cIN MEMORY\u003e"
        }
    }
]
```

### [Create a new context](#create-a-new-context)

You can create new contexts with the `docker context create` command.

The following example creates a new context called `docker-test` and specifies the host endpoint of the context to TCP socket `tcp://docker:2375`.

```console
$ docker context create docker-test --docker host=tcp://docker:2375
docker-test
Successfully created context "docker-test"
```

The new context is stored in a `meta.json` file below `~/.docker/contexts/`. Each new context you create gets its own `meta.json` stored in a dedicated sub-directory of `~/.docker/contexts/`.

You can view the new context with `docker context ls` and `docker context inspect <context-name>`.

```console
$ docker context ls
NAME          DESCRIPTION                             DOCKER ENDPOINT               ERROR
default *                                             unix:///var/run/docker.sock
docker-test                                           tcp://docker:2375
```

The current context is indicated with an asterisk ("\*").

## [Use a different context](#use-a-different-context)

You can use `docker context use` to switch between contexts.

The following command will switch the `docker` CLI to use the `docker-test` context.

```console
$ docker context use docker-test
docker-test
Current context is now "docker-test"
```

Verify the operation by listing all contexts and ensuring the asterisk ("\*") is against the `docker-test` context.

```console
$ docker context ls
NAME            DESCRIPTION                           DOCKER ENDPOINT               ERROR
default                                               unix:///var/run/docker.sock
docker-test *                                         tcp://docker:2375
```

`docker` commands will now target endpoints defined in the `docker-test` context.

You can also set the current context using the `DOCKER_CONTEXT` environment variable. The environment variable overrides the context set with `docker context use`.

Use the appropriate command below to set the context to `docker-test` using an environment variable.

```ps
> $env:DOCKER_CONTEXT='docker-test'
```

```console
$ export DOCKER_CONTEXT=docker-test
```

Run `docker context ls` to verify that the `docker-test` context is now the active context.

You can also use the global `--context` flag to override the context. The following command uses a context called `production`.

```console
$ docker --context production container ls
```

## [Exporting and importing Docker contexts](#exporting-and-importing-docker-contexts)

You can use the `docker context export` and `docker context import` commands to export and import contexts on different hosts.

The `docker context export` command exports an existing context to a file. The file can be imported on any host that has the `docker` client installed.

### [Exporting and importing a context](#exporting-and-importing-a-context)

The following example exports an existing context called `docker-test`. It will be written to a file called `docker-test.dockercontext`.

```console
$ docker context export docker-test
Written file "docker-test.dockercontext"
```

Check the contents of the export file.

```console
$ cat docker-test.dockercontext
```

Import this file on another host using `docker context import` to create context with the same configuration.

```console
$ docker context import docker-test docker-test.dockercontext
docker-test
Successfully imported context "docker-test"
```

You can verify that the context was imported with `docker context ls`.

The format of the import command is `docker context import <context-name> <context-file>`.

## [Updating a context](#updating-a-context)

You can use `docker context update` to update fields in an existing context.

The following example updates the description field in the existing `docker-test` context.

```console
$ docker context update docker-test --description "Test context"
docker-test
Successfully updated context "docker-test"
```

----
url: https://docs.docker.com/admin/company/manage/owners/
----

# Manage company owners

***

Table of contents

***

Subscription: Business

For: Administrators

A company can have multiple owners. Company owners have visibility across the entire company and can manage settings that apply to all organizations under that company. They also have the same access rights as organization owners but don’t need to be members of any individual organization.

> Important
>
> Company owners do not occupy a seat unless they are added as a member of an organization under your company, or SSO is enabled and the company owner signs in via SSO (which automatically adds them as an organization member).

## [Add a company owner](#add-a-company-owner)

1. Sign in to [Docker Home](https://app.docker.com) and select your company from the top-left account drop-down.
2. Select **Admin Console**, then **Company owners**.
3. Select **Add owner**.
4. Specify the user's Docker ID to search for the user.
5. After you find the user, select **Add company owner**.

## [Remove a company owner](#remove-a-company-owner)

1. Sign in to [Docker Home](https://app.docker.com) and select your company from the top-left account drop-down.
2. Select **Admin Console**, then **Company owners**.
3. Locate the company owner you want to remove and select the **Actions** menu.
4. Select **Remove as company owner**.

----
url: https://docs.docker.com/ai/sandboxes/architecture/
----

# Architecture

***

Table of contents

***

This page explains how Docker Sandboxes work under the hood. For the security properties of the architecture, see [Sandbox isolation](https://docs.docker.com/ai/sandboxes/security/isolation/).

## [Workspace mounting](#workspace-mounting)

Your workspace is mounted directly into the sandbox through a filesystem passthrough. The sandbox sees your actual host files, so changes in either direction are instant with no sync process involved.

Your workspace is mounted at the same absolute path as on your host. Preserving absolute paths means error messages, configuration files, and build outputs all reference paths you can find on your host. The agent sees exactly the directory structure you see, which reduces confusion when debugging or reviewing changes.

> Warning
>
> Avoid mounting network-attached or remote storage (network drives, SMB/NFS shares, or cloud-synced folders) as a workspace. The sandbox accesses workspaces through a filesystem passthrough, so every file read and write goes over the network. This adds latency and slows agent performance.

## [Storage and persistence](#storage-and-persistence)

When you create a sandbox, everything inside it persists until you remove it: Docker images and containers built or pulled by the agent, installed packages, agent state and history, and workspace changes.

Sandboxes are isolated from each other. Each one maintains its own Docker daemon state, image cache, and package installations. Multiple sandboxes don't share images or layers.

Each sandbox consumes disk space for its VM image, Docker images, container layers, and volumes, and this grows as you build images and install packages.

## [Networking](#networking)

All outbound traffic from the sandbox routes through an HTTP/HTTPS proxy on your host. Agents are configured to use the proxy automatically. The proxy enforces [network access policies](https://docs.docker.com/ai/sandboxes/security/policy/) and handles [credential injection](https://docs.docker.com/ai/sandboxes/security/credentials/). See [Network isolation](https://docs.docker.com/ai/sandboxes/security/isolation/#network-isolation) for how this works and [Default security posture](https://docs.docker.com/ai/sandboxes/security/defaults/) for what is allowed out of the box.

## [Lifecycle](#lifecycle)

`sbx run` initializes a VM with a workspace for a specified agent and starts the agent. You can stop and restart without recreating the VM, preserving installed packages and Docker images.

Sandboxes persist until explicitly removed. Stopping an agent doesn't delete the VM; environment setup carries over between runs. Use `sbx rm` to delete the sandbox, its VM, and all of its contents. If the sandbox used `--branch`, the worktree directories and their branches are also removed.

## [Comparison to alternatives](#comparison-to-alternatives)

| Approach                                            | Isolation            | Docker access      | Use case           |
| --------------------------------------------------- | -------------------- | ------------------ | ------------------ |
| Sandboxes (microVMs)                                | Full (hypervisor)    | Isolated daemon    | Autonomous agents  |
| Container with socket mount                         | Partial (namespaces) | Shared host daemon | Trusted tools      |
| [Docker-in-Docker](https://hub.docker.com/_/docker) | Partial (privileged) | Nested daemon      | CI/CD pipelines    |
| Host execution                                      | None                 | Host daemon        | Manual development |

Sandboxes trade higher resource overhead (a VM plus its own daemon) for complete isolation. Use containers when you need lightweight packaging without Docker access. Use sandboxes when you need to give something autonomous full Docker capabilities without trusting it with your host environment.

----
url: https://docs.docker.com/reference/cli/docker/model/restart-runner/
----

# docker model restart-runner

***

| Description | Restart Docker Model Runner (Docker Engine only) |
| ----------- | ------------------------------------------------ |
| Usage       | `docker model restart-runner`                    |

## [Description](#description)

This command restarts the Docker Model Runner without pulling container images. Use this command to restart the runner when you already have the required images locally.

For the first-time setup or to ensure you have the latest images, use `docker model install-runner` instead.

## [Options](#options)

| Option           | Default     | Description                                                                                             |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| `--debug`        |             | Enable debug logging                                                                                    |
| `--do-not-track` |             | Do not track models usage in Docker Model Runner                                                        |
| `--gpu`          | `auto`      | Specify GPU support (none\|auto\|cuda\|rocm\|musa\|cann)                                                |
| `--host`         | `127.0.0.1` | Host address to bind Docker Model Runner                                                                |
| `--port`         |             | Docker container port for Docker Model Runner (default: 12434 for Docker Engine, 12435 for Cloud mode)  |
| `--proxy-cert`   |             | Path to a CA certificate file for proxy SSL inspection                                                  |

----
url: https://docs.docker.com/reference/api/extensions-sdk/ExtensionHost/
----

# Interface: ExtensionHost

***

Table of contents

***

**`Since`**

0.2.0

## [Properties](#properties)

### [cli](#cli)

• `Readonly` **cli**: [`ExtensionCli`](https://docs.docker.com/reference/api/extensions-sdk/ExtensionCli/)

Executes a command in the host.

For example, execute the shipped binary `kubectl -h` command in the host:

```typescript
await ddClient.extension.host.cli.exec("kubectl", ["-h"]);
```

***

Streams the output of the command executed in the backend container or in the host.

Provided the `kubectl` binary is shipped as part of your extension, you can spawn the `kubectl -h` command in the host:

```typescript
await ddClient.extension.host.cli.exec("kubectl", ["-h"], {
           stream: {
             onOutput(data): void {
                 // As we can receive both `stdout` and `stderr`, we wrap them in a JSON object
                 JSON.stringify(
                   {
                     stdout: data.stdout,
                     stderr: data.stderr,
                   },
                   null,
                   "  "
                 );
             },
             onError(error: any): void {
               console.error(error);
             },
             onClose(exitCode: number): void {
               console.log("onClose with exit code " + exitCode);
             },
           },
         });
```

----
url: https://docs.docker.com/dhi/core-concepts/vex/
----

# Vulnerability Exploitability eXchange (VEX)

***

Table of contents

***

## [What is VEX?](#what-is-vex)

Vulnerability Exploitability eXchange (VEX) is a specification for documenting the exploitability status of vulnerabilities within software components. VEX is primarily defined through industry standards such as CSAF (OASIS) and CycloneDX VEX, with the U.S. Cybersecurity and Infrastructure Security Agency (CISA) encouraging its adoption. VEX complements CVE (Common Vulnerabilities and Exposures) identifiers by adding producer-asserted status information, indicating whether a vulnerability is exploitable in the product as shipped. This helps organizations prioritize remediation efforts by identifying vulnerabilities that do not affect their specific product configurations.

For how VEX affects vulnerability counts and scanner selection, see [Scanner integrations](https://docs.docker.com/dhi/explore/scanner-integrations/). To scan a DHI with VEX support, see [Scan Docker Hardened Images](https://docs.docker.com/dhi/how-to/scan/).

## [VEX status reference](#vex-status-reference)

Each VEX statement includes a `status` field that records Docker's exploitability assessment for a given CVE and image. DHI uses three of the four OpenVEX status values.

| Status                | Meaning                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `not_affected`        | The CVE was reported against a package in the image, but Docker has assessed it is not exploitable as shipped |
| `under_investigation` | Docker is aware of the CVE and is actively evaluating whether it affects the image                            |
| `affected`            | Docker has confirmed the CVE is exploitable in the image and a fix is not yet available                       |

You can view the VEX statements for any DHI using Docker Scout. See [Scan Docker Hardened Images](https://docs.docker.com/dhi/how-to/scan/).

### [`not_affected` justification codes](#not_affected-justification-codes)

`not_affected` statements include a machine-readable `justification` field explaining why the vulnerability does not apply:

| Justification                                       | Meaning                                                                                                    |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `component_not_present`                             | The vulnerable component is not present in this image; the CVE matched by name against a different package |
| `vulnerable_code_not_present`                       | The vulnerable code path was not compiled into this build                                                  |
| `vulnerable_code_not_in_execute_path`               | The vulnerable code exists in the package but is not called in this image's runtime configuration          |
| `vulnerable_code_cannot_be_controlled_by_adversary` | The vulnerable code exists but an attacker cannot trigger it in this configuration                         |
| `inline_mitigations_already_exist`                  | Docker has applied a backport or patch that addresses the CVE                                              |

### [Why DHI does not use `fixed`](#why-dhi-does-not-use-fixed)

DHI does not use `fixed`. VEX-enabled scanners may not handle `fixed` consistently, so when Docker backports an upstream patch where the version number alone would not reflect the fix, it uses `not_affected` with `inline_mitigations_already_exist` justification instead.

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/
----

# Configure Settings Management with a JSON file

***

Table of contents

***

Subscription: Business

For: Administrators

Settings Management lets you configure and enforce Docker Desktop settings across your organization using an `admin-settings.json` file. This standardizes Docker Desktop environments and ensures consistent configurations for all users.

## [Prerequisites](#prerequisites)

Before you begin, make sure you have:

* [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) for your organization
* A Docker Business subscription

The presence of the `admin-settings.json` file enforces sign-in on Docker Desktop. This is intended for business features that require authentication.

Users must be signed in and part of a Docker Business organization. If either condition isn't met, the settings file is ignored.

## [Step one: Create the settings file](#step-one-create-the-settings-file)

You can create the `admin-settings.json` file in two ways:

* Use the `--admin-settings` installer flag to auto-generate the file:

  * [Mac](https://docs.docker.com/desktop/setup/install/mac-install/#install-from-the-command-line) installation guide
  * [Windows](https://docs.docker.com/desktop/setup/install/windows-install/#install-from-the-command-line) installation guide

* Create it manually (UTF-8 without BOM) and place it in the following locations:

  * Mac: `/Library/Application Support/com.docker.docker/admin-settings.json`
  * Windows: `C:\ProgramData\DockerDesktop\admin-settings.json`
  * Linux: `/usr/share/docker-desktop/admin-settings.json`

> Important
>
> Place the file in a protected directory to prevent unauthorized changes. Use Mobile Device Management (MDM) tools like Jamf to distribute the file at scale across your organization.

## [Step two: Configure settings](#step-two-configure-settings)

> Tip
>
> For a complete list of available settings, their supported platforms, and which configuration methods they work with, see the [Settings reference](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/settings-reference/).

The `admin-settings.json` file uses structured keys to define configurable settings and whether values are enforced.

Each setting supports a `locked` field that controls user permissions:

* When `locked` is set to `true`, users can't change that value in Docker Desktop, the CLI, or config files.
* When `locked` is set to `false`, the value acts like a default suggestion and users can still update it.

Settings where `locked` is set to `false` are ignored on existing installs if a user has already customized that value in `settings-store.json`, `settings.json`, or `daemon.json`.

### [Grouped settings](#grouped-settings)

Docker Desktop groups some settings together with a single toggle that controls the entire section. These include:

* Enhanced Container Isolation (ECI): Uses a main toggle (`enhancedContainerIsolation`) that enables/disables the entire feature, with sub-settings for specific configurations
* Kubernetes: Uses a main toggle (`kubernetes.enabled`) with sub-settings for cluster configuration
* Docker Scout: Groups settings under the `scout` object

When configuring grouped settings:

1. Set the main toggle to enable the feature
2. Configure sub-settings within that group
3. When you lock the main toggle, users cannot modify any settings in that group

Example for `enhancedContainerIsolation`:

```json
"enhancedContainerIsolation": {
  "locked": true,  // This locks the entire ECI section
  "value": true,   // This enables ECI
  "dockerSocketMount": {  // These are sub-settings
    "imageList": {
      "images": ["docker.io/testcontainers/ryuk:*"]
    }
  }
}
```

### [Example `admin-settings.json` file](#example-admin-settingsjson-file)

The following sample is an `admin-settings.json` file with common enterprise settings configured. You can use this example as a template with the [`admin-settings.json` configurations](#admin-settingsjson-configurations):

```json
{
  "configurationFileVersion": 2,
  "exposeDockerAPIOnTCP2375": {
    "locked": true,
    "value": false
  },
  "proxy": {
    "locked": true,
    "mode": "system",
    "http": "",
    "https": "",
    "exclude": [],
    "windowsDockerdPort": 65000,
    "enableKerberosNtlm": false,
    "pac": "",
    "embeddedPac": ""
  },
  "containersProxy": {
    "locked": true,
    "mode": "manual",
    "http": "",
    "https": "",
    "exclude": [],
    "pac": "",
    "embeddedPac": "",
    "transparentPorts": ""
  },
  "enhancedContainerIsolation": {
    "locked": true,
    "value": true,
    "dockerSocketMount": {
      "imageList": {
        "images": [
          "docker.io/localstack/localstack:*",
          "docker.io/testcontainers/ryuk:*"
        ]
      },
      "commandList": {
        "type": "deny",
        "commands": ["push"]
      }
    }
  },
  "linuxVM": {
    "wslEngineEnabled": {
      "locked": false,
      "value": false
    },
    "dockerDaemonOptions": {
      "locked": false,
      "value": "{\"debug\": false}"
    },
    "vpnkitCIDR": {
      "locked": false,
      "value": "192.168.65.0/24"
    }
  },
  "kubernetes": {
    "locked": false,
    "enabled": false,
    "showSystemContainers": false,
    "imagesRepository": ""
  },
  "windowsContainers": {
    "dockerDaemonOptions": {
      "locked": false,
      "value": "{\"debug\": false}"
    }
  },
  "disableUpdate": {
    "locked": false,
    "value": false
  },
  "analyticsEnabled": {
    "locked": false,
    "value": true
  },
  "extensionsEnabled": {
    "locked": true,
    "value": false
  },
  "scout": {
    "locked": false,
    "sbomIndexing": true,
    "useBackgroundIndexing": true
  },
  "allowBetaFeatures": {
    "locked": false,
    "value": false
  },
  "blockDockerLoad": {
    "locked": false,
    "value": true
  },
  "filesharingAllowedDirectories": [
    {
      "path": "$HOME",
      "sharedByDefault": true
    },
    {
      "path": "$TMP",
      "sharedByDefault": false
    }
  ],
  "useVirtualizationFrameworkVirtioFS": {
    "locked": true,
    "value": true
  },
  "useVirtualizationFrameworkRosetta": {
    "locked": true,
    "value": true
  },
  "useGrpcfuse": {
    "locked": true,
    "value": true
  },
  "displayedOnboarding": {
    "locked": true,
    "value": true
  },
  "desktopTerminalEnabled": {
    "locked": false,
    "value": false
  },
  "enableInference": {
    "locked": false,
    "value": true
  },
  "enableInferenceTCP": {
    "locked": false,
    "value": true
  },
  "enableInferenceTCPPort": {
    "locked": true,
    "value": 12434
  },
  "enableInferenceCORS": {
    "locked": true,
    "value": ""
  },
  "enableInferenceGPUVariant": {
    "locked": true,
    "value": true
  },
  "portBindingBehavior": {
    "locked": true,
    "value": "default-port-binding"
  }
}
```

## [Step three: Apply the settings](#step-three-apply-the-settings)

Settings take effect after Docker Desktop restarts and the user signs in.

For new installations:

1. Launch Docker Desktop.
2. Sign in with your Docker account.

For existing installations:

1. Quit Docker Desktop completely.
2. Relaunch Docker Desktop.

> Important
>
> You must fully quit and reopen Docker Desktop. Restarting from the menu isn't sufficient.

## [`admin-settings.json` configurations](#admin-settingsjson-configurations)

The following tables describe all available settings in the `admin-settings.json` file.

> Note
>
> Some settings are platform-specific or require minimum Docker Desktop versions. Check the Version column for requirements.

### [General settings](#general-settings)

| Parameter                  | OS           | Description                                                                                                                                                                                                      | Version |
| -------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `configurationFileVersion` |              | Specifies the version of the configuration file format.                                                                                                                                                          |         |
| `analyticsEnabled`         |              | If `value` is set to false, Docker Desktop doesn't send usage statistics to Docker.                                                                                                                              |         |
| `disableUpdate`            |              | If `value` is set to true, checking for and notifications about Docker Desktop updates is disabled.                                                                                                              |         |
| `blockDockerLoad`          |              | If `value` is set to `true`, users are no longer able to run [`docker load`](/reference/cli/docker/image/load/) and receive an error if they try to.                                                             |         |
| `displayedOnboarding`      |              | If `value` is set to `true`, the onboarding survey will not be displayed to new users. Setting `value` to `false` has no effect.                                                                                 |         |
| `desktopTerminalEnabled`   |              | If `value` is set to `false`, developers cannot use the Docker terminal to interact with the host machine and execute commands directly from Docker Desktop.                                                     |         |
| `exposeDockerAPIOnTCP2375` | Windows only | Exposes the Docker API on a specified port. If `value` is set to true, the Docker API is exposed on port 2375. Note: This is unauthenticated and should only be enabled if protected by suitable firewall rules. |         |
| `silentModulesUpdate`      |              | If `value` is set to `true`, Docker Desktop automatically updates components that don't require a restart. For example, the Docker CLI or Docker Scout components.                                               |         |

### [Extensions](#extensions)

| Parameter                                     | OS | Description                                                                                                                                                                                                    | Version |
| --------------------------------------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `extensionsEnabled`                           |    | If `value` is set to false, Docker Extensions are disabled.                                                                                                                                                    |         |
| `onlyMarketplaceExtensions`                   |    | If `value` is set to true, developers are blocked from installing other extensions via the command line.                                                                                                       |         |
| `extensionsPrivateMarketplace`                |    | If `value` is set to true, activates the private marketplace is enabled which ensures Docker Desktop connects to content defined and controlled by the administrator instead of the public Docker marketplace. |         |
| `extensionsPrivateMarketplaceAdminContactURL` |    | Defines a contact link for developers to request new extensions in the private marketplace.                                                                                                                    |         |

### [File sharing and emulation](#file-sharing-and-emulation)

| Parameter                            | OS         | Description                                                                                                                                                                                                                                                                                                                                               | Version |
| ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `filesharingAllowedDirectories`      |            | Specify which paths your developers can add file shares to. Also accepts `$HOME`, `$TMP`, or `$TEMP` as `path` variables. When a path is added, its subdirectories are allowed. If `sharedByDefault` is set to `true`, that path will be added upon factory reset or when Docker Desktop first starts.                                                    |         |
| `useVirtualizationFrameworkVirtioFS` | macOS only | If `value` is set to `true`, VirtioFS is set as the file sharing mechanism. Note: If both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `true`, VirtioFS takes precedence. Likewise, if both `useVirtualizationFrameworkVirtioFS` and `useGrpcfuse` have `value` set to `false`, osxfs is set as the file sharing mechanism. |         |
| `useGrpcfuse`                        | macOS only | If `value` is set to `true`, gRPC Fuse is set as the file sharing mechanism.                                                                                                                                                                                                                                                                              |         |
| `useVirtualizationFrameworkRosetta`  | macOS only | If `value` is set to `true`, Docker Desktop turns on Rosetta to accelerate x86\_64/amd64 binary emulation on Apple Silicon. Note: This also automatically enables `Use Virtualization framework`.                                                                                                                                                         |         |

### [Docker Scout](#docker-scout)

| Parameter | OS | Description                                                                                                                                                                                                                                                            | Version |
| --------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `scout`   |    | Setting `useBackgroundIndexing` to `false` disables automatic indexing of images loaded to the image store. Setting `sbomIndexing` to `false` prevents users from being able to index image by inspecting them in Docker Desktop or using `docker scout` CLI commands. |         |

### [Proxy settings](#proxy-settings)

| Parameter            | OS           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Version |
| -------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `proxy`              |              | If `mode` is set to `system` instead of `manual`, Docker Desktop gets the proxy values from the system and ignores any values set for `http`, `https` and `exclude`. Change `mode` to `manual` to manually configure proxy servers. If the proxy port is custom, specify it in the `http` or `https` property, for example `"https": "http://myotherproxy.com:4321"`. The `exclude` property specifies a comma-separated list of hosts and domains to bypass the proxy. |         |
| `windowsDockerdPort` | Windows only | Exposes Docker Desktop's internal proxy locally on this port for the Windows Docker daemon to connect to. If it is set to 0, a random free port is chosen. If the value is greater than 0, use that exact value for the port. The default value is -1 which disables the option.                                                                                                                                                                                        |         |
| `enableKerberosNtlm` |              | When set to `true`, Kerberos and NTLM authentication is enabled. Default is `false`. For more information, see the settings documentation.                                                                                                                                                                                                                                                                                                                              |         |
| `pac`                |              | Specifies a PAC file URL. For example, `"pac": "http://proxy/proxy.pac"`.                                                                                                                                                                                                                                                                                                                                                                                               |         |
| `embeddedPac`        |              | Specifies an embedded PAC (Proxy Auto-config) script. For example, `"embeddedPac": "function FindProxyForURL(url, host) { return \"DIRECT\"; }"`. This setting takes precedence over HTTP, HTTPS, Proxy bypass and PAC server URL.                                                                                                                                                                                                                                      |         |

### [Container proxy](#container-proxy)

| Parameter         | OS | Description                                                                                                                                                                                                                                         | Version |
| ----------------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `containersProxy` |    | Creates air-gapped containers. For more information see [Air-Gapped Containers](https://docs.docker.com/enterprise/security/hardened-desktop/air-gapped-containers/).                                                                               |         |
| `pac`             |    | Specifies a PAC file URL. For example, `"pac": "http://containerproxy/proxy.pac"`.                                                                                                                                                                  |         |
| `embeddedPac`     |    | Specifies an embedded PAC (Proxy Auto-config) script. For example, `"embeddedPac": "function FindProxyForURL(url, host) { return \"PROXY 192.168.92.1:2003\"; }"`. This setting takes precedence over HTTP, HTTPS, Proxy bypass and PAC server URL. |         |

### [Linux VM settings](#linux-vm-settings)

| Parameter                    | OS           | Description                                                                                                                                                                                                                                                                                                                     | Version |
| ---------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `linuxVM`                    |              | Parameters and settings related to Linux VM options - grouped together here for convenience.                                                                                                                                                                                                                                    |         |
|        `wslEngineEnabled`    | Windows only | If `value` is set to true, Docker Desktop uses the WSL 2 based engine. This overrides anything that may have been set at installation using the `--backend=<backend name>` flag.                                                                                                                                                |         |
|        `dockerDaemonOptions` |              | If `value` is set to true, it overrides the options in the Docker Engine config file. See the [Docker Engine reference](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file). Note that for added security, a few of the config attributes may be overridden when Enhanced Container Isolation is enabled. |         |
|        `vpnkitCIDR`          |              | Overrides the network range used for vpnkit DHCP/DNS for `*.docker.internal`                                                                                                                                                                                                                                                    |         |

### [Windows containers](#windows-containers)

| Parameter                    | OS | Description                                                                                                                                                         | Version |
| ---------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `windowsContainers`          |    | Parameters and settings related to `windowsContainers` options - grouped together here for convenience.                                                             |         |
|        `dockerDaemonOptions` |    | Overrides the options in the Linux daemon config file. See the [Docker Engine reference](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file). |         |

> Note
>
> This setting is not available to configure via the Docker Admin Console.

### [Kubernetes settings](#kubernetes-settings)

| Parameter    | OS | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Version |
| ------------ | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `kubernetes` |    | If `enabled` is set to true, a Kubernetes single-node cluster is started when Docker Desktop starts. If `showSystemContainers` is set to true, Kubernetes containers are displayed in the Docker Desktop Dashboard and when you run `docker ps`. The [imagesRepository](https://docs.docker.com/desktop/use-desktop/kubernetes/#configuring-a-custom-image-registry-for-kubernetes-control-plane-images) setting lets you specify which repository Docker Desktop pulls control-plane Kubernetes images from. |         |

> Note
>
> When using `imagesRepository` with Enhanced Container Isolation (ECI), add these images to the [ECI Docker socket mount image list](#enhanced-container-isolation):
>
> `[imagesRepository]/desktop-cloud-provider-kind:` `[imagesRepository]/desktop-containerd-registry-mirror:`
>
> These containers mount the Docker socket, so you must add them to the ECI images list. Otherwise, ECI blocks the mount and Kubernetes won't start.

### [Networking settings](#networking-settings)

| Parameter               | OS                          | Description                                                                                                                                                                                                                 | Version                                |
| ----------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `defaultNetworkingMode` | Windows and Mac only        | Defines the default IP protocol for new Docker networks: `dual-stack` (IPv4 + IPv6, default), `ipv4only`, or `ipv6only`.                                                                                                    |                                        |
| `dnsInhibition`         | Windows and Mac only        | Controls DNS record filtering returned to containers. Options: `auto` (recommended), `ipv4`, `ipv6`, `none`                                                                                                                 |                                        |
| `portBindingBehavior`   | Linux-based containers only | Defines port binding restrictions and default behavior, allowing admins to control how a user exposes ports from their containers. Options: `default-port-binding`, `default-local-port-binding`, `local-only-port-binding` | Docker Desktop version 4.52 and later. |

For more information, see [Networking](https://docs.docker.com/desktop/features/networking/#networking-mode-and-dns-behaviour-for-mac-and-windows).

### [AI settings](#ai-settings)

| Parameter                   | OS           | Description                                                                                                                                                                                                                        | Version |
| --------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `enableInference`           |              | Setting `enableInference` to `true` enables [Docker Model Runner](https://docs.docker.com/ai/model-runner/).                                                                                                                       |         |
| `enableInferenceTCP`        |              | Enable host-side TCP support. This setting requires the Docker Model Runner setting to be enabled first.                                                                                                                           |         |
| `enableInferenceTCPPort`    |              | Specifies the exposed TCP port. This setting requires the Docker Model Runner and Enable host-side TCP support settings to be enabled first.                                                                                       |         |
| `enableInferenceCORS`       |              | Specifies the allowed CORS origins. Empty string to deny all,`*` to accept all, or a list of comma-separated values. This setting requires the Docker Model Runner and Enable host-side TCP support settings to be enabled first.  |         |
| `enableInferenceGPUVariant` | Windows only | Setting `enableInferenceGPUVariant` to `true` enables GPU-backed inference. The additional components required for this don't come by default with Docker Desktop, therefore they will be downloaded to `~/.docker/bin/inference`. |         |

### [Beta features](#beta-features)

> Important
>
> For Docker Desktop versions 4.41 and earlier, some of these settings lived under the **Experimental features** tab on the **Features in development** page.

| Parameter                   | OS | Description                                                                                                                                                                                                                                                            | Version |
| --------------------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `allowBetaFeatures`         |    | If `value` is set to `true`, beta features are enabled.                                                                                                                                                                                                                |         |
| `enableDockerAI`            |    | If `allowBetaFeatures` is true, setting `enableDockerAI` to `true` enables [Gordon](https://docs.docker.com/ai/gordon/) by default. You can independently control this setting from the `allowBetaFeatures` setting.                                                   |         |
| `enableDockerMCPToolkit`    |    | If `allowBetaFeatures` is true, setting `enableDockerMCPToolkit` to `true` enables the [MCP Toolkit feature](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/) by default. You can independently control this setting from the `allowBetaFeatures` setting. |         |
| `allowExperimentalFeatures` |    | If `value` is set to `true`, experimental features are enabled.                                                                                                                                                                                                        |         |

### [Enhanced Container Isolation](#enhanced-container-isolation)

| Parameter                    | OS | Description                                                                                                                                                                                                                                                                                                                                                                                                | Version |
| ---------------------------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `enhancedContainerIsolation` |    | If `value` is set to true, Docker Desktop runs all containers as unprivileged, via the Linux user-namespace, prevents them from modifying sensitive configurations inside the Docker Desktop VM, and uses other advanced techniques to isolate them. For more information, see [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/). |         |
|        `dockerSocketMount`   |    | By default, enhanced container isolation blocks bind-mounting the Docker Engine socket into containers (e.g., `docker run -v /var/run/docker.sock:/var/run/docker.sock ...`). This lets you relax this in a controlled way. See [ECI Configuration](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/) for more info.                                      |         |
|               `imageList`    |    | Indicates which container images are allowed to bind-mount the Docker Engine socket.                                                                                                                                                                                                                                                                                                                       |         |
|               `commandList`  |    | Restricts the commands that containers can issue via the bind-mounted Docker Engine socket.                                                                                                                                                                                                                                                                                                                |         |

----
url: https://docs.docker.com/ai/sandboxes/agents/docker-agent/
----

***

Table of contents

***

Official documentation: [Docker Agent](https://docs.docker.com/ai/docker-agent/)

## [Quick start](#quick-start)

Create a sandbox and run Docker Agent for a project directory:

```console
$ sbx run docker-agent ~/my-project
```

The workspace parameter defaults to the current directory, so `sbx run docker-agent` from inside your project works too.

## [Authentication](#authentication)

Docker Agent supports multiple providers. Store keys for the providers you want to use with [stored secrets](https://docs.docker.com/ai/sandboxes/security/credentials/#stored-secrets):

```console
$ sbx secret set -g openai
$ sbx secret set -g anthropic
$ sbx secret set -g google
$ sbx secret set -g xai
$ sbx secret set -g nebius
$ sbx secret set -g mistral
```

You only need to configure the providers you want to use. Docker Agent detects available credentials and routes requests to the appropriate provider.

Alternatively, export the environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`, `NEBIUS_API_KEY`, `MISTRAL_API_KEY`) in your shell before running the sandbox. See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for details on both methods.

## [Configuration](#configuration)

Sandboxes don't pick up user-level configuration from your host. Only project-level configuration in the working directory is available inside the sandbox. See [Why doesn't the sandbox use my user-level agent configuration?](https://docs.docker.com/ai/sandboxes/faq/#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for workarounds.

### [Default startup command](#default-startup-command)

Without extra args, the sandbox runs:

```text
docker-agent run --yolo
```

Args after `--` replace these defaults rather than being appended. To keep `run --yolo`, include them yourself:

```console
$ sbx run docker-agent -- run --yolo agent.yml
```

## [Base image](#base-image)

The sandbox uses `docker/sandbox-templates:docker-agent`. See [Templates](https://docs.docker.com/ai/sandboxes/customize/templates/) to build your own image on top of this base.

----
url: https://docs.docker.com/admin/organization/deactivate-account/
----

# Deactivate an organization

***

Table of contents

***

For: Administrators

Learn how to deactivate a Docker organization, including required prerequisite steps. For information about deactivating user accounts, see [Deactivate a user account](https://docs.docker.com/accounts/deactivate-user-account/).

> Warning
>
> All Docker products and services that use your Docker account or organization account will be inaccessible after deactivating your account.

## [Prerequisites](#prerequisites)

You must complete all the following steps before you can deactivate your organization:

* Download any images and tags you want to keep. Use `docker pull -a <image>` to pull all tags, or `docker pull <image>:<tag>` to pull a specific tag.
* If you have an active Docker subscription, [downgrade it to a free subscription](https://docs.docker.com/subscription/change/).
* Remove all other members within the organization.
* Unlink your [GitHub and Bitbucket accounts](https://docs.docker.com/docker-hub/repos/manage/builds/link-source/#unlink-a-github-user-account).
* For Business organizations, [remove your SSO connection](https://docs.docker.com/enterprise/security/single-sign-on/manage/#remove-an-organization).

## [Deactivate](#deactivate)

You can deactivate your organization using either the Admin Console or Docker Hub.

> Warning
>
> This cannot be undone. Be sure you've gathered all the data you need from your organization before deactivating it.

1. Sign in to [Docker Home](https://app.docker.com) and select the organization you want to deactivate.
2. Select **Admin Console**, then **Deactivate**. If the **Deactivate** button is unavailable, confirm you've completed all [Prerequisites](#prerequisites).
3. Enter the organization name to confirm deactivation.
4. Select **Deactivate organization**.

----
url: https://docs.docker.com/reference/api/extensions-sdk/Dialog/
----

# Interface: Dialog

***

Table of contents

***

Allows opening native dialog boxes.

**`Since`**

0.2.3

## [Methods](#methods)

### [showOpenDialog](#showopendialog)

▸ **showOpenDialog**(`dialogProperties`): `Promise`<[`OpenDialogResult`](https://docs.docker.com/reference/api/extensions-sdk/OpenDialogResult/)>

Display a native open dialog. Lets you select a file or a folder.

```typescript
ddClient.desktopUI.dialog.showOpenDialog({properties: ['openFile']});
```

#### [Parameters](#parameters)

| Name               | Type  | Description                                                                                                                                         |
| ------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dialogProperties` | `any` | Properties to specify the open dialog behaviour, see <https://www.electronjs.org/docs/latest/api/dialog#dialogshowopendialogbrowserwindow-options>. |

#### [Returns](#returns)

`Promise`<[`OpenDialogResult`](https://docs.docker.com/reference/api/extensions-sdk/OpenDialogResult/)>

----
url: https://docs.docker.com/reference/cli/docker/sandbox/create/gemini/
----

# docker sandbox create gemini

***

| Description | Create a sandbox for gemini                                   |
| ----------- | ------------------------------------------------------------- |
| Usage       | `docker sandbox create gemini WORKSPACE [EXTRA_WORKSPACE...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Create a sandbox with access to a host workspace for gemini.

The workspace path is required and will be exposed inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use 'docker sandbox run SANDBOX' to start gemini after creation.

## [Examples](#examples)

### [Create a Gemini sandbox in the current directory](#create-a-gemini-sandbox-in-the-current-directory)

```console
$ docker sandbox create gemini .
```

### [Create with an absolute path](#create-with-an-absolute-path)

```console
$ docker sandbox create gemini /home/user/my-project
```

### [Create and then run](#create-and-then-run)

```console
$ docker sandbox create --name my-gemini gemini ~/my-project
$ docker sandbox run my-gemini
```

----
url: https://docs.docker.com/scout/integrations/ci/gha/
----

# Integrate Docker Scout with GitHub Actions

***

Table of contents

***

The following example shows how to set up a Docker Scout workflow with GitHub Actions. Triggered by a pull request, the action builds the image and uses Docker Scout to compare the new version to the version of that image running in production.

This workflow uses the [docker/scout-action](https://github.com/docker/scout-action) GitHub Action to run the `docker scout compare` command to visualize how images for pull request stack up against the image you run in production.

## [Prerequisites](#prerequisites)

* This example assumes that you have an existing image repository, in Docker Hub or in another registry, where you've enabled Docker Scout.
* This example makes use of [environments](https://docs.docker.com/scout/integrations/environment/), to compare the image built in the pull request with a different version of the same image in an environment called `production`.

## [Steps](#steps)

First, set up the GitHub Action workflow to build an image. This isn't specific to Docker Scout here, but you'll need to build an image to have something to compare with.

Add the following to a GitHub Actions YAML file:

```yaml
name: Docker

on:
  push:
    tags: ["*"]
    branches:
      - "main"
  pull_request:
    branches: ["**"]

env:
  # Hostname of your registry
  REGISTRY: docker.io
  # Image repository, without hostname and tag
  IMAGE_NAME: ${{ github.repository }}
  SHA: ${{ github.event.pull_request.head.sha || github.event.after }}

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write

    steps:
      # Authenticate to the container registry
      - name: Authenticate to registry ${{ env.REGISTRY }}
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ secrets.REGISTRY_USER }}
          password: ${{ secrets.REGISTRY_TOKEN }}
      
      - name: Setup Docker buildx
        uses: docker/setup-buildx-action@v4

      # Extract metadata (tags, labels) for Docker
      - name: Extract Docker metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          labels: |
            org.opencontainers.image.revision=${{ env.SHA }}
          tags: |
            type=edge,branch=$repo.default_branch
            type=semver,pattern=v{{version}}
            type=sha,prefix=,suffix=,format=short

      # Build and push Docker image with Buildx
      # (don't push on PR, load instead)
      - name: Build and push Docker image
        id: build-and-push
        uses: docker/build-push-action@v7
        with:
          sbom: ${{ github.event_name != 'pull_request' }}
          provenance: ${{ github.event_name != 'pull_request' }}
          push: ${{ github.event_name != 'pull_request' }}
          load: ${{ github.event_name == 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
```

This creates workflow steps to:

1. Set up Docker buildx.
2. Authenticate to the registry.
3. Extract metadata from Git reference and GitHub events.
4. Build and push the Docker image to the registry.

> Note
>
> This CI workflow runs a local analysis and evaluation of your image. To evaluate the image locally, you must ensure that the image is loaded the local image store of your runner.
>
> This comparison doesn't work if you push the image to a registry, or if you build an image that can't be loaded to the runner's local image store. For example, multi-platform images or images with SBOM or provenance attestation can't be loaded to the local image store.

With this setup out of the way, you can add the following steps to run the image comparison:

```yaml
      # You can skip this step if Docker Hub is your registry
      # and you already authenticated before
      - name: Authenticate to Docker
        uses: docker/login-action@v4
        with:
          username: ${{ secrets.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PAT }}

      # Compare the image built in the pull request with the one in production
      - name: Docker Scout
        id: docker-scout
        if: ${{ github.event_name == 'pull_request' }}
        uses: docker/scout-action@v1
        with:
          command: compare
          image: ${{ steps.meta.outputs.tags }}
          to-env: production
          ignore-unchanged: true
          only-severities: critical,high
          github-token: ${{ secrets.GITHUB_TOKEN }}
```

The compare command analyzes the image and evaluates policy compliance, and cross-references the results with the corresponding image in the `production` environment. This example only includes critical and high-severity vulnerabilities, and excludes vulnerabilities that exist in both images, showing only what's changed.

The GitHub Action outputs the comparison results in a pull request comment by default.

Expand the **Policies** section to view the difference in policy compliance between the two images. Note that while the new image in this example isn't fully compliant, the output shows that the standing for the new image has improved compared to the baseline.

----
url: https://docs.docker.com/dhi/explore/test/
----

# How Docker Hardened Images are tested

***

Table of contents

***

Docker Hardened Images (DHIs) are designed to be secure, minimal, and production-ready. To ensure their reliability and security, Docker employs a comprehensive testing strategy, which you can independently verify using signed attestations and open tooling.

Every image is tested for standards compliance, functionality, and security. The results of this testing are embedded as signed attestations, which can be [inspected and verified](#view-and-verify-the-test-attestation) programmatically using the Docker Scout CLI.

## [Testing strategy overview](#testing-strategy-overview)

The testing process for DHIs focuses on two main areas:

* Image standards compliance: Ensuring that each image adheres to strict size, security, and compatibility standards.
* Application functionality: Verifying that applications within the images function correctly.

## [Image standards compliance](#image-standards-compliance)

Each DHI undergoes rigorous checks to meet the following standards:

* Minimal attack surface: Images are built to be as small as possible, removing unnecessary components to reduce potential vulnerabilities.
* Near-zero known CVEs: Images are scanned using tools like Docker Scout to ensure they are free from known Common Vulnerabilities and Exposures (CVEs).
* Multi-architecture support: DHIs are built for multiple architectures (`linux/amd64` and `linux/arm64`) to ensure broad compatibility.
* Kubernetes compatibility: Images are tested to run seamlessly within Kubernetes clusters, ensuring they meet the requirements for container orchestration environments.

## [Application functionality testing](#application-functionality-testing)

Docker tests Docker Hardened Images to ensure they behave as expected in typical usage scenarios. This includes verifying that:

* Applications start and run successfully in containerized environments.
* Runtime behavior aligns with upstream expectations.
* Build variants (like `-dev` images) support common development and build tasks.

The goal is to ensure that DHIs work out of the box for the most common use cases while maintaining the hardened, minimal design.

## [Automated testing and CI/CD integration](#automated-testing-and-cicd-integration)

Docker integrates automated testing into its Continuous Integration/Continuous Deployment (CI/CD) pipelines:

* Automated scans: Each image build triggers automated scans for vulnerabilities and compliance checks.
* Reproducible builds: Build processes are designed to be reproducible, ensuring consistency across different environments.
* Continuous monitoring: Docker continuously monitors for new vulnerabilities and updates images accordingly to maintain security standards.

## [Testing attestation](#testing-attestation)

Docker provides a test attestation that details the testing and validation processes each DHI has undergone.

### [View and verify the test attestation](#view-and-verify-the-test-attestation)

You can view and verify this attestation using the Docker Scout CLI.

1. Use the `docker scout attest get` command with the test predicate type:

   ```console
   $ docker scout attest get \
     --predicate-type https://scout.docker.com/tests/v0.1 \
     --predicate \
     dhi.io/<image>:<tag>
   ```

   > Note
   >
   > If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use `registry://dhi.io/python` instead of `dhi.io/python`.

   For example:

   ```console
   $ docker scout attest get \
     --predicate-type https://scout.docker.com/tests/v0.1 \
     --predicate \
     dhi.io/python:3.13
   ```

   This contains a list of tests and their results.

   Example output:

   ```console
       v SBOM obtained from attestation, 101 packages found
       v Provenance obtained from attestation
       {
         "reportFormat": "CTRF",
         "results": {
           "summary": {
             "failed": 0,
             "passed": 1,
             "skipped": 0,
             "start": 1749216533,
             "stop": 1749216574,
             "tests": 1
           },
           "tests": [
             {
               ...
   ```

2. Verify the test attestation signature. To ensure the attestation is authentic and signed by Docker, run:

   ```console
   docker scout attest get \
     --predicate-type https://scout.docker.com/tests/v0.1 \
     --verify \
     dhi.io/<image>:<tag> --platform <platform>
   ```

   Example output:

   ```console
    v SBOM obtained from attestation, 101 packages found
    v Provenance obtained from attestation
    v cosign verify registry.scout.docker.com/docker/dhi-python@sha256:70c8299c4d3cb4d5432734773c45ae58d8acc2f2f07803435c65515f662136d5 \
        --key https://registry.scout.docker.com/keyring/dhi/latest.pub --experimental-oci11

      Verification for registry.scout.docker.com/docker/dhi-python@sha256:70c8299c4d3cb4d5432734773c45ae58d8acc2f2f07803435c65515f662136d5 --
      The following checks were performed on each of these signatures:
        - The cosign claims were validated
        - Existence of the claims in the transparency log was verified offline
        - The signatures were verified against the specified public key

    i Signature payload
    ...
   ```

If the attestation is valid, Docker Scout will confirm the signature and show the matching `cosign verify` command.

To view other attestations, such as SBOMs or vulnerability reports, see [Verify an image](https://docs.docker.com/dhi/how-to/verify/).

----
url: https://docs.docker.com/reference/cli/docker/stack/ps/
----

# docker stack ps

***

| Description | List the tasks in the stack       |
| ----------- | --------------------------------- |
| Usage       | `docker stack ps [OPTIONS] STACK` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Lists the tasks that are running as part of the specified stack.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                        | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --filter`](#filter)     |         | Filter output based on conditions provided                                                                                                                                                                                                                                                                                                                                             |
| [`--format`](#format)         |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| [`--no-resolve`](#no-resolve) |         | Do not map IDs to Names                                                                                                                                                                                                                                                                                                                                                                |
| [`--no-trunc`](#no-trunc)     |         | Do not truncate output                                                                                                                                                                                                                                                                                                                                                                 |
| [`-q, --quiet`](#quiet)       |         | Only display task IDs                                                                                                                                                                                                                                                                                                                                                                  |

## [Examples](#examples)

### [List the tasks that are part of a stack](#list-the-tasks-that-are-part-of-a-stack)

The following command shows all the tasks that are part of the `voting` stack:

```console
$ docker stack ps voting

ID                  NAME                  IMAGE                                          NODE   DESIRED STATE  CURRENT STATE          ERROR  PORTS
xim5bcqtgk1b        voting_worker.1       dockersamples/examplevotingapp_worker:latest   node2  Running        Running 2 minutes ago
q7yik0ks1in6        voting_result.1       dockersamples/examplevotingapp_result:before   node1  Running        Running 2 minutes ago
rx5yo0866nfx        voting_vote.1         dockersamples/examplevotingapp_vote:before     node3  Running        Running 2 minutes ago
tz6j82jnwrx7        voting_db.1           postgres:9.4                                   node1  Running        Running 2 minutes ago
w48spazhbmxc        voting_redis.1        redis:alpine                                   node2  Running        Running 3 minutes ago
6jj1m02freg1        voting_visualizer.1   dockersamples/visualizer:stable                node1  Running        Running 2 minutes ago
kqgdmededccb        voting_vote.2         dockersamples/examplevotingapp_vote:before     node2  Running        Running 2 minutes ago
t72q3z038jeh        voting_redis.2        redis:alpine                                   node3  Running        Running 3 minutes ago
```

```console
$ docker stack ps -f "id=t" voting

ID                  NAME                IMAGE               NODE         DESIRED STATE       CURRENTSTATE            ERROR  PORTS
tz6j82jnwrx7        voting_db.1         postgres:9.4        node1        Running             Running 14 minutes ago
t72q3z038jeh        voting_redis.2      redis:alpine        node3        Running             Running 14 minutes ago
```

#### [name](#name)

The `name` filter matches on task names.

```console
$ docker stack ps -f "name=voting_redis" voting

ID                  NAME                IMAGE               NODE         DESIRED STATE       CURRENTSTATE            ERROR  PORTS
w48spazhbmxc        voting_redis.1      redis:alpine        node2        Running             Running 17 minutes ago
t72q3z038jeh        voting_redis.2      redis:alpine        node3        Running             Running 17 minutes ago
```

#### [node](#node)

The `node` filter matches on a node name or a node ID.

```console
$ docker stack ps -f "node=node1" voting

ID                  NAME                  IMAGE                                          NODE   DESIRED STATE  CURRENT STATE          ERROR  PORTS
q7yik0ks1in6        voting_result.1       dockersamples/examplevotingapp_result:before   node1  Running        Running 18 minutes ago
tz6j82jnwrx7        voting_db.1           postgres:9.4                                   node1  Running        Running 18 minutes ago
6jj1m02freg1        voting_visualizer.1   dockersamples/visualizer:stable                node1  Running        Running 18 minutes ago
```

#### [desired-state](#desired-state)

The `desired-state` filter can take the values `running`, `shutdown`, `ready` or `accepted`.

```console
$ docker stack ps -f "desired-state=running" voting

ID                  NAME                  IMAGE                                          NODE   DESIRED STATE  CURRENT STATE           ERROR  PORTS
xim5bcqtgk1b        voting_worker.1       dockersamples/examplevotingapp_worker:latest   node2  Running        Running 21 minutes ago
q7yik0ks1in6        voting_result.1       dockersamples/examplevotingapp_result:before   node1  Running        Running 21 minutes ago
rx5yo0866nfx        voting_vote.1         dockersamples/examplevotingapp_vote:before     node3  Running        Running 21 minutes ago
tz6j82jnwrx7        voting_db.1           postgres:9.4                                   node1  Running        Running 21 minutes ago
w48spazhbmxc        voting_redis.1        redis:alpine                                   node2  Running        Running 21 minutes ago
6jj1m02freg1        voting_visualizer.1   dockersamples/visualizer:stable                node1  Running        Running 21 minutes ago
kqgdmededccb        voting_vote.2         dockersamples/examplevotingapp_vote:before     node2  Running        Running 21 minutes ago
t72q3z038jeh        voting_redis.2        redis:alpine                                   node3  Running        Running 21 minutes ago
```

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints tasks output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder     | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `.ID`           | Task ID                                                          |
| `.Name`         | Task name                                                        |
| `.Image`        | Task image                                                       |
| `.Node`         | Node ID                                                          |
| `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) |
| `.CurrentState` | Current state of the task                                        |
| `.Error`        | Error                                                            |
| `.Ports`        | Task published ports                                             |

When using the `--format` option, the `stack ps` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `Name` and `Image` entries separated by a colon (`:`) for all tasks:

```console
$ docker stack ps --format "{{.Name}}: {{.Image}}" voting

voting_worker.1: dockersamples/examplevotingapp_worker:latest
voting_result.1: dockersamples/examplevotingapp_result:before
voting_vote.1: dockersamples/examplevotingapp_vote:before
voting_db.1: postgres:9.4
voting_redis.1: redis:alpine
voting_visualizer.1: dockersamples/visualizer:stable
voting_vote.2: dockersamples/examplevotingapp_vote:before
voting_redis.2: redis:alpine
```

To list all tasks in JSON format, use the `json` directive:

```console
$ docker stack ps --format json myapp
{"CurrentState":"Preparing 23 seconds ago","DesiredState":"Running","Error":"","ID":"2ufjubh79tn0","Image":"localstack/localstack:latest","Name":"myapp_localstack.1","Node":"docker-desktop","Ports":""}
{"CurrentState":"Running 20 seconds ago","DesiredState":"Running","Error":"","ID":"roee387ngf5r","Image":"redis:6.0.9-alpine3.12","Name":"myapp_redis.1","Node":"docker-desktop","Ports":""}
{"CurrentState":"Preparing 13 seconds ago","DesiredState":"Running","Error":"","ID":"yte68ouq7glh","Image":"postgres:13.2-alpine","Name":"myapp_repos-db.1","Node":"docker-desktop","Ports":""}
```

### [Do not map IDs to Names (--no-resolve)](#no-resolve)

The `--no-resolve` option shows IDs for task name, without mapping IDs to Names.

```console
$ docker stack ps --no-resolve voting

ID                  NAME                          IMAGE                                          NODE                        DESIRED STATE  CURRENT STATE            ERROR  PORTS
xim5bcqtgk1b        10z9fjfqzsxnezo4hb81p8mqg.1   dockersamples/examplevotingapp_worker:latest   qaqt4nrzo775jrx6detglho01   Running        Running 30 minutes ago
q7yik0ks1in6        hbxltua1na7mgqjnidldv5m65.1   dockersamples/examplevotingapp_result:before   mxpaef1tlh23s052erw88a4w5   Running        Running 30 minutes ago
rx5yo0866nfx        qyprtqw1g5nrki557i974ou1d.1   dockersamples/examplevotingapp_vote:before     kanqcxfajd1r16wlnqcblobmm   Running        Running 31 minutes ago
tz6j82jnwrx7        122f0xxngg17z52be7xspa72x.1   postgres:9.4                                   mxpaef1tlh23s052erw88a4w5   Running        Running 31 minutes ago
w48spazhbmxc        tg61x8myx563ueo3urmn1ic6m.1   redis:alpine                                   qaqt4nrzo775jrx6detglho01   Running        Running 31 minutes ago
6jj1m02freg1        8cqlyi444kzd3panjb7edh26v.1   dockersamples/visualizer:stable                mxpaef1tlh23s052erw88a4w5   Running        Running 31 minutes ago
kqgdmededccb        qyprtqw1g5nrki557i974ou1d.2   dockersamples/examplevotingapp_vote:before     qaqt4nrzo775jrx6detglho01   Running        Running 31 minutes ago
t72q3z038jeh        tg61x8myx563ueo3urmn1ic6m.2   redis:alpine                                   kanqcxfajd1r16wlnqcblobmm   Running        Running 31 minutes ago
```

### [Do not truncate output (--no-trunc)](#no-trunc)

When deploying a service, docker resolves the digest for the service's image, and pins the service to that digest. The digest is not shown by default, but is printed if `--no-trunc` is used. The `--no-trunc` option also shows the non-truncated task IDs, and error-messages, as can be seen below:

```console
$ docker stack ps --no-trunc voting

ID                          NAME                  IMAGE                                                                                                                 NODE   DESIRED STATE  CURREN STATE           ERROR  PORTS
xim5bcqtgk1bxqz91jzo4a1s5   voting_worker.1       dockersamples/examplevotingapp_worker:latest@sha256:3e4ddf59c15f432280a2c0679c4fc5a2ee5a797023c8ef0d3baf7b1385e9fed   node2  Running        Running 32 minutes ago
q7yik0ks1in6kv32gg6y6yjf7   voting_result.1       dockersamples/examplevotingapp_result:before@sha256:83b56996e930c292a6ae5187fda84dd6568a19d97cdb933720be15c757b7463   node1  Running        Running 32 minutes ago
rx5yo0866nfxc58zf4irsss6n   voting_vote.1         dockersamples/examplevotingapp_vote:before@sha256:8e64b182c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6     node3  Running        Running 32 minutes ago
tz6j82jnwrx7n2offljp3mn03   voting_db.1           postgres:9.4@sha256:6046af499eae34d2074c0b53f9a8b404716d415e4a03e68bc1d2f8064f2b027                                   node1  Running        Running 32 minutes ago
w48spazhbmxcmbjfi54gs7x90   voting_redis.1        redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7                                   node2  Running        Running 32 minutes ago
6jj1m02freg1n3z9n1evrzsbl   voting_visualizer.1   dockersamples/visualizer:stable@sha256:f924ad66c8e94b10baaf7bdb9cd491ef4e982a1d048a56a17e02bf5945401e5                node1  Running        Running 32 minutes ago
kqgdmededccbhz2wuc0e9hx7g   voting_vote.2         dockersamples/examplevotingapp_vote:before@sha256:8e64b182c87de902f2b72321c89b4af4e2b942d76d0b772532ff27ec4c6ebf6     node2  Running        Running 32 minutes ago
t72q3z038jehe1wbh9gdum076   voting_redis.2        redis:alpine@sha256:9cd405cd1ec1410eaab064a1383d0d8854d1ef74a54e1e4a92fb4ec7bdc3ee7                                   node3  Running        Running 32 minutes ago
```

### [Only display task IDs (-q, --quiet)](#quiet)

The `-q `or `--quiet` option only shows IDs of the tasks in the stack. This example outputs all task IDs of the `voting` stack:

```console
$ docker stack ps -q voting
xim5bcqtgk1b
q7yik0ks1in6
rx5yo0866nfx
tz6j82jnwrx7
w48spazhbmxc
6jj1m02freg1
kqgdmededccb
t72q3z038jeh
```

This option can be used to perform batch operations. For example, you can use the task IDs as input for other commands, such as `docker inspect`. The following example inspects all tasks of the `voting` stack:

```console
$ docker inspect $(docker stack ps -q voting)

[
    {
        "ID": "xim5bcqtgk1b1gk0krq1",
        "Version": {
<...>
```

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/
----

# Docker MCP Catalog

***

Table of contents

***

Availability: Beta

The [Docker MCP Catalog](https://hub.docker.com/mcp) is a curated collection of verified MCP servers, packaged as Docker images and distributed through Docker Hub. It solves common challenges with running MCP servers locally: environment conflicts, setup complexity, and security concerns.

The catalog serves as the source of available MCP servers. When you add servers to your [profiles](https://docs.docker.com/ai/mcp-catalog-and-toolkit/profiles/), you select them from the catalog. Each server runs as an isolated container, making it portable and consistent across different environments.

> Note
>
> E2B sandboxes now include direct access to the Docker MCP Catalog, giving developers access to over 200 tools and services to seamlessly build and run AI agents. For more information, see [E2B Sandboxes](https://docs.docker.com/ai/mcp-catalog-and-toolkit/e2b-sandboxes/).

## [What's in the catalog](#whats-in-the-catalog)

The Docker MCP Catalog includes:

* Verified servers: All servers are versioned with full provenance and SBOM metadata
* Partner tools: Servers from New Relic, Stripe, Grafana, and other trusted partners
* Docker-built servers: Locally-running servers built and digitally signed by Docker for enhanced security
* Remote services: Cloud-hosted servers that connect to external services like GitHub, Notion, and Linear

### [Local versus remote servers](#local-versus-remote-servers)

The catalog contains two types of servers based on where they run:

Local servers run as containers on your machine. They work offline once downloaded and offer predictable performance and complete data privacy. Docker builds and signs all local servers in the catalog.

Remote servers run on the provider's infrastructure and connect to external services. Many remote servers use OAuth authentication, which the MCP Toolkit handles automatically through your browser.

## [Browse the catalog](#browse-the-catalog)

Browse available MCP servers at [hub.docker.com/mcp](https://hub.docker.com/mcp) or directly in Docker Desktop:

1. In Docker Desktop, select **MCP Toolkit**.
2. Select the **Catalog** tab to browse available servers.
3. Select a server to view its description, tools, and configuration options.

## [Add servers to a profile](#add-servers-to-a-profile)

To add a server from the catalog to a profile:

1. In the **Catalog** tab, select the checkbox next to a server.
2. Choose the profile to add it to from the drop-down.

For step-by-step instructions and client connection, see [Get started with MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/get-started/) or [MCP Profiles](https://docs.docker.com/ai/mcp-catalog-and-toolkit/profiles/).

## [Custom catalogs](#custom-catalogs)

Custom catalogs let you curate focused collections of servers for your team or organization. Instead of exposing all 300+ servers in the Docker catalog, you define exactly which servers are available.

Common use cases:

* Restrict which servers your organization approves for use
* Add your organization's private MCP servers alongside public ones
* Control which server versions your team uses
* Define the server set available to AI agents using [Dynamic MCP](https://docs.docker.com/ai/mcp-catalog-and-toolkit/dynamic-mcp/)

### [Custom catalogs with Dynamic MCP](#custom-catalogs-with-dynamic-mcp)

Custom catalogs work particularly well with [Dynamic MCP](/ai/mcp-catalog-and-toolkit/dynamic-mcp/), where agents discover and add MCP servers on-demand during conversations. When you run the gateway with a custom catalog, the `mcp-find` tool searches only within that catalog. If your catalog contains 20 servers instead of 300+, agents work within that focused set, discovering and enabling tools as needed without manual configuration each time.

### [Import a custom catalog](#import-a-custom-catalog)

If someone on your team has created and published a catalog, you can import it using its OCI registry reference.

In Docker Desktop:

1. Select **MCP Toolkit** and select the **Catalog** tab.
2. Select **Import catalog**.
3. Enter the OCI reference for the catalog (for example, `registry.example.com/mcp/team-catalog:latest`).
4. Select **Import**.

Using the CLI:

```console
$ docker mcp catalog pull <oci-reference>
```

Once imported, the catalog appears alongside the Docker catalog and you can add its servers to your profiles.

### [Create and manage custom catalogs](#create-and-manage-custom-catalogs)

Creating and managing custom catalogs requires the CLI. See [Custom catalogs](https://docs.docker.com/ai/mcp-catalog-and-toolkit/cli/#custom-catalogs) in the CLI how-to for step-by-step instructions, including:

* Curating a subset of the Docker catalog
* Adding private servers to a catalog
* Building a focused catalog from scratch
* Pushing a catalog to a registry for your team to import

## [Contribute an MCP server to the catalog](#contribute-an-mcp-server-to-the-catalog)

The MCP server registry is available at <https://github.com/docker/mcp-registry>. To submit an MCP server, follow the [contributing guidelines](https://github.com/docker/mcp-registry/blob/main/CONTRIBUTING.md).

When your pull request is reviewed and approved, your MCP server is available within 24 hours on:

* Docker Desktop's [MCP Toolkit feature](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/).
* The [Docker MCP Catalog](https://hub.docker.com/mcp).
* The [Docker Hub](https://hub.docker.com/u/mcp) `mcp` namespace (for MCP servers built by Docker).

----
url: https://docs.docker.com/reference/cli/docker/trust/
----

# docker trust

***

| Description | Manage trust on Docker images |
| ----------- | ----------------------------- |
| Usage       | `docker trust`                |

## [Description](#description)

Manage trust on Docker images

## [Subcommands](#subcommands)

| Command                                                                               | Description                                            |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [`docker trust inspect`](https://docs.docker.com/reference/cli/docker/trust/inspect/) | Return low-level information about keys and signatures |
| [`docker trust key`](https://docs.docker.com/reference/cli/docker/trust/key/)         | Manage keys for signing Docker images                  |
| [`docker trust revoke`](https://docs.docker.com/reference/cli/docker/trust/revoke/)   | Remove trust for an image                              |
| [`docker trust sign`](https://docs.docker.com/reference/cli/docker/trust/sign/)       | Sign an image                                          |
| [`docker trust signer`](https://docs.docker.com/reference/cli/docker/trust/signer/)   | Manage entities who can sign Docker images             |

----
url: https://docs.docker.com/engine/release-notes/18.06/
----

# Docker Engine 18.06 release notes

***

Table of contents

***

## [18.06.3-ce](#18063-ce)

2019-02-19

### [Security fixes for Docker Engine](#security-fixes-for-docker-engine)

* Change how the `runc` critical vulnerability patch is applied to include the fix in RPM packages. [docker/engine#156](https://github.com/docker/engine/pull/156)

## [18.06.2](#18062)

2019-02-11

### [Security fixes for Docker Engine](#security-fixes-for-docker-engine-1)

* Update `runc` to address a critical vulnerability that allows specially-crafted containers to gain administrative privileges on the host. [CVE-2019-5736](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-5736)
* Ubuntu 14.04 customers using a 3.13 kernel will need to upgrade to a supported Ubuntu 4.x kernel

## [18.06.1-ce](#18061-ce)

2018-08-21

### [Builder](#builder)

* Fix no error if build args are missing during docker build. [docker/engine#25](https://github.com/docker/engine/pull/25)

- Set BuildKit's ExportedProduct variable to show useful errors. [docker/engine#21](https://github.com/docker/engine/pull/21)

### [Client](#client)

* Various shell completion script updates: [docker/cli#1229](https://github.com/docker/cli/pull/1229), [docker/cli#1268](https://github.com/docker/cli/pull/1268), and [docker/cli#1272](https://github.com/docker/cli/pull/1272)

- Fix `DOCKER_CONFIG` warning message and fallback search. [docker/cli#1241](https://github.com/docker/cli/pull/1241)
- Fix help message flags on `docker stack` commands and sub-commands. [docker/cli#1267](https://github.com/docker/cli/pull/1267)

### [Runtime](#runtime)

* Disable CRI plugin listening on port 10010 by default. [docker/engine#29](https://github.com/docker/engine/pull/29)
* Update containerd to v1.1.2. [docker/engine#33](https://github.com/docker/engine/pull/33)

- Windows: Do not invoke HCS shutdown if terminate called. [docker/engine#31](https://github.com/docker/engine/pull/31)

* Windows: Select polling-based watcher for Windows log watcher. [docker/engine#34](https://github.com/docker/engine/pull/34)

### [Swarm Mode](#swarm-mode)

* Fix the condition used for skipping over running tasks. [docker/swarmkit#2677](https://github.com/docker/swarmkit/pull/2677)
* Fix task sorting. [docker/swarmkit#2712](https://github.com/docker/swarmkit/pull/2712)

## [18.06.0-ce](#18060-ce)

2018-07-18

### [Important notes about this release](#important-notes-about-this-release)

* Docker 18.06 CE will be the last release with a 4-month maintenance lifecycle. The planned Docker 18.09 CE release will be supported for 7 months with Docker 19.03 CE being the next release in line. More details about the release process can be found [here](https://docs.docker.com/get-started/get-docker/).

### [Builder](#builder-1)

* Builder: fix layer leak on multi-stage wildcard copy. [moby/moby#37178](https://github.com/moby/moby/pull/37178)
* Fix parsing of invalid environment variable substitution . [moby/moby#37134](https://github.com/moby/moby/pull/37134)
* Builder: use the arch info from base image. [moby/moby#36816](https://github.com/moby/moby/pull/36816) [moby/moby#37197](https://github.com/moby/moby/pull/37197)

- New experimental builder backend based on [BuildKit](https://github.com/moby/buildkit). To enable, run daemon in experimental mode and set `DOCKER_BUILDKIT=1` environment variable on the docker CLI. [moby/moby#37151](https://github.com/moby/moby/pull/37151) [docker/cli#1111](https://github.com/docker/cli/pull/1111)

* Fix handling uppercase targets names in multi-stage builds. [moby/moby#36960](https://github.com/moby/moby/pull/36960)

### [Client](#client-1)

* Bump spf13/cobra to v0.0.3, pflag to v1.0.1. [moby/moby#37106](https://github.com/moby/moby/pull/37106)
* Add support for the new Stack API for Kubernetes v1beta2. [docker/cli#899](https://github.com/docker/cli/pull/899)
* K8s: more robust stack error detection on deploy. [docker/cli#948](https://github.com/docker/cli/pull/948)
* Support for rollback config in compose 3.7. [docker/cli#409](https://github.com/docker/cli/pull/409)
* Update Cobra and pflag, and use built-in --version feature. [docker/cli#1069](https://github.com/docker/cli/pull/1069)
* Fix `docker stack deploy --prune` with empty name removing all services. [docker/cli#1088](https://github.com/docker/cli/pull/1088)
* \[Kubernetes] stack services filters. [docker/cli#1023](https://github.com/docker/cli/pull/1023)

- Only show orchestrator flag in root, stack and version commands in help. [docker/cli#1106](https://github.com/docker/cli/pull/1106)
- Add an `Extras` field on the compose config types. [docker/cli#1126](https://github.com/docker/cli/pull/1126)
- Add options to the compose loader. [docker/cli#1128](https://github.com/docker/cli/pull/1128)

* Fix always listing nodes in docker stack ps command on Kubernetes. [docker/cli#1093](https://github.com/docker/cli/pull/1093)
* Fix output being shown twice on stack rm error message. [docker/cli#1093](https://github.com/docker/cli/pull/1093)

- Extend client API with custom HTTP requests. [moby/moby#37071](https://github.com/moby/moby/pull/37071)
- Changed error message for unreadable files to clarify possibility of a .Dockerignore entry. [docker/cli#1053](https://github.com/docker/cli/pull/1053)
- Restrict kubernetes.allNamespaces value to 'enabled' or 'disabled' in configuration file. [docker/cli#1087](https://github.com/docker/cli/pull/1087)
- Check errors when initializing the docker client in the help command. [docker/cli#1119](https://github.com/docker/cli/pull/1119)
- Better namespace experience with Kubernetes. Fix using namespace defined in \~/.kube/config for stack commands. Add a NAMESPACE column for docker stack ls command. Add a --all-namespaces flag for docker stack ls command. [docker/cli#991](https://github.com/docker/cli/pull/991)
- Export Push and Save. [docker/cli#1123](https://github.com/docker/cli/pull/1123)
- Export pull as a public function. [docker/cli#1026](https://github.com/docker/cli/pull/1026)
- Remove Kubernetes commands from experimental. [docker/cli#1068](https://github.com/docker/cli/pull/1068)
- Adding configs/secrets to service inspect pretty. [docker/cli#1006](https://github.com/docker/cli/pull/1006)

* Fix service filtering by name on Kubernetes. [docker/cli#1101](https://github.com/docker/cli/pull/1101)
* Fix component information alignment in `docker version`. [docker/cli#1065](https://github.com/docker/cli/pull/1065)
* Fix cpu/memory limits and reservations being reset on service update. [docker/cli#1079](https://github.com/docker/cli/pull/1079)

- Manifest list: request specific permissions. [docker/cli#1024](https://github.com/docker/cli/pull/1024)
- Setting --orchestrator=all also sets --all-namespaces unless specific --namespace are set. [docker/cli#1059](https://github.com/docker/cli/pull/1059)

* Fix panics when --compress and --stream are used together. [docker/cli#1105](https://github.com/docker/cli/pull/1105)

- Switch from x/net/context to context. [docker/cli#1038](https://github.com/docker/cli/pull/1038)

* Add --init option to `docker service create`. [docker/cli#479](https://github.com/docker/cli/pull/479)
* Fixed bug displaying garbage output for build command when --stream and --quiet flags combined. [docker/cli#1090](https://github.com/docker/cli/pull/1090)
* Add `init` support in 3.7 schema. [docker/cli#1129](https://github.com/docker/cli/pull/1129)

- Fix docker trust signer removal. [docker/cli#1112](https://github.com/docker/cli/pull/1112)
- Fix error message from docker inspect. [docker/cli#1071](https://github.com/docker/cli/pull/1071)

* Allow `x-*` extension on 3rd level objects. [docker/cli#1097](https://github.com/docker/cli/pull/1097)
* An invalid orchestrator now generates an error instead of being silently ignored. [docker/cli#1055](https://github.com/docker/cli/pull/1055)
* Added ORCHESTRATOR column to docker stack ls command. [docker/cli#973](https://github.com/docker/cli/pull/973)
* Warn when using host-ip for published ports for services. [docker/cli#1017](https://github.com/docker/cli/pull/1017)

- Added the option to enable experimental cli features through the `DOCKER_CLI_EXPERIMENTAL` environment variable. [docker/cli#1138](https://github.com/docker/cli/pull/1138)
- Add exec\_die to the list of known container events. [docker/cli#1028](https://github.com/docker/cli/pull/1028)

* \[K8s] Do env-variable expansion on the uninterpreted Config files. [docker/cli#974](https://github.com/docker/cli/pull/974)

- Print warnings on stderr for each unsupported features while parsing a compose file for deployment on Kubernetes. [docker/cli#903](https://github.com/docker/cli/pull/903)
- Added description about pids count. [docker/cli#1045](https://github.com/docker/cli/pull/1045)

* Warn user of filter when pruning. [docker/cli#1043](https://github.com/docker/cli/pull/1043)
* Fix `--rollback-*` options overwriting `--update-*` options. [docker/cli#1052](https://github.com/docker/cli/pull/1052)

- Update Attach, Build, Commit, Cp, Create subcommand fish completions. [docker/cli#1005](https://github.com/docker/cli/pull/1005)

* Add bash completion for `dockerd --default-address-pool`. [docker/cli#1173](https://github.com/docker/cli/pull/1173)
* Add bash completion for `exec_die` event. [docker/cli#1173](https://github.com/docker/cli/pull/1173)

- Update docker-credential-helper so `pass` is not called on every docker command. [docker/cli#1184](https://github.com/docker/cli/pull/1184)
- Fix for rotating swarm external CA. [docker/cli#1199](https://github.com/docker/cli/pull/1199)
- Improve version output alignment. [docker/cli#1207](https://github.com/docker/cli/pull/1207)

* Add bash completion for `service create|update --init`. [docker/cli#1210](https://github.com/docker/cli/pull/1210)

### [Deprecation](#deprecation)

* Document reserved namespaces deprecation. [docker/cli#1040](https://github.com/docker/cli/pull/1040)

### [Logging](#logging)

* Allow awslogs to use non-blocking mode. [moby/moby#36522](https://github.com/moby/moby/pull/36522)
* Improve logging of long log lines on fluentd log driver.. [moby/moby#36159](https://github.com/moby/moby/pull/36159)
* Re-order CHANGELOG.md to pass `make validate` test. [moby/moby#37047](https://github.com/moby/moby/pull/37047)
* Update Events, Exec, Export, History, Images, Import, Inspect, Load, and Login subcommand fish completions. [docker/cli#1061](https://github.com/docker/cli/pull/1061)
* Update documentation for RingLogger's ring buffer. [moby/moby#37084](https://github.com/moby/moby/pull/37084)

- Add metrics for log failures/partials. [moby/moby#37034](https://github.com/moby/moby/pull/37034)

* Fix logging plugin crash unrecoverable. [moby/moby#37028](https://github.com/moby/moby/pull/37028)
* Fix logging test type. [moby/moby#37070](https://github.com/moby/moby/pull/37070)
* Fix race conditions in logs API. [moby/moby#37062](https://github.com/moby/moby/pull/37062)
* Fix some issues in logfile reader and rotation. [moby/moby#37063](https://github.com/moby/moby/pull/37063)

### [Networking](#networking)

* Allow user to specify default address pools for docker networks. [moby/moby#36396](https://github.com/moby/moby/pull/36396) [docker/cli#818](https://github.com/docker/cli/pull/818)
* Adding logs for ipam state [docker/libnetwork#2417](https://github.com/docker/libnetwork/pull/2147)
* Fix race conditions in the overlay network driver [docker/libnetwork#2143](https://github.com/docker/libnetwork/pull/2143)
* Add wait time into xtables lock warning [docker/libnetwork#2142](https://github.com/docker/libnetwork/pull/2142)
* filter xtables lock warnings when firewalld is active [docker/libnetwork#2135](https://github.com/docker/libnetwork/pull/2135)
* Switch from x/net/context to context [docker/libnetwork#2140](https://github.com/docker/libnetwork/pull/2140)
* Adding a recovery mechanism for a split gossip cluster [docker/libnetwork#2134](https://github.com/docker/libnetwork/pull/2134)
* Running docker inspect on network attachment tasks now returns a full task object. [moby/moby#35246](https://github.com/moby/moby/pull/35246)
* Some container/network cleanups. [moby/moby#37033](https://github.com/moby/moby/pull/37033)

- Fix network inspect for overlay network. [moby/moby#37045](https://github.com/moby/moby/pull/37045)

* Improve Scalability of the Linux load balancing. [docker/engine#16](https://github.com/docker/engine/pull/16)
* Change log level from error to warning. [docker/engine#19](https://github.com/docker/engine/pull/19)

### [Runtime](#runtime-1)

* Aufs: log why aufs is not supported. [moby/moby#36995](https://github.com/moby/moby/pull/36995)
* Hide experimental checkpoint features on Windows. [docker/cli#1094](https://github.com/docker/cli/pull/1094)
* Lcow: Allow the client to customize capabilities and device cgroup rules for LCOW containers. [moby/moby#37294](https://github.com/moby/moby/pull/37294)
* Changed path given for executable output in windows to actual location of executable output. [moby/moby#37295](https://github.com/moby/moby/pull/37295)

- Add windows recycle bin test and update hcsshim to v0.6.11. [moby/moby#36994](https://github.com/moby/moby/pull/36994)

* Allow to add any args when doing a make run. [moby/moby#37190](https://github.com/moby/moby/pull/37190)
* Optimize ContainerTop() aka docker top. [moby/moby#37131](https://github.com/moby/moby/pull/37131)

- Fix compilation on 32bit machines. [moby/moby#37292](https://github.com/moby/moby/pull/37292)

* Update API version to v1 38. [moby/moby#37141](https://github.com/moby/moby/pull/37141)

- Fix `docker service update --host-add` does not update existing host entry. [docker/cli#1054](https://github.com/docker/cli/pull/1054)
- Fix swagger file type for ExecIds. [moby/moby#36962](https://github.com/moby/moby/pull/36962)
- Fix swagger volume type generation. [moby/moby#37060](https://github.com/moby/moby/pull/37060)
- Fix wrong assertion in volume/service package. [moby/moby#37211](https://github.com/moby/moby/pull/37211)
- Fix daemon panic on restart when a plugin is running. [moby/moby#37234](https://github.com/moby/moby/pull/37234)

* Construct and add 'LABEL' command from 'label' option to last stage. [moby/moby#37011](https://github.com/moby/moby/pull/37011)

- Fix race condition between exec start and resize.. [moby/moby#37172](https://github.com/moby/moby/pull/37172)

* Alternative failure mitigation of `TestExecInteractiveStdinClose`. [moby/moby#37143](https://github.com/moby/moby/pull/37143)
* RawAccess allows a set of paths to be not set as masked or readonly. [moby/moby#36644](https://github.com/moby/moby/pull/36644)
* Be explicit about github.com prefix being a legacy feature. [moby/moby#37174](https://github.com/moby/moby/pull/37174)
* Bump Golang to 1.10.3. [docker/cli#1122](https://github.com/docker/cli/pull/1122)
* Close ReadClosers to prevent xz zombies. [moby/moby#34218](https://github.com/moby/moby/pull/34218)
* Daemon.ContainerStop(): fix for a negative timeout. [moby/moby#36874](https://github.com/moby/moby/pull/36874)
* Daemon.setMounts(): copy slice in place. [moby/moby#36991](https://github.com/moby/moby/pull/36991)
* Describe IP field of swagger Port definition. [moby/moby#36971](https://github.com/moby/moby/pull/36971)
* Extract volume interaction to a volumes service. [moby/moby#36688](https://github.com/moby/moby/pull/36688)
* Fixed markdown formatting in docker image v1, v1.1, and v1.2 spec. [moby/moby#37051](https://github.com/moby/moby/pull/37051)
* Improve GetTimestamp parsing. [moby/moby#35402](https://github.com/moby/moby/pull/35402)
* Jsonmessage: pass message to aux callback. [moby/moby#37064](https://github.com/moby/moby/pull/37064)
* Overlay2: remove unused cdMountFrom() helper function. [moby/moby#37041](https://github.com/moby/moby/pull/37041)

- Overlay: Fix overlay storage-driver silently ignoring unknown storage-driver options. [moby/moby#37040](https://github.com/moby/moby/pull/37040)

* Remove some unused contrib items. [moby/moby#36977](https://github.com/moby/moby/pull/36977)
* Restartmanager: do not apply restart policy on created containers. [moby/moby#36924](https://github.com/moby/moby/pull/36924)
* Set item-type for ExecIDs. [moby/moby#37121](https://github.com/moby/moby/pull/37121)
* Use go-systemd const instead of magic string in Linux version of dockerd. [moby/moby#37136](https://github.com/moby/moby/pull/37136)
* Use stdlib TLS dialer. [moby/moby#36687](https://github.com/moby/moby/pull/36687)
* Warn when an engine label using a reserved namespace (com.docker.\*, io.docker.\*, or org.dockerproject.\*) is configured, as per [Docker object labels](https://docs.docker.com/engine/manage-resources/labels/). [moby/moby#36921](https://github.com/moby/moby/pull/36921)

- Fix missing plugin name in message. [moby/moby#37052](https://github.com/moby/moby/pull/37052)
- Fix link anchors in CONTRIBUTING.md. [moby/moby#37276](https://github.com/moby/moby/pull/37276)
- Fix link to Docker Toolbox. [moby/moby#37240](https://github.com/moby/moby/pull/37240)
- Fix mis-used skip condition. [moby/moby#37179](https://github.com/moby/moby/pull/37179)
- Fix bind mounts not working in some cases. [moby/moby#37031](https://github.com/moby/moby/pull/37031)
- Fix fd leak on attach. [moby/moby#37184](https://github.com/moby/moby/pull/37184)
- Fix fluentd partial detection. [moby/moby#37029](https://github.com/moby/moby/pull/37029)
- Fix incorrect link in version-history.md. [moby/moby#37049](https://github.com/moby/moby/pull/37049)

* Allow vim to be case insensitive for D in dockerfile. [moby/moby#37235](https://github.com/moby/moby/pull/37235)

- Add `t.Name()` to tests so that service names are unique. [moby/moby#37166](https://github.com/moby/moby/pull/37166)
- Add additional message when backendfs is extfs without d\_type support. [moby/moby#37022](https://github.com/moby/moby/pull/37022)
- Add api version checking for tests from new feature. [moby/moby#37169](https://github.com/moby/moby/pull/37169)
- Add image metrics for push and pull. [moby/moby#37233](https://github.com/moby/moby/pull/37233)
- Add support for `init` on services. [moby/moby#37183](https://github.com/moby/moby/pull/37183)
- Add verification of escapeKeys array length in pkg/term/proxy.go. [moby/moby#36918](https://github.com/moby/moby/pull/36918)

* When link id is empty for overlay2, do not remove this link.. [moby/moby#36161](https://github.com/moby/moby/pull/36161)

- Fix build on OpenBSD by defining Self(). [moby/moby#37301](https://github.com/moby/moby/pull/37301)
- Windows: Fix named pipe support for hyper-v isolated containers. [docker/engine#2](https://github.com/docker/engine/pull/2) [docker/cli#1165](https://github.com/docker/cli/pull/1165)
- Fix manifest lists to always use correct size. [docker/cli#1183](https://github.com/docker/cli/pull/1183)

* Register OCI media types. [docker/engine#4](https://github.com/docker/engine/pull/4)
* Update containerd to v1.1.1 [docker/engine#17](https://github.com/docker/engine/pull/17)
* LCOW: Prefer Windows over Linux in a manifest list. [docker/engine#3](https://github.com/docker/engine/pull/3)
* Add updated `MaskPaths` that are used in code paths directly using containerd to address [CVE-2018-10892](https://cve.mitre.org/cgi-bin/cvename.cgi?name=2018-10892). [docker/engine#15](https://github.com/docker/engine/pull/15)
* Add `/proc/acpi` to masked paths to address [CVE-2018-10892](https://cve.mitre.org/cgi-bin/cvename.cgi?name=2018-10892). [docker/engine#14](https://github.com/docker/engine/pull/14)

- Fix bindmount autocreate race. [docker/engine#11](https://github.com/docker/engine/pull/11)

### [Swarm Mode](#swarm-mode-1)

* List stacks for both Swarm and Kubernetes with --orchestrator=all in docker stack ls. Allow several occurrences of --namespace for Kubernetes with docker stack ls. [docker/cli#1031](https://github.com/docker/cli/pull/1031)
* Bump SwarmKit to remove deprecated grpc metadata wrappers. [moby/moby#36905](https://github.com/moby/moby/pull/36905)
* Issue an error for --orchestrator=all when working on mismatched Swarm and Kubernetes hosts. [docker/cli#1035](https://github.com/docker/cli/pull/1035)

- Fix broken swarm commands with Kubernetes defined as orchestrator. "--orchestrator" flag is no longer global but local to stack commands and subcommands [docker/cli#1137](https://github.com/docker/cli/pull/1137) [docker/cli#1139](https://github.com/docker/cli/pull/1139)

* Bump swarmkit to include task reaper fixes and more metrics. [docker/engine#13](https://github.com/docker/engine/pull/13)

- Avoid a leak when a service with unassigned tasks is deleted. [docker/engine#27](https://github.com/docker/engine/pull/27)
- Fix racy batching on the dispatcher. [docker/engine#27](https://github.com/docker/engine/pull/27)

----
url: https://docs.docker.com/reference/cli/sbx/ports/
----

# sbx ports

| Description | Manage sandbox port publishing |
| ----------- | ------------------------------ |
| Usage       | `sbx ports SANDBOX [flags]`    |

## [Description](#description)

Manage sandbox port publishing.

List, publish, or unpublish ports for a running sandbox. Without --publish or --unpublish flags, lists all published ports.

Port spec format: \[\[HOST\_IP:]HOST\_PORT:]SANDBOX\_PORT\[/PROTOCOL] If HOST\_PORT is omitted, an ephemeral port is allocated automatically. If HOST\_IP is omitted, the port is bound on loopback, expanded based on PROTOCOL and the sandbox's address families: tcp/udp binds both 127.0.0.1 and ::1 (or only 127.0.0.1 if the sandbox is IPv4-only); tcp4/udp4 binds only 127.0.0.1; tcp6/udp6 binds only ::1. PROTOCOL defaults to tcp. Supported protocols: tcp, tcp4, tcp6, udp, udp4, udp6.

## [Options](#options)

| Option        | Default | Description                                                                           |
| ------------- | ------- | ------------------------------------------------------------------------------------- |
| `--json`      |         | Output in JSON format (for port listing)                                              |
| `--publish`   |         | Publish a port (can be repeated): \[\[HOST\_IP:]HOST\_PORT:]SANDBOX\_PORT\[/PROTOCOL] |
| `--unpublish` |         | Unpublish a port (can be repeated): \[HOST\_IP:]HOST\_PORT:SANDBOX\_PORT\[/PROTOCOL]  |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# List published ports
sbx ports my-sandbox

# Publish sandbox port 8080 to an ephemeral host port
sbx ports my-sandbox --publish 8080

# Publish with a specific host port
sbx ports my-sandbox --publish 3000:8080

# Unpublish a port
sbx ports my-sandbox --unpublish 3000:8080
```

----
url: https://docs.docker.com/ai/docker-agent/model-providers/
----

# Model providers

***

Table of contents

***

To run Docker Agent, you need a model provider. You can either use a cloud provider with an API key or run models locally with [Docker Model Runner](https://docs.docker.com/ai/docker-agent/local-models/).

This guide covers cloud providers. For the local alternative, see [Local models with Docker Model Runner](https://docs.docker.com/ai/docker-agent/local-models/).

## [Supported providers](#supported-providers)

Docker Agent supports these cloud model providers:

* Anthropic - Claude models
* OpenAI - GPT models
* Google - Gemini models

## [Anthropic](#anthropic)

Anthropic provides the Claude family of models, including Claude Sonnet and Claude Opus.

To get an API key:

1. Go to [console.anthropic.com](https://console.anthropic.com/).
2. Sign up or sign in to your account.
3. Navigate to the API Keys section.
4. Create a new API key.
5. Copy the key.

Set your API key as an environment variable:

```console
$ export ANTHROPIC_API_KEY=your_key_here
```

Use Anthropic models in your agent configuration:

```yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    instruction: You are a helpful coding assistant
```

Available models include:

* `anthropic/claude-sonnet-4-5`
* `anthropic/claude-opus-4-5`
* `anthropic/claude-haiku-4-5`

## [OpenAI](#openai)

OpenAI provides the GPT family of models, including GPT-5 and GPT-5 mini.

To get an API key:

1. Go to [platform.openai.com/api-keys](https://platform.openai.com/api-keys).
2. Sign up or sign in to your account.
3. Navigate to the API Keys section.
4. Create a new API key.
5. Copy the key.

Set your API key as an environment variable:

```console
$ export OPENAI_API_KEY=your_key_here
```

Use OpenAI models in your agent configuration:

```yaml
agents:
  root:
    model: openai/gpt-5
    instruction: You are a helpful coding assistant
```

Available models include:

* `openai/gpt-5`
* `openai/gpt-5-mini`

## [Google Gemini](#google-gemini)

Google provides the Gemini family of models.

To get an API key:

1. Go to [aistudio.google.com/apikey](https://aistudio.google.com/apikey).
2. Sign in with your Google account.
3. Create an API key.
4. Copy the key.

Set your API key as an environment variable:

```console
$ export GOOGLE_API_KEY=your_key_here
```

Use Gemini models in your agent configuration:

```yaml
agents:
  root:
    model: google/gemini-2.5-flash
    instruction: You are a helpful coding assistant
```

Available models include:

* `google/gemini-2.5-flash`
* `google/gemini-2.5-pro`

## [OpenAI-compatible providers](#openai-compatible-providers)

You can use the `openai` provider type to connect to any model or provider that implements the OpenAI API specification. This includes services like Azure OpenAI, local inference servers, and other compatible endpoints.

Configure an OpenAI-compatible provider by specifying the base URL:

```yaml
agents:
  root:
    model: openai/your-model-name
    instruction: You are a helpful coding assistant
    provider:
      base_url: https://your-provider.example.com/v1
```

By default, Docker Agent uses the `OPENAI_API_KEY` environment variable for authentication. If your provider uses a different variable, specify it with `token_key`:

```yaml
agents:
  root:
    model: openai/your-model-name
    instruction: You are a helpful coding assistant
    provider:
      base_url: https://your-provider.example.com/v1
      token_key: YOUR_PROVIDER_API_KEY
```

## [What's next](#whats-next)

* Follow the [tutorial](https://docs.docker.com/ai/docker-agent/tutorial/) to build your first agent
* Learn about [local models with Docker Model Runner](https://docs.docker.com/ai/docker-agent/local-models/) as an alternative to cloud providers
* Review the [configuration reference](https://docs.docker.com/ai/docker-agent/reference/config/) for advanced model settings

----
url: https://docs.docker.com/build/cache/garbage-collection/
----

# Build garbage collection

***

Table of contents

***

While [`docker builder prune`](/reference/cli/docker/builder/prune/) or [`docker buildx prune`](/reference/cli/docker/buildx/prune/) commands run at once, Garbage Collection (GC) runs periodically and follows an ordered list of prune policies. The BuildKit daemon clears the build cache when the cache size becomes too big, or when the cache age expires.

For most users, the default GC behavior is sufficient and doesn't require any intervention. Advanced users, particularly those working with large-scale builds, self-managed builders, or constrained storage environments, might benefit from customizing these settings to better align with their workflow needs. The following sections explain how GC works and provide guidance on tailoring its behavior through custom configuration.

## [Garbage collection policies](#garbage-collection-policies)

GC policies define a set of rules that determine how the build cache is managed and cleaned up. These policies include criteria for when to remove cache entries, such as the age of the cache, the amount of space being used, and the type of cache records to prune.

Each GC policy is evaluated in sequence, starting with the most specific criteria, and proceeds to broader rules if previous policies do not free up enough cache. This lets BuildKit prioritize cache entries, preserving the most valuable cache while ensuring the system maintains performance and availability.

For example, say you have the following GC policies:

1. Find "stale" cache records that haven't been used in the past 48 hours, and delete records until there's maximum 5GB of "stale" cache left.
2. If the build cache size exceeds 10GB, delete records until the total cache size is no more than 10GB.

The first rule is more specific, prioritizing stale cache records and setting a lower limit for a less valuable type of cache. The second rule imposes a higher hard limit that applies to any type of cache records. With these policies, if you have 11GB worth of build cache, where:

* 7GB of which is "stale" cache
* 4GB is other, more valuable cache

A GC sweep would delete 5GB of stale cache as part of the 1st policy, with a remainder of 6GB, meaning the 2nd policy does not need to clear any more cache.

The default GC policies are (approximately):

1. Remove cache that can be easily regenerated, such as build contexts from local directories or remote Git repositories, and cache mounts, if hasn't been used for more than 48 hours.
2. Remove cache that hasn't been used in a build for more than 60 days.
3. Remove unshared cache that exceeds the build cache size limit. Unshared cache records refers to layer blobs that are not used by other resources (typically, as image layers).
4. Remove any build cache that exceeds the build cache size limit.

The precise algorithm and the means of configuring the policies differ slightly depending on what kind of builder you're using. Refer to [Configuration](#configuration) for more details.

## [Configuration](#configuration)

> Note
>
> If you're satisfied with the default garbage collection behavior and don't need to fine-tune its settings, you can skip this section. Default configurations work well for most use cases and require no additional setup.

Depending on the type of [build driver](https://docs.docker.com/build/builders/drivers/) you use, you will use different configuration files to change the builder's GC settings:

* If you use the default builder for Docker Engine (the `docker` driver), use the [Docker daemon configuration file](#docker-daemon-configuration-file).
* If you use a custom builder, use a [BuildKit configuration file](#buildkit-configuration-file).

### [Docker daemon configuration file](#docker-daemon-configuration-file)

If you're using the default [`docker` driver](https://docs.docker.com/build/builders/drivers/docker/), GC is configured in the [`daemon.json` configuration file](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file), or if you use Docker Desktop, in [**Settings > Docker Engine**](https://docs.docker.com/desktop/settings-and-maintenance/settings/).

The following snippet shows the default builder configuration for the `docker` driver for Docker Desktop users:

```json
{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  }
}
```

The `defaultKeepStorage` option configures the size limit of the build cache, which influences the GC policies. The default policies for the `docker` driver work as follows:

1. Remove ephemeral, unused build cache older than 48 hours if it exceeds 13.8% of `defaultKeepStorage`, or at minimum 512MB.
2. Remove unused build cache older than 60 days.
3. Remove unshared build cache that exceeds the `defaultKeepStorage` limit.
4. Remove any build cache that exceeds the `defaultKeepStorage` limit.

Given the Docker Desktop default value for `defaultKeepStorage` of 20GB, the default GC policies resolve to:

```json
{
  "builder": {
    "gc": {
      "enabled": true,
      "policy": [
        {
          "reservedSpace": "2.764GB",
          "keepDuration": "48h",
          "filter": [
            "type=source.local,type=exec.cachemount,type=source.git.checkout"
          ]
        },
        { "reservedSpace": "20GB", "keepDuration": ["1440h"] },
        { "reservedSpace": "20GB" },
        { "reservedSpace": "20GB", "all": true }
      ]
    }
  }
}
```

The easiest way to tweak the build cache configuration for the `docker` driver is to adjust the `defaultKeepStorage` option:

* Increase the limit if you feel like you think the GC is too aggressive.
* Decrease the limit if you need to preserve space.

#### [Custom GC policies in the Docker daemon configuration file](#custom-gc-policies-in-the-docker-daemon-configuration-file)

If you need even more control, you can define your own GC policies directly. The following example defines a more conservative GC configuration with the following policies:

1. Remove unused cache entries older than 1440 hours, or 60 days, if build cache exceeds 50GB.
2. Remove unshared cache entries if build cache exceeds 50GB.
3. Remove any cache entries if build cache exceeds 100GB.

```json
{
  "builder": {
    "gc": {
      "enabled": true,
      "policy": [
        { "reservedSpace": "50GB", "keepDuration": ["1440h"] },
        { "reservedSpace": "50GB" },
        { "reservedSpace": "100GB", "all": true }
      ]
    }
  }
}
```

> Note
>
> In the Docker daemon configuration file, the "equals" operator in GC filters is denoted using a single `=`, whereas BuildKit's configuration file uses `==`:
>
> | `daemon.json`       | `buildkitd.toml`     |
> | ------------------- | -------------------- |
> | `type=source.local` | `type==source.local` |
> | `private=true`      | `private==true`      |
> | `shared=true`       | `shared==true`       |
>
> See [prune filters](/reference/cli/docker/buildx/prune/#filter) for information about available GC filters. GC configuration in `daemon.json` supports all filters except `mutable` and `immutable`.

### [BuildKit configuration file](#buildkit-configuration-file)

For build drivers other than `docker`, GC is configured using a [`buildkitd.toml`](https://docs.docker.com/build/buildkit/toml-configuration/) configuration file. This file uses the following high-level configuration options that you can use to tweak the thresholds for how much disk space BuildKit should use for cache:

| Option          | Description                                                                                                                                             | Default value                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `reservedSpace` | The minimum amount of disk space BuildKit is allowed to allocate for cache. Usage below this threshold will not be reclaimed during garbage collection. | 10% of total disk space or 10GB (whichever is lower)  |
| `maxUsedSpace`  | The maximum amount of disk space that BuildKit is allowed to use. Usage above this threshold will be reclaimed during garbage collection.               | 60% of total disk space or 100GB (whichever is lower) |
| `minFreeSpace`  | The amount of disk space that must be kept free.                                                                                                        | 20GB                                                  |

You can set these options either as number of bytes, a unit string (for example, `512MB`), or as a percentage of the total disk size. Changing these options influences the default GC policies used by the BuildKit worker. With the default thresholds, the GC policies resolve as follows:

```toml
# Global defaults
[worker.oci]
  gc = true
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"
  minFreeSpace = "20%"

# Policy 1
[[worker.oci.gcpolicy]]
  filters = [ "type==source.local", "type==exec.cachemount", "type==source.git.checkout" ]
  keepDuration = "48h"
  maxUsedSpace = "512MB"

# Policy 2
[[worker.oci.gcpolicy]]
  keepDuration = "1440h" # 60 days
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"

# Policy 3
[[worker.oci.gcpolicy]]
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"

# Policy 4
[[worker.oci.gcpolicy]]
  all = true
  reservedSpace = "10GB"
  maxUsedSpace = "100GB"
```

In practical terms, this means:

* Policy 1: If the build cache exceeds 512MB, BuildKit removes cache records for local build contexts, remote Git contexts, and cache mounts that haven’t been used in the last 48 hours.
* Policy 2: If disk usage exceeds 100GB, unshared build cache older than 60 days is removed, ensuring at least 10GB of disk space is reserved for cache.
* Policy 3: If disk usage exceeds 100GB, any unshared cache is removed, ensuring at least 10GB of disk space is reserved for cache.
* Policy 4: If disk usage exceeds 100GB, all cache—including shared and internal records—is removed, ensuring at least 10GB of disk space is reserved for cache.

`reservedSpace` has the highest priority in defining the lower limit for build cache size. If `maxUsedSpace` or `minFreeSpace` would define a lower value, the minimum cache size would never be brought below `reservedSpace`.

If both `reservedSpace` and `maxUsedSpace` are set, a GC sweep results in a cache size between those thresholds. For example, if `reservedSpace` is set to 10GB, and `maxUsedSpace` is set to 20GB, the resulting amount of cache after a GC run is less than 20GB, but at least 10GB.

You can also define completely custom GC policies. Custom policies also let you define filters, which lets you pinpoint the types of cache entries that a given policy is allowed to prune.

#### [Custom GC policies in BuildKit](#custom-gc-policies-in-buildkit)

Custom GC policies let you fine-tune how BuildKit manages its cache, and gives you full control over cache retention based on criteria such as cache type, duration, or disk space thresholds. If you need full control over the cache thresholds and how cache records should be prioritized, defining custom GC policies is the way to go.

To define a custom GC policy, use the `[[worker.oci.gcpolicy]]` configuration block in `buildkitd.toml`. Each policy define the thresholds that will be used for that policy. The global values for `reservedSpace`, `maxUsedSpace`, and `minFreeSpace` do not apply if you use custom policies.

Here’s an example configuration:

```toml
# Custom GC Policy 1: Remove unused local contexts older than 24 hours
[[worker.oci.gcpolicy]]
  filters = ["type==source.local"]
  keepDuration = "24h"
  reservedSpace = "5GB"
  maxUsedSpace = "50GB"

# Custom GC Policy 2: Remove remote Git contexts older than 30 days
[[worker.oci.gcpolicy]]
  filters = ["type==source.git.checkout"]
  keepDuration = "720h"
  reservedSpace = "5GB"
  maxUsedSpace = "30GB"

# Custom GC Policy 3: Aggressively clean all cache if disk usage exceeds 90GB
[[worker.oci.gcpolicy]]
  all = true
  reservedSpace = "5GB"
  maxUsedSpace = "90GB"
```

In addition to the `reservedSpace`, `maxUsedSpace`, and `minFreeSpace` threshold, when defining a GC policy you have two additional configuration options:

* `all`: By default, BuildKit will exclude some cache records from being pruned during GC. Setting this option to `true` will allow any cache records to be pruned.
* `filters`: Filters let you specify specific types of cache records that a GC policy is allowed to prune.

See [buildx prune filters](/reference/cli/docker/buildx/prune/#filter) for information about available GC filters.

----
url: https://docs.docker.com/desktop/
----

# Docker Desktop

***

Table of contents

***

Docker Desktop is a one-click-install application for your Mac, Linux, or Windows environment that lets you build, share, and run containerized applications and microservices.

It provides a straightforward GUI (Graphical User Interface) that lets you manage your containers, applications, and images directly from your machine.

Docker Desktop reduces the time spent on complex setups so you can focus on writing code. It takes care of port mappings, file system concerns, and other default settings, and is regularly updated with bug fixes and security updates.

Docker Desktop integrates with your preferred development tools and languages, and gives you access to a vast ecosystem of trusted images and templates via Docker Hub. This empowers teams to accelerate development, automate builds, enable CI/CD workflows, and collaborate securely through shared repositories.

## [Key features](#key-features)

* Ability to containerize and share any application on any cloud platform, in multiple languages and frameworks.
* Quick installation and setup of a complete Docker development environment.
* Includes the latest version of Kubernetes.
* On Windows, the ability to toggle between Linux and Windows containers to build applications.
* Fast and reliable performance with native Windows Hyper-V virtualization.
* Ability to work natively on Linux through WSL 2 on Windows machines.
* Volume mounting for code and data, including file change notifications and easy access to running containers on the localhost network.

## [Products inside Docker Desktop](#products-inside-docker-desktop)

* [Docker MCP Toolkit and Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/)
* [Docker Model Runner](https://docs.docker.com/ai/model-runner/)
* [Gordon](https://docs.docker.com/ai/gordon/)
* [Docker Offload](https://docs.docker.com/offload/)
* [Docker Engine](https://docs.docker.com/engine/)
* Docker CLI client
* [Docker Build](https://docs.docker.com/build/)
* [Docker Compose](https://docs.docker.com/compose/)
* [Docker Scout](https://docs.docker.com/scout/)
* [Kubernetes](https://github.com/kubernetes/kubernetes/)

## [Next steps](#next-steps)

### Install Docker Desktop

Install Docker Desktop on [Mac](/desktop/setup/install/mac-install/), [Windows](/desktop/setup/install/windows-install/), or [Linux](/desktop/setup/install/linux/).

### [Learn about Docker Desktop](/desktop/use-desktop/)

[Navigate Docker Desktop.](/desktop/use-desktop/)

### Explore its key features

Find information about [Networking](/desktop/features/networking/), [Docker VMM](/desktop/features/vmm/), [WSL](/desktop/features/wsl/), and more.

### [View the release notes](/desktop/release-notes/)

[Find out about new features, improvements, and bug fixes.](/desktop/release-notes/)

### [Browse common FAQs](/desktop/troubleshoot-and-support/faqs/general/)

[Explore general FAQs or FAQs for specific platforms.](/desktop/troubleshoot-and-support/faqs/general/)

### [Give feedback](/desktop/troubleshoot-and-support/feedback/)

[Provide feedback on Docker Desktop or Docker Desktop features.](/desktop/troubleshoot-and-support/feedback/)

----
url: https://docs.docker.com/compose/how-tos/startup-order/
----

# Control startup and shutdown order in Compose

***

Table of contents

***

You can control the order of service startup and shutdown with the [depends\_on](https://docs.docker.com/reference/compose-file/services/#depends_on) attribute. Compose always starts and stops containers in dependency order, where dependencies are determined by `depends_on`, `links`, `volumes_from`, and `network_mode: "service:..."`.

For example, if your application needs to access a database and both services are started with `docker compose up`, there is a chance this will fail since the application service might start before the database service and won't find a database able to handle its SQL statements.

## [Control startup](#control-startup)

On startup, Compose does not wait until a container is "ready", only until it's running. This can cause issues if, for example, you have a relational database system that needs to start its own services before being able to handle incoming connections.

The solution for detecting the ready state of a service is to use the `condition` attribute with one of the following options:

* `service_started`
* `service_healthy`. This specifies that a dependency is expected to be “healthy”, which is defined with `healthcheck`, before starting a dependent service.
* `service_completed_successfully`. This specifies that a dependency is expected to run to successful completion before starting a dependent service.

## [Example](#example)

```yaml
services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      retries: 5
      start_period: 30s
      timeout: 10s
```

Compose creates services in dependency order. `db` and `redis` are created before `web`.

Compose waits for healthchecks to pass on dependencies marked with `service_healthy`. `db` is expected to be "healthy" (as indicated by `healthcheck`) before `web` is created.

`restart: true` ensures that if `db` is updated or restarted due to an explicit Compose operation, for example `docker compose restart`, the `web` service is also restarted automatically, ensuring it re-establishes connections or dependencies correctly.

The healthcheck for the `db` service uses the `pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}` command to check if the PostgreSQL database is ready. The service is retried every 10 seconds, up to 5 times.

Compose also removes services in dependency order. `web` is removed before `db` and `redis`.

## [Reference information](#reference-information)

* [`depends_on`](https://docs.docker.com/reference/compose-file/services/#depends_on)
* [`healthcheck`](https://docs.docker.com/reference/compose-file/services/#healthcheck)

----
url: https://docs.docker.com/guides/docker-build-cloud/common-questions/
----

# Common challenges and questions

***

Table of contents

***

### [Is Docker Build Cloud a standalone product or a part of Docker Desktop?](#is-docker-build-cloud-a-standalone-product-or-a-part-of-docker-desktop)

Docker Build Cloud is a service that can be used both with Docker Desktop and standalone. It lets you build your container images faster, both locally and in CI, with builds running on cloud infrastructure. The service uses a remote build cache, ensuring fast builds anywhere and for all team members.

When used with Docker Desktop, the [Builds view](/desktop/use-desktop/builds/) works with Docker Build Cloud out-of-the-box. It shows information about your builds and those initiated by your team members using the same builder, enabling collaborative troubleshooting.

To use Docker Build Cloud without Docker Desktop, you must [download and install](/build-cloud/setup/#use-docker-build-cloud-without-docker-desktop) a version of Buildx with support for Docker Build Cloud (the `cloud` driver). If you plan on building with Docker Build Cloud using the `docker compose build` command, you also need a version of Docker Compose that supports Docker Build Cloud.

### [How does Docker Build Cloud work with Docker Compose?](#how-does-docker-build-cloud-work-with-docker-compose)

Docker Compose works out of the box with Docker Build Cloud. Install the Docker Build Cloud-compatible client (buildx) and it works with both commands.

### [How many minutes are included in Docker Build Cloud Team plans?](#how-many-minutes-are-included-in-docker-build-cloud-team-plans)

Pricing details for Docker Build Cloud can be found on the [pricing page](https://www.docker.com/pricing?ref=Docs\&refAction=DocsGuidesBuildCloudFaq).

### [I’m a Docker personal user. Can I try Docker Build Cloud?](#im-a-docker-personal-user-can-i-try-docker-build-cloud)

Docker subscribers (Pro, Team, Business) receive a set number of minutes each month, shared across the account, to use Build Cloud.

If you do not have a Docker subscription, you may sign up for a free Personal account and start a trial of Docker Build Cloud. Personal accounts are limited to a single user.

For teams to receive the shared cache benefit, they must either be on a Docker Team or Docker Business subscription.

### [Does Docker Build Cloud support CI platforms? Does it work with GitHub Actions?](#does-docker-build-cloud-support-ci-platforms-does-it-work-with-github-actions)

Yes, Docker Build Cloud can be used with various CI platforms including GitHub Actions, CircleCI, Jenkins, and others. It can speed up your build pipelines, which means less time spent waiting and context switching.

Docker Build Cloud can be used with GitHub Actions to automate your build, test, and deployment pipeline. Docker provides a set of official GitHub Actions that you can use in your workflows.

Using GitHub Actions with Docker Build Cloud is straightforward. With a one-line change in your GitHub Actions configuration, everything else stays the same. You don't need to create new pipelines. Learn more in the [CI documentation](/build-cloud/ci/) for Docker Build Cloud.

----
url: https://docs.docker.com/reference/cli/docker/desktop/status/
----

# docker desktop status

***

| Description | Display Docker Desktop's status |
| ----------- | ------------------------------- |
| Usage       | `docker desktop status`         |

## [Options](#options)

| Option     | Default  | Description                                          |
| ---------- | -------- | ---------------------------------------------------- |
| `--format` | `pretty` | Format the output. Accepted values are: pretty, json |

----
url: https://docs.docker.com/reference/cli/docker/model/skills/
----

# docker model skills

***

| Description | Install Docker Model Runner skills for AI coding assistants |
| ----------- | ----------------------------------------------------------- |
| Usage       | `docker model skills`                                       |

## [Description](#description)

Install Docker Model Runner skills for AI coding assistants.

Skills are configuration files that help AI coding assistants understand how to use Docker Model Runner effectively for local model inference.

Supported targets: --codex Install to \~/.codex/skills (OpenAI Codex CLI) --claude Install to \~/.claude/skills (Claude Code) --opencode Install to \~/.config/opencode/skills (OpenCode) --dest Install to a custom directory

Example: docker model skills --claude docker model skills --codex --claude docker model skills --dest /path/to/skills

## [Options](#options)

| Option        | Default | Description                                              |
| ------------- | ------- | -------------------------------------------------------- |
| `--claude`    |         | Install skills for Claude Code (\~/.claude/skills)       |
| `--codex`     |         | Install skills for OpenAI Codex CLI (\~/.codex/skills)   |
| `--dest`      |         | Install skills to a custom directory                     |
| `-f, --force` |         | Overwrite existing skills without prompting              |
| `--opencode`  |         | Install skills for OpenCode (\~/.config/opencode/skills) |

----
url: https://docs.docker.com/enterprise/security/provisioning/auto-provisioning/
----

# Auto-provisioning

***

Table of contents

***

Auto-provisioning automatically adds users to your organization when they sign in with email addresses that match your verified domains. You must verify a domain before enabling auto-provisioning.

> Important
>
> For domains that are part of an SSO connection, Just-in-Time (JIT) provisioning takes precedence over auto-provisioning when adding users to an organization.

### [Overview](#overview)

When auto-provisioning is enabled for a verified domain:

* Users who sign in to Docker with matching email addresses are automatically added to your organization.
* Auto-provisioning only adds existing Docker users to your organization, it doesn't create new accounts.
* Users experience no changes to their sign-in process.
* Company and organization owners receive email notifications when new users are added.
* You may need to [manage seats](https://docs.docker.com/subscription/manage-seats/) to accommodate new users.

### [Enable auto-provisioning](#enable-auto-provisioning)

Auto-provisioning is configured per domain. To enable it:

1. Sign in to [Docker Home](https://app.docker.com) and select your company or organization.
2. Select **Admin Console**, then **Domain management**.
3. Select the **Actions menu** next to the domain you want to enable auto-provisioning for.
4. Select **Enable auto-provisioning**.
5. Optional. If enabling auto-provisioning at the company level, select an organization.
6. Select **Enable** to confirm.

The **Auto-provisioning** column will update to **Enabled** for the domain.

### [Disable auto-provisioning](#disable-auto-provisioning)

To disable auto-provisioning for a user:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization. If your organization is part of a company, select the company and configure the domain for the organization at the company level.
2. Select **Admin Console**, then **Domain management**.
3. Select the **Actions menu** next to your domain.
4. Select **Disable auto-provisioning**.
5. Select **Disable** to confirm.

## [Next steps](#next-steps)

To choose a different method to provision users, you can set up:

* [SCIM provisioning](https://docs.docker.com/enterprise/security/provisioning/scim/) for advanced user management.
* [Group mapping](https://docs.docker.com/enterprise/security/provisioning/scim/group-mapping/) to assign users to teams automatically.

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/create/
----

# docker dhi customization create

***

| Description | Create a new customization from YAML file |
| ----------- | ----------------------------------------- |
| Usage       | `docker dhi customization create <file>`  |

## [Description](#description)

Create a new Docker Hardened Images customization using a YAML file as input. The file should contain the complete customization structure without an 'id' field.

Flags can override values from the YAML file (see --help for details). Shell completions are available for --destination and --tag-definition-id flags. Run 'docker dhi completion --help' to set up shell completions.

## [Options](#options)

| Option                    | Default | Description                                                 |
| ------------------------- | ------- | ----------------------------------------------------------- |
| `-d, --destination`       |         | Override the destination repository (e.g. myorg/dhi-golang) |
| `--json`                  |         | Output in JSON format                                       |
| `-n, --name`              |         | Override the customization name from the YAML file          |
| `-t, --tag-definition-id` |         | Override the tag definition ID (single-target only)         |

----
url: https://docs.docker.com/reference/cli/docker/manifest/
----

# docker manifest

***

| Description | Manage Docker image manifests and manifest lists |
| ----------- | ------------------------------------------------ |
| Usage       | `docker manifest COMMAND`                        |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

The `docker manifest` command by itself performs no action. In order to operate on a manifest or manifest list, one of the subcommands must be used.

A single manifest is information about an image, such as layers, size, and digest. The `docker manifest` command also gives you additional information, such as the OS and architecture an image was built for.

A manifest list is a list of image layers that is created by specifying one or more (ideally more than one) image names. It can then be used in the same way as an image name in `docker pull` and `docker run` commands, for example.

Ideally a manifest list is created from images that are identical in function for different os/arch combinations. For this reason, manifest lists are often referred to as "multi-arch images". However, a user could create a manifest list that points to two images -- one for Windows on AMD64, and one for Darwin on AMD64.

### [manifest inspect](#manifest-inspect)

```console
$ docker manifest inspect --help

Usage:  docker manifest inspect [OPTIONS] [MANIFEST_LIST] MANIFEST

Display an image manifest, or manifest list

Options:
      --help       Print usage
      --insecure   Allow communication with an insecure registry
  -v, --verbose    Output additional info including layers and platform
```

### [manifest create](#manifest-create)

```console
Usage:  docker manifest create MANIFEST_LIST MANIFEST [MANIFEST...]

Create a local manifest list for annotating and pushing to a registry

Options:
  -a, --amend      Amend an existing manifest list
      --insecure   Allow communication with an insecure registry
      --help       Print usage
```

### [manifest annotate](#manifest-annotate)

```console
Usage:  docker manifest annotate [OPTIONS] MANIFEST_LIST MANIFEST

Add additional information to a local image manifest

Options:
      --arch string               Set architecture
      --help                      Print usage
      --os string                 Set operating system
      --os-version string         Set operating system version
      --os-features stringSlice   Set operating system feature
      --variant string            Set architecture variant
```

### [manifest push](#manifest-push)

```console
Usage:  docker manifest push [OPTIONS] MANIFEST_LIST

Push a manifest list to a repository

Options:
      --help       Print usage
      --insecure   Allow push to an insecure registry
  -p, --purge      Remove the local manifest list after push
```

### [Working with insecure registries](#working-with-insecure-registries)

The manifest command interacts solely with a registry. Because of this, it has no way to query the engine for the list of allowed insecure registries. To allow the CLI to interact with an insecure registry, some `docker manifest` commands have an `--insecure` flag. For each transaction, such as a `create`, which queries a registry, the `--insecure` flag must be specified. This flag tells the CLI that this registry call may ignore security concerns like missing or self-signed certificates. Likewise, on a `manifest push` to an insecure registry, the `--insecure` flag must be specified. If this is not used with an insecure registry, the manifest command fails to find a registry that meets the default requirements.

## [Examples](#examples)

### [Inspect an image's manifest object](#inspect-an-images-manifest-object)

```console
$ docker manifest inspect hello-world
{
        "schemaVersion": 2,
        "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
        "config": {
                "mediaType": "application/vnd.docker.container.image.v1+json",
                "size": 1520,
                "digest": "sha256:1815c82652c03bfd8644afda26fb184f2ed891d921b20a0703b46768f9755c57"
        },
        "layers": [
                {
                        "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
                        "size": 972,
                        "digest": "sha256:b04784fba78d739b526e27edc02a5a8cd07b1052e9283f5fc155828f4b614c28"
                }
        ]
}
```

### [Inspect an image's manifest and get the os/arch info](#inspect-an-images-manifest-and-get-the-osarch-info)

The `docker manifest inspect` command takes an optional `--verbose` flag that gives you the image's name (Ref), as well as the architecture and OS (Platform).

Just as with other Docker commands that take image names, you can refer to an image with or without a tag, or by digest (e.g. `hello-world@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f`).

Here is an example of inspecting an image's manifest with the `--verbose` flag:

```console
$ docker manifest inspect --verbose hello-world
{
        "Ref": "docker.io/library/hello-world:latest",
        "Digest": "sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f",
        "SchemaV2Manifest": {
                "schemaVersion": 2,
                "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
                "config": {
                        "mediaType": "application/vnd.docker.container.image.v1+json",
                        "size": 1520,
                        "digest": "sha256:1815c82652c03bfd8644afda26fb184f2ed891d921b20a0703b46768f9755c57"
                },
                "layers": [
                        {
                                "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
                                "size": 972,
                                "digest": "sha256:b04784fba78d739b526e27edc02a5a8cd07b1052e9283f5fc155828f4b614c28"
                        }
                ]
        },
        "Platform": {
                "architecture": "amd64",
                "os": "linux"
        }
}
```

### [Create and push a manifest list](#create-and-push-a-manifest-list)

To create a manifest list, you first `create` the manifest list locally by specifying the constituent images you would like to have included in your manifest list. Keep in mind that this is pushed to a registry, so if you want to push to a registry other than the docker registry, you need to create your manifest list with the registry name or IP and port. This is similar to tagging an image and pushing it to a foreign registry.

After you have created your local copy of the manifest list, you may optionally `annotate` it. Annotations allowed are the architecture and operating system (overriding the image's current values), os features, and an architecture variant.

Finally, you need to `push` your manifest list to the desired registry. Below are descriptions of these three commands, and an example putting them all together.

```console
$ docker manifest create 45.55.81.106:5000/coolapp:v1 \
    45.55.81.106:5000/coolapp-ppc64le-linux:v1 \
    45.55.81.106:5000/coolapp-arm-linux:v1 \
    45.55.81.106:5000/coolapp-amd64-linux:v1 \
    45.55.81.106:5000/coolapp-amd64-windows:v1

Created manifest list 45.55.81.106:5000/coolapp:v1
```

```console
$ docker manifest annotate 45.55.81.106:5000/coolapp:v1 45.55.81.106:5000/coolapp-arm-linux --arch arm
```

```console
$ docker manifest push 45.55.81.106:5000/coolapp:v1
Pushed manifest 45.55.81.106:5000/coolapp@sha256:9701edc932223a66e49dd6c894a11db8c2cf4eccd1414f1ec105a623bf16b426 with digest: sha256:f67dcc5fc786f04f0743abfe0ee5dae9bd8caf8efa6c8144f7f2a43889dc513b
Pushed manifest 45.55.81.106:5000/coolapp@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f with digest: sha256:b64ca0b60356a30971f098c92200b1271257f100a55b351e6bbe985638352f3a
Pushed manifest 45.55.81.106:5000/coolapp@sha256:39dc41c658cf25f33681a41310372f02728925a54aac3598310bfb1770615fc9 with digest: sha256:df436846483aff62bad830b730a0d3b77731bcf98ba5e470a8bbb8e9e346e4e8
Pushed manifest 45.55.81.106:5000/coolapp@sha256:f91b1145cd4ac800b28122313ae9e88ac340bb3f1e3a4cd3e59a3648650f3275 with digest: sha256:5bb8e50aa2edd408bdf3ddf61efb7338ff34a07b762992c9432f1c02fc0e5e62
sha256:050b213d49d7673ba35014f21454c573dcbec75254a08f4a7c34f66a47c06aba
```

### [Inspect a manifest list](#inspect-a-manifest-list)

```console
$ docker manifest inspect coolapp:v1
{
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
   "manifests": [
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 424,
         "digest": "sha256:f67dcc5fc786f04f0743abfe0ee5dae9bd8caf8efa6c8144f7f2a43889dc513b",
         "platform": {
            "architecture": "arm",
            "os": "linux"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 424,
         "digest": "sha256:b64ca0b60356a30971f098c92200b1271257f100a55b351e6bbe985638352f3a",
         "platform": {
            "architecture": "amd64",
            "os": "linux"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 425,
         "digest": "sha256:df436846483aff62bad830b730a0d3b77731bcf98ba5e470a8bbb8e9e346e4e8",
         "platform": {
            "architecture": "ppc64le",
            "os": "linux"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 425,
         "digest": "sha256:5bb8e50aa2edd408bdf3ddf61efb7338ff34a07b762992c9432f1c02fc0e5e62",
         "platform": {
            "architecture": "s390x",
            "os": "linux"
         }
      }
   ]
}
```

### [Push to an insecure registry](#push-to-an-insecure-registry)

Here is an example of creating and pushing a manifest list using a known insecure registry.

```console
$ docker manifest create --insecure myprivateregistry.mycompany.com/repo/image:1.0 \
    myprivateregistry.mycompany.com/repo/image-linux-ppc64le:1.0 \
    myprivateregistry.mycompany.com/repo/image-linux-s390x:1.0 \
    myprivateregistry.mycompany.com/repo/image-linux-arm:1.0 \
    myprivateregistry.mycompany.com/repo/image-linux-armhf:1.0 \
    myprivateregistry.mycompany.com/repo/image-windows-amd64:1.0 \
    myprivateregistry.mycompany.com/repo/image-linux-amd64:1.0

$ docker manifest push --insecure myprivateregistry.mycompany.com/repo/image:tag
```

> Note
>
> The `--insecure` flag is not required to annotate a manifest list, since annotations are to a locally-stored copy of a manifest list. You may also skip the `--insecure` flag if you are performing a `docker manifest inspect` on a locally-stored manifest list. Be sure to keep in mind that locally-stored manifest lists are never used by the engine on a `docker pull`.

## [Subcommands](#subcommands)

| Command                                                                                       | Description                                                           |
| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`docker manifest annotate`](https://docs.docker.com/reference/cli/docker/manifest/annotate/) | Add additional information to a local image manifest                  |
| [`docker manifest create`](https://docs.docker.com/reference/cli/docker/manifest/create/)     | Create a local manifest list for annotating and pushing to a registry |
| [`docker manifest inspect`](https://docs.docker.com/reference/cli/docker/manifest/inspect/)   | Display an image manifest, or manifest list                           |
| [`docker manifest push`](https://docs.docker.com/reference/cli/docker/manifest/push/)         | Push a manifest list to a repository                                  |
| [`docker manifest rm`](https://docs.docker.com/reference/cli/docker/manifest/rm/)             | Delete one or more manifest lists from local storage                  |

----
url: https://docs.docker.com/guides/rag-ollama/containerize/
----

# Containerize a RAG application

***

Table of contents

***

## [Overview](#overview)

This section walks you through containerizing a RAG application using Docker.

> Note
>
> You can see more samples of containerized GenAI applications in the [GenAI Stack](https://github.com/docker/genai-stack) demo applications.

## [Get the sample application](#get-the-sample-application)

The sample application used in this guide is an example of RAG application, made by three main components, which are the building blocks for every RAG application. A Large Language Model hosted somewhere, in this case it is hosted in a container and served via [Ollama](https://ollama.ai/). A vector database, [Qdrant](https://qdrant.tech/), to store the embeddings of local data, and a web application, using [Streamlit](https://streamlit.io/) to offer the best user experience to the user.

Clone the sample application. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/mfranzon/winy.git
```

You should now have the following files in your `winy` directory.

```text
├── winy/
│ ├── .gitignore
│ ├── app/
│ │ ├── main.py
│ │ ├── Dockerfile
| | └── requirements.txt
│ ├── tools/
│ │ ├── create_db.py
│ │ ├── create_embeddings.py
│ │ ├── requirements.txt
│ │ ├── test.py
| | └── download_model.sh
│ ├── docker-compose.yaml
│ ├── wine_database.db
│ ├── LICENSE
│ └── README.md
```

## [Containerizing your application: Essentials](#containerizing-your-application-essentials)

Containerizing an application involves packaging it along with its dependencies into a container, which ensures consistency across different environments. Here’s what you need to containerize an app like Winy :

1. Dockerfile: A Dockerfile that contains instructions on how to build a Docker image for your application. It specifies the base image, dependencies, configuration files, and the command to run your application.

2. Docker Compose File: Docker Compose is a tool for defining and running multi-container Docker applications. A Compose file allows you to configure your application's services, networks, and volumes in a single file.

## [Run the application](#run-the-application)

Inside the `winy` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Docker builds and runs your application. Depending on your network connection, it may take several minutes to download all the dependencies. You'll see a message like the following in the terminal when the application is running.

```console
server-1  |   You can now view your Streamlit app in your browser.
server-1  |
server-1  |   URL: http://0.0.0.0:8501
server-1  |
```

Open a browser and view the application at <http://localhost:8501>. You should see a simple Streamlit application.

The application requires a Qdrant database service and an LLM service to work properly. If you have access to services that you ran outside of Docker, specify the connection information in the `docker-compose.yaml`.

```yaml
winy:
  build:
    context: ./app
    dockerfile: Dockerfile
  environment:
    - QDRANT_CLIENT=http://qdrant:6333 # Specifies the url for the qdrant database
    - OLLAMA=http://ollama:11434 # Specifies the url for the ollama service
  container_name: winy
  ports:
    - "8501:8501"
  depends_on:
    - qdrant
    - ollama
```

If you don't have the services running, continue with this guide to learn how you can run some or all of these services with Docker. Remember that the `ollama` service is empty; it doesn't have any model. For this reason you need to pull a model before starting to use the RAG application. All the instructions are in the following page.

In the terminal, press `ctrl`+`c` to stop the application.

## [Summary](#summary)

In this section, you learned how you can containerize and run your RAG application using Docker.

## [Next steps](#next-steps)

In the next section, you'll learn how to properly configure the application with your preferred LLM model, completely locally, using Docker.

[Use containers for RAG development »](https://docs.docker.com/guides/rag-ollama/develop/)

----
url: https://docs.docker.com/engine/network/firewall-nftables/
----

# Docker with nftables

***

Table of contents

***

> Warning
>
> Support for nftables introduced in Docker 29.0.0 is experimental, configuration options, behavior and implementation may all change in future releases. The rules for overlay networks have not yet been migrated from iptables. Therefore, nftables cannot be enabled when the Docker daemon is running in Swarm mode.

To use nftables instead of iptables, use Docker Engine option `--firewall-backend=nftables` on its command line, or `"firewall-backend": "nftables"` in its configuration file. You may also need to modify IP forwarding configuration on the host, and migrate rules from the iptables `DOCKER-USER` chain, see [migrating from iptables to nftables](#migrating-from-iptables-to-nftables).

For bridge networks, Docker creates nftables rules in the host's network namespace. For bridge and other network types, nftables rules for DNS are also created in the container's network namespace.

Creation of nftables rules can be disabled using daemon options `iptables` and `ip6tables`. *These options apply to both iptables and nftables.* See [Prevent Docker from manipulating firewall rules](https://docs.docker.com/engine/network/packet-filtering-firewalls/#prevent-docker-from-manipulating-firewall-rules). However, this is not recommended for most users as it will likely break container networking.

## [Docker's nftables tables](#dockers-nftables-tables)

For bridge networks, Docker creates two tables, `ip docker-bridges` and `ip6 docker-bridges`.

Each table contains a number of [base chains](https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Adding_base_chains), and further chains are added for each bridge network. The moby project has some [internal documentation](https://github.com/moby/moby/blob/master/integration/network/bridge/nftablesdoc/index.md) describing its nftables, and how they depend on network and container configuration. However, the tables and their rules are likely to change between Docker Engine releases.

> Note
>
> Do not modify Docker's tables directly as the modifications are likely to be lost, Docker expects to have full ownership of its tables.

> Note
>
> Because iptables has a fixed set of chains, equivalent to nftables base chains, all rules are included in those chains. The `DOCKER-USER` chain is supplied as a way to insert rules into the `filter` table's `FORWARD` chain, to run before Docker's rules. In Docker's nftables implementation, there is no `DOCKER-USER` chain. Instead, rules can be added in separate tables, with base chains that have the same types and hook points as Docker's base chains. If necessary, [base chain priority](https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_priority) can be used to tell nftables which order to call the chains in. Docker uses well known [priority values](https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks#Priority_within_hook) for each of its base chains.

## [Migrating from iptables to nftables](#migrating-from-iptables-to-nftables)

If the Docker daemon has been running with the iptables firewall backend, restarting it with the nftables backend will delete most of Docker's iptables chains and rules, and create nftables rules instead.

If IP forwarding is not enabled, Docker will report an error when creating a bridge network that needs it. Because of the default bridge, if IPv4 forwarding is disabled, the error will be reported during daemon startup. See [IP forwarding](#ip-forwarding).

If you have rules in the `DOCKER-USER` chain, see [Migrating `DOCKER-USER`](#migrating-docker-user).

You may need to manually update the iptables `FORWARD` policy if it has been set to `DROP` by Docker with iptables, or as part of your host's firewall configuration. See [FORWARD policy in iptables](#forward-policy-in-iptables).

### [IP forwarding](#ip-forwarding)

IP forwarding on the Docker host enables Docker functionality including port publishing, communication between bridge networks, and direct routing from outside the host to containers in bridge networks.

When running with iptables, depending on network and daemon configuration, Docker may enable IPv4 and IPv6 forwarding on the host.

With its nftables firewall backend enabled, Docker will not enable IP forwarding itself. It will report an error if forwarding is needed, but not already enabled. To disable Docker's check for IP forwarding, letting it start and create networks when it determines that forwarding is disabled, use Daemon option `--ip-forward=false`, or `"ip-forward": false` in its configuration file.

> Warning
>
> When enabling IP forwarding, make sure you have firewall rules to block unwanted forwarding between non-Docker interfaces.

> Note
>
> If you stop Docker to migrate to nftables, Docker may have already enabled IP forwarding on your system. After a reboot, if no other service re-enables forwarding, Docker will fail to start.

If Docker is in a VM that has a single network interface and no other software running, there is probably no unwanted forwarding to block. But, on a physical host with multiple network interfaces, forwarding between those interfaces should probably be blocked with nftables rules unless the host is acting as a router.

To enable IP forwarding on the host, set the following sysctls:

* `net.ipv4.ip_forward=1`
* `net.ipv6.conf.all.forwarding=1`

If your host uses `systemd`, you may be able to use `systemd-sysctl`. For example, by editing `/etc/sysctl.d/99-sysctl.conf`.

If the host is running `firewalld`, you may be able to use it to block unwanted forwarding. Docker's bridges are in a firewalld zone called `docker`, it creates a forwarding policy called `docker-forwarding` that accepts forwarding from `ANY` zone to the `docker` zone.

For example, to use nftables to block forwarding between interfaces `eth0` and `eth1`, you could use:

```console
table inet no-ext-forwarding {
	chain no-ext-forwarding {
		type filter hook forward priority filter; policy accept;
		iifname "eth0" oifname "eth1" drop
		iifname "eth1" oifname "eth0" drop
	}
}
```

### [FORWARD policy in iptables](#forward-policy-in-iptables)

An iptables chain with `FORWARD` policy `DROP` will drop packets that have been accepted by Docker's nftables rules, because the packet will be processed by the iptables chains as well as Docker's nftables chains.

Some features, including port publishing, will not work unless the `DROP` policy is removed, or additional iptables rules are added to the iptables `FORWARD` chain to accept Docker-related traffic.

When Docker is using iptables, and it enables IP forwarding on the host, it sets the default policy of the iptables `FORWARD` chain to `DROP`. So, if you stop Docker to migrate to nftables, it may have set a `DROP` that you need to remove. It will be removed anyway on reboot.

To keep using rules in `DOCKER-USER` that rely on the chain having policy `DROP`, you must add explicit `ACCEPT` rules for Docker related traffic.

To check the current iptables `FORWARD` policy, use:

```console
$ iptables -L FORWARD
Chain FORWARD (policy DROP)
target     prot opt source               destination
$ ip6tables -L FORWARD
Chain FORWARD (policy ACCEPT)
target     prot opt source               destination
```

To set the iptables policies to `ACCEPT` for IPv4 and IPv6:

```console
$ iptables -P FORWARD ACCEPT
$ ip6tables -P FORWARD ACCEPT
```

### [Migrating `DOCKER-USER`](#migrating-docker-user)

With firewall backend "iptables", rules added to the iptables `DOCKER-USER` are processed before Docker's rules in the filter table's `FORWARD` chain.

When starting the daemon with nftables after running with iptables, Docker will not remove the jump from the `FORWARD` chain to `DOCKER-USER`. So, rules created in `DOCKER-USER` will continue to run until the jump is removed or the host is rebooted.

When starting with nftables, the daemon will not add the jump. So, unless there is an existing jump, rules in `DOCKER-USER` will be ignored.

#### [Migrating ACCEPT rules](#migrating-accept-rules)

Some rules in the `DOCKER-USER` chain will continue to work. For example, if a packet is dropped, it will be dropped before or after the nftables rules in Docker's `filter-FORWARD` chain. But other rules, particularly `ACCEPT` rules to override Docker's `DROP` rules, will not work.

In nftables, an "accept" rule is not final. It terminates processing for its base chain, but the accepted packet will still be processed by other base chains, which may drop it.

To override Docker's `drop` rule, you must use a firewall mark. Select a mark not already in use on your host, and use Docker Engine option `--bridge-accept-fwmark`.

For example, `--bridge-accept-fwmark=1` tells the daemon to accept any packet with an `fwmark` value of `1`. Optionally, you can supply a mask to match specific bits in the mark, `--bridge-accept-fwmark=0x1/0x3`.

Then, instead of accepting the packet in `DOCKER-USER`, add the firewall mark you have chosen and Docker will not drop it.

The firewall mark must be added before Docker's rules run. So if the mark is added in a chain with type `filter` and hook `forward`, it must have priority `filter - 1` or lower.

#### [Replacing `DOCKER-USER` with an nftables table](#replacing-docker-user-with-an-nftables-table)

Because nftables doesn't have pre-defined chains, to replace the `DOCKER-USER` chain you can create your own table and add chains and rules to it.

The `DOCKER-USER` chain has type `filter` and hook `forward`, so it can only have rules in the filter forward chain. The base chains in your table can have any `type` or `hook`. If your rules need to run before Docker's rules, give the base chains a lower `priority` number than Docker's chain. Or, a higher priority to make sure they run after Docker's rules.

Docker's base chains use the priority values defined at [priority values](https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks#Priority_within_hook)

#### [Example: restricting external connections to containers](#example-restricting-external-connections-to-containers)

By default, any remote host can connect to ports published to the Docker host's external addresses.

To allow only a specific IP or network to access the containers, create a table with a base chain that has a drop rule. For example, the following table drops packets from all IP addresses except `192.0.2.2`:

```console
table ip my-table {
	chain my-filter-forward {
		type filter hook forward priority filter; policy accept;
		iifname "ext_if" ip saddr != 192.0.2.2 counter drop
	}
}
```

You will need to change `ext_if` to your host's external interface name.

You could instead accept connections from a source subnet. The following table only accepts access from the subnet `192.0.2.0/24`:

```console
table ip my-table {
	chain my-filter-forward {
		type filter hook forward priority filter; policy accept;
		iifname "ext_if" ip saddr != 192.0.2.0/24 counter drop
	}
}
```

If you are running other services on the host that use IP forwarding and need to be accessed by different external hosts, you will need more specific filters. For example, to match the default prefix `br-` of bridge devices belonging to Docker's user-defined bridge networks:

```console
table ip my-table {
	chain my-filter-forward {
		type filter hook forward priority filter; policy accept;
		iifname "ext_if" oifname "br-*" ip saddr != 192.0.2.0/24 counter drop
	}
}
```

For more information about nftables configuration and advanced usage, refer to the [nftables wiki](https://wiki.nftables.org/wiki-nftables/index.php/Main_Page).

----
url: https://docs.docker.com/guides/rust/develop/
----

# Develop your Rust application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have completed the walkthroughs in the Docker Desktop [Learning Center](https://docs.docker.com/desktop/use-desktop/) to learn about Docker concepts.
* You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client.

## [Overview](#overview)

In this section, you’ll learn how to use volumes and networking in Docker. You’ll also use Docker to build your images and Docker Compose to make everything a whole lot easier.

First, you’ll take a look at running a database in a container and how you can use volumes and networking to persist your data and let your application talk with the database. Then you’ll pull everything together into a Compose file which lets you set up and run a local development environment with one command.

## [Run a database in a container](#run-a-database-in-a-container)

Instead of downloading PostgreSQL, installing, configuring, and then running the PostgreSQL database as a service, you can use the Docker Official Image for PostgreSQL and run it in a container.

Before you run PostgreSQL in a container, create a volume that Docker can manage to store your persistent data and configuration. Use the named volumes feature that Docker provides instead of using bind mounts.

Run the following command to create your volume.

```console
$ docker volume create db-data
```

Now create a network that your application and database will use to talk to each other. The network is called a user-defined bridge network and gives you a nice DNS lookup service which you can use when creating your connection string.

```console
$ docker network create postgresnet
```

Now you can run PostgreSQL in a container and attach to the volume and network that you created previously. Docker pulls the image from Hub and runs it for you locally. In the following command, option `--mount` is for starting the container with a volume. For more information, see [Docker volumes](https://docs.docker.com/engine/storage/volumes/).

```console
$ docker run --rm -d --mount \
  "type=volume,src=db-data,target=/var/lib/postgresql" \
  -p 5432:5432 \
  --network postgresnet \
  --name db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=example \
  postgres:18
```

Now, make sure that your PostgreSQL database is running and that you can connect to it. Connect to the running PostgreSQL database inside the container.

```console
$ docker exec -it db psql -U postgres
```

You should see output like the following.

```console
psql (15.3 (Debian 15.3-1.pgdg110+1))
Type "help" for help.

postgres=#
```

In the previous command, you logged in to the PostgreSQL database by passing the `psql` command to the `db` container. Press ctrl-d to exit the PostgreSQL interactive terminal.

## [Get and run the sample application](#get-and-run-the-sample-application)

For the sample application, you'll use a variation of the backend from the react-rust-postgres application from [Awesome Compose](https://github.com/docker/awesome-compose/tree/master/react-rust-postgres).

1. Clone the sample application repository using the following command.

   ```console
   $ git clone https://github.com/docker/docker-rust-postgres
   ```

2. In the cloned repository's directory, create a `Dockerfile`. This application includes a `migrations` directory (in addition to `src`) to initialize the database, so the Dockerfile includes a bind mount for that directory in the build stage.

   ```dockerfile
   # syntax=docker/dockerfile:1

   # Comments are provided throughout this file to help you get started.
   # If you need more help, visit the Dockerfile reference guide at
   # https://docs.docker.com/reference/dockerfile/

   ################################################################################
   # Create a stage for building the application.

   ARG RUST_VERSION=1.70.0
   ARG APP_NAME=react-rust-postgres
   FROM rust:${RUST_VERSION}-slim-bullseye AS build
   ARG APP_NAME
   WORKDIR /app

   # Build the application.
   # Leverage a cache mount to /usr/local/cargo/registry/
   # for downloaded dependencies and a cache mount to /app/target/ for
   # compiled dependencies which will speed up subsequent builds.
   # Leverage a bind mount to the src directory to avoid having to copy the
   # source code into the container. Once built, copy the executable to an
   # output directory before the cache mounted /app/target is unmounted.
   RUN --mount=type=bind,source=src,target=src \
       --mount=type=bind,source=Cargo.toml,target=Cargo.toml \
       --mount=type=bind,source=Cargo.lock,target=Cargo.lock \
       --mount=type=cache,target=/app/target/ \
       --mount=type=cache,target=/usr/local/cargo/registry/ \
       --mount=type=bind,source=migrations,target=migrations \
       <<EOF
   set -e
   cargo build --locked --release
   cp ./target/release/$APP_NAME /bin/server
   EOF

   ################################################################################
   # Create a new stage for running the application that contains the minimal
   # runtime dependencies for the application. This often uses a different base
   # image from the build stage where the necessary files are copied from the build
   # stage.
   #
   # The example below uses the debian bullseye image as the foundation for    running the app.
   # By specifying the "bullseye-slim" tag, it will also use whatever happens to    be the
   # most recent version of that tag when you build your Dockerfile. If
   # reproducibility is important, consider using a digest
   # (e.g.,    debian@sha256:ac707220fbd7b67fc19b112cee8170b41a9e97f703f588b2cdbbcdcecdd8af57).
   FROM debian:bullseye-slim AS final

   # Create a non-privileged user that the app will run under.
   # See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/   #user
   ARG UID=10001
   RUN adduser \
       --disabled-password \
       --gecos "" \
       --home "/nonexistent" \
       --shell "/sbin/nologin" \
       --no-create-home \
       --uid "${UID}" \
       appuser
   USER appuser

   # Copy the executable from the "build" stage.
   COPY --from=build /bin/server /bin/

   # Expose the port that the application listens on.
   EXPOSE 8000

   # What the container should run when it is started.
   CMD ["/bin/server"]
   ```

3. In the cloned repository's directory, run `docker build` to build the image.

   ```console
   $ docker build -t rust-backend-image .
   ```

4. Run `docker run` with the following options to run the image as a container on the same network as the database.

   ```console
   $ docker run \
     --rm -d \
     --network postgresnet \
     --name docker-develop-rust-container \
     -p 3001:8000 \
     -e PG_DBNAME=example \
     -e PG_HOST=db \
     -e PG_USER=postgres \
     -e PG_PASSWORD=mysecretpassword \
     -e ADDRESS=0.0.0.0:8000 \
     -e RUST_LOG=debug \
     rust-backend-image
   ```

5. Curl the application to verify that it connects to the database.

   ```console
   $ curl http://localhost:3001/users
   ```

   You should get a response like the following.

   ```json
   [{ "id": 1, "login": "root" }]
   ```

## [Use Compose to develop locally](#use-compose-to-develop-locally)

In the cloned repository's directory, create a `compose.yaml` file. Using Compose, you don't have to type all the parameters to pass to the `docker run` command — you can declare them in the file instead.

You need to update the following items in the `compose.yaml` file:

* Uncomment all of the database instructions.
* Add the environment variables under the server service.

The following is the updated `compose.yaml` file.

```yaml
# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Docker compose reference guide at
# https://docs.docker.com/reference/compose-file/

# Here the instructions define your application as a service called "server".
# This service is built from the Dockerfile in the current directory.
# You can add other services your application may depend on here, such as a
# database or a cache. For examples, see the Awesome Compose repository:
# https://github.com/docker/awesome-compose
services:
  server:
    build:
      context: .
      target: final
    ports:
      - 8000:8000
    environment:
      - PG_DBNAME=example
      - PG_HOST=db
      - PG_USER=postgres
      - PG_PASSWORD=mysecretpassword
      - ADDRESS=0.0.0.0:8000
      - RUST_LOG=debug
    # The commented out section below is an example of how to define a PostgreSQL
    # database that your application can use. `depends_on` tells Docker Compose to
    # start the database before your application. The `db-data` volume persists the
    # database data between container restarts. The `db-password` secret is used
    # to set the database password. You must create `db/password.txt` and add
    # a password of your choosing to it before running `docker compose up`.
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:18
    restart: always
    user: postgres
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=example
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    expose:
      - 5432
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
```

Note that the file doesn't specify a network for those 2 services. When you use Compose, it automatically creates a network and connects the services to it. For more information see [Networking in Compose](https://docs.docker.com/compose/how-tos/networking/).

Before you run the application using Compose, notice that this Compose file specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository.

In the cloned repository's directory, create a new directory named `db` and inside that directory create a file named `password.txt` that contains the password for the database. Using your favorite IDE or text editor, add the following contents to the `password.txt` file.

```text
mysecretpassword
```

If you have any other containers running from the previous sections, [stop](https://docs.docker.com/guides/rust/run-containers/#stop-start-and-name-containers) them now.

Now, run the following `docker compose up` command to start your application.

```console
$ docker compose up --build
```

The command passes the `--build` flag so Docker will compile your image and then start the containers.

Now test your API endpoint. Open a new terminal then make a request to the server using the curl commands:

```console
$ curl http://localhost:8000/users
```

You should receive the following response:

```json
[{ "id": 1, "login": "root" }]
```

## [Summary](#summary)

In this section, you took a look at setting up your Compose file to run your Rust application and database with a single command.

Related information:

* [Docker volumes](https://docs.docker.com/engine/storage/volumes/)
* [Compose overview](https://docs.docker.com/compose/)

## [Next steps](#next-steps)

In the next section, you'll take a look at how to set up a CI/CD pipeline using GitHub Actions.

[Configure CI/CD for your Rust application »](https://docs.docker.com/guides/rust/configure-ci-cd/)

----
url: https://docs.docker.com/reference/cli/docker/node/rm/
----

# docker node rm

***

| Description                                                               | Remove one or more nodes from the swarm   |
| ------------------------------------------------------------------------- | ----------------------------------------- |
| Usage                                                                     | `docker node rm [OPTIONS] NODE [NODE...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker node remove`                      |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Removes the specified nodes from a swarm.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                  | Default | Description                        |
| ----------------------- | ------- | ---------------------------------- |
| [`-f, --force`](#force) |         | Force remove a node from the swarm |

## [Examples](#examples)

### [Remove a stopped node from the swarm](#remove-a-stopped-node-from-the-swarm)

```console
$ docker node rm swarm-node-02

Node swarm-node-02 removed from swarm
```

### [Attempt to remove a running node from a swarm](#attempt-to-remove-a-running-node-from-a-swarm)

Removes the specified nodes from the swarm, but only if the nodes are in the down state. If you attempt to remove an active node you will receive an error:

```console
$ docker node rm swarm-node-03

Error response from daemon: rpc error: code = 9 desc = node swarm-node-03 is not
down and can't be removed
```

### [Forcibly remove an inaccessible node from a swarm (--force)](#force)

If you lose access to a worker node or need to shut it down because it has been compromised or is not behaving as expected, you can use the `--force` option. This may cause transient errors or interruptions, depending on the type of task being run on the node.

```console
$ docker node rm --force swarm-node-03

Node swarm-node-03 removed from swarm
```

A manager node must be demoted to a worker node (using `docker node demote`) before you can remove it from the swarm.

----
url: https://docs.docker.com/desktop/features/containerd/
----

# containerd image store

***

Table of contents

***

Docker Desktop uses containerd as its image store by default. The image store is the component responsible for pushing, pulling, and storing images on your filesystem. The containerd image store supports features like multi-platform images, image attestations, and alternative snapshotters.

## [What is `containerd`?](#what-is-containerd)

`containerd` is a container runtime that provides a lightweight, consistent interface for container lifecycle and image management. It is used under the hood by Docker Engine for creating, starting, and stopping containers.

## [What is the `containerd` image store?](#what-is-the-containerd-image-store)

The image store is the component responsible for pushing, pulling, and storing images on the filesystem.

The containerd image store extends the range of image types that the Docker Engine can natively interact with. While this is a low-level architectural change, it's a prerequisite for unlocking a range of new use cases, including:

* [Build multi-platform images](#build-multi-platform-images) and images with attestations
* Support for using containerd snapshotters with unique characteristics, such as [stargz](https://github.com/containerd/stargz-snapshotter) for lazy-pulling images on container startup, or [nydus](https://github.com/containerd/nydus-snapshotter) and [dragonfly](https://github.com/dragonflyoss/image-service) for peer-to-peer image distribution.
* Ability to run [Wasm](https://docs.docker.com/desktop/features/wasm/) containers

## [Classic image store](#classic-image-store)

The classic image store is Docker's legacy storage backend, replaced by the containerd image store. It doesn't support image indices or manifest lists, so you can't load multi-platform images locally or build images with attestations.

Most users have no reason to use the classic image store. It's available for cases where you need to match older behavior or have compatibility requirements.

## [Switch image stores](#switch-image-stores)

The containerd image store is enabled by default in Docker Desktop version 4.34 and later. To switch between image stores:

1. Navigate to **Settings** in Docker Desktop.
2. In the **General** tab, check or clear the **Use containerd for pulling and storing images** option.
3. Select **Apply**.

> Note
>
> Docker Desktop maintains separate image stores for the classic and containerd image stores. When switching between them, images and containers from the inactive store remain on disk but are hidden until you switch back.

## [Build multi-platform images](#build-multi-platform-images)

The containerd image store lets you build multi-platform images and load them to your local image store:

Building multi-platform images with the classic image store is not supported:

```console
$ docker build --platform=linux/amd64,linux/arm64 .
[+] Building 0.0s (0/0)
ERROR: Multi-platform build is not supported for the docker driver.
Switch to a different driver, or turn on the containerd image store, and try again.
Learn more at https://docs.docker.com/go/build-multi-platform/
```

----
url: https://docs.docker.com/desktop/uninstall/
----

# Uninstall Docker Desktop

***

***

> Warning
>
> Uninstalling Docker Desktop destroys Docker containers, images, volumes, and other Docker-related data local to the machine, and removes the files generated by the application. To preserve important data before uninstalling, refer to the [back up and restore data](https://docs.docker.com/desktop/settings-and-maintenance/backup-and-restore/) section.

#### [From the GUI](#from-the-gui)

1. From the Windows **Start** menu, select **Settings** > **Apps** > **Apps & features**.
2. Select **Docker Desktop** from the **Apps & features** list and then select **Uninstall**.
3. Select **Uninstall** to confirm your selection.

#### [From the CLI](#from-the-cli)

1. Locate the installer:
   ```console
   # all-user installation
   $ C:\Program Files\Docker\Docker\Docker Desktop Installer.exe

   # per-user installation (Beta)
   $ %LOCALAPPDATA%\Programs\DockerDesktop\Docker Desktop Installer.exe
   ```
2. Uninstall Docker Desktop.

* In PowerShell, run:
  ```console
  $ Start-Process 'Docker Desktop Installer.exe' -Wait uninstall
  ```
* In the Command Prompt, run:
  ```console
  $ start /w "" "Docker Desktop Installer.exe" uninstall
  ```

After uninstalling Docker Desktop, some residual files may remain which you can remove manually. These are:

```console
C:\ProgramData\Docker
C:\ProgramData\DockerDesktop
C:\Program Files\Docker
C:\Users\<your user name>\AppData\Local\Docker
C:\Users\<your user name>\AppData\Roaming\Docker
C:\Users\<your user name>\AppData\Roaming\Docker Desktop
C:\Users\<your user name>\.docker
```

#### [From the GUI](#from-the-gui)

1. Open Docker Desktop.
2. In the top-right corner of the Docker Desktop Dashboard, select the **Troubleshoot** icon.
3. Select **Uninstall**.
4. When prompted, confirm by selecting **Uninstall** again.

You can then move the Docker application to the trash.

#### [From the CLI](#from-the-cli)

Run:

```console
$ /Applications/Docker.app/Contents/MacOS/uninstall
```

You can then move the Docker application to the trash.

> Note
>
> You may encounter the following error when uninstalling Docker Desktop using the uninstall command.
>
> ```console
> $ /Applications/Docker.app/Contents/MacOS/uninstall
> Password:
> Uninstalling Docker Desktop...
> Error: unlinkat /Users/USER_HOME/Library/Containers/com.docker.docker/.com.apple.containermanagerd.metadata.plist: > operation not permitted
> ```
>
> The operation not permitted error is reported either on the file `.com.apple.containermanagerd.metadata.plist` or on the parent directory `/Users/<USER_HOME>/Library/Containers/com.docker.docker/`. This error can be ignored as you have successfully uninstalled Docker Desktop. You can remove the directory `/Users/<USER_HOME>/Library/Containers/com.docker.docker/` later by allowing **Full Disk Access** to the terminal application you are using (**System Settings** > **Privacy & Security** > **Full Disk Access**).

After uninstalling Docker Desktop, some residual files may remain which you can remove:

```console
$ rm -rf ~/Library/Group\ Containers/group.com.docker
$ rm -rf ~/.docker
```

To uninstall Docker Desktop for Ubuntu:

1. Remove the Docker Desktop application. Run:

   ```console
   $ sudo apt remove docker-desktop
   ```

   This removes the Docker Desktop package itself but doesn’t delete all of its files or settings.

2. Manually remove leftover file.

   ```console
   $ rm -r $HOME/.docker/desktop
   $ sudo rm /usr/local/bin/com.docker.cli
   $ sudo apt purge docker-desktop
   ```

   This removes configuration and data files at `$HOME/.docker/desktop`, the symlink at `/usr/local/bin/com.docker.cli`, and purges the remaining systemd service files.

3. Clean up Docker config settings. In `$HOME/.docker/config.json`, remove the `credsStore` and `currentContext` properties.

   These entries tell Docker where to store credentials and which context is active. If they remain after uninstalling Docker Desktop, they may conflict with a future Docker setup.

To uninstall Docker Desktop for Debian, run:

1. Remove the Docker Desktop application:

   ```console
   $ sudo apt remove docker-desktop
   ```

   This removes the Docker Desktop package itself but doesn’t delete all of its files or settings.

2. Manually remove leftover file.

   ```console
   $ rm -r $HOME/.docker/desktop
   $ sudo rm /usr/local/bin/com.docker.cli
   $ sudo apt purge docker-desktop
   ```

   This removes configuration and data files at `$HOME/.docker/desktop`, the symlink at `/usr/local/bin/com.docker.cli`, and purges the remaining systemd service files.

3. Clean up Docker config settings. In `$HOME/.docker/config.json`, remove the `credsStore` and `currentContext` properties.

   These entries tell Docker where to store credentials and which context is active. If they remain after uninstalling Docker Desktop, they may conflict with a future Docker setup.

To uninstall Docker Desktop for Fedora:

1. Remove the Docker Desktop application. Run:

   ```console
   $ sudo dnf remove docker-desktop
   ```

   This removes the Docker Desktop package itself but doesn’t delete all of its files or settings.

2. Manually remove leftover file.

   ```console
   $ rm -r $HOME/.docker/desktop
   $ sudo rm /usr/local/bin/com.docker.cli
   $ sudo dnf remove docker-desktop
   ```

   This removes configuration and data files at `$HOME/.docker/desktop`, the symlink at `/usr/local/bin/com.docker.cli`, and purges the remaining systemd service files.

3. Clean up Docker config settings. In `$HOME/.docker/config.json`, remove the `credsStore` and `currentContext` properties.

   These entries tell Docker where to store credentials and which context is active. If they remain after uninstalling Docker Desktop, they may conflict with a future Docker setup.

To uninstall Docker Desktop for Arch:

1. Remove the Docker Desktop application. Run:

   ```console
   $ sudo pacman -Rns docker-desktop
   ```

   This removes the Docker Desktop package along with its configuration files and dependencies not required by other packages.

2. Manually remove leftover files.

   ```console
   $ rm -r $HOME/.docker/desktop
   ```

   This removes configuration and data files at `$HOME/.docker/desktop`.

3. Clean up Docker config settings. In `$HOME/.docker/config.json`, remove the `credsStore` and `currentContext` properties.

   These entries tell Docker where to store credentials and which context is active. If they remain after uninstalling Docker Desktop, they may conflict with a future Docker setup.

----
url: https://docs.docker.com/reference/api/engine/version/v1.53/
----

# Docker Engine API v1.53 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.53.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.53.yaml)

# Docker Engine API (1.53)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.53.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.53/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.53/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.53/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf",
"Created": "2025-02-17T17:43:39.64001363Z",
"Path": "/bin/sh",
"Args": [
"-c",
"exit 9"
],
"State": {
"Status": "running",
"Running": true,
"Paused": false,
"Restarting": false,
"OOMKilled": false,
"Dead": false,
"Pid": 1234,
"ExitCode": 0,
"Error": "string",
"StartedAt": "2020-01-06T09:06:59.461876391Z",
"FinishedAt": "2020-01-06T09:07:59.461876391Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2020-01-04T10:44:24.496525531Z",
"End": "2020-01-04T10:45:21.364524523Z",
"ExitCode": 0,
"Output": "string"
}
]
}
},
"Image": "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782",
"ResolvConfPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/resolv.conf",
"HostnamePath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hostname",
"HostsPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hosts",
"LogPath": "/var/lib/docker/containers/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59-json.log",
"Name": "/funny_chatelet",
"RestartCount": 0,
"Driver": "overlayfs",
"Platform": "linux",
"ImageManifestDescriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"MountLabel": "",
"ProcessLabel": "",
"AppArmorProfile": "",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"CpuShares": 0,
"Memory": 0,
"CgroupParent": "string",
"BlkioWeight": 1000,
"BlkioWeightDevice": [
{
"Path": "string",
"Weight": 0
}
],
"BlkioDeviceReadBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceReadIOps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteIOps": [
{
"Path": "string",
"Rate": 0
}
],
"CpuPeriod": 0,
"CpuQuota": 0,
"CpuRealtimePeriod": 0,
"CpuRealtimeRuntime": 0,
"CpusetCpus": "0-3",
"CpusetMems": "string",
"Devices": [
{
"PathOnHost": "/dev/deviceName",
"PathInContainer": "/dev/deviceName",
"CgroupPermissions": "mrw"
}
],
"DeviceCgroupRules": [
"c 13:* rwm"
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 100,
"NanoCpus": 0,
"OomKillDisable": true,
"Init": true,
"PidsLimit": 0,
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
],
"CpuCount": 0,
"CpuPercent": 0,
"IOMaximumIOps": 0,
"IOMaximumBandwidth": 0,
"Binds": [
"string"
],
"ContainerIDFile": "",
"LogConfig": {
"Type": "local",
"Config": {
"max-file": "5",
"max-size": "10m"
}
},
"NetworkMode": "string",
"PortBindings": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"VolumeDriver": "string",
"VolumesFrom": [
"string"
],
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"ConsoleSize": [
80,
64
],
"Annotations": {
"property1": "string",
"property2": "string"
},
"CapAdd": [
"string"
],
"CapDrop": [
"string"
],
"CgroupnsMode": "private",
"Dns": [
"string"
],
"DnsOptions": [
"string"
],
"DnsSearch": [
"string"
],
"ExtraHosts": [
"string"
],
"GroupAdd": [
"string"
],
"IpcMode": "string",
"Cgroup": "string",
"Links": [
"string"
],
"OomScoreAdj": 500,
"PidMode": "string",
"Privileged": true,
"PublishAllPorts": true,
"ReadonlyRootfs": true,
"SecurityOpt": [
"string"
],
"StorageOpt": {
"property1": "string",
"property2": "string"
},
"Tmpfs": {
"property1": "string",
"property2": "string"
},
"UTSMode": "string",
"UsernsMode": "string",
"ShmSize": 0,
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Runtime": "string",
"Isolation": "default",
"MaskedPaths": [
"/proc/asound",
"/proc/acpi",
"/proc/kcore",
"/proc/keys",
"/proc/latency_stats",
"/proc/timer_list",
"/proc/timer_stats",
"/proc/sched_debug",
"/proc/scsi",
"/sys/firmware",
"/sys/devices/virtual/powercap"
],
"ReadonlyPaths": [
"/proc/bus",
"/proc/fs",
"/proc/irq",
"/proc/sys",
"/proc/sysrq-trigger"
]
},
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"Storage": {
"RootFS": {
"Snapshot": {
"Name": "string"
}
}
},
"SizeRw": "122880",
"SizeRootFs": "1653948416",
"Mounts": [
{
"Type": "volume",
"Name": "myvolume",
"Source": "/var/lib/docker/volumes/myvolume/_data",
"Destination": "/usr/share/nginx/html/",
"Driver": "local",
"Mode": "z",
"RW": true,
"Propagation": ""
}
],
"Config": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"NetworkSettings": {
"SandboxID": "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3",
"SandboxKey": "/var/run/docker/netns/8ab54b426c38",
"Ports": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"Networks": {
"property1": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
},
"property2": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
}
}
}
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.53/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": {
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
]
},
"Processes": {
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.53/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.53/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.53/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.53/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"name": "boring_wozniak",
"os_type": "linux",
"read": "2025-01-16T13:55:22.165243637Z",
"cpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"memory_stats": {
"usage": 0,
"max_usage": 0,
"stats": {
"active_anon": 1572864,
"active_file": 5115904,
"anon": 1572864,
"anon_thp": 0,
"file": 7626752,
"file_dirty": 0,
"file_mapped": 2723840,
"file_writeback": 0,
"inactive_anon": 0,
"inactive_file": 2510848,
"kernel_stack": 16384,
"pgactivate": 0,
"pgdeactivate": 0,
"pgfault": 2042,
"pglazyfree": 0,
"pglazyfreed": 0,
"pgmajfault": 45,
"pgrefill": 0,
"pgscan": 0,
"pgsteal": 0,
"shmem": 0,
"slab": 1180928,
"slab_reclaimable": 725576,
"slab_unreclaimable": 455352,
"sock": 0,
"thp_collapse_alloc": 0,
"thp_fault_alloc": 1,
"unevictable": 0,
"workingset_activate": 0,
"workingset_nodereclaim": 0,
"workingset_refault": 0
},
"failcnt": 0,
"limit": 8217579520,
"commitbytes": 0,
"commitpeakbytes": 0,
"privateworkingset": 0
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"pids_stats": {
"current": 5,
"limit": "18446744073709551615"
},
"blkio_stats": {
"io_service_bytes_recursive": [
{
"major": 254,
"minor": 0,
"op": "read",
"value": 7593984
},
{
"major": 254,
"minor": 0,
"op": "write",
"value": 100
}
],
"io_serviced_recursive": null,
"io_queue_recursive": null,
"io_service_time_recursive": null,
"io_wait_time_recursive": null,
"io_merged_recursive": null,
"io_time_recursive": null,
"sectors_recursive": null
},
"num_procs": 16,
"storage_stats": {
"read_count_normalized": 7593984,
"read_size_bytes": 7593984,
"write_count_normalized": 7593984,
"write_size_bytes": 7593984
},
"preread": "2025-01-16T13:55:21.160452595Z",
"precpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.53/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.53/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.53/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.53/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.53/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.53/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"Published ports are discarded when using host network mode"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.53/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.53/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.53/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.53/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.53/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.53/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.53/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.53/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.53/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.53/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.53/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |
| manifests   | booleanDefault: falseInclude `Manifests` in the image summary.                                                                                                                                                                                                                                                                                                                                       |

### Responses

/v1.53/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2,
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
}
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.53/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| reserved-space | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| max-used-space | integer \<int64>Maximum amount of disk space allowed to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                   |
| min-free-space | integer \<int64>Target amount of free disk space after pruning                                                                                                                                                                                                                                                                                                                                                                                                           |
| all            | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters        | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.53/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. If the name includes a tag or digest, specific behavior applies:- If only `fromImage` includes a tag, that tag is used.
- If both `fromImage` and `tag` are provided, `tag` takes precedence.
- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.
- If neither a tag nor digest is specified, all tags are pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.53/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| manifests | booleanDefault: falseInclude Manifests in the image summary.The `manifests` and `platform` options are mutually exclusive, and an error is produced if both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show inspect. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.The `platform` and `manifests` options are mutually exclusive, and an error is produced if both are set.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.53/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"Identity": {
"Signature": [
{
"Name": "string",
"Timestamps": [
{
"Type": "Tlog",
"URI": "string",
"Timestamp": "2019-08-24T14:15:22Z"
}
],
"KnownSigner": "DHI",
"DockerReference": "string",
"Signer": {
"CertificateIssuer": "string",
"SubjectAlternativeName": "string",
"Issuer": "string",
"BuildSignerURI": "string",
"BuildSignerDigest": "string",
"RunnerEnvironment": "string",
"SourceRepositoryURI": "string",
"SourceRepositoryDigest": "string",
"SourceRepositoryRef": "string",
"SourceRepositoryIdentifier": "string",
"SourceRepositoryOwnerURI": "string",
"SourceRepositoryOwnerIdentifier": "string",
"BuildConfigURI": "string",
"BuildConfigDigest": "string",
"BuildTrigger": "string",
"RunInvocationURI": "string",
"SourceRepositoryVisibilityAtSigning": "string"
},
"SignatureType": "bundle-v0.3",
"Error": "string",
"Warnings": [
"string"
]
}
],
"Pull": [
{
"Repository": "string"
}
],
"Build": [
{
"Ref": "string",
"CreatedAt": "2019-08-24T14:15:22Z"
}
]
},
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"Author": "",
"Config": {
"User": "web:web",
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show the history for. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.53/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag      | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed.                                                                                                                                                                                                                                                                                                                   |
| platform | stringJSON-encoded OCI platform to select the platform-variant to push. If not provided, all available variants will attempt to be pushed.If the daemon provides a multi-platform image store, this selects the platform-variant to push to the registry. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.53/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.53/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|           |                                                                                                                                                     |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| force     | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags                                              |
| noprune   | booleanDefault: falseDo not delete untagged parent images                                                                                           |
| platforms | Array of stringsSelect platform-specific content to delete. Multiple values are accepted. Each platform is a OCI platform encoded as a JSON string. |

### Responses

/v1.53/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                   |
| limit        | integerMaximum number of results to return                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.53/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.53/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.53/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | Array of stringsJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.53/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| names    | Array of stringsImage names to filter by                                                                                                                                                                                                                                             |
| platform | Array of stringsJSON encoded OCI platform(s) which will be used to select the platform-specific image(s) to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.53/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| quiet    | booleanDefault: falseSuppress progress details during load.                                                                                                                                                                                                                       |
| platform | Array of stringsJSON encoded OCI platform(s) which will be used to select the platform-specific image(s) to load if the image is multi-platform. If not provided, the full multi-platform image will be loaded.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.53/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.53/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv4": true,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.53/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Services": {
"property1": null,
"property2": null
},
"Status": {
"IPAM": {
"Subnets": {
"172.16.0.0/16": {
"IPsInUse": 3,
"DynamicIPsAvailable": 65533
},
"2001:db8:abcd:0012::0/96": {
"IPsInUse": 5,
"DynamicIPsAvailable": 4294967291
}
}
}
},
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv4": true,
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.53/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|              |                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired | stringThe network's name.                                                                                                                                                                                                              |
| Driver       | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope        | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal     | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable   | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress      | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly   | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|              | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|              | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv4   | booleanEnable IPv4 on the network.                                                                                                                                                                                                     |
| EnableIPv6   | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|              | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|              | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.53/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv4": true,
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|                   |                                                                  |
| ----------------- | ---------------------------------------------------------------- |
| Containerrequired | stringThe ID or name of the container to connect to the network. |
|                   | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.53/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|                   |                                                                          |
| ----------------- | ------------------------------------------------------------------------ |
| Containerrequired | stringThe ID or name of the container to disconnect from the network.    |
| Force             | booleanDefault: falseForce the container to disconnect from the network. |

### Responses

/v1.53/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"Force": false
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.53/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.53/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.53/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.53/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.53/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.53/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.53/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.53/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.53/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.53/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.53/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.53/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.53/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.53/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.53/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.53/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.53/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.53/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.53/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.53/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.53/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.53/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.53/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.53/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"SwapBytes": -1,
"MemorySwappiness": -1
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.53/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.53/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.53/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"SwapBytes": -1,
"MemorySwappiness": -1
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.53/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.53/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.53/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.53/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.53/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.53/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.53/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.53/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.53/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.53/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.53/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.53/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.53/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.53/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.53/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.53/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.53/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.53/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.53/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.53/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.53/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.53/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.53/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.53/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.53/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |        |
| ------------- | ------ |
| username      | string |
| password      | string |
| serveraddress | string |

### Responses

/v1.53/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.53/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "6.8.0-31-generic",
"OperatingSystem": "Ubuntu 24.04 LTS",
"OSVersion": "24.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "27.0.1",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"FirewallBackend": {
"Driver": "nftables",
"Info": [ [
"ReloadedAt",
"2025-01-01T00:00:00Z"
]
]
},
"DiscoveredDevices": [
{
"Source": "cdi",
"ID": "vendor.com/gpu=0"
}
],
"NRI": {
"Info": [ [
"plugin-path",
"/opt/docker/nri/plugins"
]
]
},
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
],
"Containerd": {
"Address": "/run/containerd/containerd.sock",
"Namespaces": {
"Containers": "moby",
"Plugins": "plugins.moby"
}
}
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.53/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "27.0.1",
"Details": { }
}
],
"Version": "27.0.1",
"ApiVersion": "1.47",
"MinAPIVersion": "1.24",
"GitCommit": "48a66213fe",
"GoVersion": "go1.22.7",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "6.8.0-31-generic",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.53/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.53/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.53/events

### Response samples

* 200
* 400
* 500

Content type

application/jsonl

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|         |                                                                                                                           |
| ------- | ------------------------------------------------------------------------------------------------------------------------- |
| type    | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |
| verbose | booleanDefault: falseShow detailed information on space usage.                                                            |

### Responses

/v1.53/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"ImageUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
},
"ContainerUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
},
"VolumeUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
},
"BuildCacheUsage": {
"ActiveCount": 1,
"TotalCount": 4,
"Reclaimable": 12345678,
"TotalSize": 98765432,
"Items": [
null
]
}
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.53/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

> **Deprecated**: This endpoint is deprecated and will be removed in a future version. Server should support gRPC directly on the listening socket.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.53/session

----
url: https://docs.docker.com/engine/install/
----

# Install Docker Engine

***

Table of contents

***

This section describes how to install Docker Engine on Linux, also known as Docker CE. Docker Engine is also available for Windows, macOS, and Linux, through Docker Desktop. For instructions on how to install Docker Desktop, see: [Overview of Docker Desktop](https://docs.docker.com/desktop/).

## [Installation procedures for supported platforms](#installation-procedures-for-supported-platforms)

Click on a platform's link to view the relevant installation procedure.

| Platform                                                                            | x86\_64 / amd64 | arm64 / aarch64 | arm (32-bit) | ppc64le | s390x |
| ----------------------------------------------------------------------------------- | --------------- | --------------- | ------------ | ------- | ----- |
| [CentOS](https://docs.docker.com/engine/install/centos/)                            | ✅               | ✅               |              | ✅       |       |
| [Debian](https://docs.docker.com/engine/install/debian/)                            | ✅               | ✅               | ✅            | ✅       |       |
| [Fedora](https://docs.docker.com/engine/install/fedora/)                            | ✅               | ✅               |              | ✅       |       |
| [Raspberry Pi OS (32-bit)](https://docs.docker.com/engine/install/raspberry-pi-os/) |                 |                 | ⚠️           |         |       |
| [RHEL](https://docs.docker.com/engine/install/rhel/)                                | ✅               | ✅               |              |         | ✅     |
| [Ubuntu](https://docs.docker.com/engine/install/ubuntu/)                            | ✅               | ✅               | ✅            | ✅       | ✅     |
| [Binaries](https://docs.docker.com/engine/install/binaries/)                        | ✅               | ✅               | ✅            |         |       |

### [Other Linux distributions](#other-linux-distributions)

> Note
>
> While the following instructions may work, Docker doesn't test or verify installation on distribution derivatives.

* If you use Debian derivatives such as "BunsenLabs Linux", "Kali Linux" or "LMDE" (Debian-based Mint) should follow the installation instructions for [Debian](https://docs.docker.com/engine/install/debian/), substitute the version of your distribution for the corresponding Debian release. Refer to the documentation of your distribution to find which Debian release corresponds with your derivative version.
* Likewise, if you use Ubuntu derivatives such as "Kubuntu", "Lubuntu" or "Xubuntu" you should follow the installation instructions for [Ubuntu](https://docs.docker.com/engine/install/ubuntu/), substituting the version of your distribution for the corresponding Ubuntu release. Refer to the documentation of your distribution to find which Ubuntu release corresponds with your derivative version.
* Some Linux distributions provide a package of Docker Engine through their package repositories. These packages are built and maintained by the Linux distribution's package maintainers and may have differences in configuration or are built from modified source code. Docker isn't involved in releasing these packages and you should report any bugs or issues involving these packages to your Linux distribution's issue tracker.

Docker provides [binaries](https://docs.docker.com/engine/install/binaries/) for manual installation of Docker Engine. These binaries are statically linked and you can use them on any Linux distribution.

## [Release channels](#release-channels)

Docker Engine has two types of update channels, **stable** and **test**:

* The **stable** channel gives you the latest versions released for general availability.
* The **test** channel gives you pre-release versions that are ready for testing before general availability.

Use the test channel with caution. Pre-release versions include experimental and early-access features that are subject to breaking changes.

## [Support](#support)

Docker Engine is an open source project, supported by the Moby project maintainers and community members. Docker doesn't provide support for Docker Engine. Docker provides support for Docker products, including Docker Desktop, which uses Docker Engine as one of its components.

For information about the open source project, refer to the [Moby project website](https://mobyproject.org/).

### [Upgrade path](#upgrade-path)

Patch releases are always backward compatible with its major and minor version.

### [Licensing](#licensing)

Commercial use of Docker Engine obtained via Docker Desktop within larger enterprises (exceeding 250 employees OR with annual revenue surpassing $10 million USD), requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsEngineInstall). Apache License, Version 2.0. See [LICENSE](https://github.com/moby/moby/blob/master/LICENSE) for the full license.

## [Reporting security issues](#reporting-security-issues)

If you discover a security issue, we request that you bring it to our attention immediately.

DO NOT file a public issue. Instead, submit your report privately to <security@docker.com>.

Security reports are greatly appreciated, and Docker will publicly thank you for it.

## [Get started](#get-started)

After setting up Docker, you can learn the basics with [Getting started with Docker](https://docs.docker.com/get-started/introduction/).

----
url: https://docs.docker.com/guides/admin-set-up/finalize-plans-and-setup/
----

# Finalize plans and begin setup

***

Table of contents

***

## [Send finalized settings files to the MDM team](#send-finalized-settings-files-to-the-mdm-team)

After reaching an agreement with the relevant teams about your baseline and security configurations as outlined in the previous section, configure Settings Management using either the [Docker Admin Console](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/) or an [`admin-settings.json` file](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/).

Once the file is ready, collaborate with your MDM team to deploy your chosen settings, along with your chosen method for [enforcing sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).

> Important
>
> Test this first with a small number of Docker Desktop developers to verify the functionality works as expected before deploying more widely.

## [Manage your organizations](#manage-your-organizations)

If you have more than one organization, consider either [consolidating them into one organization](https://docs.docker.com/admin/organization/setup/orgs/) or creating a [Docker company](https://docs.docker.com/admin/company/) to manage multiple organizations.

## [Begin setup](#begin-setup)

### [Set up single sign-on and domain verification](#set-up-single-sign-on-and-domain-verification)

Single sign-on (SSO) lets developers authenticate using their identity providers (IdPs) to access Docker. SSO is available for a whole company and all associated organizations, or an individual organization that has a Docker Business subscription. For more information, see the [documentation](https://docs.docker.com/enterprise/security/single-sign-on/).

You can also enable [SCIM](https://docs.docker.com/enterprise/security/provisioning/scim/) for further automation of provisioning and deprovisioning of users.

### [Set up Docker product entitlements included in the subscription](#set-up-docker-product-entitlements-included-in-the-subscription)

[Docker Build Cloud](https://docs.docker.com/build-cloud/) significantly reduces build times, both locally and in CI, by providing a dedicated remote builder and shared cache. Powered by the cloud, developer time and local resources are freed up so your team can focus on more important things, like innovation. To get started, [set up a cloud builder](https://app.docker.com/build/).

[Docker Scout](https://docs.docker.com/scout/) is a solution for proactively enhancing your software supply chain security. By analyzing your images, Docker Scout compiles an inventory of components, also known as a Software Bill of Materials (SBOM). The SBOM is matched against a continuously updated vulnerability database to pinpoint security weaknesses. To get started, see [Quickstart](https://docs.docker.com/scout/quickstart/).

[Testcontainers Cloud](https://testcontainers.com/cloud/docs/) allows developers to run containers in the cloud, removing the need to run heavy containers on your local machine.

[Docker Hardened Images](https://docs.docker.com/dhi/) are minimal, secure, and production-ready container base and application images maintained by Docker. Designed to reduce vulnerabilities and simplify compliance, DHIs integrate easily into your existing Docker-based workflows with little to no retooling required.

### [Ensure you're running a supported version of Docker Desktop](#ensure-youre-running-a-supported-version-of-docker-desktop)

> Warning
>
> This step could affect the experience for users on older versions of Docker Desktop.

Existing users may be running outdated or unsupported versions of Docker Desktop. All users should update to a supported version. Docker Desktop versions released within the past 6 months from the latest release are supported.

Use an MDM solution to manage the version of Docker Desktop for users. Users may also get Docker Desktop directly from Docker or through a company software portal.

[Testing »](https://docs.docker.com/guides/admin-set-up/testing/)

----
url: https://docs.docker.com/enterprise/security/single-sign-on/manage/
----

# Manage SSO domains and connections

***

Table of contents

***

Subscription: Business

For: Administrators

This page covers how to manage single sign-on (SSO) after initial setup, including managing domains, connections, users, and provisioning settings.

## [Manage domains](#manage-domains)

### [Add a domain](#add-a-domain)

To add a domain to an existing SSO connection:

1. Sign in to [Docker Home](https://app.docker.com) and select your company or organization from the top-left account drop-down.
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the SSO connections table, select the **Actions** menu for your connection, then select **Edit connection**.
4. Select **Next** to navigate to the domains section.
5. In the **Domains** section, select **Add domain**.
6. Enter the domain you want to add to the connection.
7. Select **Next** to confirm or change the connected organizations.
8. Select **Next** to confirm or change the default organization and team provisioning selections.
9. Review the connection details and select **Update connection**.

### [Remove a domain from an SSO connection](#remove-a-domain-from-an-sso-connection)

> Important
>
> If you use multiple identity providers with the same domain, you must remove the domain from each SSO connection individually.

1. Sign in to [Docker Home](https://app.docker.com) and select your company or organization from the top-left account drop-down.
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the **SSO connections** table, select the **Actions** menu for your connection, then **Edit connection**.
4. Select **Next** to navigate to the domains section.
5. In the **Domain** section, select the **X** icon next to the domain you want to remove.
6. Select **Next** to confirm or change the connected organizations.
7. Select **Next** to confirm or change the default organization and team provisioning selections.
8. Review the connection details and select **Update connection**.

> Note
>
> When you re-add a domain, Docker assigns a new TXT record value. You must complete domain verification again with the new TXT record.

## [Manage SSO connections](#manage-sso-connections)

### [View connections](#view-connections)

To view all configured SSO connections:

1. Sign in to [Docker Home](https://app.docker.com) and select your company or organization from the top-left account drop-down.
2. Select **Admin Console**, then **SSO and SCIM**.
3. View all configured connections in the **SSO connections** table.

### [Edit a connection](#edit-a-connection)

To modify an existing SSO connection:

1. Sign in to [Docker Home](https://app.docker.com) and select your company or organization from the top-left account drop-down.
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the **SSO connections** table, select the **Actions** menu for your connection, then **Edit connection**.
4. Follow the on-screen instructions to modify your connection settings.

### [Delete a connection](#delete-a-connection)

To remove an SSO connection:

1. Sign in to [Docker Home](https://app.docker.com) and select your company or organization from the top-left account drop-down.
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the **SSO connections** table, select the **Actions** menu for your connection, then **Delete connection**.
4. Follow the on-screen instructions to confirm the deletion.

> Warning
>
> Deleting an SSO connection removes access for all users who authenticate through that connection.

## [Manage users and provisioning](#manage-users-and-provisioning)

Docker automatically provisions users through Just-in-Time (JIT) provisioning when they sign in via SSO. You can also manually manage users and configure different provisioning methods.

### [How provisioning works](#how-provisioning-works)

Docker supports the following provisioning methods:

* JIT provisioning (default): Users are automatically added to your organization when they sign in via SSO
* SCIM provisioning: Sync users and groups from your identity provider to Docker
* Group mapping: Sync user groups from your identity provider with teams in your Docker organization
* Manual provisioning: Turn off automatic provisioning and manually invite users

For more information on provisioning methods, see [Provision users](https://docs.docker.com/enterprise/security/provisioning/).

### [Add guest users](#add-guest-users)

To invite users who don't authenticate through your identity provider:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Members**.
3. Select **Invite**.
4. Follow the on-screen instructions to invite the user.

The user receives an email invitation and can create a Docker account or sign in with their existing account.

### [Remove users](#remove-users)

To remove a user from your organization:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Members**.
3. Find the user you want to remove and select the **Actions** menu next to their name.
4. Select **Remove** and confirm the removal.

The user loses access to your organization immediately upon removal.

----
url: https://docs.docker.com/reference/cli/docker/context/import/
----

# docker context import

***

| Description | Import a context from a tar or zip file |
| ----------- | --------------------------------------- |
| Usage       | `docker context import CONTEXT FILE\|-` |

## [Description](#description)

Imports a context previously exported with `docker context export`. To import from stdin, use a hyphen (`-`) as filename.

----
url: https://docs.docker.com/dhi/core-concepts/digests/
----

# Image digests

***

Table of contents

***

## [What are Docker image digests?](#what-are-docker-image-digests)

A Docker image digest is a unique, cryptographic identifier (SHA-256 hash) representing the content of a Docker image. Unlike tags, which can be reused or changed, a digest is immutable and ensures that the exact same image is pulled every time. This guarantees consistency across different environments and deployments.

For example, the digest for the `nginx:latest` image might look like:

```text
sha256:94a00394bc5a8ef503fb59db0a7d0ae9e1110866e8aee8ba40cd864cea69ea1a
```

This digest uniquely identifies the specific version of the `nginx:latest` image, ensuring that any changes to the image content result in a different digest.

## [Why are image digests important?](#why-are-image-digests-important)

Using image digests instead of tags offers several advantages:

* Immutability: Once an image is built and its digest is generated, the content tied to that digest cannot change. This means that if you pull an image using its digest, you can be confident that you are retrieving exactly the same image that was originally built.

* Security: Digests help prevent supply chain attacks by ensuring that the image content has not been tampered with. Even a small change in the image content will result in a completely different digest.

* Consistency: Using digests ensures that the same image is used across different environments, reducing the risk of discrepancies between development, staging, and production environments.

## [Docker Hardened Image digests](#docker-hardened-image-digests)

By using image digests to reference DHIs, you can ensure that your applications are always using the exact same secure image version, enhancing security and compliance

## [View an image digest](#view-an-image-digest)

### [Use the Docker CLI](#use-the-docker-cli)

To view the image digest of a Docker image, you can use the following command. Replace `<image-name>:<tag>` with the image name and tag.

```console
$ docker buildx imagetools inspect <image-name>:<tag>
```

### [Use the Docker Hub UI](#use-the-docker-hub-ui)

1. Go to [Docker Hub](https://hub.docker.com/) and sign in.
2. Navigate to your organization's namespace and open the mirrored DHI repository.
3. Select the **Tags** tab to view image variants.
4. Each tag in the list includes a **Digest** field showing the image's SHA-256 value.

## [Pull an image by digest](#pull-an-image-by-digest)

Pulling an image by digest ensures that you are pulling the exact image version identified by the specified digest.

To pull a Docker image using its digest, use the following command. Replace `<image-name>` with the image name and `<digest>` with the image digest.

```console
$ docker pull <image-name>@sha256:<digest>
```

For example, to pull a `docs/dhi-python:3.13` image using its digest of `94a00394bc5a8ef503fb59db0a7d0ae9e1110866e8aee8ba40cd864cea69ea1a`, you would run:

```console
$ docker pull docs/dhi-python@sha256:94a00394bc5a8ef503fb59db0a7d0ae9e1110866e8aee8ba40cd864cea69ea1a
```

## [Multi-platform images and manifests](#multi-platform-images-and-manifests)

Docker Hardened Images are published as multi-platform images, which means a single image tag (like `docs/dhi-python:3.13`) can support multiple operating systems and CPU architectures, such as `linux/amd64`, `linux/arm64`, and more.

Instead of pointing to a single image, a multi-platform tag points to a manifest list (also called an index), which is a higher-level object that references multiple image digests, one for each supported platform.

When you inspect a multi-platform image using `docker buildx imagetools inspect`, you'll see something like this:

```text
Name:      docs/dhi-python:3.13
MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest:    sha256:6e05...d231

Manifests:
  Name:        docs/dhi-python:3.13@sha256:94a0...ea1a
  Platform:    linux/amd64
  ...

  Name:        docs/dhi-python:3.13@sha256:7f1d...bc43
  Platform:    linux/arm64
  ...
```

* The manifest list digest (`sha256:6e05...d231`) identifies the overall multi-platform image.
* Each platform-specific image has its own digest (e.g., `sha256:94a0...ea1a` for `linux/amd64`).

### [Why this matters](#why-this-matters)

* Reproducibility: If you're building or running containers on different architectures, using a tag alone will resolve to the appropriate image digest for your platform.
* Verification: You can pull and verify a specific image digest for your platform to ensure you're using the exact image version, not just the manifest list.
* Policy enforcement: When enforcing digest-based policies with Docker Scout, each platform variant is evaluated individually using its digest.

----
url: https://docs.docker.com/reference/cli/docker/sandbox/inspect/
----

# docker sandbox inspect

***

| Description | Display detailed information on one or more sandboxes   |
| ----------- | ------------------------------------------------------- |
| Usage       | `docker sandbox inspect [OPTIONS] SANDBOX [SANDBOX...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Display detailed information on one or more sandboxes.

This command retrieves and displays detailed information about the specified sandboxes using the Docker API. Each sandbox is identified by its unique ID or name.

## [Examples](#examples)

### [Inspect a sandbox](#inspect-a-sandbox)

```console
$ docker sandbox inspect abc123def
[
  {
    "id": "abc123def69b16c5c0dab4cf699e26f8d01e1ace3aeee06254e0999492e11647",
    "name": "claude-sandbox-2025-11-04-170333",
    "created_at": "2025-11-04T16:03:33.910642347Z",
    "status": "running",
    "template": "docker/sandbox-templates:claude-code",
    "labels": {
      "com.docker.sandbox.agent": "claude",
      "com.docker.sandbox.workingDirectory": "/Users/moby/code/docker/sandboxes",
      "com.docker.sandbox.workingDirectoryInode": "3041007",
      "com.docker.sandboxes": "templates",
      "com.docker.sandboxes.base": "ubuntu:questing",
      "com.docker.sandboxes.flavor": "claude-code",
      "com.docker.sdk": "true",
      "com.docker.sdk.client": "0.1.0-alpha011",
      "com.docker.sdk.container": "0.1.0-alpha012",
      "com.docker.sdk.lang": "go",
      "docker/sandbox": "true",
      "org.opencontainers.image.ref.name": "ubuntu",
      "org.opencontainers.image.version": "25.10"
    }
  }
]
```

----
url: https://docs.docker.com/desktop/setup/vm-vdi/
----

# Run Docker Desktop for Windows in a VM or VDI environment

***

Table of contents

***

Docker recommends running Docker Desktop natively on Mac, Linux, or Windows. However, Docker Desktop for Windows can run inside a virtual desktop provided the virtual desktop is properly configured.

To run Docker Desktop in a virtual desktop environment, you have two options, depending on whether nested virtualization is supported:

* If your environment supports nested virtualization, you can run Docker Desktop with its default local Linux VM.
* If nested virtualization is not supported, Docker recommends subscribing to and using Docker Offload.

## [Use Docker Offload](#use-docker-offload)

[Docker Offload](/offload/) lets you offload container workloads to a high-performance, fully hosted cloud environment, enabling a seamless hybrid experience.

Docker Offload is useful in virtual desktop environments where nested virtualization isn't supported. In these environments, Docker Desktop can use Docker Offload to ensure you can still build and run containers without relying on local virtualization.

Docker Offload decouples the Docker Desktop client from the Docker Engine, allowing the Docker CLI and Docker Desktop Dashboard to interact with cloud-based resources as if they were local. When you run a container, Docker provisions a secure, isolated, and ephemeral cloud environment connected to Docker Desktop via an SSH tunnel. Despite running remotely, features like bind mounts and port forwarding continue to work seamlessly, providing a local-like experience. To use Docker Offload:

For more information, see the [Docker Offload product page](https://www.docker.com/products/docker-offload/) and the [Docker Offload documentation](/offload/).

## [Virtual desktop support when using nested virtualization](#virtual-desktop-support-when-using-nested-virtualization)

> Note
>
> Support for running Docker Desktop on a virtual desktop is available to Docker Business customers, on VMware ESXi or Azure VMs only.

Docker support includes installing and running Docker Desktop within the VM, provided that nested virtualization is correctly enabled. The only hypervisors successfully tested are VMware ESXi and Azure, and there is no support for other VMs. For more information on Docker Desktop support, see [Get support](https://docs.docker.com/support/).

For troubleshooting problems and intermittent failures that are outside of Docker's control, you should contact your hypervisor vendor. Each hypervisor vendor offers different levels of support. For example, Microsoft supports running nested Hyper-V both on-prem and on Azure, with some version constraints. This may not be the case for VMware ESXi.

Docker does not support running multiple instances of Docker Desktop on the same machine in a VM or VDI environment.

> Tip
>
> If you're running Docker Desktop inside a Citrix VDI, note that Citrix can be used with a variety of underlying hypervisors, for example VMware, Hyper-V, Citrix Hypervisor/XenServer. Docker Desktop requires nested virtualization, which is not supported by Citrix Hypervisor/XenServer.
>
> Check with your Citrix administrator or VDI infrastructure team to confirm which hypervisor is being used, and whether nested virtualization is enabled.

## [Turn on nested virtualization](#turn-on-nested-virtualization)

You must turn on nested virtualization before you install Docker Desktop on a virtual machine that will not use Docker Cloud.

### [Turn on nested virtualization on VMware ESXi](#turn-on-nested-virtualization-on-vmware-esxi)

Nested virtualization of other hypervisors like Hyper-V inside a vSphere VM [is not a supported scenario](https://kb.vmware.com/s/article/2009916). However, running Hyper-V VM in a VMware ESXi VM is technically possible and, depending on the version, ESXi includes hardware-assisted virtualization as a supported feature. A VM that had 1 CPU with 4 cores and 12GB of memory was used for internal testing.

For steps on how to expose hardware-assisted virtualization to the guest OS, [see VMware's documentation](https://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/7-0/expose-hardware-assisted-virtualization.html).

### [Turn on nested virtualization on an Azure Virtual Machine](#turn-on-nested-virtualization-on-an-azure-virtual-machine)

Nested virtualization is supported by Microsoft for running Hyper-V inside an Azure VM.

For Azure virtual machines, [check that the VM size chosen supports nested virtualization](https://docs.microsoft.com/en-us/azure/virtual-machines/sizes). Microsoft provides [a helpful list on Azure VM sizes](https://docs.microsoft.com/en-us/azure/virtual-machines/acu) and highlights the sizes that currently support nested virtualization. D4s\_v5 machines were used for internal testing. Use this specification or above for optimal performance of Docker Desktop.

## [Docker Desktop support on Nutanix-powered VDI](#docker-desktop-support-on-nutanix-powered-vdi)

Docker Desktop can be used within Nutanix-powered VDI environments provided that the underlying Windows environment supports WSL 2 or Windows container mode. Since Nutanix officially supports WSL 2, Docker Desktop should function as expected, as long as WSL 2 operates correctly within the VDI environment.

If using Windows container mode, confirm that the Nutanix environment supports Hyper-V or alternative Windows container backends.

### [Supported configurations](#supported-configurations)

Docker Desktop follows the VDI support definitions outlined [previously](#virtual-desktop-support-when-using-nested-virtualization):

* Persistent VDI environments (Supported): You receive the same virtual desktop instance across sessions, preserving installed software and configurations.

* Non-persistent VDI environments (Not supported): Docker Desktop does not support environments where the OS resets between sessions, requiring re-installation or reconfiguration each time.

### [Support scope and responsibilities](#support-scope-and-responsibilities)

For WSL 2-related issues, contact Nutanix support. For Docker Desktop-specific issues, contact Docker support.

## [Additional resources](#additional-resources)

* [Docker Desktop on Microsoft Dev Box](https://docs.docker.com/enterprise/enterprise-deployment/dev-box/)

----
url: https://docs.docker.com/reference/compose-file/profiles/
----

# Learn how to use profiles in Docker Compose

***

Table of contents

***

With profiles you can define a set of active profiles so your Compose application model is adjusted for various usages and environments.

The [services](https://docs.docker.com/reference/compose-file/services/) top-level element supports a `profiles` attribute to define a list of named profiles. Services without a `profiles` attribute are always enabled.

A service is ignored by Compose when none of the listed `profiles` match the active ones, unless the service is explicitly targeted by a command. In that case its profile is added to the set of active profiles.

> Note
>
> All other top-level elements are not affected by `profiles` and are always active.

References to other services (by `links`, `extends` or shared resource syntax `service:xxx`) do not automatically enable a component that would otherwise have been ignored by active profiles. Instead Compose returns an error.

## [Illustrative example](#illustrative-example)

```yaml
services:
  web:
    image: web_image

  test_lib:
    image: test_lib_image
    profiles:
      - test

  coverage_lib:
    image: coverage_lib_image
    depends_on:
      - test_lib
    profiles:
      - test

  debug_lib:
    image: debug_lib_image
    depends_on:
      - test_lib
    profiles:
      - debug
```

In the above example:

* If the Compose application model is parsed when no profile is enabled, it only contains the `web` service.
* If the profile `test` is enabled, the model contains the services `test_lib` and `coverage_lib`, and service `web`, which is always enabled.
* If the profile `debug` is enabled, the model contains both `web` and `debug_lib` services, but not `test_lib` and `coverage_lib`, and as such the model is invalid regarding the `depends_on` constraint of `debug_lib`.
* If the profiles `debug` and `test` are enabled, the model contains all services; `web`, `test_lib`, `coverage_lib` and `debug_lib`.
* If Compose is executed with `test_lib` as the explicit service to run, `test_lib` and the `test` profile are active even if `test` profile is not enabled.
* If Compose is executed with `coverage_lib` as the explicit service to run, the service `coverage_lib` and the profile `test` are active and `test_lib` is pulled in by the `depends_on` constraint.
* If Compose is executed with `debug_lib` as the explicit service to run, again the model is invalid regarding the `depends_on` constraint of `debug_lib`, since `debug_lib` and `test_lib` have no common `profiles` listed.
* If Compose is executed with `debug_lib` as the explicit service to run and profile `test` is enabled, profile `debug` is automatically enabled and service `test_lib` is pulled in as a dependency starting both services `debug_lib` and `test_lib`.

Learn how to use `profiles` in [Docker Compose](https://docs.docker.com/compose/how-tos/profiles/).

----
url: https://docs.docker.com/scout/install/
----

# Install Docker Scout

***

Table of contents

***

The Docker Scout CLI plugin comes pre-installed with Docker Desktop.

If you run Docker Engine without Docker Desktop, Docker Scout doesn't come pre-installed, but you can install it as a standalone binary.

## [Installation script](#installation-script)

To install the latest version of the plugin, run the following commands:

```console
$ curl -fsSL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh -o install-scout.sh
$ sh install-scout.sh
```

> Note
>
> Always examine scripts downloaded from the internet before running them locally. Before installing, make yourself familiar with potential risks and limitations of the convenience script.

## [Manual installation](#manual-installation)

1. Download the latest release from the [releases page](https://github.com/docker/scout-cli/releases).

2. Create a subdirectory under `$HOME/.docker` called `scout`.

   ```console
   $ mkdir -p $HOME/.docker/scout
   ```

3. Extract the archive and move the `docker-scout` binary to the `$HOME/.docker/scout` directory.

4. Make the binary executable: `chmod +x $HOME/.docker/scout/docker-scout`.

5. Add the `scout` subdirectory to your `.docker/config.json` as a plugin directory:

   ```json
   {
     "cliPluginsExtraDirs": [
       "/home/USER/.docker/scout"
     ]
   }
   ```

   Substitute `<USER>` with your username on the system.

   > Note
   >
   > The path for `cliPluginsExtraDirs` must be an absolute path.

1) Download the latest release from the [releases page](https://github.com/docker/scout-cli/releases).

2) Create a subdirectory under `$HOME/.docker` called `scout`.

   ```console
   $ mkdir -p $HOME/.docker/scout
   ```

3) Extract the archive and move the `docker-scout` binary to the `$HOME/.docker/scout` directory.

4) Make the binary executable:

   ```console
   $ chmod +x $HOME/.docker/scout/docker-scout
   ```

5) Authorize the binary to be executable on macOS:

   ```console
   xattr -d com.apple.quarantine $HOME/.docker/scout/docker-scout
   ```

6) Add the `scout` subdirectory to your `.docker/config.json` as a plugin directory:

   ```json
   {
     "cliPluginsExtraDirs": [
       "/Users/USER/.docker/scout"
     ]
   }
   ```

   Substitute `<USER>` with your username on the system.

   > Note
   >
   > The path for `cliPluginsExtraDirs` must be an absolute path.

1. Download the latest release from the [releases page](https://github.com/docker/scout-cli/releases).

2. Create a subdirectory under `%USERPROFILE%/.docker` called `scout`.

   ```console
   % mkdir %USERPROFILE%\.docker\scout
   ```

3. Extract the archive and move the `docker-scout.exe` binary to the `%USERPROFILE%\.docker\scout` directory.

4. Add the `scout` subdirectory to your `.docker\config.json` as a plugin directory:

   ```json
   {
     "cliPluginsExtraDirs": [
       "C:\Users\USER\.docker\scout"
     ]
   }
   ```

   Substitute `<USER>` with your username on the system.

   > Note
   >
   > The path for `cliPluginsExtraDirs` must be an absolute path.

## [Container image](#container-image)

The Docker Scout CLI plugin is also available as a [container image](https://hub.docker.com/r/docker/scout-cli). Use the `docker/scout-cli` to run `docker scout` commands without installing the CLI plugin on your host.

```console
$ docker run -it \
  -e DOCKER_SCOUT_HUB_USER=<your Docker Hub user name> \
  -e DOCKER_SCOUT_HUB_PASSWORD=<your Docker Hub PAT>  \
  docker/scout-cli <command>
```

## [GitHub Action](#github-action)

The Docker Scout CLI plugin is also available as a [GitHub action](https://github.com/docker/scout-action). You can use it in your GitHub workflows to automatically analyze images and evaluate policy compliance with each push.

Docker Scout also integrates with many more CI/CD tools, such as Jenkins, GitLab, and Azure DevOps. Learn more about the [integrations](https://docs.docker.com/scout/integrations/) available for Docker Scout.

----
url: https://docs.docker.com/engine/swarm/swarm-tutorial/drain-node/
----

# Drain a node on the swarm

***

***

In earlier steps of the tutorial, all the nodes have been running with `Active` availability. The swarm manager can assign tasks to any `Active` node, so up to now all nodes have been available to receive tasks.

Sometimes, such as planned maintenance times, you need to set a node to `Drain` availability. `Drain` availability prevents a node from receiving new tasks from the swarm manager. It also means the manager stops tasks running on the node and launches replica tasks on a node with `Active` availability.

> Important
>
> Setting a node to `Drain` does not remove standalone containers from that node, such as those created with `docker run`, `docker compose up`, or the Docker Engine API. A node's status, including `Drain`, only affects the node's ability to schedule swarm service workloads.

1. If you haven't already, open a terminal and ssh into the machine where you run your manager node. For example, the tutorial uses a machine named `manager1`.

2. Verify that all your nodes are actively available.

   ```console
   $ docker node ls

   ID                           HOSTNAME  STATUS  AVAILABILITY  MANAGER STATUS
   1bcef6utixb0l0ca7gxuivsj0    worker2   Ready   Active
   38ciaotwjuritcdtn9npbnkuz    worker1   Ready   Active
   e216jshn25ckzbvmwlnh5jr3g *  manager1  Ready   Active        Leader
   ```

3. If you aren't still running the `redis` service from the [rolling update](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/) tutorial, start it now:

   ```console
   $ docker service create --replicas 3 --name redis --update-delay 10s redis:7.4.0

   c5uo6kdmzpon37mgj9mwglcfw
   ```

4. Run `docker service ps redis` to see how the swarm manager assigned the tasks to different nodes:

   ```console
   $ docker service ps redis

   NAME                               IMAGE        NODE     DESIRED STATE  CURRENT STATE
   redis.1.7q92v0nr1hcgts2amcjyqg3pq  redis:7.4.0  manager1 Running        Running 26 seconds
   redis.2.7h2l8h3q3wqy5f66hlv9ddmi6  redis:7.4.0  worker1  Running        Running 26 seconds
   redis.3.9bg7cezvedmkgg6c8yzvbhwsd  redis:7.4.0  worker2  Running        Running 26 seconds
   ```

   In this case the swarm manager distributed one task to each node. You may see the tasks distributed differently among the nodes in your environment.

5. Run `docker node update --availability drain <NODE-ID>` to drain a node that had a task assigned to it:

   ```console
   $ docker node update --availability drain worker1

   worker1
   ```

6. Inspect the node to check its availability:

   ```console
   $ docker node inspect --pretty worker1

   ID:			38ciaotwjuritcdtn9npbnkuz
   Hostname:		worker1
   Status:
    State:			Ready
    Availability:		Drain
   ...snip...
   ```

   The drained node shows `Drain` for `Availability`.

7. Run `docker service ps redis` to see how the swarm manager updated the task assignments for the `redis` service:

   ```console
   $ docker service ps redis

   NAME                                    IMAGE        NODE      DESIRED STATE  CURRENT STATE           ERROR
   redis.1.7q92v0nr1hcgts2amcjyqg3pq       redis:7.4.0  manager1  Running        Running 4 minutes
   redis.2.b4hovzed7id8irg1to42egue8       redis:7.4.0  worker2   Running        Running About a minute
    \_ redis.2.7h2l8h3q3wqy5f66hlv9ddmi6   redis:7.4.0  worker1   Shutdown       Shutdown 2 minutes ago
   redis.3.9bg7cezvedmkgg6c8yzvbhwsd       redis:7.4.0  worker2   Running        Running 4 minutes
   ```

   The swarm manager maintains the desired state by ending the task on a node with `Drain` availability and creating a new task on a node with `Active` availability.

8. Run `docker node update --availability active <NODE-ID>` to return the drained node to an active state:

   ```console
   $ docker node update --availability active worker1

   worker1
   ```

9. Inspect the node to see the updated state:

   ```console
   $ docker node inspect --pretty worker1

   ID:			38ciaotwjuritcdtn9npbnkuz
   Hostname:		worker1
   Status:
    State:			Ready
    Availability:		Active
   ...snip...
   ```

   When you set the node back to `Active` availability, it can receive new tasks:

   * during a service update to scale up
   * during a rolling update
   * when you set another node to `Drain` availability
   * when a task fails on another active node

## [Next steps](#next-steps)

Next, you'll learn how to use a Swarm mode routing mesh

[Use a Swarm mode routing mesh](https://docs.docker.com/engine/swarm/ingress/)

----
url: https://docs.docker.com/get-started/workshop/07_multi_container/
----

# Multi container apps

***

Table of contents

***

Up to this point, you've been working with single container apps. But, now you will add MySQL to the application stack. The following question often arises - "Where will MySQL run? Install it in the same container or run it separately?" In general, each container should do one thing and do it well. The following are a few reasons to run the container separately:

* There's a good chance you'd have to scale APIs and front-ends differently than databases.
* Separate containers let you version and update versions in isolation.
* While you may use a container for the database locally, you may want to use a managed service for the database in production. You don't want to ship your database engine with your app then.
* Running multiple processes will require a process manager (the container only starts one process), which adds complexity to container startup/shutdown.

And there are more reasons. So, like the following diagram, it's best to run your app in multiple containers.

## [Container networking](#container-networking)

Remember that containers, by default, run in isolation and don't know anything about other processes or containers on the same machine. So, how do you allow one container to talk to another? The answer is networking. If you place the two containers on the same network, they can talk to each other.

## [Start MySQL](#start-mysql)

There are two ways to put a container on a network:

* Assign the network when starting the container.
* Connect an already running container to a network.

In the following steps, you'll create the network first and then attach the MySQL container at startup.

1. Create the network.

   ```console
   $ docker network create todo-app
   ```

2. Start a MySQL container and attach it to the network. You're also going to define a few environment variables that the database will use to initialize the database. To learn more about the MySQL environment variables, see the "Environment Variables" section in the [MySQL Docker Hub listing](https://hub.docker.com/_/mysql/).

   ```console
   $ docker run -d \
       --network todo-app --network-alias mysql \
       -v todo-mysql-data:/var/lib/mysql \
       -e MYSQL_ROOT_PASSWORD=secret \
       -e MYSQL_DATABASE=todos \
       mysql:8.0
   ```

   ```powershell
   $ docker run -d `
       --network todo-app --network-alias mysql `
       -v todo-mysql-data:/var/lib/mysql `
       -e MYSQL_ROOT_PASSWORD=secret `
       -e MYSQL_DATABASE=todos `
       mysql:8.0
   ```

   ```console
   $ docker run -d ^
       --network todo-app --network-alias mysql ^
       -v todo-mysql-data:/var/lib/mysql ^
       -e MYSQL_ROOT_PASSWORD=secret ^
       -e MYSQL_DATABASE=todos ^
       mysql:8.0
   ```

   In the previous command, you can see the `--network-alias` flag. In a later section, you'll learn more about this flag.

   > Tip
   >
   > You'll notice a volume named `todo-mysql-data` in the above command that is mounted at `/var/lib/mysql`, which is where MySQL stores its data. However, you never ran a `docker volume create` command. Docker recognizes you want to use a named volume and creates one automatically for you.

3. To confirm you have the database up and running, connect to the database and verify that it connects.

   ```console
   $ docker exec -it <mysql-container-id> mysql -u root -p
   ```

   When the password prompt comes up, type in `secret`. In the MySQL shell, list the databases and verify you see the `todos` database.

   ```console
   mysql> SHOW DATABASES;
   ```

   You should see output that looks like this:

   ```plaintext
   +--------------------+
   | Database           |
   +--------------------+
   | information_schema |
   | mysql              |
   | performance_schema |
   | sys                |
   | todos              |
   +--------------------+
   5 rows in set (0.00 sec)
   ```

4. Exit the MySQL shell to return to the shell on your machine.

   ```console
   mysql> exit
   ```

   You now have a `todos` database and it's ready for you to use.

## [Connect to MySQL](#connect-to-mysql)

Now that you know MySQL is up and running, you can use it. But, how do you use it? If you run another container on the same network, how do you find the container? Remember that each container has its own IP address.

To answer the questions above and better understand container networking, you're going to make use of the [nicolaka/netshoot](https://github.com/nicolaka/netshoot) container, which ships with a lot of tools that are useful for troubleshooting or debugging networking issues.

1. Start a new container using the nicolaka/netshoot image. Make sure to connect it to the same network.

   ```console
   $ docker run -it --network todo-app nicolaka/netshoot
   ```

2. Inside the container, you're going to use the `dig` command, which is a useful DNS tool. You're going to look up the IP address for the hostname `mysql`.

   ```console
   $ dig mysql
   ```

   You should get output like the following.

   ```text
   ; <<>> DiG 9.18.8 <<>> mysql
   ;; global options: +cmd
   ;; Got answer:
   ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 32162
   ;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

   ;; QUESTION SECTION:
   ;mysql.				IN	A

   ;; ANSWER SECTION:
   mysql.			600	IN	A	172.23.0.2

   ;; Query time: 0 msec
   ;; SERVER: 127.0.0.11#53(127.0.0.11)
   ;; WHEN: Tue Oct 01 23:47:24 UTC 2019
   ;; MSG SIZE  rcvd: 44
   ```

   In the "ANSWER SECTION", you will see an `A` record for `mysql` that resolves to `172.23.0.2` (your IP address will most likely have a different value). While `mysql` isn't normally a valid hostname, Docker was able to resolve it to the IP address of the container that had that network alias. Remember, you used the `--network-alias` earlier.

   What this means is that your app only simply needs to connect to a host named `mysql` and it'll talk to the database.

## [Run your app with MySQL](#run-your-app-with-mysql)

The todo app supports the setting of a few environment variables to specify MySQL connection settings. They are:

* `MYSQL_HOST` - the hostname for the running MySQL server
* `MYSQL_USER` - the username to use for the connection
* `MYSQL_PASSWORD` - the password to use for the connection
* `MYSQL_DB` - the database to use once connected

> Note
>
> While using env vars to set connection settings is generally accepted for development, it's highly discouraged when running applications in production. Diogo Monica, a former lead of security at Docker, [wrote a fantastic blog post](https://blog.diogomonica.com/2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/) explaining why.
>
> A more secure mechanism is to use the secret support provided by your container orchestration framework. In most cases, these secrets are mounted as files in the running container. You'll see many apps (including the MySQL image and the todo app) also support env vars with a `_FILE` suffix to point to a file containing the variable.
>
> As an example, setting the `MYSQL_PASSWORD_FILE` var will cause the app to use the contents of the referenced file as the connection password. Docker doesn't do anything to support these env vars. Your app will need to know to look for the variable and get the file contents.

You can now start your dev-ready container.

1. Specify each of the previous environment variables, as well as connect the container to your app network. Make sure that you are in the `getting-started-app` directory when you run this command.

   ```console
   $ docker run -dp 127.0.0.1:3000:3000 \
     -w /app -v ".:/app" \
     --network todo-app \
     -e MYSQL_HOST=mysql \
     -e MYSQL_USER=root \
     -e MYSQL_PASSWORD=secret \
     -e MYSQL_DB=todos \
     node:24-alpine \
     sh -c "npm install && npm run dev"
   ```

   In Windows, run this command in PowerShell.

   ```powershell
   $ docker run -dp 127.0.0.1:3000:3000 `
     -w /app -v ".:/app" `
     --network todo-app `
     -e MYSQL_HOST=mysql `
     -e MYSQL_USER=root `
     -e MYSQL_PASSWORD=secret `
     -e MYSQL_DB=todos `
     node:24-alpine `
     sh -c "npm install && npm run dev"
   ```

   In Windows, run this command in Command Prompt.

   ```console
   $ docker run -dp 127.0.0.1:3000:3000 ^
     -w /app -v "%cd%:/app" ^
     --network todo-app ^
     -e MYSQL_HOST=mysql ^
     -e MYSQL_USER=root ^
     -e MYSQL_PASSWORD=secret ^
     -e MYSQL_DB=todos ^
     node:24-alpine ^
     sh -c "npm install && npm run dev"
   ```

   ```console
   $ docker run -dp 127.0.0.1:3000:3000 \
     -w //app -v "/.:/app" \
     --network todo-app \
     -e MYSQL_HOST=mysql \
     -e MYSQL_USER=root \
     -e MYSQL_PASSWORD=secret \
     -e MYSQL_DB=todos \
     node:24-alpine \
     sh -c "npm install && npm run dev"
   ```

2. If you look at the logs for the container (`docker logs -f <container-id>`), you should see a message similar to the following, which indicates it's using the mysql database.

   ```console
   [nodemon] 3.1.11
   [nodemon] to restart at any time, enter `rs`
   [nodemon] watching path(s): *.*
   [nodemon] watching extensions: js,mjs,cjs,json
   [nodemon] starting `node src/index.js`
   Waiting for mysql:3306.
   Connected!
   Connected to mysql db at host mysql
   Listening on port 3000
   ```

3. Open the app in your browser and add a few items to your todo list.

4. Connect to the mysql database and prove that the items are being written to the database. Remember, the password is `secret`.

   ```console
   $ docker exec -it <mysql-container-id> mysql -p todos
   ```

   And in the mysql shell, run the following:

   ```console
   mysql> select * from todo_items;
   +--------------------------------------+--------------------+-----------+
   | id                                   | name               | completed |
   +--------------------------------------+--------------------+-----------+
   | c906ff08-60e6-44e6-8f49-ed56a0853e85 | Do amazing things! |         0 |
   | 2912a79e-8486-4bc3-a4c5-460793a575ab | Be awesome!        |         0 |
   +--------------------------------------+--------------------+-----------+
   ```

   Your table will look different because it has your items. But, you should see them stored there.

## [Summary](#summary)

At this point, you have an application that now stores its data in an external database running in a separate container. You learned a little bit about container networking and service discovery using DNS.

Related information:

* [docker CLI reference](/reference/cli/docker/)
* [Networking overview](https://docs.docker.com/engine/network/)

## [Next steps](#next-steps)

There's a good chance you are starting to feel a little overwhelmed with everything you need to do to start up this application. You have to create a network, start containers, specify all of the environment variables, expose ports, and more. That's a lot to remember and it's certainly making things harder to pass along to someone else.

In the next section, you'll learn about Docker Compose. With Docker Compose, you can share your application stacks in a much easier way and let others spin them up with a single, simple command.

[Use Docker Compose](https://docs.docker.com/get-started/workshop/08_using_compose/)

----
url: https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/
----

# Merge Compose files

***

Table of contents

***

Docker Compose lets you merge and override a set of Compose files together to create a composite Compose file.

By default, Compose reads two files, a `compose.yaml` and an optional `compose.override.yaml` file. By convention, the `compose.yaml` contains your base configuration. The override file can contain configuration overrides for existing services or entirely new services.

If a service is defined in both files, Compose merges the configurations using the rules described below and in the [Compose Specification](https://docs.docker.com/reference/compose-file/merge/).

## [How to merge multiple Compose files](#how-to-merge-multiple-compose-files)

To use multiple override files, or an override file with a different name, you can either use the pre-defined [COMPOSE\_FILE](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_file) environment variable, or use the `-f` option to specify the list of files.

Compose merges files in the order they're specified on the command line. Subsequent files may merge, override, or add to their predecessors.

For example:

```console
$ docker compose -f compose.yaml -f compose.admin.yaml run backup_db
```

The `compose.yaml` file might specify a `webapp` service.

```yaml
webapp:
  image: examples/web
  ports:
    - "8000:8000"
  volumes:
    - "/data"
```

The `compose.admin.yaml` may also specify this same service:

```yaml
webapp:
  environment:
    - DEBUG=1
```

Any matching fields override the previous file. New values, add to the `webapp` service configuration:

```yaml
webapp:
  image: examples/web
  ports:
    - "8000:8000"
  volumes:
    - "/data"
  environment:
    - DEBUG=1
```

## [Merging rules](#merging-rules)

* Paths are evaluated relative to the base file. When you use multiple Compose files, you must make sure all paths in the files are relative to the base Compose file (the first Compose file specified with `-f`). This is required because override files need not be valid Compose files. Override files can contain small fragments of configuration. Tracking which fragment of a service is relative to which path is difficult and confusing, so to keep paths easier to understand, all paths must be defined relative to the base file.

  > Tip
  >
  > You can use `docker compose config` to review your merged configuration and avoid path-related issues.

* Compose copies configurations from the original service over to the local one. If a configuration option is defined in both the original service and the local service, the local value replaces or extends the original value.

  * For single-value options like `image`, `command` or `mem_limit`, the new value replaces the old value.

    original service:

    ```yaml
    services:
      myservice:
        # ...
        command: python app.py
    ```

    local service:

    ```yaml
    services:
      myservice:
        # ...
        command: python otherapp.py
    ```

    result:

    ```yaml
    services:
      myservice:
        # ...
        command: python otherapp.py
    ```

  * For the multi-value options `ports`, `expose`, `external_links`, `dns`, `dns_search`, and `tmpfs`, Compose concatenates both sets of values:

    original service:

    ```yaml
    services:
      myservice:
        # ...
        expose:
          - "3000"
    ```

    local service:

    ```yaml
    services:
      myservice:
        # ...
        expose:
          - "4000"
          - "5000"
    ```

    result:

    ```yaml
    services:
      myservice:
        # ...
        expose:
          - "3000"
          - "4000"
          - "5000"
    ```

  * In the case of `environment`, `labels`, `volumes`, and `devices`, Compose "merges" entries together with locally defined values taking precedence. For `environment` and `labels`, the environment variable or label name determines which value is used:

    original service:

    ```yaml
    services:
      myservice:
        # ...
        environment:
          - FOO=original
          - BAR=original
    ```

    local service:

    ```yaml
    services:
      myservice:
        # ...
        environment:
          - BAR=local
          - BAZ=local
    ```

    result:

    ```yaml
    services:
      myservice:
        # ...
        environment:
          - FOO=original
          - BAR=local
          - BAZ=local
    ```

  * Entries for `volumes` and `devices` are merged using the mount path in the container:

    original service:

    ```yaml
    services:
      myservice:
        # ...
        volumes:
          - ./original:/foo
          - ./original:/bar
    ```

    local service:

    ```yaml
    services:
      myservice:
        # ...
        volumes:
          - ./local:/bar
          - ./local:/baz
    ```

    result:

    ```yaml
    services:
      myservice:
        # ...
        volumes:
          - ./original:/foo
          - ./local:/bar
          - ./local:/baz
    ```

For more merging rules, see [Merge and override](https://docs.docker.com/reference/compose-file/merge/) in the Compose Specification.

### [Additional information](#additional-information)

* Using `-f` is optional. If not provided, Compose searches the working directory and its parent directories for a `compose.yaml` and a `compose.override.yaml` file. You must supply at least the `compose.yaml` file. If both files exist on the same directory level, Compose combines them into a single configuration.

* You can use a `-f` with `-` (dash) as the filename to read the configuration from `stdin`. For example:

  ```console
  $ docker compose -f - <<EOF
    webapp:
      image: examples/web
      ports:
       - "8000:8000"
      volumes:
       - "/data"
      environment:
       - DEBUG=1
    EOF
  ```

  When `stdin` is used, all paths in the configuration are relative to the current working directory.

* You can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either from the command line or by setting up a [COMPOSE\_FILE environment variable](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_file) in your shell or in an environment file.

  For example, if you are running the [Compose Rails sample](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/rails/README.md), and have a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like [docker compose pull](/reference/cli/docker/compose/pull/) to get the postgres image for the `db` service from anywhere by using the `-f` flag as follows: `docker compose -f ~/sandbox/rails/compose.yaml pull db`

  Here's the full example:

  ```console
  $ docker compose -f ~/sandbox/rails/compose.yaml pull db
  Pulling db (postgres:18)...
  18: Pulling from library/postgres
  ef0380f84d05: Pull complete
  50cf91dc1db8: Pull complete
  d3add4cd115c: Pull complete
  467830d8a616: Pull complete
  089b9db7dc57: Pull complete
  6fba0a36935c: Pull complete
  81ef0e73c953: Pull complete
  338a6c4894dc: Pull complete
  15853f32f67c: Pull complete
  044c83d92898: Pull complete
  17301519f133: Pull complete
  dcca70822752: Pull complete
  cecf11b8ccf3: Pull complete
  Digest: sha256:1364924c753d5ff7e2260cd34dc4ba05ebd40ee8193391220be0f9901d4e1651
  Status: Downloaded newer image for postgres:18
  ```

## [Example](#example)

A common use case for multiple files is changing a development Compose app for a production-like environment (which may be production, staging or CI). To support these differences, you can split your Compose configuration into a few different files:

Start with a base file that defines the canonical configuration for the services.

`compose.yaml`

```yaml
services:
  web:
    image: example/my_web_app:latest
    depends_on:
      - db
      - cache

  db:
    image: postgres:18

  cache:
    image: redis:latest
```

In this example the development configuration exposes some ports to the host, mounts our code as a volume, and builds the web image.

`compose.override.yaml`

```yaml
services:
  web:
    build: .
    volumes:
      - '.:/code'
    ports:
      - 8883:80
    environment:
      DEBUG: 'true'

  db:
    command: '-d'
    ports:
     - 5432:5432

  cache:
    ports:
      - 6379:6379
```

When you run `docker compose up` it reads the overrides automatically.

To use this Compose app in a production environment, another override file is created, which might be stored in a different git repository or managed by a different team.

`compose.prod.yaml`

```yaml
services:
  web:
    ports:
      - 80:80
    environment:
      PRODUCTION: 'true'

  cache:
    environment:
      TTL: '500'
```

To deploy with this production Compose file you can run

```console
$ docker compose -f compose.yaml -f compose.prod.yaml up -d
```

This deploys all three services using the configuration in `compose.yaml` and `compose.prod.yaml` but not the dev configuration in `compose.override.yaml`.

For more information, see [Using Compose in production](https://docs.docker.com/compose/how-tos/production/).

## [Limitations](#limitations)

Docker Compose supports relative paths for the many resources to be included in the application model: build context for service images, location of file defining environment variables, path to a local directory used in a bind-mounted volume. With such a constraint, code organization in a monorepo can become hard as a natural choice would be to have dedicated folders per team or component, but then the Compose files relative paths become irrelevant.

## [Reference information](#reference-information)

* [Merge rules](https://docs.docker.com/reference/compose-file/merge/)

----
url: https://docs.docker.com/guides/admin-user-management/onboard/
----

# Onboarding and managing roles and permissions in Docker

***

Table of contents

***

This page guides you through onboarding owners and members, and using tools like SSO and SCIM to future-proof onboarding going forward.

## [Invite owners](#invite-owners)

When you create a Docker organization, you automatically become its sole owner. While optional, adding additional owners can significantly ease the process of onboarding and managing your organization by distributing administrative responsibilities. It also ensures continuity and prevents blockers if the primary owner is unavailable.

For detailed information on owners, see [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/).

## [Invite members and assign roles](#invite-members-and-assign-roles)

Members are granted controlled access to resources and enjoy enhanced organizational benefits. When you invite members to join your Docker organization, you immediately assign them a role.

### [Benefits of inviting members](#benefits-of-inviting-members)

* Enhanced visibility: Gain insights into user activity, making it easier to monitor access and enforce security policies.
* Streamlined collaboration: Help members collaborate effectively by granting access to shared resources and repositories.
* Improved resource management: Organize and track users within your organization, ensuring optimal allocation of resources.
* Access to enhanced features: Members benefit from organization-wide perks, such as increased pull limits and access to premium Docker features.
* Security control: Apply and enforce security settings at an organizational level, reducing risks associated with unmanaged accounts.

For detailed information, see [Manage organization members](https://docs.docker.com/admin/organization/manage/members/).

## [Future-proof user management](#future-proof-user-management)

A robust, future-proof approach to user management combines automated provisioning, centralized authentication, and dynamic access control. Implementing these practices ensures a scalable, secure, and efficient environment.

### [Secure user authentication with single sign-on (SSO)](#secure-user-authentication-with-single-sign-on-sso)

Integrating Docker with your identity provider streamlines user access and enhances security.

SSO:

* Simplifies sign in, as users sign in with their organizational credentials.
* Reduces password-related vulnerabilities.
* Simplifies onboarding as it works seamlessly with SCIM and group mapping for automated provisioning.

For more information, see the [SSO documentation](https://docs.docker.com/enterprise/security/single-sign-on/).

### [Automate onboarding with SCIM and JIT provisioning](#automate-onboarding-with-scim-and-jit-provisioning)

Streamline user provisioning and role management with [SCIM](https://docs.docker.com/enterprise/security/provisioning/scim/) and [Just-in-Time (JIT) provisioning](https://docs.docker.com/enterprise/security/provisioning/just-in-time/).

With SCIM you can:

* Sync users and roles automatically with your identity provider.
* Automate adding, updating, or removing users based on directory changes.

With JIT provisioning you can:

* Automatically add users upon first sign in based on [group mapping](#simplify-access-with-group-mapping).
* Reduce overhead by eliminating pre-invite steps.

### [Simplify access with group mapping](#simplify-access-with-group-mapping)

Group mapping automates permissions management by linking identity provider groups to Docker roles and teams.

It also:

* Reduces manual errors in role assignments.
* Ensures consistent access control policies.
* Help you scale permissions as teams grow or change.

For more information on how it works, see [Group mapping](https://docs.docker.com/enterprise/security/provisioning/scim/group-mapping/).

[Monitoring and insights »](https://docs.docker.com/guides/admin-user-management/audit-and-monitor/)

----
url: https://docs.docker.com/ai/sandboxes/agents/copilot/
----

# Copilot

***

Table of contents

***

This guide covers authentication, configuration, and usage of GitHub Copilot in a sandboxed environment.

Official documentation: [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli)

## [Quick start](#quick-start)

Create a sandbox and run Copilot for a project directory:

```console
$ sbx run copilot ~/my-project
```

The workspace parameter is optional and defaults to the current directory:

```console
$ cd ~/my-project
$ sbx run copilot
```

## [Authentication](#authentication)

Copilot requires a GitHub token with Copilot access. Store your token using [stored secrets](https://docs.docker.com/ai/sandboxes/security/credentials/#stored-secrets):

```console
$ echo "$(gh auth token)" | sbx secret set -g github
```

Alternatively, export the `GH_TOKEN` or `GITHUB_TOKEN` environment variable in your shell before running the sandbox. See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for details on both methods.

## [Configuration](#configuration)

Sandboxes don't pick up user-level configuration from your host. Only project-level configuration in the working directory is available inside the sandbox. See [Why doesn't the sandbox use my user-level agent configuration?](https://docs.docker.com/ai/sandboxes/faq/#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for workarounds.

Copilot is configured to trust the workspace directory by default, so it operates without repeated confirmations for workspace files.

### [Default startup command](#default-startup-command)

Without extra args, the sandbox runs:

```text
copilot --yolo
```

Args after `--` replace these defaults rather than being appended. To keep `--yolo`, include it yourself:

```console
$ sbx run copilot -- --yolo -p "review this PR"
```

## [Base image](#base-image)

Template: `docker/sandbox-templates:copilot`

Preconfigured to trust the workspace directory.

----
url: https://docs.docker.com/reference/cli/docker/model/list/
----

# docker model list

***

| Description                                                               | List the models pulled to your local environment |
| ------------------------------------------------------------------------- | ------------------------------------------------ |
| Usage                                                                     | `docker model list [OPTIONS] [MODEL]`            |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker model ls`                                |

## [Description](#description)

List the models pulled to your local environment

## [Options](#options)

| Option        | Default | Description                                            |
| ------------- | ------- | ------------------------------------------------------ |
| `--json`      |         | List models in a JSON format                           |
| `--openai`    |         | List models in an OpenAI format                        |
| `--openaiurl` |         | OpenAI-compatible API endpoint URL to list models from |
| `-q, --quiet` |         | Only show model IDs                                    |

----
url: https://docs.docker.com/reference/cli/docker/trust/key/load/
----

# docker trust key load

***

| Description | Load a private key file for signing       |
| ----------- | ----------------------------------------- |
| Usage       | `docker trust key load [OPTIONS] KEYFILE` |

## [Description](#description)

`docker trust key load` adds private keys to the local Docker trust keystore.

To add a signer to a repository use `docker trust signer add`.

## [Options](#options)

| Option   | Default  | Description             |
| -------- | -------- | ----------------------- |
| `--name` | `signer` | Name for the loaded key |

## [Examples](#examples)

### [Load a single private key](#load-a-single-private-key)

For a private key `alice.pem` with permissions `-rw-------`

```console
$ docker trust key load alice.pem

Loading key from "alice.pem"...
Enter passphrase for new signer key with ID f8097df:
Repeat passphrase for new signer key with ID f8097df:
Successfully imported key from alice.pem
```

To specify a name use the `--name` flag:

```console
$ docker trust key load --name alice-key alice.pem

Loading key from "alice.pem"...
Enter passphrase for new alice-key key with ID f8097df:
Repeat passphrase for new alice-key key with ID f8097df:
Successfully imported key from alice.pem
```

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/remove/
----

# docker mcp catalog remove

***

| Description                                                               | Remove a catalog                            |
| ------------------------------------------------------------------------- | ------------------------------------------- |
| Usage                                                                     | `docker mcp catalog remove <oci-reference>` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker mcp catalog rm`                     |

## [Description](#description)

Remove a catalog

----
url: https://docs.docker.com/engine/swarm/secrets/
----

# Manage sensitive data with Docker secrets

***

Table of contents

***

## [About secrets](#about-secrets)

In terms of Docker Swarm services, a *secret* is a blob of data, such as a password, SSH private key, SSL certificate, or another piece of data that should not be transmitted over a network or stored unencrypted in a Dockerfile or in your application's source code. You can use Docker *secrets* to centrally manage this data and securely transmit it to only those containers that need access to it. Secrets are encrypted during transit and at rest in a Docker swarm. A given secret is only accessible to those services which have been granted explicit access to it, and only while those service tasks are running.

You can use secrets to manage any sensitive data which a container needs at runtime but you don't want to store in the image or in source control, such as:

* Usernames and passwords
* TLS certificates and keys
* SSH keys
* Other important data such as the name of a database or internal server
* Generic strings or binary content (up to 500 kb in size)

> Note
>
> Docker secrets are only available to swarm services, not to standalone containers. To use this feature, consider adapting your container to run as a service. Stateful containers can typically run with a scale of 1 without changing the container code.

Another use case for using secrets is to provide a layer of abstraction between the container and a set of credentials. Consider a scenario where you have separate development, test, and production environments for your application. Each of these environments can have different credentials, stored in the development, test, and production swarms with the same secret name. Your containers only need to know the name of the secret to function in all three environments.

You can also use secrets to manage non-sensitive data, such as configuration files. However, Docker supports the use of [configs](https://docs.docker.com/engine/swarm/configs/) for storing non-sensitive data. Configs are mounted into the container's filesystem directly, without the use of a RAM disk.

### [Windows support](#windows-support)

Docker includes support for secrets on Windows containers. Where there are differences in the implementations, they are called out in the examples below. Keep the following notable differences in mind:

* Microsoft Windows has no built-in driver for managing RAM disks, so within running Windows containers, secrets are persisted in clear text to the container's root disk. However, the secrets are explicitly removed when a container stops. In addition, Windows does not support persisting a running container as an image using `docker commit` or similar commands.

* On Windows, we recommend enabling [BitLocker](https://technet.microsoft.com/en-us/library/cc732774%28v=ws.11%29.aspx) on the volume containing the Docker root directory on the host machine to ensure that secrets for running containers are encrypted at rest.

* Secret files with custom targets are not directly bind-mounted into Windows containers, since Windows does not support non-directory file bind-mounts. Instead, secrets for a container are all mounted in `C:\ProgramData\Docker\internal\secrets` (an implementation detail which should not be relied upon by applications) within the container. Symbolic links are used to point from there to the desired target of the secret within the container. The default target is `C:\ProgramData\Docker\secrets`.

* When creating a service which uses Windows containers, the options to specify UID, GID, and mode are not supported for secrets. Secrets are currently only accessible by administrators and users with `system` access within the container.

## [How Docker manages secrets](#how-docker-manages-secrets)

When you add a secret to the swarm, Docker sends the secret to the swarm manager over a mutual TLS connection. The secret is stored in the Raft log, which is encrypted. The entire Raft log is replicated across the other managers, ensuring the same high availability guarantees for secrets as for the rest of the swarm management data.

When you grant a newly-created or running service access to a secret, the decrypted secret is mounted into the container in an in-memory filesystem. The location of the mount point within the container defaults to `/run/secrets/<secret_name>` in Linux containers, or `C:\ProgramData\Docker\secrets` in Windows containers. You can also specify a custom location.

You can update a service to grant it access to additional secrets or revoke its access to a given secret at any time.

A node only has access to (encrypted) secrets if the node is a swarm manager or if it is running service tasks which have been granted access to the secret. When a container task stops running, the decrypted secrets shared to it are unmounted from the in-memory filesystem for that container and flushed from the node's memory.

If a node loses connectivity to the swarm while it is running a task container with access to a secret, the task container still has access to its secrets, but cannot receive updates until the node reconnects to the swarm.

You can add or inspect an individual secret at any time, or list all secrets. You cannot remove a secret that a running service is using. See [Rotate a secret](https://docs.docker.com/engine/swarm/secrets/#example-rotate-a-secret) for a way to remove a secret without disrupting running services.

To update or roll back secrets more easily, consider adding a version number or date to the secret name. This is made easier by the ability to control the mount point of the secret within a given container.

## [Read more about `docker secret` commands](#read-more-about-docker-secret-commands)

Use these links to read about specific commands, or continue to the [example about using secrets with a service](https://docs.docker.com/engine/swarm/secrets/#simple-example-get-started-with-secrets).

* [`docker secret create`](/reference/cli/docker/secret/create/)
* [`docker secret inspect`](/reference/cli/docker/secret/inspect/)
* [`docker secret ls`](/reference/cli/docker/secret/ls/)
* [`docker secret rm`](/reference/cli/docker/secret/rm/)
* [`--secret`](/reference/cli/docker/service/create/#secret) flag for `docker service create`
* [`--secret-add` and `--secret-rm`](/reference/cli/docker/service/update/#secret-add) flags for `docker service update`

## [Examples](#examples)

This section includes three graduated examples which illustrate how to use Docker secrets. The images used in these examples have been updated to make it easier to use Docker secrets. To find out how to modify your own images in a similar way, see [Build support for Docker Secrets into your images](#build-support-for-docker-secrets-into-your-images).

> Note
>
> These examples use a single-Engine swarm and unscaled services for simplicity. The examples use Linux containers, but Windows containers also support secrets. See [Windows support](#windows-support).

### [Defining and using secrets in compose files](#defining-and-using-secrets-in-compose-files)

Both the `docker-compose` and `docker stack` commands support defining secrets in a compose file. See [the Compose file reference](https://docs.docker.com/reference/compose-file/legacy-versions/) for details.

### [Simple example: Get started with secrets](#simple-example-get-started-with-secrets)

This simple example shows how secrets work in just a few commands. For a real-world example, continue to [Intermediate example: Use secrets with a Nginx service](#intermediate-example-use-secrets-with-a-nginx-service).

1. Add a secret to Docker. The `docker secret create` command reads standard input because the last argument, which represents the file to read the secret from, is set to `-`.

   ```console
   $ printf "This is a secret" | docker secret create my_secret_data -
   ```

2. Create a `redis` service and grant it access to the secret. By default, the container can access the secret at `/run/secrets/<secret_name>`, but you can customize the file name on the container using the `target` option.

   ```console
   $ docker service  create --name redis --secret my_secret_data redis:alpine
   ```

3. Verify that the task is running without issues using `docker service ps`. If everything is working, the output looks similar to this:

   ```console
   $ docker service ps redis

   ID            NAME     IMAGE         NODE              DESIRED STATE  CURRENT STATE          ERROR  PORTS
   bkna6bpn8r1a  redis.1  redis:alpine  ip-172-31-46-109  Running        Running 8 seconds ago  
   ```

   If there were an error, and the task were failing and repeatedly restarting, you would see something like this:

   ```console
   $ docker service ps redis

   NAME                      IMAGE         NODE  DESIRED STATE  CURRENT STATE          ERROR                      PORTS
   redis.1.siftice35gla      redis:alpine  moby  Running        Running 4 seconds ago                             
    \_ redis.1.whum5b7gu13e  redis:alpine  moby  Shutdown       Failed 20 seconds ago      "task: non-zero exit (1)"  
    \_ redis.1.2s6yorvd9zow  redis:alpine  moby  Shutdown       Failed 56 seconds ago      "task: non-zero exit (1)"  
    \_ redis.1.ulfzrcyaf6pg  redis:alpine  moby  Shutdown       Failed about a minute ago  "task: non-zero exit (1)"  
    \_ redis.1.wrny5v4xyps6  redis:alpine  moby  Shutdown       Failed 2 minutes ago       "task: non-zero exit (1)"
   ```

4. Get the ID of the `redis` service task container using `docker ps` , so that you can use `docker container exec` to connect to the container and read the contents of the secret data file, which defaults to being readable by all and has the same name as the name of the secret. The first command below illustrates how to find the container ID, and the second and third commands use shell completion to do this automatically.

   ```console
   $ docker ps --filter name=redis -q

   5cb1c2348a59

   $ docker container exec $(docker ps --filter name=redis -q) ls -l /run/secrets

   total 4
   -r--r--r--    1 root     root            17 Dec 13 22:48 my_secret_data

   $ docker container exec $(docker ps --filter name=redis -q) cat /run/secrets/my_secret_data

   This is a secret
   ```

5. Verify that the secret is not available if you commit the container.

   ```console
   $ docker commit $(docker ps --filter name=redis -q) committed_redis

   $ docker run --rm -it committed_redis cat /run/secrets/my_secret_data

   cat: can't open '/run/secrets/my_secret_data': No such file or directory
   ```

6. Try removing the secret. The removal fails because the `redis` service is running and has access to the secret.

   ```console
   $ docker secret ls

   ID                          NAME                CREATED             UPDATED
   wwwrxza8sxy025bas86593fqs   my_secret_data      4 hours ago         4 hours ago


   $ docker secret rm my_secret_data

   Error response from daemon: rpc error: code = 3 desc = secret
   'my_secret_data' is in use by the following service: redis
   ```

7. Remove access to the secret from the running `redis` service by updating the service.

   ```console
   $ docker service update --secret-rm my_secret_data redis
   ```

8. Repeat steps 3 and 4 again, verifying that the service no longer has access to the secret. The container ID is different, because the `service update` command redeploys the service.

   ```console
   $ docker container exec -it $(docker ps --filter name=redis -q) cat /run/secrets/my_secret_data

   cat: can't open '/run/secrets/my_secret_data': No such file or directory
   ```

9. Stop and remove the service, and remove the secret from Docker.

   ```console
   $ docker service rm redis

   $ docker secret rm my_secret_data
   ```

### [Simple example: Use secrets in a Windows service](#simple-example-use-secrets-in-a-windows-service)

This is a very simple example which shows how to use secrets with a Microsoft IIS service running on Docker for Windows running Windows containers on Microsoft Windows 10. It is a naive example that stores the webpage in a secret.

This example assumes that you have PowerShell installed.

1. Save the following into a new file `index.html`.

   ```html
   <html lang="en">
     <head><title>Hello Docker</title></head>
     <body>
       <p>Hello Docker! You have deployed a HTML page.</p>
     </body>
   </html>
   ```

2. If you have not already done so, initialize or join the swarm.

   ```console
   > docker swarm init
   ```

3. Save the `index.html` file as a swarm secret named `homepage`.

   ```console
   > docker secret create homepage index.html
   ```

4. Create an IIS service and grant it access to the `homepage` secret.

   ```console
   > docker service create `
       --name my-iis `
       --publish published=8000,target=8000 `
       --secret src=homepage,target="\inetpub\wwwroot\index.html" `
       microsoft/iis:nanoserver
   ```

   > Note
   >
   > There is technically no reason to use secrets for this example; [configs](https://docs.docker.com/engine/swarm/configs/) are a better fit. This example is for illustration only.

5. Access the IIS service at `http://localhost:8000/`. It should serve the HTML content from the first step.

6. Remove the service and the secret.

   ```console
   > docker service rm my-iis
   > docker secret rm homepage
   > docker image remove secret-test
   ```

### [Intermediate example: Use secrets with a Nginx service](#intermediate-example-use-secrets-with-a-nginx-service)

This example is divided into two parts. [The first part](#generate-the-site-certificate) is all about generating the site certificate and does not directly involve Docker secrets at all, but it sets up [the second part](#configure-the-nginx-container), where you store and use the site certificate and Nginx configuration as secrets.

#### [Generate the site certificate](#generate-the-site-certificate)

Generate a root CA and TLS certificate and key for your site. For production sites, you may want to use a service such as `Let’s Encrypt` to generate the TLS certificate and key, but this example uses command-line tools. This step is a little complicated, but is only a set-up step so that you have something to store as a Docker secret. If you want to skip these sub-steps, you can [use Let's Encrypt](https://letsencrypt.org/getting-started/) to generate the site key and certificate, name the files `site.key` and `site.crt`, and skip to [Configure the Nginx container](#configure-the-nginx-container).

1. Generate a root key.

   ```console
   $ openssl genrsa -out "root-ca.key" 4096
   ```

2. Generate a CSR using the root key.

   ```console
   $ openssl req \
             -new -key "root-ca.key" \
             -out "root-ca.csr" -sha256 \
             -subj '/C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA'
   ```

3. Configure the root CA. Edit a new file called `root-ca.cnf` and paste the following contents into it. This constrains the root CA to signing leaf certificates and not intermediate CAs.

   ```ini
   [root_ca]
   basicConstraints = critical,CA:TRUE,pathlen:1
   keyUsage = critical, nonRepudiation, cRLSign, keyCertSign
   subjectKeyIdentifier=hash
   ```

4. Sign the certificate.

   ```console
   $ openssl x509 -req  -days 3650  -in "root-ca.csr" \
                  -signkey "root-ca.key" -sha256 -out "root-ca.crt" \
                  -extfile "root-ca.cnf" -extensions \
                  root_ca
   ```

5. Generate the site key.

   ```console
   $ openssl genrsa -out "site.key" 4096
   ```

6. Generate the site certificate and sign it with the site key.

   ```console
   $ openssl req -new -key "site.key" -out "site.csr" -sha256 \
             -subj '/C=US/ST=CA/L=San Francisco/O=Docker/CN=localhost'
   ```

7. Configure the site certificate. Edit a new file called `site.cnf` and paste the following contents into it. This constrains the site certificate so that it can only be used to authenticate a server and can't be used to sign certificates.

   ```ini
   [server]
   authorityKeyIdentifier=keyid,issuer
   basicConstraints = critical,CA:FALSE
   extendedKeyUsage=serverAuth
   keyUsage = critical, digitalSignature, keyEncipherment
   subjectAltName = DNS:localhost, IP:127.0.0.1
   subjectKeyIdentifier=hash
   ```

8. Sign the site certificate.

   ```console
   $ openssl x509 -req -days 750 -in "site.csr" -sha256 \
       -CA "root-ca.crt" -CAkey "root-ca.key"  -CAcreateserial \
       -out "site.crt" -extfile "site.cnf" -extensions server
   ```

9. The `site.csr` and `site.cnf` files are not needed by the Nginx service, but you need them if you want to generate a new site certificate. Protect the `root-ca.key` file.

#### [Configure the Nginx container](#configure-the-nginx-container)

1. Produce a very basic Nginx configuration that serves static files over HTTPS. The TLS certificate and key are stored as Docker secrets so that they can be rotated easily.

   In the current directory, create a new file called `site.conf` with the following contents:

   ```nginx
   server {
       listen                443 ssl;
       server_name           localhost;
       ssl_certificate       /run/secrets/site.crt;
       ssl_certificate_key   /run/secrets/site.key;

       location / {
           root   /usr/share/nginx/html;
           index  index.html index.htm;
       }
   }
   ```

2. Create three secrets, representing the key, the certificate, and the `site.conf`. You can store any file as a secret as long as it is smaller than 500 KB. This allows you to decouple the key, certificate, and configuration from the services that use them. In each of these commands, the last argument represents the path to the file to read the secret from on the host machine's filesystem. In these examples, the secret name and the file name are the same.

   ```console
   $ docker secret create site.key site.key

   $ docker secret create site.crt site.crt

   $ docker secret create site.conf site.conf
   ```

   ```console
   $ docker secret ls

   ID                          NAME                  CREATED             UPDATED
   2hvoi9mnnaof7olr3z5g3g7fp   site.key       58 seconds ago      58 seconds ago
   aya1dh363719pkiuoldpter4b   site.crt       24 seconds ago      24 seconds ago
   zoa5df26f7vpcoz42qf2csth8   site.conf      11 seconds ago      11 seconds ago
   ```

3. Create a service that runs Nginx and has access to the three secrets. The last part of the `docker service create` command creates a symbolic link from the location of the `site.conf` secret to `/etc/nginx.conf.d/`, where Nginx looks for extra configuration files. This step happens before Nginx actually starts, so you don't need to rebuild your image if you change the Nginx configuration.

   > Note
   >
   > Normally you would create a Dockerfile which copies the `site.conf` into place, build the image, and run a container using your custom image. This example does not require a custom image. It puts the `site.conf` into place and runs the container all in one step.

   Secrets are located within the `/run/secrets/` directory in the container by default, which may require extra steps in the container to make the secret available in a different path. The example below creates a symbolic link to the true location of the `site.conf` file so that Nginx can read it:

   ```console
   $ docker service create \
        --name nginx \
        --secret site.key \
        --secret site.crt \
        --secret site.conf \
        --publish published=3000,target=443 \
        nginx:latest \
        sh -c "ln -s /run/secrets/site.conf /etc/nginx/conf.d/site.conf && exec nginx -g 'daemon off;'"
   ```

   Instead of creating symlinks, secrets allow you to specify a custom location using the `target` option. The example below illustrates how the `site.conf` secret is made available at `/etc/nginx/conf.d/site.conf` inside the container without the use of symbolic links:

   ```console
   $ docker service create \
        --name nginx \
        --secret site.key \
        --secret site.crt \
        --secret source=site.conf,target=/etc/nginx/conf.d/site.conf \
        --publish published=3000,target=443 \
        nginx:latest \
        sh -c "exec nginx -g 'daemon off;'"
   ```

   The `site.key` and `site.crt` secrets use the short-hand syntax, without a custom `target` location set. The short syntax mounts the secrets in \`/run/secrets/ with the same name as the secret. Within the running containers, the following three files now exist:

   * `/run/secrets/site.key`
   * `/run/secrets/site.crt`
   * `/etc/nginx/conf.d/site.conf`

4. Verify that the Nginx service is running.

   ```console
   $ docker service ls

   ID            NAME   MODE        REPLICAS  IMAGE
   zeskcec62q24  nginx  replicated  1/1       nginx:latest

   $ docker service ps nginx

   NAME                  IMAGE         NODE  DESIRED STATE  CURRENT STATE          ERROR  PORTS
   nginx.1.9ls3yo9ugcls  nginx:latest  moby  Running        Running 3 minutes ago
   ```

5. Verify that the service is operational: you can reach the Nginx server, and that the correct TLS certificate is being used.

   ```console
   $ curl --cacert root-ca.crt https://localhost:3000

   <!DOCTYPE html>
   <html>
   <head>
   <title>Welcome to nginx!</title>
   <style>
       body {
           width: 35em;
           margin: 0 auto;
           font-family: Tahoma, Verdana, Arial, sans-serif;
       }
   </style>
   </head>
   <body>
   <h1>Welcome to nginx!</h1>
   <p>If you see this page, the nginx web server is successfully installed and
   working. Further configuration is required.</p>

   <p>For online documentation and support. refer to
   <a href="https://nginx.org">nginx.org</a>.<br/>
   Commercial support is available at
   <a href="https://www.nginx.com">nginx.com</a>.</p>

   <p><em>Thank you for using nginx.</em></p>
   </body>
   </html>
   ```

   ```console
   $ openssl s_client -connect localhost:3000 -CAfile root-ca.crt

   CONNECTED(00000003)
   depth=1 /C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA
   verify return:1
   depth=0 /C=US/ST=CA/L=San Francisco/O=Docker/CN=localhost
   verify return:1
   ---
   Certificate chain
    0 s:/C=US/ST=CA/L=San Francisco/O=Docker/CN=localhost
      i:/C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA
   ---
   Server certificate
   -----BEGIN CERTIFICATE-----
   …
   -----END CERTIFICATE-----
   subject=/C=US/ST=CA/L=San Francisco/O=Docker/CN=localhost
   issuer=/C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA
   ---
   No client certificate CA names sent
   ---
   SSL handshake has read 1663 bytes and written 712 bytes
   ---
   New, TLSv1/SSLv3, Cipher is AES256-SHA
   Server public key is 4096 bit
   Secure Renegotiation IS supported
   Compression: NONE
   Expansion: NONE
   SSL-Session:
       Protocol  : TLSv1
       Cipher    : AES256-SHA
       Session-ID: A1A8BF35549C5715648A12FD7B7E3D861539316B03440187D9DA6C2E48822853
       Session-ID-ctx:
       Master-Key: F39D1B12274BA16D3A906F390A61438221E381952E9E1E05D3DD784F0135FB81353DA38C6D5C021CB926E844DFC49FC4
       Key-Arg   : None
       Start Time: 1481685096
       Timeout   : 300 (sec)
       Verify return code: 0 (ok)
   ```

6. To clean up after running this example, remove the `nginx` service and the stored secrets.

   ```console
   $ docker service rm nginx

   $ docker secret rm site.crt site.key site.conf
   ```

### [Advanced example: Use secrets with a WordPress service](#advanced-example-use-secrets-with-a-wordpress-service)

In this example, you create a single-node MySQL service with a custom root password, add the credentials as secrets, and create a single-node WordPress service which uses these credentials to connect to MySQL. The [next example](#example-rotate-a-secret) builds on this one and shows you how to rotate the MySQL password and update the services so that the WordPress service can still connect to MySQL.

This example illustrates some techniques to use Docker secrets to avoid saving sensitive credentials within your image or passing them directly on the command line.

> Note
>
> This example uses a single-Engine swarm for simplicity, and uses a single-node MySQL service because a single MySQL server instance cannot be scaled by simply using a replicated service, and setting up a MySQL cluster is beyond the scope of this example.
>
> Also, changing a MySQL root passphrase isn’t as simple as changing a file on disk. You must use a query or a `mysqladmin` command to change the password in MySQL.

1. Generate a random alphanumeric password for MySQL and store it as a Docker secret with the name `mysql_password` using the `docker secret create` command. To make the password shorter or longer, adjust the last argument of the `openssl` command. This is just one way to create a relatively random password. You can use another command to generate the password if you choose.

   > Note
   >
   > After you create a secret, you cannot update it. You can only remove and re-create it, and you cannot remove a secret that a service is using. However, you can grant or revoke a running service's access to secrets using `docker service update`. If you need the ability to update a secret, consider adding a version component to the secret name, so that you can later add a new version, update the service to use it, then remove the old version.

   The last argument is set to `-`, which indicates that the input is read from standard input.

   ```console
   $ openssl rand -base64 20 | docker secret create mysql_password -

   l1vinzevzhj4goakjap5ya409
   ```

   The value returned is not the password, but the ID of the secret. In the remainder of this tutorial, the ID output is omitted.

   Generate a second secret for the MySQL `root` user. This secret isn't shared with the WordPress service created later. It's only needed to bootstrap the `mysql` service.

   ```console
   $ openssl rand -base64 20 | docker secret create mysql_root_password -
   ```

   List the secrets managed by Docker using `docker secret ls`:

   ```console
   $ docker secret ls

   ID                          NAME                  CREATED             UPDATED
   l1vinzevzhj4goakjap5ya409   mysql_password        41 seconds ago      41 seconds ago
   yvsczlx9votfw3l0nz5rlidig   mysql_root_password   12 seconds ago      12 seconds ago
   ```

   The secrets are stored in the encrypted Raft logs for the swarm.

2. Create a user-defined overlay network which is used for communication between the MySQL and WordPress services. There is no need to expose the MySQL service to any external host or container.

   ```console
   $ docker network create -d overlay mysql_private
   ```

3. Create the MySQL service. The MySQL service has the following characteristics:

   * Because the scale is set to `1`, only a single MySQL task runs. Load-balancing MySQL is left as an exercise to the reader and involves more than just scaling the service.

   * Only reachable by other containers on the `mysql_private` network.

   * Uses the volume `mydata` to store the MySQL data, so that it persists across restarts to the `mysql` service.

   * The secrets are each mounted in a `tmpfs` filesystem at `/run/secrets/mysql_password` and `/run/secrets/mysql_root_password`. They are never exposed as environment variables, nor can they be committed to an image if the `docker commit` command is run. The `mysql_password` secret is the one used by the non-privileged WordPress container to connect to MySQL.

   * Sets the environment variables `MYSQL_PASSWORD_FILE` and `MYSQL_ROOT_PASSWORD_FILE` to point to the files `/run/secrets/mysql_password` and `/run/secrets/mysql_root_password`. The `mysql` image reads the password strings from those files when initializing the system database for the first time. Afterward, the passwords are stored in the MySQL system database itself.

   * Sets environment variables `MYSQL_USER` and `MYSQL_DATABASE`. A new database called `wordpress` is created when the container starts, and the `wordpress` user has full permissions for this database only. This user cannot create or drop databases or change the MySQL configuration.

     ```console
     $ docker service create \
          --name mysql \
          --replicas 1 \
          --network mysql_private \
          --mount type=volume,source=mydata,destination=/var/lib/mysql \
          --secret source=mysql_root_password,target=mysql_root_password \
          --secret source=mysql_password,target=mysql_password \
          -e MYSQL_ROOT_PASSWORD_FILE="/run/secrets/mysql_root_password" \
          -e MYSQL_PASSWORD_FILE="/run/secrets/mysql_password" \
          -e MYSQL_USER="wordpress" \
          -e MYSQL_DATABASE="wordpress" \
          mysql:latest
     ```

4. Verify that the `mysql` container is running using the `docker service ls` command.

   ```console
   $ docker service ls

   ID            NAME   MODE        REPLICAS  IMAGE
   wvnh0siktqr3  mysql  replicated  1/1       mysql:latest
   ```

5. Now that MySQL is set up, create a WordPress service that connects to the MySQL service. The WordPress service has the following characteristics:

   * Because the scale is set to `1`, only a single WordPress task runs. Load-balancing WordPress is left as an exercise to the reader, because of limitations with storing WordPress session data on the container filesystem.
   * Exposes WordPress on port 30000 of the host machine, so that you can access it from external hosts. You can expose port 80 instead if you do not have a web server running on port 80 of the host machine.
   * Connects to the `mysql_private` network so it can communicate with the `mysql` container, and also publishes port 80 to port 30000 on all swarm nodes.
   * Has access to the `mysql_password` secret, but specifies a different target file name within the container. The WordPress container uses the mount point `/run/secrets/wp_db_password`.
   * Sets the environment variable `WORDPRESS_DB_PASSWORD_FILE` to the file path where the secret is mounted. The WordPress service reads the MySQL password string from that file and add it to the `wp-config.php` configuration file.
   * Connects to the MySQL container using the username `wordpress` and the password in `/run/secrets/wp_db_password` and creates the `wordpress` database if it does not yet exist.
   * Stores its data, such as themes and plugins, in a volume called `wpdata` so these files persist when the service restarts.

   ```console
   $ docker service create \
        --name wordpress \
        --replicas 1 \
        --network mysql_private \
        --publish published=30000,target=80 \
        --mount type=volume,source=wpdata,destination=/var/www/html \
        --secret source=mysql_password,target=wp_db_password \
        -e WORDPRESS_DB_USER="wordpress" \
        -e WORDPRESS_DB_PASSWORD_FILE="/run/secrets/wp_db_password" \
        -e WORDPRESS_DB_HOST="mysql:3306" \
        -e WORDPRESS_DB_NAME="wordpress" \
        wordpress:latest
   ```

6. Verify the service is running using `docker service ls` and `docker service ps` commands.

   ```console
   $ docker service ls

   ID            NAME       MODE        REPLICAS  IMAGE
   wvnh0siktqr3  mysql      replicated  1/1       mysql:latest
   nzt5xzae4n62  wordpress  replicated  1/1       wordpress:latest
   ```

   ```console
   $ docker service ps wordpress

   ID            NAME         IMAGE             NODE  DESIRED STATE  CURRENT STATE           ERROR  PORTS
   aukx6hgs9gwc  wordpress.1  wordpress:latest  moby  Running        Running 52 seconds ago   
   ```

   At this point, you could actually revoke the WordPress service's access to the `mysql_password` secret, because WordPress has copied the secret to its configuration file `wp-config.php`. Don't do that for now, because we use it later to facilitate rotating the MySQL password.

7. Access `http://localhost:30000/` from any swarm node and set up WordPress using the web-based wizard. All of these settings are stored in the MySQL `wordpress` database. WordPress automatically generates a password for your WordPress user, which is completely different from the password WordPress uses to access MySQL. Store this password securely, such as in a password manager. You need it to log into WordPress after [rotating the secret](#example-rotate-a-secret).

   Go ahead and write a blog post or two and install a WordPress plugin or theme to verify that WordPress is fully operational and its state is saved across service restarts.

8. Do not clean up any services or secrets if you intend to proceed to the next example, which demonstrates how to rotate the MySQL root password.

### [Example: Rotate a secret](#example-rotate-a-secret)

This example builds upon the previous one. In this scenario, you create a new secret with a new MySQL password, update the `mysql` and `wordpress` services to use it, then remove the old secret.

> Note
>
> Changing the password on a MySQL database involves running extra queries or commands, as opposed to just changing a single environment variable or a file, since the image only sets the MySQL password if the database doesn’t already exist, and MySQL stores the password within a MySQL database by default. Rotating passwords or other secrets may involve additional steps outside of Docker.

1. Create the new password and store it as a secret named `mysql_password_v2`.

   ```console
   $ openssl rand -base64 20 | docker secret create mysql_password_v2 -
   ```

2. Update the MySQL service to give it access to both the old and new secrets. Remember that you cannot update or rename a secret, but you can revoke a secret and grant access to it using a new target filename.

   ```console
   $ docker service update \
        --secret-rm mysql_password mysql

   $ docker service update \
        --secret-add source=mysql_password,target=old_mysql_password \
        --secret-add source=mysql_password_v2,target=mysql_password \
        mysql
   ```

   Updating a service causes it to restart, and when the MySQL service restarts the second time, it has access to the old secret under `/run/secrets/old_mysql_password` and the new secret under `/run/secrets/mysql_password`.

   Even though the MySQL service has access to both the old and new secrets now, the MySQL password for the WordPress user has not yet been changed.

   > Note
   >
   > This example does not rotate the MySQL `root` password.

3. Now, change the MySQL password for the `wordpress` user using the `mysqladmin` CLI. This command reads the old and new password from the files in `/run/secrets` but does not expose them on the command line or save them in the shell history.

   Do this quickly and move on to the next step, because WordPress loses the ability to connect to MySQL.

   First, find the ID of the `mysql` container task.

   ```console
   $ docker ps --filter name=mysql -q

   c7705cf6176f
   ```

   Substitute the ID in the command below, or use the second variant which uses shell expansion to do it all in a single step.

   ```console
   $ docker container exec CONTAINER_ID \
       bash -c 'mysqladmin --user=wordpress --password="$(< /run/secrets/old_mysql_password)" password "$(< /run/secrets/mysql_password)"'
   ```

   Or:

   ```console
   $ docker container exec $(docker ps --filter name=mysql -q) \
       bash -c 'mysqladmin --user=wordpress --password="$(< /run/secrets/old_mysql_password)" password "$(< /run/secrets/mysql_password)"'
   ```

4. Update the `wordpress` service to use the new password, keeping the target path at `/run/secrets/wp_db_password`. This triggers a rolling restart of the WordPress service and the new secret is used.

   ```console
   $ docker service update \
        --secret-rm mysql_password \
        --secret-add source=mysql_password_v2,target=wp_db_password \
        wordpress    
   ```

5. Verify that WordPress works by browsing to http\://localhost:30000/ on any swarm node again. Use the WordPress username and password from when you ran through the WordPress wizard in the previous task.

   Verify that the blog post you wrote still exists, and if you changed any configuration values, verify that they are still changed.

6. Revoke access to the old secret from the MySQL service and remove the old secret from Docker.

   ```console
   $ docker service update \
        --secret-rm mysql_password \
        mysql

   $ docker secret rm mysql_password
   ```

7. Run the following commands to remove the WordPress service, the MySQL container, the `mydata` and `wpdata` volumes, and the Docker secrets:

   ```console
   $ docker service rm wordpress mysql

   $ docker volume rm mydata wpdata

   $ docker secret rm mysql_password_v2 mysql_root_password
   ```

## [Build support for Docker Secrets into your images](#build-support-for-docker-secrets-into-your-images)

If you develop a container that can be deployed as a service and requires sensitive data, such as a credential, as an environment variable, consider adapting your image to take advantage of Docker secrets. One way to do this is to ensure that each parameter you pass to the image when creating the container can also be read from a file.

Many of the Docker Official Images in the [Docker library](https://github.com/docker-library/), such as the [wordpress](https://github.com/docker-library/wordpress/) image used in the above examples, have been updated in this way.

When you start a WordPress container, you provide it with the parameters it needs by setting them as environment variables. The WordPress image has been updated so that the environment variables which contain important data for WordPress, such as `WORDPRESS_DB_PASSWORD`, also have variants which can read their values from a file (`WORDPRESS_DB_PASSWORD_FILE`). This strategy ensures that backward compatibility is preserved, while allowing your container to read the information from a Docker-managed secret instead of being passed directly.

> Note
>
> Docker secrets do not set environment variables directly. This was a conscious decision, because environment variables can unintentionally be leaked between containers (for instance, if you use `--link`).

## [Use Secrets in Compose](#use-secrets-in-compose)

```yaml

services:
   db:
     image: mysql:latest
     volumes:
       - db_data:/var/lib/mysql
     environment:
       MYSQL_ROOT_PASSWORD_FILE: /run/secrets/db_root_password
       MYSQL_DATABASE: wordpress
       MYSQL_USER: wordpress
       MYSQL_PASSWORD_FILE: /run/secrets/db_password
     secrets:
       - db_root_password
       - db_password

   wordpress:
     depends_on:
       - db
     image: wordpress:latest
     ports:
       - "8000:80"
     environment:
       WORDPRESS_DB_HOST: db:3306
       WORDPRESS_DB_USER: wordpress
       WORDPRESS_DB_PASSWORD_FILE: /run/secrets/db_password
     secrets:
       - db_password


secrets:
   db_password:
     file: db_password.txt
   db_root_password:
     file: db_root_password.txt

volumes:
    db_data:
```

This example creates a simple WordPress site using two secrets in a Compose file.

The top-level element `secrets` defines two secrets `db_password` and `db_root_password`.

When deploying, Docker creates these two secrets and populates them with the content from the file specified in the Compose file.

The `db` service uses both secrets, and `wordpress` is using one.

When you deploy, Docker mounts a file under `/run/secrets/<secret_name>` in the services. These files are never persisted on disk, but are managed in memory.

Each service uses environment variables to specify where the service should look for that secret data.

More information on short and long syntax for secrets can be found in the [Compose Specification](https://docs.docker.com/reference/compose-file/secrets/).

----
url: https://docs.docker.com/reference/cli/docker/swarm/
----

# docker swarm

***

| Description | Manage Swarm   |
| ----------- | -------------- |
| Usage       | `docker swarm` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Manage the swarm.

## [Subcommands](#subcommands)

| Command                                                                                     | Description                           |
| ------------------------------------------------------------------------------------------- | ------------------------------------- |
| [`docker swarm ca`](https://docs.docker.com/reference/cli/docker/swarm/ca/)                 | Display and rotate the root CA        |
| [`docker swarm init`](https://docs.docker.com/reference/cli/docker/swarm/init/)             | Initialize a swarm                    |
| [`docker swarm join`](https://docs.docker.com/reference/cli/docker/swarm/join/)             | Join a swarm as a node and/or manager |
| [`docker swarm join-token`](https://docs.docker.com/reference/cli/docker/swarm/join-token/) | Manage join tokens                    |
| [`docker swarm leave`](https://docs.docker.com/reference/cli/docker/swarm/leave/)           | Leave the swarm                       |
| [`docker swarm unlock`](https://docs.docker.com/reference/cli/docker/swarm/unlock/)         | Unlock swarm                          |
| [`docker swarm unlock-key`](https://docs.docker.com/reference/cli/docker/swarm/unlock-key/) | Manage the unlock key                 |
| [`docker swarm update`](https://docs.docker.com/reference/cli/docker/swarm/update/)         | Update the swarm                      |

----
url: https://docs.docker.com/guides/docker-build-cloud/dev/
----

# Demo: set up and use Docker Build Cloud in development

***

***

With Docker Build Cloud, you can easily shift the build workload from local machines to the cloud, helping you achieve faster build times, especially for multi-platform builds.

In this demo, you'll see:

* How to setup the builder locally
* How to use Docker Build Cloud with Docker Compose
* How the image cache speeds up builds for others on your team

[Demo: Using Docker Build Cloud in CI »](https://docs.docker.com/guides/docker-build-cloud/ci/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/history/open/
----

# docker buildx history open

***

| Description | Open a build record in Docker Desktop        |
| ----------- | -------------------------------------------- |
| Usage       | `docker buildx history open [OPTIONS] [REF]` |

## [Description](#description)

Open a build record in Docker Desktop for visual inspection. This requires Docker Desktop to be installed and running on the host machine.

## [Examples](#examples)

### [Open the most recent build in Docker Desktop](#open-the-most-recent-build-in-docker-desktop)

```console
docker buildx history open
```

By default, this opens the most recent build on the current builder.

### [Open a specific build](#open-a-specific-build)

```console
# Using a build ID
docker buildx history open qu2gsuo8ejqrwdfii23xkkckt

# Or using a relative offset
docker buildx history open ^1
```

----
url: https://docs.docker.com/reference/cli/docker/system/info/
----

# docker system info

***

| Description                                                               | Display system-wide information |
| ------------------------------------------------------------------------- | ------------------------------- |
| Usage                                                                     | `docker system info [OPTIONS]`  |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker info`                   |

## [Description](#description)

This command displays system wide information regarding the Docker installation. Information displayed includes the kernel version, number of containers and images. The number of images shown is the number of unique images. The same image tagged under different names is counted only once.

If a format is specified, the given template will be executed instead of the default format. Go's [text/template](https://pkg.go.dev/text/template) package describes all the details of the format.

Depending on the storage driver in use, additional information can be shown, such as pool name, data file, metadata file, data space used, total data space, metadata space used, and total metadata space.

The data file is where the images are stored and the metadata file is where the meta data regarding those images are stored. When run for the first time Docker allocates a certain amount of data space and meta data space from the space available on the volume where `/var/lib/docker` is mounted.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                             |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --format`](#format) |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |

## [Examples](#examples)

### [Show output](#show-output)

The example below shows the output for a daemon running on Ubuntu Linux, using the `overlay2` storage driver. As can be seen in the output, additional information about the `overlay2` storage driver is shown:

```console
$ docker info

Client:
 Version:    25.0.0
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.12.1
    Path:     /usr/local/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v2.24.1
    Path:     /usr/local/libexec/docker/cli-plugins/docker-compose

Server:
 Containers: 14
  Running: 3
  Paused: 1
  Stopped: 10
 Images: 52
 Server Version: 25.0.0
 Storage Driver: overlayfs
  driver-type: io.containerd.snapshotter.v1
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 CDI spec directories:
  /etc/cdi
  /var/run/cdi
 Swarm: inactive
 Runtimes: runc io.containerd.runc.v2
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: 71909c1814c544ac47ab91d2e8b84718e517bb99
 runc version: v1.1.11-0-g4bccb38
 init version: de40ad0
 Security Options:
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 6.5.11-linuxkit
 Operating System: Alpine Linux v3.19
 OSType: linux
 Architecture: aarch64
 CPUs: 10
 Total Memory: 7.663GiB
 Name: 4a7ed206a70d
 ID: c20f7230-59a2-4824-a2f4-fda71c982ee6
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Experimental: false
 Insecure Registries:
  127.0.0.0/8
 Live Restore Enabled: false
 Product License: Community Engine
```

### [Format the output (--format)](#format)

You can also specify the output format:

```console
$ docker info --format '{{json .}}'

{"ID":"4cee4408-10d2-4e17-891c-a41736ac4536","Containers":14, ...}
```

### [Run `docker info` on Windows](#run-docker-info-on-windows)

Here is a sample output for a daemon running on Windows Server:

```console
C:\> docker info

Client: Docker Engine - Community
 Version:    24.0.0
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.10.4
    Path:     C:\Program Files\Docker\cli-plugins\docker-buildx.exe
  compose: Docker Compose (Docker Inc.)
    Version:  v2.17.2
    Path:     C:\Program Files\Docker\cli-plugins\docker-compose.exe

Server:
 Containers: 1
  Running: 0
  Paused: 0
  Stopped: 1
 Images: 17
 Server Version: 23.0.3
 Storage Driver: windowsfilter
 Logging Driver: json-file
 Plugins:
  Volume: local
  Network: ics internal l2bridge l2tunnel nat null overlay private transparent
  Log: awslogs etwlogs fluentd gcplogs gelf json-file local splunk syslog
 Swarm: inactive
 Default Isolation: process
 Kernel Version: 10.0 20348 (20348.1.amd64fre.fe_release.210507-1500)
 Operating System: Microsoft Windows Server Version 21H2 (OS Build 20348.707)
 OSType: windows
 Architecture: x86_64
 CPUs: 8
 Total Memory: 3.999 GiB
 Name: WIN-V0V70C0LU5P
 ID: 2880d38d-464e-4d01-91bd-c76f33ba3981
 Docker Root Dir: C:\ProgramData\docker
 Debug Mode: false
 Experimental: true
 Insecure Registries:
  myregistry:5000
  127.0.0.0/8
 Registry Mirrors:
   http://192.168.1.2/
   http://registry-mirror.example.com:5000/
 Live Restore Enabled: false
```

----
url: https://docs.docker.com/compose/how-tos/oci-artifact/
----

# Package and deploy Docker Compose applications as OCI artifacts

***

Table of contents

***

Requires: Docker Compose [2.34.0](https://github.com/docker/compose/releases/tag/v2.34.0) and later

Docker Compose supports working with [OCI artifacts](https://docs.docker.com/docker-hub/repos/manage/hub-images/oci-artifacts/), allowing you to package and distribute your Compose applications through container registries. This means you can store your Compose files alongside your container images, making it easier to version, share, and deploy your multi-container applications.

## [Publish your Compose application as an OCI artifact](#publish-your-compose-application-as-an-oci-artifact)

To distribute your Compose application as an OCI artifact, you can use the `docker compose publish` command, to publish it to an OCI-compliant registry. This allows others to then deploy your application directly from the registry.

The publish function supports most of the composition capabilities of Compose, like overrides, extends or include, [with some limitations](#limitations).

### [General steps](#general-steps)

1. Navigate to your Compose application's directory.\
   Ensure you're in the directory containing your `compose.yml` file or that you are specifying your Compose file with the `-f` flag.

2. In your terminal, sign in to your Docker account so you're authenticated with Docker Hub.

   ```console
   $ docker login
   ```

3. Use the `docker compose publish` command to push your application as an OCI artifact:

   ```console
   $ docker compose publish username/my-compose-app:latest
   ```

   If you have multiple Compose files, run:

   ```console
   $ docker compose -f compose-base.yml -f compose-production.yml publish username/my-compose-app:latest
   ```

### [Advanced publishing options](#advanced-publishing-options)

When publishing, you can pass additional options:

* `--oci-version`: Specify the OCI version (default is automatically determined).
* `--resolve-image-digests`: Pin image tags to digests.
* `--with-env`: Include environment variables in the published OCI artifact.

Compose checks to make sure there isn't any sensitive data in your configuration and displays your environment variables to confirm you want to publish them.

```text
...
you are about to publish sensitive data within your OCI artifact.
please double check that you are not leaking sensitive data
AWS Client ID
"services.serviceA.environment.AWS_ACCESS_KEY_ID": xxxxxxxxxx
AWS Secret Key
"services.serviceA.environment.AWS_SECRET_ACCESS_KEY": aws"xxxx/xxxx+xxxx+"
Github authentication
"GITHUB_TOKEN": ghp_xxxxxxxxxx
JSON Web Token
"": xxxxxxx.xxxxxxxx.xxxxxxxx
Private Key
"": -----BEGIN DSA PRIVATE KEY-----
xxxxx
-----END DSA PRIVATE KEY-----
Are you ok to publish these sensitive data? [y/N]:y

you are about to publish environment variables within your OCI artifact.
please double check that you are not leaking sensitive data
Service/Config  serviceA
FOO=bar
Service/Config  serviceB
FOO=bar
QUIX=
BAR=baz
Are you ok to publish these environment variables? [y/N]: 
```

If you decline, the publish process stops without sending anything to the registry.

## [Limitations](#limitations)

There are limitations to publishing Compose applications as OCI artifacts. You can't publish a Compose configuration:

* With service(s) containing bind mounts
* With service(s) containing only a `build` section
* That includes local files with the `include` attribute. To publish successfully, ensure that any included local files are also published. You can then use `include` to reference these files as remote `include` is supported.

## [Start an OCI artifact application](#start-an-oci-artifact-application)

To start a Docker Compose application that uses an OCI artifact, you can use the `-f` (or `--file`) flag followed by the OCI artifact reference. This allows you to specify a Compose file stored as an OCI artifact in a registry.

The `oci://` prefix indicates that the Compose file should be pulled from an OCI-compliant registry rather than loaded from the local filesystem.

```console
$ docker compose -f oci://docker.io/username/my-compose-app:latest up
```

To then run the Compose application, use the `docker compose up` command with the `-f` flag pointing to your OCI artifact:

```console
$ docker compose -f oci://docker.io/username/my-compose-app:latest up
```

### [Troubleshooting](#troubleshooting)

When you run an application from an OCI artifact, Compose may display warning messages that require you to confirm the following so as to limit the risk of running a malicious application:

* A list of the interpolation variables used along with their values
* A list of all environment variables used by the application
* If your OCI artifact application is using another remote resources, for example via [`include`](/reference/compose-file/include/).

```text
$ REGISTRY=myregistry.com docker compose -f oci://docker.io/username/my-compose-app:latest up

Found the following variables in configuration:
VARIABLE     VALUE                SOURCE        REQUIRED    DEFAULT
REGISTRY     myregistry.com      command-line   yes         
TAG          v1.0                environment    no          latest
DOCKERFILE   Dockerfile          default        no          Dockerfile
API_KEY      <unset>             none           no          

Do you want to proceed with these variables? [Y/n]:y

Warning: This Compose project includes files from remote sources:
- oci://registry.example.com/stack:latest
Remote includes could potentially be malicious. Make sure you trust the source.
Do you want to continue? [y/N]: 
```

If you agree to start the application, Compose displays the directory where all the resources from the OCI artifact have been downloaded:

```text
...
Do you want to continue? [y/N]: y

Your compose stack "oci://registry.example.com/stack:latest" is stored in "~/Library/Caches/docker-compose/964e715660d6f6c3b384e05e7338613795f7dcd3613890cfa57e3540353b9d6d"
```

The `docker compose publish` command supports non-interactive execution, letting you skip the confirmation prompt by including the `-y` (or `--yes`) flag:

```console
$ docker compose publish -y username/my-compose-app:latest
```

## [Next steps](#next-steps)

* [Familiarize yourself with Compose's trust model](https://docs.docker.com/compose/trust-model/)
* [Learn about OCI artifacts in Docker Hub](https://docs.docker.com/docker-hub/repos/manage/hub-images/oci-artifacts/)
* [Compose publish command](/reference/cli/docker/compose/publish/)
* [Understand `include`](https://docs.docker.com/reference/compose-file/include/)

----
url: https://docs.docker.com/reference/cli/docker/compose/logs/
----

# docker compose logs

***

| Description | View output from containers                  |
| ----------- | -------------------------------------------- |
| Usage       | `docker compose logs [OPTIONS] [SERVICE...]` |

## [Description](#description)

Displays log output from services

## [Options](#options)

| Option             | Default | Description                                                                                     |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------- |
| `-f, --follow`     |         | Follow log output                                                                               |
| `--index`          |         | index of the container if service has multiple replicas                                         |
| `--no-color`       |         | Produce monochrome output                                                                       |
| `--no-log-prefix`  |         | Don't print prefix in logs                                                                      |
| `--since`          |         | Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)     |
| `-n, --tail`       | `all`   | Number of lines to show from the end of the logs for each container                             |
| `-t, --timestamps` |         | Show timestamps                                                                                 |
| `--until`          |         | Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)  |

----
url: https://docs.docker.com/reference/cli/docker/compose/alpha/watch/
----

# docker compose alpha watch

***

| Description | Watch build context for service and rebuild/refresh containers when files are updated |
| ----------- | ------------------------------------------------------------------------------------- |
| Usage       | `docker compose alpha watch [SERVICE...]`                                             |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Watch build context for service and rebuild/refresh containers when files are updated

## [Options](#options)

| Option    | Default | Description                                   |
| --------- | ------- | --------------------------------------------- |
| `--no-up` |         | Do not build & start services before watching |
| `--quiet` |         | hide build output                             |

----
url: https://docs.docker.com/docker-hub/repos/manage/hub-images/manage/
----

# Image Management

***

Table of contents

***

Availability: Beta

Images and image indexes are the foundation of container images within a repository. The following diagram shows the relationship between images and image indexes.

This structure enables multi-architecture support through a single reference. It is important to note that images are not always referenced by an image index. The following objects are shown in the diagram.

* Image index: An image that points to multiple architecture-specific images (like AMD and ARM), letting a single reference work across different platforms.
* Image: Individual container images that contain the actual configuration and layers for a specific architecture and operating system.

## [Manage repository images and image indexes](#manage-repository-images-and-image-indexes)

Use the following steps to delete one or more items via the graphical user interface. To delete in bulk, see the [deletion API endpoint](/reference/api/registry/latest/#tag/delete).

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

3. In the list, select a repository.

4. Select **Image Management**.

5. Search, filter, or sort the items.

   * Search: In the search box above the list, specify your search.
   * Filter: In the **Filter by** drop-down, select **Tagged**, **Image index**, or **Image**.
   * Sort: Select the column title for **Size**, **Last pushed**, or **Last pulled**.

   > Note
   >
   > Images that haven't been pulled in over 6 months are marked as **Stale** in the **Status** column.

6. Optional. Delete one or more items.

   1. Select the checkboxes next to the items in the list. Selecting any top-level index also removes any underlying images that aren't referenced elsewhere.
   2. Select **Preview and delete**.
   3. In the window that appears, verify the items that will be deleted and the amount of storage you will reclaim.
   4. Select **Delete forever**.

   > Note
   >
   > Deletion operations may take some time to complete. Timeout errors may occur during the deletion process. The system automatically retries the deletion in the background, and the items will be removed without requiring any action from you.

----
url: https://docs.docker.com/engine/daemon/troubleshoot/
----

# Troubleshooting the Docker daemon

***

Table of contents

***

This page describes how to troubleshoot and debug the daemon if you run into issues.

You can turn on debugging on the daemon to learn about the runtime activity of the daemon and to aid in troubleshooting. If the daemon is unresponsive, you can also [force a full stack trace](https://docs.docker.com/engine/daemon/logs/#force-a-stack-trace-to-be-logged) of all threads to be added to the daemon log by sending the `SIGUSR` signal to the Docker daemon.

## [Daemon](#daemon)

### [Unable to connect to the Docker daemon](#unable-to-connect-to-the-docker-daemon)

```text
Cannot connect to the Docker daemon. Is 'docker daemon' running on this host?
```

This error may indicate:

* The Docker daemon isn't running on your system. Start the daemon and try running the command again.
* Your Docker client is attempting to connect to a Docker daemon on a different host, and that host is unreachable.

### [Check whether Docker is running](#check-whether-docker-is-running)

The operating-system independent way to check whether Docker is running is to ask Docker, using the `docker info` command.

You can also use operating system utilities, such as `sudo systemctl is-active docker` or `sudo status docker` or `sudo service docker status`, or checking the service status using Windows utilities.

Finally, you can check in the process list for the `dockerd` process, using commands like `ps` or `top`.

#### [Check which host your client is connecting to](#check-which-host-your-client-is-connecting-to)

To see which host your client is connecting to, check the value of the `DOCKER_HOST` variable in your environment.

```console
$ env | grep DOCKER_HOST
```

If this command returns a value, the Docker client is set to connect to a Docker daemon running on that host. If it's unset, the Docker client is set to connect to the Docker daemon running on the local host. If it's set in error, use the following command to unset it:

```console
$ unset DOCKER_HOST
```

You may need to edit your environment in files such as `~/.bashrc` or `~/.profile` to prevent the `DOCKER_HOST` variable from being set erroneously.

If `DOCKER_HOST` is set as intended, verify that the Docker daemon is running on the remote host and that a firewall or network outage isn't preventing you from connecting.

### [Troubleshoot conflicts between the `daemon.json` and startup scripts](#troubleshoot-conflicts-between-the-daemonjson-and-startup-scripts)

If you use a `daemon.json` file and also pass options to the `dockerd` command manually or using start-up scripts, and these options conflict, Docker fails to start with an error such as:

```text
unable to configure the Docker daemon with file /etc/docker/daemon.json:
the following directives are specified both as a flag and in the configuration
file: hosts: (from flag: [unix:///var/run/docker.sock], from file: [tcp://127.0.0.1:2376])
```

If you see an error similar to this one and you are starting the daemon manually with flags, you may need to adjust your flags or the `daemon.json` to remove the conflict.

> Note
>
> If you see this specific error message about `hosts`, continue to the [next section](#configure-the-daemon-host-with-systemd) for a workaround.

If you are starting Docker using your operating system's init scripts, you may need to override the defaults in these scripts in ways that are specific to the operating system.

#### [Configure the daemon host with systemd](#configure-the-daemon-host-with-systemd)

One notable example of a configuration conflict that's difficult to troubleshoot is when you want to specify a different daemon address from the default. Docker listens on a socket by default. On Debian and Ubuntu systems using `systemd`, this means that a host flag `-H` is always used when starting `dockerd`. If you specify a `hosts` entry in the `daemon.json`, this causes a configuration conflict and results in the Docker daemon failing to start.

To work around this problem, create a new file `/etc/systemd/system/docker.service.d/docker.conf` with the following contents, to remove the `-H` argument that's used when starting the daemon by default.

```systemd
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd
```

There are other times when you might need to configure `systemd` with Docker, such as [configuring a HTTP or HTTPS proxy](https://docs.docker.com/engine/daemon/proxy/).

> Note
>
> If you override this option without specifying a `hosts` entry in the `daemon.json` or a `-H` flag when starting Docker manually, Docker fails to start.

Run `sudo systemctl daemon-reload` before attempting to start Docker. If Docker starts successfully, it's now listening on the IP address specified in the `hosts` key of the `daemon.json` instead of a socket.

> Important
>
> Setting `hosts` in the `daemon.json` isn't supported on Docker Desktop for Windows or Docker Desktop for Mac.

### [Out of memory issues](#out-of-memory-issues)

If your containers attempt to use more memory than the system has available, you may experience an Out of Memory (OOM) exception, and a container, or the Docker daemon, might be stopped by the kernel OOM killer. To prevent this from happening, ensure that your application runs on hosts with adequate memory and see [Understand the risks of running out of memory](https://docs.docker.com/engine/containers/resource_constraints/#understand-the-risks-of-running-out-of-memory).

### [Kernel compatibility](#kernel-compatibility)

Docker can't run correctly if your kernel is older than version 3.10, or if it's missing kernel modules. To check kernel compatibility, you can download and run the [`check-config.sh`](https://raw.githubusercontent.com/docker/docker/master/contrib/check-config.sh) script.

```console
$ curl https://raw.githubusercontent.com/docker/docker/master/contrib/check-config.sh > check-config.sh

$ bash ./check-config.sh
```

The script only works on Linux.

### [Kernel cgroup swap limit capabilities](#kernel-cgroup-swap-limit-capabilities)

On Ubuntu or Debian hosts, you may see messages similar to the following when working with an image.

```text
WARNING: Your kernel does not support swap limit capabilities. Limitation discarded.
```

If you don't need these capabilities, you can ignore the warning.

You can turn on these capabilities on Ubuntu or Debian by following these instructions. Memory and swap accounting incur an overhead of about 1% of the total available memory and a 10% overall performance degradation, even when Docker isn't running.

1. Log into the Ubuntu or Debian host as a user with `sudo` privileges.

2. Edit the `/etc/default/grub` file. Add or edit the `GRUB_CMDLINE_LINUX` line to add the following two key-value pairs:

   ```text
   GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1"
   ```

   Save and close the file.

3. Update the GRUB boot loader.

   ```console
   $ sudo update-grub
   ```

   An error occurs if your GRUB configuration file has incorrect syntax. In this case, repeat steps 2 and 3.

   The changes take effect when you reboot the system.

## [Networking](#networking)

### [IP forwarding problems](#ip-forwarding-problems)

If you manually configure your network using `systemd-network` with systemd version 219 or later, Docker containers may not be able to access your network. Beginning with systemd version 220, the forwarding setting for a given network (`net.ipv4.conf.<interface>.forwarding`) defaults to off. This setting prevents IP forwarding. It also conflicts with Docker's behavior of enabling the `net.ipv4.conf.all.forwarding` setting within containers.

To work around this on RHEL, CentOS, or Fedora, edit the `<interface>.network` file in `/usr/lib/systemd/network/` on your Docker host, for example, `/usr/lib/systemd/network/80-container-host0.network`.

Add the following block within the `[Network]` section.

```systemd
[Network]
...
IPForward=kernel
# OR
IPForward=true
```

This configuration allows IP forwarding from the container as expected.

### [DNS resolver issues](#dns-resolver-issues)

```console
DNS resolver found in resolv.conf and containers can't use it
```

Linux desktop environments often have a network manager program running, that uses `dnsmasq` to cache DNS requests by adding them to `/etc/resolv.conf`. The `dnsmasq` instance runs on a loopback address such as `127.0.0.1` or `127.0.1.1`. It speeds up DNS look-ups and provides DHCP services. Such a configuration doesn't work within a Docker container. The Docker container uses its own network namespace, and resolves loopback addresses such as `127.0.0.1` to itself, and it's unlikely to be running a DNS server on its own loopback address.

If Docker detects that no DNS server referenced in `/etc/resolv.conf` is a fully functional DNS server, the following warning occurs:

```text
WARNING: Local (127.0.0.1) DNS resolver found in resolv.conf and containers
can't use it. Using default external servers : [8.8.8.8 8.8.4.4]
```

If you see this warning, first check to see if you use `dnsmasq`:

```console
$ ps aux | grep dnsmasq
```

If your container needs to resolve hosts which are internal to your network, the public nameservers aren't adequate. You have two choices:

* Specify DNS servers for Docker to use.

* Turn off `dnsmasq`.

  Turning off `dnsmasq` adds the IP addresses of actual DNS nameservers to `/etc/resolv.conf`, and you lose the benefits of `dnsmasq`.

You only need to use one of these methods.

### [Specify DNS servers for Docker](#specify-dns-servers-for-docker)

The default location of the configuration file is `/etc/docker/daemon.json`. You can change the location of the configuration file using the `--config-file` daemon flag. The following instruction assumes that the location of the configuration file is `/etc/docker/daemon.json`.

1. Create or edit the Docker daemon configuration file, which defaults to `/etc/docker/daemon.json` file, which controls the Docker daemon configuration.

   ```console
   $ sudo nano /etc/docker/daemon.json
   ```

2. Add a `dns` key with one or more DNS server IP addresses as values.

   ```json
   {
     "dns": ["8.8.8.8", "8.8.4.4"]
   }
   ```

   If the file has existing contents, you only need to add or edit the `dns` line. If your internal DNS server can't resolve public IP addresses, include at least one DNS server that can. Doing so allows you to connect to Docker Hub, and your containers to resolve internet domain names.

   Save and close the file.

3. Restart the Docker daemon.

   ```console
   $ sudo service docker restart
   ```

4. Verify that Docker can resolve external IP addresses by trying to pull an image:

   ```console
   $ docker pull hello-world
   ```

5. If necessary, verify that Docker containers can resolve an internal hostname by pinging it.

   ```console
   $ docker run --rm -it alpine ping -c4 <my_internal_host>

   PING google.com (192.168.1.2): 56 data bytes
   64 bytes from 192.168.1.2: seq=0 ttl=41 time=7.597 ms
   64 bytes from 192.168.1.2: seq=1 ttl=41 time=7.635 ms
   64 bytes from 192.168.1.2: seq=2 ttl=41 time=7.660 ms
   64 bytes from 192.168.1.2: seq=3 ttl=41 time=7.677 ms
   ```

### [Turn off `dnsmasq`](#turn-off-dnsmasq)

If you prefer not to change the Docker daemon's configuration to use a specific IP address, follow these instructions to turn off `dnsmasq` in NetworkManager.

1. Edit the `/etc/NetworkManager/NetworkManager.conf` file.

2. Comment out the `dns=dnsmasq` line by adding a `#` character to the beginning of the line.

   ```text
   # dns=dnsmasq
   ```

   Save and close the file.

3. Restart both NetworkManager and Docker. As an alternative, you can reboot your system.

   ```console
   $ sudo systemctl restart network-manager
   $ sudo systemctl restart docker
   ```

To turn off `dnsmasq` on RHEL, CentOS, or Fedora:

1. Turn off the `dnsmasq` service:

   ```console
   $ sudo systemctl stop dnsmasq
   $ sudo systemctl disable dnsmasq
   ```

2. Configure the DNS servers manually using the [Red Hat documentation](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/configuring_and_managing_networking/configuring-the-order-of-dns-servers_configuring-and-managing-networking).

### [Docker networks disappearing](#docker-networks-disappearing)

If a Docker network, such as the `docker0` bridge or a custom network, randomly disappears or otherwise appears to be working incorrectly, it could be because another service is interfering with or modifying Docker interfaces. Tools that manage networking interfaces on the host are known to sometimes also inappropriately modify Docker interfaces.

Refer to the following sections for instructions on how to configure your network manager to set Docker interfaces as un-managed, depending on the network management tools that exist on the host:

* If `netscript` is installed, consider [uninstalling it](#uninstall-netscript)
* Configure the network manager to [treat Docker interfaces as un-managed](#un-manage-docker-interfaces)
* If you're using Netplan, you may need to [apply a custom Netplan configuration](#prevent-netplan-from-overriding-network-configuration)

#### [Uninstall `netscript`](#uninstall-netscript)

If `netscript` is installed on your system, you can likely fix this issue by uninstalling it. For example, on a Debian-based system:

```console
$ sudo apt-get remove netscript-2.4
```

#### [Un-manage Docker interfaces](#un-manage-docker-interfaces)

In some cases, the network manager will attempt to manage Docker interfaces by default. You can try to explicitly flag Docker networks as un-managed by editing your system's network configuration settings.

If you're using `NetworkManager`, edit your system network configuration under `/etc/network/interfaces`

1. Create a file at `/etc/network/interfaces.d/20-docker0` with the following contents:

   ```text
   iface docker0 inet manual
   ```

   Note that this example configuration only "un-manages" the default `docker0` bridge, not custom networks.

2. Restart `NetworkManager` for the configuration change to take effect.

   ```console
   $ systemctl restart NetworkManager
   ```

3. Verify that the `docker0` interface has the `unmanaged` state.

   ```console
   $ nmcli device
   ```

If you're running Docker on a system using `systemd-networkd` as a networking daemon, configure the Docker interfaces as un-managed by creating configuration files under `/etc/systemd/network`:

1. Create `/etc/systemd/network/docker.network` with the following contents:

   ```ini
   # Ensure that the Docker interfaces are un-managed

   [Match]
   Name=docker0 br-* veth*

   [Link]
   Unmanaged=yes
   ```

2. Reload the configuration.

   ```console
   $ sudo systemctl restart systemd-networkd
   ```

3. Restart the Docker daemon.

   ```console
   $ sudo systemctl restart docker
   ```

4. Verify that the Docker interfaces have the `unmanaged` state.

   ```console
   $ networkctl
   ```

### [Prevent Netplan from overriding network configuration](#prevent-netplan-from-overriding-network-configuration)

On systems that use [Netplan](https://netplan.io/) through [`cloud-init`](https://cloudinit.readthedocs.io/en/latest/index.html), you may need to apply a custom configuration to prevent `netplan` from overriding the network manager configuration:

1. Follow the steps in [Un-manage Docker interfaces](#un-manage-docker-interfaces) for creating the network manager configuration.

2. Create a `netplan` configuration file under `/etc/netplan/50-cloud-init.yml`.

   The following example configuration file is a starting point. Adjust it to match the interfaces you want to un-manage. Incorrect configuration can lead to network connectivity issues.

   /etc/netplan/50-cloud-init.yml

   ```yaml
   network:
     ethernets:
       all:
         dhcp4: true
         dhcp6: true
         match:
           # edit this filter to match whatever makes sense for your system
           name: en*
     renderer: networkd
     version: 2
   ```

3. Apply the new Netplan configuration.

   ```console
   $ sudo netplan apply
   ```

4. Restart the Docker daemon:

   ```console
   $ sudo systemctl restart docker
   ```

5. Verify that the Docker interfaces have the `unmanaged` state.

   ```console
   $ networkctl
   ```

## [Volumes](#volumes)

### [Unable to remove filesystem](#unable-to-remove-filesystem)

```text
Error: Unable to remove filesystem
```

Some container-based utilities, such as [Google cAdvisor](https://github.com/google/cadvisor), mount Docker system directories, such as `/var/lib/docker/`, into a container. For instance, the documentation for `cadvisor` instructs you to run the `cadvisor` container as follows:

```console
$ sudo docker run \
  --volume=/:/rootfs:ro \
  --volume=/var/run:/var/run:rw \
  --volume=/sys:/sys:ro \
  --volume=/var/lib/docker/:/var/lib/docker:ro \
  --publish=8080:8080 \
  --detach=true \
  --name=cadvisor \
  google/cadvisor:latest
```

When you bind-mount `/var/lib/docker/`, this effectively mounts all resources of all other running containers as filesystems within the container which mounts `/var/lib/docker/`. When you attempt to remove any of these containers, the removal attempt may fail with an error like the following:

```text
Error: Unable to remove filesystem for
74bef250361c7817bee19349c93139621b272bc8f654ae112dd4eb9652af9515:
remove /var/lib/docker/containers/74bef250361c7817bee19349c93139621b272bc8f654ae112dd4eb9652af9515/shm:
Device or resource busy
```

The problem occurs if the container which bind-mounts `/var/lib/docker/` uses `statfs` or `fstatfs` on filesystem handles within `/var/lib/docker/` and does not close them.

Typically, we would advise against bind-mounting `/var/lib/docker` in this way. However, `cAdvisor` requires this bind-mount for core functionality.

If you are unsure which process is causing the path mentioned in the error to be busy and preventing it from being removed, you can use the `lsof` command to find its process. For instance, for the error above:

```console
$ sudo lsof /var/lib/docker/containers/74bef250361c7817bee19349c93139621b272bc8f654ae112dd4eb9652af9515/shm
```

To work around this problem, stop the container which bind-mounts `/var/lib/docker` and try again to remove the other container.

----
url: https://docs.docker.com/compose/compose-sdk/
----

# Using the Compose SDK

***

Table of contents

***

Requires: Docker Compose [5.0.0](https://github.com/docker/compose/releases/tag/v5.0.0) and later

The `docker/compose` package can be used as a Go library by third-party applications to programmatically manage containerized applications defined in Compose files. This SDK provides a comprehensive API that lets you integrate Compose functionality directly into your applications, allowing you to load, validate, and manage multi-container environments without relying on the Compose CLI.

Whether you need to orchestrate containers as part of a deployment pipeline, build custom management tools, or embed container orchestration into your application, the Compose SDK offers the same powerful capabilities that drive the Docker Compose command-line tool.

## [Set up the SDK](#set-up-the-sdk)

To get started, create an SDK instance using the `NewComposeService()` function, which initializes a service with the necessary configuration to interact with the Docker daemon and manage Compose projects. This service instance provides methods for all core Compose operations including creating, starting, stopping, and removing containers, as well as loading and validating Compose files. The service handles the underlying Docker API interactions and resource management, allowing you to focus on your application logic.

### [Requirements](#requirements)

Before using the SDK, make sure you're using a compatible version of the Docker CLI.

```go
require (
    github.com/docker/cli v28.5.2+incompatible
)
```

Docker CLI version 29.0.0 and later depends on the new `github.com/moby/moby` module, whereas Docker Compose v5 currently depends on `github.com/docker/docker`. This means you need to pin `docker/cli v28.5.2+incompatible` to ensure compatibility and avoid build errors.

### [Example usage](#example-usage)

Here's a basic example demonstrating how to load a Compose project and start the services:

```go
package main

import (
    "context"
    "log"

	"github.com/docker/cli/cli/command"
	"github.com/docker/cli/cli/flags"
    "github.com/docker/compose/v5/pkg/api"
    "github.com/docker/compose/v5/pkg/compose"
)

func main() {
    ctx := context.Background()

	dockerCLI, err := command.NewDockerCli()
	if err != nil {
		log.Fatalf("Failed to create docker CLI: %v", err)
	}
	err = dockerCLI.Initialize(&flags.ClientOptions{})
	if err != nil {
		log.Fatalf("Failed to initialize docker CLI: %v", err)
	}
	
    // Create a new Compose service instance
    service, err := compose.NewComposeService(dockerCLI)
    if err != nil {
        log.Fatalf("Failed to create compose service: %v", err)
    }

    // Load the Compose project from a compose file
    project, err := service.LoadProject(ctx, api.ProjectLoadOptions{
        ConfigPaths: []string{"compose.yaml"},
        ProjectName: "my-app",
    })
    if err != nil {
        log.Fatalf("Failed to load project: %v", err)
    }

    // Start the services defined in the Compose file
    err = service.Up(ctx, project, api.UpOptions{
        Create: api.CreateOptions{},
        Start:  api.StartOptions{},
    })
    if err != nil {
        log.Fatalf("Failed to start services: %v", err)
    }

    log.Printf("Successfully started project: %s", project.Name)
}
```

This example demonstrates the core workflow - creating a service instance, loading a project from a Compose file, and starting the services. The SDK provides many additional operations for managing the lifecycle of your containerized application.

## [Customizing the SDK](#customizing-the-sdk)

The `NewComposeService()` function accepts optional `compose.Option` parameters to customize the SDK behavior. These options allow you to configure I/O streams, concurrency limits, dry-run mode, and other advanced features.

```go
    // Create a custom output buffer to capture logs
    var outputBuffer bytes.Buffer

    // Create a compose service with custom options
    service, err := compose.NewComposeService(dockerCLI,
        compose.WithOutputStream(&outputBuffer),          // Redirect output to custom writer
        compose.WithErrorStream(os.Stderr),               // Use stderr for errors
        compose.WithMaxConcurrency(4),                    // Limit concurrent operations
        compose.WithPrompt(compose.AlwaysOkPrompt()),     // Auto-confirm all prompts
    )
```

### [Available options](#available-options)

* `WithOutputStream(io.Writer)`: Redirect standard output to a custom writer
* `WithErrorStream(io.Writer)`: Redirect error output to a custom writer
* `WithInputStream(io.Reader)`: Provide a custom input stream for interactive prompts
* `WithStreams(out, err, in)`: Set all I/O streams at once
* `WithMaxConcurrency(int)`: Limit the number of concurrent operations against the Docker API
* `WithPrompt(Prompt)`: Customize user confirmation behavior (use `AlwaysOkPrompt()` for non-interactive mode)
* `WithDryRun`: Run operations in dry-run mode without actually applying changes
* `WithContextInfo(api.ContextInfo)`: Set custom Docker context information
* `WithProxyConfig(map[string]string)`: Configure HTTP proxy settings for builds
* `WithEventProcessor(progress.EventProcessor)`: Receive progress events and operation notifications

These options provide fine-grained control over the SDK's behavior, making it suitable for various integration scenarios including CLI tools, web services, automation scripts, and testing environments.

## [Tracking operations with `EventProcessor`](#tracking-operations-with-eventprocessor)

The `EventProcessor` interface allows you to monitor Compose operations in real-time by receiving events about changes applied to Docker resources such as images, containers, volumes, and networks. This is particularly useful for building user interfaces, logging systems, or monitoring tools that need to track the progress of Compose operations.

### [Understanding `EventProcessor`](#understanding-eventprocessor)

A Compose operation, such as `up`, `down`, `build`, performs a series of changes to Docker resources. The `EventProcessor` receives notifications about these changes through three key methods:

* `Start(ctx, operation)`: Called when a Compose operation begins, for example `up`
* `On(events...)`: Called with progress events for individual resource changes, for example, container starting, image being pulled
* `Done(operation, success)`: Called when the operation completes, indicating success or failure

Each event contains information about the resource being modified, its current status, and progress indicators when applicable (such as download progress for image pulls).

### [Event status types](#event-status-types)

Events report resource changes with the following status types:

* Working: Operation is in progress, for example, creating, starting, pulling
* Done: Operation completed successfully
* Warning: Operation completed with warnings
* Error: Operation failed

Common status text values include: `Creating`, `Created`, `Starting`, `Started`, `Running`, `Stopping`, `Stopped`, `Removing`, `Removed`, `Building`, `Built`, `Pulling`, `Pulled`, and more.

### [Built-in `EventProcessor` implementations](#built-in-eventprocessor-implementations)

The SDK provides three ready-to-use `EventProcessor` implementations:

* `progress.NewTTYWriter(io.Writer)`: Renders an interactive terminal UI with progress bars and task lists (similar to the Docker Compose CLI output)
* `progress.NewPlainWriter(io.Writer)`: Outputs simple text-based progress messages suitable for non-interactive environments or log files
* `progress.NewJSONWriter()`: Render events as JSON objects
* `progress.NewQuietWriter()`: (Default) Silently processes events without producing any output

Using `EventProcessor`, a custom UI can be plugged into `docker/compose`.

----
url: https://docs.docker.com/reference/compose-file/merge/
----

# Merge Compose files

***

Table of contents

***

Compose lets you define a Compose application model through multiple Compose files. When doing so, Compose follows certain rules to merge Compose files.

These rules are outlined below.

## [Mapping](#mapping)

A YAML `mapping` gets merged by adding missing entries and merging the conflicting ones.

Merging the following example YAML trees:

```yaml
services:
  foo:
    key1: value1
    key2: value2
```

```yaml
services:
  foo:
    key2: VALUE
    key3: value3
```

Results in a Compose application model equivalent to the YAML tree:

```yaml
services:
  foo:
    key1: value1
    key2: VALUE
    key3: value3
```

## [Sequence](#sequence)

A YAML `sequence` is merged by appending values from the overriding Compose file to the previous one.

Merging the following example YAML trees:

```yaml
services:
  foo:
    DNS:
      - 1.1.1.1
```

```yaml
services:
  foo:
    DNS: 
      - 8.8.8.8
```

Results in a Compose application model equivalent to the YAML tree:

```yaml
services:
  foo:
    DNS:
      - 1.1.1.1
      - 8.8.8.8
```

## [Exceptions](#exceptions)

### [Shell commands](#shell-commands)

When merging Compose files that use the services attributes [command](https://docs.docker.com/reference/compose-file/services/#command), [entrypoint](https://docs.docker.com/reference/compose-file/services/#entrypoint) and [healthcheck: `test`](https://docs.docker.com/reference/compose-file/services/#healthcheck), the value is overridden by the latest Compose file, and not appended.

Merging the following example YAML trees:

```yaml
services:
  foo:
    command: ["echo", "foo"]
```

```yaml
services:
  foo:
    command: ["echo", "bar"]
```

Results in a Compose application model equivalent to the YAML tree:

```yaml
services:
  foo:
    command: ["echo", "bar"]
```

### [Unique resources](#unique-resources)

Applies to the [ports](https://docs.docker.com/reference/compose-file/services/#ports), [volumes](https://docs.docker.com/reference/compose-file/services/#volumes), [secrets](https://docs.docker.com/reference/compose-file/services/#secrets) and [configs](https://docs.docker.com/reference/compose-file/services/#configs) services attributes. While these types are modeled in a Compose file as a sequence, they have special uniqueness requirements:

| Attribute | Unique key                        |
| --------- | --------------------------------- |
| volumes   | target                            |
| secrets   | target                            |
| configs   | target                            |
| ports     | {ip, target, published, protocol} |

When merging Compose files, Compose appends new entries that do not violate a uniqueness constraint and merge entries that share a unique key.

Merging the following example YAML trees:

```yaml
services:
  foo:
    volumes:
      - foo:/work
```

```yaml
services:
  foo:
    volumes:
      - bar:/work
```

Results in a Compose application model equivalent to the YAML tree:

```yaml
services:
  foo:
    volumes:
      - bar:/work
```

### [Reset value](#reset-value)

In addition to the previously described mechanism, an override Compose file can also be used to remove elements from your application model. For this purpose, the custom [YAML tag](https://yaml.org/spec/1.2.2/#24-tags) `!reset` can be set to override a value set by the overridden Compose file. A valid value for attribute must be provided, but will be ignored and target attribute will be set with type's default value or `null`.

For readability, it is recommended to explicitly set the attribute value to the null (`null`) or empty array `[]` (with `!reset null` or `!reset []`) so that it is clear that resulting attribute will be cleared.

A base `compose.yaml` file:

```yaml
services:
  app:
    image: myapp
    ports:
      - "8080:80" 
    environment:
      FOO: BAR           
```

And a `compose.override.yaml` file:

```yaml
services:
  app:
    image: myapp
    ports: !reset []
    environment:
      FOO: !reset null
```

Results in:

```yaml
services:
  app:
    image: myapp
```

### [Replace value](#replace-value)

Requires: Docker Compose [2.24.4](https://github.com/docker/compose/releases/tag/v2.24.4) and later

While `!reset` can be used to remove a declaration from a Compose file using an override file, `!override` allows you to fully replace an attribute, bypassing the standard merge rules. A typical example is to fully replace a resource definition, to rely on a distinct model but using the same name.

A base `compose.yaml` file:

```yaml
services:
  app:
    image: myapp
    ports:
      - "8080:80"
```

To remove the original port, but expose a new one, the following override file is used:

```yaml
services:
  app:
    ports: !override
      - "8443:443" 
```

This results in:

```yaml
services:
  app:
    image: myapp
    ports:
      - "8443:443" 
```

If `!override` had not been used, both `8080:80` and `8443:443` would be exposed as per the [merging rules outlined above](#sequence).

## [Additional resources](#additional-resources)

For more information on how merge can be used to create a composite Compose file, see [Working with multiple Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/)

----
url: https://docs.docker.com/reference/cli/docker/service/ps/
----

# docker service ps

***

| Description | List the tasks of one or more services             |
| ----------- | -------------------------------------------------- |
| Usage       | `docker service ps [OPTIONS] SERVICE [SERVICE...]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Lists the tasks that are running as part of the specified services.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                |
| ------------------------- | ------- | ------------------------------------------ |
| [`-f, --filter`](#filter) |         | Filter output based on conditions provided |
| [`--format`](#format)     |         | Pretty-print tasks using a Go template     |
| `--no-resolve`            |         | Do not map IDs to Names                    |
| `--no-trunc`              |         | Do not truncate output                     |
| `-q, --quiet`             |         | Only display task IDs                      |

## [Examples](#examples)

### [List the tasks that are part of a service](#list-the-tasks-that-are-part-of-a-service)

The following command shows all the tasks that are part of the `redis` service:

```console
$ docker service ps redis

ID             NAME      IMAGE        NODE      DESIRED STATE  CURRENT STATE          ERROR  PORTS
0qihejybwf1x   redis.1   redis:7.4.0  manager1  Running        Running 8 seconds
bk658fpbex0d   redis.2   redis:7.4.0  worker2   Running        Running 9 seconds
5ls5s5fldaqg   redis.3   redis:7.4.0  worker1   Running        Running 9 seconds
8ryt076polmc   redis.4   redis:7.4.0  worker1   Running        Running 9 seconds
1x0v8yomsncd   redis.5   redis:7.4.0  manager1  Running        Running 8 seconds
71v7je3el7rr   redis.6   redis:7.4.0  worker2   Running        Running 9 seconds
4l3zm9b7tfr7   redis.7   redis:7.4.0  worker2   Running        Running 9 seconds
9tfpyixiy2i7   redis.8   redis:7.4.0  worker1   Running        Running 9 seconds
3w1wu13yupln   redis.9   redis:7.4.0  manager1  Running        Running 8 seconds
8eaxrb2fqpbn   redis.10  redis:7.4.0  manager1  Running        Running 8 seconds
```

In addition to running tasks, the output also shows the task history. For example, after updating the service to use the `redis:7.4.1` image, the output may look like this:

```console
$ docker service ps redis

ID            NAME         IMAGE        NODE      DESIRED STATE  CURRENT STATE                   ERROR  PORTS
50qe8lfnxaxk  redis.1      redis:7.4.1  manager1  Running        Running 6 seconds ago
ky2re9oz86r9   \_ redis.1  redis:7.4.0  manager1  Shutdown       Shutdown 8 seconds ago
3s46te2nzl4i  redis.2      redis:7.4.1  worker2   Running        Running less than a second ago
nvjljf7rmor4   \_ redis.2  redis:7.4.1  worker2   Shutdown       Rejected 23 seconds ago        "No such image: redis@sha256:6…"
vtiuz2fpc0yb   \_ redis.2  redis:7.4.0  worker2   Shutdown       Shutdown 1 second ago
jnarweeha8x4  redis.3      redis:7.4.1  worker1   Running        Running 3 seconds ago
vs448yca2nz4   \_ redis.3  redis:7.4.0  worker1   Shutdown       Shutdown 4 seconds ago
jf1i992619ir  redis.4      redis:7.4.1  worker1   Running        Running 10 seconds ago
blkttv7zs8ee   \_ redis.4  redis:7.4.0  worker1   Shutdown       Shutdown 11 seconds ago
```

The number of items in the task history is determined by the `--task-history-limit` option that was set when initializing the swarm. You can change the task history retention limit using the [`docker swarm update`](/reference/cli/docker/swarm/update/) command.

When deploying a service, docker resolves the digest for the service's image, and pins the service to that digest. The digest is not shown by default, but is printed if `--no-trunc` is used. The `--no-trunc` option also shows the non-truncated task ID, and error messages, as can be seen in the following example:

```console
$ docker service ps --no-trunc redis

ID                          NAME         IMAGE                                                                                NODE      DESIRED STATE  CURRENT STATE            ERROR                                                                                           PORTS
50qe8lfnxaxksi9w2a704wkp7   redis.1      redis:7.4.1@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842  manager1  Running        Running 5 minutes ago
ky2re9oz86r9556i2szb8a8af   \_ redis.1   redis:7.4.0@sha256:f8829e00d95672c48c60f468329d6693c4bdd28d1f057e755f8ba8b40008682e  worker2   Shutdown       Shutdown 5 minutes ago
bk658fpbex0d57cqcwoe3jthu   redis.2      redis:7.4.1@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842  worker2   Running        Running 5 seconds
nvjljf7rmor4htv7l8rwcx7i7   \_ redis.2   redis:7.4.1@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842  worker2   Shutdown       Rejected 5 minutes ago   "No such image: redis@sha256:6a692a76c2081888b589e26e6ec835743119fe453d67ecf03df7de5b73d69842"
```

```console
$ docker service ps -f "id=8" redis

ID             NAME      IMAGE        NODE      DESIRED STATE  CURRENT STATE      ERROR  PORTS
8ryt076polmc   redis.4   redis:7.4.1  worker1   Running        Running 9 seconds
8eaxrb2fqpbn   redis.10  redis:7.4.1  manager1  Running        Running 8 seconds
```

#### [name](#name)

The `name` filter matches on task names.

```console
$ docker service ps -f "name=redis.1" redis

ID            NAME     IMAGE        NODE      DESIRED STATE  CURRENT STATE      ERROR  PORTS
qihejybwf1x5  redis.1  redis:7.4.1  manager1  Running        Running 8 seconds
```

#### [node](#node)

The `node` filter matches on a node name or a node ID.

```console
$ docker service ps -f "node=manager1" redis

ID            NAME      IMAGE        NODE      DESIRED STATE  CURRENT STATE      ERROR  PORTS
0qihejybwf1x  redis.1   redis:7.4.1  manager1  Running        Running 8 seconds
1x0v8yomsncd  redis.5   redis:7.4.1  manager1  Running        Running 8 seconds
3w1wu13yupln  redis.9   redis:7.4.1  manager1  Running        Running 8 seconds
8eaxrb2fqpbn  redis.10  redis:7.4.1  manager1  Running        Running 8 seconds
```

#### [desired-state](#desired-state)

The `desired-state` filter can take the values `running`, `shutdown`, or `accepted`.

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints tasks output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder     | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `.ID`           | Task ID                                                          |
| `.Name`         | Task name                                                        |
| `.Image`        | Task image                                                       |
| `.Node`         | Node ID                                                          |
| `.DesiredState` | Desired state of the task (`running`, `shutdown`, or `accepted`) |
| `.CurrentState` | Current state of the task                                        |
| `.Error`        | Error                                                            |
| `.Ports`        | Task published ports                                             |

When using the `--format` option, the `service ps` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `Name` and `Image` entries separated by a colon (`:`) for all tasks:

```console
$ docker service ps --format "{{.Name}}: {{.Image}}" top

top.1: busybox
top.2: busybox
top.3: busybox
```

----
url: https://docs.docker.com/reference/cli/docker/desktop/enable/model-runner/
----

# docker desktop enable model-runner

***

| Description | Manage Docker Model Runner settings            |
| ----------- | ---------------------------------------------- |
| Usage       | `docker desktop enable model-runner [OPTIONS]` |

## [Description](#description)

Enable and manage Docker Model Runner settings used by 'docker model'

## [Options](#options)

| Option     | Default | Description                                                                           |
| ---------- | ------- | ------------------------------------------------------------------------------------- |
| `--no-tcp` |         | Disable TCP connection. Cannot be used with --tcp.                                    |
| `--tcp`    | `12434` | Enable or change TCP port for connection (1-65535). Cannot be used with --no-tcp.     |
| `--cors`   | `all`   | CORS configuration. Can be `all`, `none`, or comma-separated list of allowed origins. |

----
url: https://docs.docker.com/build/concepts/overview/
----

# Docker Build Overview

***

Table of contents

***

> Note
>
> While `docker build` invokes Buildx under the hood, there are subtle differences between this command and the canonical `docker buildx build`. For details, see [Difference between `docker build` and `docker buildx build`](https://docs.docker.com/build/builders/#difference-between-docker-build-and-docker-buildx-build).


----
url: https://docs.docker.com/reference/cli/docker/compose/config/
----

# docker compose config

***

| Description | Parse, resolve and render compose file in canonical format |
| ----------- | ---------------------------------------------------------- |
| Usage       | `docker compose config [OPTIONS] [SERVICE...]`             |

## [Description](#description)

`docker compose config` renders the actual data model to be applied on the Docker Engine. It merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into the canonical format.

## [Options](#options)

| Option                    | Default | Description                                                                  |
| ------------------------- | ------- | ---------------------------------------------------------------------------- |
| `--environment`           |         | Print environment used for interpolation.                                    |
| `--format`                |         | Format the output. Values: \[yaml \| json]                                   |
| `--hash`                  |         | Print the service config hash, one per line.                                 |
| `--images`                |         | Print the image names, one per line.                                         |
| `--lock-image-digests`    |         | Produces an override file with image digests                                 |
| `--models`                |         | Print the model names, one per line.                                         |
| `--networks`              |         | Print the network names, one per line.                                       |
| `--no-consistency`        |         | Don't check model consistency - warning: may produce invalid Compose output  |
| `--no-env-resolution`     |         | Don't resolve service env files                                              |
| `--no-interpolate`        |         | Don't interpolate environment variables                                      |
| `--no-normalize`          |         | Don't normalize compose model                                                |
| `--no-path-resolution`    |         | Don't resolve file paths                                                     |
| `-o, --output`            |         | Save to file (default to stdout)                                             |
| `--profiles`              |         | Print the profile names, one per line.                                       |
| `-q, --quiet`             |         | Only validate the configuration, don't print anything                        |
| `--resolve-image-digests` |         | Pin image tags to digests                                                    |
| `--services`              |         | Print the service names, one per line.                                       |
| `--variables`             |         | Print model variables and default values.                                    |
| `--volumes`               |         | Print the volume names, one per line.                                        |

----
url: https://docs.docker.com/engine/network/drivers/
----

# Network drivers

***

Table of contents

***

Docker's networking subsystem is pluggable, using drivers. Several drivers exist by default, and provide core networking functionality:

* `bridge`: The default network driver. If you don't specify a driver, this is the type of network you are creating. Bridge networks are commonly used when your application runs in a container that needs to communicate with other containers on the same host. See [Bridge network driver](https://docs.docker.com/engine/network/drivers/bridge/).

* `host`: Remove network isolation between the container and the Docker host, and use the host's networking directly. See [Host network driver](https://docs.docker.com/engine/network/drivers/host/).

* `overlay`: Overlay networks connect multiple Docker daemons together and enable Swarm services and containers to communicate across nodes. This strategy removes the need to do OS-level routing. See [Overlay network driver](https://docs.docker.com/engine/network/drivers/overlay/).

* `ipvlan`: IPvlan networks give users total control over both IPv4 and IPv6 addressing. The VLAN driver builds on top of that in giving operators complete control of layer 2 VLAN tagging and even IPvlan L3 routing for users interested in underlay network integration. See [IPvlan network driver](https://docs.docker.com/engine/network/drivers/ipvlan/).

* `macvlan`: Macvlan networks allow you to assign a MAC address to a container, making it appear as a physical device on your network. The Docker daemon routes traffic to containers by their MAC addresses. Using the `macvlan` driver is sometimes the best choice when dealing with legacy applications that expect to be directly connected to the physical network, rather than routed through the Docker host's network stack. See [Macvlan network driver](https://docs.docker.com/engine/network/drivers/macvlan/).

* `none`: Completely isolate a container from the host and other containers. `none` is not available for Swarm services. See [None network driver](https://docs.docker.com/engine/network/drivers/none/).

* [Network plugins](/engine/extend/plugins_network/): You can install and use third-party network plugins with Docker.

### [Network driver summary](#network-driver-summary)

* The default bridge network is good for running containers that don't require special networking capabilities.
* User-defined bridge networks enable containers on the same Docker host to communicate with each other. A user-defined network typically defines an isolated network for multiple containers belonging to a common project or component.
* Host network shares the host's network with the container. When you use this driver, the container's network isn't isolated from the host.
* Overlay networks are best when you need containers running on different Docker hosts to communicate, or when multiple applications work together using Swarm services.
* Macvlan networks are best when you are migrating from a VM setup or need your containers to look like physical hosts on your network, each with a unique MAC address.
* IPvlan is similar to Macvlan, but doesn't assign unique MAC addresses to containers. Consider using IPvlan when there's a restriction on the number of MAC addresses that can be assigned to a network interface or port.
* Third-party network plugins allow you to integrate Docker with specialized network stacks.

## [Next steps](#next-steps)

Each driver page includes detailed explanations, configuration options, and hands-on usage examples to help you work with that driver effectively.

----
url: https://docs.docker.com/admin/company/company-faqs/
----

# Company FAQs

***

Table of contents

***

### [Some of my organizations don’t have a Docker Business subscription. Can I still use a parent company?](#some-of-my-organizations-dont-have-a-docker-business-subscription-can-i-still-use-a-parent-company)

Yes, but you can only add organizations with a Docker Business subscription to a company.

### [What happens if one of my organizations downgrades from Docker Business, but I still need access as a company owner?](#what-happens-if-one-of-my-organizations-downgrades-from-docker-business-but-i-still-need-access-as-a-company-owner)

To access and manage child organizations, the organization must have a Docker Business subscription. If the organization isn’t included in this subscription, the owner of the organization must manage the organization outside of the company.

### [Do company owners occupy a subscription seat?](#do-company-owners-occupy-a-subscription-seat)

Company owners do not occupy a seat unless one of the following is true:

* They are added as a member of an organization under your company
* SSO is enabled and the company owner signs in via SSO, which automatically adds them as an organization member

Although company owners have the same access as organization owners across all organizations in the company, it's not necessary to add them to any organization. Doing so will cause them to occupy a seat.

When you first create a company, your account is both a company owner and an organization owner. In that case, your account will occupy a seat as long as you remain an organization owner.

To avoid occupying a seat, [assign another user as the organization owner](https://docs.docker.com/admin/organization/manage/members/#update-a-member-role) and remove yourself from the organization. You'll retain full administrative access as a company owner without using a subscription seat.

### [What permissions does the company owner have in the associated/nested organizations?](#what-permissions-does-the-company-owner-have-in-the-associatednested-organizations)

Company owners can navigate to the **Organizations** page to view all their nested organizations in a single location. They can also view or edit organization members and change single sign-on (SSO) and System for Cross-domain Identity Management (SCIM) settings. Changes to company settings impact all users in each organization under the company.

For more information, see [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/).

----
url: https://docs.docker.com/get-started/docker-concepts/running-containers/sharing-local-files/
----

# Sharing local files with containers

***

Table of contents

***

## [Explanation](#explanation)

Each container has everything it needs to function with no reliance on any pre-installed dependencies on the host machine. Since containers run in isolation, they have minimal influence on the host and other containers. This isolation has a major benefit: containers minimize conflicts with the host system and other containers. However, this isolation also means containers can't directly access data on the host machine by default.

Consider a scenario where you have a web application container that requires access to configuration settings stored in a file on your host system. This file may contain sensitive data such as database credentials or API keys. Storing such sensitive information directly within the container image poses security risks, especially during image sharing. To address this challenge, Docker offers storage options that bridge the gap between container isolation and your host machine's data.

Docker offers two primary storage options for persisting data and sharing files between the host machine and containers: volumes and bind mounts.

### [Volume versus bind mounts](#volume-versus-bind-mounts)

If you want to ensure that data generated or modified inside the container persists even after the container stops running, you would opt for a volume. See [Persisting container data](/get-started/docker-concepts/running-containers/persisting-container-data/) to learn more about volumes and their use cases.

If you have specific files or directories on your host system that you want to directly share with your container, like configuration files or development code, then you would use a bind mount. It's like opening a direct portal between your host and container for sharing. Bind mounts are ideal for development environments where real-time file access and sharing between the host and container are crucial.

### [Sharing files between a host and container](#sharing-files-between-a-host-and-container)

Both `-v` (or `--volume`) and `--mount` flags used with the `docker run` command let you share files or directories between your local machine (host) and a Docker container. However, there are some key differences in their behavior and usage.

The `-v` flag is simpler and more convenient for basic volume or bind mount operations. If the host location doesn’t exist when using `-v` or `--volume`, a directory will be automatically created.

Imagine you're a developer working on a project. You have a source directory on your development machine where your code resides. When you compile or build your code, the generated artifacts (compiled code, executables, images, etc.) are saved in a separate subdirectory within your source directory. In the following examples, this subdirectory is `/HOST/PATH`. Now you want these build artifacts to be accessible within a Docker container running your application. Additionally, you want the container to automatically access the latest build artifacts whenever you rebuild your code.

Here's a way to use `docker run` to start a container using a bind mount and map it to the container file location.

```console
$ docker run -v /HOST/PATH:/CONTAINER/PATH -it nginx
```

The `--mount` flag offers more advanced features and granular control, making it suitable for complex mount scenarios or production deployments. By default, if you use `--mount` to bind-mount a file or directory that doesn't yet exist on the Docker host, the `docker run` command doesn't automatically create it for you but generates an error.

```console
$ docker run --mount type=bind,source=/HOST/PATH,target=/CONTAINER/PATH,readonly nginx
```

> Note
>
> Docker recommends using the `--mount` syntax instead of `-v`. It provides better control over the mounting process and avoids potential issues with missing directories.

### [File permissions for Docker access to host files](#file-permissions-for-docker-access-to-host-files)

When using bind mounts, it's crucial to ensure that Docker has the necessary permissions to access the host directory. To grant read/write access, you can use the `:ro` flag (read-only) or `:rw` (read-write) with the `-v` or `--mount` flag during container creation. For example, the following command grants read-write access permission.

```console
$ docker run -v HOST-DIRECTORY:/CONTAINER-DIRECTORY:rw nginx
```

Read-only bind mounts let the container access the mounted files on the host for reading, but it can't change or delete the files. With read-write bind mounts, containers can modify or delete mounted files, and these changes or deletions will also be reflected on the host system. Read-only bind mounts ensures that files on the host can't be accidentally modified or deleted by a container.

> **Synchronized File Share**
>
> As your codebase grows larger, traditional methods of file sharing like bind mounts may become inefficient or slow, especially in development environments where frequent access to files is necessary. [Synchronized file shares](https://docs.docker.com/desktop/features/synchronized-file-sharing/) improve bind mount performance by leveraging synchronized filesystem caches. This optimization ensures that file access between the host and virtual machine (VM) is fast and efficient.

## [Try it out](#try-it-out)

In this hands-on guide, you’ll practice how to create and use a bind mount to share files between a host and a container.

### [Run a container](#run-a-container)

1. [Download and install](/get-started/get-docker/) Docker Desktop.

2. Start a container using the [httpd](https://hub.docker.com/_/httpd) image with the following command:

   ```console
   $ docker run -d -p 8080:80 --name my_site httpd:2.4
   ```

   This will start the `httpd` service in the background, and publish the webpage to port `8080` on the host.

3. Open the browser and access <http://localhost:8080> or use the curl command to verify if it's working fine or not.

   ```console
   $ curl localhost:8080
   ```

### [Use a bind mount](#use-a-bind-mount)

Using a bind mount, you can map the configuration file on your host computer to a specific location within the container. In this example, you’ll see how to change the look and feel of the webpage by using bind mount:

1. Delete the existing container by using the Docker Desktop Dashboard:

2. Create a new directory called `public_html` on your host system.

   ```console
   $ mkdir public_html
   ```

3. Navigate into the newly created directory `public_html` and create a file called `index.html` with the following content. This is a basic HTML document that creates a simple webpage that welcomes you with a friendly whale.

   ```html
   <!DOCTYPE html>
   <html lang="en">
   <head>
   <meta charset="UTF-8">
   <title> My Website with a Whale & Docker!</title>
   </head>
   <body>
   <h1>Whalecome!!</h1>
   <p>Look! There's a friendly whale greeting you!</p>
   <pre id="docker-art">
      ##         .
     ## ## ##        ==
    ## ## ## ## ##    ===
    /"""""""""""""""""\___/ ===
   {                       /  ===-
   \______ O           __/
   \    \         __/
    \____\_______/

   Hello from Docker!
   </pre>
   </body>
   </html>
   ```

4. It's time to run the container. The `--mount` and `-v` examples produce the same result. You can't run them both unless you remove the `my_site` container after running the first one.

   ```console
   $ docker run -d --name my_site -p 8080:80 -v .:/usr/local/apache2/htdocs/ httpd:2.4
   ```

   ```console
   $ docker run -d --name my_site -p 8080:80 --mount type=bind,source=./,target=/usr/local/apache2/htdocs/ httpd:2.4
   ```

   > Tip
   >
   > When using the `-v` or `--mount` flag in Windows PowerShell, you need to provide the absolute path to your directory instead of just `./`. This is because PowerShell handles relative paths differently from bash (commonly used in Mac and Linux environments).

   With everything now up and running, you should be able to access the site via <http://localhost:8080> and find a new webpage that welcomes you with a friendly whale.

### [Access the file on the Docker Desktop Dashboard](#access-the-file-on-the-docker-desktop-dashboard)

1. You can view the mounted files inside a container by selecting the container's **Files** tab and then selecting a file inside the `/usr/local/apache2/htdocs/` directory. Then, select **Open file editor**.

2. Delete the file on the host and verify the file is also deleted in the container. You will find that the files no longer exist under **Files** in the Docker Desktop Dashboard.

3. Recreate the HTML file on the host system and see that file re-appears under the **Files** tab under **Containers** on the Docker Desktop Dashboard. By now, you will be able to access the site too.

### [Stop your container](#stop-your-container)

The container continues to run until you stop it.

1. Go to the **Containers** view in the Docker Desktop Dashboard.

2. Locate the container you'd like to stop.

3. Select the **Stop** action in the Actions column.

## [Additional resources](#additional-resources)

The following resources will help you learn more about bind mounts:

* [Manage data in Docker](/storage/)
* [Volumes](/storage/volumes/)
* [Bind mounts](/storage/bind-mounts/)
* [Running containers](/reference/run/)
* [Troubleshoot storage errors](/storage/troubleshooting_volume_errors/)
* [Persisting container data](/get-started/docker-concepts/running-containers/persisting-container-data/)

## [Next steps](#next-steps)

Now that you have learned about sharing local files with containers, it’s time to learn about multi-container applications.

[Multi-container applications](https://docs.docker.com/get-started/docker-concepts/running-containers/multi-container-applications/)

----
url: https://docs.docker.com/build/ci/github-actions/configure-builder/
----

# Configuring your GitHub Actions builder

***

Table of contents

***

This page contains instructions on configuring your BuildKit instances when using our [Setup Buildx Action](https://github.com/docker/setup-buildx-action).

## [Version pinning](#version-pinning)

By default, the action will attempt to use the latest version of [Buildx](https://github.com/docker/buildx) available on the GitHub Runner (the build client) and the latest release of [BuildKit](https://github.com/moby/buildkit) (the build server).

To pin to a specific version of Buildx, use the `version` input. For example, to pin to Buildx v0.10.0:

```yaml
- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v4
  with:
    version: v0.10.0
```

To pin to a specific version of BuildKit, use the `image` option in the `driver-opts` input. For example, to pin to BuildKit v0.11.0:

```yaml
- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v4
  with:
    driver-opts: image=moby/buildkit:v0.11.0
```

## [BuildKit container logs](#buildkit-container-logs)

To display BuildKit container logs when using the `docker-container` driver, you must either [enable step debug logging](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging#enabling-step-debug-logging), or set the `--debug` buildkitd flag in the [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx) action:

```yaml
name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          buildkitd-flags: --debug
      
      - name: Build
        uses: docker/build-push-action@v7
```

Logs will be available at the end of a job:

## [BuildKit Daemon configuration](#buildkit-daemon-configuration)

You can provide a [BuildKit configuration](https://docs.docker.com/build/buildkit/toml-configuration/) to your builder if you're using the [`docker-container` driver](https://docs.docker.com/build/builders/drivers/docker-container/) (default) with the `config` or `buildkitd-config-inline` inputs:

### [Registry mirror](#registry-mirror)

You can configure a registry mirror using an inline block directly in your workflow with the `buildkitd-config-inline` input:

```yaml
name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          buildkitd-config-inline: |
            [registry."docker.io"]
              mirrors = ["mirror.gcr.io"]
```

For more information about using a registry mirror, see [Registry mirror](https://docs.docker.com/build/buildkit/configure/#registry-mirror).

### [Max parallelism](#max-parallelism)

You can limit the parallelism of the BuildKit solver which is particularly useful for low-powered machines.

You can use the `buildkitd-config-inline` input like the previous example, or you can use a dedicated BuildKit config file from your repository if you want with the `config` input:

```toml
# .github/buildkitd.toml
[worker.oci]
  max-parallelism = 4
```

```yaml
name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          config: .github/buildkitd.toml
```

## [Append additional nodes to the builder](#append-additional-nodes-to-the-builder)

Buildx supports running builds on multiple machines. This is useful for building [multi-platform images](https://docs.docker.com/build/building/multi-platform/) on native nodes for more complicated cases that aren't handled by QEMU. Building on native nodes generally has better performance, and allows you to distribute the build across multiple machines.

You can append nodes to the builder you're creating using the `append` option. It takes input in the form of a YAML string document to remove limitations intrinsically linked to GitHub Actions: you can only use strings in the input fields:

| Name              | Type   | Description                                                                                                                                                                                                                                           |
| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | String | [Name of the node](/reference/cli/docker/buildx/create/#node). If empty, it's the name of the builder it belongs to, with an index number suffix. This is useful to set it if you want to modify/remove a node in an underlying step of you workflow. |
| `endpoint`        | String | [Docker context or endpoint](/reference/cli/docker/buildx/create/#description) of the node to add to the builder                                                                                                                                      |
| `driver-opts`     | List   | List of additional [driver-specific options](/reference/cli/docker/buildx/create/#driver-opt)                                                                                                                                                         |
| `buildkitd-flags` | String | [Flags for buildkitd](/reference/cli/docker/buildx/create/#buildkitd-flags) daemon                                                                                                                                                                    |
| `platforms`       | String | Fixed [platforms](/reference/cli/docker/buildx/create/#platform) for the node. If not empty, values take priority over the detected ones.                                                                                                             |

Here is an example using remote nodes with the [`remote` driver](https://docs.docker.com/build/builders/drivers/remote/) and [TLS authentication](#tls-authentication):

```yaml
name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          driver: remote
          endpoint: tcp://oneprovider:1234
          append: |
            - endpoint: tcp://graviton2:1234
              platforms: linux/arm64
            - endpoint: tcp://linuxone:1234
              platforms: linux/s390x
        env:
          BUILDER_NODE_0_AUTH_TLS_CACERT: ${{ secrets.ONEPROVIDER_CA }}
          BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.ONEPROVIDER_CERT }}
          BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.ONEPROVIDER_KEY }}
          BUILDER_NODE_1_AUTH_TLS_CACERT: ${{ secrets.GRAVITON2_CA }}
          BUILDER_NODE_1_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }}
          BUILDER_NODE_1_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}
          BUILDER_NODE_2_AUTH_TLS_CACERT: ${{ secrets.LINUXONE_CA }}
          BUILDER_NODE_2_AUTH_TLS_CERT: ${{ secrets.LINUXONE_CERT }}
          BUILDER_NODE_2_AUTH_TLS_KEY: ${{ secrets.LINUXONE_KEY }}
```

## [Authentication for remote builders](#authentication-for-remote-builders)

The following examples show how to handle authentication for remote builders, using SSH or TLS.

### [SSH authentication](#ssh-authentication)

To be able to connect to an SSH endpoint using the [`docker-container` driver](https://docs.docker.com/build/builders/drivers/docker-container/), you have to set up the SSH private key and configuration on the GitHub Runner:

```yaml
name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up SSH
        uses: MrSquaare/ssh-setup-action@2d028b70b5e397cf8314c6eaea229a6c3e34977a # v3.1.0
        with:
          host: graviton2
          private-key: ${{ secrets.SSH_PRIVATE_KEY }}
          private-key-name: aws_graviton2
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          endpoint: ssh://me@graviton2
```

### [TLS authentication](#tls-authentication)

You can also [set up a remote BuildKit instance](https://docs.docker.com/build/builders/drivers/remote/#example-remote-buildkit-in-docker-container) using the remote driver. To ease the integration in your workflow, you can use an environment variables that sets up authentication using the BuildKit client certificates for the `tcp://`:

* `BUILDER_NODE_<idx>_AUTH_TLS_CACERT`
* `BUILDER_NODE_<idx>_AUTH_TLS_CERT`
* `BUILDER_NODE_<idx>_AUTH_TLS_KEY`

The `<idx>` placeholder is the position of the node in the list of nodes.

```yaml
name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          driver: remote
          endpoint: tcp://graviton2:1234
        env:
          BUILDER_NODE_0_AUTH_TLS_CACERT: ${{ secrets.GRAVITON2_CA }}
          BUILDER_NODE_0_AUTH_TLS_CERT: ${{ secrets.GRAVITON2_CERT }}
          BUILDER_NODE_0_AUTH_TLS_KEY: ${{ secrets.GRAVITON2_KEY }}
```

## [Standalone mode](#standalone-mode)

If you don't have the Docker CLI installed on the GitHub Runner, the Buildx binary gets invoked directly, instead of calling it as a Docker CLI plugin. This can be useful if you want to use the `kubernetes` driver in your self-hosted runner:

```yaml
name: ci

on:
  push:

jobs:
  buildx:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          driver: kubernetes
      
      - name: Build
        run: |
          buildx build .
```

## [Isolated builders](#isolated-builders)

The following example shows how you can select different builders for different jobs.

An example scenario where this might be useful is when you are using a monorepo, and you want to pinpoint different packages to specific builders. For example, some packages may be particularly resource-intensive to build and require more compute. Or they require a builder equipped with a particular capability or hardware.

For more information about remote builder, see [`remote` driver](https://docs.docker.com/build/builders/drivers/remote/) and the [append builder nodes example](#append-additional-nodes-to-the-builder).

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up builder1
        uses: docker/setup-buildx-action@v4
        id: builder1
      
      - name: Set up builder2
        uses: docker/setup-buildx-action@v4
        id: builder2
      
      - name: Build against builder1
        uses: docker/build-push-action@v7
        with:
          builder: ${{ steps.builder1.outputs.name }}
          target: mytarget1
      
      - name: Build against builder2
        uses: docker/build-push-action@v7
        with:
          builder: ${{ steps.builder2.outputs.name }}
          target: mytarget2
```

----
url: https://docs.docker.com/dhi/core-concepts/glibc-musl/
----

# glibc and musl support in Docker Hardened Images

***

Table of contents

***

Docker Hardened Images (DHI) are built to prioritize security without sacrificing compatibility with the broader open source and enterprise software ecosystem. A key aspect of this compatibility is support for common Linux standard libraries: `glibc` and `musl`.

## [What are glibc and musl?](#what-are-glibc-and-musl)

When you run Linux-based containers, the image's C library plays a key role in how applications interact with the operating system. Most modern Linux distributions rely on one of the following standard C libraries:

* `glibc` (GNU C Library): The standard C library on mainstream distributions like Debian, Ubuntu, and Red Hat Enterprise Linux. It is widely supported and typically considered the most compatible option across languages, frameworks, and enterprise software.

* `musl`: A lightweight alternative to `glibc`, commonly used in minimal distributions like Alpine Linux. While it offers smaller image sizes and performance benefits, `musl` is not always fully compatible with software that expects `glibc`.

## [DHI compatibility](#dhi-compatibility)

DHI images are available in both `glibc`-based (e.g., Debian) and `musl`-based (e.g., Alpine) variants. For enterprise applications and language runtimes where compatibility is critical, we recommend using DHI images based on glibc.

## [What to choose, glibc or musl?](#what-to-choose-glibc-or-musl)

Docker Hardened Images are available in both glibc-based (Debian) and musl-based (Alpine) variants, allowing you to choose the best fit for your workload.

Choose Debian-based (`glibc`) images if:

* You need broad compatibility with enterprise workloads, language runtimes, or proprietary software.
* You're using ecosystems like .NET, Java, or Python with native extensions that depend on `glibc`.
* You want to minimize the risk of runtime errors due to library incompatibilities.

Choose Alpine-based (`musl`) images if:

* You want a minimal footprint with smaller image sizes and reduced surface area.
* You're building a custom or tightly controlled application stack where dependencies are known and tested.
* You prioritize startup speed and lean deployments over maximum compatibility.

If you're unsure, start with a Debian-based image to ensure compatibility, and evaluate Alpine once you're confident in your application's dependencies.

----
url: https://docs.docker.com/reference/api/registry/latest/
----

# Supported registry API for Docker Hub

Supported registry API endpoints.

* [Open Markdown](https://docs.docker.com/reference/api/registry/latest.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/registry/latest.yaml)

- General

  * Overview
  * Authentication
  * Pulling Images
  * Pushing Images
  * Deleting Images

- API

  * Manifests

    * getGet image manifest
    * putPut image manifest
    * headCheck if manifest exists
    * delDelete image manifest

  * Blobs

    * postInitiate blob upload or attempt cross-repository blob mount
    * headCheck existence of blob
    * getRetrieve blob
    * getGet blob upload status
    * putComplete blob upload
    * patchUpload blob chunk
    * delCancel blob upload

[API docs by Redocly](https://redocly.com/redoc/)

# Supported registry API for Docker Hub

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/registry/latest.yaml)

Docker Hub is an OCI-compliant registry, which means it adheres to the open standards defined by the Open Container Initiative (OCI) for distributing container images. This ensures compatibility with a wide range of tools and platforms in the container ecosystem.

This reference documents the Docker Hub-supported subset of the Registry HTTP API V2. It focuses on pulling, pushing, and deleting images. It does not cover the full OCI Distribution Specification.

For the complete OCI specification, see [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec).

## [](#tag/overview)Overview

All endpoints in this API are prefixed by the version and repository name, for example:

```
/v2/<name>/
```

This format provides structured access control and URI-based scoping of image operations.

For example, to interact with the `library/ubuntu` repository, use:

```
/v2/library/ubuntu/
```

Repository names must meet these requirements:

1. Consist of path components matching `[a-z0-9]+(?:[._-][a-z0-9]+)*`
2. If more than one component, they must be separated by `/`
3. Full repository name must be fewer than 256 characters

## [](#tag/authentication)Authentication

Specifies registry authentication.

[Detailed authentication workflow and token usage](https://docs.docker.com/reference/api/registry/auth/)

## [](#tag/pull)Pulling Images

Pulling an image involves retrieving the manifest and downloading each of the image's layer blobs. This section outlines the general steps followed by a working example.

1. [Get a bearer token for the repository](https://docs.docker.com/reference/api/registry/auth/).

2. [Get the image manifest](#operation/GetImageManifest).

3. If the response in the previous step is a multi-architecture manifest list, you must do the following:

   * Parse the `manifests[]` array to locate the digest for your target platform (e.g., `linux/amd64`).
   * [Get the image manifest](#operation/GetImageManifest) using the located digest.

4. [Check if the blob exists](#operation/CheckBlobExists) before downloading. The client should send a `HEAD` request for each layer digest.

5. [Download each layer blob](#operation/GetBlob) using the digest obtained from the manifest. The client should send a `GET` request for each layer digest.

The following bash script example pulls `library/ubuntu:latest` from Docker Hub.

```bash
#!/bin/bash

# Step 1: Get a bearer token
TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/ubuntu:pull" | jq -r .token)

# Step 2: Get the image manifest. In this example, an image manifest list is returned.
curl -s -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" \
     https://registry-1.docker.io/v2/library/ubuntu/manifests/latest \
     -o manifest-list.json

# Step 3a: Parse the `manifests[]` array to locate the digest for your target platform (e.g., `linux/amd64`).
IMAGE_MANIFEST_DIGEST=$(jq -r '.manifests[] | select(.platform.architecture == "amd64" and .platform.os == "linux") | .digest' manifest-list.json)

# Step 3b: Get the platform-specific image manifest
curl -s -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
     https://registry-1.docker.io/v2/library/ubuntu/manifests/$IMAGE_MANIFEST_DIGEST \
     -o manifest.json

# Step 4: Send a HEAD request to check if the layer blob exists
DIGEST=$(jq -r '.layers[0].digest' manifest.json)
curl -I -H "Authorization: Bearer $TOKEN" \
     https://registry-1.docker.io/v2/library/ubuntu/blobs/$DIGEST

# Step 5: Download the layer blob
curl -L -H "Authorization: Bearer $TOKEN" \
     https://registry-1.docker.io/v2/library/ubuntu/blobs/$DIGEST
```

This example pulls the manifest and the first layer for the `ubuntu:latest` image on the `linux/amd64` platform. Repeat steps 4 and 5 for each digest in the `.layers[]` array in the manifest.

## [](#tag/push)Pushing Images

Pushing an image involves uploading any image blobs (such as the config or layers), and then uploading the manifest that references those blobs.

This section outlines the basic steps to push an image using the registry API.

1. [Get a bearer token for the repository](https://docs.docker.com/reference/api/registry/auth/)

2. [Check if the blob exists](#operation/CheckBlobExists) using a `HEAD` request for each blob digest.

3. If the blob does not exist, [upload the blob](#operation/CompleteBlobUpload) using a monolithic `PUT` request:

   * First, [initiate the upload](#operation/InitiateBlobUpload) with `POST`.
   * Then [upload and complete](#operation/CompleteBlobUpload) with `PUT`.

   **Note**: Alternatively, you can upload the blob in multiple chunks by using `PATCH` requests to send each chunk, followed by a final `PUT` request to complete the upload. This is known as a [chunked upload](#operation/UploadBlobChunk) and is useful for large blobs or when resuming interrupted uploads.

4. [Upload the image manifest](#operation/PutImageManifest) using a `PUT` request to associate the config and layers.

The following bash script example pushes a dummy config blob and manifest to `yourusername/helloworld:latest` on Docker Hub. You can replace `yourusername` with your Docker Hub username and `dckr_pat` with your Docker Hub personal access token.

```bash
#!/bin/bash

USERNAME=yourusername
PASSWORD=dckr_pat
REPO=yourusername/helloworld
TAG=latest
CONFIG=config.json
MIME_TYPE=application/vnd.docker.container.image.v1+json

# Step 1: Get a bearer token
TOKEN=$(curl -s -u "$USERNAME:$PASSWORD" \
"https://auth.docker.io/token?service=registry.docker.io&scope=repository:$REPO:push,pull" \
| jq -r .token)

# Create a dummy config blob and compute its digest
echo '{"architecture":"amd64","os":"linux","config":{},"rootfs":{"type":"layers","diff_ids":[]}}' > $CONFIG
DIGEST="sha256:$(sha256sum $CONFIG | awk '{print $1}')"

# Step 2: Check if the blob exists
STATUS=$(curl -s -o /dev/null -w "%{http_code}" -I \
  -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/$REPO/blobs/$DIGEST)

if [ "$STATUS" != "200" ]; then
  # Step 3: Upload blob using monolithic upload
  LOCATION=$(curl -sI -X POST \
    -H "Authorization: Bearer $TOKEN" \
    https://registry-1.docker.io/v2/$REPO/blobs/uploads/ \
    | grep -i Location | tr -d '\r' | awk '{print $2}')

  curl -s -X PUT "$LOCATION&digest=$DIGEST" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @$CONFIG
fi

# Step 4: Upload the manifest that references the config blob
MANIFEST=$(cat <<EOF
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "config": {
    "mediaType": "$MIME_TYPE",
    "size": $(stat -c%s $CONFIG),
    "digest": "$DIGEST"
  },
  "layers": []
}
EOF
)

curl -s -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.docker.distribution.manifest.v2+json" \
  -d "$MANIFEST" \
  https://registry-1.docker.io/v2/$REPO/manifests/$TAG

echo "Pushed image to $REPO:$TAG"
```

This example pushes a minimal image with no layers. To push a complete image, repeat steps 2–3 for each layer and include the layer digests in the `layers[]` field of the manifest.

## [](#tag/delete)Deleting Images

Deleting an image involves removing its manifest by digest. You must first retrieve the manifest digest, then issue a `DELETE` request using that digest.

Only untagged manifests (or those not referenced by other tags or images) can be deleted. If a manifest is still referenced, the registry returns `403 Forbidden`.

> **Note**
>
> Manifest deletion operations may experience latency and could return a `500 Internal Server Error` during deletion. The system automatically retries the deletion in the background, so the manifest will eventually be removed. You do not need to manually retry the request.

This section outlines the basic steps to delete an image using the registry API.

1. [Get a bearer token for the repository](https://docs.docker.com/reference/api/registry/auth/).
2. [Get the manifest](#operation/GetImageManifest) using the image's tag.
3. Retrieve the `Docker-Content-Digest` header from the manifest response. This digest uniquely identifies the manifest.
4. [Delete the manifest](#operation/DeleteImageManifest) using a `DELETE` request and the digest.

The following bash script example deletes the `latest` tag from `yourusername/helloworld` on Docker Hub. Replace `yourusername` with your Docker Hub username and `dckr_pat` with your Docker Hub personal access token.

```bash
#!/bin/bash

USERNAME=yourusername
PASSWORD=dckr_pat
REPO=yourusername/helloworld
TAG=latest

# Step 1: Get a bearer token
TOKEN=$(curl -s -u "$USERNAME:$PASSWORD" \
  "https://auth.docker.io/token?service=registry.docker.io&scope=repository:$REPO:pull,push,delete" \
  | jq -r .token)

# Step 2 and 3: Get the manifest and extract the digest from response headers
DIGEST=$(curl -sI -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  https://registry-1.docker.io/v2/$REPO/manifests/$TAG \
  | grep -i Docker-Content-Digest | tr -d '\r' | awk '{print $2}')

echo "Deleting manifest with digest: $DIGEST"

# Step 4: Delete the manifest by digest
curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/$REPO/manifests/$DIGEST

echo "Deleted image: $REPO@$DIGEST"
```

This example deletes the manifest for the `latest` tag. To fully delete all references to an image, ensure no other tags or referrers point to the same manifest digest.

## [](#tag/Manifests)Manifests

Image manifests are JSON documents that describe an image: its configuration blob, the digests of each layer blob, and metadata such as media‑types and annotations.

## [](#tag/Manifests/operation/GetImageManifest)Get image manifest

Fetch the manifest identified by `name` and `reference`, where `reference` can be a tag (e.g., `latest`) or a digest (e.g., `sha256:...`).

The manifest contains metadata about the image, including configuration and layer digests. It is required for pulling images from the registry.

This endpoint requires authentication. Use the `Authorization: Bearer <token>` header.

##### path Parameters

|                   |                                                                                                     |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| namerequired      | stringExample: library/ubuntuName of the target repository                                          |
| referencerequired | stringExamples:- latest - Tag
- sha256:abc123def456... - DigestTag or digest of the target manifest |

##### header Parameters

|                       |                                                                                                                                                                                                                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Authorizationrequired | stringRFC7235-compliant authorization header (e.g., `Bearer <token>`).                                                                                                                                                                                                                                             |
| Accept                | stringMedia type(s) the client supports for the manifest.The registry supports the following media types:- application/vnd.docker.distribution.manifest.v2+json
- application/vnd.docker.distribution.manifest.list.v2+json
- application/vnd.oci.image.manifest.v1+json
- application/vnd.oci.image.index.v1+json |

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/manifests/{reference}

### Request samples

* cURL

```
# GET a manifest (by tag or digest)
curl -H "Authorization: Bearer $TOKEN" \
     -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
     https://registry-1.docker.io/v2/library/ubuntu/manifests/latest
```

### Response samples

* 200

Content type

application/vnd.docker.distribution.manifest.v2+json

`{
"schemaVersion": 2,
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"config": {
"mediaType": "application/vnd.docker.container.image.v1+json",
"size": 7023,
"digest": "sha256:123456abcdef..."
},
"layers": [
{
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
"size": 32654,
"digest": "sha256:abcdef123456..."
},
{
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
"size": 16724,
"digest": "sha256:7890abcdef12..."
}
]
}`

## [](#tag/Manifests/operation/PutImageManifest)Put image manifest

Upload an image manifest for a given tag or digest. This operation registers a manifest in a repository, allowing it to be pulled using the specified reference.

This endpoint is typically used after all layer and config blobs have been uploaded to the registry.

The manifest must conform to the expected schema and media type. For Docker image manifest schema version 2, use: `application/vnd.docker.distribution.manifest.v2+json`

Requires authentication via a bearer token with `push` scope for the target repository.

##### path Parameters

|                   |                                                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| namerequired      | stringExample: library/ubuntuName of the target Repository                                                           |
| referencerequired | stringExamples:- latest - Tag
- sha256:abc123def456... - DigestTag or digest to associate with the uploaded Manifest |

##### header Parameters

|                       |                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| Authorizationrequired | stringRFC7235-compliant authorization header (e.g., `Bearer <token>`).                                        |
| Content-Typerequired  | stringExample: application/vnd.docker.distribution.manifest.v2+jsonMedia type of the manifest being uploaded. |

##### Request Body schema: application/vnd.docker.distribution.manifest.v2+jsonrequired

|                       |                  |
| --------------------- | ---------------- |
| schemaVersionrequired | integer          |
| mediaTyperequired     | string           |
| required              | object           |
| required              | Array of objects |

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/manifests/{reference}

### Request samples

* Payload
* cURL

Content type

application/vnd.docker.distribution.manifest.v2+json

`{
"schemaVersion": 2,
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"config": {
"mediaType": "application/vnd.docker.container.image.v1+json",
"size": 7023,
"digest": "sha256:123456abcdef..."
},
"layers": [
{
"mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
"size": 32654,
"digest": "sha256:abcdef123456..."
}
]
}`

## [](#tag/Manifests/operation/HeadImageManifest)Check if manifest exists

Use this endpoint to verify whether a manifest exists by tag or digest.

This is a lightweight operation that returns only headers (no body). It is useful for:

* Checking for the existence of a specific image version
* Determining the digest or size of a manifest before downloading or deleting

This endpoint requires authentication with pull scope.

##### path Parameters

|                   |                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------- |
| namerequired      | stringExample: library/ubuntuName of the Repository                                   |
| referencerequired | stringExamples:- latest - Tag
- sha256:abc123def456... - DigestTag or digest to check |

##### header Parameters

|                       |                                                                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorizationrequired | stringBearer token for authentication                                                                                                                      |
| Accept                | stringExample: application/vnd.docker.distribution.manifest.v2+jsonMedia type of the manifest to check. The response will match one of the accepted types. |

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/manifests/{reference}

### Request samples

* cURL

```
# HEAD /v2/{name}/manifests/{reference}
curl -I \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  https://registry-1.docker.io/v2/library/ubuntu/manifests/latest
```

## [](#tag/Manifests/operation/DeleteImageManifest)Delete image manifest

Delete an image manifest from a repository by digest.

Only untagged or unreferenced manifests can be deleted. If the manifest is still referenced by a tag or another image, the registry will return `403 Forbidden`.

This operation requires `delete` access to the repository.

> **Note**
>
> Manifest deletion operations may take some time and could return a `500 Internal Server Error`. The system automatically retries the deletion in the background. Manual intervention is not required.

##### path Parameters

|                   |                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------ |
| namerequired      | stringExample: yourusername/helloworldName of the repository                               |
| referencerequired | stringExample: sha256:abc123def456...Digest of the manifest to delete (e.g., `sha256:...`) |

##### header Parameters

|                       |                                         |
| --------------------- | --------------------------------------- |
| Authorizationrequired | stringBearer token with `delete` access |

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/manifests/{reference}

### Request samples

* cURL

```
# DELETE a manifest by digest
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/yourusername/helloworld/manifests/sha256:abc123def456...
```

## [](#tag/Blobs)Blobs

Blobs are the binary objects referenced from manifests: the config JSON and one or more compressed layer tarballs.

## [](#tag/Blobs/operation/InitiateBlobUpload)Initiate blob upload or attempt cross-repository blob mount

Initiate an upload session for a blob (layer or config) in a repository.

This is the first step in uploading a blob. It returns a `Location` URL where the blob can be uploaded using `PATCH` (chunked) or `PUT` (monolithic).

Instead of uploading a blob, a client may attempt to mount a blob from another repository (if it has read access) by including the `mount` and `from` query parameters.

If successful, the registry responds with `201 Created` and the blob is reused without re-upload.

If the mount fails, the upload proceeds as usual and returns a `202 Accepted`.

You must authenticate with `push` access to the target repository.

##### path Parameters

|              |                                                            |
| ------------ | ---------------------------------------------------------- |
| namerequired | stringExample: library/ubuntuName of the target repository |

##### query Parameters

|       |                                                                                                |
| ----- | ---------------------------------------------------------------------------------------------- |
| mount | stringExample: mount=sha256:abc123def456...Digest of the blob to mount from another repository |
| from  | stringExample: from=library/busyboxSource repository to mount the blob from                    |

##### header Parameters

|                       |                                                         |
| --------------------- | ------------------------------------------------------- |
| Authorizationrequired | stringBearer token for authentication with `push` scope |

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/blobs/uploads/

### Request samples

* cURL (Initiate Standard Upload)
* cURL (Cross-Repository Blob Mount)

```
# Initiate a standard blob upload session
curl -i -X POST \
  -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/
```

## [](#tag/Blobs/operation/CheckBlobExists)Check existence of blob

Check whether a blob (layer or config) exists in the registry.

This is useful before uploading a blob to avoid duplicates.

If the blob is present, the registry returns a `200 OK` response with headers like `Content-Length` and `Docker-Content-Digest`.

If the blob does not exist, the response will be `404 Not Found`.

##### path Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| namerequired   | stringExample: library/ubuntuName of the Repository         |
| digestrequired | stringExample: sha256:abc123def4567890...Digest of the blob |

##### header Parameters

|                       |                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------- |
| Authorizationrequired | stringExample: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...Bearer token with pull or push scope |

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/blobs/{digest}

### Request samples

* cURL

```
# HEAD to check if a blob exists
curl -I \
  -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/library/ubuntu/blobs/sha256:abc123...
```

### Response samples

* 200

Content type

application/json

Example

Sample request

`{
"method": "HEAD",
"url": "/v2/library/ubuntu/blobs/sha256:abc123def4567890...",
"headers": {
"Authorization": "Bearer <token>",
"Accept": "*/*"
}
}`

## [](#tag/Blobs/operation/GetBlob)Retrieve blob

Download the blob identified by digest from the registry.

Blobs include image layers and configuration objects. Clients must use the digest from the manifest to retrieve a blob.

This endpoint may return a `307 Temporary Redirect` to a CDN or storage location. Clients must follow the redirect to obtain the actual blob content.

The blob content is typically a gzipped tarball (for layers) or JSON (for configs). The MIME type is usually `application/octet-stream`.

##### path Parameters

|                |                                                         |
| -------------- | ------------------------------------------------------- |
| namerequired   | stringExample: library/ubuntuRepository Name            |
| digestrequired | stringExample: sha256:abc123def456...Digest of the Blob |

##### header Parameters

|                       |                                                                                   |
| --------------------- | --------------------------------------------------------------------------------- |
| Authorizationrequired | stringExample: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...Bearer token with pull scope |

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/blobs/{digest}

### Request samples

* cURL

```
# GET (download) a blob
curl -L \
  -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/library/ubuntu/blobs/sha256:abc123... \
  -o layer.tar.gz
```

### Response samples

* 200

Content type

application/octet-stream

```
<binary data not shown>
```

## [](#tag/Blobs/operation/GetBlobUploadStatus)Get blob upload status

Retrieve the current status of an in-progress blob upload.

This is useful for:

* Resuming an interrupted upload
* Determining how many bytes have been accepted so far
* Retrying from the correct offset in chunked uploads

The response includes the `Range` header indicating the byte range received so far, and a `Docker-Upload-UUID` for identifying the session.

##### path Parameters

|              |                                              |
| ------------ | -------------------------------------------- |
| namerequired | stringExample: library/ubuntuRepository Name |
| uuidrequired | stringExample: abc123Upload session UUID     |

##### header Parameters

|                       |                                     |
| --------------------- | ----------------------------------- |
| Authorizationrequired | stringExample: Bearer eyJhbGciOi... |

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/blobs/uploads/{uuid}

### Request samples

* cURL

```
# GET upload status
curl -I \
  -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/abc123
```

## [](#tag/Blobs/operation/CompleteBlobUpload)Complete blob upload

Complete the upload of a blob by finalizing an upload session.

This request must include the `digest` query parameter and optionally the last chunk of data. When the registry receives this request, it verifies the digest and stores the blob.

This endpoint supports:

* Monolithic uploads (upload entire blob in this request)
* Finalizing chunked uploads (last chunk plus `digest`)

##### path Parameters

|              |                                                                         |
| ------------ | ----------------------------------------------------------------------- |
| namerequired | stringExample: library/ubuntuRepository name                            |
| uuidrequired | stringExample: abc123Upload session UUID returned from the POST request |

##### query Parameters

|                |                                                                     |
| -------------- | ------------------------------------------------------------------- |
| digestrequired | stringExample: digest=sha256:abcd1234...Digest of the uploaded blob |

##### header Parameters

|                       |                                     |
| --------------------- | ----------------------------------- |
| Authorizationrequired | stringExample: Bearer eyJhbGciOi... |

##### Request Body schema: application/octet-streamoptional

string \<binary>

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/blobs/uploads/{uuid}

### Request samples

* Payload
* cURL

Content type

application/octet-stream

```
<binary data not shown>
```

## [](#tag/Blobs/operation/UploadBlobChunk)Upload blob chunk

Upload a chunk of a blob to an active upload session.

Use this method for **chunked uploads**, especially for large blobs or when resuming interrupted uploads.

The client sends binary data using `PATCH`, optionally including a `Content-Range` header.

After each chunk is accepted, the registry returns a `202 Accepted` response with:

* `Range`: current byte range stored
* `Docker-Upload-UUID`: identifier for the upload session
* `Location`: URL to continue the upload or finalize with `PUT`

##### path Parameters

|              |                                              |
| ------------ | -------------------------------------------- |
| namerequired | stringExample: library/ubuntuRepository name |
| uuidrequired | stringExample: abc123Upload session UUID     |

##### header Parameters

|                       |                                                                          |
| --------------------- | ------------------------------------------------------------------------ |
| Authorizationrequired | stringExample: Bearer eyJhbGciOi...                                      |
| Content-Range         | stringExample: bytes 0-65535Optional. Byte range of the chunk being sent |

##### Request Body schema: application/octet-streamrequired

string \<binary>

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/blobs/uploads/{uuid}

### Request samples

* Payload
* cURL

Content type

application/octet-stream

```
<binary data not shown>
```

## [](#tag/Blobs/operation/CancelBlobUpload)Cancel blob upload

Cancel an in-progress blob upload session.

This operation discards any data that has been uploaded and invalidates the upload session.

Use this when:

* An upload fails or is aborted mid-process
* The client wants to clean up unused upload sessions

After cancellation, the UUID is no longer valid and a new `POST` must be issued to restart the upload.

##### path Parameters

|              |                                                     |
| ------------ | --------------------------------------------------- |
| namerequired | stringExample: library/ubuntuName of the repository |
| uuidrequired | stringExample: abc123Upload session UUID            |

##### header Parameters

|                       |                                     |
| --------------------- | ----------------------------------- |
| Authorizationrequired | stringExample: Bearer eyJhbGciOi... |

### Responses

Docker Hub registry API

https\://registry-1.docker.io/v2/{name}/blobs/uploads/{uuid}

### Request samples

* cURL

```
# DELETE – cancel an upload session
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://registry-1.docker.io/v2/library/ubuntu/blobs/uploads/abc123`
```

----
url: https://docs.docker.com/engine/release-notes/18.01/
----

# Docker Engine 18.01 release notes

***

Table of contents

***

## [18.01.0-ce](#18010-ce)

2018-01-10

### [Builder](#builder)

* Fix files not being deleted if user-namespaces are enabled [moby/moby#35822](https://github.com/moby/moby/pull/35822)

- Add support for expanding environment-variables in `docker commit --change ...` [moby/moby#35582](https://github.com/moby/moby/pull/35582)

### [Client](#client)

* Return errors from client in stack deploy configs [docker/cli#757](https://github.com/docker/cli/pull/757)

- Fix description of filter flag in prune commands [docker/cli#774](https://github.com/docker/cli/pull/774)

* Add "pid" to unsupported options list [docker/cli#768](https://github.com/docker/cli/pull/768)
* Add support for experimental Cli configuration [docker/cli#758](https://github.com/docker/cli/pull/758)
* Add support for generic resources to bash completion [docker/cli#749](https://github.com/docker/cli/pull/749)

- Fix error in zsh completion script for docker exec [docker/cli#751](https://github.com/docker/cli/pull/751)

* Add a debug message when client closes websocket attach connection [moby/moby#35720](https://github.com/moby/moby/pull/35720)

- Fix bash completion for `"docker swarm"` [docker/cli#772](https://github.com/docker/cli/pull/772)

### [Documentation](#documentation)

* Correct references to `--publish` long syntax in docs [docker/cli#746](https://github.com/docker/cli/pull/746)
* Corrected descriptions for MAC\_ADMIN and MAC\_OVERRIDE [docker/cli#761](https://github.com/docker/cli/pull/761)
* Updated developer doc to explain external CLI [moby/moby#35681](https://github.com/moby/moby/pull/35681)

- Fix `"on-failure"` restart policy being documented as "failure" [docker/cli#754](https://github.com/docker/cli/pull/754)
- Fix anchors to "Storage driver options" [docker/cli#748](https://github.com/docker/cli/pull/748)

### [Experimental](#experimental)

* Add kubernetes support to `docker stack` command [docker/cli#721](https://github.com/docker/cli/pull/721)

- Don't append the container id to custom directory checkpoints. [moby/moby#35694](https://github.com/moby/moby/pull/35694)

### [Logging](#logging)

* Fix daemon crash when using the GELF log driver over TCP when the GELF server goes down [moby/moby#35765](https://github.com/moby/moby/pull/35765)

- Fix awslogs batch size calculation for large logs [moby/moby#35726](https://github.com/moby/moby/pull/35726)

### [Networking](#networking)

* Windows: Fix to allow docker service to start on Windows VM [docker/libnetwork#1916](https://github.com/docker/libnetwork/pull/1916)
* Fix for docker intercepting DNS requests on ICS network [docker/libnetwork#2014](https://github.com/docker/libnetwork/pull/2014)

- Windows: Added a new network creation driver option [docker/libnetwork#2021](https://github.com/docker/libnetwork/pull/2021)

### [Runtime](#runtime)

* Validate Mount-specs on container start to prevent missing host-path [moby/moby#35833](https://github.com/moby/moby/pull/35833)

- Fix overlay2 storage driver inside a user namespace [moby/moby#35794](https://github.com/moby/moby/pull/35794)

* Zfs: fix busy error on container stop [moby/moby#35674](https://github.com/moby/moby/pull/35674)

- Fix health checks not using the container's working directory [moby/moby#35845](https://github.com/moby/moby/pull/35845)
- Fix VFS graph driver failure to initialize because of failure to setup fs quota [moby/moby#35827](https://github.com/moby/moby/pull/35827)
- Fix containerd events being processed twice [moby/moby#35896](https://github.com/moby/moby/pull/35896)

### [Swarm mode](#swarm-mode)

* Fix published ports not being updated if a service has the same number of host-mode published ports with Published Port 0 [docker/swarmkit#2376](https://github.com/docker/swarmkit/pull/2376)

- Make the task termination order deterministic [docker/swarmkit#2265](https://github.com/docker/swarmkit/pull/2265)

----
url: https://docs.docker.com/reference/cli/docker/mcp/
----

# docker mcp

***

| Description | Manage MCP servers and clients |
| ----------- | ------------------------------ |

## [Description](#description)

The MCP Gateway is Docker's open-source enterprise solution for orchestrating Model Context Protocol (MCP) servers and clients.

For more information see [Docker MCP](/ai/mcp-gateway/) and the public [GitHub repository](https://github.com/docker/mcp-gateway).

## [Options](#options)

| Option          | Default | Description                        |
| --------------- | ------- | ---------------------------------- |
| `-v, --version` |         | Print version information and quit |

## [Subcommands](#subcommands)

| Command                                                                           | Description                             |
| --------------------------------------------------------------------------------- | --------------------------------------- |
| [`docker mcp catalog`](https://docs.docker.com/reference/cli/docker/mcp/catalog/) | Manage MCP server OCI catalogs          |
| [`docker mcp client`](https://docs.docker.com/reference/cli/docker/mcp/client/)   | Manage MCP clients                      |
| [`docker mcp feature`](https://docs.docker.com/reference/cli/docker/mcp/feature/) | Manage experimental features            |
| [`docker mcp gateway`](https://docs.docker.com/reference/cli/docker/mcp/gateway/) | Manage the MCP Server gateway           |
| [`docker mcp profile`](https://docs.docker.com/reference/cli/docker/mcp/profile/) | Manage profiles                         |
| [`docker mcp secret`](https://docs.docker.com/reference/cli/docker/mcp/secret/)   | Manage secrets in the local OS Keychain |
| [`docker mcp server`](https://docs.docker.com/reference/cli/docker/mcp/server/)   | Manage servers                          |
| [`docker mcp tools`](https://docs.docker.com/reference/cli/docker/mcp/tools/)     | Manage tools                            |
| [`docker mcp version`](https://docs.docker.com/reference/cli/docker/mcp/version/) | Show the version information            |

----
url: https://docs.docker.com/reference/cli/docker/model/context/inspect/
----

# docker model context inspect

***

| Description | Display detailed information about one or more contexts |
| ----------- | ------------------------------------------------------- |
| Usage       | `docker model context inspect NAME [NAME...]`           |

## [Description](#description)

Display detailed information about one or more contexts

----
url: https://docs.docker.com/reference/cli/docker/scout/compare/
----

# docker scout compare

***

| Description                                                               | Compare two images and display differences (experimental)                         |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Usage                                                                     | `docker scout compare --to IMAGE\|DIRECTORY\|ARCHIVE [IMAGE\|DIRECTORY\|ARCHIVE]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker scout diff`                                                               |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

The `docker scout compare` command analyzes two images and displays a comparison.

> This command is **experimental** and its behaviour might change in the future

The intended use of this command is to compare two versions of the same image. For instance, when a new image is built and compared to the version running in production.

If no image is specified, the most recently built image is used as a comparison target.

The following artifact types are supported:

* Images
* OCI layout directories
* Tarball archives, as created by `docker save`
* Local directory or file

By default, the tool expects an image reference, such as:

* `redis`
* `curlimages/curl:7.87.0`
* `mcr.microsoft.com/dotnet/runtime:7.0`

If the artifact you want to analyze is an OCI directory, a tarball archive, a local file or directory, or if you want to control from where the image will be resolved, you must prefix the reference with one of the following:

* `image://` (default) use a local image, or fall back to a registry lookup
* `local://` use an image from the local image store (don't do a registry lookup)
* `registry://` use an image from a registry (don't use a local image)
* `oci-dir://` use an OCI layout directory
* `archive://` use a tarball archive, as created by `docker save`
* `fs://` use a local directory or file
* `sbom://` SPDX file or in-toto attestation file with SPDX predicate or `syft` json SBOM file

## [Options](#options)

| Option                | Default             | Description                                                                                                                                                          |
| --------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-x, --exit-on`       |                     | Comma separated list of conditions to fail the action step if worse or changed, options are: vulnerability, policy, package                                          |
| `--format`            | `text`              | Output format of the generated vulnerability report: - text: default output, plain text with or without colors depending on the terminal - markdown: Markdown output |
| `--hide-policies`     |                     | Hide policy status from the output                                                                                                                                   |
| `--ignore-base`       |                     | Filter out CVEs introduced from base image                                                                                                                           |
| `--ignore-suppressed` |                     | Filter CVEs found in Scout exceptions based on the specified exception scope                                                                                         |
| `--ignore-unchanged`  |                     | Filter out unchanged packages                                                                                                                                        |
| `--multi-stage`       |                     | Show packages from multi-stage Docker builds                                                                                                                         |
| `--only-fixed`        |                     | Filter to fixable CVEs                                                                                                                                               |
| `--only-package-type` |                     | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc)                                                                                   |
| `--only-policy`       |                     | Comma separated list of policies to evaluate                                                                                                                         |
| `--only-severity`     |                     | Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by                                                                      |
| `--only-stage`        |                     | Comma separated list of multi-stage Docker build stage names                                                                                                         |
| `--only-unfixed`      |                     | Filter to unfixed CVEs                                                                                                                                               |
| `--only-vex-affected` |                     | Filter CVEs by VEX statements with status not affected                                                                                                               |
| `--org`               |                     | Namespace of the Docker organization                                                                                                                                 |
| `-o, --output`        |                     | Write the report to a file                                                                                                                                           |
| `--platform`          |                     | Platform of image to analyze                                                                                                                                         |
| `--ref`               |                     | Reference to use if the provided tarball contains multiple references. Can only be used with archive                                                                 |
| `--to`                |                     | Image, directory, or archive to compare to                                                                                                                           |
| `--to-env`            |                     | Name of environment to compare to                                                                                                                                    |
| `--to-latest`         |                     | Latest image processed to compare to                                                                                                                                 |
| `--to-ref`            |                     | Reference to use if the provided tarball contains multiple references. Can only be used with archive.                                                                |
| `--vex-author`        | `[<.*@docker.com>]` | List of VEX statement authors to accept                                                                                                                              |
| `--vex-location`      |                     | File location of directory or file containing VEX statements                                                                                                         |

## [Examples](#examples)

### [Compare the most recently built image to the latest tag](#compare-the-most-recently-built-image-to-the-latest-tag)

```console
$ docker scout compare --to namespace/repo:latest
```

### [Compare local build to the same tag from the registry](#compare-local-build-to-the-same-tag-from-the-registry)

```console
$ docker scout compare local://namespace/repo:latest --to registry://namespace/repo:latest
```

### [Ignore base images](#ignore-base-images)

```console
$ docker scout compare --ignore-base --to namespace/repo:latest namespace/repo:v1.2.3-pre
```

### [Generate a markdown output](#generate-a-markdown-output)

```console
$ docker scout compare --format markdown --to namespace/repo:latest namespace/repo:v1.2.3-pre
```

### [Only compare maven packages and only display critical vulnerabilities for maven packages](#only-compare-maven-packages-and-only-display-critical-vulnerabilities-for-maven-packages)

```console
$ docker scout compare --only-package-type maven --only-severity critical --to namespace/repo:latest namespace/repo:v1.2.3-pre
```

### [Show all policy results for both images](#show-all-policy-results-for-both-images)

```console
docker scout compare --to namespace/repo:latest namespace/repo:v1.2.3-pre
```

----
url: https://docs.docker.com/reference/samples/gitea/
----

# Gitea samples

| Name                                                                                       | Description               |
| ------------------------------------------------------------------------------------------ | ------------------------- |
| [Gitea / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/gitea-postgres) | A sample setup for Gitea. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/reference/cli/docker/container/attach/
----

# docker container attach

***

| Description                                                               | Attach local standard input, output, and error streams to a running container |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Usage                                                                     | `docker container attach [OPTIONS] CONTAINER`                                 |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker attach`                                                               |

## [Description](#description)

Use `docker attach` to attach your terminal's standard input, output, and error (or any combination of the three) to a running container using the container's ID or name. This lets you view its output or control it interactively, as though the commands were running directly in your terminal.

> Note
>
> The `attach` command displays the output of the container's `ENTRYPOINT` and `CMD` process. This can appear as if the attach command is hung when in fact the process may simply not be writing any output at that time.

You can attach to the same contained process multiple times simultaneously, from different sessions on the Docker host.

To stop a container, use `CTRL-c`. This key sequence sends `SIGKILL` to the container. If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` to the container. If the container was run with `-i` and `-t`, you can detach from a container and leave it running using the `CTRL-p CTRL-q` key sequence.

> Note
>
> A process running as PID 1 inside a container is treated specially by Linux: it ignores any signal with the default action. So, the process doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so.

You can't redirect the standard input of a `docker attach` command while attaching to a TTY-enabled container (using the `-i` and `-t` options).

While a client is connected to container's `stdio` using `docker attach`, Docker uses a \~1MB memory buffer to maximize the throughput of the application. Once this buffer is full, the speed of the API connection is affected, and so this impacts the output process' writing speed. This is similar to other applications like SSH. Because of this, it isn't recommended to run performance-critical applications that generate a lot of output in the foreground over a slow client connection. Instead, use the `docker logs` command to get access to the logs.

## [Options](#options)

| Option                          | Default | Description                                         |
| ------------------------------- | ------- | --------------------------------------------------- |
| [`--detach-keys`](#detach-keys) |         | Override the key sequence for detaching a container |
| `--no-stdin`                    |         | Do not attach STDIN                                 |
| `--sig-proxy`                   | `true`  | Proxy all received signals to the process           |

## [Examples](#examples)

### [Attach to and detach from a running container](#attach-to-and-detach-from-a-running-container)

The following example starts an Alpine container running `top` in detached mode, then attaches to the container;

```console
$ docker run -d --name topdemo alpine top -b

$ docker attach topdemo

Mem: 2395856K used, 5638884K free, 2328K shrd, 61904K buff, 1524264K cached
CPU:   0% usr   0% sys   0% nic  99% idle   0% io   0% irq   0% sirq
Load average: 0.15 0.06 0.01 1/567 6
  PID  PPID USER     STAT   VSZ %VSZ CPU %CPU COMMAND
    1     0 root     R     1700   0%   3   0% top -b
```

As the container was started without the `-i`, and `-t` options, signals are forwarded to the attached process, which means that the default `CTRL-p CTRL-q` detach key sequence produces no effect, but pressing `CTRL-c` terminates the container:

```console
<...>
  PID  PPID USER     STAT   VSZ %VSZ CPU %CPU COMMAND
    1     0 root     R     1700   0%   7   0% top -b
^P^Q
^C

$ docker ps -a --filter name=topdemo

CONTAINER ID   IMAGE     COMMAND    CREATED          STATUS                       PORTS     NAMES
96254a235bd6   alpine    "top -b"   44 seconds ago   Exited (130) 8 seconds ago             topdemo
```

Repeating the example above, but this time with the `-i` and `-t` options set;

```console
$ docker run -dit --name topdemo2 alpine /usr/bin/top -b
```

Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read escape sequence"), the Docker CLI is handling the detach sequence, and the `attach` command is detached from the container. Checking the container's status with `docker ps` shows that the container is still running in the background:

```console
$ docker attach topdemo2

Mem: 2405344K used, 5629396K free, 2512K shrd, 65100K buff, 1524952K cached
CPU:   0% usr   0% sys   0% nic  99% idle   0% io   0% irq   0% sirq
Load average: 0.12 0.12 0.05 1/594 6
  PID  PPID USER     STAT   VSZ %VSZ CPU %CPU COMMAND
    1     0 root     R     1700   0%   3   0% top -b
read escape sequence

$ docker ps -a --filter name=topdemo2

CONTAINER ID   IMAGE     COMMAND    CREATED          STATUS          PORTS     NAMES
fde88b83c2c2   alpine    "top -b"   22 seconds ago   Up 21 seconds             topdemo2
```

### [Get the exit code of the container's command](#get-the-exit-code-of-the-containers-command)

And in this second example, you can see the exit code returned by the `bash` process is returned by the `docker attach` command to its caller too:

```console
$ docker run --name test -dit alpine
275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab

$ docker attach test
/# exit 13

$ echo $?
13

$ docker ps -a --filter name=test

CONTAINER ID   IMAGE     COMMAND     CREATED              STATUS                       PORTS     NAMES
a2fe3fd886db   alpine    "/bin/sh"   About a minute ago   Exited (13) 40 seconds ago             test
```

----
url: https://docs.docker.com/reference/compose-file/fragments/
----

# Fragments

***

Table of contents

***

With Compose, you can use built-in [YAML](https://www.yaml.org/spec/1.2/spec.html#id2765878) features to make your Compose file neater and more efficient. Anchors and aliases let you create reusable blocks. This is useful if you start to find common configurations that span multiple services. Having reusable blocks minimizes potential mistakes.

Anchors are created using the `&` sign. The sign is followed by an alias name. You can use this alias with the `*` sign later to reference the value following the anchor. Make sure there is no space between the `&` and the `*` characters and the following alias name.

You can use more than one anchor and alias in a single Compose file.

## [Example 1](#example-1)

```yml
volumes:
  db-data: &default-volume
    driver: default
  metrics: *default-volume
```

In the example above, a `default-volume` anchor is created based on the `db-data` volume. It is later reused by the alias `*default-volume` to define the `metrics` volume.

Anchor resolution takes place before [variables interpolation](https://docs.docker.com/reference/compose-file/interpolation/), so variables can't be used to set anchors or aliases.

## [Example 2](#example-2)

```yml
services:
  first:
    image: my-image:latest
    environment: &env
      - CONFIG_KEY
      - EXAMPLE_KEY
      - DEMO_VAR
  second:
    image: another-image:latest
    environment: *env
```

If you have an anchor that you want to use in more than one service, use it in conjunction with an [extension](https://docs.docker.com/reference/compose-file/extension/) to make your Compose file easier to maintain.

## [Example 3](#example-3)

You may want to partially override values. Compose follows the rule outlined by [YAML merge type](https://yaml.org/type/merge.html).

In the following example, `metrics` volume specification uses alias to avoid repetition but overrides `name` attribute:

```yml
services:
  backend:
    image: example/database
    volumes:
      - db-data
      - metrics
volumes:
  db-data: &default-volume
    driver: default
    name: "data"
  metrics:
    <<: *default-volume
    name: "metrics"
```

## [Example 4](#example-4)

You can also extend the anchor to add additional values.

```yml
services:
  first:
    image: my-image:latest
    environment: &env
      FOO: BAR
      ZOT: QUIX
  second:
    image: another-image:latest
    environment:
      <<: *env
      YET_ANOTHER: VARIABLE
```

> Note
>
> [YAML merge](https://yaml.org/type/merge.html) only applies to mappings, and can't be used with sequences.

In example above, the environment variables must be declared using the `FOO: BAR` mapping syntax, while the sequence syntax `- FOO=BAR` is only valid when no fragments are involved.

----
url: https://docs.docker.com/guides/lab-dhi-node/
----

[Lab: Migrating a Node App to Docker Hardened Images](https://docs.docker.com/guides/lab-dhi-node/)

Hands-on lab: Replace a Node.js base image with a Docker Hardened Image. Analyze CVEs with Docker Scout, rewrite the Dockerfile to use multi-stage builds with DHI, and explore SBOMs, VEX, and compliance attestations.

Labs Docker Hardened Images

30 minutes

Resources:

* [Docker Hardened Images](/dhi/)
* [Docker Scout docs](/scout/)
* [Build attestations](/build/metadata/attestations/)
* [Labspace repository](https://github.com/dockersamples/labspace-dhi-node)

[« Back to all guides](/guides/)

# Lab: Migrating a Node App to Docker Hardened Images

***

Table of contents

***

Migrate a Node.js application from a standard `node:24-trixie-slim` base image to a Docker Hardened Image. You'll measure the before-and-after impact on CVE count, image size, and policy compliance using Docker Scout, then explore the supply chain attestations DHI ships with every image.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-dhi-node up -d
   ```

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

By the end of this Labspace, you will have completed the following:

* Analyze a Node.js container image with Docker Scout to identify CVE and policy failures
* Rewrite a Dockerfile to use a multi-stage build with DHI dev and runtime variants
* Compare image size and vulnerability counts before and after the migration
* Inspect supply chain attestations included with Docker Hardened Images (SBOMs, SLSA, VEX)
* Export VEX documents for integration with external scanners such as Grype or Trivy

## [Modules](#modules)

| # | Module                                   | Description                                                                     |
| - | ---------------------------------------- | ------------------------------------------------------------------------------- |
| 1 | Introduction                             | Overview of Docker Hardened Images and their security benefits                  |
| 2 | Setup                                    | Perform setup tasks required for the lab.                                       |
| 3 | Analyzing the Starting Image             | Build the app, scan it with Docker Scout, and review failing policies           |
| 4 | Migrating to DHI                         | Rewrite the Dockerfile with multi-stage DHI build and compare results           |
| 5 | DHI Attestations and Scanner Integration | Inspect SBOMs, FIPS attestations, STIG scans, and export VEX for external tools |

----
url: https://docs.docker.com/docker-hub/repos/manage/hub-images/push/
----

# Push images to a repository

***

***

To add content to a repository on Docker Hub, you need to tag your Docker image and then push it to your repository. This process lets you share your images with others or use them in different environments.

1. Tag your Docker image.

   The `docker tag` command assigns a tag to your Docker image, which includes your Docker Hub namespace and the repository name. The general syntax is:

   ```console
   $ docker tag [SOURCE_IMAGE[:TAG]] [NAMESPACE/REPOSITORY[:TAG]]
   ```

   Example:

   If your local image is called `my-app` and you want to tag it for the repository `my-namespace/my-repo` with the tag `v1.0`, run:

   ```console
   $ docker tag my-app my-namespace/my-repo:v1.0
   ```

2. Push the image to Docker Hub.

   Use the `docker push` command to upload your tagged image to the specified repository on Docker Hub.

   Example:

   ```console
   $ docker push my-namespace/my-repo:v1.0
   ```

   This command pushes the image tagged `v1.0` to the `my-namespace/my-repo` repository.

3. Verify the image on Docker Hub.

----
url: https://docs.docker.com/docker-hub/release-notes/
----

# Docker Hub release notes

***

Table of contents

***

Here you can learn about the latest changes, new features, bug fixes, and known issues for each Docker Hub release.

## [2026-05-20](#2026-05-20)

### [Infrastructure updates](#infrastructure-updates)

* Docker Hub has added Amazon CloudFront as a CDN for image pushes and pulls, improving reliability. You may see a new domain, `production.cloudfront.docker.com`, in your network logs. TLS certificates for this domain are issued by Amazon Trust Services.

  Most users are unaffected. You may need to take action if your environment uses an egress firewall with a domain allowlist, a TLS inspection proxy, or a managed CA trust store. See the [Docker Desktop allowlist](https://docs.docker.com/desktop/setup/allow-list/) for updated domain requirements. If you see TLS errors, ensure your trust store includes the [Amazon Trust Services Root CAs](https://www.amazontrust.com/repository/). If you're a paid subscriber, you can [contact Docker Support](https://hub.docker.com/support/contact/) if you need updated TLS certificate details or the issue persists.

## [2026-05-06](#2026-05-06)

### [Deprecation notice](#deprecation-notice)

* [Docker Hub Automated Builds](https://docs.docker.com/docker-hub/repos/manage/builds/) is being deprecated. Existing accounts will have access until April 1, 2027. See [migration options](https://docs.docker.com/docker-hub/repos/manage/builds/migrate/) for guides on migrating to GitHub Actions or Bitbucket Pipelines.

## [2026-02-13](#2026-02-13)

### [New](#new)

* Administrators can now prevent creating public repositories within organization namespaces using the [Disable public repositories](https://docs.docker.com/docker-hub/settings/#disable-creation-of-public-repos) setting.

## [2025-02-18](#2025-02-18)

### [New](#new-1)

* You can delete images and image indexes using [Image Management](https://docs.docker.com/docker-hub/repos/manage/hub-images/manage/).

## [2024-12-12](#2024-12-12)

### [New](#new-2)

* The AI Catalog in Docker Hub is available directly through Docker Desktop.

## [2024-03-23](#2024-03-23)

### [New](#new-3)

* You can tag Docker Hub repositories with [categories](https://docs.docker.com/docker-hub/repos/manage/information/#repository-categories).

## [2023-12-11](#2023-12-11)

* The Advanced Image Management feature, along with the corresponding API endpoints, has been retired. See [docker/roadmap#534](https://github.com/docker/roadmap/issues/534).

  The following API endpoints have been removed:

  ```text
  /namespaces/{namespace}/repositories/{repository}/images
  /namespaces/{namespace}/repositories/{repository}/images/{digest}/tags
  /namespaces/{namespace}/repositories/{repository}/images-summary
  /namespaces/{namespace}/delete-images
  ```

## [2023-08-28](#2023-08-28)

* Organizations with SSO enabled can assign members to roles, organizations, and teams with [SCIM role mapping](https://docs.docker.com/enterprise/security/provisioning/scim/#set-up-role-mapping).

## [2023-07-26](#2023-07-26)

### [New](#new-4)

* Organizations can assign the [editor role](https://docs.docker.com/enterprise/security/roles-and-permissions/) to members to grant additional permissions without full administrative access.

## [2023-05-09](#2023-05-09)

### [New](#new-5)

* Docker Business subscribers can now [create a company](https://docs.docker.com/admin/company/new-company/) in Docker Hub to manage organizations and settings.

## [2023-03-07](#2023-03-07)

### [New](#new-6)

* You can now automatically sync user updates with your Docker organizations and teams with [Group Mapping](https://docs.docker.com/enterprise/security/provisioning/scim/group-mapping/) for SSO and SCIM provisioning.

## [2022-12-12](#2022-12-12)

### [New](#new-7)

* The new domain audit feature lets you audit your domains for users who aren't a member of your organization.

## [2022-09-26](#2022-09-26)

### [New](#new-8)

* The new [autobuild feature](https://docs.docker.com/docker-hub/repos/manage/builds/manage-builds/#check-your-active-builds) lets you view your in-progress logs every 30 seconds instead of when the build is complete.

## [2022-09-21](#2022-09-21)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* In Docker Hub, you can now download a [registry.json](https://docs.docker.com/enterprise/security/enforce-sign-in/) file or copy the commands to create a registry.json file to enforce sign-in for your organization.

## [2022-09-19](#2022-09-19)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

* You can now [export a CSV file of members](https://docs.docker.com/admin/organization/manage/members/#export-members-csv-file) from organizations that you own.

## [2022-07-22](#2022-07-22)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

* You can now invite members to your organization with a CSV file containing their email addresses. The CSV file can either be a file you create for this specific purpose or one that’s extracted from another in-house system.

## [2022-07-19](#2022-07-19)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-3)

* SCIM is now available for organizations with a Docker Business subscription using an Entra ID (formerly Azure AD) identity provider.

## [2022-06-23](#2022-06-23)

### [New](#new-9)

* With [SCIM](https://docs.docker.com/enterprise/security/provisioning/scim/), you can manage users within your Okta identity provider (IdP). In addition, you can enable SCIM on organizations that are part of the Docker Business subscription.

## [2022-05-24](#2022-05-24)

### [New](#new-10)

* [Registry Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/) is now available for all Docker Business subscriptions. When enabled, your users can access specific registries in Docker Hub.

## [2022-05-03](#2022-05-03)

### [New](#new-11)

* Organization owners can [invite new members](https://docs.docker.com/admin/organization/manage/members/#invite-members) to an organization via Docker ID or email address.

## [2021-11-15](#2021-11-15)

### [New](#new-12)

* You can now purchase or upgrade to a Docker Business subscription using a credit card. To learn more, see [Upgrade your subscription](https://docs.docker.com/subscription/change/).

## [2021-08-31](#2021-08-31)

### [New](#new-13)

Docker has [announced](https://www.docker.com/blog/updating-product-subscriptions/) updates and extensions to the product subscriptions to increase productivity, collaboration, and added security for our developers and businesses. Docker subscription tiers now include Personal, Pro, Team, and Business.

The updated [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) includes a change to the terms for **Docker Desktop**.

* Docker Desktop **remains free** for small businesses (fewer than 250 employees AND less than $10 million in annual revenue), personal use, education, and non-commercial open source projects.

* It requires a paid subscription (**Pro, Team, or Business**), for as little as $5 a month, for professional use in larger enterprises.

* The effective date of these terms is August 31, 2021. There is a grace period until January 31, 2022 for those that will require a paid subscription to use Docker Desktop.

* The Docker Pro and Docker Team subscriptions now **include commercial use** of Docker Desktop.

* The existing Docker Free subscription has been renamed **Docker Personal**.

* **No changes** to Docker Engine or any other upstream **open source** Docker or Moby project.

  To understand how these changes affect you, read the [FAQs](https://www.docker.com/pricing/faq). For more information, see [Docker subscription overview](https://docs.docker.com/subscription/).

## [2021-05-05](#2021-05-05)

### [Enhancement](#enhancement)

When managing the content of your repositories, you can now filter the results based on the currentness of the tags and more easily identify your untagged images.

For Docker Hub API documentation, see [Docker Hub API Reference](https://docs.docker.com/reference/api/hub/latest/#operation/GetNamespacesRepositoriesImages).

## [2021-04-13](#2021-04-13)

### [Enhancement](#enhancement-1)

The **Billing Details** page now shows any organizations you own, in addition to your personal account. This allows you to clearly identify the billing details of your chosen namespace, and enables you to switch between your personal and your organization accounts to view or update the details.

## [2021-04-09](#2021-04-09)

### [Enhancement](#enhancement-2)

You can now specify any email address to receive billing-related emails for your organization. The email address doesn't have to be associated with an organization owner account. You must be an owner of the organization to update any billing details.

To change the email address receiving billing-related emails, log into Docker Hub and navigate to the **Billing** tab of your organization. Select **Payment Methods** > **Billing Information**. Enter the new email address that you'd like to use in the **Email** field. Click **Update** for the changes to take effect.

For details on how to update your billing information, see [Update billing information](https://docs.docker.com/billing/).

## [2021-03-22](#2021-03-22)

### [New feature](#new-feature)

**Advanced Image Management dashboard**

Docker introduces the Advanced Image Management dashboard that enables you to view and manage Docker images in your repositories.

## [2021-01-25](#2021-01-25)

### [New feature](#new-feature-1)

Docker introduces Audit logs, a new feature that allows team owners to view a list of activities that occur at organization and repository levels. This feature begins tracking the activities from the release date, that is, **from 25 January 2021**.

For more information about this feature and for instructions on how to use it, see [Activity logs](https://docs.docker.com/admin/activity-logs/).

## [2020-11-10](#2020-11-10)

### [New feature](#new-feature-2)

The **Repositories** view now shows which images have gone stale because they haven't been pulled or pushed recently. For more information, see [repository tags](https://docs.docker.com/docker-hub/repos/manage/access/#view-repository-tags).

## [2020-10-07](#2020-10-07)

### [New feature](#new-feature-3)

Docker introduces Hub Vulnerability Scanning which enables you to automatically scan Docker images for vulnerabilities using Snyk. For more information, see [Hub Vulnerability Scanning](https://docs.docker.com/docker-hub/repos/manage/vulnerability-scanning/).

## [2020-05-14](#2020-05-14)

### [New features](#new-features)

* Docker has announced a new, per-seat pricing model to accelerate developer workflows for cloud-native development. The previous private repository/concurrent autobuild-based plans have been replaced with new **Pro** and **Team** plans that include unlimited private repositories. For more information, see [Docker subscription](https://docs.docker.com/subscription/).

* Docker has enabled download rate limits for downloads and pull requests on Docker Hub. This caps the number of objects that users can download within a specified timeframe. For more information, see [Usage and limits](https://docs.docker.com/docker-hub/usage/).

## [2019-11-04](#2019-11-04)

### [Enhancements](#enhancements)

* The [repositories page](https://docs.docker.com/docker-hub/repos/) and all related settings and tabs have been updated and moved from `cloud.docker.com` to `hub.docker.com`. You can access the page at its new URL: <https://hub.docker.com/repositories>.

### [Known Issues](#known-issues)

* Scan results don't appear for some official images.

## [2019-10-21](#2019-10-21)

### [New features](#new-features-1)

* **Beta:** Docker Hub now supports two-factor authentication (2FA). Enable it in your account settings, under the **[Security](https://hub.docker.com/settings/security)** section.

  > If you lose both your 2FA authentication device and recovery code, you may not be able to recover your account.

### [Enhancements](#enhancements-1)

* As a security measure, when two-factor authentication is enabled, the Docker CLI requires a personal access token instead of a password to log in.

### [Known Issues](#known-issues-1)

* Scan results don't appear for some official images.

## [2019-10-02](#2019-10-02)

### [Enhancements](#enhancements-2)

* You can now manage teams and members straight from your [organization page](https://hub.docker.com/orgs). Each organization page now breaks down into these tabs:

  * **New:** Members - manage your members directly from this page (delete, add, or open their teams)
  * **New:** Teams - search by team or username, and open up any team page to manage the team
  * **New:** Invitees (conditional tab, only if an invite exists) - resend or remove invitations from this tab
  * Repositories
  * Settings
  * Billing

### [Bug fixes](#bug-fixes)

* Fixed an issue where Kinematic could not connect and log in to Docker Hub.

### [Known Issues](#known-issues-2)

* Scan results don't appear for some official images.

## [2019-09-19](#2019-09-19)

### [New features](#new-features-2)

* You can now [create personal access tokens](/security/access-tokens/) in Docker Hub and use them to authenticate from the Docker CLI. Find them in your account settings, under the new **[Security](https://hub.docker.com/settings/security)** section.

### [Known Issues](#known-issues-3)

* Scan results don't appear for some official images.

## [2019-09-16](#2019-09-16)

### [Enhancements](#enhancements-3)

* The [billing page](https://docs.docker.com/subscription/change/) for personal accounts has been updated. You can access the page at its new URL: <https://hub.docker.com/billing/plan>.

### [Known Issues](#known-issues-4)

* Scan results don't appear for some official images.

## [2019-09-05](#2019-09-05)

### [Enhancements](#enhancements-4)

* The `Tags` tab on an image page now provides additional information for each tag:

  * A list of digests associated with the tag
  * The architecture it was built on
  * The OS
  * The user who most recently updated an image for a specific tag

* The security scan summary for Docker Official Images has been updated.

### [Known Issues](#known-issues-5)

* Scan results don't appear for some official images.

----
url: https://docs.docker.com/ai/docker-agent/reference/examples/
----

# Examples

***

Table of contents

***

Get inspiration from the following agent examples. See more examples in the [Docker Agent GitHub repository](https://github.com/docker/docker-agent/tree/main/examples).

## [Development team](#development-team)

```yaml
models:
  model:
    provider: anthropic
    model: claude-sonnet-4-0
    max_tokens: 64000

agents:
  root:
    model: model
    description: Product Manager - Leads the development team and coordinates iterations
    instruction: |
      You are the Product Manager leading a development team consisting of a designer, frontend engineer, full stack engineer, and QA tester.

      Your responsibilities:
      - Break down user requirements into small, manageable iterations
      - Each iteration should deliver one complete feature end-to-end
      - Ensure each iteration is small enough to be completed quickly but substantial enough to provide value
      - Coordinate between team members to ensure smooth workflow
      - Define clear acceptance criteria for each feature
      - Prioritize features based on user value and technical dependencies

      IMPORTANT ITERATION PRINCIPLES:
      - Start with the most basic, core functionality first
      - Each iteration must result in working, testable code
      - Features should be incrementally built upon previous iterations
      - Don't try to build everything at once - focus on one feature at a time
      - Ensure proper handoffs between designer → frontend → fullstack → QA

      Workflow for each iteration:
      1. Define the feature and acceptance criteria
      2. Have designer create UI mockups/wireframes
      3. Have frontend engineer implement the UI
      4. Have fullstack engineer build backend and integrate
      5. Have QA test the complete feature and report issues
      6. Address any issues before moving to next iteration

      Always start by understanding what the user wants to build, then break it down into logical, small iterations.

      Always make sure to ask the right agent to do the right task using the appropriate toolset. don't try to do everything yourself.

      Always read and write all decisions and important information to a .md file called dev-team.md in the .dev-team directory.
      Make sure to append to the file and edit what is not needed anymore. Consult this file to understand the current state of the project and the team.
      This file might include references to other files that should all be placed inside the .dev-team folder. Don't write anything but code outside of this directory.

    sub_agents: [designer, awesome_engineer]
    toolsets:
      - type: filesystem
      - type: think
      - type: todo
      - type: memory
        path: dev_memory.db
      - type: mcp
        ref: docker:context7

  designer:
    model: model
    description: UI/UX Designer - Creates user interface designs and wireframes
    instruction: |
      You are a UI/UX Designer working on a development team. Your role is to create user-friendly, intuitive designs for each feature iteration.

      Your responsibilities:
      - Create wireframes and mockups for each feature
      - Design responsive layouts that work on different screen sizes
      - Ensure consistent design patterns across the application
      - Consider user experience and accessibility
      - Provide detailed design specifications for the frontend engineer
      - Use modern design principles and best practices

      For each feature you design:
      1. Create a clear wireframe showing layout and components
      2. Specify colors, fonts, spacing, and styling details
      3. Define user interactions and hover states
      4. Consider mobile responsiveness
      5. Provide clear handoff documentation for the frontend engineer

      Keep designs simple and focused on the specific feature being built in the current iteration.
      Build upon previous designs to maintain consistency across the application.

      Always read and write all decisions and important information to a .md file called dev-team.md in the .dev-team directory.
      Make sure to append to the file and edit what is not needed anymore. Consult this file to understand the current state of the project and the team. 
      This file might include references to other files that should all be placed inside the .dev-team folder. Don't write anything but code outside of this directory.
    toolsets:
      - type: filesystem
      - type: think
      - type: memory
        path: dev_memory.db
      - type: mcp
        ref: docker:context7

  awesome_engineer:
    model: model
    description: Awesome Engineer - Implements user interfaces based on designs
    instruction: |
      You are an Awesome Engineer responsible for implementing user interfaces based on the designer's specifications.

      Your responsibilities:
      - Convert design mockups into responsive, interactive web interfaces
      - Write clean, maintainable HTML, CSS, and JavaScript
      - Ensure cross-browser compatibility and mobile responsiveness
      - Implement proper accessibility features
      - Create reusable components and maintain code consistency
      - Integrate with backend APIs provided by the fullstack engineer

      Technical guidelines:
      - Use modern frontend frameworks/libraries (React, Vue, or vanilla JS as appropriate)
      - Write semantic HTML with proper structure
      - Use CSS best practices (flexbox, grid, responsive design)
      - Implement proper error handling for API calls
      - Follow accessibility guidelines (WCAG)
      - Write clean, commented code that's easy to maintain

      For each iteration:
      1. Review the design specifications carefully
      2. Break down the UI into logical components
      3. Implement the interface with proper styling
      4. Test the UI functionality before handoff
      5. Document any deviations from the design and rationale

      Focus on creating a working, polished UI for the specific feature in the current iteration.

      You are also a Full Stack Engineer responsible for building backend systems, APIs, and integrating them with the frontend.

      Your responsibilities:
      - Design and implement backend APIs and services
      - Set up databases and data models
      - Handle authentication, authorization, and security
      - Integrate frontend with backend systems
      - Ensure proper error handling and logging
      - Write tests for backend functionality
      - Deploy and maintain the application infrastructure

      Technical guidelines:
      - Choose appropriate technology stack based on requirements
      - Design RESTful APIs with proper HTTP methods and status codes
      - Implement proper data validation and sanitization
      - Use appropriate database design patterns
      - Follow security best practices
      - Write comprehensive error handling
      - Include proper logging and monitoring
      - Write unit and integration tests

      For each iteration:
      1. Design the backend architecture for the feature
      2. Implement necessary APIs and database changes
      3. Test backend functionality thoroughly
      4. Integrate with the frontend implementation
      5. Ensure end-to-end functionality works correctly
      6. Document API endpoints and usage

      Focus on building robust, scalable backend systems that support the current iteration's feature.
      Ensure seamless integration with the frontend implementation.

      Always read and write all decisions and important information to a .md file called dev-team.md in the .dev-team directory.
      Make sure to append to the file and edit what is not needed anymore. Consult this file to understand the current state of the project and the team. 
      This file might include references to other files that should all be placed inside the .dev-team folder. Don't write anything but code outside of this directory.
    toolsets:
      - type: filesystem
      - type: shell
      - type: think
      - type: memory
        path: dev_memory.db
      - type: mcp
        ref: docker:context7
```

## [Go developer](#go-developer)

```yaml
models:
  claude:
    provider: anthropic
    model: claude-opus-4-6
  haiku:
    provider: anthropic
    model: claude-haiku-4-5

agents:
  root:
    model: claude
    description: Expert Golang Developer specialized in implementing features and improving code quality.
    skills: true
    instruction: |
      **Goal:**
      Help with Go code-related tasks by examining, modifying, and validating code changes.

      TASK
          **Workflow:**
          1. **Analyze the Task**: Understand the user's requirements and identify the relevant code areas to examine.

          2. **Code Examination**: 
          - Search for relevant code files and functions
          - Analyze code structure and dependencies
          - Identify potential areas for modification

          3. **Code Modification**:
          - Make necessary code changes
          - Ensure changes follow best practices
          - Maintain code style consistency

          4. **Validation Loop**:
          - Run linters and tests to check code quality
          - Verify changes meet requirements
          - If issues found, return to step 3
          - Continue until all requirements are met

          5. **Summary**:
          - Very concisely summarize the changes made (not in a file)
          - For trivial tasks, answer the question without extra information
      </TASK>

      **Details:**
       - Be thorough in code examination before making changes
       - Always validate changes before considering the task complete
       - Follow Go best practices
       - Maintain or improve code quality
       - Be proactive in identifying potential issues
       - Only ask for clarification if necessary, try your best to use all the tools to get the info you need

       **Tools:**
        - When needed and possible, call multiple tools concurrently. It's faster and cheaper.

    add_date: true
    add_environment_info: true
    add_prompt_files:
      - AGENTS.md
    sub_agents:
      - librarian
    toolsets:
      - type: filesystem
      - type: shell
      - type: todo
      - type: mcp
        command: gopls
        version: "golang/tools@v0.21.0"
        args: ["mcp"]
    commands:
      fix-lint:
        description: "Fix the lint issues"
        instruction: |
          Fix the lint issues (if any).

          Here the result of the linting command:
          $ task lint
          ${shell({cmd: "task lint"})}

          $go_diagnostics
          ${go_diagnostics()}

          $go_vulncheck
          ${go_vulncheck()}
      remove-comments-tests: "Remove useless comments in test files (*_test.go)"
      commit:
        description: "Commit local changes"
        instruction: |
          Based on the below changes: create a single commit with an appropriate message.

          - Current git status: !shell(cmd="git status")
          - Current git diff (staged and unstaged changes): !shell(cmd="git diff HEAD")
          - Current branch: !shell(cmd="git branch --show-current")
      simplify: "Look at the local changes and try to simplify the code and architecture but don't remove any feature. I just want the code to be easier to read and maintain."
      init: |
        Create an AGENTS.md file for this project by inspecting the codebase. The AGENTS.md should help AI coding agents understand how to work with this project effectively.

        Analyze the project structure and include:
        1. **Development Commands**: Build, test, lint, and run commands (check Makefile, Taskfile.yml, package.json, Cargo.toml, etc.)
        2. **Architecture Overview**: Key packages/modules, their responsibilities, and how they interact
        3. **Code Style and Conventions**: Patterns used, error handling approaches, naming conventions
        4. **Testing Guidelines**: How to run tests, test patterns used, any special testing setup
        5. **Configuration**: Important config files and environment variables
        6. **Common Development Patterns**: Frequently used patterns specific to this codebase
        7. **Key Files Reference**: Quick reference table of important files and their purposes

        Focus on information that would help an AI agent navigate and modify the codebase correctly. Be concise but comprehensive.
      security-review: |
        Perform a security review of the local changes in this Git repository.

        **Workflow:**
        1. **Identify Changes**: Run `git diff` to see uncommitted changes, and `git diff HEAD~1` or `git log --oneline -5` to understand recent commits if needed.

        2. **Security Analysis**: Review the changes for common security issues:
           - **Input Validation**: Check for missing or inadequate input validation
           - **SQL Injection**: Look for raw SQL queries or improper use of query builders
           - **Command Injection**: Identify unsafe use of exec, shell commands, or system calls
           - **Path Traversal**: Check for unsafe file path handling
           - **Sensitive Data Exposure**: Look for hardcoded secrets, API keys, or credentials
           - **Authentication/Authorization**: Review any auth-related changes
           - **Error Handling**: Check for information leakage in error messages
           - **Dependency Security**: Note any new dependencies that should be vetted
           - **Race Conditions**: Identify potential concurrency issues in Go code
           - **Unsafe Pointer Usage**: Check for unsafe package usage

        3. **Go-Specific Checks**:
           - Run `go_vulncheck` to check for known vulnerabilities
           - Review use of `unsafe` package
           - Check for proper context cancellation and timeout handling
           - Verify proper error wrapping and handling

        4. **Report**: Provide a structured security review with:
           - **Summary**: Overall security posture of the changes
           - **Findings**: List of identified issues with severity (Critical/High/Medium/Low/Info)
           - **Recommendations**: Specific suggestions to improve security
           - **Tips**: General security best practices relevant to the changes

  planner:
    model: claude
    instruction: |
      You are a planning agent responsible for gathering user requirements and creating a development plan.
      Always ask clarifying questions to ensure you fully understand the user's needs before creating the plan.
      Once you have a clear understanding, analyze the existing code and create a detailed development plan in a markdown file. Do not write any code yourself.
      Once the plan is created, you will delegate tasks to the root agent. Make sure to provide the file name of the plan when delegating. Write the plan in the current directory.
      Use the `user_prompt` tool to ask questions to the user. Prefer Multiple Choice Questions.
    toolsets:
      - type: filesystem
      - type: user_prompt
    sub_agents:
      - root

  reviewer:
    model: google/gemini-3-pro-preview
    instruction: |
      Give me feedback about the local changes. Don't be too picky, think about code quality, security, duplication, idiomatic Go,
      performance, maintainability, and best practices.
      Provide suggestions for improvements and point out any potential issues.
      Don't be too verbose, keep your review concise and to the point.
    add_prompt_files:
      - AGENTS.md
    sub_agents:
      - librarian
    toolsets:
      - type: filesystem
      - type: shell
      - type: mcp
        command: gopls
        version: "golang/tools@v0.21.0"
        args: ["mcp"]

  librarian:
    model: haiku
    description: Documentation librarian. Can search the Web and look for relevant documentation to help the golang developer agent.
    instruction: |
      You are the librarian, your job is to look for relevant documentation to help the golang developer agent.
      When given a query, search the internet for relevant documentation, articles, or resources that can assist in completing the task.
      Use context7 for searching documentation and brave for general web searches.
      A good source of information available to agents is https://deepwiki.com/.
    toolsets:
      - type: mcp
        ref: docker:context7
      - type: mcp
        ref: docker:brave
      - type: fetch

permissions:
  allow:
    - go_diagnostics
    - go_file_context
    - go_package_api
    - go_symbol_references
    - go_vulncheck
    - go_workspace
    - shell:cmd=gh --version
    - shell:cmd=gh pr view *
    - shell:cmd=gh pr diff *
    - shell:cmd=git remote -v
    - shell:cmd=ls *
    - shell:cmd=cat *
    - shell:cmd=head *
    - shell:cmd=tail *
    - shell:cmd=wc *
    - shell:cmd=find *
    - shell:cmd=grep *
    - shell:cmd=pwd
    - shell:cmd=echo *
    - shell:cmd=which *
    - shell:cmd=type *
    - shell:cmd=file *
    - shell:cmd=stat *
    - shell:cmd=git status*
    - shell:cmd=git log*
    - shell:cmd=git diff*
    - shell:cmd=git show*
    - shell:cmd=git branch*
    - shell:cmd=git remote -v*
    - shell:cmd=git commit *
    - shell:cmd=go test*
    - shell:cmd=go build*
```

## [Technical blog writer](#technical-blog-writer)

```yaml
agents:
  root:
    model: anthropic
    description: Writes technical blog posts
    instruction: |
      You are the leader of a team of AI agents for a technical blog writing workflow.

      Here are the members in your team:
      <team_members>
      - web_search_agent: Searches the web
      - writer: Writes a 750-word technical blog post based on the chosen prompt
      </team_members>

      WORKFLOW
        1. Call the `web_search_agent` agent to search for the web to get important information about the task that is asked

        3. Call the `writer` agent to write a 750-word technical blog post based on the research done by the web_search_agent
      </WORKFLOW>

      - Use the transfer_to_agent tool to call the right agent at the right time to complete the workflow.
      - DO NOT transfer to multiple members at once
      - ONLY CALL ONE AGENT AT A TIME
      - When using the `transfer_to_agent` tool, make exactly one call and wait for the result before making another. Do not batch or parallelize tool calls.
    sub_agents:
      - web_search_agent
      - writer
    toolsets:
      - type: think

  web_search_agent:
    model: anthropic
    add_date: true
    description: Search the web for the information
    instruction: |
      Search the web for the information

      Always include sources
    toolsets:
      - type: mcp
        ref: docker:duckduckgo

  writer:
    model: anthropic
    description: Writes a 750-word technical blog post based on the chosen prompt.
    instruction: |
      You are an agent that receives a single technical writing prompt and generates a detailed, informative, and well-structured technical blog post.

      - Ensure the content is technically accurate and includes relevant code examples, diagrams, or technical explanations where appropriate.
      - Structure the blog post with clear sections, including an introduction, main content, and conclusion.
      - Use technical terminology appropriately and explain complex concepts clearly.
      - Include practical examples and real-world applications where relevant.
      - Make sure the content is engaging for a technical audience while maintaining professional standards.

      Constraints:
      - DO NOT use lists

models:
  anthropic:
    provider: anthropic
    model: claude-sonnet-4-6
```

----
url: https://docs.docker.com/reference/compose-file/secrets/
----

# Secrets

***

Table of contents

***

Secrets are a flavor of [Configs](https://docs.docker.com/reference/compose-file/configs/) focusing on sensitive data, with specific constraint for this usage.

Services can only access secrets when explicitly granted by a [`secrets` attribute](https://docs.docker.com/reference/compose-file/services/#secrets) within the `services` top-level element.

The top-level `secrets` declaration defines or references sensitive data that is granted to the services in your Compose application. The source of the secret is either `file` or `environment`.

* `file`: The secret is created with the contents of the file at the specified path.
* `environment`: The secret is created with the value of an environment variable on the host. This is only supported by Docker Compose. It is not supported when deploying with [`docker stack deploy`](https://docs.docker.com/engine/swarm/stack-deploy/).

## [Example 1](#example-1)

`server-certificate` secret is created as `<project_name>_server-certificate` when the application is deployed, by registering content of the `server.cert` as a platform secret.

```yml
secrets:
  server-certificate:
    file: ./server.cert
```

## [Example 2](#example-2)

`token` secret is created as `<project_name>_token` when the application is deployed, by registering the content of the `OAUTH_TOKEN` environment variable as a platform secret.

```yml
secrets:
  token:
    environment: "OAUTH_TOKEN"
```

> Note
>
> `environment` secrets are not supported when deploying with `docker stack deploy`. Use `file` or `external` as the secret source instead.

## [Additional resources](#additional-resources)

For more information, see [How to use secrets in Compose](https://docs.docker.com/compose/how-tos/use-secrets/).

----
url: https://docs.docker.com/reference/cli/docker/swarm/update/
----

# docker swarm update

***

| Description | Update the swarm                |
| ----------- | ------------------------------- |
| Usage       | `docker swarm update [OPTIONS]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Updates a swarm with new parameter values.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                   | Default     | Description                                                 |
| ------------------------ | ----------- | ----------------------------------------------------------- |
| `--autolock`             |             | Change manager autolocking setting (true\|false)            |
| `--cert-expiry`          | `2160h0m0s` | Validity period for node certificates (ns\|us\|ms\|s\|m\|h) |
| `--dispatcher-heartbeat` | `5s`        | Dispatcher heartbeat period (ns\|us\|ms\|s\|m\|h)           |
| `--external-ca`          |             | Specifications of one or more certificate signing endpoints |
| `--max-snapshots`        |             | API 1.25+ Number of additional Raft snapshots to retain     |
| `--snapshot-interval`    | `10000`     | API 1.25+ Number of log entries between Raft snapshots      |
| `--task-history-limit`   | `5`         | Task history retention limit                                |

## [Examples](#examples)

```console
$ docker swarm update --cert-expiry 720h
```

----
url: https://docs.docker.com/ai/sandboxes/agents/droid/
----

# Droid

***

Table of contents

***

This guide covers authentication, configuration, and usage of Droid, an AI coding agent by Factory, in a sandboxed environment.

Official documentation: [Droid](https://docs.factory.ai/)

## [Quick start](#quick-start)

Create a sandbox and run Droid for a project directory:

```console
$ sbx run droid ~/my-project
```

The workspace parameter is optional and defaults to the current directory:

```console
$ cd ~/my-project
$ sbx run droid
```

## [Authentication](#authentication)

Droid requires a [Factory account](https://factory.ai). Both authentication methods authenticate you to Factory's service directly — unlike other agents where you supply a model provider key, Factory manages model access through your Factory account.

**API key**: Store your Factory API key using [stored secrets](https://docs.docker.com/ai/sandboxes/security/credentials/#stored-secrets):

```console
$ sbx secret set -g droid
```

Alternatively, export the `FACTORY_API_KEY` environment variable in your shell before running the sandbox. See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for details on both methods.

**OAuth**: If no API key is set, Droid prompts you to authenticate interactively on first run. The proxy handles the OAuth flow, so credentials aren't stored inside the sandbox.

## [Configuration](#configuration)

Sandboxes don't pick up user-level configuration from your host. Only project-level configuration in the working directory is available inside the sandbox. See [Why doesn't the sandbox use my user-level agent configuration?](https://docs.docker.com/ai/sandboxes/faq/#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for workarounds.

### [Default startup command](#default-startup-command)

The sandbox runs `droid` with no implicit flags. Args after `--` are passed straight through:

```console
$ sbx run droid -- exec "fix the build"
```

## [Base image](#base-image)

Template: `docker/sandbox-templates:droid-docker`

Preconfigured to run without approval prompts. Authentication state is persisted across sandbox restarts.

----
url: https://docs.docker.com/subscription/manage-seats/
----

# Manage subscription seats

***

Table of contents

***

You can add or remove seats from your Docker Team or Business subscription at any time to accommodate team changes. When you add seats mid-billing cycle, you're charged a prorated amount for the additional seats.

> Important
>
> If you have a sales-assisted Docker Business subscription, contact your account manager to add or remove seats from your subscription.

## [Add seats to your subscription](#add-seats-to-your-subscription)

To add seats:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.

2. Select **Billing**.

3. Select the action menu from the **Active Plans** tile, then choose **Add seats**.

4. Follow the on-screen instructions to complete adding seats.

   * You can't use pay by invoice for purchasing additional seats.
   * You must use a card or US bank account.

You can add more members to your organization. For more information, see [Manage organization members](https://docs.docker.com/admin/organization/manage/members/).

## [Volume pricing](#volume-pricing)

Docker offers volume pricing for Docker Business subscriptions starting at 25 seats. Contact the [Docker Sales Team](https://www.docker.com/pricing/contact-sales/) for more information.

## [Remove seats from your subscription](#remove-seats-from-your-subscription)

You can remove seats from your Team or Business subscription at any time. To remove seats:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Billing**.
3. Select the action menu, then choose **Remove seats**.
4. Follow the on-screen instructions to complete removing seats.

Changes apply to your next billing cycle, and unused portions aren't refundable.

For example, if you're billed on the 8th of every month for 10 seats and remove 2 seats on the 15th, the 2 seats remain available until your next billing cycle. Your payment for 8 seats begins on the next billing cycle.

> Tip
>
> You can cancel the removal of seats before your next billing cycle. To do so, select **Cancel change**.

----
url: https://docs.docker.com/build/bake/remote-definition/
----

# Remote Bake file definition

***

Table of contents

***

You can build Bake files directly from a remote Git repository or HTTPS URL:

```console
$ docker buildx bake "https://github.com/docker/cli.git#v20.10.11" --print
#1 [internal] load git source https://github.com/docker/cli.git#v20.10.11
#1 0.745 e8f1871b077b64bcb4a13334b7146492773769f7       refs/tags/v20.10.11
#1 2.022 From https://github.com/docker/cli
#1 2.022  * [new tag]         v20.10.11  -> v20.10.11
#1 DONE 2.9s
```

This fetches the Bake definition from the specified remote location and executes the groups or targets defined in that file. If the remote Bake definition doesn't specify a build context, the context is automatically set to the Git remote. For example, [this case](https://github.com/docker/cli/blob/2776a6d694f988c0c1df61cad4bfac0f54e481c8/docker-bake.hcl#L17-L26) uses `https://github.com/docker/cli.git`:

```json
{
  "group": {
    "default": {
      "targets": ["binary"]
    }
  },
  "target": {
    "binary": {
      "context": "https://github.com/docker/cli.git#v20.10.11",
      "dockerfile": "Dockerfile",
      "args": {
        "BASE_VARIANT": "alpine",
        "GO_STRIP": "",
        "VERSION": ""
      },
      "target": "binary",
      "platforms": ["local"],
      "output": ["build"]
    }
  }
}
```

## [Use the local context with a remote definition](#use-the-local-context-with-a-remote-definition)

When building with a remote Bake definition, you may want to consume local files relative to the directory where the Bake command is executed. You can define contexts as relative to the command context using a `cwd://` prefix.

https\://github.com/dvdksn/buildx/blob/bake-remote-example/docker-bake.hcl

```hcl
target "default" {
  context = "cwd://"
  dockerfile-inline = <<EOT
FROM alpine
WORKDIR /src
COPY . .
RUN ls -l && stop
EOT
}
```

```console
$ touch foo bar
$ docker buildx bake "https://github.com/dvdksn/buildx.git#bake-remote-example"
```

```text
...
 > [4/4] RUN ls -l && stop:
#8 0.101 total 0
#8 0.102 -rw-r--r--    1 root     root             0 Jul 27 18:47 bar
#8 0.102 -rw-r--r--    1 root     root             0 Jul 27 18:47 foo
#8 0.102 /bin/sh: stop: not found
```

You can append a path to the `cwd://` prefix if you want to use a specific local directory as a context. Note that if you do specify a path, it must be within the working directory where the command gets executed. If you use an absolute path, or a relative path leading outside of the working directory, Bake will throw an error.

### [Local named contexts](#local-named-contexts)

You can also use the `cwd://` prefix to define local directories in the Bake execution context as named contexts.

The following example defines the `docs` context as `./src/docs/content`, relative to the current working directory where Bake is run as a named context.

docker-bake.hcl

```hcl
target "default" {
  contexts = {
    docs = "cwd://src/docs/content"
  }
  dockerfile = "Dockerfile"
}
```

By contrast, if you omit the `cwd://` prefix, the path would be resolved relative to the build context.

## [Specify the Bake definition to use](#specify-the-bake-definition-to-use)

When loading a Bake file from a remote Git repository, if the repository contains more than one Bake file, you can specify which Bake definition to use with the `--file` or `-f` flag:

```console
docker buildx bake -f bake.hcl "https://github.com/crazy-max/buildx.git#remote-with-local"
```

```text
...
#4 [2/2] RUN echo "hello world"
#4 0.270 hello world
#4 DONE 0.3s
```

## [Combine local and remote Bake definitions](#combine-local-and-remote-bake-definitions)

You can also combine remote definitions with local ones using the `cwd://` prefix with `-f`.

Given the following local Bake definition in the current working directory:

```hcl
# local.hcl
target "default" {
  args = {
    HELLO = "foo"
  }
}
```

The following example uses `-f` to specify two Bake definitions:

* `-f bake.hcl`: this definition is loaded relative to the Git URL.
* `-f cwd://local.hcl`: this definition is loaded relative to the current working directory where the Bake command is executed.

```console
docker buildx bake -f bake.hcl -f cwd://local.hcl "https://github.com/crazy-max/buildx.git#remote-with-local" --print
```

```json
{
  "target": {
    "default": {
      "context": "https://github.com/crazy-max/buildx.git#remote-with-local",
      "dockerfile": "Dockerfile",
      "args": {
        "HELLO": "foo"
      },
      "target": "build",
      "output": [
        {
          "type": "cacheonly"
        }
      ]
    }
  }
}
```

One case where combining local and remote Bake definitions becomes necessary is when you're building with a remote Bake definition in GitHub Actions and want to use the [metadata-action](https://github.com/docker/metadata-action) to generate tags, annotations, or labels. The metadata action generates a Bake file available in the runner's local Bake execution context. To use both the remote definition and the local "metadata-only" Bake file, specify both files and use the `cwd://` prefix for the metadata Bake file:

```yml
      - name: Build
        uses: docker/bake-action@v7
        with:
          files: |
            ./docker-bake.hcl
            cwd://${{ steps.meta.outputs.bake-file }}
          targets: build
```

## [Remote definition in a private repository](#remote-definition-in-a-private-repository)

If you want to use a remote definition that lives in a private repository, you may need to specify credentials for Bake to use when fetching the definition.

If you can authenticate to the private repository using the default `SSH_AUTH_SOCK`, then you don't need to specify any additional authentication parameters for Bake. Bake automatically uses your default agent socket.

For authentication using an HTTP token, or custom SSH agents, use the following environment variables to configure Bake's authentication strategy:

* [`BUILDX_BAKE_GIT_AUTH_TOKEN`](https://docs.docker.com/build/building/variables/#buildx_bake_git_auth_token)
* [`BUILDX_BAKE_GIT_AUTH_HEADER`](https://docs.docker.com/build/building/variables/#buildx_bake_git_auth_header)
* [`BUILDX_BAKE_GIT_SSH`](https://docs.docker.com/build/building/variables/#buildx_bake_git_ssh)

----
url: https://docs.docker.com/
----

Start a new chat

### What can I help you with?

I'm Gordon, your AI assistant for Docker and documentation questions.

Try asking

Answers are generated based on the documentation.

# How can we help?

### [Get started](/get-started/)

[Learn Docker basics.](/get-started/)

### [Guides](/guides/)

[Optimize your development workflows with Docker.](/guides/)

### [Manuals](/manuals/)

[Install, set up, configure, and use Docker products.](/manuals/)

### [Reference](/reference/)

[Browse the CLI and API documentation.](/reference/)

## Featured topics

[Docker Hardened Images ](/dhi/)[Get started with Docker Sandboxes ](/ai/sandboxes/get-started/)[Docker Desktop overview ](/desktop/)[Install Docker Engine ](/engine/install/)[Dockerfile reference ](/reference/dockerfile/)[Docker Build overview](/build/)

----
url: https://docs.docker.com/build/ci/github-actions/named-contexts/
----

# Named contexts with GitHub Actions

***

Table of contents

***

You can define [additional build contexts](/reference/cli/docker/buildx/build/#build-context), and access them in your Dockerfile with `FROM name` or `--from=name`. When Dockerfile defines a stage with the same name it's overwritten.

This can be useful with GitHub Actions to reuse results from other builds or pin an image to a specific tag in your workflow.

## [Pin image to a tag](#pin-image-to-a-tag)

Replace `alpine:latest` with a pinned one:

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN echo "Hello World"
```

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build
        uses: docker/build-push-action@v7
        with:
          build-contexts: |
            alpine=docker-image://alpine:3.23
          tags: myimage:latest
```

## [Use image in subsequent steps](#use-image-in-subsequent-steps)

By default, the [Docker Setup Buildx](https://github.com/marketplace/actions/docker-setup-buildx) action uses `docker-container` as a build driver, so built Docker images aren't loaded automatically.

With named contexts you can reuse the built image:

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN echo "Hello World"
```

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          driver: docker

      - name: Build base image
        uses: docker/build-push-action@v7
        with:
          context: "{{defaultContext}}:base"
          load: true
          tags: my-base-image:latest

      - name: Build
        uses: docker/build-push-action@v7
        with:
          build-contexts: |
            alpine=docker-image://my-base-image:latest
          tags: myimage:latest
```

## [Using with a container builder](#using-with-a-container-builder)

As shown in the previous section we are not using the default [`docker-container` driver](https://docs.docker.com/build/builders/drivers/docker-container/) for building with named contexts. That's because this driver can't load an image from the Docker store as it's isolated. To solve this problem you can use a [local registry](https://docs.docker.com/build/ci/github-actions/local-registry/) to push your base image in your workflow:

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN echo "Hello World"
```

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    services:
      registry:
        image: registry:3
        ports:
          - 5000:5000
    steps:
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          # network=host driver-opt needed to push to local registry
          driver-opts: network=host

      - name: Build base image
        uses: docker/build-push-action@v7
        with:
          context: "{{defaultContext}}:base"
          tags: localhost:5000/my-base-image:latest
          push: true

      - name: Build
        uses: docker/build-push-action@v7
        with:
          build-contexts: |
            alpine=docker-image://localhost:5000/my-base-image:latest
          tags: myimage:latest
```

----
url: https://docs.docker.com/reference/cli/sbx/policy/deny/network/
----

# sbx policy deny network

| Description | Deny network access to specified hosts                      |
| ----------- | ----------------------------------------------------------- |
| Usage       | `sbx policy deny network [-g \| SANDBOX] RESOURCES [flags]` |

## [Description](#description)

Block sandbox network access to the specified hosts.

RESOURCES is a comma-separated list of hostnames, domains, or IP addresses. Deny rules always take precedence over allow rules.

Use -g/--global to apply the rule globally to all sandboxes, or provide SANDBOX before RESOURCES to add the rule to policy "local" scoped to that sandbox.

## [Options](#options)

| Option         | Default | Description                              |
| -------------- | ------- | ---------------------------------------- |
| `-g, --global` |         | Apply the rule globally to all sandboxes |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Block access to a host globally
sbx policy deny network -g ads.example.com

# Block a host only for a specific sandbox
sbx policy deny network my-sandbox ads.example.com

# Block all outbound traffic globally
sbx policy deny network -g "**"
```

----
url: https://docs.docker.com/billing/tax-certificate/
----

# Submit a tax exemption certificate

***

Table of contents

***

If you're a customer in the United States and are exempt from sales tax, you can submit a valid tax exemption certificate to Docker Support.

If you're a global customer subject to VAT, make sure to include your [VAT number](https://docs.docker.com/billing/history/#include-your-vat-number-on-your-invoice) along with your country prefix when you update your billing profile.

## [Prerequisites](#prerequisites)

Before submitting your certificate:

* The customer name must match the name on the certificate.
* The certificate must list Docker Inc. as the Seller or Vendor, with all relevant fields completed.
* The certificate must be signed, dated, and not expired.
* You must include the Docker ID or namespace(s) for all accounts to apply the certificate to.

> Important
>
> You can use the same certificate for multiple namespaces, if applicable.

## [Contact information](#contact-information)

Use the following contact information on your certificate:

Docker, Inc. 3790 El Camino Real #1052 Palo Alto, CA 94306 (415) 941-0376

## [Register a tax certificate](#register-a-tax-certificate)

1. [Submit a Docker Support ticket](https://hub.docker.com/support/contact?topic=Billing\&subtopic=Tax%20information) to initiate the process to register a tax certificate.
2. Enter **Tax certificate** as the support ticket **Subject**.
3. In the **Details** field, enter **Submitting a tax certificate**.
4. Instructions will populate on how to submit a tax certificate.
5. Fill out all required fields on the support form.
6. In the file upload section, add the tax certificate by dragging and dropping the file, or selecting **Browse files**.
7. Select **Submit**.

Docker's support team will reach out to you if any additional information is required. You'll receive an e-mail confirmation from Docker once your tax exemption status is applied to your account.

----
url: https://docs.docker.com/reference/cli/docker/compose/unpause/
----

# docker compose unpause

***

| Description | Unpause services                      |
| ----------- | ------------------------------------- |
| Usage       | `docker compose unpause [SERVICE...]` |

## [Description](#description)

Unpauses paused containers of a service

----
url: https://docs.docker.com/engine/swarm/stack-deploy/
----

# Deploy a stack to a swarm

***

Table of contents

***

When running Docker Engine in swarm mode, you can use `docker stack deploy` to deploy a complete application stack to the swarm. The `deploy` command accepts a stack description in the form of a [Compose file](https://docs.docker.com/reference/compose-file/legacy-versions/).

> Note
>
> The `docker stack deploy` command uses the legacy [Compose file version 3](/reference/compose-file/legacy-versions/) format, used by Compose V1. The latest format, defined by the [Compose specification](/reference/compose-file/) isn't compatible with the `docker stack deploy` command.
>
> For more information about the evolution of Compose, see [History of Compose](/compose/history/).

To run through this tutorial, you need:

1. A Docker Engine running in [Swarm mode](https://docs.docker.com/engine/swarm/swarm-mode/). If you're not familiar with Swarm mode, you might want to read [Swarm mode key concepts](https://docs.docker.com/engine/swarm/key-concepts/) and [How services work](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/).

   > Note
   >
   > If you're trying things out on a local development environment, you can put your engine into Swarm mode with `docker swarm init`.
   >
   > If you've already got a multi-node swarm running, keep in mind that all `docker stack` and `docker service` commands must be run from a manager node.

2. A current version of [Docker Compose](https://docs.docker.com/compose/install/).

## [Set up a Docker registry](#set-up-a-docker-registry)

Because a swarm consists of multiple Docker Engines, a registry is required to distribute images to all of them. You can use the [Docker Hub](https://hub.docker.com) or maintain your own. Here's how to create a throwaway registry, which you can discard afterward.

1. Start the registry as a service on your swarm:

   ```console
   $ docker service create --name registry --publish published=5000,target=5000 registry:2
   ```

2. Check its status with `docker service ls`:

   ```console
   $ docker service ls

   ID            NAME      REPLICAS  IMAGE                                                                               COMMAND
   l7791tpuwkco  registry  1/1       registry:2@sha256:1152291c7f93a4ea2ddc95e46d142c31e743b6dd70e194af9e6ebe530f782c17
   ```

   Once it reads `1/1` under `REPLICAS`, it's running. If it reads `0/1`, it's probably still pulling the image.

3. Check that it's working with `curl`:

   ```console
   $ curl http://127.0.0.1:5000/v2/

   {}
   ```

## [Create the example application](#create-the-example-application)

The app used in this guide is based on the hit counter app in the [Get started with Docker Compose](https://docs.docker.com/compose/gettingstarted/) guide. It consists of a Python app which maintains a counter in a Redis instance and increments the counter whenever you visit it.

1. Create a directory for the project:

   ```console
   $ mkdir stackdemo
   $ cd stackdemo
   ```

2. Create a file called `app.py` in the project directory and paste this in:

   ```python
   from flask import Flask
   from redis import Redis

   app = Flask(__name__)
   redis = Redis(host='redis', port=6379)

   @app.route('/')
   def hello():
       count = redis.incr('hits')
       return 'Hello World! I have been seen {} times.\n'.format(count)

   if __name__ == "__main__":
       app.run(host="0.0.0.0", port=8000, debug=True)
   ```

3. Create a file called `requirements.txt` and paste these two lines in:

   ```text
   flask
   redis
   ```

4. Create a file called `Dockerfile` and paste this in:

   ```dockerfile
   # syntax=docker/dockerfile:1
   FROM python:3.4-alpine
   ADD . /code
   WORKDIR /code
   RUN pip install -r requirements.txt
   CMD ["python", "app.py"]
   ```

5. Create a file called `compose.yaml` and paste this in:

   ```yaml
     services:
       web:
         image: 127.0.0.1:5000/stackdemo
         build: .
         ports:
           - "8000:8000"
       redis:
         image: redis:alpine
   ```

   The image for the web app is built using the Dockerfile defined above. It's also tagged with `127.0.0.1:5000` - the address of the registry created earlier. This is important when distributing the app to the swarm.

## [Test the app with Compose](#test-the-app-with-compose)

1. Start the app with `docker compose up`. This builds the web app image, pulls the Redis image if you don't already have it, and creates two containers.

   You see a warning about the Engine being in swarm mode. This is because Compose doesn't take advantage of swarm mode, and deploys everything to a single node. You can safely ignore this.

   ```console
   $ docker compose up -d

   WARNING: The Docker Engine you're using is running in swarm mode.

   Compose does not use swarm mode to deploy services to multiple nodes in
   a swarm. All containers are scheduled on the current node.

   To deploy your application across the swarm, use `docker stack deploy`.

   Creating network "stackdemo_default" with the default driver
   Building web
   ...(build output)...
   Creating stackdemo_redis_1
   Creating stackdemo_web_1
   ```

2. Check that the app is running with `docker compose ps`:

   ```console
   $ docker compose ps

         Name                     Command               State           Ports
   -----------------------------------------------------------------------------------
   stackdemo_redis_1   docker-entrypoint.sh redis ...   Up      6379/tcp
   stackdemo_web_1     python app.py                    Up      0.0.0.0:8000->8000/tcp
   ```

   You can test the app with `curl`:

   ```console
   $ curl http://localhost:8000
   Hello World! I have been seen 1 times.

   $ curl http://localhost:8000
   Hello World! I have been seen 2 times.

   $ curl http://localhost:8000
   Hello World! I have been seen 3 times.
   ```

3. Bring the app down:

   ```console
   $ docker compose down --volumes

   Stopping stackdemo_web_1 ... done
   Stopping stackdemo_redis_1 ... done
   Removing stackdemo_web_1 ... done
   Removing stackdemo_redis_1 ... done
   Removing network stackdemo_default
   ```

## [Push the generated image to the registry](#push-the-generated-image-to-the-registry)

To distribute the web app's image across the swarm, it needs to be pushed to the registry you set up earlier. With Compose, this is very simple:

```console
$ docker compose push

Pushing web (127.0.0.1:5000/stackdemo:latest)...
The push refers to a repository [127.0.0.1:5000/stackdemo]
5b5a49501a76: Pushed
be44185ce609: Pushed
bd7330a79bcf: Pushed
c9fc143a069a: Pushed
011b303988d2: Pushed
latest: digest: sha256:a81840ebf5ac24b42c1c676cbda3b2cb144580ee347c07e1bc80e35e5ca76507 size: 1372
```

The stack is now ready to be deployed.

## [Deploy the stack to the swarm](#deploy-the-stack-to-the-swarm)

1. Create the stack with `docker stack deploy`:

   ```console
   $ docker stack deploy --compose-file compose.yaml stackdemo

   Ignoring unsupported options: build

   Creating network stackdemo_default
   Creating service stackdemo_web
   Creating service stackdemo_redis
   ```

   The last argument is a name for the stack. Each network, volume and service name is prefixed with the stack name.

2. Check that it's running with `docker stack services stackdemo`:

   ```console
   $ docker stack services stackdemo

   ID            NAME             MODE        REPLICAS  IMAGE
   orvjk2263y1p  stackdemo_redis  replicated  1/1       redis:3.2-alpine@sha256:f1ed3708f538b537eb9c2a7dd50dc90a706f7debd7e1196c9264edeea521a86d
   s1nf0xy8t1un  stackdemo_web    replicated  1/1       127.0.0.1:5000/stackdemo@sha256:adb070e0805d04ba2f92c724298370b7a4eb19860222120d43e0f6351ddbc26f
   ```

   Once it's running, you should see `1/1` under `REPLICAS` for both services. This might take some time if you have a multi-node swarm, as images need to be pulled.

   As before, you can test the app with `curl`:

   ```console
   $ curl http://localhost:8000
   Hello World! I have been seen 1 times.

   $ curl http://localhost:8000
   Hello World! I have been seen 2 times.

   $ curl http://localhost:8000
   Hello World! I have been seen 3 times.
   ```

   With Docker's built-in routing mesh, you can access any node in the swarm on port `8000` and get routed to the app:

   ```console
   $ curl http://address-of-other-node:8000
   Hello World! I have been seen 4 times.
   ```

3. Bring the stack down with `docker stack rm`:

   ```console
   $ docker stack rm stackdemo

   Removing service stackdemo_web
   Removing service stackdemo_redis
   Removing network stackdemo_default
   ```

4. Bring the registry down with `docker service rm`:

   ```console
   $ docker service rm registry
   ```

5. If you're just testing things out on a local machine and want to bring your Docker Engine out of Swarm mode, use `docker swarm leave`:

   ```console
   $ docker swarm leave --force

   Node left the swarm.
   ```

----
url: https://docs.docker.com/reference/cli/docker/offload/
----

# docker offload

***

| Description | Control Docker Offload from the CLI |
| ----------- | ----------------------------------- |
| Usage       | `docker offload`                    |

## [Subcommands](#subcommands)

| Command                                                                                     | Description                                      |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [`docker offload diagnose`](https://docs.docker.com/reference/cli/docker/offload/diagnose/) | Print diagnostic information for Docker Offload  |
| [`docker offload start`](https://docs.docker.com/reference/cli/docker/offload/start/)       | Start a Docker Offload session                   |
| [`docker offload status`](https://docs.docker.com/reference/cli/docker/offload/status/)     | Show the status of the Docker Offload connection |
| [`docker offload stop`](https://docs.docker.com/reference/cli/docker/offload/stop/)         | Stop a Docker Offload session                    |
| [`docker offload version`](https://docs.docker.com/reference/cli/docker/offload/version/)   | Prints the version                               |

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/settings-reference/
----

# Settings reference

***

Table of contents

***

This reference documents Docker Desktop settings that administrators can configure using [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/). Use this page to understand which settings are available, their accepted values, platform compatibility, and which configuration methods apply.

> Note
>
> This page only covers configurable settings for administrators who are deploying Docker Desktop to their organization. For the full list of Docker Desktop user-facing settings, see [Change settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/).

## [General](#general)

### [Send usage statistics](#send-usage-statistics)

Controls whether Docker Desktop collects and sends local usage statistics and crash reports to Docker. Does not affect server-side telemetry collected via Docker Hub or other backend services such as sign in timestamps, pulls, or builds.

| Property        | Value                     |
| --------------- | ------------------------- |
| Default         | `true`                    |
| Accepted values | `true`, `false`           |
| Format          | Boolean                   |
| JSON key        | `analyticsEnabled`        |
| Admin Console   | **Send usage statistics** |

> Note
>
> Organizations using the Insights Dashboard may need this setting enabled to ensure that developer activity is fully visible. If users opt out and the setting is not locked, their activity may be excluded from analytics views.

### [Automatically check for updates](#automatically-check-for-updates)

Controls whether Docker Desktop checks for and notifies users about available updates. When set to `true`, update checks and notifications are disabled.

| Property        | Value              |
| --------------- | ------------------ |
| Default         | `false`            |
| Accepted values | `true`, `false`    |
| Format          | Boolean            |
| JSON key        | `disableUpdate`    |
| Admin Console   | **Disable update** |

> Note
>
> In hardened environments, enable this setting and lock it. This guarantees that only internally vetted versions are installed.

### [Automatically update components](#automatically-update-components)

Allows Docker Desktop to automatically update components that do not require a restart, such as Docker Compose, Docker Scout, and the Docker CLI.

| Property        | Value                               |
| --------------- | ----------------------------------- |
| Default         | `true`                              |
| Accepted values | `true`, `false`                     |
| Format          | Boolean                             |
| JSON key        | `silentModulesUpdate`               |
| Admin Console   | **Automatically update components** |

### [Enable Gordon](#enable-gordon)

| Property                        | Value                                         |
| ------------------------------- | --------------------------------------------- |
| Default                         | `false`                                       |
| Accepted values (individuals)   | `true`, `false`                               |
| Accepted values (Business tier) | `"Disabled"`, `"Enabled"`, `"Always Enabled"` |
| JSON key                        | `enableDockerAI`                              |
| Admin Console                   | **Enable Gordon**                             |

> Important
>
> Docker Business customers must set this to `"Enabled"` or `"Always Enabled"` in the Admin Console. Setting to `"User Defined"` alone will not activate Gordon.

### [Block `docker load`](#block-docker-load)

Prevents users from loading local Docker images using the `docker load` command, enforcing image provenance by requiring all images to come from registries.

| Property        | Value                 |
| --------------- | --------------------- |
| Default         | `false`               |
| Accepted values | `true`, `false`       |
| Format          | Boolean               |
| JSON key        | `blockDockerLoad`     |
| Admin Console   | **Block Docker Load** |

> Note
>
> In hardened environments, enable and lock this setting. This forces all images to come from your secure, scanned registry.

### [Hide onboarding survey](#hide-onboarding-survey)

Prevents the onboarding survey from being shown to new users.

| Property        | Value                      |
| --------------- | -------------------------- |
| Default         | `false`                    |
| Accepted values | `true`, `false`            |
| Format          | Boolean                    |
| JSON key        | `displayedOnboarding`      |
| Admin Console   | **Hide onboarding survey** |

### [Enable Docker terminal](#enable-docker-terminal)

Allows or restricts access to the built-in terminal for host system interaction. When set to `false`, users cannot use the Docker terminal to interact with the host machine or execute commands directly from Docker Desktop.

| Property           | Value                    |
| ------------------ | ------------------------ |
| Default            | `false`                  |
| Accepted values    | `true`, `false`          |
| Format             | Boolean                  |
| Docker Desktop GUI | **General** tab          |
| JSON key           | `desktopTerminalEnabled` |
| Admin Console      | Not available            |

### [Expose Docker API on TCP 2375 Windows only](#expose-docker-api-on-tcp-2375-hahahugoshortcode1545s0hbhb)

Exposes the Docker API over an unauthenticated TCP socket on port 2375. Only recommended for isolated and protected environments. Supports legacy integrations that require TCP API access.

| Property        | Value                      |
| --------------- | -------------------------- |
| Default         | `false`                    |
| Accepted values | `true`, `false`            |
| Format          | Boolean                    |
| JSON key        | `exposeDockerAPIOnTCP2375` |
| Admin Console   | **Expose Docker API**      |

> Note
>
> In hardened environments, disable and lock this setting. This ensures the Docker API is only reachable via the secure internal socket.

## [Extensions](#extensions)

### [Enable Docker extensions](#enable-docker-extensions)

Controls whether users can install and run Docker Extensions.

| Property        | Value                |
| --------------- | -------------------- |
| Default         | `true`               |
| Accepted values | `true`, `false`      |
| Format          | Boolean              |
| JSON key        | `extensionsEnabled`  |
| Admin Console   | **Allow Extensions** |

> Note
>
> In hardened environments, disable and lock this setting. This prevents third-party or unverified plugins from being installed.

### [Allow only extensions distributed through the Docker Marketplace](#allow-only-extensions-distributed-through-the-docker-marketplace)

Prevents installation of third-party or locally developed extensions.

| Property        | Value                           |
| --------------- | ------------------------------- |
| Default         | `false`                         |
| Accepted values | `true`, `false`                 |
| Format          | Boolean                         |
| JSON key        | `onlyMarketplaceExtensions`     |
| Admin Console   | **Only marketplace extensions** |

### [Enable a private marketplace](#enable-a-private-marketplace)

Ensures Docker Desktop connects to content defined and controlled by the administrator instead of the public Docker Marketplace.

| Property        | Value                              |
| --------------- | ---------------------------------- |
| Default         | `false`                            |
| Accepted values | `true`, `false`                    |
| Format          | Boolean                            |
| JSON key        | `extensionsPrivateMarketplace`     |
| Admin Console   | **Extensions private marketplace** |

## [AI](#ai)

### [Enable Docker Model Runner](#enable-docker-model-runner)

Enables Docker Model Runner functionality for running AI models in containers.

| Property        | Value                          |
| --------------- | ------------------------------ |
| Default         | `true`                         |
| Accepted values | `true`, `false`                |
| Format          | Boolean                        |
| JSON key        | `enableInference`              |
| Admin Console   | **Enable Docker Model Runner** |

#### [Enable host-side TCP support](#enable-host-side-tcp-support)

Enables TCP connectivity for Docker Model Runner services, allowing external applications to connect to Model Runner via TCP.

| Property        | Value                       |
| --------------- | --------------------------- |
| Default         | `false`                     |
| Accepted values | `true`, `false`             |
| Format          | Boolean                     |
| JSON key        | `enableInferenceTCP`        |
| Admin Console   | **Host-side TCP support**   |
| Requires        | Docker Model Runner enabled |

##### [Port](#port)

Specifies the port used for Model Runner TCP connections.

| Property        | Value                                                 |
| --------------- | ----------------------------------------------------- |
| Default         | `12434`                                               |
| Accepted values | Integer                                               |
| Format          | Integer                                               |
| JSON key        | `enableInferenceTCPPort`                              |
| Admin Console   | **Host-side TCP port**                                |
| Requires        | Docker Model Runner and host-side TCP support enabled |

##### [CORS Allowed Origins](#cors-allowed-origins)

Controls cross-origin resource sharing for Model Runner web integration.

| Property        | Value                                                                         |
| --------------- | ----------------------------------------------------------------------------- |
| Default         | Empty string                                                                  |
| Accepted values | Empty string (deny all), `*` (accept all), or comma-separated list of origins |
| Format          | String                                                                        |
| JSON key        | `enableInferenceCORS`                                                         |
| Admin Console   | **CORS Allowed Origins**                                                      |
| Requires        | Docker Model Runner and host-side TCP support enabled                         |

### [Enable GPU-backed inference Windows only](#enable-gpu-backed-inference-hahahugoshortcode1545s1hbhb)

Enables GPU-backed inference. Additional components will be downloaded to `~/.docker/bin/inference`.

| Property        | Value                           |
| --------------- | ------------------------------- |
| Default         | `false`                         |
| Accepted values | `true`, `false`                 |
| Format          | Boolean                         |
| JSON key        | `enableInferenceGPUVariant`     |
| Admin Console   | **Enable GPU-backed inference** |

## [File sharing and emulation](#file-sharing-and-emulation)

### [File sharing directories](#file-sharing-directories)

Defines which host directories containers can access for development workflows.

| Property        | Value                                      |
| --------------- | ------------------------------------------ |
| Default         | Varies by OS                               |
| Accepted values | List of file paths                         |
| Format          | Array of strings                           |
| JSON key        | `filesharingAllowedDirectories`            |
| Admin Console   | Yes — **Allowed file sharing directories** |

### [VirtioFS Mac only](#virtiofs-hahahugoshortcode1545s2hbhb)

Uses VirtioFS for fast, native file sharing between host and containers. If both VirtioFS and gRPC FUSE are set to `true`, VirtioFS takes precedence.

| Property        | Value                                 |
| --------------- | ------------------------------------- |
| Default         | `true`                                |
| Accepted values | `true`, `false`                       |
| Format          | Boolean                               |
| JSON key        | `useVirtualizationFrameworkVirtioFS`  |
| Admin Console   | **Use VirtioFS for file sharing** tab |

### [gRPC FUSE Mac only](#grpc-fuse-hahahugoshortcode1545s3hbhb)

Enables gRPC FUSE for macOS file sharing.

| Property        | Value                              |
| --------------- | ---------------------------------- |
| Default         | `true`                             |
| Accepted values | `true`, `false`                    |
| Format          | Boolean                            |
| JSON key        | `useGrpcfuse`                      |
| Admin Console   | **Use gRPC FUSE for file sharing** |

### [Rosetta Mac only](#rosetta-hahahugoshortcode1545s4hbhb)

Uses Rosetta for x86\_64/amd64 emulation on Apple Silicon.

| Property        | Value                                                        |
| --------------- | ------------------------------------------------------------ |
| Default         | `true`                                                       |
| Accepted values | `true`, `false`                                              |
| Format          | Boolean                                                      |
| JSON key        | `useVirtualizationFrameworkRosetta`                          |
| Admin Console   | **Use Rosetta for x86\_64/amd64 emulation on Apple Silicon** |

## [Scout](#scout)

### [Enable Scout image analysis](#enable-scout-image-analysis)

Turns on vulnerability scanning and software bill of materials (SBOM) analysis for container images.

| Property        | Value             |
| --------------- | ----------------- |
| Default         | `true`            |
| Accepted values | `true`, `false`   |
| Format          | Boolean           |
| JSON key        | `sbomIndexing`    |
| Admin Console   | **SBOM indexing** |

### [Enable background Scout SBOM indexing](#enable-background-scout-sbom-indexing)

Keeps image metadata current by indexing during idle time or after image operations.

| Property        | Value                   |
| --------------- | ----------------------- |
| Default         | `false`                 |
| Accepted values | `true`, `false`         |
| Format          | Boolean                 |
| JSON key        | `useBackgroundIndexing` |
| Admin Console   | **Background indexing** |

## [Proxy](#proxy)

### [Embedded PAC script](#embedded-pac-script)

Specifies an embedded Proxy Auto-Config (PAC) script. For example: `"embeddedPac": "function FindProxyForURL(url, host) { return \"DIRECT\"; }"`.

| Property        | Value                       |
| --------------- | --------------------------- |
| Default         | `""`                        |
| Accepted values | Embedded PAC script content |
| Format          | String                      |
| JSON key        | `embeddedPac`               |
| Admin Console   | Yes **Embedded PAC script** |

### [PAC file URL](#pac-file-url)

Specifies a PAC file URL for Docker Desktop to use when routing network traffic. For example: `"pac": "http://proxy/proxy.pac"`.

| Property        | Value        |
| --------------- | ------------ |
| Default         | `""`         |
| Accepted values | PAC file URL |
| Format          | String       |
| JSON key        | `pac`        |
| Admin Console   | **PAC file** |

### [Override Windows "dockerd" port Windows only](#override-windows-dockerd-port-hahahugoshortcode1545s5hbhb)

Exposes Docker Desktop's internal proxy locally on this port for the Windows Docker daemon to connect to. If it is set to 0, a random free port is chosen. If the value is greater than 0, use that exact value for the port.

| Property        | Value                               |
| --------------- | ----------------------------------- |
| Default         | `-1`                                |
| Accepted values | `-1` `0`                            |
| Format          | String                              |
| JSON key        | `windowsDockerdPort`                |
| Admin Console   | **Override Windows “dockerd” port** |

### [Enable Kerberos and NTLM authentication](#enable-kerberos-and-ntlm-authentication)

Enables enterprise proxy authentication support for Kerberos and NTLM protocols.

| Property        | Value                      |
| --------------- | -------------------------- |
| Default         | `false`                    |
| Accepted values | `true`, `false`            |
| Format          | Boolean                    |
| JSON key        | `proxy.enableKerberosNtlm` |
| Admin Console   | **Kerberos NTLM**          |

### [Proxy bypass](#proxy-bypass)

Defines network addresses that containers should bypass when using proxy settings.

| Property           | Value                                       |
| ------------------ | ------------------------------------------- |
| Default            | `""`                                        |
| Accepted values    | List of addresses                           |
| Format             | String                                      |
| Docker Desktop GUI | **Proxies** tab                             |
| JSON key           | `proxy` (with `manual` and `exclude` modes) |
| Admin Console      | Yes — **Proxy** section                     |

## [Containers proxy](#containers-proxy)

### [Air-gapped container proxy](#air-gapped-container-proxy)

Configures an HTTP/HTTPS proxy for containers in air-gapped environments, providing controlled network access in offline or restricted network environments.

| Property        | Value                        |
| --------------- | ---------------------------- |
| Default         | See example below            |
| Accepted values | JSON object                  |
| Format          | JSON object                  |
| JSON key        | `containersProxy`            |
| Admin Console   | **Containers proxy** section |

```json
"containersProxy": {
  "locked": true,
  "mode": "manual",
  "http": "",
  "https": "",
  "exclude": [],
  "pac": "",
  "transparentPorts": ""
}
```

For more information, see [Air-gapped containers](https://docs.docker.com/enterprise/security/hardened-desktop/air-gapped-containers/).

## [LinuxVM](#linuxvm)

### [Enable WSL engine Windows only](#enable-wsl-engine-hahahugoshortcode1545s6hbhb)

When set to `true`, Docker Desktop uses the WSL 2 based engine. Overrides any backend flag set at installation using `--backend=<backend name>`.

| Property        | Value                                        |
| --------------- | -------------------------------------------- |
| Default         | `true`                                       |
| Accepted values | `true`, `false`                              |
| Format          | Boolean                                      |
| JSON key        | `wslEngineEnabled`                           |
| Admin Console   | **Windows Subsystem for Linux (WSL) Engine** |

### [Docker daemon options](#docker-daemon-options)

Overrides the Docker daemon configuration used in containers, without modifying local configuration files.

| Property        | Value                                             |
| --------------- | ------------------------------------------------- |
| Default         | `{}`                                              |
| Accepted values | JSON object                                       |
| Format          | Stringified JSON                                  |
| JSON key        | `linuxVM.dockerDaemonOptions`                     |
| Admin Console   | **Docker Daemon options** in the LinuxVM dropdown |

### [VPNKit CIDR Mac only](#vpnkit-cidr-hahahugoshortcode1545s7hbhb)

Sets the network subnet used for Docker Desktop's internal VPNKit DHCP/DNS services. Prevents IP address conflicts in environments with overlapping network subnets.

| Property        | Value             |
| --------------- | ----------------- |
| Default         | `192.168.65.0/24` |
| Accepted values | CIDR notation     |
| Format          | String            |
| JSON key        | `vpnkitCIDR`      |
| Admin Console   | **VPNKit CIDR**   |

## [Windows containers](#windows-containers)

### [Docker daemon options](#docker-daemon-options-1)

Overrides the Docker daemon configuration used in Windows containers, without modifying local configuration files.

| Property        | Value                                                            |
| --------------- | ---------------------------------------------------------------- |
| Default         | `{}`                                                             |
| Accepted values | JSON object                                                      |
| Format          | Stringified JSON                                                 |
| JSON key        | `windowsContainers.dockerDaemonOptions`                          |
| Admin Console   | **Docker Daemon options** in the **Windows containers dropdown** |

## [Kubernetes](#kubernetes)

### [Enable Kubernetes](#enable-kubernetes)

Enables the local Kubernetes cluster integration with Docker Desktop.

| Property        | Value                 |
| --------------- | --------------------- |
| Default         | `false`               |
| Accepted values | `true`, `false`       |
| Format          | Boolean               |
| JSON key        | `kubernetes`          |
| Admin Console   | **Enable Kubernetes** |

### [Show system containers](#show-system-containers)

Controls visibility of Kubernetes system containers in the Docker Desktop Dashboard.

| Property        | Value                      |
| --------------- | -------------------------- |
| Default         | `false`                    |
| Accepted values | `true`, `false`            |
| Format          | Boolean                    |
| Admin Console   | **Show system containers** |

### [Kubernetes image repository](#kubernetes-image-repository)

Specifies a registry used for Kubernetes control plane images instead of Docker Hub. Overrides the `[registry[:port]/][namespace]` portion of image names. Images must be mirrored from Docker Hub with matching tags.

| Property        | Value                            |
| --------------- | -------------------------------- |
| Default         | `""`                             |
| Accepted values | Registry URL                     |
| Format          | String                           |
| JSON key        | `KubernetesImagesRepository`     |
| Admin Console   | **Kubernetes Images Repository** |

> Note
>
> Images must be mirrored from Docker Hub with matching tags. Required images depend on the cluster provisioning method.

> Important
>
> When using custom image repositories with Enhanced Container Isolation, add these images to the ECI allowlist: `[imagesRepository]/desktop-cloud-provider-kind:*` and `[imagesRepository]/desktop-containerd-registry-mirror:*`.

### [Cluster provisioning method](#cluster-provisioning-method)

Controls Kubernetes cluster topology and node configuration.

| Property        | Value               |
| --------------- | ------------------- |
| Default         | `kubeadm`           |
| Accepted values | `kubeadm`, `kind`   |
| Format          | String              |
| Admin Console   | **Kubernetes mode** |

### [Node version](#node-version)

Pins the Kubernetes version used for cluster nodes.

| Property        | Value                            |
| --------------- | -------------------------------- |
| Default         | `1.31.1`                         |
| Accepted values | Semantic version (e.g. `1.29.1`) |
| Format          | String                           |
| Admin Console   | **Node version** tab             |

### [Nodes count](#nodes-count)

Sets the number of nodes in multi-node Kubernetes clusters.

| Property        | Value           |
| --------------- | --------------- |
| Default         | `1`             |
| Accepted values | Integer         |
| Format          | Integer         |
| Admin Console   | **Nodes count** |

## [Features in development](#features-in-development)

### [Access beta features](#access-beta-features)

Controls whether users can access all Docker Desktop features that are in public beta.

| Property        | Value                    |
| --------------- | ------------------------ |
| Default         | `false`                  |
| Accepted values | `true`, `false`          |
| Format          | Boolean                  |
| JSON key        | `allowBetaFeatures`      |
| Admin Console   | **Access beta features** |

### [Enable Docker MCP Toolkit (Beta)](#enable-docker-mcp-toolkit-beta)

Enables [Docker MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/) in Docker Desktop for AI model development workflows.

| Property        | Value                    |
| --------------- | ------------------------ |
| Default         | `true`                   |
| Accepted values | `true`, `false`          |
| Format          | Boolean                  |
| JSON key        | `enableDockerMCPToolkit` |
| Admin Console   | Not available            |

## [Enhance container isolation](#enhance-container-isolation)

### [Enable Enhanced Container Isolation](#enable-enhanced-container-isolation)

Prevents containers from modifying Docker Desktop VM configuration or accessing sensitive host areas.

| Property        | Value                                   |
| --------------- | --------------------------------------- |
| Default         | `false`                                 |
| Accepted values | `true`, `false`                         |
| Format          | Boolean                                 |
| JSON key        | `enhancedContainerIsolation`            |
| Admin Console   | **Enable enhanced container isolation** |

### [Docker socket access control (ECI exceptions)](#docker-socket-access-control-eci-exceptions)

Defines specific images and commands allowed to use the Docker socket when Enhanced Container Isolation is active. Supports tools like Testcontainers, LocalStack, or CI systems that need Docker socket access while maintaining security.

| Property        | Value                            |
| --------------- | -------------------------------- |
| Accepted values | JSON object                      |
| Format          | JSON object                      |
| JSON key        | \`\`dockerSocketMount\`          |
| Admin Console   | **Image list**, **Command list** |

```json
"enhancedContainerIsolation": {
  "locked": true,
  "value": true,
  "dockerSocketMount": {
    "imageList": {
      "images": [
        "docker.io/localstack/localstack:*",
        "docker.io/testcontainers/ryuk:*"
      ]
    },
    "commandList": {
      "type": "deny",
      "commands": ["push"]
    }
  }
}
```

## [Network](#network)

### [Networking mode](#networking-mode)

Sets the default IP protocol used when Docker creates new networks.

| Property        | Value                       |
| --------------- | --------------------------- |
| Default         | `dual-stack`                |
| Accepted values | `ipv4only`, `ipv6only`      |
| Format          | String                      |
| JSON key        | `defaultNetworkingMode`     |
| Admin Console   | **Default network IP mode** |

For more information, see [Networking](https://docs.docker.com/desktop/features/networking/#networking-mode-and-dns-behaviour-for-mac-and-windows).

### [Inhibit DNS resolution for IPv4/IPv6](#inhibit-dns-resolution-for-ipv4ipv6)

Filters unsupported DNS record types to improve reliability in environments where only IPv4 or IPv6 is supported. Requires Docker Desktop 4.43 and later.

| Property        | Value                      |
| --------------- | -------------------------- |
| Default         | `auto`                     |
| Accepted values | `ipv4`, `ipv6`, `none`     |
| Format          | String                     |
| JSON key        | `dnsInhibition`            |
| Admin Console   | **DNS filtering behavior** |

For more information, see [Networking](https://docs.docker.com/desktop/features/networking/#networking-mode-and-dns-behaviour-for-mac-and-windows).

### [Port binding behavior](#port-binding-behavior)

Specify how port bindings are handled for new containers.

| Property        | Value                                                                           |
| --------------- | ------------------------------------------------------------------------------- |
| Default         | `default-port-binding`                                                          |
| Accepted values | `default-local-port-binding`, `local-only-port-binding`, `default-port-binding` |
| Format          | String                                                                          |
| JSON key        | `portBindingBehavior`                                                           |
| Admin Console   | **Port binding behavior**                                                       |

## [Other](#other)

### [Enable Docker Offload](#enable-docker-offload)

Controls Docker Offload availability. When enabled, users see the Docker Offload toggle in the Docker Desktop header.

| Property        | Value                     |
| --------------- | ------------------------- |
| Default         | `false`                   |
| Accepted values | `true`, `false`           |
| Format          | Boolean                   |
| JSON key        | `enableCloud`             |
| Admin Console   | **Enable Docker Offload** |

> Note
>
> This setting is only available when Docker Offload capability is enabled for the organization.

----
url: https://docs.docker.com/reference/cli/docker/
----

# docker

***

| Description | The base command for the Docker CLI. |
| ----------- | ------------------------------------ |

## [Description](#description)

Depending on your Docker system configuration, you may be required to preface each `docker` command with `sudo`. To avoid having to use `sudo` with the `docker` command, your system administrator can create a Unix group called `docker` and add users to it.

For more information about installing Docker or `sudo` configuration, refer to the [installation](/install/) instructions for your operating system.

### [Display help text](#display-help-text)

To list the help on any command just execute the command, followed by the `--help` option.

```console
$ docker run --help

Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Create and run a new container from an image

Options:
      --add-host value             Add a custom host-to-IP mapping (host:ip) (default [])
  -a, --attach value               Attach to STDIN, STDOUT or STDERR (default [])
<...>
```

### [Environment variables](#environment-variables)

The following environment variables control the behavior of the `docker` command-line client:

| Variable                      | Description                                                                                                                                                                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DOCKER_API_VERSION`          | Override the negotiated API version to use for debugging (e.g. `1.19`)                                                                                                                                                                                       |
| `DOCKER_CERT_PATH`            | Location of your authentication keys. This variable is used both by the `docker` CLI and the [`dockerd` daemon](/reference/cli/dockerd/)                                                                                                                     |
| `DOCKER_CONFIG`               | The location of your client configuration files.                                                                                                                                                                                                             |
| `DOCKER_CONTEXT`              | Name of the `docker context` to use (overrides `DOCKER_HOST` env var and default context set with `docker context use`)                                                                                                                                      |
| `DOCKER_CUSTOM_HEADERS`       | (Experimental) Configure [custom HTTP headers](#custom-http-headers) to be sent by the client. Headers must be provided as a comma-separated list of `name=value` pairs. This is the equivalent to the `HttpHeaders` field in the configuration file.        |
| `DOCKER_DEFAULT_PLATFORM`     | Default platform for commands that take the `--platform` flag.                                                                                                                                                                                               |
| `DOCKER_HIDE_LEGACY_COMMANDS` | When set, Docker hides "legacy" top-level commands (such as `docker rm`, and `docker pull`) in `docker help` output, and only `Management commands` per object-type (e.g., `docker container`) are printed. This may become the default in a future release. |
| `DOCKER_HOST`                 | Daemon socket to connect to.                                                                                                                                                                                                                                 |
| `DOCKER_TLS`                  | Enable TLS for connections made by the `docker` CLI (equivalent of the `--tls` command-line option). Set to a non-empty value to enable TLS. Note that TLS is enabled automatically if any of the other TLS options are set.                                 |
| `DOCKER_TLS_VERIFY`           | When set Docker uses TLS and verifies the remote. This variable is used both by the `docker` CLI and the [`dockerd` daemon](/reference/cli/dockerd/)                                                                                                         |
| `BUILDKIT_PROGRESS`           | Set type of progress output (`auto`, `plain`, `tty`, `rawjson`) when [building](/reference/cli/docker/image/build/) with [BuildKit backend](/build/buildkit/). Use plain to show container output (default `auto`).                                          |
| `NO_COLOR`                    | Disable any ANSI escape codes in the output in accordance with <https://no-color.org/>                                                                                                                                                                       |
|                               |                                                                                                                                                                                                                                                              |

Because Docker is developed using Go, you can also use any environment variables used by the Go runtime. In particular, you may find these useful:

| Variable      | Description                                                                    |
| ------------- | ------------------------------------------------------------------------------ |
| `HTTP_PROXY`  | Proxy URL for HTTP requests unless overridden by NoProxy.                      |
| `HTTPS_PROXY` | Proxy URL for HTTPS requests unless overridden by NoProxy.                     |
| `NO_PROXY`    | Comma-separated values specifying hosts that should be excluded from proxying. |

See the [Go specification](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) for details on these variables.

### [Option types](#option-types)

Single character command line options can be combined, so rather than typing `docker run -i -t --name test busybox sh`, you can write `docker run -it --name test busybox sh`.

#### [Boolean](#boolean)

Boolean options take the form `-d=false`. The value you see in the help text is the default value which is set if you do **not** specify that flag. If you specify a Boolean flag without a value, this will set the flag to `true`, irrespective of the default value.

For example, running `docker run -d` will set the value to `true`, so your container **will** run in "detached" mode, in the background.

Options which default to `true` (e.g., `docker build --rm=true`) can only be set to the non-default value by explicitly setting them to `false`:

```console
$ docker build --rm=false .
```

#### [Multi](#multi)

You can specify options like `-a=[]` multiple times in a single command line, for example in these commands:

```console
$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash

$ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls
```

Sometimes, multiple options can call for a more complex value string as for `-v`:

```console
$ docker run -v /host:/container example/mysql
```

> Note
>
> Do not use the `-t` and `-a stderr` options together due to limitations in the `pty` implementation. All `stderr` in `pty` mode simply goes to `stdout`.

#### [Strings and Integers](#strings-and-integers)

Options like `--name=""` expect a string, and they can only be specified once. Options like `-c=0` expect an integer, and they can only be specified once.

### [Configuration files](#configuration-files)

By default, the Docker command line stores its configuration files in a directory called `.docker` within your `$HOME` directory.

Docker manages most of the files in the configuration directory and you shouldn't modify them. However, you can modify the `config.json` file to control certain aspects of how the `docker` command behaves.

You can modify the `docker` command behavior using environment variables or command-line options. You can also use options within `config.json` to modify some of the same behavior. If an environment variable and the `--config` flag are set, the flag takes precedent over the environment variable. Command line options override environment variables and environment variables override properties you specify in a `config.json` file.

#### [Change the `.docker` directory](#change-the-docker-directory)

To specify a different directory, use the `DOCKER_CONFIG` environment variable or the `--config` command line option. If both are specified, then the `--config` option overrides the `DOCKER_CONFIG` environment variable. The example below overrides the `docker ps` command using a `config.json` file located in the `~/testconfigs/` directory.

```console
$ docker --config ~/testconfigs/ ps
```

This flag only applies to whatever command is being ran. For persistent configuration, you can set the `DOCKER_CONFIG` environment variable in your shell (e.g. `~/.profile` or `~/.bashrc`). The example below sets the new directory to be `HOME/newdir/.docker`.

```console
$ echo export DOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile
```

### [Docker CLI configuration file (`config.json`) properties](#docker-cli-configuration-file-configjson-properties)

[]()

Use the Docker CLI configuration to customize settings for the `docker` CLI. The configuration file uses JSON formatting, and properties:

By default, configuration file is stored in `~/.docker/config.json`. Refer to the [change the `.docker` directory](#change-the-docker-directory) section to use a different location.

> Warning
>
> The configuration file and other files inside the `~/.docker` configuration directory may contain sensitive information, such as authentication information for proxies or, depending on your credential store, credentials for your image registries. Review your configuration file's content before sharing with others, and prevent committing the file to version control.

#### [Customize the default output format for commands](#customize-the-default-output-format-for-commands)

These fields lets you customize the default output format for some commands if no `--format` flag is provided.

| Property               | Description                                                                                                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `configFormat`         | Custom default format for `docker config ls` output. See [`docker config ls`](/reference/cli/docker/config/ls/#format) for a list of supported formatting directives.                   |
| `imagesFormat`         | Custom default format for `docker images` / `docker image ls` output. See [`docker images`](/reference/cli/docker/image/ls/#format) for a list of supported formatting directives.      |
| `networksFormat`       | Custom default format for `docker network ls` output. See [`docker network ls`](/reference/cli/docker/network/ls/#format) for a list of supported formatting directives.                |
| `nodesFormat`          | Custom default format for `docker node ls` output. See [`docker node ls`](/reference/cli/docker/node/ls/#format) for a list of supported formatting directives.                         |
| `pluginsFormat`        | Custom default format for `docker plugin ls` output. See [`docker plugin ls`](/reference/cli/docker/plugin/ls/#format) for a list of supported formatting directives.                   |
| `psFormat`             | Custom default format for `docker ps` / `docker container ps` output. See [`docker ps`](/reference/cli/docker/container/ls/#format) for a list of supported formatting directives.      |
| `secretFormat`         | Custom default format for `docker secret ls` output. See [`docker secret ls`](/reference/cli/docker/secret/ls/#format) for a list of supported formatting directives.                   |
| `serviceInspectFormat` | Custom default format for `docker service inspect` output. See [`docker service inspect`](/reference/cli/docker/service/inspect/#format) for a list of supported formatting directives. |
| `servicesFormat`       | Custom default format for `docker service ls` output. See [`docker service ls`](/reference/cli/docker/service/ls/#format) for a list of supported formatting directives.                |
| `statsFormat`          | Custom default format for `docker stats` output. See [`docker stats`](/reference/cli/docker/container/stats/#format) for a list of supported formatting directives.                     |
| `tasksFormat`          | Custom default format for `docker stack ps` output. See [`docker stack ps`](/reference/cli/docker/stack/ps/#format) for a list of supported formatting directives.                      |
| `volumesFormat`        | Custom default format for `docker volume ls` output. See [`docker volume ls`](/reference/cli/docker/volume/ls/#format) for a list of supported formatting directives.                   |

#### [Custom HTTP headers](#custom-http-headers)

The property `HttpHeaders` specifies a set of headers to include in all messages sent from the Docker client to the daemon. Docker doesn't try to interpret or understand these headers; it simply puts them into the messages. Docker does not allow these headers to change any headers it sets for itself.

Alternatively, use the `DOCKER_CUSTOM_HEADERS` [environment variable](#environment-variables), which is available in v27.1 and higher. This environment-variable is experimental, and its exact behavior may change.

#### [Credential store options](#credential-store-options)

The property `credsStore` specifies an external binary to serve as the default credential store. When this property is set, `docker login` will attempt to store credentials in the binary specified by `docker-credential-<value>` which is visible on `$PATH`. If this property isn't set, credentials are stored in the `auths` property of the CLI configuration file. For more information, see the [**Credential stores** section in the `docker login` documentation](/reference/cli/docker/login/#credential-stores)

The property `credHelpers` specifies a set of credential helpers to use preferentially over `credsStore` or `auths` when storing and retrieving credentials for specific registries. If this property is set, the binary `docker-credential-<value>` will be used when storing or retrieving credentials for a specific registry. For more information, see the [**Credential helpers** section in the `docker login` documentation](/reference/cli/docker/login/#credential-helpers)

#### [Automatic proxy configuration for containers](#automatic-proxy-configuration-for-containers)

The property `proxies` specifies proxy environment variables to be automatically set on containers, and set as `--build-arg` on containers used during `docker build`. A `"default"` set of proxies can be configured, and will be used for any Docker daemon that the client connects to, or a configuration per host (Docker daemon), for example, `https://docker-daemon1.example.com`. The following properties can be set for each environment:

| Property     | Description                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| `httpProxy`  | Default value of `HTTP_PROXY` and `http_proxy` for containers, and as `--build-arg` on `docker build`   |
| `httpsProxy` | Default value of `HTTPS_PROXY` and `https_proxy` for containers, and as `--build-arg` on `docker build` |
| `ftpProxy`   | Default value of `FTP_PROXY` and `ftp_proxy` for containers, and as `--build-arg` on `docker build`     |
| `noProxy`    | Default value of `NO_PROXY` and `no_proxy` for containers, and as `--build-arg` on `docker build`       |
| `allProxy`   | Default value of `ALL_PROXY` and `all_proxy` for containers, and as `--build-arg` on `docker build`     |

These settings are used to configure proxy settings for containers only, and not used as proxy settings for the `docker` CLI or the `dockerd` daemon. Refer to the [environment variables](#environment-variables) section and the [Daemon proxy configuration](/engine/daemon/proxy/) guide for configuring proxy settings for the CLI and daemon.

> Warning
>
> Proxy settings may contain sensitive information (for example, if the proxy requires authentication). Environment variables are stored as plain text in the container's configuration, and as such can be inspected through the remote API or committed to an image when using `docker commit`.

#### [Default key-sequence to detach from containers](#default-key-sequence-to-detach-from-containers)

Once attached to a container, users detach from it and leave it running using the using `CTRL-p CTRL-q` key sequence. This detach key sequence is customizable using the `detachKeys` property. Specify a `<sequence>` value for the property. The format of the `<sequence>` is a comma-separated list of either a letter \[a-Z], or the `ctrl-` combined with any of the following:

* `a-z` (a single lowercase alpha character )
* `@` (at sign)
* `[` (left bracket)
* `\\` (two backward slashes)
* `_` (underscore)
* `^` (caret)

Your customization applies to all containers started in with your Docker client. Users can override your custom or the default key sequence on a per-container basis. To do this, the user specifies the `--detach-keys` flag with the `docker attach`, `docker exec`, `docker run` or `docker start` command.

#### [CLI plugin options](#cli-plugin-options)

The property `plugins` contains settings specific to CLI plugins. The key is the plugin name, while the value is a further map of options, which are specific to that plugin.

#### [Sample configuration file](#sample-configuration-file)

Following is a sample `config.json` file to illustrate the format used for various fields:

```json
{
  "HttpHeaders": {
    "MyHeader": "MyValue"
  },
  "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}",
  "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}",
  "pluginsFormat": "table {{.ID}}\t{{.Name}}\t{{.Enabled}}",
  "statsFormat": "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}",
  "servicesFormat": "table {{.ID}}\t{{.Name}}\t{{.Mode}}",
  "secretFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}",
  "configFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}",
  "serviceInspectFormat": "pretty",
  "nodesFormat": "table {{.ID}}\t{{.Hostname}}\t{{.Availability}}",
  "detachKeys": "ctrl-e,e",
  "credsStore": "secretservice",
  "credHelpers": {
    "awesomereg.example.org": "hip-star",
    "unicorn.example.com": "vcbait"
  },
  "plugins": {
    "plugin1": {
      "option": "value"
    },
    "plugin2": {
      "anotheroption": "anothervalue",
      "athirdoption": "athirdvalue"
    }
  },
  "proxies": {
    "default": {
      "httpProxy":  "http://user:pass@example.com:3128",
      "httpsProxy": "https://my-proxy.example.com:3129",
      "noProxy":    "intra.mycorp.example.com",
      "ftpProxy":   "http://user:pass@example.com:3128",
      "allProxy":   "socks://example.com:1234"
    },
    "https://manager1.mycorp.example.com:2377": {
      "httpProxy":  "http://user:pass@example.com:3128",
      "httpsProxy": "https://my-proxy.example.com:3129"
    }
  }
}
```

#### [Experimental features](#experimental-features)

Experimental features provide early access to future product functionality. These features are intended for testing and feedback, and they may change between releases without warning or can be removed from a future release.

Starting with Docker 20.10, experimental CLI features are enabled by default, and require no configuration to enable them.

#### [Notary](#notary)

If using your own notary server and a self-signed certificate or an internal Certificate Authority, you need to place the certificate at `tls/<registry_url>/ca.crt` in your Docker config directory.

Alternatively you can trust the certificate globally by adding it to your system's list of root Certificate Authorities.

## [Options](#options)

| Option                | Default                  | Description                                                                                                                             |
| --------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--config`            | `/root/.docker`          | Location of client config files                                                                                                         |
| `-c, --context`       |                          | Name of the context to use to connect to the daemon (overrides DOCKER\_HOST env var and default context set with `docker context use`)  |
| `-D, --debug`         |                          | Enable debug mode                                                                                                                       |
| [`-H, --host`](#host) |                          | Daemon socket to connect to                                                                                                             |
| `-l, --log-level`     | `info`                   | Set the logging level (`debug`, `info`, `warn`, `error`, `fatal`)                                                                       |
| `--tls`               |                          | Use TLS; implied by --tlsverify                                                                                                         |
| `--tlscacert`         | `/root/.docker/ca.pem`   | Trust certs signed only by this CA                                                                                                      |
| `--tlscert`           | `/root/.docker/cert.pem` | Path to TLS certificate file                                                                                                            |
| `--tlskey`            | `/root/.docker/key.pem`  | Path to TLS key file                                                                                                                    |
| `--tlsverify`         |                          | Use TLS and verify the remote                                                                                                           |

## [Examples](#examples)

### [Specify daemon host (-H, --host)](#host)

You can use the `-H`, `--host` flag to specify a socket to use when you invoke a `docker` command. You can use the following protocols:

| Scheme                                 | Description               | Example                          |
| -------------------------------------- | ------------------------- | -------------------------------- |
| `unix://[<path>]`                      | Unix socket (Linux only)  | `unix:///var/run/docker.sock`    |
| `tcp://[<IP or host>[:port]]`          | TCP connection            | `tcp://174.17.0.1:2376`          |
| `ssh://[username@]<IP or host>[:port]` | SSH connection            | `ssh://user@192.168.64.5`        |
| `npipe://[<name>]`                     | Named pipe (Windows only) | `npipe:////./pipe/docker_engine` |

If you don't specify the `-H` flag, and you're not using a custom [context](/engine/context/working-with-contexts), commands use the following default sockets:

* `unix:///var/run/docker.sock` on macOS and Linux
* `npipe:////./pipe/docker_engine` on Windows

To achieve a similar effect without having to specify the `-H` flag for every command, you could also [create a context](/reference/cli/docker/context/create/), or alternatively, use the [`DOCKER_HOST` environment variable](#environment-variables).

For more information about the `-H` flag, see [Daemon socket option](/reference/cli/dockerd/#daemon-socket-option).

#### [Using TCP sockets](#using-tcp-sockets)

The following example shows how to invoke `docker ps` over TCP, to a remote daemon with IP address `174.17.0.1`, listening on port `2376`:

```console
$ docker -H tcp://174.17.0.1:2376 ps
```

> Note
>
> By convention, the Docker daemon uses port `2376` for secure TLS connections, and port `2375` for insecure, non-TLS connections.

#### [Using SSH sockets](#using-ssh-sockets)

When you use SSH invoke a command on a remote daemon, the request gets forwarded to the `/var/run/docker.sock` Unix socket on the SSH host.

```console
$ docker -H ssh://user@192.168.64.5 ps
```

You can optionally specify the location of the socket by appending a path component to the end of the SSH address.

```console
$ docker -H ssh://user@192.168.64.5/var/run/docker.sock ps
```

## [Subcommands](#subcommands)

| Command                                                                         | Description                                                                                |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [`docker builder`](https://docs.docker.com/reference/cli/docker/builder/)       | Manage builds                                                                              |
| [`docker buildx`](https://docs.docker.com/reference/cli/docker/buildx/)         | Docker Buildx                                                                              |
| [`docker checkpoint`](https://docs.docker.com/reference/cli/docker/checkpoint/) | Manage checkpoints                                                                         |
| [`docker compose`](https://docs.docker.com/reference/cli/docker/compose/)       | Docker Compose                                                                             |
| [`docker config`](https://docs.docker.com/reference/cli/docker/config/)         | Manage Swarm configs                                                                       |
| [`docker container`](https://docs.docker.com/reference/cli/docker/container/)   | Manage containers                                                                          |
| [`docker context`](https://docs.docker.com/reference/cli/docker/context/)       | Manage contexts                                                                            |
| [`docker debug`](https://docs.docker.com/reference/cli/docker/debug/)           | Get a shell into any container or image. An alternative to debugging with \`docker exec\`. |
| [`docker desktop`](https://docs.docker.com/reference/cli/docker/desktop/)       | Docker Desktop                                                                             |
| [`docker dhi`](https://docs.docker.com/reference/cli/docker/dhi/)               | CLI for managing Docker Hardened Images                                                    |
| [`docker image`](https://docs.docker.com/reference/cli/docker/image/)           | Manage images                                                                              |
| [`docker init`](https://docs.docker.com/reference/cli/docker/init/)             | Creates Docker-related starter files for your project                                      |
| [`docker inspect`](https://docs.docker.com/reference/cli/docker/inspect/)       | Return low-level information on Docker objects                                             |
| [`docker login`](https://docs.docker.com/reference/cli/docker/login/)           | Authenticate to a registry                                                                 |
| [`docker logout`](https://docs.docker.com/reference/cli/docker/logout/)         | Log out from a registry                                                                    |
| [`docker manifest`](https://docs.docker.com/reference/cli/docker/manifest/)     | Manage Docker image manifests and manifest lists                                           |
| [`docker mcp`](https://docs.docker.com/reference/cli/docker/mcp/)               | Manage MCP servers and clients                                                             |
| [`docker model`](https://docs.docker.com/reference/cli/docker/model/)           | Docker Model Runner                                                                        |
| [`docker network`](https://docs.docker.com/reference/cli/docker/network/)       | Manage networks                                                                            |
| [`docker node`](https://docs.docker.com/reference/cli/docker/node/)             | Manage Swarm nodes                                                                         |
| [`docker offload`](https://docs.docker.com/reference/cli/docker/offload/)       | Control Docker Offload from the CLI                                                        |
| [`docker pass`](https://docs.docker.com/reference/cli/docker/pass/)             | Manage your local OS keychain secrets.                                                     |
| [`docker plugin`](https://docs.docker.com/reference/cli/docker/plugin/)         | Manage plugins                                                                             |
| [`docker sandbox`](https://docs.docker.com/reference/cli/docker/sandbox/)       | Docker Sandbox                                                                             |
| [`docker scout`](https://docs.docker.com/reference/cli/docker/scout/)           | Command line tool for Docker Scout                                                         |
| [`docker search`](https://docs.docker.com/reference/cli/docker/search/)         | Search Docker Hub for images                                                               |
| [`docker secret`](https://docs.docker.com/reference/cli/docker/secret/)         | Manage Swarm secrets                                                                       |
| [`docker service`](https://docs.docker.com/reference/cli/docker/service/)       | Manage Swarm services                                                                      |
| [`docker stack`](https://docs.docker.com/reference/cli/docker/stack/)           | Manage Swarm stacks                                                                        |
| [`docker swarm`](https://docs.docker.com/reference/cli/docker/swarm/)           | Manage Swarm                                                                               |
| [`docker system`](https://docs.docker.com/reference/cli/docker/system/)         | Manage Docker                                                                              |
| [`docker trust`](https://docs.docker.com/reference/cli/docker/trust/)           | Manage trust on Docker images                                                              |
| [`docker version`](https://docs.docker.com/reference/cli/docker/version/)       | Show the Docker version information                                                        |
| [`docker volume`](https://docs.docker.com/reference/cli/docker/volume/)         | Manage volumes                                                                             |

----
url: https://docs.docker.com/reference/build-checks/consistent-instruction-casing/
----

# ConsistentInstructionCasing

***

Table of contents

***

## [Output](#output)

```text
Command 'EntryPoint' should be consistently cased
```

## [Description](#description)

Instruction keywords should use consistent casing (all lowercase or all uppercase). Using a case that mixes uppercase and lowercase, such as `PascalCase` or `snakeCase`, letters result in poor readability.

## [Examples](#examples)

❌ Bad: don't mix uppercase and lowercase.

```dockerfile
From alpine
Run echo hello > /greeting.txt
EntRYpOiNT ["cat", "/greeting.txt"]
```

✅ Good: all uppercase.

```dockerfile
FROM alpine
RUN echo hello > /greeting.txt
ENTRYPOINT ["cat", "/greeting.txt"]
```

✅ Good: all lowercase.

```dockerfile
from alpine
run echo hello > /greeting.txt
entrypoint ["cat", "/greeting.txt"]
```

----
url: https://docs.docker.com/reference/cli/docker/model/search/
----

# docker model search

***

| Description | Search for models on Docker Hub and HuggingFace |
| ----------- | ----------------------------------------------- |
| Usage       | `docker model search [OPTIONS] [TERM]`          |

## [Description](#description)

Search for models from Docker Hub (ai/ namespace) and HuggingFace.

When no search term is provided, lists all available models. When a search term is provided, filters models by name/description.

Examples: docker model search # List available models from Docker Hub docker model search llama # Search for models containing "llama" docker model search --source=all # Search both Docker Hub and HuggingFace docker model search --source=huggingface # Only search HuggingFace docker model search --limit=50 phi # Search with custom limit docker model search --json llama # Output as JSON

## [Options](#options)

| Option        | Default | Description                                   |
| ------------- | ------- | --------------------------------------------- |
| `--json`      |         | Output results as JSON                        |
| `-n, --limit` | `32`    | Maximum number of results to show             |
| `--source`    | `all`   | Source to search: all, dockerhub, huggingface |

----
url: https://docs.docker.com/guides/testcontainers-nodejs-getting-started/
----

# Getting started with Testcontainers for Node.js

Table of contents

***

Learn how to create a Node.js application and test database interactions using Testcontainers for Node.js with a real PostgreSQL instance.

**Time to complete** 15 minutes

In this guide, you will learn how to:

* Create a Node.js application that stores and retrieves customers from PostgreSQL
* Write integration tests using Testcontainers and Jest
* Run tests against a real PostgreSQL database in a Docker container

## [Prerequisites](#prerequisites)

* Node.js 18+
* npm
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-nodejs-getting-started/create-project/)

   Set up a Node.js project with a PostgreSQL-backed customer repository.

2. [Write tests](https://docs.docker.com/guides/testcontainers-nodejs-getting-started/write-tests/)

   Write integration tests using Testcontainers for Node.js and Jest with a real PostgreSQL database.

3. [Run tests](https://docs.docker.com/guides/testcontainers-nodejs-getting-started/run-tests/)

   Run your Testcontainers-based integration tests and explore next steps.

----
url: https://docs.docker.com/desktop/setup/install/mac-install/
----

# Install Docker Desktop on Mac

***

Table of contents

***

> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250 employees or more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopMacInstall).

This page provides download links, system requirements, and step-by-step installation instructions for Docker Desktop on Mac.

[Docker Desktop for Mac with Apple silicon](https://desktop.docker.com/mac/main/arm64/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-arm64) [Docker Desktop for Mac with Intel chip](https://desktop.docker.com/mac/main/amd64/Docker.dmg?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-mac-amd64)

*For checksums, see [Release notes](https://docs.docker.com/desktop/release-notes/).*

## [System requirements](#system-requirements)

* A supported version of macOS.

  > Important
  >
  > Docker Desktop is supported on the current and two previous major macOS releases. As new major versions of macOS are made generally available, Docker stops supporting the oldest version and supports the newest version of macOS (in addition to the previous two releases).

* At least 4 GB of RAM.

* For the best experience, it's recommended that you install Rosetta 2. Rosetta 2 is no longer strictly required, however there are a few optional command line tools that still require Rosetta 2 when using Darwin/AMD64. See [Known issues](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/known-issues/). To install Rosetta 2 manually from the command line, run the following command:

  ```console
  $ softwareupdate --install-rosetta
  ```

- A supported version of macOS.

  > Important
  >
  > Docker Desktop is supported on the current and two previous major macOS releases. As new major versions of macOS are made generally available, Docker stops supporting the oldest version and supports the newest version of macOS (in addition to the previous two releases).

- At least 4 GB of RAM.

> **Before you install or update**
>
> * Quit tools that might call Docker in the background (Visual Studio Code, terminals, agent apps).
>
> * If you manage fleets or install via MDM, use the [**PKG installer**](https://docs.docker.com/enterprise/enterprise-deployment/pkg-install-and-configure/).
>
> * Keep the installer volume mounted until the installation completes.
>
> If you encounter a "Docker.app is damaged" dialog, see [Fix "Docker.app is damaged" on macOS](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog/).

## [Install and run Docker Desktop on Mac](#install-and-run-docker-desktop-on-mac)

> Tip
>
> See the [FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/general/#how-do-I-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges.

### [Install interactively](#install-interactively)

1. Download the installer using the download buttons at the top of the page, or from the [release notes](https://docs.docker.com/desktop/release-notes/).

2. Double-click `Docker.dmg` to open the installer, then drag the Docker icon to the **Applications** folder. By default, Docker Desktop is installed at `/Applications/Docker.app`.

3. Double-click `Docker.app` in the **Applications** folder to start Docker.

4. The Docker menu displays the Docker Subscription Service Agreement.

   Here’s a summary of the key points:

   * Docker Desktop is free for small businesses (fewer than 250 employees AND less than $10 million in annual revenue), personal use, education, and non-commercial open source projects.
   * Otherwise, it requires a paid subscription for professional use.
   * Paid subscriptions are also required for government entities.
   * Docker Pro, Team, and Business subscriptions include commercial use of Docker Desktop.

5. Select **Accept** to continue.

   Note that Docker Desktop won't run if you do not agree to the terms. You can choose to accept the terms at a later date by opening Docker Desktop.

   For more information, see [Docker Desktop Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement). It is recommended that you also read the [FAQs](https://www.docker.com/pricing/faq).

6. From the installation window, select either:

   * **Use recommended settings (Requires password)**. This lets Docker Desktop automatically set the necessary configuration settings.
   * **Use advanced settings**. You can then set the location of the Docker CLI tools either in the system or user directory, enable the default Docker socket, and enable privileged port mapping. See [Settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#advanced), for more information and how to set the location of the Docker CLI tools.

7. Select **Finish**. If you have applied any of the previous configurations that require a password in step 6, enter your password to confirm your choice.

### [Install from the command line](#install-from-the-command-line)

After downloading `Docker.dmg` from either the download buttons at the top of the page or from the [release notes](https://docs.docker.com/desktop/release-notes/), run the following commands in a terminal to install Docker Desktop in the **Applications** folder:

```console
$ sudo hdiutil attach Docker.dmg
$ sudo /Volumes/Docker/Docker.app/Contents/MacOS/install
$ sudo hdiutil detach /Volumes/Docker
```

By default, Docker Desktop is installed at `/Applications/Docker.app`. As macOS typically performs security checks the first time an application is used, the `install` command can take several minutes to run.

#### [Installer flags](#installer-flags)

The `install` command accepts the following flags:

##### [Installation behavior](#installation-behavior)

* `--accept-license`: Accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) now, rather than requiring it to be accepted when the application is first run.
* `--user=<username>`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](https://docs.docker.com/desktop/setup/install/mac-permission-requirements/#permission-requirements). To find the username, enter `ls /Users` in the CLI.

##### [Security and access](#security-and-access)

* `--allowed-org=<org name>`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application

* `--user=<username>`: Performs the privileged configurations once during installation. This removes the need for the user to grant root privileges on first run. For more information, see [Privileged helper permission requirements](https://docs.docker.com/desktop/setup/install/mac-permission-requirements/#permission-requirements). To find the username, enter `ls /Users` in the CLI.

* `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by administrators to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/).

  * It must be used together with the `--allowed-org=<org name>` flag.
  * For example: `--allowed-org=<org name> --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"`

##### [Proxy configuration](#proxy-configuration)

* `--proxy-http-mode=<mode>`: Sets the HTTP Proxy mode. The two modes are `system` (default) or `manual`.
* `--override-proxy-http=<URL>`: Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests. It requires `--proxy-http-mode` to be `manual`.
* `--override-proxy-https=<URL>`: Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests, requires `--proxy-http-mode` to be `manual`
* `--override-proxy-exclude=<hosts/domains>`: Bypasses proxy settings for the hosts and domains. It's a comma-separated list.
* `--override-proxy-pac=<PAC file URL>`: Sets the PAC file URL. This setting takes effect only when using `manual` proxy mode.
* `--override-proxy-embedded-pac=<PAC script>`: Specifies an embedded PAC (Proxy Auto-Config) script. This setting takes effect only when using `manual` proxy mode and has precedence over the `--override-proxy-pac` flag.

###### [Example of specifying PAC file](#example-of-specifying-pac-file)

```console
$ sudo /Applications/Docker.app/Contents/MacOS/install --user testuser --proxy-http-mode="manual" --override-proxy-pac="http://localhost:8080/myproxy.pac"
```

###### [Example of specifying PAC script](#example-of-specifying-pac-script)

```console
$ sudo /Applications/Docker.app/Contents/MacOS/install --user testuser --proxy-http-mode="manual" --override-proxy-embedded-pac="function FindProxyForURL(url, host) { return \"DIRECT\"; }"
```

> Tip
>
> As an IT administrator, you can use endpoint management (MDM) software to identify the number of Docker Desktop instances and their versions within your environment. This can provide accurate license reporting, help ensure your machines use the latest version of Docker Desktop, and enable you to [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).
>
> * [Intune](https://learn.microsoft.com/en-us/mem/intune/apps/app-discovered-apps)
> * [Jamf](https://docs.jamf.com/10.25.0/jamf-pro/administrator-guide/Application_Usage.html)
> * [Kandji](https://support.kandji.io/support/solutions/articles/72000559793-view-a-device-application-list)
> * [Kolide](https://www.kolide.com/features/device-inventory/properties/mac-apps)
> * [Workspace One](https://blogs.vmware.com/euc/2022/11/how-to-use-workspace-one-intelligence-to-manage-app-licenses-and-reduce-costs.html)

## [Where to go next](#where-to-go-next)

* Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopMacInstall) to see what Docker can offer you.
* [Get started with Docker](https://docs.docker.com/get-started/introduction/).
* [Explore Docker Desktop](https://docs.docker.com/desktop/use-desktop/) and all its features.
* [Troubleshooting](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/) describes common problems, workarounds, how to run and submit diagnostics, and submit issues.
* [FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/general/) provide answers to frequently asked questions.
* [Release notes](https://docs.docker.com/desktop/release-notes/) lists component updates, new features, and improvements associated with Docker Desktop releases.
* [Back up and restore data](https://docs.docker.com/desktop/settings-and-maintenance/backup-and-restore/) provides instructions on backing up and restoring data related to Docker.

----
url: https://docs.docker.com/build/bake/funcs/
----

# Functions

***

Table of contents

***

HCL functions are great for when you need to manipulate values in your build configuration in more complex ways than just concatenation or interpolation.

## [Standard library](#standard-library)

Bake ships with built-in support for the [standard library functions](https://docs.docker.com/build/bake/stdlib/).

The following example shows the `add` function:

docker-bake.hcl

```hcl
variable "TAG" {
  default = "latest"
}

group "default" {
  targets = ["webapp"]
}

target "webapp" {
  args = {
    buildno = "${add(123, 1)}"
  }
}
```

```console
$ docker buildx bake --print webapp
```

```json
{
  "group": {
    "default": {
      "targets": ["webapp"]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "buildno": "124"
      }
    }
  }
}
```

## [User-defined functions](#user-defined-functions)

You can create [user-defined functions](https://github.com/hashicorp/hcl/tree/main/ext/userfunc) that do just what you want, if the built-in standard library functions don't meet your needs.

The following example defines an `increment` function.

docker-bake.hcl

```hcl
function "increment" {
  params = [number]
  result = number + 1
}

group "default" {
  targets = ["webapp"]
}

target "webapp" {
  args = {
    buildno = "${increment(123)}"
  }
}
```

```console
$ docker buildx bake --print webapp
```

```json
{
  "group": {
    "default": {
      "targets": ["webapp"]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": {
        "buildno": "124"
      }
    }
  }
}
```

## [Variables in functions](#variables-in-functions)

You can make references to [variables](https://docs.docker.com/build/bake/variables/) and standard library functions inside your functions.

The following example uses a global variable (`REPO`) in a custom function.

docker-bake.hcl

```hcl
# docker-bake.hcl
variable "REPO" {
  default = "user/repo"
}

function "tag" {
  params = [tag]
  result = ["${REPO}:${tag}"]
}

target "webapp" {
  tags = tag("v1")
}
```

Printing the Bake file with the `--print` flag shows that the `tag` function uses the value of `REPO` to set the prefix of the tag.

```console
$ docker buildx bake --print webapp
```

```json
{
  "group": {
    "default": {
      "targets": ["webapp"]
    }
  },
  "target": {
    "webapp": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "tags": ["user/repo:v1"]
    }
  }
}
```

----
url: https://docs.docker.com/dhi/explore/feedback/
----

***

Table of contents

***

Committed to maintaining the quality, security, and reliability of the Docker Hardened Images (DHI) a repository has been created as a point of contact to encourage the community to collaborate in improving the Hardened Images ecosystem.

## [Questions or discussions](#questions-or-discussions)

You can use the [GitHub Discussions board](https://github.com/orgs/docker-hardened-images/discussions) to engage with the DHI team for:

* General questions about DHIs
* Best practices and recommendations
* Security tips and advice
* Show and tell your implementations
* Community announcements

## [Reporting bugs or issues](#reporting-bugs-or-issues)

You can [open a new issue](https://github.com/docker-hardened-images/catalog/issues) for topics such as:

* Bug reports
* Feature requests
* Documentation improvements
* Security vulnerabilities (see security policy)

It's encouraged to first search existing issues to see if it’s already been reported. The DHI team reviews reports regularly and appreciates clear, actionable feedback.

## [Responsible security disclosure](#responsible-security-disclosure)

It is forbidden to post details of vulnerabilities before coordinated disclosure and resolution.

If you discover a security vulnerability, report it responsibly by following Docker’s [security disclosure](https://www.docker.com/trust/vulnerability-disclosure-policy/).

----
url: https://docs.docker.com/docker-hub/
----

# Docker Hub

***

***

Docker Hub simplifies development with the world's largest container registry for storing, managing, and sharing Docker images. By integrating seamlessly with your tools, it enhances productivity and ensures reliable deployment, distribution, and access to containerized applications. It also provides developers with pre-built images and assets to speed up development workflows.

Key features of Docker Hub:

* Unlimited public repositories
* Private repositories
* Webhooks to automate workflows
* GitHub and Bitbucket integrations
* Concurrent and automated builds
* Trusted content featuring high-quality, secure images

In addition to the graphical interface, you can interact with Docker Hub using the [Docker Hub API](https://docs.docker.com/reference/api/hub/latest/) or experimental [Docker Hub CLI tool](https://github.com/docker/hub-tool#readme).

### [Quickstart](/docker-hub/quickstart)

[Step-by-step instructions on getting started on Docker Hub.](/docker-hub/quickstart)

### [Library](/docker-hub/image-library/)

[Explore the content library, featuring millions of images for operating systems, frameworks, databases, and more.](/docker-hub/image-library/)

### [Repositories](/docker-hub/repos)

[Create a repository to share your images with your team, customers, or the Docker community.](/docker-hub/repos)

### [Settings](/docker-hub/settings)

[Learn about settings in Docker Hub.](/docker-hub/settings)

### [Organizations](/admin/)

[Learn about organization administration.](/admin/)

### [Usage and limits](/docker-hub/usage/)

[Explore usage limits and how to better utilize Docker Hub.](/docker-hub/usage/)

### [Release notes](/docker-hub/release-notes)

[Find out about new features, improvements, and bug fixes.](/docker-hub/release-notes)

----
url: https://docs.docker.com/reference/cli/docker/model/context/rm/
----

# docker model context rm

***

| Description                                                               | Remove one or more Model Runner contexts |
| ------------------------------------------------------------------------- | ---------------------------------------- |
| Usage                                                                     | `docker model context rm NAME [NAME...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker model context remove`            |

## [Description](#description)

Remove one or more Model Runner contexts

----
url: https://docs.docker.com/scout/policy/remediation/
----

# Remediation with Docker Scout

***

Table of contents

***

Availability: Beta

Docker Scout helps you remediate supply chain or security issues by providing recommendations based on policy evaluation results. Recommendations are suggested actions you can take that improve policy compliance, or that add metadata to images which enables Docker Scout to provide better evaluation results and recommendations.

Docker Scout provides remediation advice for the default policies of the following policy types:

* [Up-to-Date Base Images](#up-to-date-base-images-remediation)
* [Supply Chain Attestations](#supply-chain-attestations-remediation)

> Note
>
> Guided remediation is not supported for custom policies.

For images that violate policy, the recommendations focus on addressing compliance issues and fixing violations. For images where Docker Scout is unable to determine compliance, recommendations show you how to meet the prerequisites that ensure Docker Scout can successfully evaluate the policy.

## [View recommendations](#view-recommendations)

Recommendations appear on the policy details pages of the Docker Scout Dashboard. To get to this page:

1. Go to the [Policies page](https://scout.docker.com/reports/policy) in the Docker Scout Dashboard.
2. Select a policy in the list.

The policy details page groups evaluation results into two different tabs depending on the policy status:

* Violations
* Compliance unknown

The **Violations** tab lists images that don't comply with the selected policy. The **Compliance unknown** tab lists images that Docker Scout is unable to determine the compliance status for. When compliance is unknown, Docker Scout needs more information about the image.

To view recommended actions for an image, hover over one of the images in the list to reveal a **View fixes** button.

Select the **View fixes** button to opens the remediation side panel containing recommended actions for your image.

If there are more than one recommendations available, the primary recommendation displays as the **Recommended fix**. Additional recommendations are listed as **Quick fixes**. Quick fixes are usually actions that provide a temporary solution.

The side panel may also contain one or more help sections related to the available recommendations.

## [Up-to-Date Base Images remediation](#up-to-date-base-images-remediation)

The **Up-to-Date Base Images** policy checks whether the base image you use is up-to-date. The recommended actions displayed in the remediation side panel depend on how much information Docker Scout has about your image. The more information that's available, the better the recommendations.

The following scenarios outline the different recommendations depending on the information available about the image.

### [No provenance attestations](#no-provenance-attestations)

For Docker Scout to be able to evaluate this policy, you must add [provenance attestations](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) to your image. If your image doesn't have provenance attestations, compliance is undeterminable.

### [Provenance attestations available](#provenance-attestations-available)

With provenance attestations added, Docker Scout can correctly detect the base image version that you're using. The version found in the attestations is cross-referenced against the current version of the corresponding tag to determine if it's up-to-date.

If there's a policy violation, the recommended actions show how to update your base image version to the latest version, while also pinning the base image version to a specific digest. For more information, see [Pin base image versions](https://docs.docker.com/build/building/best-practices/#pin-base-image-versions).

### [GitHub integration enabled](#github-integration-enabled)

If you're hosting the source code for your image on GitHub, you can enable the [GitHub integration](https://docs.docker.com/scout/integrations/source-code-management/github/). This integration enables Docker Scout to provide even more useful remediation advice, and lets you initiate remediation for violations directly from the Docker Scout Dashboard.

With the GitHub integration enabled, you can use the remediation side panel to raise a pull request on the GitHub repository of the image. The pull request automatically updates the base image version in your Dockerfile to the up-to-date version.

This automated remediation pins your base image to a specific digest, while helping you stay up-to-date as new versions become available. Pinning the base image to a digest is important for reproducibility, and helps avoid unwanted changes from making their way into your supply chain.

For more information about base image pinning, see [Pin base image versions](https://docs.docker.com/build/building/best-practices/#pin-base-image-versions).

## [Supply Chain Attestations remediation](#supply-chain-attestations-remediation)

The default **Supply Chain Attestations** policy requires full provenance and SBOM attestations on images. If your image is missing an attestation, or if an attestation doesn't contain enough information, the policy is violated.

The recommendations available in the remediation side panel helps guide you to what action you need to take to address the issues. For example, if your image has a provenance attestation, but the attestation doesn't contain enough information, you're recommended to re-build your image with [`mode=max`](https://docs.docker.com/build/metadata/attestations/slsa-provenance/#max) provenance.

----
url: https://docs.docker.com/reference/cli/docker/model/reinstall-runner/
----

# docker model reinstall-runner

***

| Description | Reinstall Docker Model Runner (Docker Engine only) |
| ----------- | -------------------------------------------------- |
| Usage       | `docker model reinstall-runner`                    |

## [Description](#description)

This command removes the existing Docker Model Runner container and reinstalls it with the specified configuration. Models and images are preserved during reinstallation.

## [Options](#options)

| Option           | Default     | Description                                                                                             |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| `--backend`      |             | Specify backend (llama.cpp\|vllm\|diffusers). Default: llama.cpp                                        |
| `--debug`        |             | Enable debug logging                                                                                    |
| `--do-not-track` |             | Do not track models usage in Docker Model Runner                                                        |
| `--gpu`          | `auto`      | Specify GPU support (none\|auto\|cuda\|rocm\|musa\|cann)                                                |
| `--host`         | `127.0.0.1` | Host address to bind Docker Model Runner                                                                |
| `--port`         |             | Docker container port for Docker Model Runner (default: 12434 for Docker Engine, 12435 for Cloud mode)  |
| `--proxy-cert`   |             | Path to a CA certificate file for proxy SSL inspection                                                  |
| `--tls`          |             | Enable TLS/HTTPS for Docker Model Runner API                                                            |
| `--tls-cert`     |             | Path to TLS certificate file (auto-generated if not provided)                                           |
| `--tls-key`      |             | Path to TLS private key file (auto-generated if not provided)                                           |
| `--tls-port`     |             | TLS port for Docker Model Runner (default: 12444 for Docker Engine, 12445 for Cloud mode)               |

----
url: https://docs.docker.com/guides/admin-user-management/setup/
----

# Setting up roles and permissions in Docker

***

Table of contents

***

With the right configurations, you can ensure your developers have easy access to necessary resources while preventing unauthorized access. This page guides you through identifying Docker users so you can allocate subscription seats efficiently within your Docker organization, and assigning roles to align with your organization's structure.

## [Identify your Docker users and accounts](#identify-your-docker-users-and-accounts)

Before setting up roles and permissions, it's important to have a clear understanding of who in your organization requires Docker access. Focus on gathering a comprehensive view of active users, their roles within projects, and how they interact with Docker resources. This process can be supported by tools like device management software or manual assessments. Encourage all users to update their Docker accounts to use organizational email addresses, ensuring seamless integration with your subscription.

For steps on how you can do this, see [step 1 of onboarding your organization](https://docs.docker.com/admin/organization/setup/onboard/).

## [Assign roles strategically](#assign-roles-strategically)

When you invite members to join your Docker organization, you assign them a role.

Docker's predefined roles offer flexibility for various organizational needs. Assigning roles effectively ensures a balance of accessibility and security.

* Member: Non-administrative role. Members can view other members that are in the same organization.
* Editor: Partial administrative access to the organization. Editors can create, edit, and delete repositories. They can also edit an existing team's access permissions.
* Owner: Full organization administrative access. Owners can manage organization repositories, teams, members, settings, and billing.

For more information, see [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/).

### [Enhance with teams](#enhance-with-teams)

Teams in Docker provide a structured way to manage member access and they provide an additional level of permissions. They simplify permission management and enable consistent application of policies.

* Organize users into teams aligned with projects, departments, or functional roles. This approach helps streamline resource allocation and ensures clarity in access control.
* Assign permissions at the team level rather than individually. For instance, a development team might have "Read & Write" access to certain repositories, while a QA team has "Read-only" access.
* As teams grow or responsibilities shift, you can easily update permissions or add new members, maintaining consistency without reconfiguring individual settings.

For more information, see [Create and manage a team](https://docs.docker.com/admin/organization/manage/manage-a-team/).

### [Example scenarios](#example-scenarios)

* Development teams: Assign the member role to developers, granting access to the repositories needed for coding and testing.
* Team leads: Assign the editor role to team leads for resource management and repository control within their teams.
* Organizational oversight: Restrict the organization owner or company owner roles to a select few trusted individuals responsible for billing and security settings.

### [Best practices](#best-practices)

* Apply the principle of least privilege. Assign users only the minimum permissions necessary for their roles.
* Conduct regular reviews of role assignments to ensure they align with evolving team structures and organizational responsibilities.

[Onboarding and managing roles and permissions in Docker »](https://docs.docker.com/guides/admin-user-management/onboard/)

----
url: https://docs.docker.com/reference/cli/sbx/completion/fish/
----

# sbx completion fish

| Description | Generate the autocompletion script for fish |
| ----------- | ------------------------------------------- |
| Usage       | `sbx completion fish [flags]`               |

## [Description](#description)

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

```
sbx completion fish | source
```

To load completions for every new session, execute once:

```
sbx completion fish > ~/.config/fish/completions/sbx.fish
```

You will need to start a new shell for this setup to take effect.

## [Options](#options)

| Option              | Default | Description                     |
| ------------------- | ------- | ------------------------------- |
| `--no-descriptions` |         | disable completion descriptions |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/admin/company/new-company/
----

# Create new company

***

Table of contents

***

Subscription: Business

For: Administrators

Learn how to create a new company in the Docker Admin Console, a centralized dashboard for managing organizations.

## [Prerequisites](#prerequisites)

Before you begin, you must:

* Be the owner of the organization you want to add to your company
* Have a Docker Business subscription

## [Create a company](#create-a-company)

To create a new company:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.

2. Select **Admin Console**, then **Company management**.

3. Select **Create a company**.

4. Enter a unique name for your company, then select **Continue**.

   > Tip
   >
   > The name for your company can't be the same as an existing user, organization, or company namespace.

5. Review the migration details and then select **Create company**.

For more information on how you can add organizations to your company, see [Add organizations to a company](https://docs.docker.com/admin/company/manage/organizations/#add-organizations-to-a-company).

## [Next steps](#next-steps)

* [Manage organizations](https://docs.docker.com/admin/company/manage/organizations/)
* [Manage company members](https://docs.docker.com/admin/company/manage/users/)
* [Manage company owners](https://docs.docker.com/admin/company/manage/owners/)

## [More resources](#more-resources)

* [Video: Create a company](https://youtu.be/XZ5_i6qiKho?feature=shared\&t=359)

----
url: https://docs.docker.com/guides/ros2/
----

# Introduction to ROS 2 Development with Docker

Table of contents

***

This guide details how to containerize ROS 2 applications using Docker.

**Time to complete** 30 minutes

> **Acknowledgment**
>
> This guide is a community contribution. Docker would like to thank [Shakirth Anisha](https://www.linkedin.com/in/shakirth-anisha/) for her contribution to this guide.

[ROS 2](https://www.ros.org/) is a set of software libraries and tools for building robot applications. It uses Data Distribution Service (DDS) for real-time, secure communication between distributed nodes, making it ideal for robotics and autonomous systems.

***

## [What will you learn?](#what-will-you-learn)

In this guide, you'll learn how to:

* Use official ROS 2 base images from Docker Hub
* Run ROS 2 in an Ubuntu container
* Install ROS 2 packages and dependencies
* Set up a development container for local development
* Run a complete end-to-end example with Turtlesim

## [Prerequisites](#prerequisites)

Before you begin, make sure you're familiar with the following:

* [Docker Desktop](https://docs.docker.com/desktop/): You must have Docker Desktop installed and running.
* [Docker concepts](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/): You must understand core Docker concepts, such as images and containers.
* [ROS 2 concepts](https://www.ros.org): Basic understanding of concepts like nodes, packages, topics, and services.

## [What's next?](#whats-next)

Start by setting up your ROS 2 development environment using Docker and dev containers.

## [Modules](#modules)

1. [Run ROS 2](https://docs.docker.com/guides/ros2/run-ros2/)

   Run ROS 2 in an isolated Docker container using official ROS 2 images and install additional ROS 2 packages.

2. [Set Up ROS 2 workspace](https://docs.docker.com/guides/ros2/develop/)

   Learn how to develop ROS 2 applications using a Docker based workspace and development containers.

3. [Turtlesim example](https://docs.docker.com/guides/ros2/turtlesim-example/)

   Run a complete end-to-end ROS 2 example with Turtlesim.

----
url: https://docs.docker.com/reference/samples/flask/
----

# Flask samples

| Name                                                                                               | Description                                                                 |
| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [NGINX / Flask / MongoDB](https://github.com/docker/awesome-compose/tree/master/nginx-flask-mongo) | A sample Python/Flask application with Nginx proxy and a Mongo database.    |
| [NGINX / Flask / MySQL](https://github.com/docker/awesome-compose/tree/master/nginx-flask-mysql)   | A sample Python/Flask application with an Nginx proxy and a MySQL database. |
| [NGINX / WSGI / Flask](https://github.com/docker/awesome-compose/tree/master/nginx-wsgi-flask)     | A sample Nginx reverse proxy with a Flask backend using WSGI.               |
| [Python / Flask / Redis](https://github.com/docker/awesome-compose/tree/master/flask-redis)        | A sample Python/Flask and a Redis database.                                 |
| [Flask](https://github.com/docker/awesome-compose/tree/master/flask)                               | A sample Flask application.                                                 |

----
url: https://docs.docker.com/reference/cli/docker/buildx/history/
----

# docker buildx history

***

| Description | Commands to work on build records |
| ----------- | --------------------------------- |
| Usage       | `docker buildx history`           |

## [Description](#description)

Commands to work on build records

## [Subcommands](#subcommands)

| Command                                                                                                 | Description                                     |
| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [`docker buildx history export`](https://docs.docker.com/reference/cli/docker/buildx/history/export/)   | Export build records into Docker Desktop bundle |
| [`docker buildx history import`](https://docs.docker.com/reference/cli/docker/buildx/history/import/)   | Import build records into Docker Desktop        |
| [`docker buildx history inspect`](https://docs.docker.com/reference/cli/docker/buildx/history/inspect/) | Inspect a build record                          |
| [`docker buildx history logs`](https://docs.docker.com/reference/cli/docker/buildx/history/logs/)       | Print the logs of a build record                |
| [`docker buildx history ls`](https://docs.docker.com/reference/cli/docker/buildx/history/ls/)           | List build records                              |
| [`docker buildx history open`](https://docs.docker.com/reference/cli/docker/buildx/history/open/)       | Open a build record in Docker Desktop           |
| [`docker buildx history rm`](https://docs.docker.com/reference/cli/docker/buildx/history/rm/)           | Remove build records                            |
| [`docker buildx history trace`](https://docs.docker.com/reference/cli/docker/buildx/history/trace/)     | Show the OpenTelemetry trace of a build record  |

----
url: https://docs.docker.com/reference/api/engine/sdk/examples/
----

# Examples using the Docker Engine SDKs and Docker API

***

Table of contents

***

After you [install Docker](https://docs.docker.com/get-started/get-docker/), you can [install the Go or Python SDK](https://docs.docker.com/reference/api/engine/sdk/#install-the-sdks) and also try out the Docker Engine API.

Each of these examples show how to perform a given Docker operation using the Go and Python SDKs and the HTTP API using `curl`.

## [Run a container](#run-a-container)

This first example shows how to run a container using the Docker API. On the command line, you would use the `docker run` command, but this is just as easy to do from your own apps too.

This is the equivalent of typing `docker run alpine echo hello world` at the command prompt:

```go
package main

import (
	"context"
	"io"
	"log"
	"os"

	"github.com/moby/moby/api/pkg/stdcopy"
	"github.com/moby/moby/api/types/container"
	"github.com/moby/moby/client"
)

func main() {
	ctx := context.Background()
	apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0"))
	if err != nil {
		log.Fatal(err)
	}
	defer apiClient.Close()

	reader, err := apiClient.ImagePull(ctx, "docker.io/library/alpine", client.ImagePullOptions{})
	if err != nil {
		log.Fatal(err)
	}

	defer reader.Close()
	// cli.ImagePull is asynchronous.
	// The reader needs to be read completely for the pull operation to complete.
	// If stdout is not required, consider using io.Discard instead of os.Stdout.
	io.Copy(os.Stdout, reader)

	resp, err := apiClient.ContainerCreate(ctx, client.ContainerCreateOptions{
		Config: &container.Config{
			Cmd: []string{"echo", "hello world"},
			Tty: false,
		},
		Image: "alpine",
	})
	if err != nil {
		log.Fatal(err)
	}

	if _, err := apiClient.ContainerStart(ctx, resp.ID, client.ContainerStartOptions{}); err != nil {
		log.Fatal(err)
	}

	wait := apiClient.ContainerWait(ctx, resp.ID, client.ContainerWaitOptions{})
	select {
	case err := <-wait.Error:
		if err != nil {
			log.Fatal(err)
		}
	case <-wait.Result:
	}

	out, err := apiClient.ContainerLogs(ctx, resp.ID, client.ContainerLogsOptions{ShowStdout: true})
	if err != nil {
		log.Fatal(err)
	}

	stdcopy.StdCopy(os.Stdout, os.Stderr, out)
}
```

```python
import docker
client = docker.from_env()
print(client.containers.run("alpine", ["echo", "hello", "world"]))
```

```console
$ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \
  -d '{"Image": "alpine", "Cmd": ["echo", "hello world"]}' \
  -X POST http://localhost/v1.54/containers/create
{"Id":"1c6594faf5","Warnings":null}

$ curl --unix-socket /var/run/docker.sock -X POST http://localhost/v1.54/containers/1c6594faf5/start

$ curl --unix-socket /var/run/docker.sock -X POST http://localhost/v1.54/containers/1c6594faf5/wait
{"StatusCode":0}

$ curl --unix-socket /var/run/docker.sock "http://localhost/v1.54/containers/1c6594faf5/logs?stdout=1"
hello world
```

When using cURL to connect over a Unix socket, the hostname isn't important. The previous examples use `localhost`, but any hostname would work.

> Important
>
> The previous examples assume you're using cURL 7.50.0 or above. Older versions of cURL used a [non-standard URL notation](https://github.com/moby/moby/issues/17960) when using a socket connection.
>
> If you're' using an older version of cURL, use `http:/<API version>/` instead, for example: `http:/v1.54/containers/1c6594faf5/start`.

## [Run a container in the background](#run-a-container-in-the-background)

You can also run containers in the background, the equivalent of typing `docker run -d bfirsh/reticulate-splines`:

```go
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"os"

	"github.com/moby/moby/client"
)

func main() {
	ctx := context.Background()
	apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0"))
	if err != nil {
		log.Fatal(err)
	}
	defer apiClient.Close()

	imageName := "bfirsh/reticulate-splines"

	out, err := apiClient.ImagePull(ctx, imageName, client.ImagePullOptions{})
	if err != nil {
		log.Fatal(err)
	}
	defer out.Close()

	io.Copy(os.Stdout, out)

	resp, err := apiClient.ContainerCreate(ctx, client.ContainerCreateOptions{
		Image: imageName,
	})
	if err != nil {
		log.Fatal(err)
	}

	if _, err := apiClient.ContainerStart(ctx, resp.ID, client.ContainerStartOptions{}); err != nil {
		log.Fatal(err)
	}

	fmt.Println(resp.ID)
}
```

```python
import docker
client = docker.from_env()
container = client.containers.run("bfirsh/reticulate-splines", detach=True)
print(container.id)
```

```console
$ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \
  -d '{"Image": "bfirsh/reticulate-splines"}' \
  -X POST http://localhost/v1.54/containers/create
{"Id":"1c6594faf5","Warnings":null}

$ curl --unix-socket /var/run/docker.sock -X POST http://localhost/v1.54/containers/1c6594faf5/start
```

## [List and manage containers](#list-and-manage-containers)

You can use the API to list containers that are running, just like using `docker ps`:

```go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/moby/moby/client"
)

func main() {
	ctx := context.Background()
	apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0"))
	if err != nil {
		log.Fatal(err)
	}
	defer apiClient.Close()

	containers, err := apiClient.ContainerList(ctx, client.ContainerListOptions{})
	if err != nil {
		log.Fatal(err)
	}

	for _, container := range containers.Items {
		fmt.Println(container.ID)
	}
}
```

```python
import docker
client = docker.from_env()
for container in client.containers.list():
  print(container.id)
```

```console
$ curl --unix-socket /var/run/docker.sock http://localhost/v1.54/containers/json
[{
  "Id":"ae63e8b89a26f01f6b4b2c9a7817c31a1b6196acf560f66586fbc8809ffcd772",
  "Names":["/tender_wing"],
  "Image":"bfirsh/reticulate-splines",
  ...
}]
```

## [Stop all running containers](#stop-all-running-containers)

Now that you know what containers exist, you can perform operations on them. This example stops all running containers.

> Note
>
> Don't run this on a production server. Also, if you're' using swarm services, the containers stop, but Docker creates new ones to keep the service running in its configured state.

```go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/moby/moby/client"
)

func main() {
	ctx := context.Background()
	apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0"))
	if err != nil {
		log.Fatal(err)
	}
	defer apiClient.Close()

	containers, err := apiClient.ContainerList(ctx, client.ContainerListOptions{})
	if err != nil {
		log.Fatal(err)
	}

	for _, container := range containers.Items {
		fmt.Print("Stopping container ", container.ID[:10], "... ")
		noWaitTimeout := 0 // to not wait for the container to exit gracefully
		if _, err := apiClient.ContainerStop(ctx, container.ID, client.ContainerStopOptions{Timeout: &noWaitTimeout}); err != nil {
			log.Fatal(err)
		}
		fmt.Println("Success")
	}
}
```

```python
import docker
client = docker.from_env()
for container in client.containers.list():
  container.stop()
```

```console
$ curl --unix-socket /var/run/docker.sock http://localhost/v1.54/containers/json
[{
  "Id":"ae63e8b89a26f01f6b4b2c9a7817c31a1b6196acf560f66586fbc8809ffcd772",
  "Names":["/tender_wing"],
  "Image":"bfirsh/reticulate-splines",
  ...
}]

$ curl --unix-socket /var/run/docker.sock \
  -X POST http://localhost/v1.54/containers/ae63e8b89a26/stop
```

## [Print the logs of a specific container](#print-the-logs-of-a-specific-container)

You can also perform actions on individual containers. This example prints the logs of a container given its ID. You need to modify the code before running it to change the hard-coded ID of the container to print the logs for.

```go
package main

import (
	"context"
	"io"
	"log"
	"os"

	"github.com/moby/moby/client"
)

func main() {
	ctx := context.Background()
	apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0"))
	if err != nil {
		log.Fatal(err)
	}
	defer apiClient.Close()

	options := client.ContainerLogsOptions{ShowStdout: true}
	// Replace this ID with a container that really exists
	out, err := apiClient.ContainerLogs(ctx, "f1064a8a4c82", options)
	if err != nil {
		log.Fatal(err)
	}

	io.Copy(os.Stdout, out)
}
```

```python
import docker
client = docker.from_env()
container = client.containers.get('f1064a8a4c82')
print(container.logs())
```

```console
$ curl --unix-socket /var/run/docker.sock "http://localhost/v1.54/containers/ca5f55cdb/logs?stdout=1"
Reticulating spline 1...
Reticulating spline 2...
Reticulating spline 3...
Reticulating spline 4...
Reticulating spline 5...
```

## [List all images](#list-all-images)

List the images on your Engine, similar to `docker image ls`:

```go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/moby/moby/client"
)

func main() {
	ctx := context.Background()
	apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0"))
	if err != nil {
		log.Fatal(err)
	}
	defer apiClient.Close()

	images, err := apiClient.ImageList(ctx, client.ImageListOptions{})
	if err != nil {
		log.Fatal(err)
	}

	for _, image := range images.Items {
		fmt.Println(image.ID)
	}
}
```

```python
import docker
client = docker.from_env()
for image in client.images.list():
  print(image.id)
```

```console
$ curl --unix-socket /var/run/docker.sock http://localhost/v1.54/images/json
[{
  "Id":"sha256:31d9a31e1dd803470c5a151b8919ef1988ac3efd44281ac59d43ad623f275dcd",
  "ParentId":"sha256:ee4603260daafe1a8c2f3b78fd760922918ab2441cbb2853ed5c439e59c52f96",
  ...
}]
```

## [Pull an image](#pull-an-image)

Pull an image, like `docker pull`:

```go
package main

import (
	"context"
	"io"
	"log"
	"os"

	"github.com/moby/moby/client"
)

func main() {
	ctx := context.Background()
	apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0"))
	if err != nil {
		log.Fatal(err)
	}
	defer apiClient.Close()

	out, err := apiClient.ImagePull(ctx, "alpine", client.ImagePullOptions{})
	if err != nil {
		log.Fatal(err)
	}
	defer out.Close()

	io.Copy(os.Stdout, out)
}
```

```python
import docker
client = docker.from_env()
image = client.images.pull("alpine")
print(image.id)
```

```console
$ curl --unix-socket /var/run/docker.sock \
  -X POST "http://localhost/v1.54/images/create?fromImage=alpine"
{"status":"Pulling from library/alpine","id":"3.1"}
{"status":"Pulling fs layer","progressDetail":{},"id":"8f13703509f7"}
{"status":"Downloading","progressDetail":{"current":32768,"total":2244027},"progress":"[\u003e                                                  ] 32.77 kB/2.244 MB","id":"8f13703509f7"}
...
```

## [Pull an image with authentication](#pull-an-image-with-authentication)

Pull an image, like `docker pull`, with authentication:

> Note
>
> Credentials are sent in the clear. Docker's official registries use HTTPS. Private registries should also be configured to use HTTPS.

```go
package main

import (
	"context"
	"io"
	"log"
	"os"

	"github.com/moby/moby/api/pkg/authconfig"
	"github.com/moby/moby/api/types/registry"
	"github.com/moby/moby/client"
)

func main() {
	ctx := context.Background()
	apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0"))
	if err != nil {
		log.Fatal(err)
	}
	defer apiClient.Close()

	authStr, err := authconfig.Encode(registry.AuthConfig{
		Username: "username",
		Password: "password",
	})
	if err != nil {
		log.Fatal(err)
	}

	out, err := apiClient.ImagePull(ctx, "alpine", client.ImagePullOptions{RegistryAuth: authStr})
	if err != nil {
		log.Fatal(err)
	}
	defer out.Close()

	io.Copy(os.Stdout, out)
}
```

The Python SDK retrieves authentication information from the [credentials store](/reference/cli/docker/login/#credential-stores) file and integrates with [credential helpers](https://github.com/docker/docker-credential-helpers). It's possible to override these credentials, but that's out of scope for this example guide. After using `docker login`, the Python SDK uses these credentials automatically.

```python
import docker
client = docker.from_env()
image = client.images.pull("alpine")
print(image.id)
```

This example leaves the credentials in your shell's history, so consider this a naive implementation. The credentials are passed as a Base-64-encoded JSON structure.

```console
$ JSON=$(echo '{"username": "string", "password": "string", "serveraddress": "string"}' | base64)

$ curl --unix-socket /var/run/docker.sock \
  -H "Content-Type: application/tar"
  -X POST "http://localhost/v1.54/images/create?fromImage=alpine"
  -H "X-Registry-Auth"
  -d "$JSON"
{"status":"Pulling from library/alpine","id":"3.1"}
{"status":"Pulling fs layer","progressDetail":{},"id":"8f13703509f7"}
{"status":"Downloading","progressDetail":{"current":32768,"total":2244027},"progress":"[\u003e                                                  ] 32.77 kB/2.244 MB","id":"8f13703509f7"}
...
```

## [Commit a container](#commit-a-container)

Commit a container to create an image from its contents:

```go
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/moby/moby/api/types/container"
	"github.com/moby/moby/client"
)

func main() {
	ctx := context.Background()
	apiClient, err := client.New(client.FromEnv, client.WithUserAgent("my-application/1.0.0"))
	if err != nil {
		log.Fatal(err)
	}
	defer apiClient.Close()

	createResp, err := apiClient.ContainerCreate(ctx, client.ContainerCreateOptions{
		Config: &container.Config{
			Cmd: []string{"touch", "/helloworld"},
		},
		Image: "alpine",
	})
	if err != nil {
		log.Fatal(err)
	}

	if _, err := apiClient.ContainerStart(ctx, createResp.ID, client.ContainerStartOptions{}); err != nil {
		log.Fatal(err)
	}

	wait := apiClient.ContainerWait(ctx, createResp.ID, client.ContainerWaitOptions{})
	select {
	case err := <-wait.Error:
		if err != nil {
			log.Fatal(err)
		}
	case <-wait.Result:
	}

	commitResp, err := apiClient.ContainerCommit(ctx, createResp.ID, client.ContainerCommitOptions{Reference: "helloworld"})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(commitResp.ID)
}
```

```python
import docker
client = docker.from_env()
container = client.containers.run("alpine", ["touch", "/helloworld"], detach=True)
container.wait()
image = container.commit("helloworld")
print(image.id)
```

```console
$ docker run -d alpine touch /helloworld
0888269a9d584f0fa8fc96b3c0d8d57969ceea3a64acf47cd34eebb4744dbc52
$ curl --unix-socket /var/run/docker.sock\
  -X POST "http://localhost/v1.54/commit?container=0888269a9d&repo=helloworld"
{"Id":"sha256:6c86a5cd4b87f2771648ce619e319f3e508394b5bfc2cdbd2d60f59d52acda6c"}
```

----
url: https://docs.docker.com/reference/cli/docker/scout/repo/list/
----

# docker scout repo list

***

| Description | List Docker Scout repositories |
| ----------- | ------------------------------ |
| Usage       | `docker scout repo list`       |

## [Description](#description)

The docker scout repo list command shows all repositories in an organization.

If ORG is not provided the default configured organization will be used.

## [Options](#options)

| Option            | Default | Description                                                          |
| ----------------- | ------- | -------------------------------------------------------------------- |
| `--filter`        |         | Regular expression to filter repositories by name                    |
| `--only-disabled` |         | Filter to disabled repositories only                                 |
| `--only-enabled`  |         | Filter to enabled repositories only                                  |
| `--only-registry` |         | Filter to a specific registry only: - hub.docker.com - ecr (AWS ECR) |
| `--org`           |         | Namespace of the Docker organization                                 |

----
url: https://docs.docker.com/reference/samples/mariadb/
----

# MariaDB samples

| Name                                                                                                                     | Description                                                                         |
| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| [Nextcloud / Redis / MariaDB](https://github.com/docker/awesome-compose/tree/master/nextcloud-redis-mariadb)             | A sample Nextcloud setup.                                                           |
| [Compose and WordPress](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/wordpress/) | This quick-start guide demonstrates how to use Compose to set up and run WordPress. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/reference/cli/sbx/logout/
----

# sbx logout

| Description | Stop all running sandboxes and sign out of Docker |
| ----------- | ------------------------------------------------- |
| Usage       | `sbx logout [flags]`                              |

## [Options](#options)

| Option      | Default | Description              |
| ----------- | ------- | ------------------------ |
| `-y, --yes` |         | Skip confirmation prompt |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/reference/cli/docker/image/tag/
----

# docker image tag

***

| Description                                                               | Create a tag TARGET\_IMAGE that refers to SOURCE\_IMAGE  |
| ------------------------------------------------------------------------- | -------------------------------------------------------- |
| Usage                                                                     | `docker image tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker tag`                                             |

## [Description](#description)

A Docker image reference consists of several components that describe where the image is stored and its identity. These components are:

```text
[HOST[:PORT]/]NAMESPACE/REPOSITORY[:TAG]
```

* `HOST`

  Specifies the registry location where the image resides. If omitted, Docker defaults to Docker Hub (`docker.io`).

* `PORT`

  An optional port number for the registry, if necessary (for example, `:5000`).

* `NAMESPACE/REPOSITORY`

  The namespace (optional) usually represents a user or organization. The repository is required and identifies the specific image. If the namespace is omitted, Docker defaults to `library`, the namespace reserved for Docker Official Images.

* `TAG`

  An optional identifier used to specify a particular version or variant of the image. If no tag is provided, Docker defaults to `latest`.

### [Example image references](#example-image-references)

`example.com:5000/team/my-app:2.0`

* Host: `example.com`
* Port: `5000`
* Namespace: `team`
* Repository: `my-app`
* Tag: `2.0`

`alpine`

* Host: `docker.io` (default)
* Namespace: `library` (default)
* Repository: `alpine`
* Tag: `latest` (default)

For more information on the structure and rules of image naming, refer to the [Distribution reference](https://pkg.go.dev/github.com/distribution/reference#pkg-overview) as the canonical definition of the format.

## [Examples](#examples)

### [Tag an image referenced by ID](#tag-an-image-referenced-by-id)

To tag a local image with ID `0e5574283393` as `fedora/httpd` with the tag `version1.0`:

```console
$ docker tag 0e5574283393 fedora/httpd:version1.0
```

### [Tag an image referenced by Name](#tag-an-image-referenced-by-name)

To tag a local image `httpd` as `fedora/httpd` with the tag `version1.0`:

```console
$ docker tag httpd fedora/httpd:version1.0
```

Note that since the tag name isn't specified, the alias is created for an existing local version `httpd:latest`.

### [Tag an image referenced by Name and Tag](#tag-an-image-referenced-by-name-and-tag)

To tag a local image with the name `httpd` and the tag `test` as `fedora/httpd` with the tag `version1.0.test`:

```console
$ docker tag httpd:test fedora/httpd:version1.0.test
```

### [Tag an image for a private registry](#tag-an-image-for-a-private-registry)

To push an image to a private registry and not the public Docker registry you must include the registry hostname and port (if needed).

```console
$ docker tag 0e5574283393 myregistryhost:5000/fedora/httpd:version1.0
```

----
url: https://docs.docker.com/build/ci/github-actions/push-multi-registries/
----

# Push to multiple registries with GitHub Actions

***

***

The following workflow will connect you to Docker Hub and GitHub Container Registry, and push the image to both registries:

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: |
            user/app:latest
            user/app:1.0.0
            ghcr.io/user/app:latest
            ghcr.io/user/app:1.0.0
```

----
url: https://docs.docker.com/docker-hub/repos/
----

# Repositories

***

***

A Docker Hub repository is a collection of container images, enabling you to store, manage, and share Docker images publicly or privately. Each repository serves as a dedicated space where you can store images associated with a particular application, microservice, or project. Content in repositories is organized by tags, which represent different versions of the same application, allowing users to pull the right version when needed.

In this section, learn how to:

* [Create](https://docs.docker.com/docker-hub/repos/create/) a repository.

* Manage a repository, including how to manage:

  * [Repository information](https://docs.docker.com/docker-hub/repos/manage/information/): Add descriptions, overviews, and categories to help users understand the purpose and usage of your repository. Clear repository information aids discoverability and usability.

  * [Access](https://docs.docker.com/docker-hub/repos/manage/access/): Control who can access your repositories with flexible options. Make repositories public or private, add collaborators, and, for organizations, manage roles and teams to maintain security and control.

  * [Images](https://docs.docker.com/docker-hub/repos/manage/hub-images/): Repositories support diverse content types, including OCI artifacts, and allow version control through tagging. Push new images and manage existing content across repositories for flexibility.

  * [Image security insights](https://docs.docker.com/docker-hub/repos/manage/vulnerability-scanning/): Utilize continuous Docker Scout analysis and static vulnerability scanning to detect, understand, and address security issues within container images.

  * [Webhooks](https://docs.docker.com/docker-hub/repos/manage/webhooks/): Automate responses to repository events like image pushes or updates by setting up webhooks, which can trigger notifications or actions in external systems, streamlining workflows.

  * [Automated builds](https://docs.docker.com/docker-hub/repos/manage/builds/): Integrate with GitHub or Bitbucket for automated builds. Every code change triggers an image rebuild, supporting continuous integration and delivery.

  * [Trusted content](https://docs.docker.com/docker-hub/repos/manage/trusted-content/): Contribute to Docker Official Images or manage repositories in the Verified Publisher and Sponsored Open Source programs, including tasks like setting logos, accessing analytics, and enabling vulnerability scanning.

* [Archive](https://docs.docker.com/docker-hub/repos/archive/) an outdated or unsupported repository.

* [Delete](https://docs.docker.com/docker-hub/repos/delete/) a repository.

----
url: https://docs.docker.com/reference/cli/docker/network/rm/
----

# docker network rm

***

| Description                                                               | Remove one or more networks              |
| ------------------------------------------------------------------------- | ---------------------------------------- |
| Usage                                                                     | `docker network rm NETWORK [NETWORK...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker network remove`                  |

## [Description](#description)

Removes one or more networks by name or identifier. To remove a network, you must first disconnect any containers connected to it.

## [Options](#options)

| Option        | Default | Description                                |
| ------------- | ------- | ------------------------------------------ |
| `-f, --force` |         | Do not error if the network does not exist |

## [Examples](#examples)

### [Remove a network](#remove-a-network)

To remove the network named 'my-network':

```console
$ docker network rm my-network
```

### [Remove multiple networks](#remove-multiple-networks)

To delete multiple networks in a single `docker network rm` command, provide multiple network names or ids. The following example deletes a network with id `3695c422697f` and a network named `my-network`:

```console
$ docker network rm 3695c422697f my-network
```

When you specify multiple networks, the command attempts to delete each in turn. If the deletion of one network fails, the command continues to the next on the list and tries to delete that. The command reports success or failure for each deletion.

----
url: https://docs.docker.com/reference/cli/sbx/kit/inspect/
----

# sbx kit inspect

| Description | Display details about a kit artifact |
| ----------- | ------------------------------------ |
| Usage       | `sbx kit inspect REFERENCE [flags]`  |

## [Description](#description)

Load and display details about a kit artifact.

The reference can be a local directory, ZIP file path, OCI registry reference, or git repository.

## [Options](#options)

| Option   | Default | Description           |
| -------- | ------- | --------------------- |
| `--json` |         | Output in JSON format |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/compose/how-tos/multiple-compose-files/
----

# Use multiple Compose files

***

***

This section contains information on the ways you can work with multiple Compose files.

Using multiple Compose files lets you customize a Compose application for different environments or workflows. This is useful for large applications that may use dozens of containers, with ownership distributed across multiple teams. For example, if your organization or team uses a monorepo, each team may have their own “local” Compose file to run a subset of the application. They then need to rely on other teams to provide a reference Compose file that defines the expected way to run their own subset. Complexity moves from the code in to the infrastructure and the configuration file.

The quickest way to work with multiple Compose files is to [merge](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/) Compose files using the `-f` flag in the command line to list out your desired Compose files. However, [merging rules](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/#merging-rules) means this can soon get quite complicated.

Docker Compose provides two other options to manage this complexity when working with multiple Compose files. Depending on your project's needs, you can:

* [Extend a Compose file](https://docs.docker.com/compose/how-tos/multiple-compose-files/extends/) by referring to another Compose file and selecting the bits you want to use in your own application, with the ability to override some attributes.
* [Include other Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/include/) directly in your Compose file.

----
url: https://docs.docker.com/offload/quickstart/
----

# Docker Offload quickstart

***

Table of contents

***

Subscription: Docker Offload

Requires: Docker Desktop 4.68 or later

[Docker Offload](https://docs.docker.com/offload/about/) lets you build and run containers in the cloud while using your local Docker Desktop tools and workflow. This means faster builds, access to powerful cloud resources, and a seamless development experience.

This quickstart covers the steps developers need to get started with Docker Offload.

> Note
>
> If you're an organization owner, to get started you must [contact sales](https://www.docker.com/pricing/contact-sales/) and subscribe your organization to use Docker Offload. After subscribing, see [Manage Docker products](https://docs.docker.com/admin/organization/manage/manage-products/) to learn how to manage access for the developers in your organization.

## [Prerequisites](#prerequisites)

* You must have [Docker Desktop](/desktop/) installed. Docker recommends using the latest version of Docker Desktop to access the newest features and improvements in Docker Offload.
* You must have a Docker Business subscription and a Docker Offload subscription.

## [Step 1: Verify access to Docker Offload](#step-1-verify-access-to-docker-offload)

To access Docker Offload, you must be part of an organization that has subscribed to Docker Offload. As a developer, you can verify this by checking if the Docker Offload toggle appears in the Docker Desktop Dashboard header.

1. Start Docker Desktop and sign in.
2. In the Docker Desktop Dashboard header, look for the Docker Offload toggle.

If you see the Docker Offload toggle, you have access to Docker Offload and can proceed to the next step. If you don't see the Docker Offload toggle, check if Docker Offload is disabled in your [Docker Desktop settings](https://docs.docker.com/offload/configuration/), and then contact your administrator to verify that your organization has subscribed to Docker Offload and that they have enabled access for your organization.

## [Step 2: Start Docker Offload](#step-2-start-docker-offload)

You can start Docker Offload from the CLI or in the header of the Docker Desktop Dashboard. The following steps describe how to start Docker Offload using the CLI.

1. Start Docker Desktop and sign in.

2. Open a terminal and run the following command to start Docker Offload:

   ```console
   $ docker offload start
   ```

   > Tip
   >
   > To learn more about the Docker Offload CLI commands, see the [Docker Offload CLI reference](/reference/cli/docker/offload/).

3. If you are a member of multiple organizations that have access to Docker Offload, you have the option to select a profile. Your usage will be associated with the organization of the selected profile.

When Docker Offload is started, you'll see a cloud icon ( ) in the Docker Desktop Dashboard header, and the Docker Desktop Dashboard appears purple. You can run `docker offload status` in a terminal to check the status of Docker Offload.

## [Step 3: Run a container with Docker Offload](#step-3-run-a-container-with-docker-offload)

After starting Docker Offload, Docker Desktop connects to a secure cloud environment that mirrors your local experience. When you run builds or containers, they execute remotely, but behave just like local ones.

To verify that Docker Offload is working, run a container:

```console
$ docker run --rm hello-world
```

If Docker Offload is working, you'll see `Hello from Docker!` in the terminal output.

## [Step 4: Monitor your Offload session](#step-4-monitor-your-offload-session)

When Docker Offload is started and you have started session (for example, you've ran a container), then you can see current session duration estimate in the Docker Desktop Dashboard footer next to the hourglass icon ( ).

Also, when Docker Offload is started, you can view detailed session information by selecting **Docker Offload** > **Insights** in the left navigation of the Docker Desktop Dashboard.

## [Step 5: Stop Docker Offload](#step-5-stop-docker-offload)

Docker Offload automatically [idles](https://docs.docker.com/offload/about/#session-management-and-idle-state) if you do not respond to periodic prompts that appear in the Docker Desktop Dashboard. You can stop your Docker Offload session at any time. To stop Docker Offload:

```console
$ docker offload stop
```

When you stop Docker Offload, the cloud environment is terminated and all running containers and images are removed. When Docker Offload has been idle for 5 minutes, the environment is also terminated and all running containers and images are removed.

To start Docker Offload again, run the `docker offload start` command.

----
url: https://docs.docker.com/extensions/extensions-sdk/process/
----

# The build and publish process

***

Table of contents

***

This documentation is structured so that it matches the steps you need to take when creating your extension.

There are two main parts to creating a Docker extension:

1. Build the foundations
2. Publish the extension

> Note
>
> You do not need to pay to create a Docker extension. The [Docker Extension SDK](https://www.npmjs.com/package/@docker/extension-api-client) is licensed under the Apache 2.0 License and is free to use. Anyone can create new extensions and share them without constraints.
>
> There is also no constraint on how each extension should be licensed, this is up to you to decide when creating a new extension.

## [Part one: Build the foundations](#part-one-build-the-foundations)

The build process consists of:

* Installing the latest version of Docker Desktop.
* Setting up the directory with files, including the extension’s source code and the required extension-specific files.
* Creating the `Dockerfile` to build, publish, and run your extension in Docker Desktop.
* Configuring the metadata file which is required at the root of the image filesystem.
* Building and installing the extension.

For further inspiration, see the other examples in the [samples folder](https://github.com/docker/extensions-sdk/tree/main/samples).

> Tip
>
> Whilst creating your extension, make sure you follow the [design](https://docs.docker.com/extensions/extensions-sdk/design/design-guidelines/) and [UI styling](https://docs.docker.com/extensions/extensions-sdk/design/) guidelines to ensure visual consistency and [level AA accessibility standards](https://www.w3.org/WAI/WCAG2AA-Conformance).

## [Part two: Publish and distribute your extension](#part-two-publish-and-distribute-your-extension)

Docker Desktop displays published extensions in the Extensions Marketplace. The Extensions Marketplace is a curated space where developers can discover extensions to improve their developer experience and upload their own extension to share with the world.

If you want your extension published in the Marketplace, read the [publish documentation](https://docs.docker.com/extensions/extensions-sdk/extensions/publish/).

> Already built an extension?
>
> Let us know about your experience using the [feedback form](https://survey.alchemer.com/s3/7184948/Publishers-Feedback-Form).

## [What’s next?](#whats-next)

If you want to get up and running with creating a Docker Extension, see the [Quickstart guide](https://docs.docker.com/extensions/extensions-sdk/quickstart/).

Alternatively, get started with reading the "Part one: Build" section for more in-depth information about each step of the extension creation process.

For an in-depth tutorial of the entire build process, we recommend the following video walkthrough from DockerCon 2022.

----
url: https://docs.docker.com/enterprise/security/provisioning/scim/provision-scim/
----

# Set up SCIM provisioning

***

Table of contents

***

Subscription: Business

For: Administrators

## [Supported attributes](#supported-attributes)

SCIM uses attributes (name, email, etc.) to sync user information between your identity provider and Docker. Properly mapping these attributes in your identity provider ensures that user provisioning works smoothly and prevents issues like duplicate user accounts when using single sign-on.

Docker supports the following SCIM attributes:

| Attribute         | Description                                                                       |
| ----------------- | --------------------------------------------------------------------------------- |
| `userName`        | User's primary email address, used as the unique identifier                       |
| `name.givenName`  | User's first name                                                                 |
| `name.familyName` | User's surname                                                                    |
| `active`          | Indicates if a user is enabled or disabled, set to "false" to de-provision a user |

For additional details about supported attributes and SCIM, see [Docker Hub API SCIM reference](https://docs.docker.com/reference/api/hub/latest/#tag/scim).

> Important
>
> By default, Docker uses Just-in-Time (JIT) provisioning for SSO. If SCIM is enabled, JIT values still take precedence and will overwrite attribute values set by SCIM. To avoid conflicts, make sure your JIT attribute values match your SCIM values.
>
> Alternatively, you can disable JIT provisioning to rely solely on SCIM. For details, see [Just-in-Time](https://docs.docker.com/enterprise/security/provisioning/just-in-time/).

## [Enable SCIM in Docker](#enable-scim-in-docker)

To enable SCIM:

1. Sign in to [Docker Home](https://app.docker.com).
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the **SSO connections** table, select the **Actions** icon for your connection, then select **Setup SCIM**.
4. Copy the **SCIM Base URL** and **API Token** and paste the values into your IdP.

## [Enable SCIM in your IdP](#enable-scim-in-your-idp)

The user interface for your identity provider may differ slightly from the following steps. You can refer to the documentation for your identity provider to verify. For additional details, see the documentation for your identity provider:

* [Okta](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SCIM.htm)
* [Entra ID/Azure AD SAML 2.0](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/user-provisioning)

> Note
>
> Microsoft does not currently support SCIM and OIDC in the same non-gallery application in Entra ID. This page provides a verified workaround using a separate non-gallery app for SCIM provisioning. While Microsoft does not officially document this setup, it is widely used and supported in practice.

### [Step one: Enable SCIM](#step-one-enable-scim)

1. Sign in to Okta and select **Admin** to open the admin portal.

2. Open the application you created when you configured your SSO connection.

3. On the application page, select the **General** tab, then **Edit App Settings**.

4. Enable SCIM provisioning, then select **Save**.

5. Navigate to the **Provisioning**, then select **Edit SCIM Connection**.

6. To configure SCIM in Okta, set up your connection using the following values and settings:

   * SCIM Base URL: SCIM connector base URL (copied from Docker Home)
   * Unique identifier field for users: `email`
   * Supported provisioning actions: **Push New Users** and **Push Profile Updates**
   * Authentication Mode: HTTP Header
   * SCIM Bearer Token: HTTP Header Authorization Bearer Token (copied from Docker Home)

7. Select **Test Connector Configuration**.

8. Review the test results and select **Save**.

### [Step two: Enable synchronization](#step-two-enable-synchronization)

1. In Okta, select **Provisioning**.

2. Select **To App**, then **Edit**.

3. Enable **Create Users**, **Update User Attributes**, and **Deactivate Users**.

4. Select **Save**.

5. Remove unnecessary mappings. The necessary mappings are:

   * Username
   * Given name
   * Family name
   * Email

Next, [set up role mapping](#set-up-role-mapping).

Microsoft does not support SCIM and OIDC in the same non-gallery application. You must create a second non-gallery application in Entra ID for SCIM provisioning.

### [Step one: Create a separate SCIM app](#step-one-create-a-separate-scim-app)

1. In the Azure Portal, go to **Microsoft Entra ID** > **Enterprise Applications** > **New application**.
2. Select **Create your own application**.
3. Name your application and choose **Integrate any other application you don't find in the gallery**.
4. Select **Create**.

### [Step two: Configure SCIM provisioning](#step-two-configure-scim-provisioning)

1. In your new SCIM application, go to **Provisioning** > **Get started**.

2. Set **Provisioning Mode** to **Automatic**.

3. Under **Admin Credentials**:

   * **Tenant URL**: Paste the **SCIM Base URL** from Docker Home.
   * **Secret Token**: Paste the **SCIM API token** from Docker Home.

4. Select **Test Connection** to verify.

5. Select **Save** to store credentials.

Next, [set up role mapping](#set-up-role-mapping).

1. In the Azure Portal, go to **Microsoft Entra ID** > **Enterprise Applications**, and select your Docker SAML app.

2. Select **Provisioning** > **Get started**.

3. Set **Provisioning Mode** to **Automatic**.

4. Under **Admin Credentials**:

   * **Tenant URL**: Paste the **SCIM Base URL** from Docker Home.
   * **Secret Token**: Paste the **SCIM API token** from Docker Home.

5. Select **Test Connection** to verify.

6. Select **Save** to store credentials.

Next, [set up role mapping](#set-up-role-mapping).

## [Set up role mapping](#set-up-role-mapping)

You can assign [Docker roles](https://docs.docker.com/enterprise/security/roles-and-permissions/) to users by adding optional SCIM attributes in your IdP. These attributes override default role and team values set in your SSO configuration.

> Note
>
> Role mappings are supported for both SCIM and Just-in-Time (JIT) provisioning. For JIT, role mapping applies only when the user is first provisioned.

The following table lists the supported optional user-level attributes:

| Attribute    | Possible values                          | Notes                                                                                                                                                                                                                                                                                                               |
| ------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dockerRole` | `member`, `editor`, or `owner`           | If not set, the user defaults to the `member` role. Setting this attribute overrides the default. For role definitions, see [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/).                                                                                            |
| `dockerOrg`  | Docker `organizationName` (e.g., `moby`) | Overrides the default organization configured in your SSO connection. If unset, the user is provisioned to the default organization. If `dockerOrg` and `dockerTeam` are both set, the user is provisioned to the team within the specified organization.                                                           |
| `dockerTeam` | Docker `teamName` (e.g., `developers`)   | Provisions the user to the specified team in the default or specified organization. If the team doesn't exist, it is automatically created. You can still use [group mapping](https://docs.docker.com/enterprise/security/provisioning/scim/group-mapping/) to assign users to multiple teams across organizations. |

The external namespace used for these attributes is: `urn:ietf:params:scim:schemas:extension:docker:2.0:User`. This value is required in your identity provider when creating custom SCIM attributes for Docker.

### [Step one: Set up role mapping in Okta](#step-one-set-up-role-mapping-in-okta)

1. Setup [SSO](https://docs.docker.com/enterprise/security/single-sign-on/connect/) and SCIM first.

2. In the Okta admin portal, go to **Directory**, select **Profile Editor**, and then **User (Default)**.

3. Select **Add Attribute** and configure the values for the role, organization, or team you want to add. Exact naming isn't required.

4. Return to the **Profile Editor** and select your application.

5. Select **Add Attribute** and enter the required values. The **External Name** and **External Namespace** must be exact.

   * The external name values for organization/team/role mapping are `dockerOrg`, `dockerTeam`, and `dockerRole` respectively, as listed in the previous table.
   * The external namespace is the same for all of them: `urn:ietf:params:scim:schemas:extension:docker:2.0:User`.

6. After creating the attributes, navigate to the top of the page and select **Mappings**, then **Okta User to YOUR APP**.

7. Go to the newly created attributes and map the variable names to the external names, then select **Save Mappings**. If you're using JIT provisioning, continue to the following steps.

8. Navigate to **Applications** and select **YOUR APP**.

9. Select **General**, then **SAML Settings**, and **Edit**.

10. Select **Step 2** and configure the mapping from the user attribute to the Docker variables.

### [Step two: Assign roles by user](#step-two-assign-roles-by-user)

1. In the Okta Admin portal, select **Directory**, then **People**.
2. Select **Profile**, then **Edit**.
3. Select **Attributes** and update the attributes to the desired values.

### [Step three: Assign roles by group](#step-three-assign-roles-by-group)

1. In the Okta Admin portal, select **Directory**, then **People**.
2. Select **YOUR GROUP**, then **Applications**.
3. Open **YOUR APPLICATION** and select the **Edit** icon.
4. Update the attributes to the desired values.

If a user doesn't already have attributes set up, users who are added to the group will inherit these attributes upon provisioning.

### [Step one: Configure attribute mappings](#step-one-configure-attribute-mappings)

1. Complete the [SCIM provisioning setup](https://docs.docker.com/enterprise/security/provisioning/scim/provision-scim/#enable-scim-in-docker).

2. In the Azure Portal, open **Microsoft Entra ID** > **Enterprise Applications**, and select your SCIM application.

3. Go to **Provisioning** > **Mappings** > **Provision Azure Active Directory Users**.

4. Add or update the following mappings:

   * `userPrincipalName` -> `userName`
   * `mail` -> `emails.value`
   * Optional. Map `dockerRole`, `dockerOrg`, or `dockerTeam` using one of the [mapping methods](https://docs.docker.com/enterprise/security/provisioning/scim/provision-scim/#set-up-role-mapping).

5. Remove any unsupported attributes to prevent sync errors.

6. Optional. Go to **Mappings** > **Provision Azure Active Directory Groups**:

   * If group provisioning causes errors, set **Enabled** to **No**.
   * If enabling, test group mappings carefully.

7. Select **Save** to apply mappings.

### [Step two: Choose a role mapping method](#step-two-choose-a-role-mapping-method)

You can map `dockerRole`, `dockerOrg`, or `dockerTeam` using one of the following methods:

#### [Expression mapping](#expression-mapping)

Use this method if you only need to assign Docker roles like `member`, `editor`, or `owner`.

1. In the **Edit Attribute** view, set the mapping type to **Expression**.

2. In the **Expression** field:

   1. If your App Roles match Docker roles exactly, use: SingleAppRoleAssignment(\[appRoleAssignments])
   2. If they don't match, use a switch expression: `Switch(SingleAppRoleAssignment([appRoleAssignments]), "My Corp Admins", "owner", "My Corp Editors", "editor", "My Corp Users", "member")`

3. Set:

   * **Target attribute**: `urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerRole`
   * **Match objects using this attribute**: No
   * **Apply this mapping**: Always

4. Save your changes.

> Warning
>
> You can't use `dockerOrg` or `dockerTeam` with this method. Expression mapping is only compatible with one attribute.

#### [Direct mapping](#direct-mapping)

Use this method if you need to map multiple attributes (`dockerRole` + `dockerTeam`).

1. For each Docker attribute, choose a unique Entra extension attribute (`extensionAttribute1`, `extensionAttribute2`, etc.).

2. In the **Edit Attribute** view:

   * Set mapping type to **Direct**.

   * Set **Source attribute** to your selected extension attribute.

   * Set **Target attribute** to one of:

     * `dockerRole: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerRole`
     * `dockerOrg: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerOrg`
     * `dockerTeam: urn:ietf:params:scim:schemas:extension:docker:2.0:User:dockerTeam`

   * Set **Apply this mapping** to **Always**.

3. Save your changes.

To assign values, you'll need to use the Microsoft Graph API.

### [Step three: Assign users and groups](#step-three-assign-users-and-groups)

For either mapping method:

1. In the SCIM app, go to **Users and Groups** > **Add user/group**.
2. Select the users or groups to provision to Docker.
3. Select **Assign**.

If you're using expression mapping:

1. Go to **App registrations** > your SCIM app > **App Roles**.
2. Create App Roles that match Docker roles.
3. Assign users or groups to App Roles under **Users and Groups**.

If you're using direct mapping:

1. Go to [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer) and sign in as a tenant admin.
2. Use Microsoft Graph API to assign attribute values. Example PATCH request:

```bash
PATCH https://graph.microsoft.com/v1.0/users/{user-id}
Content-Type: application/json

{
  "extensionAttribute1": "owner",
  "extensionAttribute2": "moby",
  "extensionAttribute3": "developers"
}
```

> Note
>
> You must use a different extension attribute for each SCIM field.

See the documentation for your IdP for additional details:

* [Okta](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-add-custom-user-attributes.htm)
* [Entra ID/Azure AD](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes#provisioning-a-custom-extension-attribute-to-a-scim-compliant-application)

## [Test SCIM provisioning](#test-scim-provisioning)

After completing role mapping, you can test the configuration manually.

1. In the Okta admin portal, go to **Directory > People**.
2. Select a user you've assigned to your SCIM application.
3. Select **Provision User**.
4. Wait a few seconds, then check the Docker [Admin Console](https://app.docker.com/admin) under **Members**.
5. If the user doesn't appear, review logs in **Reports > System Log** and confirm SCIM settings in the app.

1) In the Azure Portal, go to **Microsoft Entra ID** > **Enterprise Applications**, and select your SCIM app.
2) Go to **Provisioning** > **Provision on demand**.
3) Select a user or group and choose **Provision**.
4) Confirm that the user appears in the Docker [Admin Console](https://app.docker.com/admin) under **Members**.
5) If needed, check **Provisioning logs** for errors.

## [Disable SCIM](#disable-scim)

If SCIM is disabled, any user provisioned through SCIM will remain in the organization. Future changes for your users will not sync from your IdP. User de-provisioning is only possible when manually removing the user from the organization.

To disable SCIM:

1. Sign in to [Docker Home](https://app.docker.com).
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the **SSO connections** table, select the **Actions** icon.
4. Select **Disable SCIM**.

## [Next steps](#next-steps)

* Set up [Group mapping](https://docs.docker.com/enterprise/security/provisioning/scim/group-mapping/).
* [Troubleshoot provisioning](https://docs.docker.com/enterprise/security/provisioning/troubleshoot-provisioning/).

----
url: https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/
----

# Troubleshoot Docker Desktop

***

Table of contents

***

This page contains information on how to diagnose and troubleshoot Docker Desktop, and how to check the logs.

## [Troubleshoot menu](#troubleshoot-menu)

To navigate to **Troubleshoot** either:

* Select the Docker menu Docker menu and then **Troubleshoot**.
* Select the **Troubleshoot** icon near the top-right corner of Docker Dashboard.

The **Troubleshooting** menu contains the following options:

* **Restart Docker Desktop**.

* **Reset Kubernetes cluster**. Select to delete all stacks and Kubernetes resources. For more information, see [Kubernetes](https://docs.docker.com/desktop/settings-and-maintenance/settings/#kubernetes).

* **Clean / Purge data**. This option resets all Docker data without a reset to factory defaults. Selecting this option results in the loss of existing settings.

* **Reset to factory defaults**: Choose this option to reset all options on Docker Desktop to their initial state, the same as when Docker Desktop was first installed.

If you are a Mac or Linux user, you also have the option to **Uninstall** Docker Desktop from your system.

## [Diagnose](#diagnose)

> Tip
>
> If you do not find a solution in troubleshooting, browse the GitHub repositories or create a new issue on the [Docker Desktop issue tracker](https://github.com/docker/desktop-feedback).

### [Diagnose from the app](#diagnose-from-the-app)

1. From **Troubleshoot**, select **Get support**. This opens the in-app Support page and starts collecting the diagnostics.

   > Note
   >
   > Gathering diagnostics may take several minutes. Don't close Docker Desktop while the diagnostics are being collected.

2. When the diagnostics collection process is complete, select **Upload to get a Diagnostic ID**.

3. When the diagnostics are uploaded, Docker Desktop prints a diagnostic ID. Copy this ID.

4. Use your diagnostics ID to get help:

   * If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support.

     > Note
     >
     > You must be signed in to Docker Desktop to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](https://docs.docker.com/support/).

   * If you don't have a paid Docker subscription, select **Report a Bug** to open a new Docker Desktop issue on GitHub. Complete the information required and ensure you add the diagnostic ID you copied in step three.

### [Diagnose from an error message](#diagnose-from-an-error-message)

1. When an error message appears, select **Gather diagnostics**.

   > Note
   >
   > Gathering diagnostics may take several minutes. Don't close Docker Desktop while the diagnostics are being collected.

2. When the diagnostics are uploaded, Docker Desktop prints a diagnostic ID. Copy this ID.

3. Use your diagnostics ID to get help:

   * If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support.

     > Note
     >
     > You must be signed in to Docker Desktop to access the support form. For information on what's covered as part of Docker Desktop support, see [Support](https://docs.docker.com/support/).

   * If you don't have a paid Docker subscription, you can open a new [Docker Desktop issue on GitHub](https://github.com/docker/desktop-feedback). Complete the information required and ensure you add the diagnostic ID printed in step two.

### [Diagnose from the terminal](#diagnose-from-the-terminal)

In some cases, it's useful to run the diagnostics yourself, for instance, if Docker Desktop cannot start.

> Note
>
> Gathering diagnostics may take several minutes. Wait for the process to complete before closing the terminal.

1. Locate the `com.docker.diagnose` tool:

   ```console
   # For all-user installations
   $ C:\Program Files\Docker\Docker\resources\com.docker.diagnose.exe

   # For per-user installations
   $ %LOCALAPPDATA%\Programs\DockerDesktop\resources\com.docker.diagnose.exe
   ```

2. Create and upload the diagnostics ID. In PowerShell, run:

   ```console
   # For all-user installations
   $ & "C:\Program Files\Docker\Docker\resources\com.docker.diagnose.exe" gather -upload

   # For per-user installations
   $ & %LOCALAPPDATA%\Programs\DockerDesktop\resources\com.docker.diagnose.exe" gather -upload
   ```

After the diagnostics have finished, the terminal displays your diagnostics ID and the path to the diagnostics file. The diagnostics ID is composed of your user ID and a timestamp. For example `BE9AFAAF-F68B-41D0-9D12-84760E6B8740/20190905152051`.

1. Locate the `com.docker.diagnose` tool:

   ```console
   $ /Applications/Docker.app/Contents/MacOS/com.docker.diagnose
   ```

2. Create and upload the diagnostics ID. Run:

   ```console
   $ /Applications/Docker.app/Contents/MacOS/com.docker.diagnose gather -upload
   ```

After the diagnostics have finished, the terminal displays your diagnostics ID and the path to the diagnostics file. The diagnostics ID is composed of your user ID and a timestamp. For example `BE9AFAAF-F68B-41D0-9D12-84760E6B8740/20190905152051`.

1. Locate the `com.docker.diagnose` tool:

   ```console
   $ /opt/docker-desktop/bin/com.docker.diagnose
   ```

2. Create and upload the diagnostics ID. Run:

   ```console
   $ /opt/docker-desktop/bin/com.docker.diagnose gather -upload
   ```

After the diagnostics have finished, the terminal displays your diagnostics ID and the path to the diagnostics file. The diagnostics ID is composed of your user ID and a timestamp. For example `BE9AFAAF-F68B-41D0-9D12-84760E6B8740/20190905152051`.

> Tip
>
> You can also use the [`docker desktop diagnose` command](https://docs.docker.com/desktop/features/desktop-cli/) to diagnose Docker Desktop and upload the diagnostics ID.

To view the contents of the diagnostic file:

1. Unzip the file. In PowerShell, copy and paste the path to the diagnostics file into the following command and then run it. It should be similar to the following example:

   ```powershell
   $ Expand-Archive -LiteralPath "C:\Users\testUser\AppData\Local\Temp\5DE9978A-3848-429E-8776-950FC869186F\20230607101602.zip" -DestinationPath "C:\Users\testuser\AppData\Local\Temp\5DE9978A-3848-429E-8776-950FC869186F\20230607101602"
   ```

2. Open the file in your preferred text editor. Run:

   ```powershell
   $ code <path-to-file>
   ```

Run:

```console
$ open /tmp/<your-diagnostics-ID>.zip
```

Run:

```console
$ unzip –l /tmp/<your-diagnostics-ID>.zip
```

#### [Use your diagnostics ID to get help](#use-your-diagnostics-id-to-get-help)

If you have a paid Docker subscription, select **Contact support**. This opens the Docker Desktop support form. Fill in the information required and add the ID you copied in step three to the **Diagnostics ID field**. Then, select **Submit ticket** to request Docker Desktop support.

If you don't have a paid Docker subscription, create an issue on [GitHub](https://github.com/docker/desktop-feedback).

### [Self-diagnose tool](#self-diagnose-tool)

> Important
>
> This tool has been deprecated.

## [Check the logs](#check-the-logs)

In addition to using the diagnose option to submit logs, you can browse the logs yourself.

In PowerShell, run:

```powershell
$ code $Env:LOCALAPPDATA\Docker\log
```

This opens up all the logs in your preferred text editor for you to explore.

### [From terminal](#from-terminal)

To watch the live flow of Docker Desktop logs in the command line, run the following script from your preferred shell.

```console
$ pred='process matches ".*(ocker|vpnkit).*" || (process in {"taskgated-helper", "launchservicesd", "kernel"} && eventMessage contains[c] "docker")'
$ /usr/bin/log stream --style syslog --level=debug --color=always --predicate "$pred"
```

Alternatively, to collect the last day of logs (`1d`) in a file, run:

```console
$ /usr/bin/log show --debug --info --style syslog --last 1d --predicate "$pred" >/tmp/logs.txt
```

### [From the Console app](#from-the-console-app)

Mac provides a built-in log viewer, named **Console**, which you can use to check Docker logs.

The Console lives in `/Applications/Utilities`. You can search for it with Spotlight Search.

To read the Docker app log messages, type `docker` in the Console window search bar and press Enter. Then select `ANY` to expand the drop-down list next to your `docker` search entry, and select `Process`.

You can use the Console Log Query to search logs, filter the results in various ways, and create reports.

You can access Docker Desktop logs by running the following command:

```console
$ journalctl --user --unit=docker-desktop
```

You can also find the logs for the internal components included in Docker Desktop at `$HOME/.docker/desktop/log/`.

## [View the Docker daemon logs](#view-the-docker-daemon-logs)

Refer to the [Read the daemon logs](https://docs.docker.com/engine/daemon/logs/) section to learn how to view the Docker Daemon logs.

## [Further resources](#further-resources)

* View specific [troubleshoot topics](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/).
* View information on [known issues](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/known-issues/)
* [Fix "Docker.app is damaged" on macOS](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog/) - Resolve macOS installation issues
* [Get support for Docker products](https://docs.docker.com/support/)

----
url: https://docs.docker.com/engine/swarm/swarm-tutorial/inspect-service/
----

# Inspect a service on the swarm

***

***

When you have [deployed a service](https://docs.docker.com/engine/swarm/swarm-tutorial/deploy-service/) to your swarm, you can use the Docker CLI to see details about the service running in the swarm.

1. If you haven't already, open a terminal and ssh into the machine where you run your manager node. For example, the tutorial uses a machine named `manager1`.

2. Run `docker service inspect --pretty <SERVICE-ID>` to display the details about a service in an easily readable format.

   To see the details on the `helloworld` service:

   ```console
   [manager1]$ docker service inspect --pretty helloworld

   ID:		9uk4639qpg7npwf3fn2aasksr
   Name:		helloworld
   Service Mode:	REPLICATED
    Replicas:		1
   Placement:
   UpdateConfig:
    Parallelism:	1
   ContainerSpec:
    Image:		alpine
    Args:	ping docker.com
   Resources:
   Endpoint Mode:  vip
   ```

   > Tip
   >
   > To return the service details in json format, run the same command without the `--pretty` flag.

   ```console
   [manager1]$ docker service inspect helloworld
   [
   {
       "ID": "9uk4639qpg7npwf3fn2aasksr",
       "Version": {
           "Index": 418
       },
       "CreatedAt": "2016-06-16T21:57:11.622222327Z",
       "UpdatedAt": "2016-06-16T21:57:11.622222327Z",
       "Spec": {
           "Name": "helloworld",
           "TaskTemplate": {
               "ContainerSpec": {
                   "Image": "alpine",
                   "Args": [
                       "ping",
                       "docker.com"
                   ]
               },
               "Resources": {
                   "Limits": {},
                   "Reservations": {}
               },
               "RestartPolicy": {
                   "Condition": "any",
                   "MaxAttempts": 0
               },
               "Placement": {}
           },
           "Mode": {
               "Replicated": {
                   "Replicas": 1
               }
           },
           "UpdateConfig": {
               "Parallelism": 1
           },
           "EndpointSpec": {
               "Mode": "vip"
           }
       },
       "Endpoint": {
           "Spec": {}
       }
   }
   ]
   ```

3. Run `docker service ps <SERVICE-ID>` to see which nodes are running the service:

   ```console
   [manager1]$ docker service ps helloworld

   NAME                                    IMAGE   NODE     DESIRED STATE  CURRENT STATE           ERROR               PORTS
   helloworld.1.8p1vev3fq5zm0mi8g0as41w35  alpine  worker2  Running        Running 3 minutes
   ```

   In this case, the one instance of the `helloworld` service is running on the `worker2` node. You may see the service running on your manager node. By default, manager nodes in a swarm can execute tasks just like worker nodes.

   Swarm also shows you the `DESIRED STATE` and `CURRENT STATE` of the service task so you can see if tasks are running according to the service definition.

4. Run `docker ps` on the node where the task is running to see details about the container for the task.

   > Tip
   >
   > If `helloworld` is running on a node other than your manager node, you must ssh to that node.

   ```console
   [worker2]$ docker ps

   CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
   e609dde94e47        alpine:latest       "ping docker.com"   3 minutes ago       Up 3 minutes                            helloworld.1.8p1vev3fq5zm0mi8g0as41w35
   ```

## [Next steps](#next-steps)

Next, you'll change the scale for the service running in the swarm.

[Change the scale](https://docs.docker.com/engine/swarm/swarm-tutorial/scale-service/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/inspect/
----

# docker buildx inspect

***

| Description | Inspect current builder instance |
| ----------- | -------------------------------- |
| Usage       | `docker buildx inspect [NAME]`   |

## [Description](#description)

Shows information about the current or specified builder.

## [Options](#options)

| Option                      | Default | Description                                             |
| --------------------------- | ------- | ------------------------------------------------------- |
| [`--bootstrap`](#bootstrap) |         | Ensure builder has booted before inspecting             |
| `--timeout`                 | `20s`   | Override the default timeout for loading builder status |

## [Examples](#examples)

### [Ensure that the builder is running before inspecting (--bootstrap)](#bootstrap)

Use the `--bootstrap` option to ensure that the builder is running before inspecting it. If the driver is `docker-container`, then `--bootstrap` starts the BuildKit container and waits until it's operational. Bootstrapping is automatically done during build, and therefore not necessary. The same BuildKit container is used during the lifetime of the associated builder node (as displayed in `buildx ls`).

### [Override the configured builder instance (--builder)](#builder)

Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

### [Get information about a builder instance](#get-information-about-a-builder-instance)

By default, `inspect` shows information about the current builder. Specify the name of the builder to inspect to get information about that builder. The following example shows information about a builder instance named `elated_tesla`:

> Note
>
> The asterisk (`*`) next to node build platform(s) indicate they have been manually set during `buildx create`. Otherwise the platforms were automatically detected.

```console
$ docker buildx inspect elated_tesla
Name:          elated_tesla
Driver:        docker-container
Last Activity: 2022-11-30 12:42:47 +0100 CET

Nodes:
Name:           elated_tesla0
Endpoint:       unix:///var/run/docker.sock
Driver Options: env.BUILDKIT_STEP_LOG_MAX_SPEED="10485760" env.JAEGER_TRACE="localhost:6831" image="moby/buildkit:latest" network="host" env.BUILDKIT_STEP_LOG_MAX_SIZE="10485760"
Status:         running
Flags:          --debug --allow-insecure-entitlement security.insecure --allow-insecure-entitlement network.host
BuildKit:       v0.10.6
Platforms:      linux/arm64*, linux/arm/v7, linux/arm/v6
Labels:
 org.mobyproject.buildkit.worker.executor:         oci
 org.mobyproject.buildkit.worker.hostname:         docker-desktop
 org.mobyproject.buildkit.worker.network:          host
 org.mobyproject.buildkit.worker.oci.process-mode: sandbox
 org.mobyproject.buildkit.worker.selinux.enabled:  false
 org.mobyproject.buildkit.worker.snapshotter:      overlayfs
GC Policy rule#0:
 All:           false
 Filters:       type==source.local,type==exec.cachemount,type==source.git.checkout
 Keep Duration: 48h0m0s
 Keep Bytes:    488.3MiB
GC Policy rule#1:
 All:           false
 Keep Duration: 1440h0m0s
 Keep Bytes:    24.21GiB
GC Policy rule#2:
 All:        false
 Keep Bytes: 24.21GiB
GC Policy rule#3:
 All:        true
 Keep Bytes: 24.21GiB
```

`debug` flag can also be used to get more information about the builder:

```console
$ docker --debug buildx inspect elated_tesla
```

----
url: https://docs.docker.com/reference/cli/docker/dhi/auth/deb/
----

# docker dhi auth deb

***

| Description | Create authentication details for DHI DEB repositories |
| ----------- | ------------------------------------------------------ |
| Usage       | `docker dhi auth deb`                                  |

## [Description](#description)

Create authentication details for DHI DEB repositories

----
url: https://docs.docker.com/guides/github-sonarqube-sandbox/
----

# How to build an AI-powered code quality workflow with SonarQube and E2B

Table of contents

***

Build AI-powered code quality workflows using E2B sandboxes with Docker's MCP catalog to automate GitHub and SonarQube integration.

**Time to complete** 40 minutes

This guide demonstrates how to build an AI-powered code quality workflow using [E2B sandboxes](https://e2b.dev/docs) with Docker’s MCP catalog. You’ll create a system that automatically analyzes code quality issues in GitHub repositories using SonarQube, then generate pull requests with fixes.

## [What you'll build](#what-youll-build)

You’ll build a Node.js script that spins up an E2B sandbox, connects GitHub and SonarQube MCP servers, and uses Claude Code to analyze code quality and propose improvements. The MCP servers are containerized and run as part of the E2B sandbox.

## [What you'll learn](#what-youll-learn)

In this guide, you'll learn:

* How to create E2B sandboxes with multiple MCP servers
* How to configure GitHub and SonarQube MCP servers for AI workflows
* How to use Claude Code inside sandboxes to interact with external tools
* How to build automated code review workflows that create quality-gated pull requests

## [Why use E2B sandboxes?](#why-use-e2b-sandboxes)

Running this workflow in E2B sandboes provides several advantages over local execution:

* Security: AI-generated code runs in isolated containers, protecting your local environment and credentials
* Zero setup: No need to install SonarQube, GitHub CLI, or manage dependencies locally
* Scalability: Resource-intensive operations like code scanning run in the cloud without consuming local resources

## [Learn more](#learn-more)

Read Docker's blog post: [Docker + E2B: Building the Future of Trusted AI](https://www.docker.com/blog/docker-e2b-building-the-future-of-trusted-ai/).

## [Modules](#modules)

1. [Build workflow](https://docs.docker.com/guides/github-sonarqube-sandbox/workflow/)

   Create E2B sandboxes, discover MCP tools, test individual operations, and build complete quality-gated PR workflows.

2. [Customize workflow](https://docs.docker.com/guides/github-sonarqube-sandbox/customize/)

   Learn how to customize prompts for specific quality issues, filter by file patterns, set quality thresholds, and integrate your workflow with GitHub Actions for automated code quality checks.

3. [Troubleshoot](https://docs.docker.com/guides/github-sonarqube-sandbox/troubleshoot/)

   Solutions for MCP tools not loading, authentication errors, permission issues, workflow timeouts, and other common problems when building code quality workflows with E2B.

----
url: https://docs.docker.com/compose/install/uninstall/
----

# Uninstall Docker Compose

***

Table of contents

***

How you uninstall Docker Compose depends on how it was installed. This guide covers uninstallation instructions for:

* Docker Compose installed via Docker Desktop
* Docker Compose installed as a CLI plugin

## [Uninstalling Docker Compose with Docker Desktop](#uninstalling-docker-compose-with-docker-desktop)

If you want to uninstall Docker Compose and you have installed Docker Desktop, see [Uninstall Docker Desktop](https://docs.docker.com/desktop/uninstall/).

> Warning
>
> Unless you have other Docker instances installed on that specific environment, uninstalling Docker Desktop removes all Docker components, including Docker Engine, Docker CLI, and Docker Compose.

## [Uninstalling the Docker Compose CLI plugin](#uninstalling-the-docker-compose-cli-plugin)

If you installed Docker Compose via a package manager, run:

On Ubuntu or Debian:

```console
$ sudo apt-get remove docker-compose-plugin
```

On RPM-based distributions:

```console
$ sudo yum remove docker-compose-plugin
```

### [Manually installed](#manually-installed)

If you installed Docker Compose manually (using curl), remove it by deleting the binary:

```console
$ rm $DOCKER_CONFIG/cli-plugins/docker-compose
```

### [Remove for all users](#remove-for-all-users)

If installed for all users, remove it from the system directory:

```console
$ rm /usr/local/lib/docker/cli-plugins/docker-compose
```

> Note
>
> If you get a **Permission denied** error using either of the previous methods, you do not have the permissions needed to remove Docker Compose. To force the removal, prepend `sudo` to either of the previous instructions and run it again.

### [Inspect the location of the Compose CLI plugin](#inspect-the-location-of-the-compose-cli-plugin)

To check where Compose is installed, use:

```console
$ docker info --format '{{range .ClientInfo.Plugins}}{{if eq .Name "compose"}}{{.Path}}{{end}}{{end}}'
```

----
url: https://docs.docker.com/reference/cli/docker/stack/rm/
----

# docker stack rm

***

| Description                                                               | Remove one or more stacks                    |
| ------------------------------------------------------------------------- | -------------------------------------------- |
| Usage                                                                     | `docker stack rm [OPTIONS] STACK [STACK...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker stack remove` `docker stack down`    |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Remove the stack from the swarm.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option         | Default | Description                   |
| -------------- | ------- | ----------------------------- |
| `-d, --detach` | `true`  | Do not wait for stack removal |

## [Examples](#examples)

### [Remove a stack](#remove-a-stack)

This will remove the stack with the name `myapp`. Services, networks, and secrets associated with the stack will be removed.

```console
$ docker stack rm myapp

Removing service myapp_redis
Removing service myapp_web
Removing service myapp_lb
Removing network myapp_default
Removing network myapp_frontend
```

### [Remove multiple stacks](#remove-multiple-stacks)

This will remove all the specified stacks, `myapp` and `vossibility`. Services, networks, and secrets associated with all the specified stacks will be removed.

```console
$ docker stack rm myapp vossibility

Removing service myapp_redis
Removing service myapp_web
Removing service myapp_lb
Removing network myapp_default
Removing network myapp_frontend
Removing service vossibility_nsqd
Removing service vossibility_logstash
Removing service vossibility_elasticsearch
Removing service vossibility_kibana
Removing service vossibility_ghollector
Removing service vossibility_lookupd
Removing network vossibility_default
Removing network vossibility_vossibility
```

----
url: https://docs.docker.com/guides/testcontainers-java-micronaut-wiremock/write-tests/
----

# Write tests with WireMock and Testcontainers

***

Table of contents

***

Mocking external API interactions at the HTTP protocol level, rather than mocking Java methods, lets you verify marshalling and unmarshalling behavior and simulate network issues.

## [Test with WireMock's JUnit 5 extension](#test-with-wiremocks-junit-5-extension)

The first approach uses WireMock's `WireMockExtension` to start an in-process WireMock server on a dynamic port.

Create `AlbumControllerTest.java`:

```java
package com.testcontainers.demo;

import static com.github.tomakehurst.wiremock.client.WireMock.aResponse;
import static com.github.tomakehurst.wiremock.client.WireMock.urlMatching;
import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;
import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.hasSize;

import com.github.tomakehurst.wiremock.client.WireMock;
import com.github.tomakehurst.wiremock.junit5.WireMockExtension;
import io.micronaut.context.ApplicationContext;
import io.micronaut.http.MediaType;
import io.micronaut.runtime.server.EmbeddedServer;
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import java.util.Collections;
import java.util.Map;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.RegisterExtension;

class AlbumControllerTest {

    @RegisterExtension
    static WireMockExtension wireMock = WireMockExtension.newInstance()
            .options(wireMockConfig().dynamicPort())
            .build();

    private Map<String, Object> getProperties() {
        return Collections.singletonMap("micronaut.http.services.photosapi.url", wireMock.baseUrl());
    }

    @Test
    void shouldGetAlbumById() {
        try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) {
            RestAssured.port = server.getPort();
            Long albumId = 1L;
            String responseJson =
                    """
            [
                 {
                     "id": 1,
                     "title": "accusamus beatae ad facilis cum similique qui sunt",
                     "url": "https://via.placeholder.com/600/92c952",
                     "thumbnailUrl": "https://via.placeholder.com/150/92c952"
                 },
                 {
                     "id": 2,
                     "title": "reprehenderit est deserunt velit ipsam",
                     "url": "https://via.placeholder.com/600/771796",
                     "thumbnailUrl": "https://via.placeholder.com/150/771796"
                 }
             ]
            """;
            wireMock.stubFor(WireMock.get(urlMatching("/albums/" + albumId + "/photos"))
                    .willReturn(aResponse()
                            .withHeader("Content-Type", MediaType.APPLICATION_JSON)
                            .withBody(responseJson)));

            given().contentType(ContentType.JSON)
                    .when()
                    .get("/api/albums/{albumId}", albumId)
                    .then()
                    .statusCode(200)
                    .body("albumId", is(albumId.intValue()))
                    .body("photos", hasSize(2));
        }
    }

    @Test
    void shouldReturnServerErrorWhenPhotoServiceCallFailed() {
        try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) {
            RestAssured.port = server.getPort();
            Long albumId = 2L;
            wireMock.stubFor(WireMock.get(urlMatching("/albums/" + albumId + "/photos"))
                    .willReturn(aResponse().withStatus(500)));

            given().contentType(ContentType.JSON)
                    .when()
                    .get("/api/albums/{albumId}", albumId)
                    .then()
                    .statusCode(500);
        }
    }
}
```

Here's what this test does:

* `WireMockExtension` starts a WireMock server on a dynamic port.
* The `getProperties()` method overrides `micronaut.http.services.photosapi.url` to point at the WireMock endpoint, so the application talks to WireMock instead of the real photo service.
* `shouldGetAlbumById()` configures a mock response for `/albums/{albumId}/photos`, sends a request to the application's `/api/albums/{albumId}` endpoint, and verifies the response body.
* `shouldReturnServerErrorWhenPhotoServiceCallFailed()` configures WireMock to return a 500 status and verifies the application propagates that error.

## [Stub using JSON mapping files](#stub-using-json-mapping-files)

Instead of stubbing with the WireMock Java API, you can use JSON mapping-based configuration.

Create `src/test/resources/wiremock/mappings/get-album-photos.json`:

```json
{
  "mappings": [
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/([0-9]+)/photos"
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": "application/json"
        },
        "bodyFileName": "album-photos-resp-200.json"
      }
    },
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/2/photos"
      },
      "response": {
        "status": 500,
        "headers": {
          "Content-Type": "application/json"
        }
      }
    },
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/3/photos"
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": "application/json"
        },
        "jsonBody": []
      }
    }
  ]
}
```

Create `src/test/resources/wiremock/__files/album-photos-resp-200.json`:

```json
[
  {
    "id": 1,
    "title": "accusamus beatae ad facilis cum similique qui sunt",
    "url": "https://via.placeholder.com/600/92c952",
    "thumbnailUrl": "https://via.placeholder.com/150/92c952"
  },
  {
    "id": 2,
    "title": "reprehenderit est deserunt velit ipsam",
    "url": "https://via.placeholder.com/600/771796",
    "thumbnailUrl": "https://via.placeholder.com/150/771796"
  }
]
```

Then initialize WireMock to load stub mappings from these files:

```java
@RegisterExtension
static WireMockExtension wireMock = WireMockExtension.newInstance()
     .options(
         wireMockConfig()
            .dynamicPort()
            .usingFilesUnderClasspath("wiremock")
    )
    .build();
```

With mapping files-based stubbing in place, write tests without needing programmatic stubs:

```java
@Test
void shouldGetAlbumById() {
    Long albumId = 1L;
    try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) {
        RestAssured.port = server.getPort();

        given().contentType(ContentType.JSON)
                .when()
                .get("/api/albums/{albumId}", albumId)
                .then()
                .statusCode(200)
                .body("albumId", is(albumId.intValue()))
                .body("photos", hasSize(2));
    }
}
```

## [Use the Testcontainers WireMock module](#use-the-testcontainers-wiremock-module)

The [Testcontainers WireMock module](https://testcontainers.com/modules/wiremock/) provisions a WireMock server as a standalone container within your tests, based on [WireMock Docker](https://github.com/wiremock/wiremock-docker).

Create `src/test/resources/mocks-config.json` with the stub mappings:

```json
{
  "mappings": [
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/([0-9]+)/photos"
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": "application/json"
        },
        "bodyFileName": "album-photos-response.json"
      }
    },
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/2/photos"
      },
      "response": {
        "status": 500,
        "headers": {
          "Content-Type": "application/json"
        }
      }
    },
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/3/photos"
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": "application/json"
        },
        "jsonBody": []
      }
    }
  ]
}
```

Create `src/test/resources/album-photos-response.json`:

```json
[
  {
    "id": 1,
    "title": "accusamus beatae ad facilis cum similique qui sunt",
    "url": "https://via.placeholder.com/600/92c952",
    "thumbnailUrl": "https://via.placeholder.com/150/92c952"
  },
  {
    "id": 2,
    "title": "reprehenderit est deserunt velit ipsam",
    "url": "https://via.placeholder.com/600/771796",
    "thumbnailUrl": "https://via.placeholder.com/150/771796"
  }
]
```

Create `AlbumControllerTestcontainersTests.java`:

```java
package com.testcontainers.demo;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.hasSize;
import static org.hamcrest.Matchers.nullValue;

import io.micronaut.context.ApplicationContext;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.runtime.server.EmbeddedServer;
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import java.util.Collections;
import java.util.Map;
import org.junit.jupiter.api.Test;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.wiremock.integrations.testcontainers.WireMockContainer;

@Testcontainers(disabledWithoutDocker = true)
class AlbumControllerTestcontainersTests {

    @Container
    static WireMockContainer wiremockServer = new WireMockContainer("wiremock/wiremock:2.35.0")
            .withMappingFromResource("mocks-config.json")
            .withFileFromResource("album-photos-response.json");

    @NonNull public Map<String, Object> getProperties() {
        return Collections.singletonMap("micronaut.http.services.photosapi.url", wiremockServer.getBaseUrl());
    }

    @Test
    void shouldGetAlbumById() {
        Long albumId = 1L;
        try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) {
            RestAssured.port = server.getPort();

            given().contentType(ContentType.JSON)
                    .when()
                    .get("/api/albums/{albumId}", albumId)
                    .then()
                    .statusCode(200)
                    .body("albumId", is(albumId.intValue()))
                    .body("photos", hasSize(2));
        }
    }

    @Test
    void shouldReturnServerErrorWhenPhotoServiceCallFailed() {
        Long albumId = 2L;
        try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) {
            RestAssured.port = server.getPort();
            given().contentType(ContentType.JSON)
                    .when()
                    .get("/api/albums/{albumId}", albumId)
                    .then()
                    .statusCode(500);
        }
    }

    @Test
    void shouldReturnEmptyPhotos() {
        Long albumId = 3L;
        try (EmbeddedServer server = ApplicationContext.run(EmbeddedServer.class, getProperties())) {
            RestAssured.port = server.getPort();
            given().contentType(ContentType.JSON)
                    .when()
                    .get("/api/albums/{albumId}", albumId)
                    .then()
                    .statusCode(200)
                    .body("albumId", is(albumId.intValue()))
                    .body("photos", nullValue());
        }
    }
}
```

Here's what this test does:

* `@Testcontainers` and `@Container` annotations start a `WireMockContainer` using the `wiremock/wiremock:2.35.0` Docker image.
* `withMappingFromResource("mocks-config.json")` loads stub mappings from the classpath resource.
* `withFileFromResource("album-photos-response.json")` makes the response body file available to WireMock.
* `getProperties()` overrides the photo service URL to point at the WireMock container's base URL.
* `shouldGetAlbumById()` verifies that the application returns the expected album with two photos.
* `shouldReturnServerErrorWhenPhotoServiceCallFailed()` verifies that a 500 from the photo service propagates to the caller.
* `shouldReturnEmptyPhotos()` verifies the application handles an empty photo list.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-micronaut-wiremock/run-tests/)

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/
----

# Registry Access Management

***

Table of contents

***

Subscription: Business

For: Administrators

Registry Access Management (RAM) lets administrators control which container registries developers can access through Docker Desktop. This DNS-level filtering ensures developers only pull and push images from approved registries, improving supply chain security.

RAM works with all registry types including cloud services, on-premises registries, and registry mirrors. You can allow any hostname or domain, but must include redirect domains (like `s3.amazonaws.com` for some registries) in your allowlist.

## [Supported registries](#supported-registries)

Registry Access Management works with any container registry, including:

* Docker Hub (allowed by default)
* Cloud registries: Amazon ECR, Google Artifact Registry, Azure Container Registry
* Git-based registries: GitHub Container Registry, GitLab Container Registry
* On-premises solutions: Nexus, Artifactory, Harbor
* Registry mirrors: Including Docker Hub mirrors

## [Prerequisites](#prerequisites)

Before configuring Registry Access Management, you must:

* [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/). Registry Access Management only takes effect when users are signed in to Docker Desktop with organization credentials.
* Use [personal access tokens (PATs)](https://docs.docker.com/security/access-tokens/) for authentication (Organization access tokens aren't supported)
* Have a Docker Business subscription

## [Configure registry permissions](#configure-registry-permissions)

To configure registry permissions:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down.

2. Select **Admin Console**, then **Registry access**.

3. Use the **toggle** to enable registry access. By default, Docker Hub is enabled in the registry list.

4. To add additional registries, select **Add registry** and provide a **Registry address** and **Registry nickname**.

5. Select **Create**. You can add up to 100 registries.

6. Verify your registry appears in the registry list and select **Save changes**.

   > Note
   >
   > Policy changes can take up to 24 hours to propagate. To apply changes immediately, ask developers to sign out and back in to Docker Desktop.

If a developer belongs to multiple organizations with different RAM policies, only the policy for the first organization in the configuration file is enforced.

> Tip
>
> RAM restrictions also apply to Dockerfile `ADD` instructions that fetch content via URL. Include trusted registry domains in your allowlist when using `ADD` with URLs.
>
> RAM is designed for container registries, not general-purpose URLs like package mirrors or storage services. Adding too many domains may cause errors or hit system limits.

## [Verify restrictions are working](#verify-restrictions-are-working)

After users sign in to Docker Desktop with their organization credentials, Registry Access Management takes effect immediately.

When users try to pull from a blocked registry:

```console
$ docker pull blocked-registry.com/image:tag
Error response from daemon: registry access to blocked-registry.com is not allowed
```

Allowed registry access works normally:

```console
$ docker pull allowed-registry.com/image:tag
# Pull succeeds
```

Registry restrictions apply to all Docker operations including pulls, pushes, and builds that reference external registries.

## [Registry limits and platform constraints](#registry-limits-and-platform-constraints)

Registry Access Management has these limits and platform-specific behaviors:

* Maximum allowlist size: 100 registries or domains per organization
* DNS-based filtering: Restrictions work at the hostname level, not IP addresses
* Redirect domains required: Must include all domains a registry redirects to (CDN endpoints, storage services)
* Windows containers: Windows image operations aren't restricted by default. Turn on **Use proxy for Windows Docker daemon** in Docker Desktop settings to apply restrictions
* WSL 2 requirements: Requires Linux kernel 5.4 or later, restrictions apply to all WSL 2 distributions

## [Build and deployment restrictions](#build-and-deployment-restrictions)

These scenarios are not restricted by Registry Access Management:

* Docker buildx with Kubernetes driver
* Docker buildx with custom Docker-container driver
* Some Docker Debug and Kubernetes image pulls (even if Docker Hub is blocked)
* Images previously cached by registry mirrors may still be blocked if the source registry is restricted

## [Security bypass considerations](#security-bypass-considerations)

Users can potentially bypass Registry Access Management through:

* Local proxies or DNS manipulation
* Signing out of Docker Desktop (unless sign-in is enforced)
* Network-level modifications outside Docker Desktop's control

To maximize security effectiveness:

* [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) to prevent bypass through sign-out
* Implement additional network-level controls for complete protection
* Use Registry Access Management as part of a broader security strategy

## [Registry allowlist best practices](#registry-allowlist-best-practices)

* Include all registry domains: Some registries redirect to multiple domains. For AWS ECR, include:

  ```text
  your-account.dkr.ecr.us-west-2.amazonaws.com
  amazonaws.com
  s3.amazonaws.com
  ```

* Practice regular allowlist maintenance:

  * Remove unused registries periodically
  * Add newly approved registries as needed
  * Update domain names that may have changed
  * Monitor registry usage through Docker Desktop analytics

* Test configuration changes:

  * Verify registry access after making allowlist updates
  * Check that all necessary redirect domains are included
  * Ensure development workflows aren't disrupted
  * Combine with [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) for comprehensive protection

----
url: https://docs.docker.com/engine/daemon/
----

# Docker daemon configuration overview

***

Table of contents

***

This page shows you how to customize the Docker daemon, `dockerd`.

> Note
>
> This page is for users who've installed Docker Engine manually. If you're using Docker Desktop, refer to the [settings page](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine).

## [Configure the Docker daemon](#configure-the-docker-daemon)

There are two ways to configure the Docker daemon:

* Use a JSON configuration file. This is the preferred option, since it keeps all configurations in a single place.
* Use flags when starting `dockerd`.

You can use both of these options together as long as you don't specify the same option both as a flag and in the JSON file. If that happens, the Docker daemon won't start and prints an error message.

### [Configuration file](#configuration-file)

The following table shows the location where the Docker daemon expects to find the configuration file by default, depending on your system and how you're running the daemon.

| OS and configuration | File location                              |
| -------------------- | ------------------------------------------ |
| Linux, regular setup | `/etc/docker/daemon.json`                  |
| Linux, rootless mode | `~/.config/docker/daemon.json`             |
| Windows              | `C:\ProgramData\docker\config\daemon.json` |

For rootless mode, the daemon respects the `XDG_CONFIG_HOME` variable. If set, the expected file location is `$XDG_CONFIG_HOME/docker/daemon.json`.

You can also explicitly specify the location of the configuration file on startup, using the `dockerd --config-file` flag.

Learn about the available configuration options in the [dockerd reference docs](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file)

### [Configuration using flags](#configuration-using-flags)

You can also start the Docker daemon manually and configure it using flags. This can be useful for troubleshooting problems.

Here's an example of how to manually start the Docker daemon, using the same configurations as shown in the previous JSON configuration:

```console
$ dockerd --debug \
  --tls=true \
  --tlscert=/var/docker/server.pem \
  --tlskey=/var/docker/serverkey.pem \
  --host tcp://192.168.59.3:2376
```

Learn about the available configuration options in the [dockerd reference docs](https://docs.docker.com/reference/cli/dockerd/), or by running:

```console
$ dockerd --help
```

## [Daemon data directory](#daemon-data-directory)

The Docker daemon persists all data in a single directory. This tracks everything related to Docker, including containers, images, volumes, service definition, and secrets.

By default the daemon stores data in:

* `/var/lib/docker` on Linux
* `C:\ProgramData\docker` on Windows

When using the [containerd image store](https://docs.docker.com/engine/storage/containerd/) (the default for Docker Engine 29.0 and later on fresh installations), image contents and container snapshots are stored in `/var/lib/containerd`. Other daemon data (volumes, configs) remains in `/var/lib/docker`.

When using [classic storage drivers](https://docs.docker.com/engine/storage/drivers/) like `overlay2` (the default for upgraded installations), all data is stored in `/var/lib/docker`.

### [Configure the data directory location](#configure-the-data-directory-location)

You can configure the Docker daemon to use a different storage directory using the `data-root` configuration option.

```json
{
  "data-root": "/mnt/docker-data"
}
```

The `data-root` option does not affect image and container data stored in `/var/lib/containerd` when using the containerd image store. To change the storage location of containerd snapshotters, use the system containerd configuration file:

/etc/containerd/config.toml

```toml
version = 2
root = "/mnt/containerd-data"
```

Make sure you use a dedicated directory for each daemon. If two daemons share the same directory, for example an NFS share, you will experience errors that are difficult to troubleshoot.

## [Next steps](#next-steps)

Many specific configuration options are discussed throughout the Docker documentation. Some places to go next include:

* [Automatically start containers](https://docs.docker.com/engine/containers/start-containers-automatically/)
* [Limit a container's resources](https://docs.docker.com/engine/containers/resource_constraints/)
* [Configure storage drivers](https://docs.docker.com/engine/storage/drivers/select-storage-driver/)
* [Container security](https://docs.docker.com/engine/security/)
* [Configure the Docker daemon to use a proxy](https://docs.docker.com/engine/daemon/proxy/)

----
url: https://docs.docker.com/guides/docker-build-cloud/
----

# Docker Build Cloud: Reclaim your time with fast, multi-architecture builds

Table of contents

***

Build applications up to 39x faster using cloud-based resources, shared team cache, and native multi-architecture support.

**Time to complete** 10 minutes

98% of developers spend up to an hour every day waiting for builds to finish ([Incredibuild: 2022 Big Dev Build Times](https://www.incredibuild.com/survey-report-2022)). Heavy, complex builds can become a major roadblock for development teams, slowing down both local development and CI/CD pipelines.

Docker Build Cloud speeds up image build times to improve developer productivity, reduce frustrations, and help you shorten the release cycle.

## [Who’s this for?](#whos-this-for)

* Anyone who wants to tackle common causes of slow image builds: limited local resources, slow emulation, and lack of build collaboration across a team.
* Developers working on older machines who want to build faster.
* Development teams working on the same repository who want to cut wait times with a shared cache.
* Developers performing multi-architecture builds who don’t want to spend hours configuring and rebuilding for emulators.

## [What you’ll learn](#what-youll-learn)

* Building container images faster locally and in CI
* Accelerating builds for multi-platform images
* Reusing pre-built images to expedite workflows

## [Tools integration](#tools-integration)

Works well with Docker Compose, GitHub Actions, and other CI solutions

## [Modules](#modules)

1. [Why Docker Build Cloud?](https://docs.docker.com/guides/docker-build-cloud/why/)

   Learn how Docker Build Cloud makes your builds faster.

2. [Demo: set up and use Docker Build Cloud in development](https://docs.docker.com/guides/docker-build-cloud/dev/)

   Learn how to use Docker Build Cloud for local builds.

3. [Demo: Using Docker Build Cloud in CI](https://docs.docker.com/guides/docker-build-cloud/ci/)

   Learn how to use Docker Build Cloud to build your app faster in CI.

4. [Common challenges and questions](https://docs.docker.com/guides/docker-build-cloud/common-questions/)

   Explore common challenges and questions related to Docker Build Cloud.

----
url: https://docs.docker.com/engine/release-notes/18.05/
----

# Docker Engine 18.05 release notes

***

Table of contents

***

## [18.05.0-ce](#18050-ce)

2018-05-09

### [Builder](#builder)

* Adding `netbsd` compatibility to the package `pkg/term`. [moby/moby#36887](https://github.com/moby/moby/pull/36887)
* Standardizes output path for artifacts of intermediate builds to `/build/`. [moby/moby#36858](https://github.com/moby/moby/pull/36858)

### [Client](#client)

* Fix `docker stack deploy` reference flag. [docker/cli#981](https://github.com/docker/cli/pull/981)
* Fix docker stack deploy re-deploying services after the service was updated with `--force`. [docker/cli#963](https://github.com/docker/cli/pull/963)

- Add bash completion for `secret|config create --template-driver`. [docker/cli#1004](https://github.com/docker/cli/pull/1004)
- Add fish completions for docker trust subcommand. [docker/cli#984](https://github.com/docker/cli/pull/984)

* Fix --format example for docker history. [docker/cli#980](https://github.com/docker/cli/pull/980)
* Fix error with merge composefile with networks. [docker/cli#983](https://github.com/docker/cli/pull/983)

### [Logging](#logging)

* Standardized the properties of storage-driver log messages. [moby/moby#36492](https://github.com/moby/moby/pull/36492)
* Improve partial message support in logger. [moby/moby#35831](https://github.com/moby/moby/pull/35831)

### [Networking](#networking)

* Allow for larger preset property values, do not override. [docker/libnetwork#2124](https://github.com/docker/libnetwork/pull/2124)
* networkdb: User write lock in handleNodeEvent. [docker/libnetwork#2136](https://github.com/docker/libnetwork/pull/2136)

- Import libnetwork fix for rolling updates. [moby/moby#36638](https://github.com/moby/moby/pull/36638)
- Update libnetwork to improve scalability of bridge network isolation rules. [moby/moby#36774](https://github.com/moby/moby/pull/36774)

* Fix a misused network object name. [moby/moby#36745](https://github.com/moby/moby/pull/36745)

### [Runtime](#runtime)

* LCOW: Implement `docker save`. [moby/moby#36599](https://github.com/moby/moby/pull/36599)
* Pkg: devmapper: dynamically load dm\_task\_deferred\_remove. [moby/moby#35518](https://github.com/moby/moby/pull/35518)
* Windows: Add GetLayerPath implementation in graphdriver. [moby/moby#36738](https://github.com/moby/moby/pull/36738)

- Fix Windows layer leak when write fails. [moby/moby#36728](https://github.com/moby/moby/pull/36728)
- Fix FIFO, sockets and device files when run in user NS. [moby/moby#36756](https://github.com/moby/moby/pull/36756)
- Fix docker version output alignment. [docker/cli#965](https://github.com/docker/cli/pull/965)

* Always make sysfs read-write with privileged. [moby/moby#36808](https://github.com/moby/moby/pull/36808)
* Bump Golang to 1.10.1. [moby/moby#35739](https://github.com/moby/moby/pull/35739)
* Bump containerd client. [moby/moby#36684](https://github.com/moby/moby/pull/36684)
* Bump golang.org/x/net to go1.10 release commit. [moby/moby#36894](https://github.com/moby/moby/pull/36894)
* Context.WithTimeout: do call the cancel func. [moby/moby#36920](https://github.com/moby/moby/pull/36920)
* Copy: avoid using all system memory with authz plugins. [moby/moby#36595](https://github.com/moby/moby/pull/36595)
* Daemon/cluster: handle partial attachment entries during configure. [moby/moby#36769](https://github.com/moby/moby/pull/36769)
* Don't make container mount unbindable. [moby/moby#36768](https://github.com/moby/moby/pull/36768)
* Extra check before unmounting on shutdown. [moby/moby#36879](https://github.com/moby/moby/pull/36879)
* Move mount parsing to separate package. [moby/moby#36896](https://github.com/moby/moby/pull/36896)
* No global volume driver store. [moby/moby#36637](https://github.com/moby/moby/pull/36637)
* Pkg/mount improvements. [moby/moby#36091](https://github.com/moby/moby/pull/36091)
* Relax some libcontainerd client locking. [moby/moby#36848](https://github.com/moby/moby/pull/36848)
* Remove daemon dependency on api packages. [moby/moby#36912](https://github.com/moby/moby/pull/36912)
* Remove the retries for service update. [moby/moby#36827](https://github.com/moby/moby/pull/36827)
* Revert unencryted storage warning prompt. [docker/cli#1008](https://github.com/docker/cli/pull/1008)
* Support cancellation in `directory.Size()`. [moby/moby#36734](https://github.com/moby/moby/pull/36734)
* Switch from x/net/context -> context. [moby/moby#36904](https://github.com/moby/moby/pull/36904)
* Fixed a function to check Content-type is `application/json` or not. [moby/moby#36778](https://github.com/moby/moby/pull/36778)

- Add default pollSettings config functions. [moby/moby#36706](https://github.com/moby/moby/pull/36706)
- Add if judgment before receiving operations on daemonWaitCh. [moby/moby#36651](https://github.com/moby/moby/pull/36651)

* Fix issues with running volume tests as non-root.. [moby/moby#36935](https://github.com/moby/moby/pull/36935)

### [Swarm Mode](#swarm-mode)

* RoleManager will remove detected nodes from the cluster membership [docker/swarmkit#2548](https://github.com/docker/swarmkit/pull/2548)
* Scheduler/TaskReaper: handle unassigned tasks marked for shutdown [docker/swarmkit#2574](https://github.com/docker/swarmkit/pull/2574)
* Avoid predefined error log. [docker/swarmkit#2561](https://github.com/docker/swarmkit/pull/2561)
* Task reaper should delete tasks with removed slots that were not yet assigned. [docker/swarmkit#2557](https://github.com/docker/swarmkit/pull/2557)
* Agent reports FIPS status. [docker/swarmkit#2587](https://github.com/docker/swarmkit/pull/2587)

- Fix: timeMutex critical operation outside of critical section. [docker/swarmkit#2603](https://github.com/docker/swarmkit/pull/2603)

* Expose swarmkit's Raft tuning parameters in engine config. [moby/moby#36726](https://github.com/moby/moby/pull/36726)
* Make internal/test/daemon.Daemon swarm aware. [moby/moby#36826](https://github.com/moby/moby/pull/36826)

----
url: https://docs.docker.com/reference/cli/docker/sandbox/create/
----

# docker sandbox create

***

| Description | Create a sandbox for an agent                     |
| ----------- | ------------------------------------------------- |
| Usage       | `docker sandbox create [OPTIONS] AGENT WORKSPACE` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Create a sandbox with access to a host workspace for an agent.

Available agents are provided as subcommands. Use "create AGENT --help" for agent-specific options.

## [Options](#options)

| Option                        | Default   | Description                                                                                                                        |
| ----------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--name`                      |           | Name for the sandbox (default: -, letters, numbers, hyphens, underscores, periods, plus signs and minus signs only)                |
| `--pull-template`             | `missing` | Template image pull policy: always (always pull from registry), missing (pull only if not cached), never (use only cached images)  |
| `-q, --quiet`                 |           | Suppress verbose output                                                                                                            |
| [`-t, --template`](#template) |           | Container image to use for the sandbox (default: agent-specific image)                                                             |

## [Examples](#examples)

### [Create a Claude sandbox](#create-a-claude-sandbox)

```console
$ docker sandbox create claude ~/my-project
```

### [Create with a custom name](#create-with-a-custom-name)

```console
$ docker sandbox create --name my-sandbox claude ~/my-project
```

### [Use a custom base image (-t, --template)](#template)

```text
--template IMAGE
```

Specify a custom container image to use as the sandbox base:

```console
$ docker sandbox create --template python:3-alpine claude ~/my-project
```

By default, each agent uses a pre-configured image.

### [Create and run immediately](#create-and-run-immediately)

After creating a sandbox, use `run` to start the agent:

```console
$ docker sandbox create --name my-sandbox claude ~/my-project
$ docker sandbox run my-sandbox
```

Or use `docker sandbox run` directly to create and run in one step:

```console
$ docker sandbox run claude ~/my-project
```

## [Subcommands](#subcommands)

| Command                                                                                                   | Description                   |
| --------------------------------------------------------------------------------------------------------- | ----------------------------- |
| [`docker sandbox create cagent`](https://docs.docker.com/reference/cli/docker/sandbox/create/cagent/)     | Create a sandbox for cagent   |
| [`docker sandbox create claude`](https://docs.docker.com/reference/cli/docker/sandbox/create/claude/)     | Create a sandbox for claude   |
| [`docker sandbox create codex`](https://docs.docker.com/reference/cli/docker/sandbox/create/codex/)       | Create a sandbox for codex    |
| [`docker sandbox create copilot`](https://docs.docker.com/reference/cli/docker/sandbox/create/copilot/)   | Create a sandbox for copilot  |
| [`docker sandbox create gemini`](https://docs.docker.com/reference/cli/docker/sandbox/create/gemini/)     | Create a sandbox for gemini   |
| [`docker sandbox create kiro`](https://docs.docker.com/reference/cli/docker/sandbox/create/kiro/)         | Create a sandbox for kiro     |
| [`docker sandbox create opencode`](https://docs.docker.com/reference/cli/docker/sandbox/create/opencode/) | Create a sandbox for opencode |
| [`docker sandbox create shell`](https://docs.docker.com/reference/cli/docker/sandbox/create/shell/)       | Create a sandbox for shell    |

----
url: https://docs.docker.com/reference/cli/docker/desktop/kubernetes/images/
----

# docker desktop kubernetes images

***

| Description | List Kubernetes images used by Docker Desktop |
| ----------- | --------------------------------------------- |
| Usage       | `docker desktop kubernetes images`            |

## [Options](#options)

| Option     | Default  | Description                                          |
| ---------- | -------- | ---------------------------------------------------- |
| `--format` | `pretty` | Format the output. Accepted values are: pretty, json |

----
url: https://docs.docker.com/reference/cli/sbx/ls/
----

# sbx ls

| Description | List sandboxes   |
| ----------- | ---------------- |
| Usage       | `sbx ls [flags]` |

## [Description](#description)

List all sandboxes with their agent, status, published ports, and workspace.

## [Options](#options)

| Option        | Default | Description                |
| ------------- | ------- | -------------------------- |
| `--json`      |         | Output in JSON format      |
| `-q, --quiet` |         | Only display sandbox names |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/reference/glossary/
----

# Glossary

| Term                         | Definition                                                                                                                                                                                                                                                                             |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| []()Docker CLI               | The Docker CLI is the command-line interface for interacting with the Docker Engine. It provides commands like `docker run`, `docker build`, `docker ps`, and others to manage Docker containers, images, and services.                                                                |
| []()Docker Compose           | Docker Compose is a tool for defining and running multi-container Docker applications using a YAML file (`compose.yaml`). With a single command, you can start all services defined in the configuration.                                                                              |
| []()Docker Desktop           | Docker Desktop is an easy-to-install application for Windows, macOS, and Linux that provides a local Docker development environment. It includes Docker Engine, Docker CLI, Docker Compose, and a Kubernetes cluster.                                                                  |
| []()Docker Engine            | Docker Engine is the client-server technology that creates and runs Docker containers. It includes the Docker daemon (`dockerd`), REST API, and the Docker CLI client.                                                                                                                 |
| []()Docker Hub               | Docker Hub is Docker’s public registry service where users can store, share, and manage container images. It hosts Docker Official Images, Verified Publisher content, and community-contributed images.                                                                               |
| []()base image               | A base image is an image you designate in a `FROM` directive in a Dockerfile. It defines the starting point for your build. Dockerfile instructions create additional layers on top of the base image. A Dockerfile with the `FROM scratch` directive uses an empty base image.        |
| []()build                    | Build is the process of building Docker images using a Dockerfile. The build uses a Dockerfile and a "context". The context is the set of files in the directory in which the image is built.                                                                                          |
| []()container                | A container is a runnable instance of an image. You can start, stop, move, or delete a container using the Docker CLI or API. Containers are isolated from one another and the host system but share the OS kernel. They provide a lightweight and consistent way to run applications. |
| []()context                  | A Docker context contains endpoint configuration for the Docker CLI to connect to different Docker environments, such as remote Docker hosts or Docker Desktop. Use `docker context use` to switch between contexts.                                                                   |
| []()image                    | An image is a read-only template used to create containers. It typically includes a base operating system and application code packaged together using a Dockerfile. Images are versioned using tags and can be pushed to or pulled from a container registry like Docker Hub.         |
| []()layer                    | In an image, a layer is a modification represented by an instruction in the Dockerfile. Layers are applied in sequence to the base image to create the final image. Unchanged layers are cached, making image builds faster and more efficient.                                        |
| []()multi-architecture image | A multi-architecture image is a Docker image that supports multiple CPU architectures, like `amd64` or `arm64`. Docker automatically pulls the correct architecture image for your platform when using a multi-arch image.                                                             |
| []()persistent storage       | Persistent storage or volume storage provides a way for containers to retain data beyond their lifecycle. This storage can exist on the host machine or an external storage system and is not tied to the container's runtime.                                                         |
| []()registry                 | A registry is a storage and content delivery system for Docker images. The default public registry is Docker Hub, but you can also set up private registries using Docker Distribution.                                                                                                |
| []()volume                   | A volume is a special directory within a container that bypasses the Union File System. Volumes are designed to persist data independently of the container lifecycle. Docker supports host, anonymous, and named volumes.                                                             |

----
url: https://docs.docker.com/dhi/how-to/hardened-packages/
----

# Use Hardened System Packages

***

Table of contents

***

Docker Hardened System Packages are built from source by Docker. This ensures supply chain integrity throughout your entire image stack by eliminating risks from potentially compromised public packages.

Access to hardened packages varies by subscription:

* **DHI Community**: Includes hardened packages in base images. Can configure the public package repository to access the same packages in custom images.
* **DHI Select**: Includes all Community packages, plus access to additional compliance-specific packages (such as FIPS variants) and Docker-patched packages through the image customization UI.
* **DHI Enterprise**: Includes all Select packages, plus the ability to configure the enterprise package repository directly in your own images for full access to compliance and security-patched packages.

## [Built-in packages](#built-in-packages)

Supported distributions of Docker Hardened Images (DHI) automatically include hardened system packages. No additional configuration is required. Simply pull and use the images as normal.

All packages in these images are built by Docker from source, maintaining the same security standards as the base images themselves.

## [Add hardened packages to your images](#add-hardened-packages-to-your-images)

You can add hardened packages to your own images in the following two ways.

### [Add packages through image customization](#add-packages-through-image-customization)

Subscription: Docker Hardened Images Select or Enterprise

When customizing Docker Hardened Images with DHI Select or DHI Enterprise, you can add hardened packages for Alpine-based images through the customization interface. Follow the steps to [create an image customization](https://docs.docker.com/dhi/how-to/customize/#create-an-image-customization) and select hardened packages during the customization process.

### [Configure the package manager](#configure-the-package-manager)

You can configure your package manager to pull from Docker's hardened package repositories. This lets you install hardened packages in your own images.

#### [Public repository](#public-repository)

To use Docker's public hardened package repository in your own images, configure your package manager in your Dockerfile to install the DHI signing key and add the DHI repository.

The configuration process involves three steps:

1. Install the [signing key](https://github.com/docker-hardened-images/keyring)
2. Configure the package repository
3. Update and install packages

The following example shows how to configure the Alpine package manager in your Dockerfile to use Docker's public hardened package repository:

```dockerfile
FROM alpine:3.23

# Install the signing key
RUN cd /etc/apk/keys && \
    wget https://dhi.io/keyring/dhi-apk@docker-0F81AD7700D99184.rsa.pub

# Replace the default repositories with the hardened package repository
RUN echo "https://dhi.io/apk/alpine/v3.23/main" > /etc/apk/repositories

# Update and install packages
RUN apk update && \
    apk add libpng
```

Replace `3.23` with your Alpine version in both the base image tag and repository URL.

To verify the configuration, build and run the image:

```console
$ docker build -t myapp:latest .
$ docker run -it myapp:latest sh
```

Inside the container, check the configured repositories:

```console
/ # cat /etc/apk/repositories
https://dhi.io/apk/alpine/v3.23/main
```

This ensures all packages are installed from Docker's hardened repository.

The following example shows how to configure the Debian package manager in your Dockerfile to use Docker's public hardened package repository:

```dockerfile
FROM debian:trixie-slim

# Install the signing key
RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates curl gnupg \
    && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://dhi.io/keyring/dhi-deb-gpg.D46852F6925E9F71.key \
    | gpg --dearmor -o /usr/share/keyrings/dhi-deb.gpg

# Add the hardened package repository
RUN echo "deb [signed-by=/usr/share/keyrings/dhi-deb.gpg] https://dhi.io/deb/debian/main trixie main" \
    > /etc/apt/sources.list.d/dhi.list

# Update and install packages
RUN apt-get update && apt-get install -y jq \
    && rm -rf /var/lib/apt/lists/*
```

To verify the configuration, build and run the image:

```console
$ docker build -t myapp:latest .
$ docker run -it myapp:latest bash
```

Inside the container, check the configured repository:

```console
root@myapp:/# cat /etc/apt/sources.list.d/dhi.list
deb [signed-by=/usr/share/keyrings/dhi-deb.gpg] https://dhi.io/deb/debian/main trixie main
```

When the DHI repository carries a hardened version of a package, `apt` prefers it over the upstream Debian version automatically. You can confirm this with `apt-cache policy <package>`, which shows a candidate with a `+dhi` or `dhi` version suffix sourced from `https://dhi.io/deb/debian/main`.

Not every Debian package is available as a hardened system package. When a package is not in the DHI repository, `apt` transparently falls back to the upstream Debian mirrors configured in the base image.

All packages installed from the Docker Hardened Images repository are built from source by Docker and include full provenance.

#### [Enterprise repository](#enterprise-repository)

Subscription: Docker Hardened Images Enterprise

With DHI Enterprise, you have access to an additional package repository that includes hardened packages for compliance variants such as FIPS, as well as additional security patches.

The configuration process involves five steps:

1. Install the [signing keys](https://github.com/docker-hardened-images/keyring)
2. Configure the base package repository
3. Add the enterprise security repository
4. Configure package installation with authentication
5. Build the image passing credentials as a secret using the DHI CLI

The following example shows how to configure the Alpine package manager in your Dockerfile to use Docker's enterprise hardened package repository:

```dockerfile
FROM alpine:3.23

# Install the signing key
RUN cd /etc/apk/keys && \
    wget https://dhi.io/keyring/dhi-apk@docker-0F81AD7700D99184.rsa.pub

# Replace the default repositories with the hardened package repository
RUN echo "https://dhi.io/apk/alpine/v3.23/main" > /etc/apk/repositories

# Update and install the enterprise configuration package to add the security repository
RUN apk update && \
    apk add dhi-enterprise-conf

# Install packages from the security repository with authentication
RUN --mount=type=secret,id=http_auth \
    HTTP_AUTH="$(cat /run/secrets/http_auth)" \
    apk update && \
    apk add openssl-fips
```

Build the image with authentication passed securely as a build secret:

```console
$ docker dhi auth apk > http_auth.txt
$ docker build --secret id=http_auth,src=http_auth.txt -t myapp-enterprise:latest .
$ rm http_auth.txt
```

The `--secret` flag securely mounts the authentication credentials during build without storing them in the image layers or metadata.

The following example shows how to configure the Debian package manager in your Dockerfile to use Docker's enterprise hardened package repository. Mount credentials at `/etc/apt/auth.conf.d/dhi.conf`; `apt` reads files in `/etc/apt/auth.conf.d/` automatically when they have mode `0600`:

```dockerfile
FROM debian:trixie-slim

# Install the signing keys
RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates curl gnupg \
    && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://dhi.io/keyring/dhi-deb-gpg.D46852F6925E9F71.key \
    | gpg --dearmor -o /usr/share/keyrings/dhi-deb.gpg
RUN curl -fsSL https://dhi.io/keyring/dhi-deb-sec-gpg.D46852F6925E9F71.key \
    | gpg --dearmor -o /usr/share/keyrings/dhi-deb-sec.gpg

# Add the hardened package repository and the enterprise security repository
RUN echo "deb [signed-by=/usr/share/keyrings/dhi-deb.gpg] https://dhi.io/deb/debian/main trixie main" \
    > /etc/apt/sources.list.d/dhi.list
RUN echo "deb [signed-by=/usr/share/keyrings/dhi-deb-sec.gpg] https://dhi.io/deb/debian/security trixie main" \
    > /etc/apt/sources.list.d/dhi-sec.list

# Install packages from the security repository with authentication
RUN --mount=type=secret,id=netrc,target=/etc/apt/auth.conf.d/dhi.conf,mode=0600 \
    apt-get update && apt-get install -y openssl \
    && rm -rf /var/lib/apt/lists/*
```

Build the image, passing credentials securely as a build secret through an environment variable:

```console
$ NETRC=$(docker dhi auth deb) docker build \
    --secret id=netrc,env=NETRC \
    -t myapp-enterprise:latest .
```

The `--secret id=netrc,env=NETRC` form securely mounts the authentication credentials during build without storing them in the image layers or metadata.

## [Verify packages](#verify-packages)

Every hardened package is cryptographically signed and includes metadata that proves its provenance and build integrity. You can verify the signatures and view the metadata to ensure your packages come from Docker's trusted build infrastructure.

### [View package metadata](#view-package-metadata)

To view information about a hardened package:

```console
$ apk info -L <package-name>
```

```console
$ dpkg -L <package-name>
```

This shows the files included in the package and its metadata.

### [Verify package signatures](#verify-package-signatures)

Hardened packages are cryptographically signed by Docker. When you install the signing keys and configure your package manager as described previously, the package manager automatically verifies signatures during installation.

If a package fails signature verification, the package manager will refuse to install it, protecting you from tampered or compromised packages.

### [Build provenance and cryptographic verification](#build-provenance-and-cryptographic-verification)

Docker hardened packages are built by Docker's trusted infrastructure and include verifiable metadata and cryptographic signatures.

To view this metadata for an installed package:

```console
$ apk info -a <package-name>
```

```console
$ apt-cache show <package-name>
```

Or to view metadata for a package before installing:

```console
$ apk fetch --stdout <package-name> | tar -xzO .PKGINFO
```

```console
$ apt-get download <package-name>
$ dpkg-deb -I <package-name>_*.deb
```

The package signing keys ensure that packages haven't been tampered with after being built. When you install the signing key and configure your package manager, all packages are automatically verified before installation.

### [Package attestations](#package-attestations)

Each hardened package includes its own attestations, similar to [image attestations](https://docs.docker.com/dhi/how-to/verify/). These attestations provide provenance and build information for individual packages, allowing you to trace the supply chain down to the package level.

You can retrieve package attestations by first extracting package information from the image's SLSA provenance, then using the package digest to access its attestations.

#### [Extract package information from image attestations](#extract-package-information-from-image-attestations)

To get provenance information for a specific package from an image's SLSA provenance attestation, you first need to retrieve the image's provenance and then filter for the specific package you're interested in.

The SLSA provenance attestation includes a `materials` array that lists all build inputs, including packages. You can use `jq` to filter this array for a specific package:

```console
$ docker scout attest get dhi.io/golang:1.26-alpine3.23 \
    --predicate-type https://slsa.dev/provenance/v0.2 | \
    jq '.predicate.materials[] | select( .uri == "https://dhi.io/apk/alpine/v3.23/main/aarch64/golang-1.26-1.26.0-r0.apk" )'
```

Replace the package URI in the `select()` filter with the specific package you're looking for. You can find available packages by first running the command without the `select()` filter to see all materials.

This returns the package URI and its SHA-256 digest:

```json
{
  "uri": "https://dhi.io/apk/alpine/v3.23/main/aarch64/golang-1.26-1.26.0-r0.apk",
  "digest": {
    "sha256": "4082a2500abc2e7b8435f9398d3514d760044fa52ca3d10cf80015469124a838"
  }
}
```

#### [List attestations for a package](#list-attestations-for-a-package)

Using the package digest from the previous section, you can list all available attestations for that package:

```console
$ curl -s https://dhi.io/apk/alpine/v3.23/main/sha256:4082a2500abc2e7b8435f9398d3514d760044fa52ca3d10cf80015469124a838/attestations/list | jq .
```

This returns information about the package and its available attestations:

```json
{
  "subject": {
    "name": "pkg:apk/alpine/golang-1.26@1.26.0-r0?os_name=&os_version=",
    "digest": {
      "sha256": "4082a2500abc2e7b8435f9398d3514d760044fa52ca3d10cf80015469124a838"
    }
  },
  "attestations": [
    {
      "predicate_type": "https://slsa.dev/provenance/v1",
      "digest": {
        "sha256": "97c919cf0edb27087739bbabeea4c1ef88d069cd41791476ba64b69280d63a32"
      },
      "url": "https://dhi.io/apk/alpine/v3.23/main/sha256:4082a2500abc2e7b8435f9398d3514d760044fa52ca3d10cf80015469124a838/attestations/sha256:97c919cf0edb27087739bbabeea4c1ef88d069cd41791476ba64b69280d63a32"
    }
  ]
}
```

#### [Retrieve package attestations](#retrieve-package-attestations)

To retrieve the actual attestation content, use the URL provided in the attestation list:

```console
$ curl -s https://dhi.io/apk/alpine/v3.23/main/sha256:4082a2500abc2e7b8435f9398d3514d760044fa52ca3d10cf80015469124a838/attestations/sha256:97c919cf0edb27087739bbabeea4c1ef88d069cd41791476ba64b69280d63a32 | jq .
```

This returns the full SLSA provenance attestation for the package, which includes information about how the package was built, its dependencies, and other build materials.

You can continue this process recursively to trace the supply chain all the way down to the compiler and other build tools used to create the package.

----
url: https://docs.docker.com/build/ci/github-actions/checks/
----

# Validating build configuration with GitHub Actions

***

Table of contents

***

[Build checks](https://docs.docker.com/build/checks/) let you validate your `docker build` configuration without actually running the build.

## [Run checks with `docker/build-push-action`](#run-checks-with-dockerbuild-push-action)

To run build checks in a GitHub Actions workflow with the `build-push-action`, set the `call` input parameter to `check`. With this set, the workflow fails if any check warnings are detected for your build's configuration.

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Validate build configuration
        uses: docker/build-push-action@v7
        with:
          call: check

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
```

## [Run checks with `docker/bake-action`](#run-checks-with-dockerbake-action)

If you're using Bake and `docker/bake-action` to run your builds, you don't need to specify any special inputs in your GitHub Actions workflow configuration. Instead, define a Bake target that calls the `check` method, and invoke that target in your CI.

```hcl
target "build" {
  dockerfile = "Dockerfile"
  args = {
    FOO = "bar"
  }
}
target "validate-build" {
  inherits = ["build"]
  call = "check"
}
```

```yaml
name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Validate build configuration
        uses: docker/bake-action@v7
        with:
          targets: validate-build

      - name: Build
        uses: docker/bake-action@v7
        with:
          targets: build
          push: true
```

### [Using the `call` input directly](#using-the-call-input-directly)

You can also set the build method with the `call` input which is equivalent to using the `--call` flag with `docker buildx bake`

For example, to run a check without defining `call` in your Bake file:

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Validate build configuration
        uses: docker/bake-action@v7
        with:
          targets: build
          call: check
```

----
url: https://docs.docker.com/reference/cli/docker/plugin/enable/
----

# docker plugin enable

***

| Description | Enable a plugin                         |
| ----------- | --------------------------------------- |
| Usage       | `docker plugin enable [OPTIONS] PLUGIN` |

## [Description](#description)

Enables a plugin. The plugin must be installed before it can be enabled, see [`docker plugin install`](/reference/cli/docker/plugin/install/).

## [Options](#options)

| Option      | Default | Description                      |
| ----------- | ------- | -------------------------------- |
| `--timeout` | `30`    | HTTP client timeout (in seconds) |

## [Examples](#examples)

The following example shows that the `sample-volume-plugin` plugin is installed, but disabled:

```console
$ docker plugin ls

ID            NAME                                    DESCRIPTION                ENABLED
69553ca1d123  tiborvass/sample-volume-plugin:latest   A test plugin for Docker   false
```

To enable the plugin, use the following command:

```console
$ docker plugin enable tiborvass/sample-volume-plugin

tiborvass/sample-volume-plugin

$ docker plugin ls

ID            NAME                                    DESCRIPTION                ENABLED
69553ca1d123  tiborvass/sample-volume-plugin:latest   A test plugin for Docker   true
```

----
url: https://docs.docker.com/reference/cli/docker/buildx/
----

# docker buildx

***

| Description | Docker Buildx   |
| ----------- | --------------- |
| Usage       | `docker buildx` |

## [Description](#description)

Extended build capabilities with BuildKit

## [Options](#options)

| Option                  | Default | Description                              |
| ----------------------- | ------- | ---------------------------------------- |
| [`--builder`](#builder) |         | Override the configured builder instance |
| `-D, --debug`           |         | Enable debug logging                     |

## [Examples](#examples)

### [Override the configured builder instance (--builder)](#builder)

You can also use the `BUILDX_BUILDER` environment variable.

## [Subcommands](#subcommands)

| Command                                                                                       | Description                                      |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [`docker buildx bake`](https://docs.docker.com/reference/cli/docker/buildx/bake/)             | Build from a file                                |
| [`docker buildx build`](https://docs.docker.com/reference/cli/docker/buildx/build/)           | Start a build                                    |
| [`docker buildx create`](https://docs.docker.com/reference/cli/docker/buildx/create/)         | Create a new builder instance                    |
| [`docker buildx dap`](https://docs.docker.com/reference/cli/docker/buildx/dap/)               | Start debug adapter protocol compatible debugger |
| [`docker buildx debug`](https://docs.docker.com/reference/cli/docker/buildx/debug/)           | Start debugger                                   |
| [`docker buildx dial-stdio`](https://docs.docker.com/reference/cli/docker/buildx/dial-stdio/) | Proxy current stdio streams to builder instance  |
| [`docker buildx du`](https://docs.docker.com/reference/cli/docker/buildx/du/)                 | Disk usage                                       |
| [`docker buildx history`](https://docs.docker.com/reference/cli/docker/buildx/history/)       | Commands to work on build records                |
| [`docker buildx imagetools`](https://docs.docker.com/reference/cli/docker/buildx/imagetools/) | Commands to work on images in registry           |
| [`docker buildx inspect`](https://docs.docker.com/reference/cli/docker/buildx/inspect/)       | Inspect current builder instance                 |
| [`docker buildx ls`](https://docs.docker.com/reference/cli/docker/buildx/ls/)                 | List builder instances                           |
| [`docker buildx policy`](https://docs.docker.com/reference/cli/docker/buildx/policy/)         | Commands for working with build policies         |
| [`docker buildx prune`](https://docs.docker.com/reference/cli/docker/buildx/prune/)           | Remove build cache                               |
| [`docker buildx rm`](https://docs.docker.com/reference/cli/docker/buildx/rm/)                 | Remove one or more builder instances             |
| [`docker buildx stop`](https://docs.docker.com/reference/cli/docker/buildx/stop/)             | Stop builder instance                            |
| [`docker buildx use`](https://docs.docker.com/reference/cli/docker/buildx/use/)               | Set the current builder instance                 |
| [`docker buildx version`](https://docs.docker.com/reference/cli/docker/buildx/version/)       | Show buildx version information                  |

----
url: https://docs.docker.com/ai/model-runner/ide-integrations/
----

# IDE and tool integrations

***

Table of contents

***

Docker Model Runner can serve as a local backend for popular AI coding assistants and development tools. This guide shows how to configure common tools to use models running in DMR.

## [Prerequisites](#prerequisites)

Before configuring any tool:

1. [Enable Docker Model Runner](https://docs.docker.com/ai/model-runner/get-started/#enable-docker-model-runner) in Docker Desktop or Docker Engine.

2. Enable TCP host access:

   * Docker Desktop: Enable **host-side TCP support** in Settings > AI, or run:
     ```console
     $ docker desktop enable model-runner --tcp 12434
     ```
   * Docker Engine: TCP is enabled by default on port 12434.

3. Pull a model:
   ```console
   $ docker model pull ai/qwen2.5-coder
   ```

> Tip
>
> The default context size for many models (such as `gpt-oss`) is 4,096 tokens, which is limiting for coding tasks. You can repackage it with a larger context window:
>
> ```console
> $ docker model pull gpt-oss
> $ docker model package --from ai/gpt-oss --context-size 32000 gpt-oss:32k
> ```
>
> Alternatively, models like ai/glm-4.7-flash, ai/qwen2.5-coder, and ai/devstral-small-2 come with 128K context by default and work without repackaging.

## [Cline (VS Code)](#cline-vs-code)

[Cline](https://github.com/cline/cline) is an AI coding assistant for VS Code.

### [Configuration](#configuration)

1. Open VS Code and go to the Cline extension settings.
2. Select **OpenAI Compatible** as the API provider.
3. Configure the following settings:

| Setting  | Value                                        |
| -------- | -------------------------------------------- |
| Base URL | `http://localhost:12434/engines/v1`          |
| API Key  | `not-needed` (or any placeholder value)      |
| Model ID | `ai/qwen2.5-coder` (or your preferred model) |

> Important
>
> The base URL must include `/engines/v1` at the end. Do not include a trailing slash.

### [Troubleshooting Cline](#troubleshooting-cline)

If Cline fails to connect:

1. Verify DMR is running:

   ```console
   $ docker model status
   ```

2. Test the endpoint directly:

   ```console
   $ curl http://localhost:12434/engines/v1/models
   ```

3. Check that CORS is configured if running a web-based version:

   * In Docker Desktop Settings > AI, add your origin to **CORS Allowed Origins**

## [Continue (VS Code / JetBrains)](#continue-vs-code--jetbrains)

[Continue](https://continue.dev) is an open-source AI code assistant that works with VS Code and JetBrains IDEs.

### [Configuration](#configuration-1)

Edit your Continue configuration file (`~/.continue/config.json`):

```json
{
  "models": [
    {
      "title": "Docker Model Runner",
      "provider": "openai",
      "model": "ai/qwen2.5-coder",
      "apiBase": "http://localhost:12434/engines/v1",
      "apiKey": "not-needed"
    }
  ]
}
```

### [Using Ollama provider](#using-ollama-provider)

Continue also supports the Ollama provider, which works with DMR:

```json
{
  "models": [
    {
      "title": "Docker Model Runner (Ollama)",
      "provider": "ollama",
      "model": "ai/qwen2.5-coder",
      "apiBase": "http://localhost:12434"
    }
  ]
}
```

## [Cursor](#cursor)

[Cursor](https://cursor.sh) is an AI-powered code editor.

### [Configuration](#configuration-2)

1. Open Cursor Settings (Cmd/Ctrl + ,).

2. Navigate to **Models** > **OpenAI API Key**.

3. Configure:

   | Setting                  | Value                               |
   | ------------------------ | ----------------------------------- |
   | OpenAI API Key           | `not-needed`                        |
   | Override OpenAI Base URL | `http://localhost:12434/engines/v1` |

4. In the model drop-down, enter your model name: `ai/qwen2.5-coder`

> Note
>
> Some Cursor features may require models with specific capabilities (e.g., function calling). Use capable models like `ai/qwen2.5-coder` or `ai/llama3.2` for best results.

## [Zed](#zed)

[Zed](https://zed.dev) is a high-performance code editor with AI features.

### [Configuration](#configuration-3)

Edit your Zed settings (`~/.config/zed/settings.json`):

```json
{
  "language_models": {
    "openai": {
      "api_url": "http://localhost:12434/engines/v1",
      "available_models": [
        {
          "name": "ai/qwen2.5-coder",
          "display_name": "Qwen 2.5 Coder (DMR)",
          "max_tokens": 8192
        }
      ]
    }
  }
}
```

## [Open WebUI](#open-webui)

[Open WebUI](https://github.com/open-webui/open-webui) provides a ChatGPT-like interface for local models.

See [Open WebUI integration](https://docs.docker.com/ai/model-runner/openwebui-integration/) for detailed setup instructions.

## [Aider](#aider)

[Aider](https://aider.chat) is an AI pair programming tool for the terminal.

### [Configuration](#configuration-4)

Set environment variables or use command-line flags:

```bash
export OPENAI_API_BASE=http://localhost:12434/engines/v1
export OPENAI_API_KEY=not-needed

aider --model openai/ai/qwen2.5-coder
```

Or in a single command:

```console
$ aider --openai-api-base http://localhost:12434/engines/v1 \
        --openai-api-key not-needed \
        --model openai/ai/qwen2.5-coder
```

## [LangChain](#langchain)

### [Python](#python)

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="not-needed",
    model="ai/qwen2.5-coder"
)

response = llm.invoke("Write a hello world function in Python")
print(response.content)
```

### [JavaScript/TypeScript](#javascripttypescript)

```typescript
import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  configuration: {
    baseURL: "http://localhost:12434/engines/v1",
  },
  apiKey: "not-needed",
  modelName: "ai/qwen2.5-coder",
});

const response = await model.invoke("Write a hello world function");
console.log(response.content);
```

## [LlamaIndex](#llamaindex)

```python
from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    api_base="http://localhost:12434/engines/v1",
    api_key="not-needed",
    model="ai/qwen2.5-coder"
)

response = llm.complete("Write a hello world function")
print(response.text)
```

## [OpenCode](#opencode)

[OpenCode](https://opencode.ai/) is an open-source coding assistant designed to integrate directly into developer workflows. It supports multiple model providers and exposes a flexible configuration system that makes it easy to switch between them.

See [Use OpenCode with Docker Model Runner](https://docs.docker.com/guides/opencode-model-runner/) for a task-focused guide that walks through model setup, configuration, and troubleshooting.

### [Configuration](#configuration-5)

1. Install OpenCode (see [docs](https://opencode.ai/docs/#install))
2. Reference DMR in your OpenCode configuration, either globally at `~/.config/opencode/opencode.json` or project specific with a `opencode.json` file in the root of your project
   ```json
   {
     "$schema": "https://opencode.ai/config.json",
     "provider": {
       "dmr": {
         "npm": "@ai-sdk/openai-compatible",
         "name": "Docker Model Runner",
         "options": {
           "baseURL": "http://localhost:12434/v1"
         },
         "models": {
           "ai/qwen2.5-coder": {
             "name": "ai/qwen2.5-coder"
           },
           "ai/llama3.2": {
             "name": "ai/llama3.2"
           }
         }
       }
     }
   }
   ```
3. Select the model you want in OpenCode

You can find more details in [this Docker Blog post](https://www.docker.com/blog/opencode-docker-model-runner-private-ai-coding/)

## [Claude Code](#claude-code)

[Claude Code](https://claude.com/product/claude-code) is [Anthropic's](https://www.anthropic.com/) command-line tool for agentic coding. It lives in your terminal, understands your codebase, and executes routine tasks, explains complex code, and handles Git workflows through natural language commands.

See [Use Claude Code with Docker Model Runner](https://docs.docker.com/guides/claude-code-model-runner/) for a task-focused guide that walks through model setup, configuration, and inspecting requests. To run Claude Code in an isolated Docker Sandbox against a local model, see [Run Claude Code in a Docker Sandbox with Docker Model Runner](https://docs.docker.com/guides/claude-code-sandbox-model-runner/).

### [Configuration](#configuration-6)

1. Install Claude Code (see [docs](https://code.claude.com/docs/en/quickstart#step-1-install-claude-code))

2. Use the `ANTHROPIC_BASE_URL` environment variable to point Claude Code at DMR. On Mac or Linux, you can do this, for example if you want to use the `gpt-oss:32k` model:

   ```bash
   ANTHROPIC_BASE_URL=http://localhost:12434 claude --model qwen2.5-coder
   ```

   On Windows (PowerShell) you can do it like this:

   ```powershell
   $env:ANTHROPIC_BASE_URL="http://localhost:12434"
   claude --model gpt-oss:32k
   ```

> Tip
>
> To avoid setting the variable each time, add it to your shell profile (`~/.bashrc`, `~/.zshrc`, or equivalent):
>
> ```shell
> export ANTHROPIC_BASE_URL=http://localhost:12434
> ```

You can find more details in [this Docker Blog post](https://www.docker.com/blog/run-claude-code-locally-docker-model-runner/)

> Note
>
> While the other integrations on this page use the [OpenAI-compatible API](/ai/model-runner/api-reference/#openai-compatible-api), DMR also exposes a [Anthropic-compatible API](/ai/model-runner/api-reference/#anthropic-compatible-api) used here.

## [Common issues](#common-issues)

### ["Connection refused" errors](#connection-refused-errors)

1. Ensure Docker Model Runner is enabled and running:

   ```console
   $ docker model status
   ```

2. Verify TCP access is enabled:

   ```console
   $ curl http://localhost:12434/engines/v1/models
   ```

3. Check if another service is using port 12434.

4. If you run your tool in WSL and want to connect to DMR on the host via `localhost`, this might not directly work. Configuring WSL to use [mirrored networking](https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking) can solve this.

### ["Model not found" errors](#model-not-found-errors)

1. Verify the model is pulled:

   ```console
   $ docker model list
   ```

2. Use the full model name including namespace (e.g., `ai/qwen2.5-coder`, not just `qwen2.5-coder`).

### [Slow responses or timeouts](#slow-responses-or-timeouts)

1. For first requests, models need to load into memory. Subsequent requests are faster.

2. Consider using a smaller model or adjusting the context size:

   ```console
   $ docker model configure --context-size 4096 ai/qwen2.5-coder
   ```

3. Check available system resources (RAM, GPU memory).

### [CORS errors (web-based tools)](#cors-errors-web-based-tools)

If using browser-based tools, add the origin to CORS allowed origins:

1. Docker Desktop: Settings > AI > CORS Allowed Origins
2. Add your tool's URL (e.g., `http://localhost:3000`)

## [Recommended models by use case](#recommended-models-by-use-case)

| Use case          | Recommended model     | Notes                                                  |
| ----------------- | --------------------- | ------------------------------------------------------ |
| Code completion   | `ai/qwen3-coder`      | Optimized for coding tasks with a large context window |
| Agentic coding    | `ai/devstral-small-2` | Good fit for tools such as Claude Code and OpenCode    |
| General assistant | `ai/llama3.2`         | Good balance of capabilities                           |
| Small/fast        | `ai/smollm2`          | Low resource usage                                     |
| Embeddings        | `ai/all-minilm`       | For RAG and semantic search                            |

## [What's next](#whats-next)

* [API reference](https://docs.docker.com/ai/model-runner/api-reference/) - Full API documentation
* [Configuration options](https://docs.docker.com/ai/model-runner/configuration/) - Tune model behavior
* [Open WebUI integration](https://docs.docker.com/ai/model-runner/openwebui-integration/) - Set up a web interface

----
url: https://docs.docker.com/reference/cli/docker/volume/inspect/
----

# docker volume inspect

***

| Description | Display detailed information on one or more volumes  |
| ----------- | ---------------------------------------------------- |
| Usage       | `docker volume inspect [OPTIONS] VOLUME [VOLUME...]` |

## [Description](#description)

Returns information about a volume. By default, this command renders all results in a JSON array. You can specify an alternate format to execute a given template for each result. Go's [text/template](https://pkg.go.dev/text/template) package describes all the details of the format.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                             |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --format`](#format) |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |

## [Examples](#examples)

```console
$ docker volume create myvolume

myvolume
```

Use the `docker volume inspect` comment to inspect the configuration of the volume:

```console
$ docker volume inspect myvolume
```

The output is in JSON format, for example:

```json
[
  {
    "CreatedAt": "2020-04-19T11:00:21Z",
    "Driver": "local",
    "Labels": {},
    "Mountpoint": "/var/lib/docker/volumes/8140a838303144125b4f54653b47ede0486282c623c3551fbc7f390cdc3e9cf5/_data",
    "Name": "myvolume",
    "Options": {},
    "Scope": "local"
  }
]
```

### [Format the output (--format)](#format)

Use the `--format` flag to format the output using a Go template, for example, to print the `Mountpoint` property:

```console
$ docker volume inspect --format '{{ .Mountpoint }}' myvolume

/var/lib/docker/volumes/myvolume/_data
```

----
url: https://docs.docker.com/build/cache/backends/azblob/
----

# Azure Blob Storage cache

***

Table of contents

***

Availability: Experimental

The `azblob` cache store uploads your resulting build cache to [Azure's blob storage service](https://azure.microsoft.com/en-us/services/storage/blobs/).

This cache storage backend is not supported with the default `docker` driver. To use this feature, create a new builder using a different driver. See [Build drivers](https://docs.docker.com/build/builders/drivers/) for more information.

## [Synopsis](#synopsis)

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=azblob,name=<cache-image>[,parameters...] \
  --cache-from type=azblob,name=<cache-image>[,parameters...] .
```

The following table describes the available CSV parameters that you can pass to `--cache-to` and `--cache-from`.

| Name                | Option                  | Type        | Default | Description                                                                                         |
| ------------------- | ----------------------- | ----------- | ------- | --------------------------------------------------------------------------------------------------- |
| `name`              | `cache-to`,`cache-from` | String      |         | Required. The name of the cache image.                                                              |
| `account_url`       | `cache-to`,`cache-from` | String      |         | Base URL of the storage account.                                                                    |
| `secret_access_key` | `cache-to`,`cache-from` | String      |         | Blob storage account key, see [authentication](#authentication).                                    |
| `mode`              | `cache-to`              | `min`,`max` | `min`   | Cache layers to export, see [cache mode](https://docs.docker.com/build/cache/backends/#cache-mode). |
| `ignore-error`      | `cache-to`              | Boolean     | `false` | Ignore errors caused by failed cache exports.                                                       |

## [Authentication](#authentication)

The `secret_access_key`, if left unspecified, is read from environment variables on the BuildKit server following the scheme for the [Azure Go SDK](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authentication). The environment variables are read from the server, not the Buildx client.

## [Further reading](#further-reading)

For an introduction to caching see [Docker build cache](https://docs.docker.com/build/cache/).

For more information on the `azblob` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#azure-blob-storage-cache-experimental).

----
url: https://docs.docker.com/dhi/core-concepts/attestations/
----

# Attestations

***

Table of contents

***

Docker Hardened Images (DHIs) and charts include comprehensive, signed security attestations that verify the image's build process, contents, and security posture. These attestations are a core part of secure software supply chain practices and help users validate that an image is trustworthy and policy-compliant.

## [What is an attestation?](#what-is-an-attestation)

An attestation is a signed statement that provides verifiable information about an image or chart, such as how it was built, what's inside it, and what security checks it has passed. Attestations are typically signed using Sigstore tooling (such as Cosign), making them tamper-evident and cryptographically verifiable.

Attestations follow standardized formats (like [in-toto](https://in-toto.io/), [CycloneDX](https://cyclonedx.org/), and [SLSA](https://slsa.dev/)) and are attached to the image or chart as OCI-compliant metadata. They can be generated automatically during image builds or added manually to document extra tests, scan results, or custom provenance.

## [Why are attestations important?](#why-are-attestations-important)

Attestations provide critical visibility into the software supply chain by:

* Documenting *what* went into an image (e.g., SBOMs)
* Verifying *how* it was built (e.g., build provenance)
* Capturing *what security scans* it has passed or failed (e.g., CVE reports, secrets scans, test results)
* Helping organizations enforce compliance and security policies
* Supporting runtime trust decisions and CI/CD policy gates

They are essential for meeting industry standards such as SLSA, and help teams reduce the risk of supply chain attacks by making build and security data transparent and verifiable.

## [How Docker Hardened Images and charts use attestations](#how-docker-hardened-images-and-charts-use-attestations)

All DHIs and charts are built using [SLSA Build Level 3](https://slsa.dev/spec/latest/levels) practices, and each image variant is published with a full set of signed attestations. These attestations allow users to:

* Verify that the image or chart was built from trusted sources in a secure environment
* View SBOMs in multiple formats to understand component-level details
* Review scan results to check for vulnerabilities or embedded secrets
* Confirm the build and deployment history of each image

Attestations are automatically published and associated with each DHI and chart. They can be inspected using tools like [Docker Scout](https://docs.docker.com/dhi/how-to/verify/) or [Cosign](https://docs.sigstore.dev/cosign/overview), and are consumable by CI/CD tooling or security platforms.

## [Image attestations](#image-attestations)

While every DHI variant includes a set of attestations, the attestations may vary based on the image variant. For example, some images may include a STIG scan attestation. The following table is a comprehensive list of all attestations that may be included with a DHI. To see which attestations are available for a specific image variant, including the specific predicate type URIs, use Docker Scout:

```console
$ docker scout attest list dhi.io/<image>:<tag>
```

For more details, see [Verify image attestations](https://docs.docker.com/dhi/how-to/verify/#verify-image-attestations).

| Attestation type          | Description                                                                                                                                                                                                          |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CycloneDX SBOM            | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing components, libraries, and versions.                                                                                             |
| STIG scan                 | Results of a STIG scan, with output in HTML and XCCDF formats.                                                                                                                                                       |
| CVEs (In-Toto format)     | A list of known vulnerabilities (CVEs) affecting the image's components, based on package and distribution scanning.                                                                                                 |
| VEX                       | A [Vulnerability Exploitability eXchange (VEX)](https://openvex.dev/) document that identifies vulnerabilities that do not apply to the image and explains why (e.g., not reachable or not present).                 |
| Scout health score        | A signed attestation from Docker Scout that summarizes the overall security and quality posture of the image.                                                                                                        |
| Scout provenance          | Provenance metadata generated by Docker Scout, including the source Git commit, build parameters, and environment details.                                                                                           |
| Scout SBOM                | An SBOM generated and signed by Docker Scout, including additional Docker-specific metadata.                                                                                                                         |
| Secrets scan              | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys.                                                                                                                   |
| Tests                     | A record of automated tests run against the image, such as functional checks or validation scripts.                                                                                                                  |
| Virus scan                | Results of antivirus scans performed on the image layers. For details, see [Malware scanning](https://docs.docker.com/dhi/explore/malware-scanning/).                                                                |
| CVEs (Scout format)       | A vulnerability report generated by Docker Scout, listing known CVEs and severity data.                                                                                                                              |
| SLSA provenance           | A standard [SLSA](https://slsa.dev/) provenance statement describing how the image was built, including build tool, parameters, and source.                                                                          |
| SLSA verification summary | A summary attestation indicating the image's compliance with SLSA requirements.                                                                                                                                      |
| SPDX SBOM                 | An SBOM in [SPDX](https://spdx.dev/) format, widely adopted in open-source ecosystems.                                                                                                                               |
| FIPS compliance           | An attestation that verifies the image uses FIPS 140-validated cryptographic modules.                                                                                                                                |
| DHI Image Sources         | Links to a corresponding source image containing all materials used to build the image, including package source code, Git repositories, and local files, ensuring compliance with open source license requirements. |

## [Package attestations](#package-attestations)

In addition to image-level attestations, Docker hardened packages also include their own attestations. These package-level attestations provide provenance and build information for individual packages within an image, allowing you to trace the supply chain at a granular level.

Package attestations include similar information as image attestations, such as SLSA provenance, showing how each package was built and what materials were used. You can extract package information from an image's attestations and then retrieve the package's own attestations recursively.

For detailed instructions on how to access and verify package attestations, see [Package attestations](https://docs.docker.com/dhi/how-to/hardened-packages/#package-attestations).

## [Helm chart attestations](#helm-chart-attestations)

Docker Hardened Image (DHI) charts also include comprehensive signed attestations that provide transparency and verification for your Kubernetes deployments. Like DHI container images, these charts are built following SLSA Build Level 3 practices and include extensive security metadata.

DHI Helm charts include the following attestations. To view the specific predicate type URIs for these attestations, use Docker Scout:

```console
$ docker scout attest list dhi.io/<chart>:<version>
```

For more details, see [Verify Helm chart attestations](https://docs.docker.com/dhi/how-to/verify/#verify-helm-chart-attestations-with-docker-scout).

| Attestation type      | Description                                                                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CycloneDX SBOM        | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing the chart itself and all container images and tools referenced by the chart.               |
| CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the container images and components referenced by the chart.                                                                  |
| Scout health score    | A signed attestation from Docker Scout that summarizes the overall security and quality posture of the chart and its referenced images.                                        |
| Scout provenance      | Provenance metadata generated by Docker Scout, including the chart source repository, build images used, and build parameters.                                                 |
| Scout SBOM            | An SBOM generated and signed by Docker Scout, including the chart and container images it references, with additional Docker-specific metadata.                                |
| Secrets scan          | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys, in the chart package.                                                       |
| Tests                 | A record of automated tests run against the chart to validate functionality and compatibility with referenced images.                                                          |
| Virus scan            | Results of antivirus scans performed on the chart package. For details, see [Malware scanning](https://docs.docker.com/dhi/explore/malware-scanning/).                         |
| CVEs (Scout format)   | A vulnerability report generated by Docker Scout, listing known CVEs and severity data for the chart's referenced images.                                                      |
| SLSA provenance       | A standard [SLSA](https://slsa.dev/) provenance statement describing how the chart was built, including build tool, source repository, referenced images, and build materials. |
| SPDX SBOM             | An SBOM in [SPDX](https://spdx.dev/) format, listing the chart and all container images and tools it references.                                                               |

## [View and verify attestations](#view-and-verify-attestations)

To view and verify attestations, see [Verify a Docker Hardened Image](https://docs.docker.com/dhi/how-to/verify/).

## [Add your own attestations](#add-your-own-attestations)

In addition to the comprehensive attestations provided by Docker Hardened Images, you can add your own signed attestations when building derivative images. This is especially useful if you’re building new applications on top of a DHI and want to maintain transparency, traceability, and trust in your software supply chain.

By attaching attestations such as SBOMs, build provenance, or custom metadata, you can meet compliance requirements, pass security audits, and support policy evaluation tools like Docker Scout.

These attestations can then be verified downstream using tools like Cosign or Docker Scout.

To learn how to attach custom attestations during the build process, see [Build attestations](https://docs.docker.com/build/metadata/attestations/).

----
url: https://docs.docker.com/engine/cli/filter/
----

# Filter commands

***

Table of contents

***

You can use the `--filter` flag to scope your commands. When filtering, the commands only include entries that match the pattern you specify.

## [Using filters](#using-filters)

The `--filter` flag expects a key-value pair separated by an operator.

```console
$ docker COMMAND --filter "KEY=VALUE"
```

The key represents the field that you want to filter on. The value is the pattern that the specified field must match. The operator can be either equals (`=`) or not equals (`!=`).

For example, the command `docker images --filter reference=alpine` filters the output of the `docker images` command to only print `alpine` images.

```console
$ docker images
REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
ubuntu       24.04     33a5cc25d22c   36 minutes ago   101MB
ubuntu       22.04     152dc042452c   36 minutes ago   88.1MB
alpine       3.21      a8cbb8c69ee7   40 minutes ago   8.67MB
alpine       latest    7144f7bab3d4   40 minutes ago   11.7MB
busybox      uclibc    3e516f71d880   48 minutes ago   2.4MB
busybox      glibc     7338d0c72c65   48 minutes ago   6.09MB
$ docker images --filter reference=alpine
REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
alpine       3.21      a8cbb8c69ee7   40 minutes ago   8.67MB
alpine       latest    7144f7bab3d4   40 minutes ago   11.7MB
```

The available fields (`reference` in this case) depend on the command you run. Some filters expect an exact match. Others handle partial matches. Some filters let you use regular expressions.

Refer to the [CLI reference description](#reference) for each command to learn about the supported filtering capabilities for each command.

## [Combining filters](#combining-filters)

You can combine multiple filters by passing multiple `--filter` flags. The following example shows how to print all images that match `alpine:latest` or `busybox` - a logical `OR`.

```console
$ docker images
REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
ubuntu       24.04     33a5cc25d22c   2 hours ago   101MB
ubuntu       22.04     152dc042452c   2 hours ago   88.1MB
alpine       3.21      a8cbb8c69ee7   2 hours ago   8.67MB
alpine       latest    7144f7bab3d4   2 hours ago   11.7MB
busybox      uclibc    3e516f71d880   2 hours ago   2.4MB
busybox      glibc     7338d0c72c65   2 hours ago   6.09MB
$ docker images --filter reference=alpine:latest --filter=reference=busybox
REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
alpine       latest    7144f7bab3d4   2 hours ago   11.7MB
busybox      uclibc    3e516f71d880   2 hours ago   2.4MB
busybox      glibc     7338d0c72c65   2 hours ago   6.09MB
```

### [Multiple negated filters](#multiple-negated-filters)

Some commands support negated filters on [labels](https://docs.docker.com/engine/manage-resources/labels/). Negated filters only consider results that don't match the specified patterns. The following command prunes all containers that aren't labeled `foo`.

```console
$ docker container prune --filter "label!=foo"
```

There's a catch in combining multiple negated label filters. Multiple negated filters create a single negative constraint - a logical `AND`. The following command prunes all containers except those labeled both `foo` and `bar`. Containers labeled either `foo` or `bar`, but not both, will be pruned.

```console
$ docker container prune --filter "label!=foo" --filter "label!=bar"
```

## [Reference](#reference)

For more information about filtering commands, refer to the CLI reference description for commands that support the `--filter` flag:

* [`docker config ls`](/reference/cli/docker/config/ls/)
* [`docker container prune`](/reference/cli/docker/container/prune/)
* [`docker image prune`](/reference/cli/docker/image/prune/)
* [`docker image ls`](/reference/cli/docker/image/ls/)
* [`docker network ls`](/reference/cli/docker/network/ls/)
* [`docker network prune`](/reference/cli/docker/network/prune/)
* [`docker node ls`](/reference/cli/docker/node/ls/)
* [`docker node ps`](/reference/cli/docker/node/ps/)
* [`docker plugin ls`](/reference/cli/docker/plugin/ls/)
* [`docker container ls`](/reference/cli/docker/container/ls/)
* [`docker search`](/reference/cli/docker/search/)
* [`docker secret ls`](/reference/cli/docker/secret/ls/)
* [`docker service ls`](/reference/cli/docker/service/ls/)
* [`docker service ps`](/reference/cli/docker/service/ps/)
* [`docker stack ps`](/reference/cli/docker/stack/ps/)
* [`docker system prune`](/reference/cli/docker/system/prune/)
* [`docker volume ls`](/reference/cli/docker/volume/ls/)
* [`docker volume prune`](/reference/cli/docker/volume/prune/)

----
url: https://docs.docker.com/ai/model-runner/
----

# Docker Model Runner

***

Table of contents

***

Requires: Docker Engine or Docker Desktop (Windows) 4.41+ or Docker Desktop (MacOS) 4.40+

For: See Requirements section below

Docker Model Runner (DMR) makes it easy to manage, run, and deploy AI models using Docker. Designed for developers, Docker Model Runner streamlines the process of pulling, running, and serving large language models (LLMs) and other AI models directly from Docker Hub, any OCI-compliant registry, or [Hugging Face](https://huggingface.co/).

With seamless integration into Docker Desktop and Docker Engine, you can serve models via OpenAI and Ollama-compatible APIs, package GGUF files as OCI Artifacts, and interact with models from both the command line and graphical interface.

Whether you're building generative AI applications, experimenting with machine learning workflows, or integrating AI into your software development lifecycle, Docker Model Runner provides a consistent, secure, and efficient way to work with AI models locally.

## [Key features](#key-features)

* [Pull and push models to and from Docker Hub or any OCI-compliant registry](https://hub.docker.com/u/ai)
* [Pull models from Hugging Face](https://huggingface.co/)
* Serve models on [OpenAI and Ollama-compatible APIs](https://docs.docker.com/ai/model-runner/api-reference/) for easy integration with existing apps
* Support for [llama.cpp, vLLM, and Diffusers inference engines](https://docs.docker.com/ai/model-runner/inference-engines/) (vLLM and Diffusers on Linux with NVIDIA GPUs)
* [Generate images from text prompts](https://docs.docker.com/ai/model-runner/inference-engines/#diffusers) using Stable Diffusion models with the Diffusers backend
* Package GGUF and Safetensors files as OCI Artifacts and publish them to any Container Registry
* Run and interact with AI models directly from the command line or from the Docker Desktop GUI
* [Connect to AI coding tools](https://docs.docker.com/ai/model-runner/ide-integrations/) like Cline, Continue, Cursor, and Aider
* [Configure context size and model parameters](https://docs.docker.com/ai/model-runner/configuration/) to tune performance
* [Set up Open WebUI](https://docs.docker.com/ai/model-runner/openwebui-integration/) for a ChatGPT-like web interface
* Manage local models and display logs
* Display prompt and response details
* Conversational context support for multi-turn interactions

## [Requirements](#requirements)

Docker Model Runner is supported on the following platforms:

Windows(amd64):

* NVIDIA GPUs
* NVIDIA drivers 576.57+

Windows(arm64):

* OpenCL for Adreno

* Qualcomm Adreno GPU (6xx series and later)

  > Note
  >
  > Some llama.cpp features might not be fully supported on the 6xx series.

- Apple Silicon

Docker Engine only:

* Supports CPU, NVIDIA (CUDA), AMD (ROCm), and Vulkan backends
* Requires NVIDIA driver 575.57.08+ when using NVIDIA GPUs

## [How Docker Model Runner works](#how-docker-model-runner-works)

Models are pulled from Docker Hub, an OCI-compliant registry, or [Hugging Face](https://huggingface.co/) the first time you use them and are stored locally. They load into memory only at runtime when a request is made, and unload when not in use to optimize resources. Because models can be large, the initial pull may take some time. After that, they're cached locally for faster access. You can interact with the model using [OpenAI and Ollama-compatible APIs](https://docs.docker.com/ai/model-runner/api-reference/).

### [Inference engines](#inference-engines)

Docker Model Runner supports three inference engines:

| Engine                                                                            | Best for                               | Model format     |
| --------------------------------------------------------------------------------- | -------------------------------------- | ---------------- |
| [llama.cpp](https://docs.docker.com/ai/model-runner/inference-engines/#llamacpp)  | Local development, resource efficiency | GGUF (quantized) |
| [vLLM](https://docs.docker.com/ai/model-runner/inference-engines/#vllm)           | Production, high throughput            | Safetensors      |
| [Diffusers](https://docs.docker.com/ai/model-runner/inference-engines/#diffusers) | Image generation (Stable Diffusion)    | Safetensors      |

llama.cpp is the default engine and works on all platforms. vLLM requires NVIDIA GPUs and is supported on Linux x86\_64 and Windows with WSL2. Diffusers enables image generation and requires NVIDIA GPUs on Linux (x86\_64 or ARM64). See [Inference engines](https://docs.docker.com/ai/model-runner/inference-engines/) for detailed comparison and setup.

### [Context size](#context-size)

Models have a configurable context size (context length) that determines how many tokens they can process. The default varies by model but is typically 2,048-8,192 tokens. You can adjust this per-model:

```console
$ docker model configure --context-size 8192 ai/qwen2.5-coder
```

See [Configuration options](https://docs.docker.com/ai/model-runner/configuration/) for details on context size and other parameters.

> Tip
>
> Using Testcontainers or Docker Compose? [Testcontainers for Java](https://java.testcontainers.org/modules/docker_model_runner/) and [Go](https://golang.testcontainers.org/modules/dockermodelrunner/), and [Docker Compose](https://docs.docker.com/ai/compose/models-and-compose/) support Docker Model Runner.

## [Known issues](#known-issues)

### [`docker model` is not recognised](#docker-model-is-not-recognised)

If you run a Docker Model Runner command and see:

```text
docker: 'model' is not a docker command
```

It means Docker can't find the plugin because it's not in the expected CLI plugins directory.

To fix this, create a symlink so Docker can detect it:

```console
$ ln -s /Applications/Docker.app/Contents/Resources/cli-plugins/docker-model ~/.docker/cli-plugins/docker-model
```

Once linked, rerun the command.

## [Privacy and data collection](#privacy-and-data-collection)

Docker Model Runner respects your privacy settings in Docker Desktop. Data collection is controlled by the **Send usage statistics** setting:

* **Disabled**: No usage data is collected

* **Enabled**: Only minimal, non-personal data is collected:

  * [Model names](https://github.com/docker/model-runner/blob/eb76b5defb1a598396f99001a500a30bbbb48f01/pkg/metrics/metrics.go#L96) (via HEAD requests to Docker Hub)
  * User agent information
  * Whether requests originate from the host or containers

When using Docker Model Runner with Docker Engine, HEAD requests to Docker Hub are made to track model names, regardless of any settings.

No prompt content, responses, or personally identifiable information is ever collected.

## [Share feedback](#share-feedback)

Thanks for trying out Docker Model Runner. To report bugs or request features, [open an issue on GitHub](https://github.com/docker/model-runner/issues). You can also give feedback through the **Give feedback** link next to the **Enable Docker Model Runner** setting.

## [Next steps](#next-steps)

* [Get started with DMR](https://docs.docker.com/ai/model-runner/get-started/) - Enable DMR and run your first model
* [API reference](https://docs.docker.com/ai/model-runner/api-reference/) - OpenAI and Ollama-compatible API documentation
* [Configuration options](https://docs.docker.com/ai/model-runner/configuration/) - Context size and runtime parameters
* [Inference engines](https://docs.docker.com/ai/model-runner/inference-engines/) - llama.cpp, vLLM, and Diffusers details
* [IDE integrations](https://docs.docker.com/ai/model-runner/ide-integrations/) - Connect Cline, Continue, Cursor, and more
* [Open WebUI integration](https://docs.docker.com/ai/model-runner/openwebui-integration/) - Set up a web chat interface

----
url: https://docs.docker.com/enterprise/security/
----

# Security for enterprises

***

Table of contents

***

Docker provides security guardrails for both administrators and developers.

If you're an administrator, you can enforce sign-in across Docker products for your developers, and scale, manage, and secure your instances of Docker Desktop with DevOps security controls like Enhanced Container Isolation and Registry Access Management.

## [For administrators](#for-administrators)

Explore the security features Docker offers to satisfy your company's security policies.

### [Enforce sign-in](/enterprise/security/enforce-sign-in/)

[Configure sign-in for members of your teams and organizations.](/enterprise/security/enforce-sign-in/)

### [Domain management](/enterprise/security/domain-management/)

[Identify uncaptured users in your organization.](/enterprise/security/domain-management/)

### [Docker Scout](/scout/)

[Explore how Docker Scout can help you create a more secure software supply chain.](/scout/)

### [SSO](/enterprise/security/single-sign-on/)

[Learn how to configure SSO for your company or organization.](/enterprise/security/single-sign-on/)

### [SCIM](/enterprise/security/provisioning/scim/)

[Set up SCIM to automatically provision and deprovision users.](/enterprise/security/provisioning/scim/)

### [Roles and permissions](/enterprise/security/roles-and-permissions/)

[Assign roles to individuals giving them different permissions within an organization.](/enterprise/security/roles-and-permissions/)

### [Private marketplace for Extensions (Beta)](/extensions/private-marketplace/)

[Learn how to configure and set up a private marketplace with a curated list of extensions for your Docker Desktop users.](/extensions/private-marketplace/)

### [Organization access tokens](/enterprise/security/access-tokens/)

[Create organization access tokens as an alternative to a password.](/enterprise/security/access-tokens/)

----
url: https://docs.docker.com/build/bake/targets/
----

# Bake targets

***

Table of contents

***

A target in a Bake file represents a build invocation. It holds all the information you would normally pass to a `docker build` command using flags.

docker-bake.hcl

```hcl
target "webapp" {
  dockerfile = "webapp.Dockerfile"
  tags = ["docker.io/username/webapp:latest"]
  context = "https://github.com/username/webapp"
}
```

To build a target with Bake, pass name of the target to the `bake` command.

```console
$ docker buildx bake webapp
```

You can build multiple targets at once by passing multiple target names to the `bake` command.

```console
$ docker buildx bake webapp api tests
```

## [Default target](#default-target)

If you don't specify a target when running `docker buildx bake`, Bake will build the target named `default`.

docker-bake.hcl

```hcl
target "default" {
  dockerfile = "webapp.Dockerfile"
  tags = ["docker.io/username/webapp:latest"]
  context = "https://github.com/username/webapp"
}
```

To build this target, run `docker buildx bake` without any arguments:

```console
$ docker buildx bake
```

## [Target properties](#target-properties)

The properties you can set for a target closely resemble the CLI flags for `docker build`, with a few additional properties that are specific to Bake.

The `dockerfile` property specifies the path to the Dockerfile for a target. If you also set a `context`, the `dockerfile` path resolves relative to that context.

docker-bake.hcl

```hcl
target "default" {
  context = "app"
  # resolves to app/src/www/Dockerfile
  dockerfile = "src/www/Dockerfile"
}
```

For all the properties you can set for a target, see the [Bake reference](/build/bake/reference#target).

## [Grouping targets](#grouping-targets)

You can group targets together using the `group` block. This is useful when you want to build multiple targets at once.

docker-bake.hcl

```hcl
group "all" {
  targets = ["webapp", "api", "tests"]
}

target "webapp" {
  dockerfile = "webapp.Dockerfile"
  tags = ["docker.io/username/webapp:latest"]
  context = "https://github.com/username/webapp"
}

target "api" {
  dockerfile = "api.Dockerfile"
  tags = ["docker.io/username/api:latest"]
  context = "https://github.com/username/api"
}

target "tests" {
  dockerfile = "tests.Dockerfile"
  contexts = {
    webapp = "target:webapp"
    api = "target:api"
  }
  output = ["type=local,dest=build/tests"]
  context = "."
}
```

To build all the targets in a group, pass the name of the group to the `bake` command.

```console
$ docker buildx bake all
```

## [Pattern matching for targets and groups](#pattern-matching-for-targets-and-groups)

Bake supports shell-style wildcard patterns when specifying target or grouped targets. This makes it easier to build multiple targets without listing each one explicitly.

Supported patterns:

* `*` matches any sequence of characters
* `?` matches any single character
* `[abc]` matches any character in brackets

> Note
>
> Always wrap wildcard patterns in quotes. Without quotes, your shell will expand the wildcard to match files in the current directory, causing errors.

Examples:

```console
# Match all targets starting with 'foo-'
$ docker buildx bake "foo-*"

# Match all targets
$ docker buildx bake "*"

# Matches: foo-baz, foo-caz, foo-daz, etc.
$ docker buildx bake "foo-?az"

# Matches: foo-bar, boo-bar
$ docker buildx bake "[fb]oo-bar"

# Matches: mtx-a-b-d, mtx-a-b-e, mtx-a-b-f
$ docker buildx bake "mtx-a-b-*"
```

You can also combine multiple patterns:

```console
$ docker buildx bake "foo*" "tests"
```

## [Additional resources](#additional-resources)

Refer to the following pages to learn more about Bake's features:

* Learn how to use [variables](https://docs.docker.com/build/bake/variables/) in Bake to make your build configuration more flexible.
* Learn how you can use matrices to build multiple images with different configurations in [Matrices](https://docs.docker.com/build/bake/matrices/).
* Head to the [Bake file reference](/build/bake/reference/) to learn about all the properties you can set in a Bake file, and its syntax.

----
url: https://docs.docker.com/reference/cli/docker/pass/get/
----

# docker pass get

***

| Description | Get a secret from a keystore. |
| ----------- | ----------------------------- |
| Usage       | `docker pass get NAME`        |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Retrieves a named secret from the local OS keychain. The secret value is masked in output.

----
url: https://docs.docker.com/reference/cli/sbx/policy/deny/
----

# sbx policy deny

| Description | Add a deny rule for sandboxes |
| ----------- | ----------------------------- |
| Usage       | `sbx policy deny COMMAND`     |

## [Description](#description)

Add a rule that blocks sandboxes from accessing specified resources.

Deny rules always take precedence over allow rules. If a resource matches both an allow and a deny rule, the request is blocked.

## [Commands](#commands)

| Command                                                                                     | Description                            |
| ------------------------------------------------------------------------------------------- | -------------------------------------- |
| [`sbx policy deny network`](https://docs.docker.com/reference/cli/sbx/policy/deny/network/) | Deny network access to specified hosts |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/reference/build-checks/multiple-instructions-disallowed/
----

# MultipleInstructionsDisallowed

***

Table of contents

***

## [Output](#output)

```text
Multiple CMD instructions should not be used in the same stage because only the last one will be used
```

## [Description](#description)

If you have multiple `CMD`, `HEALTHCHECK`, or `ENTRYPOINT` instructions in your Dockerfile, only the last occurrence is used. An image can only ever have one `CMD`, `HEALTHCHECK`, and `ENTRYPOINT`.

## [Examples](#examples)

❌ Bad: Duplicate instructions.

```dockerfile
FROM alpine
ENTRYPOINT ["echo", "Hello, Norway!"]
ENTRYPOINT ["echo", "Hello, Sweden!"]
# Only "Hello, Sweden!" will be printed
```

✅ Good: only one `ENTRYPOINT` instruction.

```dockerfile
FROM alpine
ENTRYPOINT ["echo", "Hello, Norway!\nHello, Sweden!"]
```

You can have both a regular, top-level `CMD` and a separate `CMD` for a `HEALTHCHECK` instruction.

✅ Good: only one top-level `CMD` instruction.

```dockerfile
FROM python:alpine
RUN apk add curl
HEALTHCHECK --interval=1s --timeout=3s \
  CMD ["curl", "-f", "http://localhost:8080"]
CMD ["python", "-m", "http.server", "8080"]
```

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/ls/
----

# docker mcp catalog ls

***

| Description | List all configured catalogs |
| ----------- | ---------------------------- |
| Usage       | `docker mcp catalog ls`      |

## [Description](#description)

List all configured catalogs including Docker's official catalog and any locally managed catalogs.

## [Options](#options)

| Option     | Default | Description                               |
| ---------- | ------- | ----------------------------------------- |
| `--format` |         | Output format. Supported: "json", "yaml". |

## [Examples](#examples)

# [List all catalogs](#list-all-catalogs)

docker mcp catalog ls

# [List catalogs in JSON format](#list-catalogs-in-json-format)

docker mcp catalog ls --format=json

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/pull/
----

# docker mcp profile pull

***

| Description | Pull profile from OCI registry            |
| ----------- | ----------------------------------------- |
| Usage       | `docker mcp profile pull <oci-reference>` |

## [Description](#description)

Pull profile from OCI registry

----
url: https://docs.docker.com/engine/logging/log_tags/
----

# Customize log driver output

***

***

The `tag` log option specifies how to format a tag that identifies the container's log messages. By default, the system uses the first 12 characters of the container ID. To override this behavior, specify a `tag` option:

```console
$ docker run --log-driver=fluentd --log-opt fluentd-address=myhost.local:24224 --log-opt tag="mailer"
```

Docker supports some special template markup you can use when specifying a tag's value:

| Markup             | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `{{.ID}}`          | The first 12 characters of the container ID.         |
| `{{.FullID}}`      | The full container ID.                               |
| `{{.Name}}`        | The container name.                                  |
| `{{.ImageID}}`     | The first 12 characters of the container's image ID. |
| `{{.ImageFullID}}` | The container's full image ID.                       |
| `{{.ImageName}}`   | The name of the image used by the container.         |
| `{{.DaemonName}}`  | The name of the Docker program (`docker`).           |

For example, specifying a `--log-opt tag="{{.ImageName}}/{{.Name}}/{{.ID}}"` value yields `syslog` log lines like:

```text
Aug  7 18:33:19 HOSTNAME hello-world/foobar/5790672ab6a0[9103]: Hello from Docker.
```

At startup time, the system sets the `container_name` field and `{{.Name}}` in the tags. If you use `docker rename` to rename a container, the new name isn't reflected in the log messages. Instead, these messages continue to use the original container name.

----
url: https://docs.docker.com/reference/cli/docker/compose/rm/
----

# docker compose rm

***

| Description | Removes stopped service containers         |
| ----------- | ------------------------------------------ |
| Usage       | `docker compose rm [OPTIONS] [SERVICE...]` |

## [Description](#description)

Removes stopped service containers.

By default, anonymous volumes attached to containers are not removed. You can override this with `-v`. To list all volumes, use `docker volume ls`.

Any data which is not in a volume is lost.

Running the command with no options also removes one-off containers created by `docker compose run`:

```console
$ docker compose rm
Going to remove djangoquickstart_web_run_1
Are you sure? [yN] y
Removing djangoquickstart_web_run_1 ... done
```

## [Options](#options)

| Option          | Default | Description                                         |
| --------------- | ------- | --------------------------------------------------- |
| `-f, --force`   |         | Don't ask to confirm removal                        |
| `-s, --stop`    |         | Stop the containers, if required, before removing   |
| `-v, --volumes` |         | Remove any anonymous volumes attached to containers |

----
url: https://docs.docker.com/scout/policy/ci/
----

# Evaluate policy compliance in CI

***

Table of contents

***

Adding Policy Evaluation to your continuous integration pipelines helps you detect and prevent cases where code changes would cause policy compliance to become worse compared to your baseline.

The recommended strategy for Policy Evaluation in a CI setting involves evaluating a local image and comparing the results to a baseline. If the policy compliance for the local image is worse than the specified baseline, the CI run fails with an error. If policy compliance is better or unchanged, the CI run succeeds.

This comparison is relative, meaning that it's only concerned with whether your CI image is better or worse than your baseline. It's not an absolute check to pass or fail all policies. By measuring relative to a baseline that you define, you can quickly see if a change has a positive or negative impact on policy compliance.

## [How it works](#how-it-works)

When you do Policy Evaluation in CI, you run a local policy evaluation on the image you build in your CI pipeline. To run a local evaluation, the image that you evaluate must exist in the image store where your CI workflow is being run. Either build or pull the image, and then run the evaluation.

To run policy evaluation and trigger failure if compliance for your local image is worse than your comparison baseline, you need to specify the image version to use as a baseline. You can hard-code a specific image reference, but a better solution is to use [environments](https://docs.docker.com/scout/integrations/environment/) to automatically infer the image version from an environment. The example that follows uses environments to compare the CI image with the image in the `production` environment.

## [Example](#example)

The following example on how to run policy evaluation in CI uses the [Docker Scout GitHub Action](https://github.com/marketplace/actions/docker-scout) to execute the `compare` command on an image built in CI. The compare command has a `to-env` input, which will run the comparison against an environment called `production`. The `exit-on` input is set to `policy`, meaning that the comparison fails only if policy compliance has worsened.

This example doesn't assume that you're using Docker Hub as your container registry. As a result, this workflow uses the `docker/login-action` twice:

* Once for authenticating to your container registry.
* Once more for authenticating to Docker to pull the analysis results of your `production` image.

If you use Docker Hub as your container registry, you only need to authenticate once.

> Note
>
> Due to a limitation in the Docker Engine, loading multi-platform images or images with attestations to the image store isn't supported.
>
> For the policy evaluation to work, you must load the image to the local image store of the runner. Ensure that you're building a single-platform image without attestations, and that you're loading the build results. Otherwise, the policy evaluation fails.

Also note the `pull-requests: write` permission for the job. The Docker Scout GitHub Action adds a pull request comment with the evaluation results by default, which requires this permission. For details, see [Pull Request Comments](https://github.com/docker/scout-action#pull-request-comments).

```yaml
name: Docker

on:
  push:
    tags: ["*"]
    branches:
      - "main"
  pull_request:
    branches: ["**"]

env:
  REGISTRY: docker.io
  IMAGE_NAME: IMAGE_NAME
  DOCKER_ORG: ORG

jobs:
  build:
    permissions:
      pull-requests: write

    runs-on: ubuntu-latest
    steps:
      - name: Log into registry ${{ env.REGISTRY }}
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ secrets.REGISTRY_USER }}
          password: ${{ secrets.REGISTRY_TOKEN }}
      
      - name: Setup Docker buildx
        uses: docker/setup-buildx-action@v4

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.IMAGE_NAME }}

      - name: Build image
        id: build-and-push
        uses: docker/build-push-action@v7
        with:
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          sbom: ${{ github.event_name != 'pull_request' }}
          provenance: ${{ github.event_name != 'pull_request' }}
          push: ${{ github.event_name != 'pull_request' }}
          load: ${{ github.event_name == 'pull_request' }}

      - name: Authenticate with Docker
        uses: docker/login-action@v4
        with:
          username: ${{ secrets.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PAT }}

      - name: Compare
        if: ${{ github.event_name == 'pull_request' }}
        uses: docker/scout-action@v1
        with:
          command: compare
          image: ${{ steps.meta.outputs.tags }}
          to-env: production
          platform: "linux/amd64"
          ignore-unchanged: true
          only-severities: critical,high
          organization: ${{ env.DOCKER_ORG }}
          exit-on: policy
```

The following screenshot shows what the GitHub PR comment looks like when a policy evaluation check fails because policy has become worse in the PR image compared to baseline.

This example has demonstrated how to run policy evaluation in CI with GitHub Actions. Docker Scout also supports other CI platforms. For more information, see [Docker Scout CI integrations](https://docs.docker.com/scout/integrations/#continuous-integration).

----
url: https://docs.docker.com/reference/cli/docker/compose/watch/
----

# docker compose watch

***

| Description | Watch build context for service and rebuild/refresh containers when files are updated |
| ----------- | ------------------------------------------------------------------------------------- |
| Usage       | `docker compose watch [SERVICE...]`                                                   |

## [Description](#description)

Watch build context for service and rebuild/refresh containers when files are updated

## [Options](#options)

| Option    | Default | Description                                   |
| --------- | ------- | --------------------------------------------- |
| `--no-up` |         | Do not build & start services before watching |
| `--prune` | `true`  | Prune dangling images on rebuild              |
| `--quiet` |         | hide build output                             |

----
url: https://docs.docker.com/ai/model-runner/configuration/
----

# Configuration options

***

Table of contents

***

Docker Model Runner provides several configuration options to tune model behavior, memory usage, and inference performance. This guide covers the key settings and how to apply them.

## [Context size (context length)](#context-size-context-length)

The context size determines the maximum number of tokens a model can process in a single request, including both the input prompt and generated output. This is one of the most important settings affecting memory usage and model capabilities.

### [Default context size](#default-context-size)

By default, Docker Model Runner uses a context size that balances capability with resource efficiency:

| Engine    | Default behavior                              |
| --------- | --------------------------------------------- |
| llama.cpp | 4096 tokens                                   |
| vLLM      | Uses the model's maximum trained context size |

> Note
>
> The actual default varies by model. Most models support between 2,048 and 8,192 tokens by default. Some newer models support 32K, 128K, or even larger contexts.

### [Configure context size](#configure-context-size)

You can adjust context size per model using the `docker model configure` command:

```console
$ docker model configure --context-size 8192 ai/qwen2.5-coder
```

Or in a Compose file:

```yaml
models:
  llm:
    model: ai/qwen2.5-coder
    context_size: 8192
```

### [Context size guidelines](#context-size-guidelines)

| Context size | Typical use case                          | Memory impact |
| ------------ | ----------------------------------------- | ------------- |
| 2,048        | Simple queries, short code snippets       | Low           |
| 4,096        | Standard conversations, medium code files | Moderate      |
| 8,192        | Long conversations, larger code files     | Higher        |
| 16,384+      | Extended documents, multi-file context    | High          |

> Important
>
> Larger context sizes require more memory (RAM/VRAM). If you experience out-of-memory errors, reduce the context size. As a rough guide, each additional 1,000 tokens requires approximately 100-500 MB of additional memory, depending on the model size.

### [Check a model's maximum context](#check-a-models-maximum-context)

To see a model's configuration including context size:

```console
$ docker model inspect ai/qwen2.5-coder
```

> Note
>
> The `docker model inspect` command shows the model's maximum supported context length (e.g., `gemma3.context_length`), not the configured context size. The configured context size is what you set with `docker model configure --context-size` and represents the actual limit used during inference, which should be less than or equal to the model's maximum supported context length.

## [Runtime flags](#runtime-flags)

Runtime flags let you pass parameters directly to the underlying inference engine. This provides fine-grained control over model behavior.

### [Using runtime flags](#using-runtime-flags)

Runtime flags can be provided through multiple mechanisms:

#### [Using Docker Compose](#using-docker-compose)

In a Compose file:

```yaml
models:
  llm:
    model: ai/qwen2.5-coder
    context_size: 4096
    runtime_flags:
      - "--temp"
      - "0.7"
      - "--top-p"
      - "0.9"
```

#### [Using Command Line](#using-command-line)

With the `docker model configure` command:

```console
$ docker model configure ai/qwen2.5-coder -- --temp 0.7 --top-p 0.9
```

### [Common llama.cpp parameters](#common-llamacpp-parameters)

These are the most commonly used llama.cpp parameters. You don't need to look up the llama.cpp documentation for typical use cases.

#### [Sampling parameters](#sampling-parameters)

| Flag               | Description                                                                  | Default | Range   |
| ------------------ | ---------------------------------------------------------------------------- | ------- | ------- |
| `--temp`           | Temperature for sampling. Lower = more deterministic, higher = more creative | 0.8     | 0.0-2.0 |
| `--top-k`          | Limit sampling to top K tokens. Lower = more focused                         | 40      | 1-100   |
| `--top-p`          | Nucleus sampling threshold. Lower = more focused                             | 0.9     | 0.0-1.0 |
| `--min-p`          | Minimum probability threshold                                                | 0.05    | 0.0-1.0 |
| `--repeat-penalty` | Penalty for repeating tokens                                                 | 1.1     | 1.0-2.0 |

**Example: Deterministic output (for code generation)**

```yaml
runtime_flags:
  - "--temp"
  - "0"
  - "--top-k"
  - "1"
```

**Example: Creative output (for storytelling)**

```yaml
runtime_flags:
  - "--temp"
  - "1.2"
  - "--top-p"
  - "0.95"
```

#### [Performance parameters](#performance-parameters)

| Flag              | Description                      | Default | Notes                                      |
| ----------------- | -------------------------------- | ------- | ------------------------------------------ |
| `--threads`       | CPU threads for generation       | Auto    | Set to number of performance cores         |
| `--threads-batch` | CPU threads for batch processing | Auto    | Usually same as `--threads`                |
| `--batch-size`    | Batch size for prompt processing | 512     | Higher = faster prompt processing          |
| `--mlock`         | Lock model in memory             | Off     | Prevents swapping, requires sufficient RAM |
| `--no-mmap`       | Disable memory mapping           | Off     | May improve performance on some systems    |

**Example: Optimized for multi-core CPU**

```yaml
runtime_flags:
  - "--threads"
  - "8"
  - "--batch-size"
  - "1024"
```

#### [GPU parameters](#gpu-parameters)

| Flag             | Description                | Default                | Notes                           |
| ---------------- | -------------------------- | ---------------------- | ------------------------------- |
| `--n-gpu-layers` | Layers to offload to GPU   | All (if GPU available) | Reduce if running out of VRAM   |
| `--main-gpu`     | GPU to use for computation | 0                      | For multi-GPU systems           |
| `--split-mode`   | How to split across GPUs   | layer                  | Options: `none`, `layer`, `row` |

**Example: Partial GPU offload (limited VRAM)**

```yaml
runtime_flags:
  - "--n-gpu-layers"
  - "20"
```

#### [Advanced parameters](#advanced-parameters)

| Flag                     | Description                       | Default       |
| ------------------------ | --------------------------------- | ------------- |
| `--rope-scaling`         | RoPE scaling method               | Auto          |
| `--rope-freq-base`       | RoPE base frequency               | Model default |
| `--rope-freq-scale`      | RoPE frequency scale              | Model default |
| `--no-prefill-assistant` | Disable assistant pre-fill        | Off           |
| `--reasoning-budget`     | Token budget for reasoning models | 0 (disabled)  |

### [vLLM parameters](#vllm-parameters)

When using the vLLM backend, different parameters are available.

Use `--hf_overrides` to pass HuggingFace model config overrides as JSON:

```console
$ docker model configure --hf_overrides '{"rope_scaling": {"type": "dynamic", "factor": 2.0}}' ai/model-vllm
```

## [Configuration presets](#configuration-presets)

Here are complete configuration examples for common use cases.

### [Code completion (fast, deterministic)](#code-completion-fast-deterministic)

```yaml
models:
  coder:
    model: ai/qwen2.5-coder
    context_size: 4096
    runtime_flags:
      - "--temp"
      - "0.1"
      - "--top-k"
      - "1"
      - "--batch-size"
      - "1024"
```

### [Chat assistant (balanced)](#chat-assistant-balanced)

```yaml
models:
  assistant:
    model: ai/llama3.2
    context_size: 8192
    runtime_flags:
      - "--temp"
      - "0.7"
      - "--top-p"
      - "0.9"
      - "--repeat-penalty"
      - "1.1"
```

### [Creative writing (high temperature)](#creative-writing-high-temperature)

```yaml
models:
  writer:
    model: ai/llama3.2
    context_size: 8192
    runtime_flags:
      - "--temp"
      - "1.2"
      - "--top-p"
      - "0.95"
      - "--repeat-penalty"
      - "1.0"
```

### [Long document analysis (large context)](#long-document-analysis-large-context)

```yaml
models:
  analyzer:
    model: ai/qwen2.5-coder:14B
    context_size: 32768
    runtime_flags:
      - "--mlock"
      - "--batch-size"
      - "2048"
```

### [Low memory system](#low-memory-system)

```yaml
models:
  efficient:
    model: ai/smollm2:360M-Q4_K_M
    context_size: 2048
    runtime_flags:
      - "--threads"
      - "4"
```

## [Environment-based configuration](#environment-based-configuration)

You can also configure models via environment variables in containers:

| Variable    | Description                             |
| ----------- | --------------------------------------- |
| `LLM_URL`   | Auto-injected URL of the model endpoint |
| `LLM_MODEL` | Auto-injected model identifier          |

See [Models and Compose](https://docs.docker.com/ai/compose/models-and-compose/) for details on how these are populated.

## [Reset configuration](#reset-configuration)

Configuration set via `docker model configure` persists until the model is removed. To reset configuration:

```console
$ docker model configure --context-size -1 ai/qwen2.5-coder
```

Using `-1` resets to the default value.

## [What's next](#whats-next)

* [Inference engines](https://docs.docker.com/ai/model-runner/inference-engines/) - Learn about llama.cpp and vLLM
* [API reference](https://docs.docker.com/ai/model-runner/api-reference/) - API parameters for per-request configuration
* [Models and Compose](https://docs.docker.com/ai/compose/models-and-compose/) - Configure models in Compose applications

----
url: https://docs.docker.com/reference/cli/docker/image/prune/
----

# docker image prune

***

| Description | Remove unused images           |
| ----------- | ------------------------------ |
| Usage       | `docker image prune [OPTIONS]` |

## [Description](#description)

Remove all dangling images. If `-a` is specified, also remove all images not referenced by any container.

## [Options](#options)

| Option                | Default | Description                                      |
| --------------------- | ------- | ------------------------------------------------ |
| `-a, --all`           |         | Remove all unused images, not just dangling ones |
| [`--filter`](#filter) |         | Provide filter values (e.g. `until=<timestamp>`) |
| `-f, --force`         |         | Do not prompt for confirmation                   |

## [Examples](#examples)

Example output:

```console
$ docker image prune -a

WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N] y
Deleted Images:
untagged: alpine:latest
untagged: alpine@sha256:3dcdb92d7432d56604d4545cbd324b14e647b313626d99b889d0626de158f73a
deleted: sha256:4e38e38c8ce0b8d9041a9c4fefe786631d1416225e13b0bfe8cfa2321aec4bba
deleted: sha256:4fe15f8d0ae69e169824f25f1d4da3015a48feeeeebb265cd2e328e15c6a869f
untagged: alpine:3.3
untagged: alpine@sha256:4fa633f4feff6a8f02acfc7424efd5cb3e76686ed3218abf4ca0fa4a2a358423
untagged: my-jq:latest
deleted: sha256:ae67841be6d008a374eff7c2a974cde3934ffe9536a7dc7ce589585eddd83aff
deleted: sha256:34f6f1261650bc341eb122313372adc4512b4fceddc2a7ecbb84f0958ce5ad65
deleted: sha256:cf4194e8d8db1cb2d117df33f2c75c0369c3a26d96725efb978cc69e046b87e7
untagged: my-curl:latest
deleted: sha256:b2789dd875bf427de7f9f6ae001940073b3201409b14aba7e5db71f408b8569e
deleted: sha256:96daac0cb203226438989926fc34dd024f365a9a8616b93e168d303cfe4cb5e9
deleted: sha256:5cbd97a14241c9cd83250d6b6fc0649833c4a3e84099b968dd4ba403e609945e
deleted: sha256:a0971c4015c1e898c60bf95781c6730a05b5d8a2ae6827f53837e6c9d38efdec
deleted: sha256:d8359ca3b681cc5396a4e790088441673ed3ce90ebc04de388bfcd31a0716b06
deleted: sha256:83fc9ba8fb70e1da31dfcc3c88d093831dbd4be38b34af998df37e8ac538260c
deleted: sha256:ae7041a4cc625a9c8e6955452f7afe602b401f662671cea3613f08f3d9343b35
deleted: sha256:35e0f43a37755b832f0bbea91a2360b025ee351d7309dae0d9737bc96b6d0809
deleted: sha256:0af941dd29f00e4510195dd00b19671bc591e29d1495630e7e0f7c44c1e6a8c0
deleted: sha256:9fc896fc2013da84f84e45b3096053eb084417b42e6b35ea0cce5a3529705eac
deleted: sha256:47cf20d8c26c46fff71be614d9f54997edacfe8d46d51769706e5aba94b16f2b
deleted: sha256:2c675ee9ed53425e31a13e3390bf3f539bf8637000e4bcfbb85ee03ef4d910a1

Total reclaimed space: 16.43 MB
```

### [Filtering (--filter)](#filter)

The filtering flag (`--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).

When multiple filters are provided, they are combined as follows:

* Multiple filters with **different keys** are combined using AND logic. An image must satisfy all filter conditions to be pruned.
* Multiple filters with the **same key** are combined using OR logic. An image is pruned if it matches any of the values for that key.

For example, `--filter "label=foo" --filter "until=24h"` prunes images that have the `foo` label **and** were created more than 24 hours ago. Conversely, `--filter "label=foo" --filter "label=bar"` prunes images that have **either** the `foo` **or** `bar` label.

The currently supported filters are:

* until (`<timestamp>`) - only remove images created before given timestamp
* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove images with (or without, in case `label!=...` is used) the specified labels.

The `until` filter can be Unix timestamps, date formatted timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local timezone on the daemon will be used if you do not provide either a `Z` or a `+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds\[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long.

The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`), which removes images with the specified labels. The other format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes images without the specified labels.

> Note
>
> **Predicting what will be removed**
>
> If you are using positive filtering (testing for the existence of a label or that a label has a specific value), you can use `docker image ls` with the same filtering syntax to see which images match your filter.
>
> However, if you are using negative filtering (testing for the absence of a label or that a label doesn't have a specific value), this type of filter doesn't work with `docker image ls` so you cannot easily predict which images will be removed. In addition, the confirmation prompt for `docker image prune` always warns that all dangling images will be removed, even if you are using `--filter`.

The following removes images created before `2017-01-04T00:00:00`:

```console
$ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}\t{{.Size}}'
REPOSITORY          TAG                 IMAGE ID            CREATED AT                      SIZE
foo                 latest              2f287ac753da        2017-01-04 13:42:23 -0800 PST   3.98 MB
alpine              latest              88e169ea8f46        2016-12-27 10:17:25 -0800 PST   3.98 MB
busybox             latest              e02e811dd08f        2016-10-07 14:03:58 -0700 PDT   1.09 MB

$ docker image prune -a --force --filter "until=2017-01-04T00:00:00"

Deleted Images:
untagged: alpine:latest
untagged: alpine@sha256:dfbd4a3a8ebca874ebd2474f044a0b33600d4523d03b0df76e5c5986cb02d7e8
untagged: busybox:latest
untagged: busybox@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912
deleted: sha256:e02e811dd08fd49e7f6032625495118e63f597eb150403d02e3238af1df240ba
deleted: sha256:e88b3f82283bc59d5e0df427c824e9f95557e661fcb0ea15fb0fb6f97760f9d9

Total reclaimed space: 1.093 MB

$ docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}\t{{.Size}}'

REPOSITORY          TAG                 IMAGE ID            CREATED AT                      SIZE
foo                 latest              2f287ac753da        2017-01-04 13:42:23 -0800 PST   3.98 MB
```

The following removes images created more than 10 days (`240h`) ago:

```console
$ docker images

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
foo                 latest              2f287ac753da        14 seconds ago      3.98 MB
alpine              latest              88e169ea8f46        8 days ago          3.98 MB
debian              jessie              7b0a06c805e8        2 months ago        123 MB
busybox             latest              e02e811dd08f        2 months ago        1.09 MB
golang              1.7.0               138c2e655421        4 months ago        670 MB

$ docker image prune -a --force --filter "until=240h"

Deleted Images:
untagged: golang:1.7.0
untagged: golang@sha256:6765038c2b8f407fd6e3ecea043b44580c229ccfa2a13f6d85866cf2b4a9628e
deleted: sha256:138c2e6554219de65614d88c15521bfb2da674cbb0bf840de161f89ff4264b96
deleted: sha256:ec353c2e1a673f456c4b78906d0d77f9d9456cfb5229b78c6a960bfb7496b76a
deleted: sha256:fe22765feaf3907526b4921c73ea6643ff9e334497c9b7e177972cf22f68ee93
deleted: sha256:ff845959c80148421a5c3ae11cc0e6c115f950c89bc949646be55ed18d6a2912
deleted: sha256:a4320831346648c03db64149eafc83092e2b34ab50ca6e8c13112388f25899a7
deleted: sha256:4c76020202ee1d9709e703b7c6de367b325139e74eebd6b55b30a63c196abaf3
deleted: sha256:d7afd92fb07236c8a2045715a86b7d5f0066cef025018cd3ca9a45498c51d1d6
deleted: sha256:9e63c5bce4585dd7038d830a1f1f4e44cb1a1515b00e620ac718e934b484c938
untagged: debian:jessie
untagged: debian@sha256:c1af755d300d0c65bb1194d24bce561d70c98a54fb5ce5b1693beb4f7988272f
deleted: sha256:7b0a06c805e8f23807fb8856621c60851727e85c7bcb751012c813f122734c8d
deleted: sha256:f96222d75c5563900bc4dd852179b720a0885de8f7a0619ba0ac76e92542bbc8

Total reclaimed space: 792.6 MB

$ docker images

REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
foo                 latest              2f287ac753da        About a minute ago   3.98 MB
alpine              latest              88e169ea8f46        8 days ago           3.98 MB
busybox             latest              e02e811dd08f        2 months ago         1.09 MB
```

The following example removes images with the label `deprecated`:

```console
$ docker image prune --filter="label=deprecated"
```

The following example removes images with the label `maintainer` set to `john`:

```console
$ docker image prune --filter="label=maintainer=john"
```

This example removes images which have no `maintainer` label:

```console
$ docker image prune --filter="label!=maintainer"
```

This example removes images which have a maintainer label not set to `john`:

```console
$ docker image prune --filter="label!=maintainer=john"
```

> Note
>
> You are prompted for confirmation before the `prune` removes anything, but you are not shown a list of what will potentially be removed. In addition, `docker image ls` doesn't support negative filtering, so it difficult to predict what images will actually be removed.

----
url: https://docs.docker.com/reference/api/engine/sdk/
----

# Develop with Docker Engine SDKs

***

Table of contents

***

Docker provides an API for interacting with the Docker daemon (called the Docker Engine API), as well as SDKs for Go and Python. The SDKs allow you to efficiently build and scale Docker apps and solutions. If Go or Python don't work for you, you can use the Docker Engine API directly.

The Docker Engine API is a RESTful API accessed by an HTTP client such as `wget` or `curl`, or the HTTP library which is part of most modern programming languages.

## [Install the SDKs](#install-the-sdks)

Use the following commands to install the Go or Python SDK. Both SDKs can be installed and coexist together.

### [Go SDK](#go-sdk)

```console
$ go get github.com/moby/moby/client
```

The client requires a recent version of Go. Run `go version` and ensure that you're running a currently supported version of Go.

For more information, see [Go client reference](https://pkg.go.dev/github.com/moby/moby/client).

### [Python SDK](#python-sdk)

* Recommended: Run `pip install docker`.

* If you can't use `pip`:

  1. [Download the package directly](https://pypi.python.org/pypi/docker/).
  2. Extract it and change to the extracted directory.
  3. Run `python setup.py install`.

For more information, see [Docker Engine Python SDK reference](https://docker-py.readthedocs.io/).

> Note
>
> Docker Desktop for Linux users
>
> Docker Desktop for Linux uses a per-user socket instead of the system-wide `/var/run/docker.sock`. To use Docker SDKs with Docker Desktop for Linux, set the `DOCKER_HOST` environment variable:
>
> ```bash
> export DOCKER_HOST=unix://$HOME/.docker/desktop/docker.sock
> ```
>
> For more details, see [the Linux FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/linuxfaqs/#how-do-i-use-docker-sdks-with-docker-desktop-for-linux).

## [View the API reference](#view-the-api-reference)

You can [view the reference for the latest version of the API](/reference/api/engine/latest/) or [choose a specific version](/reference/api/engine/#api-version-matrix).

## [Versioned API and SDK](#versioned-api-and-sdk)

The version of the Docker Engine API you should use depends on the version of your Docker daemon and Docker client. See the [versioned API and SDK](/reference/api/engine/#versioned-api-and-sdk) section in the API documentation for details.

## [SDK and API quickstart](#sdk-and-api-quickstart)

Use the following guidelines to choose the SDK or API version to use in your code:

* If you're starting a new project, use the [latest version](/reference/api/engine/latest/), but use API version negotiation or specify the version you are using. This helps prevent surprises.
* If you need a new feature, update your code to use at least the minimum version that supports the feature, and prefer the latest version you can use.
* Otherwise, continue to use the version that your code is already using.

As an example, the `docker run` command can be implemented using the Docker API directly, or using the Python or Go SDK.

```go
package main

import (
	"context"
	"io"
	"os"

	"github.com/moby/moby/api/pkg/stdcopy"
	"github.com/moby/moby/api/types/container"
	"github.com/moby/moby/client"
)

func main() {
	ctx := context.Background()
	apiClient, err := client.New(client.FromEnv)
	if err != nil {
		panic(err)
	}
	defer apiClient.Close()

	reader, err := apiClient.ImagePull(ctx, "docker.io/library/alpine", client.ImagePullOptions{})
	if err != nil {
		panic(err)
	}
	io.Copy(os.Stdout, reader)

	resp, err := apiClient.ContainerCreate(ctx, client.ContainerCreateOptions{
		Image: "alpine",
		Config: &container.Config{
			Cmd: []string{"echo", "hello world"},
		},
	})
	if err != nil {
		panic(err)
	}

	if _, err := apiClient.ContainerStart(ctx, resp.ID, client.ContainerStartOptions{}); err != nil {
		panic(err)
	}

	wait := apiClient.ContainerWait(ctx, resp.ID, client.ContainerWaitOptions{})
	select {
	case err := <-wait.Error:
		if err != nil {
			panic(err)
		}
	case <-wait.Result:
	}

	out, err := apiClient.ContainerLogs(ctx, resp.ID, client.ContainerLogsOptions{ShowStdout: true})
	if err != nil {
		panic(err)
	}

	stdcopy.StdCopy(os.Stdout, os.Stderr, out)
}
```

```python
import docker
client = docker.from_env()
print(client.containers.run("alpine", ["echo", "hello", "world"]))
```

```console
$ curl --unix-socket /var/run/docker.sock -H "Content-Type: application/json" \
  -d '{"Image": "alpine", "Cmd": ["echo", "hello world"]}' \
  -X POST http://localhost/v1.54/containers/create
{"Id":"1c6594faf5","Warnings":null}

$ curl --unix-socket /var/run/docker.sock -X POST http://localhost/v1.54/containers/1c6594faf5/start

$ curl --unix-socket /var/run/docker.sock -X POST http://localhost/v1.54/containers/1c6594faf5/wait
{"StatusCode":0}

$ curl --unix-socket /var/run/docker.sock "http://localhost/v1.54/containers/1c6594faf5/logs?stdout=1"
hello world
```

When using cURL to connect over a Unix socket, the hostname is not important. The previous examples use `localhost`, but any hostname would work.

> Important
>
> The previous examples assume you're using cURL 7.50.0 or above. Older versions of cURL used a [non-standard URL notation](https://github.com/moby/moby/issues/17960) when using a socket connection.
>
> If you're' using an older version of cURL, use `http:/<API version>/` instead, for example: `http:/v1.54/containers/1c6594faf5/start`.

For more examples, take a look at the [SDK examples](https://docs.docker.com/reference/api/engine/sdk/examples/).

## [Unofficial libraries](#unofficial-libraries)

There are a number of community supported libraries available for other languages. They haven't been tested by Docker, so if you run into any issues, file them with the library maintainers.

| Language | Library                                                                     |
| -------- | --------------------------------------------------------------------------- |
| C        | [libdocker](https://github.com/danielsuo/libdocker)                         |
| C#       | [Docker.DotNet](https://github.com/testcontainers/Docker.DotNet)            |
| C++      | [lasote/docker\_client](https://github.com/lasote/docker_client)            |
| Clojure  | [clj-docker-client](https://github.com/into-docker/clj-docker-client)       |
| Clojure  | [contajners](https://github.com/lispyclouds/contajners)                     |
| Dart     | [bwu\_docker](https://github.com/bwu-dart/bwu_docker)                       |
| Erlang   | [erldocker](https://github.com/proger/erldocker)                            |
| Gradle   | [gradle-docker-plugin](https://github.com/gesellix/gradle-docker-plugin)    |
| Groovy   | [docker-client](https://github.com/gesellix/docker-client)                  |
| Haskell  | [docker-hs](https://github.com/denibertovic/docker-hs)                      |
| Java     | [docker-client](https://github.com/spotify/docker-client)                   |
| Java     | [docker-java](https://github.com/docker-java/docker-java)                   |
| Java     | [docker-java-api](https://github.com/amihaiemil/docker-java-api)            |
| Java     | [jocker](https://github.com/ndeloof/jocker)                                 |
| NodeJS   | [dockerode](https://github.com/apocas/dockerode)                            |
| NodeJS   | [harbor-master](https://github.com/arhea/harbor-master)                     |
| NodeJS   | [the-moby-effect](https://github.com/leonitousconforti/the-moby-effect)     |
| Perl     | [Eixo::Docker](https://github.com/alambike/eixo-docker)                     |
| PHP      | [Docker-PHP](https://github.com/docker-php/docker-php)                      |
| Ruby     | [docker-api](https://github.com/swipely/docker-api)                         |
| Rust     | [bollard](https://github.com/fussybeaver/bollard)                           |
| Rust     | [docker-rust](https://github.com/abh1nav/docker-rust)                       |
| Rust     | [shiplift](https://github.com/softprops/shiplift)                           |
| Scala    | [tugboat](https://github.com/softprops/tugboat)                             |
| Scala    | [reactive-docker](https://github.com/almoehi/reactive-docker)               |
| Swift    | [docker-client-swift](https://github.com/valeriomazzeo/docker-client-swift) |

----
url: https://docs.docker.com/reference/cli/docker/dhi/catalog/get/
----

# docker dhi catalog get

***

| Description | Get details of a Docker Hardened Image |
| ----------- | -------------------------------------- |
| Usage       | `docker dhi catalog get <name>`        |

## [Description](#description)

Get detailed information about a Docker Hardened Image or Helm chart, including available tags and CVE counts

## [Options](#options)

| Option   | Default | Description           |
| -------- | ------- | --------------------- |
| `--json` |         | Output in JSON format |

----
url: https://docs.docker.com/reference/cli/docker/buildx/ls/
----

# docker buildx ls

***

| Description | List builder instances |
| ----------- | ---------------------- |
| Usage       | `docker buildx ls`     |

## [Description](#description)

Lists all builder instances and the nodes for each instance.

```console
$ docker buildx ls
NAME/NODE           DRIVER/ENDPOINT                   STATUS    BUILDKIT   PLATFORMS
elated_tesla*       docker-container
 \_ elated_tesla0    \_ unix:///var/run/docker.sock   running   v0.10.3    linux/amd64
 \_ elated_tesla1    \_ ssh://ubuntu@1.2.3.4          running   v0.10.3    linux/arm64*, linux/arm/v7, linux/arm/v6
default             docker
 \_ default          \_ default                       running   v0.8.2     linux/amd64
```

Each builder has one or more nodes associated with it. The current builder's name is marked with a `*` in `NAME/NODE` and explicit node to build against for the target platform marked with a `*` in the `PLATFORMS` column.

## [Options](#options)

| Option                | Default | Description                                             |
| --------------------- | ------- | ------------------------------------------------------- |
| [`--format`](#format) | `table` | Format the output                                       |
| `--no-trunc`          |         | Don't truncate output                                   |
| `--timeout`           | `20s`   | Override the default timeout for loading builder status |

## [Examples](#examples)

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints builder instances output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder       | Description                                 |
| ----------------- | ------------------------------------------- |
| `.Name`           | Builder or node name                        |
| `.DriverEndpoint` | Driver (for builder) or Endpoint (for node) |
| `.LastActivity`   | Builder last activity                       |
| `.Status`         | Builder or node status                      |
| `.Buildkit`       | BuildKit version of the node                |
| `.Platforms`      | Available node's platforms                  |
| `.Error`          | Error                                       |
| `.Builder`        | Builder object                              |

When using the `--format` option, the `ls` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `Name` and `DriverEndpoint` entries separated by a colon (`:`):

```console
$ docker buildx ls --format "{{.Name}}: {{.DriverEndpoint}}"
elated_tesla: docker-container
elated_tesla0: unix:///var/run/docker.sock
elated_tesla1: ssh://ubuntu@1.2.3.4
default: docker
default: default
```

The `Builder` placeholder can be used to access the builder object and its fields. For example, the following template outputs the builder's and nodes' names with their respective endpoints:

```console
$ docker buildx ls --format "{{.Builder.Name}}: {{range .Builder.Nodes}}\n  {{.Name}}: {{.Endpoint}}{{end}}"
elated_tesla:
  elated_tesla0: unix:///var/run/docker.sock
  elated_tesla1: ssh://ubuntu@1.2.3.4
default: docker
  default: default
```

----
url: https://docs.docker.com/guides/testcontainers-nodejs-getting-started/write-tests/
----

# Write tests with Testcontainers

***

***

Create `src/customer-repository.test.js` with the test:

```javascript
const { Client } = require("pg");
const { PostgreSqlContainer } = require("@testcontainers/postgresql");
const {
  createCustomerTable,
  createCustomer,
  getCustomers,
} = require("./customer-repository");

describe("Customer Repository", () => {
  jest.setTimeout(60000);

  let postgresContainer;
  let postgresClient;

  beforeAll(async () => {
    postgresContainer = await new PostgreSqlContainer().start();
    postgresClient = new Client({
      connectionString: postgresContainer.getConnectionUri(),
    });
    await postgresClient.connect();
    await createCustomerTable(postgresClient);
  });

  afterAll(async () => {
    await postgresClient.end();
    await postgresContainer.stop();
  });

  it("should create and return multiple customers", async () => {
    const customer1 = { id: 1, name: "John Doe" };
    const customer2 = { id: 2, name: "Jane Doe" };

    await createCustomer(postgresClient, customer1);
    await createCustomer(postgresClient, customer2);

    const customers = await getCustomers(postgresClient);
    expect(customers).toEqual([customer1, customer2]);
  });
});
```

Here's what the test does:

* The `beforeAll` block starts a real PostgreSQL container using `PostgreSqlContainer`. It then creates a `pg` client connected to the container and sets up the `customers` table.
* The `afterAll` block closes the client connection and stops the container.
* The test inserts two customers, fetches all customers, and asserts the results match.

The test timeout is set to 60 seconds to allow time for the container to start on the first run (when the Docker image needs to be pulled).

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-nodejs-getting-started/run-tests/)

----
url: https://docs.docker.com/guides/rust/configure-ci-cd/
----

# Configure CI/CD for your Rust application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete the previous sections of this guide, starting with [Develop your Rust application](https://docs.docker.com/guides/rust/develop/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

   ```console
   $ git remote set-url origin https://github.com/your-username/your-repository.git
   ```

7. Run the following commands to stage, commit, and push your local repository to GitHub.

   ```console
   $ git add -A
   $ git commit -m "my commit"
   $ git push -u origin main
   ```

## [Step two: Set up the workflow](#step-two-set-up-the-workflow)

Set up your GitHub Actions workflow for building, testing, and pushing the image to Docker Hub.

1. Go to your repository on GitHub and then select the **Actions** tab.

2. Select **set up a workflow yourself**.

   This takes you to a page for creating a new GitHub actions workflow file in your repository, under `.github/workflows/main.yml` by default.

3. In the editor window, copy and paste the following YAML configuration.

   ```yaml
   name: ci

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Login to Docker Hub
           uses: docker/login-action@v4
           with:
             username: ${{ vars.DOCKER_USERNAME }}
             password: ${{ secrets.DOCKERHUB_TOKEN }}

         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v4

         - name: Build and push
           uses: docker/build-push-action@v7
           with:
             push: true
             tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
   ```

In this section, you learned how to set up a GitHub Actions workflow for your Rust application.

Related information:

* [Introduction to GitHub Actions](https://docs.docker.com/guides/gha/)
* [Docker Build GitHub Actions](https://docs.docker.com/build/ci/github-actions/)
* [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)

## [Next steps](#next-steps)

Next, learn how you can locally test and debug your workloads on Kubernetes before deploying.

[Test your Rust deployment »](https://docs.docker.com/guides/rust/deploy/)

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/e2b-sandboxes/
----

# E2B sandboxes

***

Table of contents

***

Docker has partnered with [E2B](https://e2b.dev/), a provider of secure cloud sandboxes for AI agents. E2B sandboxes include direct access to Docker's [MCP Catalog](https://hub.docker.com/mcp), a collection of 200+ tools from publishers including GitHub, Notion, and Stripe.

When you create a sandbox, you specify which MCP tools it should access. E2B launches these tools and provides access through the Docker MCP Gateway.

## [Example: Using GitHub and Notion MCP server](#example-using-github-and-notion-mcp-server)

This example demonstrates how to connect multiple MCP servers in an E2B sandbox. You'll analyze data in Notion and create GitHub issues using Claude.

### [Prerequisites](#prerequisites)

Before you begin, make sure you have the following:

* [E2B account](https://e2b.dev/docs/quickstart) with API access

* Anthropic API key for Claude

  > Note
  >
  > This example uses Claude Code, which is pre-installed in E2B sandboxes. However, you can adapt the example to work with other AI assistants of your choice. See [E2B's MCP documentation](https://e2b.dev/docs/mcp/quickstart) for alternative connection methods.

* Node.js 18+ installed on your machine

* Notion account with:

  * A database containing sample data
  * [Integration token](https://www.notion.com/help/add-and-manage-connections-with-the-api)

* GitHub account with:

  * A repository for testing
  * Personal access token with `repo` scope

### [Set up your environment](#set-up-your-environment)

Create a new directory and initialize a Node.js project:

```console
$ mkdir mcp-e2b-quickstart
$ cd mcp-e2b-quickstart
$ npm init -y
```

Configure your project for ES modules by updating `package.json`:

```json
{
  "name": "mcp-e2b-quickstart",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  }
}
```

Install required dependencies:

```console
$ npm install e2b dotenv
```

Create a `.env` file with your credentials:

```console
$ cat > .env << 'EOF'
E2B_API_KEY=your_e2b_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
NOTION_INTEGRATION_TOKEN=ntn_your_notion_integration_token_here
GITHUB_TOKEN=ghp_your_github_pat_here
EOF
```

Protect your credentials:

```console
$ echo ".env" >> .gitignore
$ echo "node_modules/" >> .gitignore
```

### [Create an E2B sandbox with MCP servers](#create-an-e2b-sandbox-with-mcp-servers)

Create a file named `index.ts`:

```typescript
import "dotenv/config";
import { Sandbox } from "e2b";

async function quickstart(): Promise<void> {
  console.log("Creating E2B sandbox with Notion and GitHub MCP servers...\n");

  const sbx: Sandbox = await Sandbox.create({
    envs: {
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY as string,
    },
    mcp: {
      notion: {
        internalIntegrationToken: process.env
          .NOTION_INTEGRATION_TOKEN as string,
      },
      githubOfficial: {
        githubPersonalAccessToken: process.env.GITHUB_TOKEN as string,
      },
    },
  });

  const mcpUrl = sbx.getMcpUrl();
  const mcpToken = await sbx.getMcpToken();

  console.log("Sandbox created successfully!");
  console.log(`MCP Gateway URL: ${mcpUrl}\n`);

  // Wait for MCP initialization
  await new Promise<void>((resolve) => setTimeout(resolve, 1000));

  // Connect Claude to MCP gateway
  console.log("Connecting Claude to MCP gateway...");
  await sbx.commands.run(
    `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`,
    {
      timeoutMs: 0,
      onStdout: console.log,
      onStderr: console.log,
    },
  );

  console.log("\nConnection successful! Cleaning up...");
  await sbx.kill();
}

quickstart().catch(console.error);
```

Run the script:

```console
$ npx tsx index.ts
```

Create a file named `index.py`:

```python
import os
import asyncio
from dotenv import load_dotenv
from e2b import Sandbox

load_dotenv()

async def quickstart():
    print("Creating E2B sandbox with Notion and GitHub MCP servers...\n")

    sbx = await Sandbox.beta_create(
        envs={
            "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
        },
        mcp={
            "notion": {
                "internalIntegrationToken": os.getenv("NOTION_INTEGRATION_TOKEN"),
            },
            "githubOfficial": {
                "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
            },
        },
    )

    mcp_url = sbx.beta_get_mcp_url()
    mcp_token = await sbx.beta_get_mcp_token()

    print("Sandbox created successfully!")
    print(f"MCP Gateway URL: {mcp_url}\n")

    # Wait for MCP initialization
    await asyncio.sleep(1)

    # Connect Claude to MCP gateway
    print("Connecting Claude to MCP gateway...")

    def on_stdout(output):
        print(output, end='')

    def on_stderr(output):
        print(output, end='')

    await sbx.commands.run(
        f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"',
        timeout_ms=0,
        on_stdout=on_stdout,
        on_stderr=on_stderr
    )

    print("\nConnection successful! Cleaning up...")
    await sbx.kill()

if __name__ == "__main__":
    try:
        asyncio.run(quickstart())
    except Exception as e:
        print(f"Error: {e}")
```

Run the script:

```console
$ python index.py
```

You should see:

```console
Creating E2B sandbox with Notion and GitHub MCP servers...

Sandbox created successfully!
MCP Gateway URL: https://50005-xxxxx.e2b.app/mcp

Connecting Claude to MCP gateway...
Added HTTP MCP server e2b-mcp-gateway with URL: https://50005-xxxxx.e2b.app/mcp

Connection successful! Cleaning up...
```

### [Test with example workflow](#test-with-example-workflow)

Now, test the setup by running a simple workflow that searches Notion and creates a GitHub issue.

> Important
>
> Replace `owner/repo` in the prompt with your actual GitHub username and repository name (for example, `yourname/test-repo`).

Update `index.ts` with the following example:

```typescript
import "dotenv/config";
import { Sandbox } from "e2b";

async function exampleWorkflow(): Promise<void> {
  console.log("Creating sandbox...\n");

  const sbx: Sandbox = await Sandbox.create({
    envs: {
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY as string,
    },
    mcp: {
      notion: {
        internalIntegrationToken: process.env
          .NOTION_INTEGRATION_TOKEN as string,
      },
      githubOfficial: {
        githubPersonalAccessToken: process.env.GITHUB_TOKEN as string,
      },
    },
  });

  const mcpUrl = sbx.getMcpUrl();
  const mcpToken = await sbx.getMcpToken();

  console.log("Sandbox created successfully\n");

  // Wait for MCP servers to initialize
  await new Promise<void>((resolve) => setTimeout(resolve, 3000));

  console.log("Connecting Claude to MCP gateway...\n");
  await sbx.commands.run(
    `claude mcp add --transport http e2b-mcp-gateway ${mcpUrl} --header "Authorization: Bearer ${mcpToken}"`,
    {
      timeoutMs: 0,
      onStdout: console.log,
      onStderr: console.log,
    },
  );

  console.log("\nRunning example: Search Notion and create GitHub issue...\n");

  const prompt: string = `Using Notion and GitHub MCP tools:
1. Search my Notion workspace for databases
2. Create a test issue in owner/repo titled "MCP Toolkit Test" with description "Testing E2B + Docker MCP integration"
3. Confirm both operations completed successfully`;

  await sbx.commands.run(
    `echo '${prompt.replace(/'/g, "'\\''")}' | claude -p --dangerously-skip-permissions`,
    {
      timeoutMs: 0,
      onStdout: console.log,
      onStderr: console.log,
    },
  );

  await sbx.kill();
}

exampleWorkflow().catch(console.error);
```

Run the script:

```console
$ npx tsx index.ts
```

Update `index.py` with this example:

> Important
>
> Replace `owner/repo` in the prompt with your actual GitHub username and repository name (for example, `yourname/test-repo`).

```python
import os
import asyncio
import shlex
from dotenv import load_dotenv
from e2b import Sandbox

load_dotenv()

async def example_workflow():
    print("Creating sandbox...\n")

    sbx = await Sandbox.beta_create(
        envs={
            "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
        },
        mcp={
            "notion": {
                "internalIntegrationToken": os.getenv("NOTION_INTEGRATION_TOKEN"),
            },
            "githubOfficial": {
                "githubPersonalAccessToken": os.getenv("GITHUB_TOKEN"),
            },
        },
    )

    mcp_url = sbx.beta_get_mcp_url()
    mcp_token = await sbx.beta_get_mcp_token()

    print("Sandbox created successfully\n")

    # Wait for MCP servers to initialize
    await asyncio.sleep(3)

    print("Connecting Claude to MCP gateway...\n")

    def on_stdout(output):
        print(output, end='')

    def on_stderr(output):
        print(output, end='')

    await sbx.commands.run(
        f'claude mcp add --transport http e2b-mcp-gateway {mcp_url} --header "Authorization: Bearer {mcp_token}"',
        timeout_ms=0,
        on_stdout=on_stdout,
        on_stderr=on_stderr
    )

    print("\nRunning example: Search Notion and create GitHub issue...\n")

    prompt = """Using Notion and GitHub MCP tools:
1. Search my Notion workspace for databases
2. Create a test issue in owner/repo titled "MCP Toolkit Test" with description "Testing E2B + Docker MCP integration"
3. Confirm both operations completed successfully"""

    # Escape single quotes for shell
    escaped_prompt = prompt.replace("'", "'\\''")

    await sbx.commands.run(
        f"echo '{escaped_prompt}' | claude -p --dangerously-skip-permissions",
        timeout_ms=0,
        on_stdout=on_stdout,
        on_stderr=on_stderr
    )

    await sbx.kill()

if __name__ == "__main__":
    try:
        asyncio.run(example_workflow())
    except Exception as e:
        print(f"Error: {e}")
```

Run the script:

```console
$ python workflow.py
```

You should see:

```console
Creating sandbox...

Running example: Search Notion and create GitHub issue...

## Task Completed Successfully

I've completed both operations using the Notion and GitHub MCP tools:

### 1. Notion Workspace Search

Found 3 databases in your Notion workspace:
- **Customer Feedback** - Database with 12 entries tracking feature requests
- **Product Roadmap** - Planning database with 8 active projects
- **Meeting Notes** - Shared workspace with 45 pages

### 2. GitHub Issue Creation

Successfully created test issue:
- **Repository**: your-org/your-repo
- **Issue Number**: #47
- **Title**: "MCP Test"
- **Description**: "Testing E2B + Docker MCP integration"
- **Status**: Open
- **URL**: https://github.com/your-org/your-repo/issues/47

Both operations completed successfully. The MCP servers are properly configured and working.
```

The sandbox connected multiple MCP servers and orchestrated a workflow across Notion and GitHub. You can extend this pattern to combine any of the 200+ MCP servers in the Docker MCP Catalog.

## [Related pages](#related-pages)

* [How to build an AI-powered code quality workflow with SonarQube and E2B](https://docs.docker.com/guides/github-sonarqube-sandbox/)
* [Docker + E2B: Building the Future of Trusted AI](https://www.docker.com/blog/docker-e2b-building-the-future-of-trusted-ai/)
* [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/)
* [Docker MCP Toolkit and Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/)
* [Docker MCP Gateway](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/)
* [E2B MCP documentation](https://e2b.dev/docs/mcp)

----
url: https://docs.docker.com/reference/cli/docker/buildx/history/export/
----

# docker buildx history export

***

| Description | Export build records into Docker Desktop bundle   |
| ----------- | ------------------------------------------------- |
| Usage       | `docker buildx history export [OPTIONS] [REF...]` |

## [Description](#description)

Export one or more build records to `.dockerbuild` archive files. These archives contain metadata, logs, and build outputs, and can be imported into Docker Desktop or shared across environments.

## [Options](#options)

| Option                    | Default | Description                                         |
| ------------------------- | ------- | --------------------------------------------------- |
| [`--all`](#all)           |         | Export all build records for the builder            |
| [`--finalize`](#finalize) |         | Ensure build records are finalized before exporting |
| [`-o, --output`](#output) |         | Output file path                                    |

## [Examples](#examples)

### [Export all build records to a file (--all)](#all)

Use the `--all` flag and redirect the output:

```console
docker buildx history export --all > all-builds.dockerbuild
```

Or use the `--output` flag:

```console
docker buildx history export --all -o all-builds.dockerbuild
```

### [Use a specific builder instance (--builder)](#builder)

```console
docker buildx history export --builder builder0 ^1 -o builder0-build.dockerbuild
```

### [Enable debug logging (--debug)](#debug)

```console
docker buildx history export --debug qu2gsuo8ejqrwdfii23xkkckt -o debug-build.dockerbuild
```

### [Ensure build records are finalized before exporting (--finalize)](#finalize)

Clients can report their own traces concurrently, and not all traces may be saved yet by the time of the export. Use the `--finalize` flag to ensure all traces are finalized before exporting.

```console
docker buildx history export --finalize qu2gsuo8ejqrwdfii23xkkckt -o finalized-build.dockerbuild
```

### [Export a single build to a custom file (--output)](#output)

```console
docker buildx history export qu2gsuo8ejqrwdfii23xkkckt --output mybuild.dockerbuild
```

You can find build IDs by running:

```console
docker buildx history ls
```

To export two builds to separate files:

```console
# Using build IDs
docker buildx history export qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3 -o multi.dockerbuild

# Or using relative offsets
docker buildx history export ^1 ^2 -o multi.dockerbuild
```

Or use shell redirection:

```console
docker buildx history export ^1 > mybuild.dockerbuild
docker buildx history export ^2 > backend-build.dockerbuild
```

----
url: https://docs.docker.com/reference/cli/docker/context/show/
----

# docker context show

***

| Description | Print the name of the current context |
| ----------- | ------------------------------------- |
| Usage       | `docker context show`                 |

## [Description](#description)

Print the name of the current context, possibly set by `DOCKER_CONTEXT` environment variable or `--context` global option.

## [Examples](#examples)

### [Print the current context](#print-the-current-context)

The following example prints the currently used [`docker context`](/reference/cli/docker/context/):

```console
$ docker context show'
default
```

As an example, this output can be used to dynamically change your shell prompt to indicate your active context. The example below illustrates how this output could be used when using Bash as your shell.

Declare a function to obtain the current context in your `~/.bashrc`, and set this command as your `PROMPT_COMMAND`

```console
function docker_context_prompt() {
        PS1="context: $(docker context show)> "
}

PROMPT_COMMAND=docker_context_prompt
```

After reloading the `~/.bashrc`, the prompt now shows the currently selected `docker context`:

```console
$ source ~/.bashrc
context: default> docker context create --docker host=unix:///var/run/docker.sock my-context
my-context
Successfully created context "my-context"
context: default> docker context use my-context
my-context
Current context is now "my-context"
context: my-context> docker context use default
default
Current context is now "default"
context: default>
```

----
url: https://docs.docker.com/build/building/variables/
----

# Build variables

***

Table of contents

***

In Docker Build, build arguments (`ARG`) and environment variables (`ENV`) both serve as a means to pass information into the build process. You can use them to parameterize the build, allowing for more flexible and configurable builds.

> Warning
>
> Build arguments and environment variables are inappropriate for passing secrets to your build, because they're exposed in the final image. Instead, use secret mounts or SSH mounts, which expose secrets to your builds securely.
>
> See [Build secrets](https://docs.docker.com/build/building/secrets/) for more information.

## [Similarities and differences](#similarities-and-differences)

Build arguments and environment variables are similar. They're both declared in the Dockerfile and can be set using flags for the `docker build` command. Both can be used to parameterize the build. But they each serve a distinct purpose.

### [Build arguments](#build-arguments)

Build arguments are variables for the Dockerfile itself. Use them to parameterize values of Dockerfile instructions. For example, you might use a build argument to specify the version of a dependency to install.

Build arguments have no effect on the build unless it's used in an instruction. They're not accessible or present in containers instantiated from the image unless explicitly passed through from the Dockerfile into the image filesystem or configuration. They may persist in the image metadata, as provenance attestations and in the image history, which is why they're not suitable for holding secrets.

They make Dockerfiles more flexible, and easier to maintain.

For an example on how you can use build arguments, see [`ARG` usage example](#arg-usage-example).

### [Environment variables](#environment-variables)

Environment variables are passed through to the build execution environment, and persist in containers instantiated from the image.

Environment variables are primarily used to:

* Configure the execution environment for builds
* Set default environment variables for containers

Environment variables, if set, can directly influence the execution of your build, and the behavior or configuration of the application.

You can't override or set an environment variable at build-time. Values for environment variables must be declared in the Dockerfile. You can combine environment variables and build arguments to allow environment variables to be configured at build-time.

For an example on how to use environment variables for configuring builds, see [`ENV` usage example](#env-usage-example).

## [`ARG` usage example](#arg-usage-example)

Build arguments are commonly used to specify versions of components, such as image variants or package versions, used in a build.

Specifying versions as build arguments lets you build with different versions without having to manually update the Dockerfile. It also makes it easier to maintain the Dockerfile, since it lets you declare versions at the top of the file.

Build arguments can also be a way to reuse a value in multiple places. For example, if you use multiple flavors of `alpine` in your build, you can ensure you're using the same version of `alpine` everywhere:

* `golang:1.22-alpine${ALPINE_VERSION}`
* `python:3.12-alpine${ALPINE_VERSION}`
* `nginx:1-alpine${ALPINE_VERSION}`

The following example defines the version of `node` and `alpine` using build arguments.

```dockerfile
# syntax=docker/dockerfile:1

ARG NODE_VERSION="24"
ARG ALPINE_VERSION="3.23"

FROM node:${NODE_VERSION}-alpine${ALPINE_VERSION} AS base
WORKDIR /src

FROM base AS build
COPY package*.json ./
RUN npm ci
RUN npm run build

FROM base AS production
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=build /src/dist/ .
CMD ["node", "app.js"]
```

In this case, the build arguments have default values. Specifying their values when you invoke a build is optional. To override the defaults, you would use the `--build-arg` CLI flag:

```console
$ docker build --build-arg NODE_VERSION=current .
```

For more information on how to use build arguments, refer to:

* [`ARG` Dockerfile reference](https://docs.docker.com/reference/dockerfile/#arg)
* [`docker build --build-arg` reference](/reference/cli/docker/buildx/build/#build-arg)

## [`ENV` usage example](#env-usage-example)

Declaring an environment variable with `ENV` makes the variable available to all subsequent instructions in the build stage. The following example shows an example setting `NODE_ENV` to `production` before installing JavaScript dependencies with `npm`. Setting the variable makes `npm` omits packages needed only for local development.

```dockerfile
# syntax=docker/dockerfile:1

FROM node:20
WORKDIR /app
COPY package*.json ./
ENV NODE_ENV=production
RUN npm ci && npm cache clean --force
COPY . .
CMD ["node", "app.js"]
```

Environment variables aren't configurable at build-time by default. If you want to change the value of an `ENV` at build-time, you can combine environment variables and build arguments:

```dockerfile
# syntax=docker/dockerfile:1

FROM node:20
ARG NODE_ENV=production
ENV NODE_ENV=$NODE_ENV
WORKDIR /app
COPY package*.json ./
RUN npm ci && npm cache clean --force
COPY . .
CMD ["node", "app.js"]
```

With this Dockerfile, you can use `--build-arg` to override the default value of `NODE_ENV`:

```console
$ docker build --build-arg NODE_ENV=development .
```

Note that, because the environment variables you set persist in containers, using them can lead to unintended side-effects for the application's runtime.

For more information on how to use environment variables in builds, refer to:

* [`ENV` Dockerfile reference](https://docs.docker.com/reference/dockerfile/#env)

## [Scoping](#scoping)

Build arguments declared in the global scope of a Dockerfile aren't automatically inherited into the build stages. They're only accessible in the global scope.

```dockerfile
# syntax=docker/dockerfile:1

# The following build argument is declared in the global scope:
ARG NAME="joe"

FROM alpine
# The following instruction doesn't have access to the $NAME build argument
# because the argument was defined in the global scope, not for this stage.
RUN echo "hello ${NAME}!"
```

The `echo` command in this example evaluates to `hello !` because the value of the `NAME` build argument is out of scope. To inherit global build arguments into a stage, you must consume them:

```dockerfile
# syntax=docker/dockerfile:1

# Declare the build argument in the global scope
ARG NAME="joe"

FROM alpine
# Consume the build argument in the build stage
ARG NAME
RUN echo $NAME
```

Once a build argument is declared or consumed in a stage, it's automatically inherited by child stages.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine AS base
# Declare the build argument in the build stage
ARG NAME="joe"

# Create a new stage based on "base"
FROM base AS build
# The NAME build argument is available here
# since it's declared in a parent stage
RUN echo "hello $NAME!"
```

The following diagram further exemplifies how build argument and environment variable inheritance works for multi-stage builds.

## [Pre-defined build arguments](#pre-defined-build-arguments)

This section describes pre-defined build arguments available to all builds by default.

### [Multi-platform build arguments](#multi-platform-build-arguments)

Multi-platform build arguments describe the build and target platforms for the build.

The build platform is the operating system, architecture, and platform variant of the host system where the builder (the BuildKit daemon) is running.

* `BUILDPLATFORM`
* `BUILDOS`
* `BUILDARCH`
* `BUILDVARIANT`

The target platform arguments hold the same values for the target platforms for the build, specified using the `--platform` flag for the `docker build` command.

* `TARGETPLATFORM`
* `TARGETOS`
* `TARGETARCH`
* `TARGETVARIANT`

These arguments are useful for doing cross-compilation in multi-platform builds. They're available in the global scope of the Dockerfile, but they aren't automatically inherited by build stages. To use them inside stage, you must declare them:

```dockerfile
# syntax=docker/dockerfile:1

# Pre-defined build arguments are available in the global scope
FROM --platform=$BUILDPLATFORM golang
# To inherit them to a stage, declare them with ARG
ARG TARGETOS
RUN GOOS=$TARGETOS go build -o ./exe .
```

For more information about multi-platform build arguments, refer to [Multi-platform arguments](https://docs.docker.com/reference/dockerfile/#automatic-platform-args-in-the-global-scope)

### [Proxy arguments](#proxy-arguments)

Proxy build arguments let you specify proxies to use for your build. You don't need to declare or reference these arguments in the Dockerfile. Specifying a proxy with `--build-arg` is enough to make your build use the proxy.

Proxy arguments are automatically excluded from the build cache and the output of `docker history` by default. If you do reference the arguments in your Dockerfile, the proxy configuration ends up in the build cache.

The builder respects the following proxy build arguments. The variables are case insensitive.

* `HTTP_PROXY`
* `HTTPS_PROXY`
* `FTP_PROXY`
* `NO_PROXY`
* `ALL_PROXY`

To configure a proxy for your build:

```console
$ docker build --build-arg HTTP_PROXY=https://my-proxy.example.com .
```

For more information about proxy build arguments, refer to [Proxy arguments](https://docs.docker.com/reference/dockerfile/#predefined-args).

## [Build tool configuration variables](#build-tool-configuration-variables)

The following environment variables enable, disable, or change the behavior of Buildx and BuildKit. Note that these variables aren't used to configure the build container; they aren't available inside the build and they have no relation to the `ENV` instruction. They're used to configure the Buildx client, or the BuildKit daemon.

| Variable                                                                       | Type              | Description                                                     |
| ------------------------------------------------------------------------------ | ----------------- | --------------------------------------------------------------- |
| [BUILDKIT\_COLORS](#buildkit_colors)                                           | String            | Configure text color for the terminal output.                   |
| [BUILDKIT\_HOST](#buildkit_host)                                               | String            | Specify host to use for remote builders.                        |
| [BUILDKIT\_PROGRESS](#buildkit_progress)                                       | String            | Configure type of progress output.                              |
| [BUILDKIT\_TTY\_LOG\_LINES](#buildkit_tty_log_lines)                           | String            | Number of log lines (for active steps in TTY mode).             |
| [BUILDX\_BAKE\_FILE](#buildx_bake_file)                                        | String            | Specify the build definition file(s) for `docker buildx bake`.  |
| [BUILDX\_BAKE\_FILE\_SEPARATOR](#buildx_bake_file_separator)                   | String            | Specify the file-path separator for `BUILDX_BAKE_FILE`.         |
| [BUILDX\_BAKE\_GIT\_AUTH\_HEADER](#buildx_bake_git_auth_header)                | String            | HTTP authentication scheme for remote Bake files.               |
| [BUILDX\_BAKE\_GIT\_AUTH\_TOKEN](#buildx_bake_git_auth_token)                  | String            | HTTP authentication token for remote Bake files.                |
| [BUILDX\_BAKE\_GIT\_SSH](#buildx_bake_git_ssh)                                 | String            | SSH authentication for remote Bake files.                       |
| [BUILDX\_BUILDER](#buildx_builder)                                             | String            | Specify the builder instance to use.                            |
| [BUILDX\_CONFIG](#buildx_config)                                               | String            | Specify location for configuration, state, and logs.            |
| [BUILDX\_CPU\_PROFILE](#buildx_cpu_profile)                                    | String            | Generate a `pprof` CPU profile at the specified location.       |
| [BUILDX\_EXPERIMENTAL](#buildx_experimental)                                   | Boolean           | Turn on experimental features.                                  |
| [BUILDX\_GIT\_CHECK\_DIRTY](#buildx_git_check_dirty)                           | Boolean           | Enable dirty Git checkout detection.                            |
| [BUILDX\_GIT\_INFO](#buildx_git_info)                                          | Boolean           | Remove Git information in provenance attestations.              |
| [BUILDX\_GIT\_LABELS](#buildx_git_labels)                                      | String \| Boolean | Add Git provenance labels to images.                            |
| [BUILDX\_MEM\_PROFILE](#buildx_mem_profile)                                    | String            | Generate a `pprof` memory profile at the specified location.    |
| [BUILDX\_METADATA\_PROVENANCE](#buildx_metadata_provenance)                    | String \| Boolean | Customize provenance information included in the metadata file. |
| [BUILDX\_METADATA\_WARNINGS](#buildx_metadata_warnings)                        | String            | Include build warnings in the metadata file.                    |
| [BUILDX\_NO\_DEFAULT\_ATTESTATIONS](#buildx_no_default_attestations)           | Boolean           | Turn off default provenance attestations.                       |
| [BUILDX\_NO\_DEFAULT\_LOAD](#buildx_no_default_load)                           | Boolean           | Turn off loading images to image store by default.              |
| [EXPERIMENTAL\_BUILDKIT\_SOURCE\_POLICY](#experimental_buildkit_source_policy) | String            | Specify a BuildKit source policy file.                          |

BuildKit also supports a few additional configuration parameters. Refer to [BuildKit built-in build args](https://docs.docker.com/reference/dockerfile/#buildkit-built-in-build-args).

You can express Boolean values for environment variables in different ways. For example, `true`, `1`, and `T` all evaluate to true. Evaluation is done using the `strconv.ParseBool` function in the Go standard library. See the [reference documentation](https://pkg.go.dev/strconv#ParseBool) for details.

### [BUILDKIT\_COLORS](#buildkit_colors)

Changes the colors of the terminal output. Set `BUILDKIT_COLORS` to a CSV string in the following format:

```console
$ export BUILDKIT_COLORS="run=123,20,245:error=yellow:cancel=blue:warning=white"
```

Color values can be any valid RGB hex code, or one of the [BuildKit predefined colors](https://github.com/moby/buildkit/blob/master/util/progress/progressui/colors.go).

Setting `NO_COLOR` to anything turns off colorized output, as recommended by [no-color.org](https://no-color.org/).

### [BUILDKIT\_HOST](#buildkit_host)

Requires: Docker Buildx [0.9.0](https://github.com/docker/buildx/releases/tag/v0.9.0) and later

You use the `BUILDKIT_HOST` to specify the address of a BuildKit daemon to use as a remote builder. This is the same as specifying the address as a positional argument to `docker buildx create`.

Usage:

```console
$ export BUILDKIT_HOST=tcp://localhost:1234
$ docker buildx create --name=remote --driver=remote
```

If you specify both the `BUILDKIT_HOST` environment variable and a positional argument, the argument takes priority.

### [BUILDKIT\_PROGRESS](#buildkit_progress)

Sets the type of the BuildKit progress output. Valid values are:

* `auto` (default): automatically uses `tty` in interactive terminals, `plain` otherwise
* `plain`: displays build steps sequentially in simple text format
* `tty`: interactive output with formatted progress bars and build steps
* `quiet`: suppresses progress output, only shows errors and final image ID
* `none`: no progress output, only shows errors
* `rawjson`: outputs build progress as raw JSON (useful for parsing by other tools)

Usage:

```console
$ export BUILDKIT_PROGRESS=plain
```

### [BUILDKIT\_TTY\_LOG\_LINES](#buildkit_tty_log_lines)

You can change how many log lines are visible for active steps in TTY mode by setting `BUILDKIT_TTY_LOG_LINES` to a number (default to `6`).

```console
$ export BUILDKIT_TTY_LOG_LINES=8
```

### [EXPERIMENTAL\_BUILDKIT\_SOURCE\_POLICY](#experimental_buildkit_source_policy)

Lets you specify a [BuildKit source policy](https://github.com/moby/buildkit/blob/master/docs/build-repro.md#reproducing-the-pinned-dependencies) file for creating reproducible builds with pinned dependencies.

```console
$ export EXPERIMENTAL_BUILDKIT_SOURCE_POLICY=./policy.json
```

Example:

```json
{
  "rules": [
    {
      "action": "CONVERT",
      "selector": {
        "identifier": "docker-image://docker.io/library/alpine:latest"
      },
      "updates": {
        "identifier": "docker-image://docker.io/library/alpine:latest@sha256:4edbd2beb5f78b1014028f4fbb99f3237d9561100b6881aabbf5acce2c4f9454"
      }
    },
    {
      "action": "CONVERT",
      "selector": {
        "identifier": "https://raw.githubusercontent.com/moby/buildkit/v0.10.1/README.md"
      },
      "updates": {
        "attrs": {"http.checksum": "sha256:6e4b94fc270e708e1068be28bd3551dc6917a4fc5a61293d51bb36e6b75c4b53"}
      }
    },
    {
      "action": "DENY",
      "selector": {
        "identifier": "docker-image://docker.io/library/golang*"
      }
    }
  ]
}
```

### [BUILDX\_BAKE\_FILE](#buildx_bake_file)

Requires: Docker Buildx [0.26.0](https://github.com/docker/buildx/releases/tag/v0.26.0) and later

Specify one or more build definition files for `docker buildx bake`.

This environment variable provides an alternative to the `-f` / `--file` command-line flag.

Multiple files can be specified by separating them with the system path separator (":" on Linux/macOS, ";" on Windows):

```console
export BUILDX_BAKE_FILE=file1.hcl:file2.hcl
```

Or with a custom separator defined by the [BUILDX\_BAKE\_FILE\_SEPARATOR](#buildx_bake_file_separator) variable:

```console
export BUILDX_BAKE_FILE_SEPARATOR=@
export BUILDX_BAKE_FILE=file1.hcl@file2.hcl
```

If both `BUILDX_BAKE_FILE` and the `-f` flag are set, only the files provided via `-f` are used.

If a listed file does not exist or is invalid, bake returns an error.

### [BUILDX\_BAKE\_FILE\_SEPARATOR](#buildx_bake_file_separator)

Requires: Docker Buildx [0.26.0](https://github.com/docker/buildx/releases/tag/v0.26.0) and later

Controls the separator used between file paths in the `BUILDX_BAKE_FILE` environment variable.

This is useful if your file paths contain the default separator character or if you want to standardize separators across different platforms.

```console
export BUILDX_BAKE_PATH_SEPARATOR=@
export BUILDX_BAKE_FILE=file1.hcl@file2.hcl
```

### [BUILDX\_BAKE\_GIT\_AUTH\_HEADER](#buildx_bake_git_auth_header)

Requires: Docker Buildx [0.14.0](https://github.com/docker/buildx/releases/tag/v0.14.0) and later

Sets the HTTP authentication scheme when using a remote Bake definition in a private Git repository. This is equivalent to the [`GIT_AUTH_HEADER` secret](https://docs.docker.com/build/building/secrets/#http-authentication-scheme), but facilitates the pre-flight authentication in Bake when loading the remote Bake file. Supported values are `bearer` (default) and `basic`.

Usage:

```console
$ export BUILDX_BAKE_GIT_AUTH_HEADER=basic
```

### [BUILDX\_BAKE\_GIT\_AUTH\_TOKEN](#buildx_bake_git_auth_token)

Requires: Docker Buildx [0.14.0](https://github.com/docker/buildx/releases/tag/v0.14.0) and later

Sets the HTTP authentication token when using a remote Bake definition in a private Git repository. This is equivalent to the [`GIT_AUTH_TOKEN` secret](https://docs.docker.com/build/building/secrets/#git-authentication-for-remote-contexts), but facilitates the pre-flight authentication in Bake when loading the remote Bake file.

Usage:

```console
$ export BUILDX_BAKE_GIT_AUTH_TOKEN=$(cat git-token.txt)
```

### [BUILDX\_BAKE\_GIT\_SSH](#buildx_bake_git_ssh)

Requires: Docker Buildx [0.14.0](https://github.com/docker/buildx/releases/tag/v0.14.0) and later

Lets you specify a list of SSH agent socket filepaths to forward to Bake for authenticating to a Git server when using a remote Bake definition in a private repository. This is similar to SSH mounts for builds, but facilitates the pre-flight authentication in Bake when resolving the build definition.

Setting this environment is typically not necessary, because Bake will use the `SSH_AUTH_SOCK` agent socket by default. You only need to specify this variable if you want to use a socket with a different filepath. This variable can take multiple paths using a comma-separated string.

Usage:

```console
$ export BUILDX_BAKE_GIT_SSH=/run/foo/listener.sock,~/.creds/ssh.sock
```

### [BUILDX\_BUILDER](#buildx_builder)

Overrides the configured builder instance. Same as the `docker buildx --builder` CLI flag.

Usage:

```console
$ export BUILDX_BUILDER=my-builder
```

### [BUILDX\_CONFIG](#buildx_config)

You can use `BUILDX_CONFIG` to specify the directory to use for build configuration, state, and logs. The lookup order for this directory is as follows:

* `$BUILDX_CONFIG`
* `$DOCKER_CONFIG/buildx`
* `~/.docker/buildx` (default)

Usage:

```console
$ export BUILDX_CONFIG=/usr/local/etc
```

### [BUILDX\_CPU\_PROFILE](#buildx_cpu_profile)

Requires: Docker Buildx [0.18.0](https://github.com/docker/buildx/releases/tag/v0.18.0) and later

If specified, Buildx generates a `pprof` CPU profile at the specified location.

> Note
>
> This property is only useful for when developing Buildx. The profiling data is not relevant for analyzing a build's performance.

Usage:

```console
$ export BUILDX_CPU_PROFILE=buildx_cpu.prof
```

### [BUILDX\_EXPERIMENTAL](#buildx_experimental)

Enables experimental build features.

Usage:

```console
$ export BUILDX_EXPERIMENTAL=1
```

### [BUILDX\_GIT\_CHECK\_DIRTY](#buildx_git_check_dirty)

Requires: Docker Buildx [0.10.4](https://github.com/docker/buildx/releases/tag/v0.10.4) and later

When set to true, checks for dirty state in source control information for [provenance attestations](https://docs.docker.com/build/metadata/attestations/slsa-provenance/).

Usage:

```console
$ export BUILDX_GIT_CHECK_DIRTY=1
```

### [BUILDX\_GIT\_INFO](#buildx_git_info)

Requires: Docker Buildx [0.10.0](https://github.com/docker/buildx/releases/tag/v0.10.0) and later

When set to false, removes source control information from [provenance attestations](https://docs.docker.com/build/metadata/attestations/slsa-provenance/).

Usage:

```console
$ export BUILDX_GIT_INFO=0
```

### [BUILDX\_GIT\_LABELS](#buildx_git_labels)

Requires: Docker Buildx [0.10.0](https://github.com/docker/buildx/releases/tag/v0.10.0) and later

Adds provenance labels, based on Git information, to images that you build. The labels are:

* `com.docker.image.source.entrypoint`: Location of the Dockerfile relative to the project root
* `org.opencontainers.image.revision`: Git commit revision
* `org.opencontainers.image.source`: SSH or HTTPS address of the repository

Example:

```json
  "Labels": {
    "com.docker.image.source.entrypoint": "Dockerfile",
    "org.opencontainers.image.revision": "5734329c6af43c2ae295010778cd308866b95d9b",
    "org.opencontainers.image.source": "git@github.com:foo/bar.git"
  }
```

Usage:

* Set `BUILDX_GIT_LABELS=1` to include the `entrypoint` and `revision` labels.
* Set `BUILDX_GIT_LABELS=full` to include all labels.

If the repository is in a dirty state, the `revision` gets a `-dirty` suffix.

### [BUILDX\_MEM\_PROFILE](#buildx_mem_profile)

Requires: Docker Buildx [0.18.0](https://github.com/docker/buildx/releases/tag/v0.18.0) and later

If specified, Buildx generates a `pprof` memory profile at the specified location.

> Note
>
> This property is only useful for when developing Buildx. The profiling data is not relevant for analyzing a build's performance.

Usage:

```console
$ export BUILDX_MEM_PROFILE=buildx_mem.prof
```

### [BUILDX\_METADATA\_PROVENANCE](#buildx_metadata_provenance)

Requires: Docker Buildx [0.14.0](https://github.com/docker/buildx/releases/tag/v0.14.0) and later

By default, Buildx includes minimal provenance information in the metadata file through [`--metadata-file` flag](/reference/cli/docker/buildx/build/#metadata-file). This environment variable allows you to customize the provenance information included in the metadata file:

* `min` sets minimal provenance (default).
* `max` sets full provenance.
* `disabled`, `false` or `0` does not set any provenance.

### [BUILDX\_METADATA\_WARNINGS](#buildx_metadata_warnings)

Requires: Docker Buildx [0.16.0](https://github.com/docker/buildx/releases/tag/v0.16.0) and later

By default, Buildx does not include build warnings in the metadata file through [`--metadata-file` flag](/reference/cli/docker/buildx/build/#metadata-file). You can set this environment variable to `1` or `true` to include them.

### [BUILDX\_NO\_DEFAULT\_ATTESTATIONS](#buildx_no_default_attestations)

Requires: Docker Buildx [0.10.4](https://github.com/docker/buildx/releases/tag/v0.10.4) and later

By default, BuildKit v0.11 and later adds [provenance attestations](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) to images you build. Set `BUILDX_NO_DEFAULT_ATTESTATIONS=1` to disable the default provenance attestations.

Usage:

```console
$ export BUILDX_NO_DEFAULT_ATTESTATIONS=1
```

### [BUILDX\_NO\_DEFAULT\_LOAD](#buildx_no_default_load)

When you build an image using the `docker` driver, the image is automatically loaded to the image store when the build finishes. Set `BUILDX_NO_DEFAULT_LOAD` to disable automatic loading of images to the local container store.

Usage:

```console
$ export BUILDX_NO_DEFAULT_LOAD=1
```

----
url: https://docs.docker.com/ai/gordon/
----

# Gordon

***

Table of contents

***

Requires: Docker Desktop [4.74.0](https://docs.docker.com/desktop/release-notes/#4740) or later

Gordon is an AI-powered assistant that takes action on your Docker workflows. It analyzes your environment, proposes solutions, and executes commands with your permission.

## [What Gordon does](#what-gordon-does)

Gordon takes action to help you with Docker tasks:

* Explains Docker concepts and commands
* Searches Docker documentation and web resources for solutions
* Writes and modifies Dockerfiles following best practices
* Debugs container failures by reading logs and proposing fixes
* Manages containers, images, volumes, and networks

Gordon proposes every action before executing. You approve what it does.

## [Where to use Gordon](#where-to-use-gordon)

Gordon is available on four surfaces:

* Open the Gordon view from the Docker Desktop sidebar to run Docker commands with your approval. See [Using Gordon in Docker Desktop](https://docs.docker.com/ai/gordon/how-to/docker-desktop/).
* Run `docker ai` in the terminal to use the full assistant from the command line. See [Using Gordon via CLI](https://docs.docker.com/ai/gordon/how-to/cli/).
* Select the Gordon icon on any repository page at [hub.docker.com](https://hub.docker.com) to ask about a repository's images, tags, and metadata. Hand off to Docker Desktop to take action.
* Select the Gordon icon on any page at [docs.docker.com](https://docs.docker.com) to ask Docker questions.

Docker Desktop and the CLI count against your Gordon plan's [usage limits](https://docs.docker.com/ai/gordon/usage-limits/). Gordon on Docker Hub and docs.docker.com is free and does not require a Docker account or a Docker Desktop install. It has its own shared public usage limit and does not access your Docker environment.

## [Get started](#get-started)

### [Prerequisites](#prerequisites)

Before you begin:

* Docker Desktop 4.74 or later
* Sign in to your Docker account

> Note
>
> Gordon is enabled by default for signed-in Docker users. If your account belongs to an organization with a Business subscription, access requires two additional steps:
>
> 1. Contact Docker Support to activate Gordon for your organization. Docker will confirm when activation is complete.
> 2. Once confirmed, an organization administrator must turn on Gordon via [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/). Set **Enable Gordon** to **Enabled** or **Always enabled**. Ensure all Settings Management prerequisites are met for the setting to take effect on Docker Desktop clients.

### [Quick start](#quick-start)

1. Open Docker Desktop.

2. Select **Gordon** in the sidebar.

3. Select your project directory.

4. Type a question: "What containers are running?"

5. Review Gordon's proposed actions and approve.

1) Open your terminal and run:

   ```console
   $ docker ai
   ```

   This opens the Terminal User Interface (TUI) for Gordon.

2) Type a question: "what containers are running?" and press `Enter`.

3) Review Gordon's proposed actions and approve by typing `y`.

### [Permissions](#permissions)

By default, Gordon asks for approval before executing actions. You can approve individual actions or allow all actions for the current session.

Permissions reset for each session. To configure default permissions or enable auto-approve mode, see [Permissions](https://docs.docker.com/ai/gordon/how-to/permissions/).

### [Try these examples](#try-these-examples)

Container inspection:

```console
$ docker ai "show me logs from my nginx container"
```

Dockerfile review:

```console
$ docker ai "review my Dockerfile for best practices"
```

Image management:

```console
$ docker ai "list my local images and their sizes"
```

----
url: https://docs.docker.com/accounts/
----

# Docker accounts

***

***

This section covers individual Docker accounts and Docker IDs. It does not cover organizations, companies, or administrator roles.

A Docker account is required to:

* Create a Docker ID
* Access Docker products and services like Docker Hub and Docker Desktop
* Receive organization invitations
* Manage your personal settings and security features

### [Create a Docker ID](/accounts/create-account/)

[Get started with Docker and create an account.](/accounts/create-account/)

### [Manage account](/accounts/manage-account/)

[Learn how to manage the settings for your account.](/accounts/manage-account/)

### [Personal access tokens](/security/access-tokens/)

[Learn how to create and manage access tokens for your account.](/security/access-tokens/)

### [Set up two-factor authentication](/security/2fa/)

[Add an extra layer of authentication to your Docker account.](/security/2fa/)

### [Deactivate an account](/accounts/deactivate-user-account/)

[Learn how to deactivate a Docker user account.](/accounts/deactivate-user-account/)

### [Account FAQ](/accounts/general-faqs/)

[Explore frequently asked questions about Docker accounts.](/accounts/general-faqs/)

----
url: https://docs.docker.com/reference/api/engine/version/v1.45/
----

# Docker Engine API v1.45 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.45.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.45.yaml)

# Docker Engine API (1.45)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.45.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.45) is used. For example, calling `/info` is the same as calling `/v1.45/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.45/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.45/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.45/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"AppArmorProfile": "",
"Args": [
"-c",
"exit 9"
],
"Config": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"/bin/sh",
"-c",
"exit 9"
],
"Domainname": "",
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Healthcheck": {
"Test": [
"CMD-SHELL",
"exit 0"
]
},
"Hostname": "ba033ac44011",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"MacAddress": "",
"NetworkDisabled": false,
"OpenStdin": false,
"StdinOnce": false,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"StopSignal": "SIGTERM",
"StopTimeout": 10
},
"Created": "2015-01-06T15:47:31.485331387Z",
"Driver": "overlay2",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 0,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"ContainerIDFile": "",
"CpusetCpus": "",
"CpusetMems": "",
"CpuPercent": 80,
"CpuShares": 0,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"Devices": [ ],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"IpcMode": "",
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"OomKillDisable": false,
"OomScoreAdj": 500,
"NetworkMode": "bridge",
"PidMode": "",
"PortBindings": { },
"Privileged": false,
"ReadonlyRootfs": false,
"PublishAllPorts": false,
"RestartPolicy": {
"MaximumRetryCount": 2,
"Name": "on-failure"
},
"LogConfig": {
"Type": "json-file"
},
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Ulimits": [
{ }
],
"VolumeDriver": "",
"ShmSize": 67108864
},
"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
"MountLabel": "",
"Name": "/boring_euclid",
"NetworkSettings": {
"Bridge": "",
"SandboxID": "",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": 0,
"SandboxKey": "",
"EndpointID": "",
"Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"MacAddress": "",
"Networks": {
"bridge": {
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
"EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Path": "/bin/sh",
"ProcessLabel": "",
"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
"RestartCount": 1,
"State": {
"Error": "",
"ExitCode": 9,
"FinishedAt": "2015-01-06T15:47:32.080254511Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2019-12-22T10:59:05.6385933Z",
"End": "2019-12-22T10:59:05.8078452Z",
"ExitCode": 0,
"Output": ""
}
]
},
"OOMKilled": false,
"Dead": false,
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z",
"Status": "running"
},
"Mounts": [
{
"Name": "fac362...80535",
"Source": "/data",
"Destination": "/data",
"Driver": "local",
"Mode": "ro,Z",
"RW": false,
"Propagation": ""
}
]
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.45/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
],
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.45/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.45/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.45/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.45/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"read": "2015-01-08T22:57:31.547920715Z",
"pids_stats": {
"current": 3
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"memory_stats": {
"stats": {
"total_pgmajfault": 0,
"cache": 0,
"mapped_file": 0,
"total_inactive_file": 0,
"pgpgout": 414,
"rss": 6537216,
"total_mapped_file": 0,
"writeback": 0,
"unevictable": 0,
"pgpgin": 477,
"total_unevictable": 0,
"pgmajfault": 0,
"total_rss": 6537216,
"total_rss_huge": 6291456,
"total_writeback": 0,
"total_inactive_anon": 0,
"rss_huge": 6291456,
"hierarchical_memory_limit": 67108864,
"total_pgfault": 964,
"total_active_file": 0,
"active_anon": 6537216,
"total_active_anon": 6537216,
"total_pgpgout": 414,
"total_cache": 0,
"inactive_anon": 0,
"active_file": 0,
"pgfault": 964,
"inactive_file": 0,
"total_pgpgin": 477
},
"max_usage": 6651904,
"usage": 6537216,
"failcnt": 0,
"limit": 67108864
},
"blkio_stats": { },
"cpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24472255,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100215355,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 739306590000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24350896,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100093996,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 9492140000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.45/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.45/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.45/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.45/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.45/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime.This field is omitted when empty.                         |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.45/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"string"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.45/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.45/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.45/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.45/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.45/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.45/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.45/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.45/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.45/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.45/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.45/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.45/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.45/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| keep-storage | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| all          | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.45/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.45/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.45/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"DockerVersion": "20.10.7",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "web:web",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": true,
"Image": "",
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.45/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|     |                                                                                                                                                                 |
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed. |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.45/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.45/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|         |                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------ |
| force   | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags |
| noprune | booleanDefault: falseDo not delete untagged parent images                                              |

### Responses

/v1.45/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                   |
| limit        | integerMaximum number of results to return                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.45/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.45/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.45/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.45/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                          |
| ----- | ---------------------------------------- |
| names | Array of stringsImage names to filter by |

### Responses

/v1.45/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                                             |
| ----- | ----------------------------------------------------------- |
| quiet | booleanDefault: falseSuppress progress details during load. |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.45/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.45/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.45/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.45/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|                |                                                                                                                                                                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired   | stringThe network's name.                                                                                                                                                                                                              |
| CheckDuplicate | booleanDeprecated: CheckDuplicate is now always enabled.                                                                                                                                                                               |
| Driver         | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope          | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal       | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable     | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress        | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly     | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|                | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|                | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv6     | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|                | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|                | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.45/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"CheckDuplicate": true,
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.45/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
},
"MacAddress": "02:42:ac:12:05:02"
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.45/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.45/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.45/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.45/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.45/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.45/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.45/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.45/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.45/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.45/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.45/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.45/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.45/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.45/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.45/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.45/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.45/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.45/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.45/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.45/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.45/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.45/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.45/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.45/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.45/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.45/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.45/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.45/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.45/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.45/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.45/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.45/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.45/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.45/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.45/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.45/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.45/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.45/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.45/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.45/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.45/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.45/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.45/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.45/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.45/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.45/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.45/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.45/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.45/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.45/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.45/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.45/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.45/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.45/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.45/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"BridgeNfIptables": true,
"BridgeNfIp6tables": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "4.9.38-moby",
"OperatingSystem": "Alpine Linux v3.5",
"OSVersion": "16.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"AllowNondistributableArtifactsCIDRs": [ ],
"AllowNondistributableArtifactsHostnames": [ ],
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "24.0.2",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
]
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.45/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "19.03.12",
"Details": { }
}
],
"Version": "19.03.12",
"ApiVersion": "1.40",
"MinAPIVersion": "1.12",
"GitCommit": "48a66213fe",
"GoVersion": "go1.13.14",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "4.19.76-linuxkit",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.45/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.45/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.45/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|      |                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |

### Responses

/v1.45/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parents": [ ],
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parents": [
"ndlpt0hhvkqcdfkputsk4cq9c"
],
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.45/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 3987495
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.45/session

----
url: https://docs.docker.com/desktop/settings-and-maintenance/backup-and-restore/
----

# How to back up and restore your Docker Desktop data

***

Table of contents

***

Use this procedure to back up and restore your images and container data. This is useful if you want to reset your VM disk or to move your Docker environment to a new computer, or recover from a failed Docker Desktop update or installation.

> Important
>
> If you use volumes or bind-mounts to store your container data, backing up your containers may not be needed, but make sure to remember the options that were used when creating the container or use a [Docker Compose file](https://docs.docker.com/reference/compose-file/) if you want to re-create your containers with the same configuration after re-installation.

## [If Docker Desktop is functioning normally](#if-docker-desktop-is-functioning-normally)

### [Save your data](#save-your-data)

1. Commit your containers to an image with [`docker container commit`](/reference/cli/docker/container/commit/).

   Committing a container stores filesystem changes and some container configurations, such as labels and environment variables, as a local image. Be aware that environment variables may contain sensitive information such as passwords or proxy-authentication, so take care when pushing the resulting image to a registry.

   Also note that filesystem changes in a volume that are attached to the container are not included in the image, and must be backed up separately.

   If you used a [named volume](https://docs.docker.com/engine/storage/#more-details-about-mount-types) to store container data, such as databases, refer to the [back up, restore, or migrate data volumes](https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes) page in the storage section.

2. Use [`docker push`](/reference/cli/docker/image/push/) to push any images you have built locally and want to keep to the [Docker Hub registry](https://docs.docker.com/docker-hub/).

   > Tip
   >
   > [Set the repository visibility to private](https://docs.docker.com/docker-hub/repos/) if your image includes sensitive content.

   Alternatively, use [`docker image save -o images.tar image1 [image2 ...]`](/reference/cli/docker/image/save/) to save any images you want to keep to a local `.tar` file.

After backing up your data, you can uninstall the current version of Docker Desktop and [install a different version](https://docs.docker.com/desktop/release-notes/) or reset Docker Desktop to factory defaults.

### [Restore your data](#restore-your-data)

1. Load your images.

   * If you pushed to Docker Hub:

     ```console
     $ docker pull <my-backup-image>
     ```

   * If you saved a `.tar` file:

     ```console
     $ docker image load -i images.tar
     ```

2. Re-create your containers if needed, using [`docker run`](/reference/cli/docker/container/run/), or [Docker Compose](https://docs.docker.com/compose/).

To restore volume data, refer to [backup, restore, or migrate data volumes](https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes).

## [If Docker Desktop fails to start or you want to back up the whole Docker Desktop VM](#if-docker-desktop-fails-to-start-or-you-want-to-back-up-the-whole-docker-desktop-vm)

If Docker Desktop cannot launch and must be reinstalled, you can back up its VM disk and image data directly from disk. Docker Desktop must be fully stopped before backing up these files.

1. Back up Docker containers/images.

   Backup the following file:

   ```console
   %LOCALAPPDATA%\Docker\wsl\data\docker_data.vhdx
   ```

   Copy it to a safe location.

2. Back up WSL distributions.

   If you're running any WSL Linux distributions (Ubuntu, Alpine, etc.), back them up using [Microsoft's guide](https://learn.microsoft.com/en-us/windows/wsl/faq#how-can-i-back-up-my-wsl-distributions-).

3. Restore.

   After reinstalling Docker Desktop, restore the `docker_data.vhdx` to the same location and re-import your WSL distributions if needed.

1) Back up Docker containers/images.

   Backup the following file:

   ```console
   ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw
   ```

   Copy it to a safe location.

   > Tip
   >
   > To include Docker Desktop data in Time Machine backups, make sure the `~/Library/Containers/com.docker.docker` directory is not excluded from your Time Machine backup configuration.

2) Restore.

   After reinstalling Docker Desktop, restore the `Docker.raw` to the same location.

1. Back up Docker containers/images:

   Backup the following file:

   ```console
   ~/.docker/desktop/vms/0/data/Docker.raw
   ```

   Copy it to a safe location.

2. Restore.

   After reinstalling Docker Desktop, restore the `Docker.raw` to the same location.

----
url: https://docs.docker.com/engine/logging/configure/
----

# Configure logging drivers

***

Table of contents

***

Docker includes multiple logging mechanisms to help you get information from running containers and services. These mechanisms are called logging drivers. Each Docker daemon has a default logging driver, which each container uses unless you configure it to use a different logging driver, or log driver for short.

As a default, Docker uses the [`json-file` logging driver](https://docs.docker.com/engine/logging/drivers/json-file/), which caches container logs as JSON internally. In addition to using the logging drivers included with Docker, you can also implement and use [logging driver plugins](https://docs.docker.com/engine/logging/plugins/).

> Tip
>
> Use the `local` logging driver to prevent disk-exhaustion. By default, no log-rotation is performed. As a result, log-files stored by the default [`json-file` logging driver](https://docs.docker.com/engine/logging/drivers/json-file/) logging driver can cause a significant amount of disk space to be used for containers that generate much output, which can lead to disk space exhaustion.
>
> Docker keeps the json-file logging driver (without log-rotation) as a default to remain backwards compatible with older versions of Docker, and for situations where Docker is used as runtime for Kubernetes.
>
> For other situations, the `local` logging driver is recommended as it performs log-rotation by default, and uses a more efficient file format. Refer to the [Configure the default logging driver](#configure-the-default-logging-driver) section below to learn how to configure the `local` logging driver as a default, and the [local file logging driver](https://docs.docker.com/engine/logging/drivers/local/) page for more details about the `local` logging driver.

## [Configure the default logging driver](#configure-the-default-logging-driver)

To configure the Docker daemon to default to a specific logging driver, set the value of `log-driver` to the name of the logging driver in the `daemon.json` configuration file. Refer to the "daemon configuration file" section in the [`dockerd` reference manual](/reference/cli/dockerd/#daemon-configuration-file) for details.

The default logging driver is `json-file`. The following example sets the default logging driver to the [`local` log driver](https://docs.docker.com/engine/logging/drivers/local/):

```json
{
  "log-driver": "local"
}
```

If the logging driver has configurable options, you can set them in the `daemon.json` file as a JSON object with the key `log-opts`. The following example sets four configurable options on the `json-file` logging driver:

```json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3",
    "labels": "production_status",
    "env": "os,customer"
  }
}
```

Restart Docker for the changes to take effect for newly created containers. Existing containers don't use the new logging configuration automatically.

> Note
>
> `log-opts` configuration options in the `daemon.json` configuration file must be provided as strings. Boolean and numeric values (such as the value for `max-file` in the example above) must therefore be enclosed in quotes (`"`).

If you don't specify a logging driver, the default is `json-file`. To find the current default logging driver for the Docker daemon, run `docker info` and search for `Logging Driver`. You can use the following command on Linux, macOS, or PowerShell on Windows:

```console
$ docker info --format '{{.LoggingDriver}}'

json-file
```

> Note
>
> Changing the default logging driver or logging driver options in the daemon configuration only affects containers that are created after the configuration is changed. Existing containers retain the logging driver options that were used when they were created. To update the logging driver for a container, the container has to be re-created with the desired options. Refer to the [configure the logging driver for a container](#configure-the-logging-driver-for-a-container) section below to learn how to find the logging-driver configuration of a container.

## [Configure the logging driver for a container](#configure-the-logging-driver-for-a-container)

When you start a container, you can configure it to use a different logging driver than the Docker daemon's default, using the `--log-driver` flag. If the logging driver has configurable options, you can set them using one or more instances of the `--log-opt <NAME>=<VALUE>` flag. Even if the container uses the default logging driver, it can use different configurable options.

The following example starts an Alpine container with the `none` logging driver.

```console
$ docker run -it --log-driver none alpine ash
```

To find the current logging driver for a running container, if the daemon is using the `json-file` logging driver, run the following `docker inspect` command, substituting the container name or ID for `<CONTAINER>`:

```console
$ docker inspect -f '{{.HostConfig.LogConfig.Type}}' CONTAINER

json-file
```

## [Configure the delivery mode of log messages from container to log driver](#configure-the-delivery-mode-of-log-messages-from-container-to-log-driver)

Docker provides two modes for delivering messages from the container to the log driver:

* (default) direct, blocking delivery from container to driver
* non-blocking delivery that stores log messages in an intermediate per-container buffer for consumption by driver

The `non-blocking` message delivery mode prevents applications from blocking due to logging back pressure. Applications are likely to fail in unexpected ways when STDERR or STDOUT streams block.

> Warning
>
> When the buffer is full, new messages will not be enqueued. Dropping messages is often preferred to blocking the log-writing process of an application.

The `mode` log option controls whether to use the `blocking` (default) or `non-blocking` message delivery.

The `max-buffer-size` controls the size of the buffer used for intermediate message storage when `mode` is set to `non-blocking`. The default is `1m` meaning 1 MB (1 million bytes). See [function `FromHumanSize()` in the `go-units` package](https://pkg.go.dev/github.com/docker/go-units#FromHumanSize) for the allowed format strings, some examples are `1KiB` for 1024 bytes, `2g` for 2 billion bytes.

The following example starts an Alpine container with log output in non-blocking mode and a 4 megabyte buffer:

```console
$ docker run -it --log-opt mode=non-blocking --log-opt max-buffer-size=4m alpine ping 127.0.0.1
```

### [Use environment variables or labels with logging drivers](#use-environment-variables-or-labels-with-logging-drivers)

Some logging drivers add the value of a container's `--env|-e` or `--label` flags to the container's logs. This example starts a container using the Docker daemon's default logging driver (in the following example, `json-file`) but sets the environment variable `os=ubuntu`.

```console
$ docker run -dit --label production_status=testing -e os=ubuntu alpine sh
```

If the logging driver supports it, this adds additional fields to the logging output. The following output is generated by the `json-file` logging driver:

```json
"attrs":{"production_status":"testing","os":"ubuntu"}
```

## [Supported logging drivers](#supported-logging-drivers)

The following logging drivers are supported. See the link to each driver's documentation for its configurable options, if applicable. If you are using [logging driver plugins](https://docs.docker.com/engine/logging/plugins/), you may see more options.

| Driver                                                                   | Description                                                                                                 |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `none`                                                                   | No logs are available for the container and `docker logs` does not return any output.                       |
| [`local`](https://docs.docker.com/engine/logging/drivers/local/)         | Logs are stored in a custom format designed for minimal overhead.                                           |
| [`json-file`](https://docs.docker.com/engine/logging/drivers/json-file/) | The logs are formatted as JSON. The default logging driver for Docker.                                      |
| [`syslog`](https://docs.docker.com/engine/logging/drivers/syslog/)       | Writes logging messages to the `syslog` facility. The `syslog` daemon must be running on the host machine.  |
| [`journald`](https://docs.docker.com/engine/logging/drivers/journald/)   | Writes log messages to `journald`. The `journald` daemon must be running on the host machine.               |
| [`gelf`](https://docs.docker.com/engine/logging/drivers/gelf/)           | Writes log messages to a Graylog Extended Log Format (GELF) endpoint such as Graylog or Logstash.           |
| [`fluentd`](https://docs.docker.com/engine/logging/drivers/fluentd/)     | Writes log messages to `fluentd` (forward input). The `fluentd` daemon must be running on the host machine. |
| [`awslogs`](https://docs.docker.com/engine/logging/drivers/awslogs/)     | Writes log messages to Amazon CloudWatch Logs.                                                              |
| [`splunk`](https://docs.docker.com/engine/logging/drivers/splunk/)       | Writes log messages to `splunk` using the HTTP Event Collector.                                             |
| [`etwlogs`](https://docs.docker.com/engine/logging/drivers/etwlogs/)     | Writes log messages as Event Tracing for Windows (ETW) events. Only available on Windows platforms.         |
| [`gcplogs`](https://docs.docker.com/engine/logging/drivers/gcplogs/)     | Writes log messages to Google Cloud Platform (GCP) Logging.                                                 |

## [Limitations of logging drivers](#limitations-of-logging-drivers)

* Reading log information requires decompressing rotated log files, which causes a temporary increase in disk usage (until the log entries from the rotated files are read) and an increased CPU usage while decompressing.
* The capacity of the host storage where the Docker data directory resides determines the maximum size of the log file information.

----
url: https://docs.docker.com/reference/cli/docker/model/purge/
----

# docker model purge

***

| Description | Remove all models              |
| ----------- | ------------------------------ |
| Usage       | `docker model purge [OPTIONS]` |

## [Description](#description)

Remove all models

## [Options](#options)

| Option        | Default | Description                  |
| ------------- | ------- | ---------------------------- |
| `-f, --force` |         | Forcefully remove all models |

----
url: https://docs.docker.com/guides/reactjs/run-tests/
----

# Run React.js tests in a container

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize React.js application](https://docs.docker.com/guides/reactjs/containerize/).

## [Overview](#overview)

Testing is a critical part of the development process. In this section, you'll learn how to:

* Run unit tests using Vitest inside a Docker container.
* Use Docker Compose to run tests in an isolated, reproducible environment.

You’ll use [Vitest](https://vitest.dev) — a blazing fast test runner designed for Vite — along with [Testing Library](https://testing-library.com/) for assertions.

***

## [Run tests during development](#run-tests-during-development)

`docker-reactjs-sample` application includes a sample test file at location:

```console
$ src/App.test.tsx
```

This file uses Vitest and React Testing Library to verify the behavior of `App` component.

### [Step 1: Install Vitest and React Testing Library](#step-1-install-vitest-and-react-testing-library)

If you haven’t already added the necessary testing tools, install them by running:

```console
$ npm install --save-dev vitest @testing-library/react @testing-library/jest-dom jsdom
```

Then, update the scripts section of your `package.json` file to include the following:

```json
"scripts": {
  "test": "vitest run"
}
```

***

### [Step 2: Configure Vitest](#step-2-configure-vitest)

Update `vitest.config.ts` file in your project root with the following configuration:

|                                                                  |                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```
``` | ```ts
/// <reference types="vitest" />

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  base: "/",
  plugins: [react()],
  server: {
    host: true,
    port: 5173,
    strictPort: true,
  },
  test: {
    environment: "jsdom",
    setupFiles: "./src/setupTests.ts",
    globals: true,
  },
});
``` |

> Note
>
> The `test` options in `vitest.config.ts` are essential for reliable testing inside Docker:
>
> * `environment: "jsdom"` simulates a browser-like environment for rendering and DOM interactions.
> * `setupFiles: "./src/setupTests.ts"` loads global configuration or mocks before each test file (optional but recommended).
> * `globals: true` enables global test functions like `describe`, `it`, and `expect` without importing them.
>
> For more details, see the official [Vitest configuration docs](https://vitest.dev/config/).

### [Step 3: Update compose.yaml](#step-3-update-composeyaml)

Add a new service named `react-test` to your `compose.yaml` file. This service allows you to run your test suite in an isolated containerized environment.

|                                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```
``` | ```yaml
services:
  react-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "5173:5173"
    develop:
      watch:
        - action: sync
          path: .
          target: /app

  react-prod:
    build:
      context: .
      dockerfile: Dockerfile
    image: docker-reactjs-sample
    ports:
      - "8080:8080"

  react-test:
    build:
      context: .
      dockerfile: Dockerfile.dev
    command: ["npm", "run", "test"]
``` |

The react-test service reuses the same `Dockerfile.dev` used for [development](https://docs.docker.com/guides/reactjs/develop/) and overrides the default command to run tests with `npm run test`. This setup ensures a consistent test environment that matches your local development configuration.

After completing the previous steps, your project directory should contain the following files:

```text
├── docker-reactjs-sample/
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ ├── .dockerignore
│ ├── compose.yaml
│ └── nginx.conf
```

### [Step 4: Run the tests](#step-4-run-the-tests)

To execute your test suite inside the container, run the following command from your project root:

```console
$ docker compose run --rm react-test
```

This command will:

* Start the `react-test` service defined in your `compose.yaml` file.
* Execute the `npm run test` script using the same environment as development.
* Automatically remove the container after the tests complete [`docker compose run --rm`](/reference/cli/docker/compose/run/) command.

> Note
>
> For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

***

## [Summary](#summary)

In this section, you learned how to run unit tests for your React.js application inside a Docker container using Vitest and Docker Compose.

What you accomplished:

* Installed and configured Vitest and React Testing Library for testing React components.
* Created a `react-test` service in `compose.yaml` to isolate test execution.
* Reused the development `Dockerfile.dev` to ensure consistency between dev and test environments.
* Ran tests inside the container using `docker compose run --rm react-test`.
* Ensured reliable, repeatable testing across environments without relying on local machine setup.

***

## [Related resources](#related-resources)

Explore official references and best practices to sharpen your Docker testing workflow:

* [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax.
* [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles.
* [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`.
* [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container.

***

## [Next steps](#next-steps)

Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions to automatically build and test your React.js application in a containerized environment. This ensures your code is validated on every push or pull request, maintaining consistency and reliability across your development workflow.

[Automate your builds with GitHub Actions »](https://docs.docker.com/guides/reactjs/configure-github-actions/)

----
url: https://docs.docker.com/reference/cli/docker/service/logs/
----

# docker service logs

***

| Description | Fetch the logs of a service or task           |
| ----------- | --------------------------------------------- |
| Usage       | `docker service logs [OPTIONS] SERVICE\|TASK` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

The `docker service logs` command batch-retrieves logs present at the time of execution.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

The `docker service logs` command can be used with either the name or ID of a service, or with the ID of a task. If a service is passed, it will display logs for all of the containers in that service. If a task is passed, it will only display logs from that particular task.

> Note
>
> This command is only functional for services that are started with the `json-file` or `journald` logging driver.

For more information about selecting and configuring logging drivers, refer to [Configure logging drivers](/engine/logging/configure/).

The `docker service logs --follow` command will continue streaming the new output from the service's `STDOUT` and `STDERR`.

Passing a negative number or a non-integer to `--tail` is invalid and the value is set to `all` in that case.

The `docker service logs --timestamps` command will add an [RFC3339Nano timestamp](https://pkg.go.dev/time#RFC3339Nano) , for example `2014-09-16T06:17:46.000000000Z`, to each log entry. To ensure that the timestamps are aligned the nano-second part of the timestamp will be padded with zero when necessary.

The `docker service logs --details` command will add on extra attributes, such as environment variables and labels, provided to `--log-opt` when creating the service.

The `--since` option shows only the service logs generated after a given date. You can specify the date as an RFC 3339 date, a UNIX timestamp, or a Go duration string (e.g. `1m30s`, `3h`). Besides RFC3339 date format you may also use RFC3339Nano, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local timezone on the client will be used if you do not provide either a `Z` or a `+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds\[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long. You can combine the `--since` option with either or both of the `--follow` or `--tail` options.

## [Options](#options)

| Option             | Default | Description                                                                                      |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------ |
| `--details`        |         | API 1.30+ Show extra details provided to logs                                                    |
| `-f, --follow`     |         | Follow log output                                                                                |
| `--no-resolve`     |         | Do not map IDs to Names in output                                                                |
| `--no-task-ids`    |         | Do not include task IDs in output                                                                |
| `--no-trunc`       |         | Do not truncate output                                                                           |
| `--raw`            |         | API 1.30+ Do not neatly format logs                                                              |
| `--since`          |         | Show logs since timestamp (e.g. `2013-01-02T13:23:37Z`) or relative (e.g. `42m` for 42 minutes)  |
| `-n, --tail`       | `all`   | Number of lines to show from the end of the logs                                                 |
| `-t, --timestamps` |         | Show timestamps                                                                                  |

----
url: https://docs.docker.com/subscription/faq/
----

# Subscription FAQs

***

Table of contents

***

For more information on Docker subscriptions, see [Docker subscription overview](https://docs.docker.com/subscription/).

## [Can I transfer my subscription from one user or organization account to another?](#can-i-transfer-my-subscription-from-one-user-or-organization-account-to-another)

Subscriptions are non-transferable between accounts or organizations.

## [Can I pause or delay my Docker subscription?](#can-i-pause-or-delay-my-docker-subscription)

You can't pause or delay a subscription, but you can downgrade your subscription. If a subscription invoice isn't paid by the due date, there's a 15-day grace period starting from the due date.

## [Does Docker offer academic pricing?](#does-docker-offer-academic-pricing)

Contact the [Docker Sales Team](https://www.docker.com/company/contact) for information about academic pricing options.

## [How can I contribute to Docker content?](#how-can-i-contribute-to-docker-content)

Docker offers two content contribution programs:

* [Docker-Sponsored Open Source Program (DSOS)](https://docs.docker.com/docker-hub/repos/manage/trusted-content/dsos-program/) for open source projects
* [Docker Verified Publisher (DVP)](https://docs.docker.com/docker-hub/repos/manage/trusted-content/dvp-program/) for commercial publishers

You can also join the [Developer Preview Program](https://www.docker.com/community/get-involved/developer-preview/) or sign up for early access programs to participate in research and try new features.

> Tip
>
> Need to upgrade? [Compare Docker Team and Docker Business](https://www.docker.com/pricing?ref=Docs\&refAction=DocsSubscriptionFaq) to choose the plan that best fits your team's needs.

----
url: https://docs.docker.com/dhi/how-to/select-enterprise/
----

# Get started with DHI Select and Enterprise

***

Table of contents

***

Subscription: Docker Hardened Images Select or Enterprise

This guide shows you how to get started with DHI Select and Enterprise subscriptions. Unlike DHI Community, this workflow lets you mirror repositories to your organization namespace on Docker Hub, access compliance variants (FIPS), customize images, and get SLA-backed updates.

## [Prerequisites](#prerequisites)

To use this workflow, you need:

* Organization owner access in your Docker Hub namespace.

* One of the following:

  * A DHI Select or Enterprise subscription. [Contact Docker sales](https://www.docker.com/products/hardened-images/#compare) to purchase DHI Enterprise or [learn more about DHI Select](https://docs.docker.com/subscription/setup/#set-up-docker-hardened-images-select-for-an-organization).
  * An active DHI trial. [Start a free DHI trial](https://hub.docker.com/hardened-images/start-free-trial).

* [Docker Desktop](https://docs.docker.com/desktop/release-notes/) 4.65 or later to use the `docker dhi` CLI.

Each step, when applicable, shows Docker Hub and command line instructions. You can use either interface.

## [Step 1: Find an image to use](#step-1-find-an-image-to-use)

1. Go to [Docker Hub](https://hub.docker.com/) and sign in.

2. Select your organization in the left sidebar.

3. Navigate to **Hardened Images** > **Catalog**.

4. Use the search bar or filters to find an image (for example, `python`, `node`, or `golang`). For this example, search for `python`.

   To search for an image with a compliance variant (FIPS or STIG), select **Filter by** and select the relevant compliance option.

5. Select the Python repository to view its details.

6. Select **Images** to view available image variants.

1) List available image repositories:

   ```console
   $ docker dhi catalog list --type image
   ```

2) To filter by name and FIPS compliance, use the `--filter` and `--fips` flags:

   ```console
   $ docker dhi catalog list --filter python --fips
   ```

3) Get image details for the repository:

   ```console
   $ docker dhi catalog get python
   ```

Continue to the next step to mirror the image. To dive deeper into exploring images see [Search and evaluate Docker Hardened Images](https://docs.docker.com/dhi/how-to/explore/).

## [Step 2: Mirror the repository](#step-2-mirror-the-repository)

Mirroring copies a DHI repository into your organization namespace on Docker Hub. This lets you receive SLA-backed Docker security patches for your images and use customization as well as compliance variants. Only organization owners can mirror repositories.

1. In the image repository details page you found in the previous step, select **Use this image** > **Mirror repository**. Note that you must be signed in to Docker Hub to perform this action.
2. Select **Mirror**.
3. Wait for images to finish mirroring. This can take a few minutes.
4. Verify the mirrored repository appears in your organization namespace with a `dhi-` prefix (for example, `dhi-python`).

To use the following commands, you must authenticate or configure DHI CLI authentication using your Docker token. For details, see [Use the DHI CLI](https://docs.docker.com/dhi/how-to/cli/#configuration).

1. Start mirroring the repository to your organization namespace. Replace `<your-org>` with your organization name.

   ```console
   $ docker dhi mirror start --org <your-org> dhi/python,<your-org>/dhi-python
   ```

2. Wait for images to finish mirroring. This can take a few minutes.

3. Verify the mirrored repository. Replace `<your-org>` with your organization name.

   ```console
   $ docker dhi mirror list --org <your-org>
   ```

Continue to the next step to customize the image. To dive deeper into mirroring images see [Mirror a repository](https://docs.docker.com/dhi/how-to/mirror/).

## [Step 3: Customize the image](#step-3-customize-the-image)

One of the key benefits of DHI Select and Enterprise is the ability to customize your mirrored images. You can add system packages, configure settings, or make other modifications to meet your organization's specific requirements.

This example shows how to add the `curl` system package to your mirrored Python image.

1. Go to your organization namespace on Docker Hub.
2. Navigate to your mirrored repository (for example, `dhi-python`).
3. Select **Customizations**.
4. Select **Create customization**.
5. Search for `3-alpine3.23` and select any one of the images.
6. In **Add packages**, select **curl**.
7. Select **Next: Configure**.
8. In **Customization name**, enter a name for your customization (for example, `curl`).
9. Select **Next: Review customization**.
10. Select **Create customization** to start the build.

It can take a few minutes for the customization to build. Go to the **Customizations** tab of your mirrored repository and view the **Last build** column to monitor the build status.

To use the following commands, you must authenticate or configure DHI CLI authentication using your Docker token. For details, see [Use the DHI CLI](https://docs.docker.com/dhi/how-to/cli/#configuration).

1. Create a customization. Replace `<your-org>` with your organization name. This creates a file called `my-customization.yaml` with the customization details.

   ```console
   $ docker dhi customization prepare --org <your-org> python 3-alpine3.23 \
       --destination <your-org>/dhi-python \
       --name "python with curl" \
       > my-customization.yaml
   ```

2. Add the `curl` package to the customization. You can edit the file with any text or code editor. The following commands use `echo` to add the necessary lines to the YAML file:

   ```console
   $ echo "contents:" >> my-customization.yaml
   $ echo "  packages:" >> my-customization.yaml
   $ echo "    - curl" >> my-customization.yaml
   ```

3. Apply the customization:

   ```console
   $ docker dhi customization create --org <your-org> my-customization.yaml
   ```

4. Verify the customization was created:

   ```console
   $ docker dhi customization list --org <your-org>
   ```

It can take a few minutes for the customization to build. To check the build status:

1. Go to your organization namespace on Docker Hub.
2. Navigate to your mirrored repository (for example, `dhi-python`).
3. Select **Customizations**.
4. View the **Last build** column to monitor the build status.

To dive deeper into customization, see [Customize a Docker Hardened Image](https://docs.docker.com/dhi/how-to/customize/).

## [Step 4: Pull and run your customized image](#step-4-pull-and-run-your-customized-image)

After the customization build completes, you can pull and run the customized image from your organization namespace on Docker Hub.

1. Sign in to Docker Hub:

   ```console
   $ docker login
   ```

2. Pull the customized image from your organization. Replace `<your-org>` with your organization name. The customized tag includes the suffix based on your customization name.

   ```console
   $ docker pull <your-org>/dhi-python:3-alpine3.23_python-with-curl
   ```

3. Run the image and test that `curl` is installed:

   ```console
   $ docker run --rm <your-org>/dhi-python:3-alpine3.23_python-with-curl curl --version
   ```

   This confirms that the `curl` package was successfully added to the image.

To dive deeper into using images, see:

* [Use a Docker Hardened Image](https://docs.docker.com/dhi/how-to/use/) for general usage
* [Use a Helm chart](https://docs.docker.com/dhi/how-to/helm/) for deploying with Helm

## [Step 5: Remove customization and stop mirroring](#step-5-remove-customization-and-stop-mirroring)

To remove the customization and stop mirroring the repository:

1. Go to your organization namespace on Docker Hub.
2. Navigate to your mirrored repository (for example, `dhi-python`).
3. Select **Customizations**.
4. Find the customization you want to delete (for example, `python with curl`).
5. Select the trash can icon.
6. Select **Delete customization** to confirm the deletion.
7. To stop mirroring, go back to your organization's repositories list.
8. Find the mirrored repository (for example, `dhi-python`).
9. Select **Settings**.
10. Select **Stop mirroring**.
11. Select **Stop mirroring** to confirm.

## [What's next](#whats-next)

You've mirrored, customized, and run a Docker Hardened Image. Here are a few ways to keep going:

* [Migrate existing applications to DHIs](https://docs.docker.com/dhi/migration/migrate-with-ai/): Use Gordon to update your Dockerfiles to use Docker Hardened Images as the base.

* [Verify DHIs](https://docs.docker.com/dhi/how-to/verify/): Use tools like [Docker Scout](/scout/) or Cosign to inspect and verify signed attestations, like SBOMs and provenance.

* [Scan DHIs](https://docs.docker.com/dhi/how-to/scan/): Analyze the image with Docker Scout or other scanners to identify known CVEs.

----
url: https://docs.docker.com/reference/cli/docker/scout/quickview/
----

# docker scout quickview

***

| Description                                                               | Quick overview of an image                           |
| ------------------------------------------------------------------------- | ---------------------------------------------------- |
| Usage                                                                     | `docker scout quickview [IMAGE\|DIRECTORY\|ARCHIVE]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker scout qv`                                    |

## [Description](#description)

The `docker scout quickview` command displays a quick overview of an image. It displays a summary of the vulnerabilities in the specified image and vulnerabilities from the base image. If available, it also displays base image refresh and update recommendations.

| Option                | Default             | Description                                                                                          |
| --------------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| `--env`               |                     | Name of the environment                                                                              |
| `--ignore-suppressed` |                     | Filter CVEs found in Scout exceptions based on the specified exception scope                         |
| `--latest`            |                     | Latest indexed image                                                                                 |
| `--only-policy`       |                     | Comma separated list of policies to evaluate                                                         |
| `--only-vex-affected` |                     | Filter CVEs by VEX statements with status not affected                                               |
| `--org`               |                     | Namespace of the Docker organization                                                                 |
| `-o, --output`        |                     | Write the report to a file                                                                           |
| `--platform`          |                     | Platform of image to analyze                                                                         |
| `--ref`               |                     | Reference to use if the provided tarball contains multiple references. Can only be used with archive |
| `--vex-author`        | `[<.*@docker.com>]` | List of VEX statement authors to accept                                                              |
| `--vex-location`      |                     | File location of directory or file containing VEX statements                                         |

## [Examples](#examples)

### [Quick overview of an image](#quick-overview-of-an-image)

```console
$ docker scout quickview golang:1.19.4
    ...Pulling
    ✓ Pulled
    ✓ SBOM of image already cached, 278 packages indexed

  Your image  golang:1.19.4                          │    5C     3H     6M    63L
  Base image  buildpack-deps:bullseye-scm            │    5C     1H     3M    48L     6?
  Refreshed base image  buildpack-deps:bullseye-scm  │    0C     0H     0M    42L
                                                     │    -5     -1     -3     -6     -6
  Updated base image  buildpack-deps:sid-scm         │    0C     0H     1M    29L
                                                     │    -5     -1     -2    -19     -6
```

### [Quick overview of the most recently built image](#quick-overview-of-the-most-recently-built-image)

```console
$ docker scout qv
```

### [Quick overview from an SPDX file](#quick-overview-from-an-spdx-file)

```console
$  syft -o spdx-json alpine:3.16.1 | docker scout quickview sbom://
 ✔ Loaded image                                                                                                                              alpine:3.16.1
 ✔ Parsed image                                                                    sha256:3d81c46cd8756ddb6db9ec36fa06a6fb71c287fb265232ba516739dc67a5f07d
 ✔ Cataloged contents                                                                     274a317d88b54f9e67799244a1250cad3fe7080f45249fa9167d1f871218d35f
   ├── ✔ Packages                        [14 packages]
   ├── ✔ File digests                    [75 files]
   ├── ✔ File metadata                   [75 locations]
   └── ✔ Executables                     [16 executables]

  Target   │ <stdin>        │    1C     2H     8M     0L
    digest │  274a317d88b5  │
```

----
url: https://docs.docker.com/reference/cli/docker/buildx/policy/
----

# docker buildx policy

***

| Description | Commands for working with build policies |
| ----------- | ---------------------------------------- |

## [Description](#description)

Commands for working with build policies

## [Subcommands](#subcommands)

| Command                                                                                         | Description                  |
| ----------------------------------------------------------------------------------------------- | ---------------------------- |
| [`docker buildx policy eval`](https://docs.docker.com/reference/cli/docker/buildx/policy/eval/) | Evaluate policy for a source |
| [`docker buildx policy test`](https://docs.docker.com/reference/cli/docker/buildx/policy/test/) | Run policy tests             |

----
url: https://docs.docker.com/build/cache/optimize/
----

# Optimize cache usage in builds

***

Table of contents

***

When building with Docker, a layer is reused from the build cache if the instruction and the files it depends on hasn't changed since it was previously built. Reusing layers from the cache speeds up the build process because Docker doesn't have to rebuild the layer again.

Here are a few techniques you can use to optimize build caching and speed up the build process:

* [Order your layers](#order-your-layers): Putting the commands in your Dockerfile into a logical order can help you avoid unnecessary cache invalidation.
* [Keep the context small](#keep-the-context-small): The context is the set of files and directories that are sent to the builder to process a build instruction. Keeping the context as small as possible reduces the amount of data that needs to be sent to the builder, and reduces the likelihood of cache invalidation.
* [Use bind mounts](#use-bind-mounts): Bind mounts let you mount a file or directory from the host machine into the build container. Using bind mounts can help you avoid unnecessary layers in the image, which can slow down the build process.
* [Use cache mounts](#use-cache-mounts): Cache mounts let you specify a persistent package cache to be used during builds. The persistent cache helps speed up build steps, especially steps that involve installing packages using a package manager. Having a persistent cache for packages means that even if you rebuild a layer, you only download new or changed packages.
* [Use an external cache](#use-an-external-cache): An external cache lets you store build cache at a remote location. The external cache image can be shared between multiple builds, and across different environments.

## [Order your layers](#order-your-layers)

Putting the commands in your Dockerfile into a logical order is a great place to start. Because a change causes a rebuild for steps that follow, try to make expensive steps appear near the beginning of the Dockerfile. Steps that change often should appear near the end of the Dockerfile, to avoid triggering rebuilds of layers that haven't changed.

Consider the following example. A Dockerfile snippet that runs a JavaScript build from the source files in the current directory:

```dockerfile
# syntax=docker/dockerfile:1
FROM node
WORKDIR /app
COPY . .          # Copy over all files in the current directory
RUN npm install   # Install dependencies
RUN npm build     # Run build
```

This Dockerfile is rather inefficient. Updating any file causes a reinstall of all dependencies every time you build the Docker image even if the dependencies didn't change since last time.

Instead, the `COPY` command can be split in two. First, copy over the package management files (in this case, `package.json` and `yarn.lock`). Then, install the dependencies. Finally, copy over the project source code, which is subject to frequent change.

```dockerfile
# syntax=docker/dockerfile:1
FROM node
WORKDIR /app
COPY package.json yarn.lock .    # Copy package management files
RUN npm install                  # Install dependencies
COPY . .                         # Copy over project files
RUN npm build                    # Run build
```

By installing dependencies in earlier layers of the Dockerfile, there is no need to rebuild those layers when a project file has changed.

## [Keep the context small](#keep-the-context-small)

The easiest way to make sure your context doesn't include unnecessary files is to create a `.dockerignore` file in the root of your build context. The `.dockerignore` file works similarly to `.gitignore` files, and lets you exclude files and directories from the build context.

Here's an example `.dockerignore` file that excludes the `node_modules` directory, all files and directories that start with `tmp`:

.dockerignore

```plaintext
node_modules
tmp*
```

Ignore-rules specified in the `.dockerignore` file apply to the entire build context, including subdirectories. This means it's a rather coarse-grained mechanism, but it's a good way to exclude files and directories that you know you don't need in the build context, such as temporary files, log files, and build artifacts.

## [Use bind mounts](#use-bind-mounts)

You might be familiar with bind mounts for when you run containers with `docker run` or Docker Compose. Bind mounts let you mount a file or directory from the host machine into a container.

```bash
# bind mount using the -v flag
docker run -v $(pwd):/path/in/container image-name
# bind mount using the --mount flag
docker run --mount=type=bind,src=.,dst=/path/in/container image-name
```

To use bind mounts in a build, you can use the `--mount` flag with the `RUN` instruction in your Dockerfile:

```dockerfile
FROM golang:latest
WORKDIR /build
RUN --mount=type=bind,target=. go build -o /app/hello
```

In this example, the current directory is mounted into the build container at `/build` before the `go build` command gets executed. The build output is written to `/app/hello`, which is outside the mount point. This distinction is important: the build output must be written outside the bind mount target, since the mount is read-only by default. The source code is available in the build container for the duration of that `RUN` instruction. When the instruction is done executing, the mounted files are not persisted in the final image, or in the build cache. Only the output of the `go build` command remains.

The `COPY` and `ADD` instructions in a Dockerfile lets you copy files from the build context into the build container. Using bind mounts is beneficial for build cache optimization because you're not adding unnecessary layers to the cache. If you have build context that's on the larger side, and it's only used to generate an artifact, you're better off using bind mounts to temporarily mount the source code required to generate the artifact into the build. If you use `COPY` to add the files to the build container, BuildKit will include all of those files in the cache, even if the files aren't used in the final image.

There are a few things to be aware of when using bind mounts in a build:

* Bind mounts are read-only by default. If you need to write to the mounted directory, you need to specify the `rw` option. However, even with the `rw` option, the changes are not persisted in the final image or the build cache. The file writes are sustained for the duration of the `RUN` instruction, and are discarded after the instruction is done.

* Mounted files are not persisted in the final image. Only the output of the `RUN` instruction is persisted in the final image. If you need to include files from the build context in the final image, you need to use the `COPY` or `ADD` instructions.

* If the target directory is not empty, the contents of the target directory are hidden by the mounted files. The original contents are restored after the `RUN` instruction is done.

  For example, given a build context with only a `Dockerfile` in it:

  ```plaintext
  .
  └── Dockerfile
  ```

  And a Dockerfile that mounts the current directory into the build container:

  ```dockerfile
  FROM alpine:latest
  WORKDIR /work
  RUN touch foo.txt
  RUN --mount=type=bind,target=. ls
  RUN ls
  ```

  The first `ls` command with the bind mount shows the contents of the mounted directory. The second `ls` lists the contents of the original build context.

  Build log

  ```plaintext
  #8 [stage-0 3/5] RUN touch foo.txt
  #8 DONE 0.1s

  #9 [stage-0 4/5] RUN --mount=target=. ls -1
  #9 0.040 Dockerfile
  #9 DONE 0.0s

  #10 [stage-0 5/5] RUN ls -1
  #10 0.046 foo.txt
  #10 DONE 0.1s
  ```

## [Use cache mounts](#use-cache-mounts)

Regular cache layers in Docker correspond to an exact match of the instruction and the files it depends on. If the instruction and the files it depends on have changed since the layer was built, the layer is invalidated, and the build process has to rebuild the layer.

Cache mounts are a way to specify a persistent cache location to be used during builds. The cache is cumulative across builds, so you can read and write to the cache multiple times. This persistent caching means that even if you need to rebuild a layer, you only download new or changed packages. Any unchanged packages are reused from the cache mount.

To use cache mounts in a build, you can use the `--mount` flag with the `RUN` instruction in your Dockerfile:

```dockerfile
FROM node:latest
WORKDIR /app
RUN --mount=type=cache,target=/root/.npm npm install
```

In this example, the `npm install` command uses a cache mount for the `/root/.npm` directory, the default location for the npm cache. The cache mount is persisted across builds, so even if you end up rebuilding the layer, you only download new or changed packages. Any changes to the cache are persisted across builds, and the cache is shared between multiple builds.

How you specify cache mounts depends on the build tool you're using. If you're unsure how to specify cache mounts, refer to the documentation for the build tool you're using. Here are a few examples:

```dockerfile
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go build -o /app/hello
```

```dockerfile
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
  --mount=type=cache,target=/var/lib/apt,sharing=locked \
  apt update && apt-get --no-install-recommends install -y gcc
```

```dockerfile
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt
```

```dockerfile
RUN --mount=type=cache,target=/root/.gem \
    bundle install
```

```dockerfile
RUN --mount=type=cache,target=/app/target/ \
    --mount=type=cache,target=/usr/local/cargo/git/db \
    --mount=type=cache,target=/usr/local/cargo/registry/ \
    cargo build
```

```dockerfile
RUN --mount=type=cache,target=/root/.nuget/packages \
    dotnet restore
```

```dockerfile
RUN --mount=type=cache,target=/tmp/cache \
    composer install
```

It's important that you read the documentation for the build tool you're using to make sure you're using the correct cache mount options. Package managers have different requirements for how they use the cache, and using the wrong options can lead to unexpected behavior. For example, Apt needs exclusive access to its data, so the caches use the option `sharing=locked` to ensure parallel builds using the same cache mount wait for each other and not access the same cache files at the same time.

## [Use an external cache](#use-an-external-cache)

The default cache storage for builds is internal to the builder (BuildKit instance) you're using. Each builder uses its own cache storage. When you switch between different builders, the cache is not shared between them. Using an external cache lets you define a remote location for pushing and pulling cache data.

External caches are especially useful for CI/CD pipelines, where the builders are often ephemeral, and build minutes are precious. Reusing the cache between builds can drastically speed up the build process and reduce cost. You can even make use of the same cache in your local development environment.

To use an external cache, you specify the `--cache-to` and `--cache-from` options with the `docker buildx build` command.

* `--cache-to` exports the build cache to the specified location.
* `--cache-from` specifies remote caches for the build to use.

The following example shows how to set up a GitHub Actions workflow using `docker/build-push-action`, and push the build cache layers to an OCI registry image:

.github/workflows/ci.yml

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:buildcache
          cache-to: type=registry,ref=user/app:buildcache,mode=max
```

This setup tells BuildKit to look for cache in the `user/app:buildcache` image. And when the build is done, the new build cache is pushed to the same image, overwriting the old cache.

This cache can be used locally as well. To pull the cache in a local build, you can use the `--cache-from` option with the `docker buildx build` command:

```console
$ docker buildx build --cache-from type=registry,ref=user/app:buildcache .
```

## [Summary](#summary)

Optimizing cache usage in builds can significantly speed up the build process. Keeping the build context small, using bind mounts, cache mounts, and external caches are all techniques you can use to make the most of the build cache and speed up the build process.

For more information about the concepts discussed in this guide, see:

* [.dockerignore files](https://docs.docker.com/build/concepts/context/#dockerignore-files)
* [Cache invalidation](https://docs.docker.com/build/cache/invalidation/)
* [Cache mounts](https://docs.docker.com/reference/dockerfile/#run---mounttypecache)
* [Cache backend types](https://docs.docker.com/build/cache/backends/)
* [Building best practices](https://docs.docker.com/build/building/best-practices/)

----
url: https://docs.docker.com/desktop/troubleshoot-and-support/faqs/macfaqs/
----

# FAQs for Docker Desktop for Mac

***

Table of contents

***

### [What is HyperKit?](#what-is-hyperkit)

HyperKit is a hypervisor built on top of the Hypervisor.framework in macOS. It runs entirely in userspace and has no other dependencies.

Docker uses HyperKit to eliminate the need for other VM products, such as Oracle VirtualBox or VMware Fusion.

### [What is the benefit of HyperKit?](#what-is-the-benefit-of-hyperkit)

HyperKit is thinner than VirtualBox and VMware fusion, and the version included is customized for Docker workloads on Mac.

### [Where does Docker Desktop store Linux containers and images?](#where-does-docker-desktop-store-linux-containers-and-images)

Docker Desktop stores Linux containers and images in a single, large "disk image" file in the Mac filesystem. This is different from Docker on Linux, which usually stores containers and images in the `/var/lib/docker` directory.

#### [Where is the disk image file?](#where-is-the-disk-image-file)

To locate the disk image file, select **Settings** from the Docker Desktop Dashboard then **Advanced** from the **Resources** tab.

The **Advanced** tab displays the location of the disk image. It also displays the maximum size of the disk image and the actual space the disk image is consuming. Note that other tools might display space usage of the file in terms of the maximum file size, and not the actual file size.

#### [What if the file is too big?](#what-if-the-file-is-too-big)

If the disk image file is too big, you can:

> Important
>
> Do not move the file directly in Finder as this can cause Docker Desktop to lose track of the file.

##### [How do I delete unnecessary containers and images?](#how-do-i-delete-unnecessary-containers-and-images)

Check whether you have any unnecessary containers and images. If your client and daemon API are running version 1.25 or later (use the `docker version` command on the client to check your client and daemon API versions), you can see the detailed space usage information by running:

```console
$ docker system df -v
```

Alternatively, to list images, run:

```console
$ docker image ls
```

To list containers, run:

```console
$ docker container ls -a
```

If there are lots of redundant objects, run the command:

```console
$ docker system prune
```

This command removes all stopped containers, unused networks, dangling images, and build cache.

It might take a few minutes to reclaim space on the host depending on the format of the disk image file. If the file is named:

* `Docker.raw`, space on the host is reclaimed within a few seconds.
* `Docker.qcow2`, space is freed by a background process after a few minutes.

Space is only freed when images are deleted. Space is not freed automatically when files are deleted inside running containers. To trigger a space reclamation at any point, run the command:

```console
$ docker run --privileged --pid=host docker/desktop-reclaim-space
```

Note that many tools report the maximum file size, not the actual file size. To query the actual size of the file on the host from a terminal, run:

```console
$ cd ~/Library/Containers/com.docker.docker/Data/vms/0/data
$ ls -klsh Docker.raw
2333548 -rw-r--r--@ 1 username  staff    64G Dec 13 17:42 Docker.raw
```

In this example, the actual size of the disk is `2333548` KB, whereas the maximum size of the disk is `64` GB.

##### [How do I reduce the maximum size of the file?](#how-do-i-reduce-the-maximum-size-of-the-file)

To reduce the maximum size of the disk image file:

1. Select **Settings** then **Advanced** from the **Resources** tab.

2. The **Disk image size** section contains a slider that allows you to change the maximum size of the disk image. Adjust the slider to set a lower limit.

3. Select **Apply**.

When you reduce the maximum size, the current disk image file is deleted, and therefore, all containers and images are lost.

### [How do I add TLS certificates?](#how-do-i-add-tls-certificates)

You can add trusted Certificate Authorities (CAs) (used to verify registry server certificates) and client certificates (used to authenticate to registries) to your Docker daemon.

#### [Add custom CA certificates (server side)](#add-custom-ca-certificates-server-side)

All trusted CAs (root or intermediate) are supported. Docker Desktop creates a certificate bundle of all user-trusted CAs based on the Mac Keychain, and appends it to Moby trusted certificates. So if an enterprise SSL certificate is trusted by the user on the host, it is trusted by Docker Desktop.

To manually add a custom, self-signed certificate, start by adding the certificate to the macOS keychain, which is picked up by Docker Desktop. Here is an example:

```console
$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt
```

Or, if you prefer to add the certificate to your own local keychain only (rather than for all users), run this command instead:

```console
$ security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain ca.crt
```

See also, [Directory structures for certificates](#directory-structures-for-certificates).

> Note
>
> You need to restart Docker Desktop after making any changes to the keychain or to the `~/.docker/certs.d` directory in order for the changes to take effect.

For a complete explanation of how to do this, see the blog post [Adding Self-signed Registry Certs to Docker & Docker Desktop for Mac](https://blog.container-solutions.com/adding-self-signed-registry-certs-docker-mac).

#### [Add client certificates](#add-client-certificates)

You can put your client certificates in `~/.docker/certs.d/<MyRegistry>:<Port>/client.cert` and `~/.docker/certs.d/<MyRegistry>:<Port>/client.key`.

When the Docker Desktop application starts, it copies the `~/.docker/certs.d` folder on your Mac to the `/etc/docker/certs.d` directory on Moby (the Docker Desktop `xhyve` virtual machine).

> Note
>
> * You need to restart Docker Desktop after making any changes to the keychain or to the `~/.docker/certs.d` directory in order for the changes to take effect.
>
> * The registry cannot be listed as an *insecure registry*. Docker Desktop ignores certificates listed under insecure registries, and does not send client certificates. Commands like `docker run` that attempt to pull from the registry produce error messages on the command line, as well as on the registry.

#### [Directory structures for certificates](#directory-structures-for-certificates)

If you have this directory structure, you do not need to manually add the CA certificate to your Mac OS system login:

```text
/Users/<user>/.docker/certs.d/
└── <MyRegistry>:<Port>
   ├── ca.crt
   ├── client.cert
   └── client.key
```

The following further illustrates and explains a configuration with custom certificates:

```text
/etc/docker/certs.d/        <-- Certificate directory
└── localhost:5000          <-- Hostname:port
   ├── client.cert          <-- Client certificate
   ├── client.key           <-- Client key
   └── ca.crt               <-- Certificate authority that signed
                                the registry certificate
```

You can also have this directory structure, as long as the CA certificate is also in your keychain.

```text
/Users/<user>/.docker/certs.d/
└── <MyRegistry>:<Port>
    ├── client.cert
    └── client.key
```

To learn more about how to install a CA root certificate for the registry and how to set the client TLS certificate for verification, see [Verify repository client with certificates](https://docs.docker.com/engine/security/certificates/) in the Docker Engine topics.

----
url: https://docs.docker.com/guides/nodejs/configure-github-actions/
----

# Automate your builds with GitHub Actions

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a Node.js application](https://docs.docker.com/guides/nodejs/containerize/).

You must also have:

* A [GitHub](https://github.com/signup) account.
* A verified [Docker Hub](https://hub.docker.com/signup) account.

***

## [Overview](#overview)

In this section, you'll set up a CI/CD pipeline using [GitHub Actions](https://docs.github.com/en/actions) to automatically:

* Build your Node.js application inside a Docker container.
* Run unit and integration tests, and make sure your application meets solid code quality standards.
* Perform security scanning and vulnerability assessment.
* Push production-ready images to [Docker Hub](https://hub.docker.com).

***

## [Connect your GitHub repository to Docker Hub](#connect-your-github-repository-to-docker-hub)

To enable GitHub Actions to build and push Docker images, you'll securely store your Docker Hub credentials in your new GitHub repository.

### [Step 1: Connect your GitHub repository to Docker Hub](#step-1-connect-your-github-repository-to-docker-hub)

1. Create a Personal Access Token (PAT) from [Docker Hub](https://hub.docker.com).

   1. From your Docker Hub account, go to **Account Settings → Security**.
   2. Generate a new Access Token with **Read/Write** permissions.
   3. Name it something like `docker-nodejs-sample`.
   4. Copy and save the token — you'll need it in Step 4.

2. Create a repository in [Docker Hub](https://hub.docker.com/repositories/).

   1. From your Docker Hub account, select **Create a repository**.
   2. For the Repository Name, use something descriptive — for example: `nodejs-sample`.
   3. Once created, copy and save the repository name — you'll need it in Step 4.

3. Create a new [GitHub repository](https://github.com/new) for your Node.js project.

4. Add Docker Hub credentials as GitHub repository secrets.

   In your newly created GitHub repository:

   1. From **Settings**, go to **Secrets and variables → Actions → New repository secret**.

   2. Add the following secrets:

   | Name                     | Value                                            |
   | ------------------------ | ------------------------------------------------ |
   | `DOCKER_USERNAME`        | Your Docker Hub username                         |
   | `DOCKERHUB_TOKEN`        | Your Docker Hub access token (created in Step 1) |
   | `DOCKERHUB_PROJECT_NAME` | Your Docker Project Name (created in Step 2)     |

   These secrets let GitHub Actions to authenticate securely with Docker Hub during automated workflows.

5. Connect your local project to GitHub.

   Link your local project `docker-nodejs-sample` to the GitHub repository you just created by running the following command from your project root:

   ```console
      $ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git
   ```

   > Important
   >
   > Replace `{your-username}` and `{your-repository}` with your actual GitHub username and repository name.

   To confirm that your local project is correctly connected to the remote GitHub repository, run:

   ```console
   $ git remote -v
   ```

   You should see output similar to:

   ```console
   origin  https://github.com/{your-username}/{your-repository-name}.git (fetch)
   origin  https://github.com/{your-username}/{your-repository-name}.git (push)
   ```

   This confirms that your local repository is properly linked and ready to push your source code to GitHub.

6. Push your source code to GitHub.

   Follow these steps to commit and push your local project to your GitHub repository:

   1. Stage all files for commit.

      ```console
      $ git add -A
      ```

      This command stages all changes — including new, modified, and deleted files — preparing them for commit.

   2. Commit your changes.

      ```console
      $ git commit -m "Initial commit with CI/CD pipeline"
      ```

      This command creates a commit that snapshots the staged changes with a descriptive message.

   3. Push the code to the `main` branch.

      ```console
      $ git push -u origin main
      ```

      This command pushes your local commits to the `main` branch of the remote GitHub repository and sets the upstream branch.

Once completed, your code will be available on GitHub, and any GitHub Actions workflow you've configured will run automatically.

> Note
>
> Learn more about the Git commands used in this step:
>
> * [Git add](https://git-scm.com/docs/git-add) – Stage changes (new, modified, deleted) for commit
> * [Git commit](https://git-scm.com/docs/git-commit) – Save a snapshot of your staged changes
> * [Git push](https://git-scm.com/docs/git-push) – Upload local commits to your GitHub repository
> * [Git remote](https://git-scm.com/docs/git-remote) – View and manage remote repository URLs

***

### [Step 2: Set up the workflow](#step-2-set-up-the-workflow)

Now you'll create a GitHub Actions workflow that builds your Docker image, runs tests, and pushes the image to Docker Hub.

1. From your repository on GitHub, select the **Actions** tab in the top menu.

2. When prompted, select **Set up a workflow yourself**.

   This opens an inline editor to create a new workflow file. By default, it will be saved to: `.github/workflows/main.yml`

3. Add the following workflow configuration to the new file:

```yaml
name: CI/CD – Node.js Application with Docker

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

jobs:
  test:
    name: Run Node.js Tests
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:18-alpine
        env:
          POSTGRES_DB: todoapp_test
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Cache npm dependencies
        uses: actions/cache@v5
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys: ${{ runner.os }}-npm-

      - name: Build test image
        uses: docker/build-push-action@v7
        with:
          context: .
          target: test
          tags: nodejs-app-test:latest
          platforms: linux/amd64
          load: true
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache,mode=max

      - name: Run tests inside container
        run: |
          docker run --rm \
            --network host \
            -e NODE_ENV=test \
            -e POSTGRES_HOST=localhost \
            -e POSTGRES_PORT=5432 \
            -e POSTGRES_DB=todoapp_test \
            -e POSTGRES_USER=postgres \
            -e POSTGRES_PASSWORD=postgres \
            nodejs-app-test:latest
        env:
          CI: true
        timeout-minutes: 10

  build-and-push:
    name: Build and Push Docker Image
    runs-on: ubuntu-latest
    needs: test

    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Cache Docker layers
        uses: actions/cache@v5
        with:
          path: /tmp/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: ${{ runner.os }}-buildx-

      - name: Extract metadata
        id: meta
        run: |
          echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT"
          echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"

      - name: Log in to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push multi-arch production image
        uses: docker/build-push-action@v7
        with:
          context: .
          target: production
          push: true
          platforms: linux/amd64,linux/arm64
          tags: |
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }}
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache,mode=max
```

This workflow performs the following tasks for your Node.js application:

* Triggers on every `push` or `pull request` to the `main` branch.
* Builds a test Docker image using the `test` stage.
* Runs tests in a containerized environment.
* Stops the workflow if any test fails.
* Caches Docker build layers and npm dependencies for faster runs.
* Authenticates with Docker Hub using GitHub secrets.
* Builds an image using the `production` stage.
* Tags and pushes the image to Docker Hub with `latest` and short SHA tags.

> Note
>
> For more information about `docker/build-push-action`, refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md).

***

### [Step 3: Run the workflow](#step-3-run-the-workflow)

After adding your workflow file, trigger the CI/CD process.

1. Commit and push your workflow file

   From the GitHub editor, select **Commit changes…**.

   * This push automatically triggers the GitHub Actions pipeline.

2. Monitor the workflow execution

   1. From your GitHub repository, go to the **Actions** tab.
   2. Select the workflow run to follow each step: `test`, `build`, `security`, and (if successful) `push` and `deploy`.

3. Verify the Docker image on Docker Hub

   * After a successful workflow run, visit your [Docker Hub repositories](https://hub.docker.com/repositories).

   * You should see a new image under your repository with:

     * Repository name: `${your-repository-name}`

     * Tags include:

       * `latest` – represents the most recent successful build; ideal for quick testing or deployment.
       * `<short-sha>` – a unique identifier based on the commit hash, useful for version tracking, rollbacks, and traceability.

> Tip
>
> To maintain code quality and prevent accidental direct pushes, enable branch protection rules:
>
> * From your GitHub repository, go to **Settings → Branches**.
>
> * Under Branch protection rules, select **Add rule**.
>
> * Specify `main` as the branch name.
>
> * Enable options like:
>
>   * *Require a pull request before merging*.
>   * *Require status checks to pass before merging*.
>
> This ensures that only tested and reviewed code is merged into `main` branch.

***

## [Summary](#summary)

In this section, you set up a comprehensive CI/CD pipeline for your containerized Node.js application using GitHub Actions.

What you accomplished:

* Created a new GitHub repository specifically for your project.

* Generated a Docker Hub access token and added it as a GitHub secret.

* Created a GitHub Actions workflow that:

  * Builds your application in a Docker container.
  * Run tests in a containerized environment.
  * Pushes an image to Docker Hub if tests pass.

* Verified the workflow runs successfully.

Your Node.js application now has automated testing and deployment.

***

## [Related resources](#related-resources)

Deepen your understanding of automation and best practices for containerized apps:

* [Introduction to GitHub Actions](https://docs.docker.com/guides/gha/) – Learn how GitHub Actions automate your workflows
* [Docker Build GitHub Actions](https://docs.docker.com/build/ci/github-actions/) – Set up container builds with GitHub Actions
* [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) – Full reference for writing GitHub workflows
* [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) – Learn about GHCR features and usage
* [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Optimize your image for performance and security

***

## [Next steps](#next-steps)

Next, learn how you can deploy your containerized Node.js application to Kubernetes with production-ready configuration. This helps you ensure your application behaves as expected in a production-like environment, reducing surprises during deployment.

----
url: https://docs.docker.com/guides/frameworks/laravel/prerequisites/
----

# Prerequisites for Setting Up Laravel with Docker Compose

***

Table of contents

***

Before you begin setting up Laravel with Docker Compose, make sure you meet the following prerequisites:

## [Docker and Docker Compose](#docker-and-docker-compose)

You need Docker and Docker Compose installed on your system. Docker allows you to containerize applications, and Docker Compose helps you manage multi-container applications.

* Docker: Make sure Docker is installed and running on your machine. Refer to the [Docker installation guide](/get-docker/) to install Docker.
* Docker Compose: Docker Compose is included with Docker Desktop, but you can also follow the [Docker Compose installation guide](/compose/install/) if needed.

## [Basic understanding of Docker and containers](#basic-understanding-of-docker-and-containers)

A fundamental understanding of Docker and how containers work will be helpful. If you're new to Docker, consider reviewing the [Docker Overview](/get-started/overview/) to familiarize yourself with containerization concepts.

## [Basic knowledge of Laravel](#basic-knowledge-of-laravel)

This guide assumes you have a basic understanding of Laravel and PHP. Familiarity with Laravel’s command-line tools, such as [Artisan](https://laravel.com/docs/12.x/artisan), and its project structure is important for following the instructions.

* Laravel CLI: You should be comfortable using Laravel’s command-line tool (`artisan`).
* Laravel Project Structure: Familiarize yourself with Laravel’s folder structure (`app`, `config`, `routes`, `tests`, etc.).

[Laravel Production Setup with Docker Compose »](https://docs.docker.com/guides/frameworks/laravel/production-setup/)

----
url: https://docs.docker.com/guides/testcontainers-java-micronaut-wiremock/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

```console
$ ./mvnw test
```

Or with Gradle:

```console
$ ./gradlew test
```

You should see the WireMock Docker container start in the console output. It acts as the photo service, serving mock responses based on the configured expectations. All tests should pass.

## [Summary](#summary)

You built a Micronaut application that integrates with an external REST API using declarative HTTP clients, then tested that integration using WireMock and the Testcontainers WireMock module. Testing at the HTTP protocol level instead of mocking Java methods lets you catch serialization issues and simulate realistic failure scenarios.

> Tip
>
> Testcontainers WireMock modules are available for Go and Python as well.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testcontainers WireMock module](https://testcontainers.com/modules/wiremock/)
* [WireMock documentation](https://wiremock.org/docs/)
* [Testcontainers JUnit 5 quickstart](https://java.testcontainers.org/quickstart/junit_5_quickstart/)
* [Testing REST API integrations in Spring Boot using WireMock](/guides/testcontainers-java-wiremock/)

----
url: https://docs.docker.com/engine/logging/dual-logging/
----

# Use docker logs with remote logging drivers

***

Table of contents

***

## [Overview](#overview)

You can use the `docker logs` command to read container logs regardless of the configured logging driver or plugin. Docker Engine uses the [`local`](https://docs.docker.com/engine/logging/drivers/local/) logging driver to act as cache for reading the latest logs of your containers. This is called dual logging. By default, the cache has log-file rotation enabled, and is limited to a maximum of 5 files of 20 MB each (before compression) per container.

Refer to the [configuration options](#configuration-options) section to customize these defaults, or to the [disable dual logging](#disable-the-dual-logging-cache) section to disable this feature.

## [Prerequisites](#prerequisites)

Docker Engine automatically enables dual logging if the configured logging driver doesn't support reading logs.

The following examples show the result of running a `docker logs` command with and without dual logging availability:

### [Without dual logging capability](#without-dual-logging-capability)

When a container is configured with a remote logging driver such as `splunk`, and dual logging is disabled, an error is displayed when attempting to read container logs locally:

* Step 1: Configure Docker daemon

  ```console
  $ cat /etc/docker/daemon.json
  {
    "log-driver": "splunk",
    "log-opts": {
      "cache-disabled": "true",
      ... (options for "splunk" logging driver)
    }
  }
  ```

* Step 2: Start the container

  ```console
  $ docker run -d busybox --name testlog top
  ```

* Step 3: Read the container logs

  ```console
  $ docker logs 7d6ac83a89a0
  Error response from daemon: configured logging driver does not support reading
  ```

### [With dual logging capability](#with-dual-logging-capability)

With the dual logging cache enabled, the `docker logs` command can be used to read logs, even if the logging driver doesn't support reading logs. The following example shows a daemon configuration that uses the `splunk` remote logging driver as a default, with dual logging caching enabled:

* Step 1: Configure Docker daemon

  ```console
  $ cat /etc/docker/daemon.json
  {
    "log-driver": "splunk",
    "log-opts": {
      ... (options for "splunk" logging driver)
    }
  }
  ```

* Step 2: Start the container

  ```console
  $ docker run -d busybox --name testlog top
  ```

* Step 3: Read the container logs

  ```console
  $ docker logs 7d6ac83a89a0
  2019-02-04T19:48:15.423Z [INFO]  core: marked as sealed
  2019-02-04T19:48:15.423Z [INFO]  core: pre-seal teardown starting
  2019-02-04T19:48:15.423Z [INFO]  core: stopping cluster listeners
  2019-02-04T19:48:15.423Z [INFO]  core: shutting down forwarding rpc listeners
  2019-02-04T19:48:15.423Z [INFO]  core: forwarding rpc listeners stopped
  2019-02-04T19:48:15.599Z [INFO]  core: rpc listeners successfully shut down
  2019-02-04T19:48:15.599Z [INFO]  core: cluster listeners successfully shut down
  ```

> Note
>
> For logging drivers that support reading logs, such as the `local`, `json-file` and `journald` drivers, there is no difference in functionality before or after the dual logging capability became available. For these drivers, Logs can be read using `docker logs` in both scenarios.

### [Configuration options](#configuration-options)

The dual logging cache accepts the same configuration options as the [`local` logging driver](https://docs.docker.com/engine/logging/drivers/local/), but with a `cache-` prefix. These options can be specified per container, and defaults for new containers can be set using the [daemon configuration file](/reference/cli/dockerd/#daemon-configuration-file).

By default, the cache has log-file rotation enabled, and is limited to a maximum of 5 files of 20MB each (before compression) per container. Use the configuration options described below to customize these defaults.

| Option           | Default   | Description                                                                                                                                       |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cache-disabled` | `"false"` | Disable local caching. Boolean value passed as a string (`true`, `1`, `0`, or `false`).                                                           |
| `cache-max-size` | `"20m"`   | The maximum size of the cache before it is rotated. A positive integer plus a modifier representing the unit of measure (`k`, `m`, or `g`).       |
| `cache-max-file` | `"5"`     | The maximum number of cache files that can be present. If rotating the logs creates excess files, the oldest file is removed. A positive integer. |
| `cache-compress` | `"true"`  | Enable or disable compression of rotated log files. Boolean value passed as a string (`true`, `1`, `0`, or `false`).                              |

## [Disable the dual logging cache](#disable-the-dual-logging-cache)

Use the `cache-disabled` option to disable the dual logging cache. Disabling the cache can be useful to save storage space in situations where logs are only read through a remote logging system, and if there is no need to read logs through `docker logs` for debugging purposes.

Caching can be disabled for individual containers or by default for new containers, when using the [daemon configuration file](/reference/cli/dockerd/#daemon-configuration-file).

The following example uses the daemon configuration file to use the [`splunk`](https://docs.docker.com/engine/logging/drivers/splunk/) logging driver as a default, with caching disabled:

```console
$ cat /etc/docker/daemon.json
{
  "log-driver": "splunk",
  "log-opts": {
    "cache-disabled": "true",
    ... (options for "splunk" logging driver)
  }
}
```

> Note
>
> For logging drivers that support reading logs, such as the `local`, `json-file` and `journald` drivers, dual logging isn't used, and disabling the option has no effect.

## [Limitations](#limitations)

* If a container using a logging driver or plugin that sends logs remotely has a network issue, no `write` to the local cache occurs.
* If a write to `logdriver` fails for any reason (file system full, write permissions removed), the cache write fails and is logged in the daemon log. The log entry to the cache isn't retried.
* Some logs might be lost from the cache in the default configuration because a ring buffer is used to prevent blocking the stdio of the container in case of slow file writes. An admin must repair these while the daemon is shut down.

----
url: https://docs.docker.com/reference/cli/sbx/template/load/
----

# sbx template load

| Description | Load an image from a tar file into the sandbox runtime |
| ----------- | ------------------------------------------------------ |
| Usage       | `sbx template load FILE [flags]`                       |

## [Description](#description)

Load an image from a tar file into the sandbox runtime's image store.

The loaded image can be used as a template for new sandboxes. Tar files are typically created with: sbx template save SANDBOX TAG --output FILE

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Load an image from a tar file
sbx template load /tmp/myimage.tar              # Linux/macOS
sbx template load C:\Users\me\myimage.tar       # Windows

# Use the loaded image as a template
sbx run -t myimage:v1.0 claude
```

----
url: https://docs.docker.com/admin/organization/
----

# Organization overview

***

Table of contents

***

A Docker organization is a collection of teams and repositories with centralized management. It helps administrators group members and assign access in a streamlined, scalable way.

## [Organization structure](#organization-structure)

The following diagram shows how organizations relate to teams and members.

## [Organization members](#organization-members)

Organization owners have full administrator access to manage members, roles, and teams across the organization.

An organization includes members and optional teams. Teams help group members and simplify permission management.

## [Create and manage your organization](#create-and-manage-your-organization)

Learn how to create and manage your organization in the following sections.

### [Onboard your organization](/admin/organization/setup/onboard)

[Learn how to onboard and secure your organization.](/admin/organization/setup/onboard)

### [Manage members](/admin/organization/manage/members/)

[Explore how to manage members.](/admin/organization/manage/members/)

### [Activity logs](/admin/activity-logs/)

[Learn how to audit the activities of your members.](/admin/activity-logs/)

### [Image Access Management](/admin/organization/image-access/)

[Control which types of images your developers can pull.](/admin/organization/image-access/)

### [Registry Access Management](/admin/organization/registry-access/)

[Define which registries your developers can access.](/admin/organization/registry-access/)

### [Organization settings](/admin/organization/setup/general-settings/)

[Configure information for your organization and manage settings.](/admin/organization/setup/general-settings/)

### SSO and SCIM

Set up [Single Sign-On](https://docs.docker.com/enterprise/security/single-sign-on/) and [SCIM](https://docs.docker.com/enterprise/security/provisioning/scim/) for your organization.

### [Domain management](/enterprise/security/domain-management/)

[Add, verify, and audit your domains.](/enterprise/security/domain-management/)

### [FAQs](/faq/admin/organization-faqs/)

[Explore common organization FAQs.](/faq/admin/organization-faqs/)

----
url: https://docs.docker.com/reference/cli/docker/trust/inspect/
----

# docker trust inspect

***

| Description | Return low-level information about keys and signatures |
| ----------- | ------------------------------------------------------ |
| Usage       | `docker trust inspect IMAGE[:TAG] [IMAGE[:TAG]...]`    |

## [Description](#description)

`docker trust inspect` provides low-level JSON information on signed repositories. This includes all image tags that are signed, who signed them, and who can sign new tags.

## [Options](#options)

| Option     | Default | Description                                      |
| ---------- | ------- | ------------------------------------------------ |
| `--pretty` |         | Print the information in a human friendly format |

## [Examples](#examples)

### [Get low-level details about signatures for a single image tag](#get-low-level-details-about-signatures-for-a-single-image-tag)

Use the `docker trust inspect` to get trust information about an image. The following example prints trust information for the `alpine:latest` image:

```console
$ docker trust inspect alpine:latest
```

The output is in JSON format, for example:

```json
[
  {
    "Name": "alpine:latest",
    "SignedTags": [
      {
        "SignedTag": "latest",
        "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478",
        "Signers": [
          "Repo Admin"
        ]
      }
    ],
    "Signers": [],
    "AdministrativeKeys": [
      {
        "Name": "Repository",
        "Keys": [
            {
                "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd"
            }
        ]
      },
      {
        "Name": "Root",
        "Keys": [
            {
                "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce"
            }
        ]
      }
    ]
  }
]
```

The `SignedTags` key will list the `SignedTag` name, its `Digest`, and the `Signers` responsible for the signature.

`AdministrativeKeys` will list the `Repository` and `Root` keys.

If signers are set up for the repository via other `docker trust` commands, `docker trust inspect` includes a `Signers` key:

```console
$ docker trust inspect my-image:purple
```

The output is in JSON format, for example:

```json
[
  {
    "Name": "my-image:purple",
    "SignedTags": [
      {
        "SignedTag": "purple",
        "Digest": "941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557",
        "Signers": [
          "alice",
          "bob",
          "carol"
        ]
      }
    ],
    "Signers": [
      {
        "Name": "alice",
        "Keys": [
            {
                "ID": "04dd031411ed671ae1e12f47ddc8646d98f135090b01e54c3561e843084484a3"
            },
            {
                "ID": "6a11e4898a4014d400332ab0e096308c844584ff70943cdd1d6628d577f45fd8"
            }
        ]
      },
      {
        "Name": "bob",
        "Keys": [
            {
                "ID": "433e245c656ae9733cdcc504bfa560f90950104442c4528c9616daa45824ccba"
            }
        ]
      },
      {
        "Name": "carol",
        "Keys": [
            {
                "ID": "d32fa8b5ca08273a2880f455fcb318da3dc80aeae1a30610815140deef8f30d9"
            },
            {
                "ID": "9a8bbec6ba2af88a5fad6047d428d17e6d05dbdd03d15b4fc8a9a0e8049cd606"
            }
        ]
      }
    ],
    "AdministrativeKeys": [
      {
        "Name": "Repository",
        "Keys": [
            {
                "ID": "27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44"
            }
        ]
      },
      {
        "Name": "Root",
        "Keys": [
            {
                "ID": "40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f"
            }
        ]
      }
    ]
  }
]
```

If the image tag is unsigned or unavailable, `docker trust inspect` does not display any signed tags.

```console
$ docker trust inspect unsigned-img

no signatures or cannot access unsigned-img
```

However, if other tags are signed in the same image repository, `docker trust inspect` reports relevant key information:

```console
$ docker trust inspect alpine:unsigned
```

The output is in JSON format, for example:

```json
[
  {
    "Name": "alpine:unsigned",
    "Signers": [],
    "AdministrativeKeys": [
      {
        "Name": "Repository",
        "Keys": [
          {
            "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd"
          }
        ]
      },
      {
        "Name": "Root",
        "Keys": [
          {
            "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce"
          }
        ]
      }
    ]
  }
]
```

### [Get details about signatures for all image tags in a repository](#get-details-about-signatures-for-all-image-tags-in-a-repository)

If no tag is specified, `docker trust inspect` will report details for all signed tags in the repository:

```console
$ docker trust inspect alpine
```

The output is in JSON format, for example:

```json
[
  {
    "Name": "alpine",
    "SignedTags": [
      {
        "SignedTag": "3.5",
        "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c",
        "Signers": [
          "Repo Admin"
        ]
      },
      {
        "SignedTag": "3.6",
        "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478",
        "Signers": [
          "Repo Admin"
        ]
      },
      {
        "SignedTag": "edge",
        "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096",
        "Signers": [
          "Repo Admin"
        ]
      },
      {
        "SignedTag": "latest",
        "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478",
        "Signers": [
          "Repo Admin"
        ]
      }
    ],
    "Signers": [],
    "AdministrativeKeys": [
      {
        "Name": "Repository",
        "Keys": [
          {
            "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd"
          }
        ]
      },
      {
        "Name": "Root",
        "Keys": [
          {
            "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce"
          }
        ]
      }
    ]
  }
]
```

### [Get details about signatures for multiple images](#get-details-about-signatures-for-multiple-images)

`docker trust inspect` can take multiple repositories and images as arguments, and reports the results in an ordered list:

```console
$ docker trust inspect alpine notary
```

The output is in JSON format, for example:

```json
[
  {
    "Name": "alpine",
    "SignedTags": [
      {
        "SignedTag": "3.5",
        "Digest": "b007a354427e1880de9cdba533e8e57382b7f2853a68a478a17d447b302c219c",
        "Signers": [
          "Repo Admin"
        ]
      },
      {
        "SignedTag": "3.6",
        "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478",
        "Signers": [
          "Repo Admin"
        ]
      },
      {
        "SignedTag": "edge",
        "Digest": "23e7d843e63a3eee29b6b8cfcd10e23dd1ef28f47251a985606a31040bf8e096",
        "Signers": [
          "Repo Admin"
        ]
      },
      {
        "SignedTag": "integ-test-base",
        "Digest": "3952dc48dcc4136ccdde37fbef7e250346538a55a0366e3fccc683336377e372",
        "Signers": [
          "Repo Admin"
        ]
      },
      {
        "SignedTag": "latest",
        "Digest": "d6bfc3baf615dc9618209a8d607ba2a8103d9c8a405b3bd8741d88b4bef36478",
        "Signers": [
          "Repo Admin"
        ]
      }
    ],
    "Signers": [],
    "AdministrativeKeys": [
      {
        "Name": "Repository",
        "Keys": [
          {
            "ID": "5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd"
          }
        ]
      },
      {
        "Name": "Root",
        "Keys": [
          {
            "ID": "a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce"
          }
        ]
      }
    ]
  },
  {
    "Name": "notary",
    "SignedTags": [
      {
        "SignedTag": "server",
        "Digest": "71f64ab718a3331dee103bc5afc6bc492914738ce37c2d2f127a8133714ecf5c",
        "Signers": [
          "Repo Admin"
        ]
      },
      {
        "SignedTag": "signer",
        "Digest": "a6122d79b1e74f70b5dd933b18a6d1f99329a4728011079f06b245205f158fe8",
        "Signers": [
          "Repo Admin"
        ]
      }
    ],
    "Signers": [],
    "AdministrativeKeys": [
      {
        "Name": "Root",
        "Keys": [
          {
            "ID": "8cdcdef5bd039f4ab5a029126951b5985eebf57cabdcdc4d21f5b3be8bb4ce92"
          }
        ]
      },
      {
        "Name": "Repository",
        "Keys": [
          {
            "ID": "85bfd031017722f950d480a721f845a2944db26a3dc084040a70f1b0d9bbb3df"
          }
        ]
      }
    ]
  }
]
```

### [Formatting](#formatting)

You can print the inspect output in a human-readable format instead of the default JSON output, by using the `--pretty` option:

### [Get details about signatures for a single image tag](#get-details-about-signatures-for-a-single-image-tag)

```console
$ docker trust inspect --pretty alpine:latest

SIGNED TAG          DIGEST                                                             SIGNERS
latest              1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe   (Repo Admin)

Administrative keys for alpine:latest:
Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd
Root Key:       a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce
```

The `SIGNED TAG` is the signed image tag with a unique content-addressable `DIGEST`. `SIGNERS` lists all entities who have signed.

The administrative keys listed specify the root key of trust, as well as the administrative repository key. These keys are responsible for modifying signers, and rotating keys for the signed repository.

If signers are set up for the repository via other `docker trust` commands, `docker trust inspect --pretty` displays them appropriately as a `SIGNER` and specify their `KEYS`:

```console
$ docker trust inspect --pretty my-image:purple

SIGNED TAG          DIGEST                                                              SIGNERS
purple              941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557    alice, bob, carol

List of signers and their keys:

SIGNER              KEYS
alice               47caae5b3e61, a85aab9d20a4
bob                 034370bcbd77, 82a66673242c
carol               b6f9f8e1aab0

Administrative keys for my-image:
Repository Key: 27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44
Root Key:       40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f
```

However, if other tags are signed in the same image repository, `docker trust inspect` reports relevant key information.

```console
$ docker trust inspect --pretty alpine:unsigned

No signatures for alpine:unsigned


Administrative keys for alpine:unsigned:
Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd
Root Key:       a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce
```

### [Get details about signatures for all image tags in a repository](#get-details-about-signatures-for-all-image-tags-in-a-repository-1)

```console
$ docker trust inspect --pretty alpine

SIGNED TAG          DIGEST                                                             SIGNERS
2.6                 9ace551613070689a12857d62c30ef0daa9a376107ec0fff0e34786cedb3399b   (Repo Admin)
2.7                 9f08005dff552038f0ad2f46b8e65ff3d25641747d3912e3ea8da6785046561a   (Repo Admin)
3.1                 d9477888b78e8c6392e0be8b2e73f8c67e2894ff9d4b8e467d1488fcceec21c8   (Repo Admin)
3.2                 19826d59171c2eb7e90ce52bfd822993bef6a6fe3ae6bb4a49f8c1d0a01e99c7   (Repo Admin)
3.3                 8fd4b76819e1e5baac82bd0a3d03abfe3906e034cc5ee32100d12aaaf3956dc7   (Repo Admin)
3.4                 833ad81ace8277324f3ca8c91c02bdcf1d13988d8ecf8a3f97ecdd69d0390ce9   (Repo Admin)
3.5                 af2a5bd2f8de8fc1ecabf1c76611cdc6a5f1ada1a2bdd7d3816e121b70300308   (Repo Admin)
3.6                 1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe   (Repo Admin)
edge                79d50d15bd7ea48ea00cf3dd343b0e740c1afaa8e899bee475236ef338e1b53b   (Repo Admin)
latest              1072e499f3f655a032e88542330cf75b02e7bdf673278f701d7ba61629ee3ebe   (Repo Admin)

Administrative keys for alpine:
Repository Key: 5a46c9aaa82ff150bb7305a2d17d0c521c2d784246807b2dc611f436a69041fd
Root Key:       a2489bcac7a79aa67b19b96c4a3bf0c675ffdf00c6d2fabe1a5df1115e80adce
```

Here's an example with signers that are set up by `docker trust` commands:

```console
$ docker trust inspect --pretty my-image

SIGNED TAG          DIGEST                                                              SIGNERS
red                 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943    alice
blue                f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197    alice, bob
green               cae8fedc840f90c8057e1c24637d11865743ab1e61a972c1c9da06ec2de9a139    alice, bob
yellow              9cc65fc3126790e683d1b92f307a71f48f75fa7dd47a7b03145a123eaf0b45ba    carol
purple              941d3dba358621ce3c41ef67b47cf80f701ff80cdf46b5cc86587eaebfe45557    alice, bob, carol
orange              d6c271baa6d271bcc24ef1cbd65abf39123c17d2e83455bdab545a1a9093fc1c    alice

List of signers and their keys for my-image:

SIGNER              KEYS
alice               47caae5b3e61, a85aab9d20a4
bob                 034370bcbd77, 82a66673242c
carol               b6f9f8e1aab0

Administrative keys for my-image:
Repository Key: 27df2c8187e7543345c2e0bf3a1262e0bc63a72754e9a7395eac3f747ec23a44
Root Key:       40b66ccc8b176be8c7d365a17f3e046d1c3494e053dd57cfeacfe2e19c4f8e8f
```

----
url: https://docs.docker.com/compose/support-and-feedback/faq/
----

# Frequently asked questions about Docker Compose

***

Table of contents

***

### [What is the difference between `docker compose` and `docker-compose`](#what-is-the-difference-between-docker-compose-and-docker-compose)

Version one of the Docker Compose command-line binary was first released in 2014. It was written in Python, and is invoked with `docker-compose`. Typically, Compose v1 projects include a top-level version element in the `compose.yaml` file, with values ranging from 2.0 to 3.8, which refer to the specific file formats.

Version two of the Docker Compose command-line binary was announced in 2020, is written in Go, and is invoked with `docker compose`. Compose v2 ignores the version top-level element in the compose.yaml file.

For further information, see [History and development of Compose](https://docs.docker.com/compose/intro/history/).

### [What's the difference between `up`, `run`, and `start`?](#whats-the-difference-between-up-run-and-start)

Typically, you want `docker compose up`. Use `up` to start or restart all the services defined in a `compose.yaml`. In the default "attached" mode, you see all the logs from all the containers. In "detached" mode (`-d`), Compose exits after starting the containers, but the containers continue to run in the background.

The `docker compose run` command is for running "one-off" or "adhoc" tasks. It requires the service name you want to run and only starts containers for services that the running service depends on. Use `run` to run tests or perform an administrative task such as removing or adding data to a data volume container. The `run` command acts like `docker run -ti` in that it opens an interactive terminal to the container and returns an exit status matching the exit status of the process in the container.

The `docker compose start` command is useful only to restart containers that were previously created but were stopped. It never creates new containers.

### [Why do my services take 10 seconds to recreate or stop?](#why-do-my-services-take-10-seconds-to-recreate-or-stop)

The `docker compose stop` command attempts to stop a container by sending a `SIGTERM`. It then waits for a [default timeout of 10 seconds](/reference/cli/docker/compose/stop/). After the timeout, a `SIGKILL` is sent to the container to forcefully kill it. If you are waiting for this timeout, it means that your containers aren't shutting down when they receive the `SIGTERM` signal.

There has already been a lot written about this problem of [processes handling signals](https://medium.com/@gchudnov/trapping-signals-in-docker-containers-7a57fdda7d86) in containers.

To fix this problem, try the following:

* Make sure you're using the exec form of `CMD` and `ENTRYPOINT` in your Dockerfile.

  For example use `["program", "arg1", "arg2"]` not `"program arg1 arg2"`. Using the string form causes Docker to run your process using `bash` which doesn't handle signals properly. Compose always uses the JSON form, so don't worry if you override the command or entrypoint in your Compose file.

* If you are able, modify the application that you're running to add an explicit signal handler for `SIGTERM`.

* Set the `stop_signal` to a signal which the application knows how to handle:

  ```yaml
  services:
    web:
      build: .
      stop_signal: SIGINT
  ```

* If you can't modify the application, wrap the application in a lightweight init system (like [s6](https://skarnet.org/software/s6/)) or a signal proxy (like [dumb-init](https://github.com/Yelp/dumb-init) or [tini](https://github.com/krallin/tini)). Either of these wrappers takes care of handling `SIGTERM` properly.

### [How do I run multiple copies of a Compose file on the same host?](#how-do-i-run-multiple-copies-of-a-compose-file-on-the-same-host)

Compose uses the project name to create unique identifiers for all of a project's containers and other resources. To run multiple copies of a project, set a custom project name using the `-p` command line option or the [`COMPOSE_PROJECT_NAME` environment variable](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_project_name).

### [Can I use JSON instead of YAML for my Compose file?](#can-i-use-json-instead-of-yaml-for-my-compose-file)

Yes. [YAML is a superset of JSON](https://stackoverflow.com/a/1729545/444646) so any JSON file should be valid YAML. To use a JSON file with Compose, specify the filename to use, for example:

```console
$ docker compose -f compose.json up
```

### [Should I include my code with `COPY`/`ADD` or a volume?](#should-i-include-my-code-with-copyadd-or-a-volume)

You can add your code to the image using `COPY` or `ADD` directive in a `Dockerfile`. This is useful if you need to relocate your code along with the Docker image, for example when you're sending code to another environment (production, CI, etc).

Use a `volume` if you want to make changes to your code and see them reflected immediately, for example when you're developing code and your server supports hot code reloading or live-reload.

There may be cases where you want to use both. You can have the image include the code using a `COPY`, and use a `volume` in your Compose file to include the code from the host during development. The volume overrides the directory contents of the image.

----
url: https://docs.docker.com/enterprise/enterprise-deployment/pkg-install-and-configure/
----

# PKG installer

***

Table of contents

***

Subscription: Business

For: Administrators

The PKG package supports various MDM (Mobile Device Management) solutions, making it ideal for bulk installations and eliminating the need for manual setups by individual users. With this package, IT administrators can ensure standardized, policy-driven installations of Docker Desktop, enhancing efficiency and software management across their organizations.

## [Install interactively](#install-interactively)

1. In [Docker Home](http://app.docker.com), choose your organization.

2. Select **Admin Console**, then **Enterprise deployment**.

3. From the **macOS** tab, select the **Download PKG installer** button.

4. Once downloaded, double-click `Docker.pkg` to run the installer.

5. Follow the instructions on the installation wizard to authorize the installer and proceed with the installation.

   * **Introduction**: Select **Continue**.
   * **License**: Review the license agreement and select **Agree**.
   * **Destination Select**: This step is optional. It is recommended that you keep the default installation destination (usually `Macintosh HD`). Select **Continue**.
   * **Installation Type**: Select **Install**.
   * **Installation**: Authenticate using your administrator password or Touch ID.
   * **Summary**: When the installation completes, select **Close**.

> Note
>
> When installing Docker Desktop with the PKG, in-app updates are automatically disabled. This ensures organizations can maintain version consistency and prevent unapproved updates. For Docker Desktop installed with the `.dmg` installer, in-app updates remain supported.
>
> Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from the Docker Admin Console. Navigate to the **Enterprise deployment** page.
>
> To keep up to date with new releases, check the [release notes](https://docs.docker.com/desktop/release-notes/) page.

## [Install from the command line](#install-from-the-command-line)

1. In [Docker Home](http://app.docker.com), choose your organization.

2. Select **Admin Console**, then **Enterprise deployment**.

3. From the **macOS** tab, select the **Download PKG installer** button.

4. From your terminal, run the following command:

   ```console
   $ sudo installer -pkg "/path/to/Docker.pkg" -target /Applications
   ```

## [Additional resources](#additional-resources)

* See how you can deploy Docker Desktop for Mac using [Intune](https://docs.docker.com/enterprise/enterprise-deployment/use-intune/) or [Jamf Pro](https://docs.docker.com/enterprise/enterprise-deployment/use-jamf-pro/)
* Explore how to [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#plist-method-mac-only) for your users.

----
url: https://docs.docker.com/guides/testcontainers-java-quarkus/write-tests/
----

# Write tests with Testcontainers

***

Table of contents

***

## [Quarkus Dev Services](#quarkus-dev-services)

Quarkus Dev Services automatically provisions unconfigured services in development and test mode. When you include an extension and don't configure it, Quarkus starts the relevant service using [Testcontainers](https://www.testcontainers.org/) behind the scenes and wires the application to use that service.

> Note
>
> Dev Services requires a [supported Docker environment](https://www.testcontainers.org/supported_docker_environment/).

Quarkus Dev Services supports most commonly used services like SQL databases, Kafka, RabbitMQ, Redis, and MongoDB. For more information, see the [Quarkus Dev Services guide](https://quarkus.io/guides/dev-services).

## [Write tests for the API endpoints](#write-tests-for-the-api-endpoints)

Test the `GET /api/customers` and `POST /api/customers` endpoints using REST Assured. The `io.rest-assured:rest-assured` library was already added as a test dependency when you generated the project.

Create `CustomerResourceTest.java` and annotate it with `@QuarkusTest`. This bootstraps the application along with the required services using Dev Services. Because you haven't configured datasource properties, Dev Services automatically starts a PostgreSQL database using Testcontainers.

```java
package com.testcontainers.demo;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;
import static org.junit.jupiter.api.Assertions.assertFalse;

import io.quarkus.test.junit.QuarkusTest;
import io.restassured.common.mapper.TypeRef;
import io.restassured.http.ContentType;
import java.util.List;
import org.junit.jupiter.api.Test;

@QuarkusTest
class CustomerResourceTest {

    @Test
    void shouldGetAllCustomers() {
        List<Customer> customers = given().when()
                .get("/api/customers")
                .then()
                .statusCode(200)
                .extract()
                .as(new TypeRef<>() {});
        assertFalse(customers.isEmpty());
    }

    @Test
    void shouldCreateCustomerSuccessfully() {
        Customer customer = new Customer(null, "John", "john@gmail.com");
        given().contentType(ContentType.JSON)
                .body(customer)
                .when()
                .post("/api/customers")
                .then()
                .statusCode(201)
                .body("name", is("John"))
                .body("email", is("john@gmail.com"));
    }
}
```

Here's what the test does:

* `@QuarkusTest` starts the full Quarkus application with Dev Services enabled.
* Dev Services starts a PostgreSQL container using Testcontainers and configures the datasource automatically.
* `shouldGetAllCustomers()` calls `GET /api/customers` and verifies that seeded data from the Flyway migration is returned.
* `shouldCreateCustomerSuccessfully()` sends a `POST /api/customers` request and verifies the response contains the created customer data.

## [Customize test configuration](#customize-test-configuration)

By default, the Quarkus test instance starts on port 8081 and uses a `postgres:14` Docker image. Customize both by adding these properties to `src/main/resources/application.properties`:

```properties
quarkus.http.test-port=0
quarkus.datasource.devservices.image-name=postgres:15.2-alpine
```

Setting `quarkus.http.test-port=0` starts the application on a random available port, avoiding port conflicts. The `devservices.image-name` property lets you pin the PostgreSQL image to a specific version that matches production.

## [Test with services not supported by Dev Services](#test-with-services-not-supported-by-dev-services)

Your application might use a service that Dev Services doesn't support out of the box. In that case, use `QuarkusTestResourceLifecycleManager` to start the service before the Quarkus application starts for testing.

For example, suppose the application uses CockroachDB. First, add the CockroachDB Testcontainers module dependency:

```xml
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>cockroachdb</artifactId>
    <scope>test</scope>
</dependency>
```

Create a `CockroachDBTestResource` that implements `QuarkusTestResourceLifecycleManager`:

```java
package com.testcontainers.demo;

import io.quarkus.test.common.QuarkusTestResourceLifecycleManager;
import java.util.HashMap;
import java.util.Map;
import org.testcontainers.containers.CockroachContainer;

public class CockroachDBTestResource implements QuarkusTestResourceLifecycleManager {

    CockroachContainer cockroachdb;

    @Override
    public Map<String, String> start() {
        cockroachdb = new CockroachContainer("cockroachdb/cockroach:v22.2.0");
        cockroachdb.start();
        Map<String, String> conf = new HashMap<>();
        conf.put("quarkus.datasource.jdbc.url", cockroachdb.getJdbcUrl());
        conf.put("quarkus.datasource.username", cockroachdb.getUsername());
        conf.put("quarkus.datasource.password", cockroachdb.getPassword());
        return conf;
    }

    @Override
    public void stop() {
        cockroachdb.stop();
    }
}
```

Use the `CockroachDBTestResource` with `@QuarkusTestResource` in a test class:

```java
package com.testcontainers.demo;

import static io.restassured.RestAssured.given;
import static org.junit.jupiter.api.Assertions.assertFalse;

import io.quarkus.test.common.QuarkusTestResource;
import io.quarkus.test.junit.QuarkusTest;
import io.restassured.common.mapper.TypeRef;
import java.util.List;
import org.junit.jupiter.api.Test;

@QuarkusTest
@QuarkusTestResource(value = CockroachDBTestResource.class, restrictToAnnotatedClass = true)
class CockroachDBTest {

    @Test
    void shouldGetAllCustomers() {
        List<Customer> customers = given().when()
                .get("/api/customers")
                .then()
                .statusCode(200)
                .extract()
                .as(new TypeRef<>() {});
        assertFalse(customers.isEmpty());
    }
}
```

The `restrictToAnnotatedClass = true` attribute ensures the CockroachDB container only starts when running this specific test class, rather than being activated for all tests.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-quarkus/run-tests/)

----
url: https://docs.docker.com/admin/company/manage/users/
----

# Manage company members

***

Table of contents

***

Subscription: Business

For: Administrators

Company owners can invite new members to an organization via Docker ID, email address, or in bulk with a CSV file containing email addresses.

If an invitee does not have a Docker account, they must create an account and verify their email address before they can accept an invitation to join the organization. Pending invitations occupy seats for the organization the user is invited to.

## [Invite members via Docker ID or email address](#invite-members-via-docker-id-or-email-address)

Use the following steps to invite members to your organization via Docker ID or email address.

1. Sign in to [Docker Home](https://app.docker.com) and select your company.

2. On the **Organizations** page, select the organization you want to invite members to.

3. Select **Members**, then **Invite**.

4. Select **Emails or usernames**.

5. Follow the on-screen instructions to invite members. Invite a maximum of 1000 members and separate multiple entries by comma, semicolon, or space.

   > Note
   >
   > When you invite members, you assign them a role. See [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/core-roles/) for details about the access permissions for each role.

   Pending invitations appear on the Members page. The invitees receive an email with a link to Docker Hub where they can accept or decline the invitation.

## [Invite members via CSV file](#invite-members-via-csv-file)

To invite multiple members to an organization via a CSV file containing email addresses:

1. Sign in to [Docker Home](https://app.docker.com) and select your company.

2. On the **Organizations** page, select the organization you want to invite members to.

3. Select **Members**, then **Invite**.

4. Select **CSV upload**.

5. Select **Download the template CSV file** to optionally download an example CSV file. The following is an example of the contents of a valid CSV file.

   ```text
   email
   docker.user-0@example.com
   docker.user-1@example.com
   ```

   CSV file requirements:

   * The file must contain a header row with at least one heading named `email`. Additional columns are allowed and are ignored in the import.
   * The file must contain a maximum of 1000 email addresses (rows). To invite more than 1000 users, create multiple CSV files and perform all steps in this task for each file.

6. Create a new CSV file or export a CSV file from another application.

   * To export a CSV file from another application, see the application’s documentation.
   * To create a new CSV file, open a new file in a text editor, type `email` on the first line, type the user email addresses one per line on the following lines, and then save the file with a .csv extension.

7. Select **Browse files** and then select your CSV file, or drag and drop the CSV file into the **Select a CSV file to upload** box. You can only select one CSV file at a time.

   > Note
   >
   > If the amount of email addresses in your CSV file exceeds the number of available seats in your organization, you cannot continue to invite members. To invite members, you can purchase more seats, or remove some email addresses from the CSV file and re-select the new file. To purchase more seats, see [Add seats to your subscription](https://docs.docker.com/subscription/manage-seats/#add-seats-to-your-subscription) or [Contact sales](https://www.docker.com/pricing/contact-sales/).

8. After the CSV file has been uploaded, select **Review**.

   Valid email addresses and any email addresses that have issues will appear. Email addresses may have the following issues:

   * Invalid email: The email address is not a valid address. The email address will be ignored if you send invites. You can correct the email address in the CSV file and re-import the file.
   * Already invited: The user has already been sent an invite email and another invite email will not be sent.
   * Member: The user is already a member of your organization and an invite email will not be sent.
   * Duplicate: The CSV file has multiple occurrences of the same email address. The user will be sent only one invite email.

9. Follow the on-screen instructions to invite members.

   > Note
   >
   > When you invite members, you assign them a role. See [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/core-roles/) for details about the access permissions for each role.

Pending invitations appear on the Members page. The invitees receive an email with a link to Docker Hub where they can accept or decline the invitation.

## [Resend invitations to users](#resend-invitations-to-users)

You can resend individual invitations, or bulk invitations from the Admin Console.

### [Resend individual invitations](#resend-individual-invitations)

1. In [Docker Home](https://app.docker.com/), select your company from the top-left account drop-down.
2. Select **Admin Console**, then **Users**.
3. Select the **action menu** next to the invitee and select **Resend**.
4. Select **Invite** to confirm.

### [Bulk resend invitation](#bulk-resend-invitation)

1. In [Docker Home](https://app.docker.com/), select your company from the top-left account drop-down.
2. Select **Admin Console**, then **Users**.
3. Use the **checkboxes** next to **Usernames** to bulk select users.
4. Select **Resend invites**.
5. Select **Resend** to confirm.

## [Invite members via API](#invite-members-via-api)

You can bulk invite members using the Docker Hub API. For more information, see the [Bulk create invites](https://docs.docker.com/reference/api/hub/latest/#tag/invites/paths/~1v2~1invites~1bulk/post) API endpoint.

## [Manage members on a team](#manage-members-on-a-team)

Use Docker Hub to add a member to a team or remove a member from a team. For more details, see [Manage members](https://docs.docker.com/admin/organization/manage/members/#manage-members-on-a-team).

----
url: https://docs.docker.com/engine/security/rootless/troubleshoot/
----

***

Table of contents

***

### [Distribution-specific hint](#distribution-specific-hint)

* Ubuntu 24.04 and later enables restricted unprivileged user namespaces by default, which prevents unprivileged processes in creating user namespaces unless an AppArmor profile is configured to allow programs to use unprivileged user namespaces.

  If you install `docker-ce-rootless-extras` using the deb package (`apt-get install docker-ce-rootless-extras`), then the AppArmor profile for `rootlesskit` is already bundled with the `apparmor` deb package. With this installation method, you don't need to add any manual the AppArmor configuration. If you install the rootless extras using the [installation script](https://get.docker.com/rootless), however, you must add an AppArmor profile for `rootlesskit` manually:

  1. Create and install the currently logged-in user's AppArmor profile:

     ```console
     $ filename=$(echo $HOME/bin/rootlesskit | sed -e 's@^/@@' -e 's@/@.@g')
     $ [ ! -z "${filename}" ] && sudo cat <<EOF > /etc/apparmor.d/${filename}
     abi <abi/4.0>,
     include <tunables/global>

     "$HOME/bin/rootlesskit" flags=(unconfined) {
       userns,

       include if exists <local/${filename}>
     }
     EOF
     ```

  2. Restart AppArmor.

     ```console
     $ systemctl restart apparmor.service
     ```

- Add `kernel.unprivileged_userns_clone=1` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl --system`

* `sudo modprobe ip_tables iptable_mangle iptable_nat iptable_filter` is required. This might be required on other distributions as well depending on the configuration.

* Known to work on openSUSE 15 and SLES 15.

- For RHEL 8 and similar distributions, installing `fuse-overlayfs` is recommended. Run `sudo dnf install -y fuse-overlayfs`. This step is not required on RHEL 9 and similar distributions.

- You might need `sudo dnf install -y iptables`.

## [Known limitations](#known-limitations)

* Only the following storage drivers are supported:

  * `overlay2` (only if running with kernel 5.11 or later)
  * `fuse-overlayfs` (only if running with kernel 4.18 or later, and `fuse-overlayfs` is installed)
  * `btrfs` (only if running with kernel 4.18 or later, or `~/.local/share/docker` is mounted with `user_subvol_rm_allowed` mount option)
  * `vfs`

* cgroup is supported only when running with cgroup v2 and systemd. See [Limiting resources](https://docs.docker.com/engine/security/rootless/tips/#limiting-resources).

* Following features are not supported:

  * AppArmor
  * Checkpoint
  * Overlay network
  * Exposing SCTP ports

* To use the `ping` command, see [Routing ping packets](https://docs.docker.com/engine/security/rootless/tips/#routing-ping-packets).

* To expose privileged TCP/UDP ports (< 1024), see [Exposing privileged ports](https://docs.docker.com/engine/security/rootless/tips/#exposing-privileged-ports).

* NFS mounts as the docker "data-root" is not supported. This limitation is not specific to rootless mode.

### [Historical limitations](#historical-limitations)

#### [Until Docker Engine v29.5](#until-docker-engine-v295)

* `IPAddress` shown in `docker inspect` is namespaced inside RootlessKit's network namespace. This means the IP address is not reachable from the host without `nsenter`-ing into the network namespace.
* Host network (`docker run --net=host`) is also namespaced inside RootlessKit.

## [Troubleshooting](#troubleshooting)

### [Unable to install with systemd when systemd is present on the system](#unable-to-install-with-systemd-when-systemd-is-present-on-the-system)

```console
$ dockerd-rootless-setuptool.sh install
[INFO] systemd not detected, dockerd-rootless.sh needs to be started manually:
...
```

`rootlesskit` cannot detect systemd properly if you switch to your user via `sudo su`. For users which cannot be logged-in, you must use the `machinectl` command which is part of the `systemd-container` package. After installing `systemd-container` switch to `myuser` with the following command:

```console
$ sudo machinectl shell myuser@
```

Where `myuser@` is your desired username and @ signifies this machine.

### [Errors when starting the Docker daemon](#errors-when-starting-the-docker-daemon)

**\[rootlesskit:parent] error: failed to start the child: fork/exec /proc/self/exe: operation not permitted**

This error occurs mostly when the value of `/proc/sys/kernel/unprivileged_userns_clone` is set to 0:

```console
$ cat /proc/sys/kernel/unprivileged_userns_clone
0
```

To fix this issue, add `kernel.unprivileged_userns_clone=1` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl --system`.

**\[rootlesskit:parent] error: failed to start the child: fork/exec /proc/self/exe: no space left on device**

This error occurs mostly when the value of `/proc/sys/user/max_user_namespaces` is too small:

```console
$ cat /proc/sys/user/max_user_namespaces
0
```

To fix this issue, add `user.max_user_namespaces=28633` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl --system`.

**\[rootlesskit:parent] error: failed to setup UID/GID map: failed to compute uid/gid map: No subuid ranges found for user 1001 ("testuser")**

This error occurs when `/etc/subuid` and `/etc/subgid` are not configured. See [Prerequisites](https://docs.docker.com/engine/security/rootless/#prerequisites).

**could not get XDG\_RUNTIME\_DIR**

This error occurs when `$XDG_RUNTIME_DIR` is not set.

On a non-systemd host, you need to create a directory and then set the path:

```console
$ export XDG_RUNTIME_DIR=$HOME/.docker/xrd
$ rm -rf $XDG_RUNTIME_DIR
$ mkdir -p $XDG_RUNTIME_DIR
$ dockerd-rootless.sh
```

> Note
>
> You must remove the directory every time you log out.

On a systemd host, log into the host using `pam_systemd` (see below). The value is automatically set to `/run/user/$UID` and cleaned up on every logout.

**`systemctl --user` fails with "Failed to connect to bus: No such file or directory"**

This error occurs mostly when you switch from the root user to a non-root user with `sudo`:

```console
# sudo -iu testuser
$ systemctl --user start docker
Failed to connect to bus: No such file or directory
```

Instead of `sudo -iu <USERNAME>`, you need to log in using `pam_systemd`. For example:

* Log in through the graphic console
* `ssh <USERNAME>@localhost`
* `machinectl shell <USERNAME>@`

**The daemon does not start up automatically**

You need `sudo loginctl enable-linger $(whoami)` to enable the daemon to start up automatically. See [Advanced Usage](https://docs.docker.com/engine/security/rootless/tips/#advanced-usage).

### [`docker pull` errors](#docker-pull-errors)

**docker: failed to register layer: Error processing tar file(exit status 1): lchown \<FILE>: invalid argument**

This error occurs when the number of available entries in `/etc/subuid` or `/etc/subgid` is not sufficient. The number of entries required vary across images. However, 65,536 entries are sufficient for most images. See [Prerequisites](https://docs.docker.com/engine/security/rootless/#prerequisites).

**docker: failed to register layer: ApplyLayer exit status 1 stdout: stderr: lchown \<FILE>: operation not permitted**

This error occurs mostly when `~/.local/share/docker` is located on NFS.

A workaround is to specify non-NFS `data-root` directory in `~/.config/docker/daemon.json` as follows:

```json
{"data-root":"/somewhere-out-of-nfs"}
```

### [`docker run` errors](#docker-run-errors)

**docker: Error response from daemon: OCI runtime create failed: ...: read unix @->/run/systemd/private: read: connection reset by peer: unknown.**

This error occurs on cgroup v2 hosts mostly when the dbus daemon is not running for the user.

```console
$ systemctl --user is-active dbus
inactive

$ docker run hello-world
docker: Error response from daemon: OCI runtime create failed: container_linux.go:380: starting container process caused: process_linux.go:385: applying cgroup configuration for process caused: error while starting unit "docker
-931c15729b5a968ce803784d04c7421f791d87e5ca1891f34387bb9f694c488e.scope" with properties [{Name:Description Value:"libcontainer container 931c15729b5a968ce803784d04c7421f791d87e5ca1891f34387bb9f694c488e"} {Name:Slice Value:"use
r.slice"} {Name:PIDs Value:@au [4529]} {Name:Delegate Value:true} {Name:MemoryAccounting Value:true} {Name:CPUAccounting Value:true} {Name:IOAccounting Value:true} {Name:TasksAccounting Value:true} {Name:DefaultDependencies Val
ue:false}]: read unix @->/run/systemd/private: read: connection reset by peer: unknown.
```

To fix the issue, run `sudo apt-get install -y dbus-user-session` or `sudo dnf install -y dbus-daemon`, and then relogin.

If the error still occurs, try running `systemctl --user enable --now dbus` (without sudo).

**`--cpus`, `--memory`, and `--pids-limit` are ignored**

This is an expected behavior on cgroup v1 mode. To use these flags, the host needs to be configured for enabling cgroup v2. For more information, see [Limiting resources](https://docs.docker.com/engine/security/rootless/tips/#limiting-resources).

### [Networking errors](#networking-errors)

This section provides troubleshooting tips for networking in rootless mode.

Networking in rootless mode is supported via network and port drivers in RootlessKit. Network performance and characteristics depend on the combination of network and port driver you use. If you're experiencing unexpected behavior or performance related to networking, review the following table which shows the configurations supported by RootlessKit, and how they compare:

| Network driver     | Port driver        | Net throughput | Port throughput | Source IP propagation | No SUID | Note                                                                         |
| ------------------ | ------------------ | -------------- | --------------- | --------------------- | ------- | ---------------------------------------------------------------------------- |
| `gvisor-tap-vsock` | `builtin`          | Slow           | Fast ✅          | ✅ (\*)                | ✅       | Default when slirp4netns is not installed                                    |
| `slirp4netns`      | `builtin`          | Slow           | Fast ✅          | ✅ (\*)                | ✅       | Default when slirp4netns is installed                                        |
| `vpnkit`           | `builtin`          | Slow           | Fast ✅          | ✅ (\*)                | ✅       | Legacy                                                                       |
| `gvisor-tap-vsock` | `gvisor-tap-vsock` | Slow           | Slow            | ❌                     | ✅       | Not recommended. Use `builtin` port driver instead.                          |
| `slirp4netns`      | `slirp4netns`      | Slow           | Slow            | ✅                     | ✅       |                                                                              |
| `pasta`            | `implicit`         | Slow           | Fast ✅          | ✅                     | ✅       | Experimental; Needs pasta version 2023\_12\_04 or later                      |
| `lxc-user-nic`     | `builtin`          | Fast ✅         | Fast ✅          | ✅ (\*)                | ❌       | Experimental                                                                 |
| `bypass4netns`     | `bypass4netns`     | Fast ✅         | Fast ✅          | ✅                     | ✅       | **Note:** Not integrated to RootlessKit as it needs a custom seccomp profile |

(\*) Applicable since RootlessKit v3.0. Also requires `userland-proxy` to be disabled.

For information about troubleshooting specific networking issues, see:

* [`docker run -p` fails with `cannot expose privileged port`](#docker-run--p-fails-with-cannot-expose-privileged-port)
* [Ping doesn't work](#ping-doesnt-work)
* [`IPAddress` shown in `docker inspect` is unreachable](#ipaddress-shown-in-docker-inspect-is-unreachable)
* [`--net=host` doesn't listen ports on the host network namespace](#--nethost-doesnt-listen-ports-on-the-host-network-namespace)
* [Network is slow](#network-is-slow)
* [`docker run -p` does not propagate source IP addresses](#docker-run--p-does-not-propagate-source-ip-addresses)

#### [`docker run -p` fails with `cannot expose privileged port`](#docker-run--p-fails-with-cannot-expose-privileged-port)

`docker run -p` fails with this error when a privileged port (< 1024) is specified as the host port.

```console
$ docker run -p 80:80 nginx:alpine
docker: Error response from daemon: driver failed programming external connectivity on endpoint focused_swanson (9e2e139a9d8fc92b37c36edfa6214a6e986fa2028c0cc359812f685173fa6df7): Error starting userland proxy: error while calling PortManager.AddPort(): cannot expose privileged port 80, you might need to add "net.ipv4.ip_unprivileged_port_start=0" (currently 1024) to /etc/sysctl.conf, or set CAP_NET_BIND_SERVICE on rootlesskit binary, or choose a larger port number (>= 1024): listen tcp 0.0.0.0:80: bind: permission denied.
```

When you experience this error, consider using an unprivileged port instead. For example, 8080 instead of 80.

```console
$ docker run -p 8080:80 nginx:alpine
```

To allow exposing privileged ports, see [Exposing privileged ports](https://docs.docker.com/engine/security/rootless/tips/#exposing-privileged-ports).

#### [Ping doesn't work](#ping-doesnt-work)

Ping does not work when `/proc/sys/net/ipv4/ping_group_range` is set to `1 0`:

```console
$ cat /proc/sys/net/ipv4/ping_group_range
1       0
```

For details, see [Routing ping packets](https://docs.docker.com/engine/security/rootless/tips/#routing-ping-packets).

#### [`IPAddress` shown in `docker inspect` is unreachable](#ipaddress-shown-in-docker-inspect-is-unreachable)

This was an expected behavior until Docker Engine v29.5, as the daemon was namespaced inside RootlessKit's network namespace. Use `docker run -p` instead, or upgrade to Docker Engine v29.5 or later.

#### [`--net=host` doesn't listen ports on the host network namespace](#--nethost-doesnt-listen-ports-on-the-host-network-namespace)

This was an expected behavior until Docker Engine v29.5, as the daemon was namespaced inside RootlessKit's network namespace. Use `docker run -p` instead, or upgrade to Docker Engine v29.5 or later.

#### [Network is slow](#network-is-slow)

Docker with rootless mode uses a TCP/IP stack running in user mode, such as:

* [slirp4netns](https://github.com/rootless-containers/slirp4netns) (default when slirp4netns is installed)
* [pasta](https://passt.top/passt/about/)
* [VPNKit](https://github.com/moby/vpnkit)
* [gvisor-tap-vsock](https://github.com/containers/gvisor-tap-vsock) (default when none of the above is installed)

The TCP/IP stack in user mode is generally slower than the one in kernel mode, and the performance may vary depending on the network driver used.

See [RootlessKit documentation](https://github.com/rootless-containers/rootlesskit/blob/v3.0.0/docs/network.md) for more information.

##### [Workaround 1: bypass user-mode TCP/IP stack](#workaround-1-bypass-user-mode-tcpip-stack)

Use `docker run --net=host` to bypass the user-mode TCP/IP stack. This is applicable since Docker Engine v29.5. However, this requires the container to share the host network namespace, which may not be desirable for security reasons.

##### [Workaround 2: disable user-mode TCP/IP stack](#workaround-2-disable-user-mode-tcpip-stack)

Alternatively, you can use the `lxc-user-nic` network driver (experimental) to disable the user-mode TCP/IP stack entirely. However, this requires configuring `/etc/lxc/lxc-usernet` for enabling the privileged helper.

```bash
sudo apt-get install -y lxc
sudo mkdir -p /etc/lxc
cat <<EOF | sudo tee /etc/lxc/lxc-usernet
# USERNAME TYPE BRIDGE COUNT
$USER veth lxcbr0 10
EOF
```

Also, make sure that the rootful daemon is not running, as its iptables rules may interfere with the `lxc-user-nic` driver.

```console
$ systemctl is-active docker.service
inactive

$ systemctl is-active docker.socket
inactive
```

The network driver can be specified by creating `~/.config/systemd/user/docker.service.d/override.conf` with the following content:

```systemd
[Service]
Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_NET=lxc-user-nic"
# Optional: specify MTU (may affect throughput)
# Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_MTU=INTEGER"
```

And then restart the daemon:

```bash
systemctl --user daemon-reload
systemctl --user restart docker
```

#### [`docker run -p` does not propagate source IP addresses](#docker-run--p-does-not-propagate-source-ip-addresses)

This is because Docker Engine's `userland-proxy` is incompatible with RootlessKit's source IP propagation.

To disable userland-proxy, add the following configuration to `~/.config/docker/daemon.json`:

```json
{"userland-proxy": false}
```

Then restart the daemon:

```bash
systemctl --user restart docker
```

You may also need to load `br_netfilter` kernel module:

```bash
sudo tee /etc/modules-load.d/docker.conf <<EOF >/dev/null
br_netfilter
EOF

sudo systemctl restart systemd-modules-load.service
```

This is because RootlessKit's `builtin` port didn't support source IP propagation until v3.0. To enable source IP propagation, you can:

* Use the `slirp4netns` RootlessKit port driver
* Use the `pasta` RootlessKit network driver, with the `implicit` port driver

The `pasta` network driver is experimental, but provides improved throughput performance compared to the `slirp4netns` port driver. The `pasta` driver requires Docker Engine version 25.0 or later.

To change the RootlessKit networking configuration:

1. Create a file at `~/.config/systemd/user/docker.service.d/override.conf`.

2. Add the following contents, depending on which configuration you would like to use:

   * `slirp4netns`

     ```systemd
     [Service]
     Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_NET=slirp4netns"
     Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=slirp4netns"
     ```

   * `pasta` network driver with `implicit` port driver

     ```systemd
     [Service]
     Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_NET=pasta"
     Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=implicit"
     ```

3. Restart the daemon:

   ```console
   $ systemctl --user daemon-reload
   $ systemctl --user restart docker
   ```

For more information about networking options for RootlessKit, see:

* [Network drivers](https://github.com/rootless-containers/rootlesskit/blob/v3.0.0/docs/network.md)
* [Port drivers](https://github.com/rootless-containers/rootlesskit/blob/v3.0.0/docs/port.md)

### [Tips for debugging](#tips-for-debugging)

**Entering into `dockerd` namespaces**

The `dockerd-rootless.sh` script executes `dockerd` in its own user, mount, and network namespaces.

For debugging, you can enter the namespaces by running `nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)`.

## [Uninstall](#uninstall)

To remove the systemd service of the Docker daemon, run `dockerd-rootless-setuptool.sh uninstall`:

```console
$ dockerd-rootless-setuptool.sh uninstall
+ systemctl --user stop docker.service
+ systemctl --user disable docker.service
Removed /home/testuser/.config/systemd/user/default.target.wants/docker.service.
[INFO] Uninstalled docker.service
[INFO] This uninstallation tool does NOT remove Docker binaries and data.
[INFO] To remove data, run: `/usr/bin/rootlesskit rm -rf /home/testuser/.local/share/docker`
```

Unset environment variables PATH and DOCKER\_HOST if you have added them to `~/.bashrc`.

To remove the data directory, run `rootlesskit rm -rf ~/.local/share/docker`.

To remove the binaries, remove `docker-ce-rootless-extras` package if you installed Docker with package managers. If you installed Docker with <https://get.docker.com/rootless> ([Install without packages](https://docs.docker.com/engine/security/rootless/#install)), remove the binary files under `~/bin`:

```console
$ cd ~/bin
$ rm -f containerd containerd-shim containerd-shim-runc-v2 ctr docker docker-init docker-proxy dockerd dockerd-rootless-setuptool.sh dockerd-rootless.sh rootlesskit rootlesskit-docker-proxy runc vpnkit
```

----
url: https://docs.docker.com/extensions/extensions-sdk/guides/oauth2-flow/
----

# Authentication

***

Table of contents

***

> Note
>
> This page assumes that you already have an Identity Provider (IdP), such as Google, Entra ID (formerly Azure AD) or Okta, which handles the authentication process and returns an access token.

Learn how you can let users authenticate from your extension using OAuth 2.0 via a web browser, and return to your extension.

In OAuth 2.0, the term "grant type" refers to the way an application gets an access token. Although OAuth 2.0 defines several grant types, this page only describes how to authorize users from your extension using the Authorization Code grant type.

## [Authorization code grant flow](#authorization-code-grant-flow)

The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token.

After the user returns to the client via the redirect URL, the application gets the authorization code from the URL and uses it to request an access token.

The image above shows that:

* The Docker extension asks the user to authorize access to their data.
* If the user grants access, the extension then requests an access token from the service provider, passing the access grant from the user and authentication details to identify the client.
* The service provider then validates these details and returns an access token.
* The extension uses the access token to request the user data with the service provider.

### [OAuth 2.0 terminology](#oauth-20-terminology)

* Auth URL: The endpoint for the API provider authorization server, to retrieve the auth code.
* Redirect URI: The client application callback URL to redirect to after auth. This must be registered with the API provider.

Once the user enters the username and password, they're successfully authenticated.

## [Open a browser page to authenticate the user](#open-a-browser-page-to-authenticate-the-user)

From the extension UI, you can provide a button that, when selected, opens a new window in a browser to authenticate the user.

Use the [ddClient.host.openExternal](https://docs.docker.com/extensions/extensions-sdk/dev/api/dashboard/#open-a-url) API to open a browser to the auth URL. For example:

```typescript
window.ddClient.openExternal("https://authorization-server.com/authorize?
  response_type=code
  &client_id=T70hJ3ls5VTYG8ylX3CZsfIu
  &redirect_uri=${REDIRECT_URI});
```

## [Get the authorization code and access token](#get-the-authorization-code-and-access-token)

You can get the authorization code from the extension UI by listing `docker-desktop://dashboard/extension-tab?extensionId=awesome/my-extension` as the `redirect_uri` in the OAuth app you're using and concatenating the authorization code as a query parameter. The extension UI code will then be able to read the corresponding code query-param.

> Important
>
> Using this feature requires the extension SDK 0.3.3 in Docker Desktop. You need to ensure that the required SDK version for your extension set with `com.docker.desktop.extension.api.version` in [image labels](https://docs.docker.com/extensions/extensions-sdk/extensions/labels/) is higher than 0.3.3.

#### [Authorization](#authorization)

This step is where the user enters their credentials in the browser. After the authorization is complete, the user is redirected back to your extension user interface, and the extension UI code can consume the authorization code that's part of the query parameters in the URL.

#### [Exchange the Authorization Code](#exchange-the-authorization-code)

Next, you exchange the authorization code for an access token.

The extension must send a `POST` request to the 0Auth authorization server with the following parameters:

```text
POST https://authorization-server.com/token
&client_id=T70hJ3ls5VTYG8ylX3CZsfIu
&client_secret=YABbyHQShPeO1T3NDQZP8q5m3Jpb_UPNmIzqhLDCScSnRyVG
&redirect_uri=${REDIRECT_URI}
&code=N949tDLuf9ai_DaOKyuFBXStCNMQzuQbtC1QbvLv-AXqPJ_f
```

> Note
>
> The client's credentials are included in the `POST` query params in this example. OAuth authorization servers may require that the credentials are sent as a HTTP Basic Authentication header or might support different formats. See your OAuth provider docs for details.

### [Store the access token](#store-the-access-token)

The Docker Extensions SDK doesn't provide a specific mechanism to store secrets.

It's highly recommended that you use an external source of storage to store the access token.

> Note
>
> The user interface Local Storage is isolated between extensions (an extension can't access another extension's local storage), and each extension's local storage gets deleted when users uninstall an extension.

## [What's next](#whats-next)

Learn how to [publish and distribute your extension](https://docs.docker.com/extensions/extensions-sdk/extensions/)

----
url: https://docs.docker.com/guides/nodejs/containerize/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Containerize a Node.js application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Before you begin, make sure the following tools are installed and available on your system:

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

> Note
>
> New to Docker? Start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide to get familiar with key concepts like images, containers, and Dockerfiles.

***

## [Overview](#overview)

This guide walks you through the complete process of containerizing a Node.js application with Docker. You’ll learn how to create a production-ready Docker image using best practices that enhance performance, security, scalability, and operational efficiency.

By the end of this guide, you will:

* Containerize a Node.js application using Docker.
* Create and optimize a Dockerfile tailored for Node.js environments.
* Use multi-stage builds to separate dependencies and reduce image size.
* Configure the container for secure, efficient runtime using a non-root user.
* Follow best practices for building secure, lightweight, and maintainable Docker images.

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the Git repository:

```console
$ git clone https://github.com/kristiyan-velkov/docker-nodejs-sample
```

## [Build the Docker image](#build-the-docker-image)

This project is a full-stack TypeScript application with both a backend API and frontend React components, so the Dockerfile is optimized for that architecture.

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

### [Step 1: Create the Dockerfile](#step-1-create-the-dockerfile)

Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog).

Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/).

> Important
>
> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application.
>
> Official Node.js Docker Images: <https://hub.docker.com/_/node>

Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide.

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Pull the Node.js DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/node:24-alpine3.22-dev
   ```

Create a file named `Dockerfile` in your project root with the following contents. The `FROM` instruction uses `dhi.io/node:24-alpine3.22-dev` as the base image.

```dockerfile
# ========================================
# Optimized Multi-Stage Dockerfile
# Node.js TypeScript Application (Using DHI)
# ========================================

FROM dhi.io/node:24-alpine3.22-dev AS base

# Set working directory
WORKDIR /app

# Create non-root user for security
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001 -G nodejs && \
    chown -R nodejs:nodejs /app

# ========================================
# Dependencies Stage
# ========================================
FROM base AS deps

# Copy package files
COPY package*.json ./

# Install production dependencies
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
    npm ci --omit=dev && \
    npm cache clean --force

# Set proper ownership
RUN chown -R nodejs:nodejs /app

# ========================================
# Build Dependencies Stage
# ========================================
FROM base AS build-deps

# Copy package files
COPY package*.json ./

# Install all dependencies with build optimizations
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
    npm ci --no-audit --no-fund && \
    npm cache clean --force

# Create necessary directories and set permissions
RUN mkdir -p /app/node_modules/.vite && \
    chown -R nodejs:nodejs /app

# ========================================
# Build Stage
# ========================================
FROM build-deps AS build

# Copy only necessary files for building (respects .dockerignore)
COPY --chown=nodejs:nodejs . .

# Build the application
RUN npm run build

# Set proper ownership
RUN chown -R nodejs:nodejs /app

# ========================================
# Development Stage
# ========================================
FROM build-deps AS development

# Set environment
ENV NODE_ENV=development \
    NPM_CONFIG_LOGLEVEL=warn

# Copy source files
COPY . .

# Ensure all directories have proper permissions
RUN mkdir -p /app/node_modules/.vite && \
    chown -R nodejs:nodejs /app && \
    chmod -R 755 /app

# Switch to non-root user
USER nodejs

# Expose ports
EXPOSE 3000 5173 9229

# Start development server
CMD ["npm", "run", "dev:docker"]

# ========================================
# Production Stage
# ========================================
FROM dhi.io/node:24-alpine3.22-dev AS production

# Set working directory
WORKDIR /app

# Create non-root user for security
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001 -G nodejs && \
    chown -R nodejs:nodejs /app

# Set optimized environment variables
ENV NODE_ENV=production \
    NODE_OPTIONS="--max-old-space-size=256 --no-warnings" \
    NPM_CONFIG_LOGLEVEL=silent

# Copy production dependencies from deps stage
COPY --from=deps --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=deps --chown=nodejs:nodejs /app/package*.json ./
# Copy built application from build stage
COPY --from=build --chown=nodejs:nodejs /app/dist ./dist

# Switch to non-root user for security
USER nodejs

# Expose port
EXPOSE 3000

# Start production server
CMD ["node", "dist/server.js"]

# ========================================
# Test Stage
# ========================================
FROM build-deps AS test

# Set environment
ENV NODE_ENV=test \
    CI=true

# Copy source files
COPY --chown=nodejs:nodejs . .

# Switch to non-root user
USER nodejs

# Run tests with coverage
CMD ["npm", "run", "test:coverage"]
```

Create a file named `Dockerfile` in your project root with the following contents:

```dockerfile
# ========================================
# Optimized Multi-Stage Dockerfile
# Node.js TypeScript Application
# ========================================

ARG NODE_VERSION=24.11.1-alpine
FROM node:${NODE_VERSION} AS base

# Set working directory
WORKDIR /app

# Create non-root user for security
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001 -G nodejs && \
    chown -R nodejs:nodejs /app

# ========================================
# Dependencies Stage
# ========================================
FROM base AS deps

# Copy package files
COPY package*.json ./

# Install production dependencies
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
    npm ci --omit=dev && \
    npm cache clean --force

# Set proper ownership
RUN chown -R nodejs:nodejs /app

# ========================================
# Build Dependencies Stage
# ========================================
FROM base AS build-deps

# Copy package files
COPY package*.json ./

# Install all dependencies with build optimizations
RUN --mount=type=cache,target=/root/.npm,sharing=locked \
    npm ci --no-audit --no-fund && \
    npm cache clean --force

# Create necessary directories and set permissions
RUN mkdir -p /app/node_modules/.vite && \
    chown -R nodejs:nodejs /app

# ========================================
# Build Stage
# ========================================
FROM build-deps AS build

# Copy only necessary files for building (respects .dockerignore)
COPY --chown=nodejs:nodejs . .

# Build the application
RUN npm run build

# Set proper ownership
RUN chown -R nodejs:nodejs /app

# ========================================
# Development Stage
# ========================================
FROM build-deps AS development

# Set environment
ENV NODE_ENV=development \
    NPM_CONFIG_LOGLEVEL=warn

# Copy source files
COPY . .

# Ensure all directories have proper permissions
RUN mkdir -p /app/node_modules/.vite && \
    chown -R nodejs:nodejs /app && \
    chmod -R 755 /app

# Switch to non-root user
USER nodejs

# Expose ports
EXPOSE 3000 5173 9229

# Start development server
CMD ["npm", "run", "dev:docker"]

# ========================================
# Production Stage
# ========================================
ARG NODE_VERSION=24.11.1-alpine
FROM node:${NODE_VERSION} AS production

# Set working directory
WORKDIR /app

# Create non-root user for security
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001 -G nodejs && \
    chown -R nodejs:nodejs /app

# Set optimized environment variables
ENV NODE_ENV=production \
    NODE_OPTIONS="--max-old-space-size=256 --no-warnings" \
    NPM_CONFIG_LOGLEVEL=silent

# Copy production dependencies from deps stage
COPY --from=deps --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=deps --chown=nodejs:nodejs /app/package*.json ./
# Copy built application from build stage
COPY --from=build --chown=nodejs:nodejs /app/dist ./dist

# Switch to non-root user for security
USER nodejs

# Expose port
EXPOSE 3000

# Start production server
CMD ["node", "dist/server.js"]

# ========================================
# Test Stage
# ========================================
FROM build-deps AS test

# Set environment
ENV NODE_ENV=test \
    CI=true

# Copy source files
COPY --chown=nodejs:nodejs . .

# Switch to non-root user
USER nodejs

# Run tests with coverage
CMD ["npm", "run", "test:coverage"]
```

Key features of this Dockerfile:

* Multi-stage structure — Separate stages for dependencies, build, development, production, and testing to keep each phase clean and efficient.
* Lean production image — Optimized layering reduces size and keeps only what’s required to run the app.
* Security-minded setup — Uses a dedicated non-root user and excludes unnecessary packages.
* Performance-friendly design — Effective use of caching and well-structured layers for faster builds.
* Clean runtime environment — Removes files not needed in production, such as docs, tests, and build caches.
* Straightforward port usage — The app runs on port 3000 internally, exposed externally as port 8080.
* Memory-optimized runtime — Node.js is configured to run with a smaller memory limit than the default.

### [Step 2: Create the compose.yaml file](#step-2-create-the-composeyaml-file)

Create a file named `compose.yaml` in your project root:

```yaml
# ========================================
# Docker Compose Configuration
# Modern Node.js Todo Application
# ========================================

services:
  # ========================================
  # Development Service
  # ========================================
  app-dev:
    build:
      context: .
      dockerfile: Dockerfile
      target: development
    container_name: todoapp-dev
    ports:
      - "${APP_PORT:-3000}:3000" # API server
      - "${VITE_PORT:-5173}:5173" # Vite dev server
      - "${DEBUG_PORT:-9229}:9229" # Node.js debugger
    environment:
      NODE_ENV: development
      DOCKER_ENV: "true"
      POSTGRES_HOST: db
      POSTGRES_PORT: 5432
      POSTGRES_DB: todoapp
      POSTGRES_USER: todoapp
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:-todoapp_password}"
      ALLOWED_ORIGINS: "${ALLOWED_ORIGINS:-http://localhost:3000,http://localhost:5173}"
    volumes:
      - ./src:/app/src:ro
      - ./package.json:/app/package.json
      - ./vite.config.ts:/app/vite.config.ts:ro
      - ./tailwind.config.js:/app/tailwind.config.js:ro
      - ./postcss.config.js:/app/postcss.config.js:ro
    depends_on:
      db:
        condition: service_healthy
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - "**/*.test.*"
            - "**/__tests__/**"
        - action: rebuild
          path: ./package.json
        - action: sync
          path: ./vite.config.ts
          target: /app/vite.config.ts
        - action: sync
          path: ./tailwind.config.js
          target: /app/tailwind.config.js
        - action: sync
          path: ./postcss.config.js
          target: /app/postcss.config.js
    restart: unless-stopped
    networks:
      - todoapp-network

  # ========================================
  # Production Service
  # ========================================
  app-prod:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    container_name: todoapp-prod
    ports:
      - "${PROD_PORT:-8080}:3000"
    environment:
      NODE_ENV: production
      POSTGRES_HOST: db
      POSTGRES_PORT: 5432
      POSTGRES_DB: todoapp
      POSTGRES_USER: todoapp
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:-todoapp_password}"
      ALLOWED_ORIGINS: "${ALLOWED_ORIGINS:-https://yourdomain.com}"
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: "${PROD_MEMORY_LIMIT:-2G}"
          cpus: "${PROD_CPU_LIMIT:-1.0}"
        reservations:
          memory: "${PROD_MEMORY_RESERVATION:-512M}"
          cpus: "${PROD_CPU_RESERVATION:-0.25}"
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
    networks:
      - todoapp-network
    profiles:
      - prod

  # ========================================
  # PostgreSQL Database Service
  # ========================================
  db:
    image: postgres:18-alpine
    container_name: todoapp-db
    environment:
      POSTGRES_DB: "${POSTGRES_DB:-todoapp}"
      POSTGRES_USER: "${POSTGRES_USER:-todoapp}"
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:-todoapp_password}"
    volumes:
      - postgres_data:/var/lib/postgresql
    ports:
      - "${DB_PORT:-5432}:5432"
    restart: unless-stopped
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "pg_isready -U ${POSTGRES_USER:-todoapp} -d ${POSTGRES_DB:-todoapp}",
        ]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 5s
    networks:
      - todoapp-network

# ========================================
# Volume Configuration
# ========================================
volumes:
  postgres_data:
    name: todoapp-postgres-data
    driver: local

# ========================================
# Network Configuration
# ========================================
networks:
  todoapp-network:
    name: todoapp-network
    driver: bridge
```

This Docker Compose configuration includes:

* Development service (`app-dev`): Full development environment with hot reload, debugging support, and bind mounts
* Production service (`app-prod`): Optimized production deployment with resource limits and security hardening
* Database service (`db`): PostgreSQL 18 with persistent storage and health checks
* Networking: Isolated network for secure service communication
* Volumes: Persistent storage for database data

### [Step 3: Create environment configuration](#step-3-create-environment-configuration)

Create a `.env` file to configure your application settings:

```console
$ cp .env.example .env
```

Update the `.env` file with your preferred settings:

```env
# Application Configuration
NODE_ENV=development
APP_PORT=3000
VITE_PORT=5173
DEBUG_PORT=9229

# Production Configuration
PROD_PORT=8080
PROD_MEMORY_LIMIT=2G
PROD_CPU_LIMIT=1.0
PROD_MEMORY_RESERVATION=512M
PROD_CPU_RESERVATION=0.25

# Database Configuration
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_DB=todoapp
POSTGRES_USER=todoapp
POSTGRES_PASSWORD=todoapp_password
DB_PORT=5432

# Security Configuration
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
```

### [Step 4: Configure the .dockerignore file](#step-4-configure-the-dockerignore-file)

The `.dockerignore` file tells Docker which files and folders to exclude when building the image.

> Note
>
> This helps:
>
> * Reduce image size
> * Speed up the build process
> * Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image.
>
> To learn more, visit the [.dockerignore reference](https://docs.docker.com/reference/dockerfile/#dockerignore-file).

Create a file named `.dockerignore` with the following contents:

```dockerignore
# Optimized .dockerignore for Node.js + React Todo App
# Based on actual project structure

# Version control
.git/
.github/
.gitignore

# Dependencies (installed in container)
node_modules/

# Build outputs (built in container)
dist/

# Environment files
.env*

# Development files
.vscode/
*.log
coverage/
.eslintcache

# OS files
.DS_Store
Thumbs.db

# Documentation
*.md
docs/

# Deployment configs
compose.yaml
Taskfile.yml
nodejs-sample-kubernetes.yaml

# Non-essential configs (keep build configs)
*.config.js
!vite.config.ts
!esbuild.config.js
!tailwind.config.js
!postcss.config.js
!tsconfig.json
```

### [Step 5: Build the Node.js application image](#step-5-build-the-nodejs-application-image)

After creating all the configuration files, your project directory should now contain all necessary Docker configuration files:

```text
├── docker-nodejs-sample/
│ ├── Dockerfile
│ ├── .dockerignore
│ ├── compose.yaml
│ └── .env
```

Now you can build the Docker image for your Node.js application.

> Note
>
> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)).

Run the following command from the root of your project:

```console
$ docker build --target production --tag docker-nodejs-sample .
```

What this command does:

* Uses the Dockerfile in the current directory (.)
* Targets the production stage of the multi-stage build
* Packages the application and its dependencies into a Docker image
* Tags the image as docker-nodejs-sample so you can reference it later

### [Step 6: View local images](#step-6-view-local-images)

After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](https://docs.docker.com/desktop/use-desktop/images/). Since you're already working in the terminal, use the Docker CLI.

To list all locally available Docker images, run the following command:

```console
$ docker images
```

Example Output:

```shell
REPOSITORY               TAG              IMAGE ID       CREATED         SIZE
docker-nodejs-sample     latest           423525528038   14 seconds ago  237.46MB
```

This output provides key details about your images:

* Repository – The name assigned to the image.
* Tag – A version label that helps identify different builds (e.g., latest).
* Image ID – A unique identifier for the image.
* Created – The timestamp indicating when the image was built.
* Size – The total disk space used by the image.

If the build was successful, you should see `docker-nodejs-sample` image listed.

***

## [Run the containerized application](#run-the-containerized-application)

In the previous step, you created a Dockerfile for your Node.js application and built a Docker image using the `docker build` command. Now it’s time to run that image in a container and verify that your application works as expected.

Inside the `docker-nodejs-sample` directory, run the following command in a terminal.

```console
$ docker compose up app-dev --build
```

The development application will start with both servers:

* API Server: <http://localhost:3000> - Express.js backend with REST API
* Frontend: <http://localhost:5173> - Vite dev server with React frontend
* Health Check: <http://localhost:3000/health> - Application health status

For production deployment, you can use:

```console
$ docker compose up app-prod --build
```

Which serves the full-stack app at <http://localhost:8080> with the Express server running on port 3000 internally, mapped to port 8080 externally.

You should see a modern Todo List application with React 19 and a fully functional REST API.

Press `CTRL + C` in the terminal to stop your application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `docker-nodejs-sample` directory, run the following command in a terminal.

```console
$ docker compose up app-dev --build -d
```

Open a browser and view the application at <http://localhost:3000> (API) or <http://localhost:5173> (frontend). You should see the Todo application running.

To confirm that the container is running, use `docker ps` command:

```console
$ docker ps
```

This will list all active containers along with their ports, names, and status. Look for a container exposing ports 3000, 5173, and 9229 for the development app.

Example Output:

```shell
CONTAINER ID   IMAGE                          COMMAND                  CREATED          STATUS                 PORTS                                                                                                                                   NAMES
93f3faee32c3   docker-nodejs-sample-app-dev   "docker-entrypoint.s…"   33 seconds ago   Up 31 seconds          0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp, 0.0.0.0:5173->5173/tcp, [::]:5173->5173/tcp, 0.0.0.0:9230->9229/tcp, [::]:9230->9229/tcp   todoapp-dev
```

### [Run different profiles](#run-different-profiles)

You can run different configurations using Docker Compose profiles:

```console
# Run production
$ docker compose up app-prod -d

# Run tests
$ docker compose up app-test -d
```

To stop the application, run:

```console
$ docker compose down
```

> Note
>
> For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

***

## [Summary](#summary)

In this guide, you learned how to containerize, build, and run a Node.js application using Docker. By following best practices, you created a secure, optimized, and production-ready setup.

What you accomplished:

* Created a `Dockerfile` with a multi-stage build optimized for TypeScript and React.
* Created a `compose.yaml` file with development, production, and database services.
* Set up environment configuration with a `.env` file for flexible deployment settings.
* Created a `.dockerignore` file to exclude unnecessary files and keep the image clean and efficient.
* Built your Docker image using `docker build`.
* Ran the container using `docker compose up`, both in the foreground and in detached mode.
* Verified that the app was running by visiting <http://localhost:8080> (production) or <http://localhost:3000> (development).
* Learned how to stop the containerized application using `docker compose down`.

You now have a fully containerized Node.js application, running in a Docker container, and ready for deployment across any environment with confidence and consistency.

***

***

## [Next steps](#next-steps)

With your Node.js application now containerized, you're ready to move on to the next step.

In the next section, you'll learn how to develop your application using Docker containers, enabling a consistent, isolated, and reproducible development environment across any machine.

[Use containers for Node.js development »](https://docs.docker.com/guides/nodejs/develop/)

----
url: https://docs.docker.com/reference/cli/docker/version/
----

# docker version

***

| Description | Show the Docker version information |
| ----------- | ----------------------------------- |
| Usage       | `docker version [OPTIONS]`          |

## [Description](#description)

The version command prints the current version number for all independently versioned Docker components. Use the [`--format`](#format) option to customize the output.

The version command (`docker version`) outputs the version numbers of Docker components, while the `--version` flag (`docker --version`) outputs the version number of the Docker CLI you are using.

### [Default output](#default-output)

The default output renders all version information divided into two sections; the `Client` section contains information about the Docker CLI and client components, and the `Server` section contains information about the Docker Engine and components used by the Docker Engine, such as the containerd and runc OCI Runtimes.

The information shown may differ depending on how you installed Docker and what components are in use. The following example shows the output on a macOS machine running Docker Desktop:

```console
$ docker version

Client: Docker Engine - Community
 Version:           28.5.1
 API version:       1.51
 Go version:        go1.24.8
 Git commit:        e180ab8
 Built:             Wed Oct  8 12:16:17 2025
 OS/Arch:           darwin/arm64
 Context:           remote-test-server

Server: Docker Desktop 4.19.0 (12345)
 Engine:
  Version:          27.5.1
  API version:      1.47 (minimum version 1.24)
  Go version:       go1.22.11
  Git commit:       4c9b3b0
  Built:            Wed Jan 22 13:41:24 2025
  OS/Arch:          linux/amd64
  Experimental:     true
 containerd:
  Version:          v1.7.25
  GitCommit:        bcc810d6b9066471b0b6fa75f557a15a1cbf31bb
 runc:
  Version:          1.2.4
  GitCommit:        v1.2.4-0-g6c52b3f
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0
```

### [Client and server versions](#client-and-server-versions)

Docker uses a client/server architecture, which allows you to use the Docker CLI on your local machine to control a Docker Engine running on a remote machine, which can be (for example) a machine running in the cloud or inside a virtual machine.

The following example switches the Docker CLI to use a [context](/reference/cli/docker/context/) named `remote-test-server`, which runs an older version of the Docker Engine on a Linux server:

```console
$ docker context use remote-test-server
remote-test-server

$ docker version

Client: Docker Engine - Community
 Version:           28.5.1
 API version:       1.51
 Go version:        go1.24.8
 Git commit:        e180ab8
 Built:             Wed Oct  8 12:16:17 2025
 OS/Arch:           darwin/arm64
 Context:           remote-test-server

Server: Docker Engine - Community
 Engine:
  Version:          27.5.1
  API version:      1.47 (minimum version 1.24)
  Go version:       go1.22.11
  Git commit:       4c9b3b0
  Built:            Wed Jan 22 13:41:24 2025
  OS/Arch:          linux/amd64
  Experimental:     true
 containerd:
  Version:          v1.7.25
  GitCommit:        bcc810d6b9066471b0b6fa75f557a15a1cbf31bb
 runc:
  Version:          1.2.4
  GitCommit:        v1.2.4-0-g6c52b3f
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0
```

### [API version and version negotiation](#api-version-and-version-negotiation)

The API version used by the client depends on the Docker Engine that the Docker CLI is connecting with. When connecting with the Docker Engine, the Docker CLI and Docker Engine perform API version negotiation, and select the highest API version that is supported by both the Docker CLI and the Docker Engine.

For example, if the CLI is connecting with Docker Engine version 27.5, it downgrades to API version 1.47 (refer to the [API version matrix](/reference/api/engine/#api-version-matrix) to learn about the supported API versions for Docker Engine):

```console
$ docker version --format '{{.Client.APIVersion}}'

1.47
```

Be aware that API version can also be overridden using the `DOCKER_API_VERSION` environment variable, which can be useful for debugging purposes, and disables API version negotiation. The following example illustrates an environment where the `DOCKER_API_VERSION` environment variable is set. Unsetting the environment variable removes the override, and re-enables API version negotiation:

```console
$ env | grep DOCKER_API_VERSION
DOCKER_API_VERSION=1.50

$ docker version --format '{{.Client.APIVersion}}'
1.50

$ unset DOCKER_API_VERSION
$ docker version --format '{{.Client.APIVersion}}'
1.51
```

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                             |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --format`](#format) |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |

## [Examples](#examples)

### [Format the output (--format)](#format)

The formatting option (`--format`) pretty-prints the output using a Go template, which allows you to customize the output format, or to obtain specific information from the output. Refer to the [format command and log output](/config/formatting/) page for details of the format.

### [Get the server version](#get-the-server-version)

```console
$ docker version --format '{{.Server.Version}}'

28.5.1
```

### [Get the client API version](#get-the-client-api-version)

The following example prints the API version that is used by the client:

```console
$ docker version --format '{{.Client.APIVersion}}'

1.51
```

The version shown is the API version that is negotiated between the client and the Docker Engine. Refer to [API version and version negotiation](#api-version-and-version-negotiation) above for more information.

### [Dump raw JSON data](#dump-raw-json-data)

```console
$ docker version --format '{{json .}}'

{"Client":"Version":"28.5.1","ApiVersion":"1.51", ...}
```

----
url: https://docs.docker.com/extensions/extensions-sdk/build/frontend-extension-tutorial/
----

# Create an advanced frontend extension

***

Table of contents

***

To start creating your extension, you first need a directory with files which range from the extension’s source code to the required extension-specific files. This page provides information on how to set up an extension with a more advanced frontend.

Before you start, make sure you have installed the latest version of [Docker Desktop](https://docs.docker.com/desktop/release-notes/).

## [Extension folder structure](#extension-folder-structure)

The quickest way to create a new extension is to run `docker extension init my-extension` as in the [Quickstart](https://docs.docker.com/extensions/extensions-sdk/quickstart/). This creates a new directory `my-extension` that contains a fully functional extension.

> Tip
>
> The `docker extension init` generates a React based extension. But you can still use it as a starting point for your own extension and use any other frontend framework, like Vue, Angular, Svelte, etc. or even stay with vanilla Javascript.

Although you can start from an empty directory or from the `react-extension` [sample folder](https://github.com/docker/extensions-sdk/tree/main/samples), it's highly recommended that you start from the `docker extension init` command and change it to suit your needs.

```bash
.
├── Dockerfile # (1)
├── ui # (2)
│   ├── public # (3)
│   │   └── index.html
│   ├── src # (4)
│   │   ├── App.tsx
│   │   ├── index.tsx
│   ├── package.json
│   └── package-lock.lock
│   ├── tsconfig.json
├── docker.svg # (5)
└── metadata.json # (6)
```

1. Contains everything required to build the extension and run it in Docker Desktop.
2. High-level folder containing your front-end app source code.
3. Assets that aren’t compiled or dynamically generated are stored here. These can be static assets like logos or the robots.txt file.
4. The src, or source folder contains all the React components, external CSS files, and dynamic assets that are brought into the component files.
5. The icon that is displayed in the left-menu of the Docker Desktop Dashboard.
6. A file that provides information about the extension such as the name, description, and version.

## [Adapting the Dockerfile](#adapting-the-dockerfile)

> Note
>
> When using the `docker extension init`, it creates a `Dockerfile` that already contains what is needed for a React extension.

Once the extension is created, you need to configure the `Dockerfile` to build the extension and configure the labels that are used to populate the extension's card in the Marketplace. Here is an example of a `Dockerfile` for a React extension:

```Dockerfile
# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM node:18.9-alpine3.15 AS client-builder
WORKDIR /ui
# cache packages in layer
COPY ui/package.json /ui/package.json
COPY ui/package-lock.json /ui/package-lock.json
RUN --mount=type=cache,target=/usr/src/app/.npm \
    npm set cache /usr/src/app/.npm && \
    npm ci
# install
COPY ui /ui
RUN npm run build

FROM alpine
LABEL org.opencontainers.image.title="My extension" \
    org.opencontainers.image.description="Your Desktop Extension Description" \
    org.opencontainers.image.vendor="Awesome Inc." \
    com.docker.desktop.extension.api.version="0.3.3" \
    com.docker.desktop.extension.icon="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png" \
    com.docker.extension.screenshots="" \
    com.docker.extension.detailed-description="" \
    com.docker.extension.publisher-url="" \
    com.docker.extension.additional-urls="" \
    com.docker.extension.changelog=""

COPY metadata.json .
COPY docker.svg .
COPY --from=client-builder /ui/build ui
```

> Note
>
> In the example Dockerfile, you can see that the image label `com.docker.desktop.extension.icon` is set to an icon URL. The Extensions Marketplace displays this icon without installing the extension. The Dockerfile also includes `COPY docker.svg .` to copy an icon file inside the image. This second icon file is used to display the extension UI in the Dashboard, once the extension is installed.

> Important
>
> We don't have a working Dockerfile for Vue yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Vue) and let us know if you'd like a Dockerfile for Vue.

> Important
>
> We don't have a working Dockerfile for Angular yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Angular) and let us know if you'd like a Dockerfile for Angular.

> Important
>
> We don't have a working Dockerfile for Svelte yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Svelte) and let us know if you'd like a Dockerfile for Svelte.

## [Configure the metadata file](#configure-the-metadata-file)

In order to add a tab in Docker Desktop for your extension, you have to configure it in the `metadata.json` file the root of your extension directory.

```json
{
  "icon": "docker.svg",
  "ui": {
    "dashboard-tab": {
      "title": "UI Extension",
      "root": "/ui",
      "src": "index.html"
    }
  }
}
```

The `title` property is the name of the extension that is displayed in the left-menu of the Docker Desktop Dashboard. The `root` property is the path to the frontend application in the extension's container filesystem used by the system to deploy it on the host. The `src` property is the path to the HTML entry point of the frontend application within the `root` folder.

For more information on the `ui` section of the `metadata.json`, see [Metadata](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#ui-section).

## [Build the extension and install it](#build-the-extension-and-install-it)

Now that you have configured the extension, you need to build the extension image that Docker Desktop will use to install it.

```bash
docker build --tag=awesome-inc/my-extension:latest .
```

This built an image tagged `awesome-inc/my-extension:latest`, you can run `docker inspect awesome-inc/my-extension:latest` to see more details about it.

Finally, you can install the extension and see it appearing in the Docker Desktop Dashboard.

```bash
docker extension install awesome-inc/my-extension:latest
```

## [Use the Extension APIs client](#use-the-extension-apis-client)

To use the Extension APIs and perform actions with Docker Desktop, the extension must first import the `@docker/extension-api-client` library. To install it, run the command below:

```bash
npm install @docker/extension-api-client
```

Then call the `createDockerDesktopClient` function to create a client object to call the extension APIs.

```js
import { createDockerDesktopClient } from '@docker/extension-api-client';

const ddClient = createDockerDesktopClient();
```

When using Typescript, you can also install `@docker/extension-api-client-types` as a dev dependency. This will provide you with type definitions for the extension APIs and auto-completion in your IDE.

```bash
npm install @docker/extension-api-client-types --save-dev
```

For example, you can use the `docker.cli.exec` function to get the list of all the containers via the `docker ps --all` command and display the result in a table.

Replace the `ui/src/App.tsx` file with the following code:

```tsx

// ui/src/App.tsx
import React, { useEffect } from 'react';
import {
  Paper,
  Stack,
  Table,
  TableBody,
  TableCell,
  TableContainer,
  TableHead,
  TableRow,
  Typography
} from "@mui/material";
import { createDockerDesktopClient } from "@docker/extension-api-client";

//obtain docker desktop extension client
const ddClient = createDockerDesktopClient();

export function App() {
  const [containers, setContainers] = React.useState<any[]>([]);

  useEffect(() => {
    // List all containers
    ddClient.docker.cli.exec('ps', ['--all', '--format', '"{{json .}}"']).then((result) => {
      // result.parseJsonLines() parses the output of the command into an array of objects
      setContainers(result.parseJsonLines());
    });
  }, []);

  return (
    <Stack>
      <Typography data-testid="heading" variant="h3" role="title">
        Container list
      </Typography>
      <Typography
      data-testid="subheading"
      variant="body1"
      color="text.secondary"
      sx={{ mt: 2 }}
    >
      Simple list of containers using Docker Extensions SDK.
      </Typography>
      <TableContainer sx={{mt:2}}>
        <Table>
          <TableHead>
            <TableRow>
              <TableCell>Container id</TableCell>
              <TableCell>Image</TableCell>
              <TableCell>Command</TableCell>
              <TableCell>Created</TableCell>
              <TableCell>Status</TableCell>
            </TableRow>
          </TableHead>
          <TableBody>
            {containers.map((container) => (
              <TableRow
                key={container.ID}
                sx={{ '&:last-child td, &:last-child th': { border: 0 } }}
              >
                <TableCell>{container.ID}</TableCell>
                <TableCell>{container.Image}</TableCell>
                <TableCell>{container.Command}</TableCell>
                <TableCell>{container.CreatedAt}</TableCell>
                <TableCell>{container.Status}</TableCell>
              </TableRow>
            ))}
          </TableBody>
        </Table>
      </TableContainer>
    </Stack>
  );
}
```

> Important
>
> We don't have an example for Vue yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Vue) and let us know if you'd like a sample with Vue.

> Important
>
> We don't have an example for Angular yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Angular) and let us know if you'd like a sample with Angular.

> Important
>
> We don't have an example for Svelte yet. [Fill out the form](https://docs.google.com/forms/d/e/1FAIpQLSdxJDGFJl5oJ06rG7uqtw1rsSBZpUhv_s9HHtw80cytkh2X-Q/viewform?usp=pp_url\&entry.1333218187=Svelte) and let us know if you'd like a sample with Svelte.

## [Policies enforced for the front-end code](#policies-enforced-for-the-front-end-code)

Extension UI code is rendered in a separate electron session and doesn't have a node.js environment initialized, nor direct access to the electron APIs.

This is to limit the possible unexpected side effects to the overall Docker Dashboard.

The extension UI code can't perform privileged tasks, such as making changes to the system, or spawning sub-processes, except by using the SDK APIs provided with the extension framework. The Extension UI code can also perform interactions with Docker Desktop, such as navigating to various places in the Dashboard, only through the extension SDK APIs.

Extensions UI parts are isolated from each other and extension UI code is running in its own session for each extension. Extensions can't access other extensions’ session data.

`localStorage` is one of the mechanisms of a browser’s web storage. It allows users to save data as key-value pairs in the browser for later use. `localStorage` doesn't clear data when the browser (the extension pane) closes. This makes it ideal for persisting data when navigating out of the extension to other parts of Docker Desktop.

If your extension uses `localStorage` to store data, other extensions running in Docker Desktop can't access the local storage of your extension. The extension’s local storage is persisted even after Docker Desktop is stopped or restarted. When an extension is upgraded, its local storage is persisted, whereas when it is uninstalled, its local storage is completely removed.

## [Re-build the extension and update it](#re-build-the-extension-and-update-it)

Since you have modified the code of the extension, you must build again the extension.

```console
$ docker build --tag=awesome-inc/my-extension:latest .
```

Once built, you need to update it.

```console
$ docker extension update awesome-inc/my-extension:latest
```

Now you can see the backend service running in the containers tab of the Docker Desktop Dashboard and watch the logs when you need to debug it.

> Tip
>
> You can turn on [hot reloading](https://docs.docker.com/extensions/extensions-sdk/dev/test-debug/#hot-reloading-whilst-developing-the-ui) to avoid the need to rebuild the extension every time you make a change.

## [What's next?](#whats-next)

* Add a [backend](https://docs.docker.com/extensions/extensions-sdk/build/backend-extension-tutorial/) to your extension.
* Learn how to [test and debug](https://docs.docker.com/extensions/extensions-sdk/dev/test-debug/) your extension.
* Learn how to [setup CI for your extension](https://docs.docker.com/extensions/extensions-sdk/dev/continuous-integration/).
* Learn more about extensions [architecture](https://docs.docker.com/extensions/extensions-sdk/architecture/).
* For more information and guidelines on building the UI, see the [Design and UI styling section](https://docs.docker.com/extensions/extensions-sdk/design/design-guidelines/).
* If you want to set up user authentication for the extension, see [Authentication](https://docs.docker.com/extensions/extensions-sdk/guides/oauth2-flow/).

----
url: https://docs.docker.com/dhi/core-concepts/ssdlc/
----

# Secure Software Development Lifecycle

***

Table of contents

***

## [What is a Secure Software Development Lifecycle?](#what-is-a-secure-software-development-lifecycle)

A Secure Software Development Lifecycle (SSDLC) integrates security practices into every phase of software delivery, from design and development to deployment and monitoring. It’s not just about writing secure code, but about embedding security throughout the tools, environments, and workflows used to build and ship software.

SSDLC practices are often guided by compliance frameworks, organizational policies, and supply chain security standards such as SLSA (Supply-chain Levels for Software Artifacts) or NIST SSDF.

## [Why SSDLC matters](#why-ssdlc-matters)

Modern applications depend on fast, iterative development, but rapid delivery often introduces security risks if protections aren’t built in early. An SSDLC helps:

* Prevent vulnerabilities before they reach production
* Ensure compliance through traceable and auditable workflows
* Reduce operational risk by maintaining consistent security standards
* Enable secure automation in CI/CD pipelines and cloud-native environments

By making security a first-class citizen in each stage of software delivery, organizations can shift left and reduce both cost and complexity.

## [How Docker supports a secure SDLC](#how-docker-supports-a-secure-sdlc)

Docker provides tools and secure content that make SSDLC practices easier to adopt across the container lifecycle. With [Docker Hardened Images](https://docs.docker.com/dhi/) (DHIs), [Docker Debug](/reference/cli/docker/debug/), and [Docker Scout](https://docs.docker.com/scout/), teams can add security without losing velocity.

### [Plan and design](#plan-and-design)

During planning, teams define architectural constraints, compliance goals, and threat models. Docker Hardened Images help at this stage by providing:

* Secure-by-default base images for common languages and runtimes
* Verified metadata including SBOMs, provenance, and VEX documents
* Support for both glibc and musl across multiple Linux distributions

You can use DHI metadata and attestations to support design reviews, threat modeling, or architecture sign-offs.

### [Develop](#develop)

In development, security should be transparent and easy to apply. Docker Hardened Images support secure-by-default development:

* Dev variants include shells, package managers, and compilers for convenience
* Minimal runtime variants reduce attack surface in final images
* Multi-stage builds let you separate build-time tools from runtime environments

[Docker Debug](/reference/cli/docker/debug/) helps developers:

* Temporarily inject debugging tools into minimal containers
* Avoid modifying base images during troubleshooting
* Investigate issues securely, even in production-like environments

### [Build and test](#build-and-test)

Build pipelines are an ideal place to catch issues early. Docker Scout integrates with Docker Hub and the CLI to:

* Scan for known CVEs using multiple vulnerability databases
* Trace vulnerabilities to specific layers and dependencies
* Interpret signed VEX data to suppress known-irrelevant issues
* Export JSON scan reports for CI/CD workflows

Build pipelines that use Docker Hardened Images benefit from:

* Reproducible, signed images
* Minimal build surfaces to reduce exposure
* Built-in compliance with SLSA Build Level 3 standards

### [Release and deploy](#release-and-deploy)

Security automation is critical as you release software at scale. Docker supports this phase by enabling:

* Signature verification and provenance validation before deployment
* Policy enforcement gates using Docker Scout
* Safe, non-invasive container inspection using Docker Debug

DHIs ship with the metadata and signatures required to automate image verification during deployment.

### [Monitor and improve](#monitor-and-improve)

Security continues after release. With Docker tools, you can:

* Continuously monitor image vulnerabilities through Docker Hub
* Get CVE remediation guidance and patch visibility using Docker Scout
* Receive updated DHI images with rebuilt and re-signed secure layers
* Debug running workloads with Docker Debug without modifying the image

## [Summary](#summary)

Docker helps teams embed security throughout the SSDLC by combining secure content (DHIs) with developer-friendly tooling (Docker Scout and Docker Debug). These integrations promote secure practices without introducing friction, making it easier to adopt compliance and supply chain security across your software delivery lifecycle.

----
url: https://docs.docker.com/guides/testcontainers-java-spring-boot-rest-api/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Testing a Spring Boot REST API with Testcontainers

Table of contents

***

Learn how to create a Spring Boot REST API with Spring Data JPA and PostgreSQL, then test it using Testcontainers and REST Assured.

**Time to complete** 25 minutes

In this guide, you will learn how to:

* Create a Spring Boot application with a REST API endpoint
* Use Spring Data JPA with PostgreSQL to store and retrieve data
* Test the REST API using Testcontainers and REST Assured

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-spring-boot-rest-api/create-project/)

   Set up a Spring Boot project with Spring Data JPA, PostgreSQL, and a REST API.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-spring-boot-rest-api/write-tests/)

   Test the Spring Boot REST API using Testcontainers and REST Assured.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-spring-boot-rest-api/run-tests/)

   Run your Testcontainers-based Spring Boot integration tests and explore next steps.

----
url: https://docs.docker.com/build/ci/github-actions/github-builder/build/
----

# Build with Docker GitHub Builder

***

Table of contents

***

The [`build.yml` reusable workflow](https://github.com/docker/github-builder?tab=readme-ov-file#build-reusable-workflow) builds from a Dockerfile and packages the same core tasks that many repositories wire together by hand. This page shows how to call the workflow, publish [multi-platform images](https://docs.docker.com/build/building/multi-platform/), and export local build artifacts without rebuilding the job structure in every repository.

## [Build and push an image](#build-and-push-an-image)

The following workflow builds from the repository Dockerfile, pushes on branch and tag events, and uses metadata inputs to generate tags:

```yaml
name: ci

on:
  push:
    branches:
      - "main"
    tags:
      - "v*"
  pull_request:

permissions:
  contents: read

jobs:
  build:
    uses: docker/github-builder/.github/workflows/build.yml@v1
    permissions:
      contents: read # to fetch the repository content
      id-token: write # for signing attestation(s) with GitHub OIDC Token
    with:
      output: image
      push: ${{ github.event_name != 'pull_request' }}
      platforms: linux/amd64,linux/arm64
      meta-images: name/app
      meta-tags: |
        type=ref,event=branch
        type=ref,event=pr
        type=semver,pattern={{version}}
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
```

When you set `output: image`, `meta-images` is required because the workflow creates image names and [manifest tags](https://docs.docker.com/build/ci/github-actions/manage-tags-labels/) from that input. `distribute: true` is the default, so a multi-platform build can fan out across native GitHub-hosted runners instead of forcing the whole build onto one machine. The default `runner` mapping sends Linux Arm platforms to `ubuntu-24.04-arm` and uses `ubuntu-24.04` for other platforms. To change that mapping, see [runner selection](https://docs.docker.com/build/ci/github-actions/github-builder/architecture/#runner-selection). `sign: auto` is also the default, which means the workflow signs [attestation manifests](https://docs.docker.com/build/ci/github-actions/attestations/) when the image is pushed.

## [Export local output as an artifact](#export-local-output-as-an-artifact)

The same workflow can export files instead of publishing an image. This is useful when you want compiled assets, an unpacked root filesystem, or another local exporter result as part of CI:

```yaml
name: ci

on:
  pull_request:

permissions:
  contents: read

jobs:
  build:
    uses: docker/github-builder/.github/workflows/build.yml@v1
    permissions:
      contents: read # to fetch the repository content
      id-token: write # for signing attestation(s) with GitHub OIDC Token
    with:
      output: local
      artifact-upload: true
      artifact-name: build-output
      platforms: linux/amd64,linux/arm64
```

With `output: local`, the workflow exports files to the runner filesystem and merges per-platform artifacts in the finalize phase. When `artifact-upload: true` is set, the merged result is uploaded as a GitHub artifact, and `sign: auto` signs the uploaded artifacts. `push` is ignored for local output, so there is no registry requirement in this form.

## [Add cache, Dockerfile inputs, and metadata labels](#add-cache-dockerfile-inputs-and-metadata-labels)

You can tune the Dockerfile build in the same job call. This example sets a custom Dockerfile path, a target stage, GitHub Actions cache, and metadata labels:

```yaml
name: ci

on:
  push:
    branches:
      - "main"

permissions:
  contents: read

jobs:
  build:
    uses: docker/github-builder/.github/workflows/build.yml@v1
    permissions:
      contents: read # to fetch the repository content
      id-token: write # for signing attestation(s) with GitHub OIDC Token
    with:
      output: image
      push: true
      context: .
      file: ./docker/Dockerfile
      target: runtime
      build-args: |
        NODE_ENV=production
        VERSION=${{ github.sha }}
      cache: true
      cache-scope: myapp
      meta-images: name/app
      meta-tags: |
        type=sha
      set-meta-labels: true
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
```

This is a Dockerfile build, so the inputs map closely to `docker/build-push-action`. The difference is that the reusable workflow owns Buildx setup, [BuildKit](https://docs.docker.com/build/buildkit/) configuration, [SLSA provenance](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) mode, [GitHub Actions cache backend](https://docs.docker.com/build/cache/backends/gha/) wiring, signing, and manifest creation. If you need more background on metadata or platform distribution, see [Manage tags and labels](https://docs.docker.com/build/ci/github-actions/manage-tags-labels/) and [Multi-platform image](https://docs.docker.com/build/ci/github-actions/multi-platform/).

----
url: https://docs.docker.com/reference/cli/docker/buildx/rm/
----

# docker buildx rm

***

| Description | Remove one or more builder instances   |
| ----------- | -------------------------------------- |
| Usage       | `docker buildx rm [OPTIONS] [NAME...]` |

## [Description](#description)

Removes the specified or current builder. It is a no-op attempting to remove the default builder.

## [Options](#options)

| Option                            | Default | Description                                             |
| --------------------------------- | ------- | ------------------------------------------------------- |
| [`--all-inactive`](#all-inactive) |         | Remove all inactive builders                            |
| [`-f, --force`](#force)           |         | Do not prompt for confirmation                          |
| [`--keep-daemon`](#keep-daemon)   |         | Keep the BuildKit daemon running                        |
| [`--keep-state`](#keep-state)     |         | Keep BuildKit state                                     |
| `--timeout`                       | `20s`   | Override the default timeout for loading builder status |

## [Examples](#examples)

### [Remove all inactive builders (--all-inactive)](#all-inactive)

Remove builders that are not in running state.

```console
$ docker buildx rm --all-inactive
WARNING! This will remove all builders that are not in running state. Are you sure you want to continue? [y/N] y
```

### [Override the configured builder instance (--builder)](#builder)

Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

### [Do not prompt for confirmation (--force)](#force)

Do not prompt for confirmation before removing inactive builders.

```console
$ docker buildx rm --all-inactive --force
```

### [Keep the BuildKit daemon running (--keep-daemon)](#keep-daemon)

Keep the BuildKit daemon running after the buildx context is removed. This is useful when you manage BuildKit daemons and buildx contexts independently. Only supported by the [`docker-container`](/build/drivers/docker-container/) and [`kubernetes`](/build/drivers/kubernetes/) drivers.

### [Keep BuildKit state (--keep-state)](#keep-state)

Keep BuildKit state, so it can be reused by a new builder with the same name. Currently, only supported by the [`docker-container` driver](/build/drivers/docker-container/).

----
url: https://docs.docker.com/reference/build-checks/from-platform-flag-const-disallowed/
----

# FromPlatformFlagConstDisallowed

***

Table of contents

***

## [Output](#output)

```text
FROM --platform flag should not use constant value "linux/amd64"
```

## [Description](#description)

Specifying `--platform` in the Dockerfile `FROM` instruction forces the image to build on only one target platform. This prevents building a multi-platform image from this Dockerfile and you must build on the same platform as specified in `--platform`.

The recommended approach is to:

* Omit `FROM --platform` in the Dockerfile and use the `--platform` argument on the command line.
* Use `$BUILDPLATFORM` or some other combination of variables for the `--platform` argument.
* Stage name should include the platform, OS, or architecture name to indicate that it only contains platform-specific instructions.

## [Examples](#examples)

❌ Bad: using a constant argument for `--platform`

```dockerfile
FROM --platform=linux/amd64 alpine AS base
RUN apk add --no-cache git
```

✅ Good: using the default platform

```dockerfile
FROM alpine AS base
RUN apk add --no-cache git
```

✅ Good: using a meta variable

```dockerfile
FROM --platform=${BUILDPLATFORM} alpine AS base
RUN apk add --no-cache git
```

✅ Good: used in a multi-stage build with a target architecture

```dockerfile
FROM --platform=linux/amd64 alpine AS build_amd64
...

FROM --platform=linux/arm64 alpine AS build_arm64
...

FROM build_${TARGETARCH} AS build
...
```

----
url: https://docs.docker.com/reference/build-checks/redundant-target-platform/
----

# RedundantTargetPlatform

***

Table of contents

***

## [Output](#output)

```text
Setting platform to predefined $TARGETPLATFORM in FROM is redundant as this is the default behavior
```

## [Description](#description)

A custom platform can be used for a base image. The default platform is the same platform as the target output so setting the platform to `$TARGETPLATFORM` is redundant and unnecessary.

## [Examples](#examples)

❌ Bad: this usage of `--platform` is redundant since `$TARGETPLATFORM` is the default.

```dockerfile
FROM --platform=$TARGETPLATFORM alpine AS builder
RUN apk add --no-cache git
```

✅ Good: omit the `--platform` argument.

```dockerfile
FROM alpine AS builder
RUN apk add --no-cache git
```

----
url: https://docs.docker.com/build/buildkit/dockerfile-release-notes/
----

[Skip to content](#start-of-content)

You signed in with another tab or window. [Reload]() to refresh your session. You signed out in another tab or window. [Reload]() to refresh your session. You switched accounts on another tab or window. [Reload]() to refresh your session. Dismiss alert

[moby ](/moby)/ **[buildkit](/moby/buildkit)&#x20;**&#x50;ublic

* [Notifications ](/login?return_to=%2Fmoby%2Fbuildkit)You must be signed in to change notification settings
* [Fork 1.4k](/login?return_to=%2Fmoby%2Fbuildkit)
* [Star 10k](/login?return_to=%2Fmoby%2Fbuildkit)

# Releases: moby/buildkit

Releases · moby/buildkit

## v0.30.0

13 May 13:16

[github-actions](/apps/github-actions)

[v0.30.0](/moby/buildkit/tree/v0.30.0)

This tag was signed with the committer’s **verified signature**.

[](/crazy-max)[crazy-max](/crazy-max) CrazyMax

GPG key ID: ADE44D8C9D44FBE4

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`dd2170e`](/moby/buildkit/commit/dd2170e156c9633da1b2d1a58a6188e3f7d36fa4)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.30.0](/moby/buildkit/releases/tag/v0.30.0) [Latest](/moby/buildkit/releases/latest)

[Latest](/moby/buildkit/releases/latest)

Welcome to the v0.30.0 release of buildkit!

Please try out the release binaries and report any issues at\
<https://github.com/moby/buildkit/issues>.

### Contributors

* Tõnis Tiigi
* CrazyMax
* Sebastiaan van Stijn
* Jonathan A. Sternberg
* Natnael Gebremariam
* Akihiro Suda
* Dawei Wei
* Dmitrii Kostyrev
* Jiří Moravčík
* Vladimir Kuznichenkov

### Notable Changes

* Builtin Dockerfile frontend has been updated to v1.24.0 [changelog](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.24.0)
* BuildKit now supports the concept of "compatibility version" for improved reproducible builds support across different BuildKit versions. This allows users to specify a version for which the build should be compatible with, and BuildKit will attempt to maintain compatibility with that version when possible. Compatibility version will be stored in the provenance attestation of the build and can be used to independently verify the artifacts of the build on other BuildKit versions. The current compatibility version and backward compatibility with old versions are defined in [Build reproducibility docs](https://github.com/moby/buildkit/blob/v0.30.0-rc1/docs/build-repro.md#compatibility-version) [#6681](https://github.com/moby/buildkit/pull/6681)
* Git sources now support `fetch-by-commit` option where commit is fetched by the SHA and then associated with the reference. This is useful when checking out mutable references `refs/NR/merge` where the commit SHA may change during invocation and cause checksum mismatch error [#6708](https://github.com/moby/buildkit/pull/6708)
* The LLB API now supports Git bundle format. Git bundles can be loaded from registry or OCI layout blobs and Git sources can be checked out into bundle format for snapshotting [#6711](https://github.com/moby/buildkit/pull/6711)
* Provenance attestations for multi-pass or chained builds now include request details for root requests and individual input requests, allowing full reconstruction of such complex builds [#6739](https://github.com/moby/buildkit/pull/6739)
* The version of the built-in Dockerfile frontend that was used is now included in the provenance metadata and reported via worker info APIs. [#6705](https://github.com/moby/buildkit/pull/6705)
* Improve error reporting for registry errors on cache export [#6762](https://github.com/moby/buildkit/pull/6762)
* S3 cache now supports additional options `retry_mode` and `retry_max_attempts` to configure retry behavior of S3 client [#6657](https://github.com/moby/buildkit/pull/6657)
* S3 cache now supports `disable_accept_encoding` option for GCS interoperability [#6642](https://github.com/moby/buildkit/pull/6642)
* Reduce potential lock contention in gateway forwarder for improved performance on parallel builds [#6741](https://github.com/moby/buildkit/pull/6741)
* A new log level option has been added to the buildkitd TOML configuration; previous "debug" and "trace" options have been deprecated [#6732](https://github.com/moby/buildkit/pull/6732)
* Allow gateway frontend requests to forward to the built-in Dockerfile frontend the same way as to external frontends [#6643](https://github.com/moby/buildkit/pull/6643)
* Session connection health checks have been improved to better detect loss of connectivity and avoid stuck builds [#6649](https://github.com/moby/buildkit/pull/6649)
* Fix issue with Git subdirectory value not being included in ConfigSource section of SLSA provenance for builds from Git sources [#6724](https://github.com/moby/buildkit/pull/6724)
* Avoid potential deadlock if the credential helper in the client is misbehaving and never returns credentials [#6709](https://github.com/moby/buildkit/pull/6709)
* Fix possible data race in provenance computation on parallel builds [#6758](https://github.com/moby/buildkit/pull/6758)
* Fix possible provenance capture race in concurrent no-cache builds that could leave source pins empty and fail with an invalid checksum digest error [#6764](https://github.com/moby/buildkit/pull/6764)
* Fix possible data race in progress writer [#6679](https://github.com/moby/buildkit/pull/6679)
* Fix data race in S3 cache reader [#6675](https://github.com/moby/buildkit/pull/6675)
* Fix possible Git config lookup errors on Windows [#6639](https://github.com/moby/buildkit/pull/6639)
* Fix build cancellation not working properly when blocked on credential callback [#6641](https://github.com/moby/buildkit/pull/6641)

### Dependency Changes

* **github.com/Azure/azure-sdk-for-go/sdk/azcore** v1.20.0 -> v1.21.0
* **github.com/Microsoft/hcsshim** v0.14.0-rc.1 -> v0.14.1
* **github.com/aws/aws-sdk-go-v2** v1.41.4 -> v1.41.7
* **github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream** v1.7.5 -> v1.7.8
* **github.com/aws/aws-sdk-go-v2/config** v1.32.12 -> v1.32.17
* **github.com/aws/aws-sdk-go-v2/credentials** v1.19.12 -> v1.19.16
* **github.com/aws/aws-sdk-go-v2/feature/ec2/imds** v1.18.20 -> v1.18.23
* **github.com/aws/aws-sdk-go-v2/internal/configsources** v1.4.20 -> v1.4.23
* **github.com/aws/aws-sdk-go-v2/internal/endpoints/v2** v2.7.20 -> v2.7.23
* **github.com/aws/aws-sdk-go-v2/internal/v4a** v1.4.12 -> v1.4.24
* **github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding** v1.13.7 -> v1.13.9
* **github.com/aws/aws-sdk-go-v2/service/internal/checksum** v1.9.3 -> v1.9.12
* **github.com/aws/aws-sdk-go-v2/service/internal/presigned-url** v1.13.20 -> v1.13.23
* **github.com/aws/aws-sdk-go-v2/service/internal/s3shared** v1.19.12 -> v1.19.20
* **github.com/aws/aws-sdk-go-v2/service/signin** v1.0.8 -> v1.0.11
* **github.com/aws/aws-sdk-go-v2/service/sso** v1.30.13 -> v1.30.17
* **github.com/aws/aws-sdk-go-v2/service/ssooidc** v1.35.17 -> v1.35.21
* **github.com/aws/aws-sdk-go-v2/service/sts** v1.41.9 -> v1.42.1
* **github.com/aws/smithy-go** v1.24.2 -> v1.25.1
* **github.com/containerd/containerd/v2** v2.2.2 -> v2.2.3
* **github.com/docker/cli** v29.3.1 -> v29.4.3
* **github.com/moby/policy-helpers** b7c0b994300b -> a39d60132186
* **github.com/moby/profiles/seccomp** v0.1.0 -> v0.2.3
* **go.opentelemetry.io/otel/metric** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/sdk** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/sdk/metric** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/trace** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/proto/otlp** v1.9.0 -> v1.10.0
* **golang.org/x/crypto** v0.48.0 -> v0.50.0
* **golang.org/x/mod** v0.33.0 -> v0.34.0
* **golang.org/x/net** v0.51.0 -> v0.53.0
* **golang.org/x/sync** v0.19.0 -> v0.20.0
* **golang.org/x/sys** v0.42.0 -> v0.43.0
* **golang.org/x/term** v0.41.0 -> v0.42.0
* **golang.org/x/text** v0.34.0 -> v0.36.0
* **golang.org/x/time** v0.14.0 -> v0.15.0
* **google.golang.org/genproto/googleapis/api** 8636f8732409 -> 6f92a3bedf2d
* **google.golang.org/genproto/googleapis/rpc** 8636f8732409 -> 6f92a3bedf2d
* **google.golang.org/grpc** v1.79.3 -> v1.80.0
* **kernel.org/pub/linux/libs/security/libcap/cap** v1.2.77 -> v1.2.78
* **kernel.org/pub/linux/libs/security/libcap/psx** v1.2.77 -> v1.2.78

Previous release can be found at [v0.29.0](https://github.com/moby/buildkit/releases/tag/v0.29.0)

Assets 42

* [buildkit-v0.30.0.darwin-amd64.provenance.json](/moby/buildkit/releases/download/v0.30.0/buildkit-v0.30.0.darwin-amd64.provenance.json)

  sha256:72583defb59f94ddb4a96d3e0c7af12a74335a36a4e5a076f1afee4f5aea8a05

  76.5 KB 2026-05-13T12:54:05Z

* [buildkit-v0.30.0.darwin-amd64.sbom.json](/moby/buildkit/releases/download/v0.30.0/buildkit-v0.30.0.darwin-amd64.sbom.json)

  sha256:5b7864acd58224cb3a2b436fd354b01ab8578d80d2713b321fb2caa69cae6bb2

  153 KB 2026-05-13T12:54:05Z

* [buildkit-v0.30.0.darwin-amd64.sigstore.json](/moby/buildkit/releases/download/v0.30.0/buildkit-v0.30.0.darwin-amd64.sigstore.json)

  sha256:bf62f31ec9db3a790bc24cf31b380d455aebafb6e19ab3800aac4087a5991b42

  113 KB 2026-05-13T12:54:05Z

* [buildkit-v0.30.0.darwin-amd64.tar.gz](/moby/buildkit/releases/download/v0.30.0/buildkit-v0.30.0.darwin-amd64.tar.gz)

  sha256:1e57293debc7ae15e405212bbef2f0086092f71df612631a30c7aa8f74b8f37c

  16.7 MB 2026-05-13T12:54:05Z

* [buildkit-v0.30.0.darwin-arm64.provenance.json](/moby/buildkit/releases/download/v0.30.0/buildkit-v0.30.0.darwin-arm64.provenance.json)

  sha256:95d91bbb8d2fc02446493e4d25e0abb1fb2b4f357c27f0a390825c4a2e9806e1

  76.5 KB 2026-05-13T12:54:05Z

* [buildkit-v0.30.0.darwin-arm64.sbom.json](/moby/buildkit/releases/download/v0.30.0/buildkit-v0.30.0.darwin-arm64.sbom.json)

  sha256:3b35e2c0af0ae4c37e5ca522e320a5f1c963eae48a1fd9896987dec8d82faeda

  153 KB 2026-05-13T12:54:05Z

* [buildkit-v0.30.0.darwin-arm64.sigstore.json](/moby/buildkit/releases/download/v0.30.0/buildkit-v0.30.0.darwin-arm64.sigstore.json)

  sha256:a1277025d3e841ff35bd007fdc92696f2980196c9143082de2e09cc8178c77fb

  112 KB 2026-05-13T12:54:05Z

* [buildkit-v0.30.0.darwin-arm64.tar.gz](/moby/buildkit/releases/download/v0.30.0/buildkit-v0.30.0.darwin-arm64.tar.gz)

  sha256:0ceb020e2e38bc54348230faa1f281b29cb78588552b8820f453deb3784f3acb

  15.6 MB 2026-05-13T12:54:05Z

* [buildkit-v0.30.0.linux-amd64.provenance.json](/moby/buildkit/releases/download/v0.30.0/buildkit-v0.30.0.linux-amd64.provenance.json)

  sha256:f5c9c4e1a57f63684c921a7f5e0b53b8186620fb416a8eee9437eac51a2eead5

  143 KB 2026-05-13T12:54:05Z

* [buildkit-v0.30.0.linux-amd64.sbom.json](/moby/buildkit/releases/download/v0.30.0/buildkit-v0.30.0.linux-amd64.sbom.json)

  sha256:62c7856b956ea3e253a08e313a4a46a35af6baa1e6f3a0ad8dd1aea7bf8f7ee5

  672 KB 2026-05-13T12:54:05Z

* [Source code (zip)](/moby/buildkit/archive/refs/tags/v0.30.0.zip)

  2026-05-13T12:26:33Z

* [Source code (tar.gz)](/moby/buildkit/archive/refs/tags/v0.30.0.tar.gz)

  2026-05-13T12:26:33Z

* Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

3 people reacted

## dockerfile/1.24.0-labs

13 May 13:16

[github-actions](/apps/github-actions)

[dockerfile/1.24.0-labs](/moby/buildkit/tree/dockerfile/1.24.0-labs)

This tag was signed with the committer’s **verified signature**.

[](/crazy-max)[crazy-max](/crazy-max) CrazyMax

GPG key ID: ADE44D8C9D44FBE4

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`dd2170e`](/moby/buildkit/commit/dd2170e156c9633da1b2d1a58a6188e3f7d36fa4)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[dockerfile/1.24.0-labs](/moby/buildkit/releases/tag/dockerfile%2F1.24.0-labs)

### Usage

```
# syntax=docker.io/docker/dockerfile-upstream:1.24.0-labs
```

Assets 2

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## dockerfile/1.24.0

13 May 13:16

[github-actions](/apps/github-actions)

[dockerfile/1.24.0](/moby/buildkit/tree/dockerfile/1.24.0)

This tag was signed with the committer’s **verified signature**.

[](/crazy-max)[crazy-max](/crazy-max) CrazyMax

GPG key ID: ADE44D8C9D44FBE4

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`dd2170e`](/moby/buildkit/commit/dd2170e156c9633da1b2d1a58a6188e3f7d36fa4)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[dockerfile/1.24.0](/moby/buildkit/releases/tag/dockerfile%2F1.24.0)

### Usage

```
# syntax=docker.io/docker/dockerfile-upstream:1.24.0
```

### Notable changes

* Dockerfile now supports special arg definitions `SOURCE_DATE_EPOCH=context` and `SOURCE_DATE_EPOCH=<stage>` which set the value of `SOURCE_DATE_EPOCH` to the timestamp associated with the remote context or the stage respectively. When building from a Git commit, the context timestamp is the commit timestamp, and when building from a remote URL, the timestamp is resolved from the metadata of files in the TAR archive or from the `Last-Modified` header of the URL [#6602](https://github.com/moby/buildkit/pull/6602)
* Fix issue where in some cases `LABEL` value could incorrectly leak from stage linked via `COPY --from` [#6713](https://github.com/moby/buildkit/pull/6713)
* Formatting of History entries for `HEALTHCHECK` instructions has been fixed [#6664](https://github.com/moby/buildkit/pull/6664)

Assets 2

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

1 person reacted

## v0.30.0-rc2

11 May 22:05

[github-actions](/apps/github-actions)

[v0.30.0-rc2](/moby/buildkit/tree/v0.30.0-rc2)

This tag was signed with the committer’s **verified signature**. The key has expired.

[](/tonistiigi)[tonistiigi](/tonistiigi) Tõnis Tiigi

GPG key ID: AFA9DE5F8AB7AF39

Expired

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`f2e48d2`](/moby/buildkit/commit/f2e48d20dc7d744a4051d6b5591b851a29a6232f)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.30.0-rc2](/moby/buildkit/releases/tag/v0.30.0-rc2) Pre-release

Pre-release

buildkit 0.30.0-rc2

Welcome to the v0.30.0-rc2 release of buildkit!\
*This is a pre-release of buildkit*

Please try out the release binaries and report any issues at\
<https://github.com/moby/buildkit/issues>.

### Contributors

* Tõnis Tiigi
* CrazyMax
* Jonathan A. Sternberg
* Natnael Gebremariam
* Sebastiaan van Stijn

### Notable Changes

* The version of the built-in Dockerfile frontend that was used is now included in the provenance metadata and reported via worker info APIs. [#6705](https://github.com/moby/buildkit/pull/6705)
* Improve error reporting for registry errors on cache export [#6762](https://github.com/moby/buildkit/pull/6762)
* Fix possible data race in provenance computation on parallel builds [#6758](https://github.com/moby/buildkit/pull/6758)
* Revert "In special modes where the client does not expose the session connection to transfer credentials, builds can now still fall back to anonymous registry auth instead of erroring". Requires more testing. [#6744](https://github.com/moby/buildkit/pull/6744)

### Dependency Changes

* **github.com/Azure/azure-sdk-for-go/sdk/azcore** v1.20.0 -> v1.21.0
* **github.com/go-openapi/runtime** v0.29.2 -> v0.29.3
* **github.com/go-openapi/swag** v0.25.4 -> v0.25.5
* **github.com/go-openapi/swag/cmdutils** v0.25.4 -> v0.25.5
* **github.com/go-openapi/swag/netutils** v0.25.4 -> v0.25.5
* **github.com/moby/policy-helpers** b7c0b994300b -> a39d60132186
* **github.com/sigstore/sigstore** v1.10.4 -> v1.10.5
* **github.com/sigstore/timestamp-authority/v2** v2.0.3 -> v2.0.6

Previous release can be found at [v0.30.0-rc1](https://github.com/moby/buildkit/releases/tag/v0.30.0-rc1)

Assets 42

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

1 person reacted

## v0.30.0-rc1

07 May 01:32

[github-actions](/apps/github-actions)

[v0.30.0-rc1](/moby/buildkit/tree/v0.30.0-rc1)

This tag was signed with the committer’s **verified signature**. The key has expired.

[](/tonistiigi)[tonistiigi](/tonistiigi) Tõnis Tiigi

GPG key ID: AFA9DE5F8AB7AF39

Expired

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`6baf355`](/moby/buildkit/commit/6baf355a08f32b7a13b2cd38dd2bfcf4e9b49c15)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.30.0-rc1](/moby/buildkit/releases/tag/v0.30.0-rc1) Pre-release

Pre-release

buildkit 0.30.0-rc1

Welcome to the v0.30.0-rc1 release of buildkit!\
*This is a pre-release of buildkit*

Please try out the release binaries and report any issues at\
<https://github.com/moby/buildkit/issues>.

### Contributors

* Tõnis Tiigi
* CrazyMax
* Sebastiaan van Stijn
* Jonathan A. Sternberg
* Akihiro Suda
* Natnael Gebremariam
* Dawei Wei
* Dmitrii Kostyrev
* Jiří Moravčík
* Vladimir Kuznichenkov

### Notable Changes

* Builtin Dockerfile frontend has been updated to v1.24.0-rc1 [changelog](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.24.0-rc1)
* BuildKit now supports the concept of "compatibility version" for improved reproducible builds support across different BuildKit versions. This allows users to specify a version for which the build should be compatible with, and BuildKit will attempt to maintain compatibility with that version when possible. Compatibility version will be stored in the provenance attestation of the build and can be used to independently verify the artifacts of the build on other BuildKit versions. The current compatibility version and backward compatibility with old versions are defined in [Build reproducibility docs](https://github.com/moby/buildkit/blob/v0.30.0-rc1/docs/build-repro.md#compatibility-version) [#6681](https://github.com/moby/buildkit/pull/6681)
* Git sources now support `fetch-by-commit` option where commit is fetched by the SHA and then associated with the reference. This is useful when checking out mutable references `refs/NR/merge` where the commit SHA may change during invocation and cause checksum mismatch error [#6708](https://github.com/moby/buildkit/pull/6708)
* The LLB API now supports Git bundle format. Git bundles can be loaded from registry or OCI layout blobs and Git sources can be checked out into bundle format for snapshotting [#6711](https://github.com/moby/buildkit/pull/6711)
* Provenance attestations for multi-pass or chained builds now include request details for root requests and individual input requests, allowing full reconstruction of such complex builds [#6739](https://github.com/moby/buildkit/pull/6739)
* S3 cache now supports additional options `retry_mode` and `retry_max_attempts` to configure retry behavior of S3 client [#6657](https://github.com/moby/buildkit/pull/6657)
* S3 cache now supports `disable_accept_encoding` option for GCS interoperability [#6642](https://github.com/moby/buildkit/pull/6642)
* Reduce potential lock contention in gateway forwarder for improved performance on parallel builds [#6741](https://github.com/moby/buildkit/pull/6741)
* A new log level option has been added to the buildkitd TOML configuration; previous "debug" and "trace" options have been deprecated [#6732](https://github.com/moby/buildkit/pull/6732)
* Allow gateway frontend requests to forward to the built-in Dockerfile frontend the same way as to external frontends [#6643](https://github.com/moby/buildkit/pull/6643)
* In special modes where the client does not expose the session connection to transfer credentials, builds can now still fall back to anonymous registry auth instead of erroring [#6744](https://github.com/moby/buildkit/pull/6744)
* Session connection health checks have been improved to better detect loss of connectivity and avoid stuck builds [#6649](https://github.com/moby/buildkit/pull/6649)
* Fix issue with Git subdirectory value not being included in ConfigSource section of SLSA provenance for builds from Git sources [#6724](https://github.com/moby/buildkit/pull/6724)
* Avoid potential deadlock if the credential helper in the client is misbehaving and never returns credentials [#6709](https://github.com/moby/buildkit/pull/6709)
* Fix possible data race in progress writer [#6679](https://github.com/moby/buildkit/pull/6679)
* Fix data race in S3 cache reader [#6675](https://github.com/moby/buildkit/pull/6675)
* Fix possible Git config lookup errors on Windows [#6639](https://github.com/moby/buildkit/pull/6639)
* Fix build cancellation not working properly when blocked on credential callback [#6641](https://github.com/moby/buildkit/pull/6641)

### Dependency Changes

* **github.com/Microsoft/hcsshim** v0.14.0-rc.1 -> v0.14.1
* **github.com/aws/aws-sdk-go-v2** v1.41.4 -> v1.41.7
* **github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream** v1.7.5 -> v1.7.8
* **github.com/aws/aws-sdk-go-v2/config** v1.32.12 -> v1.32.17
* **github.com/aws/aws-sdk-go-v2/credentials** v1.19.12 -> v1.19.16
* **github.com/aws/aws-sdk-go-v2/feature/ec2/imds** v1.18.20 -> v1.18.23
* **github.com/aws/aws-sdk-go-v2/internal/configsources** v1.4.20 -> v1.4.23
* **github.com/aws/aws-sdk-go-v2/internal/endpoints/v2** v2.7.20 -> v2.7.23
* **github.com/aws/aws-sdk-go-v2/internal/v4a** v1.4.12 -> v1.4.24
* **github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding** v1.13.7 -> v1.13.9
* **github.com/aws/aws-sdk-go-v2/service/internal/checksum** v1.9.3 -> v1.9.12
* **github.com/aws/aws-sdk-go-v2/service/internal/presigned-url** v1.13.20 -> v1.13.23
* **github.com/aws/aws-sdk-go-v2/service/internal/s3shared** v1.19.12 -> v1.19.20
* **github.com/aws/aws-sdk-go-v2/service/signin** v1.0.8 -> v1.0.11
* **github.com/aws/aws-sdk-go-v2/service/sso** v1.30.13 -> v1.30.17
* **github.com/aws/aws-sdk-go-v2/service/ssooidc** v1.35.17 -> v1.35.21
* **github.com/aws/aws-sdk-go-v2/service/sts** v1.41.9 -> v1.42.1
* **github.com/aws/smithy-go** v1.24.2 -> v1.25.1
* **github.com/containerd/containerd/v2** v2.2.2 -> v2.2.3
* **github.com/docker/cli** v29.3.1 -> v29.4.2
* **github.com/grpc-ecosystem/grpc-gateway/v2** v2.27.7 -> v2.28.0
* **github.com/in-toto/in-toto-golang** v0.10.0 -> v0.11.0
* **github.com/klauspost/compress** v1.18.5 -> v1.18.6
* **github.com/moby/profiles/seccomp** v0.1.0 -> v0.2.3
* **go.opentelemetry.io/otel/metric** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/sdk** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/sdk/metric** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/trace** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/proto/otlp** v1.9.0 -> v1.10.0
* **google.golang.org/genproto/googleapis/api** 8636f8732409 -> 6f92a3bedf2d
* **google.golang.org/genproto/googleapis/rpc** 8636f8732409 -> 6f92a3bedf2d
* **google.golang.org/grpc** v1.79.3 -> v1.80.0
* **kernel.org/pub/linux/libs/security/libcap/cap** v1.2.77 -> v1.2.78
* **kernel.org/pub/linux/libs/security/libcap/psx** v1.2.77 -> v1.2.78

Previous release can be found at [v0.29.0](https://github.com/moby/buildkit/releases/tag/v0.29.0)

Assets 42

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

1 person reacted

## dockerfile/1.24.0-rc1-labs

07 May 01:30

[github-actions](/apps/github-actions)

[dockerfile/1.24.0-rc1-labs](/moby/buildkit/tree/dockerfile/1.24.0-rc1-labs)

[`6baf355`](/moby/buildkit/commit/6baf355a08f32b7a13b2cd38dd2bfcf4e9b49c15)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[dockerfile/1.24.0-rc1-labs](/moby/buildkit/releases/tag/dockerfile%2F1.24.0-rc1-labs) Pre-release

Pre-release

### Usage

```
# syntax=docker.io/docker/dockerfile-upstream:1.24.0-labs
```

Assets 2

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## dockerfile/1.24.0-rc1

07 May 01:31

[github-actions](/apps/github-actions)

[dockerfile/1.24.0-rc1](/moby/buildkit/tree/dockerfile/1.24.0-rc1)

[`6baf355`](/moby/buildkit/commit/6baf355a08f32b7a13b2cd38dd2bfcf4e9b49c15)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[dockerfile/1.24.0-rc1](/moby/buildkit/releases/tag/dockerfile%2F1.24.0-rc1) Pre-release

Pre-release

### Usage

```
# syntax=docker.io/docker/dockerfile-upstream:1.24.0-rc1
```

### Notable changes

* Dockerfile now supports special arg definitions `SOURCE_DATE_EPOCH=context` and `SOURCE_DATE_EPOCH=<stage>` which set the value of `SOURCE_DATE_EPOCH` to the timestamp associated with the remote context or the stage respectively. When building from a Git commit, the context timestamp is the commit timestamp, and when building from a remote URL, the timestamp is resolved from the metadata of files in the TAR archive or from the `Last-Modified` header of the URL [#6602](https://github.com/moby/buildkit/pull/6602)
* Fix issue where in some cases `LABEL` value could incorrectly leak from stage linked via `COPY --from` [#6713](https://github.com/moby/buildkit/pull/6713)
* Formatting of History entries for `HEALTHCHECK` instructions has been fixed [#6664](https://github.com/moby/buildkit/pull/6664)

Assets 2

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

1 person reacted

## v0.29.0

31 Mar 12:58

[github-actions](/apps/github-actions)

[v0.29.0](/moby/buildkit/tree/v0.29.0)

[`8543ce4`](/moby/buildkit/commit/8543ce4428265d547cb009e5ad62348284497a88)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.29.0](/moby/buildkit/releases/tag/v0.29.0)

Welcome to the v0.29.0 release of buildkit!

Please try out the release binaries and report any issues at\
<https://github.com/moby/buildkit/issues>.

### Contributors

* Tõnis Tiigi
* CrazyMax
* David Karlsson
* Akihiro Suda
* Sebastiaan van Stijn
* Brian Ristuccia
* Jonathan A. Sternberg
* Mateusz Gozdek
* Natnael Gebremariam

### Notable Changes

* Builtin Dockerfile frontend has been updated to v1.23.0 [changelog](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.23.0)
* Git sources can now initialize all files from a Git checkout with commit time in the LLB API for better reproducibility. See [Dockerfile changelog](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.23.0) for how to enable this in the Dockerfile frontend [#6600](https://github.com/moby/buildkit/pull/6600)
* Various file access operations in Git and HTTP sources have been hardened for improved security [#6613](https://github.com/moby/buildkit/pull/6613)
* Frontends can now report updated `SOURCE_DATE_EPOCH` with result metadata that can be used by exporters [#6601](https://github.com/moby/buildkit/pull/6601)
* Fix possible panic when listing build history after recent deletions [#6614](https://github.com/moby/buildkit/pull/6614)
* Fix possible issue where builds from Git repositories could start to fail after submodule rename [#6563](https://github.com/moby/buildkit/pull/6563)
* Fix possible process lifecycle event ordering issue in interactive container API that could cause deadlocks in the client [#6531](https://github.com/moby/buildkit/pull/6531)
* Fix regression where build progress skipped the message about layers being pushed to the registry [#6587](https://github.com/moby/buildkit/pull/6587)
* Fix possible cgroup initialization failure in BuildKit container image entrypoint on some environments [#6585](https://github.com/moby/buildkit/pull/6585)
* Fix issue with resolving symlinks via file access methods of the Gateway API [#6559](https://github.com/moby/buildkit/pull/6559)
* Fix possible "parent snapshot does not exist" error when exporting images in parallel [#6558](https://github.com/moby/buildkit/pull/6558)
* Fix possible panic from zstd compression [#6599](https://github.com/moby/buildkit/pull/6599)
* Fix issue where cache imports from an uninitialized local cache tag could fail the build [#6554](https://github.com/moby/buildkit/pull/6554)
* Included CNI plugins have been updated to v1.9.1 [#6583](https://github.com/moby/buildkit/pull/6583)
* Included QEMU emulator support has been updated to v10.2.1 [#6580](https://github.com/moby/buildkit/pull/6580)
* Runc container runtime has been updated to v1.3.5 [#6625](https://github.com/moby/buildkit/pull/6625)

### Dependency Changes

* **github.com/aws/aws-sdk-go-v2** v1.41.1 -> v1.41.4
* **github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream** v1.7.4 -> v1.7.5
* **github.com/containerd/cgroups/v3** v3.1.2 -> v3.1.3
* **github.com/containerd/containerd/v2** v2.2.1 -> v2.2.2
* **github.com/containerd/nydus-snapshotter** v0.15.11 -> v0.15.13
* **github.com/containerd/ttrpc** v1.2.7 -> v1.2.8
* **github.com/containernetworking/plugins** v1.9.0 -> v1.9.1
* **github.com/go-viper/mapstructure/v2** v2.4.0 -> v2.5.0
* **github.com/grpc-ecosystem/grpc-gateway/v2** v2.27.3 -> v2.27.7
* **github.com/klauspost/compress** v1.18.4 -> v1.18.5

Previous release can be found at [v0.28.1](https://github.com/moby/buildkit/releases/tag/v0.28.1)

Assets 42

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## dockerfile/1.23.0-labs

31 Mar 12:57

[github-actions](/apps/github-actions)

[dockerfile/1.23.0-labs](/moby/buildkit/tree/dockerfile/1.23.0-labs)

[`8543ce4`](/moby/buildkit/commit/8543ce4428265d547cb009e5ad62348284497a88)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[dockerfile/1.23.0-labs](/moby/buildkit/releases/tag/dockerfile%2F1.23.0-labs)

### Usage

```
# syntax=docker.io/docker/dockerfile-upstream:1.23.0-labs
```

Assets 2

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## dockerfile/1.23.0

31 Mar 12:57

[github-actions](/apps/github-actions)

[dockerfile/1.23.0](/moby/buildkit/tree/dockerfile/1.23.0)

[`8543ce4`](/moby/buildkit/commit/8543ce4428265d547cb009e5ad62348284497a88)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[dockerfile/1.23.0](/moby/buildkit/releases/tag/dockerfile%2F1.23.0)

### Usage

```
# syntax=docker.io/docker/dockerfile-upstream:1.23.0
```

### Notable changes

* Git URLs now accept the `mtime=commit` query parameter to initialize checked-out file timestamps to Git commit time. Remote builds using a Git context that define `SOURCE_DATE_EPOCH` automatically default to `mtime=commit` for better reproducibility. [#6600](https://github.com/moby/buildkit/pull/6600)
* Dockerfile can now define `SOURCE_DATE_EPOCH` build-arg in the global scope with a default value. The value can still be overridden with `--build-arg` as before. [#6601](https://github.com/moby/buildkit/pull/6601)
* Fix issue with the order of applied proxy build-args being non-deterministic [#6560](https://github.com/moby/buildkit/pull/6560)

Assets 2

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

You can’t perform that action at this time.

----
url: https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/
----

# Apply rolling updates to a service

***

***

In a previous step of the tutorial, you [scaled](https://docs.docker.com/engine/swarm/swarm-tutorial/scale-service/) the number of instances of a service. In this part of the tutorial, you deploy a service based on the Redis 7.4.0 container tag. Then you upgrade the service to use the Redis 7.4.1 container image using rolling updates.

1. If you haven't already, open a terminal and ssh into the machine where you run your manager node. For example, the tutorial uses a machine named `manager1`.

2. Deploy your Redis tag to the swarm and configure the swarm with a 10 second update delay. Note that the following example shows an older Redis tag:

   ```console
   $ docker service create \
     --replicas 3 \
     --name redis \
     --update-delay 10s \
     redis:7.4.0

   0u6a4s31ybk7yw2wyvtikmu50
   ```

   You configure the rolling update policy at service deployment time.

   The `--update-delay` flag configures the time delay between updates to a service task or sets of tasks. You can describe the time `T` as a combination of the number of seconds `Ts`, minutes `Tm`, or hours `Th`. So `10m30s` indicates a 10 minute 30 second delay.

   By default the scheduler updates 1 task at a time. You can pass the `--update-parallelism` flag to configure the maximum number of service tasks that the scheduler updates simultaneously.

   By default, when an update to an individual task returns a state of `RUNNING`, the scheduler schedules another task to update until all tasks are updated. If at any time during an update a task returns `FAILED`, the scheduler pauses the update. You can control the behavior using the `--update-failure-action` flag for `docker service create` or `docker service update`.

3. Inspect the `redis` service:

   ```console
   $ docker service inspect --pretty redis

   ID:             0u6a4s31ybk7yw2wyvtikmu50
   Name:           redis
   Service Mode:   Replicated
    Replicas:      3
   Placement:
    Strategy:	    Spread
   UpdateConfig:
    Parallelism:   1
    Delay:         10s
   ContainerSpec:
    Image:         redis:7.4.0
   Resources:
   Endpoint Mode:  vip
   ```

4. Now you can update the container image for `redis`. The swarm manager applies the update to nodes according to the `UpdateConfig` policy:

   ```console
   $ docker service update --image redis:7.4.1 redis
   redis
   ```

   The scheduler applies rolling updates as follows by default:

   * Stop the first task.
   * Schedule update for the stopped task.
   * Start the container for the updated task.
   * If the update to a task returns `RUNNING`, wait for the specified delay period then start the next task.
   * If, at any time during the update, a task returns `FAILED`, pause the update.

5. Run `docker service inspect --pretty redis` to see the new image in the desired state:

   ```console
   $ docker service inspect --pretty redis

   ID:             0u6a4s31ybk7yw2wyvtikmu50
   Name:           redis
   Service Mode:   Replicated
    Replicas:      3
   Placement:
    Strategy:	    Spread
   UpdateConfig:
    Parallelism:   1
    Delay:         10s
   ContainerSpec:
    Image:         redis:7.4.1
   Resources:
   Endpoint Mode:  vip
   ```

   The output of `service inspect` shows if your update paused due to failure:

   ```console
   $ docker service inspect --pretty redis

   ID:             0u6a4s31ybk7yw2wyvtikmu50
   Name:           redis
   ...snip...
   Update status:
    State:      paused
    Started:    11 seconds ago
    Message:    update paused due to failure or early termination of task 9p7ith557h8ndf0ui9s0q951b
   ...snip...
   ```

   To restart a paused update run `docker service update <SERVICE-ID>`. For example:

   ```console
   $ docker service update redis
   ```

   To avoid repeating certain update failures, you may need to reconfigure the service by passing flags to `docker service update`.

6. Run `docker service ps <SERVICE-ID>` to watch the rolling update:

   ```console
   $ docker service ps redis

   NAME                                   IMAGE        NODE       DESIRED STATE  CURRENT STATE            ERROR
   redis.1.dos1zffgeofhagnve8w864fco      redis:7.4.1  worker1    Running        Running 37 seconds
    \_ redis.1.88rdo6pa52ki8oqx6dogf04fh  redis:7.4.0  worker2    Shutdown       Shutdown 56 seconds ago
   redis.2.9l3i4j85517skba5o7tn5m8g0      redis:7.4.1  worker2    Running        Running About a minute
    \_ redis.2.66k185wilg8ele7ntu8f6nj6i  redis:7.4.0  worker1    Shutdown       Shutdown 2 minutes ago
   redis.3.egiuiqpzrdbxks3wxgn8qib1g      redis:7.4.1  worker1    Running        Running 48 seconds
    \_ redis.3.ctzktfddb2tepkr45qcmqln04  redis:7.4.0  mmanager1  Shutdown       Shutdown 2 minutes ago
   ```

   Before Swarm updates all of the tasks, you can see that some are running `redis:7.4.0` while others are running `redis:7.4.1`. The output above shows the state once the rolling updates are done.

## [Next steps](#next-steps)

Next, you'll learn how to drain a node in the swarm.

[Drain a node](https://docs.docker.com/engine/swarm/swarm-tutorial/drain-node/)

----
url: https://docs.docker.com/scout/policy/configure/
----

# Configure policies

***

Table of contents

***

Some policy types are configurable. This means that you can create new, customized version of that policy type with your own configuration parameters. You can also disable a policy if you need to temporarily disregard it, or delete a policy altogether if it doesn't match your needs.

> Note
>
> Historic evaluation results for the default policy configuration are removed if you delete or customize a policy.

## [Add a policy](#add-a-policy)

To add a new policy, select the policy type that you want to customize. All custom policies use a policy type as a base.

You can edit the display name and description of the new policy to help better communicate the compliant and non-compliant states of the policy. You can not change the name of the policy type, only its display names.

The available configuration parameters for a policy depends on the policy type that you're editing. For more information, refer to [Policy types](https://docs.docker.com/scout/policy/#policy-types).

To add a policy:

1. Go to the [Policies page](https://scout.docker.com/reports/policy) in the Docker Scout Dashboard.

2. Select the **Add policy** button to open the policy configuration screen.

3. On the policy configuration screen, locate the policy type that you want to configure, and select **Configure** to open the policy configuration page.

   * If the **Configure** button is grayed out, it means the current policy has no configurable parameters.
   * If the button reads **Integrate**, it indicates that setup is required before the policy can be enabled. Selecting **Integrate** will direct you to the integration's setup guide.

4. Update the policy parameters.

5. Save the changes:

   * Select **Save policy** to commit the changes and enable the policy for your current organization.
   * Select **Save and disable** to save the policy configuration without enabling it.

## [Edit a policy](#edit-a-policy)

Editing a policy lets you to modify its configuration without creating a new one from scratch. This can be useful when policy parameters need adjustments due to evolving requirements or changes in your organization's compliance goals.

To edit a policy:

1. Go to the [Policies page](https://scout.docker.com/reports/policy) in the Docker Scout Dashboard.
2. Select the policy you want to edit.
3. Select the **Edit** button.
4. Update the policy parameters.
5. Save the changes.

## [Disable a policy](#disable-a-policy)

When you disable a policy, evaluation results for that policy are hidden, and no longer appear in the Docker Scout Dashboard or in the CLI. Historic evaluation results aren't deleted if you disable a policy, so if you change your mind and re-enable a policy later, results from earlier evaluations will still be available.

To disable a policy:

1. Go to the [Policies page](https://scout.docker.com/reports/policy) in the Docker Scout Dashboard.
2. Select the policy you want to disable.
3. Select the **Disable** button.

## [Delete a policy](#delete-a-policy)

When you delete a policy, evaluation results for that policy are deleted as well, and no longer appear in the Docker Scout Dashboard or in the CLI.

To delete a policy:

1. Go to the [Policies page](https://scout.docker.com/reports/policy) in the Docker Scout Dashboard.
2. Select the policy you want to delete.
3. Select the **Delete** button.

## [Recover a deleted policy](#recover-a-deleted-policy)

If you've deleted a policy, you can recreate it by following the steps in [Add a policy](#add-a-policy). On the policy configuration screen, select **Configure** on the deleted policy that you wish to recreate.

----
url: https://docs.docker.com/enterprise/security/provisioning/troubleshoot-provisioning/
----

# Troubleshoot provisioning

***

Table of contents

***

This page helps troubleshoot common user provisioning issues including user roles, attributes, and unexpected account behavior with SCIM and Just-in-Time (JIT) provisioning.

## [SCIM attribute values are overwritten or ignored](#scim-attribute-values-are-overwritten-or-ignored)

### [Error message](#error-message)

Typically, this scenario does not produce an error message in Docker or your IdP. This issue usually surfaces as incorrect role or team assignment.

### [Causes](#causes)

* JIT provisioning is enabled, and Docker is using values from your IdP's SSO sign in flow to provision the user, which overrides SCIM-provided attributes.
* SCIM was enabled after the user was already provisioned via JIT, so SCIM updates don't take effect.

### [Affected environments](#affected-environments)

* Docker organizations using SCIM with SSO
* Users provisioned via JIT prior to SCIM setup

### [Steps to replicate](#steps-to-replicate)

1. Enable JIT and SSO for your Docker organization.
2. Sign in to Docker as a user via SSO.
3. Enable SCIM and set role/team attributes for that user.
4. SCIM attempts to update the user's attributes, but the role or team assignment does not reflect changes.

### [Solutions](#solutions)

#### [Disable JIT provisioning (recommended)](#disable-jit-provisioning-recommended)

1. Sign in to [Docker Home](https://app.docker.com/).
2. Select **Admin Console**, then **SSO and SCIM**.
3. Find the relevant SSO connection.
4. Select the **actions menu** and choose **Edit**.
5. Disable **Just-in-Time provisioning**.
6. Save your changes.

With JIT disabled, Docker uses SCIM as the source of truth for user creation and role assignment.

**Keep JIT enabled and match attributes**

If you prefer to keep JIT enabled:

* Make sure your IdP's SSO attribute mappings match the values being sent by SCIM.
* Avoid configuring SCIM to override attributes already set via JIT.

This option requires strict coordination between SSO and SCIM attributes in your IdP configuration.

## [SCIM updates don't apply to existing users](#scim-updates-dont-apply-to-existing-users)

### [Causes](#causes-1)

User accounts were originally created manually or via JIT, and SCIM is not linked to manage them.

### [Solution](#solution)

SCIM only manages users that it provisions. To allow SCIM to manage an existing user:

1. Remove the user manually from the Docker [Admin Console](https://app.docker.com/admin).
2. Trigger provisioning from your IdP.
3. SCIM will re-create the user with correct attributes.

> Warning
>
> Deleting a user removes their resource ownership (e.g., repositories). Transfer ownership before removing the user.

----
url: https://docs.docker.com/engine/containers/start-containers-automatically/
----

# Start containers automatically

***

Table of contents

***

Docker provides [restart policies](/reference/cli/docker/container/run/#restart) to control whether your containers start automatically when they exit, or when Docker restarts. Restart policies start linked containers in the correct order. Docker recommends that you use restart policies, and avoid using process managers to start containers.

Restart policies are different from the `--live-restore` flag of the `dockerd` command. Using `--live-restore` lets you to keep your containers running during a Docker upgrade, though networking and user input are interrupted.

## [Use a restart policy](#use-a-restart-policy)

To configure the restart policy for a container, use the [`--restart`](/reference/cli/docker/container/run/#restart) flag when using the `docker run` command. The value of the `--restart` flag can be any of the following:

| Flag                       | Description                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `no`                       | Don't automatically restart the container. (Default)                                                                                                                                                                                                                                                                                                                  |
| `on-failure[:max-retries]` | Restart the container if it exits due to an error, which manifests as a non-zero exit code. Optionally, limit the number of times the Docker daemon attempts to restart the container using the `:max-retries` option. The `on-failure` policy only prompts a restart if the container exits with a failure. It doesn't restart the container if the daemon restarts. |
| `always`                   | Always restart the container if it stops. If it's manually stopped, it's restarted only when Docker daemon restarts or the container itself is manually restarted. (See the second bullet listed in [restart policy details](#restart-policy-details))                                                                                                                |
| `unless-stopped`           | Similar to `always`, except that when the container is stopped (manually or otherwise), it isn't restarted even after Docker daemon restarts.                                                                                                                                                                                                                         |

The following command starts a Redis container and configures it to always restart, unless the container is explicitly stopped, or the daemon restarts.

```console
$ docker run -d --restart unless-stopped redis
```

The following command changes the restart policy for an already running container named `redis`.

```console
$ docker update --restart unless-stopped redis
```

The following command ensures all running containers restart.

```console
$ docker update --restart unless-stopped $(docker ps -q)
```

### [Restart policy details](#restart-policy-details)

Keep the following in mind when using restart policies:

* A restart policy only takes effect after a container starts successfully. In this case, starting successfully means that the container is up for at least 10 seconds and Docker has started monitoring it. This prevents a container which doesn't start at all from going into a restart loop.

* If you manually stop a container, the restart policy is ignored until the Docker daemon restarts or the container is manually restarted. This prevents a restart loop.

* Restart policies only apply to containers. To configure restart policies for Swarm services, see [flags related to service restart](/reference/cli/docker/service/create/).

### [Restarting foreground containers](#restarting-foreground-containers)

When you run a container in the foreground, stopping a container causes the attached CLI to exit as well, regardless of the restart policy of the container. This behavior is illustrated in the following example.

1. Create a Dockerfile that prints the numbers 1 to 5 and then exits.

   ```dockerfile
   FROM busybox:latest
   COPY --chmod=755 <<"EOF" /start.sh
   echo "Starting..."
   for i in $(seq 1 5); do
     echo "$i"
     sleep 1
   done
   echo "Exiting..."
   exit 1
   EOF
   ENTRYPOINT /start.sh
   ```

2. Build an image from the Dockerfile.

   ```console
   $ docker build -t startstop .
   ```

3. Run a container from the image, specifying `always` for its restart policy.

   The container prints the numbers 1..5 to stdout, and then exits. This causes the attached CLI to exit as well.

   ```console
   $ docker run --restart always startstop
   Starting...
   1
   2
   3
   4
   5
   Exiting...
   $
   ```

4. Running `docker ps` shows that is still running or restarting, thanks to the restart policy. The CLI session has already exited, however. It doesn't survive the initial container exit.

   ```console
   $ docker ps
   CONTAINER ID   IMAGE       COMMAND                  CREATED         STATUS         PORTS     NAMES
   081991b35afe   startstop   "/bin/sh -c /start.sh"   9 seconds ago   Up 4 seconds             gallant_easley
   ```

5. You can re-attach your terminal to the container between restarts, using the `docker container attach` command. It's detached again the next time the container exits.

   ```console
   $ docker container attach 081991b35afe
   4
   5
   Exiting...
   $
   ```

## [Use a process manager](#use-a-process-manager)

If restart policies don't suit your needs, such as when processes outside Docker depend on Docker containers, you can use a process manager such as [systemd](https://systemd.io/) or [supervisor](http://supervisord.org/) instead.

> Warning
>
> Don't combine Docker restart policies with host-level process managers, as this creates conflicts.

To use a process manager, configure it to start your container or service using the same `docker start` or `docker service` command you would normally use to start the container manually. Consult the documentation for the specific process manager for more details.

### [Using a process manager inside containers](#using-a-process-manager-inside-containers)

Process managers can also run within the container to check whether a process is running and starts/restart it if not.

> Warning
>
> These aren't Docker-aware, and only monitor operating system processes within the container. Docker doesn't recommend this approach, because it's platform-dependent and may differ between versions of a given Linux distribution.

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/
----

# Settings Management

***

Table of contents

***

Subscription: Business

For: Administrators

Settings Management lets administrators configure and enforce Docker Desktop settings across end-user machines. It helps maintain consistent configurations and enhances security within your organization.

## [Who should use Settings Management?](#who-should-use-settings-management)

Settings Management is designed for organizations that:

* Need centralized control over Docker Desktop configurations
* Want to standardize Docker Desktop environments across teams
* Operate in regulated environments and must enforce compliance policies

## [How Settings Management works](#how-settings-management-works)

Administrators can define settings using one of these methods:

* [Admin Console](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/): Create and assign settings policies through the Docker Admin Console. This provides a web-based interface for managing settings across your organization.
* [`admin-settings.json` file](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/): Place a configuration file on the user's machine to enforce settings. This method works well for automated deployments and scripted installations.

Enforced settings override user-defined configurations and can't be modified by developers.

## [Configurable settings](#configurable-settings)

Settings Management supports a wide range of Docker Desktop features, including:

* Proxy configurations
* Network settings
* Container isolation options
* Registry access controls
* Resource limits
* Security policies
* Cloud policies

For a complete list of settings you can enforce, see the [Settings reference](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/settings-reference/).

## [Policy precedence](#policy-precedence)

When multiple policies exist, Docker Desktop applies them in this order:

1. User-specific policies: Highest priority
2. Organization default policy: Applied when no user-specific policy exists
3. Local `admin-settings.json` file: Lowest priority, overridden by Admin Console policies
4. [Configuration profiles](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#configuration-profiles-method-mac-only) when used to control proxy settings

## [Set up Settings Management](#set-up-settings-management)

You can create settings management policies at any time, but your organization needs to verify a domain before the policies take effect.

1. Check that you have [added and verified](https://docs.docker.com/enterprise/security/domain-management/#add-and-verify-a-domain) your organization's domain.

2. [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) to ensure all developers authenticate with your organization.

3. Choose a configuration method:

   * Use the `--admin-settings` installer flag on [macOS](https://docs.docker.com/desktop/setup/install/mac-install/#install-from-the-command-line) or [Windows](https://docs.docker.com/desktop/setup/install/windows-install/#install-from-the-command-line) to automatically create the `admin-settings.json`.
   * Manually create and configure the [`admin-settings.json` file](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/).
   * Create a settings policy in the [Docker Admin Console](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/).

After configuration, developers receive the enforced settings when they:

* Quit and relaunch Docker Desktop, then sign in
* Launch and sign in to Docker Desktop for the first time

> Note
>
> Docker Desktop doesn't automatically prompt users to restart or re-authenticate after a settings change. You may need to communicate these requirements to your developers.

## [Developer experience](#developer-experience)

When settings are enforced:

* Settings options appear grayed out in Docker Desktop and can't be modified through the Dashboard, CLI, or configuration files
* If Enhanced Container Isolation is enabled, developers can't use privileged containers or similar methods to alter enforced settings within the Docker Desktop Linux VM

This ensures consistent environments while maintaining a clear visual indication of which settings are managed by administrators.

## [View applied settings](#view-applied-settings)

When administrators apply Settings Management policies, Docker Desktop greys out most enforced settings in the GUI.

The Docker Desktop GUI doesn't currently display all centralized settings, particularly Enhanced Container Isolation (ECI) settings that administrators apply via the Admin Console.

As a workaround, you can check the `settings-store.json` file to view all applied settings:

* Mac: `~/Library/Application Support/Docker/settings-store.json`
* Windows: `%APPDATA%\Docker\settings-store.json`
* Linux: `~/.docker/desktop/settings-store.json`

The `settings-store.json` file contains all settings, including those that may not appear in the Docker Desktop GUI.

## [Limitations](#limitations)

Settings Management has the following limitations:

* Doesn't work in air-gapped or offline environments
* Not compatible with environments that restrict authentication with Docker Hub

## [Next steps](#next-steps)

Get started with Settings Management:

* [Configure Settings Management with the `admin-settings.json` file](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/)
* [Configure Settings Management with the Docker Admin Console](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/)

----
url: https://docs.docker.com/reference/cli/docker/compose/create/
----

# docker compose create

***

| Description | Creates containers for a service               |
| ----------- | ---------------------------------------------- |
| Usage       | `docker compose create [OPTIONS] [SERVICE...]` |

## [Description](#description)

Creates containers for a service

## [Options](#options)

| Option             | Default  | Description                                                                                    |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------- |
| `--build`          |          | Build images before starting containers                                                        |
| `--force-recreate` |          | Recreate containers even if their configuration and image haven't changed                      |
| `--no-build`       |          | Don't build an image, even if it's policy                                                      |
| `--no-recreate`    |          | If containers already exist, don't recreate them. Incompatible with --force-recreate.          |
| `--pull`           | `policy` | Pull image before running ("always"\|"missing"\|"never"\|"build")                              |
| `--quiet-pull`     |          | Pull without printing progress information                                                     |
| `--remove-orphans` |          | Remove containers for services not defined in the Compose file                                 |
| `--scale`          |          | Scale SERVICE to NUM instances. Overrides the `scale` setting in the Compose file if present.  |
| `-y, --yes`        |          | Assume "yes" as answer to all prompts and run non-interactively                                |

----
url: https://docs.docker.com/reference/cli/docker/scout/repo/
----

# docker scout repo

***

| Description | Commands to list, enable, and disable Docker Scout on repositories |
| ----------- | ------------------------------------------------------------------ |

## [Description](#description)

Commands to list, enable, and disable Docker Scout on repositories

## [Subcommands](#subcommands)

| Command                                                                                         | Description                    |
| ----------------------------------------------------------------------------------------------- | ------------------------------ |
| [`docker scout repo disable`](https://docs.docker.com/reference/cli/docker/scout/repo/disable/) | Disable Docker Scout           |
| [`docker scout repo enable`](https://docs.docker.com/reference/cli/docker/scout/repo/enable/)   | Enable Docker Scout            |
| [`docker scout repo list`](https://docs.docker.com/reference/cli/docker/scout/repo/list/)       | List Docker Scout repositories |

----
url: https://docs.docker.com/guides/ruby/
----

# Ruby on Rails language-specific guide

***

This guide explains how to containerize Ruby on Rails applications using Docker.

**Time to complete** 20 minutes

The Ruby language-specific guide teaches you how to containerize a Ruby on Rails application using Docker. In this guide, you’ll learn how to:

* Containerize and run a Ruby on Rails application
* Configure a GitHub Actions workflow to build and push a Docker image to Docker Hub
* Set up a local environment to develop a Ruby on Rails application using containers
* Deploy your containerized Ruby on Rails application locally to Kubernetes to test and debug your deployment

Start by containerizing an existing Ruby on Rails application.

## [Modules](#modules)

1. [Containerize your app](https://docs.docker.com/guides/ruby/containerize/)

   Learn how to containerize a Ruby on Rails application.

2. [GitHub Actions CI](https://docs.docker.com/guides/ruby/configure-github-actions/)

   Learn how to configure CI/CD using GitHub Actions for your Ruby on Rails application.

3. [Develop your app](https://docs.docker.com/guides/ruby/develop/)

   Learn how to develop your Ruby on Rails application locally.

4. [Test your deployment](https://docs.docker.com/guides/ruby/deploy/)

   Learn how to develop locally using Kubernetes

----
url: https://docs.docker.com/engine/swarm/key-concepts/
----

# Swarm mode key concepts

***

Table of contents

***

This topic introduces some of the concepts unique to the cluster management and orchestration features of Docker Engine 1.12.

## [What is a swarm?](#what-is-a-swarm)

The cluster management and orchestration features embedded in Docker Engine are built using [swarmkit](https://github.com/docker/swarmkit/). Swarmkit is a separate project which implements Docker's orchestration layer and is used directly within Docker.

A swarm consists of multiple Docker hosts which run in Swarm mode and act as managers, to manage membership and delegation, and workers, which run [swarm services](#services-and-tasks). A given Docker host can be a manager, a worker, or perform both roles. When you create a service, you define its optimal state - number of replicas, network and storage resources available to it, ports the service exposes to the outside world, and more. Docker works to maintain that desired state. For instance, if a worker node becomes unavailable, Docker schedules that node's tasks on other nodes. A task is a running container which is part of a swarm service and is managed by a swarm manager, as opposed to a standalone container.

One of the key advantages of swarm services over standalone containers is that you can modify a service's configuration, including the networks and volumes it is connected to, without the need to manually restart the service. Docker will update the configuration, stop the service tasks with out of date configuration, and create new ones matching the desired configuration.

When Docker is running in Swarm mode, you can still run standalone containers on any of the Docker hosts participating in the swarm, as well as swarm services. A key difference between standalone containers and swarm services is that only swarm managers can manage a swarm, while standalone containers can be started on any daemon. Docker daemons can participate in a swarm as managers, workers, or both.

In the same way that you can use [Docker Compose](https://docs.docker.com/compose/) to define and run containers, you can define and run [Swarm service](https://docs.docker.com/engine/swarm/services/) stacks.

Keep reading for details about concepts related to Docker swarm services, including nodes, services, tasks, and load balancing.

## [Nodes](#nodes)

A node is an instance of the Docker engine participating in the swarm. You can also think of this as a Docker node. You can run one or more nodes on a single physical computer or cloud server, but production swarm deployments typically include Docker nodes distributed across multiple physical and cloud machines.

To deploy your application to a swarm, you submit a service definition to a manager node. The manager node dispatches units of work called [tasks](#services-and-tasks) to worker nodes.

Manager nodes also perform the orchestration and cluster management functions required to maintain the desired state of the swarm. Manager nodes select a single leader to conduct orchestration tasks.

Worker nodes receive and execute tasks dispatched from manager nodes. By default manager nodes also run services as worker nodes, but you can configure them to run manager tasks exclusively and be manager-only nodes. An agent runs on each worker node and reports on the tasks assigned to it. The worker node notifies the manager node of the current state of its assigned tasks so that the manager can maintain the desired state of each worker.

## [Services and tasks](#services-and-tasks)

A service is the definition of the tasks to execute on the manager or worker nodes. It is the central structure of the swarm system and the primary root of user interaction with the swarm.

When you create a service, you specify which container image to use and which commands to execute inside running containers.

In the replicated services model, the swarm manager distributes a specific number of replica tasks among the nodes based upon the scale you set in the desired state.

For global services, the swarm runs one task for the service on every available node in the cluster.

A task carries a Docker container and the commands to run inside the container. It is the atomic scheduling unit of swarm. Manager nodes assign tasks to worker nodes according to the number of replicas set in the service scale. Once a task is assigned to a node, it cannot move to another node. It can only run on the assigned node or fail.

## [Load balancing](#load-balancing)

The swarm manager uses ingress load balancing to expose the services you want to make available externally to the swarm. The swarm manager can automatically assign the service a published port or you can configure a published port for the service. You can specify any unused port. If you do not specify a port, the swarm manager assigns the service a port in the 30000-32767 range.

External components, such as cloud load balancers, can access the service on the published port of any node in the cluster whether or not the node is currently running the task for the service. All nodes in the swarm route ingress connections to a running task instance.

Swarm mode has an internal DNS component that automatically assigns each service in the swarm a DNS entry. The swarm manager uses internal load balancing to distribute requests among services within the cluster based upon the DNS name of the service.

## [What's next?](#whats-next)

* Read the [Swarm mode overview](https://docs.docker.com/engine/swarm/).
* Get started with the [Swarm mode tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/).

----
url: https://docs.docker.com/guides/testcontainers-java-replace-h2/problem-with-h2/
----

# The problem with H2 for testing

***

Table of contents

***

A common practice is to use lightweight databases like H2 or HSQL as in-memory databases for testing while using PostgreSQL, MySQL, or Oracle in production. This approach has significant drawbacks:

* The test database might not support all features of your production database.
* SQL syntax might not be compatible between H2 and your production database.
* Tests passing with H2 don't guarantee they'll work in production.

## [Example: PostgreSQL-specific syntax](#example-postgresql-specific-syntax)

Consider implementing an "upsert" — insert a product only if it doesn't already exist. In PostgreSQL, you can use:

```sql
INSERT INTO products(id, code, name) VALUES(?,?,?) ON CONFLICT DO NOTHING;
```

This query doesn't work with H2 by default:

```text
Caused by: org.h2.jdbc.JdbcSQLException: Syntax error in SQL statement
"INSERT INTO products (id, code, name) VALUES (?, ?, ?) ON[*] CONFLICT DO NOTHING";
```

You can run H2 in PostgreSQL compatibility mode, but not all features are supported. The inverse is also true — H2 supports `ROWNUM()` which PostgreSQL doesn't.

Testing with a different database than production means you can't trust your test results and must verify after deployment, defeating the purpose of automated tests.

## [The Spring Boot test using H2](#the-spring-boot-test-using-h2)

A typical H2-based test looks like this:

```java
@DataJpaTest
class ProductRepositoryTest {

   @Autowired
   ProductRepository productRepository;

   @Test
   @Sql("classpath:/sql/seed-data.sql")
   void shouldGetAllProducts() {
       List<Product> products = productRepository.findAll();
       assertEquals(2, products.size());
   }
}
```

Spring Boot uses H2 automatically when it's on the classpath. The test passes, but it doesn't catch PostgreSQL-specific issues.

[Replace H2 with the Testcontainers JDBC URL »](https://docs.docker.com/guides/testcontainers-java-replace-h2/jdbc-url-approach/)

----
url: https://docs.docker.com/reference/samples/mysql/
----

# MySQL samples

| Name                                                                                                 | Description                                                                 |
| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [Go / NGINX / MySQL](https://github.com/docker/awesome-compose/tree/master/nginx-golang-mysql)       | A sample Go application with an Nginx proxy and a MySQL database.           |
| [Java Spark / MySQL](https://github.com/docker/awesome-compose/tree/master/sparkjava-mysql)          | A sample Java application and a MySQL database.                             |
| [NGINX / ASP.NET / MySQL](https://github.com/docker/awesome-compose/tree/master/nginx-aspnet-mysql)  | A sample Nginx reverse proxy with a C# backend using ASP.NET.               |
| [NGINX / Flask / MySQL](https://github.com/docker/awesome-compose/tree/master/nginx-flask-mysql)     | A sample Python/Flask application with an Nginx proxy and a MySQL database. |
| [React / Spring / MySQL](https://github.com/docker/awesome-compose/tree/master/react-java-mysql)     | A sample React application with a Spring backend and a MySQL database.      |
| [React / Express / MySQL](https://github.com/docker/awesome-compose/tree/master/react-express-mysql) | A sample React application with a Node.js backend and a MySQL database.     |
| [WordPress / MySQL](https://github.com/docker/awesome-compose/tree/master/wordpress-mysql)           | A sample WordPress setup.                                                   |
| [dotnet-album-viewer](https://github.com/dockersamples/dotnet-album-viewer)                          | West Wind Album Viewer ASP.NET Core and Angular sample.                     |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/engine/swarm/join-nodes/
----

# Join nodes to a swarm

***

Table of contents

***

When you first create a swarm, you place a single Docker Engine into Swarm mode. To take full advantage of Swarm mode you can add nodes to the swarm:

* Adding worker nodes increases capacity. When you deploy a service to a swarm, the engine schedules tasks on available nodes whether they are worker nodes or manager nodes. When you add workers to your swarm, you increase the scale of the swarm to handle tasks without affecting the manager raft consensus.
* Manager nodes increase fault-tolerance. Manager nodes perform the orchestration and cluster management functions for the swarm. Among manager nodes, a single leader node conducts orchestration tasks. If a leader node goes down, the remaining manager nodes elect a new leader and resume orchestration and maintenance of the swarm state. By default, manager nodes also run tasks.

Docker Engine joins the swarm depending on the **join-token** you provide to the `docker swarm join` command. The node only uses the token at join time. If you subsequently rotate the token, it doesn't affect existing swarm nodes. Refer to [Run Docker Engine in swarm mode](https://docs.docker.com/engine/swarm/swarm-mode/#view-the-join-command-or-update-a-swarm-join-token).

## [Join as a worker node](#join-as-a-worker-node)

To retrieve the join command including the join token for worker nodes, run the following command on a manager node:

```console
$ docker swarm join-token worker

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
    192.168.99.100:2377
```

Run the command from the output on the worker to join the swarm:

```console
$ docker swarm join \
  --token SWMTKN-1-49nj1cmql0jkz5s954yi3oex3nedyz0fb0xx14ie39trti4wxv-8vxv8rssmk743ojnwacrr2e7c \
  192.168.99.100:2377

This node joined a swarm as a worker.
```

The `docker swarm join` command does the following:

* Switches Docker Engine on the current node into Swarm mode.
* Requests a TLS certificate from the manager.
* Names the node with the machine hostname.
* Joins the current node to the swarm at the manager listen address based upon the swarm token.
* Sets the current node to `Active` availability, meaning it can receive tasks from the scheduler.
* Extends the `ingress` overlay network to the current node.

## [Join as a manager node](#join-as-a-manager-node)

When you run `docker swarm join` and pass the manager token, Docker Engine switches into Swarm mode the same as for workers. Manager nodes also participate in the raft consensus. The new nodes should be `Reachable`, but the existing manager remains the swarm `Leader`.

Docker recommends three or five manager nodes per cluster to implement high availability. Because Swarm-mode manager nodes share data using Raft, there must be an odd number of managers. The swarm can continue to function after as long as a quorum of more than half of the manager nodes are available.

For more detail about swarm managers and administering a swarm, see [Administer and maintain a swarm of Docker Engines](https://docs.docker.com/engine/swarm/admin_guide/).

To retrieve the join command including the join token for manager nodes, run the following command on a manager node:

```console
$ docker swarm join-token manager

To add a manager to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-61ztec5kyafptydic6jfc1i33t37flcl4nuipzcusor96k7kby-5vy9t8u35tuqm7vh67lrz9xp6 \
    192.168.99.100:2377
```

Run the command from the output on the new manager node to join it to the swarm:

```console
$ docker swarm join \
  --token SWMTKN-1-61ztec5kyafptydic6jfc1i33t37flcl4nuipzcusor96k7kby-5vy9t8u35tuqm7vh67lrz9xp6 \
  192.168.99.100:2377

This node joined a swarm as a manager.
```

## [Learn More](#learn-more)

* `swarm join` [command line reference](/reference/cli/docker/swarm/join/)

----
url: https://docs.docker.com/reference/cli/docker/service/ls/
----

# docker service ls

***

| Description                                                               | List services                 |
| ------------------------------------------------------------------------- | ----------------------------- |
| Usage                                                                     | `docker service ls [OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker service list`         |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

This command lists services that are running in the swarm.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --filter`](#filter) |         | Filter output based on conditions provided                                                                                                                                                                                                                                                                                                                                             |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-q, --quiet`             |         | Only display IDs                                                                                                                                                                                                                                                                                                                                                                       |

## [Examples](#examples)

On a manager node:

```console
$ docker service ls

ID            NAME      MODE            REPLICAS             IMAGE
c8wgl7q4ndfd  frontend  replicated      5/5                  nginx:alpine
dmu1ept4cxcf  redis     replicated      3/3                  redis:7.4.1
iwe3278osahj  mongo     global          7/7                  mongo:3.3
hh08h9uu8uwr  job       replicated-job  1/1 (3/5 completed)  nginx:latest
```

The `REPLICAS` column shows both the actual and desired number of tasks for the service. If the service is in `replicated-job` or `global-job`, it will additionally show the completion status of the job as completed tasks over total tasks the job will execute.

### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).

The currently supported filters are:

* [id](/reference/cli/docker/service/ls/#id)
* [label](/reference/cli/docker/service/ls/#label)
* [mode](/reference/cli/docker/service/ls/#mode)
* [name](/reference/cli/docker/service/ls/#name)

#### [id](#id)

The `id` filter matches all or the prefix of a service's ID.

The following filter matches services with an ID starting with `0bcjw`:

```console
$ docker service ls -f "id=0bcjw"
ID            NAME   MODE        REPLICAS  IMAGE
0bcjwfh8ychr  redis  replicated  1/1       redis:7.4.1
```

#### [label](#label)

The `label` filter matches services based on the presence of a `label` alone or a `label` and a value.

The following filter matches all services with a `project` label regardless of its value:

```console
$ docker service ls --filter label=project
ID            NAME       MODE        REPLICAS  IMAGE
01sl1rp6nj5u  frontend2  replicated  1/1       nginx:alpine
36xvvwwauej0  frontend   replicated  5/5       nginx:alpine
74nzcxxjv6fq  backend    replicated  3/3       redis:7.4.1
```

The following filter matches only services with the `project` label with the `project-a` value.

```console
$ docker service ls --filter label=project=project-a
ID            NAME      MODE        REPLICAS  IMAGE
36xvvwwauej0  frontend  replicated  5/5       nginx:alpine
74nzcxxjv6fq  backend   replicated  3/3       redis:7.4.1
```

#### [mode](#mode)

The `mode` filter matches on the mode (either `replicated` or `global`) of a service.

The following filter matches only `global` services.

```console
$ docker service ls --filter mode=global
ID                  NAME                MODE                REPLICAS            IMAGE
w7y0v2yrn620        top                 global              1/1                 busybox
```

#### [name](#name)

The `name` filter matches on all or the prefix of a service's name.

The following filter matches services with a name starting with `redis`.

```console
$ docker service ls --filter name=redis
ID            NAME   MODE        REPLICAS  IMAGE
0bcjwfh8ychr  redis  replicated  1/1       redis:7.4.1
```

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints services output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder | Description                             |
| ----------- | --------------------------------------- |
| `.ID`       | Service ID                              |
| `.Name`     | Service name                            |
| `.Mode`     | Service mode (replicated, global)       |
| `.Replicas` | Service replicas                        |
| `.Image`    | Service image                           |
| `.Ports`    | Service ports published in ingress mode |

When using the `--format` option, the `service ls` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `ID`, `Mode`, and `Replicas` entries separated by a colon (`:`) for all services:

```console
$ docker service ls --format "{{.ID}}: {{.Mode}} {{.Replicas}}"

0zmvwuiu3vue: replicated 10/10
fm6uf97exkul: global 5/5
```

To list all services in JSON format, use the `json` directive:

```console
$ docker service ls --format json
{"ID":"ssniordqolsi","Image":"hello-world:latest","Mode":"replicated","Name":"hello","Ports":"","Replicas":"0/1"}
```

----
url: https://docs.docker.com/ai/docker-agent/integrations/a2a/
----

# A2A mode

***

Table of contents

***

A2A mode runs your agent as an HTTP server that other systems can call using the Agent-to-Agent protocol. This lets you expose your agent as a service that other agents or applications can discover and invoke over the network.

Use A2A when you want to make your agent callable by other systems over HTTP. For editor integration, see [ACP integration](https://docs.docker.com/ai/docker-agent/integrations/acp/). For using agents as tools in MCP clients, see [MCP integration](https://docs.docker.com/ai/docker-agent/integrations/mcp/).

## [Prerequisites](#prerequisites)

Before starting an A2A server, you need:

* Docker Agent installed - See the [installation guide](https://docs.docker.com/ai/docker-agent/#installation)
* Agent configuration - A YAML file defining your agent. See the [tutorial](https://docs.docker.com/ai/docker-agent/tutorial/)
* API keys configured - If using cloud model providers (see [Model providers](https://docs.docker.com/ai/docker-agent/model-providers/))

## [Starting an A2A server](#starting-an-a2a-server)

Basic usage:

```console
$ docker agent serve a2a ./agent.yaml
```

Your agent is now accessible via HTTP. Other A2A systems can discover your agent's capabilities and call it.

Custom port:

```console
$ docker agent serve a2a ./agent.yaml --port 8080
```

Specific agent in a team:

```console
$ docker agent serve a2a ./agent.yaml --agent engineer
```

From OCI registry:

```console
$ docker agent serve a2a agentcatalog/pirate --port 9000
```

## [HTTP endpoints](#http-endpoints)

When you start an A2A server, it exposes two HTTP endpoints:

### [Agent card: `/.well-known/agent-card`](#agent-card-well-knownagent-card)

The agent card describes your agent's capabilities:

```console
$ curl http://localhost:8080/.well-known/agent-card
```

```json
{
  "name": "agent",
  "description": "A helpful coding assistant",
  "skills": [
    {
      "id": "agent_root",
      "name": "root",
      "description": "A helpful coding assistant",
      "tags": ["llm", "dockeragent"]
    }
  ],
  "preferredTransport": "jsonrpc",
  "url": "http://localhost:8080/invoke",
  "capabilities": {
    "streaming": true
  },
  "version": "0.1.0"
}
```

### [Invoke endpoint: `/invoke`](#invoke-endpoint-invoke)

Call your agent by sending a JSON-RPC request:

```console
$ curl -X POST http://localhost:8080/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "What is 2+2?"
          }
        ]
      }
    }
  }'
```

The response includes the agent's reply:

```json
{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "artifacts": [
      {
        "parts": [
          {
            "kind": "text",
            "text": "2+2 equals 4."
          }
        ]
      }
    ]
  }
}
```

## [Example: Multi-agent workflow](#example-multi-agent-workflow)

Here's a concrete scenario where A2A is useful. You have two agents:

1. A general-purpose agent that interacts with users
2. A specialized code review agent with access to your codebase

Run the specialist as an A2A server:

```console
$ docker agent serve a2a ./code-reviewer.yaml --port 8080
Listening on 127.0.0.1:8080
```

Configure your main agent to call it:

```yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    instruction: You are a helpful assistant
    toolsets:
      - type: a2a
        url: http://localhost:8080
        name: code-reviewer
```

Now when users ask the main agent about code quality, it can delegate to the specialist. The main agent sees `code-reviewer` as a tool it can call, and the specialist has access to the codebase tools it needs.

## [Calling other A2A agents](#calling-other-a2a-agents)

Your agents can call remote A2A agents as tools. Configure the A2A toolset with the remote agent's URL:

```yaml
agents:
  root:
    toolsets:
      - type: a2a
        url: http://localhost:8080
        name: specialist
```

The `url` specifies where the remote agent is running, and `name` is an optional identifier for the tool. Your agent can now delegate tasks to the remote specialist agent.

If the remote agent requires authentication or custom headers:

```yaml
agents:
  root:
    toolsets:
      - type: a2a
        url: http://localhost:8080
        name: specialist
        remote:
          headers:
            Authorization: Bearer token123
            X-Custom-Header: value
```

## [What's next](#whats-next)

* Review the [CLI reference](https://docs.docker.com/ai/docker-agent/reference/cli/#a2a) for all `docker agent serve a2a` options
* Learn about [MCP mode](https://docs.docker.com/ai/docker-agent/integrations/mcp/) to expose agents as tools in MCP clients
* Learn about [ACP mode](https://docs.docker.com/ai/docker-agent/integrations/acp/) for editor integration
* Share your agents with [OCI registries](https://docs.docker.com/ai/docker-agent/sharing-agents/)

----
url: https://docs.docker.com/build/builders/drivers/kubernetes/
----

# Kubernetes driver

***

Table of contents

***

The Kubernetes driver lets you connect your local development or CI environments to builders in a Kubernetes cluster to allow access to more powerful compute resources, optionally on multiple native architectures.

## [Synopsis](#synopsis)

Run the following command to create a new builder, named `kube`, that uses the Kubernetes driver:

```console
$ docker buildx create \
  --bootstrap \
  --name=kube \
  --driver=kubernetes \
  --driver-opt=[key=value,...]
```

The following table describes the available driver-specific options that you can pass to `--driver-opt`:

| Parameter                                  | Type         | Default                                 | Description                                                                                                                                                                                                   |
| ------------------------------------------ | ------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image`                                    | String       |                                         | Sets the image to use for running BuildKit.                                                                                                                                                                   |
| `namespace`                                | String       | Namespace in current Kubernetes context | Sets the Kubernetes namespace.                                                                                                                                                                                |
| `default-load`                             | Boolean      | `false`                                 | Automatically load images to the Docker Engine image store.                                                                                                                                                   |
| `replicas`                                 | Integer      | 1                                       | Sets the number of Pod replicas to create. See [scaling BuildKit](#scaling-buildkit)                                                                                                                          |
| `requests.cpu`                             | CPU units    |                                         | Sets the request CPU value specified in units of Kubernetes CPU. For example `requests.cpu=100m` or `requests.cpu=2`                                                                                          |
| `requests.memory`                          | Memory size  |                                         | Sets the request memory value specified in bytes or with a valid suffix. For example `requests.memory=500Mi` or `requests.memory=4G`                                                                          |
| `requests.ephemeral-storage`               | Storage size |                                         | Sets the request ephemeral-storage value specified in bytes or with a valid suffix. For example `requests.ephemeral-storage=2Gi`                                                                              |
| `persistent-volume-claim.requests.storage` | Storage size |                                         | Sets the requested size for a persistent volume claim. When set, Buildx creates a `StatefulSet` and stores the BuildKit build cache in the claim. For example `persistent-volume-claim.requests.storage=20Gi` |
| `limits.cpu`                               | CPU units    |                                         | Sets the limit CPU value specified in units of Kubernetes CPU. For example `requests.cpu=100m` or `requests.cpu=2`                                                                                            |
| `limits.memory`                            | Memory size  |                                         | Sets the limit memory value specified in bytes or with a valid suffix. For example `requests.memory=500Mi` or `requests.memory=4G`                                                                            |
| `limits.ephemeral-storage`                 | Storage size |                                         | Sets the limit ephemeral-storage value specified in bytes or with a valid suffix. For example `requests.ephemeral-storage=100M`                                                                               |
| `buildkit-root-volume-memory`              | Memory size  | Using regular file system               | Mounts `/var/lib/buildkit` on an `emptyDir` memory-backed volume, with `SizeLimit` as the value. For example, `buildkit-root-folder-memory=6G`                                                                |
| `nodeselector`                             | CSV string   |                                         | Sets the pod's `nodeSelector` label(s). See [node assignment](#node-assignment).                                                                                                                              |
| `annotations`                              | CSV string   |                                         | Sets additional annotations on the `Deployment` or `StatefulSet` and pods.                                                                                                                                    |
| `labels`                                   | CSV string   |                                         | Sets additional labels on the `Deployment` or `StatefulSet` and pods.                                                                                                                                         |
| `tolerations`                              | CSV string   |                                         | Configures the pod's taint toleration. See [node assignment](#node-assignment).                                                                                                                               |
| `serviceaccount`                           | String       |                                         | Sets the pod's `serviceAccountName`.                                                                                                                                                                          |
| `schedulername`                            | String       |                                         | Sets the scheduler responsible for scheduling the pod.                                                                                                                                                        |
| `timeout`                                  | Time         | `120s`                                  | Set the timeout limit that determines how long Buildx will wait for pods to be provisioned before a build.                                                                                                    |
| `rootless`                                 | Boolean      | `false`                                 | Run the container as a non-root user. See [rootless mode](#rootless-mode).                                                                                                                                    |
| `loadbalance`                              | String       | `sticky`                                | Load-balancing strategy (`sticky` or `random`). If set to `sticky`, the pod is chosen using the hash of the context path.                                                                                     |
| `qemu.install`                             | Boolean      | `false`                                 | Install QEMU emulation for multi platforms support. See [QEMU](#qemu).                                                                                                                                        |
| `qemu.image`                               | String       | `tonistiigi/binfmt:latest`              | Sets the QEMU emulation image. See [QEMU](#qemu).                                                                                                                                                             |

## [Scaling BuildKit](#scaling-buildkit)

One of the main advantages of the Kubernetes driver is that you can scale the number of builder replicas up and down to handle increased build load. Scaling is configurable using the following driver options:

* `replicas=N`

  This scales the number of BuildKit pods to the desired size. By default, it only creates a single pod. Increasing the number of replicas lets you take advantage of multiple nodes in your cluster.

* `requests.cpu`, `requests.memory`, `requests.ephemeral-storage`, `limits.cpu`, `limits.memory`, `limits.ephemeral-storage`

  These options allow requesting and limiting the resources available to each BuildKit pod [according to the official Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).

For example, to create 4 replica BuildKit pods:

```console
$ docker buildx create \
  --bootstrap \
  --name=kube \
  --driver=kubernetes \
  --driver-opt=namespace=buildkit,replicas=4
```

Listing the pods, you get this:

```console
$ kubectl -n buildkit get deployments
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
kube0   4/4     4            4           8s

$ kubectl -n buildkit get pods
NAME                     READY   STATUS    RESTARTS   AGE
kube0-6977cdcb75-48ld2   1/1     Running   0          8s
kube0-6977cdcb75-rkc6b   1/1     Running   0          8s
kube0-6977cdcb75-vb4ks   1/1     Running   0          8s
kube0-6977cdcb75-z4fzs   1/1     Running   0          8s
```

Additionally, you can use the `loadbalance=(sticky|random)` option to control the load-balancing behavior when there are multiple replicas. `random` selects random nodes from the node pool, providing an even workload distribution across replicas. `sticky` (the default) attempts to connect the same build performed multiple times to the same node each time, ensuring better use of local cache.

For more information on scalability, see the options for [`docker buildx create`](/reference/cli/docker/buildx/create/#driver-opt).

## [Persistent storage](#persistent-storage)

Set the `persistent-volume-claim.requests.storage` driver option to store the BuildKit build cache in a persistent volume claim instead of the pod filesystem. When you set this option, Buildx creates a `StatefulSet` instead of a `Deployment`.

If you also set `replicas`, each replica gets its own persistent volume claim. This keeps the build cache local to each pod across restarts.

For example, to create a builder with 20 GiB of persistent storage per replica:

```console
$ docker buildx create \
  --bootstrap \
  --name=kube \
  --driver=kubernetes \
  --driver-opt=namespace=buildkit,replicas=4,persistent-volume-claim.requests.storage=20Gi
```

## [Node assignment](#node-assignment)

The Kubernetes driver allows you to control the scheduling of BuildKit pods using the `nodeSelector` and `tolerations` driver options. You can also set the `schedulername` option if you want to use a custom scheduler altogether.

You can use the `annotations` and `labels` driver options to apply additional metadata to the `Deployment` or `StatefulSet` and the pods hosting your builders.

The value of the `nodeSelector` parameter is a comma-separated string of key-value pairs, where the key is the node label and the value is the label text. For example: `"nodeselector=kubernetes.io/arch=arm64"`

The `tolerations` parameter is a semicolon-separated list of taints. It accepts the same values as the Kubernetes manifest. Each `tolerations` entry specifies a taint key and the value, operator, or effect. For example: `"tolerations=key=foo,value=bar;key=foo2,operator=exists;key=foo3,effect=NoSchedule"`

These options accept CSV-delimited strings as values. Due to quoting rules for shell commands, you must wrap the values in single quotes. You can even wrap all of `--driver-opt` in single quotes, for example:

```console
$ docker buildx create \
  --bootstrap \
  --name=kube \
  --driver=kubernetes \
  '--driver-opt="nodeselector=label1=value1,label2=value2","tolerations=key=key1,value=value1"'
```

## [Multi-platform builds](#multi-platform-builds)

The Kubernetes driver has support for creating [multi-platform images](https://docs.docker.com/build/building/multi-platform/), either using QEMU or by leveraging the native architecture of nodes.

### [QEMU](#qemu)

Like the `docker-container` driver, the Kubernetes driver also supports using [QEMU](https://www.qemu.org/) (user mode) to build images for non-native platforms. Include the `--platform` flag and specify which platforms you want to output to.

For example, to build a Linux image for `amd64` and `arm64`:

```console
$ docker buildx build \
  --builder=kube \
  --platform=linux/amd64,linux/arm64 \
  -t <user>/<image> \
  --push .
```

> Warning
>
> QEMU performs full-CPU emulation of non-native platforms, which is much slower than native builds. Compute-heavy tasks like compilation and compression/decompression will likely take a large performance hit.

Using a custom BuildKit image or invoking non-native binaries in builds may require that you explicitly turn on QEMU using the `qemu.install` option when creating the builder:

```console
$ docker buildx create \
  --bootstrap \
  --name=kube \
  --driver=kubernetes \
  --driver-opt=namespace=buildkit,qemu.install=true
```

### [Native](#native)

If you have access to cluster nodes of different architectures, the Kubernetes driver can take advantage of these for native builds. To do this, use the `--append` flag of `docker buildx create`.

First, create your builder with explicit support for a single architecture, for example `amd64`:

```console
$ docker buildx create \
  --bootstrap \
  --name=kube \
  --driver=kubernetes \
  --platform=linux/amd64 \
  --node=builder-amd64 \
  --driver-opt=namespace=buildkit,nodeselector="kubernetes.io/arch=amd64"
```

This creates a Buildx builder named `kube`, containing a single builder node named `builder-amd64`. Assigning a node name using `--node` is optional. Buildx generates a random node name if you don't provide one.

Note that the Buildx concept of a node isn't the same as the Kubernetes concept of a node. A Buildx node in this case could connect multiple Kubernetes nodes of the same architecture together.

With the `kube` builder created, you can now introduce another architecture into the mix using `--append`. For example, to add `arm64`:

```console
$ docker buildx create \
  --append \
  --bootstrap \
  --name=kube \
  --driver=kubernetes \
  --platform=linux/arm64 \
  --node=builder-arm64 \
  --driver-opt=namespace=buildkit,nodeselector="kubernetes.io/arch=arm64"
```

Listing your builders shows both nodes for the `kube` builder:

```console
$ docker buildx ls
NAME/NODE       DRIVER/ENDPOINT                                         STATUS   PLATFORMS
kube            kubernetes
  builder-amd64 kubernetes:///kube?deployment=builder-amd64&kubeconfig= running  linux/amd64*, linux/amd64/v2, linux/amd64/v3, linux/386
  builder-arm64 kubernetes:///kube?deployment=builder-arm64&kubeconfig= running  linux/arm64*
```

You can now build multi-arch `amd64` and `arm64` images, by specifying those platforms together in your build command:

```console
$ docker buildx build --builder=kube --platform=linux/amd64,linux/arm64 -t <user>/<image> --push .
```

You can repeat the `buildx create --append` command for as many architectures that you want to support.

## [Rootless mode](#rootless-mode)

The Kubernetes driver supports rootless mode. For more information on how rootless mode works, and its requirements, refer to the [Rootless Buildkit documentation](https://github.com/moby/buildkit/blob/master/docs/rootless.md).

To turn it on in your cluster, you can use the `rootless=true` driver option:

```console
$ docker buildx create \
  --name=kube \
  --driver=kubernetes \
  --driver-opt=namespace=buildkit,rootless=true
```

This will create your pods without `securityContext.privileged`.

Requires Kubernetes version 1.19 or later. Using Ubuntu as the host kernel is recommended.

## [Example: Creating a Buildx builder in Kubernetes](#example-creating-a-buildx-builder-in-kubernetes)

This guide shows you how to:

* Create a namespace for your Buildx resources
* Create a Kubernetes builder.
* List the available builders
* Build an image using your Kubernetes builders

Prerequisites:

* You have an existing Kubernetes cluster. If you don't already have one, you can follow along by installing [minikube](https://minikube.sigs.k8s.io/docs/).
* The cluster you want to connect to is accessible via the `kubectl` command, with the `KUBECONFIG` environment variable [set appropriately](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/#set-the-kubeconfig-environment-variable) if necessary.

1. Create a `buildkit` namespace.

   Creating a separate namespace helps keep your Buildx resources separate from other resources in the cluster.

   ```console
   $ kubectl create namespace buildkit
   namespace/buildkit created
   ```

2. Create a new builder with the Kubernetes driver:

   ```console
   $ docker buildx create \
     --bootstrap \
     --name=kube \
     --driver=kubernetes \
     --driver-opt=namespace=buildkit
   ```

   > Note
   >
   > Remember to specify the namespace in driver options.

3. List available builders using `docker buildx ls`

   ```console
   $ docker buildx ls
   NAME/NODE                DRIVER/ENDPOINT STATUS  PLATFORMS
   kube                     kubernetes
     kube0-6977cdcb75-k9h9m                 running linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
   default *                docker
     default                default         running linux/amd64, linux/386
   ```

4. Inspect the running pods created by the build driver with `kubectl`.

   ```console
   $ kubectl -n buildkit get deployments
   NAME    READY   UP-TO-DATE   AVAILABLE   AGE
   kube0   1/1     1            1           32s

   $ kubectl -n buildkit get pods
   NAME                     READY   STATUS    RESTARTS   AGE
   kube0-6977cdcb75-k9h9m   1/1     Running   0          32s
   ```

   The build driver creates the necessary resources on your cluster in the specified namespace (in this case, `buildkit`), while keeping your driver configuration locally.

5. Use your new builder by including the `--builder` flag when running buildx commands. For example: :

   ```console
   # Replace <registry> with your Docker username
   # and <image> with the name of the image you want to build
   docker buildx build \
     --builder=kube \
     -t <registry>/<image> \
     --push .
   ```

That's it: you've now built an image from a Kubernetes pod, using Buildx.

## [Further reading](#further-reading)

For more information on the Kubernetes driver, see the [buildx reference](/reference/cli/docker/buildx/create/#driver).

----
url: https://docs.docker.com/reference/api/engine/version/v1.42/
----

# Docker Engine API v1.42 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.42.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.42.yaml)

# Docker Engine API (1.42)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.42.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.42) is used. For example, calling `/info` is the same as calling `/v1.42/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.42/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.                                                                                                                                                                                                                                                           |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.42/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
}
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.42/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"AppArmorProfile": "",
"Args": [
"-c",
"exit 9"
],
"Config": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"/bin/sh",
"-c",
"exit 9"
],
"Domainname": "",
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Healthcheck": {
"Test": [
"CMD-SHELL",
"exit 0"
]
},
"Hostname": "ba033ac44011",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"MacAddress": "",
"NetworkDisabled": false,
"OpenStdin": false,
"StdinOnce": false,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"StopSignal": "SIGTERM",
"StopTimeout": 10
},
"Created": "2015-01-06T15:47:31.485331387Z",
"Driver": "overlay2",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 0,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"ContainerIDFile": "",
"CpusetCpus": "",
"CpusetMems": "",
"CpuPercent": 80,
"CpuShares": 0,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"Devices": [ ],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"IpcMode": "",
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"OomKillDisable": false,
"OomScoreAdj": 500,
"NetworkMode": "bridge",
"PidMode": "",
"PortBindings": { },
"Privileged": false,
"ReadonlyRootfs": false,
"PublishAllPorts": false,
"RestartPolicy": {
"MaximumRetryCount": 2,
"Name": "on-failure"
},
"LogConfig": {
"Type": "json-file"
},
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Ulimits": [
{ }
],
"VolumeDriver": "",
"ShmSize": 67108864
},
"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
"MountLabel": "",
"Name": "/boring_euclid",
"NetworkSettings": {
"Bridge": "",
"SandboxID": "",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": 0,
"SandboxKey": "",
"EndpointID": "",
"Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"MacAddress": "",
"Networks": {
"bridge": {
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
"EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Path": "/bin/sh",
"ProcessLabel": "",
"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
"RestartCount": 1,
"State": {
"Error": "",
"ExitCode": 9,
"FinishedAt": "2015-01-06T15:47:32.080254511Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2019-12-22T10:59:05.6385933Z",
"End": "2019-12-22T10:59:05.8078452Z",
"ExitCode": 0,
"Output": ""
}
]
},
"OOMKilled": false,
"Dead": false,
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z",
"Status": "running"
},
"Mounts": [
{
"Name": "fac362...80535",
"Source": "/data",
"Destination": "/data",
"Driver": "local",
"Mode": "ro,Z",
"RW": false,
"Propagation": ""
}
]
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.42/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
],
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.42/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified
* `1`: Added
* `2`: Deleted

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.42/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.42/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.42/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"read": "2015-01-08T22:57:31.547920715Z",
"pids_stats": {
"current": 3
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"memory_stats": {
"stats": {
"total_pgmajfault": 0,
"cache": 0,
"mapped_file": 0,
"total_inactive_file": 0,
"pgpgout": 414,
"rss": 6537216,
"total_mapped_file": 0,
"writeback": 0,
"unevictable": 0,
"pgpgin": 477,
"total_unevictable": 0,
"pgmajfault": 0,
"total_rss": 6537216,
"total_rss_huge": 6291456,
"total_writeback": 0,
"total_inactive_anon": 0,
"rss_huge": 6291456,
"hierarchical_memory_limit": 67108864,
"total_pgfault": 964,
"total_active_file": 0,
"active_anon": 6537216,
"total_active_anon": 6537216,
"total_pgpgout": 414,
"total_cache": 0,
"inactive_anon": 0,
"active_file": 0,
"pgfault": 964,
"inactive_file": 0,
"total_pgpgin": 477
},
"max_usage": 6651904,
"usage": 6537216,
"failcnt": 0,
"limit": 67108864
},
"blkio_stats": { },
"cpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24472255,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100215355,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 739306590000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24350896,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100093996,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 9492140000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.42/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.42/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.42/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.42/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.42/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime.This field is omitted when empty.                         |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.42/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"string"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.42/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.42/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.42/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.42/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.42/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.42/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.42/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.42/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.42/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.42/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.42/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                       |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                       |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                           |

### Responses

/v1.42/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"VirtualSize": 172064416,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.42/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| keep-storage | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                    |
| all          | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<duration>`: duration relative to daemon's time, during which build cache was not used, in Go's duration format (e.g., '24h')
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.42/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Create an image by either pulling it from a registry or importing it.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.42/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.42/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"Container": "65974bc86f1770ae4bff79f651ebdbce166ae9aada632ee3fa9af3a264911735",
"ContainerConfig": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"DockerVersion": "20.10.7",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "web:web",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": true,
"Image": "",
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"VirtualSize": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.42/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|     |                                                                                                                                                                 |
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed. |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.42/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.42/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|         |                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------ |
| force   | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags |
| noprune | booleanDefault: falseDo not delete untagged parent images                                              |

### Responses

/v1.42/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                                                       |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                                                  |
| limit        | integerMaximum number of results to return                                                                                                                                                                                                            |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-automated=(true\|false)`
- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.42/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "wma55/u1210sshd",
"star_count": 0
},
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "jdswinbank/sshd",
"star_count": 0
},
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "vgauthier/sshd",
"star_count": 0
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.42/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.                                                                                                                                                                                                                                                           |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.42/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains one directory per image layer (named using its long ID), each containing these files:

* `VERSION`: currently `1.0` - the file format version
* `json`: detailed layer information, similar to `docker inspect layer_id`
* `layer.tar`: A tarfile containing the filesystem changes in this layer

The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories for storing attribute changes and deletions.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.42/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                          |
| ----- | ---------------------------------------- |
| names | Array of stringsImage names to filter by |

### Responses

/v1.42/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                                             |
| ----- | ----------------------------------------------------------- |
| quiet | booleanDefault: falseSuppress progress details during load. |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.42/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.42/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.42/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.42/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Namerequired   | stringThe network's name.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| CheckDuplicate | booleanCheck for networks with duplicate names. Since Network is primarily keyed based on a random ID and not on the name, and network name is strictly a user-friendly alias to the network which is uniquely identified using ID, there is no guaranteed way to check for duplicates. CheckDuplicate is there to provide a best effort checking of any networks which has the same name but it is not guaranteed to catch all name collisions. |
| Driver         | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                                                                                                                                                                                                                                 |
| Scope          | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                                                                                                                                                                                                                                        |
| Internal       | booleanRestrict external access to the network.                                                                                                                                                                                                                                                                                                                                                                                                  |
| Attachable     | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                                                                                                                                                                                                                          |
| Ingress        | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                                                                                                                                                                                                                             |
| ConfigOnly     | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services.                                                                                                                                                                                                           |
|                | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                                                                                                                                                                                                                            |
|                | object (IPAM)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| EnableIPv6     | booleanEnable IPv6 on the network.                                                                                                                                                                                                                                                                                                                                                                                                               |
|                | objectNetwork specific options to be used by the drivers.                                                                                                                                                                                                                                                                                                                                                                                        |
|                | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                           |

### Responses

/v1.42/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"CheckDuplicate": true,
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.42/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
}
}
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.42/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.42/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.42/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.42/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.42/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.42/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.42/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.42/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.42/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.42/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.42/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.42/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.42/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.42/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.42/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.42/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.42/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.42/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.42/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.42/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.42/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.42/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.42/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.42/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                  |
| ---- | ------------------------------------------------------------------------------------------------ |
| Name | stringName of the service.                                                                       |
|      | objectUser-defined key/value metadata.                                                           |
|      | object (TaskSpec)User modifiable task configuration.                                             |
|      | objectScheduling mode for the service.                                                           |
|      | objectSpecification for the update strategy of the service.                                      |
|      | objectSpecification for the rollback strategy of the service.                                    |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.     |

### Responses

/v1.42/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
}
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warning": "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.42/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.42/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                  |
| ---- | ------------------------------------------------------------------------------------------------ |
| Name | stringName of the service.                                                                       |
|      | objectUser-defined key/value metadata.                                                           |
|      | object (TaskSpec)User modifiable task configuration.                                             |
|      | objectScheduling mode for the service.                                                           |
|      | objectSpecification for the update strategy of the service.                                      |
|      | objectSpecification for the rollback strategy of the service.                                    |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.     |

### Responses

/v1.42/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
}
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warning": "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.42/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.42/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.42/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.42/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.42/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.42/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.42/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.42/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.42/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.42/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.42/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.42/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.42/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.42/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.42/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.42/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.42/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.42/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.42/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.42/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.42/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.42/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.42/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.42/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.42/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.42/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.42/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"BridgeNfIptables": true,
"BridgeNfIp6tables": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "4.9.38-moby",
"OperatingSystem": "Alpine Linux v3.5",
"OSVersion": "16.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"AllowNondistributableArtifactsCIDRs": [ ],
"AllowNondistributableArtifactsHostnames": [ ],
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "23.0.0",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"Warnings": [
"WARNING: No memory limit support"
]
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.42/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "19.03.12",
"Details": { }
}
],
"Version": "19.03.12",
"ApiVersion": "1.40",
"MinAPIVersion": "1.12",
"GitCommit": "48a66213fe",
"GoVersion": "go1.13.14",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "4.19.76-linuxkit",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.42/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.42/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.42/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|      |                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |

### Responses

/v1.42/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"VirtualSize": 1092588,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parents": [ ],
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parents": [
"ndlpt0hhvkqcdfkputsk4cq9c"
],
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.42/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 3987495
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.42/session

----
url: https://docs.docker.com/accounts/deactivate-user-account/
----

# Deactivate a Docker account

***

Table of contents

***

Learn how to deactivate an individual Docker account, including prerequisites required for deactivation.

For information on deactivating an organization, see [Deactivating an organization](https://docs.docker.com/admin/organization/deactivate-account/).

> Warning
>
> All Docker products and services that use your Docker account are inaccessible after deactivating your account.

## [Prerequisites](#prerequisites)

Before deactivating your Docker account, ensure you meet the following requirements:

* If you are an organization or company owner, you must leave your organization or company before deactivating your Docker account:

  1. Sign in to [Docker Home](https://app.docker.com/admin) and choose your organization.
  2. Select **Members** and find your username.
  3. Select the **Actions** menu and then select **Leave organization**.

* If you are the sole owner of an organization, you must assign the owner role to another member of the organization and then remove yourself from the organization, or deactivate the organization. Similarly, if you are the sole owner of a company, either add someone else as a company owner and then remove yourself, or deactivate the company.

* If you have an active Docker subscription, [downgrade it to a Docker Personal subscription](https://docs.docker.com/subscription/change/).

* Download any images and tags you want to keep. Use `docker pull -a <image>` to pull all tags, or `docker pull <image>:<tag>` to pull a specific tag.

* Unlink your [GitHub and account](https://docs.docker.com/docker-hub/repos/manage/builds/link-source/#unlink-a-github-user-account).

## [Deactivate](#deactivate)

Once you have completed all the previous steps, you can deactivate your account.

> Warning
>
> Deactivating your account is permanent and can't be undone. Make sure to back up any important data.

1. Sign in to [Docker Home](https://app.docker.com/login).
2. Select your avatar to open the drop-down menu.
3. Select **Account settings**.
4. Select **Deactivate**.
5. Select **Deactivate account**, then select again to confirm.

## [Delete personal data](#delete-personal-data)

Deactivating your account does not delete your personal data. To request personal data deletion, fill out Docker's [Privacy request form](https://preferences.docker.com/).

----
url: https://docs.docker.com/engine/extend/plugins_network/
----

# Docker network driver plugins

***

Table of contents

***

This document describes Docker Engine network driver plugins generally available in Docker Engine. To view information on plugins managed by Docker Engine, refer to [Docker Engine plugin system](https://docs.docker.com/engine/extend/).

Docker Engine network plugins enable Engine deployments to be extended to support a wide range of networking technologies, such as VXLAN, IPVLAN, MACVLAN or something completely different. Network driver plugins are supported via the LibNetwork project. Each plugin is implemented as a "remote driver" for LibNetwork, which shares plugin infrastructure with Engine. Effectively, network driver plugins are activated in the same way as other plugins, and use the same kind of protocol.

## [Network plugins and Swarm mode](#network-plugins-and-swarm-mode)

[Legacy plugins](https://docs.docker.com/engine/extend/legacy_plugins/) do not work in Swarm mode. However, plugins written using the [v2 plugin system](https://docs.docker.com/engine/extend/) do work in Swarm mode, as long as they are installed on each Swarm worker node.

## [Use network driver plugins](#use-network-driver-plugins)

The means of installing and running a network driver plugin depend on the particular plugin. So, be sure to install your plugin according to the instructions obtained from the plugin developer.

Once running however, network driver plugins are used just like the built-in network drivers: by being mentioned as a driver in network-oriented Docker commands. For example,

```console
$ docker network create --driver weave mynet
```

Some network driver plugins are listed in [plugins](https://docs.docker.com/engine/extend/legacy_plugins/)

The `mynet` network is now owned by `weave`, so subsequent commands referring to that network will be sent to the plugin,

```console
$ docker run --network=mynet busybox top
```

## [Find network plugins](#find-network-plugins)

Network plugins are written by third parties, and are published by those third parties, either on [Docker Hub](https://hub.docker.com/search?q=\&type=plugin) or on the third party's site.

## [Write a network plugin](#write-a-network-plugin)

Network plugins implement the [Docker plugin API](https://docs.docker.com/engine/extend/plugin_api/) and the network plugin protocol

## [Network plugin protocol](#network-plugin-protocol)

The network driver protocol, in addition to the plugin activation call, is documented as part of libnetwork: <https://github.com/moby/moby/blob/master/daemon/libnetwork/docs/remote.md>.

----
url: https://docs.docker.com/reference/cli/docker/scout/integration/list/
----

# docker scout integration list

***

| Description | List integrations which can be installed      |
| ----------- | --------------------------------------------- |
| Usage       | `docker scout integration list [INTEGRATION]` |

## [Description](#description)

The docker scout integration list configured integrations for an organization.

## [Options](#options)

| Option   | Default | Description                               |
| -------- | ------- | ----------------------------------------- |
| `--name` |         | Name of integration configuration to list |
| `--org`  |         | Namespace of the Docker organization      |

----
url: https://docs.docker.com/guides/rust/deploy/
----

# Test your Rust deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete the previous sections of this guide, starting with [Develop your Rust application](https://docs.docker.com/guides/rust/develop/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This lets you to test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your `docker-rust-postgres` directory, create a file named `docker-rust-kubernetes.yaml`. Open the file in an IDE or text editor and add the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the name of the repository that you created in [Configure CI/CD for your Rust application](https://docs.docker.com/guides/rust/configure-ci-cd/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    service: server
  name: server
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: server
  strategy: {}
  template:
    metadata:
      labels:
        service: server
    spec:
      initContainers:
        - name: wait-for-db
          image: busybox:1.28
          command:
            [
              "sh",
              "-c",
              'until nc -zv db 5432; do echo "waiting for db"; sleep 2; done;',
            ]
      containers:
        - image: DOCKER_USERNAME/REPO_NAME
          name: server
          imagePullPolicy: Always
          ports:
            - containerPort: 8000
              hostPort: 5000
              protocol: TCP
          env:
            - name: ADDRESS
              value: 0.0.0.0:8000
            - name: PG_DBNAME
              value: example
            - name: PG_HOST
              value: db
            - name: PG_PASSWORD
              value: mysecretpassword
            - name: PG_USER
              value: postgres
            - name: RUST_LOG
              value: debug
          resources: {}
      restartPolicy: Always
status: {}
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    service: db
  name: db
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: db
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        service: db
    spec:
      containers:
        - env:
            - name: POSTGRES_DB
              value: example
            - name: POSTGRES_PASSWORD
              value: mysecretpassword
            - name: POSTGRES_USER
              value: postgres
          image: postgres:18
          name: db
          ports:
            - containerPort: 5432
              protocol: TCP
          resources: {}
      restartPolicy: Always
status: {}
---
apiVersion: v1
kind: Service
metadata:
  labels:
    service: server
  name: server
  namespace: default
spec:
  type: NodePort
  ports:
    - name: "5000"
      port: 5000
      targetPort: 8000
      nodePort: 30001
  selector:
    service: server
status:
  loadBalancer: {}
---
apiVersion: v1
kind: Service
metadata:
  labels:
    service: db
  name: db
  namespace: default
spec:
  ports:
    - name: "5432"
      port: 5432
      targetPort: 5432
  selector:
    service: db
status:
  loadBalancer: {}
```

In this Kubernetes YAML file, there are four objects, separated by the `---`. In addition to a Service and Deployment for the database, the other two objects are:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your Rust application](https://docs.docker.com/guides/rust/configure-ci-cd/).
* A NodePort service, which will route traffic from port 30001 on your host to port 5000 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to `docker-rust-postgres` and deploy your application to Kubernetes.

   ```console
   $ kubectl apply -f docker-rust-kubernetes.yaml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```shell
   deployment.apps/server created
   deployment.apps/db created
   service/server created
   service/db created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```shell
   NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
   db       1/1     1            1           2m21s
   server   1/1     1            1           2m21s
   ```

   This indicates all of the pods you asked for in your YAML are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```shell
   NAME         TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
   db           ClusterIP   10.105.167.81    <none>        5432/TCP         109s
   kubernetes   ClusterIP   10.96.0.1        <none>        443/TCP          9d
   server       NodePort    10.101.235.213   <none>        5000:30001/TCP   109s
   ```

   In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP.

3. In a terminal, curl the service.

   ```console
   $ curl http://localhost:30001/users
   [{"id":1,"login":"root"}]
   ```

4. Run the following command to tear down your application.

   ```console
   $ kubectl delete -f docker-rust-kubernetes.yaml
   ```

----
url: https://docs.docker.com/reference/cli/docker/node/demote/
----

# docker node demote

***

| Description | Demote one or more nodes from manager in the swarm |
| ----------- | -------------------------------------------------- |
| Usage       | `docker node demote NODE [NODE...]`                |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Demotes an existing manager so that it is no longer a manager.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Examples](#examples)

```console
$ docker node demote <node name>
```

----
url: https://docs.docker.com/reference/build-checks/undefined-var/
----

# UndefinedVar

***

Table of contents

***

## [Output](#output)

```text
Usage of undefined variable '$foo'
```

## [Description](#description)

This check ensures that environment variables and build arguments are correctly declared before being used. While undeclared variables might not cause an immediate build failure, they can lead to unexpected behavior or errors later in the build process.

This check does not evaluate undefined variables for `RUN`, `CMD`, and `ENTRYPOINT` instructions where you use the [shell form](https://docs.docker.com/reference/dockerfile/#shell-form). That's because when you use shell form, variables are resolved by the command shell.

It also detects common mistakes like typos in variable names. For example, in the following Dockerfile:

```dockerfile
FROM alpine
ENV PATH=$PAHT:/app/bin
```

The check identifies that `$PAHT` is undefined and likely a typo for `$PATH`:

```text
Usage of undefined variable '$PAHT' (did you mean $PATH?)
```

## [Examples](#examples)

❌ Bad: `$foo` is an undefined build argument.

```dockerfile
FROM alpine AS base
COPY $foo .
```

✅ Good: declaring `foo` as a build argument before attempting to access it.

```dockerfile
FROM alpine AS base
ARG foo
COPY $foo .
```

❌ Bad: `$foo` is undefined.

```dockerfile
FROM alpine AS base
ARG VERSION=$foo
```

✅ Good: the base image defines `$PYTHON_VERSION`

```dockerfile
FROM python AS base
ARG VERSION=$PYTHON_VERSION
```

----
url: https://docs.docker.com/engine/release-notes/19.03/
----

# Docker Engine 19.03 release notes

***

Table of contents

***

## [19.03.15](#190315)

2021-02-01

### [Security](#security)

* [CVE-2021-21285](https://github.com/moby/moby/security/advisories/GHSA-6fj5-m822-rqx8) Prevent an invalid image from crashing docker daemon
* [CVE-2021-21284](https://github.com/moby/moby/security/advisories/GHSA-7452-xqpj-6rpc) Lock down file permissions to prevent remapped root from accessing docker state
* Ensure AppArmor and SELinux profiles are applied when building with BuildKit

### [Client](#client)

* Check contexts before importing them to reduce risk of extracted files escaping context store

## [19.03.14](#190314)

2020-12-01

### [Security](#security-1)

* [CVE-2020-15257](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-15257): Update bundled static binaries of containerd to v1.3.9 [moby/moby#41731](https://github.com/moby/moby/pull/41731). Package managers should update the containerd.io package.

### [Builder](#builder)

* Beta versions of apparmor are now parsed correctly preventing build failures [moby/moby#41542](https://github.com/moby/moby/pull/41542)

### [Networking](#networking)

* Fix panic when swarmkit service keeps failing to start [moby/moby#41635](https://github.com/moby/moby/pull/41635)

### [Runtime](#runtime)

* Return correct errors instead of spurious -EINVAL [moby/moby#41293](https://github.com/moby/moby/pull/41293)

### [Rootless](#rootless)

* Lock state dir for preventing automatic clean-up by systemd-tmpfiles [moby/moby#41635](https://github.com/moby/moby/pull/41635)
* dockerd-rootless.sh: support new containerd shim socket path convention [moby/moby#41557](https://github.com/moby/moby/pull/41557)

### [Logging](#logging)

* gcplogs: Fix memory/connection leak [moby/moby#41522](https://github.com/moby/moby/pull/41522)
* awslogs: Support for AWS imdsv2 [moby/moby#41494](https://github.com/moby/moby/pull/41494)

## [19.03.13](#190313)

2020-09-16

### [Builder](#builder-1)

* buildkit: Fix nil dereference in cache logic [moby/moby#41279](https://github.com/moby/moby/pull/41279)
* buildkit: Treat Unix sockets as regular files during COPY/ADD [moby/moby#41269](https://github.com/moby/moby/pull/41269)
* buildkit: Ignore system and security xattrs in calculation to ensure consistent COPY caching regardless of SELinux environment [moby/moby#41222](https://github.com/moby/moby/pull/41222)
* buildkit: Make `--cache-from` behavior more reliable [moby/moby#41222](https://github.com/moby/moby/pull/41222)
* buildkit: Fix infinite loop burning CPU when exporting cache [moby/moby#41185](https://github.com/moby/moby/pull/41185)

### [Client](#client-1)

* Bump Golang 1.13.15 [docker/cli#2674](https://github.com/docker/cli/pull/2674)
* Fix config file permission issues (\~/.docker/config.json) [docker/cli#2631](https://github.com/docker/cli/pull/2631)
* build: Fix panic on terminals with zero height [docker/cli#2719](https://github.com/docker/cli/pull/2719)
* windows: Fix potential issue with newline character in console [docker/cli#2623](https://github.com/docker/cli/pull/2623)

### [Networking](#networking-1)

* Clean up network sandbox on failure [moby/moby#41081](https://github.com/moby/moby/pull/41081)
* Fix shallow error messages by forwarding deadline-related errors to user [moby/moby#41312](https://github.com/moby/moby/pull/41312)
* Fix leaking of netns file descriptors [moby/moby#41287](https://github.com/moby/moby/41287)

### [Rootless](#rootless-1)

* Fix port forwarder resource leak [moby/moby#41277](https://github.com/moby/moby/pull/41277)

### [Runtime](#runtime-1)

* Bump Golang 1.13.15 [moby/moby#41334](https://github.com/moby/moby/pull/41334)
* Update to containerd 1.3.7 [moby/moby#40408](https://github.com/moby/moby/pull/40408)

### [Windows](#windows)

* Fix slow Windows container start time when using servercore image [moby/moby#41192](https://github.com/moby/moby/pull/41192)

## [19.03.12](#190312)

2020-06-18

### [Client](#client-2)

* Fix bug preventing logout from registry when using multiple config files (e.g. Windows vs WSL2 when using Docker Desktop) [docker/cli#2592](https://github.com/docker/cli/pull/2592)
* Fix regression preventing context metadata to be read [docker/cli#2586](https://github.com/docker/cli/pull/2586)
* Bump Golang 1.13.12 [docker/cli#2575](https://github.com/docker/cli/pull/2575)

### [Networking](#networking-2)

* Fix regression preventing daemon start up in a systemd-nspawn environment [moby/moby#41124](https://github.com/moby/moby/pull/41124) [moby/libnetwork#2567](https://github.com/moby/libnetwork/pull/2567)
* Fix the retry logic for creating overlay networks in swarm [moby/moby#41124](https://github.com/moby/moby/pull/41124) [moby/libnetwork#2565](https://github.com/moby/libnetwork/pull/2565)

### [Runtime](#runtime-2)

* Bump Golang 1.13.12 [moby/moby#41082](https://github.com/moby/moby/pull/41082)

## [19.03.11](#190311)

2020-06-01

### [Network](#network)

Disable IPv6 Router Advertisements to prevent address spoofing. [CVE-2020-13401](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-13401)

**Description**

In the Docker default configuration, the container network interface is a virtual ethernet link going to the host (veth interface). In this configuration, an attacker able to run a process as root in a container can send and receive arbitrary packets to the host using the `CAP_NET_RAW` capability (present in the default configuration).

If IPv6 is not totally disabled on the host (via `ipv6.disable=1` on the kernel cmdline), it will be either unconfigured or configured on some interfaces, but it’s pretty likely that ipv6 forwarding is disabled, that is, `/proc/sys/net/ipv6/conf//forwarding == 0`. Also by default, `/proc/sys/net/ipv6/conf//accept_ra == 1`. The combination of these 2 sysctls means that the host accepts router advertisements and configures the IPv6 stack using them.

By sending “rogue” router advertisements from a container, an attacker can reconfigure the host to redirect part or all of the IPv6 traffic of the host to the attacker-controlled container.

Even if there was no IPv6 traffic before, if the DNS returns A (IPv4) and AAAA (IPv6) records, many HTTP libraries will try to connect via IPv6 first then fallback to IPv4, giving an opportunity to the attacker to respond. If by chance the host has a vulnerability like last year’s RCE in apt (CVE-2019-3462), the attacker can now escalate to the host.

As `CAP_NET_ADMIN` is not present by default for Docker containers, the attacker can’t configure the IPs they want to MitM, they can’t use iptables to NAT or REDIRECT the traffic, and they can’t use `IP_TRANSPARENT`. The attacker can however still use `CAP_NET_RAW` and implement a tcp/ip stack in user space.

See [kubernetes/kubernetes#91507](https://github.com/kubernetes/kubernetes/issues/91507) for related issues.

## [19.03.10](#190310)

2020-05-29

### [Client](#client-3)

* Fix version negotiation with older engine. [docker/cli#2538](https://github.com/docker/cli/pull/2538)
* Avoid setting SSH flags through hostname. [docker/cli#2560](https://github.com/docker/cli/pull/2560)
* Fix panic when DOCKER\_CLI\_EXPERIMENTAL is invalid. [docker/cli#2558](https://github.com/docker/cli/pull/2558)
* Avoid potential panic on s390x by upgrading Go to 1.13.11. [docker/cli#2532](https://github.com/docker/cli/pull/2532)

### [Networking](#networking-3)

* Fix DNS fallback regression. [moby/moby#41009](https://github.com/moby/moby/pull/41009)

### [Runtime](#runtime-3)

* Avoid potential panic on s390x by upgrading Go to 1.13.11. [moby/moby#40978](https://github.com/moby/moby/pull/40978)

### [Packaging](#packaging)

* Fix ARM builds on ARM64. [moby/moby#41027](https://github.com/moby/moby/pull/41027)

## [19.03.9](#19039)

2020-05-14

### [Builder](#builder-2)

* buildkit: Fix concurrent map write panic when building multiple images in parallel. [moby/moby#40780](https://github.com/moby/moby/pull/40780)
* buildkit: Fix issue preventing chowning of non-root-owned files between stages with userns. [moby/moby#40955](https://github.com/moby/moby/pull/40955)
* Avoid creation of irrelevant temporary files on Windows. [moby/moby#40877](https://github.com/moby/moby/pull/40877)

### [Client](#client-4)

* Fix panic on single-character volumes. [docker/cli#2471](https://github.com/docker/cli/pull/2471)
* Lazy daemon feature detection to avoid long timeouts on simple commands. [docker/cli#2442](https://github.com/docker/cli/pull/2442)
* docker context inspect on Windows is now faster. [docker/cli#2516](https://github.com/docker/cli/pull/2516)
* Bump Golang 1.13.10. [docker/cli#2431](https://github.com/docker/cli/pull/2431)
* Bump gopkg.in/yaml.v2 to v2.2.8. [docker/cli#2470](https://github.com/docker/cli/pull/2470)

### [Logging](#logging-1)

* Avoid situation preventing container logs to rotate due to closing a closed log file. [moby/moby#40921](https://github.com/moby/moby/pull/40921)

### [Networking](#networking-4)

* Fix potential panic upon restart. [moby/moby#40809](https://github.com/moby/moby/pull/40809)
* Assign the correct network value to the default bridge Subnet field. [moby/moby#40565](https://github.com/moby/moby/pull/40565)

### [Runtime](#runtime-4)

* Fix docker crash when creating namespaces with UID in /etc/subuid and /etc/subgid. [moby/moby#40562](https://github.com/moby/moby/pull/40562)
* Improve ARM platform matching. [moby/moby#40758](https://github.com/moby/moby/pull/40758)
* overlay2: show backing filesystem. [moby/moby#40652](https://github.com/moby/moby/pull/40652)
* Update CRIU to v3.13 "Silicon Willet". [moby/moby#40850](https://github.com/moby/moby/pull/40850)
* Only show registry v2 schema1 deprecation warning upon successful fallback, as opposed to any registry error. [moby/moby#40681](https://github.com/moby/moby/pull/40681)
* Use FILE\_SHARE\_DELETE for log files on Windows. [moby/moby#40563](https://github.com/moby/moby/pull/40563)
* Bump Golang 1.13.10. [moby/moby#40803](https://github.com/moby/moby/pull/40803)

### [Rootless](#rootless-2)

* Now rootlesskit-docker-proxy returns detailed error message on exposing privileged ports. [moby/moby#40863](https://github.com/moby/moby/pull/40863)
* Supports numeric ID in /etc/subuid and /etc/subgid. [moby/moby#40951](https://github.com/moby/moby/pull/40951)

### [Security](#security-2)

* apparmor: add missing rules for userns. [moby/moby#40564](https://github.com/moby/moby/pull/40564)
* SElinux: fix ENOTSUP errors not being detected when relabeling. [moby/moby#40946](https://github.com/moby/moby/pull/40946)

### [Swarm](#swarm)

* Increase refill rate for logger to avoid hanging on service logs. [moby/moby#40628](https://github.com/moby/moby/pull/40628)
* Fix issue where single swarm manager is stuck in Down state after reboot. [moby/moby#40831](https://github.com/moby/moby/pull/40831)
* tasks.db no longer grows indefinitely. [moby/moby#40831](https://github.com/moby/moby/pull/40831)

## [19.03.8](#19038)

2020-03-10

### [Runtime](#runtime-5)

* Improve mitigation for [CVE-2019-14271](https://nvd.nist.gov/vuln/detail/CVE-2019-14271) for some nscd configuration.

## [19.03.7](#19037)

2020-03-03

### [Builder](#builder-3)

* builder-next: Fix deadlock issues in corner cases. [moby/moby#40557](https://github.com/moby/moby/pull/40557)

### [Runtime](#runtime-6)

* overlay: remove modprobe execs. [moby/moby#40462](https://github.com/moby/moby/pull/40462)
* selinux: display better error messages when setting file labels. [moby/moby#40547](https://github.com/moby/moby/pull/40547)
* Speed up initial stats collection. [moby/moby#40549](https://github.com/moby/moby/pull/40549)

- rootless: use certs.d from XDG\_CONFIG\_HOME. [moby/moby#40461](https://github.com/moby/moby/pull/40461)
- Bump Golang 1.12.17. [moby/moby#40533](https://github.com/moby/moby/pull/40533)
- Bump google.golang.org/grpc to v1.23.1. [moby/moby#40566](https://github.com/moby/moby/pull/40566)
- Update containerd binary to v1.2.13. [moby/moby#40540](https://github.com/moby/moby/pull/40540)
- Prevent showing stopped containers as running in an edge case. [moby/moby#40555](https://github.com/moby/moby/pull/40555)
- Prevent potential lock. [moby/moby#40604](https://github.com/moby/moby/pull/40604)

### [Client](#client-5)

* Bump Golang 1.12.17. [docker/cli#2342](https://github.com/docker/cli/pull/2342)
* Bump google.golang.org/grpc to v1.23.1. [docker/cli#1884](https://github.com/docker/cli/pull/1884) [docker/cli#2373](https://github.com/docker/cli/pull/2373)

## [19.03.6](#19036)

2020-02-12

### [Builder](#builder-4)

* builder-next: Allow modern sign hashes for ssh forwarding. [docker/engine#453](https://github.com/docker/engine/pull/453)
* builder-next: Clear onbuild rules after triggering. [docker/engine#453](https://github.com/docker/engine/pull/453)
* builder-next: Fix issue with directory permissions when usernamespaces is enabled. [moby/moby#40440](https://github.com/moby/moby/pull/40440)
* Bump hcsshim to fix docker build failing on Windows 1903. [docker/engine#429](https://github.com/docker/engine/pull/429)

### [Networking](#networking-5)

* Shorten controller ID in exec-root to not hit UNIX\_PATH\_MAX. [docker/engine#424](https://github.com/docker/engine/pull/424)
* Fix panic in drivers/overlay/encryption.go. [docker/engine#424](https://github.com/docker/engine/pull/424)
* Fix hwaddr set race between us and udev. [docker/engine#439](https://github.com/docker/engine/pull/439)

### [Runtime](#runtime-7)

* Bump Golang 1.12.16. [moby/moby#40433](https://github.com/moby/moby/pull/40433)
* Update containerd binary to v1.2.12. [moby/moby#40433](https://github.com/moby/moby/pull/40453)
* Update to runc v1.0.0-rc10. [moby/moby#40433](https://github.com/moby/moby/pull/40453)

- Fix possible runtime panic in Lgetxattr. [docker/engine#454](https://github.com/docker/engine/pull/454)
- rootless: fix proxying UDP packets. [docker/engine#434](https://github.com/docker/engine/pull/434)

## [19.03.5](#19035)

2019-11-14

### [Builder](#builder-5)

* builder-next: Added `entitlements` in builder config. [docker/engine#412](https://github.com/docker/engine/pull/412)
* Fix builder-next: permission errors on using build secrets or ssh forwarding with userns-remap. [docker/engine#420](https://github.com/docker/engine/pull/420)
* Fix builder-next: copying a symlink inside an already copied directory. [docker/engine#420](https://github.com/docker/engine/pull/420)

### [Packaging](#packaging-1)

* Support RHEL 8 packages

### [Runtime](#runtime-8)

* Bump Golang to 1.12.12. [docker/engine#418](https://github.com/docker/engine/pull/418)
* Update to RootlessKit to v0.7.0 to harden slirp4netns with mount namespace and seccomp. [docker/engine#397](https://github.com/docker/engine/pull/397)
* Fix to propagate GetContainer error from event processor. [docker/engine#407](https://github.com/docker/engine/pull/407)
* Fix push of OCI image. [docker/engine#405](https://github.com/docker/engine/pull/405)

## [19.03.4](#19034)

2019-10-17

### [Networking](#networking-6)

* Rollback libnetwork changes to fix `DOCKER-USER` iptables chain issue. [docker/engine#404](https://github.com/docker/engine/pull/404)

### [Known Issues](#known-issues)

#### [Existing](#existing)

* In some circumstances with large clusters, Docker information might, as part of the Swarm section, include the error `code = ResourceExhausted desc = grpc: received message larger than max (5351376 vs. 4194304)`. This does not indicate any failure or misconfiguration by the user, and requires no response.
* Orchestrator port conflict can occur when redeploying all services as new. Due to many Swarm manager requests in a short amount of time, some services are not able to receive traffic and are causing a `404` error after being deployed.
  * **Workaround:** restart all tasks via `docker service update --force`.
* [CVE-2018-15664](https://nvd.nist.gov/vuln/detail/CVE-2018-15664) symlink-exchange attack with directory traversal. Workaround until proper fix is available in upcoming patch release: `docker pause` container before doing file operations. [moby/moby#39252](https://github.com/moby/moby/pull/39252)
* `docker cp` regression due to CVE mitigation. An error is produced when the source of `docker cp` is set to `/`.

## [19.03.3](#19033)

2019-10-08

### [Security](#security-3)

* Patched `runc` in containerd. [CVE-2017-18367](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-18367)

### [Builder](#builder-6)

* Fix builder-next: resolve digest for third party registries. [docker/engine#339](https://github.com/docker/engine/pull/339)

* Fix builder-next: user namespace builds when daemon started with socket activation. [docker/engine#373](https://github.com/docker/engine/pull/373)

* Fix builder-next; session: release forwarded ssh socket connection per connection. [docker/engine#373](https://github.com/docker/engine/pull/373)

* Fix build-next: llbsolver: error on multiple cache importers. [docker/engine#373](https://github.com/docker/engine/pull/373)

### [Client](#client-6)

* Added support for Docker Template 0.1.6.

* Mitigate against YAML files that have excessive aliasing. [docker/cli#2119](https://github.com/docker/cli/pull/2119)

### [Runtime](#runtime-9)

* Bump Golang to 1.12.10. [docker/engine#387](https://github.com/docker/engine/pull/387)

* Bump containerd to 1.2.10. [docker/engine#385](https://github.com/docker/engine/pull/385)

* Distribution: modify warning logic when pulling v2 schema1 manifests. [docker/engine#368](https://github.com/docker/engine/pull/368)

* Fix `POST /images/create` returning a 500 status code when providing an incorrect platform option. [docker/engine#365](https://github.com/docker/engine/pull/365)

* Fix `POST /build` returning a 500 status code when providing an incorrect platform option. [docker/engine#365](https://github.com/docker/engine/pull/365)

* Fix panic on 32-bit ARMv7 caused by misaligned struct member. [docker/engine#363](https://github.com/docker/engine/pull/363)

* Fix to return "invalid parameter" when linking to non-existing container. [docker/engine#352](https://github.com/docker/engine/pull/352)

* Fix overlay2: busy error on mount when using kernel >= 5.2. [docker/engine#332](https://github.com/docker/engine/pull/332)

* Fix `docker rmi` stuck in certain misconfigured systems, e.g. dead NFS share. [docker/engine#335](https://github.com/docker/engine/pull/335)

* Fix handling of blocked I/O of exec'd processes. [docker/engine#296](https://github.com/docker/engine/pull/296)

* Fix jsonfile logger: follow logs stuck when `max-size` is set and `max-file=1`. [docker/engine#378](https://github.com/docker/engine/pull/378)

### [Known Issues](#known-issues-1)

#### [New](#new)

* `DOCKER-USER` iptables chain is missing: [docker/for-linux#810](https://github.com/docker/for-linux/issues/810). Users cannot perform additional container network traffic filtering on top of this iptables chain. You are not affected by this issue if you are not customizing iptable chains on top of `DOCKER-USER`.
  * **Workaround:** Insert the iptables chain after the docker daemon starts. For example:
    ```text
    iptables -N DOCKER-USER
    iptables -I FORWARD -j DOCKER-USER
    iptables -A DOCKER-USER -j RETURN
    ```

#### [Existing](#existing-1)

* In some circumstances with large clusters, docker information might, as part of the Swarm section, include the error `code = ResourceExhausted desc = grpc: received message larger than max (5351376 vs. 4194304)`. This does not indicate any failure or misconfiguration by the user, and requires no response.
* Orchestrator port conflict can occur when redeploying all services as new. Due to many swarm manager requests in a short amount of time, some services are not able to receive traffic and are causing a `404` error after being deployed.
  * **Workaround:** restart all tasks via `docker service update --force`.
* [CVE-2018-15664](https://nvd.nist.gov/vuln/detail/CVE-2018-15664) symlink-exchange attack with directory traversal. Workaround until proper fix is available in upcoming patch release: `docker pause` container before doing file operations. [moby/moby#39252](https://github.com/moby/moby/pull/39252)
* `docker cp` regression due to CVE mitigation. An error is produced when the source of `docker cp` is set to `/`.

## [19.03.2](#19032)

2019-09-03

### [Builder](#builder-7)

* Fix `COPY --from` to non-existing directory on Windows. [moby/moby#39695](https://github.com/moby/moby/pull/39695)

* Fix builder-next: metadata commands not having created time in history. [moby/moby#39456](https://github.com/moby/moby/issues/39456)

* Fix builder-next: close progress on layer export error. [moby/moby#39782](https://github.com/moby/moby/pull/39782)

* Update buildkit to 588c73e1e4. [moby/moby#39781](https://github.com/moby/moby/pull/39781)

### [Client](#client-7)

* Fix Windows absolute path detection on non-Windows [docker/cli#1990](https://github.com/docker/cli/pull/1990)

* Fix to zsh completion script for `docker login --username`.

* Fix context: produce consistent output on `context create`. [docker/cli#1985](https://github.com/docker/cli/pull/1874)

* Fix support for HTTP proxy env variable. [docker/cli#2059](https://github.com/docker/cli/pull/2059)

### [Logging](#logging-2)

* Fix for reading journald logs. [moby/moby#37819](https://github.com/moby/moby/pull/37819) [moby/moby#38859](https://github.com/moby/moby/pull/38859)

### [Networking](#networking-7)

* Prevent panic on network attached to a container with disabled networking. [moby/moby#39589](https://github.com/moby/moby/pull/39589)

### [Runtime](#runtime-10)

* Bump Golang to 1.12.8.

* Fix a potential engine panic when using XFS disk quota for containers. [moby/moby#39644](https://github.com/moby/moby/pull/39644)

### [Swarm](#swarm-1)

* Fix an issue where nodes with several tasks could not be removed. [docker/swarmkit#2867](https://github.com/docker/swarmkit/pull/2867)

### [Known issues](#known-issues-2)

* In some circumstances with large clusters, docker information might, as part of the Swarm section, include the error `code = ResourceExhausted desc = grpc: received message larger than max (5351376 vs. 4194304)`. This does not indicate any failure or misconfiguration by the user, and requires no response.

* Orchestrator port conflict can occur when redeploying all services as new. Due to many swarm manager requests in a short amount of time, some services are not able to receive traffic and are causing a `404` error after being deployed.

  * Workaround: restart all tasks via `docker service update --force`.

* Traffic cannot egress the HOST because of missing Iptables rules in the FORWARD chain The missing rules are :

  ```text
  /sbin/iptables --wait -C FORWARD -o docker_gwbridge -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
  /sbin/iptables --wait -C FORWARD -o docker0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
  ```

  * Workaround: Add these rules back using a script and cron definitions. The script must contain '-C' commands to check for the presence of a rule and '-A' commands to add rules back. Run the script on a cron in regular intervals, for example, every minutes.
  * Affected versions: 18.09.1, 19.03.0

* [CVE-2018-15664](https://nvd.nist.gov/vuln/detail/CVE-2018-15664) symlink-exchange attack with directory traversal. Workaround until proper fix is available in upcoming patch release: `docker pause` container before doing file operations. [moby/moby#39252](https://github.com/moby/moby/pull/39252)

* `docker cp` regression due to CVE mitigation. An error is produced when the source of `docker cp` is set to `/`.

## [19.03.1](#19031)

2019-07-25

### [Security](#security-4)

* Fixed loading of nsswitch based config inside chroot under Glibc. [CVE-2019-14271](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-14271)

### [Known issues](#known-issues-3)

* In some circumstances, in large clusters, docker information might, as part of the Swarm section, include the error `code = ResourceExhausted desc = grpc: received message larger than max (5351376 vs. 4194304)`. This does not indicate any failure or misconfiguration by the user, and requires no response.

* Orchestrator port conflict can occur when redeploying all services as new. Due to many swarm manager requests in a short amount of time, some services are not able to receive traffic and are causing a `404` error after being deployed.

  * Workaround: restart all tasks via `docker service update --force`.

* Traffic cannot egress the HOST because of missing Iptables rules in the FORWARD chain The missing rules are :

  ```text
  /sbin/iptables --wait -C FORWARD -o docker_gwbridge -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
  /sbin/iptables --wait -C FORWARD -o docker0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
  ```

  * Workaround: Add these rules back using a script and cron definitions. The script must contain '-C' commands to check for the presence of a rule and '-A' commands to add rules back. Run the script on a cron in regular intervals, for example, every minutes.
  * Affected versions: 18.09.1, 19.03.0

* [CVE-2018-15664](https://nvd.nist.gov/vuln/detail/CVE-2018-15664) symlink-exchange attack with directory traversal. Workaround until proper fix is available in upcoming patch release: `docker pause` container before doing file operations. [moby/moby#39252](https://github.com/moby/moby/pull/39252)

* `docker cp` regression due to CVE mitigation. An error is produced when the source of `docker cp` is set to `/`.

## [19.03.0](#19030)

2019-07-22

### [Builder](#builder-8)

* Fixed `COPY --from` to preserve ownership. [moby/moby#38599](https://github.com/moby/moby/pull/38599)

* builder-next:

  * Added inline cache support `--cache-from`. [docker/engine#215](https://github.com/docker/engine/pull/215)
  * Outputs configuration allowed. [moby/moby#38898](https://github.com/moby/moby/pull/38898)
  * Fixed gcr workaround token cache. [docker/engine#212](https://github.com/docker/engine/pull/212)
  * `stopprogress` called on download error. [docker/engine#215](https://github.com/docker/engine/pull/215)
  * Buildkit now uses systemd's `resolv.conf`. [docker/engine#260](https://github.com/docker/engine/pull/260).
  * Setting buildkit outputs now allowed. [docker/cli#1766](https://github.com/docker/cli/pull/1766)
  * Look for Dockerfile specific dockerignore file (for example, Dockerfile.dockerignore) for ignored paths. [docker/engine#215](https://github.com/docker/engine/pull/215)
  * Automatically detect if process execution is possible for x86, arm, and arm64 binaries. [docker/engine#215](https://github.com/docker/engine/pull/215)
  * Updated buildkit to 1f89ec1. [docker/engine#260](https://github.com/docker/engine/pull/260)
  * Use Dockerfile frontend version `docker/dockerfile:1.1` by default. [docker/engine#215](https://github.com/docker/engine/pull/215)
  * No longer rely on an external image for COPY/ADD operations. [docker/engine#215](https://github.com/docker/engine/pull/215)

### [Client](#client-8)

* Added `--pids-limit` flag to `docker update`. [docker/cli#1765](https://github.com/docker/cli/pull/1765)
* Added systctl support for services. [docker/cli#1754](https://github.com/docker/cli/pull/1754)
* Added support for `template_driver` in compose files. [docker/cli#1746](https://github.com/docker/cli/pull/1746)
* Added `--device` support for Windows. [docker/cli#1606](https://github.com/docker/cli/pull/1606)
* Added support for Data Path Port configuration. [docker/cli#1509](https://github.com/docker/cli/pull/1509)
* Added fast context switch: commands. [docker/cli#1501](https://github.com/docker/cli/pull/1501)
* Support added for `--mount type=bind,bind-nonrecursive,...` [docker/cli#1430](https://github.com/docker/cli/pull/1430)
* Added maximum replicas per node. [docker/cli#1612](https://github.com/docker/cli/pull/1612)
* Added option to pull images quietly. [docker/cli#882](https://github.com/docker/cli/pull/882)
* Added a separate `--domainname` flag. [docker/cli#1130](https://github.com/docker/cli/pull/1130)
* Added support for secret drivers in `docker stack deploy`. [docker/cli#1783](https://github.com/docker/cli/pull/1783)
* Added ability to use swarm `Configs` as `CredentialSpecs` on services. [docker/cli#1781](https://github.com/docker/cli/pull/1781)
* Added `--security-opt systempaths=unconfined` support. [docker/cli#1808](https://github.com/docker/cli/pull/1808)
* Added basic framework for writing and running CLI plugins. [docker/cli#1564](https://github.com/docker/cli/pull/1564) [docker/cli#1898](https://github.com/docker/cli/pull/1898)
* Bumped Docker App to v0.8.0. [docker/docker-ce-packaging#341](https://github.com/docker/docker-ce-packaging/pull/341)
* Added support for Docker buildx. [docker/docker-ce-packaging#336](https://github.com/docker/docker-ce-packaging/pull/336)
* Added support for Docker Assemble v0.36.0.
* Added support for Docker Cluster v1.0.0-rc2.
* Added support for Docker Template v0.1.4.
* Added support for Docker Registry v0.1.0-rc1.
* Bumped google.golang.org/grpc to v1.20.1. [docker/cli#1884](https://github.com/docker/cli/pull/1884)
* CLI changed to pass driver specific options to `docker run`. [docker/cli#1767](https://github.com/docker/cli/pull/1767)
* Bumped Golang 1.12.5. [docker/cli#1875](https://github.com/docker/cli/pull/1875)
* `docker system info` output now segregates information relevant to the client and daemon. [docker/cli#1638](https://github.com/docker/cli/pull/1638)
* (Experimental) When targeting Kubernetes, added support for `x-pull-secret: some-pull-secret` in compose-files service configs. [docker/cli#1617](https://github.com/docker/cli/pull/1617)
* (Experimental) When targeting Kubernetes, added support for `x-pull-policy: <Never|Always|IfNotPresent>` in compose-files service configs. [docker/cli#1617](https://github.com/docker/cli/pull/1617)
* cp, save, export: Now preventing overwriting irregular files. [docker/cli#1515](https://github.com/docker/cli/pull/1515)
* npipe volume type on stack file now allowed. [docker/cli#1195](https://github.com/docker/cli/pull/1195)
* Fixed tty initial size error. [docker/cli#1529](https://github.com/docker/cli/pull/1529)
* Fixed problem with labels copying value from environment variables. [docker/cli#1671](https://github.com/docker/cli/pull/1671)

### [API](#api)

* Updated API version to v1.40. [moby/moby#38089](https://github.com/moby/moby/pull/38089)
* Added warnings to `/info` endpoint, and moved detection to the daemon. [moby/moby#37502](https://github.com/moby/moby/pull/37502)
* Added HEAD support for `/_ping` endpoint. [moby/moby#38570](https://github.com/moby/moby/pull/38570)
* Added `Cache-Control` headers to disable caching `/_ping` endpoint. [moby/moby#38569](https://github.com/moby/moby/pull/38569)
* Added `containerd`, `runc`, and `docker-init` versions to `/version`. [moby/moby#37974](https://github.com/moby/moby/pull/37974)
* Added undocumented `/grpc` endpoint and registered BuildKit's controller. [moby/moby#38990](https://github.com/moby/moby/pull/38990)

### [Experimental](#experimental)

* Enabled checkpoint/restore of containers with TTY. [moby/moby#38405](https://github.com/moby/moby/pull/38405)
* LCOW: Added support for memory and CPU limits. [moby/moby#37296](https://github.com/moby/moby/pull/37296)
* Windows: Added ContainerD runtime. [moby/moby#38541](https://github.com/moby/moby/pull/38541)
* Windows: LCOW now requires Windows RS5+. [moby/moby#39108](https://github.com/moby/moby/pull/39108)

### [Security](#security-5)

* mount: added BindOptions.NonRecursive (API v1.40). [moby/moby#38003](https://github.com/moby/moby/pull/38003)
* seccomp: whitelisted `io_pgetevents()`. [moby/moby#38895](https://github.com/moby/moby/pull/38895)
* seccomp: `ptrace(2)` for 4.8+ kernels now allowed. [moby/moby#38137](https://github.com/moby/moby/pull/38137)

### [Runtime](#runtime-11)

* Running `dockerd` as a non-root user (Rootless mode) is now allowed. [moby/moby#380050](https://github.com/moby/moby/pull/38050)
* Rootless: optional support provided for `lxc-user-nic` SUID binary. [docker/engine#208](https://github.com/docker/engine/pull/208)
* Added DeviceRequests to HostConfig to support NVIDIA GPUs. [moby/moby#38828](https://github.com/moby/moby/pull/38828)
* Added `--device` support for Windows. [moby/moby#37638](https://github.com/moby/moby/pull/37638)
* Added `memory.kernelTCP` support for linux. [moby/moby#37043](https://github.com/moby/moby/pull/37043)
* Windows credential specs can now be passed directly to the engine. [moby/moby#38777](https://github.com/moby/moby/pull/38777)
* Added pids-limit support in docker update. [moby/moby#32519](https://github.com/moby/moby/pull/32519)
* Added support for exact list of capabilities. [moby/moby#38380](https://github.com/moby/moby/pull/38380)
* daemon: Now use 'private' ipc mode by default. [moby/moby#35621](https://github.com/moby/moby/pull/35621)
* daemon: switched to semaphore-gated WaitGroup for startup tasks. [moby/moby#38301](https://github.com/moby/moby/pull/38301)
* Now use `idtools.LookupGroup` instead of parsing `/etc/group` file for docker.sock ownership to fix: `api.go doesn't respect nsswitch.conf`. [moby/moby#38126](https://github.com/moby/moby/pull/38126)
* cli: fixed images filter when using multi reference filter. [moby/moby#38171](https://github.com/moby/moby/pull/38171)
* Bumped Golang to 1.12.5. [docker/engine#209](https://github.com/docker/engine/pull/209)
* Bumped `containerd` to 1.2.6. [moby/moby#39016](https://github.com/moby/moby/pull/39016)
* Bumped `runc` to 1.0.0-rc8, opencontainers/selinux v1.2.2. [docker/engine#210](https://github.com/docker/engine/pull/210)
* Bumped `google.golang.org/grpc` to v1.20.1. [docker/engine#215](https://github.com/docker/engine/pull/215)
* Performance optimized in aufs and layer store for massively parallel container creation/removal. [moby/moby#39135](https://github.com/moby/moby/pull/39135) [moby/moby#39209](https://github.com/moby/moby/pull/39209)
* Root is now passed to chroot for chroot Tar/Untar (CVE-2018-15664) [moby/moby#39292](https://github.com/moby/moby/pull/39292)
* Fixed `docker --init` with /dev bind mount. [moby/moby#37665](https://github.com/moby/moby/pull/37665)
* The right device number is now fetched when greater than 255 and using the `--device-read-bps` option. [moby/moby#39212](https://github.com/moby/moby/pull/39212)
* Fixed `Path does not exist` error when path definitely exists. [moby/moby#39251](https://github.com/moby/moby/pull/39251)

### [Networking](#networking-8)

* Moved IPVLAN driver out of experimental. [moby/moby#38983](https://github.com/moby/moby/pull/38983)
* Added support for 'dangling' filter. [moby/moby#31551](https://github.com/moby/moby/pull/31551) [docker/libnetwork#2230](https://github.com/docker/libnetwork/pull/2230)
* Load balancer sandbox is now deleted when a service is updated with `--network-rm`. [docker/engine#213](https://github.com/docker/engine/pull/213)
* Windows: Now forcing a nil IP specified in `PortBindings` to IPv4zero (0.0.0.0). [docker/libnetwork#2376](https://github.com/docker/libnetwork/pull/2376)

### [Swarm](#swarm-2)

* Added support for maximum replicas per node. [moby/moby#37940](https://github.com/moby/moby/pull/37940)
* Added support for GMSA CredentialSpecs from Swarmkit configs. [moby/moby#38632](https://github.com/moby/moby/pull/38632)
* Added support for sysctl options in services. [moby/moby#37701](https://github.com/moby/moby/pull/37701)
* Added support for filtering on node labels. [moby/moby#37650](https://github.com/moby/moby/pull/37650)
* Windows: Support added for named pipe mounts in docker service create + stack yml. [moby/moby#37400](https://github.com/moby/moby/pull/37400)
* VXLAN UDP Port configuration now supported. [moby/moby#38102](https://github.com/moby/moby/pull/38102)
* Now using Service Placement Constraints in Enforcer. [docker/swarmkit#2857](https://github.com/docker/swarmkit/pull/2857)
* Increased max recv gRPC message size for nodes and secrets. [docker/engine#256](https://github.com/docker/engine/pull/256)

### [Logging](#logging-3)

* Enabled gcplogs driver on Windows. [moby/moby#37717](https://github.com/moby/moby/pull/37717)
* Added zero padding for RFC5424 syslog format. [moby/moby#38335](https://github.com/moby/moby/pull/38335)
* Added `IMAGE_NAME` attribute to `journald` log events. [moby/moby#38032](https://github.com/moby/moby/pull/38032)

### [Deprecation](#deprecation)

* Deprecate image manifest v2 schema1 in favor of v2 schema2. Future version of Docker will remove support for v2 schema1 althogether. [moby/moby#39365](https://github.com/moby/moby/pull/39365)
* Removed v1.10 migrator. [moby/moby#38265](https://github.com/moby/moby/pull/38265)
* Now skipping deprecated storage-drivers in auto-selection. [moby/moby#38019](https://github.com/moby/moby/pull/38019)
* Deprecated `aufs` storage driver and added warning. [moby/moby#38090](https://github.com/moby/moby/pull/38090)
* Removed support for 17.09.

For more information on deprecated flags and APIs, refer to [deprecation information](/engine/deprecated/) for target removal dates.

### [Known issues](#known-issues-4)

* In some circumstances with large clusters, docker information might, as part of the Swarm section, include the error `code = ResourceExhausted desc = grpc: received message larger than max (5351376 vs. 4194304)`. This does not indicate any failure or misconfiguration by the user, and requires no response.

* Orchestrator port conflict can occur when redeploying all services as new. Due to many swarm manager requests in a short amount of time, some services are not able to receive traffic and are causing a `404` error after being deployed.

  * Workaround: restart all tasks via `docker service update --force`.

* Traffic cannot egress the HOST because of missing Iptables rules in the FORWARD chain The missing rules are :

  ```text
  /sbin/iptables --wait -C FORWARD -o docker_gwbridge -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
  /sbin/iptables --wait -C FORWARD -o docker0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
  ```

  * Workaround: Add these rules back using a script and cron definitions. The script must contain '-C' commands to check for the presence of a rule and '-A' commands to add rules back. Run the script on a cron in regular intervals, for example, every minutes.
  * Affected versions: 18.09.1, 19.03.0

* [CVE-2018-15664](https://nvd.nist.gov/vuln/detail/CVE-2018-15664) symlink-exchange attack with directory traversal. Workaround until proper fix is available in upcoming patch release: `docker pause` container before doing file operations. [moby/moby#39252](https://github.com/moby/moby/pull/39252)

* `docker cp` regression due to CVE mitigation. An error is produced when the source of `docker cp` is set to `/`.

----
url: https://docs.docker.com/guides/testcontainers-java-spring-boot-rest-api/write-tests/
----

# Write tests with Testcontainers

***

Table of contents

***

To test the REST API, you need a running Postgres database and a started Spring context. Testcontainers spins up Postgres in a Docker container and `@DynamicPropertySource` connects it to Spring.

## [Write the test](#write-the-test)

Create `CustomerControllerTest.java`:

```java
package com.testcontainers.demo;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.hasSize;

import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import java.util.List;
import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.server.LocalServerPort;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.postgresql.PostgreSQLContainer;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class CustomerControllerTest {

  @LocalServerPort
  private Integer port;

  static PostgreSQLContainer postgres = new PostgreSQLContainer(
    "postgres:16-alpine"
  );

  @BeforeAll
  static void beforeAll() {
    postgres.start();
  }

  @AfterAll
  static void afterAll() {
    postgres.stop();
  }

  @DynamicPropertySource
  static void configureProperties(DynamicPropertyRegistry registry) {
    registry.add("spring.datasource.url", postgres::getJdbcUrl);
    registry.add("spring.datasource.username", postgres::getUsername);
    registry.add("spring.datasource.password", postgres::getPassword);
  }

  @Autowired
  CustomerRepository customerRepository;

  @BeforeEach
  void setUp() {
    RestAssured.baseURI = "http://localhost:" + port;
    customerRepository.deleteAll();
  }

  @Test
  void shouldGetAllCustomers() {
    List<Customer> customers = List.of(
      new Customer(null, "John", "john@mail.com"),
      new Customer(null, "Dennis", "dennis@mail.com")
    );
    customerRepository.saveAll(customers);

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/customers")
      .then()
      .statusCode(200)
      .body(".", hasSize(2));
  }
}
```

Here's what the test does:

* `@SpringBootTest` starts the full application on a random port.
* A `PostgreSQLContainer` starts in `@BeforeAll` and stops in `@AfterAll`.
* `@DynamicPropertySource` registers the container's JDBC URL, username, and password with Spring so that the datasource connects to the test container.
* `@BeforeEach` deletes all customer rows before each test to prevent test pollution.
* `shouldGetAllCustomers()` inserts two customers, calls `GET /api/customers`, and verifies the response contains 2 records.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-spring-boot-rest-api/run-tests/)

----
url: https://docs.docker.com/build/exporters/oci-docker/
----

# OCI and Docker exporters

***

Table of contents

***

The `oci` exporter outputs the build result into an [OCI image layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) tarball. The `docker` exporter behaves the same way, except it exports a Docker image layout instead.

The [`docker` driver](https://docs.docker.com/build/builders/drivers/docker/) doesn't support these exporters. You must use `docker-container` or some other driver if you want to generate these outputs.

## [Synopsis](#synopsis)

Build a container image using the `oci` and `docker` exporters:

```console
$ docker buildx build --output type=oci[,parameters] .
```

```console
$ docker buildx build --output type=docker[,parameters] .
```

The following table describes the available parameters:

| Parameter           | Type                                   | Default | Description                                                                                                                                                                                                   |
| ------------------- | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | String                                 |         | Specify image name(s)                                                                                                                                                                                         |
| `dest`              | String                                 |         | Path                                                                                                                                                                                                          |
| `tar`               | `true`,`false`                         | `true`  | Bundle the output into a tarball layout                                                                                                                                                                       |
| `compression`       | `uncompressed`,`gzip`,`estargz`,`zstd` | `gzip`  | Compression type, see [compression](https://docs.docker.com/build/exporters/#compression)                                                                                                                     |
| `compression-level` | `0..22`                                |         | Compression level, see [compression](https://docs.docker.com/build/exporters/#compression)                                                                                                                    |
| `force-compression` | `true`,`false`                         | `false` | Forcefully apply compression, see [compression](https://docs.docker.com/build/exporters/#compression)                                                                                                         |
| `oci-mediatypes`    | `true`,`false`                         |         | Use OCI media types in exporter manifests. Defaults to `true` for `type=oci`, and `false` for `type=docker`. See [OCI Media types](https://docs.docker.com/build/exporters/#oci-media-types)                  |
| `annotation.<key>`  | String                                 |         | Attach an annotation with the respective `key` and `value` to the built image,see [annotations](#annotations)                                                                                                 |
| `rewrite-timestamp` | `true`,`false`                         | `false` | Rewrite the file timestamps to the `SOURCE_DATE_EPOCH` value. See [build reproducibility](https://github.com/moby/buildkit/blob/master/docs/build-repro.md) for how to specify the `SOURCE_DATE_EPOCH` value. |

## [Annotations](#annotations)

These exporters support adding OCI annotation using `annotation` parameter, followed by the annotation name using dot notation. The following example sets the `org.opencontainers.image.title` annotation:

```console
$ docker buildx build \
    --output "type=<type>,name=<registry>/<image>,annotation.org.opencontainers.image.title=<title>" .
```

For more information about annotations, see [BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/annotations.md).

## [Further reading](#further-reading)

For more information on the `oci` or `docker` exporters, see the [BuildKit README](https://github.com/moby/buildkit/blob/master/README.md#docker-tarball).

----
url: https://docs.docker.com/reference/cli/docker/mcp/gateway/run/
----

# docker mcp gateway run

***

| Description | Run the gateway          |
| ----------- | ------------------------ |
| Usage       | `docker mcp gateway run` |

## [Description](#description)

Run the gateway

## [Options](#options)

| Option                      | Default          | Description                                                                                                                                    |
| --------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--additional-catalog`      |                  | Additional catalog paths to append to the default catalogs                                                                                     |
| `--additional-config`       |                  | Additional config paths to merge with the default config.yaml                                                                                  |
| `--additional-registry`     |                  | Additional registry paths to merge with the default registry.yaml                                                                              |
| `--additional-tools-config` |                  | Additional tools paths to merge with the default tools.yaml                                                                                    |
| `--block-network`           |                  | Block tools from accessing forbidden network resources                                                                                         |
| `--block-secrets`           | `true`           | Block secrets from being/received sent to/from tools                                                                                           |
| `--catalog`                 |                  | Paths to docker catalogs (absolute or relative to \~/.docker/mcp/catalogs/)                                                                    |
| `--config`                  |                  | Paths to the config files (absolute or relative to \~/.docker/mcp/)                                                                            |
| `--cpus`                    | `1`              | CPUs allocated to each MCP Server (default is 1)                                                                                               |
| `--debug-dns`               |                  | Debug DNS resolution                                                                                                                           |
| `--dry-run`                 |                  | Start the gateway but do not listen for connections (useful for testing the configuration)                                                     |
| `--enable-all-servers`      |                  | Enable all servers in the catalog (instead of using individual --servers options)                                                              |
| `--interceptor`             |                  | List of interceptors to use (format: when:type:path, e.g. 'before:exec:/bin/path')                                                             |
| `--log-calls`               | `true`           | Log calls to the tools                                                                                                                         |
| `--long-lived`              |                  | Containers are long-lived and will not be removed until the gateway is stopped, useful for stateful servers                                    |
| `--mcp-registry`            |                  | MCP registry URLs to fetch servers from (can be repeated)                                                                                      |
| `--memory`                  | `2Gb`            | Memory allocated to each MCP Server (default is 2Gb)                                                                                           |
| `--oci-ref`                 |                  | OCI image references to use                                                                                                                    |
| `--port`                    |                  | TCP port to listen on (default is to listen on stdio)                                                                                          |
| `--profile`                 |                  | Profile ID to use (mutually exclusive with --servers and --enable-all-servers)                                                                 |
| `--registry`                |                  | Paths to the registry files (absolute or relative to \~/.docker/mcp/)                                                                          |
| `--secrets`                 | `docker-desktop` | Colon separated paths to search for secrets. Can be `docker-desktop` or a path to a .env file (default to using Docker Desktop's secrets API)  |
| `--servers`                 |                  | Names of the servers to enable (if non empty, ignore --registry flag)                                                                          |
| `--static`                  |                  | Enable static mode (aka pre-started servers)                                                                                                   |
| `--tools`                   |                  | List of tools to enable                                                                                                                        |
| `--tools-config`            |                  | Paths to the tools files (absolute or relative to \~/.docker/mcp/)                                                                             |
| `--transport`               | `stdio`          | stdio, sse or streaming. Uses MCP\_GATEWAY\_AUTH\_TOKEN environment variable for localhost authentication to prevent dns rebinding attacks.    |
| `--verbose`                 |                  | Verbose output                                                                                                                                 |
| `--verify-signatures`       |                  | Verify signatures of the server images                                                                                                         |
| `--watch`                   | `true`           | Watch for changes and reconfigure the gateway                                                                                                  |

----
url: https://docs.docker.com/guides/r/
----

# R language-specific guide

***

This guide details how to containerize R applications using Docker.

**Time to complete** 10 minutes

The R language-specific guide teaches you how to containerize a R application using Docker. In this guide, you’ll learn how to:

* Containerize and run a R application
* Set up a local environment to develop a R application using containers
* Configure a CI/CD pipeline for a containerized R application using GitHub Actions
* Deploy your containerized R application locally to Kubernetes to test and debug your deployment

Start by containerizing an existing R application.

## [Modules](#modules)

1. [Containerize your app](https://docs.docker.com/guides/r/containerize/)

   Learn how to containerize a R application.

2. [Develop your app](https://docs.docker.com/guides/r/develop/)

   Learn how to develop your R application locally.

3. [Configure CI/CD](https://docs.docker.com/guides/r/configure-ci-cd/)

   Learn how to configure CI/CD using GitHub Actions for your R application.

4. [Test your deployment](https://docs.docker.com/guides/r/deploy/)

   Learn how to develop locally using Kubernetes

----
url: https://docs.docker.com/reference/compose-file/volumes/
----

# Define and manage volumes in Docker Compose

***

Table of contents

***

Volumes are persistent data stores implemented by the container engine. Compose offers a neutral way for services to mount volumes, and configuration parameters to allocate them to infrastructure. The top-level `volumes` declaration lets you configure named volumes that can be reused across multiple services.

To use a volume across multiple services, you must explicitly grant each service access by using the [volumes](https://docs.docker.com/reference/compose-file/services/#volumes) attribute within the `services` top-level element. The `volumes` attribute has additional syntax that provides more granular control.

> Tip
>
> Working with large repositories or monorepos, or with virtual file systems that are no longer scaling with your codebase? Compose now takes advantage of [Synchronized file shares](https://docs.docker.com/desktop/features/synchronized-file-sharing/) and automatically creates file shares for bind mounts. Ensure you're signed in to Docker with a paid subscription and have enabled both **Access experimental features** and **Manage Synchronized file shares with Compose** in Docker Desktop's settings.

## [Example](#example)

The following example shows a two-service setup where a database's data directory is shared with another service as a volume, named `db-data`, so that it can be periodically backed up.

```yml
services:
  backend:
    image: example/database
    volumes:
      - db-data:/etc/data

  backup:
    image: backup-service
    volumes:
      - db-data:/var/lib/backup/data

volumes:
  db-data:
```

The `db-data` volume is mounted at the `/var/lib/backup/data` and `/etc/data` container paths for backup and backend respectively.

Running `docker compose up` creates the volume if it doesn't already exist. Otherwise, the existing volume is used and is recreated if it's manually deleted outside of Compose.

## [Attributes](#attributes)

An entry under the top-level `volumes` section can be empty, in which case it uses the container engine's default configuration for creating a volume. Optionally, you can configure it with the following keys:

### [`driver`](#driver)

Specifies which volume driver should be used. If the driver is not available, Compose returns an error and doesn't deploy the application.

```yml
volumes:
  db-data:
    driver: foobar
```

### [`driver_opts`](#driver_opts)

`driver_opts` specifies a list of options as key-value pairs to pass to the driver for this volume. The options are driver-dependent.

```yml
volumes:
  example:
    driver_opts:
      type: "nfs"
      o: "addr=10.40.0.199,nolock,soft,rw"
      device: ":/docker/example"
```

If you want a named bind mount, use the `local` driver with `driver_opts`. This pattern gives a Compose volume a stable name while mapping it to a specific host path:

```yaml
volumes:
  app-data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /srv/app-data # must be the absolute host path and already exist
```

The `type`, `o`, and `device` keys are passed through to the local driver. For a one-off host-path mount on a single service, see [bind mounts](https://docs.docker.com/engine/storage/bind-mounts/).

### [`external`](#external)

If set to `true`:

* `external` specifies that this volume already exists on the platform and its lifecycle is managed outside of that of the application. Compose then doesn't create the volume and returns an error if the volume doesn't exist.
* All other attributes apart from `name` are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid.

In the following example, instead of attempting to create a volume called `{project_name}_db-data`, Compose looks for an existing volume simply called `db-data` and mounts it into the `backend` service's containers.

```yml
services:
  backend:
    image: example/database
    volumes:
      - db-data:/etc/data

volumes:
  db-data:
    external: true
```

### [`labels`](#labels)

`labels` are used to add metadata to volumes. You can use either an array or a dictionary.

It's recommended that you use reverse-DNS notation to prevent your labels from conflicting with those used by other software.

```yml
volumes:
  db-data:
    labels:
      com.example.description: "Database volume"
      com.example.department: "IT/Ops"
      com.example.label-with-empty-value: ""
```

```yml
volumes:
  db-data:
    labels:
      - "com.example.description=Database volume"
      - "com.example.department=IT/Ops"
      - "com.example.label-with-empty-value"
```

Compose sets `com.docker.compose.project` and `com.docker.compose.volume` labels.

> Note
>
> Labels defined here apply to named volumes only. They’re stored on the volume resource and visible via `docker volume inspect`. They do not apply to bind mounts and do not change mount semantics.

### [`name`](#name)

`name` sets a custom name for a volume. The name field can be used to reference volumes that contain special characters. The name is used as is and is not scoped with the stack name.

```yml
volumes:
  db-data:
    name: "my-app-data"
```

This makes it possible to make this lookup name a parameter of the Compose file, so that the model ID for the volume is hard-coded but the actual volume ID on the platform is set at runtime during deployment.

For example, if `DATABASE_VOLUME=my_volume_001` is in your `.env` file:

```yml
volumes:
  db-data:
    name: ${DATABASE_VOLUME}
```

Running `docker compose up` uses the volume called `my_volume_001`.

It can also be used in conjunction with the `external` property. This means the name used to look up the actual volume on the platform is set separately from the name used to refer to the volume within the Compose file:

```yml
volumes:
  db-data:
    external: true
    name: actual-name-of-volume
```

----
url: https://docs.docker.com/enterprise/security/single-sign-on/
----

# Single sign-on overview

***

Table of contents

***

Subscription: Business

For: Administrators

Single sign-on (SSO) lets users access Docker by authenticating through their identity providers (IdPs). SSO can be configured for an entire company, including all associated organizations, or for a single organization that has a Docker Business subscription.

## [How SSO works](#how-sso-works)

When SSO is enabled, Docker supports a non-IdP-initiated flow for user sign-in. Instead of signing in with a Docker username and password, users are redirected to your IdP’s sign-in page. Users must initiate the SSO authentication process by signing in to Docker Hub or Docker Desktop.

The following diagram illustrates how SSO operates and is managed between Docker Hub, Docker Desktop, and your IdP.

## [Set up SSO](#set-up-sso)

To configure SSO in Docker, follow these steps:

1. [Configure your domain](https://docs.docker.com/enterprise/security/single-sign-on/connect/) by creating and verifying it.
2. [Create your SSO connection](https://docs.docker.com/enterprise/security/single-sign-on/connect/) in Docker and your IdP.
3. Link Docker to your identity provider.
4. Test your SSO connection.
5. Provision users in Docker.
6. Optional. [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).
7. [Manage your SSO configuration](https://docs.docker.com/enterprise/security/single-sign-on/manage/).

Once configuration is complete, users can sign in to Docker services using their company email address. After signing in, users are added to your company, assigned to an organization, and added to a team.

> Important
>
> Docker plans to deprecate CLI password-based sign-in in future releases. Using a PAT ensures continued CLI access. For more information, see the [security announcement](https://docs.docker.com/security/security-announcements/#deprecation-of-password-logins-on-cli-when-sso-enforced).

## [Next steps](#next-steps)

* Start [configuring SSO](https://docs.docker.com/enterprise/security/single-sign-on/connect/).
* Read the [FAQs](https://docs.docker.com/enterprise/security/single-sign-on/faqs/general/).
* [Troubleshoot](https://docs.docker.com/enterprise/security/single-sign-on/troubleshoot-sso/) SSO issues.

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/profiles/
----

# MCP Profiles

***

Table of contents

***

Availability: Early Access

Requires: Docker Desktop 4.63 and later

Profiles organize your MCP servers into named collections. Without profiles, you'd configure servers separately for every AI application you use. Each time you want to change which servers are available, you'd update Claude Desktop, VS Code, Cursor, and other tools individually. Profiles solve this by centralizing your server configurations.

## [What profiles do](#what-profiles-do)

A profile is a named collection of MCP servers with their configurations and settings. You select servers from the [MCP Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/) (the source of available servers) and add them to your profiles (your configured server collections for specific work). Think of the catalog as a library of tools, and profiles as your toolboxes organized for different jobs.

Your "web-dev" profile might include GitHub, Playwright, and database servers. Your "data-analysis" profile might include spreadsheet, API, and visualization servers. Connect different AI clients to different profiles, or switch between profiles as you change tasks.

When you run the MCP Gateway or connect a client without specifying a profile, Docker MCP uses your default profile. If you're upgrading from a previous version of MCP Toolkit, your existing server configurations are already in the default profile.

## [Profile capabilities](#profile-capabilities)

Each profile maintains its own isolated collection of servers and configurations. Your "web-dev" profile might include GitHub, Playwright, and database servers, while your "data-analysis" profile includes spreadsheet, API, and visualization servers. Create as many profiles as you need, each containing only the servers relevant to that context.

You can connect different AI applications to different profiles. When you connect a client, you specify which profile it should use. This means Claude Desktop and VS Code can have access to different server collections if needed.

Profiles can be shared with your team. Push a profile to your registry, and team members can pull it to get the exact same server collection and configuration you use.

## [Creating and managing profiles](#creating-and-managing-profiles)

### [Create a profile](#create-a-profile)

1. In Docker Desktop, select **MCP Toolkit** and select the **Profiles** tab.
2. Select **Create profile**.
3. Enter a name for your profile (e.g., "web-dev").
4. Optionally, search and add servers to your profile now, or add them later.
5. Optionally, search and add clients to connect to your profile.
6. Select **Create**.

Your new profile appears in the profiles list.

### [View profile details](#view-profile-details)

Select a profile in the **Profiles** tab to view its details. The profile view has two tabs:

* **Overview**: Shows the servers in your profile, secrets configuration, and connected clients. Use the **+** buttons to add more servers or clients.
* **Tools**: Lists all available tools from your profile's servers. You can enable or disable individual tools.

### [Remove a profile](#remove-a-profile)

1. In the **Profiles** tab, find the profile you want to remove.
2. Select ⋮ next to the profile name, and then **Delete**.
3. Confirm the removal.

> Caution
>
> Removing a profile deletes all its server configurations and settings, and updates the client configuration (removes MCP Toolkit). This action can't be undone.

### [Default profile](#default-profile)

When you run the MCP Gateway or use MCP Toolkit without specifying a profile, Docker MCP uses a profile named `default`, or an empty configuration if a `default` profile does not exist.

If you're upgrading from a previous version of MCP Toolkit, your existing server configurations automatically migrate to the `default` profile. You don't need to manually recreate your setup - everything continues to work as before.

You can always specify a different profile using the `--profile` flag with the gateway command:

```console
$ docker mcp gateway run --profile web-dev
```

## [Adding servers to profiles](#adding-servers-to-profiles)

Profiles contain the MCP servers you select from the catalog. Add servers to organize your tools for specific workflows.

### [Add a server](#add-a-server)

You can add servers to a profile in two ways.

From the Catalog tab:

1. Select the **Catalog** tab.
2. Select the checkbox next to servers you want to add to see which profile to add them to.
3. Choose your profile from the drop-down.

From within a profile:

1. Select the **Profiles** tab and select your profile.
2. In the **Servers** section, select the **+** button.
3. Search for and select servers to add.

If a server requires OAuth authentication, you're prompted to authorize it. See [OAuth authentication](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/#oauth-authentication) for details.

### [List servers in a profile](#list-servers-in-a-profile)

Select a profile in the **Profiles** tab to see all servers it contains.

### [Remove a server](#remove-a-server)

1. Select the **Profiles** tab and select your profile.
2. In the **Servers** section, find the server you want to remove.
3. Select the delete icon next to the server.

## [Configuring profiles](#configuring-profiles)

### [Server configuration](#server-configuration)

Some servers require configuration beyond authentication. Configure server settings within your profile.

1. Select the **Profiles** tab and select your profile.
2. In the **Servers** section, select the configure icon next to the server.
3. Adjust the server's configuration settings as needed.

### [OAuth credentials](#oauth-credentials)

OAuth credentials are shared across all profiles. When you authorize access to a service like GitHub or Notion, that authorization is available to any server in any profile that needs it.

This means all profiles use the same OAuth credentials for a given service. If you need to use different accounts for different projects, you'll need to revoke and re-authorize between switching profiles.

See [OAuth authentication](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/#oauth-authentication) for details on authorizing servers.

### [Configuration persistence](#configuration-persistence)

Profile configurations persist in your Docker installation. When you restart Docker Desktop or your system, your profiles, servers, and configurations remain intact.

## [Sharing profiles](#sharing-profiles)

Profiles can be shared with your team by pushing them to OCI-compliant registries as artifacts. This is useful for distributing standardized MCP setups across your organization. Credentials are not included in shared profiles for security reasons. Team members configure OAuth separately after pulling.

### [Push a profile](#push-a-profile)

1. Select the profile you want to share in the **Profiles** tab.
2. Select **Push to Registry**.
3. Enter the registry destination (e.g., `registry.example.com/profiles/web-dev:v1`).
4. Complete authentication if required.

### [Pull a profile](#pull-a-profile)

1. Select **Pull from Registry** in the **Profiles** tab.
2. Enter the registry reference (e.g., `registry.example.com/profiles/team-standard:latest`).
3. Complete authentication if required.

The profile is downloaded and added to your profiles list. Configure any required OAuth credentials separately.

### [Team collaboration workflow](#team-collaboration-workflow)

A typical workflow for sharing profiles across a team:

1. Create and configure a profile with the servers your team needs.
2. Test the profile to ensure it works as expected.
3. Push the profile to your team's registry with a version tag (e.g., `registry.example.com/profiles/team-dev:v1`).
4. Share the registry reference with your team.
5. Team members pull the profile and configure any required OAuth credentials.

This ensures everyone uses the same server collection and configuration, reducing setup time and inconsistencies.

## [Using profiles with clients](#using-profiles-with-clients)

When you connect an AI client to the MCP Gateway, you specify which profile's servers the client can access.

### [Run the gateway with a profile](#run-the-gateway-with-a-profile)

Connect clients to your profile through the **Clients** section in the MCP Toolkit. You can add clients when creating a profile or add them to existing profiles later.

### [Configure clients for specific profiles](#configure-clients-for-specific-profiles)

When setting up a client manually, you can specify which profile the client uses. This lets different clients connect to different profiles.

For example, your Claude Desktop configuration might use:

```json
{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "claude-work"]
    }
  }
}
```

While your VS Code configuration uses a different profile:

```json
{
  "mcp": {
    "servers": {
      "MCP_DOCKER": {
        "command": "docker",
        "args": ["mcp", "gateway", "run", "--profile", "vscode-dev"],
        "type": "stdio"
      }
    }
  }
}
```

### [Switching between profiles](#switching-between-profiles)

To switch the profile your clients use, update the client configuration to specify a different `--profile` value in the gateway command arguments.

## [Further reading](#further-reading)

* [Get started with MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/get-started/)
* [Use MCP Toolkit from the CLI](https://docs.docker.com/ai/mcp-catalog-and-toolkit/cli/)
* [MCP Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/)
* [MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/)

----
url: https://docs.docker.com/scout/policy/
----

# Get started with Policy Evaluation in Docker Scout

***

Table of contents

***

In software supply chain management, maintaining the security and reliability of artifacts is a top priority. Policy Evaluation in Docker Scout introduces a layer of control, on top of existing analysis capabilities. It lets you define supply chain rules for your artifacts, and helps you track how your artifacts perform, relative to your rules and thresholds, over time.

Learn how you can use Policy Evaluation to ensure that your artifacts align with established best practices.

## [How Policy Evaluation works](#how-policy-evaluation-works)

When you activate Docker Scout for a repository, images that you push are [automatically analyzed](https://docs.docker.com/scout/explore/analysis/). The analysis gives you insights about the composition of your images, including what packages they contain and what vulnerabilities they're exposed to. Policy Evaluation builds on top of the image analysis feature, interpreting the analysis results against the rules defined by policies.

A policy defines image quality criteria that your artifacts should fulfill. For example, the **No AGPL v3 licenses** policy flags any image containing packages distributed under the AGPL v3 license. If an image contains such a package, that image is non-compliant with this policy. Some policies, such as the **No AGPL v3 licenses** policy, are configurable. Configurable policies let you adjust the criteria to better match your organization's needs.

In Docker Scout, policies are designed to help you ratchet forward your security and supply chain stature. Where other tools focus on providing a pass or fail status, Docker Scout policies visualizes how small, incremental changes affect policy status, even when your artifacts don't meet the policy requirements (yet). By tracking how the fail gap changes over time, you more easily see whether your artifact is improving or deteriorating relative to policy.

Policies don't necessarily have to be related to application security and vulnerabilities. You can use policies to measure and track other aspects of supply chain management as well, such as open-source license usage and base image up-to-dateness.

## [Policy types](#policy-types)

In Docker Scout, a *policy* is derived from a *policy type*. Policy types are templates that define the core parameters of a policy. You can compare policy types to classes in object-oriented programming, with each policy acting as an instance created from its corresponding policy type.

Docker Scout supports the following policy types:

* [Severity-Based Vulnerability](#severity-based-vulnerability)
* [Compliant Licenses](#compliant-licenses)
* [Up-to-Date Base Images](#up-to-date-base-images)
* [High-Profile Vulnerabilities](#high-profile-vulnerabilities)
* [Supply Chain Attestations](#supply-chain-attestations)
* [Default Non-Root User](#default-non-root-user)
* [Approved Base Images](#approved-base-images)
* [SonarQube Quality Gates](#sonarqube-quality-gates)
* [Valid Docker Hardened Image (DHI) or DHI base image](#valid-docker-hardened-image-dhi-or-dhi-base-image)

Docker Scout automatically provides default policies for repositories where it is enabled, except for the following policies, which are optional and must be configured:

* The **SonarQube Quality Gates** policy, which requires [integration with SonarQube](https://docs.docker.com/scout/integrations/code-quality/sonarqube/) before use.
* The **Valid Docker Hardened Image (DHI) or DHI base image** policy, which can be configured if you want to enforce the use of Docker Hardened Images.

You can create custom policies from any of the supported policy types, or delete a default policy if it isn't applicable to your project. For more information, refer to [Configure policies](https://docs.docker.com/scout/policy/configure/).

### [Severity-Based Vulnerability](#severity-based-vulnerability)

The **Severity-Based Vulnerability** policy type checks whether your artifacts are exposed to known vulnerabilities.

By default, this policy only flags critical and high severity vulnerabilities where there's a fix version available. Essentially, this means that there's an easy fix that you can deploy for images that fail this policy: upgrade the vulnerable package to a version containing a fix for the vulnerability.

Images are deemed non-compliant with this policy if they contain one or more vulnerabilities that fall outside the specified policy criteria.

You can configure the parameters of this policy by creating a custom version of the policy. The following policy parameters are configurable in a custom version:

* **Age**: The minimum number of days since the vulnerability was first published

  The rationale for only flagging vulnerabilities of a certain minimum age is that newly discovered vulnerabilities shouldn't cause your evaluations to fail until you've had a chance to address them.

- **Severities**: Severity levels to consider (default: `Critical, High`)

* **Fixable vulnerabilities only**: Whether or not to only report vulnerabilities with a fix version available (enabled by default).

* **Package types**: List of package types to consider.

  This option lets you specify the package types, as [PURL package type definitions](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst), that you want to include in the policy evaluation. By default, the policy considers all package types.

For more information about configuring policies, see [Configure policies](https://docs.docker.com/scout/policy/configure/).

### [Compliant Licenses](#compliant-licenses)

The **Compliant Licenses** policy type checks whether your images contain packages distributed under an inappropriate license. Images are considered non-compliant if they contain one or more packages with such a license.

You can configure the list of licenses that this policy should look out for, and add exceptions by specifying an allow-list (in the form of PURLs). See [Configure policies](https://docs.docker.com/scout/policy/configure/).

### [Up-to-Date Base Images](#up-to-date-base-images)

The **Up-to-Date Base Images** policy type checks whether the base images you use are up-to-date.

Images are considered non-compliant with this policy if the tag you used to build your image points to a different digest than what you're using. If there's a mismatch in digests, that means the base image you're using is out of date.

Your images need provenance attestations for this policy to successfully evaluate. For more information, see [No base image data](#no-base-image-data).

### [High-Profile Vulnerabilities](#high-profile-vulnerabilities)

The **High-Profile Vulnerabilities** policy type checks whether your images contain vulnerabilities from Docker Scout’s curated list. This list is kept up-to-date with newly disclosed vulnerabilities that are widely recognized to be risky.

The list includes the following vulnerabilities:

* [CVE-2014-0160 (OpenSSL Heartbleed)](https://scout.docker.com/v/CVE-2014-0160)
* [CVE-2021-44228 (Log4Shell)](https://scout.docker.com/v/CVE-2021-44228)
* [CVE-2023-38545 (cURL SOCKS5 heap buffer overflow)](https://scout.docker.com/v/CVE-2023-38545)
* [CVE-2023-44487 (HTTP/2 Rapid Reset)](https://scout.docker.com/v/CVE-2023-44487)
* [CVE-2024-3094 (XZ backdoor)](https://scout.docker.com/v/CVE-2024-3094)
* [CVE-2024-47176 (OpenPrinting - `cups-browsed`)](https://scout.docker.com/v/CVE-2024-47176)
* [CVE-2024-47076 (OpenPrinting - `libcupsfilters`)](https://scout.docker.com/v/CVE-2024-47076)
* [CVE-2024-47175 (OpenPrinting - `libppd`)](https://scout.docker.com/v/CVE-2024-47175)
* [CVE-2024-47177 (OpenPrinting - `cups-filters`)](https://scout.docker.com/v/CVE-2024-47177)

You can customize this policy to change which CVEs that are considered high-profile by configuring the policy. Custom configuration options include:

* **Excluded CVEs**: Specify the CVEs that you want this policy to ignore.

  Default: `[]` (none of the high-profile CVEs are ignored)

* **CISA KEV**: Enable tracking of vulnerabilities from CISA's Known Exploited Vulnerabilities (KEV) catalog

  The [CISA KEV catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) includes vulnerabilities that are actively exploited in the wild. When enabled, the policy flags images that contain vulnerabilities from the CISA KEV catalog.

  Enabled by default.

For more information on policy configuration, see [Configure policies](https://docs.docker.com/scout/policy/configure/).

### [Supply Chain Attestations](#supply-chain-attestations)

The **Supply Chain Attestations** policy type checks whether your images have [SBOM](https://docs.docker.com/build/metadata/attestations/sbom/) and [provenance](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) attestations.

Images are considered non-compliant if they lack either an SBOM attestation or a provenance attestation with *max mode* provenance. To ensure compliance, update your build command to attach these attestations at build-time:

```console
$ docker buildx build --provenance=true --sbom=true -t IMAGE --push .
```

For more information about building with attestations, see [Attestations](https://docs.docker.com/build/metadata/attestations/).

If you're using GitHub Actions to build and push your images, learn how you can [configure the action](https://docs.docker.com/build/ci/github-actions/attestations/) to apply SBOM and provenance attestations.

### [Default Non-Root User](#default-non-root-user)

By default, containers run as the `root` superuser with full system administration privileges inside the container, unless the Dockerfile specifies a different default user. Running containers as a privileged user weakens their runtime security, as it means any code that runs in the container can perform administrative actions.

The **Default Non-Root User** policy type detects images that are set to run as the default `root` user. To comply with this policy, images must specify a non-root user in the image configuration. Images are non-compliant with this policy if they don't specify a non-root default user for the runtime stage.

For non-compliant images, evaluation results show whether or not the `root` user was set explicitly for the image. This helps you distinguish between policy violations caused by images where the `root` user is implicit, and images where `root` is set on purpose.

The following Dockerfile runs as `root` by default despite not being explicitly set:

```Dockerfile
FROM alpine
RUN echo "Hi"
```

Whereas in the following case, the `root` user is explicitly set:

```Dockerfile
FROM alpine
USER root
RUN echo "Hi"
```

> Note
>
> This policy only checks for the default user of the image, as set in the image configuration blob. Even if you do specify a non-root default user, it's still possible to override the default user at runtime, for example by using the `--user` flag for the `docker run` command.

To make your images compliant with this policy, use the [`USER`](https://docs.docker.com/reference/dockerfile/#user) Dockerfile instruction to set a default user that doesn't have root privileges for the runtime stage.

The following Dockerfile snippets shows the difference between a compliant and non-compliant image.

```dockerfile
FROM alpine AS builder
COPY Makefile ./src /
RUN make build

FROM alpine AS runtime
COPY --from=builder bin/production /app
ENTRYPOINT ["/app/production"]
```

```dockerfile
FROM alpine AS builder
COPY Makefile ./src /
RUN make build

FROM alpine AS runtime
COPY --from=builder bin/production /app
USER nonroot
ENTRYPOINT ["/app/production"]
```

### [Approved Base Images](#approved-base-images)

The **Approved Base Images** policy type ensures that the base images you use in your builds are maintained and secure.

This policy checks whether the base images used in your builds match any of the patterns specified in the policy configuration. The following table shows a few example patterns for this policy.

| Use case                                                        | Pattern                          |
| --------------------------------------------------------------- | -------------------------------- |
| Allow all images from Docker Hub                                | `docker.io/*`                    |
| Allow all Docker Official Images                                | `docker.io/library/*`            |
| Allow images from a specific organization                       | `docker.io/orgname/*`            |
| Allow tags of a specific repository                             | `docker.io/orgname/repository:*` |
| Allow images on a registry with hostname `registry.example.com` | `registry.example.com/*`         |
| Allow slim tags of NodeJS images                                | `docker.io/library/node:*-slim`  |

An asterisk (`*`) matches up until the character that follows, or until the end of the image reference. Note that the `docker.io` prefix is required in order to match Docker Hub images. This is the registry hostname of Docker Hub.

This policy is configurable with the following options:

* **Approved base image sources**

  Specify the image reference patterns that you want to allow. The policy evaluates the base image references against these patterns.

  Default: `[*]` (any reference is an allowed base image)

* **Only supported tags**

  Allow only supported tags when using Docker Official Images.

  When this option is enabled, images using unsupported tags of official images as their base image trigger a policy violation. Supported tags for official images are listed in the **Supported tags** section of the repository overview on Docker Hub.

  Enabled by default.

* **Only supported OS distributions**

  Allow only Docker Official Images of supported Linux distribution versions.

  When this option is enabled, images using unsupported Linux distributions that have reached end of life (such as `ubuntu:18.04`) trigger a policy violation.

  Enabling this option may cause the policy to report no data if the operating system version cannot be determined.

  Enabled by default.

Your images need provenance attestations for this policy to successfully evaluate. For more information, see [No base image data](#no-base-image-data).

### [SonarQube Quality Gates](#sonarqube-quality-gates)

The **SonarQube Quality Gates** policy type builds on the [SonarQube integration](https://docs.docker.com/scout/integrations/code-quality/sonarqube/) to assess the quality of your source code. This policy works by ingesting the SonarQube code analysis results into Docker Scout.

You define the criteria for this policy using SonarQube's [quality gates](https://docs.sonarsource.com/sonarqube/latest/user-guide/quality-gates/). SonarQube evaluates your source code against the quality gates you've defined in SonarQube. Docker Scout surfaces the SonarQube assessment as a Docker Scout policy.

Docker Scout uses [provenance](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) attestations or the `org.opencontainers.image.revision` OCI annotation to link SonarQube analysis results with container images. In addition to enabling the SonarQube integration, you must also make sure that your images have either the attestation or the label.

Once you push an image and policy evaluation completes, the results from the SonarQube quality gates display as a policy in the Docker Scout Dashboard, and in the CLI.

> Note
>
> Docker Scout can only access SonarQube analyses created after the integration is enabled. Docker Scout doesn't have access to historic evaluations. Trigger a SonarQube analysis and policy evaluation after enabling the integration to view the results in Docker Scout.

### [Valid Docker Hardened Image (DHI) or DHI base image](#valid-docker-hardened-image-dhi-or-dhi-base-image)

The **Valid Docker Hardened Image (DHI) or DHI base image** policy type ensures that your images are either Docker Hardened Images (DHI) or are built using a DHI as the base image.

This policy validates images by checking for a valid Docker signed verification summary attestation. The policy considers an image compliant if either:

* The image itself is a Docker Hardened Image with a valid Docker signed verification summary attestation, or
* The base image used in the build (identified from SLSA provenance attestations) has a valid Docker signed verification summary attestation

Images are non-compliant with this policy if they lack the required Docker signed verification summary attestation and are not built from a base image with such an attestation.

This policy has no configurable parameters.

## [No base image data](#no-base-image-data)

There are cases when it's not possible to determine information about the base images used in your builds. In such cases, the **Up-to-Date Base Images** and **Approved Base Images** policies get flagged as having **No data**.

This "no data" state occurs when:

* Docker Scout doesn't know what base image tag you used
* The base image version you used has multiple tags, but not all tags are out of date

To make sure that Docker Scout always knows about your base image, you can attach [provenance attestations](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) at build-time. Docker Scout uses provenance attestations to find out the base image version.

----
url: https://docs.docker.com/reference/cli/docker/trust/sign/
----

# docker trust sign

***

| Description | Sign an image                 |
| ----------- | ----------------------------- |
| Usage       | `docker trust sign IMAGE:TAG` |

## [Description](#description)

`docker trust sign` adds signatures to tags to create signed repositories.

## [Options](#options)

| Option    | Default | Description                 |
| --------- | ------- | --------------------------- |
| `--local` |         | Sign a locally tagged image |

## [Examples](#examples)

### [Sign a tag as a repository admin](#sign-a-tag-as-a-repository-admin)

Given an image:

```console
$ docker trust inspect --pretty example/trust-demo

SIGNED TAG          DIGEST                                                             SIGNERS
v1                  c24134c079c35e698060beabe110bb83ab285d0d978de7d92fed2c8c83570a41   (Repo Admin)

Administrative keys for example/trust-demo:
Repository Key: 36d4c3601102fa7c5712a343c03b94469e5835fb27c191b529c06fd19c14a942
Root Key:       246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b
```

Sign a new tag with `docker trust sign`:

```console
$ docker trust sign example/trust-demo:v2

Signing and pushing trust metadata for example/trust-demo:v2
The push refers to a repository [docker.io/example/trust-demo]
eed4e566104a: Layer already exists
77edfb6d1e3c: Layer already exists
c69f806905c2: Layer already exists
582f327616f1: Layer already exists
a3fbb648f0bd: Layer already exists
5eac2de68a97: Layer already exists
8d4d1ab5ff74: Layer already exists
v2: digest: sha256:8f6f460abf0436922df7eb06d28b3cdf733d2cac1a185456c26debbff0839c56 size: 1787
Signing and pushing trust metadata
Enter passphrase for repository key with ID 36d4c36:
Successfully signed docker.io/example/trust-demo:v2
```

Use `docker trust inspect --pretty` to list the new signature:

```console
$ docker trust inspect --pretty example/trust-demo

SIGNED TAG          DIGEST                                                             SIGNERS
v1                  c24134c079c35e698060beabe110bb83ab285d0d978de7d92fed2c8c83570a41   (Repo Admin)
v2                  8f6f460abf0436922df7eb06d28b3cdf733d2cac1a185456c26debbff0839c56   (Repo Admin)

Administrative keys for example/trust-demo:
Repository Key: 36d4c3601102fa7c5712a343c03b94469e5835fb27c191b529c06fd19c14a942
Root Key:       246d360f7c53a9021ee7d4259e3c5692f3f1f7ad4737b1ea8c7b8da741ad980b
```

### [Sign a tag as a signer](#sign-a-tag-as-a-signer)

Given an image:

```console
$ docker trust inspect --pretty example/trust-demo

No signatures for example/trust-demo


List of signers and their keys for example/trust-demo:

SIGNER              KEYS
alice               05e87edcaecb
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

Sign a new tag with `docker trust sign`:

```console
$ docker trust sign example/trust-demo:v1

Signing and pushing trust metadata for example/trust-demo:v1
The push refers to a repository [docker.io/example/trust-demo]
26b126eb8632: Layer already exists
220d34b5f6c9: Layer already exists
8a5132998025: Layer already exists
aca233ed29c3: Layer already exists
e5d2f035d7a4: Layer already exists
v1: digest: sha256:74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4 size: 1357
Signing and pushing trust metadata
Enter passphrase for delegation key with ID 27d42a8:
Successfully signed docker.io/example/trust-demo:v1
```

`docker trust inspect --pretty` lists the new signature:

```console
$ docker trust inspect --pretty example/trust-demo

SIGNED TAG          DIGEST                                                             SIGNERS
v1                  74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4   alice

List of signers and their keys for example/trust-demo:

SIGNER              KEYS
alice               05e87edcaecb
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

----
url: https://docs.docker.com/reference/build-checks/expose-proto-casing/
----

# ExposeProtoCasing

***

Table of contents

***

## [Output](#output)

```text
Defined protocol '80/TcP' in EXPOSE instruction should be lowercase
```

## [Description](#description)

Protocol names in the [`EXPOSE`](https://docs.docker.com/reference/dockerfile/#expose) instruction should be specified in lowercase to maintain consistency and readability. This rule checks for protocols that are not in lowercase and reports them.

## [Examples](#examples)

❌ Bad: protocol is not in lowercase.

```dockerfile
FROM alpine
EXPOSE 80/TcP
```

✅ Good: protocol is in lowercase.

```dockerfile
FROM alpine
EXPOSE 80/tcp
```

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/server/remove/
----

# docker mcp profile server remove

***

| Description                                                               | Remove MCP servers from a profile                                                 |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Usage                                                                     | `docker mcp profile server remove <profile-id> --name <name1> --name <name2> ...` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker mcp profile server rm`                                                    |

## [Description](#description)

Remove MCP servers from a profile by server name.

## [Options](#options)

| Option   | Default | Description                                             |
| -------- | ------- | ------------------------------------------------------- |
| `--name` |         | Server name to remove (can be specified multiple times) |

## [Examples](#examples)

# [Remove servers by name](#remove-servers-by-name)

docker mcp profile server remove dev-tools --name github --name slack

# [Remove a single server](#remove-a-single-server)

docker mcp profile server remove dev-tools --name github

----
url: https://docs.docker.com/reference/api/extensions-sdk/RawExecResult/
----

# Interface: RawExecResult

***

Table of contents

***

**`Since`**

0.2.0

## [Hierarchy](#hierarchy)

* **`RawExecResult`**

  ↳ [`ExecResult`](https://docs.docker.com/reference/api/extensions-sdk/ExecResult/)

## [Properties](#properties)

### [cmd](#cmd)

• `Optional` `Readonly` **cmd**: `string`

***

### [killed](#killed)

• `Optional` `Readonly` **killed**: `boolean`

***

### [signal](#signal)

• `Optional` `Readonly` **signal**: `string`

***

### [code](#code)

• `Optional` `Readonly` **code**: `number`

***

### [stdout](#stdout)

• `Readonly` **stdout**: `string`

***

### [stderr](#stderr)

• `Readonly` **stderr**: `string`

----
url: https://docs.docker.com/reference/samples/typescript/
----

# TypeScript samples

| Name                                                                                    | Description                                                                    |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [Angular](https://github.com/docker/awesome-compose/tree/master/angular)                | A sample Angular application.                                                  |
| [dotnet-album-viewer](https://github.com/dockersamples/dotnet-album-viewer)             | West Wind Album Viewer ASP.NET Core and Angular sample.                        |
| [link-shortener-typescript](https://github.com/dockersamples/link-shortener-typescript) | A Simple URL Shortener built using TypeScript and Nest.js powered with Docker. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/enterprise/enterprise-deployment/ms-store/
----

# Install Docker Desktop from the Microsoft Store on Windows

***

Table of contents

***

You can deploy Docker Desktop for Windows through the [Microsoft app store](https://apps.microsoft.com/detail/xp8cbj40xlbwkx?hl=en-GB\&gl=GB).

The Microsoft Store version of Docker Desktop provides the same functionality as the standard installer but has a different update behavior depending on whether your developers install it themselves or if installation is handled by an MDM tool such as Intune. This is described in the following section.

Choose the installation method that best aligns with your environment's requirements and management practices.

## [Update behavior](#update-behavior)

### [Developer-managed installations](#developer-managed-installations)

For developers who install Docker Desktop directly:

* The Microsoft Store does not automatically update Win32 apps like Docker Desktop for most users.
* Only a subset of users (approximately 20%) may receive update notifications on the Microsoft Store page.
* Most users must manually check for and apply updates within the Store.

### [Intune-managed installations](#intune-managed-installations)

In environments managed with Intune:

* Intune checks for updates approximately every 8 hours.
* When a new version is detected, Intune triggers a `winget` upgrade.
* If appropriate policies are configured, updates can occur automatically without user intervention.
* Updates are handled by Intune's management infrastructure rather than the Microsoft Store itself.

## [WSL considerations](#wsl-considerations)

Docker Desktop for Windows integrates closely with WSL. When updating Docker Desktop installed from the Microsoft Store:

* Make sure you have quit Docker Desktop and that it is no longer running so updates can complete successfully
* In some environments, virtual hard disk (VHDX) file locks may prevent the update from completing.

## [Recommendations for Intune management](#recommendations-for-intune-management)

If using Intune to manage Docker Desktop for Windows:

* Ensure your Intune policies are configured to handle application updates
* Be aware that the update process uses WinGet APIs rather than direct Store mechanisms
* Consider testing the update process in a controlled environment to verify proper functionality

----
url: https://docs.docker.com/dhi/how-to/policies/
----

# Enforce Docker Hardened Image usage with policies

***

Table of contents

***

When you have a Docker Hardened Images Enterprise subscription, mirroring a Docker Hardened Image (DHI) repository automatically enables [Docker Scout](/scout/), allowing you to start enforcing security and compliance policies for your images without additional setup. Using Docker Scout policies, you can define and apply rules that ensure only approved and secure images, such as those based on DHIs, are used across your environments.

Docker Scout includes a dedicated [**Valid Docker Hardened Image (DHI) or DHI base image**](https://docs.docker.com/scout/policy/#valid-docker-hardened-image-dhi-or-dhi-base-image) policy type that validates whether your images are Docker Hardened Images or are built using a DHI as the base image. This policy checks for valid Docker signed verification summary attestations.

With policy evaluation built into Docker Scout, you can monitor image compliance in real time, integrate checks into your CI/CD workflows, and maintain consistent standards for image security and provenance.

## [View existing policies](#view-existing-policies)

To see the current policies applied to a mirrored DHI repository:

1. Go to the mirrored DHI repository in [Docker Hub](https://hub.docker.com).

2. Select **View on Scout**.

   This opens the [Docker Scout dashboard](https://scout.docker.com), where you can see which policies are currently active and whether your images meet the policy criteria.

Docker Scout automatically evaluates policy compliance when new images are pushed. Each policy includes a compliance result and a link to the affected images and layers.

## [Evaluate DHI policy compliance for your images](#evaluate-dhi-policy-compliance-for-your-images)

When you enable Docker Scout for your repositories, you can configure the [**Valid Docker Hardened Image (DHI) or DHI base image**](https://docs.docker.com/scout/policy/#valid-docker-hardened-image-dhi-or-dhi-base-image) policy. This optional policy validates whether your images are DHIs or built with DHI base images by checking for Docker signed verification summary attestations.

The following example shows how to build an image using a DHI base image and evaluate its compliance with the DHI policy.

### [Example: Build and evaluate a DHI-based image](#example-build-and-evaluate-a-dhi-based-image)

#### [Step 1: Use a DHI base image in your Dockerfile](#step-1-use-a-dhi-base-image-in-your-dockerfile)

Create a Dockerfile that uses a Docker Hardened Image mirrored repository as the base. For example:

```dockerfile
# Dockerfile
FROM <your-namespace>/dhi-python:3.13-alpine3.21

ENTRYPOINT ["python", "-c", "print('Hello from a DHI-based image')"]
```

#### [Step 2: Build and push the image](#step-2-build-and-push-the-image)

Open a terminal and navigate to the directory containing your Dockerfile. Then, build and push the image to your Docker Hub repository:

```console
$ docker build \
  --push \
  -t <your-namespace>/my-dhi-app:v1 .
```

#### [Step 3: Enable Docker Scout](#step-3-enable-docker-scout)

To enable Docker Scout for your organization and the repository, run the following commands in your terminal:

```console
$ docker login
$ docker scout enroll <your-namespace>
$ docker scout repo enable --org <your-namespace> <your-namespace>/my-dhi-app
```

#### [Step 4: Configure the DHI policy](#step-4-configure-the-dhi-policy)

Once Docker Scout is enabled, you can configure the **Valid Docker Hardened Image (DHI) or DHI base image** policy for your organization:

1. Go to the [Docker Scout dashboard](https://scout.docker.com).
2. Select your organization and navigate to **Policies**.
3. Configure the **Valid Docker Hardened Image (DHI) or DHI base image** policy to enable it for your repositories.

For more information on configuring policies, see [Configure policies](https://docs.docker.com/scout/policy/configure/).

#### [Step 5: View policy compliance](#step-5-view-policy-compliance)

Once the DHI policy is configured and active, you can view compliance results:

1. Go to the [Docker Scout dashboard](https://scout.docker.com).
2. Select your organization and navigate to **Images**.
3. Find your image, `<your-namespace>/my-dhi-app:v1`, and select the link in the **Compliance** column.

This shows the policy compliance results for your image. The **Valid Docker Hardened Image (DHI) or DHI base image** policy evaluates whether your image has a valid Docker signed verification summary attestation or if its base image has such an attestation.

You can now [evaluate policy compliance in your CI](/scout/policy/ci/).

----
url: https://docs.docker.com/engine/extend/legacy_plugins/
----

# Use Docker Engine plugins

***

Table of contents

***

This document describes the Docker Engine plugins generally available in Docker Engine. To view information on plugins managed by Docker, refer to [Docker Engine plugin system](https://docs.docker.com/engine/extend/).

> Note
>
> Legacy plugins are superseded by Docker Engine's managed plugin system. For plugins installed and managed by Docker, use [`docker plugin install`](https://docs.docker.com/reference/cli/docker/plugin/install/) and the [Docker Engine plugin system](https://docs.docker.com/engine/extend/). The third-party plugins listed on this page are provided for historical reference, and archived projects are marked accordingly.

You can extend the capabilities of the Docker Engine by loading third-party plugins. This page explains the types of plugins and provides links to several volume and network plugins for Docker.

## [Types of plugins](#types-of-plugins)

Plugins extend Docker's functionality. They come in specific types. For example, a [volume plugin](https://docs.docker.com/engine/extend/plugins_volume/) might enable Docker volumes to persist across multiple Docker hosts and a [network plugin](https://docs.docker.com/engine/extend/plugins_network/) might provide network plumbing.

Currently Docker supports authorization, volume and network driver plugins. In the future it will support additional plugin types.

## [Installing a plugin](#installing-a-plugin)

Follow the instructions in the plugin's documentation.

## [Finding a plugin](#finding-a-plugin)

The sections below provide an overview of third-party plugins that use the legacy plugin model.

### [Network plugins](#network-plugins)

| Plugin                                                                      | Description                                                                                                                                                                                                                                                                                              |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Contiv Networking](https://github.com/contiv/netplugin)                    | An open source network plugin to provide infrastructure and security policies for a multi-tenant micro services deployment, while providing an integration to physical network for non-container workload. Contiv Networking implements the remote driver and IPAM APIs available in Docker 1.9 onwards. |
| [Kuryr Network Plugin](https://github.com/openstack/kuryr)                  | A network plugin is developed as part of the OpenStack Kuryr project and implements the Docker networking (libnetwork) remote driver API by utilizing Neutron, the OpenStack networking service. It includes an IPAM driver as well.                                                                     |
| [Kathará Network Plugin](https://github.com/KatharaFramework/NetworkPlugin) | Docker Network Plugin used by Kathará, an open source container-based network emulation system for showing interactive demos/lessons, testing production networks in a sandbox environment, or developing new network protocols.                                                                         |

### [Volume plugins](#volume-plugins)

| Plugin                                                                                                     | Description                                                                                                                                                                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Azure File Storage plugin](https://github.com/Azure/azurefile-dockervolumedriver) (archived)              | Lets you mount Microsoft [Azure File Storage](https://azure.microsoft.com/blog/azure-file-storage-now-generally-available/) shares to Docker containers as volumes using the SMB 3.0 protocol. [Learn more](https://azure.microsoft.com/blog/persistent-docker-volumes-with-azure-file-storage/).             |
| [BeeGFS Volume Plugin](https://github.com/RedCoolBeans/docker-volume-beegfs)                               | An open source volume plugin to create persistent volumes in a BeeGFS parallel file system.                                                                                                                                                                                                                   |
| [Blockbridge plugin](https://github.com/blockbridge/blockbridge-docker-volume)                             | A volume plugin that provides access to an extensible set of container-based persistent storage options. It supports single and multi-host Docker environments with features that include tenant isolation, automated provisioning, encryption, secure deletion, snapshots and QoS.                           |
| [Contiv Volume Plugin](https://github.com/contiv/volplugin)                                                | An open source volume plugin that provides multi-tenant, persistent, distributed storage with intent based consumption. It has support for Ceph and NFS.                                                                                                                                                      |
| [Convoy plugin](https://github.com/rancher/convoy) (archived)                                              | A volume plugin for a variety of storage back-ends including device mapper and NFS. It's a simple standalone executable written in Go and provides the framework to support vendor-specific extensions such as snapshots, backups and restore.                                                                |
| [DigitalOcean Block Storage plugin](https://github.com/omallo/docker-volume-plugin-dostorage)              | Integrates DigitalOcean's [block storage solution](https://www.digitalocean.com/products/storage/) into the Docker ecosystem by automatically attaching a given block storage volume to a DigitalOcean droplet and making the contents of the volume available to Docker containers running on that droplet.  |
| [DRBD plugin](https://www.drbd.org/en/supported-projects/docker)                                           | A volume plugin that provides highly available storage replicated by [DRBD](https://www.drbd.org). Data written to the docker volume is replicated in a cluster of DRBD nodes.                                                                                                                                |
| [Flocker plugin](https://github.com/ScatterHQ/flocker) (archived)                                          | A volume plugin that provides multi-host portable volumes for Docker, enabling you to run databases and other stateful containers and move them around across a cluster of machines.                                                                                                                          |
| [Fuxi Volume Plugin](https://github.com/openstack-archive/fuxi) (archived)                                 | A volume plugin that is developed as part of the OpenStack Kuryr project and implements the Docker volume plugin API by utilizing Cinder, the OpenStack block storage service.                                                                                                                                |
| [gce-docker plugin](https://github.com/mcuadros/gce-docker) (archived)                                     | A volume plugin able to attach, format and mount Google Compute [persistent-disks](https://cloud.google.com/compute/docs/disks/persistent-disks).                                                                                                                                                             |
| [GlusterFS plugin](https://github.com/calavera/docker-volume-glusterfs) (archived)                         | A volume plugin that provides multi-host volumes management for Docker using GlusterFS.                                                                                                                                                                                                                       |
| [Horcrux Volume Plugin](https://github.com/muthu-r/horcrux)                                                | A volume plugin that allows on-demand, version controlled access to your data. Horcrux is an open-source plugin, written in Go, and supports SCP, [Minio](https://www.minio.io) and Amazon S3.                                                                                                                |
| [HPE 3Par Volume Plugin](https://github.com/hpe-storage/python-hpedockerplugin/)                           | A volume plugin that supports HPE 3Par and StoreVirtual iSCSI storage arrays.                                                                                                                                                                                                                                 |
| [IPFS Volume Plugin](https://github.com/vdemeester/docker-volume-ipfs) (archived)                          | An open source volume plugin that allows using an [ipfs](https://ipfs.io/) filesystem as a volume.                                                                                                                                                                                                            |
| [Keywhiz plugin](https://github.com/calavera/docker-volume-keywhiz) (archived)                             | A plugin that provides credentials and secret management using Keywhiz as a central repository.                                                                                                                                                                                                               |
| [Linode Volume Plugin](https://github.com/linode/docker-volume-linode)                                     | A plugin that adds the ability to manage Linode Block Storage as Docker Volumes from within a Linode.                                                                                                                                                                                                         |
| [Local Persist Plugin](https://github.com/CWSpear/local-persist)                                           | A volume plugin that extends the default `local` driver's functionality by allowing you specify a mountpoint anywhere on the host, which enables the files to *always persist*, even if the volume is removed via `docker volume rm`.                                                                         |
| [NetApp Plugin](https://github.com/NetApp/netappdvp) (nDVP)                                                | A volume plugin that provides direct integration with the Docker ecosystem for the NetApp storage portfolio. The nDVP package supports the provisioning and management of storage resources from the storage platform to Docker hosts, with a robust framework for adding additional platforms in the future. |
| [Netshare plugin](https://github.com/ContainX/docker-volume-netshare)                                      | A volume plugin that provides volume management for NFS 3/4, AWS EFS and CIFS file systems.                                                                                                                                                                                                                   |
| [Nimble Storage Volume Plugin](https://scod.hpedev.io/docker_volume_plugins/hpe_nimble_storage/index.html) | A volume plug-in that integrates with Nimble Storage Unified Flash Fabric arrays. The plug-in abstracts array volume capabilities to the Docker administrator to allow self-provisioning of secure multi-tenant volumes and clones.                                                                           |
| [OpenStorage Plugin](https://github.com/libopenstorage/openstorage)                                        | A cluster-aware volume plugin that provides volume management for file and block storage solutions. It implements a vendor neutral specification for implementing extensions such as CoS, encryption, and snapshots. It has example drivers based on FUSE, NFS, NBD and EBS to name a few.                    |
| [Portworx Volume Plugin](https://github.com/portworx/px-dev)                                               | A volume plugin that turns any server into a scale-out converged compute/storage node, providing container granular storage and highly available volumes across any node, using a shared-nothing storage backend that works with any docker scheduler.                                                        |
| [Quobyte Volume Plugin](https://github.com/quobyte/docker-volume)                                          | A volume plugin that connects Docker to [Quobyte](https://www.quobyte.com/containers)'s data center file system, a general-purpose scalable and fault-tolerant storage platform.                                                                                                                              |
| [REX-Ray plugin](https://github.com/emccode/rexray)                                                        | A volume plugin which is written in Go and provides advanced storage functionality for many platforms including VirtualBox, EC2, Google Compute Engine, OpenStack, and EMC.                                                                                                                                   |
| [Virtuozzo Storage and Ploop plugin](https://github.com/virtuozzo/docker-volume-ploop)                     | A volume plugin with support for Virtuozzo Storage distributed cloud file system as well as ploop devices.                                                                                                                                                                                                    |
| [VMware vSphere Storage Plugin](https://github.com/vmware/docker-volume-vsphere)                           | Docker Volume Driver for vSphere enables customers to address persistent storage requirements for Docker containers in vSphere environments.                                                                                                                                                                  |

### [Authorization plugins](#authorization-plugins)

| Plugin                                                               | Description                                                                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Casbin AuthZ Plugin](https://github.com/casbin/casbin-authz-plugin) | An authorization plugin based on [Casbin](https://github.com/casbin/casbin), which supports access control models like ACL, RBAC, ABAC. The access control model can be customized. The policy can be persisted into file or DB.                                                                                                     |
| [HBM plugin](https://github.com/kassisol/hbm)                        | An authorization plugin that prevents from executing commands with certains parameters.                                                                                                                                                                                                                                              |
| [Twistlock AuthZ Broker](https://github.com/twistlock/authz)         | A basic extendable authorization plugin that runs directly on the host or inside a container. This plugin allows you to define user policies that it evaluates during authorization. Basic authorization is provided if Docker daemon is started with the --tlsverify flag (username is extracted from the certificate common name). |

## [Troubleshooting a plugin](#troubleshooting-a-plugin)

If you are having problems with Docker after loading a plugin, ask the authors of the plugin for help. The Docker team may not be able to assist you.

## [Writing a plugin](#writing-a-plugin)

If you are interested in writing a plugin for Docker, or seeing how they work under the hood, see the [Docker plugins reference](https://docs.docker.com/engine/extend/plugin_api/).

----
url: https://docs.docker.com/reference/cli/docker/model/unload/
----

# docker model unload

***

| Description                                                               | Unload running models                                                  |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Usage                                                                     | `docker model unload (MODEL [MODEL ...] [--backend BACKEND] \| --all)` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker model stop`                                                    |

## [Description](#description)

Unload running models

## [Options](#options)

| Option      | Default | Description                |
| ----------- | ------- | -------------------------- |
| `--all`     |         | Unload all running models  |
| `--backend` |         | Optional backend to target |

----
url: https://docs.docker.com/get-started/introduction/build-and-push-first-image/
----

# Build and push your first image

***

Table of contents

***

## [Explanation](#explanation)

Now that you've updated the [to-do list app](https://docs.docker.com/get-started/introduction/develop-with-containers/), you’re ready to create a container image for the application and share it on Docker Hub. To do so, you will need to do the following:

1. Sign in with your Docker account
2. Create an image repository on Docker Hub
3. Build the container image
4. Push the image to Docker Hub

Before you dive into the hands-on guide, the following are a few core concepts that you should be aware of.

### [Container images](#container-images)

If you’re new to container images, think of them as a standardized package that contains everything needed to run an application, including its files, configuration, and dependencies. These packages can then be distributed and shared with others.

### [Docker Hub](#docker-hub)

To share your Docker images, you need a place to store them. This is where registries come in. While there are many registries, Docker Hub is the default and go-to registry for images. Docker Hub provides both a place for you to store your own images and to find images from others to either run or use as the bases for your own images.

When choosing base images, Docker Hub offers two categories of trusted, Docker-maintained images:

* [Docker Official Images (DOI)](https://docs.docker.com/docker-hub/image-library/trusted-content/#docker-official-images) – Curated images for popular software, following best practices and regularly updated.
* [Docker Hardened Images (DHI)](https://docs.docker.com/dhi/) – Minimal, secure, production-ready images with near-zero CVEs, designed to reduce attack surface and simplify compliance. DHI images are free and open source under Apache 2.0.

In [Develop with containers](https://docs.docker.com/get-started/introduction/develop-with-containers/), you used the following images that came from Docker Hub, each of which are [Docker Official Images](https://docs.docker.com/docker-hub/image-library/trusted-content/#docker-official-images):

* [node](https://hub.docker.com/_/node) - provides a Node environment and is used as the base of your development efforts. This image is also used as the base for the final application image.
* [mysql](https://hub.docker.com/_/mysql) - provides a MySQL database to store the to-do list items
* [phpmyadmin](https://hub.docker.com/_/phpmyadmin) - provides phpMyAdmin, a web-based interface to the MySQL database
* [traefik](https://hub.docker.com/_/traefik) - provides Traefik, a modern HTTP reverse proxy and load balancer that routes requests to the appropriate container based on routing rules

Explore the full catalog of trusted content on Docker Hub:

* [Docker Official Images](https://hub.docker.com/search?badges=official) – Curated images for popular software
* [Docker Hardened Images](https://hub.docker.com/hardened-images/catalog) – Security-hardened, minimal production images (also available at [dhi.io](https://dhi.io))
* [Docker Verified Publishers](https://hub.docker.com/search?badges=verified_publisher) – Images from verified software vendors
* [Docker Sponsored Open Source](https://hub.docker.com/search?badges=open_source) – Images from sponsored OSS projects

## [Try it out](#try-it-out)

In this hands-on guide, you'll learn how to sign in to Docker Hub and push images to Docker Hub repository.

## [Sign in with your Docker account](#sign-in-with-your-docker-account)

To push images to Docker Hub, you will need to sign in with a Docker account.

1. Open the Docker Dashboard.

2. Select **Sign in** at the top-right corner.

3. If needed, create an account and then complete the sign-in flow.

Once you're done, you should see the **Sign in** button turn into a profile picture.

## [Create an image repository](#create-an-image-repository)

Now that you have an account, you can create an image repository. Just as a Git repository holds source code, an image repository stores container images.

1. Go to [Docker Hub](https://hub.docker.com).

2. Select **Create repository**.

3. On the **Create repository** page, enter the following information:

   * **Repository name** - `getting-started-todo-app`
   * **Short description** - feel free to enter a description if you'd like
   * **Visibility** - select **Public** to allow others to pull your customized to-do app

4. Select **Create** to create the repository.

## [Build and push the image](#build-and-push-the-image)

Now that you have a repository, you are ready to build and push your image. An important note is that the image you are building extends the Node image, meaning you don't need to install or configure Node, yarn, etc. You can simply focus on what makes your application unique.

> **What is an image/Dockerfile?**
>
> Without going too deep yet, think of a container image as a single package that contains everything needed to run a process. In this case, it will contain a Node environment, the backend code, and the compiled React code.
>
> Any machine that runs a container using the image, will then be able to run the application as it was built without needing anything else pre-installed on the machine.
>
> A `Dockerfile` is a text-based script that provides the instruction set on how to build the image. For this quick start, the repository already contains the Dockerfile.

1. To get started, either clone or [download the project as a ZIP file](https://github.com/docker/getting-started-todo-app/archive/refs/heads/main.zip) to your local machine.

   ```console
   $ git clone https://github.com/docker/getting-started-todo-app
   ```

   And after the project is cloned, navigate into the new directory created by the clone:

   ```console
   $ cd getting-started-todo-app
   ```

2. Build the project by running the following command, swapping out `DOCKER_USERNAME` with your username.

   ```console
   $ docker build -t DOCKER_USERNAME/getting-started-todo-app .
   ```

   For example, if your Docker username was `mobydock`, you would run the following:

   ```console
   $ docker build -t mobydock/getting-started-todo-app .
   ```

3. To verify the image exists locally, you can use the `docker image ls` command:

   ```console
   $ docker image ls
   ```

   You will see output similar to the following:

   ```console
   REPOSITORY                          TAG       IMAGE ID       CREATED          SIZE
   mobydock/getting-started-todo-app   latest    1543656c9290   2 minutes ago    1.12GB
   ...
   ```

4. To push the image, use the `docker push` command. Be sure to replace `DOCKER_USERNAME` with your username:

   ```console
   $ docker push DOCKER_USERNAME/getting-started-todo-app
   ```

   Depending on your upload speeds, this may take a moment to push.

1) Open Visual Studio Code. Ensure you have the **Docker extension for VS Code** installed from [Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker).

2) In the **File** menu, select **Open Folder**. Choose **Clone Git Repository** and paste this URL: <https://github.com/docker/getting-started-todo-app>

3) Right-click the `Dockerfile` and select the **Build Image...** menu item.

4) In the dialog that appears, enter a name of `DOCKER_USERNAME/getting-started-todo-app`, replacing `DOCKER_USERNAME` with your Docker username.

5) After pressing **Enter**, you'll see a terminal appear where the build will occur. Once it's completed, feel free to close the terminal.

6) Open the Docker Extension for VS Code by selecting the Docker logo in the left nav menu.

7) Find the image you created. It'll have a name of `docker.io/DOCKER_USERNAME/getting-started-todo-app`.

8) Expand the image to view the tags (or different versions) of the image. You should see a tag named `latest`, which is the default tag given to an image.

9) Right-click on the **latest** item and select the **Push...** option.

10) Press **Enter** to confirm and then watch as your image is pushed to Docker Hub. Depending on your upload speeds, it might take a moment to push the image.

    Once the upload is finished, feel free to close the terminal.

## [Recap](#recap)

Before you move on, take a moment and reflect on what happened here. Within a few moments, you were able to build a container image that packages your application and push it to Docker Hub.

Going forward, you’ll want to remember that:

* Docker Hub is the go-to registry for finding trusted content. Docker provides a collection of trusted content, composed of Docker Official Images, Docker Verified Publishers, and Docker Sponsored Open Source Software, to use directly or as bases for your own images.

* Docker Hub provides a marketplace to distribute your own applications. Anyone can create an account and distribute images. While you are publicly distributing the image you created, private repositories can ensure your images are accessible to only authorized users.

> **Usage of other registries**
>
> While Docker Hub is the default registry, registries are standardized and made interoperable through the [Open Container Initiative](https://opencontainers.org/). This allows companies and organizations to run their own private registries. Quite often, trusted content is mirrored (or copied) from Docker Hub into these private registries.

## [Next steps](#next-steps)

Now that you’ve built an image, it's time to discuss why you as a developer should learn more about Docker and how it will help you in your day-to-day tasks.

[What's Next](https://docs.docker.com/get-started/introduction/whats-next/)

----
url: https://docs.docker.com/reference/cli/docker/desktop/version/
----

# docker desktop version

***

| Description | Show the Docker Desktop CLI plugin version information |
| ----------- | ------------------------------------------------------ |
| Usage       | `docker desktop version [OPTIONS]`                     |

## [Description](#description)

Show the Docker Desktop CLI plugin version information

## [Options](#options)

| Option         | Default | Description                                                     |
| -------------- | ------- | --------------------------------------------------------------- |
| `-f, --format` |         | Format the output. Values: \[pretty \| json]. (Default: pretty) |
| `--short`      |         | Shows only the version number                                   |

----
url: https://docs.docker.com/build/policies/inputs/
----

# Input reference

***

Table of contents

***

When Buildx evaluates policies, it provides information about build inputs through the `input` object. The structure of `input` depends on the type of resource your Dockerfile references.

## [Input types](#input-types)

Build inputs correspond to Dockerfile instructions:

| Dockerfile instruction                  | Input type | Access pattern |
| --------------------------------------- | ---------- | -------------- |
| `FROM alpine:latest`                    | Image      | `input.image`  |
| `COPY --from=builder /app /app`         | Image      | `input.image`  |
| `ADD https://example.com/file.tar.gz /` | HTTP       | `input.http`   |
| `ADD git@github.com:user/repo.git /src` | Git        | `input.git`    |
| Build context (`.`)                     | Local      | `input.local`  |

Each input type has specific fields available for policy evaluation.

## [HTTP inputs](#http-inputs)

HTTP inputs represent files downloaded over HTTP or HTTPS using the `ADD` instruction.

### [Example Dockerfile](#example-dockerfile)

```dockerfile
FROM alpine
ADD --checksum=sha256:abc123... https://example.com/app.tar.gz /app.tar.gz
```

### [Available fields](#available-fields)

#### [`input.http.url`](#inputhttpurl)

The complete URL of the resource.

```rego
allow if {
    input.http.url == "https://example.com/app.tar.gz"
}
```

#### [`input.http.schema`](#inputhttpschema)

The URL scheme (`http` or `https`).

```rego
# Require HTTPS for all downloads
allow if {
    input.http.schema == "https"
}
```

#### [`input.http.host`](#inputhttphost)

The hostname from the URL.

```rego
# Allow downloads from approved domains
allow if {
    input.http.host == "cdn.example.com"
}
```

#### [`input.http.path`](#inputhttppath)

The path component of the URL.

```rego
allow if {
    startswith(input.http.path, "/releases/")
}
```

#### [`input.http.checksum`](#inputhttpchecksum)

The checksum specified with `ADD --checksum=...`, if present. Empty string if no checksum was provided.

```rego
# Require checksums for all downloads
allow if {
    input.http.checksum != ""
}
```

#### [`input.http.hasAuth`](#inputhttphasauth)

Boolean indicating if the request includes authentication (HTTP basic auth or bearer token).

```rego
# Require authentication for internal servers
allow if {
    input.http.host == "internal.company.com"
    input.http.hasAuth
}
```

## [Image inputs](#image-inputs)

Image inputs represent container images from `FROM` instructions or `COPY --from` references.

### [Example Dockerfile](#example-dockerfile-1)

```dockerfile
FROM alpine:3.19@sha256:abc123...
COPY --from=builder:latest /app /app
```

### [Available fields](#available-fields-1)

#### [`input.image.ref`](#inputimageref)

The complete image reference as written in the Dockerfile.

```rego
allow if {
    input.image.ref == "alpine:3.19@sha256:abc123..."
}
```

#### [`input.image.host`](#inputimagehost)

The registry hostname. Docker Hub images use `"docker.io"`.

```rego
# Only allow Docker Hub images
allow if {
    input.image.host == "docker.io"
}

# Only allow images from GitHub Container Registry
allow if {
    input.image.host == "ghcr.io"
}
```

#### [`input.image.repo`](#inputimagerepo)

The repository name without the registry host.

```rego
allow if {
    input.image.repo == "library/alpine"
}
```

#### [`input.image.fullRepo`](#inputimagefullrepo)

The full repository path including registry host.

```rego
allow if {
    input.image.fullRepo == "docker.io/library/alpine"
}
```

#### [`input.image.tag`](#inputimagetag)

The tag portion of the reference. Empty if using a digest reference.

```rego
# Allow only specific tags
allow if {
    input.image.tag == "3.19"
}
```

#### [`input.image.isCanonical`](#inputimageiscanonical)

Boolean indicating if the reference uses a digest (`@sha256:...`).

```rego
# Require digest references
allow if {
    input.image.isCanonical
}
```

#### [`input.image.checksum`](#inputimagechecksum)

The SHA256 digest of the image manifest.

```rego
allow if {
    input.image.checksum == "sha256:abc123..."
}
```

#### [`input.image.platform`](#inputimageplatform)

The target platform for multi-platform images.

```rego
allow if {
    input.image.platform == "linux/amd64"
}
```

#### [`input.image.os`](#inputimageos)

The operating system from the image configuration.

```rego
allow if {
    input.image.os == "linux"
}
```

#### [`input.image.arch`](#inputimagearch)

The CPU architecture from the image configuration.

```rego
allow if {
    input.image.arch == "amd64"
}
```

#### [`input.image.hasProvenance`](#inputimagehasprovenance)

Boolean indicating if the image has provenance attestations.

```rego
# Require provenance for production images
allow if {
    input.image.hasProvenance
}
```

#### [`input.image.labels`](#inputimagelabels)

A map of image labels from the image configuration.

```rego
# Check for specific labels
allow if {
    input.image.labels["org.opencontainers.image.vendor"] == "Example Corp"
}
```

#### [`input.image.signatures`](#inputimagesignatures)

Array of attestation signatures. Each signature in the array has the following fields:

* `kind`: Signature kind (e.g., `"docker-github-builder"`, `"self-signed"`)
* `type`: Signature type (e.g., `"bundle-v0.3"`, `"simplesigning-v1"`)
* `timestamps`: Trusted timestamps from transparency logs
* `dockerReference`: Docker image reference
* `isDHI`: Boolean indicating if this is a Docker Hardened Image
* `signer`: Sigstore certificate details

```rego
# Require at least one signature
allow if {
    count(input.image.signatures) > 0
}
```

For Sigstore signatures, the `signer` object provides detailed certificate information from the signing workflow:

* `certificateIssuer`: Certificate issuer
* `subjectAlternativeName`: Subject alternative name from certificate
* `buildSignerURI`: URI of the build signer
* `buildSignerDigest`: Digest of the build signer
* `runnerEnvironment`: CI/CD runner environment
* `sourceRepositoryURI`: Source repository URL
* `sourceRepositoryDigest`: Source repository digest
* `sourceRepositoryRef`: Source repository ref (branch/tag)
* `sourceRepositoryIdentifier`: Source repository identifier
* `sourceRepositoryOwnerURI`: Repository owner URI
* `buildConfigURI`: Build configuration URI
* `buildTrigger`: What triggered the build
* `runInvocationURI`: CI/CD run invocation URI

```rego
# Require signatures from GitHub Actions
allow if {
    some sig in input.image.signatures
    sig.signer.runnerEnvironment == "github-hosted"
    startswith(sig.signer.sourceRepositoryURI, "https://github.com/myorg/")
}
```

## [Git inputs](#git-inputs)

Git inputs represent Git repositories referenced in `ADD` instructions or used as build context.

### [Example Dockerfile](#example-dockerfile-2)

```dockerfile
ADD git@github.com:moby/buildkit.git#v0.12.0 /src
```

### [Available fields](#available-fields-2)

#### [`input.git.schema`](#inputgitschema)

The URL scheme (`https`, `http`, `git`, or `ssh`).

```rego
# Require HTTPS for Git clones
allow if {
    input.git.schema == "https"
}
```

#### [`input.git.host`](#inputgithost)

The Git host (e.g., `github.com`, `gitlab.com`).

```rego
allow if {
    input.git.host == "github.com"
}
```

#### [`input.git.remote`](#inputgitremote)

The complete Git URL.

```rego
allow if {
    input.git.remote == "https://github.com/moby/buildkit.git"
}
```

#### [`input.git.ref`](#inputgitref)

The Git reference.

```rego
allow if {
    input.git.ref == "refs/heads/master"
}
```

#### [`input.git.tagName`](#inputgittagname)

The tag name if the reference is a tag.

```rego
# Only allow version tags
allow if {
    regex.match(`^v[0-9]+\.[0-9]+\.[0-9]+$`, input.git.tagName)
}
```

#### [`input.git.branch`](#inputgitbranch)

The branch name if the reference is a branch.

```rego
allow if {
    input.git.branch == "main"
}
```

#### [`input.git.subDir`](#inputgitsubdir)

The subdirectory path within the repository, if specified.

```rego
# Ensure clones are from the root
allow if {
    input.git.subDir == ""
}
```

#### [`input.git.isCommitRef`](#inputgitiscommitref)

Boolean indicating if the reference is a commit SHA (as opposed to a branch or tag name).

```rego
# Require commit SHAs for production
allow if {
    input.env.target == "production"
    input.git.isCommitRef
}
```

#### [`input.git.checksum`](#inputgitchecksum)

The checksum of the Git reference. For commit references and branches, this is the commit hash. For annotated tags, this is the tag object hash.

```rego
allow if {
    input.git.checksum == "abc123..."
}
```

#### [`input.git.commitChecksum`](#inputgitcommitchecksum)

The commit hash that the reference points to. For annotated tags, this differs from `checksum` (which is the tag object hash). For commit references and branches, this is the same as `checksum`.

```rego
allow if {
    input.git.commitChecksum == "abc123..."
}
```

#### [`input.git.isAnnotatedTag`](#inputgitisannotatedtag)

Boolean indicating if the reference is an annotated tag (as opposed to a lightweight tag).

```rego
# Require annotated tags
allow if {
    input.git.tagName != ""
    input.git.isAnnotatedTag
}
```

#### [`input.git.commit`](#inputgitcommit)

Object containing commit metadata:

* `author`: Author name, email, when
* `committer`: Committer name, email, when
* `message`: Commit message
* `pgpSignature`: PGP signature details if signed
* `sshSignature`: SSH signature details if signed

```rego
# Check commit author
allow if {
    input.git.commit.author.email == "maintainer@example.com"
}
```

#### [`input.git.tag`](#inputgittag)

Object containing tag metadata for annotated tags:

* `tagger`: Tagger name, email, when
* `message`: Tag message
* `pgpSignature`: PGP signature details if signed
* `sshSignature`: SSH signature details if signed

```rego
# Require signed tags
allow if {
    input.git.tag.pgpSignature != null
}
```

## [Local inputs](#local-inputs)

Local inputs represent the build context directory.

### [Available fields](#available-fields-3)

#### [`input.local.name`](#inputlocalname)

The name or path of the local context.

```rego
allow if {
    input.local.name == "."
}
```

Local inputs are typically less restricted than remote inputs, but you can still write policies to enforce context requirements.

## [Environment fields](#environment-fields)

The `input.env` object provides build configuration information set by user on invoking the build, not specific to a resource type.

### [Available fields](#available-fields-4)

#### [`input.env.filename`](#inputenvfilename)

The name of the Dockerfile being built.

```rego
# Stricter rules for production Dockerfile
allow if {
    input.env.filename == "Dockerfile"
    input.image.isCanonical
}

# Relaxed rules for development
allow if {
    input.env.filename == "Dockerfile.dev"
}
```

#### [`input.env.target`](#inputenvtarget)

The build target from multi-stage builds.

```rego
# Require signing only for release builds
allow if {
    input.env.target == "release"
    input.git.tagName != ""
    verify_git_signature(input.git.tag, "maintainer.asc")
}
```

#### [`input.env.args`](#inputenvargs)

Build arguments passed with `--build-arg`. Access specific arguments by key.

```rego
# Check build argument values
allow if {
    input.env.args.ENVIRONMENT == "production"
    input.image.hasProvenance
}
```

## [Next steps](#next-steps)

* See [Built-in functions](https://docs.docker.com/build/policies/built-ins/) for built-in helper functions to check and validate input properties
* Browse [Example policies](https://docs.docker.com/build/policies/examples/) for common patterns
* Read about [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) for advanced policy logic

----
url: https://docs.docker.com/docker-hub/repos/manage/trusted-content/dsos-program/
----

# Docker-Sponsored Open Source Program

***

Table of contents

***

[Docker-Sponsored Open Source images](https://hub.docker.com/search?badges=open_source) are published and maintained by open-source projects sponsored by Docker through the program.

Images that are part of this program have a special badge on Docker Hub making it easier for users to identify projects that Docker has verified as trusted, secure, and active open-source projects.

The Docker-Sponsored Open Source (DSOS) Program provides several features and benefits to non-commercial open source developers.

The program grants the following perks to eligible projects:

* Repository logo
* Verified Docker-Sponsored Open Source badge
* Insights and analytics
* Access to [Docker Scout](#docker-scout) for software supply chain management
* Removal of rate limiting for developers
* Improved discoverability on Docker Hub

These benefits are valid for one year and publishers can renew annually if the project still meets the program requirements. Program members and all users pulling public images from the project namespace get access to unlimited pulls and unlimited egress.

### [Repository logo](#repository-logo)

DSOS organizations can upload custom images for individual repositories on Docker Hub. This lets you override the default organization-level logo on a per-repository basis.

Only a user with an owner or editor role for the organization can change the repository logo.

#### [Image requirements](#image-requirements)

* The supported filetypes for the logo image are JPEG and PNG.
* The minimum allowed image size in pixels is 120×120.
* The maximum allowed image size in pixels is 1000×1000.
* The maximum allowed image file size is 5MB.

#### [Set the repository logo](#set-the-repository-logo)

1. Sign in to [Docker Hub](https://hub.docker.com).
2. Go to the page of the repository that you want to change the logo for.
3. Select the upload logo button, represented by a camera icon ( ) overlaying the current repository logo.
4. In the dialog that opens, select the PNG image that you want to upload to set it as the logo for the repository.

#### [Remove the logo](#remove-the-logo)

Select the **Clear** button ( ) to remove a logo.

Removing the logo makes the repository default to using the organization logo, if set, or the following default logo if not.

### [Verified Docker-Sponsored Open Source badge](#verified-docker-sponsored-open-source-badge)

Docker verifies that developers can trust images with this badge on Docker Hub as an active open source project.

### [Insights and analytics](#insights-and-analytics)

The [insights and analytics](/docker-hub/publish/insights-analytics) service provides usage metrics for how the community uses Docker images, granting insight into user behavior.

The usage metrics show the number of image pulls by tag or by digest, and breakdowns by geolocation, cloud provider, client, and more.

You can select the time span for which you want to view analytics data. You can also export the data in either a summary or raw format.

### [Docker Scout](#docker-scout)

DSOS projects can enable Docker Scout on up to 100 repositories for free. Docker Scout provides automatic image analysis, policy evaluation for improved supply chain management, integrations with third-party systems like CI platforms and source code management, and more.

You can enable Docker Scout on a per-repository basis. For information about how to use this product, refer to the [Docker Scout documentation](/scout/).

### [Who's eligible for the Docker-Sponsored Open Source program?](#whos-eligible-for-the-docker-sponsored-open-source-program)

To qualify for the program, a publisher must share the project namespace in public repositories, meet [the Open Source Initiative definition](https://opensource.org/docs/osd), and be in active development with no pathway to commercialization.

Find out more by heading to the [Docker-Sponsored Open Source Program](https://www.docker.com/community/open-source/application/) application page.

----
url: https://docs.docker.com/guides/nodejs/develop/
----

# Use containers for Node.js development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a Node.js application](https://docs.docker.com/guides/nodejs/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment for your containerized application. This includes:

* Adding a local database and persisting data
* Configuring your container to run a development environment
* Debugging your containerized application

## [Add a local database and persist data](#add-a-local-database-and-persist-data)

The application uses PostgreSQL for data persistence. Add a database service to your Docker Compose configuration.

### [Add database service to Docker Compose](#add-database-service-to-docker-compose)

If you haven't already created a `compose.yml` file in the previous section, or if you need to add the database service, update your `compose.yml` file to include the PostgreSQL database service:

```yaml
services:
  # ... existing app services ...

  # ========================================
  # PostgreSQL Database Service
  # ========================================
  db:
    image: postgres:18-alpine
    container_name: todoapp-db
    environment:
      POSTGRES_DB: '${POSTGRES_DB:-todoapp}'
      POSTGRES_USER: '${POSTGRES_USER:-todoapp}'
      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:-todoapp_password}'
    volumes:
      - postgres_data:/var/lib/postgresql
    ports:
      - '${DB_PORT:-5432}:5432'
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-todoapp} -d ${POSTGRES_DB:-todoapp}']
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 5s
    networks:
      - todoapp-network

# ========================================
# Volume Configuration
# ========================================
volumes:
  postgres_data:
    name: todoapp-postgres-data
    driver: local

# ========================================
# Network Configuration
# ========================================
networks:
  todoapp-network:
    name: todoapp-network
    driver: bridge
```

### [Update your application service](#update-your-application-service)

Make sure your application service in `compose.yml` is configured to connect to the database:

compose.yml

```yaml
services:
  app-dev:
    build:
      context: .
      dockerfile: Dockerfile
      target: development
    container_name: todoapp-dev
    ports:
      - '${APP_PORT:-3000}:3000' # API server
      - '${VITE_PORT:-5173}:5173' # Vite dev server
      - '${DEBUG_PORT:-9229}:9229' # Node.js debugger
    environment:
      NODE_ENV: development
      DOCKER_ENV: 'true'
      POSTGRES_HOST: db
      POSTGRES_PORT: 5432
      POSTGRES_DB: todoapp
      POSTGRES_USER: todoapp
      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:-todoapp_password}'
      ALLOWED_ORIGINS: '${ALLOWED_ORIGINS:-http://localhost:3000,http://localhost:5173}'
    volumes:
      - ./src:/app/src:ro
      - ./package.json:/app/package.json
      - ./vite.config.ts:/app/vite.config.ts:ro
      - ./tailwind.config.js:/app/tailwind.config.js:ro
      - ./postcss.config.js:/app/postcss.config.js:ro
    depends_on:
      db:
        condition: service_healthy
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - '**/*.test.*'
            - '**/__tests__/**'
        - action: rebuild
          path: ./package.json
        - action: sync
          path: ./vite.config.ts
          target: /app/vite.config.ts
        - action: sync
          path: ./tailwind.config.js
          target: /app/tailwind.config.js
        - action: sync
          path: ./postcss.config.js
          target: /app/postcss.config.js
    restart: unless-stopped
    networks:
      - todoapp-network

  db:
    image: postgres:18-alpine
    container_name: todoapp-db
    environment:
      POSTGRES_DB: '${POSTGRES_DB:-todoapp}'
      POSTGRES_USER: '${POSTGRES_USER:-todoapp}'
      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:-todoapp_password}'
    volumes:
      - postgres_data:/var/lib/postgresql
    ports:
      - '${DB_PORT:-5432}:5432'
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-todoapp} -d ${POSTGRES_DB:-todoapp}']
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 5s
    networks:
      - todoapp-network

volumes:
  postgres_data:
    name: todoapp-postgres-data
    driver: local

networks:
  todoapp-network:
    name: todoapp-network
    driver: bridge
```

1. The PostgreSQL database configuration is handled automatically by the application. The database is created and initialized when the application starts, with data persisted using the `postgres_data` volume.

2. Configure your environment by copying the example file:

   ```console
   $ cp .env.example .env
   ```

   Update the `.env` file with your preferred settings:

   ```env
   # Application Configuration
   NODE_ENV=development
   APP_PORT=3000
   VITE_PORT=5173
   DEBUG_PORT=9230

   # Database Configuration
   POSTGRES_HOST=db
   POSTGRES_PORT=5432
   POSTGRES_DB=todoapp
   POSTGRES_USER=todoapp
   POSTGRES_PASSWORD=todoapp_password

   # Security Configuration
   ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
   ```

3. Run the following command to start your application in development mode:

   ```console
   $ docker compose up app-dev --build
   ```

4. Open a browser and verify that the application is running at <http://localhost:5173> for the frontend or <http://localhost:3000> for the API. The React frontend is served by Vite dev server on port 5173, with API calls proxied to the Express server on port 3000.

5. Add some items to the todo list to test data persistence.

6. After adding some items to the todo list, press `CTRL + C` in the terminal to stop your application.

7. Run the application again:

   ```console
   $ docker compose up app-dev
   ```

8. Refresh <http://localhost:5173> in your browser and verify that the todo items persisted, even after the containers were removed and ran again.

## [Configure and run a development container](#configure-and-run-a-development-container)

You can use a bind mount to mount your source code into the container. The container can then see the changes you make to the code immediately, as soon as you save a file. This means that you can run processes, like nodemon, in the container that watch for filesystem changes and respond to them. To learn more about bind mounts, see [Storage overview](https://docs.docker.com/engine/storage/).

In addition to adding a bind mount, you can configure your Dockerfile and `compose.yaml` file to install development dependencies and run development tools.

### [Update your Dockerfile for development](#update-your-dockerfile-for-development)

Your Dockerfile should be configured as a multi-stage build with separate stages for development, production, and testing. If you followed the previous section, your Dockerfile already includes a development stage that has all development dependencies and runs the application with hot reload enabled.

Here's the development stage from your multi-stage Dockerfile:

Dockerfile

```dockerfile
# ========================================
# Development Stage
# ========================================
FROM build-deps AS development

# Set environment
ENV NODE_ENV=development \
    NPM_CONFIG_LOGLEVEL=warn

# Copy source files
COPY . .

# Ensure all directories have proper permissions
RUN mkdir -p /app/node_modules/.vite && \
    chown -R nodejs:nodejs /app && \
    chmod -R 755 /app

# Switch to non-root user
USER nodejs

# Expose ports
EXPOSE 3000 5173 9229

# Start development server
CMD ["npm", "run", "dev:docker"]
```

The development stage:

* Installs all dependencies including dev dependencies
* Exposes ports for the API server (3000), Vite dev server (5173), and Node.js debugger (9229)
* Runs `npm run dev` which starts both the Express server and Vite dev server concurrently
* Includes health checks for monitoring container status

Next, you'll need to update your Compose file to use the new stage.

### [Update your Compose file for development](#update-your-compose-file-for-development)

Update your `compose.yml` file to run the development stage with bind mounts for hot reloading:

compose.yml

```yaml
services:
  app-dev:
    build:
      context: .
      dockerfile: Dockerfile
      target: development
    container_name: todoapp-dev
    ports:
      - '${APP_PORT:-3000}:3000' # API server
      - '${VITE_PORT:-5173}:5173' # Vite dev server
      - '${DEBUG_PORT:-9229}:9229' # Node.js debugger
    environment:
      NODE_ENV: development
      DOCKER_ENV: 'true'
      POSTGRES_HOST: db
      POSTGRES_PORT: 5432
      POSTGRES_DB: todoapp
      POSTGRES_USER: todoapp
      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:-todoapp_password}'
      ALLOWED_ORIGINS: '${ALLOWED_ORIGINS:-http://localhost:3000,http://localhost:5173}'
    volumes:
      - ./src:/app/src:ro
      - ./package.json:/app/package.json
      - ./vite.config.ts:/app/vite.config.ts:ro
      - ./tailwind.config.js:/app/tailwind.config.js:ro
      - ./postcss.config.js:/app/postcss.config.js:ro
    depends_on:
      db:
        condition: service_healthy
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - '**/*.test.*'
            - '**/__tests__/**'
        - action: rebuild
          path: ./package.json
        - action: sync
          path: ./vite.config.ts
          target: /app/vite.config.ts
        - action: sync
          path: ./tailwind.config.js
          target: /app/tailwind.config.js
        - action: sync
          path: ./postcss.config.js
          target: /app/postcss.config.js
    restart: unless-stopped
    networks:
      - todoapp-network
```

Key features of the development configuration:

* Multi-port exposure: API server (3000), Vite dev server (5173), and debugger (9229)
* Comprehensive bind mounts: Source code, configuration files, and package files for hot reloading
* Environment variables: Configurable through `.env` file or defaults
* PostgreSQL database: Production-ready database with persistent storage
* Docker Compose watch: Automatic file synchronization and container rebuilds
* Health checks: Database health monitoring with automatic dependency management

### [Run your development container and debug your application](#run-your-development-container-and-debug-your-application)

Run the following command to run your application with the development configuration:

```console
$ docker compose up app-dev --build
```

Or with file watching for automatic updates:

```console
$ docker compose up app-dev --watch
```

For local development without Docker:

```console
$ npm run dev:with-db
```

Or start services separately:

```console
$ npm run db:start    # Start PostgreSQL container
$ npm run dev         # Start both server and client
```

### [Using Task runner (alternative)](#using-task-runner-alternative)

The project includes a Taskfile.yml for advanced workflows:

```console
# Development
$ task dev              # Start development environment
$ task dev:build        # Build development image
$ task dev:run          # Run development container

# Production
$ task build            # Build production image
$ task run              # Run production container
$ task build-run        # Build and run in one step

# Testing
$ task test             # Run all tests
$ task test:unit        # Run unit tests with coverage
$ task test:lint        # Run linting

# Kubernetes
$ task k8s:deploy       # Deploy to Kubernetes
$ task k8s:status       # Check deployment status
$ task k8s:logs         # View pod logs

# Utilities
$ task clean            # Clean up containers and images
$ task health           # Check application health
$ task logs             # View container logs
```

The application will start with both the Express API server and Vite development server:

* API Server: <http://localhost:3000> - Express.js backend with REST API
* Frontend: <http://localhost:5173> - Vite dev server with hot module replacement
* Health Check: <http://localhost:3000/health> - Application health status

Any changes to the application's source files on your local machine will now be immediately reflected in the running container thanks to the bind mounts.

Try making a change to test hot reloading:

1. Open `src/client/components/TodoApp.tsx` in an IDE or text editor.

2. Update the main heading text:

   ```diff
   - <h1 className="text-3xl font-bold text-gray-900 mb-8">
   -   Modern Todo App
   - </h1>
   + <h1 className="text-3xl font-bold text-gray-900 mb-8">
   +   My Todo App
   + </h1>
   ```

3. Save the file and the Vite dev server will automatically reload the page with your changes.

Debugging support:

You can connect a debugger to your application on port 9229. The Node.js inspector is enabled with `--inspect=0.0.0.0:9230` in the development script (`dev:server`).

### [VS Code debugger setup](#vs-code-debugger-setup)

1. Create a launch configuration in `.vscode/launch.json`:

   ```json
   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": "Attach to Docker Container",
         "type": "node",
         "request": "attach",
         "port": 9229,
         "address": "localhost",
         "localRoot": "${workspaceFolder}",
         "remoteRoot": "/app",
         "protocol": "inspector",
         "restart": true,
         "sourceMaps": true,
         "skipFiles": ["<node_internals>/**"]
       }
     ]
   }
   ```

2. Start your development container:

   ```console
   docker compose up app-dev --build
   ```

3. Attach the debugger:

   * Open VS Code
   * From the Debug panel (Ctrl/Cmd + Shift + D), select **Attach to Docker Container** from the drop-down
   * Select the green play button or press F5

### [Chrome DevTools (alternative)](#chrome-devtools-alternative)

You can also use Chrome DevTools for debugging:

1. Start your container (if not already running):

   ```console
   docker compose up app-dev --build
   ```

2. Open Chrome and go to `chrome://inspect`.

3. From the **Configure** option, add:

   ```text
   localhost:9229
   ```

4. When your Node.js target appears, select **inspect**.

### [Debugging configuration details](#debugging-configuration-details)

The debugger configuration:

* Container port: 9230 (internal debugger port)
* Host port: 9229 (mapped external port)
* Script: `tsx watch --inspect=0.0.0.0:9230 src/server/index.ts`

The debugger listens on all interfaces (`0.0.0.0`) inside the container on port 9230 and is accessible on port 9229 from your host machine.

### [Troubleshooting debugger connection](#troubleshooting-debugger-connection)

If the debugger doesn't connect:

1. Check if the container is running:

   ```console
   docker ps
   ```

2. Check if the port is exposed:

   ```console
   docker port todoapp-dev
   ```

3. Check container logs:

   ```console
   docker compose logs app-dev
   ```

   You should see a message like:

   ```text
   Debugger listening on ws://0.0.0.0:9230/...
   ```

Now you can set breakpoints in your TypeScript source files and debug your containerized Node.js application.

For more details about Node.js debugging, see the [Node.js documentation](https://nodejs.org/en/docs/guides/debugging-getting-started).

## [Summary](#summary)

You've set up your Compose file with a PostgreSQL database and data persistence. You also created a multi-stage Dockerfile and configured bind mounts for development.

Related information:

* [Volumes top-level element](/reference/compose-file/volumes/)
* [Services top-level element](/reference/compose-file/services/)
* [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/)

## [Next steps](#next-steps)

In the next section, you'll learn how to run unit tests using Docker.

[Run Node.js tests in a container »](https://docs.docker.com/guides/nodejs/run-tests/)

----
url: https://docs.docker.com/guides/testcontainers-go-getting-started/
----

# Getting started with Testcontainers for Go

Table of contents

***

Learn how to create a Go application and test database interactions using Testcontainers for Go with a real PostgreSQL instance.

**Time to complete** 20 minutes

In this guide, you will learn how to:

* Create a Go application with modules support
* Implement a Repository to manage customer data in a PostgreSQL database using the pgx driver
* Write integration tests using testcontainers-go
* Reuse containers across multiple tests using test suites

## [Prerequisites](#prerequisites)

* Go 1.25+
* Your preferred IDE (VS Code, GoLand)
* A Docker environment supported by Testcontainers. For details, see the [testcontainers-go system requirements](https://golang.testcontainers.org/system_requirements/).

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-go-getting-started/create-project/)

   Set up a Go project with a PostgreSQL-backed repository.

2. [Write tests](https://docs.docker.com/guides/testcontainers-go-getting-started/write-tests/)

   Write your first integration test using testcontainers-go and PostgreSQL.

3. [Test suites](https://docs.docker.com/guides/testcontainers-go-getting-started/test-suites/)

   Share a single Postgres container across multiple tests using testify suites.

4. [Run tests](https://docs.docker.com/guides/testcontainers-go-getting-started/run-tests/)

   Run your Testcontainers-based integration tests and explore next steps.

----
url: https://docs.docker.com/ai/sandboxes/docker-desktop/
----

# Docker Desktop sandboxes (deprecated)

***

***

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

This page covers the Docker Desktop-integrated `docker sandbox` command for running AI coding agents in isolated microVMs. This integration is superseded by the standalone `sbx` CLI, which provides the full Docker Sandboxes workflow and doesn't require Docker Desktop.

> Note
>
> Use the standalone `sbx` CLI for sandboxed AI agent workflows.

## [Prerequisites](#prerequisites)

* Docker Desktop 4.58 or later
* macOS or Windows
* API keys for your chosen agent

## [Quick start](#quick-start)

1. Set your API key in your shell configuration file:

   \~/.bashrc or \~/.zshrc

   ```plaintext
   export ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
   ```

   Source your shell configuration and restart Docker Desktop so the daemon picks up the variable.

2. Create and run a sandbox:

   ```console
   $ cd ~/my-project
   $ docker sandbox run claude
   ```

   The first run takes longer while Docker initializes the microVM.

Replace `claude` with a different [agent](#supported-agents) if needed.

## [Supported agents](#supported-agents)

| Agent                             | Command        | Notes                                |
| --------------------------------- | -------------- | ------------------------------------ |
| Claude Code                       | `claude`       | Most tested implementation           |
| Codex                             | `codex`        |                                      |
| Copilot                           | `copilot`      |                                      |
| Gemini                            | `gemini`       |                                      |
| [Docker Agent](/ai/docker-agent/) | `docker-agent` | Also available as a standalone tool  |
| Kiro                              | `kiro`         |                                      |
| OpenCode                          | `opencode`     |                                      |
| Custom shell                      | `shell`        | Minimal environment for manual setup |

The agent type is specified when creating a sandbox and can't be changed later.

## [Authentication](#authentication)

Each agent requires its own API key or credentials. Docker Sandboxes uses a daemon that doesn't inherit environment variables from your shell session, so you must set keys in your shell configuration file (not just export them in your terminal).

Common environment variables by agent:

| Agent        | Environment variable(s)                           |
| ------------ | ------------------------------------------------- |
| Claude Code  | `ANTHROPIC_API_KEY`                               |
| Codex        | `OPENAI_API_KEY`                                  |
| Copilot      | `GH_TOKEN` or `GITHUB_TOKEN`                      |
| Gemini       | `GEMINI_API_KEY` or `GOOGLE_API_KEY`              |
| Docker Agent | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and others |
| OpenCode     | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and others |
| Kiro         | Device flow (interactive browser login)           |
| Shell        | Any provider keys needed                          |

After setting variables, source your shell configuration and restart Docker Desktop. The sandbox proxy injects credentials into API requests so keys stay on your host and are never stored inside the sandbox.

## [Commands](#commands)

```console
$ docker sandbox run AGENT [PATH]                  # Create and run
$ docker sandbox ls                                # List sandboxes
$ docker sandbox exec -it <name> bash              # Shell into a sandbox
$ docker sandbox rm <name>                         # Remove a sandbox
$ docker sandbox reset                             # Remove all sandboxes
$ docker sandbox network proxy <name> --policy … # Set network policy
$ docker sandbox network log                       # View network log
```

Sandboxes don't appear in `docker ps` because they're microVMs, not containers. For the full command reference, see the [CLI reference](/reference/cli/docker/sandbox/).

Pass agent-specific CLI options after the sandbox name with a `--` separator:

```console
$ docker sandbox run <name> -- --continue
```

## [Architecture](#architecture)

Each sandbox is a lightweight microVM with its own kernel, using your system's native virtualization (macOS virtualization.framework, Windows Hyper-V). The default agent templates include a private Docker daemon, so `docker build` and `docker compose up` run inside the sandbox without affecting your host.

```plaintext
Host system
  ├── Your containers and images
  ├── Sandbox VM 1
  │   ├── Docker daemon (isolated)
  │   ├── Agent container
  │   └── Containers created by agent
  └── Sandbox VM 2
      ├── Docker daemon (isolated)
      └── Agent container
```

Your workspace syncs bidirectionally between host and sandbox at the same absolute path. Outbound internet goes through an HTTP/HTTPS filtering proxy on the host. See [Network policies](#network-policies) for configuration.

## [Network policies](#network-policies)

The filtering proxy controls what a sandbox can access. By default, all traffic is allowed except private networks and localhost.

Allow mode (block specific destinations):

```console
$ docker sandbox network proxy my-sandbox \
  --policy allow \
  --block-cidr 10.0.0.0/8
```

Deny mode (allow specific destinations):

```console
$ docker sandbox network proxy my-sandbox \
  --policy deny \
  --allow-host api.anthropic.com \
  --allow-host "*.npmjs.org"
```

View what an agent is accessing:

```console
$ docker sandbox network log
```

## [Custom templates](#custom-templates)

Build custom templates to pre-install tools:

```dockerfile
FROM docker/sandbox-templates:claude-code

USER root
RUN apt-get update && apt-get install -y build-essential \
    && rm -rf /var/lib/apt/lists/*
USER agent
```

```console
$ docker build -t my-template:v1 .
$ docker sandbox run -t my-template:v1 claude ~/project
```

## [Base environment](#base-environment)

All agent templates share a common environment:

* Ubuntu 25.10
* Docker CLI (with Buildx and Compose), Git, GitHub CLI, Node.js, Go, Python 3, uv, make, jq, ripgrep
* Non-root `agent` user with sudo access
* Package managers: apt, pip, npm

## [Troubleshooting](#troubleshooting)

### ['sandbox' is not a docker command](#sandbox-is-not-a-docker-command)

The CLI plugin isn't installed or isn't in the correct location. Verify the plugin exists at `~/.docker/cli-plugins/docker-sandbox` and restart Docker Desktop.

### [Beta features need to be enabled](#beta-features-need-to-be-enabled)

If your Docker Desktop is managed by an administrator with [Settings Management](/enterprise/security/hardened-desktop/settings-management/), ask them to [allow beta features](/enterprise/security/hardened-desktop/settings-management/configure-json-file/#beta-features).

### [Authentication failure](#authentication-failure)

Verify your API key is valid and set in your shell configuration file (not just exported in the current session). Source the file and restart Docker Desktop.

### [Permission denied on workspace files](#permission-denied-on-workspace-files)

Check **Docker Desktop** > **Settings** > **Resources** > **File Sharing** and ensure your workspace path is listed. Verify file permissions with `ls -la`.

### [Sandbox crashes on Windows](#sandbox-crashes-on-windows)

If launching multiple sandboxes causes crashes, end all `docker.openvmm.exe` processes in Task Manager and restart Docker Desktop. Launch sandboxes one at a time.

### [Persistent issues](#persistent-issues)

Reset all sandbox state:

```console
$ docker sandbox reset
```

This stops all VMs and deletes all sandbox data. Create fresh sandboxes afterward.

----
url: https://docs.docker.com/engine/install/linux-postinstall/
----

# Linux post-installation steps for Docker Engine

***

Table of contents

***

These optional post-installation procedures describe how to configure your Linux host machine to work better with Docker.

## [Manage Docker as a non-root user](#manage-docker-as-a-non-root-user)

The Docker daemon binds to a Unix socket, not a TCP port. By default it's the `root` user that owns the Unix socket, and other users can only access it using `sudo`. The Docker daemon always runs as the `root` user.

If you don't want to preface the `docker` command with `sudo`, create a Unix group called `docker` and add users to it. When the Docker daemon starts, it creates a Unix socket accessible by members of the `docker` group. On some Linux distributions, the system automatically creates this group when installing Docker Engine using a package manager. In that case, there is no need for you to manually create the group.

> Warning
>
> The `docker` group grants root-level privileges to the user. For details on how this impacts security in your system, see [Docker Daemon Attack Surface](https://docs.docker.com/engine/security/#docker-daemon-attack-surface).

> Note
>
> To run Docker without root privileges, see [Run the Docker daemon as a non-root user (Rootless mode)](https://docs.docker.com/engine/security/rootless/).

To create the `docker` group and add your user:

1. Create the `docker` group.

   ```console
   $ sudo groupadd docker
   ```

2. Add your user to the `docker` group.

   ```console
   $ sudo usermod -aG docker $USER
   ```

3. Log out and log back in so that your group membership is re-evaluated.

   > If you're running Linux in a virtual machine, it may be necessary to restart the virtual machine for changes to take effect.

   You can also run the following command to activate the changes to groups:

   ```console
   $ newgrp docker
   ```

4. Verify that you can run `docker` commands without `sudo`.

   ```console
   $ docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a message and exits.

   If you initially ran Docker CLI commands using `sudo` before adding your user to the `docker` group, you may see the following error:

   ```text
   WARNING: Error loading config file: /home/user/.docker/config.json -
   stat /home/user/.docker/config.json: permission denied
   ```

   This error indicates that the permission settings for the `~/.docker/` directory are incorrect, due to having used the `sudo` command earlier.

   To fix this problem, either remove the `~/.docker/` directory (it's recreated automatically, but any custom settings are lost), or change its ownership and permissions using the following commands:

   ```console
   $ sudo chown "$USER":"$USER" /home/"$USER"/.docker -R
   $ sudo chmod g+rwx "$HOME/.docker" -R
   ```

## [Configure Docker to start on boot with systemd](#configure-docker-to-start-on-boot-with-systemd)

Many modern Linux distributions use [systemd](https://systemd.io/) to manage which services start when the system boots. On Debian and Ubuntu, the Docker service starts on boot by default. To automatically start Docker and containerd on boot for other Linux distributions using systemd, run the following commands:

```console
$ sudo systemctl enable docker.service
$ sudo systemctl enable containerd.service
```

To stop this behavior, use `disable` instead.

```console
$ sudo systemctl disable docker.service
$ sudo systemctl disable containerd.service
```

You can use systemd unit files to configure the Docker service on startup, for example to add an HTTP proxy, set a different directory or partition for the Docker runtime files, or other customizations. For an example, see [Configure the daemon to use a proxy](https://docs.docker.com/engine/daemon/proxy/#systemd-unit-file).

## [Configure default logging driver](#configure-default-logging-driver)

Docker provides [logging drivers](https://docs.docker.com/engine/logging/) for collecting and viewing log data from all containers running on a host. The default logging driver, `json-file`, writes log data to JSON-formatted files on the host filesystem. Over time, these log files expand in size, leading to potential exhaustion of disk resources.

To avoid issues with overusing disk for log data, consider one of the following options:

* Configure the `json-file` logging driver to turn on [log rotation](https://docs.docker.com/engine/logging/drivers/json-file/).
* Use an [alternative logging driver](https://docs.docker.com/engine/logging/configure/#configure-the-default-logging-driver) such as the ["local" logging driver](https://docs.docker.com/engine/logging/drivers/local/) that performs log rotation by default.
* Use a logging driver that sends logs to a remote logging aggregator.

## [Next steps](#next-steps)

* Take a look at the [Docker workshop](https://docs.docker.com/get-started/workshop/) to learn how to build an image and run it as a containerized application.

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/server/inspect/
----

# docker mcp catalog server inspect

***

| Description | Inspect a server in a catalog                                     |
| ----------- | ----------------------------------------------------------------- |
| Usage       | `docker mcp catalog server inspect <oci-reference> <server-name>` |

## [Description](#description)

Inspect a server in a catalog

## [Options](#options)

| Option     | Default | Description                   |
| ---------- | ------- | ----------------------------- |
| `--format` | `human` | Supported: json, yaml, human. |

----
url: https://docs.docker.com/reference/cli/docker/plugin/set/
----

# docker plugin set

***

| Description | Change settings for a plugin                        |
| ----------- | --------------------------------------------------- |
| Usage       | `docker plugin set PLUGIN KEY=VALUE [KEY=VALUE...]` |

## [Description](#description)

Change settings for a plugin. The plugin must be disabled.

The settings currently supported are:

* env variables
* source of mounts
* path of devices
* args

## [Examples](#examples)

### [Change an environment variable](#change-an-environment-variable)

The following example change the env variable `DEBUG` on the `sample-volume-plugin` plugin.

```console
$ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin
[DEBUG=0]

$ docker plugin set tiborvass/sample-volume-plugin DEBUG=1

$ docker plugin inspect -f {{.Settings.Env}} tiborvass/sample-volume-plugin
[DEBUG=1]
```

### [Change the source of a mount](#change-the-source-of-a-mount)

The following example change the source of the `mymount` mount on the `myplugin` plugin.

```console
$ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount.Source}}{{end}}' myplugin
/foo

$ docker plugins set myplugin mymount.source=/bar

$ docker plugin inspect -f '{{with $mount := index .Settings.Mounts 0}}{{$mount.Source}}{{end}}' myplugin
/bar
```

> Note
>
> Since only `source` is settable in `mymount`, `docker plugins set mymount=/bar myplugin` would work too.

### [Change a device path](#change-a-device-path)

The following example change the path of the `mydevice` device on the `myplugin` plugin.

```console
$ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin

/dev/foo

$ docker plugins set myplugin mydevice.path=/dev/bar

$ docker plugin inspect -f '{{with $device := index .Settings.Devices 0}}{{$device.Path}}{{end}}' myplugin

/dev/bar
```

> Note
>
> Since only `path` is settable in `mydevice`, `docker plugins set mydevice=/dev/bar myplugin` would work too.

### [Change the source of the arguments](#change-the-source-of-the-arguments)

The following example change the value of the args on the `myplugin` plugin.

```console
$ docker plugin inspect -f '{{.Settings.Args}}' myplugin

["foo", "bar"]

$ docker plugins set myplugin myargs="foo bar baz"

$ docker plugin inspect -f '{{.Settings.Args}}' myplugin

["foo", "bar", "baz"]
```

----
url: https://docs.docker.com/ai/gordon/how-to/docker-desktop/
----

# Using Gordon in Docker Desktop

***

Table of contents

***

Requires: Docker Desktop [4.74.0](https://docs.docker.com/desktop/release-notes/#4740) or later

Gordon is integrated into Docker Desktop. Access it from the sidebar to open the Gordon view.

## [Basic usage](#basic-usage)

To access Gordon:

1. Open Docker Desktop and sign in to your Docker account.
2. Select **Gordon** in the sidebar.
3. Type your question or request in the input field.
4. Press `Enter` or select the send button.

Gordon responds in the chat view and maintains context throughout the session.

## [Working directory](#working-directory)

The working directory sets the default context for Gordon's file operations. Select your working directory when you start Gordon or use the directory icon to change it during a conversation:

1. Select the directory icon in the Gordon input area.
2. Browse and select a different directory.

## [Contextual help](#contextual-help)

The Gordon icon appears throughout Docker Desktop. Selecting it opens Gordon pre-loaded with context about the item you are working with, such as container logs or build output.

## [Usage indicator](#usage-indicator)

Docker Desktop shows a usage indicator so you can see how close you are to your tier limit. See [Usage limits and tiers](https://docs.docker.com/ai/gordon/usage-limits/) for details.

## [Disabling Gordon](#disabling-gordon)

To disable Gordon:

1. Open Docker Desktop Settings.
2. Navigate to the **AI** section.
3. Clear the **Enable Gordon** option.
4. Select **Apply**.

## [Configure tools](#configure-tools)

You can control which tools Gordon has access to. See [Configure tools](https://docs.docker.com/ai/gordon/how-to/configure-tools/) for details on enabling, disabling, and fine-tuning tool permissions.

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/
----

# Docker MCP Toolkit

***

Table of contents

***

Availability: Beta

> Note
>
> This page describes the MCP Toolkit interface in Docker Desktop 4.62 and later. Earlier versions have a different UI. Upgrade to follow these instructions exactly.

The Docker MCP Toolkit is a management interface integrated into Docker Desktop that lets you set up, manage, and run containerized MCP servers in profiles and connect them to AI agents. It removes friction from tool usage by offering secure defaults, easy setup, and support for a growing ecosystem of LLM-based clients. It is the fastest way from MCP tool discovery to local execution.

## [Key features](#key-features)

* Cross-LLM compatibility: Works with Claude, Cursor, and other MCP clients.
* Integrated tool discovery: Browse and launch MCP servers from the Docker MCP Catalog directly in Docker Desktop.
* Zero manual setup: No dependency management, runtime configuration, or setup required.
* Profile-based organization: Create separate server collections for different projects or environments.
* Organizes MCP servers into profiles, acting as a gateway for clients to access the servers in each profile.

> Tip
>
> The MCP Toolkit includes [Dynamic MCP](https://docs.docker.com/ai/mcp-catalog-and-toolkit/dynamic-mcp/), which enables AI agents to discover, add, and compose MCP servers on-demand during conversations, without manual configuration. Your agent can search the catalog and add tools as needed when you connect to the gateway.

## [How the MCP Toolkit works](#how-the-mcp-toolkit-works)

MCP introduces two core concepts: MCP clients and MCP servers.

* MCP clients are typically embedded in LLM-based applications, such as the Claude Desktop app. They request resources or actions.
* MCP servers are launched by the client to perform the requested tasks, using any necessary tools, languages, or processes.

Docker standardizes the development, packaging, and distribution of applications, including MCP servers. By packaging MCP servers as containers, Docker eliminates issues related to isolation and environment differences. You can run a container directly, without managing dependencies or configuring runtimes.

Depending on the MCP server, the tools it provides might run within the same container as the server or in dedicated containers for better isolation.

The MCP Toolkit organizes servers into profiles: named collections of servers with their configurations. This lets you maintain different server setups for different projects or environments. When you connect a client, you specify which profile it should use.

## [Security](#security)

The Docker MCP Toolkit combines passive and active measures to reduce attack surfaces and ensure safe runtime behavior.

### [Passive security](#passive-security)

Passive security refers to measures implemented at build-time, when the MCP server code is packaged into a Docker image.

* Image signing and attestation: All MCP server images under `mcp/` in the [MCP Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/) are built by Docker and digitally signed to verify their source and integrity. Each image includes a Software Bill of Materials (SBOM) for full transparency.

### [Active security](#active-security)

Active security refers to security measures at runtime, before and after tools are invoked, enforced through resource and access limitations.

* CPU allocation: MCP tools are run in their own container. They are restricted to 1 CPU, limiting the impact of potential misuse of computing resources.

* Memory allocation: Containers for MCP tools are limited to 2 GB.

* Filesystem access: By default, MCP Servers have no access to the host filesystem. The user explicitly selects the servers that will be granted file mounts.

* Interception of tool requests: Requests to and from tools that contain sensitive information such as secrets are blocked.

### [OAuth authentication](#oauth-authentication)

Some MCP servers require authentication to access external services like GitHub, Notion, and Linear. The MCP Toolkit handles OAuth authentication automatically. You authorize access through your browser, and the Toolkit manages credentials securely. You don't need to manually create API tokens or configure authentication for each service.

#### [Authorize a server with OAuth](#authorize-a-server-with-oauth)

1. In Docker Desktop, go to **MCP Toolkit** and select the **Catalog** tab.
2. Find and add an MCP server that requires OAuth.
3. In the server's **Configuration** tab, select the **OAuth** authentication method. Follow the link to begin the OAuth authorization.
4. Your browser opens the authorization page for the service. Follow the on-screen instructions to complete authentication.
5. Return to Docker Desktop when authentication is complete.

View all authorized services in the **OAuth** tab. To revoke access, select **Revoke** next to the service you want to disconnect.

## [Usage examples](#usage-examples)

### [Example: Use Claude Desktop as a client](#example-use-claude-desktop-as-a-client)

Imagine you have Claude Desktop installed, and you want to use the GitHub MCP server and the Puppeteer MCP server. You do not have to install the servers in Claude Desktop. You can add these 2 MCP servers to your profile in the MCP Toolkit and connect Claude Desktop as a client:

1. From the **MCP Toolkit** menu, select the **Catalog** tab and find the **Puppeteer** server and add it to your profile.

2. Repeat for the **GitHub Official** server.

3. From the **Clients** tab, select **Connect** next to **Claude Desktop**. Restart Claude Desktop if it's running, and it can now access all the servers in the MCP Toolkit.

4. Within Claude Desktop, run a test by submitting the following prompt using the Sonnet 3.5 model:

   ```text
   Take a screenshot of docs.docker.com and then invert the colors
   ```

### [Example: Use Visual Studio Code as a client](#example-use-visual-studio-code-as-a-client)

You can interact with all your installed MCP servers in Visual Studio Code:

1. To enable the MCP Toolkit:

   1. Insert the following in your Visual Studio Code's User `mcp.json`:

      ```json
      "mcp": {
       "servers": {
         "MCP_DOCKER": {
           "command": "docker",
           "args": [
             "mcp",
             "gateway",
             "run",
             "--profile",
             "my_profile"
           ],
           "type": "stdio"
         }
       }
      }
      ```

   1) In your terminal, navigate to your project's folder.

   2) Run:

      ```bash
      docker mcp client connect vscode --profile my_profile
      ```

      > Note
      >
      > This command creates a `.vscode/mcp.json` file in the current directory that connects VSCode to your profile. As this is a user-specific file, add it to your `.gitignore` file to prevent it from being committed to the repository.
      >
      > ```console
      > echo ".vscode/mcp.json" >> .gitignore
      > ```

2. In Visual Studio Code, open a new Chat and select the **Agent** mode:

3. You can also check the available MCP tools:

For more information about the Agent mode, see the [Visual Studio Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_use-mcp-tools-in-agent-mode).

## [Further reading](#further-reading)

* [Use MCP Toolkit from the CLI](https://docs.docker.com/ai/mcp-catalog-and-toolkit/cli/)
* [MCP Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/)
* [MCP Gateway](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/debug/
----

# docker buildx debug

***

| Description | Start debugger |
| ----------- | -------------- |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Start debugger

## [Options](#options)

| Option     | Default | Description                                                          |
| ---------- | ------- | -------------------------------------------------------------------- |
| `--invoke` |         | experimental (CLI) Launch a monitor with executing specified command |
| `--on`     | `error` | experimental (CLI) When to launch the monitor (\[always, error])     |

## [Subcommands](#subcommands)

| Command                                                                                         | Description   |
| ----------------------------------------------------------------------------------------------- | ------------- |
| [`docker buildx debug build`](https://docs.docker.com/reference/cli/docker/buildx/debug/build/) | Start a build |

----
url: https://docs.docker.com/guides/golang/develop/
----

# Use containers for Go development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Work through the steps of the [run your image as a container](https://docs.docker.com/guides/golang/run-containers/) module to learn how to manage the lifecycle of your containers.

## [Introduction](#introduction)

In this module, you'll take a look at running a database engine in a container and connecting it to the extended version of the example application. You are going to see some options for keeping persistent data and for wiring up the containers to talk to one another. Finally, you'll learn how to use Docker Compose to manage such multi-container local development environments effectively.

## [Local database and containers](#local-database-and-containers)

The database engine you are going to use is called [CockroachDB](https://www.cockroachlabs.com/product/). It is a modern, Cloud-native, distributed SQL database.

Instead of compiling CockroachDB from the source code or using the operating system's native package manager to install CockroachDB, you are going to use the [Docker image for CockroachDB](https://hub.docker.com/r/cockroachdb/cockroach) and run it in a container.

CockroachDB is compatible with PostgreSQL to a significant extent, and shares many conventions with the latter, particularly the default names for the environment variables. So, if you are familiar with Postgres, don't be surprised if you see some familiar environment variable names. The Go modules that work with Postgres, such as [pgx](https://pkg.go.dev/github.com/jackc/pgx), [pq](https://pkg.go.dev/github.com/lib/pq), [GORM](https://gorm.io/index.html), and [upper/db](https://upper.io/v4/) also work with CockroachDB.

For more information on the relation between Go and CockroachDB, refer to the [CockroachDB documentation](https://www.cockroachlabs.com/docs/v20.2/build-a-go-app-with-cockroachdb.html), although this isn't necessary to continue with the present guide.

### [Storage](#storage)

The point of a database is to have a persistent store of data. [Volumes](https://docs.docker.com/engine/storage/volumes/) are the preferred mechanism for persisting data generated by and used by Docker containers. Thus, before you start CockroachDB, create the volume for it.

To create a managed volume, run :

```console
$ docker volume create roach
roach
```

You can view the list of all managed volumes in your Docker instance with the following command:

```console
$ docker volume list
DRIVER    VOLUME NAME
local     roach
```

### [Networking](#networking)

The example application and the database engine are going to talk to one another over the network. There are different kinds of network configuration possible, and you're going to use what's called a user-defined bridge network. It is going to provide you with a DNS lookup service so that you can refer to your database engine container by its hostname.

The following command creates a new bridge network named `mynet`:

```console
$ docker network create -d bridge mynet
51344edd6430b5acd121822cacc99f8bc39be63dd125a3b3cd517b6485ab7709
```

As it was the case with the managed volumes, there is a command to list all networks set up in your Docker instance:

```console
$ docker network list
NETWORK ID     NAME          DRIVER    SCOPE
0ac2b1819fa4   bridge        bridge    local
51344edd6430   mynet         bridge    local
daed20bbecce   host          host      local
6aee44f40a39   none          null      local
```

Your bridge network `mynet` has been created successfully. The other three networks, named `bridge`, `host`, and `none` are the default networks and they had been created by the Docker itself. While it's not relevant to this guide, you can learn more about Docker networking in the [networking overview](https://docs.docker.com/engine/network/) section.

### [Choose good names for volumes and networks](#choose-good-names-for-volumes-and-networks)

As the saying goes, there are only two hard things in Computer Science: cache invalidation and naming things. And off-by-one errors.

When choosing a name for a network or a managed volume, it's best to choose a name that's indicative of the intended purpose. This guide aims for brevity, so it used short, generic names.

### [Start the database engine](#start-the-database-engine)

Now that the housekeeping chores are done, you can run CockroachDB in a container and attach it to the volume and network you had just created. When you run the following command, Docker will pull the image from Docker Hub and run it for you locally:

```console
$ docker run -d \
  --name roach \
  --hostname db \
  --network mynet \
  -p 26257:26257 \
  -p 8080:8080 \
  -v roach:/cockroach/cockroach-data \
  cockroachdb/cockroach:latest-v25.4 start-single-node \
  --insecure

# ... output omitted ...
```

Notice a clever use of the tag `latest-v25.4` to make sure that you're pulling the latest patch version of 25.4. The diversity of available tags depend on the image maintainer. Here, your intent was to have the latest patched version of CockroachDB while not straying too far away from the known working version as the time goes by. To see the tags available for the CockroachDB image, you can go to the [CockroachDB page on Docker Hub](https://hub.docker.com/r/cockroachdb/cockroach/tags).

### [Configure the database engine](#configure-the-database-engine)

Now that the database engine is live, there is some configuration to do before your application can begin using it. Fortunately, it's not a lot. You must:

1. Create a blank database.
2. Register a new user account with the database engine.
3. Grant that new user access rights to the database.

You can do that with the help of CockroachDB built-in SQL shell. To start the SQL shell in the same container where the database engine is running, type:

```console
$ docker exec -it roach ./cockroach sql --insecure
```

1. In the SQL shell, create the database that the example application is going to use:

   ```sql
   CREATE DATABASE mydb;
   ```

2. Register a new SQL user account with the database engine. Use the username `totoro`.

   ```sql
   CREATE USER totoro;
   ```

3. Give the new user the necessary permissions:

   ```sql
   GRANT ALL ON DATABASE mydb TO totoro;
   ```

4. Type `quit` to exit the shell.

The following is an example of interaction with the SQL shell.

```console
$ sudo docker exec -it roach ./cockroach sql --insecure
#
# Welcome to the CockroachDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
# Server version: CockroachDB CCL v20.1.15 (x86_64-unknown-linux-gnu, built 2021/04/26 16:11:58, go1.13.9) (same version as client)
# Cluster ID: 7f43a490-ccd6-4c2a-9534-21f393ca80ce
#
# Enter \? for a brief introduction.
#
root@:26257/defaultdb> CREATE DATABASE mydb;
CREATE DATABASE

Time: 22.985478ms

root@:26257/defaultdb> CREATE USER totoro;
CREATE ROLE

Time: 13.921659ms

root@:26257/defaultdb> GRANT ALL ON DATABASE mydb TO totoro;
GRANT

Time: 14.217559ms

root@:26257/defaultdb> quit
oliver@hki:~$
```

### [Meet the example application](#meet-the-example-application)

Now that you have started and configured the database engine, you can switch your attention to the application.

The example application for this module is an extended version of `docker-gs-ping` application you've used in the previous modules. You have two options:

* You can update your local copy of `docker-gs-ping` to match the new extended version presented in this chapter; or
* You can clone the [docker/docker-gs-ping-dev](https://github.com/docker/docker-gs-ping-dev) repository. This latter approach is recommended.

To checkout the example application, run:

```console
$ git clone https://github.com/docker/docker-gs-ping-dev.git
# ... output omitted ...
```

The application's `main.go` now includes database initialization code, as well as the code to implement a new business requirement:

* An HTTP `POST` request to `/send` containing a `{ "value" : string }` JSON must save the value to the database.

You also have an update for another business requirement. The requirement was:

* The application responds with a text message containing a heart symbol ("`<3`") on requests to `/`.

And now it's going to be:

* The application responds with the string containing the count of messages stored in the database, enclosed in the parentheses.

  Example output: `Hello, Docker! (7)`

The full source code listing of `main.go` follows.

```go
package main

import (
	"context"
	"database/sql"
	"fmt"
	"log"
	"net/http"
	"os"

	"github.com/cenkalti/backoff/v4"
	"github.com/cockroachdb/cockroach-go/v2/crdb"
	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
)

func main() {

	e := echo.New()

	e.Use(middleware.Logger())
	e.Use(middleware.Recover())

	db, err := initStore()
	if err != nil {
		log.Fatalf("failed to initialize the store: %s", err)
	}
	defer db.Close()

	e.GET("/", func(c echo.Context) error {
		return rootHandler(db, c)
	})

	e.GET("/ping", func(c echo.Context) error {
		return c.JSON(http.StatusOK, struct{ Status string }{Status: "OK"})
	})

	e.POST("/send", func(c echo.Context) error {
		return sendHandler(db, c)
	})

	httpPort := os.Getenv("HTTP_PORT")
	if httpPort == "" {
		httpPort = "8080"
	}

	e.Logger.Fatal(e.Start(":" + httpPort))
}

type Message struct {
	Value string `json:"value"`
}

func initStore() (*sql.DB, error) {

	pgConnString := fmt.Sprintf("host=%s port=%s dbname=%s user=%s password=%s sslmode=disable",
		os.Getenv("PGHOST"),
		os.Getenv("PGPORT"),
		os.Getenv("PGDATABASE"),
		os.Getenv("PGUSER"),
		os.Getenv("PGPASSWORD"),
	)

	var (
		db  *sql.DB
		err error
	)
	openDB := func() error {
		db, err = sql.Open("postgres", pgConnString)
		return err
	}

	err = backoff.Retry(openDB, backoff.NewExponentialBackOff())
	if err != nil {
		return nil, err
	}

	if _, err := db.Exec(
		"CREATE TABLE IF NOT EXISTS message (value TEXT PRIMARY KEY)"); err != nil {
		return nil, err
	}

	return db, nil
}

func rootHandler(db *sql.DB, c echo.Context) error {
	r, err := countRecords(db)
	if err != nil {
		return c.HTML(http.StatusInternalServerError, err.Error())
	}
	return c.HTML(http.StatusOK, fmt.Sprintf("Hello, Docker! (%d)\n", r))
}

func sendHandler(db *sql.DB, c echo.Context) error {

	m := &Message{}

	if err := c.Bind(m); err != nil {
		return c.JSON(http.StatusInternalServerError, err)
	}

	err := crdb.ExecuteTx(context.Background(), db, nil,
		func(tx *sql.Tx) error {
			_, err := tx.Exec(
				"INSERT INTO message (value) VALUES ($1) ON CONFLICT (value) DO UPDATE SET value = excluded.value",
				m.Value,
			)
			if err != nil {
				return c.JSON(http.StatusInternalServerError, err)
			}
			return nil
		})

	if err != nil {
		return c.JSON(http.StatusInternalServerError, err)
	}

	return c.JSON(http.StatusOK, m)
}

func countRecords(db *sql.DB) (int, error) {

	rows, err := db.Query("SELECT COUNT(*) FROM message")
	if err != nil {
		return 0, err
	}
	defer rows.Close()

	count := 0
	for rows.Next() {
		if err := rows.Scan(&count); err != nil {
			return 0, err
		}
		rows.Close()
	}

	return count, nil
}
```

The repository also includes the `Dockerfile`, which is almost exactly the same as the multi-stage `Dockerfile` introduced in the previous modules. It uses the official Docker Go image to build the application and then builds the final image by placing the compiled binary into the much slimmer, distroless image.

Regardless of whether you had updated the old example application, or checked out the new one, this new Docker image has to be built to reflect the changes to the application source code.

### [Build the application](#build-the-application)

You can build the image with the familiar `build` command:

```console
$ docker build --tag docker-gs-ping-roach .
```

### [Run the application](#run-the-application)

Now, run your container. This time you'll need to set some environment variables so that your application knows how to access the database. For now, you’ll do this right in the `docker run` command. Later you'll see a more convenient method with Docker Compose.

> Note
>
> Since you're running your CockroachDB cluster in insecure mode, the value for the password can be anything.
>
> In production, don't run in insecure mode.

```console
$ docker run -it --rm -d \
  --network mynet \
  --name rest-server \
  -p 80:8080 \
  -e PGUSER=totoro \
  -e PGPASSWORD=myfriend \
  -e PGHOST=db \
  -e PGPORT=26257 \
  -e PGDATABASE=mydb \
  docker-gs-ping-roach
```

There are a few points to note about this command.

* You map container port `8080` to host port `80` this time. Thus, for `GET` requests you can get away with literally `curl localhost`:

  ```console
  $ curl localhost
  Hello, Docker! (0)
  ```

  Or, if you prefer, a proper URL would work just as well:

  ```console
  $ curl http://localhost/
  Hello, Docker! (0)
  ```

* The total number of stored messages is `0` for now. This is fine, because you haven't posted anything to your application yet.

* You refer to the database container by its hostname, which is `db`. This is why you had `--hostname db` when you started the database container.

* The actual password doesn't matter, but it must be set to something to avoid confusing the example application.

* The container you've just run is named `rest-server`. These names are useful for managing the container lifecycle:

  ```console
  # Don't do this just yet, it's only an example:
  $ docker container rm --force rest-server
  ```

### [Test the application](#test-the-application)

In the previous section, you've already tested querying your application with `GET` and it returned zero for the stored message counter. Now, post some messages to it:

```console
$ curl --request POST \
  --url http://localhost/send \
  --header 'content-type: application/json' \
  --data '{"value": "Hello, Docker!"}'
```

The application responds with the contents of the message, which means it has been saved in the database:

```json
{ "value": "Hello, Docker!" }
```

Send another message:

```console
$ curl --request POST \
  --url http://localhost/send \
  --header 'content-type: application/json' \
  --data '{"value": "Hello, Oliver!"}'
```

And again, you get the value of the message back:

```json
{ "value": "Hello, Oliver!" }
```

Run curl and see what the message counter says:

```console
$ curl localhost
Hello, Docker! (2)
```

In this example, you sent two messages and the database kept them. Or has it? Stop and remove all your containers, but not the volumes, and try again.

First, stop the containers:

```console
$ docker container stop rest-server roach
rest-server
roach
```

Then, remove them:

```console
$ docker container rm rest-server roach
rest-server
roach
```

Verify that they're gone:

```console
$ docker container list --all
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES
```

And start them again, database first:

```console
$ docker run -d \
  --name roach \
  --hostname db \
  --network mynet \
  -p 26257:26257 \
  -p 8080:8080 \
  -v roach:/cockroach/cockroach-data \
  cockroachdb/cockroach:latest-v25.4 start-single-node \
  --insecure
```

And the service next:

```console
$ docker run -it --rm -d \
  --network mynet \
  --name rest-server \
  -p 80:8080 \
  -e PGUSER=totoro \
  -e PGPASSWORD=myfriend \
  -e PGHOST=db \
  -e PGPORT=26257 \
  -e PGDATABASE=mydb \
  docker-gs-ping-roach
```

Lastly, query your service:

```console
$ curl localhost
Hello, Docker! (2)
```

Great! The count of records from the database is correct although you haven't only stopped the containers, but you've also removed them before starting new instances. The difference is in the managed volume for CockroachDB, which you reused. The new CockroachDB container has read the database files from the disk, just as it normally would if it were running outside the container.

### [Wind down everything](#wind-down-everything)

Remember, that you're running CockroachDB in insecure mode. Now that you've built and tested your application, it's time to wind everything down before moving on. You can list the containers that you are running with the `list` command:

```console
$ docker container list
```

Now that you know the container IDs, you can use `docker container stop` and `docker container rm`, as demonstrated in the previous modules.

Stop the CockroachDB and `docker-gs-ping-roach` containers before moving on.

## [Better productivity with Docker Compose](#better-productivity-with-docker-compose)

At this point, you might be wondering if there is a way to avoid having to deal with long lists of arguments to the `docker` command. The toy example you used in this series requires five environment variables to define the connection to the database. A real application might need many, many more. Then there is also a question of dependencies. Ideally, you want to make sure that the database is started before your application is run. And spinning up the database instance may require another Docker command with many options. But there is a better way to orchestrate these deployments for local development purposes.

In this section, you'll create a Docker Compose file to start your `docker-gs-ping-roach` application and CockroachDB database engine with a single command.

### [Configure Docker Compose](#configure-docker-compose)

In your application's directory, create a new text file named `compose.yaml` with the following content.

```yaml
version: "3.8"

services:
  docker-gs-ping-roach:
    depends_on:
      - roach
    build:
      context: .
    container_name: rest-server
    hostname: rest-server
    networks:
      - mynet
    ports:
      - 80:8080
    environment:
      - PGUSER=${PGUSER:-totoro}
      - PGPASSWORD=${PGPASSWORD:?database password not set}
      - PGHOST=${PGHOST:-db}
      - PGPORT=${PGPORT:-26257}
      - PGDATABASE=${PGDATABASE:-mydb}
    deploy:
      restart_policy:
        condition: on-failure
  roach:
    image: cockroachdb/cockroach:latest-v25.4
    container_name: roach
    hostname: db
    networks:
      - mynet
    ports:
      - 26257:26257
      - 8080:8080
    volumes:
      - roach:/cockroach/cockroach-data
    command: start-single-node --insecure

volumes:
  roach:

networks:
  mynet:
    driver: bridge
```

This Docker Compose configuration is super convenient as you don't have to type all the parameters to pass to the `docker run` command. You can declaratively do that in the Docker Compose file. The [Docker Compose documentation pages](https://docs.docker.com/compose/) are quite extensive and include a full reference for the Docker Compose file format.

### [The `.env` file](#the-env-file)

Docker Compose will automatically read environment variables from a `.env` file if it's available. Since your Compose file requires `PGPASSWORD` to be set, add the following content to the `.env` file:

```bash
PGPASSWORD=whatever
```

The exact value doesn't really matter for this example, because you run CockroachDB in insecure mode. Make sure you set the variable to some value to avoid getting an error.

### [Merging Compose files](#merging-compose-files)

The filename `compose.yaml` is the default filename which `docker compose` command recognizes if no `-f` flag is provided. This means you can have multiple Docker Compose files if your environment has such requirements. Furthermore, Docker Compose files are composable, so multiple files can be specified on the command line to merge parts of the configuration together. The following list shows a few examples of scenarios where such a feature would be useful:

* Using a bind mount for the source code for local development but not when running the CI tests;
* Switching between using a pre-built image for the frontend for some API application vs creating a bind mount for source code;
* Adding additional services for integration testing;
* And many more...

You aren't going to cover any of these advanced use cases here.

### [Variable substitution in Docker Compose](#variable-substitution-in-docker-compose)

One of the really cool features of Docker Compose is [variable substitution](https://docs.docker.com/reference/compose-file/interpolation/). You can see some examples in the Compose file, `environment` section. By means of an example:

* `PGUSER=${PGUSER:-totoro}` means that inside the container, the environment variable `PGUSER` shall be set to the same value as it has on the host machine where Docker Compose is run. If there is no environment variable with this name on the host machine, the variable inside the container gets the default value of `totoro`.
* `PGPASSWORD=${PGPASSWORD:?database password not set}` means that if the environment variable `PGPASSWORD` isn't set on the host, Docker Compose will display an error. This is OK, because you don't want to hard-code default values for the password. You set the password value in the `.env` file, which is local to your machine. It is always a good idea to add `.env` to `.gitignore` to prevent the secrets being checked into the version control.

Other ways of dealing with undefined or empty values exist, as documented in the [variable substitution](https://docs.docker.com/reference/compose-file/interpolation/) section of the Docker documentation.

### [Validating Docker Compose configuration](#validating-docker-compose-configuration)

Before you apply changes made to a Compose configuration file, there is an opportunity to validate the content of the configuration file with the following command:

```console
$ docker compose config
```

When this command is run, Docker Compose reads the file `compose.yaml`, parses it into a data structure in memory, validates where possible, and prints back the reconstruction of that configuration file from its internal representation. If this isn't possible due to errors, Docker prints an error message instead.

### [Build and run the application using Docker Compose](#build-and-run-the-application-using-docker-compose)

Start your application and confirm that it's running.

```console
$ docker compose up --build
```

You passed the `--build` flag so Docker will compile your image and then start it.

> Note
>
> Docker Compose is a useful tool, but it has its own quirks. For example, no rebuild is triggered on the update to the source code unless the `--build` flag is provided. It is a very common pitfall to edit one's source code, and forget to use the `--build` flag when running `docker compose up`.

Since your set-up is now run by Docker Compose, it has assigned it a project name, so you get a new volume for your CockroachDB instance. This means that your application will fail to connect to the database, because the database doesn't exist in this new volume. The terminal displays an authentication error for the database:

```text
# ... omitted output ...
rest-server             | 2021/05/10 00:54:25 failed to initialise the store: pq: password authentication failed for user totoro
roach                   | *
roach                   | * INFO: Replication was disabled for this cluster.
roach                   | * When/if adding nodes in the future, update zone configurations to increase the replication factor.
roach                   | *
roach                   | CockroachDB node starting at 2021-05-10 00:54:26.398177 +0000 UTC (took 3.0s)
roach                   | build:               CCL v20.1.15 @ 2021/04/26 16:11:58 (go1.13.9)
roach                   | webui:               http://db:8080
roach                   | sql:                 postgresql://root@db:26257?sslmode=disable
roach                   | RPC client flags:    /cockroach/cockroach <client cmd> --host=db:26257 --insecure
roach                   | logs:                /cockroach/cockroach-data/logs
roach                   | temp dir:            /cockroach/cockroach-data/cockroach-temp349434348
roach                   | external I/O path:   /cockroach/cockroach-data/extern
roach                   | store[0]:            path=/cockroach/cockroach-data
roach                   | storage engine:      rocksdb
roach                   | status:              initialized new cluster
roach                   | clusterID:           b7b1cb93-558f-4058-b77e-8a4ddb329a88
roach                   | nodeID:              1
rest-server exited with code 0
rest-server             | 2021/05/10 00:54:25 failed to initialise the store: pq: password authentication failed for user totoro
rest-server             | 2021/05/10 00:54:26 failed to initialise the store: pq: password authentication failed for user totoro
rest-server             | 2021/05/10 00:54:29 failed to initialise the store: pq: password authentication failed for user totoro
rest-server             | 2021/05/10 00:54:25 failed to initialise the store: pq: password authentication failed for user totoro
rest-server             | 2021/05/10 00:54:26 failed to initialise the store: pq: password authentication failed for user totoro
rest-server             | 2021/05/10 00:54:29 failed to initialise the store: pq: password authentication failed for user totoro
rest-server exited with code 1
# ... omitted output ...
```

Because of the way you set up your deployment using `restart_policy`, the failing container is being restarted every 20 seconds. So, in order to fix the problem, you need to log in to the database engine and create the user. You've done it before in [Configure the database engine](#configure-the-database-engine).

This isn't a big deal. All you have to do is to connect to CockroachDB instance and run the three SQL commands to create the database and the user, as described in [Configure the database engine](#configure-the-database-engine).

So, log in to the database engine from another terminal:

```console
$ docker exec -it roach ./cockroach sql --insecure
```

And run the same commands as before to create the database `mydb`, the user `totoro`, and to grant that user necessary permissions. Once you do that (and the example application container is automatically restarts), the `rest-service` stops failing and restarting and the console goes quiet.

It would have been possible to connect the volume that you had previously used, but for the purposes of this example it's more trouble than it's worth and it also provided an opportunity to show how to introduce resilience into your deployment via the `restart_policy` Compose file feature.

### [Testing the application](#testing-the-application)

Now, test your API endpoint. In the new terminal, run the following command:

```console
$ curl http://localhost/
```

You should receive the following response:

```json
Hello, Docker! (0)
```

### [Shutting down](#shutting-down)

To stop the containers started by Docker Compose, press `ctrl+c` in the terminal where you ran `docker compose up`. To remove those containers after they've been stopped, run `docker compose down`.

### [Detached mode](#detached-mode)

You can run containers started by the `docker compose` command in detached mode, just as you would with the `docker` command, by using the `-d` flag.

To start the stack, defined by the Compose file in detached mode, run:

```console
$ docker compose up --build -d
```

Then, you can use `docker compose stop` to stop the containers and `docker compose down` to remove them.

## [Further exploration](#further-exploration)

You can run `docker compose` to see what other commands are available.

## [Wrap up](#wrap-up)

There are some tangential, yet interesting points that were purposefully not covered in this chapter. For the more adventurous reader, this section offers some pointers for further study.

### [Persistent storage](#persistent-storage)

A managed volume isn't the only way to provide your container with persistent storage. It is highly recommended to get acquainted with available storage options and their use cases, covered in [Manage data in Docker](https://docs.docker.com/engine/storage/).

### [CockroachDB clusters](#cockroachdb-clusters)

You ran a single instance of CockroachDB, which was enough for this example. But, it's possible to run a CockroachDB cluster, which is made of multiple instances of CockroachDB, each instance running in its own container. Since CockroachDB engine is distributed by design, it would have taken surprisingly little change to your procedure to run a cluster with multiple nodes.

Such distributed set-up offers interesting possibilities, such as applying Chaos Engineering techniques to simulate parts of the cluster failing and evaluating your application's ability to cope with such failures.

If you are interested in experimenting with CockroachDB clusters, check out:

* [Start a CockroachDB Cluster in Docker](https://www.cockroachlabs.com/docs/v20.2/start-a-local-cluster-in-docker-mac.html) article; and
* Documentation for Docker Compose keywords [`deploy`](https://docs.docker.com/reference/compose-file/legacy-versions/) and [`replicas`](https://docs.docker.com/reference/compose-file/legacy-versions/).

### [Other databases](#other-databases)

Since you didn't run a cluster of CockroachDB instances, you might be wondering whether you could have used a non-distributed database engine. The answer is 'yes', and if you were to pick a more traditional SQL database, such as [PostgreSQL](https://www.postgresql.org/), the process described in this chapter would have been very similar.

## [Next steps](#next-steps)

In this module, you set up a containerized development environment with your application and the database engine running in different containers. You also wrote a Docker Compose file which links the two containers together and provides for easy starting up and tearing down of the development environment.

In the next module, you'll take a look at one possible approach to running functional tests in Docker.

[Run your tests using Go test »](https://docs.docker.com/guides/golang/run-tests/)

----
url: https://docs.docker.com/build/bake/inheritance/
----

# Inheritance in Bake

***

Table of contents

***

Targets can inherit attributes from other targets, using the `inherits` attribute. For example, imagine that you have a target that builds a Docker image for a development environment:

docker-bake.hcl

```hcl
target "app-dev" {
  args = {
    GO_VERSION = "1.25"
  }
  tags = ["docker.io/username/myapp:dev"]
  labels = {
    "org.opencontainers.image.source" = "https://github.com/username/myapp"
    "org.opencontainers.image.author" = "moby.whale@example.com"
  }
}
```

You can create a new target that uses the same build configuration, but with slightly different attributes for a production build. In this example, the `app-release` target inherits the `app-dev` target, but overrides the `tags` attribute and adds a new `platforms` attribute:

docker-bake.hcl

```hcl
target "app-release" {
  inherits = ["app-dev"]
  tags = ["docker.io/username/myapp:latest"]
  platforms = ["linux/amd64", "linux/arm64"]
}
```

## [Common reusable targets](#common-reusable-targets)

One common inheritance pattern is to define a common target that contains shared attributes for all or many of the build targets in the project. For example, the following `_common` target defines a common set of build arguments:

docker-bake.hcl

```hcl
target "_common" {
  args = {
    GO_VERSION = "1.25"
    BUILDKIT_CONTEXT_KEEP_GIT_DIR = 1
  }
}
```

You can then inherit the `_common` target in other targets to apply the shared attributes:

docker-bake.hcl

```hcl
target "lint" {
  inherits = ["_common"]
  dockerfile = "./dockerfiles/lint.Dockerfile"
  output = [{ type = "cacheonly" }]
}

target "docs" {
  inherits = ["_common"]
  dockerfile = "./dockerfiles/docs.Dockerfile"
  output = ["./docs/reference"]
}

target "test" {
  inherits = ["_common"]
  target = "test-output"
  output = ["./test"]
}

target "binaries" {
  inherits = ["_common"]
  target = "binaries"
  output = ["./build"]
  platforms = ["local"]
}
```

## [Overriding inherited attributes](#overriding-inherited-attributes)

When a target inherits another target, it can override any of the inherited attributes. For example, the following target overrides the `args` attribute from the inherited target:

docker-bake.hcl

```hcl
target "app-dev" {
  inherits = ["_common"]
  args = {
    GO_VERSION = "1.17"
  }
  tags = ["docker.io/username/myapp:dev"]
}
```

The `GO_VERSION` argument in `app-release` is set to `1.17`, overriding the `GO_VERSION` argument from the `app-dev` target.

For more information about overriding attributes, see the [Overriding configurations](https://docs.docker.com/build/bake/overrides/) page.

## [Inherit from multiple targets](#inherit-from-multiple-targets)

The `inherits` attribute is a list, meaning you can reuse attributes from multiple other targets. In the following example, the app-release target reuses attributes from both the `app-dev` and `_common` targets.

docker-bake.hcl

```hcl
target "_common" {
  args = {
    GO_VERSION = "1.25"
    BUILDKIT_CONTEXT_KEEP_GIT_DIR = 1
  }
}

target "app-dev" {
  inherits = ["_common"]
  args = {
    BUILDKIT_CONTEXT_KEEP_GIT_DIR = 0
  }
  tags = ["docker.io/username/myapp:dev"]
  labels = {
    "org.opencontainers.image.source" = "https://github.com/username/myapp"
    "org.opencontainers.image.author" = "moby.whale@example.com"
  }
}

target "app-release" {
  inherits = ["app-dev", "_common"]
  tags = ["docker.io/username/myapp:latest"]
  platforms = ["linux/amd64", "linux/arm64"]
}
```

When inheriting attributes from multiple targets and there's a conflict, the target that appears last in the inherits list takes precedence. The previous example defines the `BUILDKIT_CONTEXT_KEEP_GIT_DIR` in the `_common` target and overrides it in the `app-dev` target.

The `app-release` target inherits both `app-dev` target and the `_common` target. The `BUILDKIT_CONTEXT_KEEP_GIT_DIR` argument is set to 0 in the `app-dev` target and 1 in the `_common` target. The `BUILDKIT_CONTEXT_KEEP_GIT_DIR` argument in the `app-release` target is set to 1, not 0, because the `_common` target appears last in the inherits list.

## [Reusing single attributes from targets](#reusing-single-attributes-from-targets)

If you only want to inherit a single attribute from a target, you can reference an attribute from another target using dot notation. For example, in the following Bake file, the `bar` target reuses the `tags` attribute from the `foo` target:

docker-bake.hcl

```hcl
target "foo" {
  dockerfile = "foo.Dockerfile"
  tags       = ["myapp:latest"]
}
target "bar" {
  dockerfile = "bar.Dockerfile"
  tags       = target.foo.tags
}
```

----
url: https://docs.docker.com/build-cloud/release-notes/
----

# Docker Build Cloud release notes

***

Table of contents

***

This page contains information about the new features, improvements, known issues, and bug fixes in Docker Build Cloud releases.

## [2025-02-24](#2025-02-24)

### [New](#new)

Added a new **Build settings** page where you can configure disk allocation, private resource access, and firewall settings for your cloud builders in your organization. These configurations help optimize storage, enable access to private registries, and secure outbound network traffic.

----
url: https://docs.docker.com/dhi/core-concepts/fips/
----

# FIPS

***

Table of contents

***

Subscription: Docker Hardened Images Select or Enterprise

## [What is FIPS 140?](#what-is-fips-140)

[FIPS 140](https://csrc.nist.gov/publications/detail/fips/140/3/final) is a U.S. government standard that defines security requirements for cryptographic modules that protect sensitive information. It is widely used in regulated environments such as government, healthcare, and financial services.

FIPS certification is managed by the [NIST Cryptographic Module Validation Program (CMVP)](https://csrc.nist.gov/projects/cryptographic-module-validation-program), which ensures cryptographic modules meet rigorous security standards.

## [Why FIPS compliance matters](#why-fips-compliance-matters)

FIPS 140 compliance is required or strongly recommended in many regulated environments where sensitive data must be protected, such as government, healthcare, finance, and defense. These standards ensure that cryptographic operations are performed using vetted, trusted algorithms implemented in secure modules.

Using software components that rely on validated cryptographic modules can help organizations:

* Satisfy federal and industry mandates, such as FedRAMP, which require or strongly recommend FIPS 140-validated cryptography.
* Demonstrate audit readiness, with verifiable evidence of secure, standards-based cryptographic practices.
* Reduce security risk, by blocking unapproved or unsafe algorithms (e.g., MD5) and ensuring consistent behavior across environments.

## [How Docker Hardened Images support FIPS compliance](#how-docker-hardened-images-support-fips-compliance)

While Docker Hardened Images are available to all, the FIPS variant requires a paid Docker Hardened Images subscription.

Docker Hardened Images (DHIs) include variants that use cryptographic modules validated under FIPS 140. These images are intended to help organizations meet compliance requirements by incorporating components that meet the standard.

* FIPS image variants use cryptographic modules that are already validated under FIPS 140.
* These variants are built and maintained by Docker to support environments with regulatory or compliance needs.
* Docker provides signed test attestations that document the use of validated cryptographic modules. These attestations can support internal audits and compliance reporting.
* Entropy sources (random number generation for cryptographic operations) vary by base image. Debian-based images use the OpenSSL entropy source, while Alpine-based images source entropy from the host kernel.

> Note
>
> Using a FIPS image variant helps meet compliance requirements but does not make an application or system fully compliant. Compliance depends on how the image is integrated and used within the broader system.

## [Identify images that support FIPS](#identify-images-that-support-fips)

Docker Hardened Images that support FIPS are marked as **FIPS** compliant in the Docker Hardened Images catalog.

To find DHI repositories with FIPS image variants, [search the catalog](https://docs.docker.com/dhi/how-to/explore/) and:

* Use the **FIPS** filter on the catalog page
* Look for **FIPS** compliant on individual image listings

These indicators help you quickly locate repositories that support FIPS-based compliance needs. Image variants that include FIPS support will have a tag ending with `-fips`, such as `3.13-fips`.

## [Use a FIPS variant](#use-a-fips-variant)

To use a FIPS variant, you must [mirror](https://docs.docker.com/dhi/how-to/mirror/) the repository and then pull the FIPS image from your mirrored repository.

## [View the FIPS attestation](#view-the-fips-attestation)

The FIPS variants of Docker Hardened Images contain a FIPS attestation that lists the actual cryptographic modules included in the image.

You can retrieve and inspect the FIPS attestation using the Docker Scout CLI:

```console
$ docker scout attest get \
  --predicate-type https://docker.com/dhi/fips/v0.1 \
  --predicate \
  dhi.io/<image>:<tag>
```

For example:

```console
$ docker scout attest get \
  --predicate-type https://docker.com/dhi/fips/v0.1 \
  --predicate \
  dhi.io/python:3.13-fips
```

The attestation output is a JSON array describing the cryptographic modules included in the image and their compliance status. For example:

```json
[
  {
    "certification": "CMVP #4985",
    "certificationUrl": "https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4985",
    "name": "OpenSSL FIPS Provider",
    "package": "pkg:dhi/openssl-provider-fips@3.1.2",
    "standard": "FIPS 140-3",
    "status": "active",
    "sunsetDate": "2030-03-10",
    "version": "3.1.2"
  }
]
```

----
url: https://docs.docker.com/reference/cli/docker/plugin/disable/
----

# docker plugin disable

***

| Description | Disable a plugin                         |
| ----------- | ---------------------------------------- |
| Usage       | `docker plugin disable [OPTIONS] PLUGIN` |

## [Description](#description)

Disables a plugin. The plugin must be installed before it can be disabled, see [`docker plugin install`](/reference/cli/docker/plugin/install/). Without the `-f` option, a plugin that has references (e.g., volumes, networks) cannot be disabled.

## [Options](#options)

| Option        | Default | Description                           |
| ------------- | ------- | ------------------------------------- |
| `-f, --force` |         | Force the disable of an active plugin |

## [Examples](#examples)

The following example shows that the `sample-volume-plugin` plugin is installed and enabled:

```console
$ docker plugin ls

ID            NAME                                    DESCRIPTION                ENABLED
69553ca1d123  tiborvass/sample-volume-plugin:latest   A test plugin for Docker   true
```

To disable the plugin, use the following command:

```console
$ docker plugin disable tiborvass/sample-volume-plugin

tiborvass/sample-volume-plugin

$ docker plugin ls

ID            NAME                                    DESCRIPTION                ENABLED
69553ca1d123  tiborvass/sample-volume-plugin:latest   A test plugin for Docker   false
```

----
url: https://docs.docker.com/guides/testcontainers-java-micronaut-kafka/
----

# Testing Micronaut Kafka Listener using Testcontainers

Table of contents

***

Learn how to create a Micronaut application with a Kafka listener that persists data in MySQL, then test it using Testcontainers Kafka and MySQL modules with Awaitility.

**Time to complete** 25 minutes

In this guide, you'll learn how to:

* Create a Micronaut application with Kafka integration
* Implement a Kafka listener and persist data in a MySQL database
* Test the Kafka listener using Testcontainers and Awaitility

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-micronaut-kafka/create-project/)

   Set up a Micronaut project with Kafka, Micronaut Data JPA, and MySQL.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-micronaut-kafka/write-tests/)

   Test the Micronaut Kafka listener using Testcontainers Kafka and MySQL modules with Awaitility.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-micronaut-kafka/run-tests/)

   Run your Testcontainers-based Micronaut Kafka integration tests and explore next steps.

----
url: https://docs.docker.com/engine/security/rootless/tips/
----

# Tips

***

Table of contents

***

## [Advanced usage](#advanced-usage)

### [Daemon](#daemon)

The systemd unit file is installed as `~/.config/systemd/user/docker.service`.

Use `systemctl --user` to manage the lifecycle of the daemon:

```console
$ systemctl --user start docker
```

To launch the daemon on system startup, enable the systemd service and lingering:

```console
$ systemctl --user enable docker
$ sudo loginctl enable-linger $(whoami)
```

Starting Rootless Docker as a systemd-wide service (`/etc/systemd/system/docker.service`) is not supported, even with the `User=` directive.

To run the daemon directly without systemd, you need to run `dockerd-rootless.sh` instead of `dockerd`.

The following environment variables must be set:

* `$HOME`: the home directory
* `$XDG_RUNTIME_DIR`: an ephemeral directory that is only accessible by the expected user, e,g, `~/.docker/run`. The directory should be removed on every host shutdown. The directory can be on tmpfs, however, should not be under `/tmp`. Locating this directory under `/tmp` might be vulnerable to TOCTOU attack.

It's important to note that with directory paths:

* The socket path is set to `$XDG_RUNTIME_DIR/docker.sock` by default. `$XDG_RUNTIME_DIR` is typically set to `/run/user/$UID`.
* The data dir is set to `~/.local/share/docker` by default. The data dir should not be on NFS.
* The daemon config dir is set to `~/.config/docker` by default. This directory is different from `~/.docker` that is used by the client.

### [Client](#client)

Since Docker Engine v23.0, `dockerd-rootless-setuptool.sh install` automatically configures the `docker` CLI to use the `rootless` context.

Prior to Docker Engine v23.0, a user had to specify either the socket path or the CLI context explicitly.

To specify the socket path using `$DOCKER_HOST`:

```console
$ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock
$ docker run -d -p 8080:80 nginx
```

To specify the CLI context using `docker context`:

```console
$ docker context use rootless
rootless
Current context is now "rootless"
$ docker run -d -p 8080:80 nginx
```

## [Best practices](#best-practices)

### [Rootless Docker in Docker](#rootless-docker-in-docker)

To run Rootless Docker inside "rootful" Docker, use the `docker:<version>-dind-rootless` image instead of `docker:<version>-dind`.

```console
$ docker run -d --name dind-rootless --privileged docker:25.0-dind-rootless
```

The `docker:<version>-dind-rootless` image runs as a non-root user (UID 1000). However, `--privileged` is required for disabling seccomp, AppArmor, and mount masks.

### [Expose Docker API socket through TCP](#expose-docker-api-socket-through-tcp)

To expose the Docker API socket through TCP, you need to launch `dockerd-rootless.sh` with `DOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS="-p 0.0.0.0:2376:2376/tcp"`.

```console
$ DOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS="-p 0.0.0.0:2376:2376/tcp" \
  dockerd-rootless.sh \
  -H tcp://0.0.0.0:2376 \
  --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem
```

### [Expose Docker API socket through SSH](#expose-docker-api-socket-through-ssh)

To expose the Docker API socket through SSH, you need to make sure `$DOCKER_HOST` is set on the remote host.

```console
$ ssh -l REMOTEUSER REMOTEHOST 'echo $DOCKER_HOST'
unix:///run/user/1001/docker.sock
$ docker -H ssh://REMOTEUSER@REMOTEHOST run ...
```

### [Routing ping packets](#routing-ping-packets)

On some distributions, `ping` does not work by default.

Add `net.ipv4.ping_group_range = 0 2147483647` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl --system` to allow using `ping`.

### [Exposing privileged ports](#exposing-privileged-ports)

To expose privileged ports (< 1024), set `CAP_NET_BIND_SERVICE` on `rootlesskit` binary and restart the daemon.

```console
$ sudo setcap cap_net_bind_service=ep $(which rootlesskit)
$ systemctl --user restart docker
```

Or add `net.ipv4.ip_unprivileged_port_start=0` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl --system`.

### [Limiting resources](#limiting-resources)

Limiting resources with cgroup-related `docker run` flags such as `--cpus`, `--memory`, `--pids-limit` is supported only when running with cgroup v2 and systemd. See [Changing cgroup version](https://docs.docker.com/engine/containers/runmetrics/) to enable cgroup v2.

If `docker info` shows `none` as `Cgroup Driver`, the conditions are not satisfied. When these conditions are not satisfied, rootless mode ignores the cgroup-related `docker run` flags. See [Limiting resources without cgroup](#limiting-resources-without-cgroup) for workarounds.

If `docker info` shows `systemd` as `Cgroup Driver`, the conditions are satisfied. However, typically, only `memory` and `pids` controllers are delegated to non-root users by default.

```console
$ cat /sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/cgroup.controllers
memory pids
```

To allow delegation of all controllers, you need to change the systemd configuration as follows:

```console
# mkdir -p /etc/systemd/system/user@.service.d
# cat > /etc/systemd/system/user@.service.d/delegate.conf << EOF
[Service]
Delegate=cpu cpuset io memory pids
EOF
# systemctl daemon-reload
```

> Note
>
> Delegating `cpuset` requires systemd 244 or later.

#### [Limiting resources without cgroup](#limiting-resources-without-cgroup)

Even when cgroup is not available, you can still use the traditional `ulimit` and [`cpulimit`](https://github.com/opsengine/cpulimit), though they work in process-granularity rather than in container-granularity, and can be arbitrarily disabled by the container process.

For example:

* To limit CPU usage to 0.5 cores (similar to `docker run --cpus 0.5`): `docker run <IMAGE> cpulimit --limit=50 --include-children <COMMAND>`

* To limit max VSZ to 64MiB (similar to `docker run --memory 64m`): `docker run <IMAGE> sh -c "ulimit -v 65536; <COMMAND>"`

* To limit max number of processes to 100 per namespaced UID 2000 (similar to `docker run --pids-limit=100`): `docker run --user 2000 --ulimit nproc=100 <IMAGE> <COMMAND>`

----
url: https://docs.docker.com/guides/python/lint-format-typing/
----

# Linting, formatting, and type checking for Python

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Develop your app](https://docs.docker.com/guides/python/develop/).

## [Overview](#overview)

In this section, you'll learn how to set up code quality tools for your Python application. This includes:

* Linting and formatting with Ruff
* Static type checking with Pyright
* Automating checks with pre-commit hooks

## [Linting and formatting with Ruff](#linting-and-formatting-with-ruff)

Ruff is an extremely fast Python linter and formatter written in Rust. It replaces multiple tools like flake8, isort, and black with a single unified tool.

Before using Ruff, install it in your Python environment:

```bash
pip install ruff
```

If you're using a virtual environment, make sure it is activated so the `ruff` command is available when you run the commands below.

Create a `pyproject.toml` file:

```toml
[tool.ruff]
target-version = "py312"

[tool.ruff.lint]
select = [
    "E",  # pycodestyle errors
    "W",  # pycodestyle warnings
    "F",  # pyflakes
    "I",  # isort
    "B",  # flake8-bugbear
    "C4",  # flake8-comprehensions
    "UP",  # pyupgrade
    "ARG001", # unused arguments in functions
]
ignore = [
    "E501",  # line too long, handled by black
    "B008",  # do not perform function calls in argument defaults
    "W191",  # indentation contains tabs
    "B904",  # Allow raising exceptions without from e, for HTTPException
]
```

### [Using Ruff](#using-ruff)

Run these commands to check and format your code:

```bash
# Check for errors
ruff check .

# Automatically fix fixable errors
ruff check --fix .

# Format code
ruff format .
```

## [Type checking with Pyright](#type-checking-with-pyright)

Pyright is a fast static type checker for Python that works well with modern Python features.

Add `Pyright` configuration in `pyproject.toml`:

```toml
[tool.pyright]
typeCheckingMode = "strict"
pythonVersion = "3.12"
exclude = [".venv"]
```

### [Running Pyright](#running-pyright)

To check your code for type errors:

```bash
pyright
```

## [Setting up pre-commit hooks](#setting-up-pre-commit-hooks)

Pre-commit hooks automatically run checks before each commit. The following `.pre-commit-config.yaml` snippet sets up Ruff:

```yaml
  https: https://github.com/charliermarsh/ruff-pre-commit
  rev: v0.2.2
  hooks:
    - id: ruff
      args: [--fix]
    - id: ruff-format
```

To install and use:

```bash
pre-commit install
git commit -m "Test commit"  # Automatically runs checks
```

## [Summary](#summary)

In this section, you learned how to:

* Configure and use Ruff for linting and formatting
* Set up Pyright for static type checking
* Automate checks with pre-commit hooks

These tools help maintain code quality and catch errors early in development.

## [Next steps](#next-steps)

* [Configure GitHub Actions](https://docs.docker.com/guides/python/configure-github-actions/) to run these checks automatically
* Customize linting rules to match your team's style preferences
* Explore advanced type checking features

[Automate your builds with GitHub Actions »](https://docs.docker.com/guides/python/configure-github-actions/)

----
url: https://docs.docker.com/build-cloud/ci/
----

# Use Docker Build Cloud in CI

***

Table of contents

***

Using Docker Build Cloud in CI can speed up your build pipelines, which means less time spent waiting and context switching. You control your CI workflows as usual, and delegate the build execution to Docker Build Cloud.

Building with Docker Build Cloud in CI involves the following steps:

1. Sign in to a Docker account.
2. Set up Buildx and connect to the builder.
3. Run the build.

When using Docker Build Cloud in CI, it's recommended that you push the result to a registry directly, rather than loading the image and then pushing it. Pushing directly speeds up your builds and avoids unnecessary file transfers.

If you just want to build and discard the output, export the results to the build cache or build without tagging the image. When you use Docker Build Cloud, Buildx automatically loads the build result if you build a tagged image. See [Loading build results](https://docs.docker.com/build-cloud/usage/#loading-build-results) for details.

> Note
>
> Builds on Docker Build Cloud have a timeout limit of 90 minutes. Builds that run for longer than 90 minutes are automatically cancelled.

## [Setting up credentials for CI/CD](#setting-up-credentials-for-cicd)

To enable your CI/CD system to build and push images using Docker Build Cloud, provide both an access token and a username. The type of token and the username you use depend on your account type and permissions.

* If you are an organization administrator or have permission to create [organization access tokens (OAT)](https://docs.docker.com/enterprise/security/access-tokens/), use an OAT and set `DOCKER_ACCOUNT` to your Docker Hub organization name.
* If you do not have permission to create OATs or are using a personal account, use a [personal access token (PAT)](/security/access-tokens/) and set `DOCKER_ACCOUNT` to your Docker Hub username.

### [Creating access tokens](#creating-access-tokens)

#### [For organization accounts](#for-organization-accounts)

If you are an organization administrator:

* Create an [organization access token (OAT)](https://docs.docker.com/enterprise/security/access-tokens/). The token must have these permissions:

  1. **cloud-connect** scope

  2. **Read public repositories** permission

  3. **Repository access** with **Image push** permission for the target repository:

     * Expand the **Repository** drop-down.
     * Select **Add repository** and choose your target repository.
     * Set the **Image push** permission for the repository.

If you are not an organization administrator:

* Ask your organization administrator for an access token with the permissions listed above, or use a personal access token.

#### [For personal accounts](#for-personal-accounts)

* Create a [personal access token (PAT)](/security/access-tokens/) with the following permissions:
  1. **Read & write** access.
     * Note: Building with Docker Build Cloud only requires read access, but you need write access to push images to a Docker Hub repository.

## [CI platform examples](#ci-platform-examples)

> Note
>
> In your CI/CD configuration, set the following variables/secrets:
>
> * `DOCKER_ACCESS_TOKEN` — your access token (PAT or OAT). Use a secret to store the token.
> * `DOCKER_ACCOUNT` — your Docker Hub organization name (for OAT) or username (for PAT)
> * `CLOUD_BUILDER_NAME` — the name of the cloud builder you created in the [Docker Build Cloud Dashboard](https://app.docker.com/build/)
>
> This ensures your builds authenticate correctly with Docker Build Cloud.

### [GitHub Actions](#github-actions)

```yaml
name: ci

on:
  push:
    branches:
      - "main"

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKER_ACCOUNT }}
          password: ${{ secrets.DOCKER_ACCESS_TOKEN }}
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
        with:
          driver: cloud
          endpoint: "${{ vars.DOCKER_ACCOUNT }}/${{ vars.CLOUD_BUILDER_NAME }}" # for example, "acme/default"
      
      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          tags: "IMAGE" # for example, "acme/my-image:latest"
          # For pull requests, export results to the build cache.
          # Otherwise, push to a registry.
          outputs: ${{ github.event_name == 'pull_request' && 'type=cacheonly' || 'type=registry' }}
```

The example above uses `docker/build-push-action`, which automatically uses the builder set up by `setup-buildx-action`. If you need to use the `docker build` command directly instead, you have two options:

* Use `docker buildx build` instead of `docker build`

* Set the `BUILDX_BUILDER` environment variable to use the cloud builder:

  ```yaml
  - name: Set up Docker Buildx
    id: builder
    uses: docker/setup-buildx-action@v4
    with:
      driver: cloud
      endpoint: "${{ vars.DOCKER_ACCOUNT }}/${{ vars.CLOUD_BUILDER_NAME }}"

  - name: Build
    run: |
      docker build .
    env:
      BUILDX_BUILDER: ${{ steps.builder.outputs.name }}
  ```

For more information about the `BUILDX_BUILDER` environment variable, see [Build variables](https://docs.docker.com/build/building/variables/#buildx_builder).

### [GitLab](#gitlab)

```yaml
default:
  image: docker:24-dind
  services:
    - docker:24-dind
  before_script:
    - docker info
    - echo "$DOCKER_ACCESS_TOKEN" | docker login --username "$DOCKER_ACCOUNT" --password-stdin
    - |
      apk add curl jq
      ARCH=${CI_RUNNER_EXECUTABLE_ARCH#*/}
      BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
      mkdir -vp ~/.docker/cli-plugins/
      curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
      chmod a+x ~/.docker/cli-plugins/docker-buildx
    - docker buildx create --use --driver cloud ${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}

variables:
  IMAGE_NAME: IMAGE
  DOCKER_ACCOUNT: DOCKER_ACCOUNT # your Docker Hub organization name (or username when using a personal account)
  CLOUD_BUILDER_NAME: CLOUD_BUILDER_NAME # the name of the cloud builder you created in the [Docker Build Cloud Dashboard](https://app.docker.com/build/)

# Build multi-platform image and push to a registry
build_push:
  stage: build
  script:
    - |
      docker buildx build \
        --platform linux/amd64,linux/arm64 \
        --tag "${IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}" \
        --push .

# Build an image and discard the result
build_cache:
  stage: build
  script:
    - |
      docker buildx build \
        --platform linux/amd64,linux/arm64 \
        --tag "${IMAGE_NAME}:${CI_COMMIT_SHORT_SHA}" \
        --output type=cacheonly \
        .
```

### [Circle CI](#circle-ci)

```yaml
version: 2.1

jobs:
  # Build multi-platform image and push to a registry
  build_push:
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout

      - run: |
          mkdir -vp ~/.docker/cli-plugins/
          ARCH=amd64
          BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
          curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
          chmod a+x ~/.docker/cli-plugins/docker-buildx

      - run: echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ --password-stdin
      - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

      - run: |
          docker buildx build \
          --platform linux/amd64,linux/arm64 \
          --push \
          --tag "IMAGE" .

  # Build an image and discard the result
  build_cache:
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout

      - run: |
          mkdir -vp ~/.docker/cli-plugins/
          ARCH=amd64
          BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
          curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
          chmod a+x ~/.docker/cli-plugins/docker-buildx

      - run: echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ --password-stdin
      - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

      - run: |
          docker buildx build \
          --tag temp \
          --output type=cacheonly \
          .

workflows:
  pull_request:
    jobs:
      - build_cache
  release:
    jobs:
      - build_push
```

### [Buildkite](#buildkite)

The following example sets up a Buildkite pipeline using Docker Build Cloud. The example assumes that the pipeline name is `build-push-docker` and that you manage the Docker access token using environment hooks, but feel free to adapt this to your needs.

Add the following `environment` hook agent's hook directory:

```bash
#!/bin/bash
set -euo pipefail

if [[ "$BUILDKITE_PIPELINE_NAME" == "build-push-docker" ]]; then
 export DOCKER_ACCESS_TOKEN="DOCKER_ACCESS_TOKEN"
fi
```

Create a `pipeline.yml` that uses the `docker-login` plugin:

```yaml
env:
  DOCKER_ACCOUNT: DOCKER_ACCOUNT # your Docker Hub organization name (or username when using a personal account)
  CLOUD_BUILDER_NAME: CLOUD_BUILDER_NAME # the name of the cloud builder you created in the [Docker Build Cloud Dashboard](https://app.docker.com/build/)
  IMAGE_NAME: IMAGE

steps:
  - command: ./build.sh
    key: build-push
    plugins:
      - docker-login#v2.1.0:
          username: DOCKER_ACCOUNT
          password-env: DOCKER_ACCESS_TOKEN # the variable name in the environment hook
```

Create the `build.sh` script:

```bash
DOCKER_DIR=/usr/libexec/docker

# Get download link for latest buildx binary.
# Set $ARCH to the CPU architecture (e.g. amd64, arm64)
UNAME_ARCH=`uname -m`
case $UNAME_ARCH in
  aarch64)
    ARCH="arm64";
    ;;
  amd64)
    ARCH="amd64";
    ;;
  *)
    ARCH="amd64";
    ;;
esac
BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")

# Download docker buildx with Build Cloud support
curl --silent -L --output $DOCKER_DIR/cli-plugins/docker-buildx $BUILDX_URL
chmod a+x ~/.docker/cli-plugins/docker-buildx

# Connect to your builder and set it as the default builder
docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

# Cache-only image build
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --tag "$IMAGE_NAME:$BUILDKITE_COMMIT" \
    --output type=cacheonly \
    .

# Build, tag, and push a multi-arch docker image
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --push \
    --tag "$IMAGE_NAME:$BUILDKITE_COMMIT" \
    .
```

### [Jenkins](#jenkins)

```groovy
pipeline {
  agent any

  environment {
    ARCH = 'amd64'
    DOCKER_ACCESS_TOKEN = credentials('docker-access-token')
    DOCKER_ACCOUNT = credentials('docker-account')
    CLOUD_BUILDER_NAME = 'CLOUD_BUILDER_NAME'
    IMAGE_NAME = 'IMAGE'
  }

  stages {
    stage('Build') {
      environment {
        BUILDX_URL = sh (returnStdout: true, script: 'curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\\"linux-$ARCH\\"))"').trim()
      }
      steps {
        sh 'mkdir -vp ~/.docker/cli-plugins/'
        sh 'curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL'
        sh 'chmod a+x ~/.docker/cli-plugins/docker-buildx'
        sh 'echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin'
        sh 'docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"'
        // Cache-only build
        sh 'docker buildx build --platform linux/amd64,linux/arm64 --tag "$IMAGE_NAME" --output type=cacheonly .'
        // Build and push a multi-platform image
        sh 'docker buildx build --platform linux/amd64,linux/arm64 --push --tag "$IMAGE_NAME" .'
      }
    }
  }
}
```

### [Travis CI](#travis-ci)

```yaml
language: minimal 
dist: jammy 

services:
  - docker

env:
  global:
    - IMAGE_NAME=IMAGE # for example, "acme/my-image:latest"

before_install: |
  echo "$DOCKER_ACCESS_TOKEN" | docker login --username "$DOCKER_ACCOUNT" --password-stdin

install: |
  set -e 
  BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$TRAVIS_CPU_ARCH\"))")
  mkdir -vp ~/.docker/cli-plugins/
  curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
  chmod a+x ~/.docker/cli-plugins/docker-buildx
  docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

script: |
  docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --push \
  --tag "$IMAGE_NAME" .
```

### [BitBucket Pipelines](#bitbucket-pipelines)

```yaml
# Prerequisites: $DOCKER_ACCOUNT, $CLOUD_BUILDER_NAME, $DOCKER_ACCESS_TOKEN setup as deployment variables
# This pipeline assumes $BITBUCKET_REPO_SLUG as the image name

image: atlassian/default-image:3

pipelines:
  default:
    - step:
        name: Build multi-platform image
        script:
          - mkdir -vp ~/.docker/cli-plugins/
          - ARCH=amd64
          - BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
          - curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
          - chmod a+x ~/.docker/cli-plugins/docker-buildx
          - echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
          - docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
          - IMAGE_NAME=$BITBUCKET_REPO_SLUG
          - docker buildx build
            --platform linux/amd64,linux/arm64
            --push
            --tag "$IMAGE_NAME" .
        services:
          - docker
```

### [Shell script](#shell-script)

```bash
#!/bin/bash

# Get download link for latest buildx binary. Set $ARCH to the CPU architecture (e.g. amd64, arm64)
ARCH=amd64
BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")

# Download docker buildx with Build Cloud support
mkdir -vp ~/.docker/cli-plugins/
curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
chmod a+x ~/.docker/cli-plugins/docker-buildx

# Login to Docker Hub with an access token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin

# Connect to your builder and set it as the default builder
docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

# Cache-only image build
docker buildx build \
    --tag temp \
    --output type=cacheonly \
    .

# Build, tag, and push a multi-arch docker image
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --push \
    --tag "IMAGE" \
    .
```

### [Docker Compose](#docker-compose)

Use this implementation if you want to use `docker compose build` with Docker Build Cloud in CI.

```bash
#!/bin/bash

# Get download link for latest buildx binary. Set $ARCH to the CPU architecture (e.g. amd64, arm64)
ARCH=amd64
BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
COMPOSE_URL=$(curl -sL \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/docker/compose-desktop/releases \
  | jq "[ .[] | select(.prerelease==false and .draft==false) ] | .[0].assets.[] | select(.name | endswith(\"linux-${ARCH}\")) | .browser_download_url")

# Download docker buildx with Build Cloud support
mkdir -vp ~/.docker/cli-plugins/
curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
curl --silent -L --output ~/.docker/cli-plugins/docker-compose $COMPOSE_URL
chmod a+x ~/.docker/cli-plugins/docker-buildx
chmod a+x ~/.docker/cli-plugins/docker-compose

# Login to Docker Hub with an access token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin

# Connect to your builder and set it as the default builder
docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"

# Build the image build
docker compose build
```

----
url: https://docs.docker.com/docker-hub/image-library/catalogs/
----

# Docker Hub catalogs

***

Table of contents

***

Docker Hub catalogs are your go-to collections of trusted, ready-to-use container images and resources, tailored to meet specific development needs. They make it easier to find high-quality, pre-verified content so you can quickly build, deploy, and manage your applications with confidence. Catalogs in Docker Hub:

* Simplify content discovery: Organized and curated content makes it easy to discover tools and resources tailored to your specific domain or technology.
* Reduce complexity: Trusted resources, vetted by Docker and its partners, ensure security, reliability, and adherence to best practices.
* Accelerate development: Quickly integrate advanced capabilities into your applications without the hassle of extensive research or setup.

The following sections provide an overview of the key catalogs available in Docker Hub.

## [MCP Catalog](#mcp-catalog)

The [MCP Catalog](https://hub.docker.com/mcp/) is a centralized, trusted registry for discovering, sharing, and running Model Context Protocol (MCP)-compatible tools. Seamlessly integrated into Docker Hub, the catalog includes:

* Over 100 verified MCP servers packaged as Docker images
* Tools from partners such as New Relic, Stripe, and Grafana
* Versioned releases with publisher verification
* Simplified pull-and-run support through Docker Desktop and Docker CLI

Each server runs in an isolated container to ensure consistent behavior and minimize configuration headaches. For developers working with Claude Desktop or other MCP clients, the catalog provides an easy way to extend functionality with drop-in tools.

To learn more about MCP servers, see [MCP Catalog and Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/).

## [AI Models Catalog](#ai-models-catalog)

The [AI Models Catalog](https://hub.docker.com/catalogs/models/) provides curated, trusted models that work with [Docker Model Runner](https://docs.docker.com/ai/model-runner/). This catalog is designed to make AI development more accessible by offering pre-packaged, ready-to-use models that you can pull, run, and interact with using familiar Docker tools.

With the AI Models Catalog and Docker Model Runner, you can:

* Pull and serve models from Docker Hub or any OCI-compliant registry
* Interact with models via OpenAI-compatible APIs
* Run and test models locally using Docker Desktop or CLI
* Package and publish models using the `docker model` CLI

Whether you're building generative AI applications, integrating LLMs into your workflows, or experimenting with machine learning tools, the AI Models Catalog simplifies the model management experience.

----
url: https://docs.docker.com/reference/cli/sbx/version/
----

# sbx version

| Description | Show Docker Sandboxes version information |
| ----------- | ----------------------------------------- |
| Usage       | `sbx version`                             |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/guides/nextjs/configure-github-actions/
----

# Automate your builds with GitHub Actions

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize Next.js application](https://docs.docker.com/guides/nextjs/containerize/).

You must also have:

* A [GitHub](https://github.com/signup) account.
* A verified [Docker Hub](https://hub.docker.com/signup) account.

***

## [Overview](#overview)

In this section, you'll set up a CI/CD pipeline using [GitHub Actions](https://docs.github.com/en/actions) to automatically:

* Build your Next.js application inside a Docker container.
* Run tests in a consistent environment.
* Push the production-ready image to [Docker Hub](https://hub.docker.com).

***

## [Integrate GitHub and Docker Hub](#integrate-github-and-docker-hub)

To enable GitHub Actions to build and push Docker images, you'll securely store your Docker Hub credentials in your new GitHub repository.

### [Step 1: Connect your GitHub repository to Docker Hub](#step-1-connect-your-github-repository-to-docker-hub)

1. Create a Personal Access Token (PAT) from [Docker Hub](https://hub.docker.com)

   1. Go to your **Docker Hub account → Account Settings → Security**.
   2. Generate a new Access Token with **Read/Write** permissions.
   3. Name it something like `nextjs-sample`.
   4. Copy and save the token — you'll need it in Step 4.

2. Create a repository in [Docker Hub](https://hub.docker.com/repositories/)

   1. Go to your **Docker Hub account → Create a repository**.
   2. For the Repository Name, use something descriptive — for example: `nextjs-sample`.
   3. Once created, copy and save the repository name — you'll need it in Step 4.

3. Create a new [GitHub repository](https://github.com/new) for your Next.js project

4. Add Docker Hub credentials as GitHub repository secrets

   In your newly created GitHub repository:

   1. Navigate to: **Settings → Secrets and variables → Actions → New repository secret**.

   2. Add the following secrets:

   | Name                     | Value                                            |
   | ------------------------ | ------------------------------------------------ |
   | `DOCKER_USERNAME`        | Your Docker Hub username                         |
   | `DOCKERHUB_TOKEN`        | Your Docker Hub access token (created in Step 1) |
   | `DOCKERHUB_PROJECT_NAME` | Your Docker Project Name (created in Step 2)     |

   These secrets let GitHub Actions authenticate securely with Docker Hub during automated workflows.

5. Connect Your Local Project to GitHub

   Link your local project to the GitHub repository you just created by running the following command from your project root:

   ```console
      $ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git
   ```

   > Important
   >
   > Replace `{your-username}` and `{your-repository}` with your actual GitHub username and repository name.

   To confirm that your local project is correctly connected to the remote GitHub repository, run:

   ```console
   $ git remote -v
   ```

   You should see output similar to:

   ```console
   origin  https://github.com/{your-username}/{your-repository-name}.git (fetch)
   origin  https://github.com/{your-username}/{your-repository-name}.git (push)
   ```

   This confirms that your local repository is properly linked and ready to push your source code to GitHub.

6. Push Your Source Code to GitHub

   Follow these steps to commit and push your local project to your GitHub repository:

   1. Stage all files for commit.

      ```console
      $ git add -A
      ```

      This command stages all changes — including new, modified, and deleted files — preparing them for commit.

   2. Commit your changes.

      ```console
      $ git commit -m "Initial commit"
      ```

      This command creates a commit that snapshots the staged changes with a descriptive message.

   3. Push the code to the `main` branch.

      ```console
      $ git push -u origin main
      ```

      This command pushes your local commits to the `main` branch of the remote GitHub repository and sets the upstream branch.

Once completed, your code will be available on GitHub, and any GitHub Actions workflow you've configured will run automatically.

> Note
>
> Learn more about the Git commands used in this step:
>
> * [Git add](https://git-scm.com/docs/git-add) – Stage changes (new, modified, deleted) for commit
> * [Git commit](https://git-scm.com/docs/git-commit) – Save a snapshot of your staged changes
> * [Git push](https://git-scm.com/docs/git-push) – Upload local commits to your GitHub repository
> * [Git remote](https://git-scm.com/docs/git-remote) – View and manage remote repository URLs

***

### [Step 2: Set up the workflow](#step-2-set-up-the-workflow)

Now you'll create a GitHub Actions workflow that builds your Docker image, runs tests, and pushes the image to Docker Hub.

1. Go to your repository on GitHub and select the **Actions** tab in the top menu.

2. Select **Set up a workflow yourself** when prompted.

   This opens an inline editor to create a new workflow file. By default, it will be saved to: `.github/workflows/main.yml`

3. Add the following workflow configuration to the new file:

```yaml
# CI/CD – Next.js Application with Docker
# Builds the app, runs tests in a container, and pushes the production image to Docker Hub.

name: CI/CD – Next.js Application with Docker

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

jobs:
  build-test-push:
    name: Build, Test and Push Docker Image
    runs-on: ubuntu-latest

    steps:
      # 1. Checkout source code
      - name: Checkout source code
        uses: actions/checkout@v5
        with:
          fetch-depth: 0

      # 2. Set up Docker Buildx
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      # 3. Cache Docker layers
      - name: Cache Docker layers
        uses: actions/cache@v5
        with:
          path: /tmp/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: ${{ runner.os }}-buildx-

      # 4. Cache pnpm dependencies
      - name: Cache pnpm dependencies
        uses: actions/cache@v4
        with:
          path: ~/.local/share/pnpm/store
          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: ${{ runner.os }}-pnpm-

      # 5. Extract metadata
      - name: Extract metadata
        id: meta
        run: |
          echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT"
          echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"

      # 6. Build dev Docker image (for running tests)
      - name: Build Docker image for tests
        uses: docker/build-push-action@v6
        with:
          context: .
          file: Dockerfile.dev
          tags: ${{ steps.meta.outputs.REPO_NAME }}-dev:latest
          load: true
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache,mode=max

      # 7. Run Vitest tests inside the container
      # Use same package-manager detection as Dockerfile (no corepack at runtime; node user can't write to /usr/local/bin)
      - name: Run tests
        run: |
          docker run --rm \
            --workdir /app \
            --entrypoint "" \
            -e CI=true \
            ${{ steps.meta.outputs.REPO_NAME }}-dev:latest \
            sh -c "if [ -f package-lock.json ]; then npm run test:run; elif [ -f yarn.lock ]; then yarn test:run; elif [ -f pnpm-lock.yaml ]; then pnpm run test:run; else npm run test:run; fi"
        env:
          CI: true
          NODE_ENV: test
        timeout-minutes: 10

      # 8. Log in to Docker Hub (only needed for push)
      - name: Log in to Docker Hub
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      # 9. Build and push production image (only on push to main)
      - name: Build and push production image
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        uses: docker/build-push-action@v6
        with:
          context: .
          file: Dockerfile
          push: true
          platforms: linux/amd64,linux/arm64
          tags: |
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }}
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache,mode=max
```

This workflow performs the following tasks for your Next.js application:

* Triggers on every `push` or `pull request` targeting the `main` branch.
* Builds a development Docker image using `Dockerfile.dev`, optimized for testing.
* Executes unit tests using Jest inside a clean, containerized environment to ensure consistency.
* Halts the workflow immediately if any test fails — enforcing code quality.
* Caches both Docker build layers and npm dependencies for faster CI runs.
* Authenticates securely with Docker Hub using GitHub repository secrets.
* Builds a production-ready image using the `Dockerfile`.
* Tags and pushes the final image to Docker Hub with both `latest` and short SHA tags for traceability.

> Note
>
> For more information about `docker/build-push-action`, refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md).

***

     * Repository name: `${your-repository-name}`

     * Tags include:

       * `latest` – represents the most recent successful build; ideal for quick testing or deployment.
       * `<short-sha>` – a unique identifier based on the commit hash, useful for version tracking, rollbacks, and traceability.

> Tip
>
> To maintain code quality and prevent accidental direct pushes, enable branch protection rules:
>
> * Navigate to your **GitHub repo → Settings → Branches**.
>
> * Under Branch protection rules, select **Add rule**.
>
> * Specify `main` as the branch name.
>
> * Enable options like:
>
>   * *Require a pull request before merging*.
>   * *Require status checks to pass before merging*.
>
> This ensures that only tested and reviewed code is merged into `main` branch.

***

## [Summary](#summary)

In this section, you set up a complete CI/CD pipeline for your containerized Next.js application using GitHub Actions.

With this setup, your Next.js application is now ready for automated testing and deployment across environments — increasing confidence, consistency, and team productivity.

***

***

## [Next steps](#next-steps)

Next, learn how you can locally test and debug your Next.js workloads on Kubernetes before deploying. This helps you ensure your application behaves as expected in a production-like environment, reducing surprises during deployment.

[Test your Next.js deployment »](https://docs.docker.com/guides/nextjs/deploy/)

----
url: https://docs.docker.com/engine/release-notes/20.10/
----

# Docker Engine 20.10 release notes

***

Table of contents

***

This document describes the latest changes, additions, known issues, and fixes for Docker Engine version 20.10.

## [20.10.24](#201024)

*2023-04-04*

### [Updates](#updates)

* Update Go runtime to [1.19.7](https://go.dev/doc/devel/release#go1.19.minor).
* Update Docker Buildx to [v0.10.4](https://github.com/docker/buildx/releases/tag/v0.10.4).
* Update containerd to [v1.6.20](https://github.com/containerd/containerd/releases/tag/v1.6.20).
* Update runc to [v1.1.5](https://github.com/opencontainers/runc/releases/tag/v1.1.5).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* Fixed a number of issues that can cause Swarm encrypted overlay networks to fail to uphold their guarantees, addressing [CVE-2023-28841](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28841), [CVE-2023-28840](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28840), and [CVE-2023-28842](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-28842).

  * A lack of kernel support for encrypted overlay networks now reports as an error.
  * Encrypted overlay networks are eagerly set up, rather than waiting for multiple nodes to attach.
  * Encrypted overlay networks are now usable on Red Hat Enterprise Linux 9 through the use of the `xt_bpf` kernel module.
  * Users of Swarm overlay networks should review [GHSA-vwm3-crmr-xfxw](https://github.com/moby/moby/security/advisories/GHSA-vwm3-crmr-xfxw) to ensure that unintentional exposure has not occurred.

* Upgrade github.com/containerd/fifo to v1.1.0 to fix a potential panic [moby/moby#45216](https://github.com/moby/moby/pull/45242).

* Fix missing Bash completion for installed cli-plugins [docker/cli#4091](https://github.com/docker/cli/pull/4091).

## [20.10.23](#201023)

*2023-01-19*

This release of Docker Engine contains updated versions of Docker Compose, Docker Buildx, containerd, and some minor bug fixes and enhancements.

### [Updates](#updates-1)

* Update Docker Compose to [v2.15.1](https://github.com/docker/compose/releases/tag/v2.15.1).
* Update Docker Buildx to [v0.10.0](https://github.com/docker/buildx/releases/tag/v0.10.0).
* Update containerd (`containerd.io` package) to [v1.6.15](https://github.com/containerd/containerd/releases/tag/v1.6.15).
* Update the package versioning format for `docker-compose-cli` to allow distribution version updates [docker/docker-ce-packaging#822](https://github.com/docker/docker-ce-packaging/pull/822).
* Update Go runtime to [1.18.10](https://go.dev/doc/devel/release#go1.18.minor),

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

* Fix an issue where `docker build` would fail when using `--add-host=host.docker.internal:host-gateway` with BuildKit enabled [moby/moby#44650](https://github.com/moby/moby/pull/44650).

* Revert seccomp: block socket calls to `AF_VSOCK` in default profile [moby/moby#44712](https://github.com/moby/moby/pull/44712).

  This change, while favorable from a security standpoint, caused a change in behavior for some use-cases. As such, we are reverting it to ensure stability and compatibility for the affected users.

  However, users of `AF_VSOCK` in containers should recognize that this (special) address family is not currently namespaced in any version of the Linux kernel, and may result in unexpected behavior, like containers communicating directly with host hypervisors.

  Future releases, will filter `AF_VSOCK`. Users who need to allow containers to communicate over the unnamespaced `AF_VSOCK` will need to turn off seccomp confinement or set a custom seccomp profile.

## [20.10.22](#201022)

*2022-12-16*

This release of Docker Engine contains updated versions of Docker Compose, Docker Scan, containerd, and some minor bug fixes and enhancements.

### [Updates](#updates-2)

* Update Docker Compose to [v2.14.1](https://github.com/docker/compose/releases/tag/v2.14.1).
* Update Docker Scan to [v0.23.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.23.0).
* Update containerd (`containerd.io` package) to [v1.6.13](https://github.com/containerd/containerd/releases/tag/v1.6.13), to include a fix for [CVE-2022-23471](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-23471).
* Update Go runtime to [1.18.9](https://go.dev/doc/devel/release#go1.18.minor), to include fixes for [CVE-2022-41716](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-41716), [CVE-2022-41717](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-41717), and [CVE-2022-41720](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-41720).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

* Improve error message when attempting to pull an unsupported image format or OCI artifact [moby/moby#44413](https://github.com/moby/moby/pull/44413), [moby/moby#44569](https://github.com/moby/moby/pull/44569).
* Fix an issue where the host's ephemeral port-range was ignored when selecting random ports for containers [moby/moby#44476](https://github.com/moby/moby/pull/44476).
* Fix `ssh: parse error in message type 27` errors during `docker build` on hosts using OpenSSH 8.9 or above [moby/moby#3862](https://github.com/moby/moby/pull/3862).
* seccomp: block socket calls to `AF_VSOCK` in default profile [moby/moby#44564](https://github.com/moby/moby/pull/44564).

## [20.10.21](#201021)

*2022-10-25*

This release of Docker Engine contains updated versions of Docker Compose, Docker Scan, containerd, added packages for Ubuntu 22.10, and some minor bug fixes and enhancements.

### [New](#new)

* Provide packages for Ubuntu 22.10 (Kinetic Kudu).
* Add support for `allow-nondistributable-artifacts` towards Docker Hub [moby/moby#44313](https://github.com/moby/moby/pull/44313).

### [Updates](#updates-3)

* Update Docker Compose to [v2.12.2](https://github.com/docker/compose/releases/tag/v2.12.2).
* Update Docker Scan to [v0.21.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.21.0).
* Update containerd (`containerd.io` package) to [v1.6.9](https://github.com/containerd/containerd/releases/tag/v1.6.9).
* Update bundled BuildKit version to fix `output clipped, log limit 1MiB reached` errors [moby/moby#44339](https://github.com/moby/moby/pull/44339).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-3)

* Remove experimental gate for `--platform` in bash completion [docker/cli#3824](https://github.com/docker/cli/pull/3824).
* Fix an `Invalid standard handle identifier` panic when registering the Docker Engine as a service from a legacy CLI on Windows [moby/moby#44326](https://github.com/moby/moby/pull/44326).
* Fix running Git commands in Cygwin on Windows [moby/moby#44332](https://github.com/moby/moby/pull/44332).

## [20.10.20](#201020)

*2022-10-18*

This release of Docker Engine contains partial mitigations for a Git vulnerability ([CVE-2022-39253](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-39253)), and has updated handling of `image:tag@digest` image references.

The Git vulnerability allows a maliciously crafted Git repository, when used as a build context, to copy arbitrary filesystem paths into resulting containers/images; this can occur in both the daemon, and in API clients, depending on the versions and tools in use.

The mitigations available in this release and in other consumers of the daemon API are partial and only protect users who build a Git URL context (e.g. `git+protocol://`). As the vulnerability could still be exploited by manually run Git commands that interact with and check out submodules, users should immediately upgrade to a patched version of Git to protect against this vulnerability. Further details are available from the GitHub blog (["Git security vulnerabilities announced"](https://github.blog/2022-10-18-git-security-vulnerabilities-announced/)).

### [Updates](#updates-4)

* Update Docker Compose to [v2.12.0](https://github.com/docker/compose/releases/tag/v2.12.0).
* Updated handling of `image:tag@digest` references. When pulling an image using the `image:tag@digest` ("pull by digest"), image resolution happens through the content-addressable digest and the `image` and `tag` are not used. While this is expected, this could lead to confusing behavior, and could potentially be exploited through social engineering to run an image that is already present in the local image store. Docker now checks if the digest matches the repository name used to pull the image, and otherwise will produce an error.
* Updated handling of `image:tag@digest` references. Refer to the "Daemon" section above for details.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-4)

* Added a mitigation for [CVE-2022-39253](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-39253), when using the classic Builder with a Git URL as the build context.
* Added a mitigation to the classic Builder and updated BuildKit to [v0.8.3-31-gc0149372](https://github.com/moby/buildkit/commit/c014937225cba29cfb1d5161fd134316c0e9bdaa), for [CVE-2022-39253](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-39253).

## [20.10.19](#201019)

*2022-10-14*

This release of Docker Engine comes with some bug-fixes, and an updated version of Docker Compose.

### [Updates](#updates-5)

* Update Docker Compose to [v2.11.2](https://github.com/docker/compose/releases/tag/v2.11.2).
* Update Go runtime to [1.18.7](https://go.dev/doc/devel/release#go1.18.minor), which contains fixes for [CVE-2022-2879](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-2879), [CVE-2022-2880](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-2880), and [CVE-2022-41715](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-41715).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-5)

* Fix an issue that could result in a panic during `docker builder prune` or `docker system prune` [moby/moby#44122](https://github.com/moby/moby/pull/44122).
* Fix a bug where using `docker volume prune` would remove volumes that were still in use if the daemon was running with "live restore" and was restarted [moby/moby#44238](https://github.com/moby/moby/pull/44238).

## [20.10.18](#201018)

*2022-09-09*

This release of Docker Engine comes with a fix for a low-severity security issue, some minor bug fixes, and updated versions of Docker Compose, Docker Buildx, `containerd`, and `runc`.

### [Updates](#updates-6)

* Update Docker Buildx to [v0.9.1](https://github.com/docker/buildx/releases/tag/v0.9.1).
* Update Docker Compose to [v2.10.2](https://github.com/docker/compose/releases/tag/v2.10.2).
* Update containerd (`containerd.io` package) to [v1.6.8](https://github.com/containerd/containerd/releases/tag/v1.6.8).
* Update runc version to [v1.1.4](https://github.com/opencontainers/runc/releases/tag/v1.1.4).
* Update Go runtime to [1.18.6](https://go.dev/doc/devel/release#go1.18.minor), which contains fixes for [CVE-2022-27664](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-27664) and [CVE-2022-32190](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-32190).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-6)

* Add Bash completion for Docker Compose [docker/cli#3752](https://github.com/docker/cli/pull/3752).
* Fix an issue where file-capabilities were not preserved during build [moby/moby#43876](https://github.com/moby/moby/pull/43876).
* Fix an issue that could result in a panic caused by a concurrent map read and map write [moby/moby#44067](https://github.com/moby/moby/pull/44067).
* Fix a security vulnerability relating to supplementary group permissions, which could allow a container process to bypass primary group restrictions within the container [CVE-2022-36109](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-36109), [GHSA-rc4r-wh2q-q6c4](https://github.com/moby/moby/security/advisories/GHSA-rc4r-wh2q-q6c4).
* seccomp: add support for Landlock syscalls in default policy [moby/moby#43991](https://github.com/moby/moby/pull/43991).
* seccomp: update default policy to support new syscalls introduced in kernel 5.12 - 5.16 [moby/moby#43991](https://github.com/moby/moby/pull/43991).
* Fix an issue where cache lookup for image manifests would fail, resulting in a redundant round-trip to the image registry [moby/moby#44109](https://github.com/moby/moby/pull/44109).
* Fix an issue where `exec` processes and healthchecks were not terminated when they timed out [moby/moby#44018](https://github.com/moby/moby/pull/44018).

## [20.10.17](#201017)

*2022-06-06*

This release of Docker Engine comes with updated versions of Docker Compose and the `containerd`, and `runc` components, as well as some minor bug fixes.

### [Updates](#updates-7)

* Update Docker Compose to [v2.6.0](https://github.com/docker/compose/releases/tag/v2.6.0).
* Update containerd (`containerd.io` package) to [v1.6.6](https://github.com/containerd/containerd/releases/tag/v1.6.6), which contains a fix for [CVE-2022-31030](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-31030)
* Update runc version to [v1.1.2](https://github.com/opencontainers/runc/releases/tag/v1.1.2), which contains a fix for [CVE-2022-29162](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-29162).
* Update Go runtime to [1.17.11](https://go.dev/doc/devel/release#go1.17.minor), which contains fixes for [CVE-2022-30634](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-30634), [CVE-2022-30629](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-30629), [CVE-2022-30580](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-30580) and [CVE-2022-29804](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-29804)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-7)

* Remove asterisk from docker commands in zsh completion script [docker/cli#3648](https://github.com/docker/cli/pull/3648).
* Fix Windows port conflict with published ports in host mode for overlay [moby/moby#43644](https://github.com/moby/moby/pull/43644).
* Ensure performance tuning is always applied to libnetwork sandboxes [moby/moby#43683](https://github.com/moby/moby/pull/43683).

## [20.10.16](#201016)

*2022-05-12*

This release of Docker Engine fixes a regression in the Docker CLI builds for macOS, fixes an issue with `docker stats` when using containerd 1.5 and up, and updates the Go runtime to include a fix for [CVE-2022-29526](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-29526).

### [Updates](#updates-8)

* Update golang.org/x/sys dependency which contains a fix for [CVE-2022-29526](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-29526).
* Updated the `golang.org/x/sys` build-time dependency which contains a fix for [CVE-2022-29526](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-29526).
* Updated Go runtime to [1.17.10](https://go.dev/doc/devel/release#go1.17.minor), which contains a fix for [CVE-2022-29526](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-29526).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-8)

* Fixed a regression in binaries for macOS introduced in [20.10.15](#201015), which resulted in a panic [docker/cli#43426](https://github.com/docker/cli/pull/3592).
* Fixed an issue where `docker stats` was showing empty stats when running with containerd 1.5.0 or up [moby/moby#43567](https://github.com/moby/moby/pull/43567).
* Used "weak" dependencies for the `docker scan` CLI plugin, to prevent a "conflicting requests" error when users performed an off-line installation from downloaded RPM packages [docker/docker-ce-packaging#659](https://github.com/docker/docker-ce-packaging/pull/659).

## [20.10.15](#201015)

*2022-05-05*

This release of Docker Engine comes with updated versions of the `compose`, `buildx`, `containerd`, and `runc` components, as well as some minor bug fixes.

### [Updates](#updates-9)

* Update Docker Compose to [v2.5.0](https://github.com/docker/compose/releases/tag/v2.5.0).
* Update Docker Buildx to [v0.8.2](https://github.com/docker/buildx/releases/tag/v0.8.2).
* Update Go runtime to [1.17.9](https://go.dev/doc/devel/release#go1.17.minor).
* Update containerd (`containerd.io` package) to [v1.6.4](https://github.com/containerd/containerd/releases/tag/v1.6.4).
* Update runc version to [v1.1.1](https://github.com/opencontainers/runc/releases/tag/v1.1.1).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-9)

* Use a RWMutex for stateCounter to prevent potential locking congestion [moby/moby#43426](https://github.com/moby/moby/pull/43426).
* Prevent an issue where the daemon was unable to find an available IP-range in some conditions [moby/moby#43360](https://github.com/moby/moby/pull/43360)
* Add packages for CentOS 9 stream and Fedora 36.

### [Known issues](#known-issues)

* We've identified an issue with the [macOS CLI binaries](https://download.docker.com/mac/static/stable/) in the 20.10.15 release. This issue has been resolved in the [20.10.16](#201016) release.

## [20.10.14](#201014)

*2022-03-23*

This release of Docker Engine updates the default inheritable capabilities for containers to address [CVE-2022-24769](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-24769), a new version of the `containerd.io` runtime is also included to address the same issue.

### [Updates](#updates-10)

* Update the default inheritable capabilities.
* Update the default inheritable capabilities for containers used during build.
* Update containerd (`containerd.io` package) to [v1.5.11](https://github.com/containerd/containerd/releases/tag/v1.5.11).
* Update `docker buildx` to [v0.8.1](https://github.com/docker/buildx/releases/tag/v0.8.1).

## [20.10.13](#201013)

*2022-03-10*

This release of Docker Engine contains some bug-fixes and packaging changes, updates to the `docker scan` and `docker buildx` commands, an updated version of the Go runtime, and new versions of the `containerd.io` runtime. Together with this release, we now also provide `.deb` and `.rpm` packages of Docker Compose V2, which can be installed using the (optional) `docker-compose-plugin` package.

### [New](#new-1)

* Provide `.deb` and `.rpm` packages for Docker Compose V2. [Docker Compose v2.3.3](https://github.com/docker/compose/releases/tag/v2.3.3) can now be installed on Linux using the `docker-compose-plugin` packages, which provides the `docker compose` subcommand on the Docker CLI. The Docker Compose plugin can also be installed and run standalone to be used as a drop-in replacement for `docker-compose` (Docker Compose V1) [docker/docker-ce-packaging#638](https://github.com/docker/docker-ce-packaging/pull/638). The `compose-cli-plugin` package can also be used on older version of the Docker CLI with support for CLI plugins (Docker CLI 18.09 and up).
* Provide packages for the upcoming Ubuntu 22.04 "Jammy Jellyfish" LTS release [docker/docker-ce-packaging#645](https://github.com/docker/docker-ce-packaging/pull/645), [docker/containerd-packaging#271](https://github.com/docker/containerd-packaging/pull/271).

### [Updates](#updates-11)

* Updated the bundled version of buildx to [v0.8.0](https://github.com/docker/buildx/releases/tag/v0.8.0).
* Update `docker buildx` to [v0.8.0](https://github.com/docker/buildx/releases/tag/v0.8.0).
* Update `docker scan` (`docker-scan-plugin`) to [v0.17.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.17.0).
* Update containerd (`containerd.io` package) to [v1.5.10](https://github.com/containerd/containerd/releases/tag/v1.5.10).
* Update the bundled runc version to [v1.0.3](https://github.com/opencontainers/runc/releases/tag/v1.0.3).
* Update Golang runtime to Go 1.16.15.
* Updates the fluentd log driver to prevent a potential daemon crash, and prevent containers from hanging when using the `fluentd-async-connect=true` and the remote server is unreachable [moby/moby#43147](https://github.com/moby/moby/pull/43147).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-10)

* Fix a race condition when updating the container's state [moby/moby#43166](https://github.com/moby/moby/pull/43166).
* Update the etcd dependency to prevent the daemon from incorrectly holding file locks [moby/moby#43259](https://github.com/moby/moby/pull/43259)
* Fix detection of user-namespaces when configuring the default `net.ipv4.ping_group_range` sysctl [moby/moby#43084](https://github.com/moby/moby/pull/43084).
* Retry downloading image-manifests if a connection failure happens during image pull [moby/moby#43333](https://github.com/moby/moby/pull/43333).
* Various fixes in command-line reference and API documentation.
* Prevent an OOM when using the "local" logging driver with containers that produce a large amount of log messages [moby/moby#43165](https://github.com/moby/moby/pull/43165).

## [20.10.12](#201012)

2021-12-13

This release of Docker Engine contains changes in packaging only, and provides updates to the `docker scan` and `docker buildx` commands. Versions of `docker scan` before v0.11.0 are not able to detect the [Log4j 2 CVE-2021-44228](https://nvd.nist.gov/vuln/detail/CVE-2021-44228). We are shipping an updated version of `docker scan` in this release to help you scan your images for this vulnerability.

> Note
>
> The `docker scan` command on Linux is currently only supported on x86 platforms. We do not yet provide a package for other hardware architectures on Linux.

The `docker scan` feature is provided as a separate package and, depending on your upgrade or installation method, 'docker scan' may not be updated automatically to the latest version. Use the instructions below to update `docker scan` to the latest version. You can also use these instructions to install, or upgrade the `docker scan` package without upgrading the Docker Engine:

On `.deb` based distributions, such as Ubuntu and Debian:

```console
$ apt-get update && apt-get install docker-scan-plugin
```

On rpm-based distributions, such as CentOS or Fedora:

```console
$ yum install docker-scan-plugin
```

After upgrading, verify you have the latest version of `docker scan` installed:

```console
$ docker scan --accept-license --version
Version:    v0.12.0
Git commit: 1074dd0
Provider:   Snyk (1.790.0 (standalone))
```

[Read our blog post on CVE-2021-44228](https://www.docker.com/blog/apache-log4j-2-cve-2021-44228/) to learn how to use the `docker scan` command to check if images are vulnerable.

### [Packaging](#packaging)

* Update `docker scan` to [v0.12.0](https://github.com/docker/scan-cli-plugin/releases/tag/v0.12.0).
* Update `docker buildx` to [v0.7.1](https://github.com/docker/buildx/releases/tag/v0.7.1).
* Update Golang runtime to Go 1.16.12.

## [20.10.11](#201011)

2021-11-17

> Important
>
> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), HTTP proxies configured through the `$HTTP_PROXY` environment variable are no longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` environment variable for handling requests to `https://` URLs. Refer to [Configure the daemon to use a proxy](https://docs.docker.com/engine/daemon/proxy/) to learn how to configure the Docker Daemon to use a proxy server.

### [Distribution](#distribution)

* Handle ambiguous OCI manifest parsing to mitigate [CVE-2021-41190](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-41190) / [GHSA-mc8v-mgrf-8f4m](https://github.com/opencontainers/distribution-spec/security/advisories/GHSA-mc8v-mgrf-8f4m). See [GHSA-xmmx-7jpf-fx42](https://github.com/moby/moby/security/advisories/GHSA-xmmx-7jpf-fx42) for details.

### [Windows](#windows)

* Fix panic.log file having read-only attribute set [moby/moby#42987](https://github.com/moby/moby/pull/42987).

### [Packaging](#packaging-1)

* Update containerd to [v1.4.12](https://github.com/containerd/containerd/releases/tag/v1.4.12) to mitigate [CVE-2021-41190](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-41190).
* Update Golang runtime to Go 1.16.10.

## [20.10.10](#201010)

2021-10-25

> Important
>
> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), HTTP proxies configured through the `$HTTP_PROXY` environment variable are no longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` environment variable for handling requests to `https://` URLs. Refer to the [HTTP/HTTPS proxy section](https://docs.docker.com/engine/daemon/proxy/) to learn how to configure the Docker Daemon to use a proxy server.

### [Builder](#builder)

* Fix platform-matching logic to fix `docker build` using not finding images in the local image cache on Arm machines when using BuildKit [moby/moby#42954](https://github.com/moby/moby/pull/42954)

### [Runtime](#runtime)

* Add support for `clone3` syscall in the default seccomp policy to support running containers based on recent versions of Fedora and Ubuntu. [moby/moby/#42836](https://github.com/moby/moby/pull/42836).
* Windows: update hcsshim library to fix a bug in sparse file handling in container layers, which was exposed by recent changes in Windows [moby/moby#42944](https://github.com/moby/moby/pull/42944).
* Fix some situations where `docker stop` could hang forever [moby/moby#42956](https://github.com/moby/moby/pull/42956).

### [Swarm](#swarm)

* Fix an issue where updating a service did not roll back on failure [moby/moby#42875](https://github.com/moby/moby/pull/42875).

### [Packaging](#packaging-2)

* Add packages for Ubuntu 21.10 "Impish Indri" and Fedora 35.
* Update `docker scan` to v0.9.0
* Update Golang runtime to Go 1.16.9.

## [20.10.9](#20109)

2021-10-04

This release is a security release with security fixes in the CLI, runtime, as well as updated versions of the containerd.io package.

> Important
>
> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), HTTP proxies configured through the `$HTTP_PROXY` environment variable are no longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` environment variable for handling requests to `https://` URLs. Refer to the [HTTP/HTTPS proxy section](https://docs.docker.com/engine/daemon/proxy/) to learn how to configure the Docker Daemon to use a proxy server.

### [Client](#client)

* [CVE-2021-41092](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-41092) Ensure default auth config has address field set, to prevent credentials being sent to the default registry.

### [Runtime](#runtime-1)

* [CVE-2021-41089](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-41089) Create parent directories inside a chroot during `docker cp` to prevent a specially crafted container from changing permissions of existing files in the host’s filesystem.
* [CVE-2021-41091](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-41091) Lock down file permissions to prevent unprivileged users from discovering and executing programs in `/var/lib/docker`.

### [Packaging](#packaging-3)

> **Known issue**
>
> The `ctr` binary shipping with the static packages of this release is not statically linked, and will not run in Docker images using alpine as a base image. Users can install the `libc6-compat` package, or download a previous version of the `ctr` binary as a workaround. Refer to the containerd ticket related to this issue for more details: [containerd/containerd#5824](https://github.com/containerd/containerd/issues/5824).

* Update Golang runtime to Go 1.16.8, which contains fixes for [CVE-2021-36221](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-36221) and [CVE-2021-39293](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-39293)
* Update static binaries and containerd.io rpm and deb packages to containerd v1.4.11 and runc v1.0.2 to address [CVE-2021-41103](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-41103).
* Update the bundled buildx version to v0.6.3 for rpm and deb packages.

## [20.10.8](#20108)

2021-08-03

> Important
>
> Due to [net/http changes](https://github.com/golang/go/issues/40909) in [Go 1.16](https://golang.org/doc/go1.16#net/http), HTTP proxies configured through the `$HTTP_PROXY` environment variable are no longer used for TLS (`https://`) connections. Make sure you also set an `$HTTPS_PROXY` environment variable for handling requests to `https://` URLs. Refer to the [HTTP/HTTPS proxy section](https://docs.docker.com/engine/daemon/proxy/) to learn how to configure the Docker Daemon to use a proxy server.

### [Deprecation](#deprecation)

* Deprecate support for encrypted TLS private keys. Legacy PEM encryption as specified in RFC 1423 is insecure by design. Because it does not authenticate the ciphertext, it is vulnerable to padding oracle attacks that can let an attacker recover the plaintext. Support for encrypted TLS private keys is now marked as deprecated, and will be removed in an upcoming release. [docker/cli#3219](https://github.com/docker/cli/pull/3219)
* Deprecate Kubernetes stack support. Following the deprecation of [Compose on Kubernetes](https://github.com/docker/compose-on-kubernetes), support for Kubernetes in the `stack` and `context` commands in the Docker CLI is now marked as deprecated, and will be removed in an upcoming release [docker/cli#3174](https://github.com/docker/cli/pull/3174).

### [Client](#client-1)

* Fix `Invalid standard handle identifier` errors on Windows [docker/cli#3132](https://github.com/docker/cli/pull/3132).

### [Rootless](#rootless)

* Avoid `can't open lock file /run/xtables.lock: Permission denied` error on SELinux hosts [moby/moby#42462](https://github.com/moby/moby/pull/42462).
* Disable overlay2 when running with SELinux to prevent permission denied errors [moby/moby#42462](https://github.com/moby/moby/pull/42462).
* Fix `x509: certificate signed by unknown authority` error on openSUSE Tumbleweed [moby/moby#42462](https://github.com/moby/moby/pull/42462).

### [Runtime](#runtime-2)

* Print a warning when using the `--platform` option to pull a single-arch image that does not match the specified architecture [moby/moby#42633](https://github.com/moby/moby/pull/42633).
* Fix incorrect `Your kernel does not support swap memory limit` warning when running with cgroups v2 [moby/moby#42479](https://github.com/moby/moby/pull/42479).
* Windows: Fix a situation where containers were not stopped if `HcsShutdownComputeSystem` returned an `ERROR_PROC_NOT_FOUND` error [moby/moby#42613](https://github.com/moby/moby/pull/42613)

### [Swarm](#swarm-1)

* Fix a possibility where overlapping IP addresses could exist as a result of the node failing to clean up its old loadbalancer IPs [moby/moby#42538](https://github.com/moby/moby/pull/42538)
* Fix a deadlock in log broker ("dispatcher is stopped") [moby/moby#42537](https://github.com/moby/moby/pull/42537)

### [Packaging](#packaging-4)

> **Known issue**
>
> The `ctr` binary shipping with the static packages of this release is not statically linked, and will not run in Docker images using alpine as a base image. Users can install the `libc6-compat` package, or download a previous version of the `ctr` binary as a workaround. Refer to the containerd ticket related to this issue for more details: [containerd/containerd#5824](https://github.com/containerd/containerd/issues/5824).

* Remove packaging for Ubuntu 16.04 "Xenial" and Fedora 32, as they reached EOL [docker/docker-ce-packaging#560](https://github.com/docker/docker-ce-packaging/pull/560)
* Update Golang runtime to Go 1.16.6
* Update the bundled buildx version to v0.6.1 for rpm and deb packages [docker/docker-ce-packaging#562](https://github.com/docker/docker-ce-packaging/pull/562)
* Update static binaries and containerd.io rpm and deb packages to containerd v1.4.9 and runc v1.0.1: [docker/containerd-packaging#241](https://github.com/docker/containerd-packaging/pull/241), [docker/containerd-packaging#245](https://github.com/docker/containerd-packaging/pull/245), [docker/containerd-packaging#247](https://github.com/docker/containerd-packaging/pull/247).

## [20.10.7](#20107)

2021-06-02

### [Client](#client-2)

* Suppress warnings for deprecated cgroups [docker/cli#3099](https://github.com/docker/cli/pull/3099).
* Prevent sending `SIGURG` signals to container on Linux and macOS. The Go runtime (starting with Go 1.14) uses `SIGURG` signals internally as an interrupt to support preemptable syscalls. In situations where the Docker CLI was attached to a container, these interrupts were forwarded to the container. This fix changes the Docker CLI to ignore `SIGURG` signals [docker/cli#3107](https://github.com/docker/cli/pull/3107), [moby/moby#42421](https://github.com/moby/moby/pull/42421).

### [Builder](#builder-1)

* Update BuildKit to version v0.8.3-3-g244e8cde [moby/moby#42448](https://github.com/moby/moby/pull/42448):

  * Transform relative mountpoints for exec mounts in the executor to work around a breaking change in runc v1.0.0-rc94 and up. [moby/buildkit#2137](https://github.com/moby/buildkit/pull/2137).
  * Add retry on image push 5xx errors. [moby/buildkit#2043](https://github.com/moby/buildkit/pull/2043).
  * Fix build-cache not being invalidated when renaming a file that is copied using a `COPY` command with a wildcard. Note that this change invalidates existing build caches for copy commands that use a wildcard. [moby/buildkit#2018](https://github.com/moby/buildkit/pull/2018).
  * Fix build-cache not being invalidated when using mounts [moby/buildkit#2076](https://github.com/moby/buildkit/pull/2076).

* Fix build failures when `FROM` image is not cached when using legacy schema 1 images [moby/moby#42382](https://github.com/moby/moby/pull/42382).

### [Logging](#logging)

* Update the hcsshim SDK to make daemon logs on Windows less verbose [moby/moby#42292](https://github.com/moby/moby/pull/42292).

### [Rootless](#rootless-1)

* Fix capabilities not being honored when an image was built on a daemon with user-namespaces enabled [moby/moby#42352](https://github.com/moby/moby/pull/42352).

### [Networking](#networking)

* Update libnetwork to fix publishing ports on environments with kernel boot parameter `ipv6.disable=1`, and to fix a deadlock causing internal DNS lookups to fail [moby/moby#42413](https://github.com/moby/moby/pull/42413).

### [Contrib](#contrib)

* Update rootlesskit to v0.14.2 to fix a timeout when starting the userland proxy with the `slirp4netns` port driver [moby/moby#42294](https://github.com/moby/moby/pull/42294).
* Fix "Device or resource busy" errors when running docker-in-docker on a rootless daemon [moby/moby#42342](https://github.com/moby/moby/pull/42342).

### [Packaging](#packaging-5)

* Update containerd to v1.4.6, runc v1.0.0-rc95 to address [CVE-2021-30465](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-30465) [moby/moby#42398](https://github.com/moby/moby/pull/42398), [moby/moby#42395](https://github.com/moby/moby/pull/42395), [docker/containerd-packaging#234](https://github.com/docker/containerd-packaging/pull/234)
* Update containerd to v1.4.5, runc v1.0.0-rc94 [moby/moby#42372](https://github.com/moby/moby/pull/42372), [moby/moby#42388](https://github.com/moby/moby/pull/42388), [docker/containerd-packaging#232](https://github.com/docker/containerd-packaging/pull/232).
* Update Docker Scan plugin packages (`docker-scan-plugin`) to v0.8 [docker/docker-ce-packaging#545](https://github.com/docker/docker-ce-packaging/pull/545).

## [20.10.6](#20106)

2021-04-12

### [Client](#client-3)

* Apple Silicon (darwin/arm64) support for Docker CLI [docker/cli#3042](https://github.com/docker/cli/pull/3042)
* config: print deprecation warning when falling back to pre-v1.7.0 config file `~/.dockercfg`. Support for this file will be removed in a future release [docker/cli#3000](https://github.com/docker/cli/pull/3000)

### [Builder](#builder-2)

* Fix classic builder silently ignoring unsupported Dockerfile options and prompt to enable BuildKit instead [moby/moby#42197](https://github.com/moby/moby/pull/42197)

### [Logging](#logging-1)

* json-file: fix sporadic unexpected EOF errors [moby/moby#42174](https://github.com/moby/moby/pull/42174)

### [Networking](#networking-1)

* Fix a regression in docker 20.10, causing IPv6 addresses no longer to be bound by default when mapping ports [moby/moby#42205](https://github.com/moby/moby/pull/42205)
* Fix implicit IPv6 port-mappings not included in API response. Before docker 20.10, published ports were accessible through both IPv4 and IPv6 by default, but the API only included information about the IPv4 (0.0.0.0) mapping [moby/moby#42205](https://github.com/moby/moby/pull/42205)
* Fix a regression in docker 20.10, causing the docker-proxy to not be terminated in all cases [moby/moby#42205](https://github.com/moby/moby/pull/42205)
* Fix iptables forwarding rules not being cleaned up upon container removal [moby/moby#42205](https://github.com/moby/moby/pull/42205)

### [Packaging](#packaging-6)

* Update containerd to [v1.4.4](https://github.com/containerd/containerd/releases/tag/v1.4.4) for static binaries. The containerd.io package on apt/yum repos already had this update out of band. Includes a fix for [CVE-2021-21334](https://github.com/containerd/containerd/security/advisories/GHSA-6g2q-w5j3-fwh4). [moby/moby#42124](https://github.com/moby/moby/pull/42124)
* Packages for Debian/Raspbian 11 Bullseye, Ubuntu 21.04 Hirsute Hippo and Fedora 34 [docker/docker-ce-packaging#521](https://github.com/docker/docker-ce-packaging/pull/521) [docker/docker-ce-packaging#522](https://github.com/docker/docker-ce-packaging/pull/522) [docker/docker-ce-packaging#533](https://github.com/docker/docker-ce-packaging/pull/533)
* Provide the [Docker Scan CLI](https://github.com/docker/scan-cli-plugin) plugin on Linux amd64 via a `docker-scan-plugin` package as a recommended dependency for the `docker-ce-cli` package [docker/docker-ce-packaging#537](https://github.com/docker/docker-ce-packaging/pull/537)
* Include VPNKit binary for arm64 [moby/moby#42141](https://github.com/moby/moby/pull/42141)

### [Plugins](#plugins)

* Fix docker plugin create making plugins that were incompatible with older versions of Docker [moby/moby#42256](https://github.com/moby/moby/pull/42256)

### [Rootless](#rootless-2)

* Update RootlessKit to [v0.14.1](https://github.com/rootless-containers/rootlesskit/releases/tag/v0.14.1) (see also [v0.14.0](https://github.com/rootless-containers/rootlesskit/releases/tag/v0.14.0) [v0.13.2](https://github.com/rootless-containers/rootlesskit/releases/tag/v0.13.2)) [moby/moby#42186](https://github.com/moby/moby/pull/42186) [moby/moby#42232](https://github.com/moby/moby/pull/42232)
* dockerd-rootless-setuptool.sh: create CLI context "rootless" [moby/moby#42109](https://github.com/moby/moby/pull/42109)
* dockerd-rootless.sh: prohibit running as root [moby/moby#42072](https://github.com/moby/moby/pull/42072)
* Fix "operation not permitted" when bind mounting existing mounts [moby/moby#42233](https://github.com/moby/moby/pull/42233)
* overlay2: fix "createDirWithOverlayOpaque(...) ... input/output error" [moby/moby#42235](https://github.com/moby/moby/pull/42235)
* overlay2: support "userxattr" option (kernel 5.11) [moby/moby#42168](https://github.com/moby/moby/pull/42168)
* btrfs: allow unprivileged user to delete subvolumes (kernel >= 4.18) [moby/moby#42253](https://github.com/moby/moby/pull/42253)
* cgroup2: Move cgroup v2 out of experimental [moby/moby#42263](https://github.com/moby/moby/pull/42263)

## [20.10.5](#20105)

2021-03-02

### [Client](#client-4)

* Revert [docker/cli#2960](https://github.com/docker/cli/pull/2960) to fix hanging in `docker start --attach` and remove spurious `Unsupported signal: <nil>. Discarding` messages. [docker/cli#2987](https://github.com/docker/cli/pull/2987).

## [20.10.4](#20104)

2021-02-26

### [Builder](#builder-3)

* Fix incorrect cache match for inline cache import with empty layers [moby/moby#42061](https://github.com/moby/moby/pull/42061)

* Update BuildKit to v0.8.2 [moby/moby#42061](https://github.com/moby/moby/pull/42061)

  * resolver: avoid error caching on token fetch
  * fileop: fix checksum to contain indexes of inputs preventing certain cache misses
  * Fix reference count issues on typed errors with mount references (fixing `invalid mutable ref` errors)
  * git: set token only for main remote access allowing cloning submodules with different credentials

* Ensure blobs get deleted in /var/lib/docker/buildkit/content/blobs/sha256 after pull. To clean up old state run `builder prune` [moby/moby#42065](https://github.com/moby/moby/pull/42065)

* Fix parallel pull synchronization regression [moby/moby#42049](https://github.com/moby/moby/pull/42049)

* Ensure libnetwork state files do not leak [moby/moby#41972](https://github.com/moby/moby/pull/41972)

### [Client](#client-5)

* Fix a panic on `docker login` if no config file is present [docker/cli#2959](https://github.com/docker/cli/pull/2959)
* Fix `WARNING: Error loading config file: .dockercfg: $HOME is not defined` [docker/cli#2958](https://github.com/docker/cli/pull/2958)

### [Runtime](#runtime-3)

* docker info: silence unhandleable warnings [moby/moby#41958](https://github.com/moby/moby/pull/41958)
* Avoid creating parent directories for XGlobalHeader [moby/moby#42017](https://github.com/moby/moby/pull/42017)
* Use 0755 permissions when creating missing directories [moby/moby#42017](https://github.com/moby/moby/pull/42017)
* Fallback to manifest list when no platform matches in image config [moby/moby#42045](https://github.com/moby/moby/pull/42045) [moby/moby#41873](https://github.com/moby/moby/pull/41873)
* Fix a daemon panic on setups with a custom default runtime configured [moby/moby#41974](https://github.com/moby/moby/pull/41974)
* Fix a panic when daemon configuration is empty [moby/moby#41976](https://github.com/moby/moby/pull/41976)
* Fix daemon panic when starting container with invalid device cgroup rule [moby/moby#42001](https://github.com/moby/moby/pull/42001)
* Fix userns-remap option when username & UID match [moby/moby#42013](https://github.com/moby/moby/pull/42013)
* static: update runc binary to v1.0.0-rc93 [moby/moby#42014](https://github.com/moby/moby/pull/42014)

### [Logger](#logger)

* Honor `labels-regex` config even if `labels` is not set [moby/moby#42046](https://github.com/moby/moby/pull/42046)
* Handle long log messages correctly preventing awslogs in non-blocking mode to split events bigger than 16kB [mobymoby#41975](https://github.com/moby/moby/pull/41975)

### [Rootless](#rootless-3)

* Prevent the service hanging when stopping by setting systemd KillMode to mixed [moby/moby#41956](https://github.com/moby/moby/pull/41956)
* dockerd-rootless.sh: add typo guard [moby/moby#42070](https://github.com/moby/moby/pull/42070)
* Update rootlesskit to v0.13.1 to fix handling of IPv6 addresses [moby/moby#42025](https://github.com/moby/moby/pull/42025)
* allow mknodding FIFO inside userns [moby/moby#41957](https://github.com/moby/moby/pull/41957)

### [Security](#security)

* profiles: seccomp: update to Linux 5.11 syscall list [moby/moby#41971](https://github.com/moby/moby/pull/41971)

### [Swarm](#swarm-2)

* Fix issue with heartbeat not persisting upon restart [moby/moby#42060](https://github.com/moby/moby/pull/42060)
* Fix potential stalled tasks [moby/moby#42060](https://github.com/moby/moby/pull/42060)
* Fix `--update-order` and `--rollback-order` flags when only `--update-order` or `--rollback-order` is provided [docker/cli#2963](https://github.com/docker/cli/pull/2963)
* Fix `docker service rollback` returning a non-zero exit code in some situations [docker/cli#2964](https://github.com/docker/cli/pull/2964)
* Fix inconsistent progress-bar direction on `docker service rollback` [docker/cli#2964](https://github.com/docker/cli/pull/2964)

## [20.10.3](#20103)

2021-02-01

### [Security](#security-1)

* [CVE-2021-21285](https://github.com/moby/moby/security/advisories/GHSA-6fj5-m822-rqx8) Prevent an invalid image from crashing docker daemon
* [CVE-2021-21284](https://github.com/moby/moby/security/advisories/GHSA-7452-xqpj-6rpc) Lock down file permissions to prevent remapped root from accessing docker state
* Ensure AppArmor and SELinux profiles are applied when building with BuildKit

### [Client](#client-6)

* Check contexts before importing them to reduce risk of extracted files escaping context store
* Windows: prevent executing certain binaries from current directory [docker/cli#2950](https://github.com/docker/cli/pull/2950)

## [20.10.2](#20102)

2021-01-04

### [Runtime](#runtime-4)

* Fix a daemon start up hang when restoring containers with restart policies but that keep failing to start [moby/moby#41729](https://github.com/moby/moby/pull/41729)
* overlay2: fix an off-by-one error preventing to build or run containers when data-root is 24-bytes long [moby/moby#41830](https://github.com/moby/moby/pull/41830)
* systemd: send `sd_notify STOPPING=1` when shutting down [moby/moby#41832](https://github.com/moby/moby/pull/41832)

### [Networking](#networking-2)

* Fix IPv6 port forwarding [moby/moby#41805](https://github.com/moby/moby/pull/41805) [moby/libnetwork#2604](https://github.com/moby/libnetwork/pull/2604)

### [Swarm](#swarm-3)

* Fix filtering for `replicated-job` and `global-job` service modes [moby/moby#41806](https://github.com/moby/moby/pull/41806)

### [Packaging](#packaging-7)

* buildx updated to [v0.5.1](https://github.com/docker/buildx/releases/tag/v0.5.1) [docker/docker-ce-packaging#516](https://github.com/docker/docker-ce-packaging/pull/516)

## [20.10.1](#20101)

2020-12-14

### [Builder](#builder-4)

* buildkit: updated to [v0.8.1](https://github.com/moby/buildkit/releases/tag/v0.8.1) with various bugfixes [moby/moby#41793](https://github.com/moby/moby/pull/41793)

### [Packaging](#packaging-8)

* Revert a change in the systemd unit that could prevent docker from starting due to a startup order conflict [docker/docker-ce-packaging#514](https://github.com/docker/docker-ce-packaging/pull/514)
* buildx updated to [v0.5.0](https://github.com/docker/buildx/releases/tag/v0.5.0) [docker/docker-ce-packaging#515](https://github.com/docker/docker-ce-packaging/pull/515)

## [20.10.0](#20100)

2020-12-08

### [Deprecation / Removal](#deprecation--removal)

For an overview of all deprecated features, refer to the [Deprecated Engine Features](/engine/deprecated/) page.

* Warnings and deprecation notice when `docker pull`-ing from non-compliant registries not supporting pull-by-digest [docker/cli#2872](https://github.com/docker/cli/pull/2872)
* Sterner warnings and deprecation notice for unauthenticated tcp access [moby/moby#41285](https://github.com/moby/moby/pull/41285)
* Deprecate KernelMemory (`docker run --kernel-memory`) [moby/moby#41254](https://github.com/moby/moby/pull/41254) [docker/cli#2652](https://github.com/docker/cli/pull/2652)
* Deprecate `aufs` storage driver [docker/cli#1484](https://github.com/docker/cli/pull/1484)
* Deprecate host-discovery and overlay networks with external k/v stores [moby/moby#40614](https://github.com/moby/moby/pull/40614) [moby/moby#40510](https://github.com/moby/moby/pull/40510)
* Deprecate Dockerfile legacy 'ENV name value' syntax, use `ENV name=value` instead [docker/cli#2743](https://github.com/docker/cli/pull/2743)
* Remove deprecated "filter" parameter for API v1.41 and up [moby/moby#40491](https://github.com/moby/moby/pull/40491)
* Disable distribution manifest v2 schema 1 on push [moby/moby#41295](https://github.com/moby/moby/pull/41295)
* Remove hack MalformedHostHeaderOverride breaking old docker clients (<= 1.12) in which case, set `DOCKER_API_VERSION` [moby/moby#39076](https://github.com/moby/moby/pull/39076)
* Remove "docker engine" subcommands [docker/cli#2207](https://github.com/docker/cli/pull/2207)
* Remove experimental "deploy" from "dab" files [docker/cli#2216](https://github.com/docker/cli/pull/2216)
* Remove deprecated `docker search --automated` and `--stars` flags [docker/cli#2338](https://github.com/docker/cli/pull/2338)
* No longer allow reserved namespaces in engine labels [docker/cli#2326](https://github.com/docker/cli/pull/2326)

### [API](#api)

* Update API version to v1.41
* Do not require "experimental" for metrics API [moby/moby#40427](https://github.com/moby/moby/pull/40427)
* `GET /events` now returns `prune` events after pruning resources have completed [moby/moby#41259](https://github.com/moby/moby/pull/41259)
  * Prune events are returned for `container`, `network`, `volume`, `image`, and `builder`, and have a `reclaimed` attribute, indicating the amount of space reclaimed (in bytes)
* Add `one-shot` stats option to not prime the stats [moby/moby#40478](https://github.com/moby/moby/pull/40478)
* Adding OS version info to the system info's API (`/info`) [moby/moby#38349](https://github.com/moby/moby/pull/38349)
* Add DefaultAddressPools to docker info [moby/moby#40714](https://github.com/moby/moby/pull/40714)
* Add API support for PidsLimit on services [moby/moby#39882](https://github.com/moby/moby/pull/39882)

### [Builder](#builder-5)

* buildkit,dockerfile: Support for `RUN --mount` options without needing to specify experimental dockerfile `#syntax` directive. [moby/buildkit#1717](https://github.com/moby/buildkit/pull/1717)

* dockerfile: `ARG` command now supports defining multiple build args on the same line similarly to `ENV` [moby/buildkit#1692](https://github.com/moby/buildkit/pull/1692)

* dockerfile: `--chown` flag in `ADD` now allows parameter expansion [moby/buildkit#1473](https://github.com/moby/buildkit/pull/1473)

* buildkit: Fetching authorization tokens has been moved to client-side (if the client supports it). Passwords do not leak into the build daemon anymore and users can see from build output when credentials or tokens are accessed. [moby/buildkit#1660](https://github.com/moby/buildkit/pull/1660)

* buildkit: Connection errors while communicating with the registry for push and pull now trigger a retry [moby/buildkit#1791](https://github.com/moby/buildkit/pull/1791)

* buildkit: Git source now supports token authentication via build secrets [moby/moby#41234](https://github.com/moby/moby/pull/41234) [docker/cli#2656](https://github.com/docker/cli/pull/2656) [moby/buildkit#1533](https://github.com/moby/buildkit/pull/1533)

* buildkit: Building from git source now supports forwarding SSH socket for authentication [moby/buildkit#1782](https://github.com/moby/buildkit/pull/1782)

* buildkit: Avoid builds that generate excessive logs to cause a crash or slow down the build. Clipping is performed if needed. [moby/buildkit#1754](https://github.com/moby/buildkit/pull/1754)

* buildkit: Change default Seccomp profile to the one provided by Docker [moby/buildkit#1807](https://github.com/moby/buildkit/pull/1807)

* buildkit: Support for exposing SSH agent socket on Windows has been improved [moby/buildkit#1695](https://github.com/moby/buildkit/pull/1695)

* buildkit: Disable truncating by default when using --progress=plain [moby/buildkit#1435](https://github.com/moby/buildkit/pull/1435)

* buildkit: Allow better handling client sessions dropping while it is being shared by multiple builds [moby/buildkit#1551](https://github.com/moby/buildkit/pull/1551)

* buildkit: secrets: allow providing secrets with env [moby/moby#41234](https://github.com/moby/moby/pull/41234) [docker/cli#2656](https://github.com/docker/cli/pull/2656) [moby/buildkit#1534](https://github.com/moby/buildkit/pull/1534)

  * Support `--secret id=foo,env=MY_ENV` as an alternative for storing a secret value to a file.
  * `--secret id=GIT_AUTH_TOKEN` will load env if it exists and the file does not.

* buildkit: Support for mirrors fallbacks, insecure TLS and custom TLS config [moby/moby#40814](https://github.com/moby/moby/pull/40814)

* buildkit: remotecache: Only visit each item once when walking results [moby/moby#41234](https://github.com/moby/moby/pull/41234) [moby/buildkit#1577](https://github.com/moby/buildkit/pull/1577)
  * Improves performance and CPU use on bigger graphs

* buildkit: Check remote when local image platform doesn't match [moby/moby#40629](https://github.com/moby/moby/pull/40629)

* buildkit: image export: Use correct media type when creating new layer blobs [moby/moby#41234](https://github.com/moby/moby/pull/41234) [moby/buildkit#1541](https://github.com/moby/buildkit/pull/1541)

* buildkit: progressui: fix logs time formatting [moby/moby#41234](https://github.com/moby/moby/pull/41234) [docker/cli#2656](https://github.com/docker/cli/pull/2656) [moby/buildkit#1549](https://github.com/moby/buildkit/pull/1549)

* buildkit: mitigate containerd issue on parallel push [moby/moby#41234](https://github.com/moby/moby/pull/41234) [moby/buildkit#1548](https://github.com/moby/buildkit/pull/1548)

* buildkit: inline cache: fix handling of duplicate blobs [moby/moby#41234](https://github.com/moby/moby/pull/41234) [moby/buildkit#1568](https://github.com/moby/buildkit/pull/1568)

  * Fixes <https://github.com/moby/buildkit/issues/1388> cache-from working unreliably
  * Fixes <https://github.com/moby/moby/issues/41219> Image built from cached layers is missing data

* Allow ssh:// for remote context URLs [moby/moby#40179](https://github.com/moby/moby/pull/40179)

* builder: remove legacy build's session handling (was experimental) [moby/moby#39983](https://github.com/moby/moby/pull/39983)

### [Client](#client-7)

* Add swarm jobs support to CLI [docker/cli#2262](https://github.com/docker/cli/pull/2262)
* Add `-a/--all-tags` to docker push [docker/cli#2220](https://github.com/docker/cli/pull/2220)
* Add support for Kubernetes username/password auth [docker/cli#2308](https://github.com/docker/cli/pull/2308)
* Add `--pull=missing|always|never` to `run` and `create` commands [docker/cli#1498](https://github.com/docker/cli/pull/1498)
* Add `--env-file` flag to `docker exec` for parsing environment variables from a file [docker/cli#2602](https://github.com/docker/cli/pull/2602)
* Add shorthand `-n` for `--tail` option [docker/cli#2646](https://github.com/docker/cli/pull/2646)
* Add log-driver and options to service inspect "pretty" format [docker/cli#1950](https://github.com/docker/cli/pull/1950)
* docker run: specify cgroup namespace mode with `--cgroupns` [docker/cli#2024](https://github.com/docker/cli/pull/2024)
* `docker manifest rm` command to remove manifest list draft from local storage [docker/cli#2449](https://github.com/docker/cli/pull/2449)
* Add "context" to "docker version" and "docker info" [docker/cli#2500](https://github.com/docker/cli/pull/2500)
* Propagate platform flag to container create API [docker/cli#2551](https://github.com/docker/cli/pull/2551)
* The `docker ps --format` flag now has a `.State` placeholder to print the container's state without additional details about uptime and health check [docker/cli#2000](https://github.com/docker/cli/pull/2000)
* Add support for docker-compose schema v3.9 [docker/cli#2073](https://github.com/docker/cli/pull/2073)
* Add support for docker push `--quiet` [docker/cli#2197](https://github.com/docker/cli/pull/2197)
* Hide flags that are not supported by BuildKit, if BuildKit is enabled [docker/cli#2123](https://github.com/docker/cli/pull/2123)
* Update flag description for `docker rm -v` to clarify the option only removes anonymous (unnamed) volumes [docker/cli#2289](https://github.com/docker/cli/pull/2289)
* Improve tasks printing for docker services [docker/cli#2341](https://github.com/docker/cli/pull/2341)
* docker info: list CLI plugins alphabetically [docker/cli#2236](https://github.com/docker/cli/pull/2236)
* Fix order of processing of `--label-add/--label-rm`, `--container-label-add/--container-label-rm`, and `--env-add/--env-rm` flags on `docker service update` to allow replacing existing values [docker/cli#2668](https://github.com/docker/cli/pull/2668)
* Fix `docker rm --force` returning a non-zero exit code if one or more containers did not exist [docker/cli#2678](https://github.com/docker/cli/pull/2678)
* Improve memory stats display by using `total_inactive_file` instead of `cache` [docker/cli#2415](https://github.com/docker/cli/pull/2415)
* Mitigate against YAML files that has excessive aliasing [docker/cli#2117](https://github.com/docker/cli/pull/2117)
* Allow using advanced syntax when setting a config or secret with only the source field [docker/cli#2243](https://github.com/docker/cli/pull/2243)
* Fix reading config files containing `username` and `password` auth even if `auth` is empty [docker/cli#2122](https://github.com/docker/cli/pull/2122)
* docker cp: prevent NPE when failing to stat destination [docker/cli#2221](https://github.com/docker/cli/pull/2221)
* config: preserve ownership and permissions on configfile [docker/cli#2228](https://github.com/docker/cli/pull/2228)

### [Logging](#logging-2)

* Support reading `docker logs` with all logging drivers (best effort) [moby/moby#40543](https://github.com/moby/moby/pull/40543)
* Add `splunk-index-acknowledgment` log option to work with Splunk HECs with index acknowledgment enabled [moby/moby#39987](https://github.com/moby/moby/pull/39987)
* Add partial metadata to journald logs [moby/moby#41407](https://github.com/moby/moby/pull/41407)
* Reduce allocations for logfile reader [moby/moby#40796](https://github.com/moby/moby/pull/40796)
* Fluentd: add fluentd-async, fluentd-request-ack, and deprecate fluentd-async-connect [moby/moby#39086](https://github.com/moby/moby/pull/39086)

### [Runtime](#runtime-5)

* Support cgroup2 [moby/moby#40174](https://github.com/moby/moby/pull/40174) [moby/moby#40657](https://github.com/moby/moby/pull/40657) [moby/moby#40662](https://github.com/moby/moby/pull/40662)
* cgroup2: use "systemd" cgroup driver by default when available [moby/moby#40846](https://github.com/moby/moby/pull/40846)
* new storage driver: fuse-overlayfs [moby/moby#40483](https://github.com/moby/moby/pull/40483)
* Update containerd binary to v1.4.3 [moby/moby#41732](https://github.com/moby/moby/pull/41732)
* `docker push` now defaults to `latest` tag instead of all tags [moby/moby#40302](https://github.com/moby/moby/pull/40302)
* Added ability to change the number of reconnect attempts during connection loss while pulling an image by adding max-download-attempts to the config file [moby/moby#39949](https://github.com/moby/moby/pull/39949)
* Add support for containerd v2 shim by using the now default `io.containerd.runc.v2` runtime [moby/moby#41182](https://github.com/moby/moby/pull/41182)
* cgroup v1: change the default runtime to io.containerd.runc.v2. Requires containerd v1.3.0 or later. v1.3.5 or later is recommended [moby/moby#41210](https://github.com/moby/moby/pull/41210)
* Start containers in their own cgroup namespaces [moby/moby#38377](https://github.com/moby/moby/pull/38377)
* Enable DNS Lookups for CIFS Volumes [moby/moby#39250](https://github.com/moby/moby/pull/39250)
* Use MemAvailable instead of MemFree to estimate actual available memory [moby/moby#39481](https://github.com/moby/moby/pull/39481)
* The `--device` flag in `docker run` will now be honored when the container is started in privileged mode [moby/moby#40291](https://github.com/moby/moby/pull/40291)
* Enforce reserved internal labels [moby/moby#40394](https://github.com/moby/moby/pull/40394)
* Raise minimum memory limit to 6M, to account for higher memory use by runtimes during container startup [moby/moby#41168](https://github.com/moby/moby/pull/41168)
* vendor runc v1.0.0-rc92 [moby/moby#41344](https://github.com/moby/moby/pull/41344) [moby/moby#41317](https://github.com/moby/moby/pull/41317)
* info: add warnings about missing blkio cgroup support [moby/moby#41083](https://github.com/moby/moby/pull/41083)
* Accept platform spec on container create [moby/moby#40725](https://github.com/moby/moby/pull/40725)
* Fix handling of looking up user- and group-names with spaces [moby/moby#41377](https://github.com/moby/moby/pull/41377)

### [Networking](#networking-3)

* Support host.docker.internal in dockerd on Linux [moby/moby#40007](https://github.com/moby/moby/pull/40007)

* Include IPv6 address of linked containers in /etc/hosts [moby/moby#39837](https://github.com/moby/moby/pull/39837)

* `--ip6tables` enables IPv6 iptables rules (only if experimental) [moby/moby#41622](https://github.com/moby/moby/pull/41622)

* Add alias for hostname if hostname != container name [moby/moby#39204](https://github.com/moby/moby/pull/39204)

* Better selection of DNS server (with systemd) [moby/moby#41022](https://github.com/moby/moby/pull/41022)

* Add docker interfaces to firewalld docker zone [moby/moby#41189](https://github.com/moby/moby/pull/41189) [moby/libnetwork#2548](https://github.com/moby/libnetwork/pull/2548)

  * Fixes DNS issue on CentOS8 [docker/for-linux#957](https://github.com/docker/for-linux/issues/957)
  * Fixes Port Forwarding on RHEL 8 with Firewalld running with FirewallBackend=nftables [moby/libnetwork#2496](https://github.com/moby/libnetwork/issues/2496)

* Fix an issue reporting 'failed to get network during CreateEndpoint' [moby/moby#41189](https://github.com/moby/moby/pull/41189) [moby/libnetwork#2554](https://github.com/moby/libnetwork/pull/2554)

* Log error instead of disabling IPv6 router advertisement failed [moby/moby#41189](https://github.com/moby/moby/pull/41189) [moby/libnetwork#2563](https://github.com/moby/libnetwork/pull/2563)

* No longer ignore `--default-address-pool` option in certain cases [moby/moby#40711](https://github.com/moby/moby/pull/40711)

* Produce an error with invalid address pool [moby/moby#40808](https://github.com/moby/moby/pull/40808) [moby/libnetwork#2538](https://github.com/moby/libnetwork/pull/2538)

* Fix `DOCKER-USER` chain not created when IPTableEnable=false [moby/moby#40808](https://github.com/moby/moby/pull/40808) [moby/libnetwork#2471](https://github.com/moby/libnetwork/pull/2471)

* Fix panic on startup in systemd environments [moby/moby#40808](https://github.com/moby/moby/pull/40808) [moby/libnetwork#2544](https://github.com/moby/libnetwork/pull/2544)

* Fix issue preventing containers to communicate over macvlan internal network [moby/moby#40596](https://github.com/moby/moby/pull/40596) [moby/libnetwork#2407](https://github.com/moby/libnetwork/pull/2407)

* Fix InhibitIPv4 nil panic [moby/moby#40596](https://github.com/moby/moby/pull/40596)

* Fix VFP leak in Windows overlay network deletion [moby/moby#40596](https://github.com/moby/moby/pull/40596) [moby/libnetwork#2524](https://github.com/moby/libnetwork/pull/2524)

### [Packaging](#packaging-9)

* docker.service: Add multi-user.target to After= in unit file [moby/moby#41297](https://github.com/moby/moby/pull/41297)
* docker.service: Allow socket activation [moby/moby#37470](https://github.com/moby/moby/pull/37470)
* seccomp: Remove dependency in dockerd on libseccomp [moby/moby#41395](https://github.com/moby/moby/pull/41395)

### [Rootless](#rootless-4)

* rootless: graduate from experimental [moby/moby#40759](https://github.com/moby/moby/pull/40759)
* Add dockerd-rootless-setuptool.sh [moby/moby#40950](https://github.com/moby/moby/pull/40950)
* Support `--exec-opt native.cgroupdriver=systemd` [moby/moby#40486](https://github.com/moby/moby/pull/40486)

### [Security](#security-2)

* Fix CVE-2019-14271 loading of nsswitch based config inside chroot under Glibc [moby/moby#39612](https://github.com/moby/moby/pull/39612)
* seccomp: Whitelist `clock_adjtime`. `CAP_SYS_TIME` is still required for time adjustment [moby/moby#40929](https://github.com/moby/moby/pull/40929)
* seccomp: Add openat2 and faccessat2 to default seccomp profile [moby/moby#41353](https://github.com/moby/moby/pull/41353)
* seccomp: allow 'rseq' syscall in default seccomp profile [moby/moby#41158](https://github.com/moby/moby/pull/41158)
* seccomp: allow syscall membarrier [moby/moby#40731](https://github.com/moby/moby/pull/40731)
* seccomp: whitelist io-uring related system calls [moby/moby#39415](https://github.com/moby/moby/pull/39415)
* Add default sysctls to allow ping sockets and privileged ports with no capabilities [moby/moby#41030](https://github.com/moby/moby/pull/41030)
* Fix seccomp profile for clone syscall [moby/moby#39308](https://github.com/moby/moby/pull/39308)

### [Swarm](#swarm-4)

* Add support for swarm jobs [moby/moby#40307](https://github.com/moby/moby/pull/40307)
* Add capabilities support to stack/service commands [docker/cli#2687](https://github.com/docker/cli/pull/2687) [docker/cli#2709](https://github.com/docker/cli/pull/2709) [moby/moby#39173](https://github.com/moby/moby/pull/39173) [moby/moby#41249](https://github.com/moby/moby/pull/41249)
* Add support for sending down service Running and Desired task counts [moby/moby#39231](https://github.com/moby/moby/pull/39231)
* service: support `--mount type=bind,bind-nonrecursive` [moby/moby#38788](https://github.com/moby/moby/pull/38788)
* Support ulimits on Swarm services. [moby/moby#41284](https://github.com/moby/moby/pull/41284) [docker/cli#2712](https://github.com/docker/cli/pull/2712)
* Fixed an issue where service logs could leak goroutines on the worker [moby/moby#40426](https://github.com/moby/moby/pull/40426)

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/build/list/
----

# docker dhi customization build list

***

| Description | List builds of a customization                            |
| ----------- | --------------------------------------------------------- |
| Usage       | `docker dhi customization build list <repository> <name>` |

## [Description](#description)

List all builds of a Docker Hardened Images customization by repository and name

## [Options](#options)

| Option   | Default | Description           |
| -------- | ------- | --------------------- |
| `--json` |         | Output in JSON format |

----
url: https://docs.docker.com/reference/cli/docker/model/df/
----

# docker model df

***

| Description | Show Docker Model Runner disk usage |
| ----------- | ----------------------------------- |
| Usage       | `docker model df`                   |

## [Description](#description)

Show Docker Model Runner disk usage

----
url: https://docs.docker.com/reference/cli/sbx/kit/push/
----

# sbx kit push

| Description | Push a kit artifact to an OCI registry     |
| ----------- | ------------------------------------------ |
| Usage       | `sbx kit push DIRECTORY REFERENCE [flags]` |

## [Description](#description)

Package and push a kit artifact directory to an OCI registry.

The directory must contain a valid spec.yaml. The reference should be in the format "registry/repo:tag" (e.g., "ghcr.io/myorg/my-plugin:1.0").

Authentication uses the Docker credential store.

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/docker-hub/image-library/search/
----

# Docker Hub search

***

Table of contents

***

The [Docker Hub search interface](https://hub.docker.com/search) lets you explore millions of resources. To help you find exactly what you need, it offers a variety of filters that let you narrow your results or discover different types of content.

## [Filters](#filters)

The search functionality includes filters to narrow down results based on your requirements, such as products, categories, trusted content, and publishers. This ensures that you can quickly find and access the resources best suited to your project.

### [Products](#products)

Docker Hub's content library features various products, each designed to meet specific needs of developers and organizations. These products include:

* Images
* Extensions
* Helm charts
* Compose files
* AI models
* Docker Engine plugins

#### [Images](#images)

Docker Hub hosts millions of container images, making it the go-to repository for containerized applications and solutions. These images include:

* Operating system images: Foundational images for Linux distributions like Ubuntu, Debian, and Alpine, or Windows Server images.
* Database and storage images: Pre-configured databases such as MySQL, PostgreSQL, and MongoDB to simplify application development.
* Languages and frameworks-based images: Popular images for Java, Python, Node.js, Ruby, .NET, and more, offering pre-built environments for faster development.

Images in Docker Hub simplify the development process by providing pre-built, reusable building blocks, reducing the need to start from scratch. Whether you're a beginner building your first container or an enterprise managing complex architectures, Docker Hub images provide a reliable foundation.

#### [Extensions](#extensions)

Docker Hub offers extensions for Docker Desktop, which enhance its core functionality. These extensions are purpose-built to streamline the software development lifecycle. Extensions provide tools for:

* System optimization and monitoring: Manage resources and optimize Docker Desktop’s performance.
* Container management: Simplify container deployment and monitoring.
* Database management: Facilitate efficient database operations within containers.
* Kubernetes and cloud integration: Bridge local environments with cloud-native and Kubernetes workflows.
* Visualization tools: Gain insights into container resource usage through graphical representations.

Extensions help developers and teams create a more efficient and unified workflow by reducing context switching and bringing essential tools into Docker Desktop's interface.

To learn more about extensions, see [Docker Extensions](https://docs.docker.com/extensions/).

#### [Helm charts](#helm-charts)

Helm charts in Docker Hub provide a streamlined way to package, configure, and deploy Kubernetes applications. Helm is the package manager for Kubernetes, and charts are pre-configured templates that define the resources needed to run an application in a Kubernetes cluster. Docker Hub hosts a variety of Helm charts that provide:

* Application packaging: Bundle Kubernetes manifests, configurations, and dependencies into a single, reusable chart.
* Version management: Track and manage different versions of your application deployments.
* Configuration templating: Customize deployments with values files, making it easy to deploy the same application across different environments.
* Dependency management: Automatically handle chart dependencies, ensuring all required components are deployed together.

Helm charts reduce the complexity of Kubernetes deployments, making it easier for teams to deploy, upgrade, and manage applications in production environments.

#### [Compose](#compose)

Docker Compose files in Docker Hub enable multi-container application orchestration through simple YAML configuration files. Compose is a tool for defining and running multi-container Docker applications, and Docker Hub hosts Compose files that help you:

* Multi-container orchestration: Define and run applications consisting of multiple interconnected containers with a single command.
* Service configuration: Specify container images, environment variables, networks, volumes, and dependencies in a declarative format.
* Development and testing: Quickly spin up complete application stacks for local development, testing, or demonstration purposes.
* Environment consistency: Ensure consistent application behavior across development, staging, and production environments.

Compose files simplify the process of managing complex applications by providing a clear, version-controlled definition of your entire application stack.

#### [AI models](#ai-models)

Docker Hub hosts AI and machine learning models in containerized formats, making it easier to deploy, share, and run AI applications across different environments. These containerized AI models provide:

* Pre-trained models: Access ready-to-use machine learning models for common tasks such as image recognition, natural language processing, and predictive analytics.
* Model serving: Deploy models as containerized services that can be easily integrated into applications and scaled as needed.
* Reproducible environments: Package models with their dependencies, ensuring consistent behavior across development and production environments.
* Framework support: Find models built with popular frameworks like TensorFlow, PyTorch, scikit-learn, and others.

Containerized AI models remove the need to manage infrastructure dependencies, let you deploy models across different environments, and enable scaling as application demands change.

#### [Plugins](#plugins)

Plugins in Docker Hub let you extend and customize Docker Engine to suit specialized requirements. Plugins integrate directly with the Docker Engine and provide capabilities such as:

* Network plugins: Enhance networking functionality, enabling integration with complex network infrastructures.
* Volume plugins: Provide advanced storage options, supporting persistent and distributed storage across various backends.
* Authorization plugins: Offer fine-grained access control to secure Docker environments.

By leveraging Docker plugins, teams can tailor Docker Engine to meet their specific operational needs, ensuring compatibility with existing infrastructures and workflows.

To learn more about plugins, see [Docker Engine managed plugin system](https://docs.docker.com/engine/extend/).

### [Trusted content](#trusted-content)

Docker Hub's trusted content provides a curated selection of high-quality, secure images designed to give developers confidence in the reliability and security of the resources they use. These images are stable, regularly updated, and adhere to industry best practices, making them a strong foundation for building and deploying applications. Docker Hub's trusted content includes, Docker Hardened Images, Docker Official Images, Verified Publisher images, and Docker-Sponsored Open Source Software images.

For more details, see [Trusted content](https://docs.docker.com/docker-hub/image-library/trusted-content/).

### [Publishers](#publishers)

The **Publishers** filter lets you narrow image results by the organization that published the image.

Publishers of trusted content appear first. Only a select number of publishers are shown.

### [Categories](#categories)

Docker Hub makes it easy to find and explore container images with categories. Categories group images based on their primary use case, helping you quickly locate the tools and resources you need to build, deploy, and run your applications.

### [Operating systems](#operating-systems)

The **Operating systems** filter lets you narrow your search to container images compatible with specific host operating systems. This filter ensures that the images you use align with your target environment, whether you're developing for Linux-based systems, Windows, or both.

* **Linux**: Access a wide range of images tailored for Linux environments. These images provide foundational environments for building and running Linux-based applications in containers.
* **Windows**: Explore Windows container images.

> Note
>
> The **Operating systems** filter is only available for images. If you select the **Extensions** or **Plugins** filter, then the **Operating systems** filter isn't available.

### [Architectures](#architectures)

The **Architectures** filter lets you find images built to support specific CPU architectures. This ensures compatibility with your hardware environment, from development machines to production servers.

* **ARM**: Select images compatible with ARM processors, commonly used in IoT devices and embedded systems.
* **ARM 64**: Locate 64-bit ARM-compatible images for modern ARM processors, such as those in AWS Graviton or Apple Silicon.
* **IBM POWER**: Find images optimized for IBM Power Systems, offering performance and reliability for enterprise workloads.
* **PowerPC 64 LE**: Access images designed for the little-endian PowerPC 64-bit architecture.
* **IBM Z**: Discover images tailored for IBM Z mainframes, ensuring compatibility with enterprise-grade hardware.
* **x86**: Choose images compatible with 32-bit x86 architectures, suitable for older systems or lightweight environments.
* **x86-64**: Filter images for modern 64-bit x86 systems, widely used in desktops, servers, and cloud infrastructures.

> Note
>
> The **Architectures** filter is only available for images. If you select the **Extensions** or **Plugins** filter, then the **Architectures** filter isn't available.

### [Reviewed by Docker](#reviewed-by-docker)

The **Reviewed by Docker** filter provides an extra layer of assurance when selecting extensions. This filter helps you identify whether a Docker Desktop extension has been reviewed by Docker for quality and reliability.

* **Reviewed**: Extensions that have undergone Docker's review process, ensuring they meet high standards.
* **Not Reviewed**: Extensions that have not been reviewed by Docker.

> Note
>
> The **Reviewed by Docker** filter is only available for extensions. To make the filter available, you must select only the **Extensions** filter in **Products**.

----
url: https://docs.docker.com/admin/company/
----

# Company overview

***

Table of contents

***

Subscription: Business

For: Administrators

A company provides a single point of visibility across multiple organizations, simplifying organization and settings management.

Organization owners with a Docker Business subscription can create a company and manage it through the [Docker Admin Console](https://app.docker.com/admin).

The following diagram shows how a company relates to its associated organizations.

## [Key features](#key-features)

With a company, administrators can:

* View and manage all nested organizations
* Configure company and organization settings centrally
* Control access to the company
* Have up to ten unique users assigned to the company owner role
* Configure SSO and SCIM for all nested organizations
* Enforce SSO for all users in the company

## [Create and manage your company](#create-and-manage-your-company)

Learn how to create and manage a company in the following sections.

### [Create a company](/admin/company/new-company/)

[Get started by learning how to create a company.](/admin/company/new-company/)

### [Manage organizations](/admin/company/manage/organizations/)

[Learn how to add and manage organizations as well as seats within your company.](/admin/company/manage/organizations/)

### [Manage company owners](/admin/company/manage/owners/)

[Find out more about company owners and how to manage them.](/admin/company/manage/owners/)

### [Manage users](/admin/company/manage/users/)

[Explore how to manage users in all organizations.](/admin/company/manage/users/)

### [Configure single sign-on](/enterprise/security/single-sign-on/)

[Discover how to configure SSO for your entire company.](/enterprise/security/single-sign-on/)

### [Set up SCIM](/enterprise/security/provisioning/scim/)

[Set up SCIM to automatically provision and deprovision users in your company.](/enterprise/security/provisioning/scim/)

### [Domain management](/enterprise/security/domain-management/)

[Add and verify your company's domains.](/enterprise/security/domain-management/)

### [FAQs](/faq/admin/company-faqs/)

[Explore frequently asked questions about companies.](/faq/admin/company-faqs/)

----
url: https://docs.docker.com/reference/cli/docker/context/rm/
----

# docker context rm

***

| Description                                                               | Remove one or more contexts              |
| ------------------------------------------------------------------------- | ---------------------------------------- |
| Usage                                                                     | `docker context rm CONTEXT [CONTEXT...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker context remove`                  |

## [Description](#description)

Remove one or more contexts

## [Options](#options)

| Option        | Default | Description                           |
| ------------- | ------- | ------------------------------------- |
| `-f, --force` |         | Force the removal of a context in use |

----
url: https://docs.docker.com/engine/daemon/remote-access/
----

# Configure remote access for Docker daemon

***

Table of contents

***

By default, the Docker daemon listens for connections on a Unix socket to accept requests from local clients. You can configure Docker to accept requests from remote clients by configuring it to listen on an IP address and port as well as the Unix socket.

> Warning
>
> Configuring Docker to accept connections from remote clients can leave you vulnerable to unauthorized access to the host and other attacks.
>
> It's critically important that you understand the security implications of opening Docker to the network. If steps aren't taken to secure the connection, it's possible for remote non-root users to gain root access on the host.
>
> Remote access without TLS is **not recommended**, and will require explicit opt-in in a future release. For more information on how to use TLS certificates to secure this connection, see [Protect the Docker daemon socket](https://docs.docker.com/engine/security/protect-access/).

## [Enable remote access](#enable-remote-access)

You can enable remote access to the daemon either using a `docker.service` systemd unit file for Linux distributions using systemd. Or you can use the `daemon.json` file, if your distribution doesn't use systemd.

Configuring Docker to listen for connections using both the systemd unit file and the `daemon.json` file causes a conflict that prevents Docker from starting.

### [Configuring remote access with systemd unit file](#configuring-remote-access-with-systemd-unit-file)

1. Use the command `sudo systemctl edit docker.service` to open an override file for `docker.service` in a text editor.

2. Add or modify the following lines, substituting your own values.

   ```systemd
   [Service]
   ExecStart=
   ExecStart=/usr/bin/dockerd -H fd:// -H tcp://127.0.0.1:2375
   ```

3. Save the file.

4. Reload the `systemctl` configuration.

   ```console
   $ sudo systemctl daemon-reload
   ```

5. Restart Docker.

   ```console
   $ sudo systemctl restart docker.service
   ```

6. Verify that the change has gone through.

   ```console
   $ sudo netstat -lntp | grep dockerd
   tcp        0      0 127.0.0.1:2375          0.0.0.0:*               LISTEN      3758/dockerd
   ```

### [Configuring remote access with `daemon.json`](#configuring-remote-access-with-daemonjson)

1. Set the `hosts` array in the `/etc/docker/daemon.json` to connect to the Unix socket and an IP address, as follows:

   ```json
   {
     "hosts": ["unix:///var/run/docker.sock", "tcp://127.0.0.1:2375"]
   }
   ```

2. Restart Docker.

3. Verify that the change has gone through.

   ```console
   $ sudo netstat -lntp | grep dockerd
   tcp        0      0 127.0.0.1:2375          0.0.0.0:*               LISTEN      3758/dockerd
   ```

### [Allow access to the remote API through a firewall](#allow-access-to-the-remote-api-through-a-firewall)

If you run a firewall on the same host as you run Docker, and you want to access the Docker Remote API from another remote host, you must configure your firewall to allow incoming connections on the Docker port. The default port is `2376` if you're using TLS encrypted transport, or `2375` otherwise.

Two common firewall daemons are:

* [Uncomplicated Firewall (ufw)](https://help.ubuntu.com/community/UFW), often used for Ubuntu systems.
* [firewalld](https://firewalld.org), often used for RPM-based systems.

Consult the documentation for your OS and firewall. The following information might help you get started. The settings used in this instruction are permissive, and you may want to use a different configuration that locks your system down more.

* For ufw, set `DEFAULT_FORWARD_POLICY="ACCEPT"` in your configuration.

* For firewalld, add rules similar to the following to your policy. One for incoming requests, and one for outgoing requests.

  ```xml
  <direct>
    [ <rule ipv="ipv6" table="filter" chain="FORWARD_direct" priority="0"> -i zt0 -j ACCEPT </rule> ]
    [ <rule ipv="ipv6" table="filter" chain="FORWARD_direct" priority="0"> -o zt0 -j ACCEPT </rule> ]
  </direct>
  ```

  Make sure that the interface names and chain names are correct.

## [Additional information](#additional-information)

For more detailed information on configuration options for remote access to the daemon, refer to the [dockerd CLI reference](/reference/cli/dockerd/#bind-docker-to-another-hostport-or-a-unix-socket).

----
url: https://docs.docker.com/reference/cli/docker/buildx/imagetools/create/
----

# docker buildx imagetools create

***

| Description | Create a new image based on source images               |
| ----------- | ------------------------------------------------------- |
| Usage       | `docker buildx imagetools create [OPTIONS] [SOURCE...]` |

## [Description](#description)

Create a new manifest list based on source manifests. The source manifests can be manifest lists or single platform distribution manifests and must already exist in the registry where the new manifest is created.

If only one source is specified and that source is a manifest list or image index, create performs a carbon copy. If one source is specified and that source is *not* a list or index, the output will be a manifest list, however you can disable this behavior with `--prefer-index=false` which attempts to preserve the source manifest format in the output.

## [Options](#options)

| Option                              | Default | Description                                                                                                                    |
| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [`--annotation`](#annotation)       |         | Add annotation to the image                                                                                                    |
| [`--append`](#append)               |         | Append to existing manifest                                                                                                    |
| [`--dry-run`](#dry-run)             |         | Show final image instead of pushing                                                                                            |
| [`-f, --file`](#file)               |         | Read source descriptor from file                                                                                               |
| [`--metadata-file`](#metadata-file) |         | Write create result metadata to a file                                                                                         |
| `-p, --platform`                    |         | Filter specified platforms of target image                                                                                     |
| `--prefer-index`                    | `true`  | When only a single source is specified, prefer outputting an image index or manifest list instead of performing a carbon copy  |
| `--progress`                        | `auto`  | Set type of progress output (`auto`, `none`, `plain`, `rawjson`, `tty`). Use plain to show container output                    |
| [`-t, --tag`](#tag)                 |         | Set reference for new image                                                                                                    |

## [Examples](#examples)

### [Add annotations to an image (--annotation)](#annotation)

The `--annotation` flag lets you add annotations the image index, manifest, and descriptors when creating a new image.

The following command creates a `foo/bar:latest` image with the `org.opencontainers.image.authors` annotation on the image index.

```console
$ docker buildx imagetools create \
  --annotation "index:org.opencontainers.image.authors=dvdksn" \
  --tag foo/bar:latest \
  foo/bar:alpha foo/bar:beta foo/bar:gamma
```

> Note
>
> The `imagetools create` command supports adding annotations to the image index and descriptor, using the following type prefixes:
>
> * `index:`
> * `manifest-descriptor:`
>
> It doesn't support annotating manifests or OCI layouts.

For more information about annotations, see [Annotations](/build/building/annotations/).

### [Append new sources to an existing manifest list (--append)](#append)

Use the `--append` flag to append the new sources to an existing manifest list in the destination.

### [Override the configured builder instance (--builder)](#builder)

Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

### [Show final image instead of pushing (--dry-run)](#dry-run)

Use the `--dry-run` flag to not push the image, just show it.

### [Read source descriptor from a file (-f, --file)](#file)

```text
-f FILE or --file FILE
```

Reads source from files. A source can be a manifest digest, manifest reference, or a JSON of OCI descriptor object.

In order to define annotations or additional platform properties like `os.version` and `os.features` you need to add them in the OCI descriptor object encoded in JSON.

```console
$ docker buildx imagetools inspect --raw alpine | jq '.manifests[0] | .platform."os.version"="10.1"' > descr.json
$ docker buildx imagetools create -f descr.json myuser/image
```

The descriptor in the file is merged with existing descriptor in the registry if it exists.

The supported fields for the descriptor are defined in [OCI spec](https://github.com/opencontainers/image-spec/blob/master/descriptor.md#properties) .

### [Write create result metadata to a file (--metadata-file)](#metadata-file)

To output metadata such as the image digest, pass the `--metadata-file` flag. The metadata will be written as a JSON object to the specified file. The directory of the specified file must already exist and be writable.

```console
$ docker buildx imagetools create -t user/app:latest -f image1 -f image2 --metadata-file metadata.json
$ cat metadata.json
```

```json
{
  "containerimage.descriptor": {
    "mediaType": "application/vnd.oci.image.index.v1+json",
    "digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3",
    "size": 4654
  },
  "image.name": "docker.io/user/app"
}
```

### [Set reference for new image (-t, --tag)](#tag)

```text
-t IMAGE or --tag IMAGE
```

Use the `-t` or `--tag` flag to set the name of the image to be created.

```console
$ docker buildx imagetools create --dry-run alpine@sha256:5c40b3c27b9f13c873fefb2139765c56ce97fd50230f1f2d5c91e55dec171907 sha256:c4ba6347b0e4258ce6a6de2401619316f982b7bcc529f73d2a410d0097730204
$ docker buildx imagetools create -t tonistiigi/myapp -f image1 -f image2
```

----
url: https://docs.docker.com/scout/integrations/environment/
----

# Integrating Docker Scout with environments

***

Table of contents

***

You can integrate Docker Scout with your runtime environments, and get insights for your running workloads. This gives you a real-time view of your security status for your deployed artifacts.

Docker Scout lets you define multiple environments, and assign images to different environments. This gives you a complete overview of your software supply chain, and lets you view and compare deltas between environments, for example staging and production.

How you define and name your environments is up to you. You can use patterns that are meaningful to you and that matches how you ship your applications.

## [Assign to environments](#assign-to-environments)

Each environment contains references to a number of images. These references represent containers currently running in that particular environment.

For example, say you're running `myorg/webapp:3.1` in production, you can assign that tag to your `production` environment. You might be running a different version of the same image in staging, in which case you can assign that version of the image to the `staging` environment.

To add environments to Docker Scout, you can:

* Use the `docker scout env <environment> <image>` CLI command to record images to environments manually
* Enable a runtime integration to automatically detect images in your environments.

Docker Scout supports the following runtime integrations:

* [Docker Scout GitHub Action](https://github.com/marketplace/actions/docker-scout#record-an-image-deployed-to-an-environment)
* [CLI client](https://docs.docker.com/scout/integrations/environment/cli/)
* [Sysdig integration](https://docs.docker.com/scout/integrations/environment/sysdig/)

> Note
>
> Only organization owners can create new environments and set up integrations. Additionally, Docker Scout only assigns an image to an environment if the image [has been analyzed](https://docs.docker.com/scout/explore/analysis/), either manually or through a [registry integration](https://docs.docker.com/scout/integrations/#container-registries).

## [List environments](#list-environments)

To see all of the available environments for an organization, you can use the `docker scout env` command.

```console
$ docker scout env
```

By default, this prints all environments for your personal Docker organization. To list environments for another organization that you're a part of, use the `--org` flag.

```console
$ docker scout env --org <org>
```

You can use the `docker scout config` command to change the default organization. This changes the default organization for all `docker scout` commands, not just `env`.

```console
$ docker scout config organization <org>
```

## [Comparing between environments](#comparing-between-environments)

Assigning images to environments lets you make comparisons with and between environments. This is useful for things like GitHub pull requests, for comparing the image built from the code in the PR to the corresponding image in staging or production.

You can also compare with streams using the `--to-env` flag on the [`docker scout compare`](/reference/cli/docker/scout/compare/) CLI command:

```console
$ docker scout compare --to-env production myorg/webapp:latest
```

## [View images for an environment](#view-images-for-an-environment)

To view the images for an environment:

1. Go to the [Images page](https://scout.docker.com/) in the Docker Scout Dashboard.
2. Open the **Environments** drop-down menu.
3. Select the environment that you want to view.

The list displays all images that have been assigned to the selected environment. If you've deployed multiple versions of the same image in an environment, all versions of the image appear in the list.

Alternatively, you can use the `docker scout env` command to view the images from the terminal.

```console
$ docker scout env production
docker/scout-demo-service:main@sha256:ef08dca54c4f371e7ea090914f503982e890ec81d22fd29aa3b012351a44e1bc
```

### [Mismatching image tags](#mismatching-image-tags)

When you've selected an environment on the **Images** tab, tags in the list represent the tag that was used to deploy the image. Tags are mutable, meaning that you can change the image digest that a tag refers to. If Docker Scout detects that a tag refers to an outdated digest, a warning icon displays next to the image name.

----
url: https://docs.docker.com/reference/build-checks/legacy-key-value-format/
----

# LegacyKeyValueFormat

***

Table of contents

***

## [Output](#output)

```text
"ENV key=value" should be used instead of legacy "ENV key value" format
```

## [Description](#description)

The correct format for declaring environment variables and build arguments in a Dockerfile is `ENV key=value` and `ARG key=value`, where the variable name (`key`) and value (`value`) are separated by an equals sign (`=`). Historically, Dockerfiles have also supported a space separator between the key and the value (for example, `ARG key value`). This legacy format is deprecated, and you should only use the format with the equals sign.

## [Examples](#examples)

❌ Bad: using a space separator for variable key and value.

```dockerfile
FROM alpine
ARG foo bar
```

✅ Good: use an equals sign to separate key and value.

```dockerfile
FROM alpine
ARG foo=bar
```

❌ Bad: multi-line variable declaration with a space separator.

```dockerfile
ENV DEPS \
    curl \
    git \
    make
```

✅ Good: use an equals sign and wrap the value in quotes.

```dockerfile
ENV DEPS="\
    curl \
    git \
    make"
```

> Note
>
> Be aware of leading whitespace when converting multi-line legacy syntax to the modern `key=value` format. In the legacy format, leading whitespace on continuation lines is included in the value. In the modern format with quoted values, leading whitespace inside the quotes is also preserved. If you don't want leading whitespace in the value, make sure to remove it when rewriting to the new format:
>
> ```dockerfile
> ENV DEPS="\
> curl \
> git \
> make"
> ```

----
url: https://docs.docker.com/get-started/workshop/05_persisting_data/
----

# Persist the DB

***

Table of contents

***

In case you didn't notice, your todo list is empty every single time you launch the container. Why is this? In this part, you'll dive into how the container is working.

## [The container's filesystem](#the-containers-filesystem)

When a container runs, it uses the various layers from an image for its filesystem. Each container also gets its own "scratch space" to create/update/remove files. Any changes won't be seen in another container, even if they're using the same image.

### [See this in practice](#see-this-in-practice)

To see this in action, you're going to start two containers. In one container, you'll create a file. In the other container, you'll check whether that same file exists.

1. Start an Alpine container and create a new file in it.

   ```console
   $ docker run --rm alpine touch greeting.txt
   ```

   > Tip
   >
   > Any commands you specify after the image name (in this case, `alpine`) are executed inside the container. In this case, the command `touch greeting.txt` puts a file named `greeting.txt` on the container's filesystem.

2. Run a new Alpine container and use the `stat` command to check whether the file exists.

   ```console
   $ docker run --rm alpine stat greeting.txt
   ```

   You should see output similar to the following that indicates the file does not exist in the new container.

   ```console
   stat: can't stat 'greeting.txt': No such file or directory
   ```

The `greeting.txt` file created by the first container did not exist in the second container. That is because the writeable "top layer" of each container is isolated. Even though both containers shared the same underlying layers that make up the base image, the writable layer is unique to each container.

## [Container volumes](#container-volumes)

With the previous experiment, you saw that each container starts from the image definition each time it starts. While containers can create, update, and delete files, those changes are lost when you remove the container and Docker isolates all changes to that container. With volumes, you can change all of this.

[Volumes](https://docs.docker.com/engine/storage/volumes/) provide the ability to connect specific filesystem paths of the container back to the host machine. If you mount a directory in the container, changes in that directory are also seen on the host machine. If you mount that same directory across container restarts, you'd see the same files.

There are two main types of volumes. You'll eventually use both, but you'll start with volume mounts.

## [Persist the todo data](#persist-the-todo-data)

By default, the todo app stores its data in a SQLite database at `/etc/todos/todo.db` in the container's filesystem. If you're not familiar with SQLite, no worries! It's simply a relational database that stores all the data in a single file. While this isn't the best for large-scale applications, it works for small demos. You'll learn how to switch this to a different database engine later.

With the database being a single file, if you can persist that file on the host and make it available to the next container, it should be able to pick up where the last one left off. By creating a volume and attaching (often called "mounting") it to the directory where you stored the data, you can persist the data. As your container writes to the `todo.db` file, it will persist the data to the host in the volume.

As mentioned, you're going to use a volume mount. Think of a volume mount as an opaque bucket of data. Docker fully manages the volume, including the storage location on disk. You only need to remember the name of the volume.

### [Create a volume and start the container](#create-a-volume-and-start-the-container)

You can create the volume and start the container using the CLI or Docker Desktop's graphical interface.

1. Create a volume by using the `docker volume create` command.

   ```console
   $ docker volume create todo-db
   ```

2. Stop and remove the todo app container once again with `docker rm -f <id>`, as it is still running without using the persistent volume.

3. Start the todo app container, but add the `--mount` option to specify a volume mount. Give the volume a name, and mount it to `/etc/todos` in the container, which captures all files created at the path.

   ```console
   $ docker run -dp 127.0.0.1:3000:3000 --mount type=volume,src=todo-db,target=/etc/todos getting-started
   ```

   > Note
   >
   > If you're using Git Bash, you must use different syntax for this command.
   >
   > ```console
   > $ docker run -dp 127.0.0.1:3000:3000 --mount type=volume,src=todo-db,target=//etc/todos getting-started
   > ```
   >
   > For more details about Git Bash's syntax differences, see [Working with Git Bash](/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-commands-failing-in-git-bash).

To create a volume:

1. Select **Volumes** in Docker Desktop.
2. In **Volumes**, select **Create**.
3. Specify `todo-db` as the volume name, and then select **Create**.

To stop and remove the app container:

1. Select **Containers** in Docker Desktop.
2. Select **Delete** in the **Actions** column for the container.

To start the todo app container with the volume mounted:

1. Select the search box at the top of Docker Desktop.

2. In the search window, select the **Images** tab.

3. In the search box, specify the image name, `getting-started`.

   > Tip
   >
   > Use the search filter to filter images and only show **Local images**.

4. Select your image and then select **Run**.

5. Select **Optional settings**.

6. In **Host port**, specify the port, for example, `3000`.

7. In **Host path**, specify the name of the volume, `todo-db`.

8. In **Container path**, specify `/etc/todos`.

9. Select **Run**.

### [Verify that the data persists](#verify-that-the-data-persists)

1. Once the container starts up, open the app and add a few items to your todo list.

2. Stop and remove the container for the todo app. Use Docker Desktop or `docker ps` to get the ID and then `docker rm -f <id>` to remove it.

3. Start a new container using the previous steps.

4. Open the app. You should see your items still in your list.

5. Go ahead and remove the container when you're done checking out your list.

You've now learned how to persist data.

## [Dive into the volume](#dive-into-the-volume)

A lot of people frequently ask "Where is Docker storing my data when I use a volume?" If you want to know, you can use the `docker volume inspect` command.

```console
$ docker volume inspect todo-db
```

You should see output like the following:

```console
[
    {
        "CreatedAt": "2019-09-26T02:18:36Z",
        "Driver": "local",
        "Labels": {},
        "Mountpoint": "/var/lib/docker/volumes/todo-db/_data",
        "Name": "todo-db",
        "Options": {},
        "Scope": "local"
    }
]
```

The `Mountpoint` is the actual location of the data on the disk. Note that on most machines, you will need to have root access to access this directory from the host.

## [Summary](#summary)

In this section, you learned how to persist container data.

Related information:

* [docker CLI reference](/reference/cli/docker/)
* [Volumes](https://docs.docker.com/engine/storage/volumes/)

## [Next steps](#next-steps)

Next, you'll learn how you can develop your app more efficiently using bind mounts.

[Use bind mounts](https://docs.docker.com/get-started/workshop/06_bind_mounts/)

----
url: https://docs.docker.com/build/cache/invalidation/
----

# Build cache invalidation

***

Table of contents

***

When building an image, Docker steps through the instructions in your Dockerfile, executing each in the order specified. For each instruction, the [builder](https://docs.docker.com/build/builders/) checks whether it can reuse the instruction from the build cache.

## [General rules](#general-rules)

The basic rules of build cache invalidation are as follows:

* The builder begins by checking if the base image is already cached. Each subsequent instruction is compared against the cached layers. If no cached layer matches the instruction exactly, the cache is invalidated.

* In most cases, comparing the Dockerfile instruction with the corresponding cached layer is sufficient. However, some instructions require additional checks and explanations.

* For the `ADD` and `COPY` instructions, and for `RUN` instructions with bind mounts (`RUN --mount=type=bind`), the builder calculates a cache checksum from file metadata to determine whether cache is valid. During cache lookup, cache is invalidated if the file metadata has changed for any of the files involved.

  The modification time of a file (`mtime`) is not taken into account when calculating the cache checksum. If only the `mtime` of the copied files have changed, the cache is not invalidated.

* Aside from the `ADD` and `COPY` commands, cache checking doesn't look at the files in the container to determine a cache match. For example, when processing a `RUN apt-get -y update` command the files updated in the container aren't examined to determine if a cache hit exists. In that case just the command string itself is used to find a match.

Once the cache is invalidated, all subsequent Dockerfile commands generate new images and the cache isn't used.

If your build contains several layers and you want to ensure the build cache is reusable, order the instructions from less frequently changed to more frequently changed where possible.

## [WORKDIR and SOURCE\_DATE\_EPOCH](#workdir-and-source_date_epoch)

The `WORKDIR` instruction respects the `SOURCE_DATE_EPOCH` build argument when determining cache validity. Changing `SOURCE_DATE_EPOCH` between builds invalidates the cache for `WORKDIR` and all subsequent instructions.

`SOURCE_DATE_EPOCH` sets timestamps for files created during the build. If you set this to a dynamic value like a Git commit timestamp, the cache breaks with each commit. This is expected behavior when tracking build provenance.

For reproducible builds without frequent cache invalidation, use a fixed timestamp:

```console
$ docker build --build-arg SOURCE_DATE_EPOCH=0 .
```

## [RUN instructions](#run-instructions)

The cache for `RUN` instructions isn't invalidated automatically between builds. Suppose you have a step in your Dockerfile to install `curl`:

```dockerfile
FROM alpine:3.23 AS install
RUN apk add curl
```

This doesn't mean that the version of `curl` in your image is always up-to-date. Rebuilding the image one week later will still get you the same packages as before. To force a re-execution of the `RUN` instruction, you can:

* Make sure that a layer before it has changed
* Clear the build cache ahead of the build using [`docker builder prune`](/reference/cli/docker/builder/prune/)
* Use the `--no-cache` or `--no-cache-filter` options

The `--no-cache-filter` option lets you specify a specific build stage to invalidate the cache for:

```console
$ docker build --no-cache-filter install .
```

## [Build secrets](#build-secrets)

The contents of build secrets are not part of the build cache. Changing the value of a secret doesn't result in cache invalidation.

If you want to force cache invalidation after changing a secret value, you can pass a build argument with an arbitrary value that you also change when changing the secret. Build arguments do result in cache invalidation.

```dockerfile
FROM alpine
ARG CACHEBUST
RUN --mount=type=secret,id=TOKEN,env=TOKEN \
    some-command ...
```

```console
$ TOKEN="tkn_pat123456" docker build --secret id=TOKEN --build-arg CACHEBUST=1 .
```

Properties of secrets such as IDs and mount paths do participate in the cache checksum, and result in cache invalidation if changed.

----
url: https://docs.docker.com/engine/swarm/how-swarm-mode-works/pki/
----

# Manage swarm security with public key infrastructure (PKI)

***

Table of contents

***

The Swarm mode public key infrastructure (PKI) system built into Docker makes it simple to securely deploy a container orchestration system. The nodes in a swarm use mutual Transport Layer Security (TLS) to authenticate, authorize, and encrypt the communications with other nodes in the swarm.

When you create a swarm by running `docker swarm init`, Docker designates itself as a manager node. By default, the manager node generates a new root Certificate Authority (CA) along with a key pair, which are used to secure communications with other nodes that join the swarm. If you prefer, you can specify your own externally-generated root CA, using the `--external-ca` flag of the [docker swarm init](/reference/cli/docker/swarm/init/) command.

The manager node also generates two tokens to use when you join additional nodes to the swarm: one worker token and one manager token. Each token includes the digest of the root CA's certificate and a randomly generated secret. When a node joins the swarm, the joining node uses the digest to validate the root CA certificate from the remote manager. The remote manager uses the secret to ensure the joining node is an approved node.

Each time a new node joins the swarm, the manager issues a certificate to the node. The certificate contains a randomly generated node ID to identify the node under the certificate common name (CN) and the role under the organizational unit (OU). The node ID serves as the cryptographically secure node identity for the lifetime of the node in the current swarm.

The diagram below illustrates how manager nodes and worker nodes encrypt communications using a minimum of TLS 1.2.

The example below shows the information from a certificate from a worker node:

```text
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            3b:1c:06:91:73:fb:16:ff:69:c3:f7:a2:fe:96:c1:73:e2:80:97:3b
        Signature Algorithm: ecdsa-with-SHA256
        Issuer: CN=swarm-ca
        Validity
            Not Before: Aug 30 02:39:00 2016 GMT
            Not After : Nov 28 03:39:00 2016 GMT
        Subject: O=ec2adilxf4ngv7ev8fwsi61i7, OU=swarm-worker, CN=dw02poa4vqvzxi5c10gm4pq2g
...snip...
```

By default, each node in the swarm renews its certificate every three months. You can configure this interval by running the `docker swarm update --cert-expiry <TIME PERIOD>` command. The minimum rotation value is 1 hour. Refer to the [docker swarm update](/reference/cli/docker/swarm/update/) CLI reference for details.

## [Rotating the CA certificate](#rotating-the-ca-certificate)

> Note
>
> Mirantis Kubernetes Engine (MKE), formerly known as Docker UCP, provides an external certificate manager service for the swarm. If you run swarm on MKE, you shouldn't rotate the CA certificates manually. Instead, contact Mirantis support if you need to rotate a certificate.

In the event that a cluster CA key or a manager node is compromised, you can rotate the swarm root CA so that none of the nodes trust certificates signed by the old root CA anymore.

Run `docker swarm ca --rotate` to generate a new CA certificate and key. If you prefer, you can pass the `--ca-cert` and `--external-ca` flags to specify the root certificate and to use a root CA external to the swarm. Alternately, you can pass the `--ca-cert` and `--ca-key` flags to specify the exact certificate and key you would like the swarm to use.

When you issue the `docker swarm ca --rotate` command, the following things happen in sequence:

1. Docker generates a cross-signed certificate. This means that a version of the new root CA certificate is signed with the old root CA certificate. This cross-signed certificate is used as an intermediate certificate for all new node certificates. This ensures that nodes that still trust the old root CA can still validate a certificate signed by the new CA.

2. Docker also tells all nodes to immediately renew their TLS certificates. This process may take several minutes, depending on the number of nodes in the swarm.

3. After every node in the swarm has a new TLS certificate signed by the new CA, Docker forgets about the old CA certificate and key material, and tells all the nodes to trust the new CA certificate only.

   This also causes a change in the swarm's join tokens. The previous join tokens are no longer valid.

From this point on, all new node certificates issued are signed with the new root CA, and do not contain any intermediates.

## [Learn More](#learn-more)

* Read about how [nodes](https://docs.docker.com/engine/swarm/how-swarm-mode-works/nodes/) work.
* Learn how Swarm mode [services](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) work.

----
url: https://docs.docker.com/docker-hub/image-library/mirror/
----

# Mirror the Docker Hub library

***

Table of contents

***

## [Use-case](#use-case)

If you have multiple instances of Docker running in your environment, such as multiple physical or virtual machines all running Docker, each daemon goes out to the internet and fetches an image it doesn't have locally, from the Docker repository. You can run a local registry mirror and point all your daemons there, to avoid this extra internet traffic.

> Note
>
> Docker Official Images are an intellectual property of Docker.

### [Alternatives](#alternatives)

Alternatively, if the set of images you are using is well delimited, you can simply pull them manually and push them to a simple, local, private registry.

Furthermore, if your images are all built in-house, not using the Hub at all and relying entirely on your local registry is the simplest scenario.

### [Gotcha](#gotcha)

It's currently not possible to mirror another private registry. Only the central Hub can be mirrored.

> Note
>
> Mirrors of Docker Hub are still subject to Docker's [fair use policy](https://docs.docker.com/docker-hub/usage/#fair-use).

### [Solution](#solution)

The Registry can be configured as a pull through cache. In this mode a Registry responds to all normal docker pull requests but stores all content locally.

### [Using Registry Access Management (RAM) with a registry mirror](#using-registry-access-management-ram-with-a-registry-mirror)

If Docker Hub access is restricted via your Registry Access Management (RAM) configuration, you will not be able to pull images originating from Docker Hub even if the images are available in your registry mirror.

You will encounter the following error:

```console
Error response from daemon: Access to docker.io has been restricted by your administrators.
```

If you are unable to allow access to Docker Hub, you can manually pull from your registry mirror and optionally, retag the image. For example:

```console
docker pull <your-registry-mirror>[:<port>]/library/busybox
docker tag <your-registry-mirror>[:<port>]/library/busybox:latest busybox:latest
```

## [How does it work?](#how-does-it-work)

The first time you request an image from your local registry mirror, it pulls the image from the public Docker registry and stores it locally before handing it back to you. On subsequent requests, the local registry mirror is able to serve the image from its own storage.

### [What if the content changes on the Hub?](#what-if-the-content-changes-on-the-hub)

When a pull is attempted with a tag, the Registry checks the remote to ensure if it has the latest version of the requested content. Otherwise, it fetches and caches the latest content.

### [What about my disk?](#what-about-my-disk)

In environments with high churn rates, stale data can build up in the cache. When running as a pull through cache the Registry periodically removes old content to save disk space. Subsequent requests for removed content causes a remote fetch and local re-caching.

To ensure best performance and guarantee correctness the Registry cache should be configured to use the `filesystem` driver for storage.

## [Run a Registry as a pull-through cache](#run-a-registry-as-a-pull-through-cache)

The easiest way to run a registry as a pull through cache is to run the official [Registry](https://hub.docker.com/_/registry) image. At least, you need to specify `proxy.remoteurl` within `/etc/docker/registry/config.yml` as described in the following subsection.

Multiple registry caches can be deployed over the same back-end. A single registry cache ensures that concurrent requests do not pull duplicate data, but this property does not hold true for a registry cache cluster.

### [Configure the cache](#configure-the-cache)

To configure a Registry to run as a pull through cache, the addition of a `proxy` section is required to the config file.

To access private images on the Docker Hub, a username and password can be supplied.

```yaml
proxy:
  remoteurl: https://registry-1.docker.io
  username: [username]
  password: [password]
```

> Warning
>
> If you specify a username and password, it's very important to understand that private resources that this user has access to Docker Hub is made available on your mirror. You must secure your mirror by implementing authentication if you expect these resources to stay private!

> Warning
>
> For the scheduler to clean up old entries, `delete` must be enabled in the registry configuration.

### [Configure the Docker daemon](#configure-the-docker-daemon)

Either pass the `--registry-mirror` option when starting `dockerd` manually, or edit [`/etc/docker/daemon.json`](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file) and add the `registry-mirrors` key and value, to make the change persistent.

```json
{
  "registry-mirrors": ["https://<my-docker-mirror-host>"]
}
```

Save the file and reload Docker for the change to take effect.

> Note
>
> Some log messages that appear to be errors are actually informational messages.
>
> Check the `level` field to determine whether the message is warning you about an error or is giving you information. For example, this log message is informational:
>
> ```text
> time="2017-06-02T15:47:37Z" level=info msg="error statting local store, serving from upstream: unknown blob" go.version=go1.7.4
> ```
>
> It's telling you that the file doesn't exist yet in the local cache and is being pulled from upstream.

----
url: https://docs.docker.com/build/ci/github-actions/github-builder/bake/
----

# Bake with Docker GitHub Builder

***

Table of contents

***

The [`bake.yml` reusable workflow](https://github.com/docker/github-builder?tab=readme-ov-file#bake-reusable-workflow) builds from a [Bake definition](https://docs.docker.com/build/bake/) instead of a Dockerfile input set. This page shows how to call the workflow for a target, how to pass Bake overrides and variables, and how to export local output when a Bake file is already the source of truth for your build.

## [Build and push a Bake target](#build-and-push-a-bake-target)

The following workflow builds the `image` target from `docker-bake.hcl` and publishes the result with tags generated from [metadata inputs](https://docs.docker.com/build/ci/github-actions/manage-tags-labels/):

```yaml
name: ci

on:
  push:
    branches:
      - "main"
    tags:
      - "v*"
  pull_request:

permissions:
  contents: read

jobs:
  bake:
    uses: docker/github-builder/.github/workflows/bake.yml@v1
    permissions:
      contents: read # to fetch the repository content
      id-token: write # for signing attestation(s) with GitHub OIDC Token
    with:
      output: image
      push: ${{ github.event_name != 'pull_request' }}
      target: image
      meta-images: name/app
      meta-tags: |
        type=ref,event=branch
        type=ref,event=pr
        type=semver,pattern={{version}}
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
```

Bake workflows build one target per workflow call. Groups and multi-target builds aren't supported because [SLSA provenance](https://docs.docker.com/build/ci/github-actions/attestations/), digest handling, and manifest creation are scoped to a single target.

The workflow validates the definition before the build starts and resolves the target from the files you pass in `files`. Runner selection uses the same `runner` input as the Build workflow. Set a single GitHub-hosted Linux runner label or a platform mapping when the default mapping is not enough. For details, see [runner selection](https://docs.docker.com/build/ci/github-actions/github-builder/architecture/#runner-selection).

## [Override target values and variables](#override-target-values-and-variables)

Because the workflow delegates the build to Bake, you can keep using `set` and `vars` for target-specific overrides:

```yaml
name: ci

on:
  push:
    branches:
      - "main"

permissions:
  contents: read

jobs:
  bake:
    uses: docker/github-builder/.github/workflows/bake.yml@v1
    permissions:
      contents: read # to fetch the repository content
      id-token: write # for signing attestation(s) with GitHub OIDC Token
    with:
      output: image
      push: true
      target: image
      vars: |
        IMAGE_TAG=${{ github.sha }}
      set: |
        *.args.BUILD_RUN_ID=${{ github.run_id }}
        *.platform=linux/amd64,linux/arm64
      cache: true
      cache-scope: image
      meta-images: name/app
      meta-tags: |
        type=sha
      set-meta-annotations: true
    secrets:
      registry-auths: |
        - registry: docker.io
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
```

This form fits repositories that already use Bake groups, target inheritance, and variable expansion. The reusable workflow takes care of Buildx setup, [GitHub Actions cache export](https://docs.docker.com/build/cache/backends/gha/), [Provenance defaults](https://docs.docker.com/build/metadata/attestations/slsa-provenance/), signing behavior, and the final multi-platform manifest. Metadata labels and annotations can be merged into the Bake definition without adding a separate metadata step to your workflow.

## [Export local output from Bake](#export-local-output-from-bake)

If the target should export files instead of publishing an image, switch the workflow output to `local` and upload the artifact:

```yaml
name: ci

on:
  pull_request:

permissions:
  contents: read

jobs:
  bake:
    uses: docker/github-builder/.github/workflows/bake.yml@v1
    permissions:
      contents: read # to fetch the repository content
      id-token: write # for signing attestation(s) with GitHub OIDC Token
    with:
      output: local
      target: binaries
      artifact-upload: true
      artifact-name: bake-output
```

With `output: local`, the workflow injects the matching local output override into the Bake run and merges the uploaded artifacts after the per-platform builds finish. If you need a manual Bake pattern that stays in a normal job, see [Multi-platform image](https://docs.docker.com/build/ci/github-actions/multi-platform/). If your build does not need a Bake definition, use [build.yml](https://docs.docker.com/build/ci/github-actions/github-builder/build/) instead.

----
url: https://docs.docker.com/reference/cli/docker/container/port/
----

# docker container port

***

| Description                                                               | List port mappings or a specific mapping for the container |
| ------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Usage                                                                     | `docker container port CONTAINER [PRIVATE_PORT[/PROTO]]`   |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker port`                                              |

## [Description](#description)

List port mappings or a specific mapping for the container

## [Examples](#examples)

### [Show all mapped ports](#show-all-mapped-ports)

You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or just a specific mapping:

```console
$ docker ps

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS                                            NAMES
b650456536c7        busybox:latest      top                 54 minutes ago      Up 54 minutes       0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp   test

$ docker port test

7890/tcp -> 0.0.0.0:4321
9876/tcp -> 0.0.0.0:1234

$ docker port test 7890/tcp

0.0.0.0:4321

$ docker port test 7890/udp

2014/06/24 11:53:36 Error: No public port '7890/udp' published for test

$ docker port test 7890

0.0.0.0:4321
```

----
url: https://docs.docker.com/reference/cli/docker/plugin/create/
----

# docker plugin create

***

| Description | Create a plugin from a rootfs and configuration. Plugin data directory must contain config.json and rootfs directory. |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| Usage       | `docker plugin create [OPTIONS] PLUGIN PLUGIN-DATA-DIR`                                                               |

## [Description](#description)

Creates a plugin. Before creating the plugin, prepare the plugin's root filesystem as well as the [config.json](/engine/extend/config/).

## [Options](#options)

| Option       | Default | Description                     |
| ------------ | ------- | ------------------------------- |
| `--compress` |         | Compress the context using gzip |

## [Examples](#examples)

The following example shows how to create a sample `plugin`.

```console
$ ls -ls /home/pluginDir

total 4
4 -rw-r--r--  1 root root 431 Nov  7 01:40 config.json
0 drwxr-xr-x 19 root root 420 Nov  7 01:40 rootfs

$ docker plugin create plugin /home/pluginDir

plugin

$ docker plugin ls

ID              NAME            DESCRIPTION                  ENABLED
672d8144ec02    plugin:latest   A sample plugin for Docker   false
```

The plugin can subsequently be enabled for local use or pushed to the public registry.

----
url: https://docs.docker.com/reference/cli/docker/sandbox/create/cagent/
----

# docker sandbox create cagent

***

| Description | Create a sandbox for cagent                                   |
| ----------- | ------------------------------------------------------------- |
| Usage       | `docker sandbox create cagent WORKSPACE [EXTRA_WORKSPACE...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Create a sandbox with access to a host workspace for cagent.

The workspace path is required and will be exposed inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use 'docker sandbox run SANDBOX' to start cagent after creation.

## [Examples](#examples)

### [Create a Cagent sandbox in the current directory](#create-a-cagent-sandbox-in-the-current-directory)

```console
$ docker sandbox create cagent .
```

### [Create with an absolute path](#create-with-an-absolute-path)

```console
$ docker sandbox create cagent /home/user/my-project
```

### [Create and then run](#create-and-then-run)

```console
$ docker sandbox create --name my-cagent cagent ~/my-project
$ docker sandbox run my-cagent
```

----
url: https://docs.docker.com/reference/cli/docker/buildx/build/
----

# docker buildx build

***

| Description                                                               | Start a build                                                                |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Usage                                                                     | `docker buildx build [OPTIONS] PATH \| URL \| -`                             |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker build` `docker builder build` `docker image build` `docker buildx b` |

## [Description](#description)

The `docker buildx build` command starts a build using BuildKit.

## [Options](#options)

| Option                                  | Default | Description                                                                                                                                       |
| --------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`--add-host`](#add-host)               |         | Add a custom host-to-IP mapping (format: `host:ip`)                                                                                               |
| [`--allow`](#allow)                     |         | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`, `device`)                                                          |
| [`--annotation`](#annotation)           |         | Add annotation to the image                                                                                                                       |
| [`--attest`](#attest)                   |         | Attestation parameters (format: `type=sbom,generator=image`)                                                                                      |
| [`--build-arg`](#build-arg)             |         | Set build-time variables                                                                                                                          |
| [`--build-context`](#build-context)     |         | Additional build contexts (e.g., name=path)                                                                                                       |
| [`--cache-from`](#cache-from)           |         | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`)                                                                     |
| [`--cache-to`](#cache-to)               |         | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`)                                                                 |
| [`--call`](#call)                       | `build` | Set method for evaluating build (`check`, `outline`, `targets`)                                                                                   |
| [`--cgroup-parent`](#cgroup-parent)     |         | Set the parent cgroup for the `RUN` instructions during build                                                                                     |
| [`--check`](#check)                     |         | Shorthand for `--call=check`                                                                                                                      |
| [`-f, --file`](#file)                   |         | Name of the Dockerfile (default: `PATH/Dockerfile`)                                                                                               |
| `--iidfile`                             |         | Write the image ID to a file                                                                                                                      |
| `--label`                               |         | Set metadata for an image                                                                                                                         |
| [`--load`](#load)                       |         | Shorthand for `--output=type=docker`                                                                                                              |
| [`--metadata-file`](#metadata-file)     |         | Write build result metadata to a file                                                                                                             |
| [`--network`](#network)                 |         | Set the networking mode for the `RUN` instructions during build                                                                                   |
| `--no-cache`                            |         | Do not use cache when building the image                                                                                                          |
| [`--no-cache-filter`](#no-cache-filter) |         | Do not cache specified stages                                                                                                                     |
| [`-o, --output`](#output)               |         | Output destination (format: `type=local,dest=path`)                                                                                               |
| [`--platform`](#platform)               |         | Set target platform for build                                                                                                                     |
| `--policy`                              |         | Policy configuration (format: `filename=path[,filename=path][,reset=true\|false][,disabled=true\|false][,strict=true\|false][,log-level=level]`)  |
| [`--progress`](#progress)               | `auto`  | Set type of progress output (`auto`, `none`, `plain`, `quiet`, `rawjson`, `tty`). Use plain to show container output                              |
| [`--provenance`](#provenance)           |         | Shorthand for `--attest=type=provenance`                                                                                                          |
| `--pull`                                |         | Always attempt to pull all referenced images                                                                                                      |
| [`--push`](#push)                       |         | Shorthand for `--output=type=registry,unpack=false`                                                                                               |
| `-q, --quiet`                           |         | Suppress the build output and print image ID on success                                                                                           |
| [`--sbom`](#sbom)                       |         | Shorthand for `--attest=type=sbom`                                                                                                                |
| [`--secret`](#secret)                   |         | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`)                                                                         |
| [`--shm-size`](#shm-size)               |         | Shared memory size for build containers                                                                                                           |
| [`--ssh`](#ssh)                         |         | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`)                                               |
| [`-t, --tag`](#tag)                     |         | Image identifier (format: `[registry/]repository[:tag]`)                                                                                          |
| [`--target`](#target)                   |         | Set the target build stage to build                                                                                                               |
| [`--ulimit`](#ulimit)                   |         | Ulimit options                                                                                                                                    |

## [Examples](#examples)

### [Add entries to container hosts file (--add-host)](#add-host)

You can add other hosts into a build container's `/etc/hosts` file by using one or more `--add-host` flags. This example adds static addresses for hosts named `my-hostname` and `my_hostname_v6`:

```console
$ docker buildx build --add-host my_hostname=8.8.8.8 --add-host my_hostname_v6=2001:4860:4860::8888 .
```

If you need your build to connect to services running on the host, you can use the special `host-gateway` value for `--add-host`. In the following example, build containers resolve `host.docker.internal` to the host's gateway IP.

```console
$ docker buildx build --add-host host.docker.internal=host-gateway .
```

You can wrap an IPv6 address in square brackets. `=` and `:` are both valid separators. Both formats in the following example are valid:

```console
$ docker buildx build --add-host my-hostname:10.180.0.1 --add-host my-hostname_v6=[2001:4860:4860::8888] .
```

### [Create annotations (--annotation)](#annotation)

```text
--annotation="key=value"
--annotation="[type:]key=value"
```

Add OCI annotations to the image index, manifest, or descriptor. The following example adds the `foo=bar` annotation to the image manifests:

```console
$ docker buildx build -t TAG --annotation "foo=bar" --push .
```

You can optionally add a type prefix to specify the level of the annotation. By default, the image manifest is annotated. The following example adds the `foo=bar` annotation the image index instead of the manifests:

```console
$ docker buildx build -t TAG --annotation "index:foo=bar" --push .
```

You can specify multiple types, separated by a comma (,) to add the annotation to multiple image components. The following example adds the `foo=bar` annotation to image index, descriptors, manifests:

```console
$ docker buildx build -t TAG --annotation "index,manifest,manifest-descriptor:foo=bar" --push .
```

You can also specify a platform qualifier in square brackets (`[os/arch]`) in the type prefix, to apply the annotation to a subset of manifests with the matching platform. The following example adds the `foo=bar` annotation only to the manifest with the `linux/amd64` platform:

```console
$ docker buildx build -t TAG --annotation "manifest[linux/amd64]:foo=bar" --push .
```

Wildcards are not supported in the platform qualifier; you can't specify a type prefix like `manifest[linux/*]` to add annotations only to manifests which has `linux` as the OS platform.

For more information about annotations, see [Annotations](/build/building/annotations/).

### [Create attestations (--attest)](#attest)

```text
--attest=type=sbom,...
--attest=type=provenance,...
```

Create [image attestations](/build/metadata/attestations/). BuildKit currently supports:

* `sbom` - Software Bill of Materials.

  Use `--attest=type=sbom` to generate an SBOM for an image at build-time. Alternatively, you can use the [`--sbom` shorthand](#sbom).

  For more information, see [here](/build/metadata/attestations/sbom/).

* `provenance` - SLSA Provenance

  Use `--attest=type=provenance` to generate provenance for an image at build-time. Alternatively, you can use the [`--provenance` shorthand](#provenance).

  By default, a minimal provenance attestation will be created for the build result, which will only be attached for images pushed to registries.

  For more information, see [here](/build/metadata/attestations/slsa-provenance/).

### [Allow extra privileged entitlement (--allow)](#allow)

```text
--allow=ENTITLEMENT
```

Allow extra privileged entitlement. List of entitlements:

* `network.host` - Allows executions with host networking.

* `security.insecure` - Allows executions without sandbox. See [related Dockerfile extensions](/reference/dockerfile/#run---security).

* `device` - Allows access to Container Device Interface (CDI) devices.

  * `--allow device` - Grants access to all devices.
  * `--allow device=kind|name` - Grants access to a specific device.
  * `--allow device=kind|name,alias=kind|name` - Grants access to a specific device, with optional aliasing.

For entitlements to be enabled, the BuildKit daemon also needs to allow them with `--allow-insecure-entitlement` (see [`create --buildkitd-flags`](/reference/cli/docker/buildx/create/#buildkitd-flags)).

```console
$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .
```

### [Set build-time variables (--build-arg)](#build-arg)

You can use `ENV` instructions in a Dockerfile to define variable values. These values persist in the built image. Often persistence isn't what you want. Users want to specify variables differently depending on which host they build an image on.

A good example is `http_proxy` or source versions for pulling intermediate files. The `ARG` instruction lets Dockerfile authors define values that users can set at build-time using the `--build-arg` flag:

```console
$ docker buildx build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567 .
```

This flag allows you to pass the build-time variables that are accessed like regular environment variables in the `RUN` instruction of the Dockerfile. These values don't persist in the intermediate or final images like `ENV` values do. You must add `--build-arg` for each build argument.

Using this flag doesn't alter the output you see when the build process echoes the`ARG` lines from the Dockerfile.

For detailed information on using `ARG` and `ENV` instructions, see the [Dockerfile reference](/reference/dockerfile/).

You can also use the `--build-arg` flag without a value, in which case the daemon propagates the value from the local environment into the Docker container it's building:

```console
$ export HTTP_PROXY=http://10.20.30.2:1234
$ docker buildx build --build-arg HTTP_PROXY .
```

This example is similar to how `docker run -e` works. Refer to the [`docker run` documentation](/reference/cli/docker/container/run/#env) for more information.

There are also useful built-in build arguments, such as:

* `BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool>`: trigger git context to keep the `.git` directory
* `BUILDKIT_INLINE_CACHE=<bool>`: inline cache metadata to image config or not
* `BUILDKIT_MULTI_PLATFORM=<bool>`: opt into deterministic output regardless of multi-platform output or not

```console
$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .
```

Learn more about the built-in build arguments in the [Dockerfile reference docs](/reference/dockerfile/#buildkit-built-in-build-args).

### [Additional build contexts (--build-context)](#build-context)

```text
--build-context=name=VALUE
```

Define additional build context with specified contents.

In a Dockerfile:

* the context can be accessed when `FROM name` or `--from=name` is used
* the context overrides a stage called `name` when used as `FROM ... AS name`
* the context overrides a `#syntax` directive when used as `#syntax=name`

The value can be a:

* local source directory
* [local OCI layout compliant directory](https://github.com/opencontainers/image-spec/blob/main/image-layout.md)
* container image
* Git URL
* HTTP URL

#### [Use a local path](#local-path)

Expose a secondary local source directory:

```console
$ docker buildx build --build-context project=path/to/project/source .
# docker buildx build --build-context project=https://github.com/myuser/project.git .
```

#### [Use a container image](#docker-image)

Use the `docker-image://` scheme.

Replace `alpine:latest` with a pinned one:

```console
$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .
```

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
COPY --from=project myfile /
```

#### [Use an OCI layout directory as build context](#source-oci-layout)

Use the `oci-layout:///` scheme.

Source an image from a local [OCI layout compliant directory](https://github.com/opencontainers/image-spec/blob/main/image-layout.md), either by tag, or by digest:

```console
$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout:<tag>
$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256:<digest>
```

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN apk add git
COPY --from=foo myfile /

FROM foo
```

The OCI layout directory must be compliant with the [OCI layout specification](https://github.com/opencontainers/image-spec/blob/main/image-layout.md).

### [Override the configured builder instance (--builder)](#builder)

Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

### [Use an external cache source for a build (--cache-from)](#cache-from)

```text
--cache-from=[NAME|type=TYPE[,KEY=VALUE]]
```

Use an external cache source for a build. Supported types are:

* [`registry`](/build/cache/backends/registry/) can import cache from a cache manifest or (special) image configuration on the registry.
* [`local`](/build/cache/backends/local/) can import cache from local files previously exported with `--cache-to`.
* [`gha`](/build/cache/backends/gha/) can import cache from a previously exported cache with `--cache-to` in your GitHub repository.
* [`s3`](/build/cache/backends/s3/) can import cache from a previously exported cache with `--cache-to` in your S3 bucket.
* [`azblob`](/build/cache/backends/azblob/) can import cache from a previously exported cache with `--cache-to` in your Azure bucket.

If no type is specified, `registry` exporter is used with a specified reference.

```console
$ docker buildx build --cache-from=user/app:cache .
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
$ docker buildx build --cache-from=type=gha .
$ docker buildx build --cache-from=type=s3,region=eu-west-1,bucket=mybucket .
```

> Note
>
> More info about cache exporters and available attributes can be found in the [Cache storage backends documentation](/build/cache/backends/)

### [Export build cache to an external cache destination (--cache-to)](#cache-to)

```text
--cache-to=[NAME|type=TYPE[,KEY=VALUE]]
```

Export build cache to an external cache destination. Supported types are:

* [`registry`](/build/cache/backends/registry/) exports build cache to a cache manifest in the registry.
* [`local`](/build/cache/backends/local/) exports cache to a local directory on the client.
* [`inline`](/build/cache/backends/inline/) writes the cache metadata into the image configuration.
* [`gha`](/build/cache/backends/gha/) exports cache through the GitHub Actions Cache service API.
* [`s3`](/build/cache/backends/s3/) exports cache to a S3 bucket.
* [`azblob`](/build/cache/backends/azblob/) exports cache to an Azure bucket.

```console
$ docker buildx build --cache-to=user/app:cache .
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
$ docker buildx build --cache-to=type=gha .
$ docker buildx build --cache-to=type=s3,region=eu-west-1,bucket=mybucket .
```

> Note
>
> More info about cache exporters and available attributes can be found in the [Cache storage backends documentation](/build/cache/backends/)

### [Invoke a frontend method (--call)](#call)

```text
--call=[build|check|outline|targets]
```

BuildKit frontends can support alternative modes of executions for builds, using frontend methods. Frontend methods are a way to change or extend the behavior of a build invocation, which lets you, for example, inspect, validate, or generate alternative outputs from a build.

The `--call` flag for `docker buildx build` lets you specify the frontend method that you want to execute. If this flag is unspecified, it defaults to executing the build and evaluating [build checks](/reference/build-checks/).

For Dockerfiles, the available methods are:

| Command                | Description                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `build` (default)      | Execute the build and evaluate build checks for the current build target.                                     |
| `check`                | Evaluate build checks for the either the entire Dockerfile or the selected target, without executing a build. |
| `outline`              | Show the build arguments that you can set for a target, and their default values.                             |
| `targets`              | List all the build targets in the Dockerfile.                                                                 |
| `subrequests.describe` | List all the frontend methods that the current frontend supports.                                             |

Note that other frontends may implement these or other methods. To see the list of available methods for the frontend you're using, use `--call=subrequests.describe`.

```console
$ docker buildx build -q --call=subrequests.describe .

NAME                 VERSION DESCRIPTION
outline              1.0.0   List all parameters current build target supports
targets              1.0.0   List all targets current build supports
subrequests.describe 1.0.0   List available subrequest types
```

#### [Descriptions](#descriptions)

The [`--call=targets`](#call-targets) and [`--call=outline`](#call-outline) methods include descriptions for build targets and arguments, if available. Descriptions are generated from comments in the Dockerfile. A comment on the line before a `FROM` instruction becomes the description of a build target, and a comment before an `ARG` instruction the description of a build argument. The comment must lead with the name of the stage or argument, for example:

```dockerfile
# syntax=docker/dockerfile:1

# GO_VERSION sets the Go version for the build
ARG GO_VERSION=1.22

# base-builder is the base stage for building the project
FROM golang:${GO_VERSION} AS base-builder
```

When you run `docker buildx build --call=outline`, the output includes the descriptions, as follows:

```console
$ docker buildx build -q --call=outline .

TARGET:      base-builder
DESCRIPTION: is the base stage for building the project

BUILD ARG    VALUE   DESCRIPTION
GO_VERSION   1.22    sets the Go version for the build
```

For more examples on how to write Dockerfile docstrings, check out [the Dockerfile for Docker docs](https://github.com/docker/docs/blob/main/Dockerfile).

#### [Call: check (--check)](#check)

The `check` method evaluates build checks without executing the build. The `--check` flag is a convenient shorthand for `--call=check`. Use the `check` method to validate the build configuration before starting the build.

```console
$ docker buildx build -q --check https://github.com/docker/docs.git

WARNING: InvalidBaseImagePlatform
Base image wjdp/htmltest:v0.17.0 was pulled with platform "linux/amd64", expected "linux/arm64" for current build
Dockerfile:43
--------------------
  41 |         "#content/desktop/previous-versions/*.md"
  42 |
  43 | >>> FROM wjdp/htmltest:v${HTMLTEST_VERSION} AS test
  44 |     WORKDIR /test
  45 |     COPY --from=build /out ./public
--------------------
```

Using `--check` without specifying a target evaluates the entire Dockerfile. If you want to evaluate a specific target, use the `--target` flag.

#### [Call: outline](#call-outline)

The `outline` method prints the name of the specified target (or the default target, if `--target` isn't specified), and the build arguments that the target consumes, along with their default values, if set.

The following example shows the default target `release` and its build arguments:

```console
$ docker buildx build -q --call=outline https://github.com/docker/docs.git

TARGET:      release
DESCRIPTION: is an empty scratch image with only compiled assets

BUILD ARG          VALUE     DESCRIPTION
GO_VERSION         1.22      sets the Go version for the base stage
HUGO_VERSION       0.127.0
HUGO_ENV                     sets the hugo.Environment (production, development, preview)
DOCS_URL                     sets the base URL for the site
PAGEFIND_VERSION   1.1.0
```

This means that the `release` target is configurable using these build arguments:

```console
$ docker buildx build \
  --build-arg GO_VERSION=1.22 \
  --build-arg HUGO_VERSION=0.127.0 \
  --build-arg HUGO_ENV=production \
  --build-arg DOCS_URL=https://example.com \
  --build-arg PAGEFIND_VERSION=1.1.0 \
  --target release https://github.com/docker/docs.git
```

#### [Call: targets](#call-targets)

The `targets` method lists all the build targets in the Dockerfile. These are the stages that you can build using the `--target` flag. It also indicates the default target, which is the target that will be built when you don't specify a target.

```console
$ docker buildx build -q --call=targets https://github.com/docker/docs.git

TARGET            DESCRIPTION
base              is the base stage with build dependencies
node              installs Node.js dependencies
hugo              downloads and extracts the Hugo binary
build-base        is the base stage for building the site
dev               is for local development with Docker Compose
build             creates production builds with Hugo
lint              lints markdown files
test              validates HTML output and checks for broken links
update-modules    downloads and vendors Hugo modules
vendor            is an empty stage with only vendored Hugo modules
build-upstream    builds an upstream project with a replacement module
validate-upstream validates HTML output for upstream builds
unused-media      checks for unused graphics and other media
pagefind          installs the Pagefind runtime
index             generates a Pagefind index
test-go-redirects checks that the /go/ redirects are valid
release (default) is an empty scratch image with only compiled assets
```

### [Use a custom parent cgroup (--cgroup-parent)](#cgroup-parent)

When you run `docker buildx build` with the `--cgroup-parent` option, the daemon runs the containers used in the build with the [corresponding `docker run` flag](/reference/cli/docker/container/run/#cgroup-parent).

### [Specify a Dockerfile (-f, --file)](#file)

```console
$ docker buildx build -f [PATH|URL|-] .
```

Specifies the location of the Dockerfile to use. If unspecified, a file named `Dockerfile` at the root of the build context is used by default.

The supported inputs formats are:

* [`Local file path`](#local-file-path)
* [`Remote URL`](#remote-url)
* [`Standard input`](#standard-input)

#### [Local file path](#local-file-path)

To specify a path to a local Dockerfile:

```console
$ docker buildx build -f path/to/Dockerfile .
```

#### [Remote URL](#remote-url)

To specify a URL to a remote Dockerfile:

```console
$ docker buildx build -f https://raw.githubusercontent.com/docker/buildx/refs/tags/v0.29.0/Dockerfile .
```

#### [Standard input](#standard-input)

To read a Dockerfile from stdin, use `-` as the argument:

```console
$ cat Dockerfile | docker buildx build -f - .
```

### [Load the single-platform build result to `docker images` (--load)](#load)

Shorthand for [`--output=type=docker`](#docker). Will automatically load the single-platform build result to `docker images`.

### [Write build result metadata to a file (--metadata-file)](#metadata-file)

To output build metadata such as the image digest, pass the `--metadata-file` flag. The metadata will be written as a JSON object to the specified file. The directory of the specified file must already exist and be writable.

```console
$ docker buildx build --load --metadata-file metadata.json .
$ cat metadata.json
```

```json
{
  "buildx.build.provenance": {},
  "buildx.build.ref": "mybuilder/mybuilder0/0fjb6ubs52xx3vygf6fgdl611",
  "buildx.build.warnings": {},
  "containerimage.config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
  "containerimage.descriptor": {
    "annotations": {
      "config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
      "org.opencontainers.image.created": "2022-02-08T21:28:03Z"
    },
    "digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 506
  },
  "containerimage.digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3"
}
```

> Note
>
> Build record [provenance](/build/metadata/attestations/slsa-provenance/#provenance-attestation-example) (`buildx.build.provenance`) includes minimal provenance by default. Set the `BUILDX_METADATA_PROVENANCE` environment variable to customize this behavior:
>
> * `min` sets minimal provenance (default).
> * `max` sets full provenance.
> * `disabled`, `false` or `0` doesn't set any provenance.

> Note
>
> Build warnings (`buildx.build.warnings`) are not included by default. Set the `BUILDX_METADATA_WARNINGS` environment variable to `1` or `true` to include them.

### [Set the networking mode for the RUN instructions during build (--network)](#network)

Available options for the networking mode are:

* `default` (default): Run in the default network.
* `none`: Run with no network access.
* `host`: Run in the host’s network environment.

Find more details in the [Dockerfile reference](/reference/dockerfile/#run---network).

### [Ignore build cache for specific stages (--no-cache-filter)](#no-cache-filter)

The `--no-cache-filter` lets you specify one or more stages of a multi-stage Dockerfile for which build cache should be ignored. To specify multiple stages, use a comma-separated syntax:

```console
$ docker buildx build --no-cache-filter stage1,stage2,stage3 .
```

For example, the following Dockerfile contains four stages:

* `base`
* `install`
* `test`
* `release`

```dockerfile
# syntax=docker/dockerfile:1

FROM oven/bun:1 AS base
WORKDIR /app

FROM base AS install
WORKDIR /temp/dev
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=bun.lockb,target=bun.lockb \
    bun install --frozen-lockfile

FROM base AS test
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
RUN bun test

FROM base AS release
ENV NODE_ENV=production
COPY --from=install /temp/dev/node_modules node_modules
COPY . .
ENTRYPOINT ["bun", "run", "index.js"]
```

To ignore the cache for the `install` stage:

```console
$ docker buildx build --no-cache-filter install .
```

To ignore the cache the `install` and `release` stages:

```console
$ docker buildx build --no-cache-filter install,release .
```

The arguments for the `--no-cache-filter` flag must be names of stages.

### [Set the export action for the build result (-o, --output)](#output)

```text
-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]
```

Sets the export action for the build result. The default output, when using the `docker` [build driver](/build/builders/drivers/), is a container image exported to the local image store. The `--output` flag makes this step configurable allows export of results directly to the client's filesystem, an OCI image tarball, a registry, and more.

Buildx with `docker` driver only supports the local, tarball, and image [exporters](/build/exporters/). The `docker-container` driver supports all exporters.

If you only specify a filepath as the argument to `--output`, Buildx uses the local exporter. If the value is `-`, Buildx uses the `tar` exporter and writes the output to stdout.

```console
$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o - . > out.tar
$ docker buildx build -o type=docker .
$ docker buildx build -o type=docker,dest=- . > myimage.tar
$ docker buildx build -t tonistiigi/foo -o type=registry
```

You can export multiple outputs by repeating the flag.

Supported exported types are:

* [`local`](#local)
* [`tar`](#tar)
* [`oci`](#oci)
* [`docker`](#docker)
* [`image`](#image)
* [`registry`](#registry)

#### [`local`](#local)

The `local` export type writes all result files to a directory on the client. The new files will be owned by the current user. On multi-platform builds, all results will be put in subdirectories by their platform.

Attribute key:

* `dest` - destination directory where files will be written

For more information, see [Local and tar exporters](/build/exporters/local-tar/).

#### [`tar`](#tar)

The `tar` export type writes all result files as a single tarball on the client. On multi-platform builds all results will be put in subdirectories by their platform.

Attribute key:

* `dest` - destination path where tarball will be written. “-” writes to stdout.

For more information, see [Local and tar exporters](/build/exporters/local-tar/).

#### [`oci`](#oci)

The `oci` export type writes the result image or manifest list as an [OCI image layout](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-layout.md) tarball on the client.

Attribute key:

* `dest` - destination path where tarball will be written. “-” writes to stdout.

For more information, see [OCI and Docker exporters](/build/exporters/oci-docker/).

#### [`docker`](#docker)

The `docker` export type writes the single-platform result image as a [Docker image specification](https://github.com/docker/docker/blob/v20.10.2/image/spec/v1.2.md) tarball on the client. Tarballs created by this exporter are also OCI compatible.

The default image store in Docker Engine doesn't support loading multi-platform images. You can enable the containerd image store, or push multi-platform images is to directly push to a registry, see [`registry`](#registry).

Attribute keys:

* `dest` - destination path where tarball will be written. If not specified, the tar will be loaded automatically to the local image store.
* `context` - name for the Docker context where to import the result

For more information, see [OCI and Docker exporters](/build/exporters/oci-docker/).

#### [`image`](#image)

The `image` exporter writes the build result as an image or a manifest list. When using `docker` driver the image will appear in `docker images`. Optionally, image can be automatically pushed to a registry by specifying attributes.

Attribute keys:

* `name` - name (references) for the new image.
* `push` - Boolean to automatically push the image.

For more information, see [Image and registry exporters](/build/exporters/image-registry/).

#### [`registry`](#registry)

The `registry` exporter is a shortcut for `type=image,push=true`.

For more information, see [Image and registry exporters](/build/exporters/image-registry/).

### [Set the target platforms for the build (--platform)](#platform)

```text
--platform=value[,value]
```

Set the target platform for the build. All `FROM` commands inside the Dockerfile without their own `--platform` flag will pull base images for this platform and this value will also be the platform of the resulting image.

The default value is the platform of the BuildKit daemon where the build runs. The value takes the form of `os/arch` or `os/arch/variant`. For example, `linux/amd64` or `linux/arm/v7`. Additionally, the `--platform` flag also supports a special `local` value, which tells BuildKit to use the platform of the BuildKit client that invokes the build.

When using `docker-container` driver with `buildx`, this flag can accept multiple values as an input separated by a comma. With multiple values the result will be built for all of the specified platforms and joined together into a single manifest list.

If the `Dockerfile` needs to invoke the `RUN` command, the builder needs runtime support for the specified platform. In a clean setup, you can only execute `RUN` commands for your system architecture. If your kernel supports [`binfmt_misc`](https://en.wikipedia.org/wiki/Binfmt_misc) launchers for secondary architectures, buildx will pick them up automatically. Docker Desktop releases come with `binfmt_misc` automatically configured for `arm64` and `arm` architectures. You can see what runtime platforms your current builder instance supports by running `docker buildx inspect --bootstrap`.

Inside a `Dockerfile`, you can access the current platform value through `TARGETPLATFORM` build argument. Refer to the [Dockerfile reference](/reference/dockerfile/#automatic-platform-args-in-the-global-scope) for the full description of automatic platform argument variants .

You can find the formatting definition for the platform specifier in the [containerd source code](https://github.com/containerd/containerd/blob/v1.4.3/platforms/platforms.go#L63).

```console
$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .
```

### [Set type of progress output (--progress)](#progress)

```text
--progress=VALUE
```

Set type of progress output. Supported values are:

* `auto` (default): Uses the `tty` mode if the client is a TTY, or `plain` otherwise
* `tty`: An interactive stream of the output with color and redrawing
* `plain`: Prints the raw build progress in a plaintext format
* `quiet`: Suppress the build output and print image ID on success (same as `--quiet`)
* `rawjson`: Prints the raw build progress as JSON lines

> Note
>
> You can also use the `BUILDKIT_PROGRESS` environment variable to set its value.

The following example uses `plain` output during the build:

```console
$ docker buildx build --load --progress=plain .

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s

#2 [internal] load .dockerignore
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...
```

> Note
>
> Check also the [`BUILDKIT_COLORS`](/build/building/variables/#buildkit_colors) environment variable for modifying the colors of the terminal output.

The `rawjson` output marshals the solve status events from BuildKit to JSON lines. This mode is designed to be read by an external program.

### [Create provenance attestations (--provenance)](#provenance)

Shorthand for [`--attest=type=provenance`](#attest), used to configure provenance attestations for the build result. For example, `--provenance=mode=max` can be used as an abbreviation for `--attest=type=provenance,mode=max`.

Additionally, `--provenance` can be used with Boolean values to enable or disable provenance attestations. For example, `--provenance=false` disables all provenance attestations, while `--provenance=true` enables all provenance attestations.

By default, a minimal provenance attestation will be created for the build result. Note that the default image store in Docker Engine doesn't support attestations. Provenance attestations only persist for images pushed directly to a registry if you use the default image store. Alternatively, you can switch to using the containerd image store.

For more information about provenance attestations, see [here](/build/metadata/attestations/slsa-provenance/).

### [Push the build result to a registry (--push)](#push)

Shorthand for [`--output=type=registry`](#registry). Will automatically push the build result to registry.

### [Create SBOM attestations (--sbom)](#sbom)

Shorthand for [`--attest=type=sbom`](#attest), used to configure SBOM attestations for the build result. For example, `--sbom=generator=<user>/<generator-image>` can be used as an abbreviation for `--attest=type=sbom,generator=<user>/<generator-image>`.

Additionally, `--sbom` can be used with Boolean values to enable or disable SBOM attestations. For example, `--sbom=false` disables all SBOM attestations.

Note that the default image store in Docker Engine doesn't support attestations. Provenance attestations only persist for images pushed directly to a registry if you use the default image store. Alternatively, you can switch to using the containerd image store.

For more information, see [here](/build/metadata/attestations/sbom/).

### [Secret to expose to the build (--secret)](#secret)

```text
--secret=[type=TYPE[,KEY=VALUE]
```

Exposes secrets (authentication credentials, tokens) to the build. A secret can be mounted into the build using a `RUN --mount=type=secret` mount in the [Dockerfile](/reference/dockerfile/#run---mounttypesecret). For more information about how to use build secrets, see [Build secrets](/build/building/secrets/).

Supported types are:

* [`type=file`](#typefile)
* [`type=env`](#typeenv)

Buildx attempts to detect the `type` automatically if unset. If an environment variable with the same key as `id` is set, then Buildx uses `type=env` and the variable value becomes the secret. If no such environment variable is set, and `type` is not set, then Buildx falls back to `type=file`.

#### [`type=file`](#typefile)

Source a build secret from a file.

##### [`type=file` synopsis](#typefile-synopsis)

```console
$ docker buildx build --secret [type=file,]id=ID[,src=FILEPATH] .
```

##### [`type=file` attributes](#typefile-attributes)

| Key             | Description                                                                                           | Default                    |
| --------------- | ----------------------------------------------------------------------------------------------------- | -------------------------- |
| `id`            | ID of the secret.                                                                                     | N/A (this key is required) |
| `src`, `source` | Filepath of the file containing the secret value (absolute or relative to current working directory). | `id` if unset.             |

###### [`type=file` usage](#typefile-usage)

In the following example, `type=file` is automatically detected because no environment variable matching `aws` (the ID) is set.

```console
$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
```

```dockerfile
# syntax=docker/dockerfile:1
FROM python:3
RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
  aws s3 cp s3://... ...
```

#### [`type=env`](#typeenv)

Source a build secret from an environment variable.

##### [`type=env` synopsis](#typeenv-synopsis)

```console
$ docker buildx build --secret [type=env,]id=ID[,env=VARIABLE] .
```

##### [`type=env` attributes](#typeenv-attributes)

| Key                    | Description                                     | Default                    |
| ---------------------- | ----------------------------------------------- | -------------------------- |
| `id`                   | ID of the secret.                               | N/A (this key is required) |
| `env`, `src`, `source` | Environment variable to source the secret from. | `id` if unset.             |

##### [`type=env` usage](#typeenv-usage)

In the following example, `type=env` is automatically detected because an environment variable matching `id` is set.

```console
$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .
```

```dockerfile
# syntax=docker/dockerfile:1
FROM node:alpine
RUN --mount=type=bind,target=. \
  --mount=type=secret,id=SECRET_TOKEN,env=SECRET_TOKEN \
  yarn run test
```

In the following example, the build argument `SECRET_TOKEN` is set to contain the value of the environment variable `API_KEY`.

```console
$ API_KEY=token docker buildx build --secret id=SECRET_TOKEN,env=API_KEY .
```

You can also specify the name of the environment variable with `src` or `source`:

```console
$ API_KEY=token docker buildx build --secret type=env,id=SECRET_TOKEN,src=API_KEY .
```

> Note
>
> Specifying the environment variable name with `src` or `source`, you are required to set `type=env` explicitly, or else Buildx assumes that the secret is `type=file`, and looks for a file with the name of `src` or `source` (in this case, a file named `API_KEY` relative to the location where the `docker buildx build` command was executed.

### [Shared memory size for build containers (--shm-size)](#shm-size)

Sets the size of the shared memory allocated for build containers when using `RUN` instructions.

The format is `<number><unit>`. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes.

> Note
>
> In most cases, it is recommended to let the builder automatically determine the appropriate configurations. Manual adjustments should only be considered when specific performance tuning is required for complex build scenarios.

### [SSH agent socket or keys to expose to the build (--ssh)](#ssh)

```text
--ssh=default|<id>[=<socket>|<key>[,<key>]]
```

This can be useful when some commands in your Dockerfile need specific SSH authentication (e.g., cloning a private repository).

`--ssh` exposes SSH agent socket or keys to the build and can be used with the [`RUN --mount=type=ssh` mount](/reference/dockerfile/#run---mounttypessh).

Example to access Gitlab using an SSH agent socket:

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh ssh -q -T git@gitlab.com 2>&1 | tee /hello
# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" should be printed here
# with the type of build progress is defined as `plain`.
```

```console
$ eval $(ssh-agent)
$ ssh-add ~/.ssh/id_rsa
(Input your passphrase here)
$ docker buildx build --ssh default=$SSH_AUTH_SOCK .
```

### [Tag an image (-t, --tag)](#tag)

```console
$ docker buildx build -t docker/apache:2.0 .
```

This examples builds in the same way as the previous example, but it then tags the resulting image. The repository name will be `docker/apache` and the tag `2.0`.

[Read more about valid tags](/reference/cli/docker/image/tag/).

You can apply multiple tags to an image. For example, you can apply the `latest` tag to a newly built image and add another tag that references a specific version.

For example, to tag an image both as `docker/fedora-jboss:latest` and `docker/fedora-jboss:v2.1`, use the following:

```console
$ docker buildx build -t docker/fedora-jboss:latest -t docker/fedora-jboss:v2.1 .
```

### [Specifying target build stage (--target)](#target)

When building a Dockerfile with multiple build stages, use the `--target` option to specify an intermediate build stage by name as a final stage for the resulting image. The builder skips commands after the target stage.

```dockerfile
FROM debian AS build-env
# ...

FROM alpine AS production-env
# ...
```

```console
$ docker buildx build -t mybuildimage --target build-env .
```

### [Set ulimits (--ulimit)](#ulimit)

`--ulimit` overrides the default ulimits of build's containers when using `RUN` instructions and are specified with a soft and hard limit as such: `<type>=<soft limit>[:<hard limit>]`, for example:

```console
$ docker buildx build --ulimit nofile=1024:1024 .
```

> Note
>
> If you don't provide a `hard limit`, the `soft limit` is used for both values. If no `ulimits` are set, they're inherited from the default `ulimits` set on the daemon.

> Note
>
> In most cases, it is recommended to let the builder automatically determine the appropriate configurations. Manual adjustments should only be considered when specific performance tuning is required for complex build scenarios.

----
url: https://docs.docker.com/reference/cli/docker/swarm/unlock/
----

# docker swarm unlock

***

| Description | Unlock swarm          |
| ----------- | --------------------- |
| Usage       | `docker swarm unlock` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Unlocks a locked manager using a user-supplied unlock key. This command must be used to reactivate a manager after its Docker daemon restarts if the autolock setting is turned on. The unlock key is printed at the time when autolock is enabled, and is also available from the `docker swarm unlock-key` command.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Examples](#examples)

```console
$ docker swarm unlock
Enter unlock key:
```

----
url: https://docs.docker.com/ai/sandboxes/agents/claude-code/
----

# Claude Code

***

Table of contents

***

Official documentation: [Claude Code](https://code.claude.com/docs)

## [Quick start](#quick-start)

Launch Claude Code in a sandbox by pointing it at a project directory:

```console
$ sbx run claude ~/my-project
```

The workspace parameter defaults to the current directory, so `sbx run claude` from inside your project works too. To start Claude with a specific prompt:

```console
$ sbx run claude --name my-sandbox -- "Add error handling to the login function"
```

Everything after `--` is passed directly to Claude Code. You can also pipe in a prompt from a file with `-- "$(cat prompt.txt)"`.

## [Authentication](#authentication)

Claude Code requires either an Anthropic API key or a Claude subscription.

**API key**: Store your key using [stored secrets](https://docs.docker.com/ai/sandboxes/security/credentials/#stored-secrets):

```console
$ sbx secret set -g anthropic
```

Alternatively, export the `ANTHROPIC_API_KEY` environment variable in your shell before running the sandbox. See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for details on both methods.

**Claude subscription**: If no API key is set, Claude Code prompts you to authenticate interactively using OAuth. The proxy handles the OAuth flow, so credentials aren't stored inside the sandbox.

## [Configuration](#configuration)

Sandboxes don't pick up user-level configuration from your host, such as `~/.claude`. Only project-level configuration in the working directory is available inside the sandbox. See [Why doesn't the sandbox use my user-level agent configuration?](https://docs.docker.com/ai/sandboxes/faq/#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for workarounds.

### [Default startup command](#default-startup-command)

Without extra args, the sandbox runs:

```text
claude --dangerously-skip-permissions
```

Args after `--` replace these defaults rather than being appended. To keep `--dangerously-skip-permissions`, include it yourself:

```console
$ sbx run claude -- --dangerously-skip-permissions -c
```

See the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference) for available options.

## [Agents view](#agents-view)

Claude Code's [agents view](https://code.claude.com/docs/en/agent-view) dispatches tasks to subagents that work in parallel, each in its own Git worktree. Pair it with [clone mode](https://docs.docker.com/ai/sandboxes/usage/#clone-mode) for an isolated multi-agent workflow:

```console
$ sbx run --clone claude -- agents
```

This invocation replaces the [default startup command](#default-startup-command), so it doesn't include `--dangerously-skip-permissions` and you can't switch to bypass-permissions mode inside the sandbox. To work around this, either use Claude Code's auto mode or pass the flag explicitly:

```console
$ sbx run --clone claude -- --dangerously-skip-permissions agents
```

The subagents' worktrees live inside the sandbox's private clone — none of them touches your host repository. Each subagent commits to its own branch, and you review the work from the host by fetching the `sandbox-<sandbox-name>` remote:

```console
$ git fetch sandbox-<sandbox-name>
$ git diff main..sandbox-<sandbox-name>/<branch>
```

See [Git workflow](https://docs.docker.com/ai/sandboxes/usage/#git-workflow) for clone-mode details.

## [Base image](#base-image)

The sandbox uses `docker/sandbox-templates:claude-code`. See [Templates](https://docs.docker.com/ai/sandboxes/customize/templates/) to build your own image on top of this base.

## [Use a local model](#use-a-local-model)

To run Claude Code in a sandbox against a local model on your host through Docker Model Runner, see [Run Claude Code in a Docker Sandbox with Docker Model Runner](/guides/claude-code-sandbox-model-runner/). For the host-only version without a sandbox, see [Use Claude Code with Docker Model Runner](/guides/claude-code-model-runner/).

----
url: https://docs.docker.com/guides/postgresql/networking-and-connectivity/
----

# Networking and connectivity

***

Table of contents

***

This guide covers two common ways to connect to PostgreSQL running in Docker:

* Container-to-container: Connect from your application container to PostgreSQL over a private Docker network. No ports need to be exposed to the host.
* Host-to-container: Connect from your laptop or development machine using `localhost` and a published port.

Prerequisite: This guide assumes you have PostgreSQL running with persistent storage. If you don't, follow the [Immediate Setup & Data Persistence](/guides/postgresql/immediate-setup-and-data-persistence/) guide first.

## [Internal network access (container-to-container)](#internal-network-access-container-to-container)

When your application runs in another container, connecting to PostgreSQL through a user-defined bridge network is the recommended approach. This setup provides automatic DNS resolution, so your application can connect to PostgreSQL using the container name as the hostname, without needing to track IP addresses.

> Note
>
> Why not use the default bridge network? While containers on the default bridge network can communicate, they can only do so by IP address. Since container IP addresses change when containers restart, this would require updating your PostgreSQL connection strings each time. User-defined bridge networks solve this by providing automatic DNS resolution, ensuring your PostgreSQL connection strings remain stable even if containers restart and receive new IP addresses.

Here's a quick comparison:

> Note
>
> The following examples show the difference in approach. To actually test this, follow the steps in this guide to set up containers on the appropriate networks first.

With the default bridge network, you'd need to find the IP address first:

```bash
# Get the container's IP address (changes on restart)
docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' postgres-dev
# Output: 172.17.0.2

# Then connect using that IP address from another container
# (No --network flag needed - containers default to bridge network)
docker run --rm -it \
  -e PGPASSWORD=mysecretpassword \
  postgres:18 \
  psql -h 172.17.0.2 -U postgres
```

With a user-defined network, you simply use the container name:

```bash
# Container name works directly - no IP lookup needed
docker run --rm -it \
  --network my-app-net \
  -e PGPASSWORD=mysecretpassword \
  postgres:18 \
  psql -h postgres-dev -U postgres
```

### [Step 1: Create a user-defined network](#step-1-create-a-user-defined-network)

```bash
docker network create my-app-net

# Example Output
ab7f984be43a0ca15534a9ee568716ddbe869a5875077fad3ef3192e3af7d288

docker network ls
# Output
ab7f984be43a   my-app-net    bridge    local
```

### [Step 2: Run PostgreSQL on that network (no port publishing)](#step-2-run-postgresql-on-that-network-no-port-publishing)

Notice there is no `-p 5432:5432` here. This keeps PostgreSQL internal to Docker and not accessible from the host machine, which is more secure for production environments.

```bash
docker run -d --name postgres-dev \
  --network my-app-net \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres_data:/var/lib/postgresql \
  postgres:18

  # Output
CONTAINER ID  IMAGE        COMMAND                 CREATED         STATUS        PORTS     NAMES
6d351ed89efc  postgres:18  "docker-entrypoint.s…"  9 seconds ago   Up 8 seconds  5432/tcp  postgres-dev
```

### [Step 3: Connect from another container using the Postgres container name](#step-3-connect-from-another-container-using-the-postgres-container-name)

You can test connectivity with a temporary `psql` client container:

```bash
docker run --rm -it \
  --network my-app-net \
  -e PGPASSWORD=mysecretpassword \
  postgres:18 \
  psql -h postgres-dev -U postgres
```

Key point: `-h postgres-dev` works because Docker DNS resolves the container name on a user-defined network. The container name acts as the hostname.

### [Connection string examples](#connection-string-examples)

When connecting from your application container, use these PostgreSQL connection strings:

* PostgreSQL URI format: This is the standard PostgreSQL connection URI format that combines all connection parameters into a single string, widely supported by PostgreSQL clients and libraries.

  ```bash
  postgresql://postgres:mysecretpassword@postgres-dev:5432/postgres
  ```

  This command demonstrates passing a PostgreSQL URI connection string as an environment variable to a container, which your application can then read to connect to the database.

  Example usage in a Docker run command:

  ```bash
  docker run --rm -it \
    --network my-app-net \
    -e DATABASE_URL="postgresql://postgres:mysecretpassword@postgres-dev:5432/postgres" \
    alpine:latest \
    sh -c 'echo "DATABASE_URL is set to: $DATABASE_URL"'
  ```

* PostgreSQL connection parameters: This format uses key-value pairs separated by spaces, which many PostgreSQL client libraries accept as an alternative to URI format.

  ```bash
  host=postgres-dev
  port=5432
  user=postgres
  password=mysecretpassword
  dbname=postgres
  ```

  Example usage in application code (Python with psycopg2):

  ```python
  conn = psycopg2.connect(
      host="postgres-dev",
      port=5432,
      user="postgres",
      password="mysecretpassword",
      dbname="postgres"
  )
  ```

* Connecting to a specific database: Replace the database name in the connection string to connect to a specific database instead of the default `postgres` database. If you created a custom database (e.g., `testdb`), use:

  ```bash
  postgresql://postgres:mysecretpassword@postgres-dev:5432/testdb
  ```

  Example with SSL disabled (common in Docker networks): Add `?sslmode=disable` to the connection string when connecting within a private Docker network where SSL encryption isn't required.

  ```bash
  postgresql://postgres:mysecretpassword@postgres-dev:5432/testdb?sslmode=disable
  ```

> Note
>
> The default port `5432` is used in these examples. If you're connecting to a different PostgreSQL instance or have changed the port, update the connection string accordingly. The container name (`postgres-dev`) is resolved by Docker DNS to the container's IP address on the network.

## [Connecting from the host (external access)](#connecting-from-the-host-external-access)

To connect to PostgreSQL from your host machine using tools like `psql`, `pgAdmin`, `DBeaver`, or database management scripts, you need to publish PostgreSQL's port (`5432`) to the host. This allows external tools to reach the PostgreSQL container.

### [Expose Postgres to localhost only (recommended for development)](#expose-postgres-to-localhost-only-recommended-for-development)

This binds to `127.0.0.1` so it's only reachable from your local machine, not from other devices on your network. This is the most secure option for development.

```bash
docker run -d --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 127.0.0.1:5432:5432 \
  -v postgres_data:/var/lib/postgresql \
  postgres:18
```

Now connect from your host:

* Host: `localhost` or `127.0.0.1`
* Port: `5432`

If you have `psql` installed on your host:

```bash
psql -h localhost -p 5432 -U postgres
```

You'll be prompted for the password. Alternatively, you can use the `PGPASSWORD` environment variable:

```bash
PGPASSWORD=mysecretpassword psql -h localhost -p 5432 -U postgres
```

### [Connecting with PostgreSQL GUI tools](#connecting-with-postgresql-gui-tools)

Popular PostgreSQL GUI tools can connect using these common connection details: Host: `localhost`, Port: `5432`, User: `postgres`, Database: `postgres` (or your database name).

* pgAdmin: A web-based PostgreSQL administration and development platform
* DBeaver: A universal database tool that supports PostgreSQL and many other databases. Select PostgreSQL as the connection type
* TablePlus: A modern, native database management tool for macOS and Windows with a clean interface

All tools will prompt for the password you set with `POSTGRES_PASSWORD`.

### [Expose Postgres to all network interfaces (use with caution)](#expose-postgres-to-all-network-interfaces-use-with-caution)

To allow connections from other devices on your network, use `-p 5432:5432` instead of `-p 127.0.0.1:5432:5432`. This binds PostgreSQL to all network interfaces on your host, making it accessible from any device that can reach your host, not just localhost.

```bash
docker run -d --name postgres-dev \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -v postgres_data:/var/lib/postgresql \
  postgres:18
```

> Warning
>
> Exposing PostgreSQL to all network interfaces (`0.0.0.0:5432`) makes it accessible from any device that can reach your host. Only use this in trusted network environments or behind a firewall. For production, consider using a reverse proxy or VPN instead.

### [PostgreSQL security considerations for external access](#postgresql-security-considerations-for-external-access)

When exposing PostgreSQL to external access, follow these PostgreSQL-specific security practices:

* Avoid using the `postgres` superuser: The default `postgres` user has full database privileges. Create dedicated users with only the permissions your application needs.
* Use strong passwords: PostgreSQL passwords should be complex. Consider using environment variables or secrets management instead of `hardcoding` passwords.
* Limit network exposure: Binding to `127.0.0.1` (localhost only) is safer than exposing to all interfaces (`0.0.0.0`).
* Consider SSL/TLS: For production, configure PostgreSQL to require SSL connections. The [Advanced Configuration and Initialization](/guides/postgresql/advanced-configuration-and-initialization/) guide shows how to configure PostgreSQL settings.
* Create application-specific users: Use initialization scripts to create users with limited privileges. For example, a read-only user for reporting or a user that can only access specific databases.

The [Advanced configuration and initialization](/guides/postgresql/advanced-configuration-and-initialization/) guide shows how to use initialization scripts to create users and roles automatically.

## [Using Docker Compose for networking](#using-docker-compose-for-networking)

Docker Compose automatically creates a network for your services, making networking configuration simpler. Here's an example that combines both internal and external access:

```yaml
services:
  db:
    image: postgres:18
    container_name: postgres-dev
    environment:
      POSTGRES_PASSWORD: mysecretpassword
    volumes:
      - postgres_data:/var/lib/postgresql
    ports:
      - "127.0.0.1:5432:5432"  # Expose to localhost only
    networks:
      - app-network

  app:
    build: ./my-app
    environment:
      DATABASE_URL: postgresql://postgres:mysecretpassword@db:5432/mydb
    networks:
      - app-network
    depends_on:
      - db

volumes:
  postgres_data:

networks:
  app-network:
    driver: bridge
```

In this PostgreSQL-focused setup:

* The `app` service connects to PostgreSQL using the service name (`db`) as the hostname in the connection string
* PostgreSQL is accessible from your host at `localhost:5432` for external tools
* Both services are isolated on a custom network, providing network-level security
* The `depends_on` directive ensures PostgreSQL starts before your application

PostgreSQL connection details for the app service:

* Hostname: `db` (resolved by Docker DNS)
* Port: `5432` (PostgreSQL default port)
* Database: `mydb` (as specified in the connection string)
* User: `postgres` (or a custom user you've created)

> Note
>
> Docker Compose automatically creates a network for your project. Services can reach each other by service name without explicit network configuration, but defining a custom network gives you more control. For PostgreSQL, this means your application can always connect using the service name, regardless of container restarts or IP changes.

## [Troubleshooting](#troubleshooting)

This section covers common PostgreSQL connection issues and their solutions when working with Docker networking.

### ["Could not translate host name postgres-dev"](#could-not-translate-host-name-postgres-dev)

* Both containers must be on the same Docker network (`my-app-net`).
* Verify the network exists: `docker network ls`
* Check which network a container is on: `docker inspect postgres-dev | grep NetworkMode`
* Ensure you're using a user-defined network, not the default bridge network

### ["Connection refused" or "could not connect to server"](#connection-refused-or-could-not-connect-to-server)

* PostgreSQL may still be initializing: PostgreSQL takes a few seconds to start and initialize the database cluster. Wait 5-10 seconds after container start and retry.

* Check if the PostgreSQL container is running:

  ```bash
  docker ps --filter name=postgres-dev
  ```

* Check PostgreSQL logs for initialization or connection errors:

  ```bash
  docker logs postgres-dev
  ```

  Look for messages like "database system is ready to accept connections" to confirm PostgreSQL is fully started.

* Verify the port mapping is correct:

  ```bash
  docker port postgres-dev
  ```

  This should show `5432/tcp -> 127.0.0.1:5432` (or `0.0.0.0:5432` if bound to all interfaces).

* Test PostgreSQL connectivity from inside the container:

  ```bash
  docker exec -it postgres-dev psql -U postgres -c "SELECT version();"
  ```

  If this works but external connections fail, the issue is with port publishing, not PostgreSQL itself.

### ["Password authentication failed" or "FATAL: password authentication failed for user"](#password-authentication-failed-or-fatal-password-authentication-failed-for-user)

* Confirm the password: Verify you're using the same password set in `POSTGRES_PASSWORD` when you started the container.

* Existing volume with old credentials: If you reused an existing volume, the password from the original initialization is still in effect. The `POSTGRES_PASSWORD` environment variable only sets the password during the first database initialization. To reset:

  * Remove the volume: `docker volume rm postgres_data`
  * Or connect with the old password
  * Or change the password after connecting: `ALTER USER postgres WITH PASSWORD 'newpassword';`

* Try connecting with password prompt: `psql -h localhost -U postgres -W` (the `-W` flag forces a password prompt)

* Use PGPASSWORD environment variable: `PGPASSWORD=mysecretpassword psql -h localhost -U postgres`

* Check PostgreSQL authentication configuration: If you've customized `pg_hba.conf`, verify the authentication method allows password authentication

### ["Network not found"](#network-not-found)

* Ensure the network exists before starting containers: `docker network create my-app-net`
* If using Docker Compose, the network is created automatically when you run `docker compose up`

[Companions for PostgreSQL »](https://docs.docker.com/guides/postgresql/companions-for-postgresql/)

----
url: https://docs.docker.com/dhi/core-concepts/
----

# Core concepts

***

Table of contents

***

Docker Hardened Images (DHIs) are built on a foundation of secure software supply chain practices. This section explains the core concepts behind that foundation, from signed attestations and immutable digests to standards like SLSA and VEX.

Start here if you want to understand how Docker Hardened Images support compliance, transparency, and security.

## [Security metadata and attestations](#security-metadata-and-attestations)

### [Attestations](/dhi/core-concepts/attestations/)

[Review the full set of signed attestations included with each Docker Hardened Image, such as SBOMs, VEX, build provenance, and scan results.](/dhi/core-concepts/attestations/)

### [Software Bill of Materials (SBOMs)](/dhi/core-concepts/sbom/)

[Learn what SBOMs are, why they matter, and how Docker Hardened Images include signed SBOMs to support transparency and compliance.](/dhi/core-concepts/sbom/)

### [Supply-chain Levels for Software Artifacts (SLSA)](/dhi/core-concepts/slsa/)

[Learn how Docker Hardened Images comply with SLSA Build Level 3 and how to verify provenance for secure, tamper-resistant builds.](/dhi/core-concepts/slsa/)

### [Image provenance](/dhi/core-concepts/provenance/)

[Learn how build provenance metadata helps trace the origin of Docker Hardened Images and support compliance with SLSA.](/dhi/core-concepts/provenance/)

## [Compliance standards](#compliance-standards)

### [FIPS](/dhi/core-concepts/fips/)

[Learn how Docker Hardened Images support FIPS 140 by using validated cryptographic modules and providing signed attestations for compliance audits.](/dhi/core-concepts/fips/)

### [STIG](/dhi/core-concepts/stig/)

[Learn how Docker Hardened Images provide STIG-ready container images with verifiable security scan attestations for government and enterprise compliance requirements.](/dhi/core-concepts/stig/)

### [CIS Benchmarks](/dhi/core-concepts/cis/)

[Learn how Docker Hardened Images help you meet Center for Internet Security (CIS) Docker Benchmark requirements for secure container configuration and deployment.](/dhi/core-concepts/cis/)

## [Vulnerability and risk management](#vulnerability-and-risk-management)

### [Common Vulnerabilities and Exposures (CVEs)](/dhi/core-concepts/cves/)

[Understand what CVEs are, how Docker Hardened Images reduce exposure, and how to scan images for vulnerabilities using popular tools.](/dhi/core-concepts/cves/)

### [Vulnerability Exploitability eXchange (VEX)](/dhi/core-concepts/vex/)

[Learn how VEX helps you prioritize real risks by identifying which vulnerabilities in Docker Hardened Images are actually exploitable.](/dhi/core-concepts/vex/)

### [Software Supply Chain Security](/dhi/core-concepts/sscs/)

[Learn how Docker Hardened Images help secure every stage of your software supply chain with signed metadata, provenance, and minimal attack surface.](/dhi/core-concepts/sscs/)

### [Secure Software Development Lifecycle (SSDLC)](/dhi/core-concepts/ssdlc/)

[See how Docker Hardened Images support a secure SDLC by integrating with scanning, signing, and debugging tools.](/dhi/core-concepts/ssdlc/)

## [Image structure and behavior](#image-structure-and-behavior)

### [Distroless images](/dhi/core-concepts/distroless/)

[Learn how Docker Hardened Images use distroless variants to minimize attack surface and remove unnecessary components.](/dhi/core-concepts/distroless/)

### [glibc and musl support in Docker Hardened Images](/dhi/core-concepts/glibc-musl/)

[Compare glibc and musl variants of DHIs to choose the right base image for your application’s compatibility, size, and performance needs.](/dhi/core-concepts/glibc-musl/)

### [Image immutability](/dhi/core-concepts/immutability/)

[Understand how image digests, read-only containers, and signed metadata ensure Docker Hardened Images are tamper-resistant and immutable.](/dhi/core-concepts/immutability/)

### [Image hardening](/dhi/core-concepts/hardening/)

[Learn how Docker Hardened Images are designed for security, with minimal components, nonroot execution, and secure-by-default configurations.](/dhi/core-concepts/hardening/)

## [Verification and traceability](#verification-and-traceability)

### [Digests](/dhi/core-concepts/digests/)

[Learn how to use immutable image digests to guarantee consistency and verify the exact Docker Hardened Image you're running.](/dhi/core-concepts/digests/)

### [Code signing](/dhi/core-concepts/signatures/)

[Understand how Docker Hardened Images are cryptographically signed using Cosign to verify authenticity, integrity, and secure provenance.](/dhi/core-concepts/signatures/)

----
url: https://docs.docker.com/reference/api/engine/version/v1.49/
----

# Docker Engine API v1.49 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.49.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.49.yaml)

# Docker Engine API (1.49)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.49.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.49) is used. For example, calling `/info` is the same as calling `/v1.49/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means the server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.49/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.49/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.49/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf",
"Created": "2025-02-17T17:43:39.64001363Z",
"Path": "/bin/sh",
"Args": [
"-c",
"exit 9"
],
"State": {
"Status": "running",
"Running": true,
"Paused": false,
"Restarting": false,
"OOMKilled": false,
"Dead": false,
"Pid": 1234,
"ExitCode": 0,
"Error": "string",
"StartedAt": "2020-01-06T09:06:59.461876391Z",
"FinishedAt": "2020-01-06T09:07:59.461876391Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2020-01-04T10:44:24.496525531Z",
"End": "2020-01-04T10:45:21.364524523Z",
"ExitCode": 0,
"Output": "string"
}
]
}
},
"Image": "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782",
"ResolvConfPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/resolv.conf",
"HostnamePath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hostname",
"HostsPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hosts",
"LogPath": "/var/lib/docker/containers/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59-json.log",
"Name": "/funny_chatelet",
"RestartCount": 0,
"Driver": "overlayfs",
"Platform": "linux",
"ImageManifestDescriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"MountLabel": "",
"ProcessLabel": "",
"AppArmorProfile": "",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"CpuShares": 0,
"Memory": 0,
"CgroupParent": "string",
"BlkioWeight": 1000,
"BlkioWeightDevice": [
{
"Path": "string",
"Weight": 0
}
],
"BlkioDeviceReadBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceReadIOps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteIOps": [
{
"Path": "string",
"Rate": 0
}
],
"CpuPeriod": 0,
"CpuQuota": 0,
"CpuRealtimePeriod": 0,
"CpuRealtimeRuntime": 0,
"CpusetCpus": "0-3",
"CpusetMems": "string",
"Devices": [
{
"PathOnHost": "/dev/deviceName",
"PathInContainer": "/dev/deviceName",
"CgroupPermissions": "mrw"
}
],
"DeviceCgroupRules": [
"c 13:* rwm"
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"KernelMemoryTCP": 0,
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 100,
"NanoCpus": 0,
"OomKillDisable": true,
"Init": true,
"PidsLimit": 0,
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
],
"CpuCount": 0,
"CpuPercent": 0,
"IOMaximumIOps": 0,
"IOMaximumBandwidth": 0,
"Binds": [
"string"
],
"ContainerIDFile": "",
"LogConfig": {
"Type": "local",
"Config": {
"max-file": "5",
"max-size": "10m"
}
},
"NetworkMode": "string",
"PortBindings": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"VolumeDriver": "string",
"VolumesFrom": [
"string"
],
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"ConsoleSize": [
80,
64
],
"Annotations": {
"property1": "string",
"property2": "string"
},
"CapAdd": [
"string"
],
"CapDrop": [
"string"
],
"CgroupnsMode": "private",
"Dns": [
"string"
],
"DnsOptions": [
"string"
],
"DnsSearch": [
"string"
],
"ExtraHosts": [
"string"
],
"GroupAdd": [
"string"
],
"IpcMode": "string",
"Cgroup": "string",
"Links": [
"string"
],
"OomScoreAdj": 500,
"PidMode": "string",
"Privileged": true,
"PublishAllPorts": true,
"ReadonlyRootfs": true,
"SecurityOpt": [
"string"
],
"StorageOpt": {
"property1": "string",
"property2": "string"
},
"Tmpfs": {
"property1": "string",
"property2": "string"
},
"UTSMode": "string",
"UsernsMode": "string",
"ShmSize": 0,
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Runtime": "string",
"Isolation": "default",
"MaskedPaths": [
"/proc/asound",
"/proc/acpi",
"/proc/kcore",
"/proc/keys",
"/proc/latency_stats",
"/proc/timer_list",
"/proc/timer_stats",
"/proc/sched_debug",
"/proc/scsi",
"/sys/firmware",
"/sys/devices/virtual/powercap"
],
"ReadonlyPaths": [
"/proc/bus",
"/proc/fs",
"/proc/irq",
"/proc/sys",
"/proc/sysrq-trigger"
]
},
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"SizeRw": "122880",
"SizeRootFs": "1653948416",
"Mounts": [
{
"Type": "volume",
"Name": "myvolume",
"Source": "/var/lib/docker/volumes/myvolume/_data",
"Destination": "/usr/share/nginx/html/",
"Driver": "local",
"Mode": "z",
"RW": true,
"Propagation": ""
}
],
"Config": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"NetworkSettings": {
"Bridge": "docker0",
"SandboxID": "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": "",
"Ports": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"SandboxKey": "/var/run/docker/netns/8ab54b426c38",
"SecondaryIPAddresses": [
{
"Addr": "string",
"PrefixLen": 0
}
],
"SecondaryIPv6Addresses": [
{
"Addr": "string",
"PrefixLen": 0
}
],
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"MacAddress": "02:42:ac:11:00:04",
"Networks": {
"property1": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
},
"property2": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
}
}
}
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.49/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": {
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
]
},
"Processes": {
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.49/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.49/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.49/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.49/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"name": "boring_wozniak",
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"read": "2025-01-16T13:55:22.165243637Z",
"preread": "2025-01-16T13:55:21.160452595Z",
"pids_stats": {
"current": 5,
"limit": "18446744073709551615"
},
"blkio_stats": {
"io_service_bytes_recursive": [
{
"major": 254,
"minor": 0,
"op": "read",
"value": 7593984
},
{
"major": 254,
"minor": 0,
"op": "write",
"value": 100
}
],
"io_serviced_recursive": null,
"io_queue_recursive": null,
"io_service_time_recursive": null,
"io_wait_time_recursive": null,
"io_merged_recursive": null,
"io_time_recursive": null,
"sectors_recursive": null
},
"num_procs": 16,
"storage_stats": {
"read_count_normalized": 7593984,
"read_size_bytes": 7593984,
"write_count_normalized": 7593984,
"write_size_bytes": 7593984
},
"cpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"memory_stats": {
"usage": 0,
"max_usage": 0,
"stats": {
"active_anon": 1572864,
"active_file": 5115904,
"anon": 1572864,
"anon_thp": 0,
"file": 7626752,
"file_dirty": 0,
"file_mapped": 2723840,
"file_writeback": 0,
"inactive_anon": 0,
"inactive_file": 2510848,
"kernel_stack": 16384,
"pgactivate": 0,
"pgdeactivate": 0,
"pgfault": 2042,
"pglazyfree": 0,
"pglazyfreed": 0,
"pgmajfault": 45,
"pgrefill": 0,
"pgscan": 0,
"pgsteal": 0,
"shmem": 0,
"slab": 1180928,
"slab_reclaimable": 725576,
"slab_unreclaimable": 455352,
"sock": 0,
"thp_collapse_alloc": 0,
"thp_fault_alloc": 1,
"unevictable": 0,
"workingset_activate": 0,
"workingset_nodereclaim": 0,
"workingset_refault": 0
},
"failcnt": 0,
"limit": 8217579520,
"commitbytes": 0,
"commitpeakbytes": 0,
"privateworkingset": 0
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.49/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.49/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.49/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.49/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.49/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime.This field is omitted when empty.                         |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.49/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"Published ports are discarded when using host network mode"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.49/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.49/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.49/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.49/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.49/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.49/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.49/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.49/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.49/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.49/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.49/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |
| manifests   | booleanDefault: falseInclude `Manifests` in the image summary.                                                                                                                                                                                                                                                                                                                                       |

### Responses

/v1.49/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2,
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
}
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.49/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| keep-storage   | integer \<int64>Amount of disk space in bytes to keep for cache> **Deprecated**: This parameter is deprecated and has been renamed to "reserved-space". It is kept for backward compatibility and will be removed in API v1.52.                                                                                                                                                                                                                                          |
| reserved-space | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| max-used-space | integer \<int64>Maximum amount of disk space allowed to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                   |
| min-free-space | integer \<int64>Target amount of free disk space after pruning                                                                                                                                                                                                                                                                                                                                                                                                           |
| all            | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters        | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.49/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. If the name includes a tag or digest, specific behavior applies:- If only `fromImage` includes a tag, that tag is used.
- If both `fromImage` and `tag` are provided, `tag` takes precedence.
- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.
- If neither a tag nor digest is specified, all tags are pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.49/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| manifests | booleanDefault: falseInclude Manifests in the image summary.The `manifests` and `platform` options are mutually exclusive, and an error is produced if both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show inspect. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.The `platform` and `manifests` options are mutually exclusive, and an error is produced if both are set.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.49/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"DockerVersion": "27.0.1",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "web:web",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": true,
"Image": "",
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show the history for. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.49/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag      | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed.                                                                                                                                                                                                                                                                                                                   |
| platform | stringJSON-encoded OCI platform to select the platform-variant to push. If not provided, all available variants will attempt to be pushed.If the daemon provides a multi-platform image store, this selects the platform-variant to push to the registry. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.49/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.49/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|         |                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------ |
| force   | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags |
| noprune | booleanDefault: falseDo not delete untagged parent images                                              |

### Responses

/v1.49/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                   |
| limit        | integerMaximum number of results to return                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.49/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.49/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.49/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.49/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| names    | Array of stringsImage names to filter by                                                                                                                                                                                                                                                 |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.49/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| quiet    | booleanDefault: falseSuppress progress details during load.                                                                                                                                                                                                                              |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be load if the image is multi-platform. If not provided, the full multi-platform image will be loaded.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.49/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.49/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv4": true,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.49/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv4": true,
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.49/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|              |                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired | stringThe network's name.                                                                                                                                                                                                              |
| Driver       | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope        | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal     | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable   | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress      | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly   | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|              | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|              | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv4   | booleanEnable IPv4 on the network.                                                                                                                                                                                                     |
| EnableIPv6   | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|              | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|              | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.49/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv4": true,
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.49/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
},
"MacAddress": "02:42:ac:12:05:02",
"Priority": 100
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.49/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.49/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.49/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.49/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.49/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.49/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.49/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.49/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.49/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.49/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.49/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.49/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.49/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.49/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.49/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.49/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.49/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.49/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.49/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.49/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.49/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.49/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.49/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.49/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.49/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.49/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.49/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.49/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.49/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.49/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.49/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.49/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.49/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.49/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.49/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.49/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.49/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.49/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.49/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.49/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.49/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.49/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.49/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.49/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.49/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.49/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.49/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.49/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.49/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.49/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.49/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.49/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.49/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.49/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.49/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"BridgeNfIptables": false,
"BridgeNfIp6tables": false,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "6.8.0-31-generic",
"OperatingSystem": "Ubuntu 24.04 LTS",
"OSVersion": "24.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "27.0.1",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"FirewallBackend": {
"Driver": "nftables",
"Info": [ [
"ReloadedAt",
"2025-01-01T00:00:00Z"
]
]
},
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
],
"Containerd": {
"Address": "/run/containerd/containerd.sock",
"Namespaces": {
"Containers": "moby",
"Plugins": "plugins.moby"
}
}
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.49/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "27.0.1",
"Details": { }
}
],
"Version": "27.0.1",
"ApiVersion": "1.47",
"MinAPIVersion": "1.24",
"GitCommit": "48a66213fe",
"GoVersion": "go1.22.7",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "6.8.0-31-generic",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.49/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.49/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.49/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|      |                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |

### Responses

/v1.49/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parents": [ ],
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parents": [
"ndlpt0hhvkqcdfkputsk4cq9c"
],
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.49/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.49/session

----
url: https://docs.docker.com/desktop/features/wsl/
----

# Docker Desktop WSL 2 backend on Windows

***

Table of contents

***

Windows Subsystem for Linux (WSL) 2 is a full Linux kernel built by Microsoft that lets Linux distributions run without managing virtual machines. With Docker Desktop running on WSL 2, users can leverage Linux workspaces and avoid maintaining both Linux and Windows build scripts. In addition, WSL 2 provides improvements to file system sharing, faster cold-start times, and dynamic resource allocation.

Because WSL 2 uses dynamic memory allocation, Docker Desktop requests only the CPU and memory it actually needs — freeing resources for the rest of your system, while still letting memory-intensive tasks such as multi-stage image builds run at full speed.

## [Prerequisites](#prerequisites)

Before you turn on the Docker Desktop WSL 2 feature, ensure you have:

* At a minimum WSL version 2.1.5, but ideally the latest version of WSL to [avoid Docker Desktop not working as expected](https://docs.docker.com/desktop/features/wsl/best-practices/).
* Met the Docker Desktop for Windows' [system requirements](https://docs.docker.com/desktop/setup/install/windows-install/#system-requirements).
* Installed the WSL 2 feature on Windows. For detailed instructions, refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10).

> Tip
>
> Consider enabling the WSL [autoMemoryReclaim](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#experimental-settings) setting, available since WSL 1.3.10 (experimental). This setting allows Windows to reclaim unused memory from the WSL virtual machine, preventing the Linux kernel's page cache from holding onto large amounts of RAM after container image builds complete. The result is better memory availability for other applications on the host.

## [Turn on Docker Desktop WSL 2](#turn-on-docker-desktop-wsl-2)

Before installing Docker Desktop, uninstall any version of Docker Engine or the Docker CLI that was installed directly inside a WSL Linux distribution. Running both can cause conflicts.

1. Download and install the latest version of [Docker Desktop for Windows](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-windows).

2. Follow the usual installation instructions to install Docker Desktop. Depending on which version of Windows you are using, Docker Desktop may prompt you to turn on WSL 2 during installation. Read the information displayed on the screen and turn on the WSL 2 feature to continue.

3. Start Docker Desktop from the **Windows Start** menu.

4. Navigate to **Settings**.

5. From the **General** tab, select **Use WSL 2 based engine**.

   If you have installed Docker Desktop on a system that supports WSL 2, this option is turned on by default and the setting is not visible.

6. Select **Apply**.

`docker` commands are now available from any Windows terminal using the WSL 2 engine.

> Tip
>
> By default, Docker Desktop stores the data for the WSL 2 engine at `C:\Users\[USERNAME]\AppData\Local\Docker\wsl`. If you want to change the location, go to `Settings -> Resources -> Advanced` page from the Docker Dashboard. Read more about this and other Windows settings at [Changing settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/)

## [Enable Docker in a WSL 2 distribution](#enable-docker-in-a-wsl-2-distribution)

WSL 2 lets multiple Linux distributions run side-by-side on a single shared kernel. Docker Desktop doesn't require a particular distribution to be installed, and `docker` commands work from Windows without one. However, enabling WSL integration for a distribution gives you direct access to `docker` commands from that distribution's terminal — which is useful for Linux-native development workflows.

1. Ensure the distribution runs in WSL 2 mode. WSL can run distributions in both v1 or v2 mode.

   To check the WSL mode, run:

   ```console
   $ wsl.exe -l -v
   ```

   To upgrade the Linux distribution to v2, run:

   ```console
   $ wsl.exe --set-version (distribution name) 2
   ```

   To set v2 as the default version for future installations, run:

   ```console
   $ wsl.exe --set-default-version 2
   ```

2. When Docker Desktop starts, go to **Settings** > **Resources** > **WSL Integration**.

   The Docker-WSL integration is enabled on the default WSL distribution, which is [Ubuntu](https://learn.microsoft.com/en-us/windows/wsl/install). To change your default WSL distribution, run:

   ```console
   $ wsl.exe --set-default <distribution name>
   ```

   If **WSL integrations** isn't available under **Resources**, Docker may be in Windows container mode. In your taskbar, select the Docker menu and then **Switch to Linux containers**.

3. Select **Apply**.

## [WSL 2 security in Docker Desktop](#wsl-2-security-in-docker-desktop)

Docker Desktop's WSL 2 integration works within WSL's existing security model and does not introduce security risks beyond standard WSL behavior.

Docker Desktop runs inside its own `docker-desktop` WSL distribution, isolated from other distributions in the same way any two WSL distributions are isolated from each other. Interaction between Docker Desktop and other distributions only occurs when you explicitly enable WSL integration for those distributions. This feature allows easy access to the Docker CLI from integrated distributions.

WSL is designed to aid interoperability between Windows and Linux environments. Its file system is accessible from the Windows host `\\wsl$`, meaning Windows processes can read and modify files within WSL. This behavior is not specific to Docker Desktop, but rather a core aspect of WSL itself.

For environments that require stricter isolation:

* Run Docker Desktop in Hyper-V mode instead of WSL 2 to avoid the shared-kernel model entirely.
* Enable [Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) to add an additional layer of protection around container workloads regardless of backend.

## [Additional resources](#additional-resources)

* [Explore best practices](https://docs.docker.com/desktop/features/wsl/best-practices/)
* [Understand how to develop with Docker and WSL 2](https://docs.docker.com/desktop/features/wsl/use-wsl/)
* [Learn about GPU support with WSL 2](https://docs.docker.com/desktop/features/gpu/)
* [Custom kernels on WSL](https://docs.docker.com/desktop/features/wsl/custom-kernels/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/imagetools/inspect/
----

# docker buildx imagetools inspect

***

| Description | Show details of an image in the registry          |
| ----------- | ------------------------------------------------- |
| Usage       | `docker buildx imagetools inspect [OPTIONS] NAME` |

## [Description](#description)

Show details of an image in the registry.

```console
$ docker buildx imagetools inspect alpine
Name:      docker.io/library/alpine:latest
MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest:    sha256:21a3deaa0d32a8057914f36584b5288d2e5ecc984380bc0118285c70fa8c9300

Manifests:
  Name:      docker.io/library/alpine:latest@sha256:e7d88de73db3d3fd9b2d63aa7f447a10fd0220b7cbf39803c803f2af9ba256b3
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/amd64

  Name:      docker.io/library/alpine:latest@sha256:e047bc2af17934d38c5a7fa9f46d443f1de3a7675546402592ef805cfa929f9d
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/arm/v6

  Name:      docker.io/library/alpine:latest@sha256:8483ecd016885d8dba70426fda133c30466f661bb041490d525658f1aac73822
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/arm/v7

  Name:      docker.io/library/alpine:latest@sha256:c74f1b1166784193ea6c8f9440263b9be6cae07dfe35e32a5df7a31358ac2060
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/arm64/v8

  Name:      docker.io/library/alpine:latest@sha256:2689e157117d2da668ad4699549e55eba1ceb79cb7862368b30919f0488213f4
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/386

  Name:      docker.io/library/alpine:latest@sha256:2042a492bcdd847a01cd7f119cd48caa180da696ed2aedd085001a78664407d6
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/ppc64le

  Name:      docker.io/library/alpine:latest@sha256:49e322ab6690e73a4909f787bcbdb873631264ff4a108cddfd9f9c249ba1d58e
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/s390x
```

## [Options](#options)

| Option                | Default               | Description                                   |
| --------------------- | --------------------- | --------------------------------------------- |
| [`--format`](#format) | `` `{{.Manifest}}` `` | Format the output using the given Go template |
| [`--raw`](#raw)       |                       | Show original, unformatted JSON manifest      |

## [Examples](#examples)

### [Override the configured builder instance (--builder)](#builder)

Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

### [Format the output (--format)](#format)

Format the output using the given Go template. Defaults to `{{.Manifest}}` if unset. Following fields are available:

* `.Name`: provides the reference of the image
* `.Manifest`: provides the manifest or manifest list
* `.Image`: provides the image config

#### [`.Name`](#name)

```console
$ docker buildx imagetools inspect alpine --format "{{.Name}}"
Name: docker.io/library/alpine:latest
```

#### [`.Manifest`](#manifest)

```console
$ docker buildx imagetools inspect crazymax/loop --format "{{.Manifest}}"
Name:      docker.io/crazymax/loop:latest
MediaType: application/vnd.docker.distribution.manifest.v2+json
Digest:    sha256:08602e7340970e92bde5e0a2e887c1fde4d9ae753d1e05efb4c8ef3b609f97f1
```

```console
$ docker buildx imagetools inspect moby/buildkit:master --format "{{.Manifest}}"
Name:      docker.io/moby/buildkit:master
MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest:    sha256:3183f7ce54d1efb44c34b84f428ae10aaf141e553c6b52a7ff44cc7083a05a66

Manifests:
  Name:      docker.io/moby/buildkit:master@sha256:667d28c9fb33820ce686887a717a148e89fa77f9097f9352996bbcce99d352b1
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/amd64

  Name:      docker.io/moby/buildkit:master@sha256:71789527b64ab3d7b3de01d364b449cd7f7a3da758218fbf73b9c9aae05a6775
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/arm/v7

  Name:      docker.io/moby/buildkit:master@sha256:fb64667e1ce6ab0d05478f3a8402af07b27737598dcf9a510fb1d792b13a66be
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/arm64

  Name:      docker.io/moby/buildkit:master@sha256:1c3ddf95a0788e23f72f25800c05abc4458946685e2b66788c3d978cde6da92b
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/s390x

  Name:      docker.io/moby/buildkit:master@sha256:05bcde6d460a284e5bc88026cd070277e8380355de3126cbc8fe8a452708c6b1
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/ppc64le

  Name:      docker.io/moby/buildkit:master@sha256:c04c57765304ab84f4f9807fff3e11605c3a60e16435c734b02c723680f6bd6e
  MediaType: application/vnd.docker.distribution.manifest.v2+json
  Platform:  linux/riscv64
```

#### [JSON output](#json-output)

A `json` template function is also available if you want to render fields in JSON format:

```console
$ docker buildx imagetools inspect crazymax/buildkit:attest --format "{{json .Manifest}}"
```

```json
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "digest": "sha256:7007b387ccd52bd42a050f2e8020e56e64622c9269bf7bbe257b326fe99daf19",
  "size": 855,
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:fbd10fe50b4b174bb9ea273e2eb9827fa8bf5c88edd8635a93dc83e0d1aecb55",
      "size": 673,
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:a9de632c16998489fd63fbca42a03431df00639cfb2ecb8982bf9984b83c5b2b",
      "size": 839,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:fbd10fe50b4b174bb9ea273e2eb9827fa8bf5c88edd8635a93dc83e0d1aecb55",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      }
    }
  ]
}
```

```console
$ docker buildx imagetools inspect crazymax/buildkit:attest --format "{{json .Image}}"
```

```json
{
  "created": "2022-12-01T11:46:47.713777178Z",
  "architecture": "amd64",
  "os": "linux",
  "config": {
    "Env": [
      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
    ],
    "Cmd": [
      "/bin/sh"
    ]
  },
  "rootfs": {
    "type": "layers",
    "diff_ids": [
      "sha256:ded7a220bb058e28ee3254fbba04ca90b679070424424761a53a043b93b612bf",
      "sha256:d85d09ab4b4e921666ccc2db8532e857bf3476b7588e52c9c17741d7af14204f"
    ]
  },
  "history": [
    {
      "created": "2022-11-22T22:19:28.870801855Z",
      "created_by": "/bin/sh -c #(nop) ADD file:587cae71969871d3c6456d844a8795df9b64b12c710c275295a1182b46f630e7 in / "
    },
    {
      "created": "2022-11-22T22:19:29.008562326Z",
      "created_by": "/bin/sh -c #(nop)  CMD [\"/bin/sh\"]",
      "empty_layer": true
    },
    {
      "created": "2022-12-01T11:46:47.713777178Z",
      "created_by": "RUN /bin/sh -c apk add curl # buildkit",
      "comment": "buildkit.dockerfile.v0"
    }
  ]
}
```

```console
$ docker buildx imagetools inspect moby/buildkit:master --format "{{json .Manifest}}"
```

```json
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "digest": "sha256:d895e8fdcf5e2bb39acb5966f97fc4cd87a2d13d27c939c320025eb4aca5440c",
  "size": 4654,
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:ac9dd4fbec9e36b562f910618975a2936533f8e411a3fea2858aacc0ac972e1c",
      "size": 1054,
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:0f4dc6797db467372cbf52c7236816203654a839f64a6542c9135d1973c9d744",
      "size": 1054,
      "platform": {
        "architecture": "arm",
        "os": "linux",
        "variant": "v7"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:d62bb533d95afe17c4a9caf1e7c57a3b0a7a67409ccfa7af947aeb0f670ffb87",
      "size": 1054,
      "platform": {
        "architecture": "arm64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:b4944057e0c68203cdcc3dceff3b2df3c7d9e3dd801724fa977b01081da7771e",
      "size": 1054,
      "platform": {
        "architecture": "s390x",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:825702a51eb4234904fc9253d8b0bf0a584787ffd8fc3fd6fa374188233ce399",
      "size": 1054,
      "platform": {
        "architecture": "ppc64le",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:dfb27c6acc9b9f3a7c9d47366d137089565062f43c8063c9f5e408d34c87ee4a",
      "size": 1054,
      "platform": {
        "architecture": "riscv64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:f2fe69bccc878e658caf21dfc99eaf726fb20d28f17398c1d66a90e62cc019f9",
      "size": 1113,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:ac9dd4fbec9e36b562f910618975a2936533f8e411a3fea2858aacc0ac972e1c",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:9e112f8d4e383186f36369fba7b454e246d2e9ca5def797f1b84ede265e9f3ca",
      "size": 1113,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:0f4dc6797db467372cbf52c7236816203654a839f64a6542c9135d1973c9d744",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:09d593587f8665269ec6753eaed7fbdb09968f71587dd53e06519502cbc16775",
      "size": 1113,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:d62bb533d95afe17c4a9caf1e7c57a3b0a7a67409ccfa7af947aeb0f670ffb87",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:985a3f4544dfb042db6a8703f5f76438667dd7958aba14cb04bebe3b4cbd9307",
      "size": 1113,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:b4944057e0c68203cdcc3dceff3b2df3c7d9e3dd801724fa977b01081da7771e",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:cfccb6afeede7dc29bf8abef4815d56f2723fa482ea63c9cd519cd991c379294",
      "size": 1113,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:825702a51eb4234904fc9253d8b0bf0a584787ffd8fc3fd6fa374188233ce399",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:2e93733432c6a14cb57db33928b3a17d7ca298b3babe24d9f56dca2754dbde3b",
      "size": 1113,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:dfb27c6acc9b9f3a7c9d47366d137089565062f43c8063c9f5e408d34c87ee4a",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
        "architecture": "unknown",
        "os": "unknown"
      }
    }
  ]
}
```

The following command provides [SLSA](https://github.com/moby/buildkit/blob/master/docs/attestations/slsa-provenance.md) JSON output:

```console
$ docker buildx imagetools inspect crazymax/buildkit:attest --format "{{json .Provenance}}"
```

```json
{
  "SLSA": {
    "builder": {
      "id": ""
    },
    "buildType": "https://mobyproject.org/buildkit@v1",
    "materials": [
      {
        "uri": "pkg:docker/docker/buildkit-syft-scanner@stable-1",
        "digest": {
          "sha256": "b45f1d207e16c3a3a5a10b254ad8ad358d01f7ea090d382b95c6b2ee2b3ef765"
        }
      },
      {
        "uri": "pkg:docker/alpine@latest?platform=linux%2Famd64",
        "digest": {
          "sha256": "8914eb54f968791faf6a8638949e480fef81e697984fba772b3976835194c6d4"
        }
      }
    ],
    "invocation": {
      "configSource": {},
      "parameters": {
        "frontend": "dockerfile.v0",
        "locals": [
          {
            "name": "context"
          },
          {
            "name": "dockerfile"
          }
        ]
      },
      "environment": {
        "platform": "linux/amd64"
      }
    },
    "metadata": {
      "buildInvocationID": "02tdha2xkbxvin87mz9drhag4",
      "buildStartedOn": "2022-12-01T11:50:07.264704131Z",
      "buildFinishedOn": "2022-12-01T11:50:08.243788739Z",
      "reproducible": false,
      "completeness": {
        "parameters": true,
        "environment": true,
        "materials": false
      },
      "https://mobyproject.org/buildkit@v1#metadata": {}
    }
  }
}
```

The following command provides [SBOM](https://github.com/moby/buildkit/blob/master/docs/attestations/sbom.md) JSON output:

```console
$ docker buildx imagetools inspect crazymax/buildkit:attest --format "{{json .SBOM}}"
```

```json
{
  "SPDX": {
    "SPDXID": "SPDXRef-DOCUMENT",
    "creationInfo": {
      "created": "2022-12-01T11:46:48.063400162Z",
      "creators": [
        "Tool: syft-v0.60.3",
        "Tool: buildkit-1ace2bb",
        "Organization: Anchore, Inc"
      ],
      "licenseListVersion": "3.18"
    },
    "dataLicense": "CC0-1.0",
    "documentNamespace": "https://anchore.com/syft/dir/run/src/core-0a4ccc6d-1a72-4c3a-a40e-3df1a2ffca94",
    "files": [...],
    "spdxVersion": "SPDX-2.2"
  }
}
```

```console
$ docker buildx imagetools inspect crazymax/buildkit:attest --format "{{json .}}"
```

```json
{
  "name": "crazymax/buildkit:attest",
  "manifest": {
    "schemaVersion": 2,
    "mediaType": "application/vnd.oci.image.index.v1+json",
    "digest": "sha256:7007b387ccd52bd42a050f2e8020e56e64622c9269bf7bbe257b326fe99daf19",
    "size": 855,
    "manifests": [
      {
        "mediaType": "application/vnd.oci.image.manifest.v1+json",
        "digest": "sha256:fbd10fe50b4b174bb9ea273e2eb9827fa8bf5c88edd8635a93dc83e0d1aecb55",
        "size": 673,
        "platform": {
          "architecture": "amd64",
          "os": "linux"
        }
      },
      {
        "mediaType": "application/vnd.oci.image.manifest.v1+json",
        "digest": "sha256:a9de632c16998489fd63fbca42a03431df00639cfb2ecb8982bf9984b83c5b2b",
        "size": 839,
        "annotations": {
          "vnd.docker.reference.digest": "sha256:fbd10fe50b4b174bb9ea273e2eb9827fa8bf5c88edd8635a93dc83e0d1aecb55",
          "vnd.docker.reference.type": "attestation-manifest"
        },
        "platform": {
          "architecture": "unknown",
          "os": "unknown"
        }
      }
    ]
  },
  "image": {
    "created": "2022-12-01T11:46:47.713777178Z",
    "architecture": "amd64",
    "os": "linux",
    "config": {
      "Env": [
        "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
      ],
      "Cmd": [
        "/bin/sh"
      ]
    },
    "rootfs": {
      "type": "layers",
      "diff_ids": [
        "sha256:ded7a220bb058e28ee3254fbba04ca90b679070424424761a53a043b93b612bf",
        "sha256:d85d09ab4b4e921666ccc2db8532e857bf3476b7588e52c9c17741d7af14204f"
      ]
    },
    "history": [
      {
        "created": "2022-11-22T22:19:28.870801855Z",
        "created_by": "/bin/sh -c #(nop) ADD file:587cae71969871d3c6456d844a8795df9b64b12c710c275295a1182b46f630e7 in / "
      },
      {
        "created": "2022-11-22T22:19:29.008562326Z",
        "created_by": "/bin/sh -c #(nop)  CMD [\"/bin/sh\"]",
        "empty_layer": true
      },
      {
        "created": "2022-12-01T11:46:47.713777178Z",
        "created_by": "RUN /bin/sh -c apk add curl # buildkit",
        "comment": "buildkit.dockerfile.v0"
      }
    ]
  }
}
```

#### [Multi-platform](#multi-platform)

Multi-platform images are supported for `.Image`, `.SLSA` and `.SBOM` fields. If you want to pick up a specific platform, you can specify it using the `index` go template function:

```console
$ docker buildx imagetools inspect --format '{{json (index .Image "linux/s390x")}}' moby/buildkit:master
```

```json
{
  "created": "2022-11-30T17:42:26.414957336Z",
  "architecture": "s390x",
  "os": "linux",
  "config": {
    "Env": [
      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
    ],
    "Entrypoint": [
      "buildkitd"
    ],
    "Volumes": {
      "/var/lib/buildkit": {}
    }
  },
  "rootfs": {
    "type": "layers",
    "diff_ids": [
      "sha256:41048e32d0684349141cf05f629c5fc3c5915d1f3426b66dbb8953a540e01e1e",
      "sha256:2651209b9208fff6c053bc3c17353cb07874e50f1a9bc96d6afd03aef63de76a",
      "sha256:88577322e65f094ce8ac27435880f1a8a9baadb569258026bb141770451bafcb",
      "sha256:de8f9a790e4ed10ff1f1f8ea923c9da4f97246a7e200add2dc6650eba3f10a20"
    ]
  },
  "history": [
    {
      "created": "2021-11-24T20:41:23.709681315Z",
      "created_by": "/bin/sh -c #(nop) ADD file:cd24c711a2ef431b3ff94f9a02bfc42f159bc60de1d0eceecafea4e8af02441d in / "
    },
    {
      "created": "2021-11-24T20:41:23.94211262Z",
      "created_by": "/bin/sh -c #(nop)  CMD [\"/bin/sh\"]",
      "empty_layer": true
    },
    {
      "created": "2022-01-26T18:15:21.449825391Z",
      "created_by": "RUN /bin/sh -c apk add --no-cache fuse3 git openssh pigz xz   \u0026\u0026 ln -s fusermount3 /usr/bin/fusermount # buildkit",
      "comment": "buildkit.dockerfile.v0"
    },
    {
      "created": "2022-08-25T00:39:25.652811078Z",
      "created_by": "COPY examples/buildctl-daemonless/buildctl-daemonless.sh /usr/bin/ # buildkit",
      "comment": "buildkit.dockerfile.v0"
    },
    {
      "created": "2022-11-30T17:42:26.414957336Z",
      "created_by": "VOLUME [/var/lib/buildkit]",
      "comment": "buildkit.dockerfile.v0",
      "empty_layer": true
    },
    {
      "created": "2022-11-30T17:42:26.414957336Z",
      "created_by": "COPY / /usr/bin/ # buildkit",
      "comment": "buildkit.dockerfile.v0"
    },
    {
      "created": "2022-11-30T17:42:26.414957336Z",
      "created_by": "ENTRYPOINT [\"buildkitd\"]",
      "comment": "buildkit.dockerfile.v0",
      "empty_layer": true
    }
  ]
}
```

### [Show original JSON manifest (--raw)](#raw)

Use the `--raw` option to print the raw JSON manifest.

```console
$ docker buildx imagetools inspect --raw crazymax/loop
```

```json
{
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "digest": "sha256:a98999183d2c7a8845f6d56496e51099ce6e4359ee7255504174b05430c4b78b",
    "size": 2762
  },
  "layers": [
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "digest": "sha256:8663204ce13b2961da55026a2034abb9e5afaaccf6a9cfb44ad71406dcd07c7b",
      "size": 2818370
    },
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "digest": "sha256:f0868a92f8e1e5018ed4e60eb845ed4ff0e2229897f4105e5a4735c1d6fd874f",
      "size": 1821402
    },
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "digest": "sha256:d010066dbdfcf7c12fca30cd4b567aa7218eb6762ab53169d043655b7a8d7f2e",
      "size": 404457
    }
  ]
}
```

```console
$ docker buildx imagetools inspect --raw moby/buildkit:master | jq
```

```json
{
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "schemaVersion": 2,
  "manifests": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "digest": "sha256:f9f41c85124686c2afe330a985066748a91d7a5d505777fe274df804ab5e077e",
      "size": 1158,
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "digest": "sha256:82097c2be19c617aafb3c3e43c88548738d4b2bf3db5c36666283a918b390266",
      "size": 1158,
      "platform": {
        "architecture": "arm",
        "os": "linux",
        "variant": "v7"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "digest": "sha256:b6b91e6c823d7220ded7d3b688e571ba800b13d91bbc904c1d8053593e3ee42c",
      "size": 1158,
      "platform": {
        "architecture": "arm64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "digest": "sha256:797061bcc16778de048b96f769c018ec24da221088050bbe926ea3b8d51d77e8",
      "size": 1158,
      "platform": {
        "architecture": "s390x",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "digest": "sha256:b93d3a84d18c4d0b8c279e77343d854d9b5177df7ea55cf468d461aa2523364e",
      "size": 1159,
      "platform": {
        "architecture": "ppc64le",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "digest": "sha256:d5c950dd1b270d437c838187112a0cb44c9258248d7a3a8bcb42fae8f717dc01",
      "size": 1158,
      "platform": {
        "architecture": "riscv64",
        "os": "linux"
      }
    }
  ]
}
```

----
url: https://docs.docker.com/reference/cli/docker/mcp/client/disconnect/
----

# docker mcp client disconnect

***

| Description | Disconnect the Docker MCP Toolkit from a client. Supported clients: claude-code claude-desktop cline codex continue crush cursor gemini goose gordon kiro lmstudio opencode sema4 vscode zed      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Usage       | `docker mcp client disconnect [OPTIONS] <mcp-client> Supported clients: claude-code claude-desktop cline codex continue crush cursor gemini goose gordon kiro lmstudio opencode sema4 vscode zed` |

## [Description](#description)

Disconnect the Docker MCP Toolkit from a client. Supported clients: claude-code claude-desktop cline codex continue crush cursor gemini goose gordon kiro lmstudio opencode sema4 vscode zed

## [Options](#options)

| Option         | Default | Description                                                                          |
| -------------- | ------- | ------------------------------------------------------------------------------------ |
| `-g, --global` |         | Change the system wide configuration or the clients setup in your current git repo.  |
| `-q, --quiet`  |         | Only display errors.                                                                 |

----
url: https://docs.docker.com/reference/api/extensions-sdk/OpenDialogResult/
----

# Interface: OpenDialogResult

***

Table of contents

***

**`Since`**

0.2.3

## [Properties](#properties)

### [canceled](#canceled)

• `Readonly` **canceled**: `boolean`

Whether the dialog was canceled.

***

### [filePaths](#filepaths)

• `Readonly` **filePaths**: `string`\[]

An array of file paths chosen by the user. If the dialog is cancelled this will be an empty array.

***

### [bookmarks](#bookmarks)

• `Optional` `Readonly` **bookmarks**: `string`\[]

macOS only. An array matching the `filePaths` array of `base64` encoded strings which contains security scoped bookmark data. `securityScopedBookmarks` must be enabled for this to be populated.

----
url: https://docs.docker.com/compose/how-tos/environment-variables/
----

# Environment variables in Compose

***

***

Environment variables and interpolation in Docker Compose help you create reusable, flexible configurations. This makes Dockerized applications easier to manage and deploy across environments.

> Tip
>
> Before using environment variables, read through all of the information first to get a full picture of environment variables in Docker Compose.

This section covers:

* [How to set environment variables within your container's environment](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/).
* [How environment variable precedence works within your container's environment](https://docs.docker.com/compose/how-tos/environment-variables/envvars-precedence/).
* [Pre-defined environment variables](https://docs.docker.com/compose/how-tos/environment-variables/envvars/).

It also covers:

* How [interpolation](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) can be used to set variables within your Compose file and how it relates to a container's environment.
* Some [best practices](https://docs.docker.com/compose/how-tos/environment-variables/best-practices/).

----
url: https://docs.docker.com/reference/cli/docker/compose/bridge/convert/
----

# docker compose bridge convert

***

| Description | Convert compose files to Kubernetes manifests, Helm charts, or another model |
| ----------- | ---------------------------------------------------------------------------- |
| Usage       | `docker compose bridge convert`                                              |

## [Description](#description)

Convert compose files to Kubernetes manifests, Helm charts, or another model

## [Options](#options)

| Option                 | Default | Description                                                                           |
| ---------------------- | ------- | ------------------------------------------------------------------------------------- |
| `-o, --output`         | `out`   | The output directory for the Kubernetes resources                                     |
| `--templates`          |         | Directory containing transformation templates                                         |
| `-t, --transformation` |         | Transformation to apply to compose model (default: docker/compose-bridge-kubernetes)  |

----
url: https://docs.docker.com/reference/cli/docker/context/create/
----

# docker context create

***

| Description | Create a context                          |
| ----------- | ----------------------------------------- |
| Usage       | `docker context create [OPTIONS] CONTEXT` |

## [Description](#description)

Creates a new `context`. This lets you switch the daemon your `docker` CLI connects to.

## [Options](#options)

| Option                | Default | Description                         |
| --------------------- | ------- | ----------------------------------- |
| `--description`       |         | Description of the context          |
| [`--docker`](#docker) |         | set the docker endpoint             |
| [`--from`](#from)     |         | create context from a named context |

## [Examples](#examples)

### [Create a context with a Docker endpoint (--docker)](#docker)

Use the `--docker` flag to create a context with a custom endpoint. The following example creates a context named `my-context` with a docker endpoint of `/var/run/docker.sock`:

```console
$ docker context create \
    --docker host=unix:///var/run/docker.sock \
    my-context
```

### [Create a context based on an existing context (--from)](#from)

Use the `--from=<context-name>` option to create a new context from an existing context. The example below creates a new context named `my-context` from the existing context `existing-context`:

```console
$ docker context create --from existing-context my-context
```

If the `--from` option isn't set, the `context` is created from the current context:

```console
$ docker context create my-context
```

This can be used to create a context out of an existing `DOCKER_HOST` based script:

```console
$ source my-setup-script.sh
$ docker context create my-context
```

To source the `docker` endpoint configuration from an existing context use the `--docker from=<context-name>` option. The example below creates a new context named `my-context` using the docker endpoint configuration from the existing context `existing-context`:

```console
$ docker context create \
    --docker from=existing-context \
    my-context
```

Docker endpoints configurations, as well as the description can be modified with `docker context update`.

Refer to the [`docker context update` reference](/reference/cli/docker/context/update/) for details.

----
url: https://docs.docker.com/reference/cli/dockerd/
----

# dockerd

***

Table of contents

***

# [daemon](#daemon)

```markdown
Usage:	dockerd [OPTIONS]

A self-sufficient runtime for containers.

Options:
      --add-runtime runtime                   Register an additional OCI compatible runtime (default [])
      --allow-direct-routing                  Allow remote access to published ports on container IP addresses
      --authorization-plugin list             Authorization plugins to load
      --bip string                            IPv4 address for the default bridge
      --bip6 string                           IPv6 address for the default bridge
  -b, --bridge string                         Attach containers to a network bridge
      --bridge-accept-fwmark string           In bridge networks, accept packets with this firewall mark/mask
      --cdi-spec-dir list                     CDI specification directories to use
      --cgroup-parent string                  Set parent cgroup for all containers
      --config-file string                    Daemon configuration file (default "/etc/docker/daemon.json")
      --containerd string                     containerd grpc address
      --containerd-namespace string           Containerd namespace to use (default "moby")
      --containerd-plugins-namespace string   Containerd namespace to use for plugins (default "plugins.moby")
      --cpu-rt-period int                     Limit the CPU real-time period in microseconds for the
                                              parent cgroup for all containers (not supported with cgroups v2)
      --cpu-rt-runtime int                    Limit the CPU real-time runtime in microseconds for the
                                              parent cgroup for all containers (not supported with cgroups v2)
      --cri-containerd                        start containerd with cri
      --data-root string                      Root directory of persistent Docker state (default "/var/lib/docker")
  -D, --debug                                 Enable debug mode
      --default-address-pool pool-options     Default address pools for node specific local networks
      --default-cgroupns-mode string          Default mode for containers cgroup namespace ("host" | "private") (default "private")
      --default-gateway ip                    Default gateway IPv4 address for the default bridge network
      --default-gateway-v6 ip                 Default gateway IPv6 address for the default bridge network
      --default-ipc-mode string               Default mode for containers ipc ("shareable" | "private") (default "private")
      --default-network-opt mapmap            Default network options (default map[])
      --default-runtime string                Default OCI runtime for containers (default "runc")
      --default-shm-size bytes                Default shm size for containers (default 64MiB)
      --default-ulimit ulimit                 Default ulimits for containers (default [])
      --dns list                              DNS server to use
      --dns-opt list                          DNS options to use
      --dns-search list                       DNS search domains to use
      --exec-opt list                         Runtime execution options
      --exec-root string                      Root directory for execution state files (default "/var/run/docker")
      --experimental                          Enable experimental features
      --feature map                           Enable feature in the daemon
      --firewall-backend string               Firewall backend to use, iptables or nftables
      --fixed-cidr string                     IPv4 subnet for the default bridge network
      --fixed-cidr-v6 string                  IPv6 subnet for the default bridge network
  -G, --group string                          Group for the unix socket (default "docker")
      --help                                  Print usage
  -H, --host list                             Daemon socket(s) to connect to
      --host-gateway-ip list                  IP addresses that the special 'host-gateway' string in --add-host resolves to.
                                              Defaults to the IP addresses of the default bridge
      --http-proxy string                     HTTP proxy URL to use for outgoing traffic
      --https-proxy string                    HTTPS proxy URL to use for outgoing traffic
      --icc                                   Enable inter-container communication for the default bridge network (default true)
      --init                                  Run an init in the container to forward signals and reap processes
      --init-path string                      Path to the docker-init binary
      --insecure-registry list                Enable insecure registry communication
      --ip ip                                 Host IP for port publishing from the default bridge network (default 0.0.0.0)
      --ip-forward                            Enable IP forwarding in system configuration (default true)
      --ip-forward-no-drop                    Do not set the filter-FORWARD policy to DROP when enabling IP forwarding
      --ip-masq                               Enable IP masquerading for the default bridge network (default true)
      --ip6tables                             Enable addition of ip6tables rules (default true)
      --iptables                              Enable addition of iptables rules (default true)
      --ipv6                                  Enable IPv6 networking for the default bridge network
      --label list                            Set key=value labels to the daemon
      --live-restore                          Enable live restore of docker when containers are still running
      --log-driver string                     Default driver for container logs (default "json-file")
      --log-format string                     Set the logging format ("text"|"json") (default "text")
  -l, --log-level string                      Set the logging level ("debug"|"info"|"warn"|"error"|"fatal") (default "info")
      --log-opt map                           Default log driver options for containers (default map[])
      --max-concurrent-downloads int          Set the max concurrent downloads (default 3)
      --max-concurrent-uploads int            Set the max concurrent uploads (default 5)
      --max-download-attempts int             Set the max download attempts for each pull (default 5)
      --metrics-addr string                   Set default address and port to serve the metrics api on
      --mtu int                               Set the MTU for the default "bridge" network (default 1500)
      --network-control-plane-mtu int         Network Control plane MTU (default 1500)
      --no-new-privileges                     Set no-new-privileges by default for new containers
      --no-proxy string                       Comma-separated list of hosts or IP addresses for which the proxy is skipped
      --node-generic-resource list            Advertise user-defined resource
  -p, --pidfile string                        Path to use for daemon PID file (default "/var/run/docker.pid")
      --raw-logs                              Full timestamps without ANSI coloring
      --registry-mirror list                  Preferred registry mirror
      --rootless                              Enable rootless mode; typically used with RootlessKit
      --seccomp-profile string                Path to seccomp profile. Set to "unconfined" to disable the default seccomp profile (default "builtin")
      --selinux-enabled                       Enable selinux support
      --shutdown-timeout int                  Set the default shutdown timeout (default 15)
  -s, --storage-driver string                 Storage driver to use
      --storage-opt list                      Storage driver options
      --swarm-default-advertise-addr string   Set default address or interface for swarm advertised address
      --tls                                   Use TLS; implied by --tlsverify
      --tlscacert string                      Trust certs signed only by this CA (default "~/.docker/ca.pem")
      --tlscert string                        Path to TLS certificate file (default "~/.docker/cert.pem")
      --tlskey string                         Path to TLS key file (default "~/.docker/key.pem")
      --tlsverify                             Use TLS and verify the remote
      --userland-proxy                        Use userland proxy for loopback traffic (default true)
      --userland-proxy-path string            Path to the userland proxy binary
      --userns-remap string                   User/Group setting for user namespaces
      --validate                              Validate daemon configuration and exit
  -v, --version                               Print version information and quit
```

Options with \[] may be specified multiple times.

## [Description](#description)

`dockerd` is the persistent process that manages containers. Docker uses different binaries for the daemon and client. To run the daemon you type `dockerd`.

To run the daemon with debug output, use `dockerd --debug` or add `"debug": true` to [the `daemon.json` file](#daemon-configuration-file).

> Note
>
> **Enabling experimental features**
>
> Enable experimental features by starting `dockerd` with the `--experimental` flag or adding `"experimental": true` to the `daemon.json` file.

### [Environment variables](#environment-variables)

The following list of environment variables are supported by the `dockerd` daemon. Some of these environment variables are supported both by the Docker Daemon and the `docker` CLI. Refer to [Environment variables](https://docs.docker.com/reference/cli/docker/#environment-variables) to learn about environment variables supported by the `docker` CLI.

| Variable            | Description                                                                                                                                                                       |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DOCKER_CERT_PATH`  | Location of your authentication keys. This variable is used both by the [`docker` CLI](https://docs.docker.com/reference/cli/docker/) and the `dockerd` daemon.                   |
| `DOCKER_DRIVER`     | The storage driver to use.                                                                                                                                                        |
| `DOCKER_RAMDISK`    | If set this disables `pivot_root`.                                                                                                                                                |
| `DOCKER_TLS_VERIFY` | When set Docker uses TLS and verifies the remote. This variable is used both by the [`docker` CLI](https://docs.docker.com/reference/cli/docker/) and the `dockerd` daemon.       |
| `DOCKER_TMPDIR`     | Location for temporary files created by the daemon.                                                                                                                               |
| `HTTP_PROXY`        | Proxy URL for HTTP requests unless overridden by NoProxy. See the [Go specification](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) for details.                      |
| `HTTPS_PROXY`       | Proxy URL for HTTPS requests unless overridden by NoProxy. See the [Go specification](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) for details.                     |
| `MOBY_DISABLE_PIGZ` | Disables the use of [`unpigz`](https://linux.die.net/man/1/pigz) to decompress layers in parallel when pulling images, even if it is installed.                                   |
| `NO_PROXY`          | Comma-separated values specifying hosts that should be excluded from proxying. See the [Go specification](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) for details. |

## [Examples](#examples)

### [Proxy configuration](#proxy-configuration)

> Note
>
> Refer to the [Docker Desktop manual](https://docs.docker.com/desktop/networking/#httphttps-proxy-support) if you are running [Docker Desktop](https://docs.docker.com/desktop/).

If you are behind an HTTP proxy server, for example in corporate settings, you may have to configure the Docker daemon to use the proxy server for operations such as pulling and pushing images. The daemon can be configured in three ways:

1. Using environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`).
2. Using the `http-proxy`, `https-proxy`, and `no-proxy` fields in the [daemon configuration file](#daemon-configuration-file) (Docker Engine version 23.0 or later).
3. Using the `--http-proxy`, `--https-proxy`, and `--no-proxy` command-line options. (Docker Engine version 23.0 or later).

The command-line and configuration file options take precedence over environment variables. Refer to [control and configure Docker with systemd](https://docs.docker.com/engine/daemon/proxy/) to set these environment variables on a host using `systemd`.

### [Daemon socket option](#daemon-socket-option)

The Docker daemon can listen for [Docker Engine API](https://docs.docker.com/engine/api/) requests via three different types of Socket: `unix`, `tcp`, and `fd`.

By default, a `unix` domain socket (or IPC socket) is created at `/var/run/docker.sock`, requiring either `root` permission, or `docker` group membership.

If you need to access the Docker daemon remotely, you need to enable the tcp Socket. When using a TCP socket, the Docker daemon provides un-encrypted and un-authenticated direct access to the Docker daemon by default. You should secure the daemon either using the [built in HTTPS encrypted socket](https://docs.docker.com/engine/security/protect-access/), or by putting a secure web proxy in front of it. You can listen on port `2375` on all network interfaces with `-H tcp://0.0.0.0:2375`, or on a particular network interface using its IP address: `-H tcp://192.168.59.103:2375`. It is conventional to use port `2375` for un-encrypted, and port `2376` for encrypted communication with the daemon.

> Note
>
> If you're using an HTTPS encrypted socket, keep in mind that only TLS version 1.0 and higher is supported. Protocols SSLv3 and below are not supported for security reasons.

On systemd based systems, you can communicate with the daemon via [systemd socket activation](https://0pointer.de/blog/projects/socket-activation.html), with `dockerd -H fd://`. Using `fd://` works for most setups, but you can also specify individual sockets: `dockerd -H fd://3`. If the specified socket activated files aren't found, the daemon exits. You can find examples of using systemd socket activation with Docker and systemd in the [Docker source tree](https://github.com/docker/docker/tree/master/contrib/init/systemd/).

You can configure the Docker daemon to listen to multiple sockets at the same time using multiple `-H` options:

The example below runs the daemon listening on the default Unix socket, and on 2 specific IP addresses on this host:

```console
$ sudo dockerd -H unix:///var/run/docker.sock -H tcp://192.168.59.106 -H tcp://10.10.10.2
```

The Docker client honors the `DOCKER_HOST` environment variable to set the `-H` flag for the client. Use **one** of the following commands:

```console
$ docker -H tcp://0.0.0.0:2375 ps
```

```console
$ export DOCKER_HOST="tcp://0.0.0.0:2375"

$ docker ps
```

Setting the `DOCKER_TLS_VERIFY` environment variable to any value other than the empty string is equivalent to setting the `--tlsverify` flag. The following are equivalent:

```console
$ docker --tlsverify ps
# or
$ export DOCKER_TLS_VERIFY=1
$ docker ps
```

The Docker client honors the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables (or the lowercase versions thereof). `HTTPS_PROXY` takes precedence over `HTTP_PROXY`.

The Docker client supports connecting to a remote daemon via SSH:

```console
$ docker -H ssh://me@example.com:22/var/run/docker.sock ps
$ docker -H ssh://me@example.com:22 ps
$ docker -H ssh://me@example.com ps
$ docker -H ssh://example.com ps
```

To use SSH connection, you need to set up `ssh` so that it can reach the remote host with public key authentication. Password authentication is not supported. If your key is protected with passphrase, you need to set up `ssh-agent`.

#### [Bind Docker to another host/port or a Unix socket](#bind-docker-to-another-hostport-or-a-unix-socket)

> Warning
>
> Changing the default `docker` daemon binding to a TCP port or Unix `docker` user group introduces security risks, as it may allow non-root users to gain root access on the host. Make sure you control access to `docker`. If you are binding to a TCP port, anyone with access to that port has full Docker access; so it's not advisable on an open network.

With `-H` it's possible to make the Docker daemon to listen on a specific IP and port. By default, it listens on `unix:///var/run/docker.sock` to allow only local connections by the root user. You could set it to `0.0.0.0:2375` or a specific host IP to give access to everybody, but that isn't recommended because someone could gain root access to the host where the daemon is running.

Similarly, the Docker client can use `-H` to connect to a custom port. The Docker client defaults to connecting to `unix:///var/run/docker.sock` on Linux, and `tcp://127.0.0.1:2376` on Windows.

`-H` accepts host and port assignment in the following format:

```text
tcp://[host]:[port][path] or unix://path
```

For example:

* `tcp://` -> TCP connection to `127.0.0.1` on either port `2376` when TLS encryption is on, or port `2375` when communication is in plain text.
* `tcp://host:2375` -> TCP connection on host:2375
* `tcp://host:2375/path` -> TCP connection on host:2375 and prepend path to all requests
* `unix://path/to/socket` -> Unix socket located at `path/to/socket`

`-H`, when empty, defaults to the same value as when no `-H` was passed in.

`-H` also accepts short form for TCP bindings: `host:` or `host:port` or `:port`

Run Docker in daemon mode:

```console
$ sudo <path to>/dockerd -H 0.0.0.0:5555 &
```

Download an `ubuntu` image:

```console
$ docker -H :5555 pull ubuntu
```

You can use multiple `-H`, for example, if you want to listen on both TCP and a Unix socket

```console
$ sudo dockerd -H tcp://127.0.0.1:2375 -H unix:///var/run/docker.sock &
# Download an ubuntu image, use default Unix socket
$ docker pull ubuntu
# OR use the TCP port
$ docker -H tcp://127.0.0.1:2375 pull ubuntu
```

### [Daemon storage-driver](#daemon-storage-driver)

On Linux, the Docker daemon has support for several different image layer storage drivers: `overlay2`, `fuse-overlayfs`, `btrfs`, and `zfs`.

`overlay2` is the preferred storage driver for all currently supported Linux distributions, and is selected by default. Unless users have a strong reason to prefer another storage driver, `overlay2` should be used.

You can find out more about storage drivers and how to select one in [Select a storage driver](https://docs.docker.com/engine/storage/drivers/select-storage-driver/).

On Windows, the Docker daemon only supports the `windowsfilter` storage driver.

### [Options per storage driver](#options-per-storage-driver)

Particular storage-driver can be configured with options specified with `--storage-opt` flags. Options for `zfs` start with `zfs`, and options for `btrfs` start with `btrfs`.

#### [ZFS options](#zfs-options)

##### [`zfs.fsname`](#zfsfsname)

Specifies the ZFS filesystem that the daemon should use to create its datasets. By default, the ZFS filesystem in `/var/lib/docker` is used.

###### [Example](#example)

```console
$ sudo dockerd -s zfs --storage-opt zfs.fsname=zroot/docker
```

#### [Btrfs options](#btrfs-options)

##### [`btrfs.min_space`](#btrfsmin_space)

Specifies the minimum size to use when creating the subvolume which is used for containers. If user uses disk quota for btrfs when creating or running a container with **--storage-opt size** option, Docker should ensure the **size** can't be smaller than **btrfs.min\_space**.

###### [Example](#example-1)

```console
$ sudo dockerd -s btrfs --storage-opt btrfs.min_space=10G
```

#### [Overlay2 options](#overlay2-options)

##### [`overlay2.size`](#overlay2size)

Sets the default max size of the container. It is supported only when the backing filesystem is `xfs` and mounted with `pquota` mount option. Under these conditions the user can pass any size less than the backing filesystem size.

###### [Example](#example-2)

```console
$ sudo dockerd -s overlay2 --storage-opt overlay2.size=1G
```

#### [Windowsfilter options](#windowsfilter-options)

##### [`size`](#size)

Specifies the size to use when creating the sandbox which is used for containers. Defaults to 20G.

###### [Example](#example-3)

```powershell
C:\> dockerd --storage-opt size=40G
```

### [Runtime options](#runtime-options)

The Docker daemon relies on a [OCI](https://github.com/opencontainers/runtime-spec) compliant runtime (invoked via the `containerd` daemon) as its interface to the Linux kernel `namespaces`, `cgroups`, and `SELinux`.

#### [Configure container runtimes](#configure-container-runtimes)

By default, the Docker daemon uses runc as a container runtime. You can configure the daemon to add additional runtimes.

containerd shims installed on `PATH` can be used directly, without the need to edit the daemon's configuration. For example, if you install the Kata Containers shim (`containerd-shim-kata-v2`) on `PATH`, then you can select that runtime with `docker run` without having to edit the daemon's configuration:

```console
$ docker run --runtime io.containerd.kata.v2
```

Container runtimes that don't implement containerd shims, or containerd shims installed outside of `PATH`, must be registered with the daemon, either via the configuration file or using the `--add-runtime` command line flag.

For examples on how to use other container runtimes, see [Alternative container runtimes](https://docs.docker.com/engine/daemon/alternative-runtimes/)

##### [Configure runtimes using `daemon.json`](#configure-runtimes-using-daemonjson)

To register and configure container runtimes using the daemon's configuration file, add the runtimes as entries under `runtimes`:

```json
{
  "runtimes": {
    "<runtime>": {}
  }
}
```

The key of the entry (`<runtime>` in the previous example) represents the name of the runtime. This is the name that you reference when you run a container, using `docker run --runtime <runtime>`.

The runtime entry contains an object specifying the configuration for your runtime. The properties of the object depends on what kind of runtime you're looking to register:

* If the runtime implements its own containerd shim, the object shall contain a `runtimeType` field and an optional `options` field.

  ```json
  {
    "runtimes": {
      "<runtime>": {
        "runtimeType": "<name-or-path>",
        "options": {}
      }
    }
  }
  ```

  See [Configure shims](#configure-containerd-shims).

* If the runtime is designed to be a drop-in replacement for runc, the object contains a `path` field, and an optional `runtimeArgs` field.

  ```json
  {
    "runtimes": {
      "<runtime>": {
        "path": "/path/to/bin",
        "runtimeArgs": ["...args"]
      }
    }
  }
  ```

  See [Configure runc drop-in replacements](#configure-runc-drop-in-replacements).

After changing the runtimes configuration in the configuration file, you must reload or restart the daemon for changes to take effect:

```console
$ sudo systemctl reload dockerd
```

##### [Configure containerd shims](#configure-containerd-shims)

If the runtime that you want to register implements a containerd shim, or if you want to register a runtime which uses the runc shim, use the following format for the runtime entry:

```json
{
  "runtimes": {
    "<runtime>": {
      "runtimeType": "<name-or-path>",
      "options": {}
    }
  }
}
```

`runtimeType` refers to either:

* A fully qualified name of a containerd shim.

  The fully qualified name of a shim is the same as the `runtime_type` used to register the runtime in containerd's CRI configuration. For example, `io.containerd.runsc.v1`.

* The path of a containerd shim binary.

  This option is useful if you installed the containerd shim binary outside of `PATH`.

`options` is optional. It lets you specify the runtime configuration that you want to use for the shim. The configuration parameters that you can specify in `options` depends on the runtime you're registering. For most shims, the supported configuration options are `TypeUrl` and `ConfigPath`. For example:

```json
{
  "runtimes": {
    "gvisor": {
      "runtimeType": "io.containerd.runsc.v1",
      "options": {
        "TypeUrl": "io.containerd.runsc.v1.options",
        "ConfigPath": "/etc/containerd/runsc.toml"
      }
    }
  }
}
```

You can configure multiple runtimes using the same runtimeType. For example:

```json
{
  "runtimes": {
    "gvisor-foo": {
      "runtimeType": "io.containerd.runsc.v1",
      "options": {
        "TypeUrl": "io.containerd.runsc.v1.options",
        "ConfigPath": "/etc/containerd/runsc-foo.toml"
      }
    },
    "gvisor-bar": {
      "runtimeType": "io.containerd.runsc.v1",
      "options": {
        "TypeUrl": "io.containerd.runsc.v1.options",
        "ConfigPath": "/etc/containerd/runsc-bar.toml"
      }
    }
  }
}
```

The `options` field takes a special set of configuration parameters when used with `"runtimeType": "io.containerd.runc.v2"`. For more information about runc parameters, refer to the runc configuration section in [CRI Plugin Config Guide](https://github.com/containerd/containerd/blob/v1.7.2/docs/cri/config.md#full-configuration).

##### [Configure runc drop-in replacements](#configure-runc-drop-in-replacements)

If the runtime that you want to register can act as a drop-in replacement for runc, you can register the runtime either using the daemon configuration file, or using the `--add-runtime` flag for the `dockerd` cli.

When you use the configuration file, the entry uses the following format:

```json
{
  "runtimes": {
    "<runtime>": {
      "path": "/path/to/binary",
      "runtimeArgs": ["...args"]
    }
  }
}
```

Where `path` is either the absolute path to the runtime executable, or the name of an executable installed on `PATH`:

```json
{
  "runtimes": {
    "runc": {
      "path": "runc"
    }
  }
}
```

And `runtimeArgs` lets you optionally pass additional arguments to the runtime. Entries with this format use the containerd runc shim to invoke a custom runtime binary.

When you use the `--add-runtime` CLI flag, use the following format:

```console
$ sudo dockerd --add-runtime <runtime>=<path>
```

Defining runtime arguments via the command line is not supported.

For an example configuration for a runc drop-in replacement, see [Alternative container runtimes > youki](https://docs.docker.com/engine/daemon/alternative-runtimes/#youki)

##### [Configure the default container runtime](#configure-the-default-container-runtime)

You can specify either the name of a fully qualified containerd runtime shim, or the name of a registered runtime. You can specify the default runtime either using the daemon configuration file, or using the `--default-runtime` flag for the `dockerd` cli.

When you use the configuration file, the entry uses the following format:

```json
{
  "default-runtime": "io.containerd.runsc.v1"
}
```

When you use the `--default-runtime` CLI flag, use the following format:

```console
$ dockerd --default-runtime io.containerd.runsc.v1
```

#### [Run containerd standalone](#run-containerd-standalone)

By default, the Docker daemon automatically starts `containerd`. If you want to control `containerd` startup, manually start `containerd` and pass the path to the `containerd` socket using the `--containerd` flag. For example:

```console
$ sudo dockerd --containerd /run/containerd/containerd.sock
```

#### [Configure cgroup driver](#configure-cgroup-driver)

You can configure how the runtime should manage container cgroups, using the `--exec-opt native.cgroupdriver` CLI flag.

You can only specify `cgroupfs` or `systemd`. If you specify `systemd` and it is not available, the system errors out. If you omit the `native.cgroupdriver` option,` cgroupfs` is used on cgroup v1 hosts, `systemd` is used on cgroup v2 hosts with systemd available.

This example sets the `cgroupdriver` to `systemd`:

```console
$ sudo dockerd --exec-opt native.cgroupdriver=systemd
```

Setting this option applies to all containers the daemon launches.

#### [Configure container isolation technology (Windows)](#configure-container-isolation-technology-windows)

For Windows containers, you can specify the default container isolation technology to use, using the `--exec-opt isolation` flag.

The following example makes `hyperv` the default isolation technology:

```console
> dockerd --exec-opt isolation=hyperv
```

If no isolation value is specified on daemon start, on Windows client, the default is `hyperv`, and on Windows server, the default is `process`.

### [Daemon DNS options](#daemon-dns-options)

To set the DNS server for all Docker containers, use:

```console
$ sudo dockerd --dns 8.8.8.8
```

To set the DNS search domain for all Docker containers, use:

```console
$ sudo dockerd --dns-search example.com
```

### [Insecure registries](#insecure-registries)

In this section, "registry" refers to a private registry, and `myregistry:5000` is a placeholder example of a private registry.

Docker considers a private registry either secure or insecure. A secure registry uses TLS and a copy of its CA certificate is placed on the Docker host at `/etc/docker/certs.d/myregistry:5000/ca.crt`. An insecure registry is either not using TLS (i.e., listening on plain text HTTP), or is using TLS with a CA certificate not known by the Docker daemon. The latter can happen when the certificate wasn't found under `/etc/docker/certs.d/myregistry:5000/`, or if the certificate verification failed (i.e., wrong CA).

By default, Docker assumes all registries to be secure, except for local registries. Communicating with an insecure registry isn't possible if Docker assumes that registry is secure. In order to communicate with an insecure registry, the Docker daemon requires `--insecure-registry` in one of the following two forms:

* `--insecure-registry myregistry:5000` tells the Docker daemon that myregistry:5000 should be considered insecure.
* `--insecure-registry 10.1.0.0/16` tells the Docker daemon that all registries whose domain resolve to an IP address is part of the subnet described by the CIDR syntax, should be considered insecure.

The flag can be used multiple times to allow multiple registries to be marked as insecure.

If an insecure registry isn't marked as insecure, `docker pull`, `docker push`, and `docker search` result in error messages, prompting the user to either secure or pass the `--insecure-registry` flag to the Docker daemon as described above.

Local registries, whose IP address falls in the 127.0.0.0/8 range, are automatically marked as insecure as of Docker 1.3.2. It isn't recommended to rely on this, as it may change in the future.

Enabling `--insecure-registry`, i.e., allowing un-encrypted and/or untrusted communication, can be useful when running a local registry. However, because its use creates security vulnerabilities it should only be enabled for testing purposes. For increased security, users should add their CA to their system's list of trusted CAs instead of enabling `--insecure-registry`.

#### [Legacy Registries](#legacy-registries)

Operations against registries supporting only the legacy v1 protocol are no longer supported. Specifically, the daemon doesn't attempt to push, pull or sign in to v1 registries. The exception to this is `search` which can still be performed on v1 registries.

### [Running a Docker daemon behind an HTTPS\_PROXY](#running-a-docker-daemon-behind-an-https_proxy)

When running inside a LAN that uses an `HTTPS` proxy, the proxy's certificates replace Docker Hub's certificates. These certificates must be added to your Docker host's configuration:

1. Install the `ca-certificates` package for your distribution
2. Ask your network admin for the proxy's CA certificate and append them to `/etc/pki/tls/certs/ca-bundle.crt`
3. Then start your Docker daemon with `HTTPS_PROXY=http://username:password@proxy:port/ dockerd`. The `username:` and `password@` are optional - and are only needed if your proxy is set up to require authentication.

This only adds the proxy and authentication to the Docker daemon's requests. To use the proxy when building images and running containers, see [Configure Docker to use a proxy server](https://docs.docker.com/engine/cli/proxy/)

### [Default `ulimit` settings](#default-ulimit-settings)

The `--default-ulimit` flag lets you set the default `ulimit` options to use for all containers. It takes the same options as `--ulimit` for `docker run`. If these defaults aren't set, `ulimit` settings are inherited from the Docker daemon. Any `--ulimit` options passed to `docker run` override the daemon defaults.

Be careful setting `nproc` with the `ulimit` flag, as `nproc` is designed by Linux to set the maximum number of processes available to a user, not to a container. For details, see [`docker run` reference](https://docs.docker.com/reference/cli/docker/container/run/#ulimit).

### [Access authorization](#access-authorization)

Docker's access authorization can be extended by authorization plugins that your organization can purchase or build themselves. You can install one or more authorization plugins when you start the Docker `daemon` using the `--authorization-plugin=PLUGIN_ID` option.

```console
$ sudo dockerd --authorization-plugin=plugin1 --authorization-plugin=plugin2,...
```

The `PLUGIN_ID` value is either the plugin's name or a path to its specification file. The plugin's implementation determines whether you can specify a name or path. Consult with your Docker administrator to get information about the plugins available to you.

Once a plugin is installed, requests made to the `daemon` through the command line or Docker's Engine API are allowed or denied by the plugin. If you have multiple plugins installed, each plugin, in order, must allow the request for it to complete.

For information about how to create an authorization plugin, refer to the [authorization plugin](https://docs.docker.com/engine/extend/plugins_authorization/) section.

### [Daemon user namespace options](#daemon-user-namespace-options)

The Linux kernel [user namespace support](https://man7.org/linux/man-pages/man7/user_namespaces.7.html) provides additional security by enabling a process, and therefore a container, to have a unique range of user and group IDs which are outside the traditional user and group range utilized by the host system. One of the most important security improvements is that, by default, container processes running as the `root` user have expected administrative privileges it expects (with some restrictions) inside the container, but are effectively mapped to an unprivileged `uid` on the host.

For details about how to use this feature, as well as limitations, see [Isolate containers with a user namespace](https://docs.docker.com/engine/security/userns-remap/).

### [Configure host gateway IP](#configure-host-gateway-ip)

The Docker daemon supports a special `host-gateway` value for the `--add-host` flag for the `docker run` and `docker build` commands. This value resolves to addresses on the host, so that containers can connect to services running on the host.

By default, `host-gateway` resolves to the IPv4 address of the default bridge, and its IPv6 address if it has one.

You can configure this to resolve to a different IP using the `--host-gateway-ip` flag for the dockerd command line interface, or the `host-gateway-ip` key in the daemon configuration file.

To supply both IPv4 and IPv6 addresses on the command line, use two `--host-gateway-ip` options.

To supply addresses in the daemon configuration file, use `"host-gateway-ips"` with a JSON array, as shown below. For compatibility with older versions of the daemon, a single IP address can also be specified as a JSON string in option `"host-gateway-ip"`.

```console
$ cat > /etc/docker/daemon.json
{ "host-gateway-ips": ["192.0.2.1", "2001:db8::1111"]}
$ sudo systemctl restart docker
$ docker run -it --add-host host.docker.internal:host-gateway \
  busybox ping host.docker.internal 
PING host.docker.internal (192.0.2.1): 56 data bytes
$ docker run -it --add-host host.docker.internal:host-gateway \
  busybox ping -6 host.docker.internal
PING host.docker.internal (2001:db8::1111): 56 data bytes
```

### [Configure CDI devices](#configure-cdi-devices)

Container Device Interface (CDI) is a [standardized](https://github.com/cncf-tags/container-device-interface/blob/main/SPEC.md) mechanism for container runtimes to create containers which are able to interact with third party devices.

CDI is currently only supported for Linux containers and is enabled by default since Docker Engine 28.3.0.

The Docker daemon supports running containers with CDI devices if the requested device specifications are available on the filesystem of the daemon.

The default specification directories are:

* `/etc/cdi/` for static CDI Specs
* `/var/run/cdi` for generated CDI Specs

#### [Set custom locations](#set-custom-locations)

To set custom locations for CDI specifications, use the `cdi-spec-dirs` option in the `daemon.json` configuration file, or the `--cdi-spec-dir` flag for the `dockerd` CLI:

```json
{
  "cdi-spec-dirs": ["/etc/cdi/", "/var/run/cdi"]
}
```

You can view the configured CDI specification directories using the `docker info` command.

#### [Disable CDI devices](#disable-cdi-devices)

The feature in enabled by default. To disable it, use the `cdi` options in the `daemon.json` file:

```json
"features": {
  "cdi": false
},
```

To check the status of the CDI devices, run `docker info`.

#### [Daemon logging format](#log-format)

The `--log-format` option or "log-format" option in the [daemon configuration file](#daemon-configuration-file) lets you set the format for logs produced by the daemon. The logging format should only be configured either through the `--log-format` command line option or through the "log-format" field in the configuration file; using both the command-line option and the "log-format" field in the configuration file produces an error. If this option is not set, the default is "text".

The following example configures the daemon through the `--log-format` command line option to use `json` formatted logs;

```console
$ dockerd --log-format=json
# ...
{"level":"info","msg":"API listen on /var/run/docker.sock","time":"2024-09-16T11:06:08.558145428Z"}
```

The following example shows a `daemon.json` configuration file with the "log-format" set;

```json
{
  "log-format": "json"
}
```

### [Miscellaneous options](#miscellaneous-options)

IP masquerading uses address translation to allow containers without a public IP to talk to other machines on the internet. This may interfere with some network topologies, and can be disabled with `--ip-masq=false`.

Docker supports soft links for the Docker data directory (`/var/lib/docker`) and for `/var/lib/docker/tmp`. The `DOCKER_TMPDIR` and the data directory can be set like this:

```console
$ export DOCKER_TMPDIR=/mnt/disk2/tmp
$ sudo -E dockerd --data-root /var/lib/docker -H unix://
```

#### [Default cgroup parent](#default-cgroup-parent)

The `--cgroup-parent` option lets you set the default cgroup parent for containers. If this option isn't set, it defaults to `/docker` for the cgroupfs driver, and `system.slice` for the systemd cgroup driver.

If the cgroup has a leading forward slash (`/`), the cgroup is created under the root cgroup, otherwise the cgroup is created under the daemon cgroup.

Assuming the daemon is running in cgroup `daemoncgroup`, `--cgroup-parent=/foobar` creates a cgroup in `/sys/fs/cgroup/memory/foobar`, whereas using `--cgroup-parent=foobar` creates the cgroup in `/sys/fs/cgroup/memory/daemoncgroup/foobar`

The systemd cgroup driver has different rules for `--cgroup-parent`. systemd represents hierarchy by slice and the name of the slice encodes the location in the tree. So `--cgroup-parent` for systemd cgroups should be a slice name. A name can consist of a dash-separated series of names, which describes the path to the slice from the root slice. For example, `--cgroup-parent=user-a-b.slice` means the memory cgroup for the container is created in `/sys/fs/cgroup/memory/user.slice/user-a.slice/user-a-b.slice/docker-<id>.scope`.

This setting can also be set per container, using the `--cgroup-parent` option on `docker create` and `docker run`, and takes precedence over the `--cgroup-parent` option on the daemon.

#### [Daemon metrics](#daemon-metrics)

The `--metrics-addr` option takes a TCP address to serve the metrics API.

To serve the metrics API on `localhost:9323` you would specify `--metrics-addr 127.0.0.1:9323`, allowing you to make requests on the API at `127.0.0.1:9323/metrics` to receive metrics in the [prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/) format.

Port `9323` is the [default port associated with Docker metrics](https://github.com/prometheus/prometheus/wiki/Default-port-allocations) to avoid collisions with other Prometheus exporters and services.

If you are running a Prometheus server you can add this address to your scrape configs to have Prometheus collect metrics on Docker. For more information, see [Collect Docker metrics with Prometheus](https://docs.docker.com/engine/daemon/prometheus/).

#### [Node generic resources](#node-generic-resources)

The `--node-generic-resources` option takes a list of key-value pair (`key=value`) that allows you to advertise user defined resources in a Swarm cluster.

The current expected use case is to advertise NVIDIA GPUs so that services requesting `NVIDIA-GPU=[0-16]` can land on a node that has enough GPUs for the task to run.

Example of usage:

```json
{
  "node-generic-resources": [
    "NVIDIA-GPU=UUID1",
    "NVIDIA-GPU=UUID2"
  ]
}
```

### [Enable feature in the daemon (--feature)](#feature)

The `--feature` option lets you enable or disable a feature in the daemon. This option corresponds with the "features" field in the [daemon.json configuration file](#daemon-configuration-file). Features should only be configured either through the `--feature` command line option or through the "features" field in the configuration file; using both the command-line option and the "features" field in the configuration file produces an error. The feature option can be specified multiple times to configure multiple features. The `--feature` option accepts a name and optional boolean value. When omitting the value, the default is `true`.

The following example runs the daemon with the `cdi` and `containerd-snapshotter` features enabled. The `cdi` option is provided with a value;

```console
$ dockerd --feature cdi=true --feature containerd-snapshotter
```

The following example is the equivalent using the `daemon.json` configuration file;

```json
{
  "features": {
    "cdi": true,
    "containerd-snapshotter": true
  }
}
```

### [Daemon configuration file](#daemon-configuration-file)

The `--config-file` option allows you to set any configuration option for the daemon in a JSON format. This file uses the same flag names as keys, except for flags that allow several entries, where it uses the plural of the flag name, e.g., `labels` for the `label` flag.

The options set in the configuration file must not conflict with options set using flags. The Docker daemon fails to start if an option is duplicated between the file and the flags, regardless of their value. This is intentional, and avoids silently ignore changes introduced in configuration reloads. For example, the daemon fails to start if you set daemon labels in the configuration file and also set daemon labels via the `--label` flag. Options that are not present in the file are ignored when the daemon starts.

The `--validate` option allows to validate a configuration file without starting the Docker daemon. A non-zero exit code is returned for invalid configuration files.

```console
$ dockerd --validate --config-file=/tmp/valid-config.json
configuration OK

$ echo $?
0

$ dockerd --validate --config-file /tmp/invalid-config.json
unable to configure the Docker daemon with file /tmp/invalid-config.json: the following directives don't match any configuration option: unknown-option

$ echo $?
1
```

##### [On Linux](#on-linux)

The default location of the configuration file on Linux is `/etc/docker/daemon.json`. Use the `--config-file` flag to specify a non-default location.

The following is a full example of the allowed configuration options on Linux:

```json
{
  "allow-direct-routing": false,
  "authorization-plugins": [],
  "bip": "",
  "bip6": "",
  "bridge": "",
  "bridge-accept-fwmark": "",
  "builder": {
    "gc": {
      "enabled": true,
      "defaultReservedSpace": "10GB",
      "policy": [
        { "maxUsedSpace": "512MB", "keepDuration": "48h", "filter": [ "type=source.local" ] },
        { "reservedSpace": "10GB", "maxUsedSpace": "100GB", "keepDuration": "1440h" },
        { "reservedSpace": "50GB", "minFreeSpace": "20GB", "maxUsedSpace": "200GB", "all": true }
      ]
    }
  },
  "cgroup-parent": "",
  "containerd": "/run/containerd/containerd.sock",
  "containerd-namespace": "docker",
  "containerd-plugins-namespace": "docker-plugins",
  "data-root": "",
  "debug": true,
  "default-address-pools": [
    {
      "base": "172.30.0.0/16",
      "size": 24
    },
    {
      "base": "172.31.0.0/16",
      "size": 24
    }
  ],
  "default-cgroupns-mode": "private",
  "default-gateway": "",
  "default-gateway-v6": "",
  "default-network-opts": {},
  "default-runtime": "runc",
  "default-shm-size": "64M",
  "default-ulimits": {
    "nofile": {
      "Hard": 64000,
      "Name": "nofile",
      "Soft": 64000
    }
  },
  "dns": [],
  "dns-opts": [],
  "dns-search": [],
  "exec-opts": [],
  "exec-root": "",
  "experimental": false,
  "features": {
    "cdi": true,
    "containerd-snapshotter": true
  },
  "firewall-backend": "",
  "fixed-cidr": "",
  "fixed-cidr-v6": "",
  "group": "",
  "host-gateway-ip": "",
  "hosts": [],
  "proxies": {
    "http-proxy": "http://proxy.example.com:80",
    "https-proxy": "https://proxy.example.com:443",
    "no-proxy": "*.test.example.com,.example.org"
  },
  "icc": false,
  "init": false,
  "init-path": "/usr/libexec/docker-init",
  "insecure-registries": [],
  "ip": "0.0.0.0",
  "ip-forward": false,
  "ip-masq": false,
  "iptables": false,
  "ip6tables": false,
  "ipv6": false,
  "labels": [],
  "live-restore": true,
  "log-driver": "json-file",
  "log-format": "text",
  "log-level": "",
  "log-opts": {
    "cache-disabled": "false",
    "cache-max-file": "5",
    "cache-max-size": "20m",
    "cache-compress": "true",
    "env": "os,customer",
    "labels": "somelabel",
    "max-file": "5",
    "max-size": "10m"
  },
  "max-concurrent-downloads": 3,
  "max-concurrent-uploads": 5,
  "max-download-attempts": 5,
  "mtu": 0,
  "no-new-privileges": false,
  "node-generic-resources": [
    "NVIDIA-GPU=UUID1",
    "NVIDIA-GPU=UUID2"
  ],
  "pidfile": "",
  "raw-logs": false,
  "registry-mirrors": [],
  "runtimes": {
    "cc-runtime": {
      "path": "/usr/bin/cc-runtime"
    },
    "custom": {
      "path": "/usr/local/bin/my-runc-replacement",
      "runtimeArgs": [
        "--debug"
      ]
    }
  },
  "seccomp-profile": "",
  "selinux-enabled": false,
  "shutdown-timeout": 15,
  "storage-driver": "",
  "storage-opts": [],
  "swarm-default-advertise-addr": "",
  "tls": true,
  "tlscacert": "",
  "tlscert": "",
  "tlskey": "",
  "tlsverify": true,
  "userland-proxy": false,
  "userland-proxy-path": "/usr/libexec/docker-proxy",
  "userns-remap": ""
}
```

> Note
>
> You can't set options in `daemon.json` that have already been set on daemon startup as a flag. On systems that use systemd to start the Docker daemon, `-H` is already set, so you can't use the `hosts` key in `daemon.json` to add listening addresses. See [custom Docker daemon options](https://docs.docker.com/engine/daemon/proxy/#systemd-unit-file) for an example on how to configure the daemon using systemd drop-in files.

##### [On Windows](#on-windows)

The default location of the configuration file on Windows is `%programdata%\docker\config\daemon.json`. Use the `--config-file` flag to specify a non-default location.

The following is a full example of the allowed configuration options on Windows:

```json
{
  "authorization-plugins": [],
  "bridge": "",
  "containerd": "\\\\.\\pipe\\containerd-containerd",
  "containerd-namespace": "docker",
  "containerd-plugins-namespace": "docker-plugins",
  "data-root": "",
  "debug": true,
  "default-network-opts": {},
  "default-runtime": "",
  "default-ulimits": {},
  "dns": [],
  "dns-opts": [],
  "dns-search": [],
  "exec-opts": [],
  "experimental": false,
  "features": {},
  "fixed-cidr": "",
  "group": "",
  "host-gateway-ip": "",
  "hosts": [],
  "insecure-registries": [],
  "labels": [],
  "log-driver": "",
  "log-format": "text",
  "log-level": "",
  "max-concurrent-downloads": 3,
  "max-concurrent-uploads": 5,
  "max-download-attempts": 5,
  "mtu": 0,
  "pidfile": "",
  "raw-logs": false,
  "registry-mirrors": [],
  "shutdown-timeout": 15,
  "storage-driver": "",
  "storage-opts": [],
  "swarm-default-advertise-addr": "",
  "tlscacert": "",
  "tlscert": "",
  "tlskey": "",
  "tlsverify": true
}
```

The `default-runtime` option is by default unset, in which case dockerd automatically detects the runtime. This detection is based on if the `containerd` flag is set.

Accepted values:

* `com.docker.hcsshim.v1` - This is the built-in runtime that Docker has used since Windows supported was first added and uses the v1 HCS API's in Windows.
* `io.containerd.runhcs.v1` - This is uses the containerd `runhcs` shim to run the container and uses the v2 HCS API's in Windows.

#### [Feature options](#feature-options)

The optional field `features` in `daemon.json` lets you enable or disable specific daemon features.

```json
{
  "features": {
    "some-feature": true,
    "some-disabled-feature-enabled-by-default": false
  }
}
```

The list of feature options include:

* `containerd-snapshotter`: when set to `true`, the daemon uses containerd snapshotters instead of the classic storage drivers for storing image and container data. For more information, see [containerd storage](https://docs.docker.com/engine/storage/containerd/).

* `windows-dns-proxy`: when set to `true`, the daemon's internal DNS resolver will forward requests to external servers. Without this, most applications running in the container will still be able to use secondary DNS servers configured in the container itself, but `nslookup` won't be able to resolve external names. The current default is `false`, it will change to `true` in a future release. This option is only allowed on Windows.

  > Warning
  >
  > The `windows-dns-proxy` feature flag will be removed in a future release.

#### [Configuration reload behavior](#configuration-reload-behavior)

Some options can be reconfigured when the daemon is running without requiring to restart the process. The daemon uses the `SIGHUP` signal in Linux to reload, and a global event in Windows with the key `Global\docker-daemon-config-$PID`. You can modify the options in the configuration file, but the daemon still checks for conflicting settings with the specified CLI flags. The daemon fails to reconfigure itself if there are conflicts, but it won't stop execution.

The list of currently supported options that can be reconfigured is this:

| Option                     | Description                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `debug`                    | Toggles debug mode of the daemon.                                                                           |
| `labels`                   | Replaces the daemon labels with a new set of labels.                                                        |
| `live-restore`             | Toggles [live restore](https://docs.docker.com/engine/daemon/live-restore/).                                |
| `max-concurrent-downloads` | Configures the max concurrent downloads for each pull.                                                      |
| `max-concurrent-uploads`   | Configures the max concurrent uploads for each push.                                                        |
| `max-download-attempts`    | Configures the max download attempts for each pull.                                                         |
| `default-runtime`          | Configures the runtime to be used if not is specified at container creation.                                |
| `runtimes`                 | Configures the list of available OCI runtimes that can be used to run containers.                           |
| `authorization-plugin`     | Specifies the authorization plugins to use.                                                                 |
| `insecure-registries`      | Specifies a list of registries that the daemon should consider insecure.                                    |
| `registry-mirrors`         | Specifies a list of registry mirrors.                                                                       |
| `shutdown-timeout`         | Configures the daemon's existing configuration timeout with a new timeout for shutting down all containers. |
| `features`                 | Enables or disables specific features.                                                                      |

### [Run multiple daemons](#run-multiple-daemons)

> Note
>
> Running multiple daemons on a single host is considered experimental. You may encounter unsolved problems, and things may not work as expected in some cases.

This section describes how to run multiple Docker daemons on a single host. To run multiple daemons, you must configure each daemon so that it doesn't conflict with other daemons on the same host. You can set these options either by providing them as flags, or by using a [daemon configuration file](#daemon-configuration-file).

The following daemon options must be configured for each daemon:

```text
-b, --bridge=                          Attach containers to a network bridge
--exec-root=/var/run/docker            Root of the Docker execdriver
--data-root=/var/lib/docker            Root of persisted Docker data
-p, --pidfile=/var/run/docker.pid      Path to use for daemon PID file
-H, --host=[]                          Daemon socket(s) to connect to
--iptables=true                        Enable addition of iptables rules
--config-file=/etc/docker/daemon.json  Daemon configuration file
--tlscacert="~/.docker/ca.pem"         Trust certs signed only by this CA
--tlscert="~/.docker/cert.pem"         Path to TLS certificate file
--tlskey="~/.docker/key.pem"           Path to TLS key file
```

When your daemons use different values for these flags, you can run them on the same host without any problems. It is important that you understand the meaning of these options and to use them correctly.

* The `-b, --bridge=` flag is set to `docker0` as default bridge network. It is created automatically when you install Docker. If you aren't using the default, you must create and configure the bridge manually, or set it to 'none': `--bridge=none`
* `--exec-root` is the path where the container state is stored. The default value is `/var/run/docker`. Specify the path for your running daemon here.
* `--data-root` is the path where persisted data such as images, volumes, and cluster state are stored. The default value is `/var/lib/docker`. To avoid any conflict with other daemons, set this parameter separately for each daemon.
* `-p, --pidfile=/var/run/docker.pid` is the path where the process ID of the daemon is stored. Specify the path for your PID file here.
* `--host=[]` specifies where the Docker daemon listens for client connections. If unspecified, it defaults to `/var/run/docker.sock`.
* `--iptables=false` prevents the Docker daemon from adding iptables rules. If multiple daemons manage iptables rules, they may overwrite rules set by another daemon. Be aware that disabling this option requires you to manually add iptables rules to expose container ports. If you prevent Docker from adding iptables rules, Docker also doesn't add IP masquerading rules, even if you set `--ip-masq` to `true`. Without IP masquerading rules, Docker containers can't connect to external hosts or the internet when using network other than default bridge.
* `--config-file=/etc/docker/daemon.json` is the path where configuration file is stored. You can use it instead of daemon flags. Specify the path for each daemon.
* `--tls*` Docker daemon supports `--tlsverify` mode that enforces encrypted and authenticated remote connections. The `--tls*` options enable use of specific certificates for individual daemons.

Example script for a separate “bootstrap” instance of the Docker daemon without network:

```console
$ sudo dockerd \
        -H unix:///var/run/docker-bootstrap.sock \
        -p /var/run/docker-bootstrap.pid \
        --iptables=false \
        --ip-masq=false \
        --bridge=none \
        --data-root=/var/lib/docker-bootstrap \
        --exec-root=/var/run/docker-bootstrap
```

### [Default network options](#default-network-options)

The `default-network-opts` key in the `daemon.json` configuration file, and the equivalent `--default-network-opt` CLI flag, let you specify default values for driver network driver options for new networks.

The following example shows how to configure options for the `bridge` driver using the `daemon.json` file.

```json
{
  "default-network-opts": {
    "bridge": {
      "com.docker.network.bridge.host_binding_ipv4": "127.0.0.1",
      "com.docker.network.driver.mtu": "1234"
    }
  }
}
```

This example uses the `bridge` network driver. Refer to the [bridge network driver page](https://docs.docker.com/engine/network/drivers/bridge/#options) for an overview of available driver options.

After changing the configuration and restarting the daemon, new networks that you create use these option configurations as defaults.

```console
$ docker network create mynet
$ docker network inspect mynet --format "{{json .Options}}"
{"com.docker.network.bridge.host_binding_ipv4":"127.0.0.1","com.docker.network.driver.mtu":"1234"}
```

Note that changing this daemon configuration doesn't affect pre-existing networks.

Using the `--default-network-opt` CLI flag is useful for testing and debugging purposes, but you should prefer using the `daemon.json` file for persistent daemon configuration. The CLI flag expects a value with the following format: `driver=opt=value`, for example:

```console
$ sudo dockerd \
  --default-network-opt bridge=com.docker.network.bridge.host_binding_ipv4=127.0.0.1 \
  --default-network-opt bridge=com.docker.network.driver.mtu=1234
```

----
url: https://docs.docker.com/build/policies/
----

# Validating build inputs with policies

***

Table of contents

***

Building with Docker often involves downloading remote resources. These external dependencies, such as Docker images, Git repositories, remote files, and other artifacts, are called build inputs.

For example:

* Pulling images from a registry
* Cloning a source code repository
* Fetching files from a server over HTTPS

When consuming build inputs, it's a good idea to verify the contents are what you expect them to be. One way to do this is to use the `--checksum` option for the `ADD` Dockerfile instruction. This lets you verify the SHA256 checksum of a remote resource when pulling it into a build:

```dockerfile
ADD --checksum=sha256:c0ff3312345… https://example.com/archive.tar.gz /
```

If the remote `archive.tar.gz` file does not match the checksum that the Dockerfile expects, the build fails.

Checksums verify that content matches what you expect, but only for the `ADD` instruction. They don't tell you anything about where the content came from or how it was produced. You can't use checksums to enforce constraints like "images must be signed" or "dependencies must come from approved sources."

Build policies solve this problem. They let you define rules that validate all your build inputs, enforcing requirements like provenance attestations, approved registries, and signed Git tags across your entire build process.

## [Prerequisites](#prerequisites)

Build policies is currently an experimental feature. To try it out, you'll need:

* Buildx 0.31.0 or later - Check your version: `docker buildx version`
* BuildKit 0.27.0 or later - Verify with: `docker buildx inspect --bootstrap`

If you're using Docker Desktop, ensure you're on a version that includes these updates.

## [Build policies](#build-policies)

Buildx version 0.31.0 added support for build policies. Build policies are rules for securing your Docker build supply chain, and help protect against upstream compromises, malicious dependencies, and unauthorized modifications to your build inputs.

Build policies let you enforce extended verifications on inputs used to build your projects, such as:

* Docker images must use digest references (not tags alone)
* Images must have provenance attestations and cosign signatures
* Git tags are signed by maintainers with a PGP public key
* All remote artifacts must use HTTPS and include a checksum for verification

Build policies are defined in a declarative policy language, called Rego, created for the [Open Policy Agent (OPA)](https://www.openpolicyagent.org/). The following example shows a minimal build policy in Rego.

Dockerfile.rego

```rego
package docker

default allow := false

# Allow any local inputs for this build
# For example: a local build context, or a local Dockerfile
allow if input.local

# Allow images, but only if they have provenance attestations
allow if {
    input.image.hasProvenance
}

decision := {"allow": allow}
```

If the Dockerfile associated with this policy references an image with no provenance attestation in a `FROM` instruction, the policy would be violated and the build would fail.

## [How policies work](#how-policies-work)

When you run `docker buildx build`, Buildx:

1. Resolves all build inputs (images, Git repos, HTTP downloads)
2. Looks for a policy file matching your Dockerfile name (e.g., `Dockerfile.rego`)
3. Evaluates each input against the policy before the build starts
4. Allows the build to proceed only if all inputs pass the policy

Policies are written in Rego (Open Policy Agent's policy language). You don't need to be a Rego expert - the [Introduction](https://docs.docker.com/build/policies/intro/) tutorial teaches you everything needed.

Policy files live alongside your Dockerfile:

```text
project/
├── Dockerfile
├── Dockerfile.rego
└── src/
```

No additional configuration is needed - Buildx automatically finds and loads the policy when you build.

## [Use cases](#use-cases)

Build policies help you enforce security and compliance requirements on your Docker builds. Common scenarios where policies provide value:

### [Enforce base image standards](#enforce-base-image-standards)

Require all production Dockerfiles to use specific, approved base images with digest references. Prevent developers from using arbitrary images that haven't been vetted by your security team.

### [Validate third-party dependencies](#validate-third-party-dependencies)

When your build downloads files, libraries, or tools from the internet, verify they come from trusted sources and match expected checksums or signatures. This protects against supply chain attacks where an upstream dependency is compromised.

### [Ensure signed releases](#ensure-signed-releases)

Require that all dependencies have valid signatures from trusted parties.

* Check GPG signatures for Git repositories you clone in your builds
* Verify provenance attestation signatures with Sigstore

### [Meet compliance requirements](#meet-compliance-requirements)

Some regulatory frameworks require evidence that you validate your build inputs. Build policies give you an auditable, declarative way to demonstrate you're checking dependencies against security standards.

### [Separate development and production rules](#separate-development-and-production-rules)

Apply stricter validation for production builds while allowing more flexibility during development. The same policy file can contain conditional rules based on build context or target.

## [Get started](#get-started)

Ready to start writing policies? The [Introduction](https://docs.docker.com/build/policies/intro/) tutorial walks you through creating your first policy and teaches the Rego basics you need.

For practical usage guidance, see [Using build policies](https://docs.docker.com/build/policies/usage/).

For practical examples you can copy and adapt, see the [Example policies](https://docs.docker.com/build/policies/examples/) library.

----
url: https://docs.docker.com/reference/cli/docker/network/prune/
----

# docker network prune

***

| Description | Remove all unused networks       |
| ----------- | -------------------------------- |
| Usage       | `docker network prune [OPTIONS]` |

## [Description](#description)

Remove all unused networks. Unused networks are those which are not referenced by any containers.

## [Options](#options)

| Option                | Default | Description                                      |
| --------------------- | ------- | ------------------------------------------------ |
| [`--filter`](#filter) |         | Provide filter values (e.g. `until=<timestamp>`) |
| `-f, --force`         |         | Do not prompt for confirmation                   |

## [Examples](#examples)

```console
$ docker network prune

WARNING! This will remove all custom networks not used by at least one container.
Are you sure you want to continue? [y/N] y
Deleted Networks:
n1
n2
```

### [Filtering (--filter)](#filter)

The filtering flag (`--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).

When multiple filters are provided, they are combined as follows:

* Multiple filters with **different keys** are combined using AND logic. A network must satisfy all filter conditions to be pruned.
* Multiple filters with the **same key** are combined using OR logic. A network is pruned if it matches any of the values for that key.

For example, `--filter "label=foo" --filter "until=24h"` prunes networks that have the `foo` label **and** were created more than 24 hours ago. Conversely, `--filter "label=foo" --filter "label=bar"` prunes networks that have **either** the `foo` **or** `bar` label.

The currently supported filters are:

* until (`<timestamp>`) - only remove networks created before given timestamp
* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove networks with (or without, in case `label!=...` is used) the specified labels.

The `until` filter can be Unix timestamps, date formatted timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local timezone on the daemon will be used if you do not provide either a `Z` or a `+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds\[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long.

The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`), which removes networks with the specified labels. The other format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes networks without the specified labels.

The following removes networks created more than 5 minutes ago. Note that system networks such as `bridge`, `host`, and `none` will never be pruned:

```console
$ docker network ls

NETWORK ID          NAME                DRIVER              SCOPE
7430df902d7a        bridge              bridge              local
ea92373fd499        foo-1-day-ago       bridge              local
ab53663ed3c7        foo-1-min-ago       bridge              local
97b91972bc3b        host                host                local
f949d337b1f5        none                null                local

$ docker network prune --force --filter until=5m

Deleted Networks:
foo-1-day-ago

$ docker network ls

NETWORK ID          NAME                DRIVER              SCOPE
7430df902d7a        bridge              bridge              local
ab53663ed3c7        foo-1-min-ago       bridge              local
97b91972bc3b        host                host                local
f949d337b1f5        none                null                local
```

----
url: https://docs.docker.com/reference/cli/docker/container/unpause/
----

# docker container unpause

***

| Description                                                               | Unpause all processes within one or more containers |
| ------------------------------------------------------------------------- | --------------------------------------------------- |
| Usage                                                                     | `docker container unpause CONTAINER [CONTAINER...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker unpause`                                    |

## [Description](#description)

The `docker unpause` command un-suspends all processes in the specified containers. On Linux, it does this using the freezer cgroup.

See the [freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) for further details.

## [Examples](#examples)

```console
$ docker unpause my_container
my_container
```

----
url: https://docs.docker.com/ai/gordon/concepts/capabilities/
----

# Gordon's capabilities

***

Table of contents

***

Requires: Docker Desktop [4.74.0](https://docs.docker.com/desktop/release-notes/#4740) or later

Gordon combines multiple capabilities to handle Docker workflows. This page explains what Gordon can do and the tools it uses.

## [Core capabilities](#core-capabilities)

Gordon uses five capabilities to take action on your behalf:

* Specialized sub-agents for specific Docker tasks
* Shell access to run commands
* Filesystem access to read and write files
* Knowledge base of Docker documentation and best practices
* Web access to fetch external resources

## [Internal architecture](#internal-architecture)

Gordon uses a primary agent that handles most tasks, with a specialized sub-agent for specific workflows:

* **Main agent**: Handles all Docker operations, software development, containerization, and general development tasks
* **DHI migration sub-agent**: Specialized handler for migrating Dockerfiles to Docker Hardened Images

The main agent handles:

* Creating Docker assets (Dockerfile, compose.yaml, .dockerignore)
* Optimizing Dockerfiles to reduce image size and improve build performance
* Running Docker commands (ps, logs, exec, build, compose)
* Debugging container issues and analyzing configurations
* Writing and reviewing code across multiple programming languages
* General development questions and tasks

When you request DHI migration, Gordon automatically delegates to the DHI migration sub-agent.

## [Shell access](#shell-access)

Gordon executes shell commands in your environment after you approve them. This includes Docker CLI commands, system utilities, and application-specific tools.

Example commands Gordon might run:

```console
$ docker ps
$ docker logs container-name
$ docker exec -it container-name bash
$ grep "error" app.log
```

Commands run with your user permissions. Gordon cannot access `sudo` unless you've explicitly granted it.

## [Filesystem access](#filesystem-access)

Gordon reads and writes files on your system. It can analyze Dockerfiles, read configuration files, scan directories, and parse logs without approval. Writing files requires your approval.

The working directory sets the default context for file operations, but Gordon can access files outside this directory when needed.

## [Knowledge base](#knowledge-base)

Gordon uses retrieval-augmented generation to access Docker documentation, best practices, troubleshooting procedures, and security recommendations. This lets Gordon answer questions accurately, explain errors, and suggest solutions that follow Docker's guidelines.

## [Web access](#web-access)

Gordon fetches external web resources to look up error messages, package versions, and framework documentation. This helps when debugging issues that require context outside Docker's own documentation.

Gordon cannot access authenticated or private resources, and external requests are rate-limited.

## [Working with other tools](#working-with-other-tools)

Gordon complements general-purpose AI coding assistants by focusing on Docker workflows. Use tools like Cursor or GitHub Copilot for application code and refactoring, and use Gordon for containerization, deployment configuration, and Docker operations. They work well together.

----
url: https://docs.docker.com/reference/cli/docker/buildx/history/import/
----

# docker buildx history import

***

| Description | Import build records into Docker Desktop   |
| ----------- | ------------------------------------------ |
| Usage       | `docker buildx history import [OPTIONS] -` |

## [Description](#description)

Import a build record from a `.dockerbuild` archive into Docker Desktop. This lets you view, inspect, and analyze builds created in other environments or CI pipelines.

## [Options](#options)

| Option                | Default | Description             |
| --------------------- | ------- | ----------------------- |
| [`-f, --file`](#file) |         | Import from a file path |

## [Examples](#examples)

### [Import a `.dockerbuild` archive from standard input](#import-a-dockerbuild-archive-from-standard-input)

```console
docker buildx history import < mybuild.dockerbuild
```

### [Import a build archive from a file (--file)](#file)

```console
docker buildx history import --file ./artifacts/backend-build.dockerbuild
```

### [Open a build manually](#open-a-build-manually)

By default, the `import` command automatically opens the imported build in Docker Desktop. You don't need to run `open` unless you're opening a specific build or re-opening it later.

If you've imported multiple builds, you can open one manually:

```console
docker buildx history open ci-build
```

----
url: https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/
----

# Set, use, and manage variables in a Compose file with interpolation

***

Table of contents

***

A Compose file can use variables to offer more flexibility. If you want to quickly switch between image tags to test multiple versions, or want to adjust a volume source to your local environment, you don't need to edit the Compose file each time, you can just set variables that insert values into your Compose file at runtime.

Interpolation can also be used to insert values into your Compose file at runtime, which is then used to pass variables into your container's environment

Below is a simple example:

```console
$ cat .env
TAG=v1.5
$ cat compose.yaml
services:
  web:
    image: "webapp:${TAG}"
```

When you run `docker compose up`, the `web` service defined in the Compose file [interpolates](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) in the image `webapp:v1.5` which was set in the `.env` file. You can verify this with the [config command](/reference/cli/docker/compose/config/), which prints your resolved application config to the terminal:

```console
$ docker compose config
services:
  web:
    image: 'webapp:v1.5'
```

## [Interpolation syntax](#interpolation-syntax)

Interpolation is applied for unquoted and double-quoted values. Both braced (`${VAR}`) and unbraced (`$VAR`) expressions are supported.

For more information, see [Interpolation](https://docs.docker.com/reference/compose-file/interpolation/) in the Compose Specification.

## [Ways to set variables with interpolation](#ways-to-set-variables-with-interpolation)

Docker Compose can interpolate variables into your Compose file from multiple sources.

Note that when the same variable is declared by multiple sources, precedence applies:

1. Variables from your shell environment
2. If `--env-file` is not set, variables set by an `.env` file in local working directory (`PWD`)
3. Variables from a file set by `--env-file` or an `.env` file in project directory

You can check variables and values used by Compose to interpolate the Compose model by running `docker compose config --environment`.

### [`.env` file](#env-file)

An `.env` file in Docker Compose is a text file used to define variables that should be made available for interpolation when running `docker compose up`. This file typically contains key-value pairs of variables, and it lets you centralize and manage configuration in one place. The `.env` file is useful if you have multiple variables you need to store.

The `.env` file is the default method for setting variables. The `.env` file should be placed at the root of the project directory next to your `compose.yaml` file. For more information on formatting an environment file, see [Syntax for environment files](#env-file-syntax).

Basic example:

```console
$ cat .env
## define COMPOSE_DEBUG based on DEV_MODE, defaults to false
COMPOSE_DEBUG=${DEV_MODE:-false}

$ cat compose.yaml 
  services:
    webapp:
      image: my-webapp-image
      environment:
        - DEBUG=${COMPOSE_DEBUG}

$ DEV_MODE=true docker compose config
services:
  webapp:
    environment:
      DEBUG: "true"
```

#### [Additional information](#additional-information)

* If you define a variable in your `.env` file, you can reference it directly in your `compose.yaml` with the [`environment` attribute](https://docs.docker.com/reference/compose-file/services/#environment). For example, if your `.env` file contains the environment variable `DEBUG=1` and your `compose.yaml` file looks like this:

  ```yaml
   services:
     webapp:
       image: my-webapp-image
       environment:
         - DEBUG=${DEBUG}
  ```

  Docker Compose replaces `${DEBUG}` with the value from the `.env` file

  > Important
  >
  > Be aware of [Environment variables precedence](https://docs.docker.com/compose/how-tos/environment-variables/envvars-precedence/) when using variables in an `.env` file that as environment variables in your container's environment.

* You can place your `.env` file in a location other than the root of your project's directory, and then use the [`--env-file` option in the CLI](#substitute-with---env-file) so Compose can navigate to it.

* Your `.env` file can be overridden by another `.env` if it is [substituted with `--env-file`](#substitute-with---env-file).

> Important
>
> Substitution from `.env` files is a Docker Compose CLI feature.
>
> It is not supported by Swarm when running `docker stack deploy`.

#### [`.env` file syntax](#env-file-syntax)

The following syntax rules apply to environment files:

* Lines beginning with `#` are processed as comments and ignored.

* Blank lines are ignored.

* Unquoted and double-quoted (`"`) values have interpolation applied.

* Single-quoted values can span multiple lines. Example:

  ```yaml
  KEY='SOME
  VALUE'
  ```

  If you then run `docker compose config`, you'll see:

  ```yaml
  environment:
    KEY: |-
      SOME
      VALUE
  ```

### [Substitute with `--env-file`](#substitute-with---env-file)

You can set default values for multiple environment variables, in an `.env` file and then pass the file as an argument in the CLI.

The advantage of this method is that you can store the file anywhere and name it appropriately, for example, This file path is relative to the current working directory where the Docker Compose command is executed. Passing the file path is done using the `--env-file` option:

```console
$ docker compose --env-file ./config/.env.dev up
```

#### [Additional information](#additional-information-1)

* This method is useful if you want to temporarily override an `.env` file that is already referenced in your `compose.yaml` file. For example you may have different `.env` files for production ( `.env.prod`) and testing (`.env.test`). In the following example, there are two environment files, `.env` and `.env.dev`. Both have different values set for `TAG`.

  ```console
  $ cat .env
  TAG=v1.5
  $ cat ./config/.env.dev
  TAG=v1.6
  $ cat compose.yaml
  services:
    web:
      image: "webapp:${TAG}"
  ```

  If the `--env-file` is not used in the command line, the `.env` file is loaded by default:

  ```console
  $ docker compose config
  services:
    web:
      image: 'webapp:v1.5'
  ```

  Passing the `--env-file` argument overrides the default file path:

  ```console
  $ docker compose --env-file ./config/.env.dev config
  services:
    web:
      image: 'webapp:v1.6'
  ```

  When an invalid file path is being passed as an `--env-file` argument, Compose returns an error:

  ```console
  $ docker compose --env-file ./doesnotexist/.env.dev  config
  ERROR: Couldn't find env file: /home/user/./doesnotexist/.env.dev
  ```

* You can use multiple `--env-file` options to specify multiple environment files, and Docker Compose reads them in order. Later files can override variables from earlier files.
  ```console
  $ docker compose --env-file .env --env-file .env.override up
  ```

* You can override specific environment variables from the command line when starting containers.
  ```console
  $ docker compose --env-file .env.dev up -e DATABASE_URL=mysql://new_user:new_password@new_db:3306/new_database
  ```

### [local `.env` file versus \<project directory> `.env` file](#local-env-file-versus-project-directory-env-file)

An `.env` file can also be used to declare [pre-defined environment variables](https://docs.docker.com/compose/how-tos/environment-variables/envvars/) used to control Compose behavior and files to be loaded.

When executed without an explicit `--env-file` flag, Compose searches for an `.env` file in your working directory ([PWD](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-PWD)) and loads values both for self-configuration and interpolation. If the values in this file define the `COMPOSE_FILE` pre-defined variable, which results in a project directory being set to another folder, Compose will load a second `.env` file, if present. This second `.env` file has a lower precedence.

This mechanism makes it possible to invoke an existing Compose project with a custom set of variables as overrides, without the need to pass environment variables by the command line.

```console
$ cat .env
COMPOSE_FILE=../compose.yaml
POSTGRES_VERSION=9.3

$ cat ../compose.yaml 
services:
  db:
    image: "postgres:${POSTGRES_VERSION}"
$ cat ../.env
POSTGRES_VERSION=9.2

$ docker compose config
services:
  db:
    image: "postgres:9.3"
```

### [Substitute from the shell](#substitute-from-the-shell)

You can use existing environment variables from your host machine or from the shell environment where you execute `docker compose` commands. This lets you dynamically inject values into your Docker Compose configuration at runtime. For example, suppose the shell contains `POSTGRES_VERSION=9.3` and you supply the following configuration:

```yaml
db:
  image: "postgres:${POSTGRES_VERSION}"
```

When you run `docker compose up` with this configuration, Compose looks for the `POSTGRES_VERSION` environment variable in the shell and substitutes its value in. For this example, Compose resolves the image to `postgres:9.3` before running the configuration.

If an environment variable is not set, Compose substitutes with an empty string. In the previous example, if `POSTGRES_VERSION` is not set, the value for the image option is `postgres:`.

> Note
>
> `postgres:` is not a valid image reference. Docker expects either a reference without a tag, like `postgres` which defaults to the latest image, or with a tag such as `postgres:15`.

----
url: https://docs.docker.com/engine/cli/otel/
----

# OpenTelemetry for the Docker CLI

***

Table of contents

***

Requires: Docker Engine [26.1.0](https://docs.docker.com/engine/release-notes/26.1/#2610) and later

The Docker CLI supports [OpenTelemetry](https://opentelemetry.io/docs/) instrumentation for emitting metrics about command invocations. This is disabled by default. You can configure the CLI to start emitting metrics to the endpoint that you specify. This allows you to capture information about your `docker` command invocations for more insight into your Docker usage.

Exporting metrics is opt-in, and you control where data is being sent by specifying the destination address of the metrics collector.

## [What is OpenTelemetry?](#what-is-opentelemetry)

OpenTelemetry, or OTel for short, is an open observability framework for creating and managing telemetry data, such as traces, metrics, and logs. OpenTelemetry is vendor- and tool-agnostic, meaning that it can be used with a broad variety of Observability backends.

Support for OpenTelemetry instrumentation in the Docker CLI means that the CLI can emit information about events that take place, using the protocols and conventions defined in the Open Telemetry specification.

## [How it works](#how-it-works)

The Docker CLI doesn't emit telemetry data by default. Only if you've set an environment variable on your system will Docker CLI attempt to emit OpenTelemetry metrics, to the endpoint that you specify.

```bash
DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint>
```

The variable specifies the endpoint of an OpenTelemetry collector, where telemetry data about `docker` CLI invocation should be sent. To capture the data, you'll need an OpenTelemetry collector listening on that endpoint.

The purpose of a collector is to receive the telemetry data, process it, and exports it to a backend. The backend is where the telemetry data gets stored. You can choose from a number of different backends, such as Prometheus or InfluxDB.

Some backends provide tools for visualizing the metrics directly. Alternatively, you can also run a dedicated frontend with support for generating more useful graphs, such as Grafana.

## [Setup](#setup)

To get started capturing telemetry data for the Docker CLI, you'll need to:

* Set the `DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT` environment variable to point to an OpenTelemetry collector endpoint
* Run an OpenTelemetry collector that receives the signals from CLI command invocations
* Run a backend for storing the data received from the collector

The following Docker Compose file bootstraps a set of services to get started with OpenTelemetry. It includes an OpenTelemetry collector that the CLI can send metrics to, and a Prometheus backend that scrapes the metrics off the collector.

compose.yaml

```yaml
name: cli-otel
services:
  prometheus:
    image: prom/prometheus
    command:
      - "--config.file=/etc/prometheus/prom.yml"
    ports:
      # Publish the Prometheus frontend on localhost:9091
      - 9091:9090
    restart: always
    volumes:
      # Store Prometheus data in a volume:
      - prom_data:/prometheus
      # Mount the prom.yml config file
      - ./prom.yml:/etc/prometheus/prom.yml
  otelcol:
    image: otel/opentelemetry-collector
    restart: always
    depends_on:
      - prometheus
    ports:
      - 4317:4317
    volumes:
      # Mount the otelcol.yml config file
      - ./otelcol.yml:/etc/otelcol/config.yaml

volumes:
  prom_data:
```

This service assumes that the following two configuration files exist alongside `compose.yaml`:

* otelcol.yml

  ```yaml
  # Receive signals over gRPC and HTTP
  receivers:
    otlp:
      protocols:
        grpc:
        http:

  # Establish an endpoint for Prometheus to scrape from
  exporters:
    prometheus:
      endpoint: "0.0.0.0:8889"

  service:
    pipelines:
      metrics:
        receivers: [otlp]
        exporters: [prometheus]
  ```

* prom.yml

  ```yaml
  # Configure Prometheus to scrape the OpenTelemetry collector endpoint
  scrape_configs:
    - job_name: "otel-collector"
      scrape_interval: 1s
      static_configs:
        - targets: ["otelcol:8889"]
  ```

With these files in place:

1. Start the Docker Compose services:

   ```console
   $ docker compose up
   ```

2. Configure Docker CLI to export telemetry to the OpenTelemetry collector.

   ```console
   $ export DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
   ```

3. Run a `docker` command to trigger the CLI into sending a metric signal to the OpenTelemetry collector.

   ```console
   $ docker version
   ```

4. To view telemetry metrics created by the CLI, open the Prometheus expression browser by going to <http://localhost:9091/graph>.

5. In the **Query** field, enter `command_time_milliseconds_total`, and execute the query to see the telemetry data.

## [Available metrics](#available-metrics)

Docker CLI exports a single metric, `command.time`, which measures the execution duration of a command in milliseconds. This metric has the following attributes:

* `command.name`: the name of the command
* `command.status.code`: the exit code of the command
* `command.stderr.isatty`: true if stderr is attached to a TTY
* `command.stdin.isatty`: true if stdin is attached to a TTY
* `command.stdout.isatty`: true if stdout is attached to a TTY

----
url: https://docs.docker.com/extensions/extensions-sdk/design/design-principles/
----

# Docker design principles

***

Table of contents

***

## [Provide actionable guidance](#provide-actionable-guidance)

We anticipate needs and provide simple explanations with clear actions so people are never lost and always know what to do next. Recommendations lead users to functionality that enhances the experience and extends their knowledge.

## [Create value through confidence](#create-value-through-confidence)

People from all levels of experience should feel they know how to use our product. Experiences are familiar, unified, and easy to use so all users feel like experts.

## [Infuse productivity with delight](#infuse-productivity-with-delight)

We seek out moments of purposeful delight that elevate rather than distract, making work easier and more gratifying. Simple tasks are automated and users are left with more time for innovation.

## [Build trust through transparency](#build-trust-through-transparency)

We always provide clarity on what is happening and why. No amount of detail is withheld; the right information is shown at the right time and is always accessible.

## [Scale with intention](#scale-with-intention)

Our products focus on inclusive growth and are continuously useful and adapt to match changing individual needs. We support all levels of expertise by meeting users where they are with conscious personalization.

## [What's next?](#whats-next)

* Take a look at our [UI styling guidelines](https://docs.docker.com/extensions/extensions-sdk/design/).

----
url: https://docs.docker.com/extensions/extensions-sdk/build/minimal-frontend-extension/
----

# Create a simple extension

***

Table of contents

***

To start creating your extension, you first need a directory with files which range from the extension’s source code to the required extension-specific files. This page provides information on how to set up a minimal frontend extension based on plain HTML.

Before you start, make sure you have installed the latest version of [Docker Desktop](https://docs.docker.com/desktop/release-notes/).

> Tip
>
> If you want to start a codebase for your new extension, our [Quickstart guide](https://docs.docker.com/extensions/extensions-sdk/quickstart/) and `docker extension init <my-extension>` provides a better base for your extension.

## [Extension folder structure](#extension-folder-structure)

In the `minimal-frontend` [sample folder](https://github.com/docker/extensions-sdk/tree/main/samples), you can find a ready-to-go example that represents a UI Extension built on HTML. We will go through this code example in this tutorial.

Although you can start from an empty directory, it is highly recommended that you start from the template below and change it accordingly to suit your needs.

```bash
.
├── Dockerfile # (1)
├── metadata.json # (2)
└── ui # (3)
    └── index.html
```

1. Contains everything required to build the extension and run it in Docker Desktop.
2. A file that provides information about the extension such as the name, description, and version.
3. The source folder that contains all your HTML, CSS and JS files. There can also be other static assets such as logos and icons. For more information and guidelines on building the UI, see the [Design and UI styling section](https://docs.docker.com/extensions/extensions-sdk/design/design-guidelines/).

## [Create a Dockerfile](#create-a-dockerfile)

At a minimum, your Dockerfile needs:

* [Labels](https://docs.docker.com/extensions/extensions-sdk/extensions/labels/) which provide extra information about the extension, icon and screenshots.
* The source code which in this case is an `index.html` that sits within the `ui` folder.
* The `metadata.json` file.

```Dockerfile
# syntax=docker/dockerfile:1
FROM scratch

LABEL org.opencontainers.image.title="Minimal frontend" \
    org.opencontainers.image.description="A sample extension to show how easy it's to get started with Desktop Extensions." \
    org.opencontainers.image.vendor="Awesome Inc." \
    com.docker.desktop.extension.api.version="0.3.3" \
    com.docker.desktop.extension.icon="https://www.docker.com/wp-content/uploads/2022/03/Moby-logo.png"

COPY ui ./ui
COPY metadata.json .
```

## [Configure the metadata file](#configure-the-metadata-file)

A `metadata.json` file is required at the root of the image filesystem.

```json
{
  "ui": {
    "dashboard-tab": {
      "title": "Minimal frontend",
      "root": "/ui",
      "src": "index.html"
    }
  }
}
```

For more information on the `metadata.json`, see [Metadata](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/).

## [Build the extension and install it](#build-the-extension-and-install-it)

Now that you have configured the extension, you need to build the extension image that Docker Desktop will use to install it.

```console
$ docker build --tag=awesome-inc/my-extension:latest .
```

This built an image tagged `awesome-inc/my-extension:latest`, you can run `docker inspect awesome-inc/my-extension:latest` to see more details about it.

Finally, you can install the extension and see it appearing in the Docker Desktop Dashboard.

```console
$ docker extension install awesome-inc/my-extension:latest
```

## [Preview the extension](#preview-the-extension)

To preview the extension in Docker Desktop, close and open the Docker Desktop Dashboard once the installation is complete.

The left-hand menu displays a new tab with the name of your extension.

## [What's next?](#whats-next)

* Build a more [advanced frontend](https://docs.docker.com/extensions/extensions-sdk/build/frontend-extension-tutorial/) extension.
* Learn how to [test and debug](https://docs.docker.com/extensions/extensions-sdk/dev/test-debug/) your extension.
* Learn how to [setup CI for your extension](https://docs.docker.com/extensions/extensions-sdk/dev/continuous-integration/).
* Learn more about extensions [architecture](https://docs.docker.com/extensions/extensions-sdk/architecture/).

----
url: https://docs.docker.com/docker-hub/settings/
----

# Settings

***

Table of contents

***

You can configure the following settings in Docker Hub:

* [Default privacy](#default-privacy): Settings for all repositories within each namespace
* [Notifications](#notifications): Personal settings for autobuild notifications

## [Default privacy](#default-privacy)

You can configure the following default privacy settings for all repositories in a namespace:

* [Disable creation of public repos](#disable-creation-of-public-repos): Prevent organization users from creating public repositories (organization namespaces only)
* [Configure default repository privacy](#configure-default-repository-privacy): Set the default repository privacy for new repositories

### [Disable creation of public repos](#disable-creation-of-public-repos)

Subscription: Business

For: Administrators

Organization owners and editors can prevent creating public repositories within organization namespaces. You cannot configure this setting for personal account namespaces.

> Note
>
> Enabling this feature does not affect existing public repositories. Any public repositories that already exist will remain public. To make them private, you must change their visibility in the individual repository settings.

To configure the disable public repositories setting for an organization namespace:

1. Sign in to [Docker Hub](https://hub.docker.com).
2. Select **My Hub**.
3. Select your organization from the top-left account drop-down.
4. Select **Settings** > **Default privacy**.
5. Toggle **Disable public repositories** to your desired setting.
6. Select **Save**.

### [Configure default repository privacy](#configure-default-repository-privacy)

Use the default repository privacy setting to automatically set privacy for repositories created via `docker push` commands when the repository doesn't exist yet. In this case, Docker Hub automatically creates the repository with the default repository privacy for that namespace.

> Note
>
> You cannot configure the default repository privacy setting when **Disable public repositories** is enabled.

To configure the default repository privacy for a namespace:

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub**.

3. Select your organization or account from the top-left account drop-down.

4. Select **Settings** > **Default privacy**.

5. In **Default repository privacy**, select the desired default privacy setting:

   * **Public**: All new repositories appear in Docker Hub search results and can be pulled by everyone.
   * **Private**: All new repositories don't appear in Docker Hub search results and are only accessible to you and collaborators. In addition, if the repository is created in an organization's namespace, then the repository is accessible to those with applicable roles or permissions.

6. Select **Save**.

## [Notifications](#notifications)

You can send notifications to your email for all your repositories using autobuilds.

### [Configure autobuild notifications](#configure-autobuild-notifications)

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub**.

3. Select your personal account from the top-left account drop-down.

4. Select **Settings** > **Notifications**.

5. Select the notifications to receive by email:

   * **Off**: No notifications.
   * **Only failures**: Only notifications about failed builds.
   * **Everything**: Notifications for successful and failed builds.

6. Select **Save**.

----
url: https://docs.docker.com/reference/cli/docker/buildx/imagetools/
----

# docker buildx imagetools

***

| Description | Commands to work on images in registry |
| ----------- | -------------------------------------- |
| Usage       | `docker buildx imagetools`             |

## [Description](#description)

The `imagetools` commands contains subcommands for working with manifest lists in container registries. These commands are useful for inspecting manifests to check multi-platform configuration and attestations.

## [Examples](#examples)

### [Override the configured builder instance (--builder)](#builder)

Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

## [Subcommands](#subcommands)

| Command                                                                                                       | Description                               |
| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| [`docker buildx imagetools create`](https://docs.docker.com/reference/cli/docker/buildx/imagetools/create/)   | Create a new image based on source images |
| [`docker buildx imagetools inspect`](https://docs.docker.com/reference/cli/docker/buildx/imagetools/inspect/) | Show details of an image in the registry  |

----
url: https://docs.docker.com/guides/docker-scout/why/
----

# Why Docker Scout?

***

***

Organizations face significant challenges from data breaches, including financial losses, operational disruptions, and long-term damage to brand reputation and customer trust. Docker Scout addresses critical problems such as identifying insecure container images, preventing security breaches, and reducing the risk of operational downtime due to vulnerabilities.

Docker Scout provides several benefits:

* Secure and trusted content
* A system of record for your Software Development Lifecycle (SDLC)
* Continuous security posture improvement

Docker Scout offers automated vulnerability detection and remediation, helping organizations identify and fix security issues in container images early in the development process. It also integrates with popular development tools like Docker Desktop and GitHub Actions, providing seamless security management and compliance checks within existing workflows.

[Docker Scout demo »](https://docs.docker.com/guides/docker-scout/demo/)

----
url: https://docs.docker.com/guides/frameworks/laravel/common-questions/
----

# Common Questions on Using Laravel with Docker

***

Table of contents

***

## [1. Why should I use Docker Compose for Laravel?](#1-why-should-i-use-docker-compose-for-laravel)

Docker Compose is a powerful tool for managing multi-container environments, particularly in development due to its simplicity. With Docker Compose, you can define and connect all necessary services for Laravel, such as PHP, Nginx, and databases, in a single configuration (`compose.*.yaml`). This setup ensures consistency across development, testing, and production environments, streamlining onboarding and reducing discrepancies between local and server setups.

While Docker Compose is a great choice for development, tools like **Docker Swarm** or **Kubernetes** offer advanced scaling and orchestration features, which may be beneficial for complex production deployments.

## [2. How do I debug my Laravel application with Docker Compose?](#2-how-do-i-debug-my-laravel-application-with-docker-compose)

To debug your Laravel application in a Docker environment, use **Xdebug**. In the development setup, Xdebug is installed in the `php-fpm` container to enable debugging. Ensure Xdebug is enabled in your `compose.dev.yaml` file by setting the environment variable `XDEBUG_ENABLED=true` and configuring your IDE (e.g., Visual Studio Code or PHPStorm) to connect to the remote container for debugging.

## [3. Can I use Docker Compose with databases other than PostgreSQL?](#3-can-i-use-docker-compose-with-databases-other-than-postgresql)

Yes, Docker Compose supports various database services for Laravel. While PostgreSQL is used in the examples, you can easily substitute **MySQL**, **MariaDB**, or even **SQLite**. Update the `compose.*.yaml` file to specify the required Docker image and adjust your `.env` file to reflect the new database configuration.

## [4. How can I persist data in development and production?](#4-how-can-i-persist-data-in-development-and-production)

In both development and production, Docker volumes are used to persist data. For instance, in the `compose.*.yaml` file, the `postgres-data-*` volume stores PostgreSQL data, ensuring that data is retained even if the container restarts. You can also define named volumes for other services where data persistence is essential.

## [5. What is the difference between development and production Docker configurations?](#5-what-is-the-difference-between-development-and-production-docker-configurations)

In a development environment, Docker configurations include tools that streamline coding and debugging, such as Xdebug for debugging, and volume mounts to enable real-time code updates without requiring image rebuilds.

In production, the configuration is optimized for performance, security, and efficiency. This setup uses multi-stage builds to keep the image lightweight and includes only essential tools, packages, and libraries.

It’s recommended to use `alpine`-based images in production for smaller image sizes, enhancing deployment speed and security.

Additionally, consider using [Docker Scout](https://docs.docker.com/scout/) to detect and analyze vulnerabilities, especially in production environments.

For additional information about using Docker Compose in production, see [this guide](/compose/how-tos/production/).

----
url: https://docs.docker.com/guides/go-prometheus-monitoring/develop/
----

# Developing your application

***

Table of contents

***

In the last section, you saw how using Docker Compose, you can connect your services together. In this section, you will learn how to develop the Golang application with Docker. You will also see how to use Docker Compose Watch to rebuild the image whenever you make changes to the code. Lastly, you will test the application and visualize the metrics in Grafana using Prometheus as the data source.

## [Developing the application](#developing-the-application)

Now, if you make any changes to your Golang application locally, it needs to reflect in the container, right? To do that, one approach is use the `--build` flag in Docker Compose after making changes in the code. This will rebuild all the services which have the `build` instruction in the `compose.yml` file, in your case, the `api` service (Golang application).

```console
docker compose up --build
```

But, this is not the best approach. This is not efficient. Every time you make a change in the code, you need to rebuild manually. This is not is not a good flow for development.

The better approach is to use Docker Compose Watch. In the `compose.yml` file, under the service `api`, you have added the `develop` section. So, it's more like a hot reloading. Whenever you make changes to code (defined in `path`), it will rebuild the image (or restart depending on the action). This is how you can use it:

|                                                                     |                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ```
20
``` | ```yaml
services:
  api:
    container_name: go-api
    build:
      context: .
      dockerfile: Dockerfile
    image: go-api:latest
    ports:
      - 8000:8000
    networks:
      - go-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 5
    develop:
      watch:
        - path: .
          action: rebuild
``` |

Once you have added the `develop` section in the `compose.yml` file, you can use the following command to start the development server:

```console
$ docker compose watch
```

Now, if you modify your `main.go` or any other file in the project, the `api` service will be rebuilt automatically. You will see the following output in the terminal:

```bash
Rebuilding service(s) ["api"] after changes were detected...
[+] Building 8.1s (15/15) FINISHED                                                                                                        docker:desktop-linux
 => [api internal] load build definition from Dockerfile                                                                                                  0.0s
 => => transferring dockerfile: 704B                                                                                                                      0.0s
 => [api internal] load metadata for docker.io/library/alpine:3.17                                                                                        1.1s
  .                             
 => => exporting manifest list sha256:89ebc86fd51e27c1da440dc20858ff55fe42211a1930c2d51bbdce09f430c7f1                                                    0.0s
 => => naming to docker.io/library/go-api:latest                                                                                                          0.0s
 => => unpacking to docker.io/library/go-api:latest                                                                                                       0.0s
 => [api] resolving provenance for metadata file                                                                                                          0.0s
service(s) ["api"] successfully built
```

## [Testing the application](#testing-the-application)

Now that you have your application running, head over to the Grafana dashboard to visualize the metrics you are registering. Open your browser and navigate to `http://localhost:3000`. You will be greeted with the Grafana login page. The login credentials are the ones provided in Compose file.

Once you are logged in, you can create a new dashboard. While creating dashboard you will notice that is default data source is `Prometheus`. This is because you have already configured the data source in the `grafana.yml` file.

You can use different panels to visualize the metrics. This guide doesn't go into details of Grafana. You can refer to the [Grafana documentation](https://grafana.com/docs/grafana/latest/) for more information. There is a Bar Gauge panel to visualize the total number of requests from different endpoints. You used the `api_http_request_total` and `api_http_request_error_total` metrics to get the data.

You created this panel to visualize the total number of requests from different endpoints to compare the successful and failed requests. For all the good requests, the bar will be green, and for all the failed requests, the bar will be red. Plus it will also show the from which endpoint the request is coming, either it's a successful request or a failed request. If you want to use this panel, you can import the `dashboard.json` file from the repository you cloned.

## [Summary](#summary)

You've come to the end of this guide. You learned how to develop the Golang application with Docker. You also saw how to use Docker Compose Watch to rebuild the image whenever you make changes to the code. Lastly, you tested the application and visualized the metrics in Grafana using Prometheus as the data source.

----
url: https://docs.docker.com/extensions/extensions-sdk/design/design-guidelines/
----

# Design guidelines for Docker extensions

***

Table of contents

***

At Docker, we aim to build tools that integrate into a user's existing workflows rather than requiring them to adopt new ones. We strongly recommend that you follow these guidelines when creating extensions. We review and approve your Marketplace publication based on these requirements.

Here is a simple checklist to go through when creating your extension:

* Is it easy to get started?
* Is it easy to use?
* Is it easy to get help when needed?

## [Create a consistent experience with Docker Desktop](#create-a-consistent-experience-with-docker-desktop)

Use the [Docker Material UI Theme](https://www.npmjs.com/package/@docker/docker-mui-theme) and the [Docker Extensions Styleguide](https://www.figma.com/file/U7pLWfEf6IQKUHLhdateBI/Docker-Design-Guidelines?node-id=1%3A28771) to ensure that your extension feels like it is part of Docker Desktop to create a seamless experience for users.

* Ensure the extension has both a light and dark theme. Using the components and styles as per the Docker style guide ensures that your extension meets the [level AA accessibility standard.](https://www.w3.org/WAI/WCAG2AA-Conformance).

* Ensure that your extension icon is visible both in light and dark mode.

* Ensure that the navigational behavior is consistent with the rest of Docker Desktop. Add a header to set the context for the extension.

* Avoid embedding terminal windows. The advantage we have with Docker Desktop over the CLI is that we have the opportunity to provide rich information to users. Make use of this interface as much as possible.

## [Build features natively](#build-features-natively)

* In order not to disrupt the flow of users, avoid scenarios where the user has to navigate outside Docker Desktop, to the CLI or a webpage for example, in order to carry out certain functionalities. Instead, build features that are native to Docker Desktop.

## [Break down complicated user flows](#break-down-complicated-user-flows)

* If a flow is too complicated or the concept is abstract, break down the flow into multiple steps with one simple call-to-action in each step. This helps when onboarding novice users to your extension

* Where there are multiple call-to-actions, ensure you use the primary (filled button style) and secondary buttons (outline button style) to convey the importance of each action.

## [Onboarding new users](#onboarding-new-users)

When creating your extension, ensure that first time users of the extension and your product can understand its value-add and adopt it easily. Ensure you include contextual help within the extension.

* Ensure that all necessary information is added to the extensions Marketplace as well as the extensions detail page. This should include:

  * Screenshots of the extension. Note that the recommended size for screenshots is 2400x1600 pixels.
  * A detailed description that covers what the purpose of the extension is, who would find it useful and how it works.
  * Link to necessary resources such as documentation.

* If your extension has particularly complex functionality, add a demo or video to the start page. This helps onboard a first time user quickly.

## [What's next?](#whats-next)

* Explore our [design principles](https://docs.docker.com/extensions/extensions-sdk/design/design-principles/).
* Take a look at our [UI styling guidelines](https://docs.docker.com/extensions/extensions-sdk/design/).
* Learn how to [publish your extension](https://docs.docker.com/extensions/extensions-sdk/extensions/).

----
url: https://docs.docker.com/scout/how-tos/view-create-sboms/
----

# Docker Scout SBOMs

***

Table of contents

***

[Image analysis](https://docs.docker.com/scout/explore/analysis/) uses image SBOMs to understand what packages and versions an image contains. Docker Scout uses SBOM attestations if available on the image (recommended). If no SBOM attestation is available, Docker Scout creates one by indexing the image contents.

## [View from CLI](#view-from-cli)

To view the contents of the SBOM that Docker Scout generates, you can use the `docker scout sbom` command.

```console
$ docker scout sbom [IMAGE]
```

By default, this prints the SBOM in a JSON format to stdout. The default JSON format produced by `docker scout sbom` isn't SPDX-JSON. To output SPDX, use the `--format spdx` flag:

```console
$ docker scout sbom --format spdx [IMAGE]
```

To generate a human-readable list, use the `--format list` flag:

```console
$ docker scout sbom --format list alpine

           Name             Version    Type
───────────────────────────────────────────────
  alpine-baselayout       3.4.3-r1     apk
  alpine-baselayout-data  3.4.3-r1     apk
  alpine-keys             2.4-r1       apk
  apk-tools               2.14.0-r2    apk
  busybox                 1.36.1-r2    apk
  busybox-binsh           1.36.1-r2    apk
  ca-certificates         20230506-r0  apk
  ca-certificates-bundle  20230506-r0  apk
  libc-dev                0.7.2-r5     apk
  libc-utils              0.7.2-r5     apk
  libcrypto3              3.1.2-r0     apk
  libssl3                 3.1.2-r0     apk
  musl                    1.2.4-r1     apk
  musl-utils              1.2.4-r1     apk
  openssl                 3.1.2-r0     apk
  pax-utils               1.3.7-r1     apk
  scanelf                 1.3.7-r1     apk
  ssl_client              1.36.1-r2    apk
  zlib                    1.2.13-r1    apk
```

For more information about the `docker scout sbom` command, refer to the [CLI reference](/reference/cli/docker/scout/sbom/).

## [Attach as build attestation](#attest)

You can generate the SBOM and attach it to the image at build-time as an [attestation](https://docs.docker.com/build/metadata/attestations/). BuildKit provides a default SBOM generator which is different from what Docker Scout uses. You can configure BuildKit to use the Docker Scout SBOM generator using the `--attest` flag for the `docker build` command. The Docker Scout SBOM indexer provides richer results and ensures better compatibility with the Docker Scout image analysis.

```console
$ docker build --tag <org>/<image> \
  --attest type=sbom,generator=docker/scout-sbom-indexer:latest \
  --push .
```

To build images with SBOM attestations, you must use either the [containerd image store](https://docs.docker.com/desktop/features/containerd/) feature, or use a `docker-container` builder together with the `--push` flag to push the image (with attestations) directly to a registry. The classic image store doesn't support manifest lists or image indices, which is required for adding attestations to an image.

## [Extract to file](#extract-to-file)

The command for extracting the SBOM of an image to an SPDX JSON file is different depending on whether the image has been pushed to a registry or if it's a local image.

### [Remote image](#remote-image)

To extract the SBOM of an image and save it to a file, you can use the `docker buildx imagetools inspect` command. This command only works for images in a registry.

```console
$ docker buildx imagetools inspect <image> --format "{{ json .SBOM }}" > sbom.spdx.json
```

### [Local image](#local-image)

To extract the SPDX file for a local image, build the image with the `local` exporter and use the `scout-sbom-indexer` SBOM generator plugin.

The following command saves the SBOM to a file at `build/sbom.spdx.json`.

```console
$ docker build --attest type=sbom,generator=docker/scout-sbom-indexer:latest \
  --output build .
```

----
url: https://docs.docker.com/compose/bridge/customize/
----

# Customize Compose Bridge

***

Table of contents

***

Requires: Docker Desktop 4.43.0 and later

You can customize how Compose Bridge converts your Docker Compose files into platform-specific formats.

This page explains how Compose Bridge uses templating to generate Kubernetes manifests and how you can customize these templates for your specific requirements and needs, or how you can build your own transformation.

## [How it works](#how-it-works)

Compose bridge uses transformations to let you convert a Compose model into another form.

A transformation is packaged as a Docker image that receives the fully-resolved Compose model as `/in/compose.yaml` and can produce any target format file under `/out`.

Compose Bridge includes a default Kubernetes transformation using Go templates, which you can customize by replacing or extending templates.

### [Template syntax](#template-syntax)

Compose Bridge makes use of templates to transform a Compose configuration file into Kubernetes manifests. Templates are plain text files that use the [Go templating syntax](https://pkg.go.dev/text/template). This enables the insertion of logic and data, making the templates dynamic and adaptable according to the Compose model.

When a template is executed, it must produce a YAML file which is the standard format for Kubernetes manifests. Multiple files can be generated as long as they are separated by `---`

Each YAML output file begins with custom header notation, for example:

```yaml
#! manifest.yaml
```

In the following example, a template iterates over services defined in a `compose.yaml` file. For each service, a dedicated Kubernetes manifest file is generated, named according to the service and containing specified configurations.

```yaml
{{ range $name, $service := .services }}
---
#! {{ $name }}-manifest.yaml
# Generated code, do not edit
key: value
## ...
{{ end }}
```

### [Input model](#input-model)

You can generate the input model by running `docker compose config`.

This canonical YAML output serves as the input for Compose Bridge transformations. Within the templates, data from the `compose.yaml` is accessed using dot notation, allowing you to navigate through nested data structures. For example, to access the deployment mode of a service, you would use `service.deploy.mode`:

```yaml
# iterate over a yaml sequence
{{ range $name, $service := .services }}
 # access a nested attribute using dot notation
 {{ if eq $service.deploy.mode "global" }}
kind: DaemonSet
 {{ end }}
{{ end }}
```

You can check the [Compose Specification JSON schema](https://github.com/compose-spec/compose-go/blob/main/schema/compose-spec.json) for a full overview of the Compose model. This schema outlines all possible configurations and their data types in the Compose model.

### [Helper functions](#helper-functions)

As part of the Go templating syntax, Compose Bridge offers a set of YAML helper functions designed to manipulate data within the templates efficiently:

| Function    | Description                                                                                                                      |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `seconds`   | Converts a [duration](https://docs.docker.com/reference/compose-file/extension/#specifying-durations) into an integer (seconds). |
| `uppercase` | Converts a string to uppercase.                                                                                                  |
| `title`     | Capitalizes the first letter of each word.                                                                                       |
| `safe`      | Converts a string into a safe identifier (replaces non-lowercase characters with `-`).                                           |
| `truncate`  | Removes the first N elements from a list.                                                                                        |
| `join`      | Joins list elements into a single string with a separator.                                                                       |
| `base64`    | Encodes a string as base64 (used for Kubernetes secrets).                                                                        |
| `map`       | Maps values using `“value -> newValue”` syntax.                                                                                  |
| `indent`    | Indents string content by N spaces.                                                                                              |
| `helmValue` | Outputs a Helm-style template value.                                                                                             |

In the following example, the template checks if a healthcheck interval is specified for a service, applies the `seconds` function to convert this interval into seconds and assigns the value to the `periodSeconds` attribute.

```yaml
{{ if $service.healthcheck.interval }}
            periodSeconds: {{ $service.healthcheck.interval | seconds }}{{ end }}
{{ end }}
```

## [Customize the default templates](#customize-the-default-templates)

As Kubernetes is a versatile platform, there are many ways to map Compose concepts into Kubernetes resource definitions. Compose Bridge lets you customize the transformation to match your own infrastructure decisions and preferences, with varying level of flexibility and effort.

### [Modify the default templates](#modify-the-default-templates)

You can extract templates used by the default transformation `docker/compose-bridge-kubernetes`:

```console
$ docker compose bridge transformations create --from docker/compose-bridge-kubernetes my-template
```

The templates are extracted into a directory named after your template name, in this case `my-template`. It includes:

* A Dockerfile that lets you create your own image to distribute your template
* A directory containing the templating files

Edit, [add](#add-your-own-templates), or remove templates as needed.

You can then use the generated Dockerfile to package your changes into a new transformation image, which you can then use with Compose Bridge:

```console
$ docker build --tag mycompany/transform --push .
```

Use your transformation as a replacement:

```console
$ docker compose bridge convert --transformations mycompany/transform 
```

#### [Model Runner templates](#model-runner-templates)

The default transformation also includes templates for applications that use LLMs:

* `model-runner-deployment.tmpl`: Generates the Kubernetes deployment for Docker Model Runner. Customize it to change replica counts, image tags, resource requests and limits, GPU scheduling settings, tolerations, or additional environment variables.
* `model-runner-service.tmpl`: Builds the service that exposes Docker Model Runner. Update it to switch between `ClusterIP`, `NodePort`, or `LoadBalancer` types, adjust ports, or add annotations for ingress and service meshes.
* `model-runner-pvc.tmpl`: Defines the persistent volume claim used to store downloaded models. Edit it to set storage size, storage class, access modes, or volume annotations required by your storage provider.
* `/overlays/model-runner/kustomization.yaml`: Kustomize overlay applied when you deploy Model Runner to a standalone Kubernetes cluster. Extend it to add patches for labels and annotations, attach `NetworkPolicies`, or include extra manifests.
* `/overlays/desktop/deployment.tmpl`: Desktop-specific deployment template that keeps the in-cluster Model Runner scaled down and points workloads to the host endpoint. Adjust it if you change the Desktop endpoint or want to deploy Model Runner on Desktop instead of relying on the host service.

Common customization scenarios:

* Enable GPU support by adding vendor-specific resource requests, limits, and node selectors in `model-runner-deployment.tmpl`.
* Increase or tune storage for model artifacts by editing `model-runner-pvc.tmpl` to set the desired size, storage class, or access mode.
* Expose Model Runner outside the cluster by switching the service type in `model-runner-service.tmpl` or adding ingress annotations in the model-runner overlay.
* Align cluster policies by adding labels, annotations, or NetworkPolicies through `/overlays/model-runner/kustomization.yaml`.

For more details, see [Use Model Runner](https://docs.docker.com/compose/bridge/use-model-runner/).

### [Add your own templates](#add-your-own-templates)

For resources that are not managed by Compose Bridge's default transformation, you can build your own templates.

The `compose.yaml` model may not offer all the configuration attributes required to populate the target manifest. If this is the case, you can then rely on Compose custom extensions to better describe the application, and offer an agnostic transformation.

For example, if you add `x-virtual-host` metadata to service definitions in the `compose.yaml` file, you can use the following custom attribute to produce Ingress rules:

```yaml
{{ $project := .name }}
#! {{ $name }}-ingress.yaml
# Generated code, do not edit
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: virtual-host-ingress
  namespace: {{ $project }}
spec:
  rules:  
{{ range $name, $service := .services }}
{{ range index $service "x-virtual-host" }}
  - host: ${{ . }}
    http:
      paths:
      - path: "/"
        backend:
          service:
            name: ${{ name }}
            port:
              number: 80  
{{ end }}
{{ end }}
```

Once packaged into a Docker image, you can use this custom template when transforming Compose models into Kubernetes in addition to other transformations:

```console
$ docker compose bridge convert \
    --transformation docker/compose-bridge-kubernetes \
    --transformation mycompany/transform 
```

### [Build your own transformation](#build-your-own-transformation)

While Compose Bridge templates make it easy to customize with minimal changes, you may want to make significant changes, or rely on an existing conversion tool.

A Compose Bridge transformation is a Docker image that is designed to get a Compose model from `/in/compose.yaml` and produce platform manifests under `/out`. This simple contract makes it easy to bundle an alternate transformation using [Kompose](https://kompose.io/):

```Dockerfile
FROM alpine

# Get kompose from github release page
RUN apk add --no-cache curl
ARG VERSION=1.32.0
RUN ARCH=$(uname -m | sed 's/armv7l/arm/g' | sed 's/aarch64/arm64/g' | sed 's/x86_64/amd64/g') && \
    curl -fsL \
    "https://github.com/kubernetes/kompose/releases/download/v${VERSION}/kompose-linux-${ARCH}" \
    -o /usr/bin/kompose
RUN chmod +x /usr/bin/kompose

CMD ["/usr/bin/kompose", "convert", "-f", "/in/compose.yaml", "--out", "/out"]
```

This Dockerfile bundles Kompose and defines the command to run this tool according to the Compose Bridge transformation contract.

----
url: https://docs.docker.com/reference/cli/docker/desktop/start/
----

# docker desktop start

***

| Description | Start Docker Desktop             |
| ----------- | -------------------------------- |
| Usage       | `docker desktop start [OPTIONS]` |

## [Options](#options)

| Option         | Default | Description                                                                                                                                |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `-d, --detach` |         | Do not synchronously wait for the requested operation to complete.                                                                         |
| `--timeout`    |         | Terminate the running command after the specified timeout with a non-zero exit code. A value of zero (the default) or -1 means no timeout. |

----
url: https://docs.docker.com/reference/cli/docker/image/history/
----

# docker image history

***

| Description                                                               | Show the history of an image           |
| ------------------------------------------------------------------------- | -------------------------------------- |
| Usage                                                                     | `docker image history [OPTIONS] IMAGE` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker history`                       |

## [Description](#description)

Show the history of an image

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-H, --human`             | `true`  | Print sizes and dates in human readable format                                                                                                                                                                                                                                                                                                                                         |
| `--no-trunc`              |         | Don't truncate output                                                                                                                                                                                                                                                                                                                                                                  |
| [`--platform`](#platform) |         | API 1.48+ Show history for the given platform. Formatted as `os[/arch[/variant]]` (e.g., `linux/amd64`)                                                                                                                                                                                                                                                                                |
| `-q, --quiet`             |         | Only show image IDs                                                                                                                                                                                                                                                                                                                                                                    |

## [Examples](#examples)

To see how the `docker:latest` image was built:

```console
$ docker history docker

IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
3e23a5875458        8 days ago          /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8            0 B
8578938dd170        8 days ago          /bin/sh -c dpkg-reconfigure locales &&    loc   1.245 MB
be51b77efb42        8 days ago          /bin/sh -c apt-get update && apt-get install    338.3 MB
4b137612be55        6 weeks ago         /bin/sh -c #(nop) ADD jessie.tar.xz in /        121 MB
750d58736b4b        6 weeks ago         /bin/sh -c #(nop) MAINTAINER Tianon Gravi <ad   0 B
511136ea3c5a        9 months ago                                                        0 B                 Imported from -
```

To see how the `docker:apache` image was added to a container's base image:

```console
$ docker history docker:scm
IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
2ac9d1098bf1        3 months ago        /bin/bash                                       241.4 MB            Added Apache to Fedora base image
88b42ffd1f7c        5 months ago        /bin/sh -c #(nop) ADD file:1fd8d7f9f6557cafc7   373.7 MB
c69cab00d6ef        5 months ago        /bin/sh -c #(nop) MAINTAINER Lokesh Mandvekar   0 B
511136ea3c5a        19 months ago                                                       0 B                 Imported from -
```

### [Format the output (--format)](#format)

The formatting option (`--format`) will pretty-prints history output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder     | Description                                                                                               |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| `.ID`           | Image ID                                                                                                  |
| `.CreatedSince` | Elapsed time since the image was created if `--human=true`, otherwise timestamp of when image was created |
| `.CreatedAt`    | Timestamp of when image was created                                                                       |
| `.CreatedBy`    | Command that was used to create the image                                                                 |
| `.Size`         | Image disk size                                                                                           |
| `.Comment`      | Comment for image                                                                                         |

When using the `--format` option, the `history` command either outputs the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `ID` and `CreatedSince` entries separated by a colon (`:`) for the `busybox` image:

```console
$ docker history --format "{{.ID}}: {{.CreatedSince}}" busybox

f6e427c148a7: 4 weeks ago
<missing>: 4 weeks ago
```

### [Show history for a specific platform (--platform)](#platform)

The `--platform` option allows you to specify which platform variant to show history for if multiple platforms are present. By default, `docker history` shows the history for the daemon's native platform or if not present, the first available platform.

If the local image store has multiple platform variants of an image, the `--platform` option selects which variant to show the history for. An error is produced if the given platform is not present in the local image cache.

The platform option takes the `os[/arch[/variant]]` format; for example, `linux/amd64` or `linux/arm64/v8`. Architecture and variant are optional, and if omitted falls back to the daemon's defaults.

The following example pulls the RISC-V variant of the `alpine:latest` image and shows its history.

```console
$ docker image pull --quiet --platform=linux/riscv64 alpine
docker.io/library/alpine:latest

$ docker image history --platform=linux/s390x alpine
IMAGE          CREATED       CREATED BY                                      SIZE      COMMENT
beefdbd8a1da   3 weeks ago   /bin/sh -c #(nop)  CMD ["/bin/sh"]              0B
<missing>      3 weeks ago   /bin/sh -c #(nop) ADD file:ba2637314e600db5a…   8.46MB
```

The following example attempts to show the history for a platform variant of `alpine:latest` that doesn't exist in the local image store, resulting in an error.

```console
$ docker image ls --tree
IMAGE                   ID             DISK USAGE   CONTENT SIZE   IN USE
alpine:latest           beefdbd8a1da       10.6MB         3.37MB
├─ linux/riscv64        80cde017a105       10.6MB         3.37MB
├─ linux/amd64          33735bd63cf8           0B             0B
├─ linux/arm/v6         50f635c8b04d           0B             0B
├─ linux/arm/v7         f2f82d424957           0B             0B
├─ linux/arm64/v8       9cee2b382fe2           0B             0B
├─ linux/386            b3e87f642f5c           0B             0B
├─ linux/ppc64le        c7a6800e3dc5           0B             0B
└─ linux/s390x          2b5b26e09ca2           0B             0B

$ docker image history --platform=linux/s390x alpine
Error response from daemon: image with reference alpine:latest was found but does not match the specified platform: wanted linux/s390x
```

----
url: https://docs.docker.com/reference/cli/docker/dhi/attestation/list/
----

# docker dhi attestation list

***

| Description | List attestations for a Docker Hardened Image |
| ----------- | --------------------------------------------- |
| Usage       | `docker dhi attestation list <image>`         |

## [Description](#description)

List all attestations attached to a Docker Hardened Image.

The image can be specified as:

* name:tag (e.g., nginx:1.27)
* namespace/name:tag (e.g., dhi/nginx:1.27)
* name\@sha256:digest (e.g., nginx\@sha256:abc123...)

When a tag is provided, the digest is resolved from the container registry. Use --platform to select a specific platform manifest when the image is a multi-platform index.

Attestations are retrieved via the OCI Referrers API from the Docker Scout referrer registry.

Examples:

# [List attestations for an image by tag](#list-attestations-for-an-image-by-tag)

docker dhi attestation list dhi/nginx:1.27

# [List attestations for a specific platform](#list-attestations-for-a-specific-platform)

docker dhi attestation list dhi/nginx:1.27 --platform linux/amd64

# [List attestations for an image by digest](#list-attestations-for-an-image-by-digest)

docker dhi attestation list dhi/nginx\@sha256:abc123...

# [Filter by predicate type](#filter-by-predicate-type)

docker dhi attestation list dhi/nginx:1.27 --predicate-type <https://spdx.dev/Document>

# [Filter by multiple predicate types](#filter-by-multiple-predicate-types)

docker dhi attestation list dhi/nginx:1.27 --predicate-type <https://spdx.dev/Document> --predicate-type <https://slsa.dev/provenance/v1>

# [Output in JSON format](#output-in-json-format)

docker dhi attestation list dhi/nginx:1.27 --json

## [Options](#options)

| Option             | Default | Description                                                                        |
| ------------------ | ------- | ---------------------------------------------------------------------------------- |
| `--json`           |         | Output in JSON format                                                              |
| `--platform`       |         | Platform to filter by (e.g., linux/amd64). Defaults to the Docker daemon platform  |
| `--predicate-type` |         | Filter by predicate type (can be specified multiple times)                         |

----
url: https://docs.docker.com/reference/samples/fastapi/
----

# FastAPI samples

| Name                                                                     | Description                   |
| ------------------------------------------------------------------------ | ----------------------------- |
| [FastAPI](https://github.com/docker/awesome-compose/tree/master/fastapi) | A sample FastAPI application. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/guides/java/develop/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Use containers for Java development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Work through the steps to containerize your application in [Containerize your app](https://docs.docker.com/guides/java/containerize/).

## [Overview](#overview)

In this section, you’ll walk through setting up a local development environment for the application you containerized in the previous section. This includes:

* Adding a local database and persisting data
* Creating a development container to connect a debugger
* Configuring Compose to automatically update your running Compose services as you edit and save your code

## [Add a local database and persist data](#add-a-local-database-and-persist-data)

You can use containers to set up local services, like a database. In this section, you'll update the `docker-compose.yaml` file to define a database service and a volume to persist data. Also, this particular application uses a system property to define the database type, so you'll need to update the `Dockerfile` to pass in the system property when starting the app.

In the cloned repository's directory, open the `docker-compose.yaml` file in an IDE or text editor. Your Compose file has an example database service, but it'll require a few changes for your unique app.

In the `docker-compose.yaml` file, you need to do the following:

* Uncomment all of the database instructions. You'll now use a database service instead of local storage for the data.
* Remove the top-level `secrets` element as well as the element inside the `db` service. This example uses the environment variable for the password rather than secrets.
* Remove the `user` element from the `db` service. This example specifies the user in the environment variable.
* Update the database environment variables. These are defined by the Postgres image. For more details, see the [Postgres Official Docker Image](https://hub.docker.com/_/postgres).
* Update the healthcheck test for the `db` service and specify the user. By default, the healthcheck uses the root user instead of the `petclinic` user you defined.
* Add the database URL as an environment variable in the `server` service. This overrides the default value defined in `spring-petclinic/src/main/resources/application-postgres.properties`.

The following is the updated `docker-compose.yaml` file. All comments have been removed.

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 8080:8080
    depends_on:
      db:
        condition: service_healthy
    environment:
      - POSTGRES_URL=jdbc:postgresql://db:5432/petclinic
  db:
    image: postgres:18
    restart: always
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=petclinic
      - POSTGRES_USER=petclinic
      - POSTGRES_PASSWORD=petclinic
    ports:
      - 5432:5432
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "petclinic"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
```

Open the `Dockerfile` in an IDE or text editor. In the `ENTRYPOINT` instruction, update the instruction to pass in the system property as specified in the `spring-petclinic/src/resources/db/postgres/petclinic_db_setup_postgres.txt` file.

```diff
- ENTRYPOINT [ "java", "org.springframework.boot.loader.launch.JarLauncher" ]
+ ENTRYPOINT [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ]
```

Save and close all the files.

Now, run the following `docker compose up` command to start your application.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:8080>. You should see a simple app for a pet clinic. Browse around the application. Navigate to **Veterinarians** and verify that the application is connected to the database by being able to list veterinarians.

In the terminal, press `ctrl`+`c` to stop the application.

## [Dockerfile for development](#dockerfile-for-development)

The Dockerfile you have now is great for a small, secure production image with only the components necessary to run the application. When developing, you may want a different image that has a different environment.

For example, in the development image you may want to set up the image to start the application so that you can connect a debugger to the running Java process.

Rather than managing multiple Dockerfiles, you can add a new stage. Your Dockerfile can then produce a final image which is ready for production as well as a development image.

Replace the contents of your Dockerfile with the following.

```dockerfile
# syntax=docker/dockerfile:1

FROM eclipse-temurin:21-jdk-jammy as deps
WORKDIR /build
COPY --chmod=0755 mvnw mvnw
COPY .mvn/ .mvn/
RUN --mount=type=bind,source=pom.xml,target=pom.xml \
    --mount=type=cache,target=/root/.m2 ./mvnw dependency:go-offline -DskipTests

FROM deps as package
WORKDIR /build
COPY ./src src/
RUN --mount=type=bind,source=pom.xml,target=pom.xml \
    --mount=type=cache,target=/root/.m2 \
    ./mvnw package -DskipTests && \
    mv target/$(./mvnw help:evaluate -Dexpression=project.artifactId -q -DforceStdout)-$(./mvnw help:evaluate -Dexpression=project.version -q -DforceStdout).jar target/app.jar

FROM package as extract
WORKDIR /build
RUN java -Djarmode=layertools -jar target/app.jar extract --destination target/extracted

FROM extract as development
WORKDIR /build
RUN cp -r /build/target/extracted/dependencies/. ./
RUN cp -r /build/target/extracted/spring-boot-loader/. ./
RUN cp -r /build/target/extracted/snapshot-dependencies/. ./
RUN cp -r /build/target/extracted/application/. ./
ENV JAVA_TOOL_OPTIONS -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000
CMD [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ]

FROM eclipse-temurin:21-jre-jammy AS final
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser
USER appuser
COPY --from=extract build/target/extracted/dependencies/ ./
COPY --from=extract build/target/extracted/spring-boot-loader/ ./
COPY --from=extract build/target/extracted/snapshot-dependencies/ ./
COPY --from=extract build/target/extracted/application/ ./
EXPOSE 8080
ENTRYPOINT [ "java", "-Dspring.profiles.active=postgres", "org.springframework.boot.loader.launch.JarLauncher" ]
```

Save and close the `Dockerfile`.

In the `Dockerfile` you added a new stage labeled `development` based on the `extract` stage. In this stage, you copy the extracted files to a common directory, then run a command to start the application. In the command, you expose port 8000 and declare the debug configuration for the JVM so that you can attach a debugger.

## [Use Compose to develop locally](#use-compose-to-develop-locally)

The current Compose file doesn't start your development container. To do that, you must update your Compose file to target the development stage. Also, update the port mapping of the server service to provide access for the debugger.

Open the `docker-compose.yaml` and add the following instructions into the file.

```yaml
services:
  server:
    build:
      context: .
      target: development
    ports:
      - 8080:8080
      - 8000:8000
    depends_on:
      db:
        condition: service_healthy
    environment:
      - POSTGRES_URL=jdbc:postgresql://db:5432/petclinic
  db:
    image: postgres:18
    restart: always
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=petclinic
      - POSTGRES_USER=petclinic
      - POSTGRES_PASSWORD=petclinic
    ports:
      - 5432:5432
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "petclinic"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
```

Now, start your application and to confirm that it's running.

```console
$ docker compose up --build
```

Finally, test your API endpoint. Run the following curl command:

```console
$ curl  --request GET \
  --url http://localhost:8080/vets \
  --header 'content-type: application/json'
```

You should receive the following response:

```json
{
  "vetList": [
    {
      "id": 1,
      "firstName": "James",
      "lastName": "Carter",
      "specialties": [],
      "nrOfSpecialties": 0,
      "new": false
    },
    {
      "id": 2,
      "firstName": "Helen",
      "lastName": "Leary",
      "specialties": [{ "id": 1, "name": "radiology", "new": false }],
      "nrOfSpecialties": 1,
      "new": false
    },
    {
      "id": 3,
      "firstName": "Linda",
      "lastName": "Douglas",
      "specialties": [
        { "id": 3, "name": "dentistry", "new": false },
        { "id": 2, "name": "surgery", "new": false }
      ],
      "nrOfSpecialties": 2,
      "new": false
    },
    {
      "id": 4,
      "firstName": "Rafael",
      "lastName": "Ortega",
      "specialties": [{ "id": 2, "name": "surgery", "new": false }],
      "nrOfSpecialties": 1,
      "new": false
    },
    {
      "id": 5,
      "firstName": "Henry",
      "lastName": "Stevens",
      "specialties": [{ "id": 1, "name": "radiology", "new": false }],
      "nrOfSpecialties": 1,
      "new": false
    },
    {
      "id": 6,
      "firstName": "Sharon",
      "lastName": "Jenkins",
      "specialties": [],
      "nrOfSpecialties": 0,
      "new": false
    }
  ]
}
```

## [Connect a Debugger](#connect-a-debugger)

You’ll use the debugger that comes with the IntelliJ IDEA. You can use the community version of this IDE. Open your project in IntelliJ IDEA, go to the **Run** menu, and then **Edit Configuration**. Add a new Remote JVM Debug configuration similar to the following:

Set a breakpoint.

Open `src/main/java/org/springframework/samples/petclinic/vet/VetController.java` and add a breakpoint inside the `showResourcesVetList` function.

To start your debug session, select the **Run** menu and then **Debug *NameOfYourConfiguration***.

You should now see the connection in the logs of your Compose application.

You can now call the server endpoint.

```console
$ curl --request GET --url http://localhost:8080/vets
```

You should have seen the code break on the marked line and now you are able to use the debugger just like you would normally. You can also inspect and watch variables, set conditional breakpoints, view stack traces and a do bunch of other stuff.

Press `ctrl+c` in the terminal to stop your application.

## [Automatically update services](#automatically-update-services)

Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

Open your `docker-compose.yaml` file in an IDE or text editor and then add the Compose Watch instructions. The following is the updated `docker-compose.yaml` file.

```yaml
services:
  server:
    build:
      context: .
      target: development
    ports:
      - 8080:8080
      - 8000:8000
    depends_on:
      db:
        condition: service_healthy
    environment:
      - POSTGRES_URL=jdbc:postgresql://db:5432/petclinic
    develop:
      watch:
        - action: rebuild
          path: .
  db:
    image: postgres:18
    restart: always
    volumes:
      - db-data:/var/lib/postgresql
    environment:
      - POSTGRES_DB=petclinic
      - POSTGRES_USER=petclinic
      - POSTGRES_PASSWORD=petclinic
    ports:
      - 5432:5432
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "petclinic"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
```

Run the following command to run your application with Compose Watch.

```console
$ docker compose watch
```

Open a web browser and view the application at <http://localhost:8080>. You should see the Spring Pet Clinic home page.

Any changes to the application's source files on your local machine will now be automatically reflected in the running container.

Open `spring-petclinic/src/main/resources/templates/fragments/layout.html` in an IDE or text editor and update the `Home` navigation string by adding an exclamation mark.

```diff
-   <li th:replace="~{::menuItem ('/','home','home page','home','Home')}">
+   <li th:replace="~{::menuItem ('/','home','home page','home','Home!')}">
```

Save the changes to `layout.html` and then you can continue developing while the container automatically rebuilds.

After the container is rebuilt and running, refresh <http://localhost:8080> and then verify that **Home!** now appears in the menu.

Press `ctrl+c` in the terminal to stop Compose Watch.

## [Summary](#summary)

In this section, you took a look at running a database locally and persisting the data. You also created a development image that contains the JDK and lets you attach a debugger. Finally, you set up your Compose file to expose the debugging port and configured Compose Watch to live reload your changes.

Related information:

* [Compose file reference](/reference/compose-file/)
* [Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/)
* [Dockerfile reference](/reference/dockerfile/)

## [Next steps](#next-steps)

In the next section, you’ll take a look at how to run unit tests in Docker.

[Run your Java tests »](https://docs.docker.com/guides/java/run-tests/)

----
url: https://docs.docker.com/guides/dotnet/deploy/
----

# Test your .NET deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Containerize a .NET application](https://docs.docker.com/guides/dotnet/containerize/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your `docker-dotnet-sample` directory, create a file named `docker-dotnet-kubernetes.yaml`. Open the file in an IDE or text editor and add the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the name of the repository that you created in [Configure CI/CD for your .NET application](https://docs.docker.com/guides/dotnet/configure-ci-cd/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    service: server
  name: server
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: server
  strategy: {}
  template:
    metadata:
      labels:
        service: server
    spec:
      initContainers:
        - name: wait-for-db
          image: busybox:1.28
          command:
            [
              "sh",
              "-c",
              'until nc -zv db 5432; do echo "waiting for db"; sleep 2; done;',
            ]
      containers:
        - image: DOCKER_USERNAME/REPO_NAME
          name: server
          imagePullPolicy: Always
          ports:
            - containerPort: 8080
              hostPort: 8080
              protocol: TCP
          resources: {}
      restartPolicy: Always
status: {}
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    service: db
  name: db
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: db
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        service: db
    spec:
      containers:
        - env:
            - name: POSTGRES_DB
              value: example
            - name: POSTGRES_PASSWORD
              value: example
          image: postgres:18
          name: db
          ports:
            - containerPort: 5432
              protocol: TCP
          resources: {}
      restartPolicy: Always
status: {}
---
apiVersion: v1
kind: Service
metadata:
  labels:
    service: server
  name: server
  namespace: default
spec:
  type: NodePort
  ports:
    - name: "8080"
      port: 8080
      targetPort: 8080
      nodePort: 30001
  selector:
    service: server
status:
  loadBalancer: {}
---
apiVersion: v1
kind: Service
metadata:
  labels:
    service: db
  name: db
  namespace: default
spec:
  ports:
    - name: "5432"
      port: 5432
      targetPort: 5432
  selector:
    service: db
status:
  loadBalancer: {}
```

In this Kubernetes YAML file, there are four objects, separated by the `---`. In addition to a Service and Deployment for the database, the other two objects are:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your .NET application](https://docs.docker.com/guides/dotnet/configure-ci-cd/).
* A NodePort service, which will route traffic from port 30001 on your host to port 8080 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to the `docker-dotnet-sample` directory and deploy your application to Kubernetes.

   ```console
   $ kubectl apply -f docker-dotnet-kubernetes.yaml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```shell
   deployment.apps/db created
   service/db created
   deployment.apps/server created
   service/server created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```shell
   NAME     READY   UP-TO-DATE   AVAILABLE   AGE
   db       1/1     1            1           76s
   server   1/1     1            1           76s
   ```

   This indicates all of the pods are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```shell
   NAME         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
   db           ClusterIP   10.96.156.90    <none>        5432/TCP         2m8s
   kubernetes   ClusterIP   10.96.0.1       <none>        443/TCP          164m
   server       NodePort    10.102.94.225   <none>        8080:30001/TCP   2m8s
   ```

   In addition to the default `kubernetes` service, you can see your `server` service and `db` service. The `server` service is accepting traffic on port 30001/TCP.

3. Open a browser and visit your app at `localhost:30001`. You should see your application.

4. Run the following command to tear down your application.

   ```console
   $ kubectl delete -f docker-dotnet-kubernetes.yaml
   ```

## [Summary](#summary)

In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine.

Related information:

* [Kubernetes documentation](https://kubernetes.io/docs/home/)
* [Deploy on Kubernetes with Docker Desktop](https://docs.docker.com/desktop/use-desktop/kubernetes/)
* [Swarm mode overview](https://docs.docker.com/engine/swarm/)

----
url: https://docs.docker.com/docker-hub/repos/manage/builds/migrate/
----

# Migrate from Autobuilds

***

Table of contents

***

> Warning
>
> Docker Hub Automated Builds is a deprecated feature. It will be fully retired on April 1, 2027.

This guide explains how to migrate your Docker Hub Autobuilds setup to Continuous Integration (CI) workflows, focusing on GitHub Actions and Bitbucket Pipelines as these are the built-in CI services for the two version control services supported via Autobuilds.

## [Step 1: Create access tokens](#step-1-create-access-tokens)

To grant your CI workflows the ability to pull and push images to and from Docker Hub, you first need to create access tokens:

* For a personal repository: Create a [Personal Access Token](https://docs.docker.com/security/access-tokens/) with **Read & Write** permissions.

* For an organization repository: Create an [Organization Access Token](https://docs.docker.com/enterprise/security/access-tokens/) with the following permissions:

  * **Read public repositories**
  * **Image Pull** on any private repositories that the build needs to pull from
  * **Image Push** on the repository that the built image will be pushed to

The same token can be used for all CI workflows under the account's namespace provided it has adequate permissions to all relevant Docker Hub repositories.

Store the token securely in a password manager or your CI/CD platform's secrets manager. Never commit tokens to source code repositories.

## [Step 2: Extract your Autobuilds configuration](#step-2-extract-your-autobuilds-configuration)

For each Docker Hub repository currently configured to use Autobuilds, you need to extract its configuration to set up your CI workflows to duplicate the existing functionality. The only way to extract the configuration is via the Docker Hub web interface.

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Navigate to your repository by going to **My Hub** > ***Your namespace*** > **Repositories** > ***Your Repository***.

3. Go to the **Builds** tab and select **Configure automated builds**.

   If there is no existing build configuration, then this repository is not configured for Autobuilds.

4. Note the following configuration details:

   * **Source Repository**: The GitHub or Bitbucket repository. The organization is the namespace and the repository is the repository name. This is where you need to add your workflow.

   * **Autotest**: If Autotest is enabled for Pull Requests (either internal only or internal and external), then extra steps are needed in your workflow to run the Autotest step.

   * **Repository Links**: Not supported and can be ignored. If chain builds are required, see the documentation for your CI service on how to chain builds together.

   * **Build Rules**: Specify the triggers, tags, and paths of your builds. Ignore any entry where **Autobuild** is toggled off.

   * **Build Environment Variables**: User-defined variables injected as environment variables into your build. You need to add these to your workflow. If the environment variables contain secrets, add them to your CI service's secrets manager. Then update your Dockerfile or build scripts to reference these secrets using your CI platform's syntax. See your CI service documentation on how to handle secrets.

### [Example configuration](#example-configuration)

The following image shows an example Autobuilds configuration.

Based on the pictured example, you would note the following items for this Autobuilds configuration:

* Source code repository: GitHub repository `docker/docker-rust-hello`
* Autotest: Disabled
* Build rule 1: Build and push the image with tag `latest` when a new commit to the `main` branch is detected. The Dockerfile is at `./Dockerfile` and the build context is the root of the cloned code.
* Build rule 2: Build and push the image with tag `v{\1}` when a new commit to a tag matching the regex `^v([0-9.]+)$` is detected. The Dockerfile is at `./Dockerfile` and the build context is the root of the cloned code.
* Environment variable: Key `ENV_KEY` with value `ENV_VALUE`

## [Step 3: Migrate to your CI/CD platform](#step-3-migrate-to-your-cicd-platform)

Select the tab that matches your source code repository hosting platform.

If your source code repository is hosted on GitHub, see the [Docker Autobuilds example repository](https://github.com/docker/autobuilds-actions).

All files except those under the `.github/workflows` directory are for example purposes only.

The repository's readme details how to migrate from Autobuilds to GitHub Actions using one of the two provided workflows:

* The `simple-build` workflow builds and pushes a Docker image to your Docker Hub repository.
* The `full-autobuilds` workflow contains all the steps commonly used within an Autobuilds run, including building, tagging, running Docker Compose tests, and running optional bash hook files.

### [Steps to migrate](#steps-to-migrate)

1. Follow the instructions in the [example repository readme](https://github.com/docker/autobuilds-actions) to configure a CI GitHub Action workflow in your GitHub repository.

2. The workflows contain comments on what each step does and where changes should be made. Important changes to make include:

   * Set the `DOCKER_REPOSITORY_NAME` environment variable to the full name of your Docker Hub repository
   * Set your image tagging policy
   * Set the workflow triggers

   Links to relevant documentation are provided in the readme and the workflow comments.

3. After you have completed migrating to GitHub Actions, delete the build configuration from your Docker Hub repository:

   1. Navigate to the repository's **Builds** tab.

   2. Select **Configure automated builds**.

   3. Select **Delete Build Configuration**.

If your source code repository is hosted on Bitbucket, see the [Docker Autobuilds Bitbucket example repository](https://bitbucket.org/docker-io/autobuilds-pipeline).

All files except the `bitbucket-pipelines.yml` file are for example purposes only.

The repository's readme details how to migrate from Autobuilds to Bitbucket Pipelines using the provided example `bitbucket-pipelines.yml` configuration file.

The pipeline example contains three separate pipelines:

* `branches/main`: Shows how to build, test, and push an image on changes to a specific branch
* `tags/*`: Shows how to build, test, and push an image on tag pushes, including tagging the image the same as the Git tag
* `pull-requests/*`: Shows how to build and test, but not push, an image from a pull request

### [Steps to migrate](#steps-to-migrate)

1. Follow the instructions in the [example repository readme](https://bitbucket.org/docker-io/autobuilds-pipeline) to configure a Bitbucket Pipeline in your Bitbucket repository.

2. Comments in the pipeline configuration explain what each part does and where changes need to be made. Important changes to make include:

   * Set the `DOCKER_REPOSITORY_NAME` environment variable to the full name of your Docker Hub repository
   * Set your image tagging policy (see where the `DOCKER_TAG` variable is set in each pipeline)
   * Set the pipeline triggers for branches, tags, and/or pull-requests

   Links to relevant documentation are provided in the readme and the workflow comments.

3. After you have completed migrating to Bitbucket Pipelines, delete the Build configuration from your Docker Hub repository:

   1. Navigate to the repository's **Builds** tab.

   2. Select **Configure automated builds**.

   3. Select **Delete Build Configuration**.

----
url: https://docs.docker.com/reference/cli/docker/desktop/enable/
----

# docker desktop enable

***

| Description | Enable a feature |
| ----------- | ---------------- |

## [Description](#description)

Enable or manage an individual feature

## [Subcommands](#subcommands)

| Command                                                                                                           | Description                         |
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| [`docker desktop enable model-runner`](https://docs.docker.com/reference/cli/docker/desktop/enable/model-runner/) | Manage Docker Model Runner settings |

----
url: https://docs.docker.com/scout/integrations/registry/acr/
----

# Integrate Docker Scout with Azure Container Registry

***

Table of contents

***

Integrating Docker Scout with Azure Container Registry (ACR) lets you view image insights for images hosted in ACR repositories. After integrating Docker Scout with ACR and activating Docker Scout for a repository, pushing an image to the repository automatically triggers image analysis. You can view image insights using the Docker Scout Dashboard, or the `docker scout` CLI commands.

## [How it works](#how-it-works)

To help you integrate your Azure Container Registry with Docker Scout, you can use a custom Azure Resource Manager (ARM) template that automatically creates the necessary infrastructure in Azure for you:

* An EventGrid Topic and Subscription for Image push and delete events.
* A read-only authorization token for the registry, used to list repositories, and ingest the images.

When the resources have been created in Azure, you can enable the integration for image repositories in the integrated ACR instance. Once you've enabled a repository, pushing new images triggers image analysis automatically. The analysis results appear in the Docker Scout Dashboard.

If you enable the integration on a repository that already contains images, Docker Scout pulls and analyzes the latest image version automatically.

### [ARM template](#arm-template)

The following table describes the configuration resources.

> Note
>
> Creating these resources incurs a small, recurring cost on the Azure account. The **Cost** column in the table represents an estimated monthly cost of the resources, when integrating an ACR registry that gets 100 images pushed per day.
>
> The Egress cost varies depending on usage, but it’s around $0.1 per GB, and the first 100 GB are free.

| Azure                   | Resource                                                                                   | Cost                                              |
| ----------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| Event Grid system topic | Subscribe to Azure Container Registry events (image push and image delete)                 | Free                                              |
| Event subscription      | Send Event Grid events to Scout via a Webhook subscription                                 | $0.60 for every 1M messages. First 100k for free. |
| Registry Token          | Read-only token used for Scout to list the repositories, and pull images from the registry | Free                                              |

The following JSON document shows the ARM template Docker Scout uses to create the Azure resources.

```json
{
   "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
   "contentVersion": "1.0.0.0",
   "parameters": {
      "DockerScoutWebhook": {
         "metadata": {
            "description": "EventGrid's subscription Webhook"
         },
         "type": "String"
      },
      "RegistryName": {
         "metadata": {
            "description": "Name of the registry to add Docker Scout"
         },
         "type": "String"
      },
      "systemTopics_dockerScoutRepository": {
         "defaultValue": "docker-scout-repository",
         "metadata": {
            "description": "EventGrid's topic name"
         },
         "type": "String"
      }
   },
   "resources": [
      {
         "apiVersion": "2023-06-01-preview",
         "identity": {
            "type": "None"
         },
         "location": "[resourceGroup().location]",
         "name": "[parameters('systemTopics_dockerScoutRepository')]",
         "properties": {
            "source": "[extensionResourceId(resourceGroup().Id , 'Microsoft.ContainerRegistry/Registries', parameters('RegistryName'))]",
            "topicType": "Microsoft.ContainerRegistry.Registries"
         },
         "type": "Microsoft.EventGrid/systemTopics"
      },
      {
         "apiVersion": "2023-06-01-preview",
         "dependsOn": [
            "[resourceId('Microsoft.EventGrid/systemTopics', parameters('systemTopics_dockerScoutRepository'))]"
         ],
         "name": "[concat(parameters('systemTopics_dockerScoutRepository'), '/image-change')]",
         "properties": {
            "destination": {
               "endpointType": "WebHook",
               "properties": {
                  "endpointUrl": "[parameters('DockerScoutWebhook')]",
                  "maxEventsPerBatch": 1,
                  "preferredBatchSizeInKilobytes": 64
               }
            },
            "eventDeliverySchema": "EventGridSchema",
            "filter": {
               "enableAdvancedFilteringOnArrays": true,
               "includedEventTypes": [
                  "Microsoft.ContainerRegistry.ImagePushed",
                  "Microsoft.ContainerRegistry.ImageDeleted"
               ]
            },
            "labels": [],
            "retryPolicy": {
               "eventTimeToLiveInMinutes": 1440,
               "maxDeliveryAttempts": 30
            }
         },
         "type": "Microsoft.EventGrid/systemTopics/eventSubscriptions"
      },
      {
         "apiVersion": "2023-01-01-preview",
         "name": "[concat(parameters('RegistryName'), '/docker-scout-readonly-token')]",
         "properties": {
            "credentials": {},
            "scopeMapId": "[resourceId('Microsoft.ContainerRegistry/registries/scopeMaps', parameters('RegistryName'), '_repositories_pull_metadata_read')]"
         },
         "type": "Microsoft.ContainerRegistry/registries/tokens"
      }
   ],
   "variables": {}
}
```

## [Integrate a registry](#integrate-a-registry)

1. Go to [ACR integration page](https://scout.docker.com/settings/integrations/azure/) on the Docker Scout Dashboard.

2. In the **How to integrate** section, enter the **Registry hostname** of the registry you want to integrate.

3. Select **Next**.

4. Select **Deploy to Azure** to open the template deployment wizard in Azure.

   You may be prompted to sign in to your Azure account if you're not already signed in.

5. In the template wizard, configure your deployment:

   * **Resource group**: enter the same resource group as you're using for the container registry. The Docker Scout resources must be deployed to the same resource group as the registry.

   * **Registry name**: the field is pre-filled with the subdomain of the registry hostname.

6. Select **Review + create**, and then **Create** to deploy the template.

7. Wait until the deployment is complete.

8. In the **Deployment details** section click on the newly created resource of the type **Container registry token**. Generate a new password for this token.

   Alternatively, use the search function in Azure to navigate to the **Container registry** resource that you're looking to integrate, and generate the new password for the created access token.

9. Copy the generated password and head back to the Docker Scout Dashboard to finalize the integration.

10. Paste the generated password into the **Registry token** field.

11. Select **Enable integration**.

After selecting **Enable integration**, Docker Scout performs a connection test to verify the integration. If the verification was successful, you're redirected to the Azure registry summary page, which shows you all your Azure integrations for the current organization.

Next, activate Docker Scout for the repositories that you want to analyze in [Repository settings](https://scout.docker.com/settings/repos/).

After activating repositories, images that you push are analyzed by Docker Scout. The analysis results appear in the Docker Scout Dashboard. If your repository already contains images, Docker Scout pulls and analyzes the latest image version automatically.

## [Remove an integration](#remove-an-integration)

> Important
>
> Removing the integration in the Docker Scout Dashboard doesn't automatically remove the resources created in Azure.

To remove an ACR integration:

1. Go to the [ACR integration page](https://scout.docker.com/settings/integrations/azure/) on the Docker Scout Dashboard.

2. Find the ACR integration that you want to remove, and select the **Remove** button.

3. In the dialog that opens, confirm by selecting **Remove**.

4. After removing the integration in the Docker Scout Dashboard, also remove the Azure resources related to the integration:

   * The `docker-scout-readonly-token` token for the container registry.
   * The `docker-scout-repository` Event Grid System Topic.

----
url: https://docs.docker.com/ai/sandboxes/security/
----

# Security model

***

Table of contents

***

Docker Sandboxes run AI agents in microVMs so they can execute code, install packages, and use tools without accessing your host system. Multiple isolation layers protect your host system.

## [Trust boundaries](#trust-boundaries)

The primary trust boundary is the microVM. The agent has full control inside the VM, including sudo access. The VM boundary prevents the agent from reaching anything on your host except what is explicitly shared.

What crosses the boundary into the VM:

* **Workspace directory:** mounted into the VM. The default direct mount is read-write — the agent edits your working tree in place. With [`--clone`](https://docs.docker.com/ai/sandboxes/usage/#clone-mode), your repository is mounted read-only and the agent works on a private clone.
* **Credentials:** the host-side proxy injects authentication headers into outbound HTTP requests. The raw credential values never enter the VM.
* **Network access:** HTTP and HTTPS requests to [allowed domains](https://docs.docker.com/ai/sandboxes/security/defaults/) are proxied through the host.

What crosses the boundary back to the host:

* **Workspace file changes:** visible on your host in real time with the default direct mount.
* **HTTP/HTTPS requests:** sent to allowed domains through the host proxy.

Everything else is blocked. The agent cannot access your host filesystem (outside the workspace), your host Docker daemon, your host network or localhost, other sandboxes, or any domain not in the allow list. Raw TCP, UDP, and ICMP are blocked at the network layer.

## [Isolation layers](#isolation-layers)

The sandbox security model has five layers. See [Isolation layers](https://docs.docker.com/ai/sandboxes/security/isolation/) for technical details on each.

* **Hypervisor isolation:** separate kernel per sandbox. No shared memory or processes with the host.
* **Network isolation:** all HTTP/HTTPS traffic proxied through the host. [Deny-by-default policy](https://docs.docker.com/ai/sandboxes/security/defaults/). Non-HTTP protocols blocked entirely.
* **Docker Engine isolation:** each sandbox has its own Docker Engine with no path to the host daemon.
* **Workspace isolation** (opt-in via `--clone`): the agent works on a private in-VM clone and your repository is mounted read-only. The default direct mode applies no workspace boundary — the agent edits your working tree in place.
* **Credential isolation:** API keys are injected into HTTP headers by the host-side proxy. Credential values never enter the VM.

## [What the agent can do inside the sandbox](#what-the-agent-can-do-inside-the-sandbox)

Inside the VM, the agent has full privileges: sudo access, package installation, a private Docker Engine, and read-write access to the workspace. Installed packages, Docker images, and other VM state persist across restarts. See [Default security posture](https://docs.docker.com/ai/sandboxes/security/defaults/) for the full breakdown of what is permitted and what is blocked.

## [What is not isolated by default](#what-is-not-isolated-by-default)

The sandbox isolates the agent from your host system, but the agent's actions can still affect you through the shared workspace and allowed network channels.

In direct mode, workspace changes are live on your host. With the default direct mount, the agent edits the same files you see on your host. This includes files that execute implicitly during normal development: Git hooks, CI configuration, IDE task configs, `Makefile`, `package.json` scripts, and similar build files. Review changes before running any modified code. Note that Git hooks live inside `.git/` and do not appear in `git diff` output — check them separately. See [Workspace isolation](https://docs.docker.com/ai/sandboxes/security/isolation/#workspace-isolation) for the full list and for the alternative clone-mode boundary.

The default allowed domains include broad wildcards. Some defaults like `*.googleapis.com` cover many services beyond AI APIs. Run `sbx policy ls` to see the full list of active rules, and remove entries you don't need. See [Default security posture](https://docs.docker.com/ai/sandboxes/security/defaults/).

## [Organization-wide control](#organization-wide-control)

On a single developer's machine, network and filesystem policies are configured locally with `sbx policy`. Admins can also centrally define those policies in the Docker Admin Console. When organization governance is active, the centrally defined rules apply uniformly across every sandbox in the organization and take precedence over local rules. Admins can optionally delegate specific rule types back to local control so developers can add additional allow rules.

See [Organization governance](https://docs.docker.com/ai/sandboxes/security/governance/) for details.

## [Learn more](#learn-more)

* [Isolation layers](https://docs.docker.com/ai/sandboxes/security/isolation/): how hypervisor, network, Docker, workspace, and credential isolation work
* [Default security posture](https://docs.docker.com/ai/sandboxes/security/defaults/): what a fresh sandbox permits and blocks
* [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/): how to provide and manage API keys
* [Policies](https://docs.docker.com/ai/sandboxes/security/policy/): how to customize network access rules
* [Organization governance](https://docs.docker.com/ai/sandboxes/security/governance/): centrally manage policies across an organization

----
url: https://docs.docker.com/engine/storage/drivers/btrfs-driver/
----

# BTRFS storage driver

***

Table of contents

***

> Important
>
> In most cases you should use the `overlay2` storage driver - it's not required to use the `btrfs` storage driver simply because your system uses Btrfs as its root filesystem.
>
> Btrfs driver has known issues. See [Moby issue #27653](https://github.com/moby/moby/issues/27653) for more information.

Btrfs is a copy-on-write filesystem that supports many advanced storage technologies, making it a good fit for Docker. Btrfs is included in the mainline Linux kernel.

Docker's `btrfs` storage driver leverages many Btrfs features for image and container management. Among these features are block-level operations, thin provisioning, copy-on-write snapshots, and ease of administration. You can combine multiple physical block devices into a single Btrfs filesystem.

This page refers to Docker's Btrfs storage driver as `btrfs` and the overall Btrfs Filesystem as Btrfs.

> Note
>
> The `btrfs` storage driver is only supported with Docker Engine CE on SLES, Ubuntu, and Debian systems.

## [Prerequisites](#prerequisites)

`btrfs` is supported if you meet the following prerequisites:

* `btrfs` is only recommended with Docker CE on Ubuntu or Debian systems.

* Changing the storage driver makes any containers you have already created inaccessible on the local system. Use `docker save` to save containers, and push existing images to Docker Hub or a private repository, so that you do not need to re-create them later.

* `btrfs` requires a dedicated block storage device such as a physical disk. This block device must be formatted for Btrfs and mounted into `/var/lib/docker/`. The configuration instructions below walk you through this procedure. By default, the SLES `/` filesystem is formatted with Btrfs, so for SLES, you do not need to use a separate block device, but you can choose to do so for performance reasons.

* `btrfs` support must exist in your kernel. To check this, run the following command:

  ```console
  $ grep btrfs /proc/filesystems

  btrfs
  ```

* To manage Btrfs filesystems at the level of the operating system, you need the `btrfs` command. If you don't have this command, install the `btrfsprogs` package (SLES) or `btrfs-tools` package (Ubuntu).

## [Configure Docker to use the btrfs storage driver](#configure-docker-to-use-the-btrfs-storage-driver)

This procedure is essentially identical on SLES and Ubuntu.

1. Stop Docker.

2. Copy the contents of `/var/lib/docker/` to a backup location, then empty the contents of `/var/lib/docker/`:

   ```console
   $ sudo cp -au /var/lib/docker /var/lib/docker.bk
   $ sudo rm -rf /var/lib/docker/*
   ```

3. Format your dedicated block device or devices as a Btrfs filesystem. This example assumes that you are using two block devices called `/dev/xvdf` and `/dev/xvdg`. Double-check the block device names because this is a destructive operation.

   ```console
   $ sudo mkfs.btrfs -f /dev/xvdf /dev/xvdg
   ```

   There are many more options for Btrfs, including striping and RAID. See the [Btrfs documentation](https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices).

4. Mount the new Btrfs filesystem on the `/var/lib/docker/` mount point. You can specify any of the block devices used to create the Btrfs filesystem.

   ```console
   $ sudo mount -t btrfs /dev/xvdf /var/lib/docker
   ```

   > Note
   >
   > Make the change permanent across reboots by adding an entry to `/etc/fstab`.

5. Copy the contents of `/var/lib/docker.bk` to `/var/lib/docker/`.

   ```console
   $ sudo cp -au /var/lib/docker.bk/* /var/lib/docker/
   ```

6. Configure Docker to use the `btrfs` storage driver. This is required even though `/var/lib/docker/` is now using a Btrfs filesystem. Edit or create the file `/etc/docker/daemon.json`. If it is a new file, add the following contents. If it is an existing file, add the key and value only, being careful to end the line with a comma if it isn't the final line before an ending curly bracket (`}`).

   ```json
   {
     "storage-driver": "btrfs"
   }
   ```

   See all storage options for each storage driver in the [daemon reference documentation](/reference/cli/dockerd/#options-per-storage-driver)

7. Start Docker. When it's running, verify that `btrfs` is being used as the storage driver.

   ```console
   $ docker info

   Containers: 0
    Running: 0
    Paused: 0
    Stopped: 0
   Images: 0
   Server Version: 17.03.1-ce
   Storage Driver: btrfs
    Build Version: Btrfs v4.4
    Library Version: 101
   <...>
   ```

8. When you are ready, remove the `/var/lib/docker.bk` directory.

## [Manage a Btrfs volume](#manage-a-btrfs-volume)

One of the benefits of Btrfs is the ease of managing Btrfs filesystems without the need to unmount the filesystem or restart Docker.

When space gets low, Btrfs automatically expands the volume in chunks of roughly 1 GB.

To add a block device to a Btrfs volume, use the `btrfs device add` and `btrfs filesystem balance` commands.

```console
$ sudo btrfs device add /dev/svdh /var/lib/docker

$ sudo btrfs filesystem balance /var/lib/docker
```

> Note
>
> While you can do these operations with Docker running, performance suffers. It might be best to plan an outage window to balance the Btrfs filesystem.

## [How the `btrfs` storage driver works](#how-the-btrfs-storage-driver-works)

The `btrfs` storage driver works differently from other storage drivers in that your entire `/var/lib/docker/` directory is stored on a Btrfs volume.

### [Image and container layers on-disk](#image-and-container-layers-on-disk)

Information about image layers and writable container layers is stored in `/var/lib/docker/btrfs/subvolumes/`. This subdirectory contains one directory per image or container layer, with the unified filesystem built from a layer plus all its parent layers. Subvolumes are natively copy-on-write and have space allocated to them on-demand from an underlying storage pool. They can also be nested and snapshotted. The diagram below shows 4 subvolumes. 'Subvolume 2' and 'Subvolume 3' are nested, whereas 'Subvolume 4' shows its own internal directory tree.

Only the base layer of an image is stored as a true subvolume. All the other layers are stored as snapshots, which only contain the differences introduced in that layer. You can create snapshots of snapshots as shown in the diagram below.

On disk, snapshots look and feel just like subvolumes, but in reality they are much smaller and more space-efficient. Copy-on-write is used to maximize storage efficiency and minimize layer size, and writes in the container's writable layer are managed at the block level. The following image shows a subvolume and its snapshot sharing data.

For maximum efficiency, when a container needs more space, it is allocated in chunks of roughly 1 GB in size.

Docker's `btrfs` storage driver stores every image layer and container in its own Btrfs subvolume or snapshot. The base layer of an image is stored as a subvolume whereas child image layers and containers are stored as snapshots. This is shown in the diagram below.

The high level process for creating images and containers on Docker hosts running the `btrfs` driver is as follows:

1. The image's base layer is stored in a Btrfs *subvolume* under `/var/lib/docker/btrfs/subvolumes`.

2. Subsequent image layers are stored as a Btrfs *snapshot* of the parent layer's subvolume or snapshot, but with the changes introduced by this layer. These differences are stored at the block level.

3. The container's writable layer is a Btrfs snapshot of the final image layer, with the differences introduced by the running container. These differences are stored at the block level.

## [How container reads and writes work with `btrfs`](#how-container-reads-and-writes-work-with-btrfs)

### [Reading files](#reading-files)

A container is a space-efficient snapshot of an image. Metadata in the snapshot points to the actual data blocks in the storage pool. This is the same as with a subvolume. Therefore, reads performed against a snapshot are essentially the same as reads performed against a subvolume.

### [Writing files](#writing-files)

As a general caution, writing and updating a large number of small files with Btrfs can result in slow performance.

Consider three scenarios where a container opens a file for write access with Btrfs.

#### [Writing new files](#writing-new-files)

Writing a new file to a container invokes an allocate-on-demand operation to allocate new data block to the container's snapshot. The file is then written to this new space. The allocate-on-demand operation is native to all writes with Btrfs and is the same as writing new data to a subvolume. As a result, writing new files to a container's snapshot operates at native Btrfs speeds.

#### [Modifying existing files](#modifying-existing-files)

Updating an existing file in a container is a copy-on-write operation (redirect-on-write is the Btrfs terminology). The original data is read from the layer where the file currently exists, and only the modified blocks are written into the container's writable layer. Next, the Btrfs driver updates the filesystem metadata in the snapshot to point to this new data. This behavior incurs minor overhead.

#### [Deleting files or directories](#deleting-files-or-directories)

If a container deletes a file or directory that exists in a lower layer, Btrfs masks the existence of the file or directory in the lower layer. If a container creates a file and then deletes it, this operation is performed in the Btrfs filesystem itself and the space is reclaimed.

## [Btrfs and Docker performance](#btrfs-and-docker-performance)

There are several factors that influence Docker's performance under the `btrfs` storage driver.

> Note
>
> Many of these factors are mitigated by using Docker volumes for write-heavy workloads, rather than relying on storing data in the container's writable layer. However, in the case of Btrfs, Docker volumes still suffer from these draw-backs unless `/var/lib/docker/volumes/` isn't backed by Btrfs.

### [Page caching](#page-caching)

Btrfs doesn't support page cache sharing. This means that each process accessing the same file copies the file into the Docker host's memory. As a result, the `btrfs` driver may not be the best choice for high-density use cases such as PaaS.

### [Small writes](#small-writes)

Containers performing lots of small writes (this usage pattern matches what happens when you start and stop many containers in a short period of time, as well) can lead to poor use of Btrfs chunks. This can prematurely fill the Btrfs filesystem and lead to out-of-space conditions on your Docker host. Use `btrfs filesys show` to closely monitor the amount of free space on your Btrfs device.

### [Sequential writes](#sequential-writes)

Btrfs uses a journaling technique when writing to disk. This can impact the performance of sequential writes, reducing performance by up to 50%.

### [Fragmentation](#fragmentation)

Fragmentation is a natural byproduct of copy-on-write filesystems like Btrfs. Many small random writes can compound this issue. Fragmentation can manifest as CPU spikes when using SSDs or head thrashing when using spinning disks. Either of these issues can harm performance.

If your Linux kernel version is 3.9 or higher, you can enable the `autodefrag` feature when mounting a Btrfs volume. Test this feature on your own workloads before deploying it into production, as some tests have shown a negative impact on performance.

### [SSD performance](#ssd-performance)

Btrfs includes native optimizations for SSD media. To enable these features, mount the Btrfs filesystem with the `-o ssd` mount option. These optimizations include enhanced SSD write performance by avoiding optimization such as seek optimizations that don't apply to solid-state media.

### [Balance Btrfs filesystems often](#balance-btrfs-filesystems-often)

Use operating system utilities such as a `cron` job to balance the Btrfs filesystem regularly, during non-peak hours. This reclaims unallocated blocks and helps to prevent the filesystem from filling up unnecessarily. You can't rebalance a totally full Btrfs filesystem unless you add additional physical block devices to the filesystem.

See the [Btrfs Wiki](https://btrfs.wiki.kernel.org/index.php/Balance_Filters#Balancing_to_fix_filesystem_full_errors).

### [Use fast storage](#use-fast-storage)

Solid-state drives (SSDs) provide faster reads and writes than spinning disks.

### [Use volumes for write-heavy workloads](#use-volumes-for-write-heavy-workloads)

Volumes provide the best and most predictable performance for write-heavy workloads. This is because they bypass the storage driver and don't incur any of the potential overheads introduced by thin provisioning and copy-on-write. Volumes have other benefits, such as allowing you to share data among containers and persisting even when no running container is using them.

## [Related Information](#related-information)

* [Volumes](https://docs.docker.com/engine/storage/volumes/)
* [Understand images, containers, and storage drivers](https://docs.docker.com/engine/storage/drivers/)
* [Select a storage driver](https://docs.docker.com/engine/storage/drivers/select-storage-driver/)

----
url: https://docs.docker.com/get-started/introduction/
----

# Introduction

Table of contents

***

Embark on a comprehensive learning path to understand Docker and containerization, beginning with foundational concepts and installation procedures. Progress through hands-on exercises that cover essential Docker commands, image creation, and container orchestration.

**Skill level** Beginner

**Time to complete** 15 minutes

**Prerequisites** None

## [About this series](#about-this-series)

In this guide series, you will gain hands-on experience with Docker, starting with installing and setting up Docker Desktop on your local machine. You will learn how to run your first container, understanding the basics of containerization and its benefits. This series guides you through building your first Docker image, providing insights into creating efficient and reusable images. Finally, you will explore how to publish your image on Docker Hub, enabling you to share your work with the broader community and leverage Docker's powerful ecosystem for collaborative development and deployment.

## [What you'll learn](#what-youll-learn)

* Set up Docker Desktop
* Run your first container
* Build your first image
* Publish your image on Docker Hub

## [Modules](#modules)

1. [Get Docker Desktop](https://docs.docker.com/get-started/introduction/get-docker-desktop/)

   This concept page will teach you download Docker Desktop and install it on Windows, Mac, and Linux

2. [Develop with containers](https://docs.docker.com/get-started/introduction/develop-with-containers/)

   This concept page will teach you how to develop with containers

3. [Build and push your first image](https://docs.docker.com/get-started/introduction/build-and-push-first-image/)

   This concept page will teach you how to build and push your first image

4. [What's next](https://docs.docker.com/get-started/introduction/whats-next/)

   Explore step-by-step guides to help you understand core Docker concepts, building images, and running containers.

----
url: https://docs.docker.com/build/bake/matrices/
----

# Matrix targets

***

Table of contents

***

A matrix strategy lets you fork a single target into multiple different variants, based on parameters that you specify. This works in a similar way to [Matrix strategies for GitHub Actions](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs). You can use this to reduce duplication in your Bake definition.

The matrix attribute is a map of parameter names to lists of values. Bake builds each possible combination of values as a separate target.

Each generated target must have a unique name. To specify how target names should resolve, use the name attribute.

The following example resolves the app target to `app-foo` and `app-bar`. It also uses the matrix value to define the [target build stage](/build/bake/reference/#targettarget).

docker-bake.hcl

```hcl
target "app" {
  name = "app-${tgt}"
  matrix = {
    tgt = ["foo", "bar"]
  }
  target = tgt
}
```

```console
$ docker buildx bake --print app
[+] Building 0.0s (0/0)
{
  "group": {
    "app": {
      "targets": [
        "app-foo",
        "app-bar"
      ]
    },
    "default": {
      "targets": [
        "app"
      ]
    }
  },
  "target": {
    "app-bar": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "target": "bar"
    },
    "app-foo": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "target": "foo"
    }
  }
}
```

## [Multiple axes](#multiple-axes)

You can specify multiple keys in your matrix to fork a target on multiple axes. When using multiple matrix keys, Bake builds every possible variant.

The following example builds four targets:

* `app-foo-1-0`
* `app-foo-2-0`
* `app-bar-1-0`
* `app-bar-2-0`

docker-bake.hcl

```hcl
target "app" {
  name = "app-${tgt}-${replace(version, ".", "-")}"
  matrix = {
    tgt = ["foo", "bar"]
    version = ["1.0", "2.0"]
  }
  target = tgt
  args = {
    VERSION = version
  }
}
```

## [Multiple values per matrix target](#multiple-values-per-matrix-target)

If you want to differentiate the matrix on more than just a single value, you can use maps as matrix values. Bake creates a target for each map, and you can access the nested values using dot notation.

The following example builds two targets:

* `app-foo-1-0`
* `app-bar-2-0`

docker-bake.hcl

```hcl
target "app" {
  name = "app-${item.tgt}-${replace(item.version, ".", "-")}"
  matrix = {
    item = [
      {
        tgt = "foo"
        version = "1.0"
      },
      {
        tgt = "bar"
        version = "2.0"
      }
    ]
  }
  target = item.tgt
  args = {
    VERSION = item.version
  }
}
```

----
url: https://docs.docker.com/reference/cli/docker/compose/export/
----

# docker compose export

***

| Description | Export a service container's filesystem as a tar archive |
| ----------- | -------------------------------------------------------- |
| Usage       | `docker compose export [OPTIONS] SERVICE`                |

## [Description](#description)

Export a service container's filesystem as a tar archive

## [Options](#options)

| Option         | Default | Description                                              |
| -------------- | ------- | -------------------------------------------------------- |
| `--index`      |         | index of the container if service has multiple replicas. |
| `-o, --output` |         | Write to a file, instead of STDOUT                       |

----
url: https://docs.docker.com/reference/cli/docker/dhi/mirror/
----

# docker dhi mirror

***

| Description | Mirror Docker Hardened Images to your organization |
| ----------- | -------------------------------------------------- |

## [Description](#description)

Commands to mirror Docker Hardened Images to your organization's registry

## [Options](#options)

| Option  | Default | Description                                |
| ------- | ------- | ------------------------------------------ |
| `--org` |         | Docker Hub organization (overrides config) |

## [Subcommands](#subcommands)

| Command                                                                                     | Description                                       |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| [`docker dhi mirror list`](https://docs.docker.com/reference/cli/docker/dhi/mirror/list/)   | List all mirrored Docker Hardened Images          |
| [`docker dhi mirror start`](https://docs.docker.com/reference/cli/docker/dhi/mirror/start/) | Start mirroring Docker Hardened Images            |
| [`docker dhi mirror stop`](https://docs.docker.com/reference/cli/docker/dhi/mirror/stop/)   | Stop mirroring one or more Docker Hardened Images |

----
url: https://docs.docker.com/guides/dhi-openshift/
----

[Use Docker Hardened Images with Red Hat OpenShift](https://docs.docker.com/guides/dhi-openshift/)

Learn how to deploy Docker Hardened Images (DHI) on Red Hat OpenShift, configure Security Context Constraints, handle arbitrary user ID assignment, and set file permissions for both runtime and development image variants.

Docker Hardened Images

30 minutes

[« Back to all guides](/guides/)

# Use Docker Hardened Images with Red Hat OpenShift

***

Table of contents

***

Docker Hardened Images (DHI) can be deployed on Red Hat OpenShift Container Platform, but OpenShift’s security model differs from standard Kubernetes in ways that require specific configuration. Because OpenShift runs containers with an arbitrarily assigned user ID rather than the image’s default, you must adjust file ownership and group permissions in your Dockerfiles to ensure writable paths remain accessible.

This guide explains how to deploy Docker Hardened Images in OpenShift environments, covering Security Context Constraints (SCCs), arbitrary user ID assignment, file permission requirements, and best practices for both runtime and development image variants.

## [How OpenShift security differs from Kubernetes](#how-openshift-security-differs-from-kubernetes)

OpenShift extends Kubernetes with Security Context Constraints (SCCs), which control what actions a pod can perform and what resources it can access. While vanilla Kubernetes uses Pod Security Standards (PSS) for similar purposes, SCCs are more granular and enforced by default.

The key differences that affect DHI deployments:

**Arbitrary user IDs.** By default, OpenShift runs containers using an arbitrarily assigned user ID (UID) from a range allocated to each project. The default `restricted-v2` SCC (introduced in OpenShift 4.11) uses the `MustRunAsRange` strategy, which overrides the `USER` directive in the container image with a UID from the project’s allocated range (typically starting higher than 1000000000). This means even though a DHI image specifies a non-root user (UID 65532), OpenShift will run the container as a different, unpredictable UID.

**Root group requirement.** OpenShift assigns the arbitrary UID to the root group (GID 0). The container process always runs with `gid=0(root)`. Any directories or files that the process needs to write to must be owned by the root group (GID 0) with group read/write permissions. This is documented in the [Red Hat guidelines for creating images](https://docs.openshift.com/container-platform/4.14/openshift_images/create-images.html#use-uid_create-images).

> Important
>
> DHI images set file ownership to `nonroot:nonroot` (65532:65532) by default. Because the OpenShift arbitrary UID is NOT in the `nonroot` group (65532), it cannot write to those files — even though the pod is admitted by the SCC and the container starts. You must change group ownership to GID 0 for any writable path. This is the most common source of permission errors when deploying DHI on OpenShift.

**Capability restrictions.** The `restricted-v2` SCC drops all Linux capabilities by default and enforces `allowPrivilegeEscalation: false`, `runAsNonRoot: true`, and a `seccompProfile` of type `RuntimeDefault`. DHI runtime images already satisfy these constraints because they run as a non-root user and don’t require elevated capabilities.

## [Pull DHI images into OpenShift](#pull-dhi-images-into-openshift)

Before deploying, create an image pull secret so your OpenShift cluster can authenticate to the DHI registry or your mirrored repository on Docker Hub.

### [Create an image pull secret](#create-an-image-pull-secret)

```console
oc create secret docker-registry dhi-pull-secret \
    --docker-server=docker.io \
    --docker-username=<your-docker-username> \
    --docker-password=<your-docker-access-token> \
    --docker-email=<your-email>
```

If you’re pulling directly from `dhi.io` instead of a mirrored repository, set `--docker-server=dhi.io`.

### [Link the secret to a service account](#link-the-secret-to-a-service-account)

Link the pull secret to the `default` service account in your project so that all deployments can pull DHI images automatically:

```console
oc secrets link default dhi-pull-secret --for=pull
```

To use the secret with a specific service account instead:

```console
oc secrets link <service-account-name> dhi-pull-secret --for=pull
```

## [Build OpenShift-compatible images from DHI](#build-openshift-compatible-images-from-dhi)

DHI runtime images are distroless — they contain no shell, no package manager, and no `RUN`-capable environment. This means you **cannot use `RUN` commands in the runtime stage** of your Dockerfile. All file permission adjustments for OpenShift must happen in the `-dev` build stage, and the results must be copied into the runtime stage using `COPY --chown`.

The core pattern for OpenShift compatibility:

1. Use a DHI `-dev` variant as the build stage (it has a shell).
2. Build your application and set GID 0 ownership in the build stage.
3. Copy the results into the DHI runtime image using `COPY --chown=<UID>:0`.

### [Example: Nginx for OpenShift](#example-nginx-for-openshift)

```dockerfile
# Build stage — has a shell, can run commands
FROM YOUR_ORG/dhi-nginx:1.29-alpine3.23-dev AS build

# Copy custom config and set root group ownership
COPY nginx.conf /tmp/nginx.conf
COPY default.conf /tmp/default.conf

# Prepare writable directories with GID 0
# (Nginx needs to write to cache, logs, and PID file locations)
RUN mkdir -p /tmp/nginx-cache /tmp/nginx-run && \
    chgrp -R 0 /tmp/nginx-cache /tmp/nginx-run && \
    chmod -R g=u /tmp/nginx-cache /tmp/nginx-run

# Runtime stage — distroless, NO shell, NO RUN commands
FROM YOUR_ORG/dhi-nginx:1.29-alpine3.23

COPY --from=build --chown=65532:0 /tmp/nginx.conf /etc/nginx/nginx.conf
COPY --from=build --chown=65532:0 /tmp/default.conf /etc/nginx/conf.d/default.conf
COPY --from=build --chown=65532:0 /tmp/nginx-cache /var/cache/nginx
COPY --from=build --chown=65532:0 /tmp/nginx-run /var/run
```

> Important
>
> Always use `--chown=<UID>:0` (user:root-group) when copying files into the runtime stage. This ensures the arbitrary UID that OpenShift assigns can access the files through root group membership. Never use `RUN` in the runtime stage — distroless DHI images have no shell.

> Note
>
> The UID for DHI images varies by image. Most use 65532 (`nonroot`), but some (like the Node.js image) may use a different UID. Verify with: `docker inspect dhi.io/<image>:<tag> --format '{{.Config.User}}'`

Deploy to OpenShift:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-dhi
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-dhi
  template:
    metadata:
      labels:
        app: nginx-dhi
    spec:
      containers:
        - name: nginx
          image: YOUR_ORG/dhi-nginx:1.29-alpine3.23
          ports:
            - containerPort: 8080
          securityContext:
            allowPrivilegeEscalation: false
            runAsNonRoot: true
            seccompProfile:
              type: RuntimeDefault
            capabilities:
              drop:
                - ALL
      imagePullSecrets:
        - name: dhi-pull-secret
```

DHI Nginx listens on port 8080 by default (not 80), which is compatible with the non-root requirement. No SCC changes are needed.

### [Example: Node.js application for OpenShift](#example-nodejs-application-for-openshift)

```dockerfile
# Build stage — dev variant has shell and npm
FROM YOUR_ORG/dhi-node:24-alpine3.23-dev AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Set GID 0 on everything the runtime needs to write
RUN chgrp -R 0 /app/dist /app/node_modules && \
    chmod -R g=u /app/dist /app/node_modules

# Runtime stage — distroless, NO shell
FROM YOUR_ORG/dhi-node:24-alpine3.23
WORKDIR /app
COPY --from=build --chown=65532:0 /app/dist ./dist
COPY --from=build --chown=65532:0 /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]
```

Deploy:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: node-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: node-app
  template:
    metadata:
      labels:
        app: node-app
    spec:
      containers:
        - name: app
          image: YOUR_ORG/dhi-node-app:latest
          ports:
            - containerPort: 3000
          securityContext:
            allowPrivilegeEscalation: false
            runAsNonRoot: true
            seccompProfile:
              type: RuntimeDefault
            capabilities:
              drop:
                - ALL
      imagePullSecrets:
        - name: dhi-pull-secret
```

## [Handle arbitrary user IDs](#handle-arbitrary-user-ids)

OpenShift’s `restricted-v2` SCC assigns a random UID to the container process. This UID won’t exist in `/etc/passwd` inside the image, but the container will still run — the process just won’t have a username associated with it.

This can cause issues with applications that:

* Look up the current user’s home directory or username
* Write to directories owned by a specific UID
* Check `/etc/passwd` for the running user

### [Add a `passwd` entry for the arbitrary UID](#add-a-passwd-entry-for-the-arbitrary-uid)

Some applications (notably those using certain Python or Java libraries) require a valid `/etc/passwd` entry for the running user. You can handle this with a wrapper entrypoint script.

Because this pattern requires a shell, it only works with DHI `-dev` variants or with a DHI Enterprise customized image that includes a shell. Prepare the image in the build stage:

```dockerfile
FROM YOUR_ORG/dhi-python:3.13-alpine3.23-dev AS build
# ... build your application ...

# Make /etc/passwd group-writable so the entrypoint can append to it
RUN chgrp 0 /etc/passwd && chmod g=u /etc/passwd

# Create the entrypoint wrapper
RUN printf '#!/bin/sh\n\
if ! whoami > /dev/null 2>&1; then\n\
  if [ -w /etc/passwd ]; then\n\
    echo "${USER_NAME:-appuser}:x:$(id -u):0:dynamic user:/tmp:/sbin/nologin" >> /etc/passwd\n\
  fi\n\
fi\n\
exec "$@"\n' > /entrypoint.sh && chmod +x /entrypoint.sh

# This pattern requires a -dev variant as runtime (has shell)
FROM YOUR_ORG/dhi-python:3.13-alpine3.23-dev
COPY --from=build --chown=65532:0 /app ./app
COPY --from=build --chown=65532:0 /entrypoint.sh /entrypoint.sh
COPY --from=build --chown=65532:0 /etc/passwd /etc/passwd
USER 65532
ENTRYPOINT ["/entrypoint.sh"]
CMD ["python", "app/main.py"]
```

> Note
>
> For distroless runtime images (no shell), the passwd-injection pattern is not possible. Instead, use the `nonroot` SCC (described in the following section) to run with the image’s built-in UID so the existing `/etc/passwd` entry matches the running process. Alternatively, OpenShift 4.x automatically injects the arbitrary UID into `/etc/passwd` in most cases, which resolves this for many applications.

## [Use the non-root SCC for fixed UIDs](#use-the-non-root-scc-for-fixed-uids)

If your application requires running as the specific UID defined in the image (typically 65532 for DHI), you can use the `nonroot` SCC instead of the default `restricted-v2`. The `nonroot` SCC uses the `MustRunAsNonRoot` strategy, which allows any non-zero UID.

> Important
>
> For the `nonroot` SCC to work, the image’s `USER` directive must specify a **numeric** UID (for example, `65532`), not a username string like `nonroot`. OpenShift cannot verify that a username maps to a non-zero UID. Verify your DHI image with: `docker inspect YOUR_ORG/dhi-node:24-alpine3.23 --format '{{.Config.User}}'` If the output is a string rather than a number, set `runAsUser` explicitly in the pod spec.

Create a service account and grant it the `nonroot` SCC:

```console
oc create serviceaccount dhi-nonroot
oc adm policy add-scc-to-user nonroot -z dhi-nonroot
```

Reference the service account in your deployment:

```yaml
spec:
  template:
    spec:
      serviceAccountName: dhi-nonroot
      containers:
        - name: app
          image: YOUR_ORG/dhi-node:24-alpine3.23
          securityContext:
            runAsUser: 65532
            runAsNonRoot: true
            allowPrivilegeEscalation: false
            seccompProfile:
              type: RuntimeDefault
            capabilities:
              drop:
                - ALL
```

Verify the SCC assignment after deployment:

```console
oc get pod <pod-name> -o jsonpath='{.metadata.annotations.openshift\.io/scc}'
```

This should return `nonroot`.

When using the `nonroot` SCC with a fixed UID, the process runs as 65532 (matching the image’s file ownership), so the GID 0 adjustments are not strictly required for paths already owned by 65532. However, applying `chown <UID>:0` is still recommended for portability across both `restricted-v2` and `nonroot` SCCs.

## [Use DHI dev variants in OpenShift](#use-dhi-dev-variants-in-openshift)

DHI `-dev` variants include a shell, package manager, and development tools. They run as root (UID 0) by default, which conflicts with OpenShift’s `restricted-v2` SCC. There are three approaches:

### [Option 1: Use dev variants only in build stages (recommended)](#option-1-use-dev-variants-only-in-build-stages-recommended)

Use `-dev` variants only in Dockerfile build stages and never deploy them directly to OpenShift:

```dockerfile
FROM YOUR_ORG/dhi-node:24-alpine3.23-dev AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Set root group ownership for OpenShift compatibility
RUN chgrp -R 0 /app/dist /app/node_modules && \
    chmod -R g=u /app/dist /app/node_modules

FROM YOUR_ORG/dhi-node:24-alpine3.23
WORKDIR /app
COPY --from=build --chown=65532:0 /app/dist ./dist
COPY --from=build --chown=65532:0 /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]
```

The final runtime image is non-root and distroless, fully compatible with `restricted-v2`.

### [Option 2: Grant the `anyuid` SCC for debugging](#option-2-grant-the-anyuid-scc-for-debugging)

If you need to run a `-dev` variant directly in OpenShift for debugging, grant the `anyuid` SCC to a dedicated service account:

```console
oc create serviceaccount dhi-debug
oc adm policy add-scc-to-user anyuid -z dhi-debug
```

Then reference it in your pod:

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: dhi-debug
spec:
  serviceAccountName: dhi-debug
  containers:
    - name: debug
      image: YOUR_ORG/dhi-node:24-alpine3.23-dev
      command: ["sleep", "infinity"]
  imagePullSecrets:
    - name: dhi-pull-secret
```

> Important
>
> The `anyuid` SCC allows running as any UID including root. Only use this for temporary debugging — never in production workloads.

### [Option 3: Use `oc debug` or ephemeral containers](#option-3-use-oc-debug-or-ephemeral-containers)

For distroless runtime images with no shell, use OpenShift-native debugging tools instead of `docker debug` (which only works with Docker Engine, not with CRI-O on OpenShift).

Use `oc debug` to create a copy of a pod with a debug shell:

```console
# Create a debug pod based on a deployment
oc debug deployment/nginx-dhi

# Override the image to use a -dev variant with a shell
oc debug deployment/nginx-dhi --image=YOUR_ORG/dhi-node:24-alpine3.23-dev
```

Use ephemeral containers (OpenShift 4.12+ / Kubernetes 1.25+):

```console
kubectl debug -it <pod-name> --image=YOUR_ORG/dhi-node:24-alpine3.23-dev \
    --target=app -- sh
```

This attaches a temporary debug container to a running pod without restarting it, sharing the pod’s process namespace.

> Note
>
> `docker debug` is a Docker Desktop/CLI feature for local development. It is not available on OpenShift clusters, which use CRI-O as their container runtime.

## [Deploy DHI Helm charts on OpenShift](#deploy-dhi-helm-charts-on-openshift)

DHI provides pre-configured Helm charts for popular applications. When deploying these charts on OpenShift, you may need to adjust security context settings.

### [Inspect chart values first](#inspect-chart-values-first)

Before installing, check what security context values the chart exposes:

```console
helm registry login dhi.io

helm show values oci://dhi.io/<chart-name> --version <version> | grep -A 20 securityContext
```

The available value paths vary by chart, so always check `values.yaml` before setting overrides.

### [Install with OpenShift overrides](#install-with-openshift-overrides)

The following example shows a typical installation pattern. Adjust the `--set` paths based on what `helm show values` returns for your specific chart:

```console
helm install my-release oci://dhi.io/<chart-name> \
    --version <version> \
    --set "imagePullSecrets[0].name=dhi-pull-secret" \
    -f openshift-values.yaml
```

Create an `openshift-values.yaml` with security context overrides appropriate for your chart:

```yaml
# Example — adjust keys based on `helm show values` output
podSecurityContext:
  runAsNonRoot: true
  seccompProfile:
    type: RuntimeDefault

securityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL
```

> Note
>
> DHI Helm chart value paths are not standardized across charts. For example, one chart may use `image.imagePullSecrets`, while another uses `global.imagePullSecrets`. Always consult the specific chart’s documentation or `values.yaml`.

## [Verify your deployment](#verify-your-deployment)

After deploying a DHI image to OpenShift, verify the security configuration.

### [Check the assigned SCC](#check-the-assigned-scc)

```console
oc get pods -o 'custom-columns=NAME:.metadata.name,SCC:.metadata.annotations.openshift\.io/scc'
```

Runtime DHI images should show `restricted-v2` (or `nonroot` if you configured it).

### [Check the running UID](#check-the-running-uid)

```console
oc exec <pod-name> -- id
```

With the `restricted-v2` SCC, you should see output like:

```text
uid=1000650000 gid=0(root) groups=0(root),1000650000
```

The UID is from the project’s allocated range, and the primary GID is always 0 (root group). With the `nonroot` SCC and `runAsUser: 65532`, you would see `uid=65532`.

### [Confirm the image is distroless](#confirm-the-image-is-distroless)

```console
oc exec <pod-name> -- sh -c "echo hello"
```

For runtime (non-dev) DHI images, this command should fail with an error indicating that `sh` was not found in `$PATH`. The exact error format varies between CRI-O versions.

### [Scan the deployed image](#scan-the-deployed-image)

Use Docker Scout to verify the security posture of the deployed image (run this from your local machine, not on the cluster):

```console
docker scout cves YOUR_ORG/dhi-nginx:1.29-alpine3.23
docker scout quickview YOUR_ORG/dhi-nginx:1.29-alpine3.23
```

## [Common issues and solutions](#common-issues-and-solutions)

**Pod fails to start with “container has runAsNonRoot and image has group or user ID set to root.”** This happens when deploying a DHI `-dev` variant with the default `restricted-v2` SCC. Either use the runtime variant instead, or grant the `anyuid` SCC to the service account.

**Application cannot write to a directory.** The arbitrary UID assigned by OpenShift doesn’t have write permissions. This is the most common issue with DHI on OpenShift. All writable paths must be owned by GID 0 with group write permissions. Fix this in the build stage: `chgrp -R 0 /path && chmod -R g=u /path`, then `COPY --chown=<UID>:0` into the runtime stage.

**Application fails with “user not found” or “no matching entries in passwd file.”** Some applications require a valid `/etc/passwd` entry. OpenShift 4.x automatically injects the arbitrary UID into `/etc/passwd` in most cases. If your application still fails, use the passwd-injection pattern (requires a `-dev` variant) or use the `nonroot` SCC to run with the image’s built-in UID.

**Pod fails to bind to port 80 or 443.** Ports lower than 1024 require root privileges. DHI images use unprivileged ports by default (for example, Nginx uses 8080). Configure your OpenShift Service to map the external port to the container’s unprivileged port:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: nginx-dhi
spec:
  ports:
    - port: 80
      targetPort: 8080
  selector:
    app: nginx-dhi
```

**ImagePullBackOff with “unauthorized: authentication required.”** Verify the pull secret is correctly configured and linked to the service account. Check with `oc get secret dhi-pull-secret` and `oc describe sa default`.

**Dockerfile build fails with “exec: not found” in runtime stage.** You are using `RUN` in a distroless runtime stage. DHI runtime images have no shell, so `RUN` commands cannot execute. Move all `RUN` commands to the `-dev` build stage and use `COPY --chown` to transfer results.

## [DHI and OpenShift compatibility summary](#dhi-and-openshift-compatibility-summary)

| Feature                       | DHI runtime                       | DHI `-dev`           | DHI with Enterprise customization |
| ----------------------------- | --------------------------------- | -------------------- | --------------------------------- |
| Default SCC (`restricted-v2`) | Yes, with GID 0 permissions       | Requires `anyuid`    | Yes, with GID 0 permissions       |
| Non-root by default           | Yes (UID 65532)                   | No (root)            | Yes (configurable UID)            |
| Arbitrary UID support         | Yes, with `chown <UID>:0`         | Yes                  | Yes, with `chown <UID>:0`         |
| Distroless (no shell)         | Yes — no `RUN` in Dockerfile      | No                   | Yes — no `RUN` in Dockerfile      |
| Unprivileged ports            | Yes (higher than 1024)            | Configurable         | Yes (higher than 1024)            |
| SLSA Build Level 3            | Yes                               | Yes                  | Yes                               |
| Debug on cluster              | `oc debug` / ephemeral containers | `oc exec` with shell | `oc debug` / ephemeral containers |

## [What’s next](#whats-next)

* [Use an image in Kubernetes](/dhi/how-to/k8s/) — general DHI Kubernetes deployment guide.
* [Customize an image](/dhi/how-to/customize/) — add packages to DHI images using Enterprise customization.
* [Debug a container](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers with Docker Debug (local development).
* [Managing SCCs](https://docs.openshift.com/container-platform/4.14/authentication/managing-security-context-constraints.html) — Red Hat’s reference documentation on Security Context Constraints.
* [Creating images for OpenShift](https://docs.openshift.com/container-platform/4.14/openshift_images/create-images.html) — Red Hat’s guidelines for building OpenShift-compatible container images.

----
url: https://docs.docker.com/reference/cli/docker/container/rm/
----

# docker container rm

***

| Description                                                               | Remove one or more containers                            |
| ------------------------------------------------------------------------- | -------------------------------------------------------- |
| Usage                                                                     | `docker container rm [OPTIONS] CONTAINER [CONTAINER...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker container remove` `docker rm`                    |

## [Description](#description)

Remove one or more containers

## [Options](#options)

| Option                      | Default | Description                                             |
| --------------------------- | ------- | ------------------------------------------------------- |
| [`-f, --force`](#force)     |         | Force the removal of a running container (uses SIGKILL) |
| [`-l, --link`](#link)       |         | Remove the specified link                               |
| [`-v, --volumes`](#volumes) |         | Remove anonymous volumes associated with the container  |

## [Examples](#examples)

### [Remove a container](#remove-a-container)

This removes the container referenced under the link `/redis`.

```console
$ docker rm /redis

/redis
```

### [Remove a link specified with `--link` on the default bridge network (--link)](#link)

This removes the underlying link between `/webapp` and the `/redis` containers on the default bridge network, removing all network communication between the two containers. This does not apply when `--link` is used with user-specified networks.

```console
$ docker rm --link /webapp/redis

/webapp/redis
```

### [Force-remove a running container (--force)](#force)

This command force-removes a running container.

```console
$ docker rm --force redis

redis
```

The main process inside the container referenced under the link `redis` will receive `SIGKILL`, then the container will be removed.

### [Remove all stopped containers](#remove-all-stopped-containers)

Use the [`docker container prune`](/reference/cli/docker/container/prune/) command to remove all stopped containers, or refer to the [`docker system prune`](/reference/cli/docker/system/prune/) command to remove unused containers in addition to other Docker resources, such as (unused) images and networks.

Alternatively, you can use the `docker ps` with the `-q` / `--quiet` option to generate a list of container IDs to remove, and use that list as argument for the `docker rm` command.

Combining commands can be more flexible, but is less portable as it depends on features provided by the shell, and the exact syntax may differ depending on what shell is used. To use this approach on Windows, consider using PowerShell or Bash.

The example below uses `docker ps -q` to print the IDs of all containers that have exited (`--filter status=exited`), and removes those containers with the `docker rm` command:

```console
$ docker rm $(docker ps --filter status=exited -q)
```

Or, using the `xargs` Linux utility:

```console
$ docker ps --filter status=exited -q | xargs docker rm
```

### [Remove a container and its volumes (-v, --volumes)](#volumes)

```console
$ docker rm --volumes redis
redis
```

This command removes the container and any volumes associated with it. Note that if a volume was specified with a name, it will not be removed.

### [Remove a container and selectively remove volumes](#remove-a-container-and-selectively-remove-volumes)

```console
$ docker create -v awesome:/foo -v /bar --name hello redis
hello

$ docker rm -v hello
```

In this example, the volume for `/foo` remains intact, but the volume for `/bar` is removed. The same behavior holds for volumes inherited with `--volumes-from`.

----
url: https://docs.docker.com/dhi/core-concepts/slsa/
----

# Supply-chain Levels for Software Artifacts (SLSA)

***

Table of contents

***

## [What is SLSA?](#what-is-slsa)

Supply-chain Levels for Software Artifacts (SLSA) is a security framework designed to enhance the integrity and security of software supply chains. Developed by Google and maintained by the Open Source Security Foundation (OpenSSF), SLSA provides a set of guidelines and best practices to prevent tampering, improve integrity, and secure packages and infrastructure in software projects.

SLSA defines [four build levels (0–3)](https://slsa.dev/spec/latest/build-track-basics) of increasing security rigor, focusing on areas such as build provenance, source integrity, and build environment security. Each level builds upon the previous one, offering a structured approach to achieving higher levels of software supply chain security.

## [Why is SLSA important?](#why-is-slsa-important)

SLSA is crucial for modern software development due to the increasing complexity and interconnectedness of software supply chains. Supply chain attacks, such as the SolarWinds breach, have highlighted the vulnerabilities in software development processes. By implementing SLSA, organizations can:

* Ensure artifact integrity: Verify that software artifacts have not been tampered with during the build and deployment processes.

* Enhance build provenance: Maintain verifiable records of how and when software artifacts were produced, providing transparency and accountability.

* Secure build environments: Implement controls to protect build systems from unauthorized access and modifications.

* Mitigate supply chain risks: Reduce the risk of introducing vulnerabilities or malicious code into the software supply chain.

## [What is SLSA Build Level 3?](#what-is-slsa-build-level-3)

SLSA Build Level 3, Hardened Builds, is the highest of four progressive levels in the SLSA framework. It introduces strict requirements to ensure that software artifacts are built securely and traceably. To meet Level 3, a build must:

* Be fully automated and scripted to prevent manual tampering
* Use a trusted build service that enforces source and builder authentication
* Generate a signed, tamper-resistant provenance record describing how the artifact was built
* Capture metadata about the build environment, source repository, and build steps

This level provides strong guarantees that the software was built from the expected source in a controlled, auditable environment, which significantly reduces the risk of supply chain attacks.

## [Docker Hardened Images and SLSA](#docker-hardened-images-and-slsa)

Docker Hardened Images (DHIs) are secure-by-default container images purpose-built for modern production environments. Each DHI is cryptographically signed and complies with the [SLSA Build Level 3 standard](https://slsa.dev/spec/latest/build-track-basics#build-l3), ensuring verifiable build provenance and integrity.

By integrating SLSA-compliant DHIs into your development and deployment processes, you can:

* Achieve higher security levels: Utilize images that meet stringent security standards, reducing the risk of vulnerabilities and attacks.

* Simplify compliance: Leverage built-in features like signed Software Bills of Materials (SBOMs) and vulnerability exception (VEX) statements to facilitate compliance with regulations such as FedRAMP.

* Enhance transparency: Access detailed information about the components and build process of each image, promoting transparency and trust.

* Streamline audits: Utilize verifiable build records and signatures to simplify security audits and assessments.

## [Get and verify SLSA provenance for Docker Hardened Images](#get-and-verify-slsa-provenance-for-docker-hardened-images)

Each Docker Hardened Image (DHI) is cryptographically signed and includes attestations. These attestations provide verifiable build provenance and demonstrate adherence to SLSA Build Level 3 standards.

To get and verify SLSA provenance for a DHI, you can use Docker Scout.

```console
$ docker scout attest get dhi.io/<image>:<tag> \
  --predicate-type https://slsa.dev/provenance/v0.2 \
  --verify
```

For example:

```console
$ docker scout attest get dhi.io/node:20.19-debian12 \
  --predicate-type https://slsa.dev/provenance/v0.2 \
  --verify
```

## [Resources](#resources)

For more details about SLSA definitions and Docker Build, see [SLSA definitions](/build/metadata/attestations/slsa-definitions/).

----
url: https://docs.docker.com/admin/organization/manage/members/
----

# Manage organization members

***

Table of contents

***

Learn how to manage members for your organization in Docker Hub and the Docker Admin Console.

## [Invite members](#invite-members)

Owners can invite new members to an organization via Docker ID, email address, or with a CSV file containing email addresses. If an invitee does not have a Docker account, they must create an account and verify their email address before they can accept an invitation to join the organization. When inviting members, their pending invitation occupies a seat.

### [Invite members via Docker ID or email address](#invite-members-via-docker-id-or-email-address)

Use the following steps to invite members to your organization via Docker ID or email address.

1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down.
2. Select **Members**, then **Invite**.
3. Select **Emails or usernames**.
4. Follow the on-screen instructions to invite members. Invite a maximum of 1000 members and separate multiple entries by comma, semicolon, or space.

When you invite members, you assign them a role. See [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/) for details about the access permissions for each role.

Pending invitations appear in the table. Invitees receive an email with a link to Docker Hub where they can accept or decline the invitation.

### [Invite members via CSV file](#invite-members-via-csv-file)

To invite multiple members to an organization via a CSV file containing email addresses:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down. Select **Members** > **Invite** > **CSV upload**.

2. Optional. Select **Download the template CSV file** to download an example CSV file. The following is an example of the contents of a valid CSV file:

   ```text
   email
   docker.user-0@example.com
   docker.user-1@example.com
   ```

   The example file demonstrates CSV file requirements:

   * The file must contain a header row with at least one heading named email. Additional columns are allowed and are ignored in the import.
   * The file must contain a maximum of 1000 email addresses (rows). To invite more than 1000 users, create multiple CSV files and perform all steps in this task for each file.

3. Create a new CSV file or export a CSV file from another application.

   * To export a CSV file from another application, see the application’s documentation.
   * To create a new CSV file, open a new file in a text editor, type email on the first line, type the user email addresses one per line on the following lines, and then save the file with a .csv extension.

4. Select **Browse files** and then select your CSV file, or drag and drop the CSV file into the **Select a CSV file to upload** box. You can only select one CSV file at a time.

5. After the CSV file has been uploaded, select **Review** to identify any invalid email addresses, already invited users, invited users who are already members, or duplicated email addresses within the same CSV file.

6. Follow the on-screen instructions to invite members.

Pending invitations appear in the table. The invitees receive an email with a link to Docker Hub where they can accept or decline the invitation.

### [Invite members via API](#invite-members-via-api)

You can bulk invite members using the Docker Hub API. For more information, see the [Bulk create invites](https://docs.docker.com/reference/api/hub/latest/#tag/invites/paths/~1v2~1invites~1bulk/post) API endpoint.

## [Accept invitation](#accept-invitation)

After receiving an email invitation, users can access a link to Docker Hub where they can accept or decline the invitation.

To accept an invitation:

1. Check your email inbox and open the Docker email with an invitation to join the Docker organization.
2. To open the link to Docker Hub, select the **click here** link.
3. The Docker create an account page will open. If you already have an account, select **Already have an account? Sign in**. If you do not have an account yet, create an account using the same email address you received the invitation through.
4. Optional. If you do not have an account and created one, you must navigate back to your email inbox and verify your email address using the Docker verification email.
5. Once you are signed in to Docker Hub, select **My Hub** from the top-level navigation menu.
6. Select **Accept** on your invitation.

After accepting an invitation, you are now a member of the organization.

Invitation email links expire after 14 days. If your email link has expired, you can sign in to [Docker Hub](https://hub.docker.com/) with the email address the link was sent to and accept the invitation from the **Notifications** panel.

## [Manage invitations](#manage-invitations)

After inviting members, you can resend or remove invitations as needed. Each invitee occupies one seat, so if the amount of email addresses in your CSV file exceeds the number of available seats in your organization, you won't be able to invite more members.

> Tip
>
> Need to manage more than 1,000 team members? [Upgrade to Docker Business for unlimited user invites](https://www.docker.com/pricing?ref=Docs\&refAction=DocsAdminMembers) and advanced role management. You can also [add seats](https://docs.docker.com/subscription/manage-seats/) to your subscription.

### [Resend an invitation](#resend-an-invitation)

You can send individual invitations, or bulk invitations from the Admin Console.

To resend an individual invitation:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Members**.
3. Select the **action menu** next to the invitee and select **Resend**.
4. Select **Invite** to confirm.

To bulk resend invitations:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Members**.
3. Use the **checkboxes** next to **Usernames** to bulk select users.
4. Select **Resend invites**.
5. Select **Resend** to confirm.

### [Remove an invitation](#remove-an-invitation)

To remove an invitation from the Admin Console:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Members**.
3. Select the **action menu** next to the invitee and select **Remove invitee**.
4. Select **Remove** to confirm.

## [Manage members on a team](#manage-members-on-a-team)

Use Docker Hub or the Admin Console to add or remove team members. Organization owners can add a member to one or more teams within an organization.

### [Add a member to a team](#add-a-member-to-a-team)

To add a member to a team with the Admin Console:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Teams**.
3. Select the team name.
4. Select **Add member**. You can add the member by searching for their email address or username.

An invitee must first accept the invitation to join the organization before being added to the team.

### [Remove members from teams](#remove-members-from-teams)

If your organization uses single sign-on (SSO) with [SCIM](https://docs.docker.com/enterprise/security/provisioning/scim/) enabled, you should remove members from your identity provider (IdP). This automatically removes members from Docker. If SCIM is disabled, follow procedures in this doc to remove members manually in Docker.

Organization owners can remove a member from a team in Docker Hub or Admin Console. Removing the member from the team will revoke their access to the permitted resources. To remove a member from a specific team with the Admin Console:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Teams**, then choose the name of the team member you want to remove.
3. Select the **X** next to the user's name to remove them from the team.
4. When prompted, select **Remove** to confirm.

### [Update a member role](#update-a-member-role)

Organization owners can manage [roles](https://docs.docker.com/enterprise/security/roles-and-permissions/) within an organization. If an organization is part of a company, the company owner can also manage that organization's roles. If you have SSO enabled, you can use [SCIM for role mapping](https://docs.docker.com/enterprise/security/provisioning/scim/).

To update a member role in the Admin Console:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Members**.
3. Find the username of the member whose role you want to edit. Select the **Actions** menu, then **Edit role**.

If you're the only owner of an organization and you want to edit your role, assign a new owner for your organization so you can edit your role.

## [Export members CSV file](#export-members-csv-file)

Subscription: Team Business

For: Administrators

Owners can export a CSV file containing all members. The CSV file for a company contains the following fields:

* Name: The user's name
* Username: The user's Docker ID
* Email: The user's email address
* Member of Organizations: All organizations the user is a member of within a company
* Invited to Organizations: All organizations the user is an invitee of within a company
* Account Created: The time and date when the user account was created

To export a CSV file of your members:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Members**.
3. Select the **download** icon to export a CSV file of all members.

----
url: https://docs.docker.com/scout/deep-dive/data-handling/
----

# Data collection and storage in Docker Scout

***

Table of contents

***

Docker Scout's image analysis works by collecting metadata from the container images that you analyze. This metadata is stored on the Docker Scout platform.

## [Data transmission](#data-transmission)

This section describes the data that Docker Scout collects and sends to the platform.

### [Image metadata](#image-metadata)

Docker Scout collects the following image metadata:

* Image creation timestamp
* Image digest
* Ports exposed by the image
* Environment variable names and values
* Name and value of image labels
* Order of image layers
* Hardware architecture
* Operating system type and version
* Registry URL and type

Image digests are created for each layer of an image when the image is built and pushed to a registry. They are SHA256 digests of the contents of a layer. Docker Scout doesn't create the digests; they're read from the image manifest.

The digests are matched against your own private images and Docker's database of public images to identify images that share the same layers. The image that shares most of the layers is considered a base image match for the image that's currently being analyzed.

### [SBOM metadata](#sbom-metadata)

Software Bill of Material (SBOM) metadata is used to match package types and versions with vulnerability data to infer whether an image is affected. When the Docker Scout platform receives information from security advisories about new CVEs or other risk factors, such as leaked secrets, it cross-references this information with the SBOM. If there's a match, Docker Scout displays the results in the user interfaces where Docker Scout data is surfaced, such as the Docker Scout Dashboard and in Docker Desktop.

Docker Scout collects the following SBOM metadata:

* Package URLs (PURL)
* Package author and description
* License IDs
* Package name and namespace
* Package scheme and size
* Package type and version
* Filepath within the image
* The type of direct dependency
* Total package count

The PURLs in Docker Scout follow the [purl-spec](https://github.com/package-url/purl-spec) specification. Package information is derived from the contents of image, including OS-level programs and packages, and application-level packages such as maven, npm, and so on.

### [Environment metadata](#environment-metadata)

If you integrate Docker Scout with your runtime environment via the [Sysdig integration](https://docs.docker.com/scout/integrations/environment/sysdig/), Docker Scout collects the following data points about your deployments:

* Kubernetes namespace
* Workload name
* Workload type (for example, DaemonSet)

### [Local analysis](#local-analysis)

For images analyzed locally on a developer's machine, Docker Scout only transmits PURLs and layer digests. This data isn't persistently stored on the Docker Scout platform; it's only used to run the analysis.

### [Provenance](#provenance)

For images with [provenance attestations](https://docs.docker.com/build/metadata/attestations/slsa-provenance/), Docker Scout stores the following data in addition to the SBOM:

* Materials
* Base image
* VCS information
* Dockerfile

## [Data storage](#data-storage)

For the purposes of providing the Docker Scout service, data is stored using:

* Amazon Web Services (AWS) on servers located in US East
* Google Cloud Platform (GCP) on servers located in US East

Data is used according to the processes described at [docker.com/legal](https://www.docker.com/legal/) to provide the key capabilities of Docker Scout.

----
url: https://docs.docker.com/dhi/migration/examples/go/
----

# Go

***

***

This example shows how to migrate a Go application to Docker Hardened Images.

The following examples show Dockerfiles before and after migration to Docker Hardened Images. Each example includes five variations:

* Before (Ubuntu): A sample Dockerfile using Ubuntu-based images, before migrating to DHI
* Before (Wolfi): A sample Dockerfile using Wolfi distribution images, before migrating to DHI
* Before (DOI): A sample Dockerfile using Docker Official Images, before migrating to DHI
* After (multi-stage): A sample Dockerfile after migrating to DHI with multi-stage builds (recommended for minimal, secure images)
* After (single-stage): A sample Dockerfile after migrating to DHI with single-stage builds (simpler but results in a larger image with a broader attack surface)

> Note
>
> Multi-stage builds are recommended for most use cases. Single-stage builds are supported for simplicity, but come with tradeoffs in size and security.
>
> You must authenticate to `dhi.io` before you can pull Docker Hardened Images. Use your Docker ID credentials (the same username and password you use for Docker Hub). If you don't have a Docker account, [create one](https://docs.docker.com/accounts/create-account/) for free.
>
> Run `docker login dhi.io` to authenticate.

```dockerfile
#syntax=docker/dockerfile:1

FROM ubuntu/go:1.22-24.04

WORKDIR /app
ADD . ./

# Install any additional packages if needed using apt
# RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*

RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" --installsuffix cgo -o main .

ENTRYPOINT ["/app/main"]
```

```dockerfile
#syntax=docker/dockerfile:1

FROM cgr.dev/chainguard/go:latest-dev

WORKDIR /app
ADD . ./

# Install any additional packages if needed using apk
# RUN apk add --no-cache git

RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" --installsuffix cgo -o main .

ENTRYPOINT ["/app/main"]
```

```dockerfile
#syntax=docker/dockerfile:1

FROM golang:latest

WORKDIR /app
ADD . ./

# Install any additional packages if needed using apt
# RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*

RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" --installsuffix cgo -o main .

ENTRYPOINT ["/app/main"]
```

```dockerfile
#syntax=docker/dockerfile:1

# === Build stage: Compile Go application ===
FROM dhi.io/golang:1-alpine3.21-dev AS builder

WORKDIR /app
ADD . ./

# Install any additional packages if needed using apk
# RUN apk add --no-cache git

RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" --installsuffix cgo -o main .

# === Final stage: Create minimal runtime image ===
FROM dhi.io/golang:1-alpine3.21

WORKDIR /app
COPY --from=builder /app/main  /app/main

ENTRYPOINT ["/app/main"]
```

```dockerfile
#syntax=docker/dockerfile:1

FROM dhi.io/golang:1-alpine3.21-dev

WORKDIR /app
ADD . ./

# Install any additional packages if needed using apk
# RUN apk add --no-cache git

RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" --installsuffix cgo -o main .

ENTRYPOINT ["/app/main"]
```

----
url: https://docs.docker.com/guides/testcontainers-java-aws-localstack/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

```console
$ ./mvnw test
```

Or with Gradle:

```console
$ ./gradlew test
```

You should see the LocalStack Docker container start and the test pass. After the tests finish, the container stops and is removed automatically.

## [Summary](#summary)

LocalStack lets you develop and test AWS-based applications locally. The Testcontainers LocalStack module makes it straightforward to write integration tests by using ephemeral LocalStack containers that start on random ports with no external setup required.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testcontainers LocalStack module](https://java.testcontainers.org/modules/localstack/)
* [Getting started with Testcontainers for Java](https://java.testcontainers.org/quickstart/junit_5_quickstart/)
* [Spring Cloud AWS documentation](https://docs.awspring.io/spring-cloud-aws/docs/3.0.3/reference/html/index.html)

----
url: https://docs.docker.com/scout/explore/metrics-exporter/
----

# Docker Scout metrics exporter

***

Table of contents

***

Docker Scout exposes a metrics HTTP endpoint that lets you scrape vulnerability and policy data from Docker Scout, using Prometheus or Datadog. With this you can create your own, self-hosted Docker Scout dashboards for visualizing supply chain metrics.

## [Metrics](#metrics)

The metrics endpoint exposes the following metrics:

| Metric                          | Description                                         | Labels                            | Type  |
| ------------------------------- | --------------------------------------------------- | --------------------------------- | ----- |
| `scout_stream_vulnerabilities`  | Vulnerabilities in a stream                         | `streamName`, `severity`          | Gauge |
| `scout_policy_compliant_images` | Compliant images for a policy in a stream           | `id`, `displayName`, `streamName` | Gauge |
| `scout_policy_evaluated_images` | Total images evaluated against a policy in a stream | `id`, `displayName`, `streamName` | Gauge |

> **Streams**
>
> In Docker Scout, the streams concept is a superset of [environments](https://docs.docker.com/scout/integrations/environment/). Streams include all runtime environments that you've defined, as well as the special `latest-indexed` stream. The `latest-indexed` stream contains the most recently pushed (and analyzed) tag for each repository.
>
> Streams is mostly an internal concept in Docker Scout, with the exception of the data exposed through this metrics endpoint.

## [Creating an access token](#creating-an-access-token)

To export metrics from your organization, first make sure your organization is enrolled in Docker Scout. Then, create a Personal Access Token (PAT) - a secret token that allows the exporter to authenticate with the Docker Scout API.

The PAT does not require any specific permissions, but it must be created by a user who is an owner of the Docker organization. To create a PAT, follow the steps in [Create an access token](https://docs.docker.com/security/access-tokens/).

Once you have created the PAT, store it in a secure location. You will need to provide this token to the exporter when scraping metrics.

## [Prometheus](#prometheus)

This section describes how to scrape the metrics endpoint using Prometheus.

### [Add a job for your organization](#add-a-job-for-your-organization)

In the Prometheus configuration file, add a new job for your organization. The job should include the following configuration; replace `ORG` with your organization name:

```yaml
scrape_configs:
  - job_name: ORG
    metrics_path: /v1/exporter/org/ORG/metrics
    scheme: https
    static_configs:
      - targets:
          - api.scout.docker.com
```

The address in the `targets` field is set to the domain name of the Docker Scout API, `api.scout.docker.com`. Make sure that there's no firewall rule in place preventing the server from communicating with this endpoint.

### [Add bearer token authentication](#add-bearer-token-authentication)

To scrape metrics from the Docker Scout Exporter endpoint using Prometheus, you need to configure Prometheus to use the PAT as a bearer token. The exporter requires the PAT to be passed in the `Authorization` header of the request.

Update the Prometheus configuration file to include the `authorization` configuration block. This block defines the PAT as a bearer token stored in a file:

```yaml
scrape_configs:
  - job_name: $ORG
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/token
```

The content of the file should be the PAT in plain text:

```console
dckr_pat_...
```

If you are running Prometheus in a Docker container or Kubernetes pod, mount the file into the container using a volume or secret.

Finally, restart Prometheus to apply the changes.

### [Prometheus sample project](#prometheus-sample-project)

If you don't have a Prometheus server set up, you can run a [sample project](https://github.com/dockersamples/scout-metrics-exporter) using Docker Compose. The sample includes a Prometheus server that scrapes metrics for a Docker organization enrolled in Docker Scout, alongside Grafana with a pre-configured dashboard to visualize the vulnerability and policy metrics.

1. Clone the starter template for bootstrapping a set of Compose services for scraping and visualizing the Docker Scout metrics endpoint:

   ```console
   $ git clone git@github.com:dockersamples/scout-metrics-exporter.git
   $ cd scout-metrics-exporter/prometheus
   ```

2. [Create a Docker access token](https://docs.docker.com/security/access-tokens/) and store it in a plain text file at `/prometheus/prometheus/token` under the template directory.

   token

   ```plaintext
   $ echo $DOCKER_PAT > ./prometheus/token
   ```

3. In the Prometheus configuration file at `/prometheus/prometheus/prometheus.yml`, replace `ORG` in the `metrics_path` property on line 6 with the namespace of your Docker organization.

   prometheus/prometheus.yml

   |                                                |                                                                                                                                                                                                                                                                                                                                               |
   | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | ```
    1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   12
   13
   ``` | ```yaml
   global:
     scrape_interval: 60s
     scrape_timeout: 40s
   scrape_configs:
     - job_name: Docker Scout policy
       metrics_path: /v1/exporter/org/ORG/metrics
       scheme: https
       static_configs:
         - targets:
             - api.scout.docker.com
       authorization:
         type: Bearer
         credentials_file: /etc/prometheus/token
   ``` |

4. Start the compose services.

   ```console
   docker compose up -d
   ```

   This command starts two services: the Prometheus server and Grafana. Prometheus scrapes metrics from the Docker Scout endpoint, and Grafana visualizes the metrics using a pre-configured dashboard.

To stop the demo and clean up any resources created, run:

```console
docker compose down -v
```

### [Access to Prometheus](#access-to-prometheus)

After starting the services, you can access the Prometheus expression browser by visiting <http://localhost:9090>. The Prometheus server runs in a Docker container and is accessible on port 9090.

After a few seconds, you should see the metrics endpoint as a target in the Prometheus UI at <http://localhost:9090/targets>.

Docker Scout metrics exporter Prometheus target

### [Viewing the metrics in Grafana](#viewing-the-metrics-in-grafana)

To view the Grafana dashboards, go to <http://localhost:3000/dashboards>, and sign in using the credentials defined in the Docker Compose file (username: `admin`, password: `grafana`).

Vulnerability dashboard in Grafana

Policy dashboard in Grafana

The dashboards are pre-configured to visualize the vulnerability and policy metrics scraped by Prometheus.

## [Datadog](#datadog)

This section describes how to scrape the metrics endpoint using Datadog. Datadog pulls data for monitoring by running a customizable [agent](https://docs.datadoghq.com/agent/?tab=Linux) that scrapes available endpoints for any exposed metrics. The OpenMetrics and Prometheus checks are included in the agent, so you don’t need to install anything else on your containers or hosts.

This guide assumes you have a Datadog account and a Datadog API Key. Refer to the [Datadog documentation](https://docs.datadoghq.com/agent) to get started.

### [Configure the Datadog agent](#configure-the-datadog-agent)

To start collecting the metrics, you will need to edit the agent’s configuration file for the OpenMetrics check. If you're running the agent as a container, such file must be mounted at `/etc/datadog-agent/conf.d/openmetrics.d/conf.yaml`.

The following example shows a Datadog configuration that:

* Specifies the OpenMetrics endpoint targeting the `dockerscoutpolicy` Docker organization
* A `namespace` that all collected metrics will be prefixed with
* The [`metrics`](#metrics) you want the agent to scrape (`scout_*`)
* An `auth_token` section for the Datadog agent to authenticate to the Metrics endpoint, using a Docker PAT as a Bearer token.

```yaml
instances:
  - openmetrics_endpoint: "https://api.scout.docker.com/v1/exporter/org/dockerscoutpolicy/metrics"
    namespace: "scout-metrics-exporter"
    metrics:
      - scout_*
    auth_token:
      reader:
        type: file
        path: /var/run/secrets/scout-metrics-exporter/token
      writer:
        type: header
        name: Authorization
        value: Bearer TOKEN
```

> Important
>
> Do not replace the `<TOKEN>` placeholder in the previous configuration example. It must stay as it is. Only make sure the Docker PAT is correctly mounted into the Datadog agent in the specified filesystem path. Save the file as `conf.yaml` and restart the agent.

When creating a Datadog agent configuration of your own, make sure to edit the `openmetrics_endpoint` property to target your organization, by replacing `dockerscoutpolicy` with the namespace of your Docker organization.

### [Datadog sample project](#datadog-sample-project)

If you don't have a Datadog server set up, you can run a [sample project](https://github.com/dockersamples/scout-metrics-exporter) using Docker Compose. The sample includes a Datadog agent, running as a container, that scrapes metrics for a Docker organization enrolled in Docker Scout. This sample project assumes that you have a Datadog account, an API key, and a Datadog site.

1. Clone the starter template for bootstrapping a Datadog Compose service for scraping the Docker Scout metrics endpoint:

   ```console
   $ git clone git@github.com:dockersamples/scout-metrics-exporter.git
   $ cd scout-metrics-exporter/datadog
   ```

2. [Create a Docker access token](https://docs.docker.com/security/access-tokens/) and store it in a plain text file at `/datadog/token` under the template directory.

   token

   ```plaintext
   $ echo $DOCKER_PAT > ./token
   ```

3. In the `/datadog/compose.yaml` file, update the `DD_API_KEY` and `DD_SITE` environment variables with the values for your Datadog deployment.

   ```yaml
     datadog-agent:
       container_name: datadog-agent
       image: gcr.io/datadoghq/agent:7
       environment:
         - DD_API_KEY=${DD_API_KEY} # e.g. 1b6b3a42...
         - DD_SITE=${DD_SITE} # e.g. datadoghq.com
         - DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock:ro
         - ./conf.yaml:/etc/datadog-agent/conf.d/openmetrics.d/conf.yaml:ro
         - ./token:/var/run/secrets/scout-metrics-exporter/token:ro
   ```

   The `volumes` section mounts the Docker socket from the host to the container. This is required to obtain an accurate hostname when running as a container ([more details here](https://docs.datadoghq.com/agent/troubleshooting/hostname_containers/)).

   It also mounts the agent's config file and the Docker access token.

4. Edit the `/datadog/config.yaml` file by replacing the placeholder `<ORG>` in the `openmetrics_endpoint` property with the namespace of the Docker organization that you want to collect metrics for.

   ```yaml
   instances:
     - openmetrics_endpoint: "https://api.scout.docker.com/v1/exporter/org/<ORG>/metrics"
       namespace: "scout-metrics-exporter"
   # ...
   ```

5. Start the Compose services.

   ```console
   docker compose up -d
   ```

If configured properly, you should see the OpenMetrics check under Running Checks when you run the agent’s status command whose output should look similar to:

```text
openmetrics (4.2.0)
-------------------
  Instance ID: openmetrics:scout-prometheus-exporter:6393910f4d92f7c2 [OK]
  Configuration Source: file:/etc/datadog-agent/conf.d/openmetrics.d/conf.yaml
  Total Runs: 1
  Metric Samples: Last Run: 236, Total: 236
  Events: Last Run: 0, Total: 0
  Service Checks: Last Run: 1, Total: 1
  Average Execution Time : 2.537s
  Last Execution Date : 2024-05-08 10:41:07 UTC (1715164867000)
  Last Successful Execution Date : 2024-05-08 10:41:07 UTC (1715164867000)
```

For a comprehensive list of options, take a look at this [example config file](https://github.com/DataDog/integrations-core/blob/master/openmetrics/datadog_checks/openmetrics/data/conf.yaml.example) for the generic OpenMetrics check.

### [Visualizing your data](#visualizing-your-data)

Once the agent is configured to grab Prometheus metrics, you can use them to build comprehensive Datadog graphs, dashboards, and alerts.

Go into your [Metric summary page](https://app.datadoghq.com/metric/summary?filter=scout_prometheus_exporter) to see the metrics collected from this example. This configuration will collect all exposed metrics starting with `scout_` under the namespace `scout_metrics_exporter`.

The following screenshots show examples of a Datadog dashboard containing graphs about vulnerability and policy compliance for a specific [stream](#stream).

> The reason why the lines in the graphs look flat is due to the own nature of vulnerabilities (they don't change too often) and the short time interval selected in the date picker.

## [Scrape interval](#scrape-interval)

By default, Prometheus and Datadog scrape metrics at a 15 second interval. Because of the own nature of vulnerability data, the metrics exposed through this API are unlikely to change at a high frequency. For this reason, the metrics endpoint has a 60-minute cache by default, which means a scraping interval of 60 minutes or higher is recommended. If you set the scrape interval to less than 60 minutes, you will see the same data in the metrics for multiple scrapes during that time window.

To change the scrape interval:

* Prometheus: set the `scrape_interval` field in the Prometheus configuration file at the global or job level.
* Datadog: set the `min_collection_interval` property in the Datadog agent configuration file, see [Datadog documentation](https://docs.datadoghq.com/developers/custom_checks/write_agent_check/#updating-the-collection-interval).

## [Revoke an access token](#revoke-an-access-token)

If you suspect that your PAT has been compromised or is no longer needed, you can revoke it at any time. To revoke a PAT, follow the steps in the [Create and manage access tokens](https://docs.docker.com/security/access-tokens/).

Revoking a PAT immediately invalidates the token, and prevents Prometheus from scraping metrics using that token. You will need to create a new PAT and update the Prometheus configuration to use the new token.

----
url: https://docs.docker.com/dhi/how-to/explore/
----

# Search and evaluate Docker Hardened Images

***

Table of contents

***

Docker Hardened Images (DHI) are a curated set of secure, production-ready container images designed to provide enhanced security, minimized attack surfaces, and production-ready foundations for your applications.

This page explains how to search available DHI repositories, review image metadata, examine variant details, and compare images to evaluate security improvements and differences.

## [Search the catalog](#search-the-catalog)

You can browse, search, or filter images by category in the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog) on Docker Hub.

Alternatively, use the [DHI CLI](/reference/cli/docker/dhi/), included in [Docker Desktop](/desktop/), to browse the catalog from the command line:

```console
$ docker dhi catalog list
```

Filter by image type, name, or compliance requirements:

```console
$ docker dhi catalog list --type image
$ docker dhi catalog list --filter python
$ docker dhi catalog list --fips
$ docker dhi catalog list --stig
```

### [Repository details](#repository-details)

When you select a repository from the catalog, the repository details page provides the following:

* Overview: A brief explanation of the image.
* Guides: Several guides on how to use the image and migrate your existing application.
* Images: Select this option to [view image variants](#image-variants).
* Security summary: Select a tag name to view a quick security summary, including package count, total known vulnerabilities, and Scout health score.
* Recently pushed tags: A list of recently updated image variants and when they were last updated.
* Use this image: After selecting an image variant, you can select this option to view instructions on how to pull and use the image variant.

To view repository details from the command line, use the DHI CLI:

```console
$ docker dhi catalog get python
```

This shows available tags, CVE counts, and other repository metadata.

### [Image variants](#image-variants)

Tags are used to identify image variants. Image variants are different builds of the same application or framework tailored for different use-cases.

From the [repository details](#repository-details), select **Images** to view the available image variants.

The **Images** page provides a table with the following columns:

* Image version: The image name with its base distribution (for example, `debian 13`) and associated tags.
* Type: The support lifecycle status of the variant.
* Compliance: Relevant compliance designations. For example, `CIS`, `FIPS`, or `STIG (100%)`.
* Package manager: Whether a package manager is available. A checkmark indicates a package manager is present (for example, `apt` or `apk`), a dash indicates none.
* Shell: Whether a shell is available. A checkmark indicates a shell is present (for example, `bash` or `busybox`), a dash indicates none.
* User: The user that the container runs as. For example, `root` or `nonroot (65532)`.
* Last pushed: When the image variant was last updated.
* Vulnerabilities: Vulnerability counts by severity level.
* Health: The Scout health score. Select the score to view more details.

### [Image variant details](#image-variant-details)

On the [**Images** page](#image-variants), select an image version from the table to view detailed information about that specific variant.

The image variant details page provides the following information:

* Packages: A list of all packages included in the image variant. This section includes details about each package, including its name, version, distribution, and licensing information.

* Specifications: The specifications for the image variant include the following key details:

  * Source & Build Information: The image is built from the Dockerfile found here and the Git commit.
  * Build parameters
  * Entrypoint
  * CMD
  * User
  * Working directory
  * Environment Variables
  * Labels
  * Platform

* Vulnerabilities: The vulnerabilities section provides a list of known CVEs for the image variant, including:

  * CVE
  * Severity
  * Package
  * Fix version
  * Last detected
  * Status
  * Suppressed CVEs

* Attestations: Variants include comprehensive security attestations to verify the image's build process, contents, and security posture. These attestations are signed and can be verified using cosign. For a list of available attestations, see [Attestations](https://docs.docker.com/dhi/core-concepts/attestations/).

## [Compare and evaluate images](#compare-and-evaluate-images)

Docker Scout lets you analyze the differences between two images. Comparing a DHI to a standard image helps you understand the security improvements, package differences, and overall benefits of adopting hardened images.

Comparison is useful for:

* Evaluating the security improvements when migrating from a standard image to a DHI
* Understanding package and vulnerability differences between image variants
* Assessing the impact of customizations or updates

### [Prerequisites](#prerequisites)

Before comparing images:

* Install [Docker Desktop](/desktop/) to use Docker Scout comparison features.

* Sign in to the registries containing the images you want to compare. Sign in to `dhi.io` for Docker Hardened Images:

  ```console
  $ docker login dhi.io
  ```

### [Basic comparison](#basic-comparison)

To compare a Docker Hardened Image with another image, use the [`docker scout compare`](/reference/cli/docker/scout/compare/) command:

```console
$ docker scout compare dhi.io/<image>:<tag> \
    --to <comparison-image>:<tag> \
    --platform <platform>
```

For example, to compare a DHI Node.js image with the official Node.js image:

```console
$ docker scout compare dhi.io/node:22-debian13 \
    --to node:22 \
    --platform linux/amd64
```

The output shows an overview at the top with key comparison metrics, followed by detailed package and vulnerability information. Example overview:

```console
  ## Overview

                      │                    Analyzed Image                     │              Comparison Image
  ────────────────────┼───────────────────────────────────────────────────────┼─────────────────────────────────────────────
    Target            │  dhi.io/node:22-debian13                              │  node:22
      digest          │  55d471f61608                                         │  9ee3220f602f
      platform        │ linux/amd64                                           │ linux/amd64
      vulnerabilities │    0C     0H     0M     0L                            │    0C     1H     3M   153L     4?
                      │           -1     -3   -153     -4                     │
      size            │ 41 MB (-367 MB)                                       │ 408 MB
      packages        │ 19 (-726)                                             │ 745
```

### [Filter unchanged packages](#filter-unchanged-packages)

To focus only on the differences and ignore unchanged packages, use the `--ignore-unchanged` flag:

```console
$ docker scout compare dhi.io/node:22-debian13 \
    --to node:22 \
    --platform linux/amd64 \
    --ignore-unchanged
```

This output highlights only the packages and vulnerabilities that differ between the two images, making it easier to identify the security improvements and changes.

----
url: https://docs.docker.com/reference/cli/docker/node/
----

# docker node

***

| Description | Manage Swarm nodes |
| ----------- | ------------------ |
| Usage       | `docker node`      |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Manage nodes.

## [Subcommands](#subcommands)

| Command                                                                             | Description                                                       |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [`docker node demote`](https://docs.docker.com/reference/cli/docker/node/demote/)   | Demote one or more nodes from manager in the swarm                |
| [`docker node inspect`](https://docs.docker.com/reference/cli/docker/node/inspect/) | Display detailed information on one or more nodes                 |
| [`docker node ls`](https://docs.docker.com/reference/cli/docker/node/ls/)           | List nodes in the swarm                                           |
| [`docker node promote`](https://docs.docker.com/reference/cli/docker/node/promote/) | Promote one or more nodes to manager in the swarm                 |
| [`docker node ps`](https://docs.docker.com/reference/cli/docker/node/ps/)           | List tasks running on one or more nodes, defaults to current node |
| [`docker node rm`](https://docs.docker.com/reference/cli/docker/node/rm/)           | Remove one or more nodes from the swarm                           |
| [`docker node update`](https://docs.docker.com/reference/cli/docker/node/update/)   | Update a node                                                     |

----
url: https://docs.docker.com/reference/cli/docker/scout/push/
----

# docker scout push

***

| Description | Push an image or image index to Docker Scout |
| ----------- | -------------------------------------------- |
| Usage       | `docker scout push IMAGE`                    |

## [Description](#description)

The `docker scout push` command lets you push an image or analysis result to Docker Scout.

## [Options](#options)

| Option         | Default | Description                                                        |
| -------------- | ------- | ------------------------------------------------------------------ |
| `--author`     |         | Name of the author of the image                                    |
| `--dry-run`    |         | Do not push the image but process it                               |
| `--org`        |         | Namespace of the Docker organization to which image will be pushed |
| `-o, --output` |         | Write the report to a file                                         |
| `--platform`   |         | Platform of image to be pushed                                     |
| `--sbom`       |         | Create and upload SBOMs                                            |
| `--secrets`    |         | Scan for secrets in the image                                      |
| `--timestamp`  |         | Timestamp of image or tag creation                                 |

## [Examples](#examples)

### [Push an image to Docker Scout](#push-an-image-to-docker-scout)

```console
$ docker scout push --org my-org registry.example.com/repo:tag
```

----
url: https://docs.docker.com/desktop/setup/install/windows-permission-requirements/
----

# Understand permission requirements for Windows

***

Table of contents

***

This page contains information about the permission requirements for running and installing Docker Desktop on Windows, the functionality of the privileged helper process `com.docker.service`, and the reasoning behind this approach.

It also provides clarity on running containers as `root` as opposed to having `Administrator` access on the host and the privileges of Docker Engine and Windows containers.

Docker Desktop on Windows is designed with security in mind. Administrative rights are only required when absolutely necessary.

## [Permission requirements](#permission-requirements)

The permissions required to install and run Docker Desktop depend on which [installation mode](https://docs.docker.com/desktop/setup/install/windows-install/#installation-modes) you use.

### [Per-user installation (Beta)](#per-user-installation-beta)

In per-user mode, Docker Desktop installs to `%LOCALAPPDATA%\Programs\DockerDesktop` and writes only to current-user registry keys (`HKCU`). This means:

* No administrator privileges are required to install or update Docker Desktop.
* After installation, Docker Desktop can be run without administrator privileges.
* Some settings marked **Requires password** in **Settings** still require elevation. When you change one of these settings and select **Apply**, Docker Desktop opens a UAC prompt for administrator access.

Per-user installation does not install the privileged helper service `com.docker.service` automatically. As a result, features that depend on it, such as the Hyper-V backend and Windows containers, are not available. For most users this is not a limitation, as the WSL 2 backend covers the majority of use cases.

### [All-users installation](#all-users-installation)

In all-users mode, Docker Desktop installs to `C:\Program Files\Docker\Docker` and writes to Local Machine registry keys (`HKLM`). Both locations require administrator privileges to modify, so:

* Administrator privileges are required to install and update Docker Desktop.
* On installation you receive a UAC prompt which allows the privileged helper service `com.docker.service` to be installed.
* After installation, Docker Desktop can be run without administrator privileges.

Running Docker Desktop without the privileged helper does not require users to have `docker-users` group membership. However, some features that require privileged operations will have this requirement.

If you performed the installation, you are automatically added to the `docker-users` group, but other users must be added manually. This allows the administrator to control who has access to features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers.

When Docker Desktop launches, all non-privileged named pipes are created so that only the following users can access them:

* The user that launched Docker Desktop.
* Members of the local `Administrators` group.
* The `LOCALSYSTEM` account.

### [Operations that always require elevation](#operations-that-always-require-elevation)

The following require administrator privileges regardless of installation mode.

* Enabling WSL 2 for the first time: WSL 2 must be enabled on the machine before Docker Desktop can run. This is a one-time, per-machine operation. Once WSL 2 is enabled, it does not need to be enabled again for subsequent Docker Desktop installs or updates.
* Settings marked **Requires password**: Certain Docker Desktop settings affect system-level configuration and require administrator credentials to apply. These are clearly marked **Requires password**. When you change one of these settings and select **Apply**, Docker Desktop prompts for administrator credentials.

## [Privileged helper](#privileged-helper)

Docker Desktop needs to perform a limited set of privileged operations which are conducted by the privileged helper process `com.docker.service`. This approach allows, following the principle of least privilege, `Administrator` access to be used only for the operations for which it is absolutely necessary, while still being able to use Docker Desktop as an unprivileged user.

> Note
>
> `com.docker.service` is only installed in all-users installation mode. It is not used in per-user installation, which instead relies solely on the WSL 2 backend and does not support Hyper-V or Windows containers.

The privileged helper `com.docker.service` is a Windows service which runs in the background with `SYSTEM` privileges. It listens on the named pipe `//./pipe/dockerBackendV2`. The developer runs the Docker Desktop application, which connects to the named pipe and sends commands to the service. This named pipe is protected, and only users that are part of the `docker-users` group can have access to it.

The service performs the following functionalities:

* Ensuring that `kubernetes.docker.internal` is defined in the Win32 hosts file. Defining the DNS name `kubernetes.docker.internal` allows Docker to share Kubernetes contexts with containers.
* Ensuring that `host.docker.internal` and `gateway.docker.internal` are defined in the Win32 hosts file. They point to the host local IP address and allow an application to resolve the host IP using the same name from either the host itself or a container.
* Securely caching the Registry Access Management policy which is read-only for the developer.
* Creating the Hyper-V VM `"DockerDesktopVM"` and managing its lifecycle - starting, stopping, and destroying it. The VM name is hard coded in the service code so the service cannot be used for creating or manipulating any other VMs.
* Moving the VHDX file or folder.
* Starting and stopping the Windows Docker engine and querying whether it's running.
* Deleting all Windows containers data files.
* Checking if Hyper-V is enabled.
* Checking if the bootloader activates Hyper-V.
* Checking if required Windows features are both installed and enabled.
* Conducting healthchecks and retrieving the version of the service itself.

The service start mode depends on which container engine is selected, and, for WSL, on whether it is needed to maintain `host.docker.internal` and `gateway.docker.internal` in the Win32 hosts file. This is controlled by a setting under `Use the WSL 2 based engine` in the settings page. When this is set, WSL engine behaves the same as Hyper-V. So:

* With Windows containers, or Hyper-v Linux containers, the service is started when the system boots and runs all the time, even when Docker Desktop isn't running. This is required so you can launch Docker Desktop without admin privileges.
* With WSL2 Linux containers, the service isn't necessary and therefore doesn't run automatically when the system boots. When you switch to Windows containers or Hyper-V Linux containers, or choose to maintain `host.docker.internal` and `gateway.docker.internal` in the Win32 hosts file, a UAC prompt appears asking you to accept the privileged operation to start the service. If accepted, the service is started and set to start automatically upon the next Windows boot.

## [Containers running as root within the Linux VM](#containers-running-as-root-within-the-linux-vm)

The Linux Docker daemon and containers run in a minimal, special-purpose Linux VM managed by Docker. It is immutable so you can’t extend it or change the installed software. This means that although containers run by default as `root`, this doesn't allow altering the VM and doesn't grant `Administrator` access to the Windows host machine. The Linux VM serves as a security boundary and limits what resources from the host can be accessed. File sharing uses a user-space crafted file server and any directories from the host bind mounted into Docker containers still retain their original permissions. Containers don't have access to any host files beyond those explicitly shared.

## [Enhanced Container Isolation](#enhanced-container-isolation)

In addition, Docker Desktop supports [Enhanced Container Isolation mode](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) (ECI), available to Business customers only, which further secures containers without impacting developer workflows.

ECI automatically runs all containers within a Linux user-namespace, such that root in the container is mapped to an unprivileged user inside the Docker Desktop VM. ECI uses this and other advanced techniques to further secure containers within the Docker Desktop Linux VM, such that they are further isolated from the Docker daemon and other services running inside the VM.

## [Windows containers](#windows-containers)

> Warning
>
> Enabling Windows containers has important security implications.

> Note
>
> Windows containers are only supported in all-users installation mode. They are not available when Docker Desktop is installed per-user. See [Installation modes](https://docs.docker.com/desktop/setup/install/windows-install/#installation-modes).

Unlike the Linux Docker Engine and containers which run in a VM, Windows containers are implemented using operating system features, and run directly on the Windows host. If you enable Windows containers during installation, the `ContainerAdministrator` user used for administration inside the container is a local administrator on the host machine. Enabling Windows containers during installation makes it so that members of the `docker-users` group are able to elevate to administrators on the host. For organizations who don't want their developers to run Windows containers, a `-–no-windows-containers` installer flag is available to disable their use.

## [Networking](#networking)

For network connectivity, Docker Desktop uses a user-space process (`vpnkit`), which inherits constraints like firewall rules, VPN, HTTP proxy properties etc. from the user that launched it.

----
url: https://docs.docker.com/docker-hub/repos/archive/
----

# Archive or unarchive a repository

***

Table of contents

***

You can archive a repository on Docker Hub to mark it as read-only and indicate that it's no longer actively maintained. This helps prevent the use of outdated or unsupported images in workflows. Archived repositories can also be unarchived if needed.

Docker Hub highlights repositories that haven't been updated in over a year by displaying an icon ( ) next to them on the [**Repositories** page](https://hub.docker.com/repositories/). Consider reviewing these highlighted repositories and archiving them if necessary.

When a repository is archived, the following occurs:

* The repository information can't be modified.
* New images can't be pushed to the repository.
* An **Archived** label is displayed on the public repository page.
* Users can still pull the images.

You can unarchive an archived repository to remove the archived state. When unarchived, the following occurs:

* The repository information can be modified.
* New images can be pushed to the repository.
* The **Archived** label is removed on the public repository page.

## [Archive a repository](#archive-a-repository)

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Settings** tab.

5. Select **Archive repository**.

6. Enter the name of your repository to confirm.

7. Select **Archive**.

## [Unarchive a repository](#unarchive-a-repository)

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Settings** tab.

5. Select **Unarchive repository**.

----
url: https://docs.docker.com/reference/cli/docker/desktop/engine/
----

# docker desktop engine

***

| Description | Commands to list and switch containers (Windows only) |
| ----------- | ----------------------------------------------------- |
| Usage       | `docker desktop engine`                               |

## [Subcommands](#subcommands)

| Command                                                                                         | Description                                          |
| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [`docker desktop engine ls`](https://docs.docker.com/reference/cli/docker/desktop/engine/ls/)   | List available engines (Windows only)                |
| [`docker desktop engine use`](https://docs.docker.com/reference/cli/docker/desktop/engine/use/) | Switch to Windows or Linux containers (Windows only) |

----
url: https://docs.docker.com/engine/release-notes/17.12/
----

# Docker Engine 17.12 release notes

***

Table of contents

***

## [17.12.1-ce](#17121-ce)

2018-02-27

### [Client](#client)

* Fix `node-generic-resource` typo [moby/moby#35970](https://github.com/moby/moby/pull/35970) and [moby/moby#36125](https://github.com/moby/moby/pull/36125)

- Return errors from daemon on stack deploy configs create/update [docker/cli#757](https://github.com/docker/cli/pull/757)

### [Logging](#logging)

* awslogs: fix batch size calculation for large logs [moby/moby#35726](https://github.com/moby/moby/pull/35726)

- Support a proxy in splunk log driver [moby/moby#36220](https://github.com/moby/moby/pull/36220)

### [Networking](#networking)

* Fix ingress network when upgrading from 17.09 to 17.12 [moby/moby#36003](https://github.com/moby/moby/pull/36003)

- Add verbose info to partial overlay ID [moby/moby#35989](https://github.com/moby/moby/pull/35989)

* Fix IPv6 networking being deconfigured if live-restore is being enabled [docker/libnetwork#2043](https://github.com/docker/libnetwork/pull/2043)
* Fix watchMiss thread context [docker/libnetwork#2051](https://github.com/docker/libnetwork/pull/2051)

### [Packaging](#packaging)

* Set TasksMax in docker.service [docker/docker-ce-packaging#78](https://github.com/docker/docker-ce-packaging/pull/78)

### [Runtime](#runtime)

* Bump Golang to 1.9.4
* Bump containerd to 1.0.1

- Fix dockerd not being able to reconnect to containerd when it is restarted [moby/moby#36173](https://github.com/moby/moby/pull/36173)
- Fix containerd events from being processed twice [moby/moby#35891](https://github.com/moby/moby/issues/35891)
- Fix vfs graph driver failure to initialize because of failure to setup fs quota [moby/moby#35827](https://github.com/moby/moby/pull/35827)
- Fix regression of health check not using container's working directory [moby/moby#35845](https://github.com/moby/moby/pull/35845)
- Honor `DOCKER_RAMDISK` with containerd 1.0 [moby/moby#35957](https://github.com/moby/moby/pull/35957)
- Update runc to fix hang during start and exec [moby/moby#36097](https://github.com/moby/moby/pull/36097)
- Windows: Vendor of Microsoft/hcsshim @v.0.6.8 partial fix for import layer failing [moby/moby#35924](https://github.com/moby/moby/pull/35924)

* Do not make graphdriver homes private mounts [moby/moby#36047](https://github.com/moby/moby/pull/36047)
* Use rslave propagation for mounts from daemon root [moby/moby#36055](https://github.com/moby/moby/pull/36055)
* Set daemon root to use shared mount propagation [moby/moby#36096](https://github.com/moby/moby/pull/36096)
* Validate that mounted paths exist when container is started, not just during creation [moby/moby#35833](https://github.com/moby/moby/pull/35833)
* Add `REMOVE` and `ORPHANED` to TaskState [moby/moby#36146](https://github.com/moby/moby/pull/36146)

- Fix issue where network inspect does not show Created time for networks in swarm scope [moby/moby#36095](https://github.com/moby/moby/pull/36095)

* Nullify container read write layer upon release [moby/moby#36130](https://github.com/moby/moby/pull/36160) and [moby/moby#36343](https://github.com/moby/moby/pull/36242)

### [Swarm](#swarm)

* Remove watchMiss from swarm mode [docker/libnetwork#2047](https://github.com/docker/libnetwork/pull/2047)

### [Known Issues](#known-issues)

* Health check no longer uses the container's working directory [moby/moby#35843](https://github.com/moby/moby/issues/35843)
* Errors not returned from client in stack deploy configs [moby/moby#757](https://github.com/docker/cli/pull/757)
* Docker cannot use memory limit when using systemd options [moby/moby#35123](https://github.com/moby/moby/issues/35123)

## [17.12.0-ce](#17120-ce)

2017-12-27

### [Known Issues](#known-issues-1)

* AWS logs batch size calculation [moby/moby#35726](https://github.com/moby/moby/pull/35726)
* Health check no longer uses the container's working directory [moby/moby#35843](https://github.com/moby/moby/issues/35843)
* Errors not returned from client in stack deploy configs [moby/moby#757](https://github.com/docker/cli/pull/757)
* Daemon aborts when project quota fails [moby/moby#35827](https://github.com/moby/moby/pull/35827)
* Docker cannot use memory limit when using systemd options [moby/moby#35123](https://github.com/moby/moby/issues/35123)

### [Builder](#builder)

* Fix build cache hash for broken symlink [moby/moby#34271](https://github.com/moby/moby/pull/34271)
* Fix long stream sync [moby/moby#35404](https://github.com/moby/moby/pull/35404)
* Fix dockerfile parser failing silently on long tokens [moby/moby#35429](https://github.com/moby/moby/pull/35429)

### [Client](#client-1)

* Remove secret/config duplication in cli/compose [docker/cli#671](https://github.com/docker/cli/pull/671)
* Add `--local` flag to `docker trust sign` [docker/cli#575](https://github.com/docker/cli/pull/575)
* Add `docker trust inspect` [docker/cli#694](https://github.com/docker/cli/pull/694)

- Add `name` field to secrets and configs to allow interpolation in Compose files [docker/cli#668](https://github.com/docker/cli/pull/668)
- Add `--isolation` for setting swarm service isolation mode [docker/cli#426](https://github.com/docker/cli/pull/426)

* Remove deprecated "daemon" subcommand [docker/cli#689](https://github.com/docker/cli/pull/689)

- Fix behaviour of `rmi -f` with unexpected errors [docker/cli#654](https://github.com/docker/cli/pull/654)

* Integrated Generic resource in service create [docker/cli#429](https://github.com/docker/cli/pull/429)

- Fix external networks in stacks [docker/cli#743](https://github.com/docker/cli/pull/743)

* Remove support for referencing images by image shortid [docker/cli#753](https://github.com/docker/cli/pull/753) and [moby/moby#35790](https://github.com/moby/moby/pull/35790)
* Use commit-sha instead of tag for containerd [moby/moby#35770](https://github.com/moby/moby/pull/35770)

### [Documentation](#documentation)

* Update API version history for 1.35 [moby/moby#35724](https://github.com/moby/moby/pull/35724)

### [Logging](#logging-1)

* Logentries driver line-only=true \[]byte output fix [moby/moby#35612](https://github.com/moby/moby/pull/35612)
* Logentries line-only logopt fix to maintain backwards compatibility [moby/moby#35628](https://github.com/moby/moby/pull/35628)

- Add `--until` flag for docker logs [moby/moby#32914](https://github.com/moby/moby/pull/32914)
- Add gelf log driver plugin to Windows build [moby/moby#35073](https://github.com/moby/moby/pull/35073)

* Set timeout on splunk batch send [moby/moby#35496](https://github.com/moby/moby/pull/35496)
* Update Graylog2/go-gelf [moby/moby#35765](https://github.com/moby/moby/pull/35765)

### [Networking](#networking-1)

* Move load balancer sandbox creation/deletion into libnetwork [moby/moby#35422](https://github.com/moby/moby/pull/35422)
* Only chown network files within container metadata [moby/moby#34224](https://github.com/moby/moby/pull/34224)
* Restore error type in FindNetwork [moby/moby#35634](https://github.com/moby/moby/pull/35634)

- Fix consumes MIME type for NetworkConnect [moby/moby#35542](https://github.com/moby/moby/pull/35542)

* Added support for persisting Windows network driver specific options [moby/moby#35563](https://github.com/moby/moby/pull/35563)

- Fix timeout on netlink sockets and watchmiss leak [moby/moby#35677](https://github.com/moby/moby/pull/35677)

* New daemon config for networking diagnosis [moby/moby#35677](https://github.com/moby/moby/pull/35677)

- Clean up node management logic [docker/libnetwork#2036](https://github.com/docker/libnetwork/pull/2036)
- Allocate VIPs when endpoints are restored [docker/swarmkit#2474](https://github.com/docker/swarmkit/pull/2474)

### [Runtime](#runtime-1)

* Update to containerd v1.0.0 [moby/moby#35707](https://github.com/moby/moby/pull/35707)
* Have VFS graphdriver use accelerated in-kernel copy [moby/moby#35537](https://github.com/moby/moby/pull/35537)
* Introduce `workingdir` option for docker exec [moby/moby#35661](https://github.com/moby/moby/pull/35661)
* Bump Go to 1.9.2 [moby/moby#33892](https://github.com/moby/moby/pull/33892) [docker/cli#716](https://github.com/docker/cli/pull/716)
* `/dev` should not be readonly with `--readonly` flag [moby/moby#35344](https://github.com/moby/moby/pull/35344)

- Add custom build-time Graphdrivers priority list [moby/moby#35522](https://github.com/moby/moby/pull/35522)

* LCOW: CLI changes to add platform flag - pull, run, create and build [docker/cli#474](https://github.com/docker/cli/pull/474)
* Fix width/height on Windows for `docker exec` [moby/moby#35631](https://github.com/moby/moby/pull/35631)
* Detect overlay2 support on pre-4.0 kernels [moby/moby#35527](https://github.com/moby/moby/pull/35527)
* Devicemapper: remove container rootfs mountPath after umount [moby/moby#34573](https://github.com/moby/moby/pull/34573)
* Disallow overlay/overlay2 on top of NFS [moby/moby#35483](https://github.com/moby/moby/pull/35483)

- Fix potential panic during plugin set. [moby/moby#35632](https://github.com/moby/moby/pull/35632)
- Fix some issues with locking on the container [moby/moby#35501](https://github.com/moby/moby/pull/35501)
- Fixup some issues with plugin refcounting [moby/moby#35265](https://github.com/moby/moby/pull/35265)

* Add missing lock in ProcessEvent [moby/moby#35516](https://github.com/moby/moby/pull/35516)
* Add vfs quota support [moby/moby#35231](https://github.com/moby/moby/pull/35231)

- Skip empty directories on prior graphdriver detection [moby/moby#35528](https://github.com/moby/moby/pull/35528)
- Skip xfs quota tests when running in user namespace [moby/moby#35526](https://github.com/moby/moby/pull/35526)

* Added SubSecondPrecision to config option. [moby/moby#35529](https://github.com/moby/moby/pull/35529)

- Update fsnotify to fix deadlock in removing watch [moby/moby#35453](https://github.com/moby/moby/pull/35453)

* Fix "duplicate mount point" when `--tmpfs /dev/shm` is used [moby/moby#35467](https://github.com/moby/moby/pull/35467)
* Fix honoring tmpfs-size for user `/dev/shm` mount [moby/moby#35316](https://github.com/moby/moby/pull/35316)
* Fix EBUSY errors under overlayfs and v4.13+ kernels [moby/moby#34948](https://github.com/moby/moby/pull/34948)

- Container: protect health monitor channel [moby/moby#35482](https://github.com/moby/moby/pull/35482)
- Container: protect the health status with mutex [moby/moby#35517](https://github.com/moby/moby/pull/35517)
- Container: update real-time resources [moby/moby#33731](https://github.com/moby/moby/pull/33731)
- Create labels when volume exists only remotely [moby/moby#34896](https://github.com/moby/moby/pull/34896)

* Fix leaking container/exec state [moby/moby#35484](https://github.com/moby/moby/pull/35484)

- Disallow using legacy (v1) registries [moby/moby#35751](https://github.com/moby/moby/pull/35751) and [docker/cli#747](https://github.com/docker/cli/pull/747)

* Windows: Fix case insensitive filename matching against builder cache [moby/moby#35793](https://github.com/moby/moby/pull/35793)
* Fix race conditions around process handling and error checks [moby/moby#35809](https://github.com/moby/moby/pull/35809)

- Ensure containers are stopped on daemon startup [moby/moby#35805](https://github.com/moby/moby/pull/35805)
- Follow containerd namespace conventions [moby/moby#35812](https://github.com/moby/moby/pull/35812)

### [Swarm Mode](#swarm-mode)

* Added support for swarm service isolation mode [moby/moby#34424](https://github.com/moby/moby/pull/34424)

- Fix task clean up for tasks that are complete [docker/swarmkit#2477](https://github.com/docker/swarmkit/pull/2477)

### [Packaging](#packaging-1)

* Add Packaging for Fedora 27 [docker/docker-ce-packaging#59](https://github.com/docker/docker-ce-packaging/pull/59)

- Change default versioning scheme to 0.0.0-dev unless specified for packaging [docker/docker-ce-packaging#67](https://github.com/docker/docker-ce-packaging/pull/67)
- Pass Version to engine static builds [docker/docker-ce-packaging#70](https://github.com/docker/docker-ce-packaging/pull/70)

* Added support for aarch64 on Debian (stretch/jessie) and Ubuntu Zesty or newer [docker/docker-ce-packaging#35](https://github.com/docker/docker-ce-packaging/pull/35)

----
url: https://docs.docker.com/reference/cli/docker/compose/stats/
----

# docker compose stats

***

| Description | Display a live stream of container(s) resource usage statistics |
| ----------- | --------------------------------------------------------------- |
| Usage       | `docker compose stats [OPTIONS] [SERVICE]`                      |

## [Description](#description)

Display a live stream of container(s) resource usage statistics

## [Options](#options)

| Option        | Default | Description                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-a, --all`   |         | Show all containers (default shows just running)                                                                                                                                                                                                                                                                                                                                               |
| `--format`    |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/engine/cli/formatting/> for more information about formatting output with templates |
| `--no-stream` |         | Disable streaming stats and only pull the first result                                                                                                                                                                                                                                                                                                                                         |
| `--no-trunc`  |         | Do not truncate output                                                                                                                                                                                                                                                                                                                                                                         |

----
url: https://docs.docker.com/enterprise/security/domain-management/
----

# Add and manage domains

***

Table of contents

***

Subscription: Business

For: Administrators

Domain management lets you add and verify domains for your organization, then enable auto-provisioning to automatically add users when they sign in with email addresses that match your verified domains. This approach simplifies user management, ensures consistent security settings, and reduces the risk of unmanaged users accessing Docker without visibility or control.

This page provides steps to add and delete domains, configure auto-provisioning, and audit uncaptured users.

## [Add and verify a domain](#add-and-verify-a-domain)

Adding a domain requires verification to confirm ownership. The verification process uses DNS records to prove you control the domain.

### [Add a domain](#add-a-domain)

1. Sign in to [Docker Home](https://app.docker.com) and select your organization. If your organization is part of a company, select the company and configure the domain for the organization at the company level.
2. Select **Admin Console**, then **Domain management**.
3. Select **Add a domain**.
4. Enter your domain and select **Add domain**.
5. In the pop-up modal, copy the **TXT Record Value** to verify your domain.

### [Verify a domain](#verify-a-domain)

Verification confirms that you own the domain by adding a TXT record to your Domain Name System (DNS) host. It can take up to 72 hours for the DNS change to propagate. Docker automatically checks for the record and confirms ownership once the change is recognized.

> Tip
>
> The record name field determines where the TXT record is added in your domain (root or subdomain). For root domains like `example.com`, use `@` or leave the record name empty, depending on your provider. Don't enter values like docker, `docker-verification`, `www`, or your domain name, as these may direct to the wrong place. Check your DNS provider's documentation to verify record name requirements.

Follow the steps for your DNS provider to add the **TXT Record Value**. If your provider isn't listed, use the steps for "Other providers":

1. Add your TXT record to AWS by following [Creating records by using the Amazon Route 53 console](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-creating.html).
2. Wait up to 72 hours for TXT record verification.
3. Return to the **Domain management** page of the [Admin Console](https://app.docker.com/admin) and select **Verify** next to your domain name.

1) Add your TXT record to Google Cloud DNS by following [Verifying your domain with a TXT record](https://cloud.google.com/identity/docs/verify-domain-txt).
2) Wait up to 72 hours for TXT record verification.
3) Return to the **Domain management** page of the [Admin Console](https://app.docker.com/admin) and select **Verify** next to your domain name.

1. Add your TXT record to GoDaddy by following [Add a TXT record](https://www.godaddy.com/help/add-a-txt-record-19232).
2. Wait up to 72 hours for TXT record verification.
3. Return to the **Domain management** page of the [Admin Console](https://app.docker.com/admin) and select **Verify** next to your domain name.

1) Sign in to your domain host.
2) Add a TXT record to your DNS settings using the **TXT Record Value** from Docker.
3) Wait up to 72 hours for TXT record verification.
4) Return to the **Domain management** page of the [Admin Console](https://app.docker.com/admin) and select **Verify** next to your domain name.

## [Audit domains for uncaptured users](#audit-domains-for-uncaptured-users)

Domain audit identifies uncaptured users. Uncaptured users are Docker users who have authenticated using an email address associated with your verified domains but aren't members of your Docker organization.

### [Limitations](#limitations)

Domain audit can't identify:

* Users who access Docker Desktop without authenticating
* Users who authenticate using an account that doesn't have an email address associated with one of your verified domains

To prevent unidentifiable users from accessing Docker Desktop, [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).

### [Run a domain audit](#run-a-domain-audit)

1. Sign in to [Docker Home](https://app.docker.com) and choose your company.
2. Select **Admin Console**, then **Domain management**.
3. In **Domain audit**, select **Export Users** to export a CSV file of uncaptured users.

The CSV file contains the following columns:

* Name: Docker user's display name
* Username: Docker ID of the user
* Email: Email address of the user

### [Invite uncaptured users](#invite-uncaptured-users)

You can bulk invite uncaptured users to your organization using the exported CSV file. For more information on bulk inviting users, see [Manage organization members](https://docs.docker.com/admin/organization/manage/members/).

## [Auto-provisioning](#auto-provisioning)

[Auto-provisioning](https://docs.docker.com/enterprise/security/provisioning/auto-provisioning/) uses verified domains to associate organization members with email address that match the verified domains. To override auto-provisioning, you can configure one of the two alternative methods:

* [Just-in-Time (JIT)](https://docs.docker.com/enterprise/security/provisioning/just-in-time/) provisioning
* [System for Cross-domain Identity Management (SCIM)](https://docs.docker.com/enterprise/security/provisioning/scim/)

## [Delete a domain](#delete-a-domain)

Deleting a domain removes its TXT record value and disables any associated auto-provisioning.

> Warning
>
> Deleting a domain will disable auto-provisioning for that domain and remove verification. This action cannot be undone.

To delete a domain:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization. If your organization is part of a company, select the company and configure the domain for the organization at the company level.
2. Select **Admin Console**, then **Domain management**.
3. For the domain you want to delete, select the **Actions** menu, then **Delete domain**.
4. To confirm, select **Delete domain** in the pop-up modal.

----
url: https://docs.docker.com/desktop/use-desktop/
----

# Explore Docker Desktop

***

Table of contents

***

When you open Docker Desktop, the Docker Desktop Dashboard displays.

It provides a centralized interface to manage your [containers](https://docs.docker.com/desktop/use-desktop/container/), [images](https://docs.docker.com/desktop/use-desktop/images/), [volumes](https://docs.docker.com/desktop/use-desktop/volumes/), [builds](https://docs.docker.com/desktop/use-desktop/builds/), [Kubernetes resources](https://docs.docker.com/desktop/use-desktop/kubernetes/), and [logs](https://docs.docker.com/desktop/use-desktop/logs/).

In addition, the Docker Desktop Dashboard lets you:

* Use [Gordon](https://docs.docker.com/ai/gordon/), a personal AI assistant embedded in Docker Desktop and the Docker CLI. It's designed to streamline your workflow and help you make the most of the Docker ecosystem.

* Navigate to the **Settings** menu to configure your Docker Desktop settings. Select the **Settings** icon in the Dashboard header.

* Access the **Troubleshoot** menu to debug and perform restart operations. Select the **Troubleshoot** icon in the Dashboard header.

* Be notified of new releases, installation progress updates, and more in the **Notifications center**. Select the bell icon in the bottom-right corner of the Docker Desktop Dashboard to access the notification center.

* Access the **Learning center** from the Dashboard header. It helps you get started with quick in-app walkthroughs and provides other resources for learning about Docker.

  For a more detailed guide about getting started, see [Get started](https://docs.docker.com/get-started/introduction/).

* Access [Docker Hub](https://docs.docker.com/docker-hub/) to search, browse, pull, run, or view details of images.

* Navigate to [Docker Extensions](https://docs.docker.com/extensions/) if you have enabled it.

> Tip
>
> You can customize the left-hand navigation to show only the tabs that matter to you, and hide the ones that don’t. Right-click the left-hand navigation, select **Customize**, and then select, deselect, or re-order the tabs.

## [Docker terminal](#docker-terminal)

From the Docker Dashboard footer, you can use the integrated terminal directly within Docker Desktop.

The integrated terminal:

* Persists your session if you navigate to another part of the Docker Desktop Dashboard and then return.
* Supports copy, paste, search, and clearing your session.

#### [Open the integrated terminal](#open-the-integrated-terminal)

To open the integrated terminal, either:

* Hover over your running container and under the **Actions** column, select the **Show container actions** menu. From the drop-down menu, select **Open in terminal**.
* Or, select the **Terminal** icon located in the bottom-right corner, next to the version number.

To use your external terminal, navigate to the **General** tab in **Settings** and select the **System default** option under **Choose your terminal**.

## [Quick search](#quick-search)

Use Quick Search, which is located in the Docker Dashboard header, to search for:

* Any container or Compose application on your local system. You can see an overview of associated environment variables or perform quick actions, such as start, stop, or delete.

* Public Docker Hub images, local images, and images from remote repositories (private repositories from organizations you're a part of in Hub). Depending on the type of image you select, you can either pull the image by tag, view documentation, go to Docker Hub for more details, or run a new container using the image.

* Extensions. From here, you can learn more about the extension and install it with a single click. Or, if you already have an extension installed, you can open it straight from the search results.

* Any volume. From here you can view the associated container.

* Docs. Find help from Docker's official documentation straight from Docker Desktop.

## [The Docker menu](#the-docker-menu)

Docker Desktop also includes a tray icon, referred to as the Docker menu for quick access.

Select the icon in your taskbar to open options such as:

* **Dashboard**. This takes you to the Docker Desktop Dashboard.
* **Sign in/Sign up**
* **Settings**
* **Check for updates**
* **Troubleshoot**
* **Give feedback**
* **Switch to Windows containers** (if you're on Windows)
* **About Docker Desktop**. Contains information on the versions you are running, and links to the Subscription Service Agreement for example.
* **Docker Hub**
* **Documentation**
* **Extensions**
* **Kubernetes**
* **Restart**
* **Quit Docker Desktop**

----
url: https://docs.docker.com/engine/security/trust/trust_sandbox/
----

# Play in a content trust sandbox

***

Table of contents

***

This page explains how to set up and use a sandbox for experimenting with trust. The sandbox allows you to configure and try trust operations locally without impacting your production images.

Before working through this sandbox, you should have read through the [trust overview](https://docs.docker.com/engine/security/trust/).

## [Prerequisites](#prerequisites)

These instructions assume you are running in Linux or macOS. You can run this sandbox on a local machine or on a virtual machine. You need to have privileges to run docker commands on your local machine or in the VM.

This sandbox requires you to install two Docker tools: Docker Engine >= 1.10.0 and Docker Compose >= 1.6.0. To install the Docker Engine, choose from the [list of supported platforms](https://docs.docker.com/engine/install/). To install Docker Compose, see the [detailed instructions here](https://docs.docker.com/compose/install/).

## [What is in the sandbox?](#what-is-in-the-sandbox)

If you are just using trust out-of-the-box you only need your Docker Engine client and access to the Docker Hub. The sandbox mimics a production trust environment, and sets up these additional components.

| Container       | Description                                                                                                                                                                         |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| trustsandbox    | A container with the latest version of Docker Engine and with some preconfigured certificates. This is your sandbox where you can use the `docker` client to test trust operations. |
| Registry server | A local registry service.                                                                                                                                                           |
| Notary server   | The service that does all the heavy-lifting of managing trust                                                                                                                       |

This means you run your own content trust (Notary) server and registry. If you work exclusively with the Docker Hub, you would not need these components. They are built into the Docker Hub for you. For the sandbox, however, you build your own entire, mock production environment.

Within the `trustsandbox` container, you interact with your local registry rather than the Docker Hub. This means your everyday image repositories are not used. They are protected while you play.

When you play in the sandbox, you also create root and repository keys. The sandbox is configured to store all the keys and files inside the `trustsandbox` container. Since the keys you create in the sandbox are for play only, destroying the container destroys them as well.

By using a `docker-in-docker` image for the `trustsandbox` container, you also don't pollute your real Docker daemon cache with any images you push and pull. The images are stored in an anonymous volume attached to this container, and can be destroyed after you destroy the container.

## [Build the sandbox](#build-the-sandbox)

In this section, you use Docker Compose to specify how to set up and link together the `trustsandbox` container, the Notary server, and the Registry server.

1. Create a new `trustsandbox` directory and change into it.

   ```console
   $ mkdir trustsandbox
   $ cd trustsandbox
   ```

2. Create a file called `compose.yaml` with your favorite editor. For example, using vim:

   ```console
   $ touch compose.yaml
   $ vim compose.yaml
   ```

3. Add the following to the new file.

   ```yaml
   version: "2"
   services:
     notaryserver:
       image: dockersecurity/notary_autobuilds:server-v0.5.1
       volumes:
         - notarycerts:/var/lib/notary/fixtures
       networks:
         - sandbox
       environment:
         - NOTARY_SERVER_STORAGE_TYPE=memory
         - NOTARY_SERVER_TRUST_SERVICE_TYPE=local
     sandboxregistry:
       image: registry:3
       networks:
         - sandbox
       container_name: sandboxregistry
     trustsandbox:
       image: docker:dind
       networks:
         - sandbox
       volumes:
         - notarycerts:/notarycerts
       privileged: true
       container_name: trustsandbox
       entrypoint: ""
       command: |-
           sh -c '
               cp /notarycerts/root-ca.crt /usr/local/share/ca-certificates/root-ca.crt &&
               update-ca-certificates &&
               dockerd-entrypoint.sh --insecure-registry sandboxregistry:5000'
   volumes:
     notarycerts:
       external: false
   networks:
     sandbox:
       external: false
   ```

4. Save and close the file.

5. Run the containers on your local system.

   ```console
   $ docker compose up -d
   ```

   The first time you run this, the `docker-in-docker`, Notary server, and registry images are downloaded from Docker Hub.

## [Play in the sandbox](#play-in-the-sandbox)

Now that everything is setup, you can go into your `trustsandbox` container and start testing Docker content trust. From your host machine, obtain a shell in the `trustsandbox` container.

```console
$ docker container exec -it trustsandbox sh
/ #
```

### [Test some trust operations](#test-some-trust-operations)

Now, pull some images from within the `trustsandbox` container.

1. Download a `docker` image to test with.

   ```console
   / # docker pull docker/trusttest
   docker pull docker/trusttest
   Using default tag: latest
   latest: Pulling from docker/trusttest   
   b3dbab3810fc: Pull complete
   a9539b34a6ab: Pull complete
   Digest: sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d850b2a2a67f2819a
   Status: Downloaded newer image for docker/trusttest:latest
   ```

2. Tag it to be pushed to your sandbox registry:

   ```console
   / # docker tag docker/trusttest sandboxregistry:5000/test/trusttest:latest
   ```

3. Enable content trust.

   ```console
   / # export DOCKER_CONTENT_TRUST=1
   ```

4. Identify the trust server.

   ```console
   / # export DOCKER_CONTENT_TRUST_SERVER=https://notaryserver:4443
   ```

   This step is only necessary because the sandbox is using its own server. Normally, if you are using the Docker Public Hub this step isn't necessary.

5. Pull the test image.

   ```console
   / # docker pull sandboxregistry:5000/test/trusttest
   Using default tag: latest
   Error: remote trust data does not exist for sandboxregistry:5000/test/trusttest: notaryserver:4443 does not have trust data for      sandboxregistry:5000/test/trusttest
   ```

   You see an error, because this content doesn't exist on the `notaryserver` yet.

6. Push and sign the trusted image.

   ```console
   / # docker push sandboxregistry:5000/test/trusttest:latest
   The push refers to a repository [sandboxregistry:5000/test/trusttest]
   5f70bf18a086: Pushed
   c22f7bc058a9: Pushed
   latest: digest: sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 size: 734
   Signing and pushing trust metadata
   You are about to create a new root signing key passphrase. This passphrase
   will be used to protect the most sensitive key in your signing system. Please
   choose a long, complex passphrase and be careful to keep the password and the
   key file itself secure and backed up. It is highly recommended that you use a
   password manager to generate the passphrase and keep it safe. There will be no
   way to recover this key. You can find the key in your config directory.
   Enter passphrase for new root key with ID 27ec255:
   Repeat passphrase for new root key with ID 27ec255:
   Enter passphrase for new repository key with ID 58233f9 (sandboxregistry:5000/test/trusttest):
   Repeat passphrase for new repository key with ID 58233f9 (sandboxregistry:5000/test/trusttest):
   Finished initializing "sandboxregistry:5000/test/trusttest"
   Successfully signed "sandboxregistry:5000/test/trusttest":latest
   ```

   Because you are pushing this repository for the first time, Docker creates new root and repository keys and asks you for passphrases with which to encrypt them. If you push again after this, it only asks you for repository passphrase so it can decrypt the key and sign again.

7. Try pulling the image you just pushed:

   ```console
   / # docker pull sandboxregistry:5000/test/trusttest
   Using default tag: latest
   Pull (1 of 1): sandboxregistry:5000/test/trusttest:latest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
   sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926: Pulling from test/trusttest
   Digest: sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
   Status: Downloaded newer image for sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
   Tagging sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926 as sandboxregistry:5000   test/trusttest:latest
   ```

### [Test with malicious images](#test-with-malicious-images)

What happens when data is corrupted and you try to pull it when trust is enabled? In this section, you go into the `sandboxregistry` and tamper with some data. Then, you try and pull it.

1. Leave the `trustsandbox` shell and container running.

2. Open a new interactive terminal from your host, and obtain a shell into the `sandboxregistry` container.

   ```console
   $ docker container exec -it sandboxregistry bash
   root@65084fc6f047:/#
   ```

3. List the layers for the `test/trusttest` image you pushed:

   ```console
   root@65084fc6f047:/# ls -l /var/lib/registry/docker/registry/v2/repositories/test/trusttest/_layers/sha256
   total 12
   drwxr-xr-x 2 root root 4096 Jun 10 17:26 a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
   drwxr-xr-x 2 root root 4096 Jun 10 17:26 aac0c133338db2b18ff054943cee3267fe50c75cdee969aed88b1992539ed042
   drwxr-xr-x 2 root root 4096 Jun 10 17:26 cc7629d1331a7362b5e5126beb5bf15ca0bf67eb41eab994c719a45de53255cd
   ```

4. Change into the registry storage for one of those layers (this is in a different directory):

   ```console
   root@65084fc6f047:/# cd /var/lib/registry/docker/registry/v2/blobs/sha256/aa/aac0c133338db2b18ff054943cee3267fe50c75cdee969aed88b1992539ed042
   ```

5. Add malicious data to one of the `trusttest` layers:

   ```console
   root@65084fc6f047:/# echo "Malicious data" > data
   ```

6. Go back to your `trustsandbox` terminal.

7. List the `trusttest` image.

   ```console
   / # docker image ls | grep trusttest
   REPOSITORY                            TAG                 IMAGE ID            CREATED             SIZE
   docker/trusttest                      latest              cc7629d1331a        11 months ago       5.025 MB
   sandboxregistry:5000/test/trusttest   latest              cc7629d1331a        11 months ago       5.025 MB
   sandboxregistry:5000/test/trusttest   <none>              cc7629d1331a        11 months ago       5.025 MB
   ```

8. Remove the `trusttest:latest` image from your local cache.

   ```console
   / # docker image rm -f cc7629d1331a
   Untagged: docker/trusttest:latest
   Untagged: sandboxregistry:5000/test/trusttest:latest
   Untagged: sandboxregistry:5000/test/trusttest@sha256:ebf59c538accdf160ef435f1a19938ab8c0d6bd96aef8d4ddd1b379edf15a926
   Deleted: sha256:cc7629d1331a7362b5e5126beb5bf15ca0bf67eb41eab994c719a45de53255cd
   Deleted: sha256:2a1f6535dc6816ffadcdbe20590045e6cbf048d63fd4cc753a684c9bc01abeea
   Deleted: sha256:c22f7bc058a9a8ffeb32989b5d3338787e73855bf224af7aa162823da015d44c
   ```

   Docker does not re-download images that it already has cached, but you want Docker to attempt to download the tampered image from the registry and reject it because it is invalid.

9. Pull the image again. This downloads the image from the registry, because you don't have it cached.

   ```console
   / # docker pull sandboxregistry:5000/test/trusttest
   Using default tag: latest
   Pull (1 of 1): sandboxregistry:5000/test/trusttest:latest@sha256:35d5bc26fd358da8320c137784fe590d8fcf9417263ef261653e8e1c7f15672e
   sha256:35d5bc26fd358da8320c137784fe590d8fcf9417263ef261653e8e1c7f15672e: Pulling from test/trusttest

   aac0c133338d: Retrying in 5 seconds
   a3ed95caeb02: Download complete
   error pulling image configuration: unexpected EOF
   ```

   The pull did not complete because the trust system couldn't verify the image.

## [More play in the sandbox](#more-play-in-the-sandbox)

Now, you have a full Docker content trust sandbox on your local system, feel free to play with it and see how it behaves. If you find any security issues with Docker, feel free to send us an email at <security@docker.com>.

## [Clean up your sandbox](#clean-up-your-sandbox)

When you are done, and want to clean up all the services you've started and any anonymous volumes that have been created, just run the following command in the directory where you've created your Docker Compose file:

```console
$ docker compose down -v
```

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/remove/
----

# docker mcp profile remove

***

| Description                                                               | Remove a profile                         |
| ------------------------------------------------------------------------- | ---------------------------------------- |
| Usage                                                                     | `docker mcp profile remove <profile-id>` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker mcp profile rm`                  |

## [Description](#description)

Remove a profile

----
url: https://docs.docker.com/guides/lab-containerized-sdlc/
----

[Lab: The Containerized SDLC](https://docs.docker.com/guides/lab-containerized-sdlc/)

Hands-on lab: Take a Node.js app from source to live Kubernetes deployment using Docker Compose, Testcontainers, Gitea Actions CI/CD, and kubectl — with containers at every stage of the SDLC.

Labs

60 minutes

Resources:

* [Docker Compose docs](/compose/)
* [Testcontainers docs](https://testcontainers.com/)
* [Labspace repository](https://github.com/dockersamples/labspace-containerized-sdlc)

[« Back to all guides](/guides/)

# Lab: The Containerized SDLC

***

Table of contents

***

Build a real Node.js API, then apply containers at every stage of the software development lifecycle. You'll write a Compose file for local development, integration tests using Testcontainers, a CI/CD pipeline, and Kubernetes manifests — using the same container image throughout.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-containerized-sdlc up -d
   ```

2. Open your browser to <http://dockerlabs.xyz>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

By the end of this Labspace, you will have completed the following:

* Set up a containerized local development environment with Docker Compose and Compose Watch
* Write integration tests that spin up a real database using Testcontainers
* Build a CI/CD pipeline that tests, builds, and pushes a container image automatically
* Write Kubernetes manifests and deploy a live application to a k3s cluster
* Configure the pipeline to cause an automatic deployment on every push to `main`

## [Modules](#modules)

| # | Module                                    | Description                                                              |
| - | ----------------------------------------- | ------------------------------------------------------------------------ |
| 1 | Introduction: Meet the App                | Tour the TaskFlow API and understand the SDLC journey ahead              |
| 2 | Local Dev with Docker Compose             | Write a `compose.yaml` to provision a local database and visualizer      |
| 3 | Containerizing Your Dev Environment       | Add the app to Compose with hot-reloading via Compose Watch              |
| 4 | Integration Testing with Testcontainers   | Write self-contained tests that start a real PostgreSQL container        |
| 5 | Continuous Integration with Gitea Actions | Build a pipeline that tests, builds, and pushes a container image        |
| 6 | Deploying to Kubernetes                   | Write manifests and deploy to a live k3s cluster with automated rollouts |
| 7 | The Containerized SDLC: A Recap           | Review the portability, consistency, and reproducibility gains           |

----
url: https://docs.docker.com/engine/daemon/live-restore/
----

# Live restore

***

Table of contents

***

By default, when the Docker daemon terminates, it shuts down running containers. You can configure the daemon so that containers remain running if the daemon becomes unavailable. This functionality is called *live restore*. The live restore option helps reduce container downtime due to daemon crashes, planned outages, or upgrades.

> Note
>
> Live restore isn't supported for Windows containers, but it does work for Linux containers running on Docker Desktop for Windows.

## [Enable live restore](#enable-live-restore)

There are two ways to enable the live restore setting to keep containers alive when the daemon becomes unavailable. **Only do one of the following**.

* Add the configuration to the daemon configuration file. On Linux, this defaults to `/etc/docker/daemon.json`. On Docker Desktop for Mac or Docker Desktop for Windows, select the Docker icon from the task bar, then click **Settings** -> **Docker Engine**.

  * Use the following JSON to enable `live-restore`.

    ```json
    {
      "live-restore": true
    }
    ```

  * Restart the Docker daemon. On Linux, you can avoid a restart (and avoid any downtime for your containers) by reloading the Docker daemon. If you use `systemd`, then use the command `systemctl reload docker`. Otherwise, send a `SIGHUP` signal to the `dockerd` process.

* If you prefer, you can start the `dockerd` process manually with the `--live-restore` flag. This approach isn't recommended because it doesn't set up the environment that `systemd` or another process manager would use when starting the Docker process. This can cause unexpected behavior.

## [Live restore during upgrades](#live-restore-during-upgrades)

Live restore allows you to keep containers running across Docker daemon updates, but is only supported when installing patch releases (`YY.MM.x`), not for major (`YY.MM`) daemon upgrades.

If you skip releases during an upgrade, the daemon may not restore its connection to the containers. If the daemon can't restore the connection, it can't manage the running containers and you must stop them manually.

## [Live restore upon restart](#live-restore-upon-restart)

The live restore option only works to restore containers if the daemon options, such as bridge IP addresses and graph driver, didn't change. If any of these daemon-level configuration options have changed, the live restore may not work and you may need to manually stop the containers.

## [Impact of live restore on running containers](#impact-of-live-restore-on-running-containers)

If the daemon is down for a long time, running containers may fill up the FIFO log the daemon normally reads. A full log blocks containers from logging more data. The default buffer size is 64K. If the buffers fill, you must restart the Docker daemon to flush them.

On Linux, you can modify the kernel's buffer size by changing `/proc/sys/fs/pipe-max-size`. You can't modify the buffer size on Docker Desktop for Mac or Docker Desktop for Windows.

## [Live restore and Swarm mode](#live-restore-and-swarm-mode)

The live restore option only pertains to standalone containers, and not to Swarm services. Swarm services are managed by Swarm managers. If Swarm managers are not available, Swarm services continue to run on worker nodes but can't be managed until enough Swarm managers are available to maintain a quorum.

----
url: https://docs.docker.com/docker-hub/repos/manage/hub-images/move/
----

# Move images between repositories

***

Table of contents

***

Consolidating and organizing your Docker images across repositories can streamline your workflows, whether you're managing personal projects or contributing to an organization. This topic explains how to move images between Docker Hub repositories, ensuring that your content remains accessible and organized under the correct accounts or namespaces.

> Note
>
> For bulk migrations, multi-arch images, or scripted workflows, see [Bulk migrate Docker images](https://docs.docker.com/docker-hub/repos/manage/hub-images/bulk-migrate/).

## [Personal to personal](#personal-to-personal)

When consolidating personal repositories, you can pull private images from the initial repository and push them into another repository owned by you. To avoid losing your private images, perform the following steps:

1. [Sign up](https://app.docker.com/signup) for a new Docker account with a personal subscription. (Be sure to verify your account after you've signed up.)

2. Sign in to [Docker](https://app.docker.com/login) using your original Docker account

3. Pull your images:

   ```console
   $ docker pull namespace1/docker101tutorial
   ```

4. Tag your private images with your newly created Docker username, for example:

   ```console
   $ docker tag namespace1/docker101tutorial new_namespace/docker101tutorial
   ```

5. Using `docker login` from the CLI, sign in with your newly created Docker account, and push your newly tagged private images to your new Docker account namespace:

   ```console
   $ docker push new_namespace/docker101tutorial
   ```

The private images that existed in your previous account are now available in your new account.

## [Personal to an organization](#personal-to-an-organization)

To avoid losing your private images, you can pull your private images from your personal account and push them to an organization that's owned by you.

1. Navigate to [Docker Hub](https://hub.docker.com) and select **My Hub**.

2. Select the applicable organization and verify that your user account is a member of the organization.

3. Sign in to [Docker Hub](https://hub.docker.com) using your original Docker account, and pull your images:

   ```console
   $ docker pull namespace1/docker101tutorial
   ```

4. Tag your images with your new organization namespace:

   ```console
   $ docker tag namespace1/docker101tutorial <new_org>/docker101tutorial
   ```

5. Push your newly tagged images to your new org namespace:

   ```console
   $ docker push new_org/docker101tutorial
   ```

The private images that existed in your user account are now available for your organization.

----
url: https://docs.docker.com/engine/security/trust/deploying_notary/
----

# Deploy Notary Server with Compose

***

Table of contents

***

The easiest way to deploy Notary Server is by using Docker Compose. To follow the procedure on this page, you must have already [installed Docker Compose](https://docs.docker.com/compose/install/).

1. Clone the Notary repository.

   ```console
   $ git clone https://github.com/theupdateframework/notary.git
   ```

2. Build and start Notary Server with the sample certificates.

   ```console
   $ docker compose up -d 
   ```

   For more detailed documentation about how to deploy Notary Server, see the [instructions to run a Notary service](https://github.com/theupdateframework/notary/blob/master/docs/running_a_service.md) as well as [the Notary repository](https://github.com/theupdateframework/notary) for more information.

3. Make sure that your Docker or Notary client trusts Notary Server's certificate before you try to interact with the Notary server.

See the instructions for [Docker](/reference/cli/docker/#notary) or for [Notary](https://github.com/docker/notary#using-notary) depending on which one you are using.

## [If you want to use Notary in production](#if-you-want-to-use-notary-in-production)

Check back here for instructions after Notary Server has an official stable release. To get a head start on deploying Notary in production, see [the Notary repository](https://github.com/theupdateframework/notary).

----
url: https://docs.docker.com/compose/how-tos/multiple-compose-files/include/
----

# Include

***

Table of contents

***

Requires: Docker Compose [2.20.3](https://github.com/docker/compose/releases/tag/v2.20.3) and later

With `include`, you can incorporate a separate `compose.yaml` file directly in your current `compose.yaml` file. This makes it easy to modularize complex applications into sub-Compose files, which in turn enables application configurations to be made simpler and more explicit.

The [`include` top-level element](https://docs.docker.com/reference/compose-file/include/) helps to reflect the engineering team responsible for the code directly in the config file's organization. It also solves the relative path problem that [`extends`](https://docs.docker.com/compose/how-tos/multiple-compose-files/extends/) and [merge](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/) present.

Each path listed in the `include` section loads as an individual Compose application model, with its own project directory, in order to resolve relative paths.

Once the included Compose application loads, all resources are copied into the current Compose application model.

> Note
>
> `include` applies recursively so an included Compose file which declares its own `include` section, causes those files to also be included.

## [Example](#example)

```yaml
include:
  - my-compose-include.yaml  #with serviceB declared
services:
  serviceA:
    build: .
    depends_on:
      - serviceB #use serviceB directly as if it was declared in this Compose file
```

`my-compose-include.yaml` manages `serviceB` which details some replicas, web UI to inspect data, isolated networks, volumes for data persistence, etc. The application relying on `serviceB` doesn’t need to know about the infrastructure details, and consumes the Compose file as a building block it can rely on.

This means the team managing `serviceB` can refactor its own database component to introduce additional services without impacting any dependent teams. It also means that the dependent teams don't need to include additional flags on each Compose command they run.

```yaml
include:
  - oci://docker.io/username/my-compose-app:latest # use a Compose file stored as an OCI artifact
services:
  serviceA:
    build: .
    depends_on:
      - serviceB 
```

`include` allows you to reference Compose files from remote sources, such as OCI artifacts or Git repositories.\
Here `serviceB` is defined in a Compose file stored on Docker Hub.

## [Using overrides with included Compose files](#using-overrides-with-included-compose-files)

Compose reports an error if any resource from `include` conflicts with resources from the included Compose file. This rule prevents unexpected conflicts with resources defined by the included compose file author. However, there may be some circumstances where you might want to customize the included model. This can be achieved by adding an override file to the include directive:

```yaml
include:
  - path : 
      - third-party/compose.yaml
      - override.yaml  # local override for third-party model
```

The main limitation with this approach is that you need to maintain a dedicated override file per include. For complex projects with multiple includes this would result in many Compose files.

The other option is to use a `compose.override.yaml` file. While conflicts will be rejected from the file using `include` when same resource is declared, a global Compose override file can override the resulting merged model, as demonstrated in following example:

Main `compose.yaml` file:

```yaml
include:
  - team-1/compose.yaml # declare service-1
  - team-2/compose.yaml # declare service-2
```

Override `compose.override.yaml` file:

```yaml
services:
  service-1:
    # override included service-1 to enable debugger port
    ports:
      - 2345:2345

  service-2:
    # override included service-2 to use local data folder containing test data
    volumes:
      - ./data:/data
```

Combined together, this allows you to benefit from third-party reusable components, and adjust the Compose model for your needs.

## [Reference information](#reference-information)

[`include` top-level element](https://docs.docker.com/reference/compose-file/include/)

----
url: https://docs.docker.com/ai/gordon/how-to/permissions/
----

# Gordon's permission model

***

Table of contents

***

Requires: Docker Desktop [4.74.0](https://docs.docker.com/desktop/release-notes/#4740) or later

Before Gordon uses a tool or action that can modify your system, it proposes the action and waits for your approval before executing.

## [What requires approval](#what-requires-approval)

By default, the following actions require approval before Gordon can use them:

* Commands executed in your shell
* Writing or changing files
* Fetching information from the internet

## [What doesn't require approval](#what-doesnt-require-approval)

* Reading files, listing directories (even outside Gordon's working directory)
* Searching the Docker documentation
* Analyzing code or explaining errors

## [Configuring permission settings](#configuring-permission-settings)

To change the default permission settings for Gordon:

1. Open Docker Desktop.

2. Select **Gordon** in the sidebar.

3. Select the settings icon at the bottom of text input.

In the **Basic** tab you can configure whether Gordon should ask for permission before using a tool.

You can also enable YOLO mode to bypass permission checking altogether.

The new permission settings apply immediately to all sessions.

## [Session-level permissions](#session-level-permissions)

When you choose "Approve for this session" (Desktop) or "A" (CLI), Gordon can use that specific tool without asking again during the current conversation.

Example:

```console
$ docker ai "check my containers and clean up stopped ones"

Gordon proposes:
  docker ps -a

Approve? [Y/n/a]: a

[Gordon executes docker ps -a]

Gordon proposes:
  docker container prune -f

[Executes automatically - you approved shell access for this session]
```

Session permissions reset when:

* You close the Gordon view (Desktop)
* You exit `docker ai` (CLI)
* You start a new conversation

## [Security considerations](#security-considerations)

* Working directory

  The working directory sets the default context for file operations. It does not constrain Gordon's access to files or directories; Gordon can read files outside this directory.

* Verify before approving

  Gordon can make mistakes. Before approving:

  * Confirm commands match your intent
  * Check container names and image tags are correct
  * Verify volume mounts and port mappings
  * Review file changes for important logic

  If you don't understand an operation, ask Gordon to explain it or reject and request a different approach.

* Destructive operations

  Gordon warns about destructive operations but won't prevent them. Operations like `docker container rm`, `docker system prune`, and `docker volume rm` can cause permanent data loss. Back up important data first.

## [Stopping and reverting](#stopping-and-reverting)

Stop Gordon during execution by pressing `Ctrl+C` (CLI) or selecting **Cancel** (Desktop).

Revert Gordon's actions using Docker commands or version control:

* Restore files from Git
* Restart stopped containers
* Rebuild images
* Recreate volumes from backups

Use version control for all files in your working directory.

## [Organizational controls](#organizational-controls)

Administrators can control Gordon's capabilities at the organization level using Settings Management.

Available controls:

* Disable Gordon entirely
* Restrict tool capabilities
* Set working directory boundaries

For Business subscriptions, Gordon must be enabled by an administrator before users can access it.

See [Settings Management](/enterprise/security/hardened-desktop/settings-management/) for details.

----
url: https://docs.docker.com/reference/cli/docker/mcp/version/
----

# docker mcp version

***

| Description | Show the version information |
| ----------- | ---------------------------- |
| Usage       | `docker mcp version`         |

## [Description](#description)

Show the version information

----
url: https://docs.docker.com/guides/jupyter/
----

[Data science with JupyterLab](https://docs.docker.com/guides/jupyter/)

Use Docker to run Jupyter notebooks.

Python Data science

20 minutes

[« Back to all guides](/guides/)

# Data science with JupyterLab

***

Table of contents

***

Docker and JupyterLab are two powerful tools that can enhance your data science workflow. In this guide, you will learn how to use them together to create and run reproducible data science environments. This guide is based on [Supercharging AI/ML Development with JupyterLab and Docker](https://www.docker.com/blog/supercharging-ai-ml-development-with-jupyterlab-and-docker/).

In this guide, you'll learn how to:

* Run a personal Jupyter Server with JupyterLab on your local machine
* Customize your JupyterLab environment
* Share your JupyterLab notebook and environment with other data scientists

## [What is JupyterLab?](#what-is-jupyterlab)

[JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) is an open source application built around the concept of a computational notebook document. It enables sharing and executing code, data processing, visualization, and offers a range of interactive features for creating graphs.

## [Why use Docker and JupyterLab together?](#why-use-docker-and-jupyterlab-together)

By combining Docker and JupyterLab, you can benefit from the advantages of both tools, such as:

* Containerization ensures a consistent JupyterLab environment across all deployments, eliminating compatibility issues.
* Containerized JupyterLab simplifies sharing and collaboration by removing the need for manual environment setup.
* Containers offer scalability for JupyterLab, supporting workload distribution and efficient resource management with platforms like Kubernetes.

## [Prerequisites](#prerequisites)

To follow along with this guide, you must install the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).

## [Run and access a JupyterLab container](#run-and-access-a-jupyterlab-container)

In a terminal, run the following command to run your JupyterLab container.

```console
$ docker run --rm -p 8889:8888 quay.io/jupyter/base-notebook start-notebook.py --NotebookApp.token='my-token'
```

The following are the notable parts of the command:

* `-p 8889:8888`: Maps port 8889 from the host to port 8888 on the container.
* `start-notebook.py --NotebookApp.token='my-token'`: Sets an access token rather than using a random token.

For more details, see the [Jupyter Server Options](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/common.html#jupyter-server-options) and the [docker run CLI reference](/reference/cli/docker/container/run/).

If this is the first time you are running the image, Docker will download and run it. The amount of time it takes to download the image will vary depending on your network connection.

After the image downloads and runs, you can access the container. To access the container, in a web browser navigate to [localhost:8889/lab?token=my-token](http://localhost:8889/lab?token=my-token).

To stop the container, in the terminal press `ctrl`+`c`.

To access an existing notebook on your system, you can use a [bind mount](/storage/bind-mounts/). Open a terminal and change directory to where your existing notebook is. Then, run the following command based on your operating system.

```console
$ docker run --rm -p 8889:8888 -v "$(pwd):/home/jovyan/work" quay.io/jupyter/base-notebook start-notebook.py --NotebookApp.token='my-token'
```

```console
$ docker run --rm -p 8889:8888 -v "%cd%":/home/jovyan/work quay.io/jupyter/base-notebook start-notebook.py --NotebookApp.token='my-token'
```

```console
$ docker run --rm -p 8889:8888 -v "$(pwd):/home/jovyan/work" quay.io/jupyter/base-notebook start-notebook.py --NotebookApp.token='my-token'
```

```console
$ docker run --rm -p 8889:8888 -v "/$(pwd):/home/jovyan/work" quay.io/jupyter/base-notebook start-notebook.py --NotebookApp.token='my-token'
```

The `-v` option tells Docker to mount your current working directory to `/home/jovyan/work` inside the container. By default, the Jupyter image's root directory is `/home/jovyan` and you can only access or save notebooks to that directory in the container.

Now you can access [localhost:8889/lab?token=my-token](http://localhost:8889/lab?token=my-token) and open notebooks contained in the bind mounted directory.

To stop the container, in the terminal press `ctrl`+`c`.

Docker also has volumes, which are the preferred mechanism for persisting data generated by and used by Docker containers. While bind mounts are dependent on the directory structure and OS of the host machine, volumes are completely managed by Docker.

## [Save and access notebooks](#save-and-access-notebooks)

When you remove a container, all data in that container is deleted. To save notebooks outside of the container, you can use a [volume](/engine/storage/volumes/).

### [Run a JupyterLab container with a volume](#run-a-jupyterlab-container-with-a-volume)

To start the container with a volume, open a terminal and run the following command

```console
$ docker run --rm -p 8889:8888 -v jupyter-data:/home/jovyan/work quay.io/jupyter/base-notebook start-notebook.py --NotebookApp.token='my-token'
```

The `-v` option tells Docker to create a volume named `jupyter-data` and mount it in the container at `/home/jovyan/work`.

To access the container, in a web browser navigate to [localhost:8889/lab?token=my-token](http://localhost:8889/lab?token=my-token). Notebooks can now be saved to the volume and will accessible even when the container is deleted.

### [Save a notebook to the volume](#save-a-notebook-to-the-volume)

For this example, you'll use the [Iris Dataset](https://scikit-learn.org/stable/auto_examples/datasets/plot_iris_dataset.html) example from scikit-learn.

1. Open a web browser and access your JupyterLab container at [localhost:8889/lab?token=my-token](http://localhost:8889/lab?token=my-token).

2. In the **Launcher**, under **Notebook**, select **Python 3**.

3. In the notebook, specify the following to install the necessary packages.

   ```console
   !pip install matplotlib scikit-learn
   ```

4. Select the play button to run the code.

5. In the notebook, specify the following code.

   ```python
   from sklearn import datasets

   iris = datasets.load_iris()
   import matplotlib.pyplot as plt

   _, ax = plt.subplots()
   scatter = ax.scatter(iris.data[:, 0], iris.data[:, 1], c=iris.target)
   ax.set(xlabel=iris.feature_names[0], ylabel=iris.feature_names[1])
   _ = ax.legend(
      scatter.legend_elements()[0], iris.target_names, loc="lower right", title="Classes"
   )
   ```

6. Select the play button to run the code. You should see a scatter plot of the Iris dataset.

7. In the top menu, select **File** and then **Save Notebook**.

8. Specify a name in the `work` directory to save the notebook to the volume. For example, `work/mynotebook.ipynb`.

9. Select **Rename** to save the notebook.

The notebook is now saved in the volume.

In the terminal, press `ctrl`+ `c` to stop the container.

Now, any time you run a Jupyter container with the volume, you'll have access to the saved notebook.

When you do run a new container, and then run the data plot code again, it'll need to run `!pip install matplotlib scikit-learn` and download the packages. You can avoid reinstalling packages every time you run a new container by creating your own image with the packages already installed.

## [Customize your JupyterLab environment](#customize-your-jupyterlab-environment)

You can create your own JupyterLab environment and build it into an image using Docker. By building your own image, you can customize your JupyterLab environment with the packages and tools you need, and ensure that it's consistent and reproducible across different deployments. Building your own image also makes it easier to share your JupyterLab environment with others, or to use it as a base for further development.

### [Define your environment in a Dockerfile](#define-your-environment-in-a-dockerfile)

In the previous Iris Dataset example from [Save a notebook to the volume](#save-a-notebook-to-the-volume), you had to install the dependencies, `matplotlib` and `scikit-learn`, every time you ran a new container. While the dependencies in that small example download and install quickly, it may become a problem as your list of dependencies grow. There may also be other tools, packages, or files that you always want in your environment.

In this case, you can install the dependencies as part of the environment in the image. Then, every time you run your container, the dependencies will always be installed.

You can define your environment in a Dockerfile. A Dockerfile is a text file that instructs Docker how to create an image of your JupyterLab environment. An image contains everything you want and need when running JupyterLab, such as files, packages, and tools.

In a directory of your choice, create a new text file named `Dockerfile`. Open the `Dockerfile` in an IDE or text editor and then add the following contents.

```dockerfile
# syntax=docker/dockerfile:1

FROM quay.io/jupyter/base-notebook
RUN pip install --no-cache-dir matplotlib scikit-learn
```

This Dockerfile uses the `quay.io/jupyter/base-notebook` image as the base, and then runs `pip` to install the dependencies. For more details about the instructions in the Dockerfile, see the [Dockerfile reference](/reference/dockerfile/).

Before you proceed, save your changes to the `Dockerfile`.

### [Build your environment into an image](#build-your-environment-into-an-image)

After you have a `Dockerfile` to define your environment, you can use `docker build` to build an image using your `Dockerfile`.

Open a terminal, change directory to the directory where your `Dockerfile` is located, and then run the following command.

```console
$ docker build -t my-jupyter-image .
```

The command builds a Docker image from your `Dockerfile` and a context. The `-t` option specifies the name and tag of the image, in this case `my-jupyter-image`. The `.` indicates that the current directory is the context, which means that the files in that directory can be used in the image creation process.

You can verify that the image was built by viewing the `Images` view in Docker Desktop, or by running the `docker image ls` command in a terminal. You should see an image named `my-jupyter-image`.

## [Run your image as a container](#run-your-image-as-a-container)

To run your image as a container, you use the `docker run` command. In the `docker run` command, you'll specify your own image name.

```console
$ docker run --rm -p 8889:8888 my-jupyter-image start-notebook.py --NotebookApp.token='my-token'
```

To access the container, in a web browser navigate to [localhost:8889/lab?token=my-token](http://localhost:8889/lab?token=my-token).

You can now use the packages without having to install them in your notebook.

1. In the **Launcher**, under **Notebook**, select **Python 3**.

2. In the notebook, specify the following code.

   ```python
   from sklearn import datasets

   iris = datasets.load_iris()
   import matplotlib.pyplot as plt

   _, ax = plt.subplots()
   scatter = ax.scatter(iris.data[:, 0], iris.data[:, 1], c=iris.target)
   ax.set(xlabel=iris.feature_names[0], ylabel=iris.feature_names[1])
   _ = ax.legend(
      scatter.legend_elements()[0], iris.target_names, loc="lower right", title="Classes"
   )
   ```

3. Select the play button to run the code. You should see a scatter plot of the Iris dataset.

In the terminal, press `ctrl`+ `c` to stop the container.

## [Use Compose to run your container](#use-compose-to-run-your-container)

Docker Compose is a tool for defining and running multi-container applications. In this case, the application isn't a multi-container application, but Docker Compose can make it easier to run by defining all the `docker run` options in a file.

### [Create a Compose file](#create-a-compose-file)

To use Compose, you need a `compose.yaml` file. In the same directory as your `Dockerfile`, create a new file named `compose.yaml`.

Open the `compose.yaml` file in an IDE or text editor and add the following contents.

```yaml
services:
  jupyter:
    build:
      context: .
    ports:
      - 8889:8888
    volumes:
      - jupyter-data:/home/jovyan/work
    command: start-notebook.py --NotebookApp.token='my-token'

volumes:
  jupyter-data:
    name: jupyter-data
```

This Compose file specifies all the options you used in the `docker run` command. For more details about the Compose instructions, see the [Compose file reference](https://docs.docker.com/reference/compose-file/).

Before you proceed, save your changes to the `compose.yaml` file.

### [Run your container using Compose](#run-your-container-using-compose)

Open a terminal, change directory to where your `compose.yaml` file is located, and then run the following command.

```console
$ docker compose up --build
```

This command builds your image and runs it as a container using the instructions specified in the `compose.yaml` file. The `--build` option ensures that your image is rebuilt, which is necessary if you made changes to your `Dockerfile`.

To access the container, in a web browser navigate to [localhost:8889/lab?token=my-token](http://localhost:8889/lab?token=my-token).

In the terminal, press `ctrl`+ `c` to stop the container.

## [Share your work](#share-your-work)

By sharing your image and notebook, you create a portable and replicable research environment that can be easily accessed and used by other data scientists. This process not only facilitates collaboration but also ensures that your work is preserved in an environment where it can be run without compatibility issues.

To share your image and data, you'll use [Docker Hub](https://hub.docker.com/). Docker Hub is a cloud-based registry service that lets you share and distribute container images.

### [Share your image](#share-your-image)

1. [Sign up](https://www.docker.com/pricing?ref=Docs\&refAction=DocsGuidesJupyter) or sign in to [Docker Hub](https://hub.docker.com).

2. Rename your image so that Docker knows which repository to push it to. Open a terminal and run the following `docker tag` command. Replace `YOUR-USER-NAME` with your Docker ID.

   ```console
   $ docker tag my-jupyter-image YOUR-USER-NAME/my-jupyter-image
   ```

3. Run the following `docker push` command to push the image to Docker Hub. Replace `YOUR-USER-NAME` with your Docker ID.

   ```console
   $ docker push YOUR-USER-NAME/my-jupyter-image
   ```

4. Verify that you pushed the image to Docker Hub.

   1. Go to [Docker Hub](https://hub.docker.com).
   2. Select **My Hub** > **Repositories**.
   3. View the **Last pushed** time for your repository.

Other users can now download and run your image using the `docker run` command. They need to replace `YOUR-USER-NAME` with your Docker ID.

```console
$ docker run --rm -p 8889:8888 YOUR-USER-NAME/my-jupyter-image start-notebook.py --NotebookApp.token='my-token'
```

### [Share your volume](#share-your-volume)

This example uses the Docker Desktop graphical user interface. Alternatively, in the command line interface you can [back up the volume](/engine/storage/volumes/#back-up-a-volume) and then [push it using the ORAS CLI](https://docs.docker.com/docker-hub/repos/manage/hub-images/oci-artifacts/#push-a-volume).

1. Sign in to Docker Desktop.

2. In the Docker Dashboard, select **Volumes**.

3. Select the **jupyter-data** volume by selecting the name.

4. Select the **Exports** tab.

5. Select **Quick export**.

6. For **Location**, select **Registry**.

7. In the text box under **Registry**, specify your Docker ID, a name for the volume, and a tag. For example, `YOUR-USERNAME/jupyter-data:latest`.

8. Select **Save**.

9. Verify that you exported the volume to Docker Hub.

   1. Go to [Docker Hub](https://hub.docker.com).
   2. Select **My Hub** > **Repositories**.
   3. View the **Last pushed** time for your repository.

Other users can now download and import your volume. To import the volume and then run it with your image:

1. Sign in to Docker Desktop.
2. In the Docker Dashboard, select **Volumes**.
3. Select **Create** to create a new volume.
4. Specify a name for the new volume. For this example, use `jupyter-data-2`.
5. Select **Create**.
6. In the list of volumes, select the **jupyter-data-2** volume by selecting the name.
7. Select **Import**.
8. For **Location**, select **Registry**.
9. In the text box under **Registry**, specify the same name as the repository that you exported your volume to. For example, `YOUR-USERNAME/jupyter-data:latest`.
10. Select **Import**.
11. In a terminal, run `docker run` to run your image with the imported volume. Replace `YOUR-USER-NAME` with your Docker ID.

```console
$ docker run --rm -p 8889:8888 -v jupyter-data-2:/home/jovyan/work YOUR-USER-NAME/my-jupyter-image start-notebook.py --NotebookApp.token='my-token'
```

## [Summary](#summary)

In this guide, you learned how to leverage Docker and JupyterLab to create reproducible data science environments, facilitating the development and sharing of data science projects. This included, running a personal JupyterLab server, customizing the environment with necessary tools and packages, and sharing notebooks and environments with other data scientists.

Related information:

* [Dockerfile reference](/reference/dockerfile/)
* [Compose file reference](/reference/compose-file/)
* [Docker CLI reference](https://docs.docker.com/reference/cli/docker/)
* [Jupyter Docker Stacks docs](https://jupyter-docker-stacks.readthedocs.io/en/latest/)

----
url: https://docs.docker.com/guides/lab-compose-quickstart/
----

[Lab: Docker Compose Quickstart](https://docs.docker.com/guides/lab-compose-quickstart/)

Hands-on lab: Define and run a multi-container app with Docker Compose. Progress from a bare compose.yaml through health checks, live development with watch mode, data persistence, and modular Compose file composition.

Labs

45 minutes

Resources:

* [Docker Compose docs](/compose/)
* [Compose watch mode](/compose/how-tos/file-watch/)
* [Labspace repository](https://github.com/dockersamples/labspace-compose-quickstart)

[« Back to all guides](/guides/)

# Lab: Docker Compose Quickstart

***

Table of contents

***

Build a Python Flask and Redis hit-counter app using Docker Compose, starting from a bare `compose.yaml` and progressively adding production-quality features at each step.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-compose-quickstart up -d
   ```

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

By the end of this Labspace, you will have completed the following:

* Define a multi-service application in a `compose.yaml` file and manage it with Compose commands
* Control service startup order using health checks and `depends_on` conditions
* Iterate on code without manual rebuilds using Compose watch mode
* Persist data across container restarts with named volumes
* Modularize a stack across multiple files using the `include` directive
* Use `config`, `logs`, and `exec` to inspect and debug a running stack

## [Modules](#modules)

| # | Module                           | Description                                                           |
| - | -------------------------------- | --------------------------------------------------------------------- |
| 1 | Introduction                     | Tour the starter app and verify the environment                       |
| 2 | Defining Services                | Write the first `compose.yaml` and bring up the Flask and Redis stack |
| 3 | Health Checks & Startup Order    | Add a Redis healthcheck and `depends_on` to eliminate race conditions |
| 4 | Live Development with Watch Mode | Configure watch mode to sync code changes without manual rebuilds     |
| 5 | Persistence & Debugging          | Add a named volume so Redis data survives `docker compose down`       |
| 6 | Using Multiple Compose Files     | Extract Redis into `infra.yaml` and compose files with `include`      |
| 7 | Additional Commands              | Use `config`, `logs -f`, and `exec` to inspect the running stack      |
| 8 | Recap                            | Review what was built and explore next steps                          |

----
url: https://docs.docker.com/reference/cli/docker/compose/run/
----

# docker compose run

***

| Description | Run a one-off command on a service                         |
| ----------- | ---------------------------------------------------------- |
| Usage       | `docker compose run [OPTIONS] SERVICE [COMMAND] [ARGS...]` |

## [Description](#description)

Runs a one-time command against a service.

The following command starts the `web` service and runs `bash` as its command:

```console
$ docker compose run web bash
```

Commands you use with run start in new containers with configuration defined by that of the service, including volumes, links, and other details. However, there are two important differences:

First, the command passed by `run` overrides the command defined in the service configuration. For example, if the `web` service configuration is started with `bash`, then `docker compose run web python app.py` overrides it with `python app.py`.

The second difference is that the `docker compose run` command does not create any of the ports specified in the service configuration. This prevents port collisions with already-open ports. If you do want the service’s ports to be created and mapped to the host, specify the `--service-ports`

```console
$ docker compose run --service-ports web python manage.py shell
```

Alternatively, manual port mapping can be specified with the `--publish` or `-p` options, just as when using docker run:

```console
$ docker compose run --publish 8080:80 -p 2022:22 -p 127.0.0.1:2021:21 web python manage.py shell
```

If you start a service configured with links, the run command first checks to see if the linked service is running and starts the service if it is stopped. Once all the linked services are running, the run executes the command you passed it. For example, you could run:

```console
$ docker compose run db psql -h db -U docker
```

This opens an interactive PostgreSQL shell for the linked `db` container.

If you do not want the run command to start linked containers, use the `--no-deps` flag:

```console
$ docker compose run --no-deps web python manage.py shell
```

If you want to remove the container after running while overriding the container’s restart policy, use the `--rm` flag:

```console
$ docker compose run --rm web python manage.py db upgrade
```

This runs a database upgrade script, and removes the container when finished running, even if a restart policy is specified in the service configuration.

## [Options](#options)

| Option                | Default  | Description                                                                       |
| --------------------- | -------- | --------------------------------------------------------------------------------- |
| `--build`             |          | Build image before starting container                                             |
| `--cap-add`           |          | Add Linux capabilities                                                            |
| `--cap-drop`          |          | Drop Linux capabilities                                                           |
| `-d, --detach`        |          | Run container in background and print container ID                                |
| `--entrypoint`        |          | Override the entrypoint of the image                                              |
| `-e, --env`           |          | Set environment variables                                                         |
| `--env-from-file`     |          | Set environment variables from file                                               |
| `-i, --interactive`   | `true`   | Keep STDIN open even if not attached                                              |
| `-l, --label`         |          | Add or override a label                                                           |
| `--name`              |          | Assign a name to the container                                                    |
| `-T, --no-TTY`        | `true`   | Disable pseudo-TTY allocation (default: auto-detected)                            |
| `--no-deps`           |          | Don't start linked services                                                       |
| `-p, --publish`       |          | Publish a container's port(s) to the host                                         |
| `--pull`              | `policy` | Pull image before running ("always"\|"missing"\|"never")                          |
| `-q, --quiet`         |          | Don't print anything to STDOUT                                                    |
| `--quiet-build`       |          | Suppress progress output from the build process                                   |
| `--quiet-pull`        |          | Pull without printing progress information                                        |
| `--remove-orphans`    |          | Remove containers for services not defined in the Compose file                    |
| `--rm`                |          | Automatically remove the container when it exits                                  |
| `-P, --service-ports` |          | Run command with all service's ports enabled and mapped to the host               |
| `--use-aliases`       |          | Use the service's network useAliases in the network(s) the container connects to  |
| `-u, --user`          |          | Run as specified username or uid                                                  |
| `-v, --volume`        |          | Bind mount a volume                                                               |
| `-w, --workdir`       |          | Working directory inside the container                                            |

----
url: https://docs.docker.com/dhi/core-concepts/sbom/
----

# Software Bill of Materials (SBOMs)

***

Table of contents

***

## [What is an SBOM?](#what-is-an-sbom)

An SBOM is a detailed inventory that lists all components, libraries, and dependencies used in building a software application. It provides transparency into the software supply chain by documenting each component's version, origin, and relationship to other components. Think of it as a "recipe" for your software, detailing every ingredient and how they come together.

Metadata included in an SBOM for describing software artifacts may include:

* Name of the artifact
* Version
* License type
* Authors
* Unique package identifier

## [Why are SBOMs important?](#why-are-sboms-important)

In today's software landscape, applications often comprise numerous components from various sources, including open-source libraries, third-party services, and proprietary code. This complexity can obscure visibility into potential vulnerabilities and complicate compliance efforts. SBOMs address these challenges by providing a detailed inventory of all components within an application.

The significance of SBOMs is underscored by several key factors:

* Enhanced transparency: SBOMs offer a comprehensive view of all components that constitute an application, enabling organizations to identify and assess risks associated with third-party libraries and dependencies.

* Proactive vulnerability management: By maintaining an up-to-date SBOM, organizations can swiftly identify and address vulnerabilities in software components, reducing the window of exposure to potential exploits.

* Regulatory compliance: Many regulations and industry standards now require organizations to maintain control over the software components they use. An SBOM facilitates compliance by providing a clear and accessible record.

* Improved incident response: In the event of a security breach, an SBOM enables organizations to quickly identify affected components and take appropriate action, minimizing potential damage.

## [Docker Hardened Image SBOMs](#docker-hardened-image-sboms)

Docker Hardened Images come with built-in SBOMs, ensuring that every component in the image is documented and verifiable. These SBOMs are cryptographically signed, providing a tamper-evident record of the image's contents. This integration simplifies audits and enhances trust in the software supply chain.

## [View SBOMs in Docker Hardened Images](#view-sboms-in-docker-hardened-images)

To view the SBOM of a Docker Hardened Image, you can use the `docker scout sbom` command. Replace `<image-name>:<tag>` with the image name and tag.

```console
$ docker scout sbom dhi.io/<image-name>:<tag>
```

## [Verify the SBOM of a Docker Hardened Image](#verify-the-sbom-of-a-docker-hardened-image)

Since Docker Hardened Images come with signed SBOMs, you can use Docker Scout to verify the authenticity and integrity of the SBOM attached to the image. This ensures that the SBOM has not been tampered with and that the image's contents are trustworthy.

To verify the SBOM of a Docker Hardened Image using Docker Scout, use the following command:

```console
$ docker scout attest get dhi.io/<image-name>:<tag> \
   --predicate-type https://scout.docker.com/sbom/v0.1 --verify --platform <platform>
```

For example, to verify the SBOM attestation for the `node:20.19-debian12` image:

```console
$ docker scout attest get dhi.io/node:20.19-debian12 \
   --predicate-type https://scout.docker.com/sbom/v0.1 --verify --platform linux/amd64
```

## [Resources](#resources)

For more details about SBOM attestations and Docker Build, see [SBOM attestations](/build/metadata/attestations/sbom/).

To learn more about Docker Scout and working with SBOMs, see [Docker Scout SBOMs](https://docs.docker.com/scout/how-tos/view-create-sboms/).

----
url: https://docs.docker.com/reference/cli/docker/sandbox/stop/
----

# docker sandbox stop

***

| Description | Stop one or more sandboxes without removing them |
| ----------- | ------------------------------------------------ |
| Usage       | `docker sandbox stop SANDBOX [SANDBOX...]`       |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Stop one or more sandboxes without removing them. The sandboxes can be restarted later.

## [Examples](#examples)

### [Stop a sandbox](#stop-a-sandbox)

```console
$ docker sandbox stop my-sandbox
my-sandbox
```

### [Stop multiple sandboxes](#stop-multiple-sandboxes)

```console
$ docker sandbox stop sandbox1 sandbox2
sandbox1
sandbox2
```

### [Stop all running sandboxes](#stop-all-running-sandboxes)

```console
$ docker sandbox stop $(docker sandbox ls -q)
```

----
url: https://docs.docker.com/guides/reactjs/develop/
----

# Use containers for React.js development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize React.js application](https://docs.docker.com/guides/reactjs/containerize/).

***

## [Overview](#overview)

In this section, you'll learn how to set up both production and development environments for your containerized React.js application using Docker Compose. This setup allows you to serve a static production build via Nginx and to develop efficiently inside containers using a live-reloading dev server with Compose Watch.

You’ll learn how to:

* Configure separate containers for production and development
* Enable automatic file syncing using Compose Watch in development
* Debug and live-preview your changes in real-time without manual rebuilds

***

## [Automatically update services (development mode)](#automatically-update-services-development-mode)

Use Compose Watch to automatically sync source file changes into your containerized development environment. This provides a seamless, efficient development experience without needing to restart or rebuild containers manually.

## [Step 1: Create a development Dockerfile](#step-1-create-a-development-dockerfile)

Create a file named `Dockerfile.dev` in your project root with the following content:

```dockerfile
# =========================================
# Stage 1: Develop the React.js Application
# =========================================
ARG NODE_VERSION=24.12.0-alpine

# Use a lightweight Node.js image for development
FROM node:${NODE_VERSION} AS dev

# Set the working directory inside the container
WORKDIR /app

# Copy package-related files first to leverage Docker's caching mechanism
COPY package.json package-lock.json* ./

# Install project dependencies
RUN --mount=type=cache,target=/root/.npm npm install

# Copy the rest of the application source code into the container
COPY . .

# Expose the port used by the Vite development server
EXPOSE 5173

# Use a default command, can be overridden in Docker compose.yml file
CMD ["npm", "run", "dev"]
```

This file sets up a lightweight development environment for your React app using the dev server.

### [Step 2: Update your `compose.yaml` file](#step-2-update-your-composeyaml-file)

Open your `compose.yaml` file and define two services: one for production (`react-prod`) and one for development (`react-dev`).

Here’s an example configuration for a React.js application:

```yaml
services:
  react-prod:
    build:
      context: .
      dockerfile: Dockerfile
    image: docker-reactjs-sample
    ports:
      - "8080:8080"

  react-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "5173:5173"
    develop:
      watch:
        - action: sync
          path: .
          target: /app
```

* The `react-prod` service builds and serves your static production app using Nginx.
* The `react-dev` service runs your React development server with live reload and hot module replacement.
* `watch` triggers file sync with Compose Watch.

> Note
>
> For more details, see the official guide: [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

### [Step 3: Update vite.config.ts to ensure it works properly inside Docker](#step-3-update-viteconfigts-to-ensure-it-works-properly-inside-docker)

To make Vite’s development server work reliably inside Docker, you need to update your vite.config.ts with the correct settings.

Open the `vite.config.ts` file in your project root and update it as follows:

```ts
/// <reference types="vitest" />

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  base: "/",
  plugins: [react()],
  server: {
    host: true,
    port: 5173,
    strictPort: true,
  },
});
```

> Note
>
> The `server` options in `vite.config.ts` are essential for running Vite inside Docker:
>
> * `host: true` allows the dev server to be accessible from outside the container.
> * `port: 5173` sets a consistent development port (must match the one exposed in Docker).
> * `strictPort: true` ensures Vite fails clearly if the port is unavailable, rather than switching silently.
>
> For full details, refer to the [Vite server configuration docs](https://vitejs.dev/config/server-options.html).

After completing the previous steps, your project directory should now contain the following files:

```text
├── docker-reactjs-sample/
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ ├── .dockerignore
│ ├── compose.yaml
│ └── nginx.conf
```

### [Step 4: Start Compose Watch](#step-4-start-compose-watch)

Run the following command from your project root to start your container in watch mode:

```console
$ docker compose watch react-dev
```

### [Step 5: Test Compose Watch with React](#step-5-test-compose-watch-with-react)

To verify that Compose Watch is working correctly:

1. Open the `src/App.tsx` file in your text editor.

2. Locate the following line:

   ```html
   <h1>Vite + React</h1>
   ```

3. Change it to:

   ```html
   <h1>Hello from Docker Compose Watch</h1>
   ```

4. Save the file.

5. Open your browser at <http://localhost:5173>.

You should see the updated text appear instantly, without needing to rebuild the container manually. This confirms that file watching and automatic synchronization are working as expected.

***

## [Summary](#summary)

In this section, you set up a complete development and production workflow for your React.js application using Docker and Docker Compose.

Here's what you achieved:

* Created a `Dockerfile.dev` to streamline local development with hot reloading
* Defined separate `react-dev` and `react-prod` services in your `compose.yaml` file
* Enabled real-time file syncing using Compose Watch for a smoother development experience
* Verified that live updates work seamlessly by modifying and previewing a component

With this setup, you're now equipped to build, run, and iterate on your React.js app entirely within containers—efficiently and consistently across environments.

***

In the next section, you'll learn how to run unit tests for your React.js application inside Docker containers. This ensures consistent testing across all environments and removes dependencies on local machine setup.

[Run React.js tests in a container »](https://docs.docker.com/guides/reactjs/run-tests/)

----
url: https://docs.docker.com/enterprise/enterprise-deployment/use-intune/
----

# Deploy with Intune

***

Table of contents

***

For: Administrators

Learn how to deploy Docker Desktop on Windows and macOS devices using Microsoft Intune. It covers app creation, installer configuration, and assignment to users or devices.

1. Sign in to your Intune admin center.

2. Add a new app. Select **Apps**, then **Windows**, then **Add**.

3. For the app type, select **Windows app (Win32)**

4. Select the `intunewin` package.

5. Fill in the required details, such as the description, publisher, or app version and then select **Next**.

6. Optional: On the **Program** tab, you can update the **Install command** field to suit your needs. The field is pre-populated with `msiexec /i "DockerDesktop.msi" /qn`. See the [Common installation scenarios](https://docs.docker.com/enterprise/enterprise-deployment/msi-install-and-configure/) for examples on the changes you can make.

   > Tip
   >
   > It's recommended you configure the Intune deployment to schedule a reboot of the machine on successful installs.
   >
   > This is because the Docker Desktop installer installs Windows features depending on your engine selection and also updates the membership of the `docker-users` local group.
   >
   > You may also want to set Intune to determine behaviour based on return codes and watch for a return code of `3010`. Return code 3010 means the installation succeeded but a reboot is required.

7. Complete the remaining tabs, then review and create the app.

First, upload the package:

1. Sign in to your Intune admin center.
2. Add a new app. Select **Apps**, then **macOS**, then **Add**.
3. Select **Line-of-business app** and then **Select**.
4. Upload the `Docker.pkg` file and fill in the required details.

Next, assign the app:

1. Once the app is added, navigate to **Assignments** in Intune.
2. Select **Add group** and choose the user or device groups you want to assign the app to.
3. Select **Save**.

## [Additional resources](#additional-resources)

* [Explore the FAQs](https://docs.docker.com/enterprise/enterprise-deployment/faq/).
* Learn how to [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) for your users.

----
url: https://docs.docker.com/guides/golang/deploy/
----

# Test your Go deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Build your Go image](https://docs.docker.com/guides/golang/build-images/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your project directory, create a file named `docker-go-kubernetes.yaml`. Open the file in an IDE or text editor and add the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the name of the repository that you created in [Configure CI/CD for your Go application](https://docs.docker.com/guides/golang/configure-ci-cd/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    service: server
  name: server
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: server
  strategy: {}
  template:
    metadata:
      labels:
        service: server
    spec:
      initContainers:
        - name: wait-for-db
          image: busybox:1.28
          command:
            [
              "sh",
              "-c",
              'until nc -zv db 5432; do echo "waiting for db"; sleep 2; done;',
            ]
      containers:
        - env:
            - name: PGDATABASE
              value: mydb
            - name: PGPASSWORD
              value: whatever
            - name: PGHOST
              value: db
            - name: PGPORT
              value: "5432"
            - name: PGUSER
              value: postgres
          image: DOCKER_USERNAME/REPO_NAME
          name: server
          imagePullPolicy: Always
          ports:
            - containerPort: 8080
              hostPort: 8080
              protocol: TCP
          resources: {}
      restartPolicy: Always
status: {}
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    service: db
  name: db
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: db
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        service: db
    spec:
      containers:
        - env:
            - name: POSTGRES_DB
              value: mydb
            - name: POSTGRES_PASSWORD
              value: whatever
            - name: POSTGRES_USER
              value: postgres
          image: postgres:18
          name: db
          ports:
            - containerPort: 5432
              protocol: TCP
          resources: {}
      restartPolicy: Always
status: {}
---
apiVersion: v1
kind: Service
metadata:
  labels:
    service: server
  name: server
  namespace: default
spec:
  type: NodePort
  ports:
    - name: "8080"
      port: 8080
      targetPort: 8080
      nodePort: 30001
  selector:
    service: server
status:
  loadBalancer: {}
---
apiVersion: v1
kind: Service
metadata:
  labels:
    service: db
  name: db
  namespace: default
spec:
  ports:
    - name: "5432"
      port: 5432
      targetPort: 5432
  selector:
    service: db
status:
  loadBalancer: {}
```

In this Kubernetes YAML file, there are four objects, separated by the `---`. In addition to a Service and Deployment for the database, the other two objects are:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your Go application](https://docs.docker.com/guides/golang/configure-ci-cd/).
* A NodePort service, which will route traffic from port 30001 on your host to port 8080 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to the project directory and deploy your application to Kubernetes.

   ```console
   $ kubectl apply -f docker-go-kubernetes.yaml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```shell
   deployment.apps/db created
   service/db created
   deployment.apps/server created
   service/server created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```shell
   NAME     READY   UP-TO-DATE   AVAILABLE   AGE
   db       1/1     1            1           76s
   server   1/1     1            1           76s
   ```

   This indicates all of the pods are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```shell
   NAME         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
   db           ClusterIP   10.96.156.90    <none>        5432/TCP         2m8s
   kubernetes   ClusterIP   10.96.0.1       <none>        443/TCP          164m
   server       NodePort    10.102.94.225   <none>        8080:30001/TCP   2m8s
   ```

   In addition to the default `kubernetes` service, you can see your `server` service and `db` service. The `server` service is accepting traffic on port 30001/TCP.

3. Open a terminal and curl your application to verify that it's working.

   ```console
   $ curl --request POST \
     --url http://localhost:30001/send \
     --header 'content-type: application/json' \
     --data '{"value": "Hello, Oliver!"}'
   ```

   You should get the following message back.

   ```json
   { "value": "Hello, Oliver!" }
   ```

4. Run the following command to tear down your application.

   ```console
   $ kubectl delete -f docker-go-kubernetes.yaml
   ```

----
url: https://docs.docker.com/reference/cli/docker/scout/cache/df/
----

# docker scout cache df

***

| Description | Show Docker Scout disk usage |
| ----------- | ---------------------------- |
| Usage       | `docker scout cache df`      |

## [Description](#description)

Docker Scout uses a temporary cache storage for generating image SBOMs. The cache helps avoid regenerating or fetching resources unnecessarily.

This `docker scout cache df` command shows the cached data on the host. Each cache entry is identified by the digest of the image.

You can use the `docker scout cache prune` command to delete cache data at any time.

## [Examples](#examples)

### [List temporary and cache files](#list-temporary-and-cache-files)

```console
$ docker scout cache df
Docker Scout temporary directory to generate SBOMs is located at:
   /var/folders/dw/d6h9w2sx6rv3lzwwgrnx7t5h0000gp/T/docker-scout
   this path can be configured using the DOCKER_SCOUT_CACHE_DIR environment variable

                               Image Digest                               │ Size
──────────────────────────────────────────────────────────────────────────┼────────
  sha256:c41ab5c992deb4fe7e5da09f67a8804a46bd0592bfdf0b1847dde0e0889d2bff │ 21 kB

Total: 21 kB


Docker Scout cached SBOMs are located at:
   /Users/user/.docker/scout/sbom

                               Image Digest                               │ Size of SBOM
──────────────────────────────────────────────────────────────────────────┼───────────────
  sha256:02bb6f428431fbc2809c5d1b41eab5a68350194fb508869a33cb1af4444c9b11 │ 42 kB
  sha256:03fc002fe4f370463a8f04d3a288cdffa861e462fc8b5be44ab62b296ad95183 │ 100 kB
  sha256:088134dd33e4a2997480a1488a41c11abebda465da5cf7f305a0ecf8ed494329 │ 194 kB
  sha256:0b80b2f17aff7ee5bfb135c69d0d6fe34070e89042b7aac73d1abcc79cfe6759 │ 852 kB
  sha256:0c9e8abe31a5f17d84d5c85d3853d2f948a4f126421e89e68753591f1b6fedc5 │ 930 kB
  sha256:0d49cae0723c8d310e413736b5e91e0c59b605ade2546f6e6ef8f1f3ddc76066 │ 510 kB
  sha256:0ef04748d071c2e631bb3edce8f805cb5512e746b682c83fdae6d8c0b243280b │ 1.0 MB
  sha256:13fd22925b638bb7d2131914bb8f8b0f5f582bee364aec682d9e7fe722bb486a │ 42 kB
  sha256:174c41d4fbc7f63e1f2bb7d2f7837318050406f2f27e5073a84a84f18b48b883 │ 115 kB

Total: 4 MB
```

----
url: https://docs.docker.com/reference/cli/docker/buildx/dap/build/
----

# docker buildx dap build

***

| Description | Start a build                                        |
| ----------- | ---------------------------------------------------- |
| Usage       | `docker buildx dap build [OPTIONS] PATH \| URL \| -` |

## [Description](#description)

Start a debug session using the [debug adapter protocol](https://microsoft.github.io/debug-adapter-protocol/overview) to communicate with the debugger UI.

Arguments are the same as the `build`

> Note
>
> `buildx dap build` command may receive backwards incompatible features in the future if needed. We are looking for feedback on improving the command and extending the functionality further.

## [Options](#options)

| Option              | Default | Description                                                                                                                                       |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--add-host`        |         | Add a custom host-to-IP mapping (format: `host:ip`)                                                                                               |
| `--allow`           |         | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`, `device`)                                                          |
| `--annotation`      |         | Add annotation to the image                                                                                                                       |
| `--attest`          |         | Attestation parameters (format: `type=sbom,generator=image`)                                                                                      |
| `--build-arg`       |         | Set build-time variables                                                                                                                          |
| `--build-context`   |         | Additional build contexts (e.g., name=path)                                                                                                       |
| `--cache-from`      |         | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`)                                                                     |
| `--cache-to`        |         | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`)                                                                 |
| `--call`            | `build` | Set method for evaluating build (`check`, `outline`, `targets`)                                                                                   |
| `--cgroup-parent`   |         | Set the parent cgroup for the `RUN` instructions during build                                                                                     |
| `--check`           |         | Shorthand for `--call=check`                                                                                                                      |
| `-f, --file`        |         | Name of the Dockerfile (default: `PATH/Dockerfile`)                                                                                               |
| `--iidfile`         |         | Write the image ID to a file                                                                                                                      |
| `--label`           |         | Set metadata for an image                                                                                                                         |
| `--load`            |         | Shorthand for `--output=type=docker`                                                                                                              |
| `--metadata-file`   |         | Write build result metadata to a file                                                                                                             |
| `--network`         |         | Set the networking mode for the `RUN` instructions during build                                                                                   |
| `--no-cache`        |         | Do not use cache when building the image                                                                                                          |
| `--no-cache-filter` |         | Do not cache specified stages                                                                                                                     |
| `-o, --output`      |         | Output destination (format: `type=local,dest=path`)                                                                                               |
| `--platform`        |         | Set target platform for build                                                                                                                     |
| `--policy`          |         | Policy configuration (format: `filename=path[,filename=path][,reset=true\|false][,disabled=true\|false][,strict=true\|false][,log-level=level]`)  |
| `--progress`        | `auto`  | Set type of progress output (`auto`, `none`, `plain`, `quiet`, `rawjson`, `tty`). Use plain to show container output                              |
| `--provenance`      |         | Shorthand for `--attest=type=provenance`                                                                                                          |
| `--pull`            |         | Always attempt to pull all referenced images                                                                                                      |
| `--push`            |         | Shorthand for `--output=type=registry,unpack=false`                                                                                               |
| `-q, --quiet`       |         | Suppress the build output and print image ID on success                                                                                           |
| `--sbom`            |         | Shorthand for `--attest=type=sbom`                                                                                                                |
| `--secret`          |         | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`)                                                                         |
| `--shm-size`        |         | Shared memory size for build containers                                                                                                           |
| `--ssh`             |         | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`)                                               |
| `-t, --tag`         |         | Image identifier (format: `[registry/]repository[:tag]`)                                                                                          |
| `--target`          |         | Set the target build stage to build                                                                                                               |
| `--ulimit`          |         | Ulimit options                                                                                                                                    |

## [Examples](#examples)

### [Launch request arguments](#launch-config)

The following [launch request arguments](https://microsoft.github.io/debug-adapter-protocol/specification#Requests_Launch) are supported. These are sent as a JSON body as part of the launch request.

| Name          | Type      | Default      | Description                                                                 |
| ------------- | --------- | ------------ | --------------------------------------------------------------------------- |
| `dockerfile`  | `string`  | `Dockerfile` | Name of the Dockerfile                                                      |
| `contextPath` | `string`  | `.`          | Set the context path for the build (normally the first positional argument) |
| `target`      | `string`  |              | Set the target build stage to build                                         |
| `stopOnEntry` | `boolean` | `false`      | Stop on the first instruction                                               |

### [Additional Arguments](#additional-args)

Command line arguments may be passed to the debug adapter the same way they would be passed to the normal build command and they will set the value. Launch request arguments that are set will override command line arguments if they are present.

A debug extension should include an `args` and `builder` entry in the launch configuration. These will modify the arguments passed to the binary for the tool invocation. `builder` will add `--builder <arg>` directly after the executable and `args` will append to the end of the tool invocation. For example, a launch configuration in Visual Studio Code with the following:

```json
{
    "args": ["--build-arg", "FOO=AAA"]
    "builder": ["mybuilder"]
}
```

This should cause the debug adapter to be invoked as `docker buildx --builder mybuilder dap build --build-arg FOO=AAA`.

----
url: https://docs.docker.com/reference/cli/docker/container/inspect/
----

# docker container inspect

***

| Description | Display detailed information on one or more containers        |
| ----------- | ------------------------------------------------------------- |
| Usage       | `docker container inspect [OPTIONS] CONTAINER [CONTAINER...]` |

## [Description](#description)

Display detailed information on one or more containers

## [Options](#options)

| Option         | Default | Description                                                                                                                                                                                                                             |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-f, --format` |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-s, --size`   |         | Display total file sizes                                                                                                                                                                                                                |

----
url: https://docs.docker.com/guides/traefik/
----

[HTTP routing with Traefik](https://docs.docker.com/guides/traefik/)

Use Traefik to easily route traffic between multiple containers or non-containerized workloads

Networking Docker Hardened Images

20 minutes

[« Back to all guides](/guides/)

# HTTP routing with Traefik

***

Table of contents

***

## [Introduction](#introduction)

During local development, it’s quite common to need to run multiple HTTP services. You might have both an API and a frontend app, a WireMock service to mock data endpoints, or a database visualizer (such as phpMyAdmin or pgAdmin). In many development setups, these services are exposed on different ports, which then requires you to remember what’s on what port but can also introduce other problems (such as CORS).

A reverse proxy can dramatically simplify this setup by being the single exposed service and then routing requests to the appropriate service based on the request URL (either by path or hostname). [Traefik](https://traefik.io/traefik/) is a modern, cloud-native reverse proxy and load balancer that makes developing and deploying multi-service applications easier. This guide will show you how to use Traefik with Docker to enhance your development environment.

In this guide, you will learn how to:

1. Start Traefik with Docker
2. Configure routing rules to split traffic between two containers
3. Use Traefik in a containerized development environment
4. Use Traefik to send requests to non-containerized workloads

## [Prerequisites](#prerequisites)

The following prerequisites are required to follow along with this how-to guide:

* [Docker Desktop](https://www.docker.com/products/docker-desktop/)
* [Node.js](https://nodejs.org/en/download/package-manager) and [yarn](https://yarnpkg.com/)
* Basic of Docker

## [Using Traefik with Docker](#using-traefik-with-docker)

One of the unique features of Traefik is its ability to be configured in many ways. When using the Docker provider, Traefik gets its configuration from other running containers using [labels](https://docs.docker.com/config/labels-custom-metadata/). Traefik will watch engine events (for container starts and stops), extract the labels, and update its configuration.

While there are [many Traefik-monitored labels](https://doc.traefik.io/traefik/routing/providers/docker/), the two most common will be:

* `traefik.http.routers.<service-name>.rule` - used to indicate the routing rule ([view all of the available rules here](https://doc.traefik.io/traefik/routing/routers/#rule))
* `traefik.http.services.<service-name>.loadbalancer.server.port` - indicates the port Traefik should forward the request to. Note that this container port does not need to be exposed on your host machine ([read about port detection here](https://doc.traefik.io/traefik/providers/docker/#port-detection))

Let’s do a quick demo of starting Traefik and then configuring two additional containers to be accessible using different hostnames.

1. In order for two containers to be able to communicate with each other, they need to be on the same network. Create a network named `traefik-demo` using the `docker network create` command:

   ```console
   $ docker network create traefik-demo
   ```

2. Start a Traefik container using one of the following methods. These commands exposes Traefik on port 80, mounts the Docker socket (which is used to monitor containers to update configuration), and passes the `--providers.docker` argument to configure Traefik to use the Docker provider.

   Docker Hardened Images (DHI) for Traefik are available on [Docker Hub](https://hub.docker.com/hardened-images/catalog/dhi/traefik). If you haven't authenticated yet, first run:

   ```bash
   $ docker login dhi.io
   ```

   Then start a container using the Hardened image:

   ```console
   $ docker run -d --network=traefik-demo \
     -p 80:80 \
     -v /var/run/docker.sock:/var/run/docker.sock \
     dhi.io/traefik:3.6.2 \
     --providers.docker
   ```

   You can also use the official image from Docker Hub:

   ```console
   $ docker run -d --network=traefik-demo \
     -p 80:80 \
     -v /var/run/docker.sock:/var/run/docker.sock \
     traefik:v3.6.2 \
     --providers.docker
   ```

3. Now, start a simple Nginx container and define the labels Traefik is watching for to configure the HTTP routing. Note that the Nginx container is not exposing any ports.

   Docker Hardened Images (DHI) for Nginx are available on [Nginx DHI image](https://hub.docker.com/hardened-images/catalog/dhi/nginx). If you haven't authenticated yet, first run:

   ```bash
   $ docker login dhi.io
   ```

   ```console
   $ docker run -d --network=traefik-demo \
     --label 'traefik.http.routers.nginx.rule=Host(`nginx.localhost`)' \
     dhi.io/nginx:1.29.3
   ```

   You can also run the official Nginx image as follows:

   ```console
   $ docker run -d --network=traefik-demo \
     --label 'traefik.http.routers.nginx.rule=Host(`nginx.localhost`)' \
     nginx:1.29.3
   ```

   Once the container starts, open your browser to <http://nginx.localhost> to see the app (all Chromium-based browsers route \*.localhost requests locally with no additional setup).

4. Start a second application that will use a different hostname.

   ```console
   $ docker run -d --network=traefik-demo --label 'traefik.http.routers.welcome.rule=Host(`welcome.localhost`)' docker/welcome-to-docker
   ```

   Once the container starts, open your browser to <http://welcome.localhost>. You should see a “Welcome to Docker” website.

## [Using Traefik in development](#using-traefik-in-development)

Now that you’ve experienced Traefik, it’s time to try using it in a development environment. In this example, you will use a sample application that has a split frontend and backend. This app stack has the following configuration:

1. All requests to /api to go to the API service
2. All other requests to localhost go to the frontend client
3. Since the app uses MySQL, db.localhost should provide phpMyAdmin to make it easy to access the database during development

The application can be accessed on GitHub at [dockersamples/easy-http-routing-with-traefik](https://github.com/dockersamples/easy-http-routing-with-traefik).

1. In the `compose.yaml` file, Traefik is using the following configuration:

   ```yaml
   services:
     proxy:
       image: dhi.io/traefik:3.6.2
       command: --providers.docker
       ports:
         - 80:80
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
   ```

   ```yaml
   services:
     proxy:
       image: traefik:v3.6.2
       command: --providers.docker
       ports:
         - 80:80
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
   ```

   Note that this is essentially the same configuration as used earlier, but now in a Compose syntax.

2. The client service has the following configuration, which will start the container and provide it with the labels to receive requests at localhost.

   Docker Hardened Images (DHI) for Nginx are available on [Nginx DHI image](https://hub.docker.com/hardened-images/catalog/dhi/nginx).

   If you haven't authenticated yet, first run:

   ```bash
   $ docker login dhi.io
   ```

   You can use it as your base image as shown following:

   ```yaml
   services:
     # …
     client:
       image: dhi.io/nginx:1.29.3-alpine3.21
       volumes:
         - "./client:/usr/share/nginx/html"
       labels:
         traefik.http.routers.client.rule: "Host(`localhost`)"
   ```

   ```yaml
   services:
     # …
     client:
       image: nginx:1.29.3-alpine3.22
       volumes:
         - "./client:/usr/share/nginx/html"
       labels:
         traefik.http.routers.client.rule: "Host(`localhost`)"
   ```

3. The api service has a similar configuration, but you’ll notice the routing rule has two conditions - the host must be “localhost” and the URL path must have a prefix of “/api”. Since this rule is more specific, Traefik will evaluate it first compared to the client rule.

   ```yaml
   services:
     # …
     api:
       build: ./dev/api
       volumes:
         - "./api:/var/www/html/api"
       labels:
         traefik.http.routers.api.rule: "Host(`localhost`) && PathPrefix(`/api`)"
   ```

4. And finally, the `phpmyadmin` service is configured to receive requests for the hostname “db.localhost”. The service also has environment variables defined to automatically log in, making it a little easier to get into the app.

   ```yaml
   services:
     # …
     phpmyadmin:
       image: phpmyadmin:5.2.1
       labels:
         traefik.http.routers.db.rule: "Host(`db.localhost`)"
       environment:
         PMA_USER: root
         PMA_PASSWORD: password
   ```

5. Before starting the stack, stop the Nginx container if it is still running.

   And that’s it. Now, you only need to spin up the Compose stack with a `docker compose up` and all of the services and applications will be ready for development.

## [Sending traffic to non-containerized workloads](#sending-traffic-to-non-containerized-workloads)

In some situations, you may want to forward requests to applications not running in containers. In the following architecture diagram, the same application from before is used, but the API and React apps are now running natively on the host machine.

To accomplish this, Traefik will need to use another method to configure itself. The [File provider](https://doc.traefik.io/traefik/providers/file/) lets you define the routing rules in a YAML document. Here is an example file:

```yaml
http:
  routers:
    native-api:
      rule: "Host(`localhost`) && PathPrefix(`/api`)"
      service: native-api
    native-client:
      rule: "Host(`localhost`)"
      service: native-client

  services:
    native-api:
      loadBalancer:
        servers:
          - url: "http://host.docker.internal:3000/"
    native-client:
      loadBalancer:
        servers:
          - url: "http://host.docker.internal:5173/"
```

This configuration indicates that requests that for `localhost/api` will be forwarded to a service named `native-api`, which then forwards the request to <http://host.docker.internal:3000>. The hostname `host.docker.internal` is a name that Docker Desktop provides to send requests to the host machine.

With this file, the only change is to the Compose configuration for Traefik. There are specifically two things that have changed:

1. The configuration file is mounted into the Traefik container (the exact destination path is up to you)
2. The `command` is updated to add the file provider and point to the location of the configuration file

```yaml
services:
  proxy:
    image: dhi.io/traefik:3.6.2
    command: --providers.docker --providers.file.filename=/config/traefik-config.yaml --api.insecure
    ports:
      - 80:80
      - 8080:8080
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./dev/traefik-config.yaml:/config/traefik-config.yaml
```

```yaml
services:
  proxy:
    image: traefik:v3.6.2
    command: --providers.docker --providers.file.filename=/config/traefik-config.yaml --api.insecure
    ports:
      - 80:80
      - 8080:8080
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./dev/traefik-config.yaml:/config/traefik-config.yaml
```

### [Starting the example app](#starting-the-example-app)

To run the example app that forwards requests from Traefik to native-running apps, use the following steps:

1. If you have the Compose stack still running, stop it with the following command:

   ```console
   $ docker compose down
   ```

2. Start the application using the provided `compose-native.yaml` file:

   ```console
   $ docker compose -f compose-native.yaml up
   ```

   Opening <http://localhost> will return a 502 Bad Gateway because the other apps aren’t running yet.

3. Start the API by running the following steps:

   ```console
   cd api
   yarn install
   yarn dev
   ```

4. Start the frontend by running the following steps in a new terminal (starting from the root of the project):

   ```console
   cd client
   yarn install
   yarn dev
   ```

5. Open the app at <http://localhost>. You should see an app that fetches a message from <http://localhost/api/messages>. You can also open <http://db.localhost> to view or adjust the available messages directly from the Mongo database. Traefik will ensure the requests are properly routed to the correct container or application.

6. When you’re done, run `docker compose down` to stop the containers and stop the Yarn apps by hitting `ctrl+c`.

## [Recap](#recap)

Running multiple services doesn’t have to require tricky port configuration and a good memory. With tools like Traefik, it’s easy to launch the services you need and easily access them - whether they’re for the app itself (such as the frontend and backend) or for additional development tooling (such as phpMyAdmin).

----
url: https://docs.docker.com/engine/release-notes/26.1/
----

# Docker Engine 26.1 release notes

***

Table of contents

***

This page describes the latest changes, additions, known issues, and fixes for Docker Engine version 26.1.

For more information about:

* Deprecated and removed features, see [Deprecated Engine Features](https://docs.docker.com/engine/deprecated/).
* Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history/).

## [26.1.4](#2614)

*2024-06-05*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 26.1.4 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A26.1.4)
* [moby/moby, 26.1.4 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A26.1.4)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v26.1.4/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v26.1.4/docs/api/version-history.md).

### [Security](#security)

This release updates the Go runtime to 1.21.11 which contains security fixes for:

* [CVE-2024-24789](https://github.com/golang/go/issues/66869)
* [CVE-2024-24790](https://github.com/golang/go/issues/67680)
* A symlink time of check to time of use race condition during directory removal reported by [Addison Crump](https://github.com/addisoncrump).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* Fixed an issue where promoting a node immediately after another node was demoted could cause the promotion to fail. [moby/moby#47870](https://github.com/moby/moby/pull/47870)
* Prevent the daemon log from being spammed with `superfluous response.WriteHeader call ...` messages. [moby/moby#47843](https://github.com/moby/moby/pull/47843)
* Don't show empty hints when plugins return an empty hook message. [docker/cli#5083](https://github.com/docker/cli/pull/5083)
* Fix a compatibility issue with Visual Studio Container Tools. [docker/cli#5095](https://github.com/docker/cli/pull/5095)

### [Packaging updates](#packaging-updates)

* Update containerd (static binaries only) to [v1.7.17](https://github.com/containerd/containerd/releases/tag/v1.7.17). [moby/moby#47841](https://github.com/moby/moby/pull/47841)
* [CVE-2024-24789](https://github.com/golang/go/issues/66869), [CVE-2024-24790](https://github.com/golang/go/issues/67680): Update Go runtime to 1.21.11. [moby/moby#47904](https://github.com/moby/moby/pull/47904)
* Update Compose to [v2.27.1](https://github.com/docker/compose/releases/tag/v2.27.1). [docker/docker-ce-packages#1022](https://github.com/docker/docker-ce-packaging/pull/1022)
* Update Buildx to [v0.14.1](https://github.com/docker/buildx/releases/tag/v0.14.1). [docker/docker-ce-packages#1021](https://github.com/docker/docker-ce-packaging/pull/1021)

## [26.1.3](#2613)

*2024-05-16*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 26.1.3 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A26.1.3)
* [moby/moby, 26.1.3 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A26.1.3)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v26.1.3/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v26.1.3/docs/api/version-history.md).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

* Fix a regression that prevented the use of DNS servers within a `--internal` network. [moby/moby#47832](https://github.com/moby/moby/pull/47832)
* When the internal DNS server's own address is supplied as an external server address, ignore it to avoid unproductive recursion. [moby/moby#47833](https://github.com/moby/moby/pull/47833)

### [Packaging updates](#packaging-updates-1)

* Allow runc to kill containers when confined to the runc profile in AppArmor version 4.0.0 and later. [moby/moby#47829](https://github.com/moby/moby/pull/47829)

## [26.1.2](#2612)

*2024-05-08*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 26.1.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A26.1.2)
* [moby/moby, 26.1.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A26.1.2)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v26.1.2/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v26.1.2/docs/api/version-history.md).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

* Fix an issue where the CLI process would sometimes hang when a container failed to start. [docker/cli#5062](https://github.com/docker/cli/pull/5062)

### [Packaging updates](#packaging-updates-2)

* Update Go runtime to 1.21.10. [moby/moby#47806](https://github.com/moby/moby/pull/47806)

## [26.1.1](#2611)

*2024-04-30*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 26.1.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A26.1.1)
* [moby/moby, 26.1.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A26.1.1)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v26.1.1/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v26.1.1/docs/api/version-history.md).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-3)

* Fix `docker run -d` printing an `context canceled` spurious error when OpenTelemetry is configured. [docker/cli#5044](https://github.com/docker/cli/pull/5044)
* Experimental environment variable `DOCKER_BRIDGE_PRESERVE_KERNEL_LL=1` will prevent the daemon from removing the kernel-assigned link local address on a Linux bridge. [moby/moby#47775](https://github.com/moby/moby/pull/47775)
* Resolve an issue preventing container creation on hosts with a read-only `/proc/sys/net` filesystem. If IPv6 cannot be disabled on an interface due to this, either disable IPv6 by default on the host or ensure `/proc/sys/net` is read-write. To bypass the error, set the environment variable `DOCKER_ALLOW_IPV6_ON_IPV4_INTERFACE=1` before starting the Docker daemon. [moby/moby#47769](https://github.com/moby/moby/pull/47769)

> Note
>
> The `DOCKER_ALLOW_IPV6_ON_IPV4_INTERFACE` is added as a temporary fix and will be phased out in a future major release, when the IPv6 enablement process has been improved.

### [Packaging updates](#packaging-updates-3)

* Update BuildKit to [v0.13.2](https://github.com/moby/buildkit/releases/tag/v0.13.2). [moby/moby#47762](https://github.com/moby/moby/pull/47762)
* Update Compose to [v2.27.0](https://github.com/docker/compose/releases/tag/v2.27.0). [docker/docker-ce-packages#1017](https://github.com/docker/docker-ce-packaging/pull/1017)

## [26.1.0](#2610)

*2024-04-22*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 26.1.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A26.1.0)
* [moby/moby, 26.1.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A26.1.0)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v26.1.0/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v26.1.0/docs/api/version-history.md).

### [New](#new)

* Added configurable OpenTelemetry utilities and basic instrumentation to commands. For more information, see [OpenTelemetry for the Docker CLI](https://docs.docker.com/config/otel). [docker/cli#4889](https://github.com/docker/cli/pull/4889)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-4)

* Native Windows containers are configured with an internal DNS server for container name resolution, and external DNS servers for other lookups. Not all resolvers, including `nslookup`, fall back to the external resolvers when they get a `SERVFAIL` answer from the internal server. So, the internal DNS server can now be configured to forward requests to the external resolvers, by setting a `feature` option in the `daemon.json` file:

  ```json
  {
    "features": {
      "windows-dns-proxy": true
    }
  }
  ```

  [moby/moby#47584](https://github.com/moby/moby/pull/47584)

  > Note
  >
  > * This will be the new default behavior in Docker Engine 27.0.
  > * The `windows-dns-proxy` feature flag will be removed in a future release.

* Swarm: Fix `Subpath` not being passed to the container config. [moby/moby#47711](https://github.com/moby/moby/pull/47711)

* Classic builder: Fix cache miss on `WORKDIR <directory>/` build step (directory with a trailing slash). [moby/moby#47723](https://github.com/moby/moby/pull/47723)

* containerd image store: Fix `docker images` failing when any image in the store has unexpected target. [moby/moby#47738](https://github.com/moby/moby/pull/47738)

----
url: https://docs.docker.com/reference/cli/docker/container/
----

# docker container

***

| Description | Manage containers  |
| ----------- | ------------------ |
| Usage       | `docker container` |

## [Description](#description)

Manage containers.

## [Subcommands](#subcommands)

| Command                                                                                       | Description                                                                   |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [`docker container attach`](https://docs.docker.com/reference/cli/docker/container/attach/)   | Attach local standard input, output, and error streams to a running container |
| [`docker container commit`](https://docs.docker.com/reference/cli/docker/container/commit/)   | Create a new image from a container's changes                                 |
| [`docker container cp`](https://docs.docker.com/reference/cli/docker/container/cp/)           | Copy files/folders between a container and the local filesystem               |
| [`docker container create`](https://docs.docker.com/reference/cli/docker/container/create/)   | Create a new container                                                        |
| [`docker container diff`](https://docs.docker.com/reference/cli/docker/container/diff/)       | Inspect changes to files or directories on a container's filesystem           |
| [`docker container exec`](https://docs.docker.com/reference/cli/docker/container/exec/)       | Execute a command in a running container                                      |
| [`docker container export`](https://docs.docker.com/reference/cli/docker/container/export/)   | Export a container's filesystem as a tar archive                              |
| [`docker container inspect`](https://docs.docker.com/reference/cli/docker/container/inspect/) | Display detailed information on one or more containers                        |
| [`docker container kill`](https://docs.docker.com/reference/cli/docker/container/kill/)       | Kill one or more running containers                                           |
| [`docker container logs`](https://docs.docker.com/reference/cli/docker/container/logs/)       | Fetch the logs of a container                                                 |
| [`docker container ls`](https://docs.docker.com/reference/cli/docker/container/ls/)           | List containers                                                               |
| [`docker container pause`](https://docs.docker.com/reference/cli/docker/container/pause/)     | Pause all processes within one or more containers                             |
| [`docker container port`](https://docs.docker.com/reference/cli/docker/container/port/)       | List port mappings or a specific mapping for the container                    |
| [`docker container prune`](https://docs.docker.com/reference/cli/docker/container/prune/)     | Remove all stopped containers                                                 |
| [`docker container rename`](https://docs.docker.com/reference/cli/docker/container/rename/)   | Rename a container                                                            |
| [`docker container restart`](https://docs.docker.com/reference/cli/docker/container/restart/) | Restart one or more containers                                                |
| [`docker container rm`](https://docs.docker.com/reference/cli/docker/container/rm/)           | Remove one or more containers                                                 |
| [`docker container run`](https://docs.docker.com/reference/cli/docker/container/run/)         | Create and run a new container from an image                                  |
| [`docker container start`](https://docs.docker.com/reference/cli/docker/container/start/)     | Start one or more stopped containers                                          |
| [`docker container stats`](https://docs.docker.com/reference/cli/docker/container/stats/)     | Display a live stream of container(s) resource usage statistics               |
| [`docker container stop`](https://docs.docker.com/reference/cli/docker/container/stop/)       | Stop one or more running containers                                           |
| [`docker container top`](https://docs.docker.com/reference/cli/docker/container/top/)         | Display the running processes of a container                                  |
| [`docker container unpause`](https://docs.docker.com/reference/cli/docker/container/unpause/) | Unpause all processes within one or more containers                           |
| [`docker container update`](https://docs.docker.com/reference/cli/docker/container/update/)   | Update configuration of one or more containers                                |
| [`docker container wait`](https://docs.docker.com/reference/cli/docker/container/wait/)       | Block until one or more containers stop, then print their exit codes          |

----
url: https://docs.docker.com/reference/cli/docker/image/
----

# docker image

***

| Description | Manage images  |
| ----------- | -------------- |
| Usage       | `docker image` |

## [Description](#description)

Manage images.

## [Subcommands](#subcommands)

| Command                                                                               | Description                                                              |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`docker image build`](https://docs.docker.com/reference/cli/docker/image/build/)     | Build an image from a Dockerfile                                         |
| [`docker image history`](https://docs.docker.com/reference/cli/docker/image/history/) | Show the history of an image                                             |
| [`docker image import`](https://docs.docker.com/reference/cli/docker/image/import/)   | Import the contents from a tarball to create a filesystem image          |
| [`docker image inspect`](https://docs.docker.com/reference/cli/docker/image/inspect/) | Display detailed information on one or more images                       |
| [`docker image load`](https://docs.docker.com/reference/cli/docker/image/load/)       | Load an image from a tar archive or STDIN                                |
| [`docker image ls`](https://docs.docker.com/reference/cli/docker/image/ls/)           | List images                                                              |
| [`docker image prune`](https://docs.docker.com/reference/cli/docker/image/prune/)     | Remove unused images                                                     |
| [`docker image pull`](https://docs.docker.com/reference/cli/docker/image/pull/)       | Download an image from a registry                                        |
| [`docker image push`](https://docs.docker.com/reference/cli/docker/image/push/)       | Upload an image to a registry                                            |
| [`docker image rm`](https://docs.docker.com/reference/cli/docker/image/rm/)           | Remove one or more images                                                |
| [`docker image save`](https://docs.docker.com/reference/cli/docker/image/save/)       | Save one or more images to a tar archive (streamed to STDOUT by default) |
| [`docker image tag`](https://docs.docker.com/reference/cli/docker/image/tag/)         | Create a tag TARGET\_IMAGE that refers to SOURCE\_IMAGE                  |

----
url: https://docs.docker.com/guides/go-prometheus-monitoring/application/
----

# Building the application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

You will be creating a Golang server with some endpoints to simulate a real-world application. Then you will expose metrics from the server using Prometheus.

## [Getting the sample application](#getting-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/dockersamples/go-prometheus-monitoring.git 
```

Once you cloned you will see the following content structure inside `go-prometheus-monitoring` directory,

```text
go-prometheus-monitoring
├── CONTRIBUTING.md
├── Docker
│   ├── grafana.yml
│   └── prometheus.yml
├── dashboard.json
├── Dockerfile
├── LICENSE
├── README.md
├── compose.yaml
├── go.mod
├── go.sum
└── main.go
```

* **main.go** - The entry point of the application.
* **go.mod and go.sum** - Go module files.
* **Dockerfile** - Dockerfile used to build the app.
* **Docker/** - Contains the Docker Compose configuration files for Grafana and Prometheus.
* **compose.yaml** - Compose file to launch everything (Golang app, Prometheus, and Grafana).
* **dashboard.json** - Grafana dashboard configuration file.
* **Dockerfile** - Dockerfile used to build the Golang app.
* **compose.yaml** - Docker Compose file to launch everything (Golang app, Prometheus, and Grafana).
* Other files are for licensing and documentation purposes.

## [Understanding the application](#understanding-the-application)

The following is the complete logic of the application you will find in `main.go`.

```go
package main

import (
	"strconv"

	"github.com/gin-gonic/gin"
	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/promhttp"
)

// Define metrics
var (
	HttpRequestTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
		Name: "api_http_request_total",
		Help: "Total number of requests processed by the API",
	}, []string{"path", "status"})

	HttpRequestErrorTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
		Name: "api_http_request_error_total",
		Help: "Total number of errors returned by the API",
	}, []string{"path", "status"})
)

// Custom registry (without default Go metrics)
var customRegistry = prometheus.NewRegistry()

// Register metrics with custom registry
func init() {
	customRegistry.MustRegister(HttpRequestTotal, HttpRequestErrorTotal)
}

func main() {
	router := gin.Default()

	// Register /metrics before middleware
	router.GET("/metrics", PrometheusHandler())
	
	router.Use(RequestMetricsMiddleware())
	router.GET("/health", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "Up and running!",
		})
	})
	router.GET("/v1/users", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "Hello from /v1/users",
		})
	})

	router.Run(":8000")
}

// Custom metrics handler with custom registry
func PrometheusHandler() gin.HandlerFunc {
	h := promhttp.HandlerFor(customRegistry, promhttp.HandlerOpts{})
	return func(c *gin.Context) {
		h.ServeHTTP(c.Writer, c.Request)
	}
}

// Middleware to record incoming requests metrics
func RequestMetricsMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		path := c.Request.URL.Path
		c.Next()
		status := c.Writer.Status()
		if status < 400 {
			HttpRequestTotal.WithLabelValues(path, strconv.Itoa(status)).Inc()
		} else {
			HttpRequestErrorTotal.WithLabelValues(path, strconv.Itoa(status)).Inc()
		}
	}
}
```

In this part of the code, you have imported the required packages `gin`, `prometheus`, and `promhttp`. Then you have defined a couple of variables, `HttpRequestTotal` and `HttpRequestErrorTotal` are Prometheus counter metrics, and `customRegistry` is a custom registry that will be used to register these metrics. The name of the metric is a string that you can use to identify the metric. The help string is a string that will be shown when you query the `/metrics` endpoint to understand the metric. The reason you are using the custom registry is so avoid the default Go metrics that are registered by default by the Prometheus client. Then using the `init` function you are registering the metrics with the custom registry.

```go
import (
	"strconv"

	"github.com/gin-gonic/gin"
	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/promhttp"
)

// Define metrics
var (
	HttpRequestTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
		Name: "api_http_request_total",
		Help: "Total number of requests processed by the API",
	}, []string{"path", "status"})

	HttpRequestErrorTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
		Name: "api_http_request_error_total",
		Help: "Total number of errors returned by the API",
	}, []string{"path", "status"})
)

// Custom registry (without default Go metrics)
var customRegistry = prometheus.NewRegistry()

// Register metrics with custom registry
func init() {
	customRegistry.MustRegister(HttpRequestTotal, HttpRequestErrorTotal)
}
```

In the `main` function, you have created a new instance of the `gin` framework and created three routes. You can see the health endpoint that is on path `/health` that will return a JSON with `{"message": "Up and running!"}` and the `/v1/users` endpoint that will return a JSON with `{"message": "Hello from /v1/users"}`. The third route is for the `/metrics` endpoint that will return the metrics in the Prometheus format. Then you have `RequestMetricsMiddleware` middleware, it will be called for every request made to the API. It will record the incoming requests metrics like status codes and paths. Finally, you are running the gin application on port 8000.

```golang
func main() {
	router := gin.Default()

	// Register /metrics before middleware
	router.GET("/metrics", PrometheusHandler())
	
	router.Use(RequestMetricsMiddleware())
	router.GET("/health", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "Up and running!",
		})
	})
	router.GET("/v1/users", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "Hello from /v1/users",
		})
	})

	router.Run(":8000")
}
```

Now comes the middleware function `RequestMetricsMiddleware`. This function is called for every request made to the API. It increments the `HttpRequestTotal` counter (different counter for different paths and status codes) if the status code is less than or equal to 400. If the status code is greater than 400, it increments the `HttpRequestErrorTotal` counter (different counter for different paths and status codes). The `PrometheusHandler` function is the custom handler that will be called for the `/metrics` endpoint. It will return the metrics in the Prometheus format.

```golang
// Custom metrics handler with custom registry
func PrometheusHandler() gin.HandlerFunc {
	h := promhttp.HandlerFor(customRegistry, promhttp.HandlerOpts{})
	return func(c *gin.Context) {
		h.ServeHTTP(c.Writer, c.Request)
	}
}

// Middleware to record incoming requests metrics
func RequestMetricsMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		path := c.Request.URL.Path
		c.Next()
		status := c.Writer.Status()
		if status < 400 {
			HttpRequestTotal.WithLabelValues(path, strconv.Itoa(status)).Inc()
		} else {
			HttpRequestErrorTotal.WithLabelValues(path, strconv.Itoa(status)).Inc()
		}
	}
}
```

That's it, this was the complete gist of the application. Now it's time to run and test if the app is registering metrics correctly.

## [Running the application](#running-the-application)

Make sure you are still inside `go-prometheus-monitoring` directory in the terminal, and run the following command. Install the dependencies by running `go mod tidy` and then build and run the application by running `go run main.go`. Then visit `http://localhost:8000/health` or `http://localhost:8000/v1/users`. You should see the output `{"message": "Up and running!"}` or `{"message": "Hello from /v1/users"}`. If you are able to see this then your app is successfully up and running.

Now, check your application's metrics by accessing the `/metrics` endpoint. Open `http://localhost:8000/metrics` in your browser. You should see similar output to the following.

```sh
# HELP api_http_request_error_total Total number of errors returned by the API
# TYPE api_http_request_error_total counter
api_http_request_error_total{path="/",status="404"} 1
api_http_request_error_total{path="//v1/users",status="404"} 1
api_http_request_error_total{path="/favicon.ico",status="404"} 1
# HELP api_http_request_total Total number of requests processed by the API
# TYPE api_http_request_total counter
api_http_request_total{path="/health",status="200"} 2
api_http_request_total{path="/v1/users",status="200"} 1
```

In the terminal, press `ctrl` + `c` to stop the application.

> Note
>
> If you don't want to run the application locally, and want to run it in a Docker container, skip to next page where you create a Dockerfile and containerize the application.

## [Summary](#summary)

In this section, you learned how to create a Golang app to register metrics with Prometheus. By implementing middleware functions, you were able to increment the counters based on the request path and status codes.

## [Next steps](#next-steps)

In the next section, you'll learn how to containerize your application.

[Containerize a Golang application »](https://docs.docker.com/guides/go-prometheus-monitoring/containerize/)

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/
----

# Configure Docker socket exceptions and advanced settings

***

Table of contents

***

Subscription: Business

For: Administrators

This page shows you how to configure Docker socket exceptions and other advanced settings for Enhanced Container Isolation (ECI). These configurations enable trusted tools like Testcontainers to work with ECI while maintaining security.

## [Docker socket mount permissions](#docker-socket-mount-permissions)

By default, Enhanced Container Isolation blocks containers from mounting the Docker socket to prevent malicious access to Docker Engine. However, some tools require Docker socket access.

Common scenarios requiring Docker socket access include:

* Testing frameworks: Testcontainers, which manages test containers
* Build tools: Paketo buildpacks that create ephemeral build containers
* CI/CD tools: Tools that manage containers as part of deployment pipelines
* Development utilities: Docker CLI containers for container management

## [Configure socket exceptions](#configure-socket-exceptions)

Configure Docker socket exceptions using Settings Management:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down.
2. Go to **Admin Console** > **Desktop Settings Management**.
3. [Create or edit a setting policy](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/).
4. Find **Enhanced Container Isolation** settings.
5. Configure **Docker socket access control** with your trusted images and command restrictions.

Create an [`admin-settings.json` file](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/) and add:

```json
{
  "configurationFileVersion": 2,
  "enhancedContainerIsolation": {
    "locked": true,
    "value": true,
    "dockerSocketMount": {
      "imageList": {
        "images": [
          "docker.io/localstack/localstack:*",
          "docker.io/testcontainers/ryuk:*",
          "docker:cli"
        ],
        "allowDerivedImages": true
      },
      "commandList": {
        "type": "deny",
        "commands": ["push", "build"]
      }
    }
  }
}
```

## [Image allowlist configuration](#image-allowlist-configuration)

The `imageList` defines which container images can mount the Docker socket.

### [Image reference formats](#image-reference-formats)

| Format                  | Description                                                                                                                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<image_name>[:<tag>]`  | Name of the image, with optional tag. If the tag is omitted, the `:latest` tag is used. If the tag is the wildcard `*`, then it means "any tag for that image."                                 |
| `<image_name>@<digest>` | Name of the image, with a specific repository digest (e.g., as reported by `docker buildx imagetools inspect <image>`). This means only the image that matches that name and digest is allowed. |

### [Example configurations](#example-configurations)

Basic allowlist for testing tools:

```json
"imageList": {
  "images": [
    "docker.io/testcontainers/ryuk:*",
    "docker:cli",
    "alpine:latest"
  ]
}
```

Wildcard allowlist (Docker Desktop 4.36 and later):

```json
"imageList": {
  "images": ["*"]
}
```

> Warning
>
> Using `"*"` allows all containers to mount the Docker socket, which reduces security. Only use this when explicitly listing allowed images isn't feasible.

### [Security validation](#security-validation)

Docker Desktop validates allowed images by:

1. Downloading image digests from registries for allowed images
2. Comparing container image digests against the allowlist when containers start
3. Blocking containers whose digests don't match allowed images

This prevents bypassing restrictions by re-tagging unauthorized images:

```console
$ docker tag malicious-image docker:cli
$ docker run -v /var/run/docker.sock:/var/run/docker.sock docker:cli
# This fails because the digest doesn't match the real docker:cli image
```

## [Derived images support](#derived-images-support)

For tools like Paketo buildpacks that create ephemeral local images, you can allow images derived from trusted base images.

### [Enable derived images](#enable-derived-images)

```json
"imageList": {
  "images": [
    "paketobuildpacks/builder:base"
  ],
  "allowDerivedImages": true
}
```

When `allowDerivedImages` is true, local images built from allowed base images (using `FROM` in Dockerfile) also gain Docker socket access.

### [Derived images requirements](#derived-images-requirements)

* Local images only: Derived images must not exist in remote registries
* Base image available: The parent image must be pulled locally first
* Performance impact: Adds up to 1 second to container startup for validation
* Version compatibility: Full wildcard support requires Docker Desktop 4.36+

## [Command restrictions](#command-restrictions)

### [Deny list (recommended)](#deny-list-recommended)

Blocks specified commands while allowing all others:

```json
"commandList": {
  "type": "deny",
  "commands": ["push", "build", "image*"]
}
```

### [Allow list](#allow-list)

Only allows specified commands while blocking all others:

```json
"commandList": {
  "type": "allow",
  "commands": ["ps", "container*", "volume*"]
}
```

### [Command wildcards](#command-wildcards)

| Wildcard        | Blocks/allows                       |
| --------------- | ----------------------------------- |
| `"container\*"` | All "docker container ..." commands |
| `"image\*"`     | All "docker image ..." commands     |
| `"volume\*"`    | All "docker volume ..." commands    |
| `"network\*"`   | All "docker network ..." commands   |
| `"build\*"`     | All "docker build ..." commands     |
| `"system\*"`    | All "docker system ..." commands    |

### [Command blocking example](#command-blocking-example)

When a blocked command is executed:

```console
/ # docker push myimage
Error response from daemon: enhanced container isolation: docker command "/v1.43/images/myimage/push?tag=latest" is blocked; if you wish to allow it, configure the docker socket command list in the Docker Desktop settings.
```

## [Common configuration examples](#common-configuration-examples)

### [Testcontainers setup](#testcontainers-setup)

For Java/Python testing with Testcontainers:

```json
"dockerSocketMount": {
  "imageList": {
    "images": [
      "docker.io/testcontainers/ryuk:*",
      "testcontainers/*:*"
    ]
  },
  "commandList": {
    "type": "deny",
    "commands": ["push", "build"]
  }
}
```

### [CI/CD pipeline tools](#cicd-pipeline-tools)

For controlled CI/CD container management:

```json
"dockerSocketMount": {
  "imageList": {
    "images": [
      "docker:cli",
      "your-registry.com/ci-tools/*:*"
    ]
  },
  "commandList": {
    "type": "allow",
    "commands": ["ps", "container*", "image*"]
  }
}
```

### [Development environments](#development-environments)

For local development with Docker-in-Docker:

```json
"dockerSocketMount": {
  "imageList": {
    "images": [
      "docker:dind",
      "docker:cli"
    ]
  },
  "commandList": {
    "type": "deny",
    "commands": ["system*"]
  }
}
```

## [Security recommendations](#security-recommendations)

### [Image allowlist best practices](#image-allowlist-best-practices)

* Be restrictive: Only allow images you absolutely trust and need
* Use wildcards carefully: Tag wildcards (`*`) are convenient but less secure than specific tags
* Regular reviews: Periodically review and update your allowlist
* Digest pinning: Use digest references for maximum security in critical environments

### [Command restrictions](#command-restrictions-1)

* Default to deny: Start with a deny list blocking dangerous commands like `push` and `build`
* Principle of least privilege: Only allow commands your tools actually need
* Monitor usage: Track which commands are being blocked to refine your configuration

### [Monitoring and maintenance](#monitoring-and-maintenance)

* Regular validation: Test your configuration after Docker Desktop updates, as image digests may change.
* Handle digest mismatches: If allowed images are unexpectedly blocked:
  ```console
  $ docker image rm <image>
  $ docker pull <image>
  ```

This resolves digest mismatches when upstream images are updated.

## [Next steps](#next-steps)

* Review [Enhanced Container Isolation limitations](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations/).
* Review [Enhanced Container Isolation FAQs](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/faq/).

----
url: https://docs.docker.com/guides/testcontainers-python-getting-started/write-tests/
----

# Write tests with Testcontainers

***

Table of contents

***

You'll create a PostgreSQL container using Testcontainers and use it for all the tests. Before each test, you'll delete all customer records so that tests run with a clean database.

## [Set up pytest fixtures](#set-up-pytest-fixtures)

This guide uses [pytest fixtures](https://pytest.org/en/stable/how-to/fixtures.html) for setup and teardown logic. A recommended approach is to use [finalizers](https://pytest.org/en/stable/how-to/fixtures.html#adding-finalizers-directly) to guarantee cleanup runs even if setup fails:

```python
@pytest.fixture
def setup(request):
    # setup code

    def cleanup():
        # teardown code

    request.addfinalizer(cleanup)
    return some_value
```

## [Create the test file](#create-the-test-file)

Create a `tests/__init__.py` file with empty content to enable pytest [auto-discovery](https://pytest.org/explanation/goodpractices.html#test-discovery).

Then create `tests/test_customers.py` with the fixtures:

```python
import os
import pytest
from testcontainers.postgres import PostgresContainer

from customers import customers

postgres = PostgresContainer("postgres:16-alpine")


@pytest.fixture(scope="module", autouse=True)
def setup(request):
    postgres.start()

    def remove_container():
        postgres.stop()

    request.addfinalizer(remove_container)
    os.environ["DB_CONN"] = postgres.get_connection_url()
    os.environ["DB_HOST"] = postgres.get_container_host_ip()
    os.environ["DB_PORT"] = str(postgres.get_exposed_port(5432))
    os.environ["DB_USERNAME"] = postgres.username
    os.environ["DB_PASSWORD"] = postgres.password
    os.environ["DB_NAME"] = postgres.dbname
    customers.create_table()


@pytest.fixture(scope="function", autouse=True)
def setup_data():
    customers.delete_all_customers()
```

Here's what the fixtures do:

* The `setup` fixture has `scope="module"`, so it runs once for all tests in the file. It starts a PostgreSQL container, sets environment variables with the connection details, and creates the `customers` table. A cleanup function removes the container after all tests complete.
* The `setup_data` fixture has `scope="function"`, so it runs before every test. It deletes all records to give each test a clean database.

## [Write the tests](#write-the-tests)

Add the test functions to the same file:

```python
def test_get_all_customers():
    customers.create_customer("Siva", "siva@gmail.com")
    customers.create_customer("James", "james@gmail.com")
    customers_list = customers.get_all_customers()
    assert len(customers_list) == 2


def test_get_customer_by_email():
    customers.create_customer("John", "john@gmail.com")
    customer = customers.get_customer_by_email("john@gmail.com")
    assert customer.name == "John"
    assert customer.email == "john@gmail.com"
```

* `test_get_all_customers()` inserts two customer records, fetches all customers, and asserts the count.
* `test_get_customer_by_email()` inserts a customer, fetches it by email, and asserts the details.

Because `setup_data` deletes all records before each test, the tests can run in any order.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-python-getting-started/run-tests/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/debug/build/
----

# docker buildx debug build

***

| Description                                                               | Start a build                                                                |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Usage                                                                     | `docker buildx debug build [OPTIONS] PATH \| URL \| -`                       |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker build` `docker builder build` `docker image build` `docker buildx b` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Start a build

## [Options](#options)

| Option              | Default | Description                                                                                                                                       |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--add-host`        |         | Add a custom host-to-IP mapping (format: `host:ip`)                                                                                               |
| `--allow`           |         | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`, `device`)                                                          |
| `--annotation`      |         | Add annotation to the image                                                                                                                       |
| `--attest`          |         | Attestation parameters (format: `type=sbom,generator=image`)                                                                                      |
| `--build-arg`       |         | Set build-time variables                                                                                                                          |
| `--build-context`   |         | Additional build contexts (e.g., name=path)                                                                                                       |
| `--cache-from`      |         | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`)                                                                     |
| `--cache-to`        |         | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`)                                                                 |
| `--call`            | `build` | Set method for evaluating build (`check`, `outline`, `targets`)                                                                                   |
| `--cgroup-parent`   |         | Set the parent cgroup for the `RUN` instructions during build                                                                                     |
| `--check`           |         | Shorthand for `--call=check`                                                                                                                      |
| `-f, --file`        |         | Name of the Dockerfile (default: `PATH/Dockerfile`)                                                                                               |
| `--iidfile`         |         | Write the image ID to a file                                                                                                                      |
| `--label`           |         | Set metadata for an image                                                                                                                         |
| `--load`            |         | Shorthand for `--output=type=docker`                                                                                                              |
| `--metadata-file`   |         | Write build result metadata to a file                                                                                                             |
| `--network`         |         | Set the networking mode for the `RUN` instructions during build                                                                                   |
| `--no-cache`        |         | Do not use cache when building the image                                                                                                          |
| `--no-cache-filter` |         | Do not cache specified stages                                                                                                                     |
| `-o, --output`      |         | Output destination (format: `type=local,dest=path`)                                                                                               |
| `--platform`        |         | Set target platform for build                                                                                                                     |
| `--policy`          |         | Policy configuration (format: `filename=path[,filename=path][,reset=true\|false][,disabled=true\|false][,strict=true\|false][,log-level=level]`)  |
| `--progress`        | `auto`  | Set type of progress output (`auto`, `none`, `plain`, `quiet`, `rawjson`, `tty`). Use plain to show container output                              |
| `--provenance`      |         | Shorthand for `--attest=type=provenance`                                                                                                          |
| `--pull`            |         | Always attempt to pull all referenced images                                                                                                      |
| `--push`            |         | Shorthand for `--output=type=registry,unpack=false`                                                                                               |
| `-q, --quiet`       |         | Suppress the build output and print image ID on success                                                                                           |
| `--sbom`            |         | Shorthand for `--attest=type=sbom`                                                                                                                |
| `--secret`          |         | Secret to expose to the build (format: `id=mysecret[,src=/local/secret]`)                                                                         |
| `--shm-size`        |         | Shared memory size for build containers                                                                                                           |
| `--ssh`             |         | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`)                                               |
| `-t, --tag`         |         | Image identifier (format: `[registry/]repository[:tag]`)                                                                                          |
| `--target`          |         | Set the target build stage to build                                                                                                               |
| `--ulimit`          |         | Ulimit options                                                                                                                                    |

----
url: https://docs.docker.com/build/ci/github-actions/test-before-push/
----

# Test before push with GitHub Actions

***

***

In some cases, you might want to validate that the image works as expected before pushing it. The following workflow implements several steps to achieve this:

1. Build and export the image to Docker
2. Test your image
3. Multi-platform build and push the image

```yaml
name: ci

on:
  push:

env:
  TEST_TAG: user/app:test
  LATEST_TAG: user/app:latest

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and export to Docker
        uses: docker/build-push-action@v7
        with:
          load: true
          tags: ${{ env.TEST_TAG }}

      - name: Test
        run: |
          docker run --rm ${{ env.TEST_TAG }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ env.LATEST_TAG }}
```

> Note
>
> The `linux/amd64` image is only built once in this workflow. The image is built once, and the following steps use the internal cache from the first `Build and push` step. The second `Build and push` step only builds `linux/arm64`.

----
url: https://docs.docker.com/reference/cli/docker/sandbox/create/claude/
----

# docker sandbox create claude

***

| Description | Create a sandbox for claude                                   |
| ----------- | ------------------------------------------------------------- |
| Usage       | `docker sandbox create claude WORKSPACE [EXTRA_WORKSPACE...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Create a sandbox with access to a host workspace for claude.

The workspace path is required and will be exposed inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use 'docker sandbox run SANDBOX' to start claude after creation.

## [Examples](#examples)

### [Create a Claude sandbox in the current directory](#create-a-claude-sandbox-in-the-current-directory)

```console
$ docker sandbox create claude .
```

### [Create with an absolute path](#create-with-an-absolute-path)

```console
$ docker sandbox create claude /home/user/my-project
```

### [Create and then run](#create-and-then-run)

```console
$ docker sandbox create --name my-claude claude ~/my-project
$ docker sandbox run my-claude
```

----
url: https://docs.docker.com/docker-hub/quickstart/
----

# Docker Hub quickstart

***

Table of contents

***

Docker Hub provides a vast library of pre-built images and resources, accelerating development workflows and reducing setup time. You can build upon pre-built images from Docker Hub and then use repositories to share and distribute your own images with your team or millions of other developers.

This guide shows you how to find and run a pre-built image. It then walks you through creating a custom image and sharing it through Docker Hub.

## [Prerequisites](#prerequisites)

* [Download and install Docker](https://docs.docker.com/get-started/get-docker/)
* A verified [Docker](https://app.docker.com/signup) account

## [Step 1: Find an image in Docker Hub's library](#step-1-find-an-image-in-docker-hubs-library)

You can search for content in Docker Hub itself, in the Docker Desktop Dashboard, or by using the CLI.

To search or browse for content on Docker Hub:

1. Navigate to the [Docker Hub Explore page](https://hub.docker.com/explore).

   On the **Explore** page, you can browse by catalog or category, or use the search to quickly find content.

2. Under **Categories**, select **Web servers**.

   After the results are displayed, you can further filter the results using the filters on the left side of the page.

3. In the filters, select **Docker Official Image**.

   Filtering by Trusted Content ensures that you see only high-quality, secure images curated by Docker and verified publishing partners.

4. In the results, select the **nginx** image.

   Selecting the image opens the image's page where you can learn more about how to use the image. On the page, you'll also find the `docker pull` command to pull the image.

1) Open the Docker Desktop Dashboard.

2) Select the **Docker Hub** view.

   In the **Docker Hub** view, you can browse by catalog or category, or use the search to quickly find content.

3) Leave the search box empty and then select **Search**.

   The search results are shown with additional filters now next to the search box.

4) Select the search filter icon, and then select **Docker Official Image** and **Web Servers**.

5) In the results, select the **nginx** image.

1. Open a terminal window.

   > Tip
   >
   > The Docker Desktop Dashboard contains a built-in terminal. At the bottom of the Dashboard, select **>\_ Terminal** to open it.

2. In the terminal, run the following command.

   ```console
   $ docker search --filter is-official=true nginx
   ```

   Unlike the Docker Hub and Docker Desktop interfaces, you can't browse by category using the `docker search` command. For more details about the command, see [docker search](/reference/cli/docker/search/).

Now that you've found an image, it's time to pull and run it on your device.

## [Step 2: Pull and run an image from Docker Hub](#step-2-pull-and-run-an-image-from-docker-hub)

You can run images from Docker Hub using the CLI or Docker Desktop Dashboard.

1. In the Docker Desktop Dashboard, select the **nginx** image in the **Docker Hub** view. For more details, see [Step 1: Find an image in Docker Hub's library](#step-1-find-an-image-in-docker-hubs-library).

2. On the **nginx** screen, select **Run**.

   If the image doesn't exist on your device, it is automatically pulled from Docker Hub. Pulling the image may take a few seconds or minutes depending on your connection. After the image has been pulled, a window appears in Docker Desktop and you can specify run options.

3. In the **Host port** option, specify `8080`.

4. Select **Run**.

   The container logs appear after the container starts.

5. Select the **8080:80** link to open the server, or visit <http://localhost:8080> in your web browser.

6. In the Docker Desktop Dashboard, select the **Stop** button to stop the container.

1) Open a terminal window.

   > Tip
   >
   > The Docker Desktop Dashboard contains a built-in terminal. At the bottom of the Dashboard, select **>\_ Terminal** to open it.

2) In your terminal, run the following command to pull and run the Nginx image.

   ```console
   $ docker run -p 8080:80 --rm nginx
   ```

   The `docker run` command automatically pulls and runs the image without the need to run `docker pull` first. To learn more about the command and its options, see the [`docker run` CLI reference](/reference/cli/docker/container/run/). After running the command, you should see output similar to the following.

   ```console
   Unable to find image 'nginx:latest' locally
   latest: Pulling from library/nginx
   a480a496ba95: Pull complete
   f3ace1b8ce45: Pull complete
   11d6fdd0e8a7: Pull complete
   f1091da6fd5c: Pull complete
   40eea07b53d8: Pull complete
   6476794e50f4: Pull complete
   70850b3ec6b2: Pull complete
   Digest: sha256:28402db69fec7c17e179ea87882667f1e054391138f77ffaf0c3eb388efc3ffb
   Status: Downloaded newer image for nginx:latest
   /docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
   /docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
   /docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
   10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
   10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
   /docker-entrypoint.sh: Sourcing /docker-entrypoint.d/15-local-resolvers.envsh
   /docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
   /docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
   /docker-entrypoint.sh: Configuration complete; ready for start up
   2024/11/07 21:43:41 [notice] 1#1: using the "epoll" event method
   2024/11/07 21:43:41 [notice] 1#1: nginx/1.27.2
   2024/11/07 21:43:41 [notice] 1#1: built by gcc 12.2.0 (Debian 12.2.0-14)
   2024/11/07 21:43:41 [notice] 1#1: OS: Linux 6.10.11-linuxkit
   2024/11/07 21:43:41 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
   2024/11/07 21:43:41 [notice] 1#1: start worker processes
   2024/11/07 21:43:41 [notice] 1#1: start worker process 29
   ...
   ```

3) Visit <http://localhost:8080> to view the default Nginx page and verify that the container is running.

4) In the terminal, press Ctrl+C to stop the container.

You've now run a web server without any set up or configuration. Docker Hub provides instant access to pre-built, ready-to-use container images, letting you quickly pull and run applications without needing to install or configure software manually. With Docker Hub's vast library of images, you can experiment with and deploy applications effortlessly, boosting productivity and making it easy to try out new tools, set up development environments, or build on top of existing software.

You can also extend images from Docker Hub, letting you quickly build and customize your own images to suit specific needs.

## [Step 3: Build and push an image to Docker Hub](#step-3-build-and-push-an-image-to-docker-hub)

1. Create a [Dockerfile](https://docs.docker.com/reference/dockerfile/) to specify your application:

   ```dockerfile
   FROM nginx
   RUN echo "<h1>Hello world from Docker!</h1>" > /usr/share/nginx/html/index.html
   ```

   This Dockerfile extends the Nginx image from Docker Hub to create a simple website. With just a few lines, you can easily set up, customize, and share a static website using Docker.

2. Run the following command to build your image. Replace `<YOUR-USERNAME>` with your Docker ID.

   ```console
   $ docker build -t <YOUR-USERNAME>/nginx-custom .
   ```

   This command builds your image and tags it so that Docker understands which repository to push it to in Docker Hub. To learn more about the command and its options, see the [`docker build` CLI reference](/reference/cli/docker/buildx/build/). After running the command, you should see output similar to the following.

   ```console
   [+] Building 0.6s (6/6) FINISHED                      docker:desktop-linux
    => [internal] load build definition from Dockerfile                  0.0s
    => => transferring dockerfile: 128B                                  0.0s
    => [internal] load metadata for docker.io/library/nginx:latest       0.0s
    => [internal] load .dockerignore                                     0.0s
    => => transferring context: 2B                                       0.0s
    => [1/2] FROM docker.io/library/nginx:latest                         0.1s
    => [2/2] RUN echo "<h1>Hello world from Docker!</h1>" > /usr/share/  0.2s
    => exporting to image                                                0.1s
    => => exporting layers                                               0.0s
    => => writing image sha256:f85ab68f4987847713e87a95c39009a5c9f4ad78  0.0s
    => => naming to docker.io/mobyismyname/nginx-custom                  0.0s
   ```

3. Run the following command to test your image. Replace `<YOUR-USERNAME>` with your Docker ID.

   ```console
   $ docker run -p 8080:80 --rm <YOUR-USERNAME>/nginx-custom
   ```

4. Visit <http://localhost:8080> to view the page. You should see `Hello world from Docker!`.

5. In the terminal, press CTRL+C to stop the container.

6. Sign in to Docker Desktop. You must be signed in before pushing an image to Docker Hub.

7. Run the following command to push your image to Docker Hub. Replace `<YOUR-USERNAME>` with your Docker ID.

   ```console
   $ docker push <YOUR-USERNAME>/nginx-custom
   ```

   > Note
   >
   > You must be signed in to Docker Hub through Docker Desktop or the command line, and you must also name your images correctly, as per the above steps.

   The command pushes the image to Docker Hub and automatically creates the repository if it doesn't exist. To learn more about the command, see the [`docker push` CLI reference](/reference/cli/docker/image/push/). After running the command, you should see output similar to the following.

   ```console
   Using default tag: latest
   The push refers to repository [docker.io/mobyismyname/nginx-custom]
   d0e011850342: Pushed
   e4e9e9ad93c2: Mounted from library/nginx
   6ac729401225: Mounted from library/nginx
   8ce189049cb5: Mounted from library/nginx
   296af1bd2844: Mounted from library/nginx
   63d7ce983cd5: Mounted from library/nginx
   b33db0c3c3a8: Mounted from library/nginx
   98b5f35ea9d3: Mounted from library/nginx
   latest: digest: sha256:7f5223ae866e725a7f86b856c30edd3b86f60d76694df81d90b08918d8de1e3f size: 1985
   ```

Now that you've created a repository and pushed your image, it's time to view your repository and explore its options.

## [Step 4: View your repository on Docker Hub and explore options](#step-4-view-your-repository-on-docker-hub-and-explore-options)

You can view your Docker Hub repositories in the Docker Hub or Docker Desktop interface.

1. Go to [Docker Hub](https://hub.docker.com) and sign in.

   After signing in, you should be on the **Repositories** page. If not, then go to the [**Repositories**](https://hub.docker.com/repositories/) page.

2. Find the **nginx-custom** repository and select that row.

   After selecting the repository, you should see more details and options for your repository.

1) Sign in to Docker Desktop.

2) Select the **Images** view.

3) Select the **Hub repositories** tab.

   A list of your Docker Hub repositories appears.

4) Find the **nginx-custom** repository, hover over the row, and then select **View in Hub**.

   Docker Hub opens and you are able to view more details about the image.

You've now verified that your repository exists on Docker Hub, and you've discovered more options for it. View the next steps to learn more about some of these options.

## [Next steps](#next-steps)

Add [repository information](https://docs.docker.com/docker-hub/repos/manage/information/) to help users find and use your image.

----
url: https://docs.docker.com/get-started/docker-concepts/building-images/
----

# Building images

Table of contents

***

Building container images is both technical and an art. You want to keep the image small and focused to increase your security posture, but also need to balance potential tradeoffs, such as caching impacts. In this series, you’ll deep dive into the secrets of images, how they are built and best practices.

**Skill level** Beginner

**Time to complete** 25 minutes

**Prerequisites** None

## [About this series](#about-this-series)

Learn how to build production-ready images that are lean and efficient Docker images, essential for minimizing overhead and enhancing deployment in production environments.

## [What you'll learn](#what-youll-learn)

* Understanding image layers
* Writing a Dockerfile
* Build, tag and publish an image
* Using the build cache
* Multi-stage builds

## [Modules](#modules)

1. [Understanding the image layers](https://docs.docker.com/get-started/docker-concepts/building-images/understanding-image-layers/)

   This concept page will teach you about the layers of container image.

2. [Writing a Dockerfile](https://docs.docker.com/get-started/docker-concepts/building-images/writing-a-dockerfile/)

   This concept page will teach you how to create image using Dockerfile.

3. [Build, tag, and publish an image](https://docs.docker.com/get-started/docker-concepts/building-images/build-tag-and-publish-an-image/)

   This concept page will teach you how to build, tag, and publish an image to Docker Hub or any other registry

4. [Using the build cache](https://docs.docker.com/get-started/docker-concepts/building-images/using-the-build-cache/)

   This concept page will teach you about the build cache, what changes invalidate the cache and how to effectively use the build cache.

5. [Multi-stage builds](https://docs.docker.com/get-started/docker-concepts/building-images/multi-stage-builds/)

   This concept page will teach you about the purpose of the multi-stage build and its benefits

----
url: https://docs.docker.com/reference/cli/sbx/kit/pull/
----

# sbx kit pull

| Description | Pull a kit artifact from an OCI registry |
| ----------- | ---------------------------------------- |
| Usage       | `sbx kit pull REFERENCE [flags]`         |

## [Description](#description)

Pull a kit artifact from an OCI registry and save it as a ZIP file.

The reference should be in the format "registry/repo:tag" or "registry/repo\@sha256:digest" (e.g., "ghcr.io/myorg/my-plugin:1.0").

Authentication: sbx registry secrets (sbx secret set --registry) take priority, falling back to the Docker credential store.

## [Options](#options)

| Option         | Default | Description                                            |
| -------------- | ------- | ------------------------------------------------------ |
| `-o, --output` |         | Output ZIP file path (default: derived from reference) |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/reference/cli/docker/scout/enroll/
----

# docker scout enroll

***

| Description | Enroll an organization with Docker Scout |
| ----------- | ---------------------------------------- |
| Usage       | `docker scout enroll ORG`                |

## [Description](#description)

The `docker scout enroll` command enrolls an organization with Docker Scout.

----
url: https://docs.docker.com/guides/angular/containerize/
----

# Containerize an Angular Application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Before you begin, make sure the following tools are installed and available on your system:

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client.

> **New to Docker?**\
> Start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide to get familiar with key concepts like images, containers, and Dockerfiles.

***

## [Overview](#overview)

This guide walks you through the complete process of containerizing an Angular application with Docker. You’ll learn how to create a production-ready Docker image using best practices that improve performance, security, scalability, and deployment efficiency.

By the end of this guide, you will:

* Containerize an Angular application using Docker.
* Create and optimize a Dockerfile for production builds.
* Use multi-stage builds to minimize image size.
* Serve the application efficiently with a custom Nginx configuration.
* Build secure and maintainable Docker images by following best practices.

***

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, navigate to the directory where you want to work, and run the following command to clone the git repository:

```console
$ git clone https://github.com/kristiyan-velkov/docker-angular-sample
```

***

## [Build the Docker image](#build-the-docker-image)

Angular is a front-end framework that compiles into static assets, so the Dockerfile uses a multi-stage build: one stage compiles the app with Node.js, and a second minimal stage serves the static output with Nginx.

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

### [Step 1: Create the Dockerfile](#step-1-create-the-dockerfile)

Before creating a Dockerfile, you need to choose a base image. You can either use the [Node.js Official Image](https://hub.docker.com/_/node) or a Docker Hardened Image (DHI) from the [Hardened Image catalog](https://hub.docker.com/hardened-images/catalog).

Choosing DHI offers the advantage of a production-ready image that is lightweight and secure. For more information, see [Docker Hardened Images](https://docs.docker.com/dhi/).

> Important
>
> This guide uses a stable Node.js LTS image tag that is considered secure when the guide is written. Because new releases and security patches are published regularly, the tag shown here may no longer be the safest option when you follow the guide. Always review the latest available image tags and select a secure, up-to-date version before building or deploying your application.
>
> Official Node.js Docker Images: <https://hub.docker.com/_/node>

Docker Hardened Images (DHIs) are available for Node.js in the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog/dhi/node). Docker Hardened Images are freely available to everyone with no subscription required. You can pull and use them like any other Docker image after signing in to the DHI registry. For more information, see the [DHI quickstart](/dhi/get-started/) guide.

1. Sign in to the DHI registry:

   ```console
   $ docker login dhi.io
   ```

2. Pull the Node.js DHI (check the catalog for available versions):

   ```console
   $ docker pull dhi.io/node:24-alpine3.22-dev
   ```

In the following Dockerfile, the `FROM` instruction uses `dhi.io/node:24-alpine3.22-dev` as the base image.

```dockerfile
# =========================================
# Stage 1: Build the Angular Application
# =========================================

# Use a lightweight DHI Node.js image for building
FROM dhi.io/node:24-alpine3.22-dev AS builder

# Set the working directory inside the container
WORKDIR /app

# Copy package-related files first to leverage Docker's caching mechanism
COPY package.json package-lock.json* ./

# Install project dependencies using npm ci (ensures a clean, reproducible install)
RUN --mount=type=cache,target=/root/.npm npm ci

# Copy the rest of the application source code into the container
COPY . .

# Build the Angular application
RUN npm run build 

# =========================================
# Stage 2: Prepare Nginx to Serve Static Files
# =========================================

FROM dhi.io/nginx:1.28.0-alpine3.21-dev AS runner

# Copy custom Nginx config
COPY nginx.conf /etc/nginx/nginx.conf

# Copy the static build output from the build stage to Nginx's default HTML serving directory
COPY --chown=nginx:nginx --from=builder /app/dist/*/browser /usr/share/nginx/html

# Use a non-root user for security best practices
USER nginx

# Expose port 8080 to allow HTTP traffic
# Note: The default Nginx container now listens on port 8080 instead of 80 
EXPOSE 8080

# Start Nginx directly with custom config
ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"]
CMD ["-g", "daemon off;"]
```

Create a file named `Dockerfile` with the following contents:

```dockerfile
# =========================================
# Stage 1: Build the Angular Application
# =========================================
ARG NODE_VERSION=24.12.0-alpine
ARG NGINX_VERSION=alpine3.22

# Use a lightweight Node.js image for building (customizable via ARG)
FROM node:${NODE_VERSION} AS builder

# Set the working directory inside the container
WORKDIR /app

# Copy package-related files first to leverage Docker's caching mechanism
COPY package.json *package-lock.json* ./

# Install project dependencies using npm ci (ensures a clean, reproducible install)
RUN --mount=type=cache,target=/root/.npm npm ci

# Copy the rest of the application source code into the container
COPY . .

# Build the Angular application
RUN npm run build 

# =========================================
# Stage 2: Prepare Nginx to Serve Static Files
# =========================================

FROM nginxinc/nginx-unprivileged:${NGINX_VERSION} AS runner

# Copy custom Nginx config
COPY nginx.conf /etc/nginx/nginx.conf

# Copy the static build output from the build stage to Nginx's default HTML serving directory
COPY --chown=nginx:nginx --from=builder /app/dist/*/browser /usr/share/nginx/html

# Use a built-in non-root user for security best practices
USER nginx

# Expose port 8080 to allow HTTP traffic
# Note: The default Nginx container now listens on port 8080 instead of 80 
EXPOSE 8080

# Start Nginx directly with custom config
ENTRYPOINT ["nginx", "-c", "/etc/nginx/nginx.conf"]
CMD ["-g", "daemon off;"]
```

> Note
>
> We are using nginx-unprivileged instead of the standard Nginx image to follow security best practices. Running as a non-root user in the final image:
>
> * Reduces the attack surface
> * Aligns with Docker’s recommendations for container hardening
> * Helps comply with stricter security policies in production environments

### [Step 2: Create the compose.yaml file](#step-2-create-the-composeyaml-file)

Create a file named `compose.yaml` with the following contents:

compose.yaml

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 8080:8080
```

### [Step 3: Create the .dockerignore file](#step-3-create-the-dockerignore-file)

The `.dockerignore` file tells Docker which files and folders to exclude when building the image.

> Note
>
> This helps:
>
> * Reduce image size
> * Speed up the build process
> * Prevent sensitive or unnecessary files (like `.env`, `.git`, or `node_modules`) from being added to the final image.
>
> To learn more, visit the [.dockerignore reference](https://docs.docker.com/reference/dockerfile/#dockerignore-file).

Create a file named `.dockerignore` with the following contents:

```dockerignore
# ================================
# Node and build output
# ================================
node_modules
dist
out-tsc
.angular
.cache
.tmp

# ================================
# Testing & Coverage
# ================================
coverage
jest
cypress
cypress/screenshots
cypress/videos
reports
playwright-report
.vite
.vitepress

# ================================
# Environment & log files
# ================================
*.env*
!*.env.production
*.log
*.tsbuildinfo

# ================================
# IDE & OS-specific files
# ================================
.vscode
.idea
.DS_Store
Thumbs.db
*.swp

# ================================
# Version control & CI files
# ================================
.git
.gitignore

# ================================
# Docker & local orchestration
# ================================
Dockerfile
Dockerfile.*
.dockerignore
docker-compose.yml
docker-compose*.yml

# ================================
# Miscellaneous
# ================================
*.bak
*.old
*.tmp
```

### [Step 4: Create the `nginx.conf` file](#step-4-create-the-nginxconf-file)

To serve your Angular application efficiently inside the container, you’ll configure Nginx with a custom setup. This configuration is optimized for performance, browser caching, gzip compression, and support for client-side routing.

Create a file named `nginx.conf` in the root of your project directory, and add the following content:

> Note
>
> To learn more about configuring Nginx, see the [official Nginx documentation](https://nginx.org/en/docs/).

```nginx
worker_processes auto;

pid /tmp/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    client_body_temp_path /tmp/client_temp;
    proxy_temp_path       /tmp/proxy_temp_path;
    fastcgi_temp_path     /tmp/fastcgi_temp;
    uwsgi_temp_path       /tmp/uwsgi_temp;
    scgi_temp_path        /tmp/scgi_temp;

    # Logging
    access_log off;
    error_log  /dev/stderr warn;

    # Performance
    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  65;
    keepalive_requests 1000;

    # Compression
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_min_length 256;
    gzip_comp_level 6;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/javascript
        application/x-javascript
        application/json
        application/xml
        application/xml+rss
        font/ttf
        font/otf
        image/svg+xml;

    server {
        listen       8080;
        server_name  localhost;

        root /usr/share/nginx/html;
        index index.html;

        # Angular Routing
        location / {
            try_files $uri $uri/ /index.html;
        }

        # Static Assets Caching
        location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|svg|map)$ {
            expires 1y;
            access_log off;
            add_header Cache-Control "public, immutable";
        }

        # Optional: Explicit asset route
        location /assets/ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }
}
```

### [Step 5: Build the Angular application image](#step-5-build-the-angular-application-image)

With your custom configuration in place, you're now ready to build the Docker image for your Angular application.

The updated setup includes:

* The updated setup includes a clean, production-ready Nginx configuration tailored specifically for Angular.
* Efficient multi-stage Docker build, ensuring a small and secure final image.

After completing the previous steps, your project directory should now contain the following files:

```text
├── docker-angular-sample/
│ ├── Dockerfile
│ ├── .dockerignore
│ ├── compose.yaml
│ └── nginx.conf
```

Now that your Dockerfile is configured, you can build the Docker image for your Angular application.

> Note
>
> The `docker build` command packages your application into an image using the instructions in the Dockerfile. It includes all necessary files from the current directory (called the [build context](/build/concepts/context/#what-is-a-build-context)).

Run the following command from the root of your project:

```console
$ docker build --tag docker-angular-sample .
```

What this command does:

* Uses the Dockerfile in the current directory (.)
* Packages the application and its dependencies into a Docker image
* Tags the image as docker-angular-sample so you can reference it later

### [Step 6: View local images](#step-6-view-local-images)

After building your Docker image, you can check which images are available on your local machine using either the Docker CLI or [Docker Desktop](https://docs.docker.com/desktop/use-desktop/images/). Since you're already working in the terminal, let's use the Docker CLI.

To list all locally available Docker images, run the following command:

```console
$ docker images
```

Example Output:

```shell
REPOSITORY                TAG               IMAGE ID       CREATED         SIZE
docker-angular-sample     latest            34e66bdb9d40   14 seconds ago   76.4MB
```

This output provides key details about your images:

* **Repository** – The name assigned to the image.
* **Tag** – A version label that helps identify different builds (e.g., latest).
* **Image ID** – A unique identifier for the image.
* **Created** – The timestamp indicating when the image was built.
* **Size** – The total disk space used by the image.

If the build was successful, you should see `docker-angular-sample` image listed.

***

## [Run the containerized application](#run-the-containerized-application)

In the previous step, you created a Dockerfile for your Angular application and built a Docker image using the docker build command. Now it’s time to run that image in a container and verify that your application works as expected.

Inside the `docker-angular-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:8080>. You should see a simple Angular web application.

Press `ctrl+c` in the terminal to stop your application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `docker-angular-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:8080>. You should see your Angular application running in the browser.

To confirm that the container is running, use `docker ps` command:

```console
$ docker ps
```

This will list all active containers along with their ports, names, and status. Look for a container exposing port 8080.

Example Output:

```shell
CONTAINER ID   IMAGE                          COMMAND                  CREATED             STATUS             PORTS                    NAMES
eb13026806d1   docker-angular-sample-server   "nginx -c /etc/nginx…"   About a minute ago  Up About a minute  0.0.0.0:8080->8080/tcp   docker-angular-sample-server-1
```

To stop the application, run:

```console
$ docker compose down
```

> Note
>
> For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

***

## [Summary](#summary)

In this guide, you learned how to containerize, build, and run an Angular application using Docker. By following best practices, you created a secure, optimized, and production-ready setup.

What you accomplished:

* Created a multi-stage `Dockerfile` that compiles the Angular application and serves the static files using Nginx.
* Created a `.dockerignore` file to exclude unnecessary files and keep the image clean and efficient.
* Built your Docker image using `docker build`.
* Ran the container using `docker compose up`, both in the foreground and in detached mode.
* Verified that the app was running by visiting <http://localhost:8080>.
* Learned how to stop the containerized application using `docker compose down`.

You now have a fully containerized Angular application, running in a Docker container, and ready for deployment across any environment with confidence and consistency.

***

***

## [Next steps](#next-steps)

With your Angular application now containerized, you're ready to move on to the next step.

In the next section, you'll learn how to develop your application using Docker containers, enabling a consistent, isolated, and reproducible development environment across any machine.

[Use containers for Angular development »](https://docs.docker.com/guides/angular/develop/)

----
url: https://docs.docker.com/engine/manage-resources/pruning/
----

# Prune unused Docker objects

***

Table of contents

***

Docker takes a conservative approach to cleaning up unused objects (often referred to as "garbage collection"), such as images, containers, volumes, and networks. These objects are generally not removed unless you explicitly ask Docker to do so. This can cause Docker to use extra disk space. For each type of object, Docker provides a `prune` command. In addition, you can use `docker system prune` to clean up multiple types of objects at once. This topic shows how to use these `prune` commands.

## [Prune images](#prune-images)

The `docker image prune` command allows you to clean up unused images. By default, `docker image prune` only cleans up *dangling* images. A dangling image is one that isn't tagged, and isn't referenced by any container. To remove dangling images:

```console
$ docker image prune

WARNING! This will remove all dangling images.
Are you sure you want to continue? [y/N] y
```

To remove all images which aren't used by existing containers, use the `-a` flag:

```console
$ docker image prune -a

WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N] y
```

By default, you are prompted to continue. To bypass the prompt, use the `-f` or `--force` flag.

You can limit which images are pruned using filtering expressions with the `--filter` flag. For example, to only consider images created more than 24 hours ago:

```console
$ docker image prune -a --filter "until=24h"
```

Other filtering expressions are available. See the [`docker image prune` reference](/reference/cli/docker/image/prune/) for more examples.

## [Prune containers](#prune-containers)

When you stop a container, it isn't automatically removed unless you started it with the `--rm` flag. To see all containers on the Docker host, including stopped containers, use `docker ps -a`. You may be surprised how many containers exist, especially on a development system! A stopped container's writable layers still take up disk space. To clean this up, you can use the `docker container prune` command.

```console
$ docker container prune

WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y
```

By default, you're prompted to continue. To bypass the prompt, use the `-f` or `--force` flag.

By default, all stopped containers are removed. You can limit the scope using the `--filter` flag. For instance, the following command only removes stopped containers older than 24 hours:

```console
$ docker container prune --filter "until=24h"
```

Other filtering expressions are available. See the [`docker container prune` reference](/reference/cli/docker/container/prune/) for more examples.

## [Prune volumes](#prune-volumes)

Volumes can be used by one or more containers, and take up space on the Docker host. Volumes are never removed automatically, because to do so could destroy data.

```console
$ docker volume prune

WARNING! This will remove all volumes not used by at least one container.
Are you sure you want to continue? [y/N] y
```

By default, you are prompted to continue. To bypass the prompt, use the `-f` or `--force` flag.

By default, all unused volumes are removed. You can limit the scope using the `--filter` flag. For instance, the following command only removes volumes which aren't labelled with the `keep` label:

```console
$ docker volume prune --filter "label!=keep"
```

Other filtering expressions are available. See the [`docker volume prune` reference](/reference/cli/docker/volume/prune/) for more examples.

## [Prune networks](#prune-networks)

Docker networks don't take up much disk space, but they do create `iptables` rules, bridge network devices, and routing table entries. To clean these things up, you can use `docker network prune` to clean up networks which aren't used by any containers.

```console
$ docker network prune

WARNING! This will remove all networks not used by at least one container.
Are you sure you want to continue? [y/N] y
```

By default, you're prompted to continue. To bypass the prompt, use the `-f` or `--force` flag.

By default, all unused networks are removed. You can limit the scope using the `--filter` flag. For instance, the following command only removes networks older than 24 hours:

```console
$ docker network prune --filter "until=24h"
```

Other filtering expressions are available. See the [`docker network prune` reference](/reference/cli/docker/network/prune/) for more examples.

## [Prune build cache](#prune-build-cache)

`docker buildx prune` removes the build cache for the currently selected builder. If you use multiple builders, each builder maintains its own cache — use the `--builder` flag to target a specific builder instance.

```console
$ docker buildx prune

WARNING! This will remove all dangling build cache.
Are you sure you want to continue? [y/N] y
```

By default, you're prompted to continue. To bypass the prompt, use the `-f` or `--force` flag.

See the [`docker buildx prune` reference](/reference/cli/docker/buildx/prune/) for all options, including `--all` to also remove internal and frontend images.

## [Prune everything](#prune-everything)

The `docker system prune` command is a shortcut that prunes images, containers, and networks. Volumes aren't pruned by default, and you must specify the `--volumes` flag for `docker system prune` to prune volumes.

```console
$ docker system prune

WARNING! This will remove:
        - all stopped containers
        - all networks not used by at least one container
        - all dangling images
        - unused build cache

Are you sure you want to continue? [y/N] y
```

To also prune volumes, add the `--volumes` flag:

```console
$ docker system prune --volumes

WARNING! This will remove:
        - all stopped containers
        - all networks not used by at least one container
        - all volumes not used by at least one container
        - all dangling images
        - all build cache

Are you sure you want to continue? [y/N] y
```

By default, you're prompted to continue. To bypass the prompt, use the `-f` or `--force` flag.

By default, all unused containers, networks, and images are removed. You can limit the scope using the `--filter` flag. For instance, the following command removes items older than 24 hours:

```console
$ docker system prune --filter "until=24h"
```

Other filtering expressions are available. See the [`docker system prune` reference](/reference/cli/docker/system/prune/) for more examples.

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/cli/
----

# Use MCP Toolkit from the CLI

***

Table of contents

***

Availability: Beta

> Note
>
> The `docker mcp` commands documented here are available in Docker Desktop 4.62 and later. Earlier versions may not support all commands shown.

The `docker mcp` commands let you manage MCP profiles, servers, OAuth credentials, and catalogs from the terminal. Use the CLI for scripting, automation, and headless environments.

## [Profiles](#profiles)

### [Create a profile](#create-a-profile)

```console
$ docker mcp profile create --name <profile-id>
```

The profile ID is used to reference the profile in subsequent commands:

```console
$ docker mcp profile create --name web-dev
```

### [List profiles](#list-profiles)

```console
$ docker mcp profile list
```

### [View a profile](#view-a-profile)

```console
$ docker mcp profile show <profile-id>
```

### [Remove a profile](#remove-a-profile)

```console
$ docker mcp profile remove <profile-id>
```

> Caution
>
> Removing a profile deletes all its server configurations and settings. This action can't be undone.

## [Servers](#servers)

### [Browse the catalog](#browse-the-catalog)

List available servers and their IDs:

```console
$ docker mcp catalog server ls mcp/docker-mcp-catalog
```

The output lists each server by name. The name (for example, `playwright` or `github-official`) is the server ID to use in `catalog://` URIs.

To look up a server ID in Docker Desktop, open **MCP Toolkit** > **Catalog**, select a server, and check the **Server ID** field.

### [Add servers to a profile](#add-servers-to-a-profile)

Servers are referenced by URI. The URI format depends on where the server comes from:

| Format                                | Source                     |
| ------------------------------------- | -------------------------- |
| `catalog://<catalog-ref>/<server-id>` | An OCI catalog             |
| `docker://<image>:<tag>`              | A Docker image             |
| `https://<url>/v0/servers/<uuid>`     | The MCP community registry |
| `file://<path>`                       | A local YAML or JSON file  |

The most common format is `catalog://`, where `<catalog-ref>` matches the **Catalog** field and `<server-id>` matches the **Server ID** field shown in Docker Desktop or in the `catalog server ls` output:

```console
$ docker mcp profile server add <profile-id> \
  --server catalog://<catalog-ref>/<server-id>
```

Add multiple servers in one command:

```console
$ docker mcp profile server add web-dev \
  --server catalog://mcp/docker-mcp-catalog/github-official \
  --server catalog://mcp/docker-mcp-catalog/playwright
```

To add a server defined in a local YAML file:

```console
$ docker mcp profile server add my-profile \
  --server file://./my-server.yaml
```

The YAML file defines the server image and configuration:

```yaml
name: my-server
title: My Server
type: server
image: myimage:latest
description: Description of the server
```

If the server requires OAuth authentication, authorize it in Docker Desktop after adding. See [OAuth authentication](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/#oauth-authentication).

### [List servers](#list-servers)

List all servers across all profiles:

```console
$ docker mcp profile server ls
```

Filter by profile:

```console
$ docker mcp profile server ls --filter profile=web-dev
```

### [Remove a server](#remove-a-server)

```console
$ docker mcp profile server remove <profile-id> --name <server-name>
```

Remove multiple servers at once:

```console
$ docker mcp profile server remove web-dev \
  --name github-official \
  --name playwright
```

### [Configure server settings](#configure-server-settings)

Set and retrieve configuration values for servers in a profile:

```console
$ docker mcp profile config <profile-id> --set <server-id>.<key>=<value>
$ docker mcp profile config <profile-id> --get-all
$ docker mcp profile config <profile-id> --del <server-id>.<key>
```

Server configuration keys and their expected values are defined by each server. Check the server's documentation or its entry in Docker Desktop under **MCP Toolkit** > **Catalog** > **Configuration**.

## [Gateway](#gateway)

Run the MCP Gateway with a specific profile:

```console
$ docker mcp gateway run --profile <profile-id>
```

Omit `--profile` to use the default profile.

### [Connect a client manually](#connect-a-client-manually)

To connect any client that isn't listed in Docker Desktop, configure it to run the gateway over `stdio`. For example, in a JSON-based client configuration:

```json
{
  "servers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "web-dev"],
      "type": "stdio"
    }
  }
}
```

For Claude Desktop, the format is:

```json
{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "web-dev"]
    }
  }
}
```

### [Connect a named client](#connect-a-named-client)

Connect a supported client to a profile:

```console
$ docker mcp client connect <client> --profile <profile-id>
```

For example, to connect VS Code to a project-specific profile:

```console
$ docker mcp client connect vscode --profile my-project
```

This creates a `.vscode/mcp.json` file in the current directory. Because this is a user-specific file, add it to `.gitignore`:

```console
$ echo ".vscode/mcp.json" >> .gitignore
```

## [Share profiles](#share-profiles)

Share profiles with your team using OCI registries or version control.

### [Share via OCI registry](#share-via-oci-registry)

Profiles are shared as OCI artifacts via any OCI-compatible registry. Credentials are not included for security reasons. Team members configure authentication credentials separately after pulling.

To push an existing profile called `web-dev` to an OCI registry:

```console
$ docker mcp profile push web-dev registry.example.com/profiles/web-dev:v1
```

To pull the same profile:

```console
$ docker mcp profile pull registry.example.com/profiles/team-standard:latest
```

### [Share via version control](#share-via-version-control)

For project-specific profiles, you can use the `export` and `import` commands and store the profiles in version control alongside your code. Team members can import the file to get the same configuration.

To export a profile to your project directory:

```console
$ mkdir -p .docker
$ docker mcp profile export web-dev .docker/mcp-profile.json
```

Team members who clone the repository can import the profile:

```console
$ docker mcp profile import .docker/mcp-profile.json
```

This creates a profile with the servers and configuration defined in the file. Any authentication credentials must be configured separately if needed.

## [Custom catalogs](#custom-catalogs)

Custom catalogs let you curate a focused collection of servers for your team or organization. For an overview of what custom catalogs are and when to use them, see [Custom catalogs](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/#custom-catalogs).

Catalogs are referenced by OCI reference, for example `registry.example.com/mcp/my-catalog:latest`. Servers within a catalog use the same URI schemes as when [adding servers to a profile](#add-servers-to-a-profile).

### [Customize the Docker catalog](#customize-the-docker-catalog)

Use the Docker catalog as a base, then add or remove servers to fit your organization's needs. Copy it first:

```console
$ docker mcp catalog tag mcp/docker-mcp-catalog \
  registry.example.com/mcp/company-tools:latest
```

List the servers it contains:

```console
$ docker mcp catalog server ls registry.example.com/mcp/company-tools:latest
```

Remove servers your organization doesn't approve:

```console
$ docker mcp catalog server remove \
  registry.example.com/mcp/company-tools:latest \
  --name <server-name>
```

Add your own private servers, packaged as Docker images:

```console
$ docker mcp catalog server add registry.example.com/mcp/company-tools:latest \
  --server docker://registry.example.com/mcp/internal-api:latest \
  --server docker://registry.example.com/mcp/data-pipeline:latest
```

Push when ready:

```console
$ docker mcp catalog push registry.example.com/mcp/company-tools:latest
```

### [Build a catalog from scratch](#build-a-catalog-from-scratch)

To include exactly what you choose and nothing else, create a catalog from scratch. You can include servers from the Docker catalog, your own private images, or both.

Create a catalog and specify which servers to include:

```console
$ docker mcp catalog create registry.example.com/mcp/data-tools:latest \
  --title "Data Analysis Tools" \
  --server catalog://mcp/docker-mcp-catalog/sequentialthinking \
  --server catalog://mcp/docker-mcp-catalog/brave \
  --server docker://registry.example.com/mcp/analytics:latest
```

View the result:

```console
$ docker mcp catalog show registry.example.com/mcp/data-tools:latest
```

Push to distribute:

```console
$ docker mcp catalog push registry.example.com/mcp/data-tools:latest
```

### [Distribute a catalog](#distribute-a-catalog)

Push your catalog so team members can import it:

```console
$ docker mcp catalog push <oci-reference>
```

Team members can pull it using the CLI:

```console
$ docker mcp catalog pull <oci-reference>
```

Or import it using Docker Desktop: select **MCP Toolkit** > **Catalog** > **Import catalog** and enter the OCI reference.

### [Use a custom catalog with the gateway](#use-a-custom-catalog-with-the-gateway)

Run the gateway with your catalog instead of the default Docker catalog:

```console
$ docker mcp gateway run --catalog <oci-reference>
```

For [Dynamic MCP](https://docs.docker.com/ai/mcp-catalog-and-toolkit/dynamic-mcp/), where agents discover and add servers during conversations, this limits what agents can find to your curated set.

To enable specific servers from your catalog without using a profile:

```console
$ docker mcp gateway run --catalog <oci-reference> \
  --servers <name1> --servers <name2>
```

## [Further reading](#further-reading)

* [Get started with MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/get-started/)
* [MCP Profiles](https://docs.docker.com/ai/mcp-catalog-and-toolkit/profiles/)
* [MCP Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/)
* [MCP Gateway](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/create/
----

# docker buildx create

***

| Description | Create a new builder instance                        |
| ----------- | ---------------------------------------------------- |
| Usage       | `docker buildx create [OPTIONS] [CONTEXT\|ENDPOINT]` |

## [Description](#description)

Create makes a new builder instance pointing to a Docker context or endpoint, where context is the name of a context from `docker context ls` and endpoint is the address for Docker socket (eg. `DOCKER_HOST` value).

By default, the current Docker configuration is used for determining the context/endpoint value.

Builder instances are isolated environments where builds can be invoked. All Docker contexts also get the default builder instance.

## [Options](#options)

| Option                                    | Default | Description                                                            |
| ----------------------------------------- | ------- | ---------------------------------------------------------------------- |
| [`--append`](#append)                     |         | Append a node to builder instead of changing it                        |
| `--bootstrap`                             |         | Boot builder after creation                                            |
| [`--buildkitd-config`](#buildkitd-config) |         | BuildKit daemon config file                                            |
| [`--buildkitd-flags`](#buildkitd-flags)   |         | BuildKit daemon flags                                                  |
| [`--driver`](#driver)                     |         | Driver to use (available: `docker-container`, `kubernetes`, `remote`)  |
| [`--driver-opt`](#driver-opt)             |         | Options for the driver                                                 |
| [`--leave`](#leave)                       |         | Remove a node from builder instead of changing it                      |
| [`--name`](#name)                         |         | Builder instance name                                                  |
| [`--node`](#node)                         |         | Create/modify node with given name                                     |
| [`--platform`](#platform)                 |         | Fixed platforms for current node                                       |
| `--timeout`                               | `20s`   | Override the default timeout for loading builder status                |
| [`--use`](#use)                           |         | Set the current builder instance                                       |

## [Examples](#examples)

### [Append a new node to an existing builder (--append)](#append)

The `--append` flag changes the action of the command to append a new node to an existing builder specified by `--name`. Buildx will choose an appropriate node for a build based on the platforms it supports.

```console
$ docker buildx create mycontext1
eager_beaver

$ docker buildx create --name eager_beaver --append mycontext2
eager_beaver
```

### [Specify a configuration file for the BuildKit daemon (--buildkitd-config)](#buildkitd-config)

```text
--buildkitd-config FILE
```

Specifies the configuration file for the BuildKit daemon to use. The configuration can be overridden by [`--buildkitd-flags`](#buildkitd-flags). See an [example BuildKit daemon configuration file](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md).

If you don't specify a configuration file, Buildx looks for one by default in:

* `$BUILDX_CONFIG/buildkitd.default.toml`
* `$DOCKER_CONFIG/buildx/buildkitd.default.toml`
* `~/.docker/buildx/buildkitd.default.toml`

Note that if you create a `docker-container` builder and have specified certificates for registries in the `buildkitd.toml` configuration, the files will be copied into the container under `/etc/buildkit/certs` and configuration will be updated to reflect that.

### [Specify options for the BuildKit daemon (--buildkitd-flags)](#buildkitd-flags)

```text
--buildkitd-flags FLAGS
```

Adds flags when starting the BuildKit daemon. They take precedence over the configuration file specified by [`--buildkitd-config`](#buildkitd-config). See `buildkitd --help` for the available flags.

```text
--buildkitd-flags '--debug --debugaddr 0.0.0.0:6666'
```

#### [BuildKit daemon network mode](#buildkit-daemon-network-mode)

You can specify the network mode for the BuildKit daemon with either the configuration file specified by [`--buildkitd-config`](#buildkitd-config) using the `worker.oci.networkMode` option or `--oci-worker-net` flag here. The default value is `auto` and can be one of `bridge`, `cni`, `host`:

```text
--buildkitd-flags '--oci-worker-net bridge'
```

> Note
>
> Network mode "bridge" is supported since BuildKit v0.13 and will become the default in next v0.14.

### [Set the builder driver to use (--driver)](#driver)

```text
--driver DRIVER
```

Sets the builder driver to be used. A driver is a configuration of a BuildKit backend. Buildx supports the following drivers:

* `docker` (default)
* `docker-container`
* `kubernetes`
* `remote`

For more information about build drivers, see [here](/build/builders/drivers/).

#### [`docker` driver](#docker-driver)

Uses the builder that is built into the Docker daemon. With this driver, the [`--load`](/reference/cli/docker/buildx/build/#load) flag is implied by default on `buildx build`. However, building multi-platform images or exporting cache is not currently supported.

#### [`docker-container` driver](#docker-container-driver)

Uses a BuildKit container that will be spawned via Docker. With this driver, both building multi-platform images and exporting cache are supported.

Unlike `docker` driver, built images will not automatically appear in `docker images` and [`build --load`](/reference/cli/docker/buildx/build/#load) needs to be used to achieve that.

#### [`kubernetes` driver](#kubernetes-driver)

Uses Kubernetes pods. With this driver, you can spin up pods with defined BuildKit container image to build your images.

Unlike `docker` driver, built images will not automatically appear in `docker images` and [`build --load`](/reference/cli/docker/buildx/build/#load) needs to be used to achieve that.

#### [`remote` driver](#remote-driver)

Uses a remote instance of BuildKit daemon over an arbitrary connection. With this driver, you manually create and manage instances of buildkit yourself, and configure buildx to point at it.

Unlike `docker` driver, built images will not automatically appear in `docker images` and [`build --load`](/reference/cli/docker/buildx/build/#load) needs to be used to achieve that.

### [Set additional driver-specific options (--driver-opt)](#driver-opt)

```text
--driver-opt OPTIONS
```

Passes additional driver-specific options. For information about available driver options, refer to the detailed documentation for the specific driver:

* [`docker` driver](/build/builders/drivers/docker/)
* [`docker-container` driver](/build/builders/drivers/docker-container/)
* [`kubernetes` driver](/build/builders/drivers/kubernetes/)
* [`remote` driver](/build/builders/drivers/remote/)

### [Remove a node from a builder (--leave)](#leave)

The `--leave` flag changes the action of the command to remove a node from a builder. The builder needs to be specified with `--name` and node that is removed is set with `--node`.

```console
$ docker buildx create --name mybuilder --node mybuilder0 --leave
```

### [Specify the name of the builder (--name)](#name)

```text
--name NAME
```

The `--name` flag specifies the name of the builder to be created or modified. If none is specified, one will be automatically generated.

### [Specify the name of the node (--node)](#node)

```text
--node NODE
```

The `--node` flag specifies the name of the node to be created or modified. If you don't specify a name, the node name defaults to the name of the builder it belongs to, with an index number suffix.

### [Set the platforms supported by the node (--platform)](#platform)

```text
--platform PLATFORMS
```

The `--platform` flag sets the platforms supported by the node. It expects a comma-separated list of platforms of the form OS/architecture/variant. The node will also automatically detect the platforms it supports, but manual values take priority over the detected ones and can be used when multiple nodes support building for the same platform.

```console
$ docker buildx create --platform linux/amd64
$ docker buildx create --platform linux/arm64,linux/arm/v7
```

### [Automatically switch to the newly created builder (--use)](#use)

The `--use` flag automatically switches the current builder to the newly created one. Equivalent to running `docker buildx use $(docker buildx create ...)`.

----
url: https://docs.docker.com/engine/release-notes/28/
----

# Docker Engine version 28 release notes

***

Table of contents

***

This page describes the latest changes, additions, known issues, and fixes for Docker Engine version 28.

For more information about:

* Deprecated and removed features, see [Deprecated Engine Features](https://docs.docker.com/engine/deprecated/).
* Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history/).

## [28.5.2](#2852)

*2025-11-05*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.5.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.5.2)
* [moby/moby, 28.5.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.5.2)

> Caution
>
> This release contains fixes for three high-severity security vulnerabilities in runc:
>
> * [CVE-2025-31133](https://github.com/opencontainers/runc/security/advisories/GHSA-9493-h29p-rfm2)
> * [CVE-2025-52565](https://github.com/opencontainers/runc/security/advisories/GHSA-qw9x-cqr3-wc7r)
> * [CVE-2025-52881](https://github.com/opencontainers/runc/security/advisories/GHSA-cgrx-mc8f-2prm)
>
> All three vulnerabilities ultimately allow (through different methods) for full container breakouts by bypassing runc's restrictions for writing to arbitrary `/proc` files.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* dockerd-rootless.sh: if slirp4netns is not installed, try using pasta (passt). [moby/moby#51162](https://github.com/moby/moby/pull/51162)

### [Packaging updates](#packaging-updates)

* Update BuildKit to [v0.25.2](https://github.com/moby/buildkit/releases/tag/v0.25.2). [moby/moby#51398](https://github.com/moby/moby/pull/51398)
* Update Go runtime to [1.24.9](https://go.dev/doc/devel/release#go1.24.9). [moby/moby#51387](https://github.com/moby/moby/pull/51387), [docker/cli#6613](https://github.com/docker/cli/pull/6613)
* Update runc to [v1.3.3](https://github.com/opencontainers/runc/releases/tag/v1.3.3). [moby/moby#51394](https://github.com/moby/moby/pull/51394)

### [Deprecations](#deprecations)

* Go-SDK: cli/command/image/build: deprecate `DefaultDockerfileName`, `DetectArchiveReader`, `WriteTempDockerfile`, `ResolveAndValidateContextPath`. These utilities were only used internally and will be removed in the next release. [docker/cli#6610](https://github.com/docker/cli/pull/6610)
* Go-SDK: cli/command/image/build: deprecate IsArchive utility. [docker/cli#6560](https://github.com/docker/cli/pull/6560)
* Go-SDK: opts: deprecate `ValidateMACAddress`. [docker/cli#6560](https://github.com/docker/cli/pull/6560)
* Go-SDK: opts: deprecate ListOpts.Delete(). [docker/cli#6560](https://github.com/docker/cli/pull/6560)

## [28.5.1](#2851)

*2025-10-08*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.5.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.5.1)
* [moby/moby, 28.5.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.5.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-1)

* Update BuildKit to v0.25.1. [moby/moby#51137](https://github.com/moby/moby/pull/51137)
* Update Go runtime to [1.24.8](https://go.dev/doc/devel/release#go1.24.8). [moby/moby#51133](https://github.com/moby/moby/pull/51133), [docker/cli#6541](https://github.com/docker/cli/pull/6541)

### [Deprecations](#deprecations-1)

* api/types/image: InspectResponse: deprecate `Parent` and `DockerVersion` fields. [moby/moby#51105](https://github.com/moby/moby/pull/51105)
* api/types/plugin: deprecate `Config.DockerVersion` field. [moby/moby#51110](https://github.com/moby/moby/pull/51110)

## [28.5.0](#2850)

*2025-10-02*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.5.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.5.0)
* [moby/moby, 28.5.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.5.0)

> Warning
>
> **Raspberry Pi OS 32-bit (armhf) Deprecation**
>
> Docker Engine v28 will be the last major version to support Raspberry Pi OS 32-bit (armhf). Starting with Docker Engine v29, new major versions will **no longer provide packages** for Raspberry Pi OS 32-bit (armhf).
>
> #### [Migration options](#migration-options)
>
> * **64-bit ARM:** Install the Debian `arm64` packages (fully supported).
> * **32-bit ARM (v7):** Install the Debian `armhf` packages (targets ARMv7 CPUs).
>
> **Note:** Older devices based on the ARMv6 architecture are no longer supported by official packages, including:
>
> * Raspberry Pi 1 (Model A/B/A+/B+)
> * Raspberry Pi Zero and Zero W

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-2)

* Don't print warnings in `docker info` for broken symlinks in CLI-plugin directories. [docker/cli#6476](https://github.com/docker/cli/pull/6476)
* Fix a panic during `stats` on empty event `Actor.ID`. [docker/cli#6471](https://github.com/docker/cli/pull/6471)

### [Packaging updates](#packaging-updates-1)

* Remove support for legacy CBC cipher suites. [docker/cli#6474](https://github.com/docker/cli/pull/6474)
* Update Buildkit to [v0.25.0](https://github.com/moby/buildkit/releases/tag/v0.25.0). [moby/moby#51075](https://github.com/moby/moby/pull/51075)
* Update Dockerfile syntax to [v1.19.0](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.19.0). [moby/moby#51075](https://github.com/moby/moby/pull/51075)

### [Networking](#networking)

* Eliminated harmless warning about deletion of `endpoint_count` from the data store. [moby/moby#51064](https://github.com/moby/moby/pull/51064)
* Fix a bug causing IPAM plugins to not be loaded on Windows. [moby/moby#51035](https://github.com/moby/moby/pull/51035)

### [API](#api)

* Deprecate support for kernel memory TCP accounting (`KernelMemoryTCP`). [moby/moby#51067](https://github.com/moby/moby/pull/51067)
* Fix `GET containers/{name}/checkpoints` returning `null` instead of empty JSON array when there are no checkpoints. [moby/moby#51052](https://github.com/moby/moby/pull/51052)

### [Go SDK](#go-sdk)

* cli-plugins/plugin: Run: allow customizing the CLI. [docker/cli#6481](https://github.com/docker/cli/pull/6481)
* cli/command: add `WithUserAgent` option. [docker/cli#6477](https://github.com/docker/cli/pull/6477)

### [Deprecations](#deprecations-2)

* Go-SDK: cli/command: deprecate `DockerCli.Apply`. This method is no longer used and will be removed in the next release if there are no remaining uses. [docker/cli#6497](https://github.com/docker/cli/pull/6497)
* Go-SDK: cli/command: deprecate `DockerCli.ContentTrustEnabled`. This method is no longer used and will be removed in the next release. [docker/cli#6495](https://github.com/docker/cli/pull/6495)
* Go-SDK: cli/command: deprecate `DockerCli.DefaultVersion`. This method is no longer used and will be removed in the next release. [docker/cli#6491](https://github.com/docker/cli/pull/6491)
* Go-SDK: cli/command: deprecate `ResolveDefaultContext` utility. [docker/cli#6529](https://github.com/docker/cli/pull/6529)
* Go-SDK: cli/command: deprecate `WithContentTrustFromEnv`, `WithContentTrust` options. These options were used internally, and will be removed in the next release.. [docker/cli#6489](https://github.com/docker/cli/pull/6489)
* Go-SDK: cli/manifest/store: deprecate `IsNotFound()`. [docker/cli#6514](https://github.com/docker/cli/pull/6514)
* Go-SDK: templates: deprecate NewParse() function. [docker/cli#6469](https://github.com/docker/cli/pull/6469)

## [28.4.0](#2840)

*2025-09-03*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.4.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.4.0)
* [moby/moby, 28.4.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.4.0)

### [New](#new)

* Allow Docker CLI to set the `GODEBUG` environment variable when the key-value pair (`"GODEBUG":"..."`) exists inside the docker context metadata. [docker/cli#6399](https://github.com/docker/cli/pull/6399)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-3)

* Add shell completion for `docker pull` and `docker image pull`. [docker/cli#6420](https://github.com/docker/cli/pull/6420)
* Fix a regression in v28.3.3 that could cause a panic on `docker push` if the client did not send an `X-Registry-Auth` header. [moby/moby#50738](https://github.com/moby/moby/pull/50738)
* Windows: Potentially fix an issue with "access denied" error when pulling images. [moby/moby#50871](https://github.com/moby/moby/pull/50871)
* containerd image store: Fix `docker history` failing with `snapshot X does not exist` when calling on a non-native image that was built locally. [moby/moby#50875](https://github.com/moby/moby/pull/50875)
* containerd image store: Fix `docker image prune` to emit correct `untag` and `delete` events and list only the deleted images root digests instead of every blob. [moby/moby#50837](https://github.com/moby/moby/pull/50837)
* Remove interactive login prompt from `docker push` and `docker pull` after a failure caused by missing authentication. [docker/cli#6256](https://github.com/docker/cli/pull/6256)

### [Packaging updates](#packaging-updates-2)

* Update BuildKit to [v0.24.0](https://github.com/moby/buildkit/releases/tag/v0.24.0). [moby#50888](https://github.com/moby/moby/pull/50888)
* Update Go runtime to [1.24.7](https://go.dev/doc/devel/release#go1.24.6). [moby/moby#50889](https://github.com/moby/moby/pull/50889), [docker/cli#6422](https://github.com/docker/cli/pull/6422)
* Update `runc` to [v1.3.0](https://github.com/opencontainers/runc/releases/tag/v1.3.0). [moby/moby#50699](https://github.com/moby/moby/pull/50699)
* Update containerd (static binaries only) to [v1.7.28](https://github.com/containerd/containerd/releases/tag/v1.7.28). [moby/moby#50700](https://github.com/moby/moby/pull/50700)

### [Networking](#networking-1)

* Fix an issue that could cause slow container restart on live-restore. [moby/moby#50829](https://github.com/moby/moby/pull/50829)

### [API](#api-1)

* Update deprecation message for `AuthConfig.Email` field. [moby/moby#50797](https://github.com/moby/moby/pull/50797)

### [Go SDK](#go-sdk-1)

* Deprecate profiles package which got migrated to [github.com/moby/profiles](https://github.com/moby/profiles). [moby/moby#50513](https://github.com/moby/moby/pull/50513)

### [Deprecations](#deprecations-3)

* Deprecate special handling for quoted values for the `--tlscacert`, `--tlscert`, and `--tlskey` command-line flags. [docker/cli#6291](https://github.com/docker/cli/pull/6291)
* Mark legacy links environment variables (`DOCKER_KEEP_DEPRECATED_LEGACY_LINKS_ENV_VARS`) as deprecated in v28.4 and set for removal in v30.0. [docker/cli#6309](https://github.com/docker/cli/pull/6309)
* Go-SDK: Deprecate field `NetworkSettingsBase.Bridge`, struct `NetworkSettingsBase`, all the fields of `DefaultNetworkSettings`, and struct `DefaultNetworkSettings`. [moby/moby#50839](https://github.com/moby/moby/pull/50839)
* Go-SDK: api/types: `build.CacheDiskUsage`, `container.DiskUsage`, `images.DiskUsage` and `volumes.DiskUsage` are now deprecated and will be removed in the next major release. [moby/moby#50768](https://github.com/moby/moby/pull/50768)
* Go-SDK: cli-plugins/manager: deprecate `ReexecEnvvar`. [docker/cli#6411](https://github.com/docker/cli/pull/6411)
* Go-SDK: cli-plugins/manager: deprecate annotation aliases (`CommandAnnotationPlugin`, `CommandAnnotationPluginVendor`, `CommandAnnotationPluginVersion`, `CommandAnnotationPluginInvalid`, `CommandAnnotationPluginCommandPath`) in favor of their equivalent in `cli-plugins/manager/metadata`. [docker/cli#6298](https://github.com/docker/cli/pull/6298)
* Go-SDK: cli-plugins/manager: deprecate metadata aliases (`NamePrefix`, `MetadataSubcommandName`, `HookSubcommandName`, `Metadata`, `ReexecEnvvar`) in favor of their equivalent in `cli-plugins/manager/metadata`. [docker/cli#6269](https://github.com/docker/cli/pull/6269)
* Go-SDK: cli-plugins/manager: remove `Candidate` interface, which was only for internal use. [docker/cli#6269](https://github.com/docker/cli/pull/6269)
* Go-SDK: cli-plugins/manager: remove `NewPluginError` function, which was only for internal use. [docker/cli#6269](https://github.com/docker/cli/pull/6269)
* Go-SDK: cli-plugins/manager: remove deprecated `ResourceAttributesEnvvar` const. [docker/cli#6269](https://github.com/docker/cli/pull/6269)
* Go-SDK: cli/command/builder: deprecate `NewBuilderCommand` and `NewBakeStubCommand`. These functions will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/builder: deprecate `NewPruneCommand`. [docker/cli#6343](https://github.com/docker/cli/pull/6343)
* Go-SDK: cli/command/checkpoint: deprecate `NewCheckpointCommand`. This function will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/checkpoint: deprecate `NewFormat`, `FormatWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/completion: deprecate `NoComplete`. [docker/cli#6405](https://github.com/docker/cli/pull/6405)
* Go-SDK: cli/command/completion: remove deprecated `ValidArgsFn`. [docker/cli#6259](https://github.com/docker/cli/pull/6259)
* Go-SDK: cli/command/config: deprecate `NewConfigCommand`. This function will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/config: deprecate `NewFormat`, `FormatWrite`, `InspectFormatWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/config: deprecate `RunConfigCreate`, `CreateOptions`, `RunConfigInspect`, `InspectOptions`, `RunConfigList`, `ListOptions`, `RunConfigRemove`, and `RemoveOptions`. [docker/cli#6369](https://github.com/docker/cli/pull/6369)
* Go-SDK: cli/command/container: deprecate `NewBuildCommand`, `NewPullCommand`, `NewPushCommand`, `NewImagesCommand`, `NewImageCommand`, `NewHistoryCommand`, `NewImportCommand`, `NewLoadCommand`, `NewRemoveCommand`, `NewSaveCommand`, `NewTagCommand`, `NewPruneCommand`. These functions will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/container: deprecate `NewDiffFormat`, `DiffFormatWrite`. These functions were only used internally and will be removed in the next release. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/container: deprecate `NewRunCommand`, `NewExecCommand`, `NewPsCommand`, `NewContainerCommand`, `NewAttachCommand`, `NewCommitCommand`, `NewCopyCommand`, `NewCreateCommand`, `NewDiffCommand`, `NewExportCommand`, `NewKillCommand`, `NewLogsCommand`, `NewPauseCommand`, `NewPortCommand`, `NewRenameCommand`, `NewRestartCommand`, `NewRmCommand`, `NewStartCommand`, `NewStatsCommand`, `NewStopCommand`, `NewTopCommand`, `NewUnpauseCommand`, `NewUpdateCommand`, `NewWaitCommand`, `NewPruneCommand`. These functions will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/context: deprecate `NewContextCommand`. This function will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/context: deprecate `RunCreate` and `CreateOptions`. [docker/cli#6403](https://github.com/docker/cli/pull/6403)
* Go-SDK: cli/command/context: deprecate `RunExport` and `ExportOptions`. [docker/cli#6403](https://github.com/docker/cli/pull/6403)
* Go-SDK: cli/command/context: deprecate `RunImport`. [docker/cli#6403](https://github.com/docker/cli/pull/6403)
* Go-SDK: cli/command/context: deprecate `RunRemove` and `RemoveOptions`. [docker/cli#6403](https://github.com/docker/cli/pull/6403)
* Go-SDK: cli/command/context: deprecate `RunUpdate` and `UpdateOptions`. [docker/cli#6403](https://github.com/docker/cli/pull/6403)
* Go-SDK: cli/command/context: deprecate `RunUse`. [docker/cli#6403](https://github.com/docker/cli/pull/6403)
* Go-SDK: cli/command/image: deprecate `AuthResolver` utility. [docker/cli#6357](https://github.com/docker/cli/pull/6357)
* Go-SDK: cli/command/image: deprecate `NewHistoryFormat`, `HistoryWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341), [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/manifest: deprecate `NewManifestCommand`. This functions will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/network: deprecate `NewFormat`, `FormatWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/network: deprecate `NewNetworkCommand`. These functions will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/node: deprecate `NewFormat`, `FormatWrite`, `InspectFormatWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/node: deprecate `NewNodeCommand`. This functions will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/plugin: deprecate `NewFormat`, `FormatWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/plugin: deprecate `NewPluginCommand`. This function will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/registry: deprecate `NewLoginCommand`, `NewLogoutCommand`, `NewSearchCommand`. These functions will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/registry: deprecate `NewSearchFormat`, `SearchWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/registry: deprecate `OauthLoginEscapeHatchEnvVar` const. [docker/cli#6413](https://github.com/docker/cli/pull/6413)
* Go-SDK: cli/command/secret: deprecate `NewFormat`, `FormatWrite`, `InspectFormatWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/secret: deprecate `NewSecretCommand`. This functions will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/service: deprecate `NewFormat`, `InspectFormatWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/service: deprecate `NewServiceCommand`. This function will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/stack: deprecate `NewStackCommand`. This function will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/stack: deprecate `RunList`, `RunServices`. [docker/cli#6391](https://github.com/docker/cli/pull/6391)
* Go-SDK: cli/command/swarm: deprecate `NewSwarmCommand`. This function will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/system: deprecate `NewVersionCommand`, `NewInfoCommand`, `NewSystemCommand`, `NewEventsCommand`, `NewInspectCommand`. These functions will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/task: deprecate `NewTaskFormat`, `FormatWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/trust: deprecate `NewTrustCommand`. This function will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command/trust: deprecate `SignedTagInfo`, `SignerInfo`, `NewTrustTagFormat`, `NewSignerInfoFormat`, `TagWrite`, `SignerInfoWrite`. [docker/cli#6341](https://github.com/docker/cli/pull/6341)
* Go-SDK: cli/command/volume: deprecate `NewVolumeCommand`, `NewPruneCommand`. These functions will be removed in the next release. [docker/cli#6312](https://github.com/docker/cli/pull/6312)
* Go-SDK: cli/command: remove `AddTrustSigningFlags`, `AddTrustVerificationFlags`, and `AddPlatformFlag` utilities, which were only used internally. [docker/cli#6311](https://github.com/docker/cli/pull/6311)
* Go-SDK: cli/command: remove deprecated `ConfigureAuth` utility. [docker/cli#6257](https://github.com/docker/cli/pull/6257)
* Go-SDK: cli/command: remove deprecated `CopyToFile` utility. [docker/cli#6257](https://github.com/docker/cli/pull/6257)
* Go-SDK: cli/config/types: update deprecation message for `AuthConfig.Email` field. [docker/cli#6392](https://github.com/docker/cli/pull/6392)
* Go-SDK: cli: deprecate `VisitAll`, `DisableFlagsInUseLine` utilities. These utilities were only used internally and will be removed in the next release. [docker/cli#6276](https://github.com/docker/cli/pull/6276)
* Go-SDK: cli: remove `HasCompletionArg` utility. This utility was only used internally. [docker/cli#6276](https://github.com/docker/cli/pull/6276)
* Go-SDK: deprecate `cli/command.RegistryAuthenticationPrivilegedFunc`. [docker/cli#6256](https://github.com/docker/cli/pull/6256)
* Go-SDK: deprecate cli/command/stack/formatter. [docker/cli#6391](https://github.com/docker/cli/pull/6391)
* Go-SDK: deprecate cli/command/stack/loader. [docker/cli#6391](https://github.com/docker/cli/pull/6391)
* Go-SDK: deprecate cli/command/stack/options. [docker/cli#6391](https://github.com/docker/cli/pull/6391)
* Go-SDK: deprecate cli/command/stack/swarm. [docker/cli#6391](https://github.com/docker/cli/pull/6391)
* Go-SDK: opts: deprecate `NewNamedListOptsRef`, `NewNamedMapOpts`, `NamedListOpts`, `NamedMapOpts`, and `NamedOption`. These types and functions are no longer used and will be removed in the next release. [docker/cli#6292](https://github.com/docker/cli/pull/6292)
* Go-SDK: opts: deprecate `ParseEnvFile` in favor of `kvfile.Parse`. [docker/cli#6381](https://github.com/docker/cli/pull/6381)
* Go-SDK: opts: deprecate `QuotedString`. This utility is no longer used, and will be removed in the next release. [docker/cli#6275](https://github.com/docker/cli/pull/6275)
* Go-SDK: opts: deprecate `ValidateHost` utility. This function is no longer used, and will be removed in the next release. [docker/cli#6280](https://github.com/docker/cli/pull/6280)
* Go-SDK: pkg/jsonmessage: deprecate the `JSONMessage.From`, `JSONMessage.Time`, and `JSONMessage.TimeNano` fields, as they are no longer returned by the API for progress messages. Use the `events.Message` type instead to unmarshal the `/events` response. [moby/moby#50762](https://github.com/moby/moby/pull/50762)
* Go-SDK: the cli/registry/client package is deprecated and will be removed in the next release. [docker/cli#6313](https://github.com/docker/cli/pull/6313)

## [28.3.3](#2833)

*2025-07-29*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.3.3 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.3.3)
* [moby/moby, 28.3.3 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.3.3)

### [Security](#security)

This release fixes an issue where, after a firewalld reload, published container ports could be accessed directly from the local network, even when they were intended to be accessible only via a loopback address. [CVE-2025-54388](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2025-54388) / [GHSA-x4rx-4gw3-53p4](https://github.com/moby/moby/security/advisories/GHSA-x4rx-4gw3-53p4) / [moby/moby#50506](https://github.com/moby/moby/pull/50506).

### [Packaging updates](#packaging-updates-3)

* Update Buildx to [v0.26.1](https://github.com/docker/buildx/releases/tag/v0.26.1). [docker/docker-ce-packaging#1230](https://github.com/docker/docker-ce-packaging/pull/1230)
* Update Compose to [v2.39.1](https://github.com/docker/compose/releases/tag/v2.39.1). [docker/docker-ce-packaging#1234](https://github.com/docker/docker-ce-packaging/pull/1234)
* Update Docker Model CLI plugin to [v0.1.36](https://github.com/docker/model-cli/releases/tag/v0.1.36). [docker/docker-ce-packaging#1233](https://github.com/docker/docker-ce-packaging/pull/1233)

## [28.3.2](#2832)

*2025-07-09*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.3.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.3.2)
* [moby/moby, 28.3.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.3.2)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-4)

* Fix `--use-api-socket` not working correctly when targeting a remote daemon. [docker/cli#6157](https://github.com/docker/cli/pull/6157)
* Fix stray "otel error" logs being printed if debug logging is enabled. [docker/cli#6160](https://github.com/docker/cli/pull/6160)
* Quote SSH arguments when connecting to a remote daemon over an SSH connection to avoid unexpected expansion. [docker/cli#6147](https://github.com/docker/cli/pull/6147)
* Warn when `DOCKER_AUTH_CONFIG` is set during `docker login` and `docker logout`. [docker/cli#6163](https://github.com/docker/cli/pull/6163)

### [Packaging updates](#packaging-updates-4)

* Update Compose to [v2.38.2](https://github.com/docker/compose/releases/tag/v2.38.2). [docker/docker-ce-packaging#1225](https://github.com/docker/docker-ce-packaging/pull/1225)
* Update Docker Model CLI plugin to [v0.1.33](https://github.com/docker/model-cli/releases/tag/v0.1.33). [docker/docker-ce-packaging#1227](https://github.com/docker/docker-ce-packaging/pull/1227)
* Update Go runtime to 1.24.5. [moby/moby#50354](https://github.com/moby/moby/pull/50354)

## [28.3.1](#2831)

*2025-07-02*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.3.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.3.1)
* [moby/moby, 28.3.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.3.1)

### [Packaging updates](#packaging-updates-5)

* Update BuildKit to [v0.23.2](https://github.com/moby/buildkit/releases/tag/v0.23.2). [moby/moby#50309](https://github.com/moby/moby/pull/50309)
* Update Compose to [v2.38.1](https://github.com/docker/compose/releases/tag/v2.38.1). [docker/docker-ce-packaging#1221](https://github.com/docker/docker-ce-packaging/pull/1221)
* Update Model to v0.1.32 which adds the support for the new top-level `models:` key in Docker Compose. [docker/docker-ce-packaging#1222](https://github.com/docker/docker-ce-packaging/pull/1222)

## [28.3.0](#2830)

*2025-06-24*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.3.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.3.0)
* [moby/moby, 28.3.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.3.0)

### [New](#new-1)

* Add support for AMD GPUs in `docker run --gpus`. [moby/moby#49952](https://github.com/moby/moby/pull/49952)
* Use `DOCKER_AUTH_CONFIG` as a credential store. [docker/cli#6008](https://github.com/docker/cli/pull/6008)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-5)

* Ensure that the state of the container in the daemon database (used by [/containers/json](https://docs.docker.com/reference/api/engine/version/v1.49/#tag/Container/operation/ContainerList) API) is up to date when the container is stopped using the [/containers/{id}/stop](https://docs.docker.com/reference/api/engine/version/v1.49/#tag/Container/operation/ContainerStop) API (before response of API). [moby/moby#50136](https://github.com/moby/moby/pull/50136)
* Fix `docker image inspect inspect` omitting empty fields. [moby/moby#50135](https://github.com/moby/moby/pull/50135)
* Fix `docker images --tree` not marking images as in-use when the containerd image store is disabled. [docker/cli#6140](https://github.com/docker/cli/pull/6140)
* Fix `docker pull/push` hang in non-interactive when authentication is required caused by prompting for login credentials. [docker/cli#6141](https://github.com/docker/cli/pull/6141)
* Fix a potential resource leak when a node leaves a Swarm. [moby/moby#50115](https://github.com/moby/moby/pull/50115)
* Fix a regression where a login prompt on `docker pull` would show Docker Hub-specific hints when logging in on other registries. [docker/cli#6135](https://github.com/docker/cli/pull/6135)
* Fix an issue where all new tasks in the Swarm could get stuck in the PENDING state forever after scaling up a service with placement preferences. [moby/moby#50211](https://github.com/moby/moby/pull/50211)
* Remove an undocumented, hidden, top-level `docker remove` command that was accidentally introduced in Docker 23.0. [docker/cli#6144](https://github.com/docker/cli/pull/6144)
* Validate registry-mirrors configuration as part of `dockerd --validate` and improve error messages for invalid mirrors. [moby/moby#50240](https://github.com/moby/moby/pull/50240)
* `dockerd-rootless-setuptool.sh`: Fix the script from silently returning with no error message when subuid/subgid system requirements are not satisfied. [moby/moby#50059](https://github.com/moby/moby/pull/50059)
* containerd image store: Fix `docker push` not creating a tag on the remote repository. [moby/moby#50199](https://github.com/moby/moby/pull/50199)
* containerd image store: Improve handling of errors returned by the token server during `docker pull/push`. [moby/moby#50176](https://github.com/moby/moby/pull/50176)

### [Packaging updates](#packaging-updates-6)

* Allow customizing containerd service name for OpenRC. [moby/moby#50156](https://github.com/moby/moby/pull/50156)
* Update BuildKit to [v0.23.1](https://github.com/moby/buildkit/releases/tag/v0.23.1). [moby/moby#50243](https://github.com/moby/moby/pull/50243)
* Update Buildx to [v0.25.0](https://github.com/docker/buildx/releases/tag/v0.25.0). [docker/docker-ce-packaging#1217](https://github.com/docker/docker-ce-packaging/pull/1217)
* Update Compose to [v2.37.2](https://github.com/docker/compose/releases/tag/v2.37.2). [docker/docker-ce-packaging#1219](https://github.com/docker/docker-ce-packaging/pull/1219)
* Update Docker Model CLI plugin to [v0.1.30](https://github.com/docker/model-cli/releases/tag/v0.1.30). [docker/docker-ce-packaging#1218](https://github.com/docker/docker-ce-packaging/pull/1218)
* Update Go runtime to [1.24.4](https://go.dev/doc/devel/release#go1.24.4). [docker/docker-ce-packaging#1213](https://github.com/docker/docker-ce-packaging/pull/1213), [moby/moby#50153](https://github.com/moby/moby/pull/50153), [docker/cli#6124](https://github.com/docker/cli/pull/6124)

### [Networking](#networking-2)

* Revert Swarm related changes added in 28.2.x builds, due to a regression reported in <https://github.com/moby/moby/issues/50129>. [moby/moby#50169](https://github.com/moby/moby/pull/50169)

  * Revert: Fix an issue where `docker network inspect --verbose` could sometimes crash the daemon ([https://github.com/moby/moby/pull/49937)](https://github.com/moby/moby/pull/49937%29).
  * Revert: Fix an issue where the load-balancer IP address for an overlay network would not be released in certain cases if the Swarm was lacking an ingress network ([https://github.com/moby/moby/pull/49948)](https://github.com/moby/moby/pull/49948%29).
  * Revert: Improve the reliability of NetworkDB in busy clusters and lossy networks ([https://github.com/moby/moby/pull/49932)](https://github.com/moby/moby/pull/49932%29).
  * Revert: Improvements to the reliability and convergence speed of NetworkDB ([https://github.com/moby/moby/pull/49939)](https://github.com/moby/moby/pull/49939%29).

* Fix an issue that could cause container startup to fail, or lead to failed UDP port mappings, when some container ports are mapped to `0.0.0.0` and others are mapped to specific host addresses. [moby/moby#50054](https://github.com/moby/moby/pull/50054)

* The `network inspect` response for an overlay network now reports that `EnableIPv4` is true. [moby/moby#50147](https://github.com/moby/moby/pull/50147)

* Windows: Improve daemon startup time in cases where the host has networks of type `"Mirrored"`. [moby/moby#50155](https://github.com/moby/moby/pull/50155)

* Windows: Make sure `docker system prune` and `docker network prune` only remove networks created by Docker. [moby/moby#50154](https://github.com/moby/moby/pull/50154)

### [API](#api-2)

* Update API version to 1.51. [moby/moby#50145](https://github.com/moby/moby/pull/50145)
* `GET /images/json` now sets the value of the `Containers` field for all images to the count of containers using the image. [moby/moby#50146](https://github.com/moby/moby/pull/50146)

### [Deprecations](#deprecations-4)

* Empty/nil image config fields in the `GET /images/{name}/json` response are now deprecated and will be removed in v29.0. [docker/cli#6129](https://github.com/docker/cli/pull/6129)
* api/types/container: deprecate `ExecOptions.Detach`. This field is not used, and will be removed in a future release. [moby/moby#50219](https://github.com/moby/moby/pull/50219)
* pkg/idtools: deprecate `IdentityMapping` and `Identity.Chown`. [moby/moby#50210](https://github.com/moby/moby/pull/50210)

## [28.2.2](#2822)

*2025-05-30*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.2.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.2.2)
* [moby/moby, 28.2.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.2.2)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-6)

* containerd image store: Fix a regression causing `docker build --push` to fail. This reverts [the fix](https://github.com/moby/moby/pull/49702) for `docker build` not persisting overridden images as dangling. [moby/moby#50105](https://github.com/moby/moby/pull/50105)

### [Networking](#networking-3)

* When creating the iptables `DOCKER-USER` chain, do not add an explicit `RETURN` rule, allowing users to append as well as insert their own rules. Existing rules are not removed on upgrade, but it won't be replaced after a reboot. [moby/moby#50098](https://github.com/moby/moby/pull/50098)

## [28.2.1](#2821)

*2025-05-29*

### [Packaging updates](#packaging-updates-7)

* Fix packaging regression in [v28.2.0](https://github.com/moby/moby/releases/tag/v28.2.0) which broke creating the `docker` group/user on fresh installations. [docker-ce-packaging#1209](https://github.com/docker/docker-ce-packaging/issues/1209)

## [28.2.0](#2820)

*2025-05-28*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.2.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.2.0)
* [moby/moby, 28.2.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.2.0)

> Note
>
> RHEL packages are currently not available and will be released later.

### [New](#new-2)

* Add `{{.Platform}}` as formatting option for `docker ps` to show the platform of the image the container is running. [docker/cli#6042](https://github.com/docker/cli/pull/6042)
* Add support for relative parent paths (`../`) on bind mount sources when using `docker run/create` with `-v/--volume` or `--mount type=bind` options. [docker/cli#4966](https://github.com/docker/cli/pull/4966)
* CDI is now enabled by default. [moby/moby#49963](https://github.com/moby/moby/pull/49963)
* Show discovered CDI devices in `docker info`. [docker/cli#6078](https://github.com/docker/cli/pull/6078)
* `docker image rm`: add `--platform` option to remove a variant from multi-platform images. [docker/cli#6109](https://github.com/docker/cli/pull/6109)
* containerd image store: Initial BuildKit support for building Windows container images on Windows (requires an opt-in with `DOCKER_BUILDKIT=1`). [moby/moby#49740](https://github.com/moby/moby/pull/49740)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-7)

* Add a new log option for fluentd log driver (`fluentd-write-timeout`), which enables specifying write timeouts for fluentd connections. [moby/moby#49911](https://github.com/moby/moby/pull/49911)
* Add support for `DOCKER_AUTH_CONFIG` for the experimental `--use-api-socket` option. [docker/cli#6019](https://github.com/docker/cli/pull/6019)
* Fix `docker exec` waiting for 10 seconds if a non-existing user or group was specified. [moby/moby#49868](https://github.com/moby/moby/pull/49868)
* Fix `docker swarm init` ignoring `cacert` option of `--external-ca`. [docker/cli#5995](https://github.com/docker/cli/pull/5995)
* Fix an issue where the CLI would not correctly save the configuration file (`~/.docker/config.json`) if it was a relative symbolic link. [docker/cli#5282](https://github.com/docker/cli/pull/5282)
* Fix containers with `--restart always` policy using CDI devices failing to start on daemon restart. [moby/moby#49990](https://github.com/moby/moby/pull/49990)
* Fix shell-completion to only complete some flags once, even though they can be set multiple times. [docker/cli#6030](https://github.com/docker/cli/pull/6030)
* Fix the `plugin does not implement PluginAddr interface` error for Swarm CSI drivers. [moby/moby#49961](https://github.com/moby/moby/pull/49961)
* Improve `docker login` error messages for invalid options. [docker/cli#6036](https://github.com/docker/cli/pull/6036)
* Make sure the terminal state is restored if the CLI is forcefully terminated. [docker/cli#6058](https://github.com/docker/cli/pull/6058)
* Update the default seccomp profile to match the libseccomp v2.6.0. The new syscalls are: `listmount`, `statmount`, `lsm_get_self_attr`, `lsm_list_modules`, `lsm_set_self_attr`, `mseal`, `uretprobe`, `riscv_hwprobe`, `getxattrat`, `listxattrat`, `removexattrat`, and `setxattrat`. This prevents containers from receiving EPERM errors when using them. [moby/moby#50077](https://github.com/moby/moby/pull/50077)
* `docker inspect`: add shell completion, improve flag-description for `--type` and improve validation. [docker/cli#6052](https://github.com/docker/cli/pull/6052)
* containerd image store: Enable BuildKit garbage collector by default. [moby/moby#49899](https://github.com/moby/moby/pull/49899)
* containerd image store: Fix `docker build` not persisting overridden images as dangling. [moby/moby#49702](https://github.com/moby/moby/pull/49702)
* containerd image store: Fix `docker system df` reporting a negative reclaimable space amount. [moby/moby#49707](https://github.com/moby/moby/pull/49707)
* containerd image store: Fix duplicate `PUT` requests when pushing a multi-platform image. [moby/moby#49949](https://github.com/moby/moby/pull/49949)

### [Packaging updates](#packaging-updates-8)

* Drop Ubuntu 20.04 "Focal" packages as it reached end of life. [docker/docker-ce-packaging#1200](https://github.com/docker/docker-ce-packaging/pull/1200)
* Fix install location for RPM-based `docker-ce` man-pages. [docker/docker-ce-packaging#1203](https://github.com/docker/docker-ce-packaging/pull/1203)
* Update BuildKit to [v0.22.0](https://github.com/moby/buildkit/releases/tag/v0.22.0). [moby/moby#50046](https://github.com/moby/moby/pull/50046)
* Update Buildx to [v0.24.0](https://github.com/docker/buildx/releases/tag/v0.24.0). [docker/docker-ce-packaging#1205](https://github.com/docker/docker-ce-packaging/pull/1205)
* Update Compose to [v2.36.2](https://github.com/docker/compose/releases/tag/v2.36.2). [docker/docker-ce-packaging#1208](https://github.com/docker/docker-ce-packaging/pull/1208)
* Update Go runtime to [1.24.3](https://go.dev/doc/devel/release#go1.24.3). [docker/docker-ce-packaging#1192](https://github.com/docker/docker-ce-packaging/pull/1192), [docker/cli#6060](https://github.com/docker/cli/pull/6060), [moby/moby#49174](https://github.com/moby/moby/pull/49174)

### [Networking](#networking-4)

* Add bridge network option `"com.docker.network.bridge.trusted_host_interfaces"`, accepting a colon-separated list of interface names. These interfaces have direct access to published ports on container IP addresses. [moby/moby#49832](https://github.com/moby/moby/pull/49832)
* Add daemon option `"allow-direct-routing"` to disable filtering of packets from outside the host addressed directly to containers. [moby/moby#49832](https://github.com/moby/moby/pull/49832)
* Do not display network options `com.docker.network.enable_ipv4` or `com.docker.network.enable_ipv6` in inspect output if they have been overridden by `EnableIPv4` or `EnableIPv6` in the network create request. [moby/moby#49866](https://github.com/moby/moby/pull/49866)
* Fix an issue that could cause network deletion to fail after a daemon restart, with error "has active endpoints" listing empty endpoint names. [moby/moby#49901](https://github.com/moby/moby/pull/49901)
* Fix an issue where `docker network inspect --verbose` could sometimes crash the daemon. [moby/moby#49937](https://github.com/moby/moby/pull/49937)
* Fix an issue where the load-balancer IP address for an overlay network would not be released in certain cases if the Swarm was lacking an ingress network. [moby/moby#49948](https://github.com/moby/moby/pull/49948)
* Improve the reliability of NetworkDB in busy clusters and lossy networks. [moby/moby#49932](https://github.com/moby/moby/pull/49932)
* Improvements to the reliability and convergence speed of NetworkDB. [moby/moby#49939](https://github.com/moby/moby/pull/49939)

### [API](#api-3)

* `DELETE /images/{name}` now supports a `platforms` query parameter. It accepts an array of JSON-encoded OCI Platform objects, allowing for selecting a specific platforms to delete content for. [moby/moby#49982](https://github.com/moby/moby/pull/49982)
* `GET /info` now includes a `DiscoveredDevices` field. This is an array of `DeviceInfo` objects, each providing details about a device discovered by a device driver. [moby/moby#49980](https://github.com/moby/moby/pull/49980)

### [Go SDK](#go-sdk-2)

* `api/types/container`: add `ContainerState` and constants for container state. [moby/moby#49965](https://github.com/moby/moby/pull/49965)
* `api/types/container`: change `Summary.State` to a `ContainerState`. [moby/moby#49991](https://github.com/moby/moby/pull/49991)
* `api/types/container`: define `HealthStatus` type for health-status constants. [moby/moby#49876](https://github.com/moby/moby/pull/49876)
* `api/types`: deprecate `BuildResult`, `ImageBuildOptions`, `ImageBuildOutput`, `ImageBuildResponse`, `BuilderVersion`, `BuilderV1`, and `BuilderBuildKi` which were moved to `api/types/build`. [moby/moby#50025](https://github.com/moby/moby/pull/50025)

### [Deprecations](#deprecations-5)

* API: Deprecated: `GET /images/{name}/json` no longer returns the following fields: `Config`, `Hostname`, `Domainname`, `AttachStdin`, `AttachStdout`, `AttachStderr`, `Tty`, `OpenStdin`, `StdinOnce`, `Image`, `NetworkDisabled` (already omitted unless set), `MacAddress` (already omitted unless set), `StopTimeout` (already omitted unless set). These additional fields were included in the response due to an implementation detail but not part of the image's Configuration, were marked deprecated in API v1.46, and are now omitted. [moby/moby#48457](https://github.com/moby/moby/pull/48457)
* Go-SDK: Deprecate builder/remotecontext.Rel(). This function was needed on older versions of Go, but can now be replaced by `filepath.Rel()`. [moby/moby#49843](https://github.com/moby/moby/pull/49843)
* Go-SDK: api/types: deprecate `BuildCachePruneOptions` in favor of `api/types/builder.CachePruneOptions`. [moby/moby#50015](https://github.com/moby/moby/pull/50015)
* Go-SDK: api/types: deprecate `BuildCachePruneReport` in favor of `api/types/builder.CachePruneReport`. [moby/moby#50015](https://github.com/moby/moby/pull/50015)
* Go-SDK: api/types: deprecate `NodeListOptions`, `NodeRemoveOptions`, `ServiceCreateOptions`, `ServiceUpdateOptions`, `RegistryAuthFromSpec`, `RegistryAuthFromPreviousSpec`, `ServiceListOptions`, `ServiceInspectOptions`, and `SwarmUnlockKeyResponse` which were moved to `api/types/swarm`. [moby/moby#50027](https://github.com/moby/moby/pull/50027)
* Go-SDK: api/types: deprecate `SecretCreateResponse`, `SecretListOptions`, `ConfigCreateResponse`, `ConfigListOptions` which were moved to api/types/swarm. [moby/moby#50024](https://github.com/moby/moby/pull/50024)
* Go-SDK: client: deprecate `IsErrNotFound`. [moby/moby#50012](https://github.com/moby/moby/pull/50012)
* Go-SDK: container: deprecate `IsValidHealthString` in favor of `api/types/container.ValidateHealthStatus`. [moby/moby#49893](https://github.com/moby/moby/pull/49893)
* Go-SDK: container: deprecate `StateStatus`, `WaitCondition`, and the related `WaitConditionNotRunning`, `WaitConditionNextExit`, and `WaitConditionRemoved` consts in favor of their equivalents in `api/types/container`. [moby/moby#49874](https://github.com/moby/moby/pull/49874)
* Go-SDK: opts: deprecate `ListOpts.GetAll` in favor of `ListOpts.GetSlice`. [docker/cli#6032](https://github.com/docker/cli/pull/6032)
* Remove deprecated `IsAutomated` formatting placeholder from `docker search`. [docker/cli#6091](https://github.com/docker/cli/pull/6091)
* Remove fallback for pulling images from non-OCI-compliant `docker.pkg.github.com` registry. [moby/moby#50094](https://github.com/moby/moby/pull/50094)
* Remove support for pulling legacy v2, schema 1 images and remove `DOCKER_ENABLE_DEPRECATED_PULL_SCHEMA_1_IMAGE` environment-variable. [moby/moby#50036](https://github.com/moby/moby/pull/50036), [moby/moby#42300](https://github.com/moby/moby/pull/42300)
* The `BridgeNfIptables` and `BridgeNfIp6tables` fields in the `GET /info` response were deprecated in API v1.48, and are now omitted in API v1.50. [moby/moby#49904](https://github.com/moby/moby/pull/49904)
* errdefs: Deprecate `errdefs.FromStatusCode`. Use containerd's `errhttp.ToNative` instead. [moby/moby#50030](https://github.com/moby/moby/pull/50030)

## [28.1.1](#2811)

*2025-04-18*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.1.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.1.1)
* [moby/moby, 28.1.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.1.1)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-8)

* Fix `dockerd-rootless-setuptool.sh` incorrectly reporting missing `iptables`. [moby/moby#49833](https://github.com/moby/moby/pull/49833)
* containerd image store: Fix a potential daemon crash when using `docker load` with archives containing zero-size tar headers. [moby/moby#49837](https://github.com/moby/moby/pull/49837)

### [Packaging updates](#packaging-updates-9)

* Update Buildx to [v0.23.0](https://github.com/docker/buildx/releases/tag/v0.23.0). [docker/docker-ce-packaging#1185](https://github.com/docker/docker-ce-packaging/pull/1185)
* Update Compose to [v2.35.1](https://github.com/docker/compose/releases/tag/v2.35.1). [docker/docker-ce-packaging#1188](https://github.com/docker/docker-ce-packaging/pull/1188)

### [Networking](#networking-5)

* Add a warning to a container's `/etc/resolv.conf` when no upstream DNS servers were found. [moby/moby#49827](https://github.com/moby/moby/pull/49827)

## [28.1.0](#2810)

*2025-04-17*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.1.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.1.0)
* [moby/moby, 28.1.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.1.0)

### [New](#new-3)

* Add `docker bake` sub-command as alias for `docker buildx bake`. [docker/cli#5947](https://github.com/docker/cli/pull/5947)
* Experimental: add a new `--use-api-socket` flag on `docker run` and `docker create` to enable access to Docker socket from inside a container and to share credentials from the host with the container. [docker/cli#5858](https://github.com/docker/cli/pull/5858)
* `docker image inspect` now supports a `--platform` flag to inspect a specific platform of a multi-platform image. [docker/cli#5934](https://github.com/docker/cli/pull/5934)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-9)

* Add CLI shell-completion for context names. [docker/cli#6016](https://github.com/docker/cli/pull/6016)
* Fix `docker images --tree` not including non-container images content size in the total image content size. [docker/cli#6000](https://github.com/docker/cli/pull/6000)
* Fix `docker load` not preserving replaced images. [moby/moby#49650](https://github.com/moby/moby/pull/49650)
* Fix `docker login` hints when logging in to a custom registry. [docker/cli#6015](https://github.com/docker/cli/pull/6015)
* Fix `docker stats` not working properly on machines with high CPU core count. [moby/moby#49734](https://github.com/moby/moby/pull/49734)
* Fix a regression causing `docker pull/push` to fail when interacting with a private repository. [docker/cli#5964](https://github.com/docker/cli/pull/5964)
* Fix an issue preventing rootless Docker setup on a host with no `ip_tables` kernel module. [moby/moby#49727](https://github.com/moby/moby/pull/49727)
* Fix an issue that could lead to unwanted iptables rules being restored and never deleted following a firewalld reload. [moby/moby#49728](https://github.com/moby/moby/pull/49728)
* Improve CLI completion of `docker service scale`. [docker/cli#5968](https://github.com/docker/cli/pull/5968)
* `docker images --tree` now hides both untagged and dangling images by default. [docker/cli#5924](https://github.com/docker/cli/pull/5924)
* `docker system info` will provide an exit code if a connection cannot be established to the Docker daemon. [docker/cli#5918](https://github.com/docker/cli/pull/5918)
* containerd image store: Fix `image tag` event not being emitted when building with BuildKit. [moby/moby#49678](https://github.com/moby/moby/pull/49678)
* containerd image store: Improve `docker push/pull` handling of remote registry errors. [moby/moby#49770](https://github.com/moby/moby/pull/49770)
* containerd image store: Show pull progress for non-layer image blobs. [moby/moby#49746](https://github.com/moby/moby/pull/49746)

### [Packaging updates](#packaging-updates-10)

* Add Debian "Trixie" packages. [docker/docker-ce-packaging#1181](https://github.com/docker/docker-ce-packaging/pull/1181)
* Add Fedora 42 packages. [docker/containerd-packaging#418](https://github.com/docker/containerd-packaging/pull/418), [docker/docker-ce-packaging#1169](https://github.com/docker/docker-ce-packaging/pull/1169)
* Add Ubuntu 25.04 "Plucky Puffin" packages. [docker/containerd-packaging#419](https://github.com/docker/containerd-packaging/pull/419), [docker/docker-ce-packaging#1177](https://github.com/docker/docker-ce-packaging/pull/1177)
* Update BuildKit to [v0.21.0](https://github.com/moby/buildkit/releases/tag/v0.21.0). [moby/moby#49809](https://github.com/moby/moby/pull/49809)
* Update Compose to [v2.35.0](https://github.com/docker/compose/releases/tag/v2.35.0). [docker/docker-ce-packaging#1183](https://github.com/docker/docker-ce-packaging/pull/1183)
* Update Go runtime to [1.23.8](https://go.dev/doc/devel/release#go1.23.8). [docker/cli#5986](https://github.com/docker/cli/pull/5986), [docker/docker-ce-packaging#1180](https://github.com/docker/docker-ce-packaging/pull/1180), [moby/moby#49737](https://github.com/moby/moby/pull/49737)

### [Networking](#networking-6)

* Fix a bug causing host port-mappings on Swarm containers to be duplicated on `docker ps` and `docker inspect`. [moby/moby#49724](https://github.com/moby/moby/pull/49724)
* Fix an issue that caused container network attachment to fail with error "Bridge port not forwarding". [moby/moby#49705](https://github.com/moby/moby/pull/49705)
* Fix an issue with removal of a `--link` from a container in the default bridge network. [moby/moby#49778](https://github.com/moby/moby/pull/49778)
* Improve how network-endpoint relationships are tracked to reduce the chance of the "has active endpoints" error to be wrongfully returned. [moby/moby#49736](https://github.com/moby/moby/pull/49736)
* Improve the "has active endpoints" error message by including the name of endpoints still connected to the network being deleted. [moby/moby#49773](https://github.com/moby/moby/pull/49773)

### [API](#api-4)

* Update API version to [v1.49](https://docs.docker.com/engine/api/v1.49/). [moby/moby#49718](https://github.com/moby/moby/pull/49718)
* `GET /image/{name}/json` now supports a `platform` parameter allowing to specify which platform variant of a multi-platform image to inspect. [moby/moby#49586](https://github.com/moby/moby/pull/49586)
* `GET /info` now returns a `FirewallBackend` containing information about the daemon's firewalling configuration. [moby/moby#49761](https://github.com/moby/moby/pull/49761)

### [Go SDK](#go-sdk-3)

* Update minimum required Go version to go1.23. [docker/cli#5868](https://github.com/docker/cli/pull/5868)
* cli/command/context: remove temporary `ContextType` field from JSON output. [docker/cli#5981](https://github.com/docker/cli/pull/5981)
* client: Keep image references in canonical format where possible. [moby/moby#49609](https://github.com/moby/moby/pull/49609)

### [Deprecations](#deprecations-6)

* API: Deprecated `AllowNondistributableArtifactsCIDRs` and `AllowNondistributableArtifactsHostnames` fields in the `RegistryConfig` struct in the `GET /info` response are omitted in API v1.49. [moby/moby#49749](https://github.com/moby/moby/pull/49749)
* API: Deprecated: The `ContainerdCommit.Expected`, `RuncCommit.Expected`, and `InitCommit.Expected` fields in the `GET /info` endpoint were deprecated in API v1.48, and are now omitted in API v1.49. [moby/moby#48556](https://github.com/moby/moby/pull/48556)
* Go-SDK: cli/command/image: Deprecate `RunPull`: this function was only used internally and will be removed in the next release. [docker/cli#5975](https://github.com/docker/cli/pull/5975)
* Go-SDK: cli/config/configfile: deprecate `ConfigFile.Experimental` field. Experimental CLI features are always enabled since version v20.10 and this field is no longer used. Use `ConfigFile.Features` instead for optional features. This field will be removed in a future release. [docker/cli#5977](https://github.com/docker/cli/pull/5977)
* Go-SDK: deprecate `pkg/archive`, which was migrated to `github.com/moby/go-archive`. [moby/moby#49743](https://github.com/moby/moby/pull/49743)
* Go-SDK: deprecate `pkg/atomicwriter`, which was migrated to `github.com/moby/sys/atomicwriter`. [moby/moby#49748](https://github.com/moby/moby/pull/49748)
* Go-SDK: opts: remove deprecated `PortOpt`, `ConfigOpt`, `SecretOpt` aliases. [docker/cli#5953](https://github.com/docker/cli/pull/5953)
* Go-SDK: registry: deprecate `APIEndpoint.Official` field. [moby/moby#49706](https://github.com/moby/moby/pull/49706)

## [28.0.4](#2804)

*2025-03-25*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.0.4 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.0.4)
* [moby/moby, 28.0.4 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.0.4)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-10)

* Fix a regression causing `docker pull/push` to fail when interacting with a private repository. [docker/cli#5964](https://github.com/docker/cli/pull/5964)

## [28.0.3](#2803)

*2025-03-25*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.0.3 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.0.3)
* [moby/moby, 28.0.3 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.0.3)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-11)

* Fix `docker run` truncating the `STDOUT`/`STDERR` prematurely when the container exits before the data is consumed. [docker/cli#5957](https://github.com/docker/cli/pull/5957)

### [Packaging updates](#packaging-updates-11)

* Update BuildKit to [v0.20.2](https://github.com/moby/buildkit/releases/tag/v0.20.2). [moby/moby#49698](https://github.com/moby/moby/pull/49698)
* Update `runc` to [v1.2.6](https://github.com/opencontainers/runc/releases/tag/v1.2.6). [moby/moby#49682](https://github.com/moby/moby/pull/49682)
* Update containerd to [v1.7.26](https://github.com/containerd/containerd/releases/tag/v1.7.26). [docker/containerd-packaging#409](https://github.com/docker/containerd-packaging/pull/409)

## [28.0.2](#2802)

*2025-03-19*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.0.2 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.0.2)
* [moby/moby, 28.0.2 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.0.2)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-12)

* Fix CLI-specific attributes (`docker.cli.*`) being unintentionally passed to downstream OTel services. [docker/cli#5842](https://github.com/docker/cli/pull/5842)
* Fix an issue where user-specified `OTEL_RESOURCE_ATTRIBUTES` were being overridden by CLI's internal telemetry attributes. The CLI now properly merges user-specified attributes with internal ones, allowing both to coexist. [docker/cli#5842](https://github.com/docker/cli/pull/5842)
* Fix the daemon failing to start on Windows when a container created before v28.0.0 was present. [moby/moby#49626](https://github.com/moby/moby/pull/49626)
* Fix possible error on `docker buildx prune` with `--min-free-space`. [moby/moby#49623](https://github.com/moby/moby/pull/49623)
* Fix spurious `io: read/write on closed pipe` error in the daemon log when closing a container. [moby/moby#49590](https://github.com/moby/moby/pull/49590)
* Fix the Docker daemon failing too early if the containerd socket isn't immediately available. [moby/moby#49603](https://github.com/moby/moby/pull/49603)
* Mask Linux thermal interrupt info in a container's `/proc` and `/sys` by default. [moby/moby#49560](https://github.com/moby/moby/pull/49560)
* Update `contrib/check-config.sh` to check for more kernel modules related to iptables. [moby/moby#49622](https://github.com/moby/moby/pull/49622)
* containerd image store: Fix integer overflow in User ID handling passed via `--user`. [moby/moby#49652](https://github.com/moby/moby/pull/49652)
* containerd image store: Fix spurious `reference for unknown type: application/vnd.in-toto+json` warning being logged to the daemon's log. [moby/moby#49652](https://github.com/moby/moby/pull/49652)
* containerd image store: Improve performance of `docker ps` when running a large number of containers. [moby/moby#49365](https://github.com/moby/moby/pull/49365)

### [Packaging updates](#packaging-updates-12)

* Update BuildKit to [v0.20.1](https://github.com/moby/buildkit/releases/tag/v0.20.1). [moby/moby#49587](https://github.com/moby/moby/pull/49587)
* Update Buildx to [v0.22.0](https://github.com/docker/buildx/releases/tag/v0.22.0). [docker/docker-ce-packaging#1175](https://github.com/docker/docker-ce-packaging/pull/1175)
* Update Compose to [v2.34.0](https://github.com/docker/compose/releases/tag/v2.34.0). [docker/docker-ce-packaging#1172](https://github.com/docker/docker-ce-packaging/pull/1172)
* Update Go runtime to [1.23.7](https://go.dev/doc/devel/release#go1.23.7). [docker/cli#5890](https://github.com/docker/cli/pull/5890), [docker/docker-ce-packaging#1171](https://github.com/docker/docker-ce-packaging/pull/1171), [moby/moby#49580](https://github.com/moby/moby/pull/49580)
* Update RootlessKit to [v2.3.4](https://github.com/rootless-containers/rootlesskit/releases/tag/v2.3.4). [moby/moby#49614](https://github.com/moby/moby/pull/49614)
* Update containerd (static binaries only) to [v1.7.27](https://www.github.com/containerd/containerd/releases/tag/v1.7.27). [moby/moby#49656](https://github.com/moby/moby/pull/49656)

### [Networking](#networking-7)

* Add the environment variable `DOCKER_INSECURE_NO_IPTABLES_RAW=1` to allow Docker to run on systems where the Linux kernel can't provide `CONFIG_IP_NF_RAW` support. When enabled, Docker will not create rules in the iptables `raw` table. Warning: This is not recommended for production environments as it reduces security by allowing other hosts on the local network to route to ports published to host addresses, even when they are published to `127.0.0.1.` This option bypasses some of the security hardening introduced in Docker Engine 28.0.0. [moby/moby#49621](https://github.com/moby/moby/pull/49621)
* Allow container startup when an endpoint is attached to a macvlan network driver where the parent interface is down. [moby/moby#49630](https://github.com/moby/moby/pull/49630)
* Do not skip DNAT for packets originating in a `gateway_mode=routed` network. [moby/moby#49577](https://github.com/moby/moby/pull/49577)
* Fix a bug causing `docker ps` to inconsistently report dual-stack port mappings. [moby/moby#49657](https://github.com/moby/moby/pull/49657)
* Fix a bug that could cause `docker-proxy` to stop forwarding UDP datagrams to containers. [moby/moby#49649](https://github.com/moby/moby/pull/49649)
* Fix a bug that was causing `docker-proxy` to close UDP connections to containers eagerly and resulting in the source address to change needlessly. [moby/moby#49649](https://github.com/moby/moby/pull/49649)

### [Go SDK](#go-sdk-4)

* Move various types and consts from `cli-plugins/manager` to a separate package. [docker/cli#5902](https://github.com/docker/cli/pull/5902)
* Update minimum required Go version to go1.23. [moby/moby#49541](https://github.com/moby/moby/pull/49541)
* `cli/command`: Move `PrettyPrint` utility to `cli/command/formatter`. [docker/cli#5916](https://github.com/docker/cli/pull/5916)
* runconfig/errors: split `ErrConflictHostNetwork` into `ErrConflictConnectToHostNetwork` and `ErrConflictDisconnectFromHostNetwork`. [moby/moby#49605](https://github.com/moby/moby/pull/49605)

### [Deprecations](#deprecations-7)

* Go-SDK: Deprecate `cli-plugins/manager.ResourceAttributesEnvvar` constant. It was used internally, but holds the `OTEL_RESOURCE_ATTRIBUTES` name, which is part of the OpenTelemetry specification. Users of this constant should define their own. It will be removed in the next release. [docker/cli#5881](https://github.com/docker/cli/pull/5881)
* Go-SDK: Deprecate `opts.PortOpt`, `opts.ConfigOpt` and `opts.SecretOpt`. These types were moved to the `opts/swarmopts` package. [docker/cli#5907](https://github.com/docker/cli/pull/5907)
* Go-SDK: Remove `service/logs` package. [docker/cli#5910](https://github.com/docker/cli/pull/5910)
* Go-SDK: `cli/command/image`: Deprecate `PushTrustedReference` and move to `cli/trust`. [docker/cli#5894](https://github.com/docker/cli/pull/5894)
* Go-SDK: `cli/command/image`: Deprecate and internalize `TrustedPush`. [docker/cli#5894](https://github.com/docker/cli/pull/5894)
* Go-SDK: `cli/command`: deprecate `Cli.NotaryClient`: use [`trust.GetNotaryRepository`](https://pkg.go.dev/github.com/docker/cli@v28.0.1+incompatible/cli/trust#GetNotaryRepository) instead. This method is no longer used and will be removed in the next release. [docker/cli#5885](https://github.com/docker/cli/pull/5885)
* Go-SDK: `cli/command`: deprecate `Cli.RegistryClient`. This method was only used internally and will be removed in the next release. Use [`client.NewRegistryClient`](https://pkg.go.dev/github.com/docker/cli@v28.0.1+incompatible/cli/registry/client#NewRegistryClient) instead. [docker/cli#5889](https://github.com/docker/cli/pull/5889), [docker/cli#5889](https://github.com/docker/cli/pull/5889)
* Go-SDK: `registry`: Deprecate `RepositoryInfo.Official` field. [moby/moby#49567](https://github.com/moby/moby/pull/49567)
* Go-SDK: `registry`: deprecate `HostCertsDir`: this function was only used internally and will be removed in the next release. [moby/moby#49612](https://github.com/moby/moby/pull/49612)
* Go-SDK: `registry`: deprecate `SetCertsDir`: the cert-directory is now automatically selected when running with RootlessKit, and should no longer be set manually. [moby/moby#49612](https://github.com/moby/moby/pull/49612)

## [28.0.1](#2801)

*2025-02-26*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.0.1 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.0.1)
* [moby/moby, 28.0.1 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.0.1)

### [Networking](#networking-8)

* Remove dependency on kernel modules `ip_set`, `ip_set_hash_net` and `netfilter_xt_set`.
  * The dependency was introduced in release 28.0.0 but proved too disruptive. The iptables rules using these modules have been replaced. [moby/moby#49530](https://github.com/moby/moby/pull/49530)
* Allow daemon startup on a host with IPv6 disabled without requiring `--ip6tables=false`. [moby/moby#49525](https://github.com/moby/moby/pull/49525)
* Fix a bug that was causing containers with `--restart=always` and a published port already in use to restart in a tight loop. [moby/moby#49507](https://github.com/moby/moby/pull/49507)
* Fix an issue with Swarm ingress, caused by incorrect ordering of iptables rules. [moby/moby#49538](https://github.com/moby/moby/pull/49538)
* Fix creation of a swarm-scoped network from a `--config-only` network. [moby/moby#49521](https://github.com/moby/moby/pull/49521)
* Fix `docker network inspect` reporting an IPv6 gateway with CIDR suffix for a newly created network with no specific IPAM config, until a daemon restart. [moby/moby#49520](https://github.com/moby/moby/pull/49520)
* Improve the error reported when kernel modules `ip_set`, `ip_set_hash_net` and `netilter_xt_set` are not available. [moby/moby#49524](https://github.com/moby/moby/pull/49524)
* Move most of Docker's iptables rules out of the filter-FORWARD chain, so that other applications are free to append rules that must follow Docker's rules. [moby/moby#49518](https://github.com/moby/moby/pull/49518)
* Update `--help` output and man page lo state which options only apply to the default bridge network. [moby/moby#49522](https://github.com/moby/moby/pull/49522)

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-13)

* Fix `docker context create` always returning an error when using the `"skip-tls-verify"` option. [docker/cli#5850](https://github.com/docker/cli/pull/5850)
* Fix shell completion suggesting IDs instead of names for services and nodes. [docker/cli#5848](https://github.com/docker/cli/pull/5848)
* Fix unintentionally printing exit status to standard error output when `docker exec/run` returns a non-zero status. [docker/cli#5854](https://github.com/docker/cli/pull/5854)
* Fix regression `protocol "tcp" is not supported by the RootlessKit port driver "slirp4netns"`. [moby/moby#49514](https://github.com/moby/moby/pull/49514)
* containerd image store: Fix `docker inspect` not being able to show multi-platform images with missing layers for all platforms. [moby/moby#49533](https://github.com/moby/moby/pull/49533)
* containerd image store: Fix `docker images --tree` reporting wrong content size. [moby/moby#49535](https://github.com/moby/moby/pull/49535)
* Fix compilation on i386 [moby/moby#49526](https://github.com/moby/moby/pull/49526)

### [Packaging updates](#packaging-updates-13)

* Update `github.com/go-jose/go-jose/v4` to v4.0.5 to address [GHSA-c6gw-w398-hv78](https://github.com/go-jose/go-jose/security/advisories/GHSA-c6gw-w398-hv78) / [CVE-2025-27144](https://www.cve.org/CVERecord?id=CVE-2025-27144). [docker/cli#5867](https://github.com/docker/cli/pull/5867)
* Update Buildx to [v0.21.1](https://github.com/docker/buildx/releases/tag/v0.21.1). [docker/docker-ce-packaging#1167](https://github.com/docker/docker-ce-packaging/pull/1167)
* Update Compose to [v2.33.1](https://github.com/docker/compose/releases/tag/v2.33.1). [docker/docker-ce-packaging#1168](https://github.com/docker/docker-ce-packaging/pull/1168)

### [API](#api-5)

* containerd image store: Fix `GET /images/json?manifests=1` not filling `Manifests` for index-only images [moby/moby#49533](https://github.com/moby/moby/pull/49533)
* containerd image store: Fix `GET /images/json and /images/<name>/json` `Size.Content` field including the size of content that's not available locally [moby/moby#49535](https://github.com/moby/moby/pull/49535)

## [28.0.0](#2800)

*2025-02-19*

For a full list of pull requests and changes in this release, refer to the relevant GitHub milestones:

* [docker/cli, 28.0.0 milestone](https://github.com/docker/cli/issues?q=is%3Aclosed+milestone%3A28.0.0)
* [moby/moby, 28.0.0 milestone](https://github.com/moby/moby/issues?q=is%3Aclosed+milestone%3A28.0.0)
* Deprecated and removed features, see [Deprecated Features](https://github.com/docker/cli/blob/v28.0.0/docs/deprecated.md).
* Changes to the Engine API, see [API version history](https://github.com/moby/moby/blob/v28.0.0/docs/api/version-history.md).

### [New](#new-4)

* Add ability to mount an image inside a container via `--mount type=image`. [moby/moby#48798](https://github.com/moby/moby/pull/48798)
  * You can also specify `--mount type=image,image-subpath=[subpath],...` option to mount a specific path from the image. [docker/cli#5755](https://github.com/docker/cli/pull/5755)
* `docker images --tree` now shows metadata badges [docker/cli#5744](https://github.com/docker/cli/pull/5744)
* `docker load`, `docker save`, and `docker history` now support a `--platform` flag allowing you to choose a specific platform for single-platform operations on multi-platform images. [docker/cli#5331](https://github.com/docker/cli/pull/5331)
* Add `OOMScoreAdj` to `docker service create` and `docker stack`. [docker/cli#5145](https://github.com/docker/cli/pull/5145)
* `docker buildx prune` now supports `reserved-space`, `max-used-space`, `min-free-space` and `keep-bytes` filters. [moby/moby#48720](https://github.com/moby/moby/pull/48720)
* Windows: Add support for running containerd as a child process of the daemon, instead of using a system-installed containerd. [moby/moby#47955](https://github.com/moby/moby/pull/47955)

### [Networking](#networking-9)

* The `docker-proxy` binary has been updated, older versions will not work with the updated `dockerd`. [moby/moby#48132](https://github.com/moby/moby/pull/48132)

  * Close a window in which the userland proxy (`docker-proxy`) could accept TCP connections, that would then fail after `iptables` NAT rules were set up.
  * The executable `rootlesskit-docker-proxy` is no longer used, it has been removed from the build and distribution.

* DNS nameservers read from the host's `/etc/resolv.conf` are now always accessed from the host's network namespace. [moby/moby#48290](https://github.com/moby/moby/pull/48290)
  * When the host's `/etc/resolv.conf` contains no nameservers and there are no `--dns` overrides, Google's DNS servers are no longer used, apart from by the default bridge network and in build containers.

* Container interfaces in bridge and macvlan networks now use randomly generated MAC addresses. [moby/moby#48808](https://github.com/moby/moby/pull/48808)

  * Gratuitous ARP / Neighbour Advertisement messages will be sent when the interfaces are started so that, when IP addresses are reused, they're associated with the newly generated MAC address.
  * IPv6 addresses in the default bridge network are now IPAM-assigned, rather than being derived from the MAC address.

* The deprecated OCI `prestart` hook is now only used by build containers. For other containers, network interfaces are added to the network namespace after task creation is complete, before the container task is started. [moby/moby#47406](https://github.com/moby/moby/pull/47406)

* Add a new `gw-priority` option to `docker run`, `docker container create`, and `docker network connect`. This option will be used by the Engine to determine which network provides the default gateway for a container. On `docker run`, this option is only available through the extended `--network` syntax. [docker/cli#5664](https://github.com/docker/cli/pull/5664)

* Add a new netlabel `com.docker.network.endpoint.ifname` to customize the interface name used when connecting a container to a network. It's supported by all built-in network drivers on Linux. [moby/moby#49155](https://github.com/moby/moby/pull/49155)

  * When a container is created with multiple networks specified, there's no guarantee on the order networks will be connected to the container. So, if a custom interface name uses the same prefix as the auto-generated names, for example `eth`, the container might fail to start.
  * The recommended practice is to use a different prefix, for example `en0`, or a numerical suffix high enough to never collide, for example `eth100`.
  * This label can be specified on `docker network connect` via the `--driver-opt` flag, for example `docker network connect --driver-opt=com.docker.network.endpoint.ifname=foobar …`.
  * Or via the long-form `--network` flag on `docker run`, for example `docker run --network=name=bridge,driver-opt=com.docker.network.endpoint.ifname=foobar …`

* If a custom network driver reports capability `GwAllocChecker` then, before a network is created, it will get a `GwAllocCheckerRequest` with the network's options. The custom driver may then reply that no gateway IP address should be allocated. [moby/moby#49372](https://github.com/moby/moby/pull/49372)

#### [Port publishing in bridge networks](#port-publishing-in-bridge-networks)

* `dockerd` now requires `ipset` support in the Linux kernel. [moby/moby#48596](https://github.com/moby/moby/pull/48596)

  * The `iptables` and `ip6tables` rules used to implement port publishing and network isolation have been extensively modified. This enables some of the following functional changes, and is a first step in refactoring to enable native `nftables` support in a future release. [moby/moby#48815](https://github.com/moby/moby/issues/48815)

  * If it becomes necessary to downgrade to an earlier version of the daemon, some manual cleanup of the new rules will be necessary. The simplest and surest approach is to reboot the host, or use `iptables -F` and `ip6tables -F` to flush all existing `iptables` rules from the `filter` table before starting the older version of the daemon. When that is not possible, run the following commands as root:

    * `iptables -D FORWARD -m set --match-set docker-ext-bridges-v4 dst -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT; ip6tables -D FORWARD -m set --match-set docker-ext-bridges-v6 dst -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT`
    * `iptables -D FORWARD -m set --match-set docker-ext-bridges-v4 dst -j DOCKER; ip6tables -D FORWARD -m set --match-set docker-ext-bridges-v6 dst -j DOCKER`
    * If you were previously running with the iptables filter-FORWARD policy set to `ACCEPT` and need to restore access to unpublished ports, also delete per-bridge-network rules from the `DOCKER` chains. For example, `iptables -D DOCKER ! -i docker0 -o docker0 -j DROP`.

* Fix a security issue that was allowing remote hosts to connect directly to a container on its published ports. [moby/moby#49325](https://github.com/moby/moby/pull/49325)

* Fix a security issue that was allowing neighbor hosts to connect to ports mapped on a loopback address. [moby/moby#49325](https://github.com/moby/moby/pull/49325)

* Fix an issue that prevented port publishing to link-local addresses. [moby/moby#48570](https://github.com/moby/moby/pull/48570)

* UDP ports published by a container are now reliably accessible by containers on other networks, via the host's public IP address. [moby/moby#48571](https://github.com/moby/moby/pull/48571)

* Docker will now only set the `ip6tables` policy for the `FORWARD` chain in the `filter` table to `DROP` if it enables IP forwarding on the host itself (sysctls `net.ipv6.conf.all.forwarding` and `net.ipv6.conf.default.forwarding`). This is now aligned with existing IPv4 behaviour. [moby/moby#48594](https://github.com/moby/moby/pull/48594)
  * If IPv6 forwarding is enabled on your host, but you were depending on Docker to set the ip6tables filter-FORWARD policy to `DROP`, you may need to update your host's configuration to make sure it is secure.

* Direct routed access to container ports that are not exposed using `p`/`-publish` is now blocked in the `DOCKER` iptables chain. [moby/moby#48724](https://github.com/moby/moby/pull/48724)

  * If the default iptables filter-FORWARD policy was previously left at `ACCEPT` on your host, and direct routed access to a container's unpublished ports from a remote host is still required, options are:

    * Publish the ports you need.
    * Use the new `gateway_mode_ipv[46]=nat-unprotected`, described below.

  * Container ports published to host addresses will continue to be accessible via those host addresses, using NAT or the userland proxy.

  * Unpublished container ports continue to be directly accessible from the Docker host via the container's IP address.

* Networks created with `gateway_mode_ipv[46]=routed` are now accessible from other bridge networks running on the same Docker host, as well as from outside the host. [moby/moby#48596](https://github.com/moby/moby/pull/48596)

* Bridge driver options `com.docker.network.bridge.gateway_mode_ipv4` and `com.docker.network.bridge.gateway_mode_ipv6` now accept mode `nat-unprotected`. [moby/moby#48597](https://github.com/moby/moby/pull/48597)
  * `nat-unprotected` is similar to the default `nat` mode, but no per port/protocol rules are set up. This means any port on a container can be accessed by direct-routing from a remote host.

* Bridge driver options `com.docker.network.bridge.gateway_mode_ipv4` and `com.docker.network.bridge.gateway_mode_ipv6` now accept mode `isolated`, when the network is also `internal`. [moby/moby#49262](https://github.com/moby/moby/pull/49262)

  * An address is normally assigned to the bridge device in an `internal` network. So, processes on the Docker host can access the network, and containers in the network can access host services listening on that bridge address (including services listening on "any" host address, `0.0.0.0` or `::`).
  * An `internal` bridge network created with gateway mode `isolated` does not have an address on the Docker host.

* When a port mapping includes a host IP address or port number that cannot be used because NAT from the host is disabled using `--gateway_mode_ipv[46]`, container creation will no longer fail. The unused fields may be needed if the gateway endpoint changes when networks are connected or disconnected. A message about the unused fields will be logged. [moby/moby#48575](https://github.com/moby/moby/pull/48575)

* Do not create iptables nat-POSTROUTING masquerade rules for a container's own published ports, when the userland proxy is enabled. [moby/moby#48854](https://github.com/moby/moby/pull/48854)

#### [IPv6](#ipv6)

* Add `docker network create` option `--ipv4`. To disable IPv4 address assignment for a network, use `docker network create --ipv4=false [...]`. [docker/cli#5599](https://github.com/docker/cli/pull/5599)

* Daemon option `--ipv6` (`"ipv6": true` in `daemon.json`) can now be used without `fixed-cidr-v6`. [moby/moby#48319](https://github.com/moby/moby/pull/48319)

* IPAM now handles subnets bigger than "/64". [moby/moby#49223](https://github.com/moby/moby/pull/49223)

* Duplicate address detection (DAD) is now disabled for addresses assigned to the bridges belonging to bridge networks. [moby/moby#48609](https://github.com/moby/moby/pull/48609)

* Modifications to `host-gateway`, for compatibility with IPv6-only networks. [moby/moby#48807](https://github.com/moby/moby/pull/48807)

  * When special value `host-gateway` is used in an `--add-host` option in place of an address, it's replaced by an address on the Docker host to make it possible to refer to the host by name. The address used belongs to the default bridge (normally `docker0`). Until now it's always been an IPv4 address, because all containers on bridge networks had IPv4 addresses.
  * Now, if IPv6 is enabled on the default bridge network, `/etc/hosts` entries will be created for IPv4 and IPv6 addresses. So, a container that's only connected to IPv6-only networks can access the host by name.
  * The `--host-gateway-ip` option overrides the address used to replace `host-gateway`. Two of these options are now allowed on the command line, for one IPv4 gateway and one IPv6.
  * In the `daemon.json` file, to provide two addresses, use `"host-gateway-ips"`. For example, `"host-gateway-ips": ["192.0.2.1", "2001:db8::1111"]`.

### [Bug fixes and enhancements](#bug-fixes-and-enhancements-14)

* Add IPv6 loopback address as an insecure registry by default. [moby/moby#48540](https://github.com/moby/moby/pull/48540)
* Add support for Cobra-generated completion scripts for `dockerd`. [moby/moby#49339](https://github.com/moby/moby/pull/49339)
* Fix DNS queries failing when containers are launched via `systemd` auto-start on boot [moby/moby#48812](https://github.com/moby/moby/pull/48812)
* Fix Docker Swarm mode ignoring `volume.subpath` [docker/cli#5833](https://github.com/docker/cli/pull/5833)
* Fix `docker export` continuing the export after the operation is canceled. [moby/moby#49265](https://github.com/moby/moby/pull/49265)
* Fix `docker export` not releasing the container's writable layer after a failure. [moby/moby#48517](https://github.com/moby/moby/pull/48517)
* Fix `docker images --tree` unnecessary truncating long image names when multiple names are available [docker/cli#5757](https://github.com/docker/cli/pull/5757)
* Fix a bug where a container with a name matching another container's ID is not restored on daemon startup. [moby/moby#48669](https://github.com/moby/moby/pull/48669)
* Fix an issue preventing some IPv6 addresses shown by `docker ps` to be properly bracketed [docker/cli#5468](https://github.com/docker/cli/pull/5468)
* Fix bug preventing image pulls from being cancelled during `docker run`. [docker/cli#5645](https://github.com/docker/cli/pull/5645)
* Fix error-handling when running the daemon as a Windows service to prevent unclean exits. [moby/moby#48518](https://github.com/moby/moby/pull/48518)
* Fix issue causing output of `docker run` to be inconsistent when using `--attach stdout` or `--attach stderr` versus `stdin`. `docker run --attach stdin` now exits if the container exits. [docker/cli#5662](https://github.com/docker/cli/pull/5662)
* Fix rootless Docker setup with `subid` backed by NSS modules. [moby/moby#49036](https://github.com/moby/moby/pull/49036)
* Generated completion scripts from the CLI now show descriptions next to each command/flag suggestion. [docker/cli#5756](https://github.com/docker/cli/pull/5756)
* IPv6 addresses shown by `docker ps` in port bindings are now bracketed [docker/cli#5363](https://github.com/docker/cli/pull/5363)
* Implement the ports validation method for Compose [docker/cli#5524](https://github.com/docker/cli/pull/5524)
* Improve error-output for invalid flags on the command line. [docker/cli#5233](https://github.com/docker/cli/pull/5233)
* Improve errors when failing to start a container using anther container's network namespace. [moby/moby#49367](https://github.com/moby/moby/pull/49367)
* Improve handling of invalid API errors that could result in an empty error message being shown. [moby/moby#49373](https://github.com/moby/moby/pull/49373)
* Improve output and consistency for unknown (sub)commands and invalid arguments [docker/cli#5234](https://github.com/docker/cli/pull/5234)
* Improve validation of `exec-opts` in daemon configuration. [moby/moby#48979](https://github.com/moby/moby/pull/48979)
* Update the handling of the `--gpus=0` flag to be consistent with the NVIDIA Container Runtime. [moby/moby#48482](https://github.com/moby/moby/pull/48482)
* `client.ContainerCreate` now normalizes `CapAdd` and `CapDrop` fields in `HostConfig` to their canonical form. [moby/moby#48551](https://github.com/moby/moby/pull/48551)
* `docker image save` now produces stable timestamps. [moby/moby#48611](https://github.com/moby/moby/pull/48611)
* `docker inspect` now lets you inspect Swarm configs [docker/cli#5573](https://github.com/docker/cli/pull/5573)
* containerd image store: Add support for `Extracting` layer status in `docker pull`. [moby/moby#49064](https://github.com/moby/moby/pull/49064)
* containerd image store: Fix `commit`, `import`, and `build` not preserving a replaced image as a dangling image. [moby/moby#48316](https://github.com/moby/moby/pull/48316)
* containerd image store: Make `docker load --platform` return an error when the requested platform isn't loaded. [moby/moby#48718](https://github.com/moby/moby/pull/48718)
* Fix validation of `--link` option. [docker/cli#5739](https://github.com/docker/cli/pull/5739)
* Add validation of network-diagnostic-port daemon configuration option. [moby/moby#49305](https://github.com/moby/moby/pull/49305)
* Unless explicitly configured, an IP address is no longer reserved for a gateway in cases where it is not required. Namely, “internal” bridge networks with option `com.docker.network.bridge.inhibit_ipv4`, `ipvlan` or `macvlan` networks with no parent interface, and L3 IPvlan modes. [moby/moby#49261](https://github.com/moby/moby/pull/49261)
* If a custom network driver reports capability `GwAllocChecker` then, before a network is created, it will get a `GwAllocCheckerRequest` with the network's options. The custom driver may then reply that no gateway IP address should be allocated. [moby/moby#49372](https://github.com/moby/moby/pull/49372)
* Fixed an issue that meant a container could not be attached to an L3 IPvlan at the same time as other network types. [moby/moby#49130](https://github.com/moby/moby/pull/49130)
* Remove the correct `/etc/hosts` entries when disconnecting a container from a network. [moby/moby#48857](https://github.com/moby/moby/pull/48857)
* Fix duplicate network disconnect events. [moby/moby#48800](https://github.com/moby/moby/pull/48800)
* Resolve issues related to changing `fixed-cidr` for `docker0`, and inferring configuration from a user-managed default bridge (`--bridge`). [moby/moby#48319](https://github.com/moby/moby/pull/48319)
* Remove feature flag `windows-dns-proxy`, introduced in release 26.1.0 to control forwarding to external DNS resolvers from Windows containers, to make `nslookup` work. It was enabled by default in release 27.0.0. [moby/moby#48738](https://github.com/moby/moby/pull/48738)
* Remove an `iptables` mangle rule for checksumming SCTP. The rule can be re-enabled by setting `DOCKER_IPTABLES_SCTP_CHECKSUM=1` in the daemon's environment. This override will be removed in a future release. [moby/moby#48149](https://github.com/moby/moby/pull/48149)
* Faster connection to bridge networks, in most cases. [moby/moby#49302](https://github.com/moby/moby/pull/49302)

### [Packaging updates](#packaging-updates-14)

* Update Go runtime to [1.23.6](https://go.dev/doc/devel/release#go1.23.6). [docker/cli#5795](https://github.com/docker/cli/pull/5795), [moby/moby#49393](https://github.com/moby/moby/pull/49393), [docker/docker-ce-packaging#1161](https://github.com/docker/docker-ce-packaging/pull/1161)
* Update `runc` to [v1.2.5](https://github.com/opencontainers/runc/releases/tag/v1.2.5) (static binaries only). [moby/moby#49464](https://github.com/moby/moby/pull/49464)
* Update containerd to [v1.7.25](https://github.com/containerd/containerd/releases/tag/v1.7.25). [moby/moby#49252](https://github.com/moby/moby/pull/49252)
* Update BuildKit to [v0.20.0](https://github.com/moby/buildkit/releases/tag/v0.20.0). [moby/moby#49495](https://github.com/moby/moby/pull/49495)
* Update Buildx to [v0.21.0](https://github.com/docker/buildx/releases/tag/v0.21.0). [docker/docker-ce-packaging#1166](https://github.com/docker/docker-ce-packaging/pull/1166)
* Update Compose to [v2.32.4](https://github.com/docker/compose/releases/tag/v2.32.3). [docker/docker-ce-packaging#1143](https://github.com/docker/docker-ce-packaging/pull/1143)
* The canonical source for the `dockerd(8)` man page has been moved back to the `moby/moby` repository itself. [moby/moby#48298](https://github.com/moby/moby/pull/48298)

### [Go SDK](#go-sdk-5)

* Improve validation of empty object IDs. The client now returns an "Invalid Parameter" error when trying to use an empty ID or name. This changes the error returned by some "Inspect" functions from a "Not found" error to an "Invalid Parameter". [moby/moby#49381](https://github.com/moby/moby/pull/49381)
* `Client.ImageBuild()` now omits default values from the API request's query string. [moby/moby#48651](https://github.com/moby/moby/pull/48651)
* `api/types/container`: Merge `Stats` and `StatsResponse` [moby/moby#49287](https://github.com/moby/moby/pull/49287)
* `client.WithVersion`: Strip v-prefix when setting API version [moby/moby#49352](https://github.com/moby/moby/pull/49352)
* `client`: Add `WithTraceOptions` allowing to specify custom OTe1 trace options. [moby/moby#49415](https://github.com/moby/moby/pull/49415)
* `client`: Add `HijackDialer` interface. [moby/moby#49388](https://github.com/moby/moby/pull/49388)
* `client`: Add `SwarmManagementAPIClient` interface to describe all API client methods related to Swarm-specific objects. [moby/moby#49388](https://github.com/moby/moby/pull/49388)
* `client`: Add `WithTraceOptions` allowing to specify custom OTel trace options. [moby/moby#49415](https://github.com/moby/moby/pull/49415)
* `client`: `ImageHistory`, `ImageLoad` and `ImageSave` now use variadic functional options [moby/moby#49466](https://github.com/moby/moby/pull/49466)
* `pkg/containerfs`: Move to internal [moby/moby#48097](https://github.com/moby/moby/pull/48097)
* `pkg/reexec`: Can now be used on platforms other than Linux, Windows, macOS and FreeBSD [moby/moby#49118](https://github.com/moby/moby/pull/49118)
* `api/types/container`: introduce `CommitResponse` type. This is currently an alias for `IDResponse`, but may become a distinct type in a future release. [moby/moby#49444](https://github.com/moby/moby/pull/49444)
* `api/types/container`: introduce `ExecCreateResponse` type. This is currently an alias for `IDResponse`, but may become a distinct type in a future release. [moby/moby#49444](https://github.com/moby/moby/pull/49444)

### [API](#api-6)

* Update API version to [v1.48](https://docs.docker.com/engine/api/v1.48/) [moby/moby#48476](https://github.com/moby/moby/pull/48476)

* `GET /images/{name}/json` response now returns the `Manifests` field containing information about the sub-manifests contained in the image index. This includes things like platform-specific manifests and build attestations. [moby/moby#48264](https://github.com/moby/moby/pull/48264)

* `POST /containers/create` now supports `Mount` of type `image` for mounting an image inside a container. [moby/moby#48798](https://github.com/moby/moby/pull/48798)

* `GET /images/{name}/history` now supports a `platform` parameter (JSON encoded OCI Platform type) that lets you specify a platform to show the history of. [moby/moby#48295](https://github.com/moby/moby/pull/48295)

* `POST /images/{name}/load` and `GET /images/{name}/get` now supports a `platform` parameter (JSON encoded OCI Platform type) that lets you specify a platform to load/save. Not passing this parameter results in loading/saving the full multi-platform image. [moby/moby#48295](https://github.com/moby/moby/pull/48295)

* Improve errors for invalid width/height on container resize and exec resize [moby/moby#48679](https://github.com/moby/moby/pull/48679)

* The `POST /containers/create` endpoint now includes a warning in the response when setting the container-wide `VolumeDriver` option in combination with volumes defined through `Mounts` because the `VolumeDriver` option has no effect on those volumes. This warning was previously generated by the CLI. [moby/moby#48789](https://github.com/moby/moby/pull/48789)

* containerd image store: `GET /images/json` and `GET /images/{name}/json` responses now includes `Descriptor` field, which contains an OCI descriptor of the image target. The new field is only populated if the daemon provides a multi-platform image store. [moby/moby#48894](https://github.com/moby/moby/pull/48894)

* containerd image store: `GET /containers/{name}/json` now returns an `ImageManifestDescriptor` field containing the OCI descriptor of the platform-specific image manifest of the image that was used to create the container. [moby/moby#48855](https://github.com/moby/moby/pull/48855)

* Add debug endpoints (`GET /debug/vars`, `GET /debug/pprof/`, `GET /debug/pprof/cmdline`, `GET /debug/pprof/profile`, `GET /debug/pprof/symbol`, `GET /debug/pprof/trace`, `GET /debug/pprof/{name}`) are now also accessible through the versioned-API paths (`/v<API-version>/<endpoint>`). [moby/moby#49051](https://github.com/moby/moby/pull/49051)

* Fix API returning a `500` status code instead of `400` for validation errors. [moby/moby#49217](https://github.com/moby/moby/pull/49217)

* Fix status codes for archive endpoints `HEAD /containers/{name:.*}/archive`, `GET /containers/{name:.*}/archive`, `PUT /containers/{name:.*}/archive` returning a `500` status instead of a `400` status. [moby/moby#49219](https://github.com/moby/moby/pull/49219)

* `POST /containers/create` now accepts a `writable-cgroups=true` option in `HostConfig.SecurityOpt` to mount the container's cgroups writable. This provides a more granular approach than `HostConfig.Privileged`. [moby/moby#48828](https://github.com/moby/moby/pull/48828)

* `POST /build/prune` renames `keep-bytes` to `reserved-space` and now supports additional prune parameters `max-used-space` and `min-free-space`. [moby/moby#48720](https://github.com/moby/moby/pull/48720)

* `POST /networks/create` now has an `EnableIPv4` field. Setting it to `false` disables IPv4 IPAM for the network. [moby/moby#48271](https://github.com/moby/moby/pull/48271)

  * `GET /networks/{id}` now returns an `EnableIPv4` field showing whether the network has IPv4 IPAM enabled. [moby/moby#48271](https://github.com/moby/moby/pull/48271)
  * User-defined bridge networks require either IPv4 or IPv6 address assignment to be enabled. IPv4 cannot be disabled for the default bridge network (`docker0`). [moby/moby#48323](https://github.com/moby/moby/pull/48323)
  * `macvlan` and `ipvlan` networks can be created with address assignment disabled for IPv4, IPv6, or both address families. [moby/moby#48299](https://github.com/moby/moby/pull/48299)
  * IPv4 cannot be disabled for Windows or Swarm networks. [moby/moby#48278](https://github.com/moby/moby/pull/48278)

* Add a way to specify which network should provide the default gateway for a container. [moby/moby#48936](https://github.com/moby/moby/pull/48936)

  * `POST /networks/{id}/connect` and `POST /containers/create` now accept a `GwPriority` field in `EndpointsConfig`. This value is used to determine which network endpoint provides the default gateway for the container. The endpoint with the highest priority is selected. If multiple endpoints have the same priority, endpoints are sorted lexicographically by their network name, and the one that sorts first is picked. [moby/moby#48746](https://github.com/moby/moby/pull/48746)
  * `GET /containers/json` now returns a `GwPriority` field in `NetworkSettings` for each network endpoint. The `GwPriority` field is used by the CLI’s new `gw-priority` option for `docker run` and `docker network connect`. [moby/moby#48746](https://github.com/moby/moby/pull/48746)

* Settings for `eth0` in `--sysctl` options are no longer automatically migrated to the network endpoint. [moby/moby#48746](https://github.com/moby/moby/pull/48746)
  * For example, in the Docker CLI, `docker run --network mynet --sysctl net.ipv4.conf.eth0.log_martians=1 ...` is rejected. Instead, you must use `docker run --network name=mynet,driver-opt=com.docker.network.endpoint.sysctls=net.ipv4.conf.IFNAME.log_martians=1 ...`

* `GET /containers/json` now returns an `ImageManifestDescriptor` field matching the same field in `/containers/{name}/json`. This field is only populated if the daemon provides a multi-platform image store. [moby/moby#49407](https://github.com/moby/moby/pull/49407)

### [Removed](#removed)

* The Fluent logger option `fluentd-async-connect` has been deprecated in v20.10 and is now removed. [moby/moby#46114](https://github.com/moby/moby/pull/46114)
* The `--time` option on `docker stop` and `docker restart` is deprecated and renamed to `--timeout`. [docker/cli#5485](https://github.com/docker/cli/pull/5485)
* Go-SDK: `pkg/ioutils`: Remove `NewReaderErrWrapper` as it was never used. [moby/moby#49258](https://github.com/moby/moby/pull/49258)
* Go-SDK: `pkg/ioutils`: Remove deprecated `BytesPipe`, `NewBytesPipe`, `ErrClosed`, `WriteCounter`, `NewWriteCounter`, `NewReaderErrWrapper`, `NopFlusher`. [moby/moby#49245](https://github.com/moby/moby/pull/49245)
* Go-SDK: `pkg/ioutils`: Remove deprecated `NopWriter` and `NopWriteCloser`. [moby/moby#49256](https://github.com/moby/moby/pull/49256)
* Go-SDK: `pkg/sysinfo`: Remove deprecated NumCPU. [moby/moby#49242](https://github.com/moby/moby/pull/49242)
* Go-SDK: Remove `pkg/broadcaster`, as it was only used internally [moby/moby#49172](https://github.com/moby/moby/pull/49172)
* Go-SDK: Remove deprecated `cli.Errors` type [docker/cli#5549](https://github.com/docker/cli/pull/5549)
* Remove `pkg/ioutils.ReadCloserWrapper`, as it was only used in tests. [moby/moby#49237](https://github.com/moby/moby/pull/49237)
* Remove deprecated `api-cors-header` config parameter and the `dockerd` `--api-cors-header` option [moby/moby#48209](https://github.com/moby/moby/pull/48209)
* Remove deprecated `APIEndpoint.Version` field, `APIVersion` type, and `APIVersion1` and `APIVersion2` consts. [moby/moby#49004](https://github.com/moby/moby/pull/49004)
* Remove deprecated `api-cors-header` config parameter and the Docker daemon's `--api-cors-header` option. [docker/cli#5437](https://github.com/docker/cli/pull/5437)
* Remove deprecated `pkg/directory` package [moby/moby#48779](https://github.com/moby/moby/pull/48779)
* Remove deprecated `pkg/dmsg.Dmesg()` [moby/moby#48109](https://github.com/moby/moby/pull/48109)
* Remove deprecated image/spec package, which was moved to a separate module (`github.com/moby/docker-image-spec`) [moby/moby#48460](https://github.com/moby/moby/pull/48460)
* Remove migration code and errors for the deprecated `logentries` logging driver. [moby/moby#48891](https://github.com/moby/moby/pull/48891)
* Remove support for deprecated external graph-driver plugins. [moby/moby#48072](https://github.com/moby/moby/pull/48072)
* `api/types`: Remove deprecated `container.ContainerNode` and `ContainerJSONBase.Node` field. [moby/moby#48107](https://github.com/moby/moby/pull/48107)
* `api/types`: Remove deprecated aliases: `ImagesPruneReport`, `VolumesPruneReport`, `NetworkCreateRequest`, `NetworkCreate`, `NetworkListOptions`, `NetworkCreateResponse`, `NetworkInspectOptions`, `NetworkConnect`, `NetworkDisconnect`, `EndpointResource`, `NetworkResource`, `NetworksPruneReport`, `ExecConfig`, `ExecStartCheck`, `ContainerExecInspect`, `ContainersPruneReport`, `ContainerPathStat`, `CopyToContainerOptions`, `ContainerStats`, `ImageSearchOptions`, `ImageImportSource`, `ImageLoadResponse`, `ContainerNode`. [moby/moby#48107](https://github.com/moby/moby/pull/48107)
* `libnetwork/iptables`: Remove deprecated `IPV`, `Iptables`, `IP6Tables` and `Passthrough()`. [moby/moby#49121](https://github.com/moby/moby/pull/49121)
* `pkg/archive`: Remove deprecated `CanonicalTarNameForPath`, `NewTempArchive`, `TempArchive` [moby/moby#48708](https://github.com/moby/moby/pull/48708)
* `pkg/fileutils`: Remove deprecated `GetTotalUsedFds` [moby/moby#49210](https://github.com/moby/moby/pull/49210)
* `pkg/ioutils`: Remove `OnEOFReader`, which was only used internally [moby/moby#49170](https://github.com/moby/moby/pull/49170)
* `pkg/longpath`: Remove deprecated `Prefix` constant. [moby/moby#48779](https://github.com/moby/moby/pull/48779)
* `pkg/stringid`: Remove deprecated `IsShortID` and `ValidateID` functions [moby/moby#48705](https://github.com/moby/moby/pull/48705)
* `runconfig/opts`: Remove deprecated `ConvertKVStringsToMap` [moby/moby#48102](https://github.com/moby/moby/pull/48102)
* `runconfig`: Remove deprecated `ContainerConfigWrapper`, `SetDefaultNetModeIfBlank`, `DefaultDaemonNetworkMode`, `IsPreDefinedNetwork` [moby/moby#48102](https://github.com/moby/moby/pull/48102)
* `container`: Remove deprecated `ErrNameReserved`, `ErrNameNotReserved`. [moby/moby#48728](https://github.com/moby/moby/pull/48728)
* Remove `Daemon.ContainerInspectCurrent()` method and change `Daemon.ContainerInspect()` signature to accept a `backend.ContainerInspectOptions` struct [moby/moby#48672](https://github.com/moby/moby/pull/48672)
* Remove deprecated `Daemon.Exists()` and `Daemon.IsPaused()` methods. [moby/moby#48723](https://github.com/moby/moby/pull/48723)

### [Deprecations](#deprecations-8)

* API: The `BridgeNfIptables` and `BridgeNfIp6tables` fields in the `GET /info` response are now always be `false` and will be omitted in API v1.49. The netfilter module is now loaded on-demand, and no longer during daemon startup, making these fields obsolete. [moby/moby#49114](https://github.com/moby/moby/pull/49114)

* API: The `error` and `progress` fields in streaming responses for endpoints that return a JSON progress response, such as `POST /images/create`, `POST /images/{name}/push`, and `POST /build` are deprecated. [moby/moby#49447](https://github.com/moby/moby/pull/49447)

  * Users should use the information in the `errorDetail` and `progressDetail` fields instead.
  * These fields were marked deprecated in API v1.4 (docker v0.6.0) and API v1.8 (docker v0.7.1) respectively, but still returned.
  * These fields will be left empty or will be omitted in a future API version.

* Deprecate `Daemon.Register()`. This function is unused and will be removed in the next release. [moby/moby#48702](https://github.com/moby/moby/pull/48702)

* Deprecate `client.ImageInspectWithRaw` function in favor of the new `client.ImageInspect`. [moby/moby#48264](https://github.com/moby/moby/pull/48264)

* Deprecate `daemon/config.Config.ValidatePlatformConfig()`. This method was used as helper for `config.Validate`, which should be used instead. [moby/moby#48985](https://github.com/moby/moby/pull/48985)

* Deprecate `pkg/reexec`. This package is deprecated and moved to a separate module. Use `github.com/moby/sys/reexec` instead. [moby/moby#49129](https://github.com/moby/moby/pull/49129)

* Deprecate configuration for pushing non-distributable artifacts [docker/cli#5724](https://github.com/docker/cli/pull/5724)

* Deprecate the `--allow-nondistributable-artifacts` daemon flag and corresponding `allow-nondistributable-artifacts` field in `daemon.json`. Setting either option will no longer take an effect, but a deprecation warning log is added. [moby/moby#49065](https://github.com/moby/moby/pull/49065)

* Deprecate the `RegistryConfig.AllowNondistributableArtifactsCIDRs` and `RegistryConfig.AllowNondistributableArtifactsHostnames` fields in the `GET /info` API response. For API version v1.48 and older, the fields are still included in the response, but always `null`. In API version v1.49 and later, the field will be omitted entirely. [moby/moby#49065](https://github.com/moby/moby/pull/49065)

* Go-SDK: Deprecate `registry.ServiceOptions.AllowNondistributableArtifacts` field. [moby/moby#49065](https://github.com/moby/moby/pull/49065)

* Go-SDK: The `BridgeNfIptables`, `BridgeNfIp6tables` fields in `api/types/system.Info` and `BridgeNFCallIPTablesDisabled`, `BridgeNFCallIP6TablesDisabled` fields in `pkg/sysinfo.SysInfo` are deprecated and will be removed in the next release. [moby/moby#49114](https://github.com/moby/moby/pull/49114)

* Go-SDK: `client`: Deprecate `CommonAPIClient` interface in favor of the `APIClient` interface. The `CommonAPIClient` will be changed to an alias for `APIClient` in the next release, and removed in the release after. [moby/moby#49388](https://github.com/moby/moby/pull/49388)

* Go-SDK: `client`: Deprecate `ErrorConnectionFailed` helper. This function was only used internally, and will be removed in the next release. [moby/moby#49389](https://github.com/moby/moby/pull/49389)

* Go-SDK: `pkg/ioutils`: Deprecate `NewAtomicFileWriter`, `AtomicWriteFile`, `AtomicWriteSet`, `NewAtomicWriteSet` in favor of `pkg/atomicwriter` equivalents. [moby/moby#49171](https://github.com/moby/moby/pull/49171)

* Go-SDK: `pkg/sysinfo`: Deprecate `NumCPU`. This utility has the same behavior as `runtime.NumCPU`. [moby/moby#49241](https://github.com/moby/moby/pull/49241)

* Go-SDK: `pkg/system`: Deprecate `MkdirAll`. This function provided custom handling for Windows GUID volume paths. Handling for such paths is now supported by Go standard library in go1.22 and newer, and this function is now an alias for `os.MkdirAll`, which should be used instead. This alias will be removed in the next release. [moby/moby#49162](https://github.com/moby/moby/pull/49162)

* Go-SDK: Deprecate `pkg/parsers.ParseKeyValueOpt`. [moby/moby#49177](https://github.com/moby/moby/pull/49177)

* Go-SDK: Deprecate `pkg/parsers.ParseUintListMaximum`, `pkg/parsers.ParseUintList`. These utilities were only used internally and will be removed in the next release. [moby/moby#49222](https://github.com/moby/moby/pull/49222)

* Go-SDK: Deprecate `api/type.IDResponse` in favor of `container.CommitResponse` and `container.ExecCreateResponse`, which are currently an alias, but may become distinct types in a future release. This type will be removed in the next release. [moby/moby#49446](https://github.com/moby/moby/pull/49446)

* Go-SDK: Deprecate `api/types/container.ContainerUpdateOKBody` in favor of `UpdateResponse`. This type will be removed in the next release. [moby/moby#49442](https://github.com/moby/moby/pull/49442)

* Go-SDK: Deprecate `api/types/container.ContainerTopOKBody` in favor of `TopResponse`. This type will be removed in the next release. [moby/moby#49442](https://github.com/moby/moby/pull/49442)

* Go-SDK: `pkg/jsonmessage`: Fix deprecation of `ProgressMessage`, `ErrorMessage`, which were deprecated in Docker v0.6.0 and v0.7.1 respectively. [moby/moby#49447](https://github.com/moby/moby/pull/49447)

* Move `GraphDriverData` from `api/types` to `api/types/storage`. The old type is deprecated and will be removed in the next release. [moby/moby#48108](https://github.com/moby/moby/pull/48108)

* Move `RequestPrivilegeFunc` from `api/types` to `api/types/registry`. The old type is deprecated and will be removed in the next release. [moby/moby#48119](https://github.com/moby/moby/pull/48119)

* Move from `api/types` to `api/types/container` - `NetworkSettings`, `NetworkSettingsBase`, `DefaultNetworkSettings`, `SummaryNetworkSettings`, `Health`, `HealthcheckResult`, `NoHealthcheck`, `Starting`, `Healthy`, and `Unhealthy` constants, `MountPoint`, `Port`, `ContainerState`, `Container`, `ContainerJSONBase`, `ContainerJSON`, `ContainerNode`. The old types are deprecated and will be removed in the next release. [moby/moby#48108](https://github.com/moby/moby/pull/48108)

* Move from `api/types` to `api/types/image` - `ImageInspect`, `RootFS`. The old types are deprecated and will be removed in the next release. [moby/moby#48108](https://github.com/moby/moby/pull/48108)

* `ContainerdCommit.Expected`, `RuncCommit.Expected`, and `InitCommit.Expected` fields in the `GET /info` endpoint are deprecated and will be omitted in API v1.49. [moby/moby#48478](https://github.com/moby/moby/pull/48478)

* `api/types/registry`: Deprecate `ServiceConfig.AllowNondistributableArtifactsCIDRs` and `ServiceConfig.AllowNondistributableArtifactsHostnames` fields. These fields will be removed in the next release. [moby/moby#49065](https://github.com/moby/moby/pull/49065)

* `api/types/system/Commit.Expected` field is deprecated and should no longer be used. [moby/moby#48478](https://github.com/moby/moby/pull/48478)

* `daemon/graphdriver`: Deprecate `GetDriver()` [moby/moby#48079](https://github.com/moby/moby/pull/48079)

* `libnetwork/iptables`: Deprecate `Passthrough`. This function was only used internally, and will be removed in the next release. [moby/moby#49115](https://github.com/moby/moby/pull/49115)

* `pkg/directory.Size()` function is deprecated, and will be removed in the next release. [moby/moby#48057](https://github.com/moby/moby/pull/48057)

* `registry`: Deprecate `APIEndpoint.TrimHostName`; hostname is now trimmed unconditionally for remote names. This field will be removed in the next release. [moby/moby#49005](https://github.com/moby/moby/pull/49005)

* `allow-nondistributable-artifacts` field in `daemon.json`. Setting either option will no longer take effect, but a deprecation warning log is added to raise awareness about the deprecation. This warning is planned to become an error in the next release. [moby/moby#49065](https://github.com/moby/moby/pull/49065)

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/edit/
----

# docker dhi customization edit

***

| Description                                                               | Edit an existing customization from YAML file |
| ------------------------------------------------------------------------- | --------------------------------------------- |
| Usage                                                                     | `docker dhi customization edit <file>`        |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker dhi customization update`             |

## [Description](#description)

Edit an existing Docker Hardened Images customization using a YAML file as input. The file should contain the complete customization structure with an 'id' field to identify which customization to update.

## [Options](#options)

| Option   | Default | Description           |
| -------- | ------- | --------------------- |
| `--json` |         | Output in JSON format |

----
url: https://docs.docker.com/reference/build-checks/json-args-recommended/
----

# JSONArgsRecommended

***

Table of contents

***

## [Output](#output)

```text
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals
```

## [Description](#description)

`ENTRYPOINT` and `CMD` instructions both support two different syntaxes for arguments:

* Shell form: `CMD my-cmd start`
* Exec form: `CMD ["my-cmd", "start"]`

When you use shell form, the executable runs as a child process to a shell, which doesn't pass signals. This means that the program running in the container can't detect OS signals like `SIGTERM` and `SIGKILL` and respond to them correctly.

## [Examples](#examples)

❌ Bad: the `ENTRYPOINT` command doesn't receive OS signals.

```dockerfile
FROM alpine
ENTRYPOINT my-program start
# entrypoint becomes: /bin/sh -c my-program start
```

To make sure the executable can receive OS signals, use the exec form for `CMD` and `ENTRYPOINT`, which lets you run the executable as the main process (`PID 1`) in the container, avoiding a shell parent process.

✅ Good: the `ENTRYPOINT` receives OS signals.

```dockerfile
FROM alpine
ENTRYPOINT ["my-program", "start"]
# entrypoint becomes: my-program start
```

Note that running programs as PID 1 means the program now has the special responsibilities and behaviors associated with PID 1 in Linux, such as reaping child processes.

### [Workarounds](#workarounds)

There might still be cases when you want to run your containers under a shell. When using exec form, shell features such as variable expansion, piping (`|`) and command chaining (`&&`, `||`, `;`), are not available. To use such features, you need to use shell form.

Here are some ways you can achieve that. Note that this still means that executables run as child-processes of a shell.

#### [Create a wrapper script](#create-a-wrapper-script)

You can create an entrypoint script that wraps your startup commands, and execute that script with a JSON-formatted `ENTRYPOINT` command.

✅ Good: the `ENTRYPOINT` uses JSON format.

```dockerfile
FROM alpine
RUN apk add bash
COPY --chmod=755 <<EOT /entrypoint.sh
#!/usr/bin/env bash
set -e
my-background-process &
my-program start
EOT
ENTRYPOINT ["/entrypoint.sh"]
```

#### [Explicitly specify the shell](#explicitly-specify-the-shell)

You can use the [`SHELL`](https://docs.docker.com/reference/dockerfile/#shell) Dockerfile instruction to explicitly specify a shell to use. This will suppress the warning since setting the `SHELL` instruction indicates that using shell form is a conscious decision.

✅ Good: shell is explicitly defined.

```dockerfile
FROM alpine
RUN apk add bash
SHELL ["/bin/bash", "-c"]
ENTRYPOINT echo "hello world"
```

----
url: https://docs.docker.com/billing/history/
----

# Invoices and billing history

***

Table of contents

***

Learn how to view and pay invoices, view your billing history, and verify your billing renewal date. All monthly and annual subscriptions are automatically renewed at the end of the subscription term using your default payment method.

## [View an invoice](#view-an-invoice)

Your invoice includes the following:

* Invoice number
* Date of issue
* Due date
* Your "Bill to" information
* Amount due (in USD)
* Pay online: Select this link to pay your invoice online
* Description of your order, quantity if applicable, unit price, and amount (in USD)
* Subtotal, discount (if applicable), and total

The information listed in the "Bill to" section of your invoice is based on your billing information. Not all fields are required. The billing information includes the following:

* Name (required): The name of the administrator or company
* Address (required)
* Email address (required): The email address that receives all billing-related emails for the account
* Phone number
* Tax ID or VAT

You can’t make changes to a paid or unpaid billing invoice. When you update your billing information, this change won't update an existing invoice.

If you need to update your billing information, make sure you do so before your subscription renewal date when your invoice is finalized.

For more information, see [Update billing information](https://docs.docker.com/billing/details/).

## [Pay an invoice](#pay-an-invoice)

> Note
>
> Pay by invoice is only available for subscribers on an annual billing cycle. To change your billing cycle, see [Change your billing cycle](https://docs.docker.com/billing/cycle/).

If you've selected pay by invoice for your subscription, you'll receive email reminders to pay your invoice at 10 days before the due date, on the due date, and 15 days after the due date.

You can pay an invoice from the Docker Billing Console:

1. Sign in to [Docker Home](https://app.docker.com/) and choose your organization.
2. Select **Billing**.
3. Select **Invoices** and locate the invoice you want to pay.
4. In the **Actions** column, select **Pay invoice**.
5. Fill out your payment details and select **Pay**.

When your payment has processed, the invoice's **Status** column will update to **Paid** and you will receive a confirmation email.

If you choose to pay using a US bank account, you must verify the account. For more information, see [Verify a bank account](https://docs.docker.com/billing/payment-method/#verify-a-bank-account).

### [View renewal date](#view-renewal-date)

You receive your invoice when the subscription renews. To verify your renewal date:

1. Sign in to [Docker Home Billing](https://app.docker.com/billing).
2. Find your renewal date and amount on your subscription plan card.

## [Include your VAT number on your invoice](#include-your-vat-number-on-your-invoice)

> Note
>
> If the VAT number field is not available, complete the [Contact Support form](https://hub.docker.com/support/contact/). This field may need to be manually added.

To add or update your VAT number:

1. Sign in to [Docker Home](https://app.docker.com/) and choose your organization.

2. Select **Billing**.

3. Select **Billing information** from the left-hand menu.

4. Select **Change** on your billing information card.

5. Ensure the **I'm purchasing as a business** checkbox is checked.

6. Enter your VAT number in the Tax ID section.

   > Important
   >
   > Your VAT number must include your country prefix. For example, if you are entering a VAT number for Germany, you would enter `DE123456789`.

7. Select **Update**.

Your VAT number will be included on your next invoice.

## [View billing history](#view-billing-history)

You can view your billing history and download past invoices for a personal account or organization.

### [Personal account](#personal-account)

To view billing history:

1. Sign in to [Docker Home](https://app.docker.com/) and choose your organization.
2. Select **Billing**.
3. Select **Invoices** from the left-hand menu.
4. Optional. Select the **Invoice number** to open invoice details.
5. Optional. Select the **Download** button to download an invoice.

### [Organization](#organization)

You must be an owner of the organization to view the billing history.

To view billing history:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Billing**.
3. Select **Invoices** from the left-hand menu.
4. Optional. Select the **invoice number** to open invoice details.
5. Optional. Select the **download** button to download an invoice.

----
url: https://docs.docker.com/engine/logging/plugins/
----

# Use a logging driver plugin

***

Table of contents

***

Docker logging plugins allow you to extend and customize Docker's logging capabilities beyond those of the [built-in logging drivers](https://docs.docker.com/engine/logging/configure/). A logging service provider can [implement their own plugins](https://docs.docker.com/engine/extend/plugins_logging/) and make them available on Docker Hub, or a private registry. This topic shows how a user of that logging service can configure Docker to use the plugin.

## [Install the logging driver plugin](#install-the-logging-driver-plugin)

To install a logging driver plugin, use `docker plugin install <org/image>`, using the information provided by the plugin developer.

You can list all installed plugins using `docker plugin ls`, and you can inspect a specific plugin using `docker inspect`.

## [Configure the plugin as the default logging driver](#configure-the-plugin-as-the-default-logging-driver)

When the plugin is installed, you can configure the Docker daemon to use it as the default by setting the plugin's name as the value of the `log-driver` key in the `daemon.json`, as detailed in the [logging overview](https://docs.docker.com/engine/logging/configure/#configure-the-default-logging-driver). If the logging driver supports additional options, you can set those as the values of the `log-opts` array in the same file.

## [Configure a container to use the plugin as the logging driver](#configure-a-container-to-use-the-plugin-as-the-logging-driver)

After the plugin is installed, you can configure a container to use the plugin as its logging driver by specifying the `--log-driver` flag to `docker run`, as detailed in the [logging overview](https://docs.docker.com/engine/logging/configure/#configure-the-logging-driver-for-a-container). If the logging driver supports additional options, you can specify them using one or more `--log-opt` flags with the option name as the key and the option value as the value.

----
url: https://docs.docker.com/engine/daemon/proxy/
----

# Daemon proxy configuration

***

Table of contents

***

[]()

If your organization uses a proxy server to connect to the internet, you may need to configure the Docker daemon to use the proxy server. The daemon uses a proxy server to access images stored on Docker Hub and other registries, and to reach other nodes in a Docker swarm.

This page describes how to configure a proxy for the Docker daemon. For instructions on configuring proxy settings for the Docker CLI, see [Configure Docker CLI to use a proxy server](https://docs.docker.com/engine/cli/proxy/).

> Important
>
> Proxy configurations specified in the `daemon.json` are ignored by Docker Desktop. If you use Docker Desktop, you can configure proxies using the [Docker Desktop settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies).

There are two ways you can configure these settings:

* [Configuring the daemon](#daemon-configuration) through a configuration file or CLI flags
* Setting [environment variables](#environment-variables) on the system

Configuring the daemon directly takes precedence over environment variables.

## [Daemon configuration](#daemon-configuration)

You may configure proxy behavior for the daemon in the `daemon.json` file, or using CLI flags for the `--http-proxy` or `--https-proxy` flags for the `dockerd` command. Configuration using `daemon.json` is recommended.

```json
{
  "proxies": {
    "http-proxy": "http://proxy.example.com:3128",
    "https-proxy": "http://proxy.example.com:3128",
    "no-proxy": "*.test.example.com,.example.org,127.0.0.0/8"
  }
}
```

After changing the configuration file, restart the daemon for the proxy configuration to take effect:

```console
$ sudo systemctl restart docker
```

## [Environment variables](#environment-variables)

The Docker daemon checks the following environment variables in its start-up environment to configure HTTP or HTTPS proxy behavior:

* `HTTP_PROXY`
* `http_proxy`
* `HTTPS_PROXY`
* `https_proxy`
* `NO_PROXY`
* `no_proxy`

### [systemd unit file](#systemd-unit-file)

If you're running the Docker daemon as a systemd service, you can create a systemd drop-in file that sets the variables for the `docker` service.

> **Note for rootless mode**
>
> The location of systemd configuration files are different when running Docker in [rootless mode](https://docs.docker.com/engine/security/rootless/). When running in rootless mode, Docker is started as a user-mode systemd service, and uses files stored in each users' home directory in `~/.config/systemd/<user>/docker.service.d/`. In addition, `systemctl` must be executed without `sudo` and with the `--user` flag. Select the "Rootless mode" tab if you are running Docker in rootless mode.

1. Create a systemd drop-in directory for the `docker` service:

   ```console
   $ sudo mkdir -p /etc/systemd/system/docker.service.d
   ```

2. Create a file named `/etc/systemd/system/docker.service.d/http-proxy.conf` that adds the `HTTP_PROXY` environment variable:

   ```systemd
   [Service]
   Environment="HTTP_PROXY=http://proxy.example.com:3128"
   ```

   To proxy HTTPS requests, set the `HTTPS_PROXY` environment variable:

   ```systemd
   [Service]
   Environment="HTTPS_PROXY=http://proxy.example.com:3128"
   ```

   Multiple environment variables can be set; to set both an HTTP and an HTTPS proxy;

   ```systemd
   [Service]
   Environment="HTTP_PROXY=http://proxy.example.com:3128"
   Environment="HTTPS_PROXY=http://proxy.example.com:3128"
   ```

   > Note
   >
   > Special characters in the proxy value, such as `#?!()[]{}`, must be double escaped using `%%`. For example:
   >
   > ```systemd
   > [Service]
   > Environment="HTTP_PROXY=http://domain%%5Cuser:complex%%23pass@proxy.example.com:3128/"
   > ```

3. If you have internal Docker registries that you need to contact without proxying, you can specify them via the `NO_PROXY` environment variable.

   The `NO_PROXY` variable specifies a string that contains comma-separated values for hosts that should be excluded from proxying. These are the options you can specify to exclude hosts:

   * IP address prefix (`1.2.3.4`)

   * Domain name, or a special DNS label (`*`)

   * A domain name matches that name and all subdomains. A domain name with a leading "." matches subdomains only. For example, given the domains `foo.example.com` and `example.com`:

     * `example.com` matches `example.com` and `foo.example.com`, and
     * `.example.com` matches only `foo.example.com`

   * A single asterisk (`*`) indicates that no proxying should be done

   * Literal port numbers are accepted by IP address prefixes (`1.2.3.4:80`) and domain names (`foo.example.com:80`)

   Example:

   ```systemd
   [Service]
   Environment="HTTP_PROXY=http://proxy.example.com:3128"
   Environment="HTTPS_PROXY=http://proxy.example.com:3128"
   Environment="NO_PROXY=localhost,127.0.0.1,docker-registry.example.com,.corp"
   ```

4. Flush changes and restart Docker

   ```console
   $ sudo systemctl daemon-reload
   $ sudo systemctl restart docker
   ```

5. Verify that the configuration has been loaded and matches the changes you made, for example:

   ```console
   $ sudo systemctl show --property=Environment docker

   Environment=HTTP_PROXY=http://proxy.example.com:3128 HTTPS_PROXY=http://proxy.example.com:3128 NO_PROXY=localhost,127.0.0.1,docker-registry.example.com,.corp
   ```

1) Create a systemd drop-in directory for the `docker` service:

   ```console
   $ mkdir -p ~/.config/systemd/user/docker.service.d
   ```

2) Create a file named `~/.config/systemd/user/docker.service.d/http-proxy.conf` that adds the `HTTP_PROXY` environment variable:

   ```systemd
   [Service]
   Environment="HTTP_PROXY=http://proxy.example.com:3128"
   ```

   To proxy HTTPS requests, set the `HTTPS_PROXY` environment variable:

   ```systemd
   [Service]
   Environment="HTTPS_PROXY=http://proxy.example.com:3128"
   ```

   Multiple environment variables can be set; to set both an HTTP and an HTTPS proxy;

   ```systemd
   [Service]
   Environment="HTTP_PROXY=http://proxy.example.com:3128"
   Environment="HTTPS_PROXY=http://proxy.example.com:3128"
   ```

   > Note
   >
   > Special characters in the proxy value, such as `#?!()[]{}`, must be double escaped using `%%`. For example:
   >
   > ```systemd
   > [Service]
   > Environment="HTTP_PROXY=http://domain%%5Cuser:complex%%23pass@proxy.example.com:3128/"
   > ```

3) If you have internal Docker registries that you need to contact without proxying, you can specify them via the `NO_PROXY` environment variable.

   The `NO_PROXY` variable specifies a string that contains comma-separated values for hosts that should be excluded from proxying. These are the options you can specify to exclude hosts:

   * IP address prefix (`1.2.3.4`)

   * Domain name, or a special DNS label (`*`)

   * A domain name matches that name and all subdomains. A domain name with a leading "." matches subdomains only. For example, given the domains `foo.example.com` and `example.com`:

     * `example.com` matches `example.com` and `foo.example.com`, and
     * `.example.com` matches only `foo.example.com`

   * A single asterisk (`*`) indicates that no proxying should be done

   * Literal port numbers are accepted by IP address prefixes (`1.2.3.4:80`) and domain names (`foo.example.com:80`)

   Example:

   ```systemd
   [Service]
   Environment="HTTP_PROXY=http://proxy.example.com:3128"
   Environment="HTTPS_PROXY=http://proxy.example.com:3128"
   Environment="NO_PROXY=localhost,127.0.0.1,docker-registry.example.com,.corp"
   ```

4) Flush changes and restart Docker

   ```console
   $ systemctl --user daemon-reload
   $ systemctl --user restart docker
   ```

5) Verify that the configuration has been loaded and matches the changes you made, for example:

   ```console
   $ systemctl --user show --property=Environment docker

   Environment=HTTP_PROXY=http://proxy.example.com:3128 HTTPS_PROXY=http://proxy.example.com:3128 NO_PROXY=localhost,127.0.0.1,docker-registry.example.com,.corp
   ```

----
url: https://docs.docker.com/reference/api/extensions-sdk/DockerCommand/
----

# Interface: DockerCommand

***

Table of contents

***

**`Since`**

0.2.0

## [Properties](#properties)

### [exec](#exec)

• **exec**: [`Exec`](https://docs.docker.com/reference/api/extensions-sdk/Exec/)

----
url: https://docs.docker.com/guides/testcontainers-java-keycloak-spring-boot/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

```console
$ ./mvnw test
```

Or with Gradle:

```console
$ ./gradlew test
```

You should see the Keycloak and PostgreSQL Docker containers start with the realm settings imported and the tests pass. After the tests finish, the containers stop and are removed automatically.

## [Summary](#summary)

The Testcontainers Keycloak module lets you develop and test applications using a real Keycloak server instead of mocks. Testing against a real OAuth 2.0 provider that mirrors your production setup gives you more confidence in your security configuration and token-based authentication flows.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Getting started with Testcontainers in a Java Spring Boot project](https://testcontainers.com/guides/testing-spring-boot-rest-api-using-testcontainers/)
* [Testcontainers Keycloak module](https://testcontainers.com/modules/keycloak/)
* [testcontainers-keycloak GitHub repository](https://github.com/dasniko/testcontainers-keycloak)
* [Spring Boot OAuth 2.0 Resource Server](https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/index.html)

----
url: https://docs.docker.com/reference/cli/docker/compose/publish/
----

# docker compose publish

***

| Description | Publish compose application                         |
| ----------- | --------------------------------------------------- |
| Usage       | `docker compose publish [OPTIONS] REPOSITORY[:TAG]` |

## [Description](#description)

Publish compose application

## [Options](#options)

| Option                    | Default | Description                                                                     |
| ------------------------- | ------- | ------------------------------------------------------------------------------- |
| `--app`                   |         | Published compose application (includes referenced images)                      |
| `--oci-version`           |         | OCI image/artifact specification version (automatically determined by default)  |
| `--resolve-image-digests` |         | Pin image tags to digests                                                       |
| `--with-env`              |         | Include environment variables in the published OCI artifact                     |
| `-y, --yes`               |         | Assume "yes" as answer to all prompts                                           |

----
url: https://docs.docker.com/reference/cli/docker/scout/attestation/
----

# docker scout attestation

***

| Description                                                               | Manage attestations on images |
| ------------------------------------------------------------------------- | ----------------------------- |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker scout attest`         |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Manage attestations on images

## [Subcommands](#subcommands)

| Command                                                                                                 | Description                 |
| ------------------------------------------------------------------------------------------------------- | --------------------------- |
| [`docker scout attestation add`](https://docs.docker.com/reference/cli/docker/scout/attestation/add/)   | Add attestation to image    |
| [`docker scout attestation get`](https://docs.docker.com/reference/cli/docker/scout/attestation/get/)   | Get attestation for image   |
| [`docker scout attestation list`](https://docs.docker.com/reference/cli/docker/scout/attestation/list/) | List attestations for image |

----
url: https://docs.docker.com/engine/storage/drivers/device-mapper-driver/
----

# Device Mapper storage driver (deprecated)

***

Table of contents

***

> **Deprecated**
>
> The Device Mapper driver [has been deprecated](https://docs.docker.com/engine/deprecated/#device-mapper-storage-driver), and is removed in Docker Engine v25.0. If you are using Device Mapper, you must migrate to a supported storage driver before upgrading to Docker Engine v25.0. Read the [Docker storage drivers](https://docs.docker.com/engine/storage/drivers/select-storage-driver/) page for supported storage drivers.

Device Mapper is a kernel-based framework that underpins many advanced volume management technologies on Linux. Docker's `devicemapper` storage driver leverages the thin provisioning and snapshotting capabilities of this framework for image and container management. This article refers to the Device Mapper storage driver as `devicemapper`, and the kernel framework as *Device Mapper*.

For the systems where it is supported, `devicemapper` support is included in the Linux kernel. However, specific configuration is required to use it with Docker.

The `devicemapper` driver uses block devices dedicated to Docker and operates at the block level, rather than the file level. These devices can be extended by adding physical storage to your Docker host, and they perform better than using a filesystem at the operating system (OS) level.

## [Prerequisites](#prerequisites)

* `devicemapper` is supported on Docker Engine - Community running on CentOS, Fedora, SLES 15, Ubuntu, Debian, or RHEL.
* `devicemapper` requires the `lvm2` and `device-mapper-persistent-data` packages to be installed.
* Changing the storage driver makes any containers you have already created inaccessible on the local system. Use `docker save` to save containers, and push existing images to Docker Hub or a private repository, so you do not need to recreate them later.

## [Configure Docker with the `devicemapper` storage driver](#configure-docker-with-the-devicemapper-storage-driver)

Before following these procedures, you must first meet all the [prerequisites](#prerequisites).

### [Configure `loop-lvm` mode for testing](#configure-loop-lvm-mode-for-testing)

This configuration is only appropriate for testing. The `loop-lvm` mode makes use of a 'loopback' mechanism that allows files on the local disk to be read from and written to as if they were an actual physical disk or block device. However, the addition of the loopback mechanism, and interaction with the OS filesystem layer, means that IO operations can be slow and resource-intensive. Use of loopback devices can also introduce race conditions. However, setting up `loop-lvm` mode can help identify basic issues (such as missing user space packages, kernel drivers, etc.) ahead of attempting the more complex set up required to enable `direct-lvm` mode. `loop-lvm` mode should therefore only be used to perform rudimentary testing prior to configuring `direct-lvm`.

For production systems, see [Configure direct-lvm mode for production](#configure-direct-lvm-mode-for-production).

1. Stop Docker.

   ```console
   $ sudo systemctl stop docker
   ```

2. Edit `/etc/docker/daemon.json`. If it does not yet exist, create it. Assuming that the file was empty, add the following contents.

   ```json
   {
     "storage-driver": "devicemapper"
   }
   ```

   See all storage options for each storage driver in the [daemon reference documentation](/reference/cli/dockerd/#options-per-storage-driver)

   Docker does not start if the `daemon.json` file contains badly-formed JSON.

3. Start Docker.

   ```console
   $ sudo systemctl start docker
   ```

4. Verify that the daemon is using the `devicemapper` storage driver. Use the `docker info` command and look for `Storage Driver`.

   ```console
   $ docker info

     Containers: 0
       Running: 0
       Paused: 0
       Stopped: 0
     Images: 0
     Server Version: 17.03.1-ce
     Storage Driver: devicemapper
     Pool Name: docker-202:1-8413957-pool
     Pool Blocksize: 65.54 kB
     Base Device Size: 10.74 GB
     Backing Filesystem: xfs
     Data file: /dev/loop0
     Metadata file: /dev/loop1
     Data Space Used: 11.8 MB
     Data Space Total: 107.4 GB
     Data Space Available: 7.44 GB
     Metadata Space Used: 581.6 KB
     Metadata Space Total: 2.147 GB
     Metadata Space Available: 2.147 GB
     Thin Pool Minimum Free Space: 10.74 GB
     Udev Sync Supported: true
     Deferred Removal Enabled: false
     Deferred Deletion Enabled: false
     Deferred Deleted Device Count: 0
     Data loop file: /var/lib/docker/devicemapper/data
     Metadata loop file: /var/lib/docker/devicemapper/metadata
     Library Version: 1.02.135-RHEL7 (2016-11-16)
   <...>
   ```

This host is running in `loop-lvm` mode, which is **not** supported on production systems. This is indicated by the fact that the `Data loop file` and a `Metadata loop file` are on files under `/var/lib/docker/devicemapper`. These are loopback-mounted sparse files. For production systems, see [Configure direct-lvm mode for production](#configure-direct-lvm-mode-for-production).

### [Configure direct-lvm mode for production](#configure-direct-lvm-mode-for-production)

Production hosts using the `devicemapper` storage driver must use `direct-lvm` mode. This mode uses block devices to create the thin pool. This is faster than using loopback devices, uses system resources more efficiently, and block devices can grow as needed. However, more setup is required than in `loop-lvm` mode.

After you have satisfied the [prerequisites](#prerequisites), follow the steps below to configure Docker to use the `devicemapper` storage driver in `direct-lvm` mode.

> Warning
>
> Changing the storage driver makes any containers you have already created inaccessible on the local system. Use `docker save` to save containers, and push existing images to Docker Hub or a private repository, so you do not need to recreate them later.

#### [Allow Docker to configure direct-lvm mode](#allow-docker-to-configure-direct-lvm-mode)

Docker can manage the block device for you, simplifying configuration of `direct-lvm` mode. **This is appropriate for fresh Docker setups only.** You can only use a single block device. If you need to use multiple block devices, [configure direct-lvm mode manually](#configure-direct-lvm-mode-manually) instead. The following new configuration options are available:

| Option                          | Description                                                                                                                                                                        | Required? | Default | Example                            |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- | ---------------------------------- |
| `dm.directlvm_device`           | The path to the block device to configure for `direct-lvm`.                                                                                                                        | Yes       |         | `dm.directlvm_device="/dev/xvdf"`  |
| `dm.thinp_percent`              | The percentage of space to use for storage from the passed in block device.                                                                                                        | No        | 95      | `dm.thinp_percent=95`              |
| `dm.thinp_metapercent`          | The percentage of space to use for metadata storage from the passed-in block device.                                                                                               | No        | 1       | `dm.thinp_metapercent=1`           |
| `dm.thinp_autoextend_threshold` | The threshold for when lvm should automatically extend the thin pool as a percentage of the total storage space.                                                                   | No        | 80      | `dm.thinp_autoextend_threshold=80` |
| `dm.thinp_autoextend_percent`   | The percentage to increase the thin pool by when an autoextend is triggered.                                                                                                       | No        | 20      | `dm.thinp_autoextend_percent=20`   |
| `dm.directlvm_device_force`     | Whether to format the block device even if a filesystem already exists on it. If set to `false` and a filesystem is present, an error is logged and the filesystem is left intact. | No        | false   | `dm.directlvm_device_force=true`   |

Edit the `daemon.json` file and set the appropriate options, then restart Docker for the changes to take effect. The following `daemon.json` configuration sets all of the options in the table above.

```json
{
  "storage-driver": "devicemapper",
  "storage-opts": [
    "dm.directlvm_device=/dev/xdf",
    "dm.thinp_percent=95",
    "dm.thinp_metapercent=1",
    "dm.thinp_autoextend_threshold=80",
    "dm.thinp_autoextend_percent=20",
    "dm.directlvm_device_force=false"
  ]
}
```

See all storage options for each storage driver in the [daemon reference documentation](/reference/cli/dockerd/#options-per-storage-driver)

Restart Docker for the changes to take effect. Docker invokes the commands to configure the block device for you.

> Warning
>
> Changing these values after Docker has prepared the block device for you is not supported and causes an error.

You still need to [perform periodic maintenance tasks](#manage-devicemapper).

#### [Configure direct-lvm mode manually](#configure-direct-lvm-mode-manually)

The procedure below creates a logical volume configured as a thin pool to use as backing for the storage pool. It assumes that you have a spare block device at `/dev/xvdf` with enough free space to complete the task. The device identifier and volume sizes may be different in your environment and you should substitute your own values throughout the procedure. The procedure also assumes that the Docker daemon is in the `stopped` state.

1. Identify the block device you want to use. The device is located under `/dev/` (such as `/dev/xvdf`) and needs enough free space to store the images and container layers for the workloads that host runs. A solid state drive is ideal.

2. Stop Docker.

   ```console
   $ sudo systemctl stop docker
   ```

3. Install the following packages:

   * **RHEL / CentOS**: `device-mapper-persistent-data`, `lvm2`, and all dependencies

   * **Ubuntu / Debian / SLES 15**: `thin-provisioning-tools`, `lvm2`, and all dependencies

4. Create a physical volume on your block device from step 1, using the `pvcreate` command. Substitute your device name for `/dev/xvdf`.

   > Warning
   >
   > The next few steps are destructive, so be sure that you have specified the correct device.

   ```console
   $ sudo pvcreate /dev/xvdf

   Physical volume "/dev/xvdf" successfully created.
   ```

5. Create a `docker` volume group on the same device, using the `vgcreate` command.

   ```console
   $ sudo vgcreate docker /dev/xvdf

   Volume group "docker" successfully created
   ```

6. Create two logical volumes named `thinpool` and `thinpoolmeta` using the `lvcreate` command. The last parameter specifies the amount of free space to allow for automatic expanding of the data or metadata if space runs low, as a temporary stop-gap. These are the recommended values.

   ```console
   $ sudo lvcreate --wipesignatures y -n thinpool docker -l 95%VG

   Logical volume "thinpool" created.

   $ sudo lvcreate --wipesignatures y -n thinpoolmeta docker -l 1%VG

   Logical volume "thinpoolmeta" created.
   ```

7. Convert the volumes to a thin pool and a storage location for metadata for the thin pool, using the `lvconvert` command.

   ```console
   $ sudo lvconvert -y \
   --zero n \
   -c 512K \
   --thinpool docker/thinpool \
   --poolmetadata docker/thinpoolmeta

   WARNING: Converting logical volume docker/thinpool and docker/thinpoolmeta to
   thin pool's data and metadata volumes with metadata wiping.
   THIS WILL DESTROY CONTENT OF LOGICAL VOLUME (filesystem etc.)
   Converted docker/thinpool to thin pool.
   ```

8. Configure autoextension of thin pools via an `lvm` profile.

   ```console
   $ sudo vi /etc/lvm/profile/docker-thinpool.profile
   ```

9. Specify `thin_pool_autoextend_threshold` and `thin_pool_autoextend_percent` values.

   `thin_pool_autoextend_threshold` is the percentage of space used before `lvm` attempts to autoextend the available space (100 = disabled, not recommended).

   `thin_pool_autoextend_percent` is the amount of space to add to the device when automatically extending (0 = disabled).

   The example below adds 20% more capacity when the disk usage reaches 80%.

   ```text
   activation {
     thin_pool_autoextend_threshold=80
     thin_pool_autoextend_percent=20
   }
   ```

   Save the file.

10. Apply the LVM profile, using the `lvchange` command.

    ```console
    $ sudo lvchange --metadataprofile docker-thinpool docker/thinpool

    Logical volume docker/thinpool changed.
    ```

11. Ensure monitoring of the logical volume is enabled.

    ```console
    $ sudo lvs -o+seg_monitor

    LV       VG     Attr       LSize  Pool Origin Data%  Meta%  Move Log Cpy%Sync Convert Monitor
    thinpool docker twi-a-t--- 95.00g             0.00   0.01                             not monitored
    ```

    If the output in the `Monitor` column reports, as above, that the volume is `not monitored`, then monitoring needs to be explicitly enabled. Without this step, automatic extension of the logical volume will not occur, regardless of any settings in the applied profile.

    ```console
    $ sudo lvchange --monitor y docker/thinpool
    ```

    Double check that monitoring is now enabled by running the `sudo lvs -o+seg_monitor` command a second time. The `Monitor` column should now report the logical volume is being `monitored`.

12. If you have ever run Docker on this host before, or if `/var/lib/docker/` exists, move it out of the way so that Docker can use the new LVM pool to store the contents of image and containers.

    ```console
    $ sudo su -
    # mkdir /var/lib/docker.bk
    # mv /var/lib/docker/* /var/lib/docker.bk
    # exit
    ```

    If any of the following steps fail and you need to restore, you can remove `/var/lib/docker` and replace it with `/var/lib/docker.bk`.

13. Edit `/etc/docker/daemon.json` and configure the options needed for the `devicemapper` storage driver. If the file was previously empty, it should now contain the following contents:

    ```json
    {
        "storage-driver": "devicemapper",
        "storage-opts": [
        "dm.thinpooldev=/dev/mapper/docker-thinpool",
        "dm.use_deferred_removal=true",
        "dm.use_deferred_deletion=true"
        ]
    }
    ```

14. Start Docker.

    **systemd**:

    ```console
    $ sudo systemctl start docker
    ```

    **service**:

    ```console
    $ sudo service docker start
    ```

15. Verify that Docker is using the new configuration using `docker info`.

    ```console
    $ docker info

    Containers: 0
     Running: 0
     Paused: 0
     Stopped: 0
    Images: 0
    Server Version: 17.03.1-ce
    Storage Driver: devicemapper
     Pool Name: docker-thinpool
     Pool Blocksize: 524.3 kB
     Base Device Size: 10.74 GB
     Backing Filesystem: xfs
     Data file:
     Metadata file:
     Data Space Used: 19.92 MB
     Data Space Total: 102 GB
     Data Space Available: 102 GB
     Metadata Space Used: 147.5 kB
     Metadata Space Total: 1.07 GB
     Metadata Space Available: 1.069 GB
     Thin Pool Minimum Free Space: 10.2 GB
     Udev Sync Supported: true
     Deferred Removal Enabled: true
     Deferred Deletion Enabled: true
     Deferred Deleted Device Count: 0
     Library Version: 1.02.135-RHEL7 (2016-11-16)
    <...>
    ```

    If Docker is configured correctly, the `Data file` and `Metadata file` is blank, and the pool name is `docker-thinpool`.

16. After you have verified that the configuration is correct, you can remove the `/var/lib/docker.bk` directory which contains the previous configuration.

    ```console
    $ sudo rm -rf /var/lib/docker.bk
    ```

## [Manage devicemapper](#manage-devicemapper)

### [Monitor the thin pool](#monitor-the-thin-pool)

Do not rely on LVM auto-extension alone. The volume group automatically extends, but the volume can still fill up. You can monitor free space on the volume using `lvs` or `lvs -a`. Consider using a monitoring tool at the OS level, such as Nagios.

To view the LVM logs, you can use `journalctl`:

```console
$ sudo journalctl -fu dm-event.service
```

If you run into repeated problems with thin pool, you can set the storage option `dm.min_free_space` to a value (representing a percentage) in `/etc/docker/daemon.json`. For instance, setting it to `10` ensures that operations fail with a warning when the free space is at or near 10%. See the [storage driver options in the Engine daemon reference](/reference/cli/dockerd/#daemon-storage-driver).

### [Increase capacity on a running device](#increase-capacity-on-a-running-device)

You can increase the capacity of the pool on a running thin-pool device. This is useful if the data's logical volume is full and the volume group is at full capacity. The specific procedure depends on whether you are using a [loop-lvm thin pool](#resize-a-loop-lvm-thin-pool) or a [direct-lvm thin pool](#resize-a-direct-lvm-thin-pool).

#### [Resize a loop-lvm thin pool](#resize-a-loop-lvm-thin-pool)

The easiest way to resize a `loop-lvm` thin pool is to [use the device\_tool utility](#use-the-device_tool-utility), but you can [use operating system utilities](#use-operating-system-utilities) instead.

##### [Use the device\_tool utility](#use-the-device_tool-utility)

A community-contributed script called `device_tool.go` is available in the [moby/moby](https://github.com/moby/moby/tree/master/contrib/docker-device-tool) Github repository. You can use this tool to resize a `loop-lvm` thin pool, avoiding the long process above. This tool is not guaranteed to work, but you should only be using `loop-lvm` on non-production systems.

If you do not want to use `device_tool`, you can [resize the thin pool manually](#use-operating-system-utilities) instead.

1. To use the tool, clone the Github repository, change to the `contrib/docker-device-tool`, and follow the instructions in the `README.md` to compile the tool.

2. Use the tool. The following example resizes the thin pool to 200GB.

   ```console
   $ ./device_tool resize 200GB
   ```

##### [Use operating system utilities](#use-operating-system-utilities)

If you do not want to [use the device-tool utility](#use-the-device_tool-utility), you can resize a `loop-lvm` thin pool manually using the following procedure.

In `loop-lvm` mode, a loopback device is used to store the data, and another to store the metadata. `loop-lvm` mode is only supported for testing, because it has significant performance and stability drawbacks.

If you are using `loop-lvm` mode, the output of `docker info` shows file paths for `Data loop file` and `Metadata loop file`:

```console
$ docker info |grep 'loop file'

 Data loop file: /var/lib/docker/devicemapper/data
 Metadata loop file: /var/lib/docker/devicemapper/metadata
```

Follow these steps to increase the size of the thin pool. In this example, the thin pool is 100 GB, and is increased to 200 GB.

1. List the sizes of the devices.

   ```console
   $ sudo ls -lh /var/lib/docker/devicemapper/

   total 1175492
   -rw------- 1 root root 100G Mar 30 05:22 data
   -rw------- 1 root root 2.0G Mar 31 11:17 metadata
   ```

2. Increase the size of the `data` file to 200 G using the `truncate` command, which is used to increase **or** decrease the size of a file. Note that decreasing the size is a destructive operation.

   ```console
   $ sudo truncate -s 200G /var/lib/docker/devicemapper/data
   ```

3. Verify the file size changed.

   ```console
   $ sudo ls -lh /var/lib/docker/devicemapper/

   total 1.2G
   -rw------- 1 root root 200G Apr 14 08:47 data
   -rw------- 1 root root 2.0G Apr 19 13:27 metadata
   ```

4. The loopback file has changed on disk but not in memory. List the size of the loopback device in memory, in GB. Reload it, then list the size again. After the reload, the size is 200 GB.

   ```console
   $ echo $[ $(sudo blockdev --getsize64 /dev/loop0) / 1024 / 1024 / 1024 ]

   100

   $ sudo losetup -c /dev/loop0

   $ echo $[ $(sudo blockdev --getsize64 /dev/loop0) / 1024 / 1024 / 1024 ]

   200
   ```

5. Reload the devicemapper thin pool.

   a. Get the pool name first. The pool name is the first field, delimited by `:`. This command extracts it.

   ```console
   $ sudo dmsetup status | grep ' thin-pool ' | awk -F ': ' {'print $1'}
   docker-8:1-123141-pool
   ```

   b. Dump the device mapper table for the thin pool.

   ```console
   $ sudo dmsetup table docker-8:1-123141-pool
   0 209715200 thin-pool 7:1 7:0 128 32768 1 skip_block_zeroing
   ```

   c. Calculate the total sectors of the thin pool using the second field of the output. The number is expressed in 512-k sectors. A 100G file has 209715200 512-k sectors. If you double this number to 200G, you get 419430400 512-k sectors.

   d. Reload the thin pool with the new sector number, using the following three `dmsetup` commands.

   ```console
   $ sudo dmsetup suspend docker-8:1-123141-pool
   $ sudo dmsetup reload docker-8:1-123141-pool --table '0 419430400 thin-pool 7:1 7:0 128 32768 1 skip_block_zeroing'
   $ sudo dmsetup resume docker-8:1-123141-pool
   ```

#### [Resize a direct-lvm thin pool](#resize-a-direct-lvm-thin-pool)

To extend a `direct-lvm` thin pool, you need to first attach a new block device to the Docker host, and make note of the name assigned to it by the kernel. In this example, the new block device is `/dev/xvdg`.

Follow this procedure to extend a `direct-lvm` thin pool, substituting your block device and other parameters to suit your situation.

1. Gather information about your volume group.

   Use the `pvdisplay` command to find the physical block devices currently in use by your thin pool, and the volume group's name.

   ```console
   $ sudo pvdisplay |grep 'VG Name'

   PV Name               /dev/xvdf
   VG Name               docker
   ```

   In the following steps, substitute your block device or volume group name as appropriate.

2. Extend the volume group, using the `vgextend` command with the `VG Name` from the previous step, and the name of your **new** block device.

   ```console
   $ sudo vgextend docker /dev/xvdg

   Physical volume "/dev/xvdg" successfully created.
   Volume group "docker" successfully extended
   ```

3. Extend the `docker/thinpool` logical volume. This command uses 100% of the volume right away, without auto-extend. To extend the metadata thinpool instead, use `docker/thinpool_tmeta`.

   ```console
   $ sudo lvextend -l+100%FREE -n docker/thinpool

   Size of logical volume docker/thinpool_tdata changed from 95.00 GiB (24319 extents) to 198.00 GiB (50688 extents).
   Logical volume docker/thinpool_tdata successfully resized.
   ```

4. Verify the new thin pool size using the `Data Space Available` field in the output of `docker info`. If you extended the `docker/thinpool_tmeta` logical volume instead, look for `Metadata Space Available`.

   ```bash
   Storage Driver: devicemapper
    Pool Name: docker-thinpool
    Pool Blocksize: 524.3 kB
    Base Device Size: 10.74 GB
    Backing Filesystem: xfs
    Data file:
    Metadata file:
    Data Space Used: 212.3 MB
    Data Space Total: 212.6 GB
    Data Space Available: 212.4 GB
    Metadata Space Used: 286.7 kB
    Metadata Space Total: 1.07 GB
    Metadata Space Available: 1.069 GB
   <...>
   ```

### [Activate the `devicemapper` after reboot](#activate-the-devicemapper-after-reboot)

If you reboot the host and find that the `docker` service failed to start, look for the error, "Non existing device". You need to re-activate the logical volumes with this command:

```console
$ sudo lvchange -ay docker/thinpool
```

## [How the `devicemapper` storage driver works](#how-the-devicemapper-storage-driver-works)

> Warning
>
> Do not directly manipulate any files or directories within `/var/lib/docker/`. These files and directories are managed by Docker.

Use the `lsblk` command to see the devices and their pools, from the operating system's point of view:

```console
$ sudo lsblk

NAME                    MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
xvda                    202:0    0    8G  0 disk
└─xvda1                 202:1    0    8G  0 part /
xvdf                    202:80   0  100G  0 disk
├─docker-thinpool_tmeta 253:0    0 1020M  0 lvm
│ └─docker-thinpool     253:2    0   95G  0 lvm
└─docker-thinpool_tdata 253:1    0   95G  0 lvm
  └─docker-thinpool     253:2    0   95G  0 lvm
```

Use the `mount` command to see the mount-point Docker is using:

```console
$ mount |grep devicemapper
/dev/xvda1 on /var/lib/docker/devicemapper type xfs (rw,relatime,seclabel,attr2,inode64,noquota)
```

When you use `devicemapper`, Docker stores image and layer contents in the thinpool, and exposes them to containers by mounting them under subdirectories of `/var/lib/docker/devicemapper/`.

### [Image and container layers on-disk](#image-and-container-layers-on-disk)

The `/var/lib/docker/devicemapper/metadata/` directory contains metadata about the Devicemapper configuration itself and about each image and container layer that exist. The `devicemapper` storage driver uses snapshots, and this metadata include information about those snapshots. These files are in JSON format.

The `/var/lib/docker/devicemapper/mnt/` directory contains a mount point for each image and container layer that exists. Image layer mount points are empty, but a container's mount point shows the container's filesystem as it appears from within the container.

### [Image layering and sharing](#image-layering-and-sharing)

The `devicemapper` storage driver uses dedicated block devices rather than formatted filesystems, and operates on files at the block level for maximum performance during copy-on-write (CoW) operations.

#### [Snapshots](#snapshots)

Another feature of `devicemapper` is its use of snapshots (also sometimes called *thin devices* or *virtual devices*), which store the differences introduced in each layer as very small, lightweight thin pools. Snapshots provide many benefits:

* Layers which are shared in common between containers are only stored on disk once, unless they are writable. For instance, if you have 10 different images which are all based on `alpine`, the `alpine` image and all its parent images are only stored once each on disk.

* Snapshots are an implementation of a copy-on-write (CoW) strategy. This means that a given file or directory is only copied to the container's writable layer when it is modified or deleted by that container.

* Because `devicemapper` operates at the block level, multiple blocks in a writable layer can be modified simultaneously.

* Snapshots can be backed up using standard OS-level backup utilities. Just make a copy of `/var/lib/docker/devicemapper/`.

#### [Devicemapper workflow](#devicemapper-workflow)

When you start Docker with the `devicemapper` storage driver, all objects related to image and container layers are stored in `/var/lib/docker/devicemapper/`, which is backed by one or more block-level devices, either loopback devices (testing only) or physical disks.

* The *base device* is the lowest-level object. This is the thin pool itself. You can examine it using `docker info`. It contains a filesystem. This base device is the starting point for every image and container layer. The base device is a Device Mapper implementation detail, rather than a Docker layer.

* Metadata about the base device and each image or container layer is stored in `/var/lib/docker/devicemapper/metadata/` in JSON format. These layers are copy-on-write snapshots, which means that they are empty until they diverge from their parent layers.

* Each container's writable layer is mounted on a mountpoint in `/var/lib/docker/devicemapper/mnt/`. An empty directory exists for each read-only image layer and each stopped container.

Each image layer is a snapshot of the layer below it. The lowest layer of each image is a snapshot of the base device that exists in the pool. When you run a container, it is a snapshot of the image the container is based on. The following example shows a Docker host with two running containers. The first is a `ubuntu` container and the second is a `busybox` container.

## [How container reads and writes work with `devicemapper`](#how-container-reads-and-writes-work-with-devicemapper)

### [Reading files](#reading-files)

With `devicemapper`, reads happen at the block level. The diagram below shows the high level process for reading a single block (`0x44f`) in an example container.

An application makes a read request for block `0x44f` in the container. Because the container is a thin snapshot of an image, it doesn't have the block, but it has a pointer to the block on the nearest parent image where it does exist, and it reads the block from there. The block now exists in the container's memory.

### [Writing files](#writing-files)

**Writing a new file**: With the `devicemapper` driver, writing new data to a container is accomplished by an *allocate-on-demand* operation. Each block of the new file is allocated in the container's writable layer and the block is written there.

**Updating an existing file**: The relevant block of the file is read from the nearest layer where it exists. When the container writes the file, only the modified blocks are written to the container's writable layer.

**Deleting a file or directory**: When you delete a file or directory in a container's writable layer, or when an image layer deletes a file that exists in its parent layer, the `devicemapper` storage driver intercepts further read attempts on that file or directory and responds that the file or directory does not exist.

**Writing and then deleting a file**: If a container writes to a file and later deletes the file, all of those operations happen in the container's writable layer. In that case, if you are using `direct-lvm`, the blocks are freed. If you use `loop-lvm`, the blocks may not be freed. This is another reason not to use `loop-lvm` in production.

## [Device Mapper and Docker performance](#device-mapper-and-docker-performance)

* **`allocate-on demand` performance impact**:

  The `devicemapper` storage driver uses an `allocate-on-demand` operation to allocate new blocks from the thin pool into a container's writable layer. Each block is 64KB, so this is the minimum amount of space that is used for a write.

* **Copy-on-write performance impact**: The first time a container modifies a specific block, that block is written to the container's writable layer. Because these writes happen at the level of the block rather than the file, performance impact is minimized. However, writing a large number of blocks can still negatively impact performance, and the `devicemapper` storage driver may actually perform worse than other storage drivers in this scenario. For write-heavy workloads, you should use data volumes, which bypass the storage driver completely.

### [Performance best practices](#performance-best-practices)

Keep these things in mind to maximize performance when using the `devicemapper` storage driver.

* **Use `direct-lvm`**: The `loop-lvm` mode is not performant and should never be used in production.

* **Use fast storage**: Solid-state drives (SSDs) provide faster reads and writes than spinning disks.

* **Memory usage**: the `devicemapper` uses more memory than some other storage drivers. Each launched container loads one or more copies of its files into memory, depending on how many blocks of the same file are being modified at the same time. Due to the memory pressure, the `devicemapper` storage driver may not be the right choice for certain workloads in high-density use cases.

* **Use volumes for write-heavy workloads**: Volumes provide the best and most predictable performance for write-heavy workloads. This is because they bypass the storage driver and do not incur any of the potential overheads introduced by thin provisioning and copy-on-write. Volumes have other benefits, such as allowing you to share data among containers and persisting even when no running container is using them.

  > Note
  >
  > When using `devicemapper` and the `json-file` log driver, the log files generated by a container are still stored in Docker's dataroot directory, by default `/var/lib/docker`. If your containers generate lots of log messages, this may lead to increased disk usage or the inability to manage your system due to a full disk. You can configure a [log driver](https://docs.docker.com/engine/logging/configure/) to store your container logs externally.

## [Related Information](#related-information)

* [Volumes](https://docs.docker.com/engine/storage/volumes/)
* [Understand images, containers, and storage drivers](https://docs.docker.com/engine/storage/drivers/)
* [Select a storage driver](https://docs.docker.com/engine/storage/drivers/select-storage-driver/)

----
url: https://docs.docker.com/engine/swarm/swarm-tutorial/delete-service/
----

# Delete the service running on the swarm

***

***

The remaining steps in the tutorial don't use the `helloworld` service, so now you can delete the service from the swarm.

1. If you haven't already, open a terminal and ssh into the machine where you run your manager node. For example, the tutorial uses a machine named `manager1`.

2. Run `docker service rm helloworld` to remove the `helloworld` service.

   ```console
   $ docker service rm helloworld

   helloworld
   ```

3. Run `docker service inspect <SERVICE-ID>` to verify that the swarm manager removed the service. The CLI returns a message that the service is not found:

   ```console
   $ docker service inspect helloworld
   []
   Status: Error: no such service: helloworld, Code: 1
   ```

4. Even though the service no longer exists, the task containers take a few seconds to clean up. You can use `docker ps` on the nodes to verify when the tasks have been removed.

   ```console
   $ docker ps

   CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS     NAMES
   db1651f50347        alpine:latest       "ping docker.com"        44 minutes ago      Up 46 seconds                 helloworld.5.9lkmos2beppihw95vdwxy1j3w
   43bf6e532a92        alpine:latest       "ping docker.com"        44 minutes ago      Up 46 seconds                 helloworld.3.a71i8rp6fua79ad43ycocl4t2
   5a0fb65d8fa7        alpine:latest       "ping docker.com"        44 minutes ago      Up 45 seconds                 helloworld.2.2jpgensh7d935qdc857pxulfr
   afb0ba67076f        alpine:latest       "ping docker.com"        44 minutes ago      Up 46 seconds                 helloworld.4.1c47o7tluz7drve4vkm2m5olx
   688172d3bfaa        alpine:latest       "ping docker.com"        45 minutes ago      Up About a minute             helloworld.1.74nbhb3fhud8jfrhigd7s29we

   $ docker ps
   CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS     NAMES
   ```

## [Next steps](#next-steps)

Next, you'll set up a new service and apply a rolling update.

[Apply rolling updates](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/)

----
url: https://docs.docker.com/reference/cli/docker/container/exec/
----

# docker container exec

***

| Description                                                               | Execute a command in a running container                     |
| ------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Usage                                                                     | `docker container exec [OPTIONS] CONTAINER COMMAND [ARG...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker exec`                                                |

## [Description](#description)

The `docker exec` command runs a new command in a running container.

The command you specify with `docker exec` only runs while the container's primary process (`PID 1`) is running, and it isn't restarted if the container is restarted.

The command runs in the default working directory of the container.

The command must be an executable. A chained or a quoted command doesn't work.

* This works: `docker exec -it my_container sh -c "echo a && echo b"`
* This doesn't work: `docker exec -it my_container "echo a && echo b"`

## [Options](#options)

| Option                        | Default | Description                                            |
| ----------------------------- | ------- | ------------------------------------------------------ |
| `-d, --detach`                |         | Detached mode: run command in the background           |
| `--detach-keys`               |         | Override the key sequence for detaching a container    |
| [`-e, --env`](#env)           |         | API 1.25+ Set environment variables                    |
| `--env-file`                  |         | API 1.25+ Read in a file of environment variables      |
| `-i, --interactive`           |         | Keep STDIN open even if not attached                   |
| [`--privileged`](#privileged) |         | Give extended privileges to the command                |
| `-t, --tty`                   |         | Allocate a pseudo-TTY                                  |
| `-u, --user`                  |         | Username or UID (format: `<name\|uid>[:<group\|gid>]`) |
| [`-w, --workdir`](#workdir)   |         | API 1.35+ Working directory inside the container       |

## [Examples](#examples)

### [Run `docker exec` on a running container](#run-docker-exec-on-a-running-container)

First, start a container.

```console
$ docker run --name mycontainer -d -i -t alpine /bin/sh
```

This creates and starts a container named `mycontainer` from an `alpine` image with an `sh` shell as its main process. The `-d` option (shorthand for `--detach`) sets the container to run in the background, in detached mode, with a pseudo-TTY attached (`-t`). The `-i` option is set to keep `STDIN` attached (`-i`), which prevents the `sh` process from exiting immediately.

Next, execute a command on the container.

```console
$ docker exec -d mycontainer touch /tmp/execWorks
```

This creates a new file `/tmp/execWorks` inside the running container `mycontainer`, in the background.

Next, execute an interactive `sh` shell on the container.

```console
$ docker exec -it mycontainer sh
```

This starts a new shell session in the container `mycontainer`.

### [Set environment variables for the exec process (--env, -e)](#env)

Next, set environment variables in the current bash session.

The `docker exec` command inherits the environment variables that are set at the time the container is created. Use the `--env` (or the `-e` shorthand) to override global environment variables, or to set additional environment variables for the process started by `docker exec`.

The following example creates a new shell session in the container `mycontainer`, with environment variables `$VAR_A` set to `1`, and `$VAR_B` set to `2`. These environment variables are only valid for the `sh` process started by that `docker exec` command, and aren't available to other processes running inside the container.

```console
$ docker exec -e VAR_A=1 -e VAR_B=2 mycontainer env
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=f64a4851eb71
VAR_A=1
VAR_B=2
HOME=/root
```

### [Escalate container privileges (--privileged)](#privileged)

See [`docker run --privileged`](/reference/cli/docker/container/run/#privileged).

### [Set the working directory for the exec process (--workdir, -w)](#workdir)

By default `docker exec` command runs in the same working directory set when the container was created.

```console
$ docker exec -it mycontainer pwd
/
```

You can specify an alternative working directory for the command to execute using the `--workdir` option (or the `-w` shorthand):

```console
$ docker exec -it -w /root mycontainer pwd
/root
```

### [Try to run `docker exec` on a paused container](#try-to-run-docker-exec-on-a-paused-container)

If the container is paused, then the `docker exec` command fails with an error:

```console
$ docker pause mycontainer
mycontainer

$ docker ps

CONTAINER ID   IMAGE     COMMAND     CREATED          STATUS                   PORTS     NAMES
482efdf39fac   alpine    "/bin/sh"   17 seconds ago   Up 16 seconds (Paused)             mycontainer

$ docker exec mycontainer sh

Error response from daemon: Container mycontainer is paused, unpause the container before exec

$ echo $?
1
```

----
url: https://docs.docker.com/reference/cli/docker/dhi/mirror/stop/
----

# docker dhi mirror stop

***

| Description | Stop mirroring one or more Docker Hardened Images     |
| ----------- | ----------------------------------------------------- |
| Usage       | `docker dhi mirror stop <repository> [repository...]` |

## [Description](#description)

Stop mirroring one or more Docker Hardened Image repositories.

Multiple repositories can be specified as positional arguments.

Each repository can be specified as:

* namespace/name (e.g., myorg/dhi-python) - org must match --org flag or config
* name only (e.g., dhi-python) - the namespace can be omitted for simplicity and the command will default to the current org automatically

Examples:

# [Stop mirroring a single repository](#stop-mirroring-a-single-repository)

docker dhi mirror stop myorg/dhi-python --org myorg

# [Stop mirroring using just the name (defaults to current org)](#stop-mirroring-using-just-the-name-defaults-to-current-org)

docker dhi mirror stop dhi-python --org myorg

# [Stop mirroring multiple repositories](#stop-mirroring-multiple-repositories)

docker dhi mirror stop dhi-python dhi-golang dhi-node --org myorg

# [Stop mirroring and delete the repositories](#stop-mirroring-and-delete-the-repositories)

docker dhi mirror stop dhi-python dhi-golang --org myorg --delete

# [Stop mirroring, delete without confirmation prompt](#stop-mirroring-delete-without-confirmation-prompt)

docker dhi mirror stop dhi-python dhi-golang --org myorg --delete --force

# [Stop mirroring all repositories matching a filter (using shell substitution)](#stop-mirroring-all-repositories-matching-a-filter-using-shell-substitution)

docker dhi mirror stop $(docker dhi mirror list --org myorg --filter golang --json | jq -r '.\[].repository') --org myorg

## [Options](#options)

| Option        | Default | Description                                         |
| ------------- | ------- | --------------------------------------------------- |
| `--delete`    |         | Delete the repositories after stopping mirroring    |
| `-f, --force` |         | Skip confirmation prompt when deleting repositories |

----
url: https://docs.docker.com/get-started/docker-concepts/running-containers/overriding-container-defaults/
----

# Overriding container defaults

***

Table of contents

***

## [Explanation](#explanation)

When a Docker container starts, it executes an application or command. The container gets this executable (script or file) from its image’s configuration. Containers come with default settings that usually work well, but you can change them if needed. These adjustments help the container's program run exactly how you want it to.

For example, if you have an existing database container that listens on the standard port and you want to run a new instance of the same database container, then you might want to change the port settings the new container listens on so that it doesn’t conflict with the existing container. Sometimes you might want to increase the memory available to the container if the program needs more resources to handle a heavy workload or set the environment variables to provide specific configuration details the program needs to function properly.

The `docker run` command offers a powerful way to override these defaults and tailor the container's behavior to your liking. The command offers several flags that let you to customize container behavior on the fly.

Here's a few ways you can achieve this.

### [Overriding the network ports](#overriding-the-network-ports)

Sometimes you might want to use separate database instances for development and testing purposes. Running these database instances on the same port might conflict. You can use the `-p` option in `docker run` to map container ports to host ports, allowing you to run the multiple instances of the container without any conflict.

```console
$ docker run -d -p HOST_PORT:CONTAINER_PORT postgres
```

### [Setting environment variables](#setting-environment-variables)

This option sets an environment variable `foo` inside the container with the value `bar`.

```console
$ docker run -e foo=bar postgres env
```

You will see output like the following:

```console
HOSTNAME=2042f2e6ebe4
foo=bar
```

> Tip
>
> The `.env` file acts as a convenient way to set environment variables for your Docker containers without cluttering your command line with numerous `-e` flags. To use a `.env` file, you can pass `--env-file` option with the `docker run` command.
>
> ```console
> $ docker run --env-file .env postgres env
> ```

### [Restricting the container to consume the resources](#restricting-the-container-to-consume-the-resources)

You can use the `--memory` and `--cpus` flags with the `docker run` command to restrict how much CPU and memory a container can use. For example, you can set a memory limit for the Python API container, preventing it from consuming excessive resources on your host. Here's the command:

```console
$ docker run -e POSTGRES_PASSWORD=secret --memory="512m" --cpus="0.5" postgres
```

This command limits container memory usage to 512 MB and defines the CPU quota of 0.5 for half a core.

> **Monitor the real-time resource usage**
>
> You can use the `docker stats` command to monitor the real-time resource usage of running containers. This helps you understand whether the allocated resources are sufficient or need adjustment.

By effectively using these `docker run` flags, you can tailor your containerized application's behavior to fit your specific requirements.

## [Try it out](#try-it-out)

In this hands-on guide, you'll see how to use the `docker run` command to override the container defaults.

1. [Download and install](/get-started/get-docker/) Docker Desktop.

### [Run multiple instances of the Postgres database](#run-multiple-instances-of-the-postgres-database)

1. Start a container using the [Postgres image](https://hub.docker.com/_/postgres) with the following command:

   ```console
   $ docker run -d -e POSTGRES_PASSWORD=secret -p 5432:5432 postgres
   ```

   This will start the Postgres database in the background, listening on the standard container port `5432` and mapped to port `5432` on the host machine.

2. Start a second Postgres container mapped to a different port.

   ```console
   $ docker run -d -e POSTGRES_PASSWORD=secret -p 5433:5432 postgres
   ```

   This will start another Postgres container in the background, listening on the standard postgres port `5432` in the container, but mapped to port `5433` on the host machine. You override the host port just to ensure that this new container doesn't conflict with the existing running container.

3. Verify that both containers are running by going to the **Containers** view in the Docker Desktop Dashboard.

### [Run Postgres container in a controlled network](#run-postgres-container-in-a-controlled-network)

By default, containers automatically connect to a special network called a bridge network when you run them. This bridge network acts like a virtual bridge, allowing containers on the same host to communicate with each other while keeping them isolated from the outside world and other hosts. It's a convenient starting point for most container interactions. However, for specific scenarios, you might want more control over the network configuration.

Here's where the custom network comes in. You create a custom network by passing `--network` flag with the `docker run` command. All containers without a `--network` flag are attached to the default bridge network.

Follow the steps to see how to connect a Postgres container to a custom network.

1. Create a new custom network by using the following command:

   ```console
   $ docker network create mynetwork
   ```

2. Verify the network by running the following command:

   ```console
   $ docker network ls
   ```

   This command lists all networks, including the newly created "mynetwork".

3. Connect Postgres to the custom network by using the following command:

   ```console
   $ docker run -d -e POSTGRES_PASSWORD=secret -p 5434:5432 --network mynetwork postgres
   ```

   This will start Postgres container in the background, mapped to the host port 5434 and attached to the `mynetwork` network. You passed the `--network` parameter to override the container default by connecting the container to custom Docker network for better isolation and communication with other containers. You can use `docker network inspect` command to see if the container is tied to this new bridge network.

   > **Key difference between default bridge and custom networks**
   >
   > 1. DNS resolution: By default, containers connected to the default bridge network can communicate with each other, but only by IP address. (unless you use `--link` option which is considered legacy). It is not recommended for production use due to the various [technical shortcomings](/engine/network/drivers/bridge/#differences-between-user-defined-bridges-and-the-default-bridge). On a custom network, containers can resolve each other by name or alias.
   > 2. Isolation: All containers without a `--network` specified are attached to the default bridge network, hence can be a risk, as unrelated containers are then able to communicate. Using a custom network provides a scoped network in which only containers attached to that network are able to communicate, hence providing better isolation.

### [Manage the resources](#manage-the-resources)

By default, containers are not limited in their resource usage. However, on shared systems, it's crucial to manage resources effectively. It's important not to let a running container consume too much of the host machine's memory.

This is where the `docker run` command shines again. It offers flags like `--memory` and `--cpus` to restrict how much CPU and memory a container can use.

```console
$ docker run -d -e POSTGRES_PASSWORD=secret --memory="512m" --cpus=".5" postgres
```

The `--cpus` flag specifies the CPU quota for the container. Here, it's set to half a CPU core (0.5) whereas the `--memory` flag specifies the memory limit for the container. In this case, it's set to 512 MB.

### [Override the default CMD and ENTRYPOINT in Docker Compose](#override-the-default-cmd-and-entrypoint-in-docker-compose)

Sometimes, you might need to override the default commands (`CMD`) or entry points (`ENTRYPOINT`) defined in a Docker image, especially when using Docker Compose.

1. Create a `compose.yml` file with the following content:

   ```yaml
   services:
     postgres:
       image: postgres:18
       entrypoint: ["docker-entrypoint.sh", "postgres"]
       command: ["-h", "localhost", "-p", "5432"]
       environment:
         POSTGRES_PASSWORD: secret 
   ```

   The Compose file defines a service named `postgres` that uses the official Postgres image, sets an entrypoint script, and starts the container with password authentication.

2. Bring up the service by running the following command:

   ```console
   $ docker compose up -d
   ```

   This command starts the Postgres service defined in the Docker Compose file.

3. Verify the authentication with Docker Desktop Dashboard.

   Open the Docker Desktop Dashboard, select the **Postgres** container and select **Exec** to enter into the container shell. You can type the following command to connect to the Postgres database:

   ```console
   # psql -U postgres
   ```

   > Note
   >
   > The PostgreSQL image sets up trust authentication locally so you may notice a password isn't required when connecting from localhost (inside the same container). However, a password will be required if connecting from a different host/container.

### [Override the default CMD and ENTRYPOINT with `docker run`](#override-the-default-cmd-and-entrypoint-with-docker-run)

You can also override defaults directly using the `docker run` command with the following command:

```console
$ docker run -e POSTGRES_PASSWORD=secret postgres docker-entrypoint.sh -h localhost -p 5432
```

This command runs a Postgres container, sets an environment variable for password authentication, overrides the default startup commands and configures hostname and port mapping.

## [Additional resources](#additional-resources)

* [Ways to set environment variables with Compose](/compose/how-tos/environment-variables/set-environment-variables/)
* [What is a container](/get-started/docker-concepts/the-basics/what-is-a-container/)

## [Next steps](#next-steps)

Now that you have learned about overriding container defaults, it's time to learn how to persist container data.

[Persisting container data](https://docs.docker.com/get-started/docker-concepts/running-containers/persisting-container-data/)

----
url: https://docs.docker.com/build/ci/github-actions/secrets/
----

# Using secrets with GitHub Actions

***

Table of contents

***

A build secret is sensitive information, such as a password or API token, consumed as part of the build process. Docker Build supports two forms of secrets:

* [Secret mounts](#secret-mounts) add secrets as files in the build container (under `/run/secrets` by default).
* [SSH mounts](#ssh-mounts) add SSH agent sockets or keys into the build container.

This page shows how to use secrets with GitHub Actions. For an introduction to secrets in general, see [Build secrets](https://docs.docker.com/build/building/secrets/).

## [Secret mounts](#secret-mounts)

In the following example uses and exposes the [`GITHUB_TOKEN` secret](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret) as provided by GitHub in your workflow.

First, create a `Dockerfile` that uses the secret:

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN --mount=type=secret,id=github_token,env=GITHUB_TOKEN ...
```

In this example, the secret name is `github_token`. The following workflow exposes this secret using the `secrets` input:

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build
        uses: docker/build-push-action@v7
        with:
          platforms: linux/amd64,linux/arm64
          tags: user/app:latest
          secrets: |
            "github_token=${{ secrets.GITHUB_TOKEN }}"
```

> Note
>
> Secrets are mounted as files in the build container. By default, they're available at `/run/secrets/<id>`. You can also use the `env` option to load a secret into an environment variable, or the `target` option to customize the mount path. For details on secret mounts, see [Build secrets](https://docs.docker.com/build/building/secrets/).

### [Secret sources](#secret-sources)

The `docker/build-push-action` inputs for secret mounts define where the secret value comes from. The Dockerfile `RUN --mount=type=secret` options define how the build step consumes the secret.

| Action input                           | Source                             | Equivalent Buildx option                 |
| -------------------------------------- | ---------------------------------- | ---------------------------------------- |
| `secrets: MY_SECRET=value`             | Inline value from the workflow     | `--secret id=MY_SECRET,src=<temp-file>`  |
| `secret-envs: MY_SECRET=MY_ENV_VAR`    | Environment variable on the runner | `--secret id=MY_SECRET,env=MY_ENV_VAR`   |
| `secret-files: MY_SECRET=./secret.txt` | File on the runner                 | `--secret id=MY_SECRET,src=./secret.txt` |

For example, `RUN --mount=type=secret,id=MY_SECRET` mounts the secret as a file at `/run/secrets/MY_SECRET`. To expose the same secret as an environment variable for a `RUN` instruction, use the `env` option in the Dockerfile: `RUN --mount=type=secret,id=MY_SECRET,env=MY_SECRET`.

### [Using environment variables as secret sources](#using-environment-variables-as-secret-sources)

The `secret-envs` input reads secrets from environment variables on the GitHub Actions runner. Use it when a previous workflow step sets an environment variable, or when you want to map a runner environment variable to a different secret ID for the build.

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build
        uses: docker/build-push-action@v7
        env:
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
        with:
          context: .
          secret-envs: |
            sentry_token=SENTRY_AUTH_TOKEN
          tags: user/app:latest
```

In your Dockerfile, mount the secret and expose it as an environment variable for the command that needs it:

```dockerfile
# syntax=docker/dockerfile:1
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

RUN --mount=type=secret,id=sentry_token,env=SENTRY_AUTH_TOKEN \
    npm run build
```

### [Using secret files](#using-secret-files)

The `secret-files` input lets you mount existing files as secrets in your build. This is useful when you need to use credential files that are generated during your workflow, or when you need to mount configuration files like `.npmrc` or `.pypirc` that are already in the expected format.

The key difference between `secrets`, `secret-envs`, and `secret-files`:

* `secrets`: Pass secret values as strings from the workflow.
* `secret-envs`: Read secret values from environment variables on the runner.
* `secret-files`: Mount existing files from the runner's filesystem.

#### [Example: Using .npmrc for private npm packages](#example-using-npmrc-for-private-npm-packages)

If your build needs to install packages from a private npm registry, you can create an `.npmrc` file and mount it as a secret:

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Create .npmrc file
        run: |
          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc

      - name: Build
        uses: docker/build-push-action@v7
        with:
          context: .
          secret-files: |
            npmrc=./.npmrc
          tags: user/app:latest
```

In your Dockerfile, mount the secret file to the expected location:

```dockerfile
# syntax=docker/dockerfile:1
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci

COPY . .

RUN npm run build
```

If a `RUN` instruction uses a non-root user, set `uid`, `gid`, or `mode` on the secret mount so the user can read the mounted file:

```dockerfile
RUN --mount=type=secret,id=npmrc,target=/home/node/.npmrc,uid=1000,gid=1000 \
    npm ci
```

#### [Example: Using dynamically generated credentials](#example-using-dynamically-generated-credentials)

You can generate credential files from multiple secrets and mount them:

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Create credentials file
        run: |
          cat <<EOF > aws-credentials
          [default]
          aws_access_key_id = ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws_secret_access_key = ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          EOF

      - name: Build
        uses: docker/build-push-action@v7
        with:
          context: .
          secret-files: |
            aws=./aws-credentials
          tags: user/app:latest
```

In your Dockerfile:

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine

RUN apk add --no-cache aws-cli

RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
    aws s3 cp s3://my-private-bucket/data.tar.gz /tmp/
```

### [Multi-line secrets](#multi-line-secrets)

If you're using [GitHub secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) and need to handle multi-line value, you will need to place the key-value pair between quotes:

```yaml
secrets: |
  "MYSECRET=${{ secrets.GPG_KEY }}"
  GIT_AUTH_TOKEN=abcdefghi,jklmno=0123456789
  "MYSECRET=aaaaaaaa
  bbbbbbb
  ccccccccc"
  FOO=bar
  "EMPTYLINE=aaaa

  bbbb
  ccc"
  "JSON_SECRET={""key1"":""value1"",""key2"":""value2""}"
```

| Key              | Value                               |
| ---------------- | ----------------------------------- |
| `MYSECRET`       | `***********************`           |
| `GIT_AUTH_TOKEN` | `abcdefghi,jklmno=0123456789`       |
| `MYSECRET`       | `aaaaaaaa\nbbbbbbb\nccccccccc`      |
| `FOO`            | `bar`                               |
| `EMPTYLINE`      | `aaaa\n\nbbbb\nccc`                 |
| `JSON_SECRET`    | `{"key1":"value1","key2":"value2"}` |

> Note
>
> Double escapes are needed for quote signs.

## [SSH mounts](#ssh-mounts)

SSH mounts let you authenticate with SSH servers. For example to perform a `git clone`, or to fetch application packages from a private repository.

The following Dockerfile example uses an SSH mount to fetch Go modules from a private GitHub repository.

```dockerfile
# syntax=docker/dockerfile:1

ARG GO_VERSION="1.25"

FROM golang:${GO_VERSION}-alpine AS base
ENV CGO_ENABLED=0
ENV GOPRIVATE="github.com/foo/*"
RUN apk add --no-cache file git rsync openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts
WORKDIR /src

FROM base AS vendor
# this step configure git and checks the ssh key is loaded
RUN --mount=type=ssh <<EOT
  set -e
  echo "Setting Git SSH protocol"
  git config --global url."git@github.com:".insteadOf "https://github.com/"
  (
    set +e
    ssh -T git@github.com
    if [ ! "$?" = "1" ]; then
      echo "No GitHub SSH key loaded exiting..."
      exit 1
    fi
  )
EOT
# this one download go modules
RUN --mount=type=bind,target=. \
    --mount=type=cache,target=/go/pkg/mod \
    --mount=type=ssh \
    go mod download -x

FROM vendor AS build
RUN --mount=type=bind,target=. \
    --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache \
    go build ...
```

To build this Dockerfile, you must specify an SSH mount that the builder can use in the steps with `--mount=type=ssh`.

The following GitHub Action workflow uses the `MrSquaare/ssh-setup-action` third-party action to bootstrap SSH setup on the GitHub runner. The action creates a private key defined by the GitHub Action secret `SSH_GITHUB_PPK` and adds it to the SSH agent socket file at `SSH_AUTH_SOCK`. The SSH mount in the build step assume `SSH_AUTH_SOCK` by default, so there's no need to specify the ID or path for the SSH agent socket explicitly.

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up SSH
        uses: MrSquaare/ssh-setup-action@2d028b70b5e397cf8314c6eaea229a6c3e34977a # v3.1.0
        with:
          host: github.com
          private-key: ${{ secrets.SSH_GITHUB_PPK }}
          private-key-name: github-ppk

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          ssh: default
          push: true
          tags: user/app:latest
```

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up SSH
        uses: MrSquaare/ssh-setup-action@2d028b70b5e397cf8314c6eaea229a6c3e34977a # v3.1.0
        with:
          host: github.com
          private-key: ${{ secrets.SSH_GITHUB_PPK }}
          private-key-name: github-ppk

      - name: Build
        uses: docker/bake-action@v7
        with:
          set: |
            *.ssh=default
```

----
url: https://docs.docker.com/guides/language-translation/
----

[Build a language translation app](https://docs.docker.com/guides/language-translation/)

This guide demonstrates how to use Docker to deploy language translation models for NLP tasks.

Python AI

20 minutes

[« Back to all guides](/guides/)

# Build a language translation app

***

Table of contents

***

## [Overview](#overview)

This guide walks you through building and running a language translation application. You'll build the application using Python with Googletrans, and then set up the environment and run the application using Docker.

The application demonstrates a simple but practical use of the Googletrans library for language translation, showcasing basic Python and Docker concepts. Googletrans is a free and unlimited Python library that implements the Google Translate API. It uses the Google Translate Ajax API to make calls to such methods as detect and translate.

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop.
* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Get the sample application](#get-the-sample-application)

1. Open a terminal, and clone the sample application's repository using the following command.

   ```console
   $ git clone https://github.com/harsh4870/Docker-NLP.git
   ```

2. Verify that you cloned the repository.

   You should see the following files in your `Docker-NLP` directory.

   ```text
   01_sentiment_analysis.py
   02_name_entity_recognition.py
   03_text_classification.py
   04_text_summarization.py
   05_language_translation.py
   entrypoint.sh
   requirements.txt
   Dockerfile
   README.md
   ```

## [Explore the application code](#explore-the-application-code)

The source code for the application is in the `Docker-NLP/05_language_translation.py` file. Open `05_language_translation.py` in a text or code editor to explore its contents in the following steps.

1. Import the required libraries.

   ```python
   from googletrans import Translator
   ```

   This line imports the `Translator` class from `googletrans`. Googletrans is a Python library that provides an interface to Google Translate's AJAX API.

2. Specify the main execution block.

   ```python
   if __name__ == "__main__":
   ```

   This Python idiom ensures that the following code block runs only if this script is the main program. It provides flexibility, allowing the script to function both as a standalone program and as an imported module.

3. Create an infinite loop for continuous input.

   ```python
      while True:
         input_text = input("Enter the text for translation (type 'exit' to end): ")

         if input_text.lower() == 'exit':
            print("Exiting...")
            break
   ```

   An infinite loop is established here to continuously prompt you for text input, ensuring interactivity. The loop breaks when you type `exit`, allowing you to control the application flow effectively.

4. Create an instance of Translator.

   ```python
         translator = Translator()
   ```

   This creates an instance of the Translator class, which performs the translation.

5. Translate text.

   ```python
         translated_text = translator.translate(input_text, dest='fr').text
   ```

   Here, the `translator.translate` method is called with the user input. The `dest='fr'` argument specifies that the destination language for translation is French. The `.text` attribute gets the translated string. For more details about the available language codes, see the [Googletrans docs](https://py-googletrans.readthedocs.io/en/latest/).

6. Print the original and translated text.

   ```python
         print(f"Original Text: {input_text}")
         print(f"Translated Text: {translated_text}")
   ```

   These two lines print the original text entered by the user and the translated text.

7. Create `requirements.txt`. The sample application already contains the `requirements.txt` file to specify the necessary modules that the application imports. Open `requirements.txt` in a code or text editor to explore its contents.

   ```text
   ...

   # 05 language_translation
   googletrans==4.0.0-rc1
   ```

   Only `googletrans` is required for the language translation application.

## [Explore the application environment](#explore-the-application-environment)

You'll use Docker to run the application in a container. Docker lets you containerize the application, providing a consistent and isolated environment for running it. This means the application will operate as intended within its Docker container, regardless of the underlying system differences.

To run the application in a container, a Dockerfile is required. A Dockerfile is a text document that contains all the commands you would call on the command line to assemble an image. An image is a read-only template with instructions for creating a Docker container.

The sample application already contains a `Dockerfile`. Open the `Dockerfile` in a code or text editor to explore its contents.

The following steps explain each part of the `Dockerfile`. For more details, see the [Dockerfile reference](/reference/dockerfile/).

1. Specify the base image.

   ```dockerfile
   FROM python:3.8-slim
   ```

   This command sets the foundation for the build. `python:3.8-slim` is a lightweight version of the Python 3.8 image, optimized for size and speed. Using this slim image reduces the overall size of your Docker image, leading to quicker downloads and less surface area for security vulnerabilities. This is particularly useful for a Python-based application where you might not need the full standard Python image.

2. Set the working directory.

   ```dockerfile
   WORKDIR /app
   ```

   `WORKDIR` sets the current working directory within the Docker image. By setting it to `/app`, you ensure that all subsequent commands in the Dockerfile (like `COPY` and `RUN`) are executed in this directory. This also helps in organizing your Docker image, as all application-related files are contained in a specific directory.

3. Copy the requirements file into the image.

   ```dockerfile
   COPY requirements.txt /app
   ```

   The `COPY` command transfers the `requirements.txt` file from your local machine into the Docker image. This file lists all Python dependencies required by the application. Copying it into the container lets the next command (`RUN pip install`) install these dependencies inside the image environment.

4. Install the Python dependencies in the image.

   ```dockerfile
   RUN pip install --no-cache-dir -r requirements.txt
   ```

   This line uses `pip`, Python's package installer, to install the packages listed in `requirements.txt`. The `--no-cache-dir` option disables the cache, which reduces the size of the Docker image by not storing the unnecessary cache data.

5. Run additional commands.

   ```dockerfile
   RUN python -m spacy download en_core_web_sm
   ```

   This step is specific to NLP applications that require the spaCy library. It downloads the `en_core_web_sm` model, which is a small English language model for spaCy. While not needed for this app, it's included for compatibility with other NLP applications that might use this Dockerfile.

6. Copy the application code into the image.

   ```dockerfile
   COPY *.py /app
   COPY entrypoint.sh /app
   ```

   These commands copy your Python scripts and the `entrypoint.sh` script into the image's `/app` directory. This is crucial because the container needs these scripts to run the application. The `entrypoint.sh` script is particularly important as it dictates how the application starts inside the container.

7. Set permissions for the `entrypoint.sh` script.

   ```dockerfile
   RUN chmod +x /app/entrypoint.sh
   ```

   This command modifies the file permissions of `entrypoint.sh`, making it executable. This step is necessary to ensure that the Docker container can run this script to start the application.

8. Set the entry point.

   ```dockerfile
   ENTRYPOINT ["/app/entrypoint.sh"]
   ```

   The `ENTRYPOINT` instruction configures the container to run `entrypoint.sh` as its default executable. This means that when the container starts, it automatically executes the script.

   You can explore the `entrypoint.sh` script by opening it in a code or text editor. As the sample contains several applications, the script lets you specify which application to run when the container starts.

## [Run the application](#run-the-application)

To run the application using Docker:

1. Build the image.

   In a terminal, run the following command inside the directory of where the `Dockerfile` is located.

   ```console
   $ docker build -t basic-nlp .
   ```

   ```console
   $ docker run -it basic-nlp 05_language_translation.py
   ```

   The following is a break down of the command:

   * `docker run`: This is the primary command used to run a new container from a Docker image.

   * `-it`: This is a combination of two options:

     * `-i` or `--interactive`: This keeps the standard input (STDIN) open even if not attached. It lets the container remain running in the foreground and be interactive.
     * `-t` or `--tty`: This allocates a pseudo-TTY, essentially simulating a terminal, like a command prompt or a shell. It's what lets you interact with the application inside the container.

   * `basic-nlp`: This specifies the name of the Docker image to use for creating the container. In this case, it's the image named `basic-nlp` that you created with the `docker build` command.

   * `05_language_translation.py`: This is the script you want to run inside the Docker container. It gets passed to the `entrypoint.sh` script, which runs it when the container starts.

   For more details, see the [docker run CLI reference](/reference/cli/docker/container/run/).

   > Note
   >
   > For Windows users, you may get an error when running the container. Verify that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), then rebuild the image. For more details, see \[Avoid unexpected syntax errors, use Unix style line endings for files in containers]\(/desktop/troubleshoot-and-support/troubleshoot/topics/#Unexpected-syntax-errors-use-Unix-style-line endings-for-files-in-containers).

   You will see the following in your console after the container starts.

   ```console
   Enter the text for translation (type 'exit' to end):
   ```

3. Test the application.

   Enter some text to get the text summarization.

   ```console
   Enter the text for translation (type 'exit' to end): Hello, how are you doing?
   Original Text: Hello, how are you doing?
   Translated Text: Bonjour comment allez-vous?
   ```

## [Summary](#summary)

In this guide, you learned how to build and run a language translation application. You learned how to build the application using Python with Googletrans, and then set up the environment and run the application using Docker.

Related information:

* [Docker CLI reference](/reference/cli/docker/)
* [Dockerfile reference](/reference/dockerfile/)
* [Googletrans](https://github.com/ssut/py-googletrans)
* [Python documentation](https://docs.python.org/3/)

## [Next steps](#next-steps)

Explore more [natural language processing guides](https://docs.docker.com/guides/).

----
url: https://docs.docker.com/reference/api/extensions-sdk/ExecProcess/
----

# Interface: ExecProcess

***

Table of contents

***

**`Since`**

0.2.3

## [Methods](#methods)

### [close](#close)

▸ **close**(): `void`

Close the process started by exec(streamingOptions)

#### [Returns](#returns)

`void`

----
url: https://docs.docker.com/reference/samples/minecraft/
----

# Minecraft samples

| Name                                                                                | Description                |
| ----------------------------------------------------------------------------------- | -------------------------- |
| [Minecraft server](https://github.com/docker/awesome-compose/tree/master/minecraft) | A sample Minecraft server. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/docker-hub/repos/manage/trusted-content/official-images/
----

# Docker Official Images

***

Table of contents

***

> Note
>
> Docker is retiring Docker Content Trust (DCT) for Docker Official Images (DOI). You should start planning to transition to a different image signing and verification solution (like [Sigstore](https://www.sigstore.dev/) or [Notation](https://github.com/notaryproject/notation#readme)). Docker will publish migration guides soon to help you in that effort. Timelines for the complete deprecation of DCT are being finalized and will be published soon.
>
> For more details, see <https://www.docker.com/blog/retiring-docker-content-trust/>.

Docker, Inc. sponsors a dedicated team that's responsible for reviewing and publishing all content in Docker Official Images. This team works in collaboration with upstream software maintainers, security experts, and the broader Docker community.

While it's preferable to have upstream software authors maintaining their Docker Official Images, this isn't a strict requirement. Creating and maintaining images for Docker Official Images is a collaborative process. It takes place [openly on GitHub](https://github.com/docker-library/official-images) where participation is encouraged. Anyone can provide feedback, contribute code, suggest process changes, or even propose a new Official Image.

## [Creating a Docker Official Image](#creating-a-docker-official-image)

From a high level, an Official Image starts out as a proposal in the form of a set of GitHub pull requests. The following GitHub repositories detail the proposal requirements:

* [Docker Official Images repository on GitHub](https://github.com/docker-library/official-images#readme)
* [Documentation for Docker Official Images](https://github.com/docker-library/docs#readme)

The Docker Official Images team, with help from community contributors, formally review each proposal and provide feedback to the author. This initial review process can be lengthy, often requiring a bit of back-and-forth before the proposal is accepted.

There are subjective considerations during the review process. These subjective concerns boil down to the basic question: "is this image generally useful?" For example, the [Python](https://hub.docker.com/_/python/) Docker Official Image is "generally useful" to the larger Python developer community, whereas an obscure text adventure game written in Python last week is not.

Once a new proposal is accepted, the author is responsible for keeping their images and documentation up-to-date and responding to user feedback. Docker is responsible for building and publishing the images on Docker Hub. Updates to Docker Official Images follow the same pull request process as for new images, although the review process for updates is more streamlined. The Docker Official Images team ultimately acts as a gatekeeper for all changes, which helps ensures consistency, quality, and security.

## [Submitting feedback for Docker Official Images](#submitting-feedback-for-docker-official-images)

All Docker Official Images contain a **User Feedback** section in their documentation which covers the details for that specific repository. In most cases, the GitHub repository which contains the Dockerfiles for an Official Image also has an active issue tracker.

General feedback and support questions about Docker Official Images should be directed to the `#general` channel in the [Docker Community Slack](https://dockr.ly/comm-slack).

If you're a maintainer or contributor to Docker Official Images and you're looking for help or advice, use the `#docker-library` channel on [Libera.Chat IRC](https://libera.chat).

----
url: https://docs.docker.com/ai/model-runner/get-started/
----

# Get started with DMR

***

Table of contents

***

Docker Model Runner (DMR) lets you run and manage AI models locally using Docker. This page shows you how to enable DMR, pull and run a model, configure model settings, and publish custom models.

## [Enable Docker Model Runner](#enable-docker-model-runner)

You can enable DMR using Docker Desktop or Docker Engine. Follow the instructions below based on your setup.

### [Docker Desktop](#docker-desktop)

1. In the settings view, go to the **AI** tab.

2. Select the **Enable Docker Model Runner** setting.

3. If you use Windows with a supported NVIDIA GPU, you also see and can select **Enable GPU-backed inference**.

4. Optional: To enable TCP support, select **Enable host-side TCP support**.

   1. In the **Port** field, type the port you want to use.
   2. If you interact with Model Runner from a local frontend web app, in **CORS Allows Origins**, select the origins that Model Runner should accept requests from. An origin is the URL where your web app runs, for example `http://localhost:3131`.

You can now use the `docker model` command in the CLI and view and interact with your local models in the **Models** tab in the Docker Desktop Dashboard.

### [Docker Engine](#docker-engine)

1. Ensure you have installed [Docker Engine](/engine/install/).

2. Docker Model Runner is available as a package. To install it, run:

   ```bash
   $ sudo apt-get update
   $ sudo apt-get install docker-model-plugin
   ```

   ```bash
   $ sudo dnf update
   $ sudo dnf install docker-model-plugin
   ```

3. Test the installation:

   ```bash
   $ docker model version
   $ docker model run ai/smollm2
   ```

> Note
>
> TCP support is enabled by default for Docker Engine on port `12434`.

### [Update DMR in Docker Engine](#update-dmr-in-docker-engine)

To update Docker Model Runner in Docker Engine, uninstall it with [`docker model uninstall-runner`](/reference/cli/docker/model/uninstall-runner/) then reinstall it:

```bash
docker model uninstall-runner --images && docker model install-runner
```

> Note
>
> With the above command, local models are preserved. To delete the models during the upgrade, add the `--models` option to the `uninstall-runner` command.

## [Pull a model](#pull-a-model)

Models are cached locally.

> Note
>
> When you use the Docker CLI, you can also pull models directly from [HuggingFace](https://huggingface.co/).

1. Select **Models** and select the **Docker Hub** tab.
2. Find the model you want and select **Pull**.

Use the [`docker model pull` command](/reference/cli/docker/model/pull/). For example:

Pulling from Docker Hub

```bash
docker model pull ai/smollm2:360M-Q4_K_M
```

Pulling from HuggingFace

```bash
docker model pull hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF
```

## [Run a model](#run-a-model)

1. Select **Models** and select the **Local** tab.
2. Select the play button. The interactive chat screen opens.

Use the [`docker model run` command](/reference/cli/docker/model/run/).

## [Configure a model](#configure-a-model)

You can configure a model, such as its maximum token limit and more, use Docker Compose. See [Models and Compose - Model configuration options](https://docs.docker.com/ai/compose/models-and-compose/#model-configuration-options).

## [Publish a model](#publish-a-model)

> Note
>
> This works for any Container Registry supporting OCI Artifacts, not only Docker Hub.

You can tag existing models with a new name and publish them under a different namespace and repository:

```bash
# Tag a pulled model under a new name
$ docker model tag ai/smollm2 myorg/smollm2

# Push it to Docker Hub
$ docker model push myorg/smollm2
```

For more details, see the [`docker model tag`](/reference/cli/docker/model/tag) and [`docker model push`](/reference/cli/docker/model/push) command documentation.

You can also package a model file in GGUF format as an OCI Artifact and publish it to Docker Hub.

```bash
# Download a model file in GGUF format, for example from HuggingFace
$ curl -L -o model.gguf https://huggingface.co/TheBloke/Mistral-7B-v0.1-GGUF/resolve/main/mistral-7b-v0.1.Q4_K_M.gguf

# Package it as OCI Artifact and push it to Docker Hub
$ docker model package --gguf "$(pwd)/model.gguf" --push myorg/mistral-7b-v0.1:Q4_K_M
```

For more details, see the [`docker model package`](/reference/cli/docker/model/package/) command documentation.

## [Troubleshooting](#troubleshooting)

### [Display the logs](#display-the-logs)

To troubleshoot issues, display the logs:

Select **Models** and select the **Logs** tab.

Use the [`docker model logs` command](/reference/cli/docker/model/logs/).

### [Inspect requests and responses](#inspect-requests-and-responses)

Inspecting requests and responses helps you diagnose model-related issues. For example, you can evaluate context usage to verify you stay within the model's context window or display the full body of a request to control the parameters you are passing to your models when developing with a framework.

In Docker Desktop, to inspect the requests and responses for each model:

1. Select **Models** and select the **Requests** tab. This view displays all the requests to all models:

   * The time the request was sent.
   * The model name and version
   * The prompt/request
   * The context usage
   * The time it took for the response to be generated.

2. Select one of the requests to display further details:

   * In the **Overview** tab, view the token usage, response metadata and generation speed, and the actual prompt and response.
   * In the **Request** and **Response** tabs, view the full JSON payload of the request and the response.

> Note
>
> You can also display the requests for a specific model when you select a model and then select the **Requests** tab.

## [Related pages](#related-pages)

* [API reference](https://docs.docker.com/ai/model-runner/api-reference/) - OpenAI and Ollama-compatible API documentation
* [Configuration options](https://docs.docker.com/ai/model-runner/configuration/) - Context size and runtime parameters
* [Inference engines](https://docs.docker.com/ai/model-runner/inference-engines/) - llama.cpp and vLLM details
* [IDE integrations](https://docs.docker.com/ai/model-runner/ide-integrations/) - Connect Cline, Continue, Cursor, and more
* [Open WebUI integration](https://docs.docker.com/ai/model-runner/openwebui-integration/) - Set up a web chat interface
* [Models and Compose](https://docs.docker.com/ai/compose/models-and-compose/) - Use models in Compose applications
* [Docker Model Runner CLI reference](/reference/cli/docker/model) - Complete CLI documentation

----
url: https://docs.docker.com/ai/sandboxes/security/isolation/
----

# Isolation layers

***

Table of contents

***

AI coding agents need to execute code, install packages, and run tools on your behalf. Docker Sandboxes run each agent in its own microVM. Five isolation layers protect your host: hypervisor, network, Docker Engine, workspace, and credential proxy.

## [Hypervisor isolation](#hypervisor-isolation)

Every sandbox runs inside a lightweight microVM with its own Linux kernel. Unlike containers, which share the host kernel, a sandbox VM cannot access host processes, files, or resources outside its defined boundaries.

* **Process isolation:** separate kernel per sandbox; processes inside the VM are invisible to your host and to other sandboxes
* **Filesystem isolation:** only your workspace directory is shared with the host. The rest of the VM filesystem persists across restarts but is removed when you delete the sandbox. Symlinks pointing outside the workspace scope are not followed.
* **Full cleanup:** when you remove a sandbox with `sbx rm`, the VM and everything inside it is deleted

The agent runs as a non-root user with sudo privileges inside the VM. The hypervisor boundary is the isolation control, not in-VM privilege separation.

## [Network isolation](#network-isolation)

Each sandbox has its own isolated network. Sandboxes cannot communicate with each other and cannot reach your host's localhost. There is no shared network between sandboxes or between a sandbox and your host.

All HTTP and HTTPS traffic leaving a sandbox passes through a proxy on your host that enforces the [network policy](https://docs.docker.com/ai/sandboxes/security/policy/). The sandbox routes traffic through either a forward proxy or a transparent proxy depending on the client's configuration. Both enforce the network policy; only the forward proxy [injects credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for AI services.

Raw TCP connections, UDP, and ICMP are blocked at the network layer. DNS resolution is handled by the proxy; the sandbox cannot make raw DNS queries. Traffic to private IP ranges, loopback, and link-local addresses is also blocked. Only domains explicitly listed in the policy are reachable.

For the default set of allowed domains, see [Default security posture](https://docs.docker.com/ai/sandboxes/security/defaults/).

## [Docker Engine isolation](#docker-engine-isolation)

Agents often need to build images, run containers, and use Docker Compose. Mounting your host Docker socket into a container would give the agent full access to your environment.

Docker Sandboxes avoid this by running a separate [Docker Engine](https://docs.docker.com/engine/) inside the sandbox environment, isolated from your host. When the agent runs `docker build` or `docker compose up`, those commands execute against that engine. The agent has no path to your host Docker daemon.

Each sandbox VM runs its own Docker Engine. The agent runs inside the VM, alongside that engine, and drives it to create containers, all within the VM:

```
```

## [Workspace isolation](#workspace-isolation)

When you create a sandbox, you choose one of two ways to share your workspace with it:

* **Direct mount** (the default): the agent has read-write access to your working tree. There is no boundary between the agent's edits and your host filesystem.
* **Clone mode** (`--clone`): your repository is mounted read-only into the VM and the agent works on a private clone inside the VM. The agent's edits never reach your host until you fetch them.

See [Git workflow](https://docs.docker.com/ai/sandboxes/usage/#git-workflow) for the workflow side of each.

### [Direct mount (default)](#direct-mount-default)

By default, your workspace is shared into the VM as a read-write mount. The agent and the host see the same files, and changes the agent makes appear on your host as soon as they're written.

There is no isolation between the agent and your workspace in this mode. The agent can create, modify, or delete any file in the workspace, including:

* Source code and configuration files
* Build files (`Makefile`, `package.json`, `Cargo.toml`)
* Git hooks (`.git/hooks/`)
* CI configuration (`.github/workflows/`, `.gitlab-ci.yml`)
* IDE configuration (`.vscode/tasks.json`, `.idea/` run configurations)
* Hidden files, shell scripts, and executables

Some of these files execute code when you trigger normal development actions — committing, pushing, building, or opening the project in an IDE. Review them after any agent session before performing those actions:

* Git hooks (`.git/hooks/`) run on commit, push, and other Git actions. These are inside `.git/` and don't appear in `git diff` output — check them separately with `ls -la .git/hooks/`.
* CI configuration (`.github/workflows/`, `.gitlab-ci.yml`) runs on push.
* Build files (`Makefile`, `package.json` scripts, `Cargo.toml`) run during build or install steps.
* IDE configuration (`.vscode/tasks.json`, `.idea/`) can run tasks when you open the project.

> Warning
>
> Treat sandbox-modified workspace files the same way you would treat a pull request from an untrusted contributor: review before you trust them on your host.

### [Clone mode](#clone-mode)

When you start a sandbox with [`--clone`](https://docs.docker.com/ai/sandboxes/usage/#clone-mode), the agent never works directly against your host repository. Even with full root inside the VM, it cannot modify your `.git` directory, your working tree, or any tracked file on your host.

```
```

How the boundary is enforced:

* Your repository's Git root is mounted at `/run/sandbox/source` as read-only. Nothing the agent does inside the VM can write back through that mount.
* The agent works on a private clone that lives inside the sandbox. The clone has its own index, its own refs, and its own working tree. Writes to the clone never reach your host.
* The sandbox publishes the clone over a Git daemon bound to localhost on the host. The CLI wires it up as a `sandbox-<sandbox-name>` Git remote on your host repository. Fetching from that remote uses the same trust model as fetching from any third-party remote — nothing is integrated until you explicitly merge or check out the fetched refs.

The practical guarantees:

* The agent cannot modify any tracked file or any byte under `.git/` on your host. A compromised or buggy agent cannot drop a `.git/hooks/pre-commit`, alter `.github/workflows/`, or sneak changes into your working tree.
* Concurrent `git` commands on the host and inside the sandbox cannot race on a shared `.git/index` or shared refs — there is no shared writable state.
* Credentials, signing keys, and any settings in your repository's `.git/config` stay on the host. The agent's clone has its own independent configuration.

Use clone mode whenever you want a strong boundary between the agent's Git activity and your host repository — for example when running an unfamiliar agent, running multiple agents on the same repository at once, or keeping your working tree clean while the agent works.

## [Credential isolation](#credential-isolation)

Most agents need API keys for their model provider. Rather than passing keys into the sandbox, the host-side proxy intercepts outbound API requests and injects authentication headers before forwarding each request.

Credential values are never stored inside the VM. They are not available as environment variables or files inside the sandbox unless you explicitly set them. This means a compromised sandbox cannot read API keys from the local environment.

For how to store and manage credentials, see [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/).

----
url: https://docs.docker.com/engine/install/binaries/
----

# Install Docker Engine from binaries

***

Table of contents

***

> Important
>
> This page contains information on how to install Docker using binaries. These instructions are mostly suitable for testing purposes. We do not recommend installing Docker using binaries in production environments as they don't have automatic security updates. The Linux binaries described on this page are statically linked, which means that vulnerabilities in build-time dependencies are not automatically patched by security updates of your Linux distribution.
>
> Updating binaries is also slightly more involved when compared to Docker packages installed using a package manager or through Docker Desktop, as it requires (manually) updating the installed version whenever there is a new release of Docker.
>
> Also, static binaries may not include all functionalities provided by the dynamic packages.
>
> On Windows and Mac, we recommend that you install [Docker Desktop](https://docs.docker.com/desktop/) instead. For Linux, we recommend that you follow the instructions specific for your distribution.

If you want to try Docker or use it in a testing environment, but you're not on a supported platform, you can try installing from static binaries. If possible, you should use packages built for your operating system, and use your operating system's package management system to manage Docker installation and upgrades.

Static binaries for the Docker daemon binary are only available for Linux (as `dockerd`) and Windows (as `dockerd.exe`). Static binaries for the Docker client are available for Linux, Windows, and macOS (as `docker`).

This topic discusses binary installation for Linux, Windows, and macOS:

* [Install daemon and client binaries on Linux](#install-daemon-and-client-binaries-on-linux)
* [Install client binaries on macOS](#install-client-binaries-on-macos)
* [Install server and client binaries on Windows](#install-server-and-client-binaries-on-windows)

## [Install daemon and client binaries on Linux](#install-daemon-and-client-binaries-on-linux)

### [Prerequisites](#prerequisites)

Before attempting to install Docker from binaries, be sure your host machine meets the prerequisites:

* A 64-bit installation
* Version 3.10 or higher of the Linux kernel. The latest version of the kernel available for your platform is recommended.
* `iptables` version 1.4 or higher
* `git` version 1.7 or higher
* A `ps` executable, usually provided by `procps` or a similar package.
* [XZ Utils](https://tukaani.org/xz/) 4.9 or higher
* A [properly mounted](https://github.com/tianon/cgroupfs-mount/blob/master/cgroupfs-mount) `cgroupfs` hierarchy; a single, all-encompassing `cgroup` mount point is not sufficient. See Github issues [#2683](https://github.com/moby/moby/issues/2683), [#3485](https://github.com/moby/moby/issues/3485), [#4568](https://github.com/moby/moby/issues/4568)).

#### [Secure your environment as much as possible](#secure-your-environment-as-much-as-possible)

##### [OS considerations](#os-considerations)

Enable SELinux or AppArmor if possible.

It is recommended to use AppArmor or SELinux if your Linux distribution supports either of the two. This helps improve security and blocks certain types of exploits. Review the documentation for your Linux distribution for instructions for enabling and configuring AppArmor or SELinux.

> **Security warning**
>
> If either of the security mechanisms is enabled, do not disable it as a work-around to make Docker or its containers run. Instead, configure it correctly to fix any problems.

##### [Docker daemon considerations](#docker-daemon-considerations)

* Enable `seccomp` security profiles if possible. See [Enabling `seccomp` for Docker](https://docs.docker.com/engine/security/seccomp/).

* Enable user namespaces if possible. See the [Daemon user namespace options](/reference/cli/dockerd/#daemon-user-namespace-options).

### [Install static binaries](#install-static-binaries)

1. Download the static binary archive. Go to <https://download.docker.com/linux/static/stable/>, choose your hardware platform, and download the `.tgz` file relating to the version of Docker Engine you want to install.

2. Extract the archive using the `tar` utility. The `dockerd` and `docker` binaries are extracted.

   ```console
   $ tar xzvf /path/to/FILE.tar.gz
   ```

3. **Optional**: Move the binaries to a directory on your executable path, such as `/usr/bin/`. If you skip this step, you must provide the path to the executable when you invoke `docker` or `dockerd` commands.

   ```console
   $ sudo cp docker/* /usr/bin/
   ```

4. Start the Docker daemon:

   ```console
   $ sudo dockerd &
   ```

   If you need to start the daemon with additional options, modify the above command accordingly or create and edit the file `/etc/docker/daemon.json` to add the custom configuration options.

5. Verify that Docker is installed correctly by running the `hello-world` image.

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

## [Install client binaries on macOS](#install-client-binaries-on-macos)

> Note
>
> The following instructions are mostly suitable for testing purposes. The macOS binary includes the Docker client only. It does not include the `dockerd` daemon which is required to run containers. Therefore, we recommend that you install [Docker Desktop](https://docs.docker.com/desktop/) instead.

The binaries for Mac also do not contain:

* A runtime environment. You must set up a functional engine either in a Virtual Machine, or on a remote Linux machine.
* Docker components such as `buildx` and `docker compose`.

To install client binaries, perform the following steps:

1. Download the static binary archive. Go to <https://download.docker.com/mac/static/stable/> and select `x86_64` (for Mac on Intel chip) or `aarch64` (for Mac on Apple silicon), and then download the `.tgz` file relating to the version of Docker Engine you want to install.

2. Extract the archive using the `tar` utility. The `docker` binary is extracted.

   ```console
   $ tar xzvf /path/to/FILE.tar.gz
   ```

3. Clear the extended attributes to allow it run.

   ```console
   $ sudo xattr -rc docker
   ```

   Now, when you run the following command, you can see the Docker CLI usage instructions:

   ```console
   $ docker/docker
   ```

4. **Optional**: Move the binary to a directory on your executable path, such as `/usr/local/bin/`. If you skip this step, you must provide the path to the executable when you invoke `docker` or `dockerd` commands.

   ```console
   $ sudo cp docker/docker /usr/local/bin/
   ```

5. Verify that Docker is installed correctly by running the `hello-world` image. The value of `<hostname>` is a hostname or IP address running the Docker daemon and accessible to the client.

   ```console
   $ sudo docker -H <hostname> run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a message and exits.

## [Install server and client binaries on Windows](#install-server-and-client-binaries-on-windows)

> Note
>
> The following section describes how to install the Docker daemon on Windows Server which allows you to run Windows containers only. When you install the Docker daemon on Windows Server, the daemon doesn't contain Docker components such as `buildx` and `compose`. If you're running Windows 10 or 11, we recommend that you install [Docker Desktop](https://docs.docker.com/desktop/) instead.

Binary packages on Windows include both `dockerd.exe` and `docker.exe`. On Windows, these binaries only provide the ability to run native Windows containers (not Linux containers).

To install server and client binaries, perform the following steps:

1. Download the static binary archive. Go to <https://download.docker.com/win/static/stable/x86_64> and select the latest version from the list.

2. Run the following PowerShell commands to install and extract the archive to your program files:

   ```powershell
   PS C:\> Expand-Archive /path/to/<FILE>.zip -DestinationPath $Env:ProgramFiles
   ```

3. Register the service and start the Docker Engine:

   ```powershell
   PS C:\> &$Env:ProgramFiles\Docker\dockerd --register-service
   PS C:\> Start-Service docker
   ```

4. Verify that Docker is installed correctly by running the `hello-world` image.

   ```powershell
   PS C:\> &$Env:ProgramFiles\Docker\docker run hello-world:nanoserver
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a message and exits.

## [Upgrade static binaries](#upgrade-static-binaries)

To upgrade your manual installation of Docker Engine, first stop any `dockerd` or `dockerd.exe` processes running locally, then follow the regular installation steps to install the new version on top of the existing version.

## [Next steps](#next-steps)

* Continue to [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/).

----
url: https://docs.docker.com/engine/storage/drivers/vfs-driver/
----

# VFS storage driver

***

Table of contents

***

The VFS storage driver isn't a union filesystem. Each layer is a directory on disk, and there is no copy-on-write support. To create a new layer, a "deep copy" is done of the previous layer. This leads to lower performance and more space used on disk than other storage drivers. However, it is robust, stable, and works in every environment. It can also be used as a mechanism to verify other storage back-ends against, in a testing environment.

## [Configure Docker with the `vfs` storage driver](#configure-docker-with-the-vfs-storage-driver)

1. Stop Docker.

   ```console
   $ sudo systemctl stop docker
   ```

2. Edit `/etc/docker/daemon.json`. If it doesn't yet exist, create it. Assuming that the file was empty, add the following contents.

   ```json
   {
     "storage-driver": "vfs"
   }
   ```

   If you want to set a quota to control the maximum size the VFS storage driver can use, set the `size` option on the `storage-opts` key.

   ```json
   {
     "storage-driver": "vfs",
     "storage-opts": ["size=256M"]
   }
   ```

   Docker doesn't start if the `daemon.json` file contains invalid JSON.

3. Start Docker.

   ```console
   $ sudo systemctl start docker
   ```

4. Verify that the daemon is using the `vfs` storage driver. Use the `docker info` command and look for `Storage Driver`.

   ```console
   $ docker info

   Storage Driver: vfs
   ...
   ```

Docker is now using the `vfs` storage driver. Docker has automatically created the `/var/lib/docker/vfs/` directory, which contains all the layers used by running containers.

## [How the `vfs` storage driver works](#how-the-vfs-storage-driver-works)

Each image layer and the writable container layer are represented on the Docker host as subdirectories within `/var/lib/docker/`. The union mount provides the unified view of all layers. The directory names don't directly correspond to the IDs of the layers themselves.

VFS doesn't support copy-on-write (COW). Each time a new layer is created, it's a deep copy of its parent layer. These layers are all located under `/var/lib/docker/vfs/dir/`.

### [Example: Image and container on-disk constructs](#example-image-and-container-on-disk-constructs)

The following `docker pull` command shows a Docker host downloading a Docker image comprising five layers.

```console
$ docker pull ubuntu

Using default tag: latest
latest: Pulling from library/ubuntu
e0a742c2abfd: Pull complete
486cb8339a27: Pull complete
dc6f0d824617: Pull complete
4f7a5649a30e: Pull complete
672363445ad2: Pull complete
Digest: sha256:84c334414e2bfdcae99509a6add166bbb4fa4041dc3fa6af08046a66fed3005f
Status: Downloaded newer image for ubuntu:latest
```

After pulling, each of these layers is represented as a subdirectory of `/var/lib/docker/vfs/dir/`. The directory names do not correlate with the image layer IDs shown in the `docker pull` command. To see the size taken up on disk by each layer, you can use the `du -sh` command, which gives the size as a human-readable value.

```console
$ ls -l /var/lib/docker/vfs/dir/

total 0
drwxr-xr-x.  2 root root  19 Aug  2 18:19 3262dfbe53dac3e1ab7dcc8ad5d8c4d586a11d2ac3c4234892e34bff7f6b821e
drwxr-xr-x. 21 root root 224 Aug  2 18:23 6af21814449345f55d88c403e66564faad965d6afa84b294ae6e740c9ded2561
drwxr-xr-x. 21 root root 224 Aug  2 18:23 6d3be4585ba32f9f5cbff0110e8d07aea5f5b9fbb1439677c27e7dfee263171c
drwxr-xr-x. 21 root root 224 Aug  2 18:23 9ecd2d88ca177413ab89f987e1507325285a7418fc76d0dcb4bc021447ba2bab
drwxr-xr-x. 21 root root 224 Aug  2 18:23 a292ac6341a65bf3a5da7b7c251e19de1294bd2ec32828de621d41c7ad31f895
drwxr-xr-x. 21 root root 224 Aug  2 18:23 e92be7a4a4e3ccbb7dd87695bca1a0ea373d4f673f455491b1342b33ed91446b
```

```console
$ du -sh /var/lib/docker/vfs/dir/*

4.0K	/var/lib/docker/vfs/dir/3262dfbe53dac3e1ab7dcc8ad5d8c4d586a11d2ac3c4234892e34bff7f6b821e
125M	/var/lib/docker/vfs/dir/6af21814449345f55d88c403e66564faad965d6afa84b294ae6e740c9ded2561
104M	/var/lib/docker/vfs/dir/6d3be4585ba32f9f5cbff0110e8d07aea5f5b9fbb1439677c27e7dfee263171c
125M	/var/lib/docker/vfs/dir/9ecd2d88ca177413ab89f987e1507325285a7418fc76d0dcb4bc021447ba2bab
104M	/var/lib/docker/vfs/dir/a292ac6341a65bf3a5da7b7c251e19de1294bd2ec32828de621d41c7ad31f895
104M	/var/lib/docker/vfs/dir/e92be7a4a4e3ccbb7dd87695bca1a0ea373d4f673f455491b1342b33ed91446b
```

The above output shows that three layers each take 104M and two take 125M. These directories have only small differences from each other, but they all consume the same amount of disk space. This is one of the disadvantages of using the `vfs` storage driver.

## [Related information](#related-information)

* [Understand images, containers, and storage drivers](https://docs.docker.com/engine/storage/drivers/)
* [Select a storage driver](https://docs.docker.com/engine/storage/drivers/select-storage-driver/)

----
url: https://docs.docker.com/guides/lab-ai-fundamentals/
----

[Lab: AI Fundamentals for Developers](https://docs.docker.com/guides/lab-ai-fundamentals/)

Hands-on lab: Learn the four core pillars of AI application development. Work with the Chat Completions API, prompt engineering, tool calling, and RAG through interactive exercises.

AI Labs

45 minutes

Resources:

* [Docker Model Runner docs](/ai/model-runner/)
* [Labspace repository](https://github.com/dockersamples/labspace-ai-fundamentals)

[« Back to all guides](/guides/)

# Lab: AI Fundamentals for Developers

***

Table of contents

***

Get hands-on with the four core pillars of AI application development: models, prompt engineering, tool calling, and RAG. This lab runs entirely on your machine using Docker Model Runner — no API key or cloud account required.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-ai-fundamentals up -d
   ```

   > Note
   >
   > This lab uses an AI model, which requires [the Docker Model Runner to be enabled](https://docs.docker.com/ai/model-runner/get-started/). The model may take some time to download.

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

By the end of this Labspace, you will have completed the following:

* Understand the Chat Completions API and how to structure messages for a model
* Use prompt engineering techniques including system prompts, few-shot examples, and structured output
* Implement tool calling and the agentic loop in code
* Build a RAG pipeline that grounds model responses in your own data

## [Modules](#modules)

| # | Module                               | Description                                                       |
| - | ------------------------------------ | ----------------------------------------------------------------- |
| 1 | Welcome & Setup                      | Introduction to the lab and verifying your environment            |
| 2 | Talking to Models                    | Chat Completions API, message roles, and stateless model behavior |
| 3 | Prompt Engineering                   | System prompts, few-shot examples, and structured output          |
| 4 | Tool Calling                         | Tool definitions, the agentic loop, and executing tools in code   |
| 5 | Retrieval Augmented Generation (RAG) | Retrieve, augment, and generate with your own knowledge base      |
| 6 | Wrap-up                              | Summary of concepts and next steps                                |

----
url: https://docs.docker.com/reference/api/engine/version/v1.40/
----

# Docker Engine API v1.40 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.40.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.40.yaml)

# Docker Engine API (1.40)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.40.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.40) is used. For example, calling `/info` is the same as calling `/v1.40/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.40/containers/json

|      |                                                                                                                               |
| ---- | ----------------------------------------------------------------------------------------------------------------------------- |
| name | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`. |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.                                                                                                                                                                                                                                                           |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.40/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"KernelMemory": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
}
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "e90e34656806",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.40/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"AppArmorProfile": "",
"Args": [
"-c",
"exit 9"
],
"Config": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"/bin/sh",
"-c",
"exit 9"
],
"Domainname": "",
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Healthcheck": {
"Test": [
"CMD-SHELL",
"exit 0"
]
},
"Hostname": "ba033ac44011",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"MacAddress": "",
"NetworkDisabled": false,
"OpenStdin": false,
"StdinOnce": false,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"StopSignal": "SIGTERM",
"StopTimeout": 10
},
"Created": "2015-01-06T15:47:31.485331387Z",
"Driver": "overlay2",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 0,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"ContainerIDFile": "",
"CpusetCpus": "",
"CpusetMems": "",
"CpuPercent": 80,
"CpuShares": 0,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"Devices": [ ],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"IpcMode": "",
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"KernelMemory": 0,
"OomKillDisable": false,
"OomScoreAdj": 500,
"NetworkMode": "bridge",
"PidMode": "",
"PortBindings": { },
"Privileged": false,
"ReadonlyRootfs": false,
"PublishAllPorts": false,
"RestartPolicy": {
"MaximumRetryCount": 2,
"Name": "on-failure"
},
"LogConfig": {
"Type": "json-file"
},
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Ulimits": [
{ }
],
"VolumeDriver": "",
"ShmSize": 67108864
},
"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
"MountLabel": "",
"Name": "/boring_euclid",
"NetworkSettings": {
"Bridge": "",
"SandboxID": "",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": 0,
"SandboxKey": "",
"EndpointID": "",
"Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"MacAddress": "",
"Networks": {
"bridge": {
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
"EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Path": "/bin/sh",
"ProcessLabel": "",
"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
"RestartCount": 1,
"State": {
"Error": "",
"ExitCode": 9,
"FinishedAt": "2015-01-06T15:47:32.080254511Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2019-12-22T10:59:05.6385933Z",
"End": "2019-12-22T10:59:05.8078452Z",
"ExitCode": 0,
"Output": ""
}
]
},
"OOMKilled": false,
"Dead": false,
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z",
"Status": "running"
},
"Mounts": [
{
"Name": "fac362...80535",
"Source": "/data",
"Destination": "/data",
"Driver": "local",
"Mode": "ro,Z",
"RW": false,
"Propagation": ""
}
]
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.40/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
],
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.40/containers/{id}/logs

### Response samples

* 200
* 404
* 500

Content type

application/json

`"string"`

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified
* `1`: Added
* `2`: Deleted

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.40/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.40/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                             |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| stream | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect. |

### Responses

/v1.40/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"read": "2015-01-08T22:57:31.547920715Z",
"pids_stats": {
"current": 3
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"memory_stats": {
"stats": {
"total_pgmajfault": 0,
"cache": 0,
"mapped_file": 0,
"total_inactive_file": 0,
"pgpgout": 414,
"rss": 6537216,
"total_mapped_file": 0,
"writeback": 0,
"unevictable": 0,
"pgpgin": 477,
"total_unevictable": 0,
"pgmajfault": 0,
"total_rss": 6537216,
"total_rss_huge": 6291456,
"total_writeback": 0,
"total_inactive_anon": 0,
"rss_huge": 6291456,
"hierarchical_memory_limit": 67108864,
"total_pgfault": 964,
"total_active_file": 0,
"active_anon": 6537216,
"total_active_anon": 6537216,
"total_pgpgout": 414,
"total_cache": 0,
"inactive_anon": 0,
"active_file": 0,
"pgfault": 964,
"inactive_file": 0,
"total_pgpgin": 477
},
"max_usage": 6651904,
"usage": 6537216,
"failcnt": 0,
"limit": 67108864
},
"blkio_stats": { },
"cpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24472255,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100215355,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 739306590000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24350896,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100093996,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 9492140000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.40/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.40/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|   |                                                               |
| - | ------------------------------------------------------------- |
| t | integerNumber of seconds to wait before killing the container |

### Responses

/v1.40/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|   |                                                               |
| - | ------------------------------------------------------------- |
| t | integerNumber of seconds to wait before killing the container |

### Responses

/v1.40/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.40/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemory       | integer \<int64>Kernel memory limit in bytes.                                                                                                                                                                                                          |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes).                                                                                                                                                                                    |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.40/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"KernelMemory": 52428800,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"string"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.40/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.40/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.40/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.40/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |

### Responses

/v1.40/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.40/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.40/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.40/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.40/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.40/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.40/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| all     | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                       |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) |
| digests | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                           |

### Responses

/v1.40/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"VirtualSize": 172064416,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.40/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| keep-storage | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                    |
| all          | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<duration>`: duration relative to daemon's time, during which build cache was not used, in Go's duration format (e.g., '24h')
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.40/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Create an image by either pulling it from a registry or importing it.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                   |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed.                                                                                                             |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                     |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                 |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                       |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                      |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR` |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                     |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.40/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.40/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"Container": "65974bc86f1770ae4bff79f651ebdbce166ae9aada632ee3fa9af3a264911735",
"ContainerConfig": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"DockerVersion": "20.10.7",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "web:web",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": true,
"Image": "",
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"VirtualSize": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.40/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|     |                                                                                                                                                                 |
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed. |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.40/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.40/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|         |                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------ |
| force   | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags |
| noprune | booleanDefault: falseDo not delete untagged parent images                                              |

### Responses

/v1.40/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                                                       |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                                                  |
| limit        | integerMaximum number of results to return                                                                                                                                                                                                            |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-automated=(true\|false)`
- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.40/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "wma55/u1210sshd",
"star_count": 0
},
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "jdswinbank/sshd",
"star_count": 0
},
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "vgauthier/sshd",
"star_count": 0
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.40/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.                                                                                                                                                                                                                                                           |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.40/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains one directory per image layer (named using its long ID), each containing these files:

* `VERSION`: currently `1.0` - the file format version
* `json`: detailed layer information, similar to `docker inspect layer_id`
* `layer.tar`: A tarfile containing the filesystem changes in this layer

The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories for storing attribute changes and deletions.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.40/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                          |
| ----- | ---------------------------------------- |
| names | Array of stringsImage names to filter by |

### Responses

/v1.40/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                                             |
| ----- | ----------------------------------------------------------- |
| quiet | booleanDefault: falseSuppress progress details during load. |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.40/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.40/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.40/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "net01",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.19.0.0/16",
"Gateway": "172.19.0.1"
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.40/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Namerequired   | stringThe network's name.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| CheckDuplicate | booleanCheck for networks with duplicate names. Since Network is primarily keyed based on a random ID and not on the name, and network name is strictly a user-friendly alias to the network which is uniquely identified using ID, there is no guaranteed way to check for duplicates. CheckDuplicate is there to provide a best effort checking of any networks which has the same name but it is not guaranteed to catch all name collisions. |
| Driver         | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                                                                                                                                                                                                                                 |
| Internal       | booleanRestrict external access to the network.                                                                                                                                                                                                                                                                                                                                                                                                  |
| Attachable     | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                                                                                                                                                                                                                          |
| Ingress        | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                                                                                                                                                                                                                             |
|                | object (IPAM)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| EnableIPv6     | booleanEnable IPv6 on the network.                                                                                                                                                                                                                                                                                                                                                                                                               |
|                | objectNetwork specific options to be used by the drivers.                                                                                                                                                                                                                                                                                                                                                                                        |
|                | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                           |

### Responses

/v1.40/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "isolated_nw",
"CheckDuplicate": false,
"Driver": "bridge",
"EnableIPv6": true,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11"
},
{
"Subnet": "2001:db8:abcd::/64",
"Gateway": "2001:db8:abcd::1011"
}
],
"Options": {
"foo": "bar"
}
},
"Internal": true,
"Attachable": false,
"Ingress": false,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.40/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
}
}
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.40/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.40/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.40/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |

### Responses

/v1.40/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.40/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.40/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.40/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.40/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|        |                                 |
| ------ | ------------------------------- |
| Detach | booleanDetach from the command. |
| Tty    | booleanAllocate a pseudo-TTY.   |

### Responses

/v1.40/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": false
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.40/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.40/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.40/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.40/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.40/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.40/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.40/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.40/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.40/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.40/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.40/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.40/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.40/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |

### Responses

/v1.40/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                  |
| ---- | ------------------------------------------------------------------------------------------------ |
| Name | stringName of the service.                                                                       |
|      | objectUser-defined key/value metadata.                                                           |
|      | object (TaskSpec)User modifiable task configuration.                                             |
|      | objectScheduling mode for the service.                                                           |
|      | objectSpecification for the update strategy of the service.                                      |
|      | objectSpecification for the rollback strategy of the service.                                    |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.     |

### Responses

/v1.40/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
}
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
}
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warning": "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.40/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.40/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                  |
| ---- | ------------------------------------------------------------------------------------------------ |
| Name | stringName of the service.                                                                       |
|      | objectUser-defined key/value metadata.                                                           |
|      | object (TaskSpec)User modifiable task configuration.                                             |
|      | objectScheduling mode for the service.                                                           |
|      | objectSpecification for the update strategy of the service.                                      |
|      | objectSpecification for the rollback strategy of the service.                                    |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.     |

### Responses

/v1.40/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
}
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
}
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warning": "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.40/services/{id}/logs

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`"string"`

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.40/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.40/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.40/tasks/{id}/logs

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`"string"`

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.40/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.40/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.40/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.40/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.40/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.40/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.40/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.40/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.40/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.40/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.40/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.40/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.40/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.40/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.40/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.40/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.40/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.40/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.40/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.40/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.40/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.40/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.40/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"SystemStatus": [ [
"Role",
"primary"
], [
"State",
"Healthy"
], [
"Strategy",
"spread"
], [
"Filters",
"health, port, containerslots, dependency, affinity, constraint, whitelist"
], [
"Nodes",
"2"
], [
" swarm-agent-00",
"192.168.99.102:2376"
], [
" └ ID",
"5CT6:FBGO:RVGO:CZL4:PB2K:WCYN:2JSV:KSHH:GGFW:QOPG:6J5Q:IOZ2|192.168.99.102:2376"
], [
" └ Status",
"Healthy"
], [
" └ Containers",
"1 (1 Running, 0 Paused, 0 Stopped)"
], [
" └ Reserved CPUs",
"0 / 1"
], [
" └ Reserved Memory",
"0 B / 1.021 GiB"
], [
" └ Labels",
"kernelversion=4.4.74-boot2docker, operatingsystem=Boot2Docker 17.06.0-ce (TCL 7.2); HEAD : 0672754 - Thu Jun 29 00:06:31 UTC 2017, ostype=linux, provider=virtualbox, storagedriver=aufs"
], [
" └ UpdatedAt",
"2017-08-09T10:03:46Z"
], [
" └ ServerVersion",
"17.06.0-ce"
], [
" swarm-manager",
"192.168.99.101:2376"
], [
" └ ID",
"TAMD:7LL3:SEF7:LW2W:4Q2X:WVFH:RTXX:JSYS:XY2P:JEHL:ZMJK:JGIW|192.168.99.101:2376"
], [
" └ Status",
"Healthy"
], [
" └ Containers",
"2 (2 Running, 0 Paused, 0 Stopped)"
], [
" └ Reserved CPUs",
"0 / 1"
], [
" └ Reserved Memory",
"0 B / 1.021 GiB"
], [
" └ Labels",
"kernelversion=4.4.74-boot2docker, operatingsystem=Boot2Docker 17.06.0-ce (TCL 7.2); HEAD : 0672754 - Thu Jun 29 00:06:31 UTC 2017, ostype=linux, provider=virtualbox, storagedriver=aufs"
], [
" └ UpdatedAt",
"2017-08-09T10:04:11Z"
], [
" └ ServerVersion",
"17.06.0-ce"
]
],
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemory": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"BridgeNfIptables": true,
"BridgeNfIp6tables": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"NEventsListener": 30,
"KernelVersion": "4.9.38-moby",
"OperatingSystem": "Alpine Linux v3.5",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"AllowNondistributableArtifactsCIDRs": [ ],
"AllowNondistributableArtifactsHostnames": [ ],
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "17.06.0-ce",
"ClusterStore": "consul://consul.corp.example.com:8600/some/path",
"ClusterAdvertise": "node5.corp.example.com:8000",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"Warnings": [
"WARNING: No memory limit support"
]
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.40/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "19.03.12",
"Details": { }
}
],
"Version": "19.03.12",
"ApiVersion": "1.40",
"MinAPIVersion": "1.12",
"GitCommit": "48a66213fe",
"GoVersion": "go1.13.14",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "4.19.76-linuxkit",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.40/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.40/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, and `update`

Images report these events: `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, and `untag`

Volumes report these events: `create`, `mount`, `unmount`, and `destroy`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, and `remove`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.40/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

### Responses

/v1.40/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"VirtualSize": 1092588,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parent": "",
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parent": "ndlpt0hhvkqcdfkputsk4cq9c",
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.40/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 3987495
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.40/session

----
url: https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/
----

# What is an image?

***

Table of contents

***

## [Explanation](#explanation)

Seeing as a [container](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) is an isolated process, where does it get its files and configuration? How do you share those environments?

That's where container images come in. A container image is a standardized package that includes all of the files, binaries, libraries, and configurations to run a container.

For a [PostgreSQL](https://hub.docker.com/_/postgres) image, that image will package the database binaries, config files, and other dependencies. For a Python web app, it'll include the Python runtime, your app code, and all of its dependencies.

There are two important principles of images:

1. Images are immutable. Once an image is created, it can't be modified. You can only make a new image or add changes on top of it.

2. Container images are composed of layers. Each layer represents a set of file system changes that add, remove, or modify files.

These two principles let you to extend or add to existing images. For example, if you are building a Python app, you can start from the [Python image](https://hub.docker.com/_/python) and add additional layers to install your app's dependencies and add your code. This lets you focus on your app, rather than Python itself.

### [Finding images](#finding-images)

[Docker Hub](https://hub.docker.com) is the default global marketplace for storing and distributing images. It has over 100,000 images created by developers that you can run locally. You can search for Docker Hub images and run them directly from Docker Desktop.

Docker Hub provides a variety of Docker-supported and endorsed images known as Docker Trusted Content. These provide fully managed services or great starters for your own images. These include:

* [Docker Official Images](https://hub.docker.com/search?badges=official) - a curated set of Docker repositories, serve as the starting point for the majority of users, and are some of the most secure on Docker Hub
* [Docker Hardened Images](https://hub.docker.com/hardened-images/catalog) - minimal, secure, production-ready images with near-zero CVEs, designed to reduce attack surface and simplify compliance. Free and open source under Apache 2.0
* [Docker Verified Publishers](https://hub.docker.com/search?badges=verified_publisher) - high-quality images from commercial publishers verified by Docker
* [Docker-Sponsored Open Source](https://hub.docker.com/search?badges=open_source) - images published and maintained by open-source projects sponsored by Docker through Docker's open source program

For example, [Redis](https://hub.docker.com/_/redis) and [Memcached](https://hub.docker.com/_/memcached) are a few popular ready-to-go Docker Official Images. You can download these images and have these services up and running in a matter of seconds. There are also base images, like the [Node.js](https://hub.docker.com/_/node) Docker image, that you can use as a starting point and add your own files and configurations. For production workloads requiring enhanced security, Docker Hardened Images offer minimal variants of popular images like Node.js, Python, and Go.

## [Try it out](#try-it-out)

In this hands-on, you will learn how to search and pull a container image using the Docker Desktop GUI.

### [Search for and download an image](#search-for-and-download-an-image)

1. Open the Docker Desktop Dashboard and select the **Images** view in the left-hand navigation menu.

2. Select the **Search images to run** button. If you don't see it, select the *global search bar* at the top of the screen.

3. In the **Search** field, enter "welcome-to-docker". Once the search has completed, select the `docker/welcome-to-docker` image.

4. Select **Pull** to download the image.

### [Learn about the image](#learn-about-the-image)

Once you have an image downloaded, you can learn quite a few details about the image either through the GUI or the CLI.

1. In the Docker Desktop Dashboard, select the **Images** view.

2. Select the **docker/welcome-to-docker** image to open details about the image.

3. The image details page presents you with information regarding the layers of the image, the packages and libraries installed in the image, and any discovered vulnerabilities.

Follow the instructions to search and pull a Docker image using CLI to view its layers.

### [Search for and download an image](#search-for-and-download-an-image)

1. Open a terminal and search for images using the [`docker search`](/reference/cli/docker/search/) command:

   ```console
   docker search docker/welcome-to-docker
   ```

   You will see output like the following:

   ```console
   NAME                       DESCRIPTION                                     STARS     OFFICIAL
   docker/welcome-to-docker   Docker image for new users getting started w…   20
   ```

   This output shows you information about relevant images available on Docker Hub.

2. Pull the image using the [`docker pull`](/reference/cli/docker/image/pull/) command.

   ```console
   docker pull docker/welcome-to-docker
   ```

   You will see output like the following:

   ```console
   Using default tag: latest
   latest: Pulling from docker/welcome-to-docker
   579b34f0a95b: Download complete
   d11a451e6399: Download complete
   1c2214f9937c: Download complete
   b42a2f288f4d: Download complete
   54b19e12c655: Download complete
   1fb28e078240: Download complete
   94be7e780731: Download complete
   89578ce72c35: Download complete
   Digest: sha256:eedaff45e3c78538087bdd9dc7afafac7e110061bbdd836af4104b10f10ab693
   Status: Downloaded newer image for docker/welcome-to-docker:latest
   docker.io/docker/welcome-to-docker:latest
   ```

   Each of line represents a different downloaded layer of the image. Remember that each layer is a set of filesystem changes and provides functionality of the image.

### [Learn about the image](#learn-about-the-image)

1. List your downloaded images using the [`docker image ls`](/reference/cli/docker/image/ls/) command:

   ```console
   docker image ls
   ```

   You will see output like the following:

   ```console
   REPOSITORY                 TAG       IMAGE ID       CREATED        SIZE
   docker/welcome-to-docker   latest    eedaff45e3c7   4 months ago   29.7MB
   ```

   The command shows a list of Docker images currently available on your system. The `docker/welcome-to-docker` has a total size of approximately 29.7MB.

   > **Image size**
   >
   > The image size represented here reflects the uncompressed size of the image, not the download size of the layers.

2. List the image's layers using the [`docker image history`](/reference/cli/docker/image/history/) command:

   ```console
   docker image history docker/welcome-to-docker
   ```

   You will see output like the following:

   ```console
   IMAGE          CREATED        CREATED BY                                      SIZE      COMMENT
   648f93a1ba7d   4 months ago   COPY /app/build /usr/share/nginx/html # buil…   1.6MB     buildkit.dockerfile.v0
   <missing>      5 months ago   /bin/sh -c #(nop)  CMD ["nginx" "-g" "daemon…   0B
   <missing>      5 months ago   /bin/sh -c #(nop)  STOPSIGNAL SIGQUIT           0B
   <missing>      5 months ago   /bin/sh -c #(nop)  EXPOSE 80                    0B
   <missing>      5 months ago   /bin/sh -c #(nop)  ENTRYPOINT ["/docker-entr…   0B
   <missing>      5 months ago   /bin/sh -c #(nop) COPY file:9e3b2b63db9f8fc7…   4.62kB
   <missing>      5 months ago   /bin/sh -c #(nop) COPY file:57846632accc8975…   3.02kB
   <missing>      5 months ago   /bin/sh -c #(nop) COPY file:3b1b9915b7dd898a…   298B
   <missing>      5 months ago   /bin/sh -c #(nop) COPY file:caec368f5a54f70a…   2.12kB
   <missing>      5 months ago   /bin/sh -c #(nop) COPY file:01e75c6dd0ce317d…   1.62kB
   <missing>      5 months ago   /bin/sh -c set -x     && addgroup -g 101 -S …   9.7MB
   <missing>      5 months ago   /bin/sh -c #(nop)  ENV PKG_RELEASE=1            0B
   <missing>      5 months ago   /bin/sh -c #(nop)  ENV NGINX_VERSION=1.25.3     0B
   <missing>      5 months ago   /bin/sh -c #(nop)  LABEL maintainer=NGINX Do…   0B
   <missing>      5 months ago   /bin/sh -c #(nop)  CMD ["/bin/sh"]              0B
   <missing>      5 months ago   /bin/sh -c #(nop) ADD file:ff3112828967e8004…   7.66MB
   ```

   This output shows you all of the layers, their sizes, and the command used to create the layer.

   > **Viewing the full command**
   >
   > If you add the `--no-trunc` flag to the command, you will see the full command. Note that, since the output is in a table-like format, longer commands will cause the output to be very difficult to navigate.

In this walkthrough, you searched and pulled a Docker image. In addition to pulling a Docker image, you also learned about the layers of a Docker Image.

## [Additional resources](#additional-resources)

The following resources will help you learn more about exploring, finding, and building images:

* [Docker trusted content](https://docs.docker.com/docker-hub/image-library/trusted-content/)
* [Explore the Image view in Docker Desktop](https://docs.docker.com/desktop/use-desktop/images/)
* [Docker Build overview](https://docs.docker.com/build/concepts/overview/)
* [Docker Hub](https://hub.docker.com)

## [Next steps](#next-steps)

Now that you have learned the basics of images, it's time to learn about distributing images through registries.

[What is a registry?](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-registry/)

----
url: https://docs.docker.com/scout/integrations/registry/ecr/
----

# Integrate Docker Scout with Amazon ECR

***

Table of contents

***

Integrating Docker Scout with Amazon Elastic Container Registry (ECR) lets you view image insights for images hosted in ECR repositories. After integrating Docker Scout with ECR and activating Docker Scout for a repository, pushing an image to the repository automatically triggers image analysis. You can view image insights using the Docker Scout Dashboard, or the `docker scout` CLI commands.

## [How it works](#how-it-works)

To help you integrate Docker Scout with ECR, you can use a CloudFormation stack template that creates and configures the necessary AWS resources for integrating Docker Scout with your ECR registry. For more details about the AWS resources, see [CloudFormation stack template](#cloudformation-stack-template).

The following diagram shows how the Docker Scout ECR integration works.

After the integration, Docker Scout automatically pulls and analyzes images that you push to the ECR registry. Metadata about your images are stored on the Docker Scout platform, but Docker Scout doesn't store the container images themselves. For more information about how Docker Scout handles image data, see [Data handling](https://docs.docker.com/scout/deep-dive/data-handling/).

### [CloudFormation stack template](#cloudformation-stack-template)

The following table describes the configuration resources.

> Note
>
> Creating these resources incurs a small, recurring cost on the AWS account. The **Cost** column in the table represents an estimated monthly cost of the resources, when integrating an ECR registry that gets 100 images pushed per day.
>
> Additionally, an egress cost also applies when Docker Scout pulls the images from ECR. The egress cost is around $0.09 per GB.

| Resource type                 | Resource name                | Description                                                                                | Cost  |
| ----------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------ | ----- |
| `AWS::SNSTopic::Topic`        | `SNSTopic`                   | SNS topic for notifying Docker Scout when the AWS resources have been created.             | Free  |
| `AWS::SNS::TopicPolicy`       | `TopicPolicy`                | Defines the topic for the initial setup notification.                                      | Free  |
| `AWS::SecretsManager::Secret` | `ScoutAPICredentials`        | Stores the credentials used by EventBridge to fire events to Scout.                        | $0.42 |
| `AWS::Events::ApiDestination` | `ApiDestination`             | Sets up the EventBridge connection to Docker Scout for sending ECR push and delete events. | $0.01 |
| `AWS::Events::Connection`     | `Connection`                 | EventBridge connection credentials to Scout.                                               | Free  |
| `AWS::Events::Rule`           | `DockerScoutEcrRule`         | Defines the rule to send ECR pushes and deletes to Scout.                                  | Free  |
| `AWS::Events::Rule`           | `DockerScoutRepoDeletedRule` | Defines the rule to send ECR repository deletes to Scout.                                  | Free  |
| `AWS::IAM::Role`              | `InvokeApiRole`              | Internal role to grant the event access to `ApiDestination`.                               | Free  |
| `AWS::IAM::Role`              | `AssumeRoleEcrAccess`        | This role has access to `ScoutAPICredentials` for setting up the Docker Scout integration. | Free  |

## [Integrate your first registry](#integrate-your-first-registry)

Create the CloudFormation stack in your AWS account to enable the Docker Scout integration.

Prerequisites:

* You must have access to an AWS account with permission to create resources.
* You have be an owner of the Docker organization.

To create the stack:

1. Go to the [ECR integration page](https://scout.docker.com/settings/integrations/ecr/) on the Docker Scout Dashboard.

2. Select the **Create on AWS** button.

   This opens the **Create stack** wizard in the AWS CloudFormation console in a new browser tab. If you're not already signed in to AWS, you're redirected to the sign-in page first.

   If the button is grayed-out, it means you're lacking the necessary permissions in the Docker organization.

3. Follow the steps in the **Create stack** wizard until the end. Choose the AWS region you want to integrate. Complete the procedure by creating the resources.

   The fields in the wizard are pre-populated by the CloudFormation template, so you don't need to edit any of the fields.

4. When the resources have been created (the CloudFormation status shows `CREATE_COMPLETE` in the AWS console), return to the ECR integrations page in the Docker Scout Dashboard.

   The **Integrated registries** list shows the account ID and region for the ECR registry that you just integrated. If successful, the integration status is **Connected**.

The ECR integration is now active. For Docker Scout to start analyzing images in the registry, you need to activate it for each repository in [Repository settings](https://scout.docker.com/settings/repos/).

After activating repositories, images that you push are analyzed by Docker Scout. The analysis results appear in the Docker Scout Dashboard. If your repository already contains images, Docker Scout pulls and analyzes the latest image version automatically.

## [Integrate additional registries](#integrate-additional-registries)

To add additional registries:

1. Go to the [ECR integration page](https://scout.docker.com/settings/integrations/ecr/) on the Docker Scout Dashboard.

2. Select the **Add** button at the top of the list.

3. Complete the steps for creating the AWS resources.

4. When the resources have been created, return to the ECR integrations page in the Docker Scout Dashboard.

   The **Integrated registries** list shows the account ID and region for the ECR registry that you just integrated. If successful, the integration status is **Connected**.

Next, activate Docker Scout for the repositories that you want to analyze in [Repository settings](https://scout.docker.com/settings/repos/).

## [Remove integration](#remove-integration)

To remove an integrated ECR registry, you must be an owner of the Docker organization.

1. Go to the [ECR integration page](https://scout.docker.com/settings/integrations/ecr/) on the Docker Scout Dashboard.

2. Find the registry that you want to remove in the list of integrated registries, and select the remove icon in the **Actions** column.

   If the remove icon is disabled, it means that you're lacking the necessary permissions in the Docker organization.

3. In the dialog that opens, confirm by selecting **Remove**.

> Important
>
> Removing the integration from the Docker Scout dashboard doesn't remove the AWS resources in your account.
>
> After removing the integration in Docker Scout, go to the AWS console and delete the **DockerScoutECRIntegration** CloudFormation stack for the integration that you want to remove.

## [Troubleshooting](#troubleshooting)

### [Unable to integrate registry](#unable-to-integrate-registry)

Check the **Status** of the integration on the [ECR integration page](https://scout.docker.com/settings/integrations/ecr/) in the Docker Scout Dashboard.

* If the status is **Pending** for a prolonged period of time, it's an indication that the integration was not yet completed on the AWS side. Select the **Pending** link to open the CloudFormation wizard, and complete all the steps.

* An **Error** status indicates that something's gone wrong in the back-end. You can try [removing the integration](#remove-integration) and recreating it again.

### [ECR images not showing in the dashboard](#ecr-images-not-showing-in-the-dashboard)

If image analysis results for your ECR images aren't showing up in the Docker Scout Dashboard:

* Ensure that you've activated Docker Scout for the repository. View and manage active repositories in [Repository settings](https://scout.docker.com/settings/repos/).

* Ensure that the AWS account ID and region for your registry is listed on the ECR integrations page.

  The account ID and region are included in the registry hostname: `<aws_account_id>.dkr.ecr.<region>.amazonaws.com/<image>`

----
url: https://docs.docker.com/reference/cli/docker/mcp/client/connect/
----

# docker mcp client connect

***

| Description | Connect the Docker MCP Toolkit to a client. Supported clients: claude-code claude-desktop cline codex continue crush cursor gemini goose gordon kiro lmstudio opencode sema4 vscode zed        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Usage       | `docker mcp client connect [OPTIONS] <mcp-client> Supported clients: claude-code claude-desktop cline codex continue crush cursor gemini goose gordon kiro lmstudio opencode sema4 vscode zed` |

## [Description](#description)

Connect the Docker MCP Toolkit to a client. Supported clients: claude-code claude-desktop cline codex continue crush cursor gemini goose gordon kiro lmstudio opencode sema4 vscode zed

## [Options](#options)

| Option          | Default | Description                                                                          |
| --------------- | ------- | ------------------------------------------------------------------------------------ |
| `-g, --global`  |         | Change the system wide configuration or the clients setup in your current git repo.  |
| `-p, --profile` |         | Profile to use for client connection.                                                |
| `-q, --quiet`   |         | Only display errors.                                                                 |

----
url: https://docs.docker.com/enterprise/security/provisioning/just-in-time/
----

# Just-in-Time provisioning

***

Table of contents

***

Subscription: Business

For: Administrators

Just-in-Time (JIT) provisioning streamlines user onboarding by automatically creating and updating user accounts during SSO authentication. This eliminates manual account creation and ensures users have immediate access to your organization's resources. JIT verifies that users belong to the organization and assigns them to the appropriate teams based on your identity provider (IdP) configuration. When you create your SSO connection, JIT provisioning is turned on by default.

This page explains how JIT provisioning works, SSO authentication flows, and how to disable JIT provisioning.

## [Prerequisites](#prerequisites)

Before you begin, you must have:

* SSO configured for your organization
* Administrator access to Docker Home and your identity provider

## [SSO authentication with JIT provisioning enabled](#sso-authentication-with-jit-provisioning-enabled)

When a user signs in with SSO and you have JIT provisioning enabled, the following steps occur automatically:

1. The system checks if a Docker account exists for the user's email address.

   * If an account exists: The system uses the existing account and updates the user's full name if necessary.
   * If no account exists: A new Docker account is created using basic user attributes (email, name, and surname). A unique username is generated based on the user's email, name, and random numbers to ensure all usernames are unique across the platform.

2. The system checks for any pending invitations to the SSO organization.

   * Invitation found: The invitation is automatically accepted.
   * Invitation includes a specific group: The user is added to that group within the SSO organization.

3. The system verifies if the IdP has shared group mappings during authentication.

   * Group mappings provided: The user is assigned to the relevant organizations and teams.
   * No group mappings provided: The system checks if the user is already part of the organization. If not, the user is added to the default organization and team configured in the SSO connection.

The following graphic provides an overview of SSO authentication with JIT enabled:

## [SSO authentication with JIT provisioning disabled](#sso-authentication-with-jit-provisioning-disabled)

When JIT provisioning is disabled, the following actions occur during SSO authentication:

1. The system checks if a Docker account exists for the user's email address.

   * If an account exists: The system uses the existing account and updates the user's full name if necessary.
   * If no account exists: A new Docker account is created using basic user attributes (email, name, and surname). A unique username is generated based on the user's email, name, and random numbers to ensure all usernames are unique across the platform.

2. The system checks for any pending invitations to the SSO organization.

   * Invitation found: If the user is a member of the organization or has a pending invitation, sign-in is successful, and the invitation is automatically accepted.
   * No invitation found: If the user is not a member of the organization and has no pending invitation, the sign-in fails, and an `Access denied` error appears. The user must contact an administrator to be invited to the organization.

With JIT disabled, group mapping is only available if you have [SCIM enabled](https://docs.docker.com/enterprise/security/provisioning/scim/#enable-scim-in-docker). If SCIM is not enabled, users won't be auto-provisioned to groups.

The following graphic provides an overview of SSO authentication with JIT disabled:

## [Disable JIT provisioning](#disable-jit-provisioning)

> Warning
>
> Disabling JIT provisioning may disrupt your users' access and workflows. With JIT disabled, users will not be automatically added to your organization. Users must already be a member of the organization or have a pending invitation to successfully sign in through SSO. To auto-provision users with JIT disabled, [use SCIM](https://docs.docker.com/enterprise/security/provisioning/scim/).

You may want to disable JIT provisioning for reasons such as the following:

* You have multiple organizations, have SCIM enabled, and want SCIM to be the source of truth for provisioning
* You want to control and restrict usage based on your organization's security configuration, and want to use SCIM to provision access

Users are provisioned with JIT by default. If you enable SCIM, you can disable JIT:

1. Go to [Docker Home](https://app.docker.com/) and select your organization from the top-left account drop-down.
2. Select **Admin Console**, then **SSO and SCIM**.
3. In the **SSO connections** table, select the **Action** icon, then select **Disable JIT provisioning**.
4. Select **Disable** to confirm.

## [Next steps](#next-steps)

* Configure [SCIM provisioning](https://docs.docker.com/enterprise/security/provisioning/scim/) for advanced user management.
* Set up [group mapping](https://docs.docker.com/enterprise/security/provisioning/scim/group-mapping/) to automatically assign users to teams.
* Review [Troubleshoot provisioning](https://docs.docker.com/enterprise/security/provisioning/troubleshoot-provisioning/).

----
url: https://docs.docker.com/reference/api/engine/version/v1.51/
----

# Docker Engine API v1.51 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.51.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.51.yaml)

# Docker Engine API (1.51)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.51.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.50) is used. For example, calling `/info` is the same as calling `/v1.51/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means the server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.51/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.51/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
},
"database_nw": { }
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.51/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf",
"Created": "2025-02-17T17:43:39.64001363Z",
"Path": "/bin/sh",
"Args": [
"-c",
"exit 9"
],
"State": {
"Status": "running",
"Running": true,
"Paused": false,
"Restarting": false,
"OOMKilled": false,
"Dead": false,
"Pid": 1234,
"ExitCode": 0,
"Error": "string",
"StartedAt": "2020-01-06T09:06:59.461876391Z",
"FinishedAt": "2020-01-06T09:07:59.461876391Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2020-01-04T10:44:24.496525531Z",
"End": "2020-01-04T10:45:21.364524523Z",
"ExitCode": 0,
"Output": "string"
}
]
}
},
"Image": "sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782",
"ResolvConfPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/resolv.conf",
"HostnamePath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hostname",
"HostsPath": "/var/lib/docker/containers/aa86eacfb3b3ed4cd362c1e88fc89a53908ad05fb3a4103bca3f9b28292d14bf/hosts",
"LogPath": "/var/lib/docker/containers/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59/5b7c7e2b992aa426584ce6c47452756066be0e503a08b4516a433a54d2f69e59-json.log",
"Name": "/funny_chatelet",
"RestartCount": 0,
"Driver": "overlayfs",
"Platform": "linux",
"ImageManifestDescriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"MountLabel": "",
"ProcessLabel": "",
"AppArmorProfile": "",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"CpuShares": 0,
"Memory": 0,
"CgroupParent": "string",
"BlkioWeight": 1000,
"BlkioWeightDevice": [
{
"Path": "string",
"Weight": 0
}
],
"BlkioDeviceReadBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteBps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceReadIOps": [
{
"Path": "string",
"Rate": 0
}
],
"BlkioDeviceWriteIOps": [
{
"Path": "string",
"Rate": 0
}
],
"CpuPeriod": 0,
"CpuQuota": 0,
"CpuRealtimePeriod": 0,
"CpuRealtimeRuntime": 0,
"CpusetCpus": "0-3",
"CpusetMems": "string",
"Devices": [
{
"PathOnHost": "/dev/deviceName",
"PathInContainer": "/dev/deviceName",
"CgroupPermissions": "mrw"
}
],
"DeviceCgroupRules": [
"c 13:* rwm"
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"KernelMemoryTCP": 0,
"MemoryReservation": 0,
"MemorySwap": 0,
"MemorySwappiness": 100,
"NanoCpus": 0,
"OomKillDisable": true,
"Init": true,
"PidsLimit": 0,
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
],
"CpuCount": 0,
"CpuPercent": 0,
"IOMaximumIOps": 0,
"IOMaximumBandwidth": 0,
"Binds": [
"string"
],
"ContainerIDFile": "",
"LogConfig": {
"Type": "local",
"Config": {
"max-file": "5",
"max-size": "10m"
}
},
"NetworkMode": "string",
"PortBindings": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"VolumeDriver": "string",
"VolumesFrom": [
"string"
],
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"ConsoleSize": [
80,
64
],
"Annotations": {
"property1": "string",
"property2": "string"
},
"CapAdd": [
"string"
],
"CapDrop": [
"string"
],
"CgroupnsMode": "private",
"Dns": [
"string"
],
"DnsOptions": [
"string"
],
"DnsSearch": [
"string"
],
"ExtraHosts": [
"string"
],
"GroupAdd": [
"string"
],
"IpcMode": "string",
"Cgroup": "string",
"Links": [
"string"
],
"OomScoreAdj": 500,
"PidMode": "string",
"Privileged": true,
"PublishAllPorts": true,
"ReadonlyRootfs": true,
"SecurityOpt": [
"string"
],
"StorageOpt": {
"property1": "string",
"property2": "string"
},
"Tmpfs": {
"property1": "string",
"property2": "string"
},
"UTSMode": "string",
"UsernsMode": "string",
"ShmSize": 0,
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Runtime": "string",
"Isolation": "default",
"MaskedPaths": [
"/proc/asound",
"/proc/acpi",
"/proc/kcore",
"/proc/keys",
"/proc/latency_stats",
"/proc/timer_list",
"/proc/timer_stats",
"/proc/sched_debug",
"/proc/scsi",
"/sys/firmware",
"/sys/devices/virtual/powercap"
],
"ReadonlyPaths": [
"/proc/bus",
"/proc/fs",
"/proc/irq",
"/proc/sys",
"/proc/sysrq-trigger"
]
},
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"SizeRw": "122880",
"SizeRootFs": "1653948416",
"Mounts": [
{
"Type": "volume",
"Name": "myvolume",
"Source": "/var/lib/docker/volumes/myvolume/_data",
"Destination": "/usr/share/nginx/html/",
"Driver": "local",
"Mode": "z",
"RW": true,
"Propagation": ""
}
],
"Config": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"NetworkSettings": {
"Bridge": "docker0",
"SandboxID": "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": "",
"Ports": {
"443/tcp": [
{
"HostIp": "127.0.0.1",
"HostPort": "4443"
}
],
"80/tcp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
},
{
"HostIp": "0.0.0.0",
"HostPort": "8080"
}
],
"80/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "80"
}
],
"53/udp": [
{
"HostIp": "0.0.0.0",
"HostPort": "53"
}
],
"2377/tcp": null
},
"SandboxKey": "/var/run/docker/netns/8ab54b426c38",
"SecondaryIPAddresses": [
{
"Addr": "string",
"PrefixLen": 0
}
],
"SecondaryIPv6Addresses": [
{
"Addr": "string",
"PrefixLen": 0
}
],
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"MacAddress": "02:42:ac:11:00:04",
"Networks": {
"property1": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
},
"property2": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"MacAddress": "02:42:ac:11:00:04",
"Aliases": [
"server_x",
"server_y"
],
"DriverOpts": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"GwPriority": [
10
],
"NetworkID": "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a",
"EndpointID": "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.4",
"IPPrefixLen": 16,
"IPv6Gateway": "2001:db8:2::100",
"GlobalIPv6Address": "2001:db8::5689",
"GlobalIPv6PrefixLen": 64,
"DNSNames": [
"foobar",
"server_x",
"server_y",
"my.ctr"
]
}
}
}
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.51/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": {
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
]
},
"Processes": {
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.51/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.51/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.51/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.51/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"name": "boring_wozniak",
"id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"read": "2025-01-16T13:55:22.165243637Z",
"preread": "2025-01-16T13:55:21.160452595Z",
"pids_stats": {
"current": 5,
"limit": "18446744073709551615"
},
"blkio_stats": {
"io_service_bytes_recursive": [
{
"major": 254,
"minor": 0,
"op": "read",
"value": 7593984
},
{
"major": 254,
"minor": 0,
"op": "write",
"value": 100
}
],
"io_serviced_recursive": null,
"io_queue_recursive": null,
"io_service_time_recursive": null,
"io_wait_time_recursive": null,
"io_merged_recursive": null,
"io_time_recursive": null,
"sectors_recursive": null
},
"num_procs": 16,
"storage_stats": {
"read_count_normalized": 7593984,
"read_size_bytes": 7593984,
"write_count_normalized": 7593984,
"write_size_bytes": 7593984
},
"cpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"total_usage": 29912000,
"percpu_usage": [
29912000
],
"usage_in_kernelmode": 21994000,
"usage_in_usermode": 7918000
},
"system_cpu_usage": 5,
"online_cpus": 5,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"memory_stats": {
"usage": 0,
"max_usage": 0,
"stats": {
"active_anon": 1572864,
"active_file": 5115904,
"anon": 1572864,
"anon_thp": 0,
"file": 7626752,
"file_dirty": 0,
"file_mapped": 2723840,
"file_writeback": 0,
"inactive_anon": 0,
"inactive_file": 2510848,
"kernel_stack": 16384,
"pgactivate": 0,
"pgdeactivate": 0,
"pgfault": 2042,
"pglazyfree": 0,
"pglazyfreed": 0,
"pgmajfault": 45,
"pgrefill": 0,
"pgscan": 0,
"pgsteal": 0,
"shmem": 0,
"slab": 1180928,
"slab_reclaimable": 725576,
"slab_unreclaimable": 455352,
"sock": 0,
"thp_collapse_alloc": 0,
"thp_fault_alloc": 1,
"unevictable": 0,
"workingset_activate": 0,
"workingset_nodereclaim": 0,
"workingset_refault": 0
},
"failcnt": 0,
"limit": 8217579520,
"commitbytes": 0,
"commitpeakbytes": 0,
"privateworkingset": 0
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.51/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.51/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.51/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.51/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.51/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                                                                                                                                                                          |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                                                                                                                                                                            |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.                                                                                                                                                                    |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                                                                                                                                                                                    |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                                                                                                                                                                                    |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                                                                                                                                                                              |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                                                                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                                                                                                                                                                                 |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                                                                                                                                                                                  |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                 |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                        |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                                                                                                                                                                            |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                                                                                                                                                                           |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                                                                                                                                                                           |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                                                                                                                                                                                  |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                                                                                                                                                                            |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                                                                                                                                                                                |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime.This field is omitted when empty.**Deprecated**: This field is deprecated as kernel 6.12 has deprecated `memory.kmem.tcp.limit_in_bytes` field for cgroups v1. This field will be removed in a future release. |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                                                                                                                                                                                 |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                                                                                                                                                                                   |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                                                                                                                                                                          |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                                                                                                                                                                            |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                                                                                                                                                                                |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                                                                                                                                                                           |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                                                                                                                                                                              |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                                                                                                                                                                       |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                                                                                                                                                                        |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                                                                                                                                                      |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                                                                                                                                                                                  |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                                                                                                                                                                               |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.                                                                                                                                                                    |

### Responses

/v1.51/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"Published ports are discarded when using host network mode"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.51/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.51/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.51/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.51/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.51/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.51/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.51/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.51/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.51/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.51/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.51/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                                             |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `until=<timestamp>` |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                                             |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                                                 |
| manifests   | booleanDefault: falseInclude `Manifests` in the image summary.                                                                                                                                                                                                                                                                                                                                       |

### Responses

/v1.51/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2,
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
}
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.51/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| keep-storage   | integer \<int64>Amount of disk space in bytes to keep for cache> **Deprecated**: This parameter is deprecated and has been renamed to "reserved-space". It is kept for backward compatibility and will be removed in API v1.52.                                                                                                                                                                                                                                          |
| reserved-space | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| max-used-space | integer \<int64>Maximum amount of disk space allowed to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                   |
| min-free-space | integer \<int64>Target amount of free disk space after pruning                                                                                                                                                                                                                                                                                                                                                                                                           |
| all            | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters        | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.51/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Pull or import an image.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. If the name includes a tag or digest, specific behavior applies:- If only `fromImage` includes a tag, that tag is used.
- If both `fromImage` and `tag` are provided, `tag` takes precedence.
- If `fromImage` includes a digest, the image is pulled by digest, and `tag` is ignored.
- If neither a tag nor digest is specified, all tags are pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.51/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| manifests | booleanDefault: falseInclude Manifests in the image summary.The `manifests` and `platform` options are mutually exclusive, and an error is produced if both are set.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show inspect. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.The `platform` and `manifests` options are mutually exclusive, and an error is produced if both are set.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.51/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Manifests": [
{
"ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Available": true,
"Size": {
"Total": 8213251,
"Content": 3987495
},
"Kind": "image",
"ImageData": {
"Platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"Containers": [
"ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
"abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
],
"Size": {
"Unpacked": 3987495
}
},
"AttestationData": {
"For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
}
}
],
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"DockerVersion": "27.0.1",
"Author": "",
"Config": {
"User": "web:web",
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.If the daemon provides a multi-platform image store, this selects the platform-variant to show the history for. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.51/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag      | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed.                                                                                                                                                                                                                                                                                                                   |
| platform | stringJSON-encoded OCI platform to select the platform-variant to push. If not provided, all available variants will attempt to be pushed.If the daemon provides a multi-platform image store, this selects the platform-variant to push to the registry. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.51/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.51/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|           |                                                                                                                                                     |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| force     | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags                                              |
| noprune   | booleanDefault: falseDo not delete untagged parent images                                                                                           |
| platforms | Array of stringsSelect platform-specific content to delete. Multiple values are accepted. Each platform is a OCI platform encoded as a JSON string. |

### Responses

/v1.51/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                   |
| limit        | integerMaximum number of results to return                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.51/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "A minimal Docker image based on Alpine Linux with a complete package index and only 5 MB in size!",
"is_official": true,
"is_automated": false,
"name": "alpine",
"star_count": 10093
},
{
"description": "Busybox base image.",
"is_official": true,
"is_automated": false,
"name": "Busybox base image.",
"star_count": 3037
},
{
"description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
"is_official": true,
"is_automated": false,
"name": "postgres",
"star_count": 12408
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.51/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringCommands run as this user inside the container. If omitted, commands run as the user specified in the image the container was started from.Can be either user-name or UID, and optional group-name or GID, separated by a colon (`<user-name\|UID>[<:group-name\|GID>]`).                       |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.Deprecated: this field is deprecated in API v1.44 and up. Use EndpointSettings.MacAddress instead.                                                                                                                                                         |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.51/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "123:456",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains [Content as defined in the OCI Image Layout Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#content).

Additionally, includes the manifest.json file associated with a backwards compatible docker save format.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.51/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| names    | Array of stringsImage names to filter by                                                                                                                                                                                                                                                 |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be saved if the image is multi-platform. If not provided, the full multi-platform image will be saved.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

### Responses

/v1.51/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|          |                                                                                                                                                                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| quiet    | booleanDefault: falseSuppress progress details during load.                                                                                                                                                                                                                              |
| platform | stringJSON encoded OCI platform describing a platform which will be used to select a platform-specific image to be load if the image is multi-platform. If not provided, the full multi-platform image will be loaded.Example: `{"os": "linux", "architecture": "arm", "variant": "v5"}` |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.51/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.51/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv4": true,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv4": false,
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.51/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv4": true,
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.51/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|              |                                                                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namerequired | stringThe network's name.                                                                                                                                                                                                              |
| Driver       | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                       |
| Scope        | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                              |
| Internal     | booleanRestrict external access to the network.                                                                                                                                                                                        |
| Attachable   | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                |
| Ingress      | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                   |
| ConfigOnly   | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services. |
|              | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                  |
|              | object (IPAM)                                                                                                                                                                                                                          |
| EnableIPv4   | booleanEnable IPv4 on the network.                                                                                                                                                                                                     |
| EnableIPv6   | booleanEnable IPv6 on the network.                                                                                                                                                                                                     |
|              | objectNetwork specific options to be used by the drivers.                                                                                                                                                                              |
|              | objectUser-defined key/value metadata.                                                                                                                                                                                                 |

### Responses

/v1.51/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv4": true,
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "b5c4fc71e8022147cd25de22b22173de4e3b170134117172eb595cb91b4e7e5d",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

The network must be either a local-scoped network or a swarm-scoped network with the `attachable` option set. A network cannot be re-attached to a running container

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.51/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
},
"MacAddress": "02:42:ac:12:05:02",
"Priority": 100
}
}`

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.51/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.51/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.51/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.51/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.51/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.51/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.51/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.51/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.51/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.51/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.51/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.51/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.51/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.51/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.51/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.51/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.51/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.51/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.51/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.51/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.51/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.51/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.51/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.51/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.51/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.51/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.51/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringName of the service.                                                                                                                                                                               |
|      | objectUser-defined key/value metadata.                                                                                                                                                                   |
|      | object (TaskSpec)User modifiable task configuration.                                                                                                                                                     |
|      | objectScheduling mode for the service.                                                                                                                                                                   |
|      | objectSpecification for the update strategy of the service.                                                                                                                                              |
|      | objectSpecification for the rollback strategy of the service.                                                                                                                                            |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to.Deprecated: This field is deprecated since v1.44. The Networks field in TaskSpec should be used instead. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.                                                                                                             |

### Responses

/v1.51/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
},
"Seccomp": {
"Mode": "default",
"Profile": "string"
},
"AppArmor": {
"Mode": "default"
},
"NoNewPrivileges": true
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false,
"ReadOnlyNonRecursive": false,
"ReadOnlyForceRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
},
"Subpath": "dir-inside-volume/subdirectory"
},
"ImageOptions": {
"Subpath": "dir-inside-image/subdirectory"
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0,
"Options": [ [
"noexec"
]
]
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"OomScoreAdj": 0,
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warnings": [
"unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
]
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.51/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.51/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.51/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.51/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.51/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.51/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.51/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.51/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.51/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.51/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.51/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.51/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.51/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.51/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.51/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "string",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.51/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.51/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.51/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "string",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.51/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "string",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.51/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.51/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.51/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.51/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.51/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.51/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.51/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.51/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "6.8.0-31-generic",
"OperatingSystem": "Ubuntu 24.04 LTS",
"OSVersion": "24.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "27.0.1",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"FirewallBackend": {
"Driver": "nftables",
"Info": [ [
"ReloadedAt",
"2025-01-01T00:00:00Z"
]
]
},
"DiscoveredDevices": [
{
"Source": "cdi",
"ID": "vendor.com/gpu=0"
}
],
"Warnings": [
"WARNING: No memory limit support"
],
"CDISpecDirs": [
"/etc/cdi",
"/var/run/cdi"
],
"Containerd": {
"Address": "/run/containerd/containerd.sock",
"Namespaces": {
"Containers": "moby",
"Plugins": "plugins.moby"
}
}
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.51/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "27.0.1",
"Details": { }
}
],
"Version": "27.0.1",
"ApiVersion": "1.47",
"MinAPIVersion": "1.24",
"GitCommit": "48a66213fe",
"GoVersion": "go1.22.7",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "6.8.0-31-generic",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.51/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.51/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `create`, `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.51/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|      |                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |

### Responses

/v1.51/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parents": [ ],
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parents": [
"ndlpt0hhvkqcdfkputsk4cq9c"
],
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.51/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 424,
"urls": [
"http://example.com"
],
"annotations": {
"com.docker.official-images.bashbrew.arch": "amd64",
"org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
"org.opencontainers.image.base.name": "scratch",
"org.opencontainers.image.created": "2025-01-27T00:00:00Z",
"org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
"org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
"org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
"org.opencontainers.image.version": "24.04"
},
"data": null,
"platform": {
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
},
"artifactType": null
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.51/session

----
url: https://docs.docker.com/enterprise/security/single-sign-on/faqs/idp-faqs/
----

# SSO identity provider FAQs

***

Table of contents

***

## [Can I use multiple identity providers with Docker SSO?](#can-i-use-multiple-identity-providers-with-docker-sso)

Yes, Docker supports multiple IdP configurations. A domain can be associated with multiple IdPs. Docker supports Entra ID (formerly Azure AD) and identity providers that support SAML 2.0.

## [Can I change my identity provider after configuring SSO?](#can-i-change-my-identity-provider-after-configuring-sso)

Yes. Delete your existing IdP configuration in your Docker SSO connection, then [configure SSO using your new IdP](https://docs.docker.com/enterprise/security/single-sign-on/connect/). If you had already turned on enforcement, turn off enforcement before updating the provider connection.

## [What information do I need from my identity provider to configure SSO?](#what-information-do-i-need-from-my-identity-provider-to-configure-sso)

To turn on SSO in Docker, you need the following from your IdP:

* SAML: Entity ID, ACS URL, Single Logout URL, and the public X.509 certificate
* Entra ID (formerly Azure AD): Client ID, Client Secret, AD Domain

## [What happens if my existing certificate expires?](#what-happens-if-my-existing-certificate-expires)

Contact your identity provider to retrieve a new X.509 certificate. Update with the new certificate in [SSO configuration settings](https://docs.docker.com/enterprise/security/single-sign-on/manage/#manage-sso-connections) from Docker Admin Console.

* If your organization enforces SSO, username and password credentials won't work.
* If your organization doesn't enforce SSO, users can sign in with their username and password credentials.

If you need additional help, contact [Docker support](https://app.docker.com/support/contact).

## [What happens if my IdP goes down when SSO is turned on?](#what-happens-if-my-idp-goes-down-when-sso-is-turned-on)

If SSO is enforced, users can't access Docker Hub when your IdP is down. Users can still access Docker Hub images from the CLI using personal access tokens.

If SSO is turned on but not enforced, users can fall back to username/password authentication.

## [Do bot accounts need seats to access organizations using SSO?](#do-bot-accounts-need-seats-to-access-organizations-using-sso)

Yes, bot accounts need seats like regular users, requiring a non-aliased domain email in the IdP and using a seat in Docker Hub. You can add bot accounts to your IdP and create access tokens to replace other credentials.

## [Does SAML SSO use Just-in-Time provisioning?](#does-saml-sso-use-just-in-time-provisioning)

The SSO implementation uses Just-in-Time (JIT) provisioning by default. You can optionally turn off JIT in the Admin Console if you turn on auto-provisioning using SCIM. See [Just-in-Time provisioning](https://docs.docker.com/enterprise/security/provisioning/just-in-time/).

## [My Entra ID SSO connection isn't working and shows an error. How can I troubleshoot this?](#my-entra-id-sso-connection-isnt-working-and-shows-an-error-how-can-i-troubleshoot-this)

Confirm that you've configured the necessary API permissions in Entra ID for your SSO connection. You need to grant administrator consent within your Entra ID tenant. See [Entra ID (formerly Azure AD) documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/grant-admin-consent?pivots=portal#grant-admin-consent-in-app-registrations).

----
url: https://docs.docker.com/enterprise/security/single-sign-on/faqs/enforcement-faqs/
----

# SSO enforcement FAQs

***

Table of contents

***

## [Does Docker SSO support authenticating through the command line?](#does-docker-sso-support-authenticating-through-the-command-line)

When SSO is enforced, [passwords are prevented from accessing the Docker CLI](https://docs.docker.com/security/security-announcements/#deprecation-of-password-logins-on-cli-when-sso-enforced). You must use a personal access token (PAT) for CLI authentication instead.

Each user must create a PAT to access the CLI. To learn how to create a PAT, see [Manage personal access tokens](https://docs.docker.com/security/access-tokens/). Users who already used a PAT before SSO enforcement can continue using that PAT.

## [How does SSO affect automation systems and CI/CD pipelines?](#how-does-sso-affect-automation-systems-and-cicd-pipelines)

Before enforcing SSO, you must [create personal access tokens](https://docs.docker.com/security/access-tokens/) to replace passwords in automation systems and CI/CD pipelines.

## [Can I turn on SSO without enforcing it immediately?](#can-i-turn-on-sso-without-enforcing-it-immediately)

Yes, you can turn on SSO without enforcement. Users can choose between Docker ID (standard email and password) or domain-verified email address (SSO) at the sign-in screen.

## [SSO is enforced, but a user can sign in using a username and password. Why is this happening?](#sso-is-enforced-but-a-user-can-sign-in-using-a-username-and-password-why-is-this-happening)

Guest users who aren't part of your registered domain but have been invited to your organization don't sign in through your SSO identity provider. SSO enforcement only applies to users who belong to your verified domain.

## [Can I test SSO functionality before going to production?](#can-i-test-sso-functionality-before-going-to-production)

Yes, you can create a test organization with a 5-seat Business subscription. When testing, turn on SSO but don't enforce it, or all domain email users will be forced to sign in to the test environment.

## [What is enforcing SSO versus enforcing sign-in?](#what-is-enforcing-sso-versus-enforcing-sign-in)

These are separate features you can use independently or together:

* Enforcing SSO ensures users sign in using SSO credentials instead of their Docker ID, enabling better credential management.
* Enforcing sign-in to Docker Desktop ensures users always sign in to accounts that are members of your organization, so security settings and subscription benefits are always applied.

For more details, see [Enforce sign-in for Desktop](https://docs.docker.com/enterprise/security/enforce-sign-in/#enforcing-sign-in-versus-enforcing-single-sign-on-sso).

----
url: https://docs.docker.com/reference/cli/docker/secret/create/
----

# docker secret create

***

| Description | Create a secret from a file or STDIN as content   |
| ----------- | ------------------------------------------------- |
| Usage       | `docker secret create [OPTIONS] SECRET [file\|-]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Creates a secret using standard input or from a file for the secret content.

For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/).

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                  | Default | Description               |
| ----------------------- | ------- | ------------------------- |
| `-d, --driver`          |         | API 1.31+ Secret driver   |
| [`-l, --label`](#label) |         | Secret labels             |
| `--template-driver`     |         | API 1.37+ Template driver |

## [Examples](#examples)

### [Create a secret](#create-a-secret)

```console
$ printf "my super secret password" | docker secret create my_secret -

onakdyv307se2tl7nl20anokv

$ docker secret ls

ID                          NAME                CREATED             UPDATED
onakdyv307se2tl7nl20anokv   my_secret           6 seconds ago       6 seconds ago
```

### [Create a secret with a file](#create-a-secret-with-a-file)

```console
$ docker secret create my_secret ./secret.json

dg426haahpi5ezmkkj5kyl3sn

$ docker secret ls

ID                          NAME                CREATED             UPDATED
dg426haahpi5ezmkkj5kyl3sn   my_secret           7 seconds ago       7 seconds ago
```

### [Create a secret with labels (--label)](#label)

```console
$ docker secret create \
  --label env=dev \
  --label rev=20170324 \
  my_secret ./secret.json

eo7jnzguqgtpdah3cm5srfb97
```

```console
$ docker secret inspect my_secret

[
    {
        "ID": "eo7jnzguqgtpdah3cm5srfb97",
        "Version": {
            "Index": 17
        },
        "CreatedAt": "2017-03-24T08:15:09.735271783Z",
        "UpdatedAt": "2017-03-24T08:15:09.735271783Z",
        "Spec": {
            "Name": "my_secret",
            "Labels": {
                "env": "dev",
                "rev": "20170324"
            }
        }
    }
]
```

----
url: https://docs.docker.com/ai/sandboxes/troubleshooting/
----

***

Table of contents

***

## [Run diagnostics](#run-diagnostics)

Before digging into a specific issue, run [`sbx diagnose`](/reference/cli/sbx/diagnose/) to check for common problems with your installation, such as a missing CLI binary, an unresponsive daemon, a CLI/daemon version mismatch, missing storage directories, or broken authentication.

```console
$ sbx diagnose
```

The command prints a summary of checks that passed, warned, or failed, along with suggested fixes. Use `--output json` to get machine-readable output, or `--output github-issue` to generate a Markdown snippet suitable for pasting into a GitHub issue.

## [Resetting sandboxes](#resetting-sandboxes)

If you hit persistent issues or corrupted state, run [`sbx reset`](/reference/cli/sbx/reset/) to stop all VMs and delete all sandbox data. Create fresh sandboxes afterwards.

## [Agent can't install packages or reach an API](#agent-cant-install-packages-or-reach-an-api)

Sandboxes use a [deny-by-default network policy](https://docs.docker.com/ai/sandboxes/security/policy/). If the agent fails to install packages or call an external API, the target domain is likely not in the allow list. Check which requests are being blocked:

```console
$ sbx policy log
```

Then allow the domains your workflow needs:

```console
$ sbx policy allow network -g "*.npmjs.org,*.pypi.org,files.pythonhosted.org"
```

To allow all outbound traffic instead:

```console
$ sbx policy allow network -g "**"
```

If `sbx policy allow` doesn't unblock the request, your organization may manage sandbox policies centrally and take precedence over local rules. See [Organization governance](https://docs.docker.com/ai/sandboxes/security/governance/).

## [SSH and other non-HTTP connections fail](#ssh-and-other-non-http-connections-fail)

Non-HTTP TCP connections like SSH can be allowed by adding a policy rule for the destination IP address and port. For example, to allow SSH to a specific host:

```console
$ sbx policy allow network -g "10.1.2.3:22"
```

Hostname-based rules (for example, `myhost:22`) don't work for non-HTTP connections because the proxy can't resolve the hostname to an IP address in this context. Use the IP address directly.

UDP and ICMP traffic is blocked at the network layer and can't be unblocked with policy rules.

For Git operations over SSH, you can either add an allow rule for the Git server's IP address or use HTTPS URLs instead:

```console
$ git clone https://github.com/owner/repo.git
```

## [Can't reach a service running on the host](#cant-reach-a-service-running-on-the-host)

If a request to `127.0.0.1` or a local network IP returns "connection refused" from inside a sandbox, the address is not reachable from within the sandbox VM. See [Accessing host services from a sandbox](https://docs.docker.com/ai/sandboxes/usage/#accessing-host-services-from-a-sandbox).

## [Docker authentication failure](#docker-authentication-failure)

If you see a message like `You are not authenticated to Docker`, your login session has expired. In an interactive terminal, the CLI prompts you to sign in again. In non-interactive environments such as scripts or CI, run `sbx login` to re-authenticate.

## [Agent authentication failure](#agent-authentication-failure)

If the agent can't reach its model provider or you see API key errors, the key is likely invalid, expired, or not configured. Verify it's set in your shell configuration file and that you sourced it or opened a new terminal.

For agents that use the [credential proxy](https://docs.docker.com/ai/sandboxes/security/credentials/), make sure you haven't set the API key to an invalid value inside the sandbox — the proxy injects credentials automatically on outbound requests.

If credentials are configured correctly but API calls still fail, check `sbx policy log` and look at the **PROXY** column. Requests routed through the `transparent` proxy don't get credential injection. This can happen when a client inside the sandbox (such as a process in a Docker container) isn't configured to use the forward proxy. See [Monitoring network activity](https://docs.docker.com/ai/sandboxes/security/policy/#monitoring) for details.

## [Docker build export fails with an ownership error](#docker-build-export-fails-with-an-ownership-error)

Running `docker build` with the local exporter (`--output=type=local` or `-o <path>`) inside a sandbox fails because the exporter tries to `lchown` output files to preserve ownership from the build. Processes inside the sandbox run as an unprivileged user without `CAP_CHOWN`, so the operation is denied.

Use the tar exporter and extract the archive instead:

```console
$ mkdir -p ./result
$ docker build --output type=tar,dest=- . | tar xf - -C ./result
```

Extracting the tar archive as the current user avoids the `chown` call.

## [Stale Git worktree after removing a sandbox](#stale-git-worktree-after-removing-a-sandbox)

If you used `--branch`, worktree cleanup during `sbx rm` is best-effort. If it fails, the sandbox is removed but the branch and worktree are left behind. If `git worktree list` shows a stale worktree in `.sbx/` after removing a sandbox, clean it up manually:

```console
$ git worktree remove .sbx/<sandbox-name>-worktrees/<branch-name>
$ git branch -D <branch-name>
```

## [Sandbox commits aren't signed](#sandbox-commits-arent-signed)

Docker Sandboxes can sign Git commits with SSH keys from your host agent. For setup steps, see [Signed commits](https://docs.docker.com/ai/sandboxes/usage/#signed-commits).

If `ssh-add -L` prints `The agent has no identities.`, the sandbox can reach the forwarded agent, but the host agent doesn't have a loaded key. Load the signing key into your host SSH agent:

```console
$ ssh-add ~/.ssh/id_ed25519
```

If commit signing works on the host but fails in a sandbox, check whether Git is configured to sign with a host file path such as `/Users/me/.ssh/id_ed25519.pub`. The sandbox uses the forwarded SSH agent, not the host key file path. Use the inline public key form instead:

```console
$ git config --global gpg.format ssh
$ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"
```

If Git reports that `ssh-keygen` is missing, use a sandbox template that includes OpenSSH client tools.

If `git log --show-signature` reports that `gpg.ssh.allowedSignersFile` needs to be configured, Git can't verify the SSH signature locally. This verification config isn't required to create signed commits. GitHub uses the SSH signing keys configured in your GitHub account to verify commits.

GPG and S/MIME signing keys aren't available inside the sandbox. If your repository or organization requires GPG or S/MIME signatures, or if SSH signing isn't configured, use one of these workarounds:

* Commit outside the sandbox. Let the agent make changes without committing, then commit and sign from your host terminal.

* Sign after the fact. Let the agent commit inside the sandbox, then re-sign the commits on your host:

  ```console
  $ git rebase --exec 'git commit --amend --no-edit -S' origin/main
  ```

  This replays each commit on the branch and re-signs it with your local signing key.

## [Daemon fails to start after downgrading](#daemon-fails-to-start-after-downgrading)

If you downgrade `sbx` to a version older than the one that last managed your local state, the daemon may fail to start with a database version mismatch:

```text
ERROR: failed to start backend in-process: start backend: creating containerd
server: ... database is at major version 6, but this binary only supports up
to major version 1
```

A newer version of `sbx` upgraded the local database to a schema that older binaries don't understand. To recover, reset all sandbox state:

```console
$ sbx reset --preserve-secrets
```

This stops all VMs and deletes all sandbox data. You'll need to create new sandboxes afterwards. The `--preserve-secrets` flag keeps any secrets you've set so you don't have to reconfigure them.

## [Removing all state](#removing-all-state)

As a last resort, if `sbx reset` doesn't resolve your issue, you can remove the `sbx` state directory entirely. This deletes all sandbox data, configuration, and cached images. Stop all running sandboxes first with `sbx reset`.

```console
$ rm -rf ~/Library/Application\ Support/com.docker.sandboxes/
```

```powershell
> Remove-Item -Recurse -Force "$env:LOCALAPPDATA\DockerSandboxes"
```

Sandbox state on Linux follows the XDG Base Directory specification and is spread across three directories:

```console
$ rm -rf ~/.local/state/sandboxes/
$ rm -rf ~/.cache/sandboxes/
$ rm -rf ~/.config/sandboxes/
```

If you have set custom `XDG_STATE_HOME`, `XDG_CACHE_HOME`, or `XDG_CONFIG_HOME` environment variables, replace `~/.local/state`, `~/.cache`, and `~/.config` with the corresponding values.

## [Report an issue](#report-an-issue)

If you've exhausted the steps above and the problem persists, file a GitHub issue at [github.com/docker/sbx-releases/issues](https://github.com/docker/sbx-releases/issues).

To help Docker investigate, generate a diagnostics bundle and share it when reporting the issue:

```console
$ sbx diagnose --upload
```

The bundle contains daemon logs, diagnostic check results, and basic system information. When `--upload` is confirmed, the bundle is uploaded to Docker support and the command prints a diagnostics ID. Include this ID in your issue so the team can correlate it with the uploaded bundle.

----
url: https://docs.docker.com/build/policies/built-ins/
----

# Built-in functions

***

Table of contents

***

Buildx provides built-in functions, in addition to the [Rego built-ins](#rego-built-in-functions), to extend Rego policies with Docker-specific operations like loading local files, verifying Git signatures, and pinning image digests.

## [Rego built-in functions](#rego-built-in-functions)

The functions [documented on this page](#buildx-built-in-functions) are Buildx-specific functions, distinct from [Rego's standard built-in functions](https://www.openpolicyagent.org/docs/policy-language#built-in-functions)

Buildx also supports standard Rego built-in functions, but only a subset. To see the exact list of supported functions, refer to the Buildx [source code](https://github.com/docker/buildx/blob/master/policy/builtins.go).

## [Buildx built-in functions](#buildx-built-in-functions)

Buildx provides the following custom built-in functions for policy development:

* [`print`](#print)
* [`load_json`](#load_json)
* [`verify_git_signature`](#verify_git_signature)
* [`pin_image`](#pin_image)

### [`print`](#print)

Outputs debug information during policy evaluation.

Parameters:

* Any number of values to print

Returns: The values (pass-through)

Example:

```rego
allow if {
    input.image.repo == "alpine"
    print("Allowing alpine image:", input.image.tag)
}
```

Debug output appears when building with `--progress=plain`.

### [`load_json`](#load_json)

Loads and parses JSON data from local files in the build context.

Parameters:

* `filename` (string) - Path to JSON file relative to policy directory

Returns: Parsed JSON data as Rego value

Example:

```rego
# Load approved versions from external file
approved_versions = load_json("versions.json")

allow if {
    input.image.repo == "alpine"
    some version in approved_versions.alpine
    input.image.tag == version
}
```

File structure:

```text
project/
├── Dockerfile
├── Dockerfile.rego
└── versions.json
```

versions.json:

```json
{
  "alpine": ["3.19", "3.20"],
  "golang": ["1.21", "1.22"]
}
```

The JSON file must be in the same directory as the policy or in a subdirectory accessible from the policy location.

### [`verify_git_signature`](#verify_git_signature)

Verifies PGP signatures on Git commits or tags.

Parameters:

* `git_object` (object) - Either `input.git.commit` or `input.git.tag`
* `keyfile` (string) - Path to PGP public key file (relative to policy directory)

Returns: Boolean - `true` if signature is valid, `false` otherwise

Example:

```rego
# Require signed Git tags
allow if {
    input.git.tagName != ""
    verify_git_signature(input.git.tag, "maintainer.asc")
}

# Require signed commits
allow if {
    input.git.commit
    verify_git_signature(input.git.commit, "keys/team.asc")
}
```

Directory structure:

```text
project/
├── Dockerfile.rego
└── maintainer.asc          # PGP public key
```

Or with subdirectory:

```text
project/
├── Dockerfile.rego
└── keys/
    ├── maintainer.asc
    └── team.asc
```

Obtaining public keys:

```console
$ gpg --export --armor user@example.com > maintainer.asc
```

### [`pin_image`](#pin_image)

Pins an image to a specific digest, overriding the tag-based reference. Use this to force builds to use specific image versions.

Parameters:

* `image_object` (object) - Must be `input.image` (the current image being evaluated)
* `digest` (string) - Target digest in format `sha256:...`

Returns: Boolean - `true` if pinning succeeds

Example:

```rego
# Pin alpine 3.19 to specific digest
alpine_3_19_digest = "sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412"

allow if {
    input.image.repo == "alpine"
    input.image.tag == "3.19"
    pin_image(input.image, alpine_3_19_digest)
}
```

Automatic digest replacement:

```rego
# Replace old digests with patched versions
replace_map = {
  "3.22.0": "3.22.2",
  "3.22.1": "3.22.2",
}

alpine_digests = {
  "3.22.0": "sha256:8a1f59ffb675680d47db6337b49d22281a139e9d709335b492be023728e11715",
  "3.22.2": "sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412",
}

allow if {
    input.image.repo == "alpine"
    some old_version, new_version in replace_map
    input.image.checksum == alpine_digests[old_version]
    print("Replacing", old_version, "with", new_version)
    pin_image(input.image, alpine_digests[new_version])
}
```

This pattern automatically upgrades old image versions to patched releases.

## [Next steps](#next-steps)

* Browse complete examples: [Example policies](https://docs.docker.com/build/policies/examples/)
* Learn policy development workflow: [Using build policies](https://docs.docker.com/build/policies/usage/)
* Reference input fields: [Input reference](https://docs.docker.com/build/policies/inputs/)

----
url: https://docs.docker.com/guides/testcontainers-java-lifecycle/
----

# Testcontainers container lifecycle management using JUnit 5

Table of contents

***

Learn different approaches to manage container lifecycle with Testcontainers using JUnit 5 lifecycle callbacks, extension annotations, and the singleton containers pattern.

**Time to complete** 20 minutes

In this guide, you will learn how to:

* Start and stop containers using JUnit 5 lifecycle callbacks
* Manage containers using JUnit 5 extension annotations (`@Testcontainers` and `@Container`)
* Share containers across multiple test classes using the singleton containers pattern
* Avoid a common misconfiguration when combining extension annotations with singleton containers

## [Prerequisites](#prerequisites)

* Java 17+
* Your preferred IDE
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-lifecycle/create-project/)

   Set up a Java project with a PostgreSQL-backed customer service for lifecycle testing.

2. [Lifecycle callbacks](https://docs.docker.com/guides/testcontainers-java-lifecycle/lifecycle-callbacks/)

   Manage Testcontainers container lifecycle using JUnit 5 @BeforeAll and @AfterAll callbacks.

3. [Extension annotations](https://docs.docker.com/guides/testcontainers-java-lifecycle/extension-annotations/)

   Manage Testcontainers container lifecycle using @Testcontainers and @Container annotations.

4. [Singleton containers](https://docs.docker.com/guides/testcontainers-java-lifecycle/singleton-containers/)

   Share containers across multiple test classes using the singleton containers pattern.

----
url: https://docs.docker.com/tcc/
----

# Testcontainers Cloud

***

***

----
url: https://docs.docker.com/guides/testcontainers-dotnet-aspnet-core/create-project/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Set up the project

***

Table of contents

***

## [Background](#background)

This guide builds on top of Microsoft's [Integration tests in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests) documentation. The original sample uses an in-memory SQLite database as the backing store for integration tests. You'll replace SQLite with a real Microsoft SQL Server instance running in a Docker container using Testcontainers.

You can find the original code sample in the [dotnet/AspNetCore.Docs.Samples](https://github.com/dotnet/AspNetCore.Docs.Samples/tree/main/test/integration-tests/IntegrationTestsSample) repository.

## [Clone the repository](#clone-the-repository)

Clone the Testcontainers guide repository and change into the project directory:

```console
$ git clone https://github.com/testcontainers/tc-guide-testing-aspnet-core.git
$ cd tc-guide-testing-aspnet-core
```

## [Project structure](#project-structure)

The solution contains two projects:

```text
RazorPagesProject.sln
├── src/RazorPagesProject/              # ASP.NET Core Razor Pages app
└── tests/RazorPagesProject.Tests/      # xUnit integration tests
```

### [Application project](#application-project)

The application project (`src/RazorPagesProject/RazorPagesProject.csproj`) is a Razor Pages web app that uses Entity Framework Core with SQLite as its default database provider:

```xml
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="7.0.0" />
    <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="7.0.0" />
    <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="7.0.0" />
    <PackageReference Include="Microsoft.AspNetCore.Identity.UI" Version="7.0.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

</Project>
```

The `ApplicationDbContext` stores `Message` entities and provides methods to query and manage them:

```csharp
public class ApplicationDbContext : IdentityDbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options)
    {
    }

    public virtual DbSet<Message> Messages { get; set; }

    public async virtual Task<List<Message>> GetMessagesAsync()
    {
        return await Messages
            .OrderBy(message => message.Text)
            .AsNoTracking()
            .ToListAsync();
    }

    public async virtual Task AddMessageAsync(Message message)
    {
        await Messages.AddAsync(message);
        await SaveChangesAsync();
    }

    public async virtual Task DeleteAllMessagesAsync()
    {
        foreach (Message message in Messages)
        {
            Messages.Remove(message);
        }

        await SaveChangesAsync();
    }

    public async virtual Task DeleteMessageAsync(int id)
    {
        var message = await Messages.FindAsync(id);

        if (message != null)
        {
            Messages.Remove(message);
            await SaveChangesAsync();
        }
    }

    public void Initialize()
    {
        Messages.AddRange(GetSeedingMessages());
        SaveChanges();
    }

    public static List<Message> GetSeedingMessages()
    {
        return new List<Message>()
        {
            new Message(){ Text = "You're standing on my scarf." },
            new Message(){ Text = "Would you like a jelly baby?" },
            new Message(){ Text = "To the rational mind, nothing is inexplicable; only unexplained." }
        };
    }
}
```

### [Test project](#test-project)

The test project (`tests/RazorPagesProject.Tests/RazorPagesProject.Tests.csproj`) includes xUnit, the ASP.NET Core testing infrastructure, and the Testcontainers MSSQL module:

```xml
<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="AngleSharp" Version="0.17.1" />
    <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="7.0.0" />
    <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="7.0.0" />
    <PackageReference Include="Microsoft.AspNetCore.Identity.UI" Version="7.0.0" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="7.0.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="7.0.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="7.0.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="7.0.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="7.0.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>

    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.4.0" />

    <PackageReference Include="Testcontainers.MsSql" Version="3.0.0" />
    <PackageReference Include="xunit" Version="2.4.2" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="..\..\src\RazorPagesProject\RazorPagesProject.csproj" />
  </ItemGroup>

  <ItemGroup>
    <Content Update="xunit.runner.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </Content>
  </ItemGroup>

</Project>
```

The key dependencies are:

* `Microsoft.AspNetCore.Mvc.Testing` - provides `WebApplicationFactory` for bootstrapping the app in tests
* `Microsoft.EntityFrameworkCore.SqlServer` - the SQL Server database provider for Entity Framework Core
* `Testcontainers.MsSql` - the Testcontainers module for Microsoft SQL Server

### [Existing SQLite-based test factory](#existing-sqlite-based-test-factory)

The original project includes a `CustomWebApplicationFactory` that replaces the application's database with an in-memory SQLite instance:

```csharp
public class CustomWebApplicationFactory<TProgram>
    : WebApplicationFactory<TProgram> where TProgram : class
{
    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureServices(services =>
        {
            var dbContextDescriptor = services.SingleOrDefault(
                d => d.ServiceType ==
                    typeof(DbContextOptions<ApplicationDbContext>));

            services.Remove(dbContextDescriptor);

            var dbConnectionDescriptor = services.SingleOrDefault(
                d => d.ServiceType ==
                    typeof(DbConnection));

            services.Remove(dbConnectionDescriptor);

            // Create open SqliteConnection so EF won't automatically close it.
            services.AddSingleton<DbConnection>(container =>
            {
                var connection = new SqliteConnection("DataSource=:memory:");
                connection.Open();

                return connection;
            });

            services.AddDbContext<ApplicationDbContext>((container, options) =>
            {
                var connection = container.GetRequiredService<DbConnection>();
                options.UseSqlite(connection);
            });
        });

        builder.UseEnvironment("Development");
    }
}
```

While this approach works, SQLite has behavioral differences from the database you'd use in production. In the next section, you'll replace it with a Testcontainers-managed Microsoft SQL Server instance.

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-dotnet-aspnet-core/write-tests/)

----
url: https://docs.docker.com/ai/model-runner/inference-engines/
----

# Inference engines

***

Table of contents

***

Docker Model Runner supports three inference engines: **llama.cpp**, **vLLM**, and **Diffusers**. Each engine has different strengths, supported platforms, and model format requirements. This guide helps you choose the right engine and configure it for your use case.

## [Engine comparison](#engine-comparison)

| Feature               | llama.cpp                                            | vLLM                        | Diffusers                           |
| --------------------- | ---------------------------------------------------- | --------------------------- | ----------------------------------- |
| **Model formats**     | GGUF                                                 | Safetensors, HuggingFace    | DDUF                                |
| **Platforms**         | All (macOS, Windows, Linux)                          | Linux x86\_64 only          | Linux (x86\_64, ARM64)              |
| **GPU support**       | NVIDIA, AMD, Apple Silicon, Vulkan                   | NVIDIA CUDA only            | NVIDIA CUDA only                    |
| **CPU inference**     | Yes                                                  | No                          | No                                  |
| **Quantization**      | Built-in (Q4, Q5, Q8, etc.)                          | Limited                     | Limited                             |
| **Memory efficiency** | High (with quantization)                             | Moderate                    | Moderate                            |
| **Throughput**        | Good                                                 | High (with batching)        | Good                                |
| **Best for**          | Local development, resource-constrained environments | Production, high throughput | Image generation                    |
| **Use case**          | Text generation (LLMs)                               | Text generation (LLMs)      | Image generation (Stable Diffusion) |

## [llama.cpp](#llamacpp)

[llama.cpp](https://github.com/ggerganov/llama.cpp) is the default inference engine in Docker Model Runner. It's designed for efficient local inference and supports a wide range of hardware configurations.

### [Platform support](#platform-support)

| Platform              | GPU support         | Notes                           |
| --------------------- | ------------------- | ------------------------------- |
| macOS (Apple Silicon) | Metal               | Automatic GPU acceleration      |
| Windows (x64)         | NVIDIA CUDA         | Requires NVIDIA drivers 576.57+ |
| Windows (ARM64)       | Adreno OpenCL       | Qualcomm 6xx series and later   |
| Linux (x64)           | NVIDIA, AMD, Vulkan | Multiple backend options        |
| Linux                 | CPU only            | Works on any x64/ARM64 system   |

### [Model format: GGUF](#model-format-gguf)

llama.cpp uses the GGUF format, which supports efficient quantization for reduced memory usage without significant quality loss.

#### [Quantization levels](#quantization-levels)

| Quantization | Bits per weight | Memory usage | Quality       |
| ------------ | --------------- | ------------ | ------------- |
| Q2\_K        | \~2.5           | Lowest       | Reduced       |
| Q3\_K\_M     | \~3.5           | Minimal      | Acceptable    |
| Q4\_K\_M     | \~4.5           | Low          | Good          |
| Q5\_K\_M     | \~5.5           | Moderate     | Excellent     |
| Q6\_K        | \~6.5           | Higher       | Excellent     |
| Q8\_0        | 8               | High         | Near-original |
| F16          | 16              | Highest      | Original      |

**Recommended**: Q4\_K\_M offers the best balance of quality and memory usage for most use cases.

#### [Pulling quantized models](#pulling-quantized-models)

Models on Docker Hub often include quantization in the tag:

```console
$ docker model pull ai/llama3.2:3B-Q4_K_M
```

### [Using llama.cpp](#using-llamacpp)

llama.cpp is the default engine. No special configuration is required:

```console
$ docker model run ai/smollm2
```

To explicitly specify llama.cpp when running models:

```console
$ docker model run ai/smollm2 --backend llama.cpp
```

### [llama.cpp API endpoints](#llamacpp-api-endpoints)

When using llama.cpp, API calls use the llama.cpp engine path:

```text
POST /engines/llama.cpp/v1/chat/completions
```

Or without the engine prefix:

```text
POST /engines/v1/chat/completions
```

## [vLLM](#vllm)

[vLLM](https://github.com/vllm-project/vllm) is a high-performance inference engine optimized for production workloads with high throughput requirements.

### [Platform support](#platform-support-1)

| Platform          | GPU         | Support status                   |
| ----------------- | ----------- | -------------------------------- |
| Linux x86\_64     | NVIDIA CUDA | Supported                        |
| Windows with WSL2 | NVIDIA CUDA | Supported (Docker Desktop 4.54+) |
| macOS             | -           | Not supported                    |
| Linux ARM64       | -           | Not supported                    |
| AMD GPUs          | -           | Not supported                    |

> Important
>
> vLLM requires an NVIDIA GPU with CUDA support. It does not support CPU-only inference.

### [Model format: Safetensors](#model-format-safetensors)

vLLM works with models in Safetensors format, which is the standard format for HuggingFace models. These models typically use more memory than quantized GGUF models but may offer better quality and faster inference on powerful hardware.

### [Setting up vLLM](#setting-up-vllm)

#### [Docker Engine (Linux)](#docker-engine-linux)

Install the Model Runner with vLLM backend:

```console
$ docker model install-runner --backend vllm --gpu cuda
```

Verify the installation:

```console
$ docker model status
Docker Model Runner is running

Status:
llama.cpp: running llama.cpp version: c22473b
vllm: running vllm version: 0.11.0
```

#### [Docker Desktop (Windows with WSL2)](#docker-desktop-windows-with-wsl2)

1. Ensure you have:

   * Docker Desktop 4.54 or later (minimum version for vLLM support)
   * NVIDIA GPU with updated drivers
   * WSL2 enabled

2. Install vLLM backend:

   ```console
   $ docker model install-runner --backend vllm --gpu cuda
   ```

### [Running models with vLLM](#running-models-with-vllm)

vLLM models are typically tagged with `-vllm` suffix:

```console
$ docker model run ai/smollm2-vllm
```

To specify the vLLM backend explicitly:

```console
$ docker model run ai/model --backend vllm
```

### [vLLM API endpoints](#vllm-api-endpoints)

When using vLLM, specify the engine in the API path:

```text
POST /engines/vllm/v1/chat/completions
```

### [vLLM configuration](#vllm-configuration)

#### [HuggingFace overrides](#huggingface-overrides)

Use `--hf_overrides` to pass model configuration overrides:

```console
$ docker model configure --hf_overrides '{"max_model_len": 8192}' ai/model-vllm
```

#### [Common vLLM settings](#common-vllm-settings)

| Setting                  | Description                   | Example |
| ------------------------ | ----------------------------- | ------- |
| `max_model_len`          | Maximum context length        | 8192    |
| `gpu_memory_utilization` | Fraction of GPU memory to use | 0.9     |
| `tensor_parallel_size`   | GPUs for tensor parallelism   | 2       |

### [vLLM and llama.cpp performance comparison](#vllm-and-llamacpp-performance-comparison)

| Scenario                       | Recommended engine             |
| ------------------------------ | ------------------------------ |
| Single user, local development | llama.cpp                      |
| Multiple concurrent requests   | vLLM                           |
| Limited GPU memory             | llama.cpp (with quantization)  |
| Maximum throughput             | vLLM                           |
| CPU-only system                | llama.cpp                      |
| Apple Silicon Mac              | llama.cpp                      |
| Production deployment          | vLLM (if hardware supports it) |

## [Diffusers](#diffusers)

[Diffusers](https://github.com/huggingface/diffusers) is an inference engine for image generation models, including Stable Diffusion. Unlike llama.cpp and vLLM which focus on text generation with LLMs, Diffusers enables you to generate images from text prompts.

### [Platform support](#platform-support-2)

| Platform      | GPU         | Support status |
| ------------- | ----------- | -------------- |
| Linux x86\_64 | NVIDIA CUDA | Supported      |
| Linux ARM64   | NVIDIA CUDA | Supported      |
| Windows       | -           | Not supported  |
| macOS         | -           | Not supported  |

> Important
>
> Diffusers requires an NVIDIA GPU with CUDA support. It does not support CPU-only inference.

### [Setting up Diffusers](#setting-up-diffusers)

Install the Model Runner with Diffusers backend:

```console
$ docker model reinstall-runner --backend diffusers --gpu cuda
```

Verify the installation:

```console
$ docker model status
Docker Model Runner is running

Status:
llama.cpp: running llama.cpp version: 34ce48d
mlx: not installed
sglang: sglang package not installed
vllm: vLLM binary not found
diffusers: running diffusers version: 0.36.0
```

### [Pulling Diffusers models](#pulling-diffusers-models)

Pull a Stable Diffusion model:

```console
$ docker model pull stable-diffusion:Q4
```

### [Generating images with Diffusers](#generating-images-with-diffusers)

Diffusers uses an image generation API endpoint. To generate an image:

```console
$ curl -s -X POST http://localhost:12434/engines/diffusers/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stable-diffusion:Q4",
    "prompt": "A picture of a nice cat",
    "size": "512x512"
  }' | jq -r '.data[0].b64_json' | base64 -d > image.png
```

This command:

1. Sends a POST request to the Diffusers image generation endpoint
2. Specifies the model, prompt, and output image size
3. Extracts the base64-encoded image from the response
4. Decodes it and saves it as `image.png`

### [Diffusers API endpoint](#diffusers-api-endpoint)

When using Diffusers, specify the engine in the API path:

```text
POST /engines/diffusers/v1/images/generations
```

### [Supported parameters](#supported-parameters)

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `model`   | string | Required. The model identifier (e.g., `stable-diffusion:Q4`). |
| `prompt`  | string | Required. The text description of the image to generate.      |
| `size`    | string | Image dimensions in `WIDTHxHEIGHT` format (e.g., `512x512`).  |

## [Running multiple engines](#running-multiple-engines)

You can run llama.cpp, vLLM, and Diffusers simultaneously. Docker Model Runner routes requests to the appropriate engine based on the model or explicit engine selection.

Check which engines are running:

```console
$ docker model status
Docker Model Runner is running

Status:
llama.cpp: running llama.cpp version: 34ce48d
mlx: not installed
sglang: sglang package not installed
vllm: running vllm version: 0.11.0
diffusers: running diffusers version: 0.36.0
```

### [Engine-specific API paths](#engine-specific-api-paths)

| Engine      | API path                                   | Use case                              |
| ----------- | ------------------------------------------ | ------------------------------------- |
| llama.cpp   | `/engines/llama.cpp/v1/chat/completions`   | Text generation                       |
| vLLM        | `/engines/vllm/v1/chat/completions`        | Text generation                       |
| Diffusers   | `/engines/diffusers/v1/images/generations` | Image generation                      |
| Auto-select | `/engines/v1/chat/completions`             | Text generation (auto-selects engine) |

## [Managing inference engines](#managing-inference-engines)

### [Install an engine](#install-an-engine)

```console
$ docker model install-runner --backend <engine> [--gpu <type>]
```

Options:

* `--backend`: `llama.cpp`, `vllm`, or `diffusers`
* `--gpu`: `cuda`, `rocm`, `vulkan`, or `metal` (depends on platform)

### [Reinstall an engine](#reinstall-an-engine)

```console
$ docker model reinstall-runner --backend <engine>
```

### [Check engine status](#check-engine-status)

```console
$ docker model status
```

### [View engine logs](#view-engine-logs)

```console
$ docker model logs
```

## [Packaging models for each engine](#packaging-models-for-each-engine)

### [Package a GGUF model (llama.cpp)](#package-a-gguf-model-llamacpp)

```console
$ docker model package --gguf ./model.gguf --push myorg/mymodel:Q4_K_M
```

### [Package a Safetensors model (vLLM)](#package-a-safetensors-model-vllm)

```console
$ docker model package --safetensors ./model/ --push myorg/mymodel-vllm
```

## [Troubleshooting](#troubleshooting)

### [vLLM won't start](#vllm-wont-start)

1. Verify NVIDIA GPU is available:

   ```console
   $ nvidia-smi
   ```

2. Check Docker has GPU access:

   ```console
   $ docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi
   ```

3. Verify you're on a supported platform (Linux x86\_64 or Windows WSL2).

### [llama.cpp is slow](#llamacpp-is-slow)

1. Ensure GPU acceleration is working (check logs for Metal/CUDA messages).

2. Try a more aggressive quantization:

   ```console
   $ docker model pull ai/model:Q4_K_M
   ```

3. Reduce context size:

   ```console
   $ docker model configure --context-size 2048 ai/model
   ```

### [Out of memory errors](#out-of-memory-errors)

1. Use a smaller quantization (Q4 instead of Q8).
2. Reduce context size.
3. For vLLM, adjust `gpu_memory_utilization`:
   ```console
   $ docker model configure --hf_overrides '{"gpu_memory_utilization": 0.8}' ai/model
   ```

## [What's next](#whats-next)

* [Configuration options](https://docs.docker.com/ai/model-runner/configuration/) - Detailed parameter reference
* [API reference](https://docs.docker.com/ai/model-runner/api-reference/) - API documentation
* [GPU support](https://docs.docker.com/desktop/features/gpu/) - GPU configuration for Docker Desktop

----
url: https://docs.docker.com/reference/cli/docker/dhi/auth/apk/
----

# docker dhi auth apk

***

| Description | Create authentication details for DHI APK repositories |
| ----------- | ------------------------------------------------------ |
| Usage       | `docker dhi auth apk`                                  |

## [Description](#description)

Create authentication details for DHI APK repositories

----
url: https://docs.docker.com/reference/cli/docker/pass/rm/
----

# docker pass rm

***

| Description | Remove secrets from local keychain.      |
| ----------- | ---------------------------------------- |
| Usage       | `docker pass rm name1 name2 ... [flags]` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Removes one or more named secrets from the local OS keychain. Use --all to remove every stored secret at once.

## [Options](#options)

| Option  | Default | Description        |
| ------- | ------- | ------------------ |
| `--all` |         | Remove all secrets |

## [Examples](#examples)

### [Remove a specific secret:](#remove-a-specific-secret)

docker pass rm GH\_TOKEN

### [Remove multiple secrets:](#remove-multiple-secrets)

docker pass rm GH\_TOKEN NPM\_TOKEN

### [Remove all secrets:](#remove-all-secrets)

docker pass rm --all

----
url: https://docs.docker.com/offload/configuration/
----

# Configure Docker Offload

***

Table of contents

***

Subscription: Docker Offload

Requires: Docker Desktop 4.68 or later

You can configure Docker Offload settings at different levels depending on your role. Organization owners can manage settings for all users in their organization, while individual developers can configure their own Docker Desktop settings when allowed by their organization.

## [Manage settings for your organization](#manage-settings-for-your-organization)

For organization owners, you can manage Docker Offload settings for all users in your organization. For more details, see [Manage Docker products](https://docs.docker.com/admin/organization/manage/manage-products/). To view usage for Docker Offload, see [Docker Offload usage](/offload/usage/).

## [Configure settings in Docker Desktop](#configure-settings-in-docker-desktop)

For developers, you can enable or disable Docker Offload in Docker Desktop if allowed by your organization. To manage this setting:

1. Open the Docker Desktop Dashboard and sign in.
2. Select the settings icon in the Docker Desktop Dashboard header.
3. In **Settings**, select **Docker Offload**.
4. Toggle **Enable Docker Offload**. When enabled, you can start Offload sessions.

----
url: https://docs.docker.com/ai/sandboxes/security/policy/
----

# Policies

***

Table of contents

***

Sandboxes are [network-isolated](https://docs.docker.com/ai/sandboxes/security/isolation/) from your host and from each other. A policy system controls what a sandbox can access over the network.

Use the `sbx policy` command to configure network access rules. Rules apply to all sandboxes on the machine when you use the global scope. Network allow, deny, list, and remove commands can also target one sandbox.

If your organization manages sandbox policies centrally, organization rules take precedence over the local rules described on this page. See [Organization governance](https://docs.docker.com/ai/sandboxes/security/governance/).

## [Network policies](#network-policies)

The only way traffic can leave a sandbox is through an HTTP/HTTPS proxy on your host, which enforces access rules on every outbound request.

Non-HTTP TCP traffic, including SSH, can be allowed by adding a policy rule for the destination IP address and port (for example, `sbx policy allow network -g "10.1.2.3:22"`). UDP and ICMP traffic is blocked at the network layer and can't be unblocked with policy rules.

### [Initial policy selection](#initial-policy-selection)

On first start, and after running `sbx policy reset`, the daemon prompts you to choose a network policy:

```plaintext
Choose a default network policy:

     1. Open         — All network traffic allowed, no restrictions.
     2. Balanced     — Default deny, with common dev sites allowed.
     3. Locked Down  — All network traffic blocked unless you allow it.

  Use ↑/↓ to navigate, Enter to select, or press 1–3.
```

| Policy      | Description                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open        | All outbound traffic is allowed. No restrictions. Equivalent to adding a wildcard allow rule with `sbx policy allow network -g "**"`.                                                          |
| Balanced    | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. You can extend this with `sbx policy allow`. |
| Locked Down | All outbound traffic is blocked, including model provider APIs (for example, `api.anthropic.com`). You must explicitly allow everything you need.                                              |

You can change your effective policy at any time using `sbx policy allow` and `sbx policy deny`, or start over by running `sbx policy reset`.

> Note
>
> If your organization manages sandbox policies centrally, organization rules take precedence over the policy you select here. See [Organization governance](https://docs.docker.com/ai/sandboxes/security/governance/).

### [Non-interactive environments](#non-interactive-environments)

In non-interactive environments such as CI pipelines or headless servers, the interactive prompt can't be displayed. Use `sbx policy set-default` to set the default network policy before running any other `sbx` commands:

```console
$ sbx policy set-default balanced
```

Available values are `allow-all`, `balanced`, and `deny-all`. After setting the default, you can customize further with `sbx policy allow` and `sbx policy deny` as usual.

### [Default policy](#default-policy)

All outbound HTTP/HTTPS traffic is blocked by default unless an explicit rule allows it. The **Balanced** policy ships with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. Run `sbx policy ls` to see the active rules for your installation.

### [Managing rules](#managing-rules)

Use [`sbx policy allow`](/reference/cli/sbx/policy/allow/) and [`sbx policy deny`](/reference/cli/sbx/policy/deny/) to add network access rules. Changes take effect immediately. Pass `-g` to apply a rule to all sandboxes:

```console
$ sbx policy allow network -g api.anthropic.com
$ sbx policy deny network -g ads.example.com
```

Pass a sandbox name to scope a rule to one sandbox:

```console
$ sbx policy allow network my-sandbox api.example.com
$ sbx policy deny network my-sandbox ads.example.com
```

Specify multiple hosts in one command with a comma-separated list:

```console
$ sbx policy allow network -g "api.anthropic.com,*.npmjs.org,*.pypi.org"
```

List all active policy rules with `sbx policy ls`:

```console
$ sbx policy ls
NAME                  TYPE      ORIGIN               DECISION   STATUS   RESOURCES
balanced-dev          network   local                allow      active   api.anthropic.com
ads-block             network   local                deny       active   ads.example.com
kit:my-sandbox        network   sandbox:my-sandbox   allow      active   api.example.com
kit:my-sandbox:deny   network   sandbox:my-sandbox   deny       active   telemetry.example.com
```

The columns are:

* `NAME`: the rule name.
* `TYPE`: the rule type, such as `network`.
* `ORIGIN`: where the rule applies. `local` means the rule is global and applies to all sandboxes. `sandbox:<name>` means the rule is scoped to the named sandbox.
* `DECISION`: whether the rule allows or denies the resource.
* `STATUS`: whether the rule is currently in effect. A rule may be inactive if it's overridden by another rule, for example.
* `RESOURCES`: the hosts or patterns the rule applies to.

Use `--type network` to show only network policies. Without a sandbox argument, `sbx policy ls` shows every rule across all sandboxes. Pass a sandbox name to filter the list to global rules and rules scoped to that sandbox only:

```console
$ sbx policy ls my-sandbox
```

Remove a policy by resource or by rule ID:

```console
$ sbx policy rm network -g --resource ads.example.com
$ sbx policy rm network -g --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67
```

To remove a sandbox-scoped policy, include the sandbox name:

```console
$ sbx policy rm network my-sandbox --resource api.example.com
```

### [Resetting to defaults](#resetting-to-defaults)

To remove all custom policies and restore the default policy, use `sbx policy reset`:

```console
$ sbx policy reset
```

This deletes the local policy store and stops the daemon. When the daemon restarts on the next command, you are prompted to choose a new network policy. If sandboxes are running, they stop when the daemon shuts down. You are prompted for confirmation unless you pass `--force`:

```console
$ sbx policy reset --force
```

### [Switching to allow-by-default](#switching-to-allow-by-default)

If you prefer a permissive policy where all outbound traffic is allowed, add a wildcard allow rule:

```console
$ sbx policy allow network -g "**"
```

This lets agents install packages and call any external API without additional configuration. You can still deny specific hosts with `sbx policy deny`.

### [Wildcard syntax](#wildcard-syntax)

Rules support exact domains (`example.com`), wildcard subdomains (`*.example.com`), and optional port suffixes (`example.com:443`).

Note that `example.com` doesn't match subdomains, and `*.example.com` doesn't match the root domain. Specify both to cover both.

### [Common patterns](#common-patterns)

Allow access to package managers so agents can install dependencies:

```console
$ sbx policy allow network -g "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com"
```

The **Balanced** policy already includes AI provider APIs, package managers, code hosts, and container registries. You only need to add allow rules for additional domains your workflow requires. If you chose **Locked Down**, you must explicitly allow everything.

> Warning
>
> Allowing broad domains like `github.com` permits access to any content on that domain, including user-generated content. Only allow domains you trust with your data.

### [Monitoring](#monitoring)

Use `sbx policy log` to see which hosts your sandboxes have contacted:

```console
$ sbx policy log
Blocked requests:
SANDBOX      TYPE     HOST                   PROXY        RULE            REASON         LAST SEEN        COUNT
my-sandbox   network  blocked.example.com    transparent  domain-blocked  default-deny   10:15:25 29-Jan  1

Allowed requests:
SANDBOX      TYPE     HOST                   PROXY          RULE             REASON   LAST SEEN        COUNT
my-sandbox   network  api.anthropic.com      forward        domain-allowed            10:15:23 29-Jan  42
my-sandbox   network  registry.npmjs.org     forward-bypass domain-allowed            10:15:20 29-Jan  18
my-sandbox   network  app.example.com        browser-open                             10:15:10 29-Jan  1
```

The **PROXY** column shows how the request left the sandbox:

| Value            | Description                                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `forward`        | Routed through the forward proxy. Supports [credential injection](https://docs.docker.com/ai/sandboxes/security/credentials/). |
| `forward-bypass` | Routed through the forward proxy without credential injection.                                                                 |
| `transparent`    | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available.                            |
| `network`        | Non-HTTP traffic (raw TCP, UDP, ICMP). TCP can be allowed with a policy rule; UDP and ICMP are always blocked.                 |
| `browser-open`   | A sandbox process requested opening a URL in the host browser. Policy is enforced before opening the URL.                      |

The **RULE** column identifies the policy rule that matched the request. The **REASON** column includes extra context when the daemon records one.

Filter by sandbox name by passing it as an argument:

```console
$ sbx policy log my-sandbox
```

Use `--limit N` to show only the last `N` entries, `--json` for machine-readable output, or `--type network` to filter by policy type.

## [Precedence](#precedence)

All outbound traffic is blocked by default unless an explicit rule allows it. If a domain matches both an allow and a deny rule, the deny rule wins regardless of specificity. A sandbox-scoped deny rule can block a domain for one sandbox even when a global rule permits the same domain.

To unblock a domain, find the deny rule with `sbx policy ls` and remove it with `sbx policy rm`.

If your organization manages sandbox policies centrally, organization rules take precedence and local rules are not evaluated unless the admin delegates that rule type. See [Organization governance](https://docs.docker.com/ai/sandboxes/security/governance/).

## [Troubleshooting](#troubleshooting)

### [Policy changes not taking effect](#policy-changes-not-taking-effect)

If policy changes aren't taking effect, run `sbx policy reset` to wipe the local policy store and restart the daemon. On next start, you are prompted to choose a new network policy.

----
url: https://docs.docker.com/reference/api/engine/version/v1.41/
----

# Docker Engine API v1.41 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.41.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.41.yaml)

# Docker Engine API (1.41)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.41.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.41) is used. For example, calling `/info` is the same as calling `/v1.41/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.41/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.                                                                                                                                                                                                                                                           |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.41/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"KernelMemory": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
}
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "e90e34656806",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.41/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"AppArmorProfile": "",
"Args": [
"-c",
"exit 9"
],
"Config": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"/bin/sh",
"-c",
"exit 9"
],
"Domainname": "",
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Healthcheck": {
"Test": [
"CMD-SHELL",
"exit 0"
]
},
"Hostname": "ba033ac44011",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"MacAddress": "",
"NetworkDisabled": false,
"OpenStdin": false,
"StdinOnce": false,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"StopSignal": "SIGTERM",
"StopTimeout": 10
},
"Created": "2015-01-06T15:47:31.485331387Z",
"Driver": "overlay2",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 0,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"ContainerIDFile": "",
"CpusetCpus": "",
"CpusetMems": "",
"CpuPercent": 80,
"CpuShares": 0,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"Devices": [ ],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"IpcMode": "",
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"KernelMemory": 0,
"OomKillDisable": false,
"OomScoreAdj": 500,
"NetworkMode": "bridge",
"PidMode": "",
"PortBindings": { },
"Privileged": false,
"ReadonlyRootfs": false,
"PublishAllPorts": false,
"RestartPolicy": {
"MaximumRetryCount": 2,
"Name": "on-failure"
},
"LogConfig": {
"Type": "json-file"
},
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Ulimits": [
{ }
],
"VolumeDriver": "",
"ShmSize": 67108864
},
"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
"MountLabel": "",
"Name": "/boring_euclid",
"NetworkSettings": {
"Bridge": "",
"SandboxID": "",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": 0,
"SandboxKey": "",
"EndpointID": "",
"Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"MacAddress": "",
"Networks": {
"bridge": {
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
"EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Path": "/bin/sh",
"ProcessLabel": "",
"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
"RestartCount": 1,
"State": {
"Error": "",
"ExitCode": 9,
"FinishedAt": "2015-01-06T15:47:32.080254511Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2019-12-22T10:59:05.6385933Z",
"End": "2019-12-22T10:59:05.8078452Z",
"ExitCode": 0,
"Output": ""
}
]
},
"OOMKilled": false,
"Dead": false,
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z",
"Status": "running"
},
"Mounts": [
{
"Name": "fac362...80535",
"Source": "/data",
"Destination": "/data",
"Driver": "local",
"Mode": "ro,Z",
"RW": false,
"Propagation": ""
}
]
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.41/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
],
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.41/containers/{id}/logs

### Response samples

* 200
* 404
* 500

Content type

application/json

`"string"`

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified
* `1`: Added
* `2`: Deleted

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.41/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.41/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.41/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"read": "2015-01-08T22:57:31.547920715Z",
"pids_stats": {
"current": 3
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"memory_stats": {
"stats": {
"total_pgmajfault": 0,
"cache": 0,
"mapped_file": 0,
"total_inactive_file": 0,
"pgpgout": 414,
"rss": 6537216,
"total_mapped_file": 0,
"writeback": 0,
"unevictable": 0,
"pgpgin": 477,
"total_unevictable": 0,
"pgmajfault": 0,
"total_rss": 6537216,
"total_rss_huge": 6291456,
"total_writeback": 0,
"total_inactive_anon": 0,
"rss_huge": 6291456,
"hierarchical_memory_limit": 67108864,
"total_pgfault": 964,
"total_active_file": 0,
"active_anon": 6537216,
"total_active_anon": 6537216,
"total_pgpgout": 414,
"total_cache": 0,
"inactive_anon": 0,
"active_file": 0,
"pgfault": 964,
"inactive_file": 0,
"total_pgpgin": 477
},
"max_usage": 6651904,
"usage": 6537216,
"failcnt": 0,
"limit": 67108864
},
"blkio_stats": { },
"cpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24472255,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100215355,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 739306590000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24350896,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100093996,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 9492140000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.41/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.41/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|   |                                                               |
| - | ------------------------------------------------------------- |
| t | integerNumber of seconds to wait before killing the container |

### Responses

/v1.41/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|   |                                                               |
| - | ------------------------------------------------------------- |
| t | integerNumber of seconds to wait before killing the container |

### Responses

/v1.41/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.41/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemory       | integer \<int64>Kernel memory limit in bytes.> **Deprecated**: This field is deprecated as the kernel 5.4 deprecated `kmem.limit_in_bytes`.                                                                                                            |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes).                                                                                                                                                                                    |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.41/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"KernelMemory": 52428800,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"string"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.41/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.41/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.41/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.41/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |

### Responses

/v1.41/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.41/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.41/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.41/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.41/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.41/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.41/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| all     | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                       |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) |
| digests | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                           |

### Responses

/v1.41/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"VirtualSize": 172064416,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.41/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| keep-storage | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                    |
| all          | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                             |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<duration>`: duration relative to daemon's time, during which build cache was not used, in Go's duration format (e.g., '24h')
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.41/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Create an image by either pulling it from a registry or importing it.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                   |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed.                                                                                                             |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                     |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                 |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                       |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                      |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR` |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                     |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.41/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.41/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"Container": "65974bc86f1770ae4bff79f651ebdbce166ae9aada632ee3fa9af3a264911735",
"ContainerConfig": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"DockerVersion": "20.10.7",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "web:web",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": true,
"Image": "",
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"VirtualSize": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.41/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|     |                                                                                                                                                                 |
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed. |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.41/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.41/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|         |                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------ |
| force   | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags |
| noprune | booleanDefault: falseDo not delete untagged parent images                                              |

### Responses

/v1.41/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                                                       |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                                                  |
| limit        | integerMaximum number of results to return                                                                                                                                                                                                            |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-automated=(true\|false)`
- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.41/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "wma55/u1210sshd",
"star_count": 0
},
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "jdswinbank/sshd",
"star_count": 0
},
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "vgauthier/sshd",
"star_count": 0
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.41/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.                                                                                                                                                                                                                                                           |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.41/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains one directory per image layer (named using its long ID), each containing these files:

* `VERSION`: currently `1.0` - the file format version
* `json`: detailed layer information, similar to `docker inspect layer_id`
* `layer.tar`: A tarfile containing the filesystem changes in this layer

The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories for storing attribute changes and deletions.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.41/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                          |
| ----- | ---------------------------------------- |
| names | Array of stringsImage names to filter by |

### Responses

/v1.41/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                                             |
| ----- | ----------------------------------------------------------- |
| quiet | booleanDefault: falseSuppress progress details during load. |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.41/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.41/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.41/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.41/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Namerequired   | stringThe network's name.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| CheckDuplicate | booleanCheck for networks with duplicate names. Since Network is primarily keyed based on a random ID and not on the name, and network name is strictly a user-friendly alias to the network which is uniquely identified using ID, there is no guaranteed way to check for duplicates. CheckDuplicate is there to provide a best effort checking of any networks which has the same name but it is not guaranteed to catch all name collisions. |
| Driver         | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                                                                                                                                                                                                                                 |
| Scope          | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                                                                                                                                                                                                                                        |
| Internal       | booleanRestrict external access to the network.                                                                                                                                                                                                                                                                                                                                                                                                  |
| Attachable     | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                                                                                                                                                                                                                          |
| Ingress        | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                                                                                                                                                                                                                             |
| ConfigOnly     | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services.                                                                                                                                                                                                           |
|                | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                                                                                                                                                                                                                            |
|                | object (IPAM)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| EnableIPv6     | booleanEnable IPv6 on the network.                                                                                                                                                                                                                                                                                                                                                                                                               |
|                | objectNetwork specific options to be used by the drivers.                                                                                                                                                                                                                                                                                                                                                                                        |
|                | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                           |

### Responses

/v1.41/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"CheckDuplicate": true,
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.41/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
}
}
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.41/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.41/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.41/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |

### Responses

/v1.41/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.41/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.41/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.41/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.41/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|        |                                 |
| ------ | ------------------------------- |
| Detach | booleanDetach from the command. |
| Tty    | booleanAllocate a pseudo-TTY.   |

### Responses

/v1.41/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": false
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.41/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.41/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.41/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.41/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.41/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.41/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.41/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.41/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.41/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.41/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.41/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.41/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.41/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.41/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                  |
| ---- | ------------------------------------------------------------------------------------------------ |
| Name | stringName of the service.                                                                       |
|      | objectUser-defined key/value metadata.                                                           |
|      | object (TaskSpec)User modifiable task configuration.                                             |
|      | objectScheduling mode for the service.                                                           |
|      | objectSpecification for the update strategy of the service.                                      |
|      | objectSpecification for the rollback strategy of the service.                                    |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.     |

### Responses

/v1.41/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
}
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warning": "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.41/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.41/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                  |
| ---- | ------------------------------------------------------------------------------------------------ |
| Name | stringName of the service.                                                                       |
|      | objectUser-defined key/value metadata.                                                           |
|      | object (TaskSpec)User modifiable task configuration.                                             |
|      | objectScheduling mode for the service.                                                           |
|      | objectSpecification for the update strategy of the service.                                      |
|      | objectSpecification for the rollback strategy of the service.                                    |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.     |

### Responses

/v1.41/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
}
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warning": "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.41/services/{id}/logs

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`"string"`

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.41/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.41/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.41/tasks/{id}/logs

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`"string"`

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.41/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.41/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.41/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.41/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.41/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.41/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.41/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.41/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.41/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.41/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.41/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.41/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.41/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.41/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.41/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.41/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.41/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.41/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.41/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.41/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.41/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.41/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.41/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemory": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"BridgeNfIptables": true,
"BridgeNfIp6tables": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "4.9.38-moby",
"OperatingSystem": "Alpine Linux v3.5",
"OSVersion": "16.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"AllowNondistributableArtifactsCIDRs": [ ],
"AllowNondistributableArtifactsHostnames": [ ],
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "20.10.25",
"ClusterStore": "consul://consul.corp.example.com:8600/some/path",
"ClusterAdvertise": "node5.corp.example.com:8000",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"Warnings": [
"WARNING: No memory limit support"
]
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.41/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "19.03.12",
"Details": { }
}
],
"Version": "19.03.12",
"ApiVersion": "1.40",
"MinAPIVersion": "1.12",
"GitCommit": "48a66213fe",
"GoVersion": "go1.13.14",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "4.19.76-linuxkit",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.41/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.41/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.41/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

### Responses

/v1.41/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"VirtualSize": 1092588,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parent": "",
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parent": "ndlpt0hhvkqcdfkputsk4cq9c",
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.41/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 3987495
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.41/session

----
url: https://docs.docker.com/desktop/troubleshoot-and-support/faqs/windowsfaqs/
----

# FAQs for Docker Desktop for Windows

***

Table of contents

***

### [Can I use VirtualBox alongside Docker Desktop?](#can-i-use-virtualbox-alongside-docker-desktop)

Yes, you can run VirtualBox along with Docker Desktop if you have enabled the [Windows Hypervisor Platform](https://docs.microsoft.com/en-us/virtualization/api/) feature on your machine.

### [Why is Windows 10 or Windows 11 required?](#why-is-windows-10-or-windows-11-required)

Docker Desktop uses the Windows Hyper-V features. While older Windows versions have Hyper-V, their Hyper-V implementations lack features critical for Docker Desktop to work.

### [Can I run Docker Desktop on Windows Server?](#can-i-run-docker-desktop-on-windows-server)

No, running Docker Desktop on Windows Server is not supported.

### [How do symlinks work on Windows?](#how-do-symlinks-work-on-windows)

Docker Desktop supports two types of symlinks: Windows native symlinks and symlinks created inside a container.

The Windows native symlinks are visible within the containers as symlinks, whereas symlinks created inside a container are represented as [mfsymlinks](https://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks). These are regular Windows files with a special metadata. Therefore the symlinks created inside a container appear as symlinks inside the container, but not on the host.

### [File sharing with Kubernetes and WSL 2](#file-sharing-with-kubernetes-and-wsl-2)

Docker Desktop mounts the Windows host filesystem under `/run/desktop` inside the container running Kubernetes. See the [Stack Overflow post](https://stackoverflow.com/questions/67746843/clear-persistent-volume-from-a-kubernetes-cluster-running-on-docker-desktop/69273405#69273) for an example of how to configure a Kubernetes Persistent Volume to represent directories on the host.

### [How do I add custom CA certificates?](#how-do-i-add-custom-ca-certificates)

You can add trusted Certificate Authorities (CAs) to your Docker daemon to verify registry server certificates, and client certificates, to authenticate to registries.

Docker Desktop supports all trusted Certificate Authorities (CAs) (root or intermediate). Docker recognizes certs stored under Trust Root Certification Authorities or Intermediate Certification Authorities.

Docker Desktop creates a certificate bundle of all user-trusted CAs based on the Windows certificate store, and appends it to Moby trusted certificates. Therefore, if an enterprise SSL certificate is trusted by the user on the host, it is trusted by Docker Desktop.

To learn more about how to install a CA root certificate for the registry, see [Verify repository client with certificates](https://docs.docker.com/engine/security/certificates/) in the Docker Engine topics.

### [How do I add client certificates?](#how-do-i-add-client-certificates)

You can add your client certificates in `~/.docker/certs.d/<MyRegistry>:<Port>/client.cert` and `~/.docker/certs.d/<MyRegistry>:<Port>/client.key`. You do not need to push your certificates with `git` commands.

When the Docker Desktop application starts, it copies the `~/.docker/certs.d` folder on your Windows system to the `/etc/docker/certs.d` directory on Moby (the Docker Desktop virtual machine running on Hyper-V).

You need to restart Docker Desktop after making any changes to the keychain or to the `~/.docker/certs.d` directory in order for the changes to take effect.

The registry cannot be listed as an insecure registry (see [Docker Daemon](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine)). Docker Desktop ignores certificates listed under insecure registries, and does not send client certificates. Commands like `docker run` that attempt to pull from the registry produce error messages on the command line, as well as on the registry.

To learn more about how to set the client TLS certificate for verification, see [Verify repository client with certificates](https://docs.docker.com/engine/security/certificates/) in the Docker Engine topics.

----
url: https://docs.docker.com/guides/ruby/develop/
----

# Use containers for Ruby on Rails development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a Ruby on Rails application](https://docs.docker.com/guides/ruby/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment for your containerized application. This includes:

* Adding a local database and persisting data
* Configuring Compose to automatically update your running Compose services as you edit and save your code

## [Add a local database and persist data](#add-a-local-database-and-persist-data)

You can use containers to set up local services, like a database. In this section, you'll update the `compose.yaml` file to define a database service and a volume to persist data.

In the cloned repository's directory, open the `compose.yaml` file in an IDE or text editor. You need to add the database password file as an environment variable to the server service and specify the secret file to use.

The following is the updated `compose.yaml` file.

```yaml
services:
  web:
    build: .
    command: bundle exec rails s -b '0.0.0.0'
    ports:
      - "3000:3000"
    depends_on:
      - db
    environment:
      - RAILS_ENV=test
    env_file: "webapp.env"
  db:
    image: postgres:18
    secrets:
      - db-password
    environment:
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    volumes:
      - postgres_data:/var/lib/postgresql

volumes:
  postgres_data:
secrets:
  db-password:
    file: db/password.txt
```

> Note
>
> To learn more about the instructions in the Compose file, see [Compose file reference](/reference/compose-file/).

Before you run the application using Compose, notice that this Compose file specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository.

In the cloned repository's directory, create a new directory named `db` and inside that directory create a file named `password.txt` that contains the password for the database. Using your favorite IDE or text editor, add the following contents to the `password.txt` file.

```text
mysecretpassword
```

Save and close the `password.txt` file. In addition, in the file `webapp.env` you can change the password to connect to the database.

You should now have the following contents in your `docker-ruby-on-rails` directory.

```text
.
├── Dockerfile
├── Gemfile
├── Gemfile.lock
├── README.md
├── Rakefile
├── app/
├── bin/
├── compose.yaml
├── config/
├── config.ru
├── db/
│   ├── development.sqlite3
│   ├── migrate
│   ├── password.txt
│   ├── schema.rb
│   └── seeds.rb
├── lib/
├── log/
├── public/
├── storage/
├── test/
├── tmp/
└── vendor
```

Now, run the following `docker compose up` command to start your application.

```console
$ docker compose up --build
```

In Ruby on Rails, `db:migrate` is a Rake task that is used to run migrations on the database. Migrations are a way to alter the structure of your database schema over time in a consistent and easy way.

```console
$ docker exec -it docker-ruby-on-rails-web-1 rake db:migrate RAILS_ENV=test
```

You will see a similar message like this:

`console == 20240710193146 CreateWhales: migrating ===================================== -- create_table(:whales) -> 0.0126s == 20240710193146 CreateWhales: migrated (0.0127s) ============================`

Refresh <http://localhost:3000> in your browser and add the whales.

Press `ctrl+c` in the terminal to stop your application and run `docker compose up` again, the whales are being persisted.

## [Automatically update services](#automatically-update-services)

Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

Open your `compose.yaml` file in an IDE or text editor and then add the Compose Watch instructions. The following is the updated `compose.yaml` file.

```yaml
services:
  web:
    build: .
    command: bundle exec rails s -b '0.0.0.0'
    ports:
      - "3000:3000"
    depends_on:
      - db
    environment:
      - RAILS_ENV=test
    env_file: "webapp.env"

    develop:
      watch:
        - action: rebuild
          path: .
  db:
    image: postgres:18
    secrets:
      - db-password
    environment:
      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
    volumes:
      - postgres_data:/var/lib/postgresql

volumes:
  postgres_data:
secrets:
  db-password:
    file: db/password.txt
```

Run the following command to run your application with Compose Watch.

```console
$ docker compose watch
```

Any changes to the application's source files on your local machine will now be immediately reflected in the running container.

Open `docker-ruby-on-rails/app/views/whales/index.html.erb` in an IDE or text editor and update the `Whales` string by adding an exclamation mark.

```diff
-    <h1>Whales</h1>
+    <h1>Whales!</h1>
```

Save the changes to `index.html.erb` and then wait a few seconds for the application to rebuild. Go to the application again and verify that the updated text appears.

In the next section, you'll learn how you can locally test and debug your workloads on Kubernetes before deploying.

[Test your Ruby on Rails deployment »](https://docs.docker.com/guides/ruby/deploy/)

----
url: https://docs.docker.com/guides/testcontainers-java-keycloak-spring-boot/
----

# Securing Spring Boot microservice using Keycloak and Testcontainers

Table of contents

***

Learn how to create an OAuth 2.0 Resource Server using Spring Boot, secure API endpoints with Keycloak, and test the application using the Testcontainers Keycloak module.

**Time to complete** 30 minutes

In this guide, you'll learn how to:

* Create an OAuth 2.0 Resource Server using Spring Boot
* Secure API endpoints using Keycloak
* Test the APIs using the Testcontainers Keycloak module
* Run the application locally using the Testcontainers Keycloak module

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-keycloak-spring-boot/create-project/)

   Set up a Spring Boot OAuth 2.0 Resource Server with Keycloak, PostgreSQL, and Testcontainers.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-keycloak-spring-boot/write-tests/)

   Test the secured Spring Boot API endpoints using Testcontainers Keycloak and PostgreSQL modules.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-keycloak-spring-boot/run-tests/)

   Run your Testcontainers-based Spring Boot Keycloak integration tests and explore next steps.

----
url: https://docs.docker.com/guides/postgresql/advanced-configuration-and-initialization/
----

# Advanced Configuration and Initialization

***

Table of contents

***

With persistent storage configured in the previous section, you're ready to customize PostgreSQL for real-world use. This guide covers advanced configuration techniques for running PostgreSQL in Docker containers, including automated database initialization, performance tuning, and timezone configuration.

## [Overview](#overview)

While PostgreSQL containers can be started quickly with default settings, production environments require customized configurations. This guide explains how to:

* Automate database, schema, and user creation during container startup
* Tune PostgreSQL performance parameters for containerized workloads
* Configure timezone and locale settings

## [Initialization scripts](#initialization-scripts)

The official PostgreSQL Docker image supports running initialization scripts automatically when the container starts for the first time. Any files placed in the `/docker-entrypoint-initdb.d/` directory are executed in alphabetical order.

### [How initialization works](#how-initialization-works)

When the container starts, it checks whether the PostgreSQL data directory is empty. If the directory already contains data, PostgreSQL starts immediately without running any initialization. If the directory is empty, the container runs `initdb` to create a new database cluster, then executes all scripts in `/docker-entrypoint-initdb.d/` in alphabetical order before starting PostgreSQL.

### [Supported file formats](#supported-file-formats)

| Format    | Description                      |
| --------- | -------------------------------- |
| `.sql`    | SQL commands executed directly   |
| `.sql.gz` | Gzip-compressed SQL files        |
| `.sh`     | Shell scripts executed with bash |

> Important
>
> Initialization scripts only run when the PostgreSQL data directory (`/var/lib/postgresql/data`) is empty. If you mount a volume containing existing data, initialization is skipped. This behavior prevents overwriting existing databases.

## [Mounting initialization scripts](#mounting-initialization-scripts)

Use Docker Compose to mount initialization scripts into the container. First, create a project directory:

```console
$ mkdir -p postgres-project/init-db
$ cd postgres-project
```

Create a `compose.yaml` file:

```yaml
services:
  db:
    image: postgres:18
    volumes:
      - ./init-db:/docker-entrypoint-initdb.d
      - postgres_data:/var/lib/postgresql
    environment:
      POSTGRES_PASSWORD: mysecretpassword

volumes:
  postgres_data:
```

All scripts in the `./init-db` directory execute when the container starts for the first time. This is great for bootstrapping databases.

## [Initialization script example](#initialization-script-example)

Create a file named `init.sql` in your `init-db` directory:

```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    name VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

This script runs automatically when the container starts for the first time, creating your initial database schema.

> Note
>
> Ensure initialization scripts have proper read permissions. If you encounter "Permission denied" errors, run `chmod 644 init-db/*.sql` to make the files readable by the container.

## [Performance tuning](#performance-tuning)

Default PostgreSQL settings are conservative to work on systems with limited resources. For production workloads, you should tune these parameters based on your container's allocated resources.

### [Method 1: Custom configuration file](#method-1-custom-configuration-file)

For complete control, mount a custom `postgresql.conf` file. First, extract the default configuration:

```console
$ docker run -i --rm postgres:18 cat /usr/share/postgresql/postgresql.conf.sample > my-postgres.conf
```

Edit `my-postgres.conf` with your desired settings, then mount it in your Compose file:

```yaml
services:
  db:
    image: postgres:18
    volumes:
      - ./my-postgres.conf:/etc/postgresql/postgresql.conf
      - ./init-db:/docker-entrypoint-initdb.d
      - postgres_data:/var/lib/postgresql
    command: postgres -c config_file=/etc/postgresql/postgresql.conf
    environment:
      POSTGRES_PASSWORD: mysecretpassword

volumes:
  postgres_data:
```

## [Key configuration parameters](#key-configuration-parameters)

The following tables list important `postgresql.conf` parameters for containerized PostgreSQL deployments.

### [Connection settings](#connection-settings)

| Parameter          | Description                    | Default     |
| ------------------ | ------------------------------ | ----------- |
| `listen_addresses` | IP addresses to listen on      | `localhost` |
| `port`             | TCP port number                | `5432`      |
| `max_connections`  | Maximum concurrent connections | `100`       |

### [Memory settings](#memory-settings)

| Parameter              | Description                     | Recommended starting value |
| ---------------------- | ------------------------------- | -------------------------- |
| `shared_buffers`       | Shared memory for caching       | 25% of container memory    |
| `work_mem`             | Memory per query operation      | 4MB - 64MB                 |
| `maintenance_work_mem` | Memory for VACUUM, CREATE INDEX | 64MB - 256MB               |
| `effective_cache_size` | Planner's cache size estimate   | 50-75% of container memory |

#### [Docker memory limits](#docker-memory-limits)

When tuning memory parameters, set explicit memory limits on your container using `deploy.resources.limits.memory` in Compose or `--memory` with `docker run`. Without limits, PostgreSQL sees the host's total RAM and may allocate more than intended. For example, if your container should use 4GB maximum, set `shared_buffers` to approximately 1GB (25%).

### [I/O settings](#io-settings)

| Parameter                  | Description                    | Recommended starting value   |
| -------------------------- | ------------------------------ | ---------------------------- |
| `effective_io_concurrency` | Concurrent disk I/O operations | `200` for SSDs, `2` for HDDs |

### [Timeout settings](#timeout-settings)

| Parameter             | Description                       | Default        |
| --------------------- | --------------------------------- | -------------- |
| `statement_timeout`   | Max time for any statement        | `0` (disabled) |
| `lock_timeout`        | Max time to wait for a lock       | `0` (disabled) |
| `deadlock_timeout`    | Time before checking for deadlock | `1s`           |
| `transaction_timeout` | Max time for a transaction        | `0` (disabled) |

> Note
>
> Setting `shared_buffers` too high in a container can exceed kernel shared memory limits. Use no more than 25-30% of the container's memory limit.

## [Timezone and locale configuration](#timezone-and-locale-configuration)

Proper localization ensures timestamps and sorting behave correctly for your application's users.

```yaml
services:
  db:
    image: postgres:18
    volumes:
      - postgres_data:/var/lib/postgresql
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro
    environment:
      POSTGRES_PASSWORD: mysecretpassword
      TZ: America/New_York

volumes:
  postgres_data:
```

Alternatively, set the timezone using a PostgreSQL command-line parameter:

```yaml
services:
  db:
    image: postgres:18
    command: ["postgres", "-c", "timezone=America/New_York"]
    environment:
      POSTGRES_PASSWORD: mysecretpassword
```

### [Setting the locale](#setting-the-locale)

Specify locale settings during database initialization using the `POSTGRES_INITDB_ARGS` environment variable:

```yaml
services:
  db:
    image: postgres:18
    volumes:
      - postgres_data:/var/lib/postgresql
    environment:
      POSTGRES_PASSWORD: mysecretpassword
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8"

volumes:
  postgres_data:
```

This affects collation (sorting) and character processing behavior. Changing this variable after database creation has no effect—it only applies during the first run when the data directory is initialized.

## [Connecting to the database](#connecting-to-the-database)

You can interact with PostgreSQL running in a container even without `psql` installed on your host machine.

### [Interactive shell](#interactive-shell)

Open a `psql` session inside the container:

```console
$ docker exec -it postgres-container psql -U postgres
```

Connect to a specific database:

```console
$ docker exec -it postgres-container psql -U postgres -d mydb
```

[Networking and connectivity »](https://docs.docker.com/guides/postgresql/networking-and-connectivity/)

----
url: https://docs.docker.com/reference/compose-file/configs/
----

# Configs top-level element

***

Table of contents

***

Configs let services adapt their behaviour without the need to rebuild a Docker image. As with volumes, configs are mounted as files into a container's filesystem. The location of the mount point within the container defaults to `/<config-name>` in Linux containers and `C:\<config-name>` in Windows containers.

Services can only access configs when explicitly granted by a [`configs`](https://docs.docker.com/reference/compose-file/services/#configs) attribute within the `services` top-level element.

By default, the config:

* Is owned by the user running the container command but can be overridden by service configuration.
* Has world-readable permissions (mode 0444), unless the service is configured to override this.

The top-level `configs` declaration defines or references configuration data that is granted to services in your Compose application. The source of the config is either `file`, `environment`, `content`, or `external`.

* `file`: The config is created with the contents of the file at the specified path.
* `environment`: The config content is created with the value of an environment variable. Introduced in Docker Compose version [2.23.1](https://github.com/docker/compose/releases/tag/v2.23.1).
* `content`: The content is created with the inlined value. Introduced in Docker Compose version [2.23.1](https://github.com/docker/compose/releases/tag/v2.23.1).
* `external`: If set to true, `external` specifies that this config has already been created. Compose does not attempt to create it, and if it does not exist, an error occurs.
* `name`: The name of the config object in the container engine to look up. This field can be used to reference configs that contain special characters. The name is used as is and will **not** be scoped with the project name.

## [Example 1](#example-1)

`<project_name>_http_config` is created when the application is deployed, by registering the content of the `httpd.conf` as the configuration data.

```yml
configs:
  http_config:
    file: ./httpd.conf
```

Alternatively, `http_config` can be declared as external. Compose looks up `http_config` to expose the configuration data to relevant services.

```yml
configs:
  http_config:
    external: true
```

## [Example 2](#example-2)

External configs lookup can also use a distinct key by specifying a `name`.

The following example modifies the previous one to look up a config using the parameter `HTTP_CONFIG_KEY`. The actual lookup key is set at deployment time by the [interpolation](https://docs.docker.com/reference/compose-file/interpolation/) of variables, but exposed to containers as hard-coded ID `http_config`.

```yml
configs:
  http_config:
    external: true
    name: "${HTTP_CONFIG_KEY}"
```

## [Example 3](#example-3)

`<project_name>_app_config` is created when the application is deployed, by registering the inlined content as the configuration data. This means Compose infers variables when creating the config, which allows you to adjust content according to service configuration:

```yml
configs:
  app_config:
    content: |
      debug=${DEBUG}
      spring.application.admin.enabled=${DEBUG}
      spring.application.name=${COMPOSE_PROJECT_NAME}
```

## [Example 4](#example-4)

`<project_name>_simple_config` is created when the application is deployed, using the value of an environment variable as the configuration data. This is useful for simple configuration values that don’t require interpolation:

```yml
configs:
  simple_config:
    environment: "SIMPLE_CONFIG_VALUE"
```

If `external` is set to `true`, all other attributes apart from `name` are irrelevant. If Compose detects any other attribute, it rejects the Compose file as invalid.

----
url: https://docs.docker.com/reference/cli/docker/container/wait/
----

# docker container wait

***

| Description                                                               | Block until one or more containers stop, then print their exit codes |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Usage                                                                     | `docker container wait CONTAINER [CONTAINER...]`                     |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker wait`                                                        |

## [Description](#description)

Block until one or more containers stop, then print their exit codes

## [Examples](#examples)

Start a container in the background.

```console
$ docker run -dit --name=my_container ubuntu bash
```

Run `docker wait`, which should block until the container exits.

```console
$ docker wait my_container
```

In another terminal, stop the first container. The `docker wait` command above returns the exit code.

```console
$ docker stop my_container
```

This is the same `docker wait` command from above, but it now exits, returning `0`.

```console
$ docker wait my_container

0
```

----
url: https://docs.docker.com/dhi/explore/responsibility/
----

# Understanding roles and responsibilities for Docker Hardened Images

***

Table of contents

***

Docker Hardened Images (DHIs) are curated and maintained by Docker, and built using upstream open source components. To deliver security, reliability, and compliance, responsibilities are shared among three groups:

* Upstream maintainers: the developers and communities responsible for the open source software included in each image.
* Docker: the provider of hardened, signed, and maintained container images.
* You (the customer): the consumer who runs and, optionally, customizes DHIs in your environment.

This topic outlines who handles what, so you can use DHIs effectively and securely.

## [Releases](#releases)

* Upstream: Publishes and maintains official releases of the software components included in DHIs. This includes versioning, changelogs, and deprecation notices.
* Docker: Builds, hardens, and signs Docker Hardened Images based on upstream versions. Docker maintains these images in line with upstream release timelines and internal policies.
* You: Ensure you're staying on supported versions of DHIs and upstream projects. Using outdated or unsupported components can introduce security risk.

## [Patching](#patching)

* Upstream: Maintains and updates the source code for each component, including fixing vulnerabilities in libraries and dependencies.
* Docker: Rebuilds and re-releases images with upstream patches applied. Docker monitors for vulnerabilities and publishes updates to affected images. DHI Select and DHI Enterprise include [SLA commitments](https://docs.docker.com/go/dhi-sla/). DHI Community offers a secure baseline but no guaranteed remediation timelines.
* You: Apply DHI updates in your environments and patch any software or dependencies you install on top of the base image.

## [Testing](#testing)

* Upstream: Defines the behavior and functionality of the original software, and is responsible for validating core features.
* Docker: Validates that DHIs start, run, and behave consistently with upstream expectations. Docker also runs security scans and includes a [testing attestation](https://docs.docker.com/dhi/core-concepts/attestations/) with each image.
* You: Test your application on top of DHIs and validate that any changes or customizations function as expected in your environment.

## [Security and compliance](#security-and-compliance)

* Docker: Publishes signed SBOMs, VEX documents, provenance data, and CVE scan results with each image to support compliance and supply chain security.

  * For DHI Community users: All security metadata and transparency features are included at no cost.
  * For DHI Select and Enterprise users: Additional compliance variants (like FIPS and STIG) and customization capabilities are available, with automatic rebuilds when base images are patched.

* You: Integrate DHIs into your security and compliance workflows, including vulnerability management and auditing.

## [Support](#support)

* Docker:

  * For DHI Community users: Community support and public documentation are available.
  * For DHI Select and DHI Enterprise users: Access to Docker's enterprise support team for mission-critical applications.

* You: Monitor Docker's release notes, security advisories, and documentation for updates and best practices.

## [Summary](#summary)

Docker Hardened Images give you a secure foundation, complete with signed metadata and upstream transparency. Your role is to make informed use of these images, apply updates promptly, and validate that your configurations and applications meet your internal requirements.

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/list/
----

# docker mcp catalog list

***

| Description                                                               | List catalogs             |
| ------------------------------------------------------------------------- | ------------------------- |
| Usage                                                                     | `docker mcp catalog list` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker mcp catalog ls`   |

## [Description](#description)

List catalogs

## [Options](#options)

| Option     | Default | Description                   |
| ---------- | ------- | ----------------------------- |
| `--format` | `human` | Supported: json, yaml, human. |

----
url: https://docs.docker.com/reference/cli/docker/plugin/push/
----

# docker plugin push

***

| Description | Push a plugin to a registry                 |
| ----------- | ------------------------------------------- |
| Usage       | `docker plugin push [OPTIONS] PLUGIN[:TAG]` |

## [Description](#description)

After you have created a plugin using `docker plugin create` and the plugin is ready for distribution, use `docker plugin push` to share your images to Docker Hub or a self-hosted registry.

Registry credentials are managed by [docker login](/reference/cli/docker/login/).

## [Examples](#examples)

The following example shows how to push a sample `user/plugin`.

```console
$ docker plugin ls

ID             NAME                    DESCRIPTION                  ENABLED
69553ca1d456   user/plugin:latest      A sample plugin for Docker   false

$ docker plugin push user/plugin
```

----
url: https://docs.docker.com/engine/install/rhel/
----

# Install Docker Engine on RHEL

***

Table of contents

***

To get started with Docker Engine on RHEL, make sure you [meet the prerequisites](#prerequisites), and then follow the [installation steps](#installation-methods).

## [Prerequisites](#prerequisites)

### [OS requirements](#os-requirements)

To install Docker Engine, you need a maintained version of one of the following RHEL versions:

* RHEL 8
* RHEL 9
* RHEL 10

### [Uninstall old versions](#uninstall-old-versions)

Before you can install Docker Engine, you need to uninstall any conflicting packages.

Your Linux distribution may provide unofficial Docker packages, which may conflict with the official packages provided by Docker. You must uninstall these packages before you install the official version of Docker Engine.

```console
$ sudo dnf remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-engine \
                  podman \
                  runc
```

```console
$ sudo dnf -y install dnf-plugins-core
$ sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
```

#### [Install Docker Engine](#install-docker-engine)

1. Install the Docker packages.

   To install the latest version, run:

   ```console
   $ sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   If prompted to accept the GPG key, verify that the fingerprint matches `060A 61C5 1B55 8A7F 742B 77AA C52F EB6B 621E 9F35`, and if so, accept it.

   This command installs Docker, but it doesn't start Docker. It also creates a `docker` group, however, it doesn't add any users to the group by default.

   To install a specific version, start by listing the available versions in the repository:

   ```console
   $ dnf list docker-ce --showduplicates | sort -r

   docker-ce.x86_64    3:29.5.2-1.el9    docker-ce-stable
   docker-ce.x86_64    3:29.5.1-1.el9    docker-ce-stable
   <...>
   ```

   The list returned depends on which repositories are enabled, and is specific to your version of RHEL (indicated by the `.el9` suffix in this example).

   Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), separated by a hyphen (`-`). For example, `docker-ce-3:29.5.2-1.el9`.

   Replace `<VERSION_STRING>` with the desired version and then run the following command to install:

   ```console
   $ sudo dnf install docker-ce-VERSION_STRING docker-ce-cli-VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   This command installs Docker, but it doesn't start Docker. It also creates a `docker` group, however, it doesn't add any users to the group by default.

2. Start Docker Engine.

   ```console
   $ sudo systemctl enable --now docker
   ```

   This configures the Docker systemd service to start automatically when you boot your system. If you don't want Docker to start automatically, use `sudo systemctl start docker` instead.

3. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

#### [Upgrade Docker Engine](#upgrade-docker-engine)

To upgrade Docker Engine, follow the [installation instructions](#install-using-the-repository), choosing the new version you want to install.

### [Install from a package](#install-from-a-package)

If you can't use Docker's `rpm` repository to install Docker Engine, you can download the `.rpm` file for your release and install it manually. You need to download a new file each time you want to upgrade Docker Engine.

1. Go to <https://download.docker.com/linux/rhel/>.

2. Select your RHEL version in the list.

3. Select the applicable architecture (`x86_64`, `aarch64`, or `s390x`), and then go to `stable/Packages/`.

4. Download the following `rpm` files for the Docker Engine, CLI, containerd, and Docker Compose packages:

   * `containerd.io-<version>.<arch>.rpm`
   * `docker-ce-<version>.<arch>.rpm`
   * `docker-ce-cli-<version>.<arch>.rpm`
   * `docker-buildx-plugin-<version>.<arch>.rpm`
   * `docker-compose-plugin-<version>.<arch>.rpm`

5. Install Docker Engine, changing the following path to the path where you downloaded the packages.

   ```console
   $ sudo dnf install ./containerd.io-<version>.<arch>.rpm \
     ./docker-ce-<version>.<arch>.rpm \
     ./docker-ce-cli-<version>.<arch>.rpm \
     ./docker-buildx-plugin-<version>.<arch>.rpm \
     ./docker-compose-plugin-<version>.<arch>.rpm
   ```

   Docker is installed but not started. The `docker` group is created, but no users are added to the group.

6. Start Docker Engine.

   ```console
   $ sudo systemctl enable --now docker
   ```

   This configures the Docker systemd service to start automatically when you boot your system. If you don't want Docker to start automatically, use `sudo systemctl start docker` instead.

7. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

> Tip
>
> Preview script steps before running. You can run the script with the `--dry-run` option to learn what steps the script will run when invoked:
>
> ```console
> $ curl -fsSL https://get.docker.com -o get-docker.sh
> $ sudo sh ./get-docker.sh --dry-run
> ```

This example downloads the script from <https://get.docker.com/> and runs it to install the latest stable release of Docker on Linux:

```console
$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh get-docker.sh
Executing docker install script, commit: 7cae5f8b0decc17d6571f9f52eb840fbc13b2737
<...>
```

You have now successfully installed and started Docker Engine. The `docker` service starts automatically on Debian based distributions. On `RPM` based distributions, such as CentOS, Fedora or RHEL, you need to start it manually using the appropriate `systemctl` or `service` command. As the message indicates, non-root users can't run Docker commands by default.

> **Use Docker as a non-privileged user, or install in rootless mode?**
>
> The installation script requires `root` or `sudo` privileges to install and use Docker. If you want to grant non-root users access to Docker, refer to the [post-installation steps for Linux](/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). You can also install Docker without `root` privileges, or configured to run in rootless mode. For instructions on running Docker in rootless mode, refer to [run the Docker daemon as a non-root user (rootless mode)](/engine/security/rootless/).

#### [Install pre-releases](#install-pre-releases)

Docker also provides a convenience script at <https://test.docker.com/> to install pre-releases of Docker on Linux. This script is equal to the script at `get.docker.com`, but configures your package manager to use the test channel of the Docker package repository. The test channel includes both stable and pre-releases (beta versions, release-candidates) of Docker. Use this script to get early access to new releases, and to evaluate them in a testing environment before they're released as stable.

To install the latest version of Docker on Linux from the test channel, run:

```console
$ curl -fsSL https://test.docker.com -o test-docker.sh
$ sudo sh test-docker.sh
```

#### [Upgrade Docker after using the convenience script](#upgrade-docker-after-using-the-convenience-script)

If you installed Docker using the convenience script, you should upgrade Docker using your package manager directly. There's no advantage to re-running the convenience script. Re-running it can cause issues if it attempts to re-install repositories which already exist on the host machine.

## [Uninstall Docker Engine](#uninstall-docker-engine)

1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages:

   ```console
   $ sudo dnf remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
   ```

2. Images, containers, volumes, or custom configuration files on your host aren't automatically removed. To delete all images, containers, and volumes:

   ```console
   $ sudo rm -rf /var/lib/docker
   $ sudo rm -rf /var/lib/containerd
   ```

You have to delete any edited configuration files manually.

## [Next steps](#next-steps)

* Continue to [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/).

----
url: https://docs.docker.com/engine/daemon/alternative-runtimes/
----

# Alternative container runtimes

***

Table of contents

***

Docker Engine uses containerd for managing the container lifecycle, which includes creating, starting, and stopping containers. By default, containerd uses runc as its container runtime.

## [What runtimes can I use?](#what-runtimes-can-i-use)

You can use any runtime that implements the containerd [shim API](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md). Such runtimes ship with a containerd shim, and you can use them without any additional configuration. See [Use containerd shims](#use-containerd-shims).

Examples of runtimes that implement their own containerd shims include:

* [Wasmtime](https://wasmtime.dev/)
* [gVisor](https://github.com/google/gvisor)
* [Kata Containers](https://katacontainers.io/)

You can also use runtimes designed as drop-in replacements for runc. Such runtimes depend on the runc containerd shim for invoking the runtime binary. You must manually register such runtimes in the daemon configuration.

[youki](https://github.com/youki-dev/youki) is one example of a runtime that can function as a runc drop-in replacement. Refer to the [youki example](#youki) explaining the setup.

## [Use containerd shims](#use-containerd-shims)

containerd shims let you use alternative runtimes without having to change the configuration of the Docker daemon. To use a containerd shim, install the shim binary on `PATH` on the system where the Docker daemon is running.

To use a shim with `docker run`, specify the fully qualified name of the runtime as the value to the `--runtime` flag:

```console
$ docker run --runtime io.containerd.kata.v2 hello-world
```

### [Use a containerd shim without installing on PATH](#use-a-containerd-shim-without-installing-on-path)

You can use a shim without installing it on `PATH`, in which case you need to register the shim in the daemon configuration as follows:

```json
{
  "runtimes": {
    "foo": {
      "runtimeType": "/path/to/containerd-shim-foobar-v1"
    }
  }
}
```

To use the shim, specify the name that you assigned to it:

```console
$ docker run --runtime foo hello-world
```

### [Configure shims](#configure-shims)

If you need to pass additional configuration for a containerd shim, you can use the `runtimes` option in the daemon configuration file.

1. Edit the daemon configuration file by adding a `runtimes` entry for the shim you want to configure.

   * Specify the fully qualified name for the runtime in `runtimeType` key
   * Add your runtime configuration under the `options` key

   ```json
   {
     "runtimes": {
       "gvisor": {
         "runtimeType": "io.containerd.runsc.v1",
         "options": {
           "TypeUrl": "io.containerd.runsc.v1.options",
           "ConfigPath": "/etc/containerd/runsc.toml"
         }
       }
     }
   }
   ```

2. Reload the daemon's configuration.

   ```console
   # systemctl reload docker
   ```

3. Use the customized runtime using the `--runtime` flag for `docker run`.

   ```console
   $ docker run --runtime gvisor hello-world
   ```

For more information about the configuration options for containerd shims, see [Configure containerd shims](https://docs.docker.com/reference/cli/dockerd/#configure-containerd-shims).

## [Examples](#examples)

The following examples show you how to set up and use alternative container runtimes with Docker Engine.

* [youki](#youki)
* [Wasmtime](#wasmtime)

### [youki](#youki)

youki is a container runtime written in Rust. youki claims to be faster and use less memory than runc, making it a good choice for resource-constrained environments.

youki functions as a drop-in replacement for runc, meaning it relies on the runc shim to invoke the runtime binary. When you register runtimes acting as runc replacements, you configure the path to the runtime executable, and optionally a set of runtime arguments. For more information, see [Configure runc drop-in replacements](https://docs.docker.com/reference/cli/dockerd/#configure-runc-drop-in-replacements).

To add youki as a container runtime:

1. Install youki and its dependencies.

   For instructions, refer to the [official setup guide](https://youki-dev.github.io/youki/user/basic_setup.html).

2. Register youki as a runtime for Docker by editing the Docker daemon configuration file, located at `/etc/docker/daemon.json` by default.

   The `path` key should specify the path to wherever you installed youki.

   ```console
   # cat > /etc/docker/daemon.json <<EOF
   {
     "runtimes": {
       "youki": {
         "path": "/usr/local/bin/youki"
       }
     }
   }
   EOF
   ```

3. Reload the daemon's configuration.

   ```console
   # systemctl reload docker
   ```

Now you can run containers that use youki as a runtime.

```console
$ docker run --rm --runtime youki hello-world
```

### [Wasmtime](#wasmtime)

Availability: Experimental

Wasmtime is a [Bytecode Alliance](https://bytecodealliance.org/) project, and a Wasm runtime that lets you run Wasm containers. Running Wasm containers with Docker provides two layers of security. You get all the benefits from container isolation, plus the added sandboxing provided by the Wasm runtime environment.

To add Wasmtime as a container runtime, follow these steps:

1. Turn on the [containerd image store](https://docs.docker.com/engine/storage/containerd/) feature in the daemon configuration file.

   ```json
   {
     "features": {
       "containerd-snapshotter": true
     }
   }
   ```

2. Restart the Docker daemon.

   ```console
   # systemctl restart docker
   ```

3. Install the Wasmtime containerd shim on `PATH`.

   The following command Dockerfile builds the Wasmtime binary from source and exports it to `./containerd-shim-wasmtime-v1`.

   ```console
   $ docker build --output . - <<EOF
   FROM rust:latest as build
   RUN cargo install \
       --git https://github.com/containerd/runwasi.git \
       --bin containerd-shim-wasmtime-v1 \
       --root /out \
       containerd-shim-wasmtime
   FROM scratch
   COPY --from=build /out/bin /
   EOF
   ```

   Put the binary in a directory on `PATH`.

   ```console
   $ mv ./containerd-shim-wasmtime-v1 /usr/local/bin
   ```

Now you can run containers that use Wasmtime as a runtime.

```console
$ docker run --rm \
 --runtime io.containerd.wasmtime.v1 \
 --platform wasi/wasm32 \
 michaelirwin244/wasm-example
```

## [Related information](#related-information)

* To learn more about the configuration options for container runtimes, see [Configure container runtimes](https://docs.docker.com/reference/cli/dockerd/#configure-container-runtimes).
* You can configure which runtime that the daemon should use as its default. Refer to [Configure the default container runtime](https://docs.docker.com/reference/cli/dockerd/#configure-the-default-container-runtime).

----
url: https://docs.docker.com/reference/cli/docker/model/rm/
----

# docker model rm

***

| Description | Remove local models downloaded from Docker Hub |
| ----------- | ---------------------------------------------- |
| Usage       | `docker model rm [MODEL...]`                   |

## [Description](#description)

Remove local models downloaded from Docker Hub

## [Options](#options)

| Option        | Default | Description                 |
| ------------- | ------- | --------------------------- |
| `-f, --force` |         | Forcefully remove the model |

----
url: https://docs.docker.com/reference/api/registry/auth/
----

# Registry authentication

***

Table of contents

***

This document outlines the registry authentication scheme:

1. Attempt to begin a push/pull operation with the registry.
2. If the registry requires authorization it will return a `401 Unauthorized` HTTP response with information on how to authenticate.
3. The registry client makes a request to the authorization service for a Bearer token.
4. The authorization service returns an opaque Bearer token representing the client's authorized access.
5. The client retries the original request with the Bearer token embedded in the request's Authorization header.
6. The Registry authorizes the client by validating the Bearer token and the claim set embedded within it and begins the push/pull session as usual.

## [Requirements](#requirements)

* Registry clients which can understand and respond to token auth challenges returned by the resource server.
* An authorization server capable of managing access controls to their resources hosted by any given service (such as repositories in a Docker Registry).
* A Docker Registry capable of trusting the authorization server to sign tokens which clients can use for authorization and the ability to verify these tokens for single use or for use during a sufficiently short period of time.

## [Authorization server endpoint descriptions](#authorization-server-endpoint-descriptions)

The described server is meant to serve as a standalone access control manager for resources hosted by other services which want to authenticate and manage authorizations using a separate access control manager.

A service like this is used by the official Docker Registry to authenticate clients and verify their authorization to Docker image repositories.

As of Docker 1.6, the registry client within the Docker Engine has been updated to handle such an authorization workflow.

## [How to authenticate](#how-to-authenticate)

Registry V1 clients first contact the index to initiate a push or pull. Under the Registry V2 workflow, clients should contact the registry first. If the registry server requires authentication it will return a `401 Unauthorized` response with a `WWW-Authenticate` header detailing how to authenticate to this registry.

For example, say I (username `jlhawn`) am attempting to push an image to the repository `samalba/my-app`. For the registry to authorize this, I will need `push` access to the `samalba/my-app` repository. The registry will first return this response:

```text
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Docker-Distribution-Api-Version: registry/2.0
Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:samalba/my-app:pull,push"
Date: Thu, 10 Sep 2015 19:32:31 GMT
Content-Length: 235
Strict-Transport-Security: max-age=31536000

{"errors":[{"code":"UNAUTHORIZED","message":"access to the requested resource is not authorized","detail":[{"Type":"repository","Name":"samalba/my-app","Action":"pull"},{"Type":"repository","Name":"samalba/my-app","Action":"push"}]}]}
```

Note the HTTP Response Header indicating the auth challenge:

```text
Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:samalba/my-app:pull,push"
```

This format is documented in [Section 3 of RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750#section-3)

This challenge indicates that the registry requires a token issued by the specified token server and that the request the client is attempting will need to include sufficient access entries in its claim set. To respond to this challenge, the client will need to make a `GET` request to the URL `https://auth.docker.io/token` using the `service` and `scope` values from the `WWW-Authenticate` header.

## [Requesting a token](#requesting-a-token)

Defines getting a bearer and refresh token using the token endpoint.

### [Query parameters](#query-parameters)

#### [`service`](#service)

The name of the service which hosts the resource.

#### [`offline_token`](#offline_token)

Whether to return a refresh token along with the bearer token. A refresh token is capable of getting additional bearer tokens for the same subject with different scopes. The refresh token does not have an expiration and should be considered completely opaque to the client.

#### [`client_id`](#client_id)

String identifying the client. This `client_id` does not need to be registered with the authorization server but should be set to a meaningful value in order to allow auditing keys created by unregistered clients. Accepted syntax is defined in [RFC6749 Appendix A.1](https://tools.ietf.org/html/rfc6749#appendix-A.1).

#### [`scope`](#scope)

The resource in question, formatted as one of the space-delimited entries from the `scope` parameters from the `WWW-Authenticate` header shown previously. This query parameter should be specified multiple times if there is more than one `scope` entry from the `WWW-Authenticate` header. The previous example would be specified as: `scope=repository:samalba/my-app:push`. The scope field may be empty to request a refresh token without providing any resource permissions to the returned bearer token.

### [Token response fields](#token-response-fields)

#### [`token`](#token)

An opaque `Bearer` token that clients should supply to subsequent requests in the `Authorization` header.

#### [`access_token`](#access_token)

For compatibility with OAuth 2.0, the `token` under the name `access_token` is also accepted. At least one of these fields must be specified, but both may also appear (for compatibility with older clients). When both are specified, they should be equivalent; if they differ the client's choice is undefined.

#### [`expires_in`](#expires_in)

(Optional) The duration in seconds since the token was issued that it will remain valid. When omitted, this defaults to 60 seconds. For compatibility with older clients, a token should never be returned with less than 60 seconds to live.

#### [`issued_at`](#issued_at)

(Optional) The [RFC3339](https://www.ietf.org/rfc/rfc3339.txt)-serialized UTC standard time at which a given token was issued. If `issued_at` is omitted, the expiration is from when the token exchange completed.

#### [`refresh_token`](#refresh_token)

(Optional) Token which can be used to get additional access tokens for the same subject with different scopes. This token should be kept secure by the client and only sent to the authorization server which issues bearer tokens. This field will only be set when `offline_token=true` is provided in the request.

### [Example](#example)

For this example, the client makes an HTTP GET request to the following URL:

```text
https://auth.docker.io/token?service=registry.docker.io&scope=repository:samalba/my-app:pull,push
```

The token server should first attempt to authenticate the client using any authentication credentials provided with the request. From Docker 1.11 the Docker Engine supports both Basic Authentication and OAuth2 for getting tokens. Docker 1.10 and before, the registry client in the Docker Engine only supports Basic Authentication. If an attempt to authenticate to the token server fails, the token server should return a `401 Unauthorized` response indicating that the provided credentials are invalid.

Whether the token server requires authentication is up to the policy of that access control provider. Some requests may require authentication to determine access (such as pushing or pulling a private repository) while others may not (such as pulling from a public repository).

After authenticating the client (which may simply be an anonymous client if no attempt was made to authenticate), the token server must next query its access control list to determine whether the client has the requested scope. In this example request, if I have authenticated as user `jlhawn`, the token server will determine what access I have to the repository `samalba/my-app` hosted by the entity `registry.docker.io`.

Once the token server has determined what access the client has to the resources requested in the `scope` parameter, it will take the intersection of the set of requested actions on each resource and the set of actions that the client has in fact been granted. If the client only has a subset of the requested access **it must not be considered an error** as it is not the responsibility of the token server to indicate authorization errors as part of this workflow.

Continuing with the example request, the token server will find that the client's set of granted access to the repository is `[pull, push]` which when intersected with the requested access `[pull, push]` yields an equal set. If the granted access set was found only to be `[pull]` then the intersected set would only be `[pull]`. If the client has no access to the repository then the intersected set would be empty, `[]`.

It is this intersected set of access which is placed in the returned token.

The server then constructs an implementation-specific token with this intersected set of access, and returns it to the Docker client to use to authenticate to the audience service (within the indicated window of time):

```text
HTTP/1.1 200 OK
Content-Type: application/json

{"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IlBZWU86VEVXVTpWN0pIOjI2SlY6QVFUWjpMSkMzOlNYVko6WEdIQTozNEYyOjJMQVE6WlJNSzpaN1E2In0.eyJpc3MiOiJhdXRoLmRvY2tlci5jb20iLCJzdWIiOiJqbGhhd24iLCJhdWQiOiJyZWdpc3RyeS5kb2NrZXIuY29tIiwiZXhwIjoxNDE1Mzg3MzE1LCJuYmYiOjE0MTUzODcwMTUsImlhdCI6MTQxNTM4NzAxNSwianRpIjoidFlKQ08xYzZjbnl5N2tBbjBjN3JLUGdiVjFIMWJGd3MiLCJhY2Nlc3MiOlt7InR5cGUiOiJyZXBvc2l0b3J5IiwibmFtZSI6InNhbWFsYmEvbXktYXBwIiwiYWN0aW9ucyI6WyJwdXNoIl19XX0.QhflHPfbd6eVF4lM9bwYpFZIV0PfikbyXuLx959ykRTBpe3CYnzs6YBK8FToVb5R47920PVLrh8zuLzdCr9t3w", "expires_in": 3600,"issued_at": "2009-11-10T23:00:00Z"}
```

## [Using the Bearer token](#using-the-bearer-token)

Once the client has a token, it will try the registry request again with the token placed in the HTTP `Authorization` header like so:

```text
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IkJWM0Q6MkFWWjpVQjVaOktJQVA6SU5QTDo1RU42Ok40SjQ6Nk1XTzpEUktFOkJWUUs6M0ZKTDpQT1RMIn0.eyJpc3MiOiJhdXRoLmRvY2tlci5jb20iLCJzdWIiOiJCQ0NZOk9VNlo6UUVKNTpXTjJDOjJBVkM6WTdZRDpBM0xZOjQ1VVc6NE9HRDpLQUxMOkNOSjU6NUlVTCIsImF1ZCI6InJlZ2lzdHJ5LmRvY2tlci5jb20iLCJleHAiOjE0MTUzODczMTUsIm5iZiI6MTQxNTM4NzAxNSwiaWF0IjoxNDE1Mzg3MDE1LCJqdGkiOiJ0WUpDTzFjNmNueXk3a0FuMGM3cktQZ2JWMUgxYkZ3cyIsInNjb3BlIjoiamxoYXduOnJlcG9zaXRvcnk6c2FtYWxiYS9teS1hcHA6cHVzaCxwdWxsIGpsaGF3bjpuYW1lc3BhY2U6c2FtYWxiYTpwdWxsIn0.Y3zZSwaZPqy4y9oRBVRImZyv3m_S9XDHF1tWwN7mL52C_IiA73SJkWVNsvNqpJIn5h7A2F8biv_S2ppQ1lgkbw
```

This is also described in [Section 2.1 of RFC 6750: The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://tools.ietf.org/html/rfc6750#section-2.1)

----
url: https://docs.docker.com/get-started/workshop/02_our_app/
----

# Containerize an application

***

Table of contents

***

For the rest of this guide, you'll be working with a simple todo list manager that runs on Node.js. If you're not familiar with Node.js, don't worry. This guide doesn't require any prior experience with JavaScript.

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have installed a [Git client](https://git-scm.com/downloads).
* You have an IDE or a text editor to edit files. Docker recommends using [Visual Studio Code](https://code.visualstudio.com/).

## [Get the app](#get-the-app)

Before you can run the application, you need to get the application source code onto your machine.

1. Clone the [getting-started-app repository](https://github.com/docker/getting-started-app/tree/main) using the following command:

   ```console
   $ git clone https://github.com/docker/getting-started-app.git
   ```

2. View the contents of the cloned repository. You should see the following files and sub-directories.

   ```text
   ├── getting-started-app/
   │ ├── .dockerignore
   │ ├── package.json
   │ ├── package-lock.json   
   │ ├── README.md
   │ ├── spec/
   │ ├── src/
   ```

## [Build the app's image](#build-the-apps-image)

To build the image, you'll need to use a Dockerfile. A Dockerfile is simply a text-based file with no file extension that contains a script of instructions. Docker uses this script to build a container image.

1. In the `getting-started-app` directory, the same location as the `package.json` file, create a file named `Dockerfile` with the following contents:

   ```dockerfile
   # syntax=docker/dockerfile:1

   FROM node:24-alpine
   WORKDIR /app
   COPY . .
   RUN npm install --omit=dev
   CMD ["node", "src/index.js"]
   EXPOSE 3000
   ```

   This Dockerfile does the following:

   * Uses `node:24-alpine` as the base image, a lightweight Linux image with Node.js pre-installed
   * Sets `/app` as the working directory
   * Copies source code into the image
   * Installs the necessary dependencies
   * Specifies the command to start the application
   * Documents that the app listens on port 3000

2. Build the image using the following commands:

   In the terminal, make sure you're in the `getting-started-app` directory. Replace `/path/to/getting-started-app` with the path to your `getting-started-app` directory.

   ```console
   $ cd /path/to/getting-started-app
   ```

   Build the image.

   ```console
   $ docker build -t getting-started .
   ```

   The `docker build` command uses the Dockerfile to build a new image. You might have noticed that Docker downloaded a lot of "layers". This is because you instructed the builder that you wanted to start from the `node:24-alpine` image. But, since you didn't have that on your machine, Docker needed to download the image.

   After Docker downloaded the image, the instructions from the Dockerfile copied in your application and used `npm` to install your application's dependencies.

   Finally, the `-t` flag tags your image. Think of this as a human-readable name for the final image. Since you named the image `getting-started`, you can refer to that image when you run a container.

   The `.` at the end of the `docker build` command tells Docker that it should look for the `Dockerfile` in the current directory.

## [Start an app container](#start-an-app-container)

Now that you have an image, you can run the application in a container using the `docker run` command.

1. Run your container using the `docker run` command and specify the name of the image you just created:

   ```console
   $ docker run -d -p 127.0.0.1:3000:3000 getting-started
   ```

   The `-d` flag (short for `--detach`) runs the container in the background. This means that Docker starts your container and returns you to the terminal prompt. Also, it does not display logs in the terminal.

   The `-p` flag (short for `--publish`) creates a port mapping between the host and the container. The `-p` flag takes a string value in the format of `HOST:CONTAINER`, where `HOST` is the address on the host, and `CONTAINER` is the port on the container. The command publishes the container's port 3000 to `127.0.0.1:3000` (`localhost:3000`) on the host. Without the port mapping, you wouldn't be able to access the application from the host.

2. After a few seconds, open your web browser to <http://localhost:3000>. You should see your app.

3. Add an item or two and see that it works as you expect. You can mark items as complete and remove them. Your frontend is successfully storing items in the backend.

At this point, you have a running todo list manager with a few items.

If you take a quick look at your containers, you should see at least one container running that's using the `getting-started` image and on port `3000`. To see your containers, you can use the CLI or Docker Desktop's graphical interface.

Run the `docker ps` command in a terminal to list your containers.

```console
$ docker ps
```

Output similar to the following should appear.

```console
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                      NAMES
df784548666d        getting-started     "docker-entrypoint.s…"   2 minutes ago       Up 2 minutes        127.0.0.1:3000->3000/tcp   priceless_mcclintock
```

In Docker Desktop, select the **Containers** tab to see a list of your containers.

## [Summary](#summary)

In this section, you learned the basics about creating a Dockerfile to build an image. Once you built an image, you started a container and saw the running app.

Related information:

* [Dockerfile reference](/reference/dockerfile/)
* [docker CLI reference](/reference/cli/docker/)

## [Next steps](#next-steps)

Next, you're going to make a modification to your app and learn how to update your running application with a new image. Along the way, you'll learn a few other useful commands.

[Update the application](https://docs.docker.com/get-started/workshop/03_updating_app/)

----
url: https://docs.docker.com/support/
----

# Get support for Docker products

***

Table of contents

***

Docker offers multiple support channels depending on your subscription level and needs.

## [Paid subscription support](#paid-subscription-support)

All Docker Pro, Team, and Business subscribers receive email support for Docker products.

### [Support response times](#support-response-times)

* Docker Pro: 3 business day response
* Docker Team: 2 business day response, 24×5 availability
* Docker Business: 1 business day response, 24×5 availability

> Tip
>
> Premium Support with faster response times and 24×7 availability is available as an add-on for [Docker Business subscribers](https://www.docker.com/pricing?ref=Docs\&refAction=DocsSupport).

### [Support severity levels](#support-severity-levels)

| Level    | Description                                                                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Critical | Widespread or company-wide service outage affecting many customers or all users within a single organization. Business operations are halted with no workaround available. |
| High     | Team or department-level impact preventing significant users from accessing core functionality. Severe business impact with no workaround exists.                          |
| Medium   | Individual user or small group impact causing partial loss of functionality. Business operations continue, often with workarounds available but reduced productivity.      |

### [Request support](#request-support)

> Tip
>
> Before reaching out for support, review the troubleshooting documentation for your product.

If you have a paid Docker subscription, [contact the Support team](https://hub.docker.com/support/contact/).

## [Community support](#community-support)

All Docker users can seek support through community resources, where Docker or the community respond on a best effort basis:

* [Docker Community Forums](https://forums.docker.com/)
* [Docker Community Slack](http://dockr.ly/comm-slack)

## [Docker Desktop support](#docker-desktop-support)

Docker Desktop support is available with a paid subscription.

### [Scope of support](#scope-of-support)

Docker Desktop support includes:

* Account management and billing
* Configuration and installation issues
* Desktop updates
* Sign-in issues
* Push or pull issues, including rate limiting
* Application crashes or unexpected behavior
* Automated builds
* Basic product 'how to' questions

**Windows-specific:**

* Turning on virtualization in BIOS
* Turning on Windows features
* Running inside [certain VM or VDI environments](https://docs.docker.com/desktop/setup/vm-vdi/) (Docker Business only)

Docker Desktop support excludes:

* Unsupported operating systems, including beta/preview versions
* Running containers of a different architecture using emulation
* Docker Engine, Docker CLI, or other bundled Linux components
* Kubernetes
* Features labeled as experimental
* System/Server administration activities
* Desktop as a production runtime
* Scale deployment/multi-machine installation
* Routine product maintenance (data backup, disk space, log rotation)
* Third-party applications not provided by Docker
* Altered or modified Docker software
* Hardware malfunction, abuse, or improper use
* Versions older than the latest release (except Docker Business)
* Training, customization, and integration
* Running multiple instances on a single machine

> Note
>
> Support for [running Docker Desktop in a VM or VDI environment](https://docs.docker.com/desktop/setup/vm-vdi/) is only available to Docker Business customers.

### [Supported versions](#supported-versions)

* Docker Business: Versions up to six months older than the latest version (fixes applied to latest version only)
* Docker Pro and Team: Latest version only

### [Number of machines](#number-of-machines)

* Docker Pro: One machine
* Docker Team: Number of machines equal to subscription seats
* Docker Business: Unlimited machines

### [Supported operating systems](#supported-operating-systems)

* [Mac system requirements](https://docs.docker.com/desktop/setup/install/mac-install/#system-requirements)
* [Windows system requirements](https://docs.docker.com/desktop/setup/install/windows-install/#system-requirements)
* [Linux system requirements](https://docs.docker.com/desktop/setup/install/linux/#system-requirements)

### [Community resources](#community-resources)

* [Docker Desktop issue tracker](https://github.com/docker/desktop-feedback)

### [Diagnostic data and privacy](#diagnostic-data-and-privacy)

When uploading diagnostics, the bundle may contain personal data such as usernames and IP addresses. Diagnostics bundles are only accessible to Docker, Inc. employees directly involved in diagnosing issues.

By default, Docker, Inc. deletes uploaded diagnostics bundles after 30 days. You may request removal of a diagnostics bundle by specifying the diagnostics ID or your GitHub ID. Docker, Inc. only uses the data to investigate specific user issues but may derive high-level (non-personal) metrics.

For more information, see [Docker Data Processing Agreement](https://www.docker.com/legal/data-processing-agreement).

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/air-gapped-containers/
----

# Air-gapped containers

***

Table of contents

***

Subscription: Business

For: Administrators

Air-gapped containers let you restrict container network access by controlling where containers can send and receive data. This feature applies custom proxy rules to container network traffic, helping secure environments where containers shouldn't have unrestricted internet access.

Docker Desktop can configure container network traffic to accept connections, reject connections, or tunnel through HTTP or SOCKS proxies. You control which TCP ports the policy applies to and whether to use a single proxy or per-destination policies via Proxy Auto-Configuration (PAC) files.

## [Who should use air-gapped containers?](#who-should-use-air-gapped-containers)

Use air-gapped containers if:

* Your organization requires containers to communicate only with approved internal services
* You need to meet compliance standards that mandate network isolation (such as SOC 2, ISO 27001, or PCI DSS)
* You want to prevent containers from leaking data or reaching unapproved external endpoints during builds or at runtime

## [How air-gapped containers work](#how-air-gapped-containers-work)

Air-gapped containers operate by intercepting container network traffic and applying proxy rules:

1. Traffic interception: Docker Desktop intercepts all outgoing network connections from containers
2. Port filtering: Only traffic on specified ports (`transparentPorts`) is subject to proxy rules
3. Rule evaluation: PAC file rules or static proxy settings determine how to handle each connection
4. Connection handling: Traffic is allowed directly, routed through a proxy, or blocked based on the rules

Some important considerations include:

* The existing `proxy` setting continues to apply to Docker Desktop application traffic on the host
* If PAC file download fails, containers block requests to target URLs
* Hostname is available for ports 80 and 443, but only IP addresses for other ports

## [Prerequisites](#prerequisites)

Before configuring air-gapped containers, you must have:

* [Enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) enabled to ensure users authenticate with your organization
* A Docker Business subscription
* Configured [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) with the `admin-settings.json` file to manage organization policies

## [Configure air-gapped containers](#configure-air-gapped-containers)

Add the container proxy to your [`admin-settings.json` file](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-json-file/). For example:

```json
{
  "configurationFileVersion": 2,
  "containersProxy": {
    "locked": true,
    "mode": "manual",
    "http": "",
    "https": "",
    "exclude": [],
    "pac": "http://192.168.1.16:62039/proxy.pac",
    "transparentPorts": "*"
  }
}
```

### [Configuration parameters](#configuration-parameters)

The `containersProxy` setting controls network policies applied to container traffic:

| Parameter          | Description                                  | Value                                          |
| ------------------ | -------------------------------------------- | ---------------------------------------------- |
| `locked`           | Prevents developers from overriding settings | `true` (locked), `false` (default)             |
| `mode`             | Proxy configuration method                   | `system` (use system proxy), `manual` (custom) |
| `http`             | HTTP proxy server                            | URL (e.g., `"http://proxy.company.com:8080"`)  |
| `https`            | HTTPS proxy server                           | URL (e.g., `"https://proxy.company.com:8080"`) |
| `exclude`          | Bypass proxy for these addresses             | Array of hostnames/IPs                         |
| `pac`              | Proxy Auto-Configuration file URL            | URL to PAC file                                |
| `transparentPorts` | Ports subject to proxy rules                 | Comma-separated ports or wildcard (`"*"`)      |

### [Configuration examples](#configuration-examples)

Block all external access:

```json
"containersProxy": {
  "locked": true,
  "mode": "manual",
  "http": "",
  "https": "",
  "exclude": [],
  "transparentPorts": "*"
}
```

Allow specific internal services:

```json
"containersProxy": {
  "locked": true,
  "mode": "manual",
  "http": "",
  "https": "",
  "exclude": ["internal.company.com", "10.0.0.0/8"],
  "transparentPorts": "80,443"
}
```

Route through corporate proxy:

```json
"containersProxy": {
  "locked": true,
  "mode": "manual",
  "http": "http://corporate-proxy.company.com:8080",
  "https": "http://corporate-proxy.company.com:8080",
  "exclude": ["localhost", "*.company.local"],
  "transparentPorts": "*"
}
```

## [Proxy Auto-Configuration (PAC) files](#proxy-auto-configuration-pac-files)

PAC files provide fine-grained control over container network access by defining rules for different destinations.

### [Basic PAC file structure](#basic-pac-file-structure)

```javascript
function FindProxyForURL(url, host) {
	if (localHostOrDomainIs(host, 'internal.corp')) {
		return "PROXY 10.0.0.1:3128";
	}
	if (isInNet(host, "192.168.0.0", "255.255.255.0")) {
	    return "DIRECT";
	}
    return "PROXY reject.docker.internal:1234";
}
```

### [General considerations](#general-considerations)

* `FindProxyForURL` function URL parameter format is `http://host_or_ip:port` or `https://host_or_ip:port`

* If you have an internal container trying to access `https://docs.docker.com/enterprise/security/hardened-desktop/air-gapped-containers` the Docker proxy service will submit docs.docker.com for the host value and <https://docs.docker.com:443> for the url value to `FindProxyForURL`, if you are using `shExpMatch` function in your PAC file as follows:

  ```console
  if(shExpMatch(url, "https://docs.docker.com:443/enterprise/security/*")) return "DIRECT";
  ```

  `shExpMatch` function will fail, instead use:

  ```console
  if (host == docs.docker.com && url.indexOf(":443") > 0) return "DIRECT";
  ```

### [PAC file return values](#pac-file-return-values)

| Return value                            | Action                                                |
| --------------------------------------- | ----------------------------------------------------- |
| `PROXY host:port`                       | Route through HTTP proxy at specified host and port   |
| `SOCKS5 host:port`                      | Route through SOCKS5 proxy at specified host and port |
| `DIRECT`                                | Allow direct connection without proxy                 |
| `PROXY reject.docker.internal:any_port` | Block the request completely                          |

### [Advanced PAC file example](#advanced-pac-file-example)

```javascript
function FindProxyForURL(url, host) {
  // Allow access to Docker Hub for approved base images
  if (dnsDomainIs(host, ".docker.io") || host === "docker.io") {
    return "PROXY corporate-proxy.company.com:8080";
  }

  // Allow internal package repositories
  if (localHostOrDomainIs(host, 'nexus.company.com') ||
      localHostOrDomainIs(host, 'artifactory.company.com')) {
    return "DIRECT";
  }

  // Allow development tools on specific ports
  if (url.indexOf(":3000") > 0 || url.indexOf(":8080") > 0) {
    if (isInNet(host, "10.0.0.0", "255.0.0.0")) {
      return "DIRECT";
    }
  }

  // Block access to developer's localhost
  if (host === "host.docker.internal" || host === "localhost") {
    return "PROXY reject.docker.internal:1234";
  }

  // Block all other external access
  return "PROXY reject.docker.internal:1234";
}
```

## [Verify air-gapped container configuration](#verify-air-gapped-container-configuration)

After applying the configuration, test that container network restrictions work:

Test blocked access:

```console
$ docker run --rm alpine wget -O- https://www.google.com
# Should fail or timeout based on your proxy rules
```

Test allowed access:

```console
$ docker run --rm alpine wget -O- https://internal.company.com
# Should succeed if internal.company.com is in your exclude list or PAC rules
```

Test proxy routing:

```console
$ docker run --rm alpine wget -O- https://docker.io
# Should succeed if routed through approved proxy
```

## [Security considerations](#security-considerations)

* Network policy enforcement: Air-gapped containers work at the Docker Desktop level. Advanced users might bypass restrictions through various means, so consider additional network-level controls for high-security environments.
* Development workflow impact: Overly restrictive policies can break legitimate development workflows. Test thoroughly and provide clear exceptions for necessary services.
* PAC file management: Host PAC files on reliable internal infrastructure. Failed PAC downloads result in blocked container network access.
* Performance considerations: Complex PAC files with many rules may impact container network performance. Keep rules simple and efficient.

## [Next steps](#next-steps)

* [Explore Enhanced Container Isolation](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) to further restrict what containers can do at runtime
* [Understand how Docker Desktop handles host and container networking](https://docs.docker.com/desktop/features/networking/)

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/compliance-reporting/
----

# Desktop settings reporting

***

Table of contents

***

Subscription: Business

Availability: Early Access

Requires: Docker Desktop 4.40 and later

For: Administrators

Desktop settings reporting tracks user compliance with Docker Desktop settings policies. Use this feature to monitor policy application across your organization and identify users who need assistance with compliance.

## [Prerequisites](#prerequisites)

Before you can use Docker Desktop settings reporting, make sure you have:

* [Docker Desktop](https://docs.docker.com/desktop/release-notes/) installed across your organization
* [A verified domain](https://docs.docker.com/enterprise/security/single-sign-on/connect/)
* [Enforced sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) for your organization
* A Docker Business subscription
* At least one settings policy configured

## [Access the reporting dashboard](#access-the-reporting-dashboard)

To view compliance reporting:

1. Sign in to [Docker Home](https://app.docker.com) and select your organization.
2. Select **Admin Console**, then **Desktop settings reporting**.

The reporting dashboard provides these tools:

* A search field to find users by username or email address
* Filter options to show users assigned to specific policies
* Toggles to hide or un-hide compliant users
* Compliance status indicators
* CSV export option to download compliance data

## [User compliance statuses](#user-compliance-statuses)

Docker Desktop evaluates three types of status to determine overall compliance:

### [Compliance status](#compliance-status)

This is the primary status shown in the dashboard:

| Compliance status   | What it means                                               |
| ------------------- | ----------------------------------------------------------- |
| Compliant           | The user fetched and applied the latest assigned policy.    |
| Non-compliant       | The user fetched the correct policy, but hasn't applied it. |
| Outdated            | The user fetched a previous version of the policy.          |
| No policy assigned  | The user does not have any policy assigned to them.         |
| Uncontrolled domain | The user's email domain is not verified.                    |

### [Domain status](#domain-status)

Shows how the user's email domain relates to your organization:

| Domain status | What it means                                                                |
| ------------- | ---------------------------------------------------------------------------- |
| Verified      | The user’s email domain is verified.                                         |
| Guest user    | The user's email domain is not verified.                                     |
| Domainless    | Your organization has no verified domains, and the user's domain is unknown. |

### [Settings status](#settings-status)

Indicates the user's policy assignment:

| Settings status    | What it means                                            |
| ------------------ | -------------------------------------------------------- |
| Global policy      | The user is assigned your organization's default policy. |
| User policy        | The user is assigned a specific custom policy.           |
| No policy assigned | The user is not assigned to any policy.                  |

## [Monitor compliance](#monitor-compliance)

From the **Desktop settings reporting** dashboard, you can:

* Review organization-wide compliance at a glance
* Turn on **Hide compliant users** to focus on issues
* Filter by specific policies to check targeted compliance
* Export compliance data
* Select any user's name for detailed status and resolution steps

When you select a user's name, you'll see their detailed compliance information including current status, domain verification, assigned policy, last policy fetch time, and Docker Desktop version.

## [Resolve compliance issues](#resolve-compliance-issues)

You can select a non-compliant user's name in the dashboard for recommended status resolution steps. The following sections are general resolution steps for non-compliant statuses:

### [Non-compliant or outdated users](#non-compliant-or-outdated-users)

* Ask the user to fully quit and relaunch Docker Desktop
* Verify the user is signed in to Docker Desktop
* Confirm the user has Docker Desktop 4.40 or later

### [Uncontrolled domain users](#uncontrolled-domain-users)

* Verify the user's email domain in your organization settings
* If the domain should be controlled, add and verify it, then wait for verification
* If the user is a guest and shouldn't be controlled, no action is needed

### [No policy assigned users](#no-policy-assigned-users)

* Assign the user to an existing policy
* Create a new user-specific policy for them
* Verify they're included in your organization's default policy scope

After users take corrective action, refresh the reporting dashboard to verify status changes.

## [Policy update timing](#policy-update-timing)

Docker Desktop checks for policy updates:

* At startup
* Every 60 minutes while Docker Desktop is running
* When users restart Docker Desktop

Changes to policies in the Admin Console are available immediately, but users must restart Docker Desktop to apply them.

----
url: https://docs.docker.com/reference/cli/docker/plugin/ls/
----

# docker plugin ls

***

| Description                                                               | List plugins                 |
| ------------------------------------------------------------------------- | ---------------------------- |
| Usage                                                                     | `docker plugin ls [OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker plugin list`         |

## [Description](#description)

Lists all the plugins that are currently installed. You can install plugins using the [`docker plugin install`](/reference/cli/docker/plugin/install/) command. You can also filter using the `-f` or `--filter` flag. Refer to the [filtering](#filter) section for more information about available filter options.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --filter`](#filter) |         | Provide filter values (e.g. `enabled=true`)                                                                                                                                                                                                                                                                                                                                            |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `--no-trunc`              |         | Don't truncate output                                                                                                                                                                                                                                                                                                                                                                  |
| `-q, --quiet`             |         | Only display plugin IDs                                                                                                                                                                                                                                                                                                                                                                |

## [Examples](#examples)

```console
$ docker plugin ls

ID            NAME                                    DESCRIPTION                ENABLED
69553ca1d123  tiborvass/sample-volume-plugin:latest   A test plugin for Docker   true
```

### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).

The currently supported filters are:

* enabled (boolean - true or false, 0 or 1)
* capability (string - currently `volumedriver`, `networkdriver`, `ipamdriver`, `logdriver`, `metricscollector`, or `authz`)

#### [enabled](#enabled)

The `enabled` filter matches on plugins enabled or disabled.

#### [capability](#capability)

The `capability` filter matches on plugin capabilities. One plugin might have multiple capabilities. Currently `volumedriver`, `networkdriver`, `ipamdriver`, `logdriver`, `metricscollector`, and `authz` are supported capabilities.

```console
$ docker plugin install --disable vieux/sshfs

Installed plugin vieux/sshfs

$ docker plugin ls --filter enabled=true

ID                  NAME                DESCRIPTION         ENABLED
```

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints plugins output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder        | Description                                     |
| ------------------ | ----------------------------------------------- |
| `.ID`              | Plugin ID                                       |
| `.Name`            | Plugin name and tag                             |
| `.Description`     | Plugin description                              |
| `.Enabled`         | Whether plugin is enabled or not                |
| `.PluginReference` | The reference used to push/pull from a registry |

When using the `--format` option, the `plugin ls` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `ID` and `Name` entries separated by a colon (`:`) for all plugins:

```console
$ docker plugin ls --format "{{.ID}}: {{.Name}}"

4be01827a72e: vieux/sshfs:latest
```

To list all plugins in JSON format, use the `json` directive:

```console
$ docker plugin ls --format json
{"Description":"sshFS plugin for Docker","Enabled":false,"ID":"856d89febb1c","Name":"vieux/sshfs:latest","PluginReference":"docker.io/vieux/sshfs:latest"}
```

----
url: https://docs.docker.com/build/cache/
----

# Docker build cache

***

Table of contents

***

When you build the same Docker image multiple times, knowing how to optimize the build cache is a great tool for making sure the builds run fast.

## [How the build cache works](#how-the-build-cache-works)

Understanding Docker's build cache helps you write better Dockerfiles that result in faster builds.

The following example shows a small Dockerfile for a program written in C.

```dockerfile
# syntax=docker/dockerfile:1
FROM ubuntu:latest

RUN apt-get update && apt-get install -y build-essentials
COPY main.c Makefile /src/
WORKDIR /src/
RUN make build
```

Each instruction in this Dockerfile translates to a layer in your final image. You can think of image layers as a stack, with each layer adding more content on top of the layers that came before it:

Whenever a layer changes, that layer will need to be re-built. For example, suppose you make a change to your program in the `main.c` file. After this change, the `COPY` command will have to run again in order for those changes to appear in the image. In other words, Docker will invalidate the cache for this layer.

If a layer changes, all other layers that come after it are also affected. When the layer with the `COPY` command gets invalidated, all layers that follow will need to run again, too:

And that's the Docker build cache in a nutshell. Once a layer changes, then all downstream layers need to be rebuilt as well. Even if they wouldn't build anything differently, they still need to re-run.

## [Other resources](#other-resources)

For more information on using cache to do efficient builds, see:

* [Cache invalidation](https://docs.docker.com/build/cache/invalidation/)
* [Optimize build cache](https://docs.docker.com/build-cloud/optimization/)
* [Garbage collection](https://docs.docker.com/build/cache/garbage-collection/)
* [Cache storage backends](https://docs.docker.com/build/cache/backends/)

----
url: https://docs.docker.com/dhi/explore/
----

# Explore Docker Hardened Images

***

Table of contents

***

Docker Hardened Images (DHI) are minimal, secure, and production-ready container base and application images maintained by Docker. Designed to reduce vulnerabilities and simplify compliance, DHI integrates easily into your existing Docker-based workflows with little to no retooling required.

This section helps you understand what Docker Hardened Images are, how they're built and tested, the different types available, and how responsibility is shared between Docker and you as a user. For a complete list of DHI features and capabilities, see [Features](/dhi/features/).

## [Learn more about Docker Hardened Images](#learn-more-about-docker-hardened-images)

### [What are hardened images and why use them?](/dhi/explore/what/)

[Learn what a hardened image is, how Docker Hardened Images are built, what sets them apart from typical base and application images, and why you should use them.](/dhi/explore/what/)

### [Build process](/dhi/explore/build-process/)

[Learn how Docker builds, tests, and maintains Docker Hardened Images through an automated, security-focused pipeline.](/dhi/explore/build-process/)

### [Image types](/dhi/explore/available/)

[Learn about the different image types, distributions, and variants offered in the Docker Hardened Images catalog.](/dhi/explore/available/)

### [Scanner integrations](/dhi/explore/scanner-integrations/)

[Discover which vulnerability scanners integrate with Docker Hardened Images and support open standards like OpenVEX.](/dhi/explore/scanner-integrations/)

### [Image testing](/dhi/explore/test/)

[See how Docker Hardened Images are automatically tested for standards compliance, functionality, and security.](/dhi/explore/test/)

### [Malware scanning](/dhi/explore/malware-scanning/)

[Learn how Docker scans Docker Hardened Images for viruses and malware, and how to view and verify the scan attestation.](/dhi/explore/malware-scanning/)

### [Responsibility overview](/dhi/explore/responsibility/)

[Understand Docker's role and your responsibilities when using Docker Hardened Images as part of your secure software supply chain.](/dhi/explore/responsibility/)

### [Give feedback](/dhi/explore/feedback)

[Docker welcomes all contributions and feedback.](/dhi/explore/feedback)

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/
----

# docker mcp profile

***

| Description | Manage profiles |
| ----------- | --------------- |

## [Description](#description)

Manage profiles

## [Subcommands](#subcommands)

| Command                                                                                         | Description                                    |
| ----------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [`docker mcp profile config`](https://docs.docker.com/reference/cli/docker/mcp/profile/config/) | Update the configuration of a profile          |
| [`docker mcp profile create`](https://docs.docker.com/reference/cli/docker/mcp/profile/create/) | Create a new profile of MCP servers            |
| [`docker mcp profile export`](https://docs.docker.com/reference/cli/docker/mcp/profile/export/) | Export profile to file                         |
| [`docker mcp profile import`](https://docs.docker.com/reference/cli/docker/mcp/profile/import/) | Import profile from file                       |
| [`docker mcp profile list`](https://docs.docker.com/reference/cli/docker/mcp/profile/list/)     | List profiles                                  |
| [`docker mcp profile pull`](https://docs.docker.com/reference/cli/docker/mcp/profile/pull/)     | Pull profile from OCI registry                 |
| [`docker mcp profile push`](https://docs.docker.com/reference/cli/docker/mcp/profile/push/)     | Push profile to OCI registry                   |
| [`docker mcp profile remove`](https://docs.docker.com/reference/cli/docker/mcp/profile/remove/) | Remove a profile                               |
| [`docker mcp profile server`](https://docs.docker.com/reference/cli/docker/mcp/profile/server/) | Manage servers in profiles                     |
| [`docker mcp profile show`](https://docs.docker.com/reference/cli/docker/mcp/profile/show/)     | Show profile                                   |
| [`docker mcp profile tools`](https://docs.docker.com/reference/cli/docker/mcp/profile/tools/)   | Manage tool allowlist for servers in a profile |

----
url: https://docs.docker.com/desktop/use-desktop/pause/
----

# Pause Docker Desktop

***

***

Pausing Docker Desktop temporarily suspends the Linux VM running Docker Engine. This saves the current state of all containers in memory and freezes all running processes, significantly reducing CPU and memory usage which is helpful for conserving battery on laptops.

To pause Docker Desktop, select the **Pause** icon to the left of the footer in the Docker Dashboard. To manually resume Docker Desktop, select the **Resume** option in the Docker menu, or run any Docker CLI command.

When you manually pause Docker Desktop, a paused status displays on the Docker menu and on the Docker Desktop Dashboard. You can still access the **Settings** and the **Troubleshoot** menu.

> Tip
>
> The Resource Saver feature is enabled by default and provides better CPU and memory savings than the manual Pause feature. See [Resource Saver mode](https://docs.docker.com/desktop/use-desktop/resource-saver/) for more info.

----
url: https://docs.docker.com/build-cloud/usage/
----

# Building with Docker Build Cloud

***

Table of contents

***

To build using Docker Build Cloud, invoke a build command and specify the name of the builder using the `--builder` flag.

```console
$ docker buildx build --builder cloud-ORG-BUILDER_NAME --tag IMAGE .
```

## [Use by default](#use-by-default)

If you want to use Docker Build Cloud without having to specify the `--builder` flag each time, you can set it as the default builder.

Run the following command:

```console
$ docker buildx use cloud-ORG-BUILDER_NAME --global
```

1. Open the Docker Desktop settings and navigate to the **Builders** tab.

2. Find the cloud builder under **Available builders**.

3. Open the drop-down menu and select **Use**.

Changing your default builder with `docker buildx use` only changes the default builder for the `docker buildx build` command. The `docker build` command still uses the `default` builder, unless you specify the `--builder` flag explicitly.

If you use build scripts, such as `make`, that use the `docker build` command, we recommend updating your build commands to `docker buildx build`. Alternatively, you can set the [`BUILDX_BUILDER` environment variable](https://docs.docker.com/build/building/variables/#buildx_builder) to specify which builder `docker build` should use.

## [Use with Docker Compose](#use-with-docker-compose)

To build with Docker Build Cloud using `docker compose build`, first set the cloud builder as your selected builder, then run your build.

> Note
>
> Make sure you're using a supported version of Docker Compose, see [Prerequisites](https://docs.docker.com/build-cloud/setup/#prerequisites).

```console
$ docker buildx use cloud-ORG-BUILDER_NAME
$ docker compose build
```

In addition to `docker buildx use`, you can also use the `docker compose build --builder` flag or the [`BUILDX_BUILDER` environment variable](https://docs.docker.com/build/building/variables/#buildx_builder) to select the cloud builder.

## [Loading build results](#loading-build-results)

Building with `--tag` loads the build result to the local image store automatically when the build finishes. To build without a tag and load the result, you must pass the `--load` flag.

Loading the build result for multi-platform images is not supported. Use the `docker buildx build --push` flag when building multi-platform images to push the output to a registry.

```console
$ docker buildx build --builder cloud-ORG-BUILDER_NAME \
  --platform linux/amd64,linux/arm64 \
  --tag IMAGE \
  --push .
```

If you want to build with a tag, but you don't want to load the results to your local image store, you can export the build results to the build cache only:

```console
$ docker buildx build --builder cloud-ORG-BUILDER_NAME \
  --platform linux/amd64,linux/arm64 \
  --tag IMAGE \
  --output type=cacheonly .
```

## [Multi-platform builds](#multi-platform-builds)

To run multi-platform builds, you must specify all of the platforms that you want to build for using the `--platform` flag.

```console
$ docker buildx build --builder cloud-ORG-BUILDER_NAME \
  --platform linux/amd64,linux/arm64 \
  --tag IMAGE \
  --push .
```

If you don't specify the platform, the cloud builder automatically builds for the architecture matching your local environment.

To learn more about building for multiple platforms, refer to [Multi-platform builds](/build/building/multi-platform/).

## [Cloud builds in Docker Desktop](#cloud-builds-in-docker-desktop)

The Docker Desktop [Builds view](/desktop/use-desktop/builds/) works with Docker Build Cloud out of the box. This view can show information about not only your own builds, but also builds initiated by your team members using the same builder.

Teams using a shared builder get access to information such as:

* Ongoing and completed builds
* Build configuration, statistics, dependencies, and results
* Build source (Dockerfile)
* Build logs and errors

This lets you and your team work collaboratively on troubleshooting and improving build speeds, without having to send build logs and benchmarks back and forth between each other.

## [Use secrets with Docker Build Cloud](#use-secrets-with-docker-build-cloud)

To use build secrets with Docker Build Cloud, such as authentication credentials or tokens, use the `--secret` and `--ssh` CLI flags for the `docker buildx` command. The traffic is encrypted and secrets are never stored in the build cache.

> Warning
>
> If you're misusing build arguments to pass credentials, authentication tokens, or other secrets, you should refactor your build to pass the secrets using [secret mounts](/reference/cli/docker/buildx/build/#secret) instead. Build arguments are stored in the cache and their values are exposed through attestations. Secret mounts don't leak outside of the build and are never included in attestations.

For more information, refer to:

* [`docker buildx build --secret`](/reference/cli/docker/buildx/build/#secret)
* [`docker buildx build --ssh`](/reference/cli/docker/buildx/build/#ssh)

## [Managing build cache](#managing-build-cache)

You don't need to manage Docker Build Cloud cache manually. The system manages it for you through [garbage collection](/build/cache/garbage-collection/).

Old cache is automatically removed if you hit your storage limit. You can check your current cache state using the [`docker buildx du` command](/reference/cli/docker/buildx/du/).

To clear the builder's cache manually, use the [`docker buildx prune` command](/reference/cli/docker/buildx/prune/). This works like pruning the cache for any other builder.

> Warning
>
> Pruning a cloud builder's cache also removes the cache for other team members using the same builder.

## [Unset Docker Build Cloud as the default builder](#unset-docker-build-cloud-as-the-default-builder)

If you've set a cloud builder as the default builder and want to revert to the default `docker` builder, run the following command:

```console
$ docker context use default
```

This doesn't remove the builder from your system. It only changes the builder that's automatically selected to run your builds.

## [Registries on internal networks](#registries-on-internal-networks)

It is possible to use Docker Build Cloud with a [private registry](https://docs.docker.com/build-cloud/builder-settings/#private-resource-access) or registry mirror on an internal network.

----
url: https://docs.docker.com/engine/deprecated/
----

# Deprecated Docker Engine features

***

Table of contents

***

This page provides an overview of features that are deprecated in Engine. Changes in packaging, and supported (Linux) distributions are not included. To learn about end of support for Linux distributions, refer to the [release notes](https://docs.docker.com/engine/release-notes/).

## [Feature deprecation policy](#feature-deprecation-policy)

As changes are made to Docker there may be times when existing features need to be removed or replaced with newer features. Before an existing feature is removed it is labeled as "deprecated" within the documentation and remains in Docker for at least one stable release unless specified explicitly otherwise. After that time it may be removed.

Users are expected to take note of the list of deprecated features each release and plan their migration away from those features, and (if applicable) towards the replacement features as soon as possible.

## [Deprecated engine features](#deprecated-engine-features)

The following table provides an overview of the current status of deprecated features:

* **Deprecated**: the feature is marked "deprecated" and should no longer be used.

  The feature may be removed, disabled, or change behavior in a future release. The *"Deprecated"* column contains the release in which the feature was marked deprecated, whereas the *"Remove"* column contains a tentative release in which the feature is to be removed. If no release is included in the *"Remove"* column, the release is yet to be decided on.

* **Removed**: the feature was removed, disabled, or hidden.

  Refer to the linked section for details. Some features are "soft" deprecated, which means that they remain functional for backward compatibility, and to allow users to migrate to alternatives. In such cases, a warning may be printed, and users should not rely on this feature.

| Status     | Feature                                                                                                                            | Deprecated | Remove |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------ |
| Deprecated | [Support for cgroup v1](#support-for-cgroup-v1)                                                                                    | v29.0      | -      |
| Deprecated | [`--pause` option on `docker commit`](#--pause-option-on-docker-commit)                                                            | v29.0      | v30.0  |
| Deprecated | [Legacy links environment variables](#legacy-links-environment-variables)                                                          | v28.4      | v30.0  |
| Deprecated | [Special handling for quoted values for TLS flags](#special-handling-for-quoted-values-for-tls-flags)                              | v28.4      | v29.0  |
| Deprecated | [Empty/nil fields in image Config from inspect API](#emptynil-fields-in-image-config-from-inspect-api)                             | v28.3      | v29.0  |
| Deprecated | [Configuration for pushing non-distributable artifacts](#configuration-for-pushing-non-distributable-artifacts)                    | v28.0      | v29.0  |
| Deprecated | [`--time` option on `docker stop` and `docker restart`](#--time-option-on-docker-stop-and-docker-restart)                          | v28.0      | -      |
| Removed    | [Non-standard fields in image inspect](#non-standard-fields-in-image-inspect)                                                      | v27.0      | v28.2  |
| Removed    | [API CORS headers](#api-cors-headers)                                                                                              | v27.0      | v28.0  |
| Removed    | [Graphdriver plugins (experimental)](#graphdriver-plugins-experimental)                                                            | v27.0      | v28.0  |
| Deprecated | [Unauthenticated TCP connections](#unauthenticated-tcp-connections)                                                                | v26.0      | v28.0  |
| Removed    | [`Container` and `ContainerConfig` fields in Image inspect](#container-and-containerconfig-fields-in-image-inspect)                | v25.0      | v26.0  |
| Removed    | [Deprecate legacy API versions](#deprecate-legacy-api-versions)                                                                    | v25.0      | v26.0  |
| Removed    | [Container short ID in network Aliases field](#container-short-id-in-network-aliases-field)                                        | v25.0      | v26.0  |
| Removed    | [Mount `bind-nonrecursive` option](#mount-bind-nonrecursive-option)                                                                | v25.0      | v29.0  |
| Removed    | [IsAutomated field, and `is-automated` filter on `docker search`](#isautomated-field-and-is-automated-filter-on-docker-search)     | v25.0      | v28.2  |
| Removed    | [logentries logging driver](#logentries-logging-driver)                                                                            | v24.0      | v25.0  |
| Removed    | [OOM-score adjust for the daemon](#oom-score-adjust-for-the-daemon)                                                                | v24.0      | v25.0  |
| Removed    | [BuildKit build information](#buildkit-build-information)                                                                          | v23.0      | v24.0  |
| Deprecated | [Legacy builder for Linux images](#legacy-builder-for-linux-images)                                                                | v23.0      | -      |
| Deprecated | [Legacy builder fallback](#legacy-builder-fallback)                                                                                | v23.0      | -      |
| Removed    | [Btrfs storage driver on CentOS 7 and RHEL 7](#btrfs-storage-driver-on-centos-7-and-rhel-7)                                        | v20.10     | v23.0  |
| Removed    | [Support for encrypted TLS private keys](#support-for-encrypted-tls-private-keys)                                                  | v20.10     | v23.0  |
| Removed    | [Kubernetes stack and context support](#kubernetes-stack-and-context-support)                                                      | v20.10     | v23.0  |
| Removed    | [Pulling images from non-compliant image registries](#pulling-images-from-non-compliant-image-registries)                          | v20.10     | v28.2  |
| Removed    | [Linux containers on Windows (LCOW)](#linux-containers-on-windows-lcow-experimental)                                               | v20.10     | v23.0  |
| Deprecated | [BLKIO weight options with cgroups v1](#blkio-weight-options-with-cgroups-v1)                                                      | v20.10     | -      |
| Removed    | [Kernel memory limit](#kernel-memory-limit)                                                                                        | v20.10     | v23.0  |
| Removed    | [Classic Swarm and overlay networks using external key/value stores](#classic-swarm-and-overlay-networks-using-cluster-store)      | v20.10     | v23.0  |
| Removed    | [Support for the legacy `~/.dockercfg` configuration file for authentication](#support-for-legacy-dockercfg-configuration-files)   | v20.10     | v23.0  |
| Deprecated | [CLI plugins support](#cli-plugins-support)                                                                                        | v20.10     | -      |
| Deprecated | [Dockerfile legacy `ENV name value` syntax](#dockerfile-legacy-env-name-value-syntax)                                              | v20.10     | -      |
| Removed    | [`docker build --stream` flag (experimental)](#docker-build---stream-flag-experimental)                                            | v20.10     | v20.10 |
| Removed    | [`fluentd-async-connect` log opt](#fluentd-async-connect-log-opt)                                                                  | v20.10     | v28.0  |
| Removed    | [Configuration options for experimental CLI features](#configuration-options-for-experimental-cli-features)                        | v19.03     | v23.0  |
| Removed    | [Pushing and pulling with image manifest v2 schema 1](#pushing-and-pulling-with-image-manifest-v2-schema-1)                        | v19.03     | v28.2  |
| Removed    | [`docker engine` subcommands](#docker-engine-subcommands)                                                                          | v19.03     | v20.10 |
| Removed    | [Top-level `docker deploy` subcommand (experimental)](#top-level-docker-deploy-subcommand-experimental)                            | v19.03     | v20.10 |
| Removed    | [`docker stack deploy` using "dab" files (experimental)](#docker-stack-deploy-using-dab-files-experimental)                        | v19.03     | v20.10 |
| Removed    | [Support for the `overlay2.override_kernel_check` storage option](#support-for-the-overlay2override_kernel_check-storage-option)   | v19.03     | v24.0  |
| Removed    | [AuFS storage driver](#aufs-storage-driver)                                                                                        | v19.03     | v24.0  |
| Removed    | [Legacy "overlay" storage driver](#legacy-overlay-storage-driver)                                                                  | v18.09     | v24.0  |
| Removed    | [Device mapper storage driver](#device-mapper-storage-driver)                                                                      | v18.09     | v25.0  |
| Removed    | [Use of reserved namespaces in engine labels](#use-of-reserved-namespaces-in-engine-labels)                                        | v18.06     | v20.10 |
| Removed    | [`--disable-legacy-registry` override daemon option](#--disable-legacy-registry-override-daemon-option)                            | v17.12     | v19.03 |
| Removed    | [Interacting with V1 registries](#interacting-with-v1-registries)                                                                  | v17.06     | v17.12 |
| Removed    | [Asynchronous `service create` and `service update` as default](#asynchronous-service-create-and-service-update-as-default)        | v17.05     | v17.10 |
| Removed    | [`-g` and `--graph` flags on `dockerd`](#-g-and---graph-flags-on-dockerd)                                                          | v17.05     | v23.0  |
| Deprecated | [Top-level network properties in NetworkSettings](#top-level-network-properties-in-networksettings)                                | v1.13      | v17.12 |
| Removed    | [`filter` option for `/images/json` endpoint](#filter-option-for-imagesjson-endpoint)                                              | v1.13      | v20.10 |
| Removed    | [`repository:shortid` image references](#repositoryshortid-image-references)                                                       | v1.13      | v17.12 |
| Removed    | [`docker daemon` subcommand](#docker-daemon-subcommand)                                                                            | v1.13      | v17.12 |
| Removed    | [Duplicate keys with conflicting values in engine labels](#duplicate-keys-with-conflicting-values-in-engine-labels)                | v1.13      | v17.12 |
| Deprecated | [`MAINTAINER` in Dockerfile](#maintainer-in-dockerfile)                                                                            | v1.13      | -      |
| Deprecated | [API calls without a version](#api-calls-without-a-version)                                                                        | v1.13      | v17.12 |
| Removed    | [Backing filesystem without `d_type` support for overlay/overlay2](#backing-filesystem-without-d_type-support-for-overlayoverlay2) | v1.13      | v17.12 |
| Removed    | [`--automated` and `--stars` flags on `docker search`](#--automated-and---stars-flags-on-docker-search)                            | v1.12      | v20.10 |
| Deprecated | [`-h` shorthand for `--help`](#-h-shorthand-for---help)                                                                            | v1.12      | v17.09 |
| Removed    | [`-e` and `--email` flags on `docker login`](#-e-and---email-flags-on-docker-login)                                                | v1.11      | v17.06 |
| Deprecated | [Separator (`:`) of `--security-opt` flag on `docker run`](#separator--of---security-opt-flag-on-docker-run)                       | v1.11      | v17.06 |
| Deprecated | [Ambiguous event fields in API](#ambiguous-event-fields-in-api)                                                                    | v1.10      | -      |
| Removed    | [`-f` flag on `docker tag`](#-f-flag-on-docker-tag)                                                                                | v1.10      | v1.12  |
| Removed    | [HostConfig at API container start](#hostconfig-at-api-container-start)                                                            | v1.10      | v1.12  |
| Removed    | [`--before` and `--since` flags on `docker ps`](#--before-and---since-flags-on-docker-ps)                                          | v1.10      | v1.12  |
| Removed    | [Driver-specific log tags](#driver-specific-log-tags)                                                                              | v1.9       | v1.12  |
| Removed    | [Docker Content Trust `ENV` passphrase variables name change](#docker-content-trust-env-passphrase-variables-name-change)          | v1.9       | v1.12  |
| Removed    | [`/containers/(id or name)/copy` endpoint](#containersid-or-namecopy-endpoint)                                                     | v1.8       | v1.12  |
| Removed    | [LXC built-in exec driver](#lxc-built-in-exec-driver)                                                                              | v1.8       | v1.10  |
| Removed    | [Old Command Line Options](#old-command-line-options)                                                                              | v1.8       | v1.10  |
| Removed    | [`--api-enable-cors` flag on `dockerd`](#--api-enable-cors-flag-on-dockerd)                                                        | v1.6       | v17.09 |
| Removed    | [`--run` flag on `docker commit`](#--run-flag-on-docker-commit)                                                                    | v0.10      | v1.13  |
| Removed    | [Three arguments form in `docker import`](#three-arguments-form-in-docker-import)                                                  | v0.6.7     | v1.12  |

### [Support for cgroup v1](#support-for-cgroup-v1)

**Deprecated in release: v29.0**

Support for cgroup v1 is deprecated in the v29.0 release, however, it will continue to be supported until May 2029. The latest release in May 2029 may not necessarily support cgroup v1, but there will be at least one maintained branch with the support for cgroup v1.

The cgroup version currently in use can be checked by running the `docker info` command:

```console
$ docker info
<...>
Server:
 <...>
 Cgroup Version: 2
 <...>
```

### [`--pause` option on `docker commit`](#--pause-option-on-docker-commit)

**Deprecated in release: v29.0**

**Target for removal in release: v30.0**

The `--pause` option is enabled by default since Docker v1.1.0 to prevent committing containers in an inconsistent state, but can be disabled by setting the `--pause=false` option. In docker CLI v29.0 this flag is replaced by a `--no-pause` flag instead. The `--pause` option is still functional in the v29.0 release, printing a deprecation warning, but will be removed in docker CLI v30.

### [Legacy links environment variables](#legacy-links-environment-variables)

**Deprecated in release: v28.4**

**Disabled by default in release: v29.0**

**Target for removal in release: v30.0**

Containers attached to the default bridge network can specify "legacy links" (e.g. using `--links` on the CLI) to get access to other containers attached to that network. The linking container (i.e., the container created with `--links`) automatically gets environment variables that specify the IP address and port mappings of the linked container. However, these environment variables are prefixed with the linked container's names, making them impractical.

Starting with Docker v29.0, these environment variables are no longer set by default. Users who still depend on them can start Docker Engine with the environment variable `DOCKER_KEEP_DEPRECATED_LEGACY_LINKS_ENV_VARS=1` set.

Support for legacy links environment variables, as well as the `DOCKER_KEEP_DEPRECATED_LEGACY_LINKS_ENV_VARS` will be removed in Docker Engine v30.0.

### [Special handling for quoted values for TLS flags](#special-handling-for-quoted-values-for-tls-flags)

**Deprecated in release: v28.4**

**Target for removal in release: v29.0**

The `--tlscacert`, `--tlscert`, and `--tlskey` command-line flags had non-standard behavior for handling values contained in quotes (`"` or `'`). Normally, quotes are handled by the shell, for example, in the following example, the shell takes care of handling quotes before passing the values to the `docker` CLI:

```console
docker --some-option "some-value-in-quotes" ...
```

However, when passing values using an equal sign (`=`), this may not happen and values may be handled including quotes;

```console
docker --some-option="some-value-in-quotes" ...
```

This caused issues with "Docker Machine", which used this format as part of its `docker-machine config` output, and the CLI carried special, non-standard handling for these flags.

Docker Machine reached EOL, and this special handling made the processing of flag values inconsistent with other flags used, so this behavior is deprecated. Users depending on this behavior are recommended to specify the quoted values using a space between the flag and its value, as illustrated above.

### [Empty/nil fields in image Config from inspect API](#emptynil-fields-in-image-config-from-inspect-api)

**Deprecated in release: v28.3**

**Target for removal in release: v29.0**

The `Config` field returned by `docker image inspect` (and the `GET /images/{name}/json` API endpoint) currently includes certain fields even when they are empty or nil. Starting in Docker v29.0, the following fields will be omitted from the API response when they contain empty or default values:

* `Cmd`
* `Entrypoint`
* `Env`
* `Labels`
* `OnBuild`
* `User`
* `Volumes`
* `WorkingDir`

Applications consuming the image inspect API should be updated to handle the absence of these fields gracefully, treating missing fields as having their default/empty values.

For API version corresponding to Docker v29.0, these fields will be omitted when empty. They will continue to be included when using clients that request an older API version for backward compatibility.

### [Configuration for pushing non-distributable artifacts](#configuration-for-pushing-non-distributable-artifacts)

**Deprecated in release: v28.0**

**Target for removal in release: v29.0**

Non-distributable artifacts (also called foreign layers) were introduced in docker v1.12 to accommodate Windows images for which the EULA did not allow layers to be distributed through registries other than those hosted by Microsoft. The concept of foreign / non-distributable layers was adopted by the OCI distribution spec in [oci#233](https://github.com/opencontainers/image-spec/pull/233). These restrictions were relaxed later to allow distributing these images through non-public registries, for which a configuration was added in Docker v17.0.6.0.

In 2022, Microsoft updated the EULA and [removed these restrictions](https://techcommunity.microsoft.com/blog/containers/announcing-windows-container-base-image-redistribution-rights-change/3645201), followed by the OCI distribution specification deprecating foreign layers in [oci#965](https://github.com/opencontainers/image-spec/pull/965). In 2023, Microsoft [removed the use of foreign data layers](https://techcommunity.microsoft.com/blog/containers/announcing-removal-of-foreign-layers-from-windows-container-images/3846833) for their images, making this functionality obsolete.

Docker v28.0 deprecates the `--allow-nondistributable-artifacts` daemon flag and corresponding `allow-nondistributable-artifacts` field in `daemon.json`. Setting either option no longer takes an effect, but a deprecation warning log is added to raise awareness about the deprecation. This warning is planned to become an error in the Docker v29.0.

Users currently using these options are therefore recommended to remove this option from their configuration to prevent the daemon from starting when upgrading to Docker v29.0.

The `AllowNondistributableArtifactsCIDRs` and `AllowNondistributableArtifactsHostnames` fields in the `RegistryConfig` of the `GET /info` API response are also deprecated. For API version v1.48 and lower, the fields are still included in the response but always `null`. In API version v1.49 and higher, the field will be omitted entirely.

### [`--time` option on `docker stop` and `docker restart`](#--time-option-on-docker-stop-and-docker-restart)

**Deprecated in release: v28.0**

The `--time` option for the `docker stop`, `docker container stop`, `docker restart`, and `docker container restart` commands has been renamed to `--timeout` for consistency with other uses of timeout options. The `--time` option is now deprecated and hidden, but remains functional for backward compatibility. Users are encouraged to migrate to using the `--timeout` option instead.

### [Non-standard fields in image inspect](#non-standard-fields-in-image-inspect)

**Deprecated in release: v27.0**

**Removed in release: v28.2**

The `Config` field returned shown in `docker image inspect` (and as returned by the `GET /images/{name}/json` API endpoint) returns additional fields that are not part of the image's configuration and not part of the [Docker image specification](https://github.com/moby/docker-image-spec/blob/v1.3.1/specs-go/v1/image.go#L19-L32) and [OCI image specification](https://github.com/opencontainers/image-spec/blob/v1.1.0/specs-go/v1/config.go#L24-L62).

These fields are never set (and always return the default value for the type), but are not omitted in the response when left empty. As these fields were not intended to be part of the image configuration response, they are deprecated, and will be removed from the API in thee next release.

The following fields are not part of the underlying image's `Config` field, and removed in the API response for API v1.50 and newer, corresponding with v28.2. They continue to be included when using clients that use an older API version:

* `Hostname`
* `Domainname`
* `AttachStdin`
* `AttachStdout`
* `AttachStderr`
* `Tty`
* `OpenStdin`
* `StdinOnce`
* `Image`
* `NetworkDisabled` (omitted unless set on older API versions)
* `MacAddress` (omitted unless set on older API versions)
* `StopTimeout` (omitted unless set on older API versions)

### [Graphdriver plugins (experimental)](#graphdriver-plugins-experimental)

**Deprecated in**: v27.0\*\*.

**Disabled by default in release: v27.0**

**Target for removal in release: v28.0**

[Graphdriver plugins](https://github.com/docker/cli/blob/v26.1.4/docs/extend/plugins_graphdriver.md) were an experimental feature that allowed extending the Docker Engine with custom storage drivers for storing images and containers. This feature was not maintained since its inception.

Support for graphdriver plugins was disabled by default in v27.0, and removed in v28.0. Users of this feature are recommended to instead configure the Docker Engine to use the [containerd image store](https://docs.docker.com/storage/containerd/) and a custom [snapshotter](https://github.com/containerd/containerd/tree/v1.7.18/docs/snapshotters)

### [API CORS headers](#api-cors-headers)

**Deprecated in release: v27.0**

**Disabled by default in release: v27.0**

**Removed in release: v28.0**

The `api-cors-header` configuration option for the Docker daemon is insecure, and is therefore deprecated and scheduled for removal. Incorrectly setting this option could leave a window of opportunity for unauthenticated cross-origin requests to be accepted by the daemon.

In Docker Engine v27.0, this flag can still be set, but it has no effect unless the environment variable `DOCKERD_DEPRECATED_CORS_HEADER` is also set to a non-empty value.

This flag has been removed altogether in v28.0.

This is a breaking change for authorization plugins and other programs that depend on this option for accessing the Docker API from a browser. If you need to access the API through a browser, use a reverse proxy.

### [Unauthenticated TCP connections](#unauthenticated-tcp-connections)

**Deprecated in release: v26.0**

**Target for removal in release: v28.0**

Configuring the Docker daemon to listen on a TCP address will require mandatory TLS verification. This change aims to ensure secure communication by preventing unauthorized access to the Docker daemon over potentially insecure networks. This mandatory TLS requirement applies to all TCP addresses except `tcp://localhost`.

In version 27.0 and later, specifying `--tls=false` or `--tlsverify=false` CLI flags causes the daemon to fail to start if it's also configured to accept remote connections over TCP. This also applies to the equivalent configuration options in `daemon.json`.

To facilitate remote access to the Docker daemon over TCP, you'll need to implement TLS verification. This secures the connection by encrypting data in transit and providing a mechanism for mutual authentication.

For environments remote daemon access isn't required, we recommend binding the Docker daemon to a Unix socket. For daemons where remote access is required and where TLS encryption is not feasible, you may want to consider using SSH as an alternative solution.

For further information, assistance, and step-by-step instructions on configuring TLS (or SSH) for the Docker daemon, refer to [Protect the Docker daemon socket](https://docs.docker.com/engine/security/protect-access/).

### [`Container` and `ContainerConfig` fields in Image inspect](#container-and-containerconfig-fields-in-image-inspect)

**Deprecated in release: v25.0**

**Removed in release: v26.0**

The `Container` and `ContainerConfig` fields returned by `docker inspect` are mostly an implementation detail of the classic (non-BuildKit) image builder. These fields are not portable and are empty when using the BuildKit-based builder (enabled by default since v23.0). These fields are deprecated in v25.0 and are omitted starting from v26.0 ( API version v1.45 and up). If image configuration of an image is needed, you can obtain it from the `Config` field.

### [Deprecate legacy API versions](#deprecate-legacy-api-versions)

**Deprecated in release: v25.0**

**Target for removal in release: v26.0**

The Docker daemon provides a versioned API for backward compatibility with old clients. Docker clients can perform API-version negotiation to select the most recent API version supported by the daemon (downgrading to and older version of the API when necessary). API version negotiation was introduced in Docker v1.12.0 (API 1.24), and clients before that used a fixed API version.

Docker Engine versions through v25.0 provide support for all [API versions](https://docs.docker.com/engine/api/#api-version-matrix) included in stable releases for a given platform. For Docker daemons on Linux, the earliest supported API version is 1.12 (corresponding with Docker Engine v1.0.0), whereas for Docker daemons on Windows, the earliest supported API version is 1.24 (corresponding with Docker Engine v1.12.0).

Support for legacy API versions (providing old API versions on current versions of the Docker Engine) is primarily intended to provide compatibility with recent, but still supported versions of the client, which is a common scenario (the Docker daemon may be updated to the latest release, but not all clients may be up-to-date or vice versa). Support for API versions before that (API versions provided by EOL versions of the Docker Daemon) is provided on a "best effort" basis.

Use of old API versions is rare, and support for legacy API versions involves significant complexity (Docker 1.0.0 having been released 10 years ago). Because of this, we'll start deprecating support for legacy API versions.

Docker Engine v25.0 by default disables API version older than 1.24 (aligning the minimum supported API version between Linux and Windows daemons). When connecting with a client that uses an API version older than 1.24, the daemon returns an error. The following example configures the Docker CLI to use API version 1.23, which produces an error:

```console
DOCKER_API_VERSION=1.23 docker version
Error response from daemon: client version 1.23 is too old. Minimum supported API version is 1.24,
upgrade your client to a newer version
```

Support for API versions lower than `1.24` has been permanently removed in Docker Engine v26, and the minimum supported API version will be incrementally raised in releases following that.

### [Container short ID in network Aliases field](#container-short-id-in-network-aliases-field)

**Deprecated in release: v25.0**

**Removed in release: v26.0**

The `Aliases` field returned by `docker inspect` contains the container short ID once the container is started. This behavior is deprecated in v25.0 but kept until the next release, v26.0. Starting with that version, the `Aliases` field will only contain the aliases set through the `docker container create` and `docker run` flag `--network-alias`.

A new field `DNSNames` containing the container name (if one was specified), the hostname, the network aliases, as well as the container short ID, has been introduced in v25.0 and should be used instead of the `Aliases` field.

### [Mount `bind-nonrecursive` option](#mount-bind-nonrecursive-option)

**Deprecated in release: v25.0**

**Removed in release: v29.0**

The `bind-nonrecursive` option was replaced with the [`bind-recursive`](https://docs.docker.com/engine/storage/bind-mounts/#recursive-mounts) option (see [cli-4316](https://github.com/docker/cli/pull/4316), [cli-4671](https://github.com/docker/cli/pull/4671)). The option was still accepted, but printed a deprecation warning:

```console
bind-nonrecursive is deprecated, use bind-recursive=disabled instead
```

In the v29.0 release, this warning is removed, and returned as an error. Users should use the equivalent `bind-recursive=disabled` option instead.

### [IsAutomated field, and `is-automated` filter on `docker search`](#isautomated-field-and-is-automated-filter-on-docker-search)

**Deprecated in release: v25.0**

**Removed in release: v28.2**

The `is_automated` field has been deprecated by Docker Hub's search API. Consequently, the `IsAutomated` field in image search will always be set to `false` in future, and searching for "is-automated=true" will yield no results.

The `AUTOMATED` column has been removed from the default `docker search` and `docker image search` output in v25.0, and the corresponding `IsAutomated` templating has been removed in v28.2.

### [Logentries logging driver](#logentries-logging-driver)

**Deprecated in release: v24.0**

**Removed in release: v25.0**

The logentries service SaaS was shut down on November 15, 2022, rendering this logging driver non-functional. Users should no longer use this logging driver, and the driver has been removed in Docker 25.0. Existing containers using this logging-driver are migrated to use the "local" logging driver after upgrading.

### [OOM-score adjust for the daemon](#oom-score-adjust-for-the-daemon)

**Deprecated in release: v24.0**

**Removed in release: v25.0**

The `oom-score-adjust` option was added to prevent the daemon from being OOM-killed before other processes. This option was mostly added as a convenience, as running the daemon as a systemd unit was not yet common.

Having the daemon set its own limits is not best-practice, and something better handled by the process-manager starting the daemon.

Docker v20.10 and newer no longer adjust the daemon's OOM score by default, instead setting the OOM-score to the systemd unit (OOMScoreAdjust) that's shipped with the packages.

Users currently depending on this feature are recommended to adjust the daemon's OOM score using systemd or through other means, when starting the daemon.

### [BuildKit build information](#buildkit-build-information)

**Deprecated in release: v23.0**

**Removed in release: v24.0**

[Build information](https://github.com/moby/buildkit/blob/v0.11/docs/buildinfo.md) structures have been introduced in [BuildKit v0.10.0](https://github.com/moby/buildkit/releases/tag/v0.10.0) and are generated with build metadata that allows you to see all the sources (images, Git repositories) that were used by the build with their exact versions and also the configuration that was passed to the build. This information is also embedded into the image configuration if one is generated.

### [Legacy builder for Linux images](#legacy-builder-for-linux-images)

**Deprecated in release: v23.0**

Docker v23.0 now uses BuildKit by default to build Linux images, and uses the [Buildx](https://docs.docker.com/buildx/working-with-buildx/) CLI component for `docker build`. With this change, `docker build` now exposes all advanced features that BuildKit provides and which were previously only available through the `docker buildx` subcommands.

The Buildx component is installed automatically when installing the `docker` CLI using our `.deb` or `.rpm` packages, and statically linked binaries are provided both on `download.docker.com`, and through the [`docker/buildx-bin` image](https://hub.docker.com/r/docker/buildx-bin) on Docker Hub. Refer the [Buildx section](http://docs.docker.com/go/buildx/) for detailed instructions on installing the Buildx component.

This release marks the beginning of the deprecation cycle of the classic ("legacy") builder for Linux images. No active development will happen on the classic builder (except for bugfixes). BuildKit development started five Years ago, left the "experimental" phase since Docker 18.09, and is already the default builder for [Docker Desktop](https://docs.docker.com/desktop/previous-versions/3.x-mac/#docker-desktop-320). While we're comfortable that BuildKit is stable for general use, there may be some changes in behavior. If you encounter issues with BuildKit, we encourage you to report issues in the [BuildKit issue tracker on GitHub](https://github.com/moby/buildkit/){:target="*blank" rel="noopener" class="*"}

> Classic builder for building Windows images
>
> BuildKit does not (yet) provide support for building Windows images, and `docker build` continues to use the classic builder to build native Windows images on Windows daemons.

### [Legacy builder fallback](#legacy-builder-fallback)

**Deprecated in release: v23.0**

[Docker v23.0 now uses BuildKit by default to build Linux images](#legacy-builder-for-linux-images), which requires the Buildx component to build images with BuildKit. There may be situations where the Buildx component is not available, and BuildKit cannot be used.

To provide a smooth transition to BuildKit as the default builder, Docker v23.0 has an automatic fallback for some situations, or produces an error to assist users to resolve the problem.

In situations where the user did not explicitly opt-in to use BuildKit (i.e., `DOCKER_BUILDKIT=1` is not set), the CLI automatically falls back to the classic builder, but prints a deprecation warning:

```text
DEPRECATED: The legacy builder is deprecated and will be removed in a future release.
            Install the buildx component to build images with BuildKit:
            https://docs.docker.com/go/buildx/
```

This situation may occur if the `docker` CLI is installed using the static binaries, and the Buildx component is not installed or not installed correctly. This fallback will be removed in a future release, therefore we recommend to [install the Buildx component](https://docs.docker.com/go/buildx/) and use BuildKit for your builds, or opt-out of using BuildKit with `DOCKER_BUILDKIT=0`.

If you opted-in to use BuildKit (`DOCKER_BUILDKIT=1`), but the Buildx component is missing, an error is printed instead, and the `docker build` command fails:

```text
ERROR: BuildKit is enabled but the buildx component is missing or broken.
       Install the buildx component to build images with BuildKit:
       https://docs.docker.com/go/buildx/
```

We recommend to [install the Buildx component](https://docs.docker.com/go/buildx/) to continue using BuildKit for your builds, but alternatively, users can either unset the `DOCKER_BUILDKIT` environment variable to fall back to the legacy builder, or opt-out of using BuildKit with `DOCKER_BUILDKIT=0`.

Be aware that the [classic builder is deprecated](#legacy-builder-for-linux-images) so both the automatic fallback and opting-out of using BuildKit will no longer be possible in a future release.

### [Btrfs storage driver on CentOS 7 and RHEL 7](#btrfs-storage-driver-on-centos-7-and-rhel-7)

**Removed in release: v23.0**

The `btrfs` storage driver on CentOS and RHEL was provided as a technology preview by CentOS and RHEL, but has been deprecated since the [Red Hat Enterprise Linux 7.4 release](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/ch-btrfs), and removed in CentOS 8 and RHEL 8. Users of the `btrfs` storage driver on CentOS are recommended to migrate to a different storage driver, such as `overlay2`, which is now the default storage driver. Docker 23.0 continues to provide the `btrfs` storage driver to allow users to migrate to an alternative driver. The next release of Docker will no longer provide this driver.

### [Support for encrypted TLS private keys](#support-for-encrypted-tls-private-keys)

**Deprecated in release: v20.10**

**Removed in release: v23.0**

Use of encrypted TLS private keys has been deprecated, and has been removed. Golang has deprecated support for legacy PEM encryption (as specified in [RFC 1423](https://datatracker.ietf.org/doc/html/rfc1423)), as it is insecure by design (see <https://go-review.googlesource.com/c/go/+/264159>).

This feature allowed using an encrypted private key with a supplied password, but did not provide additional security as the encryption is known to be broken, and the key is sitting next to the password in the filesystem. Users are recommended to decrypt the private key, and store it un-encrypted to continue using it.

### [Kubernetes stack and context support](#kubernetes-stack-and-context-support)

**Deprecated in release: v20.10**

**Removed in release: v23.0**

Following the deprecation of [Compose on Kubernetes](https://github.com/docker/compose-on-kubernetes), support for Kubernetes in the `stack` and `context` commands has been removed from the CLI, and options related to this functionality are now either ignored, or may produce an error.

The following command-line flags are removed from the `docker context` subcommands:

* `--default-stack-orchestrator` - swarm is now the only (and default) orchestrator for stacks.
* `--kubernetes` - the Kubernetes endpoint can no longer be stored in `docker context`.
* `--kubeconfig` - exporting a context as a kubeconfig file is no longer supported.

The output produced by the `docker context inspect` subcommand no longer contains information about `StackOrchestrator` and `Kubernetes` endpoints for new contexts.

The following command-line flags are removed from the `docker stack` subcommands:

* `--kubeconfig` - using a kubeconfig file as context is no longer supported.
* `--namespace` - configuring the Kubernetes namespace for stacks is no longer supported.
* `--orchestrator` - swarm is now the only (and default) orchestrator for stacks.

The `DOCKER_STACK_ORCHESTRATOR`, `DOCKER_ORCHESTRATOR`, and `KUBECONFIG` environment variables, as well as the `stackOrchestrator` option in the `~/.docker/config.json` CLI configuration file are no longer used, and ignored.

### [Pulling images from non-compliant image registries](#pulling-images-from-non-compliant-image-registries)

**Deprecated in release: v20.10**

**Removed in release: v28.2**

Docker Engine v20.10 and up includes optimizations to verify if images in the local image cache need updating before pulling, preventing the Docker Engine from making unnecessary API requests. These optimizations require the container image registry to conform to the [Open Container Initiative Distribution Specification](https://github.com/opencontainers/distribution-spec).

While most registries conform to the specification, we encountered some registries to be non-compliant, resulting in `docker pull` to fail.

As a temporary solution, Docker Engine v20.10 added a fallback mechanism to allow `docker pull` to be functional when using a non-compliant registry. A warning message is printed in this situation:

```
WARNING Failed to pull manifest by the resolved digest. This registry does not
        appear to conform to the distribution registry specification; falling back to
        pull by tag. This fallback is DEPRECATED, and will be removed in a future
        release.
```

The fallback was added to allow users to either migrate their images to a compliant registry, or for these registries to become compliant.

GitHub deprecated the legacy `docker.pkg.github.com` registry, and it was [sunset on Feb 24th, 2025](https://github.blog/changelog/2025-01-23-legacy-docker-registry-closing-down/) in favor of GitHub Container Registry (GHCR, ghcr.io), making this fallback no longer needed.

### [Linux containers on Windows (LCOW) (experimental)](#linux-containers-on-windows-lcow-experimental)

**Deprecated in release: v20.10**

**Removed in release: v23.0**

The experimental feature to run Linux containers on Windows (LCOW) was introduced as a technical preview in Docker 17.09. While many enhancements were made after its introduction, the feature never reached completeness, and development has now stopped in favor of running Docker natively on Linux in WSL2.

Developers who want to run Linux workloads on a Windows host are encouraged to use [Docker Desktop with WSL2](https://docs.docker.com/docker-for-windows/wsl/) instead.

### [BLKIO weight options with cgroups v1](#blkio-weight-options-with-cgroups-v1)

**Deprecated in release: v20.10**

Specifying blkio weight (`docker run --blkio-weight` and `docker run --blkio-weight-device`) is now marked as deprecated when using cgroups v1 because the corresponding features were [removed in Linux kernel v5.0 and up](https://github.com/torvalds/linux/commit/f382fb0bcef4c37dc049e9f6963e3baf204d815c). When using cgroups v2, the `--blkio-weight` options are implemented using [\`io.weight](https://github.com/torvalds/linux/blob/v5.0/Documentation/admin-guide/cgroup-v2.rst#io).

### [Kernel memory limit](#kernel-memory-limit)

**Deprecated in release: v20.10**

**Removed in release: v23.0**

Specifying kernel memory limit (`docker run --kernel-memory`) is no longer supported because the [Linux kernel deprecated `kmem.limit_in_bytes` in v5.4](https://github.com/torvalds/linux/commit/0158115f702b0ba208ab0b5adf44cae99b3ebcc7). The OCI runtime specification now marks this option as ["NOT RECOMMENDED"](https://github.com/opencontainers/runtime-spec/pull/1093), and OCI runtimes such as `runc` no longer support this option.

The Docker API no longer handles the kernel-memory fields, and Docker CLI v29.0 removes the `--kernel-memory` option.

### [Classic Swarm and overlay networks using cluster store](#classic-swarm-and-overlay-networks-using-cluster-store)

**Deprecated in release: v20.10**

**Removed in release: v23.0**

Standalone ("classic") Swarm has been deprecated, and with that the use of overlay networks using an external key/value store. The corresponding`--cluster-advertise`, `--cluster-store`, and `--cluster-store-opt` daemon options have been removed.

### [Support for legacy `~/.dockercfg` configuration files](#support-for-legacy-dockercfg-configuration-files)

**Deprecated in release: v20.10**

**Removed in release: v23.0**

The Docker CLI up until v1.7.0 used the `~/.dockercfg` file to store credentials after authenticating to a registry (`docker login`). Docker v1.7.0 replaced this file with a new CLI configuration file, located in `~/.docker/config.json`. When implementing the new configuration file, the old file (and file-format) was kept as a fall-back, to assist existing users with migrating to the new file.

Given that the old file format encourages insecure storage of credentials (credentials are stored unencrypted), and that no version of the CLI since Docker v1.7.0 has created this file, support for this file, and its format has been removed.

### [Configuration options for experimental CLI features](#configuration-options-for-experimental-cli-features)

**Deprecated in release: v19.03**

**Removed in release: v23.0**

The `DOCKER_CLI_EXPERIMENTAL` environment variable and the corresponding `experimental` field in the CLI configuration file are deprecated. Experimental features are enabled by default, and these configuration options are no longer functional.

Starting with v23.0, the Docker CLI no longer prints `Experimental` for the client in the output of `docker version`, and the field has been removed from the JSON format.

### [CLI plugins support](#cli-plugins-support)

**Deprecated in release: v20.10**

CLI Plugin API is now marked as deprecated.

### [Dockerfile legacy `ENV name value` syntax](#dockerfile-legacy-env-name-value-syntax)

**Deprecated in release: v20.10**

The Dockerfile `ENV` instruction allows values to be set using either `ENV name=value` or `ENV name value`. The latter (`ENV name value`) form can be ambiguous, for example, the following defines a single env-variable (`ONE`) with value `"TWO= THREE=world"`, but may have intended to be setting three env-vars:

```dockerfile
ENV ONE TWO= THREE=world
```

This format also does not allow setting multiple environment-variables in a single `ENV` line in the Dockerfile.

Use of the `ENV name value` syntax is discouraged, and may be removed in a future release. Users are encouraged to update their Dockerfiles to use the `ENV name=value` syntax, for example:

```dockerfile
ENV ONE="" TWO="" THREE="world"
```

### [`docker build --stream` flag (experimental)](#docker-build---stream-flag-experimental)

**Deprecated in release: v20.10**

**Removed in release: v20.10**

Docker v17.07 introduced an experimental `--stream` flag on `docker build` which allowed the build-context to be incrementally sent to the daemon, instead of unconditionally sending the whole build-context.

This functionality has been reimplemented as part of BuildKit, which uses streaming by default and the `--stream` option will be ignored when using the classic builder, printing a deprecation warning instead.

Users that want to use this feature are encouraged to enable BuildKit by setting the `DOCKER_BUILDKIT=1` environment variable or through the daemon or CLI configuration files.

### [`fluentd-async-connect` log opt](#fluentd-async-connect-log-opt)

**Deprecated in release: v20.10**

**Removed in release: v28.0**

The `--log-opt fluentd-async-connect` option for the fluentd logging driver is [deprecated in favor of `--log-opt fluentd-async`](https://github.com/moby/moby/pull/39086). A deprecation message is logged in the daemon logs if the old option is used:

```console
fluent#New: AsyncConnect is now deprecated, use Async instead
```

Users are encouraged to use the `fluentd-async` option going forward, as support for the old option has been removed.

### [Pushing and pulling with image manifest v2 schema 1](#pushing-and-pulling-with-image-manifest-v2-schema-1)

**Deprecated in release: v19.03**

**Disabled by default in release: v26.0**

**Removed in release: v28.2**

The image manifest [v2 schema 1](https://distribution.github.io/distribution/spec/deprecated-schema-v1/) and "Docker Image v1" formats were deprecated in favor of the [v2 schema 2](https://distribution.github.io/distribution/spec/manifest-v2-2/) and [OCI image spec](https://github.com/opencontainers/image-spec/tree/v1.1.0) formats.

These legacy formats should no longer be used, and users are recommended to update images to use current formats, or to upgrade to more current images. Starting with Docker v26.0, pulling these images is disabled by default, and support has been removed in v28.2. Attempting to pull a legacy image now produces an error:

```console
$ docker pull ubuntu:10.04
Error response from daemon:
Docker Image Format v1 and Docker Image manifest version 2, schema 1 support has been removed.
Suggest the author of docker.io/library/ubuntu:10.04 to upgrade the image to the OCI Format or Docker Image manifest v2, schema 2.
More information at https://docs.docker.com/go/deprecated-image-specs/
```

### [`docker engine` subcommands](#docker-engine-subcommands)

**Deprecated in release: v19.03**

**Removed in release: v20.10**

The `docker engine activate`, `docker engine check`, and `docker engine update` provided an alternative installation method to upgrade Docker Community engines to Docker Enterprise, using an image-based distribution of the Docker Engine.

This feature was only available on Linux, and only when executed on a local node. Given the limitations of this feature, and the feature not getting widely adopted, the `docker engine` subcommands will be removed, in favor of installation through standard package managers.

### [Top-level `docker deploy` subcommand (experimental)](#top-level-docker-deploy-subcommand-experimental)

**Deprecated in release: v19.03**

**Removed in release: v20.10**

The top-level `docker deploy` command (using the "Docker Application Bundle" (.dab) file format was introduced as an experimental feature in Docker 1.13 / 17.03, but superseded by support for Docker Compose files using the `docker stack deploy` subcommand.

### [`docker stack deploy` using "dab" files (experimental)](#docker-stack-deploy-using-dab-files-experimental)

**Deprecated in release: v19.03**

**Removed in release: v20.10**

With no development being done on this feature, and no active use of the file format, support for the DAB file format and the top-level `docker deploy` command (hidden by default in 19.03), will be removed, in favour of `docker stack deploy` using compose files.

### [Support for the `overlay2.override_kernel_check` storage option](#support-for-the-overlay2override_kernel_check-storage-option)

**Deprecated in release: v19.03**

**Removed in release: v24.0**

This daemon configuration option disabled the Linux kernel version check used to detect if the kernel supported OverlayFS with multiple lower dirs, which is required for the overlay2 storage driver. Starting with Docker v19.03.7, the detection was improved to no longer depend on the kernel *version*, so this option was no longer used.

### [AuFS storage driver](#aufs-storage-driver)

**Deprecated in release: v19.03**

**Removed in release: v24.0**

The `aufs` storage driver is deprecated in favor of `overlay2`, and has been removed in a Docker Engine v24.0. Users of the `aufs` storage driver must migrate to a different storage driver, such as `overlay2`, before upgrading to Docker Engine v24.0.

The `aufs` storage driver facilitated running Docker on distros that have no support for OverlayFS, such as Ubuntu 14.04 LTS, which originally shipped with a 3.14 kernel.

Now that Ubuntu 14.04 is no longer a supported distro for Docker, and `overlay2` is available to all supported distros (as they are either on kernel 4.x, or have support for multiple lowerdirs backported), there is no reason to continue maintenance of the `aufs` storage driver.

### [Legacy overlay storage driver](#legacy-overlay-storage-driver)

**Deprecated in release: v18.09**

**Removed in release: v24.0**

The `overlay` storage driver is deprecated in favor of the `overlay2` storage driver, which has all the benefits of `overlay`, without its limitations (excessive inode consumption). The legacy `overlay` storage driver has been removed in Docker Engine v24.0. Users of the `overlay` storage driver should migrate to the `overlay2` storage driver before upgrading to Docker Engine v24.0.

The legacy `overlay` storage driver allowed using overlayFS-backed filesystems on kernels older than v4.x. Now that all supported distributions are able to run `overlay2` (as they are either on kernel 4.x, or have support for multiple lowerdirs backported), there is no reason to keep maintaining the `overlay` storage driver.

### [Device mapper storage driver](#device-mapper-storage-driver)

**Deprecated in release: v18.09**

**Disabled by default in release: v23.0**

**Removed in release: v25.0**

The `devicemapper` storage driver is deprecated in favor of `overlay2`, and has been removed in Docker Engine v25.0. Users of the `devicemapper` storage driver must migrate to a different storage driver, such as `overlay2`, before upgrading to Docker Engine v25.0.

The `devicemapper` storage driver facilitates running Docker on older (3.x) kernels that have no support for other storage drivers (such as overlay2, or btrfs).

Now that support for `overlay2` is added to all supported distros (as they are either on kernel 4.x, or have support for multiple lowerdirs backported), there is no reason to continue maintenance of the `devicemapper` storage driver.

### [Use of reserved namespaces in engine labels](#use-of-reserved-namespaces-in-engine-labels)

**Deprecated in release: v18.06**

**Removed in release: v20.10**

The namespaces `com.docker.*`, `io.docker.*`, and `org.dockerproject.*` in engine labels were always documented to be reserved, but there was never any enforcement.

Usage of these namespaces will now cause a warning in the engine logs to discourage their use, and will error instead in v20.10 and above.

### [`--disable-legacy-registry` override daemon option](#--disable-legacy-registry-override-daemon-option)

**Disabled In Release: v17.12**

**Removed in release: v19.03**

The `--disable-legacy-registry` flag was disabled in Docker 17.12 and will print an error when used. For this error to be printed, the flag itself is still present, but hidden. The flag has been removed in Docker 19.03.

### [Interacting with V1 registries](#interacting-with-v1-registries)

**Disabled by default in release: v17.06**

**Removed in release: v17.12**

Version 1.8.3 added a flag (`--disable-legacy-registry=false`) which prevents the Docker daemon from `pull`, `push`, and `login` operations against v1 registries. Though enabled by default, this signals the intent to deprecate the v1 protocol.

Support for the v1 protocol to the public registry was removed in 1.13. Any mirror configurations using v1 should be updated to use a [v2 registry mirror](https://docs.docker.com/registry/recipes/mirror/).

Starting with Docker 17.12, support for V1 registries has been removed, and the `--disable-legacy-registry` flag can no longer be used, and `dockerd` will fail to start when set.

### [Asynchronous `service create` and `service update` as default](#asynchronous-service-create-and-service-update-as-default)

**Deprecated in release: v17.05**

**Disabled by default in release: [v17.10](https://github.com/docker/docker-ce/releases/tag/v17.10.0-ce)**

Docker 17.05 added an optional `--detach=false` option to make the `docker service create` and `docker service update` work synchronously. This option will be enabled by default in Docker 17.10, at which point the `--detach` flag can be used to use the previous (asynchronous) behavior.

The default for this option will also be changed accordingly for `docker service rollback` and `docker service scale` in Docker 17.10.

### [`-g` and `--graph` flags on `dockerd`](#-g-and---graph-flags-on-dockerd)

**Deprecated in release: v17.05**

**Removed in release: v23.0**

The `-g` or `--graph` flag for the `dockerd` or `docker daemon` command was used to indicate the directory in which to store persistent data and resource configuration and has been replaced with the more descriptive `--data-root` flag. These flags were deprecated and hidden in v17.05, and removed in v23.0.

### [Top-level network properties in NetworkSettings](#top-level-network-properties-in-networksettings)

**Deprecated in release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**

**Target for removal in release: v17.12**

When inspecting a container, `NetworkSettings` contains top-level information about the default ("bridge") network;

`EndpointID`, `Gateway`, `GlobalIPv6Address`, `GlobalIPv6PrefixLen`, `IPAddress`, `IPPrefixLen`, `IPv6Gateway`, and `MacAddress`.

These properties are deprecated in favor of per-network properties in `NetworkSettings.Networks`. These properties were already "deprecated" in Docker 1.9, but kept around for backward compatibility.

Refer to [#17538](https://github.com/docker/docker/pull/17538) for further information.

### [`filter` option for `/images/json` endpoint](#filter-option-for-imagesjson-endpoint)

**Deprecated in release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**

**Removed in release: v20.10**

The `filter` option to filter the list of image by reference (name or name:tag) is now implemented as a regular filter, named `reference`.

### [`repository:shortid` image references](#repositoryshortid-image-references)

**Deprecated in release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**

**Removed in release: v17.12**

The `repository:shortid` syntax for referencing images is very little used, collides with tag references, and can be confused with digest references.

Support for the `repository:shortid` notation to reference images was removed in Docker 17.12.

### [`docker daemon` subcommand](#docker-daemon-subcommand)

**Deprecated in release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**

**Removed in release: v17.12**

The daemon is moved to a separate binary (`dockerd`), and should be used instead.

### [Duplicate keys with conflicting values in engine labels](#duplicate-keys-with-conflicting-values-in-engine-labels)

**Deprecated in release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**

**Removed in release: v17.12**

When setting duplicate keys with conflicting values, an error will be produced, and the daemon will fail to start.

### [`MAINTAINER` in Dockerfile](#maintainer-in-dockerfile)

**Deprecated in release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**

`MAINTAINER` was an early very limited form of `LABEL` which should be used instead.

### [API calls without a version](#api-calls-without-a-version)

**Deprecated in release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**

**Target for removal in release: v17.12**

API versions should be supplied to all API calls to ensure compatibility with future Engine versions. Instead of just requesting, for example, the URL `/containers/json`, you must now request `/v1.25/containers/json`.

### [Backing filesystem without `d_type` support for overlay/overlay2](#backing-filesystem-without-d_type-support-for-overlayoverlay2)

**Deprecated in release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**

**Removed in release: v17.12**

The overlay and overlay2 storage driver does not work as expected if the backing filesystem does not support `d_type`. For example, XFS does not support `d_type` if it is formatted with the `ftype=0` option.

Support for these setups has been removed, and Docker v23.0 and up now fails to start when attempting to use the `overlay2` or `overlay` storage driver on a backing filesystem without `d_type` support.

Refer to [#27358](https://github.com/docker/docker/issues/27358) for details.

### [`--automated` and `--stars` flags on `docker search`](#--automated-and---stars-flags-on-docker-search)

**Deprecated in release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**

**Removed in release: v20.10**

The `docker search --automated` and `docker search --stars` options are deprecated. Use `docker search --filter=is-automated=<true|false>` and `docker search --filter=stars=...` instead.

### [`-h` shorthand for `--help`](#-h-shorthand-for---help)

**Deprecated in release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**

**Target for removal in release: v17.09**

The shorthand (`-h`) is less common than `--help` on Linux and cannot be used on all subcommands (due to it conflicting with, e.g. `-h` / `--hostname` on `docker create`). For this reason, the `-h` shorthand was not printed in the "usage" output of subcommands, nor documented, and is now marked "deprecated".

### [`-e` and `--email` flags on `docker login`](#-e-and---email-flags-on-docker-login)

**Deprecated in release: [v1.11.0](https://github.com/docker/docker/releases/tag/v1.11.0)**

**Removed in release: [v17.06](https://github.com/docker/docker-ce/releases/tag/v17.06.0-ce)**

The `docker login` no longer automatically registers an account with the target registry if the given username doesn't exist. Due to this change, the email flag is no longer required, and will be deprecated.

### [Separator (`:`) of `--security-opt` flag on `docker run`](#separator--of---security-opt-flag-on-docker-run)

**Deprecated in release: [v1.11.0](https://github.com/docker/docker/releases/tag/v1.11.0)**

**Target for removal in release: v17.06**

The flag `--security-opt` doesn't use the colon separator (`:`) anymore to divide keys and values, it uses the equal symbol (`=`) for consistency with other similar flags, like `--storage-opt`.

### [Ambiguous event fields in API](#ambiguous-event-fields-in-api)

**Deprecated in release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**

The fields `ID`, `Status` and `From` in the events API have been deprecated in favor of a more rich structure. See the events API documentation for the new format.

### [`-f` flag on `docker tag`](#-f-flag-on-docker-tag)

**Deprecated in release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**

**Removed in release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**

To make tagging consistent across the various `docker` commands, the `-f` flag on the `docker tag` command is deprecated. It is no longer necessary to specify `-f` to move a tag from one image to another. Nor will `docker` generate an error if the `-f` flag is missing and the specified tag is already in use.

### [HostConfig at API container start](#hostconfig-at-api-container-start)

**Deprecated in release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**

**Removed in release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**

Passing an `HostConfig` to `POST /containers/{name}/start` is deprecated in favor of defining it at container creation (`POST /containers/create`).

### [`--before` and `--since` flags on `docker ps`](#--before-and---since-flags-on-docker-ps)

**Deprecated in release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**

**Removed in release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**

The `docker ps --before` and `docker ps --since` options are deprecated. Use `docker ps --filter=before=...` and `docker ps --filter=since=...` instead.

### [Driver-specific log tags](#driver-specific-log-tags)

**Deprecated in release: [v1.9.0](https://github.com/docker/docker/releases/tag/v1.9.0)**

**Removed in release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**

Log tags are now generated in a standard way across different logging drivers. Because of which, the driver specific log tag options `syslog-tag`, `gelf-tag` and `fluentd-tag` have been deprecated in favor of the generic `tag` option.

```console
$ docker --log-driver=syslog --log-opt tag="{{.ImageName}}/{{.Name}}/{{.ID}}"
```

### [Docker Content Trust ENV passphrase variables name change](#docker-content-trust-env-passphrase-variables-name-change)

**Deprecated in release: [v1.9.0](https://github.com/docker/docker/releases/tag/v1.9.0)**

**Removed in release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**

Since 1.9, Docker Content Trust Offline key has been renamed to Root key and the Tagging key has been renamed to Repository key. Due to this renaming, we're also changing the corresponding environment variables

* DOCKER\_CONTENT\_TRUST\_OFFLINE\_PASSPHRASE is now named DOCKER\_CONTENT\_TRUST\_ROOT\_PASSPHRASE
* DOCKER\_CONTENT\_TRUST\_TAGGING\_PASSPHRASE is now named DOCKER\_CONTENT\_TRUST\_REPOSITORY\_PASSPHRASE

### [`/containers/(id or name)/copy` endpoint](#containersid-or-namecopy-endpoint)

**Deprecated in release: [v1.8.0](https://github.com/docker/docker/releases/tag/v1.8.0)**

**Removed in release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**

The endpoint `/containers/(id or name)/copy` is deprecated in favor of `/containers/(id or name)/archive`.

### [LXC built-in exec driver](#lxc-built-in-exec-driver)

**Deprecated in release: [v1.8.0](https://github.com/docker/docker/releases/tag/v1.8.0)**

**Removed in release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**

The built-in LXC execution driver, the lxc-conf flag, and API fields have been removed.

### [Old Command Line Options](#old-command-line-options)

**Deprecated in release: [v1.8.0](https://github.com/docker/docker/releases/tag/v1.8.0)**

**Removed in release: [v1.10.0](https://github.com/docker/docker/releases/tag/v1.10.0)**

The flags `-d` and `--daemon` are deprecated. Use the separate `dockerd` binary instead.

The following single-dash (`-opt`) variant of certain command line options are deprecated and replaced with double-dash options (`--opt`):

* `docker attach -nostdin`
* `docker attach -sig-proxy`
* `docker build -no-cache`
* `docker build -rm`
* `docker commit -author`
* `docker commit -run`
* `docker events -since`
* `docker history -notrunc`
* `docker images -notrunc`
* `docker inspect -format`
* `docker ps -beforeId`
* `docker ps -notrunc`
* `docker ps -sinceId`
* `docker rm -link`
* `docker run -cidfile`
* `docker run -dns`
* `docker run -entrypoint`
* `docker run -expose`
* `docker run -link`
* `docker run -lxc-conf`
* `docker run -n`
* `docker run -privileged`
* `docker run -volumes-from`
* `docker search -notrunc`
* `docker search -stars`
* `docker search -t`
* `docker search -trusted`
* `docker tag -force`

The following double-dash options are deprecated and have no replacement:

* `docker run --cpuset`
* `docker run --networking`
* `docker ps --since-id`
* `docker ps --before-id`
* `docker search --trusted`

**Deprecated in release: [v1.5.0](https://github.com/docker/docker/releases/tag/v1.5.0)**

**Removed in release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**

The single-dash (`-help`) was removed, in favor of the double-dash `--help`

### [`--api-enable-cors` flag on `dockerd`](#--api-enable-cors-flag-on-dockerd)

**Deprecated in release: [v1.6.0](https://github.com/docker/docker/releases/tag/v1.6.0)**

**Removed in release: [v17.09](https://github.com/docker/docker-ce/releases/tag/v17.09.0-ce)**

The flag `--api-enable-cors` is deprecated since v1.6.0. Use the flag `--api-cors-header` instead.

### [`--run` flag on `docker commit`](#--run-flag-on-docker-commit)

**Deprecated in release: [v0.10.0](https://github.com/docker/docker/releases/tag/v0.10.0)**

**Removed in release: [v1.13.0](https://github.com/docker/docker/releases/tag/v1.13.0)**

The flag `--run` of the `docker commit` command (and its short version `-run`) were deprecated in favor of the `--changes` flag that allows to pass `Dockerfile` commands.

### [Three arguments form in `docker import`](#three-arguments-form-in-docker-import)

**Deprecated in release: [v0.6.7](https://github.com/docker/docker/releases/tag/v0.6.7)**

**Removed in release: [v1.12.0](https://github.com/docker/docker/releases/tag/v1.12.0)**

The `docker import` command format `file|URL|- [REPOSITORY [TAG]]` is deprecated since November 2013. It's no longer supported.

----
url: https://docs.docker.com/reference/cli/docker/node/inspect/
----

# docker node inspect

***

| Description | Display detailed information on one or more nodes    |
| ----------- | ---------------------------------------------------- |
| Usage       | `docker node inspect [OPTIONS] self\|NODE [NODE...]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Returns information about a node. By default, this command renders all results in a JSON array. You can specify an alternate format to execute a given template for each result. Go's [text/template](https://pkg.go.dev/text/template) package describes all the details of the format.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                             |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --format`](#format) |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `--pretty`                |         | Print the information in a human friendly format                                                                                                                                                                                        |

## [Examples](#examples)

### [Inspect a node](#inspect-a-node)

```console
$ docker node inspect swarm-manager
```

```json
[
  {
    "ID": "e216jshn25ckzbvmwlnh5jr3g",
    "Version": {
      "Index": 10
    },
    "CreatedAt": "2017-05-16T22:52:44.9910662Z",
    "UpdatedAt": "2017-05-16T22:52:45.230878043Z",
    "Spec": {
      "Role": "manager",
      "Availability": "active"
    },
    "Description": {
      "Hostname": "swarm-manager",
      "Platform": {
        "Architecture": "x86_64",
        "OS": "linux"
      },
      "Resources": {
        "NanoCPUs": 1000000000,
        "MemoryBytes": 1039843328
      },
      "Engine": {
        "EngineVersion": "17.06.0-ce",
        "Plugins": [
          {
            "Type": "Volume",
            "Name": "local"
          },
          {
            "Type": "Network",
            "Name": "overlay"
          },
          {
            "Type": "Network",
            "Name": "null"
          },
          {
            "Type": "Network",
            "Name": "host"
          },
          {
            "Type": "Network",
            "Name": "bridge"
          },
          {
            "Type": "Network",
            "Name": "overlay"
          }
        ]
      },
      "TLSInfo": {
        "TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBazCCARCgAwIBAgIUOzgqU4tA2q5Yv1HnkzhSIwGyIBswCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAyMDAyNDAwWhcNMzcwNDI3MDAy\nNDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABMbiAmET+HZyve35ujrnL2kOLBEQhFDZ5MhxAuYs96n796sFlfxTxC1lM/2g\nAh8DI34pm3JmHgZxeBPKUURJHKWjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBS3sjTJOcXdkls6WSY2rTx1KIJueTAKBggqhkjO\nPQQDAgNJADBGAiEAoeVWkaXgSUAucQmZ3Yhmx22N/cq1EPBgYHOBZmHt0NkCIQC3\nzONcJ/+WA21OXtb+vcijpUOXtNjyHfcox0N8wsLDqQ==\n-----END CERTIFICATE-----\n",
        "CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
        "CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExuICYRP4dnK97fm6OucvaQ4sERCEUNnkyHEC5iz3qfv3qwWV/FPELWUz/aACHwMjfimbcmYeBnF4E8pRREkcpQ=="
      }
    },
    "Status": {
      "State": "ready",
      "Addr": "168.0.32.137"
    },
    "ManagerStatus": {
      "Leader": true,
      "Reachability": "reachable",
      "Addr": "168.0.32.137:2377"
    }
  }
]
```

### [Format the output (--format)](#format)

```console
$ docker node inspect --format '{{ .ManagerStatus.Leader }}' self

false
```

Use `--format=pretty` or the `--pretty` shorthand to pretty-print the output:

```console
$ docker node inspect --format=pretty self

ID:                     e216jshn25ckzbvmwlnh5jr3g
Hostname:               swarm-manager
Joined at:              2017-05-16 22:52:44.9910662 +0000 utc
Status:
 State:                 Ready
 Availability:          Active
 Address:               172.17.0.2
Manager Status:
 Address:               172.17.0.2:2377
 Raft Status:           Reachable
 Leader:                Yes
Platform:
 Operating System:      linux
 Architecture:          x86_64
Resources:
 CPUs:                  4
 Memory:                7.704 GiB
Plugins:
  Network:              overlay, bridge, null, host, overlay
  Volume:               local
Engine Version:         17.06.0-ce
TLS Info:
 TrustRoot:
-----BEGIN CERTIFICATE-----
MIIBazCCARCgAwIBAgIUOzgqU4tA2q5Yv1HnkzhSIwGyIBswCgYIKoZIzj0EAwIw
EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAyMDAyNDAwWhcNMzcwNDI3MDAy
NDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
A0IABMbiAmET+HZyve35ujrnL2kOLBEQhFDZ5MhxAuYs96n796sFlfxTxC1lM/2g
Ah8DI34pm3JmHgZxeBPKUURJHKWjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
Af8EBTADAQH/MB0GA1UdDgQWBBS3sjTJOcXdkls6WSY2rTx1KIJueTAKBggqhkjO
PQQDAgNJADBGAiEAoeVWkaXgSUAucQmZ3Yhmx22N/cq1EPBgYHOBZmHt0NkCIQC3
zONcJ/+WA21OXtb+vcijpUOXtNjyHfcox0N8wsLDqQ==
-----END CERTIFICATE-----

 Issuer Public Key: MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExuICYRP4dnK97fm6OucvaQ4sERCEUNnkyHEC5iz3qfv3qwWV/FPELWUz/aACHwMjfimbcmYeBnF4E8pRREkcpQ==
 Issuer Subject:    MBMxETAPBgNVBAMTCHN3YXJtLWNh
```

----
url: https://docs.docker.com/reference/api/dvp/deprecated/
----

# Deprecated Docker Verified Publisher API endpoints

***

Table of contents

***

This page provides an overview of endpoints that are deprecated in Docker Verified Publisher API.

***

| Status | Feature                                                       | Date       |
| ------ | ------------------------------------------------------------- | ---------- |
|        | [Create deprecation log table](#create-deprecation-log-table) | 2025-06-27 |

***

### [Create deprecation log table](#create-deprecation-log-table)

Reformat page

***

----
url: https://docs.docker.com/reference/cli/sbx/create/gemini/
----

# sbx create gemini

| Description | Create a sandbox for gemini                |
| ----------- | ------------------------------------------ |
| Usage       | `sbx create gemini PATH [PATH...] [flags]` |

## [Description](#description)

Create a sandbox with access to a host workspace for gemini.

The workspace path is required and will be mounted inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Global options](#global-options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `-D, --debug`    |         | Enable debug logging                                                                                                                                                                                                   |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Examples](#examples)

```console
# Create in the current directory
sbx create gemini .

# Create with a specific path
sbx create gemini /path/to/project

# Create with additional read-only workspaces
sbx create gemini . /path/to/docs:ro
```

----
url: https://docs.docker.com/desktop/features/networking/
----

# Networking on Docker Desktop

***

Table of contents

***

This page explains how Docker Desktop routes network traffic and file I/O between containers, the VM, and the host, and how this behavior is visible to firewalls and endpoint protection tools.

## [Overview](#overview)

Docker Desktop runs the Docker Engine inside a lightweight Linux virtual machine (VM). Depending on your system configuration and operating system, Docker Desktop routes network and file operations between the Docker VM and the host using different backend components.

### [Backend components and responsibilities](#backend-components-and-responsibilities)

The backend acts as:

* Network proxy: Translates traffic between the host and Linux VM.

  * On Windows and Mac, this is handled by the `com.docker.backend` process.
  * On Linux, the `qemu` process performs this function.

* File server: Handles file access from containers to the host filesystem.

  * When using gRPC FUSE, the backend performs the file sharing.
  * When using `virtiofs`, `osxfs`, or `krun`, file access is handled by those respective daemons rather than the backend process.

* Control plane: Manages Docker API calls, port forwarding, and proxy configuration.

The following table summarizes typical setups in more detail:

| Platform        | Setup                                 | Networking handled by    | File sharing handled by                | Notes                                                      |
| --------------- | ------------------------------------- | ------------------------ | -------------------------------------- | ---------------------------------------------------------- |
| Windows         | Hyper-V                               | `com.docker.backend.exe` | `com.docker.backend.exe`               | Simplest setup with full visibility to EDR/firewall tools  |
| Windows (WSL 2) | WSL 2                                 | `com.docker.backend.exe` | WSL 2 kernel (no visibility from host) | Recommended only when WSL 2 integration is needed          |
| Mac             | Virtualization framework + gRPC FUSE  | `com.docker.backend`     | `com.docker.backend`                   | Recommended for performance and visibility                 |
| Mac             | Virtualization framework + `virtiofs` | `com.docker.backend`     | Apple's Virtualization framework       | Higher performance but no file access visibility from host |
| Mac             | Virtualization framework + `osxfs`    | `com.docker.backend`     | `osxfs`                                | Legacy setup, not recommended                              |
| Mac             | DockerVMM + `virtiofs`                | `com.docker.backend`     | `krun`                                 | Currently in Beta                                          |
| Linux           | Native Linux VM                       | `qemu`                   | `virtiofsd`                            | No `com.docker.backend` process on Linux                   |

## [How containers connect to the internet](#how-containers-connect-to-the-internet)

Each Linux container in Docker Desktop runs inside a small virtual network managed by Docker and every container is attached to a Docker-managed network and receives its own internal IP address. You can view and manage these networks with `docker network ls`, `docker network create`, and `docker network inspect`. They are managed by the [`daemon.json`](https://docs.docker.com/engine/daemon/).

When a container initiates a network request, for example with `apt-get update` or `docker pull`:

* The container’s `eth0` interface connects to a virtual bridge (`docker0`) inside the VM.
* Outbound traffic from the container is sent through Network Address Translation (NAT) using a virtual adapter (typically with an internal IP such as `192.168.65.3`). You can view or change this with the [Docker Desktop settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#network).
* The traffic is transferred to the host system over a shared-memory channel rather than through a traditional virtual network interface. This approach ensures reliable communication and avoids conflicts with host-level network adapters or firewall configurations.
* On the host, Docker Desktop’s backend process receives the traffic and creates standard TCP/IP connections using the same networking APIs as other applications.

All outbound container network traffic originates from the `com.docker.backend` process. Firewalls, VPNs, and security tools, like Crowdstrike, see traffic coming from this process — not from a VM or unknown source so firewall and endpoint security software can apply rules directly to `com.docker.backend`.

## [How exposed ports work](#how-exposed-ports-work)

When you publish a container port using the `-p` or `--publish` flag, Docker Desktop makes that container port accessible from your host system or local network.

For example, with `docker run -p 80:80 nginx`:

* Docker Desktop's backend process listens on the specified host port, in this case, port `80`.
* When an application such as a web browser connects to that port, Docker Desktop forwards the connection into the Linux VM where the container is running over a shared-memory channel.
* Inside the VM, the connection is routed to the container’s internal IP address and port, for example `172.17.0.2:80`.
* The container responds through the same path, so you can access it from your host just like any other local service.

By default, `docker run -p` listens on all network interfaces (`0.0.0.0`), but you can restrict it to a specific address, such as `127.0.0.1` (`localhost`) or a particular network adapter. This behavior can be modified to bind to `localhost` by default in [Docker Desktop's network settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#network)

Host firewalls can permit or deny inbound connections by filtering on `com.docker.backend`.

## [Using Docker Desktop with a proxy](#using-docker-desktop-with-a-proxy)

Docker Desktop can use your system’s default proxy settings or custom settings that you configure with [Docker Desktop's proxy setting](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies). All proxy traffic passes through `com.docker.backend.exe`.

When a proxy is enabled:

* The backend process forwards the network requests, for example `docker pull`, through an internal proxy at `http.docker.internal:3128`.
* The internal proxy then connects either directly to the internet or through your upstream proxy, depending on your configuration and adding authentication if necessary.
* Docker Desktop then downloads the requested images or data through the proxy as usual.

Note that:

* The proxy honors system or manual proxy configuration.
* On Windows, Basic, NTLM, and Kerberos authentication is supported.
* For Mac, NTLM/Kerberos is not supported natively. Run a local proxy on `localhost` as a workaround.
* CLI plugins and other tools that use the Docker API directly must be configured separately with the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables.

## [Firewalls and endpoint visibility](#firewalls-and-endpoint-visibility)

To restrict VM or container networking apply rules to `com.docker.backend.exe` (Windows) `com.docker.backend` (Mac) or `qemu` (Linux) as all VM networking is funneled through these processes.

Use Windows Defender Firewall or enterprise endpoint firewalls for control. This enables traffic inspection and restriction at the host level without modifying the Docker Engine.

Crowdstrike and similar tools can observe all traffic and file access that passes through the backend process.

| Action                                       | Visible to host EDR? | Reason                                 |
| -------------------------------------------- | -------------------- | -------------------------------------- |
| Container reads host files                   | Yes                  | Access handled by `com.docker.backend` |
| Container writes host files                  | Yes                  | Same process performs the write        |
| Container accesses its own filesystem layers | No                   | Exists only inside the VM              |

----
url: https://docs.docker.com/enterprise/enterprise-deployment/faq/
----

# Enterprise deployment FAQs

***

Table of contents

***

## [MSI](#msi)

Common questions about installing Docker Desktop using the MSI installer.

### [What happens to user data if they have an older Docker Desktop installation (i.e. `.exe`)?](#what-happens-to-user-data-if-they-have-an-older-docker-desktop-installation-ie-exe)

Users must [uninstall](https://docs.docker.com/desktop/uninstall/) older `.exe` installations before using the new MSI version. The `.exe` installer includes a `-keep-data` flag that removes Docker Desktop while preserving underlying resources such as the container VMs:

```powershell
# For all-user installations
& 'C:\Program Files\Docker\Docker\Docker Desktop Installer.exe' uninstall -keep-data

# For per-user installations
& '%LOCALAPPDATA%\Programs\DockerDesktop\Docker Desktop Installer.exe' uninstall -keep-data
```

### [What happens if the user's machine has an older `.exe` installation?](#what-happens-if-the-users-machine-has-an-older-exe-installation)

The MSI installer detects older `.exe` installations and blocks the installation until the previous version is uninstalled. It prompts the user to uninstall their current/old version first, before retrying to install the MSI version.

### [My installation failed, how do I find out what happened?](#my-installation-failed-how-do-i-find-out-what-happened)

MSI installations may fail silently, offering little diagnostic feedback.

To debug a failed installation, run the install again with verbose logging enabled:

```powershell
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log"
```

After the installation has failed, open the log file and search for occurrences of `value 3`. This is the exit code Windows Installer outputs when it has failed. Just above the line, you will find the reason for the failure.

### [Why does the installer prompt for a reboot at the end of every fresh installation?](#why-does-the-installer-prompt-for-a-reboot-at-the-end-of-every-fresh-installation)

The installer prompts for a reboot because it assumes that changes have been made to the system that require a reboot to finish their configuration.

For example, if you select the WSL engine, the installer adds the required Windows features. After these features are installed, the system reboots to complete configurations so the WSL engine is functional.

You can suppress reboots by using the `/norestart` option when launching the installer from the command line:

```powershell
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /norestart
```

### [Why isn't the `docker-users` group populated when the MSI is installed with Intune or another MDM solution?](#why-isnt-the-docker-users-group-populated-when-the-msi-is-installed-with-intune-or-another-mdm-solution)

It's common for MDM solutions to install applications in the context of the system account. This means that the `docker-users` group isn't populated with the user's account, as the system account doesn't have access to the user's context.

As an example, you can reproduce this by running the installer with `psexec` in an elevated command prompt:

```powershell
psexec -i -s msiexec /i "DockerDesktop.msi"
```

The installation should complete successfully, but the `docker-users` group won't be populated.

As a workaround, you can create a script that runs in the context of the user account.

The script would be responsible for creating the `docker-users` group and populating it with the correct user.

Here's an example script that creates the `docker-users` group and adds the current user to it (requirements may vary depending on environment):

```powershell
$Group = "docker-users"
$CurrentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name

# Create the group
New-LocalGroup -Name $Group

# Add the user to the group
Add-LocalGroupMember -Group $Group -Member $CurrentUser
```

> Note
>
> After adding a new user to the `docker-users` group, the user must sign out and then sign back in for the changes to take effect.

## [MDM](#mdm)

Common questions about deploying Docker Desktop using mobile device management (MDM) tools such as Jamf, Intune, or Workspace ONE.

### [Why doesn't my MDM tool apply all Docker Desktop configuration settings at once?](#why-doesnt-my-mdm-tool-apply-all-docker-desktop-configuration-settings-at-once)

Some MDM tools, such as Workspace ONE, may not support applying multiple configuration settings in a single XML file. In these cases, you may need to deploy each setting in a separate XML file.

Refer to your MDM provider's documentation for specific deployment requirements or limitations.

----
url: https://docs.docker.com/guides/deno/
----

# Deno language-specific guide

Table of contents

***

Learn how to containerize JavaScript applications with the Deno runtime using Docker.

**Time to complete** 10 minutes

The Deno getting started guide teaches you how to create a containerized Deno application using Docker.

> **Acknowledgment**
>
> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide.

## [What will you learn?](#what-will-you-learn)

* Containerize and run a Deno application using Docker
* Set up a local environment to develop a Deno application using containers
* Use Docker Compose to run the application.
* Configure a CI/CD pipeline for a containerized Deno application using GitHub Actions
* Deploy your containerized application locally to Kubernetes to test and debug your deployment

## [Prerequisites](#prerequisites)

* Basic understanding of JavaScript is assumed.
* You must have familiarity with Docker concepts like containers, images, and Dockerfiles. If you are new to Docker, you can start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide.

After completing the Deno getting started modules, you should be able to containerize your own Deno application based on the examples and instructions provided in this guide.

Start by containerizing an existing Deno application.

## [Modules](#modules)

1. [Containerize your app](https://docs.docker.com/guides/deno/containerize/)

   Learn how to containerize a Deno application.

2. [Develop your app](https://docs.docker.com/guides/deno/develop/)

   Learn how to develop your Deno application locally.

3. [Configure CI/CD](https://docs.docker.com/guides/deno/configure-ci-cd/)

   Learn how to configure CI/CD using GitHub Actions for your Deno application.

4. [Test your deployment](https://docs.docker.com/guides/deno/deploy/)

----
url: https://docs.docker.com/reference/cli/docker/sandbox/reset/
----

# docker sandbox reset

***

| Description | Reset all VM sandboxes and clean up state |
| ----------- | ----------------------------------------- |
| Usage       | `docker sandbox reset [OPTIONS]`          |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Reset all VM sandboxes and permanently delete all VM data.

This command will:

* Stop all running VMs gracefully (30s timeout)
* Delete all VM state directories in \~/.docker/sandboxes/vm/
* Clear image cache in \~/.docker/sandboxes/image-cache/
* Clear all internal registries

The daemon will continue running with fresh state after reset.

⚠️ WARNING: This is a destructive operation that cannot be undone! All running agents will be forcefully terminated and their work will be lost. Cached image tars will be deleted and will need to be recreated on next use.

By default, you will be prompted to confirm (y/N). Use --force to skip the confirmation prompt.

## [Options](#options)

| Option                  | Default | Description              |
| ----------------------- | ------- | ------------------------ |
| [`-f, --force`](#force) |         | Skip confirmation prompt |

## [Examples](#examples)

### [Reset with confirmation prompt](#reset-with-confirmation-prompt)

```console
$ docker sandbox reset
⚠️  WARNING: This will permanently delete all VM data and stop all running agents!
Are you sure you want to continue? (y/N): y
All VMs reset successfully
```

### [Force reset without confirmation (-f, --force)](#force)

Skip the confirmation prompt:

```console
$ docker sandbox reset --force
All VMs reset successfully
```

> Caution
>
> This is a destructive operation that cannot be undone! All running agents will be terminated and their work will be lost.

----
url: https://docs.docker.com/guides/claude-code-sandbox-model-runner/
----

[Run Claude Code in a Docker Sandbox with Docker Model Runner](https://docs.docker.com/guides/claude-code-sandbox-model-runner/)

Combine Docker Sandboxes with Docker Model Runner to run Claude Code in an isolated microVM that talks to a local model on your host through the Anthropic-compatible API.

AI

15 minutes

[« Back to all guides](/guides/)

# Run Claude Code in a Docker Sandbox with Docker Model Runner

***

Table of contents

***

This guide shows how to run Claude Code inside a Docker Sandbox with Docker Model Runner as the backend model provider. You'll keep the agent isolated from your host in a microVM, point it at a local model on your machine, and keep all model traffic on-device.

> **Acknowledgment**
>
> Docker would like to thank [Pradumna Saraf](https://twitter.com/pradumna_saraf) for his contribution to this guide.

In this guide, you'll learn how to:

* Pull a coding model and start Docker Model Runner with TCP enabled
* Allow the sandbox to reach Docker Model Runner on your host
* Create a Claude Code sandbox and set the local endpoint persistently
* Launch Claude Code with a local model and verify the connection
* Package `gpt-oss` with a larger context window for longer prompts

## [How the pieces fit together](#how-the-pieces-fit-together)

Three components cooperate at runtime:

* **Docker Model Runner** runs on your host and serves an Anthropic-compatible API at `http://localhost:12434`.
* **The Docker Sandbox** runs Claude Code inside an isolated microVM. The microVM has its own network and can't reach your host's `localhost` directly.
* **The sandbox proxy** sits on your host and brokers every outbound request from the sandbox. It enforces network policy and translates the special hostname `host.docker.internal` to `localhost`.

Claude Code inside the sandbox sends requests to `http://host.docker.internal:12434`. The proxy rewrites the destination to `localhost:12434`, which Docker Model Runner answers. No model traffic leaves your machine.

## [Prerequisites](#prerequisites)

Before you start, make sure you have:

* [Docker Desktop](https://docs.docker.com/get-started/get-docker/) or Docker Engine installed
* [Docker Model Runner enabled](https://docs.docker.com/ai/model-runner/get-started/#enable-docker-model-runner)
* [Docker Sandboxes (`sbx`) installed and signed in](https://docs.docker.com/ai/sandboxes/get-started/#install-and-sign-in)

If you use Docker Desktop, turn on TCP access in **Settings** > **AI**, or run:

```console
$ docker desktop enable model-runner --tcp 12434
```

## [Step 1: Pull a coding model](#step-1-pull-a-coding-model)

Pull a model on your host before you create the sandbox:

```console
$ docker model pull ai/devstral-small-2
```

You can also use `ai/qwen3-coder` if you want another coding-focused model with a large context window.

## [Step 2: Allow the sandbox to reach Docker Model Runner](#step-2-allow-the-sandbox-to-reach-docker-model-runner)

Sandboxes are network-isolated by default, so you need a policy rule before the sandbox can reach Docker Model Runner.

The rule is matched against the destination the proxy forwards to, not the hostname the sandbox uses. Because the proxy rewrites `host.docker.internal` to `localhost` before forwarding, the rule allows `localhost:12434` even though Claude Code will use `host.docker.internal` in its requests:

```console
$ sbx policy allow network localhost:12434
```

For background on host access from sandboxes, see [Accessing host services from a sandbox](https://docs.docker.com/ai/sandboxes/usage/#accessing-host-services-from-a-sandbox).

## [Step 3: Create a Claude Code sandbox](#step-3-create-a-claude-code-sandbox)

From your project directory, create a sandbox without launching the agent:

```console
$ cd ~/my-project
$ sbx create claude --name claude-dmr .
```

`sbx run` would also work, but it launches Claude Code immediately. Without `ANTHROPIC_BASE_URL` set, Claude Code points at `api.anthropic.com` and either prompts for OAuth or errors out before you can fix the endpoint. Creating the sandbox first lets you write the local endpoint into it before the agent starts.

You don't need to set an Anthropic API key or run `sbx secret set anthropic`. Docker Model Runner doesn't authenticate the local endpoint, and the sandbox proxy only injects credentials for requests bound for `api.anthropic.com`. See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for the full list of services the proxy authenticates.

## [Step 4: Set the local endpoint inside the sandbox](#step-4-set-the-local-endpoint-inside-the-sandbox)

Append `ANTHROPIC_BASE_URL` to the sandbox's persistent environment file so Claude Code reads it on every launch:

```console
$ sbx exec -d claude-dmr bash -c "echo 'export ANTHROPIC_BASE_URL=http://host.docker.internal:12434' >> /etc/sandbox-persistent.sh"
```

The `bash -c` wrapper ensures the `>>` redirect runs inside the sandbox, not on your host. For details on this approach, see [How do I set custom environment variables inside a sandbox?](https://docs.docker.com/ai/sandboxes/faq/#how-do-i-set-custom-environment-variables-inside-a-sandbox).

To confirm the variable is set, open a shell in the sandbox:

```console
$ sbx exec -it claude-dmr bash
$ echo $ANTHROPIC_BASE_URL
http://host.docker.internal:12434
```

## [Step 5: Verify connectivity to Docker Model Runner](#step-5-verify-connectivity-to-docker-model-runner)

Still inside the sandbox shell, send a test request to the host endpoint:

```console
$ curl http://host.docker.internal:12434/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/devstral-small-2",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "Say hello"}]
  }'
```

A successful response confirms the policy rule and base URL are correct. Type `exit` to leave the shell. For more details about the request format, see the [Anthropic-compatible API reference](https://docs.docker.com/ai/model-runner/api-reference/#anthropic-compatible-api).

## [Step 6: Launch Claude Code with the local model](#step-6-launch-claude-code-with-the-local-model)

Run Claude Code in the sandbox and pass the model flag through to the agent:

```console
$ sbx run claude-dmr -- --model ai/devstral-small-2
```

Everything after `--` is forwarded to the Claude Code CLI. Because `ANTHROPIC_BASE_URL` is set in the sandbox's persistent environment, Claude Code routes requests to Docker Model Runner on your host instead of `api.anthropic.com`.

## [Step 7: Inspect Claude Code requests](#step-7-inspect-claude-code-requests)

To inspect the requests Claude Code sends, run on your host:

```console
$ docker model requests --model ai/devstral-small-2 | jq .
```

This helps you debug prompts, context usage, and compatibility issues without attaching to the sandbox.

## [Step 8: Package `gpt-oss` with a larger context window](#step-8-package-gpt-oss-with-a-larger-context-window)

`ai/gpt-oss` defaults to a smaller context window than coding-focused models. To use it for repository-scale prompts, package a larger variant on the host:

```console
$ docker model pull ai/gpt-oss
$ docker model package --from ai/gpt-oss --context-size 32000 gpt-oss:32k
```

Then point Claude Code at the packaged model the next time you run the sandbox:

```console
$ sbx run claude-dmr -- --model gpt-oss:32k
```

## [Clean up](#clean-up)

Sandboxes persist after Claude Code exits. To stop the sandbox without deleting it:

```console
$ sbx stop claude-dmr
```

To remove the sandbox and everything inside, including the persistent environment file:

```console
$ sbx rm claude-dmr
```

Files in your workspace are unaffected.

## [Learn more](#learn-more)

* [Use Claude Code with Docker Model Runner](https://docs.docker.com/guides/claude-code-model-runner/)
* [Get started with Docker Sandboxes](https://docs.docker.com/ai/sandboxes/get-started/)
* [Claude Code in Docker Sandboxes](https://docs.docker.com/ai/sandboxes/agents/claude-code/)
* [Docker Model Runner overview](https://docs.docker.com/ai/model-runner/)
* [Docker Model Runner API reference](https://docs.docker.com/ai/model-runner/api-reference/)

----
url: https://docs.docker.com/reference/compose-file/models/
----

# Models

***

Table of contents

***

Requires: Docker Compose [2.38.0](https://github.com/docker/compose/releases/tag/v2.38.0) and later

The top-level `models` section declares AI models that are used by your Compose application. These models are typically pulled as OCI artifacts, run by a model runner, and exposed as an API that your service containers can consume.

Services can only access models when explicitly granted by a [`models` attribute](https://docs.docker.com/reference/compose-file/services/#models) within the `services` top-level element.

## [Examples](#examples)

### [Example 1](#example-1)

```yaml
services:
  app:
    image: app
    models:
      - ai_model


models:
  ai_model:
    model: ai/model
```

In this basic example:

* The app service uses the `ai_model`.
* The `ai_model` is defined as an OCI artifact (`ai/model`) that is pulled and served by the model runner.
* Docker Compose injects connection info, for example `AI_MODEL_URL`, into the container.

### [Example 2](#example-2)

```yaml
services:
  app:
    image: app
    models:
      my_model:
        endpoint_var: MODEL_URL

models:
  my_model:
    model: ai/model
    context_size: 1024
    runtime_flags: 
      - "--a-flag"
      - "--another-flag=42"
```

In this advanced setup:

* The service app references `my_model` using the long syntax.
* Compose injects the model runner's URL as the environment variable `MODEL_URL`.

## [Attributes](#attributes)

* `model` (required): The OCI artifact identifier for the model. This is what Compose pulls and runs via the model runner.
* `context_size`: Defines the maximum token context size for the model.
* `runtime_flags`: A list of raw command-line flags passed to the inference engine when the model is started.

## [Additional resources](#additional-resources)

For more examples and information on using `model`, see [Use AI models in Compose](https://docs.docker.com/ai/compose/models-and-compose/)

----
url: https://docs.docker.com/build/cache/backends/s3/
----

# Amazon S3 cache

***

Table of contents

***

Availability: Experimental

The `s3` cache storage uploads your resulting build cache to [Amazon S3 file storage service](https://aws.amazon.com/s3/) or other S3-compatible services, such as [MinIO](https://min.io/).

This cache storage backend is not supported with the default `docker` driver. To use this feature, create a new builder using a different driver. See [Build drivers](https://docs.docker.com/build/builders/drivers/) for more information.

## [Synopsis](#synopsis)

```console
$ docker buildx build --push -t <user>/<image> \
  --cache-to type=s3,region=<region>,bucket=<bucket>,name=<cache-image>[,parameters...] \
  --cache-from type=s3,region=<region>,bucket=<bucket>,name=<cache-image> .
```

The following table describes the available CSV parameters that you can pass to `--cache-to` and `--cache-from`.

| Name                 | Option                  | Type        | Default      | Description                                                                                         |
| -------------------- | ----------------------- | ----------- | ------------ | --------------------------------------------------------------------------------------------------- |
| `region`             | `cache-to`,`cache-from` | String      |              | Required. Geographic location.                                                                      |
| `bucket`             | `cache-to`,`cache-from` | String      |              | Required. Name of the S3 bucket.                                                                    |
| `name`               | `cache-to`,`cache-from` | String      | `buildkit`   | Name of the cache image.                                                                            |
| `endpoint_url`       | `cache-to`,`cache-from` | String      |              | Endpoint of the S3 bucket.                                                                          |
| `prefix`             | `cache-to`,`cache-from` | String      |              | Prefix to prepend to all filenames.                                                                 |
| `blobs_prefix`       | `cache-to`,`cache-from` | String      | `blobs/`     | Prefix to prepend to blob filenames.                                                                |
| `upload_parallelism` | `cache-to`              | Integer     | `4`          | Number of parallel layer uploads.                                                                   |
| `touch_refresh`      | `cache-to`              | Time        | `24h`        | Interval for updating the timestamp of unchanged cache layers.                                      |
| `manifests_prefix`   | `cache-to`,`cache-from` | String      | `manifests/` | Prefix to prepend to manifest filenames.                                                            |
| `use_path_style`     | `cache-to`,`cache-from` | Boolean     | `false`      | When `true`, uses `bucket` in the URL instead of hostname.                                          |
| `access_key_id`      | `cache-to`,`cache-from` | String      |              | See [authentication](#authentication).                                                              |
| `secret_access_key`  | `cache-to`,`cache-from` | String      |              | See [authentication](#authentication).                                                              |
| `session_token`      | `cache-to`,`cache-from` | String      |              | See [authentication](#authentication).                                                              |
| `mode`               | `cache-to`              | `min`,`max` | `min`        | Cache layers to export, see [cache mode](https://docs.docker.com/build/cache/backends/#cache-mode). |
| `ignore-error`       | `cache-to`              | Boolean     | `false`      | Ignore errors caused by failed cache exports.                                                       |

## [Authentication](#authentication)

Buildx can reuse existing AWS credentials, configured either using a credentials file or environment variables, for pushing and pulling cache to S3. Alternatively, you can use the `access_key_id`, `secret_access_key`, and `session_token` attributes to specify credentials directly on the CLI.

Refer to [AWS Go SDK, Specifying Credentials](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-gosdk.html#specifying-credentials) for details about authentication using environment variables and credentials file.

## [Further reading](#further-reading)

For an introduction to caching see [Docker build cache](https://docs.docker.com/build/cache/).

For more information on the `s3` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#s3-cache-experimental).

----
url: https://docs.docker.com/guides/bun/develop/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Use containers for Bun development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a Bun application](https://docs.docker.com/guides/bun/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment for your containerized application. This includes:

* Configuring Compose to automatically update your running Compose services as you edit and save your code

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/dockersamples/bun-docker.git && cd bun-docker
```

## [Automatically update services](#automatically-update-services)

Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

Open your `compose.yml` file in an IDE or text editor and then add the Compose Watch instructions. The following example shows how to add Compose Watch to your `compose.yml` file.

|                                             |                                                                                                                                                                                                                     |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```
``` | ```yaml
services:
  server:
    image: bun-server
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    develop:
      watch:
        - action: rebuild
          path: .
``` |

Run the following command to run your application with Compose Watch.

```console
$ docker compose watch
```

Now, if you modify your `server.js` you will see the changes in real time without re-building the image.

To test it out, open the `server.js` file in your favorite text editor and change the message from `{"Status" : "OK"}` to `{"Status" : "Updated"}`. Save the file and refresh your browser at `http://localhost:3000`. You should see the updated message.

[Configure CI/CD for your Bun application »](https://docs.docker.com/guides/bun/configure-ci-cd/)

----
url: https://docs.docker.com/get-started/workshop/04_sharing_app/
----

# Share the application

***

Table of contents

***

Now that you've built an image, you can share it. To share Docker images, you have to use a Docker registry. The default registry is Docker Hub and is where all of the images you've used have come from.

> **Docker ID**
>
> A Docker ID lets you access Docker Hub, which is the world's largest library and community for container images. Create a [Docker ID](https://hub.docker.com/signup) for free if you don't have one.

## [Create a repository](#create-a-repository)

To push an image, you first need to create a repository on Docker Hub.

1. [Sign up](https://www.docker.com/pricing?ref=Docs\&refAction=DocsSharingApp) or Sign in to [Docker Hub](https://hub.docker.com).

2. Select the **Create Repository** button.

3. For the repository name, use `getting-started`. Make sure the **Visibility** is **Public**.

4. Select **Create**.

In the following image, you can see an example Docker command from Docker Hub. This command will push to this repository.

## [Push the image](#push-the-image)

Let's try to push the image to Docker Hub.

1. In the command line, run the following command:

   ```console
   docker push docker/getting-started
   ```

   You'll see an error like this:

   ```console
   $ docker push docker/getting-started
   The push refers to repository [docker.io/docker/getting-started]
   An image does not exist locally with the tag: docker/getting-started
   ```

   This failure is expected because the image isn't tagged correctly yet. Docker is looking for an image name `docker/getting-started`, but your local image is still named `getting-started`.

   You can confirm this by running:

   ```console
   docker image ls
   ```

2. To fix this, first sign in to Docker Hub using your Docker ID: `docker login YOUR-USER-NAME`.

3. Use the `docker tag` command to give the `getting-started` image a new name. Replace `YOUR-USER-NAME` with your Docker ID.

   ```console
   $ docker tag getting-started YOUR-USER-NAME/getting-started
   ```

4. Now run the `docker push` command again. If you're copying the value from Docker Hub, you can drop the `tagname` part, as you didn't add a tag to the image name. If you don't specify a tag, Docker uses a tag called `latest`.

   ```console
   $ docker push YOUR-USER-NAME/getting-started
   ```

## [Run the image on a new instance](#run-the-image-on-a-new-instance)

Now that your image has been built and pushed into a registry, you can run your app on any machine that has Docker installed. Try pulling and running your image on another computer or a cloud instance.

## [Summary](#summary)

In this section, you learned how to share your images by pushing them to a registry. You then went to a brand new instance and were able to run the freshly pushed image. This is quite common in CI pipelines, where the pipeline will create the image and push it to a registry and then the production environment can use the latest version of the image.

Related information:

* [docker CLI reference](/reference/cli/docker/)
* [Multi-platform images](https://docs.docker.com/build/building/multi-platform/)
* [Docker Hub overview](https://docs.docker.com/docker-hub/)

## [Next steps](#next-steps)

In the next section, you'll learn how to persist data in your containerized application.

[Persist the DB](https://docs.docker.com/get-started/workshop/05_persisting_data/)

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/hub-mcp/
----

# Docker Hub MCP server

***

Table of contents

***

The Docker Hub MCP Server is a Model Context Protocol (MCP) server that interfaces with Docker Hub APIs to make rich image metadata accessible to LLMs, enabling intelligent content discovery and repository management.

For more information about MCP concepts and how MCP servers work, see the [Docker MCP Catalog and Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/) overview page.

## [Key features](#key-features)

* Advanced LLM context: Docker's MCP Server provides LLMs with detailed, structured context for Docker Hub images, enabling smarter, more relevant recommendations for developers, whether they're choosing a base image or automating CI/CD workflows.
* Natural language image discovery: Developers can find the right container image using natural language, no need to remember tags or repository names. Just describe what you need, and Docker Hub will return images that match your intent.
* Simplified repository management: Hub MCP Server enables agents to manage repositories through natural language fetching image details, viewing stats, searching content, and performing key operations quickly and easily.

## [Install Docker Hub MCP server](#install-docker-hub-mcp-server)

1. From the **MCP Toolkit** menu, select the **Catalog** tab and search for **Docker Hub** and select the plus icon to add the Docker Hub MCP server.

2. In the server's **Configuration** tab, insert your Docker Hub username and personal access token (PAT).

3. In the **Clients** tab in MCP Toolkit, ensure Gordon is connected.

4. From the **Gordon** menu, you can now send requests related to your Docker Hub account, in accordance to the tools provided by the Docker Hub MCP server. To test it, ask Gordon:

   ```text
   What repositories are in my namespace?
   ```

> Tip
>
> By default, the Gordon [client](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/#install-an-mcp-client) is enabled, which means Gordon can automatically interact with your MCP servers.

## [Use Claude Desktop as a client](#use-claude-desktop-as-a-client)

1. Add the Docker Hub MCP Server configuration to your `claude_desktop_config.json`:

   ```json
   {
     "mcpServers": {
       "docker-hub": {
         "command": "node",
         "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"]
       }
     }
   }
   ```

   Where :

   * `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository

   ```json
   {
     "mcpServers": {
       "docker-hub": {
         "command": "node",
         "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio", "--username=YOUR_DOCKER_HUB_USERNAME"],
         "env": {
           "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN"
         }
       }
     }
   }
   ```

   Where :

   * `YOUR_DOCKER_HUB_USERNAME` is your Docker Hub username.
   * `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` is Docker Hub personal access token
   * `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository

2. Save the configuration file and completely restart Claude Desktop for the changes to take effect.

## [Usage with Visual Studio Code](#usage-with-visual-studio-code)

1. Add the Docker Hub MCP Server configuration to your User Settings (JSON) file in Visual Studio Code. You can do this by opening the `Command Palette` and typing `Preferences: Open User Settings (JSON)`.

   ```json
   {
     "mcpServers": {
       "docker-hub": {
         "command": "node",
         "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"]
       }
     }
   }
   ```

   Where :

   * `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository

   ```json
   {
     "mcpServers": {
       "docker-hub": {
         "command": "node",
         "args": ["/FULL/PATH/TO/YOUR/docker-hub-mcp-server/dist/index.js", "--transport=stdio"],
         "env": {
           "HUB_USERNAME": "YOUR_DOCKER_HUB_USERNAME",
           "HUB_PAT_TOKEN": "YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN"
         }
       }
     }
   }
   ```

   Where :

   * `YOUR_DOCKER_HUB_USERNAME` is your Docker Hub username.
   * `YOUR_DOCKER_HUB_PERSONAL_ACCESS_TOKEN` is Docker Hub personal access token
   * `/FULL/PATH/TO/YOUR/docker-hub-mcp-server` is the complete path to where you cloned the repository

2. Open the `Command Palette` and type `MCP: List Servers`.

3. Select `docker-hub` and select `Start Server`.

## [Using other clients](#using-other-clients)

To integrate the Docker Hub MCP Server into your own development environment, see the source code and installation instructions on the [`hub-mcp` GitHub repository](https://github.com/docker/hub-mcp).

## [Usage examples](#usage-examples)

This section provides task-oriented examples for common operations with Docker Hub tools.

### [Finding images](#finding-images)

```console
# Search for official images
$ docker ai "Search for official nginx images on Docker Hub"

# Search for lightweight images to reduce deployment size and improve performance
$ docker ai "Search for minimal Node.js images with small footprint"

# Get the most recent tag of a base image
$ docker ai "Show me the latest tag details for go"

# Find a production-ready database with enterprise features and reliability
$ docker ai "Search for production ready database images"

# Compare Ubuntu versions to choose the right one for my project
$ docker ai "Help me find the right Ubuntu version for my project"
```

### [Repository management](#repository-management)

```console
# Create a repository
$ docker ai "Create a repository in my namespace"

# List all repositories in my namespace
$ docker ai "List all repositories in my namespace"

# Find the largest repository in my namespace
$ docker ai "Which of my repositories takes up the most space?"

# Find repositories that haven't been updated recently
$ docker ai "Which of my repositories haven't had any pushes in the last 60 days?"

# Find which repositories are currently active and being used
$ docker ai "Show me my most recently updated repositories"

# Get details about a repository
$ docker ai "Show me information about my '<repository-name>' repository"
```

### [Pull/push images](#pullpush-images)

```console
# Pull latest PostgreSQL version
$ docker ai "Pull the latest postgres image"

# Push image to your Docker Hub repository
$ docker ai "Push my <image-name> to my <repository-name> repository"
```

### [Tag management](#tag-management)

```console
# List all tags for a repository
$ $ docker ai "Show me all tags for my '<repository-name>' repository"

# Find the most recently pushed tag
$ docker ai "What's the most recent tag pushed to my '<repository-name>' repository?"

# List tags with architecture filtering
$ docker ai "List tags for in the '<repository-name>' repository that support amd64 architecture"

# Get detailed information about a specific tag
$ docker ai "Show me details about the '<tag-name>' tag in the '<repository-name>' repository"

# Check if a specific tag exists
$ docker ai "Check if version 'v1.2.0' exists for my 'my-web-app' repository"
```

### [Docker Hardened Images](#docker-hardened-images)

```console
# List available hardened images
$ docker ai "What is the most secure image I can use to run a node.js application?"

# Convert Dockerfile to use a hardened image
$ docker ai "Can you help me update my Dockerfile to use a docker hardened image instead of the current one"
```

> Note
>
> To access Docker Hardened Images, a subscription is required. If you're interested in using Docker Hardened Images, visit [Docker Hardened Images](https://www.docker.com/products/hardened-images/).

## [Reference](#reference)

This section provides a comprehensive listing of the tools you can find in the Docker Hub MCP Server.

### [Docker Hub MCP server tools](#docker-hub-mcp-server-tools)

Tools to interact with your Docker repositories and discover content on Docker Hub.

| Name                             | Description                                                                                                       |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `check-repository`               | Check repository                                                                                                  |
| `check-repository-tag`           | Check repository tag                                                                                              |
| `check-repository-tags`          | Check repository tags                                                                                             |
| `create-repository`              | Creates a new repository                                                                                          |
| `docker-hardened-images`         | Lists available [Docker Hardened Images](https://www.docker.com/products/hardened-images/) in specified namespace |
| `get-namespaces`                 | Get organizations/namespaces for a user                                                                           |
| `get-repository-dockerfile`      | Gets Dockerfile for repository                                                                                    |
| `get-repository-info`            | Gets repository info                                                                                              |
| `list-repositories-by-namespace` | Lists repositories under namespace                                                                                |
| `list-repository-tags`           | List repository tags                                                                                              |
| `read-repository-tag`            | Read repository tag                                                                                               |
| `search`                         | Search content on Docker Hub                                                                                      |
| `set-repository-dockerfile`      | Sets Dockerfile for repository                                                                                    |
| `update-repository-info`         | Updates repository info                                                                                           |

----
url: https://docs.docker.com/build/ci/github-actions/share-image-jobs/
----

# Share built image between jobs with GitHub Actions

***

***

As each job is isolated in its own runner, you can't use your built image between jobs, except if you're using [self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners) or [Docker Build Cloud](/build-cloud). However, you can [pass data between jobs](https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts#passing-data-between-jobs-in-a-workflow) in a workflow using the [actions/upload-artifact](https://github.com/actions/upload-artifact) and [actions/download-artifact](https://github.com/actions/download-artifact) actions:

```yaml
name: ci

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and export
        uses: docker/build-push-action@v7
        with:
          tags: myimage:latest
          outputs: type=docker,dest=${{ runner.temp }}/myimage.tar

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: myimage
          path: ${{ runner.temp }}/myimage.tar

  use:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: myimage
          path: ${{ runner.temp }}

      - name: Load image
        run: |
          docker load --input ${{ runner.temp }}/myimage.tar
          docker image ls -a
```

----
url: https://docs.docker.com/get-started/workshop/10_what_next/
----

# What next after the Docker workshop

***

***

Congratulations on completing the Docker workshop. You've learned how to containerize applications, work with multi-container setups, use Docker Compose, and apply image-building best practices.

Here's what to explore next.

## [Secure your images](#secure-your-images)

Take your image-building skills to the next level with Docker Hardened Images—secure, minimal, and production-ready base images that are now free for everyone.

### [What are Docker Hardened Images?](/dhi/explore/what/)

[Understand secure, minimal, production-ready base images with near-zero CVEs.](/dhi/explore/what/)

### [Get started with DHI](/dhi/get-started/)

[Pull and run your first Docker Hardened Image in minutes.](/dhi/get-started/)

### [Use hardened images](/dhi/how-to/use/)

[Learn how to use DHI in your Dockerfiles and CI/CD pipelines.](/dhi/how-to/use/)

### [Explore the DHI catalog](/dhi/how-to/explore/)

[Browse available hardened images, variants, and security attestations.](/dhi/how-to/explore/)

## [Build with AI](#build-with-ai)

Docker makes it easy to run AI models locally and build agentic AI applications. Explore Docker's AI tools and start building AI-powered apps.

### [Docker Model Runner](/ai/model-runner/)

[Run and manage AI models locally using familiar Docker commands with OpenAI-compatible APIs.](/ai/model-runner/)

### [MCP Toolkit](/ai/mcp-catalog-and-toolkit/toolkit/)

[Set up, manage, and run containerized MCP servers to power your AI agents.](/ai/mcp-catalog-and-toolkit/toolkit/)

### [Build AI agents with Docker Agent](/ai/docker-agent/)

[Create teams of specialized AI agents that collaborate to solve complex problems.](/ai/docker-agent/)

### [Use AI models in Compose](/ai/compose/models-and-compose/)

[Define AI model dependencies in your Docker Compose applications.](/ai/compose/models-and-compose/)

## [Language-specific guides](#language-specific-guides)

Apply what you've learned to your preferred programming language with hands-on tutorials.

### [Node.js](/guides/language/nodejs/)

[Learn how to containerize and develop Node.js applications.](/guides/language/nodejs/)

### [Python](/guides/language/python/)

[Build and run Python applications in containers.](/guides/language/python/)

### [Java](/guides/language/java/)

[Containerize Java applications with best practices.](/guides/language/java/)

### [Go](/guides/language/golang/)

[Develop and deploy Go applications using Docker.](/guides/language/golang/)

----
url: https://docs.docker.com/scout/policy/view/
----

# View Docker Scout policy status

***

Table of contents

***

You can track policy status for your artifacts from the [Docker Scout Dashboard](#dashboard), or using the [CLI](#cli).

## [Dashboard](#dashboard)

The **Overview** tab of the [Docker Scout Dashboard](https://scout.docker.com/) displays a summary of recent changes in policy for your repositories. This summary shows images that have seen the most change in their policy evaluation between the most recent image and the previous image.

### [Policy status per repository](#policy-status-per-repository)

The **Images** tab shows the current policy status, and recent policy trend, for all images in the selected environment. The **Policy status** column in the list shows:

* Number of fulfilled policies versus the total number of policies
* Recent policy trends

The policy trend, denoted by the directional arrows, indicates whether an image is better, worse, or unchanged in terms of policy, compared to the previous image in the same environment.

* The green arrow pointing upwards shows the number of policies that got better in the latest pushed image.
* The red arrow pointing downwards shows the number of policies that got worse in the latest pushed image.
* The bidirectional gray arrow shows the number of policies that were unchanged in the latest version of this image.

If you select a repository, you can open the **Policy** tab for a detailed description of the policy delta for the most recently analyzed image and its predecessor.

### [Detailed results and remediation](#detailed-results-and-remediation)

To view the full evaluation results for an image, navigate to the image tag in the Docker Scout Dashboard and open the **Policy** tab. This shows a breakdown for all policy violations for the current image.

This view also provides recommendations on how to improve improve policy status for violated policies.

For vulnerability-related policies, the policy details view displays the fix version that removes the vulnerability, when a fix version is available. To fix the issue, upgrade the package version to the fix version.

For licensing-related policies, the list shows all packages whose license doesn't meet the policy criteria. To fix the issue, find a way to remove the dependency to the violating package, for example by looking for an alternative package distributed under a more appropriate license.

## [CLI](#cli)

To view policy status for an image from the CLI, use the `docker scout policy` command.

```console
$ docker scout policy \
  --org dockerscoutpolicy \
  --platform linux/amd64 \
  dockerscoutpolicy/email-api-service:0.0.2

    ✓ Pulled
    ✓ Policy evaluation results found


​## Overview
​
​             │               Analyzed Image
​─────────────┼──────────────────────────────────────────────
​  Target     │  dockerscoutpolicy/email-api-service:0.0.2
​    digest   │  17b1fde0329c
​    platform │ linux/amd64
​
​
​## Policies
​
​Policy status  FAILED  (2/8 policies met, 3 missing data)
​
​  Status │                  Policy                             │           Results
​─────────┼─────────────────────────────────────────────────────┼──────────────────────────────
​  ✓      │ No copyleft licenses                                │    0 packages
​  !      │ Default non-root user                               │
​  !      │ No fixable critical or high vulnerabilities         │    2C     1H     0M     0L
​  ✓      │ No high-profile vulnerabilities                     │    0C     0H     0M     0L
​  ?      │ No outdated base images                             │    No data
​         │                                                     │    Learn more ↗
​  ?      │ SonarQube quality gates passed                      │    No data
​         │                                                     │    Learn more ↗
​  !      │ Supply chain attestations                           │    2 deviations
​  ?      │ No unapproved base images                           │    No data

...
```

For more information about the command, refer to the [CLI reference](/reference/cli/docker/scout/policy/).

----
url: https://docs.docker.com/guides/testcontainers-java-micronaut-kafka/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

```console
$ ./mvnw test
```

Or with Gradle:

```console
$ ./gradlew test
```

You should see the Kafka and MySQL Docker containers start and all tests pass. After the tests finish, the containers stop and are removed automatically.

## [Summary](#summary)

Testing with real Kafka and MySQL instances gives you more confidence in the correctness of your code than mocks or embedded alternatives. The Testcontainers library manages the container lifecycle so that your integration tests run against the same services you use in production.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Testing REST API integrations in Micronaut apps using WireMock](/guides/testcontainers-java-micronaut-wiremock/)
* [Testing Spring Boot Kafka Listener using Testcontainers](/guides/testcontainers-java-spring-boot-kafka/)
* [Getting started with Testcontainers in a Java Spring Boot project](https://testcontainers.com/guides/testing-spring-boot-rest-api-using-testcontainers/)
* [Awaitility](http://www.awaitility.org/)
* [Testcontainers Kafka module](https://java.testcontainers.org/modules/kafka/)
* [Testcontainers MySQL module](https://java.testcontainers.org/modules/databases/mysql/)

----
url: https://docs.docker.com/ai/gordon/concepts/data-privacy/
----

# Data privacy and Gordon

***

Table of contents

***

Requires: Docker Desktop [4.74.0](https://docs.docker.com/desktop/release-notes/#4740) or later

This page explains what data Gordon accesses, how it's used, and what privacy protections are in place.

## [What data Gordon accesses](#what-data-gordon-accesses)

When you use Gordon, the data it accesses depends on your query and configuration.

### [Local files](#local-files)

When you use the `docker ai` command, Gordon can access files and directories on your system. The working directory sets the default context for file operations.

In Docker Desktop, if you ask about a specific file or directory in the Gordon view, you'll be prompted to select the relevant context.

### [Local images](#local-images)

Gordon integrates with Docker Desktop and can view all images in your local image store. This includes images you've built or pulled from a registry.

### [Docker environment](#docker-environment)

Gordon has access to your Docker daemon's state, including:

* Running and stopped containers
* Container logs and configuration
* Images and image layers
* Volumes and networks
* Build cache

## [Data retention policy](#data-retention-policy)

Gordon's data retention differs based on your subscription tier:

### [Paid subscriptions (Pro, Team, Business)](#paid-subscriptions-pro-team-business)

Docker and its AI providers do not retain any inputs or outputs from your Gordon sessions. Your queries, Gordon's responses, and any code or files processed are not stored.

### [Personal (free) subscription](#personal-free-subscription)

Anonymized conversation threads are stored for 30 days to improve the service. Individual queries and responses are retained as part of your conversation history.

### [All subscriptions](#all-subscriptions)

Data is never used for training AI models or shared with third parties. All data transferred to Gordon's backend is encrypted in transit.

## [Data security](#data-security)

Your data is protected through encryption in transit. For paid subscriptions, no persistent storage occurs—Gordon processes your requests and discards the data immediately.

For questions about privacy terms and conditions, review [Gordon's Supplemental Terms](https://www.docker.com/legal/docker-ai-supplemental-terms/).

## [Organizational data policies](#organizational-data-policies)

For Business subscriptions, administrators can enable or disable Gordon for their organization using Settings Management. Review your organization's data handling requirements before enabling Gordon.

See [Settings Management](/enterprise/security/hardened-desktop/settings-management/) for configuration details.

## [Disabling Gordon](#disabling-gordon)

You can disable Gordon at any time:

Individual users:

1. Open Docker Desktop Settings.
2. Navigate to the **AI** section.
3. Clear the **Enable Gordon** option.
4. Select **Apply**.

Business organizations:

Administrators can disable Gordon for the entire organization using Settings Management. See [Settings Management](/enterprise/security/hardened-desktop/settings-management/) for details.

## [Questions about privacy](#questions-about-privacy)

For questions about Docker's privacy practices:

* Review the [Docker Privacy Policy](https://www.docker.com/legal/privacy/)
* Read [Gordon's Supplemental Terms](https://www.docker.com/legal/docker-ai-supplemental-terms/)
* Contact Docker Support for specific concerns

----
url: https://docs.docker.com/build/builders/drivers/
----

# Build drivers

***

Table of contents

***

Build drivers are configurations for how and where the BuildKit backend runs. Driver settings are customizable and allow fine-grained control of the builder. Buildx supports the following drivers:

* `docker`: uses the BuildKit library bundled into the Docker daemon.
* `docker-container`: creates a dedicated BuildKit container using Docker.
* `kubernetes`: creates BuildKit pods in a Kubernetes cluster.
* `remote`: connects directly to a manually managed BuildKit daemon.

Different drivers support different use cases. The default `docker` driver prioritizes simplicity and ease of use. It has limited support for advanced features like caching and output formats, and isn't configurable. Other drivers provide more flexibility and are better at handling advanced scenarios.

The following table outlines some differences between drivers.

| Feature                      | `docker` | `docker-container` | `kubernetes` | `remote`           |
| ---------------------------- | -------- | ------------------ | ------------ | ------------------ |
| **Automatically load image** | ✅        |                    |              |                    |
| **Cache export**             | ✅\*      | ✅                  | ✅            | ✅                  |
| **Tarball output**           |          | ✅                  | ✅            | ✅                  |
| **Multi-arch images**        |          | ✅                  | ✅            | ✅                  |
| **BuildKit configuration**   |          | ✅                  | ✅            | Managed externally |

\* *The `docker` driver doesn't support all cache export options. See [Cache storage backends](https://docs.docker.com/build/cache/backends/) for more information.*

## [Loading to local image store](#loading-to-local-image-store)

Unlike when using the default `docker` driver, images built using other drivers aren't automatically loaded into the local image store. If you don't specify an output, the build result is exported to the build cache only.

To build an image using a non-default driver and load it to the image store, use the `--load` flag with the build command:

```console
$ docker buildx build --load -t <image> --builder=container .
...
=> exporting to oci image format                                                                                                      7.7s
=> => exporting layers                                                                                                                4.9s
=> => exporting manifest sha256:4e4ca161fa338be2c303445411900ebbc5fc086153a0b846ac12996960b479d3                                      0.0s
=> => exporting config sha256:adf3eec768a14b6e183a1010cb96d91155a82fd722a1091440c88f3747f1f53f                                        0.0s
=> => sending tarball                                                                                                                 2.8s
=> importing to docker
```

With this option, the image is available in the image store after the build finishes:

```console
$ docker image ls
REPOSITORY                       TAG               IMAGE ID       CREATED             SIZE
<image>                          latest            adf3eec768a1   2 minutes ago       197MB
```

### [Load by default](#load-by-default)

Requires: Docker Buildx [0.14.0](https://github.com/docker/buildx/releases/tag/v0.14.0) and later

You can configure the custom build drivers to behave in a similar way to the default `docker` driver, and load images to the local image store by default. To do so, set the `default-load` driver option when creating the builder:

```console
$ docker buildx create --driver-opt default-load=true
```

Note that, just like with the `docker` driver, if you specify a different output format with `--output`, the result will not be loaded to the image store unless you also explicitly specify `--output type=docker` or use the `--load` flag.

## [What's next](#whats-next)

Read about each driver:

* [Docker driver](https://docs.docker.com/build/builders/drivers/docker/)
* [Docker container driver](https://docs.docker.com/build/builders/drivers/docker-container/)
* [Kubernetes driver](https://docs.docker.com/build/builders/drivers/kubernetes/)
* [Remote driver](https://docs.docker.com/build/builders/drivers/remote/)

----
url: https://docs.docker.com/reference/cli/docker/plugin/install/
----

# docker plugin install

***

| Description | Install a plugin                                        |
| ----------- | ------------------------------------------------------- |
| Usage       | `docker plugin install [OPTIONS] PLUGIN [KEY=VALUE...]` |

## [Description](#description)

Installs and enables a plugin. Docker looks first for the plugin on your Docker host. If the plugin does not exist locally, then the plugin is pulled from the registry. Note that the minimum required registry version to distribute plugins is 2.3.0.

## [Options](#options)

| Option                    | Default | Description                                       |
| ------------------------- | ------- | ------------------------------------------------- |
| `--alias`                 |         | Local name for plugin                             |
| `--disable`               |         | Do not enable the plugin on install               |
| `--grant-all-permissions` |         | Grant all permissions necessary to run the plugin |

## [Examples](#examples)

The following example installs `vieus/sshfs` plugin and [sets](/reference/cli/docker/plugin/set/) its `DEBUG` environment variable to `1`. To install, `pull` the plugin from Docker Hub and prompt the user to accept the list of privileges that the plugin needs, set the plugin's parameters and enable the plugin.

```console
$ docker plugin install vieux/sshfs DEBUG=1

Plugin "vieux/sshfs" is requesting the following privileges:
 - network: [host]
 - device: [/dev/fuse]
 - capabilities: [CAP_SYS_ADMIN]
Do you grant the above permissions? [y/N] y
vieux/sshfs
```

After the plugin is installed, it appears in the list of plugins:

```console
$ docker plugin ls

ID             NAME                  DESCRIPTION                ENABLED
69553ca1d123   vieux/sshfs:latest    sshFS plugin for Docker    true
```

----
url: https://docs.docker.com/engine/cli/proxy/
----

# Use a proxy server with the Docker CLI

***

Table of contents

***

This page describes how to configure the Docker CLI to use proxies via environment variables in containers.

This page doesn't describe how to configure proxies for Docker Desktop. For instructions, see [configuring Docker Desktop to use HTTP/HTTPS proxies](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies).

If you're running Docker Engine without Docker Desktop, refer to [Configure the Docker daemon to use a proxy](https://docs.docker.com/engine/daemon/proxy/) to learn how to configure a proxy server for the Docker daemon (`dockerd`) itself.

If your container needs to use an HTTP, HTTPS, or FTP proxy server, you can configure it in different ways:

* [Configure the Docker client](#configure-the-docker-client)
* [Set proxy using the CLI](#set-proxy-using-the-cli)

> Note
>
> Unfortunately, there's no standard that defines how web clients should handle proxy environment variables, or the format for defining them.
>
> If you're interested in the history of these variables, check out this blog post on the subject, by the GitLab team: [We need to talk: Can we standardize NO\_PROXY?](https://about.gitlab.com/blog/2021/01/27/we-need-to-talk-no-proxy/).

## [Configure the Docker client](#configure-the-docker-client)

You can add proxy configurations for the Docker client using a JSON configuration file, located in `~/.docker/config.json`. Builds and containers use the configuration specified in this file.

```json
{
 "proxies": {
   "default": {
     "httpProxy": "http://proxy.example.com:3128",
     "httpsProxy": "https://proxy.example.com:3129",
     "noProxy": "*.test.example.com,.example.org,127.0.0.0/8"
   }
 }
}
```

> Warning
>
> Proxy settings may contain sensitive information. For example, some proxy servers require authentication information to be included in their URL, or their address may expose IP-addresses or hostnames of your company's environment.
>
> Environment variables are stored as plain text in the container's configuration, and as such can be inspected through the remote API or committed to an image when using `docker commit`.

The configuration becomes active after saving the file, you don't need to restart Docker. However, the configuration only applies to new containers and builds, and doesn't affect existing containers.

The following table describes the available configuration parameters.

| Property     | Description                                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| `httpProxy`  | Sets the `HTTP_PROXY` and `http_proxy` environment variables and build arguments.   |
| `httpsProxy` | Sets the `HTTPS_PROXY` and `https_proxy` environment variables and build arguments. |
| `ftpProxy`   | Sets the `FTP_PROXY` and `ftp_proxy` environment variables and build arguments.     |
| `noProxy`    | Sets the `NO_PROXY` and `no_proxy` environment variables and build arguments.       |
| `allProxy`   | Sets the `ALL_PROXY` and `all_proxy` environment variables and build arguments.     |

These settings are used to configure proxy environment variables for containers only, and not used as proxy settings for the Docker CLI or the Docker Engine itself. Refer to the [environment variables](/reference/cli/docker/#environment-variables) and [configure the Docker daemon to use a proxy server](https://docs.docker.com/engine/daemon/proxy/) sections for configuring proxy settings for the CLI and daemon.

### [Run containers with a proxy configuration](#run-containers-with-a-proxy-configuration)

When you start a container, its proxy-related environment variables are set to reflect your proxy configuration in `~/.docker/config.json`.

For example, assuming a proxy configuration like the example shown in the [earlier section](#configure-the-docker-client), environment variables for containers that you run are set as follows:

```console
$ docker run --rm alpine sh -c 'env | grep -i  _PROXY'
https_proxy=http://proxy.example.com:3129
HTTPS_PROXY=http://proxy.example.com:3129
http_proxy=http://proxy.example.com:3128
HTTP_PROXY=http://proxy.example.com:3128
no_proxy=*.test.example.com,.example.org,127.0.0.0/8
NO_PROXY=*.test.example.com,.example.org,127.0.0.0/8
```

### [Build with a proxy configuration](#build-with-a-proxy-configuration)

When you invoke a build, proxy-related build arguments are pre-populated automatically, based on the proxy settings in your Docker client configuration file.

Assuming a proxy configuration like the example shown in the [earlier section](#configure-the-docker-client), environment are set as follows during builds:

```console
$ docker build \
  --no-cache \
  --progress=plain \
  - <<EOF
FROM alpine
RUN env | grep -i _PROXY
EOF
```

```console
#5 [2/2] RUN env | grep -i _PROXY
#5 0.100 HTTPS_PROXY=https://proxy.example.com:3129
#5 0.100 no_proxy=*.test.example.com,.example.org,127.0.0.0/8
#5 0.100 NO_PROXY=*.test.example.com,.example.org,127.0.0.0/8
#5 0.100 https_proxy=https://proxy.example.com:3129
#5 0.100 http_proxy=http://proxy.example.com:3128
#5 0.100 HTTP_PROXY=http://proxy.example.com:3128
#5 DONE 0.1s
```

### [Configure proxy settings per daemon](#configure-proxy-settings-per-daemon)

The `default` key under `proxies` in `~/.docker/config.json` configures the proxy settings for all daemons that the client connects to. To configure the proxies for individual daemons, use the address of the daemon instead of the `default` key.

The following example configures both a default proxy config, and a no-proxy override for the Docker daemon on address `tcp://docker-daemon1.example.com`:

```json
{
 "proxies": {
   "default": {
     "httpProxy": "http://proxy.example.com:3128",
     "httpsProxy": "https://proxy.example.com:3129",
     "noProxy": "*.test.example.com,.example.org,127.0.0.0/8"
   },
   "tcp://docker-daemon1.example.com": {
     "noProxy": "*.internal.example.net"
   }
 }
}
```

## [Set proxy using the CLI](#set-proxy-using-the-cli)

Instead of [configuring the Docker client](#configure-the-docker-client), you can specify proxy configurations on the command-line when you invoke the `docker build` and `docker run` commands.

Proxy configuration on the command-line uses the `--build-arg` flag for builds, and the `--env` flag for when you want to run containers with a proxy.

```console
$ docker build --build-arg HTTP_PROXY="http://proxy.example.com:3128" .
$ docker run --env HTTP_PROXY="http://proxy.example.com:3128" redis
```

For a list of all the proxy-related build arguments that you can use with the `docker build` command, see [Predefined ARGs](https://docs.docker.com/reference/dockerfile/#predefined-args). These proxy values are only available in the build container. They're not included in the build output.

## [Proxy as environment variable for builds](#proxy-as-environment-variable-for-builds)

Don't use the `ENV` Dockerfile instruction to specify proxy settings for builds. Use build arguments instead.

Using environment variables for proxies embeds the configuration into the image. If the proxy is an internal proxy, it might not be accessible for containers created from that image.

Embedding proxy settings in images also poses a security risk, as the values may include sensitive information.

----
url: https://docs.docker.com/engine/storage/tmpfs/
----

# tmpfs mounts

***

Table of contents

***

[Volumes](https://docs.docker.com/engine/storage/volumes/) and [bind mounts](https://docs.docker.com/engine/storage/bind-mounts/) let you share files between the host machine and container so that you can persist data even after the container is stopped.

If you're running Docker on Linux, you have a third option: tmpfs mounts. When you create a container with a tmpfs mount, the container can create files outside the container's writable layer.

As opposed to volumes and bind mounts, a tmpfs mount is temporary, and only persisted in the host memory. When the container stops, the tmpfs mount is removed, and files written there won't be persisted.

tmpfs mounts are best used for cases when you do not want the data to persist either on the host machine or within the container. This may be for security reasons or to protect the performance of the container when your application needs to write a large volume of non-persistent state data.

> Important
>
> tmpfs mounts in Docker map directly to [tmpfs](https://en.wikipedia.org/wiki/Tmpfs) in the Linux kernel. As such, the temporary data may be written to a swap file, and thereby persisted to the filesystem.

## [Mounting over existing data](#mounting-over-existing-data)

If you create a tmpfs mount into a directory in the container in which files or directories exist, the pre-existing files are obscured by the mount. This is similar to if you were to save files into `/mnt` on a Linux host, and then mounted a USB drive into `/mnt`. The contents of `/mnt` would be obscured by the contents of the USB drive until the USB drive was unmounted.

With containers, there's no straightforward way of removing a mount to reveal the obscured files again. Your best option is to recreate the container without the mount.

## [Limitations of tmpfs mounts](#limitations-of-tmpfs-mounts)

* Unlike volumes and bind mounts, you can't share tmpfs mounts between containers.
* This functionality is only available if you're running Docker on Linux.
* Setting permissions on tmpfs may cause them to [reset after container restart](https://github.com/docker/for-linux/issues/138). In some cases [setting the uid/gid](https://github.com/docker/compose/issues/3425#issuecomment-423091370) can serve as a workaround.

## [Syntax](#syntax)

To mount a tmpfs with the `docker run` command, you can use either the `--mount` or `--tmpfs` flag.

```console
$ docker run --mount type=tmpfs,dst=<mount-path>
$ docker run --tmpfs <mount-path>
```

In general, `--mount` is preferred. The main difference is that the `--mount` flag is more explicit. On the other hand, `--tmpfs` is less verbose and gives you more flexibility as it lets you set more mount options.

The `--tmpfs` flag cannot be used with swarm services. You must use `--mount`.

### [Options for --tmpfs](#options-for---tmpfs)

The `--tmpfs` flag consists of two fields, separated by a colon character (`:`).

```console
$ docker run --tmpfs <mount-path>[:opts]
```

The first field is the container path to mount into a tmpfs. The second field is optional and lets you set mount options. Valid mount options for `--tmpfs` include:

| Option       | Description                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------- |
| `ro`         | Creates a read-only tmpfs mount.                                                            |
| `rw`         | Creates a read-write tmpfs mount (default behavior).                                        |
| `nosuid`     | Prevents `setuid` and `setgid` bits from being honored during execution.                    |
| `suid`       | Allows `setuid` and `setgid` bits to be honored during execution (default behavior).        |
| `nodev`      | Device files can be created but are not functional (access results in an error).            |
| `dev`        | Device files can be created and are fully functional.                                       |
| `exec`       | Allows the execution of executable binaries in the mounted file system.                     |
| `noexec`     | Does not allow the execution of executable binaries in the mounted file system.             |
| `sync`       | All I/O to the file system is done synchronously.                                           |
| `async`      | All I/O to the file system is done asynchronously (default behavior).                       |
| `dirsync`    | Directory updates within the file system are done synchronously.                            |
| `atime`      | Updates file access time each time the file is accessed.                                    |
| `noatime`    | Does not update file access times when the file is accessed.                                |
| `diratime`   | Updates directory access times each time the directory is accessed.                         |
| `nodiratime` | Does not update directory access times when the directory is accessed.                      |
| `size`       | Specifies the size of the tmpfs mount, for example, `size=64m`.                             |
| `mode`       | Specifies the file mode (permissions) for the tmpfs mount (for example, `mode=1777`).       |
| `uid`        | Specifies the user ID for the owner of the tmpfs mount (for example, `uid=1000`).           |
| `gid`        | Specifies the group ID for the owner of the tmpfs mount (for example, `gid=1000`).          |
| `nr_inodes`  | Specifies the maximum number of inodes for the tmpfs mount (for example, `nr_inodes=400k`). |
| `nr_blocks`  | Specifies the maximum number of blocks for the tmpfs mount (for example, `nr_blocks=1024`). |

Example

```console
$ docker run --tmpfs /data:noexec,size=1024,mode=1777
```

Not all tmpfs mount features available in the Linux mount command are supported with the `--tmpfs` flag. If you require advanced tmpfs options or features, you may need to use a privileged container or configure the mount outside of Docker.

> Caution
>
> Running containers with `--privileged` grants elevated permissions and can expose the host system to security risks. Use this option only when absolutely necessary and in trusted environments.

```console
$ docker run --privileged -it debian sh
/# mount -t tmpfs -o <options> tmpfs /data
```

### [Options for --mount](#options-for---mount)

The `--mount` flag consists of multiple key-value pairs, separated by commas and each consisting of a `<key>=<value>` tuple. The order of the keys isn't significant.

```console
$ docker run --mount type=tmpfs,dst=<mount-path>[,<key>=<value>...]
```

Valid options for `--mount type=tmpfs` include:

| Option                         | Description                                                                                                            |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `destination`, `dst`, `target` | Container path to mount into a tmpfs.                                                                                  |
| `tmpfs-size`                   | Size of the tmpfs mount in bytes. If unset, the default maximum size of a tmpfs volume is 50% of the host's total RAM. |
| `tmpfs-mode`                   | File mode of the tmpfs in octal. For instance, `700` or `0770`. Defaults to `1777` or world-writable.                  |

Example

```console
$ docker run --mount type=tmpfs,dst=/app,tmpfs-size=21474836480,tmpfs-mode=1770
```

## [Use a tmpfs mount in a container](#use-a-tmpfs-mount-in-a-container)

To use a `tmpfs` mount in a container, use the `--tmpfs` flag, or use the `--mount` flag with `type=tmpfs` and `destination` options. There is no `source` for `tmpfs` mounts. The following example creates a `tmpfs` mount at `/app` in a Nginx container. The first example uses the `--mount` flag and the second uses the `--tmpfs` flag.

```console
$ docker run -d \
  -it \
  --name tmptest \
  --mount type=tmpfs,destination=/app \
  nginx:latest
```

Verify that the mount is a `tmpfs` mount by looking in the `Mounts` section of the `docker inspect` output:

```console
$ docker inspect tmptest --format '{{ json .Mounts }}'
[{"Type":"tmpfs","Source":"","Destination":"/app","Mode":"","RW":true,"Propagation":""}]
```

```console
$ docker run -d \
  -it \
  --name tmptest \
  --tmpfs /app \
  nginx:latest
```

Verify that the mount is a `tmpfs` mount by looking in the `Mounts` section of the `docker inspect` output:

```console
$ docker inspect tmptest --format '{{ json .Mounts }}'
{"/app":""}
```

Stop and remove the container:

```console
$ docker stop tmptest
$ docker rm tmptest
```

## [Next steps](#next-steps)

* Learn about [volumes](https://docs.docker.com/engine/storage/volumes/)
* Learn about [bind mounts](https://docs.docker.com/engine/storage/bind-mounts/)
* Learn about [storage drivers](/engine/storage/drivers/)

----
url: https://docs.docker.com/ai/docker-agent/rag/
----

# RAG

***

Table of contents

***

When you configure a RAG source in Docker Agent, your agent automatically gains a search tool for that knowledge base. The agent decides when to search, retrieves only relevant information, and uses it to answer questions or complete tasks - all without you manually managing what goes in the prompt.

This guide explains how Docker Agent's RAG system works, when to use it, and how to configure it effectively for your content.

> Note
>
> RAG is an advanced feature that requires configuration and tuning. The defaults work well for getting started, but tailoring the configuration to your specific content and use case significantly improves results.

## [The problem: too much context](#the-problem-too-much-context)

Your agent can work with your entire codebase, but it can't fit everything in its context window. Even with 200K token limits, medium-sized projects are too large. Finding relevant code buried in hundreds of files wastes context.

Filesystem tools help agents read files, but the agent has to guess which files to read. It can't search by meaning, only by filename. Ask "find the retry logic" and the agent reads files hoping to stumble on the right code.

Grep finds exact text matches but misses related concepts. Searching "authentication" won't find code using "auth" or "login." You either get hundreds of matches or zero, and grep doesn't understand code structure - it just matches strings anywhere they appear.

RAG indexes your content ahead of time and enables semantic search. The agent searches pre-indexed content by meaning, not exact words. It retrieves only relevant chunks that respect code structure. No wasted context on exploration.

## [How RAG works in Docker Agent](#how-rag-works-in-docker-agent)

Configure a RAG source in your Docker Agent config:

```yaml
rag:
  codebase:
    docs: [./src, ./pkg]
    strategies:
      - type: chunked-embeddings
        embedding_model: openai/text-embedding-3-small
        vector_dimensions: 1536
        database: ./code.db

agents:
  root:
    model: openai/gpt-5
    instruction: You are a coding assistant. Search the codebase when needed.
    rag: [codebase]
```

When you reference `rag: [codebase]`, Docker Agent:

1. **At startup** - Indexes your documents (first run only, blocks until complete)
2. **During conversation** - Gives the agent a search tool
3. **When the agent searches** - Retrieves relevant chunks and adds them to context
4. **On file changes** - Automatically re-indexes modified files

The agent decides when to search based on the conversation. You don't manage what goes in context - the agent does.

### [The indexing process](#the-indexing-process)

On first run, Docker Agent:

* Reads files from configured paths
* Respects `.gitignore` patterns (can be disabled)
* Splits documents into chunks
* Creates searchable representations using your chosen strategy
* Stores everything in a local database

Subsequent runs reuse the index. If files change, Docker Agent detects this and re-indexes only what changed, keeping your knowledge base up to date without manual intervention.

## [Retrieval strategies](#retrieval-strategies)

Different content requires different retrieval approaches. Docker Agent supports three strategies, each optimized for different use cases. The defaults work well, but understanding the trade-offs helps you choose the right approach.

### [Semantic search (chunked-embeddings)](#semantic-search-chunked-embeddings)

Converts text to vectors that represent meaning, enabling search by concept rather than exact words:

```yaml
strategies:
  - type: chunked-embeddings
    embedding_model: openai/text-embedding-3-small
    vector_dimensions: 1536
    database: ./docs.db
    chunking:
      size: 1000
      overlap: 100
```

During indexing, documents are split into chunks and each chunk is converted to a 1536-dimensional vector by the embedding model. These vectors are essentially coordinates in a high-dimensional space where similar concepts are positioned close together.

When you search for "how do I authenticate users?", your query becomes a vector and the database finds chunks with nearby vectors using cosine similarity (measuring the angle between vectors). The embedding model learned that "authentication," "auth," and "login" are related concepts, so searching for one finds the others.

Example: The query "how do I authenticate users?" finds both "User authentication requires a valid API token" and "Token-based auth validates requests" despite different wording. It won't find "The authentication tests are failing" because that's a different meaning despite containing the word.

This works well for documentation where users ask questions using different terminology than your docs. The downside is it may miss exact technical terms and sometimes you want literal matches, not semantic ones. Requires embedding API calls during indexing.

### [Keyword search (BM25)](#keyword-search-bm25)

Statistical algorithm that matches and ranks by term frequency and rarity:

```yaml
strategies:
  - type: bm25
    database: ./bm25.db
    k1: 1.5
    b: 0.75
    chunking:
      size: 1000
      overlap: 100
```

During indexing, documents are tokenized and the algorithm calculates how often each term appears (term frequency) and how rare it is across all documents (inverse document frequency). The scoring index is stored in a local SQLite database.

When you search for "HandleRequest function", the algorithm finds chunks containing these exact terms and scores them based on term frequency, term rarity, and document length. Finding "HandleRequest" is scored as more significant than finding common words like "function". Think of it as grep with statistical ranking.

Example: Searching "HandleRequest function" finds `func HandleRequest(w http.ResponseWriter, r *http.Request)` and "The HandleRequest function processes incoming requests", but not "process HTTP requests" despite that being semantically similar.

The `k1` parameter (default 1.5) controls how much repeated terms matter - higher values emphasize repetition more. The `b` parameter (default 0.75) controls length normalization - higher values penalize longer documents more.

This is fast, local (no API costs), and predictable for finding function names, class names, API endpoints, and any identifier that appears verbatim. The trade-off is zero understanding of meaning - "RetryHandler" and "retry logic" won't match despite being related. Essential complement to semantic search.

### [LLM-enhanced semantic search (semantic-embeddings)](#llm-enhanced-semantic-search-semantic-embeddings)

Generates semantic summaries with an LLM before embedding, enabling search by what code does rather than what it's called:

```yaml
strategies:
  - type: semantic-embeddings
    embedding_model: openai/text-embedding-3-small
    chat_model: openai/gpt-5-mini
    vector_dimensions: 1536
    database: ./code.db
    ast_context: true
    chunking:
      size: 1000
      code_aware: true
```

During indexing, code is split using AST structure (functions stay intact), then the `chat_model` generates a semantic summary of each chunk. The summary gets embedded, not the raw code. When you search, your query matches against these summaries, but the original code is returned.

This solves a problem with regular embeddings: raw code embeddings are dominated by variable names and implementation details. A function called `processData` that implements retry logic won't semantically match "retry". But when the LLM summarizes it first, the summary explicitly mentions "retry logic," making it findable.

Example: Consider this code:

```go
func (c *Client) Do(req *Request) (*Response, error) {
    for i := 0; i < 3; i++ {
        resp, err := c.attempt(req)
        if err == nil { return resp, nil }
        time.Sleep(time.Duration(1<<i) * time.Second)
    }
    return nil, errors.New("max retries exceeded")
}
```

The LLM summary is: "Implements exponential backoff retry logic for HTTP requests, attempting up to 3 times with delays of 1s, 2s, 4s before failing."

Searching "retry logic exponential backoff" now finds this code, despite the code never using those words. The `ast_context: true` option includes AST metadata in prompts for better understanding. The `code_aware: true` chunking prevents splitting functions mid-implementation.

This approach excels at finding code by behavior in large codebases with inconsistent naming. The trade-off is significantly slower indexing (LLM call per chunk) and higher API costs (both chat and embedding models). Often overkill for well-documented code or simple projects.

## [Combining strategies with hybrid retrieval](#combining-strategies-with-hybrid-retrieval)

Each strategy has strengths and weaknesses. Combining them captures both semantic understanding and exact term matching:

```yaml
rag:
  knowledge:
    docs: [./documentation, ./src]
    strategies:
      - type: chunked-embeddings
        embedding_model: openai/text-embedding-3-small
        vector_dimensions: 1536
        database: ./vector.db
        limit: 20

      - type: bm25
        database: ./bm25.db
        limit: 15

    results:
      fusion:
        strategy: rrf
        k: 60
      deduplicate: true
      limit: 5
```

### [How fusion works](#how-fusion-works)

Both strategies run in parallel, each returning its top candidates (20 and 15 in this example). Fusion combines results using rank-based scoring, removes duplicates, and returns the top 5 final results. Your agent gets results that work for both semantic queries ("how do I...") and exact term searches ("find `configure_auth` function").

### [Fusion strategies](#fusion-strategies)

RRF (Reciprocal Rank Fusion) is recommended. It combines results based on rank rather than absolute scores, which works reliably when strategies use different scoring scales. No tuning required.

For weighted fusion, you give more importance to one strategy:

```yaml
fusion:
  strategy: weighted
  weights:
    chunked-embeddings: 0.7
    bm25: 0.3
```

This requires tuning for your content. Use it when you know one approach works better for your use case.

Max score fusion takes the highest score across strategies:

```yaml
fusion:
  strategy: max
```

This only works if strategies use comparable scoring scales. Simple but less sophisticated than RRF.

## [Improving retrieval quality](#improving-retrieval-quality)

### [Reranking results](#reranking-results)

Initial retrieval optimizes for speed. Reranking rescores results with a more sophisticated model for better relevance:

```yaml
results:
  reranking:
    model: openai/gpt-5-mini
    threshold: 0.3
    criteria: |
      When scoring relevance, prioritize:
      - Official documentation over community content
      - Recent information over outdated material
      - Practical examples over theoretical explanations
      - Code implementations over design discussions
  limit: 5
```

The `criteria` field is powerful - use it to encode domain knowledge about what makes results relevant for your specific use case. The more specific your criteria, the better the reranking.

Trade-off: Significantly better results but adds latency and API costs (LLM call for scoring each result).

### [Chunking configuration](#chunking-configuration)

How you split documents dramatically affects retrieval quality. Tailor chunking to your content type. Chunk size is measured in characters (Unicode code points), not tokens.

For documentation and prose, use moderate chunks with overlap:

```yaml
chunking:
  size: 1000
  overlap: 100
  respect_word_boundaries: true
```

Overlap preserves context at chunk boundaries. Respecting word boundaries prevents cutting words in half.

For code, use larger chunks with AST-based splitting:

```yaml
chunking:
  size: 2000
  code_aware: true
```

This keeps functions intact. The `code_aware` setting uses tree-sitter to respect code structure.

> Note
>
> Currently only Go is supported; support for additional languages is planned.

For short, focused content like API references:

```yaml
chunking:
  size: 500
  overlap: 50
```

Brief sections need less overlap since they're naturally self-contained.

Experiment with these values. If retrieval misses context, increase chunk size or overlap. If results are too broad, decrease chunk size.

## [Making decisions about RAG](#making-decisions-about-rag)

### [When to use RAG](#when-to-use-rag)

Use RAG when:

* Your content is too large for the context window
* You want targeted retrieval, not everything at once
* Content changes and needs to stay current
* Agent needs to search across many files

Don't use RAG when:

* Content is small enough to include in agent instructions
* Information rarely changes (consider prompt engineering instead)
* You need real-time data (RAG uses pre-indexed snapshots)
* Content is already in a searchable format the agent can query directly

### [Choosing retrieval strategies](#choosing-retrieval-strategies)

Use semantic search (chunked-embeddings) for user-facing documentation, content with varied terminology, and conceptual searches where users phrase questions differently than your docs.

Use keyword search (BM25) for code identifiers, function names, API endpoints, error messages, and any content where exact term matching matters. Essential for technical jargon and proper nouns.

Use LLM-enhanced semantic (semantic-embeddings) for code search by functionality, finding implementations by behavior rather than name, or complex technical content requiring deep understanding. Choose this when accuracy matters more than indexing speed.

Use hybrid (multiple strategies) for general-purpose search across mixed content, when you're unsure which approach works best, or for production systems where quality matters most. Maximum coverage at the cost of complexity.

### [Tuning for your project](#tuning-for-your-project)

Start with defaults, then adjust based on results.

If retrieval misses relevant content:

* Increase `limit` in strategies to retrieve more candidates
* Adjust `threshold` to be less strict
* Increase chunk `size` to capture more context
* Add more retrieval strategies

If retrieval returns irrelevant content:

* Decrease `limit` to fewer candidates
* Increase `threshold` to be more strict
* Add reranking with specific criteria
* Decrease chunk `size` for more focused results

If indexing is too slow:

* Increase `batch_size` for fewer API calls
* Increase `max_embedding_concurrency` for parallelism
* Consider BM25 instead of embeddings (local, no API)
* Use smaller embedding models

If results lack context:

* Increase chunk `overlap`
* Increase chunk `size`
* Use `return_full_content: true` to return entire documents
* Add neighboring chunks to results

## [Further reading](#further-reading)

* [Configuration reference](https://docs.docker.com/ai/docker-agent/reference/config/#rag) - Complete RAG options and parameters
* [RAG examples](https://github.com/docker/docker-agent/tree/main/examples/rag) - Working configurations for different scenarios
* [Tools reference](https://docs.docker.com/ai/docker-agent/reference/toolsets/) - How RAG search tools work in agent workflows

----
url: https://docs.docker.com/reference/samples/vuejs/
----

# Vue.js samples

| Name                                                                 | Description                  |
| -------------------------------------------------------------------- | ---------------------------- |
| [VueJS](https://github.com/docker/awesome-compose/tree/master/vuejs) | A sample Vue.js application. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/engine/security/
----

# Docker Engine security

***

Table of contents

***

There are four major areas to consider when reviewing Docker security:

* The intrinsic security of the kernel and its support for namespaces and cgroups
* The attack surface of the Docker daemon itself
* Loopholes in the container configuration profile, either by default, or when customized by users.
* The "hardening" security features of the kernel and how they interact with containers.

## [Kernel namespaces](#kernel-namespaces)

Docker containers are very similar to LXC containers, and they have similar security features. When you start a container with `docker run`, behind the scenes Docker creates a set of namespaces and control groups for the container.

Namespaces provide the first and most straightforward form of isolation. Processes running within a container cannot see, and even less affect, processes running in another container, or in the host system.

Each container also gets its own network stack, meaning that a container doesn't get privileged access to the sockets or interfaces of another container. Of course, if the host system is setup accordingly, containers can interact with each other through their respective network interfaces — just like they can interact with external hosts. When you specify public ports for your containers or use [links](https://docs.docker.com/engine/network/links/) then IP traffic is allowed between containers. They can ping each other, send/receive UDP packets, and establish TCP connections, but that can be restricted if necessary. From a network architecture point of view, all containers on a given Docker host are sitting on bridge interfaces. This means that they are just like physical machines connected through a common Ethernet switch; no more, no less.

How mature is the code providing kernel namespaces and private networking? Kernel namespaces were introduced [between kernel version 2.6.15 and 2.6.26](https://man7.org/linux/man-pages/man7/namespaces.7.html). This means that since July 2008 (date of the 2.6.26 release ), namespace code has been exercised and scrutinized on a large number of production systems. And there is more: the design and inspiration for the namespaces code are even older. Namespaces are actually an effort to reimplement the features of [OpenVZ](https://en.wikipedia.org/wiki/OpenVZ) in such a way that they could be merged within the mainstream kernel. And OpenVZ was initially released in 2005, so both the design and the implementation are pretty mature.

## [Control groups](#control-groups)

Control Groups are another key component of Linux containers. They implement resource accounting and limiting. They provide many useful metrics, but they also help ensure that each container gets its fair share of memory, CPU, disk I/O; and, more importantly, that a single container cannot bring the system down by exhausting one of those resources.

So while they do not play a role in preventing one container from accessing or affecting the data and processes of another container, they are essential to fend off some denial-of-service attacks. They are particularly important on multi-tenant platforms, like public and private PaaS, to guarantee a consistent uptime (and performance) even when some applications start to misbehave.

Control Groups have been around for a while as well: the code was started in 2006, and initially merged in kernel 2.6.24.

## [Docker daemon attack surface](#docker-daemon-attack-surface)

Running containers (and applications) with Docker implies running the Docker daemon. This daemon requires `root` privileges unless you opt-in to [Rootless mode](https://docs.docker.com/engine/security/rootless/), and you should therefore be aware of some important details.

First of all, only trusted users should be allowed to control your Docker daemon. This is a direct consequence of some powerful Docker features. Specifically, Docker allows you to share a directory between the Docker host and a guest container; and it allows you to do so without limiting the access rights of the container. This means that you can start a container where the `/host` directory is the `/` directory on your host; and the container can alter your host filesystem without any restriction. This is similar to how virtualization systems allow filesystem resource sharing. Nothing prevents you from sharing your root filesystem (or even your root block device) with a virtual machine.

This has a strong security implication: for example, if you instrument Docker from a web server to provision containers through an API, you should be even more careful than usual with parameter checking, to make sure that a malicious user cannot pass crafted parameters causing Docker to create arbitrary containers.

For this reason, the REST API endpoint (used by the Docker CLI to communicate with the Docker daemon) changed in Docker 0.5.2, and now uses a Unix socket instead of a TCP socket bound on 127.0.0.1 (the latter being prone to cross-site request forgery attacks if you happen to run Docker directly on your local machine, outside of a VM). You can then use traditional Unix permission checks to limit access to the control socket.

You can also expose the REST API over HTTP if you explicitly decide to do so. However, if you do that, be aware of the above mentioned security implications. Note that even if you have a firewall to limit accesses to the REST API endpoint from other hosts in the network, the endpoint can be still accessible from containers, and it can easily result in the privilege escalation. Therefore it is *mandatory* to secure API endpoints with [HTTPS and certificates](https://docs.docker.com/engine/security/protect-access/). Exposing the daemon API over HTTP without TLS is not permitted, and such a configuration causes the daemon to fail early on startup, see [Unauthenticated TCP connections](https://docs.docker.com/engine/deprecated/#unauthenticated-tcp-connections). It is also recommended to ensure that it is reachable only from a trusted network or VPN.

You can also use `DOCKER_HOST=ssh://USER@HOST` or `ssh -L /path/to/docker.sock:/var/run/docker.sock` instead if you prefer SSH over TLS.

The daemon is also potentially vulnerable to other inputs, such as image loading from either disk with `docker load`, or from the network with `docker pull`. As of Docker 1.3.2, images are now extracted in a chrooted subprocess on Linux/Unix platforms, being the first-step in a wider effort toward privilege separation. As of Docker 1.10.0, all images are stored and accessed by the cryptographic checksums of their contents, limiting the possibility of an attacker causing a collision with an existing image.

Finally, if you run Docker on a server, it is recommended to run exclusively Docker on the server, and move all other services within containers controlled by Docker. Of course, it is fine to keep your favorite admin tools (probably at least an SSH server), as well as existing monitoring/supervision processes, such as NRPE and collectd.

## [Linux kernel capabilities](#linux-kernel-capabilities)

By default, Docker starts containers with a restricted set of capabilities. What does that mean?

Capabilities turn the binary "root/non-root" dichotomy into a fine-grained access control system. Processes (like web servers) that just need to bind on a port below 1024 do not need to run as root: they can just be granted the `net_bind_service` capability instead. And there are many other capabilities, for almost all the specific areas where root privileges are usually needed. This means a lot for container security.

Typical servers run several processes as `root`, including the SSH daemon, `cron` daemon, logging daemons, kernel modules, network configuration tools, and more. A container is different, because almost all of those tasks are handled by the infrastructure around the container:

* SSH access are typically managed by a single server running on the Docker host
* `cron`, when necessary, should run as a user process, dedicated and tailored for the app that needs its scheduling service, rather than as a platform-wide facility
* Log management is also typically handed to Docker, or to third-party services like Loggly or Splunk
* Hardware management is irrelevant, meaning that you never need to run `udevd` or equivalent daemons within containers
* Network management happens outside of the containers, enforcing separation of concerns as much as possible, meaning that a container should never need to perform `ifconfig`, `route`, or ip commands (except when a container is specifically engineered to behave like a router or firewall, of course)

This means that in most cases, containers do not need "real" root privileges at all\* And therefore, containers can run with a reduced capability set; meaning that "root" within a container has much less privileges than the real "root". For instance, it is possible to:

* Deny all "mount" operations
* Deny access to raw sockets (to prevent packet spoofing)
* Deny access to some filesystem operations, like creating new device nodes, changing the owner of files, or altering attributes (including the immutable flag)
* Deny module loading

This means that even if an intruder manages to escalate to root within a container, it is much harder to do serious damage, or to escalate to the host.

This doesn't affect regular web apps, but reduces the vectors of attack by malicious users considerably. By default Docker drops all capabilities except [those needed](https://github.com/moby/moby/blob/master/daemon/pkg/oci/caps/defaults.go#L6-L19), an allowlist instead of a denylist approach. You can see a full list of available capabilities in [Linux manpages](https://man7.org/linux/man-pages/man7/capabilities.7.html).

One primary risk with running Docker containers is that the default set of capabilities and mounts given to a container may provide incomplete isolation, either independently, or when used in combination with kernel vulnerabilities.

Docker supports the addition and removal of capabilities, allowing use of a non-default profile. This may make Docker more secure through capability removal, or less secure through the addition of capabilities. The best practice for users would be to remove all capabilities except those explicitly required for their processes.

## [Docker Content Trust signature verification](#docker-content-trust-signature-verification)

Docker Engine can be configured to only run signed images. The Docker Content Trust signature verification feature is built directly into the `dockerd` binary.\
This is configured in the Dockerd configuration file.

To enable this feature, trustpinning can be configured in `daemon.json`, whereby only repositories signed with a user-specified root key can be pulled and run.

This feature provides more insight to administrators than previously available with the CLI for enforcing and performing image signature verification.

For more information on configuring Docker Content Trust Signature Verification, go to [Content trust in Docker](https://docs.docker.com/engine/security/trust/).

## [Other kernel security features](#other-kernel-security-features)

Capabilities are just one of the many security features provided by modern Linux kernels. It is also possible to leverage existing, well-known systems like TOMOYO, AppArmor, SELinux, GRSEC, etc. with Docker.

While Docker currently only enables capabilities, it doesn't interfere with the other systems. This means that there are many different ways to harden a Docker host. Here are a few examples.

* You can run a kernel with GRSEC and PAX. This adds many safety checks, both at compile-time and run-time; it also defeats many exploits, thanks to techniques like address randomization. It doesn't require Docker-specific configuration, since those security features apply system-wide, independent of containers.
* If your distribution comes with security model templates for Docker containers, you can use them out of the box. For instance, we ship a template that works with AppArmor and Red Hat comes with SELinux policies for Docker. These templates provide an extra safety net (even though it overlaps greatly with capabilities).
* You can define your own policies using your favorite access control mechanism.

Just as you can use third-party tools to augment Docker containers, including special network topologies or shared filesystems, tools exist to harden Docker containers without the need to modify Docker itself.

As of Docker 1.10 User Namespaces are supported directly by the docker daemon. This feature allows for the root user in a container to be mapped to a non uid-0 user outside the container, which can help to mitigate the risks of container breakout. This facility is available but not enabled by default.

Refer to the [daemon command](https://docs.docker.com/reference/cli/dockerd/#daemon-user-namespace-options) in the command line reference for more information on this feature. Additional information on the implementation of User Namespaces in Docker can be found in [this blog post](https://integratedcode.us/2015/10/13/user-namespaces-have-arrived-in-docker/).

## [Conclusions](#conclusions)

Docker containers are, by default, quite secure; especially if you run your processes as non-privileged users inside the container.

You can add an extra layer of safety by enabling AppArmor, SELinux, GRSEC, or another appropriate hardening system.

If you think of ways to make docker more secure, we welcome feature requests, pull requests, or comments on the Docker community forums.

## [Related information](#related-information)

* [Use trusted images](https://docs.docker.com/engine/security/trust/)
* [Seccomp security profiles for Docker](https://docs.docker.com/engine/security/seccomp/)
* [AppArmor security profiles for Docker](https://docs.docker.com/engine/security/apparmor/)
* [On the Security of Containers (2014)](https://medium.com/@ewindisch/on-the-security-of-containers-2c60ffe25a9e)
* [Docker swarm mode overlay network security model](https://docs.docker.com/engine/network/drivers/overlay/)

----
url: https://docs.docker.com/reference/cli/docker/mcp/server/
----

# docker mcp server

***

| Description | Manage servers |
| ----------- | -------------- |

## [Description](#description)

Manage servers

## [Subcommands](#subcommands)

| Command                                                                                   | Description                         |
| ----------------------------------------------------------------------------------------- | ----------------------------------- |
| [`docker mcp server init`](https://docs.docker.com/reference/cli/docker/mcp/server/init/) | Initialize a new MCP server project |

----
url: https://docs.docker.com/reference/cli/docker/scout/attestation/get/
----

# docker scout attestation get

***

| Description                                                               | Get attestation for image                             |
| ------------------------------------------------------------------------- | ----------------------------------------------------- |
| Usage                                                                     | `docker scout attestation get OPTIONS IMAGE [DIGEST]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker scout attest get`                             |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

The docker scout attestation get command gets attestations for images.

## [Options](#options)

| Option             | Default                                                    | Description                                                                                          |
| ------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--key`            | `https://registry.scout.docker.com/keyring/dhi/latest.pub` | Signature key to use for verification                                                                |
| `--org`            |                                                            | Namespace of the Docker organization                                                                 |
| `-o, --output`     |                                                            | Write the report to a file                                                                           |
| `--platform`       |                                                            | Platform of image to analyze                                                                         |
| `--predicate`      |                                                            | Get in-toto predicate only dropping the subject                                                      |
| `--predicate-type` |                                                            | Predicate-type for attestation                                                                       |
| `--ref`            |                                                            | Reference to use if the provided tarball contains multiple references. Can only be used with archive |
| `--skip-tlog`      |                                                            | Skip signature verification against public transaction log                                           |
| `--verify`         |                                                            | Verify the signature on the attestation                                                              |

----
url: https://docs.docker.com/retired/
----

# Deprecated and retired Docker products and features

***

Table of contents

***

This document provides an overview of Docker features, products, and open-source projects that have been deprecated, retired, or transitioned.

> Note
>
> This page does not cover deprecated and removed Docker Engine features. For a detailed list of deprecated Docker Engine features, refer to the [Docker Engine Deprecated Features documentation](https://docs.docker.com/engine/deprecated/).

## [Products and features](#products-and-features)

Support for these deprecated or retired features is no longer provided by Docker, Inc. The projects that have been transitioned to third parties continue to receive updates from their new maintainers.

### [Docker Machine](#docker-machine)

Docker Machine was a tool for provisioning and managing Docker hosts across various platforms, including virtual machines and cloud providers. It is no longer maintained, and users are encouraged to use [Docker Desktop](https://docs.docker.com/desktop/) or [Docker Engine](https://docs.docker.com/engine/) directly on supported platforms. Machine's approach to creating and configuring hosts has been superseded by more modern workflows that integrate more closely with Docker Desktop.

### [Docker Toolbox](#docker-toolbox)

Docker Toolbox was used on older systems where Docker Desktop could not run. It bundled Docker Machine, Docker Engine, and Docker Compose into a single installer. Toolbox is no longer maintained and is effectively replaced by [Docker Desktop](https://docs.docker.com/desktop/) on current systems. References to Docker Toolbox occasionally appear in older documentation or community tutorials, but it is not recommended for new installations.

### [Docker Cloud integrations](#docker-cloud-integrations)

Docker previously offered integrations for Amazon's Elastic Container Service (ECS) and Azure Container Instances (ACI) to streamline container workflows. These integrations have been deprecated, and users should now rely on native cloud tools or third-party solutions to manage their workloads. The move toward platform-specific or universal orchestration tools reduced the need for specialized Docker Cloud integrations.

You can still view the relevant documentation for these integrations in the [Compose CLI repository](https://github.com/docker-archive/compose-cli/tree/main/docs).

### [Docker Enterprise Edition](#docker-enterprise-edition)

Docker Enterprise Edition (EE) was Docker's commercial platform for deploying and managing large-scale container environments. It was acquired by Mirantis in 2019, and users looking for enterprise-level functionality can now explore Mirantis Kubernetes Engine or other products offered by Mirantis. Much of the technology and features found in Docker EE have been absorbed into the Mirantis product line.

> Tip
>
> For information about enterprise-level features offered by Docker today, see the [Docker Business subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsRetired).

### [Docker Data Center and Docker Trusted Registry](#docker-data-center-and-docker-trusted-registry)

Docker Data Center (DDC) was an umbrella term that encompassed Docker Universal Control Plane (UCP) and Docker Trusted Registry (DTR). These components provided a full-stack solution for managing containers, security, and registry services in enterprise environments. They are now under the Mirantis portfolio following the Docker Enterprise acquisition. Users still encountering references to DDC, UCP, or DTR should refer to Mirantis's documentation for guidance on modern equivalents.

### [Dev Environments](#dev-environments)

Dev Environments was a feature introduced in Docker Desktop that allowed developers to spin up development environments quickly. It was deprecated and removed from Docker Desktop version 4.42 and later. Similar workflows can be achieved through Docker Compose or by creating custom configurations tailored to specific project requirements.

### [Docker Desktop sandboxes](#docker-desktop-sandboxes)

Docker Desktop sandboxes let users run AI coding agents in isolated microVMs through the `docker sandbox` command. The Docker Desktop integration is deprecated. Use the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/) instead.

You can still view the [Docker Desktop sandboxes documentation](https://docs.docker.com/ai/sandboxes/docker-desktop/).

### [GitHub Copilot extension](#github-copilot-extension)

The Docker for GitHub Copilot extension integrated Docker capabilities with GitHub Copilot Chat, helping developers containerize applications, generate Docker assets, and analyze vulnerabilities through conversational prompts. The extension was available in early access on the GitHub Marketplace. GitHub [deprecated Copilot Extensions](https://github.blog/changelog/2025-09-24-deprecate-github-copilot-extensions-github-apps/) which led to the retirement of the Docker for GitHub Copilot extension. If you're looking for AI-assisted Docker workflows, explore the Docker MCP Toolkit and MCP Catalog, or use Gordon in Docker Desktop and the Docker CLI.

### [Enhanced Service Account add-ons](#enhanced-service-account-add-ons)

Enhanced Service Account add-ons provided tiered pull rate limits for automated workflows and service accounts accessing Docker Hub.

Docker recommends transitioning to [Organization Access Tokens (OATs)](https://docs.docker.com/enterprise/security/access-tokens/), which provide secure, programmatic access to Docker Hub with granular repository permissions, token expiration, and better security auditing. OATs are included with Docker Team and Business subscriptions and offer similar functionality without requiring separate add-on purchases.

### [Docker Hub Automated Builds](#docker-hub-automated-builds)

Docker Hub Automated Builds was a feature of Docker Hub that allowed building Docker images from source code in an external repository and automatically pushing the built image to your Docker repositories. This feature has been deprecated and will be removed on April 1, 2027.

## [Open source projects](#open-source-projects)

Several open-source projects originally maintained by Docker have been archived, discontinued, or transitioned to other maintainers or organizations.

### [Registry (now CNCF Distribution)](#registry-now-cncf-distribution)

The Docker Registry served as the open-source implementation of a container image registry. It was donated to the Cloud Native Computing Foundation (CNCF) in 2019 and is maintained under the name "Distribution." It remains a cornerstone for managing and distributing container images.

[CNCF Distribution](https://github.com/distribution/distribution)

### [Docker Compose v1 (replaced by Compose v2)](#docker-compose-v1-replaced-by-compose-v2)

Docker Compose v1 (`docker-compose`), a Python-based tool for defining multi-container applications, has been superseded by Compose v2 (`docker compose`), which is written in Go and integrates with the Docker CLI. Compose v1 is no longer maintained, and users should migrate to Compose v2.

[Compose v2 Documentation](https://docs.docker.com/compose/)

### [Docker SBOM CLI plugin](#docker-sbom-cli-plugin)

The Docker SBOM CLI plugin provided the `docker sbom` command for generating and viewing software bill of materials (SBOMs) for container images. The plugin is discontinued. Use [`docker scout sbom`](/reference/cli/docker/scout/sbom/) for SBOM generation and inspection.

[See Docker SBOM CLI plugin release notes for migration guidance](https://github.com/docker/sbom-cli-plugin/releases/tag/v0.7.0)

### [InfraKit](#infrakit)

InfraKit was an open-source toolkit designed to manage declarative infrastructure and automate container deployments. It has been archived, and users are encouraged to explore tools such as Terraform for infrastructure provisioning and orchestration.

[InfraKit GitHub Repository](https://github.com/docker/infrakit)

### [Docker Notary (now CNCF Notary)](#docker-notary-now-cncf-notary)

Docker Notary was a system for signing and verifying the authenticity of container content. It was donated to the CNCF in 2017 and continues to be developed as "Notary." Users seeking secure content verification should consult the CNCF Notary project.

[CNCF Notary](https://github.com/notaryproject/notary)

### [SwarmKit](#swarmkit)

SwarmKit powers Docker Swarm mode by providing orchestration for container deployments. While Swarm mode remains functional, development has slowed in favor of Kubernetes-based solutions. Individuals evaluating container orchestration options should investigate whether SwarmKit meets modern workload requirements.

[SwarmKit GitHub Repository](https://github.com/docker/swarmkit)

----
url: https://docs.docker.com/guides/testcontainers-java-aws-localstack/write-tests/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Write tests with Testcontainers

***

Table of contents

***

To test the application, you need a running LocalStack instance that emulates the AWS S3 and SQS services. Testcontainers spins up LocalStack in a Docker container and `@DynamicPropertySource` connects it to Spring Cloud AWS.

## [Configure the test container](#configure-the-test-container)

You can start a LocalStack container and configure the Spring Cloud AWS properties to talk to it instead of actual AWS services. The properties you need to set are:

```properties
spring.cloud.aws.s3.endpoint=http://localhost:4566
spring.cloud.aws.sqs.endpoint=http://localhost:4566
spring.cloud.aws.credentials.access-key=noop
spring.cloud.aws.credentials.secret-key=noop
spring.cloud.aws.region.static=us-east-1
```

For testing, use an ephemeral container that starts on a random available port so that you can run multiple builds in CI in parallel without port conflicts.

## [Write the test](#write-the-test)

Create `MessageListenerTest.java`:

```java
package com.testcontainers.demo;

import static org.assertj.core.api.Assertions.assertThat;
import static org.awaitility.Awaitility.await;
import static org.testcontainers.containers.localstack.LocalStackContainer.Service.S3;
import static org.testcontainers.containers.localstack.LocalStackContainer.Service.SQS;

import java.io.IOException;
import java.time.Duration;
import java.util.UUID;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.containers.localstack.LocalStackContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.utility.DockerImageName;

@SpringBootTest
@Testcontainers
class MessageListenerTest {

  @Container
  static LocalStackContainer localStack = new LocalStackContainer(
    DockerImageName.parse("localstack/localstack:3.0")
  );

  static final String BUCKET_NAME = UUID.randomUUID().toString();
  static final String QUEUE_NAME = UUID.randomUUID().toString();

  @DynamicPropertySource
  static void overrideProperties(DynamicPropertyRegistry registry) {
    registry.add("app.bucket", () -> BUCKET_NAME);
    registry.add("app.queue", () -> QUEUE_NAME);
    registry.add(
      "spring.cloud.aws.region.static",
      () -> localStack.getRegion()
    );
    registry.add(
      "spring.cloud.aws.credentials.access-key",
      () -> localStack.getAccessKey()
    );
    registry.add(
      "spring.cloud.aws.credentials.secret-key",
      () -> localStack.getSecretKey()
    );
    registry.add(
      "spring.cloud.aws.s3.endpoint",
      () -> localStack.getEndpointOverride(S3).toString()
    );
    registry.add(
      "spring.cloud.aws.sqs.endpoint",
      () -> localStack.getEndpointOverride(SQS).toString()
    );
  }

  @BeforeAll
  static void beforeAll() throws IOException, InterruptedException {
    localStack.execInContainer("awslocal", "s3", "mb", "s3://" + BUCKET_NAME);
    localStack.execInContainer(
      "awslocal",
      "sqs",
      "create-queue",
      "--queue-name",
      QUEUE_NAME
    );
  }

  @Autowired
  StorageService storageService;

  @Autowired
  MessageSender publisher;

  @Autowired
  ApplicationProperties properties;

  @Test
  void shouldHandleMessageSuccessfully() {
    Message message = new Message(UUID.randomUUID(), "Hello World");
    publisher.publish(properties.queue(), message);

    await()
      .pollInterval(Duration.ofSeconds(2))
      .atMost(Duration.ofSeconds(10))
      .ignoreExceptions()
      .untilAsserted(() -> {
        String msg = storageService.downloadAsString(
          properties.bucket(),
          message.uuid().toString()
        );
        assertThat(msg).isEqualTo("Hello World");
      });
  }
}
```

Here's what the test does:

* `@SpringBootTest` starts the full Spring application context.
* The Testcontainers JUnit 5 annotations `@Testcontainers` and `@Container` manage the lifecycle of a `LocalStackContainer` instance.
* `@DynamicPropertySource` obtains the dynamic S3 and SQS endpoint URLs, region, access key, and secret key from the container, and registers them as Spring Cloud AWS configuration properties.
* `@BeforeAll` creates the required SQS queue and S3 bucket using the `awslocal` CLI tool that comes pre-installed in the LocalStack Docker image. The `localStack.execInContainer()` API runs commands inside the container.
* `shouldHandleMessageSuccessfully()` publishes a `Message` to the SQS queue. The listener receives the message and stores its content in the S3 bucket with the UUID as the key. Awaitility waits up to 10 seconds for the expected content to appear in the bucket.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-aws-localstack/run-tests/)

----
url: https://docs.docker.com/build/building/best-practices/
----

# Building best practices

***

Table of contents

***

## [Use multi-stage builds](#use-multi-stage-builds)

Multi-stage builds let you reduce the size of your final image, by creating a cleaner separation between the building of your image and the final output. Split your Dockerfile instructions into distinct stages to make sure that the resulting output only contains the files that are needed to run the application.

Using multiple stages can also let you build more efficiently by executing build steps in parallel.

See [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/) for more information.

### [Create reusable stages](#create-reusable-stages)

If you have multiple images with a lot in common, consider creating a reusable stage that includes the shared components, and basing your unique stages on that. Docker only needs to build the common stage once. This means that your derivative images use memory on the Docker host more efficiently and load more quickly.

It's also easier to maintain a common base stage ("Don't repeat yourself"), than it is to have multiple different stages doing similar things.

## [Choose the right base image](#choose-the-right-base-image)

The first step towards achieving a secure image is to choose the right base image. When choosing an image, ensure it's built from a trusted source and keep it small.

* [Docker Official Images](https://hub.docker.com/search?badges=official) are a curated collection that have clear documentation, promote best practices, and are regularly updated. They provide a trusted starting point for many applications.

* [Verified Publisher](https://hub.docker.com/search?badges=verified_publisher) images are high-quality images published and maintained by the organizations partnering with Docker, with Docker verifying the authenticity of the content in their repositories.

* [Docker-Sponsored Open Source](https://hub.docker.com/search?badges=open_source) are published and maintained by open source projects sponsored by Docker through an [open source program](https://docs.docker.com/docker-hub/image-library/trusted-content/#docker-sponsored-open-source-software-images).

When you pick your base image, look out for the badges indicating that the image is part of these programs.

When building your own image from a Dockerfile, ensure you choose a minimal base image that matches your requirements. A smaller base image not only offers portability and fast downloads, but also shrinks the size of your image and minimizes the number of vulnerabilities introduced through the dependencies.

You should also consider using two types of base image: one for building and unit testing, and another (typically slimmer) image for production. In the later stages of development, your image may not require build tools such as compilers, build systems, and debugging tools. A small image with minimal dependencies can considerably lower the attack surface.

## [Rebuild your images often](#rebuild-your-images-often)

Docker images are immutable. Building an image is taking a snapshot of that image at that moment. That includes any base images, libraries, or other software you use in your build. To keep your images up-to-date and secure, rebuild your images regularly with updated dependencies.

### [Use --pull to get fresh base images](#use---pull-to-get-fresh-base-images)

The following Dockerfile uses the `24.04` tag of the `ubuntu` image. Over time, that tag may resolve to a different underlying version of the `ubuntu` image, as the publisher rebuilds the image with new security patches and updated libraries.

```dockerfile
# syntax=docker/dockerfile:1
FROM ubuntu:24.04
RUN apt-get -y update && apt-get install -y --no-install-recommends python3
```

To get the latest version of the base image, use the `--pull` flag:

```console
$ docker build --pull -t my-image:my-tag .
```

The `--pull` flag forces Docker to check for and download a newer version of the base image, even if you have a version cached locally.

### [Use --no-cache for clean builds](#use---no-cache-for-clean-builds)

The `--no-cache` flag disables the build cache, forcing Docker to rebuild all layers from scratch:

```console
$ docker build --no-cache -t my-image:my-tag .
```

This gets the latest available versions of dependencies from package managers like `apt-get` or `npm`. However, `--no-cache` doesn't pull a fresh base image - it only prevents reusing cached layers. For a completely fresh build with the latest base image, combine both flags:

```console
$ docker build --pull --no-cache -t my-image:my-tag .
```

Also consider [pinning base image versions](#pin-base-image-versions).

## [Exclude with .dockerignore](#exclude-with-dockerignore)

To exclude files not relevant to the build, without restructuring your source repository, use a `.dockerignore` file. This file supports exclusion patterns similar to `.gitignore` files.

For example, to exclude all files with the `.md` extension:

```plaintext
*.md
```

For information on creating one, see [Dockerignore file](https://docs.docker.com/build/concepts/context/#dockerignore-files).

## [Create ephemeral containers](#create-ephemeral-containers)

The image defined by your Dockerfile should generate containers that are as ephemeral as possible. Ephemeral means that the container can be stopped and destroyed, then rebuilt and replaced with an absolute minimum set up and configuration.

Refer to [Processes](https://12factor.net/processes) under *The Twelve-factor App* methodology to get a feel for the motivations of running containers in such a stateless fashion.

## [Don't install unnecessary packages](#dont-install-unnecessary-packages)

Avoid installing extra or unnecessary packages just because they might be nice to have. For example, you don’t need to include a text editor in a database image.

When you avoid installing extra or unnecessary packages, your images have reduced complexity, reduced dependencies, reduced file sizes, and reduced build times.

## [Decouple applications](#decouple-applications)

Each container should have only one concern. Decoupling applications into multiple containers makes it easier to scale horizontally and reuse containers. For instance, a web application stack might consist of three separate containers, each with its own unique image, to manage the web application, database, and an in-memory cache in a decoupled manner.

Limiting each container to one process is a good rule of thumb, but it's not a hard and fast rule. For example, not only can containers be [spawned with an init process](https://docs.docker.com/engine/containers/multi-service_container/), some programs might spawn additional processes of their own accord. For instance, [Celery](https://docs.celeryq.dev/) can spawn multiple worker processes, and [Apache](https://httpd.apache.org/) can create one process per request.

Use your best judgment to keep containers as clean and modular as possible. If containers depend on each other, you can use [Docker container networks](https://docs.docker.com/engine/network/) to ensure that these containers can communicate.

## [Sort multi-line arguments](#sort-multi-line-arguments)

Whenever possible, sort multi-line arguments alphanumerically to make maintenance easier. This helps to avoid duplication of packages and make the list much easier to update. This also makes PRs a lot easier to read and review. Adding a space before a backslash (`\`) helps as well.

Here’s an example from the [buildpack-deps image](https://github.com/docker-library/buildpack-deps):

```dockerfile
RUN apt-get update && apt-get install -y --no-install-recommends \
  bzr \
  cvs \
  git \
  mercurial \
  subversion \
  && rm -rf /var/lib/apt/lists/*
```

## [Leverage build cache](#leverage-build-cache)

When building an image, Docker steps through the instructions in your Dockerfile, executing each in the order specified. For each instruction, Docker checks whether it can reuse the instruction from the build cache.

Understanding how the build cache works, and how cache invalidation occurs, is critical for ensuring faster builds. For more information about the Docker build cache and how to optimize your builds, see [Docker build cache](https://docs.docker.com/build/cache/).

## [Pin base image versions](#pin-base-image-versions)

Image tags are mutable, meaning a publisher can update a tag to point to a new image. This is useful because it lets publishers update tags to point to newer versions of an image. And as an image consumer, it means you automatically get the new version when you re-build your image.

For example, if you specify `FROM alpine:3.21` in your Dockerfile, `3.21` resolves to the latest patch version for `3.21`.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine:3.21
```

At one point in time, the `3.21` tag might point to version 3.21.1 of the image. If you rebuild the image 3 months later, the same tag might point to a different version, such as 3.21.4. This publishing workflow is best practice, and most publishers use this tagging strategy, but it isn't enforced.

The downside with this is that you're not guaranteed to get the same for every build. This could result in breaking changes, and it means you also don't have an audit trail of the exact image versions that you're using.

To fully secure your supply chain integrity, you can pin the image version to a specific digest. By pinning your images to a digest, you're guaranteed to always use the same image version, even if a publisher replaces the tag with a new image. For example, the following Dockerfile pins the Alpine image to the same tag as earlier, `3.21`, but this time with a digest reference as well.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine:3.21@sha256:a8560b36e8b8210634f77d9f7f9efd7ffa463e380b75e2e74aff4511df3ef88c
```

With this Dockerfile, even if the publisher updates the `3.21` tag, your builds would still use the pinned image version: `a8560b36e8b8210634f77d9f7f9efd7ffa463e380b75e2e74aff4511df3ef88c`.

While this helps you avoid unexpected changes, it's also more tedious to have to look up and include the image digest for base image versions manually each time you want to update it. And you're opting out of automated security fixes, which is likely something you want to get.

Docker Scout's default [**Up-to-Date Base Images** policy](https://docs.docker.com/scout/policy/#up-to-date-base-images) checks whether the base image version you're using is in fact the latest version. This policy also checks if pinned digests in your Dockerfile correspond to the correct version. If a publisher updates an image that you've pinned, the policy evaluation returns a non-compliant status, indicating that you should update your image.

Docker Scout also supports an automated remediation workflow for keeping your base images up-to-date. When a new image digest is available, Docker Scout can automatically raise a pull request on your repository to update your Dockerfiles to use the latest version. This is better than using a tag that changes the version automatically, because you're in control and you have an audit trail of when and how the change occurred.

For more information about automatically updating your base images with Docker Scout, see [Remediation](https://docs.docker.com/scout/policy/remediation/).

## [Build and test your images in CI](#build-and-test-your-images-in-ci)

When you check in a change to source control or create a pull request, use [GitHub Actions](https://docs.docker.com/build/ci/github-actions/) or another CI/CD pipeline to automatically build and tag a Docker image and test it.

## [Dockerfile instructions](#dockerfile-instructions)

Follow these recommendations on how to properly use the [Dockerfile instructions](https://docs.docker.com/reference/dockerfile/) to create an efficient and maintainable Dockerfile.

> Tip
>
> To improve linting, code navigation, and vulnerability scanning of your Dockerfiles in Visual Studio Code see the [Docker DX](https://marketplace.visualstudio.com/items?itemName=docker.docker) extension.

### [FROM](#from)

Whenever possible, use current official images as the basis for your images. Docker recommends the [Alpine image](https://hub.docker.com/_/alpine/) as it is tightly controlled and small in size (under 6 MB), while still being a full Linux distribution.

For more information about the `FROM` instruction, see [Dockerfile reference for the FROM instruction](https://docs.docker.com/reference/dockerfile/#from).

### [LABEL](#label)

You can add labels to your image to help organize images by project, record licensing information, to aid in automation, or for other reasons. For each label, add a line beginning with `LABEL` with one or more key-value pairs. The following examples show the different acceptable formats. Explanatory comments are included inline.

Strings with spaces must be quoted or the spaces must be escaped. Inner quote characters (`"`), must also be escaped. For example:

```dockerfile
# Set one or more individual labels
LABEL com.example.version="0.0.1-beta"
LABEL vendor1="ACME Incorporated"
LABEL vendor2=ZENITH\ Incorporated
LABEL com.example.release-date="2015-02-12"
LABEL com.example.version.is-production=""
```

An image can have more than one label. Prior to Docker 1.10, it was recommended to combine all labels into a single `LABEL` instruction, to prevent extra layers from being created. This is no longer necessary, but combining labels is still supported. For example:

```dockerfile
# Set multiple labels on one line
LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"
```

The above example can also be written as:

```dockerfile
# Set multiple labels at once, using line-continuation characters to break long lines
LABEL vendor=ACME\ Incorporated \
      com.example.is-beta= \
      com.example.is-production="" \
      com.example.version="0.0.1-beta" \
      com.example.release-date="2015-02-12"
```

See [Understanding object labels](https://docs.docker.com/engine/manage-resources/labels/) for guidelines about acceptable label keys and values. For information about querying labels, refer to the items related to filtering in [Managing labels on objects](https://docs.docker.com/engine/manage-resources/labels/#manage-labels-on-objects). See also [LABEL](https://docs.docker.com/reference/dockerfile/#label) in the Dockerfile reference.

### [RUN](#run)

Split long or complex `RUN` statements on multiple lines separated with backslashes to make your Dockerfile more readable, understandable, and maintainable.

For example, you can chain commands with the `&&` operator, and use escape characters to break long commands into multiple lines.

```dockerfile
RUN apt-get update && apt-get install -y --no-install-recommends \
    package-bar \
    package-baz \
    package-foo
```

By default, backslash escapes a newline character, but you can change it with the [`escape` directive](https://docs.docker.com/reference/dockerfile/#escape).

You can also use here documents to run multiple commands without chaining them with a pipeline operator:

```dockerfile
RUN <<EOF
apt-get update
apt-get install -y --no-install-recommends \
    package-bar \
    package-baz \
    package-foo
EOF
```

For more information about `RUN`, see [Dockerfile reference for the RUN instruction](https://docs.docker.com/reference/dockerfile/#run).

#### [apt-get](#apt-get)

One common use case for `RUN` instructions in Debian-based images is to install software using `apt-get`. Because `apt-get` installs packages, the `RUN apt-get` command has several counter-intuitive behaviors to look out for.

Always combine `RUN apt-get update` with `apt-get install` in the same `RUN` statement. For example:

```dockerfile
RUN apt-get update && apt-get install -y --no-install-recommends \
    package-bar \
    package-baz \
    package-foo
```

Using `apt-get update` alone in a `RUN` statement causes caching issues and subsequent `apt-get install` instructions to fail. For example, this issue will occur in the following Dockerfile:

```dockerfile
# syntax=docker/dockerfile:1

FROM ubuntu:22.04
RUN apt-get update
RUN apt-get install -y --no-install-recommends curl
```

After building the image, all layers are in the Docker cache. Suppose you later modify `apt-get install` by adding an extra package as shown in the following Dockerfile:

```dockerfile
# syntax=docker/dockerfile:1

FROM ubuntu:22.04
RUN apt-get update
RUN apt-get install -y --no-install-recommends curl nginx
```

Docker sees the initial and modified instructions as identical and reuses the cache from previous steps. As a result the `apt-get update` isn't executed because the build uses the cached version. Because the `apt-get update` isn't run, your build can potentially get an outdated version of the `curl` and `nginx` packages.

Using `RUN apt-get update && apt-get install -y --no-install-recommends` ensures your Dockerfile installs the latest package versions with no further coding or manual intervention. This technique is known as cache busting. You can also achieve cache busting by specifying a package version. This is known as version pinning. For example:

```dockerfile
RUN apt-get update && apt-get install -y --no-install-recommends \
    package-bar \
    package-baz \
    package-foo=1.3.*
```

Version pinning forces the build to retrieve a particular version regardless of what’s in the cache. This technique can also reduce failures due to unanticipated changes in required packages.

Below is a well-formed `RUN` instruction that demonstrates all the `apt-get` recommendations.

```dockerfile
RUN apt-get update && apt-get install -y --no-install-recommends \
    aufs-tools \
    automake \
    build-essential \
    curl \
    dpkg-sig \
    libcap-dev \
    libsqlite3-dev \
    mercurial \
    reprepro \
    ruby1.9.1 \
    ruby1.9.1-dev \
    s3cmd=1.1.* \
    && rm -rf /var/lib/apt/lists/*
```

The `s3cmd` argument specifies a version `1.1.*`. If the image previously used an older version, specifying the new one causes a cache bust of `apt-get update` and ensures the installation of the new version. Listing packages on each line can also prevent mistakes in package duplication.

In addition, when you clean up the apt cache by removing `/var/lib/apt/lists` it reduces the image size, since the apt cache isn't stored in a layer. Since the `RUN` statement starts with `apt-get update`, the package cache is always refreshed prior to `apt-get install`.

Official Debian and Ubuntu images [automatically run `apt-get clean`](https://github.com/debuerreotype/debuerreotype/blob/c9542ab785e72696eb2908a6dbc9220abbabef39/scripts/debuerreotype-minimizing-config#L87-L109), so explicit invocation is not required.

#### [Using pipes](#using-pipes)

Some `RUN` commands depend on the ability to pipe the output of one command into another, using the pipe character (`|`), as in the following example:

```dockerfile
RUN wget -O - https://some.site | wc -l > /number
```

Docker executes these commands using the `/bin/sh -c` interpreter, which only evaluates the exit code of the last operation in the pipe to determine success. In the example above, this build step succeeds and produces a new image so long as the `wc -l` command succeeds, even if the `wget` command fails.

If you want the command to fail due to an error at any stage in the pipe, prepend `set -o pipefail &&` to ensure that an unexpected error prevents the build from inadvertently succeeding. For example:

```dockerfile
RUN set -o pipefail && wget -O - https://some.site | wc -l > /number
```

> Note
>
> Not all shells support the `-o pipefail` option.
>
> In cases such as the `dash` shell on Debian-based images, consider using the *exec* form of `RUN` to explicitly choose a shell that does support the `pipefail` option. For example:
>
> ```dockerfile
> RUN ["/bin/bash", "-c", "set -o pipefail && wget -O - https://some.site | wc -l > /number"]
> ```

### [CMD](#cmd)

The `CMD` instruction should be used to run the software contained in your image, along with any arguments. `CMD` should almost always be used in the form of `CMD ["executable", "param1", "param2"]`. Thus, if the image is for a service, such as Apache and Rails, you would run something like `CMD ["apache2","-DFOREGROUND"]`. Indeed, this form of the instruction is recommended for any service-based image.

In most other cases, `CMD` should be given an interactive shell, such as bash, Python and perl. For example, `CMD ["perl", "-de0"]`, `CMD ["python"]`, or `CMD ["php", "-a"]`. Using this form means that when you execute something like `docker run -it python`, you’ll get dropped into a usable shell, ready to go. `CMD` should rarely be used in the manner of `CMD ["param", "param"]` in conjunction with [`ENTRYPOINT`](https://docs.docker.com/reference/dockerfile/#entrypoint), unless you and your expected users are already quite familiar with how `ENTRYPOINT` works.

For more information about `CMD`, see [Dockerfile reference for the CMD instruction](https://docs.docker.com/reference/dockerfile/#cmd).

### [EXPOSE](#expose)

The `EXPOSE` instruction indicates the ports on which a container listens for connections. Consequently, you should use the common, traditional port for your application. For example, an image containing the Apache web server would use `EXPOSE 80`, while an image containing MongoDB would use `EXPOSE 27017` and so on.

For external access, your users can execute `docker run` with a flag indicating how to map the specified port to the port of their choice. For container linking, Docker provides environment variables for the path from the recipient container back to the source (for example, `MYSQL_PORT_3306_TCP`).

For more information about `EXPOSE`, see [Dockerfile reference for the EXPOSE instruction](https://docs.docker.com/reference/dockerfile/#expose).

### [ENV](#env)

To make new software easier to run, you can use `ENV` to update the `PATH` environment variable for the software your container installs. For example, `ENV PATH=/usr/local/nginx/bin:$PATH` ensures that `CMD ["nginx"]` just works.

The `ENV` instruction is also useful for providing the required environment variables specific to services you want to containerize, such as Postgres’s `PGDATA`.

Lastly, `ENV` can also be used to set commonly used version numbers so that version bumps are easier to maintain, as seen in the following example:

```dockerfile
ENV PG_MAJOR=9.3
ENV PG_VERSION=9.3.4
RUN curl -SL https://example.com/postgres-$PG_VERSION.tar.xz | tar -xJC /usr/src/postgres && …
ENV PATH=/usr/local/postgres-$PG_MAJOR/bin:$PATH
```

Similar to having constant variables in a program, as opposed to hard-coding values, this approach lets you change a single `ENV` instruction to automatically bump the version of the software in your container.

Each `ENV` line creates a new intermediate layer, just like `RUN` commands. This means that even if you unset the environment variable in a future layer, it still persists in this layer and its value can be dumped. You can test this by creating a Dockerfile like the following, and then building it.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
ENV ADMIN_USER="mark"
RUN echo $ADMIN_USER > ./mark
RUN unset ADMIN_USER
```

```console
$ docker run --rm test sh -c 'echo $ADMIN_USER'

mark
```

To prevent this and unset the environment variable, use a `RUN` command with shell commands, to set, use, and unset the variable all in a single layer. You can separate your commands with `;` or `&&`. If you use the second method, and one of the commands fails, the `docker build` also fails. This is usually a good idea. Using `\` as a line continuation character for Linux Dockerfiles improves readability. You could also put all of the commands into a shell script and have the `RUN` command just run that shell script.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN export ADMIN_USER="mark" \
    && echo $ADMIN_USER > ./mark \
    && unset ADMIN_USER
CMD sh
```

```console
$ docker run --rm test sh -c 'echo $ADMIN_USER'
```

For more information about `ENV`, see [Dockerfile reference for the ENV instruction](https://docs.docker.com/reference/dockerfile/#env).

### [ADD or COPY](#add-or-copy)

`ADD` and `COPY` are functionally similar. `COPY` supports basic copying of files into the container, from the [build context](https://docs.docker.com/build/concepts/context/) or from a stage in a [multi-stage build](https://docs.docker.com/build/building/multi-stage/). `ADD` supports features for fetching files from remote HTTPS and Git URLs, and extracting tar files automatically when adding files from the build context.

You'll mostly want to use `COPY` for copying files from one stage to another in a multi-stage build. If you need to add files from the build context to the container temporarily to execute a `RUN` instruction, you can often substitute the `COPY` instruction with a bind mount instead. For example, to temporarily add a `requirements.txt` file for a `RUN pip install` instruction:

```dockerfile
RUN --mount=type=bind,source=requirements.txt,target=/tmp/requirements.txt \
    pip install --requirement /tmp/requirements.txt
```

Bind mounts are more efficient than `COPY` for including files from the build context in the container. Note that bind-mounted files are only added temporarily for a single `RUN` instruction, and don't persist in the final image. If you need to include files from the build context in the final image, use `COPY`.

The `ADD` instruction is best for when you need to download a remote artifact as part of your build. `ADD` is better than manually adding files using something like `wget` and `tar`, because it ensures a more precise build cache. `ADD` also has built-in support for checksum validation of the remote resources, and a protocol for parsing branches, tags, and subdirectories from [Git URLs](/reference/cli/docker/buildx/build/).

The following example uses `ADD` to download a .NET installer. Combined with multi-stage builds, only the .NET runtime remains in the final stage, no intermediate files.

```dockerfile
# syntax=docker/dockerfile:1

FROM scratch AS src
ARG DOTNET_VERSION=8.0.0-preview.6.23329.7
ADD --checksum=sha256:270d731bd08040c6a3228115de1f74b91cf441c584139ff8f8f6503447cebdbb \
    https://dotnetcli.azureedge.net/dotnet/Runtime/$DOTNET_VERSION/dotnet-runtime-$DOTNET_VERSION-linux-arm64.tar.gz /dotnet.tar.gz

FROM mcr.microsoft.com/dotnet/runtime-deps:8.0.0-preview.6-bookworm-slim-arm64v8 AS installer

# Retrieve .NET Runtime
RUN --mount=from=src,target=/src <<EOF
mkdir -p /dotnet
tar -oxzf /src/dotnet.tar.gz -C /dotnet
EOF

FROM mcr.microsoft.com/dotnet/runtime-deps:8.0.0-preview.6-bookworm-slim-arm64v8

COPY --from=installer /dotnet /usr/share/dotnet
RUN ln -s /usr/share/dotnet/dotnet /usr/bin/dotnet
```

For more information about `ADD` or `COPY`, see the following:

* [Dockerfile reference for the ADD instruction](https://docs.docker.com/reference/dockerfile/#add)
* [Dockerfile reference for the COPY instruction](https://docs.docker.com/reference/dockerfile/#copy)

### [ENTRYPOINT](#entrypoint)

The best use for `ENTRYPOINT` is to set the image's main command, allowing that image to be run as though it was that command, and then use `CMD` as the default flags.

The following is an example of an image for the command line tool `s3cmd`:

```dockerfile
ENTRYPOINT ["s3cmd"]
CMD ["--help"]
```

You can use the following command to run the image and show the command's help:

```console
$ docker run s3cmd
```

Or, you can use the right parameters to execute a command, like in the following example:

```console
$ docker run s3cmd ls s3://mybucket
```

This is useful because the image name can double as a reference to the binary as shown in the command above.

The `ENTRYPOINT` instruction can also be used in combination with a helper script, allowing it to function in a similar way to the command above, even when starting the tool may require more than one step.

For example, the [Postgres Official Image](https://hub.docker.com/_/postgres/) uses the following script as its `ENTRYPOINT`:

```bash
#!/bin/sh
set -e

if [ "$1" = 'postgres' ]; then
    chown -R postgres "$PGDATA"

    if [ -z "$(ls -A "$PGDATA")" ]; then
        gosu postgres initdb
    fi

    exec gosu postgres "$@"
fi

exec "$@"
```

This script uses [the `exec` builtin](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#exec) so that the final running application becomes the container's PID 1. This allows the application to receive any Unix signals sent to the container. For more information, see the [`ENTRYPOINT` reference](https://docs.docker.com/reference/dockerfile/#entrypoint).

In the following example, a helper script is copied into the container and run via `ENTRYPOINT` on container start:

```dockerfile
COPY ./docker-entrypoint.sh /
ENTRYPOINT ["/docker-entrypoint.sh"]
CMD ["postgres"]
```

This script lets you interact with Postgres in several ways.

It can simply start Postgres:

```console
$ docker run postgres
```

Or, you can use it to run Postgres and pass parameters to the server:

```console
$ docker run postgres postgres --help
```

Lastly, you can use it to start a totally different tool, such as Bash:

```console
$ docker run --rm -it postgres bash
```

For more information about `ENTRYPOINT`, see [Dockerfile reference for the ENTRYPOINT instruction](https://docs.docker.com/reference/dockerfile/#entrypoint).

### [VOLUME](#volume)

You should use the `VOLUME` instruction to expose any database storage area, configuration storage, or files and folders created by your Docker container. You are strongly encouraged to use `VOLUME` for any combination of mutable or user-serviceable parts of your image.

For more information about `VOLUME`, see [Dockerfile reference for the VOLUME instruction](https://docs.docker.com/reference/dockerfile/#volume).

### [USER](#user)

If a service can run without privileges, use `USER` to change to a non-root user. Start by creating the user and group in the Dockerfile with something like the following example:

```dockerfile
RUN groupadd -r postgres && useradd --no-log-init -r -g postgres postgres
```

> Note
>
> Consider an explicit UID/GID.
>
> Users and groups in an image are assigned a non-deterministic UID/GID in that the "next" UID/GID is assigned regardless of image rebuilds. So, if it’s critical, you should assign an explicit UID/GID.

> Note
>
> Due to an [unresolved bug](https://github.com/golang/go/issues/13548) in the Go archive/tar package's handling of sparse files, attempting to create a user with a significantly large UID inside a Docker container can lead to disk exhaustion because `/var/log/faillog` in the container layer is filled with NULL (\0) characters. A workaround is to pass the `--no-log-init` flag to `useradd`. The Debian/Ubuntu `adduser` wrapper does not support this flag.

Avoid installing or using `sudo` as it has unpredictable TTY and signal-forwarding behavior that can cause problems. If you absolutely need functionality similar to `sudo`, such as initializing the daemon as `root` but running it as non-`root`, consider using [“gosu”](https://github.com/tianon/gosu).

Lastly, to reduce layers and complexity, avoid switching `USER` back and forth frequently.

For more information about `USER`, see [Dockerfile reference for the USER instruction](https://docs.docker.com/reference/dockerfile/#user).

### [WORKDIR](#workdir)

For clarity and reliability, you should always use absolute paths for your `WORKDIR`. Also, you should use `WORKDIR` instead of proliferating instructions like `RUN cd … && do-something`, which are hard to read, troubleshoot, and maintain.

For more information about `WORKDIR`, see [Dockerfile reference for the `WORKDIR` instruction](https://docs.docker.com/reference/dockerfile/#workdir).

### [ONBUILD](#onbuild)

An `ONBUILD` command executes after the current Dockerfile build completes. `ONBUILD` executes in any child image derived `FROM` the current image. Think of the `ONBUILD` command as an instruction that the parent Dockerfile gives to the child Dockerfile.

A Docker build executes `ONBUILD` commands before any command in a child Dockerfile.

`ONBUILD` is useful for images that are going to be built `FROM` a given image. For example, you would use `ONBUILD` for a language stack image that builds arbitrary user software written in that language within the Dockerfile, as you can see in [Ruby’s `ONBUILD` variants](https://github.com/docker-library/ruby/blob/c43fef8a60cea31eb9e7d960a076d633cb62ba8d/2.4/jessie/onbuild/Dockerfile).

Images built with `ONBUILD` should get a separate tag. For example, `ruby:1.9-onbuild` or `ruby:2.0-onbuild`.

Be careful when putting `ADD` or `COPY` in `ONBUILD`. The image fails catastrophically if the new build's context is missing the resource being added. Adding a separate tag, as recommended above, helps mitigate this by allowing the Dockerfile author to make a choice.

For more information about `ONBUILD`, see [Dockerfile reference for the ONBUILD instruction](https://docs.docker.com/reference/dockerfile/#onbuild).

----
url: https://docs.docker.com/guides/docker-scout/remediation/
----

# Remediation

***

***

Docker Scout's [remediation feature](https://docs.docker.com/scout/policy/remediation/) helps you address supply chain and security issues by offering tailored recommendations based on policy evaluations. These recommendations guide you in improving policy compliance or enhancing image metadata, allowing Docker Scout to perform more accurate evaluations in the future.

You can use this feature to ensure that your base images are up-to-date and that your supply chain attestations are complete. When a violation occurs, Docker Scout provides recommended fixes, such as updating your base image or adding missing attestations. If there isn’t enough information to determine compliance, Docker Scout suggests actions to help resolve the issue.

In the Docker Scout Dashboard, you can view and act on these recommendations by reviewing violations or compliance uncertainties. With integrations like GitHub, you can even automate updates, directly fixing issues from the dashboard.

[Common challenges and questions »](https://docs.docker.com/guides/docker-scout/common-questions/)

----
url: https://docs.docker.com/reference/build-checks/invalid-default-arg-in-from/
----

# InvalidDefaultArgInFrom

***

Table of contents

***

## [Output](#output)

```text
Using the global ARGs with default values should produce a valid build.
```

## [Description](#description)

An `ARG` used in an image reference should be valid when no build arguments are used. An image build should not require `--build-arg` to be used to produce a valid build.

## [Examples](#examples)

❌ Bad: don't rely on an ARG being set for an image reference to be valid

```dockerfile
ARG TAG
FROM busybox:${TAG}
```

✅ Good: include a default for the ARG

```dockerfile
ARG TAG=latest
FROM busybox:${TAG}
```

✅ Good: ARG can be empty if the image would be valid with it empty

```dockerfile
ARG VARIANT
FROM busybox:stable${VARIANT}
```

✅ Good: Use a default value if the build arg is not present

```dockerfile
ARG TAG
FROM alpine:${TAG:-3.14}
```

----
url: https://docs.docker.com/engine/logging/drivers/gcplogs/
----

# Google Cloud Logging driver

***

Table of contents

***

The Google Cloud Logging driver sends container logs to [Google Cloud Logging](https://cloud.google.com/logging/docs/) Logging.

## [Usage](#usage)

To use the `gcplogs` driver as the default logging driver, set the `log-driver` and `log-opt` keys to appropriate values in the `daemon.json` file. For more about configuring Docker using `daemon.json`, see [daemon.json](https://docs.docker.com/reference/cli/dockerd/#daemon-configuration-file).

> Note
>
> If you're using Docker Desktop, edit the daemon configuration through the Docker Desktop Dashboard. Open **Settings** and select **Docker Engine**. For details, see [Docker Engine settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/#docker-engine).

The following example sets the log driver to `gcplogs` and sets the `gcp-meta-name` option.

```json
{
  "log-driver": "gcplogs",
  "log-opts": {
    "gcp-meta-name": "example-instance-12345"
  }
}
```

Restart Docker for the changes to take effect.

You can set the logging driver for a specific container by using the `--log-driver` option to `docker run`:

```console
$ docker run --log-driver=gcplogs ...
```

If Docker detects that it's running in a Google Cloud Project, it discovers configuration from the [instance metadata service](https://cloud.google.com/compute/docs/metadata). Otherwise, the user must specify which project to log to using the `--gcp-project` log option and Docker attempts to obtain credentials from the [Google Application Default Credential](https://developers.google.com/identity/protocols/application-default-credentials). The `--gcp-project` flag takes precedence over information discovered from the metadata server, so a Docker daemon running in a Google Cloud project can be overridden to log to a different project using `--gcp-project`.

Docker fetches the values for zone, instance name and instance ID from Google Cloud metadata server. Those values can be provided via options if metadata server isn't available. They don't override the values from metadata server.

## [gcplogs options](#gcplogs-options)

You can use the `--log-opt NAME=VALUE` flag to specify these additional Google Cloud Logging driver options:

| Option          | Required | Description                                                                                                                                                                                       |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gcp-project`   | optional | Which Google Cloud project to log to. Defaults to discovering this value from the Google Cloud metadata server.                                                                                   |
| `gcp-log-cmd`   | optional | Whether to log the command that the container was started with. Defaults to false.                                                                                                                |
| `labels`        | optional | Comma-separated list of keys of labels, which should be included in message, if these labels are specified for the container.                                                                     |
| `labels-regex`  | optional | Similar to and compatible with `labels`. A regular expression to match logging-related labels. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/).             |
| `env`           | optional | Comma-separated list of keys of environment variables, which should be included in message, if these variables are specified for the container.                                                   |
| `env-regex`     | optional | Similar to and compatible with `env`. A regular expression to match logging-related environment variables. Used for advanced [log tag options](https://docs.docker.com/engine/logging/log_tags/). |
| `gcp-meta-zone` | optional | Zone name for the instance.                                                                                                                                                                       |
| `gcp-meta-name` | optional | Instance name.                                                                                                                                                                                    |
| `gcp-meta-id`   | optional | Instance ID.                                                                                                                                                                                      |

If there is collision between `label` and `env` keys, the value of the `env` takes precedence. Both options add additional fields to the attributes of a logging message.

The following is an example of the logging options required to log to the default logging destination which is discovered by querying the Google Cloud metadata server.

```console
$ docker run \
    --log-driver=gcplogs \
    --log-opt labels=location \
    --log-opt env=TEST \
    --log-opt gcp-log-cmd=true \
    --env "TEST=false" \
    --label location=west \
    your/application
```

This configuration also directs the driver to include in the payload the label `location`, the environment variable `ENV`, and the command used to start the container.

The following example shows logging options for running outside of Google Cloud. The `GOOGLE_APPLICATION_CREDENTIALS` environment variable must be set for the daemon, for example via systemd:

```ini
[Service]
Environment="GOOGLE_APPLICATION_CREDENTIALS=uQWVCPkMTI34bpssr1HI"
```

```console
$ docker run \
    --log-driver=gcplogs \
    --log-opt gcp-project=test-project \
    --log-opt gcp-meta-zone=west1 \
    --log-opt gcp-meta-name=`hostname` \
    your/application
```

----
url: https://docs.docker.com/reference/cli/docker/model/context/
----

# docker model context

***

| Description | Manage Docker Model Runner contexts |
| ----------- | ----------------------------------- |

## [Description](#description)

Manage Docker Model Runner contexts

## [Subcommands](#subcommands)

| Command                                                                                               | Description                                             |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| [`docker model context create`](https://docs.docker.com/reference/cli/docker/model/context/create/)   | Create a named Model Runner context                     |
| [`docker model context inspect`](https://docs.docker.com/reference/cli/docker/model/context/inspect/) | Display detailed information about one or more contexts |
| [`docker model context ls`](https://docs.docker.com/reference/cli/docker/model/context/ls/)           | List Model Runner contexts                              |
| [`docker model context rm`](https://docs.docker.com/reference/cli/docker/model/context/rm/)           | Remove one or more Model Runner contexts                |
| [`docker model context use`](https://docs.docker.com/reference/cli/docker/model/context/use/)         | Set the active Model Runner context                     |

----
url: https://docs.docker.com/guides/docker-scout/attestations/
----

# Attestations

***

***

[Build attestations](https://docs.docker.com/build/metadata/attestations/) give you detailed information about how an image was built and what it contains. These attestations, generated by BuildKit during build-time, attach to the final image as metadata, allowing you to inspect an image to see its origin, creator, and contents. This information helps you make informed decisions about the security and impact of the image on your supply chain.

Docker Scout uses these attestations to evaluate the image's security and supply chain posture, and to provide remediation recommendations for issues. If issues are detected, such as missing or outdated attestations, Docker Scout can guide you on how to add or update them, ensuring compliance and improving visibility into the image's security status.

There are two key types of attestations:

* SBOM, which lists the software artifacts within the image.
* Provenance, which details how the image was built.

You can create attestations by using `docker buildx build` with the `--provenance` and `--sbom` flags. Attestations attach to the image index, allowing you to inspect them without pulling the entire image. Docker Scout leverages this metadata to give you more precise recommendations and better control over your image's security.

[Remediation »](https://docs.docker.com/guides/docker-scout/remediation/)

----
url: https://docs.docker.com/build/ci/github-actions/attestations/
----

# Add SBOM and provenance attestations with GitHub Actions

***

Table of contents

***

Software Bill of Material (SBOM) and provenance [attestations](https://docs.docker.com/build/metadata/attestations/) add metadata about the contents of your image, and how it was built.

Attestations are supported with version 4 and later of the `docker/build-push-action`.

## [Default provenance](#default-provenance)

The `docker/build-push-action` GitHub Action automatically adds provenance attestations to your image, with the following conditions:

* If the GitHub repository is public, provenance attestations with `mode=max` are automatically added to the image.
* If the GitHub repository is private, provenance attestations with `mode=min` are automatically added to the image.
* If you're using the [`docker` exporter](https://docs.docker.com/build/exporters/oci-docker/), or you're loading the build results to the runner with `load: true`, no attestations are added to the image. These output formats don't support attestations.

> Warning
>
> If you're using `docker/build-push-action` to build images for code in a public GitHub repository, the provenance attestations attached to your image by default contains the values of build arguments. If you're misusing build arguments to pass secrets to your build, such as user credentials or authentication tokens, those secrets are exposed in the provenance attestation. Refactor your build to pass those secrets using [secret mounts](/reference/cli/docker/buildx/build/#secret) instead. Also remember to rotate any secrets you may have exposed.

## [Max-level provenance](#max-level-provenance)

It's recommended that you build your images with max-level provenance attestations. Private repositories only add min-level provenance by default, but you can manually override the provenance level by setting the `provenance` input on the `docker/build-push-action` GitHub Action to `mode=max`.

Note that adding attestations to an image means you must push the image to a registry directly, as opposed to loading the image to the local image store of the runner. This is because the local image store doesn't support loading images with attestations.

```yaml
name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.IMAGE_NAME }}

      - name: Build and push image
        uses: docker/build-push-action@v7
        with:
          push: true
          provenance: mode=max
          tags: ${{ steps.meta.outputs.tags }}
```

## [SBOM](#sbom)

SBOM attestations aren't automatically added to the image. To add SBOM attestations, set the `sbom` input of the `docker/build-push-action` to true.

Note that adding attestations to an image means you must push the image to a registry directly, as opposed to loading the image to the local image store of the runner. This is because the local image store doesn't support loading images with attestations.

```yaml
name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.IMAGE_NAME }}

      - name: Build and push image
        uses: docker/build-push-action@v7
        with:
          sbom: true
          push: true
          tags: ${{ steps.meta.outputs.tags }}
```

----
url: https://docs.docker.com/engine/release-notes/17.04/
----

# Docker Engine 17.04 release notes

***

Table of contents

***

## [17.04.0-ce](#17040-ce)

2017-04-05

### [Builder](#builder)

* Disable container logging for build containers [#29552](https://github.com/docker/docker/pull/29552)
* Fix use of `**/` in `.dockerignore` [#29043](https://github.com/docker/docker/pull/29043)

### [Client](#client)

* Sort `docker stack ls` by name [#31085](https://github.com/docker/docker/pull/31085)
* Flags for specifying bind mount consistency [#31047](https://github.com/docker/docker/pull/31047)

- Output of docker CLI --help is now wrapped to the terminal width [#28751](https://github.com/docker/docker/pull/28751)
- Suppress image digest in docker ps [#30848](https://github.com/docker/docker/pull/30848)
- Hide command options that are related to Windows [#30788](https://github.com/docker/docker/pull/30788)
- Fix `docker plugin install` prompt to accept "enter" for the "N" default [#30769](https://github.com/docker/docker/pull/30769)

* Add `truncate` function for Go templates [#30484](https://github.com/docker/docker/pull/30484)

- Support expanded syntax of ports in `stack deploy` [#30476](https://github.com/docker/docker/pull/30476)
- Support expanded syntax of mounts in `stack deploy` [#30597](https://github.com/docker/docker/pull/30597) [#31795](https://github.com/docker/docker/pull/31795)

* Add `--add-host` for docker build [#30383](https://github.com/docker/docker/pull/30383)
* Add `.CreatedAt` placeholder for `docker network ls --format` [#29900](https://github.com/docker/docker/pull/29900)

- Update order of `--secret-rm` and `--secret-add` [#29802](https://github.com/docker/docker/pull/29802)

* Add `--filter enabled=true` for `docker plugin ls` [#28627](https://github.com/docker/docker/pull/28627)
* Add `--format` to `docker service ls` [#28199](https://github.com/docker/docker/pull/28199)
* Add `publish` and `expose` filter for `docker ps --filter` [#27557](https://github.com/docker/docker/pull/27557)

- Support multiple service IDs on `docker service ps` [#25234](https://github.com/docker/docker/pull/25234)

* Allow swarm join with `--availability=drain` [#24993](https://github.com/docker/docker/pull/24993)

- Docker inspect now shows "docker-default" when AppArmor is enabled and no other profile was defined [#27083](https://github.com/docker/docker/pull/27083)

### [Logging](#logging)

* Implement optional ring buffer for container logs [#28762](https://github.com/docker/docker/pull/28762)
* Add `--log-opt awslogs-create-group=<true|false>` for awslogs (CloudWatch) to support creation of log groups as needed [#29504](https://github.com/docker/docker/pull/29504)

- Fix segfault when using the gcplogs logging driver with a "static" binary [#29478](https://github.com/docker/docker/pull/29478)

### [Networking](#networking)

* Check parameter `--ip`, `--ip6` and `--link-local-ip` in `docker network connect` [#30807](https://github.com/docker/docker/pull/30807)

- Added support for `dns-search` [#30117](https://github.com/docker/docker/pull/30117)
- Added --verbose option for docker network inspect to show task details from all swarm nodes [#31710](https://github.com/docker/docker/pull/31710)

* Clear stale datapath encryption states when joining the cluster [docker/libnetwork#1354](https://github.com/docker/libnetwork/pull/1354)

- Ensure iptables initialization only happens once [docker/libnetwork#1676](https://github.com/docker/libnetwork/pull/1676)

* Fix bad order of iptables filter rules [docker/libnetwork#961](https://github.com/docker/libnetwork/pull/961)

- Add anonymous container alias to service record on attachable network [docker/libnetwork#1651](https://github.com/docker/libnetwork/pull/1651)
- Support for `com.docker.network.container_iface_prefix` driver label [docker/libnetwork#1667](https://github.com/docker/libnetwork/pull/1667)
- Improve network list performance by omitting network details that are not used [#30673](https://github.com/docker/docker/pull/30673)

### [Runtime](#runtime)

* Handle paused container when restoring without live-restore set [#31704](https://github.com/docker/docker/pull/31704)

- Do not allow sub second in healthcheck options in Dockerfile [#31177](https://github.com/docker/docker/pull/31177)

* Support name and id prefix in `secret update` [#30856](https://github.com/docker/docker/pull/30856)
* Use binary frame for websocket attach endpoint [#30460](https://github.com/docker/docker/pull/30460)
* Fix linux mount calls not applying propagation type changes [#30416](https://github.com/docker/docker/pull/30416)
* Fix ExecIds leak on failed `exec -i` [#30340](https://github.com/docker/docker/pull/30340)
* Prune named but untagged images if `danglingOnly=true` [#30330](https://github.com/docker/docker/pull/30330)

- Add daemon flag to set `no_new_priv` as default for unprivileged containers [#29984](https://github.com/docker/docker/pull/29984)
- Add daemon option `--default-shm-size` [#29692](https://github.com/docker/docker/pull/29692)
- Support registry mirror config reload [#29650](https://github.com/docker/docker/pull/29650)

* Ignore the daemon log config when building images [#29552](https://github.com/docker/docker/pull/29552)

- Move secret name or ID prefix resolving from client to daemon [#29218](https://github.com/docker/docker/pull/29218)

* Allow adding rules to `cgroup devices.allow` on container create/run [#22563](https://github.com/docker/docker/pull/22563)

- Fix `cpu.cfs_quota_us` being reset when running `systemd daemon-reload` [#31736](https://github.com/docker/docker/pull/31736)

### [Swarm Mode](#swarm-mode)

* Topology-aware scheduling [#30725](https://github.com/docker/docker/pull/30725)
* Automatic service rollback on failure [#31108](https://github.com/docker/docker/pull/31108)
* Worker and manager on the same node are now connected through a UNIX socket [docker/swarmkit#1828](https://github.com/docker/swarmkit/pull/1828), [docker/swarmkit#1850](https://github.com/docker/swarmkit/pull/1850), [docker/swarmkit#1851](https://github.com/docker/swarmkit/pull/1851)

- Improve raft transport package [docker/swarmkit#1748](https://github.com/docker/swarmkit/pull/1748)
- No automatic manager shutdown on demotion/removal [docker/swarmkit#1829](https://github.com/docker/swarmkit/pull/1829)
- Use TransferLeadership to make leader demotion safer [docker/swarmkit#1939](https://github.com/docker/swarmkit/pull/1939)
- Decrease default monitoring period [docker/swarmkit#1967](https://github.com/docker/swarmkit/pull/1967)

* Add Service logs formatting [#31672](https://github.com/docker/docker/pull/31672)

- Fix service logs API to be able to specify stream [#31313](https://github.com/docker/docker/pull/31313)

* Add `--stop-signal` for `service create` and `service update` [#30754](https://github.com/docker/docker/pull/30754)
* Add `--read-only` for `service create` and `service update` [#30162](https://github.com/docker/docker/pull/30162)
* Renew the context after communicating with the registry [#31586](https://github.com/docker/docker/pull/31586)
* (experimental) Add `--tail` and `--since` options to `docker service logs` [#31500](https://github.com/docker/docker/pull/31500)
* (experimental) Add `--no-task-ids` and `--no-trunc` options to `docker service logs` [#31672](https://github.com/docker/docker/pull/31672)

### [Windows](#windows)

* Block pulling Windows images on non-Windows daemons [#29001](https://github.com/docker/docker/pull/29001)

----
url: https://docs.docker.com/docker-hub/repos/manage/trusted-content/
----

***

***

Docker's trusted content programs ensure that container images meet the highest standards for security, quality, and reliability. These programs provide opportunities for publishers and contributors to share their images with millions of developers worldwide while gaining valuable insights into their content's usage. By participating, you can enhance your content's visibility, build credibility, and access tools to optimize its impact within the container ecosystem.

In this section, learn about:

* [Docker Official Images](https://docs.docker.com/docker-hub/repos/manage/trusted-content/official-images/): Learn how to contribute, propose, and maintain Docker Official Images to serve as reliable foundations for containerized applications.
* [Docker-Sponsored Open Source (DSOS) Program](https://docs.docker.com/docker-hub/repos/manage/trusted-content/dsos-program/): Discover how open source projects can gain perks like verified badges, insights, and access to Docker Scout, enhancing visibility and trust on Docker Hub.
* [Docker Verified Publisher (DVP) Program](https://docs.docker.com/docker-hub/repos/manage/trusted-content/dvp-program/): Explore how to join the DVP program to showcase trusted, high-quality images with a verified badge, gain priority in search results, access insights, and enhance security through vulnerability analysis.
* [Insights and analytics](https://docs.docker.com/docker-hub/repos/manage/trusted-content/insights-analytics/): Access detailed metrics on image and extension usage, including pull counts, geolocation, and client data, to understand user behavior and optimize your content.

For Docker Hardened Images guidance, including how to contribute, see [Contribute to the catalog](/dhi/how-to/build/#contribute-to-the-catalog) in the dedicated DHI docs section.

----
url: https://docs.docker.com/reference/samples/pi-hole/
----

# Pi-hole samples

| Name                                                                                                  | Description                                                 |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [Pi-hole / cloudflared](https://github.com/docker/awesome-compose/tree/master/pihole-cloudflared-DoH) | A sample Pi-hole setup with use of DoH cloudflared service. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/desktop/setup/install/mac-permission-requirements/
----

# Understand permission requirements for Docker Desktop on Mac

***

Table of contents

***

This page contains information about the permission requirements for running and installing Docker Desktop on Mac.

It also provides clarity on running containers as `root` as opposed to having `root` access on the host.

Docker Desktop on Mac is designed with security in mind. Administrative rights are only required when absolutely necessary.

## [Permission requirements](#permission-requirements)

Docker Desktop for Mac is run as an unprivileged user. However, Docker Desktop requires certain functionalities to perform a limited set of privileged configurations such as:

* [Installing symlinks](#installing-symlinks) in`/usr/local/bin`.
* [Binding privileged ports](#binding-privileged-ports) that are less than 1024. Although privileged ports (ports below 1024) are not typically used as a security boundary, operating systems still prevent unprivileged processes from binding to them which breaks commands like `docker run -p 127.0.0.1:80:80 docker/getting-started`.
* [Ensuring `localhost` and `kubernetes.docker.internal` are defined](#ensuring-localhost-and-kubernetesdockerinternal-are-defined) in `/etc/hosts`. Some old macOS installs don't have `localhost` in `/etc/hosts`, which causes Docker to fail. Defining the DNS name `kubernetes.docker.internal` allows Docker to share Kubernetes contexts with containers.
* Securely caching the Registry Access Management policy which is read-only for the developer.

Privileged access is granted during installation.

The first time Docker Desktop for Mac launches, it presents an installation window where you can choose to either use the default settings, which work for most developers and requires you to grant privileged access, or use advanced settings.

If you work in an environment with elevated security requirements, for instance where local administrative access is prohibited, then you can use the advanced settings to remove the need for granting privileged access. You can configure:

* The location of the Docker CLI tools either in the system or user directory
* The default Docker socket
* Privileged port mapping

Depending on which advanced settings you configure, you must enter your password to confirm.

You can change these configurations at a later date from the **Advanced** page in **Settings**.

### [Installing symlinks](#installing-symlinks)

The Docker binaries are installed by default in `/Applications/Docker.app/Contents/Resources/bin`. Docker Desktop creates symlinks for the binaries in `/usr/local/bin`, which means they're automatically included in `PATH` on most systems.

You can choose whether to install symlinks either in `/usr/local/bin` or `$HOME/.docker/bin` during installation of Docker Desktop.

If `/usr/local/bin` is chosen, and this location is not writable by unprivileged users, Docker Desktop requires authorization to confirm this choice before the symlinks to Docker binaries are created in `/usr/local/bin`. If `$HOME/.docker/bin` is chosen, authorization is not required, but then you must [manually add `$HOME/.docker/bin`](https://docs.docker.com/desktop/settings-and-maintenance/settings/#advanced) to your PATH.

You are also given the option to enable the installation of the `/var/run/docker.sock` symlink. Creating this symlink ensures various Docker clients relying on the default Docker socket path work without additional changes.

As the `/var/run` is mounted as a tmpfs, its content is deleted on restart, symlink to the Docker socket included. To ensure the Docker socket exists after restart, Docker Desktop sets up a `launchd` startup task that creates the symlink by running `ln -s -f /Users/<user>/.docker/run/docker.sock /var/run/docker.sock`. This ensures the you aren't prompted on each startup to create the symlink. If you don't enable this option at installation, the symlink and the startup task is not created and you may have to explicitly set the `DOCKER_HOST` environment variable to `/Users/<user>/.docker/run/docker.sock` in the clients it is using. The Docker CLI relies on the current context to retrieve the socket path, the current context is set to `desktop-linux` on Docker Desktop startup.

### [Binding privileged ports](#binding-privileged-ports)

You can choose to enable privileged port mapping during installation, or from the **Advanced** page in **Settings** post-installation. Docker Desktop requires authorization to confirm this choice.

### [Ensuring `localhost` and `kubernetes.docker.internal` are defined](#ensuring-localhost-and-kubernetesdockerinternal-are-defined)

It is your responsibility to ensure that localhost is resolved to `127.0.0.1` and if Kubernetes is used, that `kubernetes.docker.internal` is resolved to `127.0.0.1`.

## [Installing from the command line](#installing-from-the-command-line)

Privileged configurations are applied during the installation with the `--user` flag on the [install command](https://docs.docker.com/desktop/setup/install/mac-install/#install-from-the-command-line). In this case, you are not prompted to grant root privileges on the first run of Docker Desktop. Specifically, the `--user` flag:

* Uninstalls the previous `com.docker.vmnetd` if present
* Sets up symlinks
* Ensures that `localhost` is resolved to `127.0.0.1`

The limitation of this approach is that Docker Desktop can only be run by one user-account per machine, namely the one specified in the `-–user` flag.

## [Privileged helper](#privileged-helper)

In the limited situations when the privileged helper is needed, for example binding privileged ports or caching the Registry Access Management policy, the privileged helper is started by `launchd` and runs in the background unless it is disabled at runtime as previously described. The Docker Desktop backend communicates with the privileged helper over the UNIX domain socket `/var/run/com.docker.vmnetd.sock`. The functionalities it performs are:

* Binding privileged ports that are less than 1024.
* Securely caching the Registry Access Management policy which is read-only for the developer.
* Uninstalling the privileged helper.

The removal of the privileged helper process is done in the same way as removing `launchd` processes.

```console
$ ps aux | grep vmnetd
root             28739   0.0  0.0 34859128    228   ??  Ss    6:03PM   0:00.06 /Library/PrivilegedHelperTools/com.docker.vmnetd
user             32222   0.0  0.0 34122828    808 s000  R+   12:55PM   0:00.00 grep vmnetd

$ sudo launchctl unload -w /Library/LaunchDaemons/com.docker.vmnetd.plist
Password:

$ ps aux | grep vmnetd
user             32242   0.0  0.0 34122828    716 s000  R+   12:55PM   0:00.00 grep vmnetd

$ rm /Library/LaunchDaemons/com.docker.vmnetd.plist

$ rm /Library/PrivilegedHelperTools/com.docker.vmnetd
```

## [Containers running as root within the Linux VM](#containers-running-as-root-within-the-linux-vm)

With Docker Desktop, the Docker daemon and containers run in a lightweight Linux VM managed by Docker. This means that although containers run by default as `root`, this doesn't grant `root` access to the Mac host machine. The Linux VM serves as a security boundary and limits what resources can be accessed from the host. Any directories from the host bind mounted into Docker containers still retain their original permissions.

## [Enhanced Container Isolation](#enhanced-container-isolation)

In addition, Docker Desktop supports [Enhanced Container Isolation mode](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/) (ECI), available to Business customers only, which further secures containers without impacting developer workflows.

ECI automatically runs all containers within a Linux user-namespace, such that root in the container is mapped to an unprivileged user inside the Docker Desktop VM. ECI uses this and other advanced techniques to further secure containers within the Docker Desktop Linux VM, such that they are further isolated from the Docker daemon and other services running inside the VM.

----
url: https://docs.docker.com/extensions/non-marketplace/
----

# Non-marketplace extensions

***

Table of contents

***

## [Install an extension not available in the Marketplace](#install-an-extension-not-available-in-the-marketplace)

> Warning
>
> Extensions installed outside the Marketplace have not gone through Docker's review process. Like all Docker extensions, they run with host-level privileges. They can install binaries, access Docker Engine, invoke commands, and access files on your machine. Install only if you trust the publisher and have verified the source.

The Extensions Marketplace is the trusted and official place to install extensions from within Docker Desktop. These extensions have gone through a review process by Docker. However, other extensions can also be installed in Docker Desktop if you trust the extension author.

Given the nature of a Docker Extension (i.e. a Docker image) you can find other places where users have their extension's source code published. For example on GitHub, GitLab or even hosted in image registries like DockerHub or GHCR. You can install an extension that has been developed by the community or internally at your company from a teammate. You are not limited to installing extensions just from the Marketplace.

> Note
>
> Ensure the option **Allow only extensions distributed through the Docker Marketplace** is disabled. Otherwise, this prevents any extension not listed in the Marketplace, via the Extension SDK tools from, being installed. You can change this option in **Settings**.

To install an extension which is not present in the Marketplace, you can use the Extensions CLI that is bundled with Docker Desktop.

In a terminal, type `docker extension install IMAGE[:TAG]` to install an extension by its image reference and optionally a tag. Use the `-f` or `--force` flag to avoid interactive confirmation.

Go to the Docker Desktop Dashboard to see the new extension installed.

## [List installed extensions](#list-installed-extensions)

Regardless whether the extension was installed from the Marketplace or manually by using the Extensions CLI, you can use the `docker extension ls` command to display the list of extensions installed. As part of the output you'll see the extension ID, the provider, version, the title and whether it runs a backend container or has deployed binaries to the host, for example:

```console
$ docker extension ls
ID                  PROVIDER            VERSION             UI                    VM                  HOST
john/my-extension   John                latest              1 tab(My-Extension)   Running(1)          -
```

Go to the Docker Desktop Dashboard, select **Add Extensions** and on the **Managed** tab to see the new extension installed. Notice that an `UNPUBLISHED` label displays which indicates that the extension has not been installed from the Marketplace.

## [Update an extension](#update-an-extension)

To update an extension which isn't present in the Marketplace, in a terminal type `docker extension update IMAGE[:TAG]` where the `TAG` should be different from the extension that's already installed.

For instance, if you installed an extension with `docker extension install john/my-extension:0.0.1`, you can update it by running `docker extension update john/my-extension:0.0.2`. Go to the Docker Desktop Dashboard to see the new extension updated.

> Note
>
> Extensions that aren't installed through the Marketplace don't receive update notifications from Docker Desktop.

## [Uninstall an extension](#uninstall-an-extension)

To uninstall an extension which is not present in the Marketplace, you can either navigate to the **Managed** tab in the Marketplace and select the **Uninstall** button, or from a terminal type `docker extension uninstall IMAGE[:TAG]`.

----
url: https://docs.docker.com/reference/cli/sbx/create/opencode/
----

# sbx create opencode

| Description | Create a sandbox for opencode                |
| ----------- | -------------------------------------------- |
| Usage       | `sbx create opencode PATH [PATH...] [flags]` |

## [Description](#description)

Create a sandbox with access to a host workspace for opencode.

The workspace path is required and will be mounted inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Global options](#global-options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `-D, --debug`    |         | Enable debug logging                                                                                                                                                                                                   |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Examples](#examples)

```console
# Create in the current directory
sbx create opencode .

# Create with a specific path
sbx create opencode /path/to/project

# Create with additional read-only workspaces
sbx create opencode . /path/to/docs:ro
```

----
url: https://docs.docker.com/guides/php/containerize/
----

# Containerize a PHP application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/).
* You have a [git client](https://git-scm.com/downloads). The examples in this section use a command-line based git client, but you can use any client.

## [Overview](#overview)

This section walks you through containerizing and running a PHP application.

## [Get the sample applications](#get-the-sample-applications)

In this guide, you will use a pre-built PHP application. The application uses Composer for library dependency management. You'll serve the application via an Apache web server.

Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository.

```console
$ git clone https://github.com/docker/docker-php-sample
```

The sample application is a basic hello world application and an application that increments a counter in a database. In addition, the application uses PHPUnit for testing.

## [Create Docker assets](#create-docker-assets)

Now that you have an application, you can create the necessary Docker assets to containerize it.

> Tip
>
> [Gordon](/ai/gordon/), Docker's AI assistant, can generate Docker assets for your project. Ask Gordon to create a Dockerfile, Compose file, and `.dockerignore` tailored to your application.

Create the following files in your `docker-php-sample` directory.

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1

# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Dockerfile reference guide at
# https://docs.docker.com/go/dockerfile-reference/

################################################################################

# Create a stage for installing app dependencies defined in Composer.
FROM composer:lts as deps

WORKDIR /app

# If your composer.json file defines scripts that run during dependency installation and
# reference your application source files, uncomment the line below to copy all the files
# into this layer.
# COPY . .

# Download dependencies as a separate step to take advantage of Docker's caching.
# Leverage a bind mounts to composer.json and composer.lock to avoid having to copy them
# into this layer.
# Leverage a cache mount to /tmp/cache so that subsequent builds don't have to re-download packages.
RUN --mount=type=bind,source=composer.json,target=composer.json \
    --mount=type=bind,source=composer.lock,target=composer.lock \
    --mount=type=cache,target=/tmp/cache \
    composer install --no-dev --no-interaction

################################################################################

# Create a new stage for running the application that contains the minimal
# runtime dependencies for the application. This often uses a different base
# image from the install or build stage where the necessary files are copied
# from the install stage.
#
# The example below uses the PHP Apache image as the foundation for running the app.
# By specifying the "8.2-apache" tag, it will also use whatever happens to be the
# most recent version of that tag when you build your Dockerfile.
# If reproducibility is important, consider using a specific digest SHA, like
# php@sha256:99cede493dfd88720b610eb8077c8688d3cca50003d76d1d539b0efc8cca72b4.
FROM php:8.2-apache as final

# Your PHP application may require additional PHP extensions to be installed
# manually. For detailed instructions for installing extensions can be found, see
# https://github.com/docker-library/docs/tree/master/php#how-to-install-more-php-extensions
# The following code blocks provide examples that you can edit and use.
#
# Add core PHP extensions, see
# https://github.com/docker-library/docs/tree/master/php#php-core-extensions
# This example adds the apt packages for the 'gd' extension's dependencies and then
# installs the 'gd' extension. For additional tips on running apt-get, see
# https://docs.docker.com/go/dockerfile-aptget-best-practices/
# RUN apt-get update && apt-get install -y \
#     libfreetype-dev \
#     libjpeg62-turbo-dev \
#     libpng-dev \
# && rm -rf /var/lib/apt/lists/* \
#     && docker-php-ext-configure gd --with-freetype --with-jpeg \
#     && docker-php-ext-install -j$(nproc) gd
#
# Add PECL extensions, see
# https://github.com/docker-library/docs/tree/master/php#pecl-extensions
# This example adds the 'redis' and 'xdebug' extensions.
# RUN pecl install redis-5.3.7 \
#    && pecl install xdebug-3.2.1 \
#    && docker-php-ext-enable redis xdebug

# Use the default production configuration for PHP runtime arguments, see
# https://github.com/docker-library/docs/tree/master/php#configuration
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"

# Copy the app dependencies from the previous install stage.
COPY --from=deps app/vendor/ /var/www/html/vendor
# Copy the app files from the app directory.
COPY ./src /var/www/html

# Switch to a non-privileged user (defined in the base image) that the app will run under.
# See https://docs.docker.com/go/dockerfile-user-best-practices/
USER www-data
```

compose.yaml

```yaml
# Comments are provided throughout this file to help you get started.
# If you need more help, visit the Docker Compose reference guide at
# https://docs.docker.com/go/compose-spec-reference/

# Here the instructions define your application as a service called "server".
# This service is built from the Dockerfile in the current directory.
# You can add other services your application may depend on here, such as a
# database or a cache. For examples, see the Awesome Compose repository:
# https://github.com/docker/awesome-compose
services:
  server:
    build:
      context: .
    ports:
      - 9000:80

# The commented out section below is an example of how to define a PostgreSQL
# database that your application can use. `depends_on` tells Docker Compose to
# start the database before your application. The `db-data` volume persists the
# database data between container restarts. The `db-password` secret is used
# to set the database password. You must create `db/password.txt` and add
# a password of your choosing to it before running `docker compose up`.
#     depends_on:
#       db:
#         condition: service_healthy
#   db:
#     image: postgres
#     restart: always
#     user: postgres
#     secrets:
#       - db-password
#     volumes:
#       - db-data:/var/lib/postgresql/data
#     environment:
#       - POSTGRES_DB=example
#       - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
#     expose:
#       - 5432
#     healthcheck:
#       test: [ "CMD", "pg_isready" ]
#       interval: 10s
#       timeout: 5s
#       retries: 5
# volumes:
#   db-data:
# secrets:
#   db-password:
#     file: db/password.txt
```

.dockerignore

```text
# Include any files or directories that you don't want to be copied to your
# container here (e.g., local build artifacts, temporary files, etc.).
#
# For more help, visit the .dockerignore file reference guide at
# https://docs.docker.com/go/build-context-dockerignore/

**/.classpath
**/.dockerignore
**/.env
**/.git
**/.gitignore
**/.project
**/.settings
**/.toolstarget
**/.vs
**/.vscode
**/.next
**/.cache
**/*.*proj.user
**/*.dbmdl
**/*.jfm
**/charts
**/docker-compose*
**/compose.y*ml
!**/composer.json
!**/composer.lock
**/Dockerfile*
**/node_modules
**/npm-debug.log
**/obj
**/secrets.dev.yaml
**/values.dev.yaml
**/vendor
LICENSE
README.md
```

You should now have the following contents in your `docker-php-sample` directory.

```text
├── docker-php-sample/
│ ├── .git/
│ ├── src/
│ ├── tests/
│ ├── .dockerignore
│ ├── .gitignore
│ ├── compose.yaml
│ ├── composer.json
│ ├── composer.lock
│ ├── Dockerfile
│ └── README.md
```

To learn more about these files, see the following:

* [Dockerfile](https://docs.docker.com/reference/dockerfile/)
* [.dockerignore](https://docs.docker.com/reference/dockerfile/#dockerignore-file)
* [compose.yaml](https://docs.docker.com/reference/compose-file/)

## [Run the application](#run-the-application)

Inside the `docker-php-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:9000/hello.php>. You should see a simple hello world application.

In the terminal, press `ctrl`+`c` to stop the application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `docker-php-sample` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:9000/hello.php>. You should see a simple hello world application.

In the terminal, run the following command to stop the application.

```console
$ docker compose down
```

For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

## [Summary](#summary)

In this section, you learned how you can containerize and run a simple PHP application using Docker.

## [Next steps](#next-steps)

In the next section, you'll learn how you can develop your application using Docker containers.

[Use containers for PHP development »](https://docs.docker.com/guides/php/develop/)

----
url: https://docs.docker.com/ai/sandboxes/agents/codex/
----

# Codex

***

Table of contents

***

This guide covers authentication, configuration, and usage of Codex in a sandboxed environment.

Official documentation: [Codex CLI](https://developers.openai.com/codex/cli)

## [Quick start](#quick-start)

Create a sandbox and run Codex for a project directory:

```console
$ sbx run codex ~/my-project
```

The workspace parameter is optional and defaults to the current directory:

```console
$ cd ~/my-project
$ sbx run codex
```

## [Authentication](#authentication)

Codex supports two authentication methods: an API key or OAuth.

**API key**: Store your OpenAI API key using [stored secrets](https://docs.docker.com/ai/sandboxes/security/credentials/#stored-secrets):

```console
$ sbx secret set -g openai
```

Alternatively, export the `OPENAI_API_KEY` environment variable in your shell before running the sandbox.

**OAuth**: If you prefer not to use an API key, start the OAuth flow on your host with:

```console
$ sbx secret set -g openai --oauth
```

This opens a browser window for authentication and stores the resulting tokens in your OS keychain. The OAuth flow runs on the host, not inside the sandbox, so browser-based authentication works without any extra setup.

See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for more details.

## [Configuration](#configuration)

Sandboxes don't pick up user-level configuration from your host, such as `~/.codex`. Only project-level configuration in the working directory is available inside the sandbox. See [Why doesn't the sandbox use my user-level agent configuration?](https://docs.docker.com/ai/sandboxes/faq/#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for workarounds.

### [Default startup command](#default-startup-command)

Without extra args, the sandbox runs:

```text
codex --dangerously-bypass-approvals-and-sandbox
```

Args after `--` replace these defaults rather than being appended. To keep the flag, include it yourself:

```console
$ sbx run codex -- --dangerously-bypass-approvals-and-sandbox "fix the build"
```

## [Base image](#base-image)

Template: `docker/sandbox-templates:codex`

----
url: https://docs.docker.com/billing/cycle/
----

# Change your billing cycle

***

Table of contents

***

You can choose between a monthly or annual billing cycle when purchasing a subscription. If you have a monthly billing cycle, you can choose to switch to an annual billing cycle.

If you're on a monthly plan, you can switch to a yearly plan at any time. However, switching from a yearly to a monthly cycle isn't supported.

When you change your billing cycle:

* Your next billing date reflects the new cycle. To find your next billing date, see [View renewal date](https://docs.docker.com/billing/history/#view-renewal-date).
* Your subscription's start date resets. For example, if the monthly subscription started on March 1 and ended on April 1, switching the billing duration on March 15, 2024, resets the new start date to March 15, 2024, with an end date of March 15, 2025.
* Any unused portion of your monthly subscription is prorated and applied as credit toward an annual subscription. For example, if your monthly cost is $10 and you're used value is $5, when you switch to an annual cycle ($100), the final charge is $95 ($100-$5).

## [Change personal account to an annual cycle](#change-personal-account-to-an-annual-cycle)

Pay by invoice is not available for subscription upgrades or changes.

To change your billing cycle:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Billing**.
3. On the plans and usage page, select **Switch to annual billing**.
4. Verify your billing information.
5. Select **Continue to payment**.
6. Verify payment information and select **Upgrade subscription**. If you choose to pay using a US bank account, you must verify the account. For more information, see [Verify a bank account](https://docs.docker.com/billing/payment-method/#verify-a-bank-account).

The billing plans and usage page will now reflect your new annual plan details.

## [Change organization to an annual cycle](#change-organization-to-an-annual-cycle)

You must be an organization owner to make changes to the payment information.

Pay by invoice is not available for subscription upgrades or changes.

Follow these steps to switch from a monthly to annual billing cycle for your organization's Docker subscription:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Billing**.
3. On the plans and usage page, select **Switch to annual billing**.
4. Verify your billing information.
5. Select **Continue to payment**.
6. Verify payment information and select **Upgrade subscription**. If you choose to pay using a US bank account, you must verify the account. For more information, see [Verify a bank account](https://docs.docker.com/billing/payment-method/#verify-a-bank-account).

----
url: https://docs.docker.com/reference/cli/docker/secret/
----

# docker secret

***

| Description | Manage Swarm secrets |
| ----------- | -------------------- |
| Usage       | `docker secret`      |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Manage secrets.

## [Subcommands](#subcommands)

| Command                                                                                 | Description                                         |
| --------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [`docker secret create`](https://docs.docker.com/reference/cli/docker/secret/create/)   | Create a secret from a file or STDIN as content     |
| [`docker secret inspect`](https://docs.docker.com/reference/cli/docker/secret/inspect/) | Display detailed information on one or more secrets |
| [`docker secret ls`](https://docs.docker.com/reference/cli/docker/secret/ls/)           | List secrets                                        |
| [`docker secret rm`](https://docs.docker.com/reference/cli/docker/secret/rm/)           | Remove one or more secrets                          |

----
url: https://docs.docker.com/guides/angular/run-tests/
----

# Run Angular tests in a container

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize Angular application](https://docs.docker.com/guides/angular/containerize/).

## [Overview](#overview)

Testing is a critical part of the development process. In this section, you'll learn how to:

* Run Jasmine unit tests using the Angular CLI inside a Docker container.
* Use Docker Compose to isolate your test environment.
* Ensure consistency between local and container-based testing.

The `docker-angular-sample` project comes pre-configured with Jasmine, so you can get started quickly without extra setup.

***

## [Run tests during development](#run-tests-during-development)

The `docker-angular-sample` application includes a sample test file at the following location:

```console
$ src/app/app.component.spec.ts
```

This test uses Jasmine to validate the AppComponent logic.

### [Step 1: Update compose.yaml](#step-1-update-composeyaml)

Add a new service named `angular-test` to your `compose.yaml` file. This service allows you to run your test suite in an isolated, containerized environment.

|                                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```
``` | ```yaml
services:
  angular-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "5173:5173"
    develop:
      watch:
        - action: sync
          path: .
          target: /app

  angular-prod:
    build:
      context: .
      dockerfile: Dockerfile
    image: docker-angular-sample
    ports:
      - "8080:8080"

  angular-test:
    build:
      context: .
      dockerfile: Dockerfile.dev
    command: ["npm", "run", "test"]
``` |

The angular-test service reuses the same `Dockerfile.dev` used for [development](https://docs.docker.com/guides/angular/develop/) and overrides the default command to run tests with `npm run test`. This setup ensures a consistent test environment that matches your local development configuration.

After completing the previous steps, your project directory should contain the following files:

```text
├── docker-angular-sample/
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ ├── .dockerignore
│ ├── compose.yaml
│ └── nginx.conf
```

### [Step 2: Run the tests](#step-2-run-the-tests)

To execute your test suite inside the container, run the following command from your project root:

```console
$ docker compose run --rm angular-test
```

This command will:

* Start the `angular-test` service defined in your `compose.yaml` file.
* Execute the `npm run test` script using the same environment as development.
* Automatically removes the container after tests complete, using the [`docker compose run --rm`](/reference/cli/docker/compose/run/) command.

You should see output similar to the following:

```shell
Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        1.529 s
```

> Note
>
> For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

***

## [Summary](#summary)

In this section, you learned how to run unit tests for your Angular application inside a Docker container using Jasmine and Docker Compose.

What you accomplished:

* Created a `angular-test` service in `compose.yaml` to isolate test execution.
* Reused the development `Dockerfile.dev` to ensure consistency between dev and test environments.
* Ran tests inside the container using `docker compose run --rm angular-test`.
* Ensured reliable, repeatable testing across environments without depending on your local machine setup.

***

## [Related resources](#related-resources)

Explore official references and best practices to sharpen your Docker testing workflow:

* [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax.
* [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles.
* [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`.
* [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container.

***

## [Next steps](#next-steps)

Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions to automatically build and test your Angular application in a containerized environment. This ensures your code is validated on every push or pull request, maintaining consistency and reliability across your development workflow.

[Automate your builds with GitHub Actions »](https://docs.docker.com/guides/angular/configure-github-actions/)

----
url: https://docs.docker.com/reference/cli/docker/model/version/
----

# docker model version

***

| Description | Show the Docker Model Runner version |
| ----------- | ------------------------------------ |
| Usage       | `docker model version`               |

## [Description](#description)

Show the Docker Model Runner version

----
url: https://docs.docker.com/reference/api/hub/deprecated/
----

# Deprecated Docker Hub API endpoints

***

Table of contents

***

This page provides an overview of endpoints that are deprecated in Docker Hub API.

***

| Status     | Feature                                                                                              | Date       |
| ---------- | ---------------------------------------------------------------------------------------------------- | ---------- |
| Deprecated | [Deprecate undocumented create/get repository](#deprecate-legacy-createrepository-and-getrepository) | 2025-09-19 |
| Deprecated | [Deprecate /v2/repositories/{namespace}](#deprecate-legacy-listnamespacerepositories)                | 2025-06-27 |
|            | [Create deprecation log table](#create-deprecation-log-table)                                        | 2025-06-27 |
| Removed    | [Docker Hub API v1 deprecation](#docker-hub-api-v1-deprecation)                                      | 2022-08-23 |

***

### [Deprecate legacy CreateRepository and GetRepository](#deprecate-legacy-createrepository-and-getrepository)

Deprecate undocumented endpoints :

* `POST /v2/repositories` and `POST /v2/repositories/{namespace}` replaced by [Create repository](/reference/api/hub/latest/#tag/repositories/operation/CreateRepository).
* `GET /v2/repositories/{namespace}/{repository}` replaced by [Get repository](/reference/api/hub/latest/#tag/repositories/operation/GetRepository).
* `HEAD /v2/repositories/{namespace}/{repository}` replaced by [Check repository](/reference/api/hub/latest/#tag/repositories/operation/CheckRepository).

***

### [Deprecate legacy ListNamespaceRepositories](#deprecate-legacy-listnamespacerepositories)

Deprecate undocumented endpoint `GET /v2/repositories/{namespace}` replaced by [List repositories](/reference/api/hub/latest/#tag/repositories/operation/listNamespaceRepositories).

***

### [Create deprecation log table](#create-deprecation-log-table)

Reformat page

***

### [Docker Hub API v1 deprecation](#docker-hub-api-v1-deprecation)

Docker Hub API v1 has been deprecated. Use Docker Hub API v2 instead.

The following API routes within the v1 path will no longer work and will return a 410 status code:

* `/v1/repositories/{name}/images`
* `/v1/repositories/{name}/tags`
* `/v1/repositories/{name}/tags/{tag_name}`
* `/v1/repositories/{namespace}/{name}/images`
* `/v1/repositories/{namespace}/{name}/tags`
* `/v1/repositories/{namespace}/{name}/tags/{tag_name}`

If you want to continue using the Docker Hub API in your current applications, update your clients to use v2 endpoints.

| **OLD**                                                                                                                                                               | **NEW**                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [/v1/repositories/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags)                                      | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/hub/latest/#tag/repositories/operation/ListRepositoryTags)     |
| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags)                          | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/hub/latest.md/#tag/repositories/operation/ListRepositoryTags)  |
| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag)             | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/hub/latest/#tag/repositories/operation/GetRepositoryTag) |
| [/v1/repositories/{namespace}/{name}/tags/{tag\_name}](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag) | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/hub/latest/#tag/repositories/operation/GetRepositoryTag) |

***

----
url: https://docs.docker.com/reference/cli/docker/scout/integration/delete/
----

# docker scout integration delete

***

| Description | Delete a new integration configuration        |
| ----------- | --------------------------------------------- |
| Usage       | `docker scout integration delete INTEGRATION` |

## [Description](#description)

The docker scout integration delete command deletes a new integration configuration for an organization.

## [Options](#options)

| Option   | Default | Description                                 |
| -------- | ------- | ------------------------------------------- |
| `--name` |         | Name of integration configuration to delete |
| `--org`  |         | Namespace of the Docker organization        |

----
url: https://docs.docker.com/compose/intro/history/
----

# History and development of Docker Compose

***

Table of contents

***

This page provides:

* A brief history of the development of the Docker Compose CLI
* A clear explanation of the major versions and file formats that make up Compose v1, v2, and v5
* The main differences between Compose v1, v2, and v5

## [Introduction](#introduction)

The diagram above highlights the key differences between Docker Compose v1, v2, and v5. Today, the supported Docker Compose CLI versions are Compose v2 and Compose v5, both of which are defined by the [Compose Specification](https://docs.docker.com/reference/compose-file/).

The diagram provides a high-level comparison of file formats, command-line syntax, and supported top-level elements. This is covered in more detail in the following sections.

### [Docker Compose CLI versioning](#docker-compose-cli-versioning)

Compose v1 was first released in 2014. It was written in Python and invoked with `docker-compose`. Typically, Compose v1 projects include a top-level `version` element in the `compose.yaml` file, with values ranging from `2.0` to `3.8`, which refer to the specific [file formats](#compose-file-format-versioning).

Compose v2, announced in 2020, is written in Go and is invoked with `docker compose`. Unlike v1, Compose v2 ignores the `version` top-level element in the `compose.yaml` file and relies entirely on the Compose Specification to interpret the file.

Compose v5, released in 2025, is functionally identical to Compose v2. Its primary distinction is the introduction of an official [Go SDK](https://docs.docker.com/compose/compose-sdk/). This SDK provides a comprehensive API that lets you integrate Compose functionality directly into your applications, allowing you to load, validate, and manage multi-container environments without relying on the Compose CLI. To avoid confusion with the legacy Compose file formats labeled “v2” and “v3,” the versioning was advanced directly to v5.

### [Compose file format versioning](#compose-file-format-versioning)

The Docker Compose CLIs are defined by specific file formats.

Three major versions of the Compose file format for Compose v1 were released:

* Compose file format 1 with Compose 1.0.0 in 2014
* Compose file format 2.x with Compose 1.6.0 in 2016
* Compose file format 3.x with Compose 1.10.0 in 2017

Compose file format 1 is substantially different to all the following formats as it lacks a top-level `services` key. Its usage is historical and files written in this format don't run with Compose v2 or v5.

Compose file format 2.x and 3.x are very similar to each other, but the latter introduced many new options targeted at Swarm deployments.

To address confusion around Compose CLI versioning, Compose file format versioning, and feature parity depending on whether Swarm mode was in use, file format 2.x and 3.x were merged into the [Compose Specification](https://docs.docker.com/reference/compose-file/).

Compose v2 and v5 uses the Compose Specification for project definition. Unlike the prior file formats, the Compose Specification is rolling and makes the `version` top-level element optional. Compose v2 and v5 also makes use of optional specifications - [Deploy](https://docs.docker.com/reference/compose-file/deploy/), [Develop](https://docs.docker.com/reference/compose-file/develop/), and [Build](https://docs.docker.com/reference/compose-file/build/).

To make migration easier, Compose v2 and v5 has backwards compatibility for certain elements that have been deprecated or changed between Compose file format 2.x/3.x and the Compose Specification.

## [What's next?](#whats-next)

* [How Compose works](https://docs.docker.com/compose/intro/compose-application-model/)
* [Compose Specification reference](https://docs.docker.com/reference/compose-file/)

----
url: https://docs.docker.com/build/metadata/annotations/
----

# Annotations

***

Table of contents

***

Annotations provide descriptive metadata for images. Use annotations to record arbitrary information and attach it to your image, which helps consumers and tools understand the origin, contents, and how to use the image.

Annotations are similar to, and in some sense overlap with, [labels](https://docs.docker.com/engine/manage-resources/labels/). Both serve the same purpose: to attach metadata to a resource. As a general principle, you can think of the difference between annotations and labels as follows:

* Annotations describe OCI image components, such as [manifests](https://github.com/opencontainers/image-spec/blob/main/manifest.md), [indexes](https://github.com/opencontainers/image-spec/blob/main/image-index.md), and [descriptors](https://github.com/opencontainers/image-spec/blob/main/descriptor.md).
* Labels describe Docker resources, such as images, containers, networks, and volumes.

The OCI image [specification](https://github.com/opencontainers/image-spec/blob/main/annotations.md) defines the format of annotations, as well as a set of pre-defined annotation keys. Adhering to the specified standards ensures that metadata about images can be surfaced automatically and consistently, by tools like Docker Scout.

Annotations are not to be confused with [attestations](https://docs.docker.com/build/metadata/attestations/):

* Attestations contain information about how an image was built and what it contains. An attestation is attached as a separate manifest on the image index. Attestations are not standardized by the Open Container Initiative.
* Annotations contain arbitrary metadata about an image. Annotations attach to the image [config](https://github.com/opencontainers/image-spec/blob/main/config.md) as labels, or on the image index or manifest as properties.

## [Add annotations](#add-annotations)

You can add annotations to an image at build-time, or when creating the image manifest or index.

> Note
>
> The Docker Engine image store doesn't support loading images with annotations. To build with annotations, make sure to push the image directly to a registry, using the `--push` CLI flag or the [registry exporter](https://docs.docker.com/build/exporters/image-registry/).

To specify annotations on the command line, use the `--annotation` flag for the `docker build` command:

```console
$ docker build --push --annotation "foo=bar" .
```

If you're using [Bake](https://docs.docker.com/build/bake/), you can use the `annotations` attribute to specify annotations for a given target:

```hcl
target "default" {
  output = ["type=registry"]
  annotations = ["foo=bar"]
}
```

For examples on how to add annotations to images built with GitHub Actions, see [Add image annotations with GitHub Actions](https://docs.docker.com/build/ci/github-actions/annotations/)

You can also add annotations to an image created using `docker buildx imagetools create`. This command only supports adding annotations to an index or manifest descriptors, see [CLI reference](/reference/cli/docker/buildx/imagetools/create/#annotation).

## [Inspect annotations](#inspect-annotations)

To view annotations on an **image index**, use the `docker buildx imagetools inspect` command. This shows you any annotations for the index and descriptors (references to manifests) that the index contains. The following example shows an `org.opencontainers.image.documentation` annotation on a descriptor, and an `org.opencontainers.image.authors` annotation on the index.

```console
$ docker buildx imagetools inspect IMAGE --raw
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:d20246ef744b1d05a1dd69d0b3fa907db007c07f79fe3e68c17223439be9fefb",
      "size": 911,
      "annotations": {
        "org.opencontainers.image.documentation": "https://foo.example/docs",
      },
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
  ],
  "annotations": {
    "org.opencontainers.image.authors": "dvdksn"
  }
}
```

To inspect annotations on a manifest, use the `docker buildx imagetools inspect` command and specify `<IMAGE>@<DIGEST>`, where `<DIGEST>` is the digest of the manifest:

```console
$ docker buildx imagetools inspect IMAGE@sha256:d20246ef744b1d05a1dd69d0b3fa907db007c07f79fe3e68c17223439be9fefb --raw
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:4368b6959a78b412efa083c5506c4887e251f1484ccc9f0af5c406d8f76ece1d",
    "size": 850
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:2c03dbb20264f09924f9eab176da44e5421e74a78b09531d3c63448a7baa7c59",
      "size": 3333033
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:4923ad480d60a548e9b334ca492fa547a3ce8879676685b6718b085de5aaf142",
      "size": 61887305
    }
  ],
  "annotations": {
    "index,manifest:org.opencontainers.image.vendor": "foocorp",
    "org.opencontainers.image.source": "https://git.example/foo.git",
  }
}
```

## [Specify annotation level](#specify-annotation-level)

By default, annotations are added to the image manifest. You can specify which level (OCI image component) to attach the annotation to by prefixing the annotation string with a special type declaration:

```console
$ docker build --annotation "TYPE:KEY=VALUE" .
```

The following types are supported:

* `manifest`: annotates manifests.
* `index`: annotates the root index.
* `manifest-descriptor`: annotates manifest descriptors in the index.
* `index-descriptor`: annotates the index descriptor in the image layout.

For example, to build an image with the annotation `foo=bar` attached to the image index:

```console
$ docker build --tag IMAGE --push --annotation "index:foo=bar" .
```

Note that the build must produce the component that you specify, or else the build will fail. For example, the following does not work, because the `docker` exporter does not produce an index:

```console
$ docker build --output type=docker --annotation "index:foo=bar" .
```

Likewise, the following example also does not work, because buildx creates a `docker` output by default under some circumstances, such as when provenance attestations are explicitly disabled:

```console
$ docker build --provenance=false --annotation "index:foo=bar" .
```

It is possible to specify types, separated by a comma, to add the annotation to more than one level. The following example creates an image with the annotation `foo=bar` on both the image index and the image manifest:

```console
$ docker build --tag IMAGE --push --annotation "index,manifest:foo=bar" .
```

You can also specify a platform qualifier within square brackets in the type prefix, to annotate only components matching specific OS and architectures. The following example adds the `foo=bar` annotation only to the `linux/amd64` manifest:

```console
$ docker build --tag IMAGE --push --annotation "manifest[linux/amd64]:foo=bar" .
```

## [Related information](#related-information)

Related articles:

* [Add image annotations with GitHub Actions](https://docs.docker.com/build/ci/github-actions/annotations/)
* [Annotations OCI specification](https://github.com/opencontainers/image-spec/blob/main/annotations.md)

Reference information:

* [`docker buildx build --annotation`](/reference/cli/docker/buildx/build/#annotation)
* [Bake file reference: `annotations`](https://docs.docker.com/build/bake/reference/#targetannotations)
* [`docker buildx imagetools create --annotation`](/reference/cli/docker/buildx/imagetools/create/#annotation)

----
url: https://docs.docker.com/reference/cli/docker/secret/rm/
----

# docker secret rm

***

| Description                                                               | Remove one or more secrets            |
| ------------------------------------------------------------------------- | ------------------------------------- |
| Usage                                                                     | `docker secret rm SECRET [SECRET...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker secret remove`                |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Removes the specified secrets from the swarm.

For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/).

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Examples](#examples)

This example removes a secret:

```console
$ docker secret rm secret.json
sapth4csdo5b6wz2p5uimh5xg
```

> Warning
>
> Unlike `docker rm`, this command does not ask for confirmation before removing a secret.

----
url: https://docs.docker.com/reference/cli/sbx/create/kiro/
----

# sbx create kiro

| Description | Create a sandbox for kiro                |
| ----------- | ---------------------------------------- |
| Usage       | `sbx create kiro PATH [PATH...] [flags]` |

## [Description](#description)

Create a sandbox with access to a host workspace for kiro.

The workspace path is required and will be mounted inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Global options](#global-options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `-D, --debug`    |         | Enable debug logging                                                                                                                                                                                                   |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Examples](#examples)

```console
# Create in the current directory
sbx create kiro .

# Create with a specific path
sbx create kiro /path/to/project

# Create with additional read-only workspaces
sbx create kiro . /path/to/docs:ro
```

----
url: https://docs.docker.com/reference/samples/ai-ml/
----

# AI/ML samples

| Name                                                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AI/ML with Docker](https://github.com/docker/genai-stack)                                                                            | Get started with AI and ML using Docker, Neo4j, LangChain, and Ollama                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [Agent-to-Agent](https://github.com/docker/compose-for-agents/tree/main/a2a)                                                          | This app is a modular AI agent runtime built on Google's Agent Development Kit (ADK) and the A2A (Agent-to-Agent) protocol. It wraps a large language model (LLM)-based agent in an HTTP API and uses structured execution flows with streaming responses, memory, and tools. It is designed to make agents callable as network services and composable with other agents.                                                                                                                                |
| [ADK Multi-Agent Fact Checker](https://github.com/docker/compose-for-agents/tree/main/adk)                                            | This project demonstrates a collaborative multi-agent system built with the Agent Development Kit (ADK), where a top-level Auditor agent coordinates the workflow to verify facts. The Critic agent gathers evidence via live internet searches using DuckDuckGo through the Model Context Protocol (MCP), while the Reviser agent analyzes and refines the conclusion using internal reasoning alone. The system showcases how agents with distinct roles and tools can collaborate under orchestration. |
| [DevDuck agents](https://github.com/docker/compose-for-agents/tree/main/adk-cerebras)                                                 | A multi-agent system for Go programming assistance built with Google Agent Development Kit (ADK). This project features a coordinating agent (DevDuck) that manages two specialized sub-agents (Bob and Cerebras) for different programming tasks.                                                                                                                                                                                                                                                        |
| [Agno](https://github.com/docker/compose-for-agents/tree/main/agno)                                                                   | This app is a multi-agent orchestration system powered by LLMs (like Qwen and OpenAI) and connected to tools via a Model Control Protocol (MCP) gateway. Its purpose is to retrieve, summarize, and document GitHub issues—automatically creating Notion pages from the summaries. It also supports file content summarization from GitHub.                                                                                                                                                               |
| [CrewAI](https://github.com/docker/compose-for-agents/tree/main/crew-ai)                                                              | This project showcases an autonomous, multi-agent virtual marketing team built with CrewAI. It automates the creation of a high-quality, end-to-end marketing strategy — from research to copywriting — using task delegation, web search, and creative synthesis.                                                                                                                                                                                                                                        |
| [SQL Agent with LangGraph](https://github.com/docker/compose-for-agents/tree/main/langgraph)                                          | This project demonstrates a zero-config AI agent that uses LangGraph to answer natural language questions by querying a SQL database — all orchestrated with Docker Compose.                                                                                                                                                                                                                                                                                                                              |
| [Langchaingo Brave Search Example - Model Context Protocol (MCP)](https://github.com/docker/compose-for-agents/tree/main/langchaingo) | This example demonstrates how to create a Go Model Context Protocol (MCP) client that communicates with the Brave Search MCP Server. The application shows how to build an MCP client that enables natural language interactions with Brave Search, allowing you to perform internet searches through a conversational interface. This example uses the official Go SDK for Model Context Protocol servers and clients, to set up the MCP client.                                                         |
| [Spring AI Brave Search Example - Model Context Protocol (MCP)](https://github.com/docker/compose-for-agents/tree/main/spring-ai)     | This example demonstrates how to create a Spring AI Model Context Protocol (MCP) client that communicates with the Brave Search MCP Server. The application shows how to build an MCP client that enables natural language interactions with Brave Search, allowing you to perform internet searches through a conversational interface. This example uses Spring Boot autoconfiguration to set up the MCP client through configuration files.                                                            |
| [MCP UI with Vercel AI SDK](https://github.com/docker/compose-for-agents/tree/main/vercel)                                            | Start an MCP UI application that uses the Vercel AI SDK to provide a chat interface for local models, provided by the Docker Model Runner, with access to MCPs from the Docker MCP Catalog.                                                                                                                                                                                                                                                                                                               |

----
url: https://docs.docker.com/reference/cli/docker/container/start/
----

# docker container start

***

| Description                                                               | Start one or more stopped containers                        |
| ------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Usage                                                                     | `docker container start [OPTIONS] CONTAINER [CONTAINER...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker start`                                              |

## [Description](#description)

Start one or more stopped containers

## [Options](#options)

| Option              | Default | Description                                                     |
| ------------------- | ------- | --------------------------------------------------------------- |
| `-a, --attach`      |         | Attach STDOUT/STDERR and forward signals                        |
| `--checkpoint`      |         | experimental (daemon) Restore from this checkpoint              |
| `--checkpoint-dir`  |         | experimental (daemon) Use a custom checkpoint storage directory |
| `--detach-keys`     |         | Override the key sequence for detaching a container             |
| `-i, --interactive` |         | Attach container's STDIN                                        |

## [Examples](#examples)

```console
$ docker start my_container
```

----
url: https://docs.docker.com/reference/cli/sbx/policy/
----

# sbx policy

| Description | Manage sandbox policies |
| ----------- | ----------------------- |
| Usage       | `sbx policy COMMAND`    |

## [Description](#description)

Manage persistent access policies for sandboxes.

Policies contain rules that control what sandboxes can access. Local rules can apply globally across all sandboxes or be scoped to one sandbox. Use subcommands to allow, deny, list, or remove rules.

## [Commands](#commands)

| Command                                                                                   | Description                     |
| ----------------------------------------------------------------------------------------- | ------------------------------- |
| [`sbx policy allow`](https://docs.docker.com/reference/cli/sbx/policy/allow/)             | Add an allow rule for sandboxes |
| [`sbx policy deny`](https://docs.docker.com/reference/cli/sbx/policy/deny/)               | Add a deny rule for sandboxes   |
| [`sbx policy log`](https://docs.docker.com/reference/cli/sbx/policy/log/)                 | Show sandbox policy logs        |
| [`sbx policy ls`](https://docs.docker.com/reference/cli/sbx/policy/ls/)                   | List sandbox policy rules       |
| [`sbx policy reset`](https://docs.docker.com/reference/cli/sbx/policy/reset/)             | Reset policies to defaults      |
| [`sbx policy rm`](https://docs.docker.com/reference/cli/sbx/policy/rm/)                   | Remove a policy rule            |
| [`sbx policy set-default`](https://docs.docker.com/reference/cli/sbx/policy/set-default/) | Set the default network policy  |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/reference/cli/sbx/secret/
----

# sbx secret

| Description | Manage stored secrets |
| ----------- | --------------------- |

## [Description](#description)

Manage stored secrets for sandbox environments.

SERVICE SECRETS (e.g. "github", "anthropic", "openai") When a sandbox starts, the proxy uses stored secrets to authenticate API requests on behalf of the agent. The secret is never exposed directly. Scoped globally (shared across all sandboxes) or to a specific sandbox.

REGISTRY SECRETS (e.g. "ghcr.io", "myregistry.azurecr.io") Used to pull private template images and kit artifacts before sandbox creation. Host-only secrets (no -g) are not injected into sandboxes; global secrets (-g) are written as \~/.docker/config.json in every new sandbox. Use "sbx secret set --registry --password-stdin" to store them.

## [Commands](#commands)

| Command                                                                   | Description               |
| ------------------------------------------------------------------------- | ------------------------- |
| [`sbx secret ls`](https://docs.docker.com/reference/cli/sbx/secret/ls/)   | List stored secrets       |
| [`sbx secret rm`](https://docs.docker.com/reference/cli/sbx/secret/rm/)   | Remove a secret           |
| [`sbx secret set`](https://docs.docker.com/reference/cli/sbx/secret/set/) | Create or update a secret |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/reference/cli/sbx/create/copilot/
----

# sbx create copilot

| Description | Create a sandbox for copilot                |
| ----------- | ------------------------------------------- |
| Usage       | `sbx create copilot PATH [PATH...] [flags]` |

## [Description](#description)

Create a sandbox with access to a host workspace for copilot.

The workspace path is required and will be mounted inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Global options](#global-options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `-D, --debug`    |         | Enable debug logging                                                                                                                                                                                                   |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Examples](#examples)

```console
# Create in the current directory
sbx create copilot .

# Create with a specific path
sbx create copilot /path/to/project

# Create with additional read-only workspaces
sbx create copilot . /path/to/docs:ro
```

----
url: https://docs.docker.com/build/builders/drivers/remote/
----

# Remote driver

***

Table of contents

***

The Buildx remote driver allows for more complex custom build workloads, allowing you to connect to externally managed BuildKit instances. This is useful for scenarios that require manual management of the BuildKit daemon, or where a BuildKit daemon is exposed from another source.

## [Synopsis](#synopsis)

```console
$ docker buildx create \
  --name remote \
  --driver remote \
  tcp://localhost:1234
```

The following table describes the available driver-specific options that you can pass to `--driver-opt`:

| Parameter      | Type    | Default            | Description                                                            |
| -------------- | ------- | ------------------ | ---------------------------------------------------------------------- |
| `key`          | String  |                    | Sets the TLS client key.                                               |
| `cert`         | String  |                    | Absolute path to the TLS client certificate to present to `buildkitd`. |
| `cacert`       | String  |                    | Absolute path to the TLS certificate authority used for validation.    |
| `servername`   | String  | Endpoint hostname. | TLS server name used in requests.                                      |
| `default-load` | Boolean | `false`            | Automatically load images to the Docker Engine image store.            |

## [Example: Remote BuildKit over Unix sockets](#example-remote-buildkit-over-unix-sockets)

This guide shows you how to create a setup with a BuildKit daemon listening on a Unix socket, and have Buildx connect through it.

1. Ensure that [BuildKit](https://github.com/moby/buildkit) is installed.

   For example, you can launch an instance of buildkitd with:

   ```console
   $ sudo ./buildkitd --group $(id -gn) --addr unix://$HOME/buildkitd.sock
   ```

   Alternatively, refer to the [Rootless Buildkit documentation](https://github.com/moby/buildkit/blob/master/docs/rootless.md) for running buildkitd in rootless mode, or [the BuildKit systemd examples](https://github.com/moby/buildkit/tree/master/examples/systemd) for running it as a systemd service.

2. Check that you have a Unix socket that you can connect to.

   ```console
   $ ls -lh /home/user/buildkitd.sock
   srw-rw---- 1 root user 0 May  5 11:04 /home/user/buildkitd.sock
   ```

3. Connect Buildx to it using the remote driver:

   ```console
   $ docker buildx create \
     --name remote-unix \
     --driver remote \
     unix://$HOME/buildkitd.sock
   ```

4. List available builders with `docker buildx ls`. You should then see `remote-unix` among them:

   ```console
   $ docker buildx ls
   NAME/NODE           DRIVER/ENDPOINT                        STATUS  PLATFORMS
   remote-unix         remote
     remote-unix0      unix:///home/.../buildkitd.sock        running linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
   default *           docker
     default           default                                running linux/amd64, linux/386
   ```

You can switch to this new builder as the default using `docker buildx use remote-unix`, or specify it per build using `--builder`:

```console
$ docker buildx build --builder=remote-unix -t test --load .
```

Remember that you need to use the `--load` flag if you want to load the build result into the Docker daemon.

## [Example: Remote BuildKit in Docker container](#example-remote-buildkit-in-docker-container)

This guide will show you how to create setup similar to the `docker-container` driver, by manually booting a BuildKit Docker container and connecting to it using the Buildx remote driver. This procedure will manually create a container and access it via it's exposed port. (You'd probably be better of just using the `docker-container` driver that connects to BuildKit through the Docker daemon, but this is for illustration purposes.)

1. Generate certificates for BuildKit.

   You can use this [bake definition](https://github.com/moby/buildkit/blob/master/examples/create-certs) as a starting point:

   ```console
   SAN="localhost 127.0.0.1" docker buildx bake "https://github.com/moby/buildkit.git#master:examples/create-certs"
   ```

   Note that while it's possible to expose BuildKit over TCP without using TLS, it's not recommended. Doing so allows arbitrary access to BuildKit without credentials.

2. With certificates generated in `.certs/`, startup the container:

   ```console
   $ docker run -d --rm \
     --name=remote-buildkitd \
     --privileged \
     -p 1234:1234 \
     -v $PWD/.certs:/etc/buildkit/certs \
     moby/buildkit:latest \
     --addr tcp://0.0.0.0:1234 \
     --tlscacert /etc/buildkit/certs/daemon/ca.pem \
     --tlscert /etc/buildkit/certs/daemon/cert.pem \
     --tlskey /etc/buildkit/certs/daemon/key.pem
   ```

   This command starts a BuildKit container and exposes the daemon's port 1234 to localhost.

3. Connect to this running container using Buildx:

   ```console
   $ docker buildx create \
     --name remote-container \
     --driver remote \
     --driver-opt cacert=${PWD}/.certs/client/ca.pem,cert=${PWD}/.certs/client/cert.pem,key=${PWD}/.certs/client/key.pem,servername=TLS_SERVER_NAME \
     tcp://localhost:1234
   ```

   Alternatively, use the `docker-container://` URL scheme to connect to the BuildKit container without specifying a port:

   ```console
   $ docker buildx create \
     --name remote-container \
     --driver remote \
     docker-container://remote-container
   ```

## [Example: Remote BuildKit in Kubernetes](#example-remote-buildkit-in-kubernetes)

This guide will show you how to create a setup similar to the `kubernetes` driver by manually creating a BuildKit `Deployment`. While the `kubernetes` driver will do this under-the-hood, it might sometimes be desirable to scale BuildKit manually. Additionally, when executing builds from inside Kubernetes pods, the Buildx builder will need to be recreated from within each pod or copied between them.

1. Create a Kubernetes deployment of `buildkitd` by following the instructions [in the BuildKit documentation](https://github.com/moby/buildkit/tree/master/examples/kubernetes).

   Create certificates for the BuildKit daemon and client using the [create-certs.sh](https://github.com/moby/buildkit/blob/master/examples/kubernetes/create-certs.sh), script and create a deployment of BuildKit pods with a service that connects to them.

2. Assuming that the service is called `buildkitd`, create a remote builder in Buildx, ensuring that the listed certificate files are present:

   ```console
   $ docker buildx create \
     --name remote-kubernetes \
     --driver remote \
     --driver-opt cacert=${PWD}/.certs/client/ca.pem,cert=${PWD}/.certs/client/cert.pem,key=${PWD}/.certs/client/key.pem \
     tcp://buildkitd.default.svc:1234
   ```

Note that this only works internally, within the cluster, since the BuildKit setup guide only creates a `ClusterIP` service. To access a builder remotely, you can set up and use an ingress, which is outside the scope of this guide.

### [Debug a remote builder in Kubernetes](#debug-a-remote-builder-in-kubernetes)

If you're having trouble accessing a remote builder deployed in Kubernetes, you can use the `kube-pod://` URL scheme to connect directly to a BuildKit pod through the Kubernetes API. Note that this method only connects to a single pod in the deployment.

```console
$ kubectl get pods --selector=app=buildkitd -o json | jq -r '.items[].metadata.name'
buildkitd-XXXXXXXXXX-xxxxx
$ docker buildx create \
  --name remote-container \
  --driver remote \
  kube-pod://buildkitd-XXXXXXXXXX-xxxxx
```

Alternatively, use the port forwarding mechanism of `kubectl`:

```console
$ kubectl port-forward svc/buildkitd 1234:1234
```

Then you can point the remote driver at `tcp://localhost:1234`.

----
url: https://docs.docker.com/reference/cli/docker/logout/
----

# docker logout

***

| Description | Log out from a registry  |
| ----------- | ------------------------ |
| Usage       | `docker logout [SERVER]` |

## [Description](#description)

Log out from a registry. If no server is specified, the default is defined by the daemon.

## [Examples](#examples)

```console
$ docker logout localhost:8080
```

----
url: https://docs.docker.com/build/building/secrets/
----

# Build secrets

***

Table of contents

***

A build secret is any piece of sensitive information, such as a password or API token, consumed as part of your application's build process.

Build arguments and environment variables are inappropriate for passing secrets to your build, because they persist in the final image. Instead, you should use secret mounts or SSH mounts, which expose secrets to your builds securely.

## [Types of build secrets](#types-of-build-secrets)

* [Secret mounts](#secret-mounts) are general-purpose mounts for passing secrets into your build. A secret mount takes a secret from the build client and makes it temporarily available inside the build container, for the duration of the build instruction. This is useful if, for example, your build needs to communicate with a private artifact server or API.
* [SSH mounts](#ssh-mounts) are special-purpose mounts for making SSH sockets or keys available inside builds. They're commonly used when you need to fetch private Git repositories in your builds.
* [Git authentication for remote contexts](#git-authentication-for-remote-contexts) is a set of pre-defined secrets for when you build with a remote Git context that's also a private repository. These secrets are "pre-flight" secrets: they are not consumed within your build instruction, but they're used to provide the builder with the necessary credentials to fetch the context.

## [Using build secrets](#using-build-secrets)

For secret mounts and SSH mounts, using build secrets is a two-step process. First you need to pass the secret into the `docker build` command, and then you need to consume the secret in your Dockerfile.

To pass a secret to a build, use the [`docker build --secret` flag](/reference/cli/docker/buildx/build/#secret), or the equivalent options for [Bake](https://docs.docker.com/build/bake/reference/#targetsecret).

```console
$ docker build --secret id=aws,src=$HOME/.aws/credentials .
```

```hcl
variable "HOME" {
  default = null
}

target "default" {
  secret = [
    "id=aws,src=${HOME}/.aws/credentials"
  ]
}
```

To consume a secret in a build and make it accessible to the `RUN` instruction, use the [`--mount=type=secret`](https://docs.docker.com/reference/dockerfile/#run---mounttypesecret) flag in the Dockerfile.

```dockerfile
RUN --mount=type=secret,id=aws \
    AWS_SHARED_CREDENTIALS_FILE=/run/secrets/aws \
    aws s3 cp ...
```

## [Secret mounts](#secret-mounts)

Secret mounts expose secrets to the build containers, as files or environment variables. You can use secret mounts to pass sensitive information to your builds, such as API tokens, passwords, or SSH keys.

### [Sources](#sources)

The source of a secret can be either a [file](/reference/cli/docker/buildx/build/#file) or an [environment variable](/reference/cli/docker/buildx/build/#typeenv). When you use the CLI or Bake, the type can be detected automatically. You can also specify it explicitly with `type=file` or `type=env`.

The following example mounts the environment variable `KUBECONFIG` to secret ID `kube`, as a file in the build container at `/run/secrets/kube`.

```console
$ docker build --secret id=kube,env=KUBECONFIG .
```

When you use secrets from environment variables, you can omit the `env` parameter to bind the secret to a file with the same name as the variable. In the following example, the value of the `API_TOKEN` variable is mounted to `/run/secrets/API_TOKEN` in the build container.

```console
$ docker build --secret id=API_TOKEN .
```

### [Target](#target)

When consuming a secret in a Dockerfile, the secret is mounted to a file by default. The default file path of the secret, inside the build container, is `/run/secrets/<id>`. You can customize how the secrets get mounted in the build container using the `target` and `env` options for the `RUN --mount` flag in the Dockerfile.

The following example takes secret id `aws` and mounts it to a file at `/run/secrets/aws` in the build container.

```dockerfile
RUN --mount=type=secret,id=aws \
    AWS_SHARED_CREDENTIALS_FILE=/run/secrets/aws \
    aws s3 cp ...
```

To mount a secret as a file with a different name, use the `target` option in the `--mount` flag.

```dockerfile
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
    aws s3 cp ...
```

To mount a secret as an environment variable instead of a file, use the `env` option in the `--mount` flag.

```dockerfile
RUN --mount=type=secret,id=aws-key-id,env=AWS_ACCESS_KEY_ID \
    --mount=type=secret,id=aws-secret-key,env=AWS_SECRET_ACCESS_KEY \
    --mount=type=secret,id=aws-session-token,env=AWS_SESSION_TOKEN \
    aws s3 cp ...
```

It's possible to use the `target` and `env` options together to mount a secret as both a file and an environment variable.

## [SSH mounts](#ssh-mounts)

If the credential you want to use in your build is an SSH agent socket or key, you can use the SSH mount instead of a secret mount. Cloning private Git repositories is a common use case for SSH mounts.

The following example clones a private GitHub repository using a [Dockerfile SSH mount](https://docs.docker.com/reference/dockerfile/#run---mounttypessh).

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
ADD git@github.com:me/myprivaterepo.git /src/
```

To pass an SSH socket the build, you use the [`docker build --ssh` flag](/reference/cli/docker/buildx/build/#ssh), or equivalent options for [Bake](https://docs.docker.com/build/bake/reference/#targetssh).

```console
$ docker buildx build --ssh default .
```

## [Git authentication for remote contexts](#git-authentication-for-remote-contexts)

BuildKit supports two pre-defined build secrets, `GIT_AUTH_TOKEN` and `GIT_AUTH_HEADER`. Use them to specify HTTP authentication parameters when building with remote, private Git repositories, including:

* Building with a private Git repository as build context
* Fetching private Git repositories in a build with `ADD`

For example, say you have a private GitHub repository at `https://github.com/example/todo-app.git`, and you want to run a build using that repository as the build context. An unauthenticated `docker build` command fails because the builder isn't authorized to pull the repository:

```console
$ docker build https://github.com/example/todo-app.git
[+] Building 0.4s (1/1) FINISHED
 => ERROR [internal] load git source https://github.com/example/todo-app.git
------
 > [internal] load git source https://github.com/example/todo-app.git:
0.313 fatal: could not read Username for 'https://github.com': terminal prompts disabled
------
```

To authenticate the builder to GitHub, set the `GIT_AUTH_TOKEN` environment variable to contain a valid GitHub access token, and pass it as a secret to the build:

```console
$ GIT_AUTH_TOKEN=$(gh auth token) docker build \
  --secret id=GIT_AUTH_TOKEN \
  https://github.com/example/todo-app.git
```

The `GIT_AUTH_TOKEN` also works with `ADD` to fetch private Git repositories as part of your build:

```dockerfile
FROM alpine
ADD https://github.com/example/todo-app.git /src
```

### [HTTP authentication scheme](#http-authentication-scheme)

BuildKit supports two Git authentication secrets:

* **`GIT_AUTH_TOKEN`**: Uses Basic authentication with a fixed username of `x-access-token` (the GitHub-style default)
* **`GIT_AUTH_HEADER`**: Uses the raw authorization header value you provide (works with any Git provider)

#### [Using GIT\_AUTH\_TOKEN (for example, GitHub)](#using-git_auth_token-for-example-github)

When you use `GIT_AUTH_TOKEN`, BuildKit constructs a Basic authentication header using `x-access-token` as the user:

```http
Authorization: Basic <base64("x-access-token:GIT_AUTH_TOKEN")>
```

This method works for providers that accept the `x-access-token` Basic auth pattern, such as GitHub. Example usage:

```console
$ export GIT_AUTH_TOKEN=$(gh auth token)
$ docker build \
  --secret id=GIT_AUTH_TOKEN \
  https://github.com/example/todo-app.git
```

#### [Using GIT\_AUTH\_HEADER (custom authorization header)](#using-git_auth_header-custom-authorization-header)

When you use `GIT_AUTH_HEADER`, BuildKit uses the exact value you provide as the `Authorization` header:

```http
Authorization: GIT_AUTH_HEADER
```

Example usage with GitLab CI/CD token:

```console
$ export GIT_AUTH_HEADER="Basic $(echo -n "gitlab-ci-token:${CI_JOB_TOKEN}" | base64)"
$ docker build \
  --secret id=GIT_AUTH_HEADER \
  https://gitlab.com/example/todo-app.git
```

### [Multiple hosts](#multiple-hosts)

You can set the `GIT_AUTH_TOKEN` and `GIT_AUTH_HEADER` secrets on a per-host basis, which lets you use different authentication parameters for different hostnames. To specify a hostname, append the hostname as a suffix to the secret ID:

```console
$ export GITHUB_TOKEN=$(gh auth token)
$ export GITLAB_AUTH_HEADER="Basic $(echo -n "gitlab-ci-token:${CI_JOB_TOKEN}" | base64)"
$ docker build \
  --secret id=GIT_AUTH_TOKEN.github.com,env=GITHUB_TOKEN \
  --secret id=GIT_AUTH_HEADER.gitlab.com,env=GITLAB_AUTH_HEADER \
  https://github.com/example/todo-app.git
```

## [HTTP authentication for `COPY` and `ADD`](#http-authentication-for-copy-and-add)

To use secrets in `COPY` or `ADD` commands, you can create `HTTP_AUTH_TOKEN_<host>` or `HTTP_AUTH_HEADER_<host>` secrets for use when accessing the specified host. For example `HTTP_AUTH_TOKEN_127.0.0.1=token` will make requests to `127.0.0.1` add a header `Authorization: Bearer token`.

These variables follow the same convention as the [Git HTTP authentication scheme](#http-authentication-scheme) handling.

----
url: https://docs.docker.com/guides/nodejs/run-tests/
----

# Run Node.js tests in a container

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a Node.js application](https://docs.docker.com/guides/nodejs/containerize/).

## [Overview](#overview)

Testing is a core part of building reliable software. Whether you're writing unit tests, integration tests, or end-to-end tests, running them consistently across environments matters. Docker makes this easy by giving you the same setup locally, in CI/CD, and during image builds.

## [Run tests when developing locally](#run-tests-when-developing-locally)

The sample application uses Vitest for testing, and it already includes tests for React components, custom hooks, API routes, database operations, and utility functions.

### [Run tests locally (without Docker)](#run-tests-locally-without-docker)

```console
$ npm run test
```

### [Add test service to Docker Compose](#add-test-service-to-docker-compose)

To run tests in a containerized environment, you need to add a dedicated test service to your `compose.yml` file. Add the following service configuration:

```yaml
services:
  # ... existing services ...

  # ========================================
  # Test Service
  # ========================================
  app-test:
    build:
      context: .
      dockerfile: Dockerfile
      target: test
    container_name: todoapp-test
    environment:
      NODE_ENV: test
      POSTGRES_HOST: db
      POSTGRES_PORT: 5432
      POSTGRES_DB: todoapp_test
      POSTGRES_USER: todoapp
      POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:-todoapp_password}'
    depends_on:
      db:
        condition: service_healthy
    command: ['npm', 'run', 'test:coverage']
    networks:
      - todoapp-network
    profiles:
      - test
```

This test service configuration:

* Builds from test stage: Uses the `test` target from your multi-stage Dockerfile
* Isolated test database: Uses a separate `todoapp_test` database for testing
* Profile-based: Uses the `test` profile so it only runs when explicitly requested
* Health dependency: Waits for the database to be healthy before starting tests

### [Run tests in a container](#run-tests-in-a-container)

You can run tests using the dedicated test service:

```console
$ docker compose up app-test --build
```

Or run tests against the development service:

```console
$ docker compose run --rm app-dev npm run test
```

For a one-off test run with coverage:

```console
$ docker compose run --rm app-dev npm run test:coverage
```

### [Run tests with coverage](#run-tests-with-coverage)

To generate a coverage report:

```console
$ npm run test:coverage
```

You should see output like the following:

```console
> docker-nodejs-sample@1.0.0 test
> vitest --run

 ✓ src/server/__tests__/routes/todos.test.ts (5 tests) 16ms
 ✓ src/shared/utils/__tests__/validation.test.ts (15 tests) 6ms
 ✓ src/client/components/__tests__/LoadingSpinner.test.tsx (8 tests) 67ms
 ✓ src/server/database/__tests__/postgres.test.ts (13 tests) 136ms
 ✓ src/client/components/__tests__/ErrorMessage.test.tsx (8 tests) 127ms
 ✓ src/client/components/__tests__/TodoList.test.tsx (8 tests) 147ms
 ✓ src/client/components/__tests__/TodoItem.test.tsx (8 tests) 218ms
 ✓ src/client/__tests__/App.test.tsx (13 tests) 259ms
 ✓ src/client/components/__tests__/AddTodoForm.test.tsx (12 tests) 323ms
 ✓ src/client/hooks/__tests__/useTodos.test.ts (11 tests) 569ms

 Test Files  9 passed (9)
      Tests  88 passed (88)
   Start at  20:57:19
   Duration  4.41s (transform 1.79s, setup 2.66s, collect 5.38s, tests 4.61s, environment 14.07s, prepare 4.34s)
```

### [Test structure](#test-structure)

The test suite covers:

* Client Components (`src/client/components/__tests__/`): React component testing with React Testing Library
* Custom Hooks (`src/client/hooks/__tests__/`): React hooks testing with proper mocking
* Server Routes (`src/server/__tests__/routes/`): API endpoint testing
* Database Layer (`src/server/database/__tests__/`): PostgreSQL database operations testing
* Utility Functions (`src/shared/utils/__tests__/`): Validation and helper function testing
* Integration Tests (`src/client/__tests__/`): Full application integration testing

## [Run tests when building](#run-tests-when-building)

To run tests during the Docker build process, you need to add a dedicated test stage to your Dockerfile. If you haven't already added this stage, add the following to your multi-stage Dockerfile:

```dockerfile
# ========================================
# Test Stage
# ========================================
FROM build-deps AS test

# Set environment
ENV NODE_ENV=test \
    CI=true

# Copy source files
COPY --chown=nodejs:nodejs . .

# Switch to non-root user
USER nodejs

# Run tests with coverage
CMD ["npm", "run", "test:coverage"]
```

This test stage:

* Test environment: Sets `NODE_ENV=test` and `CI=true` for proper test execution
* Non-root user: Runs tests as the `nodejs` user for security
* Flexible execution: Uses `CMD` instead of `RUN` to allow running tests during build or as a separate container
* Coverage support: Configured to run tests with coverage reporting

### [Build and run tests during image build](#build-and-run-tests-during-image-build)

To build an image that runs tests during the build process, you can create a custom Dockerfile or modify the existing one temporarily:

```console
$ docker build --target test -t node-docker-image-test .
```

### [Run tests in a dedicated test container](#run-tests-in-a-dedicated-test-container)

The recommended approach is to use the test service defined in `compose.yml`:

```console
$ docker compose --profile test up app-test --build
```

Or run it as a one-off container:

```console
$ docker compose run --rm app-test
```

### [Run tests with coverage in CI/CD](#run-tests-with-coverage-in-cicd)

For continuous integration, you can run tests with coverage:

```console
$ docker build --target test --progress=plain --no-cache -t test-image .
$ docker run --rm test-image npm run test:coverage
```

You should see output containing the following:

```console
 ✓ src/server/__tests__/routes/todos.test.ts (5 tests) 16ms
 ✓ src/shared/utils/__tests__/validation.test.ts (15 tests) 6ms
 ✓ src/client/components/__tests__/LoadingSpinner.test.tsx (8 tests) 67ms
 ✓ src/server/database/__tests__/postgres.test.ts (13 tests) 136ms
 ✓ src/client/components/__tests__/ErrorMessage.test.tsx (8 tests) 127ms
 ✓ src/client/components/__tests__/TodoList.test.tsx (8 tests) 147ms
 ✓ src/client/components/__tests__/TodoItem.test.tsx (8 tests) 218ms
 ✓ src/client/__tests__/App.test.tsx (13 tests) 259ms
 ✓ src/client/components/__tests__/AddTodoForm.test.tsx (12 tests) 323ms
 ✓ src/client/hooks/__tests__/useTodos.test.ts (11 tests) 569ms

 Test Files  9 passed (9)
      Tests  88 passed (88)
   Start at  20:57:19
   Duration  4.41s (transform 1.79s, setup 2.66s, collect 5.38s, tests 4.61s, environment 14.07s, prepare 4.34s)
```

## [Summary](#summary)

In this section, you learned how to run tests when developing locally using Docker Compose and how to run tests when building your image.

Related information:

* [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax.
* [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles.
* [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`.
* [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container.

## [Next steps](#next-steps)

Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions.

[Deploy your Node.js application »](https://docs.docker.com/guides/nodejs/deploy/)

----
url: https://docs.docker.com/reference/cli/docker/container/ls/
----

# docker container ls

***

| Description                                                               | List containers                                           |
| ------------------------------------------------------------------------- | --------------------------------------------------------- |
| Usage                                                                     | `docker container ls [OPTIONS]`                           |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker container list` `docker container ps` `docker ps` |

## [Description](#description)

List containers

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-a, --all`](#all)       |         | Show all containers (default shows just running)                                                                                                                                                                                                                                                                                                                                       |
| [`-f, --filter`](#filter) |         | Filter output based on conditions provided                                                                                                                                                                                                                                                                                                                                             |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-n, --last`              | `-1`    | Show n last created containers (includes all states)                                                                                                                                                                                                                                                                                                                                   |
| `-l, --latest`            |         | Show the latest created container (includes all states)                                                                                                                                                                                                                                                                                                                                |
| [`--no-trunc`](#no-trunc) |         | Don't truncate output                                                                                                                                                                                                                                                                                                                                                                  |
| `-q, --quiet`             |         | Only display container IDs                                                                                                                                                                                                                                                                                                                                                             |
| [`-s, --size`](#size)     |         | Display total file sizes                                                                                                                                                                                                                                                                                                                                                               |

## [Examples](#examples)

### [Do not truncate output (--no-trunc)](#no-trunc)

Running `docker ps --no-trunc` showing 2 linked containers.

```console
$ docker ps --no-trunc

CONTAINER ID                                                     IMAGE                        COMMAND                CREATED              STATUS              PORTS               NAMES
ca5534a51dd04bbcebe9b23ba05f389466cf0c190f1f8f182d7eea92a9671d00 ubuntu:24.04                 bash                   17 seconds ago       Up 16 seconds       3300-3310/tcp       webapp
9ca9747b233100676a48cc7806131586213fa5dab86dd1972d6a8732e3a84a4d crosbymichael/redis:latest   /redis-server --dir    33 minutes ago       Up 33 minutes       6379/tcp            redis,webapp/db
```

### [Show both running and stopped containers (-a, --all)](#all)

The `docker ps` command only shows running containers by default. To see all containers, use the `--all` (or `-a`) flag:

```console
$ docker ps -a
```

`docker ps` groups exposed ports into a single range if possible. E.g., a container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in the `PORTS` column.

### [Show disk usage by container (--size)](#size)

The `docker ps --size` (or `-s`) command displays two different on-disk-sizes for each container:

```console
$ docker ps --size

CONTAINER ID   IMAGE          COMMAND                  CREATED        STATUS       PORTS   NAMES        SIZE
e90b8831a4b8   nginx          "/bin/bash -c 'mkdir "   11 weeks ago   Up 4 hours           my_nginx     35.58 kB (virtual 109.2 MB)
00c6131c5e30   telegraf:1.5   "/entrypoint.sh"         11 weeks ago   Up 11 weeks          my_telegraf  0 B (virtual 209.5 MB)
```

* The "size" information shows the amount of data (on disk) that is used for the *writable* layer of each container
* The "virtual size" is the total amount of disk-space used for the read-only *image* data used by the container and the writable layer.

For more information, refer to the [container size on disk](/engine/storage/drivers/#container-size-on-disk) section.

### [Filtering (--filter)](#filter)

The `--filter` (or `-f`) flag format is a `key=value` pair. If there is more than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`).

The currently supported filters are:

| Filter                | Description                                                                                                                         |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | Container's ID                                                                                                                      |
| `name`                | Container's name                                                                                                                    |
| `label`               | An arbitrary string representing either a key or a key-value pair. Expressed as `<key>` or `<key>=<value>`                          |
| `exited`              | An integer representing the container's exit code. Only useful with `--all`.                                                        |
| `status`              | One of `created`, `restarting`, `running`, `removing`, `paused`, `exited`, or `dead`                                                |
| `ancestor`            | Filters containers which share a given image as an ancestor. Expressed as `<image-name>[:<tag>]`, `<image id>`, or `<image@digest>` |
| `before` or `since`   | Filters containers created before or after a given container ID or name                                                             |
| `volume`              | Filters running containers which have mounted a given volume or bind mount.                                                         |
| `network`             | Filters running containers connected to a given network.                                                                            |
| `publish` or `expose` | Filters containers which publish or expose a given port. Expressed as `<port>[/<proto>]` or `<startport-endport>/[<proto>]`         |
| `health`              | Filters containers based on their healthcheck status. One of `starting`, `healthy`, `unhealthy` or `none`.                          |
| `isolation`           | Windows daemon only. One of `default`, `process`, or `hyperv`.                                                                      |
| `is-task`             | Filters containers that are a "task" for a service. Boolean option (`true` or `false`)                                              |

#### [label](#label)

The `label` filter matches containers based on the presence of a `label` alone or a `label` and a value.

The following filter matches containers with the `color` label regardless of its value.

```console
$ docker ps --filter "label=color"

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
673394ef1d4c        busybox             "top"               47 seconds ago      Up 45 seconds                           nostalgic_shockley
d85756f57265        busybox             "top"               52 seconds ago      Up 51 seconds                           high_albattani
```

The following filter matches containers with the `color` label with the `blue` value.

```console
$ docker ps --filter "label=color=blue"

CONTAINER ID        IMAGE               COMMAND             CREATED              STATUS              PORTS               NAMES
d85756f57265        busybox             "top"               About a minute ago   Up About a minute                       high_albattani
```

#### [name](#name)

The `name` filter matches on all or part of a container's name.

The following filter matches all containers with a name containing the `nostalgic_stallman` string.

```console
$ docker ps --filter "name=nostalgic_stallman"

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
9b6247364a03        busybox             "top"               2 minutes ago       Up 2 minutes                            nostalgic_stallman
```

You can filter for a substring in a name as this shows:

```console
$ docker ps --filter "name=nostalgic"

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
715ebfcee040        busybox             "top"               3 seconds ago       Up 1 second                             i_am_nostalgic
9b6247364a03        busybox             "top"               7 minutes ago       Up 7 minutes                            nostalgic_stallman
673394ef1d4c        busybox             "top"               38 minutes ago      Up 38 minutes                           nostalgic_shockley
```

#### [exited](#exited)

The `exited` filter matches containers by exist status code. For example, to filter for containers that have exited successfully:

```console
$ docker ps -a --filter 'exited=0'

CONTAINER ID        IMAGE             COMMAND                CREATED             STATUS                   PORTS                      NAMES
ea09c3c82f6e        registry:latest   /srv/run.sh            2 weeks ago         Exited (0) 2 weeks ago   127.0.0.1:5000->5000/tcp   desperate_leakey
106ea823fe4e        fedora:latest     /bin/sh -c 'bash -l'   2 weeks ago         Exited (0) 2 weeks ago                              determined_albattani
48ee228c9464        fedora:20         bash                   2 weeks ago         Exited (0) 2 weeks ago                              tender_torvalds
```

#### [Filter by exit signal](#filter-by-exit-signal)

You can use a filter to locate containers that exited with status of `137` meaning a `SIGKILL(9)` killed them.

```console
$ docker ps -a --filter 'exited=137'

CONTAINER ID        IMAGE               COMMAND                CREATED             STATUS                       PORTS               NAMES
b3e1c0ed5bfe        ubuntu:latest       "sleep 1000"           12 seconds ago      Exited (137) 5 seconds ago                       grave_kowalevski
a2eb5558d669        redis:latest        "/entrypoint.sh redi   2 hours ago         Exited (137) 2 hours ago                         sharp_lalande
```

Any of these events result in a `137` status:

* the `init` process of the container is killed manually
* `docker kill` kills the container
* Docker daemon restarts which kills all running containers

#### [status](#status)

The `status` filter matches containers by status. The possible values for the container status are:

| Status       | Description                                                                                                                                                                                     |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created`    | A container that has never been started.                                                                                                                                                        |
| `running`    | A running container, started by either `docker start` or `docker run`.                                                                                                                          |
| `paused`     | A paused container. See `docker pause`.                                                                                                                                                         |
| `restarting` | A container which is starting due to the designated restart policy for that container.                                                                                                          |
| `exited`     | A container which is no longer running. For example, the process inside the container completed or the container was stopped using the `docker stop` command.                                   |
| `removing`   | A container which is in the process of being removed. See `docker rm`.                                                                                                                          |
| `dead`       | A "defunct" container; for example, a container that was only partially removed because resources were kept busy by an external process. `dead` containers cannot be (re)started, only removed. |

For example, to filter for `running` containers:

```console
$ docker ps --filter status=running

CONTAINER ID        IMAGE                  COMMAND             CREATED             STATUS              PORTS               NAMES
715ebfcee040        busybox                "top"               16 minutes ago      Up 16 minutes                           i_am_nostalgic
d5c976d3c462        busybox                "top"               23 minutes ago      Up 23 minutes                           top
9b6247364a03        busybox                "top"               24 minutes ago      Up 24 minutes                           nostalgic_stallman
```

To filter for `paused` containers:

```console
$ docker ps --filter status=paused

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                      PORTS               NAMES
673394ef1d4c        busybox             "top"               About an hour ago   Up About an hour (Paused)                       nostalgic_shockley
```

#### [ancestor](#ancestor)

The `ancestor` filter matches containers based on its image or a descendant of it. The filter supports the following image representation:

* `image`
* `image:tag`
* `image:tag@digest`
* `short-id`
* `full-id`

If you don't specify a `tag`, the `latest` tag is used. For example, to filter for containers that use the latest `ubuntu` image:

```console
$ docker ps --filter ancestor=ubuntu

CONTAINER ID        IMAGE               COMMAND             CREATED              STATUS              PORTS               NAMES
919e1179bdb8        ubuntu-c1           "top"               About a minute ago   Up About a minute                       admiring_lovelace
5d1e4a540723        ubuntu-c2           "top"               About a minute ago   Up About a minute                       admiring_sammet
82a598284012        ubuntu              "top"               3 minutes ago        Up 3 minutes                            sleepy_bose
bab2a34ba363        ubuntu              "top"               3 minutes ago        Up 3 minutes                            focused_yonath
```

Match containers based on the `ubuntu-c1` image which, in this case, is a child of `ubuntu`:

```console
$ docker ps --filter ancestor=ubuntu-c1

CONTAINER ID        IMAGE               COMMAND             CREATED              STATUS              PORTS               NAMES
919e1179bdb8        ubuntu-c1           "top"               About a minute ago   Up About a minute                       admiring_lovelace
```

Match containers based on the `ubuntu` version `24.04` image:

```console
$ docker ps --filter ancestor=ubuntu:24.04

CONTAINER ID        IMAGE               COMMAND             CREATED              STATUS              PORTS               NAMES
82a598284012        ubuntu:24.04        "top"               3 minutes ago        Up 3 minutes                            sleepy_bose
```

The following matches containers based on the layer `d0e008c6cf02` or an image that have this layer in its layer stack.

```console
$ docker ps --filter ancestor=d0e008c6cf02

CONTAINER ID        IMAGE               COMMAND             CREATED              STATUS              PORTS               NAMES
82a598284012        ubuntu:24.04        "top"               3 minutes ago        Up 3 minutes                            sleepy_bose
```

#### [Create time](#create-time)

##### [before](#before)

The `before` filter shows only containers created before the container with a given ID or name. For example, having these containers created:

```console
$ docker ps

CONTAINER ID        IMAGE       COMMAND       CREATED              STATUS              PORTS              NAMES
9c3527ed70ce        busybox     "top"         14 seconds ago       Up 15 seconds                          desperate_dubinsky
4aace5031105        busybox     "top"         48 seconds ago       Up 49 seconds                          focused_hamilton
6e63f6ff38b0        busybox     "top"         About a minute ago   Up About a minute                      distracted_fermat
```

Filtering with `before` would give:

```console
$ docker ps -f before=9c3527ed70ce

CONTAINER ID        IMAGE       COMMAND       CREATED              STATUS              PORTS              NAMES
4aace5031105        busybox     "top"         About a minute ago   Up About a minute                      focused_hamilton
6e63f6ff38b0        busybox     "top"         About a minute ago   Up About a minute                      distracted_fermat
```

##### [since](#since)

The `since` filter shows only containers created since the container with a given ID or name. For example, with the same containers as in `before` filter:

```console
$ docker ps -f since=6e63f6ff38b0

CONTAINER ID        IMAGE       COMMAND       CREATED             STATUS              PORTS               NAMES
9c3527ed70ce        busybox     "top"         10 minutes ago      Up 10 minutes                           desperate_dubinsky
4aace5031105        busybox     "top"         10 minutes ago      Up 10 minutes                           focused_hamilton
```

#### [volume](#volume)

The `volume` filter shows only containers that mount a specific volume or have a volume mounted in a specific path:

```console
$ docker ps --filter volume=remote-volume --format "table {{.ID}}\t{{.Mounts}}"

CONTAINER ID        MOUNTS
9c3527ed70ce        remote-volume

$ docker ps --filter volume=/data --format "table {{.ID}}\t{{.Mounts}}"

CONTAINER ID        MOUNTS
9c3527ed70ce        remote-volume
```

#### [network](#network)

The `network` filter shows only containers that are connected to a network with a given name or ID.

The following filter matches all containers that are connected to a network with a name containing `net1`.

```console
$ docker run -d --net=net1 --name=test1 ubuntu top
$ docker run -d --net=net2 --name=test2 ubuntu top

$ docker ps --filter network=net1

CONTAINER ID        IMAGE       COMMAND       CREATED             STATUS              PORTS               NAMES
9d4893ed80fe        ubuntu      "top"         10 minutes ago      Up 10 minutes                           test1
```

The network filter matches on both the network's name and ID. The following example shows all containers that are attached to the `net1` network, using the network ID as a filter:

```console
$ docker network inspect --format "{{.ID}}" net1

8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5

$ docker ps --filter network=8c0b4110ae930dbe26b258de9bc34a03f98056ed6f27f991d32919bfe401d7c5

CONTAINER ID        IMAGE       COMMAND       CREATED             STATUS              PORTS               NAMES
9d4893ed80fe        ubuntu      "top"         10 minutes ago      Up 10 minutes                           test1
```

#### [publish and expose](#publish-and-expose)

The `publish` and `expose` filters show only containers that have published or exposed port with a given port number, port range, and/or protocol. The default protocol is `tcp` when not specified.

The following filter matches all containers that have published port of 80:

```console
$ docker run -d --publish=80 busybox top
$ docker run -d --expose=8080 busybox top

$ docker ps -a

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS                   NAMES
9833437217a5        busybox             "top"               5 seconds ago       Up 4 seconds        8080/tcp                dreamy_mccarthy
fc7e477723b7        busybox             "top"               50 seconds ago      Up 50 seconds       0.0.0.0:32768->80/tcp   admiring_roentgen

$ docker ps --filter publish=80

CONTAINER ID        IMAGE               COMMAND             CREATED              STATUS              PORTS                   NAMES
fc7e477723b7        busybox             "top"               About a minute ago   Up About a minute   0.0.0.0:32768->80/tcp   admiring_roentgen
```

The following filter matches all containers that have exposed TCP port in the range of `8000-8080`:

```console
$ docker ps --filter expose=8000-8080/tcp

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
9833437217a5        busybox             "top"               21 seconds ago      Up 19 seconds       8080/tcp            dreamy_mccarthy
```

The following filter matches all containers that have exposed UDP port `80`:

```console
$ docker ps --filter publish=80/udp

CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
```

### [Format the output (--format)](#format)

The formatting option (`--format`) pretty-prints container output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder     | Description                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------- |
| `.ID`           | Container ID                                                                                    |
| `.Image`        | Image ID                                                                                        |
| `.Command`      | Quoted command                                                                                  |
| `.CreatedAt`    | Time when the container was created.                                                            |
| `.RunningFor`   | Elapsed time since the container was started.                                                   |
| `.Ports`        | Exposed ports.                                                                                  |
| `.State`        | Container status (for example; "created", "running", "exited").                                 |
| `.Status`       | Container status with details about duration and health-status.                                 |
| `.HealthStatus` | Container health status ("starting", "healthy", "unhealthy"; empty when unavailable).           |
| `.Size`         | Container disk size.                                                                            |
| `.Names`        | Container names.                                                                                |
| `.Labels`       | All labels assigned to the container.                                                           |
| `.Label`        | Value of a specific label for this container. For example `'{{.Label "com.docker.swarm.cpu"}}'` |
| `.Mounts`       | Names of the volumes mounted in this container.                                                 |
| `.Networks`     | Names of the networks attached to this container.                                               |

When using the `--format` option, the `ps` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `ID` and `Command` entries separated by a colon (`:`) for all running containers:

```console
$ docker ps --format "{{.ID}}: {{.Command}}"

a87ecb4f327c: /bin/sh -c #(nop) MA
01946d9d34d8: /bin/sh -c #(nop) MA
c1d3b0166030: /bin/sh -c yum -y up
41d50ecd2f57: /bin/sh -c #(nop) MA
```

To list all running containers with their labels in a table format you can use:

```console
$ docker ps --format "table {{.ID}}\t{{.Labels}}"

CONTAINER ID        LABELS
a87ecb4f327c        com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd
01946d9d34d8
c1d3b0166030        com.docker.swarm.node=debian,com.docker.swarm.cpu=6
41d50ecd2f57        com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd
```

To list all running containers in JSON format, use the `json` directive:

```console
$ docker ps --format json
{"Command":"\"/docker-entrypoint.…\"","CreatedAt":"2021-03-10 00:15:05 +0100 CET","ID":"a762a2b37a1d","Image":"nginx","Labels":"maintainer=NGINX Docker Maintainers \u003cdocker-maint@nginx.com\u003e","LocalVolumes":"0","Mounts":"","Names":"boring_keldysh","Networks":"bridge","Ports":"80/tcp","RunningFor":"4 seconds ago","Size":"0B","State":"running","Status":"Up 3 seconds"}
```

----
url: https://docs.docker.com/reference/samples/spark/
----

# Spark samples

| Name                                                                                        | Description                                     |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [Java Spark / MySQL](https://github.com/docker/awesome-compose/tree/master/sparkjava-mysql) | A sample Java application and a MySQL database. |
| [Spark](https://github.com/docker/awesome-compose/tree/master/sparkjava)                    | A sample Spark application.                     |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/desktop/use-desktop/images/
----

# Explore the Images view in Docker Desktop

***

Table of contents

***

The **Images** view displays a list of your Docker images and allows you to run an image as a container, pull the latest version of an image from Docker Hub, and inspect images. It also displays a summary of image vulnerabilities. In addition, the **Images** view contains clean-up options to remove unwanted images from the disk to reclaim space. If you are logged in, you can also see the images you and your organization have shared on Docker Hub. For more information, see [Explore your images](https://docs.docker.com/desktop/use-desktop/images/).

The **Images** view lets you manage Docker images without having to use the CLI. By default, it displays a list of all Docker images on your local disk.

You can also view Hub images once you have signed in to Docker Hub. This allows you to collaborate with your team and manage your images directly through Docker Desktop.

The **Images** view lets you perform core operations such as running an image as a container, pulling the latest version of an image from Docker Hub, pushing the image to Docker Hub, and inspecting images.

It also displays metadata about the image such as the:

* Tag
* Image ID
* Date created
* Size of the image.

An **In Use** tag displays next to images used by running and stopped containers. You can choose what information you want displayed by selecting the **More options** menu to the right of the search bar, and then use the toggle switches according to your preferences.

The **Images on disk** status bar displays the number of images and the total disk space used by the images and when this information was last refreshed.

## [Manage your images](#manage-your-images)

Use the **Search** field to search for any specific image.

You can sort images by:

* In use
* Unused
* Dangling

## [Run an image as a container](#run-an-image-as-a-container)

From the **Images view**, hover over an image and select **Run**.

When prompted you can either:

* Select the **Optional settings** drop-down to specify a name, port, volumes, environment variables and select **Run**
* Select **Run** without specifying any optional settings.

## [Inspect an image](#inspect-an-image)

To inspect an image, select the image row. Inspecting an image displays detailed information about the image such as the:

* Image history
* Image ID
* Date the image was created
* Size of the image
* Layers making up the image
* Base images used
* Vulnerabilities found
* Packages inside the image

[Docker Scout](https://docs.docker.com/scout/) powers this vulnerability information. For more information about this view, see [Image details view](https://docs.docker.com/scout/explore/image-details-view/)

## [Pull the latest image from Docker Hub](#pull-the-latest-image-from-docker-hub)

Select the image from the list, select the **More options** button and select **Pull**.

> Note
>
> The repository must exist on Docker Hub in order to pull the latest version of an image. You must be signed in to pull private images.

## [Push an image to Docker Hub](#push-an-image-to-docker-hub)

Select the image from the list, select the **More options** button and select **Push to Hub**.

> Note
>
> You can only push an image to Docker Hub if the image belongs to your Docker ID or your organization. That is, the image must contain the correct username/organization in its tag to be able to push it to Docker Hub.

## [Remove an image](#remove-an-image)

> Note
>
> To remove an image used by a running or a stopped container, you must first remove the associated container.

An unused image is an image which is not used by any running or stopped containers. An image becomes dangling when you build a new version of the image with the same tag.

To remove individual images, select the bin icon.

## [Docker Hub repositories](#docker-hub-repositories)

The **Images** view also allows you to manage and interact with images in Docker Hub repositories. By default, when you go to **Images** in Docker Desktop, you see a list of images that exist in your local image store. The **Local** and **Docker Hub repositories** tabs near the top toggles between viewing images in your local image store, and images in remote Docker Hub repositories that you have access to.

Switching to the **Docker Hub repositories** tab prompts you to sign in to your Docker Hub account, if you're not already signed in. When signed in, it shows you a list of images in Docker Hub organizations and repositories that you have access to.

Select an organization from the drop-down to view a list of repositories for that organization.

If you have enabled [Docker Scout](https://docs.docker.com/scout/) on the repositories, image analysis results (and [health scores](https://docs.docker.com/scout/policy/scores/) if your Docker organization is eligible) appear next to the image tags.

Hovering over an image tag reveals two options:

* **Pull**: Pull the latest version of the image from Docker Hub.
* **View in Hub**: Open the Docker Hub page and display detailed information about the image.

## [Additional resources](#additional-resources)

* [What is an image?](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/)

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/server/remove/
----

# docker mcp catalog server remove

***

| Description                                                               | Remove MCP servers from a catalog                                                    |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Usage                                                                     | `docker mcp catalog server remove <oci-reference> --name <name1> --name <name2> ...` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker mcp catalog server rm`                                                       |

## [Description](#description)

Remove MCP servers from a catalog by server name.

## [Options](#options)

| Option   | Default | Description                                             |
| -------- | ------- | ------------------------------------------------------- |
| `--name` |         | Server name to remove (can be specified multiple times) |

## [Examples](#examples)

# [Remove servers by name](#remove-servers-by-name)

docker mcp catalog server remove mcp/my-catalog:latest --name github --name slack

# [Remove a single server](#remove-a-single-server)

docker mcp catalog server remove mcp/my-catalog:latest --name github

----
url: https://docs.docker.com/extensions/extensions-sdk/dev/api/backend/
----

# Extension Backend

***

Table of contents

***

The `ddClient.extension.vm` object can be used to communicate with the backend defined in the [vm section](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#vm-section) of the extension metadata.

## [get](#get)

▸ **get**(`url`): `Promise`<`unknown`>

Performs an HTTP GET request to a backend service.

```typescript
ddClient.extension.vm.service
 .get("/some/service")
 .then((value: any) => console.log(value)
```

See [Service API Reference](https://docs.docker.com/reference/api/extensions-sdk/HttpService/) for other HTTP methods.

> Deprecated extension backend communication
>
> The methods below that use `window.ddClient.backend` are deprecated and will be removed in a future version. Use the methods specified above.

The `window.ddClient.backend` object can be used to communicate with the backend defined in the [vm section](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#vm-section) of the extension metadata. The client is already connected to the backend.

Example usages:

```typescript
window.ddClient.backend
  .get("/some/service")
  .then((value: any) => console.log(value));

window.ddClient.backend
  .post("/some/service", { ... })
  .then((value: any) => console.log(value));

window.ddClient.backend
  .put("/some/service", { ... })
  .then((value: any) => console.log(value));

window.ddClient.backend
  .patch("/some/service", { ... })
  .then((value: any) => console.log(value));

window.ddClient.backend
  .delete("/some/service")
  .then((value: any) => console.log(value));

window.ddClient.backend
  .head("/some/service")
  .then((value: any) => console.log(value));

window.ddClient.backend
  .request({ url: "/url", method: "GET", headers: { 'header-key': 'header-value' }, data: { ... }})
  .then((value: any) => console.log(value));
```

## [Run a command in the extension backend container](#run-a-command-in-the-extension-backend-container)

For example, execute the command `ls -l` inside the backend container:

```typescript
await ddClient.extension.vm.cli.exec("ls", ["-l"]);
```

Stream the output of the command executed in the backend container. For example, spawn the command `ls -l` inside the backend container:

```typescript
await ddClient.extension.vm.cli.exec("ls", ["-l"], {
  stream: {
    onOutput(data) {
      if (data.stdout) {
        console.error(data.stdout);
      } else {
        console.log(data.stderr);
      }
    },
    onError(error) {
      console.error(error);
    },
    onClose(exitCode) {
      console.log("onClose with exit code " + exitCode);
    },
  },
});
```

For more details, refer to the [Extension VM API Reference](https://docs.docker.com/reference/api/extensions-sdk/ExtensionVM/)

> Deprecated extension backend command execution
>
> This method is deprecated and will be removed in a future version. Use the specified method above.

If your extension ships with additional binaries that should be run inside the backend container, you can use the `execInVMExtension` function:

```typescript
const output = await window.ddClient.backend.execInVMExtension(
  `cliShippedInTheVm xxx`
);
console.log(output);
```

## [Invoke an extension binary on the host](#invoke-an-extension-binary-on-the-host)

Invoke a binary on the host. The binary is typically shipped with your extension using the [host section](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#host-section) in the extension metadata. Note that extensions run with user access rights, this API is not restricted to binaries listed in the [host section](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#host-section) of the extension metadata (some extensions might install software during user interaction, and invoke newly installed binaries even if not listed in the extension metadata).

For example, execute the shipped binary `kubectl -h` command in the host:

```typescript
await ddClient.extension.host.cli.exec("kubectl", ["-h"]);
```

As long as the `kubectl` binary is shipped as part of your extension, you can spawn the `kubectl -h` command in the host and get the output stream:

```typescript
await ddClient.extension.host.cli.exec("kubectl", ["-h"], {
  stream: {
    onOutput(data: { stdout: string } | { stderr: string }): void {
      if (data.stdout) {
        console.error(data.stdout);
      } else {
        console.log(data.stderr);
      }
    },
    onError(error: any): void {
      console.error(error);
    },
    onClose(exitCode: number): void {
      console.log("onClose with exit code " + exitCode);
    },
  },
});
```

You can stream the output of the command executed in the backend container or in the host.

For more details, refer to the [Extension Host API Reference](https://docs.docker.com/reference/api/extensions-sdk/ExtensionHost/)

> Deprecated invocation of extension binary
>
> This method is deprecated and will be removed in a future version. Use the method specified above.

To execute a command in the host:

```typescript
window.ddClient.execHostCmd(`cliShippedOnHost xxx`).then((cmdResult: any) => {
  console.log(cmdResult);
});
```

To stream the output of the command executed in the backend container or in the host:

```typescript
window.ddClient.spawnHostCmd(
  `cliShippedOnHost`,
  [`arg1`, `arg2`],
  (data: any, err: any) => {
    console.log(data.stdout, data.stderr);
    // Once the command exits we get the status code
    if (data.code) {
      console.log(data.code);
    }
  }
);
```

> Note
>
> You cannot use this to chain commands in a single `exec()` invocation (like `cmd1 $(cmd2)` or using pipe between commands).
>
> You need to invoke `exec()` for each command and parse results to pass parameters to the next command if needed.

----
url: https://docs.docker.com/guides/orchestration/
----

[Deployment and orchestration](https://docs.docker.com/guides/orchestration/)

Explore the essentials of container orchestration with Docker.

Deployment

10 minutes

[« Back to all guides](/guides/)

# Deployment and orchestration

***

Table of contents

***

Containerization provides an opportunity to move and scale applications to clouds and data centers. Containers effectively guarantee that those applications run the same way anywhere, allowing you to quickly and easily take advantage of all these environments. Additionally, as you scale your applications up, you need some tooling to help automate the maintenance of those applications, enable the replacement of failed containers automatically, and manage the roll-out of updates and reconfigurations of those containers during their lifecycle.

Tools to manage, scale, and maintain containerized applications are called orchestrators. Two of the most popular orchestration tools are Kubernetes and Docker Swarm. Docker Desktop provides development environments for both of these orchestrators.

The advanced modules teach you how to:

1. [Set up and use a Kubernetes environment on your development machine](https://docs.docker.com/guides/kube-deploy/)
2. [Set up and use a Swarm environment on your development machine](https://docs.docker.com/guides/swarm-deploy/)

## [Turn on Kubernetes](#turn-on-kubernetes)

Docker Desktop sets up Kubernetes for you quickly and easily. Follow the setup and validation instructions appropriate for your operating system:

### [Mac](#mac)

1. From the Docker Dashboard, navigate to **Settings**, and select the **Kubernetes** tab.

2. Select the checkbox labeled **Enable Kubernetes**, and select **Apply**. Docker Desktop automatically sets up Kubernetes for you. You'll know that Kubernetes has been successfully enabled when you see a green light beside 'Kubernetes *running*' in **Settings**.

3. To confirm that Kubernetes is up and running, create a text file called `pod.yaml` with the following content:

   ```yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: demo
   spec:
     containers:
       - name: testpod
         image: alpine:latest
         command: ["ping", "8.8.8.8"]
   ```

   This describes a pod with a single container, isolating a simple ping to 8.8.8.8.

4. In a terminal, navigate to where you created `pod.yaml` and create your pod:

   ```console
   $ kubectl apply -f pod.yaml
   ```

5. Check that your pod is up and running:

   ```console
   $ kubectl get pods
   ```

   You should see something like:

   ```shell
   NAME      READY     STATUS    RESTARTS   AGE
   demo      1/1       Running   0          4s
   ```

6. Check that you get the logs you'd expect for a ping process:

   ```console
   $ kubectl logs demo
   ```

   You should see the output of a healthy ping process:

   ```shell
   PING 8.8.8.8 (8.8.8.8): 56 data bytes
   64 bytes from 8.8.8.8: seq=0 ttl=37 time=21.393 ms
   64 bytes from 8.8.8.8: seq=1 ttl=37 time=15.320 ms
   64 bytes from 8.8.8.8: seq=2 ttl=37 time=11.111 ms
   ...
   ```

7. Finally, tear down your test pod:

   ```console
   $ kubectl delete -f pod.yaml
   ```

### [Windows](#windows)

1. From the Docker Dashboard, navigate to **Settings**, and select the **Kubernetes** tab.

2. Select the checkbox labeled **Enable Kubernetes**, and select **Apply**. Docker Desktop automatically sets up Kubernetes for you. You'll know that Kubernetes has been successfully enabled when you see a green light beside 'Kubernetes *running*' in the **Settings** menu.

3. To confirm that Kubernetes is up and running, create a text file called `pod.yaml` with the following content:

   ```yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: demo
   spec:
     containers:
       - name: testpod
         image: alpine:latest
         command: ["ping", "8.8.8.8"]
   ```

   This describes a pod with a single container, isolating a simple ping to 8.8.8.8.

4. In PowerShell, navigate to where you created `pod.yaml` and create your pod:

   ```console
   $ kubectl apply -f pod.yaml
   ```

5. Check that your pod is up and running:

   ```console
   $ kubectl get pods
   ```

   You should see something like:

   ```shell
   NAME      READY     STATUS    RESTARTS   AGE
   demo      1/1       Running   0          4s
   ```

6. Check that you get the logs you'd expect for a ping process:

   ```console
   $ kubectl logs demo
   ```

   You should see the output of a healthy ping process:

   ```shell
   PING 8.8.8.8 (8.8.8.8): 56 data bytes
   64 bytes from 8.8.8.8: seq=0 ttl=37 time=21.393 ms
   64 bytes from 8.8.8.8: seq=1 ttl=37 time=15.320 ms
   64 bytes from 8.8.8.8: seq=2 ttl=37 time=11.111 ms
   ...
   ```

7. Finally, tear down your test pod:

   ```console
   $ kubectl delete -f pod.yaml
   ```

## [Enable Docker Swarm](#enable-docker-swarm)

Docker Desktop runs primarily on Docker Engine, which has everything you need to run a Swarm built in. Follow the setup and validation instructions appropriate for your operating system:

### [Mac](#mac)

1. Open a terminal, and initialize Docker Swarm mode:

   ```console
   $ docker swarm init
   ```

   If all goes well, you should see a message similar to the following:

   ```shell
   Swarm initialized: current node (tjjggogqpnpj2phbfbz8jd5oq) is now a manager.

   To add a worker to this swarm, run the following command:

       docker swarm join --token SWMTKN-1-3e0hh0jd5t4yjg209f4g5qpowbsczfahv2dea9a1ay2l8787cf-2h4ly330d0j917ocvzw30j5x9 192.168.65.3:2377

   To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
   ```

2. Run a simple Docker service that uses an alpine-based filesystem, and isolates a ping to 8.8.8.8:

   ```console
   $ docker service create --name demo alpine:latest ping 8.8.8.8
   ```

3. Check that your service created one running container:

   ```console
   $ docker service ps demo
   ```

   You should see something like:

   ```shell
   ID                  NAME                IMAGE               NODE                DESIRED STATE       CURRENT STATE           ERROR               PORTS
   463j2s3y4b5o        demo.1              alpine:latest       docker-desktop      Running             Running 8 seconds ago
   ```

4. Check that you get the logs you'd expect for a ping process:

   ```console
   $ docker service logs demo
   ```

   You should see the output of a healthy ping process:

   ```shell
   demo.1.463j2s3y4b5o@docker-desktop    | PING 8.8.8.8 (8.8.8.8): 56 data bytes
   demo.1.463j2s3y4b5o@docker-desktop    | 64 bytes from 8.8.8.8: seq=0 ttl=37 time=13.005 ms
   demo.1.463j2s3y4b5o@docker-desktop    | 64 bytes from 8.8.8.8: seq=1 ttl=37 time=13.847 ms
   demo.1.463j2s3y4b5o@docker-desktop    | 64 bytes from 8.8.8.8: seq=2 ttl=37 time=41.296 ms
   ...
   ```

5. Finally, tear down your test service:

   ```console
   $ docker service rm demo
   ```

### [Windows](#windows)

1. Open a PowerShell, and initialize Docker Swarm mode:

   ```console
   $ docker swarm init
   ```

   If all goes well, you should see a message similar to the following:

   ```shell
   Swarm initialized: current node (tjjggogqpnpj2phbfbz8jd5oq) is now a manager.

   To add a worker to this swarm, run the following command:

       docker swarm join --token SWMTKN-1-3e0hh0jd5t4yjg209f4g5qpowbsczfahv2dea9a1ay2l8787cf-2h4ly330d0j917ocvzw30j5x9 192.168.65.3:2377

   To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
   ```

2. Run a simple Docker service that uses an alpine-based filesystem, and isolates a ping to 8.8.8.8:

   ```console
   $ docker service create --name demo alpine:latest ping 8.8.8.8
   ```

3. Check that your service created one running container:

   ```console
   $ docker service ps demo
   ```

   You should see something like:

   ```shell
   ID                  NAME                IMAGE               NODE                DESIRED STATE       CURRENT STATE           ERROR               PORTS
   463j2s3y4b5o        demo.1              alpine:latest       docker-desktop      Running             Running 8 seconds ago
   ```

4. Check that you get the logs you'd expect for a ping process:

   ```console
   $ docker service logs demo
   ```

   You should see the output of a healthy ping process:

   ```shell
   demo.1.463j2s3y4b5o@docker-desktop    | PING 8.8.8.8 (8.8.8.8): 56 data bytes
   demo.1.463j2s3y4b5o@docker-desktop    | 64 bytes from 8.8.8.8: seq=0 ttl=37 time=13.005 ms
   demo.1.463j2s3y4b5o@docker-desktop    | 64 bytes from 8.8.8.8: seq=1 ttl=37 time=13.847 ms
   demo.1.463j2s3y4b5o@docker-desktop    | 64 bytes from 8.8.8.8: seq=2 ttl=37 time=41.296 ms
   ...
   ```

5. Finally, tear down your test service:

   ```console
   $ docker service rm demo
   ```

## [Conclusion](#conclusion)

At this point, you've confirmed that you can run simple containerized workloads in Kubernetes and Swarm. The next step is to write a YAML file that describes how to run and manage these containers.

* [Deploy to Kubernetes](https://docs.docker.com/guides/kube-deploy/)
* [Deploy to Swarm](https://docs.docker.com/guides/swarm-deploy/)

## [CLI references](#cli-references)

Further documentation for all CLI commands used in this article are available here:

* [`kubectl apply`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply)
* [`kubectl get`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get)
* [`kubectl logs`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#logs)
* [`kubectl delete`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#delete)
* [`docker swarm init`](/reference/cli/docker/swarm/init/)
* [`docker service *`](/reference/cli/docker/service/)

----
url: https://docs.docker.com/reference/api/extensions-sdk/RequestConfigV0/
----

# Interface: RequestConfigV0

***

Table of contents

***

## [Properties](#properties)

### [url](#url)

• `Readonly` **url**: `string`

***

### [method](#method)

• `Readonly` **method**: `string`

***

### [headers](#headers)

• `Readonly` **headers**: `Record`<`string`, `string`>

***

### [data](#data)

• `Readonly` **data**: `any`

----
url: https://docs.docker.com/get-started/resources/
----

# Educational resources

***

Table of contents

***

Docker and the broader community of Docker experts have put together many different ways to get further training and hands-on experience with Docker. Expand your understanding of Docker and Kubernetes with these additional free and paid resources.

## [Docker Training](#docker-training)

Learn Docker and containerization fundamentals through self-paced, [hands-on training courses](/get-started/introduction) created by Docker experts.

## [Books](#books)

If books are your preferred learning style, check out these written by the [Docker Captains](https://www.docker.com/community/captains). Docker Captain is a distinction that Docker awards to select members of the community that are both experts in their field and are committed to sharing their Docker knowledge with others.

* [Operational AI with Docker](https://www.amazon.com/Operational-AI-Docker-services-Kubernetes/dp/1807301095), Ajeet Singh Raina & Harsh Manvar, April 2026
* [Learn Docker in a Month of Lunches](https://www.manning.com/books/learn-docker-in-a-month-of-lunches), Elton Stoneman. Use the code `stonemanpc` for a 40% discount.
* [Docker on Windows: From 101 to Production with Docker on Windows](https://www.amazon.com/Docker-Windows-Elton-Stoneman-ebook/dp/B0711Y4J9K/), Elton Stoneman
* [Learn Kubernetes in a Month of Lunches](https://www.manning.com/books/learn-kubernetes-in-a-month-of-lunches), Elton Stoneman. Use the code `stonemanpc` for a 40% discount.
* [Docker in Action 2nd Edition](https://www.manning.com/books/docker-in-action-second-edition) Jeff Nickoloff, Oct 2019
* [The Kubernetes Book](https://www.amazon.com/Kubernetes-Book-Nigel-Poulton/dp/1521823634/ref=sr_1_3?ie=UTF8\&qid=1509660871\&sr=8-3\&keywords=nigel+poulton), Nigel Poulton, Nov 2018
* [Docker Deep Dive](https://www.amazon.com/Docker-Deep-Dive-Nigel-Poulton-ebook/dp/B01LXWQUFF), Nigel Poulton, 2024 Edition
* \[Portuguese] [Docker para desenvolvedores](https://leanpub.com/dockerparadesenvolvedores) (2017) by Rafael Gomes
* \[Spanish] [Érase una vez Docker](https://leanpub.com/erase-una-vez-docker), Manuel Morejón, March 2023
* \[Spanish] [Érase una vez Kubernetes](https://leanpub.com/erase-una-vez-kubernetes), Manuel Morejón, Jan 2022

## [CLI cheat sheet](#cli-cheat-sheet)

The [Docker CLI cheat sheet](/get-started/docker_cheatsheet.pdf) features the common Docker CLI commands for easy reference. It covers working with Images, Containers, Docker Hub, and other general purpose commands.

## [Self-Paced online learning](#self-paced-online-learning)

A number of Docker Captains have also created video courses on Docker and Kubernetes.

* [Bret Fisher](https://www.bretfisher.com/courses/): Docker Mastery, Docker Swarm Mastery, Docker Mastery for Node.js Projects
* [Elton Stoneman](https://docker4.net/udemy): Docker for .NET Apps - on Linux and Windows. Includes the discount code `644ABCBC33F474541885`.
* [Nick Janetakis](https://nickjanetakis.com/courses/) Dive into Docker, Docker for DevOps
* [Nigel Poulton](https://nigelpoulton.com/video-courses): Kubernetes 101, Getting Started with Kubernetes, Docker and Kubernetes: The Big Picture, Kubernetes Deep Dive, Docker Deep Dive
* [Ajeet Singh Raina](https://collabnix.com/): Docker and Kubernetes Labs
* \[French] [Luc Juggery](https://www.udemy.com/user/lucjuggery/): Introduction to Kubernetes, The Docker Platform

\* Many of the courses are fee-based

----
url: https://docs.docker.com/guides/compose-bake/
----

[Building Compose projects with Bake](https://docs.docker.com/guides/compose-bake/)

This guide demonstrates how you can use Bake to build production-grade images for Docker Compose projects.

DevOps

20 minutes

[« Back to all guides](/guides/)

# Building Compose projects with Bake

***

Table of contents

***

This guide explores how you can use Bake to build images for Docker Compose projects with multiple services.

[Docker Buildx Bake](https://docs.docker.com/build/bake/) is a build orchestration tool that enables declarative configuration for your builds, much like Docker Compose does for defining runtime stacks. For projects where Docker Compose is used to spin up services for local development, Bake offers a way of seamlessly extending the project with a production-ready build configuration.

## [Prerequisites](#prerequisites)

This guide assumes that you're familiar with

* Docker Compose
* [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/)
* [Multi-platform builds](https://docs.docker.com/build/building/multi-platform/)

## [Orientation](#orientation)

This guide will use the [dvdksn/example-voting-app](https://github.com/dvdksn/example-voting-app) repository as an example of a monorepo using Docker Compose that can be extended with Bake.

```console
$ git clone https://github.com/dvdksn/example-voting-app.git
$ cd example-voting-app
```

This repository uses Docker Compose to define the runtime configurations for running the application, in the `compose.yaml` file. This app consists of the following services:

| Service  | Description                                                            |
| -------- | ---------------------------------------------------------------------- |
| `vote`   | A front-end web app in Python which lets you vote between two options. |
| `result` | A Node.js web app which shows the results of the voting in real time.  |
| `worker` | A .NET worker which consumes votes and stores them in the database.    |
| `db`     | A Postgres database backed by a Docker volume.                         |
| `redis`  | A Redis instance which collects new votes.                             |
| `seed`   | A utility container that seeds the database with mock data.            |

The `vote`, `result`, and `worker` services are built from code in this repository, whereas `db` and `redis` use pre-existing Postgres and Redis images from Docker Hub. The `seed` service is a utility that invokes requests against the front-end service to populate the database, for testing purposes.

## [Build with Compose](#build-with-compose)

When you spin up a Docker Compose project, any services that define the `build` property are automatically built before the service is started. Here's the build configuration for the `vote` service in the example repository:

compose.yaml

```yaml
services:
  vote:
    build:
      context: ./vote # Build context
      target: dev # Dockerfile stage
```

The `vote`, `result`, and `worker` services all have a build configuration specified. Running `docker compose up` will trigger a build of these services.

Did you know that you can also use Compose just to build the service images? The `docker compose build` command lets you invoke a build using the build configuration specified in the Compose file. For example, to build the `vote` service with this configuration, run:

```console
$ docker compose build vote
```

Omit the service name to build all services at once:

```console
$ docker compose build
```

The `docker compose build` command is useful when you only need to build images without running services.

The Compose file format supports a number of properties for defining your build's configuration. For example, to specify the tag name for the images, set the `image` property on the service.

```yaml
services:
  vote:
    image: username/vote
    build:
      context: ./vote
      target: dev
    #...

  result:
    image: username/result
    build:
      context: ./result
    #...

  worker:
    image: username/worker
    build:
      context: ./worker
    #...
```

Running `docker compose build` creates three service images with fully qualified image names that you can push to Docker Hub.

The `build` property supports a [wide range](https://docs.docker.com/reference/compose-file/build/) of options for configuring builds. However, building production-grade images are often different from images used in local development. To avoid cluttering your Compose file with build configurations that might not be desirable for local builds, consider separating the production builds from the local builds by using Bake to build images for release. This approach separates concerns: using Compose for local development and Bake for production-ready builds, while still reusing service definitions and fundamental build configurations.

## [Build with Bake](#build-with-bake)

Like Compose, Bake parses the build definition for a project from a configuration file. Bake supports HashiCorp Configuration Language (HCL), JSON, and the Docker Compose YAML format. When you use Bake with multiple files, it will find and merge all of the applicable configuration files into one unified build configuration. The build options defined in your Compose file are extended, or in some cases overridden, by options specified in the Bake file.

The following section explores how you can use Bake to extend the build options defined in your Compose file for production.

### [View the build configuration](#view-the-build-configuration)

Bake automatically creates a build configuration from the `build` properties of your services. Use the `--print` flag for Bake to view the build configuration for a given Compose file. This flag evaluates the build configuration and outputs the build definition in JSON format.

```console
$ docker buildx bake --print
```

The JSON-formatted output shows the group that would be executed, and all the targets of that group. A group is a collection of builds, and a target represents a single build.

```json
{
  "group": {
    "default": {
      "targets": [
        "vote",
        "result",
        "worker",
        "seed"
      ]
    }
  },
  "target": {
    "result": {
      "context": "result",
      "dockerfile": "Dockerfile",
    },
    "seed": {
      "context": "seed-data",
      "dockerfile": "Dockerfile",
    },
    "vote": {
      "context": "vote",
      "dockerfile": "Dockerfile",
      "target": "dev",
    },
    "worker": {
      "context": "worker",
      "dockerfile": "Dockerfile",
    }
  }
}
```

As you can see, Bake has created a `default` group that includes four targets:

* `seed`
* `vote`
* `result`
* `worker`

This group is created automatically from your Compose file; it includes all of your services containing a build configuration. To build this group of services with Bake, run:

```console
$ docker buildx bake
```

### [Customize the build group](#customize-the-build-group)

Start by redefining the default build group that Bake executes. The current default group includes a `seed` target — a Compose service used solely to populate the database with mock data. Since this target doesn't produce a production image, it doesn’t need to be included in the build group.

To customize the build configuration that Bake uses, create a new file at the root of the repository, alongside your `compose.yaml` file, named `docker-bake.hcl`.

```console
$ touch docker-bake.hcl
```

Open the Bake file and add the following configuration:

docker-bake.hcl

```hcl
group "default" {
  targets = ["vote", "result", "worker"]
}
```

Save the file and print your Bake definition again.

```console
$ docker buildx bake --print
```

The JSON output shows that the `default` group only includes the targets you care about.

```json
{
  "group": {
    "default": {
      "targets": ["vote", "result", "worker"]
    }
  },
  "target": {
    "result": {
      "context": "result",
      "dockerfile": "Dockerfile",
      "tags": ["username/result"]
    },
    "vote": {
      "context": "vote",
      "dockerfile": "Dockerfile",
      "tags": ["username/vote"],
      "target": "dev"
    },
    "worker": {
      "context": "worker",
      "dockerfile": "Dockerfile",
      "tags": ["username/worker"]
    }
  }
}
```

Here, the build configuration for each target (context, tags, etc.) is picked up from the `compose.yaml` file. The group is defined by the `docker-bake.hcl` file.

### [Customize targets](#customize-targets)

The Compose file currently defines the `dev` stage as the build target for the `vote` service. That's appropriate for the image that you would run in local development, because the `dev` stage includes additional development dependencies and configurations. For the production image, however, you'll want to target the `final` image instead.

To modify the target stage used by the `vote` service, add the following configuration to the Bake file:

```hcl
target "vote" {
  target = "final"
}
```

This overrides the `target` property specified in the Compose file with a different value when you run the build with Bake. The other build options in the Compose file (tag, context) remain unmodified. You can verify by inspecting the build configuration for the `vote` target with `docker buildx bake --print vote`:

```json
{
  "group": {
    "default": {
      "targets": ["vote"]
    }
  },
  "target": {
    "vote": {
      "context": "vote",
      "dockerfile": "Dockerfile",
      "tags": ["username/vote"],
      "target": "final"
    }
  }
}
```

### [Additional build features](#additional-build-features)

Production-grade builds often have different characteristics from development builds. Here are a few examples of things you might want to add for production images.

* Multi-platform

  For local development, you only need to build images for your local platform, since those images are just going to run on your machine. But for images that are pushed to a registry, it's often a good idea to build for multiple platforms, arm64 and amd64 in particular.

* Attestations

  [Attestations](https://docs.docker.com/build/metadata/attestations/) are manifests attached to the image that describe how the image was created and what components it contains. Attaching attestations to your images helps ensure that your images follow software supply chain best practices.

* Annotations

  [Annotations](https://docs.docker.com/build/metadata/annotations/) provide descriptive metadata for images. Use annotations to record arbitrary information and attach it to your image, which helps consumers and tools understand the origin, contents, and how to use the image.

> Tip
>
> Why not just define these additional build options in the Compose file directly?
>
> The `build` property in the Compose file format does not support all build features. Additionally, some features, like multi-platform builds, can drastically increase the time it takes to build a service. For local development, you're better off keeping your build step simple and fast, saving the bells and whistles for release builds.

To add these properties to the images you build with Bake, update the Bake file as follows:

```hcl
group "default" {
  targets = ["vote", "result", "worker"]
}

target "_common" {
  annotations = ["org.opencontainers.image.authors=username"]
  platforms = ["linux/amd64", "linux/arm64"]
  attest = [
    "type=provenance,mode=max",
    "type=sbom"
  ]
}

target "vote" {
  inherits = ["_common"]
  target = "final"
}

target "result" {
  inherits = ["_common"]
}

target "worker" {
  inherits = ["_common"]
}
```

This defines a new `_common` target that defines reusable build configuration for adding multi-platform support, annotations, and attestations to your images. The reusable target is inherited by the build targets.

With these changes, building the project with Bake produces three sets of multi-platform images for the `linux/amd64` and `linux/arm64` architectures. Each image is decorated with an author annotation, and both SBOM and provenance attestation records.

## [Conclusions](#conclusions)

The pattern demonstrated in this guide provides a useful approach for managing production-ready Docker images in projects using Docker Compose. Using Bake gives you access to all the powerful features of Buildx and BuildKit, and also helps separate your development and build configuration in a reasonable way.

### [Further reading](#further-reading)

For more information about how to use Bake, check out these resources:

* [Bake documentation](https://docs.docker.com/build/bake/)
* [Building with Bake from a Compose file](https://docs.docker.com/build/bake/compose-file/)
* [Bake file reference](https://docs.docker.com/build/bake/reference/)
* [Mastering multi-platform builds, testing, and more with Docker Buildx Bake](https://docs.docker.com/guides/bake/)
* [Bake GitHub Action](https://github.com/docker/bake-action)

----
url: https://docs.docker.com/reference/cli/docker/model/start-runner/
----

# docker model start-runner

***

| Description | Start Docker Model Runner (Docker Engine only) |
| ----------- | ---------------------------------------------- |
| Usage       | `docker model start-runner`                    |

## [Description](#description)

This command starts the Docker Model Runner without pulling container images. Use this command to start the runner when you already have the required images locally.

For the first-time setup or to ensure you have the latest images, use `docker model install-runner` instead.

## [Options](#options)

| Option           | Default     | Description                                                                                             |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| `--backend`      |             | Specify backend (llama.cpp\|vllm\|diffusers). Default: llama.cpp                                        |
| `--debug`        |             | Enable debug logging                                                                                    |
| `--do-not-track` |             | Do not track models usage in Docker Model Runner                                                        |
| `--gpu`          | `auto`      | Specify GPU support (none\|auto\|cuda\|rocm\|musa\|cann)                                                |
| `--host`         | `127.0.0.1` | Host address to bind Docker Model Runner                                                                |
| `--port`         |             | Docker container port for Docker Model Runner (default: 12434 for Docker Engine, 12435 for Cloud mode)  |
| `--proxy-cert`   |             | Path to a CA certificate file for proxy SSL inspection                                                  |
| `--tls`          |             | Enable TLS/HTTPS for Docker Model Runner API                                                            |
| `--tls-cert`     |             | Path to TLS certificate file (auto-generated if not provided)                                           |
| `--tls-key`      |             | Path to TLS private key file (auto-generated if not provided)                                           |
| `--tls-port`     |             | TLS port for Docker Model Runner (default: 12444 for Docker Engine, 12445 for Cloud mode)               |

----
url: https://docs.docker.com/docker-hub/repos/manage/builds/troubleshoot/
----

# Troubleshoot your autobuilds

***

Table of contents

***

> Warning
>
> Docker Hub Automated Builds is a deprecated feature. It will be fully retired on April 1, 2027.

> Note
>
> Automated builds require a Docker Pro, Team, or Business subscription.

## [Failing builds](#failing-builds)

If a build fails, a **Retry** icon appears next to the build report line on the **General** and **Builds** tabs. The **Build report** page and **Timeline logs** also display a **Retry** button.

> Note
>
> If you are viewing the build details for a repository that belongs to an organization, the **Cancel** and **Retry** buttons only appear if you have `Read & Write` access to the repository.

Automated builds have a 4-hour execution time limit. If a build reaches this time limit, it's automatically cancelled, and the build logs display the following message:

```text
2022-11-02T17:42:27Z The build was cancelled or exceeded the maximum execution time.
```

This log message is the same as when you actively cancel a build. To identify whether a build was automatically cancelled, check the build duration.

## [Build repositories with linked private submodules](#build-repositories-with-linked-private-submodules)

Docker Hub sets up a deploy key in your source code repository that allows it to clone the repository and build it. This key only works for a single, specific code repository. If your source code repository uses private Git submodules, or requires that you clone other private repositories to build, Docker Hub cannot access these additional repositories, your build cannot complete, and an error is logged in your build timeline.

To work around this, you can set up your automated build using the `SSH_PRIVATE` environment variable to override the deployment key and grant Docker Hub's build system access to the repositories.

> Note
>
> If you are using autobuild for teams, use the process below instead, and configure a service user for your source code provider. You can also do this for an individual account to limit Docker Hub's access to your source repositories.

1. Generate a SSH keypair that you use for builds only, and add the public key to your source code provider account.

   This step is optional, but allows you to revoke the build-only keypair without removing other access.

2. Copy the private half of the keypair to your clipboard.

3. In Docker Hub, navigate to the build page for the repository that has linked private submodules. (If necessary, [follow the steps here](https://docs.docker.com/docker-hub/repos/manage/builds/#configure-automated-builds) to configure the automated build.)

4. At the bottom of the screen, select the **plus** icon next to **Build Environment variables**.

5. Enter `SSH_PRIVATE` as the name for the new environment variable.

6. Paste the private half of the keypair into the **Value** field.

7. Select **Save**, or **Save and Build** to validate that the build now completes.

> Note
>
> You must configure your private git submodules using git clone over SSH (`git@submodule.tld:some-submodule.git`) rather than HTTPS.

----
url: https://docs.docker.com/subscription/scale/
----

# Scale your subscription

***

Table of contents

***

Docker subscriptions let you scale consumption as your needs grow. All paid Docker subscriptions include base amounts of Docker Build Cloud build minutes and Testcontainers Cloud runtime minutes that you can supplement with additional capacity.

You can scale consumption for:

* Docker Build Cloud build minutes
* Testcontainers Cloud runtime minutes
* Docker Hardened Images (DHI) repositories

To understand your usage patterns, [view your consumption](https://docs.docker.com/admin/organization/manage/manage-products/#monitor-product-usage-for-your-organization) at any time.

> Note
>
> Legacy Docker subscribers must upgrade to new Docker subscriptions to access scaling options. Legacy subscriptions apply to subscribers who last purchased or renewed before December 10, 2024. For details, see [Announcing Upgraded Docker Plans](https://www.docker.com/blog/november-2024-updated-plans-announcement/).

## [Usage considerations](#usage-considerations)

Minutes don't roll over. Base subscription minutes reset each billing period and don't accumulate. Additional purchased minutes expire at the end of your subscription period.

For example, with an annual Docker Team subscription (500 included minutes), if you purchase 500 additional minutes, only the additional 500 minutes roll over until your annual renewal.

## [Add Docker Build Cloud build minutes](#add-docker-build-cloud-build-minutes)

Purchase additional build minutes through the Docker Build Cloud Dashboard:

1. Sign in to [Docker Home](https://app.docker.com/) and choose your organization.
2. Select **Build Cloud**, then **Build minutes**.
3. Select **Add minutes**.
4. Select your additional minute amount, then **Continue to payment**.
5. Enter your payment details and billing address.
6. Review your order and select **Pay**.

Your additional minutes appear on the Build minutes page immediately.

## [Add Docker Testcontainers Cloud runtime minutes](#add-docker-testcontainers-cloud-runtime-minutes)

You can add Testcontainers Cloud runtime minutes in two ways:

* [Contact sales](https://www.docker.com/pricing/contact-sales/) to pre-purchase runtime minutes at discounted rates
* Use unlimited runtime minutes on-demand with billing at the end of each monthly cycle

On-demand usage is billed at higher rates than pre-purchased capacity. To avoid higher on-demand charges, pre-purchase additional minutes if you expect consistent usage over your subscription's included minutes.

## [Add DHI repositories](#add-dhi-repositories)

To add more hardened repositories to your DHI Select plan:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Billing**.
3. On the Overview page, select **Manage** next to **Hardened Images**.
4. Select how many repositories the account can use.

> Tip
>
> Purchasing eight or more hardened repositories? [Contact Docker sales](https://www.docker.com/pricing/contact-sales/) to discuss an Enterprise plan.

## [What's next](#whats-next)

To learn more, see:

* [Testcontainers overview](https://docs.docker.com/testcontainers/)
* [Docker Build Cloud overview](https://docs.docker.com/build-cloud/)
* [DHI Select and Enterprise quickstart](https://docs.docker.com/dhi/how-to/select-enterprise/)

----
url: https://docs.docker.com/build/building/cdi/
----

# Container Device Interface (CDI)

***

Table of contents

***

The [Container Device Interface (CDI)](https://github.com/cncf-tags/container-device-interface/blob/main/SPEC.md) is a specification designed to standardize how devices (like GPUs, FPGAs, and other hardware accelerators) are exposed to and used by containers. The aim is to provide a more consistent and secure mechanism for using hardware devices in containerized environments, addressing the challenges associated with device-specific setups and configurations.

In addition to enabling the container to interact with the device node, CDI also lets you specify additional configuration for the device, such as environment variables, host mounts (such as shared objects), and executable hooks.

## [Getting started](#getting-started)

To get started with CDI, you need to have a compatible environment set up. This includes having Docker v27+ installed with [CDI configured](https://docs.docker.com/reference/cli/dockerd/#configure-cdi-devices) and Buildx v0.22+.

You also need to create the [device specifications using JSON or YAML files](https://github.com/cncf-tags/container-device-interface/blob/main/SPEC.md#cdi-json-specification) in one of the following locations:

* `/etc/cdi`
* `/var/run/cdi`
* `/etc/buildkit/cdi`

> Note
>
> Location can be changed by setting the `specDirs` option in the `cdi` section of the [`buildkitd.toml` configuration file](https://docs.docker.com/build/buildkit/configure/) if you are using BuildKit directly. If you're building using the Docker Daemon with the `docker` driver, see [Configure CDI devices](https://docs.docker.com/reference/cli/dockerd/#configure-cdi-devices) documentation.

> Note
>
> If you are creating a container builder on WSL, you need to ensure that [Docker Desktop](https://docs.docker.com/desktop/) is installed and [WSL 2 GPU Paravirtualization](https://docs.docker.com/desktop/features/gpu/#prerequisites) is enabled. Buildx v0.27+ is also required to mount the WSL libraries in the container.

## [Building with a simple CDI specification](#building-with-a-simple-cdi-specification)

Let's start with a simple CDI specification that injects an environment variable into the build environment and write it to `/etc/cdi/foo.yaml`:

/etc/cdi/foo.yaml

```yaml
cdiVersion: "0.6.0"
kind: "vendor1.com/device"
devices:
- name: foo
  containerEdits:
    env:
    - FOO=injected
```

Inspect the `default` builder to verify that `vendor1.com/device` is detected as a device:

```console
$ docker buildx inspect
Name:   default
Driver: docker

Nodes:
Name:             default
Endpoint:         default
Status:           running
BuildKit version: v0.23.2
Platforms:        linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/amd64/v4, linux/386
Labels:
 org.mobyproject.buildkit.worker.moby.host-gateway-ip: 172.17.0.1
Devices:
 Name:                  vendor1.com/device=foo
 Automatically allowed: false
GC Policy rule#0:
 All:            false
 Filters:        type==source.local,type==exec.cachemount,type==source.git.checkout
 Keep Duration:  48h0m0s
 Max Used Space: 658.9MiB
GC Policy rule#1:
 All:            false
 Keep Duration:  1440h0m0s
 Reserved Space: 4.657GiB
 Max Used Space: 953.7MiB
 Min Free Space: 2.794GiB
GC Policy rule#2:
 All:            false
 Reserved Space: 4.657GiB
 Max Used Space: 953.7MiB
 Min Free Space: 2.794GiB
GC Policy rule#3:
 All:            true
 Reserved Space: 4.657GiB
 Max Used Space: 953.7MiB
 Min Free Space: 2.794GiB
```

Now let's create a Dockerfile to use this device:

```dockerfile
# syntax=docker/dockerfile:1-labs
FROM busybox
RUN --device=vendor1.com/device \
  env | grep ^FOO=
```

Here we use the [`RUN --device` command](https://docs.docker.com/reference/dockerfile/#run---device) and set `vendor1.com/device` which requests the first device available in the specification. In this case it uses `foo`, which is the first device in `/etc/cdi/foo.yaml`.

> Note
>
> [`RUN --device` command](https://docs.docker.com/reference/dockerfile/#run---device) is only featured in [`labs` channel](https://docs.docker.com/build/buildkit/frontend/#labs-channel) since [Dockerfile frontend v1.14.0-labs](https://github.com/moby/buildkit/releases/tag/dockerfile%2F1.14.0-labs) and not yet available in stable syntax.

Now let's build this Dockerfile:

```console
$ docker buildx build .
[+] Building 0.4s (5/5) FINISHED                                                                                                        docker:default
 => [internal] load build definition from Dockerfile                                                                                    0.0s 
 => => transferring dockerfile: 155B                                                                                                    0.0s
 => resolve image config for docker-image://docker/dockerfile:1-labs                                                                    0.1s 
 => CACHED docker-image://docker/dockerfile:1-labs@sha256:9187104f31e3a002a8a6a3209ea1f937fb7486c093cbbde1e14b0fa0d7e4f1b5              0.0s
 => [internal] load metadata for docker.io/library/busybox:latest                                                                       0.1s 
 => [internal] load .dockerignore                                                                                                       0.0s
 => => transferring context: 2B                                                                                                         0.0s 
ERROR: failed to build: failed to solve: failed to load LLB: device vendor1.com/device=foo is requested by the build but not allowed
```

It fails because the device `vendor1.com/device=foo` is not automatically allowed by the build as shown in the `buildx inspect` output above:

```text
Devices:
 Name:                  vendor1.com/device=foo
 Automatically allowed: false
```

To allow the device, you can use the [`--allow` flag](/reference/cli/docker/buildx/build/#allow) with the `docker buildx build` command:

```console
$ docker buildx build --allow device .
```

Or you can set the `org.mobyproject.buildkit.device.autoallow` annotation in the CDI specification to automatically allow the device for all builds:

/etc/cdi/foo.yaml

```yaml
cdiVersion: "0.6.0"
kind: "vendor1.com/device"
devices:
- name: foo
  containerEdits:
    env:
    - FOO=injected
annotations:
  org.mobyproject.buildkit.device.autoallow: true
```

Now running the build again with the `--allow device` flag:

```console
$ docker buildx build --progress=plain --allow device .
#0 building with "default" instance using docker driver

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 159B done
#1 DONE 0.0s

#2 resolve image config for docker-image://docker/dockerfile:1-labs
#2 DONE 0.1s

#3 docker-image://docker/dockerfile:1-labs@sha256:9187104f31e3a002a8a6a3209ea1f937fb7486c093cbbde1e14b0fa0d7e4f1b5
#3 CACHED

#4 [internal] load metadata for docker.io/library/busybox:latest
#4 DONE 0.1s

#5 [internal] load .dockerignore
#5 transferring context: 2B done
#5 DONE 0.0s

#6 [1/2] FROM docker.io/library/busybox:latest@sha256:f85340bf132ae937d2c2a763b8335c9bab35d6e8293f70f606b9c6178d84f42b
#6 CACHED

#7 [2/2] RUN --device=vendor1.com/device   env | grep ^FOO=
#7 0.155 FOO=injected
#7 DONE 0.2s
```

The build is successful and the output shows that the `FOO` environment variable was injected into the build environment as specified in the CDI specification.

## [Set up a container builder with GPU support](#set-up-a-container-builder-with-gpu-support)

In this section, we will show you how to set up a [container builder](https://docs.docker.com/build/builders/drivers/docker-container/) using NVIDIA GPUs. Since Buildx v0.22, when creating a new container builder, a GPU request is automatically added to the container builder if the host has GPU drivers installed in the kernel. This is similar to using [`--gpus=all` with the `docker run`](/reference/cli/docker/container/run/#gpus) command.

Now let's create a container builder named `gpubuilder` using Buildx:

```console
$ docker buildx create --name gpubuilder --driver-opt "image=moby/buildkit:buildx-stable-1-gpu" --bootstrap
#1 [internal] booting buildkit
#1 pulling image moby/buildkit:buildx-stable-1-gpu
#1 pulling image moby/buildkit:buildx-stable-1-gpu 1.0s done
#1 creating container buildx_buildkit_gpubuilder0
#1 creating container buildx_buildkit_gpubuilder0 8.8s done
#1 DONE 9.8s
gpubuilder
```

> Note
>
> We made a specially crafted BuildKit image because the current BuildKit release image is based on Alpine that doesn't support NVIDIA drivers. The following image is based on Ubuntu and installs the NVIDIA client libraries and generates the CDI specification for your GPU in the container builder if a device is requested during a build.

Let's inspect this builder:

```console
$ docker buildx inspect gpubuilder
Name:          gpubuilder
Driver:        docker-container
Last Activity: 2025-07-10 08:18:09 +0000 UTC

Nodes:
Name:                  gpubuilder0
Endpoint:              unix:///var/run/docker.sock
Driver Options:        image="moby/buildkit:buildx-stable-1-gpu"
Status:                running
BuildKit daemon flags: --allow-insecure-entitlement=network.host
BuildKit version:      v0.26.2
Platforms:             linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6
Labels:
 org.mobyproject.buildkit.worker.executor:         oci
 org.mobyproject.buildkit.worker.hostname:         d6aa9cbe8462
 org.mobyproject.buildkit.worker.network:          host
 org.mobyproject.buildkit.worker.oci.process-mode: sandbox
 org.mobyproject.buildkit.worker.selinux.enabled:  false
 org.mobyproject.buildkit.worker.snapshotter:      overlayfs
Devices:
 Name:      nvidia.com/gpu
 On-Demand: true
GC Policy rule#0:
 All:            false
 Filters:        type==source.local,type==exec.cachemount,type==source.git.checkout
 Keep Duration:  48h0m0s
 Max Used Space: 488.3MiB
GC Policy rule#1:
 All:            false
 Keep Duration:  1440h0m0s
 Reserved Space: 9.313GiB
 Max Used Space: 93.13GiB
 Min Free Space: 188.1GiB
GC Policy rule#2:
 All:            false
 Reserved Space: 9.313GiB
 Max Used Space: 93.13GiB
 Min Free Space: 188.1GiB
GC Policy rule#3:
 All:            true
 Reserved Space: 9.313GiB
 Max Used Space: 93.13GiB
 Min Free Space: 188.1GiB
```

We can see `nvidia.com/gpu` vendor is detected as a device in the builder which means that drivers were detected.

Optionally you can check if NVIDIA GPU devices are available in the container using `nvidia-smi`:

```console
$ docker exec -it buildx_buildkit_gpubuilder0 nvidia-smi -L
GPU 0: Tesla T4 (UUID: GPU-6cf00fa7-59ac-16f2-3e83-d24ccdc56f84)
```

## [Building with GPU support](#building-with-gpu-support)

Let's create a simple Dockerfile that will use the GPU device:

```dockerfile
# syntax=docker/dockerfile:1-labs
FROM ubuntu
RUN --device=nvidia.com/gpu nvidia-smi -L
```

Now run the build using the `gpubuilder` builder we created earlier:

```console
$ docker buildx --builder gpubuilder build --progress=plain .
#0 building with "gpubuilder" instance using docker-container driver
...

#7 preparing device nvidia.com/gpu
#7 0.000 > apt-get update
...
#7 4.872 > apt-get install -y gpg
...
#7 10.16 Downloading NVIDIA GPG key
#7 10.21 > apt-get update
...
#7 12.15 > apt-get install -y --no-install-recommends nvidia-container-toolkit-base
...
#7 17.80 time="2025-04-15T08:58:16Z" level=info msg="Generated CDI spec with version 0.8.0"
#7 DONE 17.8s

#8 [2/2] RUN --device=nvidia.com/gpu nvidia-smi -L
#8 0.527 GPU 0: Tesla T4 (UUID: GPU-6cf00fa7-59ac-16f2-3e83-d24ccdc56f84)
#8 DONE 1.6s
```

As you might have noticed, the step `#7` is preparing the `nvidia.com/gpu` device by installing client libraries and the toolkit to generate the CDI specifications for the GPU.

The `nvidia-smi -L` command is then executed in the container using the GPU device. The output shows the GPU UUID.

You can check the generated CDI specification within the container builder with the following command:

```console
$ docker exec -it buildx_buildkit_gpubuilder0 cat /etc/cdi/nvidia.yaml
```

For the EC2 instance [`g4dn.xlarge`](https://aws.amazon.com/ec2/instance-types/g4/) used here, it looks like this:

```yaml
cdiVersion: 0.6.0
containerEdits:
  deviceNodes:
  - path: /dev/nvidia-modeset
  - path: /dev/nvidia-uvm
  - path: /dev/nvidia-uvm-tools
  - path: /dev/nvidiactl
  env:
  - NVIDIA_VISIBLE_DEVICES=void
  hooks:
  - args:
    - nvidia-cdi-hook
    - create-symlinks
    - --link
    - ../libnvidia-allocator.so.1::/usr/lib/x86_64-linux-gnu/gbm/nvidia-drm_gbm.so
    hookName: createContainer
    path: /usr/bin/nvidia-cdi-hook
  - args:
    - nvidia-cdi-hook
    - create-symlinks
    - --link
    - libcuda.so.1::/usr/lib/x86_64-linux-gnu/libcuda.so
    hookName: createContainer
    path: /usr/bin/nvidia-cdi-hook
  - args:
    - nvidia-cdi-hook
    - enable-cuda-compat
    - --host-driver-version=570.133.20
    hookName: createContainer
    path: /usr/bin/nvidia-cdi-hook
  - args:
    - nvidia-cdi-hook
    - update-ldcache
    - --folder
    - /usr/lib/x86_64-linux-gnu
    hookName: createContainer
    path: /usr/bin/nvidia-cdi-hook
  mounts:
  - containerPath: /run/nvidia-persistenced/socket
    hostPath: /run/nvidia-persistenced/socket
    options:
    - ro
    - nosuid
    - nodev
    - bind
    - noexec
  - containerPath: /usr/bin/nvidia-cuda-mps-control
    hostPath: /usr/bin/nvidia-cuda-mps-control
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/bin/nvidia-cuda-mps-server
    hostPath: /usr/bin/nvidia-cuda-mps-server
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/bin/nvidia-debugdump
    hostPath: /usr/bin/nvidia-debugdump
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/bin/nvidia-persistenced
    hostPath: /usr/bin/nvidia-persistenced
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/bin/nvidia-smi
    hostPath: /usr/bin/nvidia-smi
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libcuda.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libcuda.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libcudadebugger.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libcudadebugger.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-allocator.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-allocator.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-cfg.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-cfg.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-gpucomp.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-gpucomp.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-nscq.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-nscq.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-nvvm.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-nvvm.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-opencl.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-opencl.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-pkcs11-openssl3.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-pkcs11-openssl3.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-pkcs11.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-pkcs11.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-ptxjitcompiler.so.570.133.20
    hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-ptxjitcompiler.so.570.133.20
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /lib/firmware/nvidia/570.133.20/gsp_ga10x.bin
    hostPath: /lib/firmware/nvidia/570.133.20/gsp_ga10x.bin
    options:
    - ro
    - nosuid
    - nodev
    - bind
  - containerPath: /lib/firmware/nvidia/570.133.20/gsp_tu10x.bin
    hostPath: /lib/firmware/nvidia/570.133.20/gsp_tu10x.bin
    options:
    - ro
    - nosuid
    - nodev
    - bind
devices:
- containerEdits:
    deviceNodes:
    - path: /dev/nvidia0
  name: "0"
- containerEdits:
    deviceNodes:
    - path: /dev/nvidia0
  name: GPU-6cf00fa7-59ac-16f2-3e83-d24ccdc56f84
- containerEdits:
    deviceNodes:
    - path: /dev/nvidia0
  name: all
kind: nvidia.com/gpu
```

Congrats on your first build using a GPU device with BuildKit and CDI.

----
url: https://docs.docker.com/subscription/change/
----

# Change your subscription

***

Table of contents

***

You can upgrade or downgrade your Docker subscription at any time to match your changing needs. This page explains how to make subscription changes and what to expect with billing and feature access.

## [Upgrade your subscription](#upgrade-your-subscription)

When you upgrade your Docker subscription, you immediately get access to all features and entitlements in your new subscription tier.

> Tip
>
> If you're upgrading from a Personal subscription to a Team subscription and want to keep your username, [convert your user account into an organization](https://docs.docker.com/admin/organization/setup/convert-account/).

To upgrade your subscription:

1. Sign in to [Docker Home](https://app.docker.com/) and select the organization you want to upgrade.

2. Select **Billing** to view your current plans.

3. Select **Browse products**.

4. Choose **View plans** from the Docker product tile on the products catalog page.

5. Choose a Docker Team or Docker Business plan for the organization.

6. Follow the on-screen instructions to complete your upgrade.

   * If you choose to pay using a US bank account, you must verify the account.
   * For more information, see [Verify a bank account](https://docs.docker.com/billing/payment-method/#verify-a-bank-account).

For detailed feature information, see [Docker Pricing](https://www.docker.com/pricing?ref=Docs\&refAction=DocsSubscriptionChange).

## [Downgrade considerations](#downgrade-considerations)

Consider the following before downgrading:

* Team size and repositories: You may need to reduce team members and convert private repositories to public or delete them based on your new subscription limits.
* SSO and SCIM: If downgrading from Docker Business and your organization uses single sign-on, remove your SSO connection and verified domains first. Organization members who were auto-provisioned through SCIM need to reset their passwords to sign in without SSO.
* Private repository collaborators: Personal subscriptions don't include collaborators for private repositories. When downgrading from Pro to Personal, all collaborators are removed and additional private repositories are locked.

For feature limits in each tier, see [Docker Pricing](https://www.docker.com/pricing?ref=Docs\&refAction=DocsSubscriptionChange).

## [Downgrade your subscription](#downgrade-your-subscription)

You can downgrade your Docker subscription at any time before the renewal date. The unused portion isn't refundable, but you retain access to paid features until the end of the current billing cycle.

To downgrade your subscription:

1. Sign in to [Docker Home](https://app.docker.com/) and select the organization you want to downgrade.
2. Select **Billing**.
3. Select the action menu, then **Cancel subscription**.
4. Fill out the feedback survey to continue with cancellation.

> Important
>
> If you have a sales-assisted Docker Business subscription, contact your account manager to downgrade your subscription.

## [Subscription pause policy](#subscription-pause-policy)

You can't pause or delay a subscription. If a subscription invoice isn't paid by the due date, there's a 15-day grace period starting from the due date.

----
url: https://docs.docker.com/compose/trust-model/
----

# Trust model for Compose files

***

Table of contents

***

Docker Compose treats every Compose file as trusted input. When a Compose file requests elevated privileges, host filesystem access, or any other configuration, Compose applies it as written. This is the same behavior as passing flags directly to `docker run`.

This means that any Compose file you run, whether it lives on your local filesystem, in a Git repository, or in an OCI registry, has full control over how containers interact with your host. The security boundary is not where the file comes from but whether you trust the author.

Evaluating trust means asking: Who authored this file? Has it changed since you last reviewed it? Do you understand every privilege it requests?

## [The dependency chain](#the-dependency-chain)

A Compose application can be assembled from multiple sources. The [`include`](https://docs.docker.com/reference/compose-file/include/) directive imports entire Compose files, while [`extends`](https://docs.docker.com/reference/compose-file/services/#extends) inherits configuration from a specific service in another file. Both support remote references and can be chained:

```text
Your command
  └─ compose.yaml                                    (local or remote)
       ├─ services, volumes, networks                (direct config)
       ├─ include:
       │    └─ oci://registry.example.com/base:v2   (remote dependency)
       │         └─ services, volumes, networks      (indirect config)
       └─ services:
            └─ app:
                 └─ extends:
                      └─ file: oci://registry.example.com/templates:v1
                           └─ service: webapp        (inherited config)
```

Each level has the same capabilities. The top-level file you inspect may appear safe while a nested `include` or `extends` introduces services with elevated privileges, host bind mounts, or untrusted images. These dependencies can also change independently. Risky settings can be introduced by a nested dependency that you never see unless you inspect the fully resolved output.

> Important
>
> Compose warns you when a configuration references remote sources. Do not accept this without understanding every reference in the chain.

## [Best practices](#best-practices)

### [Inspect the full configuration](#inspect-the-full-configuration)

To see exactly what Compose applies, including all resolved `includes`, `extends`, merged overrides, and interpolated variables, use:

```console
$ docker compose config
```

For remote references:

```console
$ docker compose -f oci://registry.example.com/myapp:latest config
```

Review this output before running `up` or `create`, especially when the configuration comes from a source you have not audited.

#### [Fields to look out for](#fields-to-look-out-for)

A Compose configuration has broad control over how containers interact with the host. The following is a non-exhaustive list of fields that carry security implications when set by an untrusted author:

| Field                   | Effect                                                      |
| ----------------------- | ----------------------------------------------------------- |
| `privileged`            | Grants the container full access to the host                |
| `cap_add`               | Adds Linux capabilities such as `SYS_ADMIN` or `NET_RAW`    |
| `security_opt`          | Configures security profiles including seccomp and AppArmor |
| `volumes` / bind mounts | Mounts host directories into the container                  |
| `network_mode: host`    | Shares the host network stack                               |
| `pid: host`             | Shares the host PID namespace                               |
| `devices`               | Exposes host devices to the container                       |
| `image`                 | Pulls and runs an arbitrary container image                 |

When in doubt, look up the effect of any unfamiliar field before running the configuration.

### [CI/CD environments](#cicd-environments)

Automated pipelines are particularly sensitive because they often run with access to credentials, cloud provider tokens, or Docker sockets.

* Avoid referencing public or unverified Compose configurations in automated pipelines.
* Gate updates behind your normal code review process.
* Use read-only Docker socket mounts where possible to limit your risk.

### [Pin remote references to digests](#pin-remote-references-to-digests)

Tags are mutable, meaning anyone with push access to a registry can overwrite a tag silently, so a reference you reviewed last week may point to different content today.

Digests are immutable. Instead of referencing by tag, pin to the digest.

```yaml
include:
  - oci://registry.example.com/base@sha256:a1b2c3d4...
```

Treat any update to a pinned digest as a code change. Make sure you review the new content before updating the reference.

### [Other](#other)

* Use a private registry: Host OCI artifacts on a registry your organization controls. Restrict who can push to it.
* Audit transitive dependencies: Check every remote `include` and `extends` reference in the chain, not just the top-level file.
* Review all Compose confirmation prompts: When loading remote Compose files, Compose displays confirmation prompts for interpolation variables, environment values, and remote includes. Review these before accepting.

## [Further reading](#further-reading)

* [OCI artifact applications](https://docs.docker.com/compose/how-tos/oci-artifact/)
* [Use Compose in production](https://docs.docker.com/compose/how-tos/production/)
* [`include` reference](https://docs.docker.com/reference/compose-file/include/)
* [`extends` reference](https://docs.docker.com/reference/compose-file/services/#extends)
* [Manage secrets in Compose](https://docs.docker.com/compose/how-tos/use-secrets/)

----
url: https://docs.docker.com/reference/api/engine/version-history/
----

# Engine API version history

***

Table of contents

***

## [v1.54 API changes](#v154-api-changes)

* `GET /images/json` now supports an `identity` query parameter. When set, the response includes manifest summaries and may include an `Identity` field for each manifest with trusted identity and origin information.
* `POST /networks/{id}/connect` now correctly applies the `MacAddress` field in `EndpointSettings`. This field was added in API v1.44, but was previously ignored.

## [v1.53 API changes](#v153-api-changes)

* `GET /info` now includes an `NRI` field. If the Node Resource Interface (NRI) is enabled, this field contains information describing it.
* `GET /events` now also supports [`application/jsonl`](https://jsonlines.org/) when negotiating content-type.
* `GET /images/{name}/json` now includes an `Identity` field with trusted identity and origin information for the image.
* Deprecated: The `POST /grpc` and `POST /session` endpoints are deprecated and will be removed in a future version.

## [v1.52 API changes](#v152-api-changes)

* `GET /images/{name}/get` now accepts multiple `platform` query-arguments to allow selecting which platform(s) of a multi-platform image must be saved.
* `POST /images/load` now accepts multiple `platform` query-arguments to allow selecting which platform(s) of a multi-platform image to load.
* `GET /events` no longer includes the deprecated `status`, `id`, and `from` fields. These fields were removed in API v1.22, but still included in the response.
* `GET /networks/{id}` now includes a `Status` field, providing statistics about IPAM allocations for the subnets assigned to the network.
* Deprecated: the Engine was automatically backfilling empty `PortBindings` lists with a PortBinding with an empty HostIP and HostPort when calling `POST /containers/{id}/start`. This behavior is now deprecated, and a warning is returned by `POST /containers/create`. A future API version will drop empty `PortBindings` list altogether.
* `GET /images/{name}/json` now omits the following `Config` fields when not set, to closer align with the implementation of the [OCI Image Specification](https://github.com/opencontainers/image-spec/blob/v1.1.1/specs-go/v1/config.go#L23-L62) `Cmd`, `Entrypoint`, `Env`, `Labels`, `OnBuild`, `User`, `Volumes`, and `WorkingDir`.
* `GET /images/{name}/json` now omits the following fields if their value is empty: `Parent`, `Comment`, `DockerVersion`, `Author`. The `Parent` and `DockerVersion` fields were set by the legacy builder, and are no longer set when using BuildKit. The `Author` field is set through the `MAINTAINER` Dockerfile instruction, which is deprecated, and the `Comment` field is option, and may not be set depending on how the image was created.
* `GET /container/{id}/json` now omits `Config.OnBuild` if its value is empty.
* `GET /containers/{id}/json`: the `NetworkSettings` no longer returns the deprecated `Bridge`, `HairpinMode`, `LinkLocalIPv6Address`, `LinkLocalIPv6PrefixLen`, `SecondaryIPAddresses`, `SecondaryIPv6Addresses`, `EndpointID`, `Gateway`, `GlobalIPv6Address`, `GlobalIPv6PrefixLen`, `IPAddress`, `IPPrefixLen`, `IPv6Gateway`, and `MacAddress` fields. These fields were deprecated in API v1.21 (docker v1.9.0) but kept around for backward compatibility.
* Removed the `KernelMemoryTCP` field from the `POST /containers/{id}/update` and `GET /containers/{id}/json` endpoints, any value it is set to will be ignored on API version `v1.52` and up. Older API versions still accept this field, but may take no effect, depending on the kernel version and OCI runtime in use.
* Removed the `KernelMemoryTCP` field from the `GET /info` endpoint.
* `GET /events` supports content-type negotiation and can produce either `application/x-ndjson` (Newline delimited JSON object stream) or `application/json-seq` (RFC7464).
* `POST /containers/create` no longer supports configuring a container-wide MAC address via the container's `Config.MacAddress` field. A container's MAC address can now only be configured via endpoint settings when connecting to a network.
* `GET /services` now returns `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements.
* `GET /services/{id}` now returns `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements.
* `POST /services/create` now accepts `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements.
* `POST /services/{id}/update` now accepts `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements.
* `GET /tasks` now returns `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements.
* `GET /tasks/{id}` now returns `SwapBytes` and `MemorySwappiness` fields as part of the `Resource` requirements.
* `GET /containers/{id}/stats` now returns an `os_type` field to allow platform- specific handling of the stats.
* `GET /system/df` returns `ImagesUsage`, `ContainersUsage`, `VolumesUsage`, and `BuildCacheUsage` fields with brief system disk usage data for each system object type. The endpoint supports the `?verbose=1` query to return verbose system disk usage information.
* Deprecated: `GET /system/df` response fields `LayersSize`, `Images`, `Containers`, `Volumes`, and `BuildCache` have been removed in favor of the-type specific usage fields. API v1.52 returns both the legacy and current fields to help existing integrations to transition to the new response. The legacy fields are not populated if the `verbose` query parameter is used. Starting with API v1.53, the legacy fields will no longer be returned.

## [v1.51 API changes](#v151-api-changes)

* `GET /images/json` now sets the value of `Containers` field for all images to the count of containers using the image. This field was previously always -1.
* Deprecated: The field `NetworkSettings.Bridge` returned by `GET /containers/{id}/json` is deprecated and will be removed in the next API version.
* Deprecated: The field `KernelMemoryTCP` as part of `POST /containers/{id}/update` and returned by `GET /containers/{id}/json` is deprecated and will be removed in the next API version.
* Deprecated: The field `KernelMemoryTCP` as part of `GET /info` is deprecated and will be removed in the next API version.
* Deprecated: the `Parent` and `DockerVersion` fields returned by the `GET /images/{name}/json` endpoint are deprecated. These fields are set by the legacy builder, and are no longer set when using BuildKit. The API continues returning these fields when set for informational purposes, but they should not be depended on as they will be omitted once the legacy builder is removed.
* Deprecated: the `Config.DockerVersion` field returned by the `GET /plugins` and `GET /images/{name}/json` endpoints is deprecated. The field is no longer set, and is omitted when empty.

## [v1.50 API changes](#v150-api-changes)

* `GET /info` now includes a `DiscoveredDevices` field. This is an array of `DeviceInfo` objects, each providing details about a device discovered by a device driver. Currently only the CDI device driver is supported.
* `DELETE /images/{name}` now supports a `platforms` query parameter. It accepts an array of JSON-encoded OCI Platform objects, allowing for selecting specific platforms to delete content for.
* Deprecated: The `BridgeNfIptables` and `BridgeNfIp6tables` fields in the `GET /info` response were deprecated in API v1.48, and are now omitted in API v1.50.
* Deprecated: `GET /images/{name}/json` no longer returns the following `Config` fields; `Hostname`, `Domainname`, `AttachStdin`, `AttachStdout`, `AttachStderr` `Tty`, `OpenStdin`, `StdinOnce`, `Image`, `NetworkDisabled` (already omitted unless set), `MacAddress` (already omitted unless set), `StopTimeout` (already omitted unless set). These additional fields were included in the response due to an implementation detail but not part of the image's Configuration. These fields were marked deprecated in API v1.46, and are now omitted. Older versions of the API still return these fields, but they are always empty.

## [v1.49 API changes](#v149-api-changes)

* `GET /images/{name}/json` now supports a `platform` parameter (JSON encoded OCI Platform type) allowing to specify a platform of the multi-platform image to inspect. This option is mutually exclusive with the `manifests` option.
* `GET /info` now returns a `FirewallBackend` containing information about the daemon's firewalling configuration.
* Deprecated: The `AllowNondistributableArtifactsCIDRs` and `AllowNondistributableArtifactsHostnames` fields in the `RegistryConfig` struct in the `GET /info` response are omitted in API v1.49.
* Deprecated: The `ContainerdCommit.Expected`, `RuncCommit.Expected`, and `InitCommit.Expected` fields in the `GET /info` endpoint were deprecated in API v1.48, and are now omitted in API v1.49.

## [v1.48 API changes](#v148-api-changes)

* Deprecated: The "error" and "progress" fields in streaming responses for endpoints that return a JSON progress response, such as `POST /images/create`, `POST /images/{name}/push`, and `POST /build` are deprecated. These fields were marked deprecated in API v1.4 (docker v0.6.0) and API v1.8 (docker v0.7.1) respectively, but still returned. These fields will be left empty or will be omitted in a future API version. Users should use the information in the `errorDetail` and `progressDetail` fields instead.
* Deprecated: The "allow-nondistributable-artifacts" daemon configuration is deprecated and enabled by default. The `AllowNondistributableArtifactsCIDRs` and `AllowNondistributableArtifactsHostnames` fields in the `RegistryConfig` struct in the `GET /info` response will now always be `null` and will be omitted in API v1.49.
* Deprecated: The `BridgeNfIptables` and `BridgeNfIp6tables` fields in the `GET /info` response are now always be `false` and will be omitted in API v1.49. The netfilter module is now loaded on-demand, and no longer during daemon startup, making these fields obsolete.
* Deprecated: The `POST /build/prune` `keep-storage` query parameter has been renamed to `reserved-space`. `keep-storage` support will be removed in API v1.52.
* `GET /images/{name}/history` now supports a `platform` parameter (JSON encoded OCI Platform type) that allows to specify a platform to show the history of.
* `POST /images/{name}/load` and `GET /images/{name}/get` now support a `platform` parameter (JSON encoded OCI Platform type) that allows to specify a platform to load/save. Not passing this parameter will result in loading/saving the full multi-platform image.
* `POST /containers/create` now includes a warning in the response when setting the container-wide `Config.VolumeDriver` option in combination with volumes defined through `Mounts` because the `VolumeDriver` option has no effect on those volumes. This warning was previously generated by the CLI, but now moved to the daemon so that other clients can also get this warning.
* `POST /containers/create` now supports `Mount` of type `image` for mounting an image inside a container.
* Deprecated: The `ContainerdCommit.Expected`, `RuncCommit.Expected`, and `InitCommit.Expected` fields in the `GET /info` endpoint are deprecated and will be omitted in API v1.49.
* `Sysctls` in `HostConfig` (top level `--sysctl` settings) for `eth0` are no longer migrated to `DriverOpts`, as described in the changes for v1.46.
* `GET /images/json` and `GET /images/{name}/json` responses now include `Descriptor` field, which contains an OCI descriptor of the image target. The new field will only be populated if the daemon provides a multi-platform image store. WARNING: This is experimental and may change at any time without any backward compatibility.
* `GET /images/{name}/json` response now will return the `Manifests` field containing information about the sub-manifests contained in the image index. This includes things like platform-specific manifests and build attestations. The new field will only be populated if the request also sets the `manifests` query parameter to `true`. This acts the same as in the `GET /images/json` endpoint. WARNING: This is experimental and may change at any time without any backward compatibility.
* `GET /containers/{name}/json` now returns an `ImageManifestDescriptor` field containing the OCI descriptor of the platform-specific image manifest of the image that was used to create the container. This field is only populated if the daemon provides a multi-platform image store.
* `POST /networks/create` now has an `EnableIPv4` field. Setting it to `false` disables IPv4 IPAM for the network. It can only be set to `false` if the daemon has experimental features enabled.
* `GET /networks/{id}` now returns an `EnableIPv4` field showing whether the network has IPv4 IPAM enabled.
* `POST /networks/{id}/connect` and `POST /containers/create` now accept a `GwPriority` field in `EndpointsConfig`. This value is used to determine which network endpoint provides the default gateway for the container. The endpoint with the highest priority is selected. If multiple endpoints have the same priority, endpoints are sorted lexicographically by their network name, and the one that sorts first is picked.
* `GET /containers/json` now returns a `GwPriority` field in `NetworkSettings` for each network endpoint.
* API debug endpoints (`GET /debug/vars`, `GET /debug/pprof/`, `GET /debug/pprof/cmdline`, `GET /debug/pprof/profile`, `GET /debug/pprof/symbol`, `GET /debug/pprof/trace`, `GET /debug/pprof/{name}`) are now also accessible through the versioned-API paths (`/v<API-version>/<endpoint>`).
* `POST /build/prune` renames `keep-storage` to `reserved-space` and now supports additional prune parameters `max-used-space` and `min-free-space`.
* `GET /containers/json` now returns an `ImageManifestDescriptor` field matching the same field in `/containers/{name}/json`. This field is only populated if the daemon provides a multi-platform image store.

## [v1.47 API changes](#v147-api-changes)

* `GET /images/json` response now includes `Manifests` field, which contains information about the sub-manifests included in the image index. This includes things like platform-specific manifests and build attestations. The new field will only be populated if the request also sets the `manifests` query parameter to `true`. WARNING: This is experimental and may change at any time without any backward compatibility.
* `GET /info` no longer includes warnings when `bridge-nf-call-iptables` or `bridge-nf-call-ip6tables` are disabled when the daemon was started. The `br_netfilter` module is now attempted to be loaded when needed, making those warnings inaccurate. This change is not versioned, and affects all API versions if the daemon has this patch.

## [v1.46 API changes](#v146-api-changes)

* `GET /info` now includes a `Containerd` field containing information about the location of the containerd API socket and containerd namespaces used by the daemon to run containers and plugins.
* `POST /containers/create` field `NetworkingConfig.EndpointsConfig.DriverOpts`, and `POST /networks/{id}/connect` field `EndpointsConfig.DriverOpts`, now support label `com.docker.network.endpoint.sysctls` for setting per-interface sysctls. The value is a comma separated list of sysctl assignments, the interface name must be "IFNAME". For example, to set `net.ipv4.config.eth0.log_martians=1`, use `net.ipv4.config.IFNAME.log_martians=1`. In API versions up-to 1.46, top level `--sysctl` settings for `eth0` will be migrated to `DriverOpts` when possible. This automatic migration will be removed in a future release.
* `GET /containers/json` now returns the annotations of containers.
* `POST /images/{name}/push` now supports a `platform` parameter (JSON encoded OCI Platform type) that allows selecting a specific platform manifest from the multi-platform image.
* `POST /containers/create` now takes `Options` as part of `HostConfig.Mounts.TmpfsOptions` to set options for tmpfs mounts.
* `POST /services/create` now takes `Options` as part of `ContainerSpec.Mounts.TmpfsOptions`, to set options for tmpfs mounts.
* `GET /events` now supports image `create` event that is emitted when a new image is built regardless if it was tagged or not.

#### [Deprecated Config fields in `GET /images/{name}/json` response](#deprecated-config-fields-in-get-imagesnamejson-response)

The `Config` field returned by this endpoint (used for "image inspect") returns additional fields that are not part of the image's configuration and not part of the [Docker Image Spec](https://github.com/moby/docker-image-spec/blob/v1.3.1/specs-go/v1/image.go#L19-L32) and the [OCI Image Spec](https://github.com/opencontainers/image-spec/blob/v1.1.0/specs-go/v1/config.go#L24-L62).

These additional fields are included in the response, due to an implementation detail, where the [api/types.ImageInspec](https://github.com/moby/moby/blob/v26.1.4/api/types/types.go#L87-L104) type used for the response is using the [container.Config](https://github.com/moby/moby/blob/v26.1.4/api/types/container/config.go#L47-L82) type.

The [container.Config](https://github.com/moby/moby/blob/v26.1.4/api/types/container/config.go#L47-L82) type is a superset of the image config, and while the image's Config is used as a *template* for containers created from the image, the additional fields are set at runtime (from options passed when creating the container) and not taken from the image Config.

These fields are never set (and always return the default value for the type), but are not omitted in the response when left empty. As these fields were not intended to be part of the image configuration response, they are deprecated, and will be removed from the API.

The following fields are currently included in the API response, but are not part of the underlying image's Config, and deprecated:

- `POST /services/create` and `POST /services/{id}/update` now support OomScoreAdj

## [v1.45 API changes](#v145-api-changes)

* `POST /containers/create` now supports `VolumeOptions.Subpath` which allows a subpath of a named volume to be mounted.
* `POST /images/search` will always assume a `false` value for the `is-automated` field. Consequently, searching for `is-automated=true` will yield no results, while `is-automated=false` will be a no-op.
* `GET /images/{name}/json` no longer includes the `Container` and `ContainerConfig` fields. To access image configuration, use `Config` field instead.
* The `Aliases` field returned in calls to `GET /containers/{name:.*}/json` no longer contains the short container ID, but instead will reflect exactly the values originally submitted to the `POST /containers/create` endpoint. The newly introduced `DNSNames` should now be used instead when short container IDs are needed.

## [v1.44 API changes](#v144-api-changes)

* GET `/images/json` now accepts an `until` filter. This accepts a timestamp and lists all images created before it. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. This change is not versioned, and affects all API versions if the daemon has this patch.
* The `VirtualSize` field in the `GET /images/{name}/json`, `GET /images/json`, and `GET /system/df` responses is now omitted. Use the `Size` field instead, which contains the same information.
* Deprecated: The `is_automated` field in the `GET /images/search` response has been deprecated and will always be set to false in the future because Docker Hub is deprecating the `is_automated` field in its search API. The deprecation is not versioned, and applies to all API versions.
* Deprecated: The `is-automated` filter for the `GET /images/search` endpoint. The `is_automated` field has been deprecated by Docker Hub's search API. Consequently, searching for `is-automated=true` will yield no results. The deprecation is not versioned, and applies to all API versions.
* Read-only bind mounts are now made recursively read-only on kernel >= 5.12 with runtimes which support the feature. `POST /containers/create`, `GET /containers/{id}/json`, and `GET /containers/json` now supports `BindOptions.ReadOnlyNonRecursive` and `BindOptions.ReadOnlyForceRecursive` to customize the behavior.
* `POST /containers/create` now accepts a `HealthConfig.StartInterval` to set the interval for health checks during the start period.
* `GET /info` now includes a `CDISpecDirs` field indicating the configured CDI specifications directories. The use of the applied setting requires the daemon to have experimental enabled, and for non-experimental daemons an empty list is always returned.
* `POST /networks/create` now returns a 400 if the `IPAMConfig` has invalid values. Note that this change is *unversioned* and applied to all API versions on daemon that support version 1.44.
* `POST /networks/create` with a duplicated name now fails systematically. As such, the `CheckDuplicate` field is now deprecated. Note that this change is *unversioned* and applied to all API versions on daemon that support version 1.44.
* `POST /containers/create` now accepts multiple `EndpointSettings` in `NetworkingConfig.EndpointSettings`.
* `POST /containers/create` and `POST /networks/{id}/connect` will now catch validation errors that were previously only returned during `POST /containers/{id}/start`. These endpoints will also return the full set of validation errors they find, instead of returning only the first one. Note that this change is *unversioned* and applies to all API versions.
* `POST /services/create` and `POST /services/{id}/update` now accept `Seccomp` and `AppArmor` fields in the `ContainerSpec.Privileges` object. This allows some configuration of Seccomp and AppArmor in Swarm services.
* A new endpoint-specific `MacAddress` field has been added to `NetworkSettings.EndpointSettings` on `POST /containers/create`, and to `EndpointConfig` on `POST /networks/{id}/connect`. The container-wide `MacAddress` field in `Config`, on `POST /containers/create`, is now deprecated.
* The field `Networks` in the `POST /services/create` and `POST /services/{id}/update` requests is now deprecated. You should instead use the field `TaskTemplate.Networks`.
* The `Container` and `ContainerConfig` fields in the `GET /images/{name}/json` response are deprecated and will no longer be included in API v1.45.
* `GET /info` now includes `status` properties in `Runtimes`.
* A new field named `DNSNames` and containing all non-fully qualified DNS names a container takes on a specific network has been added to `GET /containers/{name:.*}/json`.
* The `Aliases` field returned in calls to `GET /containers/{name:.*}/json` in v1.44 and older versions contains the short container ID. This will change in the next API version, v1.45. Starting with that API version, this specific value will be removed from the `Aliases` field such that this field will reflect exactly the values originally submitted to the `POST /containers/create` endpoint. The newly introduced `DNSNames` should now be used instead.
* The fields `HairpinMode`, `LinkLocalIPv6Address`, `LinkLocalIPv6PrefixLen`, `SecondaryIPAddresses`, `SecondaryIPv6Addresses` available in `NetworkSettings` when calling `GET /containers/{id}/json` are deprecated and will be removed in a future release. You should instead look for the default network in `NetworkSettings.Networks`.
* `GET /images/{id}/json` omits the `Created` field (previously it was `0001-01-01T00:00:00Z`) if the `Created` field is missing from the image config.

## [v1.43 API changes](#v143-api-changes)

* `POST /containers/create` now accepts `Annotations` as part of `HostConfig`. Can be used to attach arbitrary metadata to the container, which will also be passed to the runtime when the container is started.
* `GET /images/json` no longer includes hardcoded `<none>:<none>` and `<none>@<none>` in `RepoTags` and`RepoDigests` for untagged images. In such cases, empty arrays will be produced instead.
* The `VirtualSize` field in the `GET /images/{name}/json`, `GET /images/json`, and `GET /system/df` responses is deprecated and will no longer be included in API v1.44. Use the `Size` field instead, which contains the same information.
* `GET /info` now includes `no-new-privileges` in the `SecurityOptions` string list when this option is enabled globally. This change is not versioned, and affects all API versions if the daemon has this patch.

## [v1.42 API changes](#v142-api-changes)

* Removed the `BuilderSize` field on the `GET /system/df` endpoint. This field was introduced in API 1.31 as part of an experimental feature, and no longer used since API 1.40. Use field `BuildCache` instead to track storage used by the builder component.

* `POST /containers/{id}/stop` and `POST /containers/{id}/restart` now accept a `signal` query parameter, which allows overriding the container's default stop- signal.

* `GET /images/json` now accepts query parameter `shared-size`. When set `true`, images returned will include `SharedSize`, which provides the size on disk shared with other images present on the system.

* `GET /system/df` now accepts query parameter `type`. When set, computes and returns data only for the specified object type. The parameter can be specified multiple times to select several object types. Supported values are: `container`, `image`, `volume`, `build-cache`.

* `GET /system/df` can now be used concurrently. If a request is made while a previous request is still being processed, the request will receive the result of the already running calculation, once completed. Previously, an error (`a disk usage operation is already running`) would be returned in this situation. This change is not versioned, and affects all API versions if the daemon has this patch.

* The `POST /images/create` now supports both the operating system and architecture that is passed through the `platform` query parameter when using the `fromSrc` option to import an image from an archive. Previously, only the operating system was used and the architecture was ignored. If no `platform` option is set, the host's operating system and architecture as used as default. This change is not versioned, and affects all API versions if the daemon has this patch.

* The `POST /containers/{id}/wait` endpoint now returns a `400` status code if an invalid `condition` is provided (on API 1.30 and up).

* Removed the `KernelMemory` field from the `POST /containers/create` and `POST /containers/{id}/update` endpoints, any value it is set to will be ignored on API version `v1.42` and up. Older API versions still accept this field, but may take no effect, depending on the kernel version and OCI runtime in use.

* `GET /containers/{id}/json` now omits the `KernelMemory` and `KernelMemoryTCP` if they are not set.

* `GET /info` now omits the `KernelMemory` and `KernelMemoryTCP` if they are not supported by the host or host's configuration (if cgroups v2 are in use).

* `GET /_ping` and `HEAD /_ping` now return `Builder-Version` by default. This header contains the default builder to use, and is a recommendation as advertised by the daemon. However, it is up to the client to choose which builder to use.

  The default value on Linux is version "2" (BuildKit), but the daemon can be configured to recommend version "1" (classic Builder). Windows does not yet support BuildKit for native Windows images, and uses "1" (classic builder) as a default.

  This change is not versioned, and affects all API versions if the daemon has this patch.

* `GET /_ping` and `HEAD /_ping` now return a `Swarm` header, which allows a client to detect if Swarm is enabled on the daemon, without having to call additional endpoints. This change is not versioned, and affects all API versions if the daemon has this patch. Clients must consider this header "optional", and fall back to using other endpoints to get this information if the header is not present.

  The `Swarm` header can contain one of the following values:

  * "inactive"
  * "pending"
  * "error"
  * "locked"
  * "active/worker"
  * "active/manager"

* `POST /containers/create` for Windows containers now accepts a new syntax in `HostConfig.Resources.Devices.PathOnHost`. As well as the existing `class/<GUID>` syntax, `<IDType>://<ID>` is now recognised. Support for specific `<IDType>` values depends on the underlying implementation and Windows version. This change is not versioned, and affects all API versions if the daemon has this patch.

* `GET /containers/{id}/attach`, `GET /exec/{id}/start`, `GET /containers/{id}/logs` `GET /services/{id}/logs` and `GET /tasks/{id}/logs` now set Content-Type header to `application/vnd.docker.multiplexed-stream` when a multiplexed stdout/stderr stream is sent to client, `application/vnd.docker.raw-stream` otherwise.

* `POST /volumes/create` now accepts a new `ClusterVolumeSpec` to create a cluster volume (CNI). This option can only be used if the daemon is a Swarm manager. The Volume response on creation now also can contain a `ClusterVolume` field with information about the created volume.

* The `BuildCache.Parent` field, as returned by `GET /system/df` is deprecated and is now omitted. API versions before v1.42 continue to include this field.

* `GET /system/df` now includes a new `Parents` field, for "build-cache" records, which contains a list of parent IDs for the build-cache record.

* Volume information returned by `GET /volumes/{name}`, `GET /volumes` and `GET /system/df` can now contain a `ClusterVolume` if the volume is a cluster volume (requires the daemon to be a Swarm manager).

* The `Volume` type, as returned by `Added new `ClusterVolume\` fields

* Added a new `PUT /volumes{name}` endpoint to update cluster volumes (CNI). Cluster volumes are only supported if the daemon is a Swarm manager.

* `GET /containers/{name}/attach/ws` endpoint now accepts `stdin`, `stdout` and `stderr` query parameters to only attach to configured streams.

  NOTE: These parameters were documented before in older API versions, but not actually supported. API versions before v1.42 continue to ignore these parameters and default to attaching to all streams. To preserve the pre-v1.42 behavior, set all three query parameters (`?stdin=1,stdout=1,stderr=1`).

* `POST /containers/create` on Linux now respects the `HostConfig.ConsoleSize` property. Container is immediately created with the desired terminal size and clients no longer need to set the desired size on their own.

* `POST /containers/create` allow to set `CreateMountpoint` for host path to be created if missing. This brings parity with `Binds`

* `POST /containers/create` rejects request if BindOptions|VolumeOptions|TmpfsOptions is set with a non-matching mount Type.

* `POST /containers/{id}/exec` now accepts an optional `ConsoleSize` parameter. It allows to set the console size of the executed process immediately when it's created.

* `POST /volumes/prune` will now only prune "anonymous" volumes (volumes which were not given a name) by default. A new filter parameter `all` can be set to a truth-y value (`true`, `1`) to get the old behavior.

## [v1.41 API changes](#v141-api-changes)

* `GET /events` now returns `prune` events after pruning resources have completed. Prune events are returned for `container`, `network`, `volume`, `image`, and `builder`, and have a `reclaimed` attribute, indicating the amount of space reclaimed (in bytes).

* `GET /info` now returns a `CgroupVersion` field, containing the cgroup version.

* `GET /info` now returns a `DefaultAddressPools` field, containing a list of custom default address pools for local networks, which can be specified in the `daemon.json` file or `--default-address-pool` dockerd option.

* `POST /services/create` and `POST /services/{id}/update` now supports `BindOptions.NonRecursive`.

* The `ClusterStore` and `ClusterAdvertise` fields in `GET /info` are deprecated and are now omitted if they contain an empty value. This change is not versioned, and affects all API versions if the daemon has this patch.

* The `filter` (singular) query parameter, which was deprecated in favor of the `filters` option in Docker 1.13, has now been removed from the `GET /images/json` endpoint. The parameter remains available when using API version 1.40 or below.

* `GET /services` now returns `CapAdd` and `CapDrop` as part of the `ContainerSpec`.

* `GET /services/{id}` now returns `CapAdd` and `CapDrop` as part of the `ContainerSpec`.

* `POST /services/create` now accepts `CapAdd` and `CapDrop` as part of the `ContainerSpec`.

* `POST /services/{id}/update` now accepts `CapAdd` and `CapDrop` as part of the `ContainerSpec`.

* `GET /tasks` now returns `CapAdd` and `CapDrop` as part of the `ContainerSpec`.

* `GET /tasks/{id}` now returns `CapAdd` and `CapDrop` as part of the `ContainerSpec`.

* `GET /services` now returns `Pids` in `TaskTemplate.Resources.Limits`.

* `GET /services/{id}` now returns `Pids` in `TaskTemplate.Resources.Limits`.

* `POST /services/create` now accepts `Pids` in `TaskTemplate.Resources.Limits`.

* `POST /services/{id}/update` now accepts `Pids` in `TaskTemplate.Resources.Limits` to limit the maximum number of PIDs.

* `GET /tasks` now returns `Pids` in `TaskTemplate.Resources.Limits`.

* `GET /tasks/{id}` now returns `Pids` in `TaskTemplate.Resources.Limits`.

* `POST /containers/create` now accepts a `platform` query parameter in the format `os[/arch[/variant]]`.

  When set, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.

  If the option is *not* set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image *does* exist in the local image cache, but its OS or architecture do not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;

  ```
  WARNING: The requested image's platform (linux/arm64/v8) does not
           match the detected host platform (linux/amd64) and no
           specific platform was requested
  ```

* `POST /containers/create` on Linux now accepts the `HostConfig.CgroupnsMode` property. Set the property to `host` to create the container in the daemon's cgroup namespace, or `private` to create the container in its own private cgroup namespace. The per-daemon default is `host`, and can be changed by using the`CgroupNamespaceMode` daemon configuration parameter.

* `GET /info` now returns an `OSVersion` field, containing the operating system's version. This change is not versioned, and affects all API versions if the daemon has this patch.

* `GET /info` no longer returns the `SystemStatus` field if it does not have a value set. This change is not versioned, and affects all API versions if the daemon has this patch.

* `GET /services` now accepts query parameter `status`. When set `true`, services returned will include `ServiceStatus`, which provides Desired, Running, and Completed task counts for the service.

* `GET /services` may now include `ReplicatedJob` or `GlobalJob` as the `Mode` in a `ServiceSpec`.

* `GET /services/{id}` may now include `ReplicatedJob` or `GlobalJob` as the `Mode` in a `ServiceSpec`.

* `POST /services/create` now accepts `ReplicatedJob or `GlobalJob`as the`Mode`in the`ServiceSpec.

* `POST /services/{id}/update` accepts updating the fields of the `ReplicatedJob` object in the `ServiceSpec.Mode`. The service mode still cannot be changed, however.

* `GET /services` now includes `JobStatus` on Services with mode `ReplicatedJob` or `GlobalJob`.

* `GET /services/{id}` now includes `JobStatus` on Services with mode `ReplicatedJob` or `GlobalJob`.

* `GET /tasks` now includes `JobIteration` on Tasks spawned from a job-mode service.

* `GET /tasks/{id}` now includes `JobIteration` on the task if spawned from a job-mode service.

* `GET /containers/{id}/stats` now accepts a query param (`one-shot`) which, when used with `stream=false` fetches a single set of stats instead of waiting for two collection cycles to have 2 CPU stats over a 1 second period.

* The `KernelMemory` field in `HostConfig.Resources` is now deprecated.

* The `KernelMemory` field in `Info` is now deprecated.

* `GET /services` now returns `Ulimits` as part of `ContainerSpec`.

* `GET /services/{id}` now returns `Ulimits` as part of `ContainerSpec`.

* `POST /services/create` now accepts `Ulimits` as part of `ContainerSpec`.

* `POST /services/{id}/update` now accepts `Ulimits` as part of `ContainerSpec`.

## [v1.40 API changes](#v140-api-changes)

* The `/_ping` endpoint can now be accessed both using `GET` or `HEAD` requests. when accessed using a `HEAD` request, all headers are returned, but the body is empty (`Content-Length: 0`). This change is not versioned, and affects all API versions if the daemon has this patch. Clients are recommended to try using `HEAD`, but fallback to `GET` if the `HEAD` requests fails.
* `GET /_ping` and `HEAD /_ping` now set `Cache-Control` and `Pragma` headers to prevent the result from being cached. This change is not versioned, and affects all API versions if the daemon has this patch.
* `GET /services` now returns `Sysctls` as part of the `ContainerSpec`.
* `GET /services/{id}` now returns `Sysctls` as part of the `ContainerSpec`.
* `POST /services/create` now accepts `Sysctls` as part of the `ContainerSpec`.
* `POST /services/{id}/update` now accepts `Sysctls` as part of the `ContainerSpec`.
* `POST /services/create` now accepts `Config` as part of `ContainerSpec.Privileges.CredentialSpec`.
* `POST /services/{id}/update` now accepts `Config` as part of `ContainerSpec.Privileges.CredentialSpec`.
* `POST /services/create` now includes `Runtime` as an option in `ContainerSpec.Configs`
* `POST /services/{id}/update` now includes `Runtime` as an option in `ContainerSpec.Configs`
* `GET /tasks` now returns `Sysctls` as part of the `ContainerSpec`.
* `GET /tasks/{id}` now returns `Sysctls` as part of the `ContainerSpec`.
* `GET /networks` now supports a `dangling` filter type. When set to `true` (or `1`), the endpoint returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
* `GET /nodes` now supports a filter type `node.label` filter to filter nodes based on the node.label. The format of the label filter is `node.label=<key>`/`node.label=<key>=<value>` to return those with the specified labels, or `node.label!=<key>`/`node.label!=<key>=<value>` to return those without the specified labels.
* `POST /containers/create` now accepts a `fluentd-async` option in `HostConfig.LogConfig.Config` when using the Fluentd logging driver. This option deprecates the `fluentd-async-connect` option, which remains functional, but will be removed in a future release. Users are encouraged to use the `fluentd-async` option going forward. This change is not versioned, and affects all API versions if the daemon has this patch.
* `POST /containers/create` now accepts a `fluentd-request-ack` option in `HostConfig.LogConfig.Config` when using the Fluentd logging driver. If enabled, the Fluentd logging driver sends the chunk option with a unique ID. The server will respond with an acknowledgement. This option improves the reliability of the message transmission. This change is not versioned, and affects all API versions if the daemon has this patch.
* `POST /containers/create`, `GET /containers/{id}/json`, and `GET /containers/json` now supports `BindOptions.NonRecursive`.
* `POST /swarm/init` now accepts a `DataPathPort` property to set data path port number.
* `GET /info` now returns information about `DataPathPort` that is currently used in swarm
* `GET /info` now returns `PidsLimit` boolean to indicate if the host kernel has PID limit support enabled.
* `GET /info` now includes `name=rootless` in `SecurityOptions` when the daemon is running in rootless mode. This change is not versioned, and affects all API versions if the daemon has this patch.
* `GET /info` now returns `none` as `CgroupDriver` when the daemon is running in rootless mode. This change is not versioned, and affects all API versions if the daemon has this patch.
* `POST /containers/create` now accepts `DeviceRequests` as part of `HostConfig`. Can be used to set Nvidia GPUs.
* `GET /swarm` endpoint now returns DataPathPort info
* `POST /containers/create` now takes `KernelMemoryTCP` field to set hard limit for kernel TCP buffer memory.
* `GET /service` now returns `MaxReplicas` as part of the `Placement`.
* `GET /service/{id}` now returns `MaxReplicas` as part of the `Placement`.
* `POST /service/create` and `POST /services/(id or name)/update` now take the field `MaxReplicas` as part of the service `Placement`, allowing to specify maximum replicas per node for the service.
* `POST /containers/create` on Linux now creates a container with `HostConfig.IpcMode=private` by default, if IpcMode is not explicitly specified. The per-daemon default can be changed back to `shareable` by using `DefaultIpcMode` daemon configuration parameter.
* `POST /containers/{id}/update` now accepts a `PidsLimit` field to tune a container's PID limit. Set `0` or `-1` for unlimited. Leave `null` to not change the current value.
* `POST /build` now accepts `outputs` key for configuring build outputs when using BuildKit mode.

## [V1.39 API changes](#v139-api-changes)

* `GET /info` now returns an empty string, instead of `<unknown>` for `KernelVersion` and `OperatingSystem` if the daemon was unable to obtain this information.
* `GET /info` now returns information about the product license, if a license has been applied to the daemon.
* `GET /info` now returns a `Warnings` field, containing warnings and informational messages about missing features, or issues related to the daemon configuration.
* `POST /swarm/init` now accepts a `DefaultAddrPool` property to set global scope default address pool
* `POST /swarm/init` now accepts a `SubnetSize` property to set global scope networks by giving the length of the subnet masks for every such network
* `POST /session` (added in [V1.31](#v131-api-changes) is no longer experimental. This endpoint can be used to run interactive long-running protocols between the client and the daemon.

## [V1.38 API changes](#v138-api-changes)

* `GET /tasks` and `GET /tasks/{id}` now return a `NetworkAttachmentSpec` field, containing the `ContainerID` for non-service containers connected to "attachable" swarm-scoped networks.

## [v1.37 API changes](#v137-api-changes)

* `POST /containers/create` and `POST /services/create` now supports exposing SCTP ports.
* `POST /configs/create` and `POST /configs/{id}/create` now accept a `Templating` driver.
* `GET /configs` and `GET /configs/{id}` now return the `Templating` driver of the config.
* `POST /secrets/create` and `POST /secrets/{id}/create` now accept a `Templating` driver.
* `GET /secrets` and `GET /secrets/{id}` now return the `Templating` driver of the secret.

## [v1.36 API changes](#v136-api-changes)

* `Get /events` now return `exec_die` event when an exec process terminates.

## [v1.35 API changes](#v135-api-changes)

* `POST /services/create` and `POST /services/(id)/update` now accepts an `Isolation` field on container spec to set the Isolation technology of the containers running the service (`default`, `process`, or `hyperv`). This configuration is only used for Windows containers.
* `GET /containers/(name)/logs` now supports an additional query parameter: `until`, which returns log lines that occurred before the specified timestamp.
* `POST /containers/{id}/exec` now accepts a `WorkingDir` property to set the work-dir for the exec process, independent of the container's work-dir.
* `Get /version` now returns a `Platform.Name` field, which can be used by products using Moby as a foundation to return information about the platform.
* `Get /version` now returns a `Components` field, which can be used to return information about the components used. Information about the engine itself is now included as a "Component" version, and contains all information from the top-level `Version`, `GitCommit`, `APIVersion`, `MinAPIVersion`, `GoVersion`, `Os`, `Arch`, `BuildTime`, `KernelVersion`, and `Experimental` fields. Going forward, the information from the `Components` section is preferred over their top-level counterparts.

## [v1.34 API changes](#v134-api-changes)

* `POST /containers/(name)/wait?condition=removed` now also also returns in case of container removal failure. A pointer to a structure named `Error` added to the response JSON in order to indicate a failure. If `Error` is `null`, container removal has succeeded, otherwise the test of an error message indicating why container removal has failed is available from `Error.Message` field.

## [v1.33 API changes](#v133-api-changes)

* `GET /events` now supports filtering 4 more kinds of events: `config`, `node`, `secret` and `service`.

## [v1.32 API changes](#v132-api-changes)

* `POST /images/create` now accepts a `platform` parameter in the form of `os[/arch[/variant]]`.
* `POST /containers/create` now accepts additional values for the `HostConfig.IpcMode` property. New values are `private`, `shareable`, and `none`.
* `DELETE /networks/{id or name}` fixed issue where a `name` equal to another network's name was able to mask that `id`. If both a network with the given *name* exists, and a network with the given *id*, the network with the given *id* is now deleted. This change is not versioned, and affects all API versions if the daemon has this patch.

## [v1.31 API changes](#v131-api-changes)

* `DELETE /secrets/(name)` now returns status code 404 instead of 500 when the secret does not exist.
* `POST /secrets/create` now returns status code 409 instead of 500 when creating an already existing secret.
* `POST /secrets/create` now accepts a `Driver` struct, allowing the `Name` and driver-specific `Options` to be passed to store a secrets in an external secrets store. The `Driver` property can be omitted if the default (internal) secrets store is used.
* `GET /secrets/(id)` and `GET /secrets` now return a `Driver` struct, containing the `Name` and driver-specific `Options` of the external secrets store used to store the secret. The `Driver` property is omitted if no external store is used.
* `POST /secrets/(name)/update` now returns status code 400 instead of 500 when updating a secret's content which is not the labels.
* `POST /nodes/(name)/update` now returns status code 400 instead of 500 when demoting last node fails.
* `GET /networks/(id or name)` now takes an optional query parameter `scope` that will filter the network based on the scope (`local`, `swarm`, or `global`).
* `POST /session` is a new endpoint that can be used for running interactive long-running protocols between client and the daemon. This endpoint is experimental and only available if the daemon is started with experimental features enabled.
* `GET /images/(name)/get` now includes an `ImageMetadata` field which contains image metadata that is local to the engine and not part of the image config.
* `POST /services/create` now accepts a `PluginSpec` when `TaskTemplate.Runtime` is set to `plugin`
* `GET /events` now supports config events `create`, `update` and `remove` that are emitted when users create, update or remove a config
* `GET /volumes/` and `GET /volumes/{name}` now return a `CreatedAt` field, containing the date/time the volume was created. This field is omitted if the creation date/time for the volume is unknown. For volumes with scope "global", this field represents the creation date/time of the local *instance* of the volume, which may differ from instances of the same volume on different nodes.
* `GET /system/df` now returns a `CreatedAt` field for `Volumes`. Refer to the `/volumes/` endpoint for a description of this field.

## [v1.30 API changes](#v130-api-changes)

* `GET /info` now returns the list of supported logging drivers, including plugins.
* `GET /info` and `GET /swarm` now returns the cluster-wide swarm CA info if the node is in a swarm: the cluster root CA certificate, and the cluster TLS leaf certificate issuer's subject and public key. It also displays the desired CA signing certificate, if any was provided as part of the spec.
* `POST /build/` now (when not silent) produces an `Aux` message in the JSON output stream with payload `types.BuildResult` for each image produced. The final such message will reference the image resulting from the build.
* `GET /nodes` and `GET /nodes/{id}` now returns additional information about swarm TLS info if the node is part of a swarm: the trusted root CA, and the issuer's subject and public key.
* `GET /distribution/(name)/json` is a new endpoint that returns a JSON output stream with payload `types.DistributionInspect` for an image name. It includes a descriptor with the digest, and supported platforms retrieved from directly contacting the registry.
* `POST /swarm/update` now accepts 3 additional parameters as part of the swarm spec's CA configuration; the desired CA certificate for the swarm, the desired CA key for the swarm (if not using an external certificate), and an optional parameter to force swarm to generate and rotate to a new CA certificate/key pair.
* `POST /service/create` and `POST /services/(id or name)/update` now take the field `Platforms` as part of the service `Placement`, allowing to specify platforms supported by the service.
* `POST /containers/(name)/wait` now accepts a `condition` query parameter to indicate which state change condition to wait for. Also, response headers are now returned immediately to acknowledge that the server has registered a wait callback for the client.
* `POST /swarm/init` now accepts a `DataPathAddr` property to set the IP-address or network interface to use for data traffic
* `POST /swarm/join` now accepts a `DataPathAddr` property to set the IP-address or network interface to use for data traffic
* `GET /events` now supports service, node and secret events which are emitted when users create, update and remove service, node and secret
* `GET /events` now supports network remove event which is emitted when users remove a swarm scoped network
* `GET /events` now supports a filter type `scope` in which supported value could be swarm and local
* `PUT /containers/(name)/archive` now accepts a `copyUIDGID` parameter to allow copy UID/GID maps to dest file or dir.

## [v1.29 API changes](#v129-api-changes)

* `DELETE /networks/(name)` now allows to remove the ingress network, the one used to provide the routing-mesh.
* `POST /networks/create` now supports creating the ingress network, by specifying an `Ingress` boolean field. As of now this is supported only when using the overlay network driver.
* `GET /networks/(name)` now returns an `Ingress` field showing whether the network is the ingress one.
* `GET /networks/` now supports a `scope` filter to filter networks based on the network mode (`swarm`, `global`, or `local`).
* `POST /containers/create`, `POST /service/create` and `POST /services/(id or name)/update` now takes the field `StartPeriod` as a part of the `HealthConfig` allowing for specification of a period during which the container should not be considered unhealthy even if health checks do not pass.
* `GET /services/(id)` now accepts an `insertDefaults` query-parameter to merge default values into the service inspect output.
* `POST /containers/prune`, `POST /images/prune`, `POST /volumes/prune`, and `POST /networks/prune` now support a `label` filter to filter containers, images, volumes, or networks based on the label. The format of the label filter could be `label=<key>`/`label=<key>=<value>` to remove those with the specified labels, or `label!=<key>`/`label!=<key>=<value>` to remove those without the specified labels.
* `POST /services/create` now accepts `Privileges` as part of `ContainerSpec`. Privileges currently include `CredentialSpec` and `SELinuxContext`.

## [v1.28 API changes](#v128-api-changes)

* `POST /containers/create` now includes a `Consistency` field to specify the consistency level for each `Mount`, with possible values `default`, `consistent`, `cached`, or `delegated`.
* `GET /containers/create` now takes a `DeviceCgroupRules` field in `HostConfig` allowing to set custom device cgroup rules for the created container.
* Optional query parameter `verbose` for `GET /networks/(id or name)` will now list all services with all the tasks, including the non-local tasks on the given network.
* `GET /containers/(id or name)/attach/ws` now returns WebSocket in binary frame format for API version >= v1.28, and returns WebSocket in text frame format for API version< v1.28, for the purpose of backward-compatibility.
* `GET /networks` is optimised only to return list of all networks and network specific information. List of all containers attached to a specific network is removed from this API and is only available using the network specific `GET /networks/{network-id}`.
* `GET /containers/json` now supports `publish` and `expose` filters to filter containers that expose or publish certain ports.
* `POST /services/create` and `POST /services/(id or name)/update` now accept the `ReadOnly` parameter, which mounts the container's root filesystem as read only.
* `POST /build` now accepts `extrahosts` parameter to specify a host to ip mapping to use during the build.
* `POST /services/create` and `POST /services/(id or name)/update` now accept a `rollback` value for `FailureAction`.
* `POST /services/create` and `POST /services/(id or name)/update` now accept an optional `RollbackConfig` object which specifies rollback options.
* `GET /services` now supports a `mode` filter to filter services based on the service mode (either `global` or `replicated`).
* `POST /containers/(name)/update` now supports updating `NanoCpus` that represents CPU quota in units of 10-9 CPUs.
* `POST /plugins/{name}/disable` now accepts a `force` query-parameter to disable a plugin even if still in use.

## [v1.27 API changes](#v127-api-changes)

* `GET /containers/(id or name)/stats` now includes an `online_cpus` field in both `precpu_stats` and `cpu_stats`. If this field is `nil` then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

## [v1.26 API changes](#v126-api-changes)

* `POST /plugins/(plugin name)/upgrade` upgrade a plugin.

## [v1.25 API changes](#v125-api-changes)

* The API version is now required in all API calls. Instead of just requesting, for example, the URL `/containers/json`, you must now request `/v1.25/containers/json`.
* `GET /version` now returns `MinAPIVersion`.
* `POST /build` accepts `networkmode` parameter to specify network used during build.
* `GET /images/(name)/json` now returns `OsVersion` if populated
* `GET /images/(name)/json` no longer contains the `RootFS.BaseLayer` field. This field was used for Windows images that used a base-image that was pre-installed on the host (`RootFS.Type` `layers+base`), which is no longer supported, and the `RootFS.BaseLayer` field has been removed.
* `GET /info` now returns `Isolation`.
* `POST /containers/create` now takes `AutoRemove` in HostConfig, to enable auto-removal of the container on daemon side when the container's process exits.
* `GET /containers/json` and `GET /containers/(id or name)/json` now return `"removing"` as a value for the `State.Status` field if the container is being removed. Previously, "exited" was returned as status.
* `GET /containers/json` now accepts `removing` as a valid value for the `status` filter.
* `GET /containers/json` now supports filtering containers by `health` status.
* `DELETE /volumes/(name)` now accepts a `force` query parameter to force removal of volumes that were already removed out of band by the volume driver plugin.
* `POST /containers/create/` and `POST /containers/(name)/update` now validates restart policies.
* `POST /containers/create` now validates IPAMConfig in NetworkingConfig, and returns error for invalid IPv4 and IPv6 addresses (`--ip` and `--ip6` in `docker create/run`).
* `POST /containers/create` now takes a `Mounts` field in `HostConfig` which replaces `Binds`, `Volumes`, and `Tmpfs`. *note*: `Binds`, `Volumes`, and `Tmpfs` are still available and can be combined with `Mounts`.
* `POST /build` now performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. Note that this change is *unversioned* and applied to all API versions.
* `POST /build` accepts `cachefrom` parameter to specify images used for build cache.
* `GET /networks/` endpoint now correctly returns a list of *all* networks, instead of the default network if a trailing slash is provided, but no `name` or `id`.
* `DELETE /containers/(name)` endpoint now returns an error of `removal of container name is already in progress` with status code of 400, when container name is in a state of removal in progress.
* `GET /containers/json` now supports a `is-task` filter to filter containers that are tasks (part of a service in swarm mode).
* `POST /containers/create` now takes `StopTimeout` field.
* `POST /services/create` and `POST /services/(id or name)/update` now accept `Monitor` and `MaxFailureRatio` parameters, which control the response to failures during service updates.
* `POST /services/(id or name)/update` now accepts a `ForceUpdate` parameter inside the `TaskTemplate`, which causes the service to be updated even if there are no changes which would ordinarily trigger an update.
* `POST /services/create` and `POST /services/(id or name)/update` now return a `Warnings` array.
* `GET /networks/(name)` now returns field `Created` in response to show network created time.
* `POST /containers/(id or name)/exec` now accepts an `Env` field, which holds a list of environment variables to be set in the context of the command execution.
* `GET /volumes`, `GET /volumes/(name)`, and `POST /volumes/create` now return the `Options` field which holds the driver specific options to use for when creating the volume.
* `GET /exec/(id)/json` now returns `Pid`, which is the system pid for the exec'd process.
* `POST /containers/prune` prunes stopped containers.
* `POST /images/prune` prunes unused images.
* `POST /volumes/prune` prunes unused volumes.
* `POST /networks/prune` prunes unused networks.
* Every API response now includes a `Docker-Experimental` header specifying if experimental features are enabled (value can be `true` or `false`).
* Every API response now includes a `API-Version` header specifying the default API version of the server.
* The `hostConfig` option now accepts the fields `CpuRealtimePeriod` and `CpuRtRuntime` to allocate cpu runtime to rt tasks when `CONFIG_RT_GROUP_SCHED` is enabled in the kernel.
* The `SecurityOptions` field within the `GET /info` response now includes `userns` if user namespaces are enabled in the daemon.
* `GET /nodes` and `GET /node/(id or name)` now return `Addr` as part of a node's `Status`, which is the address that that node connects to the manager from.
* The `HostConfig` field now includes `NanoCpus` that represents CPU quota in units of 10-9 CPUs.
* `GET /info` now returns more structured information about security options.
* The `HostConfig` field now includes `CpuCount` that represents the number of CPUs available for execution by the container. Windows daemon only.
* `POST /services/create` and `POST /services/(id or name)/update` now accept the `TTY` parameter, which allocate a pseudo-TTY in container.
* `POST /services/create` and `POST /services/(id or name)/update` now accept the `DNSConfig` parameter, which specifies DNS related configurations in resolver configuration file (resolv.conf) through `Nameservers`, `Search`, and `Options`.
* `POST /services/create` and `POST /services/(id or name)/update` now support `node.platform.arch` and `node.platform.os` constraints in the services `TaskSpec.Placement.Constraints` field.
* `GET /networks/(id or name)` now includes IP and name of all peers nodes for swarm mode overlay networks.
* `GET /plugins` list plugins.
* `POST /plugins/pull?name=<plugin name>` pulls a plugin.
* `GET /plugins/(plugin name)` inspect a plugin.
* `POST /plugins/(plugin name)/set` configure a plugin.
* `POST /plugins/(plugin name)/enable` enable a plugin.
* `POST /plugins/(plugin name)/disable` disable a plugin.
* `POST /plugins/(plugin name)/push` push a plugin.
* `POST /plugins/create?name=(plugin name)` create a plugin.
* `DELETE /plugins/(plugin name)` delete a plugin.
* `POST /node/(id or name)/update` now accepts both `id` or `name` to identify the node to update.
* `GET /images/json` now support a `reference` filter.
* `GET /secrets` returns information on the secrets.
* `POST /secrets/create` creates a secret.
* `DELETE /secrets/{id}` removes the secret `id`.
* `GET /secrets/{id}` returns information on the secret `id`.
* `POST /secrets/{id}/update` updates the secret `id`.
* `POST /services/(id or name)/update` now accepts service name or prefix of service id as a parameter.
* `POST /containers/create` added 2 built-in log-opts that work on all logging drivers, `mode` (`blocking`|`non-blocking`), and `max-buffer-size` (e.g. `2m`) which enables a non-blocking log buffer.
* `POST /containers/create` now takes `HostConfig.Init` field to run an init inside the container that forwards signals and reaps processes.

## [v1.24 API changes](#v124-api-changes)

* `POST /containers/create` now takes `StorageOpt` field.
* `GET /info` now returns `SecurityOptions` field, showing if `apparmor`, `seccomp`, or `selinux` is supported.
* `GET /info` no longer returns the `ExecutionDriver` property. This property was no longer used after integration with ContainerD in Docker 1.11.
* `GET /networks` now supports filtering by `label` and `driver`.
* `GET /containers/json` now supports filtering containers by `network` name or id.
* `POST /containers/create` now takes `IOMaximumBandwidth` and `IOMaximumIOps` fields. Windows daemon only.
* `POST /containers/create` now returns an HTTP 400 "bad parameter" message if no command is specified (instead of an HTTP 500 "server error")
* `GET /images/search` now takes a `filters` query parameter.
* `GET /events` now supports a `reload` event that is emitted when the daemon configuration is reloaded.
* `GET /events` now supports filtering by daemon name or ID.
* `GET /events` now supports a `detach` event that is emitted on detaching from container process.
* `GET /events` now supports an `exec_detach `event that is emitted on detaching from exec process.
* `GET /images/json` now supports filters `since` and `before`.
* `POST /containers/(id or name)/start` no longer accepts a `HostConfig`.
* `POST /images/(name)/tag` no longer has a `force` query parameter.
* `GET /images/search` now supports maximum returned search results `limit`.
* `POST /containers/{name:.*}/copy` is now removed and errors out starting from this API version.
* API errors are now returned as JSON instead of plain text.
* `POST /containers/create` and `POST /containers/(id)/start` allow you to configure kernel parameters (sysctls) for use in the container.
* `POST /containers/<container ID>/exec` and `POST /exec/<exec ID>/start` no longer expects a "Container" field to be present. This property was not used and is no longer sent by the docker client.
* `POST /containers/create/` now validates the hostname (should be a valid RFC 1123 hostname).
* `POST /containers/create/` `HostConfig.PidMode` field now accepts `container:<name|id>`, to have the container join the PID namespace of an existing container.

## [v1.23 API changes](#v123-api-changes)

* `GET /containers/json` returns the state of the container, one of `created`, `restarting`, `running`, `paused`, `exited` or `dead`.
* `GET /containers/json` returns the mount points for the container.
* `GET /networks/(name)` now returns an `Internal` field showing whether the network is internal or not.
* `GET /networks/(name)` now returns an `EnableIPv6` field showing whether the network has ipv6 enabled or not.
* `POST /containers/(name)/update` now supports updating container's restart policy.
* `POST /networks/create` now supports enabling ipv6 on the network by setting the `EnableIPv6` field (doing this with a label will no longer work).
* `GET /info` now returns `CgroupDriver` field showing what cgroup driver the daemon is using; `cgroupfs` or `systemd`.
* `GET /info` now returns `KernelMemory` field, showing if "kernel memory limit" is supported.
* `POST /containers/create` now takes `PidsLimit` field, if the kernel is >= 4.3 and the pids cgroup is supported.
* `GET /containers/(id or name)/stats` now returns `pids_stats`, if the kernel is >= 4.3 and the pids cgroup is supported.
* `POST /containers/create` now allows you to override usernamespaces remapping and use privileged options for the container.
* `POST /containers/create` now allows specifying `nocopy` for named volumes, which disables automatic copying from the container path to the volume.
* `POST /auth` now returns an `IdentityToken` when supported by a registry.
* `POST /containers/create` with both `Hostname` and `Domainname` fields specified will result in the container's hostname being set to `Hostname`, rather than `Hostname.Domainname`.
* `GET /volumes` now supports more filters, new added filters are `name` and `driver`.
* `GET /containers/(id or name)/logs` now accepts a `details` query parameter to stream the extra attributes that were provided to the containers `LogOpts`, such as environment variables and labels, with the logs.
* `POST /images/load` now returns progress information as a JSON stream, and has a `quiet` query parameter to suppress progress details.

## [v1.22 API changes](#v122-api-changes)

* The `HostConfig.LxcConf` field has been removed, and is no longer available on `POST /containers/create` and `GET /containers/(id)/json`.
* `POST /container/(name)/update` updates the resources of a container.
* `GET /containers/json` supports filter `isolation` on Windows.
* `GET /containers/json` now returns the list of networks of containers.
* `GET /info` Now returns `Architecture` and `OSType` fields, providing information about the host architecture and operating system type that the daemon runs on.
* `GET /networks/(name)` now returns a `Name` field for each container attached to the network.
* `GET /version` now returns the `BuildTime` field in RFC3339Nano format to make it consistent with other date/time values returned by the API.
* `AuthConfig` now supports a `registrytoken` for token based authentication
* `POST /containers/create` now has a 4M minimum value limit for `HostConfig.KernelMemory`
* Pushes initiated with `POST /images/(name)/push` and pulls initiated with `POST /images/create` will be cancelled if the HTTP connection making the API request is closed before the push or pull completes.
* `POST /containers/create` now allows you to set a read/write rate limit for a device (in bytes per second or IO per second).
* `GET /networks` now supports filtering by `name`, `id` and `type`.
* `POST /containers/create` now allows you to set the static IPv4 and/or IPv6 address for the container.
* `POST /networks/(id)/connect` now allows you to set the static IPv4 and/or IPv6 address for the container.
* `GET /info` now includes the number of containers running, stopped, and paused.
* `POST /networks/create` now supports restricting external access to the network by setting the `Internal` field.
* `POST /networks/(id)/disconnect` now includes a `Force` option to forcefully disconnect a container from network
* `GET /containers/(id)/json` now returns the `NetworkID` of containers.
* `POST /networks/create` Now supports an options field in the IPAM config that provides options for custom IPAM plugins.
* `GET /networks/{network-id}` Now returns IPAM config options for custom IPAM plugins if any are available.
* `GET /networks/<network-id>` now returns subnets info for user-defined networks.
* `GET /info` can now return a `SystemStatus` field useful for returning additional information about applications that are built on top of engine.

## [v1.21 API changes](#v121-api-changes)

* `GET /volumes` lists volumes from all volume drivers.
* `POST /volumes/create` to create a volume.
* `GET /volumes/(name)` get low-level information about a volume.
* `DELETE /volumes/(name)` remove a volume with the specified name.
* `VolumeDriver` was moved from `config` to `HostConfig` to make the configuration portable.
* `GET /images/(name)/json` now returns information about an image's `RepoTags` and `RepoDigests`.
* The `config` option now accepts the field `StopSignal`, which specifies the signal to use to kill a container.
* `GET /containers/(id)/stats` will return networking information respectively for each interface.
* The `HostConfig` option now includes the `DnsOptions` field to configure the container's DNS options.
* `POST /build` now optionally takes a serialized map of build-time variables.
* `GET /events` now includes a `timenano` field, in addition to the existing `time` field.
* `GET /events` now supports filtering by image and container labels.
* `GET /info` now lists engine version information and return the information of `CPUShares` and `Cpuset`.
* `GET /containers/json` will return `ImageID` of the image used by container.
* `POST /exec/(name)/start` will now return an HTTP 409 when the container is either stopped or paused.
* `POST /containers/create` now takes `KernelMemory` in HostConfig to specify kernel memory limit.
* `GET /containers/(name)/json` now accepts a `size` parameter. Setting this parameter to '1' returns container size information in the `SizeRw` and `SizeRootFs` fields.
* `GET /containers/(name)/json` now returns a `NetworkSettings.Networks` field, detailing network settings per network. This field deprecates the `NetworkSettings.EndpointID`, `NetworkSettings.Gateway`, `NetworkSettings.GlobalIPv6Address`, `NetworkSettings.GlobalIPv6PrefixLen` `NetworkSettings.IPAddress`, `NetworkSettings.IPPrefixLen`, `NetworkSettings.IPv6Gateway`, `NetworkSettings.MacAddress` fields, which are still returned for backward-compatibility, but will be removed in a future version.
* `GET /exec/(id)/json` now returns a `NetworkSettings.Networks` field, detailing networksettings per network. This field deprecates the `NetworkSettings.Gateway`, `NetworkSettings.IPAddress`, `NetworkSettings.IPPrefixLen`, and `NetworkSettings.MacAddress` fields, which are still returned for backward-compatibility, but will be removed in a future version.
* The `HostConfig` option now includes the `OomScoreAdj` field for adjusting the badness heuristic. This heuristic selects which processes the OOM killer kills under out-of-memory conditions.

## [v1.20 API changes](#v120-api-changes)

* `GET /containers/(id)/archive` get an archive of filesystem content from a container.
* `PUT /containers/(id)/archive` upload an archive of content to be extracted to an existing directory inside a container's filesystem.
* `POST /containers/(id)/copy` is deprecated in favor of the above `archive` endpoint which can be used to download files and directories from a container.
* The `hostConfig` option now accepts the field `GroupAdd`, which specifies a list of additional groups that the container process will run as.

## [v1.19 API changes](#v119-api-changes)

* When the daemon detects a version mismatch with the client, usually when the client is newer than the daemon, an HTTP 400 is now returned instead of a 404.
* `GET /containers/(id)/stats` now accepts `stream` bool to get only one set of stats and disconnect.
* `GET /containers/(id)/logs` now accepts a `since` timestamp parameter.
* `GET /info` The fields `Debug`, `IPv4Forwarding`, `MemoryLimit`, and `SwapLimit` are now returned as boolean instead of as an int. In addition, the end point now returns the new boolean fields `CpuCfsPeriod`, `CpuCfsQuota`, and `OomKillDisable`.
* The `hostConfig` option now accepts the fields `CpuPeriod` and `CpuQuota`
* `POST /build` accepts `cpuperiod` and `cpuquota` options

## [v1.18 API changes](#v118-api-changes)

* `GET /version` now returns `Os`, `Arch` and `KernelVersion`.
* `POST /containers/create` and `POST /containers/(id)/start`allow you to set ulimit settings for use in the container.
* `GET /info` now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.
* `GET /images/json` added a `RepoDigests` field to include image digest information.
* `POST /build` can now set resource constraints for all containers created for the build.
* `CgroupParent` can be passed in the host config to setup container cgroups under a specific cgroup.
* `POST /build` closing the HTTP request cancels the build
* `POST /containers/(id)/exec` includes `Warnings` field to response.

### [v1.17 API changes](#v117-api-changes)

* The build supports `LABEL` command. Use this to add metadata to an image. For example you could add data describing the content of an image. `LABEL "com.example.vendor"="ACME Incorporated"`
* `POST /containers/(id)/attach` and `POST /exec/(id)/start`
* The Docker client now hints potential proxies about connection hijacking using HTTP Upgrade headers.
* `POST /containers/create` sets labels on container create describing the container.
* `GET /containers/json` returns the labels associated with the containers (`Labels`).
* `GET /containers/(id)/json` returns the list current execs associated with the container (`ExecIDs`). This endpoint now returns the container labels (`Config.Labels`).
* `POST /containers/(id)/rename` renames a container `id` to a new name.\*
* `POST /containers/create` and `POST /containers/(id)/start` callers can pass `ReadonlyRootfs` in the host config to mount the container's root filesystem as read only.
* `GET /containers/(id)/stats` returns a live stream of a container's resource usage statistics.
* `GET /images/json` returns the labels associated with each image (`Labels`).

### [v1.16 API changes](#v116-api-changes)

* `GET /info` returns the number of CPUs available on the machine (`NCPU`), total memory available (`MemTotal`), a user-friendly name describing the running Docker daemon (`Name`), a unique ID identifying the daemon (`ID`), and a list of daemon labels (`Labels`).
* `POST /containers/create` callers can set the new container's MAC address explicitly.
* Volumes are now initialized when the container is created.
* `POST /containers/(id)/copy` copies data which is contained in a volume.

### [v1.15 API changes](#v115-api-changes)

* `POST /containers/create` can now set a container's `HostConfig` when creating a container. Previously this was only available when starting a container.

### [v1.14 API changes](#v114-api-changes)

* `DELETE /containers/(id)` when using `force`, the container will be immediately killed with SIGKILL.
* `POST /containers/(id)/start` the `HostConfig` option accepts the field `CapAdd`, which specifies a list of capabilities to add, and the field `CapDrop`, which specifies a list of capabilities to drop.
* `POST /images/create` th `fromImage` and `repo` parameters support the `repo:tag` format. Consequently, the `tag` parameter is now obsolete. Using the new format and the `tag` parameter at the same time will return an error.

## [v1.13 API changes](#v113-api-changes)

* `GET /containers/(name)/json`

**New!** The `HostConfig.Links` field is now filled correctly

**New!** `Sockets` parameter added to the `/info` endpoint listing all the sockets the daemon is configured to listen on.

`POST /containers/(name)/start` `POST /containers/(name)/stop`

**New!** `start` and `stop` will now return 304 if the container's status is not modified

`POST /commit`

**New!** Added a `pause` parameter (default `true`) to pause the container during commit

## [v1.12 API changes](#v112-api-changes)

* `POST /build` now supports a `forcerm` parameter to always remove containers.
* `GET /containers/(name)/json`,`GET /images/(name)/json`: JSON keys are now in CamelCase.
* `GET /images/search`: Trusted builds are now Automated Builds, and the `is_trusted` field was renamed to `is_automated`.
* The `POST /images/(name)/insert` endpoint has been removed.

## [v1.11 API changes](#v111-api-changes)

### [What's new](#whats-new)

* Add new `GET /_ping` endpoint to check if the API server is ready to accept connections.
* `GET /events` now supports an `until` parameter to close connection after the given timestamp.
* `GET /containers/(id)/logs` is now the preferred method for getting container logs.

## [v1.10 API changes](#v110-api-changes)

* `DELETE /images/(name)` now provides a `force` parameter to force delete of an image, even if it's tagged in multiple repositories.
* `DELETE /images/(name)` now provides a `noprune` parameter to prevent the deletion of parent images.
* `DELETE /containers/(id)` now provides a `force` parameter to force deleting a container, even if it is currently running.

## [v1.9 API changes](#v19-api-changes)

* `POST /build` now takes a serialized ConfigFile which it uses to resolve the proper registry auth credentials for pulling the base image. Clients which previously implemented the version accepting an AuthConfig object must be updated.

## [v1.8 API changes](#v18-api-changes)

* `POST /build` now returns build status as JSON stream. In case of a build error, it returns the exit status of the failed command.
* `GET /containers/(id)/json` now returns the host config for the container.
* `POST /images/create`, `POST /images/(name)/insert` and `POST /images/(name)/push` now include a `progressDetail` object in the JSON. It's now possible to get the current value and the total of the progress without having to parse the string.

## [v1.7 API changes](#v17-api-changes)

* The `GET /images/viz` endpoint was removed. The `images --viz` output is now generated in the client, using the `GET /images/json` endpoint.
* The `GET /images/json` response now returns a single entry per image with a nested attribute indicating the repo/tags that apply to that image.

Instead of:

```
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "VirtualSize": 131506275,
    "Size": 131506275,
    "Created": 1365714795,
    "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
    "Tag": "12.04",
    "Repository": "ubuntu"
  },
  {
    "VirtualSize": 131506275,
    "Size": 131506275,
    "Created": 1365714795,
    "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
    "Tag": "latest",
    "Repository": "ubuntu"
  }
]
```

The returned json looks like this:

```
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
     "RepoTags": [
       "ubuntu:12.04",
       "ubuntu:latest"
     ],
     "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
     "Created": 1365714795,
     "Size": 131506275,
     "VirtualSize": 131506275
  }
]
```

## [v1.6 API changes](#v16-api-changes)

### [What's new](#whats-new-1)

* `POST /containers/(id)/attach` now provides a multiplexed response to allow splitting stderr from stdout. This is done by prefixing a header to each transmission. See the `POST /containers/(id)/attach` endpoint. The WebSocket attach is unchanged. Note that attach calls on the previous API version didn't change. Stdout and stderr are merged.

## [v1.5 API changes](#v15-api-changes)

* `POST /images/create` now accepts registry credentials via an AuthConfig object sent through the `X-Registry-Auth` header.
* `POST /images/(name)/push` now requires the `AuthConfig` object to be passed through the `X-Registry-Auth` instead of the request body.
* `GET /containers/json` changed the format of the Ports entry to a list of dicts, each containing PublicPort, PrivatePort and Type describing a port mapping.

## [v1.4 API changes](#v14-api-changes)

* `POST /images/create` now downloads all images in parallel when pulling a repo.
* `GET /containers/(id)/top` now accepts `ps` args, which is used by `docker top`, for example, `docker top <container_id> aux`.
* `GET /events` now includes the image's name.

## [v1.3 API changes](#v13-api-changes)

* Add `GET /containers/(id)/top` endpoint to list the processes running inside the container.

* Add `GET /events` endpoint to monitor docker's events via streaming or via polling.

* `GET /containers/json` now provides a `size=1` option to get the size of the containers.

* `POST /containers/<id>/start` now accepts host-specific configuration (e.g., bind mounts) in the POST body for start calls.

* `POST /build`:

  * Simplify the upload of the build context
  * Simply stream a tarball instead of multipart upload with 4 intermediary buffers
  * Simpler, less memory usage, less disk usage and faster

> **Warning**: The `POST /build` improvements are not reverse-compatible. Pre 1.3 clients will break on `POST /build`.

## [v1.2 API changes](#v12-api-changes)

* The auth configuration is now handled by the client, and clients must send authConfig as body on `POST /images/(name)/push`.
* `GET /auth` is now deprecated.
* `POST /auth` now only checks the configuration but doesn't store it on the server
* `POST /images/<name>/delete` now only untags the image if it has children and removes all the untagged parents if has any.
* `POST /images/<name>/delete` now returns a JSON structure with the list of images deleted/untagged.

## [v1.1 API changes](#v11-api-changes)

`POST /images/create`, `POST /images/(name)/insert`, and `POST /images/(name)/push` now use a JSON stream instead of HTML hijack, it looks like this:

```
HTTP/1.1 200 OK
Content-Type: application/json

{"status":"Pushing..."}
{"status":"Pushing", "progress":"1/? (n/a)"}
{"error":"Invalid..."}
...
```

## [v1.0 API changes](#v10-api-changes)

Initial version (docker [v0.3.3](https://github.com/docker/docker/commit/822056094aa31c224e78cd568e02fe5458a0eecc))

----
url: https://docs.docker.com/billing/details/
----

# Manage your billing information

***

Table of contents

***

You can update the billing information for your personal account or for an organization. When you update your billing information, these changes apply to future billing invoices. The email address you provide for a billing account is where Docker sends all invoices and other billing related communications.

> Note
>
> Existing invoices, whether paid or unpaid, cannot be updated. Changes only apply to future invoices.

## [Manage billing information](#manage-billing-information)

### [Personal account](#personal-account)

To update your billing information:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.

2. Select **Billing**.

3. Select **Billing information** from the left-hand navigation.

4. On your billing information card, select **Change**.

5. Update your billing contact and billing address information.

6. Optional. To add or update a VAT ID, select the **I'm purchasing as a business** checkbox and enter your Tax ID.

   > Important
   >
   > Your VAT number must include your country prefix. For example, if you are entering a VAT number for Germany, you would enter `DE123456789`.

7. Select **Update**.

### [Organization](#organization)

> Note
>
> You must be an organization owner to make changes to the billing information.

To update your billing information:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.

2. Select **Billing**.

3. Select **Billing information** from the left-hand navigation.

4. On your billing information card, select **Change**.

5. Update your billing contact and billing address information.

6. Optional. To add or update a VAT ID, select the **I'm purchasing as a business** checkbox and enter your Tax ID.

   > Important
   >
   > Your VAT number must include your country prefix. For example, if you are entering a VAT number for Germany, you would enter `DE123456789`.

7. Select **Update**.

## [Update your billing email address](#update-your-billing-email-address)

Docker sends the following billing-related emails:

* Confirmations (new subscriptions, paid invoices)
* Notifications (card failure, card expiration)
* Reminders (subscription renewal)

You can update the email address that receives billing invoices at any time.

### [Personal account](#personal-account-1)

To update your billing email address:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Billing**.
3. Select **Billing information** from the left-hand navigation.
4. On your billing information card, select **Change**.
5. Update your billing contact information and select **Update**.

### [Organizations](#organizations)

To update your billing email address:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Billing**.
3. Select **Billing information** from the left-hand navigation.
4. On your billing information card, select **Change**.
5. Update your billing contact information and select **Update**.

----
url: https://docs.docker.com/desktop/setup/install/windows-install/
----

# Install Docker Desktop on Windows

***

Table of contents

***

> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250 employees OR more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopWindowsInstall).

This page provides download links, system requirements, and step-by-step installation instructions for Docker Desktop on Windows.

[Docker Desktop for Windows - x86\_64](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-win-amd64) [Docker Desktop for Windows - x86\_64 on the Microsoft Store](https://apps.microsoft.com/detail/xp8cbj40xlbwkx?hl=en-GB\&gl=GB) [Docker Desktop for Windows - Arm (Early Access)](https://desktop.docker.com/win/main/arm64/Docker%20Desktop%20Installer.exe?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-win-arm64)

*For checksums, see [Release notes](https://docs.docker.com/desktop/release-notes/)*

## [Installation modes](#installation-modes)

Docker Desktop supports two installation modes. Per-user installation (Beta) is recommended for most users. It does not require administrator privileges to install or update, and the WSL 2 backend it uses covers the needs of the vast majority of Docker Desktop users.

|                          | Per-user (recommended)                                         | All users                                                            |
| ------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------- |
| Install location         | `%LOCALAPPDATA%\Programs\DockerDesktop`                        | `C:\Program Files\Docker\Docker`                                     |
| Registry keys            | Current User (HKCU)                                            | Local Machine (HKLM)                                                 |
| Admin rights to install  | Not required                                                   | Required                                                             |
| Admin rights to update   | Not required                                                   | Required                                                             |
| Linux containers backend | WSL 2 only                                                     | WSL 2 or Hyper-V                                                     |
| Windows containers       | Not supported                                                  | Supported                                                            |
| Security                 | Smaller attack surface; no privileged system service installed | Requires privileged system service; broader access to host resources |

For more information, see [Understand permission requirements for Windows](https://docs.docker.com/desktop/setup/install/windows-install/).

## [System requirements](#system-requirements)

> Tip
>
> **Should I use Hyper-V or WSL?**
>
> Docker Desktop's functionality remains consistent on both WSL and Hyper-V, without a preference for either architecture. Hyper-V and WSL have their own advantages and disadvantages, depending on your specific setup and your planned use case. Note that Hyper-V is only available with all-users installation. If you install Docker Desktop in per-user mode, WSL 2 is the only supported backend.

* WSL version 2.1.5 or later. To check your version, see [WSL: Verification and setup](#wsl-verification-and-setup)

* If you intend to use Enhanced Container Isolation, ensure you’re using WSL version 2.6 or later. This is required because ECI depends on a Linux kernel version of at least 6.3.0, and WSL 2.6+ bundles Linux kernel version 6.6.

* Windows 10 64-bit: Enterprise, Pro, or Education version 22H2 (build 19045).

* Windows 11 64-bit: Enterprise, Pro, or Education version 23H2 (build 22631) or higher.

* The Windows Server service (LanmanServer) must be enabled and its start mode set to **Automatic**.

* Turn on the WSL 2 feature on Windows. For detailed instructions, refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10).

* The following hardware prerequisites are required to successfully run WSL 2 on Windows 10 or Windows 11:

  * 64-bit processor with [Second Level Address Translation (SLAT)](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)
  * 8GB system RAM
  * Enable hardware virtualization in BIOS/UEFI. For more information, see [Virtualization](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#docker-desktop-fails-due-to-virtualization-not-working).

For more information on setting up WSL 2 with Docker Desktop, see [WSL](https://docs.docker.com/desktop/features/wsl/).

> Note
>
> Docker only supports Docker Desktop on Windows for those versions of Windows that are still within [Microsoft’s servicing timeline](https://support.microsoft.com/en-us/help/13853/windows-lifecycle-fact-sheet). Docker Desktop is not supported on server versions of Windows, such as Windows Server 2019 or Windows Server 2022. For more information on how to run containers on Windows Server, see [Microsoft's official documentation](https://learn.microsoft.com/virtualization/windowscontainers/quick-start/set-up-environment).

> Important
>
> To run [Windows containers](#windows-containers), you need Windows 10 or Windows 11 Professional or Enterprise edition. Windows Home or Education editions only allow you to run Linux containers.

* Windows 10 64-bit: Enterprise, Pro, or Education version 22H2 (build 19045).

* Windows 11 64-bit: Enterprise, Pro, or Education version 23H2 (build 22631) or higher.

* The Windows Server service (LanmanServer) must be enabled and its start mode set to **Automatic**.

* Turn on Hyper-V and Containers Windows features.

* The following hardware prerequisites are required to successfully run Client Hyper-V on Windows 10:

  * 64 bit processor with [Second Level Address Translation (SLAT)](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)
  * 8GB system RAM
  * Turn on BIOS/UEFI-level hardware virtualization support in the BIOS/UEFI settings. For more information, see [Virtualization](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#virtualization).

> Note
>
> Docker only supports Docker Desktop on Windows for those versions of Windows that are still within [Microsoft’s servicing timeline](https://support.microsoft.com/en-us/help/13853/windows-lifecycle-fact-sheet). Docker Desktop is not supported on server versions of Windows, such as Windows Server 2019 or Windows Server 2022. For more information on how to run containers on Windows Server, see [Microsoft's official documentation](https://learn.microsoft.com/virtualization/windowscontainers/quick-start/set-up-environment).

> Important
>
> To run [Windows containers](#windows-containers), you need Windows 10 or Windows 11 Professional or Enterprise edition. Windows Home or Education editions only allow you to run Linux containers.

* WSL version 2.1.5 or later. To check your version, see [WSL: Verification and setup](#wsl-verification-and-setup)

* Windows 10 64-bit: Enterprise, Pro, or Education version 22H2 (build 19045).

* Windows 11 64-bit: Enterprise, Pro, or Education version 23H2 (build 22631) or higher.

* The Windows Server service (LanmanServer) must be enabled and its start mode set to **Automatic**.

* Turn on the WSL 2 feature on Windows. For detailed instructions, refer to the [Microsoft documentation](https://docs.microsoft.com/en-us/windows/wsl/install-win10).

* The following hardware prerequisites are required to successfully run WSL 2 on Windows 10 or Windows 11:

  * 64-bit processor with [Second Level Address Translation (SLAT)](https://en.wikipedia.org/wiki/Second_Level_Address_Translation)
  * 8GB system RAM
  * Enable hardware virtualization in BIOS/UEFI. For more information, see [Virtualization](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/topics/#virtualization).

> Important
>
> Windows containers are not supported.

Containers and images created with Docker Desktop are shared between all user accounts on machines where it is installed. This is because all Windows accounts use the same VM to build and run containers. Note that it is not possible to share containers and images between user accounts when using the Docker Desktop WSL 2 backend.

Running Docker Desktop inside a VMware ESXi or Azure VM is supported for Docker Business customers. It requires enabling nested virtualization on the hypervisor first. For more information, see [Running Docker Desktop in a VM or VDI environment](https://docs.docker.com/desktop/setup/vm-vdi/).

## [Install Docker Desktop on Windows](#install-docker-desktop-on-windows)

### [Install interactively](#install-interactively)

1. Download the installer using the download button at the top of the page, or from the [release notes](https://docs.docker.com/desktop/release-notes/).

2. Double-click `Docker Desktop Installer.exe` to run the installer. The installer will ask which installation mode you prefer. Choosing per-user installs to `%LOCALAPPDATA%\Programs\DockerDesktop` and requires no administrator privileges. Choosing all users will prompt for elevation.

   > Note
   >
   > If you want to switch installation mode at a later date, you need to uninstall and reinstall Docker Desktop.

3. When prompted, ensure the **Use WSL 2 instead of Hyper-V** option on the Configuration page is selected or not depending on your choice of backend.

   On systems that support only one backend, Docker Desktop automatically selects the available option.

4. Follow the instructions on the installation wizard to authorize the installer and proceed with the installation.

5. When the installation is successful, select **Close** to complete the installation process.

6. [Start Docker Desktop](#start-docker-desktop).

### [Install from the command line](#install-from-the-command-line)

After downloading `Docker Desktop Installer.exe`, run the following command in a terminal to install Docker Desktop to `%LOCALAPPDATA%\Programs\DockerDesktop`.

For per-user installation, run:

```console
$ "Docker Desktop Installer.exe" install --user
```

To install for all users on the machine (requires administrator privileges):

```console
$ "Docker Desktop Installer.exe" install
```

If you're using PowerShell you should run it as:

```powershell
# Per-user installation (no admin required)
Start-Process 'Docker Desktop Installer.exe' -Wait -ArgumentList 'install', '--user'
 
# All-users installation (run as administrator)
Start-Process 'Docker Desktop Installer.exe' -Wait install
```

If using the Windows Command Prompt:

```sh
# Per-user installation (no admin required)
start /w "" "Docker Desktop Installer.exe" install --user
 
# All-users installation (run as administrator)
start /w "" "Docker Desktop Installer.exe" install
```

If using all-users installation and your administrator account is different to your user account, you must add the user to the **docker-users** group to access features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers:

```console
$ net localgroup docker-users <user> /add
```

See the [Installer flags](#installer-flags) section to see what flags the `install` command accepts.

> Note
>
> If you want to switch installation mode at a later date, you need to uninstall and reinstall Docker Desktop.

## [Start Docker Desktop](#start-docker-desktop)

Docker Desktop does not start automatically after installation. To start Docker Desktop:

1. Search for Docker, and select **Docker Desktop** in the search results.

2. The Docker menu ( ) displays the Docker Subscription Service Agreement.

   Here’s a summary of the key points:

   * Docker Desktop is free for small businesses (fewer than 250 employees AND less than $10 million in annual revenue), personal use, education, and non-commercial open source projects.
   * Otherwise, it requires a paid subscription for professional use.
   * Paid subscriptions are also required for government entities.
   * The Docker Pro, Team, and Business subscriptions include commercial use of Docker Desktop.

3. Select **Accept** to continue. Docker Desktop starts after you accept the terms.

   Note that Docker Desktop won't run if you do not agree to the terms. You can choose to accept the terms at a later date by opening Docker Desktop.

   For more information, see [Docker Desktop Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement/). It is recommended that you read the [FAQs](https://www.docker.com/pricing/faq).

> Tip
>
> As an IT administrator, you can use endpoint management (MDM) software to identify the number of Docker Desktop instances and their versions within your environment. This can provide accurate license reporting, help ensure your machines use the latest version of Docker Desktop, and enable you to [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).
>
> * [Intune](https://learn.microsoft.com/en-us/mem/intune/apps/app-discovered-apps)
> * [Jamf](https://docs.jamf.com/10.25.0/jamf-pro/administrator-guide/Application_Usage.html)
> * [Kandji](https://support.kandji.io/support/solutions/articles/72000559793-view-a-device-application-list)
> * [Kolide](https://www.kolide.com/features/device-inventory/properties/mac-apps)
> * [Workspace One](https://blogs.vmware.com/euc/2022/11/how-to-use-workspace-one-intelligence-to-manage-app-licenses-and-reduce-costs.html)

## [Advanced system configuration and installation options](#advanced-system-configuration-and-installation-options)

### [WSL: Verification and setup](#wsl-verification-and-setup)

If you have chosen to use WSL, first verify that your installed version meets system requirements by running the following command in your terminal:

```console
wsl --version
```

If version details do not appear, you are likely using the inbox version of WSL. This version does not support modern capabilities and must be updated.

You can update or install WSL using one of the following methods:

#### [Option 1: Install or update WSL via the terminal](#option-1-install-or-update-wsl-via-the-terminal)

1. Open PowerShell or Windows Command Prompt in administrator mode.
2. Run either the install or update command. You may be prompted to restart your machine. For more information, refer to [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install).

```console
wsl --install

wsl --update
```

#### [Option 2: Install WSL via the MSI package](#option-2-install-wsl-via-the-msi-package)

If Microsoft Store access is blocked due to security policies:

1. Go to the official [WSL GitHub Releases page](https://github.com/microsoft/WSL/releases).
2. Download the `.msi` installer from the latest stable release (under the Assets drop-down).
3. Run the downloaded installer and follow the setup instructions.

### [Installer flags](#installer-flags)

> Note
>
> If you're using PowerShell, you need to use the `ArgumentList` parameter before any flags. For example:
>
> ```powershell
> Start-Process 'Docker Desktop Installer.exe' -Wait -ArgumentList 'install', '--accept-license'
> ```

#### [Installation behavior](#installation-behavior)

* `--user`: Installs Docker Desktop in per-user mode, to `%LOCALAPPDATA%\Programs\DockerDesktop`. No administrator privileges are required. This is the recommended mode for most users. See [Installation modes](#installation-modes).
* `--quiet`: Suppresses information output when running the installer
* `--accept-license`: Accepts the [Docker Subscription Service Agreement](https://www.docker.com/legal/docker-subscription-service-agreement) now, rather than requiring it to be accepted when the application is first run
* `--installation-dir=<path>`: Changes the default installation location (`C:\Program Files\Docker\Docker`)
* `--backend=<backend name>`: Selects the default backend to use for Docker Desktop, `hyper-v`, `windows` or `wsl-2` (default)
* `--always-run-service`: After installation completes, starts `com.docker.service` and sets the service startup type to Automatic. This circumvents the need for administrator privileges, which are otherwise necessary to start `com.docker.service`. `com.docker.service` is required by Windows containers and Hyper-V backend.

#### [Security and access control](#security-and-access-control)

* `--allowed-org=<org name>`: Requires the user to sign in and be part of the specified Docker Hub organization when running the application

* `--admin-settings`: Automatically creates an `admin-settings.json` file which is used by admins to control certain Docker Desktop settings on client machines within their organization. For more information, see [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/).

  * It must be used together with the `--allowed-org=<org name>` flag.
  * For example:`--allowed-org=<org name> --admin-settings="{'configurationFileVersion': 2, 'enhancedContainerIsolation': {'value': true, 'locked': false}}"`

* `--no-windows-containers`: Disables the Windows containers integration. This can improve security. For more information, see [Windows containers](https://docs.docker.com/desktop/setup/install/windows-permission-requirements/#windows-containers).

#### [Proxy configuration](#proxy-configuration)

* `--proxy-http-mode=<mode>`: Sets the HTTP Proxy mode, `system` (default) or `manual`
* `--override-proxy-http=<URL>`: Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests, requires `--proxy-http-mode` to be `manual`
* `--override-proxy-https=<URL>`: Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests, requires `--proxy-http-mode` to be `manual`
* `--override-proxy-exclude=<hosts/domains>`: Bypasses proxy settings for the hosts and domains. Uses a comma-separated list.
* `--proxy-enable-kerberosntlm`: Enables Kerberos and NTLM proxy authentication. If you are enabling this, ensure your proxy server is properly configured for Kerberos/NTLM authentication. Available with Docker Desktop 4.32 and later.
* `--override-proxy-pac=<PAC file URL>`: Sets the PAC file URL. This setting takes effect only when using `manual` proxy mode.
* `--override-proxy-embedded-pac=<PAC script>`: Specifies an embedded PAC (Proxy Auto-Config) script. This setting takes effect only when using `manual` proxy mode and has precedence over the `--override-proxy-pac` flag.

##### [Example of specifying PAC file](#example-of-specifying-pac-file)

```console
"Docker Desktop Installer.exe" install --proxy-http-mode="manual" --override-proxy-pac="http://localhost:8080/myproxy.pac"
```

##### [Example of specifying PAC script](#example-of-specifying-pac-script)

```console
"Docker Desktop Installer.exe" install --proxy-http-mode="manual" --override-proxy-embedded-pac="function FindProxyForURL(url, host) { return \"DIRECT\"; }"
```

#### [Data root and disk location](#data-root-and-disk-location)

* `--hyper-v-default-data-root=<path>`: Specifies the default location for the Hyper-V VM disk.
* `--windows-containers-default-data-root=<path>`: Specifies the default location for the Windows containers.
* `--wsl-default-data-root=<path>`: Specifies the default location for the WSL distribution disk.

### [Administrator privileges](#administrator-privileges)

In per-user mode, Docker Desktop can be installed and updated without administrator privileges. Some settings still require elevation and are marked **Requires password** in the Settings UI. Enabling WSL 2 for the first time also requires administrator privileges, but this is a one-time, per-machine operation.

In all-users mode, installing Docker Desktop requires administrator privileges. However, once installed, it can be used without administrative access. Some actions, though, still need elevated permissions. See [Understand permission requirements for Windows](https://docs.docker.com/desktop/setup/install/windows-permission-requirements/) for more detail.

See the [FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/general/#how-do-i-run-docker-desktop-without-administrator-privileges) on how to install and run Docker Desktop without needing administrator privileges.

If you're an IT admin and your users do not have administrator rights and plan to perform operations that require elevated privileges, be sure to install Docker Desktop using the `--always-run-service` installer flag. This ensures those actions can still be executed without prompting for User Account Control (UAC) elevation. See [Installer Flags](#installer-flags) for more detail.

### [Windows containers](#windows-containers)

> Note
>
> Windows containers are only supported in all-users installation mode. They are not available when Docker Desktop is installed per-user.

From the Docker Desktop menu, you can toggle which daemon (Linux or Windows) the Docker CLI talks to. Select **Switch to Windows containers** to use Windows containers, or select **Switch to Linux containers** to use Linux containers (the default).

For more information on Windows containers, refer to the following documentation:

* Microsoft documentation on [Windows containers](https://docs.microsoft.com/en-us/virtualization/windowscontainers/about/index).

* [Build and Run Your First Windows Server Container (Blog Post)](https://www.docker.com/blog/build-your-first-docker-windows-server-container/) gives a quick tour of how to build and run native Docker Windows containers on Windows 10 and Windows Server 2016 evaluation releases.

* [Getting Started with Windows Containers (Lab)](https://github.com/docker/labs/blob/master/windows/windows-containers/README.md) shows you how to use the [MusicStore](https://github.com/aspnet/MusicStore/) application with Windows containers. The MusicStore is a standard .NET application and, [forked here to use containers](https://github.com/friism/MusicStore), is a good example of a multi-container application.

* To understand how to connect to Windows containers from the local host, see [I want to connect to a container from Windows](https://docs.docker.com/desktop/features/networking/#i-want-to-connect-to-a-container-from-the-host)

> Note
>
> When you switch to Windows containers, **Settings** only shows those tabs that are active and apply to your Windows containers.

If you set proxies or daemon configuration in Windows containers mode, these apply only on Windows containers. If you switch back to Linux containers, proxies and daemon configurations return to what you had set for Linux containers. Your Windows container settings are retained and become available again when you switch back.

## [Where to go next](#where-to-go-next)

* Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopWindowsInstall) to see what Docker can offer you.
* [Get started with Docker](https://docs.docker.com/get-started/introduction/).
* [Explore Docker Desktop](https://docs.docker.com/desktop/use-desktop/) and all its features.
* [Troubleshooting](https://docs.docker.com/desktop/troubleshoot-and-support/troubleshoot/) describes common problems, workarounds, and how to get support.
* [FAQs](https://docs.docker.com/desktop/troubleshoot-and-support/faqs/general/) provide answers to frequently asked questions.
* [Release notes](https://docs.docker.com/desktop/release-notes/) lists component updates, new features, and improvements associated with Docker Desktop releases.
* [Back up and restore data](https://docs.docker.com/desktop/settings-and-maintenance/backup-and-restore/) provides instructions on backing up and restoring data related to Docker.

----
url: https://docs.docker.com/guides/vuejs/deploy/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Test your Vue.js deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

Before you begin, make sure you’ve completed the following:

* Complete all the previous sections of this guide, starting with [Containerize Vue.js application](https://docs.docker.com/guides/vuejs/containerize/).
* [Enable Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

> **New to Kubernetes?**\
> Visit the [Kubernetes basics tutorial](https://kubernetes.io/docs/tutorials/kubernetes-basics/) to get familiar with how clusters, pods, deployments, and services work.

***

## [Overview](#overview)

This section guides you through deploying your containerized Vue.js application locally using [Docker Desktop’s built-in Kubernetes](/desktop/kubernetes/). Running your app in a local Kubernetes cluster closely simulates a real production environment, enabling you to test, validate, and debug your workloads with confidence before promoting them to staging or production.

***

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

Follow these steps to define your deployment configuration:

1. In the root of your project, create a new file named: vuejs-sample-kubernetes.yaml

2. Open the file in your IDE or preferred text editor.

3. Add the following configuration, and be sure to replace `{DOCKER_USERNAME}` and `{DOCKERHUB_PROJECT_NAME}` with your actual Docker Hub username and repository name from the previous [Automate your builds with GitHub Actions](https://docs.docker.com/guides/vuejs/configure-github-actions/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vuejs-sample
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vuejs-sample
  template:
    metadata:
      labels:
        app: vuejs-sample
    spec:
      containers:
        - name: vuejs-container
          image: {DOCKER_USERNAME}/{DOCKERHUB_PROJECT_NAME}:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 8080
          resources:
            limits:
              cpu: "500m"
              memory: "256Mi"
            requests:
              cpu: "250m"
              memory: "128Mi"
---
apiVersion: v1
kind: Service
metadata:
  name: vuejs-sample-service
  namespace: default
spec:
  type: NodePort
  selector:
    app: vuejs-sample
  ports:
    - port: 8080
      targetPort: 8080
      nodePort: 30001
```

This manifest defines two key Kubernetes resources, separated by `---`:

* Deployment Deploys a single replica of your Vue.js application inside a pod. The pod uses the Docker image built and pushed by your GitHub Actions CI/CD workflow\
  (refer to [Automate your builds with GitHub Actions](https://docs.docker.com/guides/vuejs/configure-github-actions/)).\
  The container listens on port `8080`, which is typically used by [Nginx](https://nginx.org/en/docs/) to serve your production Vue.js app.

* Service (NodePort) Exposes the deployed pod to your local machine.\
  It forwards traffic from port `30001` on your host to port `8080` inside the container.\
  This lets you access the application in your browser at <http://localhost:30001>.

> Note
>
> To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

***

## [Deploy and check your application](#deploy-and-check-your-application)

Follow these steps to deploy your containerized Vue.js app into a local Kubernetes cluster and verify that it’s running correctly.

### [Step 1. Apply the Kubernetes configuration](#step-1-apply-the-kubernetes-configuration)

In your terminal, navigate to the directory where your `vuejs-sample-kubernetes.yaml` file is located, then deploy the resources using:

```console
  $ kubectl apply -f vuejs-sample-kubernetes.yaml
```

If everything is configured properly, you’ll see confirmation that both the Deployment and the Service were created:

```shell
  deployment.apps/vuejs-sample created
  service/vuejs-sample-service created
```

This confirms that both the Deployment and the Service were successfully created and are now running inside your local cluster.

### [Step 2. Check the deployment status](#step-2-check-the-deployment-status)

Run the following command to check the status of your deployment:

```console
  $ kubectl get deployments
```

You should see output similar to the following:

```shell
  NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
  vuejs-sample         1/1     1            1           1m14s
```

This confirms that your pod is up and running with one replica available.

### [Step 3. Verify the service exposure](#step-3-verify-the-service-exposure)

Check if the NodePort service is exposing your app to your local machine:

```console
$ kubectl get services
```

You should see something like:

```shell
NAME                     TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
vuejs-sample-service     NodePort    10.98.233.59    <none>        8080:30001/TCP   1m
```

This output confirms that your app is available via NodePort on port 30001.

### [Step 4. Access your app in the browser](#step-4-access-your-app-in-the-browser)

Open your browser and navigate to <http://localhost:30001>.

You should see your production-ready Vue.js Sample application running — served by your local Kubernetes cluster.

### [Step 5. Clean up Kubernetes resources](#step-5-clean-up-kubernetes-resources)

Once you're done testing, you can delete the deployment and service using:

```console
  $ kubectl delete -f vuejs-sample-kubernetes.yaml
```

Expected output:

```shell
  deployment.apps "vuejs-sample" deleted
  service "vuejs-sample-service" deleted
```

This ensures your cluster stays clean and ready for the next deployment.

***

## [Summary](#summary)

In this section, you learned how to deploy your Vue.js application to a local Kubernetes cluster using Docker Desktop. This setup allows you to test and debug your containerized app in a production-like environment before deploying it to the cloud.

What you accomplished:

* Created a Kubernetes Deployment and NodePort Service for your Vue.js app
* Used `kubectl apply` to deploy the application locally
* Verified the app was running and accessible at `http://localhost:30001`
* Cleaned up your Kubernetes resources after testing

***

## [Related resources](#related-resources)

Explore official references and best practices to sharpen your Kubernetes deployment workflow:

* [Kubernetes documentation](https://kubernetes.io/docs/home/) – Learn about core concepts, workloads, services, and more.
* [Deploy on Kubernetes with Docker Desktop](/manuals) – Use Docker Desktop’s built-in Kubernetes support for local testing and development.
* [`kubectl` CLI reference](https://kubernetes.io/docs/reference/kubectl/) – Manage Kubernetes clusters from the command line.
* [Kubernetes Deployment resource](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) – Understand how to manage and scale applications using Deployments.
* [Kubernetes Service resource](https://kubernetes.io/docs/concepts/services-networking/service/) – Learn how to expose your application to internal and external traffic.

----
url: https://docs.docker.com/reference/cli/docker/image/push/
----

# docker image push

***

| Description                                                               | Upload an image to a registry            |
| ------------------------------------------------------------------------- | ---------------------------------------- |
| Usage                                                                     | `docker image push [OPTIONS] NAME[:TAG]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker push`                            |

## [Description](#description)

Use `docker image push` to share your images to the [Docker Hub](https://hub.docker.com) registry or to a self-hosted one.

Refer to the [`docker image tag`](/reference/cli/docker/image/tag/) reference for more information about valid image and tag names.

Killing the `docker image push` process, for example by pressing `CTRL-c` while it is running in a terminal, terminates the push operation.

Progress bars are shown during docker push, which show the uncompressed size. The actual amount of data that's pushed will be compressed before sending, so the uploaded size will not be reflected by the progress bar.

Registry credentials are managed by [docker login](/reference/cli/docker/login/).

### [Concurrent uploads](#concurrent-uploads)

By default the Docker daemon will push five layers of an image at a time. If you are on a low bandwidth connection this may cause timeout issues and you may want to lower this via the `--max-concurrent-uploads` daemon option. See the [daemon documentation](/reference/cli/dockerd/) for more details.

## [Options](#options)

| Option                        | Default | Description                                                                                                                                                                                                                                                |
| ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-a, --all-tags`](#all-tags) |         | Push all tags of an image to the repository                                                                                                                                                                                                                |
| `--platform`                  |         | API 1.46+ Push a platform-specific manifest as a single-platform image to the registry. Image index won't be pushed, meaning that other manifests, including attestations won't be preserved. 'os\[/arch\[/variant]]': Explicit platform (eg. linux/amd64) |
| `-q, --quiet`                 |         | Suppress verbose output                                                                                                                                                                                                                                    |

## [Examples](#examples)

### [Push a new image to a registry](#push-a-new-image-to-a-registry)

First save the new image by finding the container ID (using [`docker container ls`](/reference/cli/docker/container/ls/)) and then committing it to a new image name. Note that only `a-z0-9-_.` are allowed when naming images:

```console
$ docker container commit c16378f943fe rhel-httpd:latest
```

Now, push the image to the registry using the image ID. In this example the registry is on host named `registry-host` and listening on port `5000`. To do this, tag the image with the host name or IP address, and the port of the registry:

```console
$ docker image tag rhel-httpd:latest registry-host:5000/myadmin/rhel-httpd:latest

$ docker image push registry-host:5000/myadmin/rhel-httpd:latest
```

Check that this worked by running:

```console
$ docker image ls
```

You should see both `rhel-httpd` and `registry-host:5000/myadmin/rhel-httpd` listed.

### [Push all tags of an image (-a, --all-tags)](#all-tags)

Use the `-a` (or `--all-tags`) option to push all tags of a local image.

The following example creates multiple tags for an image, and pushes all those tags to Docker Hub.

```console
$ docker image tag myimage registry-host:5000/myname/myimage:latest
$ docker image tag myimage registry-host:5000/myname/myimage:v1.0.1
$ docker image tag myimage registry-host:5000/myname/myimage:v1.0
$ docker image tag myimage registry-host:5000/myname/myimage:v1
```

The image is now tagged under multiple names:

```console
$ docker image ls

REPOSITORY                          TAG        IMAGE ID       CREATED      SIZE
myimage                             latest     6d5fcfe5ff17   2 hours ago  1.22MB
registry-host:5000/myname/myimage   latest     6d5fcfe5ff17   2 hours ago  1.22MB
registry-host:5000/myname/myimage   v1         6d5fcfe5ff17   2 hours ago  1.22MB
registry-host:5000/myname/myimage   v1.0       6d5fcfe5ff17   2 hours ago  1.22MB
registry-host:5000/myname/myimage   v1.0.1     6d5fcfe5ff17   2 hours ago  1.22MB
```

When pushing with the `--all-tags` option, all tags of the `registry-host:5000/myname/myimage` image are pushed:

```console
$ docker image push --all-tags registry-host:5000/myname/myimage

The push refers to repository [registry-host:5000/myname/myimage]
195be5f8be1d: Pushed
latest: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
195be5f8be1d: Layer already exists
v1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
195be5f8be1d: Layer already exists
v1.0: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
195be5f8be1d: Layer already exists
v1.0.1: digest: sha256:edafc0a0fb057813850d1ba44014914ca02d671ae247107ca70c94db686e7de6 size: 4527
```

----
url: https://docs.docker.com/go/build-checks-experimental/
----

# Checking your build configuration

***

Table of contents

***

> Tip
>
> To improve linting, code navigation, and vulnerability scanning of your Dockerfiles in Visual Studio Code see the [Docker DX](https://marketplace.visualstudio.com/items?itemName=docker.docker) extension.

## [Build with checks](#build-with-checks)

Build checks are supported in:

* Buildx version 0.15.0 and later
* [docker/build-push-action](https://github.com/docker/build-push-action) version 6.6.0 and later
* [docker/bake-action](https://github.com/docker/bake-action) version 5.6.0 and later

Invoking a build runs the checks by default, and displays any violations in the build output. For example, the following command both builds the image and runs the checks:

```console
$ docker build .
[+] Building 3.5s (11/11) FINISHED
...

1 warning found (use --debug to expand):
  - Lint Rule 'JSONArgsRecommended': JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 7)
```

In this example, the build ran successfully, but a [JSONArgsRecommended](/reference/build-checks/json-args-recommended/) warning was reported, because `CMD` instructions should use JSON array syntax.

With the GitHub Actions, the checks display in the diff view of pull requests.

```yaml
name: Build and push Docker images
on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build and push
        uses: docker/build-push-action@v7
```

### [More verbose output](#more-verbose-output)

Check warnings for a regular `docker build` display a concise message containing the rule name, the message, and the line number of where in the Dockerfile the issue originated. If you want to see more detailed information about the checks, you can use the `--debug` flag. For example:

```console
$ docker --debug build .
[+] Building 3.5s (11/11) FINISHED
...

 1 warning found:
 - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 4)
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals
More info: https://docs.docker.com/go/dockerfile/rule/json-args-recommended/
Dockerfile:4
--------------------
   2 |
   3 |     FROM alpine
   4 | >>> CMD echo "Hello, world!"
   5 |
--------------------
```

With the `--debug` flag, the output includes a link to the documentation for the check, and a snippet of the Dockerfile where the issue was found.

## [Check a build without building](#check-a-build-without-building)

To run build checks without actually building, you can use the `docker build` command as you typically would, but with the addition of the `--check` flag. Here's an example:

```console
$ docker build --check .
```

Instead of executing the build steps, this command only runs the checks and reports any issues it finds. If there are any issues, they will be reported in the output. For example:

Output with --check

```text
[+] Building 1.5s (5/5) FINISHED
=> [internal] connecting to local controller
=> [internal] load build definition from Dockerfile
=> => transferring dockerfile: 253B
=> [internal] load metadata for docker.io/library/node:22
=> [auth] library/node:pull token for registry-1.docker.io
=> [internal] load .dockerignore
=> => transferring context: 50B
JSONArgsRecommended - https://docs.docker.com/go/dockerfile/rule/json-args-recommended/
JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals
Dockerfile:7
--------------------
5 |
6 |     COPY index.js .
7 | >>> CMD node index.js
8 |
--------------------
```

This output with `--check` shows the [verbose message](#more-verbose-output) for the check.

Unlike a regular build, if any violations are reported when using the `--check` flag, the command exits with a non-zero status code.

## [Fail build on check violations](#fail-build-on-check-violations)

Check violations for builds are reported as warnings, with exit code 0, by default. You can configure Docker to fail the build when violations are reported, using a `check=error=true` directive in your Dockerfile. This will cause the build to error out when after the build checks are run, before the actual build gets executed.

Dockerfile

|                   |                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| ```
1
2
3
4
5
``` | ```dockerfile
# syntax=docker/dockerfile:1
# check=error=true

FROM alpine
CMD echo "Hello, world!"
``` |

Without the `# check=error=true` directive, this build would complete with an exit code of 0. However, with the directive, build check violation results in non-zero exit code:

```console
$ docker build .
[+] Building 1.5s (5/5) FINISHED
...

 1 warning found (use --debug to expand):
 - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 5)
Dockerfile:1
--------------------
   1 | >>> # syntax=docker/dockerfile:1
   2 |     # check=error=true
   3 |
--------------------
ERROR: lint violation found for rules: JSONArgsRecommended
$ echo $?
1
```

You can also set the error directive on the CLI by passing the `BUILDKIT_DOCKERFILE_CHECK` build argument:

```console
$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=error=true" .
```

## [Skip checks](#skip-checks)

By default, all checks are run when you build an image. If you want to skip specific checks, you can use the `check=skip` directive in your Dockerfile. The `skip` parameter takes a CSV string of the check IDs you want to skip. For example:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=skip=JSONArgsRecommended,StageNameCasing

FROM alpine AS BASE_STAGE
CMD echo "Hello, world!"
```

Building this Dockerfile results in no check violations.

You can also skip checks by passing the `BUILDKIT_DOCKERFILE_CHECK` build argument with a CSV string of check IDs you want to skip. For example:

```console
$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing" .
```

To skip all checks, use the `skip=all` parameter:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=skip=all
```

## [Combine error and skip parameters for check directives](#combine-error-and-skip-parameters-for-check-directives)

To both skip specific checks and error on check violations, pass both the `skip` and `error` parameters separated by a semi-colon (`;`) to the `check` directive in your Dockerfile or in a build argument. For example:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=skip=JSONArgsRecommended,StageNameCasing;error=true
```

Build argument

```console
$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing;error=true" .
```

## [Experimental checks](#experimental-checks)

Before checks are promoted to stable, they may be available as experimental checks. Experimental checks are disabled by default. To see the list of experimental checks available, refer to the [Build checks reference](/reference/build-checks/).

To enable all experimental checks, set the `BUILDKIT_DOCKERFILE_CHECK` build argument to `experimental=all`:

```console
$ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=experimental=all" .
```

You can also enable experimental checks in your Dockerfile using the `check` directive:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=experimental=all
```

To selectively enable experimental checks, you can pass a CSV string of the check IDs you want to enable, either to the `check` directive in your Dockerfile or as a build argument. For example:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=experimental=JSONArgsRecommended,StageNameCasing
```

Note that the `experimental` directive takes precedence over the `skip` directive, meaning that experimental checks will run regardless of the `skip` directive you have set. For example, if you set `skip=all` and enable experimental checks, the experimental checks will still run:

Dockerfile

```dockerfile
# syntax=docker/dockerfile:1
# check=skip=all;experimental=all
```

## [Further reading](#further-reading)

For more information about using build checks, see:

* [Build checks reference](/reference/build-checks/)
* [Validating build configuration with GitHub Actions](https://docs.docker.com/build/ci/github-actions/checks/)

----
url: https://docs.docker.com/extensions/extensions-sdk/architecture/
----

# Extension architecture

***

Table of contents

***

Extensions are applications that run inside the Docker Desktop. They're packaged as Docker images, distributed through Docker Hub, and installed by users either through the Marketplace within the Docker Desktop Dashboard or the Docker Extensions CLI.

Extensions can be composed of three (optional) components:

* A frontend (or User Interface): A web application displayed in a tab of the dashboard in Docker Desktop
* A backend: One or many containerized services running in the Docker Desktop VM
* Executables: Shell scripts or binaries that Docker Desktop copies on the host when installing the extension

An extension doesn't necessarily need to have all these components, but at least one of them depending on the extension features. To configure and run those components, Docker Desktop uses a `metadata.json` file. See the [metadata](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/) section for more details.

## [The frontend](#the-frontend)

The frontend is basically a web application made from HTML, Javascript, and CSS. It can be built with a simple HTML file, some vanilla Javascript or any frontend framework, such as React or Vue.js.

When Docker Desktop installs the extension, it extracts the UI folder from the extension image, as defined by the `ui` section in the `metadata.json`. See the [ui metadata section](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#ui-section) for more details.

Every time users click on the **Extensions** tab, Docker Desktop initializes the extension's UI as if it was the first time. When they navigate away from the tab, both the UI itself and all the sub-processes started by it (if any) are terminated.

The frontend can invoke `docker` commands, communicate with the extension backend, or invoke extension executables deployed on the host, through the [Extensions SDK](https://www.npmjs.com/package/@docker/extension-api-client).

> Tip
>
> The `docker extension init` generates a React based extension. But you can still use it as a starting point for your own extension and use any other frontend framework, like Vue, Angular, Svelte, etc. or event stay with vanilla Javascript.

Learn more about [building a frontend](https://docs.docker.com/extensions/extensions-sdk/build/frontend-extension-tutorial/) for your extension.

## [The backend](#the-backend)

Alongside a frontend application, extensions can also contain one or many backend services. In most cases, the Extension does not need a backend, and features can be implemented just by invoking docker commands through the SDK. However, there are some cases when an extension requires a backend service, for example:

* To run long-running processes that must outlive the frontend
* To store data in a local database and serve them back with a REST API
* To store the extension state, like when a button starts a long-running process, so that if you navigate away from the extension and come back, the frontend can pick up where it left off
* To access specific resources in the Docker Desktop VM, for example by mounting folders in the compose file

> Tip
>
> The `docker extension init` generates a Go backend. But you can still use it as a starting point for your own extension and use any other language like Node.js, Python, Java, .Net, or any other language and framework.

Usually, the backend is made of one container that runs within the Docker Desktop VM. Internally, Docker Desktop creates a Docker Compose project, creates the container from the `image` option of the `vm` section of the `metadata.json`, and attaches it to the Compose project. See the [`vm` metadata section](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#vm-section) for more details.

In some cases, a `compose.yaml` file can be used instead of an `image`. This is useful when the backend container needs more specific options, such as mounting volumes or requesting [capabilities](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) that can't be expressed just with a Docker image. The `compose.yaml` file can also be used to add multiple containers needed by the extension, like a database or a message broker. Note that, if the Compose file defines many services, the SDK can only contact the first of them.

> Note
>
> In some cases, it is useful to also interact with the Docker engine from the backend. See [How to use the Docker socket](https://docs.docker.com/extensions/extensions-sdk/guides/use-docker-socket-from-backend/) from the backend.

To communicate with the backend, the Extension SDK provides [functions](https://docs.docker.com/extensions/extensions-sdk/dev/api/backend/#get) to make `GET`, `POST`, `PUT`, `HEAD`, and `DELETE` requests from the frontend. Under the hood, the communication is done through a socket or named pipe, depending on the operating system. If the backend was listening to a port, it would be difficult to prevent collision with other applications running on the host or in a container already. Also, some users are running Docker Desktop in constrained environments where they can't open ports on their machines.

Finally, the backend can be built with any technology, as long as it can run in a container and listen on a socket.

Learn more about [adding a backend](https://docs.docker.com/extensions/extensions-sdk/build/backend-extension-tutorial/) to your extension.

## [Executables](#executables)

In addition to the frontend and the backend, extensions can also contain executables. Executables are binaries or shell scripts that are installed on the host when the extension is installed. The frontend can invoke them with [the extension SDK](https://docs.docker.com/extensions/extensions-sdk/dev/api/backend/#invoke-an-extension-binary-on-the-host).

These executables are useful when the extension needs to interact with a third-party CLI tool, like AWS, `kubectl`, etc. Shipping those executables with the extension ensure that the CLI tool is always available, at the right version, on the users' machine.

When Docker Desktop installs the extension, it copies the executables on the host as defined by the `host` section in the `metadata.json`. See the [`host` metadata section](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#host-section) for more details.

However, since they're executed on the users' machine, they have to be available to the platform they're running on. For example, if you want to ship the `kubectl` executable, you need to provide a different version for Windows, Mac, and Linux. Multi arch images will also need to include binaries built for the right arch (AMD / ARM)

See the [host metadata section](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/#host-section) for more details.

Learn how to [invoke host binaries](https://docs.docker.com/extensions/extensions-sdk/guides/invoke-host-binaries/).

----
url: https://docs.docker.com/reference/cli/docker/checkpoint/create/
----

# docker checkpoint create

***

| Description | Create a checkpoint from a running container              |
| ----------- | --------------------------------------------------------- |
| Usage       | `docker checkpoint create [OPTIONS] CONTAINER CHECKPOINT` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Create a checkpoint from a running container

## [Options](#options)

| Option             | Default | Description                                  |
| ------------------ | ------- | -------------------------------------------- |
| `--checkpoint-dir` |         | Use a custom checkpoint storage directory    |
| `--leave-running`  |         | Leave the container running after checkpoint |

----
url: https://docs.docker.com/reference/cli/sbx/template/rm/
----

# sbx template rm

| Description | Remove a template image           |
| ----------- | --------------------------------- |
| Usage       | `sbx template rm TAG\|ID [flags]` |

## [Description](#description)

Remove a template image from the sandbox runtime's image store.

The image can be identified by tag (e.g. "myimage:v1.0") or by image ID (full or prefix, e.g. "abc123"). Use "sbx template ls" to see available images and their IDs.

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Remove by tag
sbx template rm myimage:v1.0

# Remove by image ID (prefix)
sbx template rm abc123
```

----
url: https://docs.docker.com/reference/cli/docker/image/pull/
----

# docker image pull

***

| Description                                                               | Download an image from a registry                 |
| ------------------------------------------------------------------------- | ------------------------------------------------- |
| Usage                                                                     | `docker image pull [OPTIONS] NAME[:TAG\|@DIGEST]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker pull`                                     |

## [Description](#description)

Most of your images will be created on top of a base image from the [Docker Hub](https://hub.docker.com) registry.

[Docker Hub](https://hub.docker.com) contains many pre-built images that you can `pull` and try without needing to define and configure your own.

To download a particular image, or set of images (i.e., a repository), use `docker pull`.

### [Proxy configuration](#proxy-configuration)

If you are behind an HTTP proxy server, for example in corporate settings, you may have to configure the Docker daemon to use the proxy server for operations such as pulling and pushing images. Refer to the [dockerd command-line reference](/reference/cli/dockerd/#proxy-configuration) for details.

### [Concurrent downloads](#concurrent-downloads)

By default the Docker daemon downloads three layers of an image at a time. If you are on a low bandwidth connection this may cause timeout issues and you may want to lower this via the `--max-concurrent-downloads` daemon option. See the [daemon documentation](/reference/cli/dockerd/) for more details.

## [Options](#options)

| Option                        | Default | Description                                                |
| ----------------------------- | ------- | ---------------------------------------------------------- |
| [`-a, --all-tags`](#all-tags) |         | Download all tagged images in the repository               |
| `--platform`                  |         | API 1.32+ Set platform if server is multi-platform capable |
| `-q, --quiet`                 |         | Suppress verbose output                                    |

## [Examples](#examples)

### [Pull an image from Docker Hub](#pull-an-image-from-docker-hub)

To download a particular image, or set of images (i.e., a repository), use `docker image pull` (or the `docker pull` shorthand). If no tag is provided, Docker Engine uses the `:latest` tag as a default. This example pulls the `debian:latest` image:

```console
$ docker image pull debian

Using default tag: latest
latest: Pulling from library/debian
e756f3fdd6a3: Pull complete
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:latest
docker.io/library/debian:latest
```

Docker images can consist of multiple layers. In the example above, the image consists of a single layer; `e756f3fdd6a3`.

Layers can be reused by images. For example, the `debian:bookworm` image shares its layer with the `debian:latest`. Pulling the `debian:bookworm` image therefore only pulls its metadata, but not its layers, because the layer is already present locally:

```console
$ docker image pull debian:bookworm

bookworm: Pulling from library/debian
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:bookworm
docker.io/library/debian:bookworm
```

To see which images are present locally, use the [`docker images`](/reference/cli/docker/image/ls/) command:

```console
$ docker images

REPOSITORY   TAG        IMAGE ID       CREATED        SIZE
debian       bookworm   4eacea30377a   8 days ago     124MB
debian       latest     4eacea30377a   8 days ago     124MB
```

Docker uses a content-addressable image store, and the image ID is a SHA256 digest covering the image's configuration and layers. In the example above, `debian:bookworm` and `debian:latest` have the same image ID because they are the same image tagged with different names. Because they are the same image, their layers are stored only once and do not consume extra disk space.

For more information about images, layers, and the content-addressable store, refer to [understand images, containers, and storage drivers](/engine/storage/drivers/).

### [Pull an image by digest (immutable identifier)](#pull-an-image-by-digest-immutable-identifier)

So far, you've pulled images by their name (and "tag"). Using names and tags is a convenient way to work with images. When using tags, you can `docker pull` an image again to make sure you have the most up-to-date version of that image. For example, `docker pull ubuntu:24.04` pulls the latest version of the Ubuntu 24.04 image.

In some cases you don't want images to be updated to newer versions, but prefer to use a fixed version of an image. Docker enables you to pull an image by its digest. When pulling an image by digest, you specify exactly which version of an image to pull. Doing so, allows you to "pin" an image to that version, and guarantee that the image you're using is always the same.

To know the digest of an image, pull the image first. Let's pull the latest `ubuntu:24.04` image from Docker Hub:

```console
$ docker pull ubuntu:24.04

24.04: Pulling from library/ubuntu
125a6e411906: Pull complete
Digest: sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Status: Downloaded newer image for ubuntu:24.04
docker.io/library/ubuntu:24.04
```

Docker prints the digest of the image after the pull has finished. In the example above, the digest of the image is:

```console
sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
```

Docker also prints the digest of an image when pushing to a registry. This may be useful if you want to pin to a version of the image you just pushed.

A digest takes the place of the tag when pulling an image, for example, to pull the above image by digest, run the following command:

```console
$ docker pull ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

docker.io/library/ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30: Pulling from library/ubuntu
Digest: sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Status: Image is up to date for ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
docker.io/library/ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
```

Digest can also be used in the `FROM` of a Dockerfile, for example:

```dockerfile
FROM ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
LABEL org.opencontainers.image.authors="some maintainer <maintainer@example.com>"
```

> Note
>
> Using this feature "pins" an image to a specific version in time. Docker does therefore not pull updated versions of an image, which may include security updates. If you want to pull an updated image, you need to change the digest accordingly.

### [Pull from a different registry](#pull-from-a-different-registry)

By default, `docker pull` pulls images from [Docker Hub](https://hub.docker.com). It is also possible to manually specify the path of a registry to pull from. For example, if you have set up a local registry, you can specify its path to pull from it. A registry path is similar to a URL, but does not contain a protocol specifier (`https://`).

The following command pulls the `testing/test-image` image from a local registry listening on port 5000 (`myregistry.local:5000`):

```console
$ docker image pull myregistry.local:5000/testing/test-image
```

Registry credentials are managed by [docker login](/reference/cli/docker/login/).

Docker uses the `https://` protocol to communicate with a registry, unless the registry is allowed to be accessed over an insecure connection. Refer to the [insecure registries](/reference/cli/dockerd/#insecure-registries) section for more information.

### [Pull a repository with multiple images (-a, --all-tags)](#all-tags)

By default, `docker pull` pulls a single image from the registry. A repository can contain multiple images. To pull all images from a repository, provide the `-a` (or `--all-tags`) option when using `docker pull`.

This command pulls all images from the `ubuntu` repository:

```console
$ docker image pull --all-tags ubuntu

Pulling repository ubuntu
ad57ef8d78d7: Download complete
105182bb5e8b: Download complete
511136ea3c5a: Download complete
73bd853d2ea5: Download complete
....

Status: Downloaded newer image for ubuntu
```

After the pull has completed use the `docker image ls` command (or the `docker images` shorthand) to see the images that were pulled. The example below shows all the `ubuntu` images that are present locally:

```console
$ docker image ls --filter reference=ubuntu
REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
ubuntu       22.04     8a3cdc4d1ad3   3 weeks ago    77.9MB
ubuntu       jammy     8a3cdc4d1ad3   3 weeks ago    77.9MB
ubuntu       24.04     35a88802559d   6 weeks ago    78.1MB
ubuntu       latest    35a88802559d   6 weeks ago    78.1MB
ubuntu       noble     35a88802559d   6 weeks ago    78.1MB
```

### [Cancel a pull](#cancel-a-pull)

Killing the `docker pull` process, for example by pressing `CTRL-c` while it is running in a terminal, will terminate the pull operation.

```console
$ docker pull ubuntu

Using default tag: latest
latest: Pulling from library/ubuntu
a3ed95caeb02: Pulling fs layer
236608c7b546: Pulling fs layer
^C
```

The Engine terminates a pull operation when the connection between the daemon and the client (initiating the pull) is cut or lost for any reason or the command is manually terminated.

----
url: https://docs.docker.com/reference/cli/docker/mcp/feature/disable/
----

# docker mcp feature disable

***

| Description | Disable an experimental feature             |
| ----------- | ------------------------------------------- |
| Usage       | `docker mcp feature disable <feature-name>` |

## [Description](#description)

Disable an experimental feature that was previously enabled.

----
url: https://docs.docker.com/compose/install/
----

# Overview of installing Docker Compose

***

Table of contents

***

This page summarizes the different ways you can install Docker Compose, depending on your platform and needs.

## [Installation scenarios](#installation-scenarios)

### [Docker Desktop (Recommended)](#docker-desktop-recommended)

The easiest and recommended way to get Docker Compose is to install Docker Desktop.

Docker Desktop includes Docker Compose along with Docker Engine and Docker CLI which are Compose prerequisites.

Docker Desktop is available for:

* [Linux](https://docs.docker.com/desktop/setup/install/linux/)
* [Mac](https://docs.docker.com/desktop/setup/install/mac-install/)
* [Windows](https://docs.docker.com/desktop/setup/install/windows-install/)

> Tip
>
> If you have already installed Docker Desktop, you can check which version of Compose you have by selecting **About Docker Desktop** from the Docker menu .

### [Plugin (Linux only)](#plugin-linux-only)

> Important
>
> This method is only available on Linux.

If you already have Docker Engine and Docker CLI installed, you can install the Docker Compose plugin from the command line, by either:

* [Using Docker's repository](https://docs.docker.com/compose/install/linux/#install-using-the-repository)
* [Downloading and installing manually](https://docs.docker.com/compose/install/linux/#install-the-plugin-manually)

### [Standalone (Legacy)](#standalone-legacy)

> Warning
>
> This install scenario is not recommended and is only supported for backward compatibility purposes.

You can [install the Docker Compose standalone](https://docs.docker.com/compose/install/standalone/) on Linux or on Windows Server.

----
url: https://docs.docker.com/reference/cli/docker/trust/revoke/
----

# docker trust revoke

***

| Description | Remove trust for an image                   |
| ----------- | ------------------------------------------- |
| Usage       | `docker trust revoke [OPTIONS] IMAGE[:TAG]` |

## [Description](#description)

`docker trust revoke` removes signatures from tags in signed repositories.

## [Options](#options)

| Option      | Default | Description                    |
| ----------- | ------- | ------------------------------ |
| `-y, --yes` |         | Do not prompt for confirmation |

## [Examples](#examples)

### [Revoke signatures from a signed tag](#revoke-signatures-from-a-signed-tag)

Here's an example of a repository with two signed tags:

```console
$ docker trust inspect --pretty example/trust-demo
SIGNED TAG          DIGEST                                                              SIGNERS
red                 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943    alice
blue                f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197    alice, bob

List of signers and their keys for example/trust-demo:

SIGNER              KEYS
alice               05e87edcaecb
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

When `alice`, one of the signers, runs `docker trust revoke`:

```console
$ docker trust revoke example/trust-demo:red
Enter passphrase for delegation key with ID 27d42a8:
Successfully deleted signature for example/trust-demo:red
```

After revocation, the tag is removed from the list of released tags:

```console
$ docker trust inspect --pretty example/trust-demo
SIGNED TAG          DIGEST                                                              SIGNERS
blue                f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197    alice, bob

List of signers and their keys for example/trust-demo:

SIGNER              KEYS
alice               05e87edcaecb
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

### [Revoke signatures on all tags in a repository](#revoke-signatures-on-all-tags-in-a-repository)

When no tag is specified, `docker trust` revokes all signatures that you have a signing key for.

```console
$ docker trust inspect --pretty example/trust-demo
SIGNED TAG          DIGEST                                                              SIGNERS
red                 852cc04935f930a857b630edc4ed6131e91b22073bcc216698842e44f64d2943    alice
blue                f1c38dbaeeb473c36716f6494d803fbfbe9d8a76916f7c0093f227821e378197    alice, bob

List of signers and their keys for example/trust-demo:

SIGNER              KEYS
alice               05e87edcaecb
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

When `alice`, one of the signers, runs `docker trust revoke`:

```console
$ docker trust revoke example/trust-demo
Confirm you would like to delete all signature data for example/trust-demo? [y/N] y
Enter passphrase for delegation key with ID 27d42a8:
Successfully deleted signature for example/trust-demo
```

All tags that have `alice`'s signature on them are removed from the list of released tags:

```console
$ docker trust inspect --pretty example/trust-demo

No signatures for example/trust-demo


List of signers and their keys for example/trust-demo:

SIGNER              KEYS
alice               05e87edcaecb
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

----
url: https://docs.docker.com/ai/sandboxes/agents/
----

# Supported agents

***

***

Docker Sandboxes runs the following agents out of the box:

* [Claude Code](https://docs.docker.com/ai/sandboxes/agents/claude-code/)
* [Codex](https://docs.docker.com/ai/sandboxes/agents/codex/)
* [Copilot](https://docs.docker.com/ai/sandboxes/agents/copilot/)
* [Cursor](https://docs.docker.com/ai/sandboxes/agents/cursor/)
* [Droid](https://docs.docker.com/ai/sandboxes/agents/droid/)
* [Gemini](https://docs.docker.com/ai/sandboxes/agents/gemini/)
* [Kiro](https://docs.docker.com/ai/sandboxes/agents/kiro/)
* [OpenCode](https://docs.docker.com/ai/sandboxes/agents/opencode/)
* [Docker Agent](https://docs.docker.com/ai/sandboxes/agents/docker-agent/)
* [Shell](https://docs.docker.com/ai/sandboxes/agents/shell/) — agent-less sandbox for manual setup or testing

Want to pre-install tools or customize an agent's environment? See [Customize](https://docs.docker.com/ai/sandboxes/customize/).

----
url: https://docs.docker.com/reference/cli/docker/service/scale/
----

# docker service scale

***

| Description | Scale one or multiple replicated services                     |
| ----------- | ------------------------------------------------------------- |
| Usage       | `docker service scale SERVICE=REPLICAS [SERVICE=REPLICAS...]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

The scale command enables you to scale one or more replicated services either up or down to the desired number of replicas. This command cannot be applied on services which are global mode. The command will return immediately, but the actual scaling of the service may take some time. To stop all replicas of a service while keeping the service active in the swarm you can set the scale to 0.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option         | Default | Description                                                               |
| -------------- | ------- | ------------------------------------------------------------------------- |
| `-d, --detach` |         | API 1.29+ Exit immediately instead of waiting for the service to converge |

## [Examples](#examples)

### [Scale a single service](#scale-a-single-service)

The following command scales the "frontend" service to 50 tasks.

```console
$ docker service scale frontend=50

frontend scaled to 50
```

The following command tries to scale a global service to 10 tasks and returns an error.

```console
$ docker service create --mode global --name backend backend:latest

b4g08uwuairexjub6ome6usqh

$ docker service scale backend=10

backend: scale can only be used with replicated or replicated-job mode
```

Directly afterwards, run `docker service ls`, to see the actual number of replicas.

```console
$ docker service ls --filter name=frontend

ID            NAME      MODE        REPLICAS  IMAGE
3pr5mlvu3fh9  frontend  replicated  15/50     nginx:alpine
```

You can also scale a service using the [`docker service update`](/reference/cli/docker/service/update/) command. The following commands are equivalent:

```console
$ docker service scale frontend=50
$ docker service update --replicas=50 frontend
```

### [Scale multiple services](#scale-multiple-services)

The `docker service scale` command allows you to set the desired number of tasks for multiple services at once. The following example scales both the backend and frontend services:

```console
$ docker service scale backend=3 frontend=5

backend scaled to 3
frontend scaled to 5

$ docker service ls

ID            NAME      MODE        REPLICAS  IMAGE
3pr5mlvu3fh9  frontend  replicated  5/5       nginx:alpine
74nzcxxjv6fq  backend   replicated  3/3       redis:7.4.1
```

----
url: https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/limitations/
----

# Enhanced Container Isolation limitations

***

Table of contents

***

Subscription: Business

For: Administrators

Enhanced Container Isolation has some platform-specific limitations and feature constraints. Understanding these limitations helps you plan your security strategy and set appropriate expectations.

## [WSL 2 security considerations](#wsl-2-security-considerations)

> Note
>
> Docker Desktop requires WSL 2 version 2.1.5 or later. ECI on the WSL 2 backend requires WSL version 2.6 or later because ECI depends on a Linux kernel version of at least 6.3.0. Check your version with `wsl --version` and update with `wsl --update` if needed.

Enhanced Container Isolation provides different security levels depending on your Windows backend configuration.

The following table compares ECI on WSL 2 and ECI on Hyper-V:

| Security feature                                   | ECI on WSL | ECI on Hyper-V | Comment                                                                                           |
| -------------------------------------------------- | ---------- | -------------- | ------------------------------------------------------------------------------------------------- |
| Strongly secure containers                         | Yes        | Yes            | Makes it harder for malicious container workloads to breach the Docker Desktop Linux VM and host. |
| Docker Desktop Linux VM protected from user access | No         | Yes            | On WSL, users can access Docker Engine directly or bypass Docker Desktop security settings.       |
| Docker Desktop Linux VM has a dedicated kernel     | No         | Yes            | On WSL, Docker Desktop can't guarantee the integrity of kernel level configs.                     |

WSL 2 security gaps include:

* Direct VM access: Users can bypass Docker Desktop security by accessing the VM directly: `wsl -d docker-desktop`. This gives users root access to modify Docker Engine settings and bypass Settings Management configurations.
* Shared kernel vulnerability: All WSL 2 distributions share the same Linux kernel instance. Other WSL distributions can modify kernel settings that affect Docker Desktop's security.

### [Recommendation](#recommendation)

Use Hyper-V backend for maximum security. WSL 2 offers better performance and resource utilization, but provides reduced security isolation.

## [Windows containers not supported](#windows-containers-not-supported)

ECI only works with Linux containers (Docker Desktop's default mode). Native Windows containers mode isn't supported.

## [Docker Build protection varies](#docker-build-protection-varies)

Docker Build protection depends on the driver and Docker Desktop version:

| Build drive        | Protection       | Version requirements                         |
| ------------------ | ---------------- | -------------------------------------------- |
| `docker` (default) | Protected        | Docker Desktop 4.30 and later (except WSL 2) |
| `docker` (legacy)  | Not protected    | Docker Desktop versions before 4.30          |
| `docker-container` | Always protected | All Docker Desktop versions                  |

The following Docker Build features don't work with ECI:

* `docker build --network=host`
* Docker Buildx entitlements: `network.host`, `security.insecure`

### [Recommendation](#recommendation-1)

Use `docker-container` build driver for builds requiring these features:

```console
$ docker buildx create --driver docker-container --use
$ docker buildx build --network=host .
```

## [Docker Desktop Kubernetes not protected in Kubeadm mode](#docker-desktop-kubernetes-not-protected-in-kubeadm-mode)

The integrated Kubernetes feature, when used with the legacy Kubeadm provisioner, doesn't benefit from ECI protection. Malicious or privileged pods can compromise the Docker Desktop VM and bypass security controls.

### [Recommendation](#recommendation-2)

Use the newer Docker Desktop Kubernetes "KinD" provisioner (see [Cluster provisioning method](https://docs.docker.com/desktop/use-desktop/kubernetes/#cluster-provisioning-method)). In this mode, and with ECI turned on, each Kubernetes node runs in an ECI-protected container, providing stronger isolation from the Docker Desktop VM. The KinD provisioner is also faster and allows for multi-node Kubernetes clusters.

## [Unprotected container types](#unprotected-container-types)

These container types currently don't benefit from ECI protection:

* Docker Extensions: Extension containers run without ECI protection
* Kubernetes pods: When using Docker Desktop's integrated Kubernetes with the old Kubeadm provisioner.

### [Recommendation](#recommendation-3)

Only use extensions from trusted sources in security-sensitive environments.

## [Global command restrictions](#global-command-restrictions)

Command lists apply to all containers allowed to mount the Docker socket. You can't configure different command restrictions per container image.

## [Local-only images not supported](#local-only-images-not-supported)

You can't allow arbitrary local-only images (images not in a registry) to mount the Docker socket, unless they're:

* Derived from an allowed base image (with `allowDerivedImages: true`)
* Using the wildcard allowlist (`"*"`, Docker Desktop 4.36 and later)

## [Unsupported Docker commands](#unsupported-docker-commands)

These Docker commands aren't yet supported in command list restrictions:

* `compose`: Docker Compose commands
* `dev`: Development environment commands
* `extension`: Docker Extensions management
* `feedback`: Docker feedback submission
* `init`: Docker initialization commands
* `manifest`: Image manifest management
* `plugin`: Plugin management
* `sbom`: Software Bill of Materials
* `scout`: Docker Scout commands
* `trust`: Image trust management

## [Performance considerations](#performance-considerations)

### [Derived images impact](#derived-images-impact)

Enabling `allowDerivedImages: true` adds approximately 1 second to container startup time for image validation.

### [Registry dependencies](#registry-dependencies)

* Docker Desktop periodically fetches image digests from registries for validation
* Initial container starts require registry access to validate allowed images
* Network connectivity issues may cause delays in container startup

### [Image digest validation](#image-digest-validation)

When allowed images are updated in registries, local containers may be unexpectedly blocked until you refresh the local image:

```console
$ docker image rm <image>
$ docker pull <image>
```

## [Production compatibility](#production-compatibility)

### [Container behavior differences](#container-behavior-differences)

Most containers run identically with and without ECI. However, some advanced workloads may behave differently:

* Containers requiring kernel module loading
* Workloads modifying global kernel settings (BPF, sysctl)
* Applications expecting specific privilege escalation behavior
* Tools requiring direct hardware device access

Test advanced workloads with ECI in development environments before production deployment to ensure compatibility.

### [Runtime considerations](#runtime-considerations)

Containers using the Sysbox runtime (with ECI) may have subtle differences compared to standard OCI runc runtime in production. These differences typically only affect privileged or system-level operations.

----
url: https://docs.docker.com/ai/docker-agent/evals/
----

# Evals

***

Table of contents

***

Evaluations (evals) help you track how your agent's behavior changes over time. When you save a conversation as an eval, you can replay it later to see if the agent responds differently. Evals measure consistency, not correctness - they tell you if behavior changed, not whether it's right or wrong.

## [What are evals](#what-are-evals)

An eval is a saved conversation you can replay. When you run evals, Docker Agent replays the user messages and compares the new responses against the original saved conversation. High scores mean the agent behaved similarly; low scores mean behavior changed.

What you do with that information depends on why you saved the conversation. You might save successful conversations to catch regressions, or save failure cases to document known issues and track whether they improve.

## [Common workflows](#common-workflows)

How you use evals depends on what you're trying to accomplish:

Regression testing: Save conversations where your agent performs well. When you make changes later (upgrade models, update prompts, refactor code), run the evals. High scores mean behavior stayed consistent, which is usually what you want. Low scores mean something changed - examine the new behavior to see if it's still correct.

Tracking improvements: Save conversations where your agent struggles or fails. As you make improvements, run these evals to see how behavior evolves. Low scores indicate the agent now behaves differently, which might mean you fixed the issue. You'll need to manually verify the new behavior is actually better.

Documenting edge cases: Save interesting or unusual conversations regardless of quality. Use them to understand how your agent handles edge cases and whether that behavior changes over time.

Evals measure whether behavior changed. You determine if that change is good or bad.

## [Creating an eval](#creating-an-eval)

Save a conversation from an interactive session:

```console
$ docker agent run ./agent.yaml
```

Have a conversation with your agent, then save it as an eval:

```console
> /eval test-case-name
Eval saved to evals/test-case-name.json
```

The conversation is saved to the `evals/` directory in your current working directory. You can organize eval files in subdirectories if needed.

## [Running evals](#running-evals)

Run all evals in the default directory:

```console
$ docker agent eval ./agent.yaml
```

Use a custom eval directory:

```console
$ docker agent eval ./agent.yaml ./my-evals
```

Run evals against an agent from a registry:

```console
$ docker agent eval agentcatalog/myagent
```

Example output:

```console
$ docker agent eval ./agent.yaml
--- 0
First message: tell me something interesting about kil
Eval file: c7e556c5-dae5-4898-a38c-73cc8e0e6abe
Tool trajectory score: 1.000000
Rouge-1 score: 0.447368
Cost: 0.00
Output tokens: 177
```

## [Understanding results](#understanding-results)

For each eval, Docker Agent shows:

* **First message** - The initial user message from the saved conversation
* **Eval file** - The UUID of the eval file being run
* **Tool trajectory score** - How similarly the agent used tools (0-1 scale, higher is better)
* **[ROUGE-1](https://en.wikipedia.org/wiki/ROUGE_%28metric%29) score** - Text similarity between responses (0-1 scale, higher is better)
* **Cost** - The cost for this eval run
* **Output tokens** - Number of tokens generated

Higher scores mean the agent behaved more similarly to the original recorded conversation. A score of 1.0 means identical behavior.

### [What the scores mean](#what-the-scores-mean)

**Tool trajectory score** measures whether the agent called the same tools in the same order as the original conversation. Lower scores might indicate the agent found a different approach to solve the problem, which isn't necessarily wrong but worth investigating.

**Rouge-1 score** measures how similar the response text is to the original. This is a heuristic measure - different wording might still be correct, so use this as a signal rather than absolute truth.

### [Interpreting your results](#interpreting-your-results)

Scores close to 1.0 mean your changes maintained consistent behavior - the agent is using the same approach and producing similar responses. This is generally good; your changes didn't break existing functionality.

Lower scores mean behavior changed compared to the saved conversation. This could be a regression where the agent now performs worse, or it could be an improvement where the agent found a better approach.

When scores drop, examine the actual behavior to determine if it's better or worse. The eval files are stored as JSON in your evals directory - open the file to see the original conversation. Then test your modified agent with the same input to compare responses. If the new response is better, save a new conversation to replace the eval. If it's worse, you found a regression.

The scores guide you to what changed. Your judgment determines if the change is good or bad.

## [When to use evals](#when-to-use-evals)

Evals help you track behavior changes over time. They're useful for catching regressions when you upgrade models or dependencies, documenting known failure cases you want to fix, and understanding how edge cases evolve as you iterate.

Evals aren't appropriate for determining which agent configuration works best - they measure similarity to a saved conversation, not correctness. Use manual testing to evaluate different configurations and decide which works better.

Save conversations worth tracking. Build a collection of important workflows, interesting edge cases, and known issues. Run your evals when making changes to see what shifted.

## [What's next](#whats-next)

* Check the [CLI reference](https://docs.docker.com/ai/docker-agent/reference/cli/#eval) for all `docker agent eval` options
* Learn [best practices](https://docs.docker.com/ai/docker-agent/best-practices/) for building effective agents
* Review [example configurations](https://github.com/docker/docker-agent/tree/main/examples) for different agent types

----
url: https://docs.docker.com/offload/troubleshoot/
----

# Troubleshoot Docker Offload

***

***

Subscription: Docker Offload

Requires: Docker Desktop 4.68 or later

Docker Offload requires:

* Authentication
* An active internet connection
* No restrictive proxy or firewall blocking traffic to Docker Cloud
* Access to Docker Offload
* Docker Desktop 4.68 or later

Docker Desktop uses Offload to run both builds and containers in the cloud. If builds or containers are failing to run, falling back to local, or reporting session errors, use the following steps to help resolve the issue.

1. Ensure Docker Offload is enabled in Docker Desktop:

   1. Open Docker Desktop and sign in.
   2. Go to **Settings** > **Docker Offload**.
   3. Ensure that **Enable Docker Offload** is toggled on.

2. Use the following command to check if the connection is active:

   ```console
   $ docker offload status
   ```

3. To get more information, run the following command:

   ```console
   $ docker offload diagnose
   ```

4. If you're not connected, start a new session:

   ```console
   $ docker offload start
   ```

5. Verify authentication with `docker login`.

6. If needed, you can sign out and then sign in again:

   ```console
   $ docker logout
   $ docker login
   ```

7. Verify your usage. For more information, see [Docker Offload usage](/offload/usage/).

----
url: https://docs.docker.com/compose/
----

# Docker Compose

***

***

Docker Compose is a tool for defining and running multi-container applications. It is the key to unlocking a streamlined and efficient development and deployment experience.

Compose simplifies the control of your entire application stack, making it easy to manage services, networks, and volumes in a single YAML configuration file. Then, with a single command, you create and start all the services from your configuration file.

Compose works in all environments - production, staging, development, testing, as well as CI workflows. It also has commands for managing the whole lifecycle of your application:

* Start, stop, and rebuild services
* View the status of running services
* Stream the log output of running services
* Run a one-off command on a service

### [Why use Compose?](/compose/intro/features-uses/)

[Understand Docker Compose's key benefits](/compose/intro/features-uses/)

### [How Compose works](/compose/intro/compose-application-model/)

[Understand how Compose works](/compose/intro/compose-application-model/)

### [Install Compose](/compose/install)

[Follow the instructions on how to install Docker Compose.](/compose/install)

### [Quickstart](/compose/gettingstarted)

[Learn the key concepts of Docker Compose whilst building a simple Python web application.](/compose/gettingstarted)

### [View the release notes](https://github.com/docker/compose/releases)

[Find out about the latest enhancements and bug fixes.](https://github.com/docker/compose/releases)

### [Explore the Compose file reference](/reference/compose-file)

[Find information on defining services, networks, and volumes for a Docker application.](/reference/compose-file)

### [Use Compose Bridge](/compose/bridge)

[Transform your Compose configuration file into configuration files for different platforms, such as Kubernetes.](/compose/bridge)

### [Browse common FAQs](/compose/faq)

[Explore general FAQs and find out how to give feedback.](/compose/faq)

----
url: https://docs.docker.com/build-cloud/builder-settings/
----

# Builder settings

***

Table of contents

***

The **Builder settings** page in Docker Build Cloud lets you configure disk allocation, private resource access, and firewall settings for your cloud builders in your organization. These configurations help optimize storage, enable access to private registries, and secure outbound network traffic.

## [Storage and cache management](#storage-and-cache-management)

### [Disk allocation](#disk-allocation)

The **Disk allocation** setting lets you control how much of the available storage is dedicated to the build cache. A lower allocation increases storage available for active builds.

To make disk allocation changes, navigate to **Builder settings** in Docker Build Cloud and then adjust the **Disk allocation** slider to specify the percentage of storage used for build caching.

Any changes take effect immediately.

### [Build cache space](#build-cache-space)

Your subscription includes the following Build cache space:

| Subscription | Build cache space |
| ------------ | ----------------- |
| Personal     | N/A               |
| Pro          | 50GB              |
| Team         | 100GB             |
| Business     | 200GB             |

### [Multi-architecture storage allocation](#multi-architecture-storage-allocation)

Docker Build Cloud automatically provisions builders for both amd64 and arm64 architectures. Your total build cache space is split equally between these two builders:

* Pro (50GB total): 25GB for amd64 builder + 25GB for arm64 builder
* Team (100GB total): 50GB for amd64 builder + 50GB for arm64 builder
* Business (200GB total): 100GB for amd64 builder + 100GB for arm64 builder

> Important
>
> If you only build for one architecture, be aware that your effective cache space is half of your subscription's total allocation.

### [Get more build cache space](#get-more-build-cache-space)

To get more Build cache space, [upgrade your subscription](https://docs.docker.com/subscription/scale/).

> Tip
>
> If you build large images, consider allocating less storage for caching to leave more space for active builds.

## [Private resource access](#private-resource-access)

Private resource access lets cloud builders pull images and packages from private resources. This feature is useful when builds rely on self-hosted artifact repositories or private OCI registries.

For example, if your organization hosts a private [PyPI](https://pypi.org/) repository on a private network, Docker Build Cloud would not be able to access it by default, since the cloud builder is not connected to your private network.

To enable your cloud builders to access your private resources, enter the host name and port of your private resource and then select **Add**.

### [Authentication](#authentication)

If your internal artifacts require authentication, make sure that you authenticate with the repository either before or during the build. For internal package repositories for npm or PyPI, use [build secrets](https://docs.docker.com/build/building/secrets/) to authenticate during the build. For internal OCI registries, use `docker login` to authenticate before building.

If you use a private registry that requires authentication, you need to authenticate twice before building: once to Docker Hub (to access Docker Build Cloud), and once to your private registry (to push/pull images).

```console
$ echo $DOCKER_PAT | docker login docker.io -u <username> --password-stdin
$ echo $REGISTRY_PASSWORD | docker login registry.example.com -u <username> --password-stdin
$ docker build --builder <cloud-builder> --tag registry.example.com/<image> --push .
```

## [Firewall](#firewall)

Firewall settings let you restrict cloud builder egress traffic to specific IP addresses. This helps enhance security by limiting external network egress from the builder.

1. Select the **Enable firewall: Restrict cloud builder egress to specific public IP address** checkbox.
2. Enter the IP address you want to allow.
3. Select **Add** to apply the restriction.

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/show/
----

# docker mcp profile show

***

| Description | Show profile                           |
| ----------- | -------------------------------------- |
| Usage       | `docker mcp profile show <profile-id>` |

## [Description](#description)

Show profile

## [Options](#options)

| Option      | Default | Description                          |
| ----------- | ------- | ------------------------------------ |
| `--clients` |         | Include client information in output |
| `--format`  | `human` | Supported: json, yaml, human.        |
| `--yq`      |         | YQ expression to apply to the output |

----
url: https://docs.docker.com/build/builders/
----

# Builders

***

Table of contents

***

A builder is a BuildKit daemon that you can use to run your builds. BuildKit is the build engine that solves the build steps in a Dockerfile to produce a container image or other artifacts.

You can create and manage builders, inspect them, and even connect to builders running remotely. You interact with builders using the Docker CLI.

## [Default builder](#default-builder)

Docker Engine automatically creates a builder that becomes the default backend for your builds. This builder uses the BuildKit library bundled with the daemon. This builder requires no configuration.

The default builder is directly bound to the Docker daemon and its [context](https://docs.docker.com/engine/manage-resources/contexts/). If you change the Docker context, your `default` builder refers to the new Docker context.

## [Build drivers](#build-drivers)

Buildx implements a concept of [build drivers](https://docs.docker.com/build/builders/drivers/) to refer to different builder configurations. The default builder created by the daemon uses the [`docker` driver](https://docs.docker.com/build/builders/drivers/docker/).

Buildx supports the following build drivers:

* `docker`: uses the BuildKit library bundled into the Docker daemon.
* `docker-container`: creates a dedicated BuildKit container using Docker.
* `kubernetes`: creates BuildKit pods in a Kubernetes cluster.
* `remote`: connects directly to a manually managed BuildKit daemon.

## [Selected builder](#selected-builder)

Selected builder refers to the builder that's used by default when you run build commands.

When you run a build, or interact with builders in some way using the CLI, you can use the optional `--builder` flag, or the `BUILDX_BUILDER` [environment variable](https://docs.docker.com/build/building/variables/#buildx_builder), to specify a builder by name. If you don't specify a builder, the selected builder is used.

Use the `docker buildx ls` command to see the available builder instances. The asterisk (`*`) next to a builder name indicates the selected builder.

```console
$ docker buildx ls
NAME/NODE       DRIVER/ENDPOINT      STATUS   BUILDKIT PLATFORMS
default *       docker
  default       default              running  v0.11.6  linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
my_builder      docker-container
  my_builder0   default              running  v0.11.6  linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/386
```

### [Select a different builder](#select-a-different-builder)

To switch between builders, use the `docker buildx use <name>` command.

After running this command, the builder you specify is automatically selected when you invoke builds.

### [Difference between `docker build` and `docker buildx build`](#difference-between-docker-build-and-docker-buildx-build)

Even though `docker build` is an alias for `docker buildx build`, there are subtle differences between the two commands. With Buildx, the build client and the daemon (BuildKit) are decoupled. This means you can use multiple builders from a single client, even remote ones.

The `docker build` command always defaults to using the default builder that comes bundled with the Docker Engine, to ensure backwards compatibility with older versions of the Docker CLI. The `docker buildx build` command, on the other hand, checks whether you've set a different builder as the default builder before it sends your build to BuildKit.

To use the `docker build` command with a non-default builder, you must either specify the builder explicitly:

* Using the `--builder` flag:

  ```console
  $ docker build --builder my_builder .
  ```

* Or the `BUILDX_BUILDER` environment variable:

  ```console
  $ BUILDX_BUILDER=my_builder docker build .
  ```

In general, we recommend that you use the `docker buildx build` command when you want to use custom builders. This ensures that your [selected builder](#selected-builder) configuration is interpreted correctly.

## [Additional information](#additional-information)

* For information about how to interact with and manage builders, see [Manage builders](https://docs.docker.com/build/builders/manage/)
* To learn about different types of builders, see [Build drivers](https://docs.docker.com/build/builders/drivers/)

----
url: https://docs.docker.com/dhi/explore/scanner-integrations/
----

# Scanner integrations

***

Table of contents

***

Docker Hardened Images work with various vulnerability scanners. However, to get accurate results that reflect the actual security posture of these images, your scanner needs to understand the VEX (Vulnerability Exploitability eXchange) attestations included with each image.

## [Scanners with VEX support](#scanners-with-vex-support)

The following scanners can read and apply VEX attestations included with Docker Hardened Images to deliver more accurate vulnerability assessments:

* [Docker Scout](/scout/): Automatically applies VEX statements with zero configuration. Integrated directly into Docker Desktop and the Docker CLI.
* [Trivy](https://trivy.dev/): Supports VEX through VEX Hub for automatic updates or local VEX files for air-gapped environments.
* [Grype](https://github.com/anchore/grype): Supports VEX via the `--vex` flag for local VEX file processing.
* [Wiz](https://www.wiz.io/): Automatically applies VEX statements with zero configuration.
* [Mend.io](https://www.mend.io/): Automatically retrieves and applies VEX statements with zero configuration. Combines VEX data with reachability analysis.
* [Black Duck](https://www.blackduck.com/): Identifies Docker Hardened Images and applies VEX statements with zero configuration.

For step-by-step instructions, see [Scan Docker Hardened Images](https://docs.docker.com/dhi/how-to/scan/).

## [Choosing a scanner for Docker Hardened Images](#choosing-a-scanner-for-docker-hardened-images)

When selecting a scanner for use with Docker Hardened Images, whether it supports open standards like OpenVEX is the key differentiator.

Docker Hardened Images include signed VEX attestations that follow the [OpenVEX standard](https://openvex.dev/). OpenVEX is an open standard that meets the minimum requirements for VEX defined by CISA (Cybersecurity and Infrastructure Security Agency), the U.S. government agency responsible for cybersecurity guidance. These attestations document which vulnerabilities don't apply to the image and why, helping you focus on real risks. To understand what VEX is and how it works, see the [VEX core concept](https://docs.docker.com/dhi/core-concepts/vex/).

Because OpenVEX is an open standard with government backing, it has strong industry momentum and any tool can implement it without vendor-specific integrations. This matters when you bring in third-party auditors with their own scanning tools, or when you want to use multiple security tools in your pipeline. With VEX, these tools can all read and verify the same vulnerability data directly from your images.

Without open standards like VEX, vendors make exploitability decisions using proprietary methods, making it difficult to verify claims or compare results across tools. This fragments your security toolchain and creates inconsistent vulnerability assessments across different scanning tools.

### [Benefits of scanners with VEX support](#benefits-of-scanners-with-vex-support)

Scanners that support open standards like OpenVEX and can interpret VEX attestations from Docker Hardened Images offer the following benefits:

* Accurate vulnerability counts: Automatically filter out vulnerabilities that don't apply to your specific image, often reducing false positives dramatically.
* Transparency and auditability: Verify exactly why vulnerabilities are or aren't flagged; security teams and compliance officers can review the reasoning rather than trusting a vendor's black box.
* Scanner flexibility: Switch between any VEX-enabled scanner (Docker Scout, Trivy, Grype, Wiz, Mend.io, Black Duck, etc.) without losing vulnerability context or rebuilding exclusion lists.
* Consistent results: VEX-enabled scanners interpret the same data the same way, eliminating discrepancies between tools.
* Faster workflows: Focus on real risks rather than researching why reported CVEs don't actually affect your deployment.

### [Scanners without VEX support](#scanners-without-vex-support)

Scanners that can't read VEX attestations will report vulnerabilities that don't apply to Docker Hardened Images. This creates operational challenges:

* Manual filtering required: You'll need to maintain scanner-specific ignore lists to replicate what VEX statements already document.
* Higher false positive rates: Expect to see more reported vulnerabilities that don't represent real risks.
* Increased investigation time: Security teams spend time researching why CVEs don't apply instead of addressing actual vulnerabilities. With Docker Hardened Images, security experts at Docker manage this investigation for you, thoroughly vetting each justification before adding it to a VEX statement.
* CI/CD friction: Build pipelines may fail on vulnerabilities that aren't exploitable in your images.

### [VEX-based vulnerability handling versus proprietary approaches](#vex-based-vulnerability-handling-versus-proprietary-approaches)

Docker Hardened Images use VEX attestations based on the OpenVEX open standard to document vulnerability exploitability. OpenVEX is an open standard that is recognized by government agencies such as CISA. This open standards approach differs from how some other image vendors handle vulnerabilities using proprietary methods.

#### [Docker Hardened Images with VEX](#docker-hardened-images-with-vex)

The image includes signed attestations that explain which vulnerabilities don't apply and why. Any VEX-enabled scanner can read these attestations, giving you:

* Tool flexibility: Use any scanner that supports OpenVEX (Docker Scout, Trivy, Grype, Wiz, Mend.io, Black Duck, etc.)
* Complete transparency: Review the exact reasoning for each vulnerability assessment
* Full auditability: Security teams and compliance officers can independently verify all vulnerability assessments and reasoning
* Historical visibility: VEX statements remain with the image, so you can always check vulnerability status, even for older versions

#### [Proprietary vulnerability handling](#proprietary-vulnerability-handling)

Some image vendors use proprietary advisory feeds or internal databases instead of VEX. While this may result in fewer reported vulnerabilities, it creates significant limitations:

* Tool dependency: You must use the vendor's preferred scanning tools to see their vulnerability filtering, while standard scanners will still report all CVEs; scanners must implement proprietary feeds rather than using open standards that work with all images
* No transparency: Proprietary feeds act as "black boxes" - vulnerabilities simply disappear from vendor tools with no explanation
* Limited verifiability: Security teams have no way to independently verify why vulnerabilities are excluded or whether the reasoning is sound
* Maintenance challenges: If you scan older image versions with standard tools, you can't determine which vulnerabilities actually applied at that time, making long-term security tracking difficult
* Ecosystem incompatibility: Your existing security tools (SCA, policy engines, compliance scanners) can't access or verify the vendor's proprietary vulnerability data

The fundamental difference: VEX-based approaches explain vulnerability assessments using open standards that any tool can verify and audit. Proprietary approaches hide vulnerabilities in vendor-specific systems where the reasoning can't be independently validated.

For Docker Hardened Images, use VEX-enabled scanners to get accurate results that work across your entire security toolchain.

## [What to expect from different scanners](#what-to-expect-from-different-scanners)

When scanning Docker Hardened Images with different tools, you'll see significant differences in reported vulnerability counts.

### [What VEX-enabled scanners filter automatically](#what-vex-enabled-scanners-filter-automatically)

When you scan Docker Hardened Images with VEX-enabled scanners, they automatically exclude vulnerabilities that don't apply:

* Hardware-specific vulnerabilities: Issues that only affect specific hardware architectures (for example, Power10 processors) that are irrelevant to containerized workloads.
* Unreachable code paths: CVEs in code that exists in the package but isn't executed in the image's runtime configuration.
* Build-time only issues: Vulnerabilities in build tools or dependencies that don't exist in the final runtime image.
* Temporary identifiers: Placeholder vulnerability IDs (like Debian's `TEMP-xxxxxxx`) that aren't intended for external tracking.

### [Using scanners without VEX support](#using-scanners-without-vex-support)

If your scanner doesn't support VEX, you'll need to manually exclude vulnerabilities through scanner-specific mechanisms like ignore lists or policy exceptions. This requires:

* Reviewing VEX statements from Docker Hardened Images
* Translating VEX justifications into your scanner's format
* Maintaining these exclusions as new vulnerabilities are discovered
* Repeating this process if you switch scanners or add additional scanning tools

## [What's next](#whats-next)

Learn how to [scan Docker Hardened Images](https://docs.docker.com/dhi/how-to/scan/) with VEX-compliant scanners.

----
url: https://docs.docker.com/docker-hub/image-library/trusted-content/
----

***

Table of contents

***

Docker Hub's trusted content provides a curated selection of high-quality, secure images designed to give developers confidence in the reliability and security of the resources they use. These images are stable, regularly updated, and adhere to industry best practices, making them a strong foundation for building and deploying applications. Docker Hub's trusted content includes Docker Official Images, Docker Hardened Images and charts, Verified Publisher images, and Docker-Sponsored Open Source Software images.

## [Docker Official Images](#docker-official-images)

The Docker Official Images are a curated set of Docker repositories hosted on Docker Hub.

Docker recommends you use the Docker Official Images in your projects. These images have clear documentation, promote best practices, and are regularly updated. Docker Official Images support most common use cases, making them perfect for new Docker users. Advanced users can benefit from more specialized image variants as well as review Docker Official Images as part of your `Dockerfile` learning process.

> Note
>
> Use of Docker Official Images is subject to [Docker's Terms of Service](https://www.docker.com/legal/docker-terms-service/).

These images provide essential base repositories that serve as the starting point for the majority of users.

These include operating systems such as [Ubuntu](https://hub.docker.com/_/ubuntu/) and [Alpine](https://hub.docker.com/_/alpine/), programming language runtimes such as [Python](https://hub.docker.com/_/python) and [Node](https://hub.docker.com/_/node), and other essential tools such as [memcached](https://hub.docker.com/_/memcached) and [MySQL](https://hub.docker.com/_/mysql).

The images are some of the [most secure images](https://www.docker.com/blog/enhancing-security-and-transparency-with-docker-official-images/) on Docker Hub. This is particularly important as Docker Official Images are some of the most popular on Docker Hub. Typically, Docker Official images have few or no packages containing CVEs.

The images exemplify [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/) and provide clear documentation to serve as a reference for other Dockerfile authors.

Images that are part of this program have a special badge on Docker Hub making it easier for you to identify projects that are part of Docker Official Images.

### [Supported tags and respective Dockerfile links](#supported-tags-and-respective-dockerfile-links)

The repository description for each Docker Official Image contains a **Supported tags and respective Dockerfile links** section that lists all the current tags with links to the Dockerfiles that created the image with those tags. The purpose of this section is to show what image variants are available.

Tags listed on the same line all refer to the same underlying image. Multiple tags can point to the same image. For example, in the previous screenshot taken from the `ubuntu` Docker Official Images repository, the tags `24.04`, `noble-20240225`, `noble`, and `devel` all refer to the same image.

The `latest` tag for a Docker Official Image is often optimized for ease of use and includes a wide variety of useful software, such as developer and build tools. By tagging an image as `latest`, the image maintainers are essentially suggesting that image be used as the default. In other words, if you do not know what tag to use or are unfamiliar with the underlying software, you should probably start with the `latest` image. As your understanding of the software and image variants advances, you may find other image variants better suit your needs.

### [Slim images](#slim-images)

A number of language stacks such as [Node.js](https://hub.docker.com/_/node/), [Python](https://hub.docker.com/_/python/), and [Ruby](https://hub.docker.com/_/ruby/) have `slim` tag variants designed to provide a lightweight, production-ready base image with fewer packages.

A typical consumption pattern for `slim` images is as the base image for the final stage of a [multi-staged build](https://docs.docker.com/build/building/multi-stage/). For example, you build your application in the first stage of the build using the `latest` variant and then copy your application into the final stage based upon the `slim` variant. Here is an example `Dockerfile`.

```dockerfile
FROM node:latest AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . ./
FROM node:slim
WORKDIR /app
COPY --from=build /app /app
CMD ["node", "app.js"]
```

### [Alpine images](#alpine-images)

Many Docker Official Images repositories also offer `alpine` variants. These images are built on top of the [Alpine Linux](https://www.alpinelinux.org/) distribution rather than Debian or Ubuntu. Alpine Linux is focused on providing a small, simple, and secure base for container images, and Docker Official Images `alpine` variants typically aim to install only necessary packages. As a result, Docker Official Images `alpine` variants are typically even smaller than `slim` variants.

The main caveat to note is that Alpine Linux uses [musl libc](https://musl.libc.org/) instead of [glibc](https://www.gnu.org/software/libc/). Additionally, to minimize image size, it's uncommon for Alpine-based images to include tools such as Git or Bash by default. Depending on the depth of libc requirements or assumptions in your programs, you may find yourself running into issues due to missing libraries or tools.

When you use Alpine images as a base, consider the following options in order to make your program compatible with Alpine Linux and musl:

* Compile your program against musl libc
* Statically link glibc libraries into your program
* Avoid C dependencies altogether (for example, build Go programs without CGO)
* Add the software you need yourself in your Dockerfile.

Refer to the `alpine` image [description](https://hub.docker.com/_/alpine) on Docker Hub for examples on how to install packages if you are unfamiliar.

### [Codenames](#codenames)

Tags with words that look like Toy Story characters (for example, `bookworm`, `bullseye`, and `trixie`) or adjectives (such as `jammy`, and `noble`), indicate the codename of the Linux distribution they use as a base image. Debian release codenames are [based on Toy Story characters](https://en.wikipedia.org/wiki/Debian_version_history#Naming_convention), and Ubuntu's take the form of "Adjective Animal". For example, the codename for Ubuntu 24.04 is "Noble Numbat".

Linux distribution indicators are helpful because many Docker Official Images provide variants built upon multiple underlying distribution versions (for example, `postgres:bookworm` and `postgres:bullseye`).

### [Other tags](#other-tags)

Docker Official Images tags may contain other hints to the purpose of their image variant in addition to those described here. Often these tag variants are explained in the Docker Official Images repository documentation. Reading through the "How to use this image" and "Image Variants" sections will help you to understand how to use these variants.

### [Troubleshooting failed pulls](#troubleshooting-failed-pulls)

If you're experiencing failed pulls of Docker Official Images, check whether the `DOCKER_CONTENT_TRUST` environment variable is set to `1`. Starting in August 2025, Docker Content Trust signing certificates for Docker Official Images began expiring. To resolve pull failures, unset the `DOCKER_CONTENT_TRUST` environment variable. For more details, see the [DCT retirement blog post](https://www.docker.com/blog/retiring-docker-content-trust/).

## [Docker Hardened Images](#docker-hardened-images)

Docker Hardened Images (DHI) are minimal, secure, and production-ready container base and application images maintained by Docker. DHI also includes Docker-provided hardened Helm charts built from upstream sources and published as OCI artifacts in Docker Hub.

DHI is designed to reduce vulnerabilities and simplify compliance while fitting into existing Docker workflows with little to no retooling required. Docker maintains near-zero CVEs in DHI images, and DHI images and charts include signed security metadata such as SBOMs and provenance attestations.

Image and chart repositories have special badges on Docker Hub, making it easier to identify trusted DHI content.

To browse available repositories, see the [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog). For implementation guidance, see [Docker Hardened Images](/dhi/).

## [Verified Publisher images](#verified-publisher-images)

The Docker Verified Publisher program provides high-quality images from commercial publishers verified by Docker.

These images help development teams build secure software supply chains, minimizing exposure to malicious content early in the process to save time and money later.

Images that are part of this program have a special badge on Docker Hub making it easier for users to identify projects that Docker has verified as high-quality commercial publishers.

## [Docker-Sponsored Open Source Software images](#docker-sponsored-open-source-software-images)

The Docker-Sponsored Open Source Software (OSS) program provides images that are published and maintained by open-source projects sponsored by Docker.

Images that are part of this program have a special badge on Docker Hub making it easier for users to identify projects that Docker has verified as trusted, secure, and active open-source projects.

----
url: https://docs.docker.com/guides/cpp/configure-ci-cd/
----

# Configure CI/CD for your C++ application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a C++ application](https://docs.docker.com/guides/cpp/containerize/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

   ```console
   $ git remote set-url origin https://github.com/your-username/your-repository.git
   ```

7. Run the following commands to stage, commit, and push your local repository to GitHub.

   ```console
   $ git add -A
   $ git commit -m "my commit"
   $ git push -u origin main
   ```

## [Step two: Set up the workflow](#step-two-set-up-the-workflow)

Set up your GitHub Actions workflow for building, testing, and pushing the image to Docker Hub.

1. Go to your repository on GitHub and then select the **Actions** tab.

2. Select **set up a workflow yourself**.

   This takes you to a page for creating a new GitHub actions workflow file in your repository, under `.github/workflows/main.yml` by default.

3. In the editor window, copy and paste the following YAML configuration and commit the changes.

   ```yaml
   name: ci

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Login to Docker Hub
           uses: docker/login-action@v4
           with:
             username: ${{ vars.DOCKER_USERNAME }}
             password: ${{ secrets.DOCKERHUB_TOKEN }}

         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v4

         - name: Build and push
           uses: docker/build-push-action@v7
           with:
             platforms: linux/amd64,linux/arm64
             push: true
             tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
   ```

In this section, you learned how to set up a GitHub Actions workflow for your C++ application.

Related information:

* [Introduction to GitHub Actions](https://docs.docker.com/guides/gha/)
* [Docker Build GitHub Actions](https://docs.docker.com/build/ci/github-actions/)
* [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)

## [Next steps](#next-steps)

Next, learn how you can locally test and debug your workloads on Kubernetes before deploying.

[Test your C++ deployment »](https://docs.docker.com/guides/cpp/deploy/)

----
url: https://docs.docker.com/engine/release-notes/17.09/
----

# Docker Engine 17.09 release notes

***

Table of contents

***

## [17.09.1-ce](#17091-ce)

2017-12-07

### [Builder](#builder)

* Fix config leakage on shared parent stage [moby/moby#33753](https://github.com/moby/moby/issues/33753)
* Warn on empty continuation lines only, not on comment-only lines [moby/moby#35004](https://github.com/moby/moby/pull/35004)

### [Client](#client)

* Set API version on Client even when Ping fails [docker/cli#546](https://github.com/docker/cli/pull/546)

### [Networking](#networking)

* Overlay fix for transient IP reuse [docker/libnetwork#2016](https://github.com/docker/libnetwork/pull/2016)
* Fix reapTime logic in NetworkDB and handle DNS cleanup for attachable container [docker/libnetwork#2017](https://github.com/docker/libnetwork/pull/2017)
* Disable hostname lookup on chain exists check [docker/libnetwork#2019](https://github.com/docker/libnetwork/pull/2019)
* Fix lint issues [docker/libnetwork#2020](https://github.com/docker/libnetwork/pull/2020)
* Restore error type in FindNetwork [moby/moby#35634](https://github.com/moby/moby/pull/35634)

### [Runtime](#runtime)

* Protect `health monitor` Go channel [moby/moby#35482](https://github.com/moby/moby/pull/35482)
* Fix leaking container/exec state [moby/moby#35484](https://github.com/moby/moby/pull/35484)
* Add /proc/scsi to masked paths (patch to work around [CVE-2017-16539](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-16539) [moby/moby/#35399](https://github.com/moby/moby/pull/35399)
* Vendor tar-split: fix to prevent memory exhaustion issue that could crash Docker daemon [moby/moby/#35424](https://github.com/moby/moby/pull/35424) Fixes [CVE-2017-14992](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-14992)
* Fix P/Z HubPullSuite tests [moby/moby#34837](https://github.com/moby/moby/pull/34837)

- Windows: Add support for version filtering on pull [moby/moby#35090](https://github.com/moby/moby/pull/35090)

* Windows: Stop filtering Windows manifest lists by version [moby/moby#35117](https://github.com/moby/moby/pull/35117)
* Use rslave instead of rprivate in chroot archive [moby/moby/#35217](https://github.com/moby/moby/pull/35217)
* Remove container rootfs mountPath after unmount [moby/moby#34573](https://github.com/moby/moby/pull/34573)
* Fix honoring tmpfs size of user /dev/shm mount [moby/moby#35316](https://github.com/moby/moby/pull/35316)
* Don't abort when setting may\_detach\_mounts (log the error instead) [moby/moby#35172](https://github.com/moby/moby/pull/35172)
* Fix version comparison when negotiating the API version [moby/moby#35008](https://github.com/moby/moby/pull/35008)

### [Swarm mode](#swarm-mode)

* Increase gRPC request timeout when sending snapshots [docker/swarmkit#2404](https://github.com/docker/swarmkit/pull/2404)

- Fix node filtering when there is no log driver [docker/swarmkit#2442](https://github.com/docker/swarmkit/pull/2442)
- Add an error on attempt to change cluster name [docker/swarmkit/#2454](https://github.com/docker/swarmkit/pull/2454)
- Delete node attachments when node is removed [docker/swarmkit/#2456](https://github.com/docker/swarmkit/pull/2456)
- Provide custom gRPC dialer to override default proxy dialer [docker/swarmkit/#2457](https://github.com/docker/swarmkit/pull/2457)
- Avoids recursive readlock on swarm info [moby/moby#35388](https://github.com/moby/moby/pull/35388)

## [17.09.0-ce](#17090-ce)

2017-09-26

### [Builder](#builder-1)

* Add `--chown` flag to `ADD/COPY` commands in Dockerfile [moby/moby#34263](https://github.com/moby/moby/pull/34263)

- Fix cloning unneeded files while building from git repositories [moby/moby#33704](https://github.com/moby/moby/pull/33704)

### [Client](#client-1)

* Allow extension fields in the v3.4 version of the compose format [docker/cli#452](https://github.com/docker/cli/pull/452)
* Make compose file allow to specify names for non-external volume [docker/cli#306](https://github.com/docker/cli/pull/306)
* Support `--compose-file -` as stdin [docker/cli#347](https://github.com/docker/cli/pull/347)
* Support `start_period` for healthcheck in Docker Compose [docker/cli#475](https://github.com/docker/cli/pull/475)

- Add support for `stop-signal` in docker stack commands [docker/cli#388](https://github.com/docker/cli/pull/388)
- Add support for update order in compose deployments [docker/cli#360](https://github.com/docker/cli/pull/360)
- Add ulimits to unsupported compose fields [docker/cli#482](https://github.com/docker/cli/pull/482)
- Add `--format` to `docker-search` [docker/cli#440](https://github.com/docker/cli/pull/440)

* Show images digests when `{{.Digest}}` is in format [docker/cli#439](https://github.com/docker/cli/pull/439)
* Print output of `docker stack rm` on `stdout` instead of `stderr` [docker/cli#491](https://github.com/docker/cli/pull/491)

- Fix `docker history --format {{json .}}` printing human-readable timestamps instead of ISO8601 when `--human=true` [docker/cli#438](https://github.com/docker/cli/pull/438)
- Fix idempotence of `docker stack deploy` when secrets or configs are used [docker/cli#509](https://github.com/docker/cli/pull/509)
- Fix presentation of random host ports [docker/cli#404](https://github.com/docker/cli/pull/404)
- Fix redundant service restarts when service created with multiple secrets [moby/moby#34746](https://github.com/moby/moby/issues/34746)

### [Logging](#logging)

* Fix Splunk logger not transmitting log data when tag is empty and raw-mode is used [moby/moby#34520](https://github.com/moby/moby/pull/34520)

### [Networking](#networking-1)

* Add the control plane MTU option in the daemon config [moby/moby#34103](https://github.com/moby/moby/pull/34103)
* Add service virtual IP to sandbox's loopback address [docker/libnetwork#1877](https://github.com/docker/libnetwork/pull/1877)

### [Runtime](#runtime-1)

* Graphdriver: promote overlay2 over aufs [moby/moby#34430](https://github.com/moby/moby/pull/34430)
* LCOW: Additional flags for VHD boot [moby/moby#34451](https://github.com/moby/moby/pull/34451)
* LCOW: Don't block export [moby/moby#34448](https://github.com/moby/moby/pull/34448)
* LCOW: Dynamic sandbox management [moby/moby#34170](https://github.com/moby/moby/pull/34170)
* LCOW: Force Hyper-V Isolation [moby/moby#34468](https://github.com/moby/moby/pull/34468)
* LCOW: Move toolsScratchPath to /tmp [moby/moby#34396](https://github.com/moby/moby/pull/34396)
* LCOW: Remove hard-coding [moby/moby#34398](https://github.com/moby/moby/pull/34398)
* LCOW: WORKDIR correct handling [moby/moby#34405](https://github.com/moby/moby/pull/34405)
* Windows: named pipe mounts [moby/moby#33852](https://github.com/moby/moby/pull/33852)

- Fix "permission denied" errors when accessing volume with SELinux enforcing mode [moby/moby#34684](https://github.com/moby/moby/pull/34684)
- Fix layers size reported as `0` in `docker system df` [moby/moby#34826](https://github.com/moby/moby/pull/34826)
- Fix some "device or resource busy" errors when removing containers on RHEL 7.4 based kernels [moby/moby#34886](https://github.com/moby/moby/pull/34886)

### [Swarm mode](#swarm-mode-1)

* Include whether the managers in the swarm are autolocked as part of `docker info` [docker/cli#471](https://github.com/docker/cli/pull/471)

- Add 'docker service rollback' subcommand [docker/cli#205](https://github.com/docker/cli/pull/205)

* Fix managers failing to join if the gRPC snapshot is larger than 4MB [docker/swarmkit#2375](https://github.com/docker/swarmkit/pull/2375)
* Fix "permission denied" errors for configuration file in SELinux-enabled containers [moby/moby#34732](https://github.com/moby/moby/pull/34732)
* Fix services failing to deploy on ARM nodes [moby/moby#34021](https://github.com/moby/moby/pull/34021)

### [Packaging](#packaging)

* Build scripts for ppc64el on Ubuntu [docker/docker-ce-packaging#43](https://github.com/docker/docker-ce-packaging/pull/43)

### [Deprecation](#deprecation)

* Remove deprecated `--enable-api-cors` daemon flag [moby/moby#34821](https://github.com/moby/moby/pull/34821)

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/get-started/
----

# Get started with Docker MCP Toolkit

***

Table of contents

***

Availability: Beta

> Note
>
> This page describes the MCP Toolkit interface in Docker Desktop 4.62 and later. Earlier versions have a different UI. Upgrade to follow these instructions exactly.

The Docker MCP Toolkit makes it easy to set up, manage, and run containerized Model Context Protocol (MCP) servers in profiles, and connect them to AI agents. It provides secure defaults and support for a growing ecosystem of LLM-based clients. This page shows you how to get started quickly with the Docker MCP Toolkit.

## [Setup](#setup)

Before you begin, make sure you meet the following requirements to get started with Docker MCP Toolkit.

1. Download and install the latest version of [Docker Desktop](/get-started/get-docker/).
2. Open the Docker Desktop settings and select **Beta features**.
3. Select **Enable Docker MCP Toolkit**.
4. Select **Apply**.

The **Learning center** in Docker Desktop provides walkthroughs and resources to help you get started with Docker products and features. On the **MCP Toolkit** page, the **Get started** walkthrough guides you through installing an MCP server, connecting a client, and testing your setup.

Alternatively, follow the step-by-step instructions on this page:

* [Create a profile](#create-a-profile) - Your workspace for organizing servers
* [Add MCP servers to your profile](#add-mcp-servers) - Select tools from the catalog
* [Connect clients](#connect-clients) - Link AI applications to your profile
* [Verify connections](#verify-connections) - Test that everything works

Once configured, your AI applications can use all the servers in your profile.

> Tip
>
> Prefer working from the terminal? See [Use MCP Toolkit from the CLI](https://docs.docker.com/ai/mcp-catalog-and-toolkit/cli/) for instructions on using the `docker mcp` commands.

## [Create a profile](#create-a-profile)

Profiles organize your MCP servers into collections. Create a profile for your work:

> Note
>
> If you're upgrading from a previous version of MCP Toolkit, your existing server configurations are already in a `default` profile. You can continue using the default profile or create new profiles for different projects.

1. In Docker Desktop, select **MCP Toolkit** and select the **Profiles** tab.
2. Select **Create profile**.
3. Enter a name for your profile (e.g., "Frontend development").
4. Optionally, add servers and clients now, or add them later.
5. Select **Create**.

Your new profile appears in the profiles list.

## [Add MCP servers](#add-mcp-servers)

1. In Docker Desktop, select **MCP Toolkit** and select the **Catalog** tab.
2. Browse the catalog and select the servers you want to add.
3. Select the **Add to** button and choose whether you want to add the servers to an existing profile, or create a new profile.

If a server requires configuration, a **Configuration Required** badge appears next to the server's name. You must complete the mandatory configuration before you can use the server.

You've now successfully added MCP servers to your profile. Next, connect an MCP client to use the servers in your profile.

## [Connect clients](#connect-clients)

To connect a client to MCP Toolkit:

1. In Docker Desktop, select **MCP Toolkit** and select the **Clients** tab.
2. Find your application in the list.
3. Select **Connect** to configure the client.

If your client isn't listed, you can connect the MCP Toolkit manually over `stdio` by configuring your client to run the gateway with your profile:

```plaintext
docker mcp gateway run --profile my_profile
```

For example, if your client uses a JSON file to configure MCP servers, you may add an entry like:

```json
{
  "servers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "my_profile"],
      "type": "stdio"
    }
  }
}
```

Consult the documentation of the application you're using for instructions on how to set up MCP servers manually.

## [Verify connections](#verify-connections)

Refer to the relevant section for instructions on how to verify that your setup is working:

* [Claude Code](#claude-code)
* [Claude Desktop](#claude-desktop)
* [OpenAI Codex](#codex)
* [Continue](#continue)
* [Cursor](#cursor)
* [Gemini](#gemini)
* [Goose](#goose)
* [LM Studio](#lm-studio)
* [OpenCode](#opencode)
* [Sema4.ai](#sema4)
* [Visual Studio Code](#vscode)
* [Zed](#zed)

### [Claude Code](#claude-code)

If you configured the MCP Toolkit for a specific project, navigate to the relevant project directory. Then run `claude mcp list`. The output should show `MCP_DOCKER` with a "connected" status:

```console
$ claude mcp list
Checking MCP server health...

MCP_DOCKER: docker mcp gateway run - ✓ Connected
```

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```console
$ claude "Use the GitHub MCP server to show me my open pull requests"
```

### [Claude Desktop](#claude-desktop)

Restart Claude Desktop and check the **Search and tools** menu in the chat input. You should see the `MCP_DOCKER` server listed and enabled:

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```plaintext
Use the GitHub MCP server to show me my open pull requests
```

### [Codex](#codex)

Run `codex mcp list` to view active MCP servers and their statuses. The `MCP_DOCKER` server should appear in the list with an "enabled" status:

```console
$ codex mcp list
Name        Command  Args             Env  Cwd  Status   Auth
MCP_DOCKER  docker   mcp gateway run  -    -    enabled  Unsupported
```

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```console
$ codex "Use the GitHub MCP server to show me my open pull requests"
```

### [Continue](#continue)

Launch the Continue terminal UI by running `cn`. Use the `/mcp` command to view active MCP servers and their statuses. The `MCP_DOCKER` server should appear in the list with a "connected" status:

```plaintext
   MCP Servers

   ➤ 🟢 MCP_DOCKER (🔧75 📝3)
     🔄 Restart all servers
     ⏹️ Stop all servers
     🔍 Explore MCP Servers
     Back

   ↑/↓ to navigate, Enter to select, Esc to go back
```

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```console
$ cn "Use the GitHub MCP server to show me my open pull requests"
```

### [Cursor](#cursor)

Open Cursor. If you configured the MCP Toolkit for a specific project, open the relevant project directory. Then navigate to **Cursor Settings > Tools & MCP**. You should see `MCP_DOCKER` under **Installed MCP Servers**:

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```plaintext
Use the GitHub MCP server to show me my open pull requests
```

### [Gemini](#gemini)

Run `gemini mcp list` to view active MCP servers and their statuses. The `MCP_DOCKER` should appear in the list with a "connected" status.

```console
$ gemini mcp list
Configured MCP servers:

✓ MCP_DOCKER: docker mcp gateway run (stdio) - Connected
```

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```console
$ gemini "Use the GitHub MCP server to show me my open pull requests"
```

### [Goose](#goose)

Open the Goose desktop application and select **Extensions** in the sidebar. Under **Enabled Extensions**, you should see an extension named `Mcpdocker`:

Run `goose info -v` and look for an entry named `mcpdocker` under extensions. The status should show `enabled: true`:

```console
$ goose info -v
…
    mcpdocker:
      args:
      - mcp
      - gateway
      - run
      available_tools: []
      bundled: null
      cmd: docker
      description: The Docker MCP Toolkit allows for easy configuration and consumption of MCP servers from the Docker MCP Catalog
      enabled: true
      env_keys: []
      envs: {}
      name: mcpdocker
      timeout: 300
      type: stdio
```

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```plaintext
Use the GitHub MCP server to show me my open pull requests
```

### [LM Studio](#lm-studio)

Restart LM Studio and start a new chat. Open the integrations menu and look for an entry named `mcp/mcp-docker`. Use the toggle to enable the server:

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```plaintext
Use the GitHub MCP server to show me my open pull requests
```

### [OpenCode](#opencode)

The OpenCode configuration file (at `~/.config/opencode/opencode.json` by default) contains the setup for MCP Toolkit:

```json
{
  "mcp": {
    "MCP_DOCKER": {
      "type": "local",
      "command": ["docker", "mcp", "gateway", "run"],
      "enabled": true
    }
  },
  "$schema": "https://opencode.ai/config.json"
}
```

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```console
$ opencode "Use the GitHub MCP server to show me my open pull requests"
```

### [Sema4.ai Studio](#sema4)

In Sema4.ai Studio, select **Actions** in the sidebar, then select the **MCP Servers** tab. You should see Docker MCP Toolkit in the list:

To use MCP Toolkit with Sema4.ai, add it as an agent action. Find the agent you want to connect to the MCP Toolkit and open the agent editor. Select **Add Action**, enable Docker MCP Toolkit in the list, then save your agent:

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```plaintext
Use the GitHub MCP server to show me my open pull requests
```

### [Visual Studio Code](#vscode)

Open Visual Studio Code. If you configured the MCP Toolkit for a specific project, open the relevant project directory. Then open the **Extensions** pane. You should see the `MCP_DOCKER` server listed under installed MCP servers.

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```plaintext
Use the GitHub MCP server to show me my open pull requests
```

### [Zed](#zed)

Launch Zed and open agent settings:

Ensure that `MCP_DOCKER` is listed and enabled in the MCP Servers section:

Test the connection by submitting a prompt that invokes one of your installed MCP servers:

```plaintext
Use the GitHub MCP server to show me my open pull requests
```

## [Further reading](#further-reading)

* [MCP Profiles](https://docs.docker.com/ai/mcp-catalog-and-toolkit/profiles/)
* [MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/)
* [MCP Catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/)
* [MCP Gateway](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/)

----
url: https://docs.docker.com/build/cache/backends/gha/
----

# GitHub Actions cache

***

Table of contents

***

Availability: Experimental

The GitHub Actions cache utilizes the [GitHub-provided Action's cache](https://github.com/actions/cache) or other cache services supporting the GitHub Actions cache protocol. This is the recommended cache to use inside your GitHub Actions workflows, as long as your use case falls within the [size and usage limits set by GitHub](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy).

This cache storage backend is not supported with the default `docker` driver. To use this feature, create a new builder using a different driver. See [Build drivers](https://docs.docker.com/build/builders/drivers/) for more information.

## [Synopsis](#synopsis)

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=gha[,parameters...] \
  --cache-from type=gha[,parameters...] .
```

The following table describes the available CSV parameters that you can pass to `--cache-to` and `--cache-from`.

| Name           | Option                  | Type        | Default                                                 | Description                                                                                         |
| -------------- | ----------------------- | ----------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `url`          | `cache-to`,`cache-from` | String      | `$ACTIONS_CACHE_URL` or `$ACTIONS_RESULTS_URL`          | Cache server URL, see [authentication](#authentication). Ignored when `version=2`.                  |
| `url_v2`       | `cache-to`,`cache-from` | String      | `$ACTIONS_RESULTS_URL`                                  | Cache v2 server URL, see [authentication](#authentication).                                         |
| `token`        | `cache-to`,`cache-from` | String      | `$ACTIONS_RUNTIME_TOKEN`                                | Access token, see [authentication](#authentication).                                                |
| `scope`        | `cache-to`,`cache-from` | String      | `buildkit`                                              | Which scope cache object belongs to, see [scope](#scope)                                            |
| `mode`         | `cache-to`              | `min`,`max` | `min`                                                   | Cache layers to export, see [cache mode](https://docs.docker.com/build/cache/backends/#cache-mode). |
| `ignore-error` | `cache-to`              | Boolean     | `false`                                                 | Ignore errors caused by failed cache exports.                                                       |
| `timeout`      | `cache-to`,`cache-from` | String      | `10m`                                                   | Max duration for importing or exporting cache before it's timed out.                                |
| `repository`   | `cache-to`              | String      |                                                         | GitHub repository used for cache storage.                                                           |
| `ghtoken`      | `cache-to`              | String      |                                                         | GitHub token required for accessing the GitHub API.                                                 |
| `version`      | `cache-to`,`cache-from` | String      | `1` unless `$ACTIONS_CACHE_SERVICE_V2` is set, then `2` | Selects GitHub Actions cache version, see [version](#version)                                       |

## [Authentication](#authentication)

If the `url`, `url_v2` or `token` parameters are left unspecified, the `gha` cache backend will fall back to using environment variables. If you invoke the `docker buildx` command manually from an inline step, then the variables must be manually exposed. Consider using the [`crazy-max/ghaction-github-runtime`](https://github.com/crazy-max/ghaction-github-runtime), GitHub Action as a helper for exposing the variables.

## [Scope](#scope)

Scope is a key used to identify the cache object. By default, it is set to `buildkit`. If you build multiple images, each build will overwrite the cache of the previous, leaving only the final cache.

To preserve the cache for multiple builds, you can specify this scope attribute with a specific name. In the following example, the cache is set to the image name, to ensure each image gets its own cache:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=gha,url=...,token=...,scope=image \
  --cache-from type=gha,url=...,token=...,scope=image .
$ docker buildx build --push -t <registry>/<image2> \
  --cache-to type=gha,url=...,token=...,scope=image2 \
  --cache-from type=gha,url=...,token=...,scope=image2 .
```

GitHub's [cache access restrictions](https://docs.github.com/en/actions/advanced-guides/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache), still apply. Only the cache for the current branch, the base branch and the default branch is accessible by a workflow.

## [Version](#version)

If you don’t set `version` explicitly, the default is v1. However, if the environment variable `$ACTIONS_CACHE_SERVICE_V2` is set to a value interpreted as `true` ( `1`, `true`, `yes`), then v2 is used automatically.

Only one URL is relevant at a time:

* With v1, use `url` (defaults to `$ACTIONS_CACHE_URL`).
* With v2, use `url_v2` (defaults to `$ACTIONS_RESULTS_URL`).

### [Using `docker/build-push-action`](#using-dockerbuild-push-action)

When using the [`docker/build-push-action`](https://github.com/docker/build-push-action), the `url` and `token` parameters are automatically populated. No need to manually specify them, or include any additional workarounds.

For example:

```yaml
- name: Build and push
  uses: docker/build-push-action@v7
  with:
    context: .
    push: true
    tags: "<registry>/<image>:latest"
    cache-from: type=gha
    cache-to: type=gha,mode=max
```

## [Avoid GitHub Actions cache API throttling](#avoid-github-actions-cache-api-throttling)

GitHub's [usage limits and eviction policy](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy) causes stale cache entries to be removed after a certain period of time. By default, the `gha` cache backend uses the GitHub Actions cache API to check the status of cache entries.

The GitHub Actions cache API is subject to rate limiting if you make too many requests in a short period of time, which may happen as a result of cache lookups during a build using the `gha` cache backend.

```text
#31 exporting to GitHub Actions Cache
#31 preparing build cache for export
#31 preparing build cache for export 600.3s done
#31 ERROR: maximum timeout reached
------
 > exporting to GitHub Actions Cache:
------
ERROR: failed to solve: maximum timeout reached
make: *** [Makefile:35: release] Error 1
Error: Process completed with exit code 2.
```

To mitigate this issue, you can supply a GitHub token to BuildKit. This lets BuildKit utilize the standard GitHub API for checking cache keys, thereby reducing the number of requests made to the cache API.

To provide a GitHub token, you can use the `ghtoken` parameter, and a `repository` parameter to specify the repository to use for cache storage. The `ghtoken` parameter is a GitHub token with the `repo` scope, which is required to access the GitHub Actions cache API.

The `ghtoken` parameter is automatically set to the value of `secrets.GITHUB_TOKEN` when you build with the `docker/build-push-action` action. You can also set the `ghtoken` parameter manually using the `github-token` input, as shown in the following example:

```yaml
- name: Build and push
  uses: docker/build-push-action@v7
  with:
    context: .
    push: true
    tags: "<registry>/<image>:latest"
    cache-from: type=gha
    cache-to: type=gha,mode=max
    github-token: ${{ secrets.MY_CUSTOM_TOKEN }}
```

## [Further reading](#further-reading)

For an introduction to caching see [Docker build cache](https://docs.docker.com/build/cache/).

For more information on the `gha` cache backend, see the [BuildKit README](https://github.com/moby/buildkit#github-actions-cache-experimental).

For more information about using GitHub Actions with Docker, see [Introduction to GitHub Actions](https://docs.docker.com/build/ci/github-actions/)

----
url: https://docs.docker.com/extensions/extensions-sdk/dev/test-debug/
----

# Test and debug

***

Table of contents

***

In order to improve the developer experience, Docker Desktop provides a set of tools to help you test and debug your extension.

### [Open Chrome DevTools](#open-chrome-devtools)

In order to open the Chrome DevTools for your extension when you select the **Extensions** tab, run:

```console
$ docker extension dev debug <name-of-your-extensions>
```

Each subsequent click on the extension tab also opens Chrome DevTools. To stop this behaviour, run:

```console
$ docker extension dev reset <name-of-your-extensions>
```

After an extension is deployed, it is also possible to open Chrome DevTools from the UI extension part using a variation of the [Konami Code](https://en.wikipedia.org/wiki/Konami_Code). Select the **Extensions** tab, and then hit the key sequence `up, up, down, down, left, right, left, right, p, d, t`.

### [Hot reloading whilst developing the UI](#hot-reloading-whilst-developing-the-ui)

During UI development, it’s helpful to use hot reloading to test your changes without rebuilding your entire extension. To do this, you can configure Docker Desktop to load your UI from a development server, such as the one [Vite](https://vitejs.dev/) starts when invoked with `npm start`.

Assuming your app runs on the default port, start your UI app and then run:

```console
$ cd ui
$ npm run dev
```

This starts a development server that listens on port 3000.

You can now tell Docker Desktop to use this as the frontend source. In another terminal run:

```console
$ docker extension dev ui-source <name-of-your-extensions> http://localhost:3000
```

Close and reopen the Docker Desktop dashboard and go to your extension. All the changes to the frontend code are immediately visible.

Once finished, you can reset the extension configuration to the original settings. This will also reset opening Chrome DevTools if you used `docker extension dev debug <name-of-your-extensions>`:

```console
$ docker extension dev reset <name-of-your-extensions>
```

## [Show the extension containers](#show-the-extension-containers)

If your extension is composed of one or more services running as containers in the Docker Desktop VM, you can access them easily from the dashboard in Docker Desktop.

1. In Docker Desktop, navigate to **Settings**.
2. Under the **Extensions** tab, select the **Show Docker Desktop Extensions system containers** option. You can now view your extension containers and their logs.

## [Clean up](#clean-up)

To remove the extension, run:

```console
$ docker extension rm <name-of-your-extension>
```

## [What's next](#whats-next)

* Build an [advanced frontend](https://docs.docker.com/extensions/extensions-sdk/build/frontend-extension-tutorial/) extension.
* Learn more about extensions [architecture](https://docs.docker.com/extensions/extensions-sdk/architecture/).
* Explore our [design principles](https://docs.docker.com/extensions/extensions-sdk/design/design-principles/).
* Take a look at our [UI styling guidelines](https://docs.docker.com/extensions/extensions-sdk/design/).
* Learn how to [setup CI for your extension](https://docs.docker.com/extensions/extensions-sdk/dev/continuous-integration/).

----
url: https://docs.docker.com/guides/frameworks/laravel/development-setup/
----

# Laravel Development Setup with Docker Compose

***

Table of contents

***

This guide demonstrates how to configure a **development** environment for a Laravel application using Docker and Docker Compose. It builds **on top of** the production image for PHP-FPM and then adds developer-focused features—like Xdebug—to streamline debugging. By basing the development container on a known production image, you keep both environments closely aligned.

This setup includes PHP-FPM, Nginx, and PostgreSQL services (although you can easily swap PostgreSQL for another database, like MySQL or MariaDB). Everything runs in containers, so you can develop in isolation without altering your host system.

> Note
>
> To experiment with a ready-to-run configuration, download the [Laravel Docker Examples](https://github.com/dockersamples/laravel-docker-examples) repository. It contains pre-configured setups for both development and production.

## [Project structure](#project-structure)

```plaintext
my-laravel-app/
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
├── docker/
│   ├── common/
│   │   └── php-fpm/
│   │       └── Dockerfile
│   ├── development/
│   │   ├── php-fpm/
│   │   │   └── entrypoint.sh
│   │   ├── workspace/
│   │   │   └── Dockerfile
│   │   └── nginx
│   │       ├── Dockerfile
│   │       └── nginx.conf
│   └── production/
├── compose.dev.yaml
├── compose.prod.yaml
├── .dockerignore
├── .env
├── vendor/
├── ...
```

This layout represents a typical Laravel project, with Docker configurations stored in a unified `docker` directory. You’ll find **two** Compose files — `compose.dev.yaml` (for development) and `compose.prod.yaml` (for production) — to keep your environments separate and manageable.

The environment includes a `workspace` service, a sidecar container for tasks like building front-end assets, running Artisan commands, and other CLI tools your project may require. While this extra container may seem unusual, it’s a familiar pattern in solutions like **Laravel Sail** and **Laradock**. It also includes **Xdebug** to aid in debugging.

## [Create a Dockerfile for PHP-FPM](#create-a-dockerfile-for-php-fpm)

This Dockerfile **extends** the production image by installing Xdebug and adjusting user permissions to ease local development. That way, your development environment stays consistent with production while still offering extra debug features and improved file mounting.

```dockerfile
# Builds a dev-only layer on top of the production image
FROM production AS development

# Use ARGs to define environment variables passed from the Docker build command or Docker Compose.
ARG XDEBUG_ENABLED=true
ARG XDEBUG_MODE=develop,coverage,debug,profile
ARG XDEBUG_HOST=host.docker.internal
ARG XDEBUG_IDE_KEY=DOCKER
ARG XDEBUG_LOG=/dev/stdout
ARG XDEBUG_LOG_LEVEL=0

USER root

# Configure Xdebug if enabled
RUN if [ "${XDEBUG_ENABLED}" = "true" ]; then \
    pecl install xdebug && \
    docker-php-ext-enable xdebug && \
    echo "xdebug.mode=${XDEBUG_MODE}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.idekey=${XDEBUG_IDE_KEY}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.log=${XDEBUG_LOG}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.log_level=${XDEBUG_LOG_LEVEL}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.client_host=${XDEBUG_HOST}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \
    echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \
fi

# Add ARGs for syncing permissions
ARG UID=1000
ARG GID=1000

# Create a new user with the specified UID and GID, reusing an existing group if GID exists
RUN if getent group ${GID}; then \
      group_name=$(getent group ${GID} | cut -d: -f1); \
      useradd -m -u ${UID} -g ${GID} -s /bin/bash www; \
    else \
      groupadd -g ${GID} www && \
      useradd -m -u ${UID} -g www -s /bin/bash www; \
      group_name=www; \
    fi

# Dynamically update php-fpm to use the new user and group
RUN sed -i "s/user = www-data/user = www/g" /usr/local/etc/php-fpm.d/www.conf && \
    sed -i "s/group = www-data/group = $group_name/g" /usr/local/etc/php-fpm.d/www.conf


# Set the working directory
WORKDIR /var/www

# Copy the entrypoint script
COPY ./docker/development/php-fpm/entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh

# Switch back to the non-privileged user to run the application
USER www-data

# Change the default command to run the entrypoint script
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

# Expose port 9000 and start php-fpm server
EXPOSE 9000
CMD ["php-fpm"]
```

## [Create a Dockerfile for Workspace](#create-a-dockerfile-for-workspace)

A workspace container provides a dedicated shell for asset compilation, Artisan/Composer commands, and other CLI tasks. This approach follows patterns from Laravel Sail and Laradock, consolidating all development tools into one container for convenience.

```dockerfile
# docker/development/workspace/Dockerfile
# Use the official PHP CLI image as the base
FROM php:8.5-cli

# Set environment variables for user and group ID
ARG UID=1000
ARG GID=1000
ARG NODE_VERSION=22.0.0

# Install system dependencies and build libraries
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    unzip \
    libpq-dev \
    libonig-dev \
    libssl-dev \
    libxml2-dev \
    libcurl4-openssl-dev \
    libicu-dev \
    libzip-dev \
    && docker-php-ext-install -j$(nproc) \
    pdo_mysql \
    pdo_pgsql \
    pgsql \
    intl \
    zip \
    bcmath \
    soap \
    && pecl install redis \
    && docker-php-ext-enable redis \
    && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \
    && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

# Use ARG to define environment variables passed from the Docker build command or Docker Compose.
ARG XDEBUG_ENABLED
ARG XDEBUG_MODE
ARG XDEBUG_HOST
ARG XDEBUG_IDE_KEY
ARG XDEBUG_LOG
ARG XDEBUG_LOG_LEVEL

# Configure Xdebug if enabled
RUN if [ "${XDEBUG_ENABLED}" = "true" ]; then \
    pecl install xdebug && \
    docker-php-ext-enable xdebug && \
    echo "xdebug.mode=${XDEBUG_MODE}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.idekey=${XDEBUG_IDE_KEY}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.log=${XDEBUG_LOG}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.log_level=${XDEBUG_LOG_LEVEL}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.client_host=${XDEBUG_HOST}" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \
    echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini ; \
fi

# If the group already exists, use it; otherwise, create the 'www' group
RUN if getent group ${GID}; then \
      useradd -m -u ${UID} -g ${GID} -s /bin/bash www; \
    else \
      groupadd -g ${GID} www && \
      useradd -m -u ${UID} -g www -s /bin/bash www; \
    fi && \
    usermod -aG sudo www && \
    echo 'www ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers

# Switch to the non-root user to install NVM and Node.js
USER www

# Install NVM (Node Version Manager) as the www user
RUN export NVM_DIR="$HOME/.nvm" && \
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash && \
    [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" && \
    nvm install ${NODE_VERSION} && \
    nvm alias default ${NODE_VERSION} && \
    nvm use default

# Ensure NVM is available for all future shells
RUN echo 'export NVM_DIR="$HOME/.nvm"' >> /home/www/.bashrc && \
    echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> /home/www/.bashrc && \
    echo '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"' >> /home/www/.bashrc

# Set the working directory
WORKDIR /var/www

# Override the entrypoint to avoid the default php entrypoint
ENTRYPOINT []

# Default command to keep the container running
CMD ["bash"]
```

> Note
>
> If you prefer a **one-service-per-container** approach, simply omit the workspace container and run separate containers for each task. For example, you could use a dedicated `php-cli` container for your PHP scripts, and a `node` container to handle the asset building.

## [Create a Docker Compose configuration for development](#create-a-docker-compose-configuration-for-development)

Here's the `compose.yaml` file to set up the development environment:

```yaml
services:
  web:
    image: nginx:latest # Using the default Nginx image with custom configuration.
    volumes:
      # Mount the application code for live updates
      - ./:/var/www
      # Mount the Nginx configuration file
      - ./docker/development/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      # Map port 80 inside the container to the port specified by 'NGINX_PORT' on the host machine
      - "80:80"
    environment:
      - NGINX_HOST=localhost
    networks:
      - laravel-development
    depends_on:
      php-fpm:
        condition: service_started # Wait for php-fpm to start

  php-fpm:
    # For the php-fpm service, we will use our common PHP-FPM Dockerfile with the development target
    build:
      context: .
      dockerfile: ./docker/common/php-fpm/Dockerfile
      target: development
      args:
        UID: ${UID:-1000}
        GID: ${GID:-1000}
        XDEBUG_ENABLED: ${XDEBUG_ENABLED:-true}
        XDEBUG_MODE: develop,coverage,debug,profile
        XDEBUG_HOST: ${XDEBUG_HOST:-host.docker.internal}
        XDEBUG_IDE_KEY: ${XDEBUG_IDE_KEY:-DOCKER}
        XDEBUG_LOG: /dev/stdout
        XDEBUG_LOG_LEVEL: 0
    env_file:
      # Load the environment variables from the Laravel application
      - .env
    user: "${UID:-1000}:${GID:-1000}"
    volumes:
      # Mount the application code for live updates
      - ./:/var/www
    networks:
      - laravel-development
    depends_on:
      postgres:
        condition: service_started # Wait for postgres to start

  workspace:
    # For the workspace service, we will also create a custom image to install and setup all the necessary stuff.
    build:
      context: .
      dockerfile: ./docker/development/workspace/Dockerfile
      args:
        UID: ${UID:-1000}
        GID: ${GID:-1000}
        XDEBUG_ENABLED: ${XDEBUG_ENABLED:-true}
        XDEBUG_MODE: develop,coverage,debug,profile
        XDEBUG_HOST: ${XDEBUG_HOST:-host.docker.internal}
        XDEBUG_IDE_KEY: ${XDEBUG_IDE_KEY:-DOCKER}
        XDEBUG_LOG: /dev/stdout
        XDEBUG_LOG_LEVEL: 0
    tty: true # Enables an interactive terminal
    stdin_open: true # Keeps standard input open for 'docker exec'
    env_file:
      - .env
    volumes:
      - ./:/var/www
    networks:
      - laravel-development

  postgres:
    image: postgres:18
    ports:
      - "${POSTGRES_PORT:-5432}:5432"
    environment:
      - POSTGRES_DB=app
      - POSTGRES_USER=laravel
      - POSTGRES_PASSWORD=secret
    volumes:
      - postgres-data-development:/var/lib/postgresql
    networks:
      - laravel-development

  redis:
    image: redis:alpine
    networks:
      - laravel-development

networks:
  laravel-development:

volumes:
  postgres-data-development:
```

> Note
>
> Ensure you have an `.env` file at the root of your Laravel project with the necessary configurations. You can use the `.env.example` file as a template.

## [Run your development environment](#run-your-development-environment)

To start the development environment, use:

```console
$ docker compose -f compose.dev.yaml up --build -d
```

Run this command to build and start the development environment in detached mode. When the containers finish initializing, visit <http://localhost/> to see your Laravel app in action.

## [Summary](#summary)

By building on top of the production image and adding debug tools like Xdebug, you create a Laravel development workflow that closely mirrors production. The optional workspace container simplifies tasks like asset building and running Artisan commands. If you prefer a separate container for every service (e.g., a dedicated `php-cli` and `node` container), you can skip the workspace approach. Either way, Docker Compose provides an efficient, consistent way to develop your Laravel project.

[Common Questions on Using Laravel with Docker »](https://docs.docker.com/guides/frameworks/laravel/common-questions/)

----
url: https://docs.docker.com/guides/testcontainers-java-aws-localstack/
----

# Testing AWS service integrations using LocalStack

Table of contents

***

Learn how to create a Spring Boot application with Spring Cloud AWS, then test S3 and SQS integrations using Testcontainers and LocalStack.

**Time to complete** 25 minutes

In this guide, you will learn how to:

* Create a Spring Boot application with Spring Cloud AWS integration
* Use AWS S3 and SQS services
* Test the application using Testcontainers and LocalStack

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-aws-localstack/create-project/)

   Set up a Spring Boot project with Spring Cloud AWS, S3, and SQS.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-aws-localstack/write-tests/)

   Test Spring Cloud AWS S3 and SQS integration using Testcontainers and LocalStack.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-aws-localstack/run-tests/)

   Run your Testcontainers-based Spring Cloud AWS integration tests and explore next steps.

----
url: https://docs.docker.com/scout/integrations/source-code-management/github/
----

# Integrate Docker Scout with GitHub

***

Table of contents

***

Availability: Beta

The GitHub app integration for Docker Scout grants Docker Scout access to your source code repository on GitHub. This improved visibility into how your image gets created means Docker Scout can give you automated and contextual remediation advice.

## [How it works](#how-it-works)

When you enable the GitHub integration, Docker Scout can make a direct link between the image analysis results and the source.

When analyzing your image, Docker Scout checks for [provenance attestations](https://docs.docker.com/build/metadata/attestations/slsa-provenance/) to detect the location of the source code repository for the image. If the source location is found, and you've enabled the GitHub app, Docker Scout parses the Dockerfile used to create the image.

Parsing the Dockerfile reveals the base image tag used to build the image. By knowing the base image tags used, Docker Scout can detect whether the tag is outdated, meaning it's been changed to a different image digest. For example, say you're using `alpine:3.18` as your base image, and at a later point in time, the image maintainers release a patch version for version `3.18`, containing security fixes. The `alpine:3.18` tag you've been using becomes out-of-date; the `alpine:3.18` you're using is no longer the latest.

When this happens, Docker Scout detects the discrepancy and surfaces it through the [Up-to-Date Base Images policy](https://docs.docker.com/scout/policy/#up-to-date-base-images-policy). When the GitHub integration's enabled, you'll also get automated suggestions on how to update your base image. For more information about how Docker Scout can help you automatically improve your supply chain conduct and security posture, see [Remediation](https://docs.docker.com/scout/policy/remediation/).

## [Setup](#setup)

To integrate Docker Scout with your GitHub organization:

1. Go to [GitHub integration](https://scout.docker.com/settings/integrations/github/) on the Docker Scout Dashboard.

2. Select the **Integrate GitHub app** button to open GitHub.

3. Select the organization that you want to integrate.

4. Select whether you want to integrate all repositories in the GitHub organization or a manual selection of repositories.

5. Select **Install & Authorize** to add the Docker Scout app to the organization.

   This redirects you back to the Docker Scout Dashboard, which lists your active GitHub integrations.

The GitHub integration is now active.

----
url: https://docs.docker.com/reference/cli/docker/mcp/tools/count/
----

# docker mcp tools count

***

| Description | Count tools              |
| ----------- | ------------------------ |
| Usage       | `docker mcp tools count` |

## [Description](#description)

Count tools

----
url: https://docs.docker.com/reference/cli/docker/mcp/server/init/
----

# docker mcp server init

***

| Description | Initialize a new MCP server project  |
| ----------- | ------------------------------------ |
| Usage       | `docker mcp server init <directory>` |

## [Description](#description)

Initialize a new MCP server project in the specified directory with boilerplate code, Dockerfile, and compose.yaml

## [Options](#options)

| Option       | Default | Description                                                             |
| ------------ | ------- | ----------------------------------------------------------------------- |
| `--language` | `go`    | Programming language for the server (currently only 'go' is supported)  |
| `--template` | `basic` | Template to use (basic, chatgpt-app-basic)                              |

----
url: https://docs.docker.com/reference/cli/docker/scout/sbom/
----

# docker scout sbom

***

| Description | Generate or display SBOM of an image            |
| ----------- | ----------------------------------------------- |
| Usage       | `docker scout sbom [IMAGE\|DIRECTORY\|ARCHIVE]` |

## [Description](#description)

The `docker scout sbom` command analyzes a software artifact to generate a Software Bill Of Materials (SBOM).

The SBOM contains a list of all packages in the image. You can use the `--format` flag to filter the output of the command to display only packages of a specific type.

| Option                | Default | Description                                                                                                                                                                             |
| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--format`            | `json`  | Output format: - list: list of packages of the image - json: json representation of the SBOM - spdx: spdx representation of the SBOM - cyclonedx: cyclone dx representation of the SBOM |
| `--only-package-type` |         | Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc) Can only be used with --format list                                                                  |
| `-o, --output`        |         | Write the report to a file                                                                                                                                                              |
| `--platform`          |         | Platform of image to analyze                                                                                                                                                            |
| `--ref`               |         | Reference to use if the provided tarball contains multiple references. Can only be used with archive                                                                                    |

## [Examples](#examples)

### [Display the list of packages](#display-the-list-of-packages)

```console
$ docker scout sbom --format list alpine
```

### [Only display packages of a specific type](#only-display-packages-of-a-specific-type)

```console
 $ docker scout sbom --format list --only-package-type apk alpine
```

### [Display the full SBOM in JSON format](#display-the-full-sbom-in-json-format)

```console
$ docker scout sbom alpine
```

### [Display the full SBOM of the most recently built image](#display-the-full-sbom-of-the-most-recently-built-image)

```console
$ docker scout sbom
```

### [Write SBOM to a file](#write-sbom-to-a-file)

```console
$ docker scout sbom --output alpine.sbom alpine
```

----
url: https://docs.docker.com/guides/testcontainers-java-service-configuration/copy-files/
----

# Copy files into containers

***

Table of contents

***

Sometimes you need to initialize a container by placing files in a specific location. For example, PostgreSQL runs SQL scripts from `/docker-entrypoint-initdb.d/` when the container starts.

## [Create the initialization script](#create-the-initialization-script)

Create `src/test/resources/init-db.sql`:

```sql
create table customers (
     id bigint not null,
     name varchar not null,
     primary key (id)
);
```

## [Copy the file into the container](#copy-the-file-into-the-container)

Use `withCopyFileToContainer()` to copy the SQL script into the container's init directory:

```java
package com.testcontainers.demo;

import static org.junit.jupiter.api.Assertions.assertFalse;

import java.util.List;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.testcontainers.postgresql.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.utility.MountableFile;

@Testcontainers
class CustomerServiceTest {

  @Container
  static PostgreSQLContainer postgres = new PostgreSQLContainer(
    "postgres:16-alpine"
  )
    .withCopyFileToContainer(
      MountableFile.forClasspathResource("init-db.sql"),
      "/docker-entrypoint-initdb.d/"
    );

  CustomerService customerService;

  @BeforeEach
  void setUp() {
    customerService =
    new CustomerService(
      postgres.getJdbcUrl(),
      postgres.getUsername(),
      postgres.getPassword()
    );
  }

  @Test
  void shouldGetCustomers() {
    customerService.createCustomer(new Customer(1L, "George"));
    customerService.createCustomer(new Customer(2L, "John"));

    List<Customer> customers = customerService.getAllCustomers();
    assertFalse(customers.isEmpty());
  }
}
```

The `withCopyFileToContainer(MountableFile, String)` method copies `init-db.sql` from the classpath into `/docker-entrypoint-initdb.d/` inside the container. PostgreSQL executes scripts in that directory automatically at startup.

You can also copy files from any path on the host:

```java
.withCopyFileToContainer(
    MountableFile.forHostPath("/host/path/to/init-db.sql"),
    "/docker-entrypoint-initdb.d/"
);
```

[Execute commands inside containers »](https://docs.docker.com/guides/testcontainers-java-service-configuration/exec-in-container/)

----
url: https://docs.docker.com/engine/release-notes/17.05/
----

# Docker Engine 17.05 release notes

***

Table of contents

***

## [17.05.0-ce](#17050-ce)

2017-05-04

### [Builder](#builder)

* Add multi-stage build support [#31257](https://github.com/docker/docker/pull/31257) [#32063](https://github.com/docker/docker/pull/32063)
* Allow using build-time args (`ARG`) in `FROM` [#31352](https://github.com/docker/docker/pull/31352)
* Add an option for specifying build target [#32496](https://github.com/docker/docker/pull/32496)

- Accept `-f -` to read Dockerfile from `stdin`, but use local context for building [#31236](https://github.com/docker/docker/pull/31236)
- The values of default build time arguments (e.g `HTTP_PROXY`) are no longer displayed in docker image history unless a corresponding `ARG` instruction is written in the Dockerfile. [#31584](https://github.com/docker/docker/pull/31584)

* Fix setting command if a custom shell is used in a parent image [#32236](https://github.com/docker/docker/pull/32236)
* Fix `docker build --label` when the label includes single quotes and a space [#31750](https://github.com/docker/docker/pull/31750)

### [Client](#client)

* Add `--mount` flag to `docker run` and `docker create` [#32251](https://github.com/docker/docker/pull/32251)
* Add `--type=secret` to `docker inspect` [#32124](https://github.com/docker/docker/pull/32124)
* Add `--format` option to `docker secret ls` [#31552](https://github.com/docker/docker/pull/31552)
* Add `--filter` option to `docker secret ls` [#30810](https://github.com/docker/docker/pull/30810)
* Add `--filter scope=<swarm|local>` to `docker network ls` [#31529](https://github.com/docker/docker/pull/31529)
* Add `--cpus` support to `docker update` [#31148](https://github.com/docker/docker/pull/31148)
* Add label filter to `docker system prune` and other `prune` commands [#30740](https://github.com/docker/docker/pull/30740)
* `docker stack rm` now accepts multiple stacks as input [#32110](https://github.com/docker/docker/pull/32110)
* Improve `docker version --format` option when the client has downgraded the API version [#31022](https://github.com/docker/docker/pull/31022)
* Prompt when using an encrypted client certificate to connect to a docker daemon [#31364](https://github.com/docker/docker/pull/31364)
* Display created tags on successful `docker build` [#32077](https://github.com/docker/docker/pull/32077)
* Cleanup compose convert error messages [#32087](https://github.com/moby/moby/pull/32087)

### [Contrib](#contrib)

* Add support for building docker debs for Ubuntu 17.04 Zesty on amd64 [#32435](https://github.com/docker/docker/pull/32435)

### [Daemon](#daemon)

* Fix `--api-cors-header` being ignored if `--api-enable-cors` is not set [#32174](https://github.com/docker/docker/pull/32174)
* Cleanup docker tmp dir on start [#31741](https://github.com/docker/docker/pull/31741)
* Deprecate `--graph` flag in favor or `--data-root` [#28696](https://github.com/docker/docker/pull/28696)

### [Logging](#logging)

* Add support for logging driver plugins [#28403](https://github.com/docker/docker/pull/28403)

- Add support for showing logs of individual tasks to `docker service logs`, and add `/task/{id}/logs` REST endpoint [#32015](https://github.com/docker/docker/pull/32015)
- Add `--log-opt env-regex` option to match environment variables using a regular expression [#27565](https://github.com/docker/docker/pull/27565)

### [Networking](#networking)

* Allow user to replace, and customize the ingress network [#31714](https://github.com/docker/docker/pull/31714)

- Fix UDP traffic in containers not working after the container is restarted [#32505](https://github.com/docker/docker/pull/32505)
- Fix files being written to `/var/lib/docker` if a different data-root is set [#32505](https://github.com/docker/docker/pull/32505)

### [Runtime](#runtime)

* Ensure health probe is stopped when a container exits [#32274](https://github.com/docker/docker/pull/32274)

### [Swarm Mode](#swarm-mode)

* Add update/rollback order for services (`--update-order` / `--rollback-order`) [#30261](https://github.com/docker/docker/pull/30261)
* Add support for synchronous `service create` and `service update` [#31144](https://github.com/docker/docker/pull/31144)
* Add support for "grace periods" on healthchecks through the `HEALTHCHECK --start-period` and `--health-start-period` flag to `docker service create`, `docker service update`, `docker create`, and `docker run` to support containers with an initial startup time [#28938](https://github.com/docker/docker/pull/28938)

- `docker service create` now omits fields that are not specified by the user, when possible. This will allow defaults to be applied inside the manager [#32284](https://github.com/docker/docker/pull/32284)
- `docker service inspect` now shows default values for fields that are not specified by the user [#32284](https://github.com/docker/docker/pull/32284)
- Move `docker service logs` out of experimental [#32462](https://github.com/docker/docker/pull/32462)
- Add support for Credential Spec and SELinux to services to the API [#32339](https://github.com/docker/docker/pull/32339)
- Add `--entrypoint` flag to `docker service create` and `docker service update` [#29228](https://github.com/docker/docker/pull/29228)
- Add `--network-add` and `--network-rm` to `docker service update` [#32062](https://github.com/docker/docker/pull/32062)
- Add `--credential-spec` flag to `docker service create` and `docker service update` [#32339](https://github.com/docker/docker/pull/32339)
- Add `--filter mode=<global|replicated>` to `docker service ls` [#31538](https://github.com/docker/docker/pull/31538)
- Resolve network IDs on the client side, instead of in the daemon when creating services [#32062](https://github.com/docker/docker/pull/32062)
- Add `--format` option to `docker node ls` [#30424](https://github.com/docker/docker/pull/30424)
- Add `--prune` option to `docker stack deploy` to remove services that are no longer defined in the docker-compose file [#31302](https://github.com/docker/docker/pull/31302)
- Add `PORTS` column for `docker service ls` when using `ingress` mode [#30813](https://github.com/docker/docker/pull/30813)

* Fix unnecessary re-deploying of tasks when environment-variables are used [#32364](https://github.com/docker/docker/pull/32364)
* Fix `docker stack deploy` not supporting `endpoint_mode` when deploying from a docker compose file [#32333](https://github.com/docker/docker/pull/32333)
* Proceed with startup if cluster component cannot be created to allow recovering from a broken swarm setup [#31631](https://github.com/docker/docker/pull/31631)

### [Security](#security)

* Allow setting SELinux type or MCS labels when using `--ipc=container:` or `--ipc=host` [#30652](https://github.com/docker/docker/pull/30652)

### [Deprecation](#deprecation)

* Deprecate `--api-enable-cors` daemon flag. This flag was marked deprecated in Docker 1.6.0 but not listed in deprecated features [#32352](https://github.com/docker/docker/pull/32352)
* Remove Ubuntu 12.04 (Precise Pangolin) as supported platform. Ubuntu 12.04 is EOL, and no longer receives updates [#32520](https://github.com/docker/docker/pull/32520)

----
url: https://docs.docker.com/guides/testcontainers-java-wiremock/write-tests/
----

# Write tests with WireMock and Testcontainers

***

Table of contents

***

Mocking external API interactions at the HTTP protocol level, rather than mocking Java methods, lets you verify marshalling and unmarshalling behavior and simulate network issues.

## [Test using WireMock JUnit 5 extension](#test-using-wiremock-junit-5-extension)

WireMock provides a JUnit 5 extension that starts an in-process WireMock server. You can configure stub responses using the WireMock Java API.

Create `AlbumControllerTest.java`:

```java
package com.testcontainers.demo;

import static com.github.tomakehurst.wiremock.client.WireMock.aResponse;
import static com.github.tomakehurst.wiremock.client.WireMock.urlMatching;
import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;
import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.hasSize;
import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT;

import com.github.tomakehurst.wiremock.client.WireMock;
import com.github.tomakehurst.wiremock.junit5.WireMockExtension;
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.RegisterExtension;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.server.LocalServerPort;
import org.springframework.http.MediaType;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;

@SpringBootTest(webEnvironment = RANDOM_PORT)
class AlbumControllerTest {

  @LocalServerPort
  private Integer port;

  @RegisterExtension
  static WireMockExtension wireMock = WireMockExtension
    .newInstance()
    .options(wireMockConfig().dynamicPort())
    .build();

  @DynamicPropertySource
  static void configureProperties(DynamicPropertyRegistry registry) {
    registry.add("photos.api.base-url", wireMock::baseUrl);
  }

  @BeforeEach
  void setUp() {
    RestAssured.port = port;
  }

  @Test
  void shouldGetAlbumById() {
    Long albumId = 1L;

    wireMock.stubFor(
      WireMock
        .get(urlMatching("/albums/" + albumId + "/photos"))
        .willReturn(
          aResponse()
            .withHeader("Content-Type", MediaType.APPLICATION_JSON_VALUE)
            .withBody(
              """
              [
                   {
                       "id": 1,
                       "title": "accusamus beatae ad facilis cum similique qui sunt",
                       "url": "https://via.placeholder.com/600/92c952",
                       "thumbnailUrl": "https://via.placeholder.com/150/92c952"
                   },
                   {
                       "id": 2,
                       "title": "reprehenderit est deserunt velit ipsam",
                       "url": "https://via.placeholder.com/600/771796",
                       "thumbnailUrl": "https://via.placeholder.com/150/771796"
                   }
               ]
              """
            )
        )
    );

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/albums/{albumId}", albumId)
      .then()
      .statusCode(200)
      .body("albumId", is(albumId.intValue()))
      .body("photos", hasSize(2));
  }

  @Test
  void shouldReturnServerErrorWhenPhotoServiceCallFailed() {
    Long albumId = 2L;
    wireMock.stubFor(
      WireMock
        .get(urlMatching("/albums/" + albumId + "/photos"))
        .willReturn(aResponse().withStatus(500))
    );

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/albums/{albumId}", albumId)
      .then()
      .statusCode(500);
  }
}
```

Here's what the test does:

* `@SpringBootTest` starts the full application on a random port.
* `@RegisterExtension` creates a `WireMockExtension` that starts WireMock on a dynamic port.
* `@DynamicPropertySource` overrides `photos.api.base-url` to point at the WireMock endpoint, so the application talks to WireMock instead of the real photo service.
* `shouldGetAlbumById()` configures a stub response for `/albums/{albumId}/photos`, sends a request to the application's `/api/albums/{albumId}` endpoint, and verifies the response body.
* `shouldReturnServerErrorWhenPhotoServiceCallFailed()` configures WireMock to return a 500 status and verifies that the application propagates that status to the caller.

## [Stub using JSON mapping files](#stub-using-json-mapping-files)

Instead of using the WireMock Java API, you can configure stubs with JSON mapping files. Create `src/test/resources/wiremock/mappings/get-album-photos.json`:

```json
{
  "mappings": [
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/([0-9]+)/photos"
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": "application/json"
        },
        "bodyFileName": "album-photos-resp-200.json"
      }
    },
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/2/photos"
      },
      "response": {
        "status": 500,
        "headers": {
          "Content-Type": "application/json"
        }
      }
    },
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/3/photos"
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": "application/json"
        },
        "jsonBody": []
      }
    }
  ]
}
```

Create the response body file at `src/test/resources/wiremock/__files/album-photos-resp-200.json`:

```json
[
  {
    "id": 1,
    "title": "accusamus beatae ad facilis cum similique qui sunt",
    "url": "https://via.placeholder.com/600/92c952",
    "thumbnailUrl": "https://via.placeholder.com/150/92c952"
  },
  {
    "id": 2,
    "title": "reprehenderit est deserunt velit ipsam",
    "url": "https://via.placeholder.com/600/771796",
    "thumbnailUrl": "https://via.placeholder.com/150/771796"
  }
]
```

Initialize WireMock to load stubs from the mapping files:

```java
@RegisterExtension
static WireMockExtension wireMockServer = WireMockExtension
  .newInstance()
  .options(
    wireMockConfig().dynamicPort().usingFilesUnderClasspath("wiremock")
  )
  .build();
```

With mapping-based stubs in place, create `AlbumControllerWireMockMappingTests.java`:

```java
package com.testcontainers.demo;

import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;
import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.hasSize;
import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT;

import com.github.tomakehurst.wiremock.junit5.WireMockExtension;
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.RegisterExtension;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.server.LocalServerPort;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;

@SpringBootTest(webEnvironment = RANDOM_PORT)
class AlbumControllerWireMockMappingTests {

  @LocalServerPort
  private Integer port;

  @RegisterExtension
  static WireMockExtension wireMockServer = WireMockExtension
    .newInstance()
    .options(
      wireMockConfig().dynamicPort().usingFilesUnderClasspath("wiremock")
    )
    .build();

  @DynamicPropertySource
  static void configureProperties(DynamicPropertyRegistry registry) {
    registry.add("photos.api.base-url", wireMockServer::baseUrl);
  }

  @BeforeEach
  void setUp() {
    RestAssured.port = port;
  }

  @Test
  void shouldGetAlbumById() {
    Long albumId = 1L;

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/albums/{albumId}", albumId)
      .then()
      .statusCode(200)
      .body("albumId", is(albumId.intValue()))
      .body("photos", hasSize(2));
  }

  @Test
  void shouldReturnServerErrorWhenPhotoServiceCallFailed() {
    Long albumId = 2L;

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/albums/{albumId}", albumId)
      .then()
      .statusCode(500);
  }

  @Test
  void shouldReturnEmptyPhotos() {
    Long albumId = 3L;

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/albums/{albumId}", albumId)
      .then()
      .statusCode(200)
      .body("albumId", is(albumId.intValue()))
      .body("photos", hasSize(0));
  }
}
```

The tests don't need inline stub definitions because WireMock loads the mappings automatically from the classpath.

## [Test using the Testcontainers WireMock module](#test-using-the-testcontainers-wiremock-module)

The [Testcontainers WireMock module](https://testcontainers.com/modules/wiremock/) provisions WireMock as a standalone Docker container, based on [WireMock Docker](https://github.com/wiremock/wiremock-docker). This approach is useful when you want complete isolation between the test JVM and the mock server.

Create a mock configuration file at `src/test/resources/com/testcontainers/demo/AlbumControllerTestcontainersTests/mocks-config.json`:

```json
{
  "mappings": [
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/([0-9]+)/photos"
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": "application/json"
        },
        "bodyFileName": "album-photos-response.json"
      }
    },
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/2/photos"
      },
      "response": {
        "status": 500,
        "headers": {
          "Content-Type": "application/json"
        }
      }
    },
    {
      "request": {
        "method": "GET",
        "urlPattern": "/albums/3/photos"
      },
      "response": {
        "status": 200,
        "headers": {
          "Content-Type": "application/json"
        },
        "jsonBody": []
      }
    }
  ]
}
```

Create the response body file at `src/test/resources/com/testcontainers/demo/AlbumControllerTestcontainersTests/album-photos-response.json`:

```json
[
  {
    "id": 1,
    "title": "accusamus beatae ad facilis cum similique qui sunt",
    "url": "https://via.placeholder.com/600/92c952",
    "thumbnailUrl": "https://via.placeholder.com/150/92c952"
  },
  {
    "id": 2,
    "title": "reprehenderit est deserunt velit ipsam",
    "url": "https://via.placeholder.com/600/771796",
    "thumbnailUrl": "https://via.placeholder.com/150/771796"
  }
]
```

Create `AlbumControllerTestcontainersTests.java`:

```java
package com.testcontainers.demo;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.hasSize;
import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT;

import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.server.LocalServerPort;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.wiremock.integrations.testcontainers.WireMockContainer;

@SpringBootTest(webEnvironment = RANDOM_PORT)
@Testcontainers
class AlbumControllerTestcontainersTests {

  @LocalServerPort
  private Integer port;

  @Container
  static WireMockContainer wiremockServer = new WireMockContainer(
    "wiremock/wiremock:3.6.0"
  )
    .withMapping(
      "photos-by-album",
      AlbumControllerTestcontainersTests.class,
      "mocks-config.json"
    )
    .withFileFromResource(
      "album-photos-response.json",
      AlbumControllerTestcontainersTests.class,
      "album-photos-response.json"
    );

  @DynamicPropertySource
  static void configureProperties(DynamicPropertyRegistry registry) {
    registry.add("photos.api.base-url", wiremockServer::getBaseUrl);
  }

  @BeforeEach
  void setUp() {
    RestAssured.port = port;
  }

  @Test
  void shouldGetAlbumById() {
    Long albumId = 1L;

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/albums/{albumId}", albumId)
      .then()
      .statusCode(200)
      .body("albumId", is(albumId.intValue()))
      .body("photos", hasSize(2));
  }

  @Test
  void shouldReturnServerErrorWhenPhotoServiceCallFailed() {
    Long albumId = 2L;

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/albums/{albumId}", albumId)
      .then()
      .statusCode(500);
  }

  @Test
  void shouldReturnEmptyPhotos() {
    Long albumId = 3L;

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/albums/{albumId}", albumId)
      .then()
      .statusCode(200)
      .body("albumId", is(albumId.intValue()))
      .body("photos", hasSize(0));
  }
}
```

Here's what the test does:

* The `@Testcontainers` and `@Container` annotations start a `WireMockContainer` using the `wiremock/wiremock:3.6.0` Docker image.
* `withMapping()` loads stub mappings from `mocks-config.json`, and `withFileFromResource()` loads the response body file.
* `@DynamicPropertySource` overrides `photos.api.base-url` to point at the WireMock container's base URL.
* The tests don't contain inline stub definitions because WireMock loads them from the JSON configuration files.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-wiremock/run-tests/)

----
url: https://docs.docker.com/build/building/export/
----

# Export binaries

***

Table of contents

***

Did you know that you can use Docker to build your application to standalone binaries? Sometimes, you don’t want to package and distribute your application as a Docker image. Use Docker to build your application, and use exporters to save the output to disk.

The default output format for `docker build` is a container image. That image is automatically loaded to your local image store, where you can run a container from that image, or push it to a registry. Under the hood, this uses the default exporter, called the `docker` exporter.

To export your build results as files instead, you can use the `--output` flag, or `-o` for short. The `--output` flag lets you change the output format of your build.

## [Export binaries from a build](#export-binaries-from-a-build)

If you specify a filepath to the `docker build --output` flag, Docker exports the contents of the build container at the end of the build to the specified location on your host's filesystem. This uses the `local` [exporter](https://docs.docker.com/build/exporters/local-tar/).

The neat thing about this is that you can use Docker's powerful isolation and build features to create standalone binaries. This works well for Go, Rust, and other languages that can compile to a single binary.

The following example creates a simple Rust program that prints "Hello, World!", and exports the binary to the host filesystem.

1. Create a new directory for this example, and navigate to it:

   ```console
   $ mkdir hello-world-bin
   $ cd hello-world-bin
   ```

2. Create a Dockerfile with the following contents:

   ```Dockerfile
   # syntax=docker/dockerfile:1
   FROM rust:alpine AS build
   WORKDIR /src
   COPY <<EOT hello.rs
   fn main() {
       println!("Hello World!");
   }
   EOT
   RUN rustc -o /bin/hello hello.rs

   FROM scratch
   COPY --from=build /bin/hello /
   ENTRYPOINT ["/hello"]
   ```

   > Tip
   >
   > The `COPY <<EOT` syntax is a [here-document](https://docs.docker.com/reference/dockerfile/#here-documents). It lets you write multi-line strings in a Dockerfile. Here it's used to create a simple Rust program inline in the Dockerfile.

   This Dockerfile uses a multi-stage build to compile the program in the first stage, and then copies the binary to a scratch image in the second. The final image is a minimal image that only contains the binary. This use case for the `scratch` image is common for creating minimal build artifacts for programs that don't require a full operating system to run.

3. Build the Dockerfile and export the binary to the current working directory:

   ```console
   $ docker build --output=. .
   ```

   This command builds the Dockerfile and exports the binary to the current working directory. The binary is named `hello`, and it's created in the current working directory.

## [Exporting multi-platform builds](#exporting-multi-platform-builds)

You use the `local` exporter to export binaries in combination with [multi-platform builds](https://docs.docker.com/build/building/multi-platform/). This lets you compile multiple binaries at once, that can be run on any machine of any architecture, provided that the target platform is supported by the compiler you use.

Continuing on the example Dockerfile in the [Export binaries from a build](#export-binaries-from-a-build) section:

```dockerfile
# syntax=docker/dockerfile:1
FROM rust:alpine AS build
WORKDIR /src
COPY <<EOT hello.rs
fn main() {
    println!("Hello World!");
}
EOT
RUN rustc -o /bin/hello hello.rs

FROM scratch
COPY --from=build /bin/hello /
ENTRYPOINT ["/hello"]
```

You can build this Rust program for multiple platforms using the `--platform` flag with the `docker build` command. In combination with the `--output` flag, the build exports the binaries for each target to the specified directory.

For example, to build the program for both `linux/amd64` and `linux/arm64`:

```console
$ docker build --platform=linux/amd64,linux/arm64 --output=out .
$ tree out/
out/
├── linux_amd64
│   └── hello
└── linux_arm64
    └── hello

3 directories, 2 files
```

## [Additional information](#additional-information)

In addition to the `local` exporter, there are other exporters available. To learn more about the available exporters and how to use them, see the [exporters](https://docs.docker.com/build/exporters/) documentation.

----
url: https://docs.docker.com/reference/cli/docker/manifest/inspect/
----

# docker manifest inspect

***

| Description | Display an image manifest, or manifest list                  |
| ----------- | ------------------------------------------------------------ |
| Usage       | `docker manifest inspect [OPTIONS] [MANIFEST_LIST] MANIFEST` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Display an image manifest, or manifest list

## [Options](#options)

| Option          | Default | Description                                          |
| --------------- | ------- | ---------------------------------------------------- |
| `--insecure`    |         | Allow communication with an insecure registry        |
| `-v, --verbose` |         | Output additional info including layers and platform |

----
url: https://docs.docker.com/reference/cli/docker/desktop/diagnose/
----

# docker desktop diagnose

***

| Description | Diagnose Docker Desktop issues      |
| ----------- | ----------------------------------- |
| Usage       | `docker desktop diagnose [OPTIONS]` |

## [Options](#options)

| Option         | Default | Description                |
| -------------- | ------- | -------------------------- |
| `-u, --upload` |         | Uploads the diagnostic ID. |

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/create/
----

# docker mcp profile create

***

| Description | Create a new profile of MCP servers                                                                                                     |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Usage       | `docker mcp profile create --name <name> [--id <id>] --server <ref1> --server <ref2> ... [--connect <client1> --connect <client2> ...]` |

## [Description](#description)

Create a new profile that groups multiple MCP servers together. A profile allows you to organize and manage related servers as a single unit. Profiles are decoupled from catalogs. Servers can be:

* MCP Registry references (e.g. <http://registry.modelcontextprotocol.io/v0/servers/312e45a4-2216-4b21-b9a8-0f1a51425073>)
* OCI image references with docker:// prefix (e.g., "docker://my-server:latest"). Images must be self-describing.
* Catalog references with catalog:// prefix (e.g., "catalog://mcp/docker-mcp-catalog/github+obsidian").
* Local file references with file:// prefix (e.g., "file://./server.yaml").

## [Options](#options)

| Option      | Default | Description                                                                                                                                                                                                          |
| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--connect` |         | Clients to connect to: mcp-client (can be specified multiple times). Supported clients: \[claude-code claude-desktop cline codex continue crush cursor gemini goose gordon kiro lmstudio opencode sema4 vscode zed]  |
| `--id`      |         | ID of the profile (defaults to a slugified version of the name)                                                                                                                                                      |
| `--name`    |         | Name of the profile (required)                                                                                                                                                                                       |
| `--server`  |         | Server to include specified with a URI: https\:// (MCP Registry reference) or docker:// (Docker Image reference) or catalog:// (Catalog reference) or file:// (Local file path). Can be specified multiple times.    |

## [Examples](#examples)

# [Create a profile with servers from a catalog](#create-a-profile-with-servers-from-a-catalog)

docker mcp profile create --name dev-tools --server catalog://mcp/docker-mcp-catalog/github+obsidian

# [Create a profile with multiple servers (OCI references)](#create-a-profile-with-multiple-servers-oci-references)

docker mcp profile create --name my-profile --server docker://my-server:latest --server docker://my-other-server:latest

# [Create a profile with MCP Registry references](#create-a-profile-with-mcp-registry-references)

docker mcp profile create --name my-profile --server <http://registry.modelcontextprotocol.io/v0/servers/71de5a2a-6cfb-4250-a196-f93080ecc860>

# [Connect to clients upon creation](#connect-to-clients-upon-creation)

docker mcp profile create --name dev-tools --connect cursor

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/server/add/
----

# docker mcp profile server add

***

| Description | Add MCP servers to a profile                                                       |
| ----------- | ---------------------------------------------------------------------------------- |
| Usage       | `docker mcp profile server add <profile-id> [--server <ref1> --server <ref2> ...]` |

## [Description](#description)

Add MCP servers to a profile.

## [Options](#options)

| Option     | Default | Description                                                                                                                                                                                                        |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--server` |         | Server to include specified with a URI: https\:// (MCP Registry reference) or docker:// (Docker Image reference) or catalog:// (Catalog reference) or file:// (Local file path). Can be specified multiple times.  |

## [Examples](#examples)

# [Add servers from a catalog](#add-servers-from-a-catalog)

docker mcp profile server add dev-tools --server catalog://mcp/docker-mcp-catalog/github+obsidian

# [Add servers with OCI references](#add-servers-with-oci-references)

docker mcp profile server add my-profile --server docker://my-server:latest

# [Add servers with MCP Registry references](#add-servers-with-mcp-registry-references)

docker mcp profile server add my-profile --server <http://registry.modelcontextprotocol.io/v0/servers/71de5a2a-6cfb-4250-a196-f93080ecc860>

# [Mix server references](#mix-server-references)

docker mcp profile server add dev-tools --server catalog://mcp/docker-mcp-catalog/github+obsidian --server docker://my-server:latest

----
url: https://docs.docker.com/get-started/workshop/08_using_compose/
----

# Use Docker Compose

***

Table of contents

***

[Docker Compose](https://docs.docker.com/compose/) is a tool that helps you define and share multi-container applications. With Compose, you can create a YAML file to define the services and with a single command, you can spin everything up or tear it all down.

The big advantage of using Compose is you can define your application stack in a file, keep it at the root of your project repository (it's now version controlled), and easily enable someone else to contribute to your project. Someone would only need to clone your repository and start the app using Compose. In fact, you might see quite a few projects on GitHub/GitLab doing exactly this now.

## [Create the Compose file](#create-the-compose-file)

In the `getting-started-app` directory, create a file named `compose.yaml`.

```text
├── getting-started-app/
│ ├── Dockerfile
│ ├── compose.yaml
│ ├── node_modules/
│ ├── package.json
│ ├── package-lock.json
│ ├── spec/
│ └── src/
```

## [Define the app service](#define-the-app-service)

In [part 6](https://docs.docker.com/get-started/workshop/07_multi_container/), you used the following command to start the application service.

```console
$ docker run -dp 127.0.0.1:3000:3000 \
  -w /app -v ".:/app" \
  --network todo-app \
  -e MYSQL_HOST=mysql \
  -e MYSQL_USER=root \
  -e MYSQL_PASSWORD=secret \
  -e MYSQL_DB=todos \
  node:24-alpine \
  sh -c "npm install && npm run dev"
```

You'll now define this service in the `compose.yaml` file.

1. Open `compose.yaml` in a text or code editor, and start by defining the name and image of the first service (or container) you want to run as part of your application. The name will automatically become a network alias, which will be useful when defining your MySQL service.

   ```yaml
   services:
     app:
       image: node:24-alpine
   ```

2. Typically, you will see `command` close to the `image` definition, although there is no requirement on ordering. Add the `command` to your `compose.yaml` file.

   ```yaml
   services:
     app:
       image: node:24-alpine
       command: sh -c "npm install && npm run dev"
   ```

3. Now migrate the `-p 127.0.0.1:3000:3000` part of the command by defining the `ports` for the service.

   ```yaml
   services:
     app:
       image: node:24-alpine
       command: sh -c "npm install && npm run dev"
       ports:
         - 127.0.0.1:3000:3000
   ```

4. Next, migrate both the working directory (`-w /app`) and the volume mapping (`-v ".:/app"`) by using the `working_dir` and `volumes` definitions.

   One advantage of Docker Compose volume definitions is you can use relative paths from the current directory.

   ```yaml
   services:
     app:
       image: node:24-alpine
       command: sh -c "npm install && npm run dev"
       ports:
         - 127.0.0.1:3000:3000
       working_dir: /app
       volumes:
         - ./:/app
   ```

5. Finally, you need to migrate the environment variable definitions using the `environment` key.

   ```yaml
   services:
     app:
       image: node:24-alpine
       command: sh -c "npm install && npm run dev"
       ports:
         - 127.0.0.1:3000:3000
       working_dir: /app
       volumes:
         - ./:/app
       environment:
         MYSQL_HOST: mysql
         MYSQL_USER: root
         MYSQL_PASSWORD: secret
         MYSQL_DB: todos
   ```

### [Define the MySQL service](#define-the-mysql-service)

Now, it's time to define the MySQL service. The command that you used for that container was the following:

```console
$ docker run -d \
  --network todo-app --network-alias mysql \
  -v todo-mysql-data:/var/lib/mysql \
  -e MYSQL_ROOT_PASSWORD=secret \
  -e MYSQL_DATABASE=todos \
  mysql:8.0
```

1. First define the new service and name it `mysql` so it automatically gets the network alias. Also specify the image to use as well.

   ```yaml

   services:
     app:
       # The app service definition
     mysql:
       image: mysql:8.0
   ```

2. Next, define the volume mapping. When you ran the container with `docker run`, Docker created the named volume automatically. However, that doesn't happen when running with Compose. You need to define the volume in the top-level `volumes:` section and then specify the mountpoint in the service config. By simply providing only the volume name, the default options are used.

   ```yaml
   services:
     app:
       # The app service definition
     mysql:
       image: mysql:8.0
       volumes:
         - todo-mysql-data:/var/lib/mysql

   volumes:
     todo-mysql-data:
   ```

3. Finally, you need to specify the environment variables.

   ```yaml
   services:
     app:
       # The app service definition
     mysql:
       image: mysql:8.0
       volumes:
         - todo-mysql-data:/var/lib/mysql
       environment:
         MYSQL_ROOT_PASSWORD: secret
         MYSQL_DATABASE: todos

   volumes:
     todo-mysql-data:
   ```

At this point, your complete `compose.yaml` should look like this:

```yaml
services:
  app:
    image: node:24-alpine
    command: sh -c "npm install && npm run dev"
    ports:
      - 127.0.0.1:3000:3000
    working_dir: /app
    volumes:
      - ./:/app
    environment:
      MYSQL_HOST: mysql
      MYSQL_USER: root
      MYSQL_PASSWORD: secret
      MYSQL_DB: todos

  mysql:
    image: mysql:8.0
    volumes:
      - todo-mysql-data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: todos

volumes:
  todo-mysql-data:
```

## [Run the application stack](#run-the-application-stack)

Now that you have your `compose.yaml` file, you can start your application.

1. Make sure no other copies of the containers are running first. Use `docker ps` to list the containers and `docker rm -f <ids>` to remove them.

2. Start up the application stack using the `docker compose up` command. Add the `-d` flag to run everything in the background.

   ```console
   $ docker compose up -d
   ```

   When you run the previous command, you should see output like the following:

   ```plaintext
   Creating network "app_default" with the default driver
   Creating volume "app_todo-mysql-data" with default driver
   Creating app_app_1   ... done
   Creating app_mysql_1 ... done
   ```

   You'll notice that Docker Compose created the volume as well as a network. By default, Docker Compose automatically creates a network specifically for the application stack (which is why you didn't define one in the Compose file).

3. Look at the logs using the `docker compose logs -f` command. You'll see the logs from each of the services interleaved into a single stream. This is incredibly useful when you want to watch for timing-related issues. The `-f` flag follows the log, so will give you live output as it's generated.

   If you have run the command already, you'll see output that looks like this:

   ```plaintext
   mysql_1  | 2019-10-03T03:07:16.083639Z 0 [Note] mysqld: ready for connections.
   mysql_1  | Version: '8.0.31'  socket: '/var/run/mysqld/mysqld.sock'  port: 3306  MySQL Community Server (GPL)
   app_1    | Connected to mysql db at host mysql
   app_1    | Listening on port 3000
   ```

   The service name is displayed at the beginning of the line (often colored) to help distinguish messages. If you want to view the logs for a specific service, you can add the service name to the end of the logs command (for example, `docker compose logs -f app`).

4. At this point, you should be able to open your app in your browser on <http://localhost:3000> and see it running.

## [See the app stack in Docker Desktop Dashboard](#see-the-app-stack-in-docker-desktop-dashboard)

If you look at the Docker Desktop Dashboard, you'll see that there is a group named **getting-started-app**. This is the project name from Docker Compose and used to group the containers together. By default, the project name is simply the name of the directory that the `compose.yaml` was located in.

If you expand the stack, you'll see the two containers you defined in the Compose file. The names are also a little more descriptive, as they follow the pattern of `<service-name>-<replica-number>`. So, it's very easy to quickly see what container is your app and which container is the mysql database.

## [Tear it all down](#tear-it-all-down)

When you're ready to tear it all down, simply run `docker compose down` or hit the trash can on the Docker Desktop Dashboard for the entire app. The containers will stop and the network will be removed.

> Warning
>
> By default, named volumes in your compose file are not removed when you run `docker compose down`. If you want to remove the volumes, you need to add the `--volumes` flag.
>
> The Docker Desktop Dashboard does not remove volumes when you delete the app stack.

## [Summary](#summary)

In this section, you learned about Docker Compose and how it helps you simplify the way you define and share multi-service applications.

Related information:

* [Compose overview](https://docs.docker.com/compose/)
* [Compose file reference](https://docs.docker.com/reference/compose-file/)
* [Compose CLI reference](/reference/cli/docker/compose/)

## [Next steps](#next-steps)

Next, you'll learn about a few best practices you can use to improve your Dockerfile.

[Image-building best practices](https://docs.docker.com/get-started/workshop/09_image_best/)

----
url: https://docs.docker.com/guides/sentiment-analysis/
----

[Build a sentiment analysis app](https://docs.docker.com/guides/sentiment-analysis/)

This guide demonstrates how to containerize sentiment analysis models using Docker.

Python AI

20 minutes

[« Back to all guides](/guides/)

# Build a sentiment analysis app

***

Table of contents

***

## [Overview](#overview)

In this guide, you learn how to build and run a sentiment analysis application. You'll build the application using Python with the Natural Language Toolkit (NLTK), and then set up the environment and run the application using Docker.

The application analyzes user input text for sentiment using NLTK's SentimentIntensityAnalyzer and outputs whether the sentiment is positive, negative, or neutral.

## [Prerequisites](#prerequisites)

* You have installed the latest version of [Docker Desktop](https://docs.docker.com/get-started/get-docker/). Docker adds new features regularly and some parts of this guide may work only with the latest version of Docker Desktop.
* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Get the sample application](#get-the-sample-application)

1. Open a terminal, and clone the sample application's repository using the following command.

   ```console
   $ git clone https://github.com/harsh4870/Docker-NLP.git
   ```

2. Verify that you cloned the repository.

   You should see the following files in your `Docker-NLP` directory.

   ```text
   01_sentiment_analysis.py
   02_name_entity_recognition.py
   03_text_classification.py
   04_text_summarization.py
   05_language_translation.py
   entrypoint.sh
   requirements.txt
   Dockerfile
   README.md
   ```

## [Explore the application code](#explore-the-application-code)

The source code for the sentiment analysis application is in the `Docker-NLP/01_sentiment_analysis.py` file. Open `01_sentiment_analysis.py` in a text or code editor to explore its contents in the following steps.

1. Import the required libraries.

   ```python
   import nltk
   from nltk.sentiment import SentimentIntensityAnalyzer
   import ssl
   ```

   * `nltk`: This is the Natural Language Toolkit library used for working with human language data in Python.
   * `SentimentIntensityAnalyzer`: This is a specific tool from NLTK used for determining the sentiment of a piece of text.
   * `ssl`: This module provides access to Transport Layer Security (encryption) functions used for secure web connections.

2. Handle SSL certificate verification.

   ```python
   try:
       _create_unverified_https_context = ssl._create_unverified_context
   except AttributeError:
       pass
   else:
       ssl._create_default_https_context = _create_unverified_https_context
   ```

   This block is a workaround for certain environments where downloading data through NLTK might fail due to SSL certificate verification issues. It's telling Python to ignore SSL certificate verification for HTTPS requests.

3. Download NLTK resources.

   ```python
   nltk.download('vader_lexicon')
   nltk.download('punkt')
   ```

   * `vader_lexicon`: This is a lexicon used by the `SentimentIntensityAnalyzer` for sentiment analysis.
   * `punkt`: This is used by NLTK for tokenizing sentences. It's necessary for the `SentimentIntensityAnalyzer` to function correctly.

4. Create a sentiment analysis function.

   ```python
   def perform_semantic_analysis(text):
       sid = SentimentIntensityAnalyzer()
       sentiment_score = sid.polarity_scores(text)

       if sentiment_score['compound'] >= 0.05:
           return "Positive"
       elif sentiment_score['compound'] <= -0.05:
           return "Negative"
       else:
           return "Neutral"
   ```

   * `SentimentIntensityAnalyzer()` creates an instance of the analyzer.
   * `polarity_scores(text)` generates a sentiment score for the input text.

   The function returns **Positive**, **Negative**, or **Neutral** based on the compound score.

5. Create the main loop.

   ```python
   if __name__ == "__main__":
       while True:
           input_text = input("Enter the text for semantic analysis (type 'exit' to end): ")

           if input_text.lower() == 'exit':
               print("Exiting...")
               break

           result = perform_semantic_analysis(input_text)
           print(f"Sentiment: {result}")
   ```

   This part of the script runs an infinite loop to accept user input for analysis. If the user types `exit`, the program terminates. Otherwise, it prints out the sentiment of the provided text.

6. Create `requirements.txt`.

   The sample application already contains the `requirements.txt` file to specify the necessary packages that the application imports. Open `requirements.txt` in a code or text editor to explore its contents.

   ```text
   # 01 sentiment_analysis
   nltk==3.6.5

   ...
   ```

   Only the `nltk` package is required for the sentiment analysis application.

## [Explore the application environment](#explore-the-application-environment)

You'll use Docker to run the application in a container. Docker lets you containerize the application, providing a consistent and isolated environment for running it. This means the application will operate as intended within its Docker container, regardless of the underlying system differences.

To run the application in a container, a Dockerfile is required. A Dockerfile is a text document that contains all the commands you would call on the command line to assemble an image. An image is a read-only template with instructions for creating a Docker container.

The sample application already contains a `Dockerfile`. Open the `Dockerfile` in a code or text editor to explore its contents.

The following steps explain each part of the `Dockerfile`. For more details, see the [Dockerfile reference](/reference/dockerfile/).

1. Specify the base image.

   ```dockerfile
   FROM python:3.8-slim
   ```

   This command sets the foundation for the build. `python:3.8-slim` is a lightweight version of the Python 3.8 image, optimized for size and speed. Using this slim image reduces the overall size of your Docker image, leading to quicker downloads and less surface area for security vulnerabilities. This is particularly useful for a Python-based application where you might not need the full standard Python image.

2. Set the working directory.

   ```dockerfile
   WORKDIR /app
   ```

   `WORKDIR` sets the current working directory within the Docker image. By setting it to `/app`, you ensure that all subsequent commands in the Dockerfile (like `COPY` and `RUN`) are executed in this directory. This also helps in organizing your Docker image, as all application-related files are contained in a specific directory.

3. Copy the requirements file into the image.

   ```dockerfile
   COPY requirements.txt /app
   ```

   The `COPY` command transfers the `requirements.txt` file from your local machine into the Docker image. This file lists all Python dependencies required by the application. Copying it into the container lets the next command (`RUN pip install`) install these dependencies inside the image environment.

4. Install the Python dependencies in the image.

   ```dockerfile
   RUN pip install --no-cache-dir -r requirements.txt
   ```

   This line uses `pip`, Python's package installer, to install the packages listed in `requirements.txt`. The `--no-cache-dir` option disables the cache, which reduces the size of the Docker image by not storing the unnecessary cache data.

5. Run additional commands.

   ```dockerfile
   RUN python -m spacy download en_core_web_sm
   ```

   This step is specific to NLP applications that require the spaCy library. It downloads the `en_core_web_sm` model, which is a small English language model for spaCy. While not needed for this app, it's included for compatibility with other NLP applications that might use this Dockerfile.

6. Copy the application code into the image.

   ```dockerfile
   COPY *.py /app
   COPY entrypoint.sh /app
   ```

   These commands copy your Python scripts and the `entrypoint.sh` script into the image's `/app` directory. This is crucial because the container needs these scripts to run the application. The `entrypoint.sh` script is particularly important as it dictates how the application starts inside the container.

7. Set permissions for the `entrypoint.sh` script.

   ```dockerfile
   RUN chmod +x /app/entrypoint.sh
   ```

   This command modifies the file permissions of `entrypoint.sh`, making it executable. This step is necessary to ensure that the Docker container can run this script to start the application.

8. Set the entry point.

   ```dockerfile
   ENTRYPOINT ["/app/entrypoint.sh"]
   ```

   The `ENTRYPOINT` instruction configures the container to run `entrypoint.sh` as its default executable. This means that when the container starts, it automatically executes the script.

   You can explore the `entrypoint.sh` script by opening it in a code or text editor. As the sample contains several applications, the script lets you specify which application to run when the container starts.

## [Run the application](#run-the-application)

To run the application using Docker:

1. Build the image.

   In a terminal, run the following command inside the directory of where the `Dockerfile` is located.

   ```console
   $ docker build -t basic-nlp .
   ```

   The following is a break down of the command:

   * `docker build`: This is the primary command used to build a Docker image from a Dockerfile and a context. The context is typically a set of files at a specified location, often the directory containing the Dockerfile.
   * `-t basic-nlp`: This is an option for tagging the image. The `-t` flag stands for tag. It assigns a name to the image, which in this case is `basic-nlp`. Tags are a convenient way to reference images later, especially when pushing them to a registry or running containers.
   * `.`: This is the last part of the command and specifies the build context. The period (`.`) denotes the current directory. Docker will look for a Dockerfile in this directory. The build context (the current directory, in this case) is sent to the Docker daemon to enable the build. It includes all the files and subdirectories in the specified directory.

   Docker outputs several logs to your console as it builds the image. You'll see it download and install the dependencies. Depending on your network connection, this may take several minutes. Docker does have a caching feature, so subsequent builds can be faster. The console will return to the prompt when it's complete.

   For more details, see the [docker build CLI reference](/reference/cli/docker/buildx/build/).

2. Run the image as a container.

   In a terminal, run the following command.

   ```console
   $ docker run -it basic-nlp 01_sentiment_analysis.py
   ```

   The following is a break down of the command:

   * `docker run`: This is the primary command used to run a new container from a Docker image.

   * `-it`: This is a combination of two options:

     * `-i` or `--interactive`: This keeps the standard input (STDIN) open even if not attached. It lets the container remain running in the foreground and be interactive.
     * `-t` or `--tty`: This allocates a pseudo-TTY, essentially simulating a terminal, like a command prompt or a shell. It's what lets you interact with the application inside the container.

   * `basic-nlp`: This specifies the name of the Docker image to use for creating the container. In this case, it's the image named `basic-nlp` that you created with the `docker build` command.

   * `01_sentiment_analysis.py`: This is the script you want to run inside the Docker container. It gets passed to the `entrypoint.sh` script, which runs it when the container starts.

   For more details, see the [docker run CLI reference](/reference/cli/docker/container/run/).

   > Note
   >
   > For Windows users, you may get an error when running the container. Verify that the line endings in the `entrypoint.sh` are `LF` (`\n`) and not `CRLF` (`\r\n`), then rebuild the image. For more details, see \[Avoid unexpected syntax errors, use Unix style line endings for files in containers]\(/desktop/troubleshoot-and-support/troubleshoot/topics/#Unexpected-syntax-errors-use-Unix-style-line endings-for-files-in-containers).

   You will see the following in your console after the container starts.

   ```console
   Enter the text for semantic analysis (type 'exit' to end):
   ```

3. Test the application.

   Enter a comment to get the sentiment analysis.

   ```console
   Enter the text for semantic analysis (type 'exit' to end): I love containers!
   Sentiment: Positive
   Enter the text for semantic analysis (type 'exit' to end): I'm still learning about containers.
   Sentiment: Neutral
   ```

## [Summary](#summary)

In this guide, you learned how to build and run a sentiment analysis application. You learned how to build the application using Python with NLTK, and then set up the environment and run the application using Docker.

Related information:

* [Docker CLI reference](/reference/cli/docker/)
* [Dockerfile reference](/reference/dockerfile/)
* [Natural Language Toolkit](https://www.nltk.org/)
* [Python documentation](https://docs.python.org/3/)

## [Next steps](#next-steps)

Explore more [natural language processing guides](https://docs.docker.com/guides/).

----
url: https://docs.docker.com/ai/compose/models-and-compose/
----

# Define AI Models in Docker Compose applications

***

Table of contents

***

Requires: Docker Compose [2.38.0](https://github.com/docker/compose/releases/tag/v2.38.0) and later

Compose lets you define AI models as core components of your application, so you can declare model dependencies alongside services and run the application on any platform that supports the Compose Specification.

## [Prerequisites](#prerequisites)

* Docker Compose v2.38 or later
* A platform that supports Compose models such as [Docker Model Runner (DMR)](https://docs.docker.com/ai/model-runner/#requirements).

## [What are Compose models?](#what-are-compose-models)

Compose `models` are a standardized way to define AI model dependencies in your application. By using the [`models` top-level element](https://docs.docker.com/reference/compose-file/models/) in your Compose file, you can:

* Declare which AI models your application needs
* Specify model configurations and requirements
* Make your application portable across different platforms
* Let the platform handle model provisioning and lifecycle management

## [Basic model definition](#basic-model-definition)

To define models in your Compose application, use the `models` top-level element:

```yaml
services:
  chat-app:
    image: my-chat-app
    models:
      - llm

models:
  llm:
    model: ai/smollm2
```

This example defines:

* A service called `chat-app` that uses a model named `llm`
* A model definition for `llm` that references the `ai/smollm2` model image

## [Model configuration options](#model-configuration-options)

Models support various configuration options:

```yaml
models:
  llm:
    model: ai/smollm2
    context_size: 1024
    runtime_flags:
      - "--a-flag"
      - "--another-flag=42"
```

Common configuration options include:

* `model` (required): The OCI artifact identifier for the model. This is what Compose pulls and runs via the model runner.

* `context_size`: Defines the maximum token context size for the model.

  > Note
  >
  > Each model has its own maximum context size. When increasing the context length, consider your hardware constraints. In general, try to keep context size as small as feasible for your specific needs.

* `runtime_flags`: A list of raw command-line flags passed to the inference engine when the model is started. See [Configuration options](https://docs.docker.com/ai/model-runner/configuration/) for commonly used parameters and examples.

* Platform-specific options may also be available via extension attributes `x-*`

> Tip
>
> See more example in the [Common runtime configurations](#common-runtime-configurations) section.

## [Service model binding](#service-model-binding)

Services can reference models in two ways: short syntax and long syntax.

### [Short syntax](#short-syntax)

The short syntax is the simplest way to bind a model to a service:

```yaml
services:
  app:
    image: my-app
    models:
      - llm
      - embedding-model

models:
  llm:
    model: ai/smollm2
  embedding-model:
    model: ai/all-minilm
```

With short syntax, the platform automatically generates environment variables based on the model name:

* `LLM_URL` - URL to access the LLM model
* `LLM_MODEL` - Model identifier for the LLM model
* `EMBEDDING_MODEL_URL` - URL to access the embedding-model
* `EMBEDDING_MODEL_MODEL` - Model identifier for the embedding-model

### [Long syntax](#long-syntax)

The long syntax allows you to customize environment variable names:

```yaml
services:
  app:
    image: my-app
    models:
      llm:
        endpoint_var: AI_MODEL_URL
        model_var: AI_MODEL_NAME
      embedding-model:
        endpoint_var: EMBEDDING_URL
        model_var: EMBEDDING_NAME

models:
  llm:
    model: ai/smollm2
  embedding-model:
    model: ai/all-minilm
```

With this configuration, your service receives:

* `AI_MODEL_URL` and `AI_MODEL_NAME` for the LLM model
* `EMBEDDING_URL` and `EMBEDDING_NAME` for the embedding model

## [Platform portability](#platform-portability)

One of the key benefits of using Compose models is portability across different platforms that support the Compose specification.

### [Docker Model Runner](#docker-model-runner)

When [Docker Model Runner is enabled](https://docs.docker.com/ai/model-runner/):

```yaml
services:
  chat-app:
    image: my-chat-app
    models:
      llm:
        endpoint_var: AI_MODEL_URL
        model_var: AI_MODEL_NAME

models:
  llm:
    model: ai/smollm2
    context_size: 4096
    runtime_flags:
      - "--no-prefill-assistant"
```

Docker Model Runner will:

* Pull and run the specified model locally
* Provide endpoint URLs for accessing the model
* Inject environment variables into the service

### [Cloud providers](#cloud-providers)

The Compose models specification is portable. Platforms that implement the Compose specification can support the `models` top-level element, allowing the same Compose file to run on different infrastructure. Cloud-specific behavior can be configured using extension attributes (`x-*`):

```yaml
services:
  chat-app:
    image: my-chat-app
    models:
      - llm

models:
  llm:
    model: ai/smollm2
    # Cloud-specific configurations
    x-cloud-options:
      - "cloud.instance-type=gpu-small"
      - "cloud.region=us-west-2"
```

How a platform handles model definitions depends on its implementation. A platform might:

* Use managed AI services instead of running models locally
* Apply platform-specific optimizations and scaling
* Provide additional monitoring and logging capabilities
* Handle model versioning and updates automatically

## [Common runtime configurations](#common-runtime-configurations)

Below are some example configurations for various use cases.

### [Development](#development)

```yaml
services:
  app:
    image: app
    models:
      dev_model:
        endpoint_var: DEV_URL
        model_var: DEV_MODEL

models:
  dev_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--verbose"                       # Set verbosity level to infinity
      - "--verbose-prompt"                # Print a verbose prompt before generation
      - "--log-prefix"                    # Enable prefix in log messages
      - "--log-timestamps"                # Enable timestamps in log messages
      - "--log-colors"                    # Enable colored logging
```

### [Conservative with disabled reasoning](#conservative-with-disabled-reasoning)

```yaml
services:
  app:
    image: app
    models:
      conservative_model:
        endpoint_var: CONSERVATIVE_URL
        model_var: CONSERVATIVE_MODEL

models:
  conservative_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp"                # Temperature
      - "0.1"
      - "--top-k"               # Top-k sampling
      - "1"
      - "--reasoning-budget"    # Disable reasoning
      - "0"
```

### [Creative with high randomness](#creative-with-high-randomness)

```yaml
services:
  app:
    image: app
    models:
      creative_model:
        endpoint_var: CREATIVE_URL
        model_var: CREATIVE_MODEL

models:
  creative_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp"                # Temperature
      - "1"
      - "--top-p"               # Top-p sampling
      - "0.9"
```

### [Highly deterministic](#highly-deterministic)

```yaml
services:
  app:
    image: app
    models:
      deterministic_model:
        endpoint_var: DET_URL
        model_var: DET_MODEL

models:
  deterministic_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp"                # Temperature
      - "0"
      - "--top-k"               # Top-k sampling
      - "1"
```

### [Concurrent processing](#concurrent-processing)

```yaml
services:
  app:
    image: app
    models:
      concurrent_model:
        endpoint_var: CONCURRENT_URL
        model_var: CONCURRENT_MODEL

models:
  concurrent_model:
    model: ai/model
    context_size: 2048
    runtime_flags:
      - "--threads"             # Number of threads to use during generation
      - "8"
      - "--mlock"               # Lock memory to prevent swapping
```

### [Rich vocabulary model](#rich-vocabulary-model)

```yaml
services:
  app:
    image: app
    models:
      rich_vocab_model:
        endpoint_var: RICH_VOCAB_URL
        model_var: RICH_VOCAB_MODEL

models:
  rich_vocab_model:
    model: ai/model
    context_size: 4096
    runtime_flags:
      - "--temp"                # Temperature
      - "0.1"
      - "--top-p"               # Top-p sampling
      - "0.9"
```

### [Embeddings](#embeddings)

When using embedding models with the `/v1/embeddings` endpoint, you must include the `--embeddings` runtime flag for the model to be properly configured.

```yaml
services:
  app:
    image: app
    models:
      embedding_model:
        endpoint_var: EMBEDDING_URL
        model_var: EMBEDDING_MODEL

models:
  embedding_model:
    model: ai/all-minilm
    context_size: 2048
    runtime_flags:
      - "--embeddings"          # Required for embedding models
```

## [Reference](#reference)

* [`models` top-level element](https://docs.docker.com/reference/compose-file/models/)
* [`models` attribute](https://docs.docker.com/reference/compose-file/services/#models)
* [Docker Model Runner documentation](https://docs.docker.com/ai/model-runner/)
* [Configuration options](https://docs.docker.com/ai/model-runner/configuration/) - Context size and runtime parameters
* [Inference engines](https://docs.docker.com/ai/model-runner/inference-engines/) - llama.cpp and vLLM details
* [API reference](https://docs.docker.com/ai/model-runner/api-reference/) - OpenAI and Ollama-compatible APIs

----
url: https://docs.docker.com/guides/testcontainers-java-quarkus/
----

# Testing Quarkus applications with Testcontainers

Table of contents

***

Learn how to create a Quarkus REST API with Hibernate ORM with Panache and PostgreSQL, then test it using Quarkus Dev Services, Testcontainers, and REST Assured.

**Time to complete** 25 minutes

In this guide, you'll learn how to:

* Create a Quarkus application with REST API endpoints
* Use Hibernate ORM with Panache and PostgreSQL for persistence
* Test the REST API using Quarkus Dev Services, which uses Testcontainers behind the scenes
* Test with services not supported by Dev Services using `QuarkusTestResourceLifecycleManager`

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-quarkus/create-project/)

   Set up a Quarkus project with Hibernate ORM with Panache, PostgreSQL, Flyway, and REST API endpoints.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-quarkus/write-tests/)

   Test the Quarkus REST API using Dev Services with Testcontainers, and test with services not supported by Dev Services.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-quarkus/run-tests/)

   Run your Testcontainers-based Quarkus integration tests and explore next steps.

----
url: https://docs.docker.com/guides/php/run-tests/
----

# Run PHP tests in a container

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a PHP application](https://docs.docker.com/guides/php/containerize/).

## [Overview](#overview)

Testing is an essential part of modern software development. Testing can mean a lot of things to different development teams. There are unit tests, integration tests and end-to-end testing. In this guide you take a look at running your unit tests in Docker when developing and when building.

## [Run tests when developing locally](#run-tests-when-developing-locally)

The sample application already has a PHPUnit test inside the `tests` directory. When developing locally, you can use Compose to run your tests.

Run the following command in the `docker-php-sample` directory to run the tests inside a container.

```console
$ docker compose run --build --rm server ./vendor/bin/phpunit tests/HelloWorldTest.php
```

You should see output that contains the following.

```console
Hello, Docker!PHPUnit 9.6.13 by Sebastian Bergmann and contributors.

.                                                                   1 / 1 (100%)

Time: 00:00.003, Memory: 4.00 MB

OK (1 test, 1 assertion)
```

To learn more about the command, see [docker compose run](/reference/cli/docker/compose/run/).

## [Run tests when building](#run-tests-when-building)

To run your tests when building, you need to update your Dockerfile. Create a new test stage that runs the tests.

The following is the updated Dockerfile.

```dockerfile
# syntax=docker/dockerfile:1

FROM composer:lts as prod-deps
WORKDIR /app
RUN --mount=type=bind,source=./composer.json,target=composer.json \
    --mount=type=bind,source=./composer.lock,target=composer.lock \
    --mount=type=cache,target=/tmp/cache \
    composer install --no-dev --no-interaction

FROM composer:lts as dev-deps
WORKDIR /app
RUN --mount=type=bind,source=./composer.json,target=composer.json \
    --mount=type=bind,source=./composer.lock,target=composer.lock \
    --mount=type=cache,target=/tmp/cache \
    composer install --no-interaction

FROM php:8.2-apache as base
RUN docker-php-ext-install pdo pdo_mysql
COPY ./src /var/www/html

FROM base as development
COPY ./tests /var/www/html/tests
RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini"
COPY --from=dev-deps app/vendor/ /var/www/html/vendor

FROM development as test
WORKDIR /var/www/html
RUN ./vendor/bin/phpunit tests/HelloWorldTest.php

FROM base as final
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
COPY --from=prod-deps app/vendor/ /var/www/html/vendor
USER www-data
```

Run the following command to build an image using the test stage as the target and view the test results. Include `--progress plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target test` to target the test stage.

```console
$ docker build -t php-docker-image-test --progress plain --no-cache --target test .
```

You should see output containing the following.

```console
#18 [test 2/2] RUN ./vendor/bin/phpunit tests/HelloWorldTest.php
#18 0.385 Hello, Docker!PHPUnit 9.6.13 by Sebastian Bergmann and contributors.
#18 0.392
#18 0.394 .                                                                   1 / 1 (100%)
#18 0.395
#18 0.395 Time: 00:00.003, Memory: 4.00 MB
#18 0.395
#18 0.395 OK (1 test, 1 assertion)
```

## [Summary](#summary)

In this section, you learned how to run tests when developing locally using Compose and how to run tests when building your image.

Related information:

* [docker compose run](/reference/cli/docker/compose/run/)

## [Next steps](#next-steps)

Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions.

[Configure CI/CD for your PHP application »](https://docs.docker.com/guides/php/configure-ci-cd/)

----
url: https://docs.docker.com/guides/nextjs/run-tests/
----

# Run Next.js tests in a container

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize Next.js application](https://docs.docker.com/guides/nextjs/containerize/).

## [Overview](#overview)

Testing is a critical part of the development process. In this section, you'll learn how to:

* Run unit tests using Vitest (or Jest) inside a Docker container.
* Run lint (e.g. ESLint) inside a Docker container.
* Use Docker Compose to run tests and lint in an isolated, reproducible environment.

The [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample) uses [Vitest](https://vitest.dev/) with [Testing Library](https://testing-library.com/) for component testing. You can use the same setup or follow the alternative Jest configuration later.

***

## [Run tests during development](#run-tests-during-development)

The [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample) already includes lint (ESLint) and sample tests (Vitest, `app/page.test.tsx`) in place. If you're using the sample app, you can skip to **Step 3: Update compose.yaml** and run tests or lint with the commands below. If you're using your own project, follow the install and configuration steps to add the packages and scripts.

The sample includes a test file at:

```text
app/page.test.tsx
```

This file uses Vitest and React Testing Library to verify the behavior of page components.

### [Step 1: Install Vitest and React Testing Library (custom projects)](#step-1-install-vitest-and-react-testing-library-custom-projects)

If you're using a custom project and haven't already added the necessary testing tools, install them by running:

```console
$ npm install --save-dev vitest @vitejs/plugin-react @testing-library/react @testing-library/dom jsdom
```

Then, update the scripts section of your `package.json` file to include:

```json
"scripts": {
  "test": "vitest",
  "test:run": "vitest run"
}
```

For lint, add a `lint` script (and optionally `lint:fix`). For example, with [ESLint](https://eslint.org/):

```json
"scripts": {
  "test": "vitest",
  "test:run": "vitest run",
  "lint": "eslint .",
  "lint:fix": "eslint . --fix"
}
```

The sample project uses `eslint` and `eslint-config-next` for Next.js. Install them in a custom project with:

```console
$ npm install --save-dev eslint eslint-config-next @eslint/eslintrc
```

Create an ESLint config file (e.g. `eslint.config.cjs`) in your project root with Next.js rules and global ignores:

```js
const { defineConfig, globalIgnores } = require("eslint/config");
const { FlatCompat } = require("@eslint/eslintrc");

const compat = new FlatCompat({ baseDirectory: __dirname });

module.exports = defineConfig([
  ...compat.extends(
    "eslint-config-next/core-web-vitals",
    "eslint-config-next/typescript"
  ),
  globalIgnores([
    ".next/**",
    "out/**",
    "build/**",
    "next-env.d.ts",
    "node_modules/**",
    "eslint.config.cjs",
  ]),
]);
```

***

### [Step 2: Configure Vitest (custom projects)](#step-2-configure-vitest-custom-projects)

If you're using a custom project, create a `vitest.config.ts` file in your project root (matching the [sample project](https://github.com/kristiyan-velkov/docker-nextjs-sample)):

```ts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    setupFiles: "./vitest.setup.ts",
    globals: true,
  },
});
```

Create a `vitest.setup.ts` file in your project root:

```ts
import "@testing-library/jest-dom/vitest";
```

> Note
>
> Vitest works well with Next.js and provides fast execution and ESM support. For more details, see the [Next.js testing documentation](https://nextjs.org/docs/app/building-your-application/testing) and [Vitest docs](https://vitest.dev/).

### [Step 3: Update compose.yaml](#step-3-update-composeyaml)

Add `nextjs-test` and `nextjs-lint` services to your `compose.yaml` file. In the sample project these services use the `tools` profile so they don't start with a normal `docker compose up`. Both reuse `Dockerfile.dev` and run the test or lint command:

```yaml
services:
  nextjs-prod-standalone:
    build:
      context: .
      dockerfile: Dockerfile
    image: nextjs-sample:prod
    container_name: nextjs-sample-prod
    ports:
      - "3000:3000"

  nextjs-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    image: nextjs-sample:dev
    container_name: nextjs-sample-dev
    ports:
      - "3000:3000"
    environment:
      - WATCHPACK_POLLING=true
    develop:
      watch:
        - action: sync
          path: .
          target: /app
          ignore:
            - node_modules/
            - .next/
        - action: rebuild
          path: package.json

  nextjs-test:
    build:
      context: .
      dockerfile: Dockerfile.dev
    image: nextjs-sample:dev
    container_name: nextjs-sample-test
    command:
      [
        "sh",
        "-c",
        "if [ -f package-lock.json ]; then npm run test:run 2>/dev/null || npm run test -- --run; elif [ -f yarn.lock ]; then yarn test:run 2>/dev/null || yarn test --run; elif [ -f pnpm-lock.yaml ]; then pnpm run test:run; else npm run test -- --run; fi",
      ]
    profiles:
      - tools

  nextjs-lint:
    build:
      context: .
      dockerfile: Dockerfile.dev
    image: nextjs-sample:dev
    container_name: nextjs-sample-lint
    command:
      [
        "sh",
        "-c",
        "if [ -f package-lock.json ]; then npm run lint; elif [ -f yarn.lock ]; then yarn lint; elif [ -f pnpm-lock.yaml ]; then pnpm lint; else npm run lint; fi",
      ]
    profiles:
      - tools
```

The `nextjs-test` and `nextjs-lint` services reuse the same `Dockerfile.dev` used for [development](https://docs.docker.com/guides/nextjs/develop/) and override the default command to run tests or lint. The `profiles: [tools]` means these services only run when you use the `--profile tools` option.

After completing the previous steps, your project directory should contain:

```text
├── docker-nextjs-sample/
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ ├── .dockerignore
│ ├── compose.yaml
│ ├── vitest.config.ts
│ ├── vitest.setup.ts
│ └── next.config.ts
```

### [Step 4: Run the tests](#step-4-run-the-tests)

To execute your test suite inside the container, run from your project root:

```console
$ docker compose --profile tools run --rm nextjs-test
```

This command will:

* Start the `nextjs-test` service (because of `--profile tools`).
* Run your test script (`test:run` or `test -- --run`) in the same environment as development.
* Remove the container after the tests complete ( [`docker compose run --rm`](/reference/cli/docker/compose/run/)).

> Note
>
> For more information about Compose commands and profiles, see the [Compose CLI reference](/reference/cli/docker/compose/).

### [Step 5: Run lint in the container](#step-5-run-lint-in-the-container)

To run your linter (e.g. ESLint) inside the container, use the `nextjs-lint` service with the same `tools` profile:

```console
$ docker compose --profile tools run --rm nextjs-lint
```

This command will:

* Start the `nextjs-lint` service (because of `--profile tools`).
* Run your lint script (`npm run lint`, `yarn lint`, or `pnpm lint` depending on your lockfile) in the same environment as development.
* Remove the container after lint completes.

Ensure your `package.json` includes a `lint` script. The sample project already has `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"`; for a custom project, add the same and install `eslint` and `eslint-config-next` if needed.

***

## [Summary](#summary)

In this section, you learned how to run unit tests for your Next.js application inside a Docker container using Vitest and Docker Compose.

What you accomplished:

* Installed and configured Vitest and React Testing Library for testing Next.js components.
* Created `nextjs-test` and `nextjs-lint` services in `compose.yaml` (with `tools` profile) to isolate test and lint execution.
* Reused the development `Dockerfile.dev` to ensure consistency between dev, test, and lint environments.
* Ran tests inside the container using `docker compose --profile tools run --rm nextjs-test`.
* Ran lint inside the container using `docker compose --profile tools run --rm nextjs-lint`.
* Ensured reliable, repeatable testing and linting across environments without relying on local machine setup.

***

## [Related resources](#related-resources)

Explore official references and best practices to sharpen your Docker testing workflow:

* [Dockerfile reference](/reference/dockerfile/) – Understand all Dockerfile instructions and syntax.
* [Best practices for writing Dockerfiles](/develop/develop-images/dockerfile_best-practices/) – Write efficient, maintainable, and secure Dockerfiles.
* [Compose file reference](/compose/compose-file/) – Learn the full syntax and options available for configuring services in `compose.yaml`.
* [`docker compose run` CLI reference](/reference/cli/docker/compose/run/) – Run one-off commands in a service container.
* [Next.js Testing Documentation](https://nextjs.org/docs/app/building-your-application/testing) – Official Next.js testing guide.

***

## [Next steps](#next-steps)

Next, you'll learn how to set up a CI/CD pipeline using GitHub Actions to automatically build and test your Next.js application in a containerized environment. This ensures your code is validated on every push or pull request, maintaining consistency and reliability across your development workflow.

[Automate your builds with GitHub Actions »](https://docs.docker.com/guides/nextjs/configure-github-actions/)

----
url: https://docs.docker.com/reference/cli/docker/compose/bridge/transformations/list/
----

# docker compose bridge transformations list

***

| Description                                                               | List available transformations               |
| ------------------------------------------------------------------------- | -------------------------------------------- |
| Usage                                                                     | `docker compose bridge transformations list` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker compose bridge transformations ls`   |

## [Description](#description)

List available transformations

## [Options](#options)

| Option        | Default | Description                                 |
| ------------- | ------- | ------------------------------------------- |
| `--format`    | `table` | Format the output. Values: \[table \| json] |
| `-q, --quiet` |         | Only display transformer names              |

----
url: https://docs.docker.com/reference/cli/docker/dhi/attestation/sbom/
----

# docker dhi attestation sbom

***

| Description | Display the SPDX SBOM for a Docker Hardened Image |
| ----------- | ------------------------------------------------- |
| Usage       | `docker dhi attestation sbom <image>`             |

## [Description](#description)

Display the SPDX SBOM attestation attached to a Docker Hardened Image in a human-readable format.

The command fetches the SPDX SBOM attestation from the OCI Referrers API, extracts the SPDX document, and displays a summary with a package table.

The image can be specified as:

* name:tag (e.g., nginx:1.27)
* namespace/name:tag (e.g., dhi/nginx:1.27)
* name\@sha256:digest (e.g., nginx\@sha256:abc123...)

Examples:

# [Display the SBOM for an image](#display-the-sbom-for-an-image)

docker dhi attestation sbom dhi/nginx:1.27

# [Display the SBOM for a specific platform](#display-the-sbom-for-a-specific-platform)

docker dhi attestation sbom dhi/nginx:1.27 --platform linux/amd64

## [Options](#options)

| Option       | Default | Description                                                                        |
| ------------ | ------- | ---------------------------------------------------------------------------------- |
| `--platform` |         | Platform to filter by (e.g., linux/amd64). Defaults to the Docker daemon platform  |

----
url: https://docs.docker.com/reference/cli/docker/sandbox/exec/
----

# docker sandbox exec

***

| Description | Execute a command inside a sandbox                       |
| ----------- | -------------------------------------------------------- |
| Usage       | `docker sandbox exec [OPTIONS] SANDBOX COMMAND [ARG...]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Execute a command in a sandbox that was previously created with 'docker sandbox create'.

The command and any additional arguments are executed inside the sandbox container.

## [Options](#options)

| Option                      | Default | Description                                             |
| --------------------------- | ------- | ------------------------------------------------------- |
| [`-d, --detach`](#detach)   |         | Detached mode: run command in the background            |
| `--detach-keys`             |         | Override the key sequence for detaching a container     |
| [`-e, --env`](#env)         |         | Set environment variables                               |
| `--env-file`                |         | Read in a file of environment variables                 |
| `-i, --interactive`         |         | Keep STDIN open even if not attached                    |
| `--privileged`              |         | Give extended privileges to the command                 |
| `-t, --tty`                 |         | Allocate a pseudo-TTY                                   |
| [`-u, --user`](#user)       |         | Username or UID (format: \<name\|uid>\[:\<group\|gid>]) |
| [`-w, --workdir`](#workdir) |         | Working directory inside the container                  |

## [Examples](#examples)

### [Execute a command in a sandbox](#execute-a-command-in-a-sandbox)

```console
$ docker sandbox exec my-sandbox ls -la
```

### [Run an interactive shell](#run-an-interactive-shell)

```console
$ docker sandbox exec -it my-sandbox /bin/bash
```

### [Set environment variables (-e, --env)](#env)

```text
--env KEY=VALUE
```

Pass environment variables to the command:

```console
$ docker sandbox exec \
  --env NODE_ENV=development \
  --env DATABASE_URL=postgresql://localhost/myapp \
  my-sandbox npm test
```

### [Set working directory (-w, --workdir)](#workdir)

```text
--workdir PATH
```

Run the command in a specific directory:

```console
$ docker sandbox exec --workdir /app my-sandbox python script.py
```

### [Run as specific user (-u, --user)](#user)

```text
--user USER[:GROUP]
```

Execute command as a different user:

```console
$ docker sandbox exec --user 1000:1000 my-sandbox id
```

### [Run in background (-d, --detach)](#detach)

Run a long-running command in the background:

```console
$ docker sandbox exec -d my-sandbox python server.py
```

----
url: https://docs.docker.com/docker-hub/repos/manage/hub-images/tags/
----

# Tags on Docker Hub

***

Table of contents

***

Tags let you manage multiple versions of images within a single Docker Hub repository. By adding a specific `:<tag>` to each image, such as `docs/base:testing`, you can organize and differentiate image versions for various use cases. If no tag is specified, the image defaults to the `latest` tag.

## [Tag a local image](#tag-a-local-image)

To tag a local image, use one of the following methods:

* When you build an image, use `docker build -t <org-or-user-namespace>/<repo-name>[:<tag>`.
* Re-tag an existing local image with `docker tag <existing-image> <org-or-user-namespace>/<repo-name>[:<tag>]`.
* When you commit changes, use `docker commit <existing-container> <org-or-user-namespace>/<repo-name>[:<tag>]`.

Then, you can push this image to the repository designated by its name or tag:

```console
$ docker push <org-or-user-namespace>/<repo-name>:<tag>
```

The image is then uploaded and available for use in Docker Hub.

## [View repository tags](#view-repository-tags)

You can view the available tags and the size of the associated image.

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Tags** tab.

You can select a tag's digest to see more details.

## [Delete repository tags](#delete-repository-tags)

Only the repository owner or other team members with granted permissions can delete tags.

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub** > **Repositories**.

   A list of your repositories appears.

3. Select a repository.

   The **General** page for the repository appears.

4. Select the **Tags** tab.

5. Select the corresponding checkbox next to the tags to delete.

6. Select **Delete**.

   A confirmation dialog appears.

7. Select **Delete**.

----
url: https://docs.docker.com/guides/bun/deploy/
----

# Test your Bun deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Containerize a Bun application](https://docs.docker.com/guides/bun/containerize/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your `bun-docker` directory, create a file named `docker-kubernetes.yml`. Open the file in an IDE or text editor and add the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the name of the repository that you created in [Configure CI/CD for your Bun application](https://docs.docker.com/guides/bun/configure-ci-cd/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-bun-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: bun-api
  template:
    metadata:
      labels:
        app: bun-api
    spec:
      containers:
       - name: bun-api
         image: DOCKER_USERNAME/REPO_NAME
         imagePullPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: service-entrypoint
  namespace: default
spec:
  type: NodePort
  selector:
    app: bun-api
  ports:
  - port: 3000
    targetPort: 3000
    nodePort: 30001
```

In this Kubernetes YAML file, there are two objects, separated by the `---`:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your Bun application](https://docs.docker.com/guides/bun/configure-ci-cd/).
* A NodePort service, which will route traffic from port 30001 on your host to port 3000 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to `bun-docker` and deploy your application to Kubernetes.

   ```console
   $ kubectl apply -f docker-kubernetes.yml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```text
   deployment.apps/docker-bun-demo created
   service/service-entrypoint created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```shell
   NAME                 READY   UP-TO-DATE   AVAILABLE    AGE
   docker-bun-demo       1/1     1            1           10s
   ```

   This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```shell
   NAME                 TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
   kubernetes           ClusterIP   10.96.0.1        <none>        443/TCP          88m
   service-entrypoint   NodePort    10.105.145.223   <none>        3000:30001/TCP   83s
   ```

   In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP.

3. In a browser, visit the following address. You should see the message `{"Status" : "OK"}`.

   ```console
   http://localhost:30001/
   ```

4. Run the following command to tear down your application.

   ```console
   $ kubectl delete -f docker-kubernetes.yml
   ```

## [Summary](#summary)

In this section, you learned how to use Docker Desktop to deploy your Bun application to a fully-featured Kubernetes environment on your development machine.

Related information:

* [Kubernetes documentation](https://kubernetes.io/docs/home/)
* [Deploy on Kubernetes with Docker Desktop](https://docs.docker.com/desktop/use-desktop/kubernetes/)
* [Swarm mode overview](https://docs.docker.com/engine/swarm/)

----
url: https://docs.docker.com/ai/docker-agent/best-practices/
----

# Best practices

***

Table of contents

***

Patterns you learn from building and running agents with Docker Agent. These aren't features or configuration options - they're approaches that work well in practice.

## [Handling large command outputs](#handling-large-command-outputs)

Shell commands that produce large output can overflow your agent's context window. Validation tools, test suites, and build logs often generate thousands of lines. If you capture this output directly, it consumes all available context and the agent fails.

The solution: redirect output to a file, then read the file. The Read tool automatically truncates large files to 2000 lines, and your agent can navigate through it if needed.

**Don't do this:**

```yaml
reviewer:
  instruction: |
    Run validation: `docker buildx bake validate`
    Check the output for errors.
  toolsets:
    - type: shell
```

The validation output goes directly into context. If it's large, the agent fails with a context overflow error.

**Do this:**

```yaml
reviewer:
  instruction: |
    Run validation and save output:
    `docker buildx bake validate > validation.log 2>&1`

    Read validation.log to check for errors.
    The file can be large - read the first 2000 lines.
    Errors usually appear at the beginning.
  toolsets:
    - type: filesystem
    - type: shell
```

The output goes to a file, not context. The agent reads what it needs using the filesystem toolset.

## [Structuring agent teams](#structuring-agent-teams)

A single agent handling multiple responsibilities makes instructions complex and behavior unpredictable. Breaking work across specialized agents produces better results.

The coordinator pattern works well: a root agent understands the overall task and delegates to specialists. Each specialist focuses on one thing.

**Example: Documentation writing team**

```yaml
agents:
  root:
    description: Technical writing coordinator
    instruction: |
      Coordinate documentation work:
      1. Delegate to writer for content creation
      2. Delegate to editor for formatting polish
      3. Delegate to reviewer for validation
      4. Loop back through editor if reviewer finds issues
    sub_agents: [writer, editor, reviewer]
    toolsets: [filesystem, todo]

  writer:
    description: Creates and edits documentation content
    instruction: |
      Write clear, practical documentation.
      Focus on content quality - the editor handles formatting.
    toolsets: [filesystem, think]

  editor:
    description: Polishes formatting and style
    instruction: |
      Fix formatting issues, wrap lines, run prettier.
      Remove AI-isms and polish style.
      Don't change meaning or add content.
    toolsets: [filesystem, shell]

  reviewer:
    description: Runs validation tools
    instruction: |
      Run validation suite, report failures.
    toolsets: [filesystem, shell]
```

Each agent has clear responsibilities. The writer doesn't worry about line wrapping. The editor doesn't generate content. The reviewer just runs tools.

This example uses `sub_agents` where root delegates discrete tasks and gets results back. The root agent maintains control and coordinates all work. For different coordination patterns where agents should transfer control to each other, see the `handoffs` mechanism in the [configuration reference](https://docs.docker.com/ai/docker-agent/reference/config/#task-delegation-versus-conversation-handoff).

**When to use teams:**

* Multiple distinct steps in your workflow
* Different skills required (writing ↔ editing ↔ testing)
* One step might need to retry based on later feedback

**When to use a single agent:**

* Simple, focused tasks
* All work happens in one step
* Adding coordination overhead doesn't help

## [Optimizing RAG performance](#optimizing-rag-performance)

RAG indexing takes time when you have many files. A configuration that indexes your entire codebase might take minutes to start. Optimize for what your agent actually needs.

**Narrow the scope:**

Don't index everything. Index what's relevant for the agent's work.

```yaml
# Too broad - indexes entire codebase
rag:
  codebase:
    docs: [./]

# Better - indexes only relevant directories
rag:
  codebase:
    docs: [./src/api, ./docs, ./examples]
```

If your agent only works with API code, don't index tests, vendor directories, or generated files.

**Increase batching and concurrency:**

Process more chunks per API call and make parallel requests.

```yaml
strategies:
  - type: chunked-embeddings
    embedding_model: openai/text-embedding-3-small
    batch_size: 50 # More chunks per API call
    max_embedding_concurrency: 10 # Parallel requests
    chunking:
      size: 2000 # Larger chunks = fewer total chunks
      overlap: 150
```

This reduces both API calls and indexing time.

**Consider BM25 for fast local search:**

If you need exact term matching (function names, error messages, identifiers), BM25 is fast and runs locally without API calls.

```yaml
strategies:
  - type: bm25
    database: ./bm25.db
    chunking:
      size: 1500
```

Combine with embeddings using hybrid retrieval when you need both semantic understanding and exact matching.

## [Preserving document scope](#preserving-document-scope)

When building agents that update documentation, a common problem: the agent transforms minimal guides into tutorials. It adds prerequisites, troubleshooting, best practices, examples, and detailed explanations to everything.

These additions might individually be good, but they change the document's character. A focused 90-line how-to becomes a 200-line reference.

**Build this into instructions:**

```yaml
writer:
  instruction: |
    When updating documentation:

    1. Understand the current document's scope and length
    2. Match that character - don't transform minimal guides into tutorials
    3. Add only what's genuinely missing
    4. Value brevity - not every topic needs comprehensive coverage

    Good additions fill gaps. Bad additions change the document's character.
    When in doubt, add less rather than more.
```

Tell your agents explicitly to preserve the existing document's scope. Without this guidance, they default to being comprehensive.

## [Model selection](#model-selection)

Choose models based on the agent's role and complexity.

**Use larger models (Sonnet, GPT-5) for:**

* Complex reasoning and planning
* Writing and editing content
* Coordinating multiple agents
* Tasks requiring judgment and creativity

**Use smaller models (Haiku, GPT-5 Mini) for:**

* Running validation tools
* Simple structured tasks
* Reading logs and reporting errors
* High-volume, low-complexity work

Example from the documentation writing team:

```yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-5 # Complex coordination
  writer:
    model: anthropic/claude-sonnet-4-5 # Creative content work
  editor:
    model: anthropic/claude-sonnet-4-5 # Judgment about style
  reviewer:
    model: anthropic/claude-haiku-4-5 # Just runs validation
```

The reviewer uses Haiku because it runs commands and checks for errors. No complex reasoning needed, and Haiku is faster and cheaper.

## [What's next](#whats-next)

* Review [configuration reference](https://docs.docker.com/ai/docker-agent/reference/config/) for all available options
* Check [toolsets reference](https://docs.docker.com/ai/docker-agent/reference/toolsets/) to understand what tools agents can use
* See [example configurations](https://github.com/docker/docker-agent/tree/main/examples) for complete working agents
* Read the [RAG guide](https://docs.docker.com/ai/docker-agent/rag/) for detailed retrieval optimization

----
url: https://docs.docker.com/enterprise/security/provisioning/scim/group-mapping/
----

# Group mapping

***

Table of contents

***

Subscription: Business

For: Administrators

Group mapping automatically synchronizes user groups from your identity provider (IdP) with teams in your Docker organization. For example, when you add a developer to the "backend-team" group in your IdP, they're automatically added to the corresponding team in Docker

This page explains how group mapping works, and how to set up group mapping.

> Tip
>
> Group mapping is ideal for adding users to multiple organizations or multiple teams within one organization. If you don't need to set up multi-organization or multi-team assignment, SCIM [user-level attributes](https://docs.docker.com/enterprise/security/provisioning/scim/provision-scim/#set-up-role-mapping) may be a better fit for your needs.

## [Prerequisites](#prerequisites)

Before you begin, you must have:

* SSO configured for your organization
* Administrator access to Docker Home and your identity provider

## [How group mapping works](#how-group-mapping-works)

Group mapping keeps your Docker Teams synchronized with your IdP groups through these key components:

* Authentication flow: When users sign in through SSO, your IdP shares user attributes with Docker including email, name, and group memberships.
* Automatic updates: Docker uses these attributes to create or update user profiles and manage team assignments based on IdP group changes.
* Unique identification: Docker uses email addresses as unique identifiers, so each Docker account must have a unique email address.
* Team synchronization: Users' team memberships in Docker automatically reflect changes made in your IdP groups.

## [Set up group mapping](#set-up-group-mapping)

Group mapping setup involves configuring your identity provider to share group information with Docker. This requires:

* Creating groups in your IdP using Docker's naming format
* Configuring attributes so your IdP sends group data during authentication
* Adding users to the appropriate groups
* Testing the connection to ensure groups sync properly

You can use group mapping with SSO only, or with both SSO and SCIM for enhanced user lifecycle management.

### [Group naming format](#group-naming-format)

Create groups in your IdP using the format: `organization:team`.

For example:

* For the "developers" team in the "moby" organization: `moby:developers`
* For multi-organization access: `moby:backend` and `whale:desktop`

Docker creates teams automatically if they don't already exist when groups sync.

### [Supported attributes](#supported-attributes)

| Attribute          | Description                                                                         |
| ------------------ | ----------------------------------------------------------------------------------- |
| `id`               | Unique ID of the group in UUID format. This attribute is read-only.                 |
| `displayName`      | Name of the group following the group mapping format: `organization:team`.          |
| `members`          | A list of users that are members of this group.                                     |
| `members(x).value` | Unique ID of the user that is a member of this group. Members are referenced by ID. |

## [Configure group mapping with SSO](#configure-group-mapping-with-sso)

Use group mapping with SSO connections that use the SAML authentication method.

> Note
>
> Group mapping with SSO isn't supported with the Azure AD (OIDC) authentication method. SCIM isn't required for these configurations.

The user interface for your IdP may differ slightly from the following steps. Refer to the [Okta documentation](https://help.okta.com/oie/en-us/content/topics/apps/define-group-attribute-statements.htm) to verify.

To set up group mapping:

1. Sign in to Okta and open your application.

2. Navigate to the **SAML Settings** page for your application.

3. In the **Group Attribute Statements (optional)** section, configure like the following:

   * **Name**: `groups`
   * **Name format**: `Unspecified`
   * **Filter**: `Starts with` + `organization:` where `organization` is the name of your organization The filter option will filter out the groups that aren't affiliated with your Docker organization.

4. Create your groups by selecting **Directory**, then **Groups**.

5. Add your groups using the format `organization:team` that matches the names of your organization(s) and team(s) in Docker.

6. Assign users to the group(s) that you create.

The next time you sync your groups with Docker, your users will map to the Docker groups you defined.

The user interface for your IdP may differ slightly from the following steps. Refer to the [Entra ID documentation](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes) to verify.

To set up group mapping:

1. Sign in to Entra ID and open your application.

2. Select **Manage**, then **Single sign-on**.

3. Select **Add a group claim**.

4. In the Group Claims section, select **Groups assigned to the application** with the source attribute **Cloud-only group display names (Preview)**.

5. Select **Advanced options**, then the **Filter groups** option.

6. Configure the attribute like the following:

   * **Attribute to match**: `Display name`
   * **Match with**: `Contains`
   * **String**: `:`

7. Select **Save**.

8. Select **Groups**, **All groups**, then **New group** to create your group(s).

9. Assign users to the group(s) that you create.

The next time you sync your groups with Docker, your users will map to the Docker groups you defined.

## [Configure group mapping with SCIM](#configure-group-mapping-with-scim)

Use group mapping with SCIM for more advanced user lifecycle management. Before you begin, make sure you [set up SCIM](https://docs.docker.com/enterprise/security/provisioning/scim/provision-scim/#enable-scim) first.

The user interface for your IdP may differ slightly from the following steps. Refer to the [Okta documentation](https://help.okta.com/en-us/Content/Topics/users-groups-profiles/usgp-enable-group-push.htm) to verify.

To set up your groups:

1. Sign in to Okta and open your application.

2. Select **Applications**, then **Provisioning**, and **Integration**.

3. Select **Edit** to enable groups on your connection, then select **Push groups**.

4. Select **Save**. Saving this configuration will add the **Push Groups** tab to your application.

5. Create your groups by navigating to **Directory** and selecting **Groups**.

6. Add your groups using the format `organization:team` that matches the names of your organization(s) and team(s) in Docker.

7. Assign users to the group(s) that you create.

8. Return to the **Integration** page, then select the **Push Groups** tab to open the view where you can control and manage how groups are provisioned.

9. Select **Push Groups**, then **Find groups by rule**.

10. Configure the groups by rule like the following:

    * Enter a rule name, for example `Sync groups with Docker Hub`
    * Match group by name, for example starts with `docker:` or contains `:` for multi-organization
    * If you enable **Immediately push groups by rule**, sync will happen as soon as there's a change to the group or group assignments. Enable this if you don't want to manually push groups.

Find your new rule under **By rule** in the **Pushed Groups** column. The groups that match that rule are listed in the groups table on the right-hand side.

To push the groups from this table:

1. Select **Group in Okta**.
2. Select the **Push Status** drop-down.
3. Select **Push Now**.

The user interface for your IdP may differ slightly from the following steps. Refer to the [Entra ID documentation](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/customize-application-attributes) to verify.

Complete the following before configuring group mapping:

1. Sign in to Entra ID and go to your application.
2. In your application, select **Provisioning**, then **Mappings**.
3. Select **Provision Microsoft Entra ID Groups**.
4. Select **Show advanced options**, then **Edit attribute list**.
5. Update the `externalId` type to `reference`, then select the **Multi-Value** checkbox and choose the referenced object attribute `urn:ietf:params:scim:schemas:core:2.0:Group`.
6. Select **Save**, then **Yes** to confirm.
7. Go to **Provisioning**.
8. Toggle **Provision Status** to **On**, then select **Save**.

Next, set up group mapping:

1. Go to the application overview page.
2. Under **Provision user accounts**, select **Get started**.
3. Select **Add user/group**.
4. Create your group(s) using the `organization:team` format.
5. Assign the group to the provisioning group.
6. Select **Start provisioning** to start the sync.

To verify, select **Monitor**, then **Provisioning logs** to see that your groups were provisioned successfully. In your Docker organization, you can check that the groups were correctly provisioned and the members were added to the appropriate teams.

Once complete, a user who signs in to Docker through SSO is automatically added to the organizations and teams mapped in the IdP.

> Tip
>
> [Enable SCIM](https://docs.docker.com/enterprise/security/provisioning/scim/provision-scim/) to take advantage of automatic user provisioning and de-provisioning. If you don't enable SCIM users are only automatically provisioned. You have to de-provision them manually.

## [Next steps](#next-steps)

* [Assign roles](https://docs.docker.com/enterprise/security/roles-and-permissions/core-roles/) to members of your org.
* [Enforce sign in](https://docs.docker.com/enterprise/security/enforce-sign-in/), if needed.

----
url: https://docs.docker.com/reference/cli/docker/mcp/tools/inspect/
----

# docker mcp tools inspect

***

| Description | Inspect a tool             |
| ----------- | -------------------------- |
| Usage       | `docker mcp tools inspect` |

## [Description](#description)

Inspect a tool

----
url: https://docs.docker.com/reference/cli/docker/scout/help/
----

# docker scout help

***

| Description | Display information about the available commands |
| ----------- | ------------------------------------------------ |
| Usage       | `docker scout help`                              |

## [Description](#description)

Display information about the available commands

----
url: https://docs.docker.com/docker-hub/repos/manage/builds/advanced/
----

# Advanced options for autobuild and autotest

***

Table of contents

***

> Warning
>
> Docker Hub Automated Builds is a deprecated feature. It will be fully retired on April 1, 2027.

> Note
>
> Automated builds require a Docker Pro, Team, or Business subscription.

The following options allow you to customize your automated build and automated test processes.

## [Environment variables for building and testing](#environment-variables-for-building-and-testing)

Several utility environment variables are set by the build process, and are available during automated builds, automated tests, and while executing hooks.

> Note
>
> These environment variables are only available to the build and test processes and don't affect your service's run environment.

* `SOURCE_BRANCH`: the name of the branch or the tag that is currently being tested.
* `SOURCE_COMMIT`: the SHA1 hash of the commit being tested.
* `COMMIT_MSG`: the message from the commit being tested and built.
* `DOCKER_REPO`: the name of the Docker repository being built.
* `DOCKERFILE_PATH`: the dockerfile currently being built.
* `DOCKER_TAG`: the Docker repository tag being built.
* `IMAGE_NAME`: the name and tag of the Docker repository being built. (This variable is a combination of `DOCKER_REPO`:`DOCKER_TAG`.)

If you are using these build environment variables in a `docker-compose.test.yml` file for automated testing, declare them in your `sut` service's environment as shown below.

```yaml
services:
  sut:
    build: .
    command: run_tests.sh
    environment:
      - SOURCE_BRANCH
```

## [Override build, test or push commands](#override-build-test-or-push-commands)

Docker Hub allows you to override and customize the `build`, `test` and `push` commands during automated build and test processes using hooks. For example, you might use a build hook to set build arguments used only during the build process. You can also set up [custom build phase hooks](#custom-build-phase-hooks) to perform actions in between these commands.

> Important
>
> Use these hooks with caution. The contents of these hook files replace the basic `docker` commands, so you must include a similar build, test or push command in the hook or your automated process does not complete.

To override these phases, create a folder called `hooks` in your source code repository at the same directory level as your Dockerfile. Create a file called `hooks/build`, `hooks/test`, or `hooks/push` and include commands that the builder process can execute, such as `docker` and `bash` commands (prefixed appropriately with `#!/bin/bash`).

These hooks run on an instance of [Ubuntu](https://releases.ubuntu.com/), which includes interpreters such as Perl or Python, and utilities such as `git` or `curl`. Refer to the [Ubuntu documentation](https://ubuntu.com/) for the full list of available interpreters and utilities.

## [Custom build phase hooks](#custom-build-phase-hooks)

You can run custom commands between phases of the build process by creating hooks. Hooks allow you to provide extra instructions to the autobuild and autotest processes.

Create a folder called `hooks` in your source code repository at the same directory level as your Dockerfile. Place files that define the hooks in that folder. Hook files can include both `docker` commands, and `bash` commands as long as they are prefixed appropriately with `#!/bin/bash`. The builder executes the commands in the files before and after each step.

The following hooks are available:

* `hooks/post_checkout`
* `hooks/pre_build`
* `hooks/post_build`
* `hooks/pre_test`
* `hooks/post_test`
* `hooks/pre_push` (only used when executing a build rule or [Automated build](https://docs.docker.com/docker-hub/repos/manage/builds/) )
* `hooks/post_push` (only used when executing a build rule or [Automated build](https://docs.docker.com/docker-hub/repos/manage/builds/) )

### [Build hook examples](#build-hook-examples)

#### [Override the "build" phase to set variables](#override-the-build-phase-to-set-variables)

Docker Hub allows you to define build environment variables either in the hook files, or from the automated build interface, which you can then reference in hooks.

The following example defines a build hook that uses `docker build` arguments to set the variable `CUSTOM` based on the value of variable defined using the Docker Hub build settings. `$DOCKERFILE_PATH` is a variable that you provide with the name of the Dockerfile you want to build, and `$IMAGE_NAME` is the name of the image being built.

```console
$ docker build --build-arg CUSTOM=$VAR -f $DOCKERFILE_PATH -t $IMAGE_NAME .
```

> Important
>
> A `hooks/build` file overrides the basic `docker build` command used by the builder, so you must include a similar build command in the hook or the automated build fails.

Refer to the [docker build documentation](/reference/cli/docker/buildx/build/#build-arg) to learn more about Docker build-time variables.

#### [Push to multiple repositories](#push-to-multiple-repositories)

By default the build process pushes the image only to the repository where the build settings are configured. If you need to push the same image to multiple repositories, you can set up a `post_push` hook to add additional tags and push to more repositories.

```console
$ docker tag $IMAGE_NAME $DOCKER_REPO:$SOURCE_COMMIT
$ docker push $DOCKER_REPO:$SOURCE_COMMIT
```

## [Source repository or branch clones](#source-repository-or-branch-clones)

When Docker Hub pulls a branch from a source code repository, it performs a shallow clone, it clones only the tip of the specified branch. This has the advantage of minimizing the amount of data transfer necessary from the repository and speeding up the build because it pulls only the minimal code necessary.

As a result, if you need to perform a custom action that relies on a different branch, such as a `post_push` hook, you can't checkout that branch unless you do one of the following:

* You can get a shallow checkout of the target branch by doing the following:

  ```console
  $ git fetch origin branch:mytargetbranch --depth 1
  ```

* You can also "unshallow" the clone, which fetches the whole Git history (and potentially takes a long time / moves a lot of data) by using the `--unshallow` flag on the fetch:

  ```console
  $ git fetch --unshallow origin
  ```

----
url: https://docs.docker.com/scout/how-tos/artifact-types/
----

# Use Scout with different artifact types

***

Table of contents

***

Some of the Docker Scout CLI commands support prefixes for specifying the location or type of artifact that you would like to analyze.

By default, image analysis with the `docker scout cves` command targets images in the local image store of the Docker Engine. The following command always uses a local image if it exists:

```console
$ docker scout cves <image>
```

If the image doesn't exist locally, Docker pulls the image before running the analysis. Analyzing the same image again would use the same local version by default, even if the tag has since changed in the registry.

By adding a `registry://` prefix to the image reference, you can force Docker Scout to analyze the registry version of the image:

```console
$ docker scout cves registry://<image>
```

## [Supported prefixes](#supported-prefixes)

The supported prefixes are:

| Prefix               | Description                                                          |
| -------------------- | -------------------------------------------------------------------- |
| `image://` (default) | Use a local image, or fall back to a registry lookup                 |
| `local://`           | Use an image from the local image store (don't do a registry lookup) |
| `registry://`        | Use an image from a registry (don't use a local image)               |
| `oci-dir://`         | Use an OCI layout directory                                          |
| `archive://`         | Use a tarball archive, as created by `docker save`                   |
| `fs://`              | Use a local directory or file                                        |

You can use prefixes with the following commands:

* `docker scout compare`
* `docker scout cves`
* `docker scout quickview`
* `docker scout recommendations`
* `docker scout sbom`

## [Examples](#examples)

This section contains a few examples showing how you can use prefixes to specify artifacts for `docker scout` commands.

### [Analyze a local project](#analyze-a-local-project)

The `fs://` prefix lets you analyze local source code directly, without having to build it into a container image. The following `docker scout quickview` command gives you an at-a-glance vulnerability summary of the source code in the current working directory:

```console
$ docker scout quickview fs://.
```

To view the details of vulnerabilities found in your local source code, you can use the `docker scout cves --details fs://.` command. Combine it with other flags to narrow down the results to the packages and vulnerabilities that you're interested in.

```console
$ docker scout cves --details --only-severity high fs://.
    ✓ File system read
    ✓ Indexed 323 packages
    ✗ Detected 1 vulnerable package with 1 vulnerability

​## Overview

                    │        Analyzed path
────────────────────┼──────────────────────────────
  Path              │  /Users/david/demo/scoutfs
    vulnerabilities │    0C     1H     0M     0L

​## Packages and Vulnerabilities

   0C     1H     0M     0L  fastify 3.29.0
pkg:npm/fastify@3.29.0

    ✗ HIGH CVE-2022-39288 [OWASP Top Ten 2017 Category A9 - Using Components with Known Vulnerabilities]
      https://scout.docker.com/v/CVE-2022-39288

      fastify is a fast and low overhead web framework, for Node.js. Affected versions of
      fastify are subject to a denial of service via malicious use of the Content-Type
      header. An attacker can send an invalid Content-Type header that can cause the
      application to crash. This issue has been addressed in commit  fbb07e8d  and will be
      included in release version 4.8.1. Users are advised to upgrade. Users unable to
      upgrade may manually filter out http content with malicious Content-Type headers.

      Affected range : <4.8.1
      Fixed version  : 4.8.1
      CVSS Score     : 7.5
      CVSS Vector    : CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H

1 vulnerability found in 1 package
  LOW       0
  MEDIUM    0
  HIGH      1
  CRITICAL  0
```

### [Compare a local project to an image](#compare-a-local-project-to-an-image)

With `docker scout compare`, you can compare the analysis of source code on your local filesystem with the analysis of a container image. The following example compares local source code (`fs://.`) with a registry image `registry://docker/scout-cli:latest`. In this case, both the baseline and target for the comparison use prefixes.

```console
$ docker scout compare fs://. --to registry://docker/scout-cli:latest --ignore-unchanged
WARN 'docker scout compare' is experimental and its behaviour might change in the future
    ✓ File system read
    ✓ Indexed 268 packages
    ✓ SBOM of image already cached, 234 packages indexed


  ## Overview

                           │              Analyzed File System              │              Comparison Image
  ─────────────────────────┼────────────────────────────────────────────────┼─────────────────────────────────────────────
    Path / Image reference │  /Users/david/src/docker/scout-cli-plugin      │  docker/scout-cli:latest
                           │                                                │  bb0b01303584
      platform             │                                                │ linux/arm64
      provenance           │ https://github.com/dvdksn/scout-cli-plugin.git │ https://github.com/docker/scout-cli-plugin
                           │  6ea3f7369dbdfec101ac7c0fa9d78ef05ffa6315      │  67cb4ef78bd69545af0e223ba5fb577b27094505
      vulnerabilities      │    0C     0H     1M     1L                     │    0C     0H     1M     1L
                           │                                                │
      size                 │ 7.4 MB (-14 MB)                                │ 21 MB
      packages             │ 268 (+34)                                      │ 234
                           │                                                │


  ## Packages and Vulnerabilities


    +   55 packages added
    -   21 packages removed
       213 packages unchanged
```

The previous example is truncated for brevity.

### [View the SBOM of an image tarball](#view-the-sbom-of-an-image-tarball)

The following example shows how you can use the `archive://` prefix to get the SBOM of an image tarball, created with `docker save`. The image in this case is `docker/scout-cli:latest`, and the SBOM is exported to file `sbom.spdx.json` in SPDX format.

```console
$ docker pull docker/scout-cli:latest
latest: Pulling from docker/scout-cli
257973a141f5: Download complete 
1f2083724dd1: Download complete 
5c8125a73507: Download complete 
Digest: sha256:13318bb059b0f8b0b87b35ac7050782462b5d0ac3f96f9f23d165d8ed68d0894
$ docker save docker/scout-cli:latest -o scout-cli.tar
$ docker scout sbom --format spdx -o sbom.spdx.json archive://scout-cli.tar
```

## [Learn more](#learn-more)

Read about the commands and supported flags in the CLI reference documentation:

* [`docker scout quickview`](/reference/cli/docker/scout/quickview/)
* [`docker scout cves`](/reference/cli/docker/scout/cves/)
* [`docker scout compare`](/reference/cli/docker/scout/compare/)

----
url: https://docs.docker.com/engine/daemon/ipv6/
----

# Use IPv6 networking

***

Table of contents

***

IPv6 is only supported on Docker daemons running on Linux hosts.

## [Create an IPv6 network](#create-an-ipv6-network)

* Using `docker network create`:

  ```console
  $ docker network create --ipv6 ip6net
  ```

* Using `docker network create`, specifying an IPv6 subnet:

  ```console
  $ docker network create --ipv6 --subnet 2001:db8::/64 ip6net
  ```

* Using a Docker Compose file:

  ```yaml
   networks:
     ip6net:
       enable_ipv6: true
       ipam:
         config:
           - subnet: 2001:db8::/64
  ```

> Note
>
> The address `2001:db8::/64` in these examples is [reserved for use in documentation](https://en.wikipedia.org/wiki/Reserved_IP_addresses#IPv6). Replace it with a valid IPv6 network, for example a [Unique Local Address (ULA)](https://en.wikipedia.org/wiki/Unique_local_address) subnet from `fd00::/8`.

You can now run containers that attach to the `ip6net` network.

```console
$ docker run --rm --network ip6net -p 80:80 traefik/whoami
```

This publishes port 80 on both IPv6 and IPv4. You can verify the IPv6 connection by running curl, connecting to port 80 on the IPv6 loopback address:

```console
$ curl http://[::1]:80
Hostname: ea1cfde18196
IP: 127.0.0.1
IP: ::1
IP: 172.17.0.2
IP: 2001:db8::2
IP: fe80::42:acff:fe11:2
RemoteAddr: [2001:db8::1]:37574
GET / HTTP/1.1
Host: [::1]
User-Agent: curl/8.1.2
Accept: */*
```

## [Use IPv6 for the default bridge network](#use-ipv6-for-the-default-bridge-network)

The following steps show you how to use IPv6 on the default bridge network.

1. Edit the Docker daemon configuration file, located at `/etc/docker/daemon.json`. Configure the following parameters:

   ```json
   {
     "ipv6": true,
     "fixed-cidr-v6": "2001:db8:1::/64"
   }
   ```

   > Note
   >
   > The address `2001:db8:1::/64` in this example is [reserved for use in documentation](https://en.wikipedia.org/wiki/Reserved_IP_addresses#IPv6). Replace it with a valid IPv6 network, for example a [Unique Local Address (ULA)](https://en.wikipedia.org/wiki/Unique_local_address) subnet from `fd00::/8`.

   * `ipv6` enables IPv6 networking on the default network.
   * `fixed-cidr-v6` assigns a subnet to the default bridge network, enabling dynamic IPv6 address allocation.
   * `ip6tables` enables additional IPv6 packet filter rules, providing network isolation and port mapping. It is enabled by-default, but can be disabled.

2. Save the configuration file.

3. Restart the Docker daemon for your changes to take effect.

   ```console
   $ sudo systemctl restart docker
   ```

You can now run containers on the default bridge network.

```console
$ docker run --rm -p 80:80 traefik/whoami
```

This publishes port 80 on both IPv6 and IPv4. You can verify the IPv6 connection by making a request to port 80 on the IPv6 loopback address:

```console
$ curl http://[::1]:80
Hostname: ea1cfde18196
IP: 127.0.0.1
IP: ::1
IP: 172.17.0.2
IP: 2001:db8:1::242:ac12:2
IP: fe80::42:acff:fe12:2
RemoteAddr: [2001:db8:1::1]:35558
GET / HTTP/1.1
Host: [::1]
User-Agent: curl/8.1.2
Accept: */*
```

## [Dynamic IPv6 subnet allocation](#dynamic-ipv6-subnet-allocation)

If you don't explicitly configure subnets for user-defined networks, using `docker network create --subnet=<your-subnet>`, those networks use the default address pools of the daemon as a fallback. This also applies to networks created from a Docker Compose file, with `enable_ipv6` set to `true`.

If no IPv6 pools are included in Docker Engine's `default-address-pools`, and no `--subnet` option is given, [Unique Local Addresses (ULAs)](https://en.wikipedia.org/wiki/Unique_local_address) will be used when IPv6 is enabled. These `/64` subnets include a 40-bit Global ID based on the Docker Engine's randomly generated ID, to give a high probability of uniqueness.

The built-in default address pool configuration is shown in [Subnet allocation](https://docs.docker.com/engine/network/#subnet-allocation). It does not include any IPv6 pools.

To use different pools of IPv6 subnets for dynamic address allocation, you must manually configure address pools of the daemon to include:

* The default IPv4 address pools
* One or more IPv6 pools of your own

The following example shows a valid configuration with IPv4 and IPv6 pools, both pools provide 256 subnets. IPv4 subnets with prefix length `/24` will be allocated from a `/16` pool. IPv6 subnets with prefix length `/64` will be allocated from a `/56` pool.

```json
{
  "default-address-pools": [
    { "base": "172.17.0.0/16", "size": 24 },
    { "base": "2001:db8::/56", "size": 64 }
  ]
}
```

> Note
>
> The address `2001:db8::` in this example is [reserved for use in documentation](https://en.wikipedia.org/wiki/Reserved_IP_addresses#IPv6). Replace it with a valid IPv6 network.
>
> The default IPv4 pools are from the private address range, similar to the default IPv6 [ULA](https://en.wikipedia.org/wiki/Unique_local_address) networks.

See [Subnet allocation](https://docs.docker.com/engine/network/#subnet-allocation) for more information about `default-address-pools`.

## [Docker in Docker](#docker-in-docker)

On a host using `xtables` (legacy `iptables`) instead of `nftables`, kernel module `ip6_tables` must be loaded before an IPv6 Docker network can be created, It is normally loaded automatically when Docker starts.

However, if you running Docker in Docker that is not based on a recent version of the [official `docker` image](https://hub.docker.com/_/docker), you may need to run `modprobe ip6_tables` on your host. Alternatively, use daemon option `--ip6tables=false` to disable `ip6tables` for the containerized Docker Engine.

## [Next steps](#next-steps)

* [Networking overview](https://docs.docker.com/engine/network/)

----
url: https://docs.docker.com/build/ci/github-actions/cache/
----

# Cache management with GitHub Actions

***

Table of contents

***

This page contains examples on using the cache storage backends with GitHub Actions.

> Note
>
> See [Cache storage backends](https://docs.docker.com/build/cache/backends/) for more details about cache storage backends.

## [Inline cache](#inline-cache)

In most cases you want to use the [inline cache exporter](https://docs.docker.com/build/cache/backends/inline/). However, note that the `inline` cache exporter only supports `min` cache mode. To use `max` cache mode, push the image and the cache separately using the registry cache exporter with the `cache-to` option, as shown in the [registry cache example](#registry-cache).

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:latest
          cache-to: type=inline
```

## [Registry cache](#registry-cache)

You can import/export cache from a cache manifest or (special) image configuration on the registry with the [registry cache exporter](https://docs.docker.com/build/cache/backends/registry/).

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=registry,ref=user/app:buildcache
          cache-to: type=registry,ref=user/app:buildcache,mode=max
```

## [GitHub cache](#github-cache)

### [Cache backend API](#cache-backend-api)

Availability: Experimental

The [GitHub Actions cache exporter](https://docs.docker.com/build/cache/backends/gha/) backend uses the [GitHub Cache service API](https://github.com/tonistiigi/go-actions-cache) to fetch and upload cache blobs. That's why you should only use this cache backend in a GitHub Action workflow, as the `url` (`$ACTIONS_RESULTS_URL`) and `token` (`$ACTIONS_RUNTIME_TOKEN`) attributes only get populated in a workflow context.

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=gha
          cache-to: type=gha,mode=max
```

> Important
>
> As of April 15th, 2025, [only GitHub Cache service API v2 is supported.](https://gh.io/gha-cache-sunset). The legacy v1 API has been shut down.
>
> If you encounter the following error during your build:
>
> ```console
> ERROR: failed to solve: This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP. For more information: https://gh.io/gha-cache-sunset
> ```
>
> You're probably using outdated tools that only support the legacy GitHub Cache service API v1. Here are the minimum versions you need to upgrade to depending on your use case:
>
> * Docker Buildx >= v0.21.0
> * BuildKit >= v0.20.0
> * Docker Compose >= v2.33.1
> * Docker Engine >= v28.0.0 (if you're building using the Docker driver with containerd image store enabled)
>
> If you're building using the `docker/build-push-action` or `docker/bake-action` actions on GitHub hosted runners, Docker Buildx and BuildKit are already up to date but on self-hosted runners, you may need to update them yourself. Alternatively, you can use the `docker/setup-buildx-action` action to install the latest version of Docker Buildx:
>
> ```yaml
> - name: Set up Docker Buildx
>   uses: docker/setup-buildx-action@v4
>   with:
>    version: latest
> ```
>
> If you're building using Docker Compose, you can use the `docker/setup-compose-action` action:
>
> ```yaml
> - name: Set up Docker Compose
>   uses: docker/setup-compose-action@v2
>   with:
>    version: latest
> ```
>
> If you're building using the Docker Engine with the containerd image store enabled, you can use the `docker/setup-docker-action` action:
>
> ```yaml
> -
>   name: Set up Docker
>   uses: docker/setup-docker-action@v5
>   with:
>     version: latest
>     daemon-config: |
>       {
>         "features": {
>           "containerd-snapshotter": true
>         }
>       }
> ```

### [Cache mounts](#cache-mounts)

BuildKit doesn't preserve cache mounts in the GitHub Actions cache by default. To put your cache mounts into GitHub Actions cache and reuse it between builds, you can use a workaround provided by [`reproducible-containers/buildkit-cache-dance`](https://github.com/reproducible-containers/buildkit-cache-dance).

This GitHub Action creates temporary containers to extract and inject the cache mount data with your Docker build steps.

The following example shows how to use this workaround with a Go project.

Example Dockerfile in `build/package/Dockerfile`

```Dockerfile
FROM golang:1.21.1-alpine as base-build

WORKDIR /build

RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=bind,source=go.mod,target=go.mod \
    --mount=type=bind,source=go.sum,target=go.sum \
    go mod download

RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    --mount=type=bind,target=. \
    go build -o /bin/app ./src
...
```

Example CI action

```yaml
name: ci

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Docker meta
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: user/app
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Go Build Cache for Docker
        uses: actions/cache@v5
        with:
          path: go-build-cache
          key: ${{ runner.os }}-go-build-cache-${{ hashFiles('**/go.sum') }}

      - name: Inject go-build-cache
        uses: reproducible-containers/buildkit-cache-dance@4b2444fec0c0fb9dbf175a96c094720a692ef810 # v2.1.4
        with:
          cache-source: go-build-cache

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          cache-from: type=gha
          cache-to: type=gha,mode=max
          file: build/package/Dockerfile
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          platforms: linux/amd64,linux/arm64
```

For more information about this workaround, refer to the [GitHub repository](https://github.com/reproducible-containers/buildkit-cache-dance).

### [Local cache](#local-cache)

> Warning
>
> At the moment, old cache entries aren't deleted, so the cache size [keeps growing](https://github.com/docker/build-push-action/issues/252). The following example uses the `Move cache` step as a workaround (see [`moby/buildkit#1896`](https://github.com/moby/buildkit/issues/1896) for more info).

You can also leverage [GitHub cache](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) using the [actions/cache](https://github.com/actions/cache) and [local cache exporter](https://docs.docker.com/build/cache/backends/local/) with this action:

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Cache Docker layers
        uses: actions/cache@v5
        with:
          path: ${{ runner.temp }}/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-buildx-

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest
          cache-from: type=local,src=${{ runner.temp }}/.buildx-cache
          cache-to: type=local,dest=${{ runner.temp }}/.buildx-cache-new,mode=max

      - # Temp fix
        # https://github.com/docker/build-push-action/issues/252
        # https://github.com/moby/buildkit/issues/1896
        name: Move cache
        run: |
          rm -rf ${{ runner.temp }}/.buildx-cache
          mv ${{ runner.temp }}/.buildx-cache-new ${{ runner.temp }}/.buildx-cache
```

----
url: https://docs.docker.com/engine/storage/drivers/
----

# Storage drivers

***

Table of contents

***

> Note
>
> Docker Engine 29.0 and later uses the [containerd image store](https://docs.docker.com/engine/storage/containerd/) by default for fresh installations. The containerd image store uses snapshotters instead of the classic storage drivers described on this page. If you're running a fresh installation of Docker Engine 29.0 or later, or if you've migrated to the containerd image store, this page provides background on how image layers work but the implementation details differ. For information about the containerd image store, see [containerd image store](https://docs.docker.com/engine/storage/containerd/).

To use storage drivers effectively, it's important to know how Docker builds and stores images, and how these images are used by containers. You can use this information to make informed choices about the best way to persist data from your applications and avoid performance problems along the way.

## [Storage drivers versus Docker volumes](#storage-drivers-versus-docker-volumes)

Docker uses storage drivers to store image layers, and to store data in the writable layer of a container. The container's writable layer doesn't persist after the container is deleted, but is suitable for storing ephemeral data that is generated at runtime. Storage drivers are optimized for space efficiency, but (depending on the storage driver) write speeds are lower than native file system performance, especially for storage drivers that use a copy-on-write filesystem. Write-intensive applications, such as database storage, are impacted by a performance overhead, particularly if pre-existing data exists in the read-only layer.

Use Docker volumes for write-intensive data, data that must persist beyond the container's lifespan, and data that must be shared between containers. Refer to the [volumes section](https://docs.docker.com/engine/storage/volumes/) to learn how to use volumes to persist data and improve performance.

## [Images and layers](#images-and-layers)

A Docker image is built up from a series of layers. Each layer represents an instruction in the image's Dockerfile. Each layer except the very last one is read-only. Consider the following Dockerfile:

```dockerfile
# syntax=docker/dockerfile:1

FROM ubuntu:22.04
LABEL org.opencontainers.image.authors="org@example.com"
COPY . /app
RUN make /app
RUN rm -r $HOME/.cache
CMD python /app/app.py
```

This Dockerfile contains four commands. Commands that modify the filesystem create a new layer. The `FROM` statement starts out by creating a layer from the `ubuntu:22.04` image. The `LABEL` command only modifies the image's metadata, and doesn't produce a new layer. The `COPY` command adds some files from your Docker client's current directory. The first `RUN` command builds your application using the `make` command, and writes the result to a new layer. The second `RUN` command removes a cache directory, and writes the result to a new layer. Finally, the `CMD` instruction specifies what command to run within the container, which only modifies the image's metadata, which doesn't produce an image layer.

Each layer is only a set of differences from the layer before it. Note that both *adding*, and *removing* files will result in a new layer. In the example above, the `$HOME/.cache` directory is removed, but will still be available in the previous layer and add up to the image's total size. Refer to the [Best practices for writing Dockerfiles](https://docs.docker.com/build/building/best-practices/) and [use multi-stage builds](https://docs.docker.com/build/building/multi-stage/) sections to learn how to optimize your Dockerfiles for efficient images.

The layers are stacked on top of each other. When you create a new container, you add a new writable layer on top of the underlying layers. This layer is often called the "container layer". All changes made to the running container, such as writing new files, modifying existing files, and deleting files, are written to this thin writable container layer. The diagram below shows a container based on an `ubuntu:15.04` image.

A storage driver handles the details about the way these layers interact with each other. Different storage drivers are available, which have advantages and disadvantages in different situations.

## [Container and layers](#container-and-layers)

The major difference between a container and an image is the top writable layer. All writes to the container that add new or modify existing data are stored in this writable layer. When the container is deleted, the writable layer is also deleted. The underlying image remains unchanged.

Because each container has its own writable container layer, and all changes are stored in this container layer, multiple containers can share access to the same underlying image and yet have their own data state. The diagram below shows multiple containers sharing the same Ubuntu 15.04 image.

Docker uses storage drivers to manage the contents of the image layers and the writable container layer. Each storage driver handles the implementation differently, but all drivers use stackable image layers and the copy-on-write (CoW) strategy.

> Note
>
> Use Docker volumes if you need multiple containers to have shared access to the exact same data. Refer to the [volumes section](https://docs.docker.com/engine/storage/volumes/) to learn about volumes.

## [Container size on disk](#container-size-on-disk)

To view the approximate size of a running container, you can use the `docker ps -s` command. Two different columns relate to size.

* `size`: the amount of data (on disk) that's used for the writable layer of each container.
* `virtual size`: the amount of data used for the read-only image data used by the container plus the container's writable layer `size`. Multiple containers may share some or all read-only image data. Two containers started from the same image share 100% of the read-only data, while two containers with different images which have layers in common share those common layers. Therefore, you can't just total the virtual sizes. This over-estimates the total disk usage by a potentially non-trivial amount.

The total disk space used by all of the running containers on disk is some combination of each container's `size` and the `virtual size` values. If multiple containers started from the same exact image, the total size on disk for these containers would be SUM (`size` of containers) plus one image size (`virtual size` - `size`).

This also doesn't count the following additional ways a container can take up disk space:

* Disk space used for log files stored by the [logging-driver](https://docs.docker.com/engine/logging/). This can be non-trivial if your container generates a large amount of logging data and log rotation isn't configured.
* Volumes and bind mounts used by the container.
* Disk space used for the container's configuration files, which are typically small.
* Memory written to disk (if swapping is enabled).
* Checkpoints, if you're using the experimental checkpoint/restore feature.

## [The copy-on-write (CoW) strategy](#the-copy-on-write-cow-strategy)

Copy-on-write is a strategy of sharing and copying files for maximum efficiency. If a file or directory exists in a lower layer within the image, and another layer (including the writable layer) needs read access to it, it just uses the existing file. The first time another layer needs to modify the file (when building the image or running the container), the file is copied into that layer and modified. This minimizes I/O and the size of each of the subsequent layers. These advantages are explained in more depth below.

### [Sharing promotes smaller images](#sharing-promotes-smaller-images)

When you use `docker pull` to pull down an image from a repository, or when you create a container from an image that doesn't yet exist locally, each layer is pulled down separately, and stored in Docker's local storage area, which is usually `/var/lib/docker/` on Linux hosts. You can see these layers being pulled in this example:

```console
$ docker pull ubuntu:22.04
22.04: Pulling from library/ubuntu
f476d66f5408: Pull complete
8882c27f669e: Pull complete
d9af21273955: Pull complete
f5029279ec12: Pull complete
Digest: sha256:6120be6a2b7ce665d0cbddc3ce6eae60fe94637c6a66985312d1f02f63cc0bcd
Status: Downloaded newer image for ubuntu:22.04
docker.io/library/ubuntu:22.04
```

Each of these layers is stored in its own directory inside the Docker host's local storage area. To examine the layers on the filesystem, list the contents of `/var/lib/docker/<storage-driver>`. This example uses the `overlay2` storage driver:

```console
$ ls /var/lib/docker/overlay2
16802227a96c24dcbeab5b37821e2b67a9f921749cd9a2e386d5a6d5bc6fc6d3
377d73dbb466e0bc7c9ee23166771b35ebdbe02ef17753d79fd3571d4ce659d7
3f02d96212b03e3383160d31d7c6aeca750d2d8a1879965b89fe8146594c453d
ec1ec45792908e90484f7e629330666e7eee599f08729c93890a7205a6ba35f5
l
```

The directory names don't correspond to the layer IDs.

Now imagine that you have two different Dockerfiles. You use the first one to create an image called `acme/my-base-image:1.0`.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN apk add --no-cache bash
```

The second one is based on `acme/my-base-image:1.0`, but has some additional layers:

```dockerfile
# syntax=docker/dockerfile:1
FROM acme/my-base-image:1.0
COPY . /app
RUN chmod +x /app/hello.sh
CMD /app/hello.sh
```

The second image contains all the layers from the first image, plus new layers created by the `COPY` and `RUN` instructions, and a read-write container layer. Docker already has all the layers from the first image, so it doesn't need to pull them again. The two images share any layers they have in common.

If you build images from the two Dockerfiles, you can use `docker image ls` and `docker image history` commands to verify that the cryptographic IDs of the shared layers are the same.

1. Make a new directory `cow-test/` and change into it.

2. Within `cow-test/`, create a new file called `hello.sh` with the following contents.

   ```bash
   #!/usr/bin/env bash
   echo "Hello world"
   ```

3. Copy the contents of the first Dockerfile above into a new file called `Dockerfile.base`.

4. Copy the contents of the second Dockerfile above into a new file called `Dockerfile`.

5. Within the `cow-test/` directory, build the first image. Don't forget to include the final `.` in the command. That sets the `PATH`, which tells Docker where to look for any files that need to be added to the image.

   ```console
   $ docker build -t acme/my-base-image:1.0 -f Dockerfile.base .
   [+] Building 6.0s (11/11) FINISHED
   => [internal] load build definition from Dockerfile.base                                      0.4s
   => => transferring dockerfile: 116B                                                           0.0s
   => [internal] load .dockerignore                                                              0.3s
   => => transferring context: 2B                                                                0.0s
   => resolve image config for docker.io/docker/dockerfile:1                                     1.5s
   => [auth] docker/dockerfile:pull token for registry-1.docker.io                               0.0s
   => CACHED docker-image://docker.io/docker/dockerfile:1@sha256:9e2c9eca7367393aecc68795c671... 0.0s
   => [internal] load .dockerignore                                                              0.0s
   => [internal] load build definition from Dockerfile.base                                      0.0s
   => [internal] load metadata for docker.io/library/alpine:latest                               0.0s
   => CACHED [1/2] FROM docker.io/library/alpine                                                 0.0s
   => [2/2] RUN apk add --no-cache bash                                                          3.1s
   => exporting to image                                                                         0.2s
   => => exporting layers                                                                        0.2s
   => => writing image sha256:da3cf8df55ee9777ddcd5afc40fffc3ead816bda99430bad2257de4459625eaa   0.0s
   => => naming to docker.io/acme/my-base-image:1.0                                              0.0s
   ```

6. Build the second image.

   ```console
   $ docker build -t acme/my-final-image:1.0 -f Dockerfile .

   [+] Building 3.6s (12/12) FINISHED
   => [internal] load build definition from Dockerfile                                            0.1s
   => => transferring dockerfile: 156B                                                            0.0s
   => [internal] load .dockerignore                                                               0.1s
   => => transferring context: 2B                                                                 0.0s
   => resolve image config for docker.io/docker/dockerfile:1                                      0.5s
   => CACHED docker-image://docker.io/docker/dockerfile:1@sha256:9e2c9eca7367393aecc68795c671...  0.0s
   => [internal] load .dockerignore                                                               0.0s
   => [internal] load build definition from Dockerfile                                            0.0s
   => [internal] load metadata for docker.io/acme/my-base-image:1.0                               0.0s
   => [internal] load build context                                                               0.2s
   => => transferring context: 340B                                                               0.0s
   => [1/3] FROM docker.io/acme/my-base-image:1.0                                                 0.2s
   => [2/3] COPY . /app                                                                           0.1s
   => [3/3] RUN chmod +x /app/hello.sh                                                            0.4s
   => exporting to image                                                                          0.1s
   => => exporting layers                                                                         0.1s
   => => writing image sha256:8bd85c42fa7ff6b33902ada7dcefaaae112bf5673873a089d73583b0074313dd    0.0s
   => => naming to docker.io/acme/my-final-image:1.0                                              0.0s
   ```

7. Check out the sizes of the images.

   ```console
   $ docker image ls

   REPOSITORY             TAG     IMAGE ID         CREATED               SIZE
   acme/my-final-image    1.0     8bd85c42fa7f     About a minute ago    7.75MB
   acme/my-base-image     1.0     da3cf8df55ee     2 minutes ago         7.75MB
   ```

8. Check out the history of each image.

   ```console
   $ docker image history acme/my-base-image:1.0

   IMAGE          CREATED         CREATED BY                                      SIZE      COMMENT
   da3cf8df55ee   5 minutes ago   RUN /bin/sh -c apk add --no-cache bash # bui…   2.15MB    buildkit.dockerfile.v0
   <missing>      7 weeks ago     /bin/sh -c #(nop)  CMD ["/bin/sh"]              0B
   <missing>      7 weeks ago     /bin/sh -c #(nop) ADD file:f278386b0cef68136…   5.6MB
   ```

   Some steps don't have a size (`0B`), and are metadata-only changes, which do not produce an image layer and don't take up any size, other than the metadata itself. The output above shows that this image consists of 2 image layers.

   ```console
   $ docker image history  acme/my-final-image:1.0

   IMAGE          CREATED         CREATED BY                                      SIZE      COMMENT
   8bd85c42fa7f   3 minutes ago   CMD ["/bin/sh" "-c" "/app/hello.sh"]            0B        buildkit.dockerfile.v0
   <missing>      3 minutes ago   RUN /bin/sh -c chmod +x /app/hello.sh # buil…   39B       buildkit.dockerfile.v0
   <missing>      3 minutes ago   COPY . /app # buildkit                          222B      buildkit.dockerfile.v0
   <missing>      4 minutes ago   RUN /bin/sh -c apk add --no-cache bash # bui…   2.15MB    buildkit.dockerfile.v0
   <missing>      7 weeks ago     /bin/sh -c #(nop)  CMD ["/bin/sh"]              0B
   <missing>      7 weeks ago     /bin/sh -c #(nop) ADD file:f278386b0cef68136…   5.6MB
   ```

   Notice that all steps of the first image are also included in the final image. The final image includes the two layers from the first image, and two layers that were added in the second image.

   The `<missing>` lines in the `docker history` output indicate that those steps were either built on another system and part of the `alpine` image that was pulled from Docker Hub, or were built with BuildKit as builder. Before BuildKit, the "classic" builder would produce a new "intermediate" image for each step for caching purposes, and the `IMAGE` column would show the ID of that image.

   BuildKit uses its own caching mechanism, and no longer requires intermediate images for caching. Refer to [BuildKit](https://docs.docker.com/build/buildkit/) to learn more about other enhancements made in BuildKit.

9. Check out the layers for each image

   Use the `docker image inspect` command to view the cryptographic IDs of the layers in each image:

   ```console
   $ docker image inspect --format "{{json .RootFS.Layers}}" acme/my-base-image:1.0
   [
     "sha256:72e830a4dff5f0d5225cdc0a320e85ab1ce06ea5673acfe8d83a7645cbd0e9cf",
     "sha256:07b4a9068b6af337e8b8f1f1dae3dd14185b2c0003a9a1f0a6fd2587495b204a"
   ]
   ```

   ```console
   $ docker image inspect --format "{{json .RootFS.Layers}}" acme/my-final-image:1.0
   [
     "sha256:72e830a4dff5f0d5225cdc0a320e85ab1ce06ea5673acfe8d83a7645cbd0e9cf",
     "sha256:07b4a9068b6af337e8b8f1f1dae3dd14185b2c0003a9a1f0a6fd2587495b204a",
     "sha256:cc644054967e516db4689b5282ee98e4bc4b11ea2255c9630309f559ab96562e",
     "sha256:e84fb818852626e89a09f5143dbc31fe7f0e0a6a24cd8d2eb68062b904337af4"
   ]
   ```

   Notice that the first two layers are identical in both images. The second image adds two additional layers. Shared image layers are only stored once in `/var/lib/docker/` and are also shared when pushing and pulling an image to an image registry. Shared image layers can therefore reduce network bandwidth and storage.

   > Tip
   >
   > Format output of Docker commands with the `--format` option.
   >
   > The examples above use the `docker image inspect` command with the `--format` option to view the layer IDs, formatted as a JSON array. The `--format` option on Docker commands can be a powerful feature that allows you to extract and format specific information from the output, without requiring additional tools such as `awk` or `sed`. To learn more about formatting the output of docker commands using the `--format` flag, refer to the [format command and log output section](https://docs.docker.com/engine/cli/formatting/). We also pretty-printed the JSON output using the [`jq` utility](https://stedolan.github.io/jq/) for readability.

### [Copying makes containers efficient](#copying-makes-containers-efficient)

When you start a container, a thin writable container layer is added on top of the other layers. Any changes the container makes to the filesystem are stored here. Any files the container doesn't change don't get copied to this writable layer. This means that the writable layer is as small as possible.

When an existing file in a container is modified, the storage driver performs a copy-on-write operation. The specific steps involved depend on the specific storage driver. For the `overlay2` driver, the copy-on-write operation follows this rough sequence:

* Search through the image layers for the file to update. The process starts at the newest layer and works down to the base layer one layer at a time. When results are found, they're added to a cache to speed future operations.
* Perform a `copy_up` operation on the first copy of the file that's found, to copy the file to the container's writable layer.
* Any modifications are made to this copy of the file, and the container can't see the read-only copy of the file that exists in the lower layer.

Btrfs, ZFS, and other drivers handle the copy-on-write differently. You can read more about the methods of these drivers later in their detailed descriptions.

Containers that write a lot of data consume more space than containers that don't. This is because most write operations consume new space in the container's thin writable top layer. Note that changing the metadata of files, for example, changing file permissions or ownership of a file, can also result in a `copy_up` operation, therefore duplicating the file to the writable layer.

> Tip
>
> Use volumes for write-heavy applications.
>
> Don't store the data in the container for write-heavy applications. Such applications, for example write-intensive databases, are known to be problematic particularly when pre-existing data exists in the read-only layer.
>
> Instead, use Docker volumes, which are independent of the running container, and designed to be efficient for I/O. In addition, volumes can be shared among containers and don't increase the size of your container's writable layer. Refer to the [use volumes](https://docs.docker.com/engine/storage/volumes/) section to learn about volumes.

A `copy_up` operation can incur a noticeable performance overhead. This overhead is different depending on which storage driver is in use. Large files, lots of layers, and deep directory trees can make the impact more noticeable. This is mitigated by the fact that each `copy_up` operation only occurs the first time a given file is modified.

To verify the way that copy-on-write works, the following procedure spins up 5 containers based on the `acme/my-final-image:1.0` image we built earlier and examines how much room they take up.

1. From a terminal on your Docker host, run the following `docker run` commands. The strings at the end are the IDs of each container.

   ```console
   $ docker run -dit --name my_container_1 acme/my-final-image:1.0 bash \
     && docker run -dit --name my_container_2 acme/my-final-image:1.0 bash \
     && docker run -dit --name my_container_3 acme/my-final-image:1.0 bash \
     && docker run -dit --name my_container_4 acme/my-final-image:1.0 bash \
     && docker run -dit --name my_container_5 acme/my-final-image:1.0 bash

   40ebdd7634162eb42bdb1ba76a395095527e9c0aa40348e6c325bd0aa289423c
   a5ff32e2b551168b9498870faf16c9cd0af820edf8a5c157f7b80da59d01a107
   3ed3c1a10430e09f253704116965b01ca920202d52f3bf381fbb833b8ae356bc
   939b3bf9e7ece24bcffec57d974c939da2bdcc6a5077b5459c897c1e2fa37a39
   cddae31c314fbab3f7eabeb9b26733838187abc9a2ed53f97bd5b04cd7984a5a
   ```

2. Run the `docker ps` command with the `--size` option to verify the 5 containers are running, and to see each container's size.

   ```console
   $ docker ps --size --format "table {{.ID}}\t{{.Image}}\t{{.Names}}\t{{.Size}}"

   CONTAINER ID   IMAGE                     NAMES            SIZE
   cddae31c314f   acme/my-final-image:1.0   my_container_5   0B (virtual 7.75MB)
   939b3bf9e7ec   acme/my-final-image:1.0   my_container_4   0B (virtual 7.75MB)
   3ed3c1a10430   acme/my-final-image:1.0   my_container_3   0B (virtual 7.75MB)
   a5ff32e2b551   acme/my-final-image:1.0   my_container_2   0B (virtual 7.75MB)
   40ebdd763416   acme/my-final-image:1.0   my_container_1   0B (virtual 7.75MB)
   ```

   The output above shows that all containers share the image's read-only layers (7.75MB), but no data was written to the container's filesystem, so no additional storage is used for the containers.

   > Note
   >
   > This step requires a Linux machine, and doesn't work on Docker Desktop, as it requires access to the Docker Daemon's file storage.

   While the output of `docker ps` provides you information about disk space consumed by a container's writable layer, it doesn't include information about metadata and log-files stored for each container.

   More details can be obtained by exploring the Docker Daemon's storage location (`/var/lib/docker` by default).

   ```console
   $ sudo du -sh /var/lib/docker/containers/*

   36K  /var/lib/docker/containers/3ed3c1a10430e09f253704116965b01ca920202d52f3bf381fbb833b8ae356bc
   36K  /var/lib/docker/containers/40ebdd7634162eb42bdb1ba76a395095527e9c0aa40348e6c325bd0aa289423c
   36K  /var/lib/docker/containers/939b3bf9e7ece24bcffec57d974c939da2bdcc6a5077b5459c897c1e2fa37a39
   36K  /var/lib/docker/containers/a5ff32e2b551168b9498870faf16c9cd0af820edf8a5c157f7b80da59d01a107
   36K  /var/lib/docker/containers/cddae31c314fbab3f7eabeb9b26733838187abc9a2ed53f97bd5b04cd7984a5a
   ```

   Each of these containers only takes up 36k of space on the filesystem.

3. Per-container storage

   To demonstrate this, run the following command to write the word 'hello' to a file on the container's writable layer in containers `my_container_1`, `my_container_2`, and `my_container_3`:

   ```console
   $ for i in {1..3}; do docker exec my_container_$i sh -c 'printf hello > /out.txt'; done
   ```

   Running the `docker ps` command again afterward shows that those containers now consume 5 bytes each. This data is unique to each container, and not shared. The read-only layers of the containers aren't affected, and are still shared by all containers.

   ```console
   $ docker ps --size --format "table {{.ID}}\t{{.Image}}\t{{.Names}}\t{{.Size}}"

   CONTAINER ID   IMAGE                     NAMES            SIZE
   cddae31c314f   acme/my-final-image:1.0   my_container_5   0B (virtual 7.75MB)
   939b3bf9e7ec   acme/my-final-image:1.0   my_container_4   0B (virtual 7.75MB)
   3ed3c1a10430   acme/my-final-image:1.0   my_container_3   5B (virtual 7.75MB)
   a5ff32e2b551   acme/my-final-image:1.0   my_container_2   5B (virtual 7.75MB)
   40ebdd763416   acme/my-final-image:1.0   my_container_1   5B (virtual 7.75MB)
   ```

The previous examples illustrate how copy-on-write filesystems help make containers efficient. Not only does copy-on-write save space, but it also reduces container start-up time. When you create a container (or multiple containers from the same image), Docker only needs to create the thin writable container layer.

If Docker had to make an entire copy of the underlying image stack each time it created a new container, container creation times and disk space used would be significantly increased. This would be similar to the way that virtual machines work, with one or more virtual disks per virtual machine. The [`vfs` storage](https://docs.docker.com/engine/storage/drivers/vfs-driver/) doesn't provide a CoW filesystem or other optimizations. When using this storage driver, a full copy of the image's data is created for each container.

## [Related information](#related-information)

* [Volumes](https://docs.docker.com/engine/storage/volumes/)
* [Select a storage driver](https://docs.docker.com/engine/storage/drivers/select-storage-driver/)

----
url: https://docs.docker.com/compose/gettingstarted/
----

# Docker Compose Quickstart

***

Table of contents

***

This tutorial aims to introduce fundamental concepts of Docker Compose by guiding you through the development of a basic Python web application.

Using the Flask framework, the application features a hit counter in Redis, providing a practical example of how Docker Compose can be applied in web development scenarios. The concepts demonstrated here should be understandable even if you're not familiar with Python.

## [Prerequisites](#prerequisites)

Make sure you have:

* [Installed the latest version of Docker Compose](https://docs.docker.com/compose/install/)
* A basic understanding of Docker concepts and how Docker works

## [Step 1: Set up the project](#step-1-set-up-the-project)

1. Create a directory for the project:

   ```console
   $ mkdir compose-demo
   $ cd compose-demo
   ```

2. Create `app.py` in your project directory and add the following:

   ```python
   import os
   import redis
   from flask import Flask

   app = Flask(__name__)
   cache = redis.Redis(
       host=os.getenv("REDIS_HOST", "redis"),
       port=int(os.getenv("REDIS_PORT", "6379")),
   )

   @app.route("/")
   def hello():
       count = cache.incr("hits")
       return f"Hello from Docker! I have been seen {count} time(s).\n"
   ```

   The app reads its Redis connection details from environment variables, with sensible defaults so it works out of the box.

3. Create `requirements.txt` in your project directory and add the following:

   ```text
   flask
   redis
   ```

4. Create a `Dockerfile`:

   ```dockerfile
   # syntax=docker/dockerfile:1
   FROM python:3.12-alpine  # Builds an image with the Python 3.12 image
   WORKDIR /code  # Sets the working directory to `/code`
   ENV FLASK_APP=app.py  # Sets environment variables used by the `flask` command
   ENV FLASK_RUN_HOST=0.0.0.0
   RUN apk add --no-cache gcc musl-dev linux-headers  # Installs `gcc` and other dependencies
   COPY requirements.txt .  # Copies `requirements.txt`
   RUN pip install -r requirements.txt  # Installs the Python dependencies
   COPY . .  # Copies the current directory `.` in the project to the workdir `.` in the image
   EXPOSE 5000
   CMD ["flask", "run", "--debug"]  # Sets the default command for the container to `flask run --debug`
   ```

   > Important
   >
   > Make sure the file is named `Dockerfile` with no extension. Some editors add `.txt` automatically, which causes the build to fail.

   For more information on how to write Dockerfiles, see the [Dockerfile reference](/reference/dockerfile/).

5. Create a `.env` file to hold configuration values:

   ```text
   APP_PORT=8000
   REDIS_HOST=redis
   REDIS_PORT=6379
   ```

   Compose automatically reads `.env` and makes these values available for interpolation in your `compose.yaml`. For this example the gains are modest, but in practice, keeping configuration out of the Compose file makes it easier to:

   * Change values across environments without editing YAML
   * Avoid committing secrets to version control
   * Reuse values across multiple services

6. Create a `.dockerignore` file to keep unnecessary files out of your build context:

   ```text
   .env
   *.pyc
   __pycache__
   redis-data
   ```

   Docker sends everything in your project directory to the daemon when it builds an image. Without `.dockerignore`, that includes your `.env` file (which may contain secrets) and any cached Python bytecode. Excluding them keeps builds fast and avoids accidentally baking sensitive values into an image layer.

## [Step 2: Define and start your services](#step-2-define-and-start-your-services)

Compose simplifies the control of your entire application stack, making it easy to manage services, networks, and volumes in a single YAML configuration file.

1. Create `compose.yaml` in your project directory and paste the following:

   ```yaml
   services:
     web:
       build: .
       ports:
         - "${APP_PORT}:5000"
       environment:
         - REDIS_HOST=${REDIS_HOST}
         - REDIS_PORT=${REDIS_PORT}

     redis:
       image: redis:alpine
   ```

   This Compose file defines two services:

   * The `web` service uses an image that's built from the `Dockerfile` in the current directory. It maps port `8000` on the host to port `5000` on the container where Flask listens by default.

   * The `redis` service uses a public [Redis](https://registry.hub.docker.com/_/redis/) image pulled from the Docker Hub registry.

   For more information on the `compose.yaml` file, see [How Compose works](https://docs.docker.com/compose/intro/compose-application-model/).

2. Start up your application:

   ```console
   $ docker compose up
   ```

   With a single command, you create and start all the services from your configuration file. Compose builds your web image, pulls the Redis image, and starts both containers.

3. Open `http://localhost:8000`. You should see:

   ```text
   Hello from Docker! I have been seen 1 time(s).
   ```

   Refresh the page — the counter increments on each visit.

   This minimal setup works, but it has two problems you'll fix in the next steps:

   * Startup race: `web` starts at the same time as `redis`. If Redis isn't ready yet, the Flask app fails to connect and crashes.
   * No persistence: If you run `docker compose down` followed by `docker compose up`, the counter resets to zero. `docker compose down` removes the containers, and with them any data written to the container's writable layer. `docker compose stop` preserves the containers so data survives, but you can't rely on that in production where containers are regularly replaced.

4. Stop the stack before moving on:

   ```console
   $ docker compose down
   ```

## [Step 3: Fix the startup race with health checks](#step-3-fix-the-startup-race-with-health-checks)

To fix the startup race, Compose needs to wait until `redis` is confirmed healthy before starting `web`.

1. Update `compose.yaml`:

   ```yaml
   services:
     web:
       build: .
       ports:
         - "${APP_PORT}:5000"
       environment:
         - REDIS_HOST=${REDIS_HOST}
         - REDIS_PORT=${REDIS_PORT}
       depends_on:
         redis:
           condition: service_healthy

     redis:
       image: redis:alpine
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         timeout: 3s
         retries: 5
         start_period: 10s
   ```

   The `healthcheck` block tells Compose how to test whether Redis is ready:

   * `test` is the command Compose runs inside the container to check its health. `redis-cli ping` connects to Redis and expects a `PONG` response — if it gets one, the container is healthy.
   * `start_period` gives Redis 10 seconds to initialize before health checks begin. Any failures during this window don't count toward the retry limit.
   * `interval` runs the check every 5 seconds after the start period has elapsed.
   * `timeout` gives each check 3 seconds to respond before treating it as a failure.
   * `retries` sets how many consecutive failures are allowed before Compose marks the container as unhealthy. With `interval: 5s` and `retries: 5`, Compose will wait up to 25 seconds before giving up.

2. Start the stack to confirm the ordering is fixed:

   ```console
   $ docker compose up
   ```

   You should see something similar to:

   ```text
   [+] Running 2/2
   ✔ Container compose-demo-redis-1  Healthy                       0.0s
   ```

3. Open `http://localhost:8000` to confirm the app is still working, then stop the stack before moving on:

   ```console
   $ docker compose down
   ```

## [Step 4: Enable Compose Watch for live updates](#step-4-enable-compose-watch-for-live-updates)

Without Compose Watch, every code change requires you to stop the stack, rebuild the image, and restart the containers. Compose Watch eliminates that cycle by automatically syncing changes into your running container as you save files.

1. Update `compose.yaml` to add the `develop.watch` block to the `web` service:

   ```yaml
   services:
     web:
       build: .
       ports:
         - "${APP_PORT}:5000"
       environment:
         - REDIS_HOST=${REDIS_HOST}
         - REDIS_PORT=${REDIS_PORT}
       depends_on:
         redis:
           condition: service_healthy
       develop:
         watch:
           - action: sync+restart
             path: .
             target: /code
           - action: rebuild
             path: requirements.txt

     redis:
       image: redis:alpine
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         timeout: 3s
         retries: 5
         start_period: 10s
   ```

   The `watch` block defines two rules:

   * The `sync+restart` action watches your project directory (`.`) on the host. When a file changes, Compose copies any changed files into `/code` inside the running container, then restarts the container. Because the container restarts with the updated files already in place, Flask starts up reading the new code directly — no manual rebuild or restart needed.
   * The `rebuild` action on `requirements.txt` triggers a full image rebuild whenever you add a new dependency, since installing packages requires rebuilding the image, not just syncing files.

2. Start the stack with Watch enabled:

   ```console
   $ docker compose up --watch
   ```

3. Make a live change. Open `app.py` and update the greeting:

   ```python
   return f"Hello from Compose Watch! I have been seen {count} time(s).\n"
   ```

4. Save the file. Compose Watch detects the change and syncs it immediately:

   ```text
   Syncing service "web" after changes were detected
   ```

5. Refresh `http://localhost:8000`. The updated greeting appears without any restart and the counter should still be incrementing.

6. Stop the stack before moving on:

   ```console
   $ docker compose down
   ```

   For more information on how Compose Watch works, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

## [Step 5: Persist data with named volumes](#step-5-persist-data-with-named-volumes)

Each time you stop and restart the stack the visit counter resets to zero. Redis data lives inside the container, so it disappears when the container is removed. A named volume fixes this by storing the data on the host, outside the container lifecycle.

1. Update `compose.yaml`:

   ```yaml
   services:
     web:
       build: .
       ports:
         - "${APP_PORT}:5000"
       environment:
         - REDIS_HOST=${REDIS_HOST}
         - REDIS_PORT=${REDIS_PORT}
       depends_on:
         redis:
           condition: service_healthy
       develop:
         watch:
           - action: sync+restart
             path: .
             target: /code
           - action: rebuild
             path: requirements.txt

     redis:
       image: redis:alpine
       volumes:
         - redis-data:/data
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         timeout: 3s
         retries: 5
         start_period: 10s

   volumes:
     redis-data:
   ```

   The `redis-data:/data` entry under `redis.volumes` mounts the named volume at `/data`, the path where Redis writes its data files. The top-level `volumes` key registers it with Docker so it persists between `compose down` and `compose up` cycles.

2. Start the stack with `docker compose up --watch` and refresh `http://localhost:8000` a few times to build up a count.

3. Tear down the stack with `docker compose down` and then bring it back up again with `docker compose up --watch`.

4. Open `http://localhost:8000` — the counter continues from where it left off.

5. Now reset the counter with `docker compose down -v`.

   The `-v` flag removes named volumes along with the containers. Use this intentionally — it permanently deletes the stored data.

## [Step 6: Structure your project with multiple Compose files](#step-6-structure-your-project-with-multiple-compose-files)

As applications grow, a single `compose.yaml` becomes harder to maintain. The `include` top-level element lets you split services across multiple files while keeping them part of the same application.

This is especially useful when different teams own different parts of the stack, or when you want to reuse infrastructure definitions across projects.

1. Create a new file in your project directory called `infra.yaml` and move the Redis service and volume into it:

   ```yaml
    services:
     redis:
       image: redis:alpine
       volumes:
         - redis-data:/data
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 5s
         timeout: 3s
         retries: 5
         start_period: 10s

   volumes:
     redis-data:
   ```

2. Update `compose.yaml` to include `infra.yaml`:

   ```yaml
   include:
      - path: ./infra.yaml
   services:
     web:
       build: .
       ports:
         - "${APP_PORT}:5000"
       environment:
         - REDIS_HOST=${REDIS_HOST}
         - REDIS_PORT=${REDIS_PORT}
       depends_on:
         redis:
           condition: service_healthy
       develop:
         watch:
           - action: sync+restart
             path: .
             target: /code
           - action: rebuild
             path: requirements.txt
   ```

3. Run the application to confirm everything still works:

   ```console
   $ docker compose up --watch
   ```

   Compose merges both files at startup. The `web` service can still reference `redis` by name because all included services share the same default network.

   This is a simplified example, but it demonstrates the basic principle of `include` and how it can make it easier to modularize complex applications into sub-Compose files. For more information on `include` and working with multiple Compose files, see [Working with multiple Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/).

4. Stop the stack before moving on:

   ```console
   $ docker compose down
   ```

## [Step 7: Inspect and debug your running stack](#step-7-inspect-and-debug-your-running-stack)

With a fully configured stack, you can observe what's happening inside your containers without stopping anything. This step covers the core commands for inspecting the resolved configuration, streaming logs, and running commands inside a running container.

Before starting the stack, verify that Compose has resolved your `.env` variables and merged all files correctly:

```console
$ docker compose config
```

`docker compose config` doesn't require the stack to be running — it works purely from your files. A few things worth noting in the output:

* `${APP_PORT}`, `${REDIS_HOST}`, and `${REDIS_PORT}` have all been replaced with the values from your `.env` file.
* Short-form port notation (`"8000:5000"`) is expanded into its canonical fields (`target`, `published`, `protocol`).
* The default network and volume names are made explicit, prefixed with the project name `compose-demo`.
* The output is the fully resolved configuration, with any files brought in via `include` merged into a single view.

Use `docker compose config` any time you want to confirm what Compose will actually apply, especially when debugging variable substitution or working with multiple Compose files.

Now start the stack in detached mode so the terminal stays free for the commands that follow:

```console
$ docker compose up -d
```

### [Stream logs from all services](#stream-logs-from-all-services)

```console
$ docker compose logs -f
```

The `-f` flag follows the log stream in real time, interleaving output from both containers with color-coded service name prefixes. Refresh `http://localhost:8000` a few times and watch the Flask request logs appear. To follow logs for a single service, pass its name:

```console
$ docker compose logs -f web
```

Press `Ctrl+C` to stop following logs. The containers keep running.

### [Run commands inside a running container](#run-commands-inside-a-running-container)

`docker compose exec` runs a command inside an already-running container without starting a new one. This is the primary tool for live debugging.

#### [Verify environment variables are set correctly](#verify-environment-variables-are-set-correctly)

```console
$ docker compose exec web env | grep REDIS
```

```text
REDIS_HOST=redis
REDIS_PORT=6379
```

#### [Test that the `web` container can reach Redis using the service name as the hostname](#test-that-the-web-container-can-reach-redis-using-the-service-name-as-the-hostname)

```console
$ docker compose exec web python -c "import redis; r = redis.Redis(host='redis'); print(r.ping())"
```

```text
True
```

This uses the same `redis` library your app uses, so a `True` response confirms that service discovery, networking, and the Redis connection are all working end to end.

#### [Inspect the live value of the hit counter in Redis](#inspect-the-live-value-of-the-hit-counter-in-redis)

```console
$ docker compose exec redis redis-cli GET hits
```

## [Where to go next](#where-to-go-next)

* [Explore the full list of Compose commands](/reference/cli/docker/compose/)
* [Explore the Compose file reference](https://docs.docker.com/reference/compose-file/)
* [Check out the Learning Docker Compose video on LinkedIn Learning](https://www.linkedin.com/learning/learning-docker-compose/)
* [Learn how to set environment variables in Compose](/compose/how-tos/environment-variables/set-environment-variables/)
* [Learn how to package and distribute your Compose app](/compose/how-tos/oci-artifact/)

----
url: https://docs.docker.com/ai/sandboxes/agents/opencode/
----

# OpenCode

***

Table of contents

***

This guide covers authentication, configuration, and usage of OpenCode in a sandboxed environment.

Official documentation: [OpenCode](https://opencode.ai/docs)

## [Quick start](#quick-start)

Create a sandbox and run OpenCode for a project directory:

```console
$ sbx run opencode ~/my-project
```

The workspace parameter is optional and defaults to the current directory:

```console
$ cd ~/my-project
$ sbx run opencode
```

OpenCode launches a TUI (text user interface) where you can select your preferred LLM provider and interact with the agent.

## [Authentication](#authentication)

OpenCode supports multiple providers. Store keys for the providers you want to use with [stored secrets](https://docs.docker.com/ai/sandboxes/security/credentials/#stored-secrets):

```console
$ sbx secret set -g openai
$ sbx secret set -g anthropic
$ sbx secret set -g google
$ sbx secret set -g xai
$ sbx secret set -g groq
$ sbx secret set -g aws
```

You only need to configure the providers you want to use. OpenCode detects available credentials and offers those providers in the TUI.

You can also use environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `AWS_ACCESS_KEY_ID`). See [Credentials](https://docs.docker.com/ai/sandboxes/security/credentials/) for details on both methods.

## [Configuration](#configuration)

Sandboxes don't pick up user-level configuration from your host. Only project-level configuration in the working directory is available inside the sandbox. See [Why doesn't the sandbox use my user-level agent configuration?](https://docs.docker.com/ai/sandboxes/faq/#why-doesnt-the-sandbox-use-my-user-level-agent-configuration) for workarounds.

OpenCode uses a TUI interface and doesn't require extensive configuration files. The agent prompts you to select a provider when it starts, and you can switch providers during a session.

### [Default startup command](#default-startup-command)

The sandbox runs `opencode` with no implicit flags. Args after `--` are passed straight through. For example, to resume an existing session:

```console
$ sbx run opencode -- -s <session-id>
```

### [TUI mode](#tui-mode)

OpenCode launches in TUI mode by default. The interface shows:

* Available LLM providers (based on configured credentials)
* Current conversation history
* File operations and tool usage
* Real-time agent responses

Use keyboard shortcuts to navigate the interface and interact with the agent.

## [Base image](#base-image)

Template: `docker/sandbox-templates:opencode`

OpenCode supports multiple LLM providers with automatic credential injection through the sandbox proxy.

See [Customize](https://docs.docker.com/ai/sandboxes/customize/) to pre-install tools or customize this environment.

----
url: https://docs.docker.com/reference/build-checks/copy-ignored-file/
----

# CopyIgnoredFile

***

Table of contents

***

## [Output](#output)

```text
Attempting to Copy file "./tmp/Dockerfile" that is excluded by .dockerignore
```

## [Description](#description)

When you use the Add or Copy instructions from within a Dockerfile, you should ensure that the files to be copied into the image do not match a pattern present in `.dockerignore`.

Files which match the patterns in a `.dockerignore` file are not present in the context of the image when it is built. Trying to copy or add a file which is missing from the context will result in a build error.

## [Examples](#examples)

With the given `.dockerignore` file:

```text
*/tmp/*
```

❌ Bad: Attempting to Copy file "./tmp/Dockerfile" that is excluded by .dockerignore

```dockerfile
FROM scratch
COPY ./tmp/helloworld.txt /helloworld.txt
```

✅ Good: Copying a file which is not excluded by .dockerignore

```dockerfile
FROM scratch
COPY ./forever/helloworld.txt /helloworld.txt
```

----
url: https://docs.docker.com/reference/api/extensions-sdk/HttpService/
----

# Interface: HttpService

***

Table of contents

***

**`Since`**

0.2.0

## [Methods](#methods)

### [get](#get)

▸ **get**(`url`): `Promise`<`unknown`>

Performs an HTTP GET request to a backend service.

```typescript
ddClient.extension.vm.service
 .get("/some/service")
 .then((value: any) => console.log(value)
```

#### [Parameters](#parameters)

| Name  | Type     | Description                     |
| ----- | -------- | ------------------------------- |
| `url` | `string` | The URL of the backend service. |

#### [Returns](#returns)

`Promise`<`unknown`>

***

### [post](#post)

▸ **post**(`url`, `data`): `Promise`<`unknown`>

Performs an HTTP POST request to a backend service.

```typescript
ddClient.extension.vm.service
 .post("/some/service", { ... })
 .then((value: any) => console.log(value));
```

#### [Parameters](#parameters-1)

| Name   | Type     | Description                     |
| ------ | -------- | ------------------------------- |
| `url`  | `string` | The URL of the backend service. |
| `data` | `any`    | The body of the request.        |

#### [Returns](#returns-1)

`Promise`<`unknown`>

***

### [put](#put)

▸ **put**(`url`, `data`): `Promise`<`unknown`>

Performs an HTTP PUT request to a backend service.

```typescript
ddClient.extension.vm.service
 .put("/some/service", { ... })
 .then((value: any) => console.log(value));
```

#### [Parameters](#parameters-2)

| Name   | Type     | Description                     |
| ------ | -------- | ------------------------------- |
| `url`  | `string` | The URL of the backend service. |
| `data` | `any`    | The body of the request.        |

#### [Returns](#returns-2)

`Promise`<`unknown`>

***

### [patch](#patch)

▸ **patch**(`url`, `data`): `Promise`<`unknown`>

Performs an HTTP PATCH request to a backend service.

```typescript
ddClient.extension.vm.service
 .patch("/some/service", { ... })
 .then((value: any) => console.log(value));
```

#### [Parameters](#parameters-3)

| Name   | Type     | Description                     |
| ------ | -------- | ------------------------------- |
| `url`  | `string` | The URL of the backend service. |
| `data` | `any`    | The body of the request.        |

#### [Returns](#returns-3)

`Promise`<`unknown`>

***

### [delete](#delete)

▸ **delete**(`url`): `Promise`<`unknown`>

Performs an HTTP DELETE request to a backend service.

```typescript
ddClient.extension.vm.service
 .delete("/some/service")
 .then((value: any) => console.log(value));
```

#### [Parameters](#parameters-4)

| Name  | Type     | Description                     |
| ----- | -------- | ------------------------------- |
| `url` | `string` | The URL of the backend service. |

#### [Returns](#returns-4)

`Promise`<`unknown`>

***

### [head](#head)

▸ **head**(`url`): `Promise`<`unknown`>

Performs an HTTP HEAD request to a backend service.

```typescript
ddClient.extension.vm.service
 .head("/some/service")
 .then((value: any) => console.log(value));
```

#### [Parameters](#parameters-5)

| Name  | Type     | Description                     |
| ----- | -------- | ------------------------------- |
| `url` | `string` | The URL of the backend service. |

#### [Returns](#returns-5)

`Promise`<`unknown`>

***

### [request](#request)

▸ **request**(`config`): `Promise`<`unknown`>

Performs an HTTP request to a backend service.

```typescript
ddClient.extension.vm.service
 .request({ url: "/url", method: "GET", headers: { 'header-key': 'header-value' }, data: { ... }})
 .then((value: any) => console.log(value));
```

#### [Parameters](#parameters-6)

| Name     | Type                                                                                   | Description                     |
| -------- | -------------------------------------------------------------------------------------- | ------------------------------- |
| `config` | [`RequestConfig`](https://docs.docker.com/reference/api/extensions-sdk/RequestConfig/) | The URL of the backend service. |

#### [Returns](#returns-6)

----
url: https://docs.docker.com/get-started/docker-concepts/building-images/using-the-build-cache/
----

# Using the build cache

***

Table of contents

***

## [Explanation](#explanation)

Consider the following Dockerfile that you created for the [getting-started](https://docs.docker.com/get-started/docker-concepts/building-images/writing-a-dockerfile/) app.

```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY . .
RUN yarn install --production
CMD ["node", "./src/index.js"]
```

When you run the `docker build` command to create a new image, Docker executes each instruction in your Dockerfile, creating a layer for each command and in the order specified. For each instruction, Docker checks whether it can reuse the instruction from a previous build. If it finds that you've already executed a similar instruction before, Docker doesn't need to redo it. Instead, it’ll use the cached result. This way, your build process becomes faster and more efficient, saving you valuable time and resources.

Using the build cache effectively lets you achieve faster builds by reusing results from previous builds and skipping unnecessary work. In order to maximize cache usage and avoid resource-intensive and time-consuming rebuilds, it's important to understand how cache invalidation works. Here are a few examples of situations that can cause cache to be invalidated:

* Any changes to the command of a `RUN` instruction invalidates that layer. Docker detects the change and invalidates the build cache if there's any modification to a `RUN` command in your Dockerfile.

* Any changes to files copied into the image with the `COPY` or `ADD` instructions. Docker keeps an eye on any alterations to files within your project directory. Whether it's a change in content or properties like permissions, Docker considers these modifications as triggers to invalidate the cache.

* Once one layer is invalidated, all following layers are also invalidated. If any previous layer, including the base image or intermediary layers, has been invalidated due to changes, Docker ensures that subsequent layers relying on it are also invalidated. This keeps the build process synchronized and prevents inconsistencies.

When you're writing or editing a Dockerfile, keep an eye out for unnecessary cache misses to ensure that builds run as fast and efficiently as possible.

## [Try it out](#try-it-out)

In this hands-on guide, you will learn how to use the Docker build cache effectively for a Node.js application.

### [Build the application](#build-the-application)

1. [Download and install](https://www.docker.com/products/docker-desktop/) Docker Desktop.

2. Open a terminal and [clone this sample application](https://github.com/dockersamples/todo-list-app).

   ```console
   $ git clone https://github.com/dockersamples/todo-list-app
   ```

3. Navigate into the `todo-list-app` directory:

   ```console
   $ cd todo-list-app
   ```

   Inside this directory, you'll find a file named `Dockerfile` with the following content:

   ```dockerfile
   FROM node:22-alpine
   WORKDIR /app
   COPY . .
   RUN yarn install --production
   EXPOSE 3000
   CMD ["node", "./src/index.js"]
   ```

4. Execute the following command to build the Docker image:

   ```console
   $ docker build .
   ```

   Here’s the result of the build process:

   ```console
   [+] Building 20.0s (10/10) FINISHED
   ```

   The first line indicates that the entire build process took *20.0 seconds*. The first build may take some time as it installs dependencies.

5. Rebuild without making changes.

   Now, re-run the `docker build` command without making any change in the source code or Dockerfile as shown:

   ```console
   $ docker build .
   ```

   Subsequent builds after the initial are faster due to the caching mechanism, as long as the commands and context remain unchanged. Docker caches the intermediate layers generated during the build process. When you rebuild the image without making any changes to the Dockerfile or the source code, Docker can reuse the cached layers, significantly speeding up the build process.

   ```console
   [+] Building 1.0s (9/9) FINISHED                                                                            docker:desktop-linux
    => [internal] load build definition from Dockerfile                                                                        0.0s
    => => transferring dockerfile: 187B                                                                                        0.0s
    ...
    => [internal] load build context                                                                                           0.0s
    => => transferring context: 8.16kB                                                                                         0.0s
    => CACHED [2/4] WORKDIR /app                                                                                               0.0s
    => CACHED [3/4] COPY . .                                                                                                   0.0s
    => CACHED [4/4] RUN yarn install --production                                                                              0.0s
    => exporting to image                                                                                                      0.0s
    => => exporting layers                                                                                                     0.0s
    => => exporting manifest
   ```

   The subsequent build was completed in just 1.0 second by leveraging the cached layers. No need to repeat time-consuming steps like installing dependencies.

   | Steps | Description                                          | Time Taken (1st Run) | Time Taken (2nd Run) |
   | ----- | ---------------------------------------------------- | -------------------- | -------------------- |
   | 1     | `Load build definition from Dockerfile`              | 0.0 seconds          | 0.0 seconds          |
   | 2     | `Load metadata for docker.io/library/node:22-alpine` | 2.7 seconds          | 0.9 seconds          |
   | 3     | `Load .dockerignore`                                 | 0.0 seconds          | 0.0 seconds          |
   | 4     | `Load build context`(Context size: 4.60MB)           | 0.1 seconds          | 0.0 seconds          |
   | 5     | `Set the working directory (WORKDIR)`                | 0.1 seconds          | 0.0 seconds          |
   | 6     | `Copy the local code into the container`             | 0.0 seconds          | 0.0 seconds          |
   | 7     | `Run yarn install --production`                      | 10.0 seconds         | 0.0 seconds          |
   | 8     | `Exporting layers`                                   | 2.2 seconds          | 0.0 seconds          |
   | 9     | `Exporting the final image`                          | 3.0 seconds          | 0.0 seconds          |

   Going back to the `docker image history` output, you see that each command in the Dockerfile becomes a new layer in the image. You might remember that when you made a change to the image, the `yarn` dependencies had to be reinstalled. Is there a way to fix this? It doesn't make much sense to reinstall the same dependencies every time you build, right?

   To fix this, restructure your Dockerfile so that the dependency cache remains valid unless it really needs to be invalidated. For Node-based applications, dependencies are defined in the `package.json` file. You'll want to reinstall the dependencies if that file changes, but use cached dependencies if the file is unchanged. So, start by copying only that file first, then install the dependencies, and finally copy everything else. Then, you only need to recreate the yarn dependencies if there was a change to the `package.json` file.

6. Update the Dockerfile to copy in the `package.json` file first, install dependencies, and then copy everything else in.

   ```dockerfile
   FROM node:22-alpine
   WORKDIR /app
   COPY package.json yarn.lock ./
   RUN yarn install --production 
   COPY . . 
   EXPOSE 3000
   CMD ["node", "src/index.js"]
   ```

7. Create a file named `.dockerignore` in the same folder as the Dockerfile with the following contents.

   ```plaintext
   node_modules
   ```

8. Build the new image:

   ```console
   $ docker build .
   ```

   You'll then see output similar to the following:

   ```console
   [+] Building 16.1s (10/10) FINISHED
   => [internal] load build definition from Dockerfile                                               0.0s
   => => transferring dockerfile: 175B                                                               0.0s
   => [internal] load .dockerignore                                                                  0.0s
   => => transferring context: 2B                                                                    0.0s
   => [internal] load metadata for docker.io/library/node:22-alpine                                  0.0s
   => [internal] load build context                                                                  0.8s
   => => transferring context: 53.37MB                                                               0.8s
   => [1/5] FROM docker.io/library/node:22-alpine                                                    0.0s
   => CACHED [2/5] WORKDIR /app                                                                      0.0s
   => [3/5] COPY package.json yarn.lock ./                                                           0.2s
   => [4/5] RUN yarn install --production                                                           14.0s
   => [5/5] COPY . .                                                                                 0.5s
   => exporting to image                                                                             0.6s
   => => exporting layers                                                                            0.6s
   => => writing image     
   sha256:d6f819013566c54c50124ed94d5e66c452325327217f4f04399b45f94e37d25        0.0s
   => => naming to docker.io/library/node-app:2.0                                                 0.0s
   ```

   You'll see that all layers were rebuilt. Perfectly fine since you changed the Dockerfile quite a bit.

9. Now, make a change to the `src/static/index.html` file (like change the title to say "The Awesome Todo App").

10. Build the Docker image. This time, your output should look a little different.

    ```console
    $ docker build -t node-app:3.0 .
    ```

    You'll then see output similar to the following:

    ```console
    [+] Building 1.2s (10/10) FINISHED 
    => [internal] load build definition from Dockerfile                                               0.0s
    => => transferring dockerfile: 37B                                                                0.0s
    => [internal] load .dockerignore                                                                  0.0s
    => => transferring context: 2B                                                                    0.0s
    => [internal] load metadata for docker.io/library/node:22-alpine                                  0.0s 
    => [internal] load build context                                                                  0.2s
    => => transferring context: 450.43kB                                                              0.2s
    => [1/5] FROM docker.io/library/node:22-alpine                                                    0.0s
    => CACHED [2/5] WORKDIR /app                                                                      0.0s
    => CACHED [3/5] COPY package.json yarn.lock ./                                                    0.0s
    => CACHED [4/5] RUN yarn install --production                                                     0.0s
    => [5/5] COPY . .                                                                                 0.5s 
    => exporting to image                                                                             0.3s
    => => exporting layers                                                                            0.3s
    => => writing image     
    sha256:91790c87bcb096a83c2bd4eb512bc8b134c757cda0bdee4038187f98148e2eda       0.0s
    => => naming to docker.io/library/node-app:3.0                                                 0.0s
    ```

    First off, you should notice that the build was much faster. You'll see that several steps are using previously cached layers. That's good news; you're using the build cache. Pushing and pulling this image and updates to it will be much faster as well.

By following these optimization techniques, you can make your Docker builds faster and more efficient, leading to quicker iteration cycles and improved development productivity.

## [Additional resources](#additional-resources)

* [Optimizing builds with cache management](/build/cache/)
* [Cache Storage Backend](/build/cache/backends/)
* [Build cache invalidation](/build/cache/invalidation/)

## [Next steps](#next-steps)

Now that you understand how to use the Docker build cache effectively, you're ready to learn about Multi-stage builds.

[Multi-stage builds](https://docs.docker.com/get-started/docker-concepts/building-images/multi-stage-builds/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/history/trace/
----

# docker buildx history trace

***

| Description | Show the OpenTelemetry trace of a build record |
| ----------- | ---------------------------------------------- |
| Usage       | `docker buildx history trace [OPTIONS] [REF]`  |

## [Description](#description)

View the OpenTelemetry trace for a completed build. This command loads the trace into a Jaeger UI viewer and opens it in your browser.

This helps analyze build performance, step timing, and internal execution flows.

## [Options](#options)

| Option                  | Default       | Description                       |
| ----------------------- | ------------- | --------------------------------- |
| [`--addr`](#addr)       | `127.0.0.1:0` | Address to bind the UI server     |
| [`--compare`](#compare) |               | Compare with another build record |

## [Examples](#examples)

### [Open the OpenTelemetry trace for the most recent build](#open-the-opentelemetry-trace-for-the-most-recent-build)

This command starts a temporary Jaeger UI server and opens your default browser to view the trace.

```console
docker buildx history trace
```

### [Open the trace for a specific build](#open-the-trace-for-a-specific-build)

```console
# Using a build ID
docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt

# Or using a relative offset
docker buildx history trace ^1
```

### [Run the Jaeger UI on a specific port (--addr)](#addr)

```console
# Using a build ID
docker buildx history trace qu2gsuo8ejqrwdfii23xkkckt --addr 127.0.0.1:16686

# Or using a relative offset
docker buildx history trace ^1 --addr 127.0.0.1:16686
```

### [Compare two build traces (--compare)](#compare)

Compare two specific builds by name:

```console
# Using build IDs
docker buildx history trace --compare=qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3

# Or using a single relative offset
docker buildx history trace --compare=^1
```

When you use a single reference with `--compare`, it compares that build against the most recent one.

----
url: https://docs.docker.com/reference/cli/docker/trust/signer/
----

# docker trust signer

***

| Description | Manage entities who can sign Docker images |
| ----------- | ------------------------------------------ |
| Usage       | `docker trust signer`                      |

## [Description](#description)

Manage entities who can sign Docker images

## [Subcommands](#subcommands)

| Command                                                                                           | Description     |
| ------------------------------------------------------------------------------------------------- | --------------- |
| [`docker trust signer add`](https://docs.docker.com/reference/cli/docker/trust/signer/add/)       | Add a signer    |
| [`docker trust signer remove`](https://docs.docker.com/reference/cli/docker/trust/signer/remove/) | Remove a signer |

----
url: https://docs.docker.com/enterprise/security/single-sign-on/faqs/general/
----

# General SSO FAQs

***

Table of contents

***

## [What SSO flows does Docker support?](#what-sso-flows-does-docker-support)

Docker supports Service Provider Initiated (SP-initiated) SSO flow. Users must sign in to Docker Hub or Docker Desktop to initiate the SSO authentication process.

## [Does Docker SSO support multi-factor authentication?](#does-docker-sso-support-multi-factor-authentication)

When an organization uses SSO, multi-factor authentication is controlled at the identity provider level, not on the Docker platform.

## [Can I retain my Docker ID when using SSO?](#can-i-retain-my-docker-id-when-using-sso)

Users with personal Docker IDs retain ownership of their repositories, images, and assets. When SSO is enforced, existing accounts with company domain emails are connected to the organization. Users signing in without existing accounts automatically have new accounts and Docker IDs created.

## [Are there any firewall rules required for SSO configuration?](#are-there-any-firewall-rules-required-for-sso-configuration)

No specific firewall rules are required as long as `login.docker.com` is accessible. This domain is commonly accessible by default, but some organizations may need to allow it in their firewall settings if SSO setup encounters issues.

## [Does Docker use my IdP's default session timeout?](#does-docker-use-my-idps-default-session-timeout)

Yes, Docker supports your IdP's session timeout using a custom `dockerSessionMinutes` SAML attribute instead of the standard `SessionNotOnOrAfter` element. See [SSO attributes](https://docs.docker.com/enterprise/security/provisioning/#sso-attributes) for more information.

----
url: https://docs.docker.com/engine/swarm/swarm-tutorial/scale-service/
----

# Scale the service in the swarm

***

***

Once you have [deployed a service](https://docs.docker.com/engine/swarm/swarm-tutorial/deploy-service/) to a swarm, you are ready to use the Docker CLI to scale the number of containers in the service. Containers running in a service are called tasks.

1. If you haven't already, open a terminal and ssh into the machine where you run your manager node. For example, the tutorial uses a machine named `manager1`.

2. Run the following command to change the desired state of the service running in the swarm:

   ```console
   $ docker service scale <SERVICE-ID>=<NUMBER-OF-TASKS>
   ```

   For example:

   ```console
   $ docker service scale helloworld=5

   helloworld scaled to 5
   ```

3. Run `docker service ps <SERVICE-ID>` to see the updated task list:

   ```console
   $ docker service ps helloworld

   NAME                                    IMAGE   NODE      DESIRED STATE  CURRENT STATE
   helloworld.1.8p1vev3fq5zm0mi8g0as41w35  alpine  worker2   Running        Running 7 minutes
   helloworld.2.c7a7tcdq5s0uk3qr88mf8xco6  alpine  worker1   Running        Running 24 seconds
   helloworld.3.6crl09vdcalvtfehfh69ogfb1  alpine  worker1   Running        Running 24 seconds
   helloworld.4.auky6trawmdlcne8ad8phb0f1  alpine  manager1  Running        Running 24 seconds
   helloworld.5.ba19kca06l18zujfwxyc5lkyn  alpine  worker2   Running        Running 24 seconds
   ```

   You can see that swarm has created 4 new tasks to scale to a total of 5 running instances of Alpine Linux. The tasks are distributed between the three nodes of the swarm. One is running on `manager1`.

4. Run `docker ps` to see the containers running on the node where you're connected. The following example shows the tasks running on `manager1`:

   ```console
   $ docker ps

   CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
   528d68040f95        alpine:latest       "ping docker.com"   About a minute ago   Up About a minute                       helloworld.4.auky6trawmdlcne8ad8phb0f1
   ```

   If you want to see the containers running on other nodes, ssh into those nodes and run the `docker ps` command.

## [Next steps](#next-steps)

At this point in the tutorial, you're finished with the `helloworld` service. Next, you'll delete the service

[Delete the service](https://docs.docker.com/engine/swarm/swarm-tutorial/delete-service/)

----
url: https://docs.docker.com/engine/security/trust/trust_key_mng/
----

# Manage keys for content trust

***

Table of contents

***

Trust for an image tag is managed through the use of keys. Docker's content trust makes use of five different types of keys:

| Key        | Description                                                                                                                                                                                                                         |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| root key   | Root of content trust for an image tag. When content trust is enabled, you create the root key once. Also known as the offline key, because it should be kept offline.                                                              |
| targets    | This key allows you to sign image tags, to manage delegations including delegated keys or permitted delegation paths. Also known as the repository key, since this key determines what tags can be signed into an image repository. |
| snapshot   | This key signs the current collection of image tags, preventing mix and match attacks.                                                                                                                                              |
| timestamp  | This key allows Docker image repositories to have freshness security guarantees without requiring periodic content refreshes on the client's side.                                                                                  |
| delegation | Delegation keys are optional tagging keys and allow you to delegate signing image tags to other publishers without having to share your targets key.                                                                                |

When doing a `docker push` with Content Trust enabled for the first time, the root, targets, snapshot, and timestamp keys are generated automatically for the image repository:

* The root and targets key are generated and stored locally client-side.

* The timestamp and snapshot keys are safely generated and stored in a signing server that is deployed alongside the Docker registry. These keys are generated in a backend service that isn't directly exposed to the internet and are encrypted at rest. Use the Notary CLI to [manage your snapshot key locally](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#rotate-keys).

Delegation keys are optional, and not generated as part of the normal `docker` workflow. They need to be [manually generated and added to the repository](https://docs.docker.com/engine/security/trust/trust_delegation/#creating-delegation-keys).

## [Choose a passphrase](#choose-a-passphrase)

The passphrases you chose for both the root key and your repository key should be randomly generated and stored in a password manager. Having the repository key allows users to sign image tags on a repository. Passphrases are used to encrypt your keys at rest and ensure that a lost laptop or an unintended backup doesn't put the private key material at risk.

## [Back up your keys](#back-up-your-keys)

All the Docker trust keys are stored encrypted using the passphrase you provide on creation. Even so, you should still take care of the location where you back them up. Good practice is to create two encrypted USB keys.

> Warning
>
> It is very important that you back up your keys to a safe, secure location. The loss of the repository key is recoverable, but the loss of the root key is not.

The Docker client stores the keys in the `~/.docker/trust/private` directory. Before backing them up, you should `tar` them into an archive:

```console
$ umask 077; tar -zcvf private_keys_backup.tar.gz ~/.docker/trust/private; umask 022
```

## [Hardware storage and signing](#hardware-storage-and-signing)

Docker Content Trust can store and sign with root keys from a Yubikey 4. The Yubikey is prioritized over keys stored in the filesystem. When you initialize a new repository with content trust, Docker Engine looks for a root key locally. If a key is not found and the Yubikey 4 exists, Docker Engine creates a root key in the Yubikey 4. Consult the [Notary documentation](https://github.com/theupdateframework/notary/blob/master/docs/advanced_usage.md#use-a-yubikey) for more details.

Prior to Docker Engine 1.11, this feature was only in the experimental branch.

## [Key loss](#key-loss)

> Warning
>
> If a publisher loses keys it means losing the ability to sign images for the repositories in question. If you lose a key, send an email to [Docker Hub Support](mailto:hub-support@docker.com). As a reminder, the loss of a root key is not recoverable.

This loss also requires manual intervention from every consumer that used a signed tag from this repository prior to the loss.\
Image consumers get the following error for content previously downloaded from the affected repo(s):

```console
Warning: potential malicious behavior - trust data has insufficient signatures for remote repository docker.io/my/image: valid signatures did not meet threshold
```

To correct this, they need to download a new image tag that is signed with the new key.

## [Related information](#related-information)

* [Content trust in Docker](https://docs.docker.com/engine/security/trust/)
* [Automation with content trust](https://docs.docker.com/engine/security/trust/trust_automation/)
* [Delegations for content trust](https://docs.docker.com/engine/security/trust/trust_delegation/)
* [Play in a content trust sandbox](https://docs.docker.com/engine/security/trust/trust_sandbox/)

----
url: https://docs.docker.com/reference/cli/docker/offload/stop/
----

# docker offload stop

***

| Description | Stop a Docker Offload session   |
| ----------- | ------------------------------- |
| Usage       | `docker offload stop [OPTIONS]` |

## [Options](#options)

| Option        | Default | Description                   |
| ------------- | ------- | ----------------------------- |
| `-f, --force` |         | Don't prompt for confirmation |

----
url: https://docs.docker.com/security/faqs/general/
----

# General security FAQs

***

Table of contents

***

## [How do I report a vulnerability?](#how-do-i-report-a-vulnerability)

If you've discovered a security vulnerability in Docker, report it responsibly to <security@docker.com> so Docker can quickly address it.

## [Does Docker lockout users after failed sign-ins?](#does-docker-lockout-users-after-failed-sign-ins)

Docker Hub locks out users after 10 failed sign-in attempts within 5 minutes. The lockout duration is 5 minutes. This policy applies to Docker Hub, Docker Desktop, and Docker Scout authentication.

## [Do you support physical multi-factor authentication (MFA) with YubiKeys?](#do-you-support-physical-multi-factor-authentication-mfa-with-yubikeys)

You can configure physical multi-factor authentication (MFA) through SSO using your identity provider (IdP). Check with your IdP if they support physical MFA devices like YubiKeys.

## [How are sessions managed and do they expire?](#how-are-sessions-managed-and-do-they-expire)

Docker uses tokens to manage user sessions with different expiration periods:

* Docker Desktop: Signs you out after 90 days, or 30 days of inactivity
* Docker Hub and Docker Home: Sign you out after 24 hours

Docker also supports your IdP's default session timeout through SAML attributes. For more information, see [SSO attributes](https://docs.docker.com/enterprise/security/provisioning/#sso-attributes).

## [How does Docker distinguish between employee users and contractor users?](#how-does-docker-distinguish-between-employee-users-and-contractor-users)

Organizations use verified domains to distinguish user types. Team members with email domains other than verified domains appear as "Guest" users in the organization.

## [How long are activity logs available?](#how-long-are-activity-logs-available)

Docker activity logs are available for 90 days. You're responsible for exporting logs or setting up drivers to send logs to your internal systems for longer retention.

## [Can I export a list of users with their roles and privileges?](#can-i-export-a-list-of-users-with-their-roles-and-privileges)

Yes, use the [Export Members](https://docs.docker.com/admin/organization/manage/members/#export-members-csv-file) feature to export a CSV file containing your organization's users with role and team information.

## [How does Docker Desktop handle authentication information?](#how-does-docker-desktop-handle-authentication-information)

Docker Desktop uses the host operating system's secure key management to store authentication tokens:

* macOS: [Keychain](https://support.apple.com/guide/security/keychain-data-protection-secb0694df1a/web)
* Windows: [Security and Identity API via Wincred](https://learn.microsoft.com/en-us/windows/win32/api/wincred/)
* Linux: [Pass](https://www.passwordstore.org/).

## [How do I remove users who aren't part of my IdP when using SSO without SCIM?](#how-do-i-remove-users-who-arent-part-of-my-idp-when-using-sso-without-scim)

If SCIM isn't turned on, you must manually remove users from the organization. SCIM can automate user removal, but only for users added after SCIM is turned on. Users added before SCIM was turned on must be removed manually.

For more information, see [Manage organization members](https://docs.docker.com/admin/organization/manage/members/).

## [What metadata does Scout collect from container images?](#what-metadata-does-scout-collect-from-container-images)

For information about metadata stored by Docker Scout, see [Data handling](https://docs.docker.com/scout/deep-dive/data-handling/).

## [How are Marketplace extensions vetted for security?](#how-are-marketplace-extensions-vetted-for-security)

Security vetting for extensions isn't implemented. Extensions aren't covered as part of Docker's Third-Party Risk Management Program.

## [Can I prevent users from pushing images to Docker Hub private repositories?](#can-i-prevent-users-from-pushing-images-to-docker-hub-private-repositories)

No direct setting exists to disable private repositories. However, [Registry Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/) lets administrators control which registries developers can access through Docker Desktop via the Admin Console.

----
url: https://docs.docker.com/build/building/multi-stage/
----

# Multi-stage builds

***

Table of contents

***

Multi-stage builds are useful to anyone who has struggled to optimize Dockerfiles while keeping them easy to read and maintain.

## [Use multi-stage builds](#use-multi-stage-builds)

With multi-stage builds, you use multiple `FROM` statements in your Dockerfile. Each `FROM` instruction can use a different base, and each of them begins a new stage of the build. You can selectively copy artifacts from one stage to another, leaving behind everything you don't want in the final image.

The following Dockerfile has two separate stages: one for building a binary, and another where the binary gets copied from the first stage into the next stage.

```dockerfile
# syntax=docker/dockerfile:1
FROM golang:1.25
WORKDIR /src
COPY <<EOF ./main.go
package main

import "fmt"

func main() {
  fmt.Println("hello, world")
}
EOF
RUN go build -o /bin/hello ./main.go

FROM scratch
COPY --from=0 /bin/hello /bin/hello
CMD ["/bin/hello"]
```

You only need the single Dockerfile. No need for a separate build script. Just run `docker build`.

```console
$ docker build -t hello .
```

The end result is a tiny production image with nothing but the binary inside. None of the build tools required to build the application are included in the resulting image.

How does it work? The second `FROM` instruction starts a new build stage with the `scratch` image as its base. The `COPY --from=0` line copies just the built artifact from the previous stage into this new stage. The Go SDK and any intermediate artifacts are left behind, and not saved in the final image.

## [Name your build stages](#name-your-build-stages)

By default, the stages aren't named, and you refer to them by their integer number, starting with 0 for the first `FROM` instruction. However, you can name your stages, by adding an `AS <NAME>` to the `FROM` instruction. This example improves the previous one by naming the stages and using the name in the `COPY` instruction. This means that even if the instructions in your Dockerfile are re-ordered later, the `COPY` doesn't break.

```dockerfile
# syntax=docker/dockerfile:1
FROM golang:1.25 AS build
WORKDIR /src
COPY <<EOF /src/main.go
package main

import "fmt"

func main() {
  fmt.Println("hello, world")
}
EOF
RUN go build -o /bin/hello ./main.go

FROM scratch
COPY --from=build /bin/hello /bin/hello
CMD ["/bin/hello"]
```

## [Stop at a specific build stage](#stop-at-a-specific-build-stage)

When you build your image, you don't necessarily need to build the entire Dockerfile including every stage. You can specify a target build stage. The following command assumes you are using the previous `Dockerfile` but stops at the stage named `build`:

```console
$ docker build --target build -t hello .
```

A few scenarios where this might be useful are:

* Debugging a specific build stage
* Using a `debug` stage with all debugging symbols or tools enabled, and a lean `production` stage
* Using a `testing` stage in which your app gets populated with test data, but building for production using a different stage which uses real data

## [Use an external image as a stage](#use-an-external-image-as-a-stage)

When using multi-stage builds, you aren't limited to copying from stages you created earlier in your Dockerfile. You can use the `COPY --from` instruction to copy from a separate image, either using the local image name, a tag available locally or on a Docker registry, or a tag ID. The Docker client pulls the image if necessary and copies the artifact from there. The syntax is:

```dockerfile
COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf
```

## [Use a previous stage as a new stage](#use-a-previous-stage-as-a-new-stage)

You can pick up where a previous stage left off by referring to it when using the `FROM` directive. For example:

```dockerfile
# syntax=docker/dockerfile:1

FROM alpine:latest AS builder
RUN apk --no-cache add build-base

FROM builder AS build1
COPY source1.cpp source.cpp
RUN g++ -o /binary source.cpp

FROM builder AS build2
COPY source2.cpp source.cpp
RUN g++ -o /binary source.cpp
```

## [Differences between legacy builder and BuildKit](#differences-between-legacy-builder-and-buildkit)

The legacy Docker Engine builder processes all stages of a Dockerfile leading up to the selected `--target`. It will build a stage even if the selected target doesn't depend on that stage.

[BuildKit](https://docs.docker.com/build/buildkit/) only builds the stages that the target stage depends on.

For example, given the following Dockerfile:

```dockerfile
# syntax=docker/dockerfile:1
FROM ubuntu AS base
RUN echo "base"

FROM base AS stage1
RUN echo "stage1"

FROM base AS stage2
RUN echo "stage2"
```

With [BuildKit enabled](https://docs.docker.com/build/buildkit/#getting-started), building the `stage2` target in this Dockerfile means only `base` and `stage2` are processed. There is no dependency on `stage1`, so it's skipped.

```console
$ DOCKER_BUILDKIT=1 docker build --no-cache -f Dockerfile --target stage2 .
[+] Building 0.4s (7/7) FINISHED                                                                    
 => [internal] load build definition from Dockerfile                                            0.0s
 => => transferring dockerfile: 36B                                                             0.0s
 => [internal] load .dockerignore                                                               0.0s
 => => transferring context: 2B                                                                 0.0s
 => [internal] load metadata for docker.io/library/ubuntu:latest                                0.0s
 => CACHED [base 1/2] FROM docker.io/library/ubuntu                                             0.0s
 => [base 2/2] RUN echo "base"                                                                  0.1s
 => [stage2 1/1] RUN echo "stage2"                                                              0.2s
 => exporting to image                                                                          0.0s
 => => exporting layers                                                                         0.0s
 => => writing image sha256:f55003b607cef37614f607f0728e6fd4d113a4bf7ef12210da338c716f2cfd15    0.0s
```

On the other hand, building the same target without BuildKit results in all stages being processed:

```console
$ DOCKER_BUILDKIT=0 docker build --no-cache -f Dockerfile --target stage2 .
Sending build context to Docker daemon  219.1kB
Step 1/6 : FROM ubuntu AS base
 ---> a7870fd478f4
Step 2/6 : RUN echo "base"
 ---> Running in e850d0e42eca
base
Removing intermediate container e850d0e42eca
 ---> d9f69f23cac8
Step 3/6 : FROM base AS stage1
 ---> d9f69f23cac8
Step 4/6 : RUN echo "stage1"
 ---> Running in 758ba6c1a9a3
stage1
Removing intermediate container 758ba6c1a9a3
 ---> 396baa55b8c3
Step 5/6 : FROM base AS stage2
 ---> d9f69f23cac8
Step 6/6 : RUN echo "stage2"
 ---> Running in bbc025b93175
stage2
Removing intermediate container bbc025b93175
 ---> 09fc3770a9c4
Successfully built 09fc3770a9c4
```

The legacy builder processes `stage1`, even if `stage2` doesn't depend on it.

----
url: https://docs.docker.com/engine/swarm/configs/
----

# Store configuration data using Docker Configs

***

Table of contents

***

## [About configs](#about-configs)

Docker swarm service configs allow you to store non-sensitive information, such as configuration files, outside a service's image or running containers. This allows you to keep your images as generic as possible, without the need to bind-mount configuration files into the containers or use environment variables.

Configs operate in a similar way to [secrets](https://docs.docker.com/engine/swarm/secrets/), except that they are not encrypted at rest and are mounted directly into the container's filesystem without the use of RAM disks. Configs can be added or removed from a service at any time, and services can share a config. You can even use configs in conjunction with environment variables or labels, for maximum flexibility. Config values can be generic strings or binary content (up to 500 kb in size).

> Note
>
> Docker configs are only available to swarm services, not to standalone containers. To use this feature, consider adapting your container to run as a service with a scale of 1.

Configs are supported on both Linux and Windows services.

### [Windows support](#windows-support)

Docker includes support for configs on Windows containers, but there are differences in the implementations, which are called out in the examples below. Keep the following notable differences in mind:

* Config files with custom targets are not directly bind-mounted into Windows containers, since Windows does not support non-directory file bind-mounts. Instead, configs for a container are all mounted in `C:\ProgramData\Docker\internal\configs` (an implementation detail which should not be relied upon by applications) within the container. Symbolic links are used to point from there to the desired target of the config within the container. The default target is `C:\ProgramData\Docker\configs`.

* When creating a service which uses Windows containers, the options to specify UID, GID, and mode are not supported for configs. Configs are currently only accessible by administrators and users with `system` access within the container.

* On Windows, create or update a service using `--credential-spec` with the `config://<config-name>` format. This passes the gMSA credentials file directly to nodes before a container starts. No gMSA credentials are written to disk on worker nodes. For more information, refer to [Deploy services to a swarm](https://docs.docker.com/engine/swarm/services/#gmsa-for-swarm).

## [How Docker manages configs](#how-docker-manages-configs)

When you add a config to the swarm, Docker sends the config to the swarm manager over a mutual TLS connection. The config is stored in the Raft log, which is encrypted. The entire Raft log is replicated across the other managers, ensuring the same high availability guarantees for configs as for the rest of the swarm management data.

When you grant a newly-created or running service access to a config, the config is mounted as a file in the container. The location of the mount point within the container defaults to `/<config-name>` in Linux containers. In Windows containers, configs are all mounted into `C:\ProgramData\Docker\configs` and symbolic links are created to the desired location, which defaults to `C:\<config-name>`.

You can set the ownership (`uid` and `gid`) for the config, using either the numerical ID or the name of the user or group. You can also specify the file permissions (`mode`). These settings are ignored for Windows containers.

* If not set, the config is owned by the user running the container command (often `root`) and that user's default group (also often `root`).
* If not set, the config has world-readable permissions (mode `0444`), unless a `umask` is set within the container, in which case the mode is impacted by that `umask` value.

You can update a service to grant it access to additional configs or revoke its access to a given config at any time.

A node only has access to configs if the node is a swarm manager or if it is running service tasks which have been granted access to the config. When a container task stops running, the configs shared to it are unmounted from the in-memory filesystem for that container and flushed from the node's memory.

If a node loses connectivity to the swarm while it is running a task container with access to a config, the task container still has access to its configs, but cannot receive updates until the node reconnects to the swarm.

You can add or inspect an individual config at any time, or list all configs. You cannot remove a config that a running service is using. See [Rotate a config](https://docs.docker.com/engine/swarm/configs/#example-rotate-a-config) for a way to remove a config without disrupting running services.

To update or roll back configs more easily, consider adding a version number or date to the config name. This is made easier by the ability to control the mount point of the config within a given container.

To update a stack, make changes to your Compose file, then re-run `docker stack deploy -c <new-compose-file> <stack-name>`. If you use a new config in that file, your services start using them. Keep in mind that configurations are immutable, so you can't change the file for an existing service. Instead, you create a new config to use a different file

You can run `docker stack rm` to stop the app and take down the stack. This removes any config that was created by `docker stack deploy` with the same stack name. This removes *all* configs, including those not referenced by services and those remaining after a `docker service update --config-rm`.

## [Read more about `docker config` commands](#read-more-about-docker-config-commands)

Use these links to read about specific commands, or continue to the [example about using configs with a service](#advanced-example-use-configs-with-a-nginx-service).

* [`docker config create`](/reference/cli/docker/config/create/)
* [`docker config inspect`](/reference/cli/docker/config/inspect/)
* [`docker config ls`](/reference/cli/docker/config/ls/)
* [`docker config rm`](/reference/cli/docker/config/rm/)

## [Examples](#examples)

This section includes graduated examples which illustrate how to use Docker configs.

> Note
>
> These examples use a single-engine swarm and unscaled services for simplicity. The examples use Linux containers, but Windows containers also support configs.

### [Defining and using configs in compose files](#defining-and-using-configs-in-compose-files)

The `docker stack` command supports defining configs in a Compose file. However, the `configs` key is not supported for `docker compose`. See [the Compose file reference](https://docs.docker.com/reference/compose-file/configs/) for details.

### [Simple example: Get started with configs](#simple-example-get-started-with-configs)

This simple example shows how configs work in just a few commands. For a real-world example, continue to [Advanced example: Use configs with a Nginx service](#advanced-example-use-configs-with-a-nginx-service).

1. Add a config to Docker. The `docker config create` command reads standard input because the last argument, which represents the file to read the config from, is set to `-`.

   ```console
   $ echo "This is a config" | docker config create my-config -
   ```

2. Create a `redis` service and grant it access to the config. By default, the container can access the config at `/my-config`, but you can customize the file name on the container using the `target` option.

   ```console
   $ docker service create --name redis --config my-config redis:alpine
   ```

3. Verify that the task is running without issues using `docker service ps`. If everything is working, the output looks similar to this:

   ```console
   $ docker service ps redis

   ID            NAME     IMAGE         NODE              DESIRED STATE  CURRENT STATE          ERROR  PORTS
   bkna6bpn8r1a  redis.1  redis:alpine  ip-172-31-46-109  Running        Running 8 seconds ago
   ```

4. Get the ID of the `redis` service task container using `docker ps`, so that you can use `docker container exec` to connect to the container and read the contents of the config data file, which defaults to being readable by all and has the same name as the name of the config. The first command below illustrates how to find the container ID, and the second and third commands use shell completion to do this automatically.

   ```console
   $ docker ps --filter name=redis -q

   5cb1c2348a59

   $ docker container exec $(docker ps --filter name=redis -q) ls -l /my-config

   -r--r--r--    1 root     root            12 Jun  5 20:49 my-config

   $ docker container exec $(docker ps --filter name=redis -q) cat /my-config

   This is a config
   ```

5. Try removing the config. The removal fails because the `redis` service is running and has access to the config.

   ```console

   $ docker config ls

   ID                          NAME                CREATED             UPDATED
   fzwcfuqjkvo5foqu7ts7ls578   hello               31 minutes ago      31 minutes ago


   $ docker config rm my-config

   Error response from daemon: rpc error: code = 3 desc = config 'my-config' is
   in use by the following service: redis
   ```

6. Remove access to the config from the running `redis` service by updating the service.

   ```console
   $ docker service update --config-rm my-config redis
   ```

7. Repeat steps 3 and 4 again, verifying that the service no longer has access to the config. The container ID is different, because the `service update` command redeploys the service.

   ```console
   $ docker container exec -it $(docker ps --filter name=redis -q) cat /my-config

   cat: can't open '/my-config': No such file or directory
   ```

8. Stop and remove the service, and remove the config from Docker.

   ```console
   $ docker service rm redis

   $ docker config rm my-config
   ```

### [Simple example: Use configs in a Windows service](#simple-example-use-configs-in-a-windows-service)

This is a very simple example which shows how to use configs with a Microsoft IIS service running on Docker for Windows running Windows containers on Microsoft Windows 10. It is a naive example that stores the webpage in a config.

This example assumes that you have PowerShell installed.

1. Save the following into a new file `index.html`.

   ```html
   <html lang="en">
     <head><title>Hello Docker</title></head>
     <body>
       <p>Hello Docker! You have deployed a HTML page.</p>
     </body>
   </html>
   ```

2. If you have not already done so, initialize or join the swarm.

   ```powershell
   docker swarm init
   ```

3. Save the `index.html` file as a swarm config named `homepage`.

   ```powershell
   docker config create homepage index.html
   ```

4. Create an IIS service and grant it access to the `homepage` config.

   ```powershell
   docker service create
       --name my-iis
       --publish published=8000,target=8000
       --config src=homepage,target="\inetpub\wwwroot\index.html"
       microsoft/iis:nanoserver
   ```

5. Access the IIS service at `http://localhost:8000/`. It should serve the HTML content from the first step.

6. Remove the service and the config.

   ```powershell
   docker service rm my-iis

   docker config rm homepage
   ```

### [Example: Use a templated config](#example-use-a-templated-config)

To create a configuration in which the content will be generated using a template engine, use the `--template-driver` parameter and specify the engine name as its argument. The template will be rendered when container is created.

1. Save the following into a new file `index.html.tmpl`.

   ```html
   <html lang="en">
     <head><title>Hello Docker</title></head>
     <body>
       <p>Hello {{ env "HELLO" }}! I'm service {{ .Service.Name }}.</p>
     </body>
   </html>
   ```

2. Save the `index.html.tmpl` file as a swarm config named `homepage`. Provide parameter `--template-driver` and specify `golang` as template engine.

   ```console
   $ docker config create --template-driver golang homepage index.html.tmpl
   ```

3. Create a service that runs Nginx and has access to the environment variable HELLO and to the config.

   ```console
   $ docker service create \
        --name hello-template \
        --env HELLO="Docker" \
        --config source=homepage,target=/usr/share/nginx/html/index.html \
        --publish published=3000,target=80 \
        nginx:alpine
   ```

4. Verify that the service is operational: you can reach the Nginx server, and that the correct output is being served.

   ```console
   $ curl http://0.0.0.0:3000

   <html lang="en">
     <head><title>Hello Docker</title></head>
     <body>
       <p>Hello Docker! I'm service hello-template.</p>
     </body>
   </html>
   ```

### [Advanced example: Use configs with a Nginx service](#advanced-example-use-configs-with-a-nginx-service)

This example is divided into two parts. [The first part](#generate-the-site-certificate) is all about generating the site certificate and does not directly involve Docker configs at all, but it sets up [the second part](#configure-the-nginx-container), where you store and use the site certificate as a series of secrets and the Nginx configuration as a config. The example shows how to set options on the config, such as the target location within the container and the file permissions (`mode`).

#### [Generate the site certificate](#generate-the-site-certificate)

Generate a root CA and TLS certificate and key for your site. For production sites, you may want to use a service such as `Let’s Encrypt` to generate the TLS certificate and key, but this example uses command-line tools. This step is a little complicated, but is only a set-up step so that you have something to store as a Docker secret. If you want to skip these sub-steps, you can [use Let's Encrypt](https://letsencrypt.org/getting-started/) to generate the site key and certificate, name the files `site.key` and `site.crt`, and skip to [Configure the Nginx container](#configure-the-nginx-container).

1. Generate a root key.

   ```console
   $ openssl genrsa -out "root-ca.key" 4096
   ```

2. Generate a CSR using the root key.

   ```console
   $ openssl req \
             -new -key "root-ca.key" \
             -out "root-ca.csr" -sha256 \
             -subj '/C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA'
   ```

3. Configure the root CA. Edit a new file called `root-ca.cnf` and paste the following contents into it. This constrains the root CA to only sign leaf certificates and not intermediate CAs.

   ```ini
   [root_ca]
   basicConstraints = critical,CA:TRUE,pathlen:1
   keyUsage = critical, nonRepudiation, cRLSign, keyCertSign
   subjectKeyIdentifier=hash
   ```

4. Sign the certificate.

   ```console
   $ openssl x509 -req -days 3650 -in "root-ca.csr" \
                  -signkey "root-ca.key" -sha256 -out "root-ca.crt" \
                  -extfile "root-ca.cnf" -extensions \
                  root_ca
   ```

5. Generate the site key.

   ```console
   $ openssl genrsa -out "site.key" 4096
   ```

6. Generate the site certificate and sign it with the site key.

   ```console
   $ openssl req -new -key "site.key" -out "site.csr" -sha256 \
             -subj '/C=US/ST=CA/L=San Francisco/O=Docker/CN=localhost'
   ```

7. Configure the site certificate. Edit a new file called `site.cnf` and paste the following contents into it. This constrains the site certificate so that it can only be used to authenticate a server and can't be used to sign certificates.

   ```ini
   [server]
   authorityKeyIdentifier=keyid,issuer
   basicConstraints = critical,CA:FALSE
   extendedKeyUsage=serverAuth
   keyUsage = critical, digitalSignature, keyEncipherment
   subjectAltName = DNS:localhost, IP:127.0.0.1
   subjectKeyIdentifier=hash
   ```

8. Sign the site certificate.

   ```console
   $ openssl x509 -req -days 750 -in "site.csr" -sha256 \
       -CA "root-ca.crt" -CAkey "root-ca.key" -CAcreateserial \
       -out "site.crt" -extfile "site.cnf" -extensions server
   ```

9. The `site.csr` and `site.cnf` files are not needed by the Nginx service, but you need them if you want to generate a new site certificate. Protect the `root-ca.key` file.

#### [Configure the Nginx container](#configure-the-nginx-container)

1. Produce a very basic Nginx configuration that serves static files over HTTPS. The TLS certificate and key are stored as Docker secrets so that they can be rotated easily.

   In the current directory, create a new file called `site.conf` with the following contents:

   ```nginx
   server {
       listen                443 ssl;
       server_name           localhost;
       ssl_certificate       /run/secrets/site.crt;
       ssl_certificate_key   /run/secrets/site.key;

       location / {
           root   /usr/share/nginx/html;
           index  index.html index.htm;
       }
   }
   ```

2. Create two secrets, representing the key and the certificate. You can store any file as a secret as long as it is smaller than 500 KB. This allows you to decouple the key and certificate from the services that use them. In these examples, the secret name and the file name are the same.

   ```console
   $ docker secret create site.key site.key

   $ docker secret create site.crt site.crt
   ```

3. Save the `site.conf` file in a Docker config. The first parameter is the name of the config, and the second parameter is the file to read it from.

   ```console
   $ docker config create site.conf site.conf
   ```

   List the configs:

   ```console
   $ docker config ls

   ID                          NAME                CREATED             UPDATED
   4ory233120ccg7biwvy11gl5z   site.conf           4 seconds ago       4 seconds ago
   ```

4. Create a service that runs Nginx and has access to the two secrets and the config. Set the mode to `0440` so that the file is only readable by its owner and that owner's group, not the world.

   ```console
   $ docker service create \
        --name nginx \
        --secret site.key \
        --secret site.crt \
        --config source=site.conf,target=/etc/nginx/conf.d/site.conf,mode=0440 \
        --publish published=3000,target=443 \
        nginx:latest \
        sh -c "exec nginx -g 'daemon off;'"
   ```

   Within the running containers, the following three files now exist:

   * `/run/secrets/site.key`
   * `/run/secrets/site.crt`
   * `/etc/nginx/conf.d/site.conf`

5. Verify that the Nginx service is running.

   ```console
   $ docker service ls

   ID            NAME   MODE        REPLICAS  IMAGE
   zeskcec62q24  nginx  replicated  1/1       nginx:latest

   $ docker service ps nginx

   NAME                  IMAGE         NODE  DESIRED STATE  CURRENT STATE          ERROR  PORTS
   nginx.1.9ls3yo9ugcls  nginx:latest  moby  Running        Running 3 minutes ago
   ```

6. Verify that the service is operational: you can reach the Nginx server, and that the correct TLS certificate is being used.

   ```console
   $ curl --cacert root-ca.crt https://0.0.0.0:3000

   <!DOCTYPE html>
   <html>
   <head>
   <title>Welcome to nginx!</title>
   <style>
       body {
           width: 35em;
           margin: 0 auto;
           font-family: Tahoma, Verdana, Arial, sans-serif;
       }
   </style>
   </head>
   <body>
   <h1>Welcome to nginx!</h1>
   <p>If you see this page, the nginx web server is successfully installed and
   working. Further configuration is required.</p>

   <p>For online documentation and support, refer to
   <a href="https://nginx.org">nginx.org</a>.<br/>
   Commercial support is available at
   <a href="https://www.nginx.com">www.nginx.com</a>.</p>

   <p><em>Thank you for using nginx.</em></p>
   </body>
   </html>
   ```

   ```console
   $ openssl s_client -connect 0.0.0.0:3000 -CAfile root-ca.crt

   CONNECTED(00000003)
   depth=1 /C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA
   verify return:1
   depth=0 /C=US/ST=CA/L=San Francisco/O=Docker/CN=localhost
   verify return:1
   ---
   Certificate chain
    0 s:/C=US/ST=CA/L=San Francisco/O=Docker/CN=localhost
      i:/C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA
   ---
   Server certificate
   -----BEGIN CERTIFICATE-----
   …
   -----END CERTIFICATE-----
   subject=/C=US/ST=CA/L=San Francisco/O=Docker/CN=localhost
   issuer=/C=US/ST=CA/L=San Francisco/O=Docker/CN=Swarm Secret Example CA
   ---
   No client certificate CA names sent
   ---
   SSL handshake has read 1663 bytes and written 712 bytes
   ---
   New, TLSv1/SSLv3, Cipher is AES256-SHA
   Server public key is 4096 bit
   Secure Renegotiation IS supported
   Compression: NONE
   Expansion: NONE
   SSL-Session:
       Protocol  : TLSv1
       Cipher    : AES256-SHA
       Session-ID: A1A8BF35549C5715648A12FD7B7E3D861539316B03440187D9DA6C2E48822853
       Session-ID-ctx:
       Master-Key: F39D1B12274BA16D3A906F390A61438221E381952E9E1E05D3DD784F0135FB81353DA38C6D5C021CB926E844DFC49FC4
       Key-Arg   : None
       Start Time: 1481685096
       Timeout   : 300 (sec)
       Verify return code: 0 (ok)
   ```

7. Unless you are going to continue to the next example, clean up after running this example by removing the `nginx` service and the stored secrets and config.

   ```console
   $ docker service rm nginx

   $ docker secret rm site.crt site.key

   $ docker config rm site.conf
   ```

You have now configured a Nginx service with its configuration decoupled from its image. You could run multiple sites with exactly the same image but separate configurations, without the need to build a custom image at all.

### [Example: Rotate a config](#example-rotate-a-config)

To rotate a config, you first save a new config with a different name than the one that is currently in use. You then redeploy the service, removing the old config and adding the new config at the same mount point within the container. This example builds upon the previous one by rotating the `site.conf` configuration file.

1. Edit the `site.conf` file locally. Add `index.php` to the `index` line, and save the file.

   ```nginx
   server {
       listen                443 ssl;
       server_name           localhost;
       ssl_certificate       /run/secrets/site.crt;
       ssl_certificate_key   /run/secrets/site.key;

       location / {
           root   /usr/share/nginx/html;
           index  index.html index.htm index.php;
       }
   }
   ```

2. Create a new Docker config using the new `site.conf`, called `site-v2.conf`.

   ```bah
   $ docker config create site-v2.conf site.conf
   ```

3. Update the `nginx` service to use the new config instead of the old one.

   ```console
   $ docker service update \
     --config-rm site.conf \
     --config-add source=site-v2.conf,target=/etc/nginx/conf.d/site.conf,mode=0440 \
     nginx
   ```

4. Verify that the `nginx` service is fully re-deployed, using `docker service ps nginx`. When it is, you can remove the old `site.conf` config.

   ```console
   $ docker config rm site.conf
   ```

5. To clean up, you can remove the `nginx` service, as well as the secrets and configs.

   ```console
   $ docker service rm nginx

   $ docker secret rm site.crt site.key

   $ docker config rm site-v2.conf
   ```

You have now updated your `nginx` service's configuration without the need to rebuild its image.

----
url: https://docs.docker.com/reference/cli/docker/buildx/dap/
----

# docker buildx dap

***

| Description | Start debug adapter protocol compatible debugger |
| ----------- | ------------------------------------------------ |

## [Description](#description)

Start debug adapter protocol compatible debugger

## [Subcommands](#subcommands)

| Command                                                                                     | Description   |
| ------------------------------------------------------------------------------------------- | ------------- |
| [`docker buildx dap build`](https://docs.docker.com/reference/cli/docker/buildx/dap/build/) | Start a build |

----
url: https://docs.docker.com/enterprise/security/single-sign-on/faqs/users-faqs/
----

# SSO user management FAQs

***

Table of contents

***

## [Do I need to manually add users to my organization?](#do-i-need-to-manually-add-users-to-my-organization)

No, you don't need to manually add users to your organization. Just ensure user accounts exist in your IdP. When users sign in to Docker with their domain email address, they're automatically added to the organization after successful authentication.

## [Can users use different email addresses to authenticate through SSO?](#can-users-use-different-email-addresses-to-authenticate-through-sso)

All users must authenticate using the email domain specified during SSO setup. Users with email addresses that don't match the verified domain can sign in as guests with username and password if SSO isn't enforced, but only if they've been invited.

## [How will users know they're being added to a Docker organization?](#how-will-users-know-theyre-being-added-to-a-docker-organization)

When SSO is turned on, users are prompted to authenticate through SSO the next time they sign in to Docker Hub or Docker Desktop. The system detects their domain email and prompts them to sign in with SSO credentials instead.

For CLI access, users must authenticate using personal access tokens.

## [Can I convert existing users from non-SSO to SSO accounts?](#can-i-convert-existing-users-from-non-sso-to-sso-accounts)

Yes, you can convert existing users to SSO accounts. Ensure users have:

* Company domain email addresses and accounts in your IdP
* Docker Desktop version 4.4.2 or later
* Personal access tokens created to replace passwords for CLI access
* CI/CD pipelines updated to use PATs instead of passwords

For detailed instructions, see [Configure single sign-on](https://docs.docker.com/enterprise/security/single-sign-on/connect/).

## [Is Docker SSO fully synced with the IdP?](#is-docker-sso-fully-synced-with-the-idp)

Docker SSO provides Just-in-Time (JIT) provisioning by default. Users are provisioned when they authenticate with SSO. If users leave the organization, administrators must manually [remove the user](https://docs.docker.com/admin/organization/manage/members/#remove-members-from-teams) from the organization.

[SCIM](https://docs.docker.com/enterprise/security/provisioning/scim/) provides full synchronization with users and groups. When using SCIM, the recommended configuration is to turn off JIT so all auto-provisioning is handled by SCIM.

Additionally, you can use the [Docker Hub API](https://docs.docker.com/reference/api/hub/latest/) to complete this process.

## [How does turning off Just-in-Time provisioning affect user sign-in?](#how-does-turning-off-just-in-time-provisioning-affect-user-sign-in)

When JIT is turned off (available with SCIM in the Admin Console), users must be organization members or have pending invitations to access Docker. Users who don't meet these criteria get an "Access denied" error and need administrator invitations.

See [SSO authentication with JIT provisioning disabled](https://docs.docker.com/enterprise/security/provisioning/just-in-time/#sso-authentication-with-jit-provisioning-disabled).

## [Can someone join an organization without an invitation?](#can-someone-join-an-organization-without-an-invitation)

Not without SSO. Joining requires an invite from an organization owner. When SSO is enforced, users with verified domain emails can automatically join the organization when they sign in.

## [What happens to existing licensed users when SCIM is turned on?](#what-happens-to-existing-licensed-users-when-scim-is-turned-on)

Turning on SCIM doesn't immediately remove or modify existing licensed users. They retain current access and roles, but you'll manage them through your IdP after SCIM is active. If SCIM is later turned off, previously SCIM-managed users remain in Docker but are no longer automatically updated based on your IdP.

## [Is user information visible in Docker Hub?](#is-user-information-visible-in-docker-hub)

All Docker accounts have public profiles associated with their namespace. If you don't want user information (like full names) to be visible, remove those attributes from your SSO and SCIM mappings, or use different identifiers to replace users' full names.

----
url: https://docs.docker.com/reference/cli/sbx/policy/allow/
----

# sbx policy allow

| Description | Add an allow rule for sandboxes |
| ----------- | ------------------------------- |
| Usage       | `sbx policy allow COMMAND`      |

## [Description](#description)

Add a rule that permits sandboxes to access specified resources.

Allowed resources are accessible within the selected policy scope. If a resource matches both an allow and a deny rule, the deny rule takes precedence.

## [Commands](#commands)

| Command                                                                                       | Description                             |
| --------------------------------------------------------------------------------------------- | --------------------------------------- |
| [`sbx policy allow network`](https://docs.docker.com/reference/cli/sbx/policy/allow/network/) | Allow network access to specified hosts |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/offload/optimize/
----

# Optimize Docker Offload usage

***

Table of contents

***

Docker Offload builds and runs your containers remotely, not on the machine where you invoke the commands. This means that files must be transferred from your local system to the cloud over the network.

Transferring files over the network introduces higher latency and lower bandwidth compared to local transfers.

Even with optimizations, large projects or slower network connections can lead to longer transfer times. Here are several ways to optimize your setup for Docker Offload:

* [Use `.dockerignore` files](#dockerignore-files)
* [Choose slim base images](#slim-base-images)
* [Use multi-stage builds](#multi-stage-builds)
* [Fetch remote files during the build](#fetch-remote-files-in-build)
* [Leverage multi-threaded tools](#multi-threaded-tools)

For general Dockerfile tips, see [Building best practices](https://docs.docker.com/build/building/best-practices/).

## [dockerignore files](#dockerignore-files)

A [`.dockerignore` file](https://docs.docker.com/build/concepts/context/#dockerignore-files) lets you specify which local files should *not* be included in the build context. Files excluded by these patterns won’t be uploaded to Docker Offload during a build.

Typical items to ignore:

* `.git` – avoids transferring your version history. (Note: you won’t be able to run `git` commands in the build.)
* Build artifacts or locally generated binaries.
* Dependency folders such as `node_modules`, if those are restored in the build process.

As a rule of thumb, your `.dockerignore` should be similar to your `.gitignore`.

## [Slim base images](#slim-base-images)

Smaller base images in your `FROM` instructions can reduce final image size and improve build performance. The [`alpine`](https://hub.docker.com/_/alpine) image is a good example of a minimal base.

For fully static binaries, you can use [`scratch`](https://hub.docker.com/_/scratch), which is an empty base image.

## [Multi-stage builds](#multi-stage-builds)

[Multi-stage builds](/build/building/multi-stage/) let you separate build-time and runtime environments in your Dockerfile. This not only reduces the size of the final image but also allows for parallel stage execution during the build.

Use `COPY --from` to copy files from earlier stages or external images. This approach helps minimize unnecessary layers and reduce final image size.

## [Fetch remote files in build](#fetch-remote-files-in-build)

When possible, download large files from the internet during the build itself instead of bundling them in your local context. This avoids network transfer from your client to Docker Offload.

You can do this using:

* The Dockerfile [`ADD` instruction](/reference/dockerfile/#add)
* `RUN` commands like `wget`, `curl`, or `rsync`

### [Multi-threaded tools](#multi-threaded-tools)

Some build tools, such as `make`, are single-threaded by default. If the tool supports it, configure it to run in parallel. For example, use `make --jobs=4` to run four jobs simultaneously.

Taking advantage of available CPU resources in the cloud can significantly improve build time.

----
url: https://docs.docker.com/reference/compose-file/legacy-versions/
----

# Legacy versions

***

***

The legacy versions of the Compose file reference has moved to the [V1 branch of the Compose repository](https://github.com/docker/compose/tree/v1/docs). They are no longer being actively maintained.

The latest and recommended version of the Compose file format is defined by the [Compose Specification](https://docs.docker.com/reference/compose-file/). This format merges the 2.x and 3.x versions and is implemented by **Compose 1.27.0+**. For more information, see the [History and development of Docker Compose](https://docs.docker.com/compose/intro/history/).

----
url: https://docs.docker.com/reference/samples/ruby/
----

# Ruby samples

| Name                                                                                                             | Description                                                                                         |
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [Compose and Rails](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/rails/) | This Quickstart guide shows you how to use Docker Compose to set up and run a Rails/PostgreSQL app. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/desktop/setup/install/linux/debian/
----

# Install Docker Desktop on Debian

***

Table of contents

***

> **Docker Desktop terms**
>
> Commercial use of Docker Desktop in larger enterprises (more than 250 employees OR more than $10 million USD in annual revenue) requires a [paid subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopDebianInstall).

This page contains information on how to install, launch, and upgrade Docker Desktop on a Debian distribution.

## [Prerequisites](#prerequisites)

To install Docker Desktop successfully, you must:

* Meet the [general system requirements](https://docs.docker.com/desktop/setup/install/linux/#general-system-requirements).

* Have a 64-bit version of Debian 12.

* For a Gnome Desktop environment, you must also install AppIndicator and KStatusNotifierItem [Gnome extensions](https://extensions.gnome.org/extension/615/appindicator-support/).

* If you're not using GNOME, you must install `gnome-terminal` to enable terminal access from Docker Desktop:

  ```console
  $ sudo apt install gnome-terminal
  ```

## [Install Docker Desktop](#install-docker-desktop)

Recommended approach to install Docker Desktop on Debian:

1. Set up Docker's `apt` repository. See step one of [Install using the `apt` repository](https://docs.docker.com/engine/install/debian/#install-using-the-repository).

2. Download the latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-amd64.deb?utm_source=docker\&utm_medium=webreferral\&utm_campaign=docs-driven-download-linux-amd64). For checksums, see the [Release notes](https://docs.docker.com/desktop/release-notes/).

3. Install the package using `apt`:

```console
$ sudo apt-get update
$ sudo apt-get install ./docker-desktop-amd64.deb
```

> Note
>
> At the end of the installation process, `apt` displays an error due to installing a downloaded package. You can ignore this error message.
>
> ```text
> N: Download is performed unsandboxed as root, as file '/home/user/Downloads/docker-desktop.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
> ```

By default, Docker Desktop is installed at `/opt/docker-desktop`.

The DEB package includes a post-install script that completes additional setup steps automatically.

```console
$ systemctl --user start docker-desktop
```

When Docker Desktop starts, it creates a dedicated [context](/engine/context/working-with-contexts) that the Docker CLI can use as a target and sets it as the current context in use. This is to avoid a clash with a local Docker Engine that may be running on the Linux host and using the default context. On shutdown, Docker Desktop resets the current context to the previous one.

The Docker Desktop installer updates Docker Compose and the Docker CLI binaries on the host. It installs Docker Compose V2 and gives users the choice to link it as docker-compose from the Settings panel. Docker Desktop installs the new Docker CLI binary that includes cloud-integration capabilities in `/usr/local/bin/com.docker.cli` and creates a symlink to the classic Docker CLI at `/usr/local/bin`.

After you’ve successfully installed Docker Desktop, you can check the versions of these binaries by running the following commands:

```console
$ docker compose version
Docker Compose version v2.39.4

$ docker --version
Docker version 28.4.0, build d8eb465

$ docker version
Client:
 Version:           28.4.0
 API version:       1.51
 Go version:        go1.24.7
<...>
```

To enable Docker Desktop to start on sign in, from the Docker menu, select **Settings** > **General** > **Start Docker Desktop when you sign in to your computer**.

Alternatively, open a terminal and run:

```console
$ systemctl --user enable docker-desktop
```

To stop Docker Desktop, select the Docker menu icon to open the Docker menu and select **Quit Docker Desktop**.

Alternatively, open a terminal and run:

```console
$ systemctl --user stop docker-desktop
```

## [Upgrade Docker Desktop](#upgrade-docker-desktop)

Once a new version for Docker Desktop is released, the Docker UI shows a notification. You need to download the new package each time you want to upgrade Docker Desktop and run:

```console
$ sudo apt-get install ./docker-desktop-amd64.deb
```

## [Next steps](#next-steps)

* Explore [Docker's subscriptions](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopDebianInstall) to see what Docker can offer you.

----
url: https://docs.docker.com/guides/docker-compose/common-questions/
----

# Common challenges and questions

***

Table of contents

***

### [Do I need to maintain a separate Compose file for my development, testing, and staging environments?](#do-i-need-to-maintain-a-separate-compose-file-for-my-development-testing-and-staging-environments)

You don't necessarily need to maintain entirely separate Compose files for your development, testing, and staging environments. You can define all your services in a single Compose file (`compose.yaml`). You can use profiles to group service configurations specific to each environment (`dev`, `test`, `staging`).

When you need to spin up an environment, you can activate the corresponding profiles. For example, to set up the development environment:

```console
$ docker compose --profile dev up
```

This command starts only the services associated with the `dev` profile, leaving the rest inactive.

For more information on using profiles, see [Using profiles with Compose](/compose/how-tos/profiles/).

### [How can I enforce the database service to start up before the frontend service?](#how-can-i-enforce-the-database-service-to-start-up-before-the-frontend-service)

Docker Compose ensures services start in a specific order by using the `depends_on` property. This tells Compose to start the database service before even attempting to launch the frontend service. This is crucial since applications often rely on databases being ready for connections.

However, `depends_on` only guarantees the order, not that the database is fully initialized. For a more robust approach, especially if your application relies on a prepared database (e.g., after migrations), consider [health checks](https://docs.docker.com/reference/compose-file/services/#healthcheck). Here, you can configure the frontend to wait until the database passes its health check before starting. This ensures the database is not only up but also ready to handle requests.

For more information on setting the startup order of your services, see [Control startup and shutdown order in Compose](/compose/how-tos/startup-order/).

### [Can I use Compose to build a Docker image?](#can-i-use-compose-to-build-a-docker-image)

Yes, you can use Docker Compose to build Docker images. Docker Compose is a tool for defining and running multi-container applications. Even if your application isn't a multi-container application, Docker Compose can make it easier to run by defining all the `docker run` options in a file.

To use Compose, you need a `compose.yaml` file. In this file, you can specify the build context and Dockerfile for each service. When you run the command `docker compose up --build`, Docker Compose will build the images for each service and then start the containers.

For more information on building Docker images using Compose, see the [Compose Build Specification](/compose/compose-file/build/).

### [What is the difference between Docker Compose and Dockerfile?](#what-is-the-difference-between-docker-compose-and-dockerfile)

A Dockerfile provides instructions to build a container image while a Compose file defines your running containers. Quite often, a Compose file references a Dockerfile to build an image to use for a particular service.

### [What is the difference between the `docker compose up` and `docker compose run` commands?](#what-is-the-difference-between-the-docker-compose-up-and-docker-compose-run-commands)

The `docker compose up` command creates and starts all your services. It's perfect for launching your development environment or running the entire application. The `docker compose run` command focuses on individual services. It starts a specified service along with its dependencies, allowing you to run tests or perform one-off tasks within that container.

----
url: https://docs.docker.com/desktop/use-desktop/volumes/
----

# Explore the Volumes view in Docker Desktop

***

Table of contents

***

The **Volumes** view in Docker Desktop lets you create, inspect, delete, clone, empty, export, and import [Docker volumes](https://docs.docker.com/engine/storage/volumes/). You can also browse files and folders in volumes and see which containers are using them.

## [View your volumes](#view-your-volumes)

You can view the following information about your volumes:

* Name: The name of the volume.
* Status: Whether the volume is in-use by a container or not.
* Created: How long ago the volume was created.
* Size: The size of the volume.
* Scheduled exports: Whether a scheduled export is active or not.

By default, the **Volumes** view displays a list of all the volumes.

You can filter and sort volumes as well as modify which columns are displayed by doing the following:

* Filter volumes by name: Use the **Search** field.
* Filter volumes by status: To the right of the search bar, filter volumes by **In use** or **Unused**.
* Sort volumes: Select a column name to sort the volumes.
* Customize columns: To the right of the search bar, choose what volume information to display.

## [Create a volume](#create-a-volume)

You use the following steps to create an empty volume. Alternatively, if you [start a container with a volume](https://docs.docker.com/engine/storage/volumes/#start-a-container-with-a-volume) that doesn't yet exist, Docker creates the volume for you.

To create a volume:

1. In the **Volumes** view, select the **Create** button.
2. In the **New Volume** modal, specify a volume name, and then select **Create**.

To use the volume with a container, see [Use volumes](https://docs.docker.com/engine/storage/volumes/#start-a-container-with-a-volume).

## [Inspect a volume](#inspect-a-volume)

To explore the details of a specific volume, select a volume from the list. This opens the detailed view.

The **Container in-use** tab displays the name of the container using the volume, the image name, the port number used by the container, and the target. A target is a path inside a container that gives access to the files in the volume.

The **Stored data** tab displays the files and folders in the volume and the file size. To save a file or a folder, right-click on the file or folder to display the options menu, select **Save as...**, and then specify a location to download the file.

To delete a file or a folder from the volume, right-click on the file or folder to display the options menu, select **Delete**, and then select **Delete** again to confirm.

The **Exports** tab lets you [export the volume](#export-a-volume).

## [Clone a volume](#clone-a-volume)

Cloning a volume creates a new volume with a copy of all of the data from the cloned volume. When cloning a volume used by one or more running containers, the containers are temporarily stopped while Docker clones the data, and then restarted when the cloning process is completed.

To clone a volume:

1. Sign in to Docker Desktop. You must be signed in to clone a volume.
2. In the **Volumes** view, select the **Clone** icon in the **Actions** column for the volume you want to clone.
3. In the **Clone a volume** modal, specify a **Volume name**, and then select **Clone**.

## [Delete one or more volumes](#delete-one-or-more-volumes)

Deleting a volume deletes the volume and all its data. When a container is using a volume, you can't delete the volume, even if the container is stopped. You must first stop and remove any containers using the volume before you can delete the volume.

To delete a volume:

1. In the **Volumes** view, select **Delete** icon in the **Actions** column for the volume you want to delete.
2. In the **Delete volume?** modal, select **Delete forever**.

To delete multiple volumes:

1. In the **Volumes** view, select the checkbox next to all the volumes you want to delete.
2. Select **Delete**.
3. In the **Delete volumes?** modal, select **Delete forever**.

## [Empty a volume](#empty-a-volume)

Emptying a volume deletes all a volume's data, but doesn't delete the volume. When emptying a volume used by one or more running containers, the containers are temporarily stopped while Docker empties the data, and then restarted when the emptying process is completed.

To empty a volume:

1. Sign in to Docker Desktop. You must be signed in to empty a volume.
2. In the **Volumes** view, select the volume you want to empty.
3. Next to **Import**, select the **More volume actions** icon, and then select **Empty volume**.
4. In the **Empty a volume?** modal, select **Empty**.

## [Export a volume](#export-a-volume)

You can export the content of a volume to a local file, a local image, and to an image in Docker Hub, or to a supported cloud provider. When exporting content from a volume used by one or more running containers, the containers are temporarily stopped while Docker exports the content, and then restarted when the export process is completed.

You can either [export a volume now](#export-a-volume-now) or [schedule a recurring export](#schedule-a-volume-export).

### [Export a volume now](#export-a-volume-now)

1. Sign in to Docker Desktop. You must be signed in to export a volume.

2. In the **Volumes** view, select the volume you want to export.

3. Select the **Exports** tab.

4. Select **Quick export**.

5. Select whether to export the volume to **Local or Hub storage** or **External cloud storage**, then specify the following additional details depending on your selection.

   * **Local file**: Specify a file name and select a folder.
   * **Local image**: Select a local image to export the content to. Any existing data in the image will be replaced by the exported content.
   * **New image**: Specify a name for the new image.
   * **Registry**: Specify a Docker Hub repository.

   You must have a [Docker Business subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopVolumes) to export to an external cloud provider.

   Select your cloud provider and then specify the URL to upload to the storage. Refer to the following documentation for your cloud provider to learn how to obtain a URL.

   * Amazon Web Services: [Create a presigned URL of Amazon S3 using an AWS SDK](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example_s3_Scenario_PresignedUrl_section.html)
   * Microsoft Azure: [Generate a SAS token and URL](https://learn.microsoft.com/en-us/azure/data-explorer/kusto/api/connection-strings/generate-sas-token)
   * Google Cloud: [Create a signed URL to upload an object](https://cloud.google.com/storage/docs/access-control/signing-urls-with-helpers#upload-object)

6. Select **Save**.

### [Schedule a volume export](#schedule-a-volume-export)

1. Sign in to Docker Desktop. You must be signed in and have a paid [Docker subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopVolumes) to schedule a volume export.

2. In the **Volumes** view, select the volume you want to export.

3. Select the **Exports** tab.

4. Select **Schedule export**.

5. In **Recurrence**, select how often the export occurs, and then specify the following additional details based on your selection.

   * **Daily**: Specify the time that the backup occurs each day.
   * **Weekly**: Specify one or more days, and the time that the backup occurs each week.
   * **Monthly**: Specify which day of the month and the time that the backup occurs each month.

6. Select whether to export the volume to **Local or Hub storage** or **External cloud storage**, then specify the following additional details depending on your selection.

   * **Local file**: Specify a file name and select a folder.
   * **Local image**: Select a local image to export the content to. Any existing data in the image will be replaced by the exported content.
   * **New image**: Specify a name for the new image.
   * **Registry**: Specify a Docker Hub repository.

   You must have a [Docker Business subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsDesktopVolumes) to export to an external cloud provider.

   Select your cloud provider and then specify the URL to upload to the storage. Refer to the following documentation for your cloud provider to learn how to obtain a URL.

   * Amazon Web Services: [Create a presigned URL of Amazon S3 using an AWS SDK](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example_s3_Scenario_PresignedUrl_section.html)
   * Microsoft Azure: [Generate a SAS token and URL](https://learn.microsoft.com/en-us/azure/data-explorer/kusto/api/connection-strings/generate-sas-token)
   * Google Cloud: [Create a signed URL to upload an object](https://cloud.google.com/storage/docs/access-control/signing-urls-with-helpers#upload-object)

7. Select **Save**.

## [Import a volume](#import-a-volume)

You can import a local file, a local image, or an image from Docker Hub. Any existing data in the volume is replaced by the imported content. When importing content to a volume used by one or more running containers, the containers are temporarily stopped while Docker imports the content, and then restarted when the import process is completed.

To import a volume:

1. Sign in to Docker Desktop. You must be signed in to import a volume.

2. Optionally, [create](#create-a-volume) a new volume to import the content into.

3. Select the volume you want to import content in to.

4. Select **Import**.

5. Select where the content is coming from and then specify the following additional details depending on your selection:

   * **Local file**: Select the file that contains the content.
   * **Local image**: Select the local image that contains the content.
   * **Registry**: Specify the image from Docker Hub that contains the content.

6. Select **Import**.

## [Additional resources](#additional-resources)

* [Persisting container data](https://docs.docker.com/get-started/docker-concepts/running-containers/persisting-container-data/)
* [Use volumes](https://docs.docker.com/engine/storage/volumes/)

----
url: https://docs.docker.com/reference/cli/docker/compose/bridge/
----

# docker compose bridge

***

| Description | Convert compose files into another model |
| ----------- | ---------------------------------------- |

## [Description](#description)

Convert compose files into another model

## [Subcommands](#subcommands)

| Command                                                                                                                 | Description                                                                  |
| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [`docker compose bridge convert`](https://docs.docker.com/reference/cli/docker/compose/bridge/convert/)                 | Convert compose files to Kubernetes manifests, Helm charts, or another model |
| [`docker compose bridge transformations`](https://docs.docker.com/reference/cli/docker/compose/bridge/transformations/) | Manage transformation images                                                 |

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/server/ls/
----

# docker mcp profile server ls

***

| Description                                                               | List servers across profiles     |
| ------------------------------------------------------------------------- | -------------------------------- |
| Usage                                                                     | `docker mcp profile server ls`   |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker mcp profile server list` |

## [Description](#description)

List all servers grouped by profile.

Use --filter to search for servers matching a query (case-insensitive substring matching on server names). Filters use key=value format (e.g., name=github, profile=my-dev-env).

## [Options](#options)

| Option         | Default | Description                                           |
| -------------- | ------- | ----------------------------------------------------- |
| `-f, --filter` |         | Filter output (e.g., name=github, profile=my-dev-env) |
| `--format`     | `human` | Supported: json, yaml, human.                         |

## [Examples](#examples)

# [List all servers across all profiles](#list-all-servers-across-all-profiles)

docker mcp profile server ls

# [Filter servers by name](#filter-servers-by-name)

docker mcp profile server ls --filter name=github

# [Show servers from a specific profile](#show-servers-from-a-specific-profile)

docker mcp profile server ls --filter profile=my-dev-env

# [Combine multiple filters (using short flag)](#combine-multiple-filters-using-short-flag)

docker mcp profile server ls -f name=slack -f profile=my-dev-env

# [Output in JSON format](#output-in-json-format)

docker mcp profile server ls --format json

----
url: https://docs.docker.com/compose/how-tos/file-watch/
----

# Use Compose Watch

***

Table of contents

***

Requires: Docker Compose [2.22.0](https://github.com/docker/compose/releases/tag/v2.22.0) and later

The `watch` attribute automatically updates and previews your running Compose services as you edit and save your code. For many projects, this enables a hands-off development workflow once Compose is running, as services automatically update themselves when you save your work.

`watch` adheres to the following file path rules:

* All paths are relative to the project directory, apart from ignore file patterns

* Directories are watched recursively

* Glob patterns aren't supported

* Rules from `.dockerignore` apply

  * Use `ignore` option to define additional paths to be ignored (same syntax)
  * Temporary/backup files for common IDEs (Vim, Emacs, JetBrains, & more) are ignored automatically
  * `.git` directories are ignored automatically

You don't need to switch on `watch` for all services in a Compose project. In some instances, only part of the project, for example the Javascript frontend, might be suitable for automatic updates.

Compose Watch is designed to work with services built from local source code using the `build` attribute. It doesn't track changes for services that rely on pre-built images specified by the `image` attribute.

## [Compose Watch versus bind mounts](#compose-watch-versus-bind-mounts)

Compose supports sharing a host directory inside service containers. Watch mode does not replace this functionality but exists as a companion specifically suited to developing in containers.

More importantly, `watch` allows for greater granularity than is practical with a bind mount. Watch rules let you ignore specific files or entire directories within the watched tree.

For example, in a JavaScript project, ignoring the `node_modules/` directory has two benefits:

* Performance. File trees with many small files can cause a high I/O load in some configurations
* Multi-platform. Compiled artifacts cannot be shared if the host OS or architecture is different from the container

For example, in a Node.js project, it's not recommended to sync the `node_modules/` directory. Even though JavaScript is interpreted, `npm` packages can contain native code that is not portable across platforms.

## [Configuration](#configuration)

The `watch` attribute defines a list of rules that control automatic service updates based on local file changes.

Each rule requires a `path` pattern and `action` to take when a modification is detected. There are two possible actions for `watch` and depending on the `action`, additional fields might be accepted or required.

Watch mode can be used with many different languages and frameworks. The specific paths and rules will vary from project to project, but the concepts remain the same.

### [Prerequisites](#prerequisites)

In order to work properly, `watch` relies on common executables. Make sure your service image contains the following binaries:

* stat
* mkdir
* rmdir

`watch` also requires that the container's `USER` can write to the target path so it can update files. A common pattern is for initial content to be copied into the container using the `COPY` instruction in a Dockerfile. To ensure such files are owned by the configured user, use the `COPY --chown` flag:

```dockerfile
# Run as a non-privileged user
FROM node:18
RUN useradd -ms /bin/sh -u 1001 app
USER app

# Install dependencies
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install

# Copy source files into application directory
COPY --chown=app:app . /app
```

### [`action`](#action)

#### [Sync](#sync)

If `action` is set to `sync`, Compose makes sure any changes made to files on your host automatically match with the corresponding files within the service container.

`sync` is ideal for frameworks that support "Hot Reload" or equivalent functionality.

More generally, `sync` rules can be used in place of bind mounts for many development use cases.

#### [Rebuild](#rebuild)

If `action` is set to `rebuild`, Compose automatically builds a new image with BuildKit and replaces the running service container.

The behavior is the same as running `docker compose up --build <svc>`.

Rebuild is ideal for compiled languages or as a fallback for modifications to particular files that require a full image rebuild (e.g. `package.json`).

#### [Sync + Restart](#sync--restart)

If `action` is set to `sync+restart`, Compose synchronizes your changes with the service containers and restarts them.

`sync+restart` is ideal when the config file changes, and you don't need to rebuild the image but just restart the main process of the service containers. It will work well when you update a database configuration or your `nginx.conf` file, for example.

> Tip
>
> Optimize your `Dockerfile` for speedy incremental rebuilds with [image layer caching](/build/cache) and [multi-stage builds](/build/building/multi-stage/).

### [`path` and `target`](#path-and-target)

The `target` field controls how the path is mapped into the container.

For `path: ./app/html` and a change to `./app/html/index.html`:

* `target: /app/html` -> `/app/html/index.html`
* `target: /app/static` -> `/app/static/index.html`
* `target: /assets` -> `/assets/index.html`

### [`ignore`](#ignore)

The `ignore` patterns are relative to the `path` defined in the current `watch` action, not to the project directory. In the following Example 1, the ignore path would be relative to the `./web` directory specified in the `path` attribute.

### [`initial_sync`](#initial_sync)

When using a `sync+x` action, the `initial_sync` attribute tells Compose to ensure files that are part of the defined `path` are up to date before starting a new watch session.

## [Example 1](#example-1)

This minimal example targets a Node.js application with the following structure:

```text
myproject/
├── web/
│   ├── App.jsx
│   ├── index.js
│   └── node_modules/
├── Dockerfile
├── compose.yaml
└── package.json
```

```yaml
services:
  web:
    build: .
    command: npm start
    develop:
      watch:
        - action: sync
          path: ./web
          target: /src/web
          initial_sync: true
          ignore:
            - node_modules/
        - action: rebuild
          path: package.json
```

In this example, when running `docker compose up --watch`, a container for the `web` service is launched using an image built from the `Dockerfile` in the project's root. The `web` service runs `npm start` for its command, which then launches a development version of the application with Hot Module Reload enabled in the bundler (Webpack, Vite, Turbopack, etc).

After the service is up, the watch mode starts monitoring the target directories and files. Then, whenever a source file in the `web/` directory is changed, Compose syncs the file to the corresponding location under `/src/web` inside the container. For example, `./web/App.jsx` is copied to `/src/web/App.jsx`.

Once copied, the bundler updates the running application without a restart.

And in this case, the `ignore` rule would apply to `myproject/web/node_modules/`, not `myproject/node_modules/`.

Unlike source code files, adding a new dependency can’t be done on-the-fly, so whenever `package.json` is changed, Compose rebuilds the image and recreates the `web` service container.

This pattern can be followed for many languages and frameworks, such as Python with Flask: Python source files can be synced while a change to `requirements.txt` should trigger a rebuild.

## [Example 2](#example-2)

Adapting the previous example to demonstrate `sync+restart`:

```yaml
services:
  web:
    build: .
    command: npm start
    develop:
      watch:
        - action: sync
          path: ./web
          target: /app/web
          ignore:
            - node_modules/
        - action: sync+restart
          path: ./proxy/nginx.conf
          target: /etc/nginx/conf.d/default.conf

  backend:
    build:
      context: backend
      target: builder
```

This setup demonstrates how to use the `sync+restart` action in Docker Compose to efficiently develop and test a Node.js application with a frontend web server and backend service. The configuration ensures that changes to the application code and configuration files are quickly synchronized and applied, with the `web` service restarting as needed to reflect the changes.

## [Use `watch`](#use-watch)

1. Add `watch` sections to one or more services in `compose.yaml`.
2. Run `docker compose up --watch` to build and launch a Compose project and start the file watch mode.
3. Edit service source files using your preferred IDE or editor.

> Note
>
> Watch can also be used with the dedicated `docker compose watch` command if you don't want to get the application logs mixed with the (re)build logs and filesystem sync events.

> Tip
>
> Check out [`dockersamples/avatars`](https://github.com/dockersamples/avatars), or [local setup for Docker docs](https://github.com/docker/docs/blob/main/CONTRIBUTING.md) for a demonstration of Compose `watch`.

## [Reference](#reference)

* [Compose Develop Specification](https://docs.docker.com/reference/compose-file/develop/)

----
url: https://docs.docker.com/guides/lab-creating-ai-product-reviewer/
----

[Lab: Building an AI Product Reviewer](https://docs.docker.com/guides/lab-creating-ai-product-reviewer/)

Hands-on lab: Build an AI pipeline that classifies product reviews by sentiment, clusters them by topic using embeddings, extracts actionable features, and generates context-aware responses — all running locally.

AI Labs

60 minutes

Resources:

* [Docker Model Runner docs](/ai/model-runner/)
* [Labspace repository](https://github.com/dockersamples/labspace-creating-ai-product-reviewer)

[« Back to all guides](/guides/)

# Lab: Building an AI Product Reviewer

***

Table of contents

***

Build a complete feedback analysis pipeline for a fictional AI product called Jarvis. You'll write Node.js code that runs local LLMs and embedding models via Docker Model Runner — no API keys, no cloud subscriptions, no data leaving your machine.

## [Launch the lab](#launch-the-lab)

1. Start the labspace:

   ```console
   $ docker compose -p labspace -f oci://dockersamples/labspace-creating-ai-product-reviewer up -d
   ```

2. Open your browser to <http://localhost:3030>.

3. When you're done, tear down the labspace:

   ```console
   $ docker compose -p labspace down
   ```

## [What you'll learn](#what-youll-learn)

By the end of this Labspace, you will have completed the following:

* Run LLMs locally via Docker Model Runner's OpenAI-compatible API
* Connect a Node.js app to Docker Model Runner using the OpenAI SDK and the Compose `models:` integration
* Perform sentiment analysis using low-temperature LLM classification
* Use embeddings and cosine similarity to cluster semantically related feedback
* Extract structured data from an LLM using `response_format: { type: 'json_object' }`
* Generate context-aware responses to reviews informed by extracted product features

## [Modules](#modules)

| # | Module                              | Description                                                                        |
| - | ----------------------------------- | ---------------------------------------------------------------------------------- |
| 1 | Introduction                        | Overview of the pipeline and Docker Model Runner setup                             |
| 2 | Project Setup & Docker Model Runner | Explore the starter project and wire up Compose model integration                  |
| 3 | Generating Synthetic Feedback       | Use the LLM to generate realistic product reviews as test data                     |
| 4 | Sentiment Analysis                  | Classify reviews as positive, negative, or neutral with low-temperature generation |
| 5 | Embeddings & Semantic Clustering    | Group related reviews using vector embeddings and cosine similarity                |
| 6 | Features & Responses                | Extract actionable features and generate context-aware review responses            |
| 7 | Wrap-up                             | Summary of techniques and ideas for extending the pipeline                         |

----
url: https://docs.docker.com/guides/testcontainers-dotnet-getting-started/
----

# Getting started with Testcontainers for .NET

Table of contents

***

Learn how to create a .NET application and test database interactions using Testcontainers for .NET with a real PostgreSQL instance.

**Time to complete** 20 minutes

In this guide, you will learn how to:

* Create a .NET solution with a source and test project
* Implement a `CustomerService` that manages customer records in PostgreSQL
* Write integration tests using Testcontainers and xUnit
* Manage container lifecycle with `IAsyncLifetime`

## [Prerequisites](#prerequisites)

* .NET 8.0+ SDK
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-dotnet-getting-started/create-project/)

   Set up a .NET solution with a PostgreSQL-backed customer service.

2. [Write tests](https://docs.docker.com/guides/testcontainers-dotnet-getting-started/write-tests/)

   Write integration tests using Testcontainers for .NET and xUnit with a real PostgreSQL database.

3. [Run tests](https://docs.docker.com/guides/testcontainers-dotnet-getting-started/run-tests/)

   Run your Testcontainers-based integration tests and explore next steps.

----
url: https://docs.docker.com/reference/samples/python/
----

# Python samples

| Name                                                                                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [NGINX / Flask / MongoDB](https://github.com/docker/awesome-compose/tree/master/nginx-flask-mongo)                 | A sample Python/Flask application with Nginx proxy and a Mongo database.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [NGINX / Flask / MySQL](https://github.com/docker/awesome-compose/tree/master/nginx-flask-mysql)                   | A sample Python/Flask application with an Nginx proxy and a MySQL database.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [NGINX / WSGI / Flask](https://github.com/docker/awesome-compose/tree/master/nginx-wsgi-flask)                     | A sample Nginx reverse proxy with a Flask backend using WSGI.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [Python / Flask / Redis](https://github.com/docker/awesome-compose/tree/master/flask-redis)                        | A sample Python/Flask and a Redis database.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [Flask](https://github.com/docker/awesome-compose/tree/master/flask)                                               | A sample Flask application.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [Django](https://github.com/docker/awesome-compose/tree/master/django)                                             | A sample Django application.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [FastAPI](https://github.com/docker/awesome-compose/tree/master/fastapi)                                           | A sample FastAPI application.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [example-voting-app](https://github.com/dockersamples/example-voting-app)                                          | A sample Docker Compose app.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [Compose and Django](https://github.com/docker/awesome-compose/tree/master/official-documentation-samples/django/) | This quick-start guide demonstrates how to use Docker Compose to set up and run a simple Django/PostgreSQL app.                                                                                                                                                                                                                                                                                                                                                                                           |
| [AI/ML with Docker](https://github.com/docker/genai-stack)                                                         | Get started with AI and ML using Docker, Neo4j, LangChain, and Ollama                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [Agent-to-Agent](https://github.com/docker/compose-for-agents/tree/main/a2a)                                       | This app is a modular AI agent runtime built on Google's Agent Development Kit (ADK) and the A2A (Agent-to-Agent) protocol. It wraps a large language model (LLM)-based agent in an HTTP API and uses structured execution flows with streaming responses, memory, and tools. It is designed to make agents callable as network services and composable with other agents.                                                                                                                                |
| [ADK Multi-Agent Fact Checker](https://github.com/docker/compose-for-agents/tree/main/adk)                         | This project demonstrates a collaborative multi-agent system built with the Agent Development Kit (ADK), where a top-level Auditor agent coordinates the workflow to verify facts. The Critic agent gathers evidence via live internet searches using DuckDuckGo through the Model Context Protocol (MCP), while the Reviser agent analyzes and refines the conclusion using internal reasoning alone. The system showcases how agents with distinct roles and tools can collaborate under orchestration. |
| [DevDuck agents](https://github.com/docker/compose-for-agents/tree/main/adk-cerebras)                              | A multi-agent system for Go programming assistance built with Google Agent Development Kit (ADK). This project features a coordinating agent (DevDuck) that manages two specialized sub-agents (Bob and Cerebras) for different programming tasks.                                                                                                                                                                                                                                                        |
| [Agno](https://github.com/docker/compose-for-agents/tree/main/agno)                                                | This app is a multi-agent orchestration system powered by LLMs (like Qwen and OpenAI) and connected to tools via a Model Control Protocol (MCP) gateway. Its purpose is to retrieve, summarize, and document GitHub issues—automatically creating Notion pages from the summaries. It also supports file content summarization from GitHub.                                                                                                                                                               |
| [CrewAI](https://github.com/docker/compose-for-agents/tree/main/crew-ai)                                           | This project showcases an autonomous, multi-agent virtual marketing team built with CrewAI. It automates the creation of a high-quality, end-to-end marketing strategy — from research to copywriting — using task delegation, web search, and creative synthesis.                                                                                                                                                                                                                                        |
| [SQL Agent with LangGraph](https://github.com/docker/compose-for-agents/tree/main/langgraph)                       | This project demonstrates a zero-config AI agent that uses LangGraph to answer natural language questions by querying a SQL database — all orchestrated with Docker Compose.                                                                                                                                                                                                                                                                                                                              |

----
url: https://docs.docker.com/guides/testcontainers-java-spring-boot-kafka/create-project/
----

# Create the Spring Boot project

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Spring Boot project from [Spring Initializr](https://start.spring.io) by selecting the **Spring for Apache Kafka**, **Spring Data JPA**, **MySQL Driver**, and **Testcontainers** starters.

Alternatively, clone the [guide repository](https://github.com/testcontainers/tc-guide-testing-spring-boot-kafka-listener).

After generating the application, add the Awaitility library as a test dependency. You'll use it later to assert the expectations of an asynchronous process flow.

The key dependencies in `pom.xml` are:

```xml
<properties>
    <java.version>17</java.version>
    <testcontainers.version>2.0.4</testcontainers.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.kafka</groupId>
        <artifactId>spring-kafka</artifactId>
    </dependency>
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.kafka</groupId>
        <artifactId>spring-kafka-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-kafka</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-mysql</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.awaitility</groupId>
        <artifactId>awaitility</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

Using the Testcontainers BOM (Bill of Materials) is recommended so that you don't have to repeat the version for every Testcontainers module dependency.

## [Create the JPA entity](#create-the-jpa-entity)

The application listens to a topic called `product-price-changes`. When a message arrives, it extracts the product code and price from the event payload and updates the price for that product in the MySQL database.

Create `Product.java`:

```java
package com.testcontainers.demo;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import java.math.BigDecimal;

@Entity
@Table(name = "products")
class Product {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;

  @Column(nullable = false, unique = true)
  private String code;

  @Column(nullable = false)
  private String name;

  @Column(nullable = false)
  private BigDecimal price;

  public Product() {}

  public Product(Long id, String code, String name, BigDecimal price) {
    this.id = id;
    this.code = code;
    this.name = name;
    this.price = price;
  }

  public Long getId() {
    return id;
  }

  public void setId(Long id) {
    this.id = id;
  }

  public String getCode() {
    return code;
  }

  public void setCode(String code) {
    this.code = code;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public BigDecimal getPrice() {
    return price;
  }

  public void setPrice(BigDecimal price) {
    this.price = price;
  }
}
```

## [Create the Spring Data JPA repository](#create-the-spring-data-jpa-repository)

Create a repository interface for the `Product` entity with a method to find a product by code and a method to update the price for a given product code:

```java
package com.testcontainers.demo;

import java.math.BigDecimal;
import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

interface ProductRepository extends JpaRepository<Product, Long> {
  Optional<Product> findByCode(String code);

  @Modifying
  @Query("update Product p set p.price = :price where p.code = :productCode")
  void updateProductPrice(
    @Param("productCode") String productCode,
    @Param("price") BigDecimal price
  );
}
```

## [Add a schema creation script](#add-a-schema-creation-script)

Because the application doesn't use an in-memory database, you need to create the MySQL tables. The recommended approach for production is a migration tool like Flyway or Liquibase, but for this guide the built-in Spring Boot schema initialization is sufficient.

Create `src/main/resources/schema.sql`:

```sql
create table products (
      id int NOT NULL AUTO_INCREMENT,
      code varchar(255) not null,
      name varchar(255) not null,
      price numeric(5,2) not null,
      PRIMARY KEY (id),
      UNIQUE (code)
);
```

Enable schema initialization in `src/main/resources/application.properties`:

```properties
spring.sql.init.mode=always
```

## [Create the event payload](#create-the-event-payload)

Create a record named `ProductPriceChangedEvent` that represents the structure of the event payload received from the Kafka topic:

```java
package com.testcontainers.demo;

import java.math.BigDecimal;

record ProductPriceChangedEvent(String productCode, BigDecimal price) {}
```

The sender and receiver agree on the following JSON format:

```json
{
  "productCode": "P100",
  "price": 25.0
}
```

## [Implement the Kafka listener](#implement-the-kafka-listener)

Create `ProductPriceChangedEventHandler.java`, which handles messages from the `product-price-changes` topic and updates the product price in the database:

```java
package com.testcontainers.demo;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Transactional;

@Component
@Transactional
class ProductPriceChangedEventHandler {

  private static final Logger log = LoggerFactory.getLogger(
    ProductPriceChangedEventHandler.class
  );

  private final ProductRepository productRepository;

  ProductPriceChangedEventHandler(ProductRepository productRepository) {
    this.productRepository = productRepository;
  }

  @KafkaListener(topics = "product-price-changes", groupId = "demo")
  public void handle(ProductPriceChangedEvent event) {
    log.info(
      "Received a ProductPriceChangedEvent with productCode:{}: ",
      event.productCode()
    );
    productRepository.updateProductPrice(event.productCode(), event.price());
  }
}
```

The `@KafkaListener` annotation specifies the topic name to listen to. Spring Kafka handles serialization and deserialization based on the properties configured in `application.properties`.

## [Configure Kafka serialization](#configure-kafka-serialization)

Add the following Kafka properties to `src/main/resources/application.properties`:

```properties
######## Kafka Configuration  #########
spring.kafka.bootstrap-servers=localhost:9092
spring.kafka.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer
spring.kafka.producer.value-serializer=org.springframework.kafka.support.serializer.JsonSerializer

spring.kafka.consumer.group-id=demo
spring.kafka.consumer.auto-offset-reset=latest
spring.kafka.consumer.key-deserializer=org.apache.kafka.common.serialization.StringDeserializer
spring.kafka.consumer.value-deserializer=org.springframework.kafka.support.serializer.JsonDeserializer
spring.kafka.consumer.properties.spring.json.trusted.packages=com.testcontainers.demo
```

The `productCode` key is (de)serialized using `StringSerializer`/`StringDeserializer`, and the `ProductPriceChangedEvent` value is (de)serialized using `JsonSerializer`/`JsonDeserializer`.

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-java-spring-boot-kafka/write-tests/)

----
url: https://docs.docker.com/compose/how-tos/project-name/
----

# Specify a project name

***

Table of contents

***

By default, Compose assigns the project name based on the name of the directory that contains the Compose file. You can override this with several methods.

This page offers examples of scenarios where custom project names can be helpful, outlines the various methods to set a project name, and provides the order of precedence for each approach.

> Note
>
> The default project directory is the base directory of the Compose file. A custom value can also be set for it using the [`--project-directory` command line option](/reference/cli/docker/compose/#options).

## [Example use cases](#example-use-cases)

Compose uses a project name to isolate environments from each other. There are multiple contexts where a project name is useful:

* On a development host: Create multiple copies of a single environment, useful for running stable copies for each feature branch of a project.
* On a CI server: Prevent interference between builds by setting the project name to a unique build number.
* On a shared or development host: Avoid interference between different projects that might share the same service names.

## [Set a project name](#set-a-project-name)

Project names must contain only lowercase letters, decimal digits, dashes, and underscores, and must begin with a lowercase letter or decimal digit. If the base name of the project directory or current directory violates this constraint, alternative mechanisms are available.

The precedence order for each method, from highest to lowest, is as follows:

1. The `-p` command line flag.
2. The [COMPOSE\_PROJECT\_NAME environment variable](https://docs.docker.com/compose/how-tos/environment-variables/envvars/).
3. The [top-level `name:` attribute](https://docs.docker.com/reference/compose-file/version-and-name/) in your Compose file. Or the last `name:` if you [specify multiple Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/) in the command line with the `-f` flag.
4. The base name of the project directory containing your Compose file. Or the base name of the first Compose file if you [specify multiple Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/) in the command line with the `-f` flag.
5. The base name of the current directory if no Compose file is specified.

## [What's next?](#whats-next)

* Read up on [working with multiple Compose files](https://docs.docker.com/compose/how-tos/multiple-compose-files/).
* Explore some [sample apps](https://github.com/docker/awesome-compose).

----
url: https://docs.docker.com/reference/cli/sbx/template/
----

# sbx template

| Description | Manage sandbox templates |
| ----------- | ------------------------ |
| Usage       | `sbx template COMMAND`   |

## [Description](#description)

Manage sandbox templates.

Templates are saved snapshots of sandboxes that can be reused to create new sandboxes with: sbx run -t TAG AGENT \[WORKSPACE]

## [Commands](#commands)

| Command                                                                         | Description                                            |
| ------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [`sbx template load`](https://docs.docker.com/reference/cli/sbx/template/load/) | Load an image from a tar file into the sandbox runtime |
| [`sbx template ls`](https://docs.docker.com/reference/cli/sbx/template/ls/)     | List template images                                   |
| [`sbx template rm`](https://docs.docker.com/reference/cli/sbx/template/rm/)     | Remove a template image                                |
| [`sbx template save`](https://docs.docker.com/reference/cli/sbx/template/save/) | Save a snapshot of the sandbox as a template           |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/reference/cli/docker/model/tag/
----

# docker model tag

***

| Description | Tag a model                      |
| ----------- | -------------------------------- |
| Usage       | `docker model tag SOURCE TARGET` |

## [Description](#description)

Specify a particular version or variant of the model. If no tag is provided, Docker defaults to `latest`.

----
url: https://docs.docker.com/compose/bridge/
----

# Overview of Compose Bridge

***

Table of contents

***

Requires: Docker Desktop 4.43.0 and later

Compose Bridge converts your Docker Compose configuration into platform-specific deployment formats such as Kubernetes manifests. By default, it generates:

* Kubernetes manifests
* A Kustomize overlay

These outputs are ready for deployment on Docker Desktop with [Kubernetes enabled](https://docs.docker.com/desktop/settings-and-maintenance/settings/#kubernetes).

Compose Bridge helps you bridge the gap between Compose and Kubernetes, making it easier to adopt Kubernetes while keeping the simplicity and efficiency of Compose.

It's a flexible tool that lets you either take advantage of the [default transformation](https://docs.docker.com/compose/bridge/usage/) or [create a custom transformation](https://docs.docker.com/compose/bridge/customize/) to suit specific project needs and requirements.

## [How it works](#how-it-works)

Compose Bridge uses transformations to convert a Compose model into another form.

A transformation is packaged as a Docker image that receives the fully resolved Compose model as `/in/compose.yaml` and can produce any target format file under `/out`.

Compose Bridge provides its own transformation for Kubernetes using Go templates, so that it is easy to extend for customization by replacing or appending your own templates.

For more detailed information on how these transformations work and how you can customize them for your projects, see [Customize](https://docs.docker.com/compose/bridge/customize/).

Compose Bridge also supports applications that use LLMs via Docker Model Runner.

For more details, see [Use Model Runner](https://docs.docker.com/compose/bridge/use-model-runner/).

## [Apply organizational standards at scale](#apply-organizational-standards-at-scale)

Compose Bridge supports custom transformation templates, which lets platform teams encode organizational standards once and apply them consistently whenever a `compose.yaml` file is converted to Kubernetes manifests or other formats.

Developers continue to write standard Compose files. During conversion, Compose Bridge runs your custom transformation and automatically injects the required security contexts, resource limits, labels, and network policies into the output manifests — without requiring developers to know or manage those details.

When your requirements change, update the transformation template in one place. Every team picks up the changes on their next conversion, with no edits to individual Compose files.

This separation of concerns keeps developers focused on application configuration, while platform teams control governance and enforce policy through the transformation layer.

To get started, see [Customize Compose Bridge](https://docs.docker.com/compose/bridge/customize/).

## [What's next?](#whats-next)

* [Use Compose Bridge](https://docs.docker.com/compose/bridge/usage/)
* [Explore how you can customize Compose Bridge](https://docs.docker.com/compose/bridge/customize/)

----
url: https://docs.docker.com/reference/cli/docker/init/
----

# docker init

***

| Description | Creates Docker-related starter files for your project |
| ----------- | ----------------------------------------------------- |
| Usage       | `docker init [OPTIONS]`                               |

## [Description](#description)

Initialize a project with the files necessary to run the project in a container.

Docker Desktop provides the `docker init` CLI command. Run `docker init` in your project directory to be walked through the creation of the following files with sensible defaults for your project:

* .dockerignore
* Dockerfile
* compose.yaml
* README.Docker.md

If any of the files already exist, a prompt appears and provides a warning as well as giving you the option to overwrite all the files. If `docker-compose.yaml` already exists instead of `compose.yaml`, `docker init` can overwrite it, using `docker-compose.yaml` as the name for the Compose file.

> Warning
>
> You can't recover overwritten files. To back up an existing file before selecting to overwrite it, rename the file or copy it to another directory.

After running `docker init`, you can choose one of the following templates:

* ASP.NET Core: Suitable for an ASP.NET Core application.
* Go: Suitable for a Go server application.
* Java: suitable for a Java application that uses Maven and packages as an uber jar.
* Node: Suitable for a Node server application.
* PHP with Apache: Suitable for a PHP web application.
* Python: Suitable for a Python server application.
* Rust: Suitable for a Rust server application.
* Other: General purpose starting point for containerizing your application.

After `docker init` has completed, you may need to modify the created files and tailor them to your project. Visit the following topics to learn more about the files:

* [.dockerignore](https://docs.docker.com/reference/dockerfile/#dockerignore-file)
* [Dockerfile](https://docs.docker.com/reference/dockerfile/)
* [compose.yaml](https://docs.docker.com/compose/intro/compose-application-model/)

## [Options](#options)

| Option      | Default | Description                        |
| ----------- | ------- | ---------------------------------- |
| `--version` |         | Display version of the init plugin |

## [Examples](#examples)

### [Example of running `docker init`](#example-of-running-docker-init)

The following example shows the initial menu after running `docker init`. See the additional examples to view the options for each language or framework.

```console
$ docker init

Welcome to the Docker Init CLI!

This utility will walk you through creating the following files with sensible defaults for your project:
  - .dockerignore
  - Dockerfile
  - compose.yaml
  - README.Docker.md

Let's get started!

? What application platform does your project use?  [Use arrows to move, type to filter]
> PHP with Apache - (detected) suitable for a PHP web application
  Go - suitable for a Go server application
  Java - suitable for a Java application that uses Maven and packages as an uber jar
  Python - suitable for a Python server application
  Node - suitable for a Node server application
  Rust - suitable for a Rust server application
  ASP.NET Core - suitable for an ASP.NET Core application
  Other - general purpose starting point for containerizing your application
  Don't see something you need? Let us know!
  Quit
```

### [Example of selecting Go](#example-of-selecting-go)

The following example shows the prompts that appear after selecting `Go` and example input.

```console
? What application platform does your project use? Go
? What version of Go do you want to use? 1.20
? What's the relative directory (with a leading .) of your main package? .
? What port does your server listen on? 3333

CREATED: .dockerignore
CREATED: Dockerfile
CREATED: compose.yaml
CREATED: README.Docker.md

✔ Your Docker files are ready!

Take a moment to review them and tailor them to your application.

When you're ready, start your application by running: docker compose up --build

Your application will be available at http://localhost:3333

Consult README.Docker.md for more information about using the generated files.
```

### [Example of selecting Node](#example-of-selecting-node)

The following example shows the prompts that appear after selecting `Node` and example input.

```console
? What application platform does your project use? Node
? What version of Node do you want to use? 18
? Which package manager do you want to use? yarn
? Do you want to run "yarn run build" before starting your server? Yes
? What directory is your build output to? (comma-separate if multiple) output
? What command do you want to use to start the app? node index.js
? What port does your server listen on? 8000

CREATED: .dockerignore
CREATED: Dockerfile
CREATED: compose.yaml
CREATED: README.Docker.md

✔ Your Docker files are ready!

Take a moment to review them and tailor them to your application.

When you're ready, start your application by running: docker compose up --build

Your application will be available at http://localhost:8000

Consult README.Docker.md for more information about using the generated files.
```

### [Example of selecting Python](#example-of-selecting-python)

The following example shows the prompts that appear after selecting `Python` and example input.

```console
? What application platform does your project use? Python
? What version of Python do you want to use? 3.8
? What port do you want your app to listen on? 8000
? What is the command to run your app (e.g., gunicorn 'myapp.example:app' --bind=0.0.0.0:8000)? python ./app.py

CREATED: .dockerignore
CREATED: Dockerfile
CREATED: compose.yaml
CREATED: README.Docker.md

✔ Your Docker files are ready!

Take a moment to review them and tailor them to your application.

When you're ready, start your application by running: docker compose up --build

Your application will be available at http://localhost:8000

Consult README.Docker.md for more information about using the generated files.
```

### [Example of selecting Rust](#example-of-selecting-rust)

The following example shows the prompts that appear after selecting `Rust` and example input.

```console
? What application platform does your project use? Rust
? What version of Rust do you want to use? 1.70.0
? What port does your server listen on? 8000

CREATED: .dockerignore
CREATED: Dockerfile
CREATED: compose.yaml
CREATED: README.Docker.md

✔ Your Docker files are ready!

Take a moment to review them and tailor them to your application.

When you're ready, start your application by running: docker compose up --build

Your application will be available at http://localhost:8000

Consult README.Docker.md for more information about using the generated files.
```

### [Example of selecting ASP.NET Core](#example-of-selecting-aspnet-core)

The following example shows the prompts that appear after selecting `ASP.NET Core` and example input.

```console
? What application platform does your project use? ASP.NET Core
? What's the name of your solution's main project? myapp
? What version of .NET do you want to use? 6.0
? What local port do you want to use to access your server? 8000

CREATED: .dockerignore
CREATED: Dockerfile
CREATED: compose.yaml
CREATED: README.Docker.md

✔ Your Docker files are ready!

Take a moment to review them and tailor them to your application.

When you're ready, start your application by running: docker compose up --build

Your application will be available at http://localhost:8000

Consult README.Docker.md for more information about using the generated files.
```

### [Example of selecting PHP with Apache](#example-of-selecting-php-with-apache)

The following example shows the prompts that appear after selecting `PHP with Apache` and example input. The PHP with Apache template is suitable for both pure PHP applications and applications using Composer as a dependency manager. After running `docker init`, you must manually add any PHP extensions that are required by your application to the Dockerfile.

```console
? What application platform does your project use? PHP with Apache
? What version of PHP do you want to use? 8.2
? What's the relative directory (with a leading .) for your app? ./src
? What local port do you want to use to access your server? 9000

CREATED: .dockerignore
CREATED: Dockerfile
CREATED: compose.yaml
CREATED: README.Docker.md

✔ Your Docker files are ready!

Take a moment to review them and tailor them to your application.

If your application requires specific PHP extensions, you can follow the instructions in the Dockerfile to add them.

When you're ready, start your application by running: docker compose up --build

Your application will be available at http://localhost:9000

Consult README.Docker.md for more information about using the generated files.
```

### [Example of selecting Java](#example-of-selecting-java)

The following example shows the prompts that appear after selecting `Java` and example input.

```console
? What application platform does your project use? Java
? What version of Java do you want to use? 17
? What's the relative directory (with a leading .) for your app? ./src
? What port does your server listen on? 9000

CREATED: .dockerignore
CREATED: Dockerfile
CREATED: compose.yaml
CREATED: README.Docker.md

✔ Your Docker files are ready!

Take a moment to review them and tailor them to your application.

When you're ready, start your application by running: docker compose up --build

Your application will be available at http://localhost:9000

Consult README.Docker.md for more information about using the generated files.
```

### [Example of selecting Other](#example-of-selecting-other)

The following example shows the output after selecting `Other`.

```console
? What application platform does your project use? Other

CREATED: .dockerignore
CREATED: Dockerfile
CREATED: compose.yaml
CREATED: README.Docker.md

✔ Your Docker files are ready!

Take a moment to review them and tailor them to your application.

When you're ready, start your application by running: docker compose up --build

Consult README.Docker.md for more information about using the generated files.
```

----
url: https://docs.docker.com/reference/api/extensions-sdk/ExecOptions/
----

# Interface: ExecOptions

***

Table of contents

***

**`Since`**

0.3.0

## [Hierarchy](#hierarchy)

* **`ExecOptions`**

  ↳ [`SpawnOptions`](https://docs.docker.com/reference/api/extensions-sdk/SpawnOptions/)

## [Properties](#properties)

### [cwd](#cwd)

• `Optional` **cwd**: `string`

***

### [env](#env)

• `Optional` **env**: `ProcessEnv`

----
url: https://docs.docker.com/reference/samples/go/
----

# Go samples

| Name                                                                                                   | Description                                                                |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| [Go / NGINX / MySQL](https://github.com/docker/awesome-compose/tree/master/nginx-golang-mysql)         | A sample Go application with an Nginx proxy and a MySQL database.          |
| [Go / NGINX / PostgreSQL](https://github.com/docker/awesome-compose/tree/master/nginx-golang-postgres) | A sample Go application with an Nginx proxy and a PostgreSQL database.     |
| [NGINX / Go](https://github.com/docker/awesome-compose/tree/master/nginx-golang)                       | A sample Nginx proxy with a Go backend.                                    |
| [Traefik](https://github.com/docker/awesome-compose/tree/master/traefik-golang)                        | A sample Traefik proxy with a Go backend.                                  |
| [wordsmith](https://github.com/dockersamples/wordsmith)                                                | A demo app that runs three containers, including PostgreSQL, Java, and Go. |
| [gopher-task-system](https://github.com/dockersamples/gopher-task-system)                              | A Task System using Go Docker SDK.                                         |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/build/buildkit/
----

# BuildKit

***

Table of contents

***

[BuildKit](https://github.com/moby/buildkit) is the builder backend used by Docker. BuildKit provides improved functionality and improves your builds' performance over the legacy builder used in earlier versions of Docker. It also introduces support for handling more complex scenarios:

* Detect and skip executing unused build stages
* Parallelize building independent build stages
* Incrementally transfer only the changed files in your [build context](https://docs.docker.com/build/concepts/context/) between builds
* Detect and skip transferring unused files in your [build context](https://docs.docker.com/build/concepts/context/)
* Use [Dockerfile frontend](https://docs.docker.com/build/buildkit/frontend/) implementations with many additional features
* Avoid side effects with rest of the API (intermediate images and containers)
* Prioritize your build cache for automatic pruning

The main areas BuildKit improves on the legacy builder are performance, storage management, and extensibility. From the performance side, a significant update is a fully concurrent build graph solver. It can run build steps in parallel when possible and optimize out commands that don't have an impact on the final result. The access to the local source files has also been optimized. By tracking only the updates made to these files between repeated build invocations, there is no need to wait for local files to be read or uploaded before the work can begin.

## [LLB](#llb)

At the core of BuildKit is a [Low-Level Build (LLB)](https://github.com/moby/buildkit#exploring-llb) definition format. LLB is an intermediate binary format that allows developers to extend BuildKit. LLB defines a content-addressable dependency graph that can be used to put together complex build definitions. It also supports features not exposed in Dockerfiles, like direct data mounting and nested invocation.

Everything about execution and caching of your builds is defined in LLB. The caching model is entirely rewritten compared to the legacy builder. Rather than using heuristics to compare images, LLB directly tracks the checksums of build graphs and content mounted to specific operations. This makes it much faster, more precise, and portable. The build cache can even be exported to a registry, where it can be pulled on-demand by subsequent invocations on any host.

LLB can be generated directly using a [golang client package](https://pkg.go.dev/github.com/moby/buildkit/client/llb) that allows defining the relationships between your build operations using Go language primitives. This gives you full power to run anything you can imagine, but will probably not be how most people will define their builds. Instead, most users would use a frontend component, or LLB nested invocation, to run a prepared set of build steps.

## [Frontend](#frontend)

A frontend is a component that takes a human-readable build format and converts it to LLB so BuildKit can execute it. Frontends can be distributed as images, and the user can target a specific version of a frontend that is guaranteed to work for the features used by their definition.

For example, to build a [Dockerfile](https://docs.docker.com/reference/dockerfile/) with BuildKit, you would [use an external Dockerfile frontend](https://docs.docker.com/build/buildkit/frontend/).

## [Getting started](#getting-started)

BuildKit is the default builder for Docker Desktop and Docker Engine users. If you're building Windows containers, the legacy builder is used instead.

## [BuildKit on Windows](#buildkit-on-windows)

> Warning
>
> BuildKit only fully supports building Linux containers. Windows container support is experimental.

BuildKit has experimental support for Windows containers (WCOW) as of version 0.13. This section walks you through the steps for trying it out. To share feedback, [open an issue in the repository](https://github.com/moby/buildkit/issues/new), especially `buildkitd.exe`.

### [Known limitations](#known-limitations)

For information about open bugs and limitations related to BuildKit on Windows, see [GitHub issues](https://github.com/moby/buildkit/issues?q=is%3Aissue%20state%3Aopen%20label%3Aarea%2Fwindows-wcow).

### [Prerequisites](#prerequisites)

* Architecture: `amd64`, `arm64` (binaries available but not officially tested yet).
* Supported OS: Windows Server 2019, Windows Server 2022, Windows 11.
* Base images: `ServerCore:ltsc2019`, `ServerCore:ltsc2022`, `NanoServer:ltsc2022`. See the [compatibility map here](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility?tabs=windows-server-2019%2Cwindows-11#windows-server-host-os-compatibility).
* Docker Desktop version 4.29 or later

### [Steps](#steps)

> Note
>
> The following commands require administrator (elevated) privileges in a PowerShell terminal.

1. Enable the **Hyper-V** and **Containers** Windows features.

   ```console
   > Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V, Containers -All
   ```

   If you see `RestartNeeded` as `True`, restart your machine and re-open a PowerShell terminal as an administrator. Otherwise, continue with the next step.

2. Switch to Windows containers in Docker Desktop.

   Select the Docker icon in the taskbar, and then **Switch to Windows containers...**.

3. Install containerd version 1.7.7 or later following the [setup instructions](https://github.com/containerd/containerd/blob/main/docs/getting-started.md#installing-containerd-on-windows).

4. Download and extract the latest BuildKit release.

   ```powershell
   $version = "v0.22.0" # specify the release version, v0.13+
   $arch = "amd64" # arm64 binary available too
   curl.exe -LO https://github.com/moby/buildkit/releases/download/$version/buildkit-$version.windows-$arch.tar.gz
   # there could be another `.\bin` directory from containerd instructions
   # you can move those
   mv bin bin2
   tar.exe xvf .\buildkit-$version.windows-$arch.tar.gz
   ## x bin/
   ## x bin/buildctl.exe
   ## x bin/buildkitd.exe
   ```

5. Install BuildKit binaries on `PATH`.

   ```powershell
   # after the binaries are extracted in the bin directory
   # move them to an appropriate path in your $Env:PATH directories or:
   Copy-Item -Path ".\bin" -Destination "$Env:ProgramFiles\buildkit" -Recurse -Force
   # add `buildkitd.exe` and `buildctl.exe` binaries in the $Env:PATH
   $Path = [Environment]::GetEnvironmentVariable("PATH", "Machine") + `
       [IO.Path]::PathSeparator + "$Env:ProgramFiles\buildkit"
   [Environment]::SetEnvironmentVariable( "Path", $Path, "Machine")
   $Env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + `
       [System.Environment]::GetEnvironmentVariable("Path","User")
   ```

6. Start the BuildKit daemon.

   ```console
   > buildkitd.exe
   ```

   > Note
   >
   > If you are running a *dockerd-managed* `containerd` process, use that instead, by supplying the address: `buildkitd.exe --containerd-worker-addr "npipe:////./pipe/docker-containerd"`

7. In another terminal with administrator privileges, create a remote builder that uses the local BuildKit daemon.

   > Note
   >
   > This requires Docker Desktop version 4.29 or later.

   ```console
   > docker buildx create --name buildkit-exp --use --driver=remote npipe:////./pipe/buildkitd
   buildkit-exp
   ```

8. Verify the builder connection by running `docker buildx inspect`.

   ```console
   > docker buildx inspect
   ```

   The output should indicate that the builder platform is Windows, and that the endpoint of the builder is a named pipe.

   ```text
   Name:          buildkit-exp
    Driver:        remote
    Last Activity: 2024-04-15 17:51:58 +0000 UTC
    Nodes:
    Name:             buildkit-exp0
    Endpoint:         npipe:////./pipe/buildkitd
    Status:           running
    BuildKit version: v0.13.1
    Platforms:        windows/amd64
   ...
   ```

9. Create a Dockerfile and build a `hello-buildkit` image.

   ```console
   > mkdir sample_dockerfile
   > cd sample_dockerfile
   > Set-Content Dockerfile @"
   FROM mcr.microsoft.com/windows/nanoserver:ltsc2022
   USER ContainerAdministrator
   COPY hello.txt C:/
   RUN echo "Goodbye!" >> hello.txt
   CMD ["cmd", "/C", "type C:\\hello.txt"]
   "@
   Set-Content hello.txt @"
   Hello from BuildKit!
   This message shows that your installation appears to be working correctly.
   "@
   ```

10. Build and push the image to a registry.

    ```console
    > docker buildx build --push -t <username>/hello-buildkit .
    ```

11. After pushing to the registry, run the image with `docker run`.

    ```console
    > docker run <username>/hello-buildkit
    ```

----
url: https://docs.docker.com/guides/php/
----

# PHP language-specific guide

***

This guide explains how to containerize PHP applications using Docker.

**Time to complete** 20 minutes

The PHP language-specific guide teaches you how to create a containerized PHP application using Docker. In this guide, you'll learn how to:

* Containerize and run a PHP application
* Set up a local environment to develop a PHP application using containers
* Run tests for a PHP application within containers
* Configure a CI/CD pipeline for a containerized PHP application using GitHub Actions
* Deploy your containerized application locally to Kubernetes to test and debug your deployment

After completing the PHP language-specific guide, you should be able to containerize your own PHP application based on the examples and instructions provided in this guide.

Start by containerizing an existing PHP application.

## [Modules](#modules)

1. [Containerize your app](https://docs.docker.com/guides/php/containerize/)

   Learn how to containerize a PHP application.

2. [Develop your app](https://docs.docker.com/guides/php/develop/)

   Learn how to develop your PHP application locally using containers.

3. [Run your tests](https://docs.docker.com/guides/php/run-tests/)

   Learn how to run your PHP tests in a container.

4. [Configure CI/CD](https://docs.docker.com/guides/php/configure-ci-cd/)

   Learn how to Configure CI/CD for your PHP application

5. [Test your deployment](https://docs.docker.com/guides/php/deploy/)

   Learn how to deploy your application

----
url: https://docs.docker.com/desktop/troubleshoot-and-support/faqs/releases/
----

# FAQs on Docker Desktop releases

***

Table of contents

***

### [How frequent will new releases be?](#how-frequent-will-new-releases-be)

New releases are available every week, unless there are critical fixes that need to be released sooner.

The **Automatically check for updates** setting in the **Software updates** tab is turned on by default. This means you receive notifications in the Docker menu and a notification badge on the Docker Desktop Dashboard when a new version is available.

You can also let Docker Desktop automatically download new updates in the background by selecting the **Always download updates** checkbox.

Sometimes new versions are rolled out gradually over a few days. Therefore, if you wait, it will turn up soon. Alternatively, you can select **Check for updates** in the Docker menu to get the latest version immediately.

### [How do I ensure that all users in my organization are using the same version?](#how-do-i-ensure-that-all-users-in-my-organization-are-using-the-same-version)

This is managed through your IT administrator's endpoint management software.

----
url: https://docs.docker.com/reference/cli/docker/mcp/profile/server/
----

# docker mcp profile server

***

| Description | Manage servers in profiles |
| ----------- | -------------------------- |

## [Description](#description)

Manage servers in profiles

## [Subcommands](#subcommands)

| Command                                                                                                       | Description                       |
| ------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| [`docker mcp profile server add`](https://docs.docker.com/reference/cli/docker/mcp/profile/server/add/)       | Add MCP servers to a profile      |
| [`docker mcp profile server ls`](https://docs.docker.com/reference/cli/docker/mcp/profile/server/ls/)         | List servers across profiles      |
| [`docker mcp profile server remove`](https://docs.docker.com/reference/cli/docker/mcp/profile/server/remove/) | Remove MCP servers from a profile |

----
url: https://docs.docker.com/reference/cli/docker/node/ls/
----

# docker node ls

***

| Description                                                               | List nodes in the swarm    |
| ------------------------------------------------------------------------- | -------------------------- |
| Usage                                                                     | `docker node ls [OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker node list`         |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Lists all the nodes that the Docker Swarm manager knows about. You can filter using the `-f` or `--filter` flag. Refer to the [filtering](#filter) section for more information about available filter options.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --filter`](#filter) |         | Filter output based on conditions provided                                                                                                                                                                                                                                                                                                                                             |
| [`--format`](#format)     |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| `-q, --quiet`             |         | Only display IDs                                                                                                                                                                                                                                                                                                                                                                       |

## [Examples](#examples)

```console
$ docker node ls

ID                           HOSTNAME        STATUS  AVAILABILITY  MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0    swarm-worker2   Ready   Active
38ciaotwjuritcdtn9npbnkuz    swarm-worker1   Ready   Active
e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader
```

> Note
>
> In the above example output, there is a hidden column of `.Self` that indicates if the node is the same node as the current docker daemon. A `*` (e.g., `e216jshn25ckzbvmwlnh5jr3g *`) means this node is the current docker daemon.

### [Filtering (--filter)](#filter)

The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)

The currently supported filters are:

* [id](#id)
* [label](#label)
* [node.label](#nodelabel)
* [membership](#membership)
* [name](#name)
* [role](#role)

#### [id](#id)

The `id` filter matches all or part of a node's id.

```console
$ docker node ls -f id=1

ID                         HOSTNAME       STATUS  AVAILABILITY  MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0  swarm-worker2  Ready   Active
```

#### [label](#label)

The `label` filter matches nodes based on engine labels and on the presence of a `label` alone or a `label` and a value. Engine labels are configured in the [daemon configuration](/reference/cli/dockerd/#daemon-configuration-file). To filter on Swarm `node` labels, use [`node.label` instead](#nodelabel).

The following filter matches nodes with the `foo` label regardless of its value.

```console
$ docker node ls -f "label=foo"

ID                         HOSTNAME       STATUS  AVAILABILITY  MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0  swarm-worker2  Ready   Active
```

#### [node.label](#nodelabel)

The `node.label` filter matches nodes based on node labels and on the presence of a `node.label` alone or a `node.label` and a value.

The following filter updates nodes to have a `region` node label:

```console
$ docker node update --label-add region=region-a swarm-test-01
$ docker node update --label-add region=region-a swarm-test-02
$ docker node update --label-add region=region-b swarm-test-03
$ docker node update --label-add region=region-b swarm-test-04
```

Show all nodes that have a `region` node label set:

```console
$ docker node ls --filter node.label=region

ID                            HOSTNAME        STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
yg550ettvsjn6g6t840iaiwgb *   swarm-test-01   Ready     Active         Leader           23.0.3
2lm9w9kbepgvkzkkeyku40e65     swarm-test-02   Ready     Active         Reachable        23.0.3
hc0pu7ntc7s4uvj4pv7z7pz15     swarm-test-03   Ready     Active         Reachable        23.0.3
n41b2cijmhifxxvz56vwrs12q     swarm-test-04   Ready     Active                          23.0.3
```

Show all nodes that have a `region` node label, with value `region-a`:

```console
$ docker node ls --filter node.label=region=region-a

ID                            HOSTNAME        STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
yg550ettvsjn6g6t840iaiwgb *   swarm-test-01   Ready     Active         Leader           23.0.3
2lm9w9kbepgvkzkkeyku40e65     swarm-test-02   Ready     Active         Reachable        23.0.3
```

#### [membership](#membership)

The `membership` filter matches nodes based on the presence of a `membership` and a value `accepted` or `pending`.

The following filter matches nodes with the `membership` of `accepted`.

```console
$ docker node ls -f "membership=accepted"

ID                           HOSTNAME        STATUS  AVAILABILITY  MANAGER STATUS
1bcef6utixb0l0ca7gxuivsj0    swarm-worker2   Ready   Active
38ciaotwjuritcdtn9npbnkuz    swarm-worker1   Ready   Active
```

#### [name](#name)

The `name` filter matches on all or part of a node hostname.

The following filter matches the nodes with a name equal to `swarm-master` string.

```console
$ docker node ls -f name=swarm-manager1

ID                           HOSTNAME        STATUS  AVAILABILITY  MANAGER STATUS
e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader
```

#### [role](#role)

The `role` filter matches nodes based on the presence of a `role` and a value `worker` or `manager`.

The following filter matches nodes with the `manager` role.

```console
$ docker node ls -f "role=manager"

ID                           HOSTNAME        STATUS  AVAILABILITY  MANAGER STATUS
e216jshn25ckzbvmwlnh5jr3g *  swarm-manager1  Ready   Active        Leader
```

### [Format the output (--format)](#format)

The formatting options (`--format`) pretty-prints nodes output using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder      | Description                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| `.ID`            | Node ID                                                                                               |
| `.Self`          | Node of the daemon (`true/false`, `true`indicates that the node is the same as current docker daemon) |
| `.Hostname`      | Node hostname                                                                                         |
| `.Status`        | Node status                                                                                           |
| `.Availability`  | Node availability ("active", "pause", or "drain")                                                     |
| `.ManagerStatus` | Manager status of the node                                                                            |
| `.TLSStatus`     | TLS status of the node ("Ready", or "Needs Rotation" has TLS certificate signed by an old CA)         |
| `.EngineVersion` | Engine version                                                                                        |

When using the `--format` option, the `node ls` command will either output the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `ID`, `Hostname`, and `TLS Status` entries separated by a colon (`:`) for all nodes:

```console
$ docker node ls --format "{{.ID}}: {{.Hostname}} {{.TLSStatus}}"

e216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready
35o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation
```

To list all nodes in JSON format, use the `json` directive:

```console
$ docker node ls --format json
{"Availability":"Active","EngineVersion":"23.0.3","Hostname":"docker-desktop","ID":"k8f4w7qtzpj5sqzclcqafw35g","ManagerStatus":"Leader","Self":true,"Status":"Ready","TLSStatus":"Ready"}
```

----
url: https://docs.docker.com/admin/organization/setup/onboard/
----

# Onboard your organization

***

Table of contents

***

Subscription: Team Business

For: Administrators

Learn how to onboard your organization using the Admin Console or Docker Hub.

Onboarding your organization includes:

* Identifying users to help you allocate your subscription seats
* Invite members and owners to your organization
* Secure authentication and authorization for your organization
* Enforce sign-in for Docker Desktop to ensure security best practices

These actions help administrators gain visibility into user activity and enforce security settings. Organization members also receive increased pull limits and other benefits when they are signed in.

## [Prerequisites](#prerequisites)

Before you start onboarding your organization, ensure you:

* Have a Docker Team or Business subscription. For more details, see [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs\&refAction=DocsAdminOnboard).

  > Note
  >
  > When purchasing a self-serve subscription, the on-screen instructions guide you through creating an organization. If you have purchased a subscription through Docker Sales and you have not yet created an organization, see [Create an organization](https://docs.docker.com/admin/organization/setup/orgs/).

* Familiarize yourself with Docker concepts and terminology in the [administration overview](https://docs.docker.com/admin/).

## [Onboard with guided setup](#onboard-with-guided-setup)

The Admin Console has a guided setup to help you onboard your organization. The guided setup's steps consist of basic onboarding tasks. If you want to onboard outside of the guided setup, see [Recommended onboarding steps](https://docs.docker.com/admin/organization/setup/onboard/#recommended-onboarding-steps).

To onboard using the guided setup, navigate to the [Admin Console](https://app.docker.com) and select **Guided setup** in the left-hand navigation.

The guided setup walks you through the following onboarding steps:

* **Invite your team**: Invite owners and members.
* **Manage user access**: Add and verify a domain, manage users with SSO, and enforce Docker Desktop sign-in.
* **Docker Desktop security**: Configure image access management, registry access management, and settings management.

## [Recommended onboarding steps](#recommended-onboarding-steps)

### [Step one: Identify your Docker users](#step-one-identify-your-docker-users)

Identifying your users helps you allocate seats efficiently and ensures they receive your Docker subscription benefits.

1. Identify the Docker users in your organization.

   * If your organization uses device management software, like MDM or Jamf, you can use the device management software to help identify Docker users. See your device management software's documentation for details. You can identify Docker users by checking if Docker Desktop is installed at the following location on each user's machine:

     * Mac: `/Applications/Docker.app`
     * Windows: `C:\Program Files\Docker\Docker`(all-user installation) or `%LOCALAPPDATA%\Programs\DockerDesktop` (per-user installation (Beta))
     * Linux: `/opt/docker-desktop`

   * If your organization doesn't use device management software or your users haven't installed Docker Desktop yet, you can survey your users to identify who is using Docker Desktop.

2. Ask users to update their Docker account's email address to one associated with your organization's domain, or create a new account with that email.

   * To update an account's email address, instruct your users to sign in to [Docker Hub](https://hub.docker.com), and update the email address to their email address in your organization's domain.
   * To create a new account, instruct your users to [sign up](https://hub.docker.com/signup) using their email address associated with your organization's domain. Ensure your users verify their email address.

3. Identify Docker accounts associated with your organization's domain:
   * Ask your Docker sales representative or [contact sales](https://www.docker.com/pricing/contact-sales/) to get a list of Docker accounts that use an email address in your organization's domain.

### [Step two: Invite owners](#step-two-invite-owners)

Owners can help you onboard and manage your organization.

When you create an organization, you are the only owner. It is optional to add additional owners.

To add an owner, invite a user and assign them the owner role. For more details, see [Invite members](https://docs.docker.com/admin/organization/manage/members/) and [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/).

### [Step three: Invite members](#step-three-invite-members)

When you add users to your organization, you gain visibility into their activity and you can enforce security settings. Your members also receive increased pull limits and other organization wide benefits when they are signed in.

To add a member, invite a user and assign them the member role. For more details, see [Invite members](https://docs.docker.com/admin/organization/manage/members/) and [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/).

### [Step four: Manage user access with SSO and SCIM](#step-four-manage-user-access-with-sso-and-scim)

Configuring SSO and SCIM is optional and only available to Docker Business subscribers. To upgrade a Docker Team subscription to a Docker Business subscription, see [Change your subscription](https://docs.docker.com/subscription/change/).

Use your identity provider (IdP) to manage members and provision them to Docker automatically via SSO and SCIM. See the following for more details:

* [Configure SSO](https://docs.docker.com/enterprise/security/single-sign-on/connect/) to authenticate and add members when they sign in to Docker through your identity provider.

* Optional. [Enforce SSO](https://docs.docker.com/enterprise/security/single-sign-on/connect/) to ensure that when users sign in to Docker, they must use SSO.

  > Note
  >
  > Enforcing single sign-on (SSO) and enforcing Docker Desktop sign in are different features. For more details, see [Enforcing sign-in versus enforcing single sign-on (SSO)](https://docs.docker.com/enterprise/security/enforce-sign-in/#enforcing-sign-in-versus-enforcing-single-sign-on-sso).

* [Configure SCIM](https://docs.docker.com/enterprise/security/provisioning/scim/) to automatically provision, add, and de-provision members to Docker through your identity provider.

### [Step five: Enforce sign-in for Docker Desktop](#step-five-enforce-sign-in-for-docker-desktop)

By default, members of your organization can use Docker Desktop without signing in. When users don’t sign in as a member of your organization, they don’t receive the [benefits of your organization’s subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsAdminOnboard) and they can circumvent [Docker’s security features](https://docs.docker.com/enterprise/security/hardened-desktop/).

There are multiple ways you can enforce sign-in, depending on your organization's Docker configuration:

* [Registry key method (Windows only)](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#registry-key-method-windows-only)
* [`.plist` method (Mac only)](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#plist-method-mac-only)
* [`registry.json` method (All)](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#registryjson-method-all)

### [Step six: Manage Docker Desktop security](#step-six-manage-docker-desktop-security)

Docker offers the following security features to manage your organization's security posture:

* [Image Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/image-access-management/): Control which types of images your developers can pull from Docker Hub.
* [Registry Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/): Define which registries your developers can access.
* [Settings management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/): Set and control Docker Desktop settings for your users.

## [What's next](#whats-next)

* [Manage Docker products](https://docs.docker.com/admin/organization/manage/manage-products/) to configure access and view usage.
* Configure [Hardened Docker Desktop](https://docs.docker.com/enterprise/security/hardened-desktop/) to improve your organization’s security posture for containerized development.
* [Manage your domains](https://docs.docker.com/enterprise/security/domain-management/) to ensure that all Docker users in your domain are part of your organization.

Your Docker subscription provides many more additional features. To learn more, see [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs\&refAction=DocsAdminOnboard).

----
url: https://docs.docker.com/guides/localstack/
----

[Develop and test AWS Cloud applications using LocalStack and Docker](https://docs.docker.com/guides/localstack/)

This guide explains how to use Docker to run LocalStack, a local AWS cloud stack emulator.

JavaScript Cloud services

20 minutes

[« Back to all guides](/guides/)

# Develop and test AWS Cloud applications using LocalStack and Docker

***

Table of contents

***

In modern application development, testing cloud applications locally before deploying them to a live environment helps you ship faster and with more confidence. This approach involves simulating services locally, identifying and fixing issues early, and iterating quickly without incurring costs or facing the complexities of a full cloud environment. Tools like [LocalStack](https://www.localstack.cloud/) have become invaluable in this process, enabling you to emulate AWS services and containerize applications for consistent, isolated testing environments.

In this guide, you'll learn how to:

* Use Docker to launch up a LocalStack container
* Connect to LocalStack from a non-containerized application
* Connect to LocalStack from a containerized application

## [What is LocalStack?](#what-is-localstack)

LocalStack is a cloud service emulator that runs in a single container on your laptop. It provides a powerful, flexible, and cost-effective way to test and develop AWS-based applications locally.

## [Why use LocalStack?](#why-use-localstack)

Simulating AWS services locally allows you to test how your app interacts with services like S3, Lambda, and DynamoDB without needing to connect to the real AWS cloud. You can quickly iterate on your development, avoiding the cost and complexity of deploying to the cloud during this phase.

By mimicking the behavior of these services locally, LocalStack enables faster feedback loops. Your app can interact with external APIs, but everything runs locally, removing the need to deal with cloud provisioning or network latency.

This makes it easier to validate integrations and test cloud-based scenarios without needing to configure IAM roles or policies in a live environment. You can simulate complex cloud architectures locally and push your changes to AWS only when you’re ready.

## [Using LocalStack with Docker](#using-localstack-with-docker)

The [official Docker image for LocalStack](https://hub.docker.com/r/localstack/localstack) provides a convenient way to run LocalStack on your development machine. It’s free to use and doesn’t require any API key to run. You can even use [LocalStack Docker Extension](https://www.docker.com/blog/develop-your-cloud-app-locally-with-the-localstack-extension/) to use LocalStack with a graphical user interface.

## [Prerequisites](#prerequisites)

The following prerequisites are required to follow along with this how-to guide:

* [Docker Desktop](https://www.docker.com/products/docker-desktop/)
* [Node.js](https://nodejs.org/en/download/package-manager)
* [Python and pip](https://www.python.org/downloads/)
* Basic knowledge of Docker

## [Launching LocalStack](#launching-localstack)

Launch a quick demo of LocalStack by using the following steps:

1. Start by [cloning a sample application](https://github.com/dockersamples/todo-list-localstack-docker). Open the terminal and run the following command:

   ```console
   $ git clone https://github.com/dockersamples/todo-list-localstack-docker
   $ cd todo-list-localstack-docker
   ```

2. Bring up LocalStack

   Run the following command to bring up LocalStack.

   ```console
   $ docker compose -f compose-native.yml up -d
   ```

   This Compose file also includes specifications for a required Mongo database. You can verify the services are up and running by visiting the Docker Desktop Dashboard.

3. Verify that LocalStack is up and running by selecting the container and checking the logs.

4. Creating a Local Amazon S3 Bucket

   When you create a local S3 bucket using LocalStack, you're essentially simulating the creation of an S3 bucket on AWS. This lets you to test and develop applications that interact with S3 without needing an actual AWS account.

   To create Local Amazon S3 bucket, install the [`awscli-local` CLI](https://github.com/localstack/awscli-local) on your system. The `awslocal` command is a thin wrapper around the AWS command line interface for use with LocalStack. It lets you to test and develop against a simulated environment on your local machine without needing to access the real AWS services.

   ```console
   $ pip install awscli-local
   ```

   Create a new S3 bucket within the LocalStack environment with the following command:

   ```console
   $ awslocal s3 mb s3://mysamplebucket
   ```

   The command `s3 mb s3://mysamplebucket` tells the AWS CLI to create a new S3 bucket (mb stands for `make bucket`) named `mysamplebucket`.

   You can verify if the S3 bucket gets created or not by selecting the LocalStack container on the Docker Desktop Dashboard and viewing the logs. The logs indicates that your LocalStack environment is configured correctly and you can now use the `mysamplebucket` for storing and retrieving objects.

## [Using LocalStack in development](#using-localstack-in-development)

Now that you've familiarized yourself with LocalStack, it's time to see it in action. In this demonstration, you'll use a sample application featuring a React frontend and a Node.js backend. This application stack utilizes the following components:

* React: A user-friendly frontend for accessing the todo-list application
* Node: A backend responsible for handling the HTTP requests.
* MongoDB: A database to store all the to-do list data
* LocalStack: Emulates the Amazon S3 service and stores and retrieve images.

## [Connecting to LocalStack from a non-containerized app](#connecting-to-localstack-from-a-non-containerized-app)

Now it’s time to connect your app to LocalStack. The `index.js` file, located in the backend/ directory, serves as the main entry point for the backend application.

The code interacts with LocalStack’s S3 service, which is accessed via the endpoint defined by the `S3_ENDPOINT_URL` environment variable, typically set to `http://localhost:4556` for local development.

The `S3Client` from the AWS SDK is configured to use this LocalStack endpoint, along with test credentials (`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`) that are also sourced from environment variables. This setup lets the application to perform operations on the locally simulated S3 service as if it were interacting with the real AWS S3, making the code flexible for different environments.

The code uses `multer` and `multer-s3` to handle file uploads. When a user uploads an image through the /upload route, the file is stored directly in the S3 bucket simulated by LocalStack. The bucket name is retrieved from the environment variable `S3_BUCKET_NAME`. Each uploaded file is given a unique name by appending the current timestamp to the original filename. The route then returns the URL of the uploaded file within the local S3 service, making it accessible just as it would be if hosted on a real AWS S3 bucket.

Let’s see it in action. Start by launching the Node.js backend service.

1. Change to the backend/ directory

   ```console
   $ cd backend/
   ```

2. Install the required dependencies:

   ```console
   $ npm install
   ```

3. Setting up AWS environment variables

   The `.env` file located in the backend/ directory already contains placeholder credentials and configuration values that LocalStack uses to emulate AWS services. The `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are placeholder credentials, while `S3_BUCKET_NAME` and `S3_ENDPOINT_URL` are configuration settings. No changes are needed as these values are already correctly set for LocalStack.

   > Tip
   >
   > Given that you’re running Mongo in a Docker container and the backend Node app is running natively on your host, ensure that `MONGODB_URI=mongodb://localhost:27017/todos` is set in your `.env` file.

   ```plaintext
   MONGODB_URI=mongodb://localhost:27017/todos
   AWS_ACCESS_KEY_ID=test
   AWS_SECRET_ACCESS_KEY=test
   S3_BUCKET_NAME=mysamplebucket
   S3_ENDPOINT_URL=http://localhost:4566
   AWS_REGION=us-east-1
   ```

   While the AWS SDK might typically use environment variables starting with `AWS_`, this specific application directly references the following `S3_*` variables in the index.js file (under the `backend/` directory) to configure the S3Client.

   ```js
   const s3 = new S3Client({
     endpoint: process.env.S3_ENDPOINT_URL, // Use the provided endpoint or fallback to defaults
     credentials: {
       accessKeyId: process.env.AWS_ACCESS_KEY_ID || 'default_access_key', // Default values for development
       secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || 'default_secret_key',  
     },
   });
   ```

4. Start the backend server:

   ```console
   $ node index.js
   ```

   You will see the message that the backend service has successfully started at port 5000.

## [Start the frontend service](#start-the-frontend-service)

To start the frontend service, open a new terminal and follow these steps:

1. Navigate to the `frontend` directory:

   ```console
   $ cd frontend
   ```

2. Install the required dependencies

   ```console
   $ npm install
   ```

3. Start the frontend service

   ```console
   $ npm run dev
   ```

   By now, you should see the following message:

   ```console
   VITE v5.4.2  ready in 110 ms
   ➜  Local: http://localhost:5173/
   ➜  Network: use --host to expose
   ➜  press h + enter to show help
   ```

   You can now access the app via <http://localhost:5173>. Go ahead, and upload an image by choosing an image file and clicking the **Upload** button.

   You can verify the image is uploaded to the S3 bucket by checking the LocalStack container logs:

   The `200` status code signifies that the `putObject` operation, which involves uploading an object to the S3 bucket, was executed successfully within the LocalStack environment. LocalStack logs this entry to provide visibility into the operations being performed. It helps debug and confirm that your application is interacting correctly with the emulated AWS services.

   Since LocalStack is designed to simulate AWS services locally, this log entry shows that your application is functioning as expected when performing cloud operations in a local sandbox environment.

## [Connecting to LocalStack from containerized Node app](#connecting-to-localstack-from-containerized-node-app)

Now that you have learnt how to connect a non-containerized Node.js application to LocalStack, it's time to explore the necessary changes to run the complete application stack in a containerized environment. To achieve this, you will create a Compose file specifying all required services - frontend, backend, database, and LocalStack.

1. Examine the Docker Compose file.

   The following Docker Compose file defines four services: `backend`, `frontend`, `mongodb`, and `localstack`. The `backend` and `frontend` services are your Node.js applications, while `mongodb` provides a database and `localstack` simulates AWS services like S3.

   The `backend` service depends on `localstack` and `mongodb` services, ensuring they are running before it starts. It also uses a .env file for environment variables. The frontend service depends on the backend and sets the API URL. The `mongodb` service uses a persistent volume for data storage, and `localstack` is configured to run the S3 service. This setup lets you to develop and test your application locally with AWS-like services.

   ```yaml
   services:
     backend:
       build:
         context: ./backend
         dockerfile: Dockerfile
       ports:
         - 5000:5000
       depends_on:
         - localstack
         - mongodb
       env_file:
         - backend/.env

     frontend:
       build:
         context: ./frontend
         dockerfile: Dockerfile
       ports:
         - 5173:5173
       depends_on:
         - backend
       environment:
         - REACT_APP_API_URL=http://backend:5000/api

     mongodb:
       image: mongo
       container_name: mongodb
       volumes:
         - mongodbdata:/data/db
       ports:
         - 27017:27017

     localstack:
       image: localstack/localstack
       container_name: localstack
       ports:
         - 4566:4566
       environment:
         - SERVICES=s3
         - GATEWAY_LISTEN=0.0.0.0:4566
       volumes:
         - ./localstack:/docker-entrypoint-initaws.d"

   volumes:
     mongodbdata:
   ```

2. Modify the `.env` file under the `backend/` directory to have the resources connect using the internal network names.

   > Tip
   >
   > Given the previous Compose file, the app would connect to LocalStack using the hostname `localstack` while Mongo would connect using the hostname `mongodb`.

   ```plaintext
   MONGODB_URI=mongodb://mongodb:27017/todos
   AWS_ACCESS_KEY_ID=test
   AWS_SECRET_ACCESS_KEY=test
   S3_BUCKET_NAME=mysamplebucket
   S3_ENDPOINT_URL=http://localstack:4566
   AWS_REGION=us-east-1
   ```

3. Stop the running services

   Ensure that you stop the Node frontend and backend service from the previous step by pressing “Ctrl+C” in the terminal. Also, you'll need to stop the LocalStack and Mongo containers by selecting them in the Docker Desktop Dashboard and selecting the "Delete" button.

4. Start the application stack by executing the following command at the root of your cloned project directory:

   ```console
   $ docker compose -f compose.yml up -d --build
   ```

   After a brief moment, the application will be up and running.

5. Create an S3 bucket manually

   The AWS S3 bucket is not created beforehand by the Compose file. Run the following command to create a new bucket within the LocalStack environment:

   ```console
   $ awslocal s3 mb s3://mysamplebucket
   ```

   The command creates an S3 bucket named `mysamplebucket`.

   Open <http://localhost:5173> to access the complete to-do list application and start uploading images to the Amazon S3 bucket.

   > Tip
   >
   > To optimize performance and reduce upload times during development, consider uploading smaller image files. Larger images may take longer to process and could impact the overall responsiveness of the application.

## [Recap](#recap)

This guide has walked you through setting up a local development environment using LocalStack and Docker. You’ve learned how to test AWS-based applications locally, reducing costs and increasing the efficiency of your development workflow.

----
url: https://docs.docker.com/guides/container-supported-development/
----

[Faster development and testing with container-supported development](https://docs.docker.com/guides/container-supported-development/)

Containers don't have to be just for your app. Learn how to run your app's dependent services and other debugging tools to enhance your development environment.

App development

20 minutes

[« Back to all guides](/guides/)

# Faster development and testing with container-supported development

***

Table of contents

***

Containers offer a consistent way to build, share, and run applications across different environments. While containers are typically used to containerize your application, they also make it incredibly easy to run essential services needed for development. Instead of installing or connecting to a remote database, you can easily launch your own database. But the possibilities don't stop there.

With container-supported development, you use containers to enhance your development environment by emulating or running your own instances of the services your app needs. This provides faster feedback loops, less coupling with remote services, and a greater ability to test error states.

And best of all, you can have these benefits regardless of whether the main app under development is running in containers.

## [What you'll learn](#what-youll-learn)

* The meaning of container-supported development
* How to connect non-containerized applications to containerized services
* Several examples of using containers to emulate or run local instances of services
* How to use containers to add additional troubleshooting and debugging tools to your development environment

## [Who's this for?](#whos-this-for)

* Teams that want to reduce the coupling they have on shared or deployed infrastructure or remote API endpoints
* Teams that want to reduce the complexity and costs associated with using cloud services directly during development
* Developers that want to make it easier to visualize what's going on in their databases, queues, etc.
* Teams that want to reduce the complexity of setting up their development environment without impacting the development of the app itself

## [Tools integration](#tools-integration)

Works well with Docker Compose and Testcontainers.

## [Modules](#modules)

### [What is container-supported development?](#what-is-container-supported-development)

Container-supported development is the idea of using containers to enhance your development environment by running local instances or emulators of the services your application relies on. Once you're using containers, it's easy to add additional services to visualize or troubleshoot what's going on in your services.

### [Demo: running databases locally](#demo-running-databases-locally)

With container-supported development, it's easy to run databases locally. In this demo, you'll see how to do so, as well as how to connect a non-containerized application to the database.

> Tip
>
> Learn more about running databases in containers in the [Use containerized databases](https://docs.docker.com/guides/databases/) guide.

### [Demo: mocking API endpoints](#demo-mocking-api-endpoints)

Many APIs require data from other data endpoints. In development, this adds complexities such as the sharing of credentials, uptime/availability, and rate limiting. Instead of relying on those services directly, your application can interact with a mock API server.

This demo will demonstrate how using WireMock can make it easy to develop and test an application, including the APIs various error states.

> Tip
>
> Learn more about using WireMock to mock API in the [Mocking API services with WireMock](https://docs.docker.com/guides/wiremock/) guide.

### [Demo: developing the cloud locally](#demo-developing-the-cloud-locally)

When developing apps, it's often easier to outsource aspects of the application to cloud services, such as Amazon S3. However, connecting to those services in local development introduces IAM policies, networking constraints, and provisioning complications. While these requirements are important in a production setting, they complicate development environments significantly.

With container-supported development, you can run local instances of these services during development and testing, removing the need for complex setups. In this demo, you'll see how LocalStack makes it easy to develop and test applications entirely from the developer's workstation.

> Tip
>
> Learn more about using LocalStack in the [Develop and test AWS Cloud applications using LocalStack](https://docs.docker.com/guides/localstack/) guide.

### [Demo: adding additional debug and troubleshooting tools](#demo-adding-additional-debug-and-troubleshooting-tools)

Once you start using containers in your development environment, it becomes much easier to add additional containers to visualize the contents of the databases or message queues, seed document stores, or event publishers. In this demo, you'll see a few of these examples, as well as how you can connect multiple containers together to make testing even easier.

----
url: https://docs.docker.com/admin/organization/organization-faqs/
----

# Organization FAQs

***

Table of contents

***

### [How can I see how many active users are in my organization?](#how-can-i-see-how-many-active-users-are-in-my-organization)

If your organization uses a Software Asset Management tool, you can use it to find out how many users have Docker Desktop installed. If your organization doesn't use this software, you can run an internal survey to find out who is using Docker Desktop.

For more information, see [Identify your Docker users and their Docker accounts](https://docs.docker.com/admin/organization/setup/onboard/#step-one-identify-your-docker-users).

### [Do users need to authenticate with Docker before an owner can add them to an organization?](#do-users-need-to-authenticate-with-docker-before-an-owner-can-add-them-to-an-organization)

No. Organization owners can invite users with their email addresses, and also assign them to a team during the invite process.

### [Can I force my organization's members to authenticate before using Docker Desktop and are there any benefits?](#can-i-force-my-organizations-members-to-authenticate-before-using-docker-desktop-and-are-there-any-benefits)

Yes. You can [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).

Some benefits of enforcing sign-in are:

* Ensures users receive the benefits of your subscription.
* Ensures security features like [Image Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/image-access-management/) and [Registry Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/registry-access-management/) are applied.
* Ensures you gain insights into users' activity.

### [Can I convert my personal Docker ID to an organization account?](#can-i-convert-my-personal-docker-id-to-an-organization-account)

Yes. You can convert your user account to an organization account. Once you convert a user account into an organization, it's not possible to revert it to a personal user account.

For prerequisites and instructions, see [Convert an account into an organization](https://docs.docker.com/admin/organization/setup/convert-account/).

### [Do organization invitees take up seats?](#do-organization-invitees-take-up-seats)

Yes. A user invited to an organization will take up one of the provisioned seats, even if that user hasn’t accepted their invitation yet.

To manage invites, see [Manage organization members](https://docs.docker.com/admin/organization/manage/members/).

### [Do organization owners take a seat?](#do-organization-owners-take-a-seat)

Yes. Organization owners occupy a seat.

### [What is the difference between user, invitee, seat, and member?](#what-is-the-difference-between-user-invitee-seat-and-member)

* User: Docker user with a Docker ID.
* Invitee: A user that an administrator has invited to join an organization but has not yet accepted their invitation.
* Seats: The number of purchased seats in an organization.
* Member: A user who has received and accepted an invitation to join an organization. Member can also refer to a member of a team within an organization.

### [If I have two organizations and a user belongs to both organizations, do they take up two seats?](#if-i-have-two-organizations-and-a-user-belongs-to-both-organizations-do-they-take-up-two-seats)

Yes. In a scenario where a user belongs to two organizations, they take up one seat in each organization.

----
url: https://docs.docker.com/reference/cli/docker/dhi/attestation/
----

# docker dhi attestation

***

| Description                                                               | View attestations for Docker Hardened Images |
| ------------------------------------------------------------------------- | -------------------------------------------- |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker dhi attest` `docker dhi a`           |

## [Description](#description)

Commands to list and inspect attestations attached to Docker Hardened Images

## [Options](#options)

| Option  | Default | Description                                |
| ------- | ------- | ------------------------------------------ |
| `--org` |         | Docker Hub organization (overrides config) |

## [Subcommands](#subcommands)

| Command                                                                                             | Description                                       |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| [`docker dhi attestation get`](https://docs.docker.com/reference/cli/docker/dhi/attestation/get/)   | Get attestation for a Docker Hardened Image       |
| [`docker dhi attestation list`](https://docs.docker.com/reference/cli/docker/dhi/attestation/list/) | List attestations for a Docker Hardened Image     |
| [`docker dhi attestation sbom`](https://docs.docker.com/reference/cli/docker/dhi/attestation/sbom/) | Display the SPDX SBOM for a Docker Hardened Image |

----
url: https://docs.docker.com/guides/testcontainers-java-wiremock/
----

# Testing REST API integrations using WireMock

Table of contents

***

Learn how to create a Spring Boot application that integrates with external REST APIs, then test those integrations using Testcontainers and WireMock.

**Time to complete** 20 minutes

In this guide, you'll learn how to:

* Create a Spring Boot application that talks to external REST APIs
* Test external API integrations using WireMock with both the JUnit 5 extension and the Testcontainers WireMock module

## [Prerequisites](#prerequisites)

* Java 17+
* Maven or Gradle
* A Docker environment supported by Testcontainers

> Note
>
> If you're new to Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/) to learn more about Testcontainers and the benefits of using it.

## [Modules](#modules)

1. [Create the project](https://docs.docker.com/guides/testcontainers-java-wiremock/create-project/)

   Set up a Spring Boot project with an external REST API integration using WireMock and Testcontainers.

2. [Write tests](https://docs.docker.com/guides/testcontainers-java-wiremock/write-tests/)

   Test external REST API integrations using WireMock with both the JUnit 5 extension and the Testcontainers WireMock module.

3. [Run tests](https://docs.docker.com/guides/testcontainers-java-wiremock/run-tests/)

   Run your Testcontainers WireMock integration tests and explore next steps.

----
url: https://docs.docker.com/engine/swarm/how-swarm-mode-works/nodes/
----

# How nodes work

***

Table of contents

***

Swarm mode lets you create a cluster of one or more Docker Engines called a swarm. A swarm consists of one or more nodes: physical or virtual machines running Docker Engine.

There are two types of nodes: [managers](#manager-nodes) and [workers](#worker-nodes).

If you haven't already, read through the [Swarm mode overview](https://docs.docker.com/engine/swarm/) and [key concepts](https://docs.docker.com/engine/swarm/key-concepts/).

## [Manager nodes](#manager-nodes)

Manager nodes handle cluster management tasks:

* Maintaining cluster state
* Scheduling services
* Serving Swarm mode [HTTP API endpoints](https://docs.docker.com/reference/api/engine/)

Using a [Raft](https://raft.github.io/raft.pdf) implementation, the managers maintain a consistent internal state of the entire swarm and all the services running on it. For testing purposes it is OK to run a swarm with a single manager. If the manager in a single-manager swarm fails, your services continue to run, but you need to create a new cluster to recover.

To take advantage of Swarm mode's fault-tolerance features, we recommend you implement an odd number of nodes according to your organization's high-availability requirements. When you have multiple managers you can recover from the failure of a manager node without downtime.

* A three-manager swarm tolerates a maximum loss of one manager.

* A five-manager swarm tolerates a maximum simultaneous loss of two manager nodes.

* An odd number `N` of manager nodes in the cluster tolerates the loss of at most `(N-1)/2` managers. Docker recommends a maximum of seven manager nodes for a swarm.

  > Important
  >
  > Adding more managers does NOT mean increased scalability or higher performance. In general, the opposite is true.

## [Worker nodes](#worker-nodes)

Worker nodes are also instances of Docker Engine whose sole purpose is to execute containers. Worker nodes don't participate in the Raft distributed state, make scheduling decisions, or serve the swarm mode HTTP API.

You can create a swarm of one manager node, but you cannot have a worker node without at least one manager node. By default, all managers are also workers. In a single manager node cluster, you can run commands like `docker service create` and the scheduler places all tasks on the local engine.

To prevent the scheduler from placing tasks on a manager node in a multi-node swarm, set the availability for the manager node to `Drain`. The scheduler gracefully stops tasks on nodes in `Drain` mode and schedules the tasks on an `Active` node. The scheduler does not assign new tasks to nodes with `Drain` availability.

Refer to the [`docker node update`](/reference/cli/docker/node/update/) command line reference to see how to change node availability.

## [Change roles](#change-roles)

You can promote a worker node to be a manager by running `docker node promote`. For example, you may want to promote a worker node when you take a manager node offline for maintenance. See [node promote](/reference/cli/docker/node/promote/).

You can also demote a manager node to a worker node. See [node demote](/reference/cli/docker/node/demote/).

## [Learn more](#learn-more)

* Read about how Swarm mode [services](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) work.

----
url: https://docs.docker.com/enterprise/security/enforce-sign-in/
----

# Enforce sign-in for Docker Desktop

***

Table of contents

***

Subscription: Team Business

For: Administrators

By default, users can access Docker Desktop without signing in to your organization. When users don't sign in as organization members, they miss out on subscription benefits and can bypass security features configured for your organization.

You can enforce sign-in using several methods, depending on your setup:

* [Registry key method (Windows only)](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#registry-key-method-windows-only)
* [Configuration profiles method (Mac only)](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#configuration-profiles-method-mac-only)
* [`.plist` method (Mac only)](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#plist-method-mac-only)
* [`registry.json` method (All)](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#registryjson-method-all)

This page provides an overview of how sign-in enforcement works.

## [How sign-in enforcement works](#how-sign-in-enforcement-works)

When Docker Desktop detects a registry key, `.plist` file, or `registry.json` file:

* A **Sign in required!** prompt appears, requiring users to sign in as organization members to use Docker Desktop.
* If users sign in with accounts that aren't organization members, they're automatically signed out and can't use Docker Desktop. They can select **Sign in** to try again with a different account.
* When users sign in with organization member accounts, they can use Docker Desktop normally.
* When users sign out, the **Sign in required!** prompt reappears and they can no longer use Docker Desktop unless they sign back in.

> Note
>
> Enforcing sign-in for Docker Desktop doesn't affect Docker CLI access. CLI access is only restricted for organizations that enforce single sign-on (SSO).

### [Impact on already-signed-in users](#impact-on-already-signed-in-users)

When enforcement is first deployed, users who are already running Docker Desktop are not immediately affected. Docker Desktop only re-evaluates enforcement on restart.

On the next Docker Desktop restart:

* Users signed in with an organization member account are automatically re-authenticated and continue working uninterrupted.
* Users signed in with a non-member account are immediately signed out on startup and see the **Sign in required!** prompt.

## [Enforcing sign-in versus enforcing single sign-on (SSO)](#enforcing-sign-in-versus-enforcing-single-sign-on-sso)

Enforcing Docker Desktop sign-in and [enforcing SSO](https://docs.docker.com/enterprise/security/single-sign-on/connect/#optional-enforce-sso) are different features that serve different purposes:

| Enforcement                       | Description                                                    | Benefits                                                                                                                                                                                                                                               |
| --------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Enforce sign-in only              | Users must sign in before using Docker Desktop                 | Ensures users receive the benefits of your subscription and ensures security features are applied. In addition, you gain insights into users’ activity.                                                                                                |
| Enforce single sign-on (SSO) only | If users sign in, they must sign in using SSO                  | Centralizes authentication and enforces unified policies set by the identity provider.                                                                                                                                                                 |
| Enforce both                      | Users must sign in using SSO before using Docker Desktop       | Ensures users receive the benefits of your subscription and ensures security features are applied. In addition, you gain insights into users’ activity. It also centralizes authentication and enforces unified policies set by the identity provider. |
| Enforce neither                   | If users sign in, they can use SSO or their Docker credentials | Lets users access Docker Desktop without barriers, at the cost of reduced security and insights.                                                                                                                                                       |

## [Next steps](#next-steps)

* To set up sign-in enforcement, see [Configure sign-in enforcement](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/).
* To configure SSO enforcement, see [Enforce SSO](https://docs.docker.com/enterprise/security/single-sign-on/connect/).

----
url: https://docs.docker.com/engine/network/drivers/overlay/
----

# Overlay network driver

***

Table of contents

***

The `overlay` network driver creates a distributed network among multiple Docker daemon hosts. This network sits on top of (overlays) the host-specific networks, allowing containers connected to it to communicate securely when encryption is enabled. Docker transparently handles routing of each packet to and from the correct Docker daemon host and the correct destination container.

You can create user-defined `overlay` networks using `docker network create`, in the same way that you can create user-defined `bridge` networks. Services or containers can be connected to more than one network at a time. Services or containers can only communicate across networks they're each connected to.

Overlay networks are often used to create a connection between Swarm services, but you can also use it to connect standalone containers running on different hosts. When using standalone containers, it's still required that you use Swarm mode to establish a connection between the hosts.

This page describes overlay networks in general, and when used with standalone containers. For information about overlay for Swarm services, see [Manage Swarm service networks](https://docs.docker.com/engine/swarm/networking/).

## [Requirements](#requirements)

Docker hosts must be part of a swarm to use overlay networks, even when connecting standalone containers. The following ports must be open between participating hosts:

* `2377/tcp`: Swarm control plane (configurable)
* `4789/udp`: Overlay traffic (configurable)
* `7946/tcp` and `7946/udp`: Node communication (not configurable)

## [Create an overlay network](#create-an-overlay-network)

The following table lists the ports that need to be open to each host participating in an overlay network:

| Ports                  | Description                                                                                                                                   |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `2377/tcp`             | The default Swarm control plane port, is configurable with [`docker swarm join --listen-addr`](/reference/cli/docker/swarm/join/#listen-addr) |
| `4789/udp`             | The default overlay traffic port, configurable with [`docker swarm init --data-path-addr`](/reference/cli/docker/swarm/init/#data-path-port)  |
| `7946/tcp`, `7946/udp` | Used for communication among nodes, not configurable                                                                                          |

To create an overlay network that containers on other Docker hosts can connect to, run the following command:

```console
$ docker network create -d overlay --attachable my-attachable-overlay
```

The `--attachable` option enables both standalone containers and Swarm services to connect to the overlay network. Without `--attachable`, only Swarm services can connect to the network.

You can specify the IP address range, subnet, gateway, and other options. See `docker network create --help` for details.

## [Encrypt traffic on an overlay network](#encrypt-traffic-on-an-overlay-network)

Use the `--opt encrypted` flag to encrypt the application data transmitted over the overlay network:

```console
$ docker network create \
  --opt encrypted \
  --driver overlay \
  --attachable \
  my-attachable-multi-host-network
```

This enables IPsec encryption at the level of the Virtual Extensible LAN (VXLAN). This encryption imposes a non-negligible performance penalty, so you should test this option before using it in production.

> Warning
>
> Don't attach Windows containers to encrypted overlay networks.
>
> Overlay network encryption isn't supported on Windows. Swarm doesn't report an error when a Windows host attempts to connect to an encrypted overlay network, but networking for the Windows containers is affected as follows:
>
> * Windows containers can't communicate with Linux containers on the network
> * Data traffic between Windows containers on the network isn't encrypted

## [Attach a container to an overlay network](#attach-a-container-to-an-overlay-network)

Adding containers to an overlay network gives them the ability to communicate with other containers without having to set up routing on the individual Docker daemon hosts. A prerequisite for doing this is that the hosts have joined the same Swarm.

To join an overlay network named `multi-host-network` with a `busybox` container:

```console
$ docker run --network multi-host-network busybox sh
```

> Note
>
> This only works if the overlay network is attachable (created with the `--attachable` flag).

## [Container discovery](#container-discovery)

Publishing ports of a container on an overlay network opens the ports to other containers on the same network. Containers are discoverable by doing a DNS lookup using the container name.

| Flag value                      | Description                                                                                                                                                 |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p 8080:80`                    | Map TCP port 80 in the container to port `8080` on the overlay network.                                                                                     |
| `-p 8080:80/udp`                | Map UDP port 80 in the container to port `8080` on the overlay network.                                                                                     |
| `-p 8080:80/sctp`               | Map SCTP port 80 in the container to port `8080` on the overlay network.                                                                                    |
| `-p 8080:80/tcp -p 8080:80/udp` | Map TCP port 80 in the container to TCP port `8080` on the overlay network, and map UDP port 80 in the container to UDP port `8080` on the overlay network. |

## [Connection limit for overlay networks](#connection-limit-for-overlay-networks)

Due to limitations set by the Linux kernel, overlay networks become unstable and inter-container communications may break when 1000 containers are co-located on the same host.

For more information about this limitation, see [moby/moby#44973](https://github.com/moby/moby/issues/44973#issuecomment-1543747718).

## [Usage examples](#usage-examples)

This section provides hands-on examples for working with overlay networks. These examples cover swarm services and standalone containers on multiple Docker hosts.

### [Prerequisites](#prerequisites)

All examples require at least a single-node swarm. Initialize one by running `docker swarm init` on the host. You can run these examples on multi-node swarms as well.

### [Use the default overlay network](#use-the-default-overlay-network)

This example shows how the default overlay network works with swarm services. You'll create an `nginx` service and examine the network from the service containers' perspective.

#### [Prerequisites for multi-node setup](#prerequisites-for-multi-node-setup)

This walkthrough requires three Docker hosts that can communicate with each other on the same network with no firewall blocking traffic between them:

* `manager`: Functions as both manager and worker
* `worker-1`: Functions as worker only
* `worker-2`: Functions as worker only

If you don't have three hosts available, you can set up three virtual machines on a cloud provider with Docker installed.

#### [Create the swarm](#create-the-swarm)

1. On `manager`, initialize the swarm. If the host has one network interface, the `--advertise-addr` flag is optional:

   ```console
   $ docker swarm init --advertise-addr=<IP-ADDRESS-OF-MANAGER>
   ```

   Save the join token displayed for use with workers.

2. On `worker-1`, join the swarm:

   ```console
   $ docker swarm join --token TOKEN \
     --advertise-addr <IP-ADDRESS-OF-WORKER-1> \
     <IP-ADDRESS-OF-MANAGER>:2377
   ```

3. On `worker-2`, join the swarm:

   ```console
   $ docker swarm join --token TOKEN \
     --advertise-addr <IP-ADDRESS-OF-WORKER-2> \
     <IP-ADDRESS-OF-MANAGER>:2377
   ```

4. On `manager`, list all nodes:

   ```console
   $ docker node ls

   ID                            HOSTNAME            STATUS              AVAILABILITY        MANAGER STATUS
   d68ace5iraw6whp7llvgjpu48 *   ip-172-31-34-146    Ready               Active              Leader
   nvp5rwavvb8lhdggo8fcf7plg     ip-172-31-35-151    Ready               Active
   ouvx2l7qfcxisoyms8mtkgahw     ip-172-31-36-89     Ready               Active
   ```

   Filter by role if needed:

   ```console
   $ docker node ls --filter role=manager
   $ docker node ls --filter role=worker
   ```

5. List Docker networks on all hosts. Each now has an overlay network called `ingress` and a bridge network called `docker_gwbridge`:

   ```console
   $ docker network ls

   NETWORK ID          NAME                DRIVER              SCOPE
   495c570066be        bridge              bridge              local
   961c6cae9945        docker_gwbridge     bridge              local
   ff35ceda3643        host                host                local
   trtnl4tqnc3n        ingress             overlay             swarm
   c8357deec9cb        none                null                local
   ```

The `docker_gwbridge` connects the `ingress` network to the Docker host's network interface. If you create services without specifying a network, they connect to `ingress`. It's recommended to use separate overlay networks for each application or group of related applications.

#### [Create the services](#create-the-services)

1. On `manager`, create a new overlay network:

   ```console
   $ docker network create -d overlay nginx-net
   ```

   The overlay network is automatically created on worker nodes when they run service tasks that need it.

2. On `manager`, create a 5-replica Nginx service connected to `nginx-net`:

   > Note
   >
   > Services can only be created on a manager.

   ```console
   $ docker service create \
     --name my-nginx \
     --publish target=80,published=80 \
     --replicas=5 \
     --network nginx-net \
     nginx
   ```

   The default `ingress` publish mode means you can browse to port 80 on any node and connect to one of the 5 service tasks, even if no tasks run on that node.

3. Monitor service creation progress:

   ```console
   $ docker service ls
   ```

4. Inspect the `nginx-net` network on all hosts. The `Containers` section lists all service tasks connected to the overlay network from that host.

5. From `manager`, inspect the service:

   ```console
   $ docker service inspect my-nginx
   ```

   Notice the information about ports and endpoints.

6. Create a second network and update the service to use it:

   ```console
   $ docker network create -d overlay nginx-net-2
   $ docker service update \
     --network-add nginx-net-2 \
     --network-rm nginx-net \
     my-nginx
   ```

7. Verify the update completed:

   ```console
   $ docker service ls
   ```

   Inspect both networks to verify containers moved from `nginx-net` to `nginx-net-2`.

   > Note
   >
   > Overlay networks are automatically created on swarm worker nodes as needed, but aren't automatically removed.

8. Clean up:

   ```console
   $ docker service rm my-nginx
   $ docker network rm nginx-net nginx-net-2
   ```

### [Use a user-defined overlay network](#use-a-user-defined-overlay-network)

This example shows the recommended approach for production services using custom overlay networks.

#### [Prerequisites](#prerequisites-1)

This assumes the swarm is already set up and you're on a manager node.

#### [Steps](#steps)

1. Create a user-defined overlay network:

   ```console
   $ docker network create -d overlay my-overlay
   ```

2. Start a service using the overlay network, publishing port 80 to port 8080:

   ```console
   $ docker service create \
     --name my-nginx \
     --network my-overlay \
     --replicas 1 \
     --publish published=8080,target=80 \
     nginx:latest
   ```

3. Verify the service task is connected to the network:

   ```console
   $ docker network inspect my-overlay
   ```

   Check the `Containers` section for the `my-nginx` service task.

4. Clean up:

   ```console
   $ docker service rm my-nginx
   $ docker network rm my-overlay
   ```

### [Use an overlay network for standalone containers](#use-an-overlay-network-for-standalone-containers)

This example demonstrates DNS container discovery between standalone containers on different Docker hosts using an overlay network.

#### [Prerequisites](#prerequisites-2)

You need two Docker hosts that can communicate with each other with the following ports open between them:

* TCP port 2377
* TCP and UDP port 7946
* UDP port 4789

This example refers to the hosts as `host1` and `host2`.

#### [Steps](#steps-1)

1. Set up the swarm:

   On `host1`, initialize a swarm:

   ```console
   $ docker swarm init
   Swarm initialized: current node (vz1mm9am11qcmo979tlrlox42) is now a manager.

   To add a worker to this swarm, run the following command:

       docker swarm join --token SWMTKN-1-5g90q48weqrtqryq4kj6ow0e8xm9wmv9o6vgqc5j320ymybd5c-8ex8j0bc40s6hgvy5ui5gl4gy 172.31.47.252:2377
   ```

   On `host2`, join the swarm using the token from the previous output:

   ```console
   $ docker swarm join --token <your_token> <your_ip_address>:2377
   This node joined a swarm as a worker.
   ```

   If the join fails, run `docker swarm leave --force` on `host2`, verify network and firewall settings, and try again.

2. On `host1`, create an attachable overlay network:

   ```console
   $ docker network create --driver=overlay --attachable test-net
   uqsof8phj3ak0rq9k86zta6ht
   ```

   Note the returned network ID.

3. On `host1`, start an interactive container that connects to `test-net`:

   ```console
   $ docker run -it --name alpine1 --network test-net alpine
   / #
   ```

4. On `host2`, list available networks. Notice that `test-net` doesn't exist yet:

   ```console
   $ docker network ls
   NETWORK ID          NAME                DRIVER              SCOPE
   ec299350b504        bridge              bridge              local
   66e77d0d0e9a        docker_gwbridge     bridge              local
   9f6ae26ccb82        host                host                local
   omvdxqrda80z        ingress             overlay             swarm
   b65c952a4b2b        none                null                local
   ```

5. On `host2`, start a detached, interactive container that connects to `test-net`:

   ```console
   $ docker run -dit --name alpine2 --network test-net alpine
   fb635f5ece59563e7b8b99556f816d24e6949a5f6a5b1fbd92ca244db17a4342
   ```

   > Note
   >
   > Automatic DNS container discovery only works with unique container names.

6. On `host2`, verify that `test-net` was created with the same network ID as on `host1`:

   ```console
   $ docker network ls
   NETWORK ID          NAME                DRIVER              SCOPE
   ...
   uqsof8phj3ak        test-net            overlay             swarm
   ```

7. On `host1`, ping `alpine2` from within `alpine1`:

   ```console
   / # ping -c 2 alpine2
   PING alpine2 (10.0.0.5): 56 data bytes
   64 bytes from 10.0.0.5: seq=0 ttl=64 time=0.600 ms
   64 bytes from 10.0.0.5: seq=1 ttl=64 time=0.555 ms

   --- alpine2 ping statistics ---
   2 packets transmitted, 2 packets received, 0% packet loss
   round-trip min/avg/max = 0.555/0.577/0.600 ms
   ```

   The two containers communicate over the overlay network connecting the two hosts. You can also run another container on `host2` and ping `alpine1`:

   ```console
   $ docker run -it --rm --name alpine3 --network test-net alpine
   / # ping -c 2 alpine1
   / # exit
   ```

8. On `host1`, close the `alpine1` session (which stops the container):

   ```console
   / # exit
   ```

9. Clean up. You must stop and remove containers on each host independently:

   On `host2`:

   ```console
   $ docker container stop alpine2
   $ docker network ls
   $ docker container rm alpine2
   ```

   When you stop `alpine2`, `test-net` disappears from `host2`.

   On `host1`:

   ```console
   $ docker container rm alpine1
   $ docker network rm test-net
   ```

## [Next steps](#next-steps)

* Learn about [networking from the container's point of view](https://docs.docker.com/engine/network/)
* Learn about [standalone bridge networks](https://docs.docker.com/engine/network/drivers/bridge/)

----
url: https://docs.docker.com/reference/cli/docker/system/prune/
----

# docker system prune

***

| Description | Remove unused data              |
| ----------- | ------------------------------- |
| Usage       | `docker system prune [OPTIONS]` |

## [Description](#description)

Remove all unused containers, networks, images (both dangling and unused), and optionally, volumes.

## [Options](#options)

| Option                | Default | Description                                                  |
| --------------------- | ------- | ------------------------------------------------------------ |
| `-a, --all`           |         | Remove all unused images not just dangling ones              |
| [`--filter`](#filter) |         | API 1.28+ Provide filter values (e.g. `label=<key>=<value>`) |
| `-f, --force`         |         | Do not prompt for confirmation                               |
| `--volumes`           |         | Prune anonymous volumes                                      |

## [Examples](#examples)

```console
$ docker system prune

WARNING! This will remove:
        - all stopped containers
        - all networks not used by at least one container
        - all dangling images
        - unused build cache
Are you sure you want to continue? [y/N] y

Deleted Containers:
f44f9b81948b3919590d5f79a680d8378f1139b41952e219830a33027c80c867
792776e68ac9d75bce4092bc1b5cc17b779bc926ab04f4185aec9bf1c0d4641f

Deleted Networks:
network1
network2

Deleted Images:
untagged: hello-world@sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f
deleted: sha256:1815c82652c03bfd8644afda26fb184f2ed891d921b20a0703b46768f9755c57
deleted: sha256:45761469c965421a92a69cc50e92c01e0cfa94fe026cdd1233445ea00e96289a

Total reclaimed space: 1.84kB
```

By default, volumes aren't removed to prevent important data from being deleted if there is currently no container using the volume. Use the `--volumes` flag when running the command to prune anonymous volumes as well:

```console
$ docker system prune -a --volumes

WARNING! This will remove:
        - all stopped containers
        - all networks not used by at least one container
        - all anonymous volumes not used by at least one container
        - all images without at least one container associated to them
        - all build cache
Are you sure you want to continue? [y/N] y

Deleted Containers:
0998aa37185a1a7036b0e12cf1ac1b6442dcfa30a5c9650a42ed5010046f195b
73958bfb884fa81fa4cc6baf61055667e940ea2357b4036acbbe25a60f442a4d

Deleted Networks:
my-network-a
my-network-b

Deleted Volumes:
1e31bcd425e913d9f65ec0c3841e9c4ebb543aead2a1cfe0d95a7c5e88bb5026
6a6ab3d6b8d740a1c1d4dbe36a9c5f043dd4bac5f78abfa7d1f2ae5789fe60b0

Deleted Images:
untagged: my-curl:latest
deleted: sha256:7d88582121f2a29031d92017754d62a0d1a215c97e8f0106c586546e7404447d
deleted: sha256:dd14a93d83593d4024152f85d7c63f76aaa4e73e228377ba1d130ef5149f4d8b
untagged: alpine:3.3
deleted: sha256:695f3d04125db3266d4ab7bbb3c6b23aa4293923e762aa2562c54f49a28f009f
untagged: alpine:latest
deleted: sha256:ee4603260daafe1a8c2f3b78fd760922918ab2441cbb2853ed5c439e59c52f96
deleted: sha256:9007f5987db353ec398a223bc5a135c5a9601798ba20a1abba537ea2f8ac765f
deleted: sha256:71fa90c8f04769c9721459d5aa0936db640b92c8c91c9b589b54abd412d120ab
deleted: sha256:bb1c3357b3c30ece26e6604aea7d2ec0ace4166ff34c3616701279c22444c0f3
untagged: my-jq:latest
deleted: sha256:6e66d724542af9bc4c4abf4a909791d7260b6d0110d8e220708b09e4ee1322e1
deleted: sha256:07b3fa89d4b17009eb3988dfc592c7d30ab3ba52d2007832dffcf6d40e3eda7f
deleted: sha256:3a88a5c81eb5c283e72db2dbc6d65cbfd8e80b6c89bb6e714cfaaa0eed99c548

Total reclaimed space: 13.5 MB
```

### [Filtering (--filter)](#filter)

The filtering flag (`--filter`) format is of "key=value". If there is more than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`).

When multiple filters are provided, they are combined as follows:

* Multiple filters with **different keys** are combined using AND logic. An item must satisfy all filter conditions to be pruned.
* Multiple filters with the **same key** are combined using OR logic. An item is pruned if it matches any of the values for that key.

For example, `--filter "label=foo" --filter "until=24h"` prunes items that have the `foo` label **and** were created more than 24 hours ago. Conversely, `--filter "label=foo" --filter "label=bar"` prunes items that have **either** the `foo` **or** `bar` label.

The currently supported filters are:

* until (`<timestamp>`) - only remove containers, images, and networks created before given timestamp
* label (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) - only remove containers, images, networks, and volumes with (or without, in case `label!=...` is used) the specified labels.

The `until` filter can be Unix timestamps, date formatted timestamps, or Go duration strings supported by [ParseDuration](https://pkg.go.dev/time#ParseDuration) (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time. Supported formats for date formatted time stamps include RFC3339Nano, RFC3339, `2006-01-02T15:04:05`, `2006-01-02T15:04:05.999999999`, `2006-01-02T07:00`, and `2006-01-02`. The local timezone on the daemon will be used if you do not provide either a `Z` or a `+-00:00` timezone offset at the end of the timestamp. When providing Unix timestamps enter seconds\[.nanoseconds], where seconds is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (aka Unix epoch or Unix time), and the optional .nanoseconds field is a fraction of a second no more than nine digits long.

The `label` filter accepts two formats. One is the `label=...` (`label=<key>` or `label=<key>=<value>`), which removes containers, images, networks, and volumes with the specified labels. The other format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes containers, images, networks, and volumes without the specified labels.

----
url: https://docs.docker.com/reference/compose-file/extension/
----

# Extensions

***

Table of contents

***

Extensions can be used to make your Compose file more efficient and easier to maintain.

Use the prefix `x-` as a top-level element to modularize configurations that you want to reuse. Compose ignores any fields that start with `x-`, this is the sole exception where Compose silently ignores unrecognized fields.

Extensions can also be used with [anchors and aliases](https://docs.docker.com/reference/compose-file/fragments/).

They also can be used within any structure in a Compose file where user-defined keys are not expected. Compose uses those to enable experimental features, the same way browsers add support for [custom CSS features](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords)

## [Example 1](#example-1)

```yml
x-custom:
  foo:
    - bar
    - zot

services:
  webapp:
    image: example/webapp
    x-foo: bar
```

```yml
service:
  backend:
    deploy:
      placement:
        x-aws-role: "arn:aws:iam::XXXXXXXXXXXX:role/foo"
        x-aws-region: "eu-west-3"
        x-azure-region: "france-central"
```

## [Example 2](#example-2)

```yml
x-env: &env
  environment:
    - CONFIG_KEY
    - EXAMPLE_KEY
 
services:
  first:
    <<: *env
    image: my-image:latest
  second:
    <<: *env
    image: another-image:latest
```

In this example, the environment variables do not belong to either of the services. They’ve been lifted out completely into the `x-env` extension field. This defines a new node which contains the environment field. The `&env` YAML anchor is used so both services can reference the extension field’s value as `*env`.

## [Example 3](#example-3)

```yml
x-function: &function
 labels:
   function: "true"
 depends_on:
   - gateway
 networks:
   - functions
 deploy:
   placement:
     constraints:
       - 'node.platform.os == linux'
services:
 # Node.js gives OS info about the node (Host)
 nodeinfo:
   <<: *function
   image: functions/nodeinfo:latest
   environment:
     no_proxy: "gateway"
     https_proxy: $https_proxy
 # Uses `cat` to echo back response, fastest function to execute.
 echoit:
   <<: *function
   image: functions/alpine:health
   environment:
     fprocess: "cat"
     no_proxy: "gateway"
     https_proxy: $https_proxy
```

The `nodeinfo` and `echoit` services both include the `x-function` extension via the `&function` anchor, then set their specific image and environment.

## [Example 4](#example-4)

Using [YAML merge](https://yaml.org/type/merge.html) it is also possible to use multiple extensions and share and override additional attributes for specific needs:

```yml
x-environment: &default-environment
  FOO: BAR
  ZOT: QUIX
x-keys: &keys
  KEY: VALUE
services:
  frontend:
    image: example/webapp
    environment: 
      << : [*default-environment, *keys]
      YET_ANOTHER: VARIABLE
```

> Note
>
> [YAML merge](https://yaml.org/type/merge.html) only applies to mappings, and can't be used with sequences.
>
> In the example above, the environment variables are declared using the `FOO: BAR` mapping syntax, while the sequence syntax `- FOO=BAR` is only valid when no fragments are involved.

## [Informative historical notes](#informative-historical-notes)

This section is informative. At the time of writing, the following prefixes are known to exist:

| Prefix     | Vendor/Organization |
| ---------- | ------------------- |
| docker     | Docker              |
| kubernetes | Kubernetes          |

## [Specifying byte values](#specifying-byte-values)

Values express a byte value as a string in `{amount}{byte unit}` format: The supported units are `b` (bytes), `k` or `kb` (kilo bytes), `m` or `mb` (mega bytes) and `g` or `gb` (giga bytes).

```text
    2b
    1024kb
    2048k
    300m
    1gb
```

## [Specifying durations](#specifying-durations)

Values express a duration as a string in the form of `{value}{unit}`. The supported units are `us` (microseconds), `ms` (milliseconds), `s` (seconds), `m` (minutes) and `h` (hours). Values can combine multiple values without separator.

```text
  10ms
  40s
  1m30s
  1h5m30s20ms
```

----
url: https://docs.docker.com/reference/cli/sbx/kit/add/
----

# sbx kit add

| Description | Add a kit to a running sandbox          |
| ----------- | --------------------------------------- |
| Usage       | `sbx kit add SANDBOX REFERENCE [flags]` |

## [Description](#description)

Inject a kit artifact into an already-running sandbox.

The kit's files, init files, and startup commands are applied to the running container. This allows extending a sandbox without recreating it.

The sandbox must already exist (created or running). The reference can be a local directory, ZIP file path, OCI registry reference, or git repository.

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

## [Examples](#examples)

```console
# Add a local kit directory to a sandbox
sbx kit add my-sandbox ./mcp-postgres/

# Add a kit from a ZIP file
sbx kit add my-sandbox ./mcp-postgres.zip

# Add a kit from an OCI registry
sbx kit add my-sandbox ghcr.io/myorg/mcp-postgres:1.0

# Add a kit from a git repository
sbx kit add my-sandbox git+https://github.com/org/kits.git#dir=mcp-postgres
```

----
url: https://docs.docker.com/build/building/multi-platform/
----

# Multi-platform builds

***

Table of contents

***

A multi-platform build refers to a single build invocation that targets multiple different operating system or CPU architecture combinations. When building images, this lets you create a single image that can run on multiple platforms, such as `linux/amd64`, `linux/arm64`, and `windows/amd64`.

## [Why multi-platform builds?](#why-multi-platform-builds)

Docker solves the "it works on my machine" problem by packaging applications and their dependencies into containers. This makes it easy to run the same application on different environments, such as development, testing, and production.

But containerization by itself only solves part of the problem. Containers share the host kernel, which means that the code that's running inside the container must be compatible with the host's architecture. This is why you can't run a `linux/amd64` container on an arm64 host (without using emulation), or a Windows container on a Linux host.

Multi-platform builds solve this problem by packaging multiple variants of the same application into a single image. This enables you to run the same image on different types of hardware, such as development machines running x86-64 or ARM-based Amazon EC2 instances in the cloud, without the need for emulation.

### [Difference between single-platform and multi-platform images](#difference-between-single-platform-and-multi-platform-images)

Multi-platform images have a different structure than single-platform images. Single-platform images contain a single manifest that points to a single configuration and a single set of layers. Multi-platform images contain a manifest list, pointing to multiple manifests, each of which points to a different configuration and set of layers.

When you push a multi-platform image to a registry, the registry stores the manifest list and all the individual manifests. When you pull the image, the registry returns the manifest list, and Docker automatically selects the correct variant based on the host's architecture. For example, if you run a multi-platform image on an ARM-based Raspberry Pi, Docker selects the `linux/arm64` variant. If you run the same image on an x86-64 laptop, Docker selects the `linux/amd64` variant (if you're using Linux containers).

## [Prerequisites](#prerequisites)

Multi-platform images require an image store that supports manifest lists. Docker Desktop and Docker Engine 29.0+ use the [containerd image store](https://docs.docker.com/desktop/features/containerd/) by default, which supports multi-platform images out of the box. If you're using one of these versions, no additional setup is needed.

If you're using an older version of Docker Engine, or if you upgraded from an older version that still uses classic storage drivers, you have two options:

* Enable the containerd image store using the [daemon configuration file](https://docs.docker.com/engine/storage/containerd/).
* Create a custom builder using the `docker-container` driver (see the following section).

### [Custom builder](#custom-builder)

As an alternative to using the containerd image store, you can create a custom builder that uses the `docker-container` driver. This driver supports multi-platform builds, but the resulting images aren't loaded into your Docker Engine image store. You can push them to a container registry directly with `docker build --push`.

```console
$ docker buildx create \
  --name container-builder \
  --driver docker-container \
  --bootstrap --use
```

> Note
>
> Builds with the `docker-container` driver aren't automatically loaded to your Docker Engine image store. For more information, see [Build drivers](https://docs.docker.com/build/builders/drivers/).

If you're using Docker Engine standalone and you need to build multi-platform images using emulation, official BuildKit releases bundle QEMU user-mode emulators, so in most cases you don't need to install QEMU manually. See [Install QEMU manually](#install-qemu-manually) if emulation fails, for example with a third-party BuildKit package that doesn't ship the bundled emulators.

## [Build multi-platform images](#build-multi-platform-images)

When triggering a build, use the `--platform` flag to define the target platforms for the build output, such as `linux/amd64` and `linux/arm64`:

```console
$ docker buildx build --platform linux/amd64,linux/arm64 .
```

## [Strategies](#strategies)

You can build multi-platform images using three different strategies, depending on your use case:

1. Using emulation, via [QEMU](#qemu)
2. Use a builder with [multiple native nodes](#multiple-native-nodes)
3. Use [cross-compilation](#cross-compilation) with multi-stage builds

### [QEMU](#qemu)

Building multi-platform images under emulation with QEMU is the easiest way to get started if your builder already supports it. Using emulation requires no changes to your Dockerfile, and BuildKit automatically detects the architectures that are available for emulation.

> Note
>
> Emulation with QEMU can be much slower than native builds, especially for compute-heavy tasks like compilation and compression or decompression.
>
> Use [multiple native nodes](#multiple-native-nodes) or [cross-compilation](#cross-compilation) instead, if possible.

Docker Desktop supports running and building multi-platform images under emulation by default. No configuration is necessary as the builder uses the QEMU that's bundled within the Docker Desktop VM.

#### [Install QEMU manually](#install-qemu-manually)

If the QEMU emulators bundled with BuildKit don't work for your build, for example with a third-party BuildKit package that doesn't ship them, you can install QEMU and register the executable types on the host OS. The prerequisites for installing QEMU are:

* Linux kernel version 4.8 or later
* `binfmt-support` version 2.1.7 or later
* The QEMU binaries must be statically compiled and registered with the `fix_binary` flag

Use the [`tonistiigi/binfmt`](https://github.com/tonistiigi/binfmt) image to install QEMU and register the executable types on the host with a single command:

```console
$ docker run --privileged --rm tonistiigi/binfmt --install all
```

This installs the QEMU binaries and registers them with [`binfmt_misc`](https://en.wikipedia.org/wiki/Binfmt_misc), enabling QEMU to execute non-native file formats for emulation.

Once QEMU is installed and the executable types are registered on the host OS, they work transparently inside containers. You can verify your registration by checking if `F` is among the flags in `/proc/sys/fs/binfmt_misc/qemu-*`.

### [Multiple native nodes](#multiple-native-nodes)

Using multiple native nodes provide better support for more complicated cases that QEMU can't handle, and also provides better performance.

You can add additional nodes to a builder using the `--append` flag.

The following command creates a multi-node builder from Docker contexts named `node-amd64` and `node-arm64`. This example assumes that you've already added those contexts.

```console
$ docker buildx create --use --name mybuild node-amd64
mybuild
$ docker buildx create --append --name mybuild node-arm64
$ docker buildx build --platform linux/amd64,linux/arm64 .
```

While this approach has advantages over emulation, managing multi-node builders introduces some overhead of setting up and managing builder clusters. Alternatively, you can use Docker Build Cloud, a service that provides managed multi-node builders on Docker's infrastructure. With Docker Build Cloud, you get native multi-platform ARM and X86 builders without the burden of maintaining them. Using cloud builders also provides additional benefits, such as a shared build cache.

After signing up for Docker Build Cloud, add the builder to your local environment and start building.

```console
$ docker buildx create --driver cloud ORG/BUILDER_NAME
cloud-ORG-BUILDER_NAME
$ docker build \
  --builder cloud-ORG-BUILDER_NAME \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  --tag IMAGE_NAME \
  --push .
```

For more information, see [Docker Build Cloud](https://docs.docker.com/build-cloud/).

### [Cross-compilation](#cross-compilation)

Depending on your project, if the programming language you use has good support for cross-compilation, you can leverage multi-stage builds to build binaries for target platforms from the native architecture of the builder. Special build arguments, such as `BUILDPLATFORM` and `TARGETPLATFORM`, are automatically available for use in your Dockerfile.

In the following example, the `FROM` instruction is pinned to the native platform of the builder (using the `--platform=$BUILDPLATFORM` option) to prevent emulation from kicking in. Then the pre-defined `$BUILDPLATFORM` and `$TARGETPLATFORM` build arguments are interpolated in a `RUN` instruction. In this case, the values are just printed to stdout with `echo`, but this illustrates how you would pass them to the compiler for cross-compilation.

```dockerfile
# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:alpine AS build
ARG TARGETPLATFORM
ARG BUILDPLATFORM
RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log
FROM alpine
COPY --from=build /log /log
```

## [Examples](#examples)

Here are some examples of multi-platform builds:

* [Simple multi-platform build using emulation](#simple-multi-platform-build-using-emulation)
* [Multi-platform Neovim build using Docker Build Cloud](#multi-platform-neovim-build-using-docker-build-cloud)
* [Cross-compiling a Go application](#cross-compiling-a-go-application)

### [Simple multi-platform build using emulation](#simple-multi-platform-build-using-emulation)

This example demonstrates how to build a simple multi-platform image using emulation with QEMU. The image contains a single file that prints the architecture of the container.

Prerequisites:

* Docker Desktop, or Docker Engine with [QEMU installed](#install-qemu-manually)

Steps:

1. Create an empty directory and navigate to it:

   ```console
   $ mkdir multi-platform
   $ cd multi-platform
   ```

2. Create a simple Dockerfile that prints the architecture of the container:

   ```dockerfile
   # syntax=docker/dockerfile:1
   FROM alpine
   RUN uname -m > /arch
   ```

3. Build the image for `linux/amd64` and `linux/arm64`:

   ```console
   $ docker build --platform linux/amd64,linux/arm64 -t multi-platform .
   ```

4. Run the image and print the architecture:

   ```console
   $ docker run --rm multi-platform cat /arch
   ```

   * If you're running on an x86-64 machine, you should see `x86_64`.
   * If you're running on an ARM machine, you should see `aarch64`.

### [Multi-platform Neovim build using Docker Build Cloud](#multi-platform-neovim-build-using-docker-build-cloud)

This example demonstrates how run a multi-platform build using Docker Build Cloud to compile and export [Neovim](https://github.com/neovim/neovim) binaries for the `linux/amd64` and `linux/arm64` platforms.

Docker Build Cloud provides managed multi-node builders that support native multi-platform builds without the need for emulation, making it much faster to do CPU-intensive tasks like compilation.

Prerequisites:

* You've [signed up for Docker Build Cloud and created a builder](https://docs.docker.com/build-cloud/setup/)

Steps:

1. Create an empty directory and navigate to it:

   ```console
   $ mkdir docker-build-neovim
   $ cd docker-build-neovim
   ```

2. Create a Dockerfile that builds Neovim.

   ```dockerfile
   # syntax=docker/dockerfile:1
   FROM debian:bookworm AS build
   WORKDIR /work
   RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
       --mount=type=cache,target=/var/lib/apt,sharing=locked \
       apt-get update && apt-get install -y \
       build-essential \
       cmake \
       curl \
       gettext \
       ninja-build \
       unzip
   ADD https://github.com/neovim/neovim.git#stable .
   RUN make CMAKE_BUILD_TYPE=RelWithDebInfo

   FROM scratch
   COPY --from=build /work/build/bin/nvim /
   ```

3. Build the image for `linux/amd64` and `linux/arm64` using Docker Build Cloud:

   ```console
   $ docker build \
      --builder <cloud-builder> \
      --platform linux/amd64,linux/arm64 \
      --output ./bin .
   ```

   This command builds the image using the cloud builder and exports the binaries to the `bin` directory.

4. Verify that the binaries are built for both platforms. You should see the `nvim` binary for both `linux/amd64` and `linux/arm64`.

   ```console
   $ tree ./bin
   ./bin
   ├── linux_amd64
   │   └── nvim
   └── linux_arm64
       └── nvim

   3 directories, 2 files
   ```

### [Cross-compiling a Go application](#cross-compiling-a-go-application)

This example demonstrates how to cross-compile a Go application for multiple platforms using multi-stage builds. The application is a simple HTTP server that listens on port 8080 and returns the architecture of the container. This example uses Go, but the same principles apply to other programming languages that support cross-compilation.

Cross-compilation with Docker builds works by leveraging a series of pre-defined (in BuildKit) build arguments that give you information about platforms of the builder and the build targets. You can use these pre-defined arguments to pass the platform information to the compiler.

In Go, you can use the `GOOS` and `GOARCH` environment variables to specify the target platform to build for.

Prerequisites:

* Docker Desktop or Docker Engine

Steps:

1. Create an empty directory and navigate to it:

   ```console
   $ mkdir go-server
   $ cd go-server
   ```

2. Create a base Dockerfile that builds the Go application:

   ```dockerfile
   # syntax=docker/dockerfile:1
   FROM golang:alpine AS build
   WORKDIR /app
   ADD https://github.com/dvdksn/buildme.git#eb6279e0ad8a10003718656c6867539bd9426ad8 .
   RUN go build -o server .

   FROM alpine
   COPY --from=build /app/server /server
   ENTRYPOINT ["/server"]
   ```

   This Dockerfile can't build multi-platform with cross-compilation yet. If you were to try to build this Dockerfile with `docker build`, the builder would attempt to use emulation to build the image for the specified platforms.

3. To add cross-compilation support, update the Dockerfile to use the pre-defined `BUILDPLATFORM`, `TARGETOS` and `TARGETARCH` build arguments.

   * Pin the `golang` image to the platform of the builder using the `--platform=$BUILDPLATFORM` option.
   * Add `ARG` instructions for the Go compilation stages to make the `TARGETOS` and `TARGETARCH` build arguments available to the commands in this stage.
   * Set the `GOOS` and `GOARCH` environment variables to the values of `TARGETOS` and `TARGETARCH`. The Go compiler uses these variables to do cross-compilation.

   ```dockerfile
   # syntax=docker/dockerfile:1
   FROM --platform=$BUILDPLATFORM golang:alpine AS build
   ARG TARGETOS
   ARG TARGETARCH
   WORKDIR /app
   ADD https://github.com/dvdksn/buildme.git#eb6279e0ad8a10003718656c6867539bd9426ad8 .
   RUN GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o server .

   FROM alpine
   COPY --from=build /app/server /server
   ENTRYPOINT ["/server"]
   ```

   ```dockerfile
   # syntax=docker/dockerfile:1
   FROM golang:alpine AS build
   WORKDIR /app
   ADD https://github.com/dvdksn/buildme.git#eb6279e0ad8a10003718656c6867539bd9426ad8 .
   RUN go build -o server .

   FROM alpine
   COPY --from=build /app/server /server
   ENTRYPOINT ["/server"]
   ```

   ```diff
   # syntax=docker/dockerfile:1
   -FROM golang:alpine AS build
   +FROM --platform=$BUILDPLATFORM golang:alpine AS build
   +ARG TARGETOS
   +ARG TARGETARCH
   WORKDIR /app
   ADD https://github.com/dvdksn/buildme.git#eb6279e0ad8a10003718656c6867539bd9426ad8 .
   -RUN go build -o server .
   +RUN GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o server .

   FROM alpine
   COPY --from=build /app/server /server
   ENTRYPOINT ["/server"]
   ```

4. Build the image for `linux/amd64` and `linux/arm64`:

   ```console
   $ docker build --platform linux/amd64,linux/arm64 -t go-server .
   ```

This example has shown how to cross-compile a Go application for multiple platforms with Docker builds. The specific steps on how to do cross-compilation may vary depending on the programming language you're using. Consult the documentation for your programming language to learn more about cross-compiling for different platforms.

> Tip
>
> You may also want to consider checking out [xx - Dockerfile cross-compilation helpers](https://github.com/tonistiigi/xx). `xx` is a Docker image containing utility scripts that make cross-compiling with Docker builds easier.

----
url: https://docs.docker.com/reference/cli/docker/image/load/
----

# docker image load

***

| Description                                                               | Load an image from a tar archive or STDIN |
| ------------------------------------------------------------------------- | ----------------------------------------- |
| Usage                                                                     | `docker image load [OPTIONS]`             |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker load`                             |

## [Description](#description)

Load an image or repository from a tar archive (even if compressed with gzip, bzip2, xz or zstd) from a file or STDIN. It restores both images and tags.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                    |
| ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-i, --input`](#input)   |         | Read from tar archive file, instead of STDIN                                                                                                   |
| [`--platform`](#platform) |         | API 1.48+ Load only the given platform(s). Formatted as a comma-separated list of `os[/arch[/variant]]` (e.g., `linux/amd64,linux/arm64/v8`).  |
| `-q, --quiet`             |         | Suppress the load output                                                                                                                       |

## [Examples](#examples)

```console
$ docker image ls

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
```

### [Load images from STDIN](#load-images-from-stdin)

```console
$ docker load < busybox.tar.gz

Loaded image: busybox:latest
$ docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
busybox             latest              769b9341d937        7 weeks ago         2.489 MB
```

### [Load images from a file (--input)](#input)

```console
$ docker load --input fedora.tar

Loaded image: fedora:rawhide
Loaded image: fedora:20

$ docker images

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
busybox             latest              769b9341d937        7 weeks ago         2.489 MB
fedora              rawhide             0d20aec6529d        7 weeks ago         387 MB
fedora              20                  58394af37342        7 weeks ago         385.5 MB
fedora              heisenbug           58394af37342        7 weeks ago         385.5 MB
fedora              latest              58394af37342        7 weeks ago         385.5 MB
```

### [Load a specific platform (--platform)](#platform)

The `--platform` option allows you to specify which platform variant of the image to load. By default, `docker load` loads all platform variants that are present in the archive. Use the `--platform` option to specify which platform variant of the image to load. An error is produced if the given platform is not present in the archive.

The platform option takes the `os[/arch[/variant]]` format; for example, `linux/amd64` or `linux/arm64/v8`. Architecture and variant are optional, and default to the daemon's native architecture if omitted.

The following example loads the `linux/amd64` variant of an `alpine` image from an archive that contains multiple platform variants.

```console
$ docker image load -i image.tar --platform=linux/amd64
Loaded image: alpine:latest
```

The following example attempts to load a `linux/ppc64le` image from an archive, but the given platform is not present in the archive;

```console
$ docker image load -i image.tar --platform=linux/ppc64le
requested platform (linux/ppc64le) not found: image might be filtered out
```

----
url: https://docs.docker.com/build/policies/debugging/
----

# Debugging build policies

***

Table of contents

***

When policies don't work as expected, use the tools available to inspect policy evaluation and understand what's happening. This guide covers the debugging techniques and common gotchas.

## [Quick reference](#quick-reference)

Essential debugging commands:

```console
# See complete input data during builds (recommended)
$ docker buildx build --progress=plain --policy log-level=debug .

# See policy checks and decisions
$ docker buildx build --progress=plain .

# Explore input structure for different sources
$ docker buildx policy eval --print .
$ docker buildx policy eval --print https://github.com/org/repo.git
$ docker buildx policy eval --print docker-image://alpine:3.19

# Test if policy allows a source
$ docker buildx policy eval .
```

## [Policy output with `--progress=plain`](#policy-output-with---progressplain)

To see policy evaluation during builds, use `--progress=plain`:

```console
$ docker buildx build --progress=plain .
```

This shows all policy checks, decisions, and `print()` output. Without `--progress=plain`, policy evaluation is silent unless there's an error.

```plaintext
#1 loading policies Dockerfile.rego
#1 0.010 checking policy for source docker-image://alpine:3.19 (linux/arm64)
#1 0.011 Dockerfile.rego:8: image: {"ref":"alpine:3.19","repo":"alpine","tag":"3.19"}
#1 0.012 policy decision for source docker-image://alpine:3.19: ALLOW
```

If a policy denies a source, you'll see:

```text
#1 0.012 policy decision for source docker-image://nginx:latest: DENY
ERROR: source "docker-image://nginx:latest" not allowed by policy
```

## [Debug logging](#debug-logging)

For detailed debugging, add `--policy log-level=debug` to see the full input JSON, unresolved fields, and policy responses:

```console
$ docker buildx build --progress=plain --policy log-level=debug .
```

This shows significantly more information than the default level, including the complete input structure for each source without needing `print()` statements in your policy.

Complete input JSON:

```text
#1 0.007 policy input: {
#1 0.007   "env": {
#1 0.007     "filename": "."
#1 0.007   },
#1 0.007   "image": {
#1 0.007     "ref": "docker.io/library/alpine:3.19",
#1 0.007     "host": "docker.io",
#1 0.007     "repo": "alpine",
#1 0.007     "fullRepo": "docker.io/library/alpine",
#1 0.007     "tag": "3.19",
#1 0.007     "platform": "linux/arm64",
#1 0.007     "os": "linux",
#1 0.007     "arch": "arm64"
#1 0.007   }
#1 0.007 }
```

Unresolved fields:

```text
#1 0.007 unknowns for policy evaluation: [input.image.checksum input.image.labels input.image.user input.image.volumes input.image.workingDir input.image.env input.image.hasProvenance input.image.signatures]
```

Policy response:

```text
#1 0.008 policy response: map[allow:true]
```

This detailed output is invaluable for understanding exactly what data your policy receives and which fields are not yet resolved. Use debug logging when developing policies to avoid needing extensive `print()` statements.

## [Conditional debugging with print()](#conditional-debugging-with-print)

While `--policy log-level=debug` shows all input data automatically, the `print()` function is useful for debugging specific rule logic and conditional flows:

```rego
allow if {
    input.image
    print("Checking image:", input.image.repo, "isCanonical:", input.image.isCanonical)
    input.image.repo == "alpine"
    input.image.isCanonical
}
```

Use `print()` to debug conditional logic within rules or track which rules are evaluating. For general input inspection during development, use `--policy log-level=debug` instead - it requires no policy modifications.

> Note
>
> Print statements only execute when their containing rule evaluates. A rule like `allow if { input.image; print(...) }` only prints for image inputs, not for Git repos, HTTP downloads, or local files.

## [Common issues](#common-issues)

### [Full repository path or repository name](#full-repository-path-or-repository-name)

Symptom: Policy checking repository names doesn't match as expected.

Cause: Docker Hub images use `input.image.repo` for the short name (`"alpine"`) but `input.image.fullRepo` includes the full path (`"docker.io/library/alpine"`).

Solution:

```rego
# Match just the repo name (works for Docker Hub and other registries)
allow if {
    input.image
    input.image.repo == "alpine"
}

# Or match the full repository path
allow if {
    input.image
    input.image.fullRepo == "docker.io/library/alpine"
}
```

### [Policy evaluation happens multiple times](#policy-evaluation-happens-multiple-times)

Symptom: Build output shows the same source evaluated multiple times.

Cause: BuildKit may evaluate policies at different stages (reference resolution, actual pull) or for different platforms.

This is normal behavior. Policies should be idempotent (produce same result each time for the same input).

### [Fields missing with `policy eval --print`](#fields-missing-with-policy-eval---print)

Symptom: `docker buildx policy eval --print` doesn't show expected fields like `hasProvenance`, `labels`, or `checksum`.

Cause: `--print` shows only reference information by default, without fetching from registries.

Solution: Use `--fields` to fetch specific metadata fields:

```console
$ docker buildx policy eval --print --fields image.labels docker-image://alpine:3.19
```

See [Using build policies](https://docs.docker.com/build/policies/usage/#testing-policies-with-policy-eval) for details.

## [Next steps](#next-steps)

* See complete field reference: [Input reference](https://docs.docker.com/build/policies/inputs/)
* Review example policies: [Examples](https://docs.docker.com/build/policies/examples/)
* Learn policy usage patterns: [Using build policies](https://docs.docker.com/build/policies/usage/)

----
url: https://docs.docker.com/reference/cli/docker/desktop/restart/
----

# docker desktop restart

***

| Description | Restart Docker Desktop   |
| ----------- | ------------------------ |
| Usage       | `docker desktop restart` |

## [Options](#options)

| Option         | Default | Description                                                                                                                                 |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `-d, --detach` |         | Do not synchronously wait for the requested operation to complete.                                                                          |
| `--timeout`    |         | Terminate the running command after the specified timeout with a non-zero exit code. A value of zero (the default) or -1 means no timeout.  |

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/prepare/
----

# docker dhi customization prepare

***

| Description | Prepare a new customization YAML file from a DHI base image tag |
| ----------- | --------------------------------------------------------------- |
| Usage       | `docker dhi customization prepare <dhi-repository> <tag>`       |

## [Description](#description)

Prepare a new single or bulk customization YAML file by fetching tag details from Docker Hardened Images. This creates a scaffold YAML file that can be used with the create command.

Single customization — provide the DHI source repository and tag as positional arguments: docker dhi customization prepare golang 1.24-dev --destination myorg/dhi-golang

Bulk customization — pipe a JSON array of {destination, tag-definition-id} objects via stdin: echo '\[{"destination":"myorg/dhi-golang","tag-definition-id":"golang/alpine-3.23/1.24-dev"}]'\
\| docker dhi customization prepare --name my-custo

The scaffold is written to stdout; redirect to a file if needed: docker dhi customization prepare golang 1.24-dev > customization.yaml

Run 'docker dhi customization list' to see available source repositories, or use shell completion to discover repository names and tags.

## [Options](#options)

| Option              | Default | Description                                    |
| ------------------- | ------- | ---------------------------------------------- |
| `-d, --destination` |         | Destination repository (e.g. myorg/dhi-golang) |
| `-n, --name`        |         | Name for the customization                     |

----
url: https://docs.docker.com/reference/compose-file/deploy/
----

# Compose Deploy Specification

***

Table of contents

***

Deploy is an optional part of the Compose Specification. It provides a set of deployment specifications for managing the behavior of containers across different environments.

## [Attributes](#attributes)

### [`endpoint_mode`](#endpoint_mode)

`endpoint_mode` specifies a service discovery method for external clients connecting to a service. The Compose Deploy Specification defines two canonical values:

* `endpoint_mode: vip`: Assigns the service a virtual IP (VIP) that acts as the front end for clients to reach the service on a network. Platform routes requests between the client and nodes running the service, without client knowledge of how many nodes are participating in the service or their IP addresses or ports.

* `endpoint_mode: dnsrr`: Platform sets up DNS entries for the service such that a DNS query for the service name returns a list of IP addresses (DNS round-robin), and the client connects directly to one of these.

```yml
services:
  frontend:
    image: example/webapp
    ports:
      - "8080:80"
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: vip
```

### [`labels`](#labels)

`labels` specifies metadata for the service. These labels are only set on the service and not on any containers for the service. This assumes the platform has some native concept of "service" that can match the Compose application model.

```yml
services:
  frontend:
    image: example/webapp
    deploy:
      labels:
        com.example.description: "This label will appear on the web service"
```

### [`mode`](#mode)

`mode` defines the replication model used to run a service or job. Options include:

* `global`: Ensures exactly one task continuously runs per physical node until stopped.

* `replicated`: Continuously runs a specified number of tasks across nodes until stopped (default).

* `replicated-job`: Executes a defined number of tasks until a completion state (exits with code 0)'.

  * Total tasks are determined by `replicas`.
  * Concurrency can be limited using the `max-concurrent` option (CLI only).

* `global-job`: Executes one task per physical node with a completion state (exits with code 0).
  * Automatically runs on new nodes as they are added.

```yml
services:
  frontend:
    image: example/webapp
    deploy:
      mode: global

  batch-job:
    image: example/processor
    deploy:
      mode: replicated-job
      replicas: 5

  maintenance:
    image: example/updater
    deploy:
      mode: global-job
```

> Note
>
> * Job modes (`replicated-job` and `global-job`) are designed for tasks that complete and exit with code 0.
> * Completed tasks remain until explicitly removed.
> * Options like `max-concurrent` for controlling concurrency are supported only via the CLI and are not available in Compose.

For more detailed information about job options and behavior, see the [Docker CLI documentation](/reference/cli/docker/service/create/#running-as-a-job)

### [`placement`](#placement)

`placement` specifies constraints and preferences for the platform to select a physical node to run service containers.

#### [`constraints`](#constraints)

`constraints` defines a required property the platform's node must fulfill to run the service container. For a further example, see the [CLI reference docs](/reference/cli/docker/service/create/#constraint).

```yml
deploy:
  placement:
    constraints:
      - node.labels.disktype==ssd
```

#### [`preferences`](#preferences)

`preferences` defines a strategy (currently `spread` is the only supported strategy) to spread tasks evenly over the values of the datacenter node label. For a further example, see the [CLI reference docs](/reference/cli/docker/service/create/#placement-pref)

```yml
deploy:
  placement:
    preferences:
      - spread: node.labels.zone
```

### [`replicas`](#replicas)

If the service is `replicated` (which is the default), `replicas` specifies the number of containers that should be running at any given time.

```yml
services:
  frontend:
    image: example/webapp
    deploy:
      mode: replicated
      replicas: 6
```

### [`resources`](#resources)

`resources` configures physical resource constraints for container to run on platform. Those constraints can be configured as:

* `limits`: The platform must prevent the container from allocating more resources.
* `reservations`: The platform must guarantee the container can allocate at least the configured amount.

```yml
services:
  frontend:
    image: example/webapp
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
          pids: 1
        reservations:
          cpus: '0.25'
          memory: 20M
```

#### [`cpus`](#cpus)

`cpus` configures a limit or reservation for how much of the available CPU resources, as number of cores, a container can use.

#### [`memory`](#memory)

`memory` configures a limit or reservation on the amount of memory a container can allocate, set as a string expressing a [byte value](https://docs.docker.com/reference/compose-file/extension/#specifying-byte-values).

#### [`pids`](#pids)

`pids` tunes a container’s PIDs limit, set as an integer.

#### [`devices`](#devices)

`devices` configures reservations of the devices a container can use. It contains a list of reservations, each set as an object with the following parameters: `capabilities`, `driver`, `count`, `device_ids` and `options`.

Devices are reserved using a list of capabilities, making `capabilities` the only required field. A device must satisfy all the requested capabilities for a successful reservation.

##### [`capabilities`](#capabilities)

`capabilities` are set as a list of strings, expressing both generic and driver specific capabilities. The following generic capabilities are recognized today:

* `gpu`: Graphics accelerator
* `tpu`: AI accelerator

To avoid name clashes, driver specific capabilities must be prefixed with the driver name. For example, reserving an NVIDIA CUDA-enabled accelerator might look like this:

```yml
deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["nvidia-compute"]
```

##### [`driver`](#driver)

A different driver for the reserved device(s) can be requested using `driver` field. The value is specified as a string.

```yml
deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["nvidia-compute"]
          driver: nvidia
```

##### [`count`](#count)

If `count` is set to `all` or not specified, Compose reserves all devices that satisfy the requested capabilities. Otherwise, Compose reserves at least the number of devices specified. The value is specified as an integer.

```yml
deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["tpu"]
          count: 2
```

`count` and `device_ids` fields are exclusive. Compose returns an error if both are specified.

##### [`device_ids`](#device_ids)

If `device_ids` is set, Compose reserves devices with the specified IDs provided they satisfy the requested capabilities. The value is specified as a list of strings.

```yml
deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["gpu"]
          device_ids: ["GPU-f123d1c9-26bb-df9b-1c23-4a731f61d8c7"]
```

`count` and `device_ids` fields are exclusive. Compose returns an error if both are specified.

##### [`options`](#options)

Driver specific options can be set with `options` as key-value pairs.

```yml
deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["gpu"]
          driver: gpuvendor
          options:
            virtualization: false
```

### [`restart_policy`](#restart_policy)

`restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose considers the `restart` field set by the service configuration.

* `condition`. When set to:

  * `none`, containers are not automatically restarted regardless of the exit status.
  * `on-failure`, the container is restarted if it exits due to an error, which manifests as a non-zero exit code.
  * `any` (default), containers are restarted regardless of the exit status.

* `delay`: How long to wait between restart attempts, specified as a [duration](https://docs.docker.com/reference/compose-file/extension/#specifying-durations). The default is 0, meaning restart attempts can occur immediately.

* `max_attempts`: The maximum number of failed restart attempts allowed before giving up. (Default: unlimited retries.) A failed attempt only counts toward `max_attempts` if the container does not successfully restart within the time defined by `window`. For example, if `max_attempts` is set to `2` and the container fails to restart within the window on the first try, Compose continues retrying until two such failed attempts occur, even if that means trying more than twice.

* `window`: The amount of time to wait after a restart to determine whether it was successful, specified as a [duration](https://docs.docker.com/reference/compose-file/extension/#specifying-durations) (default: the result is evaluated immediately after the restart).

```yml
deploy:
  restart_policy:
    condition: on-failure
    delay: 5s
    max_attempts: 3
    window: 120s
```

### [`rollback_config`](#rollback_config)

`rollback_config` configures how the service should be rolled back in case of a failing update.

* `parallelism`: The number of containers to rollback at a time. If set to 0, all containers rollback simultaneously.
* `delay`: The time to wait between each container group's rollback (default 0s).
* `failure_action`: What to do if a rollback fails. One of `continue` or `pause` (default `pause`)
* `monitor`: Duration after each task update to monitor for failure `(ns|us|ms|s|m|h)` (default 0s).
* `max_failure_ratio`: Failure rate to tolerate during a rollback (default 0).
* `order`: Order of operations during rollbacks. One of `stop-first` (old task is stopped before starting new one), or `start-first` (new task is started first, and the running tasks briefly overlap) (default `stop-first`).

### [`update_config`](#update_config)

`update_config` configures how the service should be updated. Useful for configuring rolling updates.

* `parallelism`: The number of containers to update at a time.
* `delay`: The time to wait between updating a group of containers.
* `failure_action`: What to do if an update fails. One of `continue`, `rollback`, or `pause` (default: `pause`).
* `monitor`: Duration after each task update to monitor for failure `(ns|us|ms|s|m|h)` (default 0s).
* `max_failure_ratio`: Failure rate to tolerate during an update.
* `order`: Order of operations during updates. One of `stop-first` (old task is stopped before starting new one), or `start-first` (new task is started first, and the running tasks briefly overlap) (default `stop-first`).

```yml
deploy:
  update_config:
    parallelism: 2
    delay: 10s
    order: stop-first
```

----
url: https://docs.docker.com/guides/cpp/develop/
----

# Use containers for C++ development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a C++ application](https://docs.docker.com/guides/cpp/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment for your containerized application. This includes:

* Configuring Compose to automatically update your running Compose services as you edit and save your code

## [Get the sample application](#get-the-sample-application)

Clone the sample application to use with this guide. Open a terminal, change directory to a directory that you want to work in, and run the following command to clone the repository:

```console
$ git clone https://github.com/dockersamples/c-plus-plus-docker.git && cd c-plus-plus-docker
```

## [Automatically update services](#automatically-update-services)

Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

Open your `compose.yml` file in an IDE or text editor and then add the Compose Watch instructions. The following example shows how to add Compose Watch to your `compose.yml` file.

|                                             |                                                                                                                                                                                                                 |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ```
``` | ```yaml
services:
  ok-api:
    image: ok-api
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    develop:
      watch:
        - action: rebuild
          path: .
``` |

Run the following command to run your application with Compose Watch.

```console
$ docker compose watch
```

Now, if you modify your `ok_api.cpp` you will see the changes in real time without re-building the image.

To test it out, open the `ok_api.cpp` file in your favorite text editor and change the message from `{"Status" : "OK"}` to `{"Status" : "Updated"}`. Save the file and refresh your browser at <http://localhost:8080>. You should see the updated message.

[Configure CI/CD for your C++ application »](https://docs.docker.com/guides/cpp/configure-ci-cd/)

----
url: https://docs.docker.com/build/ci/github-actions/annotations/
----

# Add image annotations with GitHub Actions

***

Table of contents

***

Annotations let you specify arbitrary metadata for OCI image components, such as manifests, indexes, and descriptors.

To add annotations when building images with GitHub Actions, use the [metadata-action](https://github.com/docker/metadata-action#overwrite-labels-and-annotations) to automatically create OCI-compliant annotations. The metadata action creates an `annotations` output that you can reference, both with [build-push-action](https://github.com/docker/build-push-action/) and [bake-action](https://github.com/docker/bake-action/).

```yaml
name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.IMAGE_NAME }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          push: true
```

```yaml
name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.IMAGE_NAME }}

      - name: Build
        uses: docker/bake-action@v7
        with:
          files: |
            ./docker-bake.hcl
            cwd://${{ steps.meta.outputs.bake-file-tags }}
            cwd://${{ steps.meta.outputs.bake-file-annotations }}
          push: true
```

## [Configure annotation level](#configure-annotation-level)

By default, annotations are placed on image manifests. To configure the [annotation level](https://docs.docker.com/build/metadata/annotations/#specify-annotation-level), set the `DOCKER_METADATA_ANNOTATIONS_LEVELS` environment variable on the `metadata-action` step to a comma-separated list of all the levels that you want to annotate. For example, setting `DOCKER_METADATA_ANNOTATIONS_LEVELS` to `index` results in annotations on the image index instead of the manifests.

The following example creates annotations on both the image index and manifests.

```yaml
name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.IMAGE_NAME }}
        env:
          DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          push: true
```

> Note
>
> The build must produce the components that you want to annotate. For example, to annotate an image index, the build must produce an index. If the build produces only a manifest and you specify `index` or `index-descriptor`, the build fails.

----
url: https://docs.docker.com/reference/cli/docker/buildx/stop/
----

# docker buildx stop

***

| Description | Stop builder instance       |
| ----------- | --------------------------- |
| Usage       | `docker buildx stop [NAME]` |

## [Description](#description)

Stops the specified or current builder. This does not prevent buildx build to restart the builder. The implementation of stop depends on the driver.

## [Examples](#examples)

### [Override the configured builder instance (--builder)](#builder)

Same as [`buildx --builder`](/reference/cli/docker/buildx/#builder).

----
url: https://docs.docker.com/engine/release-notes/17.10/
----

# Docker Engine 17.10 release notes

***

Table of contents

***

## [17.10.0-ce](#17100-ce)

2017-10-17

> Important
>
> `docker service scale` and `docker service rollback` use non-detached mode as default, use `--detach` to keep the old behaviour.

### [Builder](#builder)

* Reset uid/gid to 0 in uploaded build context to share build cache with other clients [docker/cli#513](https://github.com/docker/cli/pull/513)

- Add support for `ADD` urls without any sub path [moby/moby#34217](https://github.com/moby/moby/pull/34217)

### [Client](#client)

* Move output of `docker stack rm` to stdout [docker/cli#491](https://github.com/docker/cli/pull/491)
* Use natural sort for secrets and configs in cli [docker/cli#307](https://github.com/docker/cli/pull/307)
* Use non-detached mode as default for `docker service` commands [docker/cli#525](https://github.com/docker/cli/pull/525)
* Set APIVersion on the client, even when Ping fails [docker/cli#546](https://github.com/docker/cli/pull/546)

- Fix loader error with different build syntax in `docker stack deploy` [docker/cli#544](https://github.com/docker/cli/pull/544)

* Change the default output format for `docker container stats` to show `CONTAINER ID` and `NAME` [docker/cli#565](https://github.com/docker/cli/pull/565)

- Add `--no-trunc` flag to `docker container stats` [docker/cli#565](https://github.com/docker/cli/pull/565)
- Add experimental `docker trust`: `view`, `revoke`, `sign` subcommands [docker/cli#472](https://github.com/docker/cli/pull/472)

* Various doc and shell completion fixes [docker/cli#610](https://github.com/docker/cli/pull/610) [docker/cli#611](https://github.com/docker/cli/pull/611) [docker/cli#618](https://github.com/docker/cli/pull/618) [docker/cli#580](https://github.com/docker/cli/pull/580) [docker/cli#598](https://github.com/docker/cli/pull/598) [docker/cli#603](https://github.com/docker/cli/pull/603)

### [Networking](#networking)

* Enabling ILB/ELB on windows using per-node, per-network LB endpoint [moby/moby#34674](https://github.com/moby/moby/pull/34674)
* Overlay fix for transient IP reuse [docker/libnetwork#1935](https://github.com/docker/libnetwork/pull/1935)
* Serializing bitseq alloc [docker/libnetwork#1788](https://github.com/docker/libnetwork/pull/1788)

- Disable hostname lookup on chain exists check [docker/libnetwork#1974](https://github.com/docker/libnetwork/pull/1974)

### [Runtime](#runtime)

* LCOW: Add UVM debuggability by grabbing logs before tear-down [moby/moby#34846](https://github.com/moby/moby/pull/34846)
* LCOW: Prepare work for bind mounts [moby/moby#34258](https://github.com/moby/moby/pull/34258)
* LCOW: Support for docker cp, ADD/COPY on build [moby/moby#34252](https://github.com/moby/moby/pull/34252)
* LCOW: VHDX boot to readonly [moby/moby#34754](https://github.com/moby/moby/pull/34754)
* Volume: evaluate symlinks before relabeling mount source [moby/moby#34792](https://github.com/moby/moby/pull/34792)

- Fixing ‘docker cp’ to allow new target file name in a host symlinked directory [moby/moby#31993](https://github.com/moby/moby/pull/31993)

* Add support for Windows version filtering on pull [moby/moby#35090](https://github.com/moby/moby/pull/35090)

### [Swarm mode](#swarm-mode)

* Produce an error if `docker swarm init --force-new-cluster` is executed on worker nodes [moby/moby#34881](https://github.com/moby/moby/pull/34881)

- Add support for `.Node.Hostname` templating in swarm services [moby/moby#34686](https://github.com/moby/moby/pull/34686)

* Increase gRPC request timeout to 20 seconds for sending snapshots [docker/swarmkit#2391](https://github.com/docker/swarmkit/pull/2391)

- Do not filter nodes if logdriver is set to `none` [docker/swarmkit#2396](https://github.com/docker/swarmkit/pull/2396)

* Adding ipam options to ipam driver requests [docker/swarmkit#2324](https://github.com/docker/swarmkit/pull/2324)

----
url: https://docs.docker.com/reference/cli/sbx/reset/
----

# sbx reset

| Description | Reset all sandboxes and clean up state |
| ----------- | -------------------------------------- |
| Usage       | `sbx reset [flags]`                    |

## [Description](#description)

Reset Docker Sandboxes to a freshly-installed state.

This command will:

* Stop all running sandboxes gracefully (30s timeout)
* Clear image cache
* Clear all internal registries
* Delete all sandbox state
* Remove all policies
* Delete all stored secrets
* Sign out of Docker Sandboxes
* Stop the daemon
* Remove all state, cache, and config directories

WARNING: This is destructive and cannot be undone. Running agents will be terminated and their work lost. Cached images will be deleted and recreated on next use. Stored secrets will need to be re-entered.

Use --preserve-secrets to keep stored secrets. By default, you will be prompted to confirm (y/N). Use --force to skip the confirmation prompt.

## [Options](#options)

| Option               | Default | Description              |
| -------------------- | ------- | ------------------------ |
| `-f, --force`        |         | Skip confirmation prompt |
| `--preserve-secrets` |         | Keep stored secrets      |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/engine/extend/plugin_api/
----

# Docker Plugin API

***

Table of contents

***

Docker plugins are out-of-process extensions which add capabilities to the Docker Engine.

This document describes the Docker Engine plugin API. To view information on plugins managed by Docker Engine, refer to [Docker Engine plugin system](https://docs.docker.com/engine/extend/).

This page is intended for people who want to develop their own Docker plugin. If you just want to learn about or use Docker plugins, look [here](https://docs.docker.com/engine/extend/legacy_plugins/).

## [What plugins are](#what-plugins-are)

A plugin is a process running on the same or a different host as the Docker daemon, which registers itself by placing a file on the daemon host in one of the plugin directories described in [Plugin discovery](#plugin-discovery).

Plugins have human-readable names, which are short, lowercase strings. For example, `myplugin`.

Plugins can run inside or outside containers. Currently running them outside containers is recommended.

## [Plugin discovery](#plugin-discovery)

Docker discovers plugins by looking for them in the plugin directory whenever a user or container tries to use one by name.

There are three types of files which can be put in the plugin directory.

* `.sock` files are Unix domain sockets.
* `.spec` files are text files containing a URL, such as `unix:///other.sock` or `tcp://localhost:8080`.
* `.json` files are text files containing a full json specification for the plugin.

Plugins with Unix domain socket files must run on the same host as the Docker daemon. Plugins with `.spec` or `.json` files can run on a different host if you specify a remote URL.

Unix domain socket files must be located under `/run/docker/plugins`, whereas spec files can be located either under `/etc/docker/plugins` or `/usr/lib/docker/plugins`.

The name of the file (excluding the extension) determines the plugin name.

For example, a plugin named `myplugin` might create a Unix socket at `/run/docker/plugins/myplugin.sock`.

You can define each plugin into a separated subdirectory if you want to isolate definitions from each other. For example, you can create the `myplugin` socket under `/run/docker/plugins/myplugin/myplugin.sock` and only mount `/run/docker/plugins/myplugin` inside the `myplugin` container.

Docker always searches for Unix sockets in `/run/docker/plugins` first. It checks for spec or json files under `/etc/docker/plugins` and `/usr/lib/docker/plugins` if the socket doesn't exist. The directory scan stops as soon as it finds the first plugin definition with the given name.

### [JSON specification](#json-specification)

This is the JSON format for a plugin:

```json
{
  "Name": "plugin-example",
  "Addr": "https://example.com/docker/plugin",
  "TLSConfig": {
    "InsecureSkipVerify": false,
    "CAFile": "/usr/shared/docker/certs/example-ca.pem",
    "CertFile": "/usr/shared/docker/certs/example-cert.pem",
    "KeyFile": "/usr/shared/docker/certs/example-key.pem"
  }
}
```

The `TLSConfig` field is optional and TLS will only be verified if this configuration is present.

## [Plugin lifecycle](#plugin-lifecycle)

Plugins should be started before Docker, and stopped after Docker. For example, when packaging a plugin for a platform which supports `systemd`, you might use [`systemd` dependencies](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Before=) to manage startup and shutdown order.

When upgrading a plugin, you should first stop the Docker daemon, upgrade the plugin, then start Docker again.

## [Plugin activation](#plugin-activation)

When a plugin is first referred to -- either by a user referring to it by name (e.g. `docker run --volume-driver=foo`) or a container already configured to use a plugin being started -- Docker looks for the named plugin in the plugin directory and activates it with a handshake. See Handshake API below.

Plugins are not activated automatically at Docker daemon startup. Rather, they are activated only lazily, or on-demand, when they are needed.

## [Systemd socket activation](#systemd-socket-activation)

Plugins may also be socket activated by `systemd`. The official [Plugins helpers](https://github.com/docker/go-plugins-helpers) natively supports socket activation. In order for a plugin to be socket activated it needs a `service` file and a `socket` file.

The `service` file (for example `/lib/systemd/system/your-plugin.service`):

```systemd
[Unit]
Description=Your plugin
Before=docker.service
After=network.target your-plugin.socket
Requires=your-plugin.socket docker.service

[Service]
ExecStart=/usr/lib/docker/your-plugin

[Install]
WantedBy=multi-user.target
```

The `socket` file (for example `/lib/systemd/system/your-plugin.socket`):

```systemd
[Unit]
Description=Your plugin

[Socket]
ListenStream=/run/docker/plugins/your-plugin.sock

[Install]
WantedBy=sockets.target
```

This will allow plugins to be actually started when the Docker daemon connects to the sockets they're listening on (for instance the first time the daemon uses them or if one of the plugin goes down accidentally).

## [API design](#api-design)

The Plugin API is RPC-style JSON over HTTP, much like webhooks.

Requests flow from the Docker daemon to the plugin. The plugin needs to implement an HTTP server and bind this to the Unix socket mentioned in the "plugin discovery" section.

All requests are HTTP `POST` requests.

The API is versioned via an Accept header, which currently is always set to `application/vnd.docker.plugins.v1+json`.

## [Handshake API](#handshake-api)

Plugins are activated via the following "handshake" API call.

### [/Plugin.Activate](#pluginactivate)

Request: empty body

Response:

```json
{
    "Implements": ["VolumeDriver"]
}
```

Responds with a list of Docker subsystems which this plugin implements. After activation, the plugin will then be sent events from this subsystem.

Possible values are:

* [`authz`](https://docs.docker.com/engine/extend/plugins_authorization/)
* [`NetworkDriver`](https://docs.docker.com/engine/extend/plugins_network/)
* [`VolumeDriver`](https://docs.docker.com/engine/extend/plugins_volume/)

## [Plugin retries](#plugin-retries)

Attempts to call a method on a plugin are retried with an exponential backoff for up to 30 seconds. This may help when packaging plugins as containers, since it gives plugin containers a chance to start up before failing any user containers which depend on them.

## [Plugins helpers](#plugins-helpers)

To ease plugins development, we're providing an `sdk` for each kind of plugins currently supported by Docker at [docker/go-plugins-helpers](https://github.com/docker/go-plugins-helpers).

----
url: https://docs.docker.com/reference/cli/docker/trust/signer/remove/
----

# docker trust signer remove

***

| Description | Remove a signer                                                        |
| ----------- | ---------------------------------------------------------------------- |
| Usage       | `docker trust signer remove [OPTIONS] NAME REPOSITORY [REPOSITORY...]` |

## [Description](#description)

`docker trust signer remove` removes signers from signed repositories.

## [Options](#options)

| Option        | Default | Description                                                            |
| ------------- | ------- | ---------------------------------------------------------------------- |
| `-f, --force` |         | Do not prompt for confirmation before removing the most recent signer  |

## [Examples](#examples)

### [Remove a signer from a repository](#remove-a-signer-from-a-repository)

To remove an existing signer, `alice`, from this repository:

```console
$ docker trust inspect --pretty example/trust-demo

No signatures for example/trust-demo


List of signers and their keys:

SIGNER              KEYS
alice               05e87edcaecb
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

Remove `alice` with `docker trust signer remove`:

```console
$ docker trust signer remove alice example/trust-demo

Removing signer "alice" from image example/trust-demo...
Enter passphrase for repository key with ID 642692c:
Successfully removed alice from example/trust-demo
```

`docker trust inspect --pretty` now doesn't list `alice` as a valid signer:

```console
$ docker trust inspect --pretty example/trust-demo

No signatures for example/trust-demo


List of signers and their keys:

SIGNER              KEYS
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

### [Remove a signer from multiple repositories](#remove-a-signer-from-multiple-repositories)

To remove an existing signer, `alice`, from multiple repositories:

```console
$ docker trust inspect --pretty example/trust-demo

SIGNED TAG          DIGEST                                                             SIGNERS
v1                  74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4   alice, bob

List of signers and their keys:

SIGNER              KEYS
alice               05e87edcaecb
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: 95b9e5514c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

```console
$ docker trust inspect --pretty example/trust-demo2

SIGNED TAG          DIGEST                                                             SIGNERS
v1                  74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4   alice, bob

List of signers and their keys:

SIGNER              KEYS
alice               05e87edcaecb
bob                 5600f5ab76a2

Administrative keys for example/trust-demo2:
Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d9268
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

Remove `alice` from both images with a single `docker trust signer remove` command:

```console
$ docker trust signer remove alice example/trust-demo example/trust-demo2

Removing signer "alice" from image example/trust-demo...
Enter passphrase for repository key with ID 95b9e55:
Successfully removed alice from example/trust-demo

Removing signer "alice" from image example/trust-demo2...
Enter passphrase for repository key with ID ece554f:
Successfully removed alice from example/trust-demo2
```

Run `docker trust inspect --pretty` to confirm that `alice` is no longer listed as a valid signer of either `example/trust-demo` or `example/trust-demo2`:

```console
$ docker trust inspect --pretty example/trust-demo

SIGNED TAG          DIGEST                                                             SIGNERS
v1                  74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4   bob

List of signers and their keys:

SIGNER              KEYS
bob                 5600f5ab76a2

Administrative keys for example/trust-demo:
Repository Key: ecc457614c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4555b3c6ab02f71e
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

```console
$ docker trust inspect --pretty example/trust-demo2

SIGNED TAG          DIGEST                                                             SIGNERS
v1                  74d4bfa917d55d53c7df3d2ab20a8d926874d61c3da5ef6de15dd2654fc467c4   bob

List of signers and their keys:

SIGNER              KEYS
bob                 5600f5ab76a2

Administrative keys for example/trust-demo2:
Repository Key: ece554f14c9fc399da523a5f4e24fe306a0a6ee1cc79a10e4553d2ab20a8d9268
Root Key:       3cb2228f6561e58f46dbc4cda4fcaff9d5ef22e865a94636f82450d1d2234949
```

`docker trust signer remove` removes signers to repositories on a best effort basis. It continues to remove the signer from subsequent repositories if one attempt fails:

```console
$ docker trust signer remove alice example/unauthorized example/authorized

Removing signer "alice" from image example/unauthorized...
No signer alice for image example/unauthorized

Removing signer "alice" from image example/authorized...
Enter passphrase for repository key with ID c6772a0:
Successfully removed alice from example/authorized

Error removing signer from: example/unauthorized
```

----
url: https://docs.docker.com/dhi/how-to/cli/
----

# Use the DHI CLI

***

Table of contents

***

The `docker dhi` command-line interface (CLI) is a tool for managing Docker Hardened Images:

* Browse the catalog of available DHI images and their metadata
* View attestations for DHI images, including SBOMs and provenance
* Mirror DHI images to your Docker Hub organization
* Create and manage customizations of DHI images
* Generate authentication for enterprise package repositories
* Monitor customization builds

## [Installation](#installation)

The `docker dhi` CLI is available in [Docker Desktop](https://docs.docker.com/desktop/) version 4.65 and later. You can also install the standalone `dhictl` binary.

### [Docker Desktop](#docker-desktop)

The `docker dhi` command is included in Docker Desktop 4.65 and later. No additional installation is required.

### [Standalone binary](#standalone-binary)

1. Download the `dhictl` binary for your platform from the [releases](https://github.com/docker-hardened-images/dhictl/releases) page.

2. Move it to a directory in your `PATH`:

   * `mv dhictl /usr/local/bin/` on *Linux* and *macOS*
   * Move `dhictl.exe` to a directory in your `PATH` on *Windows*

## [Usage](#usage)

Every command has built-in help accessible with the `--help` flag:

```console
$ docker dhi --help
$ docker dhi catalog list --help
```

### [Browse the DHI catalog](#browse-the-dhi-catalog)

List all available DHI images:

```console
$ docker dhi catalog list
```

Filter by type, name, or compliance:

```console
$ docker dhi catalog list --type image
$ docker dhi catalog list --filter golang
$ docker dhi catalog list --fips
$ docker dhi catalog list --stig
```

Get details of a specific image, including available tags and CVE counts:

```console
$ docker dhi catalog get <image-name>
```

### [View attestations](#view-attestations)

List all attestations attached to a DHI image:

```console
$ docker dhi attestation list dhi/nginx:1.27
$ docker dhi attestation list dhi/nginx:1.27 --platform linux/amd64
$ docker dhi attestation list dhi/nginx:1.27 --predicate-type https://slsa.dev/provenance/v1
$ docker dhi attestation list dhi/nginx:1.27 --json
```

Get a specific attestation by its referrer digest:

```console
$ docker dhi attestation get dhi/nginx:1.27 sha256:<digest>
$ docker dhi attestation get dhi/nginx:1.27 sha256:<digest> -o provenance.json
```

Display the SPDX SBOM for an image:

```console
$ docker dhi attestation sbom dhi/nginx:1.27
$ docker dhi attestation sbom dhi/nginx:1.27 --platform linux/amd64
```

### [Mirror DHI images](#mirror-dhi-images)

Subscription: Docker Hardened Images Select or Enterprise

Start mirroring one or more DHI images to your Docker Hub organization:

```console
$ docker dhi mirror start --org my-org \
  dhi/golang,my-org/dhi-golang \
  dhi/nginx,my-org/dhi-nginx \
  dhi/prometheus-chart,my-org/dhi-prometheus-chart
```

Mirror with dependencies:

```console
$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --dependencies
```

List mirrored images in your organization:

```console
$ docker dhi mirror list --org my-org
```

Filter mirrored images by name or type:

```console
$ docker dhi mirror list --org my-org --filter python
$ docker dhi mirror list --org my-org --type image
$ docker dhi mirror list --org my-org --type helm-chart
```

Stop mirroring one or more images:

```console
$ docker dhi mirror stop dhi-golang --org my-org
$ docker dhi mirror stop dhi-python dhi-golang --org my-org
```

Stop mirroring and delete the repositories:

```console
$ docker dhi mirror stop dhi-golang --org my-org --delete
$ docker dhi mirror stop dhi-golang --org my-org --delete --force
```

### [Customize DHI images](#customize-dhi-images)

Subscription: Docker Hardened Images Select or Enterprise

The CLI can be used to create and manage DHI image customizations. For detailed instructions on creating customizations using the GUI, see [Customize a Docker Hardened Image](https://docs.docker.com/dhi/how-to/customize/).

The following is a quick reference for CLI commands. For complete details on all options and flags, see the [CLI reference](/reference/cli/docker/dhi/).

```console
# Prepare a single customization scaffold
$ docker dhi customization prepare golang 1.25 \
  --org my-org \
  --destination my-org/dhi-golang \
  --name "golang with git" \
  > my-customization.yaml

# Prepare a bulk customization scaffold (pipe JSON array via stdin)
$ echo '[{"destination":"my-org/dhi-golang","tag-definition-id":"golang/alpine-3.23/1.24-dev"}]' \
  | docker dhi customization prepare --name "golang with git" --org my-org \
  > my-customization.yaml

# Create a customization
$ docker dhi customization create my-customization.yaml --org my-org

# Create with flag overrides (flags take precedence over the YAML file)
$ docker dhi customization create my-customization.yaml --org my-org \
  --destination my-org/dhi-golang \
  --name "golang with git"

# List customizations
$ docker dhi customization list --org my-org

# Filter customizations by name, repository, or source
$ docker dhi customization list --org my-org --filter git
$ docker dhi customization list --org my-org --repo dhi-golang
$ docker dhi customization list --org my-org --source golang

# Get a customization by ID
$ docker dhi customization get <id> --org my-org

# Update a customization
# The YAML file must include the 'id' field to identify the customization to update
$ docker dhi customization edit my-customization.yaml --org my-org

# Delete a customization by ID
$ docker dhi customization delete <id> --org my-org

# Delete multiple customizations
$ docker dhi customization delete <id1> <id2> --org my-org

# Delete without confirmation prompt
$ docker dhi customization delete <id> --org my-org --force
```

For a complete reference of all YAML fields, see [Image customization YAML file](/dhi/how-to/customize/#image-customization-yaml-file).

### [Enterprise package authentication](#enterprise-package-authentication)

Subscription: Docker Hardened Images Enterprise

Generate authentication credentials for accessing the enterprise hardened package repository. These credentials are used when configuring your package manager to install compliance and security-patched packages in your own images. For detailed instructions, see [Enterprise repository](https://docs.docker.com/dhi/how-to/hardened-packages/#enterprise-repository).

For Alpine-based images:

```console
$ docker dhi auth apk
```

For Debian-based images:

```console
$ docker dhi auth deb
```

### [Monitor customization builds](#monitor-customization-builds)

Subscription: Docker Hardened Images Select or Enterprise

List builds for a customization:

```console
$ docker dhi customization build list <customization-id> --org my-org
$ docker dhi customization build list <customization-id> --org my-org --json
```

Get details of a specific build:

```console
$ docker dhi customization build get <customization-id> <build-id> --org my-org
$ docker dhi customization build get <customization-id> <build-id> --org my-org --json
```

View build logs:

```console
$ docker dhi customization build logs <customization-id> <build-id> --org my-org
$ docker dhi customization build logs <customization-id> <build-id> --org my-org --json
```

### [JSON output](#json-output)

Most list and get commands support a `--json` flag for machine-readable output:

```console
$ docker dhi catalog list --json
$ docker dhi catalog get golang --json
$ docker dhi attestation list dhi/nginx:1.27 --json
$ docker dhi mirror list --org my-org --json
$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --json
$ docker dhi customization list --org my-org --json
$ docker dhi customization build list <customization-id> --org my-org --json
```

## [Configuration](#configuration)

The `docker dhi` CLI can be configured with a YAML file located at:

* `$HOME/.config/dhictl/config.yaml` on *Linux* and *macOS*
* `%USERPROFILE%\.config\dhictl\config.yaml` on *Windows*

If `$XDG_CONFIG_HOME` is set, the configuration file is located at `$XDG_CONFIG_HOME/dhictl/config.yaml` (see the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/spec/latest/)).

Available configuration options:

| Option      | Environment Variable | Description                                                                                                               |
| ----------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `org`       | `DHI_ORG`            | Default Docker Hub organization for mirror and customization commands.                                                    |
| `api_token` | `DHI_API_TOKEN`      | Docker token for authentication. You can generate a token in your [Docker Hub account settings](https://hub.docker.com/). |

Environment variables take precedence over configuration file values.

----
url: https://docs.docker.com/reference/cli/docker/desktop/
----

# docker desktop

***

| Description | Docker Desktop   |
| ----------- | ---------------- |
| Usage       | `docker desktop` |

## [Description](#description)

Control Docker Desktop from the CLI

## [Subcommands](#subcommands)

| Command                                                                                         | Description                                            |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [`docker desktop diagnose`](https://docs.docker.com/reference/cli/docker/desktop/diagnose/)     | Diagnose Docker Desktop issues                         |
| [`docker desktop disable`](https://docs.docker.com/reference/cli/docker/desktop/disable/)       | Disable a feature                                      |
| [`docker desktop enable`](https://docs.docker.com/reference/cli/docker/desktop/enable/)         | Enable a feature                                       |
| [`docker desktop engine`](https://docs.docker.com/reference/cli/docker/desktop/engine/)         | Commands to list and switch containers (Windows only)  |
| [`docker desktop kubernetes`](https://docs.docker.com/reference/cli/docker/desktop/kubernetes/) | Manage Kubernetes settings                             |
| [`docker desktop logs`](https://docs.docker.com/reference/cli/docker/desktop/logs/)             | Print log entries for Docker Desktop                   |
| [`docker desktop restart`](https://docs.docker.com/reference/cli/docker/desktop/restart/)       | Restart Docker Desktop                                 |
| [`docker desktop start`](https://docs.docker.com/reference/cli/docker/desktop/start/)           | Start Docker Desktop                                   |
| [`docker desktop status`](https://docs.docker.com/reference/cli/docker/desktop/status/)         | Display Docker Desktop's status                        |
| [`docker desktop stop`](https://docs.docker.com/reference/cli/docker/desktop/stop/)             | Stop Docker Desktop                                    |
| [`docker desktop update`](https://docs.docker.com/reference/cli/docker/desktop/update/)         | Manage Docker Desktop updates                          |
| [`docker desktop version`](https://docs.docker.com/reference/cli/docker/desktop/version/)       | Show the Docker Desktop CLI plugin version information |

----
url: https://docs.docker.com/reference/cli/docker/volume/update/
----

# docker volume update

***

| Description | Update a volume (cluster volumes only)    |
| ----------- | ----------------------------------------- |
| Usage       | `docker volume update [OPTIONS] [VOLUME]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Update a volume (cluster volumes only)

## [Options](#options)

| Option           | Default  | Description                                                              |
| ---------------- | -------- | ------------------------------------------------------------------------ |
| `--availability` | `active` | API 1.42+ Swarm Cluster Volume availability (`active`, `pause`, `drain`) |

----
url: https://docs.docker.com/ai/sandboxes/agents/shell/
----

# Shell

***

Table of contents

***

`sbx run shell` drops you into a Bash login shell inside a sandbox with no pre-installed agent binary. It's useful for installing and configuring agents manually, testing custom implementations, or inspecting a running environment.

```console
$ sbx run shell ~/my-project
```

The workspace path defaults to the current directory. To run a one-off command instead of an interactive shell, pass it after `--`:

```console
$ sbx run shell -- -c "echo 'Hello from sandbox'"
```

### [Default startup command](#default-startup-command)

Without extra args, the sandbox runs `bash -l`. Args after `--` replace `-l` rather than being appended. To preserve login-shell behavior, include `-l` yourself:

```console
$ sbx run shell -- -l -c "echo hi"
```

Set your API keys as environment variables so the sandbox proxy can inject them into API requests automatically. Credentials are never stored inside the VM:

```console
$ export ANTHROPIC_API_KEY=sk-ant-xxxxx
$ export OPENAI_API_KEY=sk-xxxxx
```

Once inside the shell, you can install agents using their standard methods, for example `npm install -g @continuedev/cli`. For complex setups, build a [custom template](https://docs.docker.com/ai/sandboxes/customize/templates/) instead of installing interactively each time.

## [Base image](#base-image)

The shell sandbox uses the `shell` base image — the common base environment without a pre-installed agent.

----
url: https://docs.docker.com/enterprise/enterprise-deployment/msi-install-and-configure/
----

# MSI installer

***

Table of contents

***

Subscription: Business

For: Administrators

The MSI package supports various MDM (Mobile Device Management) solutions, making it ideal for bulk installations and eliminating the need for manual setups by individual users. With this package, IT administrators can ensure standardized, policy-driven installations of Docker Desktop, enhancing efficiency and software management across their organizations.

## [Install interactively](#install-interactively)

1. In [Docker Home](http://app.docker.com), choose your organization.

2. Select **Admin Console**, then **Enterprise deployment**.

3. From the **Windows OS** tab, select the **Download MSI installer** button.

4. Once downloaded, double-click `Docker Desktop Installer.msi` to run the installer.

5. After accepting the license agreement, choose the install location. By default, Docker Desktop is installed at `C:\Program Files\Docker\Docker`(all-user installations) or `%LOCALAPPDATA%\Programs\DockerDesktop` (per-user installations)

6. Configure the Docker Desktop installation. You can:

   * Create a desktop shortcut

   * Set the Docker Desktop service startup type to automatic

   * Disable Windows Container usage

   * Select the Docker Desktop backend: WSL or Hyper-V. If only one is supported by your system, you won't be able to choose.

7. Follow the instructions on the installation wizard to authorize the installer and proceed with the install.

8. When the installation is successful, select **Finish** to complete the installation process.

If your administrator account is different from your user account, you must add the user to the **docker-users** group to access features that require higher privileges, such as creating and managing the Hyper-V VM, or using Windows containers:

1. Run **Computer Management** as an **administrator**.
2. Navigate to **Local Users and Groups** > **Groups** > **docker-users**.
3. Right-click to add the user to the group.
4. Sign out and sign back in for the changes to take effect.

> Note
>
> When installing Docker Desktop with the MSI, in-app updates are automatically disabled by default. This ensures organizations can maintain version consistency and prevent unapproved updates. Starting with Docker Desktop version 4.60 and later, in-app updates from an MSI installation can be enabled by changing the `disableUpdate` setting to `false` through [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/).
>
> Docker Desktop notifies you when an update is available. To update Docker Desktop, download the latest installer from the Docker Admin Console. Navigate to the **Enterprise deployment** page.
>
> To keep up to date with new releases, check the [release notes](https://docs.docker.com/desktop/release-notes/) page.

## [Install from the command line](#install-from-the-command-line)

This section covers command line installations of Docker Desktop using PowerShell. It provides common installation commands that you can run. You can also add additional arguments which are outlined in [configuration options](#configuration-options).

When installing Docker Desktop, you can choose between interactive or non-interactive installations.

Interactive installations, without specifying `/quiet` or `/qn`, display the user interface and let you select your own properties.

When installing via the user interface it's possible to:

* Choose the destination folder
* Create a desktop shortcut
* Configure the Docker Desktop service startup type
* Disable Windows Containers
* Choose between the WSL or Hyper-V engine

Non-interactive installations are silent and any additional configuration must be passed as arguments.

### [Common installation commands](#common-installation-commands)

Admin rights are required to run any of the following commands.

#### [Install interactively with verbose logging](#install-interactively-with-verbose-logging)

```powershell
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log"
```

#### [Install interactively without verbose logging](#install-interactively-without-verbose-logging)

```powershell
msiexec /i "DockerDesktop.msi"
```

#### [Install non-interactively with verbose logging](#install-non-interactively-with-verbose-logging)

```powershell
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet
```

#### [Install non-interactively and suppressing reboots](#install-non-interactively-and-suppressing-reboots)

```powershell
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart
```

#### [Install non-interactively with admin settings](#install-non-interactively-with-admin-settings)

```powershell
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart ADMINSETTINGS="{""configurationFileVersion"":2,""enhancedContainerIsolation"":{""value"":true,""locked"":false}}" ALLOWEDORG="your-organization"
```

#### [Install interactively and allow users to switch to Windows containers without admin rights](#install-interactively-and-allow-users-to-switch-to-windows-containers-without-admin-rights)

```powershell
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /quiet /norestart ALLOWEDORG="your-organization" ALWAYSRUNSERVICE=1
```

#### [Install interactively specifying a PAC file](#install-interactively-specifying-a-pac-file)

```powershell
PowerShell
 msiexec --% /i "DockerDesktop.msi" /L*V ".\msi.log"  PROXYHTTPMODE="manual" OVERRIDEPROXYPAC="http://localhost:8080/myproxy.pac"
```

#### [Install interactively specifying a PAC script](#install-interactively-specifying-a-pac-script)

```powershell
PowerShell
 msiexec --% /i "DockerDesktop.msi" /L*V ".\msi.log"  PROXYHTTPMODE="manual" OVERRIDEPROXYEMBEDDEDPAC="function FindProxyForURL(url,host) {return ""DIRECT"" ;; }"
```

#### [Install with the passive display option](#install-with-the-passive-display-option)

You can use the `/passive` display option instead of `/quiet` when you want to perform a non-interactive installation but show a progress dialog.

In passive mode the installer doesn't display any prompts or error messages to the user and the installation cannot be cancelled.

For example:

```powershell
msiexec /i "DockerDesktop.msi" /L*V ".\msi.log" /passive /norestart
```

> Tip
>
> When creating a value that expects a JSON string:
>
> * The property expects a JSON formatted string
> * The string should be wrapped in double quotes
> * The string shouldn't contain any whitespace
> * Property names are expected to be in double quotes

### [Common uninstall commands](#common-uninstall-commands)

When uninstalling Docker Desktop, you need to use the same `.msi` file that was originally used to install the application.

If you no longer have the original `.msi` file, you need to use the product code associated with the installation. To find the product code, run:

```powershell
Get-WmiObject Win32_Product | Select-Object IdentifyingNumber, Name | Where-Object {$_.Name -eq "Docker Desktop"}
```

It should return output similar to the following:

```text
IdentifyingNumber                      Name
-----------------                      ----
{10FC87E2-9145-4D7D-B493-2E99E8D8E103} Docker Desktop
```

> Note
>
> This command may take some time, depending on the number of installed applications.

`IdentifyingNumber` is the applications product code and can be used to uninstall Docker Desktop. For example:

```powershell
msiexec /x {10FC87E2-9145-4D7D-B493-2E99E8D8E103} /L*V ".\msi.log" /quiet
```

#### [Uninstall interactively with verbose logging](#uninstall-interactively-with-verbose-logging)

```powershell
msiexec /x "DockerDesktop.msi" /L*V ".\msi.log"
```

#### [Uninstall interactively without verbose logging](#uninstall-interactively-without-verbose-logging)

```powershell
msiexec /x "DockerDesktop.msi"
```

#### [Uninstall non-interactively with verbose logging](#uninstall-non-interactively-with-verbose-logging)

```powershell
msiexec /x "DockerDesktop.msi" /L*V ".\msi.log" /quiet
```

#### [Uninstall non-interactively without verbose logging](#uninstall-non-interactively-without-verbose-logging)

```powershell
msiexec /x "DockerDesktop.msi" /quiet
```

### [Configuration options](#configuration-options)

In addition to the following custom properties, the Docker Desktop MSI installer also supports the standard [Windows Installer command line options](https://learn.microsoft.com/en-us/windows/win32/msi/standard-installer-command-line-options).

| Property                           | Description                                                                                                                                                                                                                                                                                         | Default                 |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `ENABLEDESKTOPSHORTCUT`            | Creates a desktop shortcut.                                                                                                                                                                                                                                                                         | 1                       |
| `INSTALLFOLDER`                    | Specifies a custom location where Docker Desktop will be installed.                                                                                                                                                                                                                                 | C:\Program Files\Docker |
| `ADMINSETTINGS`                    | Automatically creates an `admin-settings.json` file which is used to [control certain Docker Desktop settings](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) on client machines within organizations. It must be used together with the `ALLOWEDORG` property. | None                    |
| `ALLOWEDORG`                       | Requires the user to sign in and be part of the specified Docker Hub organization when running the application. This creates a registry key called `allowedOrgs` in `HKLM\Software\Policies\Docker\Docker Desktop`.                                                                                 | None                    |
| `ALWAYSRUNSERVICE`                 | Lets users switch to Windows containers without needing admin rights                                                                                                                                                                                                                                | 0                       |
| `DISABLEWINDOWSCONTAINERS`         | Disables the Windows containers integration                                                                                                                                                                                                                                                         | 0                       |
| `ENGINE`                           | Sets the Docker Engine that's used to run containers. This can be either `wsl` , `hyperv`, or `windows`                                                                                                                                                                                             | `wsl`                   |
| `PROXYENABLEKERBEROSNTLM`          | When set to 1, enables support for Kerberos and NTLM proxy authentication.                                                                                                                                                                                                                          | 0                       |
| `PROXYHTTPMODE`                    | Sets the HTTP Proxy mode. This can be either `system` or `manual`                                                                                                                                                                                                                                   | `system`                |
| `OVERRIDEPROXYHTTP`                | Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests.                                                                                                                                                                                                                        | None                    |
| `OVERRIDEPROXYHTTPS`               | Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests.                                                                                                                                                                                                                       | None                    |
| `OVERRIDEPROXYEXCLUDE`             | Bypasses proxy settings for the hosts and domains. Uses a comma-separated list.                                                                                                                                                                                                                     | None                    |
| `OVERRIDEPROXYPAC`                 | Sets the PAC file URL. This setting takes effect only when using `manual` proxy mode.                                                                                                                                                                                                               | None                    |
| `OVERRIDEPROXYEMBEDDEDPAC`         | Specifies an embedded PAC (Proxy Auto-config) script. This setting takes effect only when using `manual` proxy mode and has precedence over the `OVERRIDEPROXYPAC` flag.                                                                                                                            | None                    |
| `HYPERVDEFAULTDATAROOT`            | Specifies the default location for the Hyper-V VM disk.                                                                                                                                                                                                                                             | None                    |
| `WINDOWSCONTAINERSDEFAULTDATAROOT` | Specifies the default location for Windows containers.                                                                                                                                                                                                                                              | None                    |
| `WSLDEFAULTDATAROOT`               | Specifies the default location for the WSL distribution disk.                                                                                                                                                                                                                                       | None                    |
| `DISABLEANALYTICS`                 | When set to 1, analytics collection will be disabled for the MSI. For more information, see [Analytics](#analytics).                                                                                                                                                                                | 0                       |
| `REMOVEEXISTINGINSTALL`            | When set to 1, any existing EXE installations are removed. Existing settings and content are preserved. Available with Docker Desktop version 4.61 and later.                                                                                                                                       | 1                       |

Additionally, you can also use `/norestart` or `/forcerestart` to control reboot behaviour.

By default, the installer reboots the machine after a successful installation. When run silently, the reboot is automatic and the user is not prompted.

## [Analytics](#analytics)

The MSI installer collects anonymous usage statistics relating to installation only. This is to better understand user behaviour and to improve the user experience by identifying and addressing issues or optimizing popular features.

### [How to opt-out](#how-to-opt-out)

When you install Docker Desktop from the default installer GUI, select the **Disable analytics** checkbox located on the bottom-left corner of the **Welcome** dialog.

When you install Docker Desktop from the command line, use the `DISABLEANALYTICS` property.

```powershell
msiexec /i "win\msi\bin\en-US\DockerDesktop.msi" /L*V ".\msi.log" DISABLEANALYTICS=1
```

### [Persistence](#persistence)

If you decide to disable analytics for an installation, your choice is persisted in the registry and honoured across future upgrades and uninstalls.

However, the key is removed when Docker Desktop is uninstalled and must be configured again via one of the previous methods.

The registry key is as follows:

```powershell
SOFTWARE\Docker Inc.\Docker Desktop\DisableMsiAnalytics
```

When analytics is disabled, this key is set to `1`.

## [Additional resources](#additional-resources)

* [Explore the FAQs](https://docs.docker.com/enterprise/enterprise-deployment/faq/)

----
url: https://docs.docker.com/reference/cli/docker/desktop/kubernetes/
----

# docker desktop kubernetes

***

| Description | Manage Kubernetes settings  |
| ----------- | --------------------------- |
| Usage       | `docker desktop kubernetes` |

## [Subcommands](#subcommands)

| Command                                                                                                       | Description                                   |
| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| [`docker desktop kubernetes images`](https://docs.docker.com/reference/cli/docker/desktop/kubernetes/images/) | List Kubernetes images used by Docker Desktop |

----
url: https://docs.docker.com/build/cache/backends/
----

# Cache storage backends

***

Table of contents

***

To ensure fast builds, BuildKit automatically caches the build result in its own internal cache. Additionally, BuildKit also supports exporting build cache to an external location, making it possible to import in future builds.

An external cache becomes almost essential in CI/CD build environments. Such environments usually have little-to-no persistence between runs, but it's still important to keep the runtime of image builds as low as possible.

The default `docker` driver supports the `inline`, `local`, `registry`, and `gha` cache backends, but only if you have enabled the [containerd image store](https://docs.docker.com/desktop/features/containerd/). Other cache backends require you to select a different [driver](https://docs.docker.com/build/builders/drivers/).

> Warning
>
> If you use secrets or credentials inside your build process, ensure you manipulate them using the dedicated [`--secret` option](/reference/cli/docker/buildx/build/#secret). Manually managing secrets using `COPY` or `ARG` could result in leaked credentials.

## [Backends](#backends)

Buildx supports the following cache storage backends:

* `inline`: embeds the build cache into the image.

  The inline cache gets pushed to the same location as the main output result. This only works with the [`image` exporter](https://docs.docker.com/build/exporters/image-registry/).

* `registry`: embeds the build cache into a separate image, and pushes to a dedicated location separate from the main output.

* `local`: writes the build cache to a local directory on the filesystem.

* `gha`: uploads the build cache to [GitHub Actions cache](https://docs.github.com/en/rest/actions/cache) (beta).

* `s3`: uploads the build cache to an [AWS S3 bucket](https://aws.amazon.com/s3/) (unreleased).

* `azblob`: uploads the build cache to [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/) (unreleased).

## [Command syntax](#command-syntax)

To use any of the cache backends, you first need to specify it on build with the [`--cache-to` option](/reference/cli/docker/buildx/build/#cache-to) to export the cache to your storage backend of choice. Then, use the [`--cache-from` option](/reference/cli/docker/buildx/build/#cache-from) to import the cache from the storage backend into the current build. Unlike the local BuildKit cache (which is always enabled), all of the cache storage backends must be explicitly exported to, and explicitly imported from.

Example `buildx` command using the `registry` backend, using import and export cache:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>[,parameters...] \
  --cache-from type=registry,ref=<registry>/<cache-image>[,parameters...] .
```

> Warning
>
> As a general rule, each cache writes to some location. No location can be written to twice, without overwriting the previously cached data. If you want to maintain multiple scoped caches (for example, a cache per Git branch), then ensure that you use different locations for exported cache.

## [Multiple caches](#multiple-caches)

BuildKit supports multiple cache exporters, allowing you to push cache to more than one destination. You can also import from as many remote caches as you'd like. For example, a common pattern is to use the cache of both the current branch and the main branch. The following example shows importing cache from multiple locations using the registry cache backend:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>:<branch> \
  --cache-from type=registry,ref=<registry>/<cache-image>:<branch> \
  --cache-from type=registry,ref=<registry>/<cache-image>:main .
```

## [Configuration options](#configuration-options)

This section describes some configuration options available when generating cache exports. The options described here are common for at least two or more backend types. Additionally, the different backend types support specific parameters as well. See the detailed page about each backend type for more information about which configuration parameters apply.

The common parameters described here are:

* [Cache mode](#cache-mode)
* [Cache compression](#cache-compression)
* [OCI media type](#oci-media-types)

### [Cache mode](#cache-mode)

When generating a cache output, the `--cache-to` argument accepts a `mode` option for defining which layers to include in the exported cache. This is supported by all cache backends except for the `inline` cache.

Mode can be set to either of two options: `mode=min` or `mode=max`. For example, to build the cache with `mode=max` with the registry backend:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,mode=max \
  --cache-from type=registry,ref=<registry>/<cache-image> .
```

This option is only set when exporting a cache, using `--cache-to`. When importing a cache (`--cache-from`) the relevant parameters are automatically detected.

In `min` cache mode (the default), only layers that are exported into the resulting image are cached, while in `max` cache mode, all layers are cached, even those of intermediate steps.

While `min` cache is typically smaller (which speeds up import/export times, and reduces storage costs), `max` cache is more likely to get more cache hits. Depending on the complexity and location of your build, you should experiment with both parameters to find the results that work best for you.

### [Cache compression](#cache-compression)

The cache compression options are the same as the [exporter compression options](https://docs.docker.com/build/exporters/#compression). This is supported by the `local` and `registry` cache backends.

For example, to compress the `registry` cache with `zstd` compression:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,compression=zstd \
  --cache-from type=registry,ref=<registry>/<cache-image> .
```

### [OCI media types](#oci-media-types)

The cache OCI options are the same as the [exporter OCI options](https://docs.docker.com/build/exporters/#oci-media-types). These are supported by the `local` and `registry` cache backends.

For example, to export OCI media type cache, use the `oci-mediatypes` property:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true \
  --cache-from type=registry,ref=<registry>/<cache-image> .
```

This property is only meaningful with the `--cache-to` flag. When fetching cache, BuildKit will auto-detect the correct media types to use.

By default, the OCI media type generates an image index for the cache image. Some OCI registries, such as Amazon ECR, don't support the image index media type: `application/vnd.oci.image.index.v1+json`. If you export cache images to ECR, or any other registry that doesn't support image indices, set the `image-manifest` parameter to `true` to generate a single image manifest instead of an image index for the cache image:

```console
$ docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,oci-mediatypes=true,image-manifest=true \
  --cache-from type=registry,ref=<registry>/<cache-image> .
```

> Note
>
> Since BuildKit v0.21, `image-manifest` is enabled by default.

----
url: https://docs.docker.com/scout/
----

# Docker Scout

***

***

Container images consist of layers and software packages, which are susceptible to vulnerabilities. These vulnerabilities can compromise the security of containers and applications.

Docker Scout is a solution for proactively enhancing your software supply chain security. By analyzing your images, Docker Scout compiles an inventory of components, also known as a Software Bill of Materials (SBOM). The SBOM is matched against a continuously updated vulnerability database to pinpoint security weaknesses.

Docker Scout is a standalone service and platform that you can interact with using Docker Hub, the Docker CLI, and the Docker Scout Dashboard. Docker Scout also facilitates integrations with third-party systems, such as container registries and CI platforms.

### [Quickstart](/scout/quickstart/)

[Learn what Docker Scout can do, and how to get started.](/scout/quickstart/)

### [Image analysis](/scout/image-analysis/)

[Reveal and dig into the composition of your images.](/scout/image-analysis/)

### [Advisory database](/scout/advisory-db-sources/)

[Learn about the information sources that Docker Scout uses.](/scout/advisory-db-sources/)

### [Integrations](/scout/integrations/)

[Connect Docker Scout with your CI, registries, and other third-party services.](/scout/integrations/)

### [Dashboard](/scout/dashboard/)

[The web interface for Docker Scout.](/scout/dashboard/)

### [Policy](/scout/policy/)

[Ensure that your artifacts align with supply chain best practices.](/scout/policy/)

### [Upgrade](/subscription/change/)

[A Personal subscription includes up to 1 repository. Upgrade for more.](/subscription/change/)

----
url: https://docs.docker.com/desktop/features/synchronized-file-sharing/
----

# Synchronized file shares

***

Table of contents

***

Subscription: Pro Team Business

Synchronized file shares is an alternative file sharing mechanism that provides fast and flexible host-to-VM file sharing, enhancing bind mount performance through the use of synchronized filesystem caches.

## [Who is it for?](#who-is-it-for)

Synchronized file shares is ideal for developers who:

* Have large repositories or monorepos with 100 000 files or more totaling hundreds of megabytes or even gigabytes.
* Are using virtual filesystems, such as VirtioFS, gRPC FUSE, and osxfs, which are no longer scaling well with their codebases.
* Regularly encounter performance limitations.
* Don't want to worry about file ownership or spend time resolving conflicting file-ownership information when modifying multiple containers.

## [How does Synchronized file shares work?](#how-does-synchronized-file-shares-work)

A Synchronized file share behaves just like a virtual file share, but takes advantage of a high-performance, low-latency code synchronization engine to create a synchronized cache of the host files on an ext4 filesystem within the Docker Desktop VM. If you make filesystem changes on the host or in the VM’s containers, it propagates via bidirectional synchronization.

After creating a file share instance, any container using a bind mount that points to a location on the host filesystem matching the specified synchronized file share location, or a subdirectory within it, utilizes the Synchronized File Shares feature. Bind mounts that don't satisfy this condition are passed to the normal virtual filesystem [bind-mounting mechanism](https://docs.docker.com/engine/storage/bind-mounts/), for example VirtioFS or gRPC-FUSE.

> Note
>
> Synchronized file shares is not used by Kubernetes' `hostPath` volumes in Docker Desktop.

> Important
>
> Synchronized file shares isn't available on WSL or when using Windows containers.

## [Create a file share instance](#create-a-file-share-instance)

To create a file share instance:

1. Sign in to Docker Desktop.
2. In **Settings**, navigate to the **File sharing** tab within the **Resources** section.
3. In the **Synchronized file shares** section, select **Create share**.
4. Select a host folder to share. The synchronized file share should initialize and be usable.

File shares take a few seconds to initialize as files are copied into the Docker Desktop VM. During this time, the status indicator displays **Preparing**. There is also a status icon in the footer of the Docker Desktop Dashboard that keeps you updated.

When the status indicator displays **Watching for filesystem changes**, your files are available to the VM through all the standard bind mount mechanisms, whether that's `-v` in the command line or specified in your `compose.yml` file.

> Note
>
> When you create a new service, setting the [bind mount option consistency](/reference/cli/docker/service/create/#options-for-bind-mounts) to `:consistent` bypasses Synchronized file shares.

## [Explore your file share instance](#explore-your-file-share-instance)

The **Synchronized file shares** section displays all your file share instances and provides useful information about each instance including:

* The origin of the file share content
* A status update
* How much space each file share is using
* The number of filesystem entry counts
* The number of symbolic links
* Which container(s) is using the file share instance

Selecting a file share instance expands the dropdown and exposes this information.

## [Use `.syncignore`](#use-syncignore)

You can use a `.syncignore` file at the root of each file share, to exclude local files from your file share instance. It supports the same syntax as `.dockerignore` files and excludes, and/or re-includes, paths from synchronization. `.syncignore` files are ignored at any location other than the root of the file share.

Some example of things you might want to add to your `.syncignore` file are:

* Large dependency directories, for example `node_modules` and `composer` directories (unless you rely on accessing them via a bind mount)
* `.git` directories (again, unless you need them)

In general, use your `.syncignore` file to exclude items that aren't critical to your workflow, especially those that would be slow to sync or use significant storage.

## [Known issues](#known-issues)

* Changes made to `.syncignore` don't lead to immediate deletions unless the file share is recreated. In other words, files that are newly ignored due to modifications in the `.syncignore` file remain in their current location, but are no longer updated during synchronization.

* File share instances are limited to approximately 2 million files per share. For best performance, if you have a file share instance of this size, try to decompose it into multiple shares corresponding to individual bind mount locations.

* Case conflicts, due to Linux being case-sensitive and macOS/Windows only being case-preserving, display as **File exists** problems in the GUI. These can be ignored. However, if they persist, you can report the issue.

* Synchronized file shares proactively reports temporary issues, which can result in occasional **Conflict** and **Problem** indicators appearing in the GUI during synchronization. These can be ignored. However, if they persist, you can report the issue.

* If you switch from WSL2 to Hyper-V on Windows, Docker Desktop needs to be fully restarted.

* POSIX-style Windows paths are not supported. Avoid setting the [`COMPOSE_CONVERT_WINDOWS_PATHS`](https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_convert_windows_paths) environment variable in Docker Compose.

* If you don't have the correct permissions to create symbolic links and your container attempts to create symbolic links in your file share instance, an **unable to create symbolic link** error message displays. For Windows users, see Microsoft's [Create symbolic links documentation](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-10/security/threat-protection/security-policy-settings/create-symbolic-links) for best practices and location of the **Create symbolic links** security policy setting. For Mac and Linux users, check that you have write permissions on the folder.

----
url: https://docs.docker.com/build/release-notes/
----

[Skip to content](#start-of-content)

You signed in with another tab or window. [Reload]() to refresh your session. You signed out in another tab or window. [Reload]() to refresh your session. You switched accounts on another tab or window. [Reload]() to refresh your session. Dismiss alert

[docker ](/docker)/ **[buildx](/docker/buildx)&#x20;**&#x50;ublic

* [Notifications ](/login?return_to=%2Fdocker%2Fbuildx)You must be signed in to change notification settings
* [Fork 642](/login?return_to=%2Fdocker%2Fbuildx)
* [Star 4.4k](/login?return_to=%2Fdocker%2Fbuildx)

# Releases: docker/buildx

Releases · docker/buildx

## v0.34.1

19 May 18:39

[github-actions](/apps/github-actions)

[v0.34.1](/docker/buildx/tree/v0.34.1)

This tag was signed with the committer’s **verified signature**. The key has expired.

[](/tonistiigi)[tonistiigi](/tonistiigi) Tõnis Tiigi

GPG key ID: AFA9DE5F8AB7AF39

Expired

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`e0b0e77`](/docker/buildx/commit/e0b0e77d18d3379bc1e0d55f3b37de288d36fe47)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.34.1](/docker/buildx/releases/tag/v0.34.1) [Latest](/docker/buildx/releases/latest)

[Latest](/docker/buildx/releases/latest)

buildx 0.34.1

Welcome to the v0.34.1 release of buildx!

Please try out the release binaries and report any issues at\
<https://github.com/docker/buildx/issues>.

### Contributors

* CrazyMax
* Jonathan A. Sternberg
* Tõnis Tiigi

### Notable Changes

* Fix regression in Bake command when building from Compose files with empty array value [#3849](https://github.com/docker/buildx/issues/3849) [#3852](https://github.com/docker/buildx/pull/3852)
* Fix possible panic in Kubernetes driver when using statefulset [#3853](https://github.com/docker/buildx/pull/3853)

### Dependency Changes

This release has no dependency changes

Previous release can be found at [v0.34.0](https://github.com/docker/buildx/releases/tag/v0.34.0)

Assets 69

* [buildx-v0.34.1.darwin-amd64](/docker/buildx/releases/download/v0.34.1/buildx-v0.34.1.darwin-amd64)

  sha256:a4a74ff86e70706a0ae24330052ab52989da9f2090dc8fc478e398813de7b550

  64.1 MB 2026-05-19T18:37:46Z

* [buildx-v0.34.1.darwin-amd64.provenance.json](/docker/buildx/releases/download/v0.34.1/buildx-v0.34.1.darwin-amd64.provenance.json)

  sha256:f1c22d2338e67d46f299b289f453ee2f496a7326eb675dd20523f7c3f6160147

  53.6 KB 2026-05-19T16:50:32Z

* [buildx-v0.34.1.darwin-amd64.sbom.json](/docker/buildx/releases/download/v0.34.1/buildx-v0.34.1.darwin-amd64.sbom.json)

  sha256:36252c44ccdc9a52ad863c21f5f48734b3a998b5fe973a6ac6d24cb643a6c92b

  413 KB 2026-05-19T16:50:32Z

* [buildx-v0.34.1.darwin-arm64](/docker/buildx/releases/download/v0.34.1/buildx-v0.34.1.darwin-arm64)

  sha256:e5040acdaac1a349de84c0e7a80c861a368e0d141bf7260e1fd9a74b16749477

  59.8 MB 2026-05-19T18:38:14Z

* [buildx-v0.34.1.darwin-arm64.provenance.json](/docker/buildx/releases/download/v0.34.1/buildx-v0.34.1.darwin-arm64.provenance.json)

  sha256:39821f6cb2985b60ada4860e1f1237480429c3433e3788d32bb0c0fb7b7499cb

  53.6 KB 2026-05-19T16:50:32Z

* [buildx-v0.34.1.darwin-arm64.sbom.json](/docker/buildx/releases/download/v0.34.1/buildx-v0.34.1.darwin-arm64.sbom.json)

  sha256:e5eb02c89b931ec645a24b09dde1da10645dd9fceeb475f625b96240ed529d36

  413 KB 2026-05-19T16:50:32Z

* [buildx-v0.34.1.freebsd-amd64](/docker/buildx/releases/download/v0.34.1/buildx-v0.34.1.freebsd-amd64)

  sha256:707f62b33e6ccf97fae46f69ddf1e16307c63fb9fbd5e534ffb77d2ecd5c4cfc

  62 MB 2026-05-19T16:50:32Z

* [buildx-v0.34.1.freebsd-amd64.provenance.json](/docker/buildx/releases/download/v0.34.1/buildx-v0.34.1.freebsd-amd64.provenance.json)

  sha256:6ea4a4ee4a766010758b2edae2c0093df5f97971379e65e12a8af224cacec37b

  53.6 KB 2026-05-19T16:50:32Z

* [buildx-v0.34.1.freebsd-amd64.sbom.json](/docker/buildx/releases/download/v0.34.1/buildx-v0.34.1.freebsd-amd64.sbom.json)

  sha256:77e3ed49199668e117556c52ac44a22f9506ffc397768fa1ec77e8b6eeb8ff5c

  415 KB 2026-05-19T16:50:32Z

* [buildx-v0.34.1.freebsd-amd64.sigstore.json](/docker/buildx/releases/download/v0.34.1/buildx-v0.34.1.freebsd-amd64.sigstore.json)

  sha256:72868188a878b8a648e59a0d4b8b13c18a2749e4f36e856c9762877373eb0fde

  82.1 KB 2026-05-19T16:50:32Z

* [Source code (zip)](/docker/buildx/archive/refs/tags/v0.34.1.zip)

  2026-05-19T16:37:46Z

* [Source code (tar.gz)](/docker/buildx/archive/refs/tags/v0.34.1.tar.gz)

  2026-05-19T16:37:46Z

* Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

## v0.34.0

13 May 14:51

[github-actions](/apps/github-actions)

[v0.34.0](/docker/buildx/tree/v0.34.0)

This tag was signed with the committer’s **verified signature**.

[](/crazy-max)[crazy-max](/crazy-max) CrazyMax

GPG key ID: ADE44D8C9D44FBE4

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`3e73561`](/docker/buildx/commit/3e73561e39785683b31b05eeab1ef645be44ca42)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.34.0](/docker/buildx/releases/tag/v0.34.0)

Welcome to the v0.34.0 release of buildx!

Please try out the release binaries and report any issues at\
<https://github.com/docker/buildx/issues>.

### Contributors

* CrazyMax
* Tõnis Tiigi
* Sebastiaan van Stijn
* Jonathan A. Sternberg
* Guillaume Lours
* Hervé Le Meur
* Mateusz Gozdek

### Notable Changes

* Buildx now supports a default source policy for common build pipeline images that are provided by Docker Inc and signed by [Docker GitHub builder](https://github.com/docker/github-builder). These include `docker/dockerfile` frontend (including `docker/dockerfile-upstream` staging area) and `docker/buildkit-syft-scanner` image used for SBOM generation. These images are cryptographically verified to be authentic releases before they are used in builds. This feature is currently opt-in behind the `BUILDX_DEFAULT_POLICY` environment variable, but the intention is to enable it by default in a future release [#3807](https://github.com/docker/buildx/pull/3807)
* Add `--policy` flag to `bake` command to specify global policy evaluation options. [#3832](https://github.com/docker/buildx/pull/3832)
* Kubernetes driver now supports persistent storage options that change the deployment definition to use a StatefulSet and a persistent volume claim. [#3766](https://github.com/docker/buildx/pull/3766)
* Fix issue where progress policy errors may have been lost in progress output. [#3838](https://github.com/docker/buildx/pull/3838)
* Fix stopping `dial-stdio` command when the builder connection closes [#3790](https://github.com/docker/buildx/pull/3790)
* Fix possible panic in `buildx debug` command when solving fails [#3823](https://github.com/docker/buildx/pull/3823)
* Fix handling of Windows paths in local OCI layout definitions [#3825](https://github.com/docker/buildx/pull/3825) [#3820](https://github.com/docker/buildx/pull/3820) [#3812](https://github.com/docker/buildx/pull/3812)
* Fix possible incorrect error when using `rm` commands on Docker context based builders [#3817](https://github.com/docker/buildx/pull/3817)
* Fix possible cache miss due to nondeterministic ordering of extra hosts [#3789](https://github.com/docker/buildx/pull/3789)
* Fix mounting of WSL libraries for GPU devices only on local docker-container endpoints [#3784](https://github.com/docker/buildx/pull/3784)

### Dependency Changes

* **github.com/aws/aws-sdk-go-v2** v1.41.4 -> v1.41.7
* **github.com/aws/aws-sdk-go-v2/config** v1.32.12 -> v1.32.17
* **github.com/aws/aws-sdk-go-v2/credentials** v1.19.12 -> v1.19.16
* **github.com/aws/aws-sdk-go-v2/feature/ec2/imds** v1.18.20 -> v1.18.23
* **github.com/aws/aws-sdk-go-v2/internal/configsources** v1.4.20 -> v1.4.23
* **github.com/aws/aws-sdk-go-v2/internal/endpoints/v2** v2.7.20 -> v2.7.23
* **github.com/aws/aws-sdk-go-v2/internal/v4a** v1.4.24 ***new***
* **github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding** v1.13.7 -> v1.13.9
* **github.com/aws/aws-sdk-go-v2/service/internal/presigned-url** v1.13.20 -> v1.13.23
* **github.com/aws/aws-sdk-go-v2/service/signin** v1.0.8 -> v1.0.11
* **github.com/aws/aws-sdk-go-v2/service/sso** v1.30.13 -> v1.30.17
* **github.com/aws/aws-sdk-go-v2/service/ssooidc** v1.35.17 -> v1.35.21
* **github.com/aws/aws-sdk-go-v2/service/sts** v1.41.9 -> v1.42.1
* **github.com/aws/smithy-go** v1.24.2 -> v1.25.1
* **github.com/clipperhouse/uax29/v2** v2.2.0 ***new***
* **github.com/compose-spec/compose-go/v2** v2.9.1 -> v2.10.2
* **github.com/containerd/containerd/v2** v2.2.2 -> v2.2.3
* **github.com/docker/cli** v29.3.1 -> v29.4.3
* **github.com/docker/go-connections** v0.6.0 -> v0.7.0
* **github.com/mattn/go-runewidth** v0.0.16 -> v0.0.23
* **github.com/moby/buildkit** v0.29.0 -> v0.30.0
* **github.com/moby/moby/api** v1.54.0 -> v1.54.2
* **github.com/moby/moby/client** v0.3.0 -> v0.4.1
* **github.com/moby/policy-helpers** b7c0b994300b -> a39d60132186
* **github.com/moby/spdystream** v0.5.0 -> v0.5.1
* **go.opentelemetry.io/otel/exporters/stdout/stdouttrace** v1.38.0 -> v1.42.0
* **go.opentelemetry.io/otel/metric** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/sdk** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/sdk/metric** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/trace** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/proto/otlp** v1.9.0 -> v1.10.0
* **go.yaml.in/yaml/v4** v4.0.0-rc.4 ***new***
* **golang.org/x/crypto** v0.48.0 -> v0.50.0
* **golang.org/x/mod** v0.33.0 -> v0.34.0
* **golang.org/x/net** v0.51.0 -> v0.53.0
* **golang.org/x/oauth2** v0.34.0 -> v0.36.0
* **golang.org/x/sync** v0.19.0 -> v0.20.0
* **golang.org/x/sys** v0.42.0 -> v0.43.0
* **golang.org/x/term** v0.41.0 -> v0.42.0
* **golang.org/x/text** v0.34.0 -> v0.36.0
* **golang.org/x/time** v0.14.0 -> v0.15.0
* **golang.org/x/tools** v0.41.0 -> v0.43.0
* **google.golang.org/genproto/googleapis/api** 8636f8732409 -> 6f92a3bedf2d
* **google.golang.org/genproto/googleapis/rpc** 8636f8732409 -> 6f92a3bedf2d
* **google.golang.org/grpc** v1.79.3 -> v1.80.0
* **k8s.io/api** v0.35.2 -> v0.35.4
* **k8s.io/apimachinery** v0.35.2 -> v0.35.4
* **k8s.io/client-go** v0.35.2 -> v0.35.4

Previous release can be found at [v0.33.0](https://github.com/docker/buildx/releases/tag/v0.33.0)

Assets 69

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

2 people reacted

## v0.34.0-rc2

11 May 22:09

[github-actions](/apps/github-actions)

[v0.34.0-rc2](/docker/buildx/tree/v0.34.0-rc2)

This tag was signed with the committer’s **verified signature**. The key has expired.

[](/tonistiigi)[tonistiigi](/tonistiigi) Tõnis Tiigi

GPG key ID: AFA9DE5F8AB7AF39

Expired

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`ee42096`](/docker/buildx/commit/ee42096f31cceca381335b00a010ca8eb14089d7)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.34.0-rc2](/docker/buildx/releases/tag/v0.34.0-rc2) Pre-release

Pre-release

buildx 0.34.0-rc2

Welcome to the v0.34.0-rc2 release of buildx!\
*This is a pre-release of buildx*

Please try out the release binaries and report any issues at\
<https://github.com/docker/buildx/issues>.

### Contributors

* Tõnis Tiigi
* CrazyMax

### Notable Changes

* Add `--policy` flag to `bake` command to specify global policy evaluation options. [#3832](https://github.com/docker/buildx/pull/3832)
* Fix issue where progress policy errors may have been lost in progress output. [#3838](https://github.com/docker/buildx/pull/3838)

### Dependency Changes

* **github.com/go-openapi/runtime** v0.29.2 -> v0.29.3
* **github.com/go-openapi/swag** v0.25.4 -> v0.25.5
* **github.com/go-openapi/swag/cmdutils** v0.25.4 -> v0.25.5
* **github.com/go-openapi/swag/netutils** v0.25.4 -> v0.25.5
* **github.com/moby/buildkit** v0.30.0-rc1 -> v0.30.0-rc2
* **github.com/moby/policy-helpers** b7c0b994300b -> a39d60132186
* **github.com/sigstore/sigstore** v1.10.4 -> v1.10.5
* **github.com/sigstore/timestamp-authority/v2** v2.0.3 -> v2.0.6

Previous release can be found at [v0.34.0-rc1](https://github.com/docker/buildx/releases/tag/v0.34.0-rc1)

Assets 69

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

1 person reacted

## v0.34.0-rc1

07 May 01:33

[github-actions](/apps/github-actions)

[v0.34.0-rc1](/docker/buildx/tree/v0.34.0-rc1)

This tag was signed with the committer’s **verified signature**. The key has expired.

[](/tonistiigi)[tonistiigi](/tonistiigi) Tõnis Tiigi

GPG key ID: AFA9DE5F8AB7AF39

Expired

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`9392590`](/docker/buildx/commit/9392590cfa63ce4065b32f9d1daa6844eedf00e4)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.34.0-rc1](/docker/buildx/releases/tag/v0.34.0-rc1) Pre-release

Pre-release

buildx 0.34.0-rc1

Welcome to the v0.34.0-rc1 release of buildx!\
*This is a pre-release of buildx*

Please try out the release binaries and report any issues at\
<https://github.com/docker/buildx/issues>.

### Contributors

* CrazyMax
* Tõnis Tiigi
* Sebastiaan van Stijn
* Jonathan A. Sternberg
* Guillaume Lours
* Hervé Le Meur
* Mateusz Gozdek

### Notable Changes

* Buildx now supports a default source policy for common build pipeline images that are provided by Docker Inc and signed by [Docker GitHub builder](https://github.com/docker/github-builder). These include `docker/dockerfile` frontend (including `docker/dockerfile-upstream` staging area) and `docker/buildkit-syft-scanner` image used for SBOM generation. These images are cryptographically verified to be authentic releases before they are used in builds. This feature is currently opt-in behind the `BUILDX_DEFAULT_POLICY` environment variable, but the intention is to enable it by default in a future release [#3807](https://github.com/docker/buildx/pull/3807)
* Kubernetes driver now supports persistent storage options that change the deployment definition to use a StatefulSet and a persistent volume claim. [#3766](https://github.com/docker/buildx/pull/3766)
* Fix stopping `dial-stdio` command when the builder connection closes [#3790](https://github.com/docker/buildx/pull/3790)
* Fix possible panic in `buildx debug` command when solving fails [#3823](https://github.com/docker/buildx/pull/3823)
* Fix handling of Windows paths in local OCI layout definitions [#3825](https://github.com/docker/buildx/pull/3825) [#3820](https://github.com/docker/buildx/pull/3820) [#3812](https://github.com/docker/buildx/pull/3812)
* Fix possible incorrect error when using `rm` commands on Docker context based builders [#3817](https://github.com/docker/buildx/pull/3817)
* Fix possible cache miss due to nondeterministic ordering of extra hosts [#3789](https://github.com/docker/buildx/pull/3789)
* Fix mounting of WSL libraries for GPU devices only on local docker-container endpoints [#3784](https://github.com/docker/buildx/pull/3784)

### Dependency Changes

* **github.com/aws/aws-sdk-go-v2** v1.41.4 -> v1.41.7
* **github.com/aws/aws-sdk-go-v2/config** v1.32.12 -> v1.32.17
* **github.com/aws/aws-sdk-go-v2/credentials** v1.19.12 -> v1.19.16
* **github.com/aws/aws-sdk-go-v2/feature/ec2/imds** v1.18.20 -> v1.18.23
* **github.com/aws/aws-sdk-go-v2/internal/configsources** v1.4.20 -> v1.4.23
* **github.com/aws/aws-sdk-go-v2/internal/endpoints/v2** v2.7.20 -> v2.7.23
* **github.com/aws/aws-sdk-go-v2/internal/v4a** v1.4.24 ***new***
* **github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding** v1.13.7 -> v1.13.9
* **github.com/aws/aws-sdk-go-v2/service/internal/presigned-url** v1.13.20 -> v1.13.23
* **github.com/aws/aws-sdk-go-v2/service/signin** v1.0.8 -> v1.0.11
* **github.com/aws/aws-sdk-go-v2/service/sso** v1.30.13 -> v1.30.17
* **github.com/aws/aws-sdk-go-v2/service/ssooidc** v1.35.17 -> v1.35.21
* **github.com/aws/aws-sdk-go-v2/service/sts** v1.41.9 -> v1.42.1
* **github.com/aws/smithy-go** v1.24.2 -> v1.25.1
* **github.com/clipperhouse/uax29/v2** v2.2.0 ***new***
* **github.com/compose-spec/compose-go/v2** v2.9.1 -> v2.10.2
* **github.com/containerd/containerd/v2** v2.2.2 -> v2.2.3
* **github.com/docker/cli** v29.3.1 -> v29.4.2
* **github.com/docker/go-connections** v0.6.0 -> v0.7.0
* **github.com/grpc-ecosystem/grpc-gateway/v2** v2.27.7 -> v2.28.0
* **github.com/in-toto/in-toto-golang** v0.10.0 -> v0.11.0
* **github.com/klauspost/compress** v1.18.5 -> v1.18.6
* **github.com/mattn/go-runewidth** v0.0.16 -> v0.0.23
* **github.com/moby/buildkit** v0.29.0 -> v0.30.0-rc1
* **github.com/moby/moby/api** v1.54.0 -> v1.54.2
* **github.com/moby/moby/client** v0.3.0 -> v0.4.1
* **github.com/moby/spdystream** v0.5.0 -> v0.5.1
* **go.opentelemetry.io/otel/exporters/stdout/stdouttrace** v1.38.0 -> v1.42.0
* **go.opentelemetry.io/otel/metric** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/sdk** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/sdk/metric** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/otel/trace** v1.40.0 -> v1.43.0
* **go.opentelemetry.io/proto/otlp** v1.9.0 -> v1.10.0
* **go.yaml.in/yaml/v4** v4.0.0-rc.4 ***new***
* **google.golang.org/genproto/googleapis/api** 8636f8732409 -> 6f92a3bedf2d
* **google.golang.org/genproto/googleapis/rpc** 8636f8732409 -> 6f92a3bedf2d
* **google.golang.org/grpc** v1.79.3 -> v1.80.0
* **k8s.io/api** v0.35.2 -> v0.35.4
* **k8s.io/apimachinery** v0.35.2 -> v0.35.4
* **k8s.io/client-go** v0.35.2 -> v0.35.4

Previous release can be found at [v0.33.0](https://github.com/docker/buildx/releases/tag/v0.33.0)

Assets 69

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

1 person reacted

## v0.33.0

31 Mar 15:32

[github-actions](/apps/github-actions)

[v0.33.0](/docker/buildx/tree/v0.33.0)

[`f7897eb`](/docker/buildx/commit/f7897eba028583e0071642db3c011e860444f8cf)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.33.0](/docker/buildx/releases/tag/v0.33.0)

Welcome to the v0.33.0 release of buildx!

Please try out the release binaries and report any issues at\
<https://github.com/docker/buildx/issues>.

### Contributors

* Tõnis Tiigi
* CrazyMax
* Jonathan A. Sternberg
* Sebastiaan van Stijn
* rishabh
* Akihiro Suda

### Notable Changes

* Imagetools `create` and `inspect` commands now support OCI layout paths as source and destination that can be used together with registry references [#3721](https://github.com/docker/buildx/pull/3721)
* Bake command supports new builtin functions `formattimestamp` and `unixtimestampparse` for better handling of time values [#3286](https://github.com/docker/buildx/pull/3286)
* DAP debugger support is now generally available without the need for the experimental features flag [#3736](https://github.com/docker/buildx/pull/3736)
* Policy evaluation now supports verifying HTTP sources with PGP signatures through the `verify_http_pgp_signature` builtin [#3677](https://github.com/docker/buildx/pull/3677)
* `policy eval` command now supports `--platform` flag to specify the platform for evaluated image sources [#3738](https://github.com/docker/buildx/pull/3738)
* `policy eval` can now read policy from stdin when `-f -` is used [#3738](https://github.com/docker/buildx/pull/3738)
* `policy eval` flag `--filename` has been renamed to `--file` for consistency with other commands. The previous flag is deprecated. [#3738](https://github.com/docker/buildx/pull/3738)
* Fix issue where `imagetools create` could in some cases upload the same (attestation) manifest multiple times, possibly causing `400` error in some registries [#3731](https://github.com/docker/buildx/pull/3731)
* Fix rejecting empty string values for `BUILDKIT_SYNTAX` build argument override [#3734](https://github.com/docker/buildx/pull/3734)
* Fix possible inconsistent build context contents when using remote bake builds with a subdirectory in context path [#3678](https://github.com/docker/buildx/pull/3678)
* Fix possible formatting issue in `imagetools inspect` based on whitespace in input [#3732](https://github.com/docker/buildx/pull/3732)
* Fix possible error when finalizing build history traces in multi-node builders [#3716](https://github.com/docker/buildx/pull/3716) [#3717](https://github.com/docker/buildx/pull/3717)
* Fix possible build errors when linking Bake multi-platform targets with session attributes like build secrets [#3696](https://github.com/docker/buildx/pull/3696)
* Fix remote Bake git contexts to preserve subdirectory paths [#3682](https://github.com/docker/buildx/pull/3682)
* Fix proxy build-arg override detection when argument casing differs [#3697](https://github.com/docker/buildx/pull/3697)
* Fix DAP breakpoints on the entrypoint line being skipped in some cases [#3691](https://github.com/docker/buildx/pull/3691)
* Fix DAP breakpoint detection on case-insensitive filesystems such as Windows [#3704](https://github.com/docker/buildx/pull/3704)
* Fix DAP source path mapping for Dockerfiles outside the context root or in subdirectories [#3709](https://github.com/docker/buildx/pull/3709)
* Fix DAP stepping by skipping internal build context load steps without source locations [#3712](https://github.com/docker/buildx/pull/3712)
* Fix over-eager DAP input evaluation while stepping through builds [#3687](https://github.com/docker/buildx/pull/3687)
* Fix DAP checks for whether an exec command can run successfully [#3701](https://github.com/docker/buildx/pull/3701)
* Fix DAP debugger exit status reporting and output delivery on session shutdown [#3735](https://github.com/docker/buildx/pull/3735)

### Dependency Changes

* **github.com/aws/aws-sdk-go-v2** v1.41.1 -> v1.41.4
* **github.com/containerd/containerd/v2** v2.2.1 -> v2.2.2
* **github.com/containerd/ttrpc** v1.2.7 -> v1.2.8
* **github.com/grpc-ecosystem/grpc-gateway/v2** v2.27.3 -> v2.27.7
* **github.com/klauspost/compress** v1.18.4 -> v1.18.5
* **github.com/moby/buildkit** v0.28.0 -> v0.29.0
* **github.com/moby/moby/api** v1.53.0 -> v1.54.0
* **github.com/moby/moby/client** v0.2.2 -> v0.3.0
* **github.com/moby/patternmatcher** v0.6.0 -> v0.6.1
* **k8s.io/api** v0.34.1 -> v0.35.2
* **k8s.io/apimachinery** v0.34.1 -> v0.35.2
* **k8s.io/client-go** v0.34.1 -> v0.35.2
* **k8s.io/kube-openapi** f3f2b991d03b -> 589584f1c912
* **k8s.io/utils** 4c0f3b243397 -> bc988d571ff4
* **sigs.k8s.io/json** cfa47c3a1cc8 -> 2d320260d730

Previous release can be found at [v0.32.1](https://github.com/docker/buildx/releases/tag/v0.32.1)

Assets 69

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

4 people reacted

## v0.33.0-rc1

26 Mar 01:31

[github-actions](/apps/github-actions)

[v0.33.0-rc1](/docker/buildx/tree/v0.33.0-rc1)

This tag was signed with the committer’s **verified signature**. The key has expired.

[](/tonistiigi)[tonistiigi](/tonistiigi) Tõnis Tiigi

GPG key ID: AFA9DE5F8AB7AF39

Expired

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`55e8fa3`](/docker/buildx/commit/55e8fa3b8ebb673f36bae3a4b9cffcaadfcfceb9)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.33.0-rc1](/docker/buildx/releases/tag/v0.33.0-rc1) Pre-release

Pre-release

buildx 0.33.0-rc1

Welcome to the v0.33.0-rc1 release of buildx!\
*This is a pre-release of buildx*

Please try out the release binaries and report any issues at\
<https://github.com/docker/buildx/issues>.

### Contributors

* Tõnis Tiigi
* CrazyMax
* Jonathan A. Sternberg
* Sebastiaan van Stijn
* rishabh
* Akihiro Suda

### Notable Changes

* Imagetools `create` and `inspect` commands now support OCI layout paths as source and destination that can be used together with registry references [#3721](https://github.com/docker/buildx/pull/3721)
* Bake command supports new builtin functions `formattimestamp` and `unixtimestampparse` for better handling of time values [#3286](https://github.com/docker/buildx/pull/3286)
* DAP debugger support is now generally available without the need for the experimental features flag [#3736](https://github.com/docker/buildx/pull/3736)
* `policy eval` command now supports `--platform` flag to specify the platform for evaluated image sources [#3738](https://github.com/docker/buildx/pull/3738)
* `policy eval` can now read policy from stdin when `-f -` is used [#3738](https://github.com/docker/buildx/pull/3738)
* `policy eval` flag `--filename` has been renamed to `--file` for consistency with other commands. The previous flag is deprecated. [#3738](https://github.com/docker/buildx/pull/3738)
* Fix issue where `imagetools create` could in some cases upload the same (attestation) manifest multiple times, possibly causing `400` error in some registries [#3731](https://github.com/docker/buildx/pull/3731)
* Fix rejecting empty string values for `BUILDKIT_SYNTAX` build argument override [#3734](https://github.com/docker/buildx/pull/3734)
* Fix possible inconsistent build context contents when using remote bake builds with a subdirectory in context path [#3678](https://github.com/docker/buildx/pull/3678)
* Fix possible formatting issue in `imagetools inspect` based on whitespace in input [#3732](https://github.com/docker/buildx/pull/3732)
* Fix possible error when finalizing build history traces in multi-node builders [#3716](https://github.com/docker/buildx/pull/3716) [#3717](https://github.com/docker/buildx/pull/3717)
* Fix possible build errors when linking Bake multi-platform targets with session attributes like build secrets [#3696](https://github.com/docker/buildx/pull/3696)
* Fix remote Bake git contexts to preserve subdirectory paths [#3682](https://github.com/docker/buildx/pull/3682)
* Fix proxy build-arg override detection when argument casing differs [#3697](https://github.com/docker/buildx/pull/3697)
* Fix DAP breakpoints on the entrypoint line being skipped in some cases [#3691](https://github.com/docker/buildx/pull/3691)
* Fix DAP breakpoint detection on case-insensitive filesystems such as Windows [#3704](https://github.com/docker/buildx/pull/3704)
* Fix DAP source path mapping for Dockerfiles outside the context root or in subdirectories [#3709](https://github.com/docker/buildx/pull/3709)
* Fix DAP stepping by skipping internal build context load steps without source locations [#3712](https://github.com/docker/buildx/pull/3712)
* Fix over-eager DAP input evaluation while stepping through builds [#3687](https://github.com/docker/buildx/pull/3687)
* Fix DAP checks for whether an exec command can run successfully [#3701](https://github.com/docker/buildx/pull/3701)
* Fix DAP debugger exit status reporting and output delivery on session shutdown [#3735](https://github.com/docker/buildx/pull/3735)

### Dependency Changes

* **github.com/aws/aws-sdk-go-v2** v1.41.1 -> v1.41.4
* **github.com/containerd/containerd/v2** v2.2.1 -> v2.2.2
* **github.com/containerd/ttrpc** v1.2.7 -> v1.2.8
* **github.com/grpc-ecosystem/grpc-gateway/v2** v2.27.3 -> v2.27.7
* **github.com/klauspost/compress** v1.18.4 -> v1.18.5
* **github.com/moby/buildkit** v0.28.0 -> v0.29.0-rc1
* **github.com/moby/moby/api** v1.53.0 -> v1.54.0
* **github.com/moby/moby/client** v0.2.2 -> v0.3.0
* **github.com/moby/patternmatcher** v0.6.0 -> v0.6.1
* **github.com/moby/policy-helpers** 824747bfdd3c -> b7c0b994300b
* **github.com/oklog/ulid/v2** v2.1.1 ***new***
* **go.opentelemetry.io/otel** v1.38.0 -> v1.40.0
* **go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc** v1.38.0 -> v1.39.0
* **go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp** v1.38.0 -> v1.39.0
* **go.opentelemetry.io/otel/exporters/otlp/otlptrace** v1.38.0 -> v1.40.0
* **go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc** v1.38.0 -> v1.39.0
* **go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp** v1.38.0 -> v1.40.0
* **go.opentelemetry.io/otel/metric** v1.38.0 -> v1.40.0
* **go.opentelemetry.io/otel/sdk** v1.38.0 -> v1.40.0
* **go.opentelemetry.io/otel/sdk/metric** v1.38.0 -> v1.40.0
* **go.opentelemetry.io/otel/trace** v1.38.0 -> v1.40.0
* **go.opentelemetry.io/proto/otlp** v1.7.1 -> v1.9.0
* **google.golang.org/genproto/googleapis/api** ff82c1b0f217 -> 8636f8732409
* **google.golang.org/genproto/googleapis/rpc** 0a764e51fe1b -> 8636f8732409
* **google.golang.org/grpc** v1.78.0 -> v1.79.3
* **k8s.io/api** v0.34.1 -> v0.35.2
* **k8s.io/apimachinery** v0.34.1 -> v0.35.2
* **k8s.io/client-go** v0.34.1 -> v0.35.2
* **k8s.io/kube-openapi** f3f2b991d03b -> 589584f1c912
* **k8s.io/utils** 4c0f3b243397 -> bc988d571ff4
* **sigs.k8s.io/json** cfa47c3a1cc8 -> 2d320260d730

Previous release can be found at [v0.32.1](https://github.com/docker/buildx/releases/tag/v0.32.1)

Assets 69

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

1 person reacted

## v0.32.1

04 Mar 20:36

[github-actions](/apps/github-actions)

[v0.32.1](/docker/buildx/tree/v0.32.1)

This tag was signed with the committer’s **verified signature**. The key has expired.

[](/tonistiigi)[tonistiigi](/tonistiigi) Tõnis Tiigi

GPG key ID: AFA9DE5F8AB7AF39

Expired

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`d3bfb3f`](/docker/buildx/commit/d3bfb3f4e48a67dda56e957a6636f4fab6c5fcb2)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.32.1](/docker/buildx/releases/tag/v0.32.1)

buildx 0.32.1

Welcome to the v0.32.1 release of buildx!

Please try out the release binaries and report any issues at\
<https://github.com/docker/buildx/issues>.

### Contributors

* CrazyMax
* Tõnis Tiigi

### Notable Changes

* Fix possible error when building private Git repositories with secret credentials directly from remote source [#3694](https://github.com/docker/buildx/pull/3694)

### Dependency Changes

This release has no dependency changes

Previous release can be found at [v0.32.0](https://github.com/docker/buildx/releases/tag/v0.32.0)

Assets 69

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

1 person reacted

## v0.32.0

04 Mar 00:50

[github-actions](/apps/github-actions)

[v0.32.0](/docker/buildx/tree/v0.32.0)

This tag was signed with the committer’s **verified signature**. The key has expired.

[](/tonistiigi)[tonistiigi](/tonistiigi) Tõnis Tiigi

GPG key ID: AFA9DE5F8AB7AF39

Expired

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`a953c9b`](/docker/buildx/commit/a953c9b4b457d29a1559364f1006865fd042c66d)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.32.0](/docker/buildx/releases/tag/v0.32.0)

buildx 0.32.0

Welcome to the v0.32.0 release of buildx!

Please try out the release binaries and report any issues at\
<https://github.com/docker/buildx/issues>.

### Contributors

* Tõnis Tiigi
* CrazyMax
* Sebastiaan van Stijn
* Jonathan A. Sternberg
* Akhil Manoj
* David Karlsson
* yzewei

### Notable Changes

* Imagetools now supports `--metadata-file` flag to capture properties like descriptor/digest values for the new image. [#3638](https://github.com/docker/buildx/pull/3638)
* Imagetools auth libraries have now been combined with the ones used in `build` commands, enabling previously missing support for scoped credentials and automatic fallbacks for Docker Hardened Image registries. [#3627](https://github.com/docker/buildx/pull/3627)
* Many commands now support `--timeout` flag to configure the timeout for waiting for responses from remote builders. [#3665](https://github.com/docker/buildx/pull/3665)
* Rego Policy now supports validating builds from remote sources (Git, HTTP) [#3661](https://github.com/docker/buildx/pull/3661)
* Rego Policies now include new builtins for validating signed Sigstore bundle attestations of HTTP source artifacts. Attestations can also be automatically fetched from Github API [#3657](https://github.com/docker/buildx/pull/3657)
* Rego policies can now use `input.image.provenance` to write rules validating specific provenance attestation fields. Materials of provenance can be accessed as policy secondary inputs. Requires BuildKit v0.28+ [#3652](https://github.com/docker/buildx/pull/3652) [#3662](https://github.com/docker/buildx/pull/3662)
* Builds failing due to policy violations now have better error messages with the failing step clearly marked and the last policy logs shown with the error. [#3656](https://github.com/docker/buildx/pull/3656)
* Fix possible passing of incorrect Git auth token for Bake builds when multiple remotes with different hosts exist. [#3648](https://github.com/docker/buildx/pull/3648)
* Fixed policy filesystem reference lifecycle handling to avoid stale policy filesystem state during builds. [#3674](https://github.com/docker/buildx/pull/3674)
* Normalized default policy filename resolution from environment configuration for more consistent behavior. [#3675](https://github.com/docker/buildx/pull/3675)
* Named contexts used in different projects now get unique "shared keys" (previously based on context name) to avoid overwriting destinations of other projects, with reduced performance. This feature requires Dockerfile 1.22+ [#3618](https://github.com/docker/buildx/pull/3618)
* Fix local subdir named context copied with wrong parent directory for remote Bake builds [#3678](https://github.com/docker/buildx/pull/3678)
* Bake builds now capture the original URL information of named contexts sent as inputs in request metadata [#3682](https://github.com/docker/buildx/pull/3682) [#3462](https://github.com/docker/buildx/pull/3462)
* Additional metrics associated with DAP debugger have been added [#3633](https://github.com/docker/buildx/pull/3633)
* DAP file explorer now gets a more accurate state of the file system via updated BuildKit API [#3450](https://github.com/docker/buildx/pull/3450)
* DAP file explorer source names have been improved [#3631](https://github.com/docker/buildx/pull/3631)
* Improve the output of `-q` used with `--call` [#3655](https://github.com/docker/buildx/pull/3655)

### Dependency Changes

* **github.com/aws/aws-sdk-go-v2** v1.39.6 -> v1.41.1
* **github.com/aws/aws-sdk-go-v2/config** v1.31.20 -> v1.32.7
* **github.com/aws/aws-sdk-go-v2/credentials** v1.18.24 -> v1.19.7
* **github.com/aws/aws-sdk-go-v2/feature/ec2/imds** v1.18.13 -> v1.18.17
* **github.com/aws/aws-sdk-go-v2/internal/configsources** v1.4.13 -> v1.4.17
* **github.com/aws/aws-sdk-go-v2/internal/endpoints/v2** v2.7.13 -> v2.7.17
* **github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding** v1.13.3 -> v1.13.4
* **github.com/aws/aws-sdk-go-v2/service/internal/presigned-url** v1.13.13 -> v1.13.17
* **github.com/aws/aws-sdk-go-v2/service/signin** v1.0.5 ***new***
* **github.com/aws/aws-sdk-go-v2/service/sso** v1.30.3 -> v1.30.9
* **github.com/aws/aws-sdk-go-v2/service/ssooidc** v1.35.7 -> v1.35.13
* **github.com/aws/aws-sdk-go-v2/service/sts** v1.40.2 -> v1.41.6
* **github.com/aws/smithy-go** v1.23.2 -> v1.24.0
* **github.com/cloudflare/circl** v1.6.1 -> v1.6.3
* **github.com/docker/cli** v29.1.5 -> v29.2.1
* **github.com/go-openapi/errors** v0.22.4 -> v0.22.6
* **github.com/go-openapi/jsonpointer** v0.22.1 -> v0.22.4
* **github.com/go-openapi/jsonreference** v0.21.3 -> v0.21.4
* **github.com/go-openapi/spec** v0.22.1 -> v0.22.3
* **github.com/go-openapi/swag** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/cmdutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/conv** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/fileutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/jsonname** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/jsonutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/loading** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/mangling** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/netutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/stringutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/typeutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/yamlutils** v0.25.3 -> v0.25.4
* **github.com/go-viper/mapstructure/v2** v2.4.0 -> v2.5.0
* **github.com/golang/snappy** v1.0.0 ***new***
* **github.com/google/go-containerregistry** v0.20.6 -> v0.20.7
* **github.com/in-toto/in-toto-golang** v0.9.0 -> v0.10.0
* **github.com/klauspost/compress** v1.18.2 -> v1.18.4
* **github.com/moby/buildkit** v0.27.0 -> v0.28.0
* **github.com/moby/moby/api** v1.52.0 -> v1.53.0
* **github.com/moby/moby/client** v0.2.1 -> v0.2.2
* **github.com/moby/policy-helpers** 9fcc1a9ec5c9 -> 824747bfdd3c
* **github.com/package-url/packageurl-go** v0.1.1 ***new***
* **github.com/pelletier/go-toml/v2** v2.2.4 ***new***
* **github.com/secure-systems-lab/go-securesystemslib** v0.9.1 -> v0.10.0
* **github.com/sigstore/rekor** v1.4.3 -> v1.5.0
* **github.com/sigstore/sigstore** v1.10.0 -> v1.10.4
* **github.com/sigstore/sigstore-go** b5fe07a5a7d7 -> v1.1.4
* **github.com/sigstore/timestamp-authority/v2** v2.0.2 -> v2.0.3
* **github.com/theupdateframework/go-tuf/v2** v2.3.0 -> v2.4.1
* **google.golang.org/genproto/googleapis/api** f26f9409b101 -> ff82c1b0f217
* **google.golang.org/genproto/googleapis/rpc** f26f9409b101 -> 0a764e51fe1b
* **google.golang.org/grpc** v1.76.0 -> v1.78.0

Previous release can be found at [v0.31.1](https://github.com/docker/buildx/releases/tag/v0.31.1)

Assets 69

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

2 people reacted

## v0.32.0-rc2

27 Feb 17:14

[github-actions](/apps/github-actions)

[v0.32.0-rc2](/docker/buildx/tree/v0.32.0-rc2)

[`22074cd`](/docker/buildx/commit/22074cd4009f987987cef121684ca7e4403c8011)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.32.0-rc2](/docker/buildx/releases/tag/v0.32.0-rc2) Pre-release

Pre-release

Welcome to the v0.32.0-rc2 release of buildx!\
*This is a pre-release of buildx*

Please try out the release binaries and report any issues at\
<https://github.com/docker/buildx/issues>.

### Contributors

* Tõnis Tiigi
* CrazyMax

### Notable Changes

* Improved policy evaluation for recursive provenance materials. [#3662](https://github.com/docker/buildx/pull/3662)
* Fixed policy filesystem reference lifecycle handling to avoid stale policy filesystem state during builds. [#3674](https://github.com/docker/buildx/pull/3674)
* Normalized default policy filename resolution from environment configuration for more consistent behavior. [#3675](https://github.com/docker/buildx/pull/3675)

### Dependency Changes

* **github.com/moby/buildkit** v0.28.0-rc1 -> v0.28.0-rc2
* **github.com/package-url/packageurl-go** v0.1.1 ***new***

Previous release can be found at [v0.32.0-rc1](https://github.com/docker/buildx/releases/tag/v0.32.0-rc1)

Assets 69

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

2 people reacted

## v0.32.0-rc1

25 Feb 01:21

[github-actions](/apps/github-actions)

[v0.32.0-rc1](/docker/buildx/tree/v0.32.0-rc1)

This tag was signed with the committer’s **verified signature**. The key has expired.

[](/tonistiigi)[tonistiigi](/tonistiigi) Tõnis Tiigi

GPG key ID: AFA9DE5F8AB7AF39

Expired

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[`f35e45c`](/docker/buildx/commit/f35e45c307fe6fae96cc29f0606e46c99b257e30)

This commit was created on GitHub.com and signed with GitHub’s **verified signature**.

GPG key ID: B5690EEEBB952194

Verified

[Learn about vigilant mode](https://docs.github.com/github/authenticating-to-github/displaying-verification-statuses-for-all-of-your-commits).

[v0.32.0-rc1](/docker/buildx/releases/tag/v0.32.0-rc1) Pre-release

Pre-release

buildx 0.32.0-rc1

Welcome to the v0.32.0-rc1 release of buildx!\
*This is a pre-release of buildx*

Please try out the release binaries and report any issues at\
<https://github.com/docker/buildx/issues>.

### Contributors

* Tõnis Tiigi
* CrazyMax
* Sebastiaan van Stijn
* Jonathan A. Sternberg
* Akhil Manoj
* David Karlsson
* yzewei

### Notable Changes

* Imagetools now supports `--metadata-file` flag to capture properties like descriptor/digest values for the new image. [#3638](https://github.com/docker/buildx/pull/3638)
* Imagetools auth libraries have now been combined with the ones used in `build` commands, enabling previously missing support for scoped credentials and automatic fallbacks for Docker Hardened Image registries. [#3627](https://github.com/docker/buildx/pull/3627)
* Many commands now support `--timeout` flag to configure the timeout for waiting for responses from remote builders. [#3665](https://github.com/docker/buildx/pull/3665)
* Rego Policy now supports validating builds from remote sources (Git, HTTP) [#3661](https://github.com/docker/buildx/pull/3661)
* Rego Policies now include new builtins for validating signed Sigstore bundle attestations of HTTP source artifacts. Attestations can also be automatically fetched from Github API [#3657](https://github.com/docker/buildx/pull/3657)
* Rego policies can now use `input.image.provenance` to write rules validating specific provenance attestation fields. Requires BuildKit v0.28+ [#3652](https://github.com/docker/buildx/pull/3652)
* Builds failing due to policy violations now have better error messages with the failing step clearly marked and the last policy logs shown with the error. [#3656](https://github.com/docker/buildx/pull/3656)
* Fix possible passing of incorrect Git auth token for Bake builds when multiple remotes with different hosts exist. [#3648](https://github.com/docker/buildx/pull/3648)
* Named contexts used in different projects now get unique "shared keys" (previously based on context name) to avoid overwriting destinations of other projects, with reduced performance. This feature requires Dockerfile 1.22+ [#3618](https://github.com/docker/buildx/pull/3618)
* Bake builds now capture the original URL information of named contexts sent as inputs in request metadata [#3462](https://github.com/docker/buildx/pull/3462)
* Additional metrics associated with DAP debugger have been added [#3633](https://github.com/docker/buildx/pull/3633)
* DAP file explorer now gets a more accurate state of the file system via updated BuildKit API [#3450](https://github.com/docker/buildx/pull/3450)
* DAP file explorer source names have been improved [#3631](https://github.com/docker/buildx/pull/3631)
* Improve the output of `-q` used with `--call` [#3655](https://github.com/docker/buildx/pull/3655)

### Dependency Changes

* **github.com/aws/aws-sdk-go-v2** v1.39.6 -> v1.41.1
* **github.com/aws/aws-sdk-go-v2/config** v1.31.20 -> v1.32.7
* **github.com/aws/aws-sdk-go-v2/credentials** v1.18.24 -> v1.19.7
* **github.com/aws/aws-sdk-go-v2/feature/ec2/imds** v1.18.13 -> v1.18.17
* **github.com/aws/aws-sdk-go-v2/internal/configsources** v1.4.13 -> v1.4.17
* **github.com/aws/aws-sdk-go-v2/internal/endpoints/v2** v2.7.13 -> v2.7.17
* **github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding** v1.13.3 -> v1.13.4
* **github.com/aws/aws-sdk-go-v2/service/internal/presigned-url** v1.13.13 -> v1.13.17
* **github.com/aws/aws-sdk-go-v2/service/signin** v1.0.5 ***new***
* **github.com/aws/aws-sdk-go-v2/service/sso** v1.30.3 -> v1.30.9
* **github.com/aws/aws-sdk-go-v2/service/ssooidc** v1.35.7 -> v1.35.13
* **github.com/aws/aws-sdk-go-v2/service/sts** v1.40.2 -> v1.41.6
* **github.com/aws/smithy-go** v1.23.2 -> v1.24.0
* **github.com/docker/cli** v29.1.5 -> v29.2.1
* **github.com/go-openapi/errors** v0.22.4 -> v0.22.6
* **github.com/go-openapi/jsonpointer** v0.22.1 -> v0.22.4
* **github.com/go-openapi/jsonreference** v0.21.3 -> v0.21.4
* **github.com/go-openapi/spec** v0.22.1 -> v0.22.3
* **github.com/go-openapi/swag** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/cmdutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/conv** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/fileutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/jsonname** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/jsonutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/loading** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/mangling** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/netutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/stringutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/typeutils** v0.25.3 -> v0.25.4
* **github.com/go-openapi/swag/yamlutils** v0.25.3 -> v0.25.4
* **github.com/go-viper/mapstructure/v2** v2.4.0 -> v2.5.0
* **github.com/golang/snappy** v0.0.4 ***new***
* **github.com/google/go-containerregistry** v0.20.6 -> v0.20.7
* **github.com/in-toto/in-toto-golang** v0.9.0 -> v0.10.0
* **github.com/klauspost/compress** v1.18.2 -> v1.18.4
* **github.com/moby/buildkit** v0.27.0 -> v0.28.0-rc1
* **github.com/moby/moby/api** v1.52.0 -> v1.53.0
* **github.com/moby/moby/client** v0.2.1 -> v0.2.2
* **github.com/moby/policy-helpers** 9fcc1a9ec5c9 -> 824747bfdd3c
* **github.com/pelletier/go-toml/v2** v2.2.4 ***new***
* **github.com/secure-systems-lab/go-securesystemslib** v0.9.1 -> v0.10.0
* **github.com/sigstore/rekor** v1.4.3 -> v1.5.0
* **github.com/sigstore/sigstore** v1.10.0 -> v1.10.4
* **github.com/sigstore/sigstore-go** b5fe07a5a7d7 -> v1.1.4
* **github.com/sigstore/timestamp-authority/v2** v2.0.2 -> v2.0.3
* **github.com/theupdateframework/go-tuf/v2** v2.3.0 -> v2.4.1
* **google.golang.org/genproto/googleapis/api** f26f9409b101 -> ff82c1b0f217
* **google.golang.org/genproto/googleapis/rpc** f26f9409b101 -> 0a764e51fe1b
* **google.golang.org/grpc** v1.76.0 -> v1.78.0

Previous release can be found at [v0.31.1](https://github.com/docker/buildx/releases/tag/v0.31.1)

Assets 69

Loading

### Uh oh!

There was an error while loading. [Please reload this page]().

1 person reacted

You can’t perform that action at this time.

----
url: https://docs.docker.com/scout/release-notes/platform/
----

# Docker Scout release notes

***

Table of contents

***

This page contains information about the new features, improvements, known issues, and bug fixes in Docker Scout releases. These release notes cover the Docker Scout platform, including the Dashboard. For CLI release notes, refer to [Docker Scout CLI release notes](https://docs.docker.com/scout/release-notes/cli/).

## [Q4 2024](#q4-2024)

New features and enhancements released in the fourth quarter of 2024.

### [2024-10-09](#2024-10-09)

Policy Evaluation has graduated from Early Access to General Availability.

Docker Scout Dashboard UI changes:

* On the Docker Scout Dashboard, selecting a policy card now opens the policy details page instead of the policy results page.
* The policy results page and the policy details side panel are now read-only. Policy actions (edit, disable, delete) are now accessible from the policy details page.

## [Q3 2024](#q3-2024)

New features and enhancements released in the third quarter of 2024.

### [2024-09-30](#2024-09-30)

In this release, we've changed how custom policies work. Before, custom policies were created by copying an out-of-the-box policy. Now, you can customize policies either by editing the default policy from a **policy type** which acts as a template. The default policies in Docker Scout are also implemented based on these types.

For more information, refer to [policy types](https://docs.docker.com/scout/policy/#policy-types).

### [2024-09-09](#2024-09-09)

This release changes how [health scores](https://docs.docker.com/scout/policy/scores/) are calculated in Docker Scout. The health score calculation now considers optional and custom policies that you have configured for your organization.

This means that if you have enabled, disabled, or customized any of the default policies, Docker Scout will now take those policies into account when calculating the health score for your organization's images.

If you haven't yet enabled Docker Scout for your organization, the health score calculation will be based on the out-of-the-box policies.

### [2024-08-13](#2024-08-13)

This release changes the out-of-the-box policies to align with the policy configurations used to evaluate Docker Scout [health scores](https://docs.docker.com/scout/policy/scores/).

The default out-of-the-box policies are now:

* **No high-profile vulnerabilities**
* **No fixable critical or high vulnerabilities**
* **Approved Base Images**
* **Default non-root user**
* **Supply chain attestations**
* **Up-to-Date Base Images**
* **No AGPL v3 licenses**

The configurations for these policies are now the same as the configurations used to calculate health scores. Previously, the out-of-the-box policies had different configurations than the health score policies.

## [Q2 2024](#q2-2024)

New features and enhancements released in the second quarter of 2024.

### [2024-06-27](#2024-06-27)

This release introduces initial support for **Exceptions** in the Docker Scout Dashboard. Exceptions let you suppress vulnerabilities found in your images (false positives), using VEX documents. Attach VEX documents to images as attestations, or embed them on image filesystems, and Docker Scout will automatically detect and incorporate the VEX statements into the image analysis results.

The new [Exceptions page](https://scout.docker.com/reports/vex/) lists all exceptions affecting images in your organization. You can also go to the image view in the Docker Scout Dashboard to see all exceptions that apply to a given image.

For more information, see [Manage vulnerability exceptions](https://docs.docker.com/scout/explore/exceptions/).

### [2024-05-06](#2024-05-06)

New HTTP endpoint that lets you scrape data from Docker Scout with Prometheus, to create your own vulnerability and policy dashboards with Grafana. For more information, see [Docker Scout metrics exporter](https://docs.docker.com/scout/explore/metrics-exporter/).

## [Q1 2024](#q1-2024)

New features and enhancements released in the first quarter of 2024.

### [2024-03-29](#2024-03-29)

The **No high-profile vulnerabilities** policy now reports the `xz` backdoor vulnerability [CVE-2024-3094](https://scout.docker.com/v/CVE-2024-3094). Any images in your Docker organization containing the version of `xz/liblzma` with the backdoor will be non-compliant with the **No high-profile vulnerabilities** policy.

### [2024-03-20](#2024-03-20)

The **No fixable critical or high vulnerabilities** policy now supports a **Fixable vulnerabilities only** configuration option, which lets you decide whether or not to only flag vulnerabilities with an available fix version.

### [2024-03-14](#2024-03-14)

The **All critical vulnerabilities** policy has been removed. The **No fixable critical or high vulnerabilities** policy provides similar functionality, and will be updated in the future to allow for more extensive customization, making the now-removed **All critical vulnerabilities** policy redundant.

### [2024-01-26](#2024-01-26)

**Azure Container Registry** integration graduated from [Early Access](https://docs.docker.com/release-lifecycle/#early-access-ea) to [General Availability](https://docs.docker.com/release-lifecycle/#general-availability-ga).

For more information and setup instructions, see [Integrate Azure Container Registry](https://docs.docker.com/scout/integrations/registry/acr/).

### [2024-01-23](#2024-01-23)

New **Approved Base Images** policy, which lets you restrict which base images you allow in your builds. You define the allowed base images using a pattern. Base images whose image reference don't match the specified patterns cause the policy to fail.

### [2024-01-12](#2024-01-12)

New **Default non-root user** policy, which flags images that would run as the `root` superuser with full system administration privileges by default. Specifying a non-root default user for your images can help strengthen your runtime security.

### [2024-01-11](#2024-01-11)

[Beta](https://docs.docker.com/release-lifecycle/#beta) launch of a new GitHub app for integrating Docker Scout with your source code management, and a remediation feature for helping you improve policy compliance.

Remediation is a new capability for Docker Scout to provide contextual, recommended actions based on policy evaluation results on how you can improve compliance.

The GitHub integration enhances the remediation feature. With the integration enabled, Docker Scout is able to connect analysis results to the source. This additional context about how your images are built is used to generate better, more precise recommendations.

For more information about the types of recommendations that Docker Scout can provide to help you improve policy compliance, see [Remediation](https://docs.docker.com/scout/policy/remediation/).

For more information about how to authorize the Docker Scout GitHub app on your source repositories, see [Integrate Docker Scout with GitHub](https://docs.docker.com/scout/integrations/source-code-management/github/).

## [Q4 2023](#q4-2023)

New features and enhancements released in the fourth quarter of 2023.

### [2023-12-20](#2023-12-20)

**Azure Container Registry** integration graduated from [Beta](https://docs.docker.com/release-lifecycle/#beta) to [Early Access](https://docs.docker.com/release-lifecycle/#early-access-ea).

For more information and setup instructions, see [Integrate Azure Container Registry](https://docs.docker.com/scout/integrations/registry/acr/).

### [2023-12-06](#2023-12-06)

New [SonarQube](https://www.sonarsource.com/products/sonarqube/) integration and related policy. SonarQube is an open-source platform for continuous inspection of code quality. This integration lets you add SonarQube's quality gates as a policy evaluation in Docker Scout. Enable the integration, push your images, and see the SonarQube quality gate conditions surfaced in the new **SonarQube quality gates passed** policy.

### [2023-12-01](#2023-12-01)

[Beta](https://docs.docker.com/release-lifecycle/#beta) release of a new **Azure Container Registry** (ACR) integration, which lets Docker Scout pull and analyze images in ACR repositories automatically.

To learn more about the integration and how to get started, see [Integrate Azure Container Registry](https://docs.docker.com/scout/integrations/registry/acr/).

### [2023-11-21](#2023-11-21)

New **configurable policies** feature, which enables you to tweak the out-of-the-box policies according to your preferences, or disable them entirely if they don't quite match your needs. Some examples of how you can adapt policies for your organization include:

* Change the severity-thresholds that vulnerability-related policies use
* Customize the list of "high-profile vulnerabilities"
* Add or remove software licenses to flag as "copyleft"

For more information, see [Configurable policies](https://docs.docker.com/scout/policy/configure/).

### [2023-11-10](#2023-11-10)

New **Supply chain attestations** policy for helping you track whether your images are built with SBOM and provenance attestations. Adding attestations to images is a good first step in improving your supply chain conduct, and is often a prerequisite for doing more.

### [2023-11-01](#2023-11-01)

New **No high-profile vulnerabilities** policy, which ensures your artifacts are free from a curated list of vulnerabilities widely recognized to be risky.

### [2023-10-04](#2023-10-04)

This marks the General Availability (GA) release of Docker Scout.

The following new features are included in this release:

* [Policy Evaluation](#policy-evaluation) (Early Access)
* [Amazon ECR integration](#amazon-ecr-integration)
* [Sysdig integration](#sysdig-integration)
* [JFrog Artifactory integration](#jfrog-artifactory-integration)

#### [Policy evaluation](#policy-evaluation)

Policy Evaluation is an early access feature that helps you ensure software integrity and track how your artifacts are doing over time. This release ships with four out-of-the-box policies, enabled by default for all organizations.

* **Base images not up-to-date** evaluates whether the base images are out of date, and require updating. Up-to-date base images help you ensure that your environments are reliable and secure.
* **Critical and high vulnerabilities with fixes** reports if there are vulnerabilities with critical or high severity in your images, and where there's a fix version available that you can upgrade to.
* **All critical vulnerabilities** looks out for any vulnerabilities of critical severity found in your images.
* **Packages with AGPLv3, GPLv3 license** helps you catch possibly unwanted copyleft licenses used in your images.

You can view and evaluate policy status for images using the Docker Scout Dashboard and the `docker scout policy` CLI command. For more information, refer to the [Policy Evaluation documentation](/scout/policy/).

#### [Amazon ECR integration](#amazon-ecr-integration)

The new Amazon Elastic Container Registry (ECR) integration enables image analysis for images hosted in ECR repositories.

You set up the integration using a pre-configured CloudFormation stack template that bootstraps the necessary AWS resources in your account. Docker Scout automatically analyzes images that you push to your registry, storing only the metadata about the image contents, and not the container images themselves.

The integration offers a straightforward process for adding additional repositories, activating Docker Scout for specific repositories, and removing the integration if needed. To learn more, refer to the [Amazon ECR integration documentation](https://docs.docker.com/scout/integrations/registry/ecr/).

#### [Sysdig integration](#sysdig-integration)

The new Sysdig integration gives you real-time security insights for your Kubernetes runtime environments.

Enabling this integration helps you address and prioritize risks for images used to run your production workloads. It also helps reduce monitoring noise, by automatically excluding vulnerabilities in programs that are never loaded into memory, using VEX documents.

For more information and getting started, see [Sysdig integration documentation](https://docs.docker.com/scout/integrations/environment/sysdig/).

#### [JFrog Artifactory integration](#jfrog-artifactory-integration)

The new JFrog Artifactory integration enables automatic image analysis on Artifactory registries.

The integration involves deploying a Docker Scout Artifactory agent that polls for new images, performs analysis, and uploads results to Docker Scout, all while preserving the integrity of image data.

#### [Known limitations](#known-limitations)

* Image analysis only works for Linux images
* Docker Scout can't process images larger than 12GB in compressed size
* Creating an image SBOM (part of image analysis) has a timeout limit of 4 minutes

----
url: https://docs.docker.com/engine/storage/drivers/zfs-driver/
----

# ZFS storage driver

***

Table of contents

***

ZFS is a next generation filesystem that supports many advanced storage technologies such as volume management, snapshots, checksumming, compression and deduplication, replication and more.

It was created by Sun Microsystems (now Oracle Corporation) and is open sourced under the CDDL license. Due to licensing incompatibilities between the CDDL and GPL, ZFS cannot be shipped as part of the mainline Linux kernel. However, the ZFS On Linux (ZoL) project provides an out-of-tree kernel module and userspace tools which can be installed separately.

The ZFS on Linux (ZoL) port is healthy and maturing. However, at this point in time it is not recommended to use the `zfs` Docker storage driver for production use unless you have substantial experience with ZFS on Linux.

> Note
>
> There is also a FUSE implementation of ZFS on the Linux platform. This is not recommended. The native ZFS driver (ZoL) is more tested, has better performance, and is more widely used. The remainder of this document refers to the native ZoL port.

## [Prerequisites](#prerequisites)

* ZFS requires one or more dedicated block devices, preferably solid-state drives (SSDs).
* The `/var/lib/docker/` directory must be mounted on a ZFS-formatted filesystem.
* Changing the storage driver makes any containers you have already created inaccessible on the local system. Use `docker save` to save containers, and push existing images to Docker Hub or a private repository, so that you do not need to re-create them later.

> Note
>
> There is no need to use `MountFlags=slave` because `dockerd` and `containerd` are in different mount namespaces.

## [Configure Docker with the `zfs` storage driver](#configure-docker-with-the-zfs-storage-driver)

1. Stop Docker.

2. Copy the contents of `/var/lib/docker/` to `/var/lib/docker.bk` and remove the contents of `/var/lib/docker/`.

   ```console
   $ sudo cp -au /var/lib/docker /var/lib/docker.bk

   $ sudo rm -rf /var/lib/docker/*
   ```

3. Create a new `zpool` on your dedicated block device or devices, and mount it into `/var/lib/docker/`. Be sure you have specified the correct devices, because this is a destructive operation. This example adds two devices to the pool.

   ```console
   $ sudo zpool create -f zpool-docker -m /var/lib/docker /dev/xvdf /dev/xvdg
   ```

   The command creates the `zpool` and names it `zpool-docker`. The name is for display purposes only, and you can use a different name. Check that the pool was created and mounted correctly using `zfs list`.

   ```console
   $ sudo zfs list

   NAME           USED  AVAIL  REFER  MOUNTPOINT
   zpool-docker    55K  96.4G    19K  /var/lib/docker
   ```

4. Configure Docker to use `zfs`. Edit `/etc/docker/daemon.json` and set the `storage-driver` to `zfs`. If the file was empty before, it should now look like this:

   ```json
   {
     "storage-driver": "zfs"
   }
   ```

   Save and close the file.

5. Start Docker. Use `docker info` to verify that the storage driver is `zfs`.

   ```console
   $ sudo docker info
     Containers: 0
      Running: 0
      Paused: 0
      Stopped: 0
     Images: 0
     Server Version: 17.03.1-ce
     Storage Driver: zfs
      Zpool: zpool-docker
      Zpool Health: ONLINE
      Parent Dataset: zpool-docker
      Space Used By Parent: 249856
      Space Available: 103498395648
      Parent Quota: no
      Compression: off
   <...>
   ```

## [Manage `zfs`](#manage-zfs)

### [Increase capacity on a running device](#increase-capacity-on-a-running-device)

To increase the size of the `zpool`, you need to add a dedicated block device to the Docker host, and then add it to the `zpool` using the `zpool add` command:

```console
$ sudo zpool add zpool-docker /dev/xvdh
```

### [Limit a container's writable storage quota](#limit-a-containers-writable-storage-quota)

If you want to implement a quota on a per-image/dataset basis, you can set the `size` storage option to limit the amount of space a single container can use for its writable layer.

Edit `/etc/docker/daemon.json` and add the following:

```json
{
  "storage-driver": "zfs",
  "storage-opts": ["size=256M"]
}
```

See all storage options for each storage driver in the [daemon reference documentation](/reference/cli/dockerd/#daemon-storage-driver)

Save and close the file, and restart Docker.

## [How the `zfs` storage driver works](#how-the-zfs-storage-driver-works)

ZFS uses the following objects:

* **filesystems**: thinly provisioned, with space allocated from the `zpool` on demand.
* **snapshots**: read-only space-efficient point-in-time copies of filesystems.
* **clones**: Read-write copies of snapshots. Used for storing the differences from the previous layer.

The process of creating a clone:

1. A read-only snapshot is created from the filesystem.
2. A writable clone is created from the snapshot. This contains any differences from the parent layer.

Filesystems, snapshots, and clones all allocate space from the underlying `zpool`.

### [Image and container layers on-disk](#image-and-container-layers-on-disk)

Each running container's unified filesystem is mounted on a mount point in `/var/lib/docker/zfs/graph/`. Continue reading for an explanation of how the unified filesystem is composed.

### [Image layering and sharing](#image-layering-and-sharing)

The base layer of an image is a ZFS filesystem. Each child layer is a ZFS clone based on a ZFS snapshot of the layer below it. A container is a ZFS clone based on a ZFS Snapshot of the top layer of the image it's created from.

The diagram below shows how this is put together with a running container based on a two-layer image.

When you start a container, the following steps happen in order:

1. The base layer of the image exists on the Docker host as a ZFS filesystem.

2. Additional image layers are clones of the dataset hosting the image layer directly below it.

   In the diagram, "Layer 1" is added by taking a ZFS snapshot of the base layer and then creating a clone from that snapshot. The clone is writable and consumes space on-demand from the zpool. The snapshot is read-only, maintaining the base layer as an immutable object.

3. When the container is launched, a writable layer is added above the image.

   In the diagram, the container's read-write layer is created by making a snapshot of the top layer of the image (Layer 1) and creating a clone from that snapshot.

4. As the container modifies the contents of its writable layer, space is allocated for the blocks that are changed. By default, these blocks are 128k.

## [How container reads and writes work with `zfs`](#how-container-reads-and-writes-work-with-zfs)

### [Reading files](#reading-files)

Each container's writable layer is a ZFS clone which shares all its data with the dataset it was created from (the snapshots of its parent layers). Read operations are fast, even if the data being read is from a deep layer. This diagram illustrates how block sharing works:

### [Writing files](#writing-files)

**Writing a new file**: space is allocated on demand from the underlying `zpool` and the blocks are written directly into the container's writable layer.

**Modifying an existing file**: space is allocated only for the changed blocks, and those blocks are written into the container's writable layer using a copy-on-write (CoW) strategy. This minimizes the size of the layer and increases write performance.

**Deleting a file or directory**:

* When you delete a file or directory that exists in a lower layer, the ZFS driver masks the existence of the file or directory in the container's writable layer, even though the file or directory still exists in the lower read-only layers.
* If you create and then delete a file or directory within the container's writable layer, the blocks are reclaimed by the `zpool`.

## [ZFS and Docker performance](#zfs-and-docker-performance)

There are several factors that influence the performance of Docker using the `zfs` storage driver.

* **Memory**: Memory has a major impact on ZFS performance. ZFS was originally designed for large enterprise-grade servers with a large amount of memory.

* **ZFS Features**: ZFS includes a de-duplication feature. Using this feature may save disk space, but uses a large amount of memory. It is recommended that you disable this feature for the `zpool` you are using with Docker, unless you are using SAN, NAS, or other hardware RAID technologies.

* **ZFS Caching**: ZFS caches disk blocks in a memory structure called the adaptive replacement cache (ARC). The *Single Copy ARC* feature of ZFS allows a single cached copy of a block to be shared by multiple clones of a With this feature, multiple running containers can share a single copy of a cached block. This feature makes ZFS a good option for PaaS and other high-density use cases.

* **Fragmentation**: Fragmentation is a natural byproduct of copy-on-write filesystems like ZFS. ZFS mitigates this by using a small block size of 128k. The ZFS intent log (ZIL) and the coalescing of writes (delayed writes) also help to reduce fragmentation. You can monitor fragmentation using `zpool status`. However, there is no way to defragment ZFS without reformatting and restoring the filesystem.

* **Use the native ZFS driver for Linux**: The ZFS FUSE implementation is not recommended, due to poor performance.

### [Performance best practices](#performance-best-practices)

* **Use fast storage**: Solid-state drives (SSDs) provide faster reads and writes than spinning disks.

* **Use volumes for write-heavy workloads**: Volumes provide the best and most predictable performance for write-heavy workloads. This is because they bypass the storage driver and do not incur any of the potential overheads introduced by thin provisioning and copy-on-write. Volumes have other benefits, such as allowing you to share data among containers and persisting even when no running container is using them.

----
url: https://docs.docker.com/build/ci/github-actions/update-dockerhub-desc/
----

# Update Docker Hub description with GitHub Actions

***

***

You can update the Docker Hub repository description using a third party action called [Docker Hub Description](https://github.com/peter-evans/dockerhub-description) with this action:

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          push: true
          tags: user/app:latest

      - name: Update repo description
        uses: peter-evans/dockerhub-description@e98e4d1628a5f3be2be7c231e50981aee98723ae # v4.0.0
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
          repository: user/app
```

----
url: https://docs.docker.com/extensions/extensions-sdk/extensions/DISTRIBUTION/
----

# Package and release your extension

***

Table of contents

***

This page contains additional information on how to package and distribute extensions.

## [Package your extension](#package-your-extension)

Docker extensions are packaged as Docker images. The entire extension runtime including the UI, backend services (host or VM), and any necessary binary must be included in the extension image. Every extension image must contain a `metadata.json` file at the root of its filesystem that defines the [contents of the extension](https://docs.docker.com/extensions/extensions-sdk/architecture/metadata/).

The Docker image must have several [image labels](https://docs.docker.com/extensions/extensions-sdk/extensions/labels/), providing information about the extension. See how to use [extension labels](https://docs.docker.com/extensions/extensions-sdk/extensions/labels/) to provide extension overview information.

To package and release an extension, you must build a Docker image (`docker build`), and push the image to [Docker Hub](https://hub.docker.com/) (`docker push`) with a specific tag that lets you manage versions of the extension.

## [Release your extension](#release-your-extension)

Docker image tags must follow semver conventions in order to allow fetching the latest version of the extension, and to know if there are updates available. See [semver.org](https://semver.org/) to learn more about semantic versioning.

Extension images must be multi-arch images so that users can install extensions on ARM/AMD hardware. These multi-arch images can include ARM/AMD specific binaries. Mac users will automatically use the right image based on their architecture. Extensions that install binaries on the host must also provide Windows binaries in the same extension image. See how to [build a multi-arch image](https://docs.docker.com/extensions/extensions-sdk/extensions/multi-arch/) for your extension.

You can implement extensions without any constraints on the code repository. Docker doesn't need access to the code repository in order to use the extension. Also, you can manage new releases of your extension, without any dependency on Docker Desktop releases.

## [New releases and updates](#new-releases-and-updates)

You can release a new version of your Docker extension by pushing a new image with a new tag to Docker Hub.

Any new image pushed to an image repository corresponding to an extension defines a new version of that extension. Image tags are used to identify version numbers. Extension versions must follow semver to make it easy to understand and compare versions.

Docker Desktop scans the list of extensions published in the marketplace for new versions, and provides notifications to users when they can upgrade a specific extension. Extensions that aren't part of the Marketplace don't have automatic update notifications at the moment.

Users can download and install the newer version of any extension without updating Docker Desktop itself.

## [Extension API dependencies](#extension-api-dependencies)

Extensions must specify the Extension API version they rely on. Docker Desktop checks the extension's required version, and only proposes to install extensions that are compatible with the current Docker Desktop version installed. Users might need to update Docker Desktop in order to install the latest extensions available.

Extension image labels must specify the API version that the extension relies upon. This allows Docker Desktop to inspect newer versions of extension images without downloading the full extension image upfront.

## [License on extensions and the extension SDK](#license-on-extensions-and-the-extension-sdk)

The [Docker Extension SDK](https://www.npmjs.com/package/@docker/extension-api-client) is licensed under the Apache 2.0 License and is free to use.

There is no constraint on how each extension should be licensed, this is up to you to decide when creating a new extension.

----
url: https://docs.docker.com/docker-hub/usage/
----

# Docker Hub usage and limits

***

Table of contents

***

The following table provides an overview of the included usage and limits for each user type, subject to fair use:

| User type                | Pull rate limit per 6 hours             | Number of public repositories | Number of private repositories |
| ------------------------ | --------------------------------------- | ----------------------------- | ------------------------------ |
| Business (authenticated) | Unlimited                               | Unlimited                     | Unlimited                      |
| Team (authenticated)     | Unlimited                               | Unlimited                     | Unlimited                      |
| Pro (authenticated)      | Unlimited                               | Unlimited                     | Unlimited                      |
| Personal (authenticated) | 200                                     | Unlimited                     | Up to 1                        |
| Unauthenticated users    | 100 per IPv4 address or IPv6 /64 subnet | Not applicable                | Not applicable                 |

For more details, see [Pull usage and limits](https://docs.docker.com/docker-hub/usage/pulls/).

## [Fair use](#fair-use)

When utilizing the Docker Platform, users should be aware that excessive data transfer, pull rates, or data storage can lead to throttling, or additional charges. To ensure fair resource usage and maintain service quality, we reserve the right to impose restrictions or apply additional charges to accounts exhibiting excessive data and storage consumption.

### [Abuse rate limit](#abuse-rate-limit)

Docker Hub has an abuse rate limit to protect the application and infrastructure. This limit applies to all requests to Hub properties including web pages, APIs, and image pulls. The limit is applied per IPv4 address or per IPv6 /64 subnet, and while the limit changes over time depending on load and other factors, it's in the order of thousands of requests per minute. The abuse limit applies to all users equally regardless of account level.

You can differentiate between the pull rate limit and abuse rate limit by looking at the error code. The abuse limit returns a simple `429 Too Many Requests` response. The pull limit returns a longer error message that includes a link to documentation.

----
url: https://docs.docker.com/reference/api/extensions-sdk/ExtensionVM/
----

# Interface: ExtensionVM

***

Table of contents

***

**`Since`**

0.2.0

## [Properties](#properties)

### [cli](#cli)

• `Readonly` **cli**: [`ExtensionCli`](https://docs.docker.com/reference/api/extensions-sdk/ExtensionCli/)

Executes a command in the backend container.

Example: Execute the command `ls -l` inside the backend container:

```typescript
await ddClient.extension.vm.cli.exec(
  "ls",
  ["-l"]
);
```

Streams the output of the command executed in the backend container.

When the extension defines its own `compose.yaml` file with multiple containers, the command is executed on the first container defined. Change the order in which containers are defined to execute commands on another container.

Example: Spawn the command `ls -l` inside the backend container:

```typescript
await ddClient.extension.vm.cli.exec("ls", ["-l"], {
           stream: {
             onOutput(data): void {
                 // As we can receive both `stdout` and `stderr`, we wrap them in a JSON object
                 JSON.stringify(
                   {
                     stdout: data.stdout,
                     stderr: data.stderr,
                   },
                   null,
                   "  "
                 );
             },
             onError(error: any): void {
               console.error(error);
             },
             onClose(exitCode: number): void {
               console.log("onClose with exit code " + exitCode);
             },
           },
         });
```

**`Param`**

Command to execute.

**`Param`**

Arguments of the command to execute.

**`Param`**

The callback function where to listen from the command output data and errors.

***

### [service](#service)

• `Optional` `Readonly` **service**: [`HttpService`](https://docs.docker.com/reference/api/extensions-sdk/HttpService/)

----
url: https://docs.docker.com/dhi/migration/migrate-from-wolfi/
----

# Migrate from Wolfi

***

Table of contents

***

This guide helps you migrate from Wolfi-based images to Docker Hardened Images (DHI). Generally, the migration process is straightforward since Wolfi is Alpine-like and DHI provides an Alpine-based hardened image.

Like other hardened images, DHI provides comprehensive [attestations](/dhi/core-concepts/attestations/) including SBOMs and provenance, allowing you to [verify](https://docs.docker.com/dhi/how-to/verify/) image signatures and [scan](https://docs.docker.com/dhi/how-to/scan/) for vulnerabilities to ensure the security and integrity of your images.

## [Migration steps](#migration-steps)

The following example demonstrates how to migrate a Dockerfile from a Wolfi-based image to an Alpine-based Docker Hardened Image.

### [Step 1: Update the base image in your Dockerfile](#step-1-update-the-base-image-in-your-dockerfile)

Update the base image in your application's Dockerfile to a hardened image. This is typically going to be an image tagged as `dev` or `sdk` because it has the tools needed to install packages and dependencies.

The following example diff snippet from a Dockerfile shows the old base image replaced by the new hardened image.

> Note
>
> You must authenticate to `dhi.io` before you can pull Docker Hardened Images. Use your Docker ID credentials (the same username and password you use for Docker Hub). If you don't have a Docker account, [create one](https://docs.docker.com/accounts/create-account/) for free.
>
> Run `docker login dhi.io` to authenticate.

```diff
- ## Original base image
- FROM cgr.dev/chainguard/go:latest-dev

+ ## Updated to use hardened base image
+ FROM dhi.io/golang:1.25-alpine3.22-dev
```

Note that DHI does not have a `latest` tag in order to promote best practices around image versioning. Ensure that you specify the appropriate version tag for your image. To find the right tag, explore the available tags in the [DHI Catalog](https://hub.docker.com/hardened-images/catalog/).

### [Step 2: Update the runtime image in your Dockerfile](#step-2-update-the-runtime-image-in-your-dockerfile)

> Note
>
> Multi-stage builds are recommended to keep your final image minimal and secure. Single-stage builds are supported, but they include the full `dev` image and therefore result in a larger image with a broader attack surface.

To ensure that your final image is as minimal as possible, you should use a [multi-stage build](https://docs.docker.com/build/building/multi-stage/). All stages in your Dockerfile should use a hardened image. While intermediary stages will typically use images tagged as `dev` or `sdk`, your final runtime stage should use a runtime image.

Utilize the build stage to compile your application and copy the resulting artifacts to the final runtime stage. This ensures that your final image is minimal and secure.

The following example shows a multi-stage Dockerfile with a build stage and runtime stage:

```dockerfile
# Build stage
FROM dhi.io/golang:1.25-alpine3.22-dev AS builder
WORKDIR /app
COPY . .
RUN go build -o myapp

# Runtime stage
FROM dhi.io/golang:1.25-alpine3.22
WORKDIR /app
COPY --from=builder /app/myapp .
ENTRYPOINT ["/app/myapp"]
```

After updating your Dockerfile, build and test your application. If you encounter issues, see the [Troubleshoot](https://docs.docker.com/dhi/troubleshoot/) guide for common problems and solutions.

## [Language-specific examples](#language-specific-examples)

See the examples section for language-specific migration examples:

* [Go](https://docs.docker.com/dhi/migration/examples/go/)
* [Python](https://docs.docker.com/dhi/migration/examples/python/)
* [Node.js](https://docs.docker.com/dhi/migration/examples/node/)

----
url: https://docs.docker.com/docker-hub/image-library/
----

# Content library

***

***

Docker Hub's content library is the world's largest collection of container images, extensions, and plugins. It provides a central location to discover pre-built images and tools designed to streamline your container workflows, making it easier to share and collaborate.

In this section, learn about:

* [Search](https://docs.docker.com/docker-hub/image-library/search/): Discover how to browse and search Docker Hub's extensive resources.
* [Trusted content](https://docs.docker.com/docker-hub/image-library/trusted-content/): Dive into Docker Hardened Images, Docker Official Images, Verified Publisher content, and Sponsored Open Source images, all vetted for security and reliability to streamline your workflows.
* [Catalogs](https://docs.docker.com/docker-hub/image-library/catalogs/): Explore specialized collections like the generative AI catalogs.
* [Mirroring](https://docs.docker.com/docker-hub/image-library/mirror/): Learn how to create a mirror of Docker Hub's container image library as a pull-through cache.

----
url: https://docs.docker.com/engine/swarm/services/
----

# Deploy services to a swarm

***

Table of contents

***

Swarm services use a declarative model, which means that you define the desired state of the service, and rely upon Docker to maintain this state. The state includes information such as (but not limited to):

* The image name and tag the service containers should run
* How many containers participate in the service
* Whether any ports are exposed to clients outside the swarm
* Whether the service should start automatically when Docker starts
* The specific behavior that happens when the service is restarted (such as whether a rolling restart is used)
* Characteristics of the nodes where the service can run (such as resource constraints and placement preferences)

For an overview of Swarm mode, see [Swarm mode key concepts](https://docs.docker.com/engine/swarm/key-concepts/). For an overview of how services work, see [How services work](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/).

## [Create a service](#create-a-service)

To create a single-replica service with no extra configuration, you only need to supply the image name. This command starts an Nginx service with a randomly-generated name and no published ports. This is a naive example, since you can't interact with the Nginx service.

```console
$ docker service create nginx
```

The service is scheduled on an available node. To confirm that the service was created and started successfully, use the `docker service ls` command:

```console
$ docker service ls

ID                  NAME                MODE                REPLICAS            IMAGE                                                                                             PORTS
a3iixnklxuem        quizzical_lamarr    replicated          1/1                 docker.io/library/nginx@sha256:41ad9967ea448d7c2b203c699b429abe1ed5af331cd92533900c6d77490e0268
```

Created services do not always run right away. A service can be in a pending state if its image is unavailable, if no node meets the requirements you configure for the service, or for other reasons. See [Pending services](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/#pending-services) for more information.

To provide a name for your service, use the `--name` flag:

```console
$ docker service create --name my_web nginx
```

Just like with standalone containers, you can specify a command that the service's containers should run, by adding it after the image name. This example starts a service called `helloworld` which uses an `alpine` image and runs the command `ping docker.com`:

```console
$ docker service create --name helloworld alpine ping docker.com
```

You can also specify an image tag for the service to use. This example modifies the previous one to use the `alpine:3.6` tag:

```console
$ docker service create --name helloworld alpine:3.6 ping docker.com
```

For more details about image tag resolution, see [Specify the image version the service should use](#specify-the-image-version-a-service-should-use).

### [gMSA for Swarm](#gmsa-for-swarm)

> Note
>
> This example only works for a Windows container.

Swarm now allows using a Docker config as a gMSA credential spec - a requirement for Active Directory-authenticated applications. This reduces the burden of distributing credential specs to the nodes they're used on.

The following example assumes a gMSA and its credential spec (called credspec.json) already exists, and that the nodes being deployed to are correctly configured for the gMSA.

To use a config as a credential spec, first create the Docker config containing the credential spec:

```console
$ docker config create credspec credspec.json
```

Now, you should have a Docker config named credspec, and you can create a service using this credential spec. To do so, use the --credential-spec flag with the config name, like this:

```console
$ docker service create --credential-spec="config://credspec" <your image>
```

Your service uses the gMSA credential spec when it starts, but unlike a typical Docker config (used by passing the --config flag), the credential spec is not mounted into the container.

### [Create a service using an image on a private registry](#create-a-service-using-an-image-on-a-private-registry)

If your image is available on a private registry which requires login, use the `--with-registry-auth` flag with `docker service create`, after logging in. If your image is stored on `registry.example.com`, which is a private registry, use a command like the following:

```console
$ docker login registry.example.com

$ docker service  create \
  --with-registry-auth \
  --name my_service \
  registry.example.com/acme/my_image:latest
```

This passes the login token from your local client to the swarm nodes where the service is deployed, using the encrypted WAL logs. With this information, the nodes are able to log into the registry and pull the image.

### [Provide credential specs for managed service accounts](#provide-credential-specs-for-managed-service-accounts)

In Enterprise Edition 3.0, security is improved through the centralized distribution and management of Group Managed Service Account(gMSA) credentials using Docker config functionality. Swarm now allows using a Docker config as a gMSA credential spec, which reduces the burden of distributing credential specs to the nodes on which they are used.

> Note
>
> This option is only applicable to services using Windows containers.

Credential spec files are applied at runtime, eliminating the need for host-based credential spec files or registry entries - no gMSA credentials are written to disk on worker nodes. You can make credential specs available to Docker Engine running swarm kit worker nodes before a container starts. When deploying a service using a gMSA-based config, the credential spec is passed directly to the runtime of containers in that service.

The `--credential-spec` must be in one of the following formats:

* `file://<filename>`: The referenced file must be present in the `CredentialSpecs` subdirectory in the docker data directory, which defaults to `C:\ProgramData\Docker\` on Windows. For example, specifying `file://spec.json` loads `C:\ProgramData\Docker\CredentialSpecs\spec.json`.
* `registry://<value-name>`: The credential spec is read from the Windows registry on the daemon’s host.
* `config://<config-name>`: The config name is automatically converted to the config ID in the CLI. The credential spec contained in the specified `config` is used.

The following simple example retrieves the gMSA name and JSON contents from your Active Directory (AD) instance:

```console
$ name="mygmsa"
$ contents="{...}"
$ echo $contents > contents.json
```

Make sure that the nodes to which you are deploying are correctly configured for the gMSA.

To use a config as a credential spec, create a Docker config in a credential spec file named `credpspec.json`. You can specify any name for the name of the `config`.

```console
$ docker config create --label com.docker.gmsa.name=mygmsa credspec credspec.json
```

Now you can create a service using this credential spec. Specify the `--credential-spec` flag with the config name:

```console
$ docker service create --credential-spec="config://credspec" <your image>
```

Your service uses the gMSA credential spec when it starts, but unlike a typical Docker config (used by passing the --config flag), the credential spec is not mounted into the container.

## [Update a service](#update-a-service)

You can change almost everything about an existing service using the `docker service update` command. When you update a service, Docker stops its containers and restarts them with the new configuration.

Since Nginx is a web service, it works much better if you publish port 80 to clients outside the swarm. You can specify this when you create the service, using the `-p` or `--publish` flag. When updating an existing service, the flag is `--publish-add`. There is also a `--publish-rm` flag to remove a port that was previously published.

Assuming that the `my_web` service from the previous section still exists, use the following command to update it to publish port 80.

```console
$ docker service update --publish-add 80 my_web
```

To verify that it worked, use `docker service ls`:

```console
$ docker service ls

ID                  NAME                MODE                REPLICAS            IMAGE                                                                                             PORTS
4nhxl7oxw5vz        my_web              replicated          1/1                 docker.io/library/nginx@sha256:41ad9967ea448d7c2b203c699b429abe1ed5af331cd92533900c6d77490e0268   *:0->80/tcp
```

For more information on how publishing ports works, see [publish ports](#publish-ports).

You can update almost every configuration detail about an existing service, including the image name and tag it runs. See [Update a service's image after creation](#update-a-services-image-after-creation).

## [Remove a service](#remove-a-service)

To remove a service, use the `docker service remove` command. You can remove a service by its ID or name, as shown in the output of the `docker service ls` command. The following command removes the `my_web` service.

```console
$ docker service remove my_web
```

## [Service configuration details](#service-configuration-details)

The following sections provide details about service configuration. This topic does not cover every flag or scenario. In almost every instance where you can define a configuration at service creation, you can also update an existing service's configuration in a similar way.

See the command-line references for [`docker service create`](/reference/cli/docker/service/create/) and [`docker service update`](/reference/cli/docker/service/update/), or run one of those commands with the `--help` flag.

### [Configure the runtime environment](#configure-the-runtime-environment)

You can configure the following options for the runtime environment in the container:

* Environment variables using the `--env` flag
* The working directory inside the container using the `--workdir` flag
* The username or UID using the `--user` flag

The following service's containers have an environment variable `$MYVAR` set to `myvalue`, run from the `/tmp/` directory, and run as the `my_user` user.

```console
$ docker service create --name helloworld \
  --env MYVAR=myvalue \
  --workdir /tmp \
  --user my_user \
  alpine ping docker.com
```

### [Update the command an existing service runs](#update-the-command-an-existing-service-runs)

To update the command an existing service runs, you can use the `--args` flag. The following example updates an existing service called `helloworld` so that it runs the command `ping docker.com` instead of whatever command it was running before:

```console
$ docker service update --args "ping docker.com" helloworld
```

### [Specify the image version a service should use](#specify-the-image-version-a-service-should-use)

When you create a service without specifying any details about the version of the image to use, the service uses the version tagged with the `latest` tag. You can force the service to use a specific version of the image in a few different ways, depending on your desired outcome.

An image version can be expressed in several different ways:

* If you specify a tag, the manager (or the Docker client, if you use [content trust](https://docs.docker.com/engine/security/trust/)) resolves that tag to a digest. When the request to create a container task is received on a worker node, the worker node only sees the digest, not the tag.

  ```console
  $ docker service create --name="myservice" ubuntu:16.04
  ```

  Some tags represent discrete releases, such as `ubuntu:16.04`. Tags like this almost always resolve to a stable digest over time. It is recommended that you use this kind of tag when possible.

  Other types of tags, such as `latest` or `nightly`, may resolve to a new digest often, depending on how often an image's author updates the tag. It is not recommended to run services using a tag which is updated frequently, to prevent different service replica tasks from using different image versions.

* If you don't specify a version at all, by convention the image's `latest` tag is resolved to a digest. Workers use the image at this digest when creating the service task.

  Thus, the following two commands are equivalent:

  ```console
  $ docker service create --name="myservice" ubuntu

  $ docker service create --name="myservice" ubuntu:latest
  ```

* If you specify a digest directly, that exact version of the image is always used when creating service tasks.

  ```console
  $ docker service create \
      --name="myservice" \
      ubuntu:16.04@sha256:35bc48a1ca97c3971611dc4662d08d131869daa692acb281c7e9e052924e38b1
  ```

When you create a service, the image's tag is resolved to the specific digest the tag points to **at the time of service creation**. Worker nodes for that service use that specific digest forever unless the service is explicitly updated. This feature is particularly important if you do use often-changing tags such as `latest`, because it ensures that all service tasks use the same version of the image.

> Note
>
> If [content trust](https://docs.docker.com/engine/security/trust/) is enabled, the client actually resolves the image's tag to a digest before contacting the swarm manager, to verify that the image is signed. Thus, if you use content trust, the swarm manager receives the request pre-resolved. In this case, if the client cannot resolve the image to a digest, the request fails.

If the manager can't resolve the tag to a digest, each worker node is responsible for resolving the tag to a digest, and different nodes may use different versions of the image. If this happens, a warning like the following is logged, substituting the placeholders for real information.

```text
unable to pin image <IMAGE-NAME> to digest: REASON
```

To see an image's current digest, issue the command `docker inspect <IMAGE>:<TAG>` and look for the `RepoDigests` line. The following is the current digest for `ubuntu:latest` at the time this content was written. The output is truncated for clarity.

```console
$ docker inspect ubuntu:latest
```

```json
"RepoDigests": [
    "ubuntu@sha256:35bc48a1ca97c3971611dc4662d08d131869daa692acb281c7e9e052924e38b1"
],
```

After you create a service, its image is never updated unless you explicitly run `docker service update` with the `--image` flag as described below. Other update operations such as scaling the service, adding or removing networks or volumes, renaming the service, or any other type of update operation do not update the service's image.

### [Update a service's image after creation](#update-a-services-image-after-creation)

Each tag represents a digest, similar to a Git hash. Some tags, such as `latest`, are updated often to point to a new digest. Others, such as `ubuntu:16.04`, represent a released software version and are not expected to update to point to a new digest often if at all. When you create a service, it is constrained to create tasks using a specific digest of an image until you update the service using `service update` with the `--image` flag.

When you run `service update` with the `--image` flag, the swarm manager queries Docker Hub or your private Docker registry for the digest the tag currently points to and updates the service tasks to use that digest.

> Note
>
> If you use [content trust](https://docs.docker.com/engine/security/trust/), the Docker client resolves image and the swarm manager receives the image and digest, rather than a tag.

Usually, the manager can resolve the tag to a new digest and the service updates, redeploying each task to use the new image. If the manager can't resolve the tag or some other problem occurs, the next two sections outline what to expect.

#### [If the manager resolves the tag](#if-the-manager-resolves-the-tag)

If the swarm manager can resolve the image tag to a digest, it instructs the worker nodes to redeploy the tasks and use the image at that digest.

* If a worker has cached the image at that digest, it uses it.

* If not, it attempts to pull the image from Docker Hub or the private registry.

  * If it succeeds, the task is deployed using the new image.

  * If the worker fails to pull the image, the service fails to deploy on that worker node. Docker tries again to deploy the task, possibly on a different worker node.

#### [If the manager cannot resolve the tag](#if-the-manager-cannot-resolve-the-tag)

If the swarm manager cannot resolve the image to a digest, all is not lost:

* The manager instructs the worker nodes to redeploy the tasks using the image at that tag.

* If the worker has a locally cached image that resolves to that tag, it uses that image.

* If the worker does not have a locally cached image that resolves to the tag, the worker tries to connect to Docker Hub or the private registry to pull the image at that tag.

  * If this succeeds, the worker uses that image.

  * If this fails, the task fails to deploy and the manager tries again to deploy the task, possibly on a different worker node.

### [Publish ports](#publish-ports)

When you create a swarm service, you can publish that service's ports to hosts outside the swarm in two ways:

* [You can rely on the routing mesh](#publish-a-services-ports-using-the-routing-mesh). When you publish a service port, the swarm makes the service accessible at the target port on every node, regardless of whether there is a task for the service running on that node or not. This is less complex and is the right choice for many types of services.

* [You can publish a service task's port directly on the swarm node](#publish-a-services-ports-directly-on-the-swarm-node) where that service is running. This bypasses the routing mesh and provides the maximum flexibility, including the ability for you to develop your own routing framework. However, you are responsible for keeping track of where each task is running and routing requests to the tasks, and load-balancing across the nodes.

Keep reading for more information and use cases for each of these methods.

#### [Publish a service's ports using the routing mesh](#publish-a-services-ports-using-the-routing-mesh)

To publish a service's ports externally to the swarm, use the `--publish <PUBLISHED-PORT>:<SERVICE-PORT>` flag. The swarm makes the service accessible at the published port on every swarm node. If an external host connects to that port on any swarm node, the routing mesh routes it to a task. The external host does not need to know the IP addresses or internally-used ports of the service tasks to interact with the service. When a user or process connects to a service, any worker node running a service task may respond. For more details about swarm service networking, see [Manage swarm service networks](https://docs.docker.com/engine/swarm/networking/).

##### [Example: Run a three-task Nginx service on 10-node swarm](#example-run-a-three-task-nginx-service-on-10-node-swarm)

Imagine that you have a 10-node swarm, and you deploy an Nginx service running three tasks on a 10-node swarm:

```console
$ docker service create --name my_web \
                        --replicas 3 \
                        --publish published=8080,target=80 \
                        nginx
```

Three tasks run on up to three nodes. You don't need to know which nodes are running the tasks; connecting to port 8080 on any of the 10 nodes connects you to one of the three `nginx` tasks. You can test this using `curl`. The following example assumes that `localhost` is one of the swarm nodes. If this is not the case, or `localhost` does not resolve to an IP address on your host, substitute the host's IP address or resolvable host name.

The HTML output is truncated:

```console
$ curl localhost:8080

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
...truncated...
</html>
```

Subsequent connections may be routed to the same swarm node or a different one.

#### [Publish a service's ports directly on the swarm node](#publish-a-services-ports-directly-on-the-swarm-node)

Using the routing mesh may not be the right choice for your application if you need to make routing decisions based on application state or you need total control of the process for routing requests to your service's tasks. To publish a service's port directly on the node where it is running, use the `mode=host` option to the `--publish` flag.

> Note
>
> If you publish a service's ports directly on the swarm node using `mode=host` and also set `published=<PORT>` this creates an implicit limitation that you can only run one task for that service on a given swarm node. You can work around this by specifying `published` without a port definition, which causes Docker to assign a random port for each task.
>
> In addition, if you use `mode=host` and you do not use the `--mode=global` flag on `docker service create`, it is difficult to know which nodes are running the service to route work to them.

##### [Example: Run an `nginx` web server service on every swarm node](#example-run-an-nginx-web-server-service-on-every-swarm-node)

[nginx](https://hub.docker.com/_/nginx/) is an open source reverse proxy, load balancer, HTTP cache, and a web server. If you run nginx as a service using the routing mesh, connecting to the nginx port on any swarm node shows you the web page for (effectively) a random swarm node running the service.

The following example runs nginx as a service on each node in your swarm and exposes nginx port locally on each swarm node.

```console
$ docker service create \
  --mode global \
  --publish mode=host,target=80,published=8080 \
  --name=nginx \
  nginx:latest
```

You can reach the nginx server on port 8080 of every swarm node. If you add a node to the swarm, a nginx task is started on it. You cannot start another service or container on any swarm node which binds to port 8080.

> Note
>
> This is a purely illustrative example. Creating an application-layer routing framework for a multi-tiered service is complex and out of scope for this topic.

### [Connect the service to an overlay network](#connect-the-service-to-an-overlay-network)

You can use overlay networks to connect one or more services within the swarm.

First, create overlay network on a manager node using the `docker network create` command with the `--driver overlay` flag.

```console
$ docker network create --driver overlay my-network
```

After you create an overlay network in swarm mode, all manager nodes have access to the network.

You can create a new service and pass the `--network` flag to attach the service to the overlay network:

```console
$ docker service create \
  --replicas 3 \
  --network my-network \
  --name my-web \
  nginx
```

The swarm extends `my-network` to each node running the service.

You can also connect an existing service to an overlay network using the `--network-add` flag.

```console
$ docker service update --network-add my-network my-web
```

To disconnect a running service from a network, use the `--network-rm` flag.

```console
$ docker service update --network-rm my-network my-web
```

For more information on overlay networking and service discovery, refer to [Attach services to an overlay network](https://docs.docker.com/engine/swarm/networking/) and [Docker swarm mode overlay network security model](https://docs.docker.com/engine/network/drivers/overlay/).

### [Grant a service access to secrets](#grant-a-service-access-to-secrets)

To create a service with access to Docker-managed secrets, use the `--secret` flag. For more information, see [Manage sensitive strings (secrets) for Docker services](https://docs.docker.com/engine/swarm/secrets/)

### [Customize a service's isolation mode](#customize-a-services-isolation-mode)

> Important
>
> This setting applies to Windows hosts only and is ignored for Linux hosts.

Docker allows you to specify a swarm service's isolation mode. The isolation mode can be one of the following:

* `default`: Use the default isolation mode configured for the Docker host, as configured by the `-exec-opt` flag or `exec-opts` array in `daemon.json`. If the daemon does not specify an isolation technology, `process` is the default for Windows Server, and `hyperv` is the default (and only) choice for Windows 10.

* `process`: Run the service tasks as a separate process on the host.

  > Note
  >
  > `process` isolation mode is only supported on Windows Server. Windows 10 only supports `hyperv` isolation mode.

* `hyperv`: Run the service tasks as isolated `hyperv` tasks. This increases overhead but provides more isolation.

You can specify the isolation mode when creating or updating a new service using the `--isolation` flag.

### [Control service placement](#control-service-placement)

Swarm services provide a few different ways for you to control scale and placement of services on different nodes.

* You can specify whether the service needs to run a specific number of replicas or should run globally on every worker node. See [Replicated or global services](#replicated-or-global-services).

* You can configure the service's [CPU or memory requirements](#reserve-memory-or-cpus-for-a-service), and the service only runs on nodes which can meet those requirements.

* [Placement constraints](#placement-constraints) let you configure the service to run only on nodes with specific (arbitrary) metadata set, and cause the deployment to fail if appropriate nodes do not exist. For instance, you can specify that your service should only run on nodes where an arbitrary label `pci_compliant` is set to `true`.

* [Placement preferences](#placement-preferences) let you apply an arbitrary label with a range of values to each node, and spread your service's tasks across those nodes using an algorithm. Currently, the only supported algorithm is `spread`, which tries to place them evenly. For instance, if you label each node with a label `rack` which has a value from 1-10, then specify a placement preference keyed on `rack`, then service tasks are placed as evenly as possible across all nodes with the label `rack`, after taking other placement constraints, placement preferences, and other node-specific limitations into account.

  Unlike constraints, placement preferences are best-effort, and a service does not fail to deploy if no nodes can satisfy the preference. If you specify a placement preference for a service, nodes that match that preference are ranked higher when the swarm managers decide which nodes should run the service tasks. Other factors, such as high availability of the service, also factor into which nodes are scheduled to run service tasks. For example, if you have N nodes with the rack label (and then some others), and your service is configured to run N+1 replicas, the +1 is scheduled on a node that doesn't already have the service on it if there is one, regardless of whether that node has the `rack` label or not.

#### [Replicated or global services](#replicated-or-global-services)

Swarm mode has two types of services: replicated and global. For replicated services, you specify the number of replica tasks for the swarm manager to schedule onto available nodes. For global services, the scheduler places one task on each available node that meets the service's [placement constraints](#placement-constraints) and [resource requirements](#reserve-memory-or-cpus-for-a-service).

You control the type of service using the `--mode` flag. If you don't specify a mode, the service defaults to `replicated`. For replicated services, you specify the number of replica tasks you want to start using the `--replicas` flag. For example, to start a replicated nginx service with 3 replica tasks:

```console
$ docker service create \
  --name my_web \
  --replicas 3 \
  nginx
```

To start a global service on each available node, pass `--mode global` to `docker service create`. Every time a new node becomes available, the scheduler places a task for the global service on the new node. For example to start a service that runs alpine on every node in the swarm:

```console
$ docker service create \
  --name myservice \
  --mode global \
  alpine top
```

Service constraints let you set criteria for a node to meet before the scheduler deploys a service to the node. You can apply constraints to the service based upon node attributes and metadata or engine metadata. For more information on constraints, refer to the `docker service create` [CLI reference](/reference/cli/docker/service/create/).

#### [Reserve memory or CPUs for a service](#reserve-memory-or-cpus-for-a-service)

To reserve a given amount of memory or number of CPUs for a service, use the `--reserve-memory` or `--reserve-cpu` flags. If no available nodes can satisfy the requirement (for instance, if you request 4 CPUs and no node in the swarm has 4 CPUs), the service remains in a pending state until an appropriate node is available to run its tasks.

##### [Out Of Memory Exceptions (OOME)](#out-of-memory-exceptions-oome)

If your service attempts to use more memory than the swarm node has available, you may experience an Out Of Memory Exception (OOME) and a container, or the Docker daemon, might be killed by the kernel OOM killer. To prevent this from happening, ensure that your application runs on hosts with adequate memory and see [Understand the risks of running out of memory](https://docs.docker.com/engine/containers/resource_constraints/#understand-the-risks-of-running-out-of-memory).

Swarm services allow you to use resource constraints, placement preferences, and labels to ensure that your service is deployed to the appropriate swarm nodes.

#### [Placement constraints](#placement-constraints)

Use placement constraints to control the nodes a service can be assigned to. In the following example, the service only runs on nodes with the [label](https://docs.docker.com/engine/swarm/manage-nodes/#add-or-remove-label-metadata) `region` set to `east`. If no appropriately-labelled nodes are available, tasks will wait in `Pending` until they become available. The `--constraint` flag uses an equality operator (`==` or `!=`). For replicated services, it is possible that all services run on the same node, or each node only runs one replica, or that some nodes don't run any replicas. For global services, the service runs on every node that meets the placement constraint and any [resource requirements](#reserve-memory-or-cpus-for-a-service).

```console
$ docker service create \
  --name my-nginx \
  --replicas 5 \
  --constraint node.labels.region==east \
  nginx
```

You can also use the `constraint` service-level key in a `compose.yaml` file.

If you specify multiple placement constraints, the service only deploys onto nodes where they are all met. The following example limits the service to run on all nodes where `region` is set to `east` and `type` is not set to `devel`:

```console
$ docker service create \
  --name my-nginx \
  --mode global \
  --constraint node.labels.region==east \
  --constraint node.labels.type!=devel \
  nginx
```

You can also use placement constraints in conjunction with placement preferences and CPU/memory constraints. Be careful not to use settings that are not possible to fulfill.

For more information on constraints, refer to the `docker service create` [CLI reference](/reference/cli/docker/service/create/).

#### [Placement preferences](#placement-preferences)

While [placement constraints](#placement-constraints) limit the nodes a service can run on, *placement preferences* try to place tasks on appropriate nodes in an algorithmic way (currently, only spread evenly). For instance, if you assign each node a `rack` label, you can set a placement preference to spread the service evenly across nodes with the `rack` label, by value. This way, if you lose a rack, the service is still running on nodes on other racks.

Placement preferences are not strictly enforced. If no node has the label you specify in your preference, the service is deployed as though the preference were not set.

> Note
>
> Placement preferences are ignored for global services.

The following example sets a preference to spread the deployment across nodes based on the value of the `datacenter` label. If some nodes have `datacenter=us-east` and others have `datacenter=us-west`, the service is deployed as evenly as possible across the two sets of nodes.

```console
$ docker service create \
  --replicas 9 \
  --name redis_2 \
  --placement-pref 'spread=node.labels.datacenter' \
  redis:7.4.0
```

> Note
>
> Nodes which are missing the label used to spread still receive task assignments. As a group, these nodes receive tasks in equal proportion to any of the other groups identified by a specific label value. In a sense, a missing label is the same as having the label with a null value attached to it. If the service should only run on nodes with the label being used for the spread preference, the preference should be combined with a constraint.

You can specify multiple placement preferences, and they are processed in the order they are encountered. The following example sets up a service with multiple placement preferences. Tasks are spread first over the various datacenters, and then over racks (as indicated by the respective labels):

```console
$ docker service create \
  --replicas 9 \
  --name redis_2 \
  --placement-pref 'spread=node.labels.datacenter' \
  --placement-pref 'spread=node.labels.rack' \
  redis:7.4.0
```

You can also use placement preferences in conjunction with placement constraints or CPU/memory constraints. Be careful not to use settings that are not possible to fulfill.

This diagram illustrates how placement preferences work:

When updating a service with `docker service update`, `--placement-pref-add` appends a new placement preference after all existing placement preferences. `--placement-pref-rm` removes an existing placement preference that matches the argument.

### [Configure a service's update behavior](#configure-a-services-update-behavior)

When you create a service, you can specify a rolling update behavior for how the swarm should apply changes to the service when you run `docker service update`. You can also specify these flags as part of the update, as arguments to `docker service update`.

The `--update-delay` flag configures the time delay between updates to a service task or sets of tasks. You can describe the time `T` as a combination of the number of seconds `Ts`, minutes `Tm`, or hours `Th`. So `10m30s` indicates a 10 minute 30 second delay.

By default the scheduler updates 1 task at a time. You can pass the `--update-parallelism` flag to configure the maximum number of service tasks that the scheduler updates simultaneously.

When an update to an individual task returns a state of `RUNNING`, the scheduler continues the update by continuing to another task until all tasks are updated. If at any time during an update a task returns `FAILED`, the scheduler pauses the update. You can control the behavior using the `--update-failure-action` flag for `docker service create` or `docker service update`.

In the example service below, the scheduler applies updates to a maximum of 2 replicas at a time. When an updated task returns either `RUNNING` or `FAILED`, the scheduler waits 10 seconds before stopping the next task to update:

```console
$ docker service create \
  --replicas 10 \
  --name my_web \
  --update-delay 10s \
  --update-parallelism 2 \
  --update-failure-action continue \
  alpine
```

The `--update-max-failure-ratio` flag controls what fraction of tasks can fail during an update before the update as a whole is considered to have failed. For example, with `--update-max-failure-ratio 0.1 --update-failure-action pause`, after 10% of the tasks being updated fail, the update is paused.

An individual task update is considered to have failed if the task doesn't start up, or if it stops running within the monitoring period specified with the `--update-monitor` flag. The default value for `--update-monitor` is 30 seconds, which means that a task failing in the first 30 seconds after it's started counts towards the service update failure threshold, and a failure after that is not counted.

### [Roll back to the previous version of a service](#roll-back-to-the-previous-version-of-a-service)

In case the updated version of a service doesn't function as expected, it's possible to manually roll back to the previous version of the service using `docker service update`'s `--rollback` flag. This reverts the service to the configuration that was in place before the most recent `docker service update` command.

Other options can be combined with `--rollback`; for example, `--update-delay 0s`, to execute the rollback without a delay between tasks:

```console
$ docker service update \
  --rollback \
  --update-delay 0s
  my_web
```

You can configure a service to roll back automatically if a service update fails to deploy. See [Automatically roll back if an update fails](#automatically-roll-back-if-an-update-fails).

Manual rollback is handled at the server side, which allows manually-initiated rollbacks to respect the new rollback parameters. Note that `--rollback` cannot be used in conjunction with other flags to `docker service update`.

### [Automatically roll back if an update fails](#automatically-roll-back-if-an-update-fails)

You can configure a service in such a way that if an update to the service causes redeployment to fail, the service can automatically roll back to the previous configuration. This helps protect service availability. You can set one or more of the following flags at service creation or update. If you do not set a value, the default is used.

| Flag                           | Default | Description                                                                                                                                                                                                                                                                                                             |
| ------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--rollback-delay`             | `0s`    | Amount of time to wait after rolling back a task before rolling back the next one. A value of `0` means to roll back the second task immediately after the first rolled-back task deploys.                                                                                                                              |
| `--rollback-failure-action`    | `pause` | When a task fails to roll back, whether to `pause` or `continue` trying to roll back other tasks.                                                                                                                                                                                                                       |
| `--rollback-max-failure-ratio` | `0`     | The failure rate to tolerate during a rollback, specified as a floating-point number between 0 and 1. For instance, given 5 tasks, a failure ratio of `.2` would tolerate one task failing to roll back. A value of `0` means no failure are tolerated, while a value of `1` means any number of failure are tolerated. |
| `--rollback-monitor`           | `5s`    | Duration after each task rollback to monitor for failure. If a task stops before this time period has elapsed, the rollback is considered to have failed.                                                                                                                                                               |
| `--rollback-parallelism`       | `1`     | The maximum number of tasks to roll back in parallel. By default, one task is rolled back at a time. A value of `0` causes all tasks to be rolled back in parallel.                                                                                                                                                     |

The following example configures a `redis` service to roll back automatically if a `docker service update` fails to deploy. Two tasks can be rolled back in parallel. Tasks are monitored for 20 seconds after rollback to be sure they do not exit, and a maximum failure ratio of 20% is tolerated. Default values are used for `--rollback-delay` and `--rollback-failure-action`.

```console
$ docker service create --name=my_redis \
                        --replicas=5 \
                        --rollback-parallelism=2 \
                        --rollback-monitor=20s \
                        --rollback-max-failure-ratio=.2 \
                        redis:latest
```

### [Give a service access to volumes or bind mounts](#give-a-service-access-to-volumes-or-bind-mounts)

For best performance and portability, you should avoid writing important data directly into a container's writable layer. You should instead use data volumes or bind mounts. This principle also applies to services.

You can create two types of mounts for services in a swarm, `volume` mounts or `bind` mounts. Regardless of which type of mount you use, configure it using the `--mount` flag when you create a service, or the `--mount-add` or `--mount-rm` flag when updating an existing service. The default is a data volume if you don't specify a type.

#### [Data volumes](#data-volumes)

Data volumes are storage that exist independently of a container. The lifecycle of data volumes under swarm services is similar to that under containers. Volumes outlive tasks and services, so their removal must be managed separately. Volumes can be created before deploying a service, or if they don't exist on a particular host when a task is scheduled there, they are created automatically according to the volume specification on the service.

To use existing data volumes with a service use the `--mount` flag:

```console
$ docker service create \
  --mount src=<VOLUME-NAME>,dst=<CONTAINER-PATH> \
  --name myservice \
  IMAGE
```

If a volume with the name `<VOLUME-NAME>` doesn't exist when a task is scheduled to a particular host, then one is created. The default volume driver is `local`. To use a different volume driver with this create-on-demand pattern, specify the driver and its options with the `--mount` flag:

```console
$ docker service create \
  --mount type=volume,src=<VOLUME-NAME>,dst=<CONTAINER-PATH>,volume-driver=DRIVER,volume-opt=<KEY0>=<VALUE0>,volume-opt=<KEY1>=<VALUE1>
  --name myservice \
  IMAGE
```

For more information on how to create data volumes and the use of volume drivers, see [Use volumes](https://docs.docker.com/engine/storage/volumes/).

#### [Bind mounts](#bind-mounts)

Bind mounts are file system paths from the host where the scheduler deploys the container for the task. Docker mounts the path into the container. The file system path must exist before the swarm initializes the container for the task.

The following examples show bind mount syntax:

* To mount a read-write bind:

  ```console
  $ docker service create \
    --mount type=bind,src=<HOST-PATH>,dst=<CONTAINER-PATH> \
    --name myservice \
    IMAGE
  ```

* To mount a read-only bind:

  ```console
  $ docker service create \
    --mount type=bind,src=<HOST-PATH>,dst=<CONTAINER-PATH>,readonly \
    --name myservice \
    IMAGE
  ```

> Important
>
> Bind mounts can be useful but they can also cause problems. In most cases, it is recommended that you architect your application such that mounting paths from the host is unnecessary. The main risks include the following:
>
> * If you bind mount a host path into your service’s containers, the path must exist on every swarm node. The Docker swarm mode scheduler can schedule containers on any machine that meets resource availability requirements and satisfies all constraints and placement preferences you specify.
>
> * The Docker swarm mode scheduler may reschedule your running service containers at any time if they become unhealthy or unreachable.
>
> * Host bind mounts are non-portable. When you use bind mounts, there is no guarantee that your application runs the same way in development as it does in production.

### [Create services using templates](#create-services-using-templates)

You can use templates for some flags of `service create`, using the syntax provided by the Go's [text/template](https://golang.org/pkg/text/template/) package.

The following flags are supported:

* `--hostname`
* `--mount`
* `--env`

Valid placeholders for the Go template are:

| Placeholder       | Description    |
| ----------------- | -------------- |
| `.Service.ID`     | Service ID     |
| `.Service.Name`   | Service name   |
| `.Service.Labels` | Service labels |
| `.Node.ID`        | Node ID        |
| `.Node.Hostname`  | Node hostname  |
| `.Task.Name`      | Task name      |
| `.Task.Slot`      | Task slot      |

#### [Template example](#template-example)

This example sets the template of the created containers based on the service's name and the ID of the node where the container is running:

```console
$ docker service create --name hosttempl \
                        --hostname="{{.Node.ID}}-{{.Service.Name}}"\
                         busybox top
```

To see the result of using the template, use the `docker service ps` and `docker inspect` commands.

```console
$ docker service ps va8ew30grofhjoychbr6iot8c

ID            NAME         IMAGE                                                                                   NODE          DESIRED STATE  CURRENT STATE               ERROR  PORTS
wo41w8hg8qan  hosttempl.1  busybox:latest@sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912  2e7a8a9c4da2  Running        Running about a minute ago
```

```console
$ docker inspect --format="{{.Config.Hostname}}" hosttempl.1.wo41w8hg8qanxwjwsg4kxpprj
```

## [Learn More](#learn-more)

* [Swarm administration guide](https://docs.docker.com/engine/swarm/admin_guide/)
* [Docker Engine command line reference](/reference/cli/docker/)

----
url: https://docs.docker.com/extensions/
----

# Docker Extensions

***

Table of contents

***

Docker Extensions let you use third-party tools within Docker Desktop to extend its functionality.

You can seamlessly connect your favorite development tools to your application development and deployment workflows. Augment Docker Desktop with debugging, testing, security, and networking functionalities, and create custom add-ons using the Extensions [SDK](https://docs.docker.com/extensions/extensions-sdk/).

Anyone can use Docker Extensions and there is no limit to the number of extensions you can install.

## [What extensions are available?](#what-extensions-are-available)

There is a mix of partner and community-built extensions and Docker-built extensions. You can explore the list of available extensions in [Docker Hub](https://hub.docker.com/search?q=\&type=extension) or in the Extensions Marketplace within Docker Desktop.

## [Security and trust](#security-and-trust)

Docker Extensions run with elevated privileges on your host machine. They have direct access to the Docker Engine, can read and write files on your filesystem, and can install and run native binaries.

Docker reviews extensions submitted to the Marketplace, but does not guarantee the security of any extension. Extensions installed outside the Marketplace have not been reviewed at all. Only install extensions from publishers you trust.

If you're an organization admin, see [Configure a private marketplace](https://docs.docker.com/extensions/private-marketplace/) to control which extensions your team can install.

----
url: https://docs.docker.com/guides/golang/run-containers/
----

# Run your Go image as a container

***

Table of contents

***

## [Prerequisites](#prerequisites)

Work through the steps to containerize a Go application in [Build your Go image](https://docs.docker.com/guides/golang/build-images/).

## [Overview](#overview)

In the previous module you created a `Dockerfile` for your example application and then you created your Docker image using the command `docker build`. Now that you have the image, you can run that image and see if your application is running correctly.

A container is a normal operating system process except that this process is isolated and has its own file system, its own networking, and its own isolated process tree separate from the host.

To run an image inside of a container, you use the `docker run` command. It requires one parameter and that's the image name. Start your image and make sure it's running correctly. Run the following command in your terminal.

```console
$ docker run docker-gs-ping
```

```text
   ____    __
  / __/___/ /  ___
 / _// __/ _ \/ _ \
/___/\__/_//_/\___/ v4.10.2
High performance, minimalist Go web framework
https://echo.labstack.com
____________________________________O/_______
                                    O\
⇨ http server started on [::]:8080
```

When you run this command, you’ll notice that you weren't returned to the command prompt. This is because your application is a REST server and will run in a loop waiting for incoming requests without returning control back to the OS until you stop the container.

Make a GET request to the server using the curl command.

```console
$ curl http://localhost:8080/
curl: (7) Failed to connect to localhost port 8080: Connection refused
```

Your curl command failed because the connection to your server was refused. Meaning that you weren't able to connect to localhost on port 8080. This is expected because your container is running in isolation which includes networking. Stop the container and restart with port 8080 published on your local network.

To stop the container, press ctrl-c. This will return you to the terminal prompt.

To publish a port for your container, you’ll use the `--publish` flag (`-p` for short) on the `docker run` command. The format of the `--publish` command is `[host_port]:[container_port]`. So if you wanted to expose port `8080` inside the container to port `3000` outside the container, you would pass `3000:8080` to the `--publish` flag.

Start the container and expose port `8080` to port `8080` on the host.

```console
$ docker run --publish 8080:8080 docker-gs-ping
```

Now, rerun the curl command.

```console
$ curl http://localhost:8080/
Hello, Docker! <3
```

Success! You were able to connect to the application running inside of your container on port 8080. Switch back to the terminal where your container is running and you should see the `GET` request logged to the console.

Press `ctrl-c` to stop the container.

## [Run in detached mode](#run-in-detached-mode)

This is great so far, but your sample application is a web server and you shouldn't have to have your terminal connected to the container. Docker can run your container in detached mode in the background. To do this, you can use the `--detach` or `-d` for short. Docker will start your container the same as before but this time will detach from the container and return you to the terminal prompt.

```console
$ docker run -d -p 8080:8080 docker-gs-ping
d75e61fcad1e0c0eca69a3f767be6ba28a66625ce4dc42201a8a323e8313c14e
```

Docker started your container in the background and printed the container ID on the terminal.

Again, make sure that your container is running. Run the same `curl` command:

```console
$ curl http://localhost:8080/
Hello, Docker! <3
```

## [List containers](#list-containers)

Since you ran your container in the background, how do you know if your container is running or what other containers are running on your machine? Well, to see a list of containers running on your machine, run `docker ps`. This is similar to how the ps command is used to see a list of processes on a Linux machine.

```console
$ docker ps

CONTAINER ID   IMAGE            COMMAND             CREATED          STATUS          PORTS                    NAMES
d75e61fcad1e   docker-gs-ping   "/docker-gs-ping"   41 seconds ago   Up 40 seconds   0.0.0.0:8080->8080/tcp   inspiring_ishizaka
```

The `ps` command tells you a bunch of stuff about your running containers. You can see the container ID, the image running inside the container, the command that was used to start the container, when it was created, the status, ports that are exposed, and the names of the container.

You are probably wondering where the name of your container is coming from. Since you didn’t provide a name for the container when you started it, Docker generated a random name. You'll fix this in a minute but first you need to stop the container. To stop the container, run the `docker stop` command, passing the container's name or ID.

```console
$ docker stop inspiring_ishizaka
inspiring_ishizaka
```

Now rerun the `docker ps` command to see a list of running containers.

```console
$ docker ps

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES
```

## [Stop, start, and name containers](#stop-start-and-name-containers)

Docker containers can be started, stopped and restarted. When you stop a container, it's not removed but the status is changed to stopped and the process inside of the container is stopped. When you ran the `docker ps` command, the default output is to only show running containers. If you pass the `--all` or `-a` for short, you will see all containers on your system, including stopped containers and running containers.

```console
$ docker ps --all

CONTAINER ID   IMAGE            COMMAND                  CREATED              STATUS                      PORTS     NAMES
d75e61fcad1e   docker-gs-ping   "/docker-gs-ping"        About a minute ago   Exited (2) 23 seconds ago             inspiring_ishizaka
f65dbbb9a548   docker-gs-ping   "/docker-gs-ping"        3 minutes ago        Exited (2) 2 minutes ago              wizardly_joliot
aade1bf3d330   docker-gs-ping   "/docker-gs-ping"        3 minutes ago        Exited (2) 3 minutes ago              magical_carson
52d5ce3c15f0   docker-gs-ping   "/docker-gs-ping"        9 minutes ago        Exited (2) 3 minutes ago              gifted_mestorf
```

If you’ve been following along, you should see several containers listed. These are containers that you started and stopped but haven't removed yet.

Restart the container that you have just stopped. Locate the name of the container and replace the name of the container in the following `restart` command:

```console
$ docker restart inspiring_ishizaka
```

Now, list all the containers again using the `ps` command:

```console
$ docker ps -a

CONTAINER ID   IMAGE            COMMAND                  CREATED          STATUS                     PORTS                    NAMES
d75e61fcad1e   docker-gs-ping   "/docker-gs-ping"        2 minutes ago    Up 5 seconds               0.0.0.0:8080->8080/tcp   inspiring_ishizaka
f65dbbb9a548   docker-gs-ping   "/docker-gs-ping"        4 minutes ago    Exited (2) 2 minutes ago                            wizardly_joliot
aade1bf3d330   docker-gs-ping   "/docker-gs-ping"        4 minutes ago    Exited (2) 4 minutes ago                            magical_carson
52d5ce3c15f0   docker-gs-ping   "/docker-gs-ping"        10 minutes ago   Exited (2) 4 minutes ago                            gifted_mestorf
```

Notice that the container you just restarted has been started in detached mode and has port `8080` exposed. Also, note that the status of the container is `Up X seconds`. When you restart a container, it will be started with the same flags or commands that it was originally started with.

Stop and remove all of your containers and take a look at fixing the random naming issue.

Stop the container you just started. Find the name of your running container and replace the name in the following command with the name of the container on your system:

```console
$ docker stop inspiring_ishizaka
inspiring_ishizaka
```

Now that all of your containers are stopped, remove them. When a container is removed, it's no longer running nor is it in the stopped state. Instead, the process inside the container is terminated and the metadata for the container is removed.

To remove a container, run the `docker rm` command passing the container name. You can pass multiple container names to the command in one command.

Again, make sure you replace the containers names in the following command with the container names from your system:

```console
$ docker rm inspiring_ishizaka wizardly_joliot magical_carson gifted_mestorf

inspiring_ishizaka
wizardly_joliot
magical_carson
gifted_mestorf
```

Run the `docker ps --all` command again to verify that all containers are gone.

Now, address the pesky random name issue. Standard practice is to name your containers for the simple reason that it's easier to identify what's running in the container and what application or service it's associated with. Just like good naming conventions for variables in your code makes it simpler to read. So goes naming your containers.

To name a container, you must pass the `--name` flag to the `run` command:

```console
$ docker run -d -p 8080:8080 --name rest-server docker-gs-ping
3bbc6a3102ea368c8b966e1878a5ea9b1fc61187afaac1276c41db22e4b7f48f
```

```console
$ docker ps

CONTAINER ID   IMAGE            COMMAND             CREATED          STATUS          PORTS                    NAMES
3bbc6a3102ea   docker-gs-ping   "/docker-gs-ping"   25 seconds ago   Up 24 seconds   0.0.0.0:8080->8080/tcp   rest-server
```

Now, you can easily identify your container based on the name.

## [Next steps](#next-steps)

In this module, you learned how to run containers and publish ports. You also learned to manage the lifecycle of containers. You then learned the importance of naming your containers so that they're more easily identifiable. In the next module, you’ll learn how to run a database in a container and connect it to your application.

[Use containers for Go development »](https://docs.docker.com/guides/golang/develop/)

----
url: https://docs.docker.com/docker-hub/repos/manage/trusted-content/dvp-program/
----

# Docker Verified Publisher Program

***

Table of contents

***

[The Docker Verified Publisher Program](https://hub.docker.com/search?badges=verified_publisher) provides high-quality images from commercial publishers verified by Docker.

These images help development teams build secure software supply chains, minimizing exposure to malicious content early in the process to save time and money later.

## [Who's eligible to become a verified publisher?](#whos-eligible-to-become-a-verified-publisher)

Any independent software vendor who distributes software on Docker Hub can join the Verified Publisher Program. Find out more by heading to the [Docker Verified Publisher Program](https://www.docker.com/partners/programs) page.

> Note
>
> DVP entitlements are applied per namespace (organization). If you operate multiple Docker Hub namespaces, each requires a separate DVP application and verification process.

## [Program benefits](#program-benefits)

The Docker Verified Publisher Program (DVP) provides several features and benefits to Docker Hub publishers. The program grants the following perks based on participation tier:

* [Enterprise-grade infrastructure](#enterprise-grade-infrastructure): High availability hosting with 99.9% uptime
* [Verified publisher badge](#verified-publisher-badge): Special badge identifying high-quality commercial publishers
* [Repository logo](#repository-logo): Upload custom logos for individual repositories
* [Insights and analytics](#insights-and-analytics): Detailed usage metrics and community engagement data
* [Vulnerability analysis](#vulnerability-analysis): Automated security scanning with Docker Scout
* [Priority search ranking](#priority-search-ranking): Enhanced discoverability in Docker Hub search results
* [Co-marketing opportunities](#co-marketing-opportunities): Joint promotional activities with Docker

### [Enterprise-grade infrastructure](#enterprise-grade-infrastructure)

The Docker Verified Publisher Program runs on Docker Hub's enterprise-scale infrastructure, serving millions of developers globally. Your published content benefits from:

* High availability and uptime: Docker's systems are designed for failover across multiple availability zones, with load-balanced autoscaling, enabling 99.9% uptime.
* Global delivery and fast downloads: Docker leverages a global CDN and caching infrastructure to achieve cache hit ratios more than 99%, reducing reliance on origin traffic and ensuring fast access for developers everywhere.
* Durability: Docker maintains a documented backup policy and performs full daily backups of production data.

You simply push your images to Docker Hub as usual, and Docker takes care of the rest, serving your image to millions of developers worldwide.

To learn more, see [Availability at Docker](https://www.docker.com/trust/availability/).

### [Verified publisher badge](#verified-publisher-badge)

Images that are part of this program have a special badge on Docker Hub making it easier for users to identify projects that Docker has verified as high-quality commercial publishers.

### [Repository logo](#repository-logo)

DVP organizations can upload custom images for individual repositories on Docker Hub. This lets you override the default organization-level logo on a per-repository basis.

To manage the repository logo, see [Manage repository logo](#manage-repository-logo).

### [Vulnerability analysis](#vulnerability-analysis)

[Docker Scout](/scout/) provides automatic vulnerability analysis for DVP images published to Docker Hub. Scanning images ensures that the published content is secure, and proves to developers that they can trust the image.

You can enable analysis on a per-repository basis. For more about using this feature, see [Basic vulnerability scanning](/docker-hub/repos/manage/vulnerability-scanning/).

### [Priority search ranking](#priority-search-ranking)

Verified publisher images receive enhanced visibility in Docker Hub search results, making it easier for developers to discover your content. This improved discoverability helps drive adoption of your images within the developer community.

### [Co-marketing opportunities](#co-marketing-opportunities)

Docker collaborates with verified publishers on joint marketing initiatives, including blog posts, case studies, webinars, and conference presentations. These opportunities help amplify your brand visibility within the Docker ecosystem.

### [Insights and analytics](#insights-and-analytics)

The insights and analytics service provides usage metrics for how the community uses Docker images, granting insight into user behavior.

There is both a [web interface](https://docs.docker.com/docker-hub/repos/manage/trusted-content/insights-analytics/) and an [API](/reference/api/dvp/latest/) for accessing the analytics data.

The usage metrics show the number of image pulls by tag or by digest, geolocation, cloud provider, client, and more.

## [Manage repository logo](#manage-repository-logo)

After joining the Docker Verified Publisher Program, you can set a custom logo for each repository in your organization. The following requirements apply:

* The supported filetypes for the logo image are JPEG and PNG.
* The minimum allowed image size in pixels is 120×120.
* The maximum allowed image size in pixels is 1000×1000.
* The maximum allowed image file size is 5MB.

Only a user with an owner or editor role for the organization can change the repository logo.

### [Set the repository logo](#set-the-repository-logo)

1. Sign in to [Docker Hub](https://hub.docker.com).
2. Go to the page of the repository that you want to change the logo for.
3. Select the upload logo button, represented by a camera icon ( ) overlaying the current repository logo.
4. In the dialog that opens, select the PNG image that you want to upload to set it as the logo for the repository.

### [Remove the logo](#remove-the-logo)

Select the **Clear** button ( ) to remove a logo.

Removing the logo makes the repository default to using the organization logo, if set, or the following default logo if not.

----
url: https://docs.docker.com/reference/cli/sbx/create/claude/
----

# sbx create claude

| Description | Create a sandbox for claude                |
| ----------- | ------------------------------------------ |
| Usage       | `sbx create claude PATH [PATH...] [flags]` |

## [Description](#description)

Create a sandbox with access to a host workspace for claude.

The workspace path is required and will be mounted inside the sandbox at the same path as on the host. Additional workspaces can be provided as extra arguments. Append ":ro" to mount them read-only.

Use "sbx run SANDBOX" to attach to the agent after creation.

## [Global options](#global-options)

| Option           | Default | Description                                                                                                                                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--clone`        |         | Run the agent on a private in-container clone of the host Git repository (mounted read-only) instead of bind-mounting the workspace; the agent's commits are accessible via the sandbox-\<name> git remote on the host |
| `--cpus`         | `0`     | Number of CPUs to allocate to the sandbox (0 = auto: N-1 host CPUs, min 1)                                                                                                                                             |
| `-D, --debug`    |         | Enable debug logging                                                                                                                                                                                                   |
| `--kit`          |         | Kit reference (directory, ZIP, or OCI). Can be specified multiple times                                                                                                                                                |
| `--mcp`          |         | MCP server name to enable (use 'all' for all registered servers). Can be specified multiple times                                                                                                                      |
| `-m, --memory`   |         | Memory limit in binary units (e.g., 1024m, 8g). Default: 50% of host memory, max 32 GiB                                                                                                                                |
| `--name`         |         | Name for the sandbox (default: \<agent>-\<workdir>, letters, numbers, hyphens, periods, plus signs and minus signs only)                                                                                               |
| `-q, --quiet`    |         | Suppress verbose output                                                                                                                                                                                                |
| `-t, --template` |         | Container image to use for the sandbox (default: agent-specific image)                                                                                                                                                 |

## [Examples](#examples)

```console
# Create in the current directory
sbx create claude .

# Create with a specific path
sbx create claude /path/to/project

# Create with additional read-only workspaces
sbx create claude . /path/to/docs:ro
```

----
url: https://docs.docker.com/docker-hub/repos/manage/webhooks/
----

# Webhooks

***

Table of contents

***

You can use webhooks to cause an action in another service in response to a push event in the repository. Webhooks are POST requests sent to a URL you define in Docker Hub.

## [Create a webhook](#create-a-webhook)

To create a webhook:

1. In your chosen repository, select the **Webhooks** tab.
2. Provide a name for the webhook.
3. Provide a destination webhook URL. This is where webhook POST requests are delivered. The URL must be 255 characters or fewer.
4. Select **Create**.

## [View webhook delivery history](#view-webhook-delivery-history)

To view the history of the webhook:

1. Hover over your webhook under the **Current Webhooks section**.
2. Select the **Menu options** icon.
3. Select **View History**.

You can then view the delivery history, and whether delivering the POST request was successful or not.

## [Example webhook payload](#example-webhook-payload)

Webhook payloads have the following JSON format:

```json
{
  "callback_url": "https://registry.hub.docker.com/u/svendowideit/testhook/hook/2141b5bi5i5b02bec211i4eeih0242eg11000a/",
  "push_data": {
    "pushed_at": 1417566161,
    "pusher": "trustedbuilder",
    "tag": "latest"
  },
  "repository": {
    "comment_count": 0,
    "date_created": 1417494799,
    "description": "",
    "dockerfile": "#\n# BUILD\u0009\u0009docker build -t svendowideit/apt-cacher .\n# RUN\u0009\u0009docker run -d -p 3142:3142 -name apt-cacher-run apt-cacher\n#\n# and then you can run containers with:\n# \u0009\u0009docker run -t -i -rm -e http_proxy http://192.168.1.2:3142/ debian bash\n#\nFROM\u0009\u0009ubuntu\n\n\nVOLUME\u0009\u0009[/var/cache/apt-cacher-ng]\nRUN\u0009\u0009apt-get update ; apt-get install -yq apt-cacher-ng\n\nEXPOSE \u0009\u00093142\nCMD\u0009\u0009chmod 777 /var/cache/apt-cacher-ng ; /etc/init.d/apt-cacher-ng start ; tail -f /var/log/apt-cacher-ng/*\n",
    "full_description": "Docker Hub based automated build from a GitHub repo",
    "is_official": false,
    "is_private": true,
    "is_trusted": true,
    "name": "testhook",
    "namespace": "svendowideit",
    "owner": "svendowideit",
    "repo_name": "svendowideit/testhook",
    "repo_url": "https://registry.hub.docker.com/u/svendowideit/testhook/",
    "star_count": 0,
    "status": "Active"
  }
}
```

> Note
>
> The `callback_url` field is a legacy field and is no longer supported.

----
url: https://docs.docker.com/build/ci/github-actions/build-summary/
----

# GitHub Actions build summary

***

Table of contents

***

Docker's GitHub Actions for building and pushing images generate a job summary for your build that outlines the execution and materials used:

* A summary showing the Dockerfile used, the build duration, and cache utilization
* Inputs for the build, such as build arguments, tags, labels, and build contexts
* For builds with [Bake](https://docs.docker.com/build/bake/), the full bake definition for the build

Job summaries for Docker builds appear automatically if you use the following versions of the [Build and push Docker images](https://github.com/marketplace/actions/build-and-push-docker-images) or [Docker Buildx Bake](https://github.com/marketplace/actions/docker-buildx-bake) GitHub Actions:

* `docker/build-push-action@v7`
* `docker/bake-action@v7`

To view the job summary, open the details page for the job in GitHub after the job has finished. The summary is available for both failed and successful builds. In the case of a failed build, the summary also displays the error message that caused the build to fail:

## [Import build records to Docker Desktop](#import-build-records-to-docker-desktop)

The job summary includes a link for downloading a build record archive for the run. The build record archive is a ZIP file containing the details about a build (or builds, if you use `docker/bake-action` to build multiple targets). You can import this build record archive into Docker Desktop, which gives you a powerful, graphical interface for further analyzing the build's performance via the [Docker Desktop **Builds** view](https://docs.docker.com/desktop/use-desktop/builds/).

To import the build record archive into Docker Desktop:

1. Download and install [Docker Desktop](https://docs.docker.com/get-started/get-docker/).

2. Download the build record archive from the job summary in GitHub Actions.

3. Open the **Builds** view in Docker Desktop.

4. Select the **Import build** button, and then browse for the `.zip` archive job summary that you downloaded. Alternatively, you can drag-and-drop the build record archive ZIP file onto the Docker Desktop window after opening the import build dialog.

5. Select **Import** to add the build records.

After a few seconds, the builds from the GitHub Actions run appear under the **Completed builds** tab in the Builds view. To inspect a build and see a detailed view of all the inputs, results, build steps, and cache utilization, select the item in the list.

## [Disable job summary](#disable-job-summary)

To disable job summaries, set the `DOCKER_BUILD_SUMMARY` environment variable in the YAML configuration for your build step:

```yaml
      - name: Build
        uses: docker/build-push-action@v7
        env:
          DOCKER_BUILD_SUMMARY: false
        with:
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
```

## [Disable build record upload](#disable-build-record-upload)

To disable the upload of the build record archive to GitHub, set the `DOCKER_BUILD_RECORD_UPLOAD` environment variable in the YAML configuration for your build step:

```yaml
      - name: Build
        uses: docker/build-push-action@v7
        env:
          DOCKER_BUILD_RECORD_UPLOAD: false
        with:
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
```

With this configuration, the build summary is still generated, but does not contain a link to download the build record archive.

## [Limitations](#limitations)

Build summaries are currently not supported for:

* Repositories hosted on GitHub Enterprise Servers. Summaries can only be viewed for repositories hosted on GitHub.com.

----
url: https://docs.docker.com/reference/cli/docker/scout/config/
----

# docker scout config

***

| Description | Manage Docker Scout configuration   |
| ----------- | ----------------------------------- |
| Usage       | `docker scout config [KEY] [VALUE]` |

## [Description](#description)

`docker scout config` allows you to list, get and set Docker Scout configuration.

Available configuration key:

* `organization`: Namespace of the Docker organization to be used by default.

## [Examples](#examples)

### [List existing configuration](#list-existing-configuration)

```console
$ docker scout config
organization=my-org-namespace
```

### [Print configuration value](#print-configuration-value)

```console
$ docker scout config organization
my-org-namespace
```

### [Set configuration value](#set-configuration-value)

```console
$ docker scout config organization my-org-namespace
    ✓ Successfully set organization to my-org-namespace
```

----
url: https://docs.docker.com/guides/ros2/run-ros2/
----

# Run ROS 2 in a container

***

Table of contents

***

## [Overview](#overview)

In this section, you will run ROS 2 in an isolated Docker container using official ROS 2 images, verify that ROS 2 is working, and install additional ROS 2 packages for development and testing.

***

## [Run ROS 2 in a container](#run-ros-2-in-a-container)

The fastest way to get started with ROS 2 is to use the [official Docker image](https://hub.docker.com/_/ros/). To pull an image, start a container, and open an interactive bash shell:

1. Pull and run the official ROS 2 Docker image:

   ```console
   $ docker run -it ros:humble
   ```

   This guide uses the Humble distribution. You can replace `humble` with another supported distribution such as `rolling`, `jazzy`, or `iron`.

   > Note
   >
   > This environment is temporary and does not maintain persistence. Any files you create or packages you install will be deleted once the container is stopped or removed.

2. Verify ROS 2 is working:

   ```console
   $ echo $ROS_DISTRO
   ```

   You should see output similar to:

   ```text
   humble
   ```

## [Install ROS 2 packages](#install-ros-2-packages)

The official ROS 2 images include core packages. To install additional packages, use the `apt` package manager:

1. Update the package manager:

   ```console
   $ sudo apt update
   ```

2. Install the desired package:

   ```console
   $ sudo apt install $PACKAGE_NAME
   ```

Replace `$PACKAGE_NAME` with any package you want to install.

Some commonly used packages include:

* `ros-humble-turtlesim` - Visualization and simulation tool
* `ros-humble-rviz2` - 3D visualization tool
* `ros-humble-rqt` - Qt-based ROS graphical tools
* `ros-humble-demo-nodes-cpp` - C++ demo nodes
* `ros-humble-demo-nodes-py` - Python demo nodes
* `ros-humble-colcon-common-extensions` - Build system extensions

## [Summary](#summary)

In this section, you pulled an official ROS 2 Docker image, launched an interactive session, and extended the container's capabilities by installing additional ROS 2 packages using apt.

## [Next steps](#next-steps)

In the next section, you will configure a persistent workspace to ensure your code and modifications are saved across sessions.

[Build and develop a ROS 2 workspace »](https://docs.docker.com/guides/ros2/develop/)

----
url: https://docs.docker.com/reference/cli/docker/buildx/history/rm/
----

# docker buildx history rm

***

| Description | Remove build records                          |
| ----------- | --------------------------------------------- |
| Usage       | `docker buildx history rm [OPTIONS] [REF...]` |

## [Description](#description)

Remove one or more build records from the current builder’s history. You can remove specific builds by ID or offset, or delete all records at once using the `--all` flag.

## [Options](#options)

| Option          | Default | Description              |
| --------------- | ------- | ------------------------ |
| [`--all`](#all) |         | Remove all build records |

## [Examples](#examples)

### [Remove a specific build](#remove-a-specific-build)

```console
# Using a build ID
docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt

# Or using a relative offset
docker buildx history rm ^1
```

### [Remove multiple builds](#remove-multiple-builds)

```console
# Using build IDs
docker buildx history rm qu2gsuo8ejqrwdfii23xkkckt qsiifiuf1ad9pa9qvppc0z1l3

# Or using relative offsets
docker buildx history rm ^1 ^2
```

### [Remove all build records from the current builder (--all)](#all)

```console
docker buildx history rm --all
```

----
url: https://docs.docker.com/reference/cli/docker/sandbox/network/proxy/
----

# docker sandbox network proxy

***

| Description | Manage proxy configuration for a sandbox           |
| ----------- | -------------------------------------------------- |
| Usage       | `docker sandbox network proxy <sandbox> [OPTIONS]` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Manage proxy configuration for a sandbox

## [Options](#options)

| Option                          | Default | Description                                                                                           |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `--allow-cidr`                  |         | Remove an IP range in CIDR notation from the block or bypass lists (can be specified multiple times)  |
| [`--allow-host`](#allow-host)   |         | Permit access to a domain or IP (can be specified multiple times)                                     |
| [`--block-cidr`](#block-cidr)   |         | Block access to an IP range in CIDR notation (can be specified multiple times)                        |
| `--block-host`                  |         | Block access to a domain or IP (can be specified multiple times)                                      |
| [`--bypass-cidr`](#bypass-cidr) |         | Bypass MITM proxy for an IP range in CIDR notation (can be specified multiple times)                  |
| [`--bypass-host`](#bypass-host) |         | Bypass MITM proxy for a domain or IP (can be specified multiple times)                                |
| [`--policy`](#policy)           |         | Set the default policy                                                                                |

## [Examples](#examples)

### [Block access to a domain](#block-access-to-a-domain)

```console
$ docker sandbox network proxy my-sandbox --block-host example.com
```

### [Block multiple domains](#block-multiple-domains)

```console
$ docker sandbox network proxy my-sandbox \
  --block-host example.com \
  --block-host malicious.site
```

### [Block IP range (--block-cidr)](#block-cidr)

```text
--block-cidr CIDR
```

Block access to an IP range in CIDR notation:

```console
$ docker sandbox network proxy my-sandbox --block-cidr 192.168.1.0/24
```

### [Allow specific domain (--allow-host)](#allow-host)

```text
--allow-host DOMAIN
```

Permit access to a domain (useful with deny-by-default policy):

```console
$ docker sandbox network proxy my-sandbox \
  --policy deny \
  --allow-host api.trusted-service.com
```

### [Bypass MITM proxy for domain (--bypass-host)](#bypass-host)

```text
--bypass-host DOMAIN
```

Bypass MITM proxy for specific domains:

```console
$ docker sandbox network proxy my-sandbox --bypass-host localhost
```

### [Bypass MITM proxy for IP range (--bypass-cidr)](#bypass-cidr)

```text
--bypass-cidr CIDR
```

Bypass MITM proxy for an IP range:

```console
$ docker sandbox network proxy my-sandbox --bypass-cidr 127.0.0.0/8
```

### [Set default policy (--policy)](#policy)

```text
--policy allow|deny
```

Set the default policy for network access:

```console
# Allow by default, block specific hosts
$ docker sandbox network proxy my-sandbox \
  --policy allow \
  --block-host dangerous.example

# Deny by default, allow specific hosts
$ docker sandbox network proxy my-sandbox \
  --policy deny \
  --allow-host api.trusted.com \
  --allow-host cdn.trusted.com
```

### [Remove rules](#remove-rules)

Use `--allow-cidr` to remove IP ranges from block or bypass lists:

```console
$ docker sandbox network proxy my-sandbox --allow-cidr 192.168.1.0/24
```

----
url: https://docs.docker.com/extensions/extensions-sdk/guides/kubernetes/
----

# Interacting with Kubernetes from an extension

***

Table of contents

***

The Extensions SDK does not provide any API methods to directly interact with the Docker Desktop managed Kubernetes cluster or any other created using other tools such as KinD. However, this page provides a way for you to use other SDK APIs to interact indirectly with a Kubernetes cluster from your extension.

To request an API that directly interacts with Docker Desktop-managed Kubernetes, you can upvote [this issue](https://github.com/docker/extensions-sdk/issues/181) in the Extensions SDK GitHub repository.

## [Prerequisites](#prerequisites)

### [Turn on Kubernetes](#turn-on-kubernetes)

You can use the built-in Kubernetes in Docker Desktop to start a Kubernetes single-node cluster. A `kubeconfig` file is used to configure access to Kubernetes when used in conjunction with the `kubectl` command-line tool, or other clients. Docker Desktop conveniently provides the user with a local preconfigured `kubeconfig` file and `kubectl` command within the user’s home area. It is a convenient way to fast-tracking access for those looking to leverage Kubernetes from Docker Desktop.

## [Ship the `kubectl` as part of the extension](#ship-the-kubectl-as-part-of-the-extension)

If your extension needs to interact with Kubernetes clusters, it is recommended that you include the `kubectl` command line tool as part of your extension. By doing this, users who install your extension get `kubectl` installed on their host.

To find out how to ship the `kubectl` command line tool for multiple platforms as part of your Docker Extension image, see [Build multi-arch extensions](https://docs.docker.com/extensions/extensions-sdk/extensions/multi-arch/#adding-multi-arch-binaries).

## [Examples](#examples)

The following code snippets have been put together in the [Kubernetes Sample Extension](https://github.com/docker/extensions-sdk/tree/main/samples/kubernetes-sample-extension). It shows how to interact with a Kubernetes cluster by shipping the `kubectl` command-line tool.

### [Check the Kubernetes API server is reachable](#check-the-kubernetes-api-server-is-reachable)

Once the `kubectl` command-line tool is added to the extension image in the `Dockerfile`, and defined in the `metadata.json`, the Extensions framework deploys `kubectl` to the users' host when the extension is installed.

You can use the JS API `ddClient.extension.host?.cli.exec` to issue `kubectl` commands to, for instance, check whether the Kubernetes API server is reachable given a specific context:

```typescript
const output = await ddClient.extension.host?.cli.exec("kubectl", [
  "cluster-info",
  "--request-timeout",
  "2s",
  "--context",
  "docker-desktop",
]);
```

### [List Kubernetes contexts](#list-kubernetes-contexts)

```typescript
const output = await ddClient.extension.host?.cli.exec("kubectl", [
  "config",
  "view",
  "-o",
  "jsonpath='{.contexts}'",
]);
```

### [List Kubernetes namespaces](#list-kubernetes-namespaces)

```typescript
const output = await ddClient.extension.host?.cli.exec("kubectl", [
  "get",
  "namespaces",
  "--no-headers",
  "-o",
  'custom-columns=":metadata.name"',
  "--context",
  "docker-desktop",
]);
```

## [Persisting the kubeconfig file](#persisting-the-kubeconfig-file)

Below there are different ways to persist and read the `kubeconfig` file from the host filesystem. Users can add, edit, or remove Kubernetes context to the `kubeconfig` file at any time.

> Warning
>
> The `kubeconfig` file is very sensitive and if found can give an attacker administrative access to the Kubernetes Cluster.

### [Extension's backend container](#extensions-backend-container)

If you need your extension to persist the `kubeconfig` file after it's been read, you can have a backend container that exposes an HTTP POST endpoint to store the content of the file either in memory or somewhere within the container filesystem. This way, if the user navigates out of the extension to another part of Docker Desktop and then comes back, you don't need to read the `kubeconfig` file again.

```typescript
export const updateKubeconfig = async () => {
  const kubeConfig = await ddClient.extension.host?.cli.exec("kubectl", [
    "config",
    "view",
    "--raw",
    "--minify",
    "--context",
    "docker-desktop",
  ]);
  if (kubeConfig?.stderr) {
    console.log("error", kubeConfig?.stderr);
    return false;
  }

  // call backend container to store the kubeconfig retrieved into the container's memory or filesystem
  try {
    await ddClient.extension.vm?.service?.post("/store-kube-config", {
      data: kubeConfig?.stdout,
    });
  } catch (err) {
    console.log("error", JSON.stringify(err));
  }
};
```

### [Docker volume](#docker-volume)

Volumes are the preferred mechanism for persisting data generated by and used by Docker containers. You can make use of them to persist the `kubeconfig` file. By persisting the `kubeconfig` in a volume you won't need to read the `kubeconfig` file again when the extension pane closes. This makes it ideal for persisting data when navigating out of the extension to other parts of Docker Desktop.

```typescript
const kubeConfig = await ddClient.extension.host?.cli.exec("kubectl", [
  "config",
  "view",
  "--raw",
  "--minify",
  "--context",
  "docker-desktop",
]);
if (kubeConfig?.stderr) {
  console.log("error", kubeConfig?.stderr);
  return false;
}

await ddClient.docker.cli.exec("run", [
  "--rm",
  "-v",
  "my-vol:/tmp",
  "alpine",
  "/bin/sh",
  "-c",
  `"touch /tmp/.kube/config && echo '${kubeConfig?.stdout}' > /tmp/.kube/config"`,
]);
```

### [Extension's `localStorage`](#extensions-localstorage)

`localStorage` is one of the mechanisms of a browser's web storage. It allows users to save data as key-value pairs in the browser for later use. `localStorage` does not clear data when the browser (the extension pane) closes. This makes it ideal for persisting data when navigating out of the extension to other parts of Docker Desktop.

```typescript
localStorage.setItem("kubeconfig", kubeConfig);
```

```typescript
localStorage.getItem("kubeconfig");
```

----
url: https://docs.docker.com/get-started/docker-concepts/running-containers/multi-container-applications/
----

# Multi-container applications

***

Table of contents

***

## [Explanation](#explanation)

Starting up a single-container application is easy. For example, a Python script that performs a specific data processing task runs within a container with all its dependencies. Similarly, a Node.js application serving a static website with a small API endpoint can be effectively containerized with all its necessary libraries and dependencies. However, as applications grow in size, managing them as individual containers becomes more difficult.

Imagine the data processing Python script needs to connect to a database. Suddenly, you're now managing not just the script but also a database server within the same container. If the script requires user logins, you'll need an authentication mechanism, further bloating the container size.

One best practice for containers is that each container should do one thing and do it well. While there are exceptions to this rule, avoid the tendency to have one container do multiple things.

Now you might ask, "Do I need to run these containers separately? If I run them separately, how shall I connect them all together?"

While `docker run` is a convenient tool for launching containers, it becomes difficult to manage a growing application stack with it. Here's why:

* Imagine running several `docker run` commands (frontend, backend, and database) with different configurations for development, testing, and production environments. It's error-prone and time-consuming.
* Applications often rely on each other. Manually starting containers in a specific order and managing network connections become difficult as the stack expands.
* Each application needs its `docker run` command, making it difficult to scale individual services. Scaling the entire application means potentially wasting resources on components that don't need a boost.
* Persisting data for each application requires separate volume mounts or configurations within each `docker run` command. This creates a scattered data management approach.
* Setting environment variables for each application through separate `docker run` commands is tedious and error-prone.

That's where Docker Compose comes to the rescue.

Docker Compose defines your entire multi-container application in a single YAML file called `compose.yml`. This file specifies configurations for all your containers, their dependencies, environment variables, and even volumes and networks. With Docker Compose:

* You don't need to run multiple `docker run` commands. All you need to do is define your entire multi-container application in a single YAML file. This centralizes configuration and simplifies management.
* You can run containers in a specific order and manage network connections easily.
* You can simply scale individual services up or down within the multi-container setup. This allows for efficient allocation based on real-time needs.
* You can implement persistent volumes with ease.
* It's easy to set environment variables once in your Docker Compose file.

By leveraging Docker Compose for running multi-container setups, you can build complex applications with modularity, scalability, and consistency at their core.

## [Try it out](#try-it-out)

In this hands-on guide, you'll first see how to build and run a counter web application based on Node.js, an Nginx reverse proxy, and a Redis database using the `docker run` commands. You’ll also see how you can simplify the entire deployment process using Docker Compose.

### [Set up](#set-up)

1. Get the sample application. If you have Git, you can clone the repository for the sample application. Otherwise, you can download the sample application. Choose one of the following options.

   Use the following command in a terminal to clone the sample application repository.

   ```console
   $ git clone https://github.com/dockersamples/nginx-node-redis
   ```

   Navigate into the `nginx-node-redis` directory:

   ```console
   $ cd nginx-node-redis
   ```

   Inside this directory, you'll find two sub-directories - `nginx` and `web`.

   Download the source and extract it.

   [Download the source](https://github.com/dockersamples/nginx-node-redis/archive/refs/heads/main.zip)

   Navigate into the `nginx-node-redis-main` directory:

   ```console
   $ cd nginx-node-redis-main
   ```

   Inside this directory, you'll find two sub-directories - `nginx` and `web`.

2. [Download and install](https://docs.docker.com/get-started/get-docker/) Docker Desktop.

### [Build the images](#build-the-images)

1. Navigate into the `nginx` directory to build the image by running the following command:

   ```console
   $ docker build -t nginx .
   ```

2. Navigate into the `web` directory and run the following command to build the first web image:

   ```console
   $ docker build -t web .
   ```

### [Run the containers](#run-the-containers)

1. Before you can run a multi-container application, you need to create a network for them all to communicate through. You can do so using the `docker network create` command:

   ```console
   $ docker network create sample-app
   ```

2. Start the Redis container by running the following command, which will attach it to the previously created network and create a network alias (useful for DNS lookups):

   ```console
   $ docker run -d  --name redis --network sample-app --network-alias redis redis
   ```

3. Start the first web container by running the following command:

   ```console
   $ docker run -d --name web1 -h web1 --network sample-app --network-alias web1 web
   ```

4. Start the second web container by running the following:

   ```console
   $ docker run -d --name web2 -h web2 --network sample-app --network-alias web2 web
   ```

5. Start the Nginx container by running the following command:

   ```console
   $ docker run -d --name nginx --network sample-app  -p 80:80 nginx
   ```

   > Note
   >
   > Nginx is typically used as a reverse proxy for web applications, routing traffic to backend servers. In this case, it routes to the Node.js backend containers (web1 or web2).

6. Verify the containers are up by running the following command:

   ```console
   $ docker ps
   ```

   You will see output like the following:

   ```text
   CONTAINER ID   IMAGE     COMMAND                  CREATED              STATUS              PORTS                NAMES
   2cf7c484c144   nginx     "/docker-entrypoint.…"   9 seconds ago        Up 8 seconds        0.0.0.0:80->80/tcp   nginx
   7a070c9ffeaa   web       "docker-entrypoint.s…"   19 seconds ago       Up 18 seconds                            web2
   6dc6d4e60aaf   web       "docker-entrypoint.s…"   34 seconds ago       Up 33 seconds                            web1
   008e0ecf4f36   redis     "docker-entrypoint.s…"   About a minute ago   Up About a minute   6379/tcp             redis
   ```

7. If you look at the Docker Desktop Dashboard, you can see the containers and dive deeper into their configuration.

8. With everything up and running, you can open <http://localhost> in your browser to see the site. Refresh the page several times to see the host that’s handling the request and the total number of requests:

   ```console
   web2: Number of visits is: 9
   web1: Number of visits is: 10
   web2: Number of visits is: 11
   web1: Number of visits is: 12
   ```

   > Note
   >
   > You might have noticed that Nginx, acting as a reverse proxy, likely distributes incoming requests in a round-robin fashion between the two backend containers. This means each request might be directed to a different container (web1 and web2) on a rotating basis. The output shows consecutive increments for both the web1 and web2 containers and the actual counter value stored in Redis is updated only after the response is sent back to the client.

9. You can use the Docker Desktop Dashboard to remove the containers by selecting the containers and selecting the **Delete** button.

## [Simplify the deployment using Docker Compose](#simplify-the-deployment-using-docker-compose)

Docker Compose provides a structured and streamlined approach for managing multi-container deployments. As stated earlier, with Docker Compose, you don’t need to run multiple `docker run` commands. All you need to do is define your entire multi-container application in a single YAML file called `compose.yml`. Let’s see how it works.

Navigate to the root of the project directory. Inside this directory, you'll find a file named `compose.yml`. This YAML file is where all the magic happens. It defines all the services that make up your application, along with their configurations. Each service specifies its image, ports, volumes, networks, and any other settings necessary for its functionality.

1. Use the `docker compose up` command to start the application:

   ```console
   $ docker compose up -d --build
   ```

   When you run this command, you should see output similar to the following:

   ```console
    ✔ Network nginx-node-redis_default   Created                                                                                                   0.0s
    ✔ Container nginx-node-redis-web2-1  Created                                                                                                   0.1s
    ✔ Container nginx-node-redis-web1-1  Created                                                                                                   0.1s
    ✔ Container nginx-node-redis-redis-1 Created                                                                                                   0.1s
    ✔ Container nginx-node-redis-nginx-1 Created   
   ```

2. If you look at the Docker Desktop Dashboard, you can see the containers and dive deeper into their configuration.

3. Alternatively, you can use the Docker Desktop Dashboard to remove the containers by selecting the application stack and selecting the **Delete** button.

In this guide, you learned how easy it is to use Docker Compose to start and stop a multi-container application compared to `docker run` which is error-prone and difficult to manage.

## [Additional resources](#additional-resources)

* [`docker container run` CLI reference](https://docs.docker.com/reference/cli/docker/container/run/)
* [What is Docker Compose](/get-started/docker-concepts/the-basics/what-is-docker-compose/)

----
url: https://docs.docker.com/guides/testcontainers-java-keycloak-spring-boot/create-project/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Create the Spring Boot project

***

Table of contents

***

## [Set up the project](#set-up-the-project)

Create a Spring Boot project from [Spring Initializr](https://start.spring.io) by selecting the **Spring Web**, **Validation**, **JDBC API**, **PostgreSQL Driver**, **Spring Security**, **OAuth2 Resource Server**, and **Testcontainers** starters.

Alternatively, clone the [guide repository](https://github.com/testcontainers/tc-guide-securing-spring-boot-microservice-using-keycloak-and-testcontainers).

After generating the application, add the [testcontainers-keycloak](https://github.com/dasniko/testcontainers-keycloak) community module and [REST Assured](https://rest-assured.io/) as test dependencies.

The key dependencies in `pom.xml` are:

```xml
<properties>
    <java.version>17</java.version>
    <testcontainers.version>2.0.4</testcontainers.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-jdbc</artifactId>
    </dependency>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.security</groupId>
        <artifactId>spring-security-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-testcontainers</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-postgresql</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>com.github.dasniko</groupId>
        <artifactId>testcontainers-keycloak</artifactId>
        <version>3.4.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>
```

## [Create the domain model](#create-the-domain-model)

Create a `Product` record that represents the domain object:

```java
package com.testcontainers.products.domain;

import jakarta.validation.constraints.NotEmpty;

public record Product(Long id, @NotEmpty String title, String description) {}
```

## [Create the repository](#create-the-repository)

Implement `ProductRepository` using Spring `JdbcClient` to interact with a PostgreSQL database:

```java
package com.testcontainers.products.domain;

import java.util.List;
import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.jdbc.support.GeneratedKeyHolder;
import org.springframework.jdbc.support.KeyHolder;
import org.springframework.stereotype.Repository;

@Repository
public class ProductRepository {

  private final JdbcClient jdbcClient;

  public ProductRepository(JdbcClient jdbcClient) {
    this.jdbcClient = jdbcClient;
  }

  public List<Product> getAll() {
    return jdbcClient.sql("SELECT * FROM products").query(Product.class).list();
  }

  public Product create(Product product) {
    String sql =
      "INSERT INTO products(title, description) VALUES (:title,:description) RETURNING id";
    KeyHolder keyHolder = new GeneratedKeyHolder();
    jdbcClient
      .sql(sql)
      .param("title", product.title())
      .param("description", product.description())
      .update(keyHolder);
    Long id = keyHolder.getKeyAs(Long.class);
    return new Product(id, product.title(), product.description());
  }
}
```

## [Add a schema creation script](#add-a-schema-creation-script)

Create `src/main/resources/schema.sql` to initialize the `products` table:

```sql
CREATE TABLE products (
    id bigserial primary key,
    title varchar not null,
    description text
);
```

Enable schema initialization in `src/main/resources/application.properties`:

```properties
spring.sql.init.mode=always
```

For production applications, use a database migration tool like Flyway or Liquibase instead.

## [Implement the API endpoints](#implement-the-api-endpoints)

Create `ProductController` with endpoints to fetch all products and create a product:

```java
package com.testcontainers.products.api;

import com.testcontainers.products.domain.Product;
import com.testcontainers.products.domain.ProductRepository;
import jakarta.validation.Valid;
import java.util.List;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/products")
class ProductController {

  private final ProductRepository productRepository;

  ProductController(ProductRepository productRepository) {
    this.productRepository = productRepository;
  }

  @GetMapping
  List<Product> getAll() {
    return productRepository.getAll();
  }

  @PostMapping
  @ResponseStatus(HttpStatus.CREATED)
  Product createProduct(@RequestBody @Valid Product product) {
    return productRepository.create(product);
  }
}
```

## [Configure OAuth 2.0 security](#configure-oauth-20-security)

Create a `SecurityConfig` class that protects the API endpoints using JWT token-based authentication:

```java
package com.testcontainers.products.config;

import static org.springframework.security.config.Customizer.withDefaults;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.CorsConfigurer;
import org.springframework.security.config.annotation.web.configurers.CsrfConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
class SecurityConfig {

  @Bean
  SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
      .authorizeHttpRequests(c ->
        c
          .requestMatchers(HttpMethod.GET, "/api/products")
          .permitAll()
          .requestMatchers(HttpMethod.POST, "/api/products")
          .authenticated()
          .anyRequest()
          .authenticated()
      )
      .sessionManagement(c ->
        c.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
      )
      .cors(CorsConfigurer::disable)
      .csrf(CsrfConfigurer::disable)
      .oauth2ResourceServer(oauth2 -> oauth2.jwt(withDefaults()));
    return http.build();
  }
}
```

This configuration:

* Permits unauthenticated access to `GET /api/products`.
* Requires authentication for `POST /api/products` and all other endpoints.
* Configures the OAuth 2.0 Resource Server with JWT token-based authentication.
* Disables CORS and CSRF because this is a stateless API.

Add the JWT issuer URI to `application.properties`:

```properties
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:9090/realms/keycloaktcdemo
```

## [Export the Keycloak realm configuration](#export-the-keycloak-realm-configuration)

Before writing the tests, export a Keycloak realm configuration so that the test environment can import it automatically. Start a temporary Keycloak instance:

```console
$ docker run -p 9090:8080 \
    -e KEYCLOAK_ADMIN=admin \
    -e KEYCLOAK_ADMIN_PASSWORD=admin \
    quay.io/keycloak/keycloak:25 start-dev
```

Open `http://localhost:9090` and sign in to the Admin Console with `admin/admin`. Then set up the realm:

1. In the top-left corner, select the realm drop-down and create a realm named `keycloaktcdemo`.

2. Under the `keycloaktcdemo` realm, create a client with the following settings:

   * **Client ID**: `product-service`
   * **Client Authentication**: `On`
   * **Authentication flow**: select only **Service accounts roles**

3. On the **Client details** screen, go to the **Credentials** tab and copy the **Client secret** value.

Export the realm configuration:

```console
$ docker ps
# copy the keycloak container id

$ docker exec -it <container-id> /bin/bash

$ /opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/import --realm keycloaktcdemo

$ exit

$ docker cp <container-id>:/opt/keycloak/data/import/keycloaktcdemo-realm.json keycloaktcdemo-realm.json
```

Copy the exported `keycloaktcdemo-realm.json` file into `src/test/resources`.

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-java-keycloak-spring-boot/write-tests/)

----
url: https://docs.docker.com/reference/cli/docker/mcp/catalog/server/ls/
----

# docker mcp catalog server ls

***

| Description                                                               | List servers in a catalog                      |
| ------------------------------------------------------------------------- | ---------------------------------------------- |
| Usage                                                                     | `docker mcp catalog server ls <oci-reference>` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker mcp catalog server list`               |

## [Description](#description)

List all servers in a catalog.

Use --filter to search for servers matching a query (case-insensitive substring matching on server names). Filters use key=value format (e.g., name=github).

## [Options](#options)

| Option         | Default | Description                       |
| -------------- | ------- | --------------------------------- |
| `-f, --filter` |         | Filter output (e.g., name=github) |
| `--format`     | `human` | Supported: json, yaml, human.     |

## [Examples](#examples)

# [List all servers in a catalog](#list-all-servers-in-a-catalog)

docker mcp catalog server ls mcp/docker-mcp-catalog:latest

# [Filter servers by name](#filter-servers-by-name)

docker mcp catalog server ls mcp/docker-mcp-catalog:latest --filter name=github

# [Combine multiple filters (using short flag)](#combine-multiple-filters-using-short-flag)

docker mcp catalog server ls mcp/docker-mcp-catalog:latest -f name=slack -f name=github

# [Output in JSON format](#output-in-json-format)

docker mcp catalog server ls mcp/docker-mcp-catalog:latest --format json

----
url: https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-docker-compose/
----

# What is Docker Compose?

***

Table of contents

***

## [Explanation](#explanation)

If you've been following the guides so far, you've been working with single container applications. But, now you're wanting to do something more complicated - run databases, message queues, caches, or a variety of other services. Do you install everything in a single container? Run multiple containers? If you run multiple, how do you connect them all together?

One best practice for containers is that each container should do one thing and do it well. While there are exceptions to this rule, avoid the tendency to have one container do multiple things.

You can use multiple `docker run` commands to start multiple containers. But, you'll soon realize you'll need to manage networks, all of the flags needed to connect containers to those networks, and more. And when you're done, cleanup is a little more complicated.

With Docker Compose, you can define all of your containers and their configurations in a single YAML file. If you include this file in your code repository, anyone that clones your repository can get up and running with a single command.

It's important to understand that Compose is a declarative tool - you simply define it and go. You don't always need to recreate everything from scratch. If you make a change, run `docker compose up` again and Compose will reconcile the changes in your file and apply them intelligently.

> **Dockerfile versus Compose file**
>
> A Dockerfile provides instructions to build a container image while a Compose file defines your running containers. Quite often, a Compose file references a Dockerfile to build an image to use for a particular service.

## [Try it out](#try-it-out)

In this hands-on, you will learn how to use a Docker Compose to run a multi-container application. You'll use a simple to-do list app built with Node.js and MySQL as a database server.

### [Start the application](#start-the-application)

Follow the instructions to run the to-do list app on your system.

1. [Download and install](https://www.docker.com/products/docker-desktop/) Docker Desktop.

2. Open a terminal and [clone this sample application](https://github.com/dockersamples/todo-list-app).

   ```console
   git clone https://github.com/dockersamples/todo-list-app 
   ```

3. Navigate into the `todo-list-app` directory:

   ```console
   cd todo-list-app
   ```

   Inside this directory, you'll find a file named `compose.yaml`. This YAML file is where all the magic happens! It defines all the services that make up your application, along with their configurations. Each service specifies its image, ports, volumes, networks, and any other settings necessary for its functionality. Take some time to explore the YAML file and familiarize yourself with its structure.

4. Use the [`docker compose up`](/reference/cli/docker/compose/up/) command to start the application:

   ```console
   docker compose up -d --build
   ```

   When you run this command, you should see an output like this:

   ```console
   [+] Running 5/5
   ✔ app 3 layers [⣿⣿⣿]      0B/0B            Pulled          7.1s
     ✔ e6f4e57cc59e Download complete                          0.9s
     ✔ df998480d81d Download complete                          1.0s
     ✔ 31e174fedd23 Download complete                          2.5s
     ✔ 43c47a581c29 Download complete                          2.0s
   [+] Running 4/4
     ⠸ Network todo-list-app_default           Created         0.3s
     ⠸ Volume "todo-list-app_todo-mysql-data"  Created         0.3s
     ✔ Container todo-list-app-app-1           Started         0.3s
     ✔ Container todo-list-app-mysql-1         Started         0.3s
   ```

   A lot happened here! A couple of things to call out:

   * Two container images were downloaded from Docker Hub - node and MySQL
   * A network was created for your application
   * A volume was created to persist the database files between container restarts
   * Two containers were started with all of their necessary config

   If this feels overwhelming, don't worry! You'll get there!

5. With everything now up and running, you can open <http://localhost:3000> in your browser to see the site. Note that the application may take 10-15 seconds to fully start. If the page doesn't load right away, wait a moment and refresh. Feel free to add items to the list, check them off, and remove them.

6. If you look at the Docker Desktop GUI, you can see the containers and dive deeper into their configuration.

### [Tear it down](#tear-it-down)

Since this application was started using Docker Compose, it's easy to tear it all down when you're done.

1. In the CLI, use the [`docker compose down`](/reference/cli/docker/compose/down/) command to remove everything:

   ```console
   docker compose down
   ```

   You'll see output similar to the following:

   ```console
   [+] Running 3/3
   ✔ Container todo-list-app-mysql-1  Removed        2.9s
   ✔ Container todo-list-app-app-1    Removed        0.1s
   ✔ Network todo-list-app_default    Removed        0.1s
   ```

   > **Volume persistence**
   >
   > By default, volumes *aren't* automatically removed when you tear down a Compose stack. The idea is that you might want the data back if you start the stack again.
   >
   > If you do want to remove the volumes, add the `--volumes` flag when running the `docker compose down` command:
   >
   > ```console
   > docker compose down --volumes
   > [+] Running 1/0
   > ✔ Volume todo-list-app_todo-mysql-data  Removed
   > ```

2. Alternatively, you can use the Docker Desktop GUI to remove the containers by selecting the application stack and selecting the **Delete** button.

   > **Using the GUI for Compose stacks**
   >
   > Note that if you remove the containers for a Compose app in the GUI, it's removing only the containers. You'll have to manually remove the network and volumes if you want to do so.

In this walkthrough, you learned how to use Docker Compose to start and stop a multi-container application.

## [Additional resources](#additional-resources)

This page was a brief introduction to Compose. In the following resources, you can dive deeper into Compose and how to write Compose files.

* [Overview of Docker Compose](/compose/)
* [Overview of Docker Compose CLI](/reference/cli/docker/compose/)
* [How Compose works](/compose/intro/compose-application-model/)

----
url: https://docs.docker.com/guides/cpp/deploy/
----

# Test your C++ deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Containerize a C++ application](https://docs.docker.com/guides/cpp/containerize/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your `c-plus-plus-docker` directory, create a file named `docker-kubernetes.yml`. Open the file in an IDE or text editor and add the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the name of the repository that you created in [Configure CI/CD for your C++ application](https://docs.docker.com/guides/cpp/configure-ci-cd/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-c-plus-plus-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: ok-api
  template:
    metadata:
      labels:
        service: ok-api
    spec:
      containers:
        - name: ok-api-service
          image: DOCKER_USERNAME/REPO_NAME
          imagePullPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: service-entrypoint
  namespace: default
spec:
  type: NodePort
  selector:
    service: ok-api
  ports:
    - port: 8080
      targetPort: 8080
      nodePort: 30001
```

In this Kubernetes YAML file, there are two objects, separated by the `---`:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your C++ application](https://docs.docker.com/guides/cpp/configure-ci-cd/).
* A NodePort service, which will route traffic from port 30001 on your host to port 8080 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to `c-plus-plus-docker` and deploy your application to Kubernetes.

   ```console
   $ kubectl apply -f docker-kubernetes.yml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```text
   deployment.apps/docker-c-plus-plus-demo created
   service/service-entrypoint created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```shell
   NAME                     READY   UP-TO-DATE   AVAILABLE    AGE
   docker-c-plus-plus-demo   1/1     1            1           10s
   ```

   This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```shell
   NAME                 TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
   kubernetes           ClusterIP   10.96.0.1        <none>        443/TCP          88m
   service-entrypoint   NodePort    10.105.145.223   <none>        8080:30001/TCP   83s
   ```

   In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP.

3. In a browser, visit the following address. You should see the message `{"Status" : "OK"}`.

   ```console
   http://localhost:30001/
   ```

4. Run the following command to tear down your application.

   ```console
   $ kubectl delete -f docker-kubernetes.yml
   ```

## [Summary](#summary)

In this section, you learned how to use Docker Desktop to deploy your C++ application to a fully-featured Kubernetes environment on your development machine.

Related information:

* [Kubernetes documentation](https://kubernetes.io/docs/home/)
* [Deploy on Kubernetes with Docker Desktop](https://docs.docker.com/desktop/use-desktop/kubernetes/)
* [Swarm mode overview](https://docs.docker.com/engine/swarm/)

[Supply-chain security for C++ Docker images »](https://docs.docker.com/guides/cpp/security/)

----
url: https://docs.docker.com/reference/cli/docker/model/gateway/
----

# docker model gateway

***

| Description | Run an OpenAI-compatible LLM gateway |
| ----------- | ------------------------------------ |
| Usage       | `docker model gateway`               |

## [Description](#description)

`docker model gateway` starts a local OpenAI-compatible HTTP gateway that routes requests to one or more configured LLM providers. It supports Docker Model Runner as a first-class provider, alongside Ollama, OpenAI, Anthropic, Groq, Mistral, Azure OpenAI, and many other OpenAI-compatible endpoints.

The gateway is configured through a YAML file that declares the model list, provider routing, load-balancing, retries, and fallbacks.

### [Configuration file format](#configuration-file-format)

```yaml
model_list:
  - model_name: <alias exposed to clients>
    params:
      model: <provider>/<upstream-model-name>
      api_base: <optional base URL override>
      api_key: <optional key or os.environ/VAR_NAME>

general_settings:
  master_key: <optional API key required by clients>
  num_retries: <optional integer, default 0>
  fallbacks:
    - <primary-alias>: [<fallback-alias>, ...]
```

The `model` field under `params` uses the format `provider/model-name`. Supported provider prefixes include: `docker_model_runner`, `openai`, `anthropic`, `ollama`, `groq`, `mistral`, `together_ai`, `deepseek`, `fireworks_ai`, `openrouter`, `perplexity`, `xai`, `nvidia_nim`, `cerebras`, `sambanova`, `deepinfra`, `azure`, `azure_ai`, `vllm`, `lm_studio`, `huggingface`.

API keys can be supplied inline, as `os.environ/VAR_NAME` references, or as `${VAR_NAME}` references. The gateway resolves well-known environment variables automatically (for example, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`).

## [Options](#options)

| Option          | Default   | Description                         |
| --------------- | --------- | ----------------------------------- |
| `-c, --config`  |           | Path to the YAML configuration file |
| `--host`        | `0.0.0.0` | Host address to bind to             |
| `-p, --port`    | `4000`    | Port to listen on                   |
| `-v, --verbose` |           | Enable verbose (debug) logging      |

## [Examples](#examples)

### [Route requests to Docker Model Runner](#route-requests-to-docker-model-runner)

```yaml
model_list:
  - model_name: smollm2
    params:
      model: docker_model_runner/ai/smollm2
      api_base: http://localhost:12434/engines/llama.cpp/v1
```

```console
$ docker model gateway --config config.yaml
```

The gateway starts on `http://0.0.0.0:4000`. Send requests using any OpenAI-compatible client:

```console
$ curl http://localhost:4000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
      "model": "smollm2",
      "messages": [{"role": "user", "content": "Hello"}]
    }'
```

### [Route requests to multiple providers with fallback](#route-requests-to-multiple-providers-with-fallback)

```yaml
model_list:
  - model_name: fast
    params:
      model: groq/llama-3.1-8b-instant
      api_key: os.environ/GROQ_API_KEY
  - model_name: smart
    params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: local
    params:
      model: docker_model_runner/ai/smollm2
      api_base: http://localhost:12434/engines/llama.cpp/v1

general_settings:
  num_retries: 2
  fallbacks:
    - fast: [local]
    - smart: [fast, local]
```

```console
$ docker model gateway --config config.yaml --port 8080
```

### [Secure the gateway with an API key](#secure-the-gateway-with-an-api-key)

```yaml
model_list:
  - model_name: smollm2
    params:
      model: docker_model_runner/ai/smollm2
      api_base: http://localhost:12434/engines/llama.cpp/v1

general_settings:
  master_key: os.environ/GATEWAY_API_KEY
```

```console
$ GATEWAY_API_KEY=my-secret docker model gateway --config config.yaml
```

Clients must then pass the key as a Bearer token or via the `x-api-key` header:

```console
$ curl http://localhost:4000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{"model": "smollm2", "messages": [{"role": "user", "content": "Hi"}]}'
```

### [Use a custom host and port](#use-a-custom-host-and-port)

```console
$ docker model gateway --config config.yaml --host 127.0.0.1 --port 9000
```

### [Enable debug logging](#enable-debug-logging)

```console
$ docker model gateway --config config.yaml --verbose
```

----
url: https://docs.docker.com/reference/cli/docker/manifest/rm/
----

# docker manifest rm

***

| Description | Delete one or more manifest lists from local storage  |
| ----------- | ----------------------------------------------------- |
| Usage       | `docker manifest rm MANIFEST_LIST [MANIFEST_LIST...]` |

**Experimental**

**This command is experimental.**

Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.

## [Description](#description)

Delete one or more manifest lists from local storage

----
url: https://docs.docker.com/reference/cli/docker/compose/bridge/transformations/
----

# docker compose bridge transformations

***

| Description | Manage transformation images |
| ----------- | ---------------------------- |

## [Description](#description)

Manage transformation images

## [Subcommands](#subcommands)

| Command                                                                                                                               | Description                    |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| [`docker compose bridge transformations create`](https://docs.docker.com/reference/cli/docker/compose/bridge/transformations/create/) | Create a new transformation    |
| [`docker compose bridge transformations list`](https://docs.docker.com/reference/cli/docker/compose/bridge/transformations/list/)     | List available transformations |

----
url: https://docs.docker.com/scout/deep-dive/advisory-db-sources/
----

# Advisory database sources and matching service

***

Table of contents

***

Reliable information sources are key for Docker Scout's ability to surface relevant and accurate assessments of your software artifacts. Given the diversity of sources and methodologies in the industry, discrepancies in vulnerability assessment results can and do happen. This page describes how the Docker Scout advisory database and its CVE-to-package matching approach works to deal with these discrepancies.

## [Advisory database sources](#advisory-database-sources)

Docker Scout aggregates vulnerability data from multiple sources. The data is continuously updated to ensure that your security posture is represented using the latest available information, in real-time.

Docker Scout uses the following package repositories and security trackers:

* [AlmaLinux Security Advisory](https://errata.almalinux.org/)
* [Alpine secdb](https://secdb.alpinelinux.org/)
* [Amazon Linux Security Center](https://alas.aws.amazon.com/)
* [Bitnami Vulnerability Database](https://github.com/bitnami/vulndb)
* [CISA Known Exploited Vulnerability Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
* [CISA Vulnrichment](https://github.com/cisagov/vulnrichment)
* [Chainguard Security Feed](https://packages.cgr.dev/chainguard/osv/all.json)
* [Debian Security Bug Tracker](https://security-tracker.debian.org/tracker/)
* [Exploit Prediction Scoring System (EPSS)](https://api.first.org/epss/)
* [GitHub Advisory Database](https://github.com/advisories/)
* [GitLab Advisory Database](https://gitlab.com/gitlab-org/advisories-community/)
* [Golang VulnDB](https://github.com/golang/vulndb)
* [National Vulnerability Database](https://nvd.nist.gov/)
* [Oracle Linux Security](https://linux.oracle.com/security/)
* [Photon OS 3.0 Security Advisories](https://github.com/vmware/photon/wiki/Security-Updates-3)
* [Python Packaging Advisory Database](https://github.com/pypa/advisory-database)
* [RedHat Security Data](https://www.redhat.com/security/data/metrics/)
* [Rocky Linux Security Advisory](https://errata.rockylinux.org/)
* [RustSec Advisory Database](https://github.com/rustsec/advisory-db)
* [SUSE Security CVRF](http://ftp.suse.com/pub/projects/security/cvrf/)
* [Ubuntu CVE Tracker](https://people.canonical.com/~ubuntu-security/cve/)
* [Wolfi Security Feed](https://packages.wolfi.dev/os/security.json)
* [inTheWild, a community-driven open database of vulnerability exploitation](https://github.com/gmatuz/inthewilddb)

When you enable Docker Scout for your Docker organization, a new database instance is provisioned on the Docker Scout platform. The database stores the Software Bill of Materials (SBOM) and other metadata about your images. When a security advisory has new information about a vulnerability, your SBOM is cross-referenced with the CVE information to detect how it affects you.

For more details on how image analysis works, see the [image analysis page](https://docs.docker.com/scout/explore/analysis/).

## [Severity and scoring priority](#severity-and-scoring-priority)

Docker Scout uses two main principles when determining severity and scoring for CVEs:

* Source priority
* CVSS version preference

For source priority, Docker Scout follows this order:

1. Vendor advisories: Scout always uses the severity and scoring data from the source that matches the package and version. For example, Debian data for Debian packages.

2. NIST scoring data: If the vendor doesn't provide scoring data for a CVE, Scout falls back to NIST scoring data.

For CVSS version preference, once Scout has selected a source, it prefers CVSS v4 over v3 when both are available, as v4 is the more modern and precise scoring model.

## [Vulnerability matching](#vulnerability-matching)

Traditional tools often rely on broad [Common Product Enumeration (CPE)](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) matching, which can lead to many false-positive results.

Docker Scout uses [Package URLs (PURLs)](https://github.com/package-url/purl-spec) to match packages against CVEs, which yields more precise identification of vulnerabilities. PURLs significantly reduce the chances of false positives, focusing only on genuinely affected packages.

## [Supported package ecosystems](#supported-package-ecosystems)

Docker Scout supports the following package ecosystems:

* .NET
* GitHub packages
* Go
* Java
* JavaScript
* PHP
* Python
* RPM
* Ruby
* `alpm` (Arch Linux)
* `apk` (Alpine Linux)
* `deb` (Debian Linux and derivatives)

----
url: https://docs.docker.com/enterprise/security/enforce-sign-in/methods/
----

# Configure sign-in enforcement

***

Table of contents

***

Subscription: Team Business

For: Administrators

You can enforce sign-in for Docker Desktop using several methods. Choose the method that best fits your organization's infrastructure and security requirements.

## [Choose your method](#choose-your-method)

| Method                 | Platform      |
| ---------------------- | ------------- |
| Registry key           | Windows only  |
| Configuration profiles | Mac only      |
| `plist` file           | Mac only      |
| `registry.json`        | All platforms |

> Tip
>
> For Mac, configuration profiles offer the highest security because they're protected by Apple's System Integrity Protection (SIP).

## [Windows: Registry key method](#windows-registry-key-method)

To configure the registry key method manually:

1. Create the registry key:

   ```console
   $ HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop
   ```

2. Create a multi-string value name `allowedOrgs`.

3. Use your organization names as string data. You can add multiple organizations:

   * Use lowercase letters only
   * Add each organization on a separate line
   * Do not use spaces or commas as separators

4. Restart Docker Desktop.

5. Verify the **Sign in required!** prompt appears in Docker Desktop.

Deploy the registry key across your organization using Group Policy:

1. Create a registry script with the following structure:

   * Path: `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop`
   * Value name: `allowedOrgs` (multi-string)
   * Value data: Your organization names, one per line, in lowercase only

2. In Group Policy Management, create or edit a GPO.

3. Navigate to **Computer Configuration** > **Preferences** > **Windows Settings** > **Registry**.

4. Right-click **Registry** > **New** > **Registry Item**.

5. Configure the registry item:

   * Action: **Update**
   * Path: `HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Docker\Docker Desktop`
   * Value name: `allowedOrgs`
   * Value data: Your organization names

6. Link the GPO to the target Organizational Unit.

7. Test on a small group using `gpupdate/force`.

8. Deploy organization-wide after verification.

## [Mac: Configuration profiles method (recommended)](#mac-configuration-profiles-method-recommended)

Configuration profiles provide the most secure enforcement method for Mac, as they're protected by Apple's System Integrity Protection.

The payload is a dictionary of key-values. Docker Desktop supports the following keys:

* `allowedOrgs`: Sets a list of organizations in one single string, where each organization is in lowercase only and is separated by a semi-colon.
* `overrideProxyHTTP`: Sets the URL of the HTTP proxy that must be used for outgoing HTTP requests.
* `overrideProxyHTTPS`: Sets the URL of the HTTP proxy that must be used for outgoing HTTPS requests.
* `overrideProxyExclude`: Bypasses proxy settings for the specified hosts and domains. Uses a comma-separated list.
* `overrideProxyPAC`: Sets the file path where the PAC file is located. It has precedence over the remote PAC file on the selected proxy.
* `overrideProxyEmbeddedPAC`: Sets the content of an in-memory PAC file. It has precedence over `overrideProxyPAC`.

Overriding at least one of the proxy settings via Configuration profiles will automatically lock the settings as they're managed by Mac.

1. Create a file named `docker.mobileconfig` and include the following content:
   ```xml
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
      <key>PayloadContent</key>
      <array>
         <dict>
            <key>PayloadType</key>
            <string>com.docker.config</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadIdentifier</key>
            <string>com.docker.config</string>
            <key>PayloadUUID</key>
            <string>eed295b0-a650-40b0-9dda-90efb12be3c7</string>
            <key>PayloadDisplayName</key>
            <string>Docker Desktop Configuration</string>
            <key>PayloadDescription</key>
            <string>Configuration profile to manage Docker Desktop settings.</string>
            <key>PayloadOrganization</key>
            <string>Your company name</string>
            <key>allowedOrgs</key>
            <string>first_org;second_org</string>
            <key>overrideProxyHTTP</key>
            <string>http://company.proxy:port</string>
            <key>overrideProxyHTTPS</key>
            <string>https://company.proxy:port</string>
         </dict>
      </array>
      <key>PayloadType</key>
      <string>Configuration</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>PayloadIdentifier</key>
      <string>com.yourcompany.docker.config</string>
      <key>PayloadUUID</key>
      <string>0deedb64-7dc9-46e5-b6bf-69d64a9561ce</string>
      <key>PayloadDisplayName</key>
      <string>Docker Desktop Config Profile</string>
      <key>PayloadDescription</key>
      <string>Config profile to enforce Docker Desktop settings for allowed organizations.</string>
      <key>PayloadOrganization</key>
      <string>Your company name</string>
   </dict>
   </plist>
   ```

2. Replace placeholders:

   * Change `com.yourcompany.docker.config` to your company identifier
   * Replace `Your company name` with your organization name making sure it is all lowercase
   * Replace `PayloadUUID` with a randomly generated UUID
   * Update the `allowedOrgs` value with your organization names (separated by semicolons)
   * Replace `company.proxy:port` with http/https proxy server host(or IP address) and port

3. Deploy the profile using your MDM solution.

4. Verify the profile appears in **System Settings** > **General** > **Device Management** under **Device (Managed)**. Ensure the profile is listed with the correct name and settings.

Some MDM solutions let you specify the payload as a plain dictionary of key-value settings without the full `.mobileconfig` wrapper:

```xml
<dict>
   <key>allowedOrgs</key>
   <string>first_org;second_org</string>
   <key>overrideProxyHTTP</key>
   <string>http://company.proxy:port</string>
   <key>overrideProxyHTTPS</key>
   <string>https://company.proxy:port</string>
</dict>
```

## [Mac: plist file method](#mac-plist-file-method)

1. Create the file `/Library/Application Support/com.docker.docker/desktop.plist`.
2. Add this content, replacing `myorg1` and `myorg2` with your organization names and making sure they have lowercase letters only:
   ```xml
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
     <dict>
         <key>allowedOrgs</key>
         <array>
             <string>myorg1</string>
             <string>myorg2</string>
         </array>
     </dict>
   </plist>
   ```
3. Set file permissions to prevent editing by non-administrator users.
4. Restart Docker Desktop.
5. Verify the `Sign in required!` prompt appears in Docker Desktop.

Create and deploy a script for organization-wide distribution:

```bash
#!/bin/bash

# Create directory if it doesn't exist
sudo mkdir -p "/Library/Application Support/com.docker.docker"

# Write the plist file
sudo defaults write "/Library/Application Support/com.docker.docker/desktop.plist" allowedOrgs -array "myorg1" "myorg2"

# Set appropriate permissions
sudo chmod 644 "/Library/Application Support/com.docker.docker/desktop.plist"
sudo chown root:admin "/Library/Application Support/com.docker.docker/desktop.plist"
```

Deploy this script using SSH, remote support tools, or your preferred deployment method.

## [All platforms: registry.json method](#all-platforms-registryjson-method)

The registry.json method works across all platforms and offers flexible deployment options.

### [File locations](#file-locations)

Create the `registry.json` file (UTF-8 without BOM) at the appropriate location:

| Platform | Location                                                       |
| -------- | -------------------------------------------------------------- |
| Windows  | `/ProgramData/DockerDesktop/registry.json`                     |
| Mac      | `/Library/Application Support/com.docker.docker/registry.json` |
| Linux    | `/usr/share/docker-desktop/registry/registry.json`             |

### [Basic setup](#basic-setup)

1. Ensure users are members of your Docker organization.
2. Create the `registry.json` file at the appropriate location for your platform.
3. Add this content, replacing organization names with your own and making sure they have lowercase letters only:
   ```json
   {
      "allowedOrgs": ["myorg1", "myorg2"]
   }
   ```
4. Set file permissions to prevent user editing.
5. Restart Docker Desktop.
6. Verify the `Sign in required!` prompt appears in Docker Desktop.

> Tip
>
> If users have issues starting Docker Desktop after enforcing sign-in, they may need to update to the latest version.

#### [Windows (PowerShell as Administrator)](#windows-powershell-as-administrator)

```shell
Set-Content /ProgramData/DockerDesktop/registry.json '{"allowedOrgs":["myorg1","myorg2"]}'
```

#### [Mac](#mac)

```console
sudo mkdir -p "/Library/Application Support/com.docker.docker"
echo '{"allowedOrgs":["myorg1","myorg2"]}' | sudo tee "/Library/Application Support/com.docker.docker/registry.json"
```

#### [Linux](#linux)

```console
sudo mkdir -p /usr/share/docker-desktop/registry
echo '{"allowedOrgs":["myorg1","myorg2"]}' | sudo tee /usr/share/docker-desktop/registry/registry.json
```

Create the registry.json file during Docker Desktop installation:

#### [Windows](#windows)

```shell
# PowerShell
Start-Process '.\Docker Desktop Installer.exe' -Wait 'install --allowed-org=myorg'

# Command Prompt
"Docker Desktop Installer.exe" install --allowed-org=myorg1
```

> Note
>
> The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation.

#### [Mac](#mac)

```console
sudo hdiutil attach Docker.dmg
sudo /Volumes/Docker/Docker.app/Contents/MacOS/install --allowed-org=myorg
sudo hdiutil detach /Volumes/Docker
```

> Note
>
> The `--allowed-org` flag accepts only one organization. To enforce sign-in for multiple organizations on Mac, configure the `registry.json` file after installation.

## [Method precedence](#method-precedence)

When multiple configuration methods exist on the same system, Docker Desktop uses this precedence order:

1. Registry key (Windows only)
2. Configuration profiles (Mac only)
3. plist file (Mac only)
4. registry.json file

## [Troubleshoot sign-in enforcement](#troubleshoot-sign-in-enforcement)

If sign-in enforcement doesn't work:

* Verify file locations and permissions
* Check that organization names use lowercase letters
* Restart Docker Desktop or reboot the system
* Confirm users are members of the specified organizations
* Update Docker Desktop to the latest version

----
url: https://docs.docker.com/reference/api/hub/latest.yaml
----

\# yaml-language-server: $schema=https\://raw\.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/main/schemas/v3.0/schema.yaml openapi: 3.0.3 info: title: Docker HUB API version: 2-beta x-logo: url: https\://docs.docker.com/assets/images/logo-docker-main.png href: /reference description: | Docker Hub is a service provided by Docker for finding and sharing container images with your team. It is the world's largest library and community for container images. In addition to the \[Docker Hub UI]\(https\://docs.docker.com/docker-hub/) and \[Docker Hub CLI tool]\(https\://github.com/docker/hub-tool#readme) (currently experimental), Docker provides an API that allows you to interact with Docker Hub. Browse through the Docker Hub API documentation to explore the supported endpoints. servers: - description: Docker HUB API x-audience: public url: https\://hub.docker.com tags: - name: changelog x-displayName: Changelog description: | See the \[Changelog]\(/reference/api/hub/changelog) for a summary of changes across Docker Hub API versions. - name: resources x-displayName: Resources description: | The following resources are available to interact with the documented API: - \[Docker Hub CLI tool]\(https\://github.com/docker/hub-tool#readme) (currently experimental) - name: rate-limiting x-displayName: Rate Limiting description: | The Docker Hub API is limited on the amount of requests you can perform per minute against it. If you haven't hit the limit, each request to the API will return the following headers in the response. - \`X-RateLimit-Limit\` - The limit of requests per minute. - \`X-RateLimit-Remaining\` - The remaining amount of calls within the limit period. - \`X-RateLimit-Reset\` - The unix timestamp of when the remaining resets. If you have hit the limit, you will receive a response status of \`429\` and the \`Retry-After\` header in the response. The \[\`Retry-After\` header]\(https\://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After) specifies the number of seconds to wait until you can call the API again. \*\*Note\*\*: These rate limits are separate from anti-abuse and Docker Hub download, or pull rate limiting. To learn more about Docker Hub pull rate limiting, see \[Usage and limits]\(https\://docs.docker.com/docker-hub/usage/). - name: authentication x-displayName: Authentication description: | Most Docker Hub API endpoints require you to authenticate using your Docker credentials before using them. Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your subscription (Personal, Pro, or Team) and your account's permissions. To learn more about the features available in each subscription and to upgrade your existing subscription, see \[Docker Pricing]\(https\://www\.docker.com/pricing?ref=Docs\&refAction=DocsApiHub). # Types The Docker Hub API supports the following authentication types. You must use each authentication type with the \[Create access token]\(#tag/authentication-api/operation/AuthCreateAccessToken) route to obtain a bearer token. ## Password Using a username and password is the most powerful, yet least secure way to authenticate with Docker as a user. It allows access to resources for the user without scopes. \_In general, it is recommended to use a personal access token (PAT) instead.\_ \_\*\*The password authentication type is not available if your organization has SSO enforced.\*\*\_ ## Personal Access Token (PAT) Using a username and PAT is the most secure way to authenticate with Docker as a user. PATs are scoped to specific resources and scopes. Currently, a PAT is a more secure password due to limited functionality. In the future, we may add fine-grained access like organization access tokens for enhanced usage and security. ## Organization Access Token (OAT) Organization access tokens are scoped to specific resources and scopes in an organization. They are managed by organization owners. These tokens are meant for automation and are not meant to be used by users. # Labels These labels will show up on routes in this reference that allow for use of bearer tokens issued from them. - name: authentication-api x-displayName: Authentication description: | The authentication endpoints allow you to authenticate with Docker Hub APIs. For more information, see \[Authentication]\(#tag/authentication). - name: access-tokens x-displayName: Personal Access Tokens description: | The Personal Access Token endpoints lets you manage personal access tokens. For more information, see \[Access Tokens]\(https\://docs.docker.com/security/access-tokens/). You can use a personal access token instead of a password in the \[Docker CLI]\(https\://docs.docker.com/engine/reference/commandline/cli/) or in the \[Create an authentication token]\(#operation/PostUsersLogin) route to obtain a bearer token. ### Scopes For each scope grouping (in this case "repo"), you only need to define 1 scope as any lower scopes are assumed. For example: If you define \`repo:write\`, the API assumes the scope of both \`repo:read\` \*and\* \`repo:public\_read\` as well. If you were to define both \`repo:write\` \*and\* \`repo:read\`, then \`repo:read\` is assumed by \`repo:write\` and ignored. \*\*\*Treat your personal access token like your password and keep it secret. You cannot retrieve your token after it is generated.\*\*\* - name: audit-logs x-displayName: Audit Logs description: | The Audit Logs API endpoints allow you to query audit log events across a namespace. For more information, see \[Audit Logs]\(https\://docs.docker.com/admin/activity-logs/). - name: org-settings x-displayName: Org Settings description: | The Org Settings API endpoints allow you to manage your organization's settings. - name: repositories x-displayName: Repositories description: | The repository endpoints allow you to access your repository's tags. - name: orgs x-displayName: Organizations x-audience: public description: | The organization endpoints allow you to interact with and manage your organizations. For more information, see \[Organization administration overview]\(https\://docs.docker.com/admin/organization/). - name: groups x-displayName: Groups (Teams) x-audience: public description: | The groups endpoints allow you to manage your organization's teams and their members. For more information, see \[Create and manage a team]\(https\://docs.docker.com/admin/organization/manage/manage-a-team/). - name: invites x-displayName: Invites x-audience: public description: | The invites endpoints allow you to manage invites for users to join your Docker organization. For more information, see \[Invite members]\(https\://docs.docker.com/admin/organization/manage/members/#invite-members). - name: scim x-displayName: SCIM x-audience: public description: | SCIM is a provisioning system that lets you manage users within your identity provider (IdP). For more information, see \[System for Cross-domain Identity management]\(https\://docs.docker.com/security/for-admins/provisioning/scim/). - name: org-access-tokens x-displayName: Organization Access Tokens x-audience: public description: | The organization access token endpoints allow you to manage organization access tokens (OATs). See \[Organization access tokens]\(https\://docs.docker.com/security/for-admins/access-tokens/) for more information. paths: /v2/users/login: post: tags: - authentication-api summary: Create an authentication token operationId: PostUsersLogin security: \[] deprecated: true description: | Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. The returned token is used in the HTTP Authorization header like \`Authorization: Bearer {TOKEN}\`. \_\*\*As of September 16, 2024, this route requires a personal access token (PAT) instead of a password if your organization has SSO enforced.\*\*\_

**Deprecated**: Use \[[Create access token](#tag/authentication-api/operation/AuthCreateAccessToken)] instead.

requestBody: content: application/json: schema: $ref: "#/components/schemas/UsersLoginRequest" description: Login details. required: true responses: "200": description: Authentication successful content: application/json: schema: $ref: "#/components/schemas/PostUsersLoginSuccessResponse" "401": description: Authentication failed or second factor required content: application/json: schema: $ref: "#/components/schemas/PostUsersLoginErrorResponse" /v2/users/2fa-login: post: tags: - authentication-api summary: Second factor authentication operationId: PostUsers2FALogin security: \[] description: | When a user has two-factor authentication (2FA) enabled, this is the second call to perform after \`/v2/users/login\` call. Creates and returns a bearer token in JWT format that you can use to authenticate with Docker Hub APIs. The returned token is used in the HTTP Authorization header like \`Authorization: Bearer {TOKEN}\`. Most Docker Hub APIs require this token either to consume or to get detailed information. For example, to list images in a private repository. requestBody: content: application/json: schema: $ref: "#/components/schemas/Users2FALoginRequest" description: Login details. required: true responses: "200": description: Authentication successful content: application/json: schema: $ref: "#/components/schemas/PostUsersLoginSuccessResponse" "401": description: Authentication failed content: application/json: schema: $ref: "#/components/schemas/PostUsers2FALoginErrorResponse" /v2/auth/token: post: tags: - authentication-api security: \[] summary: Create access token operationId: AuthCreateAccessToken description: | Creates and returns a short-lived access token in JWT format for use as a bearer when calling Docker APIs. If successful, the access token returned should be used in the HTTP Authorization header like \`Authorization: Bearer {access\_token}\`. \_\*\*If your organization has SSO enforced, you must use a personal access token (PAT) instead of a password.\*\*\_ requestBody: content: application/json: schema: description: Request to create access token type: object required: - identifier - secret properties: identifier: description: | The identifier of the account to create an access token for. If using a password or personal access token, this must be a username. If using an organization access token, this must be an organization name. type: string example: myusername secret: description: | The secret of the account to create an access token for. This can be a password, personal access token, or organization access token. type: string example: dckr\_pat\_124509ugsdjga93 responses: "200": description: Token created content: application/json: schema: $ref: "#/components/schemas/AuthCreateTokenResponse" "401": description: Authentication failed $ref: "#/components/responses/unauthorized" /v2/access-tokens: post: summary: Create personal access token description: Creates and returns a personal access token. tags: - access-tokens security: - bearerAuth: \[] requestBody: content: application/json: schema: $ref: "#/components/schemas/createAccessTokenRequest" required: true responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/createAccessTokensResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" get: summary: List personal access tokens description: Returns a paginated list of personal access tokens. tags: - access-tokens security: - bearerAuth: \[] parameters: - in: query name: page schema: type: number default: 1 - in: query name: page\_size schema: type: number default: 10 responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/getAccessTokensResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" /v2/access-tokens/{uuid}: parameters: - in: path name: uuid required: true schema: type: string patch: summary: Update personal access token description: | Updates a personal access token partially. You can either update the token's label or enable/disable it. tags: - access-tokens security: - bearerAuth: \[] requestBody: content: application/json: schema: $ref: "#/components/schemas/patchAccessTokenRequest" required: true responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/patchAccessTokenResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" get: summary: Get personal access token description: Returns a personal access token by UUID. tags: - access-tokens security: - bearerAuth: \[] responses: "200": description: OK content: application/json: schema: allOf: - $ref: "#/components/schemas/accessToken" - type: object properties: token: type: string example: "" "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" delete: summary: Delete personal access token description: | Deletes a personal access token permanently. This cannot be undone. tags: - access-tokens security: - bearerAuth: \[] responses: "204": description: A successful response. "401": $ref: "#/components/responses/Unauthorized" "404": $ref: "#/components/responses/NotFound" /v2/auditlogs/{account}/actions: get: summary: List audit log actions description: | List audit log actions for a namespace to be used as a filter for querying audit log events. operationId: AuditLogs\_ListAuditActions security: - bearerAuth: \[] responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/GetAuditActionsResponse" examples: response: value: actions: billing: actions: - name: plan.upgrade description: Occurs when your organization’s billing plan is upgraded to a higher tier plan. label: Plan Upgraded - name: plan.downgrade description: Occurs when your organization’s billing plan is downgraded to a lower tier plan. label: Plan Downgraded - name: plan.seat\_add description: Occurs when a seat is added to your organization’s billing plan. label: Seat Added - name: plan.seat\_remove description: Occurs when a seat is removed from your organization’s billing plan. label: Seat Removed - name: plan.cycle\_change description: Occurs when there is a change in the recurring interval that your organization is charged. label: Billing Cycle Changed - name: plan.downgrade\_cancel description: Occurs when a scheduled plan downgrade for your organization is canceled. label: Plan Downgrade Canceled - name: plan.seat\_removal\_cancel description: Occurs when a scheduled seat removal for an organization’s billing plan is canceled. label: Seat Removal Canceled - name: plan.upgrade.request description: Occurs when a user in your organization requests a plan upgrade. label: Plan Upgrade Requested - name: plan.downgrade.request description: Occurs when a user in your organization requests a plan downgrade. label: Plan Downgrade Requested - name: plan.seat\_add.request description: Occurs when a user in your organization requests an increase in the number of seats. label: Seat Addition Requested - name: plan.seat\_removal.request description: Occurs when a user in your organization requests a decrease in the number of seats. label: Seat Removal Requested - name: plan.cycle\_change.request description: Occurs when a user in your organization requests a change in the billing cycle. label: Billing Cycle Change Requested - name: plan.downgrade\_cancel.request description: Occurs when a user in your organization requests a cancellation of a scheduled plan downgrade. label: Plan Downgrade Cancellation Requested - name: plan.seat\_removal\_cancel.request description: Occurs when a user in your organization requests a cancellation of a scheduled seat removal. label: Seat Removal Cancellation Requested - name: plan.product\_change description: Occurs when there is a change in the product that your organization subscribes to. label: Billing Product Changed label: Billing enterprise: actions: - name: setting.policy.create description: Details of adding an admin settings policy label: Policy created - name: setting.policy.update description: Details of updating an admin settings policy label: Policy updated - name: setting.policy.delete description: Details of deleting an admin settings policy label: Policy deleted - name: setting.policy.transfer description: Details of transferring an admin settings policy to another owner label: Policy transferred - name: sso.connection.create description: Details of creating a new org/company SSO connection label: Create SSO Connection - name: sso.connection.update description: Details of updating an existing org/company SSO connection label: Update SSO Connection - name: sso.connection.delete description: Details of deleting an existing org/company SSO connection label: Delete SSO Connection - name: sso.connection.enforcement\_toggle description: Details of toggling enforcement on an existing org/company SSO connection label: Enforce SSO - name: sso.connection.scim\_toggle description: Details of toggling SCIM on an existing org/company SSO connection label: Enforce SCIM - name: sso.connection.scim\_token\_refresh description: Details of a SCIM token refresh on an existing org/company SSO connection label: Refresh SCIM Token - name: sso.connection.connection\_type\_change description: Details of a connection type change on an existing org/company SSO connection label: Change SSO Connection Type - name: sso.connection.jit\_toggle description: Details of a JIT toggle on an existing org/company SSO connection label: Toggle JIT provisioning label: Enterprise offload: actions: - name: lease.start description: Details of the started Offload lease. label: Offload lease start - name: lease.end description: Details of the ended Offload lease. label: Offload lease end label: Offload oidc: actions: - name: connection.create description: Details of creating an OIDC connection. label: OIDC connection created - name: connection.update description: Details of updating an OIDC connection. label: OIDC connection updated - name: connection.delete description: Details of deleting an OIDC connection. label: OIDC connection deleted label: OIDC org: actions: - name: create description: Activities related to the creation of a new organization label: Organization Created - name: member.add description: Details of the member added to your organization label: Organization Member Added - name: member.remove description: Details about the member removed from your organization label: Organization Member Removed - name: member.role.change description: Details about the role changed for a member in your organization label: Member Role Changed - name: member.invite.send description: Details of the member invited to your organization label: Org Member Invited - name: team.create description: Activities related to the creation of a team label: Organization Created - name: team.update description: Activities related to the modification of a team label: Organization Deleted - name: team.delete description: Activities related to the deletion of a team label: Organization Deleted - name: team.member.add description: Details of the member added to your team label: Team Member Added - name: team.member.remove description: Details of the member removed from your team label: Team Member Removed - name: domain.create description: Details of the single sign-on domain added to your organization label: Single Sign-On domain added - name: domain.verify description: Details of the single sign-on domain verified for your organization label: Single Sign-On domain verified - name: domain.delete description: Details of the single sign-on domain removed from your organization label: Single Sign-On domain deleted - name: domain.auto-provisioning.toggle description: Details of toggling the Auto-Provisioning feature on a domain on or off label: Organization Auto-Provisioning Toggled - name: settings.update description: Details related to the organization setting that was updated label: Organization Settings Updated - name: registry\_access.enabled description: Activities related to enabling Registry Access Management label: Registry Access Management enabled - name: registry\_access.disabled description: Activities related to disabling Registry Access Management label: Registry Access Management disabled - name: registry\_access.registry\_added description: Activities related to the addition of a registry label: Registry Access Management registry added - name: registry\_access.registry\_updated description: Details related to the registry that was updated label: Registry Access Management registry updated - name: registry\_access.registry\_removed description: Activities related to the removal of a registry label: Registry Access Management registry removed - name: access\_token.create description: Access token created in organization label: Access token created - name: access\_token.update description: Access token updated in organization label: Access token updated - name: access\_token.delete description: Access token deleted in organization label: Access token deleted - name: customrole.create description: A custom role was created label: Custom role created - name: customrole.update description: An existing custom role was updated label: Custom role updated - name: customrole.delete description: A custom role was deleted label: Custom role deleted - name: securepolicyconfigure.create description: A secure policy configuration was created label: Secure Policy Configuration created - name: securepolicyconfigure.update description: A secure policy configuration was updated label: Secure Policy Configuration updated - name: securepolicyconfigure.delete description: A secure policy configuration was deleted label: Secure Policy Configuration deleted - name: securepolicyclient.create description: A secure policy client was created label: Secure Policy Client created - name: securepolicyclient.update description: A secure policy client was updated label: Secure Policy Client updated - name: securepolicyclient.delete description: A secure policy client was deleted label: Secure Policy Client deleted - name: securepolicyprofile.create description: A secure policy profile was created label: Secure Policy Profile created - name: securepolicyprofile.update description: A secure policy profile was updated label: Secure Policy Profile updated - name: securepolicyprofile.delete description: A secure policy profile was deleted label: Secure Policy Profile deleted label: Organization repo: actions: - name: create description: Activities related to the creation of a new repository label: Repository Created - name: update description: Activities related to the modification of a repository label: Repository Updated - name: delete description: Activities related to the deletion of a repository label: Repository Deleted - name: change\_privacy description: Details related to the privacy policies that were updated label: Privacy Changed - name: category.updated description: Details related to updating a repository categories label: Categories updated - name: immutable.tags.updated description: Details related to updating tag immutability of a repository label: Tag immutability updated - name: tag.push description: Activities related to the tags pushed label: Tag Pushed - name: tag.delete description: Activities related to the tags deleted label: Tag Deleted label: Repository "429": description: "" content: application/json: schema: {} examples: response: value: detail: Rate limit exceeded error: false "500": description: "" content: application/json: schema: {} default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: account description: Namespace to query audit log actions for. in: path required: true schema: type: string tags: - audit-logs /v2/auditlogs/{account}: get: summary: List audit log events description: | List audit log events for a given namespace. operationId: AuditLogs\_ListAuditLogs security: - bearerAuth: \[] responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/GetAuditLogsResponse" examples: response: value: logs: - account: docker action: repo.tag.push name: docker/example actor: docker data: digest: sha256:c1ae9c435032a276f80220c7d9b40f76266bbe79243d34f9cda30b76fe114dfa tag: latest timestamp: "2021-02-19T01:34:35Z" action\_description: | pushed the tag latest with the digest sha256:c1ae9c435032a to the repository docker/example "429": description: "" content: application/json: schema: {} examples: response: value: detail: Rate limit exceeded error: false "500": description: "" content: application/json: schema: {} default: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/rpcStatus" parameters: - name: account description: Namespace to query audit logs for. in: path required: true schema: type: string - name: action description: | action name one of \["repo.tag.push", ...]. Optional parameter to filter specific audit log actions. in: query required: false schema: type: string - name: name description: | name. Optional parameter to filter audit log events to a specific name. For repository events, this is the name of the repository. For organization events, this is the name of the organization. For team member events, this is the username of the team member. in: query required: false schema: type: string - name: actor description: | actor name. Optional parameter to filter audit log events to the specific user who triggered the event. in: query required: false schema: type: string - name: from description: Start of the time window you wish to query audit events for. in: query required: false schema: type: string format: date-time - name: to description: End of the time window you wish to query audit events for. in: query required: false schema: type: string format: date-time - name: page description: page - specify page number. Page number to get. in: query required: false schema: type: integer format: int32 default: 1 - name: page\_size description: page\_size - specify page size. Number of events to return per page. in: query required: false schema: type: integer format: int32 default: 25 tags: - audit-logs /v2/orgs/{name}/settings: parameters: - in: path name: name description: Name of the organization. required: true schema: type: string get: summary: Get organization settings description: | Returns organization settings by name. tags: - org-settings security: - bearerAuth: \[] responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/orgSettings" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" put: summary: Update organization settings description: | Updates an organization's settings. Some settings are only used when the organization is on a business subscription. \*\*\*Only users with administrative privileges for the organization (owner role) can modify these settings.\*\*\* The following settings are only used on a business subscription: - \`restricted\_images\` tags: - org-settings security: - bearerAuth: \[] requestBody: content: application/json: schema: required: - restricted\_images properties: restricted\_images: allOf: - $ref: "#/components/schemas/restricted\_images" - type: object required: - enabled - allow\_official\_images - allow\_verified\_publishers required: true responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/orgSettings" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v2/orgs/{name}/access-tokens: post: summary: Create access token description: | Create an access token for an organization. tags: - org-access-tokens security: - bearerAuth: \[] requestBody: content: application/json: schema: $ref: "#/components/schemas/createOrgAccessTokenRequest" required: true responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/createOrgAccessTokenResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" get: summary: List access tokens description: | List access tokens for an organization. tags: - org-access-tokens security: - bearerAuth: \[] parameters: - in: query name: page schema: type: number default: 1 - in: query name: page\_size schema: type: number default: 10 responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/getOrgAccessTokensResponse" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v2/orgs/{org\_name}/access-tokens/{access\_token\_id}: parameters: - $ref: "#/components/parameters/org\_name" - in: path name: access\_token\_id required: true schema: type: string description: The ID of the access token to retrieve example: "a7a5ef25-8889-43a0-8cc7-f2a94268e861" get: summary: Get access token description: | Get details of a specific access token for an organization. tags: - org-access-tokens security: - bearerAuth: \[] responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/getOrgAccessTokenResponse" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" patch: summary: Update access token description: | Update a specific access token for an organization. tags: - org-access-tokens security: - bearerAuth: \[] requestBody: content: application/json: schema: $ref: "#/components/schemas/updateOrgAccessTokenRequest" required: true responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/updateOrgAccessTokenResponse" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" delete: summary: Delete access token description: | Delete a specific access token for an organization. This action cannot be undone. tags: - org-access-tokens security: - bearerAuth: \[] responses: "204": description: Access token deleted successfully "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v2/namespaces/{namespace}/repositories/{repository}/tags: parameters: - $ref: "#/components/parameters/namespace" - $ref: "#/components/parameters/repository" get: operationId: ListRepositoryTags summary: List repository tags tags: - repositories security: - bearerAuth: \[] parameters: - in: query name: page required: false schema: type: integer description: Page number to get. Defaults to 1. - in: query name: page\_size required: false schema: type: integer description: Number of items to get per page. Defaults to 10. Max of 100. responses: "200": $ref: "#/components/responses/list\_tags" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" head: summary: Check repository tags tags: - repositories security: - bearerAuth: \[] responses: "200": description: Repository contains tags "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}: parameters: - $ref: "#/components/parameters/namespace" - $ref: "#/components/parameters/repository" - $ref: "#/components/parameters/tag" get: operationId: GetRepositoryTag summary: Read repository tag tags: - repositories security: - bearerAuth: \[] responses: "200": $ref: "#/components/responses/get\_tag" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" head: summary: Check repository tag tags: - repositories security: - bearerAuth: \[] responses: "200": description: Repository tag exists "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" /v2/namespaces/{namespace}/repositories/{repository}/immutabletags: parameters: - $ref: "#/components/parameters/namespace" - $ref: "#/components/parameters/repository" patch: operationId: UpdateRepositoryImmutableTags summary: "Update repository immutable tags" description: | Updates the immutable tags configuration for this repository. \*\*Only users with administrative privileges for the repository can modify these settings.\*\* tags: - repositories security: - bearerAuth: \[] requestBody: $ref: "#/components/requestBodies/update\_repository\_immutable\_tags\_request" responses: 200: $ref: "#/components/responses/update\_repository\_immutable\_tags\_response" 400: $ref: "#/components/responses/bad\_request" 401: $ref: "#/components/responses/unauthorized" 403: $ref: "#/components/responses/forbidden" 404: $ref: "#/components/responses/not\_found" /v2/namespaces/{namespace}/repositories/{repository}/immutabletags/verify: parameters: - $ref: "#/components/parameters/namespace" - $ref: "#/components/parameters/repository" post: operationId: VerifyRepositoryImmutableTags summary: "Verify repository immutable tags" description: | Validates the immutable tags regex pass in parameter and returns a list of tags matching it in this repository. \*\*Only users with administrative privileges for the repository call this endpoint.\*\* tags: - repositories security: - bearerAuth: \[] requestBody: $ref: "#/components/requestBodies/immutable\_tags\_verify\_request" responses: 200: $ref: "#/components/responses/immutable\_tags\_verify\_response" 400: $ref: "#/components/responses/bad\_request" 401: $ref: "#/components/responses/unauthorized" 403: $ref: "#/components/responses/forbidden" 404: $ref: "#/components/responses/not\_found" /v2/repositories/{namespace}/{repository}/groups: parameters: - $ref: "#/components/parameters/namespace" - $ref: "#/components/parameters/repository" post: summary: Assign a group (Team) to a repository for access tags: - repositories operationId: CreateRepositoryGroup security: - bearerAuth: \[] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RepositoryGroupCreationRequest" example: group\_id: 12345 permission: "write" responses: "200": description: Repository group permission created successfully content: application/json: schema: $ref: "#/components/schemas/RepositoryGroup" example: group\_name: "developers" permission: "write" group\_id: 12345 "400": description: Bad Request - Invalid request parameters content: application/json: schema: $ref: "#/components/schemas/error" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/NotFound" /v2/namespaces/{namespace}/repositories: parameters: - $ref: "#/components/parameters/namespace" get: operationId: listNamespaceRepositories summary: List repositories in a namespace description: | Returns a list of repositories within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. tags: - repositories security: - bearerAuth: \[] - {} # Allow anonymous access for public repositories parameters: - in: query name: page required: false schema: type: integer minimum: 1 default: 1 description: Page number to get. Defaults to 1. - in: query name: page\_size required: false schema: type: integer minimum: 1 maximum: 100 default: 10 description: Number of repositories to get per page. Defaults to 10. Max of 100. - in: query name: name required: false schema: type: string description: Filter repositories by name (partial match). - in: query name: ordering required: false schema: type: string enum: - name - -name - last\_updated - -last\_updated - pull\_count - -pull\_count description: | Order repositories by the specified field. Prefix with '-' for descending order. Available options: - \`name\` / \`-name\`: Repository name (ascending/descending) - \`last\_updated\` / \`-last\_updated\`: Last update time (ascending/descending) - \`pull\_count\` / \`-pull\_count\`: Number of pulls (ascending/descending) responses: "200": description: List of repositories content: application/json: schema: $ref: "#/components/schemas/list\_repositories\_response" examples: repositories\_list: value: count: 287 next: "https\://hub.docker.com/v2/namespaces/docker/repositories?page=2\&page\_size=2" previous: null results: - name: "highland\_builder" namespace: "docker" repository\_type: "image" status: 1 status\_description: "active" description: "Image for performing Docker build requests" is\_private: false star\_count: 7 pull\_count: 15722123 last\_updated: "2023-06-20T10:44:45.459826Z" last\_modified: "2024-10-16T13:48:34.145251Z" date\_registered: "2015-05-19T21:13:35.937763Z" affiliation: "" media\_types: - "application/octet-stream" - "application/vnd.docker.container.image.v1+json" - "application/vnd.docker.distribution.manifest.v1+prettyjws" content\_types: - "unrecognized" - "image" categories: - name: "Languages & frameworks" slug: "languages-and-frameworks" - name: "Integration & delivery" slug: "integration-and-delivery" - name: "Operating systems" slug: "operating-systems" storage\_size: 488723114800 - name: "whalesay" namespace: "docker" repository\_type: null status: 1 status\_description: "active" description: "An image for use in the Docker demo tutorial" is\_private: false star\_count: 757 pull\_count: 130737682 last\_updated: "2015-06-19T19:06:27.388123Z" last\_modified: "2024-10-16T13:48:34.145251Z" date\_registered: "2015-06-09T18:16:36.527329Z" affiliation: "" media\_types: - "application/vnd.docker.distribution.manifest.v1+prettyjws" content\_types: - "image" categories: - name: "Languages & frameworks" slug: "languages-and-frameworks" - name: "Integration & delivery" slug: "integration-and-delivery" storage\_size: 103666708 "400": description: Bad Request - Invalid request parameters content: application/json: schema: $ref: "#/components/schemas/error" examples: invalid\_ordering: summary: Invalid ordering value value: fields: ordering: \[ "Invalid ordering value. Must be one of: name, -name, last\_updated, -last\_updated, pull\_count, -pull\_count", ] text: "Invalid ordering value" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": description: Page not found - occurs when requesting a page number \`>1\` that exceeds the available results content: application/json: schema: $ref: "#/components/schemas/error" post: summary: Create a new repository description: | Creates a new repository within the specified namespace. The repository will be created with the provided metadata including name, description, and privacy settings. operationId: CreateRepository tags: - repositories security: - BearerAuth: \[] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/repo\_creation\_request" example: name: "my-app" namespace: "myorganization" description: "A sample application repository" full\_description: "This is a comprehensive description of my application repository that contains additional details about the project." registry: "docker.io" is\_private: false responses: 201: description: Repository created successfully content: application/json: schema: $ref: "#/components/schemas/repository\_info" example: name: "my-app" namespace: "myorganization" repository\_type: "image" status: 1 status\_description: "Active" description: "A sample application repository" is\_private: false is\_automated: false star\_count: 0 pull\_count: 0 last\_updated: "2025-01-20T10:30:00Z" date\_registered: "2025-01-20T10:30:00Z" collaborator\_count: 0 hub\_user: "myorganization" has\_starred: false full\_description: "This is a comprehensive description of my application repository that contains additional details about the project." media\_types: \[] content\_types: \[] categories: \[] immutable\_tags\_settings: enabled: false rules: \[] storage\_size: null source: null 400: $ref: "#/components/responses/bad\_request" 401: $ref: "#/components/responses/unauthorized" 403: $ref: "#/components/responses/forbidden" 404: $ref: "#/components/responses/not\_found" 500: $ref: "#/components/responses/internal\_error" /v2/namespaces/{namespace}/repositories/{repository}: parameters: - $ref: "#/components/parameters/namespace" - $ref: "#/components/parameters/repository" get: operationId: GetRepository summary: Get repository in a namespace description: | Returns a repository within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. tags: - repositories security: - bearerAuth: \[] - {} # Allow anonymous access for public repositories responses: 200: content: application/json: schema: $ref: "#/components/schemas/repository\_info" example: name: "my-app" namespace: "myorganization" repository\_type: "image" status: 1 status\_description: "Active" description: "A sample application repository" is\_private: false is\_automated: false star\_count: 0 pull\_count: 0 last\_updated: "2025-01-20T10:30:00Z" date\_registered: "2025-01-20T10:30:00Z" collaborator\_count: 0 hub\_user: "myorganization" has\_starred: false full\_description: "This is a comprehensive description of my application repository that contains additional details about the project." media\_types: \[] content\_types: \[] categories: \[] immutable\_tags\_settings: enabled: false rules: \[] storage\_size: null source: null 401: $ref: "#/components/responses/unauthorized" 403: $ref: "#/components/responses/forbidden" 404: $ref: "#/components/responses/not\_found" 500: $ref: "#/components/responses/internal\_error" head: operationId: CheckRepository summary: Check repository in a namespace description: | Check a repository within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. tags: - repositories security: - bearerAuth: \[] - {} # Allow anonymous access for public repositories responses: 200: content: application/json: schema: $ref: "#/components/schemas/repository\_info" example: name: "my-app" namespace: "myorganization" repository\_type: "image" status: 1 status\_description: "Active" description: "A sample application repository" is\_private: false is\_automated: false star\_count: 0 pull\_count: 0 last\_updated: "2025-01-20T10:30:00Z" date\_registered: "2025-01-20T10:30:00Z" collaborator\_count: 0 hub\_user: "myorganization" has\_starred: false full\_description: "This is a comprehensive description of my application repository that contains additional details about the project." media\_types: \[] content\_types: \[] categories: \[] immutable\_tags\_settings: enabled: false rules: \[] storage\_size: null source: null 401: $ref: "#/components/responses/unauthorized" 403: $ref: "#/components/responses/forbidden" 404: $ref: "#/components/responses/not\_found" 500: $ref: "#/components/responses/internal\_error" /v2/orgs/{org\_name}/members: parameters: - $ref: "#/components/parameters/org\_name" - $ref: "#/components/parameters/search" - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/page\_size" - $ref: "#/components/parameters/invites" - $ref: "#/components/parameters/type" - $ref: "#/components/parameters/role" get: summary: List org members description: | Returns a list of members for an organization. \_The following fields are only visible to orgs with insights enabled.\_ - \`last\_logged\_in\_at\` - \`last\_seen\_at\` - \`last\_desktop\_version\` To make visible, please see \[View Insights for organization users]\(https\://docs.docker.com/admin/insights/#view-insights-for-organization-users). tags: - orgs security: - bearerAuth: \[] responses: "200": description: List of members content: application/json: schema: type: array items: $ref: "#/components/schemas/org\_member\_paginated" "400": $ref: "#/components/responses/bad\_request" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" /v2/orgs/{org\_name}/members/export: parameters: - $ref: "#/components/parameters/org\_name" get: summary: Export org members CSV description: | Export members of an organization as a CSV tags: - orgs security: - bearerAuth: \[] responses: "200": description: Exported members content: text/csv: schema: type: array items: type: object required: - Name - Username - Email - Type - Role - Date Joined properties: Name: type: string description: First and last name of the member Username: type: string description: Username of the member Email: type: string description: Email address of the member Type: type: string description: Type of the member enum: - Invitee - User Permission: type: string description: Permission of the member enum: - Owner - Member Teams: type: string description: Comma-separated list of teams the member is part of example: team-1, team-2 Date Joined: type: string description: Date the member joined the organization example: 2020-01-01 15:00:51.193355 +0000 UTC headers: Content-Disposition: schema: type: string example: attachment;filename="{org\_name}-members-{timestamp}.csv" "400": $ref: "#/components/responses/bad\_request" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" /v2/orgs/{org\_name}/members/{username}: x-audience: public parameters: - $ref: "#/components/parameters/org\_name" - $ref: "#/components/parameters/username" put: summary: Update org member (role) description: | Updates the role of a member in the organization. \*\*\*Only users in the "owners" group of the organization can use this endpoint.\*\*\* tags: - orgs security: - bearerAuth: \[] requestBody: required: true content: application/json: schema: required: - role properties: role: type: string description: Role of the member enum: - owner - editor - member responses: "200": description: Member role updated content: application/json: schema: $ref: "#/components/schemas/org\_member" "400": $ref: "#/components/responses/bad\_request" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" delete: summary: Remove member from org description: | Removes the member from the org, ie. all groups in the org, unless they're the last owner tags: - orgs security: - bearerAuth: \[] responses: "204": description: Member removed successfully "400": $ref: "#/components/responses/bad\_request" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" /v2/orgs/{org\_name}/invites: x-audience: public parameters: - $ref: "#/components/parameters/org\_name" get: summary: List org invites description: | Return all pending invites for a given org, only team owners can call this endpoint tags: - invites security: - bearerAuth: \[] responses: "200": description: "" content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/invite" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" /v2/orgs/{org\_name}/groups: x-audience: public parameters: - $ref: "#/components/parameters/org\_name" get: summary: Get groups of an organization description: | tags: - groups security: - bearerAuth: \[] parameters: - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/page\_size" - in: query name: username schema: type: string description: Get groups for the specified username in the organization. - in: query name: search schema: type: string description: Get groups for the specified group in the organization. responses: "200": description: "" content: application/json: schema: properties: count: type: number example: 1 next: type: string example: null previous: type: string example: null results: type: array items: $ref: "#/components/schemas/org\_group" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" post: summary: Create a new group description: | Create a new group within an organization. tags: - groups security: - bearerAuth: \[] requestBody: content: application/json: schema: required: - name properties: name: type: string description: type: string responses: "201": description: Group created successfully content: application/json: schema: $ref: "#/components/schemas/org\_group" "400": $ref: "#/components/responses/bad\_request" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" /v2/orgs/{org\_name}/groups/{group\_name}: x-audience: public parameters: - $ref: "#/components/parameters/org\_name" - $ref: "#/components/parameters/group\_name" get: summary: Get a group of an organization description: | tags: - groups security: - bearerAuth: \[] responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/org\_group" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" put: summary: Update the details for an organization group description: | tags: - groups security: - bearerAuth: \[] requestBody: content: application/json: schema: required: - name properties: name: type: string description: type: string responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/org\_group" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" patch: summary: Update some details for an organization group description: | tags: - groups security: - bearerAuth: \[] requestBody: content: application/json: schema: properties: name: type: string description: type: string responses: "200": description: "" content: application/json: schema: $ref: "#/components/schemas/org\_group" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" delete: summary: Delete an organization group description: | tags: - groups security: - bearerAuth: \[] responses: "204": description: Group deleted successfully "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" /v2/orgs/{org\_name}/groups/{group\_name}/members: x-audience: public get: security: - bearerAuth: \[] parameters: - $ref: "#/components/parameters/org\_name" - $ref: "#/components/parameters/group\_name" - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/page\_size" - in: query name: search schema: type: string description: Search members by username, full\_name or email. summary: List members of a group description: | List the members (users) that are in a group. If user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails. tags: - groups responses: "200": description: "" content: application/json: schema: properties: count: type: number example: 1 next: type: string example: null previous: type: string example: null results: type: array items: $ref: "#/components/schemas/group\_member" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" post: parameters: - $ref: "#/components/parameters/org\_name" - $ref: "#/components/parameters/group\_name" summary: Add a member to a group description: | tags: - groups security: - bearerAuth: \[] requestBody: $ref: "#/components/requestBodies/add\_member\_to\_org\_group" responses: "200": description: OK "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" "500": $ref: "#/components/responses/internal\_error" /v2/orgs/{org\_name}/groups/{group\_name}/members/{username}: x-audience: public parameters: - $ref: "#/components/parameters/org\_name" - $ref: "#/components/parameters/group\_name" - $ref: "#/components/parameters/username" delete: summary: Remove a user from a group description: | tags: - groups security: - bearerAuth: \[] responses: "204": description: User removed successfully "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" /v2/invites/{id}: x-audience: public parameters: - in: path name: id required: true schema: type: string delete: summary: Cancel an invite description: | Mark the invite as cancelled so it doesn't show up on the list of pending invites tags: - invites security: - bearerAuth: \[] responses: "204": description: "" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" /v2/invites/{id}/resend: x-audience: public parameters: - in: path name: id schema: type: string required: true patch: summary: Resend an invite description: | Resend a pending invite to the user, any org owner can resend an invite tags: - invites security: - bearerAuth: \[] responses: "204": description: "" "401": $ref: "#/components/responses/unauthorized" "403": $ref: "#/components/responses/forbidden" "404": $ref: "#/components/responses/not\_found" /v2/invites/bulk: x-audience: public parameters: - $ref: "#/components/parameters/bulk\_invite" post: summary: Bulk create invites description: | Create multiple invites by emails or DockerIDs. Only a team owner can create invites. tags: - invites requestBody: $ref: "#/components/requestBodies/bulk\_invite\_request" security: - bearerAuth: \[] responses: "202": description: Accepted content: application/json: schema: type: object properties: invitees: $ref: "#/components/schemas/bulk\_invite" "400": $ref: "#/components/responses/bad\_request" "409": $ref: "#/components/responses/conflict" /v2/scim/2.0/ServiceProviderConfig: x-audience: public get: summary: Get service provider config description: | Returns a service provider config for Docker's configuration. tags: - scim security: - bearerSCIMAuth: \[] responses: "200": $ref: "#/components/responses/scim\_get\_service\_provider\_config\_resp" "401": $ref: "#/components/responses/scim\_unauthorized" "500": $ref: "#/components/responses/scim\_error" /v2/scim/2.0/ResourceTypes: x-audience: public get: summary: List resource types description: | Returns all resource types supported for the SCIM configuration. tags: - scim security: - bearerSCIMAuth: \[] responses: "200": $ref: "#/components/responses/scim\_get\_resource\_types\_resp" "401": $ref: "#/components/responses/scim\_unauthorized" "500": $ref: "#/components/responses/scim\_error" /v2/scim/2.0/ResourceTypes/{name}: x-audience: public get: summary: Get a resource type description: | Returns a resource type by name. tags: - scim parameters: - name: name in: path schema: type: string example: User required: true security: - bearerSCIMAuth: \[] responses: "200": $ref: "#/components/responses/scim\_get\_resource\_type\_resp" "401": $ref: "#/components/responses/scim\_unauthorized" "404": $ref: "#/components/responses/scim\_not\_found" "500": $ref: "#/components/responses/scim\_error" /v2/scim/2.0/Schemas: x-audience: public get: summary: List schemas description: | Returns all schemas supported for the SCIM configuration. tags: - scim security: - bearerSCIMAuth: \[] responses: "200": $ref: "#/components/responses/scim\_get\_schemas\_resp" "401": $ref: "#/components/responses/scim\_unauthorized" "500": $ref: "#/components/responses/scim\_error" /v2/scim/2.0/Schemas/{id}: x-audience: public get: summary: Get a schema description: | Returns a schema by ID. tags: - scim parameters: - name: id in: path schema: type: string example: urn:ietf:params:scim:schemas:core:2.0:User required: true security: - bearerSCIMAuth: \[] responses: "200": $ref: "#/components/responses/scim\_get\_schema\_resp" "401": $ref: "#/components/responses/scim\_unauthorized" "404": $ref: "#/components/responses/scim\_not\_found" "500": $ref: "#/components/responses/scim\_error" /v2/scim/2.0/Users: x-audience: public get: summary: List users description: | Returns paginated users for an organization. Use \`startIndex\` and \`count\` query parameters to receive paginated results. \*\*Sorting:\*\* Sorting allows you to specify the order in which resources are returned by specifying a combination of \`sortBy\` and \`sortOrder\` query parameters. The \`sortBy\` parameter specifies the attribute whose value will be used to order the returned responses. The \`sortOrder\` parameter defines the order in which the \`sortBy\` parameter is applied. Allowed values are "ascending" and "descending". \*\*Filtering:\*\* You can request a subset of resources by specifying the \`filter\` query parameter containing a filter expression. Attribute names and attribute operators used in filters are case insensitive. The filter parameter must contain at least one valid expression. Each expression must contain an attribute name followed by an attribute operator and an optional value. Supported operators are listed below. - \`eq\` equal - \`ne\` not equal - \`co\` contains - \`sw\` starts with - \`and\` Logical "and" - \`or\` Logical "or" - \`not\` "Not" function - \`()\` Precedence grouping tags: - scim security: - bearerSCIMAuth: \[] parameters: - name: startIndex in: query schema: type: integer minimum: 1 description: "" example: 1 - name: count in: query schema: type: integer minimum: 1 maximum: 200 description: "" example: 10 - name: filter in: query schema: type: string description: "" example: userName eq "jon.snow\@docker.com" - $ref: "#/components/parameters/scim\_attributes" - name: sortOrder in: query schema: type: string enum: - ascending - descending - name: sortBy in: query schema: type: string description: User attribute to sort by. example: userName responses: "200": $ref: "#/components/responses/scim\_get\_users\_resp" "400": $ref: "#/components/responses/scim\_bad\_request" "401": $ref: "#/components/responses/scim\_unauthorized" "403": $ref: "#/components/responses/scim\_forbidden" "404": $ref: "#/components/responses/scim\_not\_found" "500": $ref: "#/components/responses/scim\_error" post: summary: Create user description: | Creates a user. If the user already exists by email, they are assigned to the organization on the "company" team. tags: - scim security: - bearerSCIMAuth: \[] requestBody: $ref: "#/components/requestBodies/scim\_create\_user\_request" responses: "201": $ref: "#/components/responses/scim\_create\_user\_resp" "400": $ref: "#/components/responses/scim\_bad\_request" "401": $ref: "#/components/responses/scim\_unauthorized" "403": $ref: "#/components/responses/scim\_forbidden" "404": $ref: "#/components/responses/scim\_not\_found" "409": $ref: "#/components/responses/scim\_conflict" "500": $ref: "#/components/responses/scim\_error" /v2/scim/2.0/Users/{id}: x-audience: public parameters: - $ref: "#/components/parameters/scim\_user\_id" get: summary: Get a user description: | Returns a user by ID. tags: - scim security: - bearerSCIMAuth: \[] responses: "200": $ref: "#/components/responses/scim\_get\_user\_resp" "400": $ref: "#/components/responses/scim\_bad\_request" "401": $ref: "#/components/responses/scim\_unauthorized" "403": $ref: "#/components/responses/scim\_forbidden" "404": $ref: "#/components/responses/scim\_not\_found" "500": $ref: "#/components/responses/scim\_error" put: summary: Update a user description: | Updates a user. This route is used to change the user's name, activate, and deactivate the user. tags: - scim security: - bearerSCIMAuth: \[] requestBody: $ref: "#/components/requestBodies/scim\_update\_user\_request" responses: "200": $ref: "#/components/responses/scim\_update\_user\_resp" "400": $ref: "#/components/responses/scim\_bad\_request" "401": $ref: "#/components/responses/scim\_unauthorized" "403": $ref: "#/components/responses/scim\_forbidden" "404": $ref: "#/components/responses/scim\_not\_found" "409": $ref: "#/components/responses/scim\_conflict" "500": $ref: "#/components/responses/scim\_error" components: responses: BadRequest: description: Bad Request content: application/json: schema: $ref: "#/components/schemas/ValueError" Unauthorized: description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/Error" Forbidden: description: Forbidden content: application/json: schema: $ref: "#/components/schemas/Error" NotFound: description: Not Found content: application/json: schema: $ref: "#/components/schemas/Error" list\_tags: description: list repository tags content: application/json: schema: $ref: "#/components/schemas/paginated\_tags" get\_tag: description: repository tag content: application/json: schema: $ref: "#/components/schemas/tag" bad\_request: description: Bad Request content: application/json: schema: $ref: "#/components/schemas/error" unauthorized: description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/error" forbidden: description: Forbidden content: application/json: schema: $ref: "#/components/schemas/error" not\_found: description: Not Found content: application/json: schema: $ref: "#/components/schemas/error" conflict: description: Conflict content: application/json: schema: $ref: "#/components/schemas/error" internal\_error: description: Internal content: application/json: schema: $ref: "#/components/schemas/error" scim\_bad\_request: description: Bad Request content: application/scim+json: schema: allOf: - $ref: "#/components/schemas/scim\_error" - properties: status: example: "400" scimType: type: string description: Some types of errors will return this per the specification. scim\_unauthorized: description: Unauthorized content: application/scim+json: schema: allOf: - $ref: "#/components/schemas/scim\_error" - properties: status: example: "401" scim\_forbidden: description: Forbidden content: application/scim+json: schema: allOf: - $ref: "#/components/schemas/scim\_error" - properties: status: example: "403" scim\_not\_found: description: Not Found content: application/scim+json: schema: allOf: - $ref: "#/components/schemas/scim\_error" - properties: status: example: "404" scim\_conflict: description: Conflict content: application/scim+json: schema: allOf: - $ref: "#/components/schemas/scim\_error" - properties: status: example: "409" scim\_error: description: Internal Error content: application/scim+json: schema: allOf: - $ref: "#/components/schemas/scim\_error" - properties: status: example: "500" scim\_get\_service\_provider\_config\_resp: description: "" content: application/scim+json: schema: $ref: "#/components/schemas/scim\_service\_provider\_config" scim\_get\_resource\_types\_resp: description: "" content: application/scim+json: schema: type: object properties: schemas: type: array items: type: string example: urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 resources: type: array items: $ref: "#/components/schemas/scim\_resource\_type" scim\_get\_resource\_type\_resp: description: "" content: application/scim+json: schema: $ref: "#/components/schemas/scim\_resource\_type" scim\_get\_schemas\_resp: description: "" content: application/scim+json: schema: type: object properties: schemas: type: array items: type: string example: urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 resources: type: array items: $ref: "#/components/schemas/scim\_schema" scim\_get\_schema\_resp: description: "" content: application/scim+json: schema: $ref: "#/components/schemas/scim\_schema" scim\_get\_users\_resp: description: "" content: application/scim+json: schema: type: object properties: schemas: type: array items: type: string example: - urn:ietf:params:scim:api:messages:2.0:ListResponse totalResults: type: integer example: 1 startIndex: type: integer example: 1 itemsPerPage: type: integer example: 10 resources: type: array items: $ref: "#/components/schemas/scim\_user" scim\_create\_user\_resp: description: "" content: application/scim+json: schema: $ref: "#/components/schemas/scim\_user" scim\_get\_user\_resp: description: "" content: application/scim+json: schema: $ref: "#/components/schemas/scim\_user" scim\_update\_user\_resp: description: "" content: application/scim+json: schema: $ref: "#/components/schemas/scim\_user" update\_repository\_immutable\_tags\_response: description: "" content: application/json: schema: $ref: "#/components/schemas/repository\_info" immutable\_tags\_verify\_response: description: "" content: application/json: schema: $ref: "#/components/schemas/immutable\_tags\_verify\_response" schemas: update\_repository\_immutable\_tags\_request: type: object properties: immutable\_tags: type: boolean description: Whether immutable tags are enabled immutable\_tags\_rules: type: array items: type: string description: List of immutable tag rules example: - "v.\*" - ".\*-RELEASE" required: - immutable\_tags - immutable\_tags\_rules repo\_creation\_request: type: object required: - name - namespace properties: name: type: string description: | The name of the repository. Must be 2-255 characters long and may only include alphanumeric characters, periods (.), underscores (\_), or hyphens (-). Letters must be lowercase. minLength: 2 maxLength: 255 pattern: "^\[a-z0-9]+(?:\[.\_-]\[a-z0-9]+)\*$" example: "my-app" namespace: type: string description: The namespace where the repository will be created example: "myorganization" description: type: string description: Short description of the repository maxLength: 100 example: "A sample application repository" full\_description: type: string description: Detailed description of the repository maxLength: 25000 example: "This is a comprehensive description of my application repository that contains additional details about the project, its purpose, usage instructions, and other relevant information." registry: type: string description: The registry where the repository will be hosted example: "docker.io" is\_private: type: boolean description: Whether the repository should be private default: false example: false RepositoryGroupCreationRequest: type: object required: - group\_id - permission properties: group\_id: type: integer format: int64 description: The ID of the organization group to grant access to example: 12345 permission: type: string description: | The permission level to grant to the group: - read: Can view and pull from the repository - write: Can view, pull, and push to the repository - admin: Can view, pull, push, and manage repository settings enum: \["read", "write", "admin"] example: "write" RepositoryGroup: type: object properties: group\_name: type: string description: The name of the group example: "developers" permission: type: string description: The permission level granted to the group enum: \["read", "write", "admin"] example: "write" group\_id: type: integer format: int64 description: The ID of the group example: 12345 repository\_info: type: object properties: user: type: string description: Username of the repository owner name: type: string description: Repository name namespace: type: string description: Repository namespace repository\_type: type: string nullable: true description: Type of the repository status: type: integer description: Repository status code status\_description: type: string description: Description of the repository status description: type: string description: Short description of the repository is\_private: type: boolean description: Whether the repository is private is\_automated: type: boolean description: Whether the repository has automated builds star\_count: type: integer format: int64 description: Number of stars pull\_count: type: integer format: int64 description: Number of pulls last\_updated: type: string format: date-time example: "2021-01-05T21:06:53.506400Z" description: ISO 8601 timestamp of when repository was last updated last\_modified: type: string format: date-time example: "2021-01-05T21:06:53.506400Z" nullable: true description: ISO 8601 timestamp of when repository was last modified date\_registered: type: string format: date-time example: "2021-01-05T21:06:53.506400Z" description: ISO 8601 timestamp of when repository was created collaborator\_count: type: integer format: int64 description: Number of collaborators affiliation: type: string nullable: true description: Repository affiliation hub\_user: type: string nullable: true description: Hub user information has\_starred: type: boolean description: Whether the current user has starred this repository full\_description: type: string nullable: true description: Full description of the repository permissions: $ref: "#/components/schemas/repo\_permissions" media\_types: type: array items: type: string nullable: true description: Supported media types content\_types: type: array items: type: string description: Supported content types categories: type: array items: $ref: "#/components/schemas/category" description: Repository categories immutable\_tags\_settings: $ref: "#/components/schemas/immutable\_tags\_settings" storage\_size: type: integer format: int64 nullable: true description: Storage size in bytes source: type: string nullable: true description: Source of the repository, where it was created from required: - user - name - namespace - status - status\_description - description - is\_private - is\_automated - star\_count - pull\_count - last\_updated - date\_registered - collaborator\_count - has\_starred - permissions - media\_types - content\_types - categories - immutable\_tags\_settings repo\_permissions: type: object properties: read: type: boolean description: Read permission write: type: boolean description: Write permission admin: type: boolean description: Admin permission required: - read - write - admin immutable\_tags\_settings: type: object properties: enabled: type: boolean description: Whether immutable tags are enabled rules: type: array items: type: string description: List of immutable tag rules required: - enabled - rules immutable\_tags\_verify\_request: type: object properties: regex: type: string pattern: '^\[a-z0-9]+((\\\\.|\_|\_\_|-+)\[a-z0-9]+)\*(\\\\/\[a-z0-9]+((\\\\.|\_|\_\_|-+)\[a-z0-9]+)\*)\*$' description: 'Immutable tags rule regex pattern. Must match format: \[a-z0-9]+((\\\\.|\_|\_\_|-+)\[a-z0-9]+)\*(\\\\/\[a-z0-9]+((\\\\.|\_|\_\_|-+)\[a-z0-9]+)\*)\*' example: "v.\*" required: - regex immutable\_tags\_verify\_response: type: object properties: tags: type: array items: type: string description: List of tags that match the provided regex pattern example: - "v1.0.0" - "v2.1.3" - "latest" required: - tags repository\_list\_entry: type: object properties: name: type: string description: Name of the repository example: "hello-world" namespace: type: string description: Namespace (organization or username) that owns the repository example: "docker" repository\_type: type: string description: Type of repository enum: - image - plugin - null example: "image" nullable: true status: type: integer description: Repository status code example: 1 status\_description: type: string description: Human-readable repository status enum: - active - inactive example: "active" description: type: string description: Repository description nullable: true example: "Hello World! (an example of minimal Dockerization)" is\_private: type: boolean description: Whether the repository is private example: false star\_count: type: integer description: Number of users who starred this repository minimum: 0 example: 1234 pull\_count: type: integer description: Total number of pulls for this repository minimum: 0 example: 50000000 last\_updated: type: string format: date-time description: ISO 8601 timestamp of when the repository was last updated example: "2023-12-01T10:30:00Z" nullable: true last\_modified: type: string format: date-time description: ISO 8601 timestamp of when the repository was last modified example: "2023-12-01T10:30:00Z" nullable: true date\_registered: type: string format: date-time description: ISO 8601 timestamp of when the repository was created example: "2013-06-19T19:07:54Z" affiliation: type: string description: User's affiliation with the repository (empty string if no affiliation) example: "" media\_types: type: array description: Media types supported by this repository items: type: string example: - "application/vnd.docker.plugin.v1+json" content\_types: type: array description: Content types supported by this repository items: type: string example: - "plugin" categories: type: array description: Categories associated with this repository items: $ref: "#/components/schemas/category" example: \[] storage\_size: type: integer description: Storage size in bytes used by this repository minimum: 0 example: 232719127 category: type: object required: - name - slug properties: name: type: string description: Human-readable name of the category example: "Databases" minLength: 1 slug: type: string description: URL-friendly identifier for the category example: "databases" minLength: 1 pattern: "^\[a-z0-9]+(?:-\[a-z0-9]+)\*$" description: Repository category for classification and discovery list\_repositories\_response: allOf: - $ref: "#/components/schemas/page" - type: object properties: results: type: array items: $ref: "#/components/schemas/repository\_list\_entry" UsersLoginRequest: description: User login details type: object required: - username - password properties: username: description: The username of the Docker Hub account to authenticate with. type: string example: myusername password: description: | The password or personal access token (PAT) of the Docker Hub account to authenticate with. type: string example: p\@ssw0rd AuthCreateTokenResponse: description: successful access token response type: object properties: access\_token: description: The created access token. This expires in 10 minutes. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV\_adQssw5c PostUsersLoginSuccessResponse: description: successful user login response type: object properties: token: description: | Created authentication token. This token can be used in the HTTP Authorization header as a JWT to authenticate with the Docker Hub APIs. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV\_adQssw5c nullable: false PostUsersLoginErrorResponse: description: failed user login response or second factor required type: object required: - detail properties: detail: description: Description of the error. type: string example: Incorrect authentication credentials nullable: false login\_2fa\_token: description: | Short time lived token to be used on \`/v2/users/2fa-login\` to complete the authentication. This field is present only if 2FA is enabled. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV\_adQssw5c nullable: true Users2FALoginRequest: description: Second factor user login details type: object required: - login\_2fa\_token - code properties: login\_2fa\_token: description: The intermediate 2FA token returned from \`/v2/users/login\` API. type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV\_adQssw5c code: description: | The Time-based One-Time Password of the Docker Hub account to authenticate with. type: string example: 123456 PostUsers2FALoginErrorResponse: description: failed second factor login response. type: object properties: detail: description: Description of the error. type: string example: Incorrect authentication credentials nullable: false protobufAny: type: object properties: type\_url: type: string value: type: string format: byte rpcStatus: type: object properties: code: type: integer format: int32 message: type: string details: type: array items: $ref: "#/components/schemas/protobufAny" AuditLogAction: type: object properties: name: type: string description: Name of audit log action. description: type: string description: Description of audit log action. label: type: string description: Label for audit log action. description: Audit Log action AuditLogActions: type: object properties: actions: type: array items: $ref: "#/components/schemas/AuditLogAction" description: List of audit log actions. label: type: string description: Grouping label for a particular set of audit log actions. GetAuditActionsResponse: type: object properties: actions: type: object additionalProperties: $ref: "#/components/schemas/AuditLogActions" description: Map of audit log actions. description: GetAuditActions response. GetAuditLogsResponse: type: object properties: logs: type: array items: $ref: "#/components/schemas/AuditLog" description: List of audit log events. description: GetAuditLogs response. AuditLog: type: object properties: account: type: string action: type: string name: type: string actor: type: string data: type: object additionalProperties: type: string timestamp: type: string format: date-time action\_description: type: string description: Audit log event. ValueError: type: object description: Used to error if input validation fails. properties: fields: type: object items: type: string text: type: string Error: type: object properties: detail: type: string message: type: string accessToken: type: object properties: uuid: type: string example: b30bbf97-506c-4ecd-aabc-842f3cb484fb client\_id: type: string example: HUB creator\_ip: type: string example: 127.0.0.1 creator\_ua: type: string example: some user agent created\_at: type: string example: "2021-07-20T12:00:00.000000Z" last\_used: type: string example: null nullable: true generated\_by: type: string example: manual is\_active: type: boolean example: true token: type: string example: a7a5ef25-8889-43a0-8cc7-f2a94268e861 token\_label: type: string example: My read only token scopes: type: array example: - repo:read items: type: string expires\_at: type: string format: date-time example: "2021-10-28T18:30:19.520861Z" createAccessTokenRequest: type: object required: - token\_label - scopes properties: token\_label: type: string description: Friendly name for you to identify the token. example: My read only token minLength: 1 maxLength: 100 scopes: type: array description: | Valid scopes: "repo:admin", "repo:write", "repo:read", "repo:public\_read" example: - repo:read items: type: string expires\_at: type: string description: | Optional expiration date for the token. If omitted, the token will remain valid indefinitely. format: date-time example: "2021-10-28T18:30:19.520861Z" createAccessTokensResponse: $ref: "#/components/schemas/accessToken" getAccessTokensResponse: type: object properties: count: type: number example: 1 next: type: string example: null previous: type: string example: null active\_count: type: number example: 1 results: type: array items: allOf: - $ref: "#/components/schemas/accessToken" - type: object properties: token: type: string example: "" patchAccessTokenRequest: type: object properties: token\_label: type: string example: My read only token minLength: 1 maxLength: 100 is\_active: type: boolean example: false patchAccessTokenResponse: $ref: "#/components/schemas/accessToken" orgSettings: type: object properties: restricted\_images: $ref: "#/components/schemas/restricted\_images" restricted\_images: type: object properties: enabled: type: boolean description: Whether or not to restrict image usage for users in the organization. example: true allow\_official\_images: type: boolean description: Allow usage of official images if "enabled" is \`true\`. example: true allow\_verified\_publishers: type: boolean description: Allow usage of verified publisher images if "enabled" is \`true\`. example: true layer: type: object properties: digest: type: string description: image layer digest nullable: true size: type: integer description: size of the layer instruction: type: string description: Dockerfile instruction image: type: object properties: architecture: type: string description: CPU architecture features: type: string description: CPU features variant: type: string description: CPU variant digest: type: string description: image digest nullable: true layers: type: array items: $ref: "#/components/schemas/layer" os: type: string description: operating system os\_features: type: string description: OS features os\_version: type: string description: OS version size: type: integer description: size of the image status: type: string enum: - active - inactive description: Status of the image last\_pulled: type: string example: "2021-01-05T21:06:53.506400Z" description: datetime of last pull nullable: true last\_pushed: type: string example: "2021-01-05T21:06:53.506400Z" description: datetime of last push nullable: true tag: type: object properties: id: type: integer description: tag ID images: type: object $ref: "#/components/schemas/image" creator: type: integer description: ID of the user that pushed the tag last\_updated: type: string example: "2021-01-05T21:06:53.506400Z" description: datetime of last update nullable: true last\_updater: type: integer description: ID of the last user that updated the tag last\_updater\_username: type: string description: Hub username of the user that updated the tag name: type: string description: name of the tag repository: type: integer description: repository ID full\_size: type: integer description: compressed size (sum of all layers) of the tagged image v2: type: string description: repository API version status: type: string enum: - active - inactive description: whether a tag has been pushed to or pulled in the past month tag\_last\_pulled: type: string example: "2021-01-05T21:06:53.506400Z" description: datetime of last pull nullable: true tag\_last\_pushed: type: string example: "2021-01-05T21:06:53.506400Z" description: datetime of last push nullable: true paginated\_tags: allOf: - $ref: "#/components/schemas/page" - type: object properties: results: type: array items: $ref: "#/components/schemas/tag" page: type: object properties: count: type: integer description: total number of results available across all pages next: type: string description: link to next page of results if any nullable: true previous: type: string description: link to previous page of results if any nullable: true scim\_schema\_attribute: type: object properties: name: type: string example: userName type: enum: - string - boolean - complex type: string example: string multiValued: type: boolean example: false description: type: string example: Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. required: type: boolean example: true caseExact: type: boolean example: false mutability: type: string example: readWrite returned: type: string example: default uniqueness: type: string example: server scim\_schema\_parent\_attribute: allOf: - $ref: "#/components/schemas/scim\_schema\_attribute" - type: object properties: subAttributes: type: array items: $ref: "#/components/schemas/scim\_schema\_attribute" invite: type: object properties: id: type: string description: uuid representing the invite id example: e36eca69-4cc8-4f17-9845-ae8c2b832691 inviter\_username: type: string example: moby invitee: type: string description: can either be a dockerID for registered users or an email for non-registered users example: invitee\@docker.com org: type: string description: name of the org to join example: docker team: type: string description: name of the team (user group) to join example: owners created\_at: type: string example: "2021-10-28T18:30:19.520861Z" bulk\_invite: type: object properties: invitees: type: array description: A list of invitees items: type: object properties: invitee: type: string description: invitee email or Docker ID status: type: string description: status of the invite or validation error invite: description: Invite data if successfully invited $ref: "#/components/schemas/invite" example: invitees: - invitee: invitee\@docker.com status: invited invite: id: e36eca69-4cc8-4f17-9845-ae8c2b832691 inviter\_username: moby invitee: invitee\@docker.com org: docker team: owners created\_at: "2021-10-28T18:30:19.520861Z" - invitee: invitee2\@docker.com status: existing\_org\_member - invitee: invitee3\@docker.com status: invalid\_email\_or\_docker\_id error: type: object properties: errinfo: type: object items: type: string detail: type: string message: type: string scim\_error: type: object properties: status: type: string description: The status code for the response in string format. schemas: type: array items: type: string default: urn:ietf:params:scim:api:messages:2.0:Error detail: type: string description: Details about why the request failed. user: type: object properties: id: type: string example: 0ab70deb065a43fcacd55d48caa945d8 description: The UUID trimmed company: type: string example: Docker Inc date\_joined: type: string example: "2021-01-05T21:06:53.506400Z" full\_name: type: string example: Jon Snow gravatar\_email: type: string gravatar\_url: type: string location: type: string profile\_url: type: string type: type: string enum: - User - Org example: User username: type: string example: dockeruser org\_member: allOf: - $ref: "#/components/schemas/user" properties: email: type: string description: User's email address example: example\@docker.com role: type: string description: User's role in the Organization enum: - Owner - Member - Invitee example: Owner groups: type: array description: Groups (Teams) that the user is member of items: type: string example: - developers - owners is\_guest: type: boolean description: If the organization has verified domains, members that have email addresses outside of those domains will be flagged as guests. example: false primary\_email: type: string description: The user's email primary address. example: example\@docker.com deprecated: true last\_logged\_in\_at: type: string format: date-time description: | Last time the user logged in. To access this field, you must have insights visible for your organization. See \[Insights]\(https\://docs.docker.com/admin/insights/#view-insights-for-organization-users). example: "2021-01-05T21:06:53.506400Z" last\_seen\_at: type: string format: date-time description: | Last time the user was seen. To access this field, you must have insights visible for your organization. See \[Insights]\(https\://docs.docker.com/admin/insights/#view-insights-for-organization-users). example: "2021-01-05T21:06:53.506400Z" last\_desktop\_version: type: string description: | Last desktop version the user used. To access this field, you must have insights visible for your organization. See \[Insights]\(https\://docs.docker.com/admin/insights/#view-insights-for-organization-users). example: 4.29.0 org\_member\_paginated: type: object properties: count: type: number description: The total number of items that match with the search. example: 120 previous: type: string description: The URL or link for the previous page of items. example: https\://hub.docker.com/v2/some/resources/items?page=1\&page\_size=20 next: type: string description: The URL or link for the next page of items. example: https\://hub.docker.com/v2/some/resources/items?page=3\&page\_size=20 results: type: array description: List of accounts. items: $ref: "#/components/schemas/org\_member" org\_group: type: object properties: id: type: number example: 10 description: Group ID uuid: type: string description: UUID for the group name: type: string example: mygroup description: Name of the group description: type: string example: Groups description description: Description of the group member\_count: type: number example: 10 description: Member count of the group group\_member: type: object properties: id: type: string example: 0ab70deb065a43fcacd55d48caa945d8 description: The UUID trimmed company: type: string example: Docker Inc date\_joined: type: string format: date-time example: "2021-01-05T21:06:53.506400Z" full\_name: type: string example: John Snow gravatar\_email: type: string gravatar\_url: type: string location: type: string profile\_url: type: string type: type: string enum: - User - Org example: User username: type: string example: dockeruser email: type: string example: dockeruser\@docker.com email\_address: type: object properties: id: type: number user\_id: type: number email: type: string example: dockeruser\@docker.com verified: type: boolean primary: type: boolean legacy\_email\_address: allOf: - $ref: "#/components/schemas/email\_address" - type: object properties: user: type: string example: dockeruser email\_with\_username: allOf: - $ref: "#/components/schemas/email\_address" - type: object properties: username: type: string example: dockeruser scim\_service\_provider\_config: type: object properties: schemas: type: array items: type: string example: - urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig documentationUri: type: string example: "" patch: properties: supported: type: boolean example: false bulk: type: object properties: supported: type: boolean example: false maxOperations: type: integer maxPayloadSize: type: integer filter: type: object properties: supported: type: boolean example: true maxResults: type: integer example: 99999 changePassword: type: object properties: supported: type: boolean example: false sort: type: object properties: supported: type: boolean example: true etag: type: object properties: supported: type: boolean example: false authenticationSchemes: type: object properties: name: type: string example: OAuth 2.0 Bearer Token description: type: string example: The OAuth 2.0 Bearer Token Authentication scheme. OAuth enables clients to access protected resources by obtaining an access token, which is defined in RFC 6750 as "a string representing an access authorization issued to the client", rather than using the resource owner's credentials directly. specUri: type: string example: http\://tools.ietf.org/html/rfc6750 type: type: string example: oauthbearertoken scim\_resource\_type: type: object properties: schemas: type: array items: type: string example: - urn:ietf:params:scim:schemas:core:2.0:ResourceType id: type: string example: User name: type: string example: User description: type: string example: User endpoint: type: string example: /Users schema: type: string example: urn:ietf:params:scim:schemas:core:2.0:User scim\_schema: type: object properties: schemas: type: array items: type: string example: - urn:ietf:params:scim:schemas:core:2.0:Schema id: type: string example: urn:ietf:params:scim:schemas:core:2.0:User name: type: string example: User description: type: string example: User Account attributes: type: array example: \[] items: $ref: "#/components/schemas/scim\_schema\_parent\_attribute" scim\_email: type: object properties: value: type: string example: jon.snow\@docker.com display: type: string example: jon.snow\@docker.com primary: type: boolean example: true scim\_group: type: object properties: value: type: string example: nightswatch display: type: string example: nightswatch scim\_user\_username: type: string description: The user's email address. This must be reachable via email. example: jon.snow\@docker.com scim\_user\_name: type: object properties: givenName: type: string example: Jon familyName: type: string example: Snow scim\_user\_display\_name: type: string description: The username in Docker. Also known as the "Docker ID". example: jonsnow scim\_user\_schemas: type: array items: type: string example: urn:ietf:params:scim:schemas:core:2.0:User minItems: 1 scim\_user\_id: type: string example: d80f7c79-7730-49d8-9a41-7c42fb622d9c description: The unique identifier for the user. A v4 UUID. scim\_user: type: object properties: schemas: $ref: "#/components/schemas/scim\_user\_schemas" id: $ref: "#/components/schemas/scim\_user\_id" userName: $ref: "#/components/schemas/scim\_user\_username" name: $ref: "#/components/schemas/scim\_user\_name" displayName: $ref: "#/components/schemas/scim\_user\_display\_name" active: type: boolean example: true emails: type: array items: $ref: "#/components/schemas/scim\_email" groups: type: array items: $ref: "#/components/schemas/scim\_group" meta: type: object properties: resourceType: type: string example: User location: type: string example: https\://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c created: type: string format: date-time description: The creation date for the user as a RFC3339 formatted string. example: "2022-05-20T00:54:18Z" lastModified: type: string format: date-time description: The date the user was last modified as a RFC3339 formatted string. example: "2022-05-20T00:54:18Z" orgAccessToken: type: object properties: id: type: string example: "a7a5ef25-8889-43a0-8cc7-f2a94268e861" label: type: string example: "My organization token" created\_by: type: string example: "johndoe" is\_active: type: boolean example: true created\_at: type: string format: date-time example: "2022-05-20T00:54:18Z" expires\_at: type: string format: date-time example: "2023-05-20T00:54:18Z" nullable: true last\_used\_at: type: string format: date-time example: "2022-06-15T12:30:45Z" nullable: true orgAccessTokenResource: type: object properties: type: type: string enum: - TYPE\_REPO - TYPE\_ORG example: "TYPE\_REPO" description: The type of resource required: true path: type: string example: "myorg/myrepo" description: | The path of the resource. The format of this will change depending on the type of resource. For TYPE\_REPO resources: - Must be an existing repository name (e.g., "myorg/myrepo") - Can use glob patterns (e.g., "myorg/\*" for all repositories in the organization) - Use "\*/\*/public" to reference all public repositories required: true scopes: type: array description: The scopes this token has access to items: type: string example: "scope-image-pull" required: true getOrgAccessTokensResponse: type: object properties: total: type: number example: 10 next: type: string example: https\://hub.docker.com/v2/orgs/docker/access-tokens?page=2\&page\_size=10 previous: type: string example: https\://hub.docker.com/v2/orgs/docker/access-tokens?page=1\&page\_size=10 results: type: array items: $ref: "#/components/schemas/orgAccessToken" getOrgAccessTokenResponse: allOf: - $ref: "#/components/schemas/orgAccessToken" - type: object properties: resources: type: array description: Resources this token has access to items: $ref: "#/components/schemas/orgAccessTokenResource" createOrgAccessTokenRequest: type: object properties: label: type: string description: Label for the access token example: "My organization token" required: true description: type: string description: Description of the access token example: "Token for CI/CD pipeline" resources: type: array description: Resources this token has access to items: $ref: "#/components/schemas/orgAccessTokenResource" expires\_at: type: string format: date-time description: Expiration date for the token example: "2023-05-20T00:54:18Z" nullable: true createOrgAccessTokenResponse: type: object allOf: - type: object properties: id: type: string example: "a7a5ef25-8889-43a0-8cc7-f2a94268e861" label: type: string example: "My organization token" is\_active: type: boolean example: true created\_at: type: string format: date-time example: "2022-05-20T00:54:18Z" expires\_at: type: string format: date-time example: "2023-05-20T00:54:18Z" nullable: true last\_used\_at: type: string format: date-time example: "2022-06-15T12:30:45Z" nullable: true - type: object properties: token: type: string description: The actual token value that can be used for authentication example: "dckr\_oat\_7awgM4jG5SQvxcvmNzhKj8PQjxo" resources: type: array items: $ref: "#/components/schemas/orgAccessTokenResource" updateOrgAccessTokenRequest: type: object properties: label: type: string description: Label for the access token example: "My organization token" description: type: string description: Description of the access token example: "Token for CI/CD pipeline" resources: type: array description: Resources this token has access to items: $ref: "#/components/schemas/orgAccessTokenResource" is\_active: type: boolean description: Whether the token is active example: true updateOrgAccessTokenResponse: type: object allOf: - $ref: "#/components/schemas/orgAccessToken" - type: object properties: resources: type: array description: Resources this token has access to items: $ref: "#/components/schemas/orgAccessTokenResource" team\_repo: allOf: - $ref: "#/components/responses/team\_repo" properties: group\_name: type: string description: Name of the group permission: type: string description: Repo access permission enum: - read - write - admin parameters: namespace: in: path name: namespace required: true schema: type: string repository: in: path name: repository required: true schema: type: string tag: in: path name: tag required: true schema: type: string org\_name: in: path name: org\_name description: Name of the organization (namespace). schema: type: string example: myorganization required: true group\_name: in: path name: group\_name description: Name of the group (team) in the organization. schema: type: string example: developers required: true username: in: path name: username description: Username, identifier for the user (namespace, DockerID). schema: type: string example: jonsnow required: true page: in: query name: page description: Page number (starts on 1). schema: type: integer page\_size: in: query name: page\_size description: Number of items (rows) per page. schema: type: integer invites: in: query name: invites description: Include invites in the response. schema: type: boolean search: in: query name: search schema: type: integer description: Search term. scim\_attributes: in: query name: attributes schema: type: string description: Comma delimited list of attributes to limit to in the response. example: userName,displayName scim\_user\_id: name: id in: path schema: type: string description: The user ID. example: d80f7c79-7730-49d8-9a41-7c42fb622d9c required: true type: in: query name: type schema: type: string enum: - all - invitee - member example: all role: in: query name: role schema: type: string enum: - owner - editor - member example: owner bulk\_invite: in: header name: X-Analytics-Client-Feature description: Optional string that indicates the feature used to submit the bulk invites (e.g.'file', 'web') schema: type: string requestBodies: bulk\_invite\_request: required: true content: application/json: schema: type: object required: - org - invitees properties: org: type: string description: organization name example: docker team: type: string description: team name example: owners role: type: string description: role for invitees example: member invitees: type: array description: list of invitees emails or Docker Ids items: type: string description: invitee email or Docker ID example: - invitee1DockerId - invitee2\@docker.com - invitee3\@docker.com dry\_run: type: boolean description: Optional, run through validation but don't actually change data. example: true scim\_create\_user\_request: required: true content: application/scim+json: schema: type: object required: - schemas - userName properties: schemas: $ref: "#/components/schemas/scim\_user\_schemas" userName: $ref: "#/components/schemas/scim\_user\_username" name: $ref: "#/components/schemas/scim\_user\_name" scim\_update\_user\_request: required: true content: application/scim+json: schema: type: object required: - schemas properties: schemas: $ref: "#/components/schemas/scim\_user\_schemas" name: allOf: - $ref: "#/components/schemas/scim\_user\_name" - description: If this is omitted from the request, the update will skip the update on it. We will only ever change the name, but not clear it. enabled: type: boolean default: false description: If this is omitted from the request, it will default to false resulting in a deactivated user. add\_member\_to\_org\_group: required: true content: application/json: schema: type: object required: - member properties: member: type: string example: jonsnow update\_repository\_immutable\_tags\_request: required: true content: application/json: schema: $ref: "#/components/schemas/update\_repository\_immutable\_tags\_request" immutable\_tags\_verify\_request: required: true content: application/json: schema: $ref: "#/components/schemas/immutable\_tags\_verify\_request" securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT bearerSCIMAuth: type: http scheme: bearer x-tagGroups: - name: General tags: - changelog - resources - rate-limiting - authentication - name: API tags: - authentication-api - access-tokens - images - audit-logs - org-settings - repositories - scim - orgs - org-access-tokens - groups - invites

----
url: https://docs.docker.com/guides/php/develop/
----

# Use containers for PHP development

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete [Containerize a PHP application](https://docs.docker.com/guides/php/containerize/).

## [Overview](#overview)

In this section, you'll learn how to set up a development environment for your containerized application. This includes:

* Adding a local database and persisting data
* Adding phpMyAdmin to interact with the database
* Configuring Compose to automatically update your running Compose services as you edit and save your code
* Creating a development container that contains the dev dependencies

## [Add a local database and persist data](#add-a-local-database-and-persist-data)

You can use containers to set up local services, like a database. To do this for the sample application, you'll need to do the following:

* Update the `Dockerfile` to install extensions to connect to the database
* Update the `compose.yaml` file to add a database service and volume to persist data

### [Update the Dockerfile to install extensions](#update-the-dockerfile-to-install-extensions)

To install PHP extensions, you need to update the `Dockerfile`. Open your Dockerfile in an IDE or text editor and then update the contents. The following `Dockerfile` includes one new line that installs the `pdo` and `pdo_mysql` extensions. All comments have been removed.

```dockerfile
# syntax=docker/dockerfile:1

FROM composer:lts as deps
WORKDIR /app
RUN --mount=type=bind,source=composer.json,target=composer.json \
    --mount=type=bind,source=composer.lock,target=composer.lock \
    --mount=type=cache,target=/tmp/cache \
    composer install --no-dev --no-interaction

FROM php:8.2-apache as final
RUN docker-php-ext-install pdo pdo_mysql
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
COPY --from=deps app/vendor/ /var/www/html/vendor
COPY ./src /var/www/html
USER www-data
```

For more details about installing PHP extensions, see the [Official Docker Image for PHP](https://hub.docker.com/_/php).

### [Update the compose.yaml file to add a db and persist data](#update-the-composeyaml-file-to-add-a-db-and-persist-data)

Open the `compose.yaml` file in an IDE or text editor. You'll notice it already contains commented-out instructions for a PostgreSQL database and volume. For this application, you'll use MariaDB. For more details about MariaDB, see the [MariaDB Official Docker image](https://hub.docker.com/_/mariadb).

Open the `src/database.php` file in an IDE or text editor. You'll notice that it reads environment variables in order to connect to the database.

In the `compose.yaml` file, you'll need to update the following:

1. Uncomment and update the database instructions for MariaDB.
2. Add a secret to the server service to pass in the database password.
3. Add the database connection environment variables to the server service.
4. Uncomment the volume instructions to persist data.

The following is the updated `compose.yaml` file. All comments have been removed.

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 9000:80
    depends_on:
      db:
        condition: service_healthy
    secrets:
      - db-password
    environment:
      - PASSWORD_FILE_PATH=/run/secrets/db-password
      - DB_HOST=db
      - DB_NAME=example
      - DB_USER=root
  db:
    image: mariadb
    restart: always
    user: root
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/mysql
    environment:
      - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password
      - MARIADB_DATABASE=example
    expose:
      - 3306
    healthcheck:
      test:
        [
          "CMD",
          "/usr/local/bin/healthcheck.sh",
          "--su-mysql",
          "--connect",
          "--innodb_initialized",
        ]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
```

> Note
>
> To learn more about the instructions in the Compose file, see [Compose file reference](/reference/compose-file/).

Before you run the application using Compose, notice that this Compose file uses `secrets` and specifies a `password.txt` file to hold the database's password. You must create this file as it's not included in the source repository.

In the `docker-php-sample` directory, create a new directory named `db` and inside that directory create a file named `password.txt`. Open `password.txt` in an IDE or text editor and add the following password. The password must be on a single line, with no additional lines in the file.

```text
example
```

Save and close the `password.txt` file.

You should now have the following in your `docker-php-sample` directory.

```text
├── docker-php-sample/
│ ├── .git/
│ ├── db/
│ │ └── password.txt
│ ├── src/
│ ├── tests/
│ ├── .dockerignore
│ ├── .gitignore
│ ├── compose.yaml
│ ├── composer.json
│ ├── composer.lock
│ ├── Dockerfile
│ └── README.md
```

Run the following command to start your application.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:9000/database.php>. You should see a simple web application with text and a counter that increments every time you refresh.

Press `ctrl+c` in the terminal to stop your application.

## [Verify that data persists in the database](#verify-that-data-persists-in-the-database)

In the terminal, run `docker compose rm` to remove your containers and then run `docker compose up` to run your application again.

```console
$ docker compose rm
$ docker compose up --build
```

Refresh <http://localhost:9000/database.php> in your browser and verify that the previous count still exists. Without a volume, the database data wouldn't persist after you remove the container.

Press `ctrl+c` in the terminal to stop your application.

## [Add phpMyAdmin to interact with the database](#add-phpmyadmin-to-interact-with-the-database)

You can easily add services to your application stack by updating the `compose.yaml` file.

Update your `compose.yaml` to add a new service for phpMyAdmin. For more details, see the [phpMyAdmin Official Docker Image](https://hub.docker.com/_/phpmyadmin). The following is the updated `compose.yaml` file.

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 9000:80
    depends_on:
      db:
        condition: service_healthy
    secrets:
      - db-password
    environment:
      - PASSWORD_FILE_PATH=/run/secrets/db-password
      - DB_HOST=db
      - DB_NAME=example
      - DB_USER=root
  db:
    image: mariadb
    restart: always
    user: root
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/mysql
    environment:
      - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password
      - MARIADB_DATABASE=example
    expose:
      - 3306
    healthcheck:
      test:
        [
          "CMD",
          "/usr/local/bin/healthcheck.sh",
          "--su-mysql",
          "--connect",
          "--innodb_initialized",
        ]
      interval: 10s
      timeout: 5s
      retries: 5
  phpmyadmin:
    image: phpmyadmin
    ports:
      - 8080:80
    depends_on:
      - db
    environment:
      - PMA_HOST=db
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
```

In the terminal, run `docker compose up` to run your application again.

```console
$ docker compose up --build
```

Open <http://localhost:8080> in your browser to access phpMyAdmin. Log in using `root` as the username and `example` as the password. You can now interact with the database through phpMyAdmin.

Press `ctrl+c` in the terminal to stop your application.

## [Automatically update services](#automatically-update-services)

Use Compose Watch to automatically update your running Compose services as you edit and save your code. For more details about Compose Watch, see [Use Compose Watch](https://docs.docker.com/compose/how-tos/file-watch/).

Open your `compose.yaml` file in an IDE or text editor and then add the Compose Watch instructions. The following is the updated `compose.yaml` file.

```yaml
services:
  server:
    build:
      context: .
    ports:
      - 9000:80
    depends_on:
      db:
        condition: service_healthy
    secrets:
      - db-password
    environment:
      - PASSWORD_FILE_PATH=/run/secrets/db-password
      - DB_HOST=db
      - DB_NAME=example
      - DB_USER=root
    develop:
      watch:
        - action: sync
          path: ./src
          target: /var/www/html
  db:
    image: mariadb
    restart: always
    user: root
    secrets:
      - db-password
    volumes:
      - db-data:/var/lib/mysql
    environment:
      - MARIADB_ROOT_PASSWORD_FILE=/run/secrets/db-password
      - MARIADB_DATABASE=example
    expose:
      - 3306
    healthcheck:
      test:
        [
          "CMD",
          "/usr/local/bin/healthcheck.sh",
          "--su-mysql",
          "--connect",
          "--innodb_initialized",
        ]
      interval: 10s
      timeout: 5s
      retries: 5
  phpmyadmin:
    image: phpmyadmin
    ports:
      - 8080:80
    depends_on:
      - db
    environment:
      - PMA_HOST=db
volumes:
  db-data:
secrets:
  db-password:
    file: db/password.txt
```

Run the following command to run your application with Compose Watch.

```console
$ docker compose watch
```

Open a browser and verify that the application is running at <http://localhost:9000/hello.php>.

Any changes to the application's source files on your local machine will now be immediately reflected in the running container.

Open `hello.php` in an IDE or text editor and update the string `Hello, world!` to `Hello, Docker!`.

Save the changes to `hello.php` and then wait a few seconds for the application to sync. Refresh <http://localhost:9000/hello.php> in your browser and verify that the updated text appears.

Press `ctrl+c` in the terminal to stop Compose Watch. Run `docker compose down` in the terminal to stop the application.

## [Create a development container](#create-a-development-container)

At this point, when you run your containerized application, Composer isn't installing the dev dependencies. While this small image is good for production, it lacks the tools and dependencies you may need when developing and it doesn't include the `tests` directory. You can use multi-stage builds to build stages for both development and production in the same Dockerfile. For more details, see [Multi-stage builds](https://docs.docker.com/build/building/multi-stage/).

In the `Dockerfile`, you'll need to update the following:

1. Split the `deps` staged into two stages. One stage for production (`prod-deps`) and one stage (`dev-deps`) to install development dependencies.
2. Create a common `base` stage.
3. Create a new `development` stage for development.
4. Update the `final` stage to copy dependencies from the new `prod-deps` stage.

The following is the `Dockerfile` before and after the changes.

```dockerfile
# syntax=docker/dockerfile:1

FROM composer:lts as deps
WORKDIR /app
RUN --mount=type=bind,source=composer.json,target=composer.json \
    --mount=type=bind,source=composer.lock,target=composer.lock \
    --mount=type=cache,target=/tmp/cache \
    composer install --no-dev --no-interaction

FROM php:8.2-apache as final
RUN docker-php-ext-install pdo pdo_mysql
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
COPY --from=deps app/vendor/ /var/www/html/vendor
COPY ./src /var/www/html
USER www-data
```

```dockerfile
# syntax=docker/dockerfile:1

FROM composer:lts as prod-deps
WORKDIR /app
RUN --mount=type=bind,source=./composer.json,target=composer.json \
    --mount=type=bind,source=./composer.lock,target=composer.lock \
    --mount=type=cache,target=/tmp/cache \
    composer install --no-dev --no-interaction

FROM composer:lts as dev-deps
WORKDIR /app
RUN --mount=type=bind,source=./composer.json,target=composer.json \
    --mount=type=bind,source=./composer.lock,target=composer.lock \
    --mount=type=cache,target=/tmp/cache \
    composer install --no-interaction

FROM php:8.2-apache as base
RUN docker-php-ext-install pdo pdo_mysql
COPY ./src /var/www/html

FROM base as development
COPY ./tests /var/www/html/tests
RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini"
COPY --from=dev-deps app/vendor/ /var/www/html/vendor

FROM base as final
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
COPY --from=prod-deps app/vendor/ /var/www/html/vendor
USER www-data
```

Update your `compose.yaml` file by adding an instruction to target the development stage.

The following is the updated section of the `compose.yaml` file.

```yaml
services:
  server:
    build:
      context: .
      target: development
      # ...
```

Your containerized application will now install the dev dependencies.

Run the following command to start your application.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:9000/hello.php>. You should still see the simple "Hello, Docker!" application.

Press `ctrl+c` in the terminal to stop your application.

While the application appears the same, you can now make use of the dev dependencies. Continue to the next section to learn how you can run tests using Docker.

## [Summary](#summary)

In this section, you took a look at setting up your Compose file to add a local database and persist data. You also learned how to use Compose Watch to automatically sync your application when you update your code. And finally, you learned how to create a development container that contains the dependencies needed for development.

Related information:

* [Compose file reference](/reference/compose-file/)
* [Compose file watch](https://docs.docker.com/compose/how-tos/file-watch/)
* [Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
* [Official Docker Image for PHP](https://hub.docker.com/_/php)

## [Next steps](#next-steps)

In the next section, you'll learn how to run unit tests using Docker.

[Run PHP tests in a container »](https://docs.docker.com/guides/php/run-tests/)

----
url: https://docs.docker.com/reference/cli/docker/compose/
----

# docker compose

***

| Description | Docker Compose   |
| ----------- | ---------------- |
| Usage       | `docker compose` |

## [Description](#description)

Define and run multi-container applications with Docker

## [Options](#options)

| Option                | Default | Description                                                                                      |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `--all-resources`     |         | Include all resources, even those not used by services                                           |
| `--ansi`              | `auto`  | Control when to print ANSI control characters ("never"\|"always"\|"auto")                        |
| `--compatibility`     |         | Run compose in backward compatibility mode                                                       |
| `--dry-run`           |         | Execute command in dry run mode                                                                  |
| `--env-file`          |         | Specify an alternate environment file                                                            |
| `-f, --file`          |         | Compose configuration files                                                                      |
| `--parallel`          | `-1`    | Control max parallelism, -1 for unlimited                                                        |
| `--profile`           |         | Specify a profile to enable                                                                      |
| `--progress`          |         | Set type of progress output (auto, tty, plain, json, quiet)                                      |
| `--project-directory` |         | Specify an alternate working directory (default: the path of the, first specified, Compose file) |
| `-p, --project-name`  |         | Project name                                                                                     |

## [Examples](#examples)

### [Use `-f` to specify the name and path of one or more Compose files](#use--f-to-specify-the-name-and-path-of-one-or-more-compose-files)

Use the `-f` flag to specify the location of a Compose [configuration file](/reference/compose-file/).

#### [Specifying multiple Compose files](#specifying-multiple-compose-files)

You can supply multiple `-f` configuration files. When you supply multiple files, Compose combines them into a single configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add to their predecessors.

For example, consider this command line:

```console
$ docker compose -f compose.yaml -f compose.admin.yaml run backup_db
```

The `compose.yaml` file might specify a `webapp` service.

```yaml
services:
  webapp:
    image: examples/web
    ports:
      - "8000:8000"
    volumes:
      - "/data"
```

If the `compose.admin.yaml` also specifies this same service, any matching fields override the previous file. New values, add to the `webapp` service configuration.

```yaml
services:
  webapp:
    build: .
    environment:
      - DEBUG=1
```

When you use multiple Compose files, all paths in the files are relative to the first configuration file specified with `-f`. You can use the `--project-directory` option to override this base path.

Use a `-f` with `-` (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the configuration are relative to the current working directory.

The `-f` flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory and its parent directories looking for a `compose.yaml` or `docker-compose.yaml` file.

#### [Specifying a path to a single Compose file](#specifying-a-path-to-a-single-compose-file)

You can use the `-f` flag to specify a path to a Compose file that is not located in the current directory, either from the command line or by setting up a `COMPOSE_FILE` environment variable in your shell or in an environment file.

For an example of using the `-f` option at the command line, suppose you are running the Compose Rails sample, and have a `compose.yaml` file in a directory called `sandbox/rails`. You can use a command like `docker compose pull` to get the postgres image for the db service from anywhere by using the `-f` flag as follows:

```console
$ docker compose -f ~/sandbox/rails/compose.yaml pull db
```

#### [Using an OCI published artifact](#using-an-oci-published-artifact)

You can use the `-f` flag with the `oci://` prefix to reference a Compose file that has been published to an OCI registry. This allows you to distribute and version your Compose configurations as OCI artifacts.

To use a Compose file from an OCI registry:

```console
$ docker compose -f oci://registry.example.com/my-compose-project:latest up
```

You can also combine OCI artifacts with local files:

```console
$ docker compose -f oci://registry.example.com/my-compose-project:v1.0 -f compose.override.yaml up
```

The OCI artifact must contain a valid Compose file. You can publish Compose files to an OCI registry using the `docker compose publish` command.

#### [Using a git repository](#using-a-git-repository)

You can use the `-f` flag to reference a Compose file from a git repository. Compose supports various git URL formats:

Using HTTPS:

```console
$ docker compose -f https://github.com/user/repo.git up
```

Using SSH:

```console
$ docker compose -f git@github.com:user/repo.git up
```

You can specify a specific branch, tag, or commit:

```console
$ docker compose -f https://github.com/user/repo.git@main up
$ docker compose -f https://github.com/user/repo.git@v1.0.0 up
$ docker compose -f https://github.com/user/repo.git@abc123 up
```

You can also specify a subdirectory within the repository:

```console
$ docker compose -f https://github.com/user/repo.git#main:path/to/compose.yaml up
```

When using git resources, Compose will clone the repository and use the specified Compose file. You can combine git resources with local files:

```console
$ docker compose -f https://github.com/user/repo.git -f compose.override.yaml up
```

### [Use `-p` to specify a project name](#use--p-to-specify-a-project-name)

Each configuration has a project name. Compose sets the project name using the following mechanisms, in order of precedence:

* The `-p` command line flag
* The `COMPOSE_PROJECT_NAME` environment variable
* The top level `name:` variable from the config file (or the last `name:` from a series of config files specified using `-f`)
* The `basename` of the project directory containing the config file (or containing the first config file specified using `-f`)
* The `basename` of the current directory if no config file is specified Project names must contain only lowercase letters, decimal digits, dashes, and underscores, and must begin with a lowercase letter or decimal digit. If the `basename` of the project directory or current directory violates this constraint, you must use one of the other mechanisms.

```console
$ docker compose -p my_project ps -a
NAME                 SERVICE    STATUS     PORTS
my_project_demo_1    demo       running

$ docker compose -p my_project logs
demo_1  | PING localhost (127.0.0.1): 56 data bytes
demo_1  | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms
```

### [Use profiles to enable optional services](#use-profiles-to-enable-optional-services)

Use `--profile` to specify one or more active profiles Calling `docker compose --profile frontend up` starts the services with the profile `frontend` and services without any specified profiles. You can also enable multiple profiles, e.g. with `docker compose --profile frontend --profile debug up` the profiles `frontend` and `debug` is enabled.

Profiles can also be set by `COMPOSE_PROFILES` environment variable.

### [Configuring parallelism](#configuring-parallelism)

Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls. Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file one at a time. This can also be used to control build concurrency.

Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.

### [Set up environment variables](#set-up-environment-variables)

You can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags.

Setting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag, `COMPOSE_PROJECT_NAME` environment variable does the same as the `-p` flag, `COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag and `COMPOSE_PARALLEL_LIMIT` does the same as the `--parallel` flag.

If flags are explicitly set on the command line, the associated environment variable is ignored.

Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` stops docker compose from detecting orphaned containers for the project.

Setting the `COMPOSE_MENU` environment variable to `false` disables the helper menu when running `docker compose up` in attached mode. Alternatively, you can also run `docker compose up --menu=false` to disable the helper menu.

### [Use Dry Run mode to test your command](#use-dry-run-mode-to-test-your-command)

Use `--dry-run` flag to test a command without changing your application stack state. Dry Run mode shows you all the steps Compose applies when executing a command, for example:

```console
$ docker compose --dry-run up --build -d
[+] Pulling 1/1
 ✔ DRY-RUN MODE -  db Pulled                                                                                                                                                                                                               0.9s
[+] Running 10/8
 ✔ DRY-RUN MODE -    build service backend                                                                                                                                                                                                 0.0s
 ✔ DRY-RUN MODE -  ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd                                                                                                                                                   0.0s
 ✔ DRY-RUN MODE -  ==> ==> naming to nginx-golang-mysql-backend                                                                                                                                                                            0.0s
 ✔ DRY-RUN MODE -  Network nginx-golang-mysql_default                                    Created                                                                                                                                           0.0s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-db-1                                     Created                                                                                                                                           0.0s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-backend-1                                Created                                                                                                                                           0.0s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-proxy-1                                  Created                                                                                                                                           0.0s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-db-1                                     Healthy                                                                                                                                           0.5s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-backend-1                                Started                                                                                                                                           0.0s
 ✔ DRY-RUN MODE -  Container nginx-golang-mysql-proxy-1                                  Started                                     Started
```

From the example above, you can see that the first step is to pull the image defined by `db` service, then build the `backend` service. Next, the containers are created. The `db` service is started, and the `backend` and `proxy` wait until the `db` service is healthy before starting.

Dry Run mode works with almost all commands. You cannot use Dry Run mode with a command that doesn't change the state of a Compose stack such as `ps`, `ls`, `logs` for example.

## [Subcommands](#subcommands)

| Command                                                                                               | Description                                                                             |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [`docker compose alpha dry-run`](https://docs.docker.com/reference/cli/docker/compose/alpha/dry-run/) | EXPERIMENTAL - Dry run command allow you to test a command without applying changes     |
| [`docker compose alpha scale`](https://docs.docker.com/reference/cli/docker/compose/alpha/scale/)     | Scale services                                                                          |
| [`docker compose alpha watch`](https://docs.docker.com/reference/cli/docker/compose/alpha/watch/)     | Watch build context for service and rebuild/refresh containers when files are updated   |
| [`docker compose attach`](https://docs.docker.com/reference/cli/docker/compose/attach/)               | Attach local standard input, output, and error streams to a service's running container |
| [`docker compose bridge`](https://docs.docker.com/reference/cli/docker/compose/bridge/)               | Convert compose files into another model                                                |
| [`docker compose build`](https://docs.docker.com/reference/cli/docker/compose/build/)                 | Build or rebuild services                                                               |
| [`docker compose commit`](https://docs.docker.com/reference/cli/docker/compose/commit/)               | Create a new image from a service container's changes                                   |
| [`docker compose config`](https://docs.docker.com/reference/cli/docker/compose/config/)               | Parse, resolve and render compose file in canonical format                              |
| [`docker compose convert`](https://docs.docker.com/reference/cli/docker/compose/convert/)             | Converts the compose file to platform's canonical format                                |
| [`docker compose cp`](https://docs.docker.com/reference/cli/docker/compose/cp/)                       | Copy files/folders between a service container and the local filesystem                 |
| [`docker compose create`](https://docs.docker.com/reference/cli/docker/compose/create/)               | Creates containers for a service                                                        |
| [`docker compose down`](https://docs.docker.com/reference/cli/docker/compose/down/)                   | Stop and remove containers, networks                                                    |
| [`docker compose events`](https://docs.docker.com/reference/cli/docker/compose/events/)               | Receive real time events from containers                                                |
| [`docker compose exec`](https://docs.docker.com/reference/cli/docker/compose/exec/)                   | Execute a command in a running container                                                |
| [`docker compose export`](https://docs.docker.com/reference/cli/docker/compose/export/)               | Export a service container's filesystem as a tar archive                                |
| [`docker compose images`](https://docs.docker.com/reference/cli/docker/compose/images/)               | List images used by the created containers                                              |
| [`docker compose kill`](https://docs.docker.com/reference/cli/docker/compose/kill/)                   | Force stop service containers                                                           |
| [`docker compose logs`](https://docs.docker.com/reference/cli/docker/compose/logs/)                   | View output from containers                                                             |
| [`docker compose ls`](https://docs.docker.com/reference/cli/docker/compose/ls/)                       | List running compose projects                                                           |
| [`docker compose pause`](https://docs.docker.com/reference/cli/docker/compose/pause/)                 | Pause services                                                                          |
| [`docker compose port`](https://docs.docker.com/reference/cli/docker/compose/port/)                   | Print the public port for a port binding                                                |
| [`docker compose ps`](https://docs.docker.com/reference/cli/docker/compose/ps/)                       | List containers                                                                         |
| [`docker compose publish`](https://docs.docker.com/reference/cli/docker/compose/publish/)             | Publish compose application                                                             |
| [`docker compose pull`](https://docs.docker.com/reference/cli/docker/compose/pull/)                   | Pull service images                                                                     |
| [`docker compose push`](https://docs.docker.com/reference/cli/docker/compose/push/)                   | Push service images                                                                     |
| [`docker compose restart`](https://docs.docker.com/reference/cli/docker/compose/restart/)             | Restart service containers                                                              |
| [`docker compose rm`](https://docs.docker.com/reference/cli/docker/compose/rm/)                       | Removes stopped service containers                                                      |
| [`docker compose run`](https://docs.docker.com/reference/cli/docker/compose/run/)                     | Run a one-off command on a service                                                      |
| [`docker compose scale`](https://docs.docker.com/reference/cli/docker/compose/scale/)                 | Scale services                                                                          |
| [`docker compose start`](https://docs.docker.com/reference/cli/docker/compose/start/)                 | Start services                                                                          |
| [`docker compose stats`](https://docs.docker.com/reference/cli/docker/compose/stats/)                 | Display a live stream of container(s) resource usage statistics                         |
| [`docker compose stop`](https://docs.docker.com/reference/cli/docker/compose/stop/)                   | Stop services                                                                           |
| [`docker compose top`](https://docs.docker.com/reference/cli/docker/compose/top/)                     | Display the running processes                                                           |
| [`docker compose unpause`](https://docs.docker.com/reference/cli/docker/compose/unpause/)             | Unpause services                                                                        |
| [`docker compose up`](https://docs.docker.com/reference/cli/docker/compose/up/)                       | Create and start containers                                                             |
| [`docker compose version`](https://docs.docker.com/reference/cli/docker/compose/version/)             | Show the Docker Compose version information                                             |
| [`docker compose volumes`](https://docs.docker.com/reference/cli/docker/compose/volumes/)             | List volumes                                                                            |
| [`docker compose wait`](https://docs.docker.com/reference/cli/docker/compose/wait/)                   | Block until containers of all (or specified) services stop.                             |
| [`docker compose watch`](https://docs.docker.com/reference/cli/docker/compose/watch/)                 | Watch build context for service and rebuild/refresh containers when files are updated   |

----
url: https://docs.docker.com/guides/testcontainers-java-getting-started/create-project/
----

# Create the Java project

***

Table of contents

***

## [Set up the Maven project](#set-up-the-maven-project)

Create a Java project with Maven from your preferred IDE. This guide uses Maven, but you can use Gradle if you prefer. Add the following dependencies to `pom.xml`:

```xml
<dependencies>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>42.7.3</version>
    </dependency>
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.5.6</version>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.10.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.2.5</version>
        </plugin>
    </plugins>
</build>
```

This adds the Postgres JDBC driver, logback for logging, JUnit 5 for testing, and the latest `maven-surefire-plugin` for JUnit 5 support.

## [Implement the business logic](#implement-the-business-logic)

Create a `Customer` record:

```java
package com.testcontainers.demo;

public record Customer(Long id, String name) {}
```

Create a `DBConnectionProvider` class to hold JDBC connection parameters and provide a database `Connection`:

```java
package com.testcontainers.demo;

import java.sql.Connection;
import java.sql.DriverManager;

class DBConnectionProvider {

  private final String url;
  private final String username;
  private final String password;

  public DBConnectionProvider(String url, String username, String password) {
    this.url = url;
    this.username = username;
    this.password = password;
  }

  Connection getConnection() {
    try {
      return DriverManager.getConnection(url, username, password);
    } catch (Exception e) {
      throw new RuntimeException(e);
    }
  }
}
```

Create the `CustomerService` class:

```java
package com.testcontainers.demo;

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.ArrayList;
import java.util.List;

public class CustomerService {

  private final DBConnectionProvider connectionProvider;

  public CustomerService(DBConnectionProvider connectionProvider) {
    this.connectionProvider = connectionProvider;
    createCustomersTableIfNotExists();
  }

  public void createCustomer(Customer customer) {
    try (Connection conn = this.connectionProvider.getConnection()) {
      PreparedStatement pstmt = conn.prepareStatement(
        "insert into customers(id,name) values(?,?)"
      );
      pstmt.setLong(1, customer.id());
      pstmt.setString(2, customer.name());
      pstmt.execute();
    } catch (SQLException e) {
      throw new RuntimeException(e);
    }
  }

  public List<Customer> getAllCustomers() {
    List<Customer> customers = new ArrayList<>();

    try (Connection conn = this.connectionProvider.getConnection()) {
      PreparedStatement pstmt = conn.prepareStatement(
        "select id,name from customers"
      );
      ResultSet rs = pstmt.executeQuery();
      while (rs.next()) {
        long id = rs.getLong("id");
        String name = rs.getString("name");
        customers.add(new Customer(id, name));
      }
    } catch (SQLException e) {
      throw new RuntimeException(e);
    }
    return customers;
  }

  private void createCustomersTableIfNotExists() {
    try (Connection conn = this.connectionProvider.getConnection()) {
      PreparedStatement pstmt = conn.prepareStatement(
        """
        create table if not exists customers (
            id bigint not null,
            name varchar not null,
            primary key (id)
        )
        """
      );
      pstmt.execute();
    } catch (SQLException e) {
      throw new RuntimeException(e);
    }
  }
}
```

Here's what `CustomerService` does:

* The constructor calls `createCustomersTableIfNotExists()` to ensure the table exists.
* `createCustomer()` inserts a customer record into the database.
* `getAllCustomers()` fetches all rows from the `customers` table and returns a list of `Customer` objects.

[Write tests with Testcontainers »](https://docs.docker.com/guides/testcontainers-java-getting-started/write-tests/)

----
url: https://docs.docker.com/guides/angular/deploy/
----

# Test your Angular deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

Before you begin, make sure you’ve completed the following:

* Complete all the previous sections of this guide, starting with [Containerize Angular application](https://docs.docker.com/guides/angular/containerize/).
* [Enable Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

> **New to Kubernetes?**\
> Visit the [Kubernetes basics tutorial](https://kubernetes.io/docs/tutorials/kubernetes-basics/) to get familiar with how clusters, pods, deployments, and services work.

***

## [Overview](#overview)

This section guides you through deploying your containerized Angular application locally using [Docker Desktop’s built-in Kubernetes](/desktop/kubernetes/). Running your app in a local Kubernetes cluster closely simulates a real production environment, enabling you to test, validate, and debug your workloads with confidence before promoting them to staging or production.

***

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

Follow these steps to define your deployment configuration:

1. In the root of your project, create a new file named: angular-sample-kubernetes.yaml

2. Open the file in your IDE or preferred text editor.

3. Add the following configuration, and be sure to replace `{DOCKER_USERNAME}` and `{DOCKERHUB_PROJECT_NAME}` with your actual Docker Hub username and repository name from the previous [Automate your builds with GitHub Actions](https://docs.docker.com/guides/angular/configure-github-actions/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: angular-sample
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: angular-sample
  template:
    metadata:
      labels:
        app: angular-sample
    spec:
      containers:
        - name: angular-container
          image: {DOCKER_USERNAME}/{DOCKERHUB_PROJECT_NAME}:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 8080
          resources:
            limits:
              cpu: "500m"
              memory: "256Mi"
            requests:
              cpu: "250m"
              memory: "128Mi"
---
apiVersion: v1
kind: Service
metadata:
  name: angular-sample-service
  namespace: default
spec:
  type: NodePort
  selector:
    app: angular-sample
  ports:
    - port: 8080
      targetPort: 8080
      nodePort: 30001
```

This manifest defines two key Kubernetes resources, separated by `---`:

* Deployment Deploys a single replica of your Angular application inside a pod. The pod uses the Docker image built and pushed by your GitHub Actions CI/CD workflow\
  (refer to [Automate your builds with GitHub Actions](https://docs.docker.com/guides/angular/configure-github-actions/)).\
  The container listens on port `8080`, which is typically used by [Nginx](https://nginx.org/en/docs/) to serve your production Angular app.

* Service (NodePort) Exposes the deployed pod to your local machine.\
  It forwards traffic from port `30001` on your host to port `8080` inside the container.\
  This lets you access the application in your browser at <http://localhost:30001>.

> Note
>
> To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

***

## [Deploy and check your application](#deploy-and-check-your-application)

Follow these steps to deploy your containerized Angular app into a local Kubernetes cluster and verify that it’s running correctly.

### [Step 1. Apply the Kubernetes configuration](#step-1-apply-the-kubernetes-configuration)

In your terminal, navigate to the directory where your `angular-sample-kubernetes.yaml` file is located, then deploy the resources using:

```console
  $ kubectl apply -f angular-sample-kubernetes.yaml
```

If everything is configured properly, you’ll see confirmation that both the Deployment and the Service were created:

```shell
  deployment.apps/angular-sample created
  service/angular-sample-service created
```

This confirms that both the Deployment and the Service were successfully created and are now running inside your local cluster.

### [Step 2. Check the deployment status](#step-2-check-the-deployment-status)

Run the following command to check the status of your deployment:

```console
  $ kubectl get deployments
```

You should see output similar to the following:

```shell
  NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
  angular-sample       1/1     1            1           14s
```

This confirms that your pod is up and running with one replica available.

### [Step 3. Verify the service exposure](#step-3-verify-the-service-exposure)

Check if the NodePort service is exposing your app to your local machine:

```console
$ kubectl get services
```

You should see something like:

```shell
NAME                     TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
angular-sample-service   NodePort    10.100.185.105    <none>        8080:30001/TCP   1m
```

This output confirms that your app is available via NodePort on port 30001.

### [Step 4. Access your app in the browser](#step-4-access-your-app-in-the-browser)

Open your browser and navigate to <http://localhost:30001>.

You should see your production-ready Angular Sample application running — served by your local Kubernetes cluster.

### [Step 5. Clean up Kubernetes resources](#step-5-clean-up-kubernetes-resources)

Once you're done testing, you can delete the deployment and service using:

```console
  $ kubectl delete -f angular-sample-kubernetes.yaml
```

Expected output:

```shell
  deployment.apps "angular-sample" deleted
  service "angular-sample-service" deleted
```

This ensures your cluster stays clean and ready for the next deployment.

***

## [Summary](#summary)

In this section, you learned how to deploy your Angular application to a local Kubernetes cluster using Docker Desktop. This setup allows you to test and debug your containerized app in a production-like environment before deploying it to the cloud.

What you accomplished:

* Created a Kubernetes Deployment and NodePort Service for your Angular app
* Used `kubectl apply` to deploy the application locally
* Verified the app was running and accessible at `http://localhost:30001`
* Cleaned up your Kubernetes resources after testing

***

----
url: https://docs.docker.com/compose/intro/features-uses/
----

# Why use Compose?

***

Table of contents

***

## [Key benefits of Docker Compose](#key-benefits-of-docker-compose)

Using Docker Compose offers several benefits that streamline the development, deployment, and management of containerized applications:

* Simplified control: Define and manage multi-container apps in one YAML file, streamlining orchestration and replication.

* Efficient collaboration: Shareable YAML files support smooth collaboration between developers and operations, improving workflows and issue resolution, leading to increased overall efficiency.

* Rapid application development: Compose caches the configuration used to create a container. When you restart a service that has not changed, Compose reuses the existing containers. Reusing containers means that you can make changes to your environment quickly.

* Portability across environments: Compose supports variables in the Compose file. You can use these variables to customize your composition for different environments, or different users.

## [Common use cases of Docker Compose](#common-use-cases-of-docker-compose)

Compose can be used in many different ways. Some common use cases are outlined below.

### [Development environments](#development-environments)

When you're developing software, the ability to run an application in an isolated environment and interact with it is crucial. The Compose command line tool can be used to create the environment and interact with it.

The [Compose file](https://docs.docker.com/reference/compose-file/) provides a way to document and configure all of the application's service dependencies (databases, queues, caches, web service APIs, etc). Using the Compose command line tool you can create and start one or more containers for each dependency with a single command (`docker compose up`).

Together, these features provide a convenient way for you to get started on a project. Compose can reduce a multi-page "developer getting started guide" to a single machine-readable Compose file and a few commands.

### [Automated testing environments](#automated-testing-environments)

An important part of any Continuous Deployment or Continuous Integration process is the automated test suite. Automated end-to-end testing requires an environment in which to run tests. Compose provides a convenient way to create and destroy isolated testing environments for your test suite. By defining the full environment in a [Compose file](https://docs.docker.com/reference/compose-file/), you can create and destroy these environments in just a few commands:

```console
$ docker compose up -d
$ ./run_tests
$ docker compose down
```

### [Single host deployments](#single-host-deployments)

Compose supports production deployments on single hosts. You can use Compose to deploy applications to remote Docker hosts and manage production-specific configurations.

For details on using production-oriented features, see [Compose in production](https://docs.docker.com/compose/how-tos/production/).

## [What's next?](#whats-next)

* [Learn about the history of Compose](https://docs.docker.com/compose/intro/history/)

----
url: https://docs.docker.com/admin/organization/manage/manage-a-team/
----

# Create and manage a team

***

Table of contents

***

Subscription: Team Business

For: Administrators

You can create teams for your organization in the Admin Console or Docker Hub, and configure team repository access in Docker Hub.

A team is a group of Docker users that belong to an organization. An organization can have multiple teams. An organization owner can create new teams and add members to an existing team using their Docker ID or email address. Members aren't required to be part of a team to be associated with an organization.

The organization owner can add additional organization owners to help them manage users, teams, and repositories in the organization by assigning them the owner role.

## [What is an organization owner?](#what-is-an-organization-owner)

An organization owner is an administrator who has the following permissions:

* Manage repositories and add team members to the organization
* Access private repositories, all teams, billing information, and organization settings
* Specify [permissions](#permissions-reference) for each team in the organization
* Enable [SSO](https://docs.docker.com/enterprise/security/single-sign-on/) for the organization

When SSO is enabled for your organization, the organization owner can also manage users. Docker can auto-provision Docker IDs for new end-users or users who'd like to have a separate Docker ID for company use through SSO enforcement.

Organization owners can add others with the owner role to help them manage users, teams, and repositories in the organization.

For more information on roles, see [Roles and permissions](https://docs.docker.com/enterprise/security/roles-and-permissions/).

## [Create a team](#create-a-team)

1. Sign in to [Docker Home](https://app.docker.com) and select your organization.
2. Select **Teams**.
3. Select **Create team**.
4. Provide the team's information, then select **Create**.

## [Set team repository permissions](#set-team-repository-permissions)

You must create a team before you are able to configure repository permissions. For more details, see [Create and manage a team](https://docs.docker.com/admin/organization/manage/manage-a-team/).

To set team repository permissions:

### [Permissions reference](#permissions-reference)

* `Read-only` access lets users view, search, and pull a private repository in the same way as they can a public repository.
* `Read & Write` access lets users pull, push, and view a repository. In addition, it lets users view, cancel, retry or trigger builds.
* `Admin` access lets users pull, push, view, edit, and delete a repository. You can also edit build settings and update the repository’s description, collaborator permissions, public/private visibility, and delete.

Permissions are cumulative. For example, if you have "Read & Write" permissions, you automatically have "Read-only" permissions.

The following table shows what each permission level allows users to do:

| Action                          | Read-only | Read & Write | Admin |
| ------------------------------- | --------- | ------------ | ----- |
| Pull a Repository               | ✅         | ✅            | ✅     |
| View a Repository               | ✅         | ✅            | ✅     |
| Push a Repository               | ❌         | ✅            | ✅     |
| Edit a Repository               | ❌         | ❌            | ✅     |
| Delete a Repository             | ❌         | ❌            | ✅     |
| Update a Repository Description | ❌         | ❌            | ✅     |
| View Builds                     | ✅         | ✅            | ✅     |
| Cancel Builds                   | ❌         | ✅            | ✅     |
| Retry Builds                    | ❌         | ✅            | ✅     |
| Trigger Builds                  | ❌         | ✅            | ✅     |
| Edit Build Settings             | ❌         | ❌            | ✅     |

> Note
>
> A user who hasn't verified their email address only has `Read-only` access to the repository, regardless of the rights their team membership has given them.

## [Delete a team](#delete-a-team)

Organization owners can delete a team. When you remove a team from your organization, this action revokes member access to the team's permitted resources. It won't remove users from other teams that they belong to, and it won't delete any resources.

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.
2. Select **Teams**.
3. Select the **Actions** icon next to the name of the team you want to delete.
4. Select **Delete team**.
5. Review the confirmation message, then select **Delete**.

## [More resources](#more-resources)

* [Video: Docker Teams](https://youtu.be/WKlT1O-4Du8?feature=shared\&t=348)
* [Video: Roles, teams, and repositories](https://youtu.be/WKlT1O-4Du8?feature=shared\&t=435)

----
url: https://docs.docker.com/reference/cli/docker/model/run/
----

# docker model run

***

| Description | Run a model and interact with it using a submitted prompt or chat mode |
| ----------- | ---------------------------------------------------------------------- |
| Usage       | `docker model run MODEL [PROMPT]`                                      |

## [Description](#description)

When you run a model, Docker calls an inference server API endpoint hosted by the Model Runner through Docker Desktop. The model stays in memory until another model is requested, or until a pre-defined inactivity timeout is reached (currently 5 minutes).

You do not have to use Docker model run before interacting with a specific model from a host process or from within a container. Model Runner transparently loads the requested model on-demand, assuming it has been pulled and is locally available.

You can also use chat mode in the Docker Desktop Dashboard when you select the model in the **Models** tab.

## [Options](#options)

| Option         | Default | Description                                          |
| -------------- | ------- | ---------------------------------------------------- |
| `--color`      | `no`    | Use colored output (auto\|yes\|no)                   |
| `--debug`      |         | Enable debug logging                                 |
| `-d, --detach` |         | Load the model in the background without interaction |
| `--openaiurl`  |         | OpenAI-compatible API endpoint URL to chat with      |
| `--websearch`  |         | Enable web search tool during chat                   |

## [Examples](#examples)

### [One-time prompt](#one-time-prompt)

```console
docker model run ai/smollm2 "Hi"
```

Output:

```console
Hello! How can I assist you today?
```

### [Interactive chat](#interactive-chat)

```console
docker model run ai/smollm2
```

Output:

```console
> Hi
Hi there! It's SmolLM, AI assistant. How can I help you today?
> /bye
```

### [Pre-load a model](#pre-load-a-model)

```console
docker model run --detach ai/smollm2
```

This loads the model into memory without interaction, ensuring maximum performance for subsequent requests.

----
url: https://docs.docker.com/reference/cli/docker/model/pull/
----

# docker model pull

***

| Description | Pull a model from Docker Hub or HuggingFace to your local environment |
| ----------- | --------------------------------------------------------------------- |
| Usage       | `docker model pull MODEL`                                             |

## [Description](#description)

Pull a model to your local environment. Downloaded models also appear in the Docker Desktop Dashboard.

## [Examples](#examples)

### [Pulling a model from Docker Hub](#pulling-a-model-from-docker-hub)

```console
docker model pull ai/smollm2
```

### [Pulling from HuggingFace](#pulling-from-huggingface)

You can pull GGUF models directly from [Hugging Face](https://huggingface.co/models?library=gguf).

**Note about quantization:** If no tag is specified, the command tries to pull the `Q4_K_M` version of the model. If `Q4_K_M` doesn't exist, the command pulls the first GGUF found in the **Files** view of the model on HuggingFace. To specify the quantization, provide it as a tag, for example: `docker model pull hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF:Q4_K_S`

```console
docker model pull hf.co/bartowski/Llama-3.2-1B-Instruct-GGUF
```

----
url: https://docs.docker.com/ai/mcp-catalog-and-toolkit/faqs/
----

# MCP Toolkit FAQs

***

Table of contents

***

Docker MCP Catalog and Toolkit is a solution for securely building, sharing, and running MCP tools. This page answers common questions about MCP Catalog and Toolkit security.

### [What process does Docker follow to add a new MCP server to the catalog?](#what-process-does-docker-follow-to-add-a-new-mcp-server-to-the-catalog)

Developers can submit a pull request to the [Docker MCP Registry](https://github.com/docker/mcp-registry) to propose new servers. Docker provides detailed [contribution guidelines](https://github.com/docker/mcp-registry/blob/main/CONTRIBUTING.md) to help developers meet the required standards.

Currently, a majority of the servers in the catalog are built directly by Docker. Each server includes attestations such as:

* Build attestation: Servers are built on Docker Build Cloud.
* Source provenance: Verifiable source code origins.
* Signed SBOMs: Software Bill of Materials with cryptographic signatures.

> Note
>
> When using the images with [Docker MCP gateway](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/), you can verify attestations at runtime using the `docker mcp gateway run --verify-signatures` CLI command.

In addition to Docker-built servers, the catalog includes select servers from trusted registries such as GitHub and HashiCorp. Each third-party server undergoes a verification process that includes:

* Pulling and building the code in an ephemeral build environment.
* Testing initialization and functionality.
* Verifying that tools can be successfully listed.

### [Under what conditions does Docker reject MCP server submissions?](#under-what-conditions-does-docker-reject-mcp-server-submissions)

Docker rejects MCP server submissions that fail automated testing and validation processes during pull request review. Additionally, Docker reviewers evaluate submissions against specific requirements and reject MCP servers that don't meet these criteria.

### [Does Docker take accountability for malicious MCP servers in the Toolkit?](#does-docker-take-accountability-for-malicious-mcp-servers-in-the-toolkit)

Docker’s security measures currently represent a best-effort approach. While Docker implements automated testing, scanning, and metadata extraction for each server in the catalog, these security measures are not yet exhaustive. Docker is actively working to enhance its security processes and expand testing coverage. Enterprise customers can contact their Docker account manager for specific security requirements and implementation details.

### [How are credentials managed for MCP servers?](#how-are-credentials-managed-for-mcp-servers)

Starting with Docker Desktop version 4.43.0, credentials are stored securely in the Docker Desktop VM. The storage implementation depends on the platform (for example, macOS, WSL2). You can manage the credentials using the following CLI commands:

* `docker mcp secret ls` - List stored credentials
* `docker mcp secret rm` - Remove specific credentials
* `docker mcp oauth revoke` - Revoke OAuth-based credentials

In the upcoming versions of Docker Desktop, Docker plans to support pluggable storage for these secrets and additional out-of-the-box storage providers to give users more flexibility in managing credentials.

### [Are credentials removed when an MCP server is uninstalled?](#are-credentials-removed-when-an-mcp-server-is-uninstalled)

No. MCP servers are not technically uninstalled since they exist as Docker containers pulled to your local Docker Desktop. Removing an MCP server stops the container but leaves the image on your system. Even if the container is deleted, credentials remain stored until you remove them manually.

### [Why don't I see remote MCP servers in the catalog?](#why-dont-i-see-remote-mcp-servers-in-the-catalog)

If remote MCP servers aren't visible in the Docker Desktop catalog, your local catalog may be out of date. Remote servers are indicated by a cloud icon and include services like GitHub, Notion, and Linear.

Update your catalog by running:

```console
$ docker mcp catalog update
```

After the update completes, refresh the **Catalog** tab in Docker Desktop.

### [What's the difference between profiles and the catalog?](#whats-the-difference-between-profiles-and-the-catalog)

The [catalog](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/) is the source of available MCP servers - a library of tools you can choose from. [Profiles](https://docs.docker.com/ai/mcp-catalog-and-toolkit/profiles/) are collections of servers you've added to organize your work. Think of the catalog as a library, and profiles as your personal bookshelves containing the books you've selected for different purposes.

### [Can I share profiles with my team?](#can-i-share-profiles-with-my-team)

Yes. Profiles can be pushed to OCI-compliant registries using `docker mcp profile push my-profile registry.example.com/profiles/my-profile:v1`. Team members can pull your profile with `docker mcp profile pull registry.example.com/profiles/my-profile:v1`. Note that credentials aren't included in shared profiles for security reasons - team members need to configure OAuth and other credentials separately.

### [Do I need to create a profile to use MCP Toolkit?](#do-i-need-to-create-a-profile-to-use-mcp-toolkit)

Yes, MCP Toolkit requires a profile to run servers. If you're upgrading from a version before profiles were introduced, a default profile is automatically created for you with your existing server configurations. You can create additional named profiles to organize servers for different projects or environments.

### [What happens to servers when I switch profiles?](#what-happens-to-servers-when-i-switch-profiles)

Each profile contains its own set of servers and configurations. When you run the gateway with `--profile profile-name`, only servers in that profile are available to clients. The default profile is used when no profile is specified. Switching between profiles changes which servers your AI applications can access.

### [Can I use the same server in multiple profiles?](#can-i-use-the-same-server-in-multiple-profiles)

Yes. You can add the same MCP server to multiple profiles, each with different configurations if needed. This is useful when you need the same server with different settings for different projects or environments.

## [Related pages](#related-pages)

* [Get started with MCP Toolkit](https://docs.docker.com/ai/mcp-catalog-and-toolkit/get-started/)
* [Open-source MCP Gateway](https://docs.docker.com/ai/mcp-catalog-and-toolkit/mcp-gateway/)

----
url: https://docs.docker.com/reference/cli/docker/container/restart/
----

# docker container restart

***

| Description                                                               | Restart one or more containers                                |
| ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Usage                                                                     | `docker container restart [OPTIONS] CONTAINER [CONTAINER...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker restart`                                              |

## [Description](#description)

Restart one or more containers

## [Options](#options)

| Option                      | Default | Description                                  |
| --------------------------- | ------- | -------------------------------------------- |
| [`-s, --signal`](#signal)   |         | Signal to send to the container              |
| [`-t, --timeout`](#timeout) |         | Seconds to wait before killing the container |

## [Examples](#examples)

```console
$ docker restart my_container
```

### [Stop container with signal (-s, --signal)](#signal)

The `--signal` flag sends the system call signal to the container to exit. This signal can be a signal name in the format `SIG<NAME>`, for instance `SIGKILL`, or an unsigned number that matches a position in the kernel's syscall table, for instance `9`. Refer to [signal(7)](https://man7.org/linux/man-pages/man7/signal.7.html) for available signals.

The default signal to use is defined by the image's [`StopSignal`](https://github.com/opencontainers/image-spec/blob/v1.1.0/config.md), which can be set through the [`STOPSIGNAL`](/reference/dockerfile/#stopsignal) Dockerfile instruction when building the image, or configured using the [`--stop-signal`](/reference/cli/docker/container/run/#stop-signal) option when creating the container. If no signal is configured for the container, `SIGTERM` is used as default.

### [Stop container with timeout (-t, --timeout)](#timeout)

The `--timeout` flag sets the number of seconds to wait for the container to stop after sending the pre-defined (see [`--signal`](#signal)) system call signal. If the container does not exit after the timeout elapses, it's forcibly killed with a `SIGKILL` signal.

If you set `--timeout` to `-1`, no timeout is applied, and the daemon waits indefinitely for the container to exit.

The default timeout can be specified using the [`--stop-timeout`](/reference/cli/docker/container/run/#stop-timeout) option when creating the container. If no default is configured for the container, the Daemon determines the default, and is 10 seconds for Linux containers, and 30 seconds for Windows containers.

----
url: https://docs.docker.com/scout/how-tos/create-exceptions-gui/
----

# Create an exception using the GUI

***

Table of contents

***

The Docker Scout Dashboard and Docker Desktop provide a user-friendly interface for creating [exceptions](https://docs.docker.com/scout/explore/exceptions/) for vulnerabilities found in container images. Exceptions let you acknowledge accepted risks or address false positives in image analysis.

## [Prerequisites](#prerequisites)

To create an in the Docker Scout Dashboard or Docker Desktop, you need a Docker account with **Editor** or **Owner** permissions for the Docker organization that owns the image.

## [Steps](#steps)

To create an exception for a vulnerability in an image using the Docker Scout Dashboard or Docker Desktop:

1. Go to the [Images page](https://scout.docker.com/reports/images).
2. Select the image tag that contains the vulnerability you want to create an exception for.
3. Open the **Image layers** tab.
4. Select the layer that contains the vulnerability you want to create an exception for.
5. In the **Vulnerabilities** tab, find the vulnerability you want to create an exception for. Vulnerabilities are grouped by package. Find the package that contains the vulnerability you want to create an exception for, and then expand the package.
6. Select the **Create exception** button next to the vulnerability.

Selecting the **Create exception** button opens the **Create exception** side panel. In this panel, you can provide the details of the exception:

* **Exception type**: The type of exception. The only supported types are:

  * **Accepted risk**: The vulnerability is not addressed due to its minimal security risk, high remediation costs, dependence on an upstream fix, or similar.

  * **False positive**: The vulnerability presents no security risk in your specific use case, configuration, or because of measures in place that block exploitation

    If you select **False positive**, you must provide a justification for why the vulnerability is a false positive:

* **Additional details**: Any additional information that you want to provide about the exception.

* **Scope**: The scope of the exception. The scope can be:

  * **Image**: The exception applies to the selected image.
  * **All images in repository**: The exception applies to all images in the repository.
  * **Specific repository**: The exception applies to all images in the specified repositories.
  * **All images in my organization**: The exception applies to all images in your organization.

* **Package scope**: The scope of the exception. The package scope can be:

  * **Selected package**: The exception applies to the selected package.
  * **Any packages**: The exception applies to all packages vulnerable to this CVE.

When you've filled in the details, select the **Create** button to create the exception.

The exception is now created and factored into the analysis results for the images that you selected. The exception is also listed on the **Exceptions** tab of the [Vulnerabilities page](https://scout.docker.com/reports/vulnerabilities/exceptions) in the Docker Scout Dashboard.

1. Open the **Images** view in Docker Desktop.
2. Open the **Hub** tab.
3. Select the image tag that contains the vulnerability you want to create an exception for.
4. Select the layer that contains the vulnerability you want to create an exception for.
5. In the **Vulnerabilities** tab, find the vulnerability you want to create an exception for.
6. Select the **Create exception** button next to the vulnerability.

Selecting the **Create exception** button opens the **Create exception** side panel. In this panel, you can provide the details of the exception:

* **Exception type**: The type of exception. The only supported types are:

  * **Accepted risk**: The vulnerability is not addressed due to its minimal security risk, high remediation costs, dependence on an upstream fix, or similar.

  * **False positive**: The vulnerability presents no security risk in your specific use case, configuration, or because of measures in place that block exploitation

    If you select **False positive**, you must provide a justification for why the vulnerability is a false positive:

* **Additional details**: Any additional information that you want to provide about the exception.

* **Scope**: The scope of the exception. The scope can be:

  * **Image**: The exception applies to the selected image.
  * **All images in repository**: The exception applies to all images in the repository.
  * **Specific repository**: The exception applies to all images in the specified repositories.
  * **All images in my organization**: The exception applies to all images in your organization.

* **Package scope**: The scope of the exception. The package scope can be:

  * **Selected package**: The exception applies to the selected package.
  * **Any packages**: The exception applies to all packages vulnerable to this CVE.

When you've filled in the details, select the **Create** button to create the exception.

The exception is now created and factored into the analysis results for the images that you selected. The exception is also listed on the **Exceptions** tab of the [Vulnerabilities page](https://scout.docker.com/reports/vulnerabilities/exceptions) in the Docker Scout Dashboard.

----
url: https://docs.docker.com/engine/swarm/admin_guide/
----

# Administer and maintain a swarm of Docker Engines

***

Table of contents

***

When you run a swarm of Docker Engines, manager nodes are the key components for managing the swarm and storing the swarm state. It is important to understand some key features of manager nodes to properly deploy and maintain the swarm.

Refer to [How nodes work](https://docs.docker.com/engine/swarm/how-swarm-mode-works/nodes/) for a brief overview of Docker Swarm mode and the difference between manager and worker nodes.

## [Operate manager nodes in a swarm](#operate-manager-nodes-in-a-swarm)

Swarm manager nodes use the [Raft Consensus Algorithm](https://docs.docker.com/engine/swarm/raft/) to manage the swarm state. You only need to understand some general concepts of Raft in order to manage a swarm.

There is no limit on the number of manager nodes. The decision about how many manager nodes to implement is a trade-off between performance and fault-tolerance. Adding manager nodes to a swarm makes the swarm more fault-tolerant. However, additional manager nodes reduce write performance because more nodes must acknowledge proposals to update the swarm state. This means more network round-trip traffic.

Raft requires a majority of managers, also called the quorum, to agree on proposed updates to the swarm, such as node additions or removals. Membership operations are subject to the same constraints as state replication.

### [Maintain the quorum of managers](#maintain-the-quorum-of-managers)

If the swarm loses the quorum of managers, the swarm cannot perform management tasks. If your swarm has multiple managers, always have more than two. To maintain quorum, a majority of managers must be available. An odd number of managers is recommended, because the next even number does not make the quorum easier to keep. For instance, whether you have 3 or 4 managers, you can still only lose 1 manager and maintain the quorum. If you have 5 or 6 managers, you can still only lose two.

Even if a swarm loses the quorum of managers, swarm tasks on existing worker nodes continue to run. However, swarm nodes cannot be added, updated, or removed, and new or existing tasks cannot be started, stopped, moved, or updated.

See [Recovering from losing the quorum](#recover-from-losing-the-quorum) for troubleshooting steps if you do lose the quorum of managers.

## [Configure the manager to advertise on a static IP address](#configure-the-manager-to-advertise-on-a-static-ip-address)

When initiating a swarm, you must specify the `--advertise-addr` flag to advertise your address to other manager nodes in the swarm. For more information, see [Run Docker Engine in swarm mode](https://docs.docker.com/engine/swarm/swarm-mode/#configure-the-advertise-address). Because manager nodes are meant to be a stable component of the infrastructure, you should use a *fixed IP address* for the advertise address to prevent the swarm from becoming unstable on machine reboot.

If the whole swarm restarts and every manager node subsequently gets a new IP address, there is no way for any node to contact an existing manager. Therefore the swarm is hung while nodes try to contact one another at their old IP addresses.

Dynamic IP addresses are OK for worker nodes.

## [Add manager nodes for fault tolerance](#add-manager-nodes-for-fault-tolerance)

You should maintain an odd number of managers in the swarm to support manager node failures. Having an odd number of managers ensures that during a network partition, there is a higher chance that the quorum remains available to process requests if the network is partitioned into two sets. Keeping the quorum is not guaranteed if you encounter more than two network partitions.

| Swarm Size | Majority | Fault Tolerance |
| ---------- | -------- | --------------- |
| 1          | 1        | 0               |
| 2          | 2        | 0               |
| **3**      | 2        | **1**           |
| 4          | 3        | 1               |
| **5**      | 3        | **2**           |
| 6          | 4        | 2               |
| **7**      | 4        | **3**           |
| 8          | 5        | 3               |
| **9**      | 5        | **4**           |

For example, in a swarm with *5 nodes*, if you lose *3 nodes*, you don't have a quorum. Therefore you can't add or remove nodes until you recover one of the unavailable manager nodes or recover the swarm with disaster recovery commands. See [Recover from disaster](#recover-from-disaster).

While it is possible to scale a swarm down to a single manager node, it is impossible to demote the last manager node. This ensures you maintain access to the swarm and that the swarm can still process requests. Scaling down to a single manager is an unsafe operation and is not recommended. If the last node leaves the swarm unexpectedly during the demote operation, the swarm becomes unavailable until you reboot the node or restart with `--force-new-cluster`.

You manage swarm membership with the `docker swarm` and `docker node` subsystems. Refer to [Add nodes to a swarm](https://docs.docker.com/engine/swarm/join-nodes/) for more information on how to add worker nodes and promote a worker node to be a manager.

### [Distribute manager nodes](#distribute-manager-nodes)

In addition to maintaining an odd number of manager nodes, pay attention to datacenter topology when placing managers. For optimal fault-tolerance, distribute manager nodes across a minimum of 3 availability-zones to support failures of an entire set of machines or common maintenance scenarios. If you suffer a failure in any of those zones, the swarm should maintain the quorum of manager nodes available to process requests and rebalance workloads.

| Swarm manager nodes | Repartition (on 3 Availability zones) |
| ------------------- | ------------------------------------- |
| 3                   | 1-1-1                                 |
| 5                   | 2-2-1                                 |
| 7                   | 3-2-2                                 |
| 9                   | 3-3-3                                 |

### [Run manager-only nodes](#run-manager-only-nodes)

By default manager nodes also act as a worker nodes. This means the scheduler can assign tasks to a manager node. For small and non-critical swarms assigning tasks to managers is relatively low-risk as long as you schedule services using resource constraints for cpu and memory.

However, because manager nodes use the Raft consensus algorithm to replicate data in a consistent way, they are sensitive to resource starvation. You should isolate managers in your swarm from processes that might block swarm operations like swarm heartbeat or leader elections.

To avoid interference with manager node operation, you can drain manager nodes to make them unavailable as worker nodes:

```console
$ docker node update --availability drain NODE
```

When you drain a node, the scheduler reassigns any tasks running on the node to other available worker nodes in the swarm. It also prevents the scheduler from assigning tasks to the node.

## [Add worker nodes for load balancing](#add-worker-nodes-for-load-balancing)

[Add nodes to the swarm](https://docs.docker.com/engine/swarm/join-nodes/) to balance your swarm's load. Replicated service tasks are distributed across the swarm as evenly as possible over time, as long as the worker nodes are matched to the requirements of the services. When limiting a service to run on only specific types of nodes, such as nodes with a specific number of CPUs or amount of memory, remember that worker nodes that do not meet these requirements cannot run these tasks.

## [Monitor swarm health](#monitor-swarm-health)

You can monitor the health of manager nodes by querying the docker `nodes` API in JSON format through the `/nodes` HTTP endpoint. Refer to the [nodes API documentation](/reference/api/engine/version/v1.25/#tag/Node) for more information.

From the command line, run `docker node inspect <id-node>` to query the nodes. For instance, to query the reachability of the node as a manager:

```console
$ docker node inspect manager1 --format "{{ .ManagerStatus.Reachability }}"
reachable
```

To query the status of the node as a worker that accept tasks:

```console
$ docker node inspect manager1 --format "{{ .Status.State }}"
ready
```

From those commands, we can see that `manager1` is both at the status `reachable` as a manager and `ready` as a worker.

An `unreachable` health status means that this particular manager node is unreachable from other manager nodes. In this case you need to take action to restore the unreachable manager:

* Restart the daemon and see if the manager comes back as reachable.
* Reboot the machine.
* If neither restarting nor rebooting works, you should add another manager node or promote a worker to be a manager node. You also need to cleanly remove the failed node entry from the manager set with `docker node demote <NODE>` and `docker node rm <id-node>`.

Alternatively you can also get an overview of the swarm health from a manager node with `docker node ls`:

```console
$ docker node ls
ID                           HOSTNAME  MEMBERSHIP  STATUS  AVAILABILITY  MANAGER STATUS
1mhtdwhvsgr3c26xxbnzdc3yp    node05    Accepted    Ready   Active
516pacagkqp2xc3fk9t1dhjor    node02    Accepted    Ready   Active        Reachable
9ifojw8of78kkusuc4a6c23fx *  node01    Accepted    Ready   Active        Leader
ax11wdpwrrb6db3mfjydscgk7    node04    Accepted    Ready   Active
bb1nrq2cswhtbg4mrsqnlx1ck    node03    Accepted    Ready   Active        Reachable
di9wxgz8dtuh9d2hn089ecqkf    node06    Accepted    Ready   Active
```

## [Troubleshoot a manager node](#troubleshoot-a-manager-node)

You should never restart a manager node by copying the `raft` directory from another node. The data directory is unique to a node ID. A node can only use a node ID once to join the swarm. The node ID space should be globally unique.

To cleanly re-join a manager node to a cluster:

1. Demote the node to a worker using `docker node demote <NODE>`.
2. Remove the node from the swarm using `docker node rm <NODE>`.
3. Re-join the node to the swarm with a fresh state using `docker swarm join`.

For more information on joining a manager node to a swarm, refer to [Join nodes to a swarm](https://docs.docker.com/engine/swarm/join-nodes/).

## [Forcibly remove a node](#forcibly-remove-a-node)

In most cases, you should shut down a node before removing it from a swarm with the `docker node rm` command. If a node becomes unreachable, unresponsive, or compromised you can forcefully remove the node without shutting it down by passing the `--force` flag. For instance, if `node9` becomes compromised:

```console
$ docker node rm node9

Error response from daemon: rpc error: code = 9 desc = node node9 is not down and can't be removed

$ docker node rm --force node9

Node node9 removed from swarm
```

Before you forcefully remove a manager node, you must first demote it to the worker role. Make sure that you always have an odd number of manager nodes if you demote or remove a manager.

## [Back up the swarm](#back-up-the-swarm)

Docker manager nodes store the swarm state and manager logs in the `/var/lib/docker/swarm/` directory. This data includes the keys used to encrypt the Raft logs. Without these keys, you cannot restore the swarm.

You can back up the swarm using any manager. Use the following procedure.

1. If the swarm has auto-lock enabled, you need the unlock key to restore the swarm from backup. Retrieve the unlock key if necessary and store it in a safe location. If you are unsure, read [Lock your swarm to protect its encryption key](https://docs.docker.com/engine/swarm/swarm_manager_locking/).

2. Stop Docker on the manager before backing up the data, so that no data is being changed during the backup. It is possible to take a backup while the manager is running (a "hot" backup), but this is not recommended and your results are less predictable when restoring. While the manager is down, other nodes continue generating swarm data that is not part of this backup.

   > Note
   >
   > Be sure to maintain the quorum of swarm managers. During the time that a manager is shut down, your swarm is more vulnerable to losing the quorum if further nodes are lost. The number of managers you run is a trade-off. If you regularly take down managers to do backups, consider running a five manager swarm, so that you can lose an additional manager while the backup is running, without disrupting your services.

3. Back up the entire `/var/lib/docker/swarm` directory.

4. Restart the manager.

To restore, see [Restore from a backup](#restore-from-a-backup).

## [Recover from disaster](#recover-from-disaster)

### [Restore from a backup](#restore-from-a-backup)

After backing up the swarm as described in [Back up the swarm](#back-up-the-swarm), use the following procedure to restore the data to a new swarm.

1. Shut down Docker on the target host machine for the restored swarm.

2. Remove the contents of the `/var/lib/docker/swarm` directory on the new swarm.

3. Restore the `/var/lib/docker/swarm` directory with the contents of the backup.

   > Note
   >
   > The new node uses the same encryption key for on-disk storage as the old one. It is not possible to change the on-disk storage encryption keys at this time.
   >
   > In the case of a swarm with auto-lock enabled, the unlock key is also the same as on the old swarm, and the unlock key is needed to restore the swarm.

4. Start Docker on the new node. Unlock the swarm if necessary. Re-initialize the swarm using the following command, so that this node does not attempt to connect to nodes that were part of the old swarm, and presumably no longer exist.

   ```console
   $ docker swarm init --force-new-cluster
   ```

5. Verify that the state of the swarm is as expected. This may include application-specific tests or simply checking the output of `docker service ls` to be sure that all expected services are present.

6. If you use auto-lock, [rotate the unlock key](https://docs.docker.com/engine/swarm/swarm_manager_locking/#rotate-the-unlock-key).

7. Add manager and worker nodes to bring your new swarm up to operating capacity.

8. Reinstate your previous backup regimen on the new swarm.

### [Recover from losing the quorum](#recover-from-losing-the-quorum)

Swarm is resilient to failures and can recover from any number of temporary node failures (machine reboots or crash with restart) or other transient errors. However, a swarm cannot automatically recover if it loses a quorum. Tasks on existing worker nodes continue to run, but administrative tasks are not possible, including scaling or updating services and joining or removing nodes from the swarm. The best way to recover is to bring the missing manager nodes back online. If that is not possible, continue reading for some options for recovering your swarm.

In a swarm of `N` managers, a quorum (a majority) of manager nodes must always be available. For example, in a swarm with five managers, a minimum of three must be operational and in communication with each other. In other words, the swarm can tolerate up to `(N-1)/2` permanent failures beyond which requests involving swarm management cannot be processed. These types of failures include data corruption or hardware failures.

If you lose the quorum of managers, you cannot administer the swarm. If you have lost the quorum and you attempt to perform any management operation on the swarm, an error occurs:

```text
Error response from daemon: rpc error: code = 4 desc = context deadline exceeded
```

The best way to recover from losing the quorum is to bring the failed nodes back online. If you can't do that, the only way to recover from this state is to use the `--force-new-cluster` action from a manager node. This removes all managers except the manager the command was run from. The quorum is achieved because there is now only one manager. Promote nodes to be managers until you have the desired number of managers.

From the node to recover, run:

```console
$ docker swarm init --force-new-cluster --advertise-addr node01:2377
```

When you run the `docker swarm init` command with the `--force-new-cluster` flag, the Docker Engine where you run the command becomes the manager node of a single-node swarm which is capable of managing and running services. The manager has all the previous information about services and tasks, worker nodes are still part of the swarm, and services are still running. You need to add or re-add manager nodes to achieve your previous task distribution and ensure that you have enough managers to maintain high availability and prevent losing the quorum.

## [Force the swarm to rebalance](#force-the-swarm-to-rebalance)

Generally, you do not need to force the swarm to rebalance its tasks. When you add a new node to a swarm, or a node reconnects to the swarm after a period of unavailability, the swarm does not automatically give a workload to the idle node. This is a design decision. If the swarm periodically shifted tasks to different nodes for the sake of balance, the clients using those tasks would be disrupted. The goal is to avoid disrupting running services for the sake of balance across the swarm. When new tasks start, or when a node with running tasks becomes unavailable, those tasks are given to less busy nodes. The goal is eventual balance, with minimal disruption to the end user.

You can use the `--force` or `-f` flag with the `docker service update` command to force the service to redistribute its tasks across the available worker nodes. This causes the service tasks to restart. Client applications may be disrupted. If you have configured it, your service uses a [rolling update](https://docs.docker.com/engine/swarm/swarm-tutorial/rolling-update/).

If you use an earlier version and you want to achieve an even balance of load across workers and don't mind disrupting running tasks, you can force your swarm to re-balance by temporarily scaling the service upward. Use `docker service inspect --pretty <servicename>` to see the configured scale of a service. When you use `docker service scale`, the nodes with the lowest number of tasks are targeted to receive the new workloads. There may be multiple under-loaded nodes in your swarm. You may need to scale the service up by modest increments a few times to achieve the balance you want across all the nodes.

When the load is balanced to your satisfaction, you can scale the service back down to the original scale. You can use `docker service ps` to assess the current balance of your service across nodes.

See also [`docker service scale`](/reference/cli/docker/service/scale/) and [`docker service ps`](/reference/cli/docker/service/ps/).

----
url: https://docs.docker.com/build/metadata/attestations/attestation-storage/
----

# Image attestation storage

***

Table of contents

***

Buildkit supports creating and attaching attestations to build artifacts. These attestations can provide valuable information from the build process, including, but not limited to: [SBOMs](https://en.wikipedia.org/wiki/Software_supply_chain), [SLSA Provenance](https://slsa.dev/provenance), build logs, etc.

This document describes the current custom format used to store attestations, which is designed to be compatible with current registry implementations today. In the future, we may support exporting attestations in additional formats.

Attestations are stored as manifest objects in the image index, similar in style to OCI artifacts.

## [Properties](#properties)

### [Attestation Manifest](#attestation-manifest)

Attestation manifests are attached to the root image index object, under a separate [OCI image manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md). Each attestation manifest can contain multiple [attestation blobs](#attestation-blob), with all the of the attestations in a manifest applying to a single platform manifest. All properties of standard OCI and Docker manifests continue to apply.

The image `config` descriptor will point to a valid [image config](https://github.com/opencontainers/image-spec/blob/main/config.md), however, it will not contain attestation-specific details, and should be ignored as it is only included for compatibility purposes.

Each image layer in `layers` will contain a descriptor for a single [attestation blob](#attestation-blob). The `mediaType` of each layer will be set in accordance to its contents, one of:

* `application/vnd.in-toto+json` (currently, the only supported option)

  Indicates an in-toto attestation blob

Any unknown `mediaType`s should be ignored.

To assist attestation traversal, the following annotations may be set on each layer descriptor:

* `in-toto.io/predicate-type`

  This annotation will be set if the enclosed attestation is an in-toto attestation (currently, the only supported option). The annotation will be set to contain the same value as the `predicateType` property present inside the attestation.

  When present, this annotation may be used to find the specific attestation(s) they are looking for to avoid pulling the contents of the others.

### [Attestation Blob](#attestation-blob)

The contents of each layer will be a blob dependent on its `mediaType`.

* `application/vnd.in-toto+json`

  The blob contents will contain a full [in-toto attestation statement](https://github.com/in-toto/attestation/blob/main/spec/README.md#statement):

  ```json
  {
    "_type": "https://in-toto.io/Statement/v0.1",
    "subject": [
      {
        "name": "NAME",
        "digest": {"ALGORITHM": "HEX_VALUE"}
      },
      ...
    ],
    "predicateType": "URI",
    "predicate": { ... }
  }
  ```

  The subject of the attestation should be set to be the same digest as the target manifest described in the [Attestation Manifest Descriptor](#attestation-manifest-descriptor), or some object within.

### [Attestation Manifest Descriptor](#attestation-manifest-descriptor)

Attestation manifests are attached to the root [image index](https://github.com/opencontainers/image-spec/blob/main/image-index.md), in the `manifests` key, after all the original runnable manifests. All properties of standard OCI and Docker manifest descriptors continue to apply.

To prevent container runtimes from accidentally pulling or running the image described in the manifest, the `platform` property of the attestation manifest will be set to `unknown/unknown`, as follows:

```json
"platform": {
  "architecture": "unknown",
  "os": "unknown"
}
```

To assist index traversal, the following annotations will be set on the manifest descriptor descriptor:

* `vnd.docker.reference.type`

  This annotation describes the type of the artifact, and will be set to `attestation-manifest`. If any other value is specified, the entire manifest should be ignored.

* `vnd.docker.reference.digest`

  This annotation will contain the digest of the object in the image index that the attestation manifest refers to.

  When present, this annotation can be used to find the matching attestation manifest for a selected image manifest.

## [Examples](#examples)

*Example showing an SBOM attestation attached to a `linux/amd64` image*

#### [Image index (`sha256:94acc2ca70c40f3f6291681f37ce9c767e3d251ce01c7e4e9b98ccf148c26260`):](#image-index-sha25694acc2ca70c40f3f6291681f37ce9c767e3d251ce01c7e4e9b98ccf148c26260)

This image index defines two descriptors: an AMD64 image `sha256:23678f31..` and an attestation manifest `sha256:02cb9aa7..` for that image.

```json
{
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "schemaVersion": 2,
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827",
      "size": 1234,
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:02cb9aa7600e73fcf41ee9f0f19cc03122b2d8be43d41ce4b21335118f5dd943",
      "size": 1234,
      "annotations": {
        "vnd.docker.reference.digest": "sha256:23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827",
        "vnd.docker.reference.type": "attestation-manifest"
      },
      "platform": {
         "architecture": "unknown",
         "os": "unknown"
      }
    }
  ]
}
```

#### [Attestation manifest (`sha256:02cb9aa7600e73fcf41ee9f0f19cc03122b2d8be43d41ce4b21335118f5dd943`):](#attestation-manifest-sha25602cb9aa7600e73fcf41ee9f0f19cc03122b2d8be43d41ce4b21335118f5dd943)

This attestation manifest contains one attestation that is an in-toto attestation that contains a "https\://spdx.dev/Document" predicate, signifying that it is defining a SBOM for the image.

```json
{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "schemaVersion": 2,
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3",
    "size": 123
  },
  "layers": [
    {
      "mediaType": "application/vnd.in-toto+json",
      "digest": "sha256:133ae3f9bcc385295b66c2d83b28c25a9f294ce20954d5cf922dda860429734a",
      "size": 1234,
      "annotations": {
        "in-toto.io/predicate-type": "https://spdx.dev/Document"
      }
    }
  ]
}
```

#### [Image config (`sha256:a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3`):](#image-config-sha256a781560066f20ec9c28f2115a95a886e5e71c7c7aa9d8fd680678498b82f3ea3)

```json
{
  "architecture": "unknown",
  "os": "unknown",
  "config": {},
  "rootfs": {
    "type": "layers",
    "diff_ids": [
      "sha256:133ae3f9bcc385295b66c2d83b28c25a9f294ce20954d5cf922dda860429734a"
    ]
  }
}
```

#### [Layer content (`sha256:1ea07d5e55eb47ad0e6bbfa2ec180fb580974411e623814e519064c88f022f5c`):](#layer-content-sha2561ea07d5e55eb47ad0e6bbfa2ec180fb580974411e623814e519064c88f022f5c)

Attestation body containing the SBOM data listing the packages used during the build in SPDX format.

```json
{
  "_type": "https://in-toto.io/Statement/v0.1",
  "predicateType": "https://spdx.dev/Document",
  "subject": [
    {
      "name": "_",
      "digest": {
        "sha256": "23678f31b3b3586c4fb318aecfe64a96a1f0916ba8faf9b2be2abee63fa9e827"
      }
    }
  ],
  "predicate": {
    "SPDXID": "SPDXRef-DOCUMENT",
    "spdxVersion": "SPDX-2.2",
    ...
```

----
url: https://docs.docker.com/scout/how-tos/configure-cli/
----

# Configure Docker Scout with environment variables

***

Table of contents

***

The following environment variables are available to configure the Docker Scout CLI commands, and the corresponding `docker/scout-cli` container image:

| Name                                        | Format  | Description                                                                                 |
| ------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| DOCKER\_SCOUT\_CACHE\_FORMAT                | String  | Format of the local image cache; can be `oci` or `tar` (default: `oci`)                     |
| DOCKER\_SCOUT\_CACHE\_DIR                   | String  | Directory where the local SBOM cache is stored (default: `$HOME/.docker/scout`)             |
| DOCKER\_SCOUT\_NO\_CACHE                    | Boolean | When set to `true`, disables the use of local SBOM cache                                    |
| DOCKER\_SCOUT\_OFFLINE                      | Boolean | Use [offline mode](#offline-mode) when indexing SBOM                                        |
| DOCKER\_SCOUT\_REGISTRY\_TOKEN              | String  | Token for authenticating to a registry when pulling images                                  |
| DOCKER\_SCOUT\_REGISTRY\_USER               | String  | Username for authenticating to a registry when pulling images                               |
| DOCKER\_SCOUT\_REGISTRY\_PASSWORD           | String  | Password or personal access token for authenticating to a registry when pulling images      |
| DOCKER\_SCOUT\_HUB\_USER                    | String  | Docker Hub username for authenticating to the Docker Scout backend                          |
| DOCKER\_SCOUT\_HUB\_PASSWORD                | String  | Docker Hub password or personal access token for authenticating to the Docker Scout backend |
| DOCKER\_SCOUT\_NEW\_VERSION\_WARN           | Boolean | Warn about new versions of the Docker Scout CLI                                             |
| DOCKER\_SCOUT\_EXPERIMENTAL\_WARN           | Boolean | Warn about experimental features                                                            |
| DOCKER\_SCOUT\_EXPERIMENTAL\_POLICY\_OUTPUT | Boolean | Disable experimental output for policy evaluation                                           |

## [Offline mode](#offline-mode)

Under normal operation, Docker Scout cross-references external systems, such as npm, NuGet, or proxy.golang.org, to retrieve additional information about packages found in your image.

When `DOCKER_SCOUT_OFFLINE` is set to `true`, Docker Scout image analysis runs in offline mode. Offline mode means Docker Scout doesn't make outbound requests to external systems.

To use offline mode:

```console
$ export DOCKER_SCOUT_OFFLINE=true
```

----
url: https://docs.docker.com/guides/rust/run-containers/
----

# Run your Rust image as a container

***

Table of contents

***

## [Prerequisite](#prerequisite)

You have completed [Build your Rust image](https://docs.docker.com/guides/rust/build-images/) and you have built an image.

## [Overview](#overview)

A container is a normal operating system process except that Docker isolates this process so that it has its own file system, its own networking, and its own isolated process tree separate from the host.

To run an image inside of a container, you use the `docker run` command. The `docker run` command requires one parameter which is the name of the image.

## [Run an image](#run-an-image)

Use `docker run` to run the image you built in [Build your Rust image](https://docs.docker.com/guides/rust/build-images/).

```console
$ docker run docker-rust-image-dhi
```

After running this command, you’ll notice that you weren't returned to the command prompt. This is because your application is a server that runs in a loop waiting for incoming requests without returning control back to the OS until you stop the container.

Open a new terminal then make a request to the server using the `curl` command.

```console
$ curl http://localhost:8000
```

You should see output like the following.

```console
curl: (7) Failed to connect to localhost port 8000 after 2236 ms: Couldn't connect to server
```

As you can see, your `curl` command failed. This means you weren't able to connect to the localhost on port 8000. This is normal because your container is running in isolation which includes networking. Stop the container and restart with port 8000 published on your local network.

To stop the container, press ctrl-c. This will return you to the terminal prompt.

To publish a port for your container, you’ll use the `--publish` flag (`-p` for short) on the `docker run` command. The format of the `--publish` command is `[host port]:[container port]`. So, if you wanted to expose port 8000 inside the container to port 3001 outside the container, you would pass `3001:8000` to the `--publish` flag.

You didn't specify a port when running the application in the container and the default is 8000. If you want your previous request going to port 8000 to work, you can map the host's port 3001 to the container's port 8000:

```console
$ docker run --publish 3001:8000 docker-rust-image-dhi
```

Now, rerun the curl command. Remember to open a new terminal.

```console
$ curl http://localhost:3001
```

You should see output like the following.

```console
Hello, Docker!
```

Success! You were able to connect to the application running inside of your container on port 8000. Switch back to the terminal where your container is running and stop it.

Press ctrl-c to stop the container.

## [Run in detached mode](#run-in-detached-mode)

This is great so far, but your sample application is a web server and you don't have to be connected to the container. Docker can run your container in detached mode or in the background. To do this, you can use the `--detach` or `-d` for short. Docker starts your container the same as before but this time will "detach" from the container and return you to the terminal prompt.

```console
$ docker run -d -p 3001:8000 docker-rust-image-dhi
3e4830e7f01304811d97dd3469d47a0c7a916a8b6c28ce0ef19c6f689a521144
```

Docker started your container in the background and printed the Container ID on the terminal.

Again, make sure that your container is running properly. Run the curl command again.

```console
$ curl http://localhost:3001
```

You should see output like the following.

```console
Hello, Docker!
```

## [List containers](#list-containers)

Since you ran your container in the background, how do you know if your container is running or what other containers are running on your machine? Well, to see a list of containers running on your machine, run `docker ps`. This is similar to how you use the ps command in Linux to see a list of processes.

You should see output like the following.

```console
CONTAINER ID   IMAGE                   COMMAND                  CREATED          STATUS          PORTS                                         NAMES
3e4830e7f013   docker-rust-image-dhi   "/server"                23 seconds ago   Up 22 seconds   0.0.0.0:3001->8000/tcp, [::]:3001->8000/tcp   youthful_lamport
```

The `docker ps` command provides a bunch of information about your running containers. You can see the container ID, the image running inside the container, the command that was used to start the container, when it was created, the status, ports that were exposed, and the name of the container.

You are probably wondering where the name of your container is coming from. Since you didn’t provide a name for the container when you started it, Docker generated a random name. You’ll fix this in a minute, but first you need to stop the container. To stop the container, run the `docker stop` command which does just that, stops the container. You need to pass the name of the container or you can use the container ID.

```console
$ docker stop youthful_lamport
youthful_lamport
```

Now, rerun the `docker ps` command to see a list of running containers.

```console
$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
```

## [Stop, start, and name containers](#stop-start-and-name-containers)

You can start, stop, and restart Docker containers. When you stop a container, it's not removed, but the status is changed to stopped and the process inside the container is stopped. When you ran the `docker ps` command in the previous module, the default output only shows running containers. When you pass the `--all` or `-a` for short, you see all containers on your machine, irrespective of their start or stop status.

```console
$ docker ps -a
CONTAINER ID   IMAGE                   COMMAND                  CREATED              STATUS                          PORTS                                         NAMES
3e4830e7f013   docker-rust-image-dhi   "/server"                About a minute ago   Exited (0) 28 seconds ago                                                     youthful_lamport
60009b7eaf40   docker-rust-image-dhi   "/server"                2 minutes ago        Exited (0) About a minute ago                                                 sharp_noyce
152e1d7d9eea   docker-rust-image-dhi   "/server ."              4 minutes ago        Exited (0) 2 minutes ago                                                      magical_bhabha
```

You should now see several containers listed. These are containers that you started and stopped but you haven't removed.

Restart the container that you just stopped. Locate the name of the container you just stopped and replace the name of the container in following restart command.

```console
$ docker restart youthful_lamport
```

Now list all the containers again using the `docker ps --all` command.

```console
$ docker ps --all
CONTAINER ID   IMAGE                   COMMAND                  CREATED             STATUS                         PORTS                                         NAMES
3e4830e7f013   docker-rust-image-dhi   "/server"                3 minutes ago       Up 7 seconds                   0.0.0.0:3001->8000/tcp, [::]:3001->8000/tcp   youthful_lamport
60009b7eaf40   docker-rust-image-dhi   "/server"                4 minutes ago       Exited (0) 3 minutes ago                                                     sharp_noyce
152e1d7d9eea   docker-rust-image-dhi   "/server ."              5 minutes ago       Exited (0) 4 minutes ago                                                     magical_bhabha
```

Notice that the container you just restarted has been started in detached mode. Also, observe the status of the container is "Up X seconds". When you restart a container, it starts with the same flags or commands that it was originally started with.

Now, stop and remove all of your containers and take a look at fixing the random naming issue. Stop the container you just started. Find the name of your running container and replace the name in the following command with the name of the container on your system.

```console
$ docker stop youthful_lamport
youthful_lamport
```

Now that you have stopped all of your containers, remove them. When you remove a container, it's no longer running, nor is it in the stopped status, but the process inside the container has been stopped and the metadata for the container has been removed.

To remove a container, run the `docker rm` command with the container name. You can pass multiple container names to the command using a single command. Again, replace the container names in the following command with the container names from your system.

```console
$ docker rm youthful_lamport friendly_montalcini tender_bose
youthful_lamport
sharp_noyce
magical_bhabha
```

Run the `docker ps --all` command again to see that Docker removed all containers.

Now, it's time to address the random naming issue. Standard practice is to name your containers for the simple reason that it's easier to identify what's running in the container and what application or service it's associated with.

To name a container, pass the `--name` flag to the `docker run` command.

```console
$ docker run -d -p 3001:8000 --name docker-rust-container docker-rust-image-dhi
1aa5d46418a68705c81782a58456a4ccdb56a309cb5e6bd399478d01eaa5cdda
$ docker ps
CONTAINER ID   IMAGE                   COMMAND                  CREATED         STATUS         PORTS                                         NAMES
219b2e3c7c38   docker-rust-image-dhi   "/server"                6 seconds ago   Up 5 seconds   0.0.0.0:3001->8000/tcp, [::]:3001->8000/tcp   docker-rust-container
```

Now you can identify your container based on the name.

## [Summary](#summary)

In this section, you took a look at running containers. You also took a look at managing containers by starting, stopping, and restarting them. And finally, you looked at naming your containers so they are more identifiable.

Related information:

* [docker run CLI reference](/reference/cli/docker/container/run/)

## [Next steps](#next-steps)

In the next section, you’ll learn how to run a database in a container and connect it to a Rust application.

[Develop your Rust application »](https://docs.docker.com/guides/rust/develop/)

----
url: https://docs.docker.com/desktop/features/desktop-cli/
----

# Use the Docker Desktop CLI

***

Table of contents

***

The Docker Desktop CLI lets you perform key operations such as starting, stopping, restarting, and updating Docker Desktop directly from the command line.

The Docker Desktop CLI provides:

* Simplified automation for local development: Execute Docker Desktop operations more efficiently in scripts and tests.
* An improved developer experience: Restart, quit, or reset Docker Desktop from the command line, reducing dependency on the Docker Desktop Dashboard and improving flexibility and efficiency.

## [Usage](#usage)

```console
docker desktop COMMAND [OPTIONS]
```

## [Commands](#commands)

| Command      | Description                                                                                                                 |
| ------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `start`      | Starts Docker Desktop                                                                                                       |
| `stop`       | Stops Docker Desktop                                                                                                        |
| `restart`    | Restarts Docker Desktop                                                                                                     |
| `status`     | Displays whether Docker Desktop is running or stopped.                                                                      |
| `engine ls`  | Lists available engines (Windows only)                                                                                      |
| `engine use` | Switch between Linux and Windows containers (Windows only)                                                                  |
| `update`     | Manage Docker Desktop updates.                                                                                              |
| `logs`       | Print log entries                                                                                                           |
| `disable`    | Disable a feature                                                                                                           |
| `enable`     | Enable a feature                                                                                                            |
| `version`    | Show the Docker Desktop CLI plugin version information                                                                      |
| `kubernetes` | List Kubernetes images used by Docker Desktop or restart the cluster. Available with Docker Desktop version 4.44 and later. |
| `diagnose`   | Diagnose Docker Desktop and upload the diagnostics. Available with Docker Desktop 4.60 and later.                           |

For more details on each command, see the [Docker Desktop CLI reference](/reference/cli/docker/desktop/).

----
url: https://docs.docker.com/guides/reactjs/configure-github-actions/
----

# Automate your builds with GitHub Actions

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize React.js application](https://docs.docker.com/guides/reactjs/containerize/).

You must also have:

* A [GitHub](https://github.com/signup) account.
* A verified [Docker Hub](https://hub.docker.com/signup) account.

***

## [Overview](#overview)

In this section, you'll set up a CI/CD pipeline using [GitHub Actions](https://docs.github.com/en/actions) to automatically:

* Build your React.js application inside a Docker container.
* Run tests in a consistent environment.
* Push the production-ready image to [Docker Hub](https://hub.docker.com).

***

## [Connect your GitHub repository to Docker Hub](#connect-your-github-repository-to-docker-hub)

To enable GitHub Actions to build and push Docker images, you’ll securely store your Docker Hub credentials in your new GitHub repository.

### [Step 1: Connect your GitHub repository to Docker Hub](#step-1-connect-your-github-repository-to-docker-hub)

1. Create a Personal Access Token (PAT) from [Docker Hub](https://hub.docker.com)

   1. Go to your **Docker Hub account → Account Settings → Security**.
   2. Generate a new Access Token with **Read/Write** permissions.
   3. Name it something like `docker-reactjs-sample`.
   4. Copy and save the token — you’ll need it in Step 4.

2. Create a repository in [Docker Hub](https://hub.docker.com/repositories/)

   1. Go to your **Docker Hub account → Create a repository**.
   2. For the Repository Name, use something descriptive — for example: `reactjs-sample`.
   3. Once created, copy and save the repository name — you’ll need it in Step 4.

3. Create a new [GitHub repository](https://github.com/new) for your React.js project

4. Add Docker Hub credentials as GitHub repository secrets

   In your newly created GitHub repository:

   1. Navigate to: **Settings → Secrets and variables → Actions → New repository secret**.

   2. Add the following secrets:

   | Name                     | Value                                            |
   | ------------------------ | ------------------------------------------------ |
   | `DOCKER_USERNAME`        | Your Docker Hub username                         |
   | `DOCKERHUB_TOKEN`        | Your Docker Hub access token (created in Step 1) |
   | `DOCKERHUB_PROJECT_NAME` | Your Docker Project Name (created in Step 2)     |

   These secrets let GitHub Actions to authenticate securely with Docker Hub during automated workflows.

5. Connect Your Local Project to GitHub

   Link your local project `docker-reactjs-sample` to the GitHub repository you just created by running the following command from your project root:

   ```console
      $ git remote set-url origin https://github.com/{your-username}/{your-repository-name}.git
   ```

   > Important
   >
   > Replace `{your-username}` and `{your-repository}` with your actual GitHub username and repository name.

   To confirm that your local project is correctly connected to the remote GitHub repository, run:

   ```console
   $ git remote -v
   ```

   You should see output similar to:

   ```console
   origin  https://github.com/{your-username}/{your-repository-name}.git (fetch)
   origin  https://github.com/{your-username}/{your-repository-name}.git (push)
   ```

   This confirms that your local repository is properly linked and ready to push your source code to GitHub.

6. Push Your Source Code to GitHub

   Follow these steps to commit and push your local project to your GitHub repository:

   1. Stage all files for commit.

      ```console
      $ git add -A
      ```

      This command stages all changes — including new, modified, and deleted files — preparing them for commit.

   2. Commit your changes.

      ```console
      $ git commit -m "Initial commit"
      ```

      This command creates a commit that snapshots the staged changes with a descriptive message.

   3. Push the code to the `main` branch.

      ```console
      $ git push -u origin main
      ```

      This command pushes your local commits to the `main` branch of the remote GitHub repository and sets the upstream branch.

Once completed, your code will be available on GitHub, and any GitHub Actions workflow you’ve configured will run automatically.

> Note
>
> Learn more about the Git commands used in this step:
>
> * [Git add](https://git-scm.com/docs/git-add) – Stage changes (new, modified, deleted) for commit
> * [Git commit](https://git-scm.com/docs/git-commit) – Save a snapshot of your staged changes
> * [Git push](https://git-scm.com/docs/git-push) – Upload local commits to your GitHub repository
> * [Git remote](https://git-scm.com/docs/git-remote) – View and manage remote repository URLs

***

### [Step 2: Set up the workflow](#step-2-set-up-the-workflow)

Now you'll create a GitHub Actions workflow that builds your Docker image, runs tests, and pushes the image to Docker Hub.

1. Go to your repository on GitHub and select the **Actions** tab in the top menu.

2. Select **Set up a workflow yourself** when prompted.

   This opens an inline editor to create a new workflow file. By default, it will be saved to: `.github/workflows/main.yml`

3. Add the following workflow configuration to the new file:

```yaml
name: CI/CD – React.js Application with Docker

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

jobs:
  build-test-push:
    name: Build, Test and Push Docker Image
    runs-on: ubuntu-latest

    steps:
      # 1. Checkout source code
      - name: Checkout source code
        uses: actions/checkout@v6
        with:
          fetch-depth: 0 # Fetches full history for better caching/context

      # 2. Set up Docker Buildx
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      # 3. Cache Docker layers
      - name: Cache Docker layers
        uses: actions/cache@v5
        with:
          path: /tmp/.buildx-cache
          key: ${{ runner.os }}-buildx-${{ github.sha }}
          restore-keys: ${{ runner.os }}-buildx-

      # 4. Cache npm dependencies
      - name: Cache npm dependencies
        uses: actions/cache@v5
        with:
          path: ~/.npm
          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys: ${{ runner.os }}-npm-

      # 5. Extract metadata
      - name: Extract metadata
        id: meta
        run: |
          echo "REPO_NAME=${GITHUB_REPOSITORY##*/}" >> "$GITHUB_OUTPUT"
          echo "SHORT_SHA=${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"

      # 6. Build dev Docker image
      - name: Build Docker image for tests
        uses: docker/build-push-action@v7
        with:
          context: .
          file: Dockerfile.dev
          tags: ${{ steps.meta.outputs.REPO_NAME }}-dev:latest
          load: true # Load to local Docker daemon for testing
          cache-from: type=local,src=/tmp/.buildx-cache
          cache-to: type=local,dest=/tmp/.buildx-cache,mode=max

      # 7. Run Vitest tests
      - name: Run Vitest tests and generate report
        run: |
          docker run --rm \
            --workdir /app \
            --entrypoint "" \
            ${{ steps.meta.outputs.REPO_NAME }}-dev:latest \
            sh -c "npm ci && npx vitest run --reporter=verbose"
        env:
          CI: true
          NODE_ENV: test
        timeout-minutes: 10

      # 8. Login to Docker Hub
      - name: Log in to Docker Hub
        uses: docker/login-action@v4
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      # 9. Build and push prod image
      - name: Build and push production image
        uses: docker/build-push-action@v7
        with:
          context: .
          file: Dockerfile
          push: true
          platforms: linux/amd64,linux/arm64
          tags: |
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:latest
            ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKERHUB_PROJECT_NAME }}:${{ steps.meta.outputs.SHORT_SHA }}
          cache-from: type=local,src=/tmp/.buildx-cache
```

This workflow performs the following tasks for your React.js application:

> Note
>
> For more information about `docker/build-push-action`, refer to the [GitHub Action README](https://github.com/docker/build-push-action/blob/master/README.md).

***

     * Repository name: `${your-repository-name}`

     * Tags include:

       * `latest` – represents the most recent successful build; ideal for quick testing or deployment.
       * `<short-sha>` – a unique identifier based on the commit hash, useful for version tracking, rollbacks, and traceability.

> Tip
>
> To maintain code quality and prevent accidental direct pushes, enable branch protection rules:
>
> * Navigate to your **GitHub repo → Settings → Branches**.
>
> * Under Branch protection rules, click **Add rule**.
>
> * Specify `main` as the branch name.
>
> * Enable options like:
>
>   * *Require a pull request before merging*.
>   * *Require status checks to pass before merging*.
>
> This ensures that only tested and reviewed code is merged into `main` branch.

***

## [Summary](#summary)

In this section, you set up a complete CI/CD pipeline for your containerized React.js application using GitHub Actions.

With this setup, your React.js application is now ready for automated testing and deployment across environments — increasing confidence, consistency, and team productivity.

***

***

## [Next steps](#next-steps)

Next, learn how you can locally test and debug your React.js workloads on Kubernetes before deploying. This helps you ensure your application behaves as expected in a production-like environment, reducing surprises during deployment.

[Test your React.js deployment »](https://docs.docker.com/guides/reactjs/deploy/)

----
url: https://docs.docker.com/reference/cli/docker/mcp/tools/call/
----

# docker mcp tools call

***

| Description | Call a tool             |
| ----------- | ----------------------- |
| Usage       | `docker mcp tools call` |

## [Description](#description)

Call a tool

----
url: https://docs.docker.com/guides/docker-scout/common-questions/
----

# Common challenges and questions

***

Table of contents

***

### [How is Docker Scout different from other security tools?](#how-is-docker-scout-different-from-other-security-tools)

Docker Scout takes a broader approach to container security compared to third-party security tools. Third-party security tools, if they offer remediation guidance at all, miss the mark on their limited scope of application security posture within the software supply chain, and often limited guidance when it comes to suggested fixes. Such tools have either limitations on runtime monitoring or no runtime protection at all. When they do offer runtime monitoring, it’s limited in its adherence to key policies. Third-party security tools offer a limited scope of policy evaluation for Docker-specific builds. By focusing on the entire software supply chain, providing actionable guidance, and offering comprehensive runtime protection with strong policy enforcement, Docker Scout goes beyond just identifying vulnerabilities in your containers. It helps you build secure applications from the ground up.

### [Can I use Docker Scout with external registries other than Docker Hub?](#can-i-use-docker-scout-with-external-registries-other-than-docker-hub)

You can use Scout with registries other than Docker Hub. Integrating Docker Scout with third-party container registries enables Docker Scout to run image analysis on those repositories so that you can get insights into the composition of those images even if they aren't hosted on Docker Hub.

The following container registry integrations are available:

* Artifactory
* Amazon Elastic Container Registry
* Azure Container Registry

Learn more about configuring Scout with your registries in [Integrating Docker Scout with third-party registries](/scout/integrations/#container-registries).

### [Does Docker Scout CLI come by default with Docker Desktop?](#does-docker-scout-cli-come-by-default-with-docker-desktop)

Yes, the Docker Scout CLI plugin comes pre-installed with Docker Desktop.

### [Is it possible to run `docker scout` commands on a Linux system without Docker Desktop?](#is-it-possible-to-run-docker-scout-commands-on-a-linux-system-without-docker-desktop)

If you run Docker Engine without Docker Desktop, Docker Scout doesn't come pre-installed, but you can [install it as a standalone binary](/scout/install/).

### [How is Docker Scout using an SBOM?](#how-is-docker-scout-using-an-sbom)

An SBOM, or software bill of materials, is a list of ingredients that make up software components. [Docker Scout uses SBOMs](/scout/concepts/sbom/) to determine the components that are used in a Docker image. When you analyze an image, Docker Scout will either use the SBOM that is attached to the image (as an attestation), or generate an SBOM on the fly by analyzing the contents of the image.

The SBOM is cross-referenced with the advisory database to determine if any of the components in the image have known vulnerabilities.

----
url: https://docs.docker.com/engine/install/ubuntu/
----

# Install Docker Engine on Ubuntu

***

Table of contents

***

To get started with Docker Engine on Ubuntu, make sure you [meet the prerequisites](#prerequisites), and then follow the [installation steps](#installation-methods).

## [Prerequisites](#prerequisites)

### [Firewall limitations](#firewall-limitations)

> Warning
>
> Before you install Docker, make sure you consider the following security implications and firewall incompatibilities.

* If you use ufw or firewalld to manage firewall settings, be aware that when you expose container ports using Docker, these ports bypass your firewall rules. For more information, refer to [Docker and ufw](https://docs.docker.com/engine/network/packet-filtering-firewalls/#docker-and-ufw).
* Docker is only compatible with `iptables-nft` and `iptables-legacy`. Firewall rules created with `nft` are not supported on a system with Docker installed. Make sure that any firewall rulesets you use are created with `iptables` or `ip6tables`, and that you add them to the `DOCKER-USER` chain, see [Packet filtering and firewalls](https://docs.docker.com/engine/network/packet-filtering-firewalls/).

### [OS requirements](#os-requirements)

To install Docker Engine, you need the 64-bit version of one of these Ubuntu versions:

* Ubuntu Resolute 26.04 (LTS)
* Ubuntu Questing 25.10
* Ubuntu Noble 24.04 (LTS)
* Ubuntu Jammy 22.04 (LTS)

Docker Engine for Ubuntu is compatible with x86\_64 (or amd64), armhf, arm64, s390x, and ppc64le (ppc64el) architectures.

> Note
>
> Installation on Ubuntu derivative distributions, such as Linux Mint, is not officially supported (though it may work).

### [Uninstall old versions](#uninstall-old-versions)

Before you can install Docker Engine, you need to uninstall any conflicting packages.

Your Linux distribution may provide unofficial Docker packages, which may conflict with the official packages provided by Docker. You must uninstall these packages before you install the official version of Docker Engine.

The unofficial packages to uninstall are:

* `docker.io`
* `docker-compose`
* `docker-compose-v2`
* `docker-doc`
* `podman-docker`

Moreover, Docker Engine depends on `containerd` and `runc`. Docker Engine bundles these dependencies as one bundle: `containerd.io`. If you have installed the `containerd` or `runc` previously, uninstall them to avoid conflicts with the versions bundled with Docker Engine.

Run the following command to uninstall all conflicting packages:

```console
$ sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc | cut -f1)
```

   ```bash
   # Add Docker's official GPG key:
   sudo apt update
   sudo apt install ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc

   # Add the repository to Apt sources:
   sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
   Types: deb
   URIs: https://download.docker.com/linux/ubuntu
   Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
   Components: stable
   Architectures: $(dpkg --print-architecture)
   Signed-By: /etc/apt/keyrings/docker.asc
   EOF

   sudo apt update
   ```

2. Install the Docker packages.

   To install the latest version, run:

   ```console
   $ sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   To install a specific version of Docker Engine, start by listing the available versions in the repository:

   ```console
   $ apt list --all-versions docker-ce

   docker-ce/noble 5:29.5.2-1~ubuntu.24.04~noble <arch>
   docker-ce/noble 5:29.5.1-1~ubuntu.24.04~noble <arch>
   ...
   ```

   Select the desired version and install:

   ```console
   $ VERSION_STRING=5:29.5.2-1~ubuntu.24.04~noble
   $ sudo apt install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   > Note
   >
   > After installation, verify that Docker is running:
   >
   > ```console
   > $ sudo systemctl status docker
   > ```
   >
   > If Docker is not running, start it manually:
   >
   > ```console
   > $ sudo systemctl start docker
   > ```

3. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

#### [Upgrade Docker Engine](#upgrade-docker-engine)

To upgrade Docker Engine, follow step 2 of the [installation instructions](#install-using-the-repository), choosing the new version you want to install.

### [Install from a package](#install-from-a-package)

If you can't use Docker's `apt` repository to install Docker Engine, you can download the `deb` file for your release and install it manually. You need to download a new file each time you want to upgrade Docker Engine.

1. Go to [`https://download.docker.com/linux/ubuntu/dists/`](https://download.docker.com/linux/ubuntu/dists/).

2. Select your Ubuntu version in the list.

   ```console
   $ sudo dpkg -i ./containerd.io_<version>_<arch>.deb \
     ./docker-ce_<version>_<arch>.deb \
     ./docker-ce-cli_<version>_<arch>.deb \
     ./docker-buildx-plugin_<version>_<arch>.deb \
     ./docker-compose-plugin_<version>_<arch>.deb
   ```

   > Note
   >
   > After installation, verify that Docker is running:
   >
   > ```console
   > $ sudo systemctl status docker
   > ```
   >
   > If Docker is not running, start it manually:
   >
   > ```console
   > $ sudo systemctl start docker
   > ```

6. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

> Tip
>
> Preview script steps before running. You can run the script with the `--dry-run` option to learn what steps the script will run when invoked:
>
> ```console
> $ curl -fsSL https://get.docker.com -o get-docker.sh
> $ sudo sh ./get-docker.sh --dry-run
> ```

This example downloads the script from <https://get.docker.com/> and runs it to install the latest stable release of Docker on Linux:

```console
$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh get-docker.sh
Executing docker install script, commit: 7cae5f8b0decc17d6571f9f52eb840fbc13b2737
<...>
```

You have now successfully installed and started Docker Engine. The `docker` service starts automatically on Debian based distributions. On `RPM` based distributions, such as CentOS, Fedora or RHEL, you need to start it manually using the appropriate `systemctl` or `service` command. As the message indicates, non-root users can't run Docker commands by default.

> **Use Docker as a non-privileged user, or install in rootless mode?**
>
> The installation script requires `root` or `sudo` privileges to install and use Docker. If you want to grant non-root users access to Docker, refer to the [post-installation steps for Linux](/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). You can also install Docker without `root` privileges, or configured to run in rootless mode. For instructions on running Docker in rootless mode, refer to [run the Docker daemon as a non-root user (rootless mode)](/engine/security/rootless/).

#### [Install pre-releases](#install-pre-releases)

Docker also provides a convenience script at <https://test.docker.com/> to install pre-releases of Docker on Linux. This script is equal to the script at `get.docker.com`, but configures your package manager to use the test channel of the Docker package repository. The test channel includes both stable and pre-releases (beta versions, release-candidates) of Docker. Use this script to get early access to new releases, and to evaluate them in a testing environment before they're released as stable.

To install the latest version of Docker on Linux from the test channel, run:

```console
$ curl -fsSL https://test.docker.com -o test-docker.sh
$ sudo sh test-docker.sh
```

#### [Upgrade Docker after using the convenience script](#upgrade-docker-after-using-the-convenience-script)

If you installed Docker using the convenience script, you should upgrade Docker using your package manager directly. There's no advantage to re-running the convenience script. Re-running it can cause issues if it attempts to re-install repositories which already exist on the host machine.

## [Uninstall Docker Engine](#uninstall-docker-engine)

1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages:

   ```console
   $ sudo apt purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
   ```

2. Images, containers, volumes, or custom configuration files on your host aren't automatically removed. To delete all images, containers, and volumes:

   ```console
   $ sudo rm -rf /var/lib/docker
   $ sudo rm -rf /var/lib/containerd
   ```

3. Remove source list and keyrings

   ```console
   $ sudo rm /etc/apt/sources.list.d/docker.sources
   $ sudo rm /etc/apt/keyrings/docker.asc
   ```

----
url: https://docs.docker.com/dhi/migration/examples/node/
----

# Node.js

***

***

This example shows how to migrate a Node.js application to Docker Hardened Images.

The following examples show Dockerfiles before and after migration to Docker Hardened Images. Each example includes five variations:

* Before (Ubuntu): A sample Dockerfile using Ubuntu-based images, before migrating to DHI
* Before (Wolfi): A sample Dockerfile using Wolfi distribution images, before migrating to DHI
* Before (DOI): A sample Dockerfile using Docker Official Images, before migrating to DHI
* After (multi-stage): A sample Dockerfile after migrating to DHI with multi-stage builds (recommended for minimal, secure images)
* After (single-stage): A sample Dockerfile after migrating to DHI with single-stage builds (simpler but results in a larger image with a broader attack surface)

> Note
>
> Multi-stage builds are recommended for most use cases. Single-stage builds are supported for simplicity, but come with tradeoffs in size and security.
>
> You must authenticate to `dhi.io` before you can pull Docker Hardened Images. Use your Docker ID credentials (the same username and password you use for Docker Hub). If you don't have a Docker account, [create one](https://docs.docker.com/accounts/create-account/) for free.
>
> Run `docker login dhi.io` to authenticate.

```dockerfile
#syntax=docker/dockerfile:1

FROM ubuntu/node:18-24.04_edge
WORKDIR /usr/src/app

COPY package*.json ./

RUN npm install

COPY . .

CMD ["node", "index.js"]
```

```dockerfile
#syntax=docker/dockerfile:1

FROM cgr.dev/chainguard/node:latest-dev
WORKDIR /usr/src/app

COPY package*.json ./

# Install any additional packages if needed using apk
# RUN apk add --no-cache python3 make g++

RUN npm install

COPY . .

CMD ["node", "index.js"]
```

```dockerfile
#syntax=docker/dockerfile:1

FROM node:latest
WORKDIR /usr/src/app

COPY package*.json ./

# Install any additional packages if needed using apt
# RUN apt-get update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*

RUN npm install

COPY . .

CMD ["node", "index.js"]
```

```dockerfile
#syntax=docker/dockerfile:1

# === Build stage: Install dependencies and build application ===
FROM dhi.io/node:23-alpine3.21-dev AS builder
WORKDIR /usr/src/app

COPY package*.json ./

# Install any additional packages if needed using apk
# RUN apk add --no-cache python3 make g++

RUN npm install

COPY . .

# === Final stage: Create minimal runtime image ===
FROM dhi.io/node:23-alpine3.21
ENV PATH=/app/node_modules/.bin:$PATH

COPY --from=builder --chown=node:node /usr/src/app /app

WORKDIR /app

CMD ["index.js"]
```

```dockerfile
#syntax=docker/dockerfile:1

FROM dhi.io/node:23-alpine3.21-dev
WORKDIR /usr/src/app

COPY package*.json ./

# Install any additional packages if needed using apk
# RUN apk add --no-cache python3 make g++

RUN npm install

COPY . .

CMD ["node", "index.js"]
```

----
url: https://docs.docker.com/reference/samples/
----

# Samples overview

***

Table of contents

***

Learn how to containerize different types of services by walking through Official Docker samples.

## [Databases](#databases)

[MariaDB](https://docs.docker.com/reference/samples/mariadb/) | [MongoDB](https://docs.docker.com/reference/samples/mongodb/) | [MS-SQL](https://docs.docker.com/reference/samples/ms-sql/) | [MySQL](https://docs.docker.com/reference/samples/mysql/) | [PostgreSQL](https://docs.docker.com/reference/samples/postgres/) | [Redis](https://docs.docker.com/reference/samples/redis/)

## [Frameworks](#frameworks)

[.NET](https://docs.docker.com/reference/samples/dotnet/) | [Angular](https://docs.docker.com/reference/samples/angular/) | [Django](https://docs.docker.com/reference/samples/django/) | [Express](https://docs.docker.com/reference/samples/express/) |[FastAPI](https://docs.docker.com/reference/samples/fastapi/) | [Flask](https://docs.docker.com/reference/samples/flask/) | [Node.js](https://docs.docker.com/reference/samples/nodejs/) | [React](https://docs.docker.com/reference/samples/react/) | [Rails](https://docs.docker.com/reference/samples/rails/) | [Spark](https://docs.docker.com/reference/samples/spark/) | [Spring Boot](https://docs.docker.com/reference/samples/spring/) | [Vue.js](https://docs.docker.com/reference/samples/vuejs/)

## [Languages](#languages)

[Go](https://docs.docker.com/reference/samples/go/) | [Java](https://docs.docker.com/reference/samples/java/) | [JavaScript](https://docs.docker.com/reference/samples/javascript/) | [PHP](https://docs.docker.com/reference/samples/php/) | [Python](https://docs.docker.com/reference/samples/python/) | [Ruby](https://docs.docker.com/reference/samples/ruby/) | [Rust](https://docs.docker.com/reference/samples/rust/) | [TypeScript](https://docs.docker.com/reference/samples/typescript/)

## [Platforms](#platforms)

[Gitea](https://docs.docker.com/reference/samples/gitea/) | [Nextcloud](https://docs.docker.com/reference/samples/nextcloud/) | [Portainer](https://docs.docker.com/reference/samples/portainer/) | [Prometheus](https://docs.docker.com/reference/samples/prometheus/) | [WordPress](https://docs.docker.com/reference/samples/wordpress/)

## [Other samples](#other-samples)

[Agentic AI](https://docs.docker.com/reference/samples/agentic-ai/) | [AI/ML](https://docs.docker.com/reference/samples/ai-ml/) | [Cloudflared](https://docs.docker.com/reference/samples/cloudflared/) | [Elasticsearch / Logstash / Kibana](https://docs.docker.com/reference/samples/elasticsearch/) | [Minecraft](https://docs.docker.com/reference/samples/minecraft/) | [NGINX](https://docs.docker.com/reference/samples/nginx/) | [Pi-hole](https://docs.docker.com/reference/samples/pi-hole/) | [Plex](https://docs.docker.com/reference/samples/plex/) | [Traefik](https://docs.docker.com/reference/samples/traefik/) | [WireGuard](https://docs.docker.com/reference/samples/wireguard/)

----
url: https://docs.docker.com/admin/insights/
----

# Insights

***

Table of contents

***

Subscription: Business

For: Administrators

Insights helps administrators visualize and understand how Docker is used within their organizations. With Insights, administrators can ensure their teams are fully equipped to utilize Docker to its fullest potential, leading to improved productivity and efficiency across the organization.

Key benefits include:

* Uniform working environment: Establish and maintain standardized configurations across teams.
* Best practices: Promote and enforce usage guidelines to ensure optimal performance.
* Increased visibility: Monitor and drive adoption of organizational configurations and policies.
* Optimized license use: Ensure that developers have access to advanced features provided by a Docker subscription.

## [Prerequisites](#prerequisites)

To use Insights, you must meet the following requirements:

* [Docker Business subscription](https://www.docker.com/pricing?ref=Docs\&refAction=DocsAdminInsights)
* Administrators must [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) for users
* Your Account Executive must turn on Insights for your organization

## [View Insights for organization users](#view-insights-for-organization-users)

To access Insights, contact your Account Executive to turn on the feature. Once enabled, access Insights using the following steps:

1. Sign in to [Docker Home](https://app.docker.com/) and choose your organization.
2. Select **Insights**, then select a time period for the data you want to view.

> Note
>
> Insights data is not real-time and is updated daily. At the top-right of the Insights page, view the **Last updated** date to understand when the data was last updated.

### [Docker Desktop users](#docker-desktop-users)

Track active Docker Desktop users in your domain, differentiated by license status. This chart helps you understand the engagement levels within your organization, providing insights into how many users are actively using Docker Desktop. Note that users who opt out of analytics aren't included in the active counts.

The chart contains the following data:

| Data                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Active user                  | The number of users who have actively used Docker Desktop and either signed in with a Docker account that has a license in your organization or signed in to a Docker account with an email address from a domain associated with your organization. Users who don’t sign in to an account associated with your organization are not represented in the data. To ensure users sign in with an account associated with your organization, you can [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/). |
| Total organization members   | The number of users who have used Docker Desktop, regardless of their Insights activity.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Users opted out of analytics | The number of users who are members of your organization that have opted out of sending analytics. When users opt out of sending analytics, you won't see any of their data in Insights. To ensure that the data includes all users, you can use [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) to set `analyticsEnabled` for all your users.                                                                                                                           |
| Active users (graph)         | The view over time for total active users.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

### [Builds](#builds)

Monitor development efficiency and the time your team invests in builds with this chart. It provides a clear view of the build activity, helping you identify patterns, optimize build times, and enhance overall development productivity.

The chart contains the following data:

| Data                   | Description                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Average build per user | The average number of builds per active user. A build includes any time a user runs one of the following commands:- `docker build`
- `docker buildx b`
- `docker buildx bake`
- `docker buildx build`
- `docker buildx f`
- `docker builder b`
- `docker builder bake`
- `docker builder build`
- `docker builder f`
- `docker compose build`
- `docker compose up --build`
- `docker image build` |
| Average build time     | The average build time per build.                                                                                                                                                                                                                                                                                                                                                                  |
| Build success rate     | The percentage of builds that were successful out of the total number of builds. A successful build includes any build that exits normally.                                                                                                                                                                                                                                                        |
| Total builds (graph)   | The total number of builds separated into successful builds and failed builds. A successful build includes any build that exits normally. A failed build includes any build that exits abnormally.                                                                                                                                                                                                 |

### [Containers](#containers)

View the total and average number of containers run by users with this chart. It lets you gauge container usage across your organization, helping you understand usage trends and manage resources effectively.

The chart contains the following data:

| Data                                   | Description                                                                                                                                                                |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Total containers run                   | The total number of containers run by active users. Containers run include those run using the Docker Desktop graphical user interface, `docker run`, or `docker compose`. |
| Average number of containers run       | The average number of containers run per active user.                                                                                                                      |
| Containers run by active users (graph) | The number of containers run over time by active users.                                                                                                                    |

### [Docker Desktop usage](#docker-desktop-usage)

Explore Docker Desktop usage patterns with this chart to optimize your team's workflows and ensure compatibility. It provides valuable insights into how Docker Desktop is being utilized, enabling you to streamline processes and improve efficiency.

The chart contains the following data:

| Data                              | Description                                                                                                                                                                                                                                                               |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Most used version                 | The most used version of Docker Desktop by users in your organization.                                                                                                                                                                                                    |
| Most used OS                      | The most used operating system by users.                                                                                                                                                                                                                                  |
| Versions by active users (graph)  | The number of active users using each version of Docker Desktop. To learn more about each version and release dates, see the [Docker Desktop release notes](https://docs.docker.com/desktop/release-notes/).                                                              |
| Interface by active users (graph) | The number of active users grouped into the type of interface they used to interact with Docker Desktop. A CLI user is any active user who has run a `docker` command. A GUI user is any active user who has interacted with the Docker Desktop graphical user interface. |

### [Docker Hub images](#docker-hub-images)

Analyze image distribution activity with this chart and view the most utilized Docker Hub images within your domain. This information helps you manage image usage, ensuring that the most critical resources are readily available and efficiently used.

> Note
>
> Data for images is only for Docker Hub. Data for third-party registries and mirrors aren't included.

The chart contains the following data:

| Data                 | Description                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
| Total pulled images  | The total number of images pulled by users from Docker Hub.                                                     |
| Total pushed images  | The total number of images pushed by users to Docker Hub.                                                       |
| Top 10 pulled images | A list of the top 10 images pulled by users from Docker Hub and the number of times each image has been pulled. |

### [Extensions](#extensions)

Monitor extension installation activity with this chart. It provides visibility into the Docker Desktop extensions your teams are using, letting you track adoption and identify popular tools that enhance productivity.

The chart contains the following data:

| Data                                           | Description                                                                                                                                      |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Percentage of org with extensions installed    | The percentage of users in your organization with at least one Docker Desktop extension installed.                                               |
| Top 5 extensions installed in the organization | A list of the top 5 Docker Desktop extensions installed by users in your organization and the number of users who have installed each extension. |

## [Export Docker Desktop user data](#export-docker-desktop-user-data)

You can export Docker Desktop user data as a CSV file:

1. Open [Docker Home](https://app.docker.com) and select your organization from the top-left account drop-down.
2. Select **Admin Console** in the left-hand navigation menu.
3. Select **Desktop insights**.
4. Choose a timeframe for your insights data: **1 Week**, **1 Month**, or **3 Months**.
5. Select **Export** and choose **Docker Desktop users** from the drop-down.

Your export will automatically download. Open the file to view the export data.

### [Understanding export data](#understanding-export-data)

A Docker Desktop user export file contains the following data points:

* Name: User's name
* Username: User's Docker ID
* Email: User's email address associated with their Docker ID
* Type: User type
* Role: User [role](https://docs.docker.com/enterprise/security/roles-and-permissions/)
* Teams: Team(s) within your organization the user is a member of
* Date Joined: The date the user joined your organization
* Last Logged-In Date: The last date the user logged into Docker using their web browser (this includes Docker Hub and Docker Home)
* Docker Desktop Version: The version of Docker Desktop the user has installed
* Last Seen Date: The last date the user used the Docker Desktop application
* Opted Out Analytics: Whether the user has opted out of the [Send usage statistics](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/settings-reference/#send-usage-statistics) setting in Docker Desktop

## [Troubleshoot Insights](#troubleshoot-insights)

If you’re experiencing issues with data in Insights, consider the following solutions to resolve common problems:

* Update users to the latest version of Docker Desktop.

  Data is not shown for users using versions 4.16 or lower of Docker Desktop. In addition, older versions may not provide all data. Ensure all users have installed the latest version of Docker Desktop.

* Turn on **Send usage statistics** in Docker Desktop for all your users.

  If users have opted out of sending usage statistics for Docker Desktop, then their usage data will not be a part of Insights. To manage the setting at scale for all your users, you can use [Settings Management](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/) and turn on the `analyticsEnabled` setting.

* Ensure users use Docker Desktop and aren't using the standalone version of Docker Engine.

  Only Docker Desktop can provide data for Insights. If a user installs Docker Engine outside of Docker Desktop, Docker Engine won't provide data for that user.

* Make sure users sign in to an account associated with your organization.

  Users who don’t sign in to an account associated with your organization are not represented in the data. To ensure users sign in with an account associated with your organization, you can [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/).

----
url: https://docs.docker.com/engine/storage/containerd/
----

# containerd image store with Docker Engine

***

Table of contents

***

The containerd image store is the default storage backend for Docker Engine 29.0 and later on fresh installations. If you upgraded from an earlier version, your daemon continues using the legacy graph drivers (overlay2) until you enable the containerd image store.

containerd, the industry-standard container runtime, uses snapshotters instead of classic storage drivers for storing image and container data.

> Note
>
> The containerd image store is not available when using user namespace remapping (`userns-remap`). See [moby#47377](https://github.com/moby/moby/issues/47377) for details.

## [Why use the containerd image store](#why-use-the-containerd-image-store)

The containerd image store uses snapshotters to manage how image layers are stored and accessed on the filesystem. This differs from the classic graph drivers like overlay2.

The containerd image store enables:

* Building and storing multi-platform images locally. With classic storage drivers, you need external builders for multi-platform images.
* Working with images that include attestations (provenance, SBOM). These use image indices that the classic store doesn't support.
* Running Wasm containers. The containerd image store supports WebAssembly workloads.
* Using advanced snapshotters. containerd supports pluggable snapshotters that provide features like lazy-pulling of images (stargz) or peer-to-peer image distribution (nydus, dragonfly).

For most users, switching to the containerd image store is transparent. The storage backend changes, but your workflows remain the same.

## [Disk space usage](#disk-space-usage)

The containerd image store uses more disk space than the legacy storage drivers for the same images. This is because containerd stores images in both compressed and uncompressed formats, while the legacy drivers stored only the uncompressed layers.

When you pull an image, containerd keeps the compressed layers (as received from the registry) and also extracts them to disk. This dual storage means each layer occupies more space. The compressed format enables faster pulls and pushes, but requires additional disk capacity.

> Important
>
> containerd uses a separate storage path from the Docker data directory. If you previously configured a custom data directory for Docker (for example, to use a different partition), containerd's storage is not automatically moved to that location. You need to configure containerd's data directory separately to avoid filling your root partition.
>
> To configure containerd's data directory, see [Configure the data directory location](https://docs.docker.com/engine/daemon/#configure-the-data-directory-location).

If disk space is constrained, consider the following:

* Regularly prune unused images with `docker image prune`
* Use `docker system df` to monitor disk usage
* [Configure the data directory](https://docs.docker.com/engine/daemon/#configure-the-data-directory-location) to use a partition with adequate space

## [Enable containerd image store on Docker Engine](#enable-containerd-image-store-on-docker-engine)

If you're upgrading from an earlier Docker Engine version, you need to manually enable the containerd image store.

> Important
>
> Switching storage backends temporarily hides images and containers created with the other backend. Your data remains on disk. To access the old images again, switch back to your previous storage configuration.

Add the following configuration to your `/etc/docker/daemon.json` file:

```json
{
  "features": {
    "containerd-snapshotter": true
  }
}
```

Save the file and restart the daemon:

```console
$ sudo systemctl restart docker
```

After restarting the daemon, verify you're using the containerd image store:

```console
$ docker info -f '{{ .DriverStatus }}'
[[driver-type io.containerd.snapshotter.v1]]
```

Docker Engine uses the `overlayfs` containerd snapshotter by default.

> Note
>
> When you enable the containerd image store, existing images and containers from the overlay2 driver remain on disk but become hidden. They reappear if you switch back to overlay2. To use your existing images with the containerd image store, push them to a registry first, or use `docker save` to export them.

## [Experimental automatic migration](#experimental-automatic-migration)

Docker Engine includes an experimental feature that can automatically switch to the containerd image store under certain conditions. **This feature is experimental**. It's provided for those who want to test it, but [starting fresh](#enable-containerd-image-store-on-docker-engine) is the recommended approach.

> Caution
>
> The automatic migration feature is experimental and may not work reliably in all scenarios. Create backups before attempting to use it.

To enable automatic migration, add the `containerd-migration` feature to your `/etc/docker/daemon.json`:

```json
{
  "features": {
    "containerd-migration": true
  }
}
```

You can also set the `DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD` environment variable to make the daemon switch automatically if you have no containers and your image count is at or below the threshold. For systemd:

```console
$ sudo systemctl edit docker.service
```

Add:

```ini
[Service]
Environment="DOCKER_MIGRATE_SNAPSHOTTER_THRESHOLD=5"
```

If you have no running or stopped containers and 5 or fewer images, the daemon switches to the containerd image store on restart. Your overlay2 data remains on disk but becomes hidden.

## [Additional resources](#additional-resources)

To learn more about the containerd image store and its capabilities in Docker Desktop, see [containerd image store on Docker Desktop](https://docs.docker.com/desktop/features/containerd/).

----
url: https://docs.docker.com/compose/release-notes/
----

# Release notes

***

***

----
url: https://docs.docker.com/ai/sandboxes/customize/
----

# Customizing sandboxes

***

Table of contents

***

Availability: Early Access

Docker Sandboxes offers two ways to customize a sandbox beyond the built-in defaults:

* [Templates](https://docs.docker.com/ai/sandboxes/customize/templates/) — reusable sandbox images with tools, packages, and configuration baked in. Extend a base image with a Dockerfile, or save a running sandbox as a template.
* [Kits](https://docs.docker.com/ai/sandboxes/customize/kits/) — declarative YAML artifacts that extend an agent with tools, credentials, network rules, and files at runtime, or define a new agent from scratch.

Kits are experimental. The kit file format, CLI commands, and experience for creating, loading, and managing kits are subject to change as the feature evolves. Share feedback and bug reports in the [docker/sbx-releases](https://github.com/docker/sbx-releases) repository.

## [Templates and kits, side by side](#templates-and-kits-side-by-side)

A template is a Docker image that the sandbox runs. It's built ahead of time with a Dockerfile (or saved from a running sandbox), pushed to a registry, and pulled when a sandbox is created. Use templates for things that belong in an image: system packages, language toolchains, large dependencies — anything you'd rather not reinstall on every sandbox start.

A kit is a YAML artifact applied at sandbox creation. The kit can run install commands, drop files into the sandbox, declare network and credential rules, and (for agent kits) define which template image the agent runs in. Use kits for things that vary per agent or per team: shared linter config, project-specific install steps, credential injection for a service the agent talks to.

Templates and kits work together. An agent kit's `agent.image` field points at a template: the template provides the base environment, the kit layers config, secrets, and runtime behavior on top. A team can ship one heavy template and several thin kits without rebuilding the image each time something changes.

## [When to use which](#when-to-use-which)

| Goal                                                      | Option                                                                                                     |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Pre-install tools and packages into a reusable base image | [Template](https://docs.docker.com/ai/sandboxes/customize/templates/)                                      |
| Capture a configured running sandbox for reuse            | [Saved template](https://docs.docker.com/ai/sandboxes/customize/templates/#saving-a-sandbox-as-a-template) |
| Add a tool, credential, or config to agent runs via YAML  | [Kit (mixin)](https://docs.docker.com/ai/sandboxes/customize/kits/)                                        |
| Define a new agent from scratch                           | [Kit (agent)](https://docs.docker.com/ai/sandboxes/customize/kits/#defining-an-agent)                      |

Templates and kits can be used together. A template bakes heavy tools into the image for fast sandbox startup; a kit layered on top adds per-run credentials, config, or extra capabilities.

## [Tutorials](#tutorials)

* [Build your own agent kit](https://docs.docker.com/ai/sandboxes/customize/build-an-agent/) — step-by-step walkthrough for packaging [Amp](https://ampcode.com/) as an agent kit.

----
url: https://docs.docker.com/extensions/settings-feedback/
----

# Settings and feedback for Docker Extensions

***

Table of contents

***

## [Settings](#settings)

### [Turn on or turn off extensions](#turn-on-or-turn-off-extensions)

Docker Extensions is switched off by default. To change your settings:

1. Navigate to **Settings**.
2. Select the **Extensions** tab.
3. Next to **Enable Docker Extensions**, select or clear the checkbox to set your desired state.
4. In the bottom-right corner, select **Apply**.

> Note
>
> If you are an [organization owner](https://docs.docker.com/admin/organization/manage/manage-a-team/#what-is-an-organization-owner), you can turn off extensions for your users. Open the `settings-store.json` file, and set `"extensionsEnabled"` to `false`. The `settings-store.json` file is located at:
>
> * `~/Library/Group Containers/group.com.docker/settings-store.json` on Mac
> * `C:\Users\[USERNAME]\AppData\Roaming\Docker\settings-store.json` on Windows
>
> This can also be done with [Hardened Docker Desktop](https://docs.docker.com/enterprise/security/hardened-desktop/)

### [Turn on or turn off extensions not available in the Marketplace](#turn-on-or-turn-off-extensions-not-available-in-the-marketplace)

You can install extensions through the Marketplace or through the Extensions SDK tools. You can choose to only allow published extensions. These are extensions that have been reviewed and published in the Extensions Marketplace.

1. Navigate to **Settings**.
2. Select the **Extensions** tab.
3. Next to **Allow only extensions distributed through the Docker Marketplace**, select or clear the checkbox to set your desired state.
4. In the bottom-right corner, select **Apply**.

### [See containers created by extensions](#see-containers-created-by-extensions)

By default, containers created by extensions are hidden from the list of containers in the Docker Desktop Dashboard and the Docker CLI. To make them visible update your settings:

1. Navigate to **Settings**.
2. Select the **Extensions** tab.
3. Next to **Show Docker Extensions system containers**, select or clear the checkbox to set your desired state.
4. In the bottom-right corner, select **Apply**.

> Note
>
> Enabling extensions doesn't use computer resources (CPU / Memory) by itself.
>
> Specific extensions might use computer resources, depending on the features and implementation of each extension, but there is no reserved resources or usage cost associated with enabling extensions.

## [Submit feedback](#submit-feedback)

Feedback can be given to an extension author through a dedicated Slack channel or GitHub. To submit feedback about a particular extension:

1. Navigate to the Docker Desktop Dashboard and select the **Manage** tab. This displays a list of extensions you've installed.

2. Select the extension you want to provide feedback on.

3. Scroll down to the bottom of the extension's description and, depending on the extension, select:

   * Support
   * Slack
   * Issues. You'll be sent to a page outside of Docker Desktop to submit your feedback.

If an extension doesn't provide a way for you to give feedback, contact us and we'll pass on the feedback for you. To provide feedback, select the **Give feedback** to the right of **Extensions Marketplace**.

----
url: https://docs.docker.com/reference/cli/docker/dhi/customization/build/get/
----

# docker dhi customization build get

***

| Description | Get details of a build                                              |
| ----------- | ------------------------------------------------------------------- |
| Usage       | `docker dhi customization build get <repository> <name> <build-id>` |

## [Description](#description)

Get detailed information about a Docker Hardened Images customization build

## [Options](#options)

| Option   | Default | Description           |
| -------- | ------- | --------------------- |
| `--json` |         | Output in JSON format |

----
url: https://docs.docker.com/reference/samples/redis/
----

# Redis samples

| Name                                                                                                         | Description                                                                    |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| [NGINX / Node.js / Redis](https://github.com/docker/awesome-compose/tree/master/nginx-nodejs-redis)          | A sample Node.js application with Nginx proxy and a Redis database.            |
| [Python / Flask / Redis](https://github.com/docker/awesome-compose/tree/master/flask-redis)                  | A sample Python/Flask and a Redis database.                                    |
| [Nextcloud / Redis / MariaDB](https://github.com/docker/awesome-compose/tree/master/nextcloud-redis-mariadb) | A sample Nextcloud setup.                                                      |
| [example-voting-app](https://github.com/dockersamples/example-voting-app)                                    | A sample Docker Compose app.                                                   |
| [link-shortener-typescript](https://github.com/dockersamples/link-shortener-typescript)                      | A Simple URL Shortener built using TypeScript and Nest.js powered with Docker. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/reference/cli/docker/scout/recommendations/
----

# docker scout recommendations

***

| Description | Display available base image updates and remediation recommendations |
| ----------- | -------------------------------------------------------------------- |
| Usage       | `docker scout recommendations [IMAGE\|DIRECTORY\|ARCHIVE]`           |

## [Description](#description)

The `docker scout recommendations` command display recommendations for base images updates. It analyzes the image and display recommendations to refresh or update the base image. For each recommendation it shows a list of benefits, such as fewer vulnerabilities or smaller image size.

| Option           | Default | Description                                                                                          |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `--only-refresh` |         | Only display base image refresh recommendations                                                      |
| `--only-update`  |         | Only display base image update recommendations                                                       |
| `--org`          |         | Namespace of the Docker organization                                                                 |
| `-o, --output`   |         | Write the report to a file                                                                           |
| `--platform`     |         | Platform of image to analyze                                                                         |
| `--ref`          |         | Reference to use if the provided tarball contains multiple references. Can only be used with archive |
| `--tag`          |         | Specify tag                                                                                          |

## [Examples](#examples)

### [Display base image update recommendations](#display-base-image-update-recommendations)

```console
$ docker scout recommendations golang:1.19.4
```

### [Display base image refresh only recommendations](#display-base-image-refresh-only-recommendations)

```console
$ docker scout recommendations --only-refresh golang:1.19.4
```

### [Display base image update only recommendations](#display-base-image-update-only-recommendations)

```console
$ docker scout recommendations --only-update golang:1.19.4
```

----
url: https://docs.docker.com/reference/cli/sbx/kit/
----

# sbx kit

| Description | Manage kit artifacts |
| ----------- | -------------------- |
| Usage       | `sbx kit COMMAND`    |

## [Description](#description)

Manage kit artifacts.

Kits are declarative YAML artifacts that extend sandbox agents with additional credentials, network policies, environment variables, startup commands, and files.

## [Commands](#commands)

| Command                                                                       | Description                              |
| ----------------------------------------------------------------------------- | ---------------------------------------- |
| [`sbx kit add`](https://docs.docker.com/reference/cli/sbx/kit/add/)           | Add a kit to a running sandbox           |
| [`sbx kit inspect`](https://docs.docker.com/reference/cli/sbx/kit/inspect/)   | Display details about a kit artifact     |
| [`sbx kit pack`](https://docs.docker.com/reference/cli/sbx/kit/pack/)         | Package a directory as a kit artifact    |
| [`sbx kit pull`](https://docs.docker.com/reference/cli/sbx/kit/pull/)         | Pull a kit artifact from an OCI registry |
| [`sbx kit push`](https://docs.docker.com/reference/cli/sbx/kit/push/)         | Push a kit artifact to an OCI registry   |
| [`sbx kit validate`](https://docs.docker.com/reference/cli/sbx/kit/validate/) | Validate a kit artifact                  |

## [Global options](#global-options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/ai/sandboxes/customize/templates/
----

# Templates

***

Table of contents

***

Availability: Early Access

Every sandbox is customizable — agents install packages, pull images, and configure tools as they work, and those changes persist for the sandbox's lifetime. Templates capture a configured environment into a reusable image so you don't have to set it up again every time.

## [Custom templates](#custom-templates)

Custom templates are reusable sandbox images that extend one of the built-in agent environments with additional tools and configuration baked in. Instead of asking the agent to install packages every time, build a template once and reuse it across sandboxes and team members.

Templates make sense when multiple people need the same environment, when setup involves steps that are tedious to repeat, or when you need pinned versions of specific tools. For one-off work, the default image is fine — ask the agent to install what's needed.

> Note
>
> Custom templates customize an existing agent's environment — they don't create new agent runtimes. The agent that launches inside the sandbox is determined by the base image variant you extend and the agent you specify in the `sbx run` command, not by binaries installed in the template. To define a new agent from scratch, see [Kits](https://docs.docker.com/ai/sandboxes/customize/kits/#defining-an-agent).

### [Base images](#base-images)

All sandbox templates are published as `docker/sandbox-templates:<variant>`. They are based on Ubuntu and run as a non-root `agent` user with sudo access. Most variants include Git, Docker CLI, and common development tools like Node.js, Python, Go, and Java.

| Variant               | Agent                                                                |
| --------------------- | -------------------------------------------------------------------- |
| `claude-code`         | [Claude Code](https://claude.ai/download)                            |
| `claude-code-minimal` | Claude Code with a minimal toolset (no Node.js, Python, Go, or Java) |
| `codex`               | [OpenAI Codex](https://github.com/openai/codex)                      |
| `copilot`             | [GitHub Copilot](https://github.com/github/copilot-cli)              |
| `cursor-agent`        | [Cursor](https://cursor.com/cli)                                     |
| `docker-agent`        | [Docker Agent](https://github.com/docker/docker-agent)               |
| `droid`               | [Droid](https://www.factory.ai)                                      |
| `gemini`              | [Gemini CLI](https://github.com/google-gemini/gemini-cli)            |
| `kiro`                | [Kiro](https://kiro.dev)                                             |
| `opencode`            | [OpenCode](https://opencode.ai)                                      |
| `shell`               | No agent pre-installed. Use for manual agent setup.                  |

Each variant also has a `-docker` version (for example, `claude-code-docker`) that includes a full Docker Engine running inside the sandbox — no local Docker daemon required. When you pick a built-in agent without specifying a custom template, `sbx run` and `sbx create` use the `-docker` template variants by default.

The agent containers created from the `-docker` templates run in privileged mode inside the microVM (not on your host), with a dedicated block volume at `/var/lib/docker`, and `dockerd` starts automatically inside the sandbox. The block volume defaults to 50 GB and uses a sparse file, so it only consumes disk space as Docker writes to it.

To override the volume size, set the `DOCKER_SANDBOXES_DOCKER_SIZE` environment variable to a size string before starting the sandbox:

```console
$ DOCKER_SANDBOXES_DOCKER_SIZE=10g sbx run claude
```

Use the non-Docker variant if you don't need to build or run containers inside the sandbox and want a lighter, non-privileged environment. Specify it explicitly with `--template`:

```console
$ sbx run claude --template docker.io/docker/sandbox-templates:claude-code
```

### [Build a custom template](#build-a-custom-template)

Building a custom template requires [Docker Desktop](https://docs.docker.com/desktop/).

Write a Dockerfile that extends one of the base images. Pick the variant that matches the agent you plan to run. For example, extend `claude-code` to customize a Claude Code environment, or `codex` to customize an OpenAI Codex environment.

The following example creates a Claude Code template with Rust and protocol buffer tools pre-installed:

```dockerfile
FROM docker/sandbox-templates:claude-code
USER root
RUN apt-get update && apt-get install -y protobuf-compiler
USER agent
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
```

Use `root` for system-level package installations (`apt-get`), and switch back to `agent` before installing user-level tools. Tools that install into the home directory, such as `rustup`, `nvm`, or `pyenv`, must run as `agent` — otherwise they install under `/root/` and aren't available in the sandbox.

Build the image and push it to an OCI registry, such as Docker Hub:

```console
$ docker build -t my-org/my-template:v1 --push .
```

> Note
>
> The Docker daemon used by Docker Sandboxes pulls templates from a registry directly; it doesn't share the image store of your local Docker daemon on the host.

> Important
>
> For Docker Hub, `sbx` reuses your `sbx login` session to pull private images. For other registries (GitHub Container Registry, ECR, ACR, a self-hosted Nexus, and so on), store pull credentials with [`sbx secret set --registry`](https://docs.docker.com/ai/sandboxes/security/credentials/#registry-credentials) before running the sandbox:
>
> ```console
> $ gh auth token | sbx secret set --registry ghcr.io --password-stdin
> ```
>
> Without stored credentials, pulls from non-Docker Hub registries are anonymous and private images fail to pull.

For locally-built images, save the image to a tar and load it directly into the sandbox runtime instead of pulling from a registry:

```console
$ docker image save my-org/my-template:v1 -o my-template.tar
$ sbx template load my-template.tar
$ sbx run --template my-org/my-template:v1 claude
```

`sbx template load` imports the tar into the sandbox runtime's image store, so the image doesn't need to be reachable from a registry at sandbox creation time.

Unless you use the permissive `allow-all` network policy, you may also need to allow-list any domains that your custom tools depend on:

```console
$ sbx policy allow network -g "*.example.com:443,example.com:443"
```

Then run a sandbox with your template. The agent you specify must match the base image variant your template extends:

```console
$ sbx run --template docker.io/my-org/my-template:v1 claude
```

Because this template extends the `claude-code` base image, you run it with `claude`. If you extend `codex`, use `codex`; if you extend `shell`, use `shell` (which drops you into a Bash shell with no agent).

> Note
>
> Unlike Docker commands, `sbx` does not automatically resolve the Docker Hub domain (`docker.io`) in image references.

### [Template caching](#template-caching)

Template images are cached locally. The first use pulls from the registry; subsequent sandboxes reuse the cache. Cached images persist across sandbox creation and deletion, and are cleared when you run `sbx reset`.

## [Saving a sandbox as a template](#saving-a-sandbox-as-a-template)

Instead of writing a Dockerfile, you can save a running sandbox's state as a template. This captures installed packages, configuration changes, and files into a reusable image — useful when you've set up an environment interactively and want to preserve it.

### [Save and reuse](#save-and-reuse)

Stop the sandbox (or let the CLI prompt you), then save it with a name and tag:

```console
$ sbx template save my-sandbox my-template:v1
```

The image is stored in the sandbox runtime's local image store. Create a new sandbox from it with the `-t` flag:

```console
$ sbx run -t my-template:v1 claude
```

### [List and remove templates](#list-and-remove-templates)

List all saved templates:

```console
$ sbx template ls
```

Remove a template you no longer need:

```console
$ sbx template rm my-template:v1
```

### [Export and import](#export-and-import)

To share a saved template or move it to another machine, export it as a tar file:

```console
$ sbx template save my-sandbox my-template:v1 --output my-template.tar
```

On the other machine, load the tar file and use it:

```console
$ sbx template load my-template.tar
$ sbx run -t my-template:v1 claude
```

### [Limitations](#limitations)

Agent configuration files are always recreated when a sandbox is created. Changes to user-level agent configuration files, such as `/home/agent/.claude/settings.json` and `/home/agent/.claude.json`, do not persist in saved templates.

If the saved template was built for a different agent than the one you specify in `sbx run`, you get a warning. For example, saving a Claude sandbox and running it with `codex` produces:

```text
⚠ WARNING: template "my-template:v1" was built for the "claude" agent but you are using "codex".
  The sandbox may not work correctly. Consider using: sbx run -t my-template:v1 claude
```

----
url: https://docs.docker.com/guides/testcontainers-java-mockserver/write-tests/
----

[Insights on the state of AI agents from 800+ builders and leaders. Download your copy](https://www.docker.com/resources/the-state-of-agentic-ai-white-paper/)

✕

# Write tests with Testcontainers MockServer

***

Table of contents

***

Mocking external API interactions at the HTTP protocol level, rather than mocking Java methods, lets you verify marshalling and unmarshalling behavior and simulate network issues.

Testcontainers provides a MockServer module that starts a [MockServer](https://www.mock-server.com/) instance inside a Docker container. You can then use `MockServerClient` to configure mock expectations.

## [Write the test](#write-the-test)

Create `AlbumControllerTest.java`:

```java
package com.testcontainers.demo;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.hasSize;
import static org.mockserver.model.HttpRequest.request;
import static org.mockserver.model.HttpResponse.response;
import static org.mockserver.model.JsonBody.json;

import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.mockserver.client.MockServerClient;
import org.mockserver.model.Header;
import org.mockserver.verify.VerificationTimes;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.server.LocalServerPort;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.mockserver.MockServerContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@Testcontainers
class AlbumControllerTest {

  @LocalServerPort
  private Integer port;

  @Container
  static MockServerContainer mockServerContainer =
    new MockServerContainer("mockserver/mockserver:5.15.0");

  static MockServerClient mockServerClient;

  @DynamicPropertySource
  static void overrideProperties(DynamicPropertyRegistry registry) {
    mockServerClient =
    new MockServerClient(
      mockServerContainer.getHost(),
      mockServerContainer.getServerPort()
    );
    registry.add("photos.api.base-url", mockServerContainer::getEndpoint);
  }

  @BeforeEach
  void setUp() {
    RestAssured.port = port;
    mockServerClient.reset();
  }

  @Test
  void shouldGetAlbumById() {
    Long albumId = 1L;

    mockServerClient
      .when(
        request().withMethod("GET").withPath("/albums/" + albumId + "/photos")
      )
      .respond(
        response()
          .withStatusCode(200)
          .withHeaders(
            new Header("Content-Type", "application/json; charset=utf-8")
          )
          .withBody(
            json(
              """
              [
                   {
                       "id": 1,
                       "title": "accusamus beatae ad facilis cum similique qui sunt",
                       "url": "https://via.placeholder.com/600/92c952",
                       "thumbnailUrl": "https://via.placeholder.com/150/92c952"
                   },
                   {
                       "id": 2,
                       "title": "reprehenderit est deserunt velit ipsam",
                       "url": "https://via.placeholder.com/600/771796",
                       "thumbnailUrl": "https://via.placeholder.com/150/771796"
                   }
               ]
              """
            )
          )
      );

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/albums/{albumId}", albumId)
      .then()
      .statusCode(200)
      .body("albumId", is(albumId.intValue()))
      .body("photos", hasSize(2));

    verifyMockServerRequest("GET", "/albums/" + albumId + "/photos", 1);
  }

  @Test
  void shouldReturn404StatusWhenAlbumNotFound() {
    Long albumId = 1L;
    mockServerClient
      .when(
        request().withMethod("GET").withPath("/albums/" + albumId + "/photos")
      )
      .respond(response().withStatusCode(404));

    given()
      .contentType(ContentType.JSON)
      .when()
      .get("/api/albums/{albumId}", albumId)
      .then()
      .statusCode(404);

    verifyMockServerRequest("GET", "/albums/" + albumId + "/photos", 1);
  }

  private void verifyMockServerRequest(String method, String path, int times) {
    mockServerClient.verify(
      request().withMethod(method).withPath(path),
      VerificationTimes.exactly(times)
    );
  }
}
```

Here's what the test does:

* `@SpringBootTest` starts the full application on a random port.
* The `@Testcontainers` and `@Container` annotations start a `MockServerContainer` and create a `MockServerClient` connected to it.
* `@DynamicPropertySource` overrides `photos.api.base-url` to point at the MockServer endpoint, so the application talks to MockServer instead of the real photo service.
* `@BeforeEach` resets the `MockServerClient` before every test so that expectations from one test don't affect another.
* `shouldGetAlbumById()` configures a mock response for `/albums/{albumId}/photos`, sends a request to the application's `/api/albums/{albumId}` endpoint, and verifies the response body. It also uses `mockServerClient.verify()` to confirm that the expected API call reached MockServer.
* `shouldReturn404StatusWhenAlbumNotFound()` configures MockServer to return a 404 status and verifies the application propagates that status to the caller.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-mockserver/run-tests/)

----
url: https://docs.docker.com/reference/cli/docker/stack/ls/
----

# docker stack ls

***

| Description                                                               | List stacks                 |
| ------------------------------------------------------------------------- | --------------------------- |
| Usage                                                                     | `docker stack ls [OPTIONS]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker stack list`         |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Lists the stacks.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                | Default | Description                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`--format`](#format) |         | Format output using a custom template: 'table': Print output in table format with column headers (default) 'table TEMPLATE': Print output in table format using the given Go template 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |

## [Examples](#examples)

The following command shows all stacks and some additional information:

```console
$ docker stack ls

ID                 SERVICES            ORCHESTRATOR
myapp              2                   Kubernetes
vossibility-stack  6                   Swarm
```

### [Format the output (--format)](#format)

The formatting option (`--format`) pretty-prints stacks using a Go template.

Valid placeholders for the Go template are listed below:

| Placeholder     | Description        |
| --------------- | ------------------ |
| `.Name`         | Stack name         |
| `.Services`     | Number of services |
| `.Orchestrator` | Orchestrator name  |
| `.Namespace`    | Namespace          |

When using the `--format` option, the `stack ls` command either outputs the data exactly as the template declares or, when using the `table` directive, includes column headers as well.

The following example uses a template without headers and outputs the `Name` and `Services` entries separated by a colon (`:`) for all stacks:

```console
$ docker stack ls --format "{{.Name}}: {{.Services}}"
web-server: 1
web-cache: 4
```

To list all stacks in JSON format, use the `json` directive:

```console
$ docker stack ls --format json
{"Name":"myapp","Namespace":"","Orchestrator":"Swarm","Services":"3"}
```

----
url: https://docs.docker.com/guides/dotnet/run-tests/
----

# Run .NET tests in a container

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete all the previous sections of this guide, starting with [Containerize a .NET application](https://docs.docker.com/guides/dotnet/containerize/).

## [Overview](#overview)

Testing is an essential part of modern software development. Testing can mean a lot of things to different development teams. There are unit tests, integration tests and end-to-end testing. In this guide you take a look at running your unit tests in Docker when developing and when building.

## [Run tests when developing locally](#run-tests-when-developing-locally)

The sample application already has an xUnit test inside the `tests` directory. When developing locally, you can use Compose to run your tests.

Run the following command in the `docker-dotnet-sample` directory to run the tests inside a container.

```console
$ docker compose run --build --rm server dotnet test /source/tests
```

You should see output that contains the following.

```console
Starting test execution, please wait...
A total of 1 test files matched the specified pattern.

Passed!  - Failed:     0, Passed:     1, Skipped:     0, Total:     1, Duration: < 1 ms - /source/tests/bin/Debug/net10.0/tests.dll (net10.0)
```

To learn more about the command, see [docker compose run](/reference/cli/docker/compose/run/).

## [Run tests when building](#run-tests-when-building)

To run your tests when building, you need to update your Dockerfile. You can create a new test stage that runs the tests, or run the tests in the existing build stage. For this guide, update the Dockerfile to run the tests in the build stage.

The following is the updated Dockerfile.

```dockerfile
# syntax=docker/dockerfile:1

FROM --platform=$BUILDPLATFORM dhi.io/dotnet:10-sdk AS build
ARG TARGETARCH
COPY . /source
WORKDIR /source/src
RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \
    dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app
RUN dotnet test /source/tests

FROM dhi.io/dotnet:10-sdk AS development
COPY . /source
WORKDIR /source/src
CMD dotnet run --no-launch-profile

FROM dhi.io/aspnetcore:10 AS final
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "myWebApp.dll"]
```

```dockerfile
# syntax=docker/dockerfile:1

FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build
ARG TARGETARCH
COPY . /source
WORKDIR /source/src
RUN --mount=type=cache,id=nuget,target=/root/.nuget/packages \
    dotnet publish -a ${TARGETARCH/amd64/x64} --use-current-runtime --self-contained false -o /app
RUN dotnet test /source/tests

FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS development
COPY . /source
WORKDIR /source/src
CMD dotnet run --no-launch-profile

FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
WORKDIR /app
COPY --from=build /app .
ARG UID=10001
RUN adduser \
    --disabled-password \
    --gecos "" \
    --home "/nonexistent" \
    --shell "/sbin/nologin" \
    --no-create-home \
    --uid "${UID}" \
    appuser
USER appuser
ENTRYPOINT ["dotnet", "myWebApp.dll"]
```

Run the following command to build an image using the build stage as the target and view the test results. Include `--progress=plain` to view the build output, `--no-cache` to ensure the tests always run, and `--target build` to target the build stage.

```console
$ docker build -t dotnet-docker-image-test --progress=plain --no-cache --target build .
```

You should see output containing the following.

```console
#11 [build 5/5] RUN dotnet test /source/tests
#11 1.564   Determining projects to restore...
#11 3.421   Restored /source/src/myWebApp.csproj (in 1.02 sec).
#11 19.42   Restored /source/tests/tests.csproj (in 17.05 sec).
#11 27.91   myWebApp -> /source/src/bin/Debug/net10.0/myWebApp.dll
#11 28.47   tests -> /source/tests/bin/Debug/net10.0/tests.dll
#11 28.49 Test run for /source/tests/bin/Debug/net10.0/tests.dll (.NETCoreApp,Version=v10.0)
#11 28.67 Microsoft (R) Test Execution Command Line Tool Version 17.3.3 (x64)
#11 28.67 Copyright (c) Microsoft Corporation.  All rights reserved.
#11 28.68
#11 28.97 Starting test execution, please wait...
#11 29.03 A total of 1 test files matched the specified pattern.
#11 32.07
#11 32.08 Passed!  - Failed:     0, Passed:     1, Skipped:     0, Total:     1, Duration: < 1 ms - /source/tests/bin/Debug/net10.0/tests.dll (net10.0)
#11 DONE 32.2s
```

## [Summary](#summary)

In this section, you learned how to run tests when developing locally using Compose and how to run tests when building your image.

Related information:

* [docker compose run](/reference/cli/docker/compose/run/)

## [Next steps](#next-steps)

Next, you’ll learn how to set up a CI/CD pipeline using GitHub Actions.

[Configure CI/CD for your .NET application »](https://docs.docker.com/guides/dotnet/configure-ci-cd/)

----
url: https://docs.docker.com/get-started/docker-concepts/running-containers/persisting-container-data/
----

# Persisting container data

***

Table of contents

***

## [Explanation](#explanation)

When a container starts, it uses the files and configuration provided by the image. Each container is able to create, modify, and delete files and does so without affecting any other containers. When the container is deleted, these file changes are also deleted.

While this ephemeral nature of containers is great, it poses a challenge when you want to persist the data. For example, if you restart a database container, you might not want to start with an empty database. So, how do you persist files?

### [Container volumes](#container-volumes)

Volumes are a storage mechanism that provide the ability to persist data beyond the lifecycle of an individual container. Think of it like providing a shortcut or symlink from inside the container to outside the container.

As an example, imagine you create a volume named `log-data`.

```console
$ docker volume create log-data
```

When starting a container with the following command, the volume will be mounted (or attached) into the container at `/logs`:

```console
$ docker run -d -p 80:80 -v log-data:/logs docker/welcome-to-docker
```

If the volume `log-data` doesn't exist, Docker will automatically create it for you.

When the container runs, all files it writes into the `/logs` folder will be saved in this volume, outside of the container. If you delete the container and start a new container using the same volume, the files will still be there.

> **Sharing files using volumes**
>
> You can attach the same volume to multiple containers to share files between containers. This might be helpful in scenarios such as log aggregation, data pipelines, or other event-driven applications.

### [Managing volumes](#managing-volumes)

Volumes have their own lifecycle beyond that of containers and can grow quite large depending on the type of data and applications you’re using. The following commands will be helpful to manage volumes:

* `docker volume ls` - list all volumes
* `docker volume rm <volume-name-or-id>` - remove a volume (only works when the volume is not attached to any containers)
* `docker volume prune` - remove all unused (unattached) volumes

## [Try it out](#try-it-out)

In this guide, you'll practice creating and using volumes to persist data created by a Postgres container. When the database runs, it stores files into the `/var/lib/postgresql` directory. By attaching the volume here, you will be able to restart the container multiple times while keeping the data.

### [Use volumes](#use-volumes)

1. [Download and install](/get-started/get-docker/) Docker Desktop.

2. Start a container using the [Postgres image](https://hub.docker.com/_/postgres) with the following command:

   ```console
   $ docker run --name=db -e POSTGRES_PASSWORD=secret -d -v postgres_data:/var/lib/postgresql postgres:18
   ```

   This will start the database in the background, configure it with a password, and attach a volume to the directory PostgreSQL will persist the database files.

3. Connect to the database by using the following command:

   ```console
   $ docker exec -ti db psql -U postgres
   ```

4. In the PostgreSQL command line, run the following to create a database table and insert two records:

   ```text
   CREATE TABLE tasks (
       id SERIAL PRIMARY KEY,
       description VARCHAR(100)
   );
   INSERT INTO tasks (description) VALUES ('Finish work'), ('Have fun');
   ```

5. Verify the data is in the database by running the following in the PostgreSQL command line:

   ```text
   SELECT * FROM tasks;
   ```

   You should get output that looks like the following:

   ```text
    id | description
   ----+-------------
     1 | Finish work
     2 | Have fun
   (2 rows)
   ```

6. Exit out of the PostgreSQL shell by running the following command:

   ```console
   \q
   ```

7. Stop and remove the database container. Remember that, even though the container has been deleted, the data is persisted in the `postgres_data` volume.

   ```console
   $ docker stop db
   $ docker rm db
   ```

8. Start a new container by running the following command, attaching the same volume with the persisted data:

   ```console
   $ docker run --name=new-db -d -v postgres_data:/var/lib/postgresql postgres:18
   ```

   You might have noticed that the `POSTGRES_PASSWORD` environment variable has been omitted. That’s because that variable is only used when bootstrapping a new database.

9. Verify the database still has the records by running the following command:

   ```console
   $ docker exec -ti new-db psql -U postgres -c "SELECT * FROM tasks"
   ```

### [View volume contents](#view-volume-contents)

The Docker Desktop Dashboard provides the ability to view the contents of any volume, as well as the ability to export, import, empty, delete and clone volumes.

1. Open the Docker Desktop Dashboard and navigate to the **Volumes** view. In this view, you should see the **postgres\_data** volume.

2. Select the **postgres\_data** volume’s name.

3. The **Stored Data** tab shows the contents of the volume and provides the ability to navigate the files. The **Container in-use** tab displays the name of the container using the volume, the image name, the port number used by the container, and the target. A target is a path inside a container that gives access to the files in the volume. The **Exports** tab lets you export the volume. Double-clicking on a file will let you see the contents and make changes.

4. Right-click on any file to save it or delete it.

### [Remove volumes](#remove-volumes)

Before removing a volume, it must not be attached to any containers. If you haven’t removed the previous container, do so with the following command (the `-f` will stop the container first and then remove it):

```console
$ docker rm -f new-db
```

There are a few methods to remove volumes, including the following:

* Select the **Delete Volume** option on a volume in the Docker Desktop Dashboard.

* Use the `docker volume rm` command:

  ```console
  $ docker volume rm postgres_data
  ```

* Use the `docker volume prune` command to remove all unused volumes:

  ```console
  $ docker volume prune
  ```

## [Additional resources](#additional-resources)

The following resources will help you learn more about volumes:

* [Manage data in Docker](/engine/storage)
* [Volumes](/engine/storage/volumes)
* [Volume mounts](/engine/containers/run/#volume-mounts)

## [Next steps](#next-steps)

Now that you have learned about persisting container data, it’s time to learn about sharing local files with containers.

[Sharing local files with containers](https://docs.docker.com/get-started/docker-concepts/running-containers/sharing-local-files/)

----
url: https://docs.docker.com/guides/frameworks/laravel/production-setup/
----

# Laravel Production Setup with Docker Compose

***

Table of contents

***

This guide demonstrates how to set up a production-ready Laravel environment using Docker and Docker Compose. This configuration is designed for streamlined, scalable, and secure Laravel application deployments.

> Note
>
> To experiment with a ready-to-run configuration, download the [Laravel Docker Examples](https://github.com/dockersamples/laravel-docker-examples) repository. It contains pre-configured setups for both development and production.

## [Project structure](#project-structure)

```plaintext
my-laravel-app/
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
├── docker/
│   ├── common/
│   │   └── php-fpm/
│   │       ├── Dockerfile
│   │       └── conf.d/
│   │           └── 20-status-path.conf
│   ├── development/
│   ├── production/
│   │   ├── php-fpm/
│   │   │   └── entrypoint.sh
│   │   └── nginx
│   │       ├── Dockerfile
│   │       └── nginx.conf
├── compose.dev.yaml
├── compose.prod.yaml
├── .dockerignore
├── .env
├── vendor/
├── ...
```

This layout represents a typical Laravel project, with Docker configurations stored in a unified `docker` directory. You’ll find **two** Compose files — `compose.dev.yaml` (for development) and `compose.prod.yaml` (for production) — to keep your environments separate and manageable.

## [Create a Dockerfile for PHP-FPM (production)](#create-a-dockerfile-for-php-fpm-production)

For production, the `php-fpm` Dockerfile creates an optimized image with only the PHP extensions and libraries your application needs. As demonstrated in the [GitHub example](https://github.com/dockersamples/laravel-docker-examples), a single Dockerfile with multi-stage builds maintains consistency and reduces duplication between development and production. The following snippet shows only the production-related stages:

```dockerfile
# Stage 1: Build environment and Composer dependencies
FROM php:8.5-fpm AS builder

# Install system dependencies and PHP extensions for Laravel with MySQL/PostgreSQL support.
# Dependencies in this stage are only required for building the final image.
# Node.js and asset building are handled in the Nginx stage, not here.
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    unzip \
    libpq-dev \
    libonig-dev \
    libssl-dev \
    libxml2-dev \
    libcurl4-openssl-dev \
    libicu-dev \
    libzip-dev \
    && docker-php-ext-install -j$(nproc) \
    pdo_mysql \
    pdo_pgsql \
    pgsql \
    intl \
    zip \
    bcmath \
    soap \
    && pecl install redis \
    && docker-php-ext-enable redis \
    && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

# Set the working directory inside the container
WORKDIR /var/www

# Copy the entire Laravel application code into the container
# -----------------------------------------------------------
# In Laravel, `composer install` may trigger scripts
# needing access to application code.
# For example, the `post-autoload-dump` event might execute
# Artisan commands like `php artisan package:discover`. If the
# application code (including the `artisan` file) is not
# present, these commands will fail, leading to build errors.
#
# By copying the entire application code before running
# `composer install`, we ensure that all necessary files are
# available, allowing these scripts to run successfully.
# In other cases, it would be possible to copy composer files
# first, to leverage Docker's layer caching mechanism.
# -----------------------------------------------------------
COPY . /var/www

# Install Composer and dependencies
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \
    && composer install --no-dev --optimize-autoloader --no-interaction --no-progress --prefer-dist

# Stage 2: Production environment
FROM php:8.5-fpm AS production

# Install only runtime libraries needed in production
# libfcgi-bin and procps are required for the php-fpm-healthcheck script
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq-dev \
    libicu-dev \
    libzip-dev \
    libfcgi-bin \
    procps \
    && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

# Download and install php-fpm health check script
RUN curl -o /usr/local/bin/php-fpm-healthcheck \
    https://raw.githubusercontent.com/renatomefi/php-fpm-healthcheck/master/php-fpm-healthcheck \
    && chmod +x /usr/local/bin/php-fpm-healthcheck

# Copy the initialization script
COPY ./docker/php-fpm/entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh

# Copy the initial storage structure
COPY ./storage /var/www/storage-init

# Copy PHP extensions and libraries from the builder stage
COPY --from=builder /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions/
COPY --from=builder /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/
COPY --from=builder /usr/local/bin/docker-php-ext-* /usr/local/bin/

# Use the recommended production PHP configuration
# -----------------------------------------------------------
# PHP provides development and production configurations.
# Here, we replace the default php.ini with the production
# version to apply settings optimized for performance and
# security in a live environment.
# -----------------------------------------------------------
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"

# Keep the image-provided FPM global config intact and add pool overrides separately
COPY ./docker/common/php-fpm/conf.d/*.conf /usr/local/etc/php-fpm.d/
# Update the variables_order to include E (for ENV)
#RUN sed -i 's/variables_order = "GPCS"/variables_order = "EGPCS"/' "$PHP_INI_DIR/php.ini"

# Copy the application code and dependencies from the build stage
COPY --from=builder /var/www /var/www

# Set working directory
WORKDIR /var/www

# Ensure correct permissions
RUN chown -R www-data:www-data /var/www

# Switch to the non-privileged user to run the application
USER www-data

# Change the default command to run the entrypoint script
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

# Expose port 9000 and start php-fpm server
EXPOSE 9000
CMD ["php-fpm"]
```

## [Create a Dockerfile for PHP-CLI (production)](#create-a-dockerfile-for-php-cli-production)

For production, you often need a separate container to run Artisan commands, migrations, and other CLI tasks. In most cases you can run these commands by reusing existing PHP-FPM container:

```console
$ docker compose -f compose.prod.yaml exec php-fpm php artisan route:list
```

If you need a separate CLI container with different extensions or strict separation of concerns, consider a php-cli Dockerfile:

```dockerfile
# Stage 1: Build environment and Composer dependencies
FROM php:8.5-cli AS builder

# Install system dependencies and PHP extensions required for Laravel + MySQL/PostgreSQL support
# Some dependencies are required for PHP extensions only in the build stage
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    unzip \
    libpq-dev \
    libonig-dev \
    libssl-dev \
    libxml2-dev \
    libcurl4-openssl-dev \
    libicu-dev \
    libzip-dev \
    && docker-php-ext-install -j$(nproc) \
    pdo_mysql \
    pdo_pgsql \
    pgsql \
    intl \
    zip \
    bcmath \
    soap \
    && pecl install redis \
    && docker-php-ext-enable redis \
    && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

# Set the working directory inside the container
WORKDIR /var/www

# Copy the entire Laravel application code into the container
COPY . /var/www

# Install Composer and dependencies
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \
    && composer install --no-dev --optimize-autoloader --no-interaction --no-progress --prefer-dist

# Stage 2: Production environment
FROM php:8.5-cli

# Install client libraries required for php extensions in runtime
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq-dev \
    libicu-dev \
    libzip-dev \
    && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

# Copy PHP extensions and libraries from the builder stage
COPY --from=builder /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions/
COPY --from=builder /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/
COPY --from=builder /usr/local/bin/docker-php-ext-* /usr/local/bin/

# Use the default production configuration for PHP runtime arguments
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"

# Copy the application code and dependencies from the build stage
COPY --from=builder /var/www /var/www

# Set working directory
WORKDIR /var/www

# Ensure correct permissions
RUN chown -R www-data:www-data /var/www

# Switch to the non-privileged user to run the application
USER www-data

# Default command: Provide a bash shell to allow running any command
CMD ["bash"]
```

This Dockerfile is similar to the PHP-FPM Dockerfile, but it uses the `php:8.5-cli` image as the base image and sets up the container for running CLI commands.

## [Create a Dockerfile for Nginx (production)](#create-a-dockerfile-for-nginx-production)

Nginx serves as the web server for the Laravel application. You can include static assets directly to the container. Here's an example of possible Dockerfile for Nginx:

```dockerfile
# docker/nginx/Dockerfile
# Stage 1: Build assets
FROM debian AS builder

# Install Node.js and build tools
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    nodejs \
    npm \
    && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

# Set working directory
WORKDIR /var/www

# Copy Laravel application code
COPY . /var/www

# Install Node.js dependencies and build assets
RUN npm install && npm run build

# Stage 2: Nginx production image
FROM nginx:alpine

# Copy custom Nginx configuration
# -----------------------------------------------------------
# Replace the default Nginx configuration with our custom one
# that is optimized for serving a Laravel application.
# -----------------------------------------------------------
COPY ./docker/nginx/nginx.conf /etc/nginx/nginx.conf

# Copy Laravel's public assets from the builder stage
# -----------------------------------------------------------
# We only need the 'public' directory from our Laravel app.
# -----------------------------------------------------------
COPY --from=builder /var/www/public /var/www/public

# Set the working directory to the public folder
WORKDIR /var/www/public

# Expose port 80 and start Nginx
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

This Dockerfile uses a multi-stage build to separate the asset building process from the final production image. The first stage installs Node.js and builds the assets, while the second stage sets up the Nginx production image with the optimized configuration and the built assets.

## [Create a Docker Compose configuration for production](#create-a-docker-compose-configuration-for-production)

To bring all the services together, create a `compose.prod.yaml` file that defines the services, volumes, and networks for the production environment. Here's an example configuration:

```yaml
services:
  web:
    build:
      context: .
      dockerfile: ./docker/production/nginx/Dockerfile
    restart: unless-stopped # Automatically restart unless the service is explicitly stopped
    volumes:
      # Mount the 'laravel-storage' volume to '/var/www/storage' inside the container.
      # -----------------------------------------------------------
      # This volume stores persistent data like uploaded files and cache.
      # The ':ro' option mounts it as read-only in the 'web' service because Nginx only needs to read these files.
      # The 'php-fpm' service mounts the same volume without ':ro' to allow write operations.
      # -----------------------------------------------------------
      - laravel-storage-production:/var/www/storage:ro
    networks:
      - laravel-production
    ports:
      # Map port 80 inside the container to the port specified by 'NGINX_PORT' on the host machine.
      # -----------------------------------------------------------
      # This allows external access to the Nginx web server running inside the container.
      # For example, if 'NGINX_PORT' is set to '8080', accessing 'http://localhost:8080' will reach the application.
      # -----------------------------------------------------------
      - "${NGINX_PORT:-80}:80"
    depends_on:
      php-fpm:
        condition: service_healthy # Wait for php-fpm health check

  php-fpm:
    # For the php-fpm service, we will create a custom image to install the necessary PHP extensions and setup proper permissions.
    build:
      context: .
      dockerfile: ./docker/common/php-fpm/Dockerfile
      target: production # Use the 'production' stage in the Dockerfile
    restart: unless-stopped
    volumes:
      - laravel-storage-production:/var/www/storage # Mount the storage volume
    env_file:
      - .env
    networks:
      - laravel-production
    healthcheck:
      test: ["CMD-SHELL", "php-fpm-healthcheck || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 3
    # The 'depends_on' attribute with 'condition: service_healthy' ensures that
    # this service will not start until the 'postgres' service passes its health check.
    # This prevents the application from trying to connect to the database before it's ready.
    depends_on:
      postgres:
        condition: service_healthy

  # The 'php-cli' service provides a command-line interface for running Artisan commands and other CLI tasks.
  # -----------------------------------------------------------
  # This is useful for running migrations, seeders, or any custom scripts.
  # It shares the same codebase and environment as the 'php-fpm' service.
  # -----------------------------------------------------------
  php-cli:
    build:
      context: .
      dockerfile: ./docker/php-cli/Dockerfile
    tty: true # Enables an interactive terminal
    stdin_open: true # Keeps standard input open for 'docker exec'
    env_file:
      - .env
    networks:
      - laravel-production

  postgres:
    image: postgres:18
    restart: unless-stopped
    user: postgres
    ports:
      - "${POSTGRES_PORT}:5432"
    environment:
      - POSTGRES_DB=${POSTGRES_DATABASE}
      - POSTGRES_USER=${POSTGRES_USERNAME}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - postgres-data-production:/var/lib/postgresql
    networks:
      - laravel-production
    # Health check for PostgreSQL
    # -----------------------------------------------------------
    # Health checks allow Docker to determine if a service is operational.
    # The 'pg_isready' command checks if PostgreSQL is ready to accept connections.
    # This prevents dependent services from starting before the database is ready.
    # -----------------------------------------------------------
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:alpine
    restart: unless-stopped # Automatically restart unless the service is explicitly stopped
    networks:
      - laravel-production
    # Health check for Redis
    # -----------------------------------------------------------
    # Checks if Redis is responding to the 'PING' command.
    # This ensures that the service is not only running but also operational.
    # -----------------------------------------------------------
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

networks:
  # Attach the service to the 'laravel-production' network.
  # -----------------------------------------------------------
  # This custom network allows all services within it to communicate using their service names as hostnames.
  # For example, 'php-fpm' can connect to 'postgres' by using 'postgres' as the hostname.
  # -----------------------------------------------------------
  laravel-production:

volumes:
  postgres-data-production:
  laravel-storage-production:
```

> Note
>
> Ensure you have an `.env` file at the root of your Laravel project with the necessary configurations to match the Docker Compose setup.

## [Running your production environment](#running-your-production-environment)

To start the production environment, run:

```console
$ docker compose -f compose.prod.yaml up --build -d
```

This command will build and start all the services in detached mode, providing a scalable and production-ready setup for your Laravel application.

## [Summary](#summary)

By setting up a Docker Compose environment for Laravel in production, you ensure that your application is optimized for performance, scalable, and secure. This setup makes deployments consistent and easier to manage, reducing the likelihood of errors due to differences between environments.

[Laravel Development Setup with Docker Compose »](https://docs.docker.com/guides/frameworks/laravel/development-setup/)

----
url: https://docs.docker.com/reference/cli/docker/compose/bridge/transformations/create/
----

# docker compose bridge transformations create

***

| Description | Create a new transformation                                  |
| ----------- | ------------------------------------------------------------ |
| Usage       | `docker compose bridge transformations create [OPTION] PATH` |

## [Description](#description)

Create a new transformation

## [Options](#options)

| Option       | Default | Description                                                                  |
| ------------ | ------- | ---------------------------------------------------------------------------- |
| `-f, --from` |         | Existing transformation to copy (default: docker/compose-bridge-kubernetes)  |

----
url: https://docs.docker.com/guides/java/deploy/
----

# Test your Java deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Containerize your app](https://docs.docker.com/guides/java/containerize/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This lets you test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your `spring-petclinic` directory, create a file named `docker-java-kubernetes.yaml`. Open the file in an IDE or text editor and add the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the name of the repository that you created in [Configure CI/CD for your Java application](https://docs.docker.com/guides/java/configure-ci-cd/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-java-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      service: server
  template:
    metadata:
      labels:
        service: server
    spec:
      containers:
        - name: server-service
          image: DOCKER_USERNAME/REPO_NAME
          imagePullPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: service-entrypoint
  namespace: default
spec:
  type: NodePort
  selector:
    service: server
  ports:
    - port: 8080
      targetPort: 8080
      nodePort: 30001
```

In this Kubernetes YAML file, there are two objects, separated by the `---`:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your Java application](https://docs.docker.com/guides/java/configure-ci-cd/).
* A NodePort service, which will route traffic from port 30001 on your host to port 8080 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to `spring-petclinic` and deploy your application to Kubernetes.

   ```console
   $ kubectl apply -f docker-java-kubernetes.yaml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```shell
   deployment.apps/docker-java-demo created
   service/service-entrypoint created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```shell
   NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
   docker-java-demo     1/1     1            1           15s
   ```

   This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```shell
   NAME                 TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
   kubernetes           ClusterIP   10.96.0.1       <none>        443/TCP          23h
   service-entrypoint   NodePort    10.99.128.230   <none>        8080:30001/TCP   75s
   ```

   In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP.

3. In a terminal, curl the service. Note that a database wasn't deployed in this example.

   ```console
   $ curl --request GET \
     --url http://localhost:30001/actuator/health \
     --header 'content-type: application/json'
   ```

   You should get output like the following.

   ```console
   {"status":"UP","groups":["liveness","readiness"]}
   ```

4. Run the following command to tear down your application.

   ```console
   $ kubectl delete -f docker-java-kubernetes.yaml
   ```

## [Summary](#summary)

In this section, you learned how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine.

Related information:

* [Kubernetes documentation](https://kubernetes.io/docs/home/)
* [Deploy on Kubernetes with Docker Desktop](https://docs.docker.com/desktop/use-desktop/kubernetes/)
* [Swarm mode overview](https://docs.docker.com/engine/swarm/)

----
url: https://docs.docker.com/enterprise/security/access-tokens/
----

# Organization access tokens

***

Table of contents

***

Subscription: Team Business

Organization access tokens (OATs) provide secure, programmatic access to Docker Hub for automated systems, CI/CD pipelines, and other business-critical tasks. Unlike personal access tokens tied to individual users, OATs are associated with your organization and can be managed by any organization owner.

> Warning
>
> Organization access tokens are incompatible with Docker Desktop, Image Access Management, and Registry Access Management. If you use these features, use [personal access tokens](https://docs.docker.com/security/access-tokens/) instead.

## [Who should use organization access tokens?](#who-should-use-organization-access-tokens)

Use OATs for automated systems that need Docker Hub access without depending on individual user accounts:

* CI/CD pipelines: Build and deployment systems that push and pull images
* Production systems: Applications that pull images during deployment
* Monitoring tools: Systems that need to check repository status or pull images
* Backup systems: Tools that periodically pull images for archival
* Integration services: Third-party tools that integrate with your Docker Hub repositories

## [Key benefits](#key-benefits)

Benefits of using organization access tokens include:

* Organizational ownership: Not tied to individual users who might leave the company
* Shared management: All organization owners can create and manage OATs
* Separate usage limits: OATs have their own Docker Hub rate limits, not counting against personal accounts
* Better security audit: Track when tokens were last used and identify suspicious activity
* Granular permissions: Limit access to specific repositories and operations

## [Prerequisites](#prerequisites)

To create and use organization access tokens, you must have:

* A Docker Team or Business subscription
* Owner permissions
* Repositories you want to grant access to

## [Create an organization access token](#create-an-organization-access-token)

Owners can create tokens with these limits:

* Team subscription: Up to 10 OATs per organization
* Business subscription: Up to 100 OATs per organization

Expired tokens count toward your total limit.

To create an OAT:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.

2. Select **Admin Console**, then **Access tokens**.

3. Select **Generate access token**.

4. Configure token details:

   * Label: Descriptive name indicating the token's purpose
   * Description (optional): Additional details
   * Expiration date: When the token should expire

5. Expand the **Repository** drop-down to set access permissions:

   1. Optional. Select **Read public repositories** for access to public repositories.
   2. Select **Add repository** and choose a repository from the drop-down.
   3. Set permissions for each repository: **Image Pull** or **Image Push**.
   4. Add up to 50 repositories as needed.

6. Optional. Configure organization management permissions by expanding the **Organization** drop-down and selecting the **Allow management access to this organization's resources**:

   * **Member Edit**: Edit members of the organization
   * **Member Read**: Read members of the organization
   * **Invite Edit**: Invite members to the organization
   * **Invite Read**: Read invites to the organization
   * **Group Edit**: Edit groups of the organization
   * **Group Read**: Read groups of the organization

7. Select **Generate token**. Copy the token that appears on the screen and save it. You won't be able to retrieve the token once you exit the screen.

> Important
>
> Treat organization access tokens like passwords. Store them securely in a credential manager and never commit them to source code repositories.

## [Use organization access tokens](#use-organization-access-tokens)

Sign in to the Docker CLI using your organization access token:

```console
$ docker login --username YOUR_ORGANIZATION_NAME
Password: [paste your OAT here]
```

When prompted for a password, enter your organization access token.

## [Modify existing tokens](#modify-existing-tokens)

To manage existing tokens:

1. Sign in to [Docker Home](https://app.docker.com/) and select your organization.

2. Select **Admin Console**, then **Access tokens**.

3. Select the actions menu in the token row, you can:

   * **Edit**
   * **Deactivate**
   * **Delete**

4. Select **Save** after making changes to a token.

## [Organization access token best practices](#organization-access-token-best-practices)

* Regular token rotation: Set reasonable expiration dates and rotate tokens regularly to minimize security risks.
* Principle of least privilege: Grant only the minimum repository access and permissions needed for each use case.
* Monitor token usage: Regularly review when tokens were last used to identify unused or suspicious tokens.
* Secure storage: Store tokens in secure credential management systems, never in plain text or source code.
* Immediate revocation: Deactivate or delete tokens immediately if they're compromised or no longer needed.

----
url: https://docs.docker.com/reference/cli/docker/plugin/rm/
----

# docker plugin rm

***

| Description                                                               | Remove one or more plugins                      |
| ------------------------------------------------------------------------- | ----------------------------------------------- |
| Usage                                                                     | `docker plugin rm [OPTIONS] PLUGIN [PLUGIN...]` |
| AliasesAn alias is a short or memorable alternative for a longer command. | `docker plugin remove`                          |

## [Description](#description)

Removes a plugin. You cannot remove a plugin if it is enabled, you must disable a plugin using the [`docker plugin disable`](/reference/cli/docker/plugin/disable/) before removing it, or use `--force`. Use of `--force` is not recommended, since it can affect functioning of running containers using the plugin.

## [Options](#options)

| Option        | Default | Description                           |
| ------------- | ------- | ------------------------------------- |
| `-f, --force` |         | Force the removal of an active plugin |

## [Examples](#examples)

The following example disables and removes the `sample-volume-plugin:latest` plugin:

```console
$ docker plugin disable tiborvass/sample-volume-plugin

tiborvass/sample-volume-plugin

$ docker plugin rm tiborvass/sample-volume-plugin:latest

tiborvass/sample-volume-plugin
```

----
url: https://docs.docker.com/reference/cli/docker/model/push/
----

# docker model push

***

| Description | Push a model to Docker Hub or Hugging Face |
| ----------- | ------------------------------------------ |
| Usage       | `docker model push MODEL`                  |

## [Description](#description)

Push a model to Docker Hub or Hugging Face

----
url: https://docs.docker.com/guides/golang/configure-ci-cd/
----

# Configure CI/CD for your Go application

***

Table of contents

***

## [Prerequisites](#prerequisites)

Complete the previous sections of this guide, starting with [Build your Go image](https://docs.docker.com/guides/golang/build-images/). You must have a [GitHub](https://github.com/signup) account and a verified [Docker](https://hub.docker.com/signup) account to complete this section.

   ```console
   $ git remote set-url origin https://github.com/your-username/your-repository.git
   ```

7. Run the following commands to stage, commit, and push your local repository to GitHub.

   ```console
   $ git add -A
   $ git commit -m "my commit"
   $ git push -u origin main
   ```

## [Step two: Set up the workflow](#step-two-set-up-the-workflow)

Set up your GitHub Actions workflow for building, testing, and pushing the image to Docker Hub.

1. Go to your repository on GitHub and then select the **Actions** tab.

2. Select **set up a workflow yourself**.

   This takes you to a page for creating a new GitHub actions workflow file in your repository, under `.github/workflows/main.yml` by default.

3. In the editor window, copy and paste the following YAML configuration and commit the changes.

   ```yaml
   name: ci

   on:
     push:
       branches:
         - main

   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Login to Docker Hub
           uses: docker/login-action@v4
           with:
             username: ${{ vars.DOCKER_USERNAME }}
             password: ${{ secrets.DOCKERHUB_TOKEN }}

         - name: Set up Docker Buildx
           uses: docker/setup-buildx-action@v4

         - name: Build and push
           uses: docker/build-push-action@v7
           with:
             platforms: linux/amd64,linux/arm64
             push: true
             tags: ${{ vars.DOCKER_USERNAME }}/${{ github.event.repository.name }}:latest
   ```

[Test your Go deployment »](https://docs.docker.com/guides/golang/deploy/)

----
url: https://docs.docker.com/build/policies/examples/
----

# Policy templates and examples

***

Table of contents

***

This page provides complete, working policy examples you can copy and adapt. The examples are organized into two sections: getting started policies for quick adoption, and production templates for comprehensive security.

If you're new to policies, start with the tutorials: [Introduction](https://docs.docker.com/build/policies/intro/), [Image validation](https://docs.docker.com/build/policies/validate-images/), and [Git validation](https://docs.docker.com/build/policies/validate-git/). Those pages teach individual techniques. This page shows complete policies combining those techniques.

## [How to use these examples](#how-to-use-these-examples)

1. Copy the policy code into a `Dockerfile.rego` file next to your Dockerfile
2. Customize any todo comments with your specific values
3. Test by running `docker build .` and verifying the policy works as expected
4. Refine based on your team's needs

### [Using examples with bake](#using-examples-with-bake)

These policies work with both `docker buildx build` and `docker buildx bake`. For bake, place the policy alongside your Dockerfile and it loads automatically. To use additional policies:

```hcl
target "default" {
  dockerfile = "Dockerfile"
  policy = ["extra.rego"]
}
```

See the [Usage guide](https://docs.docker.com/build/policies/usage/) for complete bake integration details.

## [Getting started](#getting-started)

These policies work immediately with minimal or no customization. Use them to adopt policies quickly and demonstrate value to your team.

### [Development-friendly baseline](#development-friendly-baseline)

A permissive policy that allows typical development workflows while blocking obvious security issues.

```rego
package docker

default allow := false

allow if input.local
allow if input.git

# Allow common public registries
allow if {
  input.image.host == "docker.io"  # Docker Hub
}

allow if {
  input.image.host == "ghcr.io"  # GitHub Container Registry
}

allow if {
  input.image.host == "dhi.io"  # Docker Hardened Images
}

# Require HTTPS for all downloads
allow if {
  input.http.schema == "https"
}

decision := {"allow": allow}
```

This policy allows local and Git contexts, images from Docker Hub, GitHub Container Registry, and [Docker Hardened Images](/dhi/), and `ADD` downloads over HTTPS. It blocks HTTP downloads and non-standard registries.

When to use: Starting point for teams new to policies. Provides basic security without disrupting development workflows.

### [Registry allowlist](#registry-allowlist)

Control which registries your builds can pull images from.

```rego
package docker

default allow := false

allow if input.local

# TODO: Add your internal registry hostname
allowed_registries := ["docker.io", "ghcr.io", "dhi.io", "registry.company.com"]

allow if {
  input.image.host in allowed_registries
}

# Allow mirrored DHI images from Docker Hub (DHI Enterprise users)
# TODO: Replace with your organization namespace
allow if {
  input.image.host == "docker.io"
  startswith(input.image.repo, "myorg/dhi-")
}

deny_msg contains msg if {
  not allow
  input.image
  msg := sprintf("registry %s is not in the allowlist", [input.image.host])
}

decision := {"allow": allow, "deny_msg": deny_msg}
```

This policy restricts image pulls to approved registries. Customize and add your internal registry to the list. If you have a DHI Enterprise subscription and have mirrored Docker Hardened Images to Docker Hub, add a rule to allow images from your organization's namespace.

When to use: Enforce corporate policies about approved image sources. Prevents developers from using arbitrary public registries.

### [Pin base images to digests](#pin-base-images-to-digests)

Require digest references for reproducible builds.

```rego
package docker

default allow := false

allow if input.local

# Require digest references for all images
allow if {
  input.image.isCanonical
}

deny_msg contains msg if {
  not allow
  input.image
  msg := sprintf("image %s must use digest reference (e.g., @sha256:...)", [input.image.ref])
}

decision := {"allow": allow, "deny_msg": deny_msg}
```

This policy requires images use digest references like `alpine@sha256:abc123...` instead of tags like `alpine:3.19`. Digests are immutable - the same digest always resolves to the same image content.

When to use: Ensure build reproducibility. Prevents builds from breaking when upstream tags are updated. Required for compliance in some environments.

### [Control external dependencies](#control-external-dependencies)

Pin specific versions of dependencies downloaded during builds.

```rego
package docker

default allow := false

allow if input.local

# Allow any image (add restrictions as needed)
allow if input.image

# TODO: Add your allowed Git repositories and tags
allowed_repos := {
  "https://github.com/moby/buildkit.git": ["v0.26.1", "v0.27.0"],
}
# Only allow Git input from allowed_repos
allow if {
  some repo, versions in allowed_repos
  input.git.remote == repo
  input.git.tagName in versions
}

# TODO: Add your allowed downloads
allow if {
  input.http.url == "https://example.com/app-v1.0.tar.gz"
}

decision := {"allow": allow}
```

This policy creates allowlists for external dependencies. Add your Git repositories with approved version tags, and URLs.

When to use: Control which external dependencies can be used in builds. Prevents builds from pulling arbitrary versions or unverified downloads.

## [Production templates](#production-templates)

These templates demonstrate comprehensive security patterns. They require customization but show best practices for production environments.

### [Image attestation and provenance](#image-attestation-and-provenance)

Require images have provenance attestations from trusted builders.

```rego
package docker

default allow := false

allow if input.local

# TODO: Add your repository names
allowed_repos := ["myorg/backend", "myorg/frontend", "myorg/worker"]

# Production images need full attestations
allow if {
  some repo in allowed_repos
  input.image.repo == repo
  input.image.hasProvenance
  some sig in input.image.signatures
  trusted_github_builder(sig, repo)
}

# Helper to validate GitHub Actions build from main branch
trusted_github_builder(sig, repo) if {
  sig.signer.certificateIssuer == "CN=sigstore-intermediate,O=sigstore.dev"
  sig.signer.issuer == "https://token.actions.githubusercontent.com"
  startswith(sig.signer.buildSignerURI, sprintf("https://github.com/myorg/%s/.github/workflows/", [repo]))
  sig.signer.sourceRepositoryRef == "refs/heads/main"
  sig.signer.runnerEnvironment == "github-hosted"
}

# Allow Docker Hardened Images with built-in attestations
allow if {
  input.image.host == "dhi.io"
  input.image.isCanonical
  input.image.hasProvenance
}

# Allow official base images with digests
allow if {
  input.image.repo == "alpine"
  input.image.host == "docker.io"
  input.image.isCanonical
}

decision := {"allow": allow}
```

This template validates that your application images have provenance attestations, and were built by GitHub Actions from your main branch. Docker Hardened Images are allowed when using digests since they include comprehensive attestations by default. Other base images must use digests.

Customize:

* Replace `allowed_repos` with your image names
* Update the organization name in `trusted_github_builder()`
* Add rules for other base images you use

When to use: Enforce supply chain security for production deployments. Ensures images are built by trusted CI/CD pipelines with auditable provenance.

### [Signed Git releases](#signed-git-releases)

Enforce signed tags from trusted maintainers for Git dependencies.

```rego
package docker

default allow := false

allow if input.local

allow if input.image

# TODO: Replace with your repository URL
is_buildkit if {
    input.git.remote == "https://github.com/moby/buildkit.git"
}

is_version_tag if {
    is_buildkit
    regex.match(`^v[0-9]+\.[0-9]+\.[0-9]+$`, input.git.tagName)
}

# Version tags must be signed
allow if {
    is_version_tag
    input.git.tagName != ""
    verify_git_signature(input.git.tag, "maintainers.asc")
}

# Allow unsigned refs for development
allow if {
    is_buildkit
    not is_version_tag
}

decision := {"allow": allow}
```

This template requires production release tags to be signed by trusted maintainers. Development branches and commits can be unsigned.

Setup:

1. Export maintainer PGP public keys to `maintainers.asc`:
   ```console
   $ gpg --export --armor user1@example.com user2@example.com > maintainers.asc
   ```
2. Place `maintainers.asc` in the same directory as your policy file

Customize:

* Replace the repository URL in `is_buildkit`
* Update the maintainers in the PGP keyring file
* Adjust the version tag regex pattern if needed

When to use: Validate that production dependencies come from signed releases. Protects against compromised releases or unauthorized updates.

### [Multi-registry policy](#multi-registry-policy)

Apply different validation rules for internal and external registries.

```rego
package docker

default allow := false

allow if input.local

# TODO: Replace with your internal registry hostname
internal_registry := "registry.company.com"

# Internal registry: basic validation
allow if {
  input.image.host == internal_registry
}

# External registries: strict validation
allow if {
  input.image.host != internal_registry
  input.image.host != ""
  input.image.isCanonical
  input.image.hasProvenance
}

# Docker Hub: allowlist specific images
allow if {
  input.image.host == "docker.io"
  # TODO: Add your approved base images
  input.image.repo in ["alpine", "golang", "node"]
  input.image.isCanonical
}

# Docker Hardened Images: trusted by default with built-in attestations
allow if {
  input.image.host == "dhi.io"
  input.image.isCanonical
}

decision := {"allow": allow}
```

This template defines a trust boundary between internal and external image sources. Internal images require minimal validation, while external images need digests and provenance. Docker Hardened Images from `dhi.io` are treated as trusted since they include comprehensive attestations and security guarantees.

Customize:

* Set your internal registry hostname
* Add your approved Docker Hub base images
* Adjust validation requirements based on your security policies

When to use: Organizations with internal registries that need different rules for internal and external sources. Balances security with practical workflow needs.

### [Multi-environment policy](#multi-environment-policy)

Apply different rules based on the build target or stage. For example,

```rego
package docker

default allow := false

allow if input.local

# TODO: Define your environment detection logic
is_production if {
  input.env.target == "production"
}

is_development if {
  input.env.target == "development"
}

# Production: strict rules - only digest images with provenance
allow if {
  is_production
  input.image.isCanonical
  input.image.hasProvenance
}

# Development: permissive rules - any image
allow if {
  is_development
  input.image
}

# Staging inherits production rules (default target detection)
allow if {
  not is_production
  not is_development
  input.image.isCanonical
}

decision := {"allow": allow}
```

This template uses build targets to apply different validation levels. Production requires attestations and digests, development is permissive, and staging uses moderate rules.

Customize:

* Update environment detection logic (target names, build args, etc.)
* Adjust validation requirements for each environment
* Add more environments as needed

When to use: Teams with separate build configurations for different deployment stages. Allows flexibility in development while enforcing strict rules for production.

### [Complete dependency pinning](#complete-dependency-pinning)

Pin all external dependencies to specific versions across all input types.

```rego
package docker

default allow := false

allow if input.local

# TODO: Add your pinned images with exact digests
# Docker Hub images use docker.io as host
allowed_dockerhub := {
  "alpine": "sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412",
  "golang": "sha256:abc123...",
}

allow if {
  input.image.host == "docker.io"
  some repo, digest in allowed_dockerhub
  input.image.repo == repo
  input.image.checksum == digest
}

# TODO: Add your pinned DHI images
allowed_dhi := {
  "python": "sha256:def456...",
  "node": "sha256:ghi789...",
}

allow if {
  input.image.host == "dhi.io"
  some repo, digest in allowed_dhi
  input.image.repo == repo
  input.image.checksum == digest
}

# TODO: Add your pinned Git dependencies
allowed_git := {
  "https://github.com/moby/buildkit.git": {
    "tag": "v0.26.1",
    "commit": "abc123...",
  },
}

allow if {
  some url, version in allowed_git
  input.git.remote == url
  input.git.tagName == version.tag
  input.git.commitChecksum == version.commit
}

# TODO: Add your pinned HTTP downloads
allowed_downloads := {
  "https://releases.example.com/app-v1.0.tar.gz": "sha256:def456...",
}

allow if {
  some url, checksum in allowed_downloads
  input.http.url == url
  input.http.checksum == checksum
}

decision := {"allow": allow}
```

This template pins every external dependency to exact versions with cryptographic verification. Images use digests, Git repos use commit SHAs, and downloads use checksums.

Customize:

* Add all your dependencies with exact versions/checksums
* Maintain this file when updating dependencies
* Consider automating updates through CI/CD

When to use: Maximum reproducibility and security. Ensures builds always use exact versions of all dependencies. Required for high-security or regulated environments.

### [Manual signature verification](#manual-signature-verification)

Verify image signatures by inspecting signature metadata fields.

```rego
package docker

default allow := false

allow if input.local

# Require valid GitHub Actions signatures
allow if {
    input.image
    input.image.hasProvenance
    some sig in input.image.signatures
    valid_github_signature(sig)
}

# Helper function to validate GitHub Actions signature
valid_github_signature(sig) if {
    # Sigstore keyless signing
    sig.signer.certificateIssuer == "CN=sigstore-intermediate,O=sigstore.dev"
    sig.signer.issuer == "https://token.actions.githubusercontent.com"

    # TODO: Replace with your organization
    startswith(sig.signer.buildSignerURI, "https://github.com/myorg/.github/workflows/")
    startswith(sig.signer.sourceRepositoryURI, "https://github.com/myorg/")

    # Verify GitHub hosted runner
    sig.signer.runnerEnvironment == "github-hosted"

    # Require timestamp
    count(sig.timestamps) > 0
}

decision := {"allow": allow}
```

This policy validates that images were built by GitHub Actions using Sigstore keyless signing.

Customize:

* Replace `myorg` with your GitHub organization
* Adjust workflow path restrictions
* Add additional signature field checks as needed

When to use: Enforce that images are built by CI/CD with verifiable signatures, not manually pushed by developers.

## [Next steps](#next-steps)

* Write unit tests for your policies: [Test build policies](https://docs.docker.com/build/policies/testing/)
* Review [Built-in functions](https://docs.docker.com/build/policies/built-ins/) for signature verification and attestation checking
* Check the [Input reference](https://docs.docker.com/build/policies/inputs/) for all available fields you can validate
* Read the tutorials for detailed explanations: [Introduction](https://docs.docker.com/build/policies/intro/), [Image validation](https://docs.docker.com/build/policies/validate-images/), [Git validation](https://docs.docker.com/build/policies/validate-git/)

----
url: https://docs.docker.com/guides/docker-scout/
----

# Securing your software supply chain with Docker Scout

Table of contents

***

Enhance container security by automating vulnerability detection and remediation.

**Time to complete** 20 minutes

When container images are insecure, significant risks can arise. Around 60% of organizations have reported experiencing at least one security breach or vulnerability incident within a year, [resulting in operational disruption](https://cloudsecurityalliance.org/blog/2023/09/21/2023-global-cloud-threat-report-cloud-attacks-are-lightning-fast). These incidents often result in considerable downtime, with 44% of affected companies experiencing over an hour of downtime per event. The financial impact is substantial, with [the average data breach cost reaching $4.45 million](https://www.ibm.com/reports/data-breach). This highlights the critical importance of maintaining robust container security measures.

Docker Scout enhances container security by providing automated vulnerability detection and remediation, addressing insecure container images, and ensuring compliance with security standards.

## [What you'll learn](#what-youll-learn)

* Define Secure Software Supply Chain (SSSC)
* Review SBOMs and how to use them
* Detect and monitor vulnerabilities

## [Tools integration](#tools-integration)

Works well with Docker Desktop, GitHub Actions, Jenkins, Kubernetes, and other CI solutions.

## [Who’s this for?](#whos-this-for)

* DevOps engineers who need to integrate automated security checks into CI/CD pipelines to enhance the security and efficiency of their workflows.
* Developers who want to use Docker Scout to identify and remediate vulnerabilities early in the development process, ensuring the production of secure container images.
* Security professionals who must enforce security compliance, conduct vulnerability assessments, and ensure the overall security of containerized applications.

## [Modules](#modules)

1. [Why Docker Scout?](https://docs.docker.com/guides/docker-scout/why/)

   Learn how Docker Scout can help you secure your supply chain.

2. [Demo](https://docs.docker.com/guides/docker-scout/demo/)

   Learn about Docker Scout's powerful features for enhanced supply chain security.

3. [Software supply chain security](https://docs.docker.com/guides/docker-scout/s3c/)

   Learn about software supply chain security (S3C), what it means, and why it is important.

4. [Software Bill of Materials](https://docs.docker.com/guides/docker-scout/sbom/)

   Learn about Software Bill of Materials (SBOM) and how Docker Scout uses it.

5. [Attestations](https://docs.docker.com/guides/docker-scout/attestations/)

   Introduction to SBOM and provenance attestations with Docker Build, what they are, and why they exist

6. [Remediation](https://docs.docker.com/guides/docker-scout/remediation/)

   Learn how Docker Scout can help you improve your software quality automatically, using remediation

7. [Common challenges and questions](https://docs.docker.com/guides/docker-scout/common-questions/)

   Explore common challenges and questions related to Docker Scout.

----
url: https://docs.docker.com/guides/frameworks/laravel/
----

# Develop and Deploy Laravel applications with Docker Compose

Table of contents

***

Learn how to efficiently set up Laravel development and production environments using Docker Compose.

**Time to complete** 30 minutes

Laravel is a popular PHP framework that allows developers to build web applications quickly and effectively. Docker Compose simplifies the management of development and production environments by defining essential services, like PHP, a web server, and a database, in a single YAML file. This guide provides a streamlined approach to setting up a robust Laravel environment using Docker Compose, focusing on simplicity and efficiency.

> **Acknowledgment**
>
> Docker would like to thank [Sergei Shitikov](https://github.com/rw4lll) for his contribution to this guide.

The demonstrated examples can be found in [this GitHub repository](https://github.com/dockersamples/laravel-docker-examples). Docker Compose offers a straightforward approach to connecting multiple containers for Laravel, though similar setups can also be achieved using tools like Docker Swarm, Kubernetes, or individual Docker containers.

This guide is intended for educational purposes, helping developers adapt and optimize configurations for their specific use cases. Additionally, there are existing tools that support Laravel in containers:

* [Laravel Sail](https://laravel.com/docs/12.x/sail): An official package for easily starting Laravel in Docker.
* [Laradock](https://github.com/laradock/laradock): A community project that helps run Laravel applications in Docker.

## [What you’ll learn](#what-youll-learn)

* How to use Docker Compose to set up a Laravel development and production environment.
* Defining services that make Laravel development easier, including PHP-FPM, Nginx, and database containers.
* Best practices for managing Laravel environments using containerization.

## [Who’s this for?](#whos-this-for)

* Developers who work with Laravel and want to streamline environment management.
* DevOps engineers seeking efficient ways to manage and deploy Laravel applications.

## [Modules](#modules)

1. [Prerequisites for Setting Up Laravel with Docker Compose](https://docs.docker.com/guides/frameworks/laravel/prerequisites/)

   Ensure you have the required tools and knowledge before setting up Laravel with Docker Compose.

2. [Laravel Production Setup with Docker Compose](https://docs.docker.com/guides/frameworks/laravel/production-setup/)

   Set up a production-ready environment for Laravel using Docker Compose.

3. [Laravel Development Setup with Docker Compose](https://docs.docker.com/guides/frameworks/laravel/development-setup/)

   Set up a Laravel development environment using Docker Compose.

4. [Common Questions on Using Laravel with Docker](https://docs.docker.com/guides/frameworks/laravel/common-questions/)

   Find answers to common questions about setting up and managing Laravel environments with Docker Compose, including troubleshooting and best practices.

----
url: https://docs.docker.com/guides/deno/deploy/
----

# Test your Deno deployment

***

Table of contents

***

## [Prerequisites](#prerequisites)

* Complete all the previous sections of this guide, starting with [Containerize a Deno application](https://docs.docker.com/guides/deno/containerize/).
* [Turn on Kubernetes](https://docs.docker.com/desktop/use-desktop/kubernetes/#enable-kubernetes) in Docker Desktop.

## [Overview](#overview)

In this section, you'll learn how to use Docker Desktop to deploy your application to a fully-featured Kubernetes environment on your development machine. This allows you to test and debug your workloads on Kubernetes locally before deploying.

## [Create a Kubernetes YAML file](#create-a-kubernetes-yaml-file)

In your `deno-docker` directory, create a file named `docker-kubernetes.yml`. Open the file in an IDE or text editor and add the following contents. Replace `DOCKER_USERNAME/REPO_NAME` with your Docker username and the name of the repository that you created in [Configure CI/CD for your Deno application](https://docs.docker.com/guides/deno/configure-ci-cd/).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: docker-deno-demo
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: deno-api
  template:
    metadata:
      labels:
        app: deno-api
    spec:
      containers:
       - name: deno-api
         image: DOCKER_USERNAME/REPO_NAME
         imagePullPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: service-entrypoint
  namespace: default
spec:
  type: NodePort
  selector:
    app: deno-api
  ports:
  - port: 8000
    targetPort: 8000
    nodePort: 30001
```

In this Kubernetes YAML file, there are two objects, separated by the `---`:

* A Deployment, describing a scalable group of identical pods. In this case, you'll get just one replica, or copy of your pod. That pod, which is described under `template`, has just one container in it. The container is created from the image built by GitHub Actions in [Configure CI/CD for your Deno application](https://docs.docker.com/guides/deno/configure-ci-cd/).
* A NodePort service, which will route traffic from port 30001 on your host to port 8000 inside the pods it routes to, allowing you to reach your app from the network.

To learn more about Kubernetes objects, see the [Kubernetes documentation](https://kubernetes.io/docs/home/).

## [Deploy and check your application](#deploy-and-check-your-application)

1. In a terminal, navigate to `deno-docker` and deploy your application to Kubernetes.

   ```console
   $ kubectl apply -f docker-kubernetes.yml
   ```

   You should see output that looks like the following, indicating your Kubernetes objects were created successfully.

   ```text
   deployment.apps/docker-deno-demo created
   service/service-entrypoint created
   ```

2. Make sure everything worked by listing your deployments.

   ```console
   $ kubectl get deployments
   ```

   Your deployment should be listed as follows:

   ```shell
   NAME                 READY   UP-TO-DATE   AVAILABLE    AGE
   docker-deno-demo       1/1     1            1           10s
   ```

   This indicates all one of the pods you asked for in your YAML are up and running. Do the same check for your services.

   ```console
   $ kubectl get services
   ```

   You should get output like the following.

   ```shell
   NAME                 TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
   kubernetes           ClusterIP   10.96.0.1        <none>        443/TCP          88m
   service-entrypoint   NodePort    10.105.145.223   <none>        8000:30001/TCP   83s
   ```

   In addition to the default `kubernetes` service, you can see your `service-entrypoint` service, accepting traffic on port 30001/TCP.

3. In a browser, visit the following address. You should see the message `{"Status" : "OK"}`.

   ```console
   http://localhost:30001/
   ```

4. Run the following command to tear down your application.

   ```console
   $ kubectl delete -f docker-kubernetes.yml
   ```

## [Summary](#summary)

In this section, you learned how to use Docker Desktop to deploy your Deno application to a fully-featured Kubernetes environment on your development machine.

Related information:

* [Kubernetes documentation](https://kubernetes.io/docs/home/)
* [Deploy on Kubernetes with Docker Desktop](https://docs.docker.com/desktop/use-desktop/kubernetes/)
* [Swarm mode overview](https://docs.docker.com/engine/swarm/)

----
url: https://docs.docker.com/engine/release-notes/17.06/
----

# Docker Engine 17.06 release notes

***

Table of contents

***

## [17.06.2-ce](#17062-ce)

2017-09-05

### [Client](#client)

* Enable TCP keepalive in the client to prevent loss of connection [docker/cli#415](https://github.com/docker/cli/pull/415)

### [Runtime](#runtime)

* Devmapper: ensure UdevWait is called after calls to setCookie [moby/moby#33732](https://github.com/moby/moby/pull/33732)
* Aufs: ensure diff layers are correctly removed to prevent leftover files from using up storage [moby/moby#34587](https://github.com/moby/moby/pull/34587)

### [Swarm mode](#swarm-mode)

* Ignore PullOptions for running tasks [docker/swarmkit#2351](https://github.com/docker/swarmkit/pull/2351)

## [17.06.1-ce](#17061-ce)

2017-08-15

### [Builder](#builder)

* Fix a regression, where `ADD` from remote URL's extracted archives [#89](https://github.com/docker/docker-ce/pull/89)
* Fix handling of remote "git@" notation [#100](https://github.com/docker/docker-ce/pull/100)
* Fix copy `--from` conflict with force pull [#86](https://github.com/docker/docker-ce/pull/86)

### [Client](#client-1)

* Make pruning volumes optional when running `docker system prune`, and add a `--volumes` flag [#109](https://github.com/docker/docker-ce/pull/109)
* Show progress of replicated tasks before they are assigned [#97](https://github.com/docker/docker-ce/pull/97)
* Fix `docker wait` hanging if the container does not exist [#106](https://github.com/docker/docker-ce/pull/106)
* If `docker swarm ca` is called without the `--rotate` flag, warn if other flags are passed [#110](https://github.com/docker/docker-ce/pull/110)
* Fix API version negotiation not working if the daemon returns an error [#115](https://github.com/docker/docker-ce/pull/115)
* Print an error if "until" filter is combined with "--volumes" on system prune [#154](https://github.com/docker/docker-ce/pull/154)

### [Logging](#logging)

* Fix stderr logging for `journald` and `syslog` [#95](https://github.com/docker/docker-ce/pull/95)
* Fix log readers can block writes indefinitely [#98](https://github.com/docker/docker-ce/pull/98)
* Fix `awslogs` driver repeating last event [#151](https://github.com/docker/docker-ce/pull/151)

### [Networking](#networking)

* Fix issue with driver options not received by network drivers [#127](https://github.com/docker/docker-ce/pull/127)

### [Plugins](#plugins)

* Make plugin removes more resilient to failure [#91](https://github.com/docker/docker-ce/pull/91)

### [Runtime](#runtime-1)

* Prevent a `goroutine` leak when `healthcheck` gets stopped [#90](https://github.com/docker/docker-ce/pull/90)
* Do not error on relabel when relabel not supported [#92](https://github.com/docker/docker-ce/pull/92)
* Limit max backoff delay to 2 seconds for GRPC connection [#94](https://github.com/docker/docker-ce/pull/94)
* Fix issue preventing containers to run when memory cgroup was specified due to bug in certain kernels [#102](https://github.com/docker/docker-ce/pull/102)
* Fix container not responding to SIGKILL when paused [#102](https://github.com/docker/docker-ce/pull/102)
* Improve error message if an image for an incompatible OS is loaded [#108](https://github.com/docker/docker-ce/pull/108)
* Fix a handle leak in `go-winio` [#112](https://github.com/docker/docker-ce/pull/112)
* Fix issue upon upgrade, preventing docker from showing running containers when `--live-restore` is enabled [#117](https://github.com/docker/docker-ce/pull/117)
* Fix bug where services using secrets would fail to start on daemons using the `userns-remap` feature [#121](https://github.com/docker/docker-ce/pull/121)
* Fix error handling with `not-exist` errors on remove [#142](https://github.com/docker/docker-ce/pull/142)
* Fix REST API Swagger representation cannot be loaded with SwaggerUI [#156](https://github.com/docker/docker-ce/pull/156)

### [Security](#security)

* Redact secret data on secret creation [#99](https://github.com/docker/docker-ce/pull/99)

### [Swarm mode](#swarm-mode-1)

* Do not add duplicate platform information to service spec [#107](https://github.com/docker/docker-ce/pull/107)
* Cluster update and memory issue fixes [#114](https://github.com/docker/docker-ce/pull/114)
* Changing get network request to return predefined network in swarm [#150](https://github.com/docker/docker-ce/pull/150)

## [17.06.0-ce](#17060-ce)

2017-06-28

> Note
>
> of the `ADD` instruction of Dockerfile when referencing a remote `.tar.gz` file. The issue will be fixed in Docker 17.06.1.

> Note
>
> for IBM Z using the s390x architecture.

> Note
>
> registries. If you require interaction with registries that have not yet migrated to the v2 protocol, set the `--disable-legacy-registry=false` daemon option. Interaction with v1 registries will be removed in Docker 17.12.

### [Builder](#builder-1)

* Add `--iidfile` option to docker build. It allows specifying a location where to save the resulting image ID
* Allow specifying any remote ref in git checkout URLs [#32502](https://github.com/moby/moby/pull/32502)

### [Client](#client-2)

* Add `--format` option to `docker stack ls` [#31557](https://github.com/moby/moby/pull/31557)
* Add support for labels in compose initiated builds [#32632](https://github.com/moby/moby/pull/32632) [#32972](https://github.com/moby/moby/pull/32972)
* Add `--format` option to `docker history` [#30962](https://github.com/moby/moby/pull/30962)
* Add `--format` option to `docker system df` [#31482](https://github.com/moby/moby/pull/31482)
* Allow specifying Nameservers and Search Domains in stack files [#32059](https://github.com/moby/moby/pull/32059)
* Add support for `read_only` service to `docker stack deploy` [#docker/cli/73](https://github.com/docker/cli/pull/73)

- Display Swarm cluster and node TLS information [#docker/cli/44](https://github.com/docker/cli/pull/44)

* Add support for placement preference to `docker stack deploy` [#docker/cli/35](https://github.com/docker/cli/pull/35)
* Add new `ca` subcommand to `docker swarm` to allow managing a swarm CA [#docker/cli/48](https://github.com/docker/cli/pull/48)
* Add credential-spec to compose [#docker/cli/71](https://github.com/docker/cli/pull/71)
* Add support for csv format options to `--network` and `--network-add` [#docker/cli/62](https://github.com/docker/cli/pull/62) [#33130](https://github.com/moby/moby/pull/33130)

- Fix stack compose bind-mount volumes on Windows [#docker/cli/136](https://github.com/docker/cli/pull/136)
- Correctly handle a Docker daemon without registry info [#docker/cli/126](https://github.com/docker/cli/pull/126)

* Allow `--detach` and `--quiet` flags when using --rollback [#docker/cli/144](https://github.com/docker/cli/pull/144)
* Remove deprecated `--email` flag from `docker login` [#docker/cli/143](https://github.com/docker/cli/pull/143)

- Adjusted `docker stats` memory output [#docker/cli/80](https://github.com/docker/cli/pull/80)

### [Distribution](#distribution)

* Select digest over tag when both are provided during a pull [#33214](https://github.com/moby/moby/pull/33214)

### [Logging](#logging-1)

* Add monitored resource type metadata for GCP logging driver [#32930](https://github.com/moby/moby/pull/32930)
* Add multiline processing to the AWS CloudWatch logs driver [#30891](https://github.com/moby/moby/pull/30891)

### [Networking](#networking-1)

* Add Support swarm-mode services with node-local networks such as macvlan, ipvlan, bridge, host [#32981](https://github.com/moby/moby/pull/32981)
* Pass driver-options to network drivers on service creation [#32981](https://github.com/moby/moby/pull/33130)
* Isolate Swarm Control-plane traffic from Application data traffic using --data-path-addr [#32717](https://github.com/moby/moby/pull/32717)

- Several improvements to Service Discovery [#docker/libnetwork/1796](https://github.com/docker/libnetwork/pull/1796)

### [Packaging](#packaging)

* Rely on `container-selinux` on Centos/Fedora/RHEL when available [#32437](https://github.com/moby/moby/pull/32437)

### [Runtime](#runtime-2)

* Add build & engine info prometheus metrics [#32792](https://github.com/moby/moby/pull/32792)

- Update containerd to d24f39e203aa6be4944f06dd0fe38a618a36c764 [#33007](https://github.com/moby/moby/pull/33007)
- Update runc to 992a5be178a62e026f4069f443c6164912adbf09 [#33007](https://github.com/moby/moby/pull/33007)

* Add option to auto-configure blkdev for devmapper [#31104](https://github.com/moby/moby/pull/31104)
* Add log driver list to `docker info` [#32540](https://github.com/moby/moby/pull/32540)
* Add API endpoint to allow retrieving an image manifest [#32061](https://github.com/moby/moby/pull/32061)

- Do not remove container from memory on error with `forceremove` [#31012](https://github.com/moby/moby/pull/31012)

* Add support for metric plugins [#32874](https://github.com/moby/moby/pull/32874)

- Return an error when an invalid filter is given to `prune` commands [#33023](https://github.com/moby/moby/pull/33023)

* Add daemon option to allow pushing foreign layers [#33151](https://github.com/moby/moby/pull/33151)

- Fix an issue preventing containerd to be restarted after it died [#32986](https://github.com/moby/moby/pull/32986)

* Add cluster events to Docker event stream. [#32421](https://github.com/moby/moby/pull/32421)
* Add support for DNS search on windows [#33311](https://github.com/moby/moby/pull/33311)

- Upgrade to Go 1.8.3 [#33387](https://github.com/moby/moby/pull/33387)

* Prevent a containerd crash when journald is restarted [#containerd/930](https://github.com/containerd/containerd/pull/930)
* Fix healthcheck failures due to invalid environment variables [#33249](https://github.com/moby/moby/pull/33249)
* Prevent a directory to be created in lieu of the daemon socket when a container mounting it is to be restarted during a shutdown [#30348](https://github.com/moby/moby/pull/33330)
* Prevent a container to be restarted upon stop if its stop signal is set to `SIGKILL` [#33335](https://github.com/moby/moby/pull/33335)
* Ensure log drivers get passed the same filename to both StartLogging and StopLogging endpoints [#33583](https://github.com/moby/moby/pull/33583)
* Remove daemon data structure dump on `SIGUSR1` to avoid a panic [#33598](https://github.com/moby/moby/pull/33598)

### [Security](#security-1)

* Allow personality with UNAME26 bit set in default seccomp profile [#32965](https://github.com/moby/moby/pull/32965)

### [Swarm Mode](#swarm-mode-2)

* Add an option to allow specifying a different interface for the data traffic (as opposed to control traffic) [#32717](https://github.com/moby/moby/pull/32717)

- Allow specifying a secret location within the container [#32571](https://github.com/moby/moby/pull/32571)

* Add support for secrets on Windows [#32208](https://github.com/moby/moby/pull/32208)
* Add TLS Info to swarm info and node info endpoint [#32875](https://github.com/moby/moby/pull/32875)
* Add support for services to carry arbitrary config objects [#32336](https://github.com/moby/moby/pull/32336), [#docker/cli/45](https://github.com/docker/cli/pull/45),[#33169](https://github.com/moby/moby/pull/33169)
* Add API to rotate swarm CA certificate [#32993](https://github.com/moby/moby/pull/32993)

- Service digest pining is now handled client side [#32388](https://github.com/moby/moby/pull/32388), [#33239](https://github.com/moby/moby/pull/33239)

* Placement now also take platform in account [#33144](https://github.com/moby/moby/pull/33144)

- Fix possible hang when joining fails [#docker-ce/19](https://github.com/docker/docker-ce/pull/19)
- Fix an issue preventing external CA to be accepted [#33341](https://github.com/moby/moby/pull/33341)
- Fix possible orchestration panic in mixed version clusters [#swarmkit/2233](https://github.com/docker/swarmkit/pull/2233)
- Avoid assigning duplicate IPs during initialization [#swarmkit/2237](https://github.com/docker/swarmkit/pull/2237)

### [Deprecation](#deprecation)

* Disable legacy registry (v1) by default [#33629](https://github.com/moby/moby/pull/33629)

----
url: https://docs.docker.com/compose/bridge/usage/
----

# Use the default Compose Bridge transformation

***

Table of contents

***

Requires: Docker Desktop 4.43.0 and later

Compose Bridge includes a built-in transformation that automatically converts your Compose configuration into a set of Kubernetes manifests.

Based on your `compose.yaml` file, it produces:

* A [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) so all your resources are isolated and don't conflict with resources from other deployments.
* A [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) with an entry for each and every [config](https://docs.docker.com/reference/compose-file/configs/) resource in your Compose application.
* [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) for application services. This ensures that the specified number of instances of your application are maintained in the Kubernetes cluster.
* [Services](https://kubernetes.io/docs/concepts/services-networking/service/) for ports exposed by your services, used for service-to-service communication.
* [Services](https://kubernetes.io/docs/concepts/services-networking/service/) for ports published by your services, with type `LoadBalancer` so that Docker Desktop will also expose the same port on the host.
* [Network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) to replicate the networking topology defined in your `compose.yaml` file.
* [PersistentVolumeClaims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for your volumes, using `hostpath` storage class so that Docker Desktop manages volume creation.
* [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) with your secret encoded. This is designed for local use in a testing environment.

It also supplies a Kustomize overlay dedicated to Docker Desktop with:

* `Loadbalancer` for services which need to expose ports on host.
* A `PersistentVolumeClaim` to use the Docker Desktop storage provisioner `desktop-storage-provisioner` to handle volume provisioning more effectively.
* A `Kustomization.yaml` file to link all the resources together.

If your Compose file defines a `models` section for a service, Compose Bridge automatically configures your deployment so your service can locate and use its models via Docker Model Runner.

For each declared model, the transformation injects two environment variables:

* `<MODELNAME>_URL`: The endpoint for Docker Model Runner serving that model
* `<MODELNAME>_MODEL`: The model’s name or identifier

You can optionally customize these variable names using `endpoint_var` and `model_var`.

The default transformation generates two different overlays - one for Docker Desktop whilst using a local instance of Docker Model Runner, and a `model-runner` overlay with all the relevant Kubernetes resources to deploy Docker Model Runner in a pod.

| Environment    | Endpoint                                        |
| -------------- | ----------------------------------------------- |
| Docker Desktop | `http://host.docker.internal:12434/engines/v1/` |
| Kubernetes     | `http://model-runner/engines/v1/`               |

For more details, see [Use Model Runner](https://docs.docker.com/compose/bridge/use-model-runner/).

## [Use the default Compose Bridge transformation](#use-the-default-compose-bridge-transformation)

To convert your Compose file using the default transformation:

```console
$ docker compose bridge convert
```

Compose looks for a `compose.yaml` file inside the current directory and generates Kubernetes manifests.

Example output:

```console
$ docker compose -f compose.yaml bridge convert
Kubernetes resource backend-deployment.yaml created
Kubernetes resource frontend-deployment.yaml created
Kubernetes resource backend-expose.yaml created
Kubernetes resource frontend-expose.yaml created
Kubernetes resource 0-my-project-namespace.yaml created
Kubernetes resource default-network-policy.yaml created
Kubernetes resource backend-service.yaml created
Kubernetes resource frontend-service.yaml created
Kubernetes resource kustomization.yaml created
Kubernetes resource backend-deployment.yaml created
Kubernetes resource frontend-deployment.yaml created
Kubernetes resource backend-service.yaml created
Kubernetes resource frontend-service.yaml created
Kubernetes resource kustomization.yaml created
Kubernetes resource model-runner-configmap.yaml created
Kubernetes resource model-runner-deployment.yaml created
Kubernetes resource model-runner-service.yaml created
Kubernetes resource model-runner-volume-claim.yaml created
Kubernetes resource kustomization.yaml created
```

All generated files are stored in the `/out` directory in your project.

## [Deploy the generated manifests](#deploy-the-generated-manifests)

> Important
>
> Before you deploy your Compose Bridge transformations, make sure you have [enabled Kubernetes](https://docs.docker.com/desktop/settings-and-maintenance/settings/#kubernetes) in Docker Desktop.

Once the manifests are generated, deploy them to your local Kubernetes cluster:

```console
$ kubectl apply -k out/overlays/desktop/
```

> Tip
>
> You can convert and deploy your Compose project to a Kubernetes cluster from the Compose file viewer.
>
> Make sure you are signed in to your Docker account, navigate to your container in the **Containers** view, and in the top-right corner select **View configurations** and then **Convert and Deploy to Kubernetes**.

## [Additional commands](#additional-commands)

Convert a `compose.yaml` file located in another directory:

```console
$ docker compose -f <path-to-file>/compose.yaml bridge convert
```

To see all available flags, run:

```console
$ docker compose bridge convert --help
```

## [What's next?](#whats-next)

* [Explore how you can customize Compose Bridge](https://docs.docker.com/compose/bridge/customize/)
* [Use Model Runner](https://docs.docker.com/compose/bridge/use-model-runner/).

----
url: https://docs.docker.com/reference/cli/docker/model/install-runner/
----

# docker model install-runner

***

| Description | Install Docker Model Runner (Docker Engine only) |
| ----------- | ------------------------------------------------ |
| Usage       | `docker model install-runner`                    |

## [Description](#description)

This command runs implicitly when a docker model command is executed. You can run this command explicitly to add a new configuration.

## [Options](#options)

| Option           | Default     | Description                                                                                             |
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| `--backend`      |             | Specify backend (llama.cpp\|vllm\|diffusers). Default: llama.cpp                                        |
| `--debug`        |             | Enable debug logging                                                                                    |
| `--do-not-track` |             | Do not track models usage in Docker Model Runner                                                        |
| `--gpu`          | `auto`      | Specify GPU support (none\|auto\|cuda\|rocm\|musa\|cann)                                                |
| `--host`         | `127.0.0.1` | Host address to bind Docker Model Runner                                                                |
| `--port`         |             | Docker container port for Docker Model Runner (default: 12434 for Docker Engine, 12435 for Cloud mode)  |
| `--proxy-cert`   |             | Path to a CA certificate file for proxy SSL inspection                                                  |
| `--tls`          |             | Enable TLS/HTTPS for Docker Model Runner API                                                            |
| `--tls-cert`     |             | Path to TLS certificate file (auto-generated if not provided)                                           |
| `--tls-key`      |             | Path to TLS private key file (auto-generated if not provided)                                           |
| `--tls-port`     |             | TLS port for Docker Model Runner (default: 12444 for Docker Engine, 12445 for Cloud mode)               |

----
url: https://docs.docker.com/reference/cli/docker/plugin/inspect/
----

# docker plugin inspect

***

| Description | Display detailed information on one or more plugins  |
| ----------- | ---------------------------------------------------- |
| Usage       | `docker plugin inspect [OPTIONS] PLUGIN [PLUGIN...]` |

## [Description](#description)

Returns information about a plugin. By default, this command renders all results in a JSON array.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                             |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --format`](#format) |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |

## [Examples](#examples)

### [Inspect a plugin](#inspect-a-plugin)

The following example inspects the `tiborvass/sample-volume-plugin` plugin:

```console
$ docker plugin inspect tiborvass/sample-volume-plugin:latest
```

Output is in JSON format (output below is formatted for readability):

```json
{
  "Id": "8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21",
  "Name": "tiborvass/sample-volume-plugin:latest",
  "PluginReference": "tiborvas/sample-volume-plugin:latest",
  "Enabled": true,
  "Config": {
    "Mounts": [
      {
        "Name": "",
        "Description": "",
        "Settable": null,
        "Source": "/data",
        "Destination": "/data",
        "Type": "bind",
        "Options": [
          "shared",
          "rbind"
        ]
      },
      {
        "Name": "",
        "Description": "",
        "Settable": null,
        "Source": null,
        "Destination": "/foobar",
        "Type": "tmpfs",
        "Options": null
      }
    ],
    "Env": [
      "DEBUG=1"
    ],
    "Args": null,
    "Devices": null
  },
  "Manifest": {
    "ManifestVersion": "v0",
    "Description": "A test plugin for Docker",
    "Documentation": "/engine/extend/plugins/",
    "Interface": {
      "Types": [
        "docker.volumedriver/1.0"
      ],
      "Socket": "plugins.sock"
    },
    "Entrypoint": [
      "plugin-sample-volume-plugin",
      "/data"
    ],
    "Workdir": "",
    "User": {
    },
    "Network": {
      "Type": "host"
    },
    "Capabilities": null,
    "Mounts": [
      {
        "Name": "",
        "Description": "",
        "Settable": null,
        "Source": "/data",
        "Destination": "/data",
        "Type": "bind",
        "Options": [
          "shared",
          "rbind"
        ]
      },
      {
        "Name": "",
        "Description": "",
        "Settable": null,
        "Source": null,
        "Destination": "/foobar",
        "Type": "tmpfs",
        "Options": null
      }
    ],
    "Devices": [
      {
        "Name": "device",
        "Description": "a host device to mount",
        "Settable": null,
        "Path": "/dev/cpu_dma_latency"
      }
    ],
    "Env": [
      {
        "Name": "DEBUG",
        "Description": "If set, prints debug messages",
        "Settable": null,
        "Value": "1"
      }
    ],
    "Args": {
      "Name": "args",
      "Description": "command line arguments",
      "Settable": null,
      "Value": [

      ]
    }
  }
}
```

### [Format the output (--format)](#format)

```console
$ docker plugin inspect -f '{{.Id}}' tiborvass/sample-volume-plugin:latest

8c74c978c434745c3ade82f1bc0acf38d04990eaf494fa507c16d9f1daa99c21
```

----
url: https://docs.docker.com/reference/cli/docker/swarm/join-token/
----

# docker swarm join-token

***

| Description | Manage join tokens                                    |
| ----------- | ----------------------------------------------------- |
| Usage       | `docker swarm join-token [OPTIONS] (worker\|manager)` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Join tokens are secrets that allow a node to join the swarm. There are two different join tokens available, one for the worker role and one for the manager role. You pass the token using the `--token` flag when you run [swarm join](/reference/cli/docker/swarm/join/). Nodes use the join token only when they join the swarm.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                  | Default | Description        |
| ----------------------- | ------- | ------------------ |
| [`-q, --quiet`](#quiet) |         | Only display token |
| [`--rotate`](#rotate)   |         | Rotate join token  |

## [Examples](#examples)

You can view or rotate the join tokens using `swarm join-token`.

As a convenience, you can pass `worker` or `manager` as an argument to `join-token` to print the full `docker swarm join` command to join a new node to the swarm:

```console
$ docker swarm join-token worker

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233... \
    172.17.0.2:2377

$ docker swarm join-token manager

To add a manager to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233... \
    172.17.0.2:2377
```

Use the `--rotate` flag to generate a new join token for the specified role:

```console
$ docker swarm join-token --rotate worker

Successfully rotated worker join token.

To add a worker to this swarm, run the following command:

    docker swarm join \
    --token SWMTKN-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233... \
    172.17.0.2:2377
```

After using `--rotate`, only the new token will be valid for joining with the specified role.

The `-q` (or `--quiet`) flag only prints the token:

```console
$ docker swarm join-token -q worker

SWMTKN-1-aabbccdd00112233aabbccdd00112233aabbccdd00112233aa-aabbccdd00112233...
```

### [`--rotate`](#rotate)

Because tokens allow new nodes to join the swarm, you should keep them secret. Be particularly careful with manager tokens since they allow new manager nodes to join the swarm. A rogue manager has the potential to disrupt the operation of your swarm.

Rotate your swarm's join token if a token gets checked-in to version control, stolen, or a node is compromised. You may also want to periodically rotate the token to ensure any unknown token leaks do not allow a rogue node to join the swarm.

To rotate the join token and print the newly generated token, run `docker swarm join-token --rotate` and pass the role: `manager` or `worker`.

Rotating a join-token means that no new nodes will be able to join the swarm using the old token. Rotation does not affect existing nodes in the swarm because the join token is only used for authorizing new nodes joining the swarm.

### [`--quiet`](#quiet)

Only print the token. Do not print a complete command for joining.

----
url: https://docs.docker.com/reference/api/engine/version/v1.43/
----

# Docker Engine API v1.43 reference

Reference documentation and Swagger (OpenAPI) specification for the Docker Engine API.

* [Open Markdown](https://docs.docker.com/reference/api/engine/version/v1.43.md)
* [Download OpenAPI specification](https://docs.docker.com/reference/api/engine/version/v1.43.yaml)

# Docker Engine API (1.43)

Download OpenAPI specification:[Download](https://docs.docker.com/reference/api/engine/version/v1.43.yaml)

The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.

Most of the client's commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.

## [](#section/Errors)Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

```
{
  "message": "page not found"
}
```

## [](#section/Versioning)Versioning

The API is usually changed in each release, so API calls are versioned to ensure that clients don't break. To lock to a specific version of the API, you prefix the URL with its version, for example, call `/v1.30/info` to use the v1.30 version of the `/info` endpoint. If the API version specified in the URL is not supported by the daemon, a HTTP `400 Bad Request` error message is returned.

If you omit the version-prefix, the current version of the API (v1.43) is used. For example, calling `/info` is the same as calling `/v1.43/info`. Using the API without a version-prefix is deprecated and will be removed in a future release.

Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.

The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer daemons.

## [](#section/Authentication)Authentication

Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a [base64url encoded](https://tools.ietf.org/html/rfc4648#section-5) (JSON) string with the following structure:

```
{
  "username": "string",
  "password": "string",
  "serveraddress": "string"
}
```

The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.

If you have already got an identity token from the [`/auth` endpoint](#operation/SystemAuth), you can just pass this instead of credentials:

```
{
  "identitytoken": "9cbaf023786cd7..."
}
```

## [](#tag/Container)Containers

Create and manage containers.

## [](#tag/Container/operation/ContainerList)List containers

Returns a list of containers. For details on the format, see the [inspect endpoint](#operation/ContainerInspect).

Note that it uses a different, smaller representation of a container than inspecting a single container. For example, the list of linked containers is not propagated .

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| all     | booleanDefault: falseReturn all containers. By default, only running containers are shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| limit   | integerReturn this number of most recently created containers, including non-running ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| size    | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters | stringFilters to process on the container list, encoded as JSON (a `map[string][]string`). For example, `{"status": ["paused"]}` will only return paused containers.Available filters:- `ancestor`=(`<image-name>[:<tag>]`, `<image id>`, or `<image@digest>`)

/v1.43/containers/json

|          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name     | string^/?\[a-zA-Z0-9]\[a-zA-Z0-9\_.-]+$Assign the specified name to the container. Must match `/?[a-zA-Z0-9][a-zA-Z0-9_.-]+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| platform | stringDefault: ""Platform in the format `os[/arch[/variant]]` used for image lookup.When specified, the daemon checks if the requested image is present in the local image cache with the given OS and Architecture, and otherwise returns a `404` status.If the option is not set, the host's native OS and Architecture are used to look up the image in the image cache. However, if no platform is passed and the given image does exist in the local image cache, but its OS or architecture does not match, the container is created with the available image, and a warning is added to the `Warnings` field in the response, for example;```
WARNING: The requested image's platform (linux/arm64/v8) does not
         match the detected host platform (linux/amd64) and no
         specific platform was requested
``` |

##### Request Body schema:application/jsonrequired

Container to create

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.                                                                                                                                                                                                                                                           |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |
|                 | object (HostConfig)Container configuration that depends on the host we are running on                                                                                                                                                                                                                 |
|                 | object (NetworkingConfig)NetworkingConfig represents the container's networking configuration for each of its interfaces. It is used for the networking configs specified in the `docker create` and `docker network connect` commands.                                                               |

### Responses

/v1.43/containers/create

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": "",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": { }
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"HostConfig": {
"Binds": [
"/tmp:/tmp"
],
"Links": [
"redis3:redis"
],
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"NanoCpus": 500000,
"CpuPercent": 80,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpuQuota": 50000,
"CpusetCpus": "0,1",
"CpusetMems": "0,1",
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 300,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"MemorySwappiness": 60,
"OomKillDisable": false,
"OomScoreAdj": 500,
"PidMode": "",
"PidsLimit": 0,
"PortBindings": {
"22/tcp": [
{
"HostPort": "11022"
}
]
},
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": [
"8.8.8.8"
],
"DnsOptions": [
""
],
"DnsSearch": [
""
],
"VolumesFrom": [
"parent",
"other:ro"
],
"CapAdd": [
"NET_ADMIN"
],
"CapDrop": [
"MKNOD"
],
"GroupAdd": [
"newgroup"
],
"RestartPolicy": {
"Name": "",
"MaximumRetryCount": 0
},
"AutoRemove": true,
"NetworkMode": "bridge",
"Devices": [ ],
"Ulimits": [
{ }
],
"LogConfig": {
"Type": "json-file",
"Config": { }
},
"SecurityOpt": [ ],
"StorageOpt": { },
"CgroupParent": "",
"VolumeDriver": "",
"ShmSize": 67108864
},
"NetworkingConfig": {
"EndpointsConfig": {
"isolated_nw": {
"IPAMConfig": {
"IPv4Address": "172.20.30.33",
"IPv6Address": "2001:db8:abcd::3033",
"LinkLocalIPs": [
"169.254.34.68",
"fe80::3468"
]
},
"Links": [
"container_1",
"container_2"
],
"Aliases": [
"server_x",
"server_y"
]
}
}
}
}`

### Response samples

* 201
* 400
* 404
* 409
* 500

Content type

application/json

`{
"Id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Warnings": [ ]
}`

## [](#tag/Container/operation/ContainerInspect)Inspect a container

Return low-level information about a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|      |                                                                                       |
| ---- | ------------------------------------------------------------------------------------- |
| size | booleanDefault: falseReturn the size of container as fields `SizeRw` and `SizeRootFs` |

### Responses

/v1.43/containers/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"AppArmorProfile": "",
"Args": [
"-c",
"exit 9"
],
"Config": {
"AttachStderr": true,
"AttachStdin": false,
"AttachStdout": true,
"Cmd": [
"/bin/sh",
"-c",
"exit 9"
],
"Domainname": "",
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Healthcheck": {
"Test": [
"CMD-SHELL",
"exit 0"
]
},
"Hostname": "ba033ac44011",
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"MacAddress": "",
"NetworkDisabled": false,
"OpenStdin": false,
"StdinOnce": false,
"Tty": false,
"User": "",
"Volumes": {
"/volumes/data": { }
},
"WorkingDir": "",
"StopSignal": "SIGTERM",
"StopTimeout": 10
},
"Created": "2015-01-06T15:47:31.485331387Z",
"Driver": "overlay2",
"ExecIDs": [
"b35395de42bc8abd327f9dd65d913b9ba28c74d2f0734eeeae84fa1c616a0fca",
"3fc1232e5cd20c8de182ed81178503dc6437f4e7ef12b52cc5e8de020652f1c4"
],
"HostConfig": {
"MaximumIOps": 0,
"MaximumIOBps": 0,
"BlkioWeight": 0,
"BlkioWeightDevice": [
{ }
],
"BlkioDeviceReadBps": [
{ }
],
"BlkioDeviceWriteBps": [
{ }
],
"BlkioDeviceReadIOps": [
{ }
],
"BlkioDeviceWriteIOps": [
{ }
],
"ContainerIDFile": "",
"CpusetCpus": "",
"CpusetMems": "",
"CpuPercent": 80,
"CpuShares": 0,
"CpuPeriod": 100000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"Devices": [ ],
"DeviceRequests": [
{
"Driver": "nvidia",
"Count": -1,
"DeviceIDs"": [
"0",
"1",
"GPU-fef8089b-4820-abfc-e83e-94318197576e"
],
"Capabilities": [ [
"gpu",
"nvidia",
"compute"
]
],
"Options": {
"property1": "string",
"property2": "string"
}
}
],
"IpcMode": "",
"Memory": 0,
"MemorySwap": 0,
"MemoryReservation": 0,
"OomKillDisable": false,
"OomScoreAdj": 500,
"NetworkMode": "bridge",
"PidMode": "",
"PortBindings": { },
"Privileged": false,
"ReadonlyRootfs": false,
"PublishAllPorts": false,
"RestartPolicy": {
"MaximumRetryCount": 2,
"Name": "on-failure"
},
"LogConfig": {
"Type": "json-file"
},
"Sysctls": {
"net.ipv4.ip_forward": "1"
},
"Ulimits": [
{ }
],
"VolumeDriver": "",
"ShmSize": 67108864
},
"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
"MountLabel": "",
"Name": "/boring_euclid",
"NetworkSettings": {
"Bridge": "",
"SandboxID": "",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": 0,
"SandboxKey": "",
"EndpointID": "",
"Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"MacAddress": "",
"Networks": {
"bridge": {
"NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812",
"EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Path": "/bin/sh",
"ProcessLabel": "",
"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
"RestartCount": 1,
"State": {
"Error": "",
"ExitCode": 9,
"FinishedAt": "2015-01-06T15:47:32.080254511Z",
"Health": {
"Status": "healthy",
"FailingStreak": 0,
"Log": [
{
"Start": "2019-12-22T10:59:05.6385933Z",
"End": "2019-12-22T10:59:05.8078452Z",
"ExitCode": 0,
"Output": ""
}
]
},
"OOMKilled": false,
"Dead": false,
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z",
"Status": "running"
},
"Mounts": [
{
"Name": "fac362...80535",
"Source": "/data",
"Destination": "/data",
"Driver": "local",
"Mode": "ro,Z",
"RW": false,
"Propagation": ""
}
]
}`

## [](#tag/Container/operation/ContainerTop)List processes running inside a container

On Unix systems, this is done by running the `ps` command. This endpoint is not supported on Windows.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                       |
| -------- | --------------------------------------------------------------------- |
| ps\_args | stringDefault: "-ef"The arguments to pass to `ps`. For example, `aux` |

### Responses

/v1.43/containers/{id}/top

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Titles": [
"UID",
"PID",
"PPID",
"C",
"STIME",
"TTY",
"TIME",
"CMD"
],
"Processes": [ [
"root",
"13642",
"882",
"0",
"17:03",
"pts/0",
"00:00:00",
"/bin/bash"
], [
"root",
"13735",
"13642",
"0",
"17:06",
"pts/0",
"00:00:00",
"sleep 10"
]
]
}`

## [](#tag/Container/operation/ContainerLogs)Get container logs

Get `stdout` and `stderr` logs from a container.

Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| until      | integerDefault: 0Only return logs before this time, as a UNIX timestamp                                                                    |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.43/containers/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerChanges)Get changes on a container’s filesystem

Returns which files in a container's filesystem have been added, deleted, or modified. The `Kind` of modification can be one of:

* `0`: Modified ("C")
* `1`: Added ("A")
* `2`: Deleted ("D")

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.43/containers/{id}/changes

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]`

## [](#tag/Container/operation/ContainerExport)Export a container

Export the contents of a container as a tarball.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.43/containers/{id}/export

### Response samples

* 404

Content type

application/octet-stream

No sample

## [](#tag/Container/operation/ContainerStats)Get container stats based on resource usage

This endpoint returns a live stream of a container’s resource usage statistics.

The `precpu_stats` is the CPU statistic of the *previous* read, and is used to calculate the CPU usage percentage. It is not an exact copy of the `cpu_stats` field.

If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is nil then for compatibility with older daemons the length of the corresponding `cpu_usage.percpu_usage` array should be used.

On a cgroup v2 host, the following fields are not set

* `blkio_stats`: all fields other than `io_service_bytes_recursive`
* `cpu_stats`: `cpu_usage.percpu_usage`
* `memory_stats`: `max_usage` and `failcnt` Also, `memory_stats.stats` fields are incompatible with cgroup v1.

To calculate the values shown by the `stats` command of the docker cli tool the following formulas can be used:

* used\_memory = `memory_stats.usage - memory_stats.stats.cache` (cgroups v1)
* used\_memory = `memory_stats.usage - memory_stats.stats.inactive_file` (cgroups v2)
* available\_memory = `memory_stats.limit`
* Memory usage % = `(used_memory / available_memory) * 100.0`
* cpu\_delta = `cpu_stats.cpu_usage.total_usage - precpu_stats.cpu_usage.total_usage`
* system\_cpu\_delta = `cpu_stats.system_cpu_usage - precpu_stats.system_cpu_usage`
* number\_cpus = `length(cpu_stats.cpu_usage.percpu_usage)` or `cpu_stats.online_cpus`
* CPU usage % = `(cpu_delta / system_cpu_delta) * number_cpus * 100.0`

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|          |                                                                                                                |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| stream   | booleanDefault: trueStream the output. If false, the stats will be output once and then it will disconnect.    |
| one-shot | booleanDefault: falseOnly get a single stat instead of waiting for 2 cycles. Must be used with `stream=false`. |

### Responses

/v1.43/containers/{id}/stats

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"read": "2015-01-08T22:57:31.547920715Z",
"pids_stats": {
"current": 3
},
"networks": {
"eth0": {
"rx_bytes": 5338,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 36,
"tx_bytes": 648,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 8
},
"eth5": {
"rx_bytes": 4641,
"rx_dropped": 0,
"rx_errors": 0,
"rx_packets": 26,
"tx_bytes": 690,
"tx_dropped": 0,
"tx_errors": 0,
"tx_packets": 9
}
},
"memory_stats": {
"stats": {
"total_pgmajfault": 0,
"cache": 0,
"mapped_file": 0,
"total_inactive_file": 0,
"pgpgout": 414,
"rss": 6537216,
"total_mapped_file": 0,
"writeback": 0,
"unevictable": 0,
"pgpgin": 477,
"total_unevictable": 0,
"pgmajfault": 0,
"total_rss": 6537216,
"total_rss_huge": 6291456,
"total_writeback": 0,
"total_inactive_anon": 0,
"rss_huge": 6291456,
"hierarchical_memory_limit": 67108864,
"total_pgfault": 964,
"total_active_file": 0,
"active_anon": 6537216,
"total_active_anon": 6537216,
"total_pgpgout": 414,
"total_cache": 0,
"inactive_anon": 0,
"active_file": 0,
"pgfault": 964,
"inactive_file": 0,
"total_pgpgin": 477
},
"max_usage": 6651904,
"usage": 6537216,
"failcnt": 0,
"limit": 67108864
},
"blkio_stats": { },
"cpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24472255,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100215355,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 739306590000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
},
"precpu_stats": {
"cpu_usage": {
"percpu_usage": [
8646879,
24350896,
36438778,
30657443
],
"usage_in_usermode": 50000000,
"total_usage": 100093996,
"usage_in_kernelmode": 30000000
},
"system_cpu_usage": 9492140000000,
"online_cpus": 4,
"throttling_data": {
"periods": 0,
"throttled_periods": 0,
"throttled_time": 0
}
}
}`

## [](#tag/Container/operation/ContainerResize)Resize a container TTY

Resize the TTY for a container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.43/containers/{id}/resize

### Response samples

* 404

Content type

text/plain

No sample

## [](#tag/Container/operation/ContainerStart)Start a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |

### Responses

/v1.43/containers/{id}/start

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerStop)Stop a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.43/containers/{id}/stop

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerRestart)Restart a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                |
| ------ | ------------------------------------------------------------------------------ |
| signal | stringSignal to send to the container as an integer or string (e.g. `SIGINT`). |
| t      | integerNumber of seconds to wait before killing the container                  |

### Responses

/v1.43/containers/{id}/restart

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerKill)Kill a container

Send a POSIX signal to a container, defaulting to killing to the container.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|        |                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------ |
| signal | stringDefault: "SIGKILL"Signal to send to the container as an integer or string (e.g. `SIGINT`). |

### Responses

/v1.43/containers/{id}/kill

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUpdate)Update a container

Change various configuration options of a container without having to recreate it.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### Request Body schema: application/jsonrequired

|                    |                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CpuShares          | integerAn integer value representing this container's relative CPU weight versus other containers.                                                                                                                                                     |
| Memory             | integer \<int64>Default: 0Memory limit in bytes.                                                                                                                                                                                                       |
| CgroupParent       | stringPath to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.               |
| BlkioWeight        | integer \[ 0 .. 1000 ]Block IO weight (relative weight).                                                                                                                                                                                               |
|                    | Array of objectsBlock IO weight (relative device weight) in the form:```
[{"Path": "device_path", "Weight": weight}]
```                                                                                                                               |
|                    | Array of objects (ThrottleDevice)Limit read rate (bytes per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                         |
|                    | Array of objects (ThrottleDevice)Limit write rate (bytes per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                          |
|                    | Array of objects (ThrottleDevice)Limit read rate (IO per second) from a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                            |
|                    | Array of objects (ThrottleDevice)Limit write rate (IO per second) to a device, in the form:```
[{"Path": "device_path", "Rate": rate}]
```                                                                                                             |
| CpuPeriod          | integer \<int64>The length of a CPU period in microseconds.                                                                                                                                                                                            |
| CpuQuota           | integer \<int64>Microseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                   |
| CpuRealtimePeriod  | integer \<int64>The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                       |
| CpuRealtimeRuntime | integer \<int64>The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks.                                                                                                                      |
| CpusetCpus         | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                           |
| CpusetMems         | stringMemory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.                                                                                                                                                      |
|                    | Array of objects (DeviceMapping)A list of devices to add to the container.                                                                                                                                                                             |
| DeviceCgroupRules  | Array of stringsa list of cgroup rules to apply to the container                                                                                                                                                                                       |
|                    | Array of objects (DeviceRequest)A list of requests for devices to be sent to device drivers.                                                                                                                                                           |
| KernelMemoryTCP    | integer \<int64>Hard limit for kernel TCP buffer memory (in bytes). Depending on the OCI runtime in use, this option may be ignored. It is no longer supported by the default (runc) runtime.This field is omitted when empty.                         |
| MemoryReservation  | integer \<int64>Memory soft limit in bytes.                                                                                                                                                                                                            |
| MemorySwap         | integer \<int64>Total memory limit (memory + swap). Set as `-1` to enable unlimited swap.                                                                                                                                                              |
| MemorySwappiness   | integer \<int64> \[ 0 .. 100 ]Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.                                                                                                                                     |
| NanoCpus           | integer \<int64>CPU quota in units of 10-9 CPUs.                                                                                                                                                                                                       |
| OomKillDisable     | booleanDisable OOM Killer for the container.                                                                                                                                                                                                           |
| Init               | boolean or nullRun an init inside the container that forwards signals and reaps processes. This field is omitted if empty, and the default (as configured on the daemon) is used.                                                                      |
| PidsLimit          | integer or null \<int64>Tune a container's PIDs limit. Set `0` or `-1` for unlimited, or `null` to not change.                                                                                                                                         |
|                    | Array of objectsA list of resource limits to set in the container. For example:```
{"Name": "nofile", "Soft": 1024, "Hard": 2048}
```                                                                                                                  |
| CpuCount           | integer \<int64>The number of usable CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.                   |
| CpuPercent         | integer \<int64>The usable percentage of the available CPUs (Windows only).On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last. |
| IOMaximumIOps      | integer \<int64>Maximum IOps for the container system drive (Windows only)                                                                                                                                                                             |
| IOMaximumBandwidth | integer \<int64>Maximum IO in bytes per second for the container system drive (Windows only).                                                                                                                                                          |
|                    | object (RestartPolicy)The behavior to apply when the container exits. The default is not to restart.An ever increasing delay (double the previous delay, starting at 100ms) is added before each restart to prevent flooding the server.               |

### Responses

/v1.43/containers/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"BlkioWeight": 300,
"CpuShares": 512,
"CpuPeriod": 100000,
"CpuQuota": 50000,
"CpuRealtimePeriod": 1000000,
"CpuRealtimeRuntime": 10000,
"CpusetCpus": "0,1",
"CpusetMems": "0",
"Memory": 314572800,
"MemorySwap": 514288000,
"MemoryReservation": 209715200,
"RestartPolicy": {
"MaximumRetryCount": 4,
"Name": "on-failure"
}
}`

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Warnings": [
"string"
]
}`

## [](#tag/Container/operation/ContainerRename)Rename a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                  |
| ------------ | -------------------------------- |
| namerequired | stringNew name for the container |

### Responses

/v1.43/containers/{id}/rename

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerPause)Pause a container

Use the freezer cgroup to suspend all processes in a container.

Traditionally, when suspending a process the `SIGSTOP` signal is used, which is observable by the process being suspended. With the freezer cgroup the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.43/containers/{id}/pause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerUnpause)Unpause a container

Resume a container which has been paused.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

### Responses

/v1.43/containers/{id}/unpause

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "No such container: c2ada9df5af8"
}`

## [](#tag/Container/operation/ContainerAttach)Attach to a container

Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.

Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.

See the [documentation for the `docker attach` command](https://docs.docker.com/engine/reference/commandline/attach/) for more details.

### Hijacking

This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.

This is the response from the daemon for an attach request:

```
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream

[STREAM]
```

After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.

To hint potential proxies about connection hijacking, the Docker client can also optionally send connection upgrade headers.

For example, the client sends this request to upgrade the connection:

```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```

The Docker daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp

[STREAM]
```

### Stream format

When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the HTTP Content-Type header is set to application/vnd.docker.multiplexed-stream and the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.

The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).

It is encoded on the first eight bytes like this:

```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```

`STREAM_TYPE` can be:

* 0: `stdin` (is written on `stdout`)
* 1: `stdout`
* 2: `stderr`

`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.

Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.

The simplest way to implement this protocol is the following:

1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.

### Stream format when using a TTY

When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                                                                                                                                                                   |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`.                                                                                                                                                     |
| logs       | booleanDefault: falseReplay previous logs from the container.This is useful for attaching to a container that has started and you want to output everything since the container started.If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output. |
| stream     | booleanDefault: falseStream attached streams from the time the request was made onwards.                                                                                                                                                                                                                                          |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                                                                                                                                                                            |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                                                                                                                                                                           |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                                                                                                                                                                           |

### Responses

/v1.43/containers/{id}/attach

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Container/operation/ContainerAttachWebsocket)Attach to a container via a websocket

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|            |                                                                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| detachKeys | stringOverride the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,`, or `_`. |
| logs       | booleanDefault: falseReturn logs                                                                                                                                               |
| stream     | booleanDefault: falseReturn stream                                                                                                                                             |
| stdin      | booleanDefault: falseAttach to `stdin`                                                                                                                                         |
| stdout     | booleanDefault: falseAttach to `stdout`                                                                                                                                        |
| stderr     | booleanDefault: falseAttach to `stderr`                                                                                                                                        |

### Responses

/v1.43/containers/{id}/attach/ws

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerWait)Wait for a container

Block until a container stops, then returns the exit code.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|           |                                                                                                                                                                              |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| condition | stringDefault: "not-running"Enum: "not-running" "next-exit" "removed"Wait until a container state reaches the given condition.Defaults to `not-running` if omitted or empty. |

### Responses

/v1.43/containers/{id}/wait

### Response samples

* 200
* 400
* 404
* 500

Content type

application/json

`{
"StatusCode": 0,
"Error": {
"Message": "string"
}
}`

## [](#tag/Container/operation/ContainerDelete)Remove a container

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|       |                                                                               |
| ----- | ----------------------------------------------------------------------------- |
| v     | booleanDefault: falseRemove anonymous volumes associated with the container.  |
| force | booleanDefault: falseIf the container is running, kill it before removing it. |
| link  | booleanDefault: falseRemove the specified link associated with the container. |

### Responses

/v1.43/containers/{id}

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchiveInfo)Get information about files in a container

A response header `X-Docker-Container-Path-Stat` is returned, containing a base64 - encoded JSON object with some filesystem header information about the path.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.43/containers/{id}/archive

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Container/operation/ContainerArchive)Get an archive of a filesystem resource in a container

Get a tar archive of a resource in the filesystem of container id.

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|              |                                                          |
| ------------ | -------------------------------------------------------- |
| pathrequired | stringResource in the container’s filesystem to archive. |

### Responses

/v1.43/containers/{id}/archive

### Response samples

* 404

Content type

application/x-tar

No sample

## [](#tag/Container/operation/PutContainerArchive)Extract an archive of files or folders to a directory in a container

Upload a tar archive to be extracted to a path in the filesystem of container id. `path` parameter is asserted to be a directory. If it exists as a file, 400 error will be returned with message "not a directory".

##### path Parameters

|            |                                   |
| ---------- | --------------------------------- |
| idrequired | stringID or name of the container |

##### query Parameters

|                      |                                                                                                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathrequired         | stringPath to a directory in the container to extract the archive’s contents into.                                                                                            |
| noOverwriteDirNonDir | stringIf `1`, `true`, or `True` then it will be an error if unpacking the given content would cause an existing directory to be replaced with a non-directory and vice versa. |
| copyUIDGID           | stringIf `1`, `true`, then it will copy UID/GID maps to the dest file or dir                                                                                                  |

##### Request Body schema:application/x-tarrequired

The input stream must be a tar archive compressed with one of the following algorithms: `identity` (no compression), `gzip`, `bzip2`, or `xz`.

string \<binary>

### Responses

/v1.43/containers/{id}/archive

### Response samples

* 400
* 403
* 404
* 500

Content type

application/json

`{
"message": "not a directory"
}`

## [](#tag/Container/operation/ContainerPrune)Delete stopped containers

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune containers created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune containers with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.43/containers/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ContainersDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image)Images

## [](#tag/Image/operation/ImageList)List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| all         | booleanDefault: falseShow all images. Only images from a final layer (no children) are shown by default.                                                                                                                                                                                                                                                                       |
| filters     | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list.Available filters:- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) |
| shared-size | booleanDefault: falseCompute and show shared size as a `SharedSize` field on each image.                                                                                                                                                                                                                                                                                       |
| digests     | booleanDefault: falseShow digest information as a `RepoDigests` field on each image.                                                                                                                                                                                                                                                                                           |

### Responses

/v1.43/images/json

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"ParentId": "",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Created": "1644009612",
"Size": 172064416,
"SharedSize": 1239828,
"VirtualSize": 172064416,
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Containers": 2
}
]`

## [](#tag/Image/operation/ImageBuild)Build an image

Build an image from a tar archive with a `Dockerfile` in it.

The `Dockerfile` specifies how the image is built from the tar archive. It is typically in the archive's root, but can be at a different path or have a different name by specifying the `dockerfile` parameter. [See the `Dockerfile` reference for more information](https://docs.docker.com/engine/reference/builder/).

The Docker daemon performs a preliminary validation of the `Dockerfile` before starting the build, and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until the ID of the new image is output.

The build is canceled if the client drops the connection by quitting or being killed.

##### query Parameters

|             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dockerfile  | stringDefault: "Dockerfile"Path within the build context to the `Dockerfile`. This is ignored if `remote` is specified and points to an external `Dockerfile`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| t           | stringA name and optional tag to apply to the image in the `name:tag` format. If you omit the tag the default `latest` value is assumed. You can provide several `t` parameters.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| extrahosts  | stringExtra hosts to add to /etc/hosts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| remote      | stringA Git repository URI or HTTP/HTTPS context URI. If the URI points to a single text file, the file’s contents are placed into a file called `Dockerfile` and the image is built from that file. If the URI points to a tarball, the file is downloaded by the daemon and the contents therein used as the context for the build. If the URI points to a tarball and the `dockerfile` parameter is also specified, there must be a file with the corresponding path inside the tarball.                                                                                                                                        |
| q           | booleanDefault: falseSuppress verbose build output.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| nocache     | booleanDefault: falseDo not use the cache when building the image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cachefrom   | stringJSON array of images used for build cache resolution.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| pull        | stringAttempt to pull the image even if an older image exists locally.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| rm          | booleanDefault: trueRemove intermediate containers after a successful build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| forcerm     | booleanDefault: falseAlways remove intermediate containers, even upon failure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| memory      | integerSet memory limit for build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| memswap     | integerTotal memory (memory + swap). Set as `-1` to disable swap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| cpushares   | integerCPU shares (relative weight).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| cpusetcpus  | stringCPUs in which to allow execution (e.g., `0-3`, `0,1`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| cpuperiod   | integerThe length of a CPU period in microseconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| cpuquota    | integerMicroseconds of CPU time that the container can get in a CPU period.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| buildargs   | stringJSON map of string pairs for build-time variables. Users pass these values at build-time. Docker uses the buildargs as the environment context for commands run via the `Dockerfile` RUN instruction, or for variable expansion in other `Dockerfile` instructions. This is not meant for passing secret values.For example, the build arg `FOO=bar` would become `{"FOO":"bar"}` in JSON. This would result in the query parameter `buildargs={"FOO":"bar"}`. Note that `{"FOO":"bar"}` should be URI component encoded.[Read more about the buildargs instruction.](https://docs.docker.com/engine/reference/builder/#arg) |
| shmsize     | integerSize of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| squash      | booleanSquash the resulting images layers into a single layer. *(Experimental release only.)*                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| labels      | stringArbitrary key/value labels to set on the image, as a JSON map of string pairs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| networkmode | stringSets the networking mode for the run commands during build. Supported standard values are: `bridge`, `host`, `none`, and `container:<name\|id>`. Any other value is taken as a custom network's name or ID to which this container should connect to.                                                                                                                                                                                                                                                                                                                                                                        |
| platform    | stringDefault: ""Platform in the format os\[/arch\[/variant]]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| target      | stringDefault: ""Target build stage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| outputs     | stringDefault: ""BuildKit output configuration in the format of a stringified JSON array of objects. Each object must have two top-level properties: `Type` and `Attrs`. The `Type` property must be set to 'moby'. The `Attrs` property is a map of attributes for the BuildKit output configuration. See <https://docs.docker.com/build/exporters/oci-docker/> for more information.Example:```
[{"Type":"moby","Attrs":{"type":"image","force-compression":"true","compression":"zstd"}}]
```                                                                                                                                   |
| version     | stringDefault: "1"Enum: "1" "2"Version of the builder backend to use.- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit)                                                                                                                                                                                                                                                                                                                                                                                                               |

##### header Parameters

|                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-type      | stringDefault: application/x-tarValue: "application/x-tar"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| X-Registry-Config | stringThis is a base64-encoded JSON object with auth configurations for multiple registries that a build may refer to.The key is a registry URL, and the value is an auth configuration object, [as described in the authentication section](#section/Authentication). For example:```
{
  "docker.example.com": {
    "username": "janedoe",
    "password": "hunter2"
  },
  "https://index.docker.io/v1/": {
    "username": "mobydock",
    "password": "conta1n3rize14"
  }
}
```Only the registry domain name (and port if not the default 443) are required. However, for legacy reasons, the Docker Hub registry must be specified with both a `https://` prefix and a `/v1/` suffix even though Docker will prefer to use the v2 registry API. |

##### Request Body schema: application/octet-stream

A tar archive compressed with one of the following algorithms: identity (no compression), gzip, bzip2, xz.

string \<binary>

### Responses

/v1.43/build

### Response samples

* 400
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/BuildPrune)Delete builder cache

##### query Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| keep-storage | integer \<int64>Amount of disk space in bytes to keep for cache                                                                                                                                                                                                                                                                                                                                                                                                          |
| all          | booleanRemove all types of build cache                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the list of build cache objects.Available filters:- `until=<timestamp>` remove cache older than `<timestamp>`. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon's local time.
- `id=<id>`
- `parent=<id>`
- `type=<string>`
- `description=<string>`
- `inuse`
- `shared`
- `private` |

### Responses

/v1.43/build/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"CachesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCreate)Create an image

Create an image by either pulling it from a registry or importing it.

##### query Parameters

|           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fromImage | stringName of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| fromSrc   | stringSource to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| repo      | stringRepository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| tag       | stringTag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| message   | stringSet commit message for imported image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| changes   | Array of stringsApply `Dockerfile` instructions to the image that is created, for example: `changes=ENV DEBUG=true`. Note that `ENV DEBUG=true` should be URI component encoded.Supported `Dockerfile` instructions: `CMD`\|`ENTRYPOINT`\|`ENV`\|`EXPOSE`\|`ONBUILD`\|`USER`\|`VOLUME`\|`WORKDIR`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| platform  | stringDefault: ""Platform in the format os\[/arch\[/variant]].When used in combination with the `fromImage` option, the daemon checks if the given image is present in the local image cache with the given OS and Architecture, and otherwise attempts to pull the image. If the option is not set, the host's native OS and Architecture are used. If the given image does not exist in the local image cache, the daemon attempts to pull the image with the host's native OS and Architecture. If the given image does exists in the local image cache, but its OS or architecture does not match, a warning is produced.When used with the `fromSrc` option to import an image from an archive, this option sets the platform information for the imported image. If the option is not set, the host's native OS and Architecture are used for the imported image. |

##### header Parameters

|                 |                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:text/plain

Image content if the value `-` has been specified in fromSrc query parameter

string

### Responses

/v1.43/images/create

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageInspect)Inspect an image

Return low-level information about an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.43/images/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
"RepoTags": [
"example:1.0",
"example:latest",
"example:stable",
"internal.registry.example.com:5000/example:1.0"
],
"RepoDigests": [
"example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
"internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
],
"Parent": "",
"Comment": "",
"Created": "2022-02-04T21:20:12.497794809Z",
"Container": "65974bc86f1770ae4bff79f651ebdbce166ae9aada632ee3fa9af3a264911735",
"ContainerConfig": {
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
},
"DockerVersion": "20.10.7",
"Author": "",
"Config": {
"Hostname": "",
"Domainname": "",
"User": "web:web",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0,
"StartInterval": 0
},
"ArgsEscaped": true,
"Image": "",
"Volumes": {
"/app/data": { },
"/app/config": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"Shell": [
"/bin/sh",
"-c"
]
},
"Architecture": "arm",
"Variant": "v7",
"Os": "linux",
"OsVersion": "",
"Size": 1239828,
"VirtualSize": 1239828,
"GraphDriver": {
"Name": "overlay2",
"Data": {
"MergedDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/merged",
"UpperDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/diff",
"WorkDir": "/var/lib/docker/overlay2/ef749362d13333e65fc95c572eb525abbe0052e16e086cb64bc3b98ae9aa6d74/work"
}
},
"RootFS": {
"Type": "layers",
"Layers": [
"sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
]
},
"Metadata": {
"LastTagTime": "2022-02-28T14:40:02.623929178Z"
}
}`

## [](#tag/Image/operation/ImageHistory)Get the history of an image

Return parent layers of an image.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.43/images/{name}/history

### Response samples

* 200
* 404
* 500

Content type

application/json

`[
{
"Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
"Created": 1398108230,
"CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
"Tags": [
"ubuntu:lucid",
"ubuntu:10.04"
],
"Size": 182964289,
"Comment": ""
},
{
"Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
"Created": 1398108222,
"CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
"Tags": [ ],
"Size": 0,
"Comment": ""
},
{
"Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
"Created": 1371157430,
"CreatedBy": "",
"Tags": [
"scratch12:latest",
"scratch:latest"
],
"Size": 0,
"Comment": "Imported from -"
}
]`

## [](#tag/Image/operation/ImagePush)Push an image

Push an image to a registry.

If you wish to push an image on to a private registry, that image must already have a tag which references the registry. For example, `registry.example.com/myimage:latest`.

The push is cancelled if the HTTP connection is closed.

##### path Parameters

|              |                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| namerequired | stringName of the image to push. For example, `registry.example.com/myimage`. The image must be present in the local image store with the same name.The name should be provided without tag; if a tag is provided, it is ignored. For example, `registry.example.com/myimage:latest` is considered equivalent to `registry.example.com/myimage`.Use the `tag` parameter to specify the tag to push. |

##### query Parameters

|     |                                                                                                                                                                 |
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tag | stringTag of the image to push. For example, `latest`. If no tag is provided, all tags of the given image that are present in the local image store are pushed. |

##### header Parameters

|                         |                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Authrequired | stringA base64url-encoded auth configuration.Refer to the [authentication section](#section/Authentication) for details. |

### Responses

/v1.43/images/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageTag)Tag an image

Create a tag that refers to a source image.

This creates an additional reference (tag) to the source image. The tag can include a different repository name and/or tag. If the repository or tag already exists, it will be overwritten.

##### path Parameters

|              |                                |
| ------------ | ------------------------------ |
| namerequired | stringImage name or ID to tag. |

##### query Parameters

|      |                                                                    |
| ---- | ------------------------------------------------------------------ |
| repo | stringThe repository to tag in. For example, `someuser/someimage`. |
| tag  | stringThe name of the new tag.                                     |

### Responses

/v1.43/images/{name}/tag

### Response samples

* 400
* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Image/operation/ImageDelete)Remove an image

Remove an image, along with any untagged parent images that were referenced by that image.

Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

##### query Parameters

|         |                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------ |
| force   | booleanDefault: falseRemove the image even if it is being used by stopped containers or has other tags |
| noprune | booleanDefault: falseDo not delete untagged parent images                                              |

### Responses

/v1.43/images/{name}

### Response samples

* 200
* 404
* 409
* 500

Content type

application/json

`[
{
"Untagged": "3e2f21a89f"
},
{
"Deleted": "3e2f21a89f"
},
{
"Deleted": "53b4f83ac9"
}
]`

## [](#tag/Image/operation/ImageSearch)Search images

Search for an image on Docker Hub.

##### query Parameters

|              |                                                                                                                                                                                                                                                       |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| termrequired | stringTerm to search                                                                                                                                                                                                                                  |
| limit        | integerMaximum number of results to return                                                                                                                                                                                                            |
| filters      | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:- `is-automated=(true\|false)`
- `is-official=(true\|false)`
- `stars=<number>` Matches images that has at least 'number' stars. |

### Responses

/v1.43/images/search

### Response samples

* 200
* 500

Content type

application/json

`[
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "wma55/u1210sshd",
"star_count": 0
},
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "jdswinbank/sshd",
"star_count": 0
},
{
"description": "",
"is_official": false,
"is_automated": false,
"name": "vgauthier/sshd",
"star_count": 0
}
]`

## [](#tag/Image/operation/ImagePrune)Delete unused images

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`). Available filters:- `dangling=<boolean>` When set to `true` (or `1`), prune only unused *and* untagged images. When set to `false` (or `0`), all unused images are pruned.
- `until=<string>` Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.43/images/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"ImagesDeleted": [
{
"Untagged": "string",
"Deleted": "string"
}
],
"SpaceReclaimed": 0
}`

## [](#tag/Image/operation/ImageCommit)Create a new image from a container

##### query Parameters

|           |                                                                               |
| --------- | ----------------------------------------------------------------------------- |
| container | stringThe ID or name of the container to commit                               |
| repo      | stringRepository name for the created image                                   |
| tag       | stringTag name for the create image                                           |
| comment   | stringCommit message                                                          |
| author    | stringAuthor of the image (e.g., `John Hannibal Smith <hannibal@a-team.com>`) |
| pause     | booleanDefault: trueWhether to pause the container before committing          |
| changes   | string`Dockerfile` instructions to apply while committing                     |

##### Request Body schema: application/json

The container configuration

|                 |                                                                                                                                                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hostname        | stringThe hostname to use for the container, as a valid RFC 1123 hostname.                                                                                                                                                                                                                            |
| Domainname      | stringThe domain name to use for the container.                                                                                                                                                                                                                                                       |
| User            | stringThe user that commands are run as inside the container.                                                                                                                                                                                                                                         |
| AttachStdin     | booleanDefault: falseWhether to attach to `stdin`.                                                                                                                                                                                                                                                    |
| AttachStdout    | booleanDefault: trueWhether to attach to `stdout`.                                                                                                                                                                                                                                                    |
| AttachStderr    | booleanDefault: trueWhether to attach to `stderr`.                                                                                                                                                                                                                                                    |
|                 | object or nullAn object mapping ports to an empty object in the form:`{"<port>/<tcp\|udp\|sctp>": {}}`                                                                                                                                                                                                |
| Tty             | booleanDefault: falseAttach standard streams to a TTY, including `stdin` if it is not closed.                                                                                                                                                                                                         |
| OpenStdin       | booleanDefault: falseOpen `stdin`                                                                                                                                                                                                                                                                     |
| StdinOnce       | booleanDefault: falseClose `stdin` after one attached client disconnects                                                                                                                                                                                                                              |
| Env             | Array of stringsA list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.                                                                                             |
| Cmd             | Array of stringsCommand to run specified as a string or an array of strings.                                                                                                                                                                                                                          |
|                 | object (HealthConfig)A test to perform to check that the container is healthy. Healthcheck commands should be side-effect free.                                                                                                                                                                       |
| ArgsEscaped     | boolean or nullDefault: falseCommand is already escaped (Windows only)                                                                                                                                                                                                                                |
| Image           | stringThe name (or reference) of the image to use when creating the container, or which was used when the container was created.                                                                                                                                                                      |
|                 | objectAn object mapping mount point paths inside the container to empty objects.                                                                                                                                                                                                                      |
| WorkingDir      | stringThe working directory for commands to run in.                                                                                                                                                                                                                                                   |
| Entrypoint      | Array of stringsThe entry point for the container as a string or an array of strings.If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default (i.e., the entry point used by docker when there is no `ENTRYPOINT` instruction in the `Dockerfile`). |
| NetworkDisabled | boolean or nullDisable networking for the container.                                                                                                                                                                                                                                                  |
| MacAddress      | string or nullMAC address of the container.                                                                                                                                                                                                                                                           |
| OnBuild         | Array of strings or null`ONBUILD` metadata that were defined in the image's `Dockerfile`.                                                                                                                                                                                                             |
|                 | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                |
| StopSignal      | string or nullSignal to stop a container as a string or unsigned integer.                                                                                                                                                                                                                             |
| StopTimeout     | integer or nullDefault: 10Timeout to stop a container in seconds.                                                                                                                                                                                                                                     |
| Shell           | Array of strings or nullShell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell.                                                                                                                                                                                                                   |

### Responses

/v1.43/commit

### Request samples

* Payload

Content type

application/json

`{
"Hostname": "439f4e91bd1d",
"Domainname": "string",
"User": "string",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"ExposedPorts": {
"80/tcp": { },
"443/tcp": { }
},
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
],
"Cmd": [
"/bin/sh"
],
"Healthcheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"ArgsEscaped": false,
"Image": "example-image:1.0",
"Volumes": {
"property1": { },
"property2": { }
},
"WorkingDir": "/public/",
"Entrypoint": [ ],
"NetworkDisabled": true,
"MacAddress": "string",
"OnBuild": [ ],
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"StopSignal": "SIGTERM",
"StopTimeout": 10,
"Shell": [
"/bin/sh",
"-c"
]
}`

### Response samples

* 201
* 404
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Image/operation/ImageGet)Export an image

Get a tarball containing all images and metadata for a repository.

If `name` is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned. If `name` is an image ID, similarly only that image (and its parents) are returned, but with the exclusion of the `repositories` file in the tarball, as there were no image names referenced.

### Image tarball format

An image tarball contains one directory per image layer (named using its long ID), each containing these files:

* `VERSION`: currently `1.0` - the file format version
* `json`: detailed layer information, similar to `docker inspect layer_id`
* `layer.tar`: A tarfile containing the filesystem changes in this layer

The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories for storing attribute changes and deletions.

If the tarball defines a repository, the tarball should also include a `repositories` file at the root that contains a list of repository and tag names mapped to layer IDs.

```json
{
  "hello-world": {
    "latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"
  }
}
```

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or ID |

### Responses

/v1.43/images/{name}/get

## [](#tag/Image/operation/ImageGetAll)Export several images

Get a tarball containing all images and metadata for several image repositories.

For each value of the `names` parameter: if it is a specific name and tag (e.g. `ubuntu:latest`), then only that image (and its parents) are returned; if it is an image ID, similarly only that image (and its parents) are returned and there would be no names referenced in the 'repositories' file for this image ID.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                          |
| ----- | ---------------------------------------- |
| names | Array of stringsImage names to filter by |

### Responses

/v1.43/images/get

## [](#tag/Image/operation/ImageLoad)Import images

Load a set of images and tags into a repository.

For details on the format, see the [export image endpoint](#operation/ImageGet).

##### query Parameters

|       |                                                             |
| ----- | ----------------------------------------------------------- |
| quiet | booleanDefault: falseSuppress progress details during load. |

##### Request Body schema: application/x-tar

Tar archive containing images

string \<binary>

### Responses

/v1.43/images/load

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network)Networks

Networks are user-defined networks that containers can be attached to. See the [networking documentation](https://docs.docker.com/network/) for more information.

## [](#tag/Network/operation/NetworkList)List networks

Returns a list of networks. For details on the format, see the [network inspect endpoint](#operation/NetworkInspect).

Note that it uses a different, smaller representation of a network than inspecting a single network. For example, the list of containers attached to the network is not propagated in API versions 1.28 and up.

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringJSON encoded value of the filters (a `map[string][]string`) to process on the networks list.Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all networks that are not in use by a container. When set to `false` (or `0`), only networks that are in use by one or more containers are returned.
- `driver=<driver-name>` Matches a network's driver.
- `id=<network-id>` Matches all or part of a network ID.
- `label=<key>` or `label=<key>=<value>` of a network label.
- `name=<network-name>` Matches all or part of a network name.
- `scope=["swarm"\|"global"\|"local"]` Filters networks by scope (`swarm`, `global`, or `local`).
- `type=["custom"\|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. |

### Responses

/v1.43/networks

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "bridge",
"Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566",
"Created": "2016-10-19T06:21:00.416543526Z",
"Scope": "local",
"Driver": "bridge",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.17.0.0/16"
}
]
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
}
},
{
"Name": "none",
"Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "null",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
},
{
"Name": "host",
"Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e",
"Created": "0001-01-01T00:00:00Z",
"Scope": "local",
"Driver": "host",
"EnableIPv6": false,
"Internal": false,
"Attachable": false,
"Ingress": false,
"IPAM": {
"Driver": "default",
"Config": [ ]
},
"Containers": { },
"Options": { }
}
]`

## [](#tag/Network/operation/NetworkInspect)Inspect a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### query Parameters

|         |                                                                  |
| ------- | ---------------------------------------------------------------- |
| verbose | booleanDefault: falseDetailed inspect output for troubleshooting |
| scope   | stringFilter the network by scope (swarm, global, or local)      |

### Responses

/v1.43/networks/{id}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "my_network",
"Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99",
"Created": "2016-10-19T04:33:30.360899459Z",
"Scope": "local",
"Driver": "overlay",
"EnableIPv6": false,
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"Internal": false,
"Attachable": false,
"Ingress": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"ConfigOnly": false,
"Containers": {
"19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": {
"Name": "test",
"EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a",
"MacAddress": "02:42:ac:13:00:02",
"IPv4Address": "172.19.0.2/16",
"IPv6Address": ""
}
},
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Peers": [
{
"Name": "6869d7c1732b",
"IP": "10.133.77.91"
}
]
}`

## [](#tag/Network/operation/NetworkDelete)Remove a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

### Responses

/v1.43/networks/{id}

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkCreate)Create a network

##### Request Body schema: application/jsonrequired

Network configuration

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Namerequired   | stringThe network's name.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| CheckDuplicate | booleanCheck for networks with duplicate names. Since Network is primarily keyed based on a random ID and not on the name, and network name is strictly a user-friendly alias to the network which is uniquely identified using ID, there is no guaranteed way to check for duplicates. CheckDuplicate is there to provide a best effort checking of any networks which has the same name but it is not guaranteed to catch all name collisions. |
| Driver         | stringDefault: "bridge"Name of the network driver plugin to use.                                                                                                                                                                                                                                                                                                                                                                                 |
| Scope          | stringThe level at which the network exists (e.g. `swarm` for cluster-wide or `local` for machine level).                                                                                                                                                                                                                                                                                                                                        |
| Internal       | booleanRestrict external access to the network.                                                                                                                                                                                                                                                                                                                                                                                                  |
| Attachable     | booleanGlobally scoped network is manually attachable by regular containers from workers in swarm mode.                                                                                                                                                                                                                                                                                                                                          |
| Ingress        | booleanIngress network is the network which provides the routing-mesh in swarm mode.                                                                                                                                                                                                                                                                                                                                                             |
| ConfigOnly     | booleanDefault: falseCreates a config-only network. Config-only networks are placeholder networks for network configurations to be used by other networks. Config-only networks cannot be used directly to run containers or services.                                                                                                                                                                                                           |
|                | object (ConfigReference)The config-only network source to provide the configuration for this network.                                                                                                                                                                                                                                                                                                                                            |
|                | object (IPAM)                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| EnableIPv6     | booleanEnable IPv6 on the network.                                                                                                                                                                                                                                                                                                                                                                                                               |
|                | objectNetwork specific options to be used by the drivers.                                                                                                                                                                                                                                                                                                                                                                                        |
|                | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                           |

### Responses

/v1.43/networks/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "my_network",
"CheckDuplicate": true,
"Driver": "bridge",
"Scope": "string",
"Internal": true,
"Attachable": true,
"Ingress": false,
"ConfigOnly": false,
"ConfigFrom": {
"Network": "config_only_network_01"
},
"IPAM": {
"Driver": "default",
"Config": [
{
"Subnet": "172.20.0.0/16",
"IPRange": "172.20.10.0/24",
"Gateway": "172.20.10.11",
"AuxiliaryAddresses": {
"property1": "string",
"property2": "string"
}
}
],
"Options": {
"foo": "bar"
}
},
"EnableIPv6": true,
"Options": {
"com.docker.network.bridge.default_bridge": "true",
"com.docker.network.bridge.enable_icc": "true",
"com.docker.network.bridge.enable_ip_masquerade": "true",
"com.docker.network.bridge.host_binding_ipv4": "0.0.0.0",
"com.docker.network.bridge.name": "docker0",
"com.docker.network.driver.mtu": "1500"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}`

### Response samples

* 201
* 400
* 403
* 404
* 500

Content type

application/json

`{
"Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30",
"Warning": ""
}`

## [](#tag/Network/operation/NetworkConnect)Connect a container to a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                  |
| --------- | ---------------------------------------------------------------- |
| Container | stringThe ID or name of the container to connect to the network. |
|           | object (EndpointSettings)Configuration for a network endpoint.   |

### Responses

/v1.43/networks/{id}/connect

### Request samples

* Payload

Content type

application/json

`{
"Container": "3613f73ba0e4",
"EndpointConfig": {
"IPAMConfig": {
"IPv4Address": "172.24.56.89",
"IPv6Address": "2001:db8::5689"
}
}
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkDisconnect)Disconnect a container from a network

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringNetwork ID or name |

##### Request Body schema: application/jsonrequired

|           |                                                                       |
| --------- | --------------------------------------------------------------------- |
| Container | stringThe ID or name of the container to disconnect from the network. |
| Force     | booleanForce the container to disconnect from the network.            |

### Responses

/v1.43/networks/{id}/disconnect

### Request samples

* Payload

Content type

application/json

`{
"Container": "string",
"Force": true
}`

### Response samples

* 403
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Network/operation/NetworkPrune)Delete unused networks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `until=<timestamp>` Prune networks created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. `10m`, `1h30m`) computed relative to the daemon machine’s time.
- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune networks with (or without, in case `label!=...` is used) the specified labels. |

### Responses

/v1.43/networks/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"NetworksDeleted": [
"string"
]
}`

## [](#tag/Volume)Volumes

Create and manage persistent storage that can be attached to containers.

## [](#tag/Volume/operation/VolumeList)List volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | string \<json>JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters:- `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are not in use by a container. When set to `false` (or `0`), only volumes that are in use by one or more containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name. |

### Responses

/v1.43/volumes

### Response samples

* 200
* 500

Content type

application/json

`{
"Volumes": [
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": null,
"property2": null
}
}
],
"Preferred": [
{
"Segments": {
"property1": null,
"property2": null
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}
],
"Warnings": [ ]
}`

## [](#tag/Volume/operation/VolumeCreate)Create a volume

##### Request Body schema: application/jsonrequired

Volume configuration

|        |                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| Name   | stringThe new volume's name. If not specified, Docker generates a name.                                                |
| Driver | stringDefault: "local"Name of the volume driver to use.                                                                |
|        | objectA mapping of driver options and values. These options are passed directly to the driver and are driver specific. |
|        | objectUser-defined key/value metadata.                                                                                 |
|        | object (ClusterVolumeSpec)Cluster-specific options used to create the volume.                                          |

### Responses

/v1.43/volumes/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"DriverOpts": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"ClusterVolumeSpec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 201
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeInspect)Inspect a volume

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

### Responses

/v1.43/volumes/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis",
"CreatedAt": "2016-06-07T20:31:11.853781916Z",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local",
"ClusterVolume": {
"ID": "string",
"Version": {
"Index": 373531
},
"CreatedAt": "string",
"UpdatedAt": "string",
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
},
"Info": {
"CapacityBytes": 0,
"VolumeContext": {
"property1": "string",
"property2": "string"
},
"VolumeID": "string",
"AccessibleTopology": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"PublishStatus": [
{
"NodeID": "string",
"State": "pending-publish",
"PublishContext": {
"property1": "string",
"property2": "string"
}
}
]
},
"Options": {
"device": "tmpfs",
"o": "size=100m,uid=1000",
"type": "tmpfs"
},
"UsageData": {
"Size": -1,
"RefCount": -1
}
}`

## [](#tag/Volume/operation/VolumeUpdate)"Update a volume. Valid only for Swarm cluster volumes"

##### path Parameters

|              |                                    |
| ------------ | ---------------------------------- |
| namerequired | stringThe name or ID of the volume |

##### query Parameters

|                 |                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the volume being updated. This is required to avoid conflicting writes. Found in the volume's `ClusterVolume` field. |

##### Request Body schema: application/json

The spec of the volume to update. Currently, only Availability may change. All other fields must remain unchanged.

|   |                                                                               |
| - | ----------------------------------------------------------------------------- |
|   | object (ClusterVolumeSpec)Cluster-specific options used to create the volume. |

### Responses

/v1.43/volumes/{name}

### Request samples

* Payload

Content type

application/json

`{
"Spec": {
"Group": "string",
"AccessMode": {
"Scope": "single",
"Sharing": "none",
"MountVolume": { },
"Secrets": [
{
"Key": "string",
"Secret": "string"
}
],
"AccessibilityRequirements": {
"Requisite": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
],
"Preferred": [
{
"Segments": {
"property1": "string",
"property2": "string"
}
}
]
},
"CapacityRange": {
"RequiredBytes": 0,
"LimitBytes": 0
},
"Availability": "active"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumeDelete)Remove a volume

Instruct the driver to remove the volume.

##### path Parameters

|              |                         |
| ------------ | ----------------------- |
| namerequired | stringVolume name or ID |

##### query Parameters

|       |                                                      |
| ----- | ---------------------------------------------------- |
| force | booleanDefault: falseForce the removal of the volume |

### Responses

/v1.43/volumes/{name}

### Response samples

* 404
* 409
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Volume/operation/VolumePrune)Delete unused volumes

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the prune list, encoded as JSON (a `map[string][]string`).Available filters:- `label` (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune volumes with (or without, in case `label!=...` is used) the specified labels.
- `all` (`all=true`) - Consider all (local) volumes for pruning and not just anonymous volumes. |

### Responses

/v1.43/volumes/prune

### Response samples

* 200
* 500

Content type

application/json

`{
"VolumesDeleted": [
"string"
],
"SpaceReclaimed": 0
}`

## [](#tag/Exec)Exec

Run new commands inside running containers. Refer to the [command-line reference](https://docs.docker.com/engine/reference/commandline/exec/) for more information.

To exec a command in a container, you first need to create an exec instance, then start it. These two API endpoints are wrapped up in a single command-line command, `docker exec`.

## [](#tag/Exec/operation/ContainerExec)Create an exec instance

Run a command inside a running container.

##### path Parameters

|            |                               |
| ---------- | ----------------------------- |
| idrequired | stringID or name of container |

##### Request Body schema: application/jsonrequired

Exec configuration

|              |                                                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| AttachStdin  | booleanAttach to `stdin` of the exec command.                                                                                                                                  |
| AttachStdout | booleanAttach to `stdout` of the exec command.                                                                                                                                 |
| AttachStderr | booleanAttach to `stderr` of the exec command.                                                                                                                                 |
| ConsoleSize  | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array.                                                                        |
| DetachKeys   | stringOverride the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. |
| Tty          | booleanAllocate a pseudo-TTY.                                                                                                                                                  |
| Env          | Array of stringsA list of environment variables in the form `["VAR=value", ...]`.                                                                                              |
| Cmd          | Array of stringsCommand to run, as a string or array of strings.                                                                                                               |
| Privileged   | booleanDefault: falseRuns the exec process with extended privileges.                                                                                                           |
| User         | stringThe user, and optionally, group to run the exec process inside the container. Format is one of: `user`, `user:group`, `uid`, or `uid:gid`.                               |
| WorkingDir   | stringThe working directory for the exec process inside the container.                                                                                                         |

### Responses

/v1.43/containers/{id}/exec

### Request samples

* Payload

Content type

application/json

`{
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"DetachKeys": "ctrl-p,ctrl-q",
"Tty": false,
"Cmd": [
"date"
],
"Env": [
"FOO=bar",
"BAZ=quux"
]
}`

### Response samples

* 201
* 404
* 409
* 500

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Exec/operation/ExecStart)Start an exec instance

Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### Request Body schema: application/json

|             |                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| Detach      | booleanDetach from the command.                                                                         |
| Tty         | booleanAllocate a pseudo-TTY.                                                                           |
| ConsoleSize | Array of integers or null = 2 items \[ items >= 0 ]Initial console size, as an `[height, width]` array. |

### Responses

/v1.43/exec/{id}/start

### Request samples

* Payload

Content type

application/json

`{
"Detach": false,
"Tty": true,
"ConsoleSize": [
80,
64
]
}`

## [](#tag/Exec/operation/ExecResize)Resize an exec instance

Resize the TTY session used by an exec instance. This endpoint only works if `tty` was specified as part of creating and starting the exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

##### query Parameters

|           |                                                |
| --------- | ---------------------------------------------- |
| hrequired | integerHeight of the TTY session in characters |
| wrequired | integerWidth of the TTY session in characters  |

### Responses

/v1.43/exec/{id}/resize

### Response samples

* 400
* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Exec/operation/ExecInspect)Inspect an exec instance

Return low-level information about an exec instance.

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringExec instance ID |

### Responses

/v1.43/exec/{id}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false,
"Pid": 42000
}`

## [](#tag/Swarm)Swarm

Engines can be clustered together in a swarm. Refer to the [swarm mode documentation](https://docs.docker.com/engine/swarm/) for more information.

## [](#tag/Swarm/operation/SwarmInspect)Inspect swarm

### Responses

/v1.43/swarm

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24,
"JoinTokens": {
"Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx",
"Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}
}`

## [](#tag/Swarm/operation/SwarmInit)Initialize a new swarm

##### Request Body schema:application/jsonrequired

|                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr      | stringListen address used for inter-manager communication, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is used.                                                                                                                                             |
| AdvertiseAddr   | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr    | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| DataPathPort    | integer \<uint32>DataPathPort specifies the data path port number for data traffic. Acceptable port range is 1024 to 49151. if no port is set or is set to 0, default port 4789 will be used.                                                                                                                                                                                                                                                                                                                          |
| DefaultAddrPool | Array of stringsDefault Address Pool specifies default subnet pools for global scope networks.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ForceNewCluster | booleanForce creation of a new swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| SubnetSize      | integer \<uint32>SubnetSize specifies the subnet size of the networks created from the default subnet pool.                                                                                                                                                                                                                                                                                                                                                                                                            |
|                 | object (SwarmSpec)User modifiable swarm configuration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Responses

/v1.43/swarm/init

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathPort": 4789,
"DefaultAddrPool": [
"10.10.0.0/8",
"20.20.0.0/8"
],
"SubnetSize": 24,
"ForceNewCluster": false,
"Spec": {
"Orchestration": { },
"Raft": { },
"Dispatcher": { },
"CAConfig": { },
"EncryptionConfig": {
"AutoLockManagers": false
}
}
}`

### Response samples

* 200
* 400
* 500
* 503

Content type

application/json

`"7v2t30z9blmxuhnyo6s4cpenp"`

## [](#tag/Swarm/operation/SwarmJoin)Join an existing swarm

##### Request Body schema:application/jsonrequired

|               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListenAddr    | stringListen address used for inter-manager communication if the node gets promoted to manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP).                                                                                                                                                                                                                                                                                                                             |
| AdvertiseAddr | stringExternally reachable address advertised to other nodes. This can either be an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port number, like `eth0:4567`. If the port number is omitted, the port number from the listen address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when possible.                                                                                                                                        |
| DataPathAddr  | stringAddress or interface to use for data path traffic (format: `<ip\|interface>`), for example, `192.168.1.1`, or an interface, like `eth0`. If `DataPathAddr` is unspecified, the same address as `AdvertiseAddr` is used.The `DataPathAddr` specifies the address that global scope network drivers will publish towards other nodes in order to reach the containers running on this node. Using this parameter it is possible to separate the container data traffic from the management traffic of the cluster. |
| RemoteAddrs   | Array of stringsAddresses of manager nodes already participating in the swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| JoinToken     | stringSecret token for joining this swarm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Responses

/v1.43/swarm/join

### Request samples

* Payload

Content type

application/json

`{
"ListenAddr": "0.0.0.0:2377",
"AdvertiseAddr": "192.168.1.1:2377",
"DataPathAddr": "192.168.1.1",
"RemoteAddrs": [
"node1:2377"
],
"JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2"
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmLeave)Leave a swarm

##### query Parameters

|       |                                                                                                             |
| ----- | ----------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseForce leave swarm, even if this is the last manager or that it will break the cluster. |

### Responses

/v1.43/swarm/leave

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUpdate)Update a swarm

##### query Parameters

|                        |                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| versionrequired        | integer \<int64>The version number of the swarm object being updated. This is required to avoid conflicting writes. |
| rotateWorkerToken      | booleanDefault: falseRotate the worker join token.                                                                  |
| rotateManagerToken     | booleanDefault: falseRotate the manager join token.                                                                 |
| rotateManagerUnlockKey | booleanDefault: falseRotate the manager unlock key.                                                                 |

##### Request Body schema:application/jsonrequired

|      |                                                    |
| ---- | -------------------------------------------------- |
| Name | stringName of the swarm.                           |
|      | objectUser-defined key/value metadata.             |
|      | object or nullOrchestration configuration.         |
|      | objectRaft configuration.                          |
|      | object or nullDispatcher configuration.            |
|      | object or nullCA configuration.                    |
|      | objectParameters related to encryption-at-rest.    |
|      | objectDefaults for creating tasks in this cluster. |

### Responses

/v1.43/swarm/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
}`

### Response samples

* 400
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Swarm/operation/SwarmUnlockkey)Get the unlock key

### Responses

/v1.43/swarm/unlockkey

### Response samples

* 200
* 500
* 503

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

## [](#tag/Swarm/operation/SwarmUnlock)Unlock a locked manager

##### Request Body schema: application/jsonrequired

|           |                               |
| --------- | ----------------------------- |
| UnlockKey | stringThe swarm's unlock key. |

### Responses

/v1.43/swarm/unlock

### Request samples

* Payload

Content type

application/json

`{
"UnlockKey": "SWMKEY-1-7c37Cc8654o6p38HnroywCi19pllOnGtbdZEgtKxZu8"
}`

### Response samples

* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node)Nodes

Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Node/operation/NodeList)List nodes

##### query Parameters

|         |                                                                                                                                                                                                                                                                              |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringFilters to process on the nodes list, encoded as JSON (a `map[string][]string`).Available filters:- `id=<node id>`
- `label=<engine label>`
- `membership=`(`accepted`\|`pending`)\`
- `name=<node name>`
- `node.label=<node label>`
- `role=`(`manager`\|`worker`)\` |

### Responses

/v1.43/nodes

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}
]`

## [](#tag/Node/operation/NodeInspect)Inspect a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

### Responses

/v1.43/nodes/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "24ifsmvkjbyhk",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
},
"Description": {
"Hostname": "bf3067039e47",
"Platform": {
"Architecture": "x86_64",
"OS": "linux"
},
"Resources": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
},
"Engine": {
"EngineVersion": "17.06.0",
"Labels": {
"foo": "bar"
},
"Plugins": [
{
"Type": "Log",
"Name": "awslogs"
},
{
"Type": "Log",
"Name": "fluentd"
},
{
"Type": "Log",
"Name": "gcplogs"
},
{
"Type": "Log",
"Name": "gelf"
},
{
"Type": "Log",
"Name": "journald"
},
{
"Type": "Log",
"Name": "json-file"
},
{
"Type": "Log",
"Name": "splunk"
},
{
"Type": "Log",
"Name": "syslog"
},
{
"Type": "Network",
"Name": "bridge"
},
{
"Type": "Network",
"Name": "host"
},
{
"Type": "Network",
"Name": "ipvlan"
},
{
"Type": "Network",
"Name": "macvlan"
},
{
"Type": "Network",
"Name": "null"
},
{
"Type": "Network",
"Name": "overlay"
},
{
"Type": "Volume",
"Name": "local"
},
{
"Type": "Volume",
"Name": "localhost:5000/vieux/sshfs:latest"
},
{
"Type": "Volume",
"Name": "vieux/sshfs:latest"
}
]
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
}
},
"Status": {
"State": "ready",
"Message": "",
"Addr": "172.17.0.2"
},
"ManagerStatus": {
"Leader": true,
"Reachability": "reachable",
"Addr": "10.0.0.46:2377"
}
}`

## [](#tag/Node/operation/NodeDelete)Delete a node

##### path Parameters

|            |                                  |
| ---------- | -------------------------------- |
| idrequired | stringThe ID or name of the node |

##### query Parameters

|       |                                                         |
| ----- | ------------------------------------------------------- |
| force | booleanDefault: falseForce remove a node from the swarm |

### Responses

/v1.43/nodes/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Node/operation/NodeUpdate)Update a node

##### path Parameters

|            |                          |
| ---------- | ------------------------ |
| idrequired | stringThe ID of the node |

##### query Parameters

|                 |                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| versionrequired | integer \<int64>The version number of the node object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

|              |                                                               |
| ------------ | ------------------------------------------------------------- |
| Name         | stringName for the node.                                      |
|              | objectUser-defined key/value metadata.                        |
| Role         | stringEnum: "worker" "manager"Role of the node.               |
| Availability | stringEnum: "active" "pause" "drain"Availability of the node. |

### Responses

/v1.43/nodes/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Availability": "active",
"Name": "node-name",
"Role": "manager",
"Labels": {
"foo": "bar"
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service)Services

Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Service/operation/ServiceList)List services

##### query Parameters

|         |                                                                                                                                                                                                                               |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the services list.Available filters:- `id=<service id>`
- `label=<service label>`
- `mode=["replicated"\|"global"]`
- `name=<service name>` |
| status  | booleanInclude service status, with count of running and desired tasks.                                                                                                                                                       |

### Responses

/v1.43/services

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}
]`

## [](#tag/Service/operation/ServiceCreate)Create a service

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                  |
| ---- | ------------------------------------------------------------------------------------------------ |
| Name | stringName of the service.                                                                       |
|      | objectUser-defined key/value metadata.                                                           |
|      | object (TaskSpec)User modifiable task configuration.                                             |
|      | objectScheduling mode for the service.                                                           |
|      | objectSpecification for the update strategy of the service.                                      |
|      | objectSpecification for the rollback strategy of the service.                                    |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.     |

### Responses

/v1.43/services/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "web",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "nginx:alpine",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"string"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "33",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
}
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "/usr/share/nginx/html",
"Source": "web-data",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string",
"com.example.something": "something-value"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"Hosts": [
"10.10.10.10 host1",
"ABCD:EF01:2345:6789:ABCD:EF01:2345:6789 host2"
],
"DNSConfig": {
"Nameservers": [
"8.8.8.8"
],
"Search": [
"example.org"
],
"Options": [
"timeout:3"
]
},
"Secrets": [
{
"File": {
"Name": "www.example.org.key",
"UID": "33",
"GID": "33",
"Mode": 384
},
"SecretID": "fpjqlhnwb19zds35k8wn80lq9",
"SecretName": "example_org_domain_key"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 104857600,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "on-failure",
"Delay": 10000000000,
"MaxAttempts": 10,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "json-file",
"Options": {
"property1": "string",
"property2": "string",
"max-file": "3",
"max-size": "10M"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 4
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 80,
"PublishedPort": 8080,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 201
* 400
* 403
* 409
* 500
* 503

Content type

application/json

`{
"ID": "ak7w3gjqoa3kuz8xcpnyy0pvl",
"Warning": "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
}`

## [](#tag/Service/operation/ServiceInspect)Inspect a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                |                                                             |
| -------------- | ----------------------------------------------------------- |
| insertDefaults | booleanDefault: falseFill empty fields with default values. |

### Responses

/v1.43/services/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Version": {
"Index": 19
},
"CreatedAt": "2016-06-07T21:05:51.880065305Z",
"UpdatedAt": "2016-06-07T21:07:29.962229872Z",
"Spec": {
"Name": "hopeful_cori",
"TaskTemplate": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { },
"ForceUpdate": 0
},
"Mode": {
"Replicated": {
"Replicas": 1
}
},
"UpdateConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15
},
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
}
},
"Endpoint": {
"Spec": {
"Mode": "vip",
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
]
},
"Ports": [
{
"Protocol": "tcp",
"TargetPort": 6379,
"PublishedPort": 30001
}
],
"VirtualIPs": [
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.2/16"
},
{
"NetworkID": "4qvuz4ko70xaltuqbt8956gd1",
"Addr": "10.255.0.3/16"
}
]
}
}`

## [](#tag/Service/operation/ServiceDelete)Delete a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

### Responses

/v1.43/services/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Service/operation/ServiceUpdate)Update a service

##### path Parameters

|            |                              |
| ---------- | ---------------------------- |
| idrequired | stringID or name of service. |

##### query Parameters

|                  |                                                                                                                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| versionrequired  | integerThe version number of the service object being updated. This is required to avoid conflicting writes. This version number should be the value as currently set on the service *before* the update. You can find the current version by calling `GET /services/{id}` |
| registryAuthFrom | stringDefault: "spec"Enum: "spec" "previous-spec"If the `X-Registry-Auth` header is not specified, this parameter indicates where to find registry authorization credentials.                                                                                              |
| rollback         | stringSet to this parameter to `previous` to cause a server-side rollback to the previous service spec. The supplied spec will be ignored in this case.                                                                                                                    |

##### header Parameters

|                 |                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| X-Registry-Auth | stringA base64url-encoded auth configuration for pulling from private registries.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema: application/jsonrequired

|      |                                                                                                  |
| ---- | ------------------------------------------------------------------------------------------------ |
| Name | stringName of the service.                                                                       |
|      | objectUser-defined key/value metadata.                                                           |
|      | object (TaskSpec)User modifiable task configuration.                                             |
|      | objectScheduling mode for the service.                                                           |
|      | objectSpecification for the update strategy of the service.                                      |
|      | objectSpecification for the rollback strategy of the service.                                    |
|      | Array of objects (NetworkAttachmentConfig)Specifies which networks the service should attach to. |
|      | object (EndpointSpec)Properties that can be configured to access and load balance a service.     |

### Responses

/v1.43/services/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "top",
"Labels": {
"property1": "string",
"property2": "string"
},
"TaskTemplate": {
"PluginSpec": {
"Name": "string",
"Remote": "string",
"Disabled": true,
"PluginPrivilege": [
{
"Name": "network",
"Description": "string",
"Value": [
"host"
]
}
]
},
"ContainerSpec": {
"Image": "busybox",
"Labels": {
"property1": "string",
"property2": "string"
},
"Command": [
"string"
],
"Args": [
"top"
],
"Hostname": "string",
"Env": [
"string"
],
"Dir": "string",
"User": "string",
"Groups": [
"string"
],
"Privileges": {
"CredentialSpec": {
"Config": "0bt9dmxjvjiqermk6xrop3ekq",
"File": "spec.json",
"Registry": "string"
},
"SELinuxContext": {
"Disable": true,
"User": "string",
"Role": "string",
"Type": "string",
"Level": "string"
}
},
"TTY": true,
"OpenStdin": true,
"ReadOnly": true,
"Mounts": [
{
"Target": "string",
"Source": "string",
"Type": "volume",
"ReadOnly": true,
"Consistency": "string",
"BindOptions": {
"Propagation": "private",
"NonRecursive": false,
"CreateMountpoint": false
},
"VolumeOptions": {
"NoCopy": false,
"Labels": {
"property1": "string",
"property2": "string"
},
"DriverConfig": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"TmpfsOptions": {
"SizeBytes": 0,
"Mode": 0
}
}
],
"StopSignal": "string",
"StopGracePeriod": 0,
"HealthCheck": {
"Test": [
"string"
],
"Interval": 0,
"Timeout": 0,
"Retries": 0,
"StartPeriod": 0
},
"Hosts": [
"string"
],
"DNSConfig": {
"Nameservers": [
"string"
],
"Search": [
"string"
],
"Options": [
"string"
]
},
"Secrets": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"SecretID": "string",
"SecretName": "string"
}
],
"Configs": [
{
"File": {
"Name": "string",
"UID": "string",
"GID": "string",
"Mode": 0
},
"Runtime": { },
"ConfigID": "string",
"ConfigName": "string"
}
],
"Isolation": "default",
"Init": true,
"Sysctls": {
"property1": "string",
"property2": "string"
},
"CapabilityAdd": [
"CAP_NET_RAW",
"CAP_SYS_ADMIN",
"CAP_SYS_CHROOT",
"CAP_SYSLOG"
],
"CapabilityDrop": [
"CAP_NET_RAW"
],
"Ulimits": [
{
"Name": "string",
"Soft": 0,
"Hard": 0
}
]
},
"NetworkAttachmentSpec": {
"ContainerID": "string"
},
"Resources": {
"Limits": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"Pids": 100
},
"Reservations": {
"NanoCPUs": 4000000000,
"MemoryBytes": 8272408576,
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}
},
"RestartPolicy": {
"Condition": "any",
"Delay": 0,
"MaxAttempts": 0,
"Window": 0
},
"Placement": {
"Constraints": [
"node.hostname!=node3.corp.example.com",
"node.role!=manager",
"node.labels.type==production",
"node.platform.os==linux",
"node.platform.arch==x86_64"
],
"Preferences": [
{
"Spread": {
"SpreadDescriptor": "node.labels.datacenter"
}
},
{
"Spread": {
"SpreadDescriptor": "node.labels.rack"
}
}
],
"MaxReplicas": 0,
"Platforms": [
{
"Architecture": "x86_64",
"OS": "linux"
}
]
},
"ForceUpdate": 0,
"Runtime": "string",
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"LogDriver": {
"Name": "string",
"Options": {
"property1": "string",
"property2": "string"
}
}
},
"Mode": {
"Replicated": {
"Replicas": 1
},
"Global": { },
"ReplicatedJob": {
"MaxConcurrent": 1,
"TotalCompletions": 0
},
"GlobalJob": { }
},
"UpdateConfig": {
"Parallelism": 2,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"RollbackConfig": {
"Parallelism": 1,
"Delay": 1000000000,
"FailureAction": "pause",
"Monitor": 15000000000,
"MaxFailureRatio": 0.15,
"Order": "stop-first"
},
"Networks": [
{
"Target": "string",
"Aliases": [
"string"
],
"DriverOpts": {
"property1": "string",
"property2": "string"
}
}
],
"EndpointSpec": {
"Mode": "vip",
"Ports": [
{
"Name": "string",
"Protocol": "tcp",
"TargetPort": 0,
"PublishedPort": 0,
"PublishMode": "ingress"
}
]
}
}`

### Response samples

* 200
* 400
* 404
* 500
* 503

Content type

application/json

`{
"Warning": "unable to pin image doesnotexist:latest to digest: image library/doesnotexist:latest not found"
}`

## [](#tag/Service/operation/ServiceLogs)Get service logs

Get `stdout` and `stderr` logs from a service. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                                 |
| ---------- | ------------------------------- |
| idrequired | stringID or name of the service |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow service context and extra details provided to logs.                                                              |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.43/services/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Task)Tasks

A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Task/operation/TaskList)List tasks

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the tasks list.Available filters:- `desired-state=(running \| shutdown \| accepted)`
- `id=<task id>`
- `label=key` or `label="key=value"`
- `name=<task name>`
- `node=<node id or name>`
- `service=<service name>` |

### Responses

/v1.43/tasks

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
]
},
{
"ID": "1yljwbmlr8er2waf8orvqpwms",
"Version": {
"Index": 30
},
"CreatedAt": "2016-06-07T21:07:30.019104782Z",
"UpdatedAt": "2016-06-07T21:07:30.231958098Z",
"Name": "hopeful_cori",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:30.202183143Z",
"State": "shutdown",
"Message": "shutdown",
"ContainerStatus": {
"ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213"
}
},
"DesiredState": "shutdown",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.5/16"
]
}
]
}
]`

## [](#tag/Task/operation/TaskInspect)Inspect a task

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

### Responses

/v1.43/tasks/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "0kzzo1i0y4jz6027t0k7aezc7",
"Version": {
"Index": 71
},
"CreatedAt": "2016-06-07T21:07:31.171892745Z",
"UpdatedAt": "2016-06-07T21:07:31.376370513Z",
"Spec": {
"ContainerSpec": {
"Image": "redis"
},
"Resources": {
"Limits": { },
"Reservations": { }
},
"RestartPolicy": {
"Condition": "any",
"MaxAttempts": 0
},
"Placement": { }
},
"ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz",
"Slot": 1,
"NodeID": "60gvrl6tm78dmak4yl7srz94v",
"Status": {
"Timestamp": "2016-06-07T21:07:31.290032978Z",
"State": "running",
"Message": "started",
"ContainerStatus": {
"ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035",
"PID": 677
}
},
"DesiredState": "running",
"NetworksAttachments": [
{
"Network": {
"ID": "4qvuz4ko70xaltuqbt8956gd1",
"Version": {
"Index": 18
},
"CreatedAt": "2016-06-07T20:31:11.912919752Z",
"UpdatedAt": "2016-06-07T21:07:29.955277358Z",
"Spec": {
"Name": "ingress",
"Labels": {
"com.docker.swarm.internal": "true"
},
"DriverConfiguration": { },
"IPAMOptions": {
"Driver": { },
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"DriverState": {
"Name": "overlay",
"Options": {
"com.docker.network.driver.overlay.vxlanid_list": "256"
}
},
"IPAMOptions": {
"Driver": {
"Name": "default"
},
"Configs": [
{
"Subnet": "10.255.0.0/16",
"Gateway": "10.255.0.1"
}
]
}
},
"Addresses": [
"10.255.0.10/16"
]
}
],
"AssignedGenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
]
}`

## [](#tag/Task/operation/TaskLogs)Get task logs

Get `stdout` and `stderr` logs from a task. See also [`/containers/{id}/logs`](#operation/ContainerLogs).

**Note**: This endpoint works only for services with the `local`, `json-file` or `journald` logging drivers.

##### path Parameters

|            |                      |
| ---------- | -------------------- |
| idrequired | stringID of the task |

##### query Parameters

|            |                                                                                                                                            |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| details    | booleanDefault: falseShow task context and extra details provided to logs.                                                                 |
| follow     | booleanDefault: falseKeep connection after returning logs.                                                                                 |
| stdout     | booleanDefault: falseReturn logs from `stdout`                                                                                             |
| stderr     | booleanDefault: falseReturn logs from `stderr`                                                                                             |
| since      | integerDefault: 0Only return logs since this time, as a UNIX timestamp                                                                     |
| timestamps | booleanDefault: falseAdd timestamps to every log line                                                                                      |
| tail       | stringDefault: "all"Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines. |

### Responses

/v1.43/tasks/{id}/logs

### Response samples

* 404

Content type

application/vnd.docker.raw-stream

No sample

## [](#tag/Secret)Secrets

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Secret/operation/SecretList)List secrets

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list.Available filters:- `id=<secret id>`
- `label=<key> or label=<key>=value`
- `name=<secret name>`
- `names=<secret name>` |

### Responses

/v1.43/secrets

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "blt1owaxmitz71s9v5zh81zun",
"Version": {
"Index": 85
},
"CreatedAt": "2017-07-20T13:55:28.678958722Z",
"UpdatedAt": "2017-07-20T13:55:28.678958722Z",
"Spec": {
"Name": "mysql-passwd",
"Labels": {
"some.label": "some.value"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
},
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
}
}
}
]`

## [](#tag/Secret/operation/SecretCreate)Create a secret

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.43/secrets/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "app-key.crt",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Secret/operation/SecretInspect)Inspect a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.43/secrets/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt",
"Labels": {
"foo": "bar"
},
"Driver": {
"Name": "secret-bucket",
"Options": {
"OptionA": "value for driver option A",
"OptionB": "value for driver option B"
}
}
}
}`

## [](#tag/Secret/operation/SecretDelete)Delete a secret

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the secret |

### Responses

/v1.43/secrets/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Secret/operation/SecretUpdate)Update a Secret

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the secret |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the secret object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the secret.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Data | stringData is the data to store as a secret, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. It must be empty if the Driver field is set, in which case the data is loaded from an external secret store. The maximum allowed size is 500KB, as defined in [MaxSecretSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0/api/validation#MaxSecretSize).This field is only used to *create* a secret, and is not returned by other endpoints. |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Responses

/v1.43/secrets/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Data": "",
"Driver": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
},
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config)Configs

Configs are application configurations that can be used by services. Swarm mode must be enabled for these endpoints to work.

## [](#tag/Config/operation/ConfigList)List configs

##### query Parameters

|         |                                                                                                                                                                                                                             |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the configs list.Available filters:- `id=<config id>`
- `label=<key> or label=<key>=value`
- `name=<config name>`
- `names=<config name>` |

### Responses

/v1.43/configs

### Response samples

* 200
* 500
* 503

Content type

application/json

`[
{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "server.conf"
}
}
]`

## [](#tag/Config/operation/ConfigCreate)Create a config

##### Request Body schema: application/json

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.43/configs/create

### Request samples

* Payload

Content type

application/json

`{
"Name": "server.conf",
"Labels": {
"property1": "string",
"property2": "string",
"foo": "bar"
},
"Data": "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 201
* 409
* 500
* 503

Content type

application/json

`{
"Id": "string"
}`

## [](#tag/Config/operation/ConfigInspect)Inspect a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.43/configs/{id}

### Response samples

* 200
* 404
* 500
* 503

Content type

application/json

`{
"ID": "ktnbjxoalbkvbvedmg1urrz8h",
"Version": {
"Index": 11
},
"CreatedAt": "2016-11-05T01:20:17.327670065Z",
"UpdatedAt": "2016-11-05T01:20:17.327670065Z",
"Spec": {
"Name": "app-dev.crt"
}
}`

## [](#tag/Config/operation/ConfigDelete)Delete a config

##### path Parameters

|            |                        |
| ---------- | ---------------------- |
| idrequired | stringID of the config |

### Responses

/v1.43/configs/{id}

### Response samples

* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Config/operation/ConfigUpdate)Update a Config

##### path Parameters

|            |                                    |
| ---------- | ---------------------------------- |
| idrequired | stringThe ID or name of the config |

##### query Parameters

|                 |                                                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| versionrequired | integer \<int64>The version number of the config object being updated. This is required to avoid conflicting writes. |

##### Request Body schema:application/json

The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values.

|      |                                                                                                                                                                                                                                                                                                                                                |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | stringUser-defined name of the config.                                                                                                                                                                                                                                                                                                         |
|      | objectUser-defined key/value metadata.                                                                                                                                                                                                                                                                                                         |
| Data | stringData is the data to store as a config, formatted as a standard base64-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-4)) string. The maximum allowed size is 1000KB, as defined in [MaxConfigSize](https://pkg.go.dev/github.com/moby/swarmkit/v2@v2.0.0-20250103191802-8c1959736554/manager/controlapi#MaxConfigSize). |
|      | object (Driver)Driver represents a driver (network, logging, secrets).                                                                                                                                                                                                                                                                         |

### Responses

/v1.43/configs/{id}/update

### Request samples

* Payload

Content type

application/json

`{
"Name": "string",
"Labels": {
"property1": "string",
"property2": "string"
},
"Data": "string",
"Templating": {
"Name": "some-driver",
"Options": {
"OptionA": "value for driver-specific option A",
"OptionB": "value for driver-specific option B"
}
}
}`

### Response samples

* 400
* 404
* 500
* 503

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin)Plugins

## [](#tag/Plugin/operation/PluginList)List plugins

Returns information about installed plugins.

##### query Parameters

|         |                                                                                                                                                                                 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filters | stringA JSON encoded value of the filters (a `map[string][]string`) to process on the plugin list.Available filters:- `capability=<capability name>`
- `enable=<true>\|<false>` |

### Responses

/v1.43/plugins

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}
]`

## [](#tag/Plugin/operation/GetPluginPrivileges)Get plugin privileges

##### query Parameters

|                |                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------- |
| remoterequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.43/plugins/privileges

### Response samples

* 200
* 500

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

## [](#tag/Plugin/operation/PluginPull)Install a plugin

Pulls and installs a plugin. After the plugin is installed, it can be enabled using the [`POST /plugins/{name}/enable` endpoint](#operation/PostPluginsEnable).

##### query Parameters

|                |                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| remoterequired | stringRemote reference for plugin to install.The `:latest` tag is optional, and is used as the default if omitted. |
| name           | stringLocal name for the pulled plugin.The `:latest` tag is optional, and is used as the default if omitted.       |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.43/plugins/pull

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginInspect)Inspect a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.43/plugins/{name}/json

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginDelete)Remove a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------------- |
| force | booleanDefault: falseDisable the plugin before removing. This may result in issues if the plugin is in use by a container. |

### Responses

/v1.43/plugins/{name}

### Response samples

* 200
* 404
* 500

Content type

application/json

`{
"Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078",
"Name": "tiborvass/sample-volume-plugin",
"Enabled": true,
"Settings": {
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
"DEBUG=0"
],
"Args": [
"string"
],
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PluginReference": "localhost:5000/tiborvass/sample-volume-plugin:latest",
"Config": {
"DockerVersion": "17.06.0-ce",
"Description": "A sample volume plugin for Docker",
"Documentation": "https://docs.docker.com/engine/extend/plugins/",
"Interface": {
"Types": [
"docker.volumedriver/1.0"
],
"Socket": "plugins.sock",
"ProtocolScheme": "some.protocol/v1.0"
},
"Entrypoint": [
"/usr/bin/sample-volume-plugin",
"/data"
],
"WorkDir": "/bin/",
"User": {
"UID": 1000,
"GID": 1000
},
"Network": {
"Type": "host"
},
"Linux": {
"Capabilities": [
"CAP_SYS_ADMIN",
"CAP_SYSLOG"
],
"AllowAllDevices": false,
"Devices": [
{
"Name": "string",
"Description": "string",
"Settable": [
"string"
],
"Path": "/dev/fuse"
}
]
},
"PropagatedMount": "/mnt/volumes",
"IpcHost": false,
"PidHost": false,
"Mounts": [
{
"Name": "some-mount",
"Description": "This is a mount that's used by the plugin.",
"Settable": [
"string"
],
"Source": "/var/lib/docker/plugins/",
"Destination": "/mnt/state",
"Type": "bind",
"Options": [
"rbind",
"rw"
]
}
],
"Env": [
{
"Name": "DEBUG",
"Description": "If set, prints debug messages",
"Settable": null,
"Value": "0"
}
],
"Args": {
"Name": "args",
"Description": "command line arguments",
"Settable": [
"string"
],
"Value": [
"string"
]
},
"rootfs": {
"type": "layers",
"diff_ids": [
"sha256:675532206fbf3030b8458f88d6e26d4eb1577688a25efec97154c94e8b6b4887",
"sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
]
}
}
}`

## [](#tag/Plugin/operation/PluginEnable)Enable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|         |                                                           |
| ------- | --------------------------------------------------------- |
| timeout | integerDefault: 0Set the HTTP client timeout (in seconds) |

### Responses

/v1.43/plugins/{name}/enable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginDisable)Disable a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|       |                                                     |
| ----- | --------------------------------------------------- |
| force | booleanForce disable a plugin even if still in use. |

### Responses

/v1.43/plugins/{name}/disable

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginUpgrade)Upgrade a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### query Parameters

|                |                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| remoterequired | stringRemote reference to upgrade to.The `:latest` tag is optional, and is used as the default if omitted. |

##### header Parameters

|                 |                                                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-Registry-Auth | stringA base64url-encoded auth configuration to use when pulling a plugin from a registry.Refer to the [authentication section](#section/Authentication) for details. |

##### Request Body schema:application/json

Array

|             |                  |
| ----------- | ---------------- |
| Name        | string           |
| Description | string           |
| Value       | Array of strings |

### Responses

/v1.43/plugins/{name}/upgrade

### Request samples

* Payload

Content type

application/json

`[
{
"Name": "network",
"Description": "",
"Value": [
"host"
]
},
{
"Name": "mount",
"Description": "",
"Value": [
"/data"
]
},
{
"Name": "device",
"Description": "",
"Value": [
"/dev/cpu_dma_latency"
]
}
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginCreate)Create a plugin

##### query Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/x-tar

Path to tar containing plugin rootfs and manifest

string \<binary>

### Responses

/v1.43/plugins/create

### Response samples

* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginPush)Push a plugin

Push a plugin to the registry.

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

### Responses

/v1.43/plugins/{name}/push

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/Plugin/operation/PluginSet)Configure a plugin

##### path Parameters

|              |                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------- |
| namerequired | stringThe name of the plugin. The `:latest` tag is optional, and is the default if omitted. |

##### Request Body schema: application/json

Array

string

### Responses

/v1.43/plugins/{name}/set

### Request samples

* Payload

Content type

application/json

`[
"DEBUG=1"
]`

### Response samples

* 404
* 500

Content type

application/json

`{
"message": "Something went wrong."
}`

## [](#tag/System)System

## [](#tag/System/operation/SystemAuth)Check auth configuration

Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.

##### Request Body schema: application/json

Authentication to check

|               |                                                                                                                                                                                 |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| username      | string                                                                                                                                                                          |
| password      | string                                                                                                                                                                          |
| email         | stringEmail is an optional value associated with the username.> **Deprecated**: This field is deprecated since docker 1.11 (API v1.23) and will be removed in a future release. |
| serveraddress | string                                                                                                                                                                          |

### Responses

/v1.43/auth

### Request samples

* Payload

Content type

application/json

`{
"username": "hannibal",
"password": "xxxx",
"serveraddress": "https://index.docker.io/v1/"
}`

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Status": "Login Succeeded",
"IdentityToken": "9cbaf023786cd7..."
}`

## [](#tag/System/operation/SystemInfo)Get system information

### Responses

/v1.43/info

### Response samples

* 200
* 500

Content type

application/json

`{
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"Containers": 14,
"ContainersRunning": 3,
"ContainersPaused": 1,
"ContainersStopped": 10,
"Images": 508,
"Driver": "overlay2",
"DriverStatus": [ [
"Backing Filesystem",
"extfs"
], [
"Supports d_type",
"true"
], [
"Native Overlay Diff",
"true"
]
],
"DockerRootDir": "/var/lib/docker",
"Plugins": {
"Volume": [
"local"
],
"Network": [
"bridge",
"host",
"ipvlan",
"macvlan",
"null",
"overlay"
],
"Authorization": [
"img-authz-plugin",
"hbm"
],
"Log": [
"awslogs",
"fluentd",
"gcplogs",
"gelf",
"journald",
"json-file",
"splunk",
"syslog"
]
},
"MemoryLimit": true,
"SwapLimit": true,
"KernelMemoryTCP": true,
"CpuCfsPeriod": true,
"CpuCfsQuota": true,
"CPUShares": true,
"CPUSet": true,
"PidsLimit": true,
"OomKillDisable": true,
"IPv4Forwarding": true,
"BridgeNfIptables": true,
"BridgeNfIp6tables": true,
"Debug": true,
"NFd": 64,
"NGoroutines": 174,
"SystemTime": "2017-08-08T20:28:29.06202363Z",
"LoggingDriver": "string",
"CgroupDriver": "cgroupfs",
"CgroupVersion": "1",
"NEventsListener": 30,
"KernelVersion": "4.9.38-moby",
"OperatingSystem": "Alpine Linux v3.5",
"OSVersion": "16.04",
"OSType": "linux",
"Architecture": "x86_64",
"NCPU": 4,
"MemTotal": 2095882240,
"IndexServerAddress": "https://index.docker.io/v1/",
"RegistryConfig": {
"AllowNondistributableArtifactsCIDRs": [ ],
"AllowNondistributableArtifactsHostnames": [ ],
"InsecureRegistryCIDRs": [
"::1/128",
"127.0.0.0/8"
],
"IndexConfigs": {
"127.0.0.1:5000": {
"Name": "127.0.0.1:5000",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"[2001:db8:a0b:12f0::1]:80": {
"Name": "[2001:db8:a0b:12f0::1]:80",
"Mirrors": [ ],
"Secure": false,
"Official": false
},
"docker.io": {
"Name": "docker.io",
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/"
],
"Secure": true,
"Official": true
},
"registry.internal.corp.example.com:3000": {
"Name": "registry.internal.corp.example.com:3000",
"Mirrors": [ ],
"Secure": false,
"Official": false
}
},
"Mirrors": [
"https://hub-mirror.corp.example.com:5000/",
"https://[2001:db8:a0b:12f0::1]/"
]
},
"GenericResources": [
{
"DiscreteResourceSpec": {
"Kind": "SSD",
"Value": 3
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID1"
}
},
{
"NamedResourceSpec": {
"Kind": "GPU",
"Value": "UUID2"
}
}
],
"HttpProxy": "http://xxxxx:xxxxx@proxy.corp.example.com:8080",
"HttpsProxy": "https://xxxxx:xxxxx@proxy.corp.example.com:4443",
"NoProxy": "*.local, 169.254/16",
"Name": "node5.corp.example.com",
"Labels": [
"storage=ssd",
"production"
],
"ExperimentalBuild": true,
"ServerVersion": "24.0.2",
"Runtimes": {
"runc": {
"path": "runc"
},
"runc-master": {
"path": "/go/bin/runc"
},
"custom": {
"path": "/usr/local/bin/my-oci-runtime",
"runtimeArgs": [
"--debug",
"--systemd-cgroup=false"
]
}
},
"DefaultRuntime": "runc",
"Swarm": {
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"NodeAddr": "10.0.0.46",
"LocalNodeState": "active",
"ControlAvailable": true,
"Error": "",
"RemoteManagers": [
{
"NodeID": "71izy0goik036k48jg985xnds",
"Addr": "10.0.0.158:2377"
},
{
"NodeID": "79y6h1o4gv8n120drcprv5nmc",
"Addr": "10.0.0.159:2377"
},
{
"NodeID": "k67qz4598weg5unwwffg6z1m1",
"Addr": "10.0.0.46:2377"
}
],
"Nodes": 4,
"Managers": 3,
"Cluster": {
"ID": "abajmipo7b4xz5ip2nrla6b11",
"Version": {
"Index": 373531
},
"CreatedAt": "2016-08-18T10:44:24.496525531Z",
"UpdatedAt": "2017-08-09T07:09:37.632105588Z",
"Spec": {
"Name": "default",
"Labels": {
"com.example.corp.type": "production",
"com.example.corp.department": "engineering"
},
"Orchestration": {
"TaskHistoryRetentionLimit": 10
},
"Raft": {
"SnapshotInterval": 10000,
"KeepOldSnapshots": 0,
"LogEntriesForSlowFollowers": 500,
"ElectionTick": 3,
"HeartbeatTick": 1
},
"Dispatcher": {
"HeartbeatPeriod": 5000000000
},
"CAConfig": {
"NodeCertExpiry": 7776000000000000,
"ExternalCAs": [
{
"Protocol": "cfssl",
"URL": "string",
"Options": {
"property1": "string",
"property2": "string"
},
"CACert": "string"
}
],
"SigningCACert": "string",
"SigningCAKey": "string",
"ForceRotate": 0
},
"EncryptionConfig": {
"AutoLockManagers": false
},
"TaskDefaults": {
"LogDriver": {
"Name": "json-file",
"Options": {
"max-file": "10",
"max-size": "100m"
}
}
}
},
"TLSInfo": {
"TrustRoot": "-----BEGIN CERTIFICATE-----\nMIIBajCCARCgAwIBAgIUbYqrLSOSQHoxD8CwG6Bi2PJi9c8wCgYIKoZIzj0EAwIw\nEzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNDI0MjE0MzAwWhcNMzcwNDE5MjE0\nMzAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH\nA0IABJk/VyMPYdaqDXJb/VXh5n/1Yuv7iNrxV3Qb3l06XD46seovcDWs3IZNV1lf\n3Skyr0ofcchipoiHkXBODojJydSjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB\nAf8EBTADAQH/MB0GA1UdDgQWBBRUXxuRcnFjDfR/RIAUQab8ZV/n4jAKBggqhkjO\nPQQDAgNIADBFAiAy+JTe6Uc3KyLCMiqGl2GyWGQqQDEcO3/YG36x7om65AIhAJvz\npxv6zFeVEkAEEkqIYi0omA9+CjanB/6Bz4n1uw8H\n-----END CERTIFICATE-----\n",
"CertIssuerSubject": "MBMxETAPBgNVBAMTCHN3YXJtLWNh",
"CertIssuerPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmT9XIw9h1qoNclv9VeHmf/Vi6/uI2vFXdBveXTpcPjqx6i9wNazchk1XWV/dKTKvSh9xyGKmiIeRcE4OiMnJ1A=="
},
"RootRotationInProgress": false,
"DataPathPort": 4789,
"DefaultAddrPool": [ [
"10.10.0.0/16",
"20.20.0.0/16"
]
],
"SubnetSize": 24
}
},
"LiveRestoreEnabled": false,
"Isolation": "default",
"InitBinary": "docker-init",
"ContainerdCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"RuncCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"InitCommit": {
"ID": "cfb82a876ecc11b5ca0977d1733adbe58599088a",
"Expected": "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
},
"SecurityOptions": [
"name=apparmor",
"name=seccomp,profile=default",
"name=selinux",
"name=userns",
"name=rootless"
],
"ProductLicense": "Community Engine",
"DefaultAddressPools": [
{
"Base": "10.10.0.0/16",
"Size": "24"
}
],
"Warnings": [
"WARNING: No memory limit support"
]
}`

## [](#tag/System/operation/SystemVersion)Get version

Returns the version of Docker that is running and various information about the system that Docker is running on.

### Responses

/v1.43/version

### Response samples

* 200
* 500

Content type

application/json

`{
"Platform": {
"Name": "string"
},
"Components": [
{
"Name": "Engine",
"Version": "19.03.12",
"Details": { }
}
],
"Version": "19.03.12",
"ApiVersion": "1.40",
"MinAPIVersion": "1.12",
"GitCommit": "48a66213fe",
"GoVersion": "go1.13.14",
"Os": "linux",
"Arch": "amd64",
"KernelVersion": "4.19.76-linuxkit",
"Experimental": true,
"BuildTime": "2020-06-22T15:49:27.000000000+00:00"
}`

## [](#tag/System/operation/SystemPing)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.43/\_ping

## [](#tag/System/operation/SystemPingHead)Ping

This is a dummy endpoint you can use to test if the server is accessible.

### Responses

/v1.43/\_ping

## [](#tag/System/operation/SystemEvents)Monitor events

Stream real-time events from the server.

Various objects within Docker report events when something happens to them.

Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `exec_die`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, `update`, and `prune`

Images report these events: `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, `untag`, and `prune`

Volumes report these events: `create`, `mount`, `unmount`, `destroy`, and `prune`

Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, `remove`, and `prune`

The Docker daemon reports these events: `reload`

Services report these events: `create`, `update`, and `remove`

Nodes report these events: `create`, `update`, and `remove`

Secrets report these events: `create`, `update`, and `remove`

Configs report these events: `create`, `update`, and `remove`

The Builder reports `prune` events

##### query Parameters

|         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| since   | stringShow events created since this timestamp then stream new events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| until   | stringShow events created until this timestamp then stop streaming.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| filters | stringA JSON encoded value of filters (a `map[string][]string`) to process on the event list. Available filters:- `config=<string>` config name or ID
- `container=<string>` container name or ID
- `daemon=<string>` daemon name or ID
- `event=<string>` event type
- `image=<string>` image name or ID
- `label=<string>` image or container label
- `network=<string>` network name or ID
- `node=<string>` node ID
- `plugin`= plugin name or ID
- `scope`= local or swarm
- `secret=<string>` secret name or ID
- `service=<string>` service name or ID
- `type=<string>` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service`, `secret` or `config`
- `volume=<string>` volume name |

### Responses

/v1.43/events

### Response samples

* 200
* 400
* 500

Content type

application/json

`{
"Type": "container",
"Action": "create",
"Actor": {
"ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743",
"Attributes": {
"com.example.some-label": "some-label-value",
"image": "alpine:latest",
"name": "my-container"
}
},
"scope": "local",
"time": 1629574695,
"timeNano": 1629574695515050000
}`

## [](#tag/System/operation/SystemDataUsage)Get data usage information

##### query Parameters

|      |                                                                                                                           |
| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | Array of stringsItems Enum: "container" "image" "volume" "build-cache"Object types, for which to compute and return data. |

### Responses

/v1.43/system/df

### Response samples

* 200
* 500

Content type

application/json

`{
"LayersSize": 1092588,
"Images": [
{
"Id": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"ParentId": "",
"RepoTags": [
"busybox:latest"
],
"RepoDigests": [
"busybox@sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6"
],
"Created": 1466724217,
"Size": 1092588,
"SharedSize": 0,
"VirtualSize": 1092588,
"Labels": { },
"Containers": 1
}
],
"Containers": [
{
"Id": "e575172ed11dc01bfce087fb27bee502db149e1a0fad7c296ad300bbff178148",
"Names": [
"/top"
],
"Image": "busybox",
"ImageID": "sha256:2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749",
"Command": "top",
"Created": 1472592424,
"Ports": [ ],
"SizeRootFs": 1092588,
"Labels": { },
"State": "exited",
"Status": "Exited (0) 56 minutes ago",
"HostConfig": {
"NetworkMode": "default"
},
"NetworkSettings": {
"Networks": {
"bridge": {
"IPAMConfig": null,
"Links": null,
"Aliases": null,
"NetworkID": "d687bc59335f0e5c9ee8193e5612e8aee000c8c62ea170cfb99c098f95899d92",
"EndpointID": "8ed5115aeaad9abb174f68dcf135b49f11daf597678315231a32ca28441dec6a",
"Gateway": "172.18.0.1",
"IPAddress": "172.18.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": "02:42:ac:12:00:02"
}
}
},
"Mounts": [ ]
}
],
"Volumes": [
{
"Name": "my-volume",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/my-volume/_data",
"Labels": null,
"Scope": "local",
"Options": null,
"UsageData": {
"Size": 10920104,
"RefCount": 2
}
}
],
"BuildCache": [
{
"ID": "hw53o5aio51xtltp5xjp8v7fx",
"Parents": [ ],
"Type": "regular",
"Description": "pulled from docker.io/library/debian@sha256:234cb88d3020898631af0ccbbcca9a66ae7306ecd30c9720690858c1b007d2a0",
"InUse": false,
"Shared": true,
"Size": 0,
"CreatedAt": "2021-06-28T13:31:01.474619385Z",
"LastUsedAt": "2021-07-07T22:02:32.738075951Z",
"UsageCount": 26
},
{
"ID": "ndlpt0hhvkqcdfkputsk4cq9c",
"Parents": [
"ndlpt0hhvkqcdfkputsk4cq9c"
],
"Type": "regular",
"Description": "mount / from exec /bin/sh -c echo 'Binary::apt::APT::Keep-Downloaded-Packages \"true\";' > /etc/apt/apt.conf.d/keep-cache",
"InUse": false,
"Shared": true,
"Size": 51,
"CreatedAt": "2021-06-28T13:31:03.002625487Z",
"LastUsedAt": "2021-07-07T22:02:32.773909517Z",
"UsageCount": 26
}
]
}`

## [](#tag/Distribution)Distribution

## [](#tag/Distribution/operation/DistributionInspect)Get image information from the registry

Return image digest and platform information by contacting the registry.

##### path Parameters

|              |                        |
| ------------ | ---------------------- |
| namerequired | stringImage name or id |

### Responses

/v1.43/distribution/{name}/json

### Response samples

* 200
* 401
* 500

Content type

application/json

`{
"Descriptor": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
"size": 3987495
},
"Platforms": [
{
"architecture": "arm",
"os": "windows",
"os.version": "10.0.19041.1165",
"os.features": [
"win32k"
],
"variant": "v7"
}
]
}`

## [](#tag/Session)Session

## [](#tag/Session/operation/Session)Initialize interactive session

Start a new interactive session with a server. Session allows server to call back to the client for advanced capabilities.

### Hijacking

This endpoint hijacks the HTTP connection to HTTP2 transport that allows the client to expose gPRC services on that connection.

For example, the client sends this request to upgrade the connection:

```
POST /session HTTP/1.1
Upgrade: h2c
Connection: Upgrade
```

The Docker daemon responds with a `101 UPGRADED` response follow with the raw stream:

```
HTTP/1.1 101 UPGRADED
Connection: Upgrade
Upgrade: h2c
```

### Responses

/v1.43/session

----
url: https://docs.docker.com/get-started/
----

# Get started

***

***

If you're new to Docker, this section guides you through the essential resources to get started.

Follow the guides to help you get started and learn how Docker can optimize your development workflows.

For more advanced concepts and scenarios in Docker, see [Guides](/guides/).

## [Foundations of Docker](#foundations-of-docker)

Install Docker and jump into discovering what Docker is.

### [Get Docker](/get-started/get-docker/)

[Choose the best installation path for your setup.](/get-started/get-docker/)

### [What is Docker?](/get-started/docker-overview/)

[Learn about the Docker platform.](/get-started/docker-overview/)

Learn the foundational concepts and workflows of Docker.

### [Introduction](/get-started/introduction/)

[Get started with the basics and the benefits of containerizing your applications.](/get-started/introduction/)

### [Docker concepts](/get-started/docker-concepts/the-basics/what-is-a-container/)

[Gain a better understanding of foundational Docker concepts.](/get-started/docker-concepts/the-basics/what-is-a-container/)

### [Docker workshop](/get-started/workshop/)

[Get guided through a 45-minute workshop to learn about Docker.](/get-started/workshop/)

----
url: https://docs.docker.com/reference/cli/docker/model/launch/
----

# docker model launch

***

| Description | Launch an app configured to use Docker Model Runner |
| ----------- | --------------------------------------------------- |
| Usage       | `docker model launch [APP] [-- APP_ARGS...]`        |

## [Description](#description)

Launch an app configured to use Docker Model Runner.

Without arguments, lists all supported apps.

Supported apps: anythingllm, claude, codex, openclaw, opencode, openwebui

Examples: docker model launch docker model launch opencode docker model launch claude -- --help docker model launch openwebui --port 3000 docker model launch claude --config

## [Options](#options)

| Option      | Default | Description                                     |
| ----------- | ------- | ----------------------------------------------- |
| `--config`  |         | Print configuration without launching           |
| `--detach`  |         | Run containerized app in background             |
| `--dry-run` |         | Print what would be executed without running it |
| `--image`   |         | Override container image for containerized apps |
| `--model`   |         | Model to use (for opencode)                     |
| `--port`    |         | Host port to expose (web UIs)                   |

----
url: https://docs.docker.com/engine/release-notes/17.03/
----

# Docker Engine 17.03 release notes

***

Table of contents

***

## [17.03.3-ce](#17033-ce)

2018-08-30

### [Runtime](#runtime)

* Update go-connections to d217f8e [#28](https://github.com/docker/engine/pull/28)

## [17.03.2-ce](#17032-ce)

2017-05-29

### [Networking](#networking)

* Fix a concurrency issue preventing network creation [#33273](https://github.com/moby/moby/pull/33273)

### [Runtime](#runtime-1)

* Relabel secrets path to avoid a Permission Denied on selinux enabled systems [#33236](https://github.com/moby/moby/pull/33236) (ref [#32529](https://github.com/moby/moby/pull/32529)
* Fix cases where local volume were not properly relabeled if needed [#33236](https://github.com/moby/moby/pull/33236) (ref [#29428](https://github.com/moby/moby/pull/29428))
* Fix an issue while upgrading if a plugin rootfs was still mounted [#33236](https://github.com/moby/moby/pull/33236) (ref [#32525](https://github.com/moby/moby/pull/32525))
* Fix an issue where volume wouldn't default to the `rprivate` propagation mode [#33236](https://github.com/moby/moby/pull/33236) (ref [#32851](https://github.com/moby/moby/pull/32851))
* Fix a panic that could occur when a volume driver could not be retrieved [#33236](https://github.com/moby/moby/pull/33236) (ref [#32347](https://github.com/moby/moby/pull/32347))

- Add a warning in `docker info` when the `overlay` or `overlay2` graphdriver is used on a filesystem without `d_type` support [#33236](https://github.com/moby/moby/pull/33236) (ref [#31290](https://github.com/moby/moby/pull/31290))

* Fix an issue with backporting mount spec to older volumes [#33207](https://github.com/moby/moby/pull/33207)
* Fix issue where a failed unmount can lead to data loss on local volume remove [#33120](https://github.com/moby/moby/pull/33120)

### [Swarm Mode](#swarm-mode)

* Fix a case where tasks could get killed unexpectedly [#33118](https://github.com/moby/moby/pull/33118)
* Fix an issue preventing to deploy services if the registry cannot be reached despite the needed images being locally present [#33117](https://github.com/moby/moby/pull/33117)

## [17.03.1-ce](#17031-ce)

2017-03-27

### [Remote API (v1.27) & Client](#remote-api-v127--client)

* Fix autoremove on older api [#31692](https://github.com/docker/docker/pull/31692)
* Fix default network customization for a stack [#31258](https://github.com/docker/docker/pull/31258/)
* Correct CPU usage calculation in presence of offline CPUs and newer Linux [#31802](https://github.com/docker/docker/pull/31802)
* Fix issue where service healthcheck is `{}` in remote API [#30197](https://github.com/docker/docker/pull/30197)

### [Runtime](#runtime-2)

* Update runc to 54296cf40ad8143b62dbcaa1d90e520a2136ddfe [#31666](https://github.com/docker/docker/pull/31666)
* Ignore cgroup2 mountpoints [opencontainers/runc#1266](https://github.com/opencontainers/runc/pull/1266)
* Update containerd to 4ab9917febca54791c5f071a9d1f404867857fcc [#31662](https://github.com/docker/docker/pull/31662) [#31852](https://github.com/docker/docker/pull/31852)
* Register healtcheck service before calling restore() [docker/containerd#609](https://github.com/docker/containerd/pull/609)
* Fix `docker exec` not working after unattended upgrades that reload apparmor profiles [#31773](https://github.com/docker/docker/pull/31773)
* Fix unmounting layer without merge dir with Overlay2 [#31069](https://github.com/docker/docker/pull/31069)
* Do not ignore "volume in use" errors when force-delete [#31450](https://github.com/docker/docker/pull/31450)

### [Swarm Mode](#swarm-mode-1)

* Update swarmkit to 17756457ad6dc4d8a639a1f0b7a85d1b65a617bb [#31807](https://github.com/docker/docker/pull/31807)
* Scheduler now correctly considers tasks which have been assigned to a node but aren't yet running [docker/swarmkit#1980](https://github.com/docker/swarmkit/pull/1980)
* Allow removal of a network when only dead tasks reference it [docker/swarmkit#2018](https://github.com/docker/swarmkit/pull/2018)
* Retry failed network allocations less aggressively [docker/swarmkit#2021](https://github.com/docker/swarmkit/pull/2021)
* Avoid network allocation for tasks that are no longer running [docker/swarmkit#2017](https://github.com/docker/swarmkit/pull/2017)
* Bookkeeping fixes inside network allocator allocator [docker/swarmkit#2019](https://github.com/docker/swarmkit/pull/2019) [docker/swarmkit#2020](https://github.com/docker/swarmkit/pull/2020)

### [Windows](#windows)

* Cleanup HCS on restore [#31503](https://github.com/docker/docker/pull/31503)

## [17.03.0-ce](#17030-ce)

2017-03-01

> Important
>
> Starting with this release, Docker is on a monthly release cycle and uses a new YY.MM versioning scheme to reflect this. Two channels are available: monthly and quarterly. Any given monthly release will only receive security and bugfixes until the next monthly release is available. Quarterly releases receive security and bugfixes for 4 months after initial release. This release includes bugfixes for 1.13.1 but there are no major feature additions and the API version stays the same. Upgrading from Docker 1.13.1 to 17.03.0 is expected to be simple and low-risk.

### [Client](#client)

* Fix panic in `docker stats --format` [#30776](https://github.com/docker/docker/pull/30776)

### [Contrib](#contrib)

* Update various `bash` and `zsh` completion scripts [#30823](https://github.com/docker/docker/pull/30823), [#30945](https://github.com/docker/docker/pull/30945) and more...
* Block obsolete socket families in default seccomp profile - mitigates unpatched kernels' CVE-2017-6074 [#29076](https://github.com/docker/docker/pull/29076)

### [Networking](#networking-1)

* Fix bug on overlay encryption keys rotation in cross-datacenter swarm [#30727](https://github.com/docker/docker/pull/30727)
* Fix side effect panic in overlay encryption and network control plane communication failure ("No installed keys could decrypt the message") on frequent swarm leader re-election [#25608](https://github.com/docker/docker/pull/25608)
* Several fixes around system responsiveness and datapath programming when using overlay network with external kv-store [docker/libnetwork#1639](https://github.com/docker/libnetwork/pull/1639), [docker/libnetwork#1632](https://github.com/docker/libnetwork/pull/1632) and more...
* Discard incoming plain vxlan packets for encrypted overlay network [#31170](https://github.com/docker/docker/pull/31170)
* Release the network attachment on allocation failure [#31073](https://github.com/docker/docker/pull/31073)
* Fix port allocation when multiple published ports map to the same target port [docker/swarmkit#1835](https://github.com/docker/swarmkit/pull/1835)

### [Runtime](#runtime-3)

* Fix a deadlock in docker logs [#30223](https://github.com/docker/docker/pull/30223)
* Fix CPU spin waiting for log write events [#31070](https://github.com/docker/docker/pull/31070)
* Fix a possible crash when using journald [#31231](https://github.com/docker/docker/pull/31231) [#31263](https://github.com/docker/docker/pull/31263)
* Fix a panic on close of nil channel [#31274](https://github.com/docker/docker/pull/31274)
* Fix duplicate mount point for `--volumes-from` in `docker run` [#29563](https://github.com/docker/docker/pull/29563)
* Fix `--cache-from` does not cache last step [#31189](https://github.com/docker/docker/pull/31189)

### [Swarm Mode](#swarm-mode-2)

* Shutdown leaks an error when the container was never started [#31279](https://github.com/docker/docker/pull/31279)
* Fix possibility of tasks getting stuck in the "NEW" state during a leader failover [docker/swarmkit#1938](https://github.com/docker/swarmkit/pull/1938)
* Fix extraneous task creations for global services that led to confusing replica counts in `docker service ls` [docker/swarmkit#1957](https://github.com/docker/swarmkit/pull/1957)
* Fix problem that made rolling updates slow when `task-history-limit` was set to 1 [docker/swarmkit#1948](https://github.com/docker/swarmkit/pull/1948)
* Restart tasks elsewhere, if appropriate, when they are shut down as a result of nodes no longer satisfying constraints [docker/swarmkit#1958](https://github.com/docker/swarmkit/pull/1958)
* (experimental)

----
url: https://docs.docker.com/reference/cli/docker/service/inspect/
----

# docker service inspect

***

| Description | Display detailed information on one or more services    |
| ----------- | ------------------------------------------------------- |
| Usage       | `docker service inspect [OPTIONS] SERVICE [SERVICE...]` |

Swarm This command works with the Swarm orchestrator.

## [Description](#description)

Inspects the specified service.

By default, this renders all results in a JSON array. If a format is specified, the given template will be executed for each result.

Go's [text/template](https://pkg.go.dev/text/template) package describes all the details of the format.

> Note
>
> This is a cluster management command, and must be executed on a swarm manager node. To learn about managers and workers, refer to the [Swarm mode section](/engine/swarm/) in the documentation.

## [Options](#options)

| Option                    | Default | Description                                                                                                                                                                                                                             |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`-f, --format`](#format) |         | Format output using a custom template: 'json': Print in JSON format 'TEMPLATE': Print output using the given Go template. Refer to <https://docs.docker.com/go/formatting/> for more information about formatting output with templates |
| [`--pretty`](#pretty)     |         | Print the information in a human friendly format                                                                                                                                                                                        |

## [Examples](#examples)

### [Inspect a service by name or ID](#inspect-a-service-by-name-or-id)

You can inspect a service, either by its *name*, or *ID*

For example, given the following service;

```console
$ docker service ls
ID            NAME   MODE        REPLICAS  IMAGE
dmu1ept4cxcf  redis  replicated  3/3       redis:7.4.1
```

Both `docker service inspect redis`, and `docker service inspect dmu1ept4cxcf` produce the same result:

```console
$ docker service inspect redis
```

The output is in JSON format, for example:

```json
[
  {
    "ID": "dmu1ept4cxcfe8k8lhtux3ro3",
    "Version": {
      "Index": 12
    },
    "CreatedAt": "2016-06-17T18:44:02.558012087Z",
    "UpdatedAt": "2016-06-17T18:44:02.558012087Z",
    "Spec": {
      "Name": "redis",
      "TaskTemplate": {
        "ContainerSpec": {
          "Image": "redis:7.4.1"
        },
        "Resources": {
          "Limits": {},
          "Reservations": {}
        },
        "RestartPolicy": {
          "Condition": "any",
          "MaxAttempts": 0
        },
        "Placement": {}
      },
      "Mode": {
        "Replicated": {
          "Replicas": 1
        }
      },
      "UpdateConfig": {},
      "EndpointSpec": {
        "Mode": "vip"
      }
    },
    "Endpoint": {
      "Spec": {}
    }
  }
]
```

```console
$ docker service inspect dmu1ept4cxcf

[
  {
    "ID": "dmu1ept4cxcfe8k8lhtux3ro3",
    "Version": {
      "Index": 12
    },
    ...
  }
]
```

### [Formatting (--pretty)](#pretty)

You can print the inspect output in a human-readable format instead of the default JSON output, by using the `--pretty` option:

```console
$ docker service inspect --pretty frontend

ID:     c8wgl7q4ndfd52ni6qftkvnnp
Name:   frontend
Labels:
 - org.example.projectname=demo-app
Service Mode:   REPLICATED
 Replicas:      5
Placement:
UpdateConfig:
 Parallelism:   0
 On failure:    pause
 Max failure ratio: 0
ContainerSpec:
 Image:     nginx:alpine
Resources:
Networks:   net1
Endpoint Mode:  vip
Ports:
 PublishedPort = 4443
  Protocol = tcp
  TargetPort = 443
  PublishMode = ingress
```

You can also use `--format pretty` for the same effect.

### [Format the output (--format)](#format)

You can use the --format option to obtain specific information about a The `--format` option can be used to obtain specific information about a service. For example, the following command outputs the number of replicas of the "redis" service.

```console
$ docker service inspect --format='{{.Spec.Mode.Replicated.Replicas}}' redis

10
```

----
url: https://docs.docker.com/build-cloud/optimization/
----

# Optimize for building in the cloud

***

Table of contents

***

Docker Build Cloud runs your builds remotely, and not on the machine where you invoke the build. This means that file transfers between the client and builder happen over the network.

Transferring files over the network has a higher latency and lower bandwidth than local transfers. Docker Build Cloud has several features to mitigate this:

* It uses attached storage volumes for build cache, which makes reading and writing cache very fast.
* Loading build results back to the client only pulls the layers that were changed compared to previous builds.

Despite these optimizations, building remotely can still yield slow context transfers and image loads, for large projects or if the network connection is slow. Here are some ways that you can optimize your builds to make the transfer more efficient:

* [Dockerignore files](#dockerignore-files)
* [Slim base images](#slim-base-images)
* [Multi-stage builds](#multi-stage-builds)
* [Fetch remote files in build](#fetch-remote-files-in-build)
* [Multi-threaded tools](#multi-threaded-tools)

For more information on how to optimize your builds, see [Building best practices](https://docs.docker.com/build/building/best-practices/).

### [Dockerignore files](#dockerignore-files)

Using a [`.dockerignore` file](https://docs.docker.com/build/concepts/context/#dockerignore-files), you can be explicit about which local files you don’t want to include in the build context. Files caught by the glob patterns you specify in your ignore-file aren't transferred to the remote builder.

Some examples of things you might want to add to your `.dockerignore` file are:

* `.git` — skip sending the version control history in the build context. Note that this means you won’t be able to run Git commands in your build steps, such as `git rev-parse`.
* Directories containing build artifacts, such as binaries. Build artifacts created locally during development.
* Vendor directories for package managers, such as `node_modules`.

In general, the contents of your `.dockerignore` file should be similar to what you have in your `.gitignore`.

### [Slim base images](#slim-base-images)

Selecting smaller images for your `FROM` instructions in your Dockerfile can help reduce the size of the final image. The [Alpine image](https://hub.docker.com/_/alpine) is a good example of a minimal Docker image that provides all of the OS utilities you would expect from a Linux container.

There’s also the [special `scratch` image](https://hub.docker.com/_/scratch), which contains nothing at all. Useful for creating images of statically linked binaries, for example.

### [Multi-stage builds](#multi-stage-builds)

[Multi-stage builds](/build/building/multi-stage/) can make your build run faster, because stages can run in parallel. It can also make your end-result smaller. Write your Dockerfile in such a way that the final runtime stage uses the smallest possible base image, with only the resources that your program requires to run.

It’s also possible to [copy resources from other images or stages](/build/building/multi-stage/#name-your-build-stages), using the Dockerfile `COPY --from` instruction. This technique can reduce the number of layers, and the size of those layers, in the final stage.

### [Fetch remote files in build](#fetch-remote-files-in-build)

When possible, you should fetch files from a remote location in the build, rather than bundling the files into the build context. Downloading files on the Docker Build Cloud server directly is better, because it will likely be faster than transferring the files with the build context.

You can fetch remote files during the build using the [Dockerfile `ADD` instruction](/reference/dockerfile/#add), or in your `RUN` instructions with tools like `wget` and `rsync`.

### [Multi-threaded tools](#multi-threaded-tools)

Some tools that you use in your build instructions may not utilize multiple cores by default. One such example is `make` which uses a single thread by default, unless you specify the `make --jobs=<n>` option. For build steps involving such tools, try checking if you can optimize the execution with parallelization.

----
url: https://docs.docker.com/build/debug/opentelemetry/
----

# OpenTelemetry support

***

***

Both Buildx and BuildKit support [OpenTelemetry](https://opentelemetry.io/).

To capture the trace to [Jaeger](https://github.com/jaegertracing/jaeger), set `JAEGER_TRACE` environment variable to the collection address using a `driver-opt`.

First create a Jaeger container:

```console
$ docker run -d --name jaeger -p "6831:6831/udp" -p "16686:16686" --restart unless-stopped jaegertracing/all-in-one
```

Then [create a `docker-container` builder](https://docs.docker.com/build/builders/drivers/docker-container/) that will use the Jaeger instance via the `JAEGER_TRACE` environment variable:

```console
$ docker buildx create --use \
  --name mybuilder \
  --driver docker-container \
  --driver-opt "network=host" \
  --driver-opt "env.JAEGER_TRACE=localhost:6831"
```

Boot and [inspect `mybuilder`](/reference/cli/docker/buildx/inspect/):

```console
$ docker buildx inspect --bootstrap
```

Buildx commands should be traced at `http://127.0.0.1:16686/`:

----
url: https://docs.docker.com/guides/nodejs/
----

# Node.js language-specific guide

Table of contents

***

This guide explains how to containerize Node.js applications using Docker.

**Time to complete** 20 minutes

[Node.js](https://nodejs.org/en) is a JavaScript runtime for building web applications. This guide shows you how to containerize a TypeScript Node.js application with a React frontend and PostgreSQL database.

The sample application is a modern full-stack Todo application featuring:

* **Backend**: Express.js with TypeScript, PostgreSQL database, and RESTful API
* **Frontend**: React.js with Vite and Tailwind CSS 4

> **Acknowledgment**
>
> Docker extends its sincere gratitude to [Kristiyan Velkov](https://www.linkedin.com/in/kristiyan-velkov-763130b3/) for authoring this guide. As a Docker Captain and experienced Full-stack engineer, his expertise in Docker, DevOps, and modern web development has made this resource invaluable for the community, helping developers navigate and optimize their Docker workflows.

***

## [What will you learn?](#what-will-you-learn)

In this guide, you will learn how to:

* Containerize and run a Node.js application using Docker.
* Run tests inside a Docker container.
* Set up a development container environment.
* Configure GitHub Actions for CI/CD with Docker.
* Deploy your Dockerized Node.js app to Kubernetes.

To begin, you’ll start by containerizing an existing Node.js application.

***

## [Prerequisites](#prerequisites)

Before you begin, make sure you're familiar with the following:

* Basic understanding of [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) and [TypeScript](https://www.typescriptlang.org/).
* Basic knowledge of [Node.js](https://nodejs.org/en), [npm](https://docs.npmjs.com/about-npm), and [React](https://react.dev/) for modern web development.
* Understanding of Docker concepts such as images, containers, and Dockerfiles. If you're new to Docker, start with the [Docker basics](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) guide.
* Familiarity with [Express.js](https://expressjs.com/) for backend API development.

Once you've completed the Node.js getting started modules, you’ll be ready to containerize your own Node.js application using the examples and instructions provided in this guide.

## [Modules](#modules)

1. [Containerize](https://docs.docker.com/guides/nodejs/containerize/)

   Learn how to containerize a Node.js application with Docker by creating an optimized, production-ready image using best practices for performance, security, and scalability.

2. [Develop your app](https://docs.docker.com/guides/nodejs/develop/)

   Learn how to develop your Node.js application locally using containers.

3. [Run your tests](https://docs.docker.com/guides/nodejs/run-tests/)

   Learn how to run your Node.js tests in a container.

4. [Deploy your app](https://docs.docker.com/guides/nodejs/deploy/)

   Learn how to deploy your containerized Node.js application to Kubernetes with production-ready configuration

5. [GitHub Actions CI](https://docs.docker.com/guides/nodejs/configure-github-actions/)

   Learn how to configure CI/CD using GitHub Actions for your Node.js application.

----
url: https://docs.docker.com/scout/integrations/registry/artifactory/
----

# Integrate Docker Scout with Artifactory Container Registry

***

Table of contents

***

Integrating Docker Scout with JFrog Artifactory lets you index and analyze images from Artifactory. This integration is powered by a long-running `docker scout watch` process. It pulls images from your selected repositories (optionally filtered), can receive webhook callbacks from Artifactory, and pushes image data to Docker Scout. View results in the Docker Scout Dashboard or with `docker scout` CLI.

## [How it works](#how-it-works)

You run [`docker scout watch`](/reference/cli/docker/scout/watch/) on a host you control and configure the Artifactory-specific registry string via `--registry "key=value,..."`. The watch process can:

* Watch specific repositories or an entire registry
* Optionally ingest all existing images once
* Periodically refresh repository lists
* Receive webhook callbacks from Artifactory on a local port you choose

After the integration, Docker Scout automatically pulls and analyzes images that you push to the Artifactory registry. Metadata about your images are stored on the Docker Scout platform, but Docker Scout doesn't store the container images themselves. For more information about how Docker Scout handles image data, see [Data handling](https://docs.docker.com/scout/deep-dive/data-handling/).

### [Artifactory-specific registry string options](#artifactory-specific-registry-string-options)

These `type=artifactory` options override the generic registry handling for the `--registry` option:

| Key              | Required | Description                                                                                |
| ---------------- | -------- | ------------------------------------------------------------------------------------------ |
| `type`           | Yes      | Must be `artifactory`.                                                                     |
| `registry`       | Yes      | Docker/OCI registry hostname (e.g., `example.jfrog.io`).                                   |
| `api`            | Yes      | Artifactory REST API base URL (e.g., `https://example.jfrog.io/artifactory`).              |
| `repository`     | Yes      | Repository to watch (replaces `--repository`).                                             |
| `includes`       | No       | Globs to include (e.g., `*/frontend*`).                                                    |
| `excludes`       | No       | Globs to exclude (e.g., `*/legacy/*`).                                                     |
| `port`           | No       | Local port to listen on for webhook callbacks.                                             |
| `subdomain-mode` | No       | `true` or `false`; matches Artifactory’s Docker layout (subdomain versus repository-path). |

## [Integrate an Artifactory registry](#integrate-an-artifactory-registry)

Use the following steps to integrate your Artifactory registry with Docker Scout.

1. Pick the host on which to run `docker scout watch`.

   The host must have local or network access to your private registry and be able to access the Scout API (`https://api.scout.docker.com`) over the internet. If you're using webhook callbacks, Artifactory must also be able to reach the Scout client host on the configured port. Override the `--workers` option (default: `3`) for optimal performance based on the size of the host and the expected workload.

2. Ensure you are running the latest version of Scout.

   Check your current version:

   ```console
   $ docker scout version
   ```

   If necessary, [install the latest version of Scout](https://docs.docker.com/scout/install/).

3. Set up your Artifactory credentials.

   Store the credentials that the Scout client will use to authenticate with Artifactory. The following is an example using environment variables. Replace `<user>` and `<password-or-access-token>` with your actual values.

   ```console
   $ export DOCKER_SCOUT_ARTIFACTORY_API_USER=<user>
   $ export DOCKER_SCOUT_ARTIFACTORY_API_PASSWORD=<password-or-access-token>
   ```

   > Tip
   >
   > As a best practice, create a dedicated user with read-only access and use an access token instead of a password.

   Store the credential that Artifactory will use to authenticate webhook callbacks. The following is an example using an environment variable. Replace `<random-64-128-character-secret>` with an actual secret.

   ```console
   $ export DOCKER_SCOUT_ARTIFACTORY_WEBHOOK_SECRET=<random-64-128-character-secret>
   ```

   > Tip
   >
   > As a best practice, generate a high-entropy random string of 64-128 characters.

4. Set up your Scout credentials.

   1. Generate an organization access token for accessing Scout. For more details, see [Create an organization access token](/enterprise/security/access-tokens/#create-an-organization-access-token).

   2. Sign in to Docker using the organization access token.

      ```console
      $ docker login --username <your_organization_name>
      ```

      When prompted for a password, paste the organization access token you generated.

   3. Connect your local Docker environment to your organization's Docker Scout service.

      ```console
      $ docker scout enroll <your_organization_name>
      ```

5. Index existing images. You only need to do this once.

   Run `docker scout watch` with the `--all-images` option to index all images in the specified Artifactory repository. The following is an example command:

   ```console
   $ docker scout watch --registry \
   "type=artifactory,registry=example.jfrog.io,api=https://example.jfrog.io/artifactory,include=*/frontend*,exclude=*/dta/*,repository=docker-local,port=9000,subdomain-mode=true" \
   --all-images
   ```

6. Confirm the images have been indexed by viewing them on the [Scout Dashboard](https://scout.docker.com/).

7. Configure Artifactory callbacks.

   In your Artifactory UI or via REST API, configure webhooks for image push/update events. Set the endpoint to your `docker scout watch` host and port, and include the `DOCKER_SCOUT_ARTIFACTORY_WEBHOOK_SECRET` for authentication.

   For more information, see the [JFrog Artifactory Webhooks documentation](https://jfrog.com/help/r/jfrog-platform-administration-documentation/webhooks) or the [JFrog Artifactory REST API Webhooks documentation](https://jfrog.com/help/r/jfrog-rest-apis/webhooks).

8. Continuously watch for new or updated images.

   Run `docker scout watch` with the `--refresh-registry` option to watch for new images to index.

   The `docker scout watch` command is a long-running process that must continue running indefinitely in the background to receive webhooks and watch for new images. If you run it directly in a terminal and close the session, the process will stop.

   The following is an example command. You can run the process as a system service, for example using `systemd` or `nohup`, to ensure it continues running in the background.

   ```console
   $ docker scout watch --registry \
   "type=artifactory,registry=example.jfrog.io,api=https://example.jfrog.io/artifactory,include=*/frontend*,exclude=*/dta/*,repository=docker-local,port=9000,subdomain-mode=true" \
   --refresh-registry
   ```

9. Optional. Set up Scout integration for real-time notifications from popular collaboration platforms. For details, see [Integrate Docker Scout with Slack](https://docs.docker.com/scout/integrations/team-collaboration/slack/).

----
url: https://docs.docker.com/dhi/get-started/
----

# Docker Hardened Images quickstart

***

Table of contents

***

This guide shows you how to go from zero to running a Docker Hardened Image (DHI) using a real example. At the end, you'll compare the DHI to a standard Docker image to better understand the differences. While the steps use a specific image as an example, they can be applied to any DHI.

This quickstart uses DHI Community images from `dhi.io`. You sign in with your Docker account, pull and run an image, and compare it with a Docker Official Image.

> Note
>
> If you have a DHI Select or Enterprise subscription, see [Get started with DHI Select and Enterprise](https://docs.docker.com/dhi/how-to/select-enterprise/) instead. Select and Enterprise use mirrored repositories in your organization namespace on Docker Hub to enable customization, SLA-backed security updates, and access to compliance variants.

## [Step 1: Find an image to use](#step-1-find-an-image-to-use)

1. Go to the Hardened Images catalog in [Docker Hub](https://hub.docker.com/hardened-images/catalog).
2. Use the search bar or filters to find an image (for example, `python`, `node`, or `golang`). For this example, search for `python`.
3. Select the Python repository to view its details.

Continue to the next step to pull and run the image. To dive deeper into searching and evaluating images, see [Search and evaluate Docker Hardened Images](https://docs.docker.com/dhi/how-to/explore/).

## [Step 2: Pull and run the image](#step-2-pull-and-run-the-image)

You can pull and run a DHI like any other Docker image. Note that Docker Hardened Images are designed to be minimal and secure, so they may not include all the tools or libraries you expect in a typical image. You can view the typical differences in [Considerations when adopting DHIs](https://docs.docker.com/dhi/how-to/use/#considerations-when-adopting-dhis).

The following example demonstrates that you can run the Python image and execute a simple Python command just like you would with any other Docker image:

1. Open a terminal and sign in to the Docker Hardened Images registry using your Docker account credentials.

   ```console
   $ docker login dhi.io
   ```

   > Tip
   >
   > If you don't have a Docker account, [create a free account](https://hub.docker.com/signup) to get started.

2. Pull the image:

   ```console
   $ docker pull dhi.io/python:3.13
   ```

3. Run the image to confirm everything works:

   ```console
   $ docker run --rm dhi.io/python:3.13 python -c "print('Hello from DHI')"
   ```

   This starts a container from the `python:3.13` image and runs a simple Python script that prints `Hello from DHI`.

To dive deeper into using images, see:

* [Use a Docker Hardened Image](https://docs.docker.com/dhi/how-to/use/) for general usage
* [Use a Helm chart](https://docs.docker.com/dhi/how-to/helm/) for deploying with Helm

## [Step 3: Compare with other images](#step-3-compare-with-other-images)

You can quickly compare DHIs with other images to see the security improvements and differences. This comparison helps you understand the value of using hardened images.

Run the following command to compare the Docker Hardened Image for Python with the non-hardened Docker Official Image for Python from Docker Hub. Look for the `## Overview` section in the output for a summary comparison.

```console
$ docker scout compare dhi.io/python:3.13 \
    --to python:3.13 \
    --platform linux/amd64 \
    --ignore-unchanged
```

The `## Overview` section of the output looks similar to the following:

```plaintext
  ## Overview

                      │                    Analyzed Image                     │               Comparison Image
  ────────────────────┼───────────────────────────────────────────────────────┼───────────────────────────────────────────────
    Target            │  dhi.io/python:3.13                                   │  python:3.13
      digest          │  c215e9da9f84                                         │  7f48e892134c
      tag             │  3.13                                                 │  3.13
      platform        │ linux/amd64                                           │ linux/amd64
      provenance      │ https://github.com/docker-hardened-images/definitions │ https://github.com/docker-library/python.git
                      │  77a629b3d0db035700206c2a4e7ed904e5902ea8             │  3f2d7e4c339ab883455b81a873519f1d0f2cd80a
      vulnerabilities │    0C     0H     0M     0L                            │    0C     1H     5M   141L     2?
                      │           -1     -5   -141     -2                     │
      size            │ 35 MB (-377 MB)                                       │ 412 MB
      packages        │ 80 (-530)                                             │ 610
                      │                                                       │
```

> Note
>
> This is example output. Your results may vary depending on newly discovered CVEs and image updates.

Docker maintains near-zero CVEs in Docker Hardened Images. For DHI Select and Enterprise subscriptions, when new CVEs are discovered, the CVEs are remediated within the industry-leading SLA time frame. Learn more about the [SLA-backed security features](https://docs.docker.com/dhi/features/#sla-backed-security).

This comparison shows that the Docker Hardened Image:

* Removes vulnerabilities: 1 high, 5 medium, 141 low, and 2 unspecified severity CVEs removed
* Reduces size: From 412 MB down to 35 MB (91% reduction)
* Minimizes packages: From 610 packages down to 80 (87% reduction)

To dive deeper into comparing images see [Search and evaluate Docker Hardened Images](https://docs.docker.com/dhi/how-to/explore/#compare-and-evaluate-images).

## [What's next](#whats-next)

You've pulled and run your first Docker Hardened Image. Here are a few ways to keep going:

* [Migrate existing applications to DHIs](https://docs.docker.com/dhi/migration/migrate-with-ai/): Use Gordon to update your Dockerfiles to use Docker Hardened Images as the base.

* [Start a trial](https://hub.docker.com/hardened-images/start-free-trial) to explore the benefits of a DHI subscription, such as access to FIPS and STIG variants, customized images, and SLA-backed updates.

* [Get started with DHI Select and Enterprise](https://docs.docker.com/dhi/how-to/select-enterprise/): After subscribing to a DHI subscription or starting a trial, learn how to mirror repositories, customize images, and access compliance variants.

* [Verify DHIs](https://docs.docker.com/dhi/how-to/verify/): Use tools like [Docker Scout](/scout/) or Cosign to inspect and verify signed attestations, like SBOMs and provenance.

* [Scan DHIs](https://docs.docker.com/dhi/how-to/scan/): Analyze the image with Docker Scout or other scanners to identify known CVEs.

----
url: https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/
----

# What is a container?

***

Table of contents

***

## [Explanation](#explanation)

Imagine you're developing a killer web app that has three main components - a React frontend, a Python API, and a PostgreSQL database. If you wanted to work on this project, you'd have to install Node, Python, and PostgreSQL.

How do you make sure you have the same versions as the other developers on your team? Or your CI/CD system? Or what's used in production?

How do you ensure the version of Python (or Node or the database) your app needs isn't affected by what's already on your machine? How do you manage potential conflicts?

Enter containers!

What is a container? Simply put, containers are isolated processes for each of your app's components. Each component - the frontend React app, the Python API engine, and the database - runs in its own isolated environment, completely isolated from everything else on your machine.

Here's what makes them awesome. Containers are:

* Self-contained. Each container has everything it needs to function with no reliance on any pre-installed dependencies on the host machine.
* Isolated. Since containers run in isolation, they have minimal influence on the host and other containers, increasing the security of your applications.
* Independent. Each container is independently managed. Deleting one container won't affect any others.
* Portable. Containers can run anywhere! The container that runs on your development machine will work the same way in a data center or anywhere in the cloud!

### [Containers versus virtual machines (VMs)](#containers-versus-virtual-machines-vms)

Without getting too deep, a VM is an entire operating system with its own kernel, hardware drivers, programs, and applications. Spinning up a VM only to isolate a single application is a lot of overhead.

A container is simply an isolated process with all of the files it needs to run. If you run multiple containers, they all share the same kernel, allowing you to run more applications on less infrastructure.

> **Using VMs and containers together**
>
> Quite often, you will see containers and VMs used together. As an example, in a cloud environment, the provisioned machines are typically VMs. However, instead of provisioning one machine to run one application, a VM with a container runtime can run multiple containerized applications, increasing resource utilization and reducing costs.

## [Try it out](#try-it-out)

In this hands-on, you will see how to run a Docker container using the Docker Desktop GUI.

Use the following instructions to run a container.

1. Open Docker Desktop and select the **Search** field on the top navigation bar.

2. Specify `welcome-to-docker` in the search input and then select the **Pull** button.

3. Once the image is successfully pulled, select the **Run** button.

4. Expand the **Optional settings**.

5. In the **Container name**, specify `welcome-to-docker`.

6. In the **Host port**, specify `8080`.

7. Select **Run** to start your container.

Congratulations! You just ran your first container! 🎉

### [View your container](#view-your-container)

You can view all of your containers by going to the **Containers** view of the Docker Desktop Dashboard.

This container runs a web server that displays a simple website. When working with more complex projects, you'll run different parts in different containers. For example, you might run a different container for the frontend, backend, and database.

### [Access the frontend](#access-the-frontend)

When you launched the container, you exposed one of the container's ports onto your machine. Think of this as creating configuration to let you connect through the isolated environment of the container.

For this container, the frontend is accessible on port `8080`. To open the website, select the link in the **Port(s)** column of your container or visit <http://localhost:8080> in your browser.

### [Explore your container](#explore-your-container)

Docker Desktop lets you explore and interact with different aspects of your container. Try it out yourself.

1. Go to the **Containers** view in the Docker Desktop Dashboard.

2. Select your container.

3. Select the **Files** tab to explore your container's isolated file system.

### [Stop your container](#stop-your-container)

The `docker/welcome-to-docker` container continues to run until you stop it.

1. Go to the **Containers** view in the Docker Desktop Dashboard.

2. Locate the container you'd like to stop.

3. Select the **Stop** action in the **Actions** column.

Follow the instructions to run a container using the CLI:

1. Open your CLI terminal and start a container by using the [`docker run`](/reference/cli/docker/container/run/) command:

   ```console
   $ docker run -d -p 8080:80 docker/welcome-to-docker
   ```

   The output from this command is the full container ID.

Congratulations! You just fired up your first container! 🎉

### [View your running containers](#view-your-running-containers)

You can verify if the container is up and running by using the [`docker ps`](/reference/cli/docker/container/ls/) command:

```console
docker ps
```

You will see output like the following:

```console
 CONTAINER ID   IMAGE                      COMMAND                  CREATED          STATUS          PORTS                      NAMES
 a1f7a4bb3a27   docker/welcome-to-docker   "/docker-entrypoint.…"   11 seconds ago   Up 11 seconds   0.0.0.0:8080->80/tcp       gracious_keldysh
```

This container runs a web server that displays a simple website. When working with more complex projects, you'll run different parts in different containers. For example, a different container for the `frontend`, `backend`, and `database`.

> Tip
>
> The `docker ps` command will show you *only* running containers. To view stopped containers, add the `-a` flag to list all containers: `docker ps -a`

### [Access the frontend](#access-the-frontend)

When you launched the container, you exposed one of the container's ports onto your machine. Think of this as creating configuration to let you to connect through the isolated environment of the container.

For this container, the frontend is accessible on port `8080`. To open the website, select the link in the **Port(s)** column of your container or visit <http://localhost:8080> in your browser.

### [Stop your container](#stop-your-container)

The `docker/welcome-to-docker` container continues to run until you stop it. You can stop a container using the `docker stop` command.

1. Run `docker ps` to get the ID of the container

2. Provide the container ID or name to the [`docker stop`](/reference/cli/docker/container/stop/) command:

   ```console
   docker stop <the-container-id>
   ```

> Tip
>
> When referencing containers by ID, you don't need to provide the full ID. You only need to provide enough of the ID to make it unique. As an example, the previous container could be stopped by running the following command:
>
> ```console
> docker stop a1f
> ```

## [Additional resources](#additional-resources)

The following links provide additional guidance into containers:

* [Running a container](/engine/containers/run/)
* [Overview of container](https://www.docker.com/resources/what-container/)
* [Why Docker?](https://www.docker.com/why-docker/)

## [Next steps](#next-steps)

Now that you have learned the basics of a Docker container, it's time to learn about Docker images.

[What is an image?](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/)

----
url: https://docs.docker.com/ai/gordon/how-to/cli/
----

# Using Gordon via CLI

***

Table of contents

***

Requires: Docker Desktop [4.74.0](https://docs.docker.com/desktop/release-notes/#4740) or later

The `docker ai` command provides a Terminal User Interface (TUI) for Gordon, integrating AI assistance directly into your terminal.

## [Basic usage](#basic-usage)

Launch the interactive TUI:

```console
$ docker ai
```

This opens Gordon's terminal interface where you can type prompts, approve actions, and continue conversations with full context.

Pass a prompt directly as an argument:

```console
$ docker ai "list my running containers"
```

Exit the TUI with `/exit` or `Ctrl+C`.

## [Working directory](#working-directory)

The working directory sets the default context for Gordon's file operations.

Gordon uses your current shell directory as the working directory:

```console
$ cd ~/my-project
$ docker ai
```

Override with `-C` or `--working-dir`:

```console
$ docker ai -C ~/different-project
```

## [Disabling Gordon](#disabling-gordon)

Gordon CLI is part of Docker Desktop. To disable it, disable Gordon in Docker Desktop Settings:

1. Open Docker Desktop Settings.
2. Navigate to the **AI** section.
3. Clear the **Enable Gordon** option.
4. Select **Apply**.

## [Commands](#commands)

The `docker ai` command includes several subcommands:

Interactive mode (default):

```console
$ docker ai
```

Opens the TUI for conversational interaction.

Version:

```console
$ docker ai version
```

Displays the Gordon version.

Feedback:

```console
$ docker ai feedback
```

Opens a feedback form in your browser.

----
url: https://docs.docker.com/desktop/troubleshoot-and-support/feedback/
----

***

Table of contents

***

There are many ways you can provide feedback on Docker Desktop or Docker Desktop features.

### [In-product feedback](#in-product-feedback)

On each Docker Desktop Dashboard view, there is a **Give feedback** link. This opens a feedback form where you can share ideas directly with the Docker Team.

### [Feedback via Docker Community forums](#feedback-via-docker-community-forums)

To get help from the community, review current user topics, join or start a discussion, sign in to the appropriate Docker forums:

* [Docker Desktop for Mac forum](https://forums.docker.com/c/docker-for-mac)
* [Docker Desktop for Windows forum](https://forums.docker.com/c/docker-for-windows)
* [Docker Desktop for Linux forum](https://forums.docker.com/c/docker-desktop-for-linux/60)

### [Report bugs or problems on GitHub](#report-bugs-or-problems-on-github)

To report bugs or problems, visit:

* [Docker Desktop issues on GitHub](https://github.com/docker/desktop-feedback)
* [Docker Extensions issues on GitHub](https://github.com/docker/extensions-sdk/issues)

### [Feedback via Community Slack channels](#feedback-via-community-slack-channels)

You can also provide feedback through the following [Docker Community Slack](https://dockr.ly/comm-slack) channels:

* \#docker-desktop-mac
* \#docker-desktop-windows
* \#docker-desktop-linux
* \#extensions

----
url: https://docs.docker.com/manuals/
----

# Manuals

***

***

This section contains user guides on how to install, set up, configure, and use Docker products.

## [AI and agents](#ai-and-agents)

All the Docker AI tools in one easy-to-access location.

### [Docker Sandboxes](/ai/sandboxes/)

[Run AI coding agents in isolated environments.](/ai/sandboxes/)

### [MCP Catalog and Toolkit](/ai/mcp-catalog-and-toolkit/)

[Augment your AI workflow with MCP servers.](/ai/mcp-catalog-and-toolkit/)

### [Gordon](/ai/gordon/)

[Streamline your workflow and get the most out of the Docker ecosystem with your personal AI assistant.](/ai/gordon/)

### [Docker Model Runner](/ai/model-runner/)

[View and manage your local models.](/ai/model-runner/)

### [Docker Agent](/ai/docker-agent)

[The open-source multi-agent solution to assist you in your tasks.](/ai/docker-agent)

## [Application development](#application-development)

End-to-end developer solutions for innovative teams.

### [Docker Desktop](/desktop/)

[Your command center for container development.](/desktop/)

### [Docker Offload](/offload/)

[Build and run containers in the cloud.](/offload/)

### [Docker Build Cloud](/build-cloud/)

[Build your images faster in the cloud.](/build-cloud/)

### [Testcontainers](/testcontainers/)

[Run containers programmatically in your preferred programming language.](/testcontainers/)

### [Docker Build](/build/)

[Build and ship any application anywhere.](/build/)

### [Docker Engine](/engine/)

[The industry-leading container runtime.](/engine/)

### [Docker Compose](/compose/)

[Define and run multi-container applications.](/compose/)

## [Supply chain security](#supply-chain-security)

Security guardrails and image analysis for your software supply chain.

### [Docker Hub](/docker-hub/)

[Discover, share, and integrate container images.](/docker-hub/)

### [Docker Hardened Images](/dhi/)

[Secure, minimal images for trusted software delivery.](/dhi/)

### [Docker Scout](/scout/)

[Image analysis and policy evaluation.](/scout/)

## [Platform](#platform)

Documentation related to the Docker platform, such as administration and subscription management.

### [Administration](/admin/)

[Centralized observability for companies and organizations.](/admin/)

### [Billing](/billing/)

[Manage billing and payment methods.](/billing/)

### [Accounts](/accounts/)

[Manage your Docker account.](/accounts/)

### [Security](/security/)

[Security guardrails for both administrators and developers.](/security/)

### [Subscription](/subscription/)

[Commercial use licenses for Docker products.](/subscription/)

## [Enterprise](#enterprise)

Targeted at IT administrators with help on deploying Docker Desktop at scale with configuration guidance on security related features.

### [Deploy Docker Desktop](/enterprise/enterprise-deployment/)

[Deploy Docker Desktop at scale within your company](/enterprise/enterprise-deployment/)

----
url: https://docs.docker.com/reference/cli/docker/sandbox/network/log/
----

# docker sandbox network log

***

| Description | Show network logs            |
| ----------- | ---------------------------- |
| Usage       | `docker sandbox network log` |

## [Description](#description)

> Warning
>
> The Docker Desktop-integrated `docker sandbox` commands are deprecated and replaced by the standalone [`sbx` CLI](https://docs.docker.com/ai/sandboxes/). This deprecation applies only to the Docker Desktop integration, not to Docker Sandboxes.

Show network logs

## [Options](#options)

| Option                  | Default | Description                           |
| ----------------------- | ------- | ------------------------------------- |
| [`--json`](#json)       |         | Output in JSON format                 |
| [`--limit`](#limit)     |         | Maximum number of log entries to show |
| [`-q, --quiet`](#quiet) |         | Only display log entries              |

## [Examples](#examples)

### [Show network logs](#show-network-logs)

```console
$ docker sandbox network log
2026-01-29T10:15:23Z sandbox=my-sandbox request GET https://api.example.com/data allowed
2026-01-29T10:15:24Z sandbox=my-sandbox request POST https://api.example.com/submit allowed
2026-01-29T10:15:25Z sandbox=my-sandbox request GET https://blocked.example.com/ denied
```

### [Show only log entries (--quiet)](#quiet)

```text
--quiet
```

Suppress headers and only show log entries:

```console
$ docker sandbox network log --quiet
2026-01-29T10:15:23Z sandbox=my-sandbox request GET https://api.example.com/data allowed
2026-01-29T10:15:24Z sandbox=my-sandbox request POST https://api.example.com/submit allowed
```

### [Limit number of entries (--limit)](#limit)

```text
--limit N
```

Show only the last N log entries:

```console
$ docker sandbox network log --limit 10
```

### [JSON output (--json)](#json)

Output logs in JSON format for parsing:

```console
$ docker sandbox network log --json
{
  "entries": [
    {
      "timestamp": "2026-01-29T10:15:23Z",
      "sandbox": "my-sandbox",
      "type": "request",
      "method": "GET",
      "url": "https://api.example.com/data",
      "action": "allowed"
    }
  ]
}
```

----
url: https://docs.docker.com/reference/samples/elasticsearch/
----

# Elasticsearch / Logstash / Kibana samples

| Name                                                                                                                     | Description                                         |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
| [Elasticsearch / Logstash / Kibana](https://github.com/docker/awesome-compose/tree/master/elasticsearch-logstash-kibana) | A sample Elasticsearch, Logstash, and Kibana stack. |

## Looking for more samples?

Visit the following GitHub repositories for more Docker samples.

* [Awesome Compose](https://github.com/docker/awesome-compose): A curated repository containing over 30 Docker Compose samples. These samples offer a starting point for how to integrate different services using a Compose file.

* [Docker Samples](https://github.com/dockersamples?q=\&type=all\&language=\&sort=stargazers): A collection of over 30 repositories that offer sample containerized demo applications, tutorials, and labs.

----
url: https://docs.docker.com/guides/cpp/containerize/
----

# Containerize a C++ application

***

Table of contents

***

## [Prerequisites](#prerequisites)

* You have a [Git client](https://git-scm.com/downloads). The examples in this section use a command-line based Git client, but you can use any client.

## [Overview](#overview)

This section walks you through containerizing and running a C++ application, using Docker Compose.

## [Get the sample application](#get-the-sample-application)

We're using the same sample repository that you used in the previous sections of this guide. If you haven't already cloned the repository, clone it now:

```console
$ git clone https://github.com/dockersamples/c-plus-plus-docker.git
```

You should now have the following contents in your `c-plus-plus-docker` (root) directory.

```text
├── c-plus-plus-docker/
│ ├── compose.yml
│ ├── Dockerfile
│ ├── LICENSE
│ ├── ok_api.cpp
│ └── README.md
```

To learn more about the files in the repository, see the following:

* [Dockerfile](https://docs.docker.com/reference/dockerfile/)
* [.dockerignore](https://docs.docker.com/reference/dockerfile/#dockerignore-file)
* [compose.yml](https://docs.docker.com/reference/compose-file/)

## [Run the application](#run-the-application)

Inside the `c-plus-plus-docker` directory, run the following command in a terminal.

```console
$ docker compose up --build
```

Open a browser and view the application at <http://localhost:8080>. You will see a message `{"Status" : "OK"}` in the browser.

In the terminal, press `ctrl`+`c` to stop the application.

### [Run the application in the background](#run-the-application-in-the-background)

You can run the application detached from the terminal by adding the `-d` option. Inside the `c-plus-plus-docker` directory, run the following command in a terminal.

```console
$ docker compose up --build -d
```

Open a browser and view the application at <http://localhost:8080>.

In the terminal, run the following command to stop the application.

```console
$ docker compose down
```

For more information about Compose commands, see the [Compose CLI reference](/reference/cli/docker/compose/).

## [Summary](#summary)

In this section, you learned how you can containerize and run your C++ application using Docker.

Related information:

* [Docker Compose overview](https://docs.docker.com/compose/)

## [Next steps](#next-steps)

In the next section, you'll learn how you can develop your application using containers.

[Use containers for C++ development »](https://docs.docker.com/guides/cpp/develop/)

----
url: https://docs.docker.com/dhi/how-to/customize/
----

# Customize a Docker Hardened Image or chart

***

Table of contents

***

Subscription: Docker Hardened Images Select or Enterprise

When you have a DHI Select or DHI Enterprise subscription, you can customize Docker Hardened Images (DHI) and charts to suit your specific needs using the Docker Hub web interface. For images, this lets you select a base image, add packages, add OCI artifacts (such as custom certificates or additional tools), and configure settings. For charts, this lets you customize the image references.

Your customizations stay secure automatically. When the base Docker Hardened Image or chart receives a security patch or your OCI artifacts are updated, Docker automatically rebuilds your customizations in the background. This ensures continuous compliance and protection by default, with no manual work required. The rebuilt artifacts are signed and attested to the same SLSA Build Level 3 standard as the base images and charts, ensuring a secure and verifiable supply chain.

## [Customize a Docker Hardened Image](#customize-a-docker-hardened-image)

To add a customized Docker Hardened Image to your organization, an organization owner must first [mirror](https://docs.docker.com/dhi/how-to/mirror/) the DHI repository to your organization on Docker Hub. Once the repository is mirrored, any user with access to the mirrored DHI repository can create a customized image.

You can create customizations using either the DHI CLI or the Docker Hub web interface.

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub**.

3. In the namespace drop-down, select your organization that has a mirrored DHI repository.

4. Select **Hardened Images** > **Manage** > **Mirrored Images**.

5. For the mirrored DHI repository you want to customize, select the menu icon in the far right column.

6. Select **Customize**.

   At this point, the on-screen instructions will guide you through the customization process. You can continue with the following steps for more details.

7. Select one or more images or Helm charts and versions you want to customize.

   When selecting multiple images and versions, all selections must share the same distribution and distribution version. For example, you can select `dhi-node:22_alpine3.23` and `dhi-python:3.13_alpine3.23` together (both Alpine 3.23), but you cannot mix `dhi-node:22_debian` with Alpine images, or mix different Alpine versions like `alpine3.23` and `alpine3.22`.

   Alternatively, you can select multiple Helm chart versions to apply the same customization to all of them. You cannot mix images and Helm charts in the same customization.

8. Select **Next**.

9. Optional. Add packages.

   1. In the packages drop-down, select the packages you want to add to the image.

      The packages available in the drop-down are OS system packages for the selected image variant. For version 3.23 Alpine-based images, these are hardened packages that have been built from source by Docker with cryptographic signatures and full supply chain security. For version 3.22 Alpine-based images and Debian-based images, these are standard system packages.

   2. In the **OCI artifacts** drop-down, first, select the repository that contains the OCI artifact image. Then, select the tag you want to use from that repository. Finally, specify the specific paths you want to include from the OCI artifact image.

      The OCI artifacts are images that you have previously built and pushed to a repository in the same namespace as the mirrored DHI. For example, you can add a custom root CA certificate or another image that contains a tool you need, like adding Python to a Node.js image. For more details on how to create an OCI artifact image, see [Create an OCI artifact image](#create-an-oci-artifact-image).

      You can add multiple OCI artifact images to a single customization. When you add more than one, they're applied in the order you add them in the **OCI artifacts** drop-down. If multiple images contain directories or files with the same path, images added later overwrite files from images added earlier. To manage this, you must select paths to include and optionally exclude from each OCI artifact image. This allows you to control which files are included in the final customized image.

      By default, no files are included from the OCI artifact image. You must explicitly include the paths you want. After including a path, you can then explicitly exclude files or directories underneath it.

      > Note
      >
      > When files necessary for runtime are overwritten by OCI artifacts, the image build still succeeds, but you may have issues when running the image.

   3. In the **Scripts** section, you can add, edit, or remove scripts.

      Scripts let you add files to the container image that you can access at runtime. They are not executed during the build process. This is useful for services that require pre-start initialization, such as setup scripts or file writes to directories like `/var/lock` or `/out`.

      You must specify the following:

      * The path where the script will be placed
      * The script content
      * The UID and GID ownership of the script
      * The octal file permissions of the script

10. Select **Next: Configure** to configure the following image settings:

    > Note
    >
    > When customizing multiple images at once, many of these configuration options are limited by default and may not be available.

    1. Specify the [environment variables](/reference/dockerfile/#env) and their values that the image will contain.
    2. Add [labels](/reference/dockerfile/#label) to the image.
    3. Add [annotations](/build/metadata/annotations/) to the image.
    4. Specify the users to add to the image. When you add a user, a home directory is automatically created for that user with 0755 permissions.
    5. Specify the user groups to add to the image.
    6. Select which [user](/reference/dockerfile/#user) to run the images as.
    7. Add [`ENTRYPOINT`](/reference/dockerfile/#entrypoint) arguments to the image. These arguments are appended to the base image's entrypoint.
    8. Add [`CMD`](/reference/dockerfile/#cmd) arguments to the image. These arguments are appended to the base image's command.
    9. Override the default (`/`) [working directory](/reference/dockerfile/#workdir) for the image.
    10. Specify a suffix for the customization name that is appended to the customized image's tag. For example, if you specify `custom` when customizing the `dhi-python:3.13` image, the customized image will be tagged as `dhi-python:3.13_custom`.
    11. Select the compression format for the image layers. You can choose between **ZSTD** (default) or **GZIP** compression. **ZSTD** typically provides faster image pulls and better compression ratios, but may have compatibility issues with older software. If you need compatibility with older Docker versions, use **GZIP**.
    12. Select the platforms you want to build the image for. You must select at least one platform.

11. Select **Next: Review customization**.

12. Select **Create Customization**.

    A summary of the customization appears. It may take some time for the image to build. Once built, it will appear in the **Tags** tab of the repository, and your team members can pull it like any other image.

Authenticate with `docker login` using your Docker credentials or a [personal access token (PAT)](https://docs.docker.com/security/access-tokens/) with **Read & Write** permissions, or an [organization access token (OAT)](https://docs.docker.com/enterprise/security/access-tokens/). When using an OAT, the available operations depend on the token's permission scope:

* To list or get customizations, or to view build logs, the OAT must have read (pull) access to the destination repository. Results are scoped to repositories the OAT can access.
* To create, update, or delete a customization, the OAT must have push access to the destination repository. Bulk operations require push access to every referenced destination repository.

Use the [`docker dhi customization`](/reference/cli/docker/dhi/customization/) command:

```console
# Prepare a single customization scaffold
$ docker dhi customization prepare golang 1.25 \
  --org my-org \
  --destination my-org/dhi-golang \
  --name "golang with git" \
  > my-customization.yaml

# Prepare a bulk customization scaffold (pipe JSON array via stdin)
$ echo '[{"destination":"my-org/dhi-golang","tag-definition-id":"golang/alpine-3.23/1.24-dev"}]' \
  | docker dhi customization prepare --name "golang with git" --org my-org \
  > my-customization.yaml

# Create a customization
$ docker dhi customization create my-customization.yaml --org my-org

# List customizations
$ docker dhi customization list --org my-org

# Filter customizations by name, repository, or source
$ docker dhi customization list --org my-org --filter git
$ docker dhi customization list --org my-org --repo dhi-golang
$ docker dhi customization list --org my-org --source golang

# Get a customization by ID
$ docker dhi customization get <id> --org my-org

# Update a customization
$ docker dhi customization edit my-customization.yaml --org my-org

# Delete a customization by ID
$ docker dhi customization delete <id> --org my-org

# Delete without confirmation prompt
$ docker dhi customization delete <id> --org my-org --force
```

For a complete reference of all YAML fields, see [Image customization YAML file](#image-customization-yaml-file).

You can manage DHI customizations as infrastructure-as-code using the [DHI Terraform provider](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs). If you haven't configured the provider yet, see the Terraform tab in [Mirror a repository](https://docs.docker.com/dhi/how-to/mirror/) for setup instructions.

Define a `dhi_customization` resource for each customization:

```hcl
resource "dhi_customization" "golang_with_git" {
  repository = "dhi-golang"
  name       = "golang with git"

  contents {
    packages = ["git", "curl"]
  }

  platform {
    os           = "linux"
    architecture = "amd64"
  }
}
```

The `dhi_customization` resource also supports optional configuration blocks for `accounts`, `files`, `labels`, `annotations`, `environment`, `entrypoint`, `cmd`, `user`, `workdir`, and `stop_signal`.

Run `terraform apply` to create the customization.

To edit a customization, update the resource configuration and run `terraform apply`. To delete a customization, remove the resource and run `terraform apply`.

For the full list of resource attributes, see the [Terraform Registry documentation](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs/resources/customization).

> Note
>
> Monitoring customization builds is not available through the Terraform provider. Use the Docker Hub web interface or the DHI CLI to monitor builds.

### [Image customization YAML file](#image-customization-yaml-file)

When using the CLI, customizations are defined in a YAML file. Use `docker dhi customization prepare` to generate a scaffold with all available fields and commented-out examples. Edit the file to describe what you want, then pass it to `docker dhi customization create`.

The file has two parts: a preamble that identifies the customization and its targets, and a configuration section that specifies what to change.

#### [About the `id` field](#about-the-id-field)

The `id` field is assigned automatically by Docker Hub when you run `docker dhi customization create`. When creating a new customization, omit `id` entirely. It is read-only.

To find the ID of an existing customization, run:

```console
$ docker dhi customization list --org my-org
```

The `id` appears in the output and in files retrieved with `docker dhi customization get <id> --org my-org`. It lets `docker dhi customization edit` identify which customization to update. Scaffolds from `docker dhi customization prepare` do not include `id`, and that is expected.

#### [Set targets](#set-targets)

The `name` and `targets` fields are required in every customization file. The `targets` array specifies which image versions the customization applies to. Use a single entry for a single-image customization, or multiple entries for a bulk customization that applies the same configuration to several images at once.

```yaml
name: golang with git

targets:
  - destination: my-org/dhi-golang
    tag_definition_id: golang/alpine-3.23/1.25
```

| Field                         | Description                                                                                                                                                             |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                        | Human-readable name. Converted to lowercase and hyphenated, it becomes the image tag suffix. For example, `golang with git` produces tags ending in `_golang-with-git`. |
| `targets[].destination`       | Destination repository in Docker Hub, such as `my-org/dhi-golang`.                                                                                                      |
| `targets[].tag_definition_id` | Tag definition to customize, such as `golang/alpine-3.23/1.25`. Use `docker dhi customization prepare` with tab completion to find valid values.                        |

> Note
>
> When `targets` has more than one entry, the fields `accounts`, `entrypoint`, and `cmd` are not supported. Including them causes `docker dhi customization create` to return an error.

#### [Add packages](#add-packages)

To install additional OS packages in your customized image, list them under `contents.packages`. Available packages depend on the base image variant.

```yaml
contents:
  packages:
    - git
    - curl
```

#### [Add OCI artifacts](#add-oci-artifacts)

To layer additional files into your customized image, such as custom certificates, internal tools, or configuration files, list OCI artifact images under `contents.artifacts`.

```yaml
contents:
  artifacts:
    - name: my-org/my-certs:latest
      includes:
        - etc/ssl/certs
      excludes:
        - etc/ssl/certs/old
```

| Field      | Description                                                                                         |
| ---------- | --------------------------------------------------------------------------------------------------- |
| `name`     | Image reference of the OCI artifact. Must be in the same Docker Hub namespace as the mirrored DHI.  |
| `includes` | Paths to copy from the artifact. No files are included by default. You must list at least one path. |
| `excludes` | Paths to exclude after applying `includes`.                                                         |

For instructions on building an OCI artifact image, see [Create an OCI artifact image](#create-an-oci-artifact-image).

#### [Inject files into the image](#inject-files-into-the-image)

To add static files at build time, such as configuration files or startup scripts, use the `paths` field. Files are added as static content and are not executed during the build.

```yaml
paths:
  - path: /etc/myconfig
    contents: |
      key=value
    mode: "0644"
    uid: 0
    gid: 0
```

| Field      | Description                                                                                                                 |
| ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `path`     | Absolute path where the file will be placed in the image.                                                                   |
| `contents` | File content. Use a YAML block scalar (`\|`) for multi-line content.                                                        |
| `mode`     | Octal file permissions, such as `"0644"`. Quote the value to prevent YAML from treating the leading zero as octal notation. |
| `uid`      | User ID of the file owner.                                                                                                  |
| `gid`      | Group ID of the file owner.                                                                                                 |

#### [Configure user accounts](#configure-user-accounts)

To add users or groups to the image, or to change which user the container runs as, use the `accounts` field.

> Note
>
> Not supported for bulk customizations (multiple `targets`).

```yaml
accounts:
  root: true
  runs-as: nonroot
  users:
    - name: nonroot
      uid: 65532
      gid: 65532
  groups:
    - name: nonroot
      gid: 65532
      members:
        - nonroot
```

| Field              | Description                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------- |
| `root`             | Whether to enable the root user. Default is `false`. Required if `runs-as` is set to `root`. |
| `runs-as`          | The default user the container runs as.                                                      |
| `users[].name`     | Username.                                                                                    |
| `users[].uid`      | User ID.                                                                                     |
| `users[].gid`      | Primary group ID. Optional.                                                                  |
| `groups[].name`    | Group name.                                                                                  |
| `groups[].gid`     | Group ID.                                                                                    |
| `groups[].members` | Usernames to add to this group. Optional.                                                    |

#### [Set environment variables](#set-environment-variables)

To add or override environment variables in the image, use the `environment` field. These are merged with the base image's existing environment and do not replace it.

```yaml
environment:
  MY_VAR: my_value
  DEBUG: "false"
```

Quote values that a YAML parser would interpret as non-string types, for example `"false"`, `"0"`, and `"null"`.

#### [Set labels and annotations](#set-labels-and-annotations)

To add OCI metadata to the image, use `labels` and `annotations`. Labels are stored in the image config; annotations are stored in the image manifest. Use [OCI standard keys](https://specs.opencontainers.org/image-spec/annotations/) where applicable.

```yaml
labels:
  org.opencontainers.image.authors: your-email@example.com
  org.opencontainers.image.version: "1.0.0"

annotations:
  org.opencontainers.image.title: Custom hardened image
  org.opencontainers.image.description: Customized Docker Hardened Image
```

#### [Override entrypoint and command](#override-entrypoint-and-command)

To change how the container starts, use `entrypoint` and `cmd`. These arguments are appended to the base image's existing entrypoint and command.

> Note
>
> Not supported for bulk customizations (multiple `targets`).

```yaml
entrypoint:
  - /docker-entrypoint.sh

cmd:
  - /bin/bash
```

#### [Set platforms and compression](#set-platforms-and-compression)

To build for multiple architectures, list them under `platforms`. At least one platform is required.

```yaml
platforms:
  - linux/amd64
  - linux/arm64
```

To control layer compression, set `compression`. `ZSTD` (the default) offers better compression and faster pulls. Use `GZIP` for compatibility with older tooling.

```yaml
compression: ZSTD
```

### [Create an OCI artifact image](#create-an-oci-artifact-image)

An OCI artifact image is a Docker image that contains files or directories that you want to include in your customized Docker Hardened Image (DHI). This can include additional tools, libraries, or configuration files.

When creating an image to use as an OCI artifact, it should ideally be as minimal as possible and contain only the necessary files.

For example, to distribute a custom root CA certificate as part of a trusted CA bundle, you can use a multi-stage build. This approach registers your certificate with the system and outputs an updated CA bundle, which can be extracted into a minimal final image:

```dockerfile
# syntax=docker/dockerfile:1

FROM dhi.io/bash:5-dev AS certs

ENV DEBIAN_FRONTEND=noninteractive

RUN mkdir -p /usr/local/share/ca-certificates/my-rootca
COPY certs/rootCA.crt /usr/local/share/ca-certificates/my-rootca

RUN update-ca-certificates

FROM scratch
COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
```

You can follow this pattern to create other OCI artifacts, such as images containing tools or libraries that you want to include in your customized DHI. Install the necessary tools or libraries in the first stage, and then copy the relevant files to the final stage that uses `FROM scratch`. This ensures that your OCI artifact is minimal and contains only the necessary files.

In order for the OCI artifact to be available in a DHI customization, it must be built and pushed to a repository in the same namespace as the mirrored DHI repository.

If you're customizing a DHI for multiple platforms (such as `linux/amd64` and `linux/arm64`), build your OCI artifact for all the platforms using the `--platform` flag:

```console
$ docker buildx build --platform linux/amd64,linux/arm64 \
  -t <your-namespace>/my-oci-artifact:latest \
  --push .
```

This creates a single image manifest that you can use for each platform. The customization build system automatically selects the correct platform variant when building each customized image.

> Important
>
> The customization UI will only allow you to select platforms that are available in all OCI artifacts you've added. If a platform is missing from any OCI artifact, you won't be able to select that platform for your customization.

Once pushed to a repository in your organization's namespace, the OCI artifact automatically appears in the customization workflow when you select OCI artifacts to add to your customized Docker Hardened Image.

#### [Best practices for OCI artifacts](#best-practices-for-oci-artifacts)

Follow these best practices when creating OCI artifacts for DHI customizations:

* Use multi-stage builds: Build or install dependencies in a builder stage, then copy only the necessary files to a `FROM scratch` final stage. This keeps the OCI artifact minimal and free of unnecessary build tools.

* Include only essential files: OCI artifacts should contain only the files you need to add to the customized image. Avoid including package managers, shells, or other utilities that won't be used in the final image.

* Match target platforms: Build your OCI artifact for all platforms you plan to use in your customizations. Use `docker buildx build --platform` to create multi-platform images when needed.

* Use specific tags: Tag your OCI artifacts with specific versions or dates (like `v1.0` or `20250101`) rather than relying solely on `latest`. This ensures reproducible builds and makes it easier to track which artifacts are used in which customizations.

* Enable immutable tags: Consider enabling [immutable tags](https://docs.docker.com/docker-hub/repos/manage/hub-images/immutable-tags/) for your OCI artifact repositories. This prevents accidental overwrites and ensures that each version of your OCI artifact remains unchanged, improving reproducibility and reliability of your customizations.

## [Customize a DHI Helm chart](#customize-a-dhi-helm-chart)

You can customize DHI Helm charts to meet your organization's specific needs. Via the Docker Hub web interface, you can modify the image references to reference mirrored images or customized images you've created. This lets you create a custom, securely-built chart with references to images stored in Docker Hub or other private registries. DHI securely packages customized Helm charts that reference your repositories, wherever they are stored, by default.

To customize image references, an organization owner must [mirror](https://docs.docker.com/dhi/how-to/mirror/) the DHI chart repository to your organization on Docker Hub.

You can create one chart customization per Helm chart repository. This is different from image customizations, where you can create multiple customizations per repository. If you need to make changes, you can edit your existing customization. Alternatively, you can mirror the same Helm chart repository again and add a new customization to the new mirror.

> Note
>
> You can customize Docker Hardened Image charts like any other Helm chart using standard Helm tools and practices, such as a `values.yaml` file, outside of Docker Hub. The following instructions describe how to customize image references for the chart using the Docker Hub web interface.

To customize a Docker Hardened Image Helm chart after it has been mirrored:

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub**.

3. In the namespace drop-down, select your organization that has a mirrored DHI repository.

4. Select **Hardened Images** > **Manage** > **Mirrored Helm charts**.

5. For the mirrored DHI repository you want to customize, select the **Name**.

6. Select the **Customizations** tab.

7. Select **Create customization**.

   At this point, the on-screen instructions will guide you through the customization process.

### [Helm chart customization YAML file](#helm-chart-customization-yaml-file)

When using the CLI, Helm chart customizations use the same `prepare` / `create` workflow as image customizations, but the configuration section uses `reference_mappings` instead of image fields.

Use `reference_mappings` to substitute image references within the chart, for example to point a chart's image references at your mirrored DHIs.

```yaml
name: use mirrored images

targets:
  - destination: my-org/dhi-haproxy-chart
    tag_definition_id: haproxy/helm/1

reference_mappings:
  - from: dhi/haproxy
    to: my-org/dhi-haproxy
```

| Field                       | Description                                                                     |
| --------------------------- | ------------------------------------------------------------------------------- |
| `reference_mappings[].from` | The image reference in the chart to replace.                                    |
| `reference_mappings[].to`   | The replacement image reference, typically a mirrored DHI in your organization. |

## [Monitor customization builds](#monitor-customization-builds)

After creating a customization, you can track build status and view logs through Docker Hub or the DHI CLI.

1. Sign in to [Docker Hub](https://hub.docker.com).
2. Select **My Hub**.
3. In the namespace drop-down, select your organization.
4. Select **Hardened Images** > **Manage**.
5. Select the **Customizations** tab.

List builds for a customization:

```console
$ docker dhi customization build list <customization-id> --org my-org
```

Get details of a specific build:

```console
$ docker dhi customization build get <customization-id> <build-id> --org my-org
```

View build logs:

```console
$ docker dhi customization build logs <customization-id> <build-id> --org my-org
```

## [Edit or delete a customization](#edit-or-delete-a-customization)

1. Sign in to [Docker Hub](https://hub.docker.com).

2. Select **My Hub**.

3. In the namespace drop-down, select your organization that has a mirrored repository.

4. Select **Hardened Images** > **Manage**.

5. Select **Customizations**.

6. For the customized DHI repository you want to manage, select the menu icon in the far right column. From here, you can:

   * **Edit**: Edit the customization.
   * **Create new**: Create a new customization based on the source repository.
   * **Delete**: Delete the customization.

7. Follow the on-screen instructions to complete the edit or deletion.

To edit a customization, update your YAML file and run:

```console
$ docker dhi customization edit my-customization.yaml --org my-org
```

The YAML file must include the `id` field to identify which customization to update. To find the ID, run `docker dhi customization list --org my-org`.

To delete a customization by ID:

```console
$ docker dhi customization delete <id> --org my-org
$ docker dhi customization delete <id> --org my-org --force
```

The `--force` flag skips the confirmation prompt.

----
url: https://docs.docker.com/reference/build-checks/
----

# Build checks

***

***

BuildKit has built-in support for analyzing your build configuration based on a set of pre-defined rules for enforcing Dockerfile and building best practices. Adhering to these rules helps avoid errors and ensures good readability of your Dockerfile.

Checks run as a build invocation, but instead of producing a build output, it performs a series of checks to validate that your build doesn't violate any of the rules. To run a check, use the `--check` flag:

```console
$ docker build --check .
```

To learn more about how to use build checks, see [Checking your build configuration](https://docs.docker.com/build/checks/).

| Name                                                                             | Description                                                                                                                                                                                      |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [StageNameCasing](./stage-name-casing/)                                          | Stage names should be lowercase                                                                                                                                                                  |
| [FromAsCasing](./from-as-casing/)                                                | The 'as' keyword should match the case of the 'from' keyword                                                                                                                                     |
| [NoEmptyContinuation](./no-empty-continuation/)                                  | Empty continuation lines will become errors in a future release                                                                                                                                  |
| [ConsistentInstructionCasing](./consistent-instruction-casing/)                  | All commands within the Dockerfile should use the same casing (either upper or lower)                                                                                                            |
| [DuplicateStageName](./duplicate-stage-name/)                                    | Stage names should be unique                                                                                                                                                                     |
| [ReservedStageName](./reserved-stage-name/)                                      | Reserved words should not be used as stage names                                                                                                                                                 |
| [JSONArgsRecommended](./json-args-recommended/)                                  | JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals                                                                                               |
| [MaintainerDeprecated](./maintainer-deprecated/)                                 | The MAINTAINER instruction is deprecated, use a label instead to define an image author                                                                                                          |
| [UndefinedArgInFrom](./undefined-arg-in-from/)                                   | FROM command must use declared ARGs                                                                                                                                                              |
| [WorkdirRelativePath](./workdir-relative-path/)                                  | Relative workdir without an absolute workdir declared within the build can have unexpected results if the base image changes                                                                     |
| [UndefinedVar](./undefined-var/)                                                 | Variables should be defined before their use                                                                                                                                                     |
| [MultipleInstructionsDisallowed](./multiple-instructions-disallowed/)            | Multiple instructions of the same type should not be used in the same stage                                                                                                                      |
| [LegacyKeyValueFormat](./legacy-key-value-format/)                               | Legacy key/value format with whitespace separator should not be used                                                                                                                             |
| [RedundantTargetPlatform](./redundant-target-platform/)                          | Setting platform to predefined $TARGETPLATFORM in FROM is redundant as this is the default behavior                                                                                              |
| [SecretsUsedInArgOrEnv](./secrets-used-in-arg-or-env/)                           | Sensitive data should not be used in the ARG or ENV commands                                                                                                                                     |
| [InvalidDefaultArgInFrom](./invalid-default-arg-in-from/)                        | Default value for global ARG results in an empty or invalid base image name                                                                                                                      |
| [FromPlatformFlagConstDisallowed](./from-platform-flag-const-disallowed/)        | FROM --platform flag should not use a constant value                                                                                                                                             |
| [CopyIgnoredFile](./copy-ignored-file/)                                          | Attempting to Copy file that is excluded by .dockerignore                                                                                                                                        |
| [InvalidDefinitionDescription (experimental)](./invalid-definition-description/) | Comment for build stage or argument should follow the format: \`# \`. If this is not intended to be a description comment, add an empty line or comment between the instruction and the comment. |
| [ExposeProtoCasing](./expose-proto-casing/)                                      | Protocol in EXPOSE instruction should be lowercase                                                                                                                                               |
| [ExposeInvalidFormat](./expose-invalid-format/)                                  | IP address and host-port mapping should not be used in EXPOSE instruction. This will become an error in a future release                                                                         |

----
url: https://docs.docker.com/reference/dockerfile/
----

# Dockerfile reference

***

Table of contents

***

Docker can build images automatically by reading the instructions from a Dockerfile. A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. This page describes the commands you can use in a Dockerfile.

## [Overview](#overview)

The Dockerfile supports the following instructions:

| Instruction                            | Description                                                 |
| -------------------------------------- | ----------------------------------------------------------- |
| [`ADD`](#add)                          | Add local or remote files and directories.                  |
| [`ARG`](#arg)                          | Use build-time variables.                                   |
| [`CMD`](#cmd)                          | Specify default commands.                                   |
| [`COPY`](#copy)                        | Copy files and directories.                                 |
| [`ENTRYPOINT`](#entrypoint)            | Specify default executable.                                 |
| [`ENV`](#env)                          | Set environment variables.                                  |
| [`EXPOSE`](#expose)                    | Describe which ports your application is listening on.      |
| [`FROM`](#from)                        | Create a new build stage from a base image.                 |
| [`HEALTHCHECK`](#healthcheck)          | Check a container's health on startup.                      |
| [`LABEL`](#label)                      | Add metadata to an image.                                   |
| [`MAINTAINER`](#maintainer-deprecated) | Specify the author of an image.                             |
| [`ONBUILD`](#onbuild)                  | Specify instructions for when the image is used in a build. |
| [`RUN`](#run)                          | Execute build commands.                                     |
| [`SHELL`](#shell)                      | Set the default shell of an image.                          |
| [`STOPSIGNAL`](#stopsignal)            | Specify the system call signal for exiting a container.     |
| [`USER`](#user)                        | Set user and group ID.                                      |
| [`VOLUME`](#volume)                    | Create volume mounts.                                       |
| [`WORKDIR`](#workdir)                  | Change working directory.                                   |

## [Format](#format)

Here is the format of the Dockerfile:

```dockerfile
# Comment
INSTRUCTION arguments
```

The instruction is not case-sensitive. However, convention is for them to be UPPERCASE to distinguish them from arguments more easily.

Docker runs instructions in a Dockerfile in order. A Dockerfile **must begin with a `FROM` instruction**. This may be after [parser directives](#parser-directives), [comments](#format), and globally scoped [ARGs](#arg). The `FROM` instruction specifies the [base image](https://docs.docker.com/glossary/#base-image) from which you are building. `FROM` may only be preceded by one or more `ARG` instructions, which declare arguments that are used in `FROM` lines in the Dockerfile.

BuildKit treats lines that begin with `#` as a comment, unless the line is a valid [parser directive](#parser-directives). A `#` marker anywhere else in a line is treated as an argument. This allows statements like:

```dockerfile
# Comment
RUN echo 'we are running some # of cool things'
```

Comment lines are removed before the Dockerfile instructions are executed. The comment in the following example is removed before the shell executes the `echo` command.

```dockerfile
RUN echo hello \
# comment
world
```

The following examples is equivalent.

```dockerfile
RUN echo hello \
world
```

Comments don't support line continuation characters.

> Note
>
> **Note on whitespace**
>
> For backward compatibility, leading whitespace before comments (`#`) and instructions (such as `RUN`) are ignored, but discouraged. Leading whitespace is not preserved in these cases, and the following examples are therefore equivalent:
>
> ```dockerfile
>         # this is a comment-line
>     RUN echo hello
> RUN echo world
> ```
>
> ```dockerfile
> # this is a comment-line
> RUN echo hello
> RUN echo world
> ```
>
> Whitespace in instruction arguments, however, isn't ignored. The following example prints `hello world` with leading whitespace as specified:
>
> ```dockerfile
> RUN echo "\
>      hello\
>      world"
> ```

## [Parser directives](#parser-directives)

Parser directives are optional, and affect the way in which subsequent lines in a Dockerfile are handled. Parser directives don't add layers to the build, and don't show up as build steps. Parser directives are written as a special type of comment in the form `# directive=value`. A single directive may only be used once.

The following parser directives are supported:

* [`syntax`](#syntax)
* [`escape`](#escape)
* [`check`](#check) (since Dockerfile v1.8.0)

Once a comment, empty line or builder instruction has been processed, BuildKit no longer looks for parser directives. Instead it treats anything formatted as a parser directive as a comment and doesn't attempt to validate if it might be a parser directive. Therefore, all parser directives must be at the top of a Dockerfile.

Parser directive keys, such as `syntax` or `check`, aren't case-sensitive, but they're lowercase by convention. Values for a directive are case-sensitive and must be written in the appropriate case for the directive. For example, `#check=skip=jsonargsrecommended` is invalid because the check name must use Pascal case, not lowercase. It's also conventional to include a blank line following any parser directives. Line continuation characters aren't supported in parser directives.

Due to these rules, the following examples are all invalid:

Invalid due to line continuation:

```dockerfile
# direc \
tive=value
```

Invalid due to appearing twice:

```dockerfile
# directive=value1
# directive=value2

FROM ImageName
```

Treated as a comment because it appears after a builder instruction:

```dockerfile
FROM ImageName
# directive=value
```

Treated as a comment because it appears after a comment that isn't a parser directive:

```dockerfile
# About my dockerfile
# directive=value
FROM ImageName
```

The following `unknowndirective` is treated as a comment because it isn't recognized. The known `syntax` directive is treated as a comment because it appears after a comment that isn't a parser directive.

```dockerfile
# unknowndirective=value
# syntax=value
```

Non line-breaking whitespace is permitted in a parser directive. Hence, the following lines are all treated identically:

```dockerfile
#directive=value
# directive =value
#	directive= value
# directive = value
#	  dIrEcTiVe=value
```

### [syntax](#syntax)

[]()

Use the `syntax` parser directive to declare the Dockerfile syntax version to use for the build. If unspecified, BuildKit uses a bundled version of the Dockerfile frontend. Declaring a syntax version lets you automatically use the latest Dockerfile version without having to upgrade BuildKit or Docker Engine, or even use a custom Dockerfile implementation.

Most users will want to set this parser directive to `docker/dockerfile:1`, which causes BuildKit to pull the latest stable version of the Dockerfile syntax before the build.

```dockerfile
# syntax=docker/dockerfile:1
```

For more information about how the parser directive works, see [Custom Dockerfile syntax](https://docs.docker.com/build/buildkit/dockerfile-frontend/).

### [escape](#escape)

```dockerfile
# escape=\
```

Or

```dockerfile
# escape=`
```

The `escape` directive sets the character used to escape characters in a Dockerfile. If not specified, the default escape character is `\`.

The escape character is used both to escape characters in a line, and to escape a newline. This allows a Dockerfile instruction to span multiple lines. Note that regardless of whether the `escape` parser directive is included in a Dockerfile, escaping is not performed in a `RUN` command, except at the end of a line.

Setting the escape character to `` ` `` is especially useful on `Windows`, where `\` is the directory path separator. `` ` `` is consistent with [Windows PowerShell](https://technet.microsoft.com/en-us/library/hh847755.aspx).

Consider the following example which would fail in a non-obvious way on Windows. The second `\` at the end of the second line would be interpreted as an escape for the newline, instead of a target of the escape from the first `\`. Similarly, the `\` at the end of the third line would, assuming it was actually handled as an instruction, cause it be treated as a line continuation. The result of this Dockerfile is that second and third lines are considered a single instruction:

```dockerfile
FROM microsoft/nanoserver
COPY testfile.txt c:\\
RUN dir c:\
```

Results in:

```console
PS E:\myproject> docker build -t cmd .

Sending build context to Docker daemon 3.072 kB
Step 1/2 : FROM microsoft/nanoserver
 ---> 22738ff49c6d
Step 2/2 : COPY testfile.txt c:\RUN dir c:
GetFileAttributesEx c:RUN: The system cannot find the file specified.
PS E:\myproject>
```

One solution to the above would be to use `/` as the target of both the `COPY` instruction, and `dir`. However, this syntax is, at best, confusing as it is not natural for paths on Windows, and at worst, error prone as not all commands on Windows support `/` as the path separator.

By adding the `escape` parser directive, the following Dockerfile succeeds as expected with the use of natural platform semantics for file paths on Windows:

```dockerfile
# escape=`

FROM microsoft/nanoserver
COPY testfile.txt c:\
RUN dir c:\
```

Results in:

```console
PS E:\myproject> docker build -t succeeds --no-cache=true .

Sending build context to Docker daemon 3.072 kB
Step 1/3 : FROM microsoft/nanoserver
 ---> 22738ff49c6d
Step 2/3 : COPY testfile.txt c:\
 ---> 96655de338de
Removing intermediate container 4db9acbb1682
Step 3/3 : RUN dir c:\
 ---> Running in a2c157f842f5
 Volume in drive C has no label.
 Volume Serial Number is 7E6D-E0F7

 Directory of c:\

10/05/2016  05:04 PM             1,894 License.txt
10/05/2016  02:22 PM    DIR          Program Files
10/05/2016  02:14 PM    DIR          Program Files (x86)
10/28/2016  11:18 AM                62 testfile.txt
10/28/2016  11:20 AM    DIR          Users
10/28/2016  11:20 AM    DIR          Windows
           2 File(s)          1,956 bytes
           4 Dir(s)  21,259,096,064 bytes free
 ---> 01c7f3bef04f
Removing intermediate container a2c157f842f5
Successfully built 01c7f3bef04f
PS E:\myproject>
```

### [check](#check)

```dockerfile
# check=skip=<checks|all>
# check=error=<boolean>
```

The `check` directive is used to configure how [build checks](https://docs.docker.com/build/checks/) are evaluated. By default, all checks are run, and failures are treated as warnings.

You can disable specific checks using `#check=skip=<check-name>`. To specify multiple checks to skip, separate them with a comma:

```dockerfile
# check=skip=JSONArgsRecommended,StageNameCasing
```

To disable all checks, use `#check=skip=all`.

By default, builds with failing build checks exit with a zero status code despite warnings. To make the build fail on warnings, set `#check=error=true`.

```dockerfile
# check=error=true
```

> Note
>
> When using the `check` directive, with `error=true` option, it is recommended to pin the [Dockerfile syntax](#syntax) to a specific version. Otherwise, your build may start to fail when new checks are added in the future versions.

To combine both the `skip` and `error` options, use a semi-colon to separate them:

```dockerfile
# check=skip=JSONArgsRecommended;error=true
```

To see all available checks, see the [build checks reference](https://docs.docker.com/reference/build-checks/). Note that the checks available depend on the Dockerfile syntax version. To make sure you're getting the most up-to-date checks, use the [`syntax`](#syntax) directive to specify the Dockerfile syntax version to the latest stable version.

## [Environment replacement](#environment-replacement)

Environment variables (declared with [the `ENV` statement](#env)) can also be used in certain instructions as variables to be interpreted by the Dockerfile. Escapes are also handled for including variable-like syntax into a statement literally.

Environment variables are notated in the Dockerfile either with `$variable_name` or `${variable_name}`. They are treated equivalently and the brace syntax is typically used to address issues with variable names with no whitespace, like `${foo}_bar`.

The `${variable_name}` syntax also supports a few of the standard `bash` modifiers as specified below:

* `${variable:-word}` indicates that if `variable` is set and non-empty then the result will be that value. If `variable` is unset or empty then `word` will be the result.
* `${variable-word}` indicates that if `variable` is set (even if empty) then the result will be that value. If `variable` is unset then `word` will be the result.
* `${variable:+word}` indicates that if `variable` is set and non-empty then `word` will be the result, otherwise the result is the empty string.
* `${variable+word}` indicates that if `variable` is set (even if empty) then `word` will be the result, otherwise the result is the empty string.

The following variable replacements are supported in a pre-release version of Dockerfile syntax, when using the `# syntax=docker/dockerfile-upstream:master` syntax directive in your Dockerfile:

* `${variable#pattern}` removes the shortest match of `pattern` from `variable`, seeking from the start of the string.

  ```bash
  str=foobarbaz echo ${str#f*b}     # arbaz
  ```

* `${variable##pattern}` removes the longest match of `pattern` from `variable`, seeking from the start of the string.

  ```bash
  str=foobarbaz echo ${str##f*b}    # az
  ```

* `${variable%pattern}` removes the shortest match of `pattern` from `variable`, seeking backwards from the end of the string.

  ```bash
  string=foobarbaz echo ${string%b*}    # foobar
  ```

* `${variable%%pattern}` removes the longest match of `pattern` from `variable`, seeking backwards from the end of the string.

  ```bash
  string=foobarbaz echo ${string%%b*}   # foo
  ```

* `${variable/pattern/replacement}` replace the first occurrence of `pattern` in `variable` with `replacement`

  ```bash
  string=foobarbaz echo ${string/ba/fo}  # fooforbaz
  ```

* `${variable//pattern/replacement}` replaces all occurrences of `pattern` in `variable` with `replacement`

  ```bash
  string=foobarbaz echo ${string//ba/fo}  # fooforfoz
  ```

In all cases, `word` can be any string, including additional environment variables.

`pattern` is a glob pattern where `?` matches any single character and `*` any number of characters (including zero). To match literal `?` and `*`, use a backslash escape: `\?` and `\*`.

You can escape whole variable names by adding a `\` before the variable: `\$foo` or `\${foo}`, for example, will translate to `$foo` and `${foo}` literals respectively.

Example (parsed representation is displayed after the `#`):

```dockerfile
FROM busybox
ENV FOO=/bar
WORKDIR ${FOO}   # WORKDIR /bar
ADD . $FOO       # ADD . /bar
COPY \$FOO /quux # COPY $FOO /quux
```

Environment variables are supported by the following list of instructions in the Dockerfile:

* `ADD`
* `COPY`
* `ENV`
* `EXPOSE`
* `FROM`
* `LABEL`
* `STOPSIGNAL`
* `USER`
* `VOLUME`
* `WORKDIR`
* `ONBUILD` (when combined with one of the supported instructions above)

You can also use environment variables with `RUN`, `CMD`, and `ENTRYPOINT` instructions, but in those cases the variable substitution is handled by the command shell, not the builder. Note that instructions using the exec form don't invoke a command shell automatically. See [Variable substitution](#variable-substitution).

Environment variable substitution use the same value for each variable throughout the entire instruction. Changing the value of a variable only takes effect in subsequent instructions. Consider the following example:

```dockerfile
ENV abc=hello
ENV abc=bye def=$abc
ENV ghi=$abc
```

* The value of `def` becomes `hello`
* The value of `ghi` becomes `bye`

## [.dockerignore file](#dockerignore-file)

You can use `.dockerignore` file to exclude files and directories from the build context. For more information, see [.dockerignore file](https://docs.docker.com/build/building/context/#dockerignore-files).

## [Shell and exec form](#shell-and-exec-form)

The `RUN`, `CMD`, and `ENTRYPOINT` instructions all have two possible forms:

* `INSTRUCTION ["executable","param1","param2"]` (exec form)
* `INSTRUCTION command param1 param2` (shell form)

The exec form makes it possible to avoid shell string munging, and to invoke commands using a specific command shell, or any other executable. It uses a JSON array syntax, where each element in the array is a command, flag, or argument.

The shell form is more relaxed, and emphasizes ease of use, flexibility, and readability. The shell form automatically uses a command shell, whereas the exec form does not.

### [Exec form](#exec-form)

The exec form is parsed as a JSON array, which means that you must use double-quotes (") around words, not single-quotes (').

```dockerfile
ENTRYPOINT ["/bin/bash", "-c", "echo hello"]
```

The exec form is best used to specify an `ENTRYPOINT` instruction, combined with `CMD` for setting default arguments that can be overridden at runtime. For more information, see [ENTRYPOINT](#entrypoint).

#### [Variable substitution](#variable-substitution)

Using the exec form doesn't automatically invoke a command shell. This means that normal shell processing, such as variable substitution, doesn't happen. For example, `RUN [ "echo", "$HOME" ]` won't handle variable substitution for `$HOME`.

If you want shell processing then either use the shell form or execute a shell directly with the exec form, for example: `RUN [ "sh", "-c", "echo $HOME" ]`. When using the exec form and executing a shell directly, as in the case for the shell form, it's the shell that's doing the environment variable substitution, not the builder.

#### [Backslashes](#backslashes)

In exec form, you must escape backslashes. This is particularly relevant on Windows where the backslash is the path separator. The following line would otherwise be treated as shell form due to not being valid JSON, and fail in an unexpected way:

```dockerfile
RUN ["c:\windows\system32\tasklist.exe"]
```

The correct syntax for this example is:

```dockerfile
RUN ["c:\\windows\\system32\\tasklist.exe"]
```

### [Shell form](#shell-form)

Unlike the exec form, instructions using the shell form always use a command shell. The shell form doesn't use the JSON array format, instead it's a regular string. The shell form string lets you escape newlines using the [escape character](#escape) (backslash by default) to continue a single instruction onto the next line. This makes it easier to use with longer commands, because it lets you split them up into multiple lines. For example, consider these two lines:

```dockerfile
RUN source $HOME/.bashrc && \
echo $HOME
```

They're equivalent to the following line:

```dockerfile
RUN source $HOME/.bashrc && echo $HOME
```

You can also use heredocs with the shell form to break up supported commands.

```dockerfile
RUN <<EOF
  source $HOME/.bashrc
  echo $HOME
EOF
```

For more information about heredocs, see [Here-documents](#here-documents).

### [Use a different shell](#use-a-different-shell)

You can change the default shell using the `SHELL` command. For example:

```dockerfile
SHELL ["/bin/bash", "-c"]
RUN echo hello
```

For more information, see [SHELL](#shell).

## [FROM](#from)

```dockerfile
FROM [--platform=<platform>] <image> [AS <name>]
```

Or

```dockerfile
FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]
```

Or

```dockerfile
FROM [--platform=<platform>] <image>[@<digest>] [AS <name>]
```

The `FROM` instruction initializes a new build stage and sets the [base image](https://docs.docker.com/glossary/#base-image) for subsequent instructions. As such, a valid Dockerfile must start with a `FROM` instruction. The image can be any valid image.

* `ARG` is the only instruction that may precede `FROM` in the Dockerfile. See [Understand how ARG and FROM interact](#understand-how-arg-and-from-interact).

* `FROM` can appear multiple times within a single Dockerfile to create multiple images or use one build stage as a dependency for another. Simply make a note of the last image ID output by the commit before each new `FROM` instruction. Each `FROM` instruction clears any state created by previous instructions.

* Optionally a name can be given to a new build stage by adding `AS name` to the `FROM` instruction. The name can be used in subsequent `FROM <name>`, [`COPY --from=<name>`](#copy---from), and [`RUN --mount=type=bind,from=<name>`](#run---mounttypebind) instructions to refer to the image built in this stage.

  Using a previous build stage as the base for a subsequent stage is a common pattern for sharing a common base environment:

  ```dockerfile
  FROM ubuntu AS base
  RUN apt-get update && apt-get install -y shared-tooling

  FROM base AS dev
  RUN apt-get install -y dev-tooling

  FROM base AS prod
  COPY --from=build /app /app
  ```

* The `tag` or `digest` values are optional. If you omit either of them, the builder assumes a `latest` tag by default. The builder returns an error if it can't find the `tag` value.

The optional `--platform` flag can be used to specify the platform of the image in case `FROM` references a multi-platform image. For example, `linux/amd64`, `linux/arm64`, or `windows/amd64`. By default, the target platform of the build request is used. Global build arguments can be used in the value of this flag, for example [automatic platform ARGs](#automatic-platform-args-in-the-global-scope) allow you to force a stage to native build platform (`--platform=$BUILDPLATFORM`), and use it to cross-compile to the target platform inside the stage.

### [Understand how ARG and FROM interact](#understand-how-arg-and-from-interact)

`FROM` instructions support variables that are declared by any `ARG` instructions that occur before the first `FROM`.

```dockerfile
ARG  CODE_VERSION=latest
FROM base:${CODE_VERSION}
CMD  /code/run-app

FROM extras:${CODE_VERSION}
CMD  /code/run-extras
```

An `ARG` declared before a `FROM` is outside of a build stage, so it can't be used in any instruction after a `FROM`. To use the default value of an `ARG` declared before the first `FROM` use an `ARG` instruction without a value inside of a build stage:

```dockerfile
ARG VERSION=latest
FROM busybox:$VERSION
ARG VERSION
RUN echo $VERSION > image_version
```

## [RUN](#run)

The `RUN` instruction will execute any commands to create a new layer on top of the current image. The added layer is used in the next step in the Dockerfile. `RUN` has two forms:

```dockerfile
# Shell form:
RUN [OPTIONS] <command> ...
# Exec form:
RUN [OPTIONS] [ "<command>", ... ]
```

For more information about the differences between these two forms, see [shell or exec forms](#shell-and-exec-form).

The shell form is most commonly used, and lets you break up longer instructions into multiple lines, either using newline [escapes](#escape), or with [heredocs](#here-documents):

```dockerfile
RUN <<EOF
apt-get update
apt-get install -y curl
EOF
```

The available `[OPTIONS]` for the `RUN` instruction are:

| Option                          | Minimum Dockerfile version |
| ------------------------------- | -------------------------- |
| [`--device`](#run---device)     | 1.14-labs                  |
| [`--mount`](#run---mount)       | 1.2                        |
| [`--network`](#run---network)   | 1.3                        |
| [`--security`](#run---security) | 1.20                       |

### [Cache invalidation for RUN instructions](#cache-invalidation-for-run-instructions)

The cache for `RUN` instructions isn't invalidated automatically during the next build. The cache for an instruction like `RUN apt-get dist-upgrade -y` will be reused during the next build. The cache for `RUN` instructions can be invalidated by using the `--no-cache` flag, for example `docker build --no-cache`.

See the [Dockerfile Best Practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/) for more information.

The cache for `RUN` instructions can be invalidated by [`ADD`](#add) and [`COPY`](#copy) instructions.

### [RUN --device](#run---device)

> Note
>
> Not yet available in stable syntax, use [`docker/dockerfile:1-labs`](#syntax) version. It also needs BuildKit 0.20.0 or later.

```dockerfile
RUN --device=name,[required]
```

`RUN --device` allows build to request [CDI devices](https://github.com/moby/buildkit/blob/master/docs/cdi.md) to be available to the build step.

> Warning
>
> The use of `--device` is protected by the `device` entitlement, which needs to be enabled when starting the buildkitd daemon with `--allow-insecure-entitlement device` flag or in [buildkitd config](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md), and for a build request with [`--allow device` flag](https://docs.docker.com/engine/reference/commandline/buildx_build/#allow).

The device `name` is provided by the CDI specification registered in BuildKit.

In the following example, multiple devices are registered in the CDI specification for the `vendor1.com/device` vendor.

```yaml
cdiVersion: "0.6.0"
kind: "vendor1.com/device"
devices:
  - name: foo
    containerEdits:
      env:
        - FOO=injected
  - name: bar
    annotations:
      org.mobyproject.buildkit.device.class: class1
    containerEdits:
      env:
        - BAR=injected
  - name: baz
    annotations:
      org.mobyproject.buildkit.device.class: class1
    containerEdits:
      env:
        - BAZ=injected
  - name: qux
    annotations:
      org.mobyproject.buildkit.device.class: class2
    containerEdits:
      env:
        - QUX=injected
annotations:
  org.mobyproject.buildkit.device.autoallow: true
```

The device name format is flexible and accepts various patterns to support multiple device configurations:

* `vendor1.com/device`: request the first device found for this vendor
* `vendor1.com/device=foo`: request a specific device
* `vendor1.com/device=*`: request all devices for this vendor
* `class1`: request devices by `org.mobyproject.buildkit.device.class` annotation

> Note
>
> Annotations are supported by the CDI specification since 0.6.0.

> Note
>
> To automatically allow all devices registered in the CDI specification, you can set the `org.mobyproject.buildkit.device.autoallow` annotation. You can also set this annotation for a specific device.

#### [Example: CUDA-Powered LLaMA Inference](#example-cuda-powered-llama-inference)

In this example we use the `--device` flag to run `llama.cpp` inference using an NVIDIA GPU device through CDI:

```dockerfile
# syntax=docker/dockerfile:1-labs

FROM scratch AS model
ADD https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf /model.gguf

FROM scratch AS prompt
COPY <<EOF prompt.txt
Q: Generate  a list of 10 unique biggest countries by population in JSON with their estimated poulation in 1900 and 2024. Answer only newline formatted JSON with keys "country", "population_1900", "population_2024" with 10 items.
A:
[
    {

EOF

FROM ghcr.io/ggml-org/llama.cpp:full-cuda-b5124
RUN --device=nvidia.com/gpu=all \
    --mount=from=model,target=/models \
    --mount=from=prompt,target=/tmp \
    ./llama-cli -m /models/model.gguf -no-cnv -ngl 99 -f /tmp/prompt.txt
```

### [RUN --mount](#run---mount)

```dockerfile
RUN --mount=[type=TYPE][,option=<value>[,option=<value>]...]
```

`RUN --mount` allows you to create filesystem mounts that the build can access. This can be used to:

* Create bind mount to the host filesystem or other build stages
* Access build secrets or ssh-agent sockets
* Use a persistent package management cache to speed up your build

The supported mount types are:

| Type                                     | Description                                                                                                              |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [`bind`](#run---mounttypebind) (default) | Bind-mount context directories (read-only).                                                                              |
| [`cache`](#run---mounttypecache)         | Mount a temporary directory to cache directories for compilers and package managers.                                     |
| [`tmpfs`](#run---mounttypetmpfs)         | Mount a `tmpfs` in the build container.                                                                                  |
| [`secret`](#run---mounttypesecret)       | Allow the build container to access secure files such as private keys without baking them into the image or build cache. |
| [`ssh`](#run---mounttypessh)             | Allow the build container to access SSH keys via SSH agents, with support for passphrases.                               |

### [RUN --mount=type=bind](#run---mounttypebind)

This mount type allows binding files or directories to the build container. A bind mount is read-only by default.

| Option                                   | Description                                                                                                                                   |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `target`, `dst`, `destination`[1](#fn:1) | Mount path.                                                                                                                                   |
| `source`                                 | Source path in the `from`. Defaults to the root of the `from`.                                                                                |
| `from`                                   | Build stage, context, or image name for the root of the source. Defaults to the build context.                                                |
| `rw`,`readwrite`                         | Allow writes on the mount. Written data will be discarded after the `RUN` instruction completes and will not be committed to the image layer. |

### [RUN --mount=type=cache](#run---mounttypecache)

This mount type allows the build container to cache directories for compilers and package managers.

| Option                                   | Description                                                                                                                                                                                                                                                                |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                     | Optional ID to identify separate/different caches. Defaults to value of `target`.                                                                                                                                                                                          |
| `target`, `dst`, `destination`[1](#fn:1) | Mount path.                                                                                                                                                                                                                                                                |
| `ro`,`readonly`                          | Read-only if set.                                                                                                                                                                                                                                                          |
| `sharing`                                | One of `shared`, `private`, or `locked`. Defaults to `shared`. A `shared` cache mount can be used concurrently by multiple writers. `private` creates a new mount if there are multiple writers. `locked` pauses the second writer until the first one releases the mount. |
| `from`                                   | Build stage, context, or image name to use as a base of the cache mount. Defaults to empty directory.                                                                                                                                                                      |
| `source`                                 | Subpath in the `from` to mount. Defaults to the root of the `from`.                                                                                                                                                                                                        |
| `mode`                                   | File mode for new cache directory in octal. Default `0755`.                                                                                                                                                                                                                |
| `uid`                                    | User ID for new cache directory. Default `0`.                                                                                                                                                                                                                              |
| `gid`                                    | Group ID for new cache directory. Default `0`.                                                                                                                                                                                                                             |

Contents of the cache directories persists between builder invocations without invalidating the instruction cache. Cache mounts should only be used for better performance. Your build should work with any contents of the cache directory as another build may overwrite the files or GC may clean it if more storage space is needed.

#### [Example: cache Go packages](#example-cache-go-packages)

```dockerfile
# syntax=docker/dockerfile:1
FROM golang
RUN --mount=type=cache,target=/root/.cache/go-build \
  go build ...
```

#### [Example: cache apt packages](#example-cache-apt-packages)

```dockerfile
# syntax=docker/dockerfile:1
FROM ubuntu
RUN rm -f /etc/apt/apt.conf.d/docker-clean; echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' > /etc/apt/apt.conf.d/keep-cache
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
  --mount=type=cache,target=/var/lib/apt,sharing=locked \
  apt-get update && apt-get --no-install-recommends install -y gcc
```

Apt needs exclusive access to its data, so the caches use the option `sharing=locked`, which will make sure multiple parallel builds using the same cache mount will wait for each other and not access the same cache files at the same time. You could also use `sharing=private` if you prefer to have each build create another cache directory in this case.

### [RUN --mount=type=tmpfs](#run---mounttypetmpfs)

This mount type allows mounting `tmpfs` in the build container.

| Option                                   | Description                                           |
| ---------------------------------------- | ----------------------------------------------------- |
| `target`, `dst`, `destination`[1](#fn:1) | Mount path.                                           |
| `size`                                   | Specify an upper limit on the size of the filesystem. |

### [RUN --mount=type=secret](#run---mounttypesecret)

This mount type allows the build container to access secret values, such as tokens or private keys, without baking them into the image.

By default, the secret is mounted as a file. You can also mount the secret as an environment variable by setting the `env` option.

| Option                         | Description                                                                                                     |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `id`                           | ID of the secret. Defaults to basename of the target path.                                                      |
| `target`, `dst`, `destination` | Mount the secret to the specified path. Defaults to `/run/secrets/` + `id` if unset and if `env` is also unset. |
| `env`                          | Mount the secret to an environment variable instead of a file, or both. (since Dockerfile v1.10.0)              |
| `required`                     | If set to `true`, the instruction errors out when the secret is unavailable. Defaults to `false`.               |
| `mode`                         | File mode for secret file in octal. Default `0400`.                                                             |
| `uid`                          | User ID for secret file. Default `0`.                                                                           |
| `gid`                          | Group ID for secret file. Default `0`.                                                                          |

#### [Example: access to S3](#example-access-to-s3)

```dockerfile
# syntax=docker/dockerfile:1
FROM python:3
RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
  aws s3 cp s3://... ...
```

```console
$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .
```

#### [Example: Mount as environment variable](#example-mount-as-environment-variable)

The following example takes the secret `API_KEY` and mounts it as an environment variable with the same name.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN --mount=type=secret,id=API_KEY,env=API_KEY \
    some-command --token-from-env $API_KEY
```

Assuming that the `API_KEY` environment variable is set in the build environment, you can build this with the following command:

```console
$ docker buildx build --secret id=API_KEY .
```

### [RUN --mount=type=ssh](#run---mounttypessh)

This mount type allows the build container to access SSH keys via SSH agents, with support for passphrases.

| Option                         | Description                                                                                    |
| ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `id`                           | ID of SSH agent socket or key. Defaults to "default".                                          |
| `target`, `dst`, `destination` | SSH agent socket path. Defaults to `/run/buildkit/ssh_agent.${N}`.                             |
| `required`                     | If set to `true`, the instruction errors out when the key is unavailable. Defaults to `false`. |
| `mode`                         | File mode for socket in octal. Default `0600`.                                                 |
| `uid`                          | User ID for socket. Default `0`.                                                               |
| `gid`                          | Group ID for socket. Default `0`.                                                              |

#### [Example: access to GitLab](#example-access-to-gitlab)

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh \
  ssh -q -T git@gitlab.com 2>&1 | tee /hello
# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" should be printed here
# with the type of build progress is defined as `plain`.
```

```console
$ eval $(ssh-agent)
$ ssh-add ~/.ssh/id_rsa
(Input your passphrase here)
$ docker buildx build --ssh default=$SSH_AUTH_SOCK .
```

You can also specify a path to `*.pem` file on the host directly instead of `$SSH_AUTH_SOCK`. However, pem files with passphrases are not supported.

### [RUN --network](#run---network)

```dockerfile
RUN --network=TYPE
```

`RUN --network` allows control over which networking environment the command is run in.

The supported network types are:

| Type                                         | Description                            |
| -------------------------------------------- | -------------------------------------- |
| [`default`](#run---networkdefault) (default) | Run in the default network.            |
| [`none`](#run---networknone)                 | Run with no network access.            |
| [`host`](#run---networkhost)                 | Run in the host's network environment. |

### [RUN --network=default](#run---networkdefault)

Equivalent to not supplying a flag at all, the command is run in the default network for the build.

### [RUN --network=none](#run---networknone)

The command is run with no network access (`lo` is still available, but is isolated to this process)

#### [Example: isolating external effects](#example-isolating-external-effects)

```dockerfile
# syntax=docker/dockerfile:1
FROM python:3.6
ADD mypackage.tgz wheels/
RUN --network=none pip install --find-links wheels mypackage
```

`pip` will only be able to install the packages provided in the tarfile, which can be controlled by an earlier build stage.

### [RUN --network=host](#run---networkhost)

The command is run in the host's network environment (similar to `docker build --network=host`, but on a per-instruction basis)

> Warning
>
> The use of `--network=host` is protected by the `network.host` entitlement, which needs to be enabled when starting the buildkitd daemon with `--allow-insecure-entitlement network.host` flag or in [buildkitd config](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md), and for a build request with [`--allow network.host` flag](https://docs.docker.com/engine/reference/commandline/buildx_build/#allow).

### [RUN --security](#run---security)

```dockerfile
RUN --security=<sandbox|insecure>
```

The default security mode is `sandbox`. With `--security=insecure`, the builder runs the command without sandbox in insecure mode, which allows to run flows requiring elevated privileges (e.g. containerd). This is equivalent to running `docker run --privileged`.

> Warning
>
> In order to access this feature, entitlement `security.insecure` should be enabled when starting the buildkitd daemon with `--allow-insecure-entitlement security.insecure` flag or in [buildkitd config](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md), and for a build request with [`--allow security.insecure` flag](https://docs.docker.com/engine/reference/commandline/buildx_build/#allow).

Default sandbox mode can be activated via `--security=sandbox`, but that is no-op.

#### [Example: check entitlements](#example-check-entitlements)

```dockerfile
# syntax=docker/dockerfile:1
FROM ubuntu
RUN --security=insecure cat /proc/self/status | grep CapEff
```

```text
#84 0.093 CapEff:	0000003fffffffff
```

## [CMD](#cmd)

The `CMD` instruction sets the command to be executed when running a container from an image.

You can specify `CMD` instructions using [shell or exec forms](#shell-and-exec-form):

* `CMD ["executable","param1","param2"]` (exec form)
* `CMD ["param1","param2"]` (exec form, as default parameters to `ENTRYPOINT`)
* `CMD command param1 param2` (shell form)

There can only be one `CMD` instruction in a Dockerfile. If you list more than one `CMD`, only the last one takes effect.

The purpose of a `CMD` is to provide defaults for an executing container. These defaults can include an executable, or they can omit the executable, in which case you must specify an `ENTRYPOINT` instruction as well.

If you would like your container to run the same executable every time, then you should consider using `ENTRYPOINT` in combination with `CMD`. See [`ENTRYPOINT`](#entrypoint). If the user specifies arguments to `docker run` then they will override the default specified in `CMD`, but still use the default `ENTRYPOINT`.

If `CMD` is used to provide default arguments for the `ENTRYPOINT` instruction, both the `CMD` and `ENTRYPOINT` instructions should be specified in the [exec form](#exec-form).

> Note
>
> Don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits the result; `CMD` doesn't execute anything at build time, but specifies the intended command for the image.

## [LABEL](#label)

```dockerfile
LABEL <key>=<value> [<key>=<value>...]
```

The `LABEL` instruction adds metadata to an image. A `LABEL` is a key-value pair. To include spaces within a `LABEL` value, use quotes and backslashes as you would in command-line parsing. A few usage examples:

```dockerfile
LABEL "com.example.vendor"="ACME Incorporated"
LABEL com.example.label-with-value="foo"
LABEL version="1.0"
LABEL description="This text illustrates \
that label-values can span multiple lines."
```

An image can have more than one label. You can specify multiple labels on a single line. Prior to Docker 1.10, this decreased the size of the final image, but this is no longer the case. You may still choose to specify multiple labels in a single instruction, in one of the following two ways:

```dockerfile
LABEL multi.label1="value1" multi.label2="value2" other="value3"
```

```dockerfile
LABEL multi.label1="value1" \
      multi.label2="value2" \
      other="value3"
```

> Note
>
> Be sure to use double quotes and not single quotes. Particularly when you are using string interpolation (e.g. `LABEL example="foo-$ENV_VAR"`), single quotes will take the string as is without unpacking the variable's value.

Labels included in base images (images in the `FROM` line) are inherited by your image. If a label already exists but with a different value, the most-recently-applied value overrides any previously-set value.

In a multi-stage build, labels from intermediate stages are only present in the final image if the final stage is directly or indirectly based on them (via `FROM`). Labels from a stage that you only reference with `COPY --from` or `RUN --mount=from=` are not included in the output image. Labels from the base image specified in the final `FROM` instruction are always inherited.

To view an image's labels, use the `docker image inspect` command. You can use the `--format` option to show just the labels;

```console
$ docker image inspect --format='{{json .Config.Labels}}' myimage
```

```json
{
  "com.example.vendor": "ACME Incorporated",
  "com.example.label-with-value": "foo",
  "version": "1.0",
  "description": "This text illustrates that label-values can span multiple lines.",
  "multi.label1": "value1",
  "multi.label2": "value2",
  "other": "value3"
}
```

## [MAINTAINER (deprecated)](#maintainer-deprecated)

```dockerfile
MAINTAINER <name>
```

The `MAINTAINER` instruction sets the *Author* field of the generated images. The `LABEL` instruction is a much more flexible version of this and you should use it instead, as it enables setting any metadata you require, and can be viewed easily, for example with `docker inspect`. To set a label corresponding to the `MAINTAINER` field you could use:

```dockerfile
LABEL org.opencontainers.image.authors="SvenDowideit@home.org.au"
```

This will then be visible from `docker inspect` with the other labels.

## [EXPOSE](#expose)

```dockerfile
EXPOSE <port> [<port>/<protocol>...]
```

The `EXPOSE` instruction informs Docker that the container listens on the specified network ports at runtime. You can specify whether the port listens on TCP or UDP, and the default is TCP if you don't specify a protocol.

The `EXPOSE` instruction doesn't actually publish the port. It functions as a type of documentation between the person who builds the image and the person who runs the container, about which ports are intended to be published. To publish the port when running the container, use the `-p` flag on `docker run` to publish and map one or more ports, or the `-P` flag to publish all exposed ports and map them to high-order ports.

By default, `EXPOSE` assumes TCP. You can also specify UDP:

```dockerfile
EXPOSE 80/udp
```

To expose on both TCP and UDP, include two lines:

```dockerfile
EXPOSE 80/tcp
EXPOSE 80/udp
```

In this case, if you use `-P` with `docker run`, the port will be exposed once for TCP and once for UDP. Remember that `-P` uses an ephemeral high-ordered host port on the host, so TCP and UDP doesn't use the same port.

Regardless of the `EXPOSE` settings, you can override them at runtime by using the `-p` flag. For example

```console
$ docker run -p 80:80/tcp -p 80:80/udp ...
```

To set up port redirection on the host system, see [using the -P flag](https://docs.docker.com/reference/cli/docker/container/run/#publish). The `docker network` command supports creating networks for communication among containers without the need to expose or publish specific ports, because the containers connected to the network can communicate with each other over any port. For detailed information, see the [overview of this feature](https://docs.docker.com/engine/userguide/networking/).

## [ENV](#env)

```dockerfile
ENV <key>=<value> [<key>=<value>...]
```

The `ENV` instruction sets the environment variable `<key>` to the value `<value>`. This value will be in the environment for all subsequent instructions in the build stage and can be [replaced inline](#environment-replacement) in many as well. The value will be interpreted for other environment variables, so quote characters will be removed if they are not escaped. Like command line parsing, quotes and backslashes can be used to include spaces within values.

Example:

```dockerfile
ENV MY_NAME="John Doe"
ENV MY_DOG=Rex\ The\ Dog
ENV MY_CAT=fluffy
```

The `ENV` instruction allows for multiple `<key>=<value> ...` variables to be set at one time, and the example below will yield the same net results in the final image:

```dockerfile
ENV MY_NAME="John Doe" MY_DOG=Rex\ The\ Dog \
    MY_CAT=fluffy
```

The environment variables set using `ENV` will persist when a container is run from the resulting image. You can view the values using `docker inspect`, and change them using `docker run --env <key>=<value>`.

A stage inherits any environment variables that were set using `ENV` by its parent stage or any ancestor. Refer to the [multi-stage builds section](https://docs.docker.com/build/building/multi-stage/) in the manual for more information.

Environment variable persistence can cause unexpected side effects. For example, setting `ENV DEBIAN_FRONTEND=noninteractive` changes the behavior of `apt-get`, and may confuse users of your image.

If an environment variable is only needed during build, and not in the final image, consider setting a value for a single command instead:

```dockerfile
RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ...
```

Or using [`ARG`](#arg), which is not persisted in the final image:

```dockerfile
ARG DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y ...
```

> Note
>
> **Alternative syntax**
>
> The `ENV` instruction also allows an alternative syntax `ENV <key> <value>`, omitting the `=`. For example:
>
> ```dockerfile
> ENV MY_VAR my-value
> ```
>
> This syntax does not allow for multiple environment-variables to be set in a single `ENV` instruction, and can be confusing. For example, the following sets a single environment variable (`ONE`) with value `"TWO= THREE=world"`:
>
> ```dockerfile
> ENV ONE TWO= THREE=world
> ```
>
> The alternative syntax is supported for backward compatibility, but discouraged for the reasons outlined above, and may be removed in a future release.

## [ADD](#add)

ADD has two forms. The latter form is required for paths containing whitespace.

```dockerfile
ADD [OPTIONS] <src> ... <dest>
ADD [OPTIONS] ["<src>", ... "<dest>"]
```

The available `[OPTIONS]` are:

| Option                                  | Minimum Dockerfile version |
| --------------------------------------- | -------------------------- |
| [`--keep-git-dir`](#add---keep-git-dir) | 1.1                        |
| [`--checksum`](#add---checksum)         | 1.6                        |
| [`--chmod`](#add---chmod)               | 1.2                        |
| [`--chown`](#add---chown)               |                            |
| [`--link`](#add---link)                 | 1.4                        |
| [`--unpack`](#add---unpack)             | 1.17                       |
| [`--exclude`](#add---exclude)           | 1.19                       |

The `ADD` instruction copies new files or directories from `<src>` and adds them to the filesystem of the image at the path `<dest>`. Files and directories can be copied from the build context, a remote URL, or a Git repository.

The `ADD` and `COPY` instructions are functionally similar, but serve slightly different purposes. Learn more about the [differences between `ADD` and `COPY`](https://docs.docker.com/build/building/best-practices/#add-or-copy).

### [Source](#source)

You can specify multiple source files or directories with `ADD`. The last argument must always be the destination. For example, to add two files, `file1.txt` and `file2.txt`, from the build context to `/usr/src/things/` in the build container:

```dockerfile
ADD file1.txt file2.txt /usr/src/things/
```

If you specify multiple source files, either directly or using a wildcard, then the destination must be a directory (must end with a slash `/`).

To add files from a remote location, you can specify a URL or the address of a Git repository as the source. For example:

```dockerfile
ADD https://example.com/archive.zip /usr/src/things/
ADD git@github.com:user/repo.git /usr/src/things/
```

BuildKit detects the type of `<src>` and processes it accordingly.

* If `<src>` is a local file or directory, the contents of the directory are copied to the specified destination. See [Adding files from the build context](#adding-files-from-the-build-context).
* If `<src>` is a local tar archive, it is decompressed and extracted to the specified destination. See [Adding local tar archives](#adding-local-tar-archives).
* If `<src>` is a URL, the contents of the URL are downloaded and placed at the specified destination. See [Adding files from a URL](#adding-files-from-a-url).
* If `<src>` is a Git repository, the repository is cloned to the specified destination. See [Adding files from a Git repository](#adding-files-from-a-git-repository).

#### [Adding files from the build context](#adding-files-from-the-build-context)

Any relative or local path that doesn't begin with a `http://`, `https://`, or `git@` protocol prefix is considered a local file path. The local file path is relative to the build context. For example, if the build context is the current directory, `ADD file.txt /` adds the file at `./file.txt` to the root of the filesystem in the build container.

Specifying a source path with a leading slash or one that navigates outside the build context, such as `ADD ../something /something`, automatically removes any parent directory navigation (`../`). Trailing slashes in the source path are also disregarded, making `ADD something/ /something` equivalent to `ADD something /something`.

If the source is a directory, the contents of the directory are copied, including filesystem metadata. The directory itself isn't copied, only its contents. If it contains subdirectories, these are also copied, and merged with any existing directories at the destination. Any conflicts are resolved in favor of the content being added, on a file-by-file basis, except if you're trying to copy a directory onto an existing file, in which case an error is raised.

If the source is a file, the file and its metadata are copied to the destination. File permissions are preserved. If the source is a file and a directory with the same name exists at the destination, an error is raised.

If you pass a Dockerfile through stdin to the build (`docker build - < Dockerfile`), there is no build context. In this case, you can only use the `ADD` instruction to copy remote files. You can also pass a tar archive through stdin: (`docker build - < archive.tar`), the Dockerfile at the root of the archive and the rest of the archive will be used as the context of the build.

##### [Pattern matching](#pattern-matching)

For local files, each `<src>` may contain wildcards and matching will be done using Go's [filepath.Match](https://golang.org/pkg/path/filepath#Match) rules.

For example, to add all files and directories in the root of the build context ending with `.png`:

```dockerfile
ADD *.png /dest/
```

In the following example, `?` is a single-character wildcard, matching e.g. `index.js` and `index.ts`.

```dockerfile
ADD index.?s /dest/
```

When adding files or directories that contain special characters (such as `[` and `]`), you need to escape those paths following the Golang rules to prevent them from being treated as a matching pattern. For example, to add a file named `arr[0].txt`, use the following;

```dockerfile
ADD arr[[]0].txt /dest/
```

#### [Adding local tar archives](#adding-local-tar-archives)

When using a local tar archive as the source for `ADD`, and the archive is in a recognized compression format (`gzip`, `bzip2` or `xz`, or uncompressed), the archive is decompressed and extracted into the specified destination. Local tar archives are extracted by default, see the \[`ADD --unpack` flag].

When a directory is extracted, it has the same behavior as `tar -x`. The result is the union of:

1. Whatever existed at the destination path, and
2. The contents of the source tree, with conflicts resolved in favor of the content being added, on a file-by-file basis.

> Note
>
> Whether a file is identified as a recognized compression format or not is done solely based on the contents of the file, not the name of the file. For example, if an empty file happens to end with `.tar.gz` this isn't recognized as a compressed file and doesn't generate any kind of decompression error message, rather the file will simply be copied to the destination.

#### [Adding files from a URL](#adding-files-from-a-url)

In the case where source is a remote file URL, the destination will have permissions of 600. If the HTTP response contains a `Last-Modified` header, the timestamp from that header will be used to set the `mtime` on the destination file. However, like any other file processed during an `ADD`, `mtime` isn't included in the determination of whether or not the file has changed and the cache should be updated.

If remote file is a tar archive, the archive is not extracted by default. To download and extract the archive, use the \[`ADD --unpack` flag].

If the destination ends with a trailing slash, then the filename is inferred from the URL path. For example, `ADD http://example.com/foobar /` would create the file `/foobar`. The URL must have a nontrivial path so that an appropriate filename can be discovered (`http://example.com` doesn't work).

If the destination doesn't end with a trailing slash, the destination path becomes the filename of the file downloaded from the URL. For example, `ADD http://example.com/foo /bar` creates the file `/bar`.

If your URL files are protected using authentication, you need to use `RUN wget`, `RUN curl` or use another tool from within the container as the `ADD` instruction doesn't support authentication.

#### [Adding files from a Git repository](#adding-files-from-a-git-repository)

To use a Git repository as the source for `ADD`, you can reference the repository's HTTP or SSH address as the source. The repository is cloned to the specified destination in the image.

```dockerfile
ADD https://github.com/user/repo.git /mydir/
```

You can use URL fragments to specify a specific branch, tag, commit, or subdirectory. For example, to add the `docs` directory of the `v0.14.1` tag of the `buildkit` repository:

```dockerfile
ADD git@github.com:moby/buildkit.git#v0.14.1:docs /buildkit-docs
```

For more information about Git URL fragments, see [URL fragments](https://docs.docker.com/build/building/context/#url-fragments).

When adding from a Git repository, the permissions bits for files are 644. If a file in the repository has the executable bit set, it will have permissions set to 755. Directories have permissions set to 755.

When using a Git repository as the source, the repository must be accessible from the build context. To add a repository via SSH, whether public or private, you must pass an SSH key for authentication. For example, given the following Dockerfile:

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
ADD git@git.example.com:foo/bar.git /bar
```

To build this Dockerfile, pass the `--ssh` flag to the `docker build` to mount the SSH agent socket to the build. For example:

```console
$ docker build --ssh default .
```

For more information about building with secrets, see [Build secrets](https://docs.docker.com/build/building/secrets/).

### [Destination](#destination)

If the destination path begins with a forward slash, it's interpreted as an absolute path, and the source files are copied into the specified destination relative to the root of the current build stage.

```dockerfile
# create /abs/test.txt
ADD test.txt /abs/
```

Trailing slashes are significant. For example, `ADD test.txt /abs` creates a file at `/abs`, whereas `ADD test.txt /abs/` creates `/abs/test.txt`.

If the destination path doesn't begin with a leading slash, it's interpreted as relative to the working directory of the build container.

```dockerfile
WORKDIR /usr/src/app
# create /usr/src/app/rel/test.txt
ADD test.txt rel/
```

If destination doesn't exist, it's created, along with all missing directories in its path.

If the source is a file, and the destination doesn't end with a trailing slash, the source file will be written to the destination path as a file.

### [ADD --keep-git-dir](#add---keep-git-dir)

```dockerfile
ADD [--keep-git-dir=<boolean>] <src> ... <dir>
```

When `<src>` is the HTTP or SSH address of a remote Git repository, BuildKit adds the contents of the Git repository to the image excluding the `.git` directory by default.

The `--keep-git-dir=true` flag lets you preserve the `.git` directory.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
ADD --keep-git-dir=true https://github.com/moby/buildkit.git#v0.10.1 /buildkit
```

### [ADD --checksum](#add---checksum)

```dockerfile
ADD [--checksum=<hash>] <src> ... <dir>
```

The `--checksum` flag lets you verify the checksum of a remote Git or HTTP resource:

* For Git sources, the checksum is the commit SHA. It can be the full commit SHA or match on the prefix (1 or more characters).
* For HTTP sources, the checksum is the SHA-256 content digest, formatted as `sha256:<hash>`. SHA-256 is the only supported hash algorithm.

```dockerfile
ADD --checksum=be1f38e https://github.com/moby/buildkit.git#v0.26.2 /
ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d https://mirrors.edge.kernel.org/pub/linux/kernel/Historic/linux-0.01.tar.gz /
```

### [ADD --chmod](#add---chmod)

See [`COPY --chmod`](#copy---chmod).

### [ADD --chown](#add---chown)

See [`COPY --chown`](#copy---chown).

### [ADD --link](#add---link)

See [`COPY --link`](#copy---link).

### [ADD --unpack](#add---unpack)

```dockerfile
ADD [--unpack=<bool>] <src> ... <dir>
```

The `--unpack` flag controls whether or not to automatically unpack tar archives (including compressed formats like `gzip` or `bzip2`) when adding them to the image. Local tar archives are unpacked by default, whereas remote tar archives (where `src` is a URL) are downloaded without unpacking.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
# Download and unpack archive.tar.gz into /download:
ADD --unpack=true https://example.com/archive.tar.gz /download
# Add local tar without unpacking:
ADD --unpack=false my-archive.tar.gz .
```

### [ADD --exclude](#add---exclude)

See [`COPY --exclude`](#copy---exclude).

## [COPY](#copy)

COPY has two forms. The latter form is required for paths containing whitespace.

```dockerfile
COPY [OPTIONS] <src> ... <dest>
COPY [OPTIONS] ["<src>", ... "<dest>"]
```

The available `[OPTIONS]` are:

| Option                         | Minimum Dockerfile version |
| ------------------------------ | -------------------------- |
| [`--from`](#copy---from)       |                            |
| [`--chmod`](#copy---chmod)     | 1.2                        |
| [`--chown`](#copy---chown)     |                            |
| [`--link`](#copy---link)       | 1.4                        |
| [`--parents`](#copy---parents) | 1.20                       |
| [`--exclude`](#copy---exclude) | 1.19                       |

The `COPY` instruction copies new files or directories from `<src>` and adds them to the filesystem of the image at the path `<dest>`. Files and directories can be copied from the build context, build stage, named context, or an image.

The `ADD` and `COPY` instructions are functionally similar, but serve slightly different purposes. Learn more about the [differences between `ADD` and `COPY`](https://docs.docker.com/build/building/best-practices/#add-or-copy).

### [Source](#source-1)

You can specify multiple source files or directories with `COPY`. The last argument must always be the destination. For example, to copy two files, `file1.txt` and `file2.txt`, from the build context to `/usr/src/things/` in the build container:

```dockerfile
COPY file1.txt file2.txt /usr/src/things/
```

If you specify multiple source files, either directly or using a wildcard, then the destination must be a directory (must end with a slash `/`).

`COPY` accepts a flag `--from=<name>` that lets you specify the source location to be a build stage, context, or image. The following example copies files from a stage named `build`:

```dockerfile
FROM golang AS build
WORKDIR /app
RUN --mount=type=bind,target=. go build -o /myapp ./cmd

COPY --from=build /myapp /usr/bin/
```

For more information about copying from named sources, see the [`--from` flag](#copy---from).

#### [Copying from the build context](#copying-from-the-build-context)

When copying source files from the build context, paths are interpreted as relative to the root of the context.

Specifying a source path with a leading slash or one that navigates outside the build context, such as `COPY ../something /something`, automatically removes any parent directory navigation (`../`). Trailing slashes in the source path are also disregarded, making `COPY something/ /something` equivalent to `COPY something /something`.

If the source is a directory, the contents of the directory are copied, including filesystem metadata. The directory itself isn't copied, only its contents. If it contains subdirectories, these are also copied, and merged with any existing directories at the destination. Any conflicts are resolved in favor of the content being added, on a file-by-file basis, except if you're trying to copy a directory onto an existing file, in which case an error is raised.

If the source is a file, the file and its metadata are copied to the destination. File permissions are preserved. If the source is a file and a directory with the same name exists at the destination, an error is raised.

If you pass a Dockerfile through stdin to the build (`docker build - < Dockerfile`), there is no build context. In this case, you can only use the `COPY` instruction to copy files from other stages, named contexts, or images, using the [`--from` flag](#copy---from). You can also pass a tar archive through stdin: (`docker build - < archive.tar`), the Dockerfile at the root of the archive and the rest of the archive will be used as the context of the build.

When using a Git repository as the build context, the permissions bits for copied files are 644. If a file in the repository has the executable bit set, it will have permissions set to 755. Directories have permissions set to 755.

##### [Pattern matching](#pattern-matching-1)

For local files, each `<src>` may contain wildcards and matching will be done using Go's [filepath.Match](https://golang.org/pkg/path/filepath#Match) rules.

For example, to add all files and directories in the root of the build context ending with `.png`:

```dockerfile
COPY *.png /dest/
```

In the following example, `?` is a single-character wildcard, matching e.g. `index.js` and `index.ts`.

```dockerfile
COPY index.?s /dest/
```

When adding files or directories that contain special characters (such as `[` and `]`), you need to escape those paths following the Golang rules to prevent them from being treated as a matching pattern. For example, to add a file named `arr[0].txt`, use the following;

```dockerfile
COPY arr[[]0].txt /dest/
```

### [Destination](#destination-1)

If the destination path begins with a forward slash, it's interpreted as an absolute path, and the source files are copied into the specified destination relative to the root of the current build stage.

```dockerfile
# create /abs/test.txt
COPY test.txt /abs/
```

Trailing slashes are significant. For example, `COPY test.txt /abs` creates a file at `/abs`, whereas `COPY test.txt /abs/` creates `/abs/test.txt`.

If the destination path doesn't begin with a leading slash, it's interpreted as relative to the working directory of the build container.

```dockerfile
WORKDIR /usr/src/app
# create /usr/src/app/rel/test.txt
COPY test.txt rel/
```

If destination doesn't exist, it's created, along with all missing directories in its path.

If the source is a file, and the destination doesn't end with a trailing slash, the source file will be written to the destination path as a file.

### [COPY --from](#copy---from)

By default, the `COPY` instruction copies files from the build context. The `COPY --from` flag lets you copy files from an image, a build stage, or a named context instead.

```dockerfile
COPY [--from=<image|stage|context>] <src> ... <dest>
```

To copy from a build stage in a [multi-stage build](https://docs.docker.com/build/building/multi-stage/), specify the name of the stage you want to copy from. You specify stage names using the `AS` keyword with the `FROM` instruction.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine AS build
COPY . .
RUN apk add clang
RUN clang -o /hello hello.c

FROM scratch
COPY --from=build /hello /
```

You can also copy files directly from named contexts (specified with `--build-context <name>=<source>`) or images. The following example copies an `nginx.conf` file from the official Nginx image.

```dockerfile
COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf
```

The source path of `COPY --from` is always resolved from filesystem root of the image or stage that you specify.

### [COPY --chmod](#copy---chmod)

```dockerfile
COPY [--chmod=<perms>] <src> ... <dest>
```

The `--chmod` flag supports octal notation (e.g., `755`, `644`) and symbolic notation (e.g., `+x`, `g=u`). Symbolic notation (added in Dockerfile version 1.14) is useful when octal isn't flexible enough. For example, `u=rwX,go=rX` sets directories to 755 and files to 644, while preserving the executable bit on files that already have it. (Capital `X` means "executable only if it's a directory or already executable.")

For more information about symbolic notation syntax, see the [chmod(1) manual](https://man.freebsd.org/cgi/man.cgi?chmod).

Examples using octal notation:

```dockerfile
COPY --chmod=755 app.sh /app/
COPY --chmod=644 file.txt /data/
ARG MODE=440
COPY --chmod=$MODE . .
```

Examples using symbolic notation:

```dockerfile
COPY --chmod=+x script.sh /app/
COPY --chmod=u=rwX,go=rX . /app/
COPY --chmod=g=u config/ /config/
```

The `--chmod` flag is not supported when building Windows containers.

### [COPY --chown](#copy---chown)

```dockerfile
COPY [--chown=<user>:<group>] <src> ... <dest>
```

Sets ownership of copied files. Without this flag, files are created with UID and GID of 0.

The flag accepts usernames, group names, UIDs, or GIDs in any combination. If you specify only a user, the GID is set to the same numeric value as the UID.

```dockerfile
COPY --chown=55:mygroup files* /somedir/
COPY --chown=bin files* /somedir/
COPY --chown=1 files* /somedir/
COPY --chown=10:11 files* /somedir/
COPY --chown=myuser:mygroup --chmod=644 files* /somedir/
```

When using names instead of numeric IDs, BuildKit resolves them using `/etc/passwd` and `/etc/group` in the container's root filesystem. If these files are missing or don't contain the specified names, the build fails. Numeric IDs don't require this lookup.

The `--chown` flag is not supported when building Windows containers.

### [COPY --link](#copy---link)

```dockerfile
COPY [--link[=<boolean>]] <src> ... <dest>
```

Enabling this flag in `COPY` or `ADD` commands allows you to copy files with enhanced semantics where your files remain independent on their own layer and don't get invalidated when commands on previous layers are changed.

When `--link` is used your source files are copied into an empty destination directory. That directory is turned into a layer that is linked on top of your previous state.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
COPY --link /foo /bar
```

Is equivalent of doing two builds:

```dockerfile
FROM alpine
```

and

```dockerfile
FROM scratch
COPY /foo /bar
```

and merging all the layers of both images together.

#### [Benefits of using `--link`](#benefits-of-using---link)

Use `--link` to reuse already built layers in subsequent builds with `--cache-from` even if the previous layers have changed. This is especially important for multi-stage builds where a `COPY --from` statement would previously get invalidated if any previous commands in the same stage changed, causing the need to rebuild the intermediate stages again. With `--link` the layer the previous build generated is reused and merged on top of the new layers. This also means you can easily rebase your images when the base images receive updates, without having to execute the whole build again. In backends that support it, BuildKit can do this rebase action without the need to push or pull any layers between the client and the registry. BuildKit will detect this case and only create new image manifest that contains the new layers and old layers in correct order.

The same behavior where BuildKit can avoid pulling down the base image can also happen when using `--link` and no other commands that would require access to the files in the base image. In that case BuildKit will only build the layers for the `COPY` commands and push them to the registry directly on top of the layers of the base image.

#### [Incompatibilities with `--link=false`](#incompatibilities-with---linkfalse)

When using `--link` the `COPY/ADD` commands are not allowed to read any files from the previous state. This means that if in previous state the destination directory was a path that contained a symlink, `COPY/ADD` can not follow it. In the final image the destination path created with `--link` will always be a path containing only directories.

If you don't rely on the behavior of following symlinks in the destination path, using `--link` is always recommended. The performance of `--link` is equivalent or better than the default behavior and, it creates much better conditions for cache reuse.

### [COPY --parents](#copy---parents)

```dockerfile
COPY [--parents[=<boolean>]] <src> ... <dest>
```

The `--parents` flag preserves parent directories for `src` entries. This flag defaults to `false`.

```dockerfile
# syntax=docker/dockerfile:1
FROM scratch

COPY ./x/a.txt ./y/a.txt /no_parents/
COPY --parents ./x/a.txt ./y/a.txt /parents/

# /no_parents/a.txt
# /parents/x/a.txt
# /parents/y/a.txt
```

This behavior is similar to the [Linux `cp` utility's](https://www.man7.org/linux/man-pages/man1/cp.1.html) `--parents` or [`rsync`](https://man7.org/linux/man-pages/man1/rsync.1.html) `--relative` flag.

As with Rsync, it is possible to limit which parent directories are preserved by inserting a dot and a slash (`./`) into the source path. If such point exists, only parent directories after it will be preserved. This may be especially useful copies between stages with `--from` where the source paths need to be absolute.

```dockerfile
# syntax=docker/dockerfile:1
FROM scratch

COPY --parents ./x/./y/*.txt /parents/

# Build context:
# ./x/y/a.txt
# ./x/y/b.txt
#
# Output:
# /parents/y/a.txt
# /parents/y/b.txt
```

The `**` wildcard matches any number of path components, including none, and can be used to recursively match files across directory levels:

```dockerfile
# syntax=docker/dockerfile:1
FROM scratch

COPY --parents ./src/**/*.txt /parents/

# Build context:
# ./src/a.txt
# ./src/x/b.txt
# ./src/x/y/c.txt
#
# Output:
# /parents/src/a.txt
# /parents/src/x/b.txt
# /parents/src/x/y/c.txt
```

Note that, without the `--parents` flag specified, any filename collision will fail the Linux `cp` operation with an explicit error message (`cp: will not overwrite just-created './x/a.txt' with './y/a.txt'`), where the Buildkit will silently overwrite the target file at the destination.

While it is possible to preserve the directory structure for `COPY` instructions consisting of only one `src` entry, usually it is more beneficial to keep the layer count in the resulting image as low as possible. Therefore, with the `--parents` flag, the Buildkit is capable of packing multiple `COPY` instructions together, keeping the directory structure intact.

### [COPY --exclude](#copy---exclude)

```dockerfile
COPY [--exclude=<path> ...] <src> ... <dest>
```

The `--exclude` flag lets you specify a path expression for files to be excluded.

The path expression follows the same format as `<src>`, supporting wildcards and matching using Go's [filepath.Match](https://golang.org/pkg/path/filepath#Match) rules. For example, to add all files starting with "hom", excluding files with a `.txt` extension:

```dockerfile
# syntax=docker/dockerfile:1
FROM scratch

COPY --exclude=*.txt hom* /mydir/
```

You can specify the `--exclude` option multiple times for a `COPY` instruction. Multiple `--excludes` are files matching its patterns not to be copied, even if the files paths match the pattern specified in `<src>`. To add all files starting with "hom", excluding files with either `.txt` or `.md` extensions:

```dockerfile
# syntax=docker/dockerfile:1
FROM scratch

COPY --exclude=*.txt --exclude=*.md hom* /mydir/
```

## [ENTRYPOINT](#entrypoint)

An `ENTRYPOINT` allows you to configure a container that will run as an executable.

`ENTRYPOINT` has two possible forms:

* The exec form, which is the preferred form:

  ```dockerfile
  ENTRYPOINT ["executable", "param1", "param2"]
  ```

* The shell form:

  ```dockerfile
  ENTRYPOINT command param1 param2
  ```

For more information about the different forms, see [Shell and exec form](#shell-and-exec-form).

The following command starts a container from the `nginx` with its default content, listening on port 80:

```console
$ docker run -i -t --rm -p 80:80 nginx
```

Command line arguments to `docker run <image>` will be appended after all elements in an exec form `ENTRYPOINT`, and will override all elements specified using `CMD`.

This allows arguments to be passed to the entry point, i.e., `docker run <image> -d` will pass the `-d` argument to the entry point. You can override the `ENTRYPOINT` instruction using the `docker run --entrypoint` flag.

The shell form of `ENTRYPOINT` ignores any `CMD` or `docker run` command line arguments. It also starts your `ENTRYPOINT` as a subcommand of `/bin/sh -c`, which does not pass signals. This means that the executable will not be the container's `PID 1`, and will not receive Unix signals. In this case, your executable doesn't receive a `SIGTERM` from `docker stop <container>`.

Only the last `ENTRYPOINT` instruction in the Dockerfile will have an effect.

### [Exec form ENTRYPOINT example](#exec-form-entrypoint-example)

You can use the exec form of `ENTRYPOINT` to set fairly stable default commands and arguments and then use `CMD` to set additional defaults that are more likely to be changed.

When combining exec form `ENTRYPOINT` with `CMD`, use the exec form of `CMD` as well. Using the shell form of `CMD` causes it to be wrapped in `/bin/sh -c`, which means the `ENTRYPOINT` receives a shell invocation as its argument rather than the bare command and parameters. See [Understand how CMD and ENTRYPOINT interact](#understand-how-cmd-and-entrypoint-interact).

```dockerfile
FROM ubuntu
ENTRYPOINT ["top", "-b"]
CMD ["-c"]
```

When you run the container, you can see that `top` is the only process:

```console
$ docker run -it --rm --name test  top -H

top - 08:25:00 up  7:27,  0 users,  load average: 0.00, 0.01, 0.05
Threads:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
%Cpu(s):  0.1 us,  0.1 sy,  0.0 ni, 99.7 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
KiB Mem:   2056668 total,  1616832 used,   439836 free,    99352 buffers
KiB Swap:  1441840 total,        0 used,  1441840 free.  1324440 cached Mem

  PID USER      PR  NI    VIRT    RES    SHR S %CPU %MEM     TIME+ COMMAND
    1 root      20   0   19744   2336   2080 R  0.0  0.1   0:00.04 top
```

To examine the result further, you can use `docker exec`:

```console
$ docker exec -it test ps aux

USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  2.6  0.1  19752  2352 ?        Ss+  08:24   0:00 top -b -H
root         7  0.0  0.1  15572  2164 ?        R+   08:25   0:00 ps aux
```

And you can gracefully request `top` to shut down using `docker stop test`.

The following Dockerfile shows using the `ENTRYPOINT` to run Apache in the foreground (i.e., as `PID 1`):

```dockerfile
FROM debian:stable
RUN apt-get update && apt-get install -y --force-yes apache2
EXPOSE 80 443
VOLUME ["/var/www", "/var/log/apache2", "/etc/apache2"]
ENTRYPOINT ["/usr/sbin/apache2ctl", "-D", "FOREGROUND"]
```

If you need to write a starter script for a single executable, you can ensure that the final executable receives the Unix signals by using `exec` and `gosu` commands:

```bash
#!/usr/bin/env bash
set -e

if [ "$1" = 'postgres' ]; then
    chown -R postgres "$PGDATA"

    if [ -z "$(ls -A "$PGDATA")" ]; then
        gosu postgres initdb
    fi

    exec gosu postgres "$@"
fi

exec "$@"
```

Lastly, if you need to do some extra cleanup (or communicate with other containers) on shutdown, or are co-ordinating more than one executable, you may need to ensure that the `ENTRYPOINT` script receives the Unix signals, passes them on, and then does some more work:

```bash
#!/bin/sh
# Note: I've written this using sh so it works in the busybox container too

# USE the trap if you need to also do manual cleanup after the service is stopped,
#     or need to start multiple services in the one container
trap "echo TRAPed signal" HUP INT QUIT TERM

# start service in background here
/usr/sbin/apachectl start

echo "[hit enter key to exit] or run 'docker stop <container>'"
read

# stop service and clean up here
echo "stopping apache"
/usr/sbin/apachectl stop

echo "exited $0"
```

If you run this image with `docker run -it --rm -p 80:80 --name test apache`, you can then examine the container's processes with `docker exec`, or `docker top`, and then ask the script to stop Apache:

```console
$ docker exec -it test ps aux

USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.1  0.0   4448   692 ?        Ss+  00:42   0:00 /bin/sh /run.sh 123 cmd cmd2
root        19  0.0  0.2  71304  4440 ?        Ss   00:42   0:00 /usr/sbin/apache2 -k start
www-data    20  0.2  0.2 360468  6004 ?        Sl   00:42   0:00 /usr/sbin/apache2 -k start
www-data    21  0.2  0.2 360468  6000 ?        Sl   00:42   0:00 /usr/sbin/apache2 -k start
root        81  0.0  0.1  15572  2140 ?        R+   00:44   0:00 ps aux

$ docker top test

PID                 USER                COMMAND
10035               root                {run.sh} /bin/sh /run.sh 123 cmd cmd2
10054               root                /usr/sbin/apache2 -k start
10055               33                  /usr/sbin/apache2 -k start
10056               33                  /usr/sbin/apache2 -k start

$ /usr/bin/time docker stop test

test
real	0m 0.27s
user	0m 0.03s
sys	0m 0.03s
```

> Note
>
> You can override the `ENTRYPOINT` setting using `--entrypoint`, but this can only set the binary to exec (no `sh -c` will be used).

### [Shell form ENTRYPOINT example](#shell-form-entrypoint-example)

You can specify a plain string for the `ENTRYPOINT` and it will execute in `/bin/sh -c`. This form will use shell processing to substitute shell environment variables, and will ignore any `CMD` or `docker run` command line arguments. To ensure that `docker stop` will signal any long running `ENTRYPOINT` executable correctly, you need to remember to start it with `exec`:

```dockerfile
FROM ubuntu
ENTRYPOINT exec top -b
```

When you run this image, you'll see the single `PID 1` process:

```console
$ docker run -it --rm --name test top

Mem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cached
CPU:   5% usr   0% sys   0% nic  94% idle   0% io   0% irq   0% sirq
Load average: 0.08 0.03 0.05 2/98 6
  PID  PPID USER     STAT   VSZ %VSZ %CPU COMMAND
    1     0 root     R     3164   0%   0% top -b
```

Which exits cleanly on `docker stop`:

```console
$ /usr/bin/time docker stop test

test
real	0m 0.20s
user	0m 0.02s
sys	0m 0.04s
```

If you forget to add `exec` to the beginning of your `ENTRYPOINT`:

```dockerfile
FROM ubuntu
ENTRYPOINT top -b
CMD -- --ignored-param1
```

You can then run it (giving it a name for the next step):

```console
$ docker run -it --name test top --ignored-param2

top - 13:58:24 up 17 min,  0 users,  load average: 0.00, 0.00, 0.00
Tasks:   2 total,   1 running,   1 sleeping,   0 stopped,   0 zombie
%Cpu(s): 16.7 us, 33.3 sy,  0.0 ni, 50.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
MiB Mem :   1990.8 total,   1354.6 free,    231.4 used,    404.7 buff/cache
MiB Swap:   1024.0 total,   1024.0 free,      0.0 used.   1639.8 avail Mem

  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
    1 root      20   0    2612    604    536 S   0.0   0.0   0:00.02 sh
    6 root      20   0    5956   3188   2768 R   0.0   0.2   0:00.00 top
```

You can see from the output of `top` that the specified `ENTRYPOINT` is not `PID 1`.

If you then run `docker stop test`, the container will not exit cleanly - the `stop` command will be forced to send a `SIGKILL` after the timeout:

```console
$ docker exec -it test ps waux

USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         1  0.4  0.0   2612   604 pts/0    Ss+  13:58   0:00 /bin/sh -c top -b --ignored-param2
root         6  0.0  0.1   5956  3188 pts/0    S+   13:58   0:00 top -b
root         7  0.0  0.1   5884  2816 pts/1    Rs+  13:58   0:00 ps waux

$ /usr/bin/time docker stop test

test
real	0m 10.19s
user	0m 0.04s
sys	0m 0.03s
```

### [Understand how CMD and ENTRYPOINT interact](#understand-how-cmd-and-entrypoint-interact)

Both `CMD` and `ENTRYPOINT` instructions define what command gets executed when running a container. There are few rules that describe their co-operation.

1. Dockerfile should specify at least one of `CMD` or `ENTRYPOINT` commands.

2. `ENTRYPOINT` should be defined when using the container as an executable.

3. `CMD` should be used as a way of defining default arguments for an `ENTRYPOINT` command or for executing an ad-hoc command in a container.

4. `CMD` will be overridden when running the container with alternative arguments.

The table below shows what command is executed for different `ENTRYPOINT` / `CMD` combinations:

|                                   | No ENTRYPOINT                | ENTRYPOINT exec\_entry p1\_entry | ENTRYPOINT \["exec\_entry", "p1\_entry"]           |
| --------------------------------- | ---------------------------- | -------------------------------- | -------------------------------------------------- |
| **No CMD**                        | error, not allowed           | /bin/sh -c exec\_entry p1\_entry | exec\_entry p1\_entry                              |
| **CMD \["exec\_cmd", "p1\_cmd"]** | exec\_cmd p1\_cmd            | /bin/sh -c exec\_entry p1\_entry | exec\_entry p1\_entry exec\_cmd p1\_cmd            |
| **CMD exec\_cmd p1\_cmd**         | /bin/sh -c exec\_cmd p1\_cmd | /bin/sh -c exec\_entry p1\_entry | exec\_entry p1\_entry /bin/sh -c exec\_cmd p1\_cmd |

> Note
>
> If `CMD` is defined from the base image, setting `ENTRYPOINT` will reset `CMD` to an empty value. In this scenario, `CMD` must be defined in the current image to have a value.

## [VOLUME](#volume)

```dockerfile
VOLUME ["/data"]
```

The `VOLUME` instruction creates a mount point with the specified name and marks it as holding externally mounted volumes from native host or other containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log /var/db`. For more information/examples and mounting instructions via the Docker client, refer to [*Share Directories via Volumes*](https://docs.docker.com/storage/volumes/) documentation.

The `docker run` command initializes the newly created volume with any data that exists at the specified location within the base image. For example, consider the following Dockerfile snippet:

```dockerfile
FROM ubuntu
RUN mkdir /myvol
RUN echo "hello world" > /myvol/greeting
VOLUME /myvol
```

This Dockerfile results in an image that causes `docker run` to create a new mount point at `/myvol` and copy the `greeting` file into the newly created volume.

### [Notes about specifying volumes](#notes-about-specifying-volumes)

Keep the following things in mind about volumes in the Dockerfile.

* **Volumes on Windows-based containers**: When using Windows-based containers, the destination of a volume inside the container must be one of:

  * a non-existing or empty directory
  * a drive other than `C:`

* **Changing the volume from within the Dockerfile**: If any build steps change the data within the volume after it has been declared, those changes will be discarded when using the legacy builder. When using Buildkit, the changes will instead be kept.

* **JSON formatting**: The list is parsed as a JSON array. You must enclose words with double quotes (`"`) rather than single quotes (`'`).

* **The host directory is declared at container run-time**: The host directory (the mountpoint) is, by its nature, host-dependent. This is to preserve image portability, since a given host directory can't be guaranteed to be available on all hosts. For this reason, you can't mount a host directory from within the Dockerfile. The `VOLUME` instruction does not support specifying a `host-dir` parameter. You must specify the mountpoint when you create or run the container.

## [USER](#user)

```dockerfile
USER <user>[:<group>]
```

or

```dockerfile
USER UID[:<GID>]
```

The `USER` instruction sets the user name (or UID) and optionally the user group (or GID) to use as the default user and group for the remainder of the current stage. The specified user is used for `RUN` instructions and at runtime runs the relevant `ENTRYPOINT` and `CMD` commands.

> Note that when specifying a group for the user, the user will have *only* the specified group membership. Any other configured group memberships will be ignored.

> Warning
>
> When the user doesn't have a primary group then the image (or the next instructions) will be run with the `root` group.
>
> On Windows, the user must be created first if it's not a built-in account. This can be done with the `net user` command called as part of a Dockerfile.

```dockerfile
FROM microsoft/windowsservercore
# Create Windows user in the container
RUN net user /add patrick
# Set it for subsequent commands
USER patrick
```

## [WORKDIR](#workdir)

```dockerfile
WORKDIR /path/to/workdir
```

The `WORKDIR` instruction sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY` and `ADD` instructions that follow it in the Dockerfile. If the `WORKDIR` doesn't exist, it will be created even if it's not used in any subsequent Dockerfile instruction.

The `WORKDIR` instruction can be used multiple times in a Dockerfile. If a relative path is provided, it will be relative to the path of the previous `WORKDIR` instruction. For example:

```dockerfile
WORKDIR /a
WORKDIR b
WORKDIR c
RUN pwd
```

The output of the final `pwd` command in this Dockerfile would be `/a/b/c`.

The `WORKDIR` instruction can resolve environment variables previously set using `ENV`. You can only use environment variables explicitly set in the Dockerfile. For example:

```dockerfile
ENV DIRPATH=/path
WORKDIR $DIRPATH/$DIRNAME
RUN pwd
```

The output of the final `pwd` command in this Dockerfile would be `/path/$DIRNAME`

If not specified, the default working directory is `/`. In practice, if you aren't building a Dockerfile from scratch (`FROM scratch`), the `WORKDIR` may likely be set by the base image you're using.

Therefore, to avoid unintended operations in unknown directories, it's best practice to set your `WORKDIR` explicitly.

## [ARG](#arg)

```dockerfile
ARG <name>[=<default value>] [<name>[=<default value>]...]
```

The `ARG` instruction defines a variable that users can pass at build time to the builder with the `docker build` command using the `--build-arg <varname>=<value>` flag. This variable can be used in subsequent instructions such as `FROM`, `ENV`, `WORKDIR`, and others using the `${VAR}` or `$VAR` template syntax. It is also passed to all subsequent `RUN` instructions as a build-time environment variable.

Unlike `ENV`, an `ARG` variable is not embedded in the image and is not available in the final container.

> Warning
>
> It isn't recommended to use build arguments for passing secrets such as user credentials, API tokens, etc. Build arguments are visible in the `docker history` command and in `max` mode provenance attestations, which are attached to the image by default if you use the Buildx GitHub Actions and your GitHub repository is public.
>
> Refer to the [`RUN --mount=type=secret`](#run---mounttypesecret) section to learn about secure ways to use secrets when building images.

A Dockerfile may include one or more `ARG` instructions. For example, the following is a valid Dockerfile:

```dockerfile
FROM busybox
ARG user1
ARG buildno
# ...
```

### [Default values](#default-values)

An `ARG` instruction can optionally include a default value:

```dockerfile
FROM busybox
ARG user1=someuser
ARG buildno=1
# ...
```

If an `ARG` instruction has a default value and if there is no value passed at build-time, the builder uses the default.

### [Scope](#scope)

An `ARG` variable comes into effect from the line on which it is declared in the Dockerfile. For example, consider this Dockerfile:

```dockerfile
FROM busybox
USER ${username:-some_user}
ARG username
USER $username
# ...
```

A user builds this file by calling:

```console
$ docker build --build-arg username=what_user .
```

* The `USER` instruction on line 2 evaluates to the `some_user` fallback, because the `username` variable is not yet declared.
* The `username` variable is declared on line 3, and available for reference in Dockerfile instruction from that point onwards.
* The `USER` instruction on line 4 evaluates to `what_user`, since at that point the `username` argument has a value of `what_user` which was passed on the command line. Prior to its definition by an `ARG` instruction, any use of a variable results in an empty string.

An `ARG` variable declared within a build stage is automatically inherited by other stages based on that stage. Unrelated build stages do not have access to the variable. To use an argument in multiple distinct stages, each stage must include the `ARG` instruction, or they must both be based on a shared base stage in the same Dockerfile where the variable is declared.

For more information, refer to [variable scoping](https://docs.docker.com/build/building/variables/#scoping).

### [Using ARG variables](#using-arg-variables)

You can use an `ARG` or an `ENV` instruction to specify variables that are available to the `RUN` instruction. Environment variables defined using the `ENV` instruction always override an `ARG` instruction of the same name. Consider this Dockerfile with an `ENV` and `ARG` instruction.

```dockerfile
FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=v1.0.0
RUN echo $CONT_IMG_VER
```

Then, assume this image is built with this command:

```console
$ docker build --build-arg CONT_IMG_VER=v2.0.1 .
```

In this case, the `RUN` instruction uses `v1.0.0` instead of the `ARG` setting passed by the user:`v2.0.1` This behavior is similar to a shell script where a locally scoped variable overrides the variables passed as arguments or inherited from environment, from its point of definition.

Using the example above but a different `ENV` specification you can create more useful interactions between `ARG` and `ENV` instructions:

```dockerfile
FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}
RUN echo $CONT_IMG_VER
```

Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. Consider a docker build without the `--build-arg` flag:

```console
$ docker build .
```

Using this Dockerfile example, `CONT_IMG_VER` is still persisted in the image but its value would be `v1.0.0` as it is the default set in line 3 by the `ENV` instruction.

The variable expansion technique in this example allows you to pass arguments from the command line and persist them in the final image by leveraging the `ENV` instruction. Variable expansion is only supported for [a limited set of Dockerfile instructions.](#environment-replacement)

### [Predefined ARGs](#predefined-args)

Docker has a set of predefined `ARG` variables that you can use without a corresponding `ARG` instruction in the Dockerfile.

* `HTTP_PROXY`
* `http_proxy`
* `HTTPS_PROXY`
* `https_proxy`
* `FTP_PROXY`
* `ftp_proxy`
* `NO_PROXY`
* `no_proxy`
* `ALL_PROXY`
* `all_proxy`

To use these, pass them on the command line using the `--build-arg` flag, for example:

```console
$ docker build --build-arg HTTPS_PROXY=https://my-proxy.example.com .
```

By default, these pre-defined variables are excluded from the output of `docker history`. Excluding them reduces the risk of accidentally leaking sensitive authentication information in an `HTTP_PROXY` variable.

For example, consider building the following Dockerfile using `--build-arg HTTP_PROXY=http://user:pass@proxy.lon.example.com`

```dockerfile
FROM ubuntu
RUN echo "Hello World"
```

In this case, the value of the `HTTP_PROXY` variable is not available in the `docker history` and is not cached. If you were to change location, and your proxy server changed to `http://user:pass@proxy.sfo.example.com`, a subsequent build does not result in a cache miss.

If you need to override this behaviour then you may do so by adding an `ARG` statement in the Dockerfile as follows:

```dockerfile
FROM ubuntu
ARG HTTP_PROXY
RUN echo "Hello World"
```

When building this Dockerfile, the `HTTP_PROXY` is preserved in the `docker history`, and changing its value invalidates the build cache.

### [Automatic platform ARGs in the global scope](#automatic-platform-args-in-the-global-scope)

This feature is only available when using the [BuildKit](https://docs.docker.com/build/buildkit/) backend.

BuildKit supports a predefined set of `ARG` variables with information on the platform of the node performing the build (build platform) and on the platform of the resulting image (target platform). The target platform can be specified with the `--platform` flag on `docker build`.

The following `ARG` variables are set automatically:

* `TARGETPLATFORM` - platform of the build result. Eg `linux/amd64`, `linux/arm/v7`, `windows/amd64`.
* `TARGETOS` - OS component of TARGETPLATFORM
* `TARGETARCH` - architecture component of TARGETPLATFORM
* `TARGETVARIANT` - variant component of TARGETPLATFORM
* `BUILDPLATFORM` - platform of the node performing the build.
* `BUILDOS` - OS component of BUILDPLATFORM
* `BUILDARCH` - architecture component of BUILDPLATFORM
* `BUILDVARIANT` - variant component of BUILDPLATFORM

These arguments are defined in the global scope so are not automatically available inside build stages or for your `RUN` commands. To expose one of these arguments inside the build stage redefine it without value.

For example:

```dockerfile
FROM alpine
ARG TARGETPLATFORM
RUN echo "I'm building for $TARGETPLATFORM"
```

### [BuildKit built-in build args](#buildkit-built-in-build-args)

| Arg                               | Type   | Description                                                                                                                                                                                                      |
| --------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BUILDKIT_BUILD_NAME`             | String | Override the build name shown in [`buildx history` command](https://docs.docker.com/reference/cli/docker/buildx/history/) and [Docker Desktop Builds view](https://docs.docker.com/desktop/use-desktop/builds/). |
| `BUILDKIT_CACHE_MOUNT_NS`         | String | Set optional cache ID namespace.                                                                                                                                                                                 |
| `BUILDKIT_CONTEXT_KEEP_GIT_DIR`   | Bool   | Trigger Git context to keep the `.git` directory.                                                                                                                                                                |
| `BUILDKIT_INLINE_CACHE`[2](#fn:2) | Bool   | Inline cache metadata to image config or not.                                                                                                                                                                    |
| `BUILDKIT_MULTI_PLATFORM`         | Bool   | Opt into deterministic output regardless of multi-platform output or not.                                                                                                                                        |
| `BUILDKIT_SANDBOX_HOSTNAME`       | String | Set the hostname (default `buildkitsandbox`)                                                                                                                                                                     |
| `BUILDKIT_SYNTAX`                 | String | Set frontend image. Set to `dockerfile.v0` to ignore the Dockerfile `# syntax=` directive and use the built-in frontend instead.                                                                                 |
| `SOURCE_DATE_EPOCH`               | Int    | Set the Unix timestamp for created image and layers. More info from [reproducible builds](https://reproducible-builds.org/docs/source-date-epoch/). Supported since Dockerfile 1.5, BuildKit 0.11                |

#### [Example: keep `.git` dir](#example-keep-git-dir)

When using a Git context, `.git` dir is not kept on checkouts. It can be useful to keep it around if you want to retrieve git information during your build:

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
WORKDIR /src
RUN --mount=target=. \
  make REVISION=$(git rev-parse HEAD) build
```

```console
$ docker build --build-arg BUILDKIT_CONTEXT_KEEP_GIT_DIR=1 https://github.com/user/repo.git#main
```

### [Impact on build caching](#impact-on-build-caching)

`ARG` variables are not persisted into the built image as `ENV` variables are. However, `ARG` variables do impact the build cache in similar ways. If a Dockerfile defines an `ARG` variable whose value is different from a previous build, then a "cache miss" occurs upon its first usage, not its definition. In particular, all `RUN` instructions following an `ARG` instruction use the `ARG` variable implicitly (as an environment variable), thus can cause a cache miss. All predefined `ARG` variables are exempt from caching unless there is a matching `ARG` statement in the Dockerfile.

For example, consider these two Dockerfile:

```dockerfile
FROM ubuntu
ARG CONT_IMG_VER
RUN echo $CONT_IMG_VER
```

```dockerfile
FROM ubuntu
ARG CONT_IMG_VER
RUN echo hello
```

If you specify `--build-arg CONT_IMG_VER=<value>` on the command line, in both cases, the specification on line 2 doesn't cause a cache miss; line 3 does cause a cache miss. `ARG CONT_IMG_VER` causes the `RUN` line to be identified as the same as running `CONT_IMG_VER=<value> echo hello`, so if the `<value>` changes, you get a cache miss.

Consider another example under the same command line:

```dockerfile
FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=$CONT_IMG_VER
RUN echo $CONT_IMG_VER
```

In this example, the cache miss occurs on line 3. The miss happens because the variable's value in the `ENV` references the `ARG` variable and that variable is changed through the command line. In this example, the `ENV` command causes the image to include the value.

If an `ENV` instruction overrides an `ARG` instruction of the same name, like this Dockerfile:

```dockerfile
FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=hello
RUN echo $CONT_IMG_VER
```

Line 3 doesn't cause a cache miss because the value of `CONT_IMG_VER` is a constant (`hello`). As a result, the environment variables and values used on the `RUN` (line 4) doesn't change between builds.

## [ONBUILD](#onbuild)

```dockerfile
ONBUILD INSTRUCTION
```

The `ONBUILD` instruction adds to the image a trigger instruction to be executed at a later time, when the image is used as the base for another build. The trigger will be executed in the context of the downstream build, as if it had been inserted immediately after the `FROM` instruction in the downstream Dockerfile.

This is useful if you are building an image which will be used as a base to build other images, for example an application build environment or a daemon which may be customized with user-specific configuration.

For example, if your image is a reusable Python application builder, it will require application source code to be added in a particular directory, and it might require a build script to be called after that. You can't just call `ADD` and `RUN` now, because you don't yet have access to the application source code, and it will be different for each application build. You could simply provide application developers with a boilerplate Dockerfile to copy-paste into their application, but that's inefficient, error-prone and difficult to update because it mixes with application-specific code.

The solution is to use `ONBUILD` to register advance instructions to run later, during the next build stage.

Here's how it works:

1. When it encounters an `ONBUILD` instruction, the builder adds a trigger to the metadata of the image being built. The instruction doesn't otherwise affect the current build.
2. At the end of the build, a list of all triggers is stored in the image manifest, under the key `OnBuild`. They can be inspected with the `docker inspect` command.
3. Later the image may be used as a base for a new build, using the `FROM` instruction. As part of processing the `FROM` instruction, the downstream builder looks for `ONBUILD` triggers, and executes them in the same order they were registered. If any of the triggers fail, the `FROM` instruction is aborted which in turn causes the build to fail. If all triggers succeed, the `FROM` instruction completes and the build continues as usual.
4. Triggers are cleared from the final image after being executed. In other words they aren't inherited by "grand-children" builds.

For example you might add something like this:

```dockerfile
ONBUILD ADD . /app/src
ONBUILD RUN /usr/local/bin/python-build --dir /app/src
```

### [Copy or mount from stage, image, or context](#copy-or-mount-from-stage-image-or-context)

As of Dockerfile syntax 1.11, you can use `ONBUILD` with instructions that copy or mount files from other stages, images, or build contexts. For example:

```dockerfile
# syntax=docker/dockerfile:1.11
FROM alpine AS baseimage
ONBUILD COPY --from=build /usr/bin/app /app
ONBUILD RUN --mount=from=config,target=/opt/appconfig ...
```

If the source of `from` is a build stage, the stage must be defined in the Dockerfile where `ONBUILD` gets triggered. If it's a named context, that context must be passed to the downstream build.

### [ONBUILD limitations](#onbuild-limitations)

* Chaining `ONBUILD` instructions using `ONBUILD ONBUILD` isn't allowed.
* The `ONBUILD` instruction may not trigger `FROM` or `MAINTAINER` instructions.

## [STOPSIGNAL](#stopsignal)

```dockerfile
STOPSIGNAL signal
```

The `STOPSIGNAL` instruction sets the system call signal that will be sent to the container to exit. This signal can be a signal name in the format `SIG<NAME>`, for instance `SIGKILL`, or an unsigned number that matches a position in the kernel's syscall table, for instance `9`. The default is `SIGTERM` if not defined.

`STOPSIGNAL` applies to the signal sent by `docker stop` (and by the Docker daemon when stopping a container). It does not affect signals sent by keyboard shortcuts such as Ctrl+C, which sends `SIGINT` directly to the process regardless of the `STOPSIGNAL` setting.

The image's default stopsignal can be overridden per container, using the `--stop-signal` flag on `docker run` and `docker create`.

## [HEALTHCHECK](#healthcheck)

The `HEALTHCHECK` instruction has two forms:

* `HEALTHCHECK [OPTIONS] CMD command` (check container health by running a command inside the container)
* `HEALTHCHECK NONE` (disable any healthcheck inherited from the base image)

The `HEALTHCHECK` instruction tells Docker how to test a container to check that it's still working. This can detect cases such as a web server stuck in an infinite loop and unable to handle new connections, even though the server process is still running.

When a container has a healthcheck specified, it has a health status in addition to its normal status. This status is initially `starting`. Whenever a health check passes, it becomes `healthy` (whatever state it was previously in). After a certain number of consecutive failures, it becomes `unhealthy`.

The options that can appear before `CMD` are:

* `--interval=DURATION` (default: `30s`)
* `--timeout=DURATION` (default: `30s`)
* `--start-period=DURATION` (default: `0s`)
* `--start-interval=DURATION` (default: `5s`)
* `--retries=N` (default: `3`)

The health check will first run **interval** seconds after the container is started, and then again **interval** seconds after each previous check completes. During the **start period**, health checks run at **start interval** frequency instead.

If a single run of the check takes longer than **timeout** seconds then the check is considered to have failed. The process performing the check is abruptly stopped with a `SIGKILL`.

It takes **retries** consecutive failures of the health check for the container to be considered `unhealthy`.

**start period** provides initialization time for containers that need time to bootstrap. Probe failure during that period will not be counted towards the maximum number of retries. However, if a health check succeeds during the start period, the container is considered started and all consecutive failures will be counted towards the maximum number of retries.

**start interval** is the time between health checks during the start period. This option requires Docker Engine version 25.0 or later.

There can only be one `HEALTHCHECK` instruction in a Dockerfile. If you list more than one then only the last `HEALTHCHECK` will take effect.

The command after the `CMD` keyword can be either a shell command (e.g. `HEALTHCHECK CMD /bin/check-running`) or an exec array (as with other Dockerfile commands; see e.g. `ENTRYPOINT` for details).

The command's exit status indicates the health status of the container. The possible values are:

* 0: success - the container is healthy and ready for use
* 1: unhealthy - the container isn't working correctly
* 2: reserved - don't use this exit code

For example, to check every five minutes or so that a web-server is able to serve the site's main page within three seconds:

```dockerfile
HEALTHCHECK --interval=5m --timeout=3s \
  CMD curl -f http://localhost/ || exit 1
```

To help debug failing probes, any output text (UTF-8 encoded) that the command writes on stdout or stderr will be stored in the health status and can be queried with `docker inspect`. Such output should be kept short (only the first 4096 bytes are stored currently).

When the health status of a container changes, a `health_status` event is generated with the new status.

## [SHELL](#shell)

```dockerfile
SHELL ["executable", "parameters"]
```

The `SHELL` instruction allows the default shell used for the shell form of commands to be overridden. The default shell on Linux is `["/bin/sh", "-c"]`, and on Windows is `["cmd", "/S", "/C"]`. The `SHELL` instruction must be written in JSON form in a Dockerfile.

The `SHELL` instruction is particularly useful on Windows where there are two commonly used and quite different native shells: `cmd` and `powershell`, as well as alternate shells available including `sh`.

The `SHELL` instruction can appear multiple times. Each `SHELL` instruction overrides all previous `SHELL` instructions, and affects all subsequent instructions. For example:

```dockerfile
FROM microsoft/windowsservercore

# Executed as cmd /S /C echo default
RUN echo default

# Executed as cmd /S /C powershell -command Write-Host default
RUN powershell -command Write-Host default

# Executed as powershell -command Write-Host hello
SHELL ["powershell", "-command"]
RUN Write-Host hello

# Executed as cmd /S /C echo hello
SHELL ["cmd", "/S", "/C"]
RUN echo hello
```

The following instructions can be affected by the `SHELL` instruction when the shell form of them is used in a Dockerfile: `RUN`, `CMD` and `ENTRYPOINT`.

The following example is a common pattern found on Windows which can be streamlined by using the `SHELL` instruction:

```dockerfile
RUN powershell -command Execute-MyCmdlet -param1 "c:\foo.txt"
```

The command invoked by the builder will be:

```powershell
cmd /S /C powershell -command Execute-MyCmdlet -param1 "c:\foo.txt"
```

This is inefficient for two reasons. First, there is an unnecessary `cmd.exe` command processor (aka shell) being invoked. Second, each `RUN` instruction in the shell form requires an extra `powershell -command` prefixing the command.

To make this more efficient, one of two mechanisms can be employed. One is to use the JSON form of the `RUN` command such as:

```dockerfile
RUN ["powershell", "-command", "Execute-MyCmdlet", "-param1 \"c:\\foo.txt\""]
```

While the JSON form is unambiguous and does not use the unnecessary `cmd.exe`, it does require more verbosity through double-quoting and escaping. The alternate mechanism is to use the `SHELL` instruction and the shell form, making a more natural syntax for Windows users, especially when combined with the `escape` parser directive:

```dockerfile
# escape=`

FROM microsoft/nanoserver
SHELL ["powershell","-command"]
RUN New-Item -ItemType Directory C:\Example
ADD Execute-MyCmdlet.ps1 c:\example\
RUN c:\example\Execute-MyCmdlet -sample 'hello world'
```

Resulting in:

```console
PS E:\myproject> docker build -t shell .

Sending build context to Docker daemon 4.096 kB
Step 1/5 : FROM microsoft/nanoserver
 ---> 22738ff49c6d
Step 2/5 : SHELL powershell -command
 ---> Running in 6fcdb6855ae2
 ---> 6331462d4300
Removing intermediate container 6fcdb6855ae2
Step 3/5 : RUN New-Item -ItemType Directory C:\Example
 ---> Running in d0eef8386e97


    Directory: C:\


Mode         LastWriteTime              Length Name
----         -------------              ------ ----
d-----       10/28/2016  11:26 AM              Example


 ---> 3f2fbf1395d9
Removing intermediate container d0eef8386e97
Step 4/5 : ADD Execute-MyCmdlet.ps1 c:\example\
 ---> a955b2621c31
Removing intermediate container b825593d39fc
Step 5/5 : RUN c:\example\Execute-MyCmdlet 'hello world'
 ---> Running in be6d8e63fe75
hello world
 ---> 8e559e9bf424
Removing intermediate container be6d8e63fe75
Successfully built 8e559e9bf424
PS E:\myproject>
```

The `SHELL` instruction could also be used to modify the way in which a shell operates. For example, using `SHELL cmd /S /C /V:ON|OFF` on Windows, delayed environment variable expansion semantics could be modified.

The `SHELL` instruction can also be used on Linux should an alternate shell be required such as `zsh`, `csh`, `tcsh` and others.

## [Here-Documents](#here-documents)

Here-documents allow redirection of subsequent Dockerfile lines to the input of `RUN` or `COPY` commands. If such command contains a [here-document](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_07_04) the Dockerfile considers the next lines until the line only containing a here-doc delimiter as part of the same command.

### [Example: Running a multi-line script](#example-running-a-multi-line-script)

```dockerfile
# syntax=docker/dockerfile:1
FROM debian
RUN <<EOT bash
  set -ex
  apt-get update
  apt-get install -y vim
EOT
```

If the command only contains a here-document, its contents is evaluated with the default shell.

```dockerfile
# syntax=docker/dockerfile:1
FROM debian
RUN <<EOT
  mkdir -p foo/bar
EOT
```

Alternatively, shebang header can be used to define an interpreter.

```dockerfile
# syntax=docker/dockerfile:1
FROM python:3.6
RUN <<EOT
#!/usr/bin/env python
print("hello world")
EOT
```

More complex examples may use multiple here-documents.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
RUN <<FILE1 cat > file1 && <<FILE2 cat > file2
I am
first
FILE1
I am
second
FILE2
```

### [Example: Creating inline files](#example-creating-inline-files)

With `COPY` instructions, you can replace the source parameter with a here-doc indicator to write the contents of the here-document directly to a file. The following example creates a `greeting.txt` file containing `hello world` using a `COPY` instruction.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
COPY <<EOF greeting.txt
hello world
EOF
```

Regular here-doc [variable expansion and tab stripping rules](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_07_04) apply. The following example shows a small Dockerfile that creates a `hello.sh` script file using a `COPY` instruction with a here-document.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
ARG FOO=bar
COPY <<-EOT /script.sh
  echo "hello ${FOO}"
EOT
ENTRYPOINT ash /script.sh
```

In this case, file script prints "hello bar", because the variable is expanded when the `COPY` instruction gets executed.

```console
$ docker build -t heredoc .
$ docker run heredoc
hello bar
```

If instead you were to quote any part of the here-document word `EOT`, the variable would not be expanded at build-time.

```dockerfile
# syntax=docker/dockerfile:1
FROM alpine
ARG FOO=bar
COPY <<-"EOT" /script.sh
  echo "hello ${FOO}"
EOT
ENTRYPOINT ash /script.sh
```

Note that `ARG FOO=bar` is excessive here, and can be removed. The variable gets interpreted at runtime, when the script is invoked:

```console
$ docker build -t heredoc .
$ docker run -e FOO=world heredoc
hello world
```

## [Dockerfile examples](#dockerfile-examples)

For examples of Dockerfiles, refer to:

* The [building best practices page](https://docs.docker.com/build/building/best-practices/)
* The ["get started" tutorials](https://docs.docker.com/get-started/)
* The [language-specific getting started guides](https://docs.docker.com/guides/language/)

***

1. Value required [↩︎](#fnref:1) [↩︎](#fnref1:1) [↩︎](#fnref2:1)

2. For Docker-integrated [BuildKit](https://docs.docker.com/build/buildkit/#getting-started) and `docker buildx build` [↩︎](#fnref:2)

----
url: https://docs.docker.com/guides/testcontainers-java-spring-boot-kafka/run-tests/
----

# Run tests and next steps

***

Table of contents

***

## [Run the tests](#run-the-tests)

```console
$ ./mvnw test
```

Or with Gradle:

```console
$ ./gradlew test
```

You should see the Kafka and MySQL Docker containers start and all tests pass. After the tests finish, the containers stop and are removed automatically.

## [Summary](#summary)

Testing with real Kafka and MySQL instances gives you more confidence in the correctness of your code than mocks or embedded alternatives. The Testcontainers library manages the container lifecycle so that your integration tests run against the same services you use in production.

To learn more about Testcontainers, visit the [Testcontainers overview](https://testcontainers.com/getting-started/).

## [Further reading](#further-reading)

* [Getting started with Testcontainers in a Java Spring Boot project](https://testcontainers.com/guides/testing-spring-boot-rest-api-using-testcontainers/)
* [The simplest way to replace H2 with a real database for testing](https://testcontainers.com/guides/replace-h2-with-real-database-for-testing/)
* [Awaitility](http://www.awaitility.org/)
* [Testcontainers Kafka module](https://java.testcontainers.org/modules/kafka/)
* [Testcontainers MySQL module](https://java.testcontainers.org/modules/databases/mysql/)

----
url: https://docs.docker.com/build/ci/github-actions/reproducible-builds/
----

# Reproducible builds with GitHub Actions

***

Table of contents

***

`SOURCE_DATE_EPOCH` is a [standardized environment variable](https://reproducible-builds.org/docs/source-date-epoch/) for instructing build tools to produce a reproducible output. Setting the environment variable for a build makes the timestamps in the image index, config, and file metadata reflect the specified Unix time.

To set the environment variable in GitHub Actions, use the built-in `env` property on the build step.

## [Unix epoch timestamps](#unix-epoch-timestamps)

The following example sets the `SOURCE_DATE_EPOCH` variable to 0, Unix epoch.

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build
        uses: docker/build-push-action@v7
        with:
          tags: user/app:latest
        env:
          SOURCE_DATE_EPOCH: 0
```

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Build
        uses: docker/bake-action@v7
        env:
          SOURCE_DATE_EPOCH: 0
```

## [Git commit timestamps](#git-commit-timestamps)

The following example sets `SOURCE_DATE_EPOCH` to the Git commit timestamp.

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Get Git commit timestamps
        run: echo "TIMESTAMP=$(git log -1 --pretty=%ct)" >> $GITHUB_ENV

      - name: Build
        uses: docker/build-push-action@v7
        with:
          tags: user/app:latest
        env:
          SOURCE_DATE_EPOCH: ${{ env.TIMESTAMP }}
```

```yaml
name: ci

on:
  push:

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Get Git commit timestamps
        run: echo "TIMESTAMP=$(git log -1 --pretty=%ct)" >> $GITHUB_ENV

      - name: Build
        uses: docker/bake-action@v7
        env:
          SOURCE_DATE_EPOCH: ${{ env.TIMESTAMP }}
```

## [Additional information](#additional-information)

For more information about the `SOURCE_DATE_EPOCH` support in BuildKit, see [BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/build-repro.md#source_date_epoch).

----
url: https://docs.docker.com/engine/install/fedora/
----

# Install Docker Engine on Fedora

***

Table of contents

***

To get started with Docker Engine on Fedora, make sure you [meet the prerequisites](#prerequisites), and then follow the [installation steps](#installation-methods).

## [Prerequisites](#prerequisites)

### [OS requirements](#os-requirements)

To install Docker Engine, you need a maintained version of one of the following Fedora versions:

* Fedora 44
* Fedora 43
* Fedora 42

### [Uninstall old versions](#uninstall-old-versions)

Before you can install Docker Engine, you need to uninstall any conflicting packages.

Your Linux distribution may provide unofficial Docker packages, which may conflict with the official packages provided by Docker. You must uninstall these packages before you install the official version of Docker Engine.

```console
$ sudo dnf remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-selinux \
                  docker-engine-selinux \
                  docker-engine
```

`dnf` might report that you have none of these packages installed.

Images, containers, volumes, and networks stored in `/var/lib/docker/` aren't automatically removed when you uninstall Docker.

## [Installation methods](#installation-methods)

You can install Docker Engine in different ways, depending on your needs:

* You can [set up Docker's repositories](#install-using-the-repository) and install from them, for ease of installation and upgrade tasks. This is the recommended approach.

* You can download the RPM package, [install it manually](#install-from-a-package), and manage upgrades completely manually. This is useful in situations such as installing Docker on air-gapped systems with no access to the internet.

* In testing and development environments, you can use automated [convenience scripts](#install-using-the-convenience-script) to install Docker.

Apache License, Version 2.0. See [LICENSE](https://github.com/moby/moby/blob/master/LICENSE) for the full license.

### [Install using the rpm repository](#install-using-the-repository)

Before you install Docker Engine for the first time on a new host machine, you need to set up the Docker repository. Afterward, you can install and update Docker from the repository.

#### [Set up the repository](#set-up-the-repository)

```console
$ sudo dnf config-manager addrepo --from-repofile https://download.docker.com/linux/fedora/docker-ce.repo
```

#### [Install Docker Engine](#install-docker-engine)

1. Install the Docker packages.

   To install the latest version, run:

   ```console
   $ sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   If prompted to accept the GPG key, verify that the fingerprint matches `060A 61C5 1B55 8A7F 742B 77AA C52F EB6B 621E 9F35`, and if so, accept it.

   This command installs Docker, but it doesn't start Docker. It also creates a `docker` group, however, it doesn't add any users to the group by default.

   To install a specific version, start by listing the available versions in the repository:

   ```console
   $ dnf list docker-ce --showduplicates | sort -r

   docker-ce.x86_64    3:29.5.2-1.fc41    docker-ce-stable
   docker-ce.x86_64    3:29.5.1-1.fc41    docker-ce-stable
   <...>
   ```

   The list returned depends on which repositories are enabled, and is specific to your version of Fedora (indicated by the `.fc40` suffix in this example).

   Install a specific version by its fully qualified package name, which is the package name (`docker-ce`) plus the version string (2nd column), separated by a hyphen (`-`). For example, `docker-ce-3:29.5.2-1.fc41`.

   Replace `<VERSION_STRING>` with the desired version and then run the following command to install:

   ```console
   $ sudo dnf install docker-ce-VERSION_STRING docker-ce-cli-VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin
   ```

   This command installs Docker, but it doesn't start Docker. It also creates a `docker` group, however, it doesn't add any users to the group by default.

2. Start Docker Engine.

   ```console
   $ sudo systemctl enable --now docker
   ```

   This configures the Docker systemd service to start automatically when you boot your system. If you don't want Docker to start automatically, use `sudo systemctl start docker` instead.

   > Note
   >
   > If the Docker service fails to start and `journalctl -u docker` shows `failed to find iptables`, point the `iptables` command to `iptables-nft` using `alternatives` and restart the service:
   >
   > ```console
   > $ sudo alternatives --set iptables /usr/bin/iptables-nft
   > $ sudo systemctl restart docker
   > ```

3. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

#### [Upgrade Docker Engine](#upgrade-docker-engine)

To upgrade Docker Engine, follow the [installation instructions](#install-using-the-repository), choosing the new version you want to install.

### [Install from a package](#install-from-a-package)

If you can't use Docker's `rpm` repository to install Docker Engine, you can download the `.rpm` file for your release and install it manually. You need to download a new file each time you want to upgrade Docker Engine.

1. Go to <https://download.docker.com/linux/fedora/> and choose your version of Fedora. Then browse to `x86_64/stable/Packages/` and download the `.rpm` file for the Docker version you want to install.

2. Install Docker Engine, changing the following path to the path where you downloaded the Docker package.

   ```console
   $ sudo dnf install /path/to/package.rpm
   ```

   Docker is installed but not started. The `docker` group is created, but no users are added to the group.

3. Start Docker Engine.

   ```console
   $ sudo systemctl enable --now docker
   ```

   This configures the Docker systemd service to start automatically when you boot your system. If you don't want Docker to start automatically, use `sudo systemctl start docker` instead.

   > Note
   >
   > If the Docker service fails to start and `journalctl -u docker` shows `failed to find iptables`, point the `iptables` command to `iptables-nft` using `alternatives` and restart the service:
   >
   > ```console
   > $ sudo alternatives --set iptables /usr/bin/iptables-nft
   > $ sudo systemctl restart docker
   > ```

4. Verify that the installation is successful by running the `hello-world` image:

   ```console
   $ sudo docker run hello-world
   ```

   This command downloads a test image and runs it in a container. When the container runs, it prints a confirmation message and exits.

You have now successfully installed and started Docker Engine.

> Tip
>
> Receiving errors when trying to run without root?
>
> The `docker` user group exists but contains no users, which is why you’re required to use `sudo` to run Docker commands. Continue to [Linux postinstall](/engine/install/linux-postinstall) to allow non-privileged users to run Docker commands and for other optional configuration steps.

> Tip
>
> Preview script steps before running. You can run the script with the `--dry-run` option to learn what steps the script will run when invoked:
>
> ```console
> $ curl -fsSL https://get.docker.com -o get-docker.sh
> $ sudo sh ./get-docker.sh --dry-run
> ```

This example downloads the script from <https://get.docker.com/> and runs it to install the latest stable release of Docker on Linux:

```console
$ curl -fsSL https://get.docker.com -o get-docker.sh
$ sudo sh get-docker.sh
Executing docker install script, commit: 7cae5f8b0decc17d6571f9f52eb840fbc13b2737
<...>
```

You have now successfully installed and started Docker Engine. The `docker` service starts automatically on Debian based distributions. On `RPM` based distributions, such as CentOS, Fedora or RHEL, you need to start it manually using the appropriate `systemctl` or `service` command. As the message indicates, non-root users can't run Docker commands by default.

> **Use Docker as a non-privileged user, or install in rootless mode?**
>
> The installation script requires `root` or `sudo` privileges to install and use Docker. If you want to grant non-root users access to Docker, refer to the [post-installation steps for Linux](/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). You can also install Docker without `root` privileges, or configured to run in rootless mode. For instructions on running Docker in rootless mode, refer to [run the Docker daemon as a non-root user (rootless mode)](/engine/security/rootless/).

#### [Install pre-releases](#install-pre-releases)

Docker also provides a convenience script at <https://test.docker.com/> to install pre-releases of Docker on Linux. This script is equal to the script at `get.docker.com`, but configures your package manager to use the test channel of the Docker package repository. The test channel includes both stable and pre-releases (beta versions, release-candidates) of Docker. Use this script to get early access to new releases, and to evaluate them in a testing environment before they're released as stable.

To install the latest version of Docker on Linux from the test channel, run:

```console
$ curl -fsSL https://test.docker.com -o test-docker.sh
$ sudo sh test-docker.sh
```

#### [Upgrade Docker after using the convenience script](#upgrade-docker-after-using-the-convenience-script)

If you installed Docker using the convenience script, you should upgrade Docker using your package manager directly. There's no advantage to re-running the convenience script. Re-running it can cause issues if it attempts to re-install repositories which already exist on the host machine.

## [Uninstall Docker Engine](#uninstall-docker-engine)

1. Uninstall the Docker Engine, CLI, containerd, and Docker Compose packages:

   ```console
   $ sudo dnf remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
   ```

2. Images, containers, volumes, or custom configuration files on your host aren't automatically removed. To delete all images, containers, and volumes:

   ```console
   $ sudo rm -rf /var/lib/docker
   $ sudo rm -rf /var/lib/containerd
   ```

You have to delete any edited configuration files manually.

## [Next steps](#next-steps)

* Continue to [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/).

----
url: https://docs.docker.com/reference/build-checks/duplicate-stage-name/
----

# DuplicateStageName

***

Table of contents

***

## [Output](#output)

```text
Duplicate stage name 'foo-base', stage names should be unique
```

## [Description](#description)

Defining multiple stages with the same name results in an error because the builder is unable to uniquely resolve the stage name reference.

## [Examples](#examples)

❌ Bad: `builder` is declared as a stage name twice.

```dockerfile
FROM debian:latest AS builder
RUN apt-get update; apt-get install -y curl

FROM golang:latest AS builder
```

✅ Good: stages have unique names.

```dockerfile
FROM debian:latest AS deb-builder
RUN apt-get update; apt-get install -y curl

FROM golang:latest AS go-builder
```

----
url: https://docs.docker.com/guides/testcontainers-java-jooq-flyway/write-tests/
----

# Write tests with Testcontainers

***

Table of contents

***

Before writing the tests, create an SQL script to seed test data at `src/test/resources/test-data.sql`:

```sql
DELETE FROM comments;
DELETE FROM posts;
DELETE FROM users;

INSERT INTO users(id, name, email) VALUES
(1, 'Siva', 'siva@gmail.com'),
(2, 'Oleg', 'oleg@gmail.com');

INSERT INTO posts(id, title, content, created_by, created_at) VALUES
(1, 'Post 1 Title', 'Post 1 content', 1, CURRENT_TIMESTAMP),
(2, 'Post 2 Title', 'Post 2 content', 2, CURRENT_TIMESTAMP);

INSERT INTO comments(id, name, content, post_id, created_at) VALUES
(1, 'Ron', 'Comment 1', 1, CURRENT_TIMESTAMP),
(2, 'James', 'Comment 2', 1, CURRENT_TIMESTAMP),
(3, 'Robert', 'Comment 3', 2, CURRENT_TIMESTAMP);
```

## [Test with the @JooqTest slice](#test-with-the-jooqtest-slice)

The `@JooqTest` annotation loads only the persistence layer components and auto-configures jOOQ's `DSLContext`. Use the Testcontainers special JDBC URL to start a Postgres container.

Create `UserRepositoryJooqTest.java`:

```java
package com.testcontainers.demo.domain;

import static org.assertj.core.api.Assertions.assertThat;

import org.jooq.DSLContext;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.jooq.JooqTest;
import org.springframework.test.context.jdbc.Sql;

@JooqTest(
  properties = {
    "spring.test.database.replace=none",
    "spring.datasource.url=jdbc:tc:postgresql:16-alpine:///db",
  }
)
@Sql("/test-data.sql")
class UserRepositoryJooqTest {

  @Autowired
  DSLContext dsl;

  UserRepository repository;

  @BeforeEach
  void setUp() {
    this.repository = new UserRepository(dsl);
  }

  @Test
  void shouldCreateUserSuccessfully() {
    User user = new User(null, "John", "john@gmail.com");

    User savedUser = repository.createUser(user);

    assertThat(savedUser.id()).isNotNull();
    assertThat(savedUser.name()).isEqualTo("John");
    assertThat(savedUser.email()).isEqualTo("john@gmail.com");
  }

  @Test
  void shouldGetUserByEmail() {
    User user = repository.getUserByEmail("siva@gmail.com").orElseThrow();

    assertThat(user.id()).isEqualTo(1L);
    assertThat(user.name()).isEqualTo("Siva");
    assertThat(user.email()).isEqualTo("siva@gmail.com");
  }
}
```

Here's what the test does:

* `@JooqTest` loads only the persistence layer and auto-configures `DSLContext`.
* The Testcontainers special JDBC URL (`jdbc:tc:postgresql:16-alpine:///db`) starts a PostgreSQL container automatically.
* Because `flyway-core` is on the classpath, Spring Boot runs the Flyway migrations from `src/main/resources/db/migration` on startup.
* `@Sql("/test-data.sql")` loads the test data before each test.
* The `UserRepository` is instantiated manually with the injected `DSLContext`.

## [Integration test with @SpringBootTest](#integration-test-with-springboottest)

For a full integration test, use `@SpringBootTest` with the Testcontainers `@ServiceConnection` support introduced in Spring Boot 3.1.

Create `UserRepositoryTest.java`:

```java
package com.testcontainers.demo.domain;

import static org.assertj.core.api.Assertions.assertThat;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.test.context.jdbc.Sql;
import org.testcontainers.postgresql.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@SpringBootTest
@Sql("/test-data.sql")
@Testcontainers
class UserRepositoryTest {

  @Container
  @ServiceConnection
  static PostgreSQLContainer postgres = new PostgreSQLContainer(
    "postgres:16-alpine"
  );

  @Autowired
  UserRepository repository;

  @Test
  void shouldCreateUserSuccessfully() {
    User user = new User(null, "John", "john@gmail.com");

    User savedUser = repository.createUser(user);

    assertThat(savedUser.id()).isNotNull();
    assertThat(savedUser.name()).isEqualTo("John");
    assertThat(savedUser.email()).isEqualTo("john@gmail.com");
  }

  @Test
  void shouldGetUserByEmail() {
    User user = repository.getUserByEmail("siva@gmail.com").orElseThrow();

    assertThat(user.id()).isEqualTo(1L);
    assertThat(user.name()).isEqualTo("Siva");
    assertThat(user.email()).isEqualTo("siva@gmail.com");
  }
}
```

Here's what the test does:

* `@SpringBootTest` loads the entire application context, so `UserRepository` is injected directly.
* `@Testcontainers` and `@Container` manage the PostgreSQL container lifecycle.
* `@ServiceConnection` auto-configures the datasource properties from the running container, replacing the need for `@DynamicPropertySource`.
* `@Sql("/test-data.sql")` initializes the test data.

## [Test PostRepository](#test-postrepository)

Test the `PostRepository` that fetches complex object graphs using the Testcontainers special JDBC URL.

Create `PostRepositoryTest.java`:

```java
package com.testcontainers.demo.domain;

import static org.assertj.core.api.Assertions.assertThat;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.jdbc.Sql;

@SpringBootTest(
  properties = {
    "spring.test.database.replace=none",
    "spring.datasource.url=jdbc:tc:postgresql:16-alpine:///db",
  }
)
@Sql("/test-data.sql")
class PostRepositoryTest {

  @Autowired
  PostRepository repository;

  @Test
  void shouldGetPostById() {
    Post post = repository.getPostById(1L).orElseThrow();

    assertThat(post.id()).isEqualTo(1L);
    assertThat(post.title()).isEqualTo("Post 1 Title");
    assertThat(post.content()).isEqualTo("Post 1 content");
    assertThat(post.createdBy().id()).isEqualTo(1L);
    assertThat(post.createdBy().name()).isEqualTo("Siva");
    assertThat(post.createdBy().email()).isEqualTo("siva@gmail.com");
    assertThat(post.comments()).hasSize(2);
  }
}
```

This test verifies that `getPostById` loads the post along with its creator and comments in a single query using jOOQ's MULTISET feature.

[Run tests and next steps »](https://docs.docker.com/guides/testcontainers-java-jooq-flyway/run-tests/)

----
url: https://docs.docker.com/reference/cli/sbx/
----

# sbx

| Description | Manage AI coding agent sandboxes. |
| ----------- | --------------------------------- |
| Usage       | `sbx`                             |

## [Description](#description)

Docker Sandboxes creates isolated sandbox environments for AI agents, powered by Docker.

Run without a command to launch interactive mode, or pass a command for CLI usage.

## [Commands](#commands)

| Command                                                                   | Description                                                |
| ------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [`sbx completion`](https://docs.docker.com/reference/cli/sbx/completion/) | Generate the autocompletion script for the specified shell |
| [`sbx cp`](https://docs.docker.com/reference/cli/sbx/cp/)                 | Copy files or directories between a sandbox and the host   |
| [`sbx create`](https://docs.docker.com/reference/cli/sbx/create/)         | Create a sandbox for an agent                              |
| [`sbx diagnose`](https://docs.docker.com/reference/cli/sbx/diagnose/)     | Diagnose common issues with your sbx installation          |
| [`sbx exec`](https://docs.docker.com/reference/cli/sbx/exec/)             | Execute a command inside a sandbox                         |
| [`sbx kit`](https://docs.docker.com/reference/cli/sbx/kit/)               | Manage kit artifacts                                       |
| [`sbx login`](https://docs.docker.com/reference/cli/sbx/login/)           | Sign in to Docker                                          |
| [`sbx logout`](https://docs.docker.com/reference/cli/sbx/logout/)         | Stop all running sandboxes and sign out of Docker          |
| [`sbx ls`](https://docs.docker.com/reference/cli/sbx/ls/)                 | List sandboxes                                             |
| [`sbx policy`](https://docs.docker.com/reference/cli/sbx/policy/)         | Manage sandbox policies                                    |
| [`sbx ports`](https://docs.docker.com/reference/cli/sbx/ports/)           | Manage sandbox port publishing                             |
| [`sbx reset`](https://docs.docker.com/reference/cli/sbx/reset/)           | Reset all sandboxes and clean up state                     |
| [`sbx rm`](https://docs.docker.com/reference/cli/sbx/rm/)                 | Remove one or more sandboxes                               |
| [`sbx run`](https://docs.docker.com/reference/cli/sbx/run/)               | Run an agent in a sandbox                                  |
| [`sbx secret`](https://docs.docker.com/reference/cli/sbx/secret/)         | Manage stored secrets                                      |
| [`sbx stop`](https://docs.docker.com/reference/cli/sbx/stop/)             | Stop one or more sandboxes without removing them           |
| [`sbx template`](https://docs.docker.com/reference/cli/sbx/template/)     | Manage sandbox templates                                   |
| [`sbx version`](https://docs.docker.com/reference/cli/sbx/version/)       | Show Docker Sandboxes version information                  |

## [Options](#options)

| Option        | Default | Description          |
| ------------- | ------- | -------------------- |
| `-D, --debug` |         | Enable debug logging |

----
url: https://docs.docker.com/guides/ros2/turtlesim-example/
----

# Run a complete example with Turtlesim

***

Table of contents

***

## [Overview](#overview)

Turtlesim is a simple simulation tool that demonstrates fundamental ROS 2 concepts such as nodes, topics, and services. In this section, you'll run a complete example with Turtlesim, control the turtle, monitor topics, and visualize the system with rqt.

***

## [Configure display forwarding](#configure-display-forwarding)

### [Linux](#linux)

Allow Docker access to your X server:

```console
$ xhost +local:docker
```

### [macOS](#macos)

On macOS, use XQuartz to provide X11 support. Install XQuartz using Homebrew:

1. Install XQuartz using Homebrew:

   ```console
   $ brew install --cask xquartz
   ```

2. Open XQuartz from Applications, then navigate to `Preferences > Security` and enable `Allow connections from network clients`. Restart your computer to ensure the changes take effect.

3. After rebooting, open a terminal and allow local connections:

   ```console
   $ defaults write org.xquartz.X11 nolisten_tcp -bool false
   $ xhost +localhost
   $ xhost + 127.0.0.1
   ```

## [Start the container](#start-the-container)

Start the container using the same Docker Compose setup from the workspace section.

For Linux:

```console
$ cd ws_linux
$ docker compose up -d
$ docker compose exec ros2 /bin/bash
```

For macOS:

```console
$ cd ws_mac
$ docker compose up -d
$ docker compose exec ros2 /bin/bash
```

## [Install and run Turtlesim](#install-and-run-turtlesim)

Inside the container, install the Turtlesim package:

1. Update the package manager:

   ```console
   $ sudo apt update
   ```

2. Install the Turtlesim package:

   ```console
   $ sudo apt install -y ros-humble-turtlesim
   ```

3. Run the Turtlesim node:

   ```console
   $ ros2 run turtlesim turtlesim_node
   ```

A window should appear on your desktop showing a turtle in a grid.

## [Control the turtle](#control-the-turtle)

1. Open a new terminal and connect to the same container, then start the keyboard teleop node:

   ```console
   $ ros2 run turtlesim turtle_teleop_key
   ```

   This node allows you to control the turtle using your keyboard. Use the arrow keys to move the turtle forward, backward, left, and right. Press `Ctrl+C` to stop the teleop node.

2. Move the turtle around the window. You should see it draw a path as it moves.

## [Monitor topics](#monitor-topics)

1. Open another terminal and connect to the same container, then list all active topics:

   ```console
   $ ros2 topic list
   ```

   You should see output similar to the following:

   ```text
   /parameter_events
   /rosout
   /turtle1/cmd_vel
   /turtle1/color_sensor
   /turtle1/pose
   ```

2. Get information about a specific topic:

   ```console
   $ ros2 topic info /turtle1/pose
   ```

   You'll see the topic type and which nodes publish and subscribe to it.

## [Visualize the system with rqt](#visualize-the-system-with-rqt)

1. Open another terminal and connect to the same container, then update the package manager:

   ```console
   $ sudo apt update
   ```

2. Install rqt:

   ```console
   $ sudo apt install -y 'ros-humble-rqt*'
   ```

3. Start rqt:

   ```console
   $ ros2 run rqt_gui rqt_gui
   ```

An rqt window should appear. rqt provides several useful plugins for visualizing and monitoring ROS 2 systems.

### [Node Graph](#node-graph)

You can explore the node graph by navigating to **Plugins > Introspection > Node Graph**. A new tab opens showing nodes and topics with connections illustrated as lines. This visualization demonstrates how the teleop node sends velocity commands to the Turtlesim node, and how the Turtlesim node publishes position data back through topics.

### [Topic Monitor](#topic-monitor)

You can monitor active topics by navigating to **Plugins > Topics > Topic Monitor**. A new tab opens displaying all active topics and their current values. Select the eye icon next to `/turtle1/pose` to monitor it. As you move the turtle, watch the pose values update in real time, showing the position of the turtle and orientation changing based on your commands.

### [Service Caller](#service-caller)

You can call services from rqt using **Plugins > Services > Service Caller**. Select a service such as `/turtle1/teleport_absolute`, enter values for the request fields, and select **Call** to send the request.

### [Plots](#plots)

To plot topic data over time navigate to **Plugins > Visualization > Plot**. For example, in the Plot window, type `/turtle1/pose/x` in the Topic field and press Enter. Move the turtle and watch the X position displayed as a graph over time.

## [Call ROS 2 services](#call-ros-2-services)

Turtlesim provides services for actions such as repositioning the turtle and clearing the path.

1. List available services:

   ```console
   $ ros2 service list
   ```

   You should see services such as `/turtle1/set_pen` (to change pen color and width), `/turtle1/teleport_absolute` (to move the turtle to a specific position), and `/turtle1/teleport_relative` (to move the turtle relative to its current position).

2. Teleport the turtle to a new position:

   ```console
   $ ros2 service call /turtle1/teleport_absolute turtlesim/srv/TeleportAbsolute "
   x: 1.0
   y: 3.0
   theta: 0.0
   "
   ```

   The turtle should instantly move to the specified position (1.0, 3.0).

## [Create a simple publisher](#create-a-simple-publisher)

1. Create a Python script that publishes velocity commands to control the turtle programmatically. In a new terminal, create a file called `move_turtle.py`:

   ```python
   import rclpy
   from geometry_msgs.msg import Twist
   import time

   def main():
       rclpy.init()
       node = rclpy.create_node('turtle_mover')
       publisher = node.create_publisher(Twist, 'turtle1/cmd_vel', 10)

       # Create a twist message
       msg = Twist()
       msg.linear.x = 2.0  # Move forward at 2 m/s
       msg.angular.z = 1.0  # Rotate at 1 rad/s

       # Publish the message
       for i in range(50):
           publisher.publish(msg)
           time.sleep(0.1)

       # Stop the turtle
       msg.linear.x = 0.0
       msg.angular.z = 0.0
       publisher.publish(msg)

       node.destroy_node()
       rclpy.shutdown()

   if __name__ == '__main__':
       main()
   ```

2. Run the script:

   ```console
   $ python3 move_turtle.py
   ```

   The turtle should move in a circular motion for 5 seconds and then stop.

## [Summary](#summary)

In this section, you configured display forwarding, used the Turtlesim nodes, inspected nodes and topics, and visualized the system using rqt. Finally, you interacted with ROS 2 services and created a simple publisher to move the turtle programmatically.

These fundamental concepts apply directly to real-world robotics applications with actual sensors and actuators.

## [Related resources](#related-resources)

* [ROS 2 Turtlesim tutorials](https://docs.ros.org/en/humble/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Topics/Understanding-ROS2-Topics.html)
* [ROS 2 Concepts](https://docs.ros.org/en/humble/Concepts.html)
* [Geometry Messages](https://github.com/ros2/geometry2/tree/humble/geometry_msgs)

----
url: https://docs.docker.com/extensions/extensions-sdk/extensions/share/
----

# Share your extension

***

Table of contents

***

Once your extension image is accessible on Docker Hub, anyone with access to the image can install the extension.

People can install your extension by typing `docker extension install my/awesome-extension:latest` in to the terminal.

However, this option doesn't provide a preview of the extension before it's installed.

## [Create a share URL](#create-a-share-url)

Docker lets you share your extensions using a URL.

When people navigate to this URL, it opens Docker Desktop and displays a preview of your extension in the same way as an extension in the Marketplace. From the preview, users can then select **Install**.

To generate this link you can either:

* Run the following command:

  ```console
  $ docker extension share my/awesome-extension:0.0.1
  ```

* Once you have installed your extension locally, navigate to the **Manage** tab and select **Share**.

> Note
>
> Previews of the extension description or screenshots, for example, are created using [extension labels](https://docs.docker.com/extensions/extensions-sdk/extensions/labels/).

----
url: https://docs.docker.com/scout/explore/image-details-view/
----

# Image details view

***

Table of contents

***

The image details view shows a breakdown of the Docker Scout analysis. You can access the image view from the Docker Scout Dashboard, the Docker Desktop **Images** view, and from the image tag page on Docker Hub. The image details show a breakdown of the image hierarchy (base images), image layers, packages, and vulnerabilities.

Docker Desktop first analyzes images locally, where it generates a software bill of materials (SBOM). Docker Desktop, Docker Hub, and the Docker Scout Dashboard and CLI all use the [package URL (PURL) links](https://github.com/package-url/purl-spec) in this SBOM to query for matching Common Vulnerabilities and Exposures (CVEs) in [Docker Scout's advisory database](https://docs.docker.com/scout/deep-dive/advisory-db-sources/).

## [Image hierarchy](#image-hierarchy)

The image you inspect may have one or more base images represented under **Image hierarchy**. This means the author of the image used other images as starting points when building the image. Often these base images are either operating system images such as Debian, Ubuntu, and Alpine, or programming language images such as PHP, Python, and Java.

Selecting each image in the chain lets you see which layers originate from each base image. Selecting the **ALL** row selects all layers and base images.

One or more of the base images may have updates available, which may include updated security patches that remove vulnerabilities from your image. Any base images with available updates are noted to the right of **Image hierarchy**.

## [Layers](#layers)

A Docker image consists of layers. Image layers are listed from top to bottom, with the earliest layer at the top and the most recent layer at the bottom. Often, the layers at the top of the list originate from a base image, and the layers towards the bottom added by the image author, often using commands in a Dockerfile. Selecting a base image under **Image hierarchy** highlights with layers originate from a base image.

Selecting individual or multiple layers filters the packages and vulnerabilities on the right-hand side to show what the selected layers added.

## [Vulnerabilities](#vulnerabilities)

The **Vulnerabilities** tab displays a list of vulnerabilities and exploits detected in the image. The list is grouped by package, and sorted in order of severity.

You can find further information on the vulnerability or exploit, including if a fix is available, by expanding the list item.

## [Remediation recommendations](#remediation-recommendations)

When you inspect an image in Docker Desktop or Docker Hub, Docker Scout can provide recommendations for improving the security of that image.

### [Recommendations in Docker Desktop](#recommendations-in-docker-desktop)

To view security recommendations for an image in Docker Desktop:

1. Go to the **Images** view in Docker Desktop.
2. Select the image tag that you want to view recommendations for.
3. Near the top, select the **Recommended fixes** drop-down button.

The drop-down menu lets you choose whether you want to see recommendations for the current image or any base images used to build it:

* [**Recommendations for this image**](#recommendations-for-current-image) provides recommendations for the current image that you're inspecting.
* [**Recommendations for base image**](#recommendations-for-base-image) provides recommendations for base images used to build the image.

If the image you're viewing has no associated base images, the drop-down menu only shows the option to view recommendations for the current image.

### [Recommendations in Docker Hub](#recommendations-in-docker-hub)

To view security recommendations for an image in Docker Hub:

1. Go to the repository page for an image where you have activated Docker Scout image analysis.

2. Open the **Tags** tab.

3. Select the tag that you want to view recommendations for.

4. Select the **View recommended base image fixes** button.

   This opens a window which gives you recommendations for you can improve the security of your image by using better base images. See [Recommendations for base image](#recommendations-for-base-image) for more details.

### [Recommendations for current image](#recommendations-for-current-image)

The recommendations for the current image view helps you determine whether the image version that you're using is out of date. If the tag you're using is referencing an old digest, the view shows a recommendation to update the tag by pulling the latest version.

Select the **Pull new image** button to get the updated version. Check the checkbox to remove the old version after pulling the latest.

### [Recommendations for base image](#recommendations-for-base-image)

The base image recommendations view contains two tabs for toggling between different types of recommendations:

* **Refresh base image**
* **Change base image**

These base image recommendations are only actionable if you're the author of the image you're inspecting. This is because changing the base image for an image requires you to update the Dockerfile and re-build the image.

#### [Refresh base image](#refresh-base-image)

This tab shows if the selected base image tag is the latest available version, or if it's outdated.

If the base image tag used to build the current image isn't the latest, then the delta between the two versions shows in this window. The delta information includes:

* The tag name, and aliases, of the recommended (newer) version
* The age of the current base image version
* The age of the latest available version
* The number of CVEs affecting each version

At the bottom of the window, you also receive command snippets that you can run to re-build the image using the latest version.

#### [Change base image](#change-base-image)

This tab shows different alternative tags that you can use, and outlines the benefits and disadvantages of each tag version. Selecting the base image shows recommended options for that tag.

For example, if the image you're inspecting is using an old version of `debian` as a base image, it shows recommendations for newer and more secure versions of `debian` to use. By providing more than one alternative to choose from, you can see for yourself how the options compare with each other, and decide which one to use.

Select a tag recommendation to see further details of the recommendation. It shows the benefits and potential disadvantages of the tag, why it's a recommended, and how to update your Dockerfile to use this version.

----
url: https://docs.docker.com/reference/cli/docker/scout/cache/
----

# docker scout cache

***

| Description | Manage Docker Scout cache and temporary files |
| ----------- | --------------------------------------------- |

## [Description](#description)

Manage Docker Scout cache and temporary files

## [Subcommands](#subcommands)

| Command                                                                                       | Description                     |
| --------------------------------------------------------------------------------------------- | ------------------------------- |
| [`docker scout cache df`](https://docs.docker.com/reference/cli/docker/scout/cache/df/)       | Show Docker Scout disk usage    |
| [`docker scout cache prune`](https://docs.docker.com/reference/cli/docker/scout/cache/prune/) | Remove temporary or cached data |

----
url: https://docs.docker.com/platform-release-notes/
----

# Release notes for Docker Home, the Admin Console, billing, security, and subscription features

***

Table of contents

***

This page provides details on new features, enhancements, known issues, and bug fixes across Docker Home, the Admin Console, billing, security, and subscription functionalities.

## [2026-02-13](#2026-02-13)

### [New](#new)

* Administrators can now control whether organization members can push content to their personal namespaces on Docker Hub with [namespace access control](https://docs.docker.com/enterprise/security/hardened-desktop/namespace-access/).
* Administrators can now prevent creating public repositories within organization namespaces using the [Disable public repositories](https://docs.docker.com/docker-hub/settings/#disable-creation-of-public-repos) setting.

## [2026-01-27](#2026-01-27)

### [New](#new-1)

* Administrators can now use an allow list with [Image Access Management](https://docs.docker.com/enterprise/security/hardened-desktop/image-access-management/) to approve specific repositories that bypass image access controls.

## [2025-01-30](#2025-01-30)

### [New](#new-2)

* Installing Docker Desktop via the PKG installer is now generally available.
* Enforcing sign-in via configuration profiles is now generally available.

## [2024-12-10](#2024-12-10)

### [New](#new-3)

* New Docker subscriptions are now available. For more information, see [Docker subscriptions and features](https://www.docker.com/pricing?ref=Docs\&refAction=DocsPlatformReleaseNotes) and [Announcing Upgraded Docker Plans: Simpler, More Value, Better Development and Productivity](https://www.docker.com/blog/november-2024-updated-plans-announcement/).

## [2024-11-18](#2024-11-18)

### [New](#new-4)

* Administrators can now:

  * Enforce sign-in with [configuration profiles](https://docs.docker.com/enterprise/security/enforce-sign-in/methods/#configuration-profiles-method-mac-only) (Early Access).
  * Enforce sign-in for more than one organization at a time (Early Access).
  * Deploy Docker Desktop for Mac in bulk with the [PKG installer](https://docs.docker.com/enterprise/enterprise-deployment/pkg-install-and-configure/) (Early Access).
  * [Use Desktop Settings Management via the Docker Admin Console](https://docs.docker.com/enterprise/security/hardened-desktop/settings-management/configure-admin-console/) (Early Access).

### [Bug fixes and enhancements](#bug-fixes-and-enhancements)

* Enhance Container Isolation (ECI) has been improved to:

  * Permit admins to [turn off Docker socket mount restrictions](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/#allowing-all-containers-to-mount-the-docker-socket).
  * Support wildcard tags when using the [`allowedDerivedImages` setting](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/config/#docker-socket-mount-permissions-for-derived-images).

## [2024-11-11](#2024-11-11)

### [New](#new-5)

* [Personal access tokens](/security/access-tokens/) (PATs) now support expiration dates.

## [2024-10-15](#2024-10-15)

### [New](#new-6)

* Beta: You can now create [organization access tokens](/security/for-admins/access-tokens/) (OATs) to enhance security for organizations and streamline access management for organizations in the Docker Admin Console.

## [2024-08-29](#2024-08-29)

### [New](#new-7)

* Deploying Docker Desktop via the [MSI installer](https://docs.docker.com/enterprise/enterprise-deployment/msi-install-and-configure/) is now generally available.
* Two new methods to [enforce sign-in](https://docs.docker.com/enterprise/security/enforce-sign-in/) (Windows registry key and `.plist` file) are now generally available.

## [2024-08-24](#2024-08-24)

### [New](#new-8)

* Administrators can now view [organization Insights](https://docs.docker.com/admin/insights/).

## [2024-07-17](#2024-07-17)

### [New](#new-9)

* You can now centrally access and manage Docker products in [Docker Home](https://app.docker.com).